@pylonsync/realtime 0.22.26 → 0.22.27

package/dist/interpolation.d.ts

@@ -76,6 +76,7 @@ export declare class EntityInterpolator {
     /** Lives that ended, oldest first, so `record` can drop them when
      *  `update` does not run (a hidden tab keeps receiving frames). */
     private ended;
+    private endedStart;
     constructor(options?: InterpolationOptions);
     /** The newest tick recorded, or -1. */
     get latestTick(): number;

package/dist/wire.d.ts

@@ -160,5 +160,5 @@ export declare class StreamFrames {
     /** Add a chunk and return the frames it completed. */
     push(chunk: Uint8Array): ArrayBuffer[];
     private peek;
-    private take;
+    private consume;
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.26",
+  "version": "0.22.27",
   "description": "Pylon realtime shard client pieces with no framework: the wire protocol, codecs, and the entity replication decoder and table.",
   "type": "module",
   "main": "./src/index.ts",

package/src/interpolation.test.ts

@@ -178,4 +178,26 @@ describe("EntityInterpolator", () => {
     // A render tick past them all draws nothing.
     expect(h.at(tick).size).toBe(0);
   });
+
+  test("cleanup preserves reused ids through compaction and a tick reset", () => {
+    const h = harness();
+    for (let tick = 1; tick <= 3000; tick++) {
+      h.frame(tick, {
+        despawn: tick > 1 ? [1, 2] : [],
+        spawn: [{ id: 1, pos: [tick, 0, 0] }, { id: 2, pos: [-tick, 0, 0] }],
+      });
+    }
+    expect(h.at(2999.5).get(1)?.x).toBeCloseTo(2999);
+    expect(h.at(3000).get(1)?.x).toBeCloseTo(3000);
+    expect(h.interp.entered).toEqual([1, 2]);
+    expect(h.interp.left).toEqual([1, 2]);
+    const retained = h.interp as unknown as { ended: unknown[] };
+    expect(retained.ended.length).toBeLessThan(2048);
+    h.frame(1, { full: true, spawn: [{ id: 3, pos: [7, 0, 0] }] });
+    expect([...h.at(1).keys()]).toEqual([3]);
+    h.frame(2, { despawn: [3] });
+    h.frame(300, {});
+    expect(h.at(300).size).toBe(0);
+    expect(retained.ended.length).toBe(0);
+  });
 });

package/src/interpolation.ts

