@woosh/meep-engine 2.145.0 → 2.147.0

package/src/engine/ecs/EntityManager.d.ts

@@ -75,14 +75,6 @@ export class EntityManager {
      * @type {EntityManagerState}
      */
     state: EntityManagerState;
-    /**
-     * Track remainders of simulation time for fixed step
-     * Needed for accurate time keeping
-     * @private
-     * @readonly
-     * @type {Map<System, number>}
-     */
-    private readonly systemAccumulatedFixedStepTime;
     /**
      * Value used to execute {@link System.fixedUpdate}
      * In seconds.
@@ -95,12 +87,32 @@ export class EntityManager {
      */
     fixedUpdateStepSize: number;
     /**
-     * How long can any given system run it's {@link System.fixedUpdate}, per simulation update
-     * This is value allows us to avoid cases where {@link System.fixedUpdate} takes longer that its time step and causes a runaway freeze
-     * In milliseconds.
+     * Wall-clock budget, in milliseconds, for the whole fixed-step catch-up loop
+     * within a single {@link simulate} call. Once a cycle's accumulated
+     * fixedUpdate work exceeds this, the loop stops early and the unconsumed time
+     * stays in the accumulator to be caught up later — this avoids a runaway
+     * freeze when {@link System.fixedUpdate} work outpaces its time step. (Now a
+     * per-cycle budget across all systems' lock-step steps; previously per-system.)
      * @type {number}
      */
     fixedUpdatePerSystemExecutionTimeLimit: number;
+    /**
+     * Monotonic **simulation tick id** — the count of fixed steps the simulation
+     * has executed. Advances once per {@link fixedUpdateStepSize} step inside
+     * {@link simulate}. This is the hub-owned identity that producers (physics,
+     * network) stamp per-tick state with, and that render-rate consumers
+     * (interpolation) read as "the latest completed step". Pairs with
+     * {@link getFixedStepAlpha}.
+     * @type {number}
+     */
+    fixedStepTick: number;
+    /**
+     * Canonical fixed-step time accumulator backing {@link fixedStepTick} and
+     * {@link getFixedStepAlpha}. Holds the sub-step remainder in `[0, step)`.
+     * @private
+     * @type {number}
+     */
+    private __fixedStepAccumulator;
     /**
      * Currently attached dataset.
      * Do not modify directly, instead use {@link attachDataset} and {@link detachDataset} respectively.
@@ -160,6 +172,17 @@ export class EntityManager {
      * @param {number} time_delta_seconds in seconds
      */
     simulate(time_delta_seconds: number): void;
+    /**
+     * Fractional progress through the current fixed step, in `[0, 1)` — the
+     * leftover sim time that hasn't yet formed a whole {@link fixedUpdateStepSize}
+     * step, normalized by the step size. This is the blend parameter the
+     * render-time interpolation system pairs with {@link fixedStepTick} to
+     * interpolate between the last two completed steps: `alpha = 0` sits on the
+     * previous tick, `alpha → 1` approaches the latest.
+     *
+     * @returns {number} alpha in `[0, 1)`
+     */
+    getFixedStepAlpha(): number;
     /**
      * If the {@link EntityManager} is already started, the system will be started automatically before being added
      * @param {System} system

package/src/engine/ecs/EntityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,6BAFW,MAAM,QAyEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBAjsBe,sBAAsB,UAisBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBA/7BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;;;;OAQG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,+BAA2B;IAE3B;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,6BAFW,MAAM,QA8EhB;IAED;;;;;;;;;OASG;IACH,qBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,iEA2DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CAyC5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBAjtBe,sBAAsB,UAitBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBA59BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}

package/src/engine/ecs/EntityManager.js

@@ -105,15 +105,6 @@ export class EntityManager {
      */
     state = EntityManagerState.Initial;
 
-    /**
-     * Track remainders of simulation time for fixed step
-     * Needed for accurate time keeping
-     * @private
-     * @readonly
-     * @type {Map<System, number>}
-     */
-    systemAccumulatedFixedStepTime = new Map();
-
     /**
      * Value used to execute {@link System.fixedUpdate}
      * In seconds.
@@ -127,13 +118,35 @@ export class EntityManager {
     fixedUpdateStepSize = 0.016666666666;
 
     /**
-     * How long can any given system run it's {@link System.fixedUpdate}, per simulation update
-     * This is value allows us to avoid cases where {@link System.fixedUpdate} takes longer that its time step and causes a runaway freeze
-     * In milliseconds.
+     * Wall-clock budget, in milliseconds, for the whole fixed-step catch-up loop
+     * within a single {@link simulate} call. Once a cycle's accumulated
+     * fixedUpdate work exceeds this, the loop stops early and the unconsumed time
+     * stays in the accumulator to be caught up later — this avoids a runaway
+     * freeze when {@link System.fixedUpdate} work outpaces its time step. (Now a
+     * per-cycle budget across all systems' lock-step steps; previously per-system.)
      * @type {number}
      */
     fixedUpdatePerSystemExecutionTimeLimit = 15;
 
+    /**
+     * Monotonic **simulation tick id** — the count of fixed steps the simulation
+     * has executed. Advances once per {@link fixedUpdateStepSize} step inside
+     * {@link simulate}. This is the hub-owned identity that producers (physics,
+     * network) stamp per-tick state with, and that render-rate consumers
+     * (interpolation) read as "the latest completed step". Pairs with
+     * {@link getFixedStepAlpha}.
+     * @type {number}
+     */
+    fixedStepTick = 0;
+
+    /**
+     * Canonical fixed-step time accumulator backing {@link fixedStepTick} and
+     * {@link getFixedStepAlpha}. Holds the sub-step remainder in `[0, step)`.
+     * @private
+     * @type {number}
+     */
+    __fixedStepAccumulator = 0;
+
     /**
      * Currently attached dataset.
      * Do not modify directly, instead use {@link attachDataset} and {@link detachDataset} respectively.
@@ -431,55 +444,75 @@ export class EntityManager {
         const system_count = systems.length;
 
         const fixed_step = this.fixedUpdateStepSize;
-        const accumulatedTime = this.systemAccumulatedFixedStepTime;
 
         assert.notNaN(fixed_step, 'fixed_step');
         assert.greaterThan(fixed_step, 0, 'fixed_step must be greater than 0');
 
-        for (let i = 0; i < system_count; i++) {
-
-            const system = systems[i];
-
-            // Perform fixed-step update
-            if (system.fixedUpdate !== noop) {
-                let accumulated_time = accumulatedTime.get(system) + time_delta_seconds;
-
-                const t0 = performance.now();
-
-                while (accumulated_time >= fixed_step) {
-
+        // Global fixed-step loop. Every system advances its fixedUpdate in
+        // LOCK-STEP on a single shared accumulator, and the simulation tick id is
+        // incremented once per step inside the loop — so all systems run the same
+        // step under the same `fixedStepTick`, and a producer can read
+        // `fixedStepTick` during its own fixedUpdate as the true current step.
+        // (All fixedUpdates for a step run before any update() — a clean
+        // sim-then-render phase split that also keeps every system on the same
+        // tick boundary for deterministic rewind/resim.)
+        this.__fixedStepAccumulator += time_delta_seconds;
+
+        const t0 = performance.now();
+        while (this.__fixedStepAccumulator >= fixed_step) {
+            this.fixedStepTick++;
+
+            for (let i = 0; i < system_count; i++) {
+                const system = systems[i];
+                if (system.fixedUpdate !== noop) {
                     try {
-                        system.fixedUpdate(fixed_step)
+                        system.fixedUpdate(fixed_step);
                     } catch (e) {
                         console.error(`Failed during fixedUpdate of system '${computeSystemName(system)}': `, e);
                     }
-
-                    accumulated_time -= fixed_step;
-
-                    if (performance.now() - t0 > this.fixedUpdatePerSystemExecutionTimeLimit) {
-                        console.warn(`.fixedUpdate of system '${computeSystemName(system)}' is falling behind current clock due to slow execution. Retardation is done to avoid severe performance impact.`);
-                        break;
-                    }
                 }
+            }
 
-                // record whatever remains
-                accumulatedTime.set(system, accumulated_time);
+            this.__fixedStepAccumulator -= fixed_step;
 
+            // Runaway guard: cap total fixed-step catch-up per simulate so a long
+            // stall (e.g. a backgrounded tab resuming) doesn't freeze the frame.
+            // The unconsumed remainder stays in the accumulator and is caught up
+            // over subsequent calls.
+            if (performance.now() - t0 > this.fixedUpdatePerSystemExecutionTimeLimit) {
+                console.warn('EntityManager.simulate: fixedUpdate is falling behind the clock; capping catch-up this cycle to avoid a freeze.');
+                break;
             }
+        }
 
+        // Variable-rate update pass — after all fixed steps for this cycle.
+        for (let i = 0; i < system_count; i++) {
+            const system = systems[i];
             if (system.update !== noop) {
-
                 try {
                     system.update(time_delta_seconds);
                 } catch (e) {
                     console.error(`Failed during update of system '${computeSystemName(system)}': `, e);
                 }
-
             }
-
         }
     }
 
+    /**
+     * Fractional progress through the current fixed step, in `[0, 1)` — the
+     * leftover sim time that hasn't yet formed a whole {@link fixedUpdateStepSize}
+     * step, normalized by the step size. This is the blend parameter the
+     * render-time interpolation system pairs with {@link fixedStepTick} to
+     * interpolate between the last two completed steps: `alpha = 0` sits on the
+     * previous tick, `alpha → 1` approaches the latest.
+     *
+     * @returns {number} alpha in `[0, 1)`
+     */
+    getFixedStepAlpha() {
+        const alpha = this.__fixedStepAccumulator / this.fixedUpdateStepSize;
+        return alpha < 1 ? alpha : 1;
+    }
+
     /**
      * If the {@link EntityManager} is already started, the system will be started automatically before being added
      * @param {System} system
@@ -542,8 +575,6 @@ export class EntityManager {
         // link dependency components
         this.dataset?.registerManyComponentTypes(system.referenced_components);
 
-        this.systemAccumulatedFixedStepTime.set(system, 0);
-
         this.on.systemAdded.send1(system);
 
         return result_promise;
@@ -590,8 +621,6 @@ export class EntityManager {
             });
         });
 
-        this.systemAccumulatedFixedStepTime.delete(system);
-
         this.on.systemRemoved.send1(system);
 
         return true;

package/src/engine/interpolation/BinaryInterpolationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BinaryInterpolationAdapter.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/BinaryInterpolationAdapter.js"],"names":[],"mappings":";;;;;gCAMU,MAAM;AANhB;;;;;;;GAOG;AACH;IACI,gEAAgE;;IAEhE,qEAAqE;;IAErE,+DAA+D;;GAEhE;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAEI,sDAAsD;IACtD,MADW,MAAM,CACe;IAEhC;;;;;;;;;;;;;OAaG;IACH,0EAJW,MAAM,iBACN,MAAM,KACN,MAAM,QAIhB;CACJ"}

package/src/engine/interpolation/Interpoland.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Descriptor for ONE thing the interpolation system blends for an entity.
+ *
+ * An entity carries an {@link Interpolated} component holding a LIST of these.
+ * Pure ECS allows at most one component instance of a given class per entity, so
+ * "interpolate the pose AND something else on the same entity" is expressed as a
+ * list of interpolands, not several `Interpolated` components.
+ *
+ * Each interpoland binds, for one interpolated quantity:
+ *  - a stable `type_id` distinguishing it in the interpolation log under the
+ *    entity's key (the log is indexed by `(key, type_id, tick)`);
+ *  - the live ECS `component_class` the blended result is written into;
+ *  - a `serialization_adapter` that encodes the live component into a snapshot
+ *    and decodes a blended snapshot back into it; and
+ *  - an `interpolation_adapter` that blends two snapshots at `t`.
+ *
+ * Interpolands are stateless and shareable — one instance per kind can be reused
+ * across every entity that interpolates that kind (e.g. a single shared pose
+ * interpoland for every physics body).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Interpoland {
+    /**
+     * @param {number} type_id stable id distinguishing this kind in the log
+     * @param {Function} component_class live component class written into
+     * @param {BinaryClassSerializationAdapter} serialization_adapter encodes /
+     *   decodes the live component to / from a snapshot
+     * @param {BinaryInterpolationAdapter} interpolation_adapter blends two
+     *   snapshots
+     */
+    constructor(type_id: number, component_class: Function, serialization_adapter: BinaryClassSerializationAdapter, interpolation_adapter: BinaryInterpolationAdapter);
+    /** @type {number} */
+    type_id: number;
+    /** @type {Function} */
+    component_class: Function;
+    /** @type {BinaryClassSerializationAdapter} */
+    serialization_adapter: BinaryClassSerializationAdapter;
+    /** @type {BinaryInterpolationAdapter} */
+    interpolation_adapter: BinaryInterpolationAdapter;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isInterpoland: boolean;
+}
+//# sourceMappingURL=Interpoland.d.ts.map

