Adding a New Controller

While the controllers that ship with behave3d are useful for many of the common cases, you will inevitably face a limitation, or behavior different than what you need. In such cases you can edit the source file of the problematic controller by adding new parameters enabling additional functionality, for example. However, when you want to create functionality which by default behaves differently than the currently-existing controller, you can create a new controller type with a file copy-pasted from the existing controller's file.

Example: You want to make an upgraded version of the standard move() controller and name the new controller cool_move().

Here are the steps to perform:

  1. Duplicate file controllerMove.js and name the copy controllerCoolMove.js.
  2. Open controllerCoolMove.js and replace all occurances of "controllerMove" with "controllerCoolMove"
  3. Then go to the last line of the file and modify the name(alias) you want the controller to be known by:
    Behave3d.registerController("cool_move", Behave3d.controllerCoolMove);
  4. Modify the lists defining the new controller's messages, events and parameters:
    Behave3d.controllerCoolMove.prototype.events,
    Behave3d.controllerCoolMove.prototype.messages and
    Behave3d.controllerCoolMove.prototype.default_params
  5. Add initializations in Behave3d.controllerCoolMove.prototype.construct().
  6. Add new-messages handling in Behave3d.controllerCoolMove.prototype.message().
  7. Add new update functionality in Behave3d.controllerCoolMove.prototype.update().
  8. You can add whatever methods to the controller's prototype.

At this point, there is no documentation on the internal methods of the behave3d library, so you must explore the existing controllers and engine source files for more insight. Here is just a quick note that will make the process of controllers creation and initialization more clear:

Each controller's construct() method is called 3 times as there are 3 stages of construction and initialization. The process is split in 3 stages, so that when initializing many controllers at once, controllers can reference other ones defined after them.

  1. Stage 1: All controllers are instantiated and their parameters set.
  2. Stage 2: All controllers add their DOM event and behave3d event listeners. Listeners to any other controllers can be added too, as all controllers have been created on Stage 1.
  3. Stage 3: All controllers send initializing messages and fire initializing events (listened-for by themselves and other controllers). These events will be correctly handled, as all controllers have set their event listeners on Stage 2.

While in most cases it's more convenient to start a new controller's file from an exisiting one, here is an empty controller template, at least for the sake of seeing more clearly the controller structure. This template is available in the library package as controller_Template_.js.

Controller Template