@series-inc/rundot-syncplay 5.25.0-beta.4 → 5.25.0-beta.5

package/README.md

@@ -157,6 +157,21 @@ presentation-only and never feeds simulation. Starting a new mode always tears
 down the old one, and a stale async connection/preparation closes without
 replacing the current session.
 
+**Incremental adoption (mature games).** A game with its own stateful renderer,
+input model, and connection UI can swap only its lifecycle orchestration onto the
+runner without rewriting those layers:
+
+- Keep your own presentation singleton — use an identity `project: (frame) => frame`
+  and feed your renderer from the `subscribe` snapshot (`renderState`, `renderAlpha`)
+  instead of `getRenderState()`.
+- Supply `localInputForTick: (slot, frame) => Input` when your local input is a
+  per-tick pulse/edge that must be consumed and cleared each frame; the runner then
+  reads it (offline local slot and networked prediction) instead of the persistent
+  `applyInput(...)` value.
+- Drive a room badge from the snapshot's `ready`, `appliedThrough`, `predictedThrough`,
+  `localSlot`, and `status` — no reach into the underlying client (e.g. `appliedThrough < 0`
+  means "waiting for peers"; `predictedThrough - appliedThrough` is the catch-up depth).
+
 Direct `NetworkedSyncplayClient` users get the same projection surface:
 `getPresentationFrame()`, `renderAlpha`, `currentFrame`, `caughtUp`, and a
 bounded confirmed-frame queue via the optional `confirmedPresentationBufferSize`

package/dist/runner.d.ts

@@ -31,6 +31,14 @@ export interface SyncplayRunnerConfig<State, Input, Checkpoint, Projection, Rend
     readonly prepareNetworkRuntime?: (descriptor: NetworkedSyncplaySessionDescriptor, signal: AbortSignal) => Promise<void>;
     readonly maxPredictionTicks?: number;
     readonly maxOfflineStepsPerUpdate?: number;
+    /**
+     * Local-slot input provider for incremental adoption. A mature game whose
+     * input is a per-tick pulse/edge (consumed and cleared each frame) supplies
+     * its own reader here instead of relying on the persistent `applyInput`
+     * value. Called once per simulated local frame (offline and networked). When
+     * omitted, the runner uses the last `applyInput(...)` value verbatim.
+     */
+    readonly localInputForTick?: (slot: number, frame: number) => Input;
 }
 export interface SyncplayRunnerOfflineOptions<Input> {
     readonly identity: KinetixRuntimeIdentity;
@@ -45,6 +53,16 @@ export interface SyncplayRunnerSnapshot<RenderState> {
     readonly renderAlpha: number;
     readonly localSlot: number;
     readonly rollbackCount: number;
+    /**
+     * Networked session telemetry, surfaced so a connection UI (e.g. a room
+     * badge) can retrofit onto the runner without reaching into the client.
+     * Offline: `ready` is true once a session exists and the frame counters
+     * track the local session. Before any session/client: `ready` false,
+     * `appliedThrough` -1, `predictedThrough` 0.
+     */
+    readonly ready: boolean;
+    readonly appliedThrough: number;
+    readonly predictedThrough: number;
     readonly error?: Error;
 }
 export interface SyncplayRunner<Input, RenderState, EventPayload> {
@@ -52,6 +70,9 @@ export interface SyncplayRunner<Input, RenderState, EventPayload> {
     readonly renderAlpha: number;
     readonly localSlot: number;
     readonly rollbackCount: number;
+    readonly ready: boolean;
+    readonly appliedThrough: number;
+    readonly predictedThrough: number;
     startOffline(options: SyncplayRunnerOfflineOptions<Input>): void;
     startNetworked(connect: () => Promise<SyncplayRunnerTransport>): Promise<void>;
     applyInput(input: Input): void;

package/dist/runner.js

@@ -34,6 +34,21 @@ export function createSyncplayRunner(config) {
         for (const listener of eventListeners)
             listener(dispatch.record);
     });
+    function telemetryReady() {
+        if (networkClient !== undefined)
+            return networkClient.ready;
+        return localSession !== undefined;
+    }
+    function telemetryAppliedThrough() {
+        if (networkClient !== undefined)
+            return networkClient.appliedThrough;
+        return localSession !== undefined ? localSession.currentFrame : -1;
+    }
+    function telemetryPredictedThrough() {
+        if (networkClient !== undefined)
+            return networkClient.predictedThrough;
+        return localSession !== undefined ? localSession.currentFrame : 0;
+    }
     function snapshot() {
         return Object.freeze({
             status,
@@ -41,6 +56,9 @@ export function createSyncplayRunner(config) {
             renderAlpha,
             localSlot,
             rollbackCount: networkClient?.rollbacks ?? 0,
+            ready: telemetryReady(),
+            appliedThrough: telemetryAppliedThrough(),
+            predictedThrough: telemetryPredictedThrough(),
             ...(status === 'error' && error !== undefined ? { error } : {}),
         });
     }
@@ -165,7 +183,9 @@ export function createSyncplayRunner(config) {
                 transport: clientTransport,
                 runtimeFactory: config.runtimeFactory,
                 defaultInput: config.defaultInput,
-                localInputForTick: () => structuredClone(latestInput),
+                localInputForTick: (slot, tick) => config.localInputForTick !== undefined
+                    ? config.localInputForTick(slot, tick)
+                    : structuredClone(latestInput),
                 encodeInput: config.encodeInput,
                 decodeInput: config.decodeInput,
                 confirmedPresentationBufferSize: 256,
@@ -205,7 +225,7 @@ export function createSyncplayRunner(config) {
                 const nextFrame = localSession.currentFrame + 1;
                 for (let slot = 0; slot < offlineOptions.playerCount; slot += 1) {
                     const input = slot === localSlot
-                        ? latestInput
+                        ? (config.localInputForTick !== undefined ? config.localInputForTick(slot, nextFrame) : latestInput)
                         : offlineOptions.botInputForTick?.(slot, nextFrame) ?? config.defaultInput;
                     localSession.setInput(slot, structuredClone(input));
                 }
@@ -265,6 +285,9 @@ export function createSyncplayRunner(config) {
         get renderAlpha() { return renderAlpha; },
         get localSlot() { return localSlot; },
         get rollbackCount() { return networkClient?.rollbacks ?? 0; },
+        get ready() { return telemetryReady(); },
+        get appliedThrough() { return telemetryAppliedThrough(); },
+        get predictedThrough() { return telemetryPredictedThrough(); },
         startOffline,
         startNetworked,
         applyInput(input) { latestInput = structuredClone(input); },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/rundot-syncplay",
-  "version": "5.25.0-beta.4",
+  "version": "5.25.0-beta.5",
   "description": "Kinetix orchestration, rollback, replay, late-join, and deterministic networking for RUN.game",
   "repository": {
     "type": "git",