@aura3d/physics 1.0.6

package/src/CollisionVolumes.ts

@@ -0,0 +1,218 @@
+import { cloneVec3, validateFiniteVec3, type Bounds, type Vec3 } from "./Shape.js";
+
+export type CombatFacing = -1 | 1;
+export type CollisionOwnerId = string | number;
+export type CollisionVolumeKind = "hitbox" | "hurtbox" | "pushbox" | "guardbox";
+
+export type CollisionVolumeDescriptor = {
+  readonly id?: string;
+  readonly ownerId?: CollisionOwnerId;
+  readonly offset?: Vec3;
+  readonly halfExtents: Vec3;
+  readonly enabled?: boolean;
+  readonly tags?: readonly string[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type CollisionVolume = {
+  readonly id: string;
+  readonly kind: CollisionVolumeKind;
+  readonly offset: Vec3;
+  readonly halfExtents: Vec3;
+  readonly enabled: boolean;
+  readonly tags: readonly string[];
+  readonly ownerId?: CollisionOwnerId;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type ResolvedCollisionVolume = CollisionVolume & {
+  readonly center: Vec3;
+  readonly facing: CombatFacing;
+  readonly bounds: Bounds;
+};
+
+export type CollisionPenetration = {
+  readonly normal: Vec3;
+  readonly depth: number;
+  readonly axis: 0 | 1 | 2;
+  readonly overlap: Vec3;
+};
+
+export function collisionVolume(kind: CollisionVolumeKind, descriptor: CollisionVolumeDescriptor): CollisionVolume {
+  validateHalfExtents(descriptor.halfExtents, `${kind} halfExtents`);
+  const volume = {
+    id: descriptor.id ?? kind,
+    kind,
+    offset: cloneVec3(descriptor.offset ?? [0, 0, 0]),
+    halfExtents: cloneVec3(descriptor.halfExtents),
+    enabled: descriptor.enabled ?? true,
+    tags: [...(descriptor.tags ?? [])],
+    ...(descriptor.ownerId === undefined ? {} : { ownerId: descriptor.ownerId }),
+    ...(descriptor.metadata === undefined ? {} : { metadata: { ...descriptor.metadata } })
+  };
+  validateFiniteVec3(volume.offset, `${kind} offset`);
+  return volume;
+}
+
+export function hitbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
+  return collisionVolume("hitbox", descriptor);
+}
+
+export function hurtbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
+  return collisionVolume("hurtbox", descriptor);
+}
+
+export function pushbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
+  return collisionVolume("pushbox", descriptor);
+}
+
+export function guardbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
+  return collisionVolume("guardbox", descriptor);
+}
+
+export const createHitbox = hitbox;
+export const createHurtbox = hurtbox;
+export const createPushbox = pushbox;
+export const createGuardbox = guardbox;
+export const createGuardBox = guardbox;
+
+export function cloneCollisionVolume(volume: CollisionVolume): CollisionVolume {
+  return {
+    id: volume.id,
+    kind: volume.kind,
+    offset: cloneVec3(volume.offset),
+    halfExtents: cloneVec3(volume.halfExtents),
+    enabled: volume.enabled,
+    tags: [...volume.tags],
+    ...(volume.ownerId === undefined ? {} : { ownerId: volume.ownerId }),
+    ...(volume.metadata === undefined ? {} : { metadata: { ...volume.metadata } })
+  };
+}
+
+export function withVolumeOwner(volume: CollisionVolume, ownerId: CollisionOwnerId): CollisionVolume {
+  return {
+    ...cloneCollisionVolume(volume),
+    ownerId
+  };
+}
+
+export function resolveCollisionVolume(volume: CollisionVolume, ownerPosition: Vec3, facing: CombatFacing = 1): ResolvedCollisionVolume {
+  validateFiniteVec3(ownerPosition, "volume owner position");
+  const resolvedFacing = normalizeFacing(facing);
+  const center: Vec3 = [
+    ownerPosition[0] + volume.offset[0] * resolvedFacing,
+    ownerPosition[1] + volume.offset[1],
+    ownerPosition[2] + volume.offset[2]
+  ];
+  return {
+    ...cloneCollisionVolume(volume),
+    center,
+    facing: resolvedFacing,
+    bounds: aabbFromCenter(center, volume.halfExtents)
+  };
+}
+
+export function aabbFromCenter(center: Vec3, halfExtents: Vec3): Bounds {
+  validateFiniteVec3(center, "aabb center");
+  validateHalfExtents(halfExtents, "aabb halfExtents");
+  return {
+    min: [center[0] - halfExtents[0], center[1] - halfExtents[1], center[2] - halfExtents[2]],
+    max: [center[0] + halfExtents[0], center[1] + halfExtents[1], center[2] + halfExtents[2]]
+  };
+}
+
+export function boundsCenter(bounds: Bounds): Vec3 {
+  validateBounds(bounds, "bounds");
+  return [
+    (bounds.min[0] + bounds.max[0]) * 0.5,
+    (bounds.min[1] + bounds.max[1]) * 0.5,
+    (bounds.min[2] + bounds.max[2]) * 0.5
+  ];
+}
+
+export function boundsHalfExtents(bounds: Bounds): Vec3 {
+  validateBounds(bounds, "bounds");
+  return [
+    (bounds.max[0] - bounds.min[0]) * 0.5,
+    (bounds.max[1] - bounds.min[1]) * 0.5,
+    (bounds.max[2] - bounds.min[2]) * 0.5
+  ];
+}
+
+export function overlapsAabb(a: Bounds, b: Bounds): boolean {
+  validateBounds(a, "a bounds");
+  validateBounds(b, "b bounds");
+  return (
+    a.min[0] < b.max[0] &&
+    a.max[0] > b.min[0] &&
+    a.min[1] < b.max[1] &&
+    a.max[1] > b.min[1] &&
+    a.min[2] < b.max[2] &&
+    a.max[2] > b.min[2]
+  );
+}
+
+export function overlapsVolume(a: ResolvedCollisionVolume, b: ResolvedCollisionVolume): boolean {
+  if (!a.enabled || !b.enabled) {
+    return false;
+  }
+  return overlapsAabb(a.bounds, b.bounds);
+}
+
+export function aabbPenetration(a: Bounds, b: Bounds): CollisionPenetration | null {
+  if (!overlapsAabb(a, b)) {
+    return null;
+  }
+  const overlap: Vec3 = [
+    Math.min(a.max[0] - b.min[0], b.max[0] - a.min[0]),
+    Math.min(a.max[1] - b.min[1], b.max[1] - a.min[1]),
+    Math.min(a.max[2] - b.min[2], b.max[2] - a.min[2])
+  ];
+  let axis: 0 | 1 | 2 = 0;
+  if (overlap[1] < overlap[axis]) {
+    axis = 1;
+  }
+  if (overlap[2] < overlap[axis]) {
+    axis = 2;
+  }
+  const centerA = boundsCenter(a);
+  const centerB = boundsCenter(b);
+  const normal: [number, number, number] = [0, 0, 0];
+  normal[axis] = centerA[axis] <= centerB[axis] ? -1 : 1;
+  return {
+    normal,
+    depth: overlap[axis],
+    axis,
+    overlap
+  };
+}
+
+export function volumePairKey(a: CollisionVolume | ResolvedCollisionVolume, b: CollisionVolume | ResolvedCollisionVolume): string {
+  const keyA = volumeKey(a);
+  const keyB = volumeKey(b);
+  return keyA < keyB ? `${keyA}:${keyB}` : `${keyB}:${keyA}`;
+}
+
+export function normalizeFacing(value: number): CombatFacing {
+  return value < 0 ? -1 : 1;
+}
+
+export function validateBounds(bounds: Bounds, name: string): void {
+  validateFiniteVec3(bounds.min, `${name} min`);
+  validateFiniteVec3(bounds.max, `${name} max`);
+  if (bounds.min[0] > bounds.max[0] || bounds.min[1] > bounds.max[1] || bounds.min[2] > bounds.max[2]) {
+    throw new Error(`${name} min values must be less than or equal to max values.`);
+  }
+}
+
+function validateHalfExtents(value: Vec3, name: string): void {
+  validateFiniteVec3(value, name);
+  if (value[0] <= 0 || value[1] <= 0 || value[2] <= 0) {
+    throw new Error(`${name} must contain finite positive values.`);
+  }
+}
+
+function volumeKey(volume: CollisionVolume | ResolvedCollisionVolume): string {
+  const owner = volume.ownerId === undefined ? "none" : String(volume.ownerId);
+  return `${owner}/${volume.kind}/${volume.id}`;
+}

