Script

Dynamic scripting component for runtime code execution.

Allows entities to have behavior defined through HScript code that can be modified at runtime. Scripts have access to the full Ceramic API and can define lifecycle methods (init, update, destroy).

Features:

• JavaScript/TypeScript-like syntax (arrow functions, for-of loops)
• Automatic entity lifecycle management
• Error handling and sandboxing
• Module system for inter-script communication
• Infinite loop protection

// Create a script that moves an entity
var scriptCode = '
var speed = 100;

function update(delta) {
    entity.x += speed * delta;
    if (entity.x > screen.width) {
        entity.x = 0;
    }
}
';

var entity = new Quad();
entity.size(50, 50);
entity.script = new Script(scriptCode);

Static Members #

Global error handlers called when scripts encounter errors. Add handlers here to be notified of all script errors.

Global trace handlers called when scripts use trace(). Add handlers here to intercept script trace output.

Logger instance for script-related messages

Instance Members #

The source code content of this script. Preprocessed to convert JS/TS idioms to HScript.

The parsed HScript AST (Abstract Syntax Tree).

The HScript interpreter executing this script. Provides access to variables and execution context.

Module interface for inter-script communication. Other scripts can access this script's exports through this module.

Executes the script and sets up lifecycle callbacks.

Looks for and binds these optional functions:

• init(): Called once after script execution
• update(delta): Called every frame with time delta
• destroy(): Called when script is destroyed

Gets an entity by its ID from the script's context.

Searches for entities in:

1. Parent Fragment if the script's entity is a Visual
2. Fragment variable in the script's scope

Gets a script module by entity ID.

Allows scripts to access other scripts' exported functions and variables through their module interface.

Gets a variable value from the script's scope.

Calls a function defined in the script.

Internal method to call script functions with optimized argument passing.

Creates a new script with the given source code.

The script is parsed immediately. If parsing fails, the script is marked as broken and scheduled for destruction.

Private Members #

Maximum iterations allowed in loops to prevent infinite loops

Shared HScript parser instance

Whether the script has been successfully parsed and is ready to run

Whether the script is currently executing

Whether the script has encountered a fatal error

Tracks loop iterations for infinite loop detection

Called when script is attached to an entity as a component. Sets up entity-specific variables and schedules execution.

Checks for infinite loops by tracking iteration counts. Called automatically in while loops.

Resets loop iteration counters each frame. Prevents false positives from accumulated iterations.

Metadata #