@zylem/game-lib 0.6.0 → 0.6.3

package/dist/thruster-DhRaJnoL.d.ts

@@ -0,0 +1,172 @@
+import { StateMachine } from 'typescript-fsm';
+import { Z as ZylemWorld } from './world-Be5m1XC1.js';
+import { RigidBody } from '@dimforge/rapier3d-compat';
+import { Vector3, Quaternion } from 'three';
+import { b as BehaviorDescriptor } from './behavior-descriptor-BWNWmIjv.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;
+}
+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;
+}
+declare class ThrusterFSM {
+    private ctx;
+    machine: StateMachine<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);
+    /**
+     * Query function - returns entities with required thruster components
+     */
+    private queryEntities;
+    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;
+}
+/**
+ * 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 TransformComponent as T, createPhysicsBodyComponent as a, type ThrusterMovementComponent as b, createTransformComponent as c, type ThrusterInputComponent 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-Be5m1XC1.d.ts

@@ -0,0 +1,31 @@
+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-BpbZqg19.js';
+
+/**
+ * Interface for entities that handle collision events.
+ */
+interface CollisionHandlerDelegate {
+    handlePostCollision(params: any): boolean;
+    handleIntersectionEvent(params: any): void;
+}
+declare class ZylemWorld implements Entity<ZylemWorld> {
+    type: string;
+    world: World;
+    collisionMap: Map<string, GameEntity<any>>;
+    collisionBehaviorMap: Map<string, GameEntity<any>>;
+    _removalMap: Map<string, GameEntity<any>>;
+    static loadPhysics(gravity: Vector3): Promise<RAPIER__default.World>;
+    constructor(world: World);
+    addEntity(entity: any): void;
+    setForRemoval(entity: any): void;
+    destroyEntity(entity: GameEntity<any>): void;
+    setup(): void;
+    update(params: UpdateContext<any>): void;
+    updatePostCollisionBehaviors(delta: number): void;
+    updateColliders(delta: number): void;
+    destroy(): void;
+}
+
+export { type CollisionHandlerDelegate as C, ZylemWorld as Z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zylem/game-lib",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "type": "module",
   "description": "A powerful and easy-to-use framework for creating simple 3D digital interactive applications using TypeScript.",
   "license": "MIT",
@@ -42,9 +42,25 @@
       "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/screen-wrap": {
+      "types": "./dist/behavior/screen-wrap.d.ts",
+      "import": "./dist/behavior/screen-wrap.js"
+    },
+    "./behavior/world-boundary-2d": {
+      "types": "./dist/behavior/world-boundary-2d.d.ts",
+      "import": "./dist/behavior/world-boundary-2d.js"
+    },
+    "./behavior/ricochet-2d": {
+      "types": "./dist/behavior/ricochet-2d.d.ts",
+      "import": "./dist/behavior/ricochet-2d.js"
+    },
+    "./behavior/platformer-3d": {
+      "types": "./dist/behavior/platformer-3d.d.ts",
+      "import": "./dist/behavior/platformer-3d.js"
     }
   },
   "keywords": [
@@ -76,6 +92,7 @@
     "nanoid": "^5.1.5",
     "stats.js": "^0.17.0",
     "three": "^0.180.0",
+    "typescript-fsm": "^1.6.0",
     "valtio": "^2.1.7"
   },
   "peerDependencies": {

package/dist/behaviors.d.ts

@@ -1,106 +0,0 @@
-import { G as GameEntity, m as CollisionContext, U as UpdateContext, B as BehaviorCallbackType } from './entity-COvRtFNG.js';
-import { M as MoveableEntity } from './moveable-B_vyA6cw.js';
-import { Vector } from '@dimforge/rapier3d-compat';
-import 'three';
-import 'bitecs';
-
-/**
- * A branded bitmask representing a set of collision types.
- */
-type CollisionMask = number & {
-    readonly __brand: "CollisionMask";
-};
-type NameSelector = string | string[] | RegExp;
-type CollisionSelector = {
-    name: NameSelector;
-} | {
-    mask: CollisionMask | RegExp;
-} | {
-    test: (other: GameEntity<any>) => boolean;
-};
-
-/**
- * Behavior for ricocheting an entity off other objects in 2D
- */
-declare function ricochet2DCollision(options?: Partial<Ricochet2DCollisionOptions>, callback?: Ricochet2DCollisionCallback): {
-    type: 'collision';
-    handler: (ctx: CollisionContext<MoveableEntity, GameEntity<any>>) => void;
-};
-
-interface RicochetEvent extends Partial<UpdateContext<MoveableEntity>> {
-    boundary?: 'top' | 'bottom' | 'left' | 'right';
-    position: Vector;
-    velocityBefore: Vector;
-    velocityAfter: Vector;
-}
-interface RicochetCollisionEvent extends CollisionContext<MoveableEntity, GameEntity<any>> {
-    position: Vector;
-}
-interface Ricochet2DInBoundsOptions {
-    restitution?: number;
-    minSpeed?: number;
-    maxSpeed?: number;
-    boundaries: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-    };
-    separation?: number;
-}
-interface Ricochet2DCollisionOptions {
-    restitution?: number;
-    minSpeed?: number;
-    maxSpeed?: number;
-    separation?: number;
-    collisionWith?: CollisionSelector;
-    /**
-     * Choose between simple axis inversion or angled (paddle-style) reflection.
-     * Defaults to 'angled'.
-     */
-    reflectionMode?: 'simple' | 'angled';
-}
-type Ricochet2DCallback = (event: RicochetEvent) => void;
-type Ricochet2DCollisionCallback = (event: RicochetCollisionEvent) => void;
-
-/**
- * Behavior for ricocheting an entity within fixed 2D boundaries
- */
-declare function ricochet2DInBounds(options?: Partial<Ricochet2DInBoundsOptions>, callback?: Ricochet2DCallback): {
-    type: BehaviorCallbackType;
-    handler: (ctx: UpdateContext<MoveableEntity>) => void;
-};
-
-interface BoundaryEvent {
-    me: MoveableEntity;
-    boundary: BoundaryHits;
-    position: Vector;
-    updateContext: UpdateContext<MoveableEntity>;
-}
-interface BoundaryOptions {
-    boundaries: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-    };
-    onBoundary?: (event: BoundaryEvent) => void;
-    stopMovement?: boolean;
-}
-/**
- * Checks if the entity has hit a boundary and stops its movement if it has
- *
- * @param options Configuration options for the boundary behavior
- * @param options.boundaries The boundaries of the stage
- * @param options.onBoundary A callback function that is called when the entity hits a boundary
- * @param options.stopMovement Whether to stop the entity's movement when it hits a boundary
- * @returns A behavior callback with type 'update' and a handler function
- */
-declare function boundary2d(options?: Partial<BoundaryOptions>): {
-    type: BehaviorCallbackType;
-    handler: (ctx: UpdateContext<MoveableEntity>) => void;
-};
-type BoundaryHit = 'top' | 'bottom' | 'left' | 'right';
-type BoundaryHits = Record<BoundaryHit, boolean>;
-
-export { boundary2d, ricochet2DCollision, ricochet2DInBounds };