@zylem/game-lib 0.6.2 → 0.6.4

package/dist/sync-state-machine-CZyspBpj.d.ts

@@ -0,0 +1,16 @@
+import { SyncCallback, StateMachine, ITransition, ILogger } from 'typescript-fsm';
+
+/**
+ * Local wrapper around typescript-fsm's SyncStateMachine.
+ *
+ * typescript-fsm@1.6.0 incorrectly reports callback-less transitions as
+ * unhandled even after moving to the next state, which causes noisy
+ * `No transition...` console errors for valid FSM dispatches.
+ */
+declare class SyncStateMachine<STATE extends string | number | symbol, EVENT extends string | number | symbol, CALLBACK extends Record<EVENT, SyncCallback> = Record<EVENT, SyncCallback>> extends StateMachine<STATE, EVENT, CALLBACK> {
+    constructor(init: STATE, transitions?: ITransition<STATE, EVENT, CALLBACK[EVENT]>[], logger?: ILogger);
+    dispatch<E extends EVENT>(_event: E, ..._args: unknown[]): Promise<void>;
+    syncDispatch<E extends EVENT>(event: E, ...args: unknown[]): boolean;
+}
+
+export { SyncStateMachine as S };

package/dist/thruster-23lzoPZd.d.ts

@@ -0,0 +1,180 @@
+import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
+import { Z as ZylemWorld } from './world-DfgxoNMt.js';
+import { RigidBody } from '@dimforge/rapier3d-compat';
+import { Vector3, Quaternion } from 'three';
+import { c as BehaviorDescriptor } from './behavior-descriptor-BXnVR8Ki.js';
+
+/**
+ * Core ECS Components
+ *
+ * These are pure data interfaces with no logic.
+ * They work alongside the existing bitecs components in transformable.system.ts
+ */
+
+interface TransformComponent {
+    position: Vector3;
+    rotation: Quaternion;
+}
+declare function createTransformComponent(): TransformComponent;
+interface PhysicsBodyComponent {
+    body: RigidBody;
+}
+declare function createPhysicsBodyComponent(body: RigidBody): PhysicsBodyComponent;
+
+/**
+ * Thruster-specific ECS Components
+ *
+ * These components are specific to the thruster movement system.
+ */
+interface ThrusterMovementComponent {
+    /** Linear thrust force in Newtons (or scaled units) */
+    linearThrust: number;
+    /** Angular thrust torque scalar */
+    angularThrust: number;
+    /** Optional linear damping override */
+    linearDamping?: number;
+    /** Optional angular damping override */
+    angularDamping?: number;
+}
+declare function createThrusterMovementComponent(linearThrust: number, angularThrust: number, options?: {
+    linearDamping?: number;
+    angularDamping?: number;
+}): ThrusterMovementComponent;
+interface ThrusterInputComponent {
+    /** Forward thrust intent: 0..1 */
+    thrust: number;
+    /** Rotation intent: -1..1 */
+    rotate: number;
+    /** World-space X thrust intent: -1..1 */
+    thrustX: number;
+    /** World-space Y thrust intent: -1..1 */
+    thrustY: number;
+}
+declare function createThrusterInputComponent(): ThrusterInputComponent;
+interface ThrusterStateComponent {
+    /** Whether the thruster is enabled */
+    enabled: boolean;
+    /** Current thrust after FSM/gating */
+    currentThrust: number;
+}
+declare function createThrusterStateComponent(): ThrusterStateComponent;
+
+/**
+ * ThrusterFSM
+ *
+ * State machine controller for thruster behavior.
+ * FSM does NOT touch physics or ThrusterMovementBehavior - it only writes ThrusterInputComponent.
+ */
+
+declare enum ThrusterState {
+    Idle = "idle",
+    Active = "active",
+    Boosting = "boosting",
+    Disabled = "disabled",
+    Docked = "docked"
+}
+declare enum ThrusterEvent {
+    Activate = "activate",
+    Deactivate = "deactivate",
+    Boost = "boost",
+    EndBoost = "endBoost",
+    Disable = "disable",
+    Enable = "enable",
+    Dock = "dock",
+    Undock = "undock"
+}
+interface ThrusterFSMContext {
+    input: ThrusterInputComponent;
+}
+interface PlayerInput {
+    thrust: number;
+    rotate: number;
+    thrustX?: number;
+    thrustY?: number;
+}
+declare class ThrusterFSM {
+    private ctx;
+    machine: SyncStateMachine<ThrusterState, ThrusterEvent, never>;
+    constructor(ctx: ThrusterFSMContext);
+    /**
+     * Get current state
+     */
+    getState(): ThrusterState;
+    /**
+     * Dispatch an event to transition state
+     */
+    dispatch(event: ThrusterEvent): void;
+    /**
+     * Update FSM state based on player input.
+     * Auto-transitions between Idle/Active to report current state.
+     * Does NOT modify input - just observes and reports.
+     */
+    update(playerInput: PlayerInput): void;
+}
+
+/**
+ * ThrusterMovementBehavior
+ *
+ * This is the heart of the thruster movement system - a pure, stateless force generator.
+ * Works identically for player, AI, and replay.
+ */
+
+/**
+ * Zylem-style Behavior interface
+ */
+interface Behavior {
+    update(dt: number): void;
+}
+/**
+ * Entity with thruster components
+ */
+interface ThrusterEntity {
+    physics: PhysicsBodyComponent;
+    thruster: ThrusterMovementComponent;
+    $thruster: ThrusterInputComponent;
+}
+/**
+ * ThrusterMovementBehavior - Force generator for thruster-equipped entities
+ *
+ * Responsibilities:
+ * - Query entities with PhysicsBody, ThrusterMovement, and ThrusterInput components
+ * - Apply velocities based on thrust input (2D mode)
+ * - Apply angular velocity based on rotation input
+ */
+declare class ThrusterMovementBehavior implements Behavior {
+    private world;
+    constructor(world: ZylemWorld);
+    /**
+     * Update a single thruster-enabled entity.
+     */
+    updateEntity(gameEntity: any, _dt: number): void;
+    update(dt: number): void;
+}
+
+/**
+ * Thruster behavior options (typed for entity.use() autocomplete)
+ */
+interface ThrusterBehaviorOptions {
+    /** Forward thrust force (default: 10) */
+    linearThrust: number;
+    /** Rotation torque (default: 5) */
+    angularThrust: number;
+    /** Optional linear damping override */
+    linearDamping?: number;
+}
+/**
+ * ThrusterBehavior - typed descriptor for thruster movement.
+ *
+ * Uses the existing ThrusterMovementBehavior under the hood.
+ *
+ * @example
+ * ```typescript
+ * import { ThrusterBehavior } from "@zylem/game-lib";
+ *
+ * const ship = createSprite({ ... });
+ * ship.use(ThrusterBehavior, { linearThrust: 15, angularThrust: 8 });
+ * ```
+ */
+declare const ThrusterBehavior: BehaviorDescriptor<ThrusterBehaviorOptions, Record<string, never>, ThrusterEntity>;
+
+export { type Behavior as B, type PhysicsBodyComponent as P, type ThrusterInputComponent as T, type TransformComponent as a, createPhysicsBodyComponent as b, createTransformComponent as c, type ThrusterMovementComponent as d, type ThrusterStateComponent as e, createThrusterMovementComponent as f, createThrusterInputComponent as g, createThrusterStateComponent as h, ThrusterState as i, ThrusterEvent as j, ThrusterFSM as k, type ThrusterFSMContext as l, type PlayerInput as m, ThrusterMovementBehavior as n, type ThrusterEntity as o, ThrusterBehavior as p, type ThrusterBehaviorOptions as q };

