Skip to main content

Behaviours - Lifecycle Management Functions

You can add behavior components with a THREE.js context to create custom scripts that modify your object's behavior, making your scene more dynamic and interactive. Additionally, a terminal is available to display all script outputs for debugging and testing.

Lifecycle Management Overview​

We provide a simple script template to manage an object’s lifecycle inside a scene. This includes three essential functions that govern behavior from creation to destruction:

/*
 * A directive that connects to lifecycle hooks.
 */
#pragma lifecycle(startup, update, dispose)

/*
 * Fired once when the object is instantiated in the scene.
 */
function startup() {
}

/*
 * Fired every frame to handle dynamic updates.
 */
function update(delta, time) {
}

/*
 * Fired when the object is destroyed to clean up resources.
 */
function dispose() {
}

The Directive​

The directive #pragma lifecycle(startup, update, dispose) links your custom functions to the system’s lifecycle hooks. This ensures that startup(), update(), and dispose() are executed at the correct stages of your object’s lifecycle.

Function Breakdown​

1. startup()​

  • When it runs: Called once when the object is created or added to the scene.
  • Purpose: Used for initial setup, such as setting positions, loading resources, or initializing variables.
  • Example: Defining a character’s starting position, loading textures, or setting initial values.

2. update(delta, time)​

  • When it runs: Called on every frame while the object exists.
  • Purpose: Manages continuous updates and dynamic behaviors like movement, animations, or user input.
  • Parameters:
    • delta: Time elapsed since the last frame (useful for smooth movements).
    • time: Total time since the app started (useful for time-based events).
  • Example: Moving a character, animating a bouncing ball, or triggering actions based on input.

3. dispose()​

  • When it runs: Called when the object is removed or destroyed.
  • Purpose: Cleans up and releases resources like textures or event listeners to free memory.
  • Example: Stopping sounds, clearing intervals, or unloading textures.

By implementing these functions, you ensure your objects are properly managed from creation to disposal.

Play Mode (Script Preview)​

Before publishing your scene, you can preview and test your scripts directly in the editor. This helps catch any errors and ensures your dynamic behaviors function correctly.

Click the Play icon in the toolbar to run your script inside the viewport. You’ll be able to interact with the scene and monitor any console logs or warnings.

⚠️ Important Note​

Only the startup(), update(delta, time), and dispose() functions are recognized by the lifecycle system. Any additional functions or code written outside these hooks will not be executed automatically.

For more advanced usage and API details, visit our dedicated section.