Every HTML element in the DOM tree that has behave3d functionality has an object of type Behave3d.Element attached as a property. The name of the property is defined by Behave3d.consts.BEHAVE3D_PROPERTY and by default is "behave3d".

The object contains:

The engine keeps a list of references to all elements on the page that contain a Behave3d.Element - this is the so-called elements pool. All elements in the pool have their controllers updated and transforms applied on each drawing frame.

Note that not only elements that have controllers assigned need to have Behave3d.Element instantiated. All elements that will be applied 3D transforms and physics need it. Some controllers, like box() and carousel(), apply transforms not on the element they are assigned to, but on its child nodes. These controllers instantiate Behave3d.Element on their children automatically.

Another, not very obvious case when an element needs to have Behave3d.Element instantiated is when a controller on another element wants to listen to this element's events, i.e. to listen to this element's actions() controller's events.

Instantiating Behave3d.Element

Removing Behave3d.Element

If the page contains many elements with behave3d functionality that will not be used any more, this functionality can be removed, freeing memory and saving the few clock cycles spent in updating the idle controllers.

Removal is done via the .removeFromPool() method, which removes all controllers from the element, and then removes the element from the pool and as property of the HTML element.

In case you want to remove not only the Behave3d.Element but also the HTML element (from the DOM tree), there's the remove_element message of the actions() controller, which, as a message, allows the removal of the element to be scheduled to happen upon a controller's event:

Note that when an HTML element is deleted from the DOM tree by external scripts, the engine doesn't "see" this (it's expensive to check) and continues to update its Behave3d.Element. Either call manually the .removeFromPool() method for each deleted HTML element, or call Behave3d.updatePool(), which will check all elements in the pool to see if the document.contains() them and will remove from the pool all deleted HTML elements.