@homie-rocks/studio 0.46.6 → 0.47.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,5 @@
+import { wrapPoint } from './topology.mjs';
+import { tileApi } from './tiles.ts';
 import { nearbyMap } from './map-index.ts';
 import { collisionQueries } from './live.ts';
 /*
@@ -184,7 +186,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 +280,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 } : {}) });
 }
@@ -299,12 +301,13 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
  */
 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 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({
     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 })),
   }));
 }

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/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 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,24 @@ 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`);
   const result = Object.freeze({
-    name,
+    ...(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 +360,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`);

package/rules/tiles.ts

@@ -0,0 +1,58 @@
+import { bakeGridFlow } from './nav/Flow.ts';
+import { charge } from './guard.ts';
+import type { GameMap, MapBox, MapWrap, Vec3 } from './rules.ts';
+export interface Tiles {
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+    readonly at: Vec3;
+    readonly solidHeight: number;
+    readonly data: readonly number[];
+    readonly flows: Readonly<Record<string, readonly number[]>>;
+}
+const fields = new WeakMap<object, Map<string, ReturnType<typeof bakeGridFlow>>>();
+export function compileTiles(raw: any, wrap?: MapWrap): {
+    tiles: Tiles;
+    boxes: MapBox[];
+} | undefined {
+    if (raw === undefined)
+        return;
+    const { width, height, size = 1, solidHeight = 1 } = raw, n = width * height, at = raw.at ?? [0, 0, 0];
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1 || !Number.isSafeInteger(n) || !Number.isFinite(size) || size <= 0 || !Number.isFinite(solidHeight) || solidHeight <= 0 || !Array.isArray(at) || at.length < 2 || at.length > 3 || at.some((x: unknown) => typeof x !== 'number' || !Number.isFinite(x)) || !Array.isArray(raw.data) || raw.data.length !== n)
+        throw new Error('map tiles: positive width, height, size, solidHeight, at and one data value per cell');
+    if (!Number.isFinite(at[0] + width * size) || !Number.isFinite(at[1] + height * size) || !Number.isFinite((at[2] ?? 0) + solidHeight))
+        throw new Error('map tiles: finite extent required');
+    const data = raw.data.map((v: unknown) => { if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > 65535)
+        throw new Error('map tile values are integers 0..65535'); return v; });
+    const origin = { x: at[0], y: at[1], z: at[2] ?? 0 }, boxes: MapBox[] = [];
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++)
+            if (data[y * width + x]) {
+                const start = x;
+                while (x + 1 < width && data[y * width + x + 1])
+                    x++;
+                boxes.push(Object.freeze({ min: Object.freeze({ x: origin.x + start * size, y: origin.y + y * size, z: origin.z }), max: Object.freeze({ x: origin.x + (x + 1) * size, y: origin.y + (y + 1) * size, z: origin.z + solidHeight }) }));
+            }
+    const flows: Record<string, readonly number[]> = {}, baked = new Map<string, ReturnType<typeof bakeGridFlow>>();
+    for (const [name, goals] of Object.entries(raw.flows ?? {})) {
+        if (!/^[a-z][A-Za-z0-9_]{0,31}$/.test(name) || !Array.isArray(goals))
+            throw new Error('tile flows name lists of goal cell indices');
+        flows[name] = Object.freeze([...goals]);
+        baked.set(name, bakeGridFlow({ width, height, data, wrapX: Boolean(wrap?.x), wrapY: Boolean(wrap?.y) }, goals, charge));
+    }
+    const tiles = Object.freeze({ width, height, size, solidHeight, at: Object.freeze(origin), data: Object.freeze(data), flows: Object.freeze(flows) });
+    fields.set(tiles, baked);
+    return { tiles, boxes };
+}
+export function tileApi(get: () => GameMap) {
+    const cell = (x: unknown, y: unknown) => { const t = get().tiles; if (!t || typeof x !== 'number' || typeof y !== 'number' || !Number.isInteger(x) || !Number.isInteger(y))
+        return -1; const w = get().wrap; if (w?.x)
+        x = ((x % t.width) + t.width) % t.width; if (w?.y)
+        y = ((y % t.height) + t.height) % t.height; return x < 0 || y < 0 || x >= t.width || y >= t.height ? -1 : y * t.width + x; };
+    return {
+        tile: (x: unknown, y: unknown) => { charge(4); const id = cell(x, y); return id < 0 ? 1 : get().tiles!.data[id]; },
+        distance: (name: unknown, x: unknown, y: unknown) => { charge(4); const id = cell(x, y), f = typeof name === 'string' && get().tiles ? fields.get(get().tiles!)?.get(name) : null; return id < 0 || !f ? -1 : f.distance[id]; },
+        flow: (name: unknown, x: unknown, y: unknown) => { charge(8); const id = cell(x, y), t = get().tiles, f = typeof name === 'string' && t ? fields.get(t)?.get(name) : null; if (!t || id < 0 || !f || f.next[id] < 0)
+            return undefined; const next = f.next[id], dx = next % t.width - id % t.width, dy = Math.floor(next / t.width) - Math.floor(id / t.width); return Object.freeze({ x: Math.abs(dx) > 1 ? -Math.sign(dx) : dx, y: Math.abs(dy) > 1 ? -Math.sign(dy) : dy, z: 0 }); },
+    };
+}

