@zylem/behaviors 0.2.0

package/dist/platformer-3d.d.ts

@@ -0,0 +1,347 @@
+import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
+import { a as BehaviorDescriptor } from './behavior-system-DYbx-x_-.js';
+import 'typescript-fsm';
+
+/**
+ * Platformer 3D ECS Components
+ *
+ * Components for 3D platformer movement system including walking, running,
+ * jumping with multi-jump support, and falling/landing states.
+ */
+interface Platformer3DMovementComponent {
+    /** Base walking speed */
+    walkSpeed: number;
+    /** Sprint/run speed */
+    runSpeed: number;
+    /** Initial jump force/velocity */
+    jumpForce: number;
+    /** Maximum number of jumps (1 = single jump, 2 = double jump, etc.) */
+    maxJumps: number;
+    /** Gravity force (optional override) */
+    gravity: number;
+    /** Ray length for ground detection */
+    groundRayLength: number;
+    /** Coyote time in seconds (grace period after leaving ground) */
+    coyoteTime: number;
+    /** Jump buffer time in seconds (queue jump input before landing) */
+    jumpBufferTime: number;
+    /** Velocity multiplier when releasing jump button early (0-1) */
+    jumpCutMultiplier: number;
+    /** Time in seconds before multi-jump becomes available (0 = after button release) */
+    multiJumpWindowTime: number;
+    /** Enable ground-ray debug visualization */
+    debugGroundProbe: boolean;
+}
+declare function createPlatformer3DMovementComponent(options?: Partial<Platformer3DMovementComponent>): Platformer3DMovementComponent;
+interface Platformer3DInputComponent {
+    /** Horizontal movement input (-1 to 1) */
+    moveX: number;
+    /** Forward/backward movement input (-1 to 1) */
+    moveZ: number;
+    /** Jump button pressed */
+    jump: boolean;
+    /** Run/sprint button held */
+    run: boolean;
+}
+declare function createPlatformer3DInputComponent(): Platformer3DInputComponent;
+interface Platformer3DStateComponent {
+    /** Is the entity on the ground */
+    grounded: boolean;
+    /** Is currently in a jump arc */
+    jumping: boolean;
+    /** Is falling (not jumping) */
+    falling: boolean;
+    /** Current jump count (for multi-jump) */
+    jumpCount: number;
+    /** Y position when jump started */
+    jumpStartHeight: number;
+    /** Current movement speed being applied */
+    currentSpeed: number;
+    /** Last known ground Y position */
+    lastGroundedY: number;
+    /** Was jump button pressed last frame (for edge detection) */
+    jumpPressedLastFrame: boolean;
+    /** Is currently colliding with ground (from physics collision callback) */
+    collisionGrounded: boolean;
+    /** Timestamp of last ground collision */
+    groundedCollisionTime: number;
+    /** Time in seconds since last grounded */
+    timeSinceGrounded: number;
+    /** Is a jump allowed due to buffer? */
+    jumpBuffered: boolean;
+    /** Time remaining in jump buffer */
+    jumpBufferTimer: number;
+    /** Is jump button currently held */
+    jumpHeld: boolean;
+    /** Has the jump cut been applied for this jump? */
+    jumpCutApplied: boolean;
+    /** Has jump button been released since last jump (required for multi-jump) */
+    jumpReleasedSinceLastJump: boolean;
+    /** Time since current jump started (for multi-jump window) */
+    timeSinceJump: number;
+    /** True for the single frame on which a jump impulse was applied; prevents gravity from clobbering jump velocity. */
+    jumpedThisFrame: boolean;
+    /** Remaining seconds of jump-cut velocity ramp; while > 0, velocity.y lerps toward velocity.y * jumpCutMultiplier. */
+    jumpCutRampTimer: number;
+    /** Remaining seconds of grounded-hysteresis grace (keeps `grounded` true briefly after ground probe misses, to absorb edge/ray flicker). */
+    groundedGraceTimer: number;
+}
+declare function createPlatformer3DStateComponent(): Platformer3DStateComponent;
+
+/**
+ * Platformer 3D Finite State Machine
+ *
+ * Manages state transitions for 3D platformer movement:
+ * - Idle: Standing still on ground
+ * - Walking: Moving on ground (slow)
+ * - Running: Moving on ground (fast)
+ * - Jumping: Ascending from jump
+ * - Falling: Descending (gravity)
+ * - Landing: Just touched ground
+ */
+
+/**
+ * Simplified Collision Context interface
+ */
+interface PlatformerCollisionContext {
+    contact: {
+        normal: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+    };
+}
+/**
+ * Platformer states
+ */
+declare enum Platformer3DState {
+    Idle = "idle",
+    Walking = "walking",
+    Running = "running",
+    Jumping = "jumping",
+    Falling = "falling",
+    Landing = "landing"
+}
+/**
+ * Events that trigger state transitions
+ */
+declare enum Platformer3DEvent {
+    Walk = "walk",
+    Run = "run",
+    Jump = "jump",
+    Fall = "fall",
+    Land = "land",
+    Stop = "stop"
+}
+/**
+ * Context for the FSM
+ */
+interface Platformer3DContext {
+    input: Platformer3DInputComponent;
+    state: Platformer3DStateComponent;
+}
+/**
+ * Platformer 3D FSM
+ */
+declare class Platformer3DFSM {
+    private ctx;
+    machine: SyncStateMachine<Platformer3DState, Platformer3DEvent, never>;
+    constructor(ctx: Platformer3DContext);
+    /**
+     * Get the current state
+     */
+    getState(): Platformer3DState;
+    /**
+     * Dispatch an event to the FSM
+     */
+    dispatch(event: Platformer3DEvent): void;
+    /**
+     * Check if grounded
+     */
+    isGrounded(): boolean;
+    /**
+     * Get current jump count from context
+     */
+    getJumpCount(): number;
+    /**
+     * Handle collision event to update ground state
+     */
+    handleCollision(ctx: PlatformerCollisionContext): void;
+    /**
+     * Update FSM based on current state
+     */
+    update(input: Platformer3DInputComponent, state: Platformer3DStateComponent): void;
+}
+
+/**
+ * Platformer 3D Behavior System
+ *
+ * Handles 3D platformer physics including:
+ * - Contact-based ground detection (uses the actual capsule collider — no
+ *   raycast/shapecast probe). The bottom of the body's collider is the
+ *   single source of truth for "is grounded".
+ * - Horizontal movement (walk/run)
+ * - Jumping with multi-jump support
+ * - Gravity application (Rapier's internal gravity is disabled per-body so
+ *   `movement.gravity` is the only fall acceleration — previously the two
+ *   stacked, doubling the airborne fall rate).
+ * - State synchronization with FSM
+ */
+
+/**
+ * Entity with platformer components
+ */
+interface Platformer3DEntity {
+    uuid: string;
+    body: any;
+    platformer: Platformer3DMovementComponent;
+    $platformer: Platformer3DInputComponent;
+    platformerState: Platformer3DStateComponent;
+    transformStore?: any;
+}
+/**
+ * Platformer 3D Movement Behavior
+ *
+ * Core physics system for 3D platformer movement.
+ *
+ * Ground detection uses Rapier's narrow-phase contacts on the entity's
+ * collider (`world.contactsWith` + `contactPair`). This eliminates the old
+ * shape/ray probe and aligns "grounded" with the same surface the body
+ * physically rests on, which removes the jitter that happened on heightmap
+ * terrain (the probe and the contact resolver could disagree by a frame).
+ */
+declare class Platformer3DBehavior$1 {
+    private world;
+    private scene;
+    /**
+     * Tracks entities whose Rapier `gravityScale` has been zeroed so that
+     * `applyGravity` is the sole writer of vertical velocity. We do this
+     * lazily on the first update because the body isn't always available at
+     * construction time.
+     */
+    private gravityConfiguredUUIDs;
+    constructor(world: any, scene: any);
+    /**
+     * Detect "grounded" using the actual capsule collider's contact pairs.
+     *
+     * A contact is treated as ground when its solver point lies below the
+     * body center (i.e., it sits on the bottom hemisphere/cylinder). We
+     * deliberately don't filter by normal direction: the contact point's
+     * position alone is robust against the various normal-flip conventions
+     * Rapier uses for `flipped` manifolds and against rolling-bottom edges
+     * on heightmap terrain.
+     */
+    private detectGroundedFromContacts;
+    /**
+     * One-time per-entity physics setup: take over gravity from Rapier's
+     * world so that `applyGravity` controls the entire airborne fall curve.
+     * Without this, gravity was effectively doubled (Rapier's world gravity
+     * + this behavior's explicit gravity were both pulling the body down).
+     */
+    private ensurePhysicsConfigured;
+    /**
+     * Apply horizontal movement based on input.
+     *
+     * Only writes X/Z axes — Y is left untouched so Rapier's contact resolution
+     * can damp vertical motion correctly while grounded. Jump and gravity are
+     * the sole writers of Y velocity (see handleJump / applyGravity).
+     */
+    private applyMovement;
+    /**
+     * Handle jump logic with multi-jump, coyote time, buffering, and jump-cut ramp.
+     */
+    private handleJump;
+    /**
+     * Apply gravity when not grounded.
+     *
+     * Skipped on the single frame immediately after a jump impulse is applied
+     * (tracked via `state.jumpedThisFrame`) so gravity never overwrites a
+     * just-applied jump velocity. The flag is cleared here regardless, so it
+     * only suppresses exactly one gravity step — independent of frame rate.
+     */
+    private applyGravity;
+    /**
+     * Update entity state based on physics.
+     *
+     * Grounded is determined purely by Rapier's contact pairs on the entity's
+     * collider. This removes a whole class of slope/heightmap jitter caused
+     * by the previous shape probe disagreeing with the contact resolver — the
+     * probe could report grounded while a contact impulse had just nudged the
+     * body off the ground, producing visible micro-bouncing.
+     *
+     * While grounded, vertical velocity is held at 0 each frame. This stops
+     * residual upward kicks from slope-contact resolution from accumulating
+     * across frames (which previously caused the character to "ride up"
+     * slopes and lose contact briefly, then fall back, then re-contact, in a
+     * tight oscillation).
+     */
+    private updateState;
+    /**
+     * Update one platformer entity. Invoked per linked entity by the
+     * Platformer3DBehaviorSystem adapter.
+     */
+    updateEntity(entity: any, delta: number): void;
+    destroy(): void;
+}
+
+/**
+ * Platformer behavior options (typed for entity.use() autocomplete)
+ */
+interface Platformer3DBehaviorOptions {
+    /** Base walking speed (default: 12) */
+    walkSpeed?: number;
+    /** Sprint/run speed (default: 24) */
+    runSpeed?: number;
+    /** Initial jump force (default: 12) */
+    jumpForce?: number;
+    /** Maximum number of jumps (default: 1) */
+    maxJumps?: number;
+    /** Gravity force (default: 9.82) */
+    gravity?: number;
+    /** Ray length for ground detection (default: 1.0) */
+    groundRayLength?: number;
+    /** Enable debug visualization for ground probe rays (default: false) */
+    debugGroundProbe?: boolean;
+}
+/**
+ * Platformer3DBehavior - typed descriptor for 3D platformer movement
+ *
+ * Provides complete 3D platformer physics including:
+ * - Walking and running
+ * - Jumping with multi-jump support
+ * - Gravity and falling
+ * - Ground detection
+ *
+ * @example
+ * ```typescript
+ * import { Platformer3DBehavior } from "@zylem/game-lib/behavior";
+ *
+ * const player = await playgroundActor('player');
+ * const platformer = player.use(Platformer3DBehavior, {
+ *   walkSpeed: 12,
+ *   runSpeed: 24,
+ *   jumpForce: 12,
+ *   maxJumps: 2, // Double jump!
+ * });
+ *
+ * // In update loop
+ * player.onUpdate(({ inputs }) => {
+ *   player.$platformer.moveX = inputs.p1.axes.Horizontal.value;
+ *   player.$platformer.moveZ = inputs.p1.axes.Vertical.value;
+ *   player.$platformer.jump = inputs.p1.buttons.A.held > 0;
+ *   player.$platformer.run = inputs.p1.shoulders.LTrigger.held > 0;
+ *
+ *   const state = platformer.getState();
+ *   const grounded = platformer.isGrounded();
+ * });
+ * ```
+ */
+declare const Platformer3DBehavior: BehaviorDescriptor<Platformer3DBehaviorOptions, {
+    getState: () => Platformer3DState;
+    isGrounded: () => boolean;
+    getJumpCount: () => number;
+    onPlatformCollision: (ctx: PlatformerCollisionContext) => void;
+}, Platformer3DEntity>;
+
+export { Platformer3DBehavior, type Platformer3DBehaviorOptions, type Platformer3DContext, type Platformer3DEntity, Platformer3DEvent, Platformer3DFSM, type Platformer3DInputComponent, Platformer3DBehavior$1 as Platformer3DMovementBehavior, type Platformer3DMovementComponent, Platformer3DState, type Platformer3DStateComponent, type PlatformerCollisionContext, createPlatformer3DInputComponent, createPlatformer3DMovementComponent, createPlatformer3DStateComponent };