@@ -93,7 +93,8 @@ export class EntityInterpolator {
   private drawn = -1;
   /** Lives that ended, oldest first, so `record` can drop them when
    *  `update` does not run (a hidden tab keeps receiving frames). */
-  private ended: Array<{ id: number; life: Life }> = [];
+  private ended: Array<{ id: number; life: Life } | undefined> = [];
+  private endedStart = 0;
 
   constructor(options: InterpolationOptions = {}) {
     this.snapDistance = options.snapDistance ?? Infinity;
@@ -120,6 +121,7 @@ export class EntityInterpolator {
   clear(): void {
     this.lives.clear();
     this.ended = [];
+    this.endedStart = 0;
     this.lastTick = -1;
     this.floor = -Infinity;
     this.drawn = -1;
@@ -215,18 +217,26 @@ export class EntityInterpolator {
    * when it runs; this bounds them when it does not.
    */
   private dropEnded(tick: number): void {
-    let n = 0;
-    while (n < this.ended.length && (this.ended[n].life.despawnTick as number) < tick - ENDED_TICKS) {
-      const { id, life } = this.ended[n];
+    while (this.endedStart < this.ended.length) {
+      const { id, life } = this.ended[this.endedStart]!;
+      const expired = (life.despawnTick as number) < tick - ENDED_TICKS;
+      if (!expired) break;
       const lives = this.lives.get(id);
       if (lives) {
         const i = lives.indexOf(life);
         if (i >= 0) lives.splice(i, 1);
         if (lives.length === 0) this.lives.delete(id);
       }
-      n++;
+      // Release the life now, without shifting the retained entries.
+      this.ended[this.endedStart++] = undefined;
+    }
+    if (this.endedStart === this.ended.length) {
+      this.ended = [];
+      this.endedStart = 0;
+    } else if (this.endedStart >= 1024 && this.endedStart >= this.ended.length / 2) {
+      this.ended = this.ended.slice(this.endedStart);
+      this.endedStart = 0;
     }
-    if (n > 0) this.ended.splice(0, n);
   }
 
   private openLife(id: number): Life | null {

package/src/replication.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { replicationPayload } from "../test/frames";
 import { EntityTable, ReplicationError } from "./replication";
 import fixtures from "./replication.fixtures.json";
 
@@ -13,6 +14,76 @@ function hex(b: Uint8Array): string {
   return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
 }
 
+describe("stream position updates", () => {
+  test("empty and sparse frames do not read unchanged positions", () => {
+    const table = new EntityTable();
+    table.apply(replicationPayload({
+      full: true,
+      spawn: [
+        { id: 1, pos: [1, 2, 3] },
+        { id: 2, pos: [4, 5, 6] },
+      ],
+    }));
+    const quiet = table.get(2)!;
+    let reads = 0;
+    const qx = quiet.qx;
+    Object.defineProperty(quiet, "qx", {
+      get() {
+        reads++;
+        return qx;
+      },
+    });
+    table.apply(replicationPayload({}), 2);
+    const summary = table.apply(replicationPayload({
+      update: [{ id: 1, from: [1, 2, 3], pos: [-1, 8, 3] }],
+    }), 3);
+    expect(reads).toBe(0);
+    expect(summary.updated).toEqual([1]);
+    const moved = table.get(1)!;
+    expect([moved.x, moved.y, moved.z]).toEqual([-100, 800, 300].map((q) => q * table.precision));
+    expect([quiet.x, quiet.y, quiet.z]).toEqual([400, 500, 600].map((q) => q * table.precision));
+    expect(table.streamTick).toBe(3);
+  });
+
+  test("precision changes rescale unchanged entities", () => {
+    const table = new EntityTable();
+    table.apply(replicationPayload({
+      spawn: [
+        { id: 1, pos: [1, 2, -3] },
+        { id: 2, pos: [4, 5, 6] },
+      ],
+    }));
+    const frame = replicationPayload({ update: [{ id: 1, from: [1, 2, -3], pos: [2, 2, -3] }] });
+    new DataView(frame.buffer).setFloat32(2, 0.5, true);
+    table.apply(frame);
+    expect([table.get(1)!.x, table.get(1)!.y, table.get(1)!.z]).toEqual([100, 100, -150]);
+    expect([table.get(2)!.x, table.get(2)!.y, table.get(2)!.z]).toEqual([200, 250, 300]);
+    const empty = replicationPayload({});
+    new DataView(empty.buffer).setFloat32(2, 0.25, true);
+    table.apply(empty);
+    expect(table.get(2)!.x).toBe(100);
+  });
+
+  test("mixed frames and full replacements retain positions and components", () => {
+    const table = new EntityTable();
+    table.apply(replicationPayload({ spawn: [{ id: 1 }, { id: 2 }] }));
+    table.apply(replicationPayload({
+      despawn: [1],
+      spawn: [{ id: 3, pos: [7, -8, 9] }],
+      update: [
+        { id: 2, components: { 4: [1, 2] } },
+        { id: 3, from: [7, -8, 9], pos: [8, -8, 9] },
+      ],
+    }));
+    expect(table.get(1)).toBeUndefined();
+    expect(table.get(2)!.components.get(4)).toEqual(new Uint8Array([1, 2]));
+    expect(table.get(3)!.x).toBe(800 * table.precision);
+    table.apply(replicationPayload({ full: true, spawn: [{ id: 4, pos: [-2, 3, 4] }] }));
+    expect([...table.entities.keys()]).toEqual([4]);
+    expect(table.get(4)!.x).toBe(-200 * table.precision);
+  });
+});
+
 describe("the Rust encoder's frames (replication.fixtures.json)", () => {
   test("apply to the same tables the Rust decoder holds", () => {
     const table = new EntityTable();

package/src/replication.ts

@@ -275,6 +275,7 @@ export class EntityTable {
       this.datagramFrames.clear();
       this.spawnTicks.clear();
     }
+    const precisionChanged = precision !== this.precision;
     this.precision = precision;
     const summary: ReplicationSummary = { full, spawned: [], updated: [], despawned: [] };
 
@@ -324,15 +325,20 @@ export class EntityTable {
       if (mask & MASK_Y) e.qy = toSafe(BigInt(e.qy) + r.zigzag(), "position");
       if (mask & MASK_Z) e.qz = toSafe(BigInt(e.qz) + r.zigzag(), "position");
       if (mask & MASK_COMPONENTS) readComponents(r, e.components);
+      e.x = e.qx * precision;
+      e.y = e.qy * precision;
+      e.z = e.qz * precision;
       summary.updated.push(last);
     }
     if (!r.done) throw new ReplicationError("trailing bytes");
 
-    // Positions follow the frame's precision (a full frame may change it).
-    for (const e of this.entities.values()) {
-      e.x = e.qx * precision;
-      e.y = e.qy * precision;
-      e.z = e.qz * precision;
+    // A precision change also affects entities absent from this frame.
+    if (precisionChanged) {
+      for (const e of this.entities.values()) {
+        e.x = e.qx * precision;
+        e.y = e.qy * precision;
+        e.z = e.qz * precision;
+      }
     }
     if (tick !== undefined) this.streamTick = tick;
     return summary;

package/src/wire.test.ts

@@ -6,13 +6,52 @@ import {
   SHARD_HEADER_LEN,
   ShardCodec,
   ShardFrameKind,
+  StreamFrames,
   decodeShardPayload,
   decodeShardRejection,
   encodeDatagramAckBatches,
   encodeShardInput,
   parseShardFrame,
+  lengthPrefixed,
 } from "./wire";
 
+describe("StreamFrames", () => {
+  test("decodes fragmented headers, empty frames, and combined frames", () => {
+    const messages = [new Uint8Array(), new Uint8Array([1, 2, 3]), new Uint8Array([4])];
+    const wire = new Uint8Array(messages.reduce((sum, value) => sum + value.length + 4, 0));
+    let at = 0;
+    for (const message of messages) {
+      wire.set(lengthPrefixed(message), at);
+      at += message.length + 4;
+    }
+    for (const size of [1, 2, 3, 4, 7, wire.length]) {
+      const decoder = new StreamFrames();
+      const frames: ArrayBuffer[] = [];
+      expect(decoder.push(new Uint8Array())).toEqual([]);
+      for (let offset = 0; offset < wire.length; offset += size) {
+        frames.push(...decoder.push(wire.subarray(offset, offset + size)));
+      }
+      expect(frames.map((value) => [...new Uint8Array(value)])).toEqual(messages.map((value) => [...value]));
+    }
+  });
+
+  test("completed frames own their bytes for contiguous and fragmented inputs", () => {
+    for (const split of [1, 5, 10]) {
+      const source = lengthPrefixed(new Uint8Array([1, 2, 3, 4, 5, 6]));
+      const decoder = new StreamFrames();
+      const frames = [...decoder.push(source.subarray(0, split)), ...decoder.push(source.subarray(split))];
+      source.fill(0);
+      expect([...new Uint8Array(frames[0])]).toEqual([1, 2, 3, 4, 5, 6]);
+    }
+  });
+
+  test("rejects oversized frames before buffering their body", () => {
+    const header = new Uint8Array(4);
+    new DataView(header.buffer).setUint32(0, 64 * 1024 * 1024 + 1);
+    expect(() => new StreamFrames().push(header)).toThrow("stream frame");
+  });
+});
+
 function frame(kind: number, codec: number, tick: number, ack: number, payload: Uint8Array) {
   const buf = new ArrayBuffer(SHARD_HEADER_LEN + payload.length);
   const view = new DataView(buf);

package/src/wire.ts

@@ -323,6 +323,7 @@ export class StreamFrames {
 
   /** Add a chunk and return the frames it completed. */
   push(chunk: Uint8Array): ArrayBuffer[] {
+    if (chunk.length === 0) return [];
     this.chunks.push(chunk);
     this.buffered += chunk.length;
     const frames: ArrayBuffer[] = [];
@@ -331,9 +332,10 @@ export class StreamFrames {
       const len = new DataView(head.buffer, head.byteOffset, 4).getUint32(0);
       if (len > MAX_STREAM_FRAME) throw new Error(`a ${len}-byte stream frame`);
       if (this.buffered < 4 + len) break;
-      this.take(4);
-      const frame = this.take(len);
-      frames.push(frame.buffer.slice(frame.byteOffset, frame.byteOffset + frame.length) as ArrayBuffer);
+      this.consume(4);
+      const frame = new Uint8Array(len);
+      this.consume(len, frame);
+      frames.push(frame.buffer);
     }
     return frames;
   }
@@ -351,11 +353,11 @@ export class StreamFrames {
     return out;
   }
 
-  private take(n: number): Uint8Array {
-    const out = this.peek(n);
+  private consume(n: number, output?: Uint8Array): void {
     let left = n;
     while (left > 0) {
       const c = this.chunks[0];
+      if (output) output.set(c.subarray(0, Math.min(c.length, left)), n - left);
       if (c.length <= left) {
         this.chunks.shift();
         left -= c.length;
@@ -365,6 +367,5 @@ export class StreamFrames {
       }
     }
     this.buffered -= n;
-    return out;
   }
 }