@zylem/game-lib 0.6.4 → 0.7.0

package/dist/{entity-vj-HTjzU.d.ts → entity-DNkYKfdp.d.ts}

@@ -1,147 +1,9 @@
-import { Vector3, Vector2, Color, Material, BufferGeometry, Mesh, Group, ShaderMaterial } from 'three';
-import { Vector3 as Vector3$1, RigidBodyDesc, ColliderDesc, RigidBody, Vector, Collider } from '@dimforge/rapier3d-compat';
-import { IComponent } from 'bitecs';
-import * as mitt from 'mitt';
-import { c as BehaviorDescriptor, d as BehaviorHandle, e as BehaviorRef } from './behavior-descriptor-BXnVR8Ki.js';
-
-/** Input
- *
- * Maximum number of local players is 8.
- * All input can be mapped to a gamepad or keyboard but shares the common
- * interface represented as a gamepad.
- */
-type InputPlayerNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
-type InputPlayer = `p${InputPlayerNumber}`;
-interface ButtonState {
-    pressed: boolean;
-    released: boolean;
-    held: number;
-}
-interface AnalogState {
-    value: number;
-    held: number;
-}
-interface InputGamepad {
-    playerNumber: InputPlayerNumber;
-    buttons: {
-        A: ButtonState;
-        B: ButtonState;
-        X: ButtonState;
-        Y: ButtonState;
-        Start: ButtonState;
-        Select: ButtonState;
-        L: ButtonState;
-        R: ButtonState;
-    };
-    directions: {
-        Up: ButtonState;
-        Down: ButtonState;
-        Left: ButtonState;
-        Right: ButtonState;
-    };
-    shoulders: {
-        LTrigger: ButtonState;
-        RTrigger: ButtonState;
-    };
-    axes: {
-        Horizontal: AnalogState;
-        Vertical: AnalogState;
-        SecondaryHorizontal: AnalogState;
-        SecondaryVertical: AnalogState;
-    };
-    /** Screen-space cursor position (normalized 0..1). Only populated by MouseProvider. */
-    pointer?: {
-        x: number;
-        y: number;
-    };
-}
-type Inputs = Record<InputPlayer, InputGamepad>;
-interface InputProvider {
-    getInput(delta: number): Partial<InputGamepad>;
-    isConnected(): boolean;
-    getName(): string;
-    dispose?(): void;
-}
-
-type LoadingEvent = {
-    type: 'start' | 'progress' | 'complete';
-    message?: string;
-    progress?: number;
-    total?: number;
-    current?: number;
-};
-interface IGame<TGlobals extends Record<string, unknown> = any> {
-    start: () => Promise<this>;
-    nextStage: () => void;
-    previousStage: () => void;
-    reset: () => Promise<void>;
-    pause: () => Promise<void>;
-    resume: () => Promise<void>;
-    onLoading: (callback: (event: LoadingEvent) => void) => void;
-    loadStageFromId: (stageId: string) => Promise<void>;
-    end: () => Promise<void>;
-    goToStage: () => void;
-}
-interface IStage {
-    onUpdate: (callback: UpdateFunction<IStage>) => void;
-    onSetup: (callback: SetupFunction<IStage>) => void;
-    onDestroy: (callback: DestroyFunction<IStage>) => void;
-}
-interface ICamera {
-    move: (position: Vector3) => void;
-    rotate: (pitch: number, yaw: number, roll: number) => void;
-}
-
-type GlobalRecord = Record<string, unknown>;
-/** Setup */
-interface SetupContext<T, TGlobals extends GlobalRecord = any> {
-    me: T;
-    globals: TGlobals;
-    inputs?: Inputs;
-    camera?: ICamera;
-    stage?: IStage;
-    game?: IGame<TGlobals>;
-}
-interface SetupFunction<T, TGlobals extends GlobalRecord = any> {
-    (context: SetupContext<T, TGlobals>): void;
-}
-/** Loaded */
-interface LoadedContext<T, TGlobals extends GlobalRecord = any> {
-    me: T;
-    globals: TGlobals;
-}
-interface LoadedFunction<T, TGlobals extends GlobalRecord = any> {
-    (context: LoadedContext<T, TGlobals>): void;
-}
-/** Update */
-type UpdateContext<T, TGlobals extends GlobalRecord = any> = {
-    me: T;
-    delta: number;
-    inputs: Inputs;
-    globals: TGlobals;
-    camera: ICamera;
-    stage?: IStage;
-    game?: IGame<TGlobals>;
-};
-interface UpdateFunction<T, TGlobals extends GlobalRecord = any> {
-    (context: UpdateContext<T, TGlobals>): void;
-}
-/** Destroy */
-interface DestroyContext<T, TGlobals extends GlobalRecord = any> {
-    me: T;
-    globals: TGlobals;
-}
-interface DestroyFunction<T, TGlobals extends GlobalRecord = any> {
-    (context: DestroyContext<T, TGlobals>): void;
-}
-/** Cleanup */
-interface CleanupContext<T, TGlobals extends GlobalRecord = any> {
-    me: T;
-    globals: TGlobals;
-}
-interface CleanupFunction<T, TGlobals extends GlobalRecord = any> {
-    (context: CleanupContext<T, TGlobals>): void;
-}
+import { BufferGeometry, Material, Mesh, Group, Vector3, Color, ShaderMaterial } from 'three';
+import { RigidBodyDesc, ColliderDesc, RigidBody, Collider, Vector } from '@dimforge/rapier3d-compat';
+import { a as Vec3Input, c as Vec3, s as MaterialBuilder, M as MaterialOptions, b as Vec2Input } from './material-Wz83vTTp.js';
+import { S as SetupContext, f as UpdateContext, D as DestroyContext, h as SetupFunction, i as LoadedFunction, U as UpdateFunction, j as DestroyFunction, k as CleanupFunction, L as LoadedContext, C as CleanupContext } from './base-node-life-cycle-CnJ-7zX-.js';
+import { EventEmitterDelegate, EntityEvents } from './events.js';
+import { TransformState, MoveableEntity, BehaviorDescriptor, BehaviorHandle, BehaviorRef } from '@zylem/behaviors/core';
 
 interface NodeInterface {
     uuid: string;
@@ -170,7 +32,6 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     protected parent: NodeInterface | null;
     protected children: NodeInterface[];
     options: Options;
-    eid: number;
     uuid: string;
     name: string;
     markedForRemoval: boolean;
@@ -237,95 +98,374 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     private recordLifecycleRegistration;
 }
 
