@zylem/behaviors 0.3.0 → 0.4.0

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

@@ -1,7 +1,8 @@
 import { J as JumpConfig3D, b as JumpInput3D, a as JumpContext3D, c as JumpState3D } from './components--hjBMTnz.js';
 export { V as Vec3Like, d as createJumpConfig3D, e as createJumpInput3D, f as createJumpState3D } from './components--hjBMTnz.js';
 import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
-import { a as BehaviorDescriptor } from './behavior-system-DYbx-x_-.js';
+import * as _dimforge_rapier3d_compat from '@dimforge/rapier3d-compat';
+import { a as BehaviorDescriptor, T as TransformState } from './behavior-system-DSNek0W9.js';
 import 'typescript-fsm';
 
 /**
@@ -15,7 +16,7 @@ import 'typescript-fsm';
  * is configured; otherwise the movement controller owns X/Z.
  */
 
-declare class Jumper3DBehavior {
+declare class Jumper3DSystem {
     /**
      * Advance the jump system by one frame.
      *
@@ -116,26 +117,26 @@ interface Jumper3DBehaviorOptions {
 }
 interface Jumper3DEntity {
     uuid: string;
-    body: any;
-    transformStore: any;
+    body: _dimforge_rapier3d_compat.RigidBody | null;
+    transformStore: TransformState;
     jumper: JumpConfig3D;
     $jumper: JumpInput3D;
     jumperState: JumpState3D;
 }
 /**
- * Jumper3D — composable 3D jump behavior.
+ * Jumper3DBehavior — composable 3D jump behavior.
  *
  * Provides height-based jumping, multi-jump, coyote time, jump buffering,
  * variable jump height, configurable fall gravity, and optional air control.
  *
- * Designed to compose with any movement controller (e.g. FirstPersonController)
- * — the controller writes X/Z velocity and Jumper3D writes Y velocity.
+ * Designed to compose with any movement controller (e.g. FirstPersonBehavior)
+ * — the controller writes X/Z velocity and Jumper3DBehavior writes Y velocity.
  *
  * @example
  * ```typescript
- * import { Jumper3D } from "@zylem/game-lib/behavior";
+ * import { Jumper3DBehavior } from "@zylem/game-lib/behavior";
  *
- * const jumper = player.use(Jumper3D, {
+ * const jumper = player.use(Jumper3DBehavior, {
  *   jumpHeight: 2.5,
  *   gravity: 20,
  *   maxJumps: 2,
@@ -154,11 +155,11 @@ interface Jumper3DEntity {
  * });
  * ```
  */
-declare const Jumper3D: BehaviorDescriptor<Jumper3DBehaviorOptions, {
+declare const Jumper3DBehavior: BehaviorDescriptor<Jumper3DBehaviorOptions, {
     getState: () => Jumper3DState;
     isJumping: () => boolean;
     getJumpsUsed: () => number;
     getJumpsRemaining: () => number;
 }, Jumper3DEntity>;
 
-export { JumpConfig3D, JumpContext3D, JumpInput3D, JumpState3D, Jumper3D, Jumper3DBehavior, type Jumper3DBehaviorOptions, type Jumper3DEntity, Jumper3DEvent, Jumper3DFSM, Jumper3DState, JumperTickEvent, type JumperTickResult };
+export { JumpConfig3D, JumpContext3D, JumpInput3D, JumpState3D, Jumper3DBehavior, type Jumper3DBehaviorOptions, type Jumper3DEntity, Jumper3DEvent, Jumper3DFSM, Jumper3DState, Jumper3DSystem, JumperTickEvent, type JumperTickResult };

package/dist/jumper-3d.js

@@ -1,28 +1,29 @@
 import {
-  Jumper3D,
   Jumper3DBehavior,
   Jumper3DEvent,
   Jumper3DFSM,
   Jumper3DState,
+  Jumper3DSystem,
   JumperTickEvent
-} from "./chunk-FOOM42MK.js";
+} from "./chunk-RONH2KDI.js";
 import {
   createJumpConfig3D,
   createJumpInput3D,
   createJumpState3D
-} from "./chunk-F7E23E26.js";
-import "./chunk-UFHYR2LV.js";
-import "./chunk-RQWWUML4.js";
-import "./chunk-RER2IDPW.js";
-import "./chunk-YDLO5M7S.js";
+} from "./chunk-4WH2ZN7P.js";
+import "./chunk-JXMF4NUI.js";
+import "./chunk-OTLSUYQQ.js";
+import "./chunk-4URF65BR.js";
+import "./chunk-EZNCCO4L.js";
 export {
-  Jumper3D,
   Jumper3DBehavior,
   Jumper3DEvent,
   Jumper3DFSM,
   Jumper3DState,
+  Jumper3DSystem,
   JumperTickEvent,
   createJumpConfig3D,
   createJumpInput3D,
   createJumpState3D
 };
+//# sourceMappingURL=jumper-3d.js.map

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

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

package/dist/{moveable-BCRpjAQb.d.ts → moveable-BLTHO7Jq.d.ts}

@@ -1,82 +1,6 @@
 import { Vector3 } from 'three';
 import { RigidBody, Vector } from '@dimforge/rapier3d-compat';
-
-type VelocityIntentMode = 'replace' | 'add';
-interface VelocityIntent {
-    x?: number;
-    y?: number;
-    z?: number;
-    mode: VelocityIntentMode;
-    priority?: number;
-}
-/**
- * Transform state managed by Valtio for batched physics updates.
- *
- * This store accumulates transformation intents during the frame,
- * then applies them all at once after onUpdate() callbacks complete.
- *
- * Design decisions:
- * - Position: Accumulated deltas (additive)
- * - Rotation: Last value wins (replacement)
- * - Velocity: Accumulated deltas (additive)
- * - Angular velocity: Accumulated deltas (additive)
- */
-interface TransformState {
-    /** Position deltas to be applied (accumulated) */
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Rotation quaternion (last value wins) */
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-        w: number;
-    };
-    /** Linear velocity (accumulated) */
-    velocity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Angular velocity (accumulated) */
-    angularVelocity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Per-source velocity intents composed once per frame */
-    velocityChannels: Record<string, VelocityIntent>;
-    /** Dirty flags to track what needs to be applied */
-    dirty: {
-        position: boolean;
-        rotation: boolean;
-        /** @deprecated Use per-axis velocityX/Y/Z flags for new code */
-        velocity: boolean;
-        velocityX: boolean;
-        velocityY: boolean;
-        velocityZ: boolean;
-        velocityChannels: boolean;
-        angularVelocity: boolean;
-    };
-}
-/**
- * Create a new transform store with optional initial values.
- * The store is a Valtio proxy, making it reactive for debugging/visualization.
- *
- * @param initial Optional initial state values
- * @returns Reactive transform state
- */
-declare function createTransformStore(initial?: Partial<TransformState>): TransformState;
-/**
- * Reset a transform store to its initial clean state.
- * Called after applying changes to prepare for the next frame.
- *
- * @param store The transform store to reset
- */
-declare function resetTransformStore(store: TransformState): void;
+import { T as TransformState } from './behavior-system-DSNek0W9.js';
 
 interface EntityWithBody {
     body: RigidBody | null;
@@ -173,4 +97,4 @@ interface MoveableEntity extends EntityWithBody {
  */
 declare function makeMoveable<T extends EntityWithBody>(entity: T): T & MoveableEntity;
 
-export { type EntityWithBody as E, type MoveableEntity as M, type TransformState as T, type VelocityIntent as V, type VelocityIntentMode as a, getVelocity as b, createTransformStore as c, move as d, moveForwardXY as e, moveX as f, getPosition as g, moveXY as h, moveXZ as i, moveY as j, moveZ as k, resetVelocity as l, makeMoveable as m, setPositionX as n, setPositionY as o, setPositionZ as p, wrapAroundXY as q, resetTransformStore as r, setPosition as s, wrapAround3D as w };
+export { type EntityWithBody as E, type MoveableEntity as M, getVelocity as a, move as b, moveForwardXY as c, moveX as d, moveXY as e, moveXZ as f, getPosition as g, moveY as h, moveZ as i, setPositionX as j, setPositionY as k, setPositionZ as l, makeMoveable as m, wrapAroundXY as n, resetVelocity as r, setPosition as s, wrapAround3D as w };

package/dist/particle-emitter/presets.js

@@ -4,7 +4,7 @@ import {
   gasPresets,
   magicPresets,
   waterPresets
-} from "../chunk-WSKD7GY3.js";
+} from "../chunk-7JJEIADR.js";
 export {
   electricityPresets,
   firePresets,
@@ -12,3 +12,4 @@ export {
   magicPresets,
   waterPresets
 };
+//# sourceMappingURL=presets.js.map

package/dist/particle-emitter/presets.js.map

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

package/dist/particle-emitter.d.ts

@@ -1,4 +1,4 @@
-import { a as BehaviorDescriptor } from './behavior-system-DYbx-x_-.js';
+import { a as BehaviorDescriptor } from './behavior-system-DSNek0W9.js';
 import { i as Vec3Input } from './vector-Bm65-FOG.js';
 import { h as ParticlePresetMaterialOptions, P as ParticleEffectDefinition, C as spark, o as ember, p as flamelet, l as blaze, A as smolder, t as mist, E as spray, D as splash, n as drizzle, H as torrent, I as vapor, z as smoke, q as haze, w as plume, s as miasma, B as spark$1, j as arc, G as surge, y as pulse, F as storm, k as arcane, r as holy, m as corrupted, u as nature, J as voidMagic, x as psychic, i as Particles } from './spark-Dx3cJbTW.js';
 export { a as ParticleMagicAgency, b as ParticleMagicAlignment, c as ParticleMagicModifierInput, d as ParticleMagicModifierOptions, e as ParticleMagicOrder, f as ParticleMagicRealityEffect, g as ParticleMagicTemperament, S as SemanticParticlePresetOptions, v as particleEffect } from './spark-Dx3cJbTW.js';

package/dist/particle-emitter.js

@@ -1,14 +1,15 @@
 import {
   ParticleEmitterBehavior,
   particlePresets
-} from "./chunk-VPZ32CCD.js";
+} from "./chunk-5SM5SH5O.js";
 import {
   particleEffect
-} from "./chunk-WSKD7GY3.js";
-import "./chunk-RHW3IDQX.js";
-import "./chunk-YDLO5M7S.js";
+} from "./chunk-7JJEIADR.js";
+import "./chunk-WWVD5DR5.js";
+import "./chunk-EZNCCO4L.js";
 export {
   ParticleEmitterBehavior,
   particleEffect,
   particlePresets
 };
