@homie-rocks/studio 0.46.6 → 0.48.0

package/rules/interest.mjs

@@ -1,9 +1,22 @@
+import { periodicDelta, wrapValue } from './topology.mjs';
 /** Per-connection state delivery. Pure data, shared by the relay and the view.
  * Deltas may name a periodic keyframe or the previous ordered frame. A missing
  * chained predecessor is ignored until the next keyframe. Periodic encoders
  * repair the chain; ordered transports reset it on connection or epoch change.
  * No history grows with time: one keyframe per connection, no per-frame queue.
  */
+const wrapOf = snap => snap.d?.[2]?.[3]?.wrap;
+const axisNames=['x','y','z'];
+const distanceSq=(p,q,wrap)=>{if(!wrap){const dx=p[0]-q[0],dy=p[1]-q[1],dz=(p[2]??0)-(q[2]??0);return dx*dx+dy*dy+dz*dz;}let d=0;for(let i=0;i<3;i++)d+=periodicDelta(q[i]??0,p[i]??0,wrap?.[axisNames[i]])**2;return d;};
+function periodicCells(cells,p,size,wrap) {
+  const shifts=axisNames.map(k=>wrap?.[k]?[0,wrap[k][1]-wrap[k][0],wrap[k][0]-wrap[k][1]]:[0]);
+  const found=new Set();
+  for(const sx of shifts[0])for(const sy of shifts[1])for(const sz of shifts[2]){
+    const x=Math.floor((p[0]+sx)/size),y=Math.floor((p[1]+sy)/size),z=Math.floor(((p[2]??0)+sz)/size);
+    for(let dx=-1;dx<=1;dx++)for(let dy=-1;dy<=1;dy++)for(let dz=-1;dz<=1;dz++)for(const e of cells.get(`${x+dx},${y+dy},${z+dz}`)??[])found.add(e);
+  }
+  return [...found];
+}
 const spatial = new WeakMap(), controls = new WeakMap();
 function indexFor(snap, radius) {
   let byRadius = spatial.get(snap.d[1]);
@@ -29,10 +42,11 @@ export function interestSnapshot(snap, seat, radiusM) {
     else if (own) {
       const q=own[3], x=Math.floor(q[0]/index.size), y=Math.floor(q[1]/index.size), z=Math.floor((q[2]??0)/index.size);
       const cell = `${x},${y},${z}`;
-      let candidates = index.candidates.get(cell);
+      let candidates = wrapOf(snap) ? null : index.candidates.get(cell);
       if (!candidates) {
         candidates = [];
-        for(let dx=-1;dx<=1;dx++)for(let dy=-1;dy<=1;dy++)for(let dz=-1;dz<=1;dz++)
+        if(wrapOf(snap)) candidates=periodicCells(index.cells,q,index.size,wrapOf(snap));
+        else for(let dx=-1;dx<=1;dx++)for(let dy=-1;dy<=1;dy++)for(let dz=-1;dz<=1;dz++)
           candidates.push(...(index.cells.get(`${x+dx},${y+dy},${z+dz}`)??[]));
         // Every player in this cell shares the ordered candidates. The final
         // radius check remains exact for that player's position.
@@ -41,7 +55,7 @@ export function interestSnapshot(snap, seat, radiusM) {
       }
       for (const e of candidates) {
         const p=e[3];
-        if(e===own||(p[0]-q[0])**2+(p[1]-q[1])**2+((p[2]??0)-(q[2]??0))**2<=radiusM**2)visible.push(e);
+        if(e===own||distanceSq(p,q,wrapOf(snap))<=radiusM**2)visible.push(e);
       }
     }
   }
@@ -97,9 +111,9 @@ export function snapshotText(snap) {
 
 /** Whether a body that left `sent` at tick `sentTick` and kept its velocity is within `tolerance` of `entity` now. */
 const POSITION = 1 << 3, VELOCITY = 1 << 4, HEADING = 1 << 5;
-function coasts(entity, sent, ticks, hz, tolerance) {
+function coasts(entity, sent, ticks, hz, tolerance, wrap) {
   const p = entity[3], q = sent[3], v = sent[4], t = ticks / hz;
-  for (let i = 0; i < p.length; i++) if (Math.abs(p[i] - (q[i] + v[i] * t)) > tolerance) return false;
+  for (let i = 0; i < p.length; i++) if (Math.abs(periodicDelta(q[i] + v[i] * t,p[i],wrap?.[axisNames[i]])) > tolerance) return false;
   // A heading is a unit vector: the same tolerance, as a turn of that many metres at one metre's reach.
   const h = entity[5], g = sent[5];
   if (Array.isArray(h) && Array.isArray(g)) for (let i = 0; i < h.length; i++) if (Math.abs(h[i] - g[i]) > COAST_HEADING) return false;
@@ -136,7 +150,7 @@ export function snapshotEncoder(keyframeTicks, chained = false, coast = null) {
         if (!before) { changed.push(entity); continue; }
         const change = changedRow(entity, before);
         // Only where it is, how fast and which way it faces: anything else a body changed is always sent.
-        if (change && coasting && !(change[1] & ~(POSITION | VELOCITY | HEADING)) && coasts(entity, before, snap.k - held.k, coasting.hz, coasting.toleranceM)) continue;
+        if (change && coasting && !(change[1] & ~(POSITION | VELOCITY | HEADING)) && coasts(entity, before, snap.k - held.k, coasting.hz, coasting.toleranceM, wrapOf(snap))) continue;
         if (held && chained) { held.entity = entity; held.k = snap.k; }
         if (change) changed.push(change);
       }
@@ -154,13 +168,13 @@ export function snapshotDecoder() {
   // The tick each row was last SENT at: a frame that says `coast` leaves a body out while it keeps its course,
   // and this end moves it along its last velocity. `rows` keeps what was sent; what is returned is where it is now.
   let sentAt = new Map();
-  const coasted = (list, snap) => {
+  const coasted = (list, snap, collision) => {
     const hz = snap.coast;
     if (!(hz > 0)) return list;
     return list.map(row => {
       const ticks = snap.k - (sentAt.get(row[0]) ?? snap.k), v = row[4];
       if (ticks <= 0 || !Array.isArray(v) || !v.some(n => n !== 0)) return row;
-      const moved = row.slice(); moved[3] = row[3].map((n, i) => n + v[i] * ticks / hz);
+      const moved = row.slice(); moved[3] = row[3].map((n, i) => wrapValue(n + v[i] * ticks / hz, collision?.[3]?.wrap?.[axisNames[i]]));
       return moved;
     });
   };
@@ -212,7 +226,7 @@ export function snapshotDecoder() {
       for (const id of d.removed) { next.delete(id); if (d.chain) sentAt.delete(id); }
       for (const entity of updates) { next.set(entity[0], entity); if (d.chain) sentAt.set(entity[0], snap.k); }
       for (const e of d.own ?? []) { next.set(e[0], e); if (d.chain) sentAt.set(e[0], snap.k); }
-      const decoded = { ...snap, d: [d.round, coasted([...next.values()], snap), ...(d.collision === undefined ? base.d.slice(2) : [d.collision])] };
+      const decoded = { ...snap, d: [d.round, coasted([...next.values()], snap, d.collision ?? base.d[2]), ...(d.collision === undefined ? base.d.slice(2) : [d.collision])] };
       if (d.chain) { base = decoded; rows = next; }
       return decoded;
     },
@@ -238,7 +252,7 @@ export function scheduledView({ radiusM = null, precisionM = 0, nearM = null, fa
       let row = entity, sampledTick = snap.k;
       if (entity !== own) {
         const p = entity[3], q = own?.[3];
-        const distanceSquared = q ? (p[0]-q[0])**2 + (p[1]-q[1])**2 + ((p[2]??0)-(q[2]??0))**2 : 0;
+        const distanceSquared = q ? distanceSq(p,q,wrapOf(snap)) : 0;
         const old = held?.row;
         const interval = farHz && nearM !== null && distanceSquared > nearM**2 ? Math.max(1, Math.round(tickHz / farHz)) : 1;
         // Spread far-view refreshes across players instead of sending the
@@ -355,10 +369,11 @@ export function crowdWorlds({ radiusM = null, precisionM = 0 } = {}) {
         near(p) {
           if (radiusM === null) return this.everything();
           const x = Math.floor(p[0] / size), y = Math.floor(p[1] / size), z = Math.floor((p[2] ?? 0) / size), key = `${x},${y},${z}`;
-          let list = around.get(key);
+          let list = wrapOf(snap) ? null : around.get(key);
           if (!list) {
             list = [];
-            for (let dx = -1; dx <= 1; dx++) for (let dy = -1; dy <= 1; dy++) for (let dz = -1; dz <= 1; dz++) { const cell = cells.get(`${x + dx},${y + dy},${z + dz}`); if (cell) for (const i of cell) list.push(i); }
+            if(wrapOf(snap)) list=periodicCells(cells,p,size,wrapOf(snap));
+            else for (let dx = -1; dx <= 1; dx++) for (let dy = -1; dy <= 1; dy++) for (let dz = -1; dz <= 1; dz++) { const cell = cells.get(`${x + dx},${y + dy},${z + dz}`); if (cell) for (const i of cell) list.push(i); }
             list.sort((a, b) => a - b); around.set(key, list);
           }
           return list;
@@ -390,7 +405,7 @@ export function crowdView(worlds, { nearM = null, farHz = null } = {}, tickHz =
       let far = false;
       if (e !== mine && q) {
         const p = e[3]; let d = 0;
-        for (let a = 0; a < p.length; a++) d += (p[a] - q[a]) ** 2;
+        for (let a = 0; a < p.length; a++) d += periodicDelta(q[a],p[a],wrapOf(snap)?.[axisNames[a]]) ** 2;
         if (d > reach) continue;
         far = d > nearSq;
       }
@@ -407,7 +422,7 @@ export function crowdView(worlds, { nearM = null, farHz = null } = {}, tickHz =
         let tolerance = precisionM;
         if (far) { let speed = 0; for (let a = 0; a < v.length; a++) speed += v[a] * v[a]; tolerance = Math.max(precisionM, Math.sqrt(speed) * farShare); }
         let there = true;
-        for (let a = 0; a < p.length; a++) if (Math.abs(p[a] - (b[a] + v[a] * t)) > tolerance) { there = false; break; }
+        for (let a = 0; a < p.length; a++) if (Math.abs(periodicDelta(b[a]+v[a]*t,p[a],wrapOf(snap)?.[axisNames[a]])) > tolerance) { there = false; break; }
         if (there) {
           const h = row[5], g = before[5];
           if (Array.isArray(h) && Array.isArray(g)) for (let a = 0; a < h.length; a++) if (Math.abs(h[a] - g[a]) > COAST_HEADING) { there = false; break; }

package/rules/live.ts

@@ -1,3 +1,4 @@
+import {wrapPoint} from './topology.mjs';
 import { rayQuery, raySnapshot, type QueryTarget } from './query.ts';
 import { overlapsTerrain } from './terrain.ts';
 import { nearbyMap } from './map-index.ts';
@@ -10,7 +11,7 @@ import { castMap3, solidAt, type BodyShape } from './collision.ts';
 import { sweepMap, rayBox, rayCircle } from './math.ts';
 
 export type ColliderRow = [string, string, number, number, number, number, number, number, {kind: string; query?: QueryDef; fields: Record<string, number | string | boolean>}?];
-export type CollisionRevision = [number, number, ColliderRow[]];
+export type CollisionRevision = [number, number, ColliderRow[], {wrap?: import('./rules.ts').MapWrap; map?: import('./map-state.ts').MapRevision | null; previousMap?: import('./map-state.ts').MapRevision | null}?];
 export function colliderRow(id: string, at: Vec3, body: BodyShape, def: ColliderDef, fields: Record<string, unknown>, kind?: string, query?: QueryDef): ColliderRow | null {
   const opts = def === true ? {} : def;
   if (opts.enabled && fields[opts.enabled] !== true) return null;
@@ -44,7 +45,7 @@ export function collisionMap(map: MapShapes, rows: readonly ColliderRow[]): MapS
     else if (shape === 'sphere') spheres.push({ at: { x, y, z: z + w / 2 }, r: w / 2, id } as any);
     else capsules.push({ at, r: w / 2, height: h, id } as any);
   }
-  const combined = { bounds: map.bounds, staticMap: map, boxes, circles, spheres, capsules };
+  const combined = { ...(map.wrap?{wrap:map.wrap}:{}), bounds: map.bounds, staticMap: map, boxes, circles, spheres, capsules };
   rowsOf.set(combined, rows);
   return combined;
 }
@@ -71,7 +72,7 @@ export function collisionQueries(map: () => MapShapes, shape: () => BodyShape, d
       const d = typeof distance === 'number' && Number.isFinite(distance) ? Math.max(0, Math.min(10000, distance)) : 0;
       if (dims === 2) return Object.freeze({ at: Object.freeze(p), normal: Object.freeze({ x: 0, y: 0, z: 1 }), dist: 0 });
       const h = castMap3(m, p, { x: 0, y: 0, z: -d }, shape());
-      return h && h.nz > 0.5 ? Object.freeze({ at: Object.freeze({ ...p, z: p.z - d * h.t }), normal: Object.freeze({ x: h.nx, y: h.ny, z: h.nz }), dist: d * h.t, ...(h.id ? { entity: h.id } : {}) }) : undefined;
+      return h && h.nz > 0.5 ? Object.freeze({ at: Object.freeze(wrapPoint({ ...p, z: p.z - d * h.t },m.wrap)), normal: Object.freeze({ x: h.nx, y: h.ny, z: h.nz }), dist: d * h.t, ...(h.id ? { entity: h.id } : {}) }) : undefined;
     },
     overlaps: (body: unknown) => {
       const p = position(body), s = shape(), a = solidAt(p, s), m = nearbyMap(map(), p, {x:0,y:0,z:0}, s.radius, s.height || 2*s.radius, dims);

package/rules/map-index.ts

@@ -1,3 +1,4 @@
+import { imageOffsets } from './topology.mjs';
 /** Immutable build-time BVH. Queries charge nodes visited and narrow-phase work,
  * never the number of shapes in the level. Live geometry is a separate overlay. */
 import { charge } from './guard.ts';
@@ -31,6 +32,29 @@ export function indexMap(map: MapShapes): void {
 }
 /** The segment of a body's reference point against bounds expanded by its extents. */
 export function nearbyMap(map: MapShapes, p:Vec3, d:Vec3, radius:number, height:number, dims=3):MapShapes {
+  if (!map.wrap) return nearbyFlatMap(map,p,d,radius,height,dims);
+  const bounds={min:{...map.bounds.min},max:{...map.bounds.max}};
+  for(const k of axes)if(map.wrap[k]){bounds.min[k]=-Infinity;bounds.max[k]=Infinity;}
+  const out:any={bounds,boxes:[],circles:[],spheres:[],capsules:[],heightTiles:[]};
+  const extent={min:{...map.bounds.min},max:{...map.bounds.max}};
+  const root=indexes.get(map.staticMap??map);
+  if(root) for(const k of axes){if(Number.isFinite(root.min[k]))extent.min[k]=Math.min(extent.min[k],root.min[k]);if(Number.isFinite(root.max[k]))extent.max[k]=Math.max(extent.max[k],root.max[k]);}
+  if(map.staticMap)for(const key of ['boxes','circles','spheres','capsules'] as const)for(const raw of map[key]??[]){
+    charge(12);const v:any=raw;
+    for(const k of axes){const low=key==='boxes'?v.min[k]:v.at[k]-v.r,high=key==='boxes'?v.max[k]:v.at[k]+(k==='z'&&key==='capsules'?v.height:v.r);extent.min[k]=Math.min(extent.min[k],low);extent.max[k]=Math.max(extent.max[k],high);}
+  }
+  for(const offset of imageOffsets(extent,map.wrap,p,d,radius,height,dims)){
+    charge(48);
+    const found=nearbyFlatMap(map,{x:p.x-offset.x,y:p.y-offset.y,z:p.z-offset.z},d,radius,height,dims);
+    const shift=(v:Vec3)=>({x:v.x+offset.x,y:v.y+offset.y,z:v.z+offset.z});
+    for(const key of ['boxes','circles','spheres','capsules','heightTiles'] as const)for(const value of found[key]??[]){
+      charge(24);const v:any=value;
+      out[key].push(key==='boxes'?{...v,min:shift(v.min),max:shift(v.max)}:{...v,at:shift(v.at)});
+    }
+  }
+  return out;
+}
+function nearbyFlatMap(map: MapShapes, p:Vec3, d:Vec3, radius:number, height:number, dims=3):MapShapes {
   const parent=map.staticMap;
   const root=indexes.get(parent??map);
   if(!root)return map;

package/rules/map-state.ts

@@ -0,0 +1,54 @@
+/** Copy and compile a room map before publishing it. No mutation survives a failed bake. */
+import { charge, own } from './guard.ts';
+import { compileMap, type GameMap } from './rules.ts';
+export type MapRevision = readonly [
+    number,
+    unknown
+];
+function copy(value: unknown, depth = 0): unknown {
+    charge(6);
+    if (typeof value === 'string') {
+        charge(value.length);
+        return value;
+    }
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (!value || typeof value !== 'object' || depth > 8)
+        throw new Error('map.replace needs finite plain map data');
+    if (Array.isArray(value)) {
+        const out = [];
+        for (let i = 0; i < value.length; i++)
+            out.push(copy(own(value, i), depth + 1));
+        return Object.freeze(out);
+    }
+    const out: Record<string, unknown> = Object.create(null);
+    for (const key of Object.keys(value)) {
+        charge(key.length);
+        out[key] = copy(own(value, key), depth + 1);
+    }
+    return Object.freeze(out);
+}
+export function prepareMapReplacement(value: unknown, base: GameMap): {
+    raw: unknown;
+    map: GameMap;
+    cells: number;
+} {
+    const raw = copy(value) as any;
+    // Index construction sorts at each depth. Charge its upper bound before compilation.
+    let runs = 0;
+    const tiles = raw?.tiles;
+    if (tiles && Array.isArray(tiles.data)) {
+        charge(tiles.data.length * 8);
+        for (let i = 0; i < tiles.data.length; i++)
+            if (tiles.data[i] && (i % tiles.width === 0 || !tiles.data[i - 1]))
+                runs++;
+    }
+    const count = (raw?.boxes?.length ?? 0) + (raw?.circles?.length ?? 0) + (raw?.spheres?.length ?? 0) + (raw?.capsules?.length ?? 0) + (raw?.heightTiles?.length ?? 0) + runs;
+    charge(64 + count * (16 + Math.ceil(Math.log2(count + 1)) ** 2));
+    const map = compileMap(raw, base.name);
+    if (JSON.stringify(map.bounds) !== JSON.stringify(base.bounds) || (['x', 'y', 'z'] as const).some(k => Boolean(map.wrap?.[k]) !== Boolean(base.wrap?.[k])))
+        throw new Error('map.replace preserves bounds and wrap; replace level geometry, tiles and spots');
+    return { raw, map, cells: JSON.stringify(raw).length };
+}

package/rules/math.ts

@@ -1,3 +1,7 @@
+import { physicsWorld } from './physics.ts';
+import { substeps } from './substeps.ts';
+import { wrapPoint } from './topology.mjs';
+import { tileApi } from './tiles.ts';
 import { nearbyMap } from './map-index.ts';
 import { collisionQueries } from './live.ts';
 /*
@@ -184,7 +188,7 @@ export const exact = Object.freeze({ sin, cos, atan, atan2, exp, log, pow });
 /* ------------------------------------------------------------------ the ground plane: a point or a circle against the map */
 
 /** The shapes of a map the sweep reads (rules.ts `GameMap` has them). */
-export interface MapShapes { staticMap?: MapShapes; bounds: { min: Vec3; max: Vec3 }; boxes: readonly { min: Vec3; max: Vec3 }[]; circles: readonly { at: Vec3; r: number }[]; spheres?: readonly { at: Vec3; r: number }[]; capsules?: readonly { at: Vec3; r: number; height: number }[]; heightTiles?: readonly import('./rules.ts').MapHeightTile[] }
+export interface MapShapes { wrap?: import('./rules.ts').MapWrap; staticMap?: MapShapes; bounds: { min: Vec3; max: Vec3 }; boxes: readonly { min: Vec3; max: Vec3 }[]; circles: readonly { at: Vec3; r: number }[]; spheres?: readonly { at: Vec3; r: number }[]; capsules?: readonly { at: Vec3; r: number; height: number }[]; heightTiles?: readonly import('./rules.ts').MapHeightTile[] }
 /** How close a swept body stops to what it hit, in metres. */
 export const SKIN = 0.001;
 
@@ -278,16 +282,16 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
     const h = castMap3(map, p, d, shape);
     const length = Math.sqrt(dx * dx + dy * dy + d.z * d.z);
     const t = h ? Math.max(0, h.t - (length > 0 ? SKIN / length : 0)) : 1;
-    const at = v(fr(px + dx * t), fr(py + dy * t), fr(p.z + d.z * t));
+    const at = wrapPoint(v(fr(px + dx * t), fr(py + dy * t), fr(p.z + d.z * t)), map.wrap);
     put(body, 'pos', at); if (own(options, 'ground') !== false) put(body, 'grounded', restsOnMap(map, at, shape));
     return h ? Object.freeze({ at, normal: v(h.nx, h.ny, h.nz), ...(h.id ? { entity: h.id } : {}) }) : undefined;
   }
   const { hit: h } = castMap(map, px, py, dx, dy, radius);
   put(body, 'grounded', true);
-  if (!h) { put(body, 'pos', v(fr(px + dx), fr(py + dy), 0)); return undefined; }
+  if (!h) { put(body, 'pos', wrapPoint(v(fr(px + dx), fr(py + dy), 0), map.wrap)); return undefined; }
   const l = Math.sqrt(dx * dx + dy * dy);
   const t = l > 0 ? Math.max(0, h.t - SKIN / l) : 0;
-  const at = v(fr(px + dx * t), fr(py + dy * t), 0);
+  const at = wrapPoint(v(fr(px + dx * t), fr(py + dy * t), 0), map.wrap);
   put(body, 'pos', at);
   return Object.freeze({ at, normal: v(h.nx, h.ny, 0), ...(h.id ? { entity: h.id } : {}) });
 }
@@ -297,14 +301,22 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
  * map. One function, so that the browser (view.ts) and the person the build check plays hold the same one. The
  * server's own (core.ts `moveCtx`) is made beside the rest of its world, and charges as that does.
  */
+const physicsContexts = new WeakMap<object, () => void>();
+export function disposeMoveContext(context: object): void { physicsContexts.get(context)?.(); physicsContexts.delete(context); }
 export function moveContext(o: { tick: () => number; tickHz: number; tune: unknown; map: MapShapes; name: string; spots: Readonly<Record<string, readonly unknown[]>>; radius: () => number; shape?: () => BodyShape; dims: number; geometry?: () => MapShapes; self?: () => string | undefined }): unknown {
+  const physics = physicsWorld((o.map as import('./rules.ts').GameMap).physics);
   const none = Object.freeze([]);
+  const currentMap = () => (o.geometry?.()?.staticMap ?? o.geometry?.() ?? o.map) as import('./rules.ts').GameMap;
   const queries = collisionQueries(() => o.geometry?.() ?? o.map, () => o.shape?.() ?? {shape: 'sphere', radius: o.radius(), height: 2 * o.radius()}, o.dims, o.self);
-  return brand(Object.freeze({
+  const context = brand(Object.freeze({
+    ...(physics ? {physics: physics.movement} : {}),
+    substeps: substeps(o.tickHz),
     get tick() { return o.tick(); }, dt: 1 / o.tickHz, tune: o.tune, math,
     // As the server's `ctx.ticks` reads it: a plain number, or nothing.
     ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * o.tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
     world: brand(Object.freeze(queries)),
-    map: brand(Object.freeze({ name: o.name, spot: (name: string) => (own(o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(o.spots, name) ?? none, ...queries })),
+    map: brand(Object.freeze({ ...tileApi(currentMap), name: o.name, spot: (name: string) => (own(currentMap().spots ?? o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(currentMap().spots ?? o.spots, name) ?? none, ...queries })),
   }));
+  if (physics) physicsContexts.set(context, physics.dispose);
+  return context;
 }

package/rules/nav/Flow.ts

@@ -0,0 +1,53 @@
+// Generated by scripts/studio-nav.mjs from packages/nav/src/Flow.ts.
+/** Cardinal multi-source flow bake. Stable left/up/right/down ties.
+ * Callers can debit deterministic work before allocation and for each visited cell. */
+export interface FlowGrid {
+  width: number;
+  height: number;
+  data: readonly number[];
+  wrapX?: boolean;
+  wrapY?: boolean;
+}
+
+export function bakeGridFlow(
+  grid: FlowGrid,
+  goals: readonly number[],
+  charge: (units: number) => void = () => {},
+): { distance: Int32Array; next: Int32Array } {
+  const { width, height, data } = grid;
+  const count = width * height;
+  if (!Number.isSafeInteger(count) || width < 1 || height < 1 ||
+      !Number.isInteger(width) || !Number.isInteger(height) || data.length !== count) {
+    throw new Error('nav flow: invalid grid');
+  }
+  charge(count * 4);
+  const distance = new Int32Array(count).fill(-1);
+  const next = new Int32Array(count).fill(-1);
+  const queue = new Int32Array(count);
+  let tail = 0;
+  for (const goal of goals) {
+    charge(2);
+    if (!Number.isInteger(goal) || goal < 0 || goal >= count) throw new Error('nav flow: goal outside grid');
+    if (!data[goal] && distance[goal]! < 0) {
+      distance[goal] = 0;
+      next[goal] = goal;
+      queue[tail++] = goal;
+    }
+  }
+  for (let head = 0; head < tail; head++) {
+    charge(16);
+    const cell = queue[head]!, x = cell % width, y = Math.floor(cell / width);
+    for (const [dx, dy] of [[-1, 0], [0, -1], [1, 0], [0, 1]]) {
+      let nx = x + dx!, ny = y + dy!;
+      if (grid.wrapX) nx = (nx + width) % width;
+      if (grid.wrapY) ny = (ny + height) % height;
+      if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
+      const id = ny * width + nx;
+      if (data[id] || distance[id] !== -1) continue;
+      distance[id] = distance[cell]! + 1;
+      next[id] = cell;
+      queue[tail++] = id;
+    }
+  }
+  return { distance, next };
+}

package/rules/pack.ts

@@ -1,3 +1,4 @@
+import { takeSubsteps, type StepPose } from './substeps.ts';
 /*
  * pack.ts — declared state in and out: holding a value to its declared type, and packing it for the wire and the save.
  * =============================================================================
@@ -262,7 +263,7 @@ export interface MoveBody { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boole
  * left rounded to 32-bit floats and held to the declared shapes as the server does it, so both hold the same numbers.
  * `used` is the units it took. What it throws goes to `failed` (the budget's own stop too) and the body is still read.
  */
-export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number } {
+export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number; steps?: readonly StepPose[] } {
   G.queryEpoch++; G.left = quota;
   const bag = coerceFields(motion, body.motion, dims);
   const target: Record<string, unknown> = {};
@@ -296,7 +297,8 @@ export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => v
   const used = quota - (G.left > 0 ? G.left : 0);
   G.left = Infinity;
   naming('body', 'pos'); const pos = vec3(body.pos, dims); naming('body', 'vel'); const vel = vec3(body.vel, dims); naming('body', 'heading'); const heading = dir(body.heading, dims); naming();
-  return { pos, vel, heading, grounded: body.grounded === true, motion: thawFields(motion, bag), used };
+  const steps = takeSubsteps(body);
+  return { pos, vel, heading, grounded: body.grounded === true, motion: thawFields(motion, bag), used, ...(steps ? {steps} : {}) };
 }
 
 /** How many values `pack` has packed since this was last set to 0: the core reads it to charge a tick for the state it sends. */

package/rules/physics-engine.ts

@@ -0,0 +1,73 @@
+/** Loaded only by games declaring a baked physics level. */
+import { createWorld } from '@homie-rocks/physics/World.js';
+import { initPhysics } from '@homie-rocks/physics/Worker.js';
+import { brand, charge } from './guard.ts';
+import { registerPhysics, type PhysicsMovement, type RulesPhysics } from './physics.ts';
+
+// CPU calibration is recorded in docs/physics-048-calibration.md. Charges precede work.
+export const PHYSICS_UNITS = Object.freeze({ cast: 768, ray: 640, overlap: 640, step: 2400 });
+export async function initializePhysics(source: WebAssembly.Module | BufferSource): Promise<void> {
+  await initPhysics(source);
+  registerPhysics((mesh, saved) => {
+    const world = createWorld({ up: 'z', fixedDt: 1 / 300, maxSubsteps: 128, bounds: null });
+    try {
+      if (saved) world.restore(Uint8Array.from(saved));
+      else world.createBody({ type: 'static', colliders: [{ shape: { kind: 'mesh', vertices: Float32Array.from(mesh.vertices), indices: Uint32Array.from(mesh.indices) } }] });
+      const count = Math.max(1, Math.ceil(mesh.indices.length / (1754 * 3)));
+      const convex = (shape: {kind:string}) => { if (!['box','sphere','capsule'].includes(shape.kind)) throw new Error('rules physics queries use a box, sphere or capsule'); };
+      const movement: PhysicsMovement = {
+        cast(...args) { charge(PHYSICS_UNITS.cast * count); convex(args[0]); return world.castShape(...args); },
+        ray(...args) { charge(PHYSICS_UNITS.ray * count); return world.raycast(...args); },
+        overlap(...args) { charge(PHYSICS_UNITS.overlap * count); convex(args[0]); return world.overlaps(...args); },
+        sweep(body, delta, radius, height) {
+          charge(64);
+          let left = { ...delta }, pos = { ...body.pos }, vel = { ...body.vel };
+          let grounded = false;
+          for (let n = 0; n < 4; n++) {
+            const length = Math.hypot(left.x, left.y, left.z);
+            if (length < 1e-9) break;
+            charge(PHYSICS_UNITS.cast * count);
+            const hit = world.castCapsule(pos, left, radius, height);
+            const fraction = hit ? Math.max(0, hit.fraction) : 1;
+            pos = { x: pos.x + left.x * fraction, y: pos.y + left.y * fraction, z: pos.z + left.z * fraction };
+            if (!hit) break;
+            if (hit.normal.z > .65 && delta.z <= 0) grounded = true;
+            const normal = hit.normal;
+            const dot = left.x * normal.x + left.y * normal.y + left.z * normal.z;
+            const speed = vel.x * normal.x + vel.y * normal.y + vel.z * normal.z;
+            if (normal.z > .65 && delta.z <= 0) {
+              // Lift the requested horizontal travel along a walkable slope.
+              // Projecting gravity onto its normal would make an idle capsule drift.
+              left = { x: left.x * (1-fraction), y: left.y * (1-fraction), z: 0 };
+              left.z = -(left.x * normal.x + left.y * normal.y) / normal.z;
+              vel = { x: vel.x, y: vel.y, z: Math.max(0, vel.z) };
+            } else {
+              left = { x: (left.x-normal.x*Math.min(0,dot))*(1-fraction), y: (left.y-normal.y*Math.min(0,dot))*(1-fraction), z: (left.z-normal.z*Math.min(0,dot))*(1-fraction) };
+              vel = { x:vel.x-normal.x*Math.min(0,speed), y:vel.y-normal.y*Math.min(0,speed), z:vel.z-normal.z*Math.min(0,speed) };
+            }
+          }
+          body.pos = pos; body.vel = vel; body.grounded = grounded;
+        },
+      };
+      const api: RulesPhysics = {
+        ...movement,
+        step(dt) {
+          charge(8);
+          if (!Number.isFinite(dt) || dt < 0) throw new Error('physics: dt must be finite and nonnegative');
+          charge(PHYSICS_UNITS.step * count * Math.max(1, Math.ceil(dt * 300)));
+          while (dt > .1) { world.step(.1); dt -= .1; }
+          world.step(dt);
+        },
+      };
+      let disposed = false, finalSave: number[] | undefined;
+      return { api: brand(Object.freeze(api)), movement: brand(Object.freeze(movement)),
+        save: () => finalSave ? [...finalSave] : Array.from(world.snapshot()),
+        dispose: () => {
+          if (disposed) return;
+          try { finalSave = Array.from(world.snapshot()); } catch { /* A failed engine has no final checkpoint. */ }
+          world.dispose(); disposed = true;
+        },
+      };
+    } catch (error) { world.dispose(); throw error; }
+  });
+}

package/rules/physics.ts

@@ -0,0 +1,26 @@
+/** Opt-in boundary. Importing the rules kernel never imports or initializes WASM. */
+import type { Vec3 } from './rules.ts';
+export interface PhysicsMesh { vertices: readonly number[]; indices: readonly number[] }
+// Structural query types keep the ordinary rules types independent of the optional package.
+export type PhysicsShape = {kind: 'box'; halfExtents: Vec3} | {kind: 'sphere'; radius: number} | {kind: 'capsule'; radius: number; halfHeight: number};
+export interface PhysicsRotation {x: number; y: number; z: number; w: number}
+export interface PhysicsFilter {layers?: {membership: number; filter: number}; excludeBody?: number; excludeCollider?: number; sensors?: boolean}
+export interface PhysicsHit {collider: number; body: number; point: Vec3; normal: Vec3}
+export interface PhysicsMovement {
+  sweep(body: {pos: Vec3; vel: Vec3; grounded: boolean}, delta: Vec3, radius: number, height: number): void;
+  ray(origin: Vec3, direction: Vec3, distance: number, filter?: PhysicsFilter): (PhysicsHit & {distance: number}) | null;
+  overlap(shape: PhysicsShape, position: Vec3, orientation?: PhysicsRotation, filter?: PhysicsFilter): number[];
+  cast(shape: PhysicsShape, position: Vec3, delta: Vec3, orientation?: PhysicsRotation, filter?: PhysicsFilter): (PhysicsHit & {fraction: number}) | null;
+}
+export interface RulesPhysics extends PhysicsMovement {
+  step(seconds: number): void;
+}
+export interface PhysicsBridge { api: RulesPhysics; movement: PhysicsMovement; save(): number[]; dispose(): void }
+let factory: ((mesh: PhysicsMesh, saved?: number[]) => PhysicsBridge) | undefined;
+export function registerPhysics(value: NonNullable<typeof factory>): void { factory = value; }
+export function physicsWorld(mesh?: PhysicsMesh, saved?: number[]): PhysicsBridge | undefined {
+  if (!mesh) { if (saved !== undefined) throw new Error('physics save requires a physics level'); return; }
+  if (saved !== undefined && (!Array.isArray(saved) || saved.some(n => !Number.isInteger(n) || n < 0 || n > 255))) throw new Error('physics: invalid saved bytes');
+  if (!factory) throw new Error('physics: initialize the game before starting its room');
+  return factory(mesh, saved);
+}

package/rules/query.ts

@@ -1,3 +1,4 @@
+import { imageOffsets, wrapPoint } from './topology.mjs';
 /** Bounded, data-only ray policy. Shared by rules and predicted geometry queries. */
 import { charge, brand, plainData, put } from './guard.ts';
 import { own, dir, vec3 } from './pack.ts';
@@ -37,14 +38,15 @@ export function rayQuery(map: MapShapes, targets: readonly QueryTarget[], dims:
   const take=(h: {t:number;nx:number;ny:number;nz?:number}|null,id?:string,part?:string):void=>{
     if(!h)return; charge(32);
     if(h.t===0 && h.nx===0 && h.ny===0 && !h.nz)h={...h,nx:-d.x,ny:-d.y,nz:-d.z};
-    hits.push(Object.freeze({at:vec3({x:p.x+delta.x*h.t,y:p.y+delta.y*h.t,z:p.z+delta.z*h.t},dims),normal:vec3({x:h.nx,y:h.ny,z:h.nz??0},dims),dist:max*h.t,...(id?{entity:id}:{}),...(part?{part}:{})}));
+    hits.push(Object.freeze({at:vec3(wrapPoint({x:p.x+delta.x*h.t,y:p.y+delta.y*h.t,z:p.z+delta.z*h.t},map.wrap),dims),normal:vec3({x:h.nx,y:h.ny,z:h.nz??0},dims),dist:max*h.t,...(id?{entity:id}:{}),...(part?{part}:{})}));
   };
   if(own(options,'entitiesOnly')!==true && (layer===undefined || layer==='geometry')) {
     if(dims===3) {const found: import('./collision.ts').Hit3[]=[];const h=castMap3(map,start,delta,shape,all?found:undefined,includeInside);if(all)for(const h of found)take(h);else take(h);}
     else {const found: import('./math.ts').Hit[]=[];const h=castMap(map,p.x,p.y,delta.x,delta.y,radius,all?found:undefined,includeInside,shape.shape==='box').hit;if(all)for(const h of found)take(h);else take(h);}
   }
   const point=solidAt(start,shape);
-  for(const target of targets) {
+  const candidates=map.wrap?periodicTargets(targets,map,start,delta,radius,height,dims,profile as string | undefined):targets;
+  for(const target of candidates) {
     if(excluded.has(target.id) || own(options,'geometryOnly')===true&&!target.geometry || layer!==undefined && layer!==(target.query?.layer??(target.geometry?'geometry':'body')) || kind!==undefined && kind!==target.kind || tag!==undefined && !target.query?.tags?.includes(tag as string)) continue;
     const declared = target.at ? queryParts(target.at,target.query,profile as string | undefined) : target.parts;
     const parts=(own(options,'geometryOnly')!==true && declared?.length?declared:[{name:'',solid:target.solid}]).filter(part=>{
@@ -96,8 +98,21 @@ export function raySnapshot(map:MapShapes,targets:readonly QueryTarget[],dims:nu
  const ray=(from:unknown,direction:unknown,max:unknown)=>rayQuery(map,scene,dims,from,direction,max,policy,self)[0];
  const radius=typeof own(policy,'radius')==='number'?own(policy,'radius') as number:0,height=own(policy,'shape')==='box'||own(policy,'shape')==='capsule'?Number(own(policy,'height')??radius*2):radius*2;
  const position=(body:unknown)=>{const at=own(body,'pos');if(!at||typeof at!=='object')throw new Error('scene sweep/support takes a scratch body with a plain pos');return vec3(at,dims);};
- const support=(body:unknown,distance:unknown=.002)=>{const p=position(body);if(dims===2)return Object.freeze({at:p,normal:Object.freeze({x:0,y:0,z:1}),dist:0});if(typeof distance!=='number'||!Number.isFinite(distance)||distance<0)throw new Error('support distance is finite and nonnegative');const h=rayQuery(map,scene,dims,{x:p.x,y:p.y,z:p.z+height/2},{x:0,y:0,z:-1},distance,policy,self,false,false)[0];return h&&h.normal.z>.5?Object.freeze({...h,at:vec3({x:h.at.x,y:h.at.y,z:(h.at.z??0)-height/2},dims)}):undefined;};
+ const support=(body:unknown,distance:unknown=.002)=>{const p=position(body);if(dims===2)return Object.freeze({at:p,normal:Object.freeze({x:0,y:0,z:1}),dist:0});if(typeof distance!=='number'||!Number.isFinite(distance)||distance<0)throw new Error('support distance is finite and nonnegative');const h=rayQuery(map,scene,dims,{x:p.x,y:p.y,z:p.z+height/2},{x:0,y:0,z:-1},distance,policy,self,false,false)[0];return h&&h.normal.z>.5?Object.freeze({...h,at:vec3(wrapPoint({x:h.at.x,y:h.at.y,z:(h.at.z??0)-height/2},map.wrap),dims)}):undefined;};
  const sweep=(body:unknown,delta:unknown,options?:unknown)=>{const p=position(body),d=vec3(delta,dims),length=Math.sqrt(d.x*d.x+d.y*d.y+d.z*d.z),h=length?rayQuery(map,scene,dims,{x:p.x,y:p.y,z:p.z+height/2},d,length,policy,self,false,false)[0]:undefined;
-   const fraction=h?Math.max(0,(h.dist-.001)/length):1;put(body as object,'pos',vec3({x:p.x+d.x*fraction,y:p.y+d.y*fraction,z:p.z+d.z*fraction},dims));if(own(options,'ground')!==false)put(body as object,'grounded',dims===2||Boolean(support(body)));return h?Object.freeze({...h,at:vec3(own(body,'pos'),dims)}):undefined;};
+   const fraction=h?Math.max(0,(h.dist-.001)/length):1;put(body as object,'pos',vec3(wrapPoint({x:p.x+d.x*fraction,y:p.y+d.y*fraction,z:p.z+d.z*fraction},map.wrap),dims));if(own(options,'ground')!==false)put(body as object,'grounded',dims===2||Boolean(support(body)));return h?Object.freeze({...h,at:vec3(own(body,'pos'),dims)}):undefined;};
  return brand(Object.freeze({ray,rayAll:(from:unknown,direction:unknown,max:unknown)=>rayQuery(map,scene,dims,from,direction,max,policy,self,true),sweep,support}));
 }
+
+/** Default queries retain their original target loop; only wrapped worlds construct images. */
+function* periodicTargets(targets:readonly QueryTarget[],map:MapShapes,start:Vec3,delta:Vec3,radius:number,height:number,dims:number,profile?:string):Generator<QueryTarget> {
+  for(const source of targets) {
+    const ext={min:{x:source.solid.min.x-source.solid.r,y:source.solid.min.y-source.solid.r,z:source.solid.min.z-source.solid.r},max:{x:source.solid.max.x+source.solid.r,y:source.solid.max.y+source.solid.r,z:source.solid.max.z+source.solid.r}};
+    for(const part of (source.at ? queryParts(source.at,source.query,profile) : source.parts) ?? []) for(const k of ['x','y','z'] as const){ext.min[k]=Math.min(ext.min[k],part.solid.min[k]-part.solid.r);ext.max[k]=Math.max(ext.max[k],part.solid.max[k]+part.solid.r);}
+    for(const offset of imageOffsets(ext,map.wrap,start,delta,radius,height,dims)) {
+    charge(48);
+    const shift=(v:Vec3)=>({x:v.x+offset.x,y:v.y+offset.y,z:v.z+offset.z});
+    yield {...source,at:source.at?shift(source.at):undefined,solid:{...source.solid,min:shift(source.solid.min),max:shift(source.solid.max)},parts:source.parts?.map(part=>({...part,solid:{...part.solid,min:shift(part.solid.min),max:shift(part.solid.max)}}))};
+    }
+  }
+}

package/rules/rules.ts

@@ -1,3 +1,4 @@
+import { compileTiles, type Tiles } from './tiles.ts';
 import {prepareGraph,type RouteNode} from './navigation.ts';
 import { prepareTile as prepareExactTile } from './terrain.ts';
 import { prepareTile as prepareLegacyTile } from './terrain-legacy.ts';
@@ -289,7 +290,8 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
 export interface MapBox { readonly min: Vec3; readonly max: Vec3 }
 export interface MapCircle { readonly at: Vec3; readonly r: number }
 export interface MapHeightTile { readonly base?: number; readonly diagonal?: '00-11' | '10-01'; readonly at: Vec3; readonly size: Readonly<{ x: number; y: number }>; readonly heights: readonly [number, number, number, number] }
-export interface GameMap { readonly name: string; readonly heightTiles: readonly MapHeightTile[]; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spheres: readonly MapCircle[]; readonly capsules: readonly (MapCircle & { height: number })[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
+export type MapWrap = Readonly<Partial<Record<'x' | 'y' | 'z', readonly [number, number]>>>;
+export interface GameMap { readonly physics?: import('./physics.ts').PhysicsMesh; readonly tiles?: Tiles; readonly wrap?: MapWrap; readonly name: string; readonly heightTiles: readonly MapHeightTile[]; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spheres: readonly MapCircle[]; readonly capsules: readonly (MapCircle & { height: number })[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
 
 const vecOf = (a: unknown, what: string): Vec3 => {
   const p = Array.isArray(a) ? { x: a[0], y: a[1], z: a[2] ?? 0 } : a as { x?: unknown; y?: unknown; z?: unknown } | null;
@@ -323,8 +325,33 @@ export function compileMap(raw: unknown, name = 'main'): GameMap {
   };
   if ([m.boxes, m.circles, m.spheres, m.capsules, m.heightTiles].some(list => list !== undefined && !Array.isArray(list))) throw new Error(`${where}: shapes are lists`);
   if ([m.boxes, m.circles, m.spheres, m.capsules, m.heightTiles].reduce((n, list) => n + (list?.length ?? 0), 0) > 100000) throw new Error(`${where}: at most 100000 static shapes`);
+  const bounds = box(m.bounds, `${where} bounds`);
+  let wrap: MapWrap | undefined;
+  if (m.wrap !== undefined) {
+    if (!m.wrap || typeof m.wrap !== 'object' || Array.isArray(m.wrap)) throw new Error(`${where}: wrap names axes x, y, z`);
+    const axes: Partial<Record<'x'|'y'|'z', readonly [number,number]>> = {};
+    for (const key of Object.keys(m.wrap)) {
+      if (!['x','y','z'].includes(key) || m.wrap[key] !== true) throw new Error(`${where}: wrap axes are true (period comes from bounds)`);
+      const k = key as 'x'|'y'|'z';
+      if (!(bounds.max[k] > bounds.min[k]) || !Number.isFinite(bounds.max[k]-bounds.min[k])) throw new Error(`${where}: wrapped axis needs finite positive extent`);
+      axes[k] = Object.freeze([bounds.min[k], bounds.max[k]]);
+    }
+    if(Object.keys(axes).length) wrap = Object.freeze(axes);
+  }
+  const tiled=compileTiles(m.tiles,wrap);
+  if(tiled) for(const k of ['x','y'] as const) if(wrap?.[k] && (tiled.tiles.at[k]!==bounds.min[k] || tiled.tiles.at[k]+tiled.tiles.size*(k==='x'?tiled.tiles.width:tiled.tiles.height)!==bounds.max[k])) throw new Error(`${where}: tiles must span each wrapped axis`);
+  let physics: import('./physics.ts').PhysicsMesh | undefined;
+  if (m.physics !== undefined) {
+    const {vertices, indices} = m.physics ?? {};
+    if (!Array.isArray(vertices) || !Array.isArray(indices) || !vertices.length || vertices.length % 3 || !indices.length || indices.length % 3 ||
+      vertices.some((n: unknown) => typeof n !== 'number' || !Number.isFinite(n) || !Number.isFinite(Math.fround(n))) ||
+      indices.some((n: unknown) => !Number.isSafeInteger(n) || (n as number) < 0 || (n as number) >= vertices.length / 3)) throw new Error(`${where}: physics needs a build-time baked triangle mesh`);
+    physics = Object.freeze({vertices:Object.freeze([...vertices]),indices:Object.freeze([...indices])});
+  }
   const result = Object.freeze({
-    name,
+    ...(m.physics ? {physics: physics!} : {}),
+    ...(tiled?{tiles:tiled.tiles}:{}),
+    name, ...(wrap ? {wrap} : {}),
     heightTiles: Object.freeze((m.heightTiles ?? []).map((t: any, i: number) => {
       const what = `${where} heightTiles[${i}]`;
       const at = vecOf(t?.at, `${what}.at`);
@@ -342,8 +369,8 @@ export function compileMap(raw: unknown, name = 'main'): GameMap {
       if (!Number.isFinite(c.height) || c.height < 2 * shape.r) throw new Error(`${where} capsules[${i}]: height is at least twice the radius`);
       return Object.freeze({ ...shape, height: c.height });
     })),
-    bounds: box(m.bounds, `${where} bounds`),
-    boxes: Object.freeze((Array.isArray(m.boxes) ? m.boxes : []).map((b: unknown, i: number) => box(b, `${where} boxes[${i}]`))),
+    bounds,
+    boxes: Object.freeze([...(tiled?.boxes??[]),...(Array.isArray(m.boxes) ? m.boxes : [])].map((b: unknown, i: number) => box(b, `${where} boxes[${i}]`))),
     circles: Object.freeze((Array.isArray(m.circles) ? m.circles : []).map((c: any, i: number) => {
       const r = Number(c?.r);
       if (!Number.isFinite(r) || !(r > 0)) throw new Error(`${where} circles[${i}] needs "r", its radius in metres`);