@zylem/game-lib 0.6.2 → 0.6.4

package/dist/behavior/world-boundary-3d.js

@@ -0,0 +1,274 @@
+// 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/core/utility/sync-state-machine.ts
+import {
+  StateMachine as BaseStateMachine
+} from "typescript-fsm";
+import { t } from "typescript-fsm";
+var SyncStateMachine = class extends BaseStateMachine {
+  constructor(init, transitions = [], logger = console) {
+    super(init, transitions, logger);
+  }
+  dispatch(_event, ..._args) {
+    throw new Error("SyncStateMachine does not support async dispatch.");
+  }
+  syncDispatch(event, ...args) {
+    const found = this.transitions.some((transition) => {
+      if (transition.fromState !== this._current || transition.event !== event) {
+        return false;
+      }
+      const current = this._current;
+      this._current = transition.toState;
+      if (!transition.cb) {
+        return true;
+      }
+      try {
+        transition.cb(...args);
+        return true;
+      } catch (error) {
+        this._current = current;
+        this.logger.error("Exception in callback", error);
+        throw error;
+      }
+    });
+    if (!found) {
+      const errorMessage = this.formatErr(this._current, event);
+      this.logger.error(errorMessage);
+    }
+    return found;
+  }
+};
+
+// src/lib/behaviors/shared/bounds-3d.ts
+function normalizeBounds3DPadding(padding) {
+  if (typeof padding === "number") {
+    return { x: padding, y: padding, z: padding };
+  }
+  return {
+    x: padding?.x ?? 0,
+    y: padding?.y ?? 0,
+    z: padding?.z ?? 0
+  };
+}
+function insetBounds3D(bounds, padding) {
+  const resolved = normalizeBounds3DPadding(padding);
+  return {
+    minX: bounds.minX + resolved.x,
+    maxX: bounds.maxX - resolved.x,
+    minY: bounds.minY + resolved.y,
+    maxY: bounds.maxY - resolved.y,
+    minZ: bounds.minZ + resolved.z,
+    maxZ: bounds.maxZ - resolved.z
+  };
+}
+function computeBounds3DHits(position, bounds) {
+  const hits = {
+    left: false,
+    right: false,
+    top: false,
+    bottom: false,
+    back: false,
+    front: false
+  };
+  if (position.x <= bounds.minX) hits.left = true;
+  else if (position.x >= bounds.maxX) hits.right = true;
+  if (position.y <= bounds.minY) hits.bottom = true;
+  else if (position.y >= bounds.maxY) hits.top = true;
+  if (position.z <= bounds.minZ) hits.back = true;
+  else if (position.z >= bounds.maxZ) hits.front = true;
+  return hits;
+}
+function hasAnyBounds3DHit(hits) {
+  return hits.left || hits.right || hits.top || hits.bottom || hits.back || hits.front;
+}
+function constrainMovementToBounds3D(hits, moveX, moveY, moveZ) {
+  let adjustedX = moveX;
+  let adjustedY = moveY;
+  let adjustedZ = moveZ;
+  if (hits.left && moveX < 0 || hits.right && moveX > 0) {
+    adjustedX = 0;
+  }
+  if (hits.bottom && moveY < 0 || hits.top && moveY > 0) {
+    adjustedY = 0;
+  }
+  if (hits.back && moveZ < 0 || hits.front && moveZ > 0) {
+    adjustedZ = 0;
+  }
+  return { moveX: adjustedX, moveY: adjustedY, moveZ: adjustedZ };
+}
+function clampPointToBounds3D(position, bounds) {
+  return {
+    x: Math.min(bounds.maxX, Math.max(bounds.minX, position.x)),
+    y: Math.min(bounds.maxY, Math.max(bounds.minY, position.y)),
+    z: Math.min(bounds.maxZ, Math.max(bounds.minZ, position.z))
+  };
+}
+
+// src/lib/behaviors/world-boundary-3d/world-boundary-3d-fsm.ts
+var WorldBoundary3DState = /* @__PURE__ */ ((WorldBoundary3DState2) => {
+  WorldBoundary3DState2["Inside"] = "inside";
+  WorldBoundary3DState2["Touching"] = "touching";
+  return WorldBoundary3DState2;
+})(WorldBoundary3DState || {});
+var WorldBoundary3DEvent = /* @__PURE__ */ ((WorldBoundary3DEvent2) => {
+  WorldBoundary3DEvent2["EnterInside"] = "enter-inside";
+  WorldBoundary3DEvent2["TouchBoundary"] = "touch-boundary";
+  return WorldBoundary3DEvent2;
+})(WorldBoundary3DEvent || {});
+function computeWorldBoundary3DHits(position, bounds, padding) {
+  return computeBounds3DHits(position, insetBounds3D({
+    minX: bounds.left,
+    maxX: bounds.right,
+    minY: bounds.bottom,
+    maxY: bounds.top,
+    minZ: bounds.back,
+    maxZ: bounds.front
+  }, padding));
+}
+function hasAnyWorldBoundary3DHit(hits) {
+  return hasAnyBounds3DHit(hits);
+}
+var WorldBoundary3DFSM = class {
+  machine;
+  lastHits = {
+    top: false,
+    bottom: false,
+    left: false,
+    right: false,
+    back: false,
+    front: false
+  };
+  lastPosition = null;
+  lastClampedPosition = null;
+  lastUpdatedAtMs = null;
+  constructor() {
+    this.machine = new SyncStateMachine(
+      "inside" /* Inside */,
+      [
+        t("inside" /* Inside */, "touch-boundary" /* TouchBoundary */, "touching" /* Touching */),
+        t("touching" /* Touching */, "enter-inside" /* EnterInside */, "inside" /* Inside */),
+        t("inside" /* Inside */, "enter-inside" /* EnterInside */, "inside" /* Inside */),
+        t("touching" /* Touching */, "touch-boundary" /* TouchBoundary */, "touching" /* Touching */)
+      ]
+    );
+  }
+  getState() {
+    return this.machine.getState();
+  }
+  getLastHits() {
+    return this.lastHits;
+  }
+  getMovement(moveX, moveY, moveZ) {
+    return constrainMovementToBounds3D(this.lastHits, moveX, moveY, moveZ);
+  }
+  getLastPosition() {
+    return this.lastPosition;
+  }
+  getLastClampedPosition() {
+    return this.lastClampedPosition;
+  }
+  getLastUpdatedAtMs() {
+    return this.lastUpdatedAtMs;
+  }
+  update(position, bounds, padding) {
+    const effectiveBounds = insetBounds3D({
+      minX: bounds.left,
+      maxX: bounds.right,
+      minY: bounds.bottom,
+      maxY: bounds.top,
+      minZ: bounds.back,
+      maxZ: bounds.front
+    }, padding);
+    const hits = computeBounds3DHits(position, effectiveBounds);
+    this.lastHits = hits;
+    this.lastPosition = { x: position.x, y: position.y, z: position.z };
+    this.lastClampedPosition = clampPointToBounds3D(position, effectiveBounds);
+    this.lastUpdatedAtMs = Date.now();
+    if (hasAnyWorldBoundary3DHit(hits)) {
+      this.dispatch("touch-boundary" /* TouchBoundary */);
+    } else {
+      this.dispatch("enter-inside" /* EnterInside */);
+    }
+    return hits;
+  }
+  dispatch(event) {
+    if (this.machine.can(event)) {
+      this.machine.syncDispatch(event);
+    }
+  }
+};
+
+// src/lib/behaviors/world-boundary-3d/world-boundary-3d.descriptor.ts
+var defaultOptions = {
+  boundaries: { top: 0, bottom: 0, left: 0, right: 0, back: 0, front: 0 },
+  padding: 0
+};
+var WORLD_BOUNDARY_3D_BEHAVIOR_KEY = /* @__PURE__ */ Symbol.for(
+  "zylem:behavior:world-boundary-3d"
+);
+function createWorldBoundary3DHandle(ref) {
+  return {
+    getLastHits: () => {
+      const fsm = ref.fsm;
+      return fsm?.getLastHits() ?? null;
+    },
+    getMovement: (moveX, moveY, moveZ) => {
+      const fsm = ref.fsm;
+      return fsm?.getMovement(moveX, moveY, moveZ) ?? { moveX, moveY, moveZ };
+    },
+    getLastClampedPosition: () => {
+      const fsm = ref.fsm;
+      return fsm?.getLastClampedPosition() ?? null;
+    }
+  };
+}
+var WorldBoundary3DSystem = class {
+  constructor(world, getBehaviorLinks) {
+    this.world = world;
+    this.getBehaviorLinks = getBehaviorLinks;
+  }
+  update(_ecs, _delta) {
+    const links = this.getBehaviorLinks?.(WORLD_BOUNDARY_3D_BEHAVIOR_KEY);
+    if (!links) return;
+    for (const link of links) {
+      const gameEntity = link.entity;
+      const boundaryRef = link.ref;
+      if (!gameEntity.body) continue;
+      const options = boundaryRef.options;
+      if (!boundaryRef.fsm) {
+        boundaryRef.fsm = new WorldBoundary3DFSM();
+      }
+      const pos = gameEntity.body.translation();
+      boundaryRef.fsm.update(
+        { x: pos.x, y: pos.y, z: pos.z },
+        options.boundaries,
+        options.padding
+      );
+    }
+  }
+  destroy(_ecs) {
+  }
+};
+var WorldBoundary3DBehavior = defineBehavior({
+  name: "world-boundary-3d",
+  defaultOptions,
+  systemFactory: (ctx) => new WorldBoundary3DSystem(ctx.world, ctx.getBehaviorLinks),
+  createHandle: createWorldBoundary3DHandle
+});
+export {
+  WorldBoundary3DBehavior,
+  WorldBoundary3DEvent,
+  WorldBoundary3DFSM,
+  WorldBoundary3DState,
+  computeWorldBoundary3DHits,
+  hasAnyWorldBoundary3DHit
+};
+//# sourceMappingURL=world-boundary-3d.js.map

