@series-inc/rundot-syncplay 6.0.0-rc.4 → 6.0.0-rc.41

package/MIGRATING-RC20-TO-RC22.md

@@ -0,0 +1,133 @@
+# Migrating from Syncplay 6.0.0-rc.20 to rc.22
+
+Syncplay `6.0.0-rc.22` introduces ergonomics improvements for branded units, public state codecs for game-owned state containing `bigint` physics identifiers, generalized multi-wheel vehicle verification, and explicit guidance for Kinematic Character Controller (KCC) Revision 2.
+
+---
+
+## 1. Branded Vector Helpers & Migration Codemod (Item 10)
+
+### What Changed
+In rc.20, unit branding (`Meters`, `Radians`, `Newtons`, etc.) was tightened across all physics APIs to prevent unit mismatch bugs. However, writing `{ x: meters(a), y: meters(b), z: meters(c) }` across hundreds of lines introduces substantial boilerplate.
+
+rc.22 exports convenient vector constructors that accept both positional coordinates and existing `{ x, y, z }` record objects:
+
+```ts
+import {
+  meters3,
+  radians3,
+  metersPerSecond3,
+  metersPerSecondSquared3,
+  newtons3,
+  vec3,
+  meters2,
+  radians2,
+  metersPerSecond2,
+  vec2,
+} from '@series-inc/rundot-syncplay/physics/3d';
+```
+
+### Usage
+
+```ts
+// Positional coordinates
+const pos = meters3(0, 1.5, -2);
+const vel = metersPerSecond3(0, 0, 15);
+const force = newtons3(0, 500, 0);
+
+// Object coordinates (drop-in wrapper for legacy vector objects)
+const legacyVec = { x: 10, y: 0, z: -5 };
+const brandedPos = meters3(legacyVec);
+
+// Custom brands
+const custom = vec3(turns, 0.1, 0.2, 0.3);
+```
+
+### Regex / Search & Replace Codemod
+
+If your codebase has repetitive manual `{ x: meters(...), y: meters(...), z: meters(...) }` calls, you can migrate them with the following regular expressions:
+
+- **Find:**
+  ```regexp
+  \{\s*x:\s*meters\(([^)]+)\),\s*y:\s*meters\(([^)]+)\),\s*z:\s*meters\(([^)]+)\)\s*\}
+  ```
+- **Replace:**
+  ```ts
+  meters3($1, $2, $3)
+  ```
+
+- **2D Vectors Find:**
+  ```regexp
+  \{\s*x:\s*meters\(([^)]+)\),\s*y:\s*meters\(([^)]+)\)\s*\}
+  ```
+- **Replace:**
+  ```ts
+  meters2($1, $2)
+  ```
+
+---
+
+## 2. KCC Revision 2: Native Step-Up & Platform Support Persistence (Item 11)
+
+### Native Step-Up (No Custom Raycast Hacks)
+In Revision 1, stepping up over vertical edges (curbs, stairs, debris) often required game-side raycasts to manually nudge the character upward before stepping.
+
+In **Revision 2 (`behaviorRevision: 2`)**, the solver natively sweeps the bottom spherical cap against vertical steps up to `stepHeight`.
+- Author `stepHeight: 0.3` (or your desired maximum step height in meters).
+- A 0.2 m vertical edge will be climbed smoothly and deterministically without clipping or snagging.
+- **Action Required:** Remove any custom game-side pre-step raycasts or edge-nudging hacks; they are redundant and can interfere with the native solver's ground alignment.
+
+### Crucial: Persist the `support` Field Across Ticks
+Revision 2 introduces physical moving-platform carry and continuous contact resolution via the `support` property on `DeterministicKccState3D` / step result.
+
+```ts
+// Ticking KCC Revision 2:
+const result = stepDeterministicKcc3D(input, {
+  ...currentState,
+  // CRITICAL: Pass back the support returned from the previous tick!
+  support: lastStepResult.support,
+}, world, options);
+```
+
+> [!IMPORTANT]
+> If your game drops `support` or creates a fresh state object each frame without copying `lastStepResult.support`, the character controller will not inherit platform velocity or maintain stable ground contact.
+
+---
+
+## 3. Game-Owned State Codecs for BigInt Body IDs (Item 8)
+
+### What Changed
+`DeterministicVehicleState3D` and `DeterministicKccSupport3D` (when `kind: 'physics'`) carry native 64-bit `PhysicsBodyId3D` values represented as JavaScript `bigint` primitives.
+
+Standard `JSON.stringify(state)` throws:
+```
+TypeError: Do not know how to serialize a BigInt
+```
+
+### Solution
+Syncplay rc.22 exports canonical serialization and deserialization helpers that encode `bigint` without loss:
+
+```ts
+import {
+  encodeDeterministicVehicleState3D,
+  decodeDeterministicVehicleState3D,
+  encodeDeterministicVehicleState3DBytes,
+  decodeDeterministicVehicleState3DBytes,
+  encodeDeterministicKccSupport3D,
+  decodeDeterministicKccSupport3D,
+  encodeDeterministicKccSupport3DBytes,
+  decodeDeterministicKccSupport3DBytes,
+} from '@series-inc/rundot-syncplay/physics/3d';
+
+// Save vehicle state to JSON string or binary Uint8Array
+const savedJson = encodeDeterministicVehicleState3D(vehicleState);
+const savedBytes = encodeDeterministicVehicleState3DBytes(vehicleState);
+
+// Restore vehicle state
+const restoredState = decodeDeterministicVehicleState3D(savedJson);
+
+// Save KCC support state
+const savedSupportJson = encodeDeterministicKccSupport3D(kccResult.support);
+const restoredSupport = decodeDeterministicKccSupport3D(savedSupportJson);
+```
+
+These functions use canonical JSON formatting with BigInt sentinels (`{"$rdm":"bigint","value":"..."}`) ensuring bit-identical hashing and portable network snapshots across clients.

