@forgeax/engine-physics 0.1.27 → 0.1.28

package/dist/physics-world.d.ts

@@ -1,4 +1,6 @@
 import type { Vec2, Vec3 } from '@forgeax/engine-math';
+import type { Result } from '@forgeax/engine-types';
+import type { DerivedPhysicsCandidate, DerivedPhysicsCandidateInput, DerivedPhysicsError, DerivedPhysicsFailure, DerivedPhysicsMotion, DerivedPhysicsPublication, DerivedPhysicsSnapshot, DerivedShapeState, PhysicsConstraintInput, PhysicsContactObservation } from './derived-physics';
 /**
  * Raycast hit result — returned by `PhysicsWorld.raycast()`.
  *
@@ -49,7 +51,7 @@ export interface PhysicsWorld {
      * (unlike `world.set(entity, Transform, { translation: ... })` on
      * dynamic bodies, which would cause a velocity spike).
      *
-     * @param entity - the entity (must have RigidBody + Collider).
+     * @param entity - the entity with a registered native body.
      * @param position - new world-space position.
      */
     teleport(entity: number, position: Vec3): void;
@@ -85,7 +87,7 @@ export interface PhysicsWorld {
      *
      * Returns `true` after `ensureBody` has created a Rapier body for the entity
      * (which happens asynchronously via WASM fire-and-forget load + tick pipeline).
-     * Always returns `false` for entities that have no `RigidBody` + `Collider`.
+     * A RigidBody-only 3D entity is a native body even before derived shapes arrive.
      *
      * AI-user contract: before calling `moveAndSlide` inside a per-frame driver,
      * guard with `if (!pw.hasBody(entity)) return;` to avoid `body-not-found`
@@ -93,6 +95,62 @@ export interface PhysicsWorld {
      * `physicsSyncBackend` tick that builds the body.
      */
     hasBody(entity: number): boolean;
+    /**
+     * Prepare a replacement set of local derived shapes without making it
+     * queryable. The Rapier 3D implementation backs these shapes with one
+     * native world and one ECS body; 2D backends may omit this optional seam.
+     */
+    prepareDerivedShapeCandidate?: (input: DerivedPhysicsCandidateInput) => Result<DerivedPhysicsCandidate, DerivedPhysicsError>;
+    /**
+     * Queue a prepared candidate. The optional synchronous geometry commit runs
+     * after fallible native preparation, before step/publication. It must either
+     * commit its complete ECS binding or return failure without changing it.
+     * Returned failure restores old physics; a thrown callback has uncertain ECS
+     * writes and requires rebuild. Reentrant physics access is refused.
+     */
+    admitDerivedShapeCandidate?: (candidate: DerivedPhysicsCandidate, commitGeometry?: () => Result<void, Error>) => Result<DerivedPhysicsCandidate, DerivedPhysicsError>;
+    /** Borrowed ordering proof, present only inside the paired geometry commit. */
+    getDerivedAdmission?: (entity?: number) => {
+        readonly entity: number;
+        readonly revision: number;
+        readonly fixedStep: number;
+    } | undefined;
+    /** Cancel a candidate that has not been published. */
+    cancelDerivedShapeCandidate?: (candidate: DerivedPhysicsCandidate) => Result<void, DerivedPhysicsError>;
+    /** Invalidate pending candidates without touching the last committed state. */
+    invalidateDerivedShapeCandidates?: (reason?: string) => void;
+    /** Read the most recent fixed-step publication for one body. */
+    getDerivedPublication?: (entity: number) => DerivedPhysicsPublication | undefined;
+    /** Read the structured failure from the latest rejected admission, if any. */
+    getDerivedFailure?: (entity: number) => DerivedPhysicsFailure | undefined;
+    /** Read the committed body type without exposing a native Rapier body. */
+    getDerivedBodyType?: (entity: number) => 'static' | 'dynamic' | 'kinematic' | undefined;
+    /** Read whether a native admission failure requires a full World rebuild. */
+    getDerivedRecoveryState?: () => 'ready' | 'rebuild-required';
+    /** Read detached mass evidence without exposing a native body handle. */
+    getDerivedBodyMass?: (entity: number) => number | undefined;
+    /** Read the committed world-space COM and velocities for one derived body. */
+    getDerivedMotion?: (entity: number) => DerivedPhysicsMotion | undefined;
+    /** Read the currently committed local shape identities for one body. */
+    getDerivedShapes?: (entity: number) => readonly DerivedShapeState[];
+    /** Read detached contact observations from the latest fixed-step drain. */
+    getContactObservations?: () => readonly PhysicsContactObservation[];
+    /** Complete the fixed-step publication after ECS writeback/contact sync. */
+    finalizeDerivedFixedStep?: () => void;
+    /** Capture portable, committed input for explicit rebuild/recovery. */
+    captureDerivedPhysicsState?: () => DerivedPhysicsSnapshot;
+    /** Restore a previously captured input through normal candidate admission. */
+    restoreDerivedPhysicsState?: (snapshot: DerivedPhysicsSnapshot) => Result<readonly DerivedPhysicsCandidate[], DerivedPhysicsError>;
+    /** Create/update/remove constraints in the same solver as ordinary bodies. */
+    createDerivedConstraint?: (input: PhysicsConstraintInput) => Result<{
+        readonly id: string;
+        readonly revision: number;
+    }, DerivedPhysicsError>;
+    updateDerivedConstraint?: (input: PhysicsConstraintInput) => Result<{
+        readonly id: string;
+        readonly revision: number;
+    }, DerivedPhysicsError>;
+    removeDerivedConstraint?: (id: string) => Result<void, DerivedPhysicsError>;
 }
 /** 2D raycast hit result. */
 export interface RaycastHit2D {

package/dist/physics-world.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"physics-world.d.ts","sourceRoot":"","sources":["../src/physics-world.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;IAChB,gCAAgC;IAChC,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IAEhC,wCAAwC;IACxC,UAAU,IAAI,IAAI,CAAC;IAEnB;;;;;;;;OAQG;IACH,OAAO,CACL,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,UAAU,GAAG,SAAS,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvD,sDAAsD;IACtD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,qEAAqE;IACrE,YAAY,IAAI,MAAM,CAAC;IAEvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,UAAU,IAAI,IAAI,CAAC;IACnB,OAAO,CACL,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjE;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IACvD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,IAAI,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC"}
+{"version":3,"file":"physics-world.d.ts","sourceRoot":"","sources":["../src/physics-world.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-physics",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,21 +26,21 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.27",
-    "@forgeax/engine-math": "0.1.27",
-    "@forgeax/engine-plugin": "0.1.27",
-    "@forgeax/engine-types": "0.1.27"
+    "@forgeax/engine-ecs": "0.1.28",
+    "@forgeax/engine-math": "0.1.28",
+    "@forgeax/engine-plugin": "0.1.28",
+    "@forgeax/engine-types": "0.1.28"
   },
   "devDependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.27",
-    "@forgeax/engine-physics-rapier2d": "0.1.27",
-    "@forgeax/engine-physics-rapier3d": "0.1.27",
-    "@forgeax/engine-runtime": "0.1.27",
-    "@forgeax/engine-shader": "0.1.27"
+    "@forgeax/engine-assets-runtime": "0.1.28",
+    "@forgeax/engine-physics-rapier2d": "0.1.28",
+    "@forgeax/engine-physics-rapier3d": "0.1.28",
+    "@forgeax/engine-runtime": "0.1.28",
+    "@forgeax/engine-shader": "0.1.28"
   },
   "peerDependencies": {
-    "@forgeax/engine-physics-rapier2d": "0.1.27",
-    "@forgeax/engine-physics-rapier3d": "0.1.27"
+    "@forgeax/engine-physics-rapier2d": "0.1.28",
+    "@forgeax/engine-physics-rapier3d": "0.1.28"
   },
   "peerDependenciesMeta": {
     "@forgeax/engine-physics-rapier2d": {

package/src/__tests__/derived-physics.unit.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest';
+import {
+  cloneDerivedPhysicsInput,
+  normalizeVoxelShapeInput,
+  preserveCenterOfMassVelocity,
+  validateMassProperties,
+} from '../derived-physics';
+
+const shape = (id = 'left', voxelSize: readonly [number, number, number] = [1, 1, 1]) => ({
+  id,
+  revision: 1,
+  cells: new Int32Array([0, 0, 0, -1, 0, 0]),
+  voxelSize,
+});
+
+describe('derived physics data contract', () => {
+  it('copies cells and normalizes a local orientation before native preparation', () => {
+    const input = shape();
+    const result = normalizeVoxelShapeInput({ ...input, rotation: [0, 0, 0, 2] });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    input.cells[0] = 99;
+    expect(result.value.cells[0]).toBe(0);
+    expect(result.value.rotation[3]).toBeCloseTo(1);
+  });
+
+  it('rejects mismatched voxel seams and degenerate explicit mass', () => {
+    const seam = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [shape('left'), shape('right', [2, 1, 1])],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [1, 0, 0] }],
+    });
+    expect(seam.ok).toBe(false);
+    if (!seam.ok) expect(seam.error.code).toBe('derived-seam-invalid');
+
+    const mass = validateMassProperties({
+      mode: 'explicit',
+      mass: 1,
+      centerOfMass: [0, 0, 0],
+      principalInertia: [1, 0, 1],
+    });
+    expect(mass.ok).toBe(false);
+    if (!mass.ok) expect(mass.error.code).toBe('derived-mass-invalid');
+  });
+
+  it('requires seam origin/grid agreement while accepting quaternion sign equivalence', () => {
+    const aligned = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        { ...shape('left'), origin: [0, 0, 0], rotation: [0, 0, 0, 1] },
+        { ...shape('right'), origin: [2, 0, 0], rotation: [0, 0, 0, -1] },
+      ],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [2, 0, 0] }],
+    });
+    expect(aligned.ok).toBe(true);
+
+    const offsetMismatch = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        { ...shape('left'), origin: [0, 0, 0] },
+        { ...shape('right'), origin: [2, 0, 0] },
+      ],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [1, 0, 0] }],
+    });
+    expect(offsetMismatch.ok).toBe(false);
+    if (!offsetMismatch.ok) expect(offsetMismatch.error.code).toBe('derived-seam-invalid');
+
+    const rotationMismatch = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        { ...shape('left'), origin: [0, 0, 0] },
+        { ...shape('right'), origin: [2, 0, 0], rotation: [0, Math.SQRT1_2, 0, Math.SQRT1_2] },
+      ],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [2, 0, 0] }],
+    });
+    expect(rotationMismatch.ok).toBe(false);
+    if (!rotationMismatch.ok) expect(rotationMismatch.error.code).toBe('derived-seam-invalid');
+  });
+
+  it('checks seam offsets after rotating the local delta into the shared grid frame', () => {
+    const quarterTurnZ: readonly [number, number, number, number] = [
+      0,
+      0,
+      Math.SQRT1_2,
+      Math.SQRT1_2,
+    ];
+    const aligned = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        { ...shape('left'), origin: [0, 0, 0], rotation: quarterTurnZ },
+        { ...shape('right'), origin: [0, 1, 0], rotation: quarterTurnZ },
+      ],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [1, 0, 0] }],
+    });
+    expect(aligned.ok).toBe(true);
+
+    const misaligned = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        { ...shape('left'), origin: [0, 0, 0], rotation: quarterTurnZ },
+        { ...shape('right'), origin: [1, 0, 0], rotation: quarterTurnZ },
+      ],
+      seams: [{ shapeA: 'left', shapeB: 'right', offset: [1, 0, 0] }],
+    });
+    expect(misaligned.ok).toBe(false);
+    if (!misaligned.ok) expect(misaligned.error.code).toBe('derived-seam-invalid');
+  });
+
+  it('bounds candidate counts and estimated staged bytes', () => {
+    const tooManyShapes = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: Array.from({ length: 65 }, (_, index) => shape(`shape-${index}`)),
+    });
+    expect(tooManyShapes.ok).toBe(false);
+    if (!tooManyShapes.ok) {
+      expect(tooManyShapes.error.code).toBe('derived-candidate-budget-exceeded');
+      expect(tooManyShapes.error.detail.actual).toBe(65);
+    }
+
+    const tooManyBytes = cloneDerivedPhysicsInput({
+      entity: 7,
+      revision: 1,
+      sourceKey: 'body:7',
+      shapes: [
+        {
+          id: 'large',
+          revision: 1,
+          cells: new Int32Array(262_144 * 3),
+          voxelSize: [1, 1, 1],
+        },
+      ],
+    });
+    expect(tooManyBytes.ok).toBe(false);
+    if (!tooManyBytes.ok) expect(tooManyBytes.error.code).toBe('derived-candidate-budget-exceeded');
+  });
+
+  it('preserves linear velocity at a moved center of mass and leaves angular velocity intact', () => {
+    expect(preserveCenterOfMassVelocity([1, 2, 3], [0, 0, 2], [0, 0, 0], [0, 1, 0])).toEqual([
+      -1, 2, 3,
+    ]);
+  });
+});