@driftengine/physics 4.5.0 → 4.6.1

package/README.md

@@ -5,7 +5,7 @@ kinematic sweep that resolves a moving body against a static world one axis at a
 
 **It imports no other engine package.** Together with `@driftengine/entities` that makes a
 deterministic simulation you can run with no renderer in its module graph — in Node, in a worker,
-or on a server, which is what an authoritative host needs. **45.2 KB gzipped** standalone, measured
+or on a server, which is what an authoritative host needs. **45.4 KB gzipped** standalone, measured
 by `scripts/size-gate.test.mjs` against `scripts/fixtures/size/physics-only.ts`.
 
 **`@driftengine/core` re-exports every name here**, so reaching for collision through the core

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export type { Manifold, ShapePose } from './manifold.ts';
 export { MAX_CONTACTS, collideShapes, createManifold } from './manifold.ts';
 export type { Parallelism, WorldOptions } from './world.ts';
 export { PhysicsWorld } from './world.ts';
+export { StaticRegions } from './staticRegions.ts';
 export { ContactConstraints, LINEAR_SLOP, MAX_BIAS_VELOCITY, RESTITUTION_THRESHOLD, applyRestitution, isDynamicBody, prepareContact, solveContacts, warmStart, } from './solver.ts';
 export { IslandSet } from './island.ts';
 export type { FrictionModel } from './solver.ts';

package/dist/index.js

@@ -6,6 +6,7 @@ export { DynamicTree } from './tree.js';
 export { MAX_BODIES, PairSet, layersInteract, pairA, pairB, pairKey } from './pairs.js';
 export { MAX_CONTACTS, collideShapes, createManifold } from './manifold.js';
 export { PhysicsWorld } from './world.js';
+export { StaticRegions } from './staticRegions.js';
 export { ContactConstraints, LINEAR_SLOP, MAX_BIAS_VELOCITY, RESTITUTION_THRESHOLD, applyRestitution, isDynamicBody, prepareContact, solveContacts, warmStart, } from './solver.js';
 export { IslandSet } from './island.js';
 export { DisjointExecutor, SerialExecutor, ShuffledExecutor } from './executor.js';

package/dist/manifold.js

@@ -400,6 +400,21 @@ function closestOnPolytope(shape, world, planes, faces, px, py, pz) {
             bestPlane = f;
         }
     }