package/MIGRATING-RC28-TO-RC29.md

@@ -0,0 +1,51 @@
+# Migrating from Syncplay 6.0.0-rc.28 to rc.29
+
+Syncplay `6.0.0-rc.29` resolves partner feedback on portal physics, doorway aperture sliding, character controller pending body references, and output parity across checkpoint restores.
+
+---
+
+## 1. Reserved Collision Layers 24–30 (Portal Host Slots)
+
+### What Changed
+To provide zero-overhead wall aperture cutouts without altering the native C++ physics solver, Syncplay dynamically isolates portal host colliders by temporarily shifting host bodies to dedicated internal filtering layers.
+
+- **Bits 24 through 30 (`0x7f000000`)** in the 32-bit collision layer bitmask are now reserved for internal portal host filtering.
+- Up to **7 distinct host bodies** can be registered concurrently across active portal pairs in a physics world.
+- Host slots are dynamically allocated upon portal pair creation and automatically reclaimed when the portal pair is removed via `removePortalPair(handle)`.
+
+### Action Required
+If your game uses layers 24 through 30 for custom gameplay categories (such as projectiles, debris, or triggers), those categories will conflict with portal host suppression.
+- Move custom gameplay categories to unreserved layers (bits 0 through 23).
+- Update any layer bitmasks (`mask` and `layerMask` queries) that reference layers 24–30.
+
+---
+
+## 2. Aperture Containment Tolerance (0.05 m per Boundary)
+
+### What Changed
+In rc.28, resting contact solvers permitted normal micro-penetration (~2 mm under gravity). For bodies sliding into doorways where the portal aperture started at floor height ($y=0$), the body's lower bounds slightly breached the zero margin, causing the wall host collider to remain active and stopping the body at the frame.
+
+In rc.29, aperture containment calculations incorporate an explicit margin tolerance of **0.05 m (5 cm)** per projected boundary:
+
+$$|x| + e_x \le \frac{W}{2} + 0.05, \qquad |y| + e_y \le \frac{H}{2} + 0.05$$
+
+### Behavior
+- A centered body can be up to **0.10 m wider** than the opening ($0.05\text{ m}$ on each side) and still pass through without being blocked by the host wall.
+- Bodies that protrude more than 0.05 m past any single boundary remain blocked by the wall collider.
+- Floor-level doorways admit resting boxes and angled approaches smoothly without catching.
+
+---
+
+## 3. KCC Explicit Portals: Pending Body References
+
+### What Changed
+When creating a character controller and a portal pair inside the same `world.edit()` transaction, passing `hostBodyId` as the pending body reference object returned by `edit.createBody()` previously threw `SyntaxError: Cannot convert [object Object] to a BigInt`.
+
+In rc.29, character controller portal ingestion automatically resolves pending body references through `physics.resolveBody(ref).id`, accepting raw `BigInt`, number, string, live handle, or pending reference objects.
+
+---
+
+## 4. Checkpoint Output Parity
+
+### What Changed
+`world.checkpointLatest(checkpoint)` now satisfies the full `PhysicsLatestOutputs3D` contract, returning frozen empty arrays for `portalCrossings: []` and `motionBatch: { count: 0, bodies: [] }` on checkpoint reads, guaranteeing strict deep-equality against `world.latest()` on non-crossing frames.

