@series-inc/rundot-syncplay 5.23.0-beta.7 → 5.23.0

package/dist/physics3d.d.ts

@@ -1,5 +1,7 @@
 import { type DeterministicPhysicsMaterial } from './deterministic-primitives.js';
-export type DeterministicPhysicsShape3D = {
+import { type Point3D } from './physics3d-shared.js';
+import { type DeterministicPhysicsJoint3D } from './physics3d-joints.js';
+export type DeterministicPhysicsPrimitiveShape3D = {
     readonly type: 'box';
     readonly halfX: number;
     readonly halfY: number;
@@ -11,13 +13,30 @@ export type DeterministicPhysicsShape3D = {
     readonly type: 'capsule';
     readonly radius: number;
     readonly halfHeight: number;
-} | {
+};
+export interface DeterministicPhysicsCompoundChild3D {
+    readonly shape: DeterministicPhysicsPrimitiveShape3D;
+    readonly offset: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly quarterTurns?: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+}
+export type DeterministicPhysicsShape3D = DeterministicPhysicsPrimitiveShape3D | {
     readonly type: 'mesh';
     readonly vertices: readonly {
         readonly x: number;
         readonly y: number;
         readonly z: number;
     }[];
+} | {
+    readonly type: 'compound';
+    readonly children: readonly DeterministicPhysicsCompoundChild3D[];
 };
 export declare const deterministicPhysicsCallback3D: {
     readonly collisionEnter: 1;
@@ -28,6 +47,23 @@ export declare const deterministicPhysicsCallback3D: {
     readonly triggerExit: 32;
 };
 export type DeterministicPhysicsCallbackMask3D = number;
+export interface DeterministicPhysicsVec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export interface DeterministicPhysicsQuaternion3D {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly w: number;
+}
+/** Optional per-axis flags used by `lockLinear` / `lockAngular`. */
+export interface DeterministicPhysicsAxisLock3D {
+    readonly x?: boolean;
+    readonly y?: boolean;
+    readonly z?: boolean;
+}
 export interface DeterministicPhysicsBody3D {
     readonly id: string;
     readonly kind: 'static' | 'dynamic' | 'kinematic';
@@ -44,6 +80,20 @@ export interface DeterministicPhysicsBody3D {
     readonly avy?: number;
     readonly avz?: number;
     readonly inertia?: number;
+    /** Full 6-DOF orientation (opt-in); bodies without it are rotation-locked through the rigid solver. */
+    readonly orientation?: DeterministicPhysicsQuaternion3D;
+    readonly angularVel?: DeterministicPhysicsVec3;
+    readonly mass?: number;
+    readonly linearDamping?: number;
+    readonly angularDamping?: number;
+    /** Multiplies world gravity for this body; default 1. */
+    readonly gravityScale?: number;
+    readonly lockLinear?: DeterministicPhysicsAxisLock3D;
+    readonly lockAngular?: DeterministicPhysicsAxisLock3D;
+    readonly ccd?: boolean;
+    /** Canonical sleep state maintained by the rigid solver. */
+    readonly sleeping?: boolean;
+    readonly lowVelFrames?: number;
     readonly shape: DeterministicPhysicsShape3D;
     readonly layer: number;
     readonly mask: number;
@@ -52,11 +102,36 @@ export interface DeterministicPhysicsBody3D {
     readonly callbackMask?: DeterministicPhysicsCallbackMask3D;
     readonly material?: DeterministicPhysicsMaterial;
 }
+/**
+ * Persistent warm-start contact impulse cache. Part of canonical world state so
+ * snapshot/restore/rollback reproduces solver trajectories bit-identically.
+ */
+export interface DeterministicContactCacheEntry3D {
+    readonly pair: string;
+    readonly anchorX: number;
+    readonly anchorY: number;
+    readonly anchorZ: number;
+    readonly normalImpulse: number;
+    readonly tangentImpulse1: number;
+    readonly tangentImpulse2: number;
+}
+export interface DeterministicJointCacheEntry3D {
+    readonly jointId: string;
+    readonly impulseX: number;
+    readonly impulseY: number;
+    readonly impulseZ: number;
+    readonly axialImpulse: number;
+    readonly hingeAngle: number;
+    /** Set once a breakable joint exceeded its breakImpulse; sticky across steps. */
+    readonly broken?: boolean;
+}
 export interface DeterministicPhysicsWorld3D {
     readonly frame: number;
     readonly bodies: readonly DeterministicPhysicsBody3D[];
     readonly activePairs: readonly string[];
     readonly activePairMetadata: readonly DeterministicPhysicsActivePair3D[];
+    readonly contactCache: readonly DeterministicContactCacheEntry3D[];
+    readonly jointCache: readonly DeterministicJointCacheEntry3D[];
 }
 export interface DeterministicPhysicsActivePair3D {
     readonly pair: string;
@@ -135,6 +210,8 @@ export interface DeterministicPhysicsContactEvent3D {
     readonly b: string;
     readonly trigger: boolean;
     readonly sensor: boolean;
+    /** Accumulated normal impulse (quantized) from the rigid solver; 0 for triggers/exits. */
+    readonly normalImpulse?: number;
 }
 export interface DeterministicPhysicsContactDetail3D {
     readonly pair: string;
@@ -145,6 +222,7 @@ export interface DeterministicPhysicsContactDetail3D {
     readonly point: Point3D;
     readonly normal: Point3D;
     readonly penetration: number;
+    readonly normalImpulse?: number;
 }
 export interface DeterministicPhysics3DCallbackMaskFixtureResult {
     readonly checksum: string;
@@ -211,6 +289,8 @@ export interface DeterministicPhysics3DStackFixtureResult {
 export interface DeterministicPhysicsStepResult3D {
     readonly world: DeterministicPhysicsWorld3D;
     readonly contacts: readonly DeterministicPhysicsContactEvent3D[];
+    /** Joint ids that broke this step (newly, sorted); sticky once broken. */
+    readonly brokenJointIds: readonly string[];
     readonly scheduledQueryResults: readonly {
         readonly id: string;
         readonly hits: readonly DeterministicPhysicsHit3D[];
@@ -229,13 +309,38 @@ export interface DeterministicPhysicsStepResult3D {
     readonly checksum: string;
 }
 export declare function createDeterministicPhysicsWorld3D(bodies: readonly DeterministicPhysicsBody3D[]): DeterministicPhysicsWorld3D;
+export interface DeterministicPhysicsImpulseApplication3D {
+    readonly bodyId: string;
+    readonly impulse: Point3D;
+    readonly worldPoint?: Point3D;
+}
+/**
+ * Apply a batch of deterministic impulses in one canonical-world rebuild.
+ * Semantically the impulses accumulate in list order (same math as repeated
+ * `applyDeterministicImpulse3D`, but velocities are quantized once per body at
+ * the end rather than per impulse), and every touched body's contact island is
+ * woken. One `O(bodies)` rebuild instead of one per impulse — this is the
+ * fast path for per-frame controller output (vehicles, KCC pushes).
+ */
+export declare function applyDeterministicImpulses3D(world: DeterministicPhysicsWorld3D, impulses: readonly DeterministicPhysicsImpulseApplication3D[]): DeterministicPhysicsWorld3D;
+/**
+ * Apply a deterministic impulse to a body (linear + angular via lever arm),
+ * waking the body and its contact island. Returns a new canonical world.
+ */
+export declare function applyDeterministicImpulse3D(world: DeterministicPhysicsWorld3D, bodyId: string, impulse: Point3D, worldPoint?: Point3D): DeterministicPhysicsWorld3D;
+/** Set a body's linear (and optional angular) velocity deterministically, waking its island. */
+export declare function setDeterministicBodyVelocity3D(world: DeterministicPhysicsWorld3D, bodyId: string, velocity: Point3D, angularVelocity?: Point3D): DeterministicPhysicsWorld3D;
 export declare function stepDeterministicPhysicsWorld3D(world: DeterministicPhysicsWorld3D, options?: {
     readonly gravityY?: number;
     readonly scheduledQueries?: readonly DeterministicPhysicsScheduledQuery3D[];
     readonly constraints?: readonly DeterministicPhysicsConstraint3D[];
+    readonly joints?: readonly DeterministicPhysicsJoint3D[];
     readonly dtTicks?: number;
+    readonly velocityIterations?: number;
     readonly computeChecksum?: boolean;
 }): DeterministicPhysicsStepResult3D;
+/** O(1) body lookup backed by the per-world query-index cache. */
+export declare function deterministicPhysicsBodyById3D(world: DeterministicPhysicsWorld3D, bodyId: string): DeterministicPhysicsBody3D | undefined;
 export declare function raycastDeterministicPhysics3D(world: DeterministicPhysicsWorld3D, query: DeterministicPhysicsRaycastQuery3D): readonly DeterministicPhysicsHit3D[];
 export declare function raycastDeterministicPhysics3DDetailed(world: DeterministicPhysicsWorld3D, query: DeterministicPhysicsRaycastQuery3D): readonly DeterministicPhysicsDetailedHit3D[];
 export declare function overlapDeterministicPhysics3D(world: DeterministicPhysicsWorld3D, query: DeterministicPhysicsOverlapQuery3D): readonly string[];
@@ -277,9 +382,4 @@ export declare function runDeterministicPhysics3DStress(bodies: number, frames:
     readonly rollbackEquivalent: boolean;
 };
 export declare function runDeterministicPhysics3DStackFixture(stackLayers?: number, frames?: number): DeterministicPhysics3DStackFixtureResult;
-interface Point3D {
-    readonly x: number;
-    readonly y: number;
-    readonly z: number;
-}
-export {};
+export declare function deriveInverseInertia(shape: DeterministicPhysicsShape3D, mass: number): Point3D;