@flighthq/physics2d-abi 0.4.0-edge.1908.751021c

package/src/physics2DAbiCommand.test.ts

@@ -0,0 +1,337 @@
+import {
+  createPhysics2DCollider,
+  createPhysics2DDistanceJoint,
+  createPhysics2DGearJoint,
+  createPhysics2DMouseJoint,
+  createPhysics2DPrismaticJoint,
+  createPhysics2DPulleyJoint,
+  createPhysics2DRevoluteJoint,
+  createPhysics2DRopeJoint,
+  createPhysics2DSolverConfig,
+  createPhysics2DWeldJoint,
+  createPhysics2DWheelJoint,
+  createRigidBody2D,
+} from '@flighthq/physics2d/contract';
+import type { CollisionBuiltInShape2D, Physics2DJoint } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createPhysics2DAbiCommandBuffer } from './physics2DAbiBuffer';
+import {
+  getPhysics2DAbiSetColliderCommandByteLength,
+  writePhysics2DAbiApplyForceAtPointCommand,
+  writePhysics2DAbiApplyForceCommand,
+  writePhysics2DAbiApplyLinearImpulseAtPointCommand,
+  writePhysics2DAbiApplyLinearImpulseCommand,
+  writePhysics2DAbiApplyTorqueCommand,
+  writePhysics2DAbiDestroyBodyCommand,
+  writePhysics2DAbiDestroyColliderCommand,
+  writePhysics2DAbiDestroyJointCommand,
+  writePhysics2DAbiSetBodyCommand,
+  writePhysics2DAbiSetColliderCommand,
+  writePhysics2DAbiSetGravityCommand,
+  writePhysics2DAbiSetJointCommand,
+  writePhysics2DAbiSetSolverConfigCommand,
+  writePhysics2DAbiWakeBodyCommand,
+} from './physics2DAbiCommand';
+import {
+  Physics2DAbiCommandByteLength,
+  Physics2DAbiCommandHeaderByteLength,
+  Physics2DAbiCommandKind,
+  Physics2DAbiCommandRecordHeaderByteLength,
+  Physics2DAbiJointFlag,
+  Physics2DAbiJointKind,
+  Physics2DAbiShapeHeaderByteLength,
+  Physics2DAbiShapeKind,
+} from './physics2DAbiLayout';
+
+const MATERIAL = { density: 1, friction: 0.3, restitution: 0.1 };
+
+function record(buffer: ReturnType<typeof createPhysics2DAbiCommandBuffer>, at = Physics2DAbiCommandHeaderByteLength) {
+  const view = new DataView(buffer.data.buffer);
+  return {
+    view,
+    kind: view.getUint32(at, true),
+    byteLength: view.getUint32(at + 4, true),
+    objectId: view.getUint32(at + 8, true),
+    relatedId: view.getUint32(at + 12, true),
+    payload: at + Physics2DAbiCommandRecordHeaderByteLength,
+  };
+}
+
+function body() {
+  const value = createRigidBody2D('dynamic', 3, -4, 0.5);
+  value.velocityX = 1;
+  value.velocityY = 2;
+  value.angularVelocity = 3;
+  return value;
+}
+
+describe('getPhysics2DAbiSetColliderCommandByteLength', () => {
+  it('reports the exact length the writer will consume, per shape', () => {
+    const shapes: [CollisionBuiltInShape2D, number][] = [
+      [{ kind: 'circle', x: 0, y: 0, radius: 1 }, 3],
+      [{ kind: 'aabb', minX: -1, minY: -1, maxX: 1, maxY: 1 }, 4],
+      [{ kind: 'obb', x: 0, y: 0, halfW: 1, halfH: 2, rotation: 0.5 }, 5],
+      [{ kind: 'capsule', x0: -1, y0: 0, x1: 1, y1: 0, radius: 0.5 }, 5],
+      [{ kind: 'polygon', points: [0, 0, 1, 0, 0, 1] }, 6],
+      [{ kind: 'segment', x0: 0, y0: 0, x1: 1, y1: 1 }, 4],
+      [{ kind: 'point', x: 2, y: 3 }, 2],
+    ];
+    for (const [shape, scalarCount] of shapes) {
+      const collider = createPhysics2DCollider(shape, MATERIAL);
+      const expected = Physics2DAbiCommandByteLength.SetColliderMinimum + scalarCount * 8;
+      expect(getPhysics2DAbiSetColliderCommandByteLength(collider), shape.kind).toBe(expected);
+
+      const buffer = createPhysics2DAbiCommandBuffer(1024);
+      expect(writePhysics2DAbiSetColliderCommand(buffer, 1, 1, collider), shape.kind).toBe(true);
+      expect(buffer.byteLength - Physics2DAbiCommandHeaderByteLength, shape.kind).toBe(expected);
+    }
+  });
+});
+
+describe('writePhysics2DAbiApplyForceAtPointCommand', () => {
+  it('carries the world point in the second pair', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiApplyForceAtPointCommand(buffer, 2, 5, 6, 7, 8)).toBe(true);
+    const written = record(buffer);
+    expect(written.view.getFloat64(written.payload + 16, true)).toBe(7);
+    expect(written.view.getFloat64(written.payload + 24, true)).toBe(8);
+  });
+});
+
+describe('writePhysics2DAbiApplyForceCommand', () => {
+  it('zeroes the point slots a pointless action does not use', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiApplyForceCommand(buffer, 2, 5, 6)).toBe(true);
+    const written = record(buffer);
+    expect(written.kind).toBe(Physics2DAbiCommandKind.ApplyForce);
+    expect(written.view.getFloat64(written.payload, true)).toBe(5);
+    expect(written.view.getFloat64(written.payload + 16, true)).toBe(0);
+  });
+});
+
+describe('writePhysics2DAbiApplyLinearImpulseAtPointCommand', () => {
+  it('uses its own discriminant rather than the pointless one', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiApplyLinearImpulseAtPointCommand(buffer, 1, 1, 1, 2, 2)).toBe(true);
+    expect(record(buffer).kind).toBe(Physics2DAbiCommandKind.ApplyLinearImpulseAtPoint);
+  });
+});
+
+describe('writePhysics2DAbiApplyLinearImpulseCommand', () => {
+  it('uses its own discriminant rather than the force one', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiApplyLinearImpulseCommand(buffer, 1, 1, 1)).toBe(true);
+    expect(record(buffer).kind).toBe(Physics2DAbiCommandKind.ApplyLinearImpulse);
+  });
+});
+
+describe('writePhysics2DAbiApplyTorqueCommand', () => {
+  it('leaves the three unused body-action slots zero', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiApplyTorqueCommand(buffer, 1, 12)).toBe(true);
+    const written = record(buffer);
+    expect(written.view.getFloat64(written.payload, true)).toBe(12);
+    expect(written.view.getFloat64(written.payload + 8, true)).toBe(0);
+    expect(written.view.getFloat64(written.payload + 16, true)).toBe(0);
+    expect(written.view.getFloat64(written.payload + 24, true)).toBe(0);
+  });
+});
+
+describe('writePhysics2DAbiDestroyBodyCommand', () => {
+  it('writes a header-only record', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiDestroyBodyCommand(buffer, 3)).toBe(true);
+    expect(record(buffer).byteLength).toBe(Physics2DAbiCommandRecordHeaderByteLength);
+    expect(record(buffer).objectId).toBe(3);
+  });
+});
+
+describe('writePhysics2DAbiDestroyColliderCommand', () => {
+  it('writes a header-only record', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiDestroyColliderCommand(buffer, 4)).toBe(true);
+    expect(record(buffer).kind).toBe(Physics2DAbiCommandKind.DestroyCollider);
+  });
+});
+
+describe('writePhysics2DAbiDestroyJointCommand', () => {
+  it('writes a header-only record', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiDestroyJointCommand(buffer, 5)).toBe(true);
+    expect(record(buffer).kind).toBe(Physics2DAbiCommandKind.DestroyJoint);
+  });
+});
+
+describe('writePhysics2DAbiSetBodyCommand', () => {
+  it('writes a fixed-length record carrying the seventeen body scalars', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    expect(writePhysics2DAbiSetBodyCommand(buffer, 9, body())).toBe(true);
+    const written = record(buffer);
+    expect(written.kind).toBe(Physics2DAbiCommandKind.SetBody);
+    expect(written.byteLength).toBe(Physics2DAbiCommandByteLength.SetBody);
+    expect(written.objectId).toBe(9);
+    expect(written.relatedId).toBe(0);
+    expect(written.view.getFloat64(written.payload + 8, true)).toBe(3);
+    expect(written.view.getFloat64(written.payload + 16, true)).toBe(-4);
+    expect(written.view.getFloat64(written.payload + 24, true)).toBe(0.5);
+  });
+
+  it('refuses an id outside the non-zero uint32 range', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    expect(writePhysics2DAbiSetBodyCommand(buffer, 0, body())).toBe(false);
+    expect(writePhysics2DAbiSetBodyCommand(buffer, 1.5, body())).toBe(false);
+    expect(buffer.commandCount).toBe(0);
+  });
+
+  it('leaves the stream untouched when the record does not fit', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(Physics2DAbiCommandHeaderByteLength + 8);
+    expect(writePhysics2DAbiSetBodyCommand(buffer, 1, body())).toBe(false);
+    expect(buffer.byteLength).toBe(Physics2DAbiCommandHeaderByteLength);
+    expect(buffer.commandCount).toBe(0);
+  });
+});
+
+describe('writePhysics2DAbiSetColliderCommand', () => {
+  it('names the body in the related id and encodes the shape inline', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    const collider = createPhysics2DCollider({ kind: 'circle', x: 1, y: 2, radius: 3 }, MATERIAL, true, {
+      categoryBits: 5,
+      maskBits: 6,
+      groupIndex: -7,
+    });
+    expect(writePhysics2DAbiSetColliderCommand(buffer, 4, 8, collider)).toBe(true);
+    const written = record(buffer);
+    expect(written.objectId).toBe(4);
+    expect(written.relatedId).toBe(8);
+    expect(written.view.getUint32(written.payload, true)).toBe(1);
+    expect(written.view.getUint32(written.payload + 4, true)).toBe(5);
+    expect(written.view.getUint32(written.payload + 8, true)).toBe(6);
+    expect(written.view.getInt32(written.payload + 12, true)).toBe(-7);
+    expect(written.view.getFloat64(written.payload + 16, true)).toBe(1);
+    const shapeAt = written.payload + 40;
+    expect(written.view.getUint32(shapeAt, true)).toBe(Physics2DAbiShapeKind.Circle);
+    expect(written.view.getUint32(shapeAt + 4, true)).toBe(3);
+    expect(written.view.getUint32(shapeAt + 8, true)).toBe(0);
+    expect(written.view.getFloat64(shapeAt + Physics2DAbiShapeHeaderByteLength, true)).toBe(1);
+  });
+
+  it('refuses a filter that will not fit its integer field', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    const collider = createPhysics2DCollider({ kind: 'circle', x: 0, y: 0, radius: 1 }, MATERIAL);
+    collider.filter.categoryBits = -1;
+    expect(writePhysics2DAbiSetColliderCommand(buffer, 1, 1, collider)).toBe(false);
+  });
+});
+
+describe('writePhysics2DAbiSetGravityCommand', () => {
+  it('carries two components and names no object', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiSetGravityCommand(buffer, 1, -9.81)).toBe(true);
+    const written = record(buffer);
+    expect(written.kind).toBe(Physics2DAbiCommandKind.SetGravity);
+    expect(written.objectId).toBe(0);
+    expect(written.view.getFloat64(written.payload, true)).toBe(1);
+    expect(written.view.getFloat64(written.payload + 8, true)).toBe(-9.81);
+  });
+});
+
+describe('writePhysics2DAbiSetJointCommand', () => {
+  it('encodes every built-in kind with its own discriminant', () => {
+    const cases: [Physics2DJoint, number][] = [
+      [createPhysics2DDistanceJoint({ bodyA: 0, bodyB: 1, length: 2 }), Physics2DAbiJointKind.Distance],
+      [createPhysics2DRevoluteJoint({ bodyA: 0, bodyB: 1 }), Physics2DAbiJointKind.Revolute],
+      [createPhysics2DPrismaticJoint({ bodyA: 0, bodyB: 1 }), Physics2DAbiJointKind.Prismatic],
+      [createPhysics2DWeldJoint({ bodyA: 0, bodyB: 1 }), Physics2DAbiJointKind.Weld],
+      [createPhysics2DWheelJoint({ bodyA: 0, bodyB: 1 }), Physics2DAbiJointKind.Wheel],
+      [createPhysics2DRopeJoint({ bodyA: 0, bodyB: 1, maxLength: 3 }), Physics2DAbiJointKind.Rope],
+      [createPhysics2DMouseJoint({ body: 0, targetX: 1, targetY: 2, maxForce: 10 }), Physics2DAbiJointKind.Mouse],
+      [
+        createPhysics2DPulleyJoint({
+          bodyA: 0,
+          bodyB: 1,
+          groundAnchorAX: 0,
+          groundAnchorAY: 4,
+          groundAnchorBX: 2,
+          groundAnchorBY: 4,
+          ratio: 1,
+          constant: 6,
+        }),
+        Physics2DAbiJointKind.Pulley,
+      ],
+      [
+        createPhysics2DGearJoint({
+          bodyA: 0,
+          bodyB: 1,
+          ratio: 2,
+          constant: 0,
+          coordinateA: 'angular',
+          coordinateB: 'angular',
+        }),
+        Physics2DAbiJointKind.Gear,
+      ],
+    ];
+    for (const [joint, kind] of cases) {
+      const buffer = createPhysics2DAbiCommandBuffer(1024);
+      expect(writePhysics2DAbiSetJointCommand(buffer, 1, 1, 2, joint), joint.kind).toBe(true);
+      const written = record(buffer);
+      expect(written.byteLength, joint.kind).toBe(Physics2DAbiCommandByteLength.SetJoint);
+      expect(written.view.getUint32(written.payload, true), joint.kind).toBe(kind);
+      expect(written.view.getUint32(written.payload + 4, true), joint.kind).toBe(1);
+      expect(written.view.getUint32(written.payload + 8, true), joint.kind).toBe(2);
+    }
+  });
+
+  it('refuses a kind with no wire discriminant rather than writing a zero one', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    const joint = createPhysics2DDistanceJoint({ bodyA: 0, bodyB: 1, length: 1 });
+    expect(writePhysics2DAbiSetJointCommand(buffer, 1, 1, 2, { ...joint, kind: 'acme.Conveyor' })).toBe(false);
+    expect(buffer.commandCount).toBe(0);
+  });
+
+  it('reads a gear coordinate pair out of the flags it shares with the enable bits', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(1024);
+    const joint = createPhysics2DGearJoint({
+      bodyA: 0,
+      bodyB: 1,
+      ratio: 1,
+      constant: 0,
+      coordinateA: 'linear',
+      coordinateB: 'angular',
+    });
+    expect(writePhysics2DAbiSetJointCommand(buffer, 1, 1, 2, joint)).toBe(true);
+    const flags = record(buffer).view.getUint32(record(buffer).payload + 12, true);
+    expect(flags & Physics2DAbiJointFlag.LinearCoordinateA).toBe(Physics2DAbiJointFlag.LinearCoordinateA);
+    expect(flags & Physics2DAbiJointFlag.LinearCoordinateB).toBe(0);
+  });
+});
+
+describe('writePhysics2DAbiSetSolverConfigCommand', () => {
+  it('packs the three booleans into flags and holds the substep word zero', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    const config = createPhysics2DSolverConfig();
+    expect(writePhysics2DAbiSetSolverConfigCommand(buffer, config)).toBe(true);
+    const written = record(buffer);
+    expect(written.byteLength).toBe(Physics2DAbiCommandByteLength.SetSolverConfig);
+    expect(written.view.getUint32(written.payload + 4, true)).toBe(0);
+    expect(written.view.getUint32(written.payload + 16, true)).toBe(config.velocityIterations);
+    expect(written.view.getUint32(written.payload + 20, true)).toBe(config.positionIterations);
+    expect(written.view.getFloat64(written.payload + 32, true)).toBe(config.sleepLinearThreshold);
+  });
+
+  it('refuses an iteration count that is not a uint32', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(
+      writePhysics2DAbiSetSolverConfigCommand(buffer, { ...createPhysics2DSolverConfig(), velocityIterations: -1 }),
+    ).toBe(false);
+  });
+});
+
+describe('writePhysics2DAbiWakeBodyCommand', () => {
+  it('writes a header-only record and rejects a zero id', () => {
+    const buffer = createPhysics2DAbiCommandBuffer(256);
+    expect(writePhysics2DAbiWakeBodyCommand(buffer, 0)).toBe(false);
+    expect(writePhysics2DAbiWakeBodyCommand(buffer, 6)).toBe(true);
+    expect(record(buffer).kind).toBe(Physics2DAbiCommandKind.WakeBody);
+  });
+});