-type Vec3 = Vector3 | Vector3$1;
-
-declare function shortHash(objString: string): string;
-
-/**
- * GLSL shader object (traditional approach for WebGL)
- */
-type ZylemShaderObject = {
-    fragment: string;
-    vertex: string;
-};
 /**
- * TSL shader type (for WebGPU)
- * colorNode should be a TSL node that returns the fragment color
+ * `WasmStageRuntime` — owns one wasm `WebAssembly.Instance` of `@zylem/runtime`
+ * and exposes the unified-Stage FFI as a set of typed TypeScript methods.
+ * Replaces the legacy {@link ZylemRuntimeStageAdapter} + {@link ZylemWorld}
+ * pair; every `ZylemStage` instantiates exactly one `WasmStageRuntime`.
+ *
+ * The runtime is the single source of truth for per-frame physics state.
+ * TS-side behaviors and visual layers (destructible-3d, particle-emitter,
+ * screen-visibility) read transforms from the render buffer; sim-only
+ * behaviors push their attach/query payload through the per-behavior
+ * helpers exposed here.
  */
-type ZylemTSLShader = {
-    colorNode: any;
-    transparent?: boolean;
+/** Sentinel handle for "no entity / failed allocation". Mirrors `INVALID_SLOT` in Rust. */
+declare const STAGE_INVALID_SLOT = 4294967295;
+/** Fixed render-buffer stride in floats. Must match `STAGE_RENDER_STRIDE` in Rust. */
+declare const STAGE_RENDER_STRIDE = 12;
+/** Fixed event-buffer stride in floats. Must match `STAGE_EVENT_STRIDE` in Rust. */
+declare const STAGE_EVENT_STRIDE = 6;
+/** Fixed pose-scratch stride in floats. Must match `POSE_SCRATCH_LEN` in Rust. */
+declare const STAGE_POSE_LEN = 7;
+declare const enum StageBodyKind {
+    Dynamic = 0,
+    Static = 1,
+    KinematicPosition = 2,
+    KinematicVelocity = 3
+}
+declare const enum StageBoundaryDim {
+    Two = 2,
+    Three = 3
+}
+declare const enum StageRicochetDim {
+    Two = 2,
+    Three = 3
+}
+declare const enum StageRicochetReflection {
+    Mirror = 0,
+    Angled = 1
+}
+declare const enum StageTopDownPlane {
+    Xy = 0,
+    Xz = 1
+}
+declare const enum StageEventType {
+    CollisionStarted = 1,
+    CollisionStopped = 2,
+    BoundaryHit = 3,
+    Ricochet = 4,
+    RegionEntered = 5,
+    JumpStarted = 6,
+    Landed = 7,
+    Wrapped = 8,
+    CooldownFired = 9
+}
+interface StageEvent {
+    type: StageEventType;
+    primarySlot: number | null;
+    secondarySlot: number | null;
+    payload: [number, number, number];
+}
+interface StagePose {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+}
+interface StageBodyConfig {
+    kind: StageBodyKind;
+    position: readonly [number, number, number];
+    rotation: readonly [number, number, number, number];
+    linearDamping: number;
+    angularDamping: number;
+    gravityScale: number;
+    canSleep: boolean;
+    ccdEnabled: boolean;
+    lockRotation: readonly [boolean, boolean, boolean];
+    lockTranslation: readonly [boolean, boolean, boolean];
+}
+type StageColliderShape = {
+    type: 'box';
+    halfExtents: readonly [number, number, number];
+} | {
+    type: 'sphere';
+    radius: number;
+} | {
+    type: 'capsule';
+    halfHeight: number;
+    radius: number;
+} | {
+    type: 'cylinder';
+    halfHeight: number;
+    radius: number;
+} | {
+    type: 'convexHull';
+    vertices: Float32Array;
+} | {
+    type: 'trimesh';
+    vertices: Float32Array;
+    indices: Uint32Array;
+} | {
+    type: 'heightfield';
+    rows: number;
+    cols: number;
+    scale: readonly [number, number, number];
+    heights: Float32Array;
 };
-/**
- * Combined shader type supporting both GLSL and TSL
- */
-type ZylemShader = ZylemShaderObject | ZylemTSLShader;
-/**
- * Check if a shader is a TSL shader
- */
-declare function isTSLShader(shader: ZylemShader): shader is ZylemTSLShader;
-/**
- * Check if a shader is a GLSL shader
- */
-declare function isGLSLShader(shader: ZylemShader): shader is ZylemShaderObject;
-interface MaterialOptions {
-    path?: string;
-    normalMap?: string;
-    repeat?: Vector2;
-    shader?: ZylemShader;
-    color?: Color;
-    /** Opacity from 0 (fully transparent) to 1 (fully opaque). */
-    opacity?: number;
-    /**
-     * When true, prefer TSL/NodeMaterial (for WebGPU)
-     * When false, prefer GLSL/ShaderMaterial (for WebGL)
-     */
-    useTSL?: boolean;
+interface StageColliderConfig {
+    shape: StageColliderShape;
+    offset: readonly [number, number, number];
+    friction: number;
+    restitution: number;
+    sensor: boolean;
+    /** Packed Rapier interaction-groups: high 16 bits = membership, low 16 bits = filter. */
+    collisionGroups: number;
 }
-type BatchGeometryMap = Map<symbol, number>;
-interface BatchMaterialMapObject {
-    geometryMap: BatchGeometryMap;
-    material: Material;
+/** Minimal exports surface used by `WasmStageRuntime`. Mirrors `stage_ffi.rs`. */
+interface StageWasmExports {
+    readonly memory: WebAssembly.Memory;
+    zylem_stage_create(initialCapacity: number): number;
+    zylem_stage_destroy(): void;
+    zylem_stage_set_gravity(x: number, y: number, z: number): void;
+    zylem_stage_step(dt: number): number;
+    zylem_stage_active_count(): number;
+    zylem_stage_capacity(): number;
+    zylem_stage_tick_count(): number;
+    zylem_stage_create_entity(): number;
+    zylem_stage_destroy_entity(slot: number): number;
+    zylem_stage_attach_body(slot: number, kind: number, px: number, py: number, pz: number, rx: number, ry: number, rz: number, rw: number, linearDamping: number, angularDamping: number, gravityScale: number, canSleep: number, ccdEnabled: number, lockRotX: number, lockRotY: number, lockRotZ: number, lockTransX: number, lockTransY: number, lockTransZ: number): number;
+    zylem_stage_add_collider_box(slot: number, hx: number, hy: number, hz: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_sphere(slot: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_capsule(slot: number, halfHeight: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_cylinder(slot: number, halfHeight: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_convex_hull(slot: number, vertexOffset: number, vertexCount: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_trimesh(slot: number, vertexOffset: number, vertexCount: number, indexOffset: number, indexCount: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
+    zylem_stage_add_collider_heightfield(slot: number, rows: number, cols: number, sx: number, sy: number, sz: number, heightOffset: number, px: number, py: number, pz: number, friction: number, restitution: number, collisionGroups: number): number;
+    zylem_stage_get_pose(slot: number): number;
+    zylem_stage_pose_ptr(): number;
+    zylem_stage_pose_len(): number;
+    zylem_stage_set_position(slot: number, x: number, y: number, z: number): number;
+    zylem_stage_set_rotation(slot: number, x: number, y: number, z: number, w: number): number;
+    zylem_stage_set_linvel(slot: number, x: number, y: number, z: number): number;
+    zylem_stage_get_linvel(slot: number): number;
+    zylem_stage_set_angvel(slot: number, x: number, y: number, z: number): number;
+    zylem_stage_apply_impulse(slot: number, x: number, y: number, z: number): number;
+    zylem_stage_vec3_ptr(): number;
+    zylem_stage_render_ptr(): number;
+    zylem_stage_render_len(): number;
+    zylem_stage_render_stride(): number;
+    zylem_stage_event_ptr(): number;
+    zylem_stage_event_len(): number;
+    zylem_stage_event_count(): number;
+    zylem_stage_event_stride(): number;
+    zylem_stage_query_ptr(): number;
+    zylem_stage_query_len(): number;
+    zylem_stage_scratch_ptr(): number;
+    zylem_stage_scratch_capacity(): number;
+    zylem_stage_attach_cooldown(slot: number): number;
+    zylem_stage_cooldown_register(slot: number, id: number, duration: number, immediate: number): number;
+    zylem_stage_cooldown_fire(slot: number, id: number): number;
+    zylem_stage_cooldown_reset(slot: number, id: number): number;
+    zylem_stage_cooldown_remaining(slot: number, id: number): number;
+    zylem_stage_attach_world_boundary(slot: number, dim: number, top: number, bottom: number, left: number, right: number, front: number, back: number, padding: number): number;
+    zylem_stage_query_world_boundary(slot: number): number;
+    zylem_stage_attach_screen_wrap(slot: number, width: number, height: number, centerX: number, centerY: number, edgeThreshold: number): number;
+    zylem_stage_query_screen_wrap(slot: number): number;
+    zylem_stage_attach_ricochet(slot: number, dim: number, minSpeed: number, maxSpeed: number, speedMultiplier: number, maxAngleDeg: number, reflectionMode: number): number;
+    zylem_stage_query_ricochet(slot: number): number;
+    zylem_stage_attach_thruster(slot: number, maxSpeed: number, acceleration: number, turnRateRadS: number, linearDamping: number): number;
+    zylem_stage_set_thruster_input(slot: number, thrust: number, turn: number): void;
+    zylem_stage_query_thruster(slot: number): number;
+    zylem_stage_attach_top_down(slot: number, plane: number, speed: number, faceMovement: number): number;
+    zylem_stage_set_top_down_input(slot: number, a: number, b: number): void;
+    zylem_stage_attach_jumper_2d(slot: number, jumpForce: number, maxJumps: number, jumpBufferTime: number, coyoteTime: number, gravity: number): number;
+    zylem_stage_set_jumper_2d_input(slot: number, jumpPressed: number): void;
+    zylem_stage_query_jumper_2d(slot: number): number;
+    zylem_stage_attach_jumper_3d(slot: number, jumpForce: number, maxJumps: number, gravity: number): number;
+    zylem_stage_set_jumper_3d_input(slot: number, jump: number): void;
+    zylem_stage_query_jumper_3d(slot: number): number;
+    zylem_stage_attach_shooter_2d(slot: number, fireRateHz: number, muzzleOffsetX: number, muzzleOffsetY: number, muzzleSpeed: number): number;
+    zylem_stage_shooter_2d_fire(slot: number, x: number, y: number, z: number, yaw: number): number;
+    zylem_stage_query_shooter_2d(slot: number): number;
+    zylem_stage_attach_platformer_3d(slot: number, halfHeight: number, radius: number, walkSpeed: number, runSpeed: number, jumpForce: number, maxJumps: number, gravity: number): number;
+    zylem_stage_set_platformer_3d_input_axes(slot: number, moveX: number, moveZ: number): void;
+    zylem_stage_set_platformer_3d_input_buttons(slot: number, jump: number, run: number): void;
+    zylem_stage_query_platformer_3d(slot: number): number;
+    zylem_stage_attach_first_person(slot: number, walkSpeed: number, runSpeed: number, eyeHeight: number, lookSensitivity: number): number;
+    zylem_stage_set_first_person_input(slot: number, moveX: number, moveZ: number, lookYaw: number, lookPitch: number, run: number): void;
+    zylem_stage_query_first_person(slot: number): number;
+    zylem_stage_invalid_slot(): number;
 }
-type BatchKey = ReturnType<typeof shortHash>;
-type TexturePath = string | null;
-declare class MaterialBuilder {
-    static batchMaterialMap: Map<BatchKey, BatchMaterialMapObject>;
-    /**
-     * Clear the static batch material cache.
-     * Should be called during game disposal to prevent stale material references
-     * from persisting across demo/stage switches.
-     */
-    static clearBatchCache(): void;
-    materials: Material[];
-    /** Whether to use TSL/NodeMaterial (for WebGPU compatibility) */
-    private useTSL;
-    constructor(useTSL?: boolean);
-    batchMaterial(options: Partial<MaterialOptions>, entityType: symbol): void;
-    build(options: Partial<MaterialOptions>, entityType: symbol): void;
-    withColor(color: Color, useTSL?: boolean, opacity?: number): this;
-    withShader(shader: ZylemShaderObject, opacity?: number): this;
-    withTSLShader(shader: ZylemTSLShader, opacity?: number): this;
-    private applyOpacity;
-    /**
-     * Set texture - loads in background (deferred).
-     * Material is created immediately with null map, texture applies when loaded.
-     */
-    setTexture(texturePath?: TexturePath, repeat?: Vector2, useTSL?: boolean, opacity?: number): void;
-    /**
-     * Set normal map for the current material
-     */
-    setNormalMap(normalMapPath: string, repeat?: Vector2): void;
-    setColor(color: Color, useTSL?: boolean, opacity?: number): void;
-    /**
-     * Set GLSL shader (WebGL only)
-     */
-    setShader(customShader: ZylemShaderObject, opacity?: number): void;
-    /**
-     * Set TSL shader (WebGPU compatible)
-     */
-    setTSLShader(tslShader: ZylemTSLShader, opacity?: number): void;
+/** Default options for `createWasmStageRuntime`. */
+interface WasmStageRuntimeOptions {
+    initialCapacity?: number;
+    gravity?: readonly [number, number, number];
+    imports?: WebAssembly.Imports;
 }
+/**
+ * Owns the wasm instance plus the live float-views over its render / event /
+ * pose / scratch buffers. The instance is per-`ZylemStage`; each stage gets
+ * its own `WebAssembly.Instance` so the singleton inside `stage_ffi.rs`
+ * stays single-stage scoped (today's `thread_local!` contract).
+ */
+declare class WasmStageRuntime {
+    readonly exports: StageWasmExports;
+    private readonly memory;
+    private renderView;
+    private eventView;
+    private poseView;
+    private vec3View;
+    private queryView;
+    private scratchView;
+    constructor(exports: StageWasmExports, options?: WasmStageRuntimeOptions);
+    /** Recreate typed views over wasm memory. Call after step() or whenever memory may have grown. */
+    refreshViews(): void;
+    /** Step the simulation by `dt` seconds. Refreshes views afterwards. */
+    step(dt: number): number;
+    dispose(): void;
+    get tickCount(): number;
+    get activeCount(): number;
+    setGravity(x: number, y: number, z: number): void;
+    createEntity(): number;
+    destroyEntity(slot: number): boolean;
+    attachBody(slot: number, config: StageBodyConfig): boolean;
+    addCollider(slot: number, config: StageColliderConfig): boolean;
+    private stageScratch;
+    private stageScratchIndices;
+    getPose(slot: number, out?: StagePose): StagePose | null;
+    setPosition(slot: number, x: number, y: number, z: number): boolean;
+    setRotation(slot: number, x: number, y: number, z: number, w: number): boolean;
+    setLinearVelocity(slot: number, x: number, y: number, z: number): boolean;
+    getLinearVelocity(slot: number, out?: [number, number, number]): [number, number, number] | null;
+    setAngularVelocity(slot: number, x: number, y: number, z: number): boolean;
+    applyImpulse(slot: number, x: number, y: number, z: number): boolean;
+    /** Read-only view over the render buffer; one slot occupies {@link STAGE_RENDER_STRIDE} floats. */
+    get render(): Float32Array;
+    get renderStride(): number;
+    /** Drain the wasm event buffer into a fresh array of typed events. */
+    drainEvents(): StageEvent[];
+    get queryScratch(): Float32Array;
+    attachCooldown(slot: number): boolean;
+    registerCooldown(slot: number, id: number, durationSeconds: number, immediate?: boolean): boolean;
+    fireCooldown(slot: number, id: number): boolean;
+    resetCooldown(slot: number, id: number): boolean;
+    cooldownRemaining(slot: number, id: number): number;
+    attachWorldBoundary(slot: number, dim: StageBoundaryDim, bounds: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+        front: number;
+        back: number;
+        padding?: number;
+    }): boolean;
+    queryWorldBoundary(slot: number): {
+        hits: number;
+        clamped: [number, number, number];
+    } | null;
+    attachScreenWrap(slot: number, opts: {
+        width: number;
+        height: number;
+        centerX?: number;
+        centerY?: number;
+        edgeThreshold?: number;
+    }): boolean;
+    queryScreenWrap(slot: number): {
+        fsm: number;
+        lastWrappedAxes: number;
+    } | null;
+    attachRicochet(slot: number, dim: StageRicochetDim, opts: {
+        minSpeed: number;
+        maxSpeed: number;
+        speedMultiplier: number;
+        maxAngleDeg: number;
+        reflectionMode: StageRicochetReflection;
+    }): boolean;
+    queryRicochet(slot: number): {
+        bounces: number;
+        lastKind: number;
+    } | null;
+    attachThruster(slot: number, opts: {
+        maxSpeed: number;
+        acceleration: number;
+        turnRateRadPerSec: number;
+        linearDamping: number;
+    }): boolean;
+    setThrusterInput(slot: number, thrust: number, turn: number): void;
+    queryThruster(slot: number): {
+        headingRad: number;
+        speed: number;
+    } | null;
+    attachTopDown(slot: number, opts: {
+        plane: StageTopDownPlane;
+        speed: number;
+        faceMovement?: boolean;
+    }): boolean;
+    setTopDownInput(slot: number, axisA: number, axisB: number): void;
+    attachJumper2D(slot: number, opts: {
+        jumpForce: number;
+        maxJumps: number;
+        jumpBufferTime: number;
+        coyoteTime: number;
+        gravity: number;
+    }): boolean;
+    setJumper2DInput(slot: number, jumpPressed: boolean): void;
+    queryJumper2D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        coyote: number;
+        jumpBuffer: number;
+    } | null;
+    attachJumper3D(slot: number, opts: {
+        jumpForce: number;
+        maxJumps: number;
+        gravity: number;
+    }): boolean;
+    setJumper3DInput(slot: number, jump: boolean): void;
+    queryJumper3D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        verticalVelocity: number;
+    } | null;
+    attachShooter2D(slot: number, opts: {
+        fireRateHz: number;
+        muzzleOffsetX: number;
+        muzzleOffsetY: number;
+        muzzleSpeed: number;
+    }): boolean;
+    fireShooter2D(slot: number, x: number, y: number, z: number, yaw: number): boolean;
+    queryShooter2D(slot: number): {
+        cooldown: number;
+        firedCount: number;
+    } | null;
+    attachPlatformer3D(slot: number, opts: {
+        halfHeight: number;
+        radius: number;
+        walkSpeed: number;
+        runSpeed: number;
+        jumpForce: number;
+        maxJumps: number;
+        gravity: number;
+    }): boolean;
+    setPlatformer3DInputAxes(slot: number, moveX: number, moveZ: number): void;
+    setPlatformer3DInputButtons(slot: number, jump: boolean, run: boolean): void;
+    queryPlatformer3D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        fsmState: number;
+        speed: number;
+    } | null;
+    attachFirstPerson(slot: number, opts: {
+        walkSpeed: number;
+        runSpeed: number;
+        eyeHeight: number;
+        lookSensitivity: number;
+    }): boolean;
+    setFirstPersonInput(slot: number, opts: {
+        moveX: number;
+        moveZ: number;
+        lookYawDelta: number;
+        lookPitchDelta: number;
+        run: boolean;
+    }): void;
+    queryFirstPerson(slot: number): {
+        yaw: number;
+        pitch: number;
+        speed: number;
+        eyeHeight: number;
+    } | null;
+}
+/** Loads + instantiates a wasm module and constructs a `WasmStageRuntime`. */
+declare function createWasmStageRuntime(source: RequestInfo | URL | ArrayBuffer, options?: WasmStageRuntimeOptions): Promise<WasmStageRuntime>;
 
 /**
  * Options for configuring entity collision behavior.
@@ -333,8 +473,8 @@ declare class MaterialBuilder {
 interface CollisionOptions {
     static?: boolean;
     sensor?: boolean;
-    size?: Vector3$1;
-    position?: Vector3$1;
+    size?: Vec3Input;
+    position?: Vec3Input;
     collisionType?: string;
     collisionFilter?: string[];
 }
@@ -374,343 +514,18 @@ declare abstract class EntityMeshBuilder extends MeshBuilder {
     build(options: GameEntityOptions): BufferGeometry;
     postBuild(): void;
 }
-
-interface Behavior {
-    component: IComponent;
-    values: any;
-}
-
-/**
- * Reusable delegate for event emission and subscription.
- * Use via composition in Game, Stage, and Entity classes.
- *
- * @example
- * class Game {
- *   private eventDelegate = new EventEmitterDelegate<GameEvents>();
- *
- *   dispatch<K extends keyof GameEvents>(event: K, payload: GameEvents[K]) {
- *     this.eventDelegate.dispatch(event, payload);
- *   }
- * }
- */
-declare class EventEmitterDelegate<TEvents extends Record<string, unknown>> {
-    private emitter;
-    private unsubscribes;
-    constructor();
-    /**
-     * Dispatch an event to all listeners.
-     */
-    dispatch<K extends keyof TEvents>(event: K, payload: TEvents[K]): void;
-    /**
-     * Subscribe to an event. Returns an unsubscribe function.
-     */
-    listen<K extends keyof TEvents>(event: K, handler: (payload: TEvents[K]) => void): () => void;
-    /**
-     * Subscribe to all events.
-     */
-    listenAll(handler: (type: keyof TEvents, payload: TEvents[keyof TEvents]) => void): () => void;
-    /**
-     * Clean up all subscriptions.
-     */
-    dispose(): void;
-}
-
-/**
- * Payload for game loading events with stage context.
- */
-interface GameLoadingPayload extends LoadingEvent {
-    stageName?: string;
-    stageIndex?: number;
-}
-/** Payload for stage configuration sent to editor. */
-interface StageConfigPayload {
-    id: string;
-    backgroundColor: string;
-    backgroundImage: string | null;
-    gravity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    inputs: Record<string, string[]>;
-    variables: Record<string, unknown>;
-}
-/** Payload for entity configuration sent to editor. */
-interface EntityConfigPayload {
-    uuid: string;
-    name: string;
-    type: string;
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    scale: {
-        x: number;
-        y: number;
-        z: number;
-    };
-}
-/** Payload for state dispatch events from game to editor. */
-interface StateDispatchPayload {
-    scope: 'game' | 'stage' | 'entity';
-    path: string;
-    value: unknown;
-    previousValue?: unknown;
-    config?: {
-        id: string;
-        aspectRatio: number;
-        fullscreen: boolean;
-        bodyBackground: string | undefined;
-        internalResolution: {
-            width: number;
-            height: number;
-        } | undefined;
-        debug: boolean;
-    } | null;
-    stageConfig?: StageConfigPayload | null;
-    entities?: EntityConfigPayload[] | null;
-}
-type GameEvents = {
-    'loading:start': GameLoadingPayload;
-    'loading:progress': GameLoadingPayload;
-    'loading:complete': GameLoadingPayload;
-    'paused': {
-        paused: boolean;
-    };
-    'debug': {
-        enabled: boolean;
-    };
-    'state:dispatch': StateDispatchPayload;
-};
-type StageEvents = {
-    'stage:loaded': {
-        stageId: string;
-    };
-    'stage:unloaded': {
-        stageId: string;
-    };
-    'stage:variable:changed': {
-        key: string;
-        value: unknown;
-    };
-};
-type EntityEvents = {
-    'entity:spawned': {
-        entityId: string;
-        name: string;
-    };
-    'entity:destroyed': {
-        entityId: string;
-    };
-    'entity:collision': {
-        entityId: string;
-        otherId: string;
-    };
-    'entity:model:loading': {
-        entityId: string;
-        files: string[];
-    };
-    'entity:model:loaded': {
-        entityId: string;
-        success: boolean;
-        meshCount?: number;
-    };
-    'entity:animation:loaded': {
-        entityId: string;
-        animationCount: number;
-    };
-};
-type ZylemEvents = GameEvents & StageEvents & EntityEvents;
-/**
- * Global event bus for cross-package communication.
- *
- * Usage:
- * ```ts
- * import { zylemEventBus } from '@zylem/game-lib';
- *
- * // Subscribe
- * const unsub = zylemEventBus.on('loading:progress', (e) => console.log(e));
- *
- * // Emit
- * zylemEventBus.emit('loading:progress', { type: 'progress', progress: 0.5 });
- *
- * // Cleanup
- * unsub();
- * ```
- */
-declare const zylemEventBus: mitt.Emitter<ZylemEvents>;
-
-type VelocityIntentMode = 'replace' | 'add';
-interface VelocityIntent {
-    x?: number;
-    y?: number;
-    z?: number;
-    mode: VelocityIntentMode;
-    priority?: number;
-}
-/**
- * Transform state managed by Valtio for batched physics updates.
- *
- * This store accumulates transformation intents during the frame,
- * then applies them all at once after onUpdate() callbacks complete.
- *
- * Design decisions:
- * - Position: Accumulated deltas (additive)
- * - Rotation: Last value wins (replacement)
- * - Velocity: Accumulated deltas (additive)
- * - Angular velocity: Accumulated deltas (additive)
- */
-interface TransformState {
-    /** Position deltas to be applied (accumulated) */
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Rotation quaternion (last value wins) */
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-        w: number;
-    };
-    /** Linear velocity (accumulated) */
-    velocity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Angular velocity (accumulated) */
-    angularVelocity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Per-source velocity intents composed once per frame */
-    velocityChannels: Record<string, VelocityIntent>;
-    /** Dirty flags to track what needs to be applied */
-    dirty: {
-        position: boolean;
-        rotation: boolean;
-        /** @deprecated Use per-axis velocityX/Y/Z flags for new code */
-        velocity: boolean;
-        velocityX: boolean;
-        velocityY: boolean;
-        velocityZ: boolean;
-        velocityChannels: boolean;
-        angularVelocity: boolean;
-    };
-}
-/**
- * Create a new transform store with optional initial values.
- * The store is a Valtio proxy, making it reactive for debugging/visualization.
- *
- * @param initial Optional initial state values
- * @returns Reactive transform state
- */
-declare function createTransformStore(initial?: Partial<TransformState>): TransformState;
-/**
- * Reset a transform store to its initial clean state.
- * Called after applying changes to prepare for the next frame.
- *
- * @param store The transform store to reset
- */
-declare function resetTransformStore(store: TransformState): void;
-
-interface EntityWithBody {
-    body: RigidBody | null;
-    transformStore?: TransformState;
-}
-/**
- * Move an entity along the X axis, preserving other velocities.
- */
-declare function moveX(entity: EntityWithBody, delta: number): void;
-/**
- * Move an entity along the Y axis, preserving other velocities.
- */
-declare function moveY(entity: EntityWithBody, delta: number): void;
-/**
- * Move an entity along the Z axis, preserving other velocities.
- */
-declare function moveZ(entity: EntityWithBody, delta: number): void;
-/**
- * Move an entity along the X and Y axis, preserving Z velocity.
- */
-declare function moveXY(entity: EntityWithBody, deltaX: number, deltaY: number): void;
-/**
- * Move an entity along the X and Z axis, preserving Y velocity.
- */
-declare function moveXZ(entity: EntityWithBody, deltaX: number, deltaZ: number): void;
-/**
- * Move entity based on a vector, adding to existing velocities.
- */
-declare function move(entity: EntityWithBody, vector: Vector3): void;
-/**
- * Reset entity velocity
- */
-declare function resetVelocity(entity: EntityWithBody): void;
-/**
- * Move entity forward in 2D space, preserving Z velocity
- */
-declare function moveForwardXY(entity: EntityWithBody, delta: number, rotation2DAngle: number): void;
-/**
- * Get entity position
- */
-declare function getPosition(entity: EntityWithBody): Vector | null;
-/**
- * Get entity velocity
- */
-declare function getVelocity(entity: EntityWithBody): Vector | null;
-/**
- * Set entity position
- */
-declare function setPosition(entity: EntityWithBody, x: number, y: number, z: number): void;
-/**
- * Set entity X position
- */
-declare function setPositionX(entity: EntityWithBody, x: number): void;
-/**
- * Set entity Y position
- */
-declare function setPositionY(entity: EntityWithBody, y: number): void;
-/**
- * Set entity Z position
- */
-declare function setPositionZ(entity: EntityWithBody, z: number): void;
-/**
- * Wrap entity around 2D bounds
- */
-declare function wrapAroundXY(entity: EntityWithBody, boundsX: number, boundsY: number): void;
-/**
- * Wrap entity around 3D bounds
- */
-declare function wrapAround3D(entity: EntityWithBody, boundsX: number, boundsY: number, boundsZ: number): void;
-/**
- * Enhanced moveable entity with bound methods
- */
-interface MoveableEntity extends EntityWithBody {
-    moveX(delta: number): void;
-    moveY(delta: number): void;
-    moveZ(delta: number): void;
-    moveXY(deltaX: number, deltaY: number): void;
-    moveXZ(deltaX: number, deltaZ: number): void;
-    move(vector: Vector3): void;
-    resetVelocity(): void;
-    moveForwardXY(delta: number, rotation2DAngle: number): void;
-    getPosition(): Vector | null;
-    getVelocity(): Vector | null;
-    setPosition(x: number, y: number, z: number): void;
-    setPositionX(x: number): void;
-    setPositionY(y: number): void;
-    setPositionZ(z: number): void;
-    wrapAroundXY(boundsX: number, boundsY: number): void;
-    wrapAround3D(boundsX: number, boundsY: number, boundsZ: number): void;
+declare abstract class EntityBuilder<T extends GameEntity<U> & P, U extends GameEntityOptions, P = any> {
+    protected meshBuilder: EntityMeshBuilder | null;
+    protected collisionBuilder: EntityCollisionBuilder | null;
+    protected materialBuilder: MaterialBuilder | null;
+    protected options: Partial<U>;
+    protected entity: T;
+    constructor(options: Partial<U>, entity: T, meshBuilder: EntityMeshBuilder | null, collisionBuilder: EntityCollisionBuilder | null);
+    withPosition(setupPosition: Vec3): this;
+    withMaterial(options: Partial<MaterialOptions>, entityType: symbol): this;
+    applyMaterialToGroup(group: Group, materials: Material[]): void;
+    build(): T;
+    protected abstract createEntity(options: Partial<U>): T;
 }
 
 interface RotatableEntity {
@@ -816,7 +631,7 @@ interface BaseCollisionOptions {
     /** Whether this collider is a sensor */
     sensor?: boolean;
     /** Position offset relative to the entity origin */
-    offset?: Vec3;
+    offset?: Vec3Input;
     /** Collision type string for group filtering */
     collisionType?: string;
     /** Allowed collision types for filtering */
@@ -824,7 +639,7 @@ interface BaseCollisionOptions {
 }
 interface BoxCollisionOptions extends BaseCollisionOptions {
     /** Box dimensions (default: 1x1x1) */
-    size?: Vec3;
+    size?: Vec3Input;
 }
 /**
  * Create a box (cuboid) collision component.
@@ -882,10 +697,7 @@ interface PillCollisionOptions extends BaseCollisionOptions {
 declare function pillCollision(opts?: PillCollisionOptions): CollisionComponent;
 interface PlaneCollisionOptions extends BaseCollisionOptions {
     /** Tile dimensions (default: 10x10) */
-    tile?: {
-        x: number;
-        y: number;
-    };
+    tile?: Vec2Input;
     /** Number of subdivisions per axis (default: 10) */
     subdivisions?: number;
     /** Pre-computed height data for the heightfield */
@@ -898,7 +710,7 @@ interface PlaneCollisionOptions extends BaseCollisionOptions {
 declare function planeCollision(opts?: PlaneCollisionOptions): CollisionComponent;
 interface ZoneCollisionOptions extends BaseCollisionOptions {
     /** Zone dimensions (default: 1x1x1) */
-    size?: Vec3;
+    size?: Vec3Input;
 }
 /**
  * Create a zone (sensor cuboid) collision component.
@@ -958,12 +770,24 @@ type IBuilder<BuilderOptions = any> = {
     build: (options: BuilderOptions) => BuilderOptions;
     postBuild: (options: BuilderOptions) => BuilderOptions;
 };
+type GameEntitySimulationMode = 'ts' | 'runtime';
+type GameEntityRenderMode = 'mesh' | 'instanced';
+type RuntimeEntityBodyMode = 'dynamic' | 'static' | 'none';
+type RuntimeEntityColorMode = 'base' | 'heatTint';
+interface RuntimeEntityOptions {
+    simulation?: GameEntitySimulationMode;
+    render?: GameEntityRenderMode;
+    batchKeyOverride?: string;
+    body?: RuntimeEntityBodyMode;
+    colorMode?: RuntimeEntityColorMode;
+}
 type GameEntityOptions = {
     name?: string;
     color?: Color;
-    size?: Vec3;
-    position?: Vec3;
+    size?: Vec3Input;
+    position?: Vec3Input;
     batched?: boolean;
+    runtime?: RuntimeEntityOptions;
     collision?: Partial<CollisionOptions>;
     material?: Partial<MaterialOptions>;
     custom?: {
@@ -987,7 +811,6 @@ interface EntityDebugInfo {
     buildInfo: () => Record<string, string>;
 }
 declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implements GameEntityLifeCycle, EntityDebugInfo, MoveableEntity, RotatableEntityAPI {
-    behaviors: Behavior[];
     group: Group | undefined;
     mesh: Mesh | undefined;
     materials: Material[] | undefined;
@@ -1013,6 +836,24 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     instanceId: number;
     /** Whether this entity uses instanced rendering */
     isInstanced: boolean;
+    /** Runtime slot index when owned by a stage runtime adapter (legacy alias for runtimeHandle). */
+    runtimeSlot: number;
+    /**
+     * Stable u32 handle into the wasm `StageSimulation`. Returned by
+     * `WasmStageRuntime.createEntity()`; -1 means the entity is not currently
+     * attached to the runtime. Replaces `runtimeSlot` and the legacy
+     * `entity.body` / `entity.collider` fields once Phase 3 lands.
+     */
+    runtimeHandle: number;
+    /** True once the entity has been attached to the wasm `StageSimulation`. */
+    runtimeAttached: boolean;
+    /**
+     * Optional reference to the stage's {@link WasmStageRuntime}. Set by
+     * `StageEntityDelegate.spawnEntity()` so {@link GameEntity.getPose} /
+     * {@link GameEntity.setPose} can route through the unified-Stage runtime
+     * without each call site needing to thread the wasm handle around.
+     */
+    wasmStageRef: WasmStageRuntime | null;
     protected eventDelegate: EventEmitterDelegate<EntityEvents>;
     private behaviorRefs;
     private cloneFactory;
@@ -1051,6 +892,37 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     setRotation: (x: number, y: number, z: number) => void;
     getRotation: () => any;
     constructor();
+    /**
+     * Read the entity's pose. Prefers the unified-Stage wasm runtime when
+     * the entity has a live `runtimeHandle`; otherwise falls back to the
+     * legacy TS Rapier `RigidBody` translation/rotation. Returns `null` when
+     * neither source is available.
+     */
+    getPose(): {
+        position: Vec3;
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        };
+    } | null;
+    /**
+     * Write the entity's pose. Routes through the unified-Stage wasm runtime
+     * when present; otherwise writes to the legacy TS Rapier `RigidBody`.
+     *
+     * Either or both of `position` and `rotation` may be omitted to leave
+     * that component unchanged.
+     */
+    setPose(input: {
+        position?: Vec3Input;
+        rotation?: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        };
+    }): boolean;
     /**
      * Add meshes, collision components, or child entities to this entity.
      * Supports fluent chaining: `entity.add(boxMesh()).add(boxCollision())`.
@@ -1076,6 +948,8 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
      * @example `const press = entity.action(onPress())`
      */
     action<A extends Action>(action: A): A;
+    /** Remove all registered actions (fire-and-forget and persistent). */
+    clearActions(): void;
     /**
      * Tick all registered actions. Called automatically before user onUpdate callbacks.
      *
@@ -1166,4 +1040,4 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
  */
 declare function create(options?: Partial<GameEntityOptions>): GameEntity<GameEntityOptions>;
 
-export { sphereCollision as $, type Action as A, setRotationZ as B, setRotationDegrees as C, setRotationDegreesY as D, setRotationDegreesX as E, setRotationDegreesZ as F, setRotation as G, getRotation as H, GameEntity as I, type UpdateFunction as J, type DestroyFunction as K, type SetupContext as L, type DestroyContext as M, type LoadingEvent as N, BaseNode as O, type GameEntityOptions as P, type StageEvents as Q, type MaterialOptions as R, type SetupFunction as S, type TransformState as T, type UpdateContext as U, type Vec3 as V, type MoveableEntity as W, type InputPlayer as X, create as Y, type ZylemShader as Z, boxCollision as _, moveX as a, coneCollision as a0, pyramidCollision as a1, cylinderCollision as a2, pillCollision as a3, planeCollision as a4, zoneCollision as a5, type CollisionComponent as a6, EventEmitterDelegate as a7, zylemEventBus as a8, type ZylemEvents as a9, type GameEvents as aa, type EntityEvents as ab, type GameLoadingPayload as ac, type StateDispatchPayload as ad, type StageConfigPayload as ae, type EntityConfigPayload as af, type ZylemShaderObject as ag, type ZylemTSLShader as ah, isTSLShader as ai, isGLSLShader as aj, type InputPlayerNumber as ak, type InputProvider as al, type Inputs as am, GameEntityLifeCycle as an, type IGame as ao, type LoadedContext as ap, type CleanupContext as aq, type NodeInterface as ar, type TexturePath as as, moveY as b, createTransformStore as c, moveZ as d, moveXY as e, moveXZ as f, resetVelocity as g, moveForwardXY as h, getPosition as i, getVelocity as j, setPositionX as k, setPositionY as l, move as m, setPositionZ as n, wrapAround3D as o, rotateInDirection as p, rotateYEuler as q, resetTransformStore as r, setPosition as s, rotateEuler as t, rotateX as u, rotateY as v, wrapAroundXY as w, rotateZ as x, setRotationY as y, setRotationX as z };
+export { type Action as A, setRotationDegrees as B, setRotationDegreesY as C, setRotationDegreesX as D, setRotationDegreesZ as E, setRotation as F, GameEntity as G, getRotation as H, type GameEntityOptions as I, EntityBuilder as J, EntityMeshBuilder as K, EntityCollisionBuilder as L, BaseNode as M, create as N, boxCollision as O, sphereCollision as P, coneCollision as Q, pyramidCollision as R, StageBodyKind as S, cylinderCollision as T, pillCollision as U, planeCollision as V, type WasmStageRuntimeOptions as W, zoneCollision as X, type CollisionComponent as Y, type NodeInterface as Z, GameEntityLifeCycle as _, type StageBodyConfig as a, type StageColliderConfig as b, type StageColliderShape as c, type StageEvent as d, type StagePose as e, type StageWasmExports as f, StageBoundaryDim as g, StageEventType as h, StageRicochetDim as i, StageRicochetReflection as j, StageTopDownPlane as k, STAGE_EVENT_STRIDE as l, STAGE_INVALID_SLOT as m, STAGE_POSE_LEN as n, STAGE_RENDER_STRIDE as o, WasmStageRuntime as p, createWasmStageRuntime as q, rotateInDirection as r, rotateYEuler as s, rotateEuler as t, rotateX as u, rotateY as v, rotateZ as w, setRotationY as x, setRotationX as y, setRotationZ as z };