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
"main" field in the lib's
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
which gets poluted with the engine's function
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:
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
rotate() one with controller ID
Just like DOM elements, controllers need an ID only when having to be addressed by other controllers or scripts.
move() controller has:
dx: 50- move the element 50 pixels to the right,
start- as soon as the controller is initialized, send message
start on: a mouseover- a message-upon-event trigger, causing the controller to recieve message
startupon another controller with ID =
aon the same element (the default actions() controller) firing the event
start_back on: rot end- a message-upon-event trigger, causing the controller to recieve message
start_backupon the other controller
rotfiring the event
end, which it does at the end of its movement.
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_newupon the other controller
movfiring 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
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
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,
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
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,
Behave3d.Element.addController() method that is used internally by
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
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
frameevent 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: