@zylem/game-lib 0.6.2 → 0.6.4

package/dist/physics.d.ts

@@ -0,0 +1,205 @@
+import { B as BodyCommand, a as SerializableBodyDesc, S as SerializableColliderDesc, b as SerializableCharacterController, P as PhysicsStepResultEvent, C as CollisionPair } from './physics-protocol-BDD3P5W2.js';
+export { h as ColliderShapeKind, F as FLOATS_PER_BODY, c as PhysicsCommand, f as PhysicsErrorEvent, d as PhysicsEvent, e as PhysicsReadyEvent, g as SerializableBodyType, T as TransformOffset } from './physics-protocol-BDD3P5W2.js';
+import { P as PhysicsPoseHistory, a as PhysicsPose } from './physics-pose-DCc4oE44.js';
+import { RigidBodyDesc, ColliderDesc } from '@dimforge/rapier3d-compat';
+
+/**
+ * Main-thread handle for a physics body that lives in a Web Worker.
+ *
+ * Provides the same read interface as a Rapier RigidBody (translation,
+ * rotation, linvel, angvel) by returning cached values that are synced
+ * from the worker each frame.
+ *
+ * Write operations (setLinvel, setTranslation, etc.) are queued as
+ * {@link BodyCommand}s and sent to the worker on the next step.
+ */
+declare class PhysicsBodyHandle {
+    readonly uuid: string;
+    /** Last-known physics state, updated from worker each frame. */
+    private _snapshot;
+    /** Queued commands to be sent to the worker on next step. */
+    private _pendingCommands;
+    /** Optional reference to the proxy's shared command queue. */
+    private _sharedQueue;
+    constructor(uuid: string, sharedQueue?: BodyCommand[]);
+    /** Cached position from last physics step. */
+    translation(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Cached rotation quaternion from last physics step. */
+    rotation(): {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    /** Cached linear velocity from last physics step. */
+    linvel(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Cached angular velocity from last physics step. */
+    angvel(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    getPoseHistory(): PhysicsPoseHistory;
+    getRenderPose(alpha: number): PhysicsPose;
+    setLinvel(v: {
+        x: number;
+        y: number;
+        z: number;
+    }, _wakeUp?: boolean): void;
+    setAngvel(v: {
+        x: number;
+        y: number;
+        z: number;
+    }, _wakeUp?: boolean): void;
+    setTranslation(v: {
+        x: number;
+        y: number;
+        z: number;
+    }, _wakeUp?: boolean): void;
+    setRotation(q: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }, _wakeUp?: boolean): void;
+    applyImpulse(v: {
+        x: number;
+        y: number;
+        z: number;
+    }, _wakeUp?: boolean): void;
+    applyTorqueImpulse(v: {
+        x: number;
+        y: number;
+        z: number;
+    }, _wakeUp?: boolean): void;
+    lockTranslations(locked: boolean, _wakeUp?: boolean): void;
+    lockRotations(locked: boolean, _wakeUp?: boolean): void;
+    setLinearDamping(damping: number): void;
+    setGravityScale(scale: number, _wakeUp?: boolean): void;
+    /** Returns 'Dynamic' for compatibility; actual type is not synced. */
+    bodyType(): number;
+    mass(): number;
+    isEnabled(): boolean;
+    isSleeping(): boolean;
+    /** Collider access is not available through the handle. Returns null. */
+    collider(_index: number): null;
+    /**
+     * Update the cached snapshot from worker data.
+     * Called by the PhysicsProxy after receiving a stepResult.
+     */
+    _seedSnapshot(px: number, py: number, pz: number, rx: number, ry: number, rz: number, rw: number, lvx: number, lvy: number, lvz: number, avx: number, avy: number, avz: number): void;
+    _updateSnapshot(px: number, py: number, pz: number, rx: number, ry: number, rz: number, rw: number, lvx: number, lvy: number, lvz: number, avx: number, avy: number, avz: number): void;
+    /** Drain pending commands. */
+    _drainCommands(): BodyCommand[];
+    private enqueue;
+    private copyPose;
+    private writePose;
+    private setCollapsedTranslation;
+    private setCollapsedRotation;
+}
+
+/**
+ * Callback signature for collision events dispatched by the proxy.
+ */
+type CollisionCallback = (pair: CollisionPair) => void;
+/**
+ * Main-thread proxy that communicates with the physics Web Worker.
+ *
+ * Usage:
+ * ```ts
+ * const proxy = new PhysicsProxy();
+ * await proxy.init([0, -9.81, 0], 60);
+ * const handle = proxy.addBody(uuid, bodyDesc, colliderDescs);
+ * // each frame:
+ * await proxy.step(delta);
+ * ```
+ *
+ * The proxy owns the worker lifecycle and manages body handles.
+ * After each step, all handles are updated with fresh transform data
+ * and collision callbacks are fired.
+ */
+declare class PhysicsProxy {
+    private worker;
+    private handles;
+    private commandQueue;
+    private collisionListeners;
+    private pendingStep;
+    /** Latest interpolation alpha from the worker (0..1). */
+    interpolationAlpha: number;
+    /**
+     * Spawn the worker and initialize the Rapier world inside it.
+     * Resolves when the worker reports `ready`.
+     *
+     * @param gravity World gravity as [x, y, z].
+     * @param physicsRate Physics tick rate in Hz (default 60).
+     * @param workerUrl URL to the physics worker script. The consuming
+     *   application must provide this because bundlers (Vite, Webpack)
+     *   can only resolve worker URLs from application source code.
+     *   Example for Vite:
+     *   ```ts
+     *   new URL('@zylem/game-lib/dist/physics-worker.js', import.meta.url)
+     *   ```
+     */
+    init(gravity: [number, number, number], physicsRate?: number, workerUrl?: URL): Promise<void>;
+    /**
+     * Register a body in the worker and return a main-thread handle.
+     *
+     * @returns A {@link PhysicsBodyHandle} for reading cached transforms
+     *   and queuing write commands.
+     */
+    addBody(uuid: string, body: SerializableBodyDesc, colliders: SerializableColliderDesc[], characterController?: SerializableCharacterController): PhysicsBodyHandle;
+    /** Remove a body from the worker and discard its handle. */
+    removeBody(uuid: string): void;
+    /** Get a body handle by entity UUID. */
+    getHandle(uuid: string): PhysicsBodyHandle | undefined;
+    /**
+     * Send a step command to the worker with the current frame delta
+     * and all queued body commands.
+     *
+     * Returns a promise that resolves after the worker replies with
+     * the step result. Handles are updated and collision callbacks
+     * are fired before the promise resolves.
+     */
+    step(delta: number): Promise<PhysicsStepResultEvent>;
+    /**
+     * Subscribe to collision events.
+     * @returns Unsubscribe function.
+     */
+    onCollision(callback: CollisionCallback): () => void;
+    /** Terminate the worker and release all handles. */
+    dispose(): void;
+    private send;
+    private onWorkerMessage;
+    private applyStepResult;
+}
+
+/**
+ * Convert a Rapier RigidBodyDesc to a plain serializable object.
+ *
+ * Rapier descriptors are WASM-backed class instances that cannot cross
+ * the postMessage boundary. This extracts the relevant data into a
+ * JSON-safe format that the worker can reconstruct.
+ */
+declare function serializeBodyDesc(desc: RigidBodyDesc): SerializableBodyDesc;
+/**
+ * Convert a Rapier ColliderDesc to a plain serializable object.
+ *
+ * Because Rapier's ColliderDesc uses opaque shape enums and internal
+ * buffers, we infer the shape from the descriptor's internal type tag
+ * and extract the numeric dimensions.
+ */
+declare function serializeColliderDesc(desc: ColliderDesc): SerializableColliderDesc;
+/**
+ * Create a serializable character controller descriptor.
+ */
+declare function serializeCharacterController(): SerializableCharacterController;
+
+export { BodyCommand, CollisionPair, PhysicsBodyHandle, PhysicsProxy, PhysicsStepResultEvent, SerializableBodyDesc, SerializableCharacterController, SerializableColliderDesc, serializeBodyDesc, serializeCharacterController, serializeColliderDesc };