@series-inc/rundot-syncplay 5.25.0-beta.0 → 5.25.0-beta.2

package/README.md

@@ -52,6 +52,33 @@ session-config bytes, asks the game for a matching runtime through its runtime
 factory, and rejects a locally loaded pack mismatch before frame 0. Replays use
 the same identity/config/factory path.
 
+## Presentation frames
+
+`session.getState()` returns a detached deep copy of the current frame, which
+costs O(state) per read and is unaffordable for a large mutable world (a
+destructible voxel city, a big streaming map).
+
+`session.getPresentationFrame()` is the no-clone path. It calls the runtime's
+optional `project(checkpoint, previous)` and returns the result untouched:
+
+- **Requires** a runtime built with a `projectState` hook. A runtime without
+  `project` throws `SYNCPLAY_PROJECTION_UNSUPPORTED` — there is no silent
+  fallback to `inspect`.
+- **The result is immutable.** Callers must not mutate it. It may share structure
+  with authoritative state and with previously returned projections, which is
+  exactly what lets a renderer diff persistent roots and skip shared subtrees.
+- **`previous` is the last frame this session projected**, enabling delta
+  projections. It is absent — meaning the runtime should produce a full frame —
+  on the first call, after `restoreToFrame` or `restoreSnapshot`, and whenever
+  the previously projected frame is no longer retained (pruned or rolled past).
+- **Reading the same frame twice is free and idempotent.** Repeat calls return
+  the identical projection rather than re-projecting the frame against itself
+  (which would report an empty delta). Authoritative state cannot change without
+  the frame advancing, so multiple render passes per frame are safe.
+
+Projections are presentation-only: they never re-enter simulation and are not
+part of deterministic identity.
+
 ## Public projections and secrets
 
 Every peer applies the same confirmed inputs and authority commands. Optional

package/dist/runtime-session.d.ts

