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

package/README.md

@@ -157,6 +157,25 @@ 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).
+- Tune the networked client through the runner: `pacing` (`targetLeadTicks`,
+  `maxStepsPerPump`, drift correction) and `inputDelay` (`minTicks`/`maxTicks`,
+  RTT-adaptive) are forwarded verbatim, and live `netStats` (RTT, timescale, input
+  delay) is surfaced on the snapshot + runner (`null` offline) for a netcode HUD.
+
 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

@@ -1,5 +1,5 @@
 import type { DeterministicEventRecord } from './events.js';
-import { type KinetixRuntimeFactory, type NetworkedClientTransport, type NetworkedSyncplaySessionDescriptor, type NetworkedSyncplayClientOptions } from './networked-client.js';
+import { type KinetixRuntimeFactory, type NetworkedClientTransport, type NetworkedSyncplaySessionDescriptor, type NetworkedSyncplayClientInputDelayOptions, type NetworkedSyncplayClientNetStats, type NetworkedSyncplayClientOptions, type NetworkedSyncplayClientPacingOptions } from './networked-client.js';
 import type { KinetixRuntimeIdentity } from './runtime-session.js';
 export type SyncplayRunnerStatus = 'offline' | 'connecting' | 'syncing' | 'live' | 'stopped' | 'error';
 export type SyncplayRunnerConnectionEvent = {
@@ -31,6 +31,24 @@ 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;
+    /**
+     * Wall-clock pacing + clock-drift correction for the networked client (G1).
+     * Forwarded verbatim; omit for the client defaults.
+     */
+    readonly pacing?: NetworkedSyncplayClientPacingOptions;
+    /**
+     * Local input delay for the networked client. `maxTicks > minTicks` auto-tunes
+     * from measured RTT. Forwarded verbatim; omit for the client default (0).
+     */
+    readonly inputDelay?: NetworkedSyncplayClientInputDelayOptions;
 }
 export interface SyncplayRunnerOfflineOptions<Input> {
     readonly identity: KinetixRuntimeIdentity;
@@ -45,6 +63,18 @@ 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;
+    /** Live networked netcode telemetry (RTT, timescale, input delay); null offline. */
+    readonly netStats: NetworkedSyncplayClientNetStats | null;
     readonly error?: Error;
 }
 export interface SyncplayRunner<Input, RenderState, EventPayload> {
@@ -52,6 +82,10 @@ export interface SyncplayRunner<Input, RenderState, EventPayload> {
     readonly renderAlpha: number;
     readonly localSlot: number;
     readonly rollbackCount: number;
+    readonly ready: boolean;
+    readonly appliedThrough: number;
+    readonly predictedThrough: number;
+    readonly netStats: NetworkedSyncplayClientNetStats | null;
     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,10 @@ export function createSyncplayRunner(config) {
             renderAlpha,
             localSlot,
             rollbackCount: networkClient?.rollbacks ?? 0,
+            ready: telemetryReady(),
+            appliedThrough: telemetryAppliedThrough(),
+            predictedThrough: telemetryPredictedThrough(),
+            netStats: networkClient?.netStats ?? null,
             ...(status === 'error' && error !== undefined ? { error } : {}),
         });
     }
@@ -165,11 +184,15 @@ 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,
                 ...(config.maxPredictionTicks === undefined ? {} : { maxPredictionTicks: config.maxPredictionTicks }),
+                ...(config.pacing === undefined ? {} : { pacing: config.pacing }),
+                ...(config.inputDelay === undefined ? {} : { inputDelay: config.inputDelay }),
             });
             networkClient = client;
             await client.whenReady();
@@ -205,7 +228,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 +288,10 @@ 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(); },
+        get netStats() { return networkClient?.netStats ?? null; },
         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.6",
   "description": "Kinetix orchestration, rollback, replay, late-join, and deterministic networking for RUN.game",
   "repository": {
     "type": "git",