package/dist/behavior/world-boundary-3d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/behaviors/behavior-descriptor.ts","../../src/lib/core/utility/sync-state-machine.ts","../../src/lib/behaviors/shared/bounds-3d.ts","../../src/lib/behaviors/world-boundary-3d/world-boundary-3d-fsm.ts","../../src/lib/behaviors/world-boundary-3d/world-boundary-3d.descriptor.ts"],"sourcesContent":["/**\n * BehaviorDescriptor\n *\n * Type-safe behavior descriptors that provide options inference.\n * Used with entity.use() to declaratively attach behaviors to entities.\n *\n * Each behavior can define its own handle type via `createHandle`,\n * providing behavior-specific methods with full type safety.\n */\n\nimport type { BehaviorSystemFactory } from './behavior-system';\n\n/**\n * Base handle returned by entity.use() for lazy access to behavior runtime.\n * FSM is null until entity is spawned and components are initialized.\n */\nexport interface BaseBehaviorHandle<\n  O extends Record<string, any> = Record<string, any>,\n> {\n  /** Get the FSM instance (null until entity is spawned) */\n  getFSM(): any | null;\n  /** Get the current options */\n  getOptions(): O;\n  /** Access the underlying behavior ref */\n  readonly ref: BehaviorRef<O>;\n}\n\n/**\n * Reference to a behavior stored on an entity\n */\nexport interface BehaviorRef<\n  O extends Record<string, any> = Record<string, any>,\n> {\n  /** The behavior descriptor */\n  descriptor: BehaviorDescriptor<O, any>;\n  /** Merged options (defaults + overrides) */\n  options: O;\n  /** Optional FSM instance - set lazily when entity is spawned */\n  fsm?: any;\n}\n\n/**\n * A typed behavior descriptor that associates a symbol key with:\n * - Default options (providing type inference)\n * - A system factory to create the behavior system\n * - An optional handle factory for behavior-specific methods\n */\nexport interface BehaviorDescriptor<\n  O extends Record<string, any> = Record<string, any>,\n  H extends Record<string, any> = Record<string, never>,\n  I = unknown,\n> {\n  /** Unique symbol identifying this behavior */\n  readonly key: symbol;\n  /** Default options (used for type inference) */\n  readonly defaultOptions: O;\n  /** Factory to create the behavior system */\n  readonly systemFactory: BehaviorSystemFactory;\n  /**\n   * Optional factory to create behavior-specific handle methods.\n   * These methods are merged into the handle returned by entity.use().\n   */\n  readonly createHandle?: (ref: BehaviorRef<O>) => H;\n}\n\n/**\n * The full handle type returned by entity.use().\n * Combines base handle with behavior-specific methods.\n */\nexport type BehaviorHandle<\n  O extends Record<string, any> = Record<string, any>,\n  H extends Record<string, any> = Record<string, never>,\n> = BaseBehaviorHandle<O> & H;\n\n/**\n * Configuration for defining a new behavior\n */\nexport interface DefineBehaviorConfig<\n  O extends Record<string, any>,\n  H extends Record<string, any> = Record<string, never>,\n  I = unknown,\n> {\n  /** Human-readable name for debugging */\n  name: string;\n  /** Default options - these define the type */\n  defaultOptions: O;\n  /** Factory function to create the system */\n  systemFactory: BehaviorSystemFactory;\n  /**\n   * Optional factory to create behavior-specific handle methods.\n   * The returned object is merged into the handle returned by entity.use().\n   *\n   * @example\n   * ```typescript\n   * createHandle: (ref) => ({\n   *   getLastHits: () => ref.fsm?.getLastHits() ?? null,\n   *   getMovement: (moveX, moveY) => ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },\n   * }),\n   * ```\n   */\n  createHandle?: (ref: BehaviorRef<O>) => H;\n}\n\n/**\n * Define a typed behavior descriptor.\n *\n * @example\n * ```typescript\n * export const WorldBoundary2DBehavior = defineBehavior({\n *   name: 'world-boundary-2d',\n *   defaultOptions: { boundaries: { top: 0, bottom: 0, left: 0, right: 0 } },\n *   systemFactory: (ctx) => new WorldBoundary2DSystem(ctx.world),\n *   createHandle: (ref) => ({\n *     getLastHits: () => ref.fsm?.getLastHits() ?? null,\n *     getMovement: (moveX: number, moveY: number) =>\n *       ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },\n *   }),\n * });\n *\n * // Usage - handle has getLastHits and getMovement with full types\n * const boundary = ship.use(WorldBoundary2DBehavior, { ... });\n * const hits = boundary.getLastHits(); // Fully typed!\n * ```\n */\nexport function defineBehavior<\n  O extends Record<string, any>,\n  H extends Record<string, any> = Record<string, never>,\n  I = unknown,\n>(\n  config: DefineBehaviorConfig<O, H, I>,\n): BehaviorDescriptor<O, H, I> {\n  return {\n    key: Symbol.for(`zylem:behavior:${config.name}`),\n    defaultOptions: config.defaultOptions,\n    systemFactory: config.systemFactory,\n    createHandle: config.createHandle,\n  };\n}\n","import {\n\tStateMachine as BaseStateMachine,\n\ttype ILogger,\n\ttype ITransition,\n\ttype SyncCallback,\n} from 'typescript-fsm';\n\nexport { t } from 'typescript-fsm';\nexport type { ILogger, ITransition, SyncCallback };\n\n/**\n * Local wrapper around typescript-fsm's SyncStateMachine.\n *\n * typescript-fsm@1.6.0 incorrectly reports callback-less transitions as\n * unhandled even after moving to the next state, which causes noisy\n * `No transition...` console errors for valid FSM dispatches.\n */\nexport class SyncStateMachine<\n\tSTATE extends string | number | symbol,\n\tEVENT extends string | number | symbol,\n\tCALLBACK extends Record<EVENT, SyncCallback> = Record<EVENT, SyncCallback>,\n> extends BaseStateMachine<STATE, EVENT, CALLBACK> {\n\tconstructor(\n\t\tinit: STATE,\n\t\ttransitions: ITransition<STATE, EVENT, CALLBACK[EVENT]>[] = [],\n\t\tlogger: ILogger = console,\n\t) {\n\t\tsuper(init, transitions, logger);\n\t}\n\n\tdispatch<E extends EVENT>(_event: E, ..._args: unknown[]): Promise<void> {\n\t\tthrow new Error('SyncStateMachine does not support async dispatch.');\n\t}\n\n\tsyncDispatch<E extends EVENT>(event: E, ...args: unknown[]): boolean {\n\t\tconst found = this.transitions.some((transition) => {\n\t\t\tif (transition.fromState !== this._current || transition.event !== event) {\n\t\t\t\treturn false;\n\t\t\t}\n\n\t\t\tconst current = this._current;\n\t\t\tthis._current = transition.toState;\n\n\t\t\tif (!transition.cb) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\ttransition.cb(...args);\n\t\t\t\treturn true;\n\t\t\t} catch (error) {\n\t\t\t\tthis._current = current;\n\t\t\t\tthis.logger.error('Exception in callback', error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\n\t\tif (!found) {\n\t\t\tconst errorMessage = this.formatErr(this._current, event);\n\t\t\tthis.logger.error(errorMessage);\n\t\t}\n\n\t\treturn found;\n\t}\n}\n","export interface Bounds3DPoint {\n\tx: number;\n\ty: number;\n\tz: number;\n}\n\nexport interface Bounds3DBox {\n\tminX: number;\n\tmaxX: number;\n\tminY: number;\n\tmaxY: number;\n\tminZ: number;\n\tmaxZ: number;\n}\n\nexport interface Bounds3DSize {\n\twidth: number;\n\theight: number;\n\tdepth: number;\n\tcenterX?: number;\n\tcenterY?: number;\n\tcenterZ?: number;\n}\n\nexport interface Bounds3DHits {\n\tleft: boolean;\n\tright: boolean;\n\ttop: boolean;\n\tbottom: boolean;\n\tback: boolean;\n\tfront: boolean;\n}\n\nexport interface Bounds3DPadding {\n\tx: number;\n\ty: number;\n\tz: number;\n}\n\nexport type Bounds3DPaddingInput =\n\t| number\n\t| Partial<Bounds3DPadding>\n\t| undefined;\n\nexport function createBounds3DBox({\n\twidth,\n\theight,\n\tdepth,\n\tcenterX = 0,\n\tcenterY = 0,\n\tcenterZ = 0,\n}: Bounds3DSize): Bounds3DBox {\n\tconst halfWidth = width / 2;\n\tconst halfHeight = height / 2;\n\tconst halfDepth = depth / 2;\n\treturn {\n\t\tminX: centerX - halfWidth,\n\t\tmaxX: centerX + halfWidth,\n\t\tminY: centerY - halfHeight,\n\t\tmaxY: centerY + halfHeight,\n\t\tminZ: centerZ - halfDepth,\n\t\tmaxZ: centerZ + halfDepth,\n\t};\n}\n\nexport function normalizeBounds3DPadding(\n\tpadding?: Bounds3DPaddingInput,\n): Bounds3DPadding {\n\tif (typeof padding === 'number') {\n\t\treturn { x: padding, y: padding, z: padding };\n\t}\n\n\treturn {\n\t\tx: padding?.x ?? 0,\n\t\ty: padding?.y ?? 0,\n\t\tz: padding?.z ?? 0,\n\t};\n}\n\nexport function insetBounds3D(\n\tbounds: Bounds3DBox,\n\tpadding?: Bounds3DPaddingInput,\n): Bounds3DBox {\n\tconst resolved = normalizeBounds3DPadding(padding);\n\treturn {\n\t\tminX: bounds.minX + resolved.x,\n\t\tmaxX: bounds.maxX - resolved.x,\n\t\tminY: bounds.minY + resolved.y,\n\t\tmaxY: bounds.maxY - resolved.y,\n\t\tminZ: bounds.minZ + resolved.z,\n\t\tmaxZ: bounds.maxZ - resolved.z,\n\t};\n}\n\nexport function computeBounds3DHits(\n\tposition: Bounds3DPoint,\n\tbounds: Bounds3DBox,\n): Bounds3DHits {\n\tconst hits: Bounds3DHits = {\n\t\tleft: false,\n\t\tright: false,\n\t\ttop: false,\n\t\tbottom: false,\n\t\tback: false,\n\t\tfront: false,\n\t};\n\n\tif (position.x <= bounds.minX) hits.left = true;\n\telse if (position.x >= bounds.maxX) hits.right = true;\n\n\tif (position.y <= bounds.minY) hits.bottom = true;\n\telse if (position.y >= bounds.maxY) hits.top = true;\n\n\tif (position.z <= bounds.minZ) hits.back = true;\n\telse if (position.z >= bounds.maxZ) hits.front = true;\n\n\treturn hits;\n}\n\nexport function hasAnyBounds3DHit(hits: Bounds3DHits): boolean {\n\treturn hits.left || hits.right || hits.top || hits.bottom || hits.back || hits.front;\n}\n\nexport function constrainMovementToBounds3D(\n\thits: Bounds3DHits,\n\tmoveX: number,\n\tmoveY: number,\n\tmoveZ: number,\n): { moveX: number; moveY: number; moveZ: number } {\n\tlet adjustedX = moveX;\n\tlet adjustedY = moveY;\n\tlet adjustedZ = moveZ;\n\n\tif ((hits.left && moveX < 0) || (hits.right && moveX > 0)) {\n\t\tadjustedX = 0;\n\t}\n\n\tif ((hits.bottom && moveY < 0) || (hits.top && moveY > 0)) {\n\t\tadjustedY = 0;\n\t}\n\n\tif ((hits.back && moveZ < 0) || (hits.front && moveZ > 0)) {\n\t\tadjustedZ = 0;\n\t}\n\n\treturn { moveX: adjustedX, moveY: adjustedY, moveZ: adjustedZ };\n}\n\nexport function clampPointToBounds3D(\n\tposition: Bounds3DPoint,\n\tbounds: Bounds3DBox,\n): Bounds3DPoint {\n\treturn {\n\t\tx: Math.min(bounds.maxX, Math.max(bounds.minX, position.x)),\n\t\ty: Math.min(bounds.maxY, Math.max(bounds.minY, position.y)),\n\t\tz: Math.min(bounds.maxZ, Math.max(bounds.minZ, position.z)),\n\t};\n}\n\nexport function getBounds3DNormalFromHits(\n\thits: Bounds3DHits,\n): { x: number; y: number; z: number } {\n\tlet x = 0;\n\tlet y = 0;\n\tlet z = 0;\n\n\tif (hits.left) x = 1;\n\tif (hits.right) x = -1;\n\tif (hits.bottom) y = 1;\n\tif (hits.top) y = -1;\n\tif (hits.back) z = 1;\n\tif (hits.front) z = -1;\n\n\treturn { x, y, z };\n}\n","import { SyncStateMachine, t } from '../../core/utility/sync-state-machine';\nimport {\n\tclampPointToBounds3D,\n\tcomputeBounds3DHits,\n\tconstrainMovementToBounds3D,\n\thasAnyBounds3DHit,\n\tinsetBounds3D,\n\ttype Bounds3DPaddingInput,\n\ttype Bounds3DPoint,\n} from '../shared/bounds-3d';\n\nexport type WorldBoundary3DHit =\n\t| 'top'\n\t| 'bottom'\n\t| 'left'\n\t| 'right'\n\t| 'back'\n\t| 'front';\n\nexport type WorldBoundary3DHits = Record<WorldBoundary3DHit, boolean>;\n\nexport interface WorldBoundary3DPosition extends Bounds3DPoint {}\n\nexport interface WorldBoundary3DBounds {\n\ttop: number;\n\tbottom: number;\n\tleft: number;\n\tright: number;\n\tback: number;\n\tfront: number;\n}\n\nexport enum WorldBoundary3DState {\n\tInside = 'inside',\n\tTouching = 'touching',\n}\n\nexport enum WorldBoundary3DEvent {\n\tEnterInside = 'enter-inside',\n\tTouchBoundary = 'touch-boundary',\n}\n\nexport function computeWorldBoundary3DHits(\n\tposition: WorldBoundary3DPosition,\n\tbounds: WorldBoundary3DBounds,\n\tpadding?: Bounds3DPaddingInput,\n): WorldBoundary3DHits {\n\treturn computeBounds3DHits(position, insetBounds3D({\n\t\tminX: bounds.left,\n\t\tmaxX: bounds.right,\n\t\tminY: bounds.bottom,\n\t\tmaxY: bounds.top,\n\t\tminZ: bounds.back,\n\t\tmaxZ: bounds.front,\n\t}, padding));\n}\n\nexport function hasAnyWorldBoundary3DHit(hits: WorldBoundary3DHits): boolean {\n\treturn hasAnyBounds3DHit(hits);\n}\n\nexport class WorldBoundary3DFSM {\n\tpublic readonly machine: SyncStateMachine<WorldBoundary3DState, WorldBoundary3DEvent, never>;\n\n\tprivate lastHits: WorldBoundary3DHits = {\n\t\ttop: false,\n\t\tbottom: false,\n\t\tleft: false,\n\t\tright: false,\n\t\tback: false,\n\t\tfront: false,\n\t};\n\tprivate lastPosition: WorldBoundary3DPosition | null = null;\n\tprivate lastClampedPosition: WorldBoundary3DPosition | null = null;\n\tprivate lastUpdatedAtMs: number | null = null;\n\n\tconstructor() {\n\t\tthis.machine = new SyncStateMachine<WorldBoundary3DState, WorldBoundary3DEvent, never>(\n\t\t\tWorldBoundary3DState.Inside,\n\t\t\t[\n\t\t\t\tt(WorldBoundary3DState.Inside, WorldBoundary3DEvent.TouchBoundary, WorldBoundary3DState.Touching),\n\t\t\t\tt(WorldBoundary3DState.Touching, WorldBoundary3DEvent.EnterInside, WorldBoundary3DState.Inside),\n\t\t\t\tt(WorldBoundary3DState.Inside, WorldBoundary3DEvent.EnterInside, WorldBoundary3DState.Inside),\n\t\t\t\tt(WorldBoundary3DState.Touching, WorldBoundary3DEvent.TouchBoundary, WorldBoundary3DState.Touching),\n\t\t\t],\n\t\t);\n\t}\n\n\tgetState(): WorldBoundary3DState {\n\t\treturn this.machine.getState();\n\t}\n\n\tgetLastHits(): WorldBoundary3DHits {\n\t\treturn this.lastHits;\n\t}\n\n\tgetMovement(\n\t\tmoveX: number,\n\t\tmoveY: number,\n\t\tmoveZ: number,\n\t): { moveX: number; moveY: number; moveZ: number } {\n\t\treturn constrainMovementToBounds3D(this.lastHits, moveX, moveY, moveZ);\n\t}\n\n\tgetLastPosition(): WorldBoundary3DPosition | null {\n\t\treturn this.lastPosition;\n\t}\n\n\tgetLastClampedPosition(): WorldBoundary3DPosition | null {\n\t\treturn this.lastClampedPosition;\n\t}\n\n\tgetLastUpdatedAtMs(): number | null {\n\t\treturn this.lastUpdatedAtMs;\n\t}\n\n\tupdate(\n\t\tposition: WorldBoundary3DPosition,\n\t\tbounds: WorldBoundary3DBounds,\n\t\tpadding?: Bounds3DPaddingInput,\n\t): WorldBoundary3DHits {\n\t\tconst effectiveBounds = insetBounds3D({\n\t\t\tminX: bounds.left,\n\t\t\tmaxX: bounds.right,\n\t\t\tminY: bounds.bottom,\n\t\t\tmaxY: bounds.top,\n\t\t\tminZ: bounds.back,\n\t\t\tmaxZ: bounds.front,\n\t\t}, padding);\n\n\t\tconst hits = computeBounds3DHits(position, effectiveBounds);\n\t\tthis.lastHits = hits;\n\t\tthis.lastPosition = { x: position.x, y: position.y, z: position.z };\n\t\tthis.lastClampedPosition = clampPointToBounds3D(position, effectiveBounds);\n\t\tthis.lastUpdatedAtMs = Date.now();\n\n\t\tif (hasAnyWorldBoundary3DHit(hits)) {\n\t\t\tthis.dispatch(WorldBoundary3DEvent.TouchBoundary);\n\t\t} else {\n\t\t\tthis.dispatch(WorldBoundary3DEvent.EnterInside);\n\t\t}\n\n\t\treturn hits;\n\t}\n\n\tprivate dispatch(event: WorldBoundary3DEvent): void {\n\t\tif (this.machine.can(event)) {\n\t\t\tthis.machine.syncDispatch(event);\n\t\t}\n\t}\n}\n","import type { IWorld } from 'bitecs';\nimport { defineBehavior, type BehaviorRef } from '../behavior-descriptor';\nimport type { BehaviorEntityLink, BehaviorSystem } from '../behavior-system';\nimport type { Bounds3DPaddingInput } from '../shared/bounds-3d';\nimport {\n\tWorldBoundary3DFSM,\n\ttype WorldBoundary3DBounds,\n\ttype WorldBoundary3DHits,\n\ttype WorldBoundary3DPosition,\n} from './world-boundary-3d-fsm';\n\nexport interface WorldBoundary3DOptions {\n\tboundaries: WorldBoundary3DBounds;\n\tpadding?: Bounds3DPaddingInput;\n}\n\nexport interface WorldBoundary3DHandle {\n\tgetLastHits(): WorldBoundary3DHits | null;\n\tgetMovement(\n\t\tmoveX: number,\n\t\tmoveY: number,\n\t\tmoveZ: number,\n\t): { moveX: number; moveY: number; moveZ: number };\n\tgetLastClampedPosition(): WorldBoundary3DPosition | null;\n}\n\nconst defaultOptions: WorldBoundary3DOptions = {\n\tboundaries: { top: 0, bottom: 0, left: 0, right: 0, back: 0, front: 0 },\n\tpadding: 0,\n};\n\nconst WORLD_BOUNDARY_3D_BEHAVIOR_KEY = Symbol.for(\n\t'zylem:behavior:world-boundary-3d',\n);\n\nfunction createWorldBoundary3DHandle(\n\tref: BehaviorRef<WorldBoundary3DOptions>,\n): WorldBoundary3DHandle {\n\treturn {\n\t\tgetLastHits: () => {\n\t\t\tconst fsm = ref.fsm as WorldBoundary3DFSM | undefined;\n\t\t\treturn fsm?.getLastHits() ?? null;\n\t\t},\n\t\tgetMovement: (moveX: number, moveY: number, moveZ: number) => {\n\t\t\tconst fsm = ref.fsm as WorldBoundary3DFSM | undefined;\n\t\t\treturn fsm?.getMovement(moveX, moveY, moveZ) ?? { moveX, moveY, moveZ };\n\t\t},\n\t\tgetLastClampedPosition: () => {\n\t\t\tconst fsm = ref.fsm as WorldBoundary3DFSM | undefined;\n\t\t\treturn fsm?.getLastClampedPosition() ?? null;\n\t\t},\n\t};\n}\n\nclass WorldBoundary3DSystem implements BehaviorSystem {\n\tconstructor(\n\t\tprivate world: any,\n\t\tprivate getBehaviorLinks?: (key: symbol) => Iterable<BehaviorEntityLink>,\n\t) {}\n\n\tupdate(_ecs: IWorld, _delta: number): void {\n\t\tconst links = this.getBehaviorLinks?.(WORLD_BOUNDARY_3D_BEHAVIOR_KEY);\n\t\tif (!links) return;\n\n\t\tfor (const link of links) {\n\t\t\tconst gameEntity = link.entity as any;\n\t\t\tconst boundaryRef = link.ref as any;\n\t\t\tif (!gameEntity.body) continue;\n\n\t\t\tconst options = boundaryRef.options as WorldBoundary3DOptions;\n\t\t\tif (!boundaryRef.fsm) {\n\t\t\t\tboundaryRef.fsm = new WorldBoundary3DFSM();\n\t\t\t}\n\n\t\t\tconst pos = gameEntity.body.translation();\n\t\t\tboundaryRef.fsm.update(\n\t\t\t\t{ x: pos.x, y: pos.y, z: pos.z },\n\t\t\t\toptions.boundaries,\n\t\t\t\toptions.padding,\n\t\t\t);\n\t\t}\n\t}\n\n\tdestroy(_ecs: IWorld): void {}\n}\n\nexport const WorldBoundary3DBehavior = defineBehavior({\n\tname: 'world-boundary-3d',\n\tdefaultOptions,\n\tsystemFactory: (ctx) =>\n\t\tnew WorldBoundary3DSystem(ctx.world, ctx.getBehaviorLinks),\n\tcreateHandle: createWorldBoundary3DHandle,\n});\n"],"mappings":"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","names":["WorldBoundary3DState","WorldBoundary3DEvent"]}

package/dist/behavior-descriptor-BXnVR8Ki.d.ts

@@ -0,0 +1,159 @@
+import { IWorld } from 'bitecs';
+
+/**
+ * BehaviorSystem Interface
+ *
+ * Base interface for ECS-based behavior systems that run at the stage level.
+ * Systems query entities with matching components and process them each frame.
+ */
+
+/**
+ * A behavior system that processes entities with specific components.
+ *
+ * @example
+ * ```typescript
+ * class ThrusterMovementSystem implements BehaviorSystem {
+ *   update(ecs: IWorld, delta: number): void {
+ *     // Query and process entities with thruster components
+ *   }
+ * }
+ * ```
+ */
+interface BehaviorSystem {
+    /** Called once per frame with ECS world and delta time */
+    update(ecs: IWorld, delta: number): void;
+    /** Optional cleanup when stage is destroyed */
+    destroy?(ecs: IWorld): void;
+}
+/**
+ * Runtime link between a spawned entity and one of its behavior refs.
+ * Systems can iterate these links to avoid scanning all world entities.
+ */
+interface BehaviorEntityLink {
+    entity: any;
+    ref: any;
+}
+/**
+ * Context provided to behavior-system factories.
+ */
+interface BehaviorSystemContext {
+    world: any;
+    ecs: IWorld;
+    scene: any;
+    /**
+     * Returns live behavior links for a descriptor key.
+     * O(1) lookup into a pre-built stage index.
+     */
+    getBehaviorLinks?: (key: symbol) => Iterable<BehaviorEntityLink>;
+}
+/**
+ * Factory function that creates a BehaviorSystem.
+ * Receives the stage for access to world, scene, etc.
+ */
+type BehaviorSystemFactory<T extends BehaviorSystem = BehaviorSystem> = (stage: BehaviorSystemContext) => T;
+
+/**
+ * BehaviorDescriptor
+ *
+ * Type-safe behavior descriptors that provide options inference.
+ * Used with entity.use() to declaratively attach behaviors to entities.
+ *
+ * Each behavior can define its own handle type via `createHandle`,
+ * providing behavior-specific methods with full type safety.
+ */
+
+/**
+ * Base handle returned by entity.use() for lazy access to behavior runtime.
+ * FSM is null until entity is spawned and components are initialized.
+ */
+interface BaseBehaviorHandle<O extends Record<string, any> = Record<string, any>> {
+    /** Get the FSM instance (null until entity is spawned) */
+    getFSM(): any | null;
+    /** Get the current options */
+    getOptions(): O;
+    /** Access the underlying behavior ref */
+    readonly ref: BehaviorRef<O>;
+}
+/**
+ * Reference to a behavior stored on an entity
+ */
+interface BehaviorRef<O extends Record<string, any> = Record<string, any>> {
+    /** The behavior descriptor */
+    descriptor: BehaviorDescriptor<O, any>;
+    /** Merged options (defaults + overrides) */
+    options: O;
+    /** Optional FSM instance - set lazily when entity is spawned */
+    fsm?: any;
+}
+/**
+ * A typed behavior descriptor that associates a symbol key with:
+ * - Default options (providing type inference)
+ * - A system factory to create the behavior system
+ * - An optional handle factory for behavior-specific methods
+ */
+interface BehaviorDescriptor<O extends Record<string, any> = Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown> {
+    /** Unique symbol identifying this behavior */
+    readonly key: symbol;
+    /** Default options (used for type inference) */
+    readonly defaultOptions: O;
+    /** Factory to create the behavior system */
+    readonly systemFactory: BehaviorSystemFactory;
+    /**
+     * Optional factory to create behavior-specific handle methods.
+     * These methods are merged into the handle returned by entity.use().
+     */
+    readonly createHandle?: (ref: BehaviorRef<O>) => H;
+}
+/**
+ * The full handle type returned by entity.use().
+ * Combines base handle with behavior-specific methods.
+ */
+type BehaviorHandle<O extends Record<string, any> = Record<string, any>, H extends Record<string, any> = Record<string, never>> = BaseBehaviorHandle<O> & H;
+/**
+ * Configuration for defining a new behavior
+ */
+interface DefineBehaviorConfig<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown> {
+    /** Human-readable name for debugging */
+    name: string;
+    /** Default options - these define the type */
+    defaultOptions: O;
+    /** Factory function to create the system */
+    systemFactory: BehaviorSystemFactory;
+    /**
+     * Optional factory to create behavior-specific handle methods.
+     * The returned object is merged into the handle returned by entity.use().
+     *
+     * @example
+     * ```typescript
+     * createHandle: (ref) => ({
+     *   getLastHits: () => ref.fsm?.getLastHits() ?? null,
+     *   getMovement: (moveX, moveY) => ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },
+     * }),
+     * ```
+     */
+    createHandle?: (ref: BehaviorRef<O>) => H;
+}
+/**
+ * Define a typed behavior descriptor.
+ *
+ * @example
+ * ```typescript
+ * export const WorldBoundary2DBehavior = defineBehavior({
+ *   name: 'world-boundary-2d',
+ *   defaultOptions: { boundaries: { top: 0, bottom: 0, left: 0, right: 0 } },
+ *   systemFactory: (ctx) => new WorldBoundary2DSystem(ctx.world),
+ *   createHandle: (ref) => ({
+ *     getLastHits: () => ref.fsm?.getLastHits() ?? null,
+ *     getMovement: (moveX: number, moveY: number) =>
+ *       ref.fsm?.getMovement(moveX, moveY) ?? { moveX, moveY },
+ *   }),
+ * });
+ *
+ * // Usage - handle has getLastHits and getMovement with full types
+ * const boundary = ship.use(WorldBoundary2DBehavior, { ... });
+ * const hits = boundary.getLastHits(); // Fully typed!
+ * ```
+ */
+declare function defineBehavior<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>, I = unknown>(config: DefineBehaviorConfig<O, H, I>): BehaviorDescriptor<O, H, I>;
+
+export { type BehaviorSystem as B, type DefineBehaviorConfig as D, type BehaviorEntityLink as a, type BehaviorSystemFactory as b, type BehaviorDescriptor as c, type BehaviorHandle as d, type BehaviorRef as e, defineBehavior as f };

package/dist/{blueprints-Cq3Ko6_G.d.ts → blueprints-DmbK2dki.d.ts}

@@ -1,6 +1,6 @@
 import { Vector2 } from 'three';
-import { G as GameEntity } from './world-C8tQ7Plj.js';
-import { b as Stage } from './stage-types-Bd-KtcYT.js';
+import { I as GameEntity } from './entity-vj-HTjzU.js';
+import { b as Stage } from './stage-types-C19IhuzA.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';