package/dist/world-DfgxoNMt.d.ts

@@ -0,0 +1,105 @@
+import { Vector3 } from 'three';
+import RAPIER__default, { World } from '@dimforge/rapier3d-compat';
+import { E as Entity } from './entity-Bq_eNEDI.js';
+import { I as GameEntity, U as UpdateContext } from './entity-vj-HTjzU.js';
+
+/**
+ * Interface for entities that handle collision events.
+ */
+interface CollisionHandlerDelegate {
+    handlePostCollision(params: any): boolean;
+    handleIntersectionEvent(params: any): void;
+}
+/**
+ * Physics world wrapper supporting two modes:
+ *
+ * - **Direct mode** (default): Rapier world lives on the main thread.
+ *   This is the original behavior with the Phase-1 fixed-timestep accumulator.
+ *
+ * - **Worker mode**: Physics runs in a Web Worker via {@link PhysicsProxy}.
+ *   Entity bodies are replaced with {@link PhysicsBodyHandle} instances that
+ *   cache transforms and queue write commands. Collision events are delivered
+ *   asynchronously (one frame latency).
+ */
+declare class ZylemWorld implements Entity<ZylemWorld> {
+    type: string;
+    /** Rapier world instance (null in worker mode). */
+    world: World;
+    collisionMap: Map<string, GameEntity<any>>;
+    collisionBehaviorMap: Map<string, GameEntity<any>>;
+    _removalMap: Map<string, GameEntity<any>>;
+    private activeCollisionPairs;
+    private currentCollisionTimeMs;
+    /** Fixed timestep in seconds used for each physics step. */
+    readonly fixedTimestep: number;
+    /** Unprocessed time carried over between frames. */
+    private accumulator;
+    /** Maximum number of physics steps allowed per frame to prevent spiral-of-death. */
+    private static readonly MAX_STEPS_PER_FRAME;
+    /**
+     * Interpolation alpha (0..1) representing the fraction of an unprocessed
+     * timestep remaining after the last physics step. Can be used to interpolate
+     * rendering transforms between the previous and current physics state.
+     */
+    interpolationAlpha: number;
+    /** When true, physics runs in a Web Worker via the proxy. */
+    readonly workerMode: boolean;
+    /** Physics worker proxy (only set in worker mode). */
+    private proxy;
+    /** Pending step promise (worker mode). */
+    private _pendingStep;
+    private readonly trackedDirectBodies;
+    static loadPhysics(gravity: Vector3): Promise<RAPIER__default.World>;
+    /**
+     * Initialize physics in worker mode. Returns a ZylemWorld that
+     * delegates all physics to a Web Worker.
+     *
+     * @param gravity World gravity.
+     * @param physicsRate Physics tick rate in Hz.
+     * @param workerUrl Optional URL to the worker script.
+     */
+    static loadPhysicsWorker(gravity: Vector3, physicsRate?: number, workerUrl?: URL): Promise<ZylemWorld>;
+    /**
+     * @param world The Rapier physics world instance (null in worker mode).
+     * @param physicsRate Physics update rate in Hz (default 60).
+     * @param useWorker Whether to use worker mode (default false).
+     */
+    constructor(world: World, physicsRate?: number, useWorker?: boolean);
+    addEntity(entity: any): void;
+    setForRemoval(entity: any): void;
+    destroyEntity(entity: GameEntity<any>): void;
+    setup(): void;
+    /**
+     * Advance the physics simulation.
+     *
+     * In direct mode, uses the fixed-timestep accumulator on the main thread.
+     * In worker mode, sends a step command and awaits the result.
+     */
+    update(params: UpdateContext<any>): void;
+    /**
+     * In worker mode, the step is async. Call this to await the
+     * pending step before reading transform data.
+     */
+    awaitStep(): Promise<void>;
+    private addEntityDirect;
+    private destroyEntityDirect;
+    private updateDirect;
+    private captureDirectBodyPreviousPoses;
+    private captureDirectBodyCurrentPoses;
+    private patchDirectBodyPoseTracking;
+    private addEntityWorker;
+    private destroyEntityWorker;
+    private updateWorker;
+    updatePostCollisionBehaviors(delta: number): void;
+    private processPendingRemovals;
+    private removeEntityFromTracking;
+    private pruneActiveCollisionPairs;
+    private collectCollisionPairsFromWorld;
+    private processCollisionPairs;
+    private dispatchCollisionPhase;
+    private dispatchIntersectionDelegates;
+    destroy(): void;
+    private clearEntityPhysicsState;
+}
+
+export { type CollisionHandlerDelegate as C, ZylemWorld as Z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zylem/game-lib",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "type": "module",
   "description": "A powerful and easy-to-use framework for creating simple 3D digital interactive applications using TypeScript.",
   "license": "MIT",
@@ -42,9 +42,49 @@
       "types": "./dist/actions.d.ts",
       "import": "./dist/actions.js"
     },