package/src/Constraint.ts

@@ -0,0 +1,120 @@
+import { addVec3, dotVec3, normalizeVec3, scaleVec3, subVec3, validateFiniteVec3, type Vec3 } from "./Shape.js";
+import type { RigidBody } from "./RigidBody.js";
+
+export type ConstraintType = "fixed" | "hinge" | "slider" | "spring";
+
+export type ConstraintDescriptor = {
+  readonly type: ConstraintType;
+  readonly bodyA: RigidBody;
+  readonly bodyB: RigidBody;
+  readonly localAnchorA?: Vec3;
+  readonly localAnchorB?: Vec3;
+  readonly restLength?: number;
+  readonly stiffness?: number;
+  readonly axis?: Vec3;
+};
+
+export class Constraint {
+  readonly type: ConstraintType;
+  readonly bodyA: RigidBody;
+  readonly bodyB: RigidBody;
+  readonly localAnchorA: Vec3;
+  readonly localAnchorB: Vec3;
+  readonly restOffset: Vec3;
+  readonly restLength: number;
+  readonly stiffness: number;
+  readonly axis: Vec3;
+
+  constructor(descriptor: ConstraintDescriptor) {
+    if (descriptor.bodyA.id === descriptor.bodyB.id) {
+      throw new Error("Constraint requires two different bodies.");
+    }
+    this.localAnchorA = descriptor.localAnchorA ?? [0, 0, 0];
+    this.localAnchorB = descriptor.localAnchorB ?? [0, 0, 0];
+    validateFiniteVec3(this.localAnchorA, "constraint localAnchorA");
+    validateFiniteVec3(this.localAnchorB, "constraint localAnchorB");
+    this.axis = normalizeVec3(descriptor.axis ?? [1, 0, 0]);
+    this.type = descriptor.type;
+    this.bodyA = descriptor.bodyA;
+    this.bodyB = descriptor.bodyB;
+    const anchorA = this.anchorAWorld();
+    const anchorB = this.anchorBWorld();
+    this.restOffset = subVec3(anchorB, anchorA);
+    this.restLength = descriptor.restLength ?? Math.hypot(this.restOffset[0], this.restOffset[1], this.restOffset[2]);
+    this.stiffness = descriptor.stiffness ?? 1;
+    if (!Number.isFinite(this.restLength) || this.restLength < 0) {
+      throw new Error("Constraint restLength must be finite and non-negative.");
+    }
+    if (!Number.isFinite(this.stiffness) || this.stiffness < 0 || this.stiffness > 1) {
+      throw new Error("Constraint stiffness must be in the [0, 1] range.");
+    }
+  }
+
+  solve(): void {
+    if (this.stiffness === 0) {
+      return;
+    }
+    if (this.type === "fixed") {
+      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
+      this.applyError(subVec3(currentOffset, this.restOffset));
+      this.applyVelocityError(subVec3(this.bodyB.velocity, this.bodyA.velocity));
+    } else if (this.type === "hinge") {
+      this.applyError(subVec3(this.anchorBWorld(), this.anchorAWorld()));
+      this.applyVelocityError(subVec3(this.bodyB.velocity, this.bodyA.velocity));
+    } else if (this.type === "slider") {
+      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
+      const projected = scaleVec3(this.axis, dotVec3(currentOffset, this.axis));
+      this.applyError(subVec3(currentOffset, projected));
+      const relativeVelocity = subVec3(this.bodyB.velocity, this.bodyA.velocity);
+      const projectedVelocity = scaleVec3(this.axis, dotVec3(relativeVelocity, this.axis));
+      this.applyVelocityError(subVec3(relativeVelocity, projectedVelocity));
+    } else if (this.type === "spring") {
+      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
+      const currentLength = Math.hypot(currentOffset[0], currentOffset[1], currentOffset[2]);
+      if (currentLength <= 1e-9) {
+        return;
+      }
+      const lengthError = currentLength - this.restLength;
+      this.applyError(scaleVec3(currentOffset, lengthError / currentLength));
+      const relativeVelocity = subVec3(this.bodyB.velocity, this.bodyA.velocity);
+      const axis = scaleVec3(currentOffset, 1 / currentLength);
+      this.applyVelocityError(scaleVec3(axis, dotVec3(relativeVelocity, axis) * Math.min(1, this.stiffness)));
+    }
+  }
+
+  private anchorAWorld(): Vec3 {
+    return addVec3(this.bodyA.position, this.localAnchorA);
+  }
+
+  private anchorBWorld(): Vec3 {
+    return addVec3(this.bodyB.position, this.localAnchorB);
+  }
+
+  private applyError(error: Vec3): void {
+    const inverseMassSum = this.bodyA.inverseMass + this.bodyB.inverseMass;
+    if (inverseMassSum <= 0) {
+      return;
+    }
+    const weightedError = scaleVec3(error, this.stiffness);
+    if (this.bodyA.inverseMass > 0) {
+      this.bodyA.setPosition(addVec3(this.bodyA.position, scaleVec3(weightedError, this.bodyA.inverseMass / inverseMassSum)));
+    }
+    if (this.bodyB.inverseMass > 0) {
+      this.bodyB.setPosition(subVec3(this.bodyB.position, scaleVec3(weightedError, this.bodyB.inverseMass / inverseMassSum)));
+    }
+  }
+
+  private applyVelocityError(errorVelocity: Vec3): void {
+    const inverseMassSum = this.bodyA.inverseMass + this.bodyB.inverseMass;
+    if (inverseMassSum <= 0) {
+      return;
+    }
+    const correctionImpulse = scaleVec3(errorVelocity, -this.stiffness / inverseMassSum);
+    if (this.bodyA.inverseMass > 0) {
+      this.bodyA.applyImpulse(scaleVec3(correctionImpulse, -1));
+    }
+    if (this.bodyB.inverseMass > 0) {
+      this.bodyB.applyImpulse(correctionImpulse);
+    }
+  }
+}