package/dist/platformer-3d.js

@@ -0,0 +1,23 @@
+import {
+  Platformer3DBehavior,
+  Platformer3DBehavior2,
+  Platformer3DEvent,
+  Platformer3DFSM,
+  Platformer3DState,
+  createPlatformer3DInputComponent,
+  createPlatformer3DMovementComponent,
+  createPlatformer3DStateComponent
+} from "./chunk-JAN34G6S.js";
+import "./chunk-4URF65BR.js";
+import "./chunk-EZNCCO4L.js";
+export {
+  Platformer3DBehavior2 as Platformer3DBehavior,
+  Platformer3DEvent,
+  Platformer3DFSM,
+  Platformer3DBehavior as Platformer3DMovementBehavior,
+  Platformer3DState,
+  createPlatformer3DInputComponent,
+  createPlatformer3DMovementComponent,
+  createPlatformer3DStateComponent
+};
+//# sourceMappingURL=platformer-3d.js.map

package/dist/platformer-3d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ricochet-2d.d.ts

@@ -0,0 +1,274 @@
+import { B as BaseEntityInterface } from './entity-types-CmtQ-IBp.js';
+import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
+import { a as BehaviorDescriptor } from './behavior-system-DYbx-x_-.js';
+import 'three';
+import '@dimforge/rapier3d-compat';
+import 'typescript-fsm';
+
+/**
+ * Ricochet2DFSM
+ *
+ * FSM + extended state to track ricochet events and results.
+ * The FSM state tracks whether a ricochet is currently occurring.
+ */
+
+interface Ricochet2DResult {
+    /** The reflected velocity vector */
+    velocity: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    /** The resulting speed after reflection */
+    speed: number;
+    /** The collision normal used for reflection */
+    normal: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+}
+interface Ricochet2DCollisionContext {
+    entity?: BaseEntityInterface;
+    otherEntity?: BaseEntityInterface;
+    /** Current velocity of the entity (optional if entity is provided) */
+    selfVelocity?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    /** Contact information from the collision */
+    contact: {
+        /** The collision normal */
+        normal?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+        /**
+         * Optional position where the collision occurred.
+         * If provided, used for precise offset calculation.
+         */
+        position?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+    };
+    /**
+     * Optional position of the entity that owns this behavior.
+     * Used with contact.position for offset calculations.
+     */
+    selfPosition?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    /**
+     * Optional position of the other entity in the collision.
+     * Used for paddle-style deflection: offset = (contactY - otherY) / halfHeight.
+     */
+    otherPosition?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    /**
+     * Optional size of the other entity (e.g., paddle size).
+     * If provided, used to normalize the offset based on the collision face.
+     */
+    otherSize?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+}
+declare enum Ricochet2DState {
+    Idle = "idle",
+    Ricocheting = "ricocheting"
+}
+declare enum Ricochet2DEvent {
+    StartRicochet = "start-ricochet",
+    EndRicochet = "end-ricochet"
+}
+/**
+ * Callback type for ricochet event listeners.
+ */
+type RicochetCallback = (result: Ricochet2DResult) => void;
+/**
+ * FSM wrapper with extended state (lastResult).
+ * Systems or consumers call `computeRicochet(...)` when a collision occurs.
+ */
+declare class Ricochet2DFSM {
+    readonly machine: SyncStateMachine<Ricochet2DState, Ricochet2DEvent, never>;
+    private lastResult;
+    private lastUpdatedAtMs;
+    private currentTimeMs;
+    private listeners;
+    constructor();
+    /**
+     * Add a listener for ricochet events.
+     * @returns Unsubscribe function
+     */
+    addListener(callback: RicochetCallback): () => void;
+    /**
+     * Emit result to all listeners.
+     */
+    private emitToListeners;
+    getState(): Ricochet2DState;
+    /**
+     * Returns the last computed ricochet result, or null if none.
+     */
+    getLastResult(): Ricochet2DResult | null;
+    /**
+     * Best-effort timestamp (ms) of the last computation.
+     */
+    getLastUpdatedAtMs(): number | null;
+    /**
+     * Set current game time (called by system each frame).
+     * Used for cooldown calculations.
+     */
+    setCurrentTimeMs(timeMs: number): void;
+    /**
+     * Check if ricochet is on cooldown (to prevent rapid duplicate applications).
+     * @param cooldownMs Cooldown duration in milliseconds (default: 50ms)
+     */
+    isOnCooldown(cooldownMs?: number): boolean;
+    /**
+     * Reset cooldown state (e.g., on entity respawn).
+     */
+    resetCooldown(): void;
+    /**
+     * Compute a ricochet result from collision context.
+     * Returns the result for the consumer to apply, or null if invalid input.
+     */
+    computeRicochet(ctx: Ricochet2DCollisionContext, options?: {
+        minSpeed?: number;
+        maxSpeed?: number;
+        speedMultiplier?: number;
+        reflectionMode?: 'simple' | 'angled';
+        maxAngleDeg?: number;
+    }): Ricochet2DResult | null;
+    /**
+     * Extract velocity, position, and size data from entities or context.
+     */
+    private extractDataFromEntities;
+    /**
+     * Compute collision normal from entity positions using AABB heuristic.
+     */
+    private computeNormalFromPositions;
+    /**
+     * Compute basic reflection using the formula: v' = v - 2(v·n)n
+     */
+    private computeBasicReflection;
+    /**
+     * Compute angled deflection for paddle-style reflections.
+     */
+    private computeAngledDeflection;
+    /**
+     * Compute hit offset for angled deflection (-1 to 1).
+     */
+    private computeHitOffset;
+    /**
+     * Apply speed constraints to the reflected velocity.
+     */
+    private applySpeedClamp;
+    /**
+     * Clear the ricochet state (call after consumer has applied the result).
+     */
+    clearRicochet(): void;
+    private dispatch;
+}
+
+interface Ricochet2DOptions {
+    /**
+     * Minimum speed after reflection.
+     * Default: 2
+     */
+    minSpeed: number;
+    /**
+     * Maximum speed after reflection.
+     * Default: 20
+     */
+    maxSpeed: number;
+    /**
+     * Speed multiplier applied during angled reflection.
+     * Default: 1.05
+     */
+    speedMultiplier: number;
+    /**
+     * Reflection mode:
+     * - 'simple': Basic axis inversion
+     * - 'angled': Paddle-style deflection based on contact point
+     * Default: 'angled'
+     */
+    reflectionMode: 'simple' | 'angled';
+    /**
+     * Maximum deflection angle in degrees for angled mode.
+     * Default: 60
+     */
+    maxAngleDeg: number;
+}
+/**
+ * Handle methods provided by Ricochet2DBehavior
+ */
+interface Ricochet2DHandle {
+    /**
+     * Compute a ricochet/reflection result from collision context.
+     * Returns the result for the consumer to apply, or null if invalid input.
+     *
+     * @param ctx - Collision context with selfVelocity and contact normal
+     * @returns Ricochet result with velocity, speed, and normal, or null
+     */
+    getRicochet(ctx: Ricochet2DCollisionContext): Ricochet2DResult | null;
+    /**
+     * Compute ricochet and apply velocity directly via transformStore.
+     * Emits to onRicochet listeners if successful.
+     *
+     * @param ctx - Collision context with entity and contact normal
+     * @returns true if ricochet was computed and applied, false otherwise
+     */
+    applyRicochet(ctx: Ricochet2DCollisionContext): boolean;
+    /**
+     * Get the last computed ricochet result, or null if none.
+     */
+    getLastResult(): Ricochet2DResult | null;
+    /**
+     * Register a listener for ricochet events.
+     * Called whenever a ricochet is computed (from getRicochet or applyRicochet).
+     *
+     * @param callback - Function to call with ricochet result
+     * @returns Unsubscribe function
+     */
+    onRicochet(callback: RicochetCallback): () => void;
+}
+/**
+ * Ricochet2DBehavior
+ *
+ * @example
+ * ```ts
+ * import { Ricochet2DBehavior } from "@zylem/game-lib/behavior";
+ *
+ * const ball = createSphere({ ... });
+ * const ricochet = ball.use(Ricochet2DBehavior, {
+ *   minSpeed: 3,
+ *   maxSpeed: 15,
+ *   reflectionMode: 'angled',
+ * });
+ *
+ * ball.onCollision(({ entity, other }) => {
+ *   const velocity = entity.body.linvel();
+ *   const result = ricochet.getRicochet({
+ *     selfVelocity: velocity,
+ *     contact: { normal: { x: 1, y: 0 } }, // from collision data
+ *   });
+ *
+ *   if (result) {
+ *     entity.body.setLinvel(result.velocity, true);
+ *   }
+ * });
+ * ```
+ */
+declare const Ricochet2DBehavior: BehaviorDescriptor<Ricochet2DOptions, Ricochet2DHandle, unknown>;
+
+export { Ricochet2DBehavior, type Ricochet2DCollisionContext, Ricochet2DEvent, Ricochet2DFSM, type Ricochet2DHandle, type Ricochet2DOptions, type Ricochet2DResult, Ricochet2DState, type RicochetCallback };

package/dist/ricochet-2d.js

@@ -0,0 +1,16 @@
+import {
+  Ricochet2DBehavior,
+  Ricochet2DEvent,
+  Ricochet2DFSM,
+  Ricochet2DState
+} from "./chunk-KOZUNIIE.js";
+import "./chunk-Y6UJOUE5.js";
+import "./chunk-4URF65BR.js";
+import "./chunk-EZNCCO4L.js";
+export {
+  Ricochet2DBehavior,
+  Ricochet2DEvent,
+  Ricochet2DFSM,
+  Ricochet2DState
+};
+//# sourceMappingURL=ricochet-2d.js.map

package/dist/ricochet-2d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}