@zylem/game-lib 0.6.3 → 0.7.0

package/dist/entity-DNkYKfdp.d.ts

@@ -0,0 +1,1043 @@
+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;
+    name: string;
+    markedForRemoval: boolean;
+    nodeSetup(params: SetupContext<any>): void;
+    nodeUpdate(params: UpdateContext<any>): void;
+    nodeDestroy(params: DestroyContext<any>): void;
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+}
+
+type BaseNodeOptions<T = any> = BaseNode | Partial<T>;
+/**
+ * Lifecycle callback arrays - each lifecycle event can have multiple callbacks
+ * that execute in order.
+ */
+interface LifecycleCallbacks<T> {
+    setup: Array<SetupFunction<T>>;
+    loaded: Array<LoadedFunction<T>>;
+    update: Array<UpdateFunction<T>>;
+    destroy: Array<DestroyFunction<T>>;
+    cleanup: Array<CleanupFunction<T>>;
+}
+declare abstract class BaseNode<Options = any, T = any> implements NodeInterface {
+    protected parent: NodeInterface | null;
+    protected children: NodeInterface[];
+    options: Options;
+    uuid: string;
+    name: string;
+    markedForRemoval: boolean;
+    /**
+     * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+     * Uses `any` for the type parameter to avoid invariance issues when subclasses
+     * are assigned to BaseNode references. Type safety is enforced by the public
+     * onSetup/onUpdate/etc. methods which are typed with `this`.
+     */
+    protected lifecycleCallbacks: LifecycleCallbacks<any>;
+    private trackLifecycleRegistrations;
+    private userLifecycleRegistrations;
+    constructor(args?: BaseNodeOptions[]);
+    /**
+     * Add setup callbacks to be executed in order during nodeSetup
+     */
+    onSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Add loaded callbacks to be executed in order during nodeLoaded
+     */
+    onLoaded(...callbacks: Array<LoadedFunction<this>>): this;
+    /**
+     * Add update callbacks to be executed in order during nodeUpdate
+     */
+    onUpdate(...callbacks: Array<UpdateFunction<this>>): this;
+    /**
+     * Add destroy callbacks to be executed in order during nodeDestroy
+     */
+    onDestroy(...callbacks: Array<DestroyFunction<this>>): this;
+    /**
+     * Add cleanup callbacks to be executed in order during nodeCleanup
+     */
+    onCleanup(...callbacks: Array<CleanupFunction<this>>): this;
+    /**
+     * Prepend setup callbacks (run before existing ones)
+     */
+    prependSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Prepend update callbacks (run before existing ones)
+     */
+    prependUpdate(...callbacks: Array<UpdateFunction<this>>): this;
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+    add(baseNode: NodeInterface): void;
+    remove(baseNode: NodeInterface): void;
+    getChildren(): NodeInterface[];
+    isComposite(): boolean;
+    enableUserLifecycleTracking(): void;
+    protected replayUserLifecycleRegistrationsTo(target: BaseNode<any, any>, wrap?: <T extends Function>(callback: T) => T): void;
+    protected cloneChildrenInto(target: BaseNode<any, any>): void;
+    abstract create(): T;
+    protected abstract _setup(params: SetupContext<this>): void;
+    protected abstract _loaded(params: LoadedContext<this>): Promise<void>;
+    protected abstract _update(params: UpdateContext<this>): void;
+    protected abstract _destroy(params: DestroyContext<this>): void;
+    protected abstract _cleanup(params: CleanupContext<this>): void;
+    nodeSetup(params: SetupContext<this>): void;
+    nodeUpdate(params: UpdateContext<this>): void;
+    nodeDestroy(params: DestroyContext<this>): void;
+    nodeLoaded(params: LoadedContext<this>): Promise<void>;
+    nodeCleanup(params: CleanupContext<this>): void;
+    getOptions(): Options;
+    setOptions(options: Partial<Options>): void;
+    private recordLifecycleRegistration;
+}
+
+/**
+ * `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.
+ */
+/** 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;
+};
+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;
+}
+/** 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;
+}
+/** 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.
+ */
+interface CollisionOptions {
+    static?: boolean;
+    sensor?: boolean;
+    size?: Vec3Input;
+    position?: Vec3Input;
+    collisionType?: string;
+    collisionFilter?: string[];
+}
+declare class CollisionBuilder {
+    static: boolean;
+    sensor: boolean;
+    gravity: Vec3;
+    build(options: Partial<CollisionOptions>): [RigidBodyDesc, ColliderDesc];
+    withCollision(collisionOptions: Partial<CollisionOptions>): this;
+    collider(options: CollisionOptions): ColliderDesc;
+    bodyDesc({ isDynamicBody }: {
+        isDynamicBody?: boolean | undefined;
+    }): RigidBodyDesc;
+}
+
+/**
+ * TODO: allow for multiple materials requires geometry groups
+ * TODO: allow for instanced uniforms
+ * TODO: allow for geometry groups
+ * TODO: allow for batched meshes
+ * import { InstancedUniformsMesh } from 'three-instanced-uniforms-mesh';
+ * may not need geometry groups for shaders though
+ * setGeometry<T extends BufferGeometry>(geometry: T) {
+ *   MeshBuilder.bachedMesh = new BatchedMesh(10, 5000, 10000, material);
+ * }
+ */
+type MeshBuilderOptions = Partial<Pick<GameEntityOptions, 'batched' | 'material'>>;
+declare class MeshBuilder {
+    _build(meshOptions: MeshBuilderOptions, geometry: BufferGeometry, materials: Material[]): Mesh;
+    _postBuild(): void;
+}
+
+declare abstract class EntityCollisionBuilder extends CollisionBuilder {
+    abstract collider(options: GameEntityOptions): ColliderDesc;
+}
+declare abstract class EntityMeshBuilder extends MeshBuilder {
+    build(options: GameEntityOptions): BufferGeometry;
+    postBuild(): 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 {
+    body: RigidBody | null;
+    group: any;
+    transformStore?: TransformState;
+}
+/**
+ * Rotate an entity in the direction of a movement vector
+ */
+declare function rotateInDirection(entity: RotatableEntity, moveVector: Vector3): void;
+/**
+ * Rotate an entity around the Y axis using Euler angles
+ */
+declare function rotateYEuler(entity: RotatableEntity, amount: number): void;
+/**
+ * Rotate an entity using Euler angles
+ */
+declare function rotateEuler(entity: RotatableEntity, rotation: Vector3): void;
+/**
+ * Rotate an entity around the Y axis.
+ */
+declare function rotateY(entity: RotatableEntity, delta: number): void;
+/**
+ * Rotate an entity around the X axis.
+ */
+declare function rotateX(entity: RotatableEntity, delta: number): void;
+/**
+ * Rotate an entity around the Z axis.
+ */
+declare function rotateZ(entity: RotatableEntity, delta: number): void;
+/**
+ * Set rotation around Y axis.
+ */
+declare function setRotationY(entity: RotatableEntity, y: number): void;
+/**
+ * Set rotation around Y axis
+ */
+declare function setRotationDegreesY(entity: RotatableEntity, y: number): void;
+/**
+ * Set rotation around X axis.
+ */
+declare function setRotationX(entity: RotatableEntity, x: number): void;
+/**
+ * Set rotation around X axis
+ */
+declare function setRotationDegreesX(entity: RotatableEntity, x: number): void;
+/**
+ * Set rotation around Z axis.
+ */
+declare function setRotationZ(entity: RotatableEntity, z: number): void;
+/**
+ * Set rotation around Z axis
+ */
+declare function setRotationDegreesZ(entity: RotatableEntity, z: number): void;
+/**
+ * Set rotation for all axes.
+ */
+declare function setRotation(entity: RotatableEntity, x: number, y: number, z: number): void;
+/**
+ * Set rotation for all axes
+ */
+declare function setRotationDegrees(entity: RotatableEntity, x: number, y: number, z: number): void;
+/**
+ * Get current rotation
+ */
+declare function getRotation(entity: RotatableEntity): any;
+/**
+ * Rotatable entity API with bound methods
+ */
+interface RotatableEntityAPI extends RotatableEntity {
+    rotateInDirection(moveVector: Vector3): void;
+    rotateYEuler(amount: number): void;
+    rotateEuler(rotation: Vector3): void;
+    rotateY(delta: number): void;
+    rotateX(delta: number): void;
+    rotateZ(delta: number): void;
+    setRotationY(y: number): void;
+    setRotationX(x: number): void;
+    setRotationZ(z: number): void;
+    setRotationDegrees(x: number, y: number, z: number): void;
+    setRotationDegreesY(y: number): void;
+    setRotationDegreesX(x: number): void;
+    setRotationDegreesZ(z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    getRotation(): any;
+}
+
+/**
+ * A built collision component containing a rigid body description and collider description.
+ * Returned by collision factory functions (boxCollision, sphereCollision, etc.)
+ * and consumed by GameEntity.add().
+ */
+interface CollisionComponent {
+    __kind: 'collision';
+    bodyDesc: RigidBodyDesc;
+    colliderDesc: ColliderDesc;
+    cloneComponent: () => CollisionComponent;
+}
+interface BaseCollisionOptions {
+    /** Whether the body is static (fixed) or dynamic */
+    static?: boolean;
+    /** Whether this collider is a sensor */
+    sensor?: boolean;
+    /** Position offset relative to the entity origin */
+    offset?: Vec3Input;
+    /** Collision type string for group filtering */
+    collisionType?: string;
+    /** Allowed collision types for filtering */
+    collisionFilter?: string[];
+}
+interface BoxCollisionOptions extends BaseCollisionOptions {
+    /** Box dimensions (default: 1x1x1) */
+    size?: Vec3Input;
+}
+/**
+ * Create a box (cuboid) collision component.
+ */
+declare function boxCollision(opts?: BoxCollisionOptions): CollisionComponent;
+interface SphereCollisionOptions extends BaseCollisionOptions {
+    /** Sphere radius (default: 1) */
+    radius?: number;
+}
+/**
+ * Create a sphere (ball) collision component.
+ */
+declare function sphereCollision(opts?: SphereCollisionOptions): CollisionComponent;
+interface ConeCollisionOptions extends BaseCollisionOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a cone collision component.
+ */
+declare function coneCollision(opts?: ConeCollisionOptions): CollisionComponent;
+interface PyramidCollisionOptions extends BaseCollisionOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a pyramid collision component (approximated as a cone).
+ */
+declare function pyramidCollision(opts?: PyramidCollisionOptions): CollisionComponent;
+interface CylinderCollisionOptions extends BaseCollisionOptions {
+    /** Top radius (default: 1) */
+    radiusTop?: number;
+    /** Bottom radius (default: 1) */
+    radiusBottom?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a cylinder collision component.
+ */
+declare function cylinderCollision(opts?: CylinderCollisionOptions): CollisionComponent;
+interface PillCollisionOptions extends BaseCollisionOptions {
+    /** Capsule hemisphere radius (default: 0.5) */
+    radius?: number;
+    /** Cylindrical section length (default: 1) */
+    length?: number;
+}
+/**
+ * Create a pill (capsule) collision component.
+ */
+declare function pillCollision(opts?: PillCollisionOptions): CollisionComponent;
+interface PlaneCollisionOptions extends BaseCollisionOptions {
+    /** Tile dimensions (default: 10x10) */
+    tile?: Vec2Input;
+    /** Number of subdivisions per axis (default: 10) */
+    subdivisions?: number;
+    /** Pre-computed height data for the heightfield */
+    heightData?: Float32Array;
+}
+/**
+ * Create a plane (heightfield) collision component.
+ * For flat planes, pass no heightData — a zeroed heightfield is used.
+ */
+declare function planeCollision(opts?: PlaneCollisionOptions): CollisionComponent;
+interface ZoneCollisionOptions extends BaseCollisionOptions {
+    /** Zone dimensions (default: 1x1x1) */
+    size?: Vec3Input;
+}
+/**
+ * Create a zone (sensor cuboid) collision component.
+ * Always a sensor; static by default.
+ */
+declare function zoneCollision(opts?: ZoneCollisionOptions): CollisionComponent;
+
+/**
+ * Action interface -- the base contract for all actions.
+ *
+ * Actions are entity-scoped, self-contained objects that modify entity state
+ * over time. They are ticked automatically by the entity update loop.
+ */
+interface Action {
+    /** Internal duration in seconds (0 = instant, Infinity = persistent) */
+    readonly duration: number;
+    /** Whether this action has completed */
+    readonly done: boolean;
+    /** Whether this action auto-removes when done (set by entity.action()) */
+    persistent: boolean;
+    /** Advance the action by delta seconds */
+    tick(entity: GameEntity<any>, delta: number): void;
+    /** Reset the action to its initial state */
+    reset(): void;
+}
+
+interface CollisionContext<T, O extends GameEntityOptions, TGlobals extends Record<string, unknown> = any> {
+    entity: T;
+    other: GameEntity<O | any>;
+    globals: TGlobals;
+}
+type CollisionPhase = 'enter' | 'stay';
+interface CollisionRegistrationOptions {
+    phase?: CollisionPhase;
+    cooldownMs?: number;
+}
+interface NormalizedCollisionRegistrationOptions {
+    phase: CollisionPhase;
+    cooldownMs?: number;
+}
+interface CollisionRegistration<T, O extends GameEntityOptions> {
+    id: number;
+    callback: (params: CollisionContext<T, O>) => void;
+    options: NormalizedCollisionRegistrationOptions;
+}
+interface CollisionDispatchMetadata {
+    phase: CollisionPhase;
+    nowMs: number;
+}
+interface CollisionDelegate<T, O extends GameEntityOptions> {
+    collision?: CollisionRegistration<any, any>[];
+    cooldowns?: Map<string, number>;
+    nextId?: number;
+}
+type IBuilder<BuilderOptions = any> = {
+    preBuild: (options: BuilderOptions) => BuilderOptions;
+    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?: Vec3Input;
+    position?: Vec3Input;
+    batched?: boolean;
+    runtime?: RuntimeEntityOptions;
+    collision?: Partial<CollisionOptions>;
+    material?: Partial<MaterialOptions>;
+    custom?: {
+        [key: string]: any;
+    };
+    collisionType?: string;
+    collisionGroup?: string;
+    collisionFilter?: string[];
+    _builders?: {
+        meshBuilder?: IBuilder | EntityMeshBuilder | null;
+        collisionBuilder?: IBuilder | EntityCollisionBuilder | null;
+        materialBuilder?: MaterialBuilder | null;
+    };
+};
+declare abstract class GameEntityLifeCycle {
+    abstract _setup(params: SetupContext<this>): void;
+    abstract _update(params: UpdateContext<this>): void;
+    abstract _destroy(params: DestroyContext<this>): void;
+}
+interface EntityDebugInfo {
+    buildInfo: () => Record<string, string>;
+}
+declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implements GameEntityLifeCycle, EntityDebugInfo, MoveableEntity, RotatableEntityAPI {
+    group: Group | undefined;
+    mesh: Mesh | undefined;
+    materials: Material[] | undefined;
+    bodyDesc: RigidBodyDesc | null;
+    body: RigidBody | null;
+    physicsAttached: boolean;
+    colliderDesc: ColliderDesc | undefined;
+    collider: Collider | undefined;
+    custom: Record<string, any>;
+    /** All collider descriptions for this entity (including primary) */
+    colliderDescs: ColliderDesc[];
+    /** All colliders attached to this entity's rigid body */
+    colliders: Collider[];
+    /** Additional meshes for compound visual entities (added via add()) */
+    compoundMeshes: Mesh[];
+    debugInfo: Record<string, any>;
+    debugMaterial: ShaderMaterial | undefined;
+    collisionDelegate: CollisionDelegate<this, O>;
+    collisionType?: string;
+    /** Batch key for instanced rendering (null if not instanced) */
+    batchKey: string | null;
+    /** Index within the instanced mesh batch */
+    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;
+    private trackAddedComponents;
+    private trackedComponents;
+    transformStore: TransformState;
+    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;
+    rotateInDirection: (moveVector: Vector3) => void;
+    rotateYEuler: (amount: number) => void;
+    rotateEuler: (eulerRotation: Vector3) => void;
+    rotateX: (delta: number) => void;
+    rotateY: (delta: number) => void;
+    rotateZ: (delta: number) => void;
+    setRotationY: (y: number) => void;
+    setRotationX: (x: number) => void;
+    setRotationZ: (z: number) => void;
+    setRotationDegrees: (x: number, y: number, z: number) => void;
+    setRotationDegreesY: (y: number) => void;
+    setRotationDegreesX: (x: number) => void;
+    setRotationDegreesZ: (z: number) => void;
+    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())`.
+     *
+     * - `Mesh`: First mesh becomes the primary mesh; subsequent meshes are
+     *   compound meshes grouped together.
+     * - `CollisionComponent`: First sets bodyDesc + colliderDesc; subsequent
+     *   add extra colliders to the same rigid body.
+     * - `NodeInterface`: Added as a child entity (delegates to BaseNode.add).
+     */
+    add(...components: Array<NodeInterface | Mesh | CollisionComponent>): this;
+    private addMeshComponent;
+    private addCollisionComponent;
+    private trackComponent;
+    private _actions;
+    /**
+     * Run a fire-and-forget action. Auto-removed when done.
+     * @example `me.runAction(moveBy({ x: 10, duration: 0.3 }))`
+     */
+    runAction<A extends Action>(action: A): A;
+    /**
+     * Register a persistent action (throttle, onPress). Not removed when done.
+     * @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.
+     *
+     * Resets velocity/angularVelocity accumulation before ticking so that
+     * actions can compose via `+=` without cross-frame build-up.
+     * (The existing move helpers like `moveXY` use `=` which doesn't accumulate,
+     * but action composition needs additive writes on a clean slate each frame.)
+     */
+    _tickActions(delta: number): void;
+    create(): this;
+    clone(overrides?: Partial<O>): this;
+    finalizeCloneSupport(factory: (options?: Partial<O>) => GameEntity<O>): this;
+    /**
+     * Add collision callbacks
+     */
+    onCollision(callback: (params: CollisionContext<this, O>) => void, options?: CollisionRegistrationOptions): this;
+    onCollision(...callbacks: ((params: CollisionContext<this, O>) => void)[]): this;
+    /**
+     * Use a behavior on this entity via typed descriptor.
+     * Behaviors will be auto-registered as systems when the entity is spawned.
+     * @param descriptor The behavior descriptor (import from behaviors module)
+     * @param options Optional overrides for the behavior's default options
+     * @returns BehaviorHandle with behavior-specific methods for lazy FSM access
+     */
+    use<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>>(descriptor: BehaviorDescriptor<O, H>, options?: Partial<O>): BehaviorHandle<O, H>;
+    /**
+     * Get all behavior references attached to this entity.
+     * Used by the stage to auto-register required systems.
+     */
+    getBehaviorRefs(): BehaviorRef[];
+    getCollisionCallbacks(): Array<(params: CollisionContext<this, O>) => void>;
+    getCollisionRegistrations(): Array<CollisionRegistration<this, O>>;
+    private copyBehaviorRefsTo;
+    /**
+     * Entity-specific setup - resets actions for a fresh stage session.
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+     */
+    _setup(params: SetupContext<this>): void;
+    protected _loaded(_params: LoadedContext<this>): Promise<void>;
+    /**
+     * Entity-specific update - updates materials.
+     * Transform changes are applied by the stage after all update callbacks complete.
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+     */
+    _update(params: UpdateContext<this>): void;
+    /**
+     * Entity-specific destroy -- reserved for consumer game logic.
+     * Engine-internal resource disposal runs in _cleanup() instead.
+     */
+    _destroy(params: DestroyContext<this>): void;
+    /**
+     * Engine-internal resource cleanup -- runs automatically after destroy.
+     * Disposes GPU/DOM resources (meshes, materials, debug material).
+     *
+     * Note: actions, collision callbacks, and behavior refs are intentionally
+     * NOT cleared here -- they are registered by consumer code at module level
+     * and must persist across stage reloads. Actions are reset in _setup().
+     */
+    protected _cleanup(_params: CleanupContext<this>): void;
+    _collision(other: GameEntity<O>, globals?: any, dispatch?: CollisionDispatchMetadata): void;
+    protected updateMaterials(params: any): void;
+    buildInfo(): Record<string, string>;
+    /**
+     * Dispatch an event from this entity.
+     * Events are emitted both locally and to the global event bus.
+     */
+    dispatch<K extends keyof EntityEvents>(event: K, payload: EntityEvents[K]): void;
+    /**
+     * Listen for events on this entity instance.
+     * @returns Unsubscribe function
+     */
+    listen<K extends keyof EntityEvents>(event: K, handler: (payload: EntityEvents[K]) => void): () => void;
+    /**
+     * Clean up entity event subscriptions.
+     */
+    disposeEvents(): void;
+}
+/**
+ * Create a bare entity with no mesh or collision.
+ * Use `.add(boxMesh(), boxCollision())` to compose its shape.
+ *
+ * @example
+ * ```ts
+ * const box = create({ position: { x: 0, y: 5, z: 0 } })
+ *   .add(boxMesh({ size: { x: 2, y: 2, z: 2 } }))
+ *   .add(boxCollision({ size: { x: 2, y: 2, z: 2 } }));
+ * ```
+ */
+declare function create(options?: Partial<GameEntityOptions>): GameEntity<GameEntityOptions>;
+
+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 };