@zylem/behaviors 0.4.0 → 0.5.1

package/dist/behavior-system-CeJXzNvr.d.ts

@@ -0,0 +1,868 @@
+import { StageWasmExports } from '@zylem/runtime';
+
+/**
+ * BehaviorDescriptor
+ *
+ * Type-safe behavior descriptors that provide options inference.
+ * Used with entity.use() to declaratively attach behaviors to entities.
+ *
+ * Each behavior can define its own handle type via `createHandle`,
+ * providing behavior-specific methods with full type safety.
+ */
+
+/**
+ * Base handle returned by entity.use() for lazy access to behavior runtime.
+ * FSM is null until entity is spawned and components are initialized.
+ */
+interface BaseBehaviorHandle<O extends Record<string, any> = Record<string, any>> {
+    /** Get the FSM instance (null until entity is spawned) */
+    getFSM(): any | null;
+    /** Get the current options */
+    getOptions(): O;
+    /** Access the underlying behavior ref */
+    readonly ref: BehaviorRef<O>;
+}
+/**
+ * Reference to a behavior stored on an entity
+ */
+interface BehaviorRef<O extends Record<string, any> = Record<string, any>> {
+    /** The behavior descriptor */
+    descriptor: BehaviorDescriptor<O, any>;
+    /** Merged options (defaults + overrides) */
+    options: O;
+    /** Optional FSM instance - set lazily when entity is spawned */
+    fsm?: any;
+}
+/**
+ * A typed behavior descriptor that associates a symbol key with:
+ * - Default options (providing type inference)
+ * - A system factory to create the behavior system
+ * - An optional handle factory for behavior-specific methods
+ */
+interface BehaviorDescriptor<O extends Record<string, any> = Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown> {
+    /** Unique symbol identifying this behavior */
+    readonly key: symbol;
+    /** Default options (used for type inference) */
+    readonly defaultOptions: O;
+    /** Factory to create the behavior system */
+    readonly systemFactory: any;
+    /**
+     * Optional factory to create behavior-specific handle methods.
+     * These methods are merged into the handle returned by entity.use().
+     */
+    readonly createHandle?: (ref: any) => H;
+}
+/**
+ * The full handle type returned by entity.use().
+ * Combines base handle with behavior-specific methods.
+ */
+type BehaviorHandle<O extends Record<string, any> = Record<string, any>, H extends Record<string, any> = Record<string, never>> = BaseBehaviorHandle<O> & H;
+/**
+ * Configuration for defining a new behavior
+ */
+interface DefineBehaviorConfig<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown> {
+    /** Human-readable name for debugging */
+    name: string;
+    /** Default options - these define the type */
+    defaultOptions: O;
+    /** Factory function to create the system */
+    systemFactory: BehaviorSystemFactory;
+    /**
+     * Optional factory to create behavior-specific handle methods.
+     * The returned object is merged into the handle returned by entity.use().
+     *
+     * @example
+     * ```typescript
+     * createHandle: (ref) => ({
+     *   getLastHits: () => ref.fsm?.getLastHits() ?? null,
+     *   getMovement: (moveX, moveY) => ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },
+     * }),
+     * ```
+     */
+    createHandle?: (ref: BehaviorRef<O>) => H;
+}
+/**
+ * Define a typed behavior descriptor.
+ *
+ * @example
+ * ```typescript
+ * export const WorldBoundary2DBehavior = defineBehavior({
+ *   name: 'world-boundary-2d',
+ *   defaultOptions: { boundaries: { top: 0, bottom: 0, left: 0, right: 0 } },
+ *   systemFactory: (ctx) => new WorldBoundary2DSystem(ctx.world),
+ *   createHandle: (ref) => ({
+ *     getLastHits: () => ref.fsm?.getLastHits() ?? null,
+ *     getMovement: (moveX: number, moveY: number) =>
+ *       ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },
+ *   }),
+ * });
+ *
+ * // Usage - handle has getLastHits and getMovement with full types
+ * const boundary = ship.use(WorldBoundary2DBehavior, { ... });
+ * const hits = boundary.getLastHits(); // Fully typed!
+ * ```
+ */
+declare function defineBehavior<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown>(config: DefineBehaviorConfig<O, H, I>): BehaviorDescriptor<O, H, I>;
+
+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;
+        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;
+
+/**
+ * Minimal, runtime-agnostic entity options contract.
+ *
+ * The full engine entity (in `@zylem/game-lib`) provides a richer options type,
+ * but behaviors only rely on this loose shape.
+ */
+interface GameEntityOptions {
+    [key: string]: any;
+    name?: string;
+}
+/**
+ * Structural stand-in for the engine `GameEntity`.
+ *
+ * Behaviors annotate against this loose contract so that `@zylem/behaviors`
+ * (and its `@zylem/behaviors/core` surface) never has to depend on the concrete
+ * `@zylem/game-lib` entity implementation. The real engine entity is
+ * structurally assignable to this type.
+ */
+declare class GameEntity<TOptions = unknown> {
+    [key: string]: any;
+    uuid: string;
+    name: string;
+    type: string;
+    options?: TOptions & Record<string, unknown>;
+    group: any;
+    mesh?: any;
+    materials?: any[];
+    /** Opaque host-owned physics references (never inspected by behaviors). */
+    body: unknown | null;
+    collider: unknown | null;
+    colliderDesc?: any;
+    colliderDescs: any[];
+    bodyDesc?: any;
+    physicsAttached: boolean;
+    runtimeHandle?: number;
+    transformStore?: TransformState;
+    nodeDestroy?: any;
+    isInstanced?: boolean;
+    private __behaviorRefs;
+    create(): this;
+    onCleanup(callback: () => void): this;
+    setPosition(_x: number, _y: number, _z: number): void;
+    setRotation(_x: number, _y: number, _z: number): void;
+    setRotationZ(_z: number): void;
+    setScale(_x: number, _y: number, _z: number): void;
+    /**
+     * Attach a behavior to this entity. The real engine entity does substantially
+     * more, but this functional stub stores the merged ref and builds the handle
+     * so descriptor/handle logic (and tests that drive behaviors directly) work
+     * without the full engine.
+     */
+    use<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>>(descriptor: BehaviorDescriptor<O, H>, options?: Partial<O>): BehaviorHandle<O, H>;
+    /** Live behavior refs attached via {@link use}. */
+    getBehaviorRefs(): BehaviorRef<any>[];
+}
+/**
+ * Factory contract injected into behavior systems via
+ * {@link BehaviorSystemContext.createEntity}. The host engine supplies the real
+ * entity factory at stage-construction time.
+ */
+type CreateEntityFn = (options?: Partial<GameEntityOptions>) => GameEntity<GameEntityOptions>;
+
+/**
+ * `WasmStageRuntime` — owns one wasm `WebAssembly.Instance` of
+ * `@zylem/runtime` and exposes the unified-Stage FFI as typed TypeScript
+ * methods. This is the single simulation adapter for the whole framework:
+ * behavior systems talk to it through the {@link BehaviorRuntime} contract,
+ * and hosts (e.g. `@zylem/game-lib`) drive it through
+ * {@link createSimulation} in `./simulation`.
+ */
+
+/** Sentinel handle for "no entity / failed allocation". Mirrors `INVALID_SLOT` in Rust. */
+declare const STAGE_INVALID_SLOT = 4294967295;
+declare const StageBodyKind: {
+    readonly Dynamic: 0;
+    readonly Static: 1;
+    readonly KinematicPosition: 2;
+    readonly KinematicVelocity: 3;
+};
+type StageBodyKindValue = (typeof StageBodyKind)[keyof typeof StageBodyKind];
+declare const StageBoundaryDim: {
+    readonly Two: 2;
+    readonly Three: 3;
+};
+declare const StageRicochetDim: {
+    readonly Two: 2;
+    readonly Three: 3;
+};
+declare const StageRicochetReflection: {
+    readonly Mirror: 0;
+    readonly Angled: 1;
+};
+declare const StageTopDownPlane: {
+    readonly Xy: 0;
+    readonly Xz: 1;
+};
+declare const StageEventType: {
+    readonly CollisionStarted: 1;
+    readonly CollisionStopped: 2;
+    readonly BoundaryHit: 3;
+    readonly Ricochet: 4;
+    readonly RegionEntered: 5;
+    readonly JumpStarted: 6;
+    readonly Landed: 7;
+    readonly Wrapped: 8;
+    readonly CooldownFired: 9;
+};
+type StageBoundaryDimValue = (typeof StageBoundaryDim)[keyof typeof StageBoundaryDim];
+type StageRicochetDimValue = (typeof StageRicochetDim)[keyof typeof StageRicochetDim];
+type StageRicochetReflectionValue = (typeof StageRicochetReflection)[keyof typeof StageRicochetReflection];
+type StageTopDownPlaneValue = (typeof StageTopDownPlane)[keyof typeof StageTopDownPlane];
+/** Position + rotation snapshot for one runtime slot. */
+interface StagePose {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+}
+interface StageWorldBoundaryOptions {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    front?: number;
+    back?: number;
+    padding?: number;
+}
+interface StageScreenWrapOptions {
+    width: number;
+    height: number;
+    centerX?: number;
+    centerY?: number;
+    edgeThreshold?: number;
+}
+interface StageRicochetOptions {
+    minSpeed: number;
+    maxSpeed: number;
+    speedMultiplier: number;
+    maxAngleDeg: number;
+    reflectionMode: StageRicochetReflectionValue;
+}
+interface StageThrusterOptions {
+    maxSpeed: number;
+    acceleration: number;
+    turnRateRadPerSec: number;
+    linearDamping: number;
+}
+interface StageTopDownOptions {
+    plane: StageTopDownPlaneValue;
+    speed: number;
+    faceMovement?: boolean;
+}
+interface StageShooter2DOptions {
+    fireRateHz: number;
+    muzzleOffsetX: number;
+    muzzleOffsetY: number;
+    muzzleSpeed: number;
+}
+interface StageJumper2DOptions {
+    jumpForce: number;
+    maxJumps: number;
+    jumpBufferTime: number;
+    coyoteTime: number;
+    gravity: number;
+}
+interface StageJumper3DOptions {
+    jumpForce: number;
+    maxJumps: number;
+    gravity: number;
+    /** Coyote time in seconds (default 0.1). */
+    coyoteTime?: number;
+    /** Jump buffer window in seconds (default 0.08). */
+    jumpBufferTime?: number;
+}
+interface StagePlatformer3DOptions {
+    halfHeight: number;
+    radius: number;
+    walkSpeed: number;
+    runSpeed: number;
+    jumpForce: number;
+    maxJumps: number;
+    gravity: number;
+    /** Coyote time in seconds (default 0.1). */
+    coyoteTime?: number;
+    /** Jump buffer window in seconds (default 0.1). */
+    jumpBufferTime?: number;
+    /** Velocity multiplier applied on early jump release (default 0.5). */
+    jumpCutMultiplier?: number;
+    /** Seconds before a multi-jump becomes available (default 0.15). */
+    multiJumpWindow?: number;
+    /** Max slope angle in degrees the KCC can climb (default 50). */
+    slopeClimbAngle?: number;
+    /** Slope angle in degrees past which the character slides (default 40). */
+    slopeSlideAngle?: number;
+    /** Autostep max height in world units; 0 disables (default 0.3). */
+    autostepHeight?: number;
+    /** Minimum unobstructed width for an autostep (default 0.1). */
+    autostepMinWidth?: number;
+    /** Snap-to-ground distance in world units; 0 disables (default 0.3). */
+    snapToGroundDistance?: number;
+    /** KCC collision offset between collider and environment (default 0.05). */
+    characterOffset?: number;
+}
+interface StagePlatformer2DOptions {
+    halfHeight: number;
+    radius: number;
+    walkSpeed: number;
+    runSpeed: number;
+    jumpForce: number;
+    maxJumps: number;
+    gravity: number;
+    /** Coyote time in seconds (default 0.1). */
+    coyoteTime?: number;
+    /** Jump buffer window in seconds (default 0.1). */
+    jumpBufferTime?: number;
+    /** Velocity multiplier applied on early jump release (default 0.5). */
+    jumpCutMultiplier?: number;
+    /** Seconds before a multi-jump becomes available (default 0.15). */
+    multiJumpWindow?: number;
+    /** Max slope angle in degrees the KCC can climb (default 50). */
+    slopeClimbAngle?: number;
+    /** Slope angle in degrees past which the character slides (default 40). */
+    slopeSlideAngle?: number;
+    /** Autostep max height in world units; 0 disables (default 0.25). */
+    autostepHeight?: number;
+    /** Minimum unobstructed width for an autostep (default 0.05). */
+    autostepMinWidth?: number;
+    /** Snap-to-ground distance in world units; 0 disables (default 0.2). */
+    snapToGroundDistance?: number;
+    /** KCC collision offset between collider and environment (default 0.05). */
+    characterOffset?: number;
+}
+interface StageFirstPersonOptions {
+    walkSpeed: number;
+    runSpeed: number;
+    eyeHeight: number;
+    lookSensitivity: number;
+}
+interface StageFirstPersonInput {
+    moveX: number;
+    moveZ: number;
+    lookYawDelta: number;
+    lookPitchDelta: number;
+    run: boolean;
+}
+/** Button bits for the batched input buffer's bitmask field. */
+declare const STAGE_INPUT_BUTTON_JUMP = 1;
+declare const STAGE_INPUT_BUTTON_RUN = 2;
+/**
+ * Decoded per-slot behavior snapshot written by the runtime after every
+ * step: movement fields come from whichever character behavior the entity
+ * has (platformer 3D/2D, jumper 3D/2D); first-person fills yaw/pitch.
+ * Values reflect the end of the previous `step()` (one-frame read lag).
+ */
+interface StageBehaviorSnapshot {
+    grounded: boolean;
+    fsmState: number;
+    jumpCount: number;
+    verticalVelocity: number;
+    speed: number;
+    yaw: number;
+    pitch: number;
+}
+/**
+ * Wasm fast-path backrefs a behavior system stores on its `BehaviorRef` every
+ * frame so descriptor handles can read the runtime snapshot buffer instead of
+ * a duplicate TS FSM (or hardcoded defaults).
+ */
+interface WasmSnapshotBackref {
+    __wasmStage?: BehaviorRuntime | null;
+    __entity?: {
+        runtimeHandle?: number;
+    } | null;
+}
+/**
+ * Read the behavior snapshot for the entity a `BehaviorRef` is linked to.
+ * Returns `null` off the wasm fast path (no stage runtime / no
+ * `runtimeHandle` / no snapshot yet), in which case handles should fall back
+ * to their TS FSM.
+ */
+declare function readBehaviorSnapshot(ref: object): StageBehaviorSnapshot | null;
+/**
+ * Runtime surface behavior systems rely on. `WasmStageRuntime` is the real
+ * wasm-backed implementation; `MockBehaviorRuntime` (see
+ * `./mock-behavior-runtime`) implements the same contract for unit tests, so
+ * descriptors stay runtime-agnostic.
+ */
+interface BehaviorRuntime {
+    getPose(handle: number, out?: StagePose): StagePose | null;
+    setPosition(handle: number, x: number, y: number, z: number): boolean;
+    setRotation(handle: number, x: number, y: number, z: number, w: number): boolean;
+    writeInputAxes(handle: number, axisA: number, axisB: number): boolean;
+    writeInputLook(handle: number, yawDelta: number, pitchDelta: number): boolean;
+    /** Write reserved input slots (thruster world-space vector X/Y). */
+    writeInputReserved(handle: number, reservedA: number, reservedB: number): boolean;
+    writeInputButton(handle: number, buttonMask: number, pressed: boolean): boolean;
+    /** Read the per-slot behavior snapshot written at the end of the previous step. */
+    readSnapshot(handle: number, out?: StageBehaviorSnapshot): StageBehaviorSnapshot | null;
+    attachThruster(handle: number, opts: StageThrusterOptions): boolean;
+    setThrusterInput(handle: number, thrust: number, rotate: number, vectorX?: number, vectorY?: number): void;
+    attachTopDown(handle: number, opts: StageTopDownOptions): boolean;
+    setTopDownInput(handle: number, moveX: number, moveY: number): void;
+    attachShooter2D(handle: number, opts: StageShooter2DOptions): boolean;
+    attachScreenWrap(handle: number, opts: StageScreenWrapOptions): boolean;
+    queryScreenWrap(handle: number): {
+        fsm: number;
+        lastWrappedAxes: number;
+    } | null;
+    attachWorldBoundary(handle: number, dim: StageBoundaryDimValue, opts: StageWorldBoundaryOptions): boolean;
+    queryWorldBoundary(handle: number): {
+        hits: number;
+        clamped: [number, number, number];
+    } | null;
+    attachRicochet(handle: number, dim: StageRicochetDimValue, opts: StageRicochetOptions): boolean;
+    attachPlatformer3D(handle: number, opts: StagePlatformer3DOptions): boolean;
+    setPlatformer3DInputAxes(handle: number, moveX: number, moveZ: number): void;
+    setPlatformer3DInputButtons(handle: number, jump: boolean, run: boolean): void;
+    attachPlatformer2D(handle: number, opts: StagePlatformer2DOptions): boolean;
+    setPlatformer2DInputAxes(handle: number, moveX: number): void;
+    setPlatformer2DInputButtons(handle: number, jump: boolean, run: boolean): void;
+    attachFirstPerson(handle: number, opts: StageFirstPersonOptions): boolean;
+    setFirstPersonInput(handle: number, input: StageFirstPersonInput): void;
+    attachJumper2D(handle: number, opts: StageJumper2DOptions): boolean;
+    setJumper2DInput(handle: number, jumpPressed: boolean): void;
+    attachJumper3D(handle: number, opts: StageJumper3DOptions): boolean;
+    setJumper3DInput(handle: number, jumpPressed: boolean): void;
+}
+/** Default options used when constructing a wasm-backed Stage runtime. */
+interface WasmStageRuntimeOptions {
+    initialCapacity?: number;
+    gravity?: readonly [number, number, number];
+    imports?: WebAssembly.Imports;
+    /**
+     * Custom wasm source. Defaults to the `zylem_runtime.wasm` bundled with
+     * `@zylem/runtime`.
+     */
+    source?: RequestInfo | URL | ArrayBuffer | Uint8Array;
+}
+type StageEventTypeValue = (typeof StageEventType)[keyof typeof StageEventType];
+/** One decoded event drained from the runtime's per-step event buffer. */
+interface StageEvent {
+    type: StageEventTypeValue;
+    primarySlot: number | null;
+    secondarySlot: number | null;
+    payload: [number, number, number];
+}
+/**
+ * Decoded view of one entity's slot in the unified render buffer.
+ *
+ * Mirrors the `STAGE_RENDER_STRIDE` (12-float) packing documented in
+ * `runtime/stage/render.rs`:
+ * `[0..3]` position, `[3..7]` rotation xyzw, `[7]` uniform scale,
+ * `[8..12]` custom0..custom3 (per-behavior shading hints).
+ */
+interface StageRenderSlot {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+    scale: number;
+    custom: [number, number, number, number];
+}
+/**
+ * Read a single entity slot out of a unified-Stage render buffer view.
+ *
+ * @param view   The `Float32Array` over wasm memory (e.g. `WasmStageRuntime.render`).
+ * @param slot   The entity's wasm slot id (its `runtimeHandle`).
+ * @param out    Optional target object to write into (avoids per-call allocation).
+ * @returns The decoded slot, or `null` when the slot is out of range.
+ */
+declare function readStageRenderSlot(view: Float32Array, slot: number, out?: StageRenderSlot): StageRenderSlot | null;
+interface StageBodyConfig {
+    kind: StageBodyKindValue;
+    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: 'cone';
+    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 interaction-groups: high 16 bits = membership, low 16 bits = filter. */
+    collisionGroups: number;
+}
+/** Result of a physics raycast against the stage. */
+interface StageRaycastHit {
+    slot: number;
+    distance: number;
+    normal: [number, number, number];
+}
+/** Body introspection payload for debug tooling. */
+interface StageBodyInfo {
+    bodyType: number;
+    mass: number;
+    isSleeping: boolean;
+    isEnabled: boolean;
+    linearVelocity: [number, number, number];
+}
+/** Line-list wireframe for physics debug rendering. */
+interface StageDebugRender {
+    /** `[x, y, z]` per vertex, two vertices per line. */
+    vertices: Float32Array;
+    /** RGBA per vertex. */
+    colors: Float32Array;
+}
+/**
+ * Owns the wasm instance plus the live float-views over its render / event /
+ * pose / scratch buffers. One instance per logical stage; 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 implements BehaviorRuntime {
+    readonly exports: StageWasmExports;
+    private readonly memory;
+    private renderView;
+    private inputView;
+    private snapshotView;
+    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;
+    getAngularVelocity(slot: number, out?: [number, number, number]): [number, number, number] | null;
+    applyImpulse(slot: number, x: number, y: number, z: number): boolean;
+    /** Cast a ray against the physics world. Returns the closest hit or `null`. */
+    castRay(origin: readonly [number, number, number], dir: readonly [number, number, number], maxDistance: number, solidOnly?: boolean): StageRaycastHit | null;
+    /** Body introspection for debug tooling. */
+    getBodyInfo(slot: number): StageBodyInfo | null;
+    /** Wireframe debug render of every collider (all shapes). */
+    getDebugRender(): StageDebugRender | null;
+    /** Read-only view over the render buffer; one slot occupies {@link STAGE_RENDER_STRIDE} floats. */
+    get render(): Float32Array;
+    get renderStride(): number;
+    /**
+     * Decode a single entity slot from the live render buffer. Convenience
+     * wrapper over {@link readStageRenderSlot} bound to this runtime's view.
+     */
+    readRenderSlot(slot: number, out?: StageRenderSlot): StageRenderSlot | null;
+    /** Drain the wasm event buffer into a fresh array of typed events. */
+    drainEvents(): StageEvent[];
+    /** Writable view over the slot-indexed input buffer ({@link STAGE_INPUT_STRIDE} floats/slot). */
+    get input(): Float32Array;
+    get inputStride(): number;
+    /** Read-only view over the per-slot behavior snapshot buffer ({@link STAGE_SNAPSHOT_STRIDE} floats/slot). */
+    get snapshot(): Float32Array;
+    get snapshotStride(): number;
+    /**
+     * Write the primary movement axes for a slot into the batched input
+     * buffer and mark the slot dirty. Field-scoped (doesn't touch look
+     * deltas or buttons) so multiple behaviors composed on one entity can
+     * each write their part.
+     */
+    writeInputAxes(slot: number, axisA: number, axisB: number): boolean;
+    /** Write the look deltas (first-person yaw/pitch) for a slot. */
+    writeInputLook(slot: number, yawDelta: number, pitchDelta: number): boolean;
+    /** Write reserved input slots (thruster world-space vector X/Y). */
+    writeInputReserved(slot: number, reservedA: number, reservedB: number): boolean;
+    /**
+     * Set or clear one button bit ({@link STAGE_INPUT_BUTTON_JUMP} /
+     * {@link STAGE_INPUT_BUTTON_RUN}) in a slot's input bitmask.
+     */
+    writeInputButton(slot: number, buttonMask: number, pressed: boolean): boolean;
+    /**
+     * Decode a slot's behavior snapshot from the buffer written at the end of
+     * the previous step. Returns `null` when the slot has no behavior data.
+     */
+    readSnapshot(slot: number, out?: StageBehaviorSnapshot): StageBehaviorSnapshot | null;
+    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: StageBoundaryDimValue, bounds: StageWorldBoundaryOptions): boolean;
+    queryWorldBoundary(slot: number): {
+        hits: number;
+        clamped: [number, number, number];
+    } | null;
+    attachScreenWrap(slot: number, opts: StageScreenWrapOptions): boolean;
+    queryScreenWrap(slot: number): {
+        fsm: number;
+        lastWrappedAxes: number;
+    } | null;
+    attachRicochet(slot: number, dim: StageRicochetDimValue, opts: StageRicochetOptions): boolean;
+    queryRicochet(slot: number): {
+        bounces: number;
+        lastKind: number;
+    } | null;
+    attachThruster(slot: number, opts: StageThrusterOptions): boolean;
+    setThrusterInput(slot: number, thrust: number, turn: number, vectorX?: number, vectorY?: number): void;
+    queryThruster(slot: number): {
+        headingRad: number;
+        speed: number;
+    } | null;
+    attachTopDown(slot: number, opts: StageTopDownOptions): boolean;
+    setTopDownInput(slot: number, axisA: number, axisB: number): void;
+    attachJumper2D(slot: number, opts: StageJumper2DOptions): boolean;
+    setJumper2DInput(slot: number, jumpPressed: boolean): void;
+    queryJumper2D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        coyote: number;
+        jumpBuffer: number;
+    } | null;
+    attachJumper3D(slot: number, opts: StageJumper3DOptions): boolean;
+    setJumper3DInput(slot: number, jump: boolean): void;
+    queryJumper3D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        verticalVelocity: number;
+    } | null;
+    attachShooter2D(slot: number, opts: StageShooter2DOptions): 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: StagePlatformer3DOptions): 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;
+    attachPlatformer2D(slot: number, opts: StagePlatformer2DOptions): boolean;
+    setPlatformer2DInputAxes(slot: number, moveX: number): void;
+    setPlatformer2DInputButtons(slot: number, jump: boolean, run: boolean): void;
+    queryPlatformer2D(slot: number): {
+        grounded: boolean;
+        jumpCount: number;
+        fsmState: number;
+        verticalVelocity: number;
+    } | null;
+    attachFirstPerson(slot: number, opts: StageFirstPersonOptions): boolean;
+    setFirstPersonInput(slot: number, input: StageFirstPersonInput): void;
+    queryFirstPerson(slot: number): {
+        yaw: number;
+        pitch: number;
+        speed: number;
+        eyeHeight: number;
+    } | null;
+}
+/**
+ * Load the bundled `@zylem/runtime` wasm (or a custom `source`), instantiate
+ * it, and construct a `WasmStageRuntime` around the exports.
+ */
+declare function createWasmStageRuntime(options?: WasmStageRuntimeOptions): Promise<WasmStageRuntime>;
+
+/**
+ * Structural stand-in for the engine world wrapper. The engine's world
+ * delegate exposes an entity lookup map; behaviors only rely on this slice.
+ *
+ * The map value is intentionally `unknown` (not the `GameEntity` stub class):
+ * the engine's concrete entity class is a different nominal type, and systems
+ * that iterate the map narrow entities themselves.
+ */
+interface ZylemWorld {
+    collisionMap?: Map<string, unknown>;
+}
+
+/**
+ * BehaviorSystem Interface
+ *
+ * Legacy behavior systems reserved the first `update` argument for an ECS world
+ * handle; it is always `undefined` now.
+ */
+/**
+ * A behavior system that processes entities with specific components.
+ *
+ * @example
+ * ```typescript
+ * class ThrusterSystem implements BehaviorSystem {
+ *   update(_ecs: unknown, delta: number): void {
+ *     // Iterate behavior links, push intent into wasm runtime, etc.
+ *   }
+ * }
+ * ```
+ */
+interface BehaviorSystem {
+    /** Optional eager initialization when a behavior link is registered on a live entity */
+    attach?(link: BehaviorEntityLink): void;
+    /** Called once per frame. The first argument is always `undefined` (reserved legacy slot). */
+    update(ecs: unknown, delta: number): void;
+    /** Optional cleanup when a behavior link is detached from a live entity */
+    detach?(link: BehaviorEntityLink): void;
+    /** Optional cleanup when stage is destroyed */
+    destroy?(ecs?: unknown): void;
+}
+/**
+ * Runtime link between a spawned entity and one of its behavior refs.
+ * Systems can iterate these links to avoid scanning all world entities.
+ */
+interface BehaviorEntityLink {
+    entity: any;
+    ref: any;
+}
+/**
+ * Context provided to behavior-system factories.
+ *
+ * After the runtime-only stage migration, `wasmStage` is the source of
+ * truth — descriptors should call `wasmStage.attach<X>(handle, opts)` /
+ * `wasmStage.query<X>(handle)` from inside the system instead of touching
+ * `entity.body` directly. The legacy `world` / `scene` fields remain for
+ * unmigrated descriptors.
+ */
+interface BehaviorSystemContext {
+    world: ZylemWorld | null;
+    /** Host scene wrapper (engine-specific); behaviors only call `add`/`remove`-style methods on it. */
+    scene: any;
+    /** Wasm-driven Stage runtime; omitted when the stage has no wasm module. */
+    wasmStage?: BehaviorRuntime | null;
+    /**
+     * Returns live behavior links for a descriptor key.
+     * O(1) lookup into a pre-built stage index.
+     */
+    getBehaviorLinks?: (key: symbol) => Iterable<BehaviorEntityLink>;
+    /**
+     * Host-injected entity factory. Behaviors that spawn entities at runtime
+     * (e.g. destructible-3d fragments) use this instead of importing the engine
+     * entity factory directly, keeping the behavior layer decoupled.
+     */
+    createEntity?: CreateEntityFn;
+    /**
+     * Host-injected accessor for the global game-state bag, passed to entity
+     * lifecycle hooks (e.g. `nodeDestroy`).
+     */
+    getGlobals?: () => any;
+}
+/**
+ * Factory function that creates a BehaviorSystem.
+ * Receives the stage for access to world, scene, etc.
+ */
+type BehaviorSystemFactory<T extends BehaviorSystem = BehaviorSystem> = (stage: BehaviorSystemContext) => T;
+
+export { type WasmSnapshotBackref as $, type StageJumper2DOptions as A, type BaseBehaviorHandle as B, type CreateEntityFn as C, type DefineBehaviorConfig as D, type StageJumper3DOptions as E, type StagePlatformer2DOptions as F, GameEntity as G, type StagePlatformer3DOptions as H, type StagePose as I, type StageRaycastHit as J, type StageRenderSlot as K, StageRicochetDim as L, type StageRicochetDimValue as M, type StageRicochetOptions as N, StageRicochetReflection as O, type StageRicochetReflectionValue as P, type StageScreenWrapOptions as Q, type StageShooter2DOptions as R, STAGE_INPUT_BUTTON_JUMP as S, type StageThrusterOptions as T, type StageTopDownOptions as U, StageTopDownPlane as V, type StageTopDownPlaneValue as W, type StageWorldBoundaryOptions as X, type TransformState as Y, type VelocityIntent as Z, type VelocityIntentMode as _, type BehaviorDescriptor as a, WasmStageRuntime as a0, type WasmStageRuntimeOptions as a1, createTransformStore as a2, createWasmStageRuntime as a3, defineBehavior as a4, readBehaviorSnapshot as a5, readStageRenderSlot as a6, type BehaviorEntityLink as b, type BehaviorHandle as c, type BehaviorRef as d, type BehaviorRuntime as e, type BehaviorSystem as f, type BehaviorSystemContext as g, type BehaviorSystemFactory as h, type GameEntityOptions as i, STAGE_INPUT_BUTTON_RUN as j, STAGE_INVALID_SLOT as k, type StageBehaviorSnapshot as l, type StageBodyConfig as m, type StageBodyInfo as n, StageBodyKind as o, type StageBodyKindValue as p, StageBoundaryDim as q, type StageBoundaryDimValue as r, type StageColliderConfig as s, type StageColliderShape as t, type StageDebugRender as u, type StageEvent as v, StageEventType as w, type StageEventTypeValue as x, type StageFirstPersonInput as y, type StageFirstPersonOptions as z };