@web-engine-dev/scripting

Runtime scripting layer for gameplay logic with lifecycle hooks. Provides a Unity MonoBehaviour-like API for creating game behaviors.

Features

• Script Lifecycle: onFirst, onStart, onUpdate, onFixedUpdate, onLateUpdate, onDestroy
• Script Registry: Type-safe registration and instantiation
• Entity Binding: Attach scripts to entities
• Error Handling: Graceful error recovery
• Events: Subscribe to script lifecycle events

Installation

npm install @web-engine-dev/scripting
# or
pnpm add @web-engine-dev/scripting

Quick Start

import {
  Script,
  ScriptContext,
  defineScript,
  ScriptManager,
  createScriptTypeId,
} from '@web-engine-dev/scripting';

// Define a script
class PlayerController implements Script {
  readonly typeId = createScriptTypeId('PlayerController');
  readonly instanceId = 0 as any;
  enabled = true;

  speed = 5;

  onStart(context: ScriptContext) {
    console.log('Player initialized');
  }

  onUpdate(context: ScriptContext) {
    const movement = this.speed * context.deltaTime;
    // Apply movement
  }

  onDestroy(context: ScriptContext) {
    console.log('Player destroyed');
  }
}

// Register the script
defineScript('PlayerController', PlayerController, {
  name: 'Player Controller',
  category: 'Character',
  tags: ['player', 'movement'],
});

// Use in game loop
const manager = new ScriptManager();
const entity = { id: 1 };

const script = manager.attach(entity, createScriptTypeId('PlayerController'));

API Reference

Script Interface

Method	Description
onFirst(ctx)	Called on the very first tick (before onStart)
onStart(ctx)	Called once when script starts
onUpdate(ctx)	Called every frame
onFixedUpdate	Called at fixed timestep
onLateUpdate	Called after all updates
onDestroy(ctx)	Called when script is destroyed

ScriptContext

Property	Description
deltaTime	Time since last update
time	Total elapsed time
entity	Attached entity

ScriptManager

Method	Description
attach(entity, type)	Attach script to entity
detach(script)	Remove script from entity
first(dt, t)	Call onFirst (very first tick only)
processStart(dt, t)	Call onStart for new scripts
update(dt, t)	Call onUpdate
fixedUpdate(dt, t)	Call onFixedUpdate
lateUpdate(dt, t)	Call onLateUpdate

Decorator Registration

import { RegisterScript } from '@web-engine-dev/scripting';

@RegisterScript({
  typeId: 'EnemyAI',
  name: 'Enemy AI',
  category: 'AI',
})
class EnemyAI implements Script {
  // ...
}

Game Loop Integration

const manager = new ScriptManager();

function gameLoop(deltaTime: number, time: number) {
  // Process newly attached scripts
  manager.processStart(deltaTime, time);

  // Main updates
  manager.update(deltaTime, time);

  // Physics updates (in fixed loop)
  manager.fixedUpdate(fixedDeltaTime, time);

  // Late updates (after physics)
  manager.lateUpdate(deltaTime, time);
}