behave3d Workflow

Including of Scripts

The behave3d library is loaded and automatically started by including the engine's script file. All controllers that will be used on the page must also have their source files included after the engine. Note that the scene() and actions() controllers are used automatically by the engine and so must always be included.

The mandatory files to include are:

Loading the engine file will create window.Behave3d, which contains all the library's functionality. The engine has started the frame-updating routine but so far there are no registered behave3d elements on the page. The engine does not automatically check the DOM tree for such elements.

Loading as a module

The "main" field in the lib's package.json links to the file dist/Behave3d_ES6Wrapper.js, which is an ES6 module transpiled by Babel to a CommonJS module.

This module includes the engine, the mandatory and several of the most popular controllers:

Note that the module cannot operate without a global window object, which gets poluted with the engine's function Behave3d(). The module's default export is simply a reference to this function.

Static & Dynamic Creation of Controllers

There are two ways that controllers can be attached to HTML elements:

  • The static way, through the behave3d="..." attribute on the HTML tags:

     ...and after all elements:
  • The dynamic way, through javascript:

In both ways the syntax of the controllers-definitions strings is the same - check the Controller Documentation page for details on it. You can set not only parameters in these strings, but also triggering conditions (message-upon-event) and initial messages. For example:


Here we have two controllers defined: a move() one with controller ID mov, and a rotate() one with controller ID rot. Just like DOM elements, controllers need an ID only when having to be addressed by other controllers or scripts.

The move() controller has:

  • dx: 50 - move the element 50 pixels to the right,
  • start - as soon as the controller is initialized, send message start to it,
  • start on: a mouseover - a message-upon-event trigger, causing the controller to recieve message start upon another controller with ID = a on the same element (the default actions() controller) firing the event mouseover,
  • start_back on: rot end - a message-upon-event trigger, causing the controller to recieve message start_back upon the other controller rot firing the event end, which it does at the end of its movement.

The rotate() controller has:

  • z: 1 - rotate the element around its Z axis,
  • angle: 90 - this many degrees clockwise,
  • start_new on: mov end - a message-upon-event trigger, causing the controller to recieve message start_new upon the other controller mov firing the event end, which it does at the end of its forward movement.

Whenever initializing or setting the values of parameters that represent coordinates or lengths, for convenience, you can supply values relative to the element's, or its parent's, or the document's, or the viewport's position and size. For more information, visit page Controller # Coordinate Parameters. Just a few examples:

Notes on Static Creation

The Behave3d.updatePool() method should be called after the part of the DOM tree containing all behave3d elements on the page is ready, but this doesn't mean that the document's DOM-ready event should be waited for. Simply call the method with an inline script somewhere bellow the elements in page.

Note that this method can be called more than once. Each time the engine will scan the DOM tree and add to the behave3d pool those elements with behave3d attribute that are not already in the pool. The routine will also remove from the pool elements which were deleted from the DOM tree.

The all-at-once creation of controllers via the Behave3d.updatePool() method has an advantage against adding the controllers one by one via javascript - that controllers can reference (for message-upon-event triggering) other controllers on following elements. For example, this is fine:

But this will cause an error, because while executing the command on the first line, the engine cannot find a controller with ID = m on the #e2 element (it will be created with the next command):

Notes on Dynamic Creation

Just like the Behave3d.updatePool() method has the advantage of early-referencing among elements, the Behave3d.Element.add() method, which can add several controllers at once, can use early-referencing among controllers. For example, this is fine:

But this will cause an error, because while initializing the first controller, the second one (with ID = m) is unknown (it will be created with the next command):

In order to dynamically create controllers with early/circular references (listening for each other's events), you should first create all controllers, and then create the triggers:

When your scripts need to often send messages to a particular controller, instead of having to select it every time with Behave3d("element_id controller_id").controllerMethod(), you can take a reference to it when creating it:

In case you want (or need) to skip casting the controller's parameters to string, there's the Behave3d.Element.addController() method that is used internally by Behave3d.Element.add():

Commanding & Listening to Controllers

At any time during the functioning of a controller you can:

Removing & Cleanup

You can remove a single controller or the whole behave3d functionality from an HTML element:

You can also automate the removal of a controller or whole element when they are no longer needed: