@zylem/game-lib 0.6.0 → 0.6.3

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

@@ -0,0 +1,274 @@
+import { B as BaseEntityInterface } from '../entity-types-DAu8sGJH.js';
+import { StateMachine } from 'typescript-fsm';
+import { b as BehaviorDescriptor } from '../behavior-descriptor-BWNWmIjv.js';
+import 'three';
+import '@dimforge/rapier3d-compat';
+import 'bitecs';
+
+/**
+ * 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: StateMachine<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";
+ *
+ * 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/behavior/ricochet-2d.js

@@ -0,0 +1,394 @@
+// src/lib/behaviors/ricochet-2d/ricochet-2d-fsm.ts
+import { StateMachine, t } from "typescript-fsm";
+var Ricochet2DState = /* @__PURE__ */ ((Ricochet2DState2) => {
+  Ricochet2DState2["Idle"] = "idle";
+  Ricochet2DState2["Ricocheting"] = "ricocheting";
+  return Ricochet2DState2;
+})(Ricochet2DState || {});
+var Ricochet2DEvent = /* @__PURE__ */ ((Ricochet2DEvent2) => {
+  Ricochet2DEvent2["StartRicochet"] = "start-ricochet";
+  Ricochet2DEvent2["EndRicochet"] = "end-ricochet";
+  return Ricochet2DEvent2;
+})(Ricochet2DEvent || {});
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+var Ricochet2DFSM = class {
+  machine;
+  lastResult = null;
+  lastUpdatedAtMs = null;
+  currentTimeMs = 0;
+  listeners = /* @__PURE__ */ new Set();
+  constructor() {
+    this.machine = new StateMachine(
+      "idle" /* Idle */,
+      [
+        t("idle" /* Idle */, "start-ricochet" /* StartRicochet */, "ricocheting" /* Ricocheting */),
+        t("ricocheting" /* Ricocheting */, "end-ricochet" /* EndRicochet */, "idle" /* Idle */),
+        // Self transitions (no-ops)
+        t("idle" /* Idle */, "end-ricochet" /* EndRicochet */, "idle" /* Idle */),
+        t("ricocheting" /* Ricocheting */, "start-ricochet" /* StartRicochet */, "ricocheting" /* Ricocheting */)
+      ]
+    );
+  }
+  /**
+   * Add a listener for ricochet events.
+   * @returns Unsubscribe function
+   */
+  addListener(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  /**
+   * Emit result to all listeners.
+   */
+  emitToListeners(result) {
+    for (const callback of this.listeners) {
+      try {
+        callback(result);
+      } catch (e) {
+        console.error("[Ricochet2DFSM] Listener error:", e);
+      }
+    }
+  }
+  getState() {
+    return this.machine.getState();
+  }
+  /**
+   * Returns the last computed ricochet result, or null if none.
+   */
+  getLastResult() {
+    return this.lastResult;
+  }
+  /**
+   * Best-effort timestamp (ms) of the last computation.
+   */
+  getLastUpdatedAtMs() {
+    return this.lastUpdatedAtMs;
+  }
+  /**
+   * Set current game time (called by system each frame).
+   * Used for cooldown calculations.
+   */
+  setCurrentTimeMs(timeMs) {
+    this.currentTimeMs = timeMs;
+  }
+  /**
+   * Check if ricochet is on cooldown (to prevent rapid duplicate applications).
+   * @param cooldownMs Cooldown duration in milliseconds (default: 50ms)
+   */
+  isOnCooldown(cooldownMs = 50) {
+    if (this.lastUpdatedAtMs === null) return false;
+    return this.currentTimeMs - this.lastUpdatedAtMs < cooldownMs;
+  }
+  /**
+   * Reset cooldown state (e.g., on entity respawn).
+   */
+  resetCooldown() {
+    this.lastUpdatedAtMs = null;
+  }
+  /**
+   * Compute a ricochet result from collision context.
+   * Returns the result for the consumer to apply, or null if invalid input.
+   */
+  computeRicochet(ctx, options = {}) {
+    const {
+      minSpeed = 2,
+      maxSpeed = 20,
+      speedMultiplier = 1.05,
+      reflectionMode = "angled",
+      maxAngleDeg = 60
+    } = options;
+    const { selfVelocity, selfPosition, otherPosition, otherSize } = this.extractDataFromEntities(ctx);
+    if (!selfVelocity) {
+      this.dispatch("end-ricochet" /* EndRicochet */);
+      return null;
+    }
+    const speed = Math.hypot(selfVelocity.x, selfVelocity.y);
+    if (speed === 0) {
+      this.dispatch("end-ricochet" /* EndRicochet */);
+      return null;
+    }
+    const normal = ctx.contact.normal ?? this.computeNormalFromPositions(selfPosition, otherPosition);
+    if (!normal) {
+      this.dispatch("end-ricochet" /* EndRicochet */);
+      return null;
+    }
+    let reflected = this.computeBasicReflection(selfVelocity, normal);
+    if (reflectionMode === "angled") {
+      reflected = this.computeAngledDeflection(
+        selfVelocity,
+        normal,
+        speed,
+        maxAngleDeg,
+        speedMultiplier,
+        selfPosition,
+        otherPosition,
+        otherSize,
+        ctx.contact.position
+      );
+    }
+    reflected = this.applySpeedClamp(reflected, minSpeed, maxSpeed);
+    const result = {
+      velocity: { x: reflected.x, y: reflected.y, z: 0 },
+      speed: Math.hypot(reflected.x, reflected.y),
+      normal: { x: normal.x, y: normal.y, z: 0 }
+    };
+    this.lastResult = result;
+    this.lastUpdatedAtMs = this.currentTimeMs;
+    this.dispatch("start-ricochet" /* StartRicochet */);
+    this.emitToListeners(result);
+    return result;
+  }
+  /**
+   * Extract velocity, position, and size data from entities or context.
+   */
+  extractDataFromEntities(ctx) {
+    let selfVelocity = ctx.selfVelocity;
+    let selfPosition = ctx.selfPosition;
+    let otherPosition = ctx.otherPosition;
+    let otherSize = ctx.otherSize;
+    if (ctx.entity?.body) {
+      const vel = ctx.entity.body.linvel();
+      selfVelocity = selfVelocity ?? { x: vel.x, y: vel.y, z: vel.z };
+      const pos = ctx.entity.body.translation();
+      selfPosition = selfPosition ?? { x: pos.x, y: pos.y, z: pos.z };
+    }
+    if (ctx.otherEntity?.body) {
+      const pos = ctx.otherEntity.body.translation();
+      otherPosition = otherPosition ?? { x: pos.x, y: pos.y, z: pos.z };
+    }
+    if (ctx.otherEntity && "size" in ctx.otherEntity) {
+      const size = ctx.otherEntity.size;
+      if (size && typeof size.x === "number") {
+        otherSize = otherSize ?? { x: size.x, y: size.y, z: size.z };
+      }
+    }
+    return { selfVelocity, selfPosition, otherPosition, otherSize };
+  }
+  /**
+   * Compute collision normal from entity positions using AABB heuristic.
+   */
+  computeNormalFromPositions(selfPosition, otherPosition) {
+    if (!selfPosition || !otherPosition) return null;
+    const dx = selfPosition.x - otherPosition.x;
+    const dy = selfPosition.y - otherPosition.y;
+    if (Math.abs(dx) > Math.abs(dy)) {
+      return { x: dx > 0 ? 1 : -1, y: 0, z: 0 };
+    } else {
+      return { x: 0, y: dy > 0 ? 1 : -1, z: 0 };
+    }
+  }
+  /**
+   * Compute basic reflection using the formula: v' = v - 2(v·n)n
+   */
+  computeBasicReflection(velocity, normal) {
+    const vx = velocity.x;
+    const vy = velocity.y;
+    const dotProduct = vx * normal.x + vy * normal.y;
+    return {
+      x: vx - 2 * dotProduct * normal.x,
+      y: vy - 2 * dotProduct * normal.y
+    };
+  }
+  /**
+   * Compute angled deflection for paddle-style reflections.
+   */
+  computeAngledDeflection(velocity, normal, speed, maxAngleDeg, speedMultiplier, selfPosition, otherPosition, otherSize, contactPosition) {
+    const maxAngleRad = maxAngleDeg * Math.PI / 180;
+    let tx = -normal.y;
+    let ty = normal.x;
+    if (Math.abs(normal.x) > Math.abs(normal.y)) {
+      if (ty < 0) {
+        tx = -tx;
+        ty = -ty;
+      }
+    } else {
+      if (tx < 0) {
+        tx = -tx;
+        ty = -ty;
+      }
+    }
+    const offset = this.computeHitOffset(
+      velocity,
+      normal,
+      speed,
+      tx,
+      ty,
+      selfPosition,
+      otherPosition,
+      otherSize,
+      contactPosition
+    );
+    const angle = clamp(offset, -1, 1) * maxAngleRad;
+    const cosA = Math.cos(angle);
+    const sinA = Math.sin(angle);
+    const newSpeed = speed * speedMultiplier;
+    return {
+      x: newSpeed * (normal.x * cosA + tx * sinA),
+      y: newSpeed * (normal.y * cosA + ty * sinA)
+    };
+  }
+  /**
+   * Compute hit offset for angled deflection (-1 to 1).
+   */
+  computeHitOffset(velocity, normal, speed, tx, ty, selfPosition, otherPosition, otherSize, contactPosition) {
+    if (otherPosition && otherSize) {
+      const useY = Math.abs(normal.x) > Math.abs(normal.y);
+      const halfExtent = useY ? otherSize.y / 2 : otherSize.x / 2;
+      if (useY) {
+        const selfY = selfPosition?.y ?? contactPosition?.y ?? 0;
+        const paddleY = otherPosition.y;
+        return (selfY - paddleY) / halfExtent;
+      } else {
+        const selfX = selfPosition?.x ?? contactPosition?.x ?? 0;
+        const paddleX = otherPosition.x;
+        return (selfX - paddleX) / halfExtent;
+      }
+    }
+    return (velocity.x * tx + velocity.y * ty) / speed;
+  }
+  /**
+   * Apply speed constraints to the reflected velocity.
+   */
+  applySpeedClamp(velocity, minSpeed, maxSpeed) {
+    const currentSpeed = Math.hypot(velocity.x, velocity.y);
+    if (currentSpeed === 0) return velocity;
+    const targetSpeed = clamp(currentSpeed, minSpeed, maxSpeed);
+    const scale = targetSpeed / currentSpeed;
+    return {
+      x: velocity.x * scale,
+      y: velocity.y * scale
+    };
+  }
+  /**
+   * Clear the ricochet state (call after consumer has applied the result).
+   */
+  clearRicochet() {
+    this.dispatch("end-ricochet" /* EndRicochet */);
+  }
+  dispatch(event) {
+    if (this.machine.can(event)) {
+      this.machine.dispatch(event);
+    }
+  }
+};
+
+// src/lib/behaviors/behavior-descriptor.ts
+function defineBehavior(config) {
+  return {
+    key: /* @__PURE__ */ Symbol.for(`zylem:behavior:${config.name}`),
+    defaultOptions: config.defaultOptions,
+    systemFactory: config.systemFactory,
+    createHandle: config.createHandle
+  };
+}
+
+// src/lib/behaviors/ricochet-2d/ricochet-2d.descriptor.ts
+var defaultOptions = {
+  minSpeed: 2,
+  maxSpeed: 20,
+  speedMultiplier: 1.05,
+  reflectionMode: "angled",
+  maxAngleDeg: 60
+};
+function createRicochet2DHandle(ref) {
+  return {
+    getRicochet: (ctx) => {
+      const fsm = ref.fsm;
+      if (!fsm) return null;
+      return fsm.computeRicochet(ctx, ref.options);
+    },
+    applyRicochet: (ctx) => {
+      const fsm = ref.fsm;
+      if (!fsm) return false;
+      if (fsm.isOnCooldown()) return false;
+      const result = fsm.computeRicochet(ctx, ref.options);
+      if (!result) return false;
+      const entity = ctx.entity;
+      if (entity?.transformStore) {
+        entity.transformStore.velocity.x = result.velocity.x;
+        entity.transformStore.velocity.y = result.velocity.y;
+        entity.transformStore.velocity.z = result.velocity.z ?? 0;
+        entity.transformStore.dirty.velocity = true;
+      }
+      return true;
+    },
+    getLastResult: () => {
+      const fsm = ref.fsm;
+      return fsm?.getLastResult() ?? null;
+    },
+    onRicochet: (callback) => {
+      const fsm = ref.fsm;
+      if (!fsm) {
+        if (!ref.pendingListeners) {
+          ref.pendingListeners = [];
+        }
+        ref.pendingListeners.push(callback);
+        return () => {
+          const pending = ref.pendingListeners;
+          const idx = pending.indexOf(callback);
+          if (idx >= 0) pending.splice(idx, 1);
+        };
+      }
+      return fsm.addListener(callback);
+    }
+  };
+}
+var Ricochet2DSystem = class {
+  constructor(world) {
+    this.world = world;
+  }
+  elapsedMs = 0;
+  update(_ecs, delta) {
+    this.elapsedMs += delta * 1e3;
+    if (!this.world?.collisionMap) return;
+    for (const [, entity] of this.world.collisionMap) {
+      const gameEntity = entity;
+      if (typeof gameEntity.getBehaviorRefs !== "function") continue;
+      const refs = gameEntity.getBehaviorRefs();
+      const ricochetRef = refs.find(
+        (r) => r.descriptor.key === /* @__PURE__ */ Symbol.for("zylem:behavior:ricochet-2d")
+      );
+      if (!ricochetRef) continue;
+      if (!ricochetRef.fsm) {
+        ricochetRef.fsm = new Ricochet2DFSM();
+        const pending = ricochetRef.pendingListeners;
+        if (pending) {
+          for (const cb of pending) {
+            ricochetRef.fsm.addListener(cb);
+          }
+          ricochetRef.pendingListeners = [];
+        }
+      }
+      ricochetRef.fsm.setCurrentTimeMs(this.elapsedMs);
+    }
+  }
+  destroy(_ecs) {
+    if (!this.world?.collisionMap) return;
+    for (const [, entity] of this.world.collisionMap) {
+      const gameEntity = entity;
+      if (typeof gameEntity.getBehaviorRefs !== "function") continue;
+      const refs = gameEntity.getBehaviorRefs();
+      const ricochetRef = refs.find(
+        (r) => r.descriptor.key === /* @__PURE__ */ Symbol.for("zylem:behavior:ricochet-2d")
+      );
+      if (ricochetRef?.fsm) {
+        ricochetRef.fsm.resetCooldown();
+      }
+    }
+  }
+};
+var Ricochet2DBehavior = defineBehavior({
+  name: "ricochet-2d",
+  defaultOptions,
+  systemFactory: (ctx) => new Ricochet2DSystem(ctx.world),
+  createHandle: createRicochet2DHandle
+});
+export {
+  Ricochet2DBehavior,
+  Ricochet2DEvent,
+  Ricochet2DFSM,
+  Ricochet2DState
+};
+//# sourceMappingURL=ricochet-2d.js.map