Extending Devkit with Modules

Note on terminology: the devkit debugger refers to the window where a game is simulated and any tools contained within. The devkit simulator refers to the iframe in which a simulated game is running.

A devkit module is a set of features packaged separately from devkit that extends the functionality of games or the devkit toolchain. A module consumes the devkit api to provide this functionality. Users can install modules using the devkit install command.

Modules extending game functionality include:

• Accelerometer - provides accelerometer support for iOS, Android, and the web, normalizing all the platform APIs through the HTML5 devicemotion event.
• Effects

Modules extending devkit tools include:

• Devkit View Inspector - extends the devkit debugger with a view hierarchy inspector. Though this module ships pre-installed in devkit, it uses the same external module APIs.
• Devkit Simulator Client - extends the devkit simulator client, providing the implementation for simulator buttons like screenshot, home, back, pause, and step. This module also ships pre-installed with devkit and is by default available in all games running inside the simulator.

Extending Devkit

1. Create a folder for your module with a package.json file (compatible with npm).

2. Add a devkit key to package.json with an object called extensions.

   The keys in the extension objects are all optional, but can include:

   • debugger: extends the front-end debugger, running code that will execute in either node (server-side) or on the client (in the debugger, the window around the simulator)
   • devkit-simulator: provides additional code that executes inside the simulator (in the same context as a game)

   The values for the keys are relative paths to node imports. Devkit will execute these directly with require(...).

   Example:

      "devkit": {
        "extensions": {
          "debugger": "debugger",
          "devkit-simulator": "simulator"
        }
      }
   

debugger extension

The debugger extension should implement a getMiddleware function that returns middleware for the debugger (the outer window of the simulator) and, optionally, middleware for the simulator (the client iframe).

• debugger middleware is mounted at /api/modules/[app-key]/[module-name]/. When the debugger loads, an iframe will be created for each module that registers simulator middleware.
• simulator middleware is mounted at /apps/[app-key]/modules/[module-name]/.

Example for hosting static content to the simulator:

exports.getMiddleware = function (api, app) {
  return {
    'debugger': express.static(path.join(__dirname, 'static'))
  };
};

simulator extension

When the simulator loads, all modules that defined a simulator extension will be available in a list at CONFIG.simulator.modules and can also be imported directly by name (e.g. import [module-name]).

The default load time process, defined by launchClient.js, for the simulator only, is:

• each simulator module is loaded in a try-catch
• if the module provides an onLaunch function, it will be executed
• if the onLaunch function returns a Promise, load of the game will be blocked on the Promise for up to 5 seconds. Load of the client will continue regardless of whether the Promise rejects or resolves.