@zylem/behaviors 0.4.1 → 0.5.1

package/dist/core.d.ts

@@ -1,13 +1,12 @@
-import { L as VelocityIntentMode, T as TransformState } from './behavior-system-y8SGrGWy.js';
-export { B as BaseBehaviorHandle, a as BehaviorDescriptor, b as BehaviorEntityLink, c as BehaviorHandle, d as BehaviorRef, e as BehaviorSystem, f as BehaviorSystemContext, g as BehaviorSystemFactory, C as CreateEntityFn, D as DefineBehaviorConfig, G as GameEntity, h as GameEntityOptions, S as STAGE_INPUT_BUTTON_JUMP, i as STAGE_INPUT_BUTTON_RUN, j as StageBehaviorSnapshot, k as StageBodyKind, l as StageBoundaryDim, m as StageBoundaryDimValue, n as StageEventType, o as StageFirstPersonInput, p as StageFirstPersonOptions, q as StageJumper2DOptions, r as StageJumper3DOptions, s as StagePlatformer2DOptions, t as StagePlatformer3DOptions, u as StagePose, v as StageRicochetDim, w as StageRicochetDimValue, x as StageRicochetOptions, y as StageRicochetReflection, z as StageRicochetReflectionValue, A as StageScreenWrapOptions, E as StageShooter2DOptions, F as StageThrusterOptions, H as StageTopDownOptions, I as StageTopDownPlane, J as StageTopDownPlaneValue, K as StageWorldBoundaryOptions, V as VelocityIntent, W as WasmSnapshotBackref, M as WasmStageRuntime, N as WasmStageRuntimeOptions, O as createTransformStore, P as defineBehavior, Q as readBehaviorSnapshot } from './behavior-system-y8SGrGWy.js';
-export { u as useBehavior } from './use-behavior-B85d5u7-.js';
-export { P as PhysicsBodyComponent, T as TransformComponent, c as createPhysicsBodyComponent, a as createTransformComponent } from './components-BWG1GkZA.js';
-export { E as EntityWithBody, M as MoveableEntity, g as getPosition, a as getVelocity, m as makeMoveable, b as move, c as moveForwardXY, d as moveX, e as moveXY, f as moveXZ, h as moveY, i as moveZ, r as resetVelocity, s as setPosition, j as setPositionX, k as setPositionY, l as setPositionZ, w as wrapAround3D, n as wrapAroundXY } from './moveable-Cl9h-_w7.js';
-export { V as VEC2_ONE, a as VEC2_ZERO, b as VEC3_ONE, c as VEC3_ZERO, d as Vec2, e as Vec2Components, f as Vec2Input, g as Vec3, h as Vec3Components, i as Vec3Input, j as isVec2Input, k as isVec3Input, n as normalizeVec2, l as normalizeVec3, t as toRapierVector3, m as toThreeVector2, o as toThreeVector3 } from './vector-Bm65-FOG.js';
+import { _ as VelocityIntentMode, Y as TransformState, e as BehaviorRuntime, I as StagePose, l as StageBehaviorSnapshot, T as StageThrusterOptions, U as StageTopDownOptions, R as StageShooter2DOptions, Q as StageScreenWrapOptions, r as StageBoundaryDimValue, X as StageWorldBoundaryOptions, M as StageRicochetDimValue, N as StageRicochetOptions, H as StagePlatformer3DOptions, F as StagePlatformer2DOptions, z as StageFirstPersonOptions, y as StageFirstPersonInput, A as StageJumper2DOptions, E as StageJumper3DOptions, a0 as WasmStageRuntime, a1 as WasmStageRuntimeOptions, p as StageBodyKindValue, t as StageColliderShape, K as StageRenderSlot, J as StageRaycastHit, n as StageBodyInfo, u as StageDebugRender } from './behavior-system-CeJXzNvr.js';
+export { B as BaseBehaviorHandle, a as BehaviorDescriptor, b as BehaviorEntityLink, c as BehaviorHandle, d as BehaviorRef, f as BehaviorSystem, g as BehaviorSystemContext, h as BehaviorSystemFactory, C as CreateEntityFn, D as DefineBehaviorConfig, G as GameEntity, i as GameEntityOptions, S as STAGE_INPUT_BUTTON_JUMP, j as STAGE_INPUT_BUTTON_RUN, k as STAGE_INVALID_SLOT, m as StageBodyConfig, o as StageBodyKind, q as StageBoundaryDim, s as StageColliderConfig, v as StageEvent, w as StageEventType, x as StageEventTypeValue, L as StageRicochetDim, O as StageRicochetReflection, P as StageRicochetReflectionValue, V as StageTopDownPlane, W as StageTopDownPlaneValue, Z as VelocityIntent, $ as WasmSnapshotBackref, a2 as createTransformStore, a3 as createWasmStageRuntime, a4 as defineBehavior, a5 as readBehaviorSnapshot, a6 as readStageRenderSlot } from './behavior-system-CeJXzNvr.js';
+export { P as PhysicsBodyComponent, T as TransformComponent, c as createPhysicsBodyComponent, a as createTransformComponent, u as useBehavior } from './components-BANNjAZP.js';
+export { E as EntityWithBody, M as MoveableBodyLike, a as MoveableEntity, V as Vector, g as getPosition, b as getVelocity, m as makeMoveable, c as move, d as moveForwardXY, e as moveX, f as moveXY, h as moveXZ, i as moveY, j as moveZ, r as resetVelocity, s as setPosition, k as setPositionX, l as setPositionY, n as setPositionZ, w as wrapAround3D, o as wrapAroundXY } from './moveable-XhzWPAw5.js';
+export { V as VEC2_ONE, a as VEC2_ZERO, b as VEC3_ONE, c as VEC3_ZERO, d as Vec2, e as Vec2Components, f as Vec2Input, g as Vec3, h as Vec3Components, i as Vec3Input, j as isVec2Input, k as isVec3Input, n as normalizeVec2, l as normalizeVec3, t as toThreeVector2, m as toThreeVector3 } from './vector-DjhLUrak.js';
 export { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
 export { F as FirstPersonPerspective } from './first-person-perspective-C9Mptl0-.js';
 export { ILogger, ITransition, SyncCallback, t } from 'typescript-fsm';
-import '@dimforge/rapier3d-compat';
+export { STAGE_EVENT_STRIDE, STAGE_INPUT_STRIDE, STAGE_RENDER_STRIDE, STAGE_SNAPSHOT_STRIDE, StageWasmExports } from '@zylem/runtime';
 import 'three';
 
 interface VelocityIntentOptions {
@@ -22,4 +21,285 @@ interface VelocityIntentVector {
 declare function setVelocityIntent(store: TransformState, sourceId: string, vector: VelocityIntentVector, options?: VelocityIntentOptions): void;
 declare function clearVelocityIntent(store: TransformState, sourceId: string): void;
 
-export { TransformState, VelocityIntentMode, type VelocityIntentOptions, type VelocityIntentVector, clearVelocityIntent, setVelocityIntent };
+/**
+ * In-memory implementation of the {@link BehaviorRuntime} contract for unit
+ * tests. Records every attach / input call per handle and lets tests seed
+ * poses and behavior snapshots without instantiating the wasm runtime.
+ */
+
+interface MockSlotState {
+    pose: StagePose;
+    snapshot: StageBehaviorSnapshot | null;
+    input: {
+        axisA: number;
+        axisB: number;
+        yawDelta: number;
+        pitchDelta: number;
+        reservedA: number;
+        reservedB: number;
+        buttons: number;
+    };
+    attachments: Map<string, unknown>;
+    inputs: Array<{
+        kind: string;
+        args: unknown[];
+    }>;
+    screenWrapQuery: {
+        fsm: number;
+        lastWrappedAxes: number;
+    } | null;
+    worldBoundaryQuery: {
+        hits: number;
+        clamped: [number, number, number];
+    } | null;
+}
+declare class MockBehaviorRuntime implements BehaviorRuntime {
+    private slots;
+    private slot;
+    /** Seed the pose returned by {@link getPose} for a handle. */
+    setPose(handle: number, pose: StagePose): void;
+    /** Seed the snapshot returned by {@link readSnapshot} for a handle. */
+    setSnapshot(handle: number, snapshot: StageBehaviorSnapshot | null): void;
+    /** Seed {@link queryScreenWrap} results. */
+    setScreenWrapQuery(handle: number, value: {
+        fsm: number;
+        lastWrappedAxes: number;
+    } | null): void;
+    /** Seed {@link queryWorldBoundary} results. */
+    setWorldBoundaryQuery(handle: number, value: {
+        hits: number;
+        clamped: [number, number, number];
+    } | null): void;
+    /** Attachment options recorded for a handle, keyed by behavior name. */
+    getAttachment<T>(handle: number, kind: string): T | undefined;
+    hasAttachment(handle: number, kind: string): boolean;
+    /** Every per-entity input call recorded for a handle, oldest first. */
+    getInputCalls(handle: number): Array<{
+        kind: string;
+        args: unknown[];
+    }>;
+    /** Last written batched-input state for a handle. */
+    getBatchedInput(handle: number): MockSlotState['input'];
+    reset(): void;
+    setPosition(handle: number, x: number, y: number, z: number): boolean;
+    setRotation(handle: number, x: number, y: number, z: number, w: number): boolean;
+    getPose(handle: number, out?: StagePose): StagePose | null;
+    writeInputAxes(handle: number, axisA: number, axisB: number): boolean;
+    writeInputLook(handle: number, yawDelta: number, pitchDelta: number): boolean;
+    writeInputReserved(handle: number, reservedA: number, reservedB: number): boolean;
+    writeInputButton(handle: number, buttonMask: number, pressed: boolean): boolean;
+    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;
+}
+
+/**
+ * `Simulation` (a.k.a. `BehaviorWorld`) — the primary public abstraction of
+ * `@zylem/behaviors`. It owns the wasm runtime lifecycle (one
+ * `WebAssembly.Instance` of `@zylem/runtime` per simulation), the fixed
+ * timestep accumulator, an entity registry mapping opaque
+ * {@link EntityHandle}s to runtime slots, and per-step event translation
+ * from raw stage events into typed {@link SimulationEvent}s.
+ *
+ * Hosts (e.g. `@zylem/game-lib`) call {@link createSimulation} once per
+ * stage, `spawn()`/`despawn()` entities, call `update(delta)` once per
+ * render frame, and read poses for rendering from the returned
+ * {@link SimulationFrame}.
+ */
+
+/**
+ * Opaque, stable identifier for a simulation entity. `slot` is the raw
+ * runtime slot index — treat it as an implementation detail owned by the
+ * Simulation (it is only exposed so hosts can wire behavior systems, which
+ * address the batched buffers by slot).
+ */
+interface EntityHandle {
+    /** Monotonic public id, never reused within a Simulation. */
+    readonly id: number;
+    /** Raw runtime slot index. Internal — may be reused after despawn. */
+    readonly slot: number;
+}
+/** Partial body description; unspecified fields use sensible defaults. */
+interface SimulationBodyDefinition {
+    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];
+}
+/** Partial collider description; unspecified fields use sensible defaults. */
+interface SimulationColliderDefinition {
+    shape: StageColliderShape;
+    offset?: readonly [number, number, number];
+    friction?: number;
+    restitution?: number;
+    sensor?: boolean;
+    collisionGroups?: number;
+}
+/** Everything needed to materialize one entity inside the runtime. */
+interface EntityDefinition {
+    body?: SimulationBodyDefinition;
+    colliders?: SimulationColliderDefinition[];
+}
+/** Typed, handle-resolved simulation event. */
+type SimulationEvent = {
+    type: 'collisionStarted' | 'collisionStopped';
+    a: EntityHandle | null;
+    b: EntityHandle | null;
+    /** True when either collider in the pair is a sensor (zone overlap). */
+    sensor: boolean;
+    /** Best-effort contact normal (x, y); zero for sensor pairs / stops. */
+    normal: [number, number];
+} | {
+    type: 'boundaryHit';
+    entity: EntityHandle | null;
+    axes: number;
+    signs: number;
+} | {
+    type: 'ricochet';
+    entity: EntityHandle | null;
+    kind: number;
+} | {
+    type: 'regionEntered';
+    entity: EntityHandle | null;
+    triggerId: number;
+} | {
+    type: 'jumpStarted';
+    entity: EntityHandle | null;
+    jumpCount: number;
+} | {
+    type: 'landed';
+    entity: EntityHandle | null;
+} | {
+    type: 'wrapped';
+    entity: EntityHandle | null;
+    axes: number;
+} | {
+    type: 'cooldownFired';
+    entity: EntityHandle | null;
+    cooldownId: number;
+};
+/**
+ * Snapshot of one `update()` call: how many fixed steps ran, the live render
+ * buffer view, the previous-step render copy + interpolation alpha for
+ * smooth rendering, and the translated events from every step taken.
+ */
+interface SimulationFrame {
+    /** Wall-clock delta handed to `update()`. */
+    deltaTime: number;
+    /** Number of fixed steps executed (0 when accumulating). */
+    stepsTaken: number;
+    /** Interpolation alpha in [0, 1): fraction of a fixed step accumulated. */
+    alpha: number;
+    /** Live render buffer (post-step poses), {@link STAGE_RENDER_STRIDE} floats per slot. */
+    render: Float32Array;
+    /** Copy of the render buffer as of the step before the last one. */
+    previousRender: Float32Array;
+    renderStride: number;
+    /** Typed events from all steps taken this update, oldest first. */
+    events: SimulationEvent[];
+}
+interface SimulationOptions extends WasmStageRuntimeOptions {
+    /** Fixed physics timestep in seconds (default 1/60). */
+    fixedTimestep?: number;
+    /** Max fixed steps per `update()` to avoid death spirals (default 4). */
+    maxSubSteps?: number;
+}
+/**
+ * The behavior world. Construct via {@link createSimulation}.
+ */
+declare class Simulation {
+    /**
+     * The low-level wasm adapter. Behavior systems receive this as their
+     * `wasmStage` context so descriptors can attach/query behaviors by slot;
+     * hosts should prefer the handle-based methods on the Simulation itself.
+     */
+    readonly adapter: WasmStageRuntime;
+    readonly fixedTimestep: number;
+    private readonly maxSubSteps;
+    private accumulator;
+    private nextEntityId;
+    private slotToHandle;
+    private idToHandle;
+    private previousRender;
+    private disposed;
+    constructor(adapter: WasmStageRuntime, options?: SimulationOptions);
+    /**
+     * Create a runtime entity from a plain definition. Returns `null` when
+     * the runtime rejects the allocation.
+     */
+    spawn(definition?: EntityDefinition): EntityHandle | null;
+    despawn(handle: EntityHandle): boolean;
+    /** Resolve a raw runtime slot back to its public handle, if alive. */
+    handleForSlot(slot: number): EntityHandle | null;
+    get entityCount(): number;
+    /**
+     * Advance the simulation by `deltaTime` seconds using a fixed-timestep
+     * accumulator. Runs zero or more fixed steps and returns a
+     * {@link SimulationFrame} with translated events and interpolation data.
+     */
+    update(deltaTime: number): SimulationFrame;
+    private capturePreviousRender;
+    private translateEvents;
+    getPose(handle: EntityHandle, out?: StagePose): StagePose | null;
+    setPosition(handle: EntityHandle, x: number, y: number, z: number): boolean;
+    setRotation(handle: EntityHandle, x: number, y: number, z: number, w: number): boolean;
+    setLinearVelocity(handle: EntityHandle, x: number, y: number, z: number): boolean;
+    getLinearVelocity(handle: EntityHandle): [number, number, number] | null;
+    setAngularVelocity(handle: EntityHandle, x: number, y: number, z: number): boolean;
+    applyImpulse(handle: EntityHandle, x: number, y: number, z: number): boolean;
+    readRenderSlot(handle: EntityHandle, out?: StageRenderSlot): StageRenderSlot | null;
+    /** Decode a handle's pose from the previous-step render copy. */
+    readPreviousRenderSlot(handle: EntityHandle, out?: StageRenderSlot): StageRenderSlot | null;
+    readSnapshot(handle: EntityHandle, out?: StageBehaviorSnapshot): StageBehaviorSnapshot | null;
+    setGravity(x: number, y: number, z: number): void;
+    /** Physics raycast; the hit's slot is resolved to an entity handle. */
+    castRay(origin: readonly [number, number, number], dir: readonly [number, number, number], maxDistance: number, solidOnly?: boolean): (Omit<StageRaycastHit, 'slot'> & {
+        entity: EntityHandle | null;
+    }) | null;
+    getBodyInfo(handle: EntityHandle): StageBodyInfo | null;
+    getDebugRender(): StageDebugRender | null;
+    get isDisposed(): boolean;
+    /** Destroy the wasm stage. The Simulation must not be used afterwards. */
+    dispose(): void;
+}
+/** Alias matching the architecture doc's naming. */
+type BehaviorWorld = Simulation;
+/**
+ * Load and instantiate the `@zylem/runtime` wasm module and wrap it in a
+ * {@link Simulation}. One call per logical stage/world.
+ */
+declare function createSimulation(options?: SimulationOptions): Promise<Simulation>;
+
+export { BehaviorRuntime, type BehaviorWorld, type EntityDefinition, type EntityHandle, MockBehaviorRuntime, Simulation, type SimulationBodyDefinition, type SimulationColliderDefinition, type SimulationEvent, type SimulationFrame, type SimulationOptions, StageBehaviorSnapshot, StageBodyInfo, StageBodyKindValue, StageBoundaryDimValue, StageColliderShape, StageDebugRender, StageFirstPersonInput, StageFirstPersonOptions, StageJumper2DOptions, StageJumper3DOptions, StagePlatformer2DOptions, StagePlatformer3DOptions, StagePose, StageRaycastHit, StageRenderSlot, StageRicochetDimValue, StageRicochetOptions, StageScreenWrapOptions, StageShooter2DOptions, StageThrusterOptions, StageTopDownOptions, StageWorldBoundaryOptions, TransformState, VelocityIntentMode, type VelocityIntentOptions, type VelocityIntentVector, WasmStageRuntime, WasmStageRuntimeOptions, clearVelocityIntent, createSimulation, setVelocityIntent };