@woosh/meep-engine 2.146.0 → 2.147.0

package/src/engine/physics/INTEPOLATION_SYSTEM_PLAN.md

@@ -0,0 +1,287 @@
+# Interpolation system — build plan
+
+Cross-cutting plan for fixed-step → render interpolation. Spans **render**,
+**physics** (a producer), and **network** (a producer + the existing primitives
+this builds on). Referenced from `engine/physics/PLAN.md`.
+
+> Filename note: created as `INTEPOLATION_SYSTEM_PLAN.md` per the request; rename
+> to `INTERPOLATION_SYSTEM_PLAN.md` if the spelling was unintended.
+
+---
+
+## Goal
+
+The simulation advances on a fixed step (`EntityManager.fixedUpdateStepSize`,
+~60 Hz). The renderer runs at a variable, usually higher, display rate on its own
+`requestAnimationFrame` loop. Between two fixed steps the rendered pose is frozen
+at the last step, so motion stutters / temporally aliases — worst at low fixed
+rates or high refresh. This system smooths the discrete per-tick poses across the
+render rate.
+
+## Hard constraints (these shaped every decision)
+
+1. **Write `Transform`, not the renderable.** Scene culling, mesh BVHs, particle
+   systems, trails, and attachment hierarchies are all driven off the ECS
+   `Transform`. Writing an interpolated pose into a three.js object directly
+   would smooth *some* visuals and desync the rest. The interpolated pose must
+   land in `Transform` so the whole engine sees it uniformly. (Bonus: attachment
+   children of an interpolated physics parent then track it **for free**, because
+   the attachment system is push-based on the parent's `Transform.onChanged`.)
+2. **Only interpolate what moved.** Per-frame cost must be O(moving bodies),
+   never O(total). The engine targets massive worlds — tens of thousands of
+   dynamic bodies with only a tiny awake/moving fraction at any moment.
+3. **Don't fight physics.** Physics must never integrate from an interpolated
+   pose. The simulation reads authoritative state; interpolation is a downstream
+   render channel.
+4. **Co-designed with network.** The network package can change (not yet shipped).
+   Interpolation must share machinery with replication, not duplicate it.
+5. **Rewind-safe.** The network can rewind and re-simulate. If a rewind+resim
+   produces the same state, the observer must see the **same** interpolated
+   result — no visual drift from re-running history.
+6. **Agnostic to what it interpolates.** Translation+rotation is one case;
+   network may interpolate other replicated quantities. The mechanism blends
+   *encoded snapshots of any registered component type*.
+
+## Key realization — reuse, don't rebuild
+
+The network package already contains the agnostic interpolation engine. Physics
+becomes a *producer* into it; we do not build a parallel system.
+
+- `network/sim/BinaryInterpolationAdapter.js` —
+  `interpolate(out, source, offA, offB, t)`: type-agnostic blend of two encoded
+  snapshots. Concrete `Transform` / `Vector3` / `Quaternion` adapters exist.
+  **This is constraint 6, already solved.**
+- `network/sim/InterpolationLog.js` — a **tick-indexed ring** (`Map<tick, …>`)
+  of per-component snapshots, recording **only components that changed that tick**
+  (the package's O(mutations)-not-O(entities) bet == constraint 2). Keyed by a
+  plain integer; `interpolate(out, key, type_id, tickA, tickB, t, adapter)`
+  blends two ticks into an out-buffer that is then deserialized into the live
+  component.
+- `network/sim/SimActionExecutor.js` — `before_execute` hook, JSDoc:
+  *"NetworkSession undoes render-time interpolation on remote-owned components"*
+  before reading authoritative state. **The architecture already committed to
+  interpolation writing the live component and the sim restoring authoritative
+  before it reads** (constraints 1 + 3).
+- `network/sim/ActionLog.js` + `network/sim/RewindEngine.js` — rewind restores
+  prior authoritative state; resim replays forward via `onReplay`
+  (constraint 5).
+
+## Locked decisions
+
+1. **Neutral shared primitive.** Lift `InterpolationLog`,
+   `BinaryInterpolationAdapter`, and the blend adapters out of `network/` into a
+   neutral `engine/interpolation/`. Physics and network both produce into it; one
+   render-time pass blends for both. Replication + rewind layer on top **only**
+   for networked entities — single-player physics pays no action-log cost.
+2. **Restore-from-log at step start.** Before each physics tick, reset each moving
+   body's live `Transform` to its latest authoritative tick snapshot (a *quiet*
+   write that bypasses `onChanged`). The solver / narrowphase / broadphase /
+   integrators keep reading & writing `Transform` exactly as today — **no rewiring
+   of the physics hot paths.** The authoritative "cache" is the log's newest tick.
+
+## Glossary (load-bearing terms)
+
+- **Tick** — one fixed simulation step, identified by a monotonic integer *tick
+  number*. The orchestrator's frame number when networked; an internal counter
+  otherwise.
+- **Authoritative pose / endpoint** — the exact pose the simulation produced at
+  the *end* of a tick. The thing physics owns and rewind restores.
+- **Snapshot** — an authoritative pose encoded into the log under
+  `(log key, type_id, tick)` via a serialization adapter.
+- **Log key** — the integer identity under which an entity's snapshots are
+  recorded and looked up in the shared log. `network_id` when the entity is
+  networked (so a server's recording and a client's receipt line up under one
+  identity); a locally-allocated interp id otherwise. Carried on the
+  `Interpolated` component. (See §"Q&A".)
+- **alpha** — `accumulator / fixedUpdateStepSize ∈ [0, 1)`: the fractional
+  progress between the two most-recent *completed* ticks. The blend parameter `t`.
+  We render **between** the last two ticks (one step in the past), so both
+  endpoints always exist — no extrapolation. (See §"Q&A".)
+- **`InterpolationSystem`** — the system that owns the render-time blend pass. It
+  runs in `System.update(dt)` (the variable-rate, rAF-driven cycle), NOT ad-hoc in
+  a `preRender` callback. `update` can fire on ticks where no render happens —
+  harmless (a blend with no following draw is just discarded). If display-exact
+  timing is ever needed, the system can additionally hook `preRender` from its
+  `startup`; `update` is the default.
+- **`Interpolated` component** — opt-in marker physics & render cooperate around.
+  Holds the **log key** (defaults to `-1`; `InterpolationSystem.link` assigns it
+  `entity_id` when still `-1`, so the common case needs no manual setup — the
+  network system can instead set it to the `network_id` directly for replicated
+  entities), the blend type/adapter id, and a `snap` flag. A body without it keeps
+  today's direct-write behavior (this is how physics "sees" who to cooperate
+  with).
+
+## Architecture — one engine, two producers
+
+**Per fixed tick, for bodies carrying `Interpolated`:**
+
+1. **Restore (step start):** reset the live `Transform` to the log's latest
+   authoritative tick — a quiet write (no `onChanged`). This is `before_execute`
+   / "undo render interpolation" applied to physics. Physics then reads truth.
+2. **Step:** physics integrates as today → `Transform` = new authoritative pose.
+3. **Record (step end):** if it actually moved (`|Δ| > ε`), snapshot the pose into
+   the current tick. Sparse by construction → O(moving).
+
+**Per `InterpolationSystem.update(dt)` (render/rAF cadence):** for each
+`Interpolated` entity, pick `(tickA, tickB, t)` and blend → deserialize into the
+live `Transform` (this write *does* fire `onChanged` → culling/particles/trails/
+attachments update). O(moving). `t` source is per-producer: local =
+`EntityManager.getFixedStepAlpha(physicsSystem)`; remote = the network's existing
+render-delay/jitter playout.
+
+```
+simulate()  [fixed-step catch-up loop]      InterpolationSystem.update(dt)  [rAF cadence]
+  for awake+Interpolated:                     for Interpolated e:
+    restore Transform ← log.latest (quiet)      (a,b,t) = window(e)   // t = getFixedStepAlpha(physics)
+  ...physics step → Transform = authoritative   blend(a,b,t) → Transform   (onChanged)
+  for moved+Interpolated:                       → later draw passes read Transform
+    log.record(key, tick, Transform)
+```
+
+## Why each constraint holds
+
+1. **Writes Transform** — blend deserializes into the live component; every
+   Transform-linked system works, hierarchy included.
+2. **Only moving** — produce & blend only for moved bodies; the log is sparse.
+3. **Doesn't fight physics** — restore-at-step-start; physics never sees the
+   interpolated pose. Provable by an interp-on vs interp-off sim-state bit-identity
+   test.
+4. **Co-designed with network** — same log, same adapters, same `before_execute`;
+   physics is a new producer into the existing pipeline.
+5. **Rewind-safe** — the log is tick-keyed; resim re-runs the deterministic sim,
+   which re-records the *same* tick numbers with identical bytes → identical
+   blend output. Requirement: the replay path records snapshots like the live path
+   (it runs the same systems), and the log supports re-recording rewound ticks.
+6. **Agnostic** — `BinaryInterpolationAdapter`; pose is one type; any component
+   with a (serialization adapter + interpolation adapter) pair interpolates the
+   same way.
+
+## Invariants
+
+- **Interpolation never feeds back into the sim.** Guarded by restore-at-step-start
+  and an interp-on/off sim bit-identity test.
+- **The log's latest tick is the single authoritative cache** between steps;
+  `Transform` is a derived render channel for interpolated bodies.
+- **Sparse by motion** — O(moving), never O(N).
+
+## Precision note (massive worlds)
+
+The network *wire* Transform adapter uses Float32 position + smallest-three
+quaternion for bandwidth. That quantizes badly far from the origin. The shared
+**interp log stores full-precision snapshots** (Float64 position + full
+quaternion) for both local and remote (remote is re-serialized at full precision
+on apply); wire compression stays on the wire only.
+
+## Contract change (interpolated bodies only)
+
+For a body carrying `Interpolated`, raw external `Transform` writes are no longer
+authoritative — restore-at-step-start would clobber them. External authoritative
+changes (teleport, kinematic drive) go through a `setPose` / `teleport` API that
+updates the log's latest tick **and** sets `snap` (so the next render does not
+slide across the jump). Bodies *without* `Interpolated` keep today's raw-write
+teleport contract.
+
+## Phases
+
+Each phase: implement → spec → run from `H:/git/moh` → commit. Black-box tests,
+headless where possible (the log, adapters, and physics producer are
+headless-testable; the render hook is thin).
+
+> **Status (Phases 0–2 landed).** Key deltas from the original sketch, decided
+> during build: the fixed-step **tick lives on `EntityManager`**
+> (`fixedStepTick`), not a per-system clock, and `getFixedStepAlpha()` is the one
+> global sim-clock alpha (no system arg). To make the per-step tick exact, the
+> scheduler was changed to a **global lock-step loop** on a single accumulator
+> (commit `0fd41f3`) — all systems' `fixedUpdate` advance together, tick++ per
+> step. The physics producer is **agnostic** (iterates the component's
+> interpolands, uses their adapters) and reads its log via an injected
+> `PhysicsSystem.interpolationLog` (null → skipped). Restore reads `tick-1`,
+> record writes `tick`; lock-step makes both exact with no per-body tick field.
+
+- [x] **Phase 0 — Neutralize the primitive** (`0980e45`). `InterpolationLog` +
+  `BinaryInterpolationAdapter` (+ spec) moved to `engine/interpolation/`; network
+  importers repointed. `EntityManager.getFixedStepAlpha`. (Log key generalization
+  is cosmetic — it was already a plain integer.)
+- [x] **Phase 1 — `Interpolated` + `InterpolationSystem`** (`fc3c3aa`).
+  `Interpoland` descriptor; `Interpolated` carries a **list** of interpolands
+  (one component-per-class → many smoothed quantities); `link` auto-assigns
+  `key = entity` when `-1`; `update` blends each interpoland `(tick-1, tick)` at
+  `getFixedStepAlpha()` into the live component. Full-precision (Float64) pose
+  adapters + `POSE_INTERPOLAND`. Tested: blend / snap / untouched-when-empty /
+  key auto-assign / multi-interpoland.
+- [x] **Phase 2 — Physics as producer** (`a05db76` tick + `dade4d6` producer;
+  scheduler `0fd41f3`). `__interp_restore` (top of `fixedUpdate`, undo render
+  interpolation) + `__interp_record` (after solve/CCD, before sleep test).
+  **Determinism guard passes**: interp ON (live Transform polluted every awake
+  step) vs OFF → bit-identical pose AND velocity every step through fall →
+  contact → settle → sleep.
+  - [x] *`setPose` teleport API* (`691f9a0`). `PhysicsSystem.setPose(rb, pos, rot)`
+    writes the Transform, wakes, and sets `snap`. `snap` semantics finalized:
+    the consumer **leaves the live pose untouched** for that frame (a teleport's
+    new pose isn't in the log yet) and the producer's restore **skips** a snapped
+    body. *Known edge:* clean for the common ~1:1 sim:render rate; when render
+    rate ≫ sim rate a teleport could show a brief flicker (the latest tick isn't
+    retroactively overwritten) — fixable later with an in-place latest-tick
+    overwrite if it ever matters.
+  - [x] *End-to-end wiring verified* (`691f9a0`,
+    `InterpolationSystem.integration.spec`). A real `EntityManager` driving
+    physics + `InterpolationSystem` with `physics.interpolationLog = interp.log`
+    interpolates a body's `Transform` every render frame between fixed steps
+    (control with interp off is frozen between steps). *App wiring* (registering
+    the systems + connecting the log in the actual game world) is still the app
+    layer's job — the recipe is the integration spec.
+- **Phase 3 — Network unification.** *Architecture + coherence landed; live
+  NetworkSession migration is the remaining integration.*
+  - **Finding:** the network package *already* does remote interpolation on the
+    shared primitive — `NetworkSession` owns an `InterpolationLog`, records
+    remote-owned components on `onFrameApplied` (`#on_frame_applied`), undoes
+    render interpolation via `normalize_if_dirty` (the `before_execute` hook),
+    and blends each remote entity through the SAME `log.interpolate → deserialize`
+    path as the local system, on an `AdaptiveRenderDelay`-smoothed playout frame
+    (`#render_interpolated_entities`). So the *primitive* was unified by Phase 0;
+    what was missing was a single *consumer* spanning both timelines.
+  - [x] **Unified consumer.** Component stays pure data: `Interpolated.sourceId`
+    (an int; `INTERPOLATION_SOURCE_LOCAL = 0` default = local fixed-step clock +
+    the system's own log). The timelines' logs + window providers live on the
+    SYSTEM, registered via `InterpolationSystem.registerSource(id, log, sample)`
+    (the network owns its playout window). One `update` blends local and
+    source-driven entities, each source sampled once per frame. *Test:* a local
+    sim-clock entity and a remote playout-source entity both interpolate
+    correctly in one `update` (local + remote coherent in one scene).
+  - [ ] **Live migration (remaining):** point `NetworkSession`'s remote entities
+    at a `NetworkInterpolationSource` (wrapping its playout window + log), mark
+    them with `Interpolated`, and drop `#render_interpolated_entities` so the
+    `InterpolationSystem` is the sole render consumer. Deferred to avoid
+    destabilizing the tested netcode; needs exposing the session's playout window
+    as a side-effect-free `sample()`.
+- **Phase 4 — Rewind/resim correctness.** Interp log supports resim re-recording:
+  on rewind to target, truncate ticks ≥ target; resim re-records forward.
+  *Test:* sim to T, capture interp-log bytes; rewind to T−k, resim to T with
+  identical inputs; assert interp-log bytes over (T−k, T] are bit-identical →
+  observer-identical when nothing changed.
+- **Phase 5 — Camera + edges.** Camera following an interpolated body reads the
+  interpolated source pose. Spawn/despawn & key reuse via generation; verify a
+  visual child of an interpolated physics parent tracks it (hierarchy-for-free);
+  kinematic/parked filtered by the moved-ε test.
+
+## Open items (flagged, not yet decided)
+
+- **Local-vs-remote render timeline.** Local predicted-present vs remote
+  delayed-playout is the classic netcode coherence question. v1 can render both
+  at local-present; refine when the predict/reconcile client lands.
+- **`onChanged` suppression at sim time.** Interpolated bodies could suppress
+  `integrate_position`'s `onChanged` (the render blend will set the final pose).
+  Keep it for now — it keeps culling current between slow render frames.
+
+## Source touchpoints (verify at implementation)
+
+- `engine/physics/integration/integrate_position.js` — writes `Transform` via
+  `.set()` (fires `onChanged`); restore must be a quiet sibling write.
+- `engine/physics/body/BodyStorage.js` — awake set (`awake_at`/`awake_count`) =
+  moving candidates; generation = spawn/despawn/reuse detection.
+- `engine/ecs/EntityManager.js` — `fixedUpdateStepSize`, the per-system
+  accumulator `systemAccumulatedFixedStepTime`, the fixed-step catch-up loop.
+- `engine/graphics/GraphicsEngine.js` — `on.preRender` (the blend hook, fired
+  before the draw passes).
+- `engine/network/sim/{InterpolationLog,BinaryInterpolationAdapter,
+  SimActionExecutor,RewindEngine}.js` — the primitives to neutralize/extend.

package/src/engine/physics/PLAN.md

@@ -777,15 +777,16 @@ scaffolding is in place.
       each body's pose straight into the ECS `Transform` once per fixed step
       (`EntityManager.fixedUpdateStepSize`); with a render rate that doesn't match
       the fixed rate, the rendered motion aliases (stutter / temporal aliasing,
-      worst at low fixed rates). The standard fix is to keep the previous and
-      current fixed-step pose per body and have the renderer lerp position /
-      slerp rotation by the accumulator's fractional remainder
-      (`alpha = leftover / fixedStep`). Open design questions: where the
-      double-buffered "previous pose" lives so it does NOT bloat the simulation
-      hot state or the netcode-replicated component set (a render-side component
-      vs. the physics body), and how teleports / kinematic snaps opt out of
-      interpolation for a frame. Sits at the physics↔render seam, not in the
-      solver.
+      worst at low fixed rates). Designed as a cross-cutting system (render +
+      physics-as-producer + network-as-producer), reusing the network package's
+      agnostic interpolation primitives rather than a physics-local mechanism.
+      Full design + phasing: **see
+      [`INTEPOLATION_SYSTEM_PLAN.md`](./INTEPOLATION_SYSTEM_PLAN.md)**. Locked
+      decisions: a neutral shared interpolation log/adapters (lifted out of
+      `network/`); physics restores authoritative pose from the log at step start
+      (no solver rewiring) and records moved bodies' snapshots at step end;
+      blend → `Transform` at `preRender`; O(moving) not O(N); rewind-safe via the
+      tick-keyed log.
 
 ### API polish
 - [x] **`overlap(shape, position, rotation, output, output_offset,

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -218,6 +218,23 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      * @private
      */
     private __pair_filter_bound;
+    /**
+     * Optional shared interpolation log to produce per-step pose snapshots
+     * into (the {@link InterpolationSystem}'s log). When set — and only then —
+     * each fixedUpdate restores every awake {@link Interpolated} body's live
+     * components from the previous tick (undoing render-time interpolation so
+     * the sim reads authoritative state), then records the post-step state
+     * under the current `entityManager.fixedStepTick`. Null on a headless /
+     * non-rendering world, where the producer work is skipped entirely.
+     * @type {InterpolationLog|null}
+     */
+    interpolationLog: InterpolationLog | null;
+    /**
+     * Reusable decode buffer for restoring interpolated snapshots.
+     * @private
+     * @type {BinaryBuffer}
+     */
+    private __interp_scratch;
     /**
      * Symmetric layer/mask check + optional user callback. Called per
      * candidate pair during broadphase. Returns `true` to accept the pair.
@@ -468,6 +485,32 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
         y: number;
         z: number;
     }): void;
+    /**
+     * Teleport a body to a new pose, bypassing integration: writes the body's
+     * Transform directly and wakes it. For an interpolated body this also flags a
+     * render `snap` on its {@link Interpolated} component, so the producer keeps
+     * this pose (rather than restoring the previous tick over it) and the
+     * renderer shows the new pose without sliding across the jump.
+     *
+     * This is the authoritative way to reposition an interpolated body — a raw
+     * `Transform` write would be undone by the per-step restore. Velocity is left
+     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
+     * stop the body.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} position world position
+     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation world unit-quaternion rotation
+     */
+    setPose(rigidBody: RigidBody, position: Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }, rotation: Quaternion | {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }): void;
     /**
      * Force the body awake. Static bodies are ignored.
      * @param {RigidBody} rigidBody
@@ -674,6 +717,27 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      * @private
      */
     private __dispatch_contact_events;
+    /**
+     * Producer — restore pass. At the top of a fixed step, reset every awake
+     * {@link Interpolated} body's live components to their authoritative state
+     * from the previous tick's snapshot, undoing any render-time interpolation
+     * the {@link InterpolationSystem} wrote between frames so the sim integrates
+     * from truth, not an interpolated pose. A body with no previous snapshot
+     * (first step ever, or just woken) is left as-is — its live state is already
+     * authoritative. No-op unless {@link interpolationLog} is wired.
+     * @private
+     */
+    private __interp_restore;
+    /**
+     * Producer — record pass. At the end of a fixed step, snapshot every awake
+     * {@link Interpolated} body's live components into the shared log under the
+     * current `entityManager.fixedStepTick`. The render-time
+     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
+     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
+     * unless {@link interpolationLog} is wired.
+     * @private
+     */
+    private __interp_record;
     fixedUpdate(dt: any): void;
     /**
      * @readonly

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import Vector3 from "../../../core/geom/Vector3.js";
@@ -47,6 +48,7 @@ import { Collider, COLLIDER_UNBOUND } from "./Collider.js";
 import { RIGID_BODY_UNALLOCATED, RigidBody } from "./RigidBody.js";
 import { RigidBodyFlags } from "./RigidBodyFlags.js";
 import { SleepState } from "./SleepState.js";
+import { Interpolated } from "../../interpolation/Interpolated.js";
 
 /**
  * Reusable scratch buffer for world-AABB construction so the link path is
@@ -319,6 +321,26 @@ export class PhysicsSystem extends System {
          * @private
          */
         this.__pair_filter_bound = (idA, idB) => this.__pair_filter(idA, idB);
+
+        /**
+         * Optional shared interpolation log to produce per-step pose snapshots
+         * into (the {@link InterpolationSystem}'s log). When set — and only then —
+         * each fixedUpdate restores every awake {@link Interpolated} body's live
+         * components from the previous tick (undoing render-time interpolation so
+         * the sim reads authoritative state), then records the post-step state
+         * under the current `entityManager.fixedStepTick`. Null on a headless /
+         * non-rendering world, where the producer work is skipped entirely.
+         * @type {InterpolationLog|null}
+         */
+        this.interpolationLog = null;
+
+        /**
+         * Reusable decode buffer for restoring interpolated snapshots.
+         * @private
+         * @type {BinaryBuffer}
+         */
+        this.__interp_scratch = new BinaryBuffer();
+        this.__interp_scratch.fromArrayBuffer(new ArrayBuffer(256));
     }
 
     /**
@@ -829,6 +851,50 @@ export class PhysicsSystem extends System {
         }
     }
 
+    /**
+     * Teleport a body to a new pose, bypassing integration: writes the body's
+     * Transform directly and wakes it. For an interpolated body this also flags a
+     * render `snap` on its {@link Interpolated} component, so the producer keeps
+     * this pose (rather than restoring the previous tick over it) and the
+     * renderer shows the new pose without sliding across the jump.
+     *
+     * This is the authoritative way to reposition an interpolated body — a raw
+     * `Transform` write would be undone by the per-step restore. Velocity is left
+     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
+     * stop the body.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} position world position
+     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation world unit-quaternion rotation
+     */
+    setPose(rigidBody, position, rotation) {
+        const idx = body_id_index(rigidBody._bodyId);
+        const transform = this.__transforms[idx];
+        if (transform === undefined) {
+            return;
+        }
+
+        transform.position.set(position.x, position.y, position.z);
+        transform.rotation.set(rotation.x, rotation.y, rotation.z, rotation.w);
+
+        this.__wake_body(rigidBody);
+
+        // Flag a snap on the body's Interpolated component, if any, so the
+        // interpolation producer (restore) and consumer (blend) treat this pose
+        // as authoritative this frame instead of interpolating across the jump.
+        const em = this.entityManager;
+        if (em !== null && em !== undefined) {
+            const dataset = em.dataset;
+            if (dataset !== null && dataset !== undefined) {
+                const entity = this.storage.entity_at(idx);
+                const interpolated = dataset.getComponent(entity, Interpolated);
+                if (interpolated !== undefined && interpolated !== null) {
+                    interpolated.snap = true;
+                }
+            }
+        }
+    }
+
     /**
      * Force the body awake. Static bodies are ignored.
      * @param {RigidBody} rigidBody
@@ -1273,7 +1339,103 @@ export class PhysicsSystem extends System {
         }
     }
 
+    /**
+     * Producer — restore pass. At the top of a fixed step, reset every awake
+     * {@link Interpolated} body's live components to their authoritative state
+     * from the previous tick's snapshot, undoing any render-time interpolation
+     * the {@link InterpolationSystem} wrote between frames so the sim integrates
+     * from truth, not an interpolated pose. A body with no previous snapshot
+     * (first step ever, or just woken) is left as-is — its live state is already
+     * authoritative. No-op unless {@link interpolationLog} is wired.
+     * @private
+     */
+    __interp_restore() {
+        const log = this.interpolationLog;
+        const em = this.entityManager;
+        if (log === null || em === null || em === undefined) return;
+        const dataset = em.dataset;
+        if (dataset === null || dataset === undefined) return;
+
+        const prev_tick = em.fixedStepTick - 1;
+        if (prev_tick < 0) return;
+
+        const storage = this.storage;
+        const count = storage.awake_count;
+        const scratch = this.__interp_scratch;
+
+        for (let i = 0; i < count; i++) {
+            const idx = storage.awake_at(i);
+            const entity = storage.entity_at(idx);
+            const interpolated = dataset.getComponent(entity, Interpolated);
+            if (interpolated === undefined || interpolated === null) continue;
+            // A teleported body (snap set, e.g. via setPose) keeps its live pose
+            // this step — restoring the previous tick would undo the teleport.
+            if (interpolated.snap) continue;
+            const key = interpolated.key;
+            if (key < 0) continue;
+
+            const interpolands = interpolated.interpolands;
+            for (let k = 0; k < interpolands.length; k++) {
+                const ip = interpolands[k];
+                scratch.position = 0;
+                // Snap to the previous tick's snapshot (both offsets equal → t irrelevant).
+                const ok = log.interpolate(scratch, key, ip.type_id, prev_tick, prev_tick, 0, ip.interpolation_adapter);
+                if (!ok) continue;
+                const target = dataset.getComponent(entity, ip.component_class);
+                if (target === undefined || target === null) continue;
+                scratch.position = 0;
+                ip.serialization_adapter.deserialize(scratch, target);
+            }
+        }
+    }
+
+    /**
+     * Producer — record pass. At the end of a fixed step, snapshot every awake
+     * {@link Interpolated} body's live components into the shared log under the
+     * current `entityManager.fixedStepTick`. The render-time
+     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
+     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
+     * unless {@link interpolationLog} is wired.
+     * @private
+     */
+    __interp_record() {
+        const log = this.interpolationLog;
+        const em = this.entityManager;
+        if (log === null || em === null || em === undefined) return;
+        const dataset = em.dataset;
+        if (dataset === null || dataset === undefined) return;
+
+        const tick = em.fixedStepTick;
+        const storage = this.storage;
+        const count = storage.awake_count;
+
+        log.begin_tick(tick);
+        for (let i = 0; i < count; i++) {
+            const idx = storage.awake_at(i);
+            const entity = storage.entity_at(idx);
+            const interpolated = dataset.getComponent(entity, Interpolated);
+            if (interpolated === undefined || interpolated === null) continue;
+            const key = interpolated.key;
+            if (key < 0) continue;
+
+            const interpolands = interpolated.interpolands;
+            for (let k = 0; k < interpolands.length; k++) {
+                const ip = interpolands[k];
+                const target = dataset.getComponent(entity, ip.component_class);
+                if (target === undefined || target === null) continue;
+                const buf = log.begin_record(key, ip.type_id);
+                ip.serialization_adapter.serialize(buf, target);
+                log.end_record();
+            }
+        }
+        log.end_tick();
+    }
+
     fixedUpdate(dt) {
+        // Producer: restore authoritative pose (undo render interpolation)
+        // before the sim reads any Transform this step.
+        this.__interp_restore();
+
         const gx = this.gravity.x;
         const gy = this.gravity.y;
         const gz = this.gravity.z;
@@ -1454,6 +1616,12 @@ export class PhysicsSystem extends System {
             ccd_resolve(this);
         }
 
+        // Producer: record the post-step authoritative pose of every awake
+        // interpolated body under this step's tick. Before the sleep test, so a
+        // body that settles this step still records its final pose for the last
+        // interpolation interval.
+        this.__interp_record();
+
         // Stage 9: sleep test.
         this.__sleep_test(dt);