package/src/physics2DAbiLayout.test.ts

@@ -0,0 +1,293 @@
+import { collideContactManifold2D, createCollisionContactManifold2D } from '@flighthq/collision/contract';
+import type { CollisionBuiltInShape2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  Physics2DAbiBodyFlag,
+  Physics2DAbiBodyType,
+  Physics2DAbiBodyValue,
+  Physics2DAbiBodyValueStride,
+  Physics2DAbiCapability,
+  Physics2DAbiCommandByteLength,
+  Physics2DAbiCommandHeaderByteLength,
+  Physics2DAbiCommandHeaderOffset,
+  Physics2DAbiCommandKind,
+  Physics2DAbiCommandMagic,
+  Physics2DAbiCommandRecordHeaderByteLength,
+  Physics2DAbiCommandRecordOffset,
+  Physics2DAbiContactFlag,
+  Physics2DAbiContactId,
+  Physics2DAbiContactIdStride,
+  Physics2DAbiContactPointValue,
+  Physics2DAbiContactPointValueStride,
+  Physics2DAbiContactValue,
+  Physics2DAbiContactValueStride,
+  Physics2DAbiJointCommonValue,
+  Physics2DAbiJointFlag,
+  Physics2DAbiJointKind,
+  Physics2DAbiJointKindValueCount,
+  Physics2DAbiJointValue,
+  Physics2DAbiJointValueStride,
+  Physics2DAbiMaxContactPoints,
+  Physics2DAbiQueryValue,
+  Physics2DAbiQueryValueStride,
+  Physics2DAbiSetBodyPayloadOffset,
+  Physics2DAbiSetColliderPayloadOffset,
+  Physics2DAbiSetJointPayloadOffset,
+  Physics2DAbiSetSolverConfigPayloadOffset,
+  Physics2DAbiShapeHeaderByteLength,
+  Physics2DAbiShapeHeaderOffset,
+  Physics2DAbiShapeKind,
+  Physics2DAbiSolverConfigFlag,
+  Physics2DAbiSolverConfigValue,
+  Physics2DAbiVersion,
+} from './physics2DAbiLayout';
+
+describe('Physics2DAbiBodyFlag', () => {
+  it('reserves the low two bits for the type and one bit each above it', () => {
+    expect(Physics2DAbiBodyFlag.TypeMask).toBe(0b11);
+    expect(Object.values(Physics2DAbiBodyType)).toEqual([0, 1, 2]);
+    for (const type of Object.values(Physics2DAbiBodyType)) expect(type & Physics2DAbiBodyFlag.TypeMask).toBe(type);
+    expect(Physics2DAbiBodyFlag.FixedRotation).toBe(4);
+    expect(Physics2DAbiBodyFlag.SleepEnabled).toBe(32);
+  });
+});
+
+// These constants ARE the wire contract. A test that recomputed them from the source would agree with
+// any change, so every number here is written out literally: changing one has to be a deliberate edit
+// in two places, which is the only thing that makes a version bump a decision rather than an accident.
+describe('Physics2DAbiBodyValue', () => {
+  it('indexes seventeen authored body scalars in wire order', () => {
+    expect(Physics2DAbiBodyValueStride).toBe(17);
+    expect(Object.values(Physics2DAbiBodyValue)).toEqual([...Array(17).keys()]);
+    expect(Physics2DAbiBodyValue.X).toBe(0);
+    expect(Physics2DAbiBodyValue.Angle).toBe(2);
+    expect(Physics2DAbiBodyValue.Mass).toBe(9);
+    expect(Physics2DAbiBodyValue.SleepTimer).toBe(16);
+  });
+});
+
+describe('Physics2DAbiCapability', () => {
+  it('declares one bit per optional backend feature', () => {
+    expect(Physics2DAbiCapability).toEqual({
+      ContactHooks: 1,
+      PersistentWorlds: 2,
+      Queries: 4,
+      SelectiveReadback: 8,
+    });
+  });
+});
+
+describe('Physics2DAbiCommandByteLength', () => {
+  it('keeps every record eight-aligned and consistent with its payload', () => {
+    for (const [name, byteLength] of Object.entries(Physics2DAbiCommandByteLength)) {
+      expect(byteLength % 8, name).toBe(0);
+      expect(byteLength, name).toBeGreaterThanOrEqual(Physics2DAbiCommandRecordHeaderByteLength);
+    }
+    expect(Physics2DAbiCommandByteLength.SetGravity).toBe(Physics2DAbiCommandRecordHeaderByteLength + 2 * 8);
+    expect(Physics2DAbiCommandByteLength.SetBody).toBe(
+      Physics2DAbiCommandRecordHeaderByteLength + Physics2DAbiSetBodyPayloadOffset.Values + 17 * 8,
+    );
+    expect(Physics2DAbiCommandByteLength.SetJoint).toBe(
+      Physics2DAbiCommandRecordHeaderByteLength + Physics2DAbiSetJointPayloadOffset.KindValues + 9 * 8,
+    );
+    expect(Physics2DAbiCommandByteLength.SetSolverConfig).toBe(
+      Physics2DAbiCommandRecordHeaderByteLength + Physics2DAbiSetSolverConfigPayloadOffset.Values + 6 * 8,
+    );
+    expect(Physics2DAbiCommandByteLength.BodyAction).toBe(Physics2DAbiCommandRecordHeaderByteLength + 4 * 8);
+    expect(Physics2DAbiCommandByteLength.SetColliderMinimum).toBe(
+      Physics2DAbiCommandRecordHeaderByteLength +
+        Physics2DAbiSetColliderPayloadOffset.Shape +
+        Physics2DAbiShapeHeaderByteLength,
+    );
+  });
+});
+
+describe('Physics2DAbiCommandKind', () => {
+  it('assigns each command a stable discriminant', () => {
+    expect(Physics2DAbiCommandKind).toEqual({
+      SetGravity: 1,
+      SetSolverConfig: 2,
+      SetBody: 3,
+      DestroyBody: 4,
+      SetCollider: 5,
+      DestroyCollider: 6,
+      SetJoint: 7,
+      DestroyJoint: 8,
+      ApplyForce: 9,
+      ApplyForceAtPoint: 10,
+      ApplyLinearImpulse: 11,
+      ApplyLinearImpulseAtPoint: 12,
+      ApplyTorque: 13,
+      WakeBody: 14,
+    });
+  });
+});
+
+describe('Physics2DAbiCommandMagic', () => {
+  it('spells P2DA, distinguishing the stream from the 3D one at the header', () => {
+    expect(Physics2DAbiCommandMagic).toBe(0x41443250);
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, Physics2DAbiCommandMagic, true);
+    expect(String.fromCharCode(...bytes)).toBe('P2DA');
+    expect(Physics2DAbiVersion).toBe(1);
+    expect(Physics2DAbiCommandHeaderByteLength).toBe(16);
+    expect(Physics2DAbiCommandHeaderOffset).toEqual({ Magic: 0, Version: 4, ByteLength: 8, CommandCount: 12 });
+    expect(Physics2DAbiCommandRecordOffset).toEqual({ Kind: 0, ByteLength: 4, ObjectId: 8, RelatedId: 12 });
+  });
+});
+
+describe('Physics2DAbiContactFlag', () => {
+  it('names the three contact states the standard record carries', () => {
+    expect(Physics2DAbiContactFlag).toEqual({ Enabled: 1, Sensor: 2, Touching: 4 });
+  });
+});
+
+describe('Physics2DAbiContactValue', () => {
+  it('sizes a manifold to the exact planar bound of two points', () => {
+    expect(Physics2DAbiMaxContactPoints).toBe(2);
+    expect(Physics2DAbiContactIdStride).toBe(4);
+    expect(Physics2DAbiContactValueStride).toBe(4);
+    expect(Physics2DAbiContactPointValueStride).toBe(7);
+    expect(Object.values(Physics2DAbiContactId)).toEqual([0, 1, 2, 3]);
+    expect(Object.values(Physics2DAbiContactValue)).toEqual([0, 1, 2, 3]);
+    expect(Object.values(Physics2DAbiContactPointValue)).toEqual([0, 1, 2, 3, 4, 5, 6]);
+  });
+});
+
+describe('Physics2DAbiJointFlag', () => {
+  it('overlays the gear coordinate bits on the enable bits, which no kind uses together', () => {
+    expect(Physics2DAbiJointFlag.CollideConnected).toBe(1);
+    expect(Physics2DAbiJointFlag.Broken).toBe(2);
+    // Deliberate aliasing: a record carries exactly one kind, so a gear's coordinates and a revolute's
+    // motor/limit bits can share positions 2 and 3 without either ever reading the other's meaning.
+    expect(Physics2DAbiJointFlag.LinearCoordinateA).toBe(Physics2DAbiJointFlag.EnableMotor);
+    expect(Physics2DAbiJointFlag.LinearCoordinateB).toBe(Physics2DAbiJointFlag.EnableLimit);
+  });
+});
+
+describe('Physics2DAbiJointKind', () => {
+  it('covers all nine built-in 2D joints', () => {
+    expect(Physics2DAbiJointKind).toEqual({
+      Distance: 1,
+      Revolute: 2,
+      Prismatic: 3,
+      Weld: 4,
+      Wheel: 5,
+      Rope: 6,
+      Mouse: 7,
+      Pulley: 8,
+      Gear: 9,
+    });
+    expect(Physics2DAbiJointKindValueCount).toBe(9);
+    expect(Object.values(Physics2DAbiJointCommonValue)).toEqual([0, 1, 2, 3, 4, 5]);
+    expect(Object.values(Physics2DAbiJointValue)).toEqual([0, 1, 2]);
+    expect(Physics2DAbiJointValueStride).toBe(3);
+  });
+});
+
+describe('Physics2DAbiMaxContactPoints', () => {
+  it('is not exceeded by any built-in 2D manifold, swept rather than argued', () => {
+    // The hook buffer reserves exactly this many point slots, and `writeContact` clamps to it. That the
+    // planar bound is two is a geometric argument in a comment; collision exports no 2D counterpart to
+    // MAX_COLLISION_CONTACT_POINTS_3D to check it against, so this sweeps the pair matrix instead. If a
+    // future shape or manifold change produces a third point, a contact hook would silently see a
+    // truncated manifold, and this is what would say so.
+    const shapes: CollisionBuiltInShape2D[] = [
+      { kind: 'circle', x: 0, y: 0, radius: 0.6 },
+      { kind: 'aabb', minX: -0.6, minY: -0.6, maxX: 0.6, maxY: 0.6 },
+      { kind: 'obb', x: 0, y: 0, halfW: 0.6, halfH: 0.4, rotation: 0 },
+      { kind: 'capsule', x0: -0.5, y0: 0, x1: 0.5, y1: 0, radius: 0.35 },
+      { kind: 'polygon', points: [-0.6, -0.5, 0.6, -0.5, 0.7, 0.4, -0.4, 0.6] },
+    ];
+    const manifold = createCollisionContactManifold2D();
+    let widest = 0;
+    let overlaps = 0;
+    for (const a of shapes) {
+      for (const b of shapes) {
+        // Slide one shape across the other on both axes and at several angles, so face-face,
+        // face-vertex, and end-on arrangements are all reached rather than one lucky pose.
+        for (let step = -12; step <= 12; step += 1) {
+          const offset = step * 0.1;
+          for (const rotation of [0, 0.37, Math.PI / 4, 1.2]) {
+            const moved = translateShape(b, offset, offset * 0.5, rotation);
+            if (!collideContactManifold2D(a, moved, manifold)) continue;
+            overlaps += 1;
+            widest = Math.max(widest, manifold.pointCount);
+          }
+        }
+      }
+    }
+    // The sweep has to actually collide things, or "never exceeded" is a statement about no manifolds.
+    expect(overlaps).toBeGreaterThan(100);
+    expect(widest).toBe(Physics2DAbiMaxContactPoints);
+  });
+});
+
+describe('Physics2DAbiQueryValue', () => {
+  it('carries fraction, point, and normal in five slots', () => {
+    expect(Physics2DAbiQueryValueStride).toBe(5);
+    expect(Physics2DAbiQueryValue).toEqual({ Fraction: 0, X: 1, Y: 2, NormalX: 3, NormalY: 4 });
+  });
+});
+
+describe('Physics2DAbiShapeKind', () => {
+  it('covers all seven built-in 2D shapes, including the two area-less ones', () => {
+    expect(Physics2DAbiShapeKind).toEqual({
+      Circle: 1,
+      Aabb: 2,
+      Obb: 3,
+      Capsule: 4,
+      Polygon: 5,
+      Segment: 6,
+      Point: 7,
+    });
+    expect(Physics2DAbiShapeHeaderByteLength).toBe(16);
+    expect(Physics2DAbiShapeHeaderOffset).toEqual({
+      Kind: 0,
+      ScalarCount: 4,
+      IntegerCount: 8,
+      Version: 12,
+      Scalars: 16,
+    });
+  });
+});
+
+describe('Physics2DAbiSolverConfigFlag', () => {
+  it('holds the substep word zero, since Physics2D has no substeps', () => {
+    expect(Physics2DAbiSolverConfigFlag).toEqual({ AllowSleeping: 1, ContinuousCollision: 2, WarmStarting: 4 });
+    expect(Physics2DAbiSetSolverConfigPayloadOffset.Reserved0).toBe(4);
+    expect(Object.values(Physics2DAbiSolverConfigValue)).toEqual([0, 1, 2, 3, 4, 5]);
+  });
+});
+
+// Moves a shape by (dx, dy), additionally rotating the kinds that carry an angle so the sweep reaches
+// arrangements an axis-aligned slide never would.
+function translateShape(shape: Readonly<CollisionBuiltInShape2D>, dx: number, dy: number, rotation: number) {
+  if (shape.kind === 'circle') return { ...shape, x: shape.x + dx, y: shape.y + dy };
+  if (shape.kind === 'aabb') {
+    return { ...shape, minX: shape.minX + dx, minY: shape.minY + dy, maxX: shape.maxX + dx, maxY: shape.maxY + dy };
+  }
+  if (shape.kind === 'obb') return { ...shape, x: shape.x + dx, y: shape.y + dy, rotation };
+  if (shape.kind === 'capsule') {
+    const cos = Math.cos(rotation);
+    const sin = Math.sin(rotation);
+    return {
+      ...shape,
+      x0: shape.x0 * cos - shape.y0 * sin + dx,
+      y0: shape.x0 * sin + shape.y0 * cos + dy,
+      x1: shape.x1 * cos - shape.y1 * sin + dx,
+      y1: shape.x1 * sin + shape.y1 * cos + dy,
+    };
+  }
+  if (shape.kind !== 'polygon') return shape;
+  const cos = Math.cos(rotation);
+  const sin = Math.sin(rotation);
+  const points: number[] = [];
+  for (let i = 0; i < shape.points.length; i += 2) {
+    const x = shape.points[i];
+    const y = shape.points[i + 1];
+    points.push(x * cos - y * sin + dx, x * sin + y * cos + dy);
+  }
+  return { ...shape, points };
+}