@flighthq/physics3d-abi 0.4.0-next.1827.9db114b

package/src/physics3DAbi.test.ts

@@ -0,0 +1,584 @@
+import {
+  addPhysics3DBody,
+  addPhysics3DCollider,
+  createPhysics3DBallAndSocketJoint,
+  createPhysics3DCollider,
+  createPhysics3DConeTwistJoint,
+  createPhysics3DDistanceJoint,
+  createPhysics3DFixedJoint,
+  createPhysics3DGeneric6DofJoint,
+  createPhysics3DHingeJoint,
+  createPhysics3DSolverConfig,
+  createPhysics3DSliderJoint,
+  createPhysics3DWorld,
+  createRigidBody3D,
+  stepPhysics3D,
+} from '@flighthq/physics3d/contract';
+import type {
+  CollisionColliderShape3D,
+  Physics3DAbi,
+  Physics3DAbiBodyBuffer,
+  Physics3DAbiCommandBuffer,
+  Physics3DJoint,
+  RigidBody3D,
+} from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createPhysics3DAbi,
+  createPhysics3DAbiWorld,
+  destroyPhysics3DAbiWorld,
+  executePhysics3DAbiCommands,
+  getPhysics3DAbiWorldStatus,
+  readPhysics3DAbiBodies,
+  readPhysics3DAbiContacts,
+  readPhysics3DAbiJoints,
+  stepPhysics3DAbiWorld,
+} from './physics3DAbi';
+import {
+  clearPhysics3DAbiCommandBuffer,
+  createPhysics3DAbiBodyBuffer,
+  createPhysics3DAbiCommandBuffer,
+  createPhysics3DAbiContactBuffer,
+  createPhysics3DAbiExecutionResult,
+  createPhysics3DAbiJointBuffer,
+  createPhysics3DAbiQueryBuffer,
+} from './physics3DAbiBuffer';
+import {
+  writePhysics3DAbiApplyForceAtPointCommand,
+  writePhysics3DAbiApplyForceCommand,
+  writePhysics3DAbiApplyLinearImpulseAtPointCommand,
+  writePhysics3DAbiApplyLinearImpulseCommand,
+  writePhysics3DAbiApplyTorqueCommand,
+  writePhysics3DAbiDestroyBodyCommand,
+  writePhysics3DAbiDestroyColliderCommand,
+  writePhysics3DAbiDestroyJointCommand,
+  writePhysics3DAbiSetBodyCommand,
+  writePhysics3DAbiSetColliderCommand,
+  writePhysics3DAbiSetGravityCommand,
+  writePhysics3DAbiSetJointCommand,
+  writePhysics3DAbiSetSolverConfigCommand,
+  writePhysics3DAbiWakeBodyCommand,
+} from './physics3DAbiCommand';
+import {
+  Physics3DAbiBodyValue,
+  Physics3DAbiBodyValueStride,
+  Physics3DAbiCapability,
+  Physics3DAbiCommandHeaderByteLength,
+  Physics3DAbiVersion,
+} from './physics3DAbiLayout';
+import { queryPhysics3DAbiPoint } from './physics3DAbiQuery';
+
+describe('createPhysics3DAbi', () => {
+  it('publishes the reference version and required baseline capabilities', () => {
+    const abi = createPhysics3DAbi();
+    expect(abi.version).toBe(Physics3DAbiVersion);
+    expect(abi.capabilities).toBe(
+      Physics3DAbiCapability.ContactHooks |
+        Physics3DAbiCapability.PersistentWorlds |
+        Physics3DAbiCapability.Queries |
+        Physics3DAbiCapability.SelectiveReadback,
+    );
+  });
+
+  it('decodes all nine built-in collider shapes through the public command stream', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands = createPhysics3DAbiCommandBuffer(32768);
+    const body = createRigidBody3D('static');
+    expect(writePhysics3DAbiSetBodyCommand(commands, 1, body)).toBe(true);
+    const shapes = getColliderShapes();
+    for (let i = 0; i < shapes.length; i += 1) {
+      expect(writePhysics3DAbiSetColliderCommand(commands, i + 1, 1, createPhysics3DCollider(shapes[i]))).toBe(true);
+    }
+
+    const result = createPhysics3DAbiExecutionResult();
+    expect(executePhysics3DAbiCommands(abi, world, commands, result)).toBe(true);
+    expect(result.commandIndex).toBe(1 + shapes.length);
+  });
+
+  it('executes and reads through caller-owned shared-memory views', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands: Physics3DAbiCommandBuffer = {
+      data: new Uint8Array(new SharedArrayBuffer(512)),
+      byteLength: 0,
+      commandCount: 0,
+    };
+    clearPhysics3DAbiCommandBuffer(commands);
+    const body = createRigidBody3D();
+    body.x = 17;
+    expect(writePhysics3DAbiSetBodyCommand(commands, 3, body)).toBe(true);
+    executeOrThrow(abi, world, commands);
+
+    const out: Physics3DAbiBodyBuffer = {
+      ids: new Uint32Array(new SharedArrayBuffer(Uint32Array.BYTES_PER_ELEMENT)),
+      flags: new Uint32Array(new SharedArrayBuffer(Uint32Array.BYTES_PER_ELEMENT)),
+      values: new Float64Array(new SharedArrayBuffer(Physics3DAbiBodyValueStride * Float64Array.BYTES_PER_ELEMENT)),
+      count: 0,
+      requiredCount: 0,
+    };
+    expect(readPhysics3DAbiBodies(abi, world, null, out)).toBe(true);
+    expect(out.ids[0]).toBe(3);
+    expect(out.values[Physics3DAbiBodyValue.X]).toBe(17);
+  });
+});
+
+describe('createPhysics3DAbiWorld', () => {
+  it('allocates non-zero handles that are never reused by one ABI instance', () => {
+    const abi = createPhysics3DAbi();
+    const first = createPhysics3DAbiWorld(abi);
+    expect(first).toBeGreaterThan(0);
+    expect(destroyPhysics3DAbiWorld(abi, first)).toBe(true);
+    const second = createPhysics3DAbiWorld(abi);
+    expect(second).toBeGreaterThan(first);
+  });
+});
+
+describe('destroyPhysics3DAbiWorld', () => {
+  it('makes every later operation on that handle observably stale', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    expect(destroyPhysics3DAbiWorld(abi, world)).toBe(true);
+    expect(destroyPhysics3DAbiWorld(abi, world)).toBe(false);
+    expect(stepPhysics3DAbiWorld(abi, world, 1 / 60)).toBe('StaleWorld');
+    expect(readPhysics3DAbiBodies(abi, world, null, createPhysics3DAbiBodyBuffer(1))).toBe(false);
+  });
+});
+
+describe('executePhysics3DAbiCommands', () => {
+  it('commits the valid prefix and identifies the first rejected command', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands = createPhysics3DAbiCommandBuffer();
+    const body = createRigidBody3D();
+    body.x = 6;
+    expect(writePhysics3DAbiSetBodyCommand(commands, 5, body)).toBe(true);
+    expect(writePhysics3DAbiDestroyBodyCommand(commands, 999)).toBe(true);
+
+    const result = createPhysics3DAbiExecutionResult();
+    expect(executePhysics3DAbiCommands(abi, world, commands, result)).toBe(false);
+    expect(result).toMatchObject({ status: 'MissingBody', commandIndex: 1 });
+
+    const bodies = createPhysics3DAbiBodyBuffer(1);
+    expect(readPhysics3DAbiBodies(abi, world, null, bodies)).toBe(true);
+    expect(bodies.ids[0]).toBe(5);
+    expect(bodies.values[Physics3DAbiBodyValue.X]).toBe(6);
+  });
+
+  it('rejects a corrupted header before applying anything', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands = createPhysics3DAbiCommandBuffer();
+    writePhysics3DAbiSetGravityCommand(commands, 1, 2, 3);
+    commands.data[0] ^= 0xff;
+    const result = createPhysics3DAbiExecutionResult();
+
+    expect(executePhysics3DAbiCommands(abi, world, commands, result)).toBe(false);
+    expect(result).toEqual({
+      status: 'InvalidBuffer',
+      commandIndex: 0,
+      byteOffset: Physics3DAbiCommandHeaderByteLength,
+      commandKind: 0,
+    });
+  });
+
+  it('rejects unknown flag bits rather than silently adopting future semantics', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands = createPhysics3DAbiCommandBuffer();
+    writePhysics3DAbiSetBodyCommand(commands, 1, createRigidBody3D());
+    new DataView(commands.data.buffer).setUint32(32, 1 << 31, true);
+    const result = createPhysics3DAbiExecutionResult();
+
+    expect(executePhysics3DAbiCommands(abi, world, commands, result)).toBe(false);
+    expect(result.status).toBe('InvalidCommand');
+  });
+
+  it('applies configuration, force, impulse, torque, and wake commands to persistent state', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const body = createRigidBody3D();
+    body.mass = 2;
+    body.inertiaXX = 4;
+    body.inertiaYY = 4;
+    body.inertiaZZ = 4;
+    body.sleeping = true;
+    const config = createPhysics3DSolverConfig();
+    config.substeps = 2;
+
+    executeOrThrow(
+      abi,
+      world,
+      writeCommands((commands) => {
+        writePhysics3DAbiSetGravityCommand(commands, 0, 0, 0);
+        writePhysics3DAbiSetSolverConfigCommand(commands, config);
+        writePhysics3DAbiSetBodyCommand(commands, 7, body);
+        writePhysics3DAbiApplyForceCommand(commands, 7, 2, 0, 0);
+        writePhysics3DAbiApplyForceAtPointCommand(commands, 7, 2, 0, 0, 0, 1, 0);
+        writePhysics3DAbiApplyLinearImpulseCommand(commands, 7, 2, 0, 0);
+        writePhysics3DAbiApplyLinearImpulseAtPointCommand(commands, 7, 2, 0, 0, 0, 1, 0);
+        writePhysics3DAbiApplyTorqueCommand(commands, 7, 0, 0, 6);
+        writePhysics3DAbiWakeBodyCommand(commands, 7);
+      }),
+    );
+
+    const beforeStep = createPhysics3DAbiBodyBuffer(1);
+    expect(readPhysics3DAbiBodies(abi, world, null, beforeStep)).toBe(true);
+    expect(beforeStep.flags[0] & (1 << 4)).toBe(0);
+    expect(beforeStep.values[Physics3DAbiBodyValue.VelocityX]).toBeCloseTo(2, 12);
+    expect(beforeStep.values[Physics3DAbiBodyValue.AngularVelocityZ]).toBeCloseTo(-0.5, 12);
+    expect(beforeStep.values[Physics3DAbiBodyValue.ForceX]).toBe(4);
+    expect(beforeStep.values[Physics3DAbiBodyValue.TorqueZ]).toBe(4);
+
+    expect(stepPhysics3DAbiWorld(abi, world, 0.5)).toBe('Complete');
+    const afterStep = createPhysics3DAbiBodyBuffer(1);
+    expect(readPhysics3DAbiBodies(abi, world, null, afterStep)).toBe(true);
+    expect(afterStep.values[Physics3DAbiBodyValue.VelocityX]).toBeCloseTo(3, 12);
+    expect(afterStep.values[Physics3DAbiBodyValue.VelocityY]).toBe(0);
+    expect(afterStep.values[Physics3DAbiBodyValue.ForceX]).toBe(0);
+    expect(afterStep.values[Physics3DAbiBodyValue.TorqueZ]).toBe(0);
+  });
+
+  it('removes collider identity and broadphase query visibility atomically', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const body = createRigidBody3D('static');
+    executeOrThrow(
+      abi,
+      world,
+      writeCommands((commands) => {
+        writePhysics3DAbiSetBodyCommand(commands, 1, body);
+        writePhysics3DAbiSetColliderCommand(commands, 2, 1, createPhysics3DCollider(unitAabb()));
+      }),
+    );
+    const hits = createPhysics3DAbiQueryBuffer(1);
+    expect(queryPhysics3DAbiPoint(abi, world, 0, 0, 0, hits)).toBe(true);
+    expect([hits.count, hits.requiredCount]).toEqual([1, 1]);
+
+    executeOrThrow(
+      abi,
+      world,
+      writeCommands((commands) => {
+        writePhysics3DAbiDestroyColliderCommand(commands, 2);
+      }),
+    );
+    expect(queryPhysics3DAbiPoint(abi, world, 0, 0, 0, hits)).toBe(true);
+    expect([hits.count, hits.requiredCount]).toEqual([0, 0]);
+  });
+});
+
+describe('getPhysics3DAbiWorldStatus', () => {
+  it('distinguishes a usable handle from a destroyed one', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    expect(getPhysics3DAbiWorldStatus(abi, world)).toBe('Ready');
+    destroyPhysics3DAbiWorld(abi, world);
+    expect(getPhysics3DAbiWorldStatus(abi, world)).toBe('Stale');
+  });
+});
+
+describe('readPhysics3DAbiBodies', () => {
+  it('reports a sorted full count and writes only the prefix that fits', () => {
+    const { abi, world } = createBodyReadWorld();
+    const out = createPhysics3DAbiBodyBuffer(1);
+
+    expect(readPhysics3DAbiBodies(abi, world, null, out)).toBe(true);
+    expect(out.requiredCount).toBe(2);
+    expect(out.count).toBe(1);
+    expect(out.ids[0]).toBe(10);
+  });
+
+  it('preserves selective caller order and silently omits missing ids', () => {
+    const { abi, world } = createBodyReadWorld();
+    const out = createPhysics3DAbiBodyBuffer(2);
+
+    expect(readPhysics3DAbiBodies(abi, world, new Uint32Array([20, 404, 10]), out)).toBe(true);
+    expect(out.requiredCount).toBe(2);
+    expect(out.count).toBe(2);
+    expect([...out.ids]).toEqual([20, 10]);
+  });
+});
+
+describe('readPhysics3DAbiContacts', () => {
+  it('publishes contact identities, events, and required capacity after a step', () => {
+    const { abi, world } = createContactWorld();
+    expect(stepPhysics3DAbiWorld(abi, world, 1 / 60)).toBe('Complete');
+
+    const out = createPhysics3DAbiContactBuffer(4, 16);
+    expect(readPhysics3DAbiContacts(abi, world, 'All', out)).toBe(true);
+    expect(out.count).toBeGreaterThan(0);
+    expect(new Set([out.ids[0], out.ids[1]])).toEqual(new Set([1, 2]));
+    expect(new Set([out.ids[2], out.ids[3]])).toEqual(new Set([11, 22]));
+
+    const began = createPhysics3DAbiContactBuffer(4, 16);
+    expect(readPhysics3DAbiContacts(abi, world, 'Began', began)).toBe(true);
+    expect(began.count).toBeGreaterThan(0);
+
+    const undersized = createPhysics3DAbiContactBuffer(0, 0);
+    expect(readPhysics3DAbiContacts(abi, world, 'All', undersized)).toBe(true);
+    expect(undersized.count).toBe(0);
+    expect(undersized.requiredCount).toBeGreaterThan(0);
+    expect(undersized.requiredPointCount).toBeGreaterThan(0);
+  });
+});
+
+describe('readPhysics3DAbiJoints', () => {
+  it('decodes every built-in joint and returns reactions in caller-id order', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    const commands = createPhysics3DAbiCommandBuffer(16384);
+    writePhysics3DAbiSetBodyCommand(commands, 10, createRigidBody3D());
+    writePhysics3DAbiSetBodyCommand(commands, 20, createRigidBody3D());
+    const joints = getJoints();
+    const ids = [70, 10, 60, 20, 50, 30, 40];
+    for (let i = 0; i < joints.length; i += 1) {
+      expect(writePhysics3DAbiSetJointCommand(commands, ids[i], joints[i])).toBe(true);
+    }
+    const result = createPhysics3DAbiExecutionResult();
+    expect(executePhysics3DAbiCommands(abi, world, commands, result)).toBe(true);
+
+    const out = createPhysics3DAbiJointBuffer(3);
+    expect(readPhysics3DAbiJoints(abi, world, out)).toBe(true);
+    expect(out.requiredCount).toBe(7);
+    expect(out.count).toBe(3);
+    expect([...out.ids]).toEqual([10, 20, 30]);
+    expect([...out.values]).toEqual(new Array(18).fill(0));
+  });
+
+  it('removes a joint explicitly and cascades the others when a body is destroyed', () => {
+    const abi = createPhysics3DAbi();
+    const world = createPhysics3DAbiWorld(abi);
+    executeOrThrow(
+      abi,
+      world,
+      writeCommands((commands) => {
+        writePhysics3DAbiSetBodyCommand(commands, 1, createRigidBody3D());
+        writePhysics3DAbiSetBodyCommand(commands, 2, createRigidBody3D());
+        writePhysics3DAbiSetJointCommand(commands, 5, createPhysics3DDistanceJoint({ bodyA: 1, bodyB: 2 }));
+        writePhysics3DAbiSetJointCommand(commands, 6, createPhysics3DBallAndSocketJoint({ bodyA: 1, bodyB: 2 }));
+      }),
+    );
+    executeOrThrow(
+      abi,
+      world,
+      writeCommands((commands) => {
+        writePhysics3DAbiDestroyJointCommand(commands, 5);
+        writePhysics3DAbiDestroyBodyCommand(commands, 1);
+      }),
+    );
+
+    const out = createPhysics3DAbiJointBuffer(2);
+    expect(readPhysics3DAbiJoints(abi, world, out)).toBe(true);
+    expect([out.count, out.requiredCount]).toEqual([0, 0]);
+  });
+});
+
+describe('stepPhysics3DAbiWorld', () => {
+  it('matches the standard Physics3D solver over a persistent multi-step world', () => {
+    const abi = createPhysics3DAbi();
+    const abiWorld = createPhysics3DAbiWorld(abi);
+    const source = createRigidBody3D();
+    source.x = -2;
+    source.y = 4;
+    source.velocityX = 1.25;
+    const collider = createPhysics3DCollider(unitAabb());
+    const commands = createPhysics3DAbiCommandBuffer();
+    writePhysics3DAbiSetBodyCommand(commands, 7, source);
+    writePhysics3DAbiSetColliderCommand(commands, 9, 7, collider);
+    executeOrThrow(abi, abiWorld, commands);
+
+    const directWorld = createPhysics3DWorld();
+    const directBody = createRigidBody3D();
+    directBody.x = source.x;
+    directBody.y = source.y;
+    directBody.velocityX = source.velocityX;
+    addPhysics3DBody(directWorld, directBody);
+    addPhysics3DCollider(directWorld, directBody, createPhysics3DCollider(unitAabb()));
+
+    for (let i = 0; i < 120; i += 1) {
+      expect(stepPhysics3DAbiWorld(abi, abiWorld, 1 / 120)).toBe('Complete');
+      stepPhysics3D(directWorld, 1 / 120);
+    }
+
+    const out = createPhysics3DAbiBodyBuffer(1);
+    readPhysics3DAbiBodies(abi, abiWorld, null, out);
+    expect(out.values[Physics3DAbiBodyValue.X]).toBeCloseTo(directBody.x, 12);
+    expect(out.values[Physics3DAbiBodyValue.Y]).toBeCloseTo(directBody.y, 12);
+    expect(out.values[Physics3DAbiBodyValue.VelocityY]).toBeCloseTo(directBody.velocityY, 12);
+  });
+
+  it('adapts synchronous contact hooks without exposing the owned world', () => {
+    const { abi, world } = createContactWorld();
+    const buffer = createPhysics3DAbiContactBuffer(1, 4);
+    const reentrantResult = createPhysics3DAbiExecutionResult();
+    let preSolveCount = 0;
+    let postSolveCount = 0;
+    let nestedStepStatus = '';
+    let statusDuringHook = '';
+    let readDuringHook = true;
+    let queryDuringHook = true;
+    let destroyDuringHook = true;
+
+    expect(
+      stepPhysics3DAbiWorld(abi, world, 1 / 60, {
+        buffer,
+        preSolve(contact): void {
+          preSolveCount += 1;
+          contact.values[3] = 0.75;
+          executePhysics3DAbiCommands(abi, world, createPhysics3DAbiCommandBuffer(), reentrantResult);
+          nestedStepStatus = stepPhysics3DAbiWorld(abi, world, 1 / 60);
+          statusDuringHook = getPhysics3DAbiWorldStatus(abi, world);
+          readDuringHook = readPhysics3DAbiBodies(abi, world, null, createPhysics3DAbiBodyBuffer(1));
+          queryDuringHook = queryPhysics3DAbiPoint(abi, world, 0, 0, 0, createPhysics3DAbiQueryBuffer(1));
+          destroyDuringHook = destroyPhysics3DAbiWorld(abi, world);
+        },
+        postSolve(): void {
+          postSolveCount += 1;
+        },
+      }),
+    ).toBe('Complete');
+    expect(preSolveCount).toBeGreaterThan(0);
+    expect(postSolveCount).toBeGreaterThan(0);
+    expect(reentrantResult.status).toBe('BusyWorld');
+    expect(nestedStepStatus).toBe('BusyWorld');
+    expect(statusDuringHook).toBe('Busy');
+    expect(readDuringHook).toBe(false);
+    expect(queryDuringHook).toBe(false);
+    expect(destroyDuringHook).toBe(false);
+
+    const contacts = createPhysics3DAbiContactBuffer(2, 8);
+    readPhysics3DAbiContacts(abi, world, 'All', contacts);
+    expect(contacts.values[3]).toBe(0.75);
+  });
+
+  it('declines invalid timesteps and insufficient live hook buffers explicitly', () => {
+    const { abi, world } = createContactWorld();
+    expect(stepPhysics3DAbiWorld(abi, world, 0)).toBe('Declined');
+    expect(
+      stepPhysics3DAbiWorld(abi, world, 1 / 60, {
+        buffer: createPhysics3DAbiContactBuffer(0, 0),
+        preSolve(): void {},
+        postSolve: null,
+      }),
+    ).toBe('InsufficientHookBuffer');
+    expect(
+      stepPhysics3DAbiWorld(abi, world, 1 / 60, {
+        buffer: createPhysics3DAbiContactBuffer(0, 0),
+        preSolve: null,
+        postSolve: null,
+      }),
+    ).toBe('Complete');
+  });
+});
+
+function createBodyReadWorld(): { abi: Physics3DAbi; world: number } {
+  const abi = createPhysics3DAbi();
+  const world = createPhysics3DAbiWorld(abi);
+  const commands = createPhysics3DAbiCommandBuffer();
+  const body20 = createRigidBody3D();
+  body20.x = 20;
+  const body10 = createRigidBody3D();
+  body10.x = 10;
+  writePhysics3DAbiSetBodyCommand(commands, 20, body20);
+  writePhysics3DAbiSetBodyCommand(commands, 10, body10);
+  executeOrThrow(abi, world, commands);
+  return { abi, world };
+}
+
+function createContactWorld(): { abi: Physics3DAbi; world: number } {
+  const abi = createPhysics3DAbi();
+  const world = createPhysics3DAbiWorld(abi);
+  const commands = createPhysics3DAbiCommandBuffer();
+  const ground = createRigidBody3D('static');
+  const box = createRigidBody3D();
+  box.y = 0.75;
+  writePhysics3DAbiSetBodyCommand(commands, 2, ground);
+  writePhysics3DAbiSetColliderCommand(commands, 22, 2, createPhysics3DCollider(unitAabb()));
+  writePhysics3DAbiSetBodyCommand(commands, 1, box);
+  writePhysics3DAbiSetColliderCommand(commands, 11, 1, createPhysics3DCollider(unitAabb()));
+  executeOrThrow(abi, world, commands);
+  return { abi, world };
+}
+
+function executeOrThrow(abi: Readonly<Physics3DAbi>, world: number, commands: Physics3DAbiCommandBuffer): void {
+  const result = createPhysics3DAbiExecutionResult();
+  if (!executePhysics3DAbiCommands(abi, world, commands, result)) {
+    throw new Error(`Unexpected ABI command failure: ${result.status} at ${result.commandIndex}`);
+  }
+}
+
+function getColliderShapes(): CollisionColliderShape3D[] {
+  return [
+    { kind: 'sphere', x: 0, y: 0, z: 0, radius: 1 },
+    unitAabb(),
+    {
+      kind: 'box',
+      x: 0,
+      y: 0,
+      z: 0,
+      halfX: 1,
+      halfY: 1,
+      halfZ: 1,
+      rotationX: 0,
+      rotationY: 0,
+      rotationZ: 0,
+      rotationW: 1,
+    },
+    { kind: 'capsule', x0: 0, y0: -1, z0: 0, x1: 0, y1: 1, z1: 0, radius: 0.5 },
+    { kind: 'cylinder', x0: 0, y0: -1, z0: 0, x1: 0, y1: 1, z1: 0, radius: 0.5 },
+    { kind: 'cone', apexX: 0, apexY: 1, apexZ: 0, baseX: 0, baseY: -1, baseZ: 0, radius: 1 },
+    { kind: 'convex', points: [0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1] },
+    {
+      kind: 'triangle-mesh',
+      version: 0,
+      x: 0,
+      y: 0,
+      z: 0,
+      rotationX: 0,
+      rotationY: 0,
+      rotationZ: 0,
+      rotationW: 1,
+      points: [0, 0, 0, 1, 0, 0, 0, 0, 1],
+      indices: [0, 1, 2],
+    },
+    {
+      kind: 'heightfield',
+      columns: 2,
+      rows: 2,
+      version: 0,
+      cellSizeX: 1,
+      cellSizeZ: 1,
+      x: 0,
+      y: 0,
+      z: 0,
+      rotationX: 0,
+      rotationY: 0,
+      rotationZ: 0,
+      rotationW: 1,
+      heights: [0, 0, 0, 0],
+    },
+  ];
+}
+
+function getJoints(): Physics3DJoint[] {
+  return [
+    createPhysics3DBallAndSocketJoint({ bodyA: 10, bodyB: 20 }),
+    createPhysics3DDistanceJoint({ bodyA: 10, bodyB: 20, length: 1 }),
+    createPhysics3DFixedJoint({ bodyA: 10, bodyB: 20 }),
+    createPhysics3DHingeJoint({ bodyA: 10, bodyB: 20 }),
+    createPhysics3DSliderJoint({ bodyA: 10, bodyB: 20 }),
+    createPhysics3DConeTwistJoint({ bodyA: 10, bodyB: 20 }),
+    createPhysics3DGeneric6DofJoint({ bodyA: 10, bodyB: 20 }),
+  ];
+}
+
+function unitAabb(): CollisionColliderShape3D {
+  return { kind: 'aabb', minX: -0.5, minY: -0.5, minZ: -0.5, maxX: 0.5, maxY: 0.5, maxZ: 0.5 };
+}
+
+function writeCommands(write: (commands: Physics3DAbiCommandBuffer) => void): Physics3DAbiCommandBuffer {
+  const commands = createPhysics3DAbiCommandBuffer();
+  write(commands);
+  return commands;
+}

package/src/physics3DAbiBuffer.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  clearPhysics3DAbiCommandBuffer,
+  createPhysics3DAbiBodyBuffer,
+  createPhysics3DAbiCommandBuffer,
+  createPhysics3DAbiContactBuffer,
+  createPhysics3DAbiExecutionResult,
+  createPhysics3DAbiJointBuffer,
+  createPhysics3DAbiQueryBuffer,
+  getPhysics3DAbiCommandBufferRemainingByteLength,
+} from './physics3DAbiBuffer';
+import {
+  Physics3DAbiBodyValueStride,
+  Physics3DAbiCommandHeaderByteLength,
+  Physics3DAbiCommandMagic,
+  Physics3DAbiContactIdStride,
+  Physics3DAbiContactPointValueStride,
+  Physics3DAbiContactValueStride,
+  Physics3DAbiJointValueStride,
+  Physics3DAbiQueryValueStride,
+  Physics3DAbiVersion,
+} from './physics3DAbiLayout';
+
+describe('clearPhysics3DAbiCommandBuffer', () => {
+  it('rewrites the canonical little-endian header and resets the published stream', () => {
+    const out = createPhysics3DAbiCommandBuffer(64);
+    out.data.fill(0xff);
+    out.byteLength = 64;
+    out.commandCount = 3;
+
+    clearPhysics3DAbiCommandBuffer(out);
+
+    const view = new DataView(out.data.buffer);
+    expect(view.getUint32(0, true)).toBe(Physics3DAbiCommandMagic);
+    expect(view.getUint32(4, true)).toBe(Physics3DAbiVersion);
+    expect(view.getUint32(8, true)).toBe(Physics3DAbiCommandHeaderByteLength);
+    expect(view.getUint32(12, true)).toBe(0);
+    expect(out.byteLength).toBe(Physics3DAbiCommandHeaderByteLength);
+    expect(out.commandCount).toBe(0);
+  });
+});
+
+describe('createPhysics3DAbiBodyBuffer', () => {
+  it('allocates the documented structure-of-arrays capacity', () => {
+    const out = createPhysics3DAbiBodyBuffer(3);
+    expect(out.ids).toHaveLength(3);
+    expect(out.flags).toHaveLength(3);
+    expect(out.values).toHaveLength(3 * Physics3DAbiBodyValueStride);
+    expect([out.count, out.requiredCount]).toEqual([0, 0]);
+  });
+});
+
+describe('createPhysics3DAbiCommandBuffer', () => {
+  it('allocates only through an explicit byte capacity', () => {
+    const out = createPhysics3DAbiCommandBuffer(80);
+    expect(out.data).toHaveLength(80);
+    expect(out.byteLength).toBe(Physics3DAbiCommandHeaderByteLength);
+  });
+
+  it('rejects a capacity that cannot hold the stream header', () => {
+    expect(() => createPhysics3DAbiCommandBuffer(15)).toThrow(RangeError);
+  });
+});
+
+describe('createPhysics3DAbiContactBuffer', () => {
+  it('allocates contact and point capacities independently', () => {
+    const out = createPhysics3DAbiContactBuffer(2, 5);
+    expect(out.ids).toHaveLength(2 * Physics3DAbiContactIdStride);
+    expect(out.values).toHaveLength(2 * Physics3DAbiContactValueStride);
+    expect(out.pointFeatureIds).toHaveLength(5);
+    expect(out.pointValues).toHaveLength(5 * Physics3DAbiContactPointValueStride);
+  });
+});
+
+describe('createPhysics3DAbiExecutionResult', () => {
+  it('starts at a complete empty stream boundary', () => {
+    expect(createPhysics3DAbiExecutionResult()).toEqual({
+      status: 'Complete',
+      commandIndex: 0,
+      byteOffset: Physics3DAbiCommandHeaderByteLength,
+      commandKind: 0,
+    });
+  });
+});
+
+describe('createPhysics3DAbiJointBuffer', () => {
+  it('allocates one reaction row per joint', () => {
+    const out = createPhysics3DAbiJointBuffer(4);
+    expect(out.ids).toHaveLength(4);
+    expect(out.flags).toHaveLength(4);
+    expect(out.values).toHaveLength(4 * Physics3DAbiJointValueStride);
+  });
+});
+
+describe('createPhysics3DAbiQueryBuffer', () => {
+  it('allocates identity and geometry rows at the same capacity', () => {
+    const out = createPhysics3DAbiQueryBuffer(6);
+    expect(out.bodyIds).toHaveLength(6);
+    expect(out.colliderIds).toHaveLength(6);
+    expect(out.values).toHaveLength(6 * Physics3DAbiQueryValueStride);
+  });
+
+  it('rejects negative and fractional capacities', () => {
+    expect(() => createPhysics3DAbiQueryBuffer(-1)).toThrow(RangeError);
+    expect(() => createPhysics3DAbiQueryBuffer(1.5)).toThrow(RangeError);
+  });
+});
+
+describe('getPhysics3DAbiCommandBufferRemainingByteLength', () => {
+  it('reports capacity after the published prefix without going negative', () => {
+    const out = createPhysics3DAbiCommandBuffer(64);
+    expect(getPhysics3DAbiCommandBufferRemainingByteLength(out)).toBe(48);
+    out.byteLength = 80;
+    expect(getPhysics3DAbiCommandBufferRemainingByteLength(out)).toBe(0);
+  });
+});