+    /*
+     * **One face is a surface, not a solid: behind it is inside only where the point projects onto
+     * it.** A mesh's triangle arrives here as a polytope of one face, and "behind every face" is then
+     * the whole half-space behind the triangle's plane — so a capsule standing on a kerb, its axis a
+     * few centimetres past the kerb's front face, was "inside" that face's triangles half a metre above
+     * them, pushed back along the face normal and stopped dead on top of the kerb. Where the point
+     * projects outside the triangle the closest point is on its boundary, which the outside path finds
+     * and the mesh's one-sided rule then sorts. Behind the triangle and over it is still inside, which
+     * is what holds a sphere that has dipped a little through a floor.
+     */
+    if (inside &&
+        faces === 1 &&
+        !projectsOntoFace(shape, world, planes, px, py, pz, bestPlane, bestPlaneDist)) {
+        inside = false;
+    }
     if (inside) {
         const nx = planes[bestPlane * 4] ?? 0;
         const ny = planes[bestPlane * 4 + 1] ?? 0;
@@ -439,6 +454,32 @@ function closestOnPolytope(shape, world, planes, faces, px, py, pz) {
     CLOSEST[6] = Math.sqrt(bestD2);
 }
 const TRI = new Float64Array(3);
+/**
+ * Whether `p`, `distance` from face `face`'s plane along its normal, projects inside that face: the
+ * closest point on the face to its projection is the projection itself.
+ */
+function projectsOntoFace(shape, world, planes, px, py, pz, face, distance) {
+    const n = faceVertices(shape, face, loop);
+    /* The world plane the distance was measured against, so a rotated mesh projects correctly. */
+    const nx = planes[face * 4] ?? 0;
+    const ny = planes[face * 4 + 1] ?? 0;
+    const nz = planes[face * 4 + 2] ?? 0;
+    const qx = px - nx * distance;
+    const qy = py - ny * distance;
+    const qz = pz - nz * distance;
+    const a = (loop[0] ?? 0) * 3;
+    for (let i = 1; i + 1 < n; i++) {
+        const b = (loop[i] ?? 0) * 3;
+        const c = (loop[i + 1] ?? 0) * 3;
+        closestOnTriangle(qx, qy, qz, world[a] ?? 0, world[a + 1] ?? 0, world[a + 2] ?? 0, world[b] ?? 0, world[b + 1] ?? 0, world[b + 2] ?? 0, world[c] ?? 0, world[c + 1] ?? 0, world[c + 2] ?? 0);
+        const dx = qx - TRI[0];
+        const dy = qy - TRI[1];
+        const dz = qz - TRI[2];
+        if (dx * dx + dy * dy + dz * dz < 1e-12)
+            return true;
+    }
+    return false;
+}
 /** Closest point on a triangle to `p`, by the standard barycentric region test. */
 function closestOnTriangle(px, py, pz, ax, ay, az, bx, by, bz, cx, cy, cz) {
     const abx = bx - ax;

package/dist/meshContact.js

@@ -1,6 +1,7 @@
 import { fieldCandidates, fieldConvexEdges, fieldCorners, fieldPlane } from './heightfieldShape.js';
 import { collideShapes, createManifold } from './manifold.js';
 import { shapeBounds } from './shape.js';
+import { faceCount } from './faces.js';
 /**
  * Contacts between a convex shape and a static triangle mesh.
  *
@@ -93,6 +94,8 @@ export function collideMesh(shapeA, poseA, shapeB, poseB, margin, out) {
     /* Two meshes never touch: both are static, so nothing would move if they did. */
     if (isMesh(other))
         return 0;
+    /* A sphere or capsule's contacts lie on the triangle, not on it; see `filterInteriorEdge`. */
+    const roundRadius = faceCount(other) === 0 ? other.radius : -1;
     /*
      * The moving shape's bounds, carried into the mesh's own frame — because the tree is in that
      * frame and rebuilding it per frame is exactly what static means it never has to do. The box is
@@ -126,8 +129,8 @@ export function collideMesh(shapeA, poseA, shapeB, poseB, margin, out) {
         /* One-sided: a normal pointing into the back of the triangle is a body already through it. */
         if (away <= 0)
             continue;
-        if (away < FACE_DOT)
-            filterInteriorEdge(mesh, triangle, meshPose, sign);
+        if (away < FACE_DOT && !filterInteriorEdge(mesh, triangle, meshPose, sign, roundRadius))
+            continue;
         const target = out[count];
         if (target === undefined)
             break;
@@ -211,8 +214,18 @@ function worldCorner(mesh, triangle, corner, pose, out, at) {
  * The separations are recomputed from the face plane rather than scaled, because the direction has
  * changed and a scaled depth would hold a body off the floor by the cosine of an angle nobody
  * chose.
+ *
+ * **A sphere or capsule is measured from its own centre, not from the contact point.** Its manifold's
+ * points lie on the triangle, so their distance from the face plane is zero whatever the real gap —
+ * and a capsule standing on a kerb, just past the top edge of the kerb's front face, read as touching
+ * that face with the face's normal, which faces backwards along its walk: a wall it had already
+ * stepped over, stopping it dead on top. So the centre that produced each contact is rebuilt from
+ * the edge normal before that normal is replaced, and the separation is its plane distance less the
+ * radius. **A centre behind the face plane drops the contact**, returning false: the one-sided rule,
+ * applied to the geometry after the swap as it is to the geometry before it. A polytope's points lie
+ * on the body, so their plane distance is already the separation, as before.
  */
-function filterInteriorEdge(mesh, triangle, meshPose, sign) {
+function filterInteriorEdge(mesh, triangle, meshPose, sign, roundRadius) {
     let deepest = 0;
     for (let i = 1; i < scratch.count; i++) {
         if ((scratch.separations[i] ?? 0) < (scratch.separations[deepest] ?? 0))
@@ -234,12 +247,32 @@ function filterInteriorEdge(mesh, triangle, meshPose, sign) {
     }
     /* A convex edge is a real one: the ridge is there and the body should feel it. */
     if ((convexEdgesOf(mesh, triangle) >> nearest) & 1)
-        return;
+        return true;
+    worldPlaneAnchor(mesh, triangle, meshPose, ANCHOR);
+    const plane = FACE[0] * ANCHOR[0] + FACE[1] * ANCHOR[1] + FACE[2] * ANCHOR[2];
+    if (roundRadius >= 0) {
+        /* Mesh-to-body along the old normal, out to the centre: the point plus that much of the gap. */
+        const ux = sign * scratch.nx;
+        const uy = sign * scratch.ny;
+        const uz = sign * scratch.nz;
+        for (let i = 0; i < scratch.count; i++) {
+            const reach = (scratch.separations[i] ?? 0) + roundRadius;
+            const cx = (scratch.points[i * 3] ?? 0) + ux * reach;
+            const cy = (scratch.points[i * 3 + 1] ?? 0) + uy * reach;
+            const cz = (scratch.points[i * 3 + 2] ?? 0) + uz * reach;
+            const height = cx * FACE[0] + cy * FACE[1] + cz * FACE[2] - plane;
+            if (height < 0)
+                return false;
+            scratch.separations[i] = height - roundRadius;
+        }
+        scratch.nx = sign * FACE[0];
+        scratch.ny = sign * FACE[1];
+        scratch.nz = sign * FACE[2];
+        return true;
+    }
     scratch.nx = sign * FACE[0];
     scratch.ny = sign * FACE[1];
     scratch.nz = sign * FACE[2];
-    worldPlaneAnchor(mesh, triangle, meshPose, ANCHOR);
-    const plane = FACE[0] * ANCHOR[0] + FACE[1] * ANCHOR[1] + FACE[2] * ANCHOR[2];
     for (let i = 0; i < scratch.count; i++) {
         scratch.separations[i] =
             (scratch.points[i * 3] ?? 0) * FACE[0] +
@@ -247,6 +280,7 @@ function filterInteriorEdge(mesh, triangle, meshPose, sign) {
                 (scratch.points[i * 3 + 2] ?? 0) * FACE[2] -
                 plane;
     }
+    return true;
 }
 const EDGE = new Float64Array(6);
 const ANCHOR = new Float64Array(3);

package/dist/staticRegions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A world's static scenery by region: one body a region, added when the region streams in and
+ * removed when it streams out, with each region's body index kept right as the world moves bodies.
+ *
+ * **One body a region, and a triangle mesh is what makes that cheap.** A city region holds hundreds
+ * of boxes and a few odd shapes; as bodies they would be tens of thousands for the city, every one
+ * an index to follow. As one static triangle mesh each — `meshShape`, which carries its own tree —
+ * the whole city is a few hundred bodies and a region comes and goes as one add and one remove.
+ *
+ * **Why the indices need following.** `PhysicsWorld.removeBody` fills the hole with its last body,
+ * so removing one region's body moves another's — possibly another region's, possibly anything
+ * else in the world. It returns the index that moved, and this uses it. **What it gives up** is any
+ * other caller's body index in the same world: a removal moves whatever was last, and only the
+ * caller that asked for it hears where it went. A world that also holds bodies somebody else tracks
+ * by index needs those removed through one place that follows them all.
+ */
+import type { BodyDesc } from './bodies.ts';
+import type { PhysicsWorld } from './world.ts';
+export declare class StaticRegions {
+    private readonly world;
+    private readonly bodyOfRegion;
+    /** The region each body index belongs to, or −1. Grows with the world. */
+    private regionOfBody;
+    constructor(world: PhysicsWorld);
+    /** How many regions are in the world. */
+    get size(): number;
+    has(region: number): boolean;
+    /** The body index a region stands as now, or −1. It changes as other regions are removed. */
+    bodyOf(region: number): number;
+    /** Add a region as one body. A region already in the world is refused rather than doubled. */
+    add(region: number, desc: BodyDesc): number;
+    /** Take a region out of the world. A region that is not there is nothing to remove. */
+    remove(region: number): void;
+}

package/dist/staticRegions.js

@@ -0,0 +1,54 @@
+export class StaticRegions {
+    world;
+    bodyOfRegion = new Map();
+    /** The region each body index belongs to, or −1. Grows with the world. */
+    regionOfBody = new Int32Array(64).fill(-1);
+    constructor(world) {
+        this.world = world;
+    }
+    /** How many regions are in the world. */
+    get size() {
+        return this.bodyOfRegion.size;
+    }
+    has(region) {
+        return this.bodyOfRegion.has(region);
+    }
+    /** The body index a region stands as now, or −1. It changes as other regions are removed. */
+    bodyOf(region) {
+        return this.bodyOfRegion.get(region) ?? -1;
+    }
+    /** Add a region as one body. A region already in the world is refused rather than doubled. */
+    add(region, desc) {
+        if (this.bodyOfRegion.has(region)) {
+            throw new Error(`StaticRegions: region ${region} is already in the world — remove it before adding it ` +
+                'again, or its scenery would collide twice');
+        }
+        const body = this.world.addBody(desc);
+        while (body >= this.regionOfBody.length) {
+            const wider = new Int32Array(this.regionOfBody.length * 2).fill(-1);
+            wider.set(this.regionOfBody);
+            this.regionOfBody = wider;
+        }
+        this.regionOfBody[body] = region;
+        this.bodyOfRegion.set(region, body);
+        return body;
+    }
+    /** Take a region out of the world. A region that is not there is nothing to remove. */
+    remove(region) {
+        const body = this.bodyOfRegion.get(region);
+        if (body === undefined)
+            return;
+        this.bodyOfRegion.delete(region);
+        const moved = this.world.removeBody(body);
+        if (moved < 0) {
+            this.regionOfBody[body] = -1;
+            return;
+        }
+        /* The body that was last now sits at `body`: whichever region owned it follows it there. */
+        const owner = this.regionOfBody[moved] ?? -1;
+        this.regionOfBody[body] = owner;
+        this.regionOfBody[moved] = -1;
+        if (owner >= 0)
+            this.bodyOfRegion.set(owner, body);
+    }
+}

package/dist/world.d.ts

@@ -220,7 +220,12 @@ export declare class PhysicsWorld implements IslandSolver {
      * quietly stop the newcomer colliding with whatever the departed was jointed to.
      */
     private followRemoval;
-    removeBody(index: number): void;
+    /**
+     * Remove a body, filling its index with the last body — whose index this returns, or −1 when the
+     * removed body was the last. **Every index past the removed one can change**, so a caller keeping
+     * body indices follows the returned one; `StaticRegions` is the worked example.
+     */
+    removeBody(index: number): number;
     /** Advance one fixed tick. */
     step(dt: number): void;
     /**

package/dist/world.js

@@ -270,6 +270,11 @@ export class PhysicsWorld {
         for (const key of kept)
             this.ignoredPairs.add(key);
     }
+    /**
+     * Remove a body, filling its index with the last body — whose index this returns, or −1 when the
+     * removed body was the last. **Every index past the removed one can change**, so a caller keeping
+     * body indices follows the returned one; `StaticRegions` is the worked example.
+     */
     removeBody(index) {
         this.tree.remove(this.leafOf[index] ?? 0);
         const moved = this.bodies.remove(index);
@@ -282,6 +287,7 @@ export class PhysicsWorld {
         this.warm.clear();
         // Every index past the removed one may have moved, so a remembered pair is a lie.
         this.events.clear();
+        return moved;
     }
     /** Advance one fixed tick. */
     step(dt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/physics",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "description": "Collision shapes, spatial queries and swept kinematic collision",
   "license": "Apache-2.0",
   "type": "module",

package/src/index.ts

@@ -35,6 +35,7 @@ export type { Manifold, ShapePose } from './manifold.ts';
 export { MAX_CONTACTS, collideShapes, createManifold } from './manifold.ts';
 export type { Parallelism, WorldOptions } from './world.ts';
 export { PhysicsWorld } from './world.ts';
+export { StaticRegions } from './staticRegions.ts';
 export {
   ContactConstraints,
   LINEAR_SLOP,

package/src/manifold.ts

@@ -542,6 +542,23 @@ function closestOnPolytope(
       bestPlane = f;
     }
   }
+  /*
+   * **One face is a surface, not a solid: behind it is inside only where the point projects onto
+   * it.** A mesh's triangle arrives here as a polytope of one face, and "behind every face" is then
+   * the whole half-space behind the triangle's plane — so a capsule standing on a kerb, its axis a
+   * few centimetres past the kerb's front face, was "inside" that face's triangles half a metre above
+   * them, pushed back along the face normal and stopped dead on top of the kerb. Where the point
+   * projects outside the triangle the closest point is on its boundary, which the outside path finds
+   * and the mesh's one-sided rule then sorts. Behind the triangle and over it is still inside, which
+   * is what holds a sphere that has dipped a little through a floor.
+   */
+  if (
+    inside &&
+    faces === 1 &&
+    !projectsOntoFace(shape, world, planes, px, py, pz, bestPlane, bestPlaneDist)
+  ) {
+    inside = false;
+  }
   if (inside) {
     const nx = planes[bestPlane * 4] ?? 0;
     const ny = planes[bestPlane * 4 + 1] ?? 0;
@@ -597,6 +614,54 @@ function closestOnPolytope(
 
 const TRI = new Float64Array(3);
 
+/**
+ * Whether `p`, `distance` from face `face`'s plane along its normal, projects inside that face: the
+ * closest point on the face to its projection is the projection itself.
+ */
+function projectsOntoFace(
+  shape: ConvexShape,
+  world: Float32Array,
+  planes: Float32Array,
+  px: number,
+  py: number,
+  pz: number,
+  face: number,
+  distance: number,
+): boolean {
+  const n = faceVertices(shape, face, loop);
+  /* The world plane the distance was measured against, so a rotated mesh projects correctly. */
+  const nx = planes[face * 4] ?? 0;
+  const ny = planes[face * 4 + 1] ?? 0;
+  const nz = planes[face * 4 + 2] ?? 0;
+  const qx = px - nx * distance;
+  const qy = py - ny * distance;
+  const qz = pz - nz * distance;
+  const a = (loop[0] ?? 0) * 3;
+  for (let i = 1; i + 1 < n; i++) {
+    const b = (loop[i] ?? 0) * 3;
+    const c = (loop[i + 1] ?? 0) * 3;
+    closestOnTriangle(
+      qx,
+      qy,
+      qz,
+      world[a] ?? 0,
+      world[a + 1] ?? 0,
+      world[a + 2] ?? 0,
+      world[b] ?? 0,
+      world[b + 1] ?? 0,
+      world[b + 2] ?? 0,
+      world[c] ?? 0,
+      world[c + 1] ?? 0,
+      world[c + 2] ?? 0,
+    );
+    const dx = qx - TRI[0];
+    const dy = qy - TRI[1];
+    const dz = qz - TRI[2];
+    if (dx * dx + dy * dy + dz * dz < 1e-12) return true;
+  }
+  return false;
+}
+
 /** Closest point on a triangle to `p`, by the standard barycentric region test. */
 function closestOnTriangle(
   px: number,

package/src/meshContact.ts

@@ -4,6 +4,7 @@ import { collideShapes, createManifold } from './manifold.ts';
 import type { Manifold, ShapePose } from './manifold.ts';
 import type { ConvexShape } from './shape.ts';
 import { shapeBounds } from './shape.ts';
+import { faceCount } from './faces.ts';
 
 /**
  * Contacts between a convex shape and a static triangle mesh.
@@ -108,6 +109,8 @@ export function collideMesh(
   const otherPose = meshIsA ? poseB : poseA;
   /* Two meshes never touch: both are static, so nothing would move if they did. */
   if (isMesh(other)) return 0;
+  /* A sphere or capsule's contacts lie on the triangle, not on it; see `filterInteriorEdge`. */
+  const roundRadius = faceCount(other) === 0 ? other.radius : -1;
 
   /*
    * The moving shape's bounds, carried into the mesh's own frame — because the tree is in that
@@ -141,7 +144,8 @@ export function collideMesh(
       sign * scratch.nx * FACE[0] + sign * scratch.ny * FACE[1] + sign * scratch.nz * FACE[2];
     /* One-sided: a normal pointing into the back of the triangle is a body already through it. */
     if (away <= 0) continue;
-    if (away < FACE_DOT) filterInteriorEdge(mesh, triangle, meshPose, sign);
+    if (away < FACE_DOT && !filterInteriorEdge(mesh, triangle, meshPose, sign, roundRadius))
+      continue;
 
     const target = out[count];
     if (target === undefined) break;
@@ -237,13 +241,24 @@ function worldCorner(
  * The separations are recomputed from the face plane rather than scaled, because the direction has
  * changed and a scaled depth would hold a body off the floor by the cosine of an angle nobody
  * chose.
+ *
+ * **A sphere or capsule is measured from its own centre, not from the contact point.** Its manifold's
+ * points lie on the triangle, so their distance from the face plane is zero whatever the real gap —
+ * and a capsule standing on a kerb, just past the top edge of the kerb's front face, read as touching
+ * that face with the face's normal, which faces backwards along its walk: a wall it had already
+ * stepped over, stopping it dead on top. So the centre that produced each contact is rebuilt from
+ * the edge normal before that normal is replaced, and the separation is its plane distance less the
+ * radius. **A centre behind the face plane drops the contact**, returning false: the one-sided rule,
+ * applied to the geometry after the swap as it is to the geometry before it. A polytope's points lie
+ * on the body, so their plane distance is already the separation, as before.
  */
 function filterInteriorEdge(
   mesh: NonNullable<ConvexShape['triangles']>,
   triangle: number,
   meshPose: ShapePose,
   sign: number,
-): void {
+  roundRadius: number,
+): boolean {
   let deepest = 0;
   for (let i = 1; i < scratch.count; i++) {
     if ((scratch.separations[i] ?? 0) < (scratch.separations[deepest] ?? 0)) deepest = i;
@@ -264,13 +279,33 @@ function filterInteriorEdge(
     }
   }
   /* A convex edge is a real one: the ridge is there and the body should feel it. */
-  if ((convexEdgesOf(mesh, triangle) >> nearest) & 1) return;
+  if ((convexEdgesOf(mesh, triangle) >> nearest) & 1) return true;
+
+  worldPlaneAnchor(mesh, triangle, meshPose, ANCHOR);
+  const plane = FACE[0] * ANCHOR[0] + FACE[1] * ANCHOR[1] + FACE[2] * ANCHOR[2];
+  if (roundRadius >= 0) {
+    /* Mesh-to-body along the old normal, out to the centre: the point plus that much of the gap. */
+    const ux = sign * scratch.nx;
+    const uy = sign * scratch.ny;
+    const uz = sign * scratch.nz;
+    for (let i = 0; i < scratch.count; i++) {
+      const reach = (scratch.separations[i] ?? 0) + roundRadius;
+      const cx = (scratch.points[i * 3] ?? 0) + ux * reach;
+      const cy = (scratch.points[i * 3 + 1] ?? 0) + uy * reach;
+      const cz = (scratch.points[i * 3 + 2] ?? 0) + uz * reach;
+      const height = cx * FACE[0] + cy * FACE[1] + cz * FACE[2] - plane;
+      if (height < 0) return false;
+      scratch.separations[i] = height - roundRadius;
+    }
+    scratch.nx = sign * FACE[0];
+    scratch.ny = sign * FACE[1];
+    scratch.nz = sign * FACE[2];
+    return true;
+  }
 
   scratch.nx = sign * FACE[0];
   scratch.ny = sign * FACE[1];
   scratch.nz = sign * FACE[2];
-  worldPlaneAnchor(mesh, triangle, meshPose, ANCHOR);
-  const plane = FACE[0] * ANCHOR[0] + FACE[1] * ANCHOR[1] + FACE[2] * ANCHOR[2];
   for (let i = 0; i < scratch.count; i++) {
     scratch.separations[i] =
       (scratch.points[i * 3] ?? 0) * FACE[0] +
@@ -278,6 +313,7 @@ function filterInteriorEdge(
       (scratch.points[i * 3 + 2] ?? 0) * FACE[2] -
       plane;
   }
+  return true;
 }
 
 const EDGE = new Float64Array(6);

package/src/staticRegions.ts

@@ -0,0 +1,76 @@
+/**
+ * A world's static scenery by region: one body a region, added when the region streams in and
+ * removed when it streams out, with each region's body index kept right as the world moves bodies.
+ *
+ * **One body a region, and a triangle mesh is what makes that cheap.** A city region holds hundreds
+ * of boxes and a few odd shapes; as bodies they would be tens of thousands for the city, every one
+ * an index to follow. As one static triangle mesh each — `meshShape`, which carries its own tree —
+ * the whole city is a few hundred bodies and a region comes and goes as one add and one remove.
+ *
+ * **Why the indices need following.** `PhysicsWorld.removeBody` fills the hole with its last body,
+ * so removing one region's body moves another's — possibly another region's, possibly anything
+ * else in the world. It returns the index that moved, and this uses it. **What it gives up** is any
+ * other caller's body index in the same world: a removal moves whatever was last, and only the
+ * caller that asked for it hears where it went. A world that also holds bodies somebody else tracks
+ * by index needs those removed through one place that follows them all.
+ */
+import type { BodyDesc } from './bodies.ts';
+import type { PhysicsWorld } from './world.ts';
+
+export class StaticRegions {
+  private readonly bodyOfRegion = new Map<number, number>();
+  /** The region each body index belongs to, or −1. Grows with the world. */
+  private regionOfBody = new Int32Array(64).fill(-1);
+
+  constructor(private readonly world: PhysicsWorld) {}
+
+  /** How many regions are in the world. */
+  get size(): number {
+    return this.bodyOfRegion.size;
+  }
+
+  has(region: number): boolean {
+    return this.bodyOfRegion.has(region);
+  }
+
+  /** The body index a region stands as now, or −1. It changes as other regions are removed. */
+  bodyOf(region: number): number {
+    return this.bodyOfRegion.get(region) ?? -1;
+  }
+
+  /** Add a region as one body. A region already in the world is refused rather than doubled. */
+  add(region: number, desc: BodyDesc): number {
+    if (this.bodyOfRegion.has(region)) {
+      throw new Error(
+        `StaticRegions: region ${region} is already in the world — remove it before adding it ` +
+          'again, or its scenery would collide twice',
+      );
+    }
+    const body = this.world.addBody(desc);
+    while (body >= this.regionOfBody.length) {
+      const wider = new Int32Array(this.regionOfBody.length * 2).fill(-1);
+      wider.set(this.regionOfBody);
+      this.regionOfBody = wider;
+    }
+    this.regionOfBody[body] = region;
+    this.bodyOfRegion.set(region, body);
+    return body;
+  }
+
+  /** Take a region out of the world. A region that is not there is nothing to remove. */
+  remove(region: number): void {
+    const body = this.bodyOfRegion.get(region);
+    if (body === undefined) return;
+    this.bodyOfRegion.delete(region);
+    const moved = this.world.removeBody(body);
+    if (moved < 0) {
+      this.regionOfBody[body] = -1;
+      return;
+    }
+    /* The body that was last now sits at `body`: whichever region owned it follows it there. */
+    const owner = this.regionOfBody[moved] ?? -1;
+    this.regionOfBody[body] = owner;
+    this.regionOfBody[moved] = -1;
+    if (owner >= 0) this.bodyOfRegion.set(owner, body);
+  }
+}

package/src/world.ts

@@ -433,7 +433,12 @@ export class PhysicsWorld implements IslandSolver {
     for (const key of kept) this.ignoredPairs.add(key);
   }
 
-  removeBody(index: number): void {
+  /**
+   * Remove a body, filling its index with the last body — whose index this returns, or −1 when the
+   * removed body was the last. **Every index past the removed one can change**, so a caller keeping
+   * body indices follows the returned one; `StaticRegions` is the worked example.
+   */
+  removeBody(index: number): number {
     this.tree.remove(this.leafOf[index] ?? 0);
     const moved = this.bodies.remove(index);
     this.followRemoval(index, moved);
@@ -445,6 +450,7 @@ export class PhysicsWorld implements IslandSolver {
     this.warm.clear();
     // Every index past the removed one may have moved, so a remembered pair is a lie.
     this.events.clear();
+    return moved;
   }
 
   /** Advance one fixed tick. */