@forgeax/engine-physics-rapier3d 0.1.28 → 0.1.30

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

@@ -44,12 +44,13 @@ function addBody(
   pw: ReturnType<typeof createRapier3DPhysicsWorld>,
   entity: number,
   position: [number, number, number],
+  rotation: readonly [number, number, number, number] = [0, 0, 0, 1],
 ) {
   pw.ensureBody(
     entity,
     {
       position: { x: position[0], y: position[1], z: position[2] },
-      rotation: { x: 0, y: 0, z: 0, w: 1 },
+      rotation: { x: rotation[0], y: rotation[1], z: rotation[2], w: rotation[3] },
       scale: { x: 1, y: 1, z: 1 },
     },
     {
@@ -100,6 +101,408 @@ function rapierWithMassFailure(RAPIER: Rapier3DModule): Rapier3DModule {
 }
 
 describe('Rapier 3D derived voxel candidates', () => {
+  it('applies a revision-bound world impulse at a point without teleporting the derived body', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      pw.setGravity(vec3.create(0, 0, 0));
+      addBody(pw, 7, [0, 0, 0]);
+      pw.admitDerivedShapeCandidate(
+        pw.prepareDerivedShapeCandidate(voxelCandidate(7, 1)).unwrap(),
+      ).unwrap();
+      pw.step(1 / 60);
+      const before = pw.getDerivedMotion(7);
+      if (before === undefined) throw new Error('missing committed motion');
+      const input = {
+        entity: 7,
+        sourceKey: 'body:7',
+        revision: 1,
+        impulse: [0, 2, 0] as const,
+        point: [
+          before.centerOfMass[0] + 1,
+          before.centerOfMass[1],
+          before.centerOfMass[2],
+        ] as const,
+      };
+      pw.applyDerivedImpulse(input).unwrap();
+      const after = pw.getDerivedMotion(7);
+      if (after === undefined) throw new Error('missing impulse motion');
+      expect(after.centerOfMass).toEqual(before.centerOfMass);
+      expect(after.linearVelocity[1] - before.linearVelocity[1]).toBeCloseTo(1, 5);
+      expect(after.angularVelocity[2] - before.angularVelocity[2]).toBeCloseTo(2, 5);
+      expect(pw.applyDerivedImpulse({ ...input, revision: 0 }).ok).toBe(false);
+      expect(pw.applyDerivedImpulse({ ...input, sourceKey: 'another-owner' }).ok).toBe(false);
+      expect(pw.applyDerivedImpulse({ ...input, impulse: [0, Number.NaN, 0] }).ok).toBe(false);
+      expect(pw.getDerivedMotion(7)).toEqual(after);
+      const queued = pw.prepareDerivedShapeCandidate(voxelCandidate(7, 2)).unwrap();
+      pw.admitDerivedShapeCandidate(queued).unwrap();
+      expect(pw.applyDerivedImpulse(input).ok).toBe(false);
+      pw.cancelDerivedShapeCandidate(queued).unwrap();
+      expect(pw.applyDerivedImpulse(input).ok).toBe(true);
+      const moving = pw.getDerivedMotion(7);
+      if (moving === undefined) throw new Error('missing moving body');
+      pw.step(1 / 120);
+      const advanced = pw.getDerivedMotion(7);
+      if (advanced === undefined) throw new Error('missing stepped motion');
+      expect(advanced.centerOfMass[1] - moving.centerOfMass[1]).toBeCloseTo(
+        moving.linearVelocity[1] / 120,
+        5,
+      );
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it('requires recovery after a native impulse mutates and then throws', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const OriginalWorld = RAPIER.World;
+    function FaultWorld(gravity: unknown) {
+      const world = new OriginalWorld(gravity);
+      const create = world.createRigidBody.bind(world);
+      world.createRigidBody = (descriptor: unknown) => {
+        const body = create(descriptor);
+        const apply = body.applyImpulseAtPoint.bind(body);
+        body.applyImpulseAtPoint = (...args: unknown[]) => {
+          apply(...args);
+          throw new Error('partial native impulse');
+        };
+        return body;
+      };
+      return world;
+    }
+    const pw = createRapier3DPhysicsWorld({ ...RAPIER, World: FaultWorld });
+    try {
+      addBody(pw, 7, [0, 0, 0]);
+      pw.admitDerivedShapeCandidate(
+        pw.prepareDerivedShapeCandidate(voxelCandidate(7, 1)).unwrap(),
+      ).unwrap();
+      pw.step(1 / 60);
+      expect(
+        pw.applyDerivedImpulse({
+          entity: 7,
+          sourceKey: 'body:7',
+          revision: 1,
+          impulse: [1, 0, 0],
+          point: [0, 0, 0],
+        }).ok,
+      ).toBe(false);
+      expect(pw.getDerivedRecoveryState()).toBe('rebuild-required');
+      expect(pw.getDerivedMotion(7)).toBeUndefined();
+      expect(() => pw.raycast(vec3.create(0, 0, 5), vec3.create(0, 0, -1), 10)).toThrow();
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it('clears one derived shape set in the same group that replaces its successor', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      pw.setGravity(vec3.create(0, 0, 0));
+      for (const entity of [7, 8]) {
+        addBody(pw, entity, [(entity - 7) * 10, 0, 0]);
+        pw.admitDerivedShapeCandidate(
+          pw.prepareDerivedShapeCandidate(voxelCandidate(entity, 1)).unwrap(),
+        ).unwrap();
+      }
+      pw.step(1 / 60);
+      const ray = () => pw.raycast(vec3.create(-0.5, 0.5, 3), vec3.create(0, 0, -1), 5);
+      expect(ray()?.entity).toBe(7);
+      const removed = pw
+        .prepareDerivedShapeCandidate({ entity: 7, revision: 2, sourceKey: 'body:7', shapes: [] })
+        .unwrap();
+      const successor = pw.prepareDerivedShapeCandidate(voxelCandidate(8, 2)).unwrap();
+      pw.admitDerivedShapeCandidates([removed, successor]).unwrap();
+      expect(ray()?.entity).toBe(7);
+      pw.step(1 / 60);
+      expect(ray()).toBeUndefined();
+      expect(pw.getDerivedPublication(7)).toMatchObject({ revision: 2, shapeIds: [] });
+      expect(pw.getDerivedPublication(8)?.revision).toBe(2);
+      expect(pw.hasBody(7)).toBe(true); // ECS still owns body removal.
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it.each([
+    'cancel',
+    'despawn',
+  ] as const)('releases the whole queued group after one member %s', async (action) => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      for (const entity of [7, 8]) addBody(pw, entity, [(entity - 7) * 10, 0, 0]);
+      const candidates = [7, 8].map((entity) =>
+        pw.prepareDerivedShapeCandidate(voxelCandidate(entity, 1)).unwrap(),
+      );
+      pw.admitDerivedShapeCandidates(candidates).unwrap();
+      const first = candidates[0];
+      if (first === undefined) throw new Error('missing first fixture candidate');
+      if (action === 'cancel') pw.cancelDerivedShapeCandidate(first).unwrap();
+      else pw.removeEntity(7);
+      pw.step(1 / 60);
+      expect(pw.getDerivedPublication(8)).toBeUndefined();
+      // A stranded member would retain the per-body pending lock here.
+      const retry = pw.prepareDerivedShapeCandidate(voxelCandidate(8, 2)).unwrap();
+      pw.admitDerivedShapeCandidate(retry).unwrap();
+      pw.step(1 / 60);
+      expect(pw.getDerivedPublication(8)?.revision).toBe(2);
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it.each([
+    'refuse',
+    'throw',
+  ] as const)('treats a batch geometry %s as a group-wide outcome', async (action) => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      for (const entity of [7, 8]) {
+        addBody(pw, entity, [(entity - 7) * 10, 0, 0]);
+        pw.admitDerivedShapeCandidate(
+          pw.prepareDerivedShapeCandidate(voxelCandidate(entity, 1)).unwrap(),
+        ).unwrap();
+      }
+      pw.step(1 / 60);
+      const candidates = [7, 8].map((entity) =>
+        pw.prepareDerivedShapeCandidate(voxelCandidate(entity, 2)).unwrap(),
+      );
+      pw.admitDerivedShapeCandidates(candidates, () => {
+        if (action === 'throw') throw new Error('uncertain consumer write');
+        return err(new Error('consumer refused without writes'));
+      }).unwrap();
+      pw.step(1 / 60);
+      for (const entity of [7, 8]) {
+        expect(pw.getDerivedFailure(entity)?.recovery).toBe(
+          action === 'throw' ? 'rebuild-required' : 'old-state-retained',
+        );
+        expect(pw.getDerivedPublication(entity)?.revision).toBe(action === 'throw' ? undefined : 1);
+      }
+      expect(pw.getDerivedRecoveryState()).toBe(action === 'throw' ? 'rebuild-required' : 'ready');
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it('publishes two derived bodies under one paired admission and fixed-step receipt', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      pw.setGravity(vec3.create(0, 0, 0));
+      addBody(pw, 7, [0, 0, 0]);
+      addBody(pw, 8, [10, 0, 0]);
+      const candidates = [7, 8].map((entity) =>
+        pw
+          .prepareDerivedShapeCandidate({
+            ...voxelCandidate(entity, 1),
+            constraints: [
+              {
+                id: `coupled:${entity}`,
+                revision: 1,
+                kind: 'spring',
+                bodyA: 7,
+                bodyB: 8,
+                bodyASource: { sourceKey: 'body:7', revision: 1 },
+                bodyBSource: { sourceKey: 'body:8', revision: 1 },
+                anchorA: [0, 0, 0],
+                anchorB: [0, 0, 0],
+                restLength: 10,
+                stiffness: 2,
+                damping: 1,
+              },
+            ],
+          })
+          .unwrap(),
+      );
+      let commits = 0;
+      pw.admitDerivedShapeCandidates(candidates, () => {
+        commits += 1;
+        expect(pw.getDerivedAdmission(7)).toMatchObject({ entity: 7, revision: 1, fixedStep: 1 });
+        expect(pw.getDerivedAdmission(8)).toMatchObject({ entity: 8, revision: 1, fixedStep: 1 });
+        return ok(undefined);
+      }).unwrap();
+      expect(pw.getDerivedPublication(7)).toBeUndefined();
+      expect(pw.getDerivedPublication(8)).toBeUndefined();
+      pw.step(1 / 60);
+      expect(commits).toBe(1);
+      expect(pw.getDerivedPublication(7)).toMatchObject({ revision: 1, fixedStep: 1 });
+      expect(pw.getDerivedPublication(8)).toMatchObject({ revision: 1, fixedStep: 1 });
+      expect(pw.getDerivedAdmission(7)).toBeUndefined();
+      const snapshot = pw.captureDerivedPhysicsState();
+      const fresh = createRapier3DPhysicsWorld(RAPIER);
+      try {
+        fresh.setGravity(vec3.create(0, 0, 0));
+        addBody(fresh, 7, [0, 0, 0]);
+        addBody(fresh, 8, [10, 0, 0]);
+        fresh.restoreDerivedPhysicsState(snapshot).unwrap();
+        fresh.step(1 / 60);
+        expect(fresh.getDerivedPublication(7)?.revision).toBe(1);
+        expect(fresh.getDerivedPublication(8)?.revision).toBe(1);
+        const restored = fresh
+          .captureDerivedPhysicsState()
+          .bodies.flatMap((body) => body.constraints);
+        expect([...new Set(restored.map((joint) => joint.id))].sort()).toEqual([
+          'coupled:7',
+          'coupled:8',
+        ]);
+      } finally {
+        fresh.dispose();
+      }
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it('rolls back the entire group when the second native mass mutation fails', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const OriginalWorld = RAPIER.World;
+    let failSecond = false;
+    function FaultWorld(gravity: unknown) {
+      const world = new OriginalWorld(gravity);
+      const create = world.createRigidBody.bind(world);
+      world.createRigidBody = (descriptor: unknown) => {
+        const body = create(descriptor);
+        const setMass = body.setAdditionalMassProperties.bind(body);
+        body.setAdditionalMassProperties = (...args: unknown[]) => {
+          setMass(...args);
+          if (failSecond && args[0] === 13) {
+            failSecond = false;
+            throw new Error('second body failed after mass mutation');
+          }
+        };
+        return body;
+      };
+      return world;
+    }
+    const pw = createRapier3DPhysicsWorld({ ...RAPIER, World: FaultWorld });
+    try {
+      pw.setGravity(vec3.create(0, 0, 0));
+      for (const entity of [7, 8]) {
+        addBody(pw, entity, [(entity - 7) * 10, 0, 0]);
+        pw.admitDerivedShapeCandidate(
+          pw.prepareDerivedShapeCandidate(voxelCandidate(entity, 1)).unwrap(),
+        ).unwrap();
+      }
+      pw.step(1 / 60);
+      const before = [7, 8].map((entity) => ({
+        publication: pw.getDerivedPublication(entity),
+        motion: pw.getDerivedMotion(entity),
+      }));
+      const joint = {
+        id: 'batch-shared-joint',
+        revision: 1,
+        kind: 'spring' as const,
+        bodyA: 7,
+        bodyB: 8,
+        bodyASource: { sourceKey: 'body:7', revision: 1 },
+        bodyBSource: { sourceKey: 'body:8', revision: 1 },
+        anchorA: [0, 0, 0] as const,
+        anchorB: [0, 0, 0] as const,
+        restLength: 10,
+        stiffness: 2,
+        damping: 1,
+      };
+      pw.createDerivedConstraint(joint).unwrap();
+      const oldRay = () => pw.raycast(vec3.create(-0.5, 0.5, 3), vec3.create(0, 0, -1), 5);
+      const newRay = () => pw.raycast(vec3.create(4.5, 0.5, 3), vec3.create(0, 0, -1), 5);
+      expect(oldRay()?.entity).toBe(7);
+      expect(newRay()).toBeUndefined();
+      const candidates = [7, 8].map((entity) => {
+        const input = voxelCandidate(entity, 2);
+        return pw
+          .prepareDerivedShapeCandidate({
+            ...input,
+            shapes: [{ id: 'replacement', revision: 2, cells: [[4, 0, 0]], voxelSize: [1, 1, 1] }],
+            seams: [],
+            constraints:
+              entity === 7
+                ? [
+                    {
+                      ...joint,
+                      revision: 2,
+                      bodyASource: { sourceKey: 'body:7', revision: 2 },
+                      bodyBSource: { sourceKey: 'body:8', revision: 2 },
+                    },
+                  ]
+                : [],
+            massProperties: { ...input.massProperties, mass: entity === 7 ? 5 : 13 },
+          })
+          .unwrap();
+      });
+      let commits = 0;
+      failSecond = true;
+      pw.admitDerivedShapeCandidates(candidates, () => {
+        commits += 1;
+        return ok(undefined);
+      }).unwrap();
+      pw.step(1 / 60);
+      expect(commits).toBe(0);
+      expect(oldRay()?.entity).toBe(7);
+      expect(newRay()).toBeUndefined();
+      expect(pw.captureDerivedPhysicsState().bodies.flatMap((body) => body.constraints)).toEqual([
+        joint,
+        joint,
+      ]);
+      for (let i = 0; i < 2; i++) {
+        const entity = i + 7;
+        expect(pw.getDerivedPublication(entity)).toEqual(before[i]?.publication);
+        expect(pw.getDerivedMotion(entity)).toEqual(before[i]?.motion);
+        expect(pw.getDerivedFailure(entity)).toMatchObject({
+          candidateId: candidates[i]?.candidateId,
+          recovery: 'old-state-retained',
+        });
+      }
+      expect(pw.getDerivedRecoveryState()).toBe('ready');
+    } finally {
+      pw.dispose();
+    }
+  });
+
+  it('restores a world COM using the newly admitted nonzero local mass center', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    try {
+      pw.setGravity(vec3.create(0, 0, 0));
+      addBody(pw, 7, [10, 20, 0], [0, 0, Math.SQRT1_2, Math.SQRT1_2]);
+      pw.admitDerivedShapeCandidate(
+        pw
+          .prepareDerivedShapeCandidate({
+            ...voxelCandidate(7, 1),
+            massProperties: {
+              mode: 'explicit',
+              mass: 6,
+              centerOfMass: [1.5, 0, 0.5],
+              principalInertia: [1, 1, 1],
+            },
+            motion: {
+              centerOfMass: [10, 21.5, 0.5],
+              linearVelocity: [0, 0, 0],
+              angularVelocity: [0, 0, 0],
+            },
+          })
+          .unwrap(),
+      ).unwrap();
+      pw.step(1 / 60);
+      const motion = pw.getDerivedMotion(7);
+      expect(motion?.centerOfMass[0]).toBeCloseTo(10, 5);
+      expect(motion?.centerOfMass[1]).toBeCloseTo(21.5, 5);
+      expect(motion?.centerOfMass[2]).toBeCloseTo(0.5, 5);
+      expect(pw.getDerivedBodyMass(7)).toBeCloseTo(6, 5);
+    } finally {
+      pw.dispose();
+    }
+  });
+
   it('stops publication and queries if native step throws after the geometry commit', async () => {
     const RAPIER = await loadRapier3D();
     if ('code' in RAPIER) throw RAPIER;
@@ -258,6 +661,84 @@ describe('Rapier 3D derived voxel candidates', () => {
     expect(pw.getDerivedBodyMass(7)).toBeCloseTo(2, 5);
   });
 
+  it('retains a newly created colliderless body when its first paired admission is refused', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    pw.ensureBody(
+      7,
+      {
+        position: { x: 0, y: 0, z: 0 },
+        rotation: { x: 0, y: 0, z: 0, w: 1 },
+        scale: { x: 1, y: 1, z: 1 },
+      },
+      { type: 1, mass: 1, linearDamping: 0, angularDamping: 0, gravityScale: 0, ccdEnabled: 0 },
+      undefined,
+    );
+    expect(pw.getDerivedBodyMass(7)).toBeCloseTo(1);
+    const candidate = pw.prepareDerivedShapeCandidate(voxelCandidate(7, 1)).unwrap();
+    pw.admitDerivedShapeCandidates([candidate], () =>
+      err(new Error('reject new fragment')),
+    ).unwrap();
+    pw.step(1 / 60);
+    expect(pw.getDerivedRecoveryState()).toBe('ready');
+    expect(pw.getDerivedFailure(7)?.recovery).toBe('old-state-retained');
+    expect(pw.getDerivedBodyMass(7)).toBeCloseTo(1);
+    expect(pw.getDerivedPublication(7)).toBeUndefined();
+    expect(pw.raycast(vec3.create(0.5, 0.5, 3), vec3.create(0, 0, -1), 5)).toBeUndefined();
+    pw.dispose();
+  });
+
+  it('carries a successor world orientation through admission, rollback and snapshot recovery', async () => {
+    const RAPIER = await loadRapier3D();
+    if ('code' in RAPIER) throw RAPIER;
+    const pw = createRapier3DPhysicsWorld(RAPIER);
+    addBody(pw, 16, [0, 0, 0]);
+    const rotation: [number, number, number, number] = [0, Math.SQRT1_2, 0, Math.SQRT1_2];
+    const input = {
+      ...voxelCandidate(16, 1),
+      motion: {
+        centerOfMass: [10, 0, 0] as const,
+        linearVelocity: [0, 0, 0] as const,
+        angularVelocity: [0, 0, 0] as const,
+        rotation,
+      },
+    };
+    const prepared = pw.prepareDerivedShapeCandidate(input).unwrap();
+    rotation[1] = 0;
+    rotation[3] = 1;
+    pw.admitDerivedShapeCandidate(prepared).unwrap();
+    pw.step(1 / 60);
+    expect(pw.getDerivedMotion(16)?.rotation?.[1]).toBeCloseTo(Math.SQRT1_2);
+    expect(pw.raycast(vec3.create(10.5, 4, -2.25), vec3.create(0, -1, 0), 5)?.entity).toBe(16);
+    const before = pw.getDerivedMotion(16);
+    pw.admitDerivedShapeCandidate(
+      pw
+        .prepareDerivedShapeCandidate({
+          ...voxelCandidate(16, 2),
+          motion: { ...input.motion, rotation: [0, 0, 0, 1] },
+        })
+        .unwrap(),
+      () => err(new Error('keep the prior orientation')),
+    ).unwrap();
+    pw.step(1 / 60);
+    expect(pw.getDerivedMotion(16)).toEqual(before);
+    const snapshot = pw.captureDerivedPhysicsState();
+    pw.removeEntity(16);
+    addBody(pw, 16, [0, 0, 0]);
+    pw.restoreDerivedPhysicsState(snapshot).unwrap();
+    pw.step(1 / 60);
+    expect(pw.getDerivedMotion(16)?.rotation?.[1]).toBeCloseTo(Math.SQRT1_2);
+    expect(pw.raycast(vec3.create(10.5, 4, -2.25), vec3.create(0, -1, 0), 5)?.entity).toBe(16);
+    expect(
+      pw.prepareDerivedShapeCandidate({
+        ...voxelCandidate(16, 2),
+        motion: { ...input.motion, rotation: [0, 0, 0, 0] },
+      }).ok,
+    ).toBe(false);
+    pw.dispose();
+  });
+
   it('exposes committed COM and motion and restores that movement through a snapshot', async () => {
     const RAPIER = await loadRapier3D();
     if ('code' in RAPIER) {

package/src/index.ts

@@ -3,11 +3,11 @@
 // Re-exports the RapierPhysicsWorld3D class, WASM loader, and three-phase tick
 // systems.
 
-export type { Rapier3DCollisionEvent } from './rapier-physics-world-3d';
+export type { Rapier3DCollisionEvent } from './rapier-physics-world-3d.js';
 export {
   createRapier3DPhysicsWorld,
   RapierPhysicsWorld3D,
   registerPhysicsSystems,
-} from './rapier-physics-world-3d';
-export type { Rapier3DModule } from './wasm-loader';
-export { loadRapier3D } from './wasm-loader';
+} from './rapier-physics-world-3d.js';
+export type { Rapier3DModule } from './wasm-loader.js';
+export { loadRapier3D } from './wasm-loader.js';