@series-inc/rundot-syncplay 5.28.0-beta.4 → 6.0.0-rc.2

package/README.md

@@ -1,11 +1,10 @@
 # RUN Syncplay
 
-Syncplay is the orchestration layer over a signed deterministic runtime. The
-deterministic core ships inside this package under the `/core` subpaths
-(`@series-inc/rundot-syncplay/core/...`): it owns deterministic state, RNG
-streams, stepping, opaque checkpoints, serialization, hydration, and checksums.
-Syncplay owns inputs, prediction, confirmation, rollback policy, replay logs,
-late join, secrets, and transport.
+Syncplay is the orchestration layer over a signed deterministic runtime. Public
+runtime utilities use the `/core` subpaths. Public physics uses `/physics/2d`
+and `/physics/3d`. Both physics APIs use the canonical C++ core compiled to
+WASM. Syncplay owns inputs, prediction, confirmation, rollback policy, replay
+logs, late join, secrets, and transport.
 
 ## Installation
 
@@ -134,7 +133,8 @@ The published JavaScript graph has a committed exhaustive side-effect audit.
 effects and are preserved through the package's precise `sideEffects` allowlist.
 
 > **Upgrading an existing game?** See
-> [MIGRATING-SESSION-PRIMITIVES.md](./MIGRATING-SESSION-PRIMITIVES.md). Two
+> [the RC1 migration guide](https://github.com/series-ai/venus/blob/develop/packages/sdk-docs/rundot-developer-platform/api/SYNCPLAY-RC1-MIGRATION.md)
+> and [the session primitive guide](https://github.com/series-ai/venus/blob/develop/packages/syncplay/MIGRATING-SESSION-PRIMITIVES.md). Two
 > changes are not additive: the runner now rejects an unsafe input codec at
 > construction, and the effects adapter now dedupes on your event `dedupeKey`.
 
@@ -158,8 +158,9 @@ dependency float cannot keep the same engine hash.
 | Subpath | Role |
 |---------|------|
 | `/core/runtime` | `createInstalledRuntimeAdapter`, identity helpers |
-| `/core/physics` | WASM physics (`initPhysics`, …) — reference solver |
-| `/` or `/browser` | KCC, runner, session, **TypeScript** physics — the solver `stepDeterministicKcc3D` collides against |
+| `/physics/2d` | Canonical TypeScript 2D API over the C++/WASM core |
+| `/physics/3d` | Canonical TypeScript 3D API over the C++/WASM core |
+| `/` or `/browser` | Runner, session, and 3D character movement |
 | `/testing` | Simulated multi-peer / synctest |
 | `/node` | Authority room helpers (not for browser bundles) |
 
@@ -298,14 +299,22 @@ const runner = createSyncplayRunner({
     events: (frame) => frame.events,
   },
 })
-runner.startOffline({ identity, sessionConfigBytes, playerCount: 2, botInputForTick })
-await runner.startNetworked(() => createSyncplayRoom(api.realtime, roomOptions))
+await runner.start({
+  mode: 'offline', identity, sessionConfigBytes, playerCount: 2, botInputForTick,
+})
 runner.applyInput(readInput())
 runner.update(deltaMs)
 render(runner.getRenderState(), runner.renderAlpha)
+runner.stop()
+await runner.start({
+  mode: 'networked',
+  connect: (signal) => createSyncplayRoom(api.realtime, roomOptions, signal),
+})
+runner.dispose()
 ```
 
-**Status** is exactly `offline | connecting | syncing | live | stopped | error`:
+`runner.lifecycle` reports `idle | starting | running | stopped | failed |
+disposed`. The existing `status` field remains available for display state:
 
 - `connecting` covers the room-open promise.
 - `syncing` covers session-descriptor/asset preparation, reconnect, and catch-up.
@@ -314,7 +323,13 @@ render(runner.getRenderState(), runner.renderAlpha)
 - `error` carries connection, preparation, and offline-construction failures on
   the runner snapshot (and the throw is rethrown to the caller).
 - `stop` aborts preparation, closes the transport, and disposes the active
-  client/session — idempotently.
+  client/session. `stop` and `dispose` are idempotent. `dispose` is terminal.
+
+The runtime factory can return a runtime or a promise. A direct runtime is
+borrowed. The runner does not dispose it. Return `{ runtime, dispose }` to give
+the runner an owned lease. Cleanup releases session checkpoints before the
+lease. Cancellation also cleans a late owned lease or transport. The old
+`startOffline` and `startNetworked` methods remain as compatibility methods.
 
 Presentation stays **predicted** for render motion, while side-effect events are
 delivered only from authority-confirmed frames received after the first live
@@ -432,3 +447,31 @@ over a deterministic simulated network (`createSimulatedSyncplayMatch`,
 and `assertPresentationParity` cover the runner seam — a real runner driven on
 a fully controlled clock against the simulated match. Failures name the phase,
 frame, and disagreeing checksums.
+
+## Physics API v1
+
+Syncplay RC1 has one public TypeScript API for each physics dimension. Import
+2D physics from `@series-inc/rundot-syncplay/physics/2d`. Import 3D physics from
+`@series-inc/rundot-syncplay/physics/3d`. Do not import a raw physics adapter
+from `/core`.
+
+Call `initPhysics2D()` or `initPhysics3D()` before world creation. Create an
+owned world with `createPhysicsWorld2D()` or `createPhysicsWorld3D()`. Each
+world provides fixed stepping, atomic edits, retained queries, opaque native
+checkpoints, portable checkpoint bytes, a state digest, and explicit disposal.
+
+The TypeScript facade does not contain a second solver. Both dimensions run in
+the canonical C++ core compiled to WASM. The internal solver algorithm, state
+layout, WASM boundary, schedule, and checkpoint representation can change when
+a complete benchmark proves a faster design. Each replacement must keep the
+public contract, deterministic results, rollback controls, and bounded memory.
+
+RC1 starts a new physics numeric epoch. Do not load a beta physics checkpoint
+or replay into an RC1 world. Change the game deterministic version. Start new
+rollback, replay, and late-join history.
+
+Read the [2D guide](https://github.com/series-ai/venus/blob/develop/packages/sdk-docs/rundot-developer-platform/api/SYNCPLAY-PHYSICS-2D.md),
+the [3D guide](https://github.com/series-ai/venus/blob/develop/packages/sdk-docs/rundot-developer-platform/api/SYNCPLAY-PHYSICS.md), and
+the [RC1 migration helper](https://github.com/series-ai/venus/blob/develop/packages/sdk-docs/rundot-developer-platform/api/SYNCPLAY-RC1-MIGRATION.md).
+Physical-phone performance remains a release gate. Do not infer phone results
+from desktop measurements.

package/core/baker.d.ts

@@ -0,0 +1,14 @@
+// Generated. Declares the runtime exports of ./core/baker.
+
+export declare function assertKinetixProductContract(products: any): any;
+export declare function assertKinetixRuntimeIdentityMatchesProducts(products: any, identity: any): any;
+export declare function bakeKinetixEnvelope(envelope: any, installedProfiles: any): any;
+export declare function deriveCustomRuntimeIdentity(options: any): any;
+export declare function deriveKinetixRuntimeIdentity(products: any, runtimeContract?: any): any;
+export declare const kinetixBakerVersion: "rundot.kinetix-baker.v1";
+export declare const kinetixPhases: readonly ["initialization", "fixed-simulation", "post-simulation", "presentation-projection", "presentation"];
+export declare function kinetixRuntimeModuleManifest(sourceRoot: any, relativePaths: any): any;
+export declare function scanKinetixPayloadTree(value: any): any;
+export declare function stableKinetixProductBytes(products: any): any;
+export declare function stableKinetixSourceBytes(envelope: any): any;
+export declare function validateInstalledKinetixProfile(profileId: any, profile: any): any;

package/core/build-native.d.ts

@@ -0,0 +1,3 @@
+// Generated. Declares the runtime exports of ./core/build-native.
+
+export declare function buildNative(): any;

package/core/build-wasm-physics.d.ts

@@ -0,0 +1,6 @@
+// Generated. Declares the runtime exports of ./core/build-wasm-physics.
+
+export declare function buildWasmPhysics(options?: any): any;
+export declare function buildWasmPhysics2D(options?: any): any;
+export declare function getWasmNumericProfile(arg0?: any): any;
+export declare function getWasmPhysicsSourceHashes(): any;

package/core/compiler.d.ts

@@ -0,0 +1,4 @@
+// Generated. Declares the runtime exports of ./core/compiler.
+
+export declare function compileKinetixProject(arg0?: any): any;
+export declare function compileTrustedKinetixSource(arg0: any): any;

package/core/deterministic-math.d.ts

@@ -0,0 +1,2 @@
+export declare const DETERMINISTIC_MATH_SOURCE: string;
+export declare function installDeterministicMath(): void;

package/core/envelope.d.ts

@@ -0,0 +1,8 @@
+// Generated. Declares the runtime exports of ./core/envelope.
+
+export declare const kinetixDomains: readonly ["simulation", "presentation", "binding"];
+export declare function kinetixEnvelopeDigest(envelope: any): any;
+export declare const kinetixEnvelopeVersion: "rundot.kinetix-envelope.v1";
+export declare const kinetixReferenceKinds: readonly ["entity", "component", "prefab", "prefab-local-entity", "prefab-local-component", "asset", "scene"];
+export declare function stableKinetixEnvelopeBytes(envelope: any): any;
+export declare function validateKinetixEnvelope(envelope: any): any;

package/core/f64-bits.d.ts

@@ -0,0 +1,4 @@
+// Generated. Declares the runtime exports of ./core/f64-bits.
+
+export declare function f64FromHex(hex: any): any;
+export declare function hexFromF64(value: any): any;

package/core/index.d.ts

@@ -31,58 +31,6 @@ export {
   createDeterministicMath,
   DeterministicRandom,
 } from './deterministic-stdlib';
-export {
-  applyDeterministicImpulse3D,
-  applyDeterministicImpulses3D,
-  applyDeterministicWorldEdit3D,
-  applyPhysicsImpulse,
-  applyPhysicsImpulses,
-  applyPhysicsWorldEdit,
-  createPhysicsWorld,
-  createDeterministicPhysicsWorld3D,
-  createTrustedDeterministicPhysicsWorld3D,
-  cookPhysicsCollider,
-  contactDetailsDeterministicPhysics3D,
-  contactDetailsPhysics,
-  initPhysics,
-  initPhysics3D,
-  overlapDeterministicPhysics3D,
-  overlapPhysics,
-  physicsReady,
-  physics3DReady,
-  physicsWasmMetadata,
-  raycastDeterministicPhysics3D,
-  raycastDeterministicPhysics3DDetailed,
-  raycastPhysics,
-  raycastPhysicsDetailed,
-  resetPhysics3DCache,
-  setDeterministicBodyVelocity3D,
-  setPhysicsBodyVelocity,
-  shapeCastDeterministicPhysics3D,
-  shapeCastPhysics,
-  stepPhysicsWorld,
-  stepDeterministicPhysicsWorld3D,
-} from './physics';
-export type {
-  KinetixPhysicsActivePair,
-  KinetixPhysicsBody,
-  KinetixPhysicsContactCacheEntry,
-  KinetixPhysicsContactDetail,
-  KinetixPhysicsContactEvent,
-  KinetixPhysicsHit,
-  KinetixPhysicsJointCacheEntry,
-  KinetixPhysicsOverlapQuery,
-  KinetixPhysicsQuaternion,
-  KinetixPhysicsQueryOptions,
-  KinetixPhysicsRaycastQuery,
-  KinetixPhysicsScheduledQuery,
-  KinetixPhysicsShape,
-  KinetixPhysicsShapeCastQuery,
-  KinetixPhysicsStepOptions,
-  KinetixPhysicsStepResult,
-  KinetixPhysicsVec3,
-  KinetixPhysicsWorld,
-} from './physics';
 export type {
   DeterministicMathApi,
   DeterministicQuaternion,
@@ -277,6 +225,7 @@ export function deriveCustomRuntimeIdentity(
 ): import('./runtime').KinetixRuntimeIdentity;
 export const kinetixBakerVersion: string;
 export const kinetixPhases: readonly string[];
+export const kinetixProductKinds: readonly ['simulation', 'presentation', 'binding'];
 
 export function createKinetixWorld(options: {
   worldId: string;

package/core/native/kinetix-native-main.cpp

@@ -273,17 +273,14 @@ int runPhysicsSession() {
                 << " status=" << status << '\n';
       return 2;
     }
-    const std::uint32_t telemetryCount = rundot::kinetix::physics::contactTelemetryCount();
-    const double* telemetry = rundot::kinetix::physics::contactTelemetryData();
-    contactCache.resize(static_cast<std::size_t>(telemetryCount) * rundot::kinetix::physics::kContactCacheStride);
-    for (std::uint32_t index = 0; index < telemetryCount; index += 1) {
-      const double* source = telemetry + static_cast<std::size_t>(index)
-        * rundot::kinetix::physics::kContactTelemetryStride;
-      double* target = contactCache.data() + static_cast<std::size_t>(index)
-        * rundot::kinetix::physics::kContactCacheStride;
-      for (std::uint32_t field = 0; field < rundot::kinetix::physics::kContactCacheStride; field += 1) {
-        target[field] = source[field];
-      }
+    const std::uint32_t contactCount = rundot::kinetix::physics::contactCacheCount();
+    const double* cacheData = rundot::kinetix::physics::contactCacheData();
+    if (contactCount == 0) {
+      contactCache.clear();
+    } else {
+      contactCache.assign(cacheData, cacheData
+        + static_cast<std::size_t>(contactCount)
+          * rundot::kinetix::physics::kContactCacheStride);
     }
     for (std::uint32_t bodyIndex = 0; bodyIndex < bodyCount; bodyIndex += 1) {
       const std::size_t offset = static_cast<std::size_t>(bodyIndex) * stride;