Behaviours - Lifecycle Management Functions

You can add behavior components with THREE.js context to create custom code that alters your object's behaviors, making your scene more dynamic. Additionally, a terminal is available to redirect and display all script outputs.

We offer a simple script designed to manage the lifecycle of an object in a scene. It includes three main lifecycle functions that help manage the object's behavior from creation to destruction.

    /*
    * A directive that allows connection to lifecycle hooks.
    */
    #pragma lifecycle(startup,update,dispose)
    /*
    *  Fired only once when the object is instantiated in the scene, enabling initial setup.
    */
    function startup() {
    }
    /*
    *  Fired on every frame, allowing for continuous updates and dynamic behavior.
    */
    function update(delta,time) {
    }
    /*
    *  Fired on object destruction, enabling disposal of resources and proper finalization.
    */
    function dispose() {
    }

The Directive

The #pragma lifecycle(startup,update,dispose) line at the top is a directive that connects these functions to the object's lifecycle hooks. This means it tells the system to call the startup(), update(), and dispose() functions at the appropriate times in the object's lifecycle.

Definitions of the Functions

1. startup()

   • What it does: This function is called only once when the object is first created or added to the scene.

   • Purpose: It is used for initial setup. Think of it as preparing the object, such as setting initial values, loading resources, or establishing starting conditions.

   • Example: Setting the initial position of a character, loading textures, or initializing variables.

2. update(delta, time)

   • What it does: This function is called on every frame, which means it runs repeatedly as long as the object exists in the scene.

   • Purpose: It allows for continuous updates and dynamic behavior. This is where you can make the object move, check for user input, or update animations.

   • Parameters:

     • delta: The time elapsed since the last frame. It helps in creating smooth and consistent movement or updates.

     • time: The total time elapsed since the application started. It can be used for time-based events.

   • Example: Moving a character based on user input, updating the position of a bouncing ball, or playing animations.

3. dispose()

   • What it does: This function is called when the object is destroyed or removed from the scene.

   • Purpose: It is used for cleanup and releasing resources. This ensures that memory is freed up and any resources that were used by the object are properly disposed of.

   • Example: Stopping sounds, freeing up memory used by textures, or removing event listeners.

By using these functions, you can manage how an object behaves from the moment it's created, through its updates, until it's no longer needed and gets cleaned up.

Play Mode

You have the option to run a preview of the scripts before viewing the results in the metaverse. This ensures there are no errors and that the code runs as expected.

Simply click the ‘Play’ icon in the toolbar to run the script in the viewport. You will be able to see any dynamic behavior added to the scene and handle any errors or warnings.

Warning

These behaviors only work with the given startup(), update(delta, time), and dispose() functions. Any new functions or code outside the specified ones will not be automatically recognized or executed by the lifecycle management system.