package/rules/topology.mjs

@@ -0,0 +1,22 @@
+/** Periodic coordinates. Half-period ties consistently choose the negative way. */
+export const wrapValue = (value, range) => range ? range[0] + ((value - range[0]) % (range[1] - range[0]) + range[1] - range[0]) % (range[1] - range[0]) : value;
+export const periodicDelta = (a, b, range) => range ? wrapValue(b - a, [-(range[1] - range[0]) / 2, (range[1] - range[0]) / 2]) : b - a;
+export const wrapPoint = (p, wrap) => wrap ? {x: wrapValue(p.x, wrap.x), y: wrapValue(p.y, wrap.y), z: wrapValue(p.z ?? 0, wrap.z)} : p;
+export const relativePoint = (p, at, wrap) => wrap ? {x:at.x+periodicDelta(at.x,p.x,wrap.x),y:at.y+periodicDelta(at.y,p.y,wrap.y),z:(at.z??0)+periodicDelta(at.z??0,p.z??0,wrap.z)} : p;
+export const blendPosition = (a,b,t,wrap) => ({x:wrapValue(a.x+periodicDelta(a.x,b.x,wrap?.x)*t,wrap?.x),y:wrapValue(a.y+periodicDelta(a.y,b.y,wrap?.y)*t,wrap?.y),z:wrapValue(a.z+periodicDelta(a.z,b.z,wrap?.z)*t,wrap?.z)});
+export function boundPosition(p, map, radius, height, dims) {
+  const b=map.bounds,w=map.wrap;
+  return {x:w?.x?wrapValue(p.x,w.x):Math.max(b.min.x+radius,Math.min(b.max.x-radius,p.x)),y:w?.y?wrapValue(p.y,w.y):Math.max(b.min.y+radius,Math.min(b.max.y-radius,p.y)),z:dims===3?(w?.z?wrapValue(p.z,w.z):Math.max(b.min.z,Math.min(b.max.z-height,p.z))):0};
+}
+/** Stream periodic images intersecting a query's swept bounds; callers meter each image. */
+export function* imageOffsets(bounds, wrap, p, d, radius, height, dims=3) {
+  const ranges=['x','y','z'].map(k=>{
+    if(!wrap?.[k] || k==='z'&&dims===2)return [0,0,0];
+    const period=wrap[k][1]-wrap[k][0];
+    const lo=Math.min(p[k],p[k]+d[k])-(k==='z'?0:radius),hi=Math.max(p[k],p[k]+d[k])+(k==='z'?height:radius);
+    const first=Math.ceil((lo-bounds.max[k])/period),last=Math.floor((hi-bounds.min[k])/period);
+    if(!Number.isSafeInteger(first)||!Number.isSafeInteger(last))throw new RangeError('periodic query exceeds exact integer coordinates');
+    return [first,last,period];
+  });
+  for(let x=ranges[0][0];x<=ranges[0][1];x++)for(let y=ranges[1][0];y<=ranges[1][1];y++)for(let z=ranges[2][0];z<=ranges[2][1];z++)yield {x:x*ranges[0][2],y:y*ranges[1][2],z:z*ranges[2][2]};
+}

package/rules/types.ts

@@ -24,11 +24,11 @@ export interface RaySnapshot {sweep(body:{pos:Point;grounded?:boolean},delta:Poi
 export interface RayQueries { rays(options?:RayOptions):RaySnapshot; ray(from: Point, direction: Point, max: number, options?: RayOptions): RayHit | undefined; rayAll(from: Point, direction: Point, max: number, options?: RayOptions): readonly RayHit[] }
 export interface EffectAudience { readonly to?: string | readonly string[]; readonly within?: number }
 export type Area = { sphere: { at: Point; r: number } } | { box: { min: Point; max: Point } } | { cone: { at: Point; dir: Point; r: number; angle: number } };
-export interface MapView { readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
+export interface MapView { tile(x:number,y:number):number; distance(flow:string,x:number,y:number):number; flow(name:string,x:number,y:number):Vec3|undefined; readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
 export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
 export interface Round { readonly n: number; readonly phase: 'live' | 'over'; readonly endsAt: number }
 export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
-  readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
+  readonly tune: ReadonlyState<T>; readonly map: MapView & (Room extends true ? {replace(data:Record<string,unknown>):void} : {}); readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
   readonly shared: Room extends true ? S : ReadonlyState<S>;
   readonly round: Round & (Room extends true ? { end(): void; restart(): void } : {});
   /** Budget units the running handler may still spend (0.46.3). */