@@ -1,6 +1,19 @@
 import { type KinetixRuntime, type KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
 import type { RecordedChecksum, RecordedCommandFrame, RecordedInputFlags, RecordedInputFrame, ReplayFile } from './types.js';
 export type { KinetixRuntime, KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
+/**
+ * A Kinetix runtime that may expose the optional no-clone presentation
+ * projection, re-typed for this session's Projection.
+ *
+ * `project` is omitted and re-declared rather than inherited so this compiles
+ * against both Kinetix builds we resolve against: the published ABI v1 runtime
+ * (no `project`) that the lockfile pins and publish lanes keep, and the
+ * in-repo runtime (whose `project` defaults to `Projection = State`) that test
+ * lanes overlay. Presence is feature-detected at runtime either way.
+ */
+export type ProjectionCapableRuntime<State, Input, Checkpoint, Projection> = Omit<KinetixRuntime<State, Input, Checkpoint>, 'project'> & {
+    project?(checkpoint: Checkpoint, previous?: Checkpoint): Readonly<Projection>;
+};
 export interface RuntimeExternalSnapshot<Input> {
     readonly frame: number;
     readonly runtimeBytes: Uint8Array;
@@ -16,8 +29,8 @@ export interface RuntimeFrameSnapshot<State, Input, Checkpoint> {
     readonly checkpoint: Checkpoint;
     readonly state: State;
 }
-export interface RuntimeSessionConfig<State, Input, Checkpoint> {
-    readonly runtime: KinetixRuntime<State, Input, Checkpoint>;
+export interface RuntimeSessionConfig<State, Input, Checkpoint, Projection = State> {
+    readonly runtime: ProjectionCapableRuntime<State, Input, Checkpoint, Projection>;
     readonly playerCount: number;
     readonly defaultInput: Input;
     readonly snapshotBufferSize?: number;
@@ -30,7 +43,7 @@ export interface RuntimeSessionConfig<State, Input, Checkpoint> {
     readonly onCommandFrameRecorded?: (frame: RecordedCommandFrame) => void;
     readonly onChecksumRecorded?: (checksum: RecordedChecksum) => void;
 }
-export interface RuntimeSession<State, Input, Checkpoint = unknown> {
+export interface RuntimeSession<State, Input, Checkpoint = unknown, Projection = State> {
     readonly currentFrame: number;
     readonly accumulatedMs: number;
     readonly schemaIdentity: KinetixRuntimeIdentity;
@@ -40,6 +53,13 @@ export interface RuntimeSession<State, Input, Checkpoint = unknown> {
     update(deltaMs: number): number;
     stepFrames(count: number): void;
     getState(): State;
+    /**
+     * Projects the current frame for presentation without cloning. Requires a
+     * runtime that implements `project`; throws SYNCPLAY_PROJECTION_UNSUPPORTED
+     * otherwise. The result is immutable and may share structure with previous
+     * frames — callers must not mutate it.
+     */
+    getPresentationFrame(): Readonly<Projection>;
     exportReplay(): ReplayFile;
     peekSnapshot(frame: number): RuntimeFrameSnapshot<State, Input, Checkpoint> | undefined;
     getSnapshot(frame: number): RuntimeFrameSnapshot<State, Input, Checkpoint> | undefined;
@@ -53,4 +73,4 @@ export interface RuntimeSession<State, Input, Checkpoint = unknown> {
     getSnapshotFrames(): readonly number[];
     dispose(): void;
 }
-export declare function createRuntimeSession<State, Input, Checkpoint>(config: RuntimeSessionConfig<State, Input, Checkpoint>): RuntimeSession<State, Input, Checkpoint>;
+export declare function createRuntimeSession<State, Input, Checkpoint, Projection = State>(config: RuntimeSessionConfig<State, Input, Checkpoint, Projection>): RuntimeSession<State, Input, Checkpoint, Projection>;

package/dist/runtime-session.js

@@ -38,6 +38,7 @@ export function createRuntimeSession(config) {
     let accumulatedMs = 0;
     let disposed = false;
     let hydrated = false;
+    let lastProjected;
     const frame0 = config.runtime.capture();
     retained.set(config.runtime.currentFrame, {
         checkpoint: frame0,
@@ -116,7 +117,19 @@ export function createRuntimeSession(config) {
                 checksum: frame % checksumInterval === 0,
             });
         }
-        const results = config.runtime.advance(requests);
+        let results;
+        try {
+            results = config.runtime.advance(requests);
+        }
+        catch (error) {
+            // advance() is atomic: the batch stepped no frames, so its commands must
+            // not be replayed on the next attempt. A command the runtime refuses to
+            // decode would otherwise be rebuilt into every subsequent request and
+            // wedge the session permanently.
+            for (const request of requests)
+                pendingCommands.delete(request.frame);
+            throw error;
+        }
         if (results.length !== requests.length)
             throw new Error('SYNCPLAY_RUNTIME_RESULT_COUNT_MISMATCH');
         for (let index = 0; index < results.length; index += 1) {
@@ -205,9 +218,11 @@ export function createRuntimeSession(config) {
             const count = Math.max(0, Math.floor((total * config.runtime.identity.tickRate + 1e-9) / 1000));
             if (count > (config.maxCatchUpFrames ?? 240))
                 throw new Error('session.catch-up-limit');
-            accumulatedMs = total;
             runFrames(count);
-            accumulatedMs = Math.max(0, accumulatedMs - count * (1000 / config.runtime.identity.tickRate));
+            // Commit consumed time only after the frames actually land; if runFrames
+            // throws, accumulatedMs keeps its pre-update value so a later update does
+            // not over-count catch-up for frames that never stepped.
+            accumulatedMs = Math.max(0, total - count * (1000 / config.runtime.identity.tickRate));
             return count;
         },
         stepFrames: runFrames,
@@ -215,6 +230,29 @@ export function createRuntimeSession(config) {
             active();
             return structuredClone(config.runtime.inspect(requireRetained(config.runtime.currentFrame).checkpoint));
         },
+        getPresentationFrame() {
+            active();
+            const project = config.runtime.project;
+            if (typeof project !== 'function')
+                throw new Error('SYNCPLAY_PROJECTION_UNSUPPORTED');
+            const frame = config.runtime.currentFrame;
+            const entry = requireRetained(frame);
+            // Re-reading a frame must not diff it against itself — a delta hook given
+            // the current frame as its own baseline would report nothing changed.
+            // State cannot move without the frame advancing, so the projection this
+            // frame already produced is still the answer.
+            if (lastProjected?.frame === frame)
+                return lastProjected.projection;
+            // A previously projected frame may have been pruned or rolled past; the
+            // runtime then gets no baseline and produces a full frame. Deliberate
+            // contract, not a fallback.
+            const previous = lastProjected === undefined
+                ? undefined
+                : retained.get(lastProjected.frame)?.checkpoint;
+            const projection = project.call(config.runtime, entry.checkpoint, previous);
+            lastProjected = { frame, projection };
+            return projection;
+        },
         exportReplay() {
             active();
             if (hydrated)
@@ -277,6 +315,7 @@ export function createRuntimeSession(config) {
             commandFrames.splice(0, commandFrames.length, ...commandFrames.filter((record) => record.frame <= frame));
             checksums.splice(0, checksums.length, ...checksums.filter((record) => record.frame <= frame));
             accumulatedMs = 0;
+            lastProjected = undefined;
         },
         restoreSnapshot(snapshot) {
             active();
@@ -314,6 +353,7 @@ export function createRuntimeSession(config) {
             commandFrames.length = 0;
             checksums.length = 0;
             accumulatedMs = 0;
+            lastProjected = undefined;
             hydrated = true;
         },
         getSnapshotFrames() { active(); return [...retained.keys()]; },
@@ -323,6 +363,9 @@ export function createRuntimeSession(config) {
             for (const entry of retained.values())
                 release(entry.checkpoint);
             retained.clear();
+            // A projection may share structure with the whole world; releasing the
+            // checkpoints while still pinning it would defeat the release.
+            lastProjected = undefined;
             disposed = true;
         },
     };

package/dist/sdk-session.d.ts

@@ -1,5 +1,4 @@
-import type { KinetixRuntime } from '@series-inc/rundot-kinetix/runtime';
-import { type RuntimeSession, type RuntimeSessionConfig } from './runtime-session.js';
-export type SyncplaySessionPolicy<State, Input, Checkpoint = unknown> = Omit<RuntimeSessionConfig<State, Input, Checkpoint>, 'runtime'>;
-export type SyncplaySession<State, Input, Checkpoint = unknown> = RuntimeSession<State, Input, Checkpoint>;
-export declare function createSyncplaySession<State, Input, Checkpoint = unknown>(runtime: KinetixRuntime<State, Input, Checkpoint>, policy: SyncplaySessionPolicy<State, Input, Checkpoint>): SyncplaySession<State, Input, Checkpoint>;
+import { type ProjectionCapableRuntime, type RuntimeSession, type RuntimeSessionConfig } from './runtime-session.js';
+export type SyncplaySessionPolicy<State, Input, Checkpoint = unknown, Projection = State> = Omit<RuntimeSessionConfig<State, Input, Checkpoint, Projection>, 'runtime'>;
+export type SyncplaySession<State, Input, Checkpoint = unknown, Projection = State> = RuntimeSession<State, Input, Checkpoint, Projection>;
+export declare function createSyncplaySession<State, Input, Checkpoint = unknown, Projection = State>(runtime: ProjectionCapableRuntime<State, Input, Checkpoint, Projection>, policy: SyncplaySessionPolicy<State, Input, Checkpoint, Projection>): SyncplaySession<State, Input, Checkpoint, Projection>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/rundot-syncplay",
-  "version": "5.25.0-beta.0",
+  "version": "5.25.0-beta.2",
   "description": "Kinetix orchestration, rollback, replay, late-join, and deterministic networking for RUN.game",
   "repository": {
     "type": "git",
@@ -49,8 +49,9 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "npm run test:core",
-    "test:core": "tsx --test tests/canonical.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts",
+    "test:core": "tsx --test tests/canonical.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts tests/test-manifest.test.ts",
     "test:soak": "tsx --test tests/runtime-soak.test.ts",
+    "test:extended": "tsx --test tests/animation.test.ts tests/asset-cooking.test.ts tests/backend-proof-checksum-vectors.test.ts tests/bot-documents.test.ts tests/bot-primitives.test.ts tests/collider-cooking.test.ts tests/collision.test.ts tests/command-timeline.test.ts tests/config-bundle.test.ts tests/cosmetic-physics3d.test.ts tests/deterministic-primitives.test.ts tests/ecs-lite.test.ts tests/effects-adapter.test.ts tests/engine-runtime.test.ts tests/errors.test.ts tests/events.test.ts tests/input-button.test.ts tests/load-128-players.test.ts tests/math.test.ts tests/movement.test.ts tests/movement3d.test.ts tests/multiclient-authority.test.ts tests/navigation.test.ts tests/noise.test.ts tests/physics-cert.test.ts tests/physics2d.test.ts tests/physics3d-ccd.test.ts tests/physics3d-coverage.test.ts tests/physics3d-destruction-cert.test.ts tests/physics3d-heightfield.test.ts tests/physics3d-hull.test.ts tests/physics3d-joints.test.ts tests/physics3d-kinematic-mesh.test.ts tests/physics3d-mass.test.ts tests/physics3d-materials.test.ts tests/physics3d-mesh-onesided.test.ts tests/physics3d-query-index.test.ts tests/physics3d-recipes.test.ts tests/physics3d-rotation-convention.test.ts tests/physics3d-shared.test.ts tests/physics3d-sleeping-manifold-reuse.test.ts tests/physics3d-solver.test.ts tests/physics3d-stacking.test.ts tests/physics3d-toi.test.ts tests/physics3d-vehicle.test.ts tests/physics3d-voxel.test.ts tests/physics3d-world-edit.test.ts tests/physics3d.test.ts tests/random.test.ts tests/rollback-history.test.ts tests/schema-artifacts.test.ts tests/schema-codegen.test.ts tests/schema-dsl-binary.test.ts tests/schema.test.ts tests/signals.test.ts tests/sparse-set.test.ts tests/static-checker.test.ts tests/system-lifecycle.test.ts tests/wire-canonical-sentinels.test.ts tests/ws-frame.test.ts",
     "test:ci": "npm run build && npm run test:core",
     "pack:dry-run": "npm pack --dry-run"
   },
@@ -64,7 +65,7 @@
     "Kinetix"
   ],
   "dependencies": {
-    "@series-inc/rundot-kinetix": "0.1.0-beta.0"
+    "@series-inc/rundot-kinetix": "0.1.0-beta.6"
   },
   "devDependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",