-    "./behaviors": {
-      "types": "./dist/behaviors.d.ts",
-      "import": "./dist/behaviors.js"
+    "./behavior/thruster": {
+      "types": "./dist/behavior/thruster.d.ts",
+      "import": "./dist/behavior/thruster.js"
+    },
+    "./behavior/top-down-movement": {
+      "types": "./dist/behavior/top-down-movement.d.ts",
+      "import": "./dist/behavior/top-down-movement.js"
+    },
+    "./behavior/shooter-2d": {
+      "types": "./dist/behavior/shooter-2d.d.ts",
+      "import": "./dist/behavior/shooter-2d.js"
+    },
+    "./behavior/screen-wrap": {
+      "types": "./dist/behavior/screen-wrap.d.ts",
+      "import": "./dist/behavior/screen-wrap.js"
+    },
+    "./behavior/screen-visibility": {
+      "types": "./dist/behavior/screen-visibility.d.ts",
+      "import": "./dist/behavior/screen-visibility.js"
+    },
+    "./behavior/world-boundary-2d": {
+      "types": "./dist/behavior/world-boundary-2d.d.ts",
+      "import": "./dist/behavior/world-boundary-2d.js"
+    },
+    "./behavior/world-boundary-3d": {
+      "types": "./dist/behavior/world-boundary-3d.d.ts",
+      "import": "./dist/behavior/world-boundary-3d.js"
+    },
+    "./behavior/ricochet-2d": {
+      "types": "./dist/behavior/ricochet-2d.d.ts",
+      "import": "./dist/behavior/ricochet-2d.js"
+    },
+    "./behavior/ricochet-3d": {
+      "types": "./dist/behavior/ricochet-3d.d.ts",
+      "import": "./dist/behavior/ricochet-3d.js"
+    },
+    "./behavior/jumper-2d": {
+      "types": "./dist/behavior/jumper-2d.d.ts",
+      "import": "./dist/behavior/jumper-2d.js"
+    },
+    "./behavior/platformer-3d": {
+      "types": "./dist/behavior/platformer-3d.d.ts",
+      "import": "./dist/behavior/platformer-3d.js"
     }
   },
   "keywords": [
@@ -65,14 +105,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "biome check .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --reporter=verbose",
-    "coverage": "vitest run --coverage"
-  },
   "dependencies": {
     "@dimforge/rapier3d-compat": "^0.11.2",
     "@sinclair/typebox": "^0.34.41",
@@ -106,5 +138,13 @@
     "typescript": "5.8.2",
     "vite-plugin-solid": "^2.11.8",
     "vitest": "^4.0.9"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --reporter=verbose",
+    "coverage": "vitest run --coverage"
   }
-}
+}