package/src/Constraints.ts

@@ -0,0 +1 @@
+export * from "./Constraint.js";

package/src/Crowd.ts

@@ -0,0 +1,283 @@
+import { arriveSteering, type SteeringPoint, type SteeringVector } from "./Steering";
+
+export type CrowdFormationType = "line" | "wedge" | "column" | "circle";
+
+export interface CrowdAgentOptions {
+  readonly id: string;
+  readonly position: SteeringPoint;
+  readonly velocity?: SteeringVector;
+  readonly radius?: number;
+  readonly maxSpeed?: number;
+  readonly priority?: number;
+}
+
+export interface CrowdSimulationOptions {
+  readonly neighborRadius?: number;
+  readonly maxNeighbors?: number;
+  readonly separationWeight?: number;
+  readonly alignmentWeight?: number;
+  readonly cohesionWeight?: number;
+  readonly formationWeight?: number;
+  readonly maxForce?: number;
+}
+
+export interface CrowdFormationOptions {
+  readonly type: CrowdFormationType;
+  readonly center: SteeringPoint;
+  readonly forward?: SteeringVector;
+  readonly spacing?: number;
+}
+
+export interface CrowdAgentSnapshot {
+  readonly id: string;
+  readonly position: SteeringPoint;
+  readonly velocity: SteeringVector;
+  readonly speed: number;
+  readonly neighborCount: number;
+  readonly formationSlot: SteeringPoint;
+}
+
+export interface CrowdSimulationSnapshot {
+  readonly agentCount: number;
+  readonly neighborPairs: number;
+  readonly averageNeighbors: number;
+  readonly averageSpeed: number;
+  readonly maxSpeed: number;
+  readonly formationType: CrowdFormationType | "none";
+  readonly center: SteeringPoint;
+  readonly agents: readonly CrowdAgentSnapshot[];
+}
+
+type CrowdAgentState = {
+  readonly id: string;
+  position: SteeringPoint;
+  velocity: SteeringVector;
+  readonly radius: number;
+  readonly maxSpeed: number;
+  readonly priority: number;
+};
+
+export class CrowdSimulation {
+  private readonly agents: CrowdAgentState[] = [];
+  private readonly neighborRadius: number;
+  private readonly maxNeighbors: number;
+  private readonly separationWeight: number;
+  private readonly alignmentWeight: number;
+  private readonly cohesionWeight: number;
+  private readonly formationWeight: number;
+  private readonly maxForce: number;
+  private formation: CrowdFormationOptions | undefined;
+  private lastNeighbors = new Map<string, readonly CrowdAgentState[]>();
+  private lastSlots = new Map<string, SteeringPoint>();
+
+  constructor(options: CrowdSimulationOptions = {}) {
+    this.neighborRadius = positive(options.neighborRadius ?? 0.55, "neighborRadius");
+    this.maxNeighbors = Math.max(1, Math.floor(options.maxNeighbors ?? 6));
+    this.separationWeight = nonNegative(options.separationWeight ?? 1.8, "separationWeight");
+    this.alignmentWeight = nonNegative(options.alignmentWeight ?? 0.55, "alignmentWeight");
+    this.cohesionWeight = nonNegative(options.cohesionWeight ?? 0.42, "cohesionWeight");
+    this.formationWeight = nonNegative(options.formationWeight ?? 0.85, "formationWeight");
+    this.maxForce = positive(options.maxForce ?? 1.2, "maxForce");
+  }
+
+  addAgent(options: CrowdAgentOptions): void {
+    if (this.agents.some((agent) => agent.id === options.id)) throw new Error(`Crowd agent already exists: ${options.id}`);
+    this.agents.push({
+      id: options.id,
+      position: options.position,
+      velocity: options.velocity ?? [0, 0],
+      radius: positive(options.radius ?? 0.1, "radius"),
+      maxSpeed: positive(options.maxSpeed ?? 0.65, "maxSpeed"),
+      priority: nonNegative(options.priority ?? 50, "priority")
+    });
+  }
+
+  removeAgent(id: string): boolean {
+    const index = this.agents.findIndex((agent) => agent.id === id);
+    if (index < 0) return false;
+    this.agents.splice(index, 1);
+    this.lastNeighbors.delete(id);
+    this.lastSlots.delete(id);
+    return true;
+  }
+
+  setFormation(options: CrowdFormationOptions | undefined): void {
+    this.formation = options;
+  }
+
+  update(deltaSeconds: number): CrowdSimulationSnapshot {
+    const dt = Math.max(0, deltaSeconds);
+    const neighborsById = new Map(this.agents.map((agent) => [agent.id, this.neighborsFor(agent)]));
+    const slots = formationSlots(this.agents.length, this.formation);
+    this.lastNeighbors = neighborsById;
+    this.lastSlots = new Map(this.agents.map((agent, index) => [agent.id, slots[index] ?? agent.position]));
+
+    for (let index = 0; index < this.agents.length; index += 1) {
+      const agent = this.agents[index]!;
+      const neighbors = neighborsById.get(agent.id) ?? [];
+      const slot = slots[index] ?? agent.position;
+      const force = clampMagnitude(addMany([
+        scale(separationForce(agent, neighbors), this.separationWeight),
+        scale(alignmentForce(agent, neighbors), this.alignmentWeight),
+        scale(cohesionForce(agent, neighbors), this.cohesionWeight),
+        scale(formationForce(agent, slot), this.formationWeight)
+      ]), this.maxForce);
+      const priorityDamping = Math.max(0.35, Math.min(1, agent.priority / 100));
+      const velocity = clampMagnitude([
+        agent.velocity[0] + force[0] * dt * priorityDamping,
+        agent.velocity[1] + force[1] * dt * priorityDamping
+      ], agent.maxSpeed);
+      agent.velocity = velocity;
+      agent.position = [
+        round3(agent.position[0] + velocity[0] * dt),
+        round3(agent.position[1] + velocity[1] * dt)
+      ];
+    }
+
+    return this.snapshot();
+  }
+
+  snapshot(): CrowdSimulationSnapshot {
+    const agentSnapshots = this.agents.map((agent) => {
+      const neighbors = this.lastNeighbors.get(agent.id) ?? [];
+      return {
+        id: agent.id,
+        position: [round3(agent.position[0]), round3(agent.position[1])] as const,
+        velocity: [round3(agent.velocity[0]), round3(agent.velocity[1])] as const,
+        speed: round3(length(agent.velocity)),
+        neighborCount: neighbors.length,
+        formationSlot: this.lastSlots.get(agent.id) ?? agent.position
+      };
+    });
+    const neighborPairs = agentSnapshots.reduce((sum, agent) => sum + agent.neighborCount, 0) / 2;
+    const averageSpeed = agentSnapshots.length > 0
+      ? agentSnapshots.reduce((sum, agent) => sum + agent.speed, 0) / agentSnapshots.length
+      : 0;
+    return {
+      agentCount: agentSnapshots.length,
+      neighborPairs: round3(neighborPairs),
+      averageNeighbors: agentSnapshots.length > 0 ? round3((neighborPairs * 2) / agentSnapshots.length) : 0,
+      averageSpeed: round3(averageSpeed),
+      maxSpeed: round3(Math.max(0, ...agentSnapshots.map((agent) => agent.speed))),
+      formationType: this.formation?.type ?? "none",
+      center: centerOf(agentSnapshots.map((agent) => agent.position)),
+      agents: agentSnapshots
+    };
+  }
+
+  private neighborsFor(agent: CrowdAgentState): readonly CrowdAgentState[] {
+    return this.agents
+      .filter((candidate) => candidate !== agent && distance(agent.position, candidate.position) <= this.neighborRadius)
+      .sort((left, right) => distance(agent.position, left.position) - distance(agent.position, right.position) || left.id.localeCompare(right.id))
+      .slice(0, this.maxNeighbors);
+  }
+}
+
+function separationForce(agent: CrowdAgentState, neighbors: readonly CrowdAgentState[]): SteeringVector {
+  const contributions = neighbors.map((neighbor) => {
+    const away = subtract(agent.position, neighbor.position);
+    const gap = Math.max(0.001, length(away) - agent.radius - neighbor.radius);
+    return scale(normalize(away), 1 / gap);
+  });
+  return normalize(addMany(contributions));
+}
+
+function alignmentForce(agent: CrowdAgentState, neighbors: readonly CrowdAgentState[]): SteeringVector {
+  if (neighbors.length === 0) return [0, 0];
+  const average = scale(addMany(neighbors.map((neighbor) => neighbor.velocity)), 1 / neighbors.length);
+  return subtract(clampMagnitude(average, agent.maxSpeed), agent.velocity);
+}
+
+function cohesionForce(agent: CrowdAgentState, neighbors: readonly CrowdAgentState[]): SteeringVector {
+  if (neighbors.length === 0) return [0, 0];
+  const center = centerOf(neighbors.map((neighbor) => neighbor.position));
+  return arriveSteering({ position: agent.position, velocity: agent.velocity, target: center, maxSpeed: agent.maxSpeed, slowingRadius: 0.45 }).force;
+}
+
+function formationForce(agent: CrowdAgentState, slot: SteeringPoint): SteeringVector {
+  return arriveSteering({ position: agent.position, velocity: agent.velocity, target: slot, maxSpeed: agent.maxSpeed, slowingRadius: 0.35, tolerance: 0.025 }).force;
+}
+
+function formationSlots(count: number, formation: CrowdFormationOptions | undefined): readonly SteeringPoint[] {
+  if (!formation) return [];
+  const spacing = formation.spacing ?? 0.24;
+  const forward = normalize(formation.forward ?? [1, 0]);
+  const right: SteeringVector = [forward[1], -forward[0]];
+  return Array.from({ length: count }, (_, index) => {
+    switch (formation.type) {
+      case "line":
+        return offset(formation.center, right, (index - (count - 1) / 2) * spacing);
+      case "column":
+        return offset(formation.center, forward, -index * spacing);
+      case "circle": {
+        const angle = (Math.PI * 2 * index) / Math.max(1, count);
+        return [round3(formation.center[0] + Math.cos(angle) * spacing), round3(formation.center[1] + Math.sin(angle) * spacing)];
+      }
+      case "wedge": {
+        if (index === 0) return formation.center;
+        const side = index % 2 === 0 ? 1 : -1;
+        const row = Math.ceil(index / 2);
+        return add(offset(formation.center, forward, -row * spacing), scale(right, side * row * spacing));
+      }
+    }
+  });
+}
+
+function offset(origin: SteeringPoint, direction: SteeringVector, amount: number): SteeringPoint {
+  return [round3(origin[0] + direction[0] * amount), round3(origin[1] + direction[1] * amount)];
+}
+
+function add(left: SteeringPoint, right: SteeringVector): SteeringPoint {
+  return [round3(left[0] + right[0]), round3(left[1] + right[1])];
+}
+
+function subtract(left: SteeringPoint, right: SteeringPoint): SteeringVector {
+  return [left[0] - right[0], left[1] - right[1]];
+}
+
+function scale(value: SteeringVector, scalar: number): SteeringVector {
+  return [value[0] * scalar, value[1] * scalar];
+}
+
+function addMany(values: readonly SteeringVector[]): SteeringVector {
+  return values.reduce<SteeringVector>((sum, value) => [sum[0] + value[0], sum[1] + value[1]], [0, 0]);
+}
+
+function distance(left: SteeringPoint, right: SteeringPoint): number {
+  return length(subtract(left, right));
+}
+
+function length(value: SteeringVector): number {
+  return Math.hypot(value[0], value[1]);
+}
+
+function normalize(value: SteeringVector): SteeringVector {
+  const magnitude = length(value);
+  return magnitude === 0 ? [0, 0] : [value[0] / magnitude, value[1] / magnitude];
+}
+
+function clampMagnitude(value: SteeringVector, maxMagnitude: number): SteeringVector {
+  const magnitude = length(value);
+  if (magnitude === 0 || magnitude <= maxMagnitude) return value;
+  return scale(value, maxMagnitude / magnitude);
+}
+
+function centerOf(points: readonly SteeringPoint[]): SteeringPoint {
+  if (points.length === 0) return [0, 0];
+  const sum = points.reduce<SteeringVector>((total, point) => [total[0] + point[0], total[1] + point[1]], [0, 0]);
+  return [round3(sum[0] / points.length), round3(sum[1] / points.length)];
+}
+
+function positive(value: number, name: string): number {
+  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`Crowd ${name} must be a finite positive number.`);
+  return value;
+}
+
+function nonNegative(value: number, name: string): number {
+  if (!Number.isFinite(value) || value < 0) throw new RangeError(`Crowd ${name} must be a finite non-negative number.`);
+  return value;
+}
+
+function round3(value: number): number {
+  return Number(value.toFixed(3));
+}