package/src/engine/interpolation/Interpoland.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Interpoland.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/Interpoland.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IACI;;;;;;;OAOG;IACH,qBAPW,MAAM,wIAgBhB;IARG,qBAAqB;IACrB,SADW,MAAM,CACK;IACtB,uBAAuB;IACvB,0BAAsC;IACtC,8CAA8C;IAC9C,uDAAkD;IAClD,yCAAyC;IACzC,kDAAkD;IAI1D;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC"}

package/src/engine/interpolation/Interpoland.js

@@ -0,0 +1,49 @@
+/**
+ * Descriptor for ONE thing the interpolation system blends for an entity.
+ *
+ * An entity carries an {@link Interpolated} component holding a LIST of these.
+ * Pure ECS allows at most one component instance of a given class per entity, so
+ * "interpolate the pose AND something else on the same entity" is expressed as a
+ * list of interpolands, not several `Interpolated` components.
+ *
+ * Each interpoland binds, for one interpolated quantity:
+ *  - a stable `type_id` distinguishing it in the interpolation log under the
+ *    entity's key (the log is indexed by `(key, type_id, tick)`);
+ *  - the live ECS `component_class` the blended result is written into;
+ *  - a `serialization_adapter` that encodes the live component into a snapshot
+ *    and decodes a blended snapshot back into it; and
+ *  - an `interpolation_adapter` that blends two snapshots at `t`.
+ *
+ * Interpolands are stateless and shareable — one instance per kind can be reused
+ * across every entity that interpolates that kind (e.g. a single shared pose
+ * interpoland for every physics body).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Interpoland {
+    /**
+     * @param {number} type_id stable id distinguishing this kind in the log
+     * @param {Function} component_class live component class written into
+     * @param {BinaryClassSerializationAdapter} serialization_adapter encodes /
+     *   decodes the live component to / from a snapshot
+     * @param {BinaryInterpolationAdapter} interpolation_adapter blends two
+     *   snapshots
+     */
+    constructor(type_id, component_class, serialization_adapter, interpolation_adapter) {
+        /** @type {number} */
+        this.type_id = type_id;
+        /** @type {Function} */
+        this.component_class = component_class;
+        /** @type {BinaryClassSerializationAdapter} */
+        this.serialization_adapter = serialization_adapter;
+        /** @type {BinaryInterpolationAdapter} */
+        this.interpolation_adapter = interpolation_adapter;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Interpoland.prototype.isInterpoland = true;

package/src/engine/interpolation/Interpolated.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Sentinel for {@link Interpolated#key} before assignment. The
+ * {@link InterpolationSystem} replaces it with the entity id at link time.
+ * @type {number}
+ */
+export const INTERPOLATION_KEY_UNSET: number;
+/**
+ * Default {@link Interpolated#sourceId}: the local fixed-step timeline (the
+ * {@link InterpolationSystem}'s own log, blended on `fixedStepTick`). Every
+ * physics-driven body uses this. Other source ids are registered with the
+ * system (e.g. a network playout) and assigned to remote entities.
+ * @type {number}
+ */
+export const INTERPOLATION_SOURCE_LOCAL: number;
+/**
+ * Marker component opting an entity into render-time interpolation, and the
+ * cooperation point producers (physics, network) and the consumer
+ * ({@link InterpolationSystem}) share.
+ *
+ * Carries:
+ *  - `key`: the integer identity this entity's snapshots are filed under in the
+ *    interpolation log. Defaults to {@link INTERPOLATION_KEY_UNSET}; the
+ *    {@link InterpolationSystem} assigns it the entity id at link time when
+ *    unset — the common case needs no manual setup. The network layer can set it
+ *    to the `network_id` instead, so a replicated entity keeps one identity
+ *    across peers.
+ *  - `interpolands`: the {@link Interpoland} kinds to blend for this entity (one
+ *    pose interpoland in the common case; more for entities that smooth several
+ *    quantities).
+ *  - `snap`: when true, the next consume shows the latest snapshot exactly (no
+ *    blend) and the flag clears — used to avoid sliding across a teleport.
+ *
+ * Transient render configuration: NOT serialized or replicated.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Interpolated {
+    /**
+     * Log key. {@link INTERPOLATION_KEY_UNSET} until the system assigns the
+     * entity id (or a producer assigns a network_id).
+     * @type {number}
+     */
+    key: number;
+    /**
+     * When true, the next consume snaps to the latest snapshot (no blend) and
+     * the flag clears. Set on teleport so the render doesn't slide across the jump.
+     * @type {boolean}
+     */
+    snap: boolean;
+    /**
+     * The interpoland kinds to blend for this entity.
+     * @type {Interpoland[]}
+     */
+    interpolands: Interpoland[];
+    /**
+     * Which interpolation timeline this entity is blended on — a plain id, NOT a
+     * resource or behavior (those live on the {@link InterpolationSystem}, keyed
+     * by this id). {@link INTERPOLATION_SOURCE_LOCAL} (the default) is the local
+     * fixed-step clock + the system's own log; a remote/networked entity carries
+     * the id of a source the network registered with the system (its
+     * render-delayed playout + log), so one render pass blends local and remote
+     * entities coherently.
+     * @type {number}
+     */
+    sourceId: number;
+    /**
+     * Value equality over the configurable state: the timeline ({@link sourceId})
+     * and the interpoland kinds (compared by their stable `type_id`). The
+     * system-assigned log {@link key} and the transient {@link snap} flag are
+     * excluded.
+     *
+     * @param {Interpolated} other
+     * @returns {boolean}
+     */
+    equals(other: Interpolated): boolean;
+    /**
+     * Hash over the same configurable state as {@link equals}. Equal components
+     * hash equal.
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * Copy `other`'s state into this component. The interpoland list is
+     * duplicated as a new array sharing the (stateless, shared) interpoland
+     * descriptors; `key`, `snap`, and `sourceId` are copied verbatim.
+     *
+     * @param {Interpolated} other
+     * @returns {Interpolated} this
+     */
+    copy(other: Interpolated): Interpolated;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isInterpolated: boolean;
+}
+export namespace Interpolated {
+    let typeName: string;
+}
+//# sourceMappingURL=Interpolated.d.ts.map

package/src/engine/interpolation/Interpolated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Interpolated.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/Interpolated.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;;GAMG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAEI;;;;OAIG;IACH,KAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,cAFU,aAAa,CAEL;IAElB;;;;;;;;;OASG;IACH,UAFU,MAAM,CAEsB;IAEtC;;;;;;;;OAQG;IACH,cAHW,YAAY,GACV,OAAO,CAuBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CASlB;IAED;;;;;;;OAOG;IACH,YAHW,YAAY,GACV,YAAY,CAQxB;IASL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;CAZpC;;kBAIS,MAAM"}

package/src/engine/interpolation/Interpolated.js

@@ -0,0 +1,149 @@
+import { combine_hash } from "../../core/collection/array/combine_hash.js";
+
+/**
+ * Sentinel for {@link Interpolated#key} before assignment. The
+ * {@link InterpolationSystem} replaces it with the entity id at link time.
+ * @type {number}
+ */
+export const INTERPOLATION_KEY_UNSET = -1;
+
+/**
+ * Default {@link Interpolated#sourceId}: the local fixed-step timeline (the
+ * {@link InterpolationSystem}'s own log, blended on `fixedStepTick`). Every
+ * physics-driven body uses this. Other source ids are registered with the
+ * system (e.g. a network playout) and assigned to remote entities.
+ * @type {number}
+ */
+export const INTERPOLATION_SOURCE_LOCAL = 0;
+
+/**
+ * Marker component opting an entity into render-time interpolation, and the
+ * cooperation point producers (physics, network) and the consumer
+ * ({@link InterpolationSystem}) share.
+ *
+ * Carries:
+ *  - `key`: the integer identity this entity's snapshots are filed under in the
+ *    interpolation log. Defaults to {@link INTERPOLATION_KEY_UNSET}; the
+ *    {@link InterpolationSystem} assigns it the entity id at link time when
+ *    unset — the common case needs no manual setup. The network layer can set it
+ *    to the `network_id` instead, so a replicated entity keeps one identity
+ *    across peers.
+ *  - `interpolands`: the {@link Interpoland} kinds to blend for this entity (one
+ *    pose interpoland in the common case; more for entities that smooth several
+ *    quantities).
+ *  - `snap`: when true, the next consume shows the latest snapshot exactly (no
+ *    blend) and the flag clears — used to avoid sliding across a teleport.
+ *
+ * Transient render configuration: NOT serialized or replicated.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Interpolated {
+
+    /**
+     * Log key. {@link INTERPOLATION_KEY_UNSET} until the system assigns the
+     * entity id (or a producer assigns a network_id).
+     * @type {number}
+     */
+    key = INTERPOLATION_KEY_UNSET;
+
+    /**
+     * When true, the next consume snaps to the latest snapshot (no blend) and
+     * the flag clears. Set on teleport so the render doesn't slide across the jump.
+     * @type {boolean}
+     */
+    snap = false;
+
+    /**
+     * The interpoland kinds to blend for this entity.
+     * @type {Interpoland[]}
+     */
+    interpolands = [];
+
+    /**
+     * Which interpolation timeline this entity is blended on — a plain id, NOT a
+     * resource or behavior (those live on the {@link InterpolationSystem}, keyed
+     * by this id). {@link INTERPOLATION_SOURCE_LOCAL} (the default) is the local
+     * fixed-step clock + the system's own log; a remote/networked entity carries
+     * the id of a source the network registered with the system (its
+     * render-delayed playout + log), so one render pass blends local and remote
+     * entities coherently.
+     * @type {number}
+     */
+    sourceId = INTERPOLATION_SOURCE_LOCAL;
+
+    /**
+     * Value equality over the configurable state: the timeline ({@link sourceId})
+     * and the interpoland kinds (compared by their stable `type_id`). The
+     * system-assigned log {@link key} and the transient {@link snap} flag are
+     * excluded.
+     *
+     * @param {Interpolated} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (other === null || other === undefined || other.isInterpolated !== true) {
+            return false;
+        }
+        if (this.sourceId !== other.sourceId) {
+            return false;
+        }
+        const a = this.interpolands;
+        const b = other.interpolands;
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (a[i].type_id !== b[i].type_id) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Hash over the same configurable state as {@link equals}. Equal components
+     * hash equal.
+     * @returns {number}
+     */
+    hash() {
+        let h = this.sourceId | 0;
+        const ips = this.interpolands;
+        for (let i = 0; i < ips.length; i++) {
+            h = combine_hash(h, ips[i].type_id | 0);
+        }
+        return h;
+    }
+
+    /**
+     * Copy `other`'s state into this component. The interpoland list is
+     * duplicated as a new array sharing the (stateless, shared) interpoland
+     * descriptors; `key`, `snap`, and `sourceId` are copied verbatim.
+     *
+     * @param {Interpolated} other
+     * @returns {Interpolated} this
+     */
+    copy(other) {
+        this.key = other.key;
+        this.snap = other.snap;
+        this.sourceId = other.sourceId;
+        this.interpolands = other.interpolands.slice();
+        return this;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Interpolated.typeName = "Interpolated";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Interpolated.prototype.isInterpolated = true;

package/src/engine/{network/sim → interpolation}/InterpolationLog.d.ts

@@ -161,5 +161,5 @@ export class InterpolationLog {
     clear(): void;
     #private;
 }
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=InterpolationLog.d.ts.map

package/src/engine/interpolation/InterpolationLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InterpolationLog.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/InterpolationLog.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAkBI;;;;;OAKG;IACH,0DALW;QAAE,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,EAkGvE;IA9EG,+BAA+B;IAC/B,0BADqB,MAAM,CACiB;IAe5C,+BAA+B;IAC/B,2BADqB,MAAM,CACa;IA+D5C;;;;;;;;OAQG;IACH,iBAFW,MAAM,QAkEhB;IAED;;;;;;;;;;;;;OAaG;IACH,yBAJW,MAAM,WACN,MAAM,GACJ,YAAY,CAmCxB;IAED;;;;;OAKG;IACH,mBAsDC;IAED;;;;;;;OAOG;IACH,iBAeC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,YAPW,MAAM,EAAE,GAAC,WAAW,cACpB,MAAM,QACN,MAAM,cACN,MAAM,WACN,MAAM,GACJ,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBATW,YAAY,cACZ,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,KACN,MAAM,wCAEJ,OAAO,CAuBnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,eAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,cASC;;CACJ;6BArkB4B,mCAAmC"}

package/src/engine/{network/sim → interpolation}/InterpolationLog.js

@@ -1,5 +1,5 @@
-import { assert } from "../../../core/assert.js";
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { assert } from "../../core/assert.js";
+import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
 
 /** Words per record: [network_id, type_id, byte_offset, byte_length]. 4 × u32 = 16 B. */
 const RECORD_WORDS = 4;