openvibers/openvibe.games Commits
Physics conformance suite and an in-memory mock world (ADR-0007 M1 step 1): packages/physics/src/conformance.test.ts runs every seam case against MockPhysicsWorld and the Havok adapter (bodies, sweeps, joints, sleep and settle thresholds read through the adapter under test, gravity measured, per-engine landing heights pinned separately), with a guard that fails on a skip entry naming no case. The mock (@openvibe/physics/mock) now backs the gameplay movement tests in place of their ad-hoc stub, which exposed two mock bugs: a swept capsule's height is its total height including caps (it was 0.8 m too tall), and a capsule sweep meets a plane from either side (walls and ceilings were passed through), with the start-overlap guard both engines have. The two unrun smoke scripts are gone (the suite covers them). sliceTest waits for the recalled snapshot and meta.secured inside one budget (a race). Reviewed independently twice; pnpm typecheck, lint and test green (1036 passed, 9 skipped).
Changes
@@@ -100,7 +100,6 @@ freeze. Props are protected: only you and players you trust can move them.| `pnpm format` | Prettier write || `pnpm build` | Production build of all packages + client bundle || `tsx apps/server/scripts/sliceTest.ts` | End-to-end vertical-slice test (boots a real server, drives protocol clients, restarts, asserts persistence) |--| `tsx packages/physics/scripts/smoke.ts` | Headless Havok smoke test |## Production@@@ -1711,12 +1711,18 @@ async function main(): Promise<void> {}assert(site, 'extraction event announced with a location')await walkTo(a, site[0], site[1], 60_000)-- // Hold the circle until the recall (25s hold + slack).++ // Hold the circle until the recall (25s hold + slack). The recall arrives as++ // three separate frames — an announce, the position update and the++ // inventory — in no guaranteed order, so the loop must not stop on the++ // player snapshot alone: the inventory frame carrying meta.secured is what++ // the assertion below reads, and it routinely lands after the snapshot.{const start = Date.now()++ const secured = (): boolean =>++ a.inventory?.slots.find((s) => s.stack.def === 'salvage_core')?.stack.meta?.secured === 1while (Date.now() - start < 45_000) {const me = a.me-- if (me && Math.hypot(me.pos[0] - 0, me.pos[2] - 4) < 6) break // recalled to spawn++ if (me && Math.hypot(me.pos[0] - 0, me.pos[2] - 4) < 6 && secured()) break // both frames in// Nudge back toward the beacon in case physics drift pushed us out.const dist = me ? Math.hypot(me.pos[0] - site[0], me.pos[2] - site[1]) : 99if (me && dist > 3) await walkTo(a, site[0], site[1], 6000)@@@ -12,5 +12,8 @@"dependencies": {"@openvibe/content": "workspace:*","@openvibe/shared": "workspace:*"++ },++ "devDependencies": {++ "@openvibe/physics": "workspace:*"}}@@@ -1,7 +1,12 @@--import { describe, expect, it } from 'vitest'++import { afterEach, describe, expect, it } from 'vitest'import { vec3, type Vec3 } from '@openvibe/shared'++import {++ createMockPhysicsWorld,++ mockCollisionQueries,++ type MockPhysicsWorld,++} from '@openvibe/physics/mock'import { Buttons } from './buttons.js'--import type { CollisionQueries, SweepHit } from './collision.js'++import type { CollisionQueries } from './collision.js'import { DEFAULT_MOVEMENT } from './params.js'import {Stance,@@@ -16,34 +21,28 @@ const P = DEFAULT_MOVEMENTconst DT = 1 / 30/**-- * Analytic test world: infinite ground plane at y=0 and an optional wall-- * plane at x = wallX (normal -X). Capsule contact analytically resolved.++ * The movement tests walk on the physics package's own mock world rather than++ * a hand-rolled analytic stub, so the sweep geometry under test is the one++ * `mockCollisionQueries` binds with the server's mask (apps/server/src/game/++ * systems/movement.ts:58-68). Analytic surfaces stand in for level geometry:++ * `addGroundPlane` is the floor, `addCast` a wall or a ceiling.*/--function makeWorld(wallX?: number): CollisionQueries {-- return {-- sweepCapsule(from: Vec3, to: Vec3, radius: number, height: number): SweepHit | null {-- const half = height / 2-- const hits: SweepHit[] = []-- const fromBottom = from.y - half-- const toBottom = to.y - half-- if (fromBottom >= 0 && toBottom < 0) {-- const fraction = fromBottom / (fromBottom - toBottom)-- hits.push({ fraction, normal: vec3(0, 1, 0), point: vec3(from.x, 0, from.z) })-- }-- if (wallX !== undefined) {-- const limit = wallX - radius-- if (from.x <= limit && to.x > limit) {-- const fraction = (limit - from.x) / (to.x - from.x)-- hits.push({ fraction, normal: vec3(-1, 0, 0), point: vec3(wallX, from.y, from.z) })-- }-- }-- if (hits.length === 0) return null-- hits.sort((a, b) => a.fraction - b.fraction)-- return hits[0] ?? null-- },-- }++/** Worlds created by `makeWorld`, disposed after each case. */++const live: MockPhysicsWorld[] = []++++function makeWorld(opts?: { wallX?: number; ceilingY?: number }): CollisionQueries {++ const world = createMockPhysicsWorld()++ world.addGroundPlane(0)++ if (opts?.wallX !== undefined) world.addCast({ normal: vec3(1, 0, 0), offset: opts.wallX })++ if (opts?.ceilingY !== undefined) world.addCast({ normal: vec3(0, 1, 0), offset: opts.ceilingY })++ live.push(world)++ return mockCollisionQueries(world)}++afterEach(() => {++ while (live.length > 0) live.pop()?.dispose()++})++function idle(): MoveInput {return { moveX: 0, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }}@@@ -52,8 +51,13 @@ function forward(buttons = 0): MoveInput {return { moveX: 0, moveZ: 1, yaw: 0, pitch: 0, buttons }}++/**++ * Spawn a hair above the floor: the mock's ground plane rejects a sweep that++ * starts in exact contact (t = 0, like Havok's), so a spawn at exactly++ * capsuleHeight/2 has no ground to find until gravity pulls it down a tick.++ */function spawnGrounded() {-- return createMoveState(vec3(0, P.capsuleHeight / 2, 0))++ return createMoveState(vec3(0, P.capsuleHeight / 2 + 0.01, 0))}function horizSpeed(v: Vec3): number {@@@ -135,7 +139,7 @@ describe('stepMovement', () => {it('slides along walls instead of stopping', () => {const s = spawnGrounded()-- const world = makeWorld(2)++ const world = makeWorld({ wallX: 2 })// Move diagonally (+X into wall, +Z along it)const input: MoveInput = { moveX: 1, moveZ: 1, yaw: 0, pitch: 0, buttons: 0 }for (let i = 0; i < 120; i++) stepMovement(s, input, P, world, DT)@@@ -146,7 +150,7 @@ describe('stepMovement', () => {it('is deterministic for identical input streams', () => {const run = () => {const s = spawnGrounded()-- const world = makeWorld(3)++ const world = makeWorld({ wallX: 3 })for (let i = 0; i < 200; i++) {const input: MoveInput = {moveX: Math.sin(i * 0.1),@@@ -217,21 +221,9 @@ describe('stances', () => {})it('standing up is blocked by a ceiling', () => {-- // World with a ceiling at y=1.4: crouch fits (hull 1.2), standing does not.-- const ceiling = 1.4-- const world: ReturnType<typeof makeWorld> = {-- sweepCapsule(from, to, radius, height) {-- const base = makeWorld().sweepCapsule(from, to, radius, height)-- const fromTop = from.y + height / 2-- const toTop = to.y + height / 2-- if (fromTop <= ceiling && toTop > ceiling) {-- const fraction = (ceiling - fromTop) / (toTop - fromTop)-- const hit = { fraction, normal: vec3(0, -1, 0), point: vec3(from.x, ceiling, from.z) }-- if (!base || fraction < base.fraction) return hit-- }-- return base-- },-- }++ // Upward-facing analytic plane at y=1.4: crouch fits (hull 1.2), standing++ // does not, so the up-sweep inside updateStance must hit it.++ const world = makeWorld({ ceilingY: 1.4 })const s = spawnGrounded()stepMovement(s, { ...idle(), buttons: Buttons.Crouch }, P, world, DT)for (let i = 0; i < 30; i++)@@@ -274,7 +266,7 @@ describe('noclip', () => {it('passes through walls', () => {const state = createMoveState(vec3(0, 1, 0))state.noclip = true-- const world = makeWorld(2) // wall at x=2++ const world = makeWorld({ wallX: 2 }) // wall at x=2for (let i = 0; i < 90; i++)stepMovement(state, { moveX: 1, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }, P, world, DT)expect(state.pos.x).toBeGreaterThan(3)@@@ -5,7 +5,8 @@"type": "module","exports": {".": "./src/index.ts",-- "./havok": "./src/havok/index.ts"++ "./havok": "./src/havok/index.ts",++ "./mock": "./src/mock.ts"},"scripts": {"build": "tsc --build"ddeleted file mode 100644@@@ -1,267 +0,0 @@--/**-- * Headless constraint smoke test (run with tsx): exercises every sandbox-- * constraint variant — rope, hinge (limits, friction, motor), slider-- * (limits, motor), spring — against real Havok, exactly as the dedicated-- * server runs it. Complements smoke.ts (bodies, sweeps, weld).-- */--import { readFile } from 'node:fs/promises'--import { createRequire } from 'node:module'--import HavokPhysics from '@babylonjs/havok'--import { quat, vec3, type Vec3 } from '@openvibe/shared'--import { CollisionLayer } from '../src/types.js'--import { createHeadlessHavokWorld } from '../src/havok/index.js'----const require = createRequire(import.meta.url)--const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')--const havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })----const world = createHeadlessHavokWorld(havok)--const dt = 1 / 30--const PROP_MASK = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player----world.addBody({-- shape: { type: 'box', size: [200, 1, 200] },-- motion: 'static',-- pos: vec3(0, -0.5, 0),-- layer: CollisionLayer.Static,-- collidesWith: CollisionLayer.Prop | CollisionLayer.Player,--})----const rot = quat()--const p = vec3()----function makeBox(pos: Vec3, size = 0.5, motion: 'dynamic' | 'static' = 'dynamic'): number {-- return world.addBody({-- shape: { type: 'box', size: [size, size, size] },-- motion,-- pos,-- massKg: 10,-- layer: CollisionLayer.Prop,-- collidesWith: PROP_MASK,-- })--}----// ── Rope: a box tethered to a static anchor swings but never exceeds length ──--{-- const anchor = makeBox(vec3(0, 6, 0), 0.4, 'static')-- const bob = makeBox(vec3(1.5, 6, 0), 0.4)-- const rope = world.addConstraint({-- type: 'rope',-- bodyA: anchor,-- bodyB: bob,-- anchorA: vec3(0, 0, 0),-- anchorB: vec3(0, 0, 0),-- length: 2,-- })-- let maxDist = 0-- let minY = Infinity-- for (let i = 0; i < 300; i++) {-- world.step(dt)-- world.getTransform(bob, p, rot)-- maxDist = Math.max(maxDist, Math.hypot(p.x, p.y - 6, p.z))-- minY = Math.min(minY, p.y)-- }-- console.log('rope: max anchor distance', maxDist.toFixed(3), 'lowest y', minY.toFixed(2))-- if (maxDist > 2.3) throw new Error(`rope stretched past length: ${maxDist}`)-- // The bob must have swung down through the bottom of its arc (a pendulum-- // on a taut 2 m tether reaches y ≈ 4).-- if (minY > 4.6) throw new Error(`rope bob never swung down: minY=${minY}`)-- world.removeConstraint(rope)--}----// ── Hinge with limits: a door swings but respects ±45° ──--{-- const post = makeBox(vec3(10, 2, 0), 0.4, 'static')-- const door = makeBox(vec3(10.9, 2, 0), 0.4)-- world.addConstraint({-- type: 'hinge',-- bodyA: post,-- bodyB: door,-- anchorA: vec3(0.45, 0, 0),-- anchorB: vec3(-0.45, 0, 0),-- axisA: vec3(0, 1, 0),-- axisB: vec3(0, 1, 0),-- limits: { min: -Math.PI / 4, max: Math.PI / 4 },-- })-- // Shove the door hard sideways; the hinge must cap the swing.-- world.setLinearVelocity(door, vec3(0, 0, 8))-- let maxAngle = 0-- for (let i = 0; i < 90; i++) {-- world.step(dt)-- world.getTransform(door, p, rot)-- const angle = Math.abs(Math.atan2(p.z, p.x - 10))-- maxAngle = Math.max(maxAngle, angle)-- }-- console.log('hinge: max swing angle', ((maxAngle * 180) / Math.PI).toFixed(1), 'deg')-- if (maxAngle > Math.PI / 4 + 0.25) throw new Error(`hinge blew past its limit: ${maxAngle}`)-- if (maxAngle < 0.2) throw new Error('hinge did not swing at all')-- world.getTransform(door, p, rot)-- if (Math.abs(p.y - 2) > 0.25) throw new Error(`hinge door fell: y=${p.y}`)--}----// ── Motorized hinge (bearing + drive): a wheel spins up ──--{-- const axleMount = makeBox(vec3(20, 3, 0), 0.4, 'static')-- const wheel = world.addBody({-- shape: { type: 'cylinder', radius: 0.6, height: 0.2 },-- motion: 'dynamic',-- pos: vec3(20, 3, 0.4),-- massKg: 8,-- layer: CollisionLayer.Prop,-- collidesWith: PROP_MASK,-- })-- const motorId = world.addConstraint({-- type: 'hinge',-- bodyA: axleMount,-- bodyB: wheel,-- anchorA: vec3(0, 0, 0.4),-- anchorB: vec3(0, 0, 0),-- axisA: vec3(0, 0, 1),-- axisB: vec3(0, 1, 0), // cylinder's own axis is +Y-- motor: { targetVelocity: 6, maxForce: 500 },-- })-- const av = vec3()-- for (let i = 0; i < 90; i++) world.step(dt)-- world.getAngularVelocity(wheel, av)-- const spin = Math.hypot(av.x, av.y, av.z)-- console.log('motor: wheel angular speed', spin.toFixed(2), 'rad/s')-- if (spin < 4) throw new Error(`motorized wheel did not spin up: ${spin}`)-- // Retune the motor to stop; it should brake.-- world.setConstraintMotor(motorId, { targetVelocity: 0, maxForce: 500 })-- for (let i = 0; i < 60; i++) world.step(dt)-- world.getAngularVelocity(wheel, av)-- const stopped = Math.hypot(av.x, av.y, av.z)-- console.log('motor: after brake', stopped.toFixed(3), 'rad/s')-- if (stopped > 0.5) throw new Error(`motor did not brake: ${stopped}`)--}----// ── Slider with limits: a drawer slides along a rail and stops ──--{-- const rail = makeBox(vec3(30, 2, 0), 0.4, 'static')-- const drawer = makeBox(vec3(30, 2, 0.6), 0.4)-- world.addConstraint({-- type: 'slider',-- bodyA: rail,-- bodyB: drawer,-- anchorA: vec3(0, 0, 0.6),-- anchorB: vec3(0, 0, 0),-- axisA: vec3(0, 0, 1),-- axisB: vec3(0, 0, 1),-- limits: { min: -0.5, max: 1.0 },-- })-- world.setLinearVelocity(drawer, vec3(0, 0, 5))-- let maxZ = -Infinity-- let minZ = Infinity-- let maxOffAxis = 0-- for (let i = 0; i < 120; i++) {-- world.step(dt)-- world.getTransform(drawer, p, rot)-- maxZ = Math.max(maxZ, p.z)-- minZ = Math.min(minZ, p.z)-- maxOffAxis = Math.max(maxOffAxis, Math.abs(p.x - 30), Math.abs(p.y - 2))-- if (i === 60) world.setLinearVelocity(drawer, vec3(0, 0, -5))-- }-- console.log(-- 'slider: travel',-- minZ.toFixed(2),-- '..',-- maxZ.toFixed(2),-- 'off-axis',-- maxOffAxis.toFixed(3),-- )-- if (maxZ > 1.85 || minZ < -0.15) throw new Error(`slider blew limits: ${minZ}..${maxZ}`)-- if (maxZ < 1.3) throw new Error(`slider did not travel: ${maxZ}`)-- if (maxOffAxis > 0.15) throw new Error(`slider left its rail: ${maxOffAxis}`)--}----// ── Spring: a hanging box bounces then settles near rest length ──--{-- const mount = makeBox(vec3(40, 6, 0), 0.4, 'static')-- const bob = makeBox(vec3(40, 5.5, 0), 0.4)-- world.addConstraint({-- type: 'spring',-- bodyA: mount,-- bodyB: bob,-- anchorA: vec3(0, 0, 0),-- anchorB: vec3(0, 0, 0),-- restLength: 1.5,-- stiffness: 400,-- damping: 15,-- })-- for (let i = 0; i < 300; i++) world.step(dt)-- world.getTransform(bob, p, rot)-- const dist = Math.hypot(p.x - 40, p.y - 6, p.z)-- console.log('spring: settled anchor distance', dist.toFixed(3), '(rest 1.5)')-- // Gravity stretches the spring below rest; generous envelope.-- if (dist < 1.2 || dist > 2.2) throw new Error(`spring settled badly: ${dist}`)--}----// ── Stress: a 200-prop welded structure must settle and stay cheap ──--{-- const GRID = 10 // 10 x 20 wall of boxes-- const ROWS = 20-- const ids: number[] = []-- for (let r = 0; r < ROWS; r++) {-- for (let c = 0; c < GRID; c++) {-- ids.push(makeBox(vec3(60 + c * 0.52, 0.26 + r * 0.52, 0), 0.5))-- }-- }-- // Weld each box to its right and upper neighbor (grid lattice).-- let welds = 0-- for (let r = 0; r < ROWS; r++) {-- for (let c = 0; c < GRID; c++) {-- const i = r * GRID + c-- if (c + 1 < GRID) {-- world.addConstraint({ type: 'weld', bodyA: ids[i]!, bodyB: ids[i + 1]! })-- welds++-- }-- if (r + 1 < ROWS) {-- world.addConstraint({ type: 'weld', bodyA: ids[i]!, bodyB: ids[i + GRID]! })-- welds++-- }-- }-- }-- // Settle phase.-- let settleTick = -1-- const t0 = performance.now()-- for (let i = 0; i < 600; i++) {-- world.step(dt)-- if (settleTick < 0 && ids.every((id) => world.isSettled(id))) {-- settleTick = i-- break-- }-- }-- const settleMs = performance.now() - t0-- console.log(-- `stress: ${ids.length} props, ${welds} welds — settled at tick ${settleTick} (${settleMs.toFixed(0)}ms total)`,-- )-- if (settleTick < 0) throw new Error('welded structure never settled')---- // Settled steps must be cheap (structure asleep, no solver churn).-- const t1 = performance.now()-- for (let i = 0; i < 100; i++) world.step(dt)-- const idleMs = (performance.now() - t1) / 100-- console.log(`stress: settled step cost ${idleMs.toFixed(3)}ms`)-- if (idleMs > 5) throw new Error(`sleeping welded structure too expensive: ${idleMs}ms/step`)-- if (!ids.every((id) => world.isSettled(id))) throw new Error('structure woke without cause')---- // Impact wakes the island, then it settles again.-- world.setLinearVelocity(ids[ids.length - 1]!, vec3(0, 0, 6))-- world.step(dt)-- const awake = ids.filter((id) => !world.isSettled(id)).length-- console.log(`stress: impact woke ${awake} bodies`)-- if (awake < 1) throw new Error('impact failed to wake the structure')-- let resettled = false-- for (let i = 0; i < 900; i++) {-- world.step(dt)-- if (ids.every((id) => world.isSettled(id))) {-- resettled = true-- console.log(`stress: re-settled after ${i} ticks`)-- break-- }-- }-- if (!resettled) throw new Error('structure never re-settled after impact')--}----world.dispose()--console.log('CONSTRAINT SMOKE OK')ddeleted file mode 100644@@@ -1,120 +0,0 @@--/**-- * Headless physics smoke test (run with tsx): loads the Havok wasm in Node,-- * builds a world, drops a dynamic box onto static ground, checks it settles,-- * and verifies capsule sweeps + raycasts. Exercises the exact code path the-- * dedicated server uses.-- */--import { readFile } from 'node:fs/promises'--import { createRequire } from 'node:module'--import HavokPhysics from '@babylonjs/havok'--import { quat, vec3 } from '@openvibe/shared'--import { CollisionLayer } from '../src/types.js'--import { createHeadlessHavokWorld } from '../src/havok/index.js'----const require = createRequire(import.meta.url)--const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')--const havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })----const world = createHeadlessHavokWorld(havok)----const ground = world.addBody({-- shape: { type: 'box', size: [100, 1, 100] },-- motion: 'static',-- pos: vec3(0, -0.5, 0),-- layer: CollisionLayer.Static,-- collidesWith: CollisionLayer.Prop | CollisionLayer.Player,--})----const box = world.addBody({-- shape: { type: 'box', size: [0.7, 0.7, 0.7] },-- motion: 'dynamic',-- pos: vec3(0, 3, 0),-- massKg: 25,-- layer: CollisionLayer.Prop,-- collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,--})----const dt = 1 / 30--for (let i = 0; i < 120; i++) world.step(dt)----const pos = vec3()--const rot = quat()--world.getTransform(box, pos, rot)--console.log('box rest pos:', pos, 'settled:', world.isSettled(box))--if (Math.abs(pos.y - 0.35) > 0.05) throw new Error(`box did not rest at 0.35: ${pos.y}`)--if (!world.isSettled(box)) throw new Error('box did not settle')----// Capsule sweep down over the box should hit its top--const hit = world.sweepCapsule(-- vec3(0, 3, 0),-- vec3(0, 0.5, 0),-- 0.4,-- 1.8,-- CollisionLayer.Static | CollisionLayer.Prop,--)--console.log('sweep hit:', hit)--if (!hit || hit.normal.y < 0.9) throw new Error('capsule sweep failed')----// Raycast should identify the box body--const ray = world.raycast(vec3(2, 0.35, 0), vec3(-2, 0.35, 0), CollisionLayer.Prop)--console.log('ray hit:', ray)--if (!ray || ray.bodyId !== box) throw new Error('raycast failed')----// Freeze then unfreeze--world.setMotionType(box, 'static')--world.setMotionType(box, 'dynamic')--world.step(dt)----// Kinematic player body pushes a prop--const player = world.addBody({-- shape: { type: 'capsule', radius: 0.4, height: 1.8 },-- motion: 'kinematic',-- pos: vec3(-3, 0.9, 0),-- layer: CollisionLayer.Player,-- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,--})--for (let i = 0; i < 60; i++) {-- world.setTransform(player, vec3(-3 + i * 0.06, 0.9, 0))-- world.step(dt)--}--world.getTransform(box, pos, rot)--console.log('box after push:', pos, 'settled:', world.isSettled(box))--if (pos.x < 0.05) throw new Error('kinematic player failed to push prop')----// Weld: two stacked boxes welded together should move as one and keep--// their relative offset after being shoved.--const weldA = world.addBody({-- shape: { type: 'box', size: [0.5, 0.5, 0.5] },-- motion: 'dynamic',-- pos: vec3(10, 0.25, 0),-- massKg: 10,-- layer: CollisionLayer.Prop,-- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,--})--const weldB = world.addBody({-- shape: { type: 'box', size: [0.5, 0.5, 0.5] },-- motion: 'dynamic',-- pos: vec3(10, 0.78, 0),-- massKg: 10,-- layer: CollisionLayer.Prop,-- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,--})--for (let i = 0; i < 30; i++) world.step(dt)--const weldId = world.addConstraint({ type: 'weld', bodyA: weldA, bodyB: weldB })--world.setLinearVelocity(weldA, vec3(4, 0, 0))--for (let i = 0; i < 60; i++) world.step(dt)--const pa = vec3()--const pb = vec3()--world.getTransform(weldA, pa, rot)--world.getTransform(weldB, pb, rot)--console.log('weld: A', pa, 'B', pb)--if (pa.x < 10.3) throw new Error('welded pair did not slide')--const dy = pb.y - pa.y--if (Math.abs(pb.x - pa.x) > 0.25 || dy < 0.3 || dy > 0.75) {-- throw new Error(`weld did not hold relative pose (dx=${pb.x - pa.x}, dy=${dy})`)--}--world.removeConstraint(weldId)----world.removeBody(ground)--world.dispose()--console.log('PHYSICS SMOKE OK')nnew file mode 100644@@@ -0,0 +1,1536 @@++import { readFile } from 'node:fs/promises'++import { createRequire } from 'node:module'++import { quat, vec3, type Quat, type Vec3 } from '@openvibe/shared'++import { beforeAll, describe, expect, it } from 'vitest'++import HavokPhysics from '@babylonjs/havok'++import { createHeadlessHavokWorld } from './havok/index.js'++import {++ MOCK_GRAVITY,++ MOCK_SETTLE_ANGULAR,++ MOCK_SETTLE_LINEAR,++ MOCK_TICK,++ createMockPhysicsWorld,++} from './mock.js'++import { CollisionLayer, type BodyDesc, type PhysicsWorld } from './types.js'++++/**++ * Seam conformance.++ *++ * Every case runs against whatever PhysicsWorld factory is handed to++ * `conformance()`, so a second engine (ADR-0007 decision 2 names Rapier) can be++ * held to exactly the behaviour Havok has today. Nothing in this file may reach++ * around the seam: no Babylon, no Havok, no assumption about internals beyond++ * what `PhysicsWorld` promises.++ *++ * ── Constants, read off havokWorld.ts rather than the brief ──────────────++ * - gravity (0, -16.5, 0) havokWorld.ts:588++ * - material friction 0.75 / static 0.85 / restitution 0.05 :123++ * - linear damping 0.05, angular 0.6 :131-132++ * - default mass 10 kg :128++ * - settle thresholds 0.05 m/s, 0.15 rad/s :72-73 (squared compare, angular `<=`)++ *++ * ── Behaviour asserted here that is NOT in the seam doc comment ──────────++ * These are properties of today's Havok adapter, documented so the Rapier port++ * reproduces them rather than trips over them:++ *++ * 1. **`step(dt)` does not honour its argument.** `HavokWorld.step` calls++ * `plugin.executeStep(dt, bodies)`, and the Havok plugin resolves the world++ * step time as `this._useDeltaForWorldStep ? delta : this._fixedTimeStep`++ * with `_useDeltaForWorldStep` false by default — so every step() advances a++ * fixed 1/60 s of simulation regardless of the dt passed in. Measured: 30++ * step(1/30) and 30 step(1/15) both yield v.y = -8.14 m/s, while 60++ * step(1/60) yields -16.09. The seam comment says "advances by a fixed dt",++ * which is the *intent*; the caller-side 30 Hz tick is what the game relies++ * on and it is unaffected, but a Rapier adapter that actually honours dt++ * would be ~2× faster per tick at 30 Hz and would change every simulation++ * constant tuned against Havok. Listed for Opus.++ * 2. **Waking or settling a body at the exact threshold.** The code compares++ * `len² > threshold²` for linear (so a body moving at exactly 0.05 m/s is++ * reported *unsettled* by Havok's float storage, though the comparison says++ * settled) and `<=` for angular. The mock implements the comparison as++ * written; this suite therefore probes just under and just over each++ * threshold and does not pin the exact-boundary behaviour.++ * 3. **Raycast filtering is by the body's own `layer`.** `plugin.raycast` is++ * called with `membership: 0xffffffff, collideWith: collidesWith`++ * (havokWorld.ts:415-418), but the shape filter is a membership/collide++ * pair, so a body is hit when `rayMask & body.layer` and `body.layer &++ * body.collidesWith` — the body's `collidesWith` must include its own layer++ * for the pair to pass. Measured: layer Player / collidesWith Static is hit++ * by mask 4 but not by mask 1, while layer Static / collidesWith Prop is hit++ * by mask 1, 2, 3 and 7. The mock filters on `rayMask & body.layer` only,++ * which is a superset — see "what the mock does not model".++ * 4. **A welded body resists velocity changes for a few steps.** `setLinearVelocity`++ * on one half of a weld writes the velocity, but the joint's relative-pose++ * preservation pulls the pair back over the next couple of steps. Asserted++ * here as "the pair stays together", not as free sliding.++ * 5. **`isSettled`, `wake` and `applyForce` ignore non-dynamic bodies**++ * (havokWorld.ts:225, :233, :406), and `removeBody` / `removeConstraint` on++ * an unknown id are silent no-ops (:142, :399) while every other body++ * accessor throws `unknown physics body <id>` (:482).++ */++++const DT = 1 / 30++++interface Adapter {++ /** Name used in the describe block. */++ name: string++ /** Fresh world per case; the case disposes it. */++ create: () => PhysicsWorld++ /**++ * Cases the mock deliberately does not model. Listing a case here keeps it in++ * the file (visible, not forgotten) while marking it as Havok-only.++ */++ skip?: (title: string) => boolean++ /**++ * Real simulated seconds one `step()` advances. The mock honours the dt it is++ * given; the Havok plugin resolves a fixed 1/60 s of its own (see the header++ * note), so a case that wants "N seconds of gravity" must ask each adapter for++ * its own tick count rather than sharing one number.++ */++ stepSeconds: number++}++++/** HavokWorld over a NullEngine scene — the exact headless server code path. */++let havok: unknown++beforeAll(async () => {++ const require = createRequire(import.meta.url)++ const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')++ havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })++}, 60_000)++++const havokAdapter: Adapter = {++ name: 'HavokWorld',++ create: () => createHeadlessHavokWorld(havok),++ // Measured (header note 1): the plugin ignores the dt passed to step() and++ // advances its own fixed 1/60 s.++ stepSeconds: 1 / 60,++}++++/**++ * Case titles the mock cannot model, as prefixes. Kept as data (not baked into++ * a lambda) so `it('every case the mock skips still runs somewhere')` can check++ * each one against the titles this file actually defines: an entry left behind++ * after a case is renamed or deleted silently skips nothing, which is how the++ * mock came to run a case its own header said it could not model.++ */++const MOCK_SKIP_PREFIXES: readonly string[] = [++ 'step advances',++ 'a welded island',++ 'a welded pair resists',++ 'a spring',++ 'a rope',++ 'a hinge',++ 'a motorized hinge',++ 'a slider',++ 'angular damping is strong',++ 'surface friction is high',++ 'a body knocked off',++ 'sweepCapsule offsetting',++]++++/**++ * The mock world, with the same analytic surfaces the Havok cases build out of++ * static boxes. No ambient ground plane: several cases deliberately sweep a ray++ * or capsule through empty space or sideways past a wall, and a global plane++ * would hit first.++ */++const mockAdapter: Adapter = {++ name: 'MockPhysicsWorld',++ // No ambient ground plane: several cases deliberately sweep a ray or capsule++ // through empty space or sideways past a wall, and a global plane would hit++ // first. Cases that need ground add `groundDesc()` like the Havok ones.++ create: () => createMockPhysicsWorld(),++ // Semi-implicit Euler at the 30 Hz tick the game actually runs at.++ stepSeconds: MOCK_TICK,++ skip: (title) => MOCK_SKIP_PREFIXES.some((prefix) => title.startsWith(prefix)),++}++++const pos = (): Vec3 => vec3()++const rot = (): Quat => quat()++++/** Ground: a 200 m static box with its top face at y = 0. */++function groundDesc(size = 200): BodyDesc {++ return {++ shape: { type: 'box', size: [size, 1, size] },++ motion: 'static',++ pos: vec3(0, -0.5, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ }++}++++function dynamicBoxDesc(at: Vec3, size = 0.7, massKg?: number): BodyDesc {++ return {++ shape: { type: 'box', size: [size, size, size] },++ motion: 'dynamic',++ pos: at,++ ...(massKg === undefined ? {} : { massKg }),++ layer: CollisionLayer.Prop,++ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,++ }++}++++function stepFor(w: PhysicsWorld, ticks: number, dt = DT): void {++ for (let i = 0; i < ticks; i++) w.step(dt)++}++++/**++ * Steps `seconds` worth of SIMULATED time. The two engines do not agree on how++ * long one step() is (header note 1), so a case that means "two seconds of++ * gravity" must convert through the adapter rather than share a tick count.++ */++function stepSecondsFor(a: Adapter, w: PhysicsWorld, seconds: number): void {++ stepFor(w, Math.round(seconds / a.stepSeconds))++}++++/** A body at rest: dynamic, but its gravity contribution is neutralised. */++function addParkedBody(w: PhysicsWorld, at: Vec3, massKg = 10): number {++ const id = w.addBody(dynamicBoxDesc(at, 0.5, massKg))++ // Park it by freezing and unfreezing: the seam's documented freeze path.++ w.setMotionType(id, 'static')++ w.setMotionType(id, 'dynamic')++ return id++}++++function conformance(a: Adapter): void {++ describe(`PhysicsWorld conformance: ${a.name}`, () => {++ const maybe = a.skip ?? (() => false)++++ /** The world for one case; `close()` disposes it. */++ let world: PhysicsWorld | null = null++ const open = (): PhysicsWorld => {++ world = a.create()++ return world++ }++ const close = (): void => {++ world?.dispose()++ world = null++ }++++ // ── lifecycle ───────────────────────────────────────────────────────────++++ it('adds a body and returns a live id', () => {++ const w = open()++ const ground = w.addBody(groundDesc())++ const p = pos()++ w.getTransform(ground, p, rot())++ expect(p.y).toBeCloseTo(-0.5, 3)++ close()++ })++++ it('hands out distinct ids for distinct bodies', () => {++ const w = open()++ expect(w.addBody(groundDesc())).not.toBe(w.addBody(dynamicBoxDesc(vec3(5, 10, 5))))++ close()++ })++++ it('removeBody drops the body; removing it again is a silent no-op', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0)))++ w.removeBody(box)++ expect(() => w.removeBody(box)).not.toThrow()++ expect(() => w.getTransform(box, pos(), rot())).toThrow(/unknown physics body/)++ close()++ })++++ it('every other body accessor throws on an unknown id', () => {++ const w = open()++ const ghost = 987_654++ expect(() => w.setTransform(ghost, vec3())).toThrow(/unknown physics body/)++ expect(() => w.setMotionType(ghost, 'static')).toThrow(/unknown physics body/)++ expect(() => w.getLinearVelocity(ghost, pos())).toThrow(/unknown physics body/)++ expect(() => w.setLinearVelocity(ghost, vec3())).toThrow(/unknown physics body/)++ expect(() => w.getAngularVelocity(ghost, pos())).toThrow(/unknown physics body/)++ expect(() => w.setAngularVelocity(ghost, vec3())).toThrow(/unknown physics body/)++ expect(() => w.isSettled(ghost)).toThrow(/unknown physics body/)++ expect(() => w.wake(ghost)).toThrow(/unknown physics body/)++ expect(() => w.applyForce(ghost, vec3(1, 0, 0))).toThrow(/unknown physics body/)++ close()++ })++++ // ── transforms ──────────────────────────────────────────────────────────++++ it('getTransform reports the transform the body was added with', () => {++ const w = open()++ const b = w.addBody({++ shape: { type: 'box', size: [1, 1, 1] },++ motion: 'static',++ pos: vec3(3, 2, -7),++ rot: quat(0, 1, 0, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop,++ })++ const p = pos()++ const q = rot()++ w.getTransform(b, p, q)++ expect(p.x).toBeCloseTo(3, 5)++ expect(p.y).toBeCloseTo(2, 5)++ expect(p.z).toBeCloseTo(-7, 5)++ expect(q.y).toBeCloseTo(1, 5)++ expect(q.w).toBeCloseTo(0, 5)++ close()++ })++++ it('a body added without a rotation reads back as identity', () => {++ const w = open()++ const q = rot()++ w.getTransform(w.addBody(groundDesc()), pos(), q)++ expect(q).toEqual({ x: 0, y: 0, z: 0, w: 1 })++ close()++ })++++ it('setTransform teleports a STATIC body (remote-player mirror regression)', () => {++ const w = open()++ const mirror = w.addBody({++ shape: { type: 'capsule', radius: 0.4, height: 1.8 },++ motion: 'static',++ pos: vec3(0, 1, 0),++ layer: CollisionLayer.Player,++ collidesWith: CollisionLayer.Static | CollisionLayer.Prop,++ })++ // Havok needs the explicit TELEPORT prestep dance for this to land at++ // all (havokWorld.ts:179-185, marked CRITICAL); a regression here means++ // remote players silently stop being collidable.++ w.setTransform(mirror, vec3(9, 1, 4))++ const p = pos()++ w.getTransform(mirror, p, rot())++ expect(p.x).toBeCloseTo(9, 3)++ expect(p.y).toBeCloseTo(1, 3)++ expect(p.z).toBeCloseTo(4, 3)++ close()++ })++++ it('setTransform teleports a DYNAMIC body', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))++ w.setTransform(box, vec3(-5, 4, 0))++ const p = pos()++ w.getTransform(box, p, rot())++ expect(p.x).toBeCloseTo(-5, 3)++ expect(p.y).toBeCloseTo(4, 3)++ close()++ })++++ it('setTransform on a kinematic body is adopted on the next step', () => {++ const w = open()++ const k = w.addBody({++ shape: { type: 'capsule', radius: 0.4, height: 1.8 },++ motion: 'kinematic',++ pos: vec3(0, 1, 0),++ layer: CollisionLayer.Player,++ collidesWith: 0,++ })++ w.setTransform(k, vec3(12, 1, 0))++ w.step(DT)++ const p = pos()++ w.getTransform(k, p, rot())++ expect(p.x).toBeGreaterThan(0.5)++ expect(p.x).toBeLessThanOrEqual(12.001)++ close()++ })++++ it('setTransform also writes the rotation when one is given', () => {++ const w = open()++ const b = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setTransform(b, vec3(0, 900, 0), quat(0, 0, 1, 0))++ const q = rot()++ w.getTransform(b, pos(), q)++ expect(q.z).toBeCloseTo(1, 3)++ expect(q.w).toBeCloseTo(0, 3)++ close()++ })++++ // ── motion types ────────────────────────────────────────────────────────++++ it('setMotionType freezes a dynamic body where it stands', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))++ stepFor(w, 30)++ w.setMotionType(box, 'static')++ const frozen = pos()++ w.getTransform(box, frozen, rot())++ stepFor(w, 60)++ const after = pos()++ w.getTransform(box, after, rot())++ expect(after.y).toBeCloseTo(frozen.y, 1)++ close()++ })++++ it('a body made dynamic again falls under gravity', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))++ stepFor(w, 30)++ w.setMotionType(box, 'static')++ w.setMotionType(box, 'dynamic')++ const before = pos()++ w.getTransform(box, before, rot())++ stepFor(w, 20)++ const after = pos()++ w.getTransform(box, after, rot())++ expect(after.y).toBeLessThan(before.y - 0.5)++ close()++ })++++ it('setMotionType to the type it already has is a no-op', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setLinearVelocity(box, vec3(2, 0, 0))++ w.setMotionType(box, 'dynamic')++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(v.x).toBeCloseTo(2, 3)++ close()++ })++++ // ── velocities ──────────────────────────────────────────────────────────++++ it('linear velocity round-trips', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setLinearVelocity(box, vec3(6, 0, 0))++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(v.x).toBeCloseTo(6, 5)++ expect(v.y).toBeCloseTo(0, 5)++ expect(v.z).toBeCloseTo(0, 5)++ close()++ })++++ it('a body given a linear velocity travels that way when stepped', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setLinearVelocity(box, vec3(6, 0, 0))++ stepFor(w, 10)++ const p = pos()++ w.getTransform(box, p, rot())++ expect(p.x).toBeGreaterThan(0.5)++ close()++ })++++ it('angular velocity round-trips', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setAngularVelocity(box, vec3(0, 2, 0))++ const v = pos()++ w.getAngularVelocity(box, v)++ expect(v.y).toBeCloseTo(2, 5)++ close()++ })++++ it('writing zeros through the setters stops the body', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))++ w.setLinearVelocity(box, vec3(5, 0, 0))++ w.setAngularVelocity(box, vec3(1, 0, 0))++ w.setLinearVelocity(box, vec3(0, 0, 0))++ w.setAngularVelocity(box, vec3(0, 0, 0))++ const lv = pos()++ const av = pos()++ w.getLinearVelocity(box, lv)++ w.getAngularVelocity(box, av)++ expect(Math.hypot(lv.x, lv.y, lv.z)).toBeLessThan(0.01)++ expect(Math.hypot(av.x, av.y, av.z)).toBeLessThan(0.01)++ close()++ })++++ // ── settle / wake ───────────────────────────────────────────────────────++++ it('static and kinematic bodies are settled by definition', () => {++ const w = open()++ expect(w.isSettled(w.addBody(groundDesc()))).toBe(true)++ expect(++ w.isSettled(++ w.addBody({++ shape: { type: 'capsule', radius: 0.4, height: 1.8 },++ motion: 'kinematic',++ pos: vec3(0, 1, 0),++ layer: CollisionLayer.Player,++ collidesWith: 0,++ }),++ ),++ ).toBe(true)++ close()++ })++++ it('wake does not change a parked body velocity', () => {++ const w = open()++ const box = addParkedBody(w, vec3(0, 900, 0))++ // Half the linear settle threshold: comfortably settled before and after,++ // so the assertion reads the adapter's threshold rather than a literal.++ // `toBeLessThanOrEqual` carries 1e-6 of slack because Havok stores velocity++ // in f32 and 0.025 does not round-trip exactly.++ const subThreshold = 0.025++ w.setLinearVelocity(box, vec3(subThreshold, 0, 0))++ expect(w.isSettled(box)).toBe(true)++ w.wake(box)++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(Math.hypot(v.x, v.y, v.z)).toBeLessThanOrEqual(subThreshold + 1e-6)++ close()++ })++++ it('wake on a non-dynamic body is a no-op, not a throw', () => {++ const w = open()++ const g = w.addBody(groundDesc())++ expect(() => w.wake(g)).not.toThrow()++ const p = pos()++ w.getTransform(g, p, rot())++ expect(p.y).toBeCloseTo(-0.5, 3)++ close()++ })++++ // ── raycast ─────────────────────────────────────────────────────────────++++ it('raycast returns the body, point, normal and a 0..1 fraction', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))++ w.addBody(groundDesc())++ stepFor(w, 30)++ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)++ expect(hit).not.toBeNull()++ expect(hit?.bodyId).toBe(box)++ // The segment is 10 long and the near face is at x = 1 → 4 m travelled.++ expect(hit?.fraction).toBeCloseTo(0.4, 3)++ expect(hit?.point.x).toBeCloseTo(1, 2)++ expect(hit?.normal.x).toBeCloseTo(1, 2)++ close()++ })++++ it('raycast filters by the body layer the mask names', () => {++ const w = open()++ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))++ const along = (mask: number): number | null =>++ w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), mask)?.fraction ?? null++ expect(along(CollisionLayer.Prop)).not.toBeNull()++ expect(along(CollisionLayer.Static)).toBeNull()++ expect(along(CollisionLayer.Static | CollisionLayer.Prop)).not.toBeNull()++ close()++ })++++ it('raycast misses cleanly when nothing is in the way', () => {++ const w = open()++ w.addBody(groundDesc())++ expect(w.raycast(vec3(0, 50, 0), vec3(0, 40, 0), CollisionLayer.Static)).toBeNull()++ close()++ })++++ it('raycast takes the first hit along the segment', () => {++ const w = open()++ w.addBody(groundDesc())++ const near = w.addBody(dynamicBoxDesc(vec3(3, 1, 0), 1, 10))++ w.addBody(dynamicBoxDesc(vec3(-3, 1, 0), 1, 10))++ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)++ expect(hit?.bodyId).toBe(near)++ close()++ })++++ it.skipIf(maybe('raycast reports'))(++ 'raycast reports the surface point, not the travelled point',++ () => {++ // Measured on Havok: a ray 10 long hitting a box whose near face is at++ // x = 1 reports fraction 0.4 with the point on that face. The mock's++ // slab test reports the same, so this is pinned on both.++ const w = open()++ w.addBody(groundDesc())++ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))++ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)++ expect(hit?.fraction).toBeCloseTo(0.4, 3)++ expect(hit?.point.x).toBeCloseTo(1, 3)++ expect(hit?.point.y).toBeCloseTo(1, 3)++ close()++ },++ )++++ // ── capsule sweep ───────────────────────────────────────────────────────++++ it('sweepCapsule returns an upward normal when landing on ground', () => {++ const w = open()++ w.addBody(groundDesc())++ const hit = w.sweepCapsule(++ vec3(0, 5, 0),++ vec3(0, -1, 0),++ 0.4,++ 1.8,++ CollisionLayer.Static | CollisionLayer.Prop,++ )++ expect(hit).not.toBeNull()++ expect(hit?.normal.y).toBeGreaterThan(0.9)++ // The capsule bottom starts at 4.1 and lands at 0: 4.1 of a 6 m sweep.++ expect(hit?.fraction).toBeGreaterThan(0.5)++ expect(hit?.fraction).toBeLessThan(1)++ expect(hit?.point.y).toBeCloseTo(0, 1)++ close()++ })++++ it('sweepCapsule returns null when the path is clear', () => {++ const w = open()++ w.addBody(groundDesc())++ expect(++ w.sweepCapsule(vec3(0, 5, 0), vec3(0, 4, 0), 0.4, 1.8, CollisionLayer.Static),++ ).toBeNull()++ close()++ })++++ it('sweepCapsule filters by the collision mask', () => {++ const w = open()++ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))++ const sweep = (mask: number) => w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask)++ expect(sweep(CollisionLayer.Static)).toBeNull()++ expect(sweep(CollisionLayer.Static | CollisionLayer.Prop)).not.toBeNull()++ close()++ })++++ it('sweepCapsule skips the excluded body and hits another one', () => {++ const w = open()++ const self = w.addBody({++ shape: { type: 'capsule', radius: 0.4, height: 1.8 },++ motion: 'kinematic',++ pos: vec3(0, 1, 0),++ layer: CollisionLayer.Player,++ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,++ })++ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))++ const mask = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player++ expect(w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask)).not.toBeNull()++ // The player's own kinematic capsule is on the Player layer and collides++ // with Player, so without the exclusion it would be the first hit.++ expect(w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask, self)).not.toBeNull()++ close()++ })++++ it('sweepCapsule fraction grows with the distance to the obstacle', () => {++ const w = open()++ w.addBody(groundDesc())++ const near = w.sweepCapsule(vec3(0, 3, 0), vec3(0, -1, 0), 0.4, 1.8, CollisionLayer.Static)++ const far = w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, CollisionLayer.Static)++ expect(near).not.toBeNull()++ expect(far!.fraction).toBeGreaterThan(near!.fraction)++ close()++ })++++ it('sweepCapsule reports a horizontal normal against a wall', () => {++ const w = open()++ w.addBody({++ shape: { type: 'box', size: [1, 4, 10] },++ motion: 'static',++ pos: vec3(2, 2, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Player | CollisionLayer.Prop,++ })++ const hit = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static)++ expect(hit).not.toBeNull()++ expect(Math.abs(hit!.normal.x)).toBeGreaterThan(0.9)++ expect(Math.abs(hit!.normal.y)).toBeLessThan(0.2)++ close()++ })++++ it.skipIf(maybe('sweepCapsule offsetting'))(++ 'sweepCapsule offsetting by the radius keeps a capsule out of a wall',++ () => {++ // Measured on Havok: a fat capsule and a thin one both report the++ // surface point x = 1.5 (the wall face), but the fat one stops 0.35 m++ // earlier along the sweep, because its centre is further from the face.++ const w = open()++ w.addBody({++ shape: { type: 'box', size: [1, 4, 10] },++ motion: 'static',++ pos: vec3(2, 2, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Player | CollisionLayer.Prop,++ })++ const fat = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static)++ const thin = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.05, 1.8, CollisionLayer.Static)++ expect(fat).not.toBeNull()++ expect(thin).not.toBeNull()++ expect(fat!.point.x).toBeCloseTo(1.5, 2)++ expect(thin!.point.x).toBeCloseTo(1.5, 2)++ expect(fat!.fraction).toBeLessThan(thin!.fraction)++ close()++ },++ )++++ // ── constraints ─────────────────────────────────────────────────────────++++ it.skipIf(maybe('a weld holds'))(++ 'a weld holds its pair in the creation-time relative pose',++ () => {++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ // Weld BEFORE the fall. Both boxes are the same size on the same floor,++ // so once they settle they sit side by side at the same height and the++ // creation-time offset would be zero — the mock has no contact solver++ // to stack them, and a fixture that depends on stacking only works on++ // an engine that has one. Welding while B is genuinely above A pins the++ // offset (0.5) that the rest of the case is about.++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 30)++ const pa = pos()++ const pb = pos()++ const q = rot()++ w.getTransform(a, pa, q)++ w.getTransform(b, pb, q)++ const dy0 = pb.y - pa.y++ expect(dy0).toBeGreaterThan(0.3)++ expect(dy0).toBeLessThan(0.75)++ // Give the pair a shove and let it settle again: the offset must hold.++ w.setLinearVelocity(a, vec3(4, 0, 0))++ stepFor(w, 90)++ w.getTransform(a, pa, rot())++ w.getTransform(b, pb, rot())++ expect(Math.abs(pb.x - pa.x)).toBeLessThan(0.25)++ expect(pb.y - pa.y).toBeGreaterThan(0.3)++ expect(pb.y - pa.y).toBeLessThan(0.75)++ w.removeConstraint(weld)++ close()++ },++ )++++ it.skipIf(maybe('a welded pair resists'))(++ 'a welded pair resists a velocity change on one member',++ () => {++ // Havok pulls a welded pair back over a couple of steps rather than++ // letting one half run away: a 6 m/s kick on the upper box decays to++ // 1.6 m/s within five steps and the pair is back at its offset by 60.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ const pb = pos()++ w.setLinearVelocity(b, vec3(0, 6, 0))++ stepFor(w, 5)++ w.getTransform(b, pb, rot())++ expect(pb.y).toBeLessThan(1.2)++ stepFor(w, 55)++ w.getTransform(b, pb, rot())++ expect(pb.y).toBeCloseTo(0.75, 1)++ close()++ },++ )++++ it.skipIf(maybe('removing a weld'))('removing a weld is a live handle, not a throw', () => {++ // Havok: the two joints stay rigidly posed after removal, because a++ // weld adds no energy and a stacked pair is already at rest. Asserted as++ // "the pair is unchanged and nothing throws" — what the pair does next is++ // Havok's business, not the seam's.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ const pa = pos()++ const pb = pos()++ w.getTransform(a, pa, rot())++ w.getTransform(b, pb, rot())++ expect(pa.y).toBeCloseTo(0.25, 2)++ expect(pb.y).toBeCloseTo(0.75, 2)++ w.removeConstraint(weld)++ expect(() => w.removeConstraint(weld)).not.toThrow()++ stepFor(w, 180)++ const p2 = pos()++ w.getTransform(a, p2, rot())++ expect(p2.y).toBeCloseTo(0.25, 2)++ close()++ })++++ it.skipIf(maybe('a welded island'))(++ 'a welded island stays rigid when a member is displaced',++ () => {++ // Measured on Havok: teleporting the follower of a weld drags the++ // island along it over the following steps rather than instantly.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ const pa = pos()++ const pb = pos()++ // A purely lateral nudge: same height, so it neither buries the pair in++ // the ground nor drives the solver a huge positional error in one step.++ // Teleporting B far away (e.g. to x = 6, y = 2) drags the whole island++ // through the ground, and what comes back out is the solver untangling++ // that error, not the weld.++ w.setTransform(b, vec3(0, 0.75, 0.5))++ w.step(DT)++ w.getTransform(a, pa, rot())++ w.getTransform(b, pb, rot())++ // The weld pulled B back toward A's pose rather than leaving it where it++ // was dropped, and A began to follow B instead of staying put.++ expect(pb.z).toBeLessThan(0.5)++ expect(pa.z).toBeGreaterThan(0)++ // "Stays rigid" is the claim worth pinning. Measured on Havok, the++ // island does not snap back within one step — it keeps sliding for a++ // while — but it never tears: after settling the vertical offset it was++ // welded with is intact and the lateral displacement has closed, so++ // the nudge was absorbed by the island rather than by the joint++ // stretching.++ stepFor(w, 60)++ w.getTransform(a, pa, rot())++ w.getTransform(b, pb, rot())++ expect(pb.y - pa.y).toBeCloseTo(0.5, 1)++ expect(pb.z - pa.z).toBeCloseTo(0, 1)++ close()++ },++ )++++ it('removing a weld frees the follower', () => {++ // What "freed" means at the seam: once the joint is gone the two bodies++ // are independent, so a velocity change on the follower moves the++ // follower and leaves the driver exactly where it was.++ //++ // It deliberately does NOT assert that the follower then rests at some++ // particular height. On a stacked pair resting on the ground that is++ // engine behaviour and the two engines disagree: the mock has no++ // body-body contacts, so the follower drops straight through back to the++ // floor (0.25) inside this window, while Havok's solver keeps it on the++ // driver and carries it to 1.609. Both are "no longer welded", which is++ // the property that belongs to the seam; a per-engine landing height is++ // pinned separately in each engine branch. Measured: with the pair++ // grounded and the follower kicked to +6 m/s after removal, Havok leaves++ // the driver at 0.250 and the follower at 1.609 after 30 steps; the mock++ // leaves the driver at 0.250 and the follower at 0.250, having already++ // arced up and landed back on the floor.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ w.removeConstraint(weld)++ const pa = pos()++ w.getTransform(a, pa, rot())++ expect(pa.y).toBeCloseTo(0.25, 2)++ w.setLinearVelocity(b, vec3(0, 6, 0))++ stepFor(w, 30)++ const pa2 = pos()++ const pb = pos()++ w.getTransform(a, pa2, rot())++ w.getTransform(b, pb, rot())++ // The driver did not move at all, and the follower has left the pose the++ // weld held it in (0.75) — up on Havok, down through the missing contact++ // on the mock. A still-welded follower could not do either.++ expect(pa2.y).toBeCloseTo(0.25, 2)++ expect(Math.abs(pb.y - 0.75)).toBeGreaterThan(0.1)++ close()++ })++++ // Mock-only, so gated on the adapter itself rather than through `maybe`:++ // `skip` lists what the MOCK cannot do, not what this case is good for.++ it.skipIf(a.name !== 'MockPhysicsWorld')(++ 'a freed follower lands on the floor once it has arced up (mock only)',++ () => {++ // The mock half of the case above, pinned on its own number. With no++ // body-body contacts the follower falls straight through the driver and++ // is caught by the ground plane, so it settles beside it rather than on++ // top of it. Havok's solver stacks them, so this cannot be shared.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ w.removeConstraint(weld)++ w.setLinearVelocity(b, vec3(0, 6, 0))++ // Enough steps to arc up and come back down: 6 m/s against -16.5 m/s² is++ // ~1.1 s of flight, which is 33 steps at the 30 Hz tick.++ stepFor(w, 90)++ const pb = pos()++ w.getTransform(b, pb, rot())++ expect(pb.y).toBeCloseTo(0.25, 2)++ expect(w.isSettled(b)).toBe(true)++ close()++ },++ )++++ it('setConstraintMotor on a weld, or on an unknown id, is a silent no-op', () => {++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.26, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.78, 0), 0.5, 10))++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ expect(() => w.setConstraintMotor(weld, { targetVelocity: 9, maxForce: 100 })).not.toThrow()++ expect(() =>++ w.setConstraintMotor(999_999, { targetVelocity: 9, maxForce: 100 }),++ ).not.toThrow()++ stepFor(w, 60)++ close()++ })++++ it.skipIf(maybe('a rope'))('a rope is slack below its length and taut at it', () => {++ const w = open()++ w.addBody(groundDesc())++ const anchor = w.addBody({++ shape: { type: 'box', size: [0.4, 0.4, 0.4] },++ motion: 'static',++ pos: vec3(0, 6, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const bob = w.addBody(dynamicBoxDesc(vec3(1.5, 6, 0), 0.4, 10))++ const rope = w.addConstraint({++ type: 'rope',++ bodyA: anchor,++ bodyB: bob,++ anchorA: vec3(),++ anchorB: vec3(),++ length: 2,++ })++ let maxDist = 0++ let minY = Infinity++ const p = pos()++ for (let i = 0; i < 300; i++) {++ w.step(DT)++ w.getTransform(bob, p, rot())++ maxDist = Math.max(maxDist, Math.hypot(p.x, p.y - 6, p.z))++ minY = Math.min(minY, p.y)++ }++ expect(maxDist).toBeLessThanOrEqual(2.3)++ // A taut 2 m pendulum swings through ~4 m below a 6 m anchor.++ expect(minY).toBeLessThanOrEqual(4.6)++ w.removeConstraint(rope)++ close()++ })++++ it.skipIf(maybe('a hinge'))('a hinge with limits caps the swing and holds the door up', () => {++ const w = open()++ w.addBody(groundDesc())++ const post = w.addBody({++ shape: { type: 'box', size: [0.4, 0.4, 0.4] },++ motion: 'static',++ pos: vec3(10, 2, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const door = w.addBody(dynamicBoxDesc(vec3(10.9, 2, 0), 0.4, 10))++ w.addConstraint({++ type: 'hinge',++ bodyA: post,++ bodyB: door,++ anchorA: vec3(0.45, 0, 0),++ anchorB: vec3(-0.45, 0, 0),++ axisA: vec3(0, 1, 0),++ axisB: vec3(0, 1, 0),++ limits: { min: -Math.PI / 4, max: Math.PI / 4 },++ })++ w.setLinearVelocity(door, vec3(0, 0, 8))++ const p = pos()++ let maxAngle = 0++ for (let i = 0; i < 90; i++) {++ w.step(DT)++ w.getTransform(door, p, rot())++ maxAngle = Math.max(maxAngle, Math.abs(Math.atan2(p.z, p.x - 10)))++ }++ expect(maxAngle).toBeGreaterThan(0.2)++ expect(maxAngle).toBeLessThanOrEqual(Math.PI / 4 + 0.25)++ w.getTransform(door, p, rot())++ expect(Math.abs(p.y - 2)).toBeLessThan(0.25)++ close()++ })++++ it.skipIf(maybe('a motorized hinge'))(++ 'a motorized hinge spins a wheel up and retunes to brake it',++ () => {++ const w = open()++ const mount = w.addBody({++ shape: { type: 'box', size: [0.4, 0.4, 0.4] },++ motion: 'static',++ pos: vec3(20, 3, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const wheel = w.addBody({++ shape: { type: 'cylinder', radius: 0.6, height: 0.2 },++ motion: 'dynamic',++ pos: vec3(20, 3, 0.4),++ massKg: 8,++ layer: CollisionLayer.Prop,++ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,++ })++ const motorId = w.addConstraint({++ type: 'hinge',++ bodyA: mount,++ bodyB: wheel,++ anchorA: vec3(0, 0, 0.4),++ anchorB: vec3(0, 0, 0),++ axisA: vec3(0, 0, 1),++ axisB: vec3(0, 1, 0), // a Babylon cylinder's own axis is +Y++ motor: { targetVelocity: 6, maxForce: 500 },++ })++ stepFor(w, 90)++ const av = pos()++ w.getAngularVelocity(wheel, av)++ expect(Math.hypot(av.x, av.y, av.z)).toBeGreaterThan(4)++ w.setConstraintMotor(motorId, { targetVelocity: 0, maxForce: 500 })++ stepFor(w, 60)++ w.getAngularVelocity(wheel, av)++ expect(Math.hypot(av.x, av.y, av.z)).toBeLessThan(0.5)++ close()++ },++ )++++ it.skipIf(maybe('a slider'))(++ 'a slider travels along its rail, respects its limits and stays on it',++ () => {++ const w = open()++ w.addBody(groundDesc())++ const rail = w.addBody({++ shape: { type: 'box', size: [0.4, 0.4, 0.4] },++ motion: 'static',++ pos: vec3(30, 2, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const drawer = w.addBody(dynamicBoxDesc(vec3(30, 2, 0.6), 0.4, 10))++ w.addConstraint({++ type: 'slider',++ bodyA: rail,++ bodyB: drawer,++ anchorA: vec3(0, 0, 0.6),++ anchorB: vec3(0, 0, 0),++ axisA: vec3(0, 0, 1),++ axisB: vec3(0, 0, 1),++ limits: { min: -0.5, max: 1.0 },++ })++ w.setLinearVelocity(drawer, vec3(0, 0, 5))++ const p = pos()++ let maxZ = -Infinity++ let minZ = Infinity++ let maxOffAxis = 0++ for (let i = 0; i < 120; i++) {++ w.step(DT)++ w.getTransform(drawer, p, rot())++ maxZ = Math.max(maxZ, p.z)++ minZ = Math.min(minZ, p.z)++ maxOffAxis = Math.max(maxOffAxis, Math.abs(p.x - 30), Math.abs(p.y - 2))++ if (i === 60) w.setLinearVelocity(drawer, vec3(0, 0, -5))++ }++ expect(maxZ).toBeGreaterThan(1.3)++ expect(maxZ).toBeLessThanOrEqual(1.85)++ expect(minZ).toBeGreaterThanOrEqual(-0.15)++ expect(maxOffAxis).toBeLessThanOrEqual(0.15)++ close()++ },++ )++++ it.skipIf(maybe('a spring'))('a spring settles at roughly its rest length', () => {++ const w = open()++ w.addBody(groundDesc())++ const mount = w.addBody({++ shape: { type: 'box', size: [0.4, 0.4, 0.4] },++ motion: 'static',++ pos: vec3(40, 6, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const bob = w.addBody(dynamicBoxDesc(vec3(40, 5.5, 0), 0.4, 10))++ w.addConstraint({++ type: 'spring',++ bodyA: mount,++ bodyB: bob,++ anchorA: vec3(),++ anchorB: vec3(),++ restLength: 1.5,++ stiffness: 400,++ damping: 15,++ })++ stepFor(w, 300)++ const p = pos()++ w.getTransform(bob, p, rot())++ const dist = Math.hypot(p.x - 40, p.y - 6, p.z)++ expect(dist).toBeGreaterThan(1.2)++ expect(dist).toBeLessThan(2.2)++ close()++ })++++ it('every constraint variant is accepted and keeps a live handle', () => {++ const w = open()++ w.addBody(groundDesc())++ const mk = (y: number) => w.addBody(dynamicBoxDesc(vec3(100, y, 0), 0.4, 10))++ const a = mk(1)++ const b = mk(2)++ const ids = [++ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b }),++ w.addConstraint({++ type: 'rope',++ bodyA: a,++ bodyB: b,++ anchorA: vec3(),++ anchorB: vec3(),++ length: 2,++ collision: false,++ }),++ w.addConstraint({++ type: 'hinge',++ bodyA: a,++ bodyB: b,++ anchorA: vec3(),++ anchorB: vec3(),++ axisA: vec3(0, 1, 0),++ axisB: vec3(0, 1, 0),++ limits: { min: -1, max: 1 },++ friction: 0.1,++ motor: { targetVelocity: 1, maxForce: 10 },++ }),++ w.addConstraint({++ type: 'slider',++ bodyA: a,++ bodyB: b,++ anchorA: vec3(),++ anchorB: vec3(),++ axisA: vec3(0, 0, 1),++ axisB: vec3(0, 0, 1),++ motor: { targetVelocity: 1, maxForce: 10 },++ }),++ w.addConstraint({++ type: 'spring',++ bodyA: a,++ bodyB: b,++ anchorA: vec3(),++ anchorB: vec3(),++ restLength: 1,++ stiffness: 100,++ damping: 5,++ }),++ ]++ expect(new Set(ids).size).toBe(ids.length)++ for (const id of ids) {++ expect(() => w.setConstraintMotor(id, { targetVelocity: 0, maxForce: 1 })).not.toThrow()++ expect(() => w.removeConstraint(id)).not.toThrow()++ }++ close()++ })++++ // ── disposal ────────────────────────────────────────────────────────────++++ it('dispose is safe after bodies have already been removed', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 2, 0)))++ const other = w.addBody(dynamicBoxDesc(vec3(2, 2, 0)))++ w.addConstraint({ type: 'weld', bodyA: box, bodyB: other })++ w.removeBody(box)++ expect(() => w.dispose()).not.toThrow()++ expect(() => w.dispose()).not.toThrow()++ world = null++ })++++ // ── engine-independent constants ─────────────────────────────────────────++ // These must hold for every adapter, so they run for both worlds. The++ // acceleration-shaped ones are additionally pinned in the engine describe++ // below, where the numbers have been measured.++++ describe('seam constants', () => {++ it('settle thresholds sit between 0.01 and 0.1 m/s, and 0.1 and 0.2 rad/s', () => {++ // The thresholds are read back through the adapter under test, not off++ // a literal: this case is about WHERE the seam's threshold lies, which++ // is what the game is tuned against. Exactly-at-the-boundary behaviour++ // is deliberately not pinned (header note 2: Havok compares len² >++ // threshold² against an f32, so a body at exactly 0.05 is reported++ // unsettled there and settled on the mock).++ const w = open()++ // Just inside both thresholds: settled.++ const inside = addParkedBody(w, vec3(0, 900, 0))++ w.setLinearVelocity(inside, vec3(0.01, 0, 0))++ w.setAngularVelocity(inside, vec3(0, 0.1, 0))++ expect(w.isSettled(inside)).toBe(true)++ // Comfortably above either one: not settled.++ const fast = addParkedBody(w, vec3(50, 900, 0))++ w.setLinearVelocity(fast, vec3(1, 0, 0))++ expect(w.isSettled(fast)).toBe(false)++ const spinning = addParkedBody(w, vec3(100, 900, 0))++ w.setAngularVelocity(spinning, vec3(0, 1, 0))++ expect(w.isSettled(spinning)).toBe(false)++ // Just over each threshold: not settled. 0.06 and 0.16 sit a clear++ // f32 step above 0.05 and 0.15 without landing on the boundary.++ const justOverLinear = addParkedBody(w, vec3(150, 900, 0))++ w.setLinearVelocity(justOverLinear, vec3(0.06, 0, 0))++ expect(w.isSettled(justOverLinear)).toBe(false)++ const justOverAngular = addParkedBody(w, vec3(200, 900, 0))++ w.setAngularVelocity(justOverAngular, vec3(0, 0.16, 0))++ expect(w.isSettled(justOverAngular)).toBe(false)++ close()++ })++++ it('gravity is (0, -16.5, 0) m/s^2', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ w.setLinearVelocity(box, vec3(0, 0, 0))++ // Two seconds of free fall, asked for in simulated seconds because the++ // two engines advance by different amounts per step(): the mock reaches++ // -29.9 m/s in 60 steps of 1/30 s, the Havok plugin -31.4 m/s in 120++ // steps of its fixed 1/60 s. Either way it is nowhere near a 9.81 m/s²++ // world, which would be -19.++ stepSecondsFor(a, w, 2)++ const v = pos()++ w.getLinearVelocity(box, v)++ // The window is the two-second band both engines land inside; it would++ // not survive a 9.81 m/s² world, which would be -19.++ expect(v.y).toBeLessThan(-29)++ expect(v.y).toBeGreaterThan(-34)++ close()++ })++++ it('restitution is near zero: a dropped box does not bounce', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 8, 0), 0.7, 25))++ let landedAt = -Infinity++ for (let i = 0; i < 300; i++) {++ w.step(DT)++ const p = pos()++ w.getTransform(box, p, rot())++ if (p.y < 0.36) {++ landedAt = p.y++ break++ }++ }++ expect(landedAt).not.toBe(-Infinity)++ stepFor(w, 30)++ const p = pos()++ w.getTransform(box, p, rot())++ // A restitution of 0.05 cannot lift a 25 kg box more than a whisker.++ expect(p.y).toBeLessThan(landedAt + 0.35)++ expect(p.y).toBeLessThan(0.5)++ close()++ })++ })++++ // ── engine-specific dynamics ────────────────────────────────────────────++ // These assert the numeric feel the game is tuned against. The mock's++ // values are exact by construction, so they are marked separately from the++ // Havok numbers where the two genuinely differ.++++ if (a.name === 'MockPhysicsWorld') {++ it('exposes the same seam constants the Havok adapter is built from', () => {++ // The shared cases above read gravity and the settle thresholds back++ // through the adapter, so they cannot see a literal drift in either++ // one. This pins the mock's own values against the numbers measured off++ // havokWorld.ts (the header block's list), so the two adapters stay++ // declared to the same constants and the shared cases mean something.++ expect(MOCK_GRAVITY).toBe(-16.5)++ expect(MOCK_SETTLE_LINEAR).toBe(0.05)++ expect(MOCK_SETTLE_ANGULAR).toBe(0.15)++ })++++ it('applies its own gravity, damping and mass, exactly', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ // Semi-implicit Euler at 30 Hz: v += g·dt, then v *= (1 - 0.05·dt).++ // Two seconds is -16.5 × 2 = -33 before the damping losses.++ for (let i = 0; i < 60; i++) w.step(MOCK_TICK)++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(v.y).toBeLessThan(-29)++ expect(v.y).toBeGreaterThan(-33)++ close()++ })++++ it('a body rests on the analytic ground plane and settles', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))++ stepFor(w, 240)++ const p = pos()++ w.getTransform(box, p, rot())++ expect(p.y).toBeCloseTo(0.35, 3)++ expect(w.isSettled(box)).toBe(true)++ close()++ })++++ it('a body in free fall is never settled', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 500, 0)))++ stepFor(w, 30)++ expect(w.isSettled(box)).toBe(false)++ close()++ })++++ it('a resting body carries no angular velocity once the ground stops it', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))++ w.setAngularVelocity(box, vec3(0, 5, 0))++ stepFor(w, 240)++ const v = pos()++ w.getAngularVelocity(box, v)++ expect(Math.hypot(v.x, v.y, v.z)).toBe(0)++ close()++ })++++ it('applyForce accelerates in the force direction and ignores non-dynamic bodies', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ const ground = w.addBody(groundDesc())++ for (let i = 0; i < 10; i++) {++ w.applyForce(box, vec3(10, 0, 0))++ w.step(DT)++ }++ const v = pos()++ w.getLinearVelocity(box, v)++ // a = F/m = 1 m/s^2 for 10 kg, so about 0.33 m/s after a third second.++ expect(v.x).toBeCloseTo(1 / 3, 1)++ w.applyForce(ground, vec3(1000, 0, 0))++ stepFor(w, 10)++ const p = pos()++ w.getTransform(ground, p, rot())++ expect(p.x).toBeCloseTo(0, 3)++ close()++ })++++ it('an analytic cast plane stops casts but not bodies', () => {++ const w = createMockPhysicsWorld()++ w.addCast({ normal: vec3(-1, 0, 0), offset: 2, minY: -1, maxY: 3 })++ expect(w.castCount()).toBe(1)++ expect(++ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),++ ).not.toBeNull()++ // No ground plane at all, so a body just keeps falling.++ const box = w.addBody(dynamicBoxDesc(vec3(-3, 10, 0), 0.5, 10))++ stepFor(w, 60)++ const p = pos()++ w.getTransform(box, p, rot())++ expect(p.y).toBeLessThan(0)++ close()++ })++++ it('a patched cast plane only hits inside its patch', () => {++ const w = createMockPhysicsWorld()++ w.addCast({ normal: vec3(-1, 0, 0), offset: 2, minY: -1, maxY: 3, minZ: -1, maxZ: 1 })++ expect(++ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),++ ).not.toBeNull()++ expect(++ w.sweepCapsule(vec3(-3, 1, 8), vec3(3, 1, 8), 0.4, 1.8, CollisionLayer.Static),++ ).toBeNull()++ expect(++ w.sweepCapsule(vec3(-3, 9, 0), vec3(3, 9, 0), 0.4, 1.8, CollisionLayer.Static),++ ).toBeNull()++ close()++ })++++ it('groundHeightAt reports the analytic plane, not a wall cast', () => {++ const w = createMockPhysicsWorld()++ w.addGroundPlane(0)++ w.markLastCastAsGround()++ w.addCast({ normal: vec3(-1, 0, 0), offset: 2 })++ expect(w.groundHeightAt(0, 0)).toBe(0)++ expect(++ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),++ ).not.toBeNull()++ close()++ })++++ it('is bit-identical across runs', () => {++ const run = (): number[] => {++ const w = createMockPhysicsWorld()++ w.addCast({ normal: vec3(0, 1, 0), offset: 0 })++ w.markLastCastAsGround()++ w.addCast({ normal: vec3(-1, 0, 0), offset: 2 })++ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))++ const out: number[] = []++ for (let i = 0; i < 200; i++) {++ w.setLinearVelocity(box, vec3(3 + Math.sin(i * 0.1), 0, 0))++ w.step(DT)++ const p = pos()++ w.getTransform(box, p, rot())++ out.push(p.x, p.y, p.z)++ }++ close()++ return out++ }++ expect(run()).toEqual(run())++ })++++ it('every case the mock skips still runs somewhere', async () => {++ // A `skip` entry naming a title that no longer exists silently skips++ // nothing, which is how the mock ended up running a case its header++ // claimed it could not model. Each prefix below must be a prefix of a++ // title this file actually defines; read them out of the source so the++ // check cannot go stale when a case is renamed or removed.++ const source = await readFile(new URL(import.meta.url), 'utf8')++ const titles = [++ ...source.matchAll(/\bit(?:\.skipIf\([\s\S]*?\)\s*)?\(\s*\n?\s*'([^']+)'/g),++ ].map((m) => m[1]!)++ expect(titles.length).toBeGreaterThan(40)++ const dead = MOCK_SKIP_PREFIXES.filter((p) => !titles.some((t) => t.startsWith(p)))++ expect(dead).toEqual([])++ })++ } else {++ it('a freed follower stays on the driver on Havok’s solver', () => {++ // The Havok half of "removing a weld frees the follower": the contact++ // solver keeps the upper box stacked on the lower one, so after the same++ // 30-step window the shared case finds it up at ~1.6 rather than back++ // down on the floor. Measured: 1.609.++ const w = open()++ w.addBody(groundDesc())++ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))++ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))++ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })++ stepFor(w, 60)++ w.removeConstraint(weld)++ w.setLinearVelocity(b, vec3(0, 6, 0))++ stepFor(w, 30)++ const pb = pos()++ w.getTransform(b, pb, rot())++ expect(pb.y).toBeGreaterThan(0.75)++ expect(pb.y).toBeLessThan(2)++ close()++ })++++ it.skipIf(maybe('step advances'))(++ 'step advances a fixed 1/60 s regardless of the dt passed (Havok plugin)',++ () => {++ const probe = (dt: number, ticks: number) => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ stepFor(w, ticks, dt)++ const v = pos()++ w.getLinearVelocity(box, v)++ close()++ return v.y++ }++ // 30 steps at 30 Hz and 30 steps at 15 Hz are the same amount of++ // simulated time, because the plugin uses its own fixed step time.++ expect(probe(1 / 30, 30)).toBeCloseTo(probe(1 / 15, 30), 3)++ // An extra second of simulation is very nearly twice the velocity.++ expect(probe(1 / 60, 120) / probe(1 / 60, 60)).toBeGreaterThan(1.9)++ expect(probe(1 / 60, 120) / probe(1 / 60, 60)).toBeLessThan(2.1)++ // One simulated second of this gravity: about -16.5 m/s.++ expect(probe(1 / 30, 60)).toBeLessThan(-15)++ expect(probe(1 / 30, 60)).toBeGreaterThan(-17)++ },++ )++++ it('a resting dynamic body on the ground settles', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 3, 0), 0.7, 25))++ stepFor(w, 240)++ expect(w.isSettled(box)).toBe(true)++ close()++ })++++ it('a body in free fall is never settled', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 500, 0)))++ stepFor(w, 30)++ expect(w.isSettled(box)).toBe(false)++ close()++ })++++ it('applyForce accelerates a dynamic body; static and kinematic are ignored', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 0.5, 10))++ w.setLinearVelocity(box, vec3(0, 0, 0))++ for (let i = 0; i < 60; i++) {++ w.applyForce(box, vec3(100, 0, 0))++ w.step(DT)++ }++ const p = pos()++ w.getTransform(box, p, rot())++ expect(p.x).toBeGreaterThan(0.3)++ const k = w.addBody({++ shape: { type: 'sphere', radius: 0.5 },++ motion: 'kinematic',++ pos: vec3(20, 5, 0),++ layer: CollisionLayer.Player,++ collidesWith: 0,++ })++ w.applyForce(k, vec3(500, 0, 0))++ stepFor(w, 30)++ const kp = pos()++ w.getTransform(k, kp, rot())++ expect(kp.x).toBeCloseTo(20, 3)++ close()++ })++++ it('mass scales the response to an equal force', () => {++ const w = open()++ const heavy = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 40))++ const light = w.addBody(dynamicBoxDesc(vec3(50, 900, 0), 0.5, 10))++ for (let i = 0; i < 20; i++) {++ w.applyForce(heavy, vec3(400, 0, 0))++ w.applyForce(light, vec3(400, 0, 0))++ w.step(DT)++ }++ const hv = pos()++ const lv = pos()++ w.getLinearVelocity(heavy, hv)++ w.getLinearVelocity(light, lv)++ expect(lv.x / Math.max(hv.x, 1e-9)).toBeGreaterThan(3)++ expect(lv.x / Math.max(hv.x, 1e-9)).toBeLessThan(5)++ close()++ })++++ it('linear damping is light (0.05): a coasting body keeps its speed', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ w.setLinearVelocity(box, vec3(10, 0, 0))++ stepFor(w, 30)++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(v.x).toBeGreaterThan(9.5)++ expect(v.x).toBeLessThan(10)++ close()++ })++++ it('angular damping is strong (0.6): a free spin decays within seconds', () => {++ const w = open()++ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))++ w.setAngularVelocity(box, vec3(0, 10, 0))++ stepFor(w, 60)++ const v = pos()++ w.getAngularVelocity(box, v)++ expect(v.y).toBeLessThan(6)++ expect(v.y).toBeGreaterThan(0)++ close()++ })++++ it('surface friction is high enough that a sliding box stops quickly', () => {++ const w = open()++ w.addBody(groundDesc())++ const box = w.addBody(dynamicBoxDesc(vec3(0, 0.36, 0), 0.7, 25))++ w.setLinearVelocity(box, vec3(10, 0, 0))++ stepFor(w, 180)++ const v = pos()++ w.getLinearVelocity(box, v)++ expect(Math.abs(v.x)).toBeLessThan(1.5)++ close()++ })++++ it('a body knocked off a ledge falls; the ledge does not move it sideways', () => {++ const w = open()++ w.addBody({++ shape: { type: 'box', size: [4, 1, 10] },++ motion: 'static',++ pos: vec3(0, 0.5, 0),++ layer: CollisionLayer.Static,++ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,++ })++ const box = w.addBody(dynamicBoxDesc(vec3(0, 2, 0), 0.7, 25))++ stepFor(w, 60)++ const resting = pos()++ w.getTransform(box, resting, rot())++ expect(resting.y).toBeCloseTo(1.35, 2)++ w.setLinearVelocity(box, vec3(8, 0, 0))++ stepFor(w, 90)++ const gone = pos()++ w.getTransform(box, gone, rot())++ expect(gone.y).toBeLessThan(0)++ close()++ })++ }++ })++}++++conformance(havokAdapter)++conformance(mockAdapter)nnew file mode 100644@@@ -0,0 +1,790 @@++import {++ quat,++ vec3,++ v3copy,++ v3dot,++ v3lengthSq,++ v3scale,++ v3set,++ type Quat,++ type Vec3,++} from '@openvibe/shared'++import {++ CollisionLayer,++ type BodyDesc,++ type BodyId,++ type ConstraintDesc,++ type ConstraintId,++ type ConstraintMotor,++ type MotionType,++ type PhysicsWorld,++ type RayHit,++ type SweepHit,++} from './types.js'++++/**++ * Deterministic, wasm-free PhysicsWorld for tests and for any consumer that++ * needs a collision oracle without an engine (ADR-0007 decision 2: the seam++ * must be testable without wasm, and the engine swap must be "tested, not++ * assumed").++ *++ * It is deliberately NOT a miniature physics engine:++ *++ * - **Analytic ground plane.** `addGroundPlane()` installs an infinite plane++ * y = 0 — the terrain the server builds — and capsule sweeps and rays resolve++ * against it exactly. `addCast()` adds further analytic surfaces (a wall, a++ * ceiling, a step) that only casts see; that is the scripted cast table.++ * - **Boxes, not rigid bodies.** Every shape is reduced to a world-axis-aligned++ * bounding box that never rotates, and nothing stacks. A body falls, lands and++ * rests; it does not push, roll, bounce off or topple anything.++ * - **Weld is real**, because it is the one constraint the prop-island and++ * settle bookkeeping depend on: members of a weld group move as one.++ * Rope, hinge, slider and spring keep live handles but exert no force.++ *++ * Everything is f64, iterated in insertion order, with no wall-clock time and++ * no hashing, so two runs of the same script are bit-identical. That is what++ * makes the mock usable as the movement determinism oracle.++ *++ * See conformance.test.ts ("what the mock deliberately does not model") for the++ * full list of gaps a real adapter must close.++ */++++/** 30 Hz — the tick rate both the server and client prediction run at. */++export const MOCK_TICK = 1 / 30++++export const MOCK_GRAVITY = -16.5++/** Must match the Havok adapter's settle thresholds (havokWorld.ts:72-73). */++export const MOCK_SETTLE_LINEAR = 0.05++export const MOCK_SETTLE_ANGULAR = 0.15++export const MOCK_DEFAULT_MASS_KG = 10++export const MOCK_MATERIAL = { friction: 0.75, staticFriction: 0.85, restitution: 0.05 } as const++export const MOCK_LINEAR_DAMPING = 0.05++export const MOCK_ANGULAR_DAMPING = 0.6++++interface MockBody {++ id: BodyId++ desc: BodyDesc++ motion: MotionType++ pos: Vec3++ rot: Quat++ linVel: Vec3++ angVel: Vec3++ /** Forces accumulated since the last step (seam semantics: applyForce is a force, not an impulse). */++ force: Vec3++ torque: Vec3++ massKg: number++ /** Axis-aligned half extents; a capsule is bounded by radius in x/z and height/2 in y. */++ half: Vec3++ /** Weld bookkeeping: the rigid group this body follows, if any. */++ weld: WeldGroup | null++}++++/** A rigid group of bodies linked by welds, with A as the driver. */++interface WeldGroup {++ driver: MockBody++ members: { body: MockBody; offset: Vec3 }[]++}++++interface MockConstraint {++ id: ConstraintId++ desc: ConstraintDesc++ motor: ConstraintMotor | null++}++++/** A castable analytic surface: { p : dot(n, p) = offset } clipped by an AABB patch. */++interface CastPlane {++ normal: Vec3++ offset: number++ patchMin: Vec3 | null++ patchMax: Vec3 | null++ /** Ground casts also stop bodies; a wall cast only stops casts. */++ isGround: boolean++}++++function setQuat(out: Quat, q: Quat | undefined): void {++ if (q) {++ out.x = q.x++ out.y = q.y++ out.z = q.z++ out.w = q.w++ } else {++ out.x = 0++ out.y = 0++ out.z = 0++ out.w = 1++ }++}++++/**++ * Half extents of a shape, axis-aligned about its centre. A capsule's radius++ * inflates x/z only; a trimesh collapses to its local bounds (the mock has no++ * triangle queries).++ */++function halfExtents(desc: BodyDesc): Vec3 {++ switch (desc.shape.type) {++ case 'box':++ return vec3(desc.shape.size[0] / 2, desc.shape.size[1] / 2, desc.shape.size[2] / 2)++ case 'sphere':++ return vec3(desc.shape.radius, desc.shape.radius, desc.shape.radius)++ case 'cylinder':++ case 'capsule':++ return vec3(desc.shape.radius, desc.shape.height / 2, desc.shape.radius)++ case 'trimesh': {++ const { positions } = desc.shape++ let minX = Infinity++ let minY = Infinity++ let minZ = Infinity++ let maxX = -Infinity++ let maxY = -Infinity++ let maxZ = -Infinity++ for (let i = 0; i + 2 < positions.length; i += 3) {++ if (positions[i]! < minX) minX = positions[i]!++ if (positions[i]! > maxX) maxX = positions[i]!++ if (positions[i + 1]! < minY) minY = positions[i + 1]!++ if (positions[i + 1]! > maxY) maxY = positions[i + 1]!++ if (positions[i + 2]! < minZ) minZ = positions[i + 2]!++ if (positions[i + 2]! > maxZ) maxZ = positions[i + 2]!++ }++ if (!Number.isFinite(minX)) return vec3()++ return vec3((maxX - minX) / 2, (maxY - minY) / 2, (maxZ - minZ) / 2)++ }++ }++}++++export class MockPhysicsWorld implements PhysicsWorld {++ private nextId: BodyId = 1++ private nextConstraintId: ConstraintId = 1++ /** Insertion-ordered on purpose: determinism, not lookup speed. */++ private readonly bodies = new Map<BodyId, MockBody>()++ private readonly constraints = new Map<ConstraintId, MockConstraint>()++ private readonly casts: CastPlane[] = []++ private disposed = false++++ step(dt: number): void {++ this.assertLive()++ for (const body of this.bodies.values()) {++ if (body.motion !== 'dynamic') continue++ const invMass = 1 / Math.max(body.massKg, 1e-6)++ body.linVel.x += body.force.x * invMass * dt++ body.linVel.y += MOCK_GRAVITY * dt + body.force.y * invMass * dt++ body.linVel.z += body.force.z * invMass * dt++ v3set(body.force, 0, 0, 0)++ body.angVel.x += body.torque.x * invMass * dt++ body.angVel.y += body.torque.y * invMass * dt++ body.angVel.z += body.torque.z * invMass * dt++ v3set(body.torque, 0, 0, 0)++ v3scale(body.linVel, body.linVel, Math.max(0, 1 - MOCK_LINEAR_DAMPING * dt))++ v3scale(body.angVel, body.angVel, Math.max(0, 1 - MOCK_ANGULAR_DAMPING * dt))++ body.pos.x += body.linVel.x * dt++ body.pos.y += body.linVel.y * dt++ body.pos.z += body.linVel.z * dt++ }++ this.resolveContacts()++ this.poseWeldGroups()++ }++++ addBody(desc: BodyDesc): BodyId {++ this.assertLive()++ const id = this.nextId++++ const body: MockBody = {++ id,++ desc,++ motion: desc.motion,++ pos: vec3(desc.pos.x, desc.pos.y, desc.pos.z),++ rot: quat(),++ linVel: vec3(),++ angVel: vec3(),++ force: vec3(),++ torque: vec3(),++ massKg: desc.massKg ?? MOCK_DEFAULT_MASS_KG,++ half: halfExtents(desc),++ weld: null,++ }++ setQuat(body.rot, desc.rot)++ this.bodies.set(id, body)++ return id++ }++++ removeBody(id: BodyId): void {++ const body = this.bodies.get(id)++ if (!body) return++ this.bodies.delete(id)++ // Any group this body belonged to loses it; a group left with no members is++ // dropped, so the survivors become independent again.++ for (const other of this.bodies.values()) {++ const group = other.weld++ if (!group) continue++ if (group.driver === body) other.weld = null++ else group.members = group.members.filter((m) => m.body !== body)++ }++ }++++ getTransform(id: BodyId, outPos: Vec3, outRot: Quat): void {++ const body = this.mustGet(id)++ v3copy(outPos, body.pos)++ setQuat(outRot, body.rot)++ }++++ setTransform(id: BodyId, pos: Vec3, rot?: Quat): void {++ const body = this.mustGet(id)++ const group = body.weld++ if (group) {++ // Moving any member moves the whole island rigidly, exactly as a weld does.++ const dx = pos.x - body.pos.x++ const dy = pos.y - body.pos.y++ const dz = pos.z - body.pos.z++ v3set(++ group.driver.pos,++ group.driver.pos.x + dx,++ group.driver.pos.y + dy,++ group.driver.pos.z + dz,++ )++ this.poseWeldGroups()++ }++ if (!group) v3copy(body.pos, pos)++ if (rot) setQuat(body.rot, rot)++ }++++ setMotionType(id: BodyId, motion: MotionType): void {++ const body = this.mustGet(id)++ if (body.motion === motion) return++ body.motion = motion++ if (motion !== 'dynamic') {++ // Matches the Havok adapter: freezing a body drops its motion.++ v3set(body.linVel, 0, 0, 0)++ v3set(body.angVel, 0, 0, 0)++ v3set(body.force, 0, 0, 0)++ v3set(body.torque, 0, 0, 0)++ }++ }++++ getLinearVelocity(id: BodyId, out: Vec3): void {++ v3copy(out, this.mustGet(id).linVel)++ }++++ setLinearVelocity(id: BodyId, v: Vec3): void {++ v3copy(this.mustGet(id).linVel, v)++ }++++ getAngularVelocity(id: BodyId, out: Vec3): void {++ v3copy(out, this.mustGet(id).angVel)++ }++++ setAngularVelocity(id: BodyId, v: Vec3): void {++ v3copy(this.mustGet(id).angVel, v)++ }++++ isSettled(id: BodyId): boolean {++ const body = this.mustGet(id)++ if (body.motion !== 'dynamic') return true++ if (v3lengthSq(body.linVel) > MOCK_SETTLE_LINEAR * MOCK_SETTLE_LINEAR) return false++ return v3lengthSq(body.angVel) <= MOCK_SETTLE_ANGULAR * MOCK_SETTLE_ANGULAR++ }++++ wake(id: BodyId): void {++ // Dynamic-only, exactly like the Havok adapter. Waking is not an impulse,++ // so there is deliberately nothing to do.++ const body = this.mustGet(id)++ if (body.motion !== 'dynamic') return++ }++++ addConstraint(desc: ConstraintDesc): ConstraintId {++ this.assertLive()++ const a = this.mustGet(desc.bodyA)++ const b = this.mustGet(desc.bodyB)++ const id = this.nextConstraintId++++ const motor = desc.type === 'hinge' || desc.type === 'slider' ? (desc.motor ?? null) : null++ this.constraints.set(id, { id, desc, motor })++ if (desc.type === 'weld') {++ // Weld preserves the creation-time relative pose: every member becomes a++ // rigid follower of A at the offset it had when the joint was made.++ const group: WeldGroup = {++ driver: a,++ members: [++ { body: b, offset: vec3(b.pos.x - a.pos.x, b.pos.y - a.pos.y, b.pos.z - a.pos.z) },++ ],++ }++ b.weld = group++ }++ return id++ }++++ removeConstraint(id: ConstraintId): void {++ const rec = this.constraints.get(id)++ if (!rec) return++ this.constraints.delete(id)++ if (rec.desc.type === 'weld') {++ const body = this.bodies.get(rec.desc.bodyB)++ if (body?.weld) body.weld = null++ }++ }++++ setConstraintMotor(id: ConstraintId, motor: ConstraintMotor): void {++ const rec = this.constraints.get(id)++ if (!rec) return++ if (rec.desc.type !== 'hinge' && rec.desc.type !== 'slider') return++ rec.motor = { targetVelocity: motor.targetVelocity, maxForce: motor.maxForce }++ }++++ /** The motor currently configured on a hinge/slider, or null. Test introspection. */++ getConstraintMotor(id: ConstraintId): ConstraintMotor | null {++ return this.constraints.get(id)?.motor ?? null++ }++++ applyForce(id: BodyId, force: Vec3): void {++ const body = this.mustGet(id)++ if (body.motion !== 'dynamic') return++ body.force.x += force.x++ body.force.y += force.y++ body.force.z += force.z++ }++++ raycast(from: Vec3, to: Vec3, collidesWith: number): RayHit | null {++ this.assertLive()++ const d = vec3(to.x - from.x, to.y - from.y, to.z - from.z)++ const length = Math.sqrt(v3lengthSq(d))++ let best: RayHit | null = null++ for (const body of this.bodies.values()) {++ if (!(body.desc.layer & collidesWith)) continue++ const hit = rayAabb(from, d, length, body.pos, body.half)++ if (!hit) continue++ if (!best || hit.fraction < best.fraction) {++ best = { bodyId: body.id, point: hit.point, normal: hit.normal, fraction: hit.fraction }++ }++ }++ for (const plane of this.casts) {++ const hit = rayPlane(from, d, length, plane)++ if (!hit) continue++ if (best && best.fraction <= hit.fraction) continue++ best = {++ bodyId: MOCK_CAST_BODY_ID,++ point: hit.point,++ normal: hit.normal,++ fraction: hit.fraction,++ }++ }++ return best++ }++++ sweepCapsule(++ from: Vec3,++ to: Vec3,++ radius: number,++ height: number,++ collidesWith: number,++ exclude?: BodyId,++ ): SweepHit | null {++ this.assertLive()++ const d = vec3(to.x - from.x, to.y - from.y, to.z - from.z)++ // `height` is the capsule's TOTAL height including both caps (types.ts:170),++ // so the cylindrical segment runs height/2 - radius either side of centre —++ // the same conversion HavokWorld.getSweepShape makes (havokWorld.ts:533).++ const half = Math.max(height / 2 - radius, 0.01)++ let best: SweepHit | null = null++ const consider = (fraction: number, normal: Vec3, point: Vec3): void => {++ if (fraction < -1e-9 || fraction > 1 + 1e-9) return++ const f = Math.min(Math.max(fraction, 0), 1)++ if (best && f >= best.fraction) return++ best = { fraction: f, normal: vec3(normal.x, normal.y, normal.z), point }++ }++ for (const body of this.bodies.values()) {++ if (body.id === exclude) continue++ if (!(body.desc.layer & collidesWith)) continue++ const hit = sweepCapsuleAabb(from, d, radius, half, body.pos, body.half)++ if (hit) consider(hit.fraction, hit.normal, hit.point)++ }++ for (const plane of this.casts) {++ const hit = sweepCapsulePlane(from, d, radius, half, plane)++ if (hit) consider(hit.fraction, hit.normal, hit.point)++ }++ return best++ }++++ dispose(): void {++ if (this.disposed) return++ this.disposed = true++ this.bodies.clear()++ this.constraints.clear()++ this.casts.length = 0++ }++++ // ── mock-only construction ──────────────────────────────────────────────++++ /**++ * Infinite analytic ground plane with its top face at `y`. Capsule sweeps++ * and rays resolve against it exactly, and dynamic bodies rest on it. This++ * is the surface the movement tests walk on.++ */++ addGroundPlane(y = 0): void {++ this.addCast({ normal: vec3(0, 1, 0), offset: y })++ }++++ /**++ * Marks the most recent cast as ground: casts so marked also stop bodies++ * (`groundHeightAt`) instead of only stopping casts.++ */++ markLastCastAsGround(): void {++ const plane = this.casts[this.casts.length - 1]++ if (plane) plane.isGround = true++ }++++ /**++ * An analytic surface only rays and capsule sweeps see: an infinite plane,++ * unit normal `normal`, at signed distance `offset`, clipped to an optional++ * axis-aligned patch. This is how a test declares a wall, a ceiling or a step++ * without inventing geometry the mock would then have to simulate.++ */++ addCast(plane: {++ normal: Vec3++ offset: number++ minX?: number++ maxX?: number++ minY?: number++ maxY?: number++ minZ?: number++ maxZ?: number++ }): void {++ const len = Math.sqrt(v3lengthSq(plane.normal))++ const normal = vec3(plane.normal.x, plane.normal.y, plane.normal.z)++ if (len > 1e-9) v3scale(normal, normal, 1 / len)++ const patched =++ plane.minX !== undefined ||++ plane.maxX !== undefined ||++ plane.minY !== undefined ||++ plane.maxY !== undefined ||++ plane.minZ !== undefined ||++ plane.maxZ !== undefined++ this.casts.push({++ normal,++ offset: plane.offset / (len > 1e-9 ? len : 1),++ patchMin: patched++ ? vec3(plane.minX ?? -Infinity, plane.minY ?? -Infinity, plane.minZ ?? -Infinity)++ : null,++ patchMax: patched++ ? vec3(plane.maxX ?? Infinity, plane.maxY ?? Infinity, plane.maxZ ?? Infinity)++ : null,++ isGround: false,++ })++ }++++ /** Number of cast surfaces currently installed. Test introspection. */++ castCount(): number {++ return this.casts.length++ }++++ /**++ * The highest non-dynamic surface under (x, z): any analytic up-facing cast++ * plane whose patch covers the column, else the top face of the tallest++ * static/kinematic body whose footprint covers it, else -Infinity.++ */++ groundHeightAt(x: number, z: number): number {++ let floor = -Infinity++ for (const plane of this.casts) {++ if (!plane.isGround) continue++ if (Math.abs(plane.normal.y - 1) > 1e-6) continue++ const { patchMin: lo, patchMax: hi } = plane++ if (lo && hi && (x < lo.x || x > hi.x || z < lo.z || z > hi.z)) continue++ if (plane.offset > floor) floor = plane.offset++ }++ for (const other of this.bodies.values()) {++ if (other.motion === 'dynamic') continue++ if (Math.abs(other.pos.x - x) > other.half.x) continue++ if (Math.abs(other.pos.z - z) > other.half.z) continue++ const top = other.pos.y + other.half.y++ if (top > floor) floor = top++ }++ return floor++ }++++ // ── internals ───────────────────────────────────────────────────────────++++ private assertLive(): void {++ if (this.disposed) throw new Error('physics world disposed')++ }++++ private mustGet(id: BodyId): MockBody {++ const body = this.bodies.get(id)++ if (!body) throw new Error(`unknown physics body ${id}`)++ return body++ }++++ /** Places every welded follower at its group's driver pose plus its offset. */++ private poseWeldGroups(): void {++ const seen = new Set<WeldGroup>()++ for (const body of this.bodies.values()) {++ const group = body.weld++ if (!group || seen.has(group)) continue++ seen.add(group)++ for (const member of group.members) {++ member.body.pos.x = group.driver.pos.x + member.offset.x++ member.body.pos.y = group.driver.pos.y + member.offset.y++ member.body.pos.z = group.driver.pos.z + member.offset.z++ }++ }++ }++++ /**++ * Resting contact against the analytic ground plane and the top face of any++ * non-dynamic body. The mock has no contact solver: friction is modelled as++ * "stop" and restitution (0.05) as "no bounce", which is all a body resting++ * on a plane can observably do here.++ */++ private resolveContacts(): void {++ for (const body of this.bodies.values()) {++ if (body.motion !== 'dynamic') continue++ const floor = this.groundHeightAt(body.pos.x, body.pos.z)++ if (!Number.isFinite(floor)) continue++ const bottom = body.pos.y - body.half.y++ if (bottom >= floor - 1e-9) continue++ body.pos.y = floor + body.half.y++ v3set(body.linVel, 0, 0, 0)++ v3set(body.angVel, 0, 0, 0)++ }++ this.poseWeldGroups()++ }++}++++/**++ * `BodyId` reported for a hit on the analytic cast table. Cast surfaces are not++ * bodies, so they share one reserved id; tests that care which surface was hit++ * should use a box instead.++ */++export const MOCK_CAST_BODY_ID: BodyId = 0++++/** A fresh, empty mock world. */++export function createMockPhysicsWorld(): MockPhysicsWorld {++ return new MockPhysicsWorld()++}++++/**++ * Binds a mock world to the movement module's `CollisionQueries` with the same++ * fixed mask and self-exclusion the server uses++ * (apps/server/src/game/systems/movement.ts:58-68).++ */++export function mockCollisionQueries(++ world: MockPhysicsWorld,++ collidesWith: number = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,++ exclude?: () => number | undefined,++): { sweepCapsule(from: Vec3, to: Vec3, radius: number, height: number): SweepHit | null } {++ return {++ sweepCapsule: (from, to, radius, height) =>++ world.sweepCapsule(from, to, radius, height, collidesWith, exclude?.()),++ }++}++++// ── analytic primitives ──────────────────────────────────────────────────++++/**++ * Slab test of a ray against an AABB. `d` is the whole segment, so the++ * parameter is already the 0..1 fraction the seam wants.++ */++function rayAabb(++ from: Vec3,++ d: Vec3,++ _length: number,++ center: Vec3,++ half: Vec3,++): { point: Vec3; normal: Vec3; fraction: number } | null {++ const o = [from.x, from.y, from.z]++ const dd = [d.x, d.y, d.z]++ const c = [center.x, center.y, center.z]++ const h = [half.x, half.y, half.z]++ let tMin = -Infinity++ let tMax = Infinity++ let axis = 0++ let sign = -1++ for (let a = 0; a < 3; a++) {++ if (Math.abs(dd[a]!) < 1e-12) {++ if (o[a]! < c[a]! - h[a]! || o[a]! > c[a]! + h[a]!) return null++ continue++ }++ const inv = 1 / dd[a]!++ let t1 = (c[a]! - h[a]! - o[a]!) * inv++ let t2 = (c[a]! + h[a]! - o[a]!) * inv++ let s = -1++ if (t1 > t2) {++ const tmp = t1++ t1 = t2++ t2 = tmp++ s = 1++ }++ if (t1 > tMin) {++ tMin = t1++ axis = a++ sign = s++ }++ if (t2 < tMax) tMax = t2++ if (tMin > tMax) return null++ }++ // The origin is already inside the box: nothing to report as a surface hit.++ if (tMin <= 0 || tMin > 1) return null++ const normal = vec3(0, 0, 0)++ if (axis === 0) normal.x = sign++ else if (axis === 1) normal.y = sign++ else normal.z = sign++ return {++ point: vec3(from.x + d.x * tMin, from.y + d.y * tMin, from.z + d.z * tMin),++ normal,++ fraction: tMin,++ }++}++++function rayPlane(++ from: Vec3,++ d: Vec3,++ _length: number,++ plane: CastPlane,++): { point: Vec3; normal: Vec3; fraction: number } | null {++ const denom = v3dot(plane.normal, d)++ if (Math.abs(denom) < 1e-12) return null++ const t = (plane.offset - v3dot(plane.normal, from)) / denom++ if (t <= 0 || t > 1) return null++ const point = vec3(from.x + d.x * t, from.y + d.y * t, from.z + d.z * t)++ if (!inPatch(plane, point)) return null++ // Surface normal always opposes the ray.++ const n = vec3(plane.normal.x, plane.normal.y, plane.normal.z)++ if (denom > 0) v3scale(n, n, -1)++ return { point, normal: n, fraction: t }++}++++/**++ * Sweeps a vertical capsule (centre segment of half-length `half`, radius++ * `radius`) against an AABB. The Minkowski sum of a vertical capsule and an++ * AABB is not an AABB, so this inflates the box by `radius` in x/z and by++ * `half + radius` in y: conservative at the corners, exact on every face. For++ * an axis-aligned world — all the mock models — that is the whole story.++ *++ * Havok reports the contact point on the *surface*, not at the capsule centre++ * (measured: a sweep onto ground at y = 0 returns y = 0 exactly), so the point++ * is walked back onto the inflated face along −normal.++ */++function sweepCapsuleAabb(++ from: Vec3,++ d: Vec3,++ radius: number,++ half: number,++ center: Vec3,++ boxHalf: Vec3,++): SweepHit | null {++ const lo = [++ center.x - boxHalf.x - radius,++ center.y - boxHalf.y - half - radius,++ center.z - boxHalf.z - radius,++ ]++ const hi = [++ center.x + boxHalf.x + radius,++ center.y + boxHalf.y + half + radius,++ center.z + boxHalf.z + radius,++ ]++ const o = [from.x, from.y, from.z]++ const dd = [d.x, d.y, d.z]++ let tMin = -Infinity++ let tMax = Infinity++ let axis = 0++ let sign = -1++ for (let a = 0; a < 3; a++) {++ if (Math.abs(dd[a]!) < 1e-12) {++ if (o[a]! < lo[a]! || o[a]! > hi[a]!) return null++ continue++ }++ const inv = 1 / dd[a]!++ let t1 = (lo[a]! - o[a]!) * inv++ let t2 = (hi[a]! - o[a]!) * inv++ let s = -1++ if (t1 > t2) {++ const tmp = t1++ t1 = t2++ t2 = tmp++ s = 1++ }++ if (t1 > tMin) {++ tMin = t1++ axis = a++ sign = s++ }++ if (t2 < tMax) tMax = t2++ if (tMin > tMax) return null++ }++ // Already overlapping at t = 0: the capsule starts inside, which is not a++ // contact the caller can act on.++ if (tMin <= 0 || tMin > 1) return null++ const normal = vec3(0, 0, 0)++ if (axis === 0) normal.x = sign++ else if (axis === 1) normal.y = sign++ else normal.z = sign++ // Walk the centre back onto the true surface: distance is the capsule's++ // support along the normal, `radius` on the sides and `half + radius` on++ // the caps.++ const support = axis === 1 ? half + radius : radius++ const centre = vec3(from.x + d.x * tMin, from.y + d.y * tMin, from.z + d.z * tMin)++ const point = vec3(++ centre.x - normal.x * support,++ centre.y - normal.y * support,++ centre.z - normal.z * support,++ )++ return { fraction: tMin, normal, point }++}++++/**++ * Sweeps a vertical capsule against an analytic plane. The support function of++ * a Y-axis capsule of half-length `half` and radius `radius` along a unit normal++ * n is `half·|n.y| + radius`, which is exact, so the contact is a single++ * closed-form division per side.++ *++ * The capsule is a closed convex set centred on the sweep line, so it can touch++ * the plane from either side: the earliest contact is min over s of++ * (s·support − signed) / (n·d). The ground plane is the common case (capsule++ * above it, s = +1); a wall or a ceiling declared with an outward normal is++ * approached from the opposite side, s = −1. Taking only one of the two misses++ * every wall and lets the sweep continue through it.++ *++ * A sweep that *starts* already overlapping the slab has no first contact to++ * report, exactly as in the AABB path above (tMin <= 0). This matters for a++ * short hull on a thick radius: STANCE_HULL[Prone] = 0.7 with a 0.4 radius++ * clamps the cylindrical segment to 0.02, so a prone capsule is 0.82 tall and++ * rests 0.06 into the floor. Reporting a hit there would block every upward++ * sweep, i.e. the player could never stand up.++ */++function sweepCapsulePlane(++ from: Vec3,++ d: Vec3,++ radius: number,++ half: number,++ plane: CastPlane,++): SweepHit | null {++ const denom = v3dot(plane.normal, d)++ if (Math.abs(denom) < 1e-12) return null++ const support = half * Math.abs(plane.normal.y) + radius++ const signed = v3dot(plane.normal, from) - plane.offset++ if (signed < support && signed > -support) return null++ let best = Infinity++ for (const side of [support, -support]) {++ const t = (side - signed) / denom++ if (t >= 0 && t <= 1 && t < best) best = t++ }++ if (best === Infinity) return null++ const centre = vec3(from.x + d.x * best, from.y + d.y * best, from.z + d.z * best)++ if (!inPatch(plane, centre)) return null++ // Surface normal always opposes the sweep.++ const normal = vec3(plane.normal.x, plane.normal.y, plane.normal.z)++ if (denom > 0) v3scale(normal, normal, -1)++ const point = vec3(++ centre.x - normal.x * support,++ centre.y - normal.y * support,++ centre.z - normal.z * support,++ )++ return { fraction: best, normal, point }++}++++function inPatch(plane: CastPlane, point: Vec3): boolean {++ const { patchMin: lo, patchMax: hi } = plane++ if (!lo || !hi) return true++ return (++ point.x >= lo.x &&++ point.x <= hi.x &&++ point.y >= lo.y &&++ point.y <= hi.y &&++ point.z >= lo.z &&++ point.z <= hi.z++ )++}@@@ -156,6 +156,10 @@ importers:'@openvibe/shared':specifier: workspace:*version: link:../shared++ devDependencies:++ '@openvibe/physics':++ specifier: workspace:*++ version: link:../physicspackages/persistence:dependencies:
@@ -100,7 +100,6 @@ freeze. Props are protected: only you and players you trust can move them.
@@ -100,7 +100,6 @@ freeze. Props are protected: only you and players you trust can move them.
| `pnpm format` | Prettier write |
| `pnpm format` | Prettier write |
| `pnpm build` | Production build of all packages + client bundle |
| `pnpm build` | Production build of all packages + client bundle |
| `tsx apps/server/scripts/sliceTest.ts` | End-to-end vertical-slice test (boots a real server, drives protocol clients, restarts, asserts persistence) |
| `tsx apps/server/scripts/sliceTest.ts` | End-to-end vertical-slice test (boots a real server, drives protocol clients, restarts, asserts persistence) |
-| `tsx packages/physics/scripts/smoke.ts` | Headless Havok smoke test |
## Production
## Production
@@ -1711,12 +1711,18 @@ async function main(): Promise<void> {
@@ -1711,12 +1711,18 @@ async function main(): Promise<void> {
}
}
assert(site, 'extraction event announced with a location')
assert(site, 'extraction event announced with a location')
await walkTo(a, site[0], site[1], 60_000)
await walkTo(a, site[0], site[1], 60_000)
- // Hold the circle until the recall (25s hold + slack).
+ // Hold the circle until the recall (25s hold + slack). The recall arrives as
+ // three separate frames — an announce, the position update and the
+ // inventory — in no guaranteed order, so the loop must not stop on the
+ // player snapshot alone: the inventory frame carrying meta.secured is what
+ // the assertion below reads, and it routinely lands after the snapshot.
{
{
const start = Date.now()
const start = Date.now()
+ const secured = (): boolean =>
+ a.inventory?.slots.find((s) => s.stack.def === 'salvage_core')?.stack.meta?.secured === 1
while (Date.now() - start < 45_000) {
while (Date.now() - start < 45_000) {
const me = a.me
const me = a.me
- if (me && Math.hypot(me.pos[0] - 0, me.pos[2] - 4) < 6) break // recalled to spawn
+ if (me && Math.hypot(me.pos[0] - 0, me.pos[2] - 4) < 6 && secured()) break // both frames in
// Nudge back toward the beacon in case physics drift pushed us out.
// Nudge back toward the beacon in case physics drift pushed us out.
const dist = me ? Math.hypot(me.pos[0] - site[0], me.pos[2] - site[1]) : 99
const dist = me ? Math.hypot(me.pos[0] - site[0], me.pos[2] - site[1]) : 99
if (me && dist > 3) await walkTo(a, site[0], site[1], 6000)
if (me && dist > 3) await walkTo(a, site[0], site[1], 6000)
@@ -12,5 +12,8 @@
@@ -12,5 +12,8 @@
"dependencies": {
"dependencies": {
"@openvibe/content": "workspace:*",
"@openvibe/content": "workspace:*",
"@openvibe/shared": "workspace:*"
"@openvibe/shared": "workspace:*"
+ },
+ "devDependencies": {
+ "@openvibe/physics": "workspace:*"
}
}
}
}
@@ -1,7 +1,12 @@
@@ -1,7 +1,12 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
import { vec3, type Vec3 } from '@openvibe/shared'
import { vec3, type Vec3 } from '@openvibe/shared'
+import {
+ createMockPhysicsWorld,
+ mockCollisionQueries,
+ type MockPhysicsWorld,
+} from '@openvibe/physics/mock'
import { Buttons } from './buttons.js'
import { Buttons } from './buttons.js'
-import type { CollisionQueries, SweepHit } from './collision.js'
+import type { CollisionQueries } from './collision.js'
import { DEFAULT_MOVEMENT } from './params.js'
import { DEFAULT_MOVEMENT } from './params.js'
import {
import {
Stance,
Stance,
@@ -16,34 +21,28 @@ const P = DEFAULT_MOVEMENT
@@ -16,34 +21,28 @@ const P = DEFAULT_MOVEMENT
const DT = 1 / 30
const DT = 1 / 30
/**
/**
- * Analytic test world: infinite ground plane at y=0 and an optional wall
- * plane at x = wallX (normal -X). Capsule contact analytically resolved.
+ * The movement tests walk on the physics package's own mock world rather than
+ * a hand-rolled analytic stub, so the sweep geometry under test is the one
+ * `mockCollisionQueries` binds with the server's mask (apps/server/src/game/
+ * systems/movement.ts:58-68). Analytic surfaces stand in for level geometry:
+ * `addGroundPlane` is the floor, `addCast` a wall or a ceiling.
*/
*/
-function makeWorld(wallX?: number): CollisionQueries {
- return {
- sweepCapsule(from: Vec3, to: Vec3, radius: number, height: number): SweepHit | null {
- const half = height / 2
- const hits: SweepHit[] = []
- const fromBottom = from.y - half
- const toBottom = to.y - half
- if (fromBottom >= 0 && toBottom < 0) {
- const fraction = fromBottom / (fromBottom - toBottom)
- hits.push({ fraction, normal: vec3(0, 1, 0), point: vec3(from.x, 0, from.z) })
- }
- if (wallX !== undefined) {
- const limit = wallX - radius
- if (from.x <= limit && to.x > limit) {
- const fraction = (limit - from.x) / (to.x - from.x)
- hits.push({ fraction, normal: vec3(-1, 0, 0), point: vec3(wallX, from.y, from.z) })
- }
- }
- if (hits.length === 0) return null
- hits.sort((a, b) => a.fraction - b.fraction)
- return hits[0] ?? null
- },
- }
+/** Worlds created by `makeWorld`, disposed after each case. */
+const live: MockPhysicsWorld[] = []
+
+function makeWorld(opts?: { wallX?: number; ceilingY?: number }): CollisionQueries {
+ const world = createMockPhysicsWorld()
+ world.addGroundPlane(0)
+ if (opts?.wallX !== undefined) world.addCast({ normal: vec3(1, 0, 0), offset: opts.wallX })
+ if (opts?.ceilingY !== undefined) world.addCast({ normal: vec3(0, 1, 0), offset: opts.ceilingY })
+ live.push(world)
+ return mockCollisionQueries(world)
}
}
+afterEach(() => {
+ while (live.length > 0) live.pop()?.dispose()
+})
+
function idle(): MoveInput {
function idle(): MoveInput {
return { moveX: 0, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }
return { moveX: 0, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }
}
}
@@ -52,8 +51,13 @@ function forward(buttons = 0): MoveInput {
@@ -52,8 +51,13 @@ function forward(buttons = 0): MoveInput {
return { moveX: 0, moveZ: 1, yaw: 0, pitch: 0, buttons }
return { moveX: 0, moveZ: 1, yaw: 0, pitch: 0, buttons }
}
}
+/**
+ * Spawn a hair above the floor: the mock's ground plane rejects a sweep that
+ * starts in exact contact (t = 0, like Havok's), so a spawn at exactly
+ * capsuleHeight/2 has no ground to find until gravity pulls it down a tick.
+ */
function spawnGrounded() {
function spawnGrounded() {
- return createMoveState(vec3(0, P.capsuleHeight / 2, 0))
+ return createMoveState(vec3(0, P.capsuleHeight / 2 + 0.01, 0))
}
}
function horizSpeed(v: Vec3): number {
function horizSpeed(v: Vec3): number {
@@ -135,7 +139,7 @@ describe('stepMovement', () => {
@@ -135,7 +139,7 @@ describe('stepMovement', () => {
it('slides along walls instead of stopping', () => {
it('slides along walls instead of stopping', () => {
const s = spawnGrounded()
const s = spawnGrounded()
- const world = makeWorld(2)
+ const world = makeWorld({ wallX: 2 })
// Move diagonally (+X into wall, +Z along it)
// Move diagonally (+X into wall, +Z along it)
const input: MoveInput = { moveX: 1, moveZ: 1, yaw: 0, pitch: 0, buttons: 0 }
const input: MoveInput = { moveX: 1, moveZ: 1, yaw: 0, pitch: 0, buttons: 0 }
for (let i = 0; i < 120; i++) stepMovement(s, input, P, world, DT)
for (let i = 0; i < 120; i++) stepMovement(s, input, P, world, DT)
@@ -146,7 +150,7 @@ describe('stepMovement', () => {
@@ -146,7 +150,7 @@ describe('stepMovement', () => {
it('is deterministic for identical input streams', () => {
it('is deterministic for identical input streams', () => {
const run = () => {
const run = () => {
const s = spawnGrounded()
const s = spawnGrounded()
- const world = makeWorld(3)
+ const world = makeWorld({ wallX: 3 })
for (let i = 0; i < 200; i++) {
for (let i = 0; i < 200; i++) {
const input: MoveInput = {
const input: MoveInput = {
moveX: Math.sin(i * 0.1),
moveX: Math.sin(i * 0.1),
@@ -217,21 +221,9 @@ describe('stances', () => {
@@ -217,21 +221,9 @@ describe('stances', () => {
})
})
it('standing up is blocked by a ceiling', () => {
it('standing up is blocked by a ceiling', () => {
- // World with a ceiling at y=1.4: crouch fits (hull 1.2), standing does not.
- const ceiling = 1.4
- const world: ReturnType<typeof makeWorld> = {
- sweepCapsule(from, to, radius, height) {
- const base = makeWorld().sweepCapsule(from, to, radius, height)
- const fromTop = from.y + height / 2
- const toTop = to.y + height / 2
- if (fromTop <= ceiling && toTop > ceiling) {
- const fraction = (ceiling - fromTop) / (toTop - fromTop)
- const hit = { fraction, normal: vec3(0, -1, 0), point: vec3(from.x, ceiling, from.z) }
- if (!base || fraction < base.fraction) return hit
- }
- return base
- },
- }
+ // Upward-facing analytic plane at y=1.4: crouch fits (hull 1.2), standing
+ // does not, so the up-sweep inside updateStance must hit it.
+ const world = makeWorld({ ceilingY: 1.4 })
const s = spawnGrounded()
const s = spawnGrounded()
stepMovement(s, { ...idle(), buttons: Buttons.Crouch }, P, world, DT)
stepMovement(s, { ...idle(), buttons: Buttons.Crouch }, P, world, DT)
for (let i = 0; i < 30; i++)
for (let i = 0; i < 30; i++)
@@ -274,7 +266,7 @@ describe('noclip', () => {
@@ -274,7 +266,7 @@ describe('noclip', () => {
it('passes through walls', () => {
it('passes through walls', () => {
const state = createMoveState(vec3(0, 1, 0))
const state = createMoveState(vec3(0, 1, 0))
state.noclip = true
state.noclip = true
- const world = makeWorld(2) // wall at x=2
+ const world = makeWorld({ wallX: 2 }) // wall at x=2
for (let i = 0; i < 90; i++)
for (let i = 0; i < 90; i++)
stepMovement(state, { moveX: 1, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }, P, world, DT)
stepMovement(state, { moveX: 1, moveZ: 0, yaw: 0, pitch: 0, buttons: 0 }, P, world, DT)
expect(state.pos.x).toBeGreaterThan(3)
expect(state.pos.x).toBeGreaterThan(3)
@@ -5,7 +5,8 @@
@@ -5,7 +5,8 @@
"type": "module",
"type": "module",
"exports": {
"exports": {
".": "./src/index.ts",
".": "./src/index.ts",
- "./havok": "./src/havok/index.ts"
+ "./havok": "./src/havok/index.ts",
+ "./mock": "./src/mock.ts"
},
},
"scripts": {
"scripts": {
"build": "tsc --build"
"build": "tsc --build"
deleted file mode 100644
deleted file mode 100644
@@ -1,267 +0,0 @@
@@ -1,267 +0,0 @@
-/**
- * Headless constraint smoke test (run with tsx): exercises every sandbox
- * constraint variant — rope, hinge (limits, friction, motor), slider
- * (limits, motor), spring — against real Havok, exactly as the dedicated
- * server runs it. Complements smoke.ts (bodies, sweeps, weld).
- */
-import { readFile } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import HavokPhysics from '@babylonjs/havok'
-import { quat, vec3, type Vec3 } from '@openvibe/shared'
-import { CollisionLayer } from '../src/types.js'
-import { createHeadlessHavokWorld } from '../src/havok/index.js'
-
-const require = createRequire(import.meta.url)
-const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')
-const havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })
-
-const world = createHeadlessHavokWorld(havok)
-const dt = 1 / 30
-const PROP_MASK = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player
-
-world.addBody({
- shape: { type: 'box', size: [200, 1, 200] },
- motion: 'static',
- pos: vec3(0, -0.5, 0),
- layer: CollisionLayer.Static,
- collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
-})
-
-const rot = quat()
-const p = vec3()
-
-function makeBox(pos: Vec3, size = 0.5, motion: 'dynamic' | 'static' = 'dynamic'): number {
- return world.addBody({
- shape: { type: 'box', size: [size, size, size] },
- motion,
- pos,
- massKg: 10,
- layer: CollisionLayer.Prop,
- collidesWith: PROP_MASK,
- })
-}
-
-// ── Rope: a box tethered to a static anchor swings but never exceeds length ──
-{
- const anchor = makeBox(vec3(0, 6, 0), 0.4, 'static')
- const bob = makeBox(vec3(1.5, 6, 0), 0.4)
- const rope = world.addConstraint({
- type: 'rope',
- bodyA: anchor,
- bodyB: bob,
- anchorA: vec3(0, 0, 0),
- anchorB: vec3(0, 0, 0),
- length: 2,
- })
- let maxDist = 0
- let minY = Infinity
- for (let i = 0; i < 300; i++) {
- world.step(dt)
- world.getTransform(bob, p, rot)
- maxDist = Math.max(maxDist, Math.hypot(p.x, p.y - 6, p.z))
- minY = Math.min(minY, p.y)
- }
- console.log('rope: max anchor distance', maxDist.toFixed(3), 'lowest y', minY.toFixed(2))
- if (maxDist > 2.3) throw new Error(`rope stretched past length: ${maxDist}`)
- // The bob must have swung down through the bottom of its arc (a pendulum
- // on a taut 2 m tether reaches y ≈ 4).
- if (minY > 4.6) throw new Error(`rope bob never swung down: minY=${minY}`)
- world.removeConstraint(rope)
-}
-
-// ── Hinge with limits: a door swings but respects ±45° ──
-{
- const post = makeBox(vec3(10, 2, 0), 0.4, 'static')
- const door = makeBox(vec3(10.9, 2, 0), 0.4)
- world.addConstraint({
- type: 'hinge',
- bodyA: post,
- bodyB: door,
- anchorA: vec3(0.45, 0, 0),
- anchorB: vec3(-0.45, 0, 0),
- axisA: vec3(0, 1, 0),
- axisB: vec3(0, 1, 0),
- limits: { min: -Math.PI / 4, max: Math.PI / 4 },
- })
- // Shove the door hard sideways; the hinge must cap the swing.
- world.setLinearVelocity(door, vec3(0, 0, 8))
- let maxAngle = 0
- for (let i = 0; i < 90; i++) {
- world.step(dt)
- world.getTransform(door, p, rot)
- const angle = Math.abs(Math.atan2(p.z, p.x - 10))
- maxAngle = Math.max(maxAngle, angle)
- }
- console.log('hinge: max swing angle', ((maxAngle * 180) / Math.PI).toFixed(1), 'deg')
- if (maxAngle > Math.PI / 4 + 0.25) throw new Error(`hinge blew past its limit: ${maxAngle}`)
- if (maxAngle < 0.2) throw new Error('hinge did not swing at all')
- world.getTransform(door, p, rot)
- if (Math.abs(p.y - 2) > 0.25) throw new Error(`hinge door fell: y=${p.y}`)
-}
-
-// ── Motorized hinge (bearing + drive): a wheel spins up ──
-{
- const axleMount = makeBox(vec3(20, 3, 0), 0.4, 'static')
- const wheel = world.addBody({
- shape: { type: 'cylinder', radius: 0.6, height: 0.2 },
- motion: 'dynamic',
- pos: vec3(20, 3, 0.4),
- massKg: 8,
- layer: CollisionLayer.Prop,
- collidesWith: PROP_MASK,
- })
- const motorId = world.addConstraint({
- type: 'hinge',
- bodyA: axleMount,
- bodyB: wheel,
- anchorA: vec3(0, 0, 0.4),
- anchorB: vec3(0, 0, 0),
- axisA: vec3(0, 0, 1),
- axisB: vec3(0, 1, 0), // cylinder's own axis is +Y
- motor: { targetVelocity: 6, maxForce: 500 },
- })
- const av = vec3()
- for (let i = 0; i < 90; i++) world.step(dt)
- world.getAngularVelocity(wheel, av)
- const spin = Math.hypot(av.x, av.y, av.z)
- console.log('motor: wheel angular speed', spin.toFixed(2), 'rad/s')
- if (spin < 4) throw new Error(`motorized wheel did not spin up: ${spin}`)
- // Retune the motor to stop; it should brake.
- world.setConstraintMotor(motorId, { targetVelocity: 0, maxForce: 500 })
- for (let i = 0; i < 60; i++) world.step(dt)
- world.getAngularVelocity(wheel, av)
- const stopped = Math.hypot(av.x, av.y, av.z)
- console.log('motor: after brake', stopped.toFixed(3), 'rad/s')
- if (stopped > 0.5) throw new Error(`motor did not brake: ${stopped}`)
-}
-
-// ── Slider with limits: a drawer slides along a rail and stops ──
-{
- const rail = makeBox(vec3(30, 2, 0), 0.4, 'static')
- const drawer = makeBox(vec3(30, 2, 0.6), 0.4)
- world.addConstraint({
- type: 'slider',
- bodyA: rail,
- bodyB: drawer,
- anchorA: vec3(0, 0, 0.6),
- anchorB: vec3(0, 0, 0),
- axisA: vec3(0, 0, 1),
- axisB: vec3(0, 0, 1),
- limits: { min: -0.5, max: 1.0 },
- })
- world.setLinearVelocity(drawer, vec3(0, 0, 5))
- let maxZ = -Infinity
- let minZ = Infinity
- let maxOffAxis = 0
- for (let i = 0; i < 120; i++) {
- world.step(dt)
- world.getTransform(drawer, p, rot)
- maxZ = Math.max(maxZ, p.z)
- minZ = Math.min(minZ, p.z)
- maxOffAxis = Math.max(maxOffAxis, Math.abs(p.x - 30), Math.abs(p.y - 2))
- if (i === 60) world.setLinearVelocity(drawer, vec3(0, 0, -5))
- }
- console.log(
- 'slider: travel',
- minZ.toFixed(2),
- '..',
- maxZ.toFixed(2),
- 'off-axis',
- maxOffAxis.toFixed(3),
- )
- if (maxZ > 1.85 || minZ < -0.15) throw new Error(`slider blew limits: ${minZ}..${maxZ}`)
- if (maxZ < 1.3) throw new Error(`slider did not travel: ${maxZ}`)
- if (maxOffAxis > 0.15) throw new Error(`slider left its rail: ${maxOffAxis}`)
-}
-
-// ── Spring: a hanging box bounces then settles near rest length ──
-{
- const mount = makeBox(vec3(40, 6, 0), 0.4, 'static')
- const bob = makeBox(vec3(40, 5.5, 0), 0.4)
- world.addConstraint({
- type: 'spring',
- bodyA: mount,
- bodyB: bob,
- anchorA: vec3(0, 0, 0),
- anchorB: vec3(0, 0, 0),
- restLength: 1.5,
- stiffness: 400,
- damping: 15,
- })
- for (let i = 0; i < 300; i++) world.step(dt)
- world.getTransform(bob, p, rot)
- const dist = Math.hypot(p.x - 40, p.y - 6, p.z)
- console.log('spring: settled anchor distance', dist.toFixed(3), '(rest 1.5)')
- // Gravity stretches the spring below rest; generous envelope.
- if (dist < 1.2 || dist > 2.2) throw new Error(`spring settled badly: ${dist}`)
-}
-
-// ── Stress: a 200-prop welded structure must settle and stay cheap ──
-{
- const GRID = 10 // 10 x 20 wall of boxes
- const ROWS = 20
- const ids: number[] = []
- for (let r = 0; r < ROWS; r++) {
- for (let c = 0; c < GRID; c++) {
- ids.push(makeBox(vec3(60 + c * 0.52, 0.26 + r * 0.52, 0), 0.5))
- }
- }
- // Weld each box to its right and upper neighbor (grid lattice).
- let welds = 0
- for (let r = 0; r < ROWS; r++) {
- for (let c = 0; c < GRID; c++) {
- const i = r * GRID + c
- if (c + 1 < GRID) {
- world.addConstraint({ type: 'weld', bodyA: ids[i]!, bodyB: ids[i + 1]! })
- welds++
- }
- if (r + 1 < ROWS) {
- world.addConstraint({ type: 'weld', bodyA: ids[i]!, bodyB: ids[i + GRID]! })
- welds++
- }
- }
- }
- // Settle phase.
- let settleTick = -1
- const t0 = performance.now()
- for (let i = 0; i < 600; i++) {
- world.step(dt)
- if (settleTick < 0 && ids.every((id) => world.isSettled(id))) {
- settleTick = i
- break
- }
- }
- const settleMs = performance.now() - t0
- console.log(
- `stress: ${ids.length} props, ${welds} welds — settled at tick ${settleTick} (${settleMs.toFixed(0)}ms total)`,
- )
- if (settleTick < 0) throw new Error('welded structure never settled')
-
- // Settled steps must be cheap (structure asleep, no solver churn).
- const t1 = performance.now()
- for (let i = 0; i < 100; i++) world.step(dt)
- const idleMs = (performance.now() - t1) / 100
- console.log(`stress: settled step cost ${idleMs.toFixed(3)}ms`)
- if (idleMs > 5) throw new Error(`sleeping welded structure too expensive: ${idleMs}ms/step`)
- if (!ids.every((id) => world.isSettled(id))) throw new Error('structure woke without cause')
-
- // Impact wakes the island, then it settles again.
- world.setLinearVelocity(ids[ids.length - 1]!, vec3(0, 0, 6))
- world.step(dt)
- const awake = ids.filter((id) => !world.isSettled(id)).length
- console.log(`stress: impact woke ${awake} bodies`)
- if (awake < 1) throw new Error('impact failed to wake the structure')
- let resettled = false
- for (let i = 0; i < 900; i++) {
- world.step(dt)
- if (ids.every((id) => world.isSettled(id))) {
- resettled = true
- console.log(`stress: re-settled after ${i} ticks`)
- break
- }
- }
- if (!resettled) throw new Error('structure never re-settled after impact')
-}
-
-world.dispose()
-console.log('CONSTRAINT SMOKE OK')
deleted file mode 100644
deleted file mode 100644
@@ -1,120 +0,0 @@
@@ -1,120 +0,0 @@
-/**
- * Headless physics smoke test (run with tsx): loads the Havok wasm in Node,
- * builds a world, drops a dynamic box onto static ground, checks it settles,
- * and verifies capsule sweeps + raycasts. Exercises the exact code path the
- * dedicated server uses.
- */
-import { readFile } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import HavokPhysics from '@babylonjs/havok'
-import { quat, vec3 } from '@openvibe/shared'
-import { CollisionLayer } from '../src/types.js'
-import { createHeadlessHavokWorld } from '../src/havok/index.js'
-
-const require = createRequire(import.meta.url)
-const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')
-const havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })
-
-const world = createHeadlessHavokWorld(havok)
-
-const ground = world.addBody({
- shape: { type: 'box', size: [100, 1, 100] },
- motion: 'static',
- pos: vec3(0, -0.5, 0),
- layer: CollisionLayer.Static,
- collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
-})
-
-const box = world.addBody({
- shape: { type: 'box', size: [0.7, 0.7, 0.7] },
- motion: 'dynamic',
- pos: vec3(0, 3, 0),
- massKg: 25,
- layer: CollisionLayer.Prop,
- collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,
-})
-
-const dt = 1 / 30
-for (let i = 0; i < 120; i++) world.step(dt)
-
-const pos = vec3()
-const rot = quat()
-world.getTransform(box, pos, rot)
-console.log('box rest pos:', pos, 'settled:', world.isSettled(box))
-if (Math.abs(pos.y - 0.35) > 0.05) throw new Error(`box did not rest at 0.35: ${pos.y}`)
-if (!world.isSettled(box)) throw new Error('box did not settle')
-
-// Capsule sweep down over the box should hit its top
-const hit = world.sweepCapsule(
- vec3(0, 3, 0),
- vec3(0, 0.5, 0),
- 0.4,
- 1.8,
- CollisionLayer.Static | CollisionLayer.Prop,
-)
-console.log('sweep hit:', hit)
-if (!hit || hit.normal.y < 0.9) throw new Error('capsule sweep failed')
-
-// Raycast should identify the box body
-const ray = world.raycast(vec3(2, 0.35, 0), vec3(-2, 0.35, 0), CollisionLayer.Prop)
-console.log('ray hit:', ray)
-if (!ray || ray.bodyId !== box) throw new Error('raycast failed')
-
-// Freeze then unfreeze
-world.setMotionType(box, 'static')
-world.setMotionType(box, 'dynamic')
-world.step(dt)
-
-// Kinematic player body pushes a prop
-const player = world.addBody({
- shape: { type: 'capsule', radius: 0.4, height: 1.8 },
- motion: 'kinematic',
- pos: vec3(-3, 0.9, 0),
- layer: CollisionLayer.Player,
- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,
-})
-for (let i = 0; i < 60; i++) {
- world.setTransform(player, vec3(-3 + i * 0.06, 0.9, 0))
- world.step(dt)
-}
-world.getTransform(box, pos, rot)
-console.log('box after push:', pos, 'settled:', world.isSettled(box))
-if (pos.x < 0.05) throw new Error('kinematic player failed to push prop')
-
-// Weld: two stacked boxes welded together should move as one and keep
-// their relative offset after being shoved.
-const weldA = world.addBody({
- shape: { type: 'box', size: [0.5, 0.5, 0.5] },
- motion: 'dynamic',
- pos: vec3(10, 0.25, 0),
- massKg: 10,
- layer: CollisionLayer.Prop,
- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,
-})
-const weldB = world.addBody({
- shape: { type: 'box', size: [0.5, 0.5, 0.5] },
- motion: 'dynamic',
- pos: vec3(10, 0.78, 0),
- massKg: 10,
- layer: CollisionLayer.Prop,
- collidesWith: CollisionLayer.Static | CollisionLayer.Prop,
-})
-for (let i = 0; i < 30; i++) world.step(dt)
-const weldId = world.addConstraint({ type: 'weld', bodyA: weldA, bodyB: weldB })
-world.setLinearVelocity(weldA, vec3(4, 0, 0))
-for (let i = 0; i < 60; i++) world.step(dt)
-const pa = vec3()
-const pb = vec3()
-world.getTransform(weldA, pa, rot)
-world.getTransform(weldB, pb, rot)
-console.log('weld: A', pa, 'B', pb)
-if (pa.x < 10.3) throw new Error('welded pair did not slide')
-const dy = pb.y - pa.y
-if (Math.abs(pb.x - pa.x) > 0.25 || dy < 0.3 || dy > 0.75) {
- throw new Error(`weld did not hold relative pose (dx=${pb.x - pa.x}, dy=${dy})`)
-}
-world.removeConstraint(weldId)
-
-world.removeBody(ground)
-world.dispose()
-console.log('PHYSICS SMOKE OK')
new file mode 100644
new file mode 100644
@@ -0,0 +1,1536 @@
@@ -0,0 +1,1536 @@
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { quat, vec3, type Quat, type Vec3 } from '@openvibe/shared'
+import { beforeAll, describe, expect, it } from 'vitest'
+import HavokPhysics from '@babylonjs/havok'
+import { createHeadlessHavokWorld } from './havok/index.js'
+import {
+ MOCK_GRAVITY,
+ MOCK_SETTLE_ANGULAR,
+ MOCK_SETTLE_LINEAR,
+ MOCK_TICK,
+ createMockPhysicsWorld,
+} from './mock.js'
+import { CollisionLayer, type BodyDesc, type PhysicsWorld } from './types.js'
+
+/**
+ * Seam conformance.
+ *
+ * Every case runs against whatever PhysicsWorld factory is handed to
+ * `conformance()`, so a second engine (ADR-0007 decision 2 names Rapier) can be
+ * held to exactly the behaviour Havok has today. Nothing in this file may reach
+ * around the seam: no Babylon, no Havok, no assumption about internals beyond
+ * what `PhysicsWorld` promises.
+ *
+ * ── Constants, read off havokWorld.ts rather than the brief ──────────────
+ * - gravity (0, -16.5, 0) havokWorld.ts:588
+ * - material friction 0.75 / static 0.85 / restitution 0.05 :123
+ * - linear damping 0.05, angular 0.6 :131-132
+ * - default mass 10 kg :128
+ * - settle thresholds 0.05 m/s, 0.15 rad/s :72-73 (squared compare, angular `<=`)
+ *
+ * ── Behaviour asserted here that is NOT in the seam doc comment ──────────
+ * These are properties of today's Havok adapter, documented so the Rapier port
+ * reproduces them rather than trips over them:
+ *
+ * 1. **`step(dt)` does not honour its argument.** `HavokWorld.step` calls
+ * `plugin.executeStep(dt, bodies)`, and the Havok plugin resolves the world
+ * step time as `this._useDeltaForWorldStep ? delta : this._fixedTimeStep`
+ * with `_useDeltaForWorldStep` false by default — so every step() advances a
+ * fixed 1/60 s of simulation regardless of the dt passed in. Measured: 30
+ * step(1/30) and 30 step(1/15) both yield v.y = -8.14 m/s, while 60
+ * step(1/60) yields -16.09. The seam comment says "advances by a fixed dt",
+ * which is the *intent*; the caller-side 30 Hz tick is what the game relies
+ * on and it is unaffected, but a Rapier adapter that actually honours dt
+ * would be ~2× faster per tick at 30 Hz and would change every simulation
+ * constant tuned against Havok. Listed for Opus.
+ * 2. **Waking or settling a body at the exact threshold.** The code compares
+ * `len² > threshold²` for linear (so a body moving at exactly 0.05 m/s is
+ * reported *unsettled* by Havok's float storage, though the comparison says
+ * settled) and `<=` for angular. The mock implements the comparison as
+ * written; this suite therefore probes just under and just over each
+ * threshold and does not pin the exact-boundary behaviour.
+ * 3. **Raycast filtering is by the body's own `layer`.** `plugin.raycast` is
+ * called with `membership: 0xffffffff, collideWith: collidesWith`
+ * (havokWorld.ts:415-418), but the shape filter is a membership/collide
+ * pair, so a body is hit when `rayMask & body.layer` and `body.layer &
+ * body.collidesWith` — the body's `collidesWith` must include its own layer
+ * for the pair to pass. Measured: layer Player / collidesWith Static is hit
+ * by mask 4 but not by mask 1, while layer Static / collidesWith Prop is hit
+ * by mask 1, 2, 3 and 7. The mock filters on `rayMask & body.layer` only,
+ * which is a superset — see "what the mock does not model".
+ * 4. **A welded body resists velocity changes for a few steps.** `setLinearVelocity`
+ * on one half of a weld writes the velocity, but the joint's relative-pose
+ * preservation pulls the pair back over the next couple of steps. Asserted
+ * here as "the pair stays together", not as free sliding.
+ * 5. **`isSettled`, `wake` and `applyForce` ignore non-dynamic bodies**
+ * (havokWorld.ts:225, :233, :406), and `removeBody` / `removeConstraint` on
+ * an unknown id are silent no-ops (:142, :399) while every other body
+ * accessor throws `unknown physics body <id>` (:482).
+ */
+
+const DT = 1 / 30
+
+interface Adapter {
+ /** Name used in the describe block. */
+ name: string
+ /** Fresh world per case; the case disposes it. */
+ create: () => PhysicsWorld
+ /**
+ * Cases the mock deliberately does not model. Listing a case here keeps it in
+ * the file (visible, not forgotten) while marking it as Havok-only.
+ */
+ skip?: (title: string) => boolean
+ /**
+ * Real simulated seconds one `step()` advances. The mock honours the dt it is
+ * given; the Havok plugin resolves a fixed 1/60 s of its own (see the header
+ * note), so a case that wants "N seconds of gravity" must ask each adapter for
+ * its own tick count rather than sharing one number.
+ */
+ stepSeconds: number
+}
+
+/** HavokWorld over a NullEngine scene — the exact headless server code path. */
+let havok: unknown
+beforeAll(async () => {
+ const require = createRequire(import.meta.url)
+ const wasmPath = require.resolve('@babylonjs/havok/lib/esm/HavokPhysics.wasm')
+ havok = await HavokPhysics({ wasmBinary: (await readFile(wasmPath)).buffer as ArrayBuffer })
+}, 60_000)
+
+const havokAdapter: Adapter = {
+ name: 'HavokWorld',
+ create: () => createHeadlessHavokWorld(havok),
+ // Measured (header note 1): the plugin ignores the dt passed to step() and
+ // advances its own fixed 1/60 s.
+ stepSeconds: 1 / 60,
+}
+
+/**
+ * Case titles the mock cannot model, as prefixes. Kept as data (not baked into
+ * a lambda) so `it('every case the mock skips still runs somewhere')` can check
+ * each one against the titles this file actually defines: an entry left behind
+ * after a case is renamed or deleted silently skips nothing, which is how the
+ * mock came to run a case its own header said it could not model.
+ */
+const MOCK_SKIP_PREFIXES: readonly string[] = [
+ 'step advances',
+ 'a welded island',
+ 'a welded pair resists',
+ 'a spring',
+ 'a rope',
+ 'a hinge',
+ 'a motorized hinge',
+ 'a slider',
+ 'angular damping is strong',
+ 'surface friction is high',
+ 'a body knocked off',
+ 'sweepCapsule offsetting',
+]
+
+/**
+ * The mock world, with the same analytic surfaces the Havok cases build out of
+ * static boxes. No ambient ground plane: several cases deliberately sweep a ray
+ * or capsule through empty space or sideways past a wall, and a global plane
+ * would hit first.
+ */
+const mockAdapter: Adapter = {
+ name: 'MockPhysicsWorld',
+ // No ambient ground plane: several cases deliberately sweep a ray or capsule
+ // through empty space or sideways past a wall, and a global plane would hit
+ // first. Cases that need ground add `groundDesc()` like the Havok ones.
+ create: () => createMockPhysicsWorld(),
+ // Semi-implicit Euler at the 30 Hz tick the game actually runs at.
+ stepSeconds: MOCK_TICK,
+ skip: (title) => MOCK_SKIP_PREFIXES.some((prefix) => title.startsWith(prefix)),
+}
+
+const pos = (): Vec3 => vec3()
+const rot = (): Quat => quat()
+
+/** Ground: a 200 m static box with its top face at y = 0. */
+function groundDesc(size = 200): BodyDesc {
+ return {
+ shape: { type: 'box', size: [size, 1, size] },
+ motion: 'static',
+ pos: vec3(0, -0.5, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ }
+}
+
+function dynamicBoxDesc(at: Vec3, size = 0.7, massKg?: number): BodyDesc {
+ return {
+ shape: { type: 'box', size: [size, size, size] },
+ motion: 'dynamic',
+ pos: at,
+ ...(massKg === undefined ? {} : { massKg }),
+ layer: CollisionLayer.Prop,
+ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,
+ }
+}
+
+function stepFor(w: PhysicsWorld, ticks: number, dt = DT): void {
+ for (let i = 0; i < ticks; i++) w.step(dt)
+}
+
+/**
+ * Steps `seconds` worth of SIMULATED time. The two engines do not agree on how
+ * long one step() is (header note 1), so a case that means "two seconds of
+ * gravity" must convert through the adapter rather than share a tick count.
+ */
+function stepSecondsFor(a: Adapter, w: PhysicsWorld, seconds: number): void {
+ stepFor(w, Math.round(seconds / a.stepSeconds))
+}
+
+/** A body at rest: dynamic, but its gravity contribution is neutralised. */
+function addParkedBody(w: PhysicsWorld, at: Vec3, massKg = 10): number {
+ const id = w.addBody(dynamicBoxDesc(at, 0.5, massKg))
+ // Park it by freezing and unfreezing: the seam's documented freeze path.
+ w.setMotionType(id, 'static')
+ w.setMotionType(id, 'dynamic')
+ return id
+}
+
+function conformance(a: Adapter): void {
+ describe(`PhysicsWorld conformance: ${a.name}`, () => {
+ const maybe = a.skip ?? (() => false)
+
+ /** The world for one case; `close()` disposes it. */
+ let world: PhysicsWorld | null = null
+ const open = (): PhysicsWorld => {
+ world = a.create()
+ return world
+ }
+ const close = (): void => {
+ world?.dispose()
+ world = null
+ }
+
+ // ── lifecycle ───────────────────────────────────────────────────────────
+
+ it('adds a body and returns a live id', () => {
+ const w = open()
+ const ground = w.addBody(groundDesc())
+ const p = pos()
+ w.getTransform(ground, p, rot())
+ expect(p.y).toBeCloseTo(-0.5, 3)
+ close()
+ })
+
+ it('hands out distinct ids for distinct bodies', () => {
+ const w = open()
+ expect(w.addBody(groundDesc())).not.toBe(w.addBody(dynamicBoxDesc(vec3(5, 10, 5))))
+ close()
+ })
+
+ it('removeBody drops the body; removing it again is a silent no-op', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0)))
+ w.removeBody(box)
+ expect(() => w.removeBody(box)).not.toThrow()
+ expect(() => w.getTransform(box, pos(), rot())).toThrow(/unknown physics body/)
+ close()
+ })
+
+ it('every other body accessor throws on an unknown id', () => {
+ const w = open()
+ const ghost = 987_654
+ expect(() => w.setTransform(ghost, vec3())).toThrow(/unknown physics body/)
+ expect(() => w.setMotionType(ghost, 'static')).toThrow(/unknown physics body/)
+ expect(() => w.getLinearVelocity(ghost, pos())).toThrow(/unknown physics body/)
+ expect(() => w.setLinearVelocity(ghost, vec3())).toThrow(/unknown physics body/)
+ expect(() => w.getAngularVelocity(ghost, pos())).toThrow(/unknown physics body/)
+ expect(() => w.setAngularVelocity(ghost, vec3())).toThrow(/unknown physics body/)
+ expect(() => w.isSettled(ghost)).toThrow(/unknown physics body/)
+ expect(() => w.wake(ghost)).toThrow(/unknown physics body/)
+ expect(() => w.applyForce(ghost, vec3(1, 0, 0))).toThrow(/unknown physics body/)
+ close()
+ })
+
+ // ── transforms ──────────────────────────────────────────────────────────
+
+ it('getTransform reports the transform the body was added with', () => {
+ const w = open()
+ const b = w.addBody({
+ shape: { type: 'box', size: [1, 1, 1] },
+ motion: 'static',
+ pos: vec3(3, 2, -7),
+ rot: quat(0, 1, 0, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop,
+ })
+ const p = pos()
+ const q = rot()
+ w.getTransform(b, p, q)
+ expect(p.x).toBeCloseTo(3, 5)
+ expect(p.y).toBeCloseTo(2, 5)
+ expect(p.z).toBeCloseTo(-7, 5)
+ expect(q.y).toBeCloseTo(1, 5)
+ expect(q.w).toBeCloseTo(0, 5)
+ close()
+ })
+
+ it('a body added without a rotation reads back as identity', () => {
+ const w = open()
+ const q = rot()
+ w.getTransform(w.addBody(groundDesc()), pos(), q)
+ expect(q).toEqual({ x: 0, y: 0, z: 0, w: 1 })
+ close()
+ })
+
+ it('setTransform teleports a STATIC body (remote-player mirror regression)', () => {
+ const w = open()
+ const mirror = w.addBody({
+ shape: { type: 'capsule', radius: 0.4, height: 1.8 },
+ motion: 'static',
+ pos: vec3(0, 1, 0),
+ layer: CollisionLayer.Player,
+ collidesWith: CollisionLayer.Static | CollisionLayer.Prop,
+ })
+ // Havok needs the explicit TELEPORT prestep dance for this to land at
+ // all (havokWorld.ts:179-185, marked CRITICAL); a regression here means
+ // remote players silently stop being collidable.
+ w.setTransform(mirror, vec3(9, 1, 4))
+ const p = pos()
+ w.getTransform(mirror, p, rot())
+ expect(p.x).toBeCloseTo(9, 3)
+ expect(p.y).toBeCloseTo(1, 3)
+ expect(p.z).toBeCloseTo(4, 3)
+ close()
+ })
+
+ it('setTransform teleports a DYNAMIC body', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))
+ w.setTransform(box, vec3(-5, 4, 0))
+ const p = pos()
+ w.getTransform(box, p, rot())
+ expect(p.x).toBeCloseTo(-5, 3)
+ expect(p.y).toBeCloseTo(4, 3)
+ close()
+ })
+
+ it('setTransform on a kinematic body is adopted on the next step', () => {
+ const w = open()
+ const k = w.addBody({
+ shape: { type: 'capsule', radius: 0.4, height: 1.8 },
+ motion: 'kinematic',
+ pos: vec3(0, 1, 0),
+ layer: CollisionLayer.Player,
+ collidesWith: 0,
+ })
+ w.setTransform(k, vec3(12, 1, 0))
+ w.step(DT)
+ const p = pos()
+ w.getTransform(k, p, rot())
+ expect(p.x).toBeGreaterThan(0.5)
+ expect(p.x).toBeLessThanOrEqual(12.001)
+ close()
+ })
+
+ it('setTransform also writes the rotation when one is given', () => {
+ const w = open()
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setTransform(b, vec3(0, 900, 0), quat(0, 0, 1, 0))
+ const q = rot()
+ w.getTransform(b, pos(), q)
+ expect(q.z).toBeCloseTo(1, 3)
+ expect(q.w).toBeCloseTo(0, 3)
+ close()
+ })
+
+ // ── motion types ────────────────────────────────────────────────────────
+
+ it('setMotionType freezes a dynamic body where it stands', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))
+ stepFor(w, 30)
+ w.setMotionType(box, 'static')
+ const frozen = pos()
+ w.getTransform(box, frozen, rot())
+ stepFor(w, 60)
+ const after = pos()
+ w.getTransform(box, after, rot())
+ expect(after.y).toBeCloseTo(frozen.y, 1)
+ close()
+ })
+
+ it('a body made dynamic again falls under gravity', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 10, 0)))
+ stepFor(w, 30)
+ w.setMotionType(box, 'static')
+ w.setMotionType(box, 'dynamic')
+ const before = pos()
+ w.getTransform(box, before, rot())
+ stepFor(w, 20)
+ const after = pos()
+ w.getTransform(box, after, rot())
+ expect(after.y).toBeLessThan(before.y - 0.5)
+ close()
+ })
+
+ it('setMotionType to the type it already has is a no-op', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setLinearVelocity(box, vec3(2, 0, 0))
+ w.setMotionType(box, 'dynamic')
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(v.x).toBeCloseTo(2, 3)
+ close()
+ })
+
+ // ── velocities ──────────────────────────────────────────────────────────
+
+ it('linear velocity round-trips', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setLinearVelocity(box, vec3(6, 0, 0))
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(v.x).toBeCloseTo(6, 5)
+ expect(v.y).toBeCloseTo(0, 5)
+ expect(v.z).toBeCloseTo(0, 5)
+ close()
+ })
+
+ it('a body given a linear velocity travels that way when stepped', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setLinearVelocity(box, vec3(6, 0, 0))
+ stepFor(w, 10)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ expect(p.x).toBeGreaterThan(0.5)
+ close()
+ })
+
+ it('angular velocity round-trips', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setAngularVelocity(box, vec3(0, 2, 0))
+ const v = pos()
+ w.getAngularVelocity(box, v)
+ expect(v.y).toBeCloseTo(2, 5)
+ close()
+ })
+
+ it('writing zeros through the setters stops the body', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0)))
+ w.setLinearVelocity(box, vec3(5, 0, 0))
+ w.setAngularVelocity(box, vec3(1, 0, 0))
+ w.setLinearVelocity(box, vec3(0, 0, 0))
+ w.setAngularVelocity(box, vec3(0, 0, 0))
+ const lv = pos()
+ const av = pos()
+ w.getLinearVelocity(box, lv)
+ w.getAngularVelocity(box, av)
+ expect(Math.hypot(lv.x, lv.y, lv.z)).toBeLessThan(0.01)
+ expect(Math.hypot(av.x, av.y, av.z)).toBeLessThan(0.01)
+ close()
+ })
+
+ // ── settle / wake ───────────────────────────────────────────────────────
+
+ it('static and kinematic bodies are settled by definition', () => {
+ const w = open()
+ expect(w.isSettled(w.addBody(groundDesc()))).toBe(true)
+ expect(
+ w.isSettled(
+ w.addBody({
+ shape: { type: 'capsule', radius: 0.4, height: 1.8 },
+ motion: 'kinematic',
+ pos: vec3(0, 1, 0),
+ layer: CollisionLayer.Player,
+ collidesWith: 0,
+ }),
+ ),
+ ).toBe(true)
+ close()
+ })
+
+ it('wake does not change a parked body velocity', () => {
+ const w = open()
+ const box = addParkedBody(w, vec3(0, 900, 0))
+ // Half the linear settle threshold: comfortably settled before and after,
+ // so the assertion reads the adapter's threshold rather than a literal.
+ // `toBeLessThanOrEqual` carries 1e-6 of slack because Havok stores velocity
+ // in f32 and 0.025 does not round-trip exactly.
+ const subThreshold = 0.025
+ w.setLinearVelocity(box, vec3(subThreshold, 0, 0))
+ expect(w.isSettled(box)).toBe(true)
+ w.wake(box)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(Math.hypot(v.x, v.y, v.z)).toBeLessThanOrEqual(subThreshold + 1e-6)
+ close()
+ })
+
+ it('wake on a non-dynamic body is a no-op, not a throw', () => {
+ const w = open()
+ const g = w.addBody(groundDesc())
+ expect(() => w.wake(g)).not.toThrow()
+ const p = pos()
+ w.getTransform(g, p, rot())
+ expect(p.y).toBeCloseTo(-0.5, 3)
+ close()
+ })
+
+ // ── raycast ─────────────────────────────────────────────────────────────
+
+ it('raycast returns the body, point, normal and a 0..1 fraction', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))
+ w.addBody(groundDesc())
+ stepFor(w, 30)
+ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)
+ expect(hit).not.toBeNull()
+ expect(hit?.bodyId).toBe(box)
+ // The segment is 10 long and the near face is at x = 1 → 4 m travelled.
+ expect(hit?.fraction).toBeCloseTo(0.4, 3)
+ expect(hit?.point.x).toBeCloseTo(1, 2)
+ expect(hit?.normal.x).toBeCloseTo(1, 2)
+ close()
+ })
+
+ it('raycast filters by the body layer the mask names', () => {
+ const w = open()
+ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))
+ const along = (mask: number): number | null =>
+ w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), mask)?.fraction ?? null
+ expect(along(CollisionLayer.Prop)).not.toBeNull()
+ expect(along(CollisionLayer.Static)).toBeNull()
+ expect(along(CollisionLayer.Static | CollisionLayer.Prop)).not.toBeNull()
+ close()
+ })
+
+ it('raycast misses cleanly when nothing is in the way', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ expect(w.raycast(vec3(0, 50, 0), vec3(0, 40, 0), CollisionLayer.Static)).toBeNull()
+ close()
+ })
+
+ it('raycast takes the first hit along the segment', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const near = w.addBody(dynamicBoxDesc(vec3(3, 1, 0), 1, 10))
+ w.addBody(dynamicBoxDesc(vec3(-3, 1, 0), 1, 10))
+ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)
+ expect(hit?.bodyId).toBe(near)
+ close()
+ })
+
+ it.skipIf(maybe('raycast reports'))(
+ 'raycast reports the surface point, not the travelled point',
+ () => {
+ // Measured on Havok: a ray 10 long hitting a box whose near face is at
+ // x = 1 reports fraction 0.4 with the point on that face. The mock's
+ // slab test reports the same, so this is pinned on both.
+ const w = open()
+ w.addBody(groundDesc())
+ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))
+ const hit = w.raycast(vec3(5, 1, 0), vec3(-5, 1, 0), CollisionLayer.Prop)
+ expect(hit?.fraction).toBeCloseTo(0.4, 3)
+ expect(hit?.point.x).toBeCloseTo(1, 3)
+ expect(hit?.point.y).toBeCloseTo(1, 3)
+ close()
+ },
+ )
+
+ // ── capsule sweep ───────────────────────────────────────────────────────
+
+ it('sweepCapsule returns an upward normal when landing on ground', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const hit = w.sweepCapsule(
+ vec3(0, 5, 0),
+ vec3(0, -1, 0),
+ 0.4,
+ 1.8,
+ CollisionLayer.Static | CollisionLayer.Prop,
+ )
+ expect(hit).not.toBeNull()
+ expect(hit?.normal.y).toBeGreaterThan(0.9)
+ // The capsule bottom starts at 4.1 and lands at 0: 4.1 of a 6 m sweep.
+ expect(hit?.fraction).toBeGreaterThan(0.5)
+ expect(hit?.fraction).toBeLessThan(1)
+ expect(hit?.point.y).toBeCloseTo(0, 1)
+ close()
+ })
+
+ it('sweepCapsule returns null when the path is clear', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ expect(
+ w.sweepCapsule(vec3(0, 5, 0), vec3(0, 4, 0), 0.4, 1.8, CollisionLayer.Static),
+ ).toBeNull()
+ close()
+ })
+
+ it('sweepCapsule filters by the collision mask', () => {
+ const w = open()
+ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))
+ const sweep = (mask: number) => w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask)
+ expect(sweep(CollisionLayer.Static)).toBeNull()
+ expect(sweep(CollisionLayer.Static | CollisionLayer.Prop)).not.toBeNull()
+ close()
+ })
+
+ it('sweepCapsule skips the excluded body and hits another one', () => {
+ const w = open()
+ const self = w.addBody({
+ shape: { type: 'capsule', radius: 0.4, height: 1.8 },
+ motion: 'kinematic',
+ pos: vec3(0, 1, 0),
+ layer: CollisionLayer.Player,
+ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 2, 10))
+ const mask = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player
+ expect(w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask)).not.toBeNull()
+ // The player's own kinematic capsule is on the Player layer and collides
+ // with Player, so without the exclusion it would be the first hit.
+ expect(w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, mask, self)).not.toBeNull()
+ close()
+ })
+
+ it('sweepCapsule fraction grows with the distance to the obstacle', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const near = w.sweepCapsule(vec3(0, 3, 0), vec3(0, -1, 0), 0.4, 1.8, CollisionLayer.Static)
+ const far = w.sweepCapsule(vec3(0, 5, 0), vec3(0, -1, 0), 0.4, 1.8, CollisionLayer.Static)
+ expect(near).not.toBeNull()
+ expect(far!.fraction).toBeGreaterThan(near!.fraction)
+ close()
+ })
+
+ it('sweepCapsule reports a horizontal normal against a wall', () => {
+ const w = open()
+ w.addBody({
+ shape: { type: 'box', size: [1, 4, 10] },
+ motion: 'static',
+ pos: vec3(2, 2, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Player | CollisionLayer.Prop,
+ })
+ const hit = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static)
+ expect(hit).not.toBeNull()
+ expect(Math.abs(hit!.normal.x)).toBeGreaterThan(0.9)
+ expect(Math.abs(hit!.normal.y)).toBeLessThan(0.2)
+ close()
+ })
+
+ it.skipIf(maybe('sweepCapsule offsetting'))(
+ 'sweepCapsule offsetting by the radius keeps a capsule out of a wall',
+ () => {
+ // Measured on Havok: a fat capsule and a thin one both report the
+ // surface point x = 1.5 (the wall face), but the fat one stops 0.35 m
+ // earlier along the sweep, because its centre is further from the face.
+ const w = open()
+ w.addBody({
+ shape: { type: 'box', size: [1, 4, 10] },
+ motion: 'static',
+ pos: vec3(2, 2, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Player | CollisionLayer.Prop,
+ })
+ const fat = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static)
+ const thin = w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.05, 1.8, CollisionLayer.Static)
+ expect(fat).not.toBeNull()
+ expect(thin).not.toBeNull()
+ expect(fat!.point.x).toBeCloseTo(1.5, 2)
+ expect(thin!.point.x).toBeCloseTo(1.5, 2)
+ expect(fat!.fraction).toBeLessThan(thin!.fraction)
+ close()
+ },
+ )
+
+ // ── constraints ─────────────────────────────────────────────────────────
+
+ it.skipIf(maybe('a weld holds'))(
+ 'a weld holds its pair in the creation-time relative pose',
+ () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ // Weld BEFORE the fall. Both boxes are the same size on the same floor,
+ // so once they settle they sit side by side at the same height and the
+ // creation-time offset would be zero — the mock has no contact solver
+ // to stack them, and a fixture that depends on stacking only works on
+ // an engine that has one. Welding while B is genuinely above A pins the
+ // offset (0.5) that the rest of the case is about.
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 30)
+ const pa = pos()
+ const pb = pos()
+ const q = rot()
+ w.getTransform(a, pa, q)
+ w.getTransform(b, pb, q)
+ const dy0 = pb.y - pa.y
+ expect(dy0).toBeGreaterThan(0.3)
+ expect(dy0).toBeLessThan(0.75)
+ // Give the pair a shove and let it settle again: the offset must hold.
+ w.setLinearVelocity(a, vec3(4, 0, 0))
+ stepFor(w, 90)
+ w.getTransform(a, pa, rot())
+ w.getTransform(b, pb, rot())
+ expect(Math.abs(pb.x - pa.x)).toBeLessThan(0.25)
+ expect(pb.y - pa.y).toBeGreaterThan(0.3)
+ expect(pb.y - pa.y).toBeLessThan(0.75)
+ w.removeConstraint(weld)
+ close()
+ },
+ )
+
+ it.skipIf(maybe('a welded pair resists'))(
+ 'a welded pair resists a velocity change on one member',
+ () => {
+ // Havok pulls a welded pair back over a couple of steps rather than
+ // letting one half run away: a 6 m/s kick on the upper box decays to
+ // 1.6 m/s within five steps and the pair is back at its offset by 60.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ const pb = pos()
+ w.setLinearVelocity(b, vec3(0, 6, 0))
+ stepFor(w, 5)
+ w.getTransform(b, pb, rot())
+ expect(pb.y).toBeLessThan(1.2)
+ stepFor(w, 55)
+ w.getTransform(b, pb, rot())
+ expect(pb.y).toBeCloseTo(0.75, 1)
+ close()
+ },
+ )
+
+ it.skipIf(maybe('removing a weld'))('removing a weld is a live handle, not a throw', () => {
+ // Havok: the two joints stay rigidly posed after removal, because a
+ // weld adds no energy and a stacked pair is already at rest. Asserted as
+ // "the pair is unchanged and nothing throws" — what the pair does next is
+ // Havok's business, not the seam's.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ const pa = pos()
+ const pb = pos()
+ w.getTransform(a, pa, rot())
+ w.getTransform(b, pb, rot())
+ expect(pa.y).toBeCloseTo(0.25, 2)
+ expect(pb.y).toBeCloseTo(0.75, 2)
+ w.removeConstraint(weld)
+ expect(() => w.removeConstraint(weld)).not.toThrow()
+ stepFor(w, 180)
+ const p2 = pos()
+ w.getTransform(a, p2, rot())
+ expect(p2.y).toBeCloseTo(0.25, 2)
+ close()
+ })
+
+ it.skipIf(maybe('a welded island'))(
+ 'a welded island stays rigid when a member is displaced',
+ () => {
+ // Measured on Havok: teleporting the follower of a weld drags the
+ // island along it over the following steps rather than instantly.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ const pa = pos()
+ const pb = pos()
+ // A purely lateral nudge: same height, so it neither buries the pair in
+ // the ground nor drives the solver a huge positional error in one step.
+ // Teleporting B far away (e.g. to x = 6, y = 2) drags the whole island
+ // through the ground, and what comes back out is the solver untangling
+ // that error, not the weld.
+ w.setTransform(b, vec3(0, 0.75, 0.5))
+ w.step(DT)
+ w.getTransform(a, pa, rot())
+ w.getTransform(b, pb, rot())
+ // The weld pulled B back toward A's pose rather than leaving it where it
+ // was dropped, and A began to follow B instead of staying put.
+ expect(pb.z).toBeLessThan(0.5)
+ expect(pa.z).toBeGreaterThan(0)
+ // "Stays rigid" is the claim worth pinning. Measured on Havok, the
+ // island does not snap back within one step — it keeps sliding for a
+ // while — but it never tears: after settling the vertical offset it was
+ // welded with is intact and the lateral displacement has closed, so
+ // the nudge was absorbed by the island rather than by the joint
+ // stretching.
+ stepFor(w, 60)
+ w.getTransform(a, pa, rot())
+ w.getTransform(b, pb, rot())
+ expect(pb.y - pa.y).toBeCloseTo(0.5, 1)
+ expect(pb.z - pa.z).toBeCloseTo(0, 1)
+ close()
+ },
+ )
+
+ it('removing a weld frees the follower', () => {
+ // What "freed" means at the seam: once the joint is gone the two bodies
+ // are independent, so a velocity change on the follower moves the
+ // follower and leaves the driver exactly where it was.
+ //
+ // It deliberately does NOT assert that the follower then rests at some
+ // particular height. On a stacked pair resting on the ground that is
+ // engine behaviour and the two engines disagree: the mock has no
+ // body-body contacts, so the follower drops straight through back to the
+ // floor (0.25) inside this window, while Havok's solver keeps it on the
+ // driver and carries it to 1.609. Both are "no longer welded", which is
+ // the property that belongs to the seam; a per-engine landing height is
+ // pinned separately in each engine branch. Measured: with the pair
+ // grounded and the follower kicked to +6 m/s after removal, Havok leaves
+ // the driver at 0.250 and the follower at 1.609 after 30 steps; the mock
+ // leaves the driver at 0.250 and the follower at 0.250, having already
+ // arced up and landed back on the floor.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ w.removeConstraint(weld)
+ const pa = pos()
+ w.getTransform(a, pa, rot())
+ expect(pa.y).toBeCloseTo(0.25, 2)
+ w.setLinearVelocity(b, vec3(0, 6, 0))
+ stepFor(w, 30)
+ const pa2 = pos()
+ const pb = pos()
+ w.getTransform(a, pa2, rot())
+ w.getTransform(b, pb, rot())
+ // The driver did not move at all, and the follower has left the pose the
+ // weld held it in (0.75) — up on Havok, down through the missing contact
+ // on the mock. A still-welded follower could not do either.
+ expect(pa2.y).toBeCloseTo(0.25, 2)
+ expect(Math.abs(pb.y - 0.75)).toBeGreaterThan(0.1)
+ close()
+ })
+
+ // Mock-only, so gated on the adapter itself rather than through `maybe`:
+ // `skip` lists what the MOCK cannot do, not what this case is good for.
+ it.skipIf(a.name !== 'MockPhysicsWorld')(
+ 'a freed follower lands on the floor once it has arced up (mock only)',
+ () => {
+ // The mock half of the case above, pinned on its own number. With no
+ // body-body contacts the follower falls straight through the driver and
+ // is caught by the ground plane, so it settles beside it rather than on
+ // top of it. Havok's solver stacks them, so this cannot be shared.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ w.removeConstraint(weld)
+ w.setLinearVelocity(b, vec3(0, 6, 0))
+ // Enough steps to arc up and come back down: 6 m/s against -16.5 m/s² is
+ // ~1.1 s of flight, which is 33 steps at the 30 Hz tick.
+ stepFor(w, 90)
+ const pb = pos()
+ w.getTransform(b, pb, rot())
+ expect(pb.y).toBeCloseTo(0.25, 2)
+ expect(w.isSettled(b)).toBe(true)
+ close()
+ },
+ )
+
+ it('setConstraintMotor on a weld, or on an unknown id, is a silent no-op', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.26, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.78, 0), 0.5, 10))
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ expect(() => w.setConstraintMotor(weld, { targetVelocity: 9, maxForce: 100 })).not.toThrow()
+ expect(() =>
+ w.setConstraintMotor(999_999, { targetVelocity: 9, maxForce: 100 }),
+ ).not.toThrow()
+ stepFor(w, 60)
+ close()
+ })
+
+ it.skipIf(maybe('a rope'))('a rope is slack below its length and taut at it', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const anchor = w.addBody({
+ shape: { type: 'box', size: [0.4, 0.4, 0.4] },
+ motion: 'static',
+ pos: vec3(0, 6, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const bob = w.addBody(dynamicBoxDesc(vec3(1.5, 6, 0), 0.4, 10))
+ const rope = w.addConstraint({
+ type: 'rope',
+ bodyA: anchor,
+ bodyB: bob,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ length: 2,
+ })
+ let maxDist = 0
+ let minY = Infinity
+ const p = pos()
+ for (let i = 0; i < 300; i++) {
+ w.step(DT)
+ w.getTransform(bob, p, rot())
+ maxDist = Math.max(maxDist, Math.hypot(p.x, p.y - 6, p.z))
+ minY = Math.min(minY, p.y)
+ }
+ expect(maxDist).toBeLessThanOrEqual(2.3)
+ // A taut 2 m pendulum swings through ~4 m below a 6 m anchor.
+ expect(minY).toBeLessThanOrEqual(4.6)
+ w.removeConstraint(rope)
+ close()
+ })
+
+ it.skipIf(maybe('a hinge'))('a hinge with limits caps the swing and holds the door up', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const post = w.addBody({
+ shape: { type: 'box', size: [0.4, 0.4, 0.4] },
+ motion: 'static',
+ pos: vec3(10, 2, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const door = w.addBody(dynamicBoxDesc(vec3(10.9, 2, 0), 0.4, 10))
+ w.addConstraint({
+ type: 'hinge',
+ bodyA: post,
+ bodyB: door,
+ anchorA: vec3(0.45, 0, 0),
+ anchorB: vec3(-0.45, 0, 0),
+ axisA: vec3(0, 1, 0),
+ axisB: vec3(0, 1, 0),
+ limits: { min: -Math.PI / 4, max: Math.PI / 4 },
+ })
+ w.setLinearVelocity(door, vec3(0, 0, 8))
+ const p = pos()
+ let maxAngle = 0
+ for (let i = 0; i < 90; i++) {
+ w.step(DT)
+ w.getTransform(door, p, rot())
+ maxAngle = Math.max(maxAngle, Math.abs(Math.atan2(p.z, p.x - 10)))
+ }
+ expect(maxAngle).toBeGreaterThan(0.2)
+ expect(maxAngle).toBeLessThanOrEqual(Math.PI / 4 + 0.25)
+ w.getTransform(door, p, rot())
+ expect(Math.abs(p.y - 2)).toBeLessThan(0.25)
+ close()
+ })
+
+ it.skipIf(maybe('a motorized hinge'))(
+ 'a motorized hinge spins a wheel up and retunes to brake it',
+ () => {
+ const w = open()
+ const mount = w.addBody({
+ shape: { type: 'box', size: [0.4, 0.4, 0.4] },
+ motion: 'static',
+ pos: vec3(20, 3, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const wheel = w.addBody({
+ shape: { type: 'cylinder', radius: 0.6, height: 0.2 },
+ motion: 'dynamic',
+ pos: vec3(20, 3, 0.4),
+ massKg: 8,
+ layer: CollisionLayer.Prop,
+ collidesWith: CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const motorId = w.addConstraint({
+ type: 'hinge',
+ bodyA: mount,
+ bodyB: wheel,
+ anchorA: vec3(0, 0, 0.4),
+ anchorB: vec3(0, 0, 0),
+ axisA: vec3(0, 0, 1),
+ axisB: vec3(0, 1, 0), // a Babylon cylinder's own axis is +Y
+ motor: { targetVelocity: 6, maxForce: 500 },
+ })
+ stepFor(w, 90)
+ const av = pos()
+ w.getAngularVelocity(wheel, av)
+ expect(Math.hypot(av.x, av.y, av.z)).toBeGreaterThan(4)
+ w.setConstraintMotor(motorId, { targetVelocity: 0, maxForce: 500 })
+ stepFor(w, 60)
+ w.getAngularVelocity(wheel, av)
+ expect(Math.hypot(av.x, av.y, av.z)).toBeLessThan(0.5)
+ close()
+ },
+ )
+
+ it.skipIf(maybe('a slider'))(
+ 'a slider travels along its rail, respects its limits and stays on it',
+ () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const rail = w.addBody({
+ shape: { type: 'box', size: [0.4, 0.4, 0.4] },
+ motion: 'static',
+ pos: vec3(30, 2, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const drawer = w.addBody(dynamicBoxDesc(vec3(30, 2, 0.6), 0.4, 10))
+ w.addConstraint({
+ type: 'slider',
+ bodyA: rail,
+ bodyB: drawer,
+ anchorA: vec3(0, 0, 0.6),
+ anchorB: vec3(0, 0, 0),
+ axisA: vec3(0, 0, 1),
+ axisB: vec3(0, 0, 1),
+ limits: { min: -0.5, max: 1.0 },
+ })
+ w.setLinearVelocity(drawer, vec3(0, 0, 5))
+ const p = pos()
+ let maxZ = -Infinity
+ let minZ = Infinity
+ let maxOffAxis = 0
+ for (let i = 0; i < 120; i++) {
+ w.step(DT)
+ w.getTransform(drawer, p, rot())
+ maxZ = Math.max(maxZ, p.z)
+ minZ = Math.min(minZ, p.z)
+ maxOffAxis = Math.max(maxOffAxis, Math.abs(p.x - 30), Math.abs(p.y - 2))
+ if (i === 60) w.setLinearVelocity(drawer, vec3(0, 0, -5))
+ }
+ expect(maxZ).toBeGreaterThan(1.3)
+ expect(maxZ).toBeLessThanOrEqual(1.85)
+ expect(minZ).toBeGreaterThanOrEqual(-0.15)
+ expect(maxOffAxis).toBeLessThanOrEqual(0.15)
+ close()
+ },
+ )
+
+ it.skipIf(maybe('a spring'))('a spring settles at roughly its rest length', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const mount = w.addBody({
+ shape: { type: 'box', size: [0.4, 0.4, 0.4] },
+ motion: 'static',
+ pos: vec3(40, 6, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const bob = w.addBody(dynamicBoxDesc(vec3(40, 5.5, 0), 0.4, 10))
+ w.addConstraint({
+ type: 'spring',
+ bodyA: mount,
+ bodyB: bob,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ restLength: 1.5,
+ stiffness: 400,
+ damping: 15,
+ })
+ stepFor(w, 300)
+ const p = pos()
+ w.getTransform(bob, p, rot())
+ const dist = Math.hypot(p.x - 40, p.y - 6, p.z)
+ expect(dist).toBeGreaterThan(1.2)
+ expect(dist).toBeLessThan(2.2)
+ close()
+ })
+
+ it('every constraint variant is accepted and keeps a live handle', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const mk = (y: number) => w.addBody(dynamicBoxDesc(vec3(100, y, 0), 0.4, 10))
+ const a = mk(1)
+ const b = mk(2)
+ const ids = [
+ w.addConstraint({ type: 'weld', bodyA: a, bodyB: b }),
+ w.addConstraint({
+ type: 'rope',
+ bodyA: a,
+ bodyB: b,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ length: 2,
+ collision: false,
+ }),
+ w.addConstraint({
+ type: 'hinge',
+ bodyA: a,
+ bodyB: b,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ axisA: vec3(0, 1, 0),
+ axisB: vec3(0, 1, 0),
+ limits: { min: -1, max: 1 },
+ friction: 0.1,
+ motor: { targetVelocity: 1, maxForce: 10 },
+ }),
+ w.addConstraint({
+ type: 'slider',
+ bodyA: a,
+ bodyB: b,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ axisA: vec3(0, 0, 1),
+ axisB: vec3(0, 0, 1),
+ motor: { targetVelocity: 1, maxForce: 10 },
+ }),
+ w.addConstraint({
+ type: 'spring',
+ bodyA: a,
+ bodyB: b,
+ anchorA: vec3(),
+ anchorB: vec3(),
+ restLength: 1,
+ stiffness: 100,
+ damping: 5,
+ }),
+ ]
+ expect(new Set(ids).size).toBe(ids.length)
+ for (const id of ids) {
+ expect(() => w.setConstraintMotor(id, { targetVelocity: 0, maxForce: 1 })).not.toThrow()
+ expect(() => w.removeConstraint(id)).not.toThrow()
+ }
+ close()
+ })
+
+ // ── disposal ────────────────────────────────────────────────────────────
+
+ it('dispose is safe after bodies have already been removed', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 2, 0)))
+ const other = w.addBody(dynamicBoxDesc(vec3(2, 2, 0)))
+ w.addConstraint({ type: 'weld', bodyA: box, bodyB: other })
+ w.removeBody(box)
+ expect(() => w.dispose()).not.toThrow()
+ expect(() => w.dispose()).not.toThrow()
+ world = null
+ })
+
+ // ── engine-independent constants ─────────────────────────────────────────
+ // These must hold for every adapter, so they run for both worlds. The
+ // acceleration-shaped ones are additionally pinned in the engine describe
+ // below, where the numbers have been measured.
+
+ describe('seam constants', () => {
+ it('settle thresholds sit between 0.01 and 0.1 m/s, and 0.1 and 0.2 rad/s', () => {
+ // The thresholds are read back through the adapter under test, not off
+ // a literal: this case is about WHERE the seam's threshold lies, which
+ // is what the game is tuned against. Exactly-at-the-boundary behaviour
+ // is deliberately not pinned (header note 2: Havok compares len² >
+ // threshold² against an f32, so a body at exactly 0.05 is reported
+ // unsettled there and settled on the mock).
+ const w = open()
+ // Just inside both thresholds: settled.
+ const inside = addParkedBody(w, vec3(0, 900, 0))
+ w.setLinearVelocity(inside, vec3(0.01, 0, 0))
+ w.setAngularVelocity(inside, vec3(0, 0.1, 0))
+ expect(w.isSettled(inside)).toBe(true)
+ // Comfortably above either one: not settled.
+ const fast = addParkedBody(w, vec3(50, 900, 0))
+ w.setLinearVelocity(fast, vec3(1, 0, 0))
+ expect(w.isSettled(fast)).toBe(false)
+ const spinning = addParkedBody(w, vec3(100, 900, 0))
+ w.setAngularVelocity(spinning, vec3(0, 1, 0))
+ expect(w.isSettled(spinning)).toBe(false)
+ // Just over each threshold: not settled. 0.06 and 0.16 sit a clear
+ // f32 step above 0.05 and 0.15 without landing on the boundary.
+ const justOverLinear = addParkedBody(w, vec3(150, 900, 0))
+ w.setLinearVelocity(justOverLinear, vec3(0.06, 0, 0))
+ expect(w.isSettled(justOverLinear)).toBe(false)
+ const justOverAngular = addParkedBody(w, vec3(200, 900, 0))
+ w.setAngularVelocity(justOverAngular, vec3(0, 0.16, 0))
+ expect(w.isSettled(justOverAngular)).toBe(false)
+ close()
+ })
+
+ it('gravity is (0, -16.5, 0) m/s^2', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ w.setLinearVelocity(box, vec3(0, 0, 0))
+ // Two seconds of free fall, asked for in simulated seconds because the
+ // two engines advance by different amounts per step(): the mock reaches
+ // -29.9 m/s in 60 steps of 1/30 s, the Havok plugin -31.4 m/s in 120
+ // steps of its fixed 1/60 s. Either way it is nowhere near a 9.81 m/s²
+ // world, which would be -19.
+ stepSecondsFor(a, w, 2)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ // The window is the two-second band both engines land inside; it would
+ // not survive a 9.81 m/s² world, which would be -19.
+ expect(v.y).toBeLessThan(-29)
+ expect(v.y).toBeGreaterThan(-34)
+ close()
+ })
+
+ it('restitution is near zero: a dropped box does not bounce', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 8, 0), 0.7, 25))
+ let landedAt = -Infinity
+ for (let i = 0; i < 300; i++) {
+ w.step(DT)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ if (p.y < 0.36) {
+ landedAt = p.y
+ break
+ }
+ }
+ expect(landedAt).not.toBe(-Infinity)
+ stepFor(w, 30)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ // A restitution of 0.05 cannot lift a 25 kg box more than a whisker.
+ expect(p.y).toBeLessThan(landedAt + 0.35)
+ expect(p.y).toBeLessThan(0.5)
+ close()
+ })
+ })
+
+ // ── engine-specific dynamics ────────────────────────────────────────────
+ // These assert the numeric feel the game is tuned against. The mock's
+ // values are exact by construction, so they are marked separately from the
+ // Havok numbers where the two genuinely differ.
+
+ if (a.name === 'MockPhysicsWorld') {
+ it('exposes the same seam constants the Havok adapter is built from', () => {
+ // The shared cases above read gravity and the settle thresholds back
+ // through the adapter, so they cannot see a literal drift in either
+ // one. This pins the mock's own values against the numbers measured off
+ // havokWorld.ts (the header block's list), so the two adapters stay
+ // declared to the same constants and the shared cases mean something.
+ expect(MOCK_GRAVITY).toBe(-16.5)
+ expect(MOCK_SETTLE_LINEAR).toBe(0.05)
+ expect(MOCK_SETTLE_ANGULAR).toBe(0.15)
+ })
+
+ it('applies its own gravity, damping and mass, exactly', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ // Semi-implicit Euler at 30 Hz: v += g·dt, then v *= (1 - 0.05·dt).
+ // Two seconds is -16.5 × 2 = -33 before the damping losses.
+ for (let i = 0; i < 60; i++) w.step(MOCK_TICK)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(v.y).toBeLessThan(-29)
+ expect(v.y).toBeGreaterThan(-33)
+ close()
+ })
+
+ it('a body rests on the analytic ground plane and settles', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))
+ stepFor(w, 240)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ expect(p.y).toBeCloseTo(0.35, 3)
+ expect(w.isSettled(box)).toBe(true)
+ close()
+ })
+
+ it('a body in free fall is never settled', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 500, 0)))
+ stepFor(w, 30)
+ expect(w.isSettled(box)).toBe(false)
+ close()
+ })
+
+ it('a resting body carries no angular velocity once the ground stops it', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))
+ w.setAngularVelocity(box, vec3(0, 5, 0))
+ stepFor(w, 240)
+ const v = pos()
+ w.getAngularVelocity(box, v)
+ expect(Math.hypot(v.x, v.y, v.z)).toBe(0)
+ close()
+ })
+
+ it('applyForce accelerates in the force direction and ignores non-dynamic bodies', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ const ground = w.addBody(groundDesc())
+ for (let i = 0; i < 10; i++) {
+ w.applyForce(box, vec3(10, 0, 0))
+ w.step(DT)
+ }
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ // a = F/m = 1 m/s^2 for 10 kg, so about 0.33 m/s after a third second.
+ expect(v.x).toBeCloseTo(1 / 3, 1)
+ w.applyForce(ground, vec3(1000, 0, 0))
+ stepFor(w, 10)
+ const p = pos()
+ w.getTransform(ground, p, rot())
+ expect(p.x).toBeCloseTo(0, 3)
+ close()
+ })
+
+ it('an analytic cast plane stops casts but not bodies', () => {
+ const w = createMockPhysicsWorld()
+ w.addCast({ normal: vec3(-1, 0, 0), offset: 2, minY: -1, maxY: 3 })
+ expect(w.castCount()).toBe(1)
+ expect(
+ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),
+ ).not.toBeNull()
+ // No ground plane at all, so a body just keeps falling.
+ const box = w.addBody(dynamicBoxDesc(vec3(-3, 10, 0), 0.5, 10))
+ stepFor(w, 60)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ expect(p.y).toBeLessThan(0)
+ close()
+ })
+
+ it('a patched cast plane only hits inside its patch', () => {
+ const w = createMockPhysicsWorld()
+ w.addCast({ normal: vec3(-1, 0, 0), offset: 2, minY: -1, maxY: 3, minZ: -1, maxZ: 1 })
+ expect(
+ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),
+ ).not.toBeNull()
+ expect(
+ w.sweepCapsule(vec3(-3, 1, 8), vec3(3, 1, 8), 0.4, 1.8, CollisionLayer.Static),
+ ).toBeNull()
+ expect(
+ w.sweepCapsule(vec3(-3, 9, 0), vec3(3, 9, 0), 0.4, 1.8, CollisionLayer.Static),
+ ).toBeNull()
+ close()
+ })
+
+ it('groundHeightAt reports the analytic plane, not a wall cast', () => {
+ const w = createMockPhysicsWorld()
+ w.addGroundPlane(0)
+ w.markLastCastAsGround()
+ w.addCast({ normal: vec3(-1, 0, 0), offset: 2 })
+ expect(w.groundHeightAt(0, 0)).toBe(0)
+ expect(
+ w.sweepCapsule(vec3(-3, 1, 0), vec3(3, 1, 0), 0.4, 1.8, CollisionLayer.Static),
+ ).not.toBeNull()
+ close()
+ })
+
+ it('is bit-identical across runs', () => {
+ const run = (): number[] => {
+ const w = createMockPhysicsWorld()
+ w.addCast({ normal: vec3(0, 1, 0), offset: 0 })
+ w.markLastCastAsGround()
+ w.addCast({ normal: vec3(-1, 0, 0), offset: 2 })
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 5, 0), 0.7, 25))
+ const out: number[] = []
+ for (let i = 0; i < 200; i++) {
+ w.setLinearVelocity(box, vec3(3 + Math.sin(i * 0.1), 0, 0))
+ w.step(DT)
+ const p = pos()
+ w.getTransform(box, p, rot())
+ out.push(p.x, p.y, p.z)
+ }
+ close()
+ return out
+ }
+ expect(run()).toEqual(run())
+ })
+
+ it('every case the mock skips still runs somewhere', async () => {
+ // A `skip` entry naming a title that no longer exists silently skips
+ // nothing, which is how the mock ended up running a case its header
+ // claimed it could not model. Each prefix below must be a prefix of a
+ // title this file actually defines; read them out of the source so the
+ // check cannot go stale when a case is renamed or removed.
+ const source = await readFile(new URL(import.meta.url), 'utf8')
+ const titles = [
+ ...source.matchAll(/\bit(?:\.skipIf\([\s\S]*?\)\s*)?\(\s*\n?\s*'([^']+)'/g),
+ ].map((m) => m[1]!)
+ expect(titles.length).toBeGreaterThan(40)
+ const dead = MOCK_SKIP_PREFIXES.filter((p) => !titles.some((t) => t.startsWith(p)))
+ expect(dead).toEqual([])
+ })
+ } else {
+ it('a freed follower stays on the driver on Havok’s solver', () => {
+ // The Havok half of "removing a weld frees the follower": the contact
+ // solver keeps the upper box stacked on the lower one, so after the same
+ // 30-step window the shared case finds it up at ~1.6 rather than back
+ // down on the floor. Measured: 1.609.
+ const w = open()
+ w.addBody(groundDesc())
+ const a = w.addBody(dynamicBoxDesc(vec3(0, 0.25, 0), 0.5, 10))
+ const b = w.addBody(dynamicBoxDesc(vec3(0, 0.75, 0), 0.5, 10))
+ const weld = w.addConstraint({ type: 'weld', bodyA: a, bodyB: b })
+ stepFor(w, 60)
+ w.removeConstraint(weld)
+ w.setLinearVelocity(b, vec3(0, 6, 0))
+ stepFor(w, 30)
+ const pb = pos()
+ w.getTransform(b, pb, rot())
+ expect(pb.y).toBeGreaterThan(0.75)
+ expect(pb.y).toBeLessThan(2)
+ close()
+ })
+
+ it.skipIf(maybe('step advances'))(
+ 'step advances a fixed 1/60 s regardless of the dt passed (Havok plugin)',
+ () => {
+ const probe = (dt: number, ticks: number) => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ stepFor(w, ticks, dt)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ close()
+ return v.y
+ }
+ // 30 steps at 30 Hz and 30 steps at 15 Hz are the same amount of
+ // simulated time, because the plugin uses its own fixed step time.
+ expect(probe(1 / 30, 30)).toBeCloseTo(probe(1 / 15, 30), 3)
+ // An extra second of simulation is very nearly twice the velocity.
+ expect(probe(1 / 60, 120) / probe(1 / 60, 60)).toBeGreaterThan(1.9)
+ expect(probe(1 / 60, 120) / probe(1 / 60, 60)).toBeLessThan(2.1)
+ // One simulated second of this gravity: about -16.5 m/s.
+ expect(probe(1 / 30, 60)).toBeLessThan(-15)
+ expect(probe(1 / 30, 60)).toBeGreaterThan(-17)
+ },
+ )
+
+ it('a resting dynamic body on the ground settles', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 3, 0), 0.7, 25))
+ stepFor(w, 240)
+ expect(w.isSettled(box)).toBe(true)
+ close()
+ })
+
+ it('a body in free fall is never settled', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 500, 0)))
+ stepFor(w, 30)
+ expect(w.isSettled(box)).toBe(false)
+ close()
+ })
+
+ it('applyForce accelerates a dynamic body; static and kinematic are ignored', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 1, 0), 0.5, 10))
+ w.setLinearVelocity(box, vec3(0, 0, 0))
+ for (let i = 0; i < 60; i++) {
+ w.applyForce(box, vec3(100, 0, 0))
+ w.step(DT)
+ }
+ const p = pos()
+ w.getTransform(box, p, rot())
+ expect(p.x).toBeGreaterThan(0.3)
+ const k = w.addBody({
+ shape: { type: 'sphere', radius: 0.5 },
+ motion: 'kinematic',
+ pos: vec3(20, 5, 0),
+ layer: CollisionLayer.Player,
+ collidesWith: 0,
+ })
+ w.applyForce(k, vec3(500, 0, 0))
+ stepFor(w, 30)
+ const kp = pos()
+ w.getTransform(k, kp, rot())
+ expect(kp.x).toBeCloseTo(20, 3)
+ close()
+ })
+
+ it('mass scales the response to an equal force', () => {
+ const w = open()
+ const heavy = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 40))
+ const light = w.addBody(dynamicBoxDesc(vec3(50, 900, 0), 0.5, 10))
+ for (let i = 0; i < 20; i++) {
+ w.applyForce(heavy, vec3(400, 0, 0))
+ w.applyForce(light, vec3(400, 0, 0))
+ w.step(DT)
+ }
+ const hv = pos()
+ const lv = pos()
+ w.getLinearVelocity(heavy, hv)
+ w.getLinearVelocity(light, lv)
+ expect(lv.x / Math.max(hv.x, 1e-9)).toBeGreaterThan(3)
+ expect(lv.x / Math.max(hv.x, 1e-9)).toBeLessThan(5)
+ close()
+ })
+
+ it('linear damping is light (0.05): a coasting body keeps its speed', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ w.setLinearVelocity(box, vec3(10, 0, 0))
+ stepFor(w, 30)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(v.x).toBeGreaterThan(9.5)
+ expect(v.x).toBeLessThan(10)
+ close()
+ })
+
+ it('angular damping is strong (0.6): a free spin decays within seconds', () => {
+ const w = open()
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 900, 0), 0.5, 10))
+ w.setAngularVelocity(box, vec3(0, 10, 0))
+ stepFor(w, 60)
+ const v = pos()
+ w.getAngularVelocity(box, v)
+ expect(v.y).toBeLessThan(6)
+ expect(v.y).toBeGreaterThan(0)
+ close()
+ })
+
+ it('surface friction is high enough that a sliding box stops quickly', () => {
+ const w = open()
+ w.addBody(groundDesc())
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 0.36, 0), 0.7, 25))
+ w.setLinearVelocity(box, vec3(10, 0, 0))
+ stepFor(w, 180)
+ const v = pos()
+ w.getLinearVelocity(box, v)
+ expect(Math.abs(v.x)).toBeLessThan(1.5)
+ close()
+ })
+
+ it('a body knocked off a ledge falls; the ledge does not move it sideways', () => {
+ const w = open()
+ w.addBody({
+ shape: { type: 'box', size: [4, 1, 10] },
+ motion: 'static',
+ pos: vec3(0, 0.5, 0),
+ layer: CollisionLayer.Static,
+ collidesWith: CollisionLayer.Prop | CollisionLayer.Player,
+ })
+ const box = w.addBody(dynamicBoxDesc(vec3(0, 2, 0), 0.7, 25))
+ stepFor(w, 60)
+ const resting = pos()
+ w.getTransform(box, resting, rot())
+ expect(resting.y).toBeCloseTo(1.35, 2)
+ w.setLinearVelocity(box, vec3(8, 0, 0))
+ stepFor(w, 90)
+ const gone = pos()
+ w.getTransform(box, gone, rot())
+ expect(gone.y).toBeLessThan(0)
+ close()
+ })
+ }
+ })
+}
+
+conformance(havokAdapter)
+conformance(mockAdapter)
new file mode 100644
new file mode 100644
@@ -0,0 +1,790 @@
@@ -0,0 +1,790 @@
+import {
+ quat,
+ vec3,
+ v3copy,
+ v3dot,
+ v3lengthSq,
+ v3scale,
+ v3set,
+ type Quat,
+ type Vec3,
+} from '@openvibe/shared'
+import {
+ CollisionLayer,
+ type BodyDesc,
+ type BodyId,
+ type ConstraintDesc,
+ type ConstraintId,
+ type ConstraintMotor,
+ type MotionType,
+ type PhysicsWorld,
+ type RayHit,
+ type SweepHit,
+} from './types.js'
+
+/**
+ * Deterministic, wasm-free PhysicsWorld for tests and for any consumer that
+ * needs a collision oracle without an engine (ADR-0007 decision 2: the seam
+ * must be testable without wasm, and the engine swap must be "tested, not
+ * assumed").
+ *
+ * It is deliberately NOT a miniature physics engine:
+ *
+ * - **Analytic ground plane.** `addGroundPlane()` installs an infinite plane
+ * y = 0 — the terrain the server builds — and capsule sweeps and rays resolve
+ * against it exactly. `addCast()` adds further analytic surfaces (a wall, a
+ * ceiling, a step) that only casts see; that is the scripted cast table.
+ * - **Boxes, not rigid bodies.** Every shape is reduced to a world-axis-aligned
+ * bounding box that never rotates, and nothing stacks. A body falls, lands and
+ * rests; it does not push, roll, bounce off or topple anything.
+ * - **Weld is real**, because it is the one constraint the prop-island and
+ * settle bookkeeping depend on: members of a weld group move as one.
+ * Rope, hinge, slider and spring keep live handles but exert no force.
+ *
+ * Everything is f64, iterated in insertion order, with no wall-clock time and
+ * no hashing, so two runs of the same script are bit-identical. That is what
+ * makes the mock usable as the movement determinism oracle.
+ *
+ * See conformance.test.ts ("what the mock deliberately does not model") for the
+ * full list of gaps a real adapter must close.
+ */
+
+/** 30 Hz — the tick rate both the server and client prediction run at. */
+export const MOCK_TICK = 1 / 30
+
+export const MOCK_GRAVITY = -16.5
+/** Must match the Havok adapter's settle thresholds (havokWorld.ts:72-73). */
+export const MOCK_SETTLE_LINEAR = 0.05
+export const MOCK_SETTLE_ANGULAR = 0.15
+export const MOCK_DEFAULT_MASS_KG = 10
+export const MOCK_MATERIAL = { friction: 0.75, staticFriction: 0.85, restitution: 0.05 } as const
+export const MOCK_LINEAR_DAMPING = 0.05
+export const MOCK_ANGULAR_DAMPING = 0.6
+
+interface MockBody {
+ id: BodyId
+ desc: BodyDesc
+ motion: MotionType
+ pos: Vec3
+ rot: Quat
+ linVel: Vec3
+ angVel: Vec3
+ /** Forces accumulated since the last step (seam semantics: applyForce is a force, not an impulse). */
+ force: Vec3
+ torque: Vec3
+ massKg: number
+ /** Axis-aligned half extents; a capsule is bounded by radius in x/z and height/2 in y. */
+ half: Vec3
+ /** Weld bookkeeping: the rigid group this body follows, if any. */
+ weld: WeldGroup | null
+}
+
+/** A rigid group of bodies linked by welds, with A as the driver. */
+interface WeldGroup {
+ driver: MockBody
+ members: { body: MockBody; offset: Vec3 }[]
+}
+
+interface MockConstraint {
+ id: ConstraintId
+ desc: ConstraintDesc
+ motor: ConstraintMotor | null
+}
+
+/** A castable analytic surface: { p : dot(n, p) = offset } clipped by an AABB patch. */
+interface CastPlane {
+ normal: Vec3
+ offset: number
+ patchMin: Vec3 | null
+ patchMax: Vec3 | null
+ /** Ground casts also stop bodies; a wall cast only stops casts. */
+ isGround: boolean
+}
+
+function setQuat(out: Quat, q: Quat | undefined): void {
+ if (q) {
+ out.x = q.x
+ out.y = q.y
+ out.z = q.z
+ out.w = q.w
+ } else {
+ out.x = 0
+ out.y = 0
+ out.z = 0
+ out.w = 1
+ }
+}
+
+/**
+ * Half extents of a shape, axis-aligned about its centre. A capsule's radius
+ * inflates x/z only; a trimesh collapses to its local bounds (the mock has no
+ * triangle queries).
+ */
+function halfExtents(desc: BodyDesc): Vec3 {
+ switch (desc.shape.type) {
+ case 'box':
+ return vec3(desc.shape.size[0] / 2, desc.shape.size[1] / 2, desc.shape.size[2] / 2)
+ case 'sphere':
+ return vec3(desc.shape.radius, desc.shape.radius, desc.shape.radius)
+ case 'cylinder':
+ case 'capsule':
+ return vec3(desc.shape.radius, desc.shape.height / 2, desc.shape.radius)
+ case 'trimesh': {
+ const { positions } = desc.shape
+ let minX = Infinity
+ let minY = Infinity
+ let minZ = Infinity
+ let maxX = -Infinity
+ let maxY = -Infinity
+ let maxZ = -Infinity
+ for (let i = 0; i + 2 < positions.length; i += 3) {
+ if (positions[i]! < minX) minX = positions[i]!
+ if (positions[i]! > maxX) maxX = positions[i]!
+ if (positions[i + 1]! < minY) minY = positions[i + 1]!
+ if (positions[i + 1]! > maxY) maxY = positions[i + 1]!
+ if (positions[i + 2]! < minZ) minZ = positions[i + 2]!
+ if (positions[i + 2]! > maxZ) maxZ = positions[i + 2]!
+ }
+ if (!Number.isFinite(minX)) return vec3()
+ return vec3((maxX - minX) / 2, (maxY - minY) / 2, (maxZ - minZ) / 2)
+ }
+ }
+}
+
+export class MockPhysicsWorld implements PhysicsWorld {
+ private nextId: BodyId = 1
+ private nextConstraintId: ConstraintId = 1
+ /** Insertion-ordered on purpose: determinism, not lookup speed. */
+ private readonly bodies = new Map<BodyId, MockBody>()
+ private readonly constraints = new Map<ConstraintId, MockConstraint>()
+ private readonly casts: CastPlane[] = []
+ private disposed = false
+
+ step(dt: number): void {
+ this.assertLive()
+ for (const body of this.bodies.values()) {
+ if (body.motion !== 'dynamic') continue
+ const invMass = 1 / Math.max(body.massKg, 1e-6)
+ body.linVel.x += body.force.x * invMass * dt
+ body.linVel.y += MOCK_GRAVITY * dt + body.force.y * invMass * dt
+ body.linVel.z += body.force.z * invMass * dt
+ v3set(body.force, 0, 0, 0)
+ body.angVel.x += body.torque.x * invMass * dt
+ body.angVel.y += body.torque.y * invMass * dt
+ body.angVel.z += body.torque.z * invMass * dt
+ v3set(body.torque, 0, 0, 0)
+ v3scale(body.linVel, body.linVel, Math.max(0, 1 - MOCK_LINEAR_DAMPING * dt))
+ v3scale(body.angVel, body.angVel, Math.max(0, 1 - MOCK_ANGULAR_DAMPING * dt))
+ body.pos.x += body.linVel.x * dt
+ body.pos.y += body.linVel.y * dt
+ body.pos.z += body.linVel.z * dt
+ }
+ this.resolveContacts()
+ this.poseWeldGroups()
+ }
+
+ addBody(desc: BodyDesc): BodyId {
+ this.assertLive()
+ const id = this.nextId++
+ const body: MockBody = {
+ id,
+ desc,
+ motion: desc.motion,
+ pos: vec3(desc.pos.x, desc.pos.y, desc.pos.z),
+ rot: quat(),
+ linVel: vec3(),
+ angVel: vec3(),
+ force: vec3(),
+ torque: vec3(),
+ massKg: desc.massKg ?? MOCK_DEFAULT_MASS_KG,
+ half: halfExtents(desc),
+ weld: null,
+ }
+ setQuat(body.rot, desc.rot)
+ this.bodies.set(id, body)
+ return id
+ }
+
+ removeBody(id: BodyId): void {
+ const body = this.bodies.get(id)
+ if (!body) return
+ this.bodies.delete(id)
+ // Any group this body belonged to loses it; a group left with no members is
+ // dropped, so the survivors become independent again.
+ for (const other of this.bodies.values()) {
+ const group = other.weld
+ if (!group) continue
+ if (group.driver === body) other.weld = null
+ else group.members = group.members.filter((m) => m.body !== body)
+ }
+ }
+
+ getTransform(id: BodyId, outPos: Vec3, outRot: Quat): void {
+ const body = this.mustGet(id)
+ v3copy(outPos, body.pos)
+ setQuat(outRot, body.rot)
+ }
+
+ setTransform(id: BodyId, pos: Vec3, rot?: Quat): void {
+ const body = this.mustGet(id)
+ const group = body.weld
+ if (group) {
+ // Moving any member moves the whole island rigidly, exactly as a weld does.
+ const dx = pos.x - body.pos.x
+ const dy = pos.y - body.pos.y
+ const dz = pos.z - body.pos.z
+ v3set(
+ group.driver.pos,
+ group.driver.pos.x + dx,
+ group.driver.pos.y + dy,
+ group.driver.pos.z + dz,
+ )
+ this.poseWeldGroups()
+ }
+ if (!group) v3copy(body.pos, pos)
+ if (rot) setQuat(body.rot, rot)
+ }
+
+ setMotionType(id: BodyId, motion: MotionType): void {
+ const body = this.mustGet(id)
+ if (body.motion === motion) return
+ body.motion = motion
+ if (motion !== 'dynamic') {
+ // Matches the Havok adapter: freezing a body drops its motion.
+ v3set(body.linVel, 0, 0, 0)
+ v3set(body.angVel, 0, 0, 0)
+ v3set(body.force, 0, 0, 0)
+ v3set(body.torque, 0, 0, 0)
+ }
+ }
+
+ getLinearVelocity(id: BodyId, out: Vec3): void {
+ v3copy(out, this.mustGet(id).linVel)
+ }
+
+ setLinearVelocity(id: BodyId, v: Vec3): void {
+ v3copy(this.mustGet(id).linVel, v)
+ }
+
+ getAngularVelocity(id: BodyId, out: Vec3): void {
+ v3copy(out, this.mustGet(id).angVel)
+ }
+
+ setAngularVelocity(id: BodyId, v: Vec3): void {
+ v3copy(this.mustGet(id).angVel, v)
+ }
+
+ isSettled(id: BodyId): boolean {
+ const body = this.mustGet(id)
+ if (body.motion !== 'dynamic') return true
+ if (v3lengthSq(body.linVel) > MOCK_SETTLE_LINEAR * MOCK_SETTLE_LINEAR) return false
+ return v3lengthSq(body.angVel) <= MOCK_SETTLE_ANGULAR * MOCK_SETTLE_ANGULAR
+ }
+
+ wake(id: BodyId): void {
+ // Dynamic-only, exactly like the Havok adapter. Waking is not an impulse,
+ // so there is deliberately nothing to do.
+ const body = this.mustGet(id)
+ if (body.motion !== 'dynamic') return
+ }
+
+ addConstraint(desc: ConstraintDesc): ConstraintId {
+ this.assertLive()
+ const a = this.mustGet(desc.bodyA)
+ const b = this.mustGet(desc.bodyB)
+ const id = this.nextConstraintId++
+ const motor = desc.type === 'hinge' || desc.type === 'slider' ? (desc.motor ?? null) : null
+ this.constraints.set(id, { id, desc, motor })
+ if (desc.type === 'weld') {
+ // Weld preserves the creation-time relative pose: every member becomes a
+ // rigid follower of A at the offset it had when the joint was made.
+ const group: WeldGroup = {
+ driver: a,
+ members: [
+ { body: b, offset: vec3(b.pos.x - a.pos.x, b.pos.y - a.pos.y, b.pos.z - a.pos.z) },
+ ],
+ }
+ b.weld = group
+ }
+ return id
+ }
+
+ removeConstraint(id: ConstraintId): void {
+ const rec = this.constraints.get(id)
+ if (!rec) return
+ this.constraints.delete(id)
+ if (rec.desc.type === 'weld') {
+ const body = this.bodies.get(rec.desc.bodyB)
+ if (body?.weld) body.weld = null
+ }
+ }
+
+ setConstraintMotor(id: ConstraintId, motor: ConstraintMotor): void {
+ const rec = this.constraints.get(id)
+ if (!rec) return
+ if (rec.desc.type !== 'hinge' && rec.desc.type !== 'slider') return
+ rec.motor = { targetVelocity: motor.targetVelocity, maxForce: motor.maxForce }
+ }
+
+ /** The motor currently configured on a hinge/slider, or null. Test introspection. */
+ getConstraintMotor(id: ConstraintId): ConstraintMotor | null {
+ return this.constraints.get(id)?.motor ?? null
+ }
+
+ applyForce(id: BodyId, force: Vec3): void {
+ const body = this.mustGet(id)
+ if (body.motion !== 'dynamic') return
+ body.force.x += force.x
+ body.force.y += force.y
+ body.force.z += force.z
+ }
+
+ raycast(from: Vec3, to: Vec3, collidesWith: number): RayHit | null {
+ this.assertLive()
+ const d = vec3(to.x - from.x, to.y - from.y, to.z - from.z)
+ const length = Math.sqrt(v3lengthSq(d))
+ let best: RayHit | null = null
+ for (const body of this.bodies.values()) {
+ if (!(body.desc.layer & collidesWith)) continue
+ const hit = rayAabb(from, d, length, body.pos, body.half)
+ if (!hit) continue
+ if (!best || hit.fraction < best.fraction) {
+ best = { bodyId: body.id, point: hit.point, normal: hit.normal, fraction: hit.fraction }
+ }
+ }
+ for (const plane of this.casts) {
+ const hit = rayPlane(from, d, length, plane)
+ if (!hit) continue
+ if (best && best.fraction <= hit.fraction) continue
+ best = {
+ bodyId: MOCK_CAST_BODY_ID,
+ point: hit.point,
+ normal: hit.normal,
+ fraction: hit.fraction,
+ }
+ }
+ return best
+ }
+
+ sweepCapsule(
+ from: Vec3,
+ to: Vec3,
+ radius: number,
+ height: number,
+ collidesWith: number,
+ exclude?: BodyId,
+ ): SweepHit | null {
+ this.assertLive()
+ const d = vec3(to.x - from.x, to.y - from.y, to.z - from.z)
+ // `height` is the capsule's TOTAL height including both caps (types.ts:170),
+ // so the cylindrical segment runs height/2 - radius either side of centre —
+ // the same conversion HavokWorld.getSweepShape makes (havokWorld.ts:533).
+ const half = Math.max(height / 2 - radius, 0.01)
+ let best: SweepHit | null = null
+ const consider = (fraction: number, normal: Vec3, point: Vec3): void => {
+ if (fraction < -1e-9 || fraction > 1 + 1e-9) return
+ const f = Math.min(Math.max(fraction, 0), 1)
+ if (best && f >= best.fraction) return
+ best = { fraction: f, normal: vec3(normal.x, normal.y, normal.z), point }
+ }
+ for (const body of this.bodies.values()) {
+ if (body.id === exclude) continue
+ if (!(body.desc.layer & collidesWith)) continue
+ const hit = sweepCapsuleAabb(from, d, radius, half, body.pos, body.half)
+ if (hit) consider(hit.fraction, hit.normal, hit.point)
+ }
+ for (const plane of this.casts) {
+ const hit = sweepCapsulePlane(from, d, radius, half, plane)
+ if (hit) consider(hit.fraction, hit.normal, hit.point)
+ }
+ return best
+ }
+
+ dispose(): void {
+ if (this.disposed) return
+ this.disposed = true
+ this.bodies.clear()
+ this.constraints.clear()
+ this.casts.length = 0
+ }
+
+ // ── mock-only construction ──────────────────────────────────────────────
+
+ /**
+ * Infinite analytic ground plane with its top face at `y`. Capsule sweeps
+ * and rays resolve against it exactly, and dynamic bodies rest on it. This
+ * is the surface the movement tests walk on.
+ */
+ addGroundPlane(y = 0): void {
+ this.addCast({ normal: vec3(0, 1, 0), offset: y })
+ }
+
+ /**
+ * Marks the most recent cast as ground: casts so marked also stop bodies
+ * (`groundHeightAt`) instead of only stopping casts.
+ */
+ markLastCastAsGround(): void {
+ const plane = this.casts[this.casts.length - 1]
+ if (plane) plane.isGround = true
+ }
+
+ /**
+ * An analytic surface only rays and capsule sweeps see: an infinite plane,
+ * unit normal `normal`, at signed distance `offset`, clipped to an optional
+ * axis-aligned patch. This is how a test declares a wall, a ceiling or a step
+ * without inventing geometry the mock would then have to simulate.
+ */
+ addCast(plane: {
+ normal: Vec3
+ offset: number
+ minX?: number
+ maxX?: number
+ minY?: number
+ maxY?: number
+ minZ?: number
+ maxZ?: number
+ }): void {
+ const len = Math.sqrt(v3lengthSq(plane.normal))
+ const normal = vec3(plane.normal.x, plane.normal.y, plane.normal.z)
+ if (len > 1e-9) v3scale(normal, normal, 1 / len)
+ const patched =
+ plane.minX !== undefined ||
+ plane.maxX !== undefined ||
+ plane.minY !== undefined ||
+ plane.maxY !== undefined ||
+ plane.minZ !== undefined ||
+ plane.maxZ !== undefined
+ this.casts.push({
+ normal,
+ offset: plane.offset / (len > 1e-9 ? len : 1),
+ patchMin: patched
+ ? vec3(plane.minX ?? -Infinity, plane.minY ?? -Infinity, plane.minZ ?? -Infinity)
+ : null,
+ patchMax: patched
+ ? vec3(plane.maxX ?? Infinity, plane.maxY ?? Infinity, plane.maxZ ?? Infinity)
+ : null,
+ isGround: false,
+ })
+ }
+
+ /** Number of cast surfaces currently installed. Test introspection. */
+ castCount(): number {
+ return this.casts.length
+ }
+
+ /**
+ * The highest non-dynamic surface under (x, z): any analytic up-facing cast
+ * plane whose patch covers the column, else the top face of the tallest
+ * static/kinematic body whose footprint covers it, else -Infinity.
+ */
+ groundHeightAt(x: number, z: number): number {
+ let floor = -Infinity
+ for (const plane of this.casts) {
+ if (!plane.isGround) continue
+ if (Math.abs(plane.normal.y - 1) > 1e-6) continue
+ const { patchMin: lo, patchMax: hi } = plane
+ if (lo && hi && (x < lo.x || x > hi.x || z < lo.z || z > hi.z)) continue
+ if (plane.offset > floor) floor = plane.offset
+ }
+ for (const other of this.bodies.values()) {
+ if (other.motion === 'dynamic') continue
+ if (Math.abs(other.pos.x - x) > other.half.x) continue
+ if (Math.abs(other.pos.z - z) > other.half.z) continue
+ const top = other.pos.y + other.half.y
+ if (top > floor) floor = top
+ }
+ return floor
+ }
+
+ // ── internals ───────────────────────────────────────────────────────────
+
+ private assertLive(): void {
+ if (this.disposed) throw new Error('physics world disposed')
+ }
+
+ private mustGet(id: BodyId): MockBody {
+ const body = this.bodies.get(id)
+ if (!body) throw new Error(`unknown physics body ${id}`)
+ return body
+ }
+
+ /** Places every welded follower at its group's driver pose plus its offset. */
+ private poseWeldGroups(): void {
+ const seen = new Set<WeldGroup>()
+ for (const body of this.bodies.values()) {
+ const group = body.weld
+ if (!group || seen.has(group)) continue
+ seen.add(group)
+ for (const member of group.members) {
+ member.body.pos.x = group.driver.pos.x + member.offset.x
+ member.body.pos.y = group.driver.pos.y + member.offset.y
+ member.body.pos.z = group.driver.pos.z + member.offset.z
+ }
+ }
+ }
+
+ /**
+ * Resting contact against the analytic ground plane and the top face of any
+ * non-dynamic body. The mock has no contact solver: friction is modelled as
+ * "stop" and restitution (0.05) as "no bounce", which is all a body resting
+ * on a plane can observably do here.
+ */
+ private resolveContacts(): void {
+ for (const body of this.bodies.values()) {
+ if (body.motion !== 'dynamic') continue
+ const floor = this.groundHeightAt(body.pos.x, body.pos.z)
+ if (!Number.isFinite(floor)) continue
+ const bottom = body.pos.y - body.half.y
+ if (bottom >= floor - 1e-9) continue
+ body.pos.y = floor + body.half.y
+ v3set(body.linVel, 0, 0, 0)
+ v3set(body.angVel, 0, 0, 0)
+ }
+ this.poseWeldGroups()
+ }
+}
+
+/**
+ * `BodyId` reported for a hit on the analytic cast table. Cast surfaces are not
+ * bodies, so they share one reserved id; tests that care which surface was hit
+ * should use a box instead.
+ */
+export const MOCK_CAST_BODY_ID: BodyId = 0
+
+/** A fresh, empty mock world. */
+export function createMockPhysicsWorld(): MockPhysicsWorld {
+ return new MockPhysicsWorld()
+}
+
+/**
+ * Binds a mock world to the movement module's `CollisionQueries` with the same
+ * fixed mask and self-exclusion the server uses
+ * (apps/server/src/game/systems/movement.ts:58-68).
+ */
+export function mockCollisionQueries(
+ world: MockPhysicsWorld,
+ collidesWith: number = CollisionLayer.Static | CollisionLayer.Prop | CollisionLayer.Player,
+ exclude?: () => number | undefined,
+): { sweepCapsule(from: Vec3, to: Vec3, radius: number, height: number): SweepHit | null } {
+ return {
+ sweepCapsule: (from, to, radius, height) =>
+ world.sweepCapsule(from, to, radius, height, collidesWith, exclude?.()),
+ }
+}
+
+// ── analytic primitives ──────────────────────────────────────────────────
+
+/**
+ * Slab test of a ray against an AABB. `d` is the whole segment, so the
+ * parameter is already the 0..1 fraction the seam wants.
+ */
+function rayAabb(
+ from: Vec3,
+ d: Vec3,
+ _length: number,
+ center: Vec3,
+ half: Vec3,
+): { point: Vec3; normal: Vec3; fraction: number } | null {
+ const o = [from.x, from.y, from.z]
+ const dd = [d.x, d.y, d.z]
+ const c = [center.x, center.y, center.z]
+ const h = [half.x, half.y, half.z]
+ let tMin = -Infinity
+ let tMax = Infinity
+ let axis = 0
+ let sign = -1
+ for (let a = 0; a < 3; a++) {
+ if (Math.abs(dd[a]!) < 1e-12) {
+ if (o[a]! < c[a]! - h[a]! || o[a]! > c[a]! + h[a]!) return null
+ continue
+ }
+ const inv = 1 / dd[a]!
+ let t1 = (c[a]! - h[a]! - o[a]!) * inv
+ let t2 = (c[a]! + h[a]! - o[a]!) * inv
+ let s = -1
+ if (t1 > t2) {
+ const tmp = t1
+ t1 = t2
+ t2 = tmp
+ s = 1
+ }
+ if (t1 > tMin) {
+ tMin = t1
+ axis = a
+ sign = s
+ }
+ if (t2 < tMax) tMax = t2
+ if (tMin > tMax) return null
+ }
+ // The origin is already inside the box: nothing to report as a surface hit.
+ if (tMin <= 0 || tMin > 1) return null
+ const normal = vec3(0, 0, 0)
+ if (axis === 0) normal.x = sign
+ else if (axis === 1) normal.y = sign
+ else normal.z = sign
+ return {
+ point: vec3(from.x + d.x * tMin, from.y + d.y * tMin, from.z + d.z * tMin),
+ normal,
+ fraction: tMin,
+ }
+}
+
+function rayPlane(
+ from: Vec3,
+ d: Vec3,
+ _length: number,
+ plane: CastPlane,
+): { point: Vec3; normal: Vec3; fraction: number } | null {
+ const denom = v3dot(plane.normal, d)
+ if (Math.abs(denom) < 1e-12) return null
+ const t = (plane.offset - v3dot(plane.normal, from)) / denom
+ if (t <= 0 || t > 1) return null
+ const point = vec3(from.x + d.x * t, from.y + d.y * t, from.z + d.z * t)
+ if (!inPatch(plane, point)) return null
+ // Surface normal always opposes the ray.
+ const n = vec3(plane.normal.x, plane.normal.y, plane.normal.z)
+ if (denom > 0) v3scale(n, n, -1)
+ return { point, normal: n, fraction: t }
+}
+
+/**
+ * Sweeps a vertical capsule (centre segment of half-length `half`, radius
+ * `radius`) against an AABB. The Minkowski sum of a vertical capsule and an
+ * AABB is not an AABB, so this inflates the box by `radius` in x/z and by
+ * `half + radius` in y: conservative at the corners, exact on every face. For
+ * an axis-aligned world — all the mock models — that is the whole story.
+ *
+ * Havok reports the contact point on the *surface*, not at the capsule centre
+ * (measured: a sweep onto ground at y = 0 returns y = 0 exactly), so the point
+ * is walked back onto the inflated face along −normal.
+ */
+function sweepCapsuleAabb(
+ from: Vec3,
+ d: Vec3,
+ radius: number,
+ half: number,
+ center: Vec3,
+ boxHalf: Vec3,
+): SweepHit | null {
+ const lo = [
+ center.x - boxHalf.x - radius,
+ center.y - boxHalf.y - half - radius,
+ center.z - boxHalf.z - radius,
+ ]
+ const hi = [
+ center.x + boxHalf.x + radius,
+ center.y + boxHalf.y + half + radius,
+ center.z + boxHalf.z + radius,
+ ]
+ const o = [from.x, from.y, from.z]
+ const dd = [d.x, d.y, d.z]
+ let tMin = -Infinity
+ let tMax = Infinity
+ let axis = 0
+ let sign = -1
+ for (let a = 0; a < 3; a++) {
+ if (Math.abs(dd[a]!) < 1e-12) {
+ if (o[a]! < lo[a]! || o[a]! > hi[a]!) return null
+ continue
+ }
+ const inv = 1 / dd[a]!
+ let t1 = (lo[a]! - o[a]!) * inv
+ let t2 = (hi[a]! - o[a]!) * inv
+ let s = -1
+ if (t1 > t2) {
+ const tmp = t1
+ t1 = t2
+ t2 = tmp
+ s = 1
+ }
+ if (t1 > tMin) {
+ tMin = t1
+ axis = a
+ sign = s
+ }
+ if (t2 < tMax) tMax = t2
+ if (tMin > tMax) return null
+ }
+ // Already overlapping at t = 0: the capsule starts inside, which is not a
+ // contact the caller can act on.
+ if (tMin <= 0 || tMin > 1) return null
+ const normal = vec3(0, 0, 0)
+ if (axis === 0) normal.x = sign
+ else if (axis === 1) normal.y = sign
+ else normal.z = sign
+ // Walk the centre back onto the true surface: distance is the capsule's
+ // support along the normal, `radius` on the sides and `half + radius` on
+ // the caps.
+ const support = axis === 1 ? half + radius : radius
+ const centre = vec3(from.x + d.x * tMin, from.y + d.y * tMin, from.z + d.z * tMin)
+ const point = vec3(
+ centre.x - normal.x * support,
+ centre.y - normal.y * support,
+ centre.z - normal.z * support,
+ )
+ return { fraction: tMin, normal, point }
+}
+
+/**
+ * Sweeps a vertical capsule against an analytic plane. The support function of
+ * a Y-axis capsule of half-length `half` and radius `radius` along a unit normal
+ * n is `half·|n.y| + radius`, which is exact, so the contact is a single
+ * closed-form division per side.
+ *
+ * The capsule is a closed convex set centred on the sweep line, so it can touch
+ * the plane from either side: the earliest contact is min over s of
+ * (s·support − signed) / (n·d). The ground plane is the common case (capsule
+ * above it, s = +1); a wall or a ceiling declared with an outward normal is
+ * approached from the opposite side, s = −1. Taking only one of the two misses
+ * every wall and lets the sweep continue through it.
+ *
+ * A sweep that *starts* already overlapping the slab has no first contact to
+ * report, exactly as in the AABB path above (tMin <= 0). This matters for a
+ * short hull on a thick radius: STANCE_HULL[Prone] = 0.7 with a 0.4 radius
+ * clamps the cylindrical segment to 0.02, so a prone capsule is 0.82 tall and
+ * rests 0.06 into the floor. Reporting a hit there would block every upward
+ * sweep, i.e. the player could never stand up.
+ */
+function sweepCapsulePlane(
+ from: Vec3,
+ d: Vec3,
+ radius: number,
+ half: number,
+ plane: CastPlane,
+): SweepHit | null {
+ const denom = v3dot(plane.normal, d)
+ if (Math.abs(denom) < 1e-12) return null
+ const support = half * Math.abs(plane.normal.y) + radius
+ const signed = v3dot(plane.normal, from) - plane.offset
+ if (signed < support && signed > -support) return null
+ let best = Infinity
+ for (const side of [support, -support]) {
+ const t = (side - signed) / denom
+ if (t >= 0 && t <= 1 && t < best) best = t
+ }
+ if (best === Infinity) return null
+ const centre = vec3(from.x + d.x * best, from.y + d.y * best, from.z + d.z * best)
+ if (!inPatch(plane, centre)) return null
+ // Surface normal always opposes the sweep.
+ const normal = vec3(plane.normal.x, plane.normal.y, plane.normal.z)
+ if (denom > 0) v3scale(normal, normal, -1)
+ const point = vec3(
+ centre.x - normal.x * support,
+ centre.y - normal.y * support,
+ centre.z - normal.z * support,
+ )
+ return { fraction: best, normal, point }
+}
+
+function inPatch(plane: CastPlane, point: Vec3): boolean {
+ const { patchMin: lo, patchMax: hi } = plane
+ if (!lo || !hi) return true
+ return (
+ point.x >= lo.x &&
+ point.x <= hi.x &&
+ point.y >= lo.y &&
+ point.y <= hi.y &&
+ point.z >= lo.z &&
+ point.z <= hi.z
+ )
+}
@@ -156,6 +156,10 @@ importers:
@@ -156,6 +156,10 @@ importers:
'@openvibe/shared':
'@openvibe/shared':
specifier: workspace:*
specifier: workspace:*
version: link:../shared
version: link:../shared
+ devDependencies:
+ '@openvibe/physics':
+ specifier: workspace:*
+ version: link:../physics
packages/persistence:
packages/persistence:
dependencies:
dependencies: