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.

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:

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:

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:

• Disable / enable it

  A disabled controller cannot receive messages other than enable, remove (to delete the controller) and params (to modify its parameters). A disabled controller also doesn't have its .update() method called, so it doesn't apply any transforms or perform any update logics.

• Pause / un-pause it

  A paused controller has its update logics paused, and it continues to apply the same transformations (with tha same values). It also continues to receive messages.

  Note that paused controllers are automatically un-paused by messages ordering the start of a new movement/transition.

• Send messages to it

  You command the controller via sending messages to it (eventually with parameters), and via the defined message-upon-event triggers that automatically send messages to the controller upon an event.

• Set new values of its parameters

  While changing some parameters' values takes effect immediately, the values of other parameters are used by their controller only when it recalculates its internal variables upon receiving a message.

• Set new triggers

  At any moment you can add new message-on-event triggers, which actually creates listener functions containing a single statement - sending the message.

  Note that currently, as of version 0.80, functionality is still not implemented and you can't remove behave3d event listeners.

• Set event listeners

  In case you want to control a controller (like, modify a parameter) on every frame, there's the frame event that every controller fires right before calling its update method.

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: