@zylem/behaviors 0.4.0 → 0.5.1

package/dist/core.js

@@ -2,15 +2,7 @@ import {
   createPhysicsBodyComponent,
   createTransformComponent,
   useBehavior
-} from "./chunk-UYFOLI2X.js";
-import {
-  StageBodyKind,
-  StageBoundaryDim,
-  StageEventType,
-  StageRicochetDim,
-  StageRicochetReflection,
-  StageTopDownPlane
-} from "./chunk-4V7TIRO2.js";
+} from "./chunk-5A5AYP2C.js";
 import {
   VEC2_ONE,
   VEC2_ZERO,
@@ -20,21 +12,36 @@ import {
   isVec3Input,
   normalizeVec2,
   normalizeVec3,
-  toRapierVector3,
   toThreeVector2,
   toThreeVector3
-} from "./chunk-WWVD5DR5.js";
-import {
-  clearVelocityIntent,
-  setVelocityIntent
-} from "./chunk-OTLSUYQQ.js";
+} from "./chunk-M3QDKKDF.js";
 import {
   SyncStateMachine,
-  t
-} from "./chunk-4URF65BR.js";
+  import_typescript_fsm
+} from "./chunk-AS3HR7AS.js";
+import {
+  STAGE_EVENT_STRIDE,
+  STAGE_INPUT_BUTTON_JUMP,
+  STAGE_INPUT_BUTTON_RUN,
+  STAGE_INPUT_STRIDE,
+  STAGE_INVALID_SLOT,
+  STAGE_RENDER_STRIDE,
+  STAGE_SNAPSHOT_STRIDE,
+  StageBodyKind,
+  StageBoundaryDim,
+  StageEventType,
+  StageRicochetDim,
+  StageRicochetReflection,
+  StageTopDownPlane,
+  WasmStageRuntime,
+  createWasmStageRuntime,
+  readBehaviorSnapshot,
+  readStageRenderSlot
+} from "./chunk-E4X4YJZB.js";
 import {
   defineBehavior
 } from "./chunk-EZNCCO4L.js";
+import "./chunk-5WRI5ZAA.js";
 
 // src/lib/capabilities/transform-store.ts
 import { proxy } from "valtio";
@@ -66,6 +73,30 @@ function createTransformStore(initial) {
   });
 }
 
+// src/lib/capabilities/velocity-intents.ts
+function setVelocityIntent(store, sourceId, vector, options = {}) {
+  const prev = store.velocityChannels[sourceId];
+  const mode = options.mode ?? prev?.mode ?? "replace";
+  const priority = options.priority ?? prev?.priority ?? 0;
+  const isAdditiveMerge = mode === "add" && prev?.mode === "add";
+  const x = vector.x == null ? prev?.x : isAdditiveMerge ? (prev?.x ?? 0) + vector.x : vector.x;
+  const y = vector.y == null ? prev?.y : isAdditiveMerge ? (prev?.y ?? 0) + vector.y : vector.y;
+  const z = vector.z == null ? prev?.z : isAdditiveMerge ? (prev?.z ?? 0) + vector.z : vector.z;
+  store.velocityChannels[sourceId] = {
+    x,
+    y,
+    z,
+    mode,
+    priority
+  };
+  store.dirty.velocityChannels = true;
+}
+function clearVelocityIntent(store, sourceId) {
+  if (!(sourceId in store.velocityChannels)) return;
+  delete store.velocityChannels[sourceId];
+  store.dirty.velocityChannels = true;
+}
+
 // src/lib/capabilities/moveable.ts
 import { Vector3 } from "three";
 function moveX(entity, delta) {
@@ -189,6 +220,433 @@ function makeMoveable(entity) {
   return moveable;
 }
 
+// src/lib/runtime/mock-behavior-runtime.ts
+function freshSlot() {
+  return {
+    pose: { position: [0, 0, 0], rotation: [0, 0, 0, 1] },
+    snapshot: null,
+    input: { axisA: 0, axisB: 0, yawDelta: 0, pitchDelta: 0, reservedA: 0, reservedB: 0, buttons: 0 },
+    attachments: /* @__PURE__ */ new Map(),
+    inputs: [],
+    screenWrapQuery: null,
+    worldBoundaryQuery: null
+  };
+}
+var MockBehaviorRuntime = class {
+  slots = /* @__PURE__ */ new Map();
+  slot(handle) {
+    let state = this.slots.get(handle);
+    if (!state) {
+      state = freshSlot();
+      this.slots.set(handle, state);
+    }
+    return state;
+  }
+  // ─── Test seams ─────────────────────────────────────────────────────
+  /** Seed the pose returned by {@link getPose} for a handle. */
+  setPose(handle, pose) {
+    this.slot(handle).pose = pose;
+  }
+  /** Seed the snapshot returned by {@link readSnapshot} for a handle. */
+  setSnapshot(handle, snapshot) {
+    this.slot(handle).snapshot = snapshot;
+  }
+  /** Seed {@link queryScreenWrap} results. */
+  setScreenWrapQuery(handle, value) {
+    this.slot(handle).screenWrapQuery = value;
+  }
+  /** Seed {@link queryWorldBoundary} results. */
+  setWorldBoundaryQuery(handle, value) {
+    this.slot(handle).worldBoundaryQuery = value;
+  }
+  /** Attachment options recorded for a handle, keyed by behavior name. */
+  getAttachment(handle, kind) {
+    return this.slots.get(handle)?.attachments.get(kind);
+  }
+  hasAttachment(handle, kind) {
+    return this.slots.get(handle)?.attachments.has(kind) ?? false;
+  }
+  /** Every per-entity input call recorded for a handle, oldest first. */
+  getInputCalls(handle) {
+    return this.slots.get(handle)?.inputs ?? [];
+  }
+  /** Last written batched-input state for a handle. */
+  getBatchedInput(handle) {
+    return this.slot(handle).input;
+  }
+  reset() {
+    this.slots.clear();
+  }
+  // ─── BehaviorRuntime contract ───────────────────────────────────────
+  setPosition(handle, x, y, z) {
+    const pose = this.slot(handle).pose;
+    pose.position[0] = x;
+    pose.position[1] = y;
+    pose.position[2] = z;
+    return true;
+  }
+  setRotation(handle, x, y, z, w) {
+    const pose = this.slot(handle).pose;
+    pose.rotation[0] = x;
+    pose.rotation[1] = y;
+    pose.rotation[2] = z;
+    pose.rotation[3] = w;
+    return true;
+  }
+  getPose(handle, out) {
+    const state = this.slots.get(handle);
+    if (!state) return null;
+    const result = out ?? { position: [0, 0, 0], rotation: [0, 0, 0, 1] };
+    result.position[0] = state.pose.position[0];
+    result.position[1] = state.pose.position[1];
+    result.position[2] = state.pose.position[2];
+    result.rotation[0] = state.pose.rotation[0];
+    result.rotation[1] = state.pose.rotation[1];
+    result.rotation[2] = state.pose.rotation[2];
+    result.rotation[3] = state.pose.rotation[3];
+    return result;
+  }
+  writeInputAxes(handle, axisA, axisB) {
+    const input = this.slot(handle).input;
+    input.axisA = axisA;
+    input.axisB = axisB;
+    return true;
+  }
+  writeInputLook(handle, yawDelta, pitchDelta) {
+    const input = this.slot(handle).input;
+    input.yawDelta = yawDelta;
+    input.pitchDelta = pitchDelta;
+    return true;
+  }
+  writeInputReserved(handle, reservedA, reservedB) {
+    const input = this.slot(handle).input;
+    input.reservedA = reservedA;
+    input.reservedB = reservedB;
+    return true;
+  }
+  writeInputButton(handle, buttonMask, pressed) {
+    const input = this.slot(handle).input;
+    input.buttons = pressed ? input.buttons | buttonMask : input.buttons & ~buttonMask;
+    return true;
+  }
+  readSnapshot(handle, out) {
+    const snapshot = this.slots.get(handle)?.snapshot ?? null;
+    if (!snapshot) return null;
+    if (!out) return { ...snapshot };
+    Object.assign(out, snapshot);
+    return out;
+  }
+  attachThruster(handle, opts) {
+    this.slot(handle).attachments.set("thruster", opts);
+    return true;
+  }
+  setThrusterInput(handle, thrust, rotate, vectorX = 0, vectorY = 0) {
+    this.slot(handle).inputs.push({
+      kind: "thruster",
+      args: [thrust, rotate, vectorX, vectorY]
+    });
+  }
+  attachTopDown(handle, opts) {
+    this.slot(handle).attachments.set("topDown", opts);
+    return true;
+  }
+  setTopDownInput(handle, moveX2, moveY2) {
+    this.slot(handle).inputs.push({ kind: "topDown", args: [moveX2, moveY2] });
+  }
+  attachShooter2D(handle, opts) {
+    this.slot(handle).attachments.set("shooter2d", opts);
+    return true;
+  }
+  attachScreenWrap(handle, opts) {
+    this.slot(handle).attachments.set("screenWrap", opts);
+    return true;
+  }
+  queryScreenWrap(handle) {
+    return this.slots.get(handle)?.screenWrapQuery ?? null;
+  }
+  attachWorldBoundary(handle, dim, opts) {
+    this.slot(handle).attachments.set("worldBoundary", { dim, ...opts });
+    return true;
+  }
+  queryWorldBoundary(handle) {
+    return this.slots.get(handle)?.worldBoundaryQuery ?? null;
+  }
+  attachRicochet(handle, dim, opts) {
+    this.slot(handle).attachments.set("ricochet", { dim, ...opts });
+    return true;
+  }
+  attachPlatformer3D(handle, opts) {
+    this.slot(handle).attachments.set("platformer3d", opts);
+    return true;
+  }
+  setPlatformer3DInputAxes(handle, moveX2, moveZ2) {
+    this.slot(handle).inputs.push({ kind: "platformer3dAxes", args: [moveX2, moveZ2] });
+  }
+  setPlatformer3DInputButtons(handle, jump, run) {
+    this.slot(handle).inputs.push({ kind: "platformer3dButtons", args: [jump, run] });
+  }
+  attachPlatformer2D(handle, opts) {
+    this.slot(handle).attachments.set("platformer2d", opts);
+    return true;
+  }
+  setPlatformer2DInputAxes(handle, moveX2) {
+    this.slot(handle).inputs.push({ kind: "platformer2dAxes", args: [moveX2] });
+  }
+  setPlatformer2DInputButtons(handle, jump, run) {
+    this.slot(handle).inputs.push({ kind: "platformer2dButtons", args: [jump, run] });
+  }
+  attachFirstPerson(handle, opts) {
+    this.slot(handle).attachments.set("firstPerson", opts);
+    return true;
+  }
+  setFirstPersonInput(handle, input) {
+    this.slot(handle).inputs.push({ kind: "firstPerson", args: [input] });
+  }
+  attachJumper2D(handle, opts) {
+    this.slot(handle).attachments.set("jumper2d", opts);
+    return true;
+  }
+  setJumper2DInput(handle, jumpPressed) {
+    this.slot(handle).inputs.push({ kind: "jumper2d", args: [jumpPressed] });
+  }
+  attachJumper3D(handle, opts) {
+    this.slot(handle).attachments.set("jumper3d", opts);
+    return true;
+  }
+  setJumper3DInput(handle, jumpPressed) {
+    this.slot(handle).inputs.push({ kind: "jumper3d", args: [jumpPressed] });
+  }
+};
+
+// src/lib/runtime/simulation.ts
+var DEFAULT_FIXED_TIMESTEP = 1 / 60;
+var DEFAULT_MAX_SUB_STEPS = 4;
+var Simulation = class {
+  /**
+   * The low-level wasm adapter. Behavior systems receive this as their
+   * `wasmStage` context so descriptors can attach/query behaviors by slot;
+   * hosts should prefer the handle-based methods on the Simulation itself.
+   */
+  adapter;
+  fixedTimestep;
+  maxSubSteps;
+  accumulator = 0;
+  nextEntityId = 1;
+  slotToHandle = /* @__PURE__ */ new Map();
+  idToHandle = /* @__PURE__ */ new Map();
+  previousRender = new Float32Array(0);
+  disposed = false;
+  constructor(adapter, options = {}) {
+    this.adapter = adapter;
+    this.fixedTimestep = options.fixedTimestep ?? DEFAULT_FIXED_TIMESTEP;
+    this.maxSubSteps = Math.max(1, options.maxSubSteps ?? DEFAULT_MAX_SUB_STEPS);
+  }
+  // ─── Entity lifecycle ───────────────────────────────────────────────
+  /**
+   * Create a runtime entity from a plain definition. Returns `null` when
+   * the runtime rejects the allocation.
+   */
+  spawn(definition = {}) {
+    const slot = this.adapter.createEntity();
+    if (slot === 4294967295) return null;
+    const body = definition.body;
+    const bodyConfig = {
+      kind: body?.kind ?? StageBodyKind.Dynamic,
+      position: body?.position ?? [0, 0, 0],
+      rotation: body?.rotation ?? [0, 0, 0, 1],
+      linearDamping: body?.linearDamping ?? 0,
+      angularDamping: body?.angularDamping ?? 0,
+      gravityScale: body?.gravityScale ?? 1,
+      canSleep: body?.canSleep ?? false,
+      ccdEnabled: body?.ccdEnabled ?? true,
+      lockRotation: body?.lockRotation ?? [false, false, false],
+      lockTranslation: body?.lockTranslation ?? [false, false, false]
+    };
+    this.adapter.attachBody(slot, bodyConfig);
+    for (const collider of definition.colliders ?? []) {
+      const config = {
+        shape: collider.shape,
+        offset: collider.offset ?? [0, 0, 0],
+        friction: collider.friction ?? 0.5,
+        restitution: collider.restitution ?? 0,
+        sensor: collider.sensor ?? false,
+        collisionGroups: collider.collisionGroups ?? 4294967295
+      };
+      this.adapter.addCollider(slot, config);
+    }
+    const handle = { id: this.nextEntityId++, slot };
+    this.slotToHandle.set(slot, handle);
+    this.idToHandle.set(handle.id, handle);
+    return handle;
+  }
+  despawn(handle) {
+    const registered = this.idToHandle.get(handle.id);
+    if (!registered) return false;
+    this.idToHandle.delete(handle.id);
+    if (this.slotToHandle.get(registered.slot) === registered) {
+      this.slotToHandle.delete(registered.slot);
+    }
+    return this.adapter.destroyEntity(registered.slot);
+  }
+  /** Resolve a raw runtime slot back to its public handle, if alive. */
+  handleForSlot(slot) {
+    return this.slotToHandle.get(slot) ?? null;
+  }
+  get entityCount() {
+    return this.idToHandle.size;
+  }
+  // ─── Per-frame update ───────────────────────────────────────────────
+  /**
+   * Advance the simulation by `deltaTime` seconds using a fixed-timestep
+   * accumulator. Runs zero or more fixed steps and returns a
+   * {@link SimulationFrame} with translated events and interpolation data.
+   */
+  update(deltaTime) {
+    const events = [];
+    this.accumulator += Math.max(0, deltaTime);
+    let steps = 0;
+    while (this.accumulator >= this.fixedTimestep && steps < this.maxSubSteps) {
+      this.capturePreviousRender();
+      this.adapter.step(this.fixedTimestep);
+      this.translateEvents(this.adapter.drainEvents(), events);
+      this.accumulator -= this.fixedTimestep;
+      steps++;
+    }
+    if (steps === this.maxSubSteps && this.accumulator >= this.fixedTimestep) {
+      this.accumulator = this.accumulator % this.fixedTimestep;
+    }
+    return {
+      deltaTime,
+      stepsTaken: steps,
+      alpha: this.fixedTimestep > 0 ? this.accumulator / this.fixedTimestep : 0,
+      render: this.adapter.render,
+      previousRender: this.previousRender,
+      renderStride: STAGE_RENDER_STRIDE,
+      events
+    };
+  }
+  capturePreviousRender() {
+    const current = this.adapter.render;
+    if (this.previousRender.length !== current.length) {
+      this.previousRender = new Float32Array(current.length);
+    }
+    this.previousRender.set(current);
+  }
+  translateEvents(raw, out) {
+    for (const event of raw) {
+      const primary = event.primarySlot !== null ? this.handleForSlot(event.primarySlot) : null;
+      const secondary = event.secondarySlot !== null ? this.handleForSlot(event.secondarySlot) : null;
+      switch (event.type) {
+        case StageEventType.CollisionStarted:
+        case StageEventType.CollisionStopped:
+          out.push({
+            type: event.type === StageEventType.CollisionStarted ? "collisionStarted" : "collisionStopped",
+            a: primary,
+            b: secondary,
+            sensor: event.payload[0] !== 0,
+            normal: [event.payload[1], event.payload[2]]
+          });
+          break;
+        case StageEventType.BoundaryHit:
+          out.push({
+            type: "boundaryHit",
+            entity: primary,
+            axes: event.payload[0] | 0,
+            signs: event.payload[1] | 0
+          });
+          break;
+        case StageEventType.Ricochet:
+          out.push({ type: "ricochet", entity: primary, kind: event.payload[0] | 0 });
+          break;
+        case StageEventType.RegionEntered:
+          out.push({ type: "regionEntered", entity: primary, triggerId: event.payload[0] | 0 });
+          break;
+        case StageEventType.JumpStarted:
+          out.push({ type: "jumpStarted", entity: primary, jumpCount: event.payload[0] | 0 });
+          break;
+        case StageEventType.Landed:
+          out.push({ type: "landed", entity: primary });
+          break;
+        case StageEventType.Wrapped:
+          out.push({ type: "wrapped", entity: primary, axes: event.payload[0] | 0 });
+          break;
+        case StageEventType.CooldownFired:
+          out.push({ type: "cooldownFired", entity: primary, cooldownId: event.payload[0] | 0 });
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  // ─── Handle-based reads / writes ────────────────────────────────────
+  getPose(handle, out) {
+    return this.adapter.getPose(handle.slot, out);
+  }
+  setPosition(handle, x, y, z) {
+    return this.adapter.setPosition(handle.slot, x, y, z);
+  }
+  setRotation(handle, x, y, z, w) {
+    return this.adapter.setRotation(handle.slot, x, y, z, w);
+  }
+  setLinearVelocity(handle, x, y, z) {
+    return this.adapter.setLinearVelocity(handle.slot, x, y, z);
+  }
+  getLinearVelocity(handle) {
+    return this.adapter.getLinearVelocity(handle.slot);
+  }
+  setAngularVelocity(handle, x, y, z) {
+    return this.adapter.setAngularVelocity(handle.slot, x, y, z);
+  }
+  applyImpulse(handle, x, y, z) {
+    return this.adapter.applyImpulse(handle.slot, x, y, z);
+  }
+  readRenderSlot(handle, out) {
+    return readStageRenderSlot(this.adapter.render, handle.slot, out);
+  }
+  /** Decode a handle's pose from the previous-step render copy. */
+  readPreviousRenderSlot(handle, out) {
+    return readStageRenderSlot(this.previousRender, handle.slot, out);
+  }
+  readSnapshot(handle, out) {
+    return this.adapter.readSnapshot(handle.slot, out);
+  }
+  // ─── World-level controls / diagnostics ─────────────────────────────
+  setGravity(x, y, z) {
+    this.adapter.setGravity(x, y, z);
+  }
+  /** Physics raycast; the hit's slot is resolved to an entity handle. */
+  castRay(origin, dir, maxDistance, solidOnly = true) {
+    const hit = this.adapter.castRay(origin, dir, maxDistance, solidOnly);
+    if (!hit) return null;
+    return {
+      distance: hit.distance,
+      normal: hit.normal,
+      entity: this.handleForSlot(hit.slot)
+    };
+  }
+  getBodyInfo(handle) {
+    return this.adapter.getBodyInfo(handle.slot);
+  }
+  getDebugRender() {
+    return this.adapter.getDebugRender();
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  /** Destroy the wasm stage. The Simulation must not be used afterwards. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.slotToHandle.clear();
+    this.idToHandle.clear();
+    this.adapter.dispose();
+  }
+};
+async function createSimulation(options = {}) {
+  const adapter = await createWasmStageRuntime(options);
+  return new Simulation(adapter, options);
+}
+
 // src/lib/entities/entity.ts
 var GameEntity = class {
   uuid;
@@ -198,6 +656,7 @@ var GameEntity = class {
   group = null;
   mesh;
   materials;
+  /** Opaque host-owned physics references (never inspected by behaviors). */
   body = null;
   collider = null;
   colliderDesc;
@@ -250,8 +709,18 @@ var GameEntity = class {
     return this.__behaviorRefs;
   }
 };
+var export_t = import_typescript_fsm.t;
 export {
   GameEntity,
+  MockBehaviorRuntime,
+  STAGE_EVENT_STRIDE,
+  STAGE_INPUT_BUTTON_JUMP,
+  STAGE_INPUT_BUTTON_RUN,
+  STAGE_INPUT_STRIDE,
+  STAGE_INVALID_SLOT,
+  STAGE_RENDER_STRIDE,
+  STAGE_SNAPSHOT_STRIDE,
+  Simulation,
   StageBodyKind,
   StageBoundaryDim,
   StageEventType,
@@ -263,10 +732,13 @@ export {
   VEC2_ZERO,
   VEC3_ONE,
   VEC3_ZERO,
+  WasmStageRuntime,
   clearVelocityIntent,
   createPhysicsBodyComponent,
+  createSimulation,
   createTransformComponent,
   createTransformStore,
+  createWasmStageRuntime,
   defineBehavior,
   getPosition,
   getVelocity,
@@ -282,14 +754,15 @@ export {
   moveZ,
   normalizeVec2,
   normalizeVec3,
+  readBehaviorSnapshot,
+  readStageRenderSlot,
   resetVelocity,
   setPosition,
   setPositionX,
   setPositionY,
   setPositionZ,
   setVelocityIntent,
-  t,
-  toRapierVector3,
+  export_t as t,
   toThreeVector2,
   toThreeVector3,
   useBehavior,