+//# sourceMappingURL=particle-emitter.js.map

package/dist/particle-emitter.js.map

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

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

@@ -0,0 +1,306 @@
+import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
+import { RigidBody, Collider } from '@dimforge/rapier3d-compat';
+import { Z as ZylemWorld, a as BehaviorDescriptor } from './behavior-system-DSNek0W9.js';
+import 'typescript-fsm';
+
+/**
+ * Platformer 2D Components
+ *
+ * Components for 2D platformer movement on the X/Y plane: walking/running on
+ * X, jumping with multi-jump support, and falling/landing states.
+ */
+interface Platformer2DMovementComponent {
+    /** 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 */
+    gravity: 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;
+    /** Maximum slope angle (degrees) the character can walk up */
+    slopeClimbAngle: number;
+    /** Slope angle (degrees) past which the character slides down */
+    slopeSlideAngle: number;
+    /** Autostep configuration for SNES-style step-ups, or false to disable */
+    autostep: {
+        maxHeight: number;
+        minWidth: number;
+    } | false;
+    /** Snap-to-ground distance (keeps the character glued going downhill) */
+    snapToGroundDistance: number;
+    /** Character controller offset (small gap kept between collider and environment) */
+    characterOffset: number;
+}
+declare function createPlatformer2DMovementComponent(options?: Partial<Platformer2DMovementComponent>): Platformer2DMovementComponent;
+interface Platformer2DInputComponent {
+    /** Horizontal movement input (-1 to 1) */
+    moveX: number;
+    /** Jump button pressed */
+    jump: boolean;
+    /** Run/sprint button held */
+    run: boolean;
+}
+declare function createPlatformer2DInputComponent(): Platformer2DInputComponent;
+interface Platformer2DStateComponent {
+    /** 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;
+    /** 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, verticalVelocity lerps toward verticalVelocity * jumpCutMultiplier. */
+    jumpCutRampTimer: number;
+    /**
+     * Controller-owned vertical velocity (units/second).
+     * The body is kinematic, so `linvel()` is meaningless — this field is the
+     * single source of truth for jump/gravity motion on the Y axis.
+     */
+    verticalVelocity: number;
+}
+declare function createPlatformer2DStateComponent(): Platformer2DStateComponent;
+
+/**
+ * Platformer 2D Finite State Machine
+ *
+ * Manages state transitions for 2D 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 (normal in the X/Y plane).
+ */
+interface Platformer2DCollisionContext {
+    contact: {
+        normal: {
+            x: number;
+            y: number;
+        };
+    };
+}
+declare enum Platformer2DState {
+    Idle = "idle",
+    Walking = "walking",
+    Running = "running",
+    Jumping = "jumping",
+    Falling = "falling",
+    Landing = "landing"
+}
+declare enum Platformer2DEvent {
+    Walk = "walk",
+    Run = "run",
+    Jump = "jump",
+    Fall = "fall",
+    Land = "land",
+    Stop = "stop"
+}
+interface Platformer2DContext {
+    input: Platformer2DInputComponent;
+    state: Platformer2DStateComponent;
+}
+declare class Platformer2DFSM {
+    private ctx;
+    machine: SyncStateMachine<Platformer2DState, Platformer2DEvent, never>;
+    constructor(ctx: Platformer2DContext);
+    getState(): Platformer2DState;
+    dispatch(event: Platformer2DEvent): void;
+    isGrounded(): boolean;
+    getJumpCount(): number;
+    /**
+     * Update FSM based on current component state.
+     */
+    update(input: Platformer2DInputComponent, state: Platformer2DStateComponent): void;
+}
+
+/**
+ * Platformer 2D System
+ *
+ * Kinematic character controller (SNES-style) on the X/Y plane: the
+ * controller owns all motion and physics is only a collision database.
+ *
+ * - The entity's body is converted to `KinematicPositionBased` on first
+ *   update; Rapier never applies forces to it.
+ * - Each tick, desired displacement (X input + integrated vertical velocity,
+ *   z locked to 0) is run through Rapier's `KinematicCharacterController`
+ *   (collide-and-slide with autostep, slope limits, and snap-to-ground) and
+ *   the corrected movement is applied via `setNextKinematicTranslation`. The
+ *   z coordinate is re-pinned to its first-seen value every tick so slide
+ *   resolution can never drift the entity off the 2D plane.
+ * - Grounded comes from `controller.computedGrounded()` — no contact-pair or
+ *   raycast probing.
+ * - Vertical velocity lives in `state.verticalVelocity` (`linvel()` is
+ *   meaningless on kinematic bodies). Jump buffering, coyote time,
+ *   multi-jump, and the jump-cut ramp all operate on that field.
+ */
+
+/**
+ * Entity with 2D platformer components
+ */
+interface Platformer2DEntity {
+    uuid: string;
+    body: RigidBody;
+    collider?: Collider | null;
+    platformer2D: Platformer2DMovementComponent;
+    $platformer2D: Platformer2DInputComponent;
+    platformer2DState: Platformer2DStateComponent;
+}
+/**
+ * Platformer 2D movement system.
+ *
+ * Core kinematic controller for 2D platformer movement. Requires a live
+ * `ZylemWorld` with the raw Rapier `World` exposed on `.world` — without it
+ * the system is a no-op.
+ */
+declare class Platformer2DSystem {
+    private world;
+    /** Per-entity character controllers, keyed by entity uuid. */
+    private controllers;
+    /** Spawn-time z per entity; re-pinned every tick to hold the 2D plane. */
+    private planeZ;
+    constructor(world: ZylemWorld | null);
+    /**
+     * One-time per-entity physics setup: convert the body to a
+     * position-based kinematic body, record the plane z, and create the
+     * entity's character controller. Done lazily on the first update because
+     * the body isn't always available at construction time.
+     */
+    private ensurePhysicsConfigured;
+    /**
+     * Handle jump logic with multi-jump, coyote time, buffering, and jump-cut
+     * ramp. All vertical motion is written to `state.verticalVelocity`.
+     */
+    private handleJump;
+    /**
+     * Integrate gravity into `state.verticalVelocity`.
+     *
+     * While grounded (and not on the jump frame) vertical velocity is held at
+     * a small constant downward speed so the controller stays pressed into
+     * the ground. Skipped entirely on the frame a jump was applied — the
+     * grounded flag is still stale-true then and would clobber the jump.
+     */
+    private applyGravity;
+    /**
+     * Update entity state from the controller's grounded result.
+     */
+    private updateState;
+    /**
+     * Update one platformer entity. Invoked per linked entity by the
+     * Platformer2DBehaviorSystem adapter.
+     */
+    updateEntity(entity: Platformer2DEntity, delta: number): void;
+    destroy(): void;
+}
+
+/**
+ * Platformer 2D behavior options (typed for entity.use() autocomplete)
+ */
+interface Platformer2DBehaviorOptions {
+    /** Base walking speed (default: 8) */
+    walkSpeed?: number;
+    /** Sprint/run speed (default: 14) */
+    runSpeed?: number;
+    /** Initial jump force (default: 12) */
+    jumpForce?: number;
+    /** Maximum number of jumps (default: 1) */
+    maxJumps?: number;
+    /** Gravity force (default: 20) */
+    gravity?: number;
+    /** Coyote time in seconds (default: 0.1) */
+    coyoteTime?: number;
+    /** Jump buffer time in seconds (default: 0.1) */
+    jumpBufferTime?: number;
+    /** Velocity multiplier when releasing jump early (default: 0.5) */
+    jumpCutMultiplier?: number;
+    /** Maximum slope angle in degrees the character can walk up (default: 50) */
+    slopeClimbAngle?: number;
+    /** Slope angle in degrees past which the character slides (default: 40) */
+    slopeSlideAngle?: number;
+    /** Autostep over small step-ups, or false to disable (default: { maxHeight: 0.25, minWidth: 0.05 }) */
+    autostep?: {
+        maxHeight: number;
+        minWidth: number;
+    } | false;
+    /** Snap-to-ground distance for downhill/step-down stability (default: 0.2) */
+    snapToGroundDistance?: number;
+    /** Character controller collision offset (default: 0.05) */
+    characterOffset?: number;
+}
+/**
+ * Platformer2DBehavior - typed descriptor for 2D platformer movement
+ *
+ * Provides complete 2D platformer physics on the X/Y plane including:
+ * - Walking and running on X
+ * - Jumping with buffer, coyote time, multi-jump, and jump-cut
+ * - Gravity ownership and falling
+ * - Kinematic character controller (collide-and-slide, autostep, snap-to-ground)
+ *
+ * @example
+ * ```typescript
+ * import { Platformer2DBehavior } from "@zylem/behaviors/platformer-2d";
+ *
+ * const platformer = player.use(Platformer2DBehavior, {
+ *   walkSpeed: 8,
+ *   runSpeed: 14,
+ *   jumpForce: 12,
+ *   maxJumps: 2, // Double jump!
+ * });
+ *
+ * // In update loop
+ * player.onUpdate(({ inputs }) => {
+ *   player.$platformer2D.moveX = inputs.p1.axes.Horizontal.value;
+ *   player.$platformer2D.jump = inputs.p1.buttons.A.held > 0;
+ *   player.$platformer2D.run = inputs.p1.shoulders.LTrigger.held > 0;
+ *
+ *   const state = platformer.getState();
+ *   const grounded = platformer.isGrounded();
+ * });
+ * ```
+ */
+declare const Platformer2DBehavior: BehaviorDescriptor<Platformer2DBehaviorOptions, {
+    getState: () => Platformer2DState;
+    isGrounded: () => boolean;
+    getJumpCount: () => number;
+}, Platformer2DEntity>;
+
+export { Platformer2DBehavior, type Platformer2DBehaviorOptions, type Platformer2DCollisionContext, type Platformer2DContext, type Platformer2DEntity, Platformer2DEvent, Platformer2DFSM, type Platformer2DInputComponent, type Platformer2DMovementComponent, Platformer2DState, type Platformer2DStateComponent, Platformer2DSystem, createPlatformer2DInputComponent, createPlatformer2DMovementComponent, createPlatformer2DStateComponent };

package/dist/platformer-2d.js

@@ -0,0 +1,23 @@
+import {
+  Platformer2DBehavior,
+  Platformer2DEvent,
+  Platformer2DFSM,
+  Platformer2DState,
+  Platformer2DSystem,
+  createPlatformer2DInputComponent,
+  createPlatformer2DMovementComponent,
+  createPlatformer2DStateComponent
+} from "./chunk-RTRFJVCZ.js";
+import "./chunk-4URF65BR.js";
+import "./chunk-EZNCCO4L.js";
+export {
+  Platformer2DBehavior,
+  Platformer2DEvent,
+  Platformer2DFSM,
+  Platformer2DState,
+  Platformer2DSystem,
+  createPlatformer2DInputComponent,
+  createPlatformer2DMovementComponent,
+  createPlatformer2DStateComponent
+};
+//# sourceMappingURL=platformer-2d.js.map

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

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