@series-inc/rundot-syncplay 5.26.0-beta.3 → 5.26.0-beta.4

package/core/native/mobile/syncplay_native_probe.cpp

@@ -1,8 +1,10 @@
 #include "syncplay_native_probe_abi.h"
 
+#include "../fixed_math.hpp"
 #include "../physics/physics.hpp"
 #include "box3d_probe_scenario.hpp"
 
+#include <bit>
 #include <chrono>
 #include <cstdint>
 #include <mutex>
@@ -40,6 +42,35 @@ extern "C" std::int32_t rundot_syncplay_native_probe_run(
     output->status = RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_UNSUPPORTED_ABI;
     return output->status;
   }
+  if (input->scenario_id == RUNDOT_SYNCPLAY_NATIVE_PROBE_SCENARIO_FIXED_MATH_V1) {
+    if (input->frames == 0 || input->frames > 1000000) {
+      output->status = RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_INVALID_FRAMES;
+      return output->status;
+    }
+    namespace fx = rundot::fixedmath;
+    const fx::Config cfg = fx::defaultConfig();
+    bool ok = true;
+    fx::Vec3 p{0, 0, 0};
+    fx::Vec3 v{1000, 2000, -500};
+    double acc = 0;
+    const auto mathStart = std::chrono::steady_clock::now();
+    for (std::uint32_t i = 0; i < input->frames; i += 1) {
+      p = fx::vec3Add(cfg, p, fx::vec3Scale(cfg, v, 990, ok), ok);
+      acc += fx::vec3Length(cfg, p, ok);
+      v = fx::vec3Scale(cfg, v, 999, ok);
+      if (p.x > 2000000000.0) p = fx::Vec3{0, 0, 0};
+    }
+    output->elapsed_ns = static_cast<std::uint64_t>(
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::steady_clock::now() - mathStart).count());
+    output->completed_frames = input->frames;
+    // The digest IS the f64 bit pattern, so it compares directly against the
+    // JavaScript lane's DataView-derived value with no formatting in between.
+    output->final_checksum = std::bit_cast<std::uint64_t>(acc);
+    output->status = ok ? RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_OK
+                        : RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_STEP_FAILED;
+    return output->status;
+  }
   if (input->scenario_id != RUNDOT_SYNCPLAY_NATIVE_PROBE_SCENARIO_BOX3D_V1) {
     output->status = RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_UNSUPPORTED_SCENARIO;
     return output->status;

package/core/native/mobile/syncplay_native_probe_abi.h

@@ -4,6 +4,11 @@
 
 #define RUNDOT_SYNCPLAY_NATIVE_PROBE_ABI_VERSION 1u
 #define RUNDOT_SYNCPLAY_NATIVE_PROBE_SCENARIO_BOX3D_V1 1u
+// Runs the fixed-point math kernel and returns its f64-bit digest in
+// final_checksum. Exists so a device can compare its C++ result against the same
+// kernel run in the app's JavaScript engine: with interpreted glue allowed on
+// Android, that engine is on the consensus path and must agree bit-for-bit.
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_SCENARIO_FIXED_MATH_V1 2u
 
 #define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_OK 0
 #define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_INVALID_ARGUMENT (-1)

package/core/scripts/build-mobile-native.mjs

@@ -21,6 +21,8 @@ export const MOBILE_NATIVE_FILES = Object.freeze([
   'physics/abi.cpp',
   'deterministic_math.hpp',
   'deterministic_math.cpp',
+  'fixed_math.hpp',
+  'fixed_math.cpp',
 ]);
 
 const sourceExtensions = new Set(['.cpp', '.hpp', '.h']);

package/dist/browser.d.ts

@@ -61,7 +61,7 @@ export type { DeterministicAuthoritativeLagCompensation3DShotContext, Determinis
 export type { DeterministicLocalAuthoritySnapshotIdentity, DeterministicLocalAuthoritySnapshotTransfer, DeterministicLocalAuthorityWireEnvelope, DeterministicLocalAuthorityWireKind } from './local-authority-wire.js';
 export type { DeterministicFixedQuaternion, DeterministicFixedVec2, DeterministicFixedVec3, DeterministicMath } from './math.js';
 export type { DeterministicFpsAimState, DeterministicFpsInput, DeterministicKccBody, DeterministicKccInput, DeterministicKccStepResult, DeterministicLagCompensatedHitValidation, DeterministicLagCompensatedShot, DeterministicMovementCrowdMetrics, DeterministicMovementSimulationMetrics, DeterministicMovementStep, DeterministicMovementWorld, DeterministicMovingPlatform, DeterministicOneWayPlatform, DeterministicSlope, DeterministicTargetSnapshot, DeterministicTopDownBody, DeterministicTopDownBounds, DeterministicTopDownInput } from './movement.js';
-export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
+export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccJumpTuning3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
 export type { CookedDeterministicNavigationGraph, DeterministicFlowField, DeterministicNavEdge, DeterministicNavigationAgent, DeterministicNavigationGraphSource, DeterministicNavigationStepOptions, DeterministicNavigationStepResult, DeterministicNavNode, DeterministicNavRegion, DeterministicPathQuery, DeterministicPathResult, DeterministicTilemapSource } from './navigation.js';
 export type { CookedDeterministicNavmesh, DeterministicNavmeshAgent, DeterministicNavmeshAgentStepResult, DeterministicNavmeshImportSource, DeterministicNavmeshLink, DeterministicNavmeshMovingAvoidanceObstacle, DeterministicNavmeshOffMeshTraversalState, DeterministicNavmeshOffMeshTraversalStep, DeterministicNavmeshPath, DeterministicNavmeshPoint, DeterministicNavmeshPolygon, DeterministicNavmeshSource } from './navmesh.js';
 export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, NetworkedSyncplaySlotPresence, PreparedNetworkedSyncplayTransport, SyncplayPredictionMode } from './networked-client.js';

package/dist/index.d.ts

@@ -73,7 +73,7 @@ export type { DeterministicAuthoritativeLagCompensation3DShotContext, Determinis
 export type { DeterministicLocalAuthoritySnapshotIdentity, DeterministicLocalAuthoritySnapshotTransfer, DeterministicLocalAuthorityWireEnvelope, DeterministicLocalAuthorityWireKind } from './local-authority-wire.js';
 export type { DeterministicFixedQuaternion, DeterministicFixedVec2, DeterministicFixedVec3, DeterministicMath } from './math.js';
 export type { DeterministicFpsAimState, DeterministicFpsInput, DeterministicKccBody, DeterministicKccInput, DeterministicKccStepResult, DeterministicMovementCrowdMetrics, DeterministicMovementSimulationMetrics, DeterministicMovementStep, DeterministicMovementWorld, DeterministicMovingPlatform, DeterministicOneWayPlatform, DeterministicSlope, DeterministicTargetSnapshot, DeterministicTopDownBody, DeterministicTopDownBounds, DeterministicTopDownInput } from './movement.js';
-export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
+export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccJumpTuning3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
 export type { CookedDeterministicNavigationGraph, DeterministicFlowField, DeterministicNavEdge, DeterministicNavigationAgent, DeterministicNavigationGraphSource, DeterministicNavigationStepOptions, DeterministicNavigationStepResult, DeterministicNavNode, DeterministicNavRegion, DeterministicPathQuery, DeterministicPathResult, DeterministicTilemapSource } from './navigation.js';
 export type { CookedDeterministicNavmesh, DeterministicNavmeshAgent, DeterministicNavmeshAgentStepResult, DeterministicNavmeshImportSource, DeterministicNavmeshLink, DeterministicNavmeshMovingAvoidanceObstacle, DeterministicNavmeshOffMeshTraversalState, DeterministicNavmeshOffMeshTraversalStep, DeterministicNavmeshPath, DeterministicNavmeshPoint, DeterministicNavmeshPolygon, DeterministicNavmeshSource } from './navmesh.js';
 export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, PreparedNetworkedSyncplayTransport, SyncplayPredictionMode } from './networked-client.js';

package/dist/movement3d.d.ts

@@ -24,6 +24,20 @@ export interface DeterministicKccInput3D {
     readonly moveZ: number;
     readonly jumpPressed?: boolean;
 }
+export interface DeterministicKccJumpTuning3D {
+    /** Upward velocity the jump sets, in units per frame. Default 10. */
+    readonly impulse?: number;
+    /**
+     * Immediate lift applied on the jump frame to unstick the capsule from the
+     * ground it is resting on. Defaults to `impulse / 10`, which keeps the
+     * historical 1-unit lift at the default impulse and scales with a retune.
+     */
+    readonly liftOff?: number;
+    /** Frames a jump stays available after leaving the ground. Default 4. */
+    readonly coyoteFrames?: number;
+    /** Frames an early jump press is held for. Minimum 1, default 4. */
+    readonly bufferFrames?: number;
+}
 export interface DeterministicKccExternalImpulse3D {
     readonly id: string;
     readonly vx: number;
@@ -198,6 +212,14 @@ export declare function stepDeterministicKcc3D(body: DeterministicKccBody3D, inp
      * bit-identical checksums.
      */
     readonly groundOnStaticBodies?: boolean;
+    /**
+     * Jump tuning, in the KCC's frame units. Gravity retunes through a processor
+     * because processors run before `vy -= 1`, but the jump impulse is applied
+     * AFTER them, so it cannot be scaled the same way — without these a game that
+     * retunes gravity must own jump, coyote and buffer itself. Every default
+     * reproduces the previous hardcoded behaviour bit-for-bit.
+     */
+    readonly jump?: DeterministicKccJumpTuning3D;
 }): DeterministicKccStepResult3D;
 export interface DeterministicKccCarryState3D {
     readonly bodyId: string;

package/dist/movement3d.js

@@ -1,8 +1,39 @@
 import { defaultChecksum } from './canonical.js';
 import { createDeterministicPhysicsWorld3D, overlapDeterministicPhysics3D, } from './physics3d.js';
 import { heightfieldLocalSurfaceY } from './physics3d-heightfield.js';
-import { mulMat3Vec, quaternionFromQuarterTurns, quatMultiply, quatToMat3, rotatePointByQuat } from './physics3d-shared.js';
+import { mulMat3Vec, quaternionFromQuarterTurns, quatMultiply, quatToMat3, rotatePointByQuat, solverSqrt } from './physics3d-shared.js';
+function normalizeKccJumpTuning3D(tuning) {
+    const impulse = finiteKccJumpNumber(tuning?.impulse, 10, 'impulse');
+    return {
+        impulse,
+        liftOff: finiteKccJumpNumber(tuning?.liftOff, impulse / 10, 'liftOff'),
+        coyoteFrames: kccJumpFrameCount(tuning?.coyoteFrames, 'coyoteFrames', 0),
+        // A press arms the jump by writing this into jumpBufferFrames and the gate
+        // needs it > 0, so 0 would not mean "no buffering" — it would mean "never
+        // jump". 1 is the real floor: the press lives for the frame it happened on.
+        bufferFrames: kccJumpFrameCount(tuning?.bufferFrames, 'bufferFrames', 1),
+    };
+}
+function finiteKccJumpNumber(value, fallback, field) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isFinite(value)) {
+        throw new Error(`KCC jump.${field} must be a finite number`);
+    }
+    return value;
+}
+function kccJumpFrameCount(value, field, minimum) {
+    if (value === undefined) {
+        return 4;
+    }
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`KCC jump.${field} must be an integer >= ${minimum}, got ${value}`);
+    }
+    return value;
+}
 export function stepDeterministicKcc3D(body, input, world, options) {
+    const jump = normalizeKccJumpTuning3D(options.jump);
     let next = applyProcessors(body, input, options.frame, options.processors ?? []);
     const events = [];
     let correctionCount = 0;
@@ -10,8 +41,8 @@ export function stepDeterministicKcc3D(body, input, world, options) {
     let collisionFilterCalls = 0;
     let collisionFilterRejectedHits = 0;
     const externalImpulse = combineExternalKccImpulses(options.externalImpulses ?? []);
-    let coyoteFrames = next.grounded ? 4 : Math.max(0, next.coyoteFrames - 1);
-    let jumpBufferFrames = input.jumpPressed === true ? 4 : Math.max(0, next.jumpBufferFrames - 1);
+    let coyoteFrames = next.grounded ? jump.coyoteFrames : Math.max(0, next.coyoteFrames - 1);
+    let jumpBufferFrames = input.jumpPressed === true ? jump.bufferFrames : Math.max(0, next.jumpBufferFrames - 1);
     let vx = input.moveX + externalImpulse.vx;
     let vz = input.moveZ + externalImpulse.vz;
     let vy = next.vy - 1 + externalImpulse.vy;
@@ -70,8 +101,8 @@ export function stepDeterministicKcc3D(body, input, world, options) {
         }
     }
     if (jumpBufferFrames > 0 && (next.grounded || next.coyoteFrames > 0 || grounded)) {
-        vy = 10;
-        y += 1;
+        vy = jump.impulse;
+        y += jump.liftOff;
         grounded = false;
         platformId = undefined;
         jumpBufferFrames = 0;
@@ -198,7 +229,7 @@ export function stepDeterministicKcc3D(body, input, world, options) {
     next = boundsCorrection.body;
     const finalBody = {
         ...next,
-        coyoteFrames: next.grounded ? 4 : coyoteFrames,
+        coyoteFrames: next.grounded ? jump.coyoteFrames : coyoteFrames,
         jumpBufferFrames,
     };
     return {
@@ -361,6 +392,42 @@ function groundContactTopAt(body, x, z) {
  * skinWidth defaults to 0; a plain double is bit-identical on every peer.
  */
 const KCC_GROUND_CLEARANCE = 1e-4;
+/**
+ * Extra vertical lift a round capsule bottom needs to rest ON a sloped surface
+ * instead of IN it.
+ *
+ * groundContactTopAt reports the height under the capsule CENTRE, but the
+ * bottom is a sphere, so on gradient `g` the contact sits uphill and a bare
+ * radius of lift buries the uphill flank by `radius * (sec θ - 1)`. Past ~1.7°
+ * that exceeds KCC_GROUND_CLEARANCE, every overlap probe (full, x-only AND
+ * z-only) hits, and resolvePhysicsSlide3D reverts the whole horizontal move.
+ *
+ * Sampled a bottom-sphere radius out: that is the footprint the sphere can
+ * touch, it reads a plane exactly at any angle, and it self-bounds the
+ * discontinuities groundContactTopAt has on some shapes (a compound's children
+ * can butt together at a height jump) — a jump of D reads as D/radius here
+ * instead of the skyward fling an epsilon probe would give. Per axis it takes
+ * the steeper of forward/backward so a sample straddling an edge cannot
+ * average its way to an under-lift and back into the freeze.
+ */
+function kccSlopeClearance(body, x, z, top, geometry) {
+    const step = geometry.radius + geometry.skinWidth;
+    const axisGradient = (deltaX, deltaZ) => {
+        const ahead = groundContactTopAt(body, x + deltaX, z + deltaZ);
+        const behind = groundContactTopAt(body, x - deltaX, z - deltaZ);
+        const forward = ahead === undefined ? 0 : Math.abs(ahead - top) / step;
+        const backward = behind === undefined ? 0 : Math.abs(top - behind) / step;
+        return Math.max(forward, backward);
+    };
+    const gradientX = axisGradient(step, 0);
+    const gradientZ = axisGradient(0, step);
+    const gradientSq = gradientX * gradientX + gradientZ * gradientZ;
+    if (gradientSq <= 0) {
+        return 0;
+    }
+    // radius + skinWidth is the bottom-sphere radius physicsOverlapsKcc probes with.
+    return (geometry.radius + geometry.skinWidth) * (solverSqrt(1 + gradientSq) - 1);
+}
 /**
  * Distance from the capsule's centre to the bottom of its collision shape.
  * A capsule's vertical extent is halfHeight + radius (see primitiveHalfExtent),
@@ -397,8 +464,15 @@ function staticGroundUnderKcc(physics, x, y, z, previousFeetY, geometry, ignored
     const grounds = physics.bodies
         .filter((body) => body.kind === 'static' && hitIds.has(body.id) && !ignoredBodyIds.has(body.id))
         .map((body) => ({ body, top: groundContactTopAt(body, x, z) }))
-        .filter((candidate) => candidate.top !== undefined
-        && feetY <= candidate.top + snapDistance
+        .filter((candidate) => candidate.top !== undefined)
+        .map((candidate) => ({
+        ...candidate,
+        lift: kccSlopeClearance(candidate.body, x, z, candidate.top, geometry),
+    }))
+        // The band is measured from where the capsule actually STANDS, so a slope
+        // lift bigger than snapDistance cannot drop it out of its own ground the
+        // next frame and leave it cycling between grounded and falling.
+        .filter((candidate) => feetY <= candidate.top + candidate.lift + snapDistance
         && previousFeetY >= candidate.top - snapDistance)
         .sort((left, right) => right.top - left.top || compareStrings(left.body.id, right.body.id));
     const ground = grounds[0];
@@ -407,7 +481,7 @@ function staticGroundUnderKcc(physics, x, y, z, previousFeetY, geometry, ignored
     }
     return {
         bodyId: ground.body.id,
-        topY: ground.top + kccFeetOffset(geometry),
+        topY: ground.top + kccFeetOffset(geometry) + ground.lift,
     };
 }
 /** World half-extents (x,y,z) of a primitive shape under rotation matrix `m`. */

package/package.json

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