package/src/ECSPhysicsBridge.ts

@@ -0,0 +1,53 @@
+import type { PhysicsWorld } from "./PhysicsWorld.js";
+import { interpolatePosition } from "./ScenePhysicsBridge.js";
+import type { Vec3 } from "./Shape.js";
+
+export type ECSTransformLike = {
+  position: [number, number, number];
+};
+
+export type ECSPhysicsBinding = {
+  readonly bodyId: number;
+  readonly transform: ECSTransformLike;
+  readonly mode?: "dynamic" | "kinematic";
+};
+
+export class ECSPhysicsBridge {
+  private readonly bindings = new Map<number, ECSPhysicsBinding>();
+
+  bind(binding: ECSPhysicsBinding): void {
+    if (this.bindings.has(binding.bodyId)) {
+      throw new Error(`Body ${binding.bodyId} is already bound to an ECS transform.`);
+    }
+    this.bindings.set(binding.bodyId, binding);
+  }
+
+  unbind(bodyId: number): void {
+    this.bindings.delete(bodyId);
+  }
+
+  pushKinematic(world: Pick<PhysicsWorld, "getBody">): void {
+    for (const binding of this.bindings.values()) {
+      if (binding.mode !== "kinematic") {
+        continue;
+      }
+      world.getBody(binding.bodyId)?.setPosition(binding.transform.position);
+    }
+  }
+
+  pullDynamic(world: Pick<PhysicsWorld, "getBody">, alpha = 1): void {
+    for (const binding of this.bindings.values()) {
+      if (binding.mode === "kinematic") {
+        continue;
+      }
+      const body = world.getBody(binding.bodyId);
+      if (!body) {
+        continue;
+      }
+      const interpolated = interpolatePosition(body.previousPosition, body.position, alpha);
+      binding.transform.position[0] = interpolated[0];
+      binding.transform.position[1] = interpolated[1];
+      binding.transform.position[2] = interpolated[2];
+    }
+  }
+}