package/MIGRATING-RC31-TO-RC32.md

@@ -0,0 +1,67 @@
+# Migrating from Syncplay 6.0.0-rc.31 to rc.32
+
+`6.0.0-rc.32` was tagged but not published. `6.0.0-rc.33` is the first published release with these changes, and it adds joint island isolation (C1). Use this guide to move from rc.31 to rc.33.
+
+Syncplay `6.0.0-rc.32` implements the complete Wreck Yard feature request roadmap (Sections A through E), delivering deterministic math parity, stable body keys, SI vector helpers, velocity retention aliases, KCC portal diagnostics, and partner test repro fixtures.
+
+---
+
+## 1. Deterministic `pow` and Static Checker (D1)
+
+### What Changed
+- `pow(base, exp)` is now provided as a canonical deterministic float function across `@series-inc/rundot-syncplay`, `/core/deterministic-math`, and `DeterministicMath.pow`.
+- IEEE 754 edge cases, negative bases with integral exponents, special powers ($\pm 0, \pm\infty, \pm 1$), and fractional powers are strictly preserved with bit-identical cross-platform determinism via the minimax/fdlibm standard.
+- The static checker (`checkDeterminism`) now rejects the JavaScript exponentiation operators `**` and `**=` as well as direct calls to ambient `Math.pow`, emitting code `SYNCPLAY_MATH_NON_DETERMINISTIC_OPERATOR` and recommending `pow(base, exp)` from `@series-inc/rundot-syncplay`.
+
+### Action Required
+Replace any usage of `Math.pow(x, y)` or `x ** y` in simulation code with `pow(x, y)`:
+```ts
+import { pow } from '@series-inc/rundot-syncplay';
+const result = pow(base, exponent);
+```
+
+---
+
+## 2. Stable Body Keys with O(1) Lookup (D2)
+
+### What Changed
+- Physics body inputs now accept an optional `key?: string` in `createBody({ ..., key: 'chassis-root' })`.
+- Keys must be non-empty, trimmed strings not exceeding 128 characters, and must be unique within the physics world.
+- Worlds provide `world.resolveKey(key: string): PhysicsBodyHandle3D`, performing an $O(1)$ lookup to retrieve the current handle. If the key is not found, `world.resolveKey` throws `SyncplayError` with code `physics.handle-missing`.
+- Query hits (`RaycastHit3D`, `ShapeCastHit3D`) and contact manifolds now annotate the resolved `bodyKey?: string` whenever a colliding body possesses a key.
+- Key-to-body bindings are fully serialized in checkpoint trailers and restored bit-identically across rollback and resimulation.
+
+---
+
+## 3. SI Vector and Coordinate Helpers (D3)
+
+### What Changed
+The root package entrypoint `@series-inc/rundot-syncplay` now provides enhanced `vec3` and `meters3` helpers:
+- `vec3(x, y, z)` or `vec3([x, y, z])` or `vec3({ x, y, z }, scale?)`
+- `meters3(x, y, z)` or `meters3([x, y, z])` or `meters3({ x, y, z }, scale?)`
+These functions construct validated `PhysicsVector3D<Meters>` objects from three coordinate arguments, tuple arrays, or existing vector records with an optional uniform scaling factor.
+
+---
+
+## 4. Linear Velocity Retention Alias (D4)
+
+### What Changed
+- Physics body inputs accept `linearVelocityRetention?: number` as an explicit semantic alternative to `linearDamping`.
+- Worlds provide `world.setBodyLinearVelocityRetention(body, retention)` to update velocity retention at runtime.
+- Specifying both `linearDamping` and `linearVelocityRetention` simultaneously throws `SyncplayError` with code `physics.definition-invalid`.
+
+---
+
+## 5. KCC Portal Diagnostics (D5)
+
+### What Changed
+- Character controller traversal through portals now validates character dimensions against the aperture opening.
+- If a capsule's radius or height exceeds the portal aperture, the KCC step blocks entry, zeros forward velocity toward the aperture plane, and emits a `'portal-blocked'` event with diagnostic reason `'capsule_larger_than_opening'`.
+
+---
+
+## 6. Partner Repro Suite & Provenance Tracking (E1, E2)
+
+### What Changed
+- 26 partner repro fixtures are cataloged under `packages/syncplay/tests/fixtures/wreck-yard/` with cryptographic SHA-256 provenance tracking in `manifest.json`.
+- Zero-tolerance CI tests enforce regression gates across all wall cases, latest-parity crossing frames, and rollback bit-identity.

package/MIGRATING-RC33-TO-RC34.md

@@ -0,0 +1,105 @@
+# Migrating from Syncplay 6.0.0-rc.33 to rc.34
+
+This release closes the rc.33 gaps that Wreck Yard reported and adds query,
+vehicle, and portal work from the full request list. Each section names what
+changes for a game and what does not.
+
+## Behavior changes
+
+### Portal host walls keep their own collision layers (A4)
+
+Before rc.34, a portal host wall took one of the reserved layers 24 to 30, and
+every body mask and every query layer mask silently included those layers. A
+world could have at most 7 host walls.
+
+From rc.34:
+
+- A host wall keeps the layer and mask you gave it. `readBody(host).layer`
+  reports that layer.
+- Body masks and query layer masks are exactly what you set. Layers 24 to 30
+  follow the normal rules. A body on layer 30 touches only bodies whose mask
+  includes layer 30.
+- A query layer mask now applies to host walls like any other body. To hit a
+  host wall with a filtered query, include the host's layer.
+- The number of host walls is limited only by body capacity.
+- The step excludes contacts between a host wall and the bodies inside one of
+  its openings. Bodies outside an opening still touch the wall.
+
+What to check: if a game relied on bodies on layers 24 to 30 touching
+everything, give the other bodies masks that include those layers.
+
+### Portal checkpoints from rc.28 to rc.33
+
+Serialized checkpoints that carry portal state now use portal trailer
+version 2. A version 1 trailer (rc.28 through rc.33) stored the reserved host
+layers and fails to restore with `physics.checkpoint-invalid`. Checkpoints with
+no portal state have no trailer and restore as before. Rollback and late join
+between peers on the same version are not affected.
+
+## Additions
+
+### Unit vectors from the physics entrypoint (D3)
+
+Import `vec3` and `meters3` from `@series-inc/rundot-syncplay/physics/3d`.
+The unit-typed form takes an optional scale:
+
+```ts
+import { meters, vec3 } from '@series-inc/rundot-syncplay/physics/3d';
+
+const offset = vec3(meters, [1, 2, 3], 0.5); // { x: 0.5, y: 1, z: 1.5 }
+```
+
+The root exports stay as deprecated aliases of the same functions.
+
+### Body keys (D2)
+
+- `PhysicsContactEvent3D` declares `bodyKeyA` and `bodyKeyB`.
+- `PhysicsFluidInteraction3D` carries `bodyKey`.
+- `world.resolveKeyId(key)` returns the live body id without reading the body.
+
+### Static checker (D1 follow-up)
+
+`Math.sqrt` is allowed: IEEE 754 rounds it correctly in every engine. `pow`,
+`hypot`, and `**` stay flagged.
+
+### Query index (B1)
+
+Raycast, overlap, and shape cast use a spatial index. A query tests only the
+bodies whose bounds overlap its own bounds, so its cost no longer grows with
+far bodies. Hits, order, points, and normals are bit-identical to the linear
+scan. `world.queryStats().testedBodies` reports the bodies the last query
+tested. `queryIndex: false` in a world definition selects the linear scan.
+
+### Ray batches and the wheel layer mask (B3)
+
+- `world.raycastBatch(queries)` runs 1 to 64 rays and returns each ray's hits.
+  The results equal separate `raycast` calls.
+- `DeterministicVehicleDefinition3D.wheelCastLayerMask` lets the wheel rays
+  skip layers. A mask of `0xffffffff` gives the same results as no mask.
+
+### Vehicle step cost (C2)
+
+The revision 2 vehicle step casts all wheels in one native call and reads its
+support bodies in one batch. The tire solve is unchanged, and results are
+bit-identical to separate reads.
+
+### Queries through portals (A3)
+
+`shapeCast` and `overlap` now pass through open portals, like `raycast`. Hits
+found through a portal carry `portalHops` and `portalPath`. A query that must
+ignore portals sets `maxPortalDepth: 0`. The character controller already
+handles portals itself and sets it.
+
+### Portal placement (A5)
+
+`fitPortalEnd(world, { hostBodyId, point, normal, up, opening })` returns a
+pose that fits fully on a static box host face, or null. Bodies take
+`portalable: false`, and edits take `setPortalable(body, portalable)`.
+
+### Portal render helpers (A6)
+
+Render-only helpers in `/physics/3d`: `portalTransformMatrix3D`,
+`portalVirtualCameraMatrix3D`, `portalExitClipPlane3D`,
+`portalPlaneInCameraSpace3D`, `portalObliqueProjection3D`, `planPortalViews3D`,
+`portalPoseJumpBodyIds3D`, `interpolatePortalBodyPose3D`, and
+`multiplyPortalMatrices`. They do not change the simulation.