@flighthq/physics3d 0.4.0-next.1694.598ef6f

package/src/step.test.ts

@@ -0,0 +1,390 @@
+import type { Physics3DContact, Physics3DWorld, RigidBody3D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createPhysics3DContact, createPhysics3DContactPoint } from './contacts';
+import { refreshRigidBody3DWorldInertia } from './integrate';
+import { createPhysics3DFixedJoint, createPhysics3DHingeJoint } from './jointFactories';
+import { addPhysics3DJoint, removePhysics3DJoint } from './jointRegistry';
+import { createPhysics3DMassData, setRigidBody3DMassData } from './massProperties';
+import { registerBuiltInPhysics3DJointSolvers } from './registerBuiltInPhysics3DJointSolvers';
+import { setPhysics3DStepGuard, stepPhysics3D, stepPhysics3DInterval } from './step';
+import {
+  addPhysics3DBody,
+  applyPhysics3DForce,
+  createPhysics3DWorld,
+  createRigidBody3D,
+  removePhysics3DBody,
+  setPhysics3DBodyType,
+} from './world';
+
+describe('setPhysics3DStepGuard', () => {
+  it('is consulted only when the step declines, and only while installed', () => {
+    const seen: number[] = [];
+    setPhysics3DStepGuard((_world, dt) => seen.push(dt));
+    try {
+      const world = createPhysics3DWorld();
+      addPhysics3DBody(world, createRigidBody3D('dynamic'));
+
+      // A step that runs must not reach the seam: the guard's message means the simulation stopped, so
+      // firing it on a healthy step would make the one signal it carries meaningless.
+      stepPhysics3D(world, 1 / 60);
+      expect(seen).toEqual([]);
+
+      stepPhysics3D(world, 0);
+      expect(seen).toEqual([0]);
+
+      setPhysics3DStepGuard(null);
+      stepPhysics3D(world, 0);
+      expect(seen).toEqual([0]);
+    } finally {
+      setPhysics3DStepGuard(null);
+    }
+  });
+});
+
+describe('stepPhysics3D', () => {
+  it('advances a free body by gravity over the interval', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+
+    stepPhysics3D(world, 1 / 60);
+
+    expect(body.velocityY).toBeCloseTo(world.gravityY / 60, 12);
+    expect(body.y).toBeCloseTo((world.gravityY / 60) * (1 / 60), 12);
+  });
+
+  it('refuses to run inside itself', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    addRestingContact(world, addUnitBody(world), ground);
+    world.contactHooks.preSolve = (inner) => stepPhysics3D(inner, 1 / 60);
+
+    expect(() => stepPhysics3D(world, 1 / 60)).toThrow(/recursively/);
+  });
+
+  it('declines silently rather than throwing on an unusable timestep', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+
+    expect(() => stepPhysics3D(world, 0)).not.toThrow();
+    expect(() => stepPhysics3D(world, Number.NaN)).not.toThrow();
+    expect(body.velocityY).toBe(0);
+    expect(body.y).toBe(0);
+  });
+
+  it('declines on a body carrying a non-finite field', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+    const other = addUnitBody(world);
+    other.velocityX = Number.POSITIVE_INFINITY;
+
+    stepPhysics3D(world, 1 / 60);
+
+    // One invalid body stops the whole step, because a NaN reaches every constraint its body touches.
+    expect(body.velocityY).toBe(0);
+  });
+
+  it('declines when substeps would advance nothing', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+    world.config.substeps = 0;
+
+    stepPhysics3D(world, 1 / 60);
+
+    expect(body.velocityY).toBe(0);
+  });
+
+  it('clears the force accumulators so a force applied once acts once', () => {
+    const world = createTestWorld();
+    world.gravityY = 0;
+    const body = addUnitBody(world);
+    applyPhysics3DForce(body, 10, 0, 0);
+
+    stepPhysics3D(world, 1 / 60);
+    const afterOne = body.velocityX;
+    stepPhysics3D(world, 1 / 60);
+
+    expect(afterOne).toBeCloseTo(10 / 60, 12);
+    expect(body.velocityX).toBeCloseTo(afterOne, 12);
+  });
+
+  it('records the SUB-interval as the previous timestep, not the whole step', () => {
+    const world = createTestWorld();
+    addUnitBody(world);
+    world.config.substeps = 4;
+
+    stepPhysics3D(world, 1 / 60);
+
+    // The warm-start cache is built by a sub-interval's iterations, so scaling it next step has to compare
+    // against that interval. Recording the whole step would rescale by the substep count.
+    expect(world.previousTimestep).toBeCloseTo(1 / 240, 12);
+  });
+
+  it('integrates more accurately with more substeps over the same interval', () => {
+    const coarse = createTestWorld();
+    const coarseBody = addUnitBody(coarse);
+    stepPhysics3D(coarse, 1 / 60);
+
+    const fine = createTestWorld();
+    fine.config.substeps = 8;
+    const fineBody = addUnitBody(fine);
+    stepPhysics3D(fine, 1 / 60);
+
+    // Both reach the same velocity — constant acceleration over the same total time — but the finer
+    // division tracks the exact 0.5*g*t^2 displacement more closely.
+    const exact = 0.5 * fine.gravityY * (1 / 60) * (1 / 60);
+    expect(fineBody.velocityY).toBeCloseTo(coarseBody.velocityY, 12);
+    expect(Math.abs(fineBody.y - exact)).toBeLessThan(Math.abs(coarseBody.y - exact));
+  });
+
+  it('resolves a supplied contact so a falling body does not pass through the ground', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    setPhysics3DBodyType(ground, 'static');
+    refreshRigidBody3DWorldInertia(ground);
+    const box = addUnitBody(world);
+    box.velocityY = -10;
+    addRestingContact(world, box, ground);
+
+    stepPhysics3D(world, 1 / 60);
+
+    expect(box.velocityY).toBeGreaterThan(-1e-6);
+  });
+
+  it('holds two bodies together through a joint across many steps', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const anchor = addUnitBody(world);
+    setPhysics3DBodyType(anchor, 'static');
+    refreshRigidBody3DWorldInertia(anchor);
+    const hanging = addUnitBody(world);
+    hanging.x = 1;
+    addPhysics3DJoint(
+      world,
+      createPhysics3DFixedJoint({ bodyA: anchor.index, bodyB: hanging.index, localAnchorBX: -1 }),
+    );
+
+    for (let i = 0; i < 120; i += 1) stepPhysics3D(world, 1 / 60);
+
+    // Gravity pulls for two seconds; without the joint the body would be roughly 20 units down.
+    expect(Math.abs(hanging.y)).toBeLessThan(0.05);
+    expect(hanging.x).toBeCloseTo(1, 1);
+  });
+
+  it('lets a hinge motor drive a body it is anchored to', () => {
+    const world = createTestWorld();
+    world.gravityY = 0;
+    registerBuiltInPhysics3DJointSolvers(world);
+    const anchor = addUnitBody(world);
+    setPhysics3DBodyType(anchor, 'static');
+    refreshRigidBody3DWorldInertia(anchor);
+    const arm = addUnitBody(world);
+    addPhysics3DJoint(
+      world,
+      createPhysics3DHingeJoint({
+        bodyA: anchor.index,
+        bodyB: arm.index,
+        enableMotor: true,
+        motorSpeed: 2,
+        maxMotorTorque: 1000,
+      }),
+    );
+
+    for (let i = 0; i < 30; i += 1) stepPhysics3D(world, 1 / 60);
+
+    expect(arm.angularVelocityX).toBeCloseTo(2, 4);
+  });
+
+  it('stops integrating a settled island, even under gravity', () => {
+    const world = createTestWorld();
+    world.gravityY = 0;
+    const body = addUnitBody(world);
+    for (let i = 0; i < 60; i += 1) stepPhysics3D(world, 1 / 60);
+    expect(body.sleeping).toBe(true);
+
+    const restingY = body.y;
+    world.gravityY = -10;
+    stepPhysics3D(world, 1 / 60);
+
+    // The whole point of the sleeping skip: a settled pile costs no integration, so gravity cannot
+    // accelerate it and it does not drift.
+    expect(body.y).toBe(restingY);
+    expect(body.velocityY).toBe(0);
+    expect(body.sleeping).toBe(true);
+  });
+
+  it('wakes a sleeping body the caller writes a velocity onto', () => {
+    const world = createTestWorld();
+    world.gravityY = 0;
+    const body = addUnitBody(world);
+    for (let i = 0; i < 60; i += 1) stepPhysics3D(world, 1 / 60);
+    expect(body.sleeping).toBe(true);
+
+    body.velocityY = 5;
+    stepPhysics3D(world, 1 / 60);
+
+    // Stillness is re-read from the CURRENT velocities at the top of every step, so writing one is enough
+    // to wake the island — a caller does not have to remember `wakePhysics3DBody` as well.
+    expect(body.sleeping).toBe(false);
+    expect(body.y).toBeCloseTo(5 / 60, 12);
+  });
+
+  it('lets a pre-solve hook disable a contact for the step', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    setPhysics3DBodyType(ground, 'static');
+    refreshRigidBody3DWorldInertia(ground);
+    const box = addUnitBody(world);
+    box.velocityY = -10;
+    addRestingContact(world, box, ground);
+    world.contactHooks.preSolve = (_inner, contact) => {
+      contact.enabled = false;
+    };
+
+    stepPhysics3D(world, 1 / 60);
+
+    expect(box.velocityY).toBeLessThan(-9);
+  });
+
+  it('runs the post-solve hook once the step has committed', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    setPhysics3DBodyType(ground, 'static');
+    refreshRigidBody3DWorldInertia(ground);
+    const box = addUnitBody(world);
+    box.velocityY = -10;
+    addRestingContact(world, box, ground);
+    let observed = Number.NaN;
+    world.contactHooks.postSolve = () => {
+      observed = box.velocityY;
+    };
+
+    stepPhysics3D(world, 1 / 60);
+
+    expect(observed).toBeCloseTo(box.velocityY, 12);
+  });
+
+  it('rejects a lifecycle mutation attempted from inside a hook', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const ground = addUnitBody(world);
+    const box = addUnitBody(world);
+    addRestingContact(world, box, ground);
+    const joint = addPhysics3DJoint(world, createPhysics3DFixedJoint({ bodyA: ground.index, bodyB: box.index }));
+    world.contactHooks.preSolve = (inner) => removePhysics3DJoint(inner, joint);
+
+    expect(() => stepPhysics3D(world, 1 / 60)).toThrow(/stepping/);
+  });
+
+  it('restores the fields a throwing hook touched before the failure propagates', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    const box = addUnitBody(world);
+    const contact = addRestingContact(world, box, ground);
+    contact.friction = 0.5;
+    world.contactHooks.preSolve = (_inner, edited) => {
+      edited.friction = 9;
+      throw new Error('hook failed');
+    };
+
+    expect(() => stepPhysics3D(world, 1 / 60)).toThrow(/hook failed/);
+    expect(contact.friction).toBe(0.5);
+    expect(ground.index).toBe(0);
+  });
+
+  it('rejects a hook that leaves a contact the step cannot use', () => {
+    const world = createTestWorld();
+    const ground = addUnitBody(world);
+    const contact = addRestingContact(world, addUnitBody(world), ground);
+    world.contactHooks.preSolve = (_inner, edited) => {
+      edited.friction = Number.NaN;
+    };
+
+    expect(() => stepPhysics3D(world, 1 / 60)).toThrow(/invalid contact state/);
+    expect(contact.friction).toBe(0);
+  });
+
+  it('clears the stepping flag after a hook throws, so the next step still runs', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+    addRestingContact(world, addUnitBody(world), body);
+    world.contactHooks.preSolve = () => {
+      throw new Error('hook failed');
+    };
+
+    expect(() => stepPhysics3D(world, 1 / 60)).toThrow();
+    world.contactHooks.preSolve = null;
+
+    expect(() => stepPhysics3D(world, 1 / 60)).not.toThrow();
+    expect(body.velocityY).toBeLessThan(0);
+  });
+
+  it('survives a body removed while a joint still names it', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const anchor = addUnitBody(world);
+    const hanging = addUnitBody(world);
+    addPhysics3DJoint(world, createPhysics3DFixedJoint({ bodyA: anchor.index, bodyB: hanging.index }));
+    removePhysics3DBody(world, hanging);
+
+    expect(() => stepPhysics3D(world, 1 / 60)).not.toThrow();
+    expect(Number.isFinite(anchor.y)).toBe(true);
+  });
+});
+
+describe('stepPhysics3DInterval', () => {
+  it('advances one sub-interval without touching the force accumulators', () => {
+    const world = createTestWorld();
+    const body = addUnitBody(world);
+    applyPhysics3DForce(body, 6, 0, 0);
+    // The island workspace is built by the step; a caller assembling its own loop builds it too.
+    stepPhysics3D(world, 1 / 60);
+    applyPhysics3DForce(body, 6, 0, 0);
+    const before = body.velocityX;
+
+    stepPhysics3DInterval(world, 1 / 60);
+
+    // The force is still there afterwards, because clearing it belongs to the step and not to the
+    // interval — a substep loop that cleared forces would apply them once and then integrate zeros.
+    expect(body.velocityX).toBeCloseTo(before + 6 / 60, 12);
+    expect(body.forceX).toBe(6);
+  });
+});
+
+// A resting contact between `box` and `ground`, with the normal oriented from the geometry rather than
+// assumed.
+//
+// The normal points so that resolving pushes A out of B — and A is whichever body holds the LOWER INDEX,
+// which the caller does not choose. Writing `normalY = 1` because "the ground is below" is right only when
+// the box happens to have been added first; the other way round it pushes the GROUND up out of the box,
+// which for a static ground is a no-op and reads as a solver that silently ignores the contact.
+function addRestingContact(world: Physics3DWorld, box: RigidBody3D, ground: RigidBody3D): Physics3DContact {
+  const contact = createPhysics3DContact(box.index, ground.index);
+  contact.normalY = contact.bodyA === box.index ? 1 : -1;
+  contact.touching = true;
+  const point = createPhysics3DContactPoint();
+  point.depth = 0.01;
+  point.featureId = 1;
+  contact.points.push(point);
+  contact.pointCount = 1;
+  world.contacts.push(contact);
+  return contact;
+}
+
+function addUnitBody(world: Physics3DWorld): RigidBody3D {
+  const body = createRigidBody3D('dynamic');
+  const data = createPhysics3DMassData();
+  data.mass = 1;
+  data.inertiaXX = 1;
+  data.inertiaYY = 1;
+  data.inertiaZZ = 1;
+  setRigidBody3DMassData(body, data);
+  addPhysics3DBody(world, body);
+  return body;
+}
+
+function createTestWorld(): Physics3DWorld {
+  const world = createPhysics3DWorld();
+  world.gravityY = -10;
+  return world;
+}

package/src/stepValidation.test.ts

@@ -0,0 +1,244 @@
+import type { Physics3DWorld } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createPhysics3DContact, createPhysics3DContactPoint } from './contacts';
+import { createPhysics3DBallAndSocketJoint } from './jointFactories';
+import { addPhysics3DJoint } from './jointRegistry';
+import {
+  isPhysics3DBodyStateValid,
+  isPhysics3DContactStateValid,
+  isPhysics3DContactValid,
+  isPhysics3DGravityValid,
+  isPhysics3DJointStateValid,
+  isPhysics3DPositionIterationsValid,
+  isPhysics3DSolverConfigValid,
+  isPhysics3DSubstepsValid,
+  isPhysics3DTimestepValid,
+  isPhysics3DVelocityIterationsValid,
+} from './stepValidation';
+import { addPhysics3DBody, createPhysics3DWorld, createRigidBody3D } from './world';
+
+describe('isPhysics3DBodyStateValid', () => {
+  it('accepts a freshly built world', () => {
+    expect(isPhysics3DBodyStateValid(createTestWorld())).toBe(true);
+  });
+
+  it('rejects a non-finite pose, velocity, or accumulator', () => {
+    for (const key of ['z', 'orientationW', 'angularVelocityY', 'torqueZ', 'centerX'] as const) {
+      const world = createTestWorld();
+      world.bodies[0][key] = Number.NaN;
+      expect(isPhysics3DBodyStateValid(world)).toBe(false);
+    }
+  });
+
+  it('rejects a non-finite WORLD inertia tensor', () => {
+    const world = createTestWorld();
+    world.bodies[0].inverseInertiaWorldXY = Number.POSITIVE_INFINITY;
+
+    // Derived, and included anyway: it is what every constraint row multiplies by, so a NaN there reaches
+    // both bodies of every contact and joint within one sub-interval.
+    expect(isPhysics3DBodyStateValid(world)).toBe(false);
+  });
+
+  it('rejects a body the index map has lost track of', () => {
+    const world = createTestWorld();
+    world.bodyByIndex.delete(world.bodies[0].index);
+
+    expect(isPhysics3DBodyStateValid(world)).toBe(false);
+  });
+
+  it('rejects an unknown body type and a negative mass', () => {
+    const type = createTestWorld();
+    (type.bodies[0] as { type: string }).type = 'ghost';
+    expect(isPhysics3DBodyStateValid(type)).toBe(false);
+
+    const mass = createTestWorld();
+    mass.bodies[0].mass = -1;
+    expect(isPhysics3DBodyStateValid(mass)).toBe(false);
+  });
+});
+
+describe('isPhysics3DContactStateValid', () => {
+  it('accepts a world with no contacts', () => {
+    expect(isPhysics3DContactStateValid(createTestWorld())).toBe(true);
+  });
+
+  it('rejects the world when any one contact is unusable', () => {
+    const world = createTestWorld();
+    world.contacts.push(createPhysics3DContact(0, 1));
+    world.contacts.push(createPhysics3DContact(0, 1));
+    world.contacts[1].friction = Number.NaN;
+
+    expect(isPhysics3DContactStateValid(world)).toBe(false);
+  });
+});
+
+describe('isPhysics3DContactValid', () => {
+  it('accepts a freshly allocated contact', () => {
+    expect(isPhysics3DContactValid(createPhysics3DContact(0, 1))).toBe(true);
+  });
+
+  it('rejects a point count that runs past the points it has', () => {
+    const contact = createPhysics3DContact(0, 1);
+    contact.pointCount = 2;
+
+    expect(isPhysics3DContactValid(contact)).toBe(false);
+  });
+
+  it('rejects a negative friction or restitution', () => {
+    const friction = createPhysics3DContact(0, 1);
+    friction.friction = -0.1;
+    expect(isPhysics3DContactValid(friction)).toBe(false);
+
+    const restitution = createPhysics3DContact(0, 1);
+    restitution.restitution = -1;
+    expect(isPhysics3DContactValid(restitution)).toBe(false);
+  });
+
+  it('rejects a non-finite field on a point it will actually read', () => {
+    const contact = createPhysics3DContact(0, 1);
+    const point = createPhysics3DContactPoint();
+    point.rBZ = Number.NaN;
+    contact.points.push(point);
+    contact.pointCount = 1;
+
+    expect(isPhysics3DContactValid(contact)).toBe(false);
+  });
+
+  it('ignores a point beyond the count, which the solver never reads', () => {
+    const contact = createPhysics3DContact(0, 1);
+    const point = createPhysics3DContactPoint();
+    point.depth = Number.NaN;
+    contact.points.push(point);
+
+    expect(isPhysics3DContactValid(contact)).toBe(true);
+  });
+});
+
+describe('isPhysics3DGravityValid', () => {
+  it('accepts finite gravity on every axis and rejects any non-finite one', () => {
+    expect(isPhysics3DGravityValid(createTestWorld())).toBe(true);
+
+    for (const axis of ['gravityX', 'gravityY', 'gravityZ'] as const) {
+      const world = createTestWorld();
+      world[axis] = Number.NaN;
+      expect(isPhysics3DGravityValid(world)).toBe(false);
+    }
+  });
+});
+
+describe('isPhysics3DJointStateValid', () => {
+  it('accepts a world with no joints', () => {
+    expect(isPhysics3DJointStateValid(createTestWorld())).toBe(true);
+  });
+
+  it('rejects a joint with an empty kind or a non-integer endpoint', () => {
+    const kind = createTestWorld();
+    addPhysics3DJoint(kind, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 })).kind = '';
+    expect(isPhysics3DJointStateValid(kind)).toBe(false);
+
+    const endpoint = createTestWorld();
+    addPhysics3DJoint(endpoint, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 })).bodyB = 1.5;
+    expect(isPhysics3DJointStateValid(endpoint)).toBe(false);
+  });
+
+  it('rejects a non-finite field a kind added, not only the common ones', () => {
+    const world = createTestWorld();
+    const joint = addPhysics3DJoint(world, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 }));
+    (joint as unknown as Record<string, number>).acmeSuspensionTravel = Number.NaN;
+
+    // Walking the object rather than a fixed key list is what makes this cover a user's own joint kind,
+    // which is the point of an open registry.
+    expect(isPhysics3DJointStateValid(world)).toBe(false);
+  });
+});
+
+describe('isPhysics3DPositionIterationsValid', () => {
+  it('accepts zero and rejects a negative or fractional count', () => {
+    const world = createTestWorld();
+    world.config.sequentialImpulse.positionIterations = 0;
+    expect(isPhysics3DPositionIterationsValid(world.config)).toBe(true);
+
+    world.config.sequentialImpulse.positionIterations = -1;
+    expect(isPhysics3DPositionIterationsValid(world.config)).toBe(false);
+
+    world.config.sequentialImpulse.positionIterations = 2.5;
+    expect(isPhysics3DPositionIterationsValid(world.config)).toBe(false);
+  });
+});
+
+describe('isPhysics3DSolverConfigValid', () => {
+  it('accepts the default tuning', () => {
+    expect(isPhysics3DSolverConfigValid(createTestWorld().config)).toBe(true);
+  });
+
+  it('rejects a position correction outside zero to one', () => {
+    const world = createTestWorld();
+    world.config.sequentialImpulse.positionCorrection = 1.5;
+
+    expect(isPhysics3DSolverConfigValid(world.config)).toBe(false);
+  });
+
+  it('rejects negative sleep thresholds and a negative slop', () => {
+    const threshold = createTestWorld();
+    threshold.config.sleepAngularThreshold = -1;
+    expect(isPhysics3DSolverConfigValid(threshold.config)).toBe(false);
+
+    const slop = createTestWorld();
+    slop.config.sequentialImpulse.penetrationSlop = -0.01;
+    expect(isPhysics3DSolverConfigValid(slop.config)).toBe(false);
+  });
+
+  it('does not speak for the iteration counts or substeps', () => {
+    const world = createTestWorld();
+    world.config.substeps = 0;
+    world.config.sequentialImpulse.velocityIterations = -4;
+
+    // Those three are asked separately, because they are the ones a caller is most likely to have tuned by
+    // hand and the explanation names each of them.
+    expect(isPhysics3DSolverConfigValid(world.config)).toBe(true);
+  });
+});
+
+describe('isPhysics3DSubstepsValid', () => {
+  it('requires at least one whole sub-interval', () => {
+    const world = createTestWorld();
+    expect(isPhysics3DSubstepsValid(world.config)).toBe(true);
+
+    for (const substeps of [0, -1, 1.5, Number.NaN]) {
+      world.config.substeps = substeps;
+      expect(isPhysics3DSubstepsValid(world.config)).toBe(false);
+    }
+  });
+});
+
+describe('isPhysics3DTimestepValid', () => {
+  it('requires a finite positive interval', () => {
+    expect(isPhysics3DTimestepValid(1 / 60)).toBe(true);
+    expect(isPhysics3DTimestepValid(0)).toBe(false);
+    expect(isPhysics3DTimestepValid(-1)).toBe(false);
+    expect(isPhysics3DTimestepValid(Number.NaN)).toBe(false);
+    expect(isPhysics3DTimestepValid(Number.POSITIVE_INFINITY)).toBe(false);
+  });
+});
+
+describe('isPhysics3DVelocityIterationsValid', () => {
+  it('accepts zero and rejects a negative or fractional count', () => {
+    const world = createTestWorld();
+    world.config.sequentialImpulse.velocityIterations = 0;
+    expect(isPhysics3DVelocityIterationsValid(world.config)).toBe(true);
+
+    world.config.sequentialImpulse.velocityIterations = -1;
+    expect(isPhysics3DVelocityIterationsValid(world.config)).toBe(false);
+
+    world.config.sequentialImpulse.velocityIterations = 0.5;
+    expect(isPhysics3DVelocityIterationsValid(world.config)).toBe(false);
+  });
+});
+
+function createTestWorld(): Physics3DWorld {
+  const world = createPhysics3DWorld();
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  return world;
+}