@homie-rocks/studio 0.46.6 → 0.47.0

package/CHANGELOG.md

@@ -17,9 +17,52 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.47.0] - 2026-10-13
+
+**Plugin 0.47.0** · Wrapped worlds and generated collision maps.
+
+Games can wrap across map edges and replace seeded tile levels during play, with the same collision geometry in server rules and prediction.
+
+### Added
+
+- Maps may opt into wrapping independently on x, y and z with `wrap: {x:true}`;
+  periods come from bounds. Bodies, sweeps, rays, overlaps, support, near/box queries,
+  area events, ranged effects, spatial delivery, rewind and view interpolation use
+  periodic geometry. Crossing an edge wraps rather than clamps. Sweeps/rays retain
+  their supplied direction and pay for each periodic image they visit.
+- Room handlers can call `world.map.replace(data)`. A replacement is validated,
+  indexed and activated atomically at the next tick, preserving bounds and wrapping.
+  Compact current/pending revisions are saved and sent once per collision revision;
+  local prediction replays the same compiled map by activation tick.
+- Maps accept row-major `tiles` with width, height, size, optional origin and solid
+  height. Nonzero cells compile to indexed horizontal runs. Rules and movement can
+  query `map.tile(x,y)`; views read `room.map.tiles`.
+- Named multi-source cardinal `tiles.flows` bake during map compilation. Rules and
+  movement use constant-work `map.distance(name,x,y)` and `map.flow(name,x,y)`.
+  The standalone rules runtime ships the nav package's new `Flow.js` baker, checked
+  against its source in the release gate. Generation, copying, indexing and baking
+  are charged to the rules handler; ordinary static-map budget charges are unchanged.
+- Seeded virtual-time release cases cover two-view seam crossing in 2D/3D and
+  generated-map collision, mid-round regeneration and restore, including 300 ms
+  delay and 12% loss. Geometry and navigation tests cover periodic casts,
+  multi-period movement, atomic failure and independently checked shortest paths.
+  Eight-player generation/restore replays also match every save and snapshot
+  across Node, Chrome and workerd for 240 seeded ticks.
+
+### Fixed
+
+- Handlers reached synchronously by `world.dispatch` now report their coverage to
+  the build checker, including failures, without opening a second handler budget.
+- The rewrite guide specifies named helper re-exports (`export *` is refused), and
+  the rules guide explains that mandatory spawn fields precede deferred `arrive`.
+
+This release covers wrapped worlds and generated levels. Arbitrary triangle-mesh
+collision, the measured Rapier-versus-kernel decision, first-class integration
+substeps, and the assisted rewrite command remain follow-up work.
+
 ## [0.46.6] - 2026-10-11
 
-**Plugin 0.46.6** · Big rooms: what one room carries, measured.
+**Plugin 0.46.6** · Big rooms: what one room carries, measured. · [release-2026-10-11-studio-0.46.6](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-11-studio-0.46.6)
 
 What one room object carries on Cloudflare, measured in six trials and stated: with a light game at 20 ticks a second, 300 players with margin, 600 at the edge, 800 to 1,000 only by luck.
 

package/guides/game/REWRITE.md

@@ -17,7 +17,8 @@ Read RULES.md before starting.
    An old file named rules.ts may already export pure helpers that tests import.
    Preserve that public test API and every existing test file byte-for-byte,
    including imports. Re-export the old helpers from rules.ts if extracted into
-   another module; do not redirect tests to that module. Record test-file hashes
+   another module with named exports (`export { helper } from './helper'`);
+   `export *` is refused. Do not redirect tests to that module. Record test-file hashes
    before editing and compare them at the end. The filename alone does not
    mean it is a rules-plus-view game. If tests now load toolkit TypeScript under
    Node, use a narrowly scoped TypeScript loader and keep the normal test command

package/guides/game/RULES.md

@@ -1178,3 +1178,70 @@ still snap to authority. Opt in only after measuring stop/reversal and delayed
 collision behavior for the game's mover.
 
 For multi-cast movement or scratch trajectory checks, `ctx.world.sweep(body, delta, {ground:false})` (also captured-scene `sweep`) moves and returns the same collision but leaves `body.grounded` unchanged. Use it only when your mover computes support explicitly. Omitting the option retains the existing support query and grounding behavior. This avoids paying for identical support checks after horizontal and upward probes.
+
+
+## Wrapped worlds and generated levels (0.47.0)
+
+Declare wrapping in the map, independently per axis. The period is the bounds'
+extent; an omitted axis keeps its existing bounded behaviour:
+
+```json
+{"bounds":{"min":[0,0,0],"max":[25,25,10]},"wrap":{"x":true}}
+```
+
+Bodies and hit positions use canonical coordinates in `[min,max)`. Sweeps and rays
+follow the supplied displacement through periodic copies of the geometry; they can
+cross more than one period and pay for each visited image. Near/box queries, area
+events, effect ranges, spatial delivery, rewind and drawing interpolation use the
+short way around. Exactly half a period chooses the negative direction. A renderer
+can read `room.map.wrap.x` (the pair `[min,max]`) to draw copies at the viewport's
+edges. The server does not duplicate entities. In a maze with one tunnel, keep
+solid border cells on every other row; wrapping itself is per axis, not per row.
+
+For a generated maze, replace the room's current map in `room.start` or a room
+handler. Build its data using the rules' seeded random source, then publish once:
+
+```ts
+world.map.replace({
+  bounds: { min: [0, 0], max: [25, 25] },
+  wrap: { x: true },
+  tiles: { width: 25, height: 25, size: 1, data: cells,
+    flows: { exit: [312] } },
+  spots: { start: [[12.5, 19.5]] },
+});
+```
+
+`replace` preserves the original bounds and wrapping. It validates, bakes cardinal
+navigation fields and compiles the spatial index before publishing anything. A
+failed bake leaves the previous revision intact. The last successful replacement
+in a tick becomes current at the next tick; all bodies use the same revision.
+The compact map data and activation tick travel with collision revisions and saves,
+including both current and pending maps. Prediction replays against that tick's
+compiled geometry. Late knowledge is corrected by the normal reconciliation path.
+
+Tiles are row-major integers: zero is open, nonzero is solid. `at` defaults to
+`[0,0,0]`, `size` and `solidHeight` to 1. Horizontal runs become indexed boxes,
+including in 3D. On a wrapped axis the grid must span the full map. Authored boxes,
+round shapes, terrain and spots can be included in the same replacement. The view
+reads `room.map.tiles`; rules and movement read `world.map.tile(x,y)` and
+`ctx.map.tile(x,y)`. Cell coordinates are integers, not metres. Outside an unwrapped
+grid is solid. A custom tile mover may read these cells instead of using sweeps.
+
+`flows` names lists of open destination cell indices. `map.distance(name,x,y)` gives
+cardinal hops to the nearest destination, or -1 when unreachable/unknown;
+`map.flow(name,x,y)` gives the next unit direction, zero at a destination, or
+undefined when unreachable/unknown. Each lookup is constant work (4 or 8 budget
+units). Baking uses `@homie-rocks/nav`'s shared cardinal flow implementation;
+left/up/right/down resolves ties, including tunnels. Change destinations by
+publishing new flow declarations with the map. This is a bake, not an unmetered
+path search: budget for every field and regenerate only when its goals change.
+
+Room replacement charges copying, grid scanning, index construction and each flow
+bake to the calling handler. Snapshots charge for the compact data. Existing static
+maps need no replacement and retain their previous budget charges. A few thousand
+cells regenerated a few times a round belong in one map revision; live collider
+entities remain suitable for independently moving doors, cover and platforms.
+
+`spawn` exposes a new entity before its deferred `on.arrive` handler. Pass every
+field that must be valid immediately in the spawn data; use `arrive` for subsequent
+work, not for mandatory initialization.

package/guides/game/SKILL.md

@@ -75,6 +75,12 @@ Cloudflare or physical-phone capacity guarantees.
 
 ## Write and change rules plus view
 
+For wrapping worlds or generated levels, use the map's opt-in `wrap` and room-scoped
+`world.map.replace` APIs described in RULES.md's **Wrapped worlds and generated levels**.
+Prefer one indexed map revision for a generated maze; keep independently moving
+doors and platforms as live colliders. Generation and navigation baking spend the
+room handler's budget.
+
 **Read [RULES.md](RULES.md) before writing code.** All five starters use this contract.
 Work in few, large edits: read each source file once, decide its changes, then
 make every change it needs in ONE file_edit with an edits list. Build after each

package/lib/rules-check-worker.mjs

@@ -1,3 +1,4 @@
+import { boundPosition } from '../rules/topology.mjs';
 /**
  * The generated play of a rules game, in a worker thread of its own (rules-check.mjs starts it).
  *
@@ -353,7 +354,7 @@ function play(c, companions, allow) {
         error => { fault ??= `${siteOf(name, 'move')} ${name}.move: prediction failed: ${error.message}.${when()}`; });
       units += result.used;
       const r = kind.body.radius, height = kind.body.height || 2 * r, bounds = c.map.bounds;
-      result.pos = L.P.vec3({ x: Math.max(bounds.min.x + r, Math.min(bounds.max.x - r, result.pos.x)), y: Math.max(bounds.min.y + r, Math.min(bounds.max.y - r, result.pos.y)), z: c.dims === 3 ? Math.max(bounds.min.z, Math.min(bounds.max.z - height, result.pos.z)) : 0 }, c.dims);
+      result.pos = L.P.vec3(boundPosition(result.pos,geometry??c.map,r,height,c.dims),c.dims);
       delete result.used;
       if (JSON.stringify(result) !== JSON.stringify(after)) fault ??= `${siteOf(name, 'move')} ${name}.move: prediction and the server produced different bodies from the same input.${when()}`;
     }

package/lib/rules-guard.mjs

@@ -66,11 +66,11 @@ export const REFUSED_NAMES = ['constructor', 'prototype', '__proto__', 'stack',
 /** The names JavaScript calls by itself to turn an object into a number or a text: no function may sit under one. */
 export const HOOK_NAMES = ['valueOf', 'toString', 'toJSON'];
 /** What the host runtime's own objects offer: `world`, `ctx`, the round, the map (rules/core.ts) and `world.math` (rules/math.ts). */
-export const WORLD_METHODS = ['ticks', 'random', 'route', 'label', 'send', 'dispatch', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'rayAll', 'rays', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'restart', 'spot', 'spots'];
+export const WORLD_METHODS = ['ticks', 'random', 'route', 'label', 'send', 'dispatch', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'rayAll', 'rays', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'restart', 'spot', 'spots', 'replace', 'tile', 'distance', 'flow'];
 export const MATH_METHODS = ['sin', 'cos', 'tan', 'atan', 'atan2', 'asin', 'acos', 'exp', 'log', 'pow', 'hypot', 'rad', 'deg', 'clamp', 'lerp', 'vec', 'add', 'sub', 'scale', 'dot', 'cross', 'len', 'dist', 'norm', 'clampLen', 'lerpVec', 'dir', 'angle'];
 const VALUE_METHODS = new Set([...ARRAY_METHODS, ...STRING_METHODS, ...MAPSET_METHODS]);
 export const MOVE_METHODS = ['support', 'overlaps'];
-const NEW_METHODS = new Set(['route','label','dispatch','rayAll','rays','restart']);
+const NEW_METHODS = new Set(['route','label','dispatch','rayAll','rays','restart','replace','tile','distance','flow']);
 const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...MATH_METHODS]);
 const refusedName = (k) => REFUSED_NAMES.includes(k) || k.startsWith('toLocale');
 /** Operators that turn each operand into a number or a text. (`+` is handled beside them; `==` and `!=` are refused.) */

package/lib/template-history.json

@@ -2901,6 +2901,48 @@
      }
     }
    }
+  },
+  "0.47.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "27881d11d3ff3803",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.46.6",
+  "version": "0.47.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/rules/collision.ts

@@ -11,6 +11,7 @@ export interface BodyShape { shape: string; radius: number; height: number; terr
 export interface Solid { min: Vec3; max: Vec3; r: number }
 export interface Hit3 { t: number; nx: number; ny: number; nz: number; id?: string }
 export interface Map3 {
+  wrap?: import('./rules.ts').MapWrap;
   staticMap?: Map3;
   bounds: MapBox; boxes: readonly MapBox[]; circles: readonly MapCircle[];
   heightTiles?: readonly MapHeightTile[];

package/rules/core.ts

@@ -1,3 +1,6 @@
+import { prepareMapReplacement, type MapRevision } from './map-state.ts';
+import { tileApi } from './tiles.ts';
+import { boundPosition, periodicDelta, relativePoint, blendPosition, wrapPoint } from './topology.mjs';
 import {routeGraph} from './navigation.ts';
 import { rayQuery, raySnapshot, type QueryTarget } from './query.ts';
 import { colliderSolid, castCollider2, colliderRow, collisionMap, collisionQueries, type CollisionRevision } from './live.ts';
@@ -141,6 +144,7 @@ export interface SavedCore {
   round: [number, number, number, number]; overAt: number; match: [number, number]; trips: number;
   shared: unknown[]; policy: CorePolicy; intent?: [number, number, number?];
   collision?: [number,number];
+  maps?: {current:MapRevision|null;pending:MapRevision|null};
   history?: [number, [string, number, number, number, number][]][];
   asks: PendingAsk[];
   guideViews: [number, Record<string, unknown>][];
@@ -191,6 +195,9 @@ export interface Core {
  * `Adjusted`; also `effect`, `think` and `decision`): the handler, what was done, the field's name and what was written.
  */
 export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number) => import('./rules.ts').Character | null | undefined; characterSaved?: (seat: number, character: import('./rules.ts').Character) => void; rewindTicks?: (seat: number)=>number; label?: (seat:number,driver:Driver)=>string; moved?: (kind: string, tick: number, input: Readonly<Record<string, unknown>>, before: import('./pack.ts').MoveBody, after: import('./pack.ts').MoveBody, geometry: import('./math.ts').MapShapes, id: string) => void; observe?: (kind: string, handler: string, error?: string) => void; noted?: (kind: string, handler: string, what: string, at: string, written: string) => void; seed?: number; epoch?: number; restore?: SavedCore | null; restoreEpoch?: number; stage?: string; decisions?: boolean } = {}): Core {
+  let currentMap=c.map;
+  let mapRevision:MapRevision|null=null,pendingMap:MapRevision|null=null;
+  let pendingGeometry:typeof currentMap|null=null,mapCells=0,currentMapCells=0,pendingMapCells=0;
   const dims = c.dims;
   const tickHz = c.settings.tickHz;
   const dt = 1 / tickHz;
@@ -356,7 +363,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     naming(kind.name, 'fields'); const f = coerceFields(kind.fields, init.fields, dims);
     naming(kind.name, 'motion'); const m = coerceFields(kind.motion, init.motion, dims); naming();
     const e: Ent = {
-      id: `e${n.toString(36)}`, n, kind, pos: clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), vel: ZERO, heading: init.heading === undefined ? AHEAD : dir(init.heading, dims), grounded: dims === 2 || restsOnMap(c.map, clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), kind.body ?? { shape: 'sphere', radius: 0, height: 0 }),
+      id: `e${n.toString(36)}`, n, kind, pos: clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), vel: ZERO, heading: init.heading === undefined ? AHEAD : dir(init.heading, dims), grounded: dims === 2 || restsOnMap(currentMap, clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), kind.body ?? { shape: 'sphere', radius: 0, height: 0 }),
       r: 0, born: tick, arrived: false, why, dead: false,
       f, m,
       seat: player ? player.seat : -1, owner: player ? player.owner : '', driver: player ? player.driver : 'bot', away: false, goal: null,
@@ -366,10 +373,15 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     return e;
   }
   function clampIn(p: Vec3, r: number, height = 0): Vec3 {
-    const b = c.map.bounds;
-    const x = Math.max(b.min.x + r, Math.min(b.max.x - r, p.x)); const y = Math.max(b.min.y + r, Math.min(b.max.y - r, p.y));
-    const z = dims === 3 ? Math.max(b.min.z, Math.min(b.max.z - height, p.z)) : 0;
-    return x === p.x && y === p.y && z === p.z ? p : V({ x, y, z });
+    if(!currentMap.wrap){
+      const b=currentMap.bounds;
+      const x=Math.max(b.min.x+r,Math.min(b.max.x-r,p.x));
+      const y=Math.max(b.min.y+r,Math.min(b.max.y-r,p.y));
+      const z=dims===3?Math.max(b.min.z,Math.min(b.max.z-height,p.z)):0;
+      return x===p.x&&y===p.y&&z===p.z?p:V({x,y,z});
+    }
+    const at = boundPosition(p,currentMap,r,height,dims);
+    return at.x===p.x&&at.y===p.y&&at.z===p.z?p:V(at);
   }
 
   /* ---------------------------------------------------------------- running a handler under the budget */
@@ -470,9 +482,15 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     return k;
   };
   const mapApi = brand(Object.freeze({
-    name: c.map.name,
-    spot: (name: unknown): Vec3 | undefined => (typeof name === 'string' && Object.hasOwn(c.map.spots, name) ? c.map.spots[name][0] : undefined),
-    spots: (name: unknown): readonly Vec3[] => (typeof name === 'string' && Object.hasOwn(c.map.spots, name) ? c.map.spots[name] : NO_SPOTS),
+    get name(){return currentMap.name;},
+    ...tileApi(()=>currentMap),
+    replace:(raw:unknown)=>{
+      need('room','world.map.replace()');
+      const prepared=prepareMapReplacement(raw,c.map);
+      pendingMap=Object.freeze([tick+1,prepared.raw]);pendingGeometry=prepared.map;pendingMapCells=prepared.cells;mapCells=currentMapCells+pendingMapCells;
+    },
+    spot: (name: unknown): Vec3 | undefined => (typeof name === 'string' && Object.hasOwn(currentMap.spots, name) ? currentMap.spots[name][0] : undefined),
+    spots: (name: unknown): readonly Vec3[] => (typeof name === 'string' && Object.hasOwn(currentMap.spots, name) ? currentMap.spots[name] : NO_SPOTS),
   }));
   let roundApi: Readonly<Record<string, unknown>> = Object.freeze({});
   const refreshRound = (): void => {
@@ -512,13 +530,13 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const row=e.kind.collider?colliderRow(e.id,e.pos,e.kind.body,e.kind.collider,e.f):null;
       if(e.kind.collider&&!row)continue;
       let at=e.pos;
-      if(!e.kind.collider && wanted<tick && before && after){charge(4*(before[1].length+after[1].length));const a=before[1].find(p=>p[0]===e.id&&p[4]===e.r),b=after[1].find(p=>p[0]===e.id&&p[4]===e.r);if(a&&b){const mix=after[0]===before[0]?0:Math.max(0,Math.min(1,(wanted-before[0])/(after[0]-before[0])));at={x:a[1]+(b[1]-a[1])*mix,y:a[2]+(b[2]-a[2])*mix,z:a[3]+(b[3]-a[3])*mix};}}
+      if(!e.kind.collider && wanted<tick && before && after){charge(4*(before[1].length+after[1].length));const a=before[1].find(p=>p[0]===e.id&&p[4]===e.r),b=after[1].find(p=>p[0]===e.id&&p[4]===e.r);if(a&&b){const mix=after[0]===before[0]?0:Math.max(0,Math.min(1,(wanted-before[0])/(after[0]-before[0])));at=blendPosition({x:a[1],y:a[2],z:a[3]},{x:b[1],y:b[2],z:b[3]},mix,currentMap.wrap);}}
       targets.push({id:e.id,kind:e.kind.name,query:e.kind.query,fields:e.f,geometry:Boolean(row),solid:row?colliderSolid(row):solidAt(at,e.kind.body),at});
     }
     return targets;
   }
   function cast3(p: Vec3, d: Vec3, shape: BodyShape, ignored: Set<string>): Hit3 | null {
-    let best = castMap3(c.map, p, d, shape);
+    let best = castMap3(currentMap, p, d, shape);
     const solid = solidAt(p, shape);
     for (const other of ents.values()) {
       if (!other.kind.body || ignored.has(other.id)) continue;
@@ -568,8 +586,16 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const parent = cx, parentTouched = touched, note = G.note;
       cx = {scope:'ent',ent:e}; touched = []; dispatchDepth++;
       if (noted) G.note = (what, at, written) => noted(e.kind.name, `on.${String(ev)}`, what, at, written);
+      let failure: unknown;
       try { fn(world,e.self,payload); }
-      finally { try { settle(); } finally { cx=parent; touched=parentTouched; G.note=note; dispatchDepth--; } }
+      catch(error) { failure=error; throw error; }
+      finally {
+        try { settle(); } catch(error) { failure=error; throw error; }
+        finally {
+          cx=parent; touched=parentTouched; G.note=note; dispatchDepth--;
+          opts.observe?.(e.kind.name, `on.${String(ev)}`, failure===undefined?undefined:errorText(failure));
+        }
+      }
       return true;
     },
     sendRoom: (ev: unknown, data?: unknown): void => {
@@ -651,7 +677,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       e.pos = clampIn(V(at), e.kind.body?.radius ?? 0, e.kind.body ? e.kind.body.height || 2 * e.kind.body.radius : 0);
       e.vel = vel !== undefined ? V(vel) : ZERO;
       if (heading !== undefined) e.heading = dir(heading, dims);
-      e.grounded = dims === 2 || restsOnMap(c.map, e.pos, e.kind.body ?? { shape: 'sphere', radius: 0, height: 0 });
+      e.grounded = dims === 2 || restsOnMap(currentMap, e.pos, e.kind.body ?? { shape: 'sphere', radius: 0, height: 0 });
       e.r = (e.r + 1) & 0xffff;
       e.allow = 0;
     },
@@ -662,8 +688,8 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       let cost = 0;
       for (const e of ents.values()) {
         if (k && e.kind !== k) continue;
-        const dx = e.pos.x - p.x; const dy = e.pos.y - p.y;
-        const dz = dims === 3 ? e.pos.z - p.z : 0;
+        const dx = periodicDelta(p.x,e.pos.x,currentMap.wrap?.x); const dy = periodicDelta(p.y,e.pos.y,currentMap.wrap?.y);
+        const dz = dims === 3 ? periodicDelta(p.z,e.pos.z,currentMap.wrap?.z) : 0;
         const d2 = dx * dx + dy * dy + dz * dz;
         if (d2 <= R * R) { found.push({ d: d2, e }); cost += viewCost.get(e.kind) as number; }
       }
@@ -678,12 +704,13 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       if (max.x - min.x > 2 * REACH_M || max.y - min.y > 2 * REACH_M || dims === 3 && max.z - min.z > 2 * REACH_M) throw new Error(`world.inBox reaches ${REACH_M} m from its centre at most`);
       const found: Ent[] = [];
       let cost = 0;
-      for (const e of ents.values()) if ((!k || e.kind === k) && e.pos.x >= min.x && e.pos.x <= max.x && e.pos.y >= min.y && e.pos.y <= max.y && (dims === 2 || e.pos.z >= min.z && e.pos.z <= max.z)) { found.push(e); cost += viewCost.get(e.kind) as number; }
+      const centre={x:(min.x+max.x)/2,y:(min.y+max.y)/2,z:(min.z+max.z)/2};
+      for (const e of ents.values()) {const p=relativePoint(e.pos,centre,currentMap.wrap);if ((!k || e.kind === k) && p.x >= min.x && p.x <= max.x && p.y >= min.y && p.y <= max.y && (dims === 2 || p.z >= min.z && p.z <= max.z)) { found.push(e); cost += viewCost.get(e.kind) as number; }}
       charge(cost);
       return Object.freeze(found.map(viewOf));
     },
     ray: (from: unknown, direction: unknown, max: unknown, options?: unknown): unknown => {
-      if (options !== undefined) return rayQuery(c.map, rayTargets(options), dims, from, direction, max, options, cx.ent?.id)[0];
+      if (options !== undefined || currentMap.wrap) return rayQuery(currentMap, rayTargets(options), dims, from, direction, max, options, cx.ent?.id)[0];
       // Charged before the cast, for every shape it may test: the map's, and every entity in the room.
       charge(20 + 4 * ents.size);
       const p = V(from); const d = dir(direction, dims); const far = reach(max, 'world.ray');
@@ -692,7 +719,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
         const hit = cast3(p, delta, { shape: 'sphere', radius: 0, height: 0 }, new Set(cx.ent ? [cx.ent.id] : []));
         return hit ? Object.freeze({ ...(hit.id ? { entity: hit.id } : {}), at: V({ x: p.x + delta.x * hit.t, y: p.y + delta.y * hit.t, z: p.z + delta.z * hit.t }), normal: V({ x: hit.nx, y: hit.ny, z: hit.nz }), dist: far * hit.t }) : undefined;
       }
-      const cast = castMap(c.map, p.x, p.y, d.x * far, d.y * far, 0);
+      const cast = castMap(currentMap, p.x, p.y, d.x * far, d.y * far, 0);
       let best: Hit | null = cast.hit;
       for (const e of ents.values()) {
         if (!e.kind.body || e === cx.ent) continue;
@@ -711,12 +738,19 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const named=typeof graph==='string';if(named&&!Object.hasOwn(c.navigation,graph))throw new Error('unknown navigation graph');return routeGraph(named?c.navigation[graph]:graph,from,to,rayTargets({geometryOnly:true}).map(t=>t.solid),radius,height,named);
     },
     label: (id: unknown): string => {charge(20);const e=typeof id==='string'?ents.get(id):undefined;if(!e?.kind.player)return '';return String(opts.label?.(e.seat,e.driver)??`Player ${e.seat+1}`).slice(0,40);},
-    rays: (options?: unknown): unknown => raySnapshot(c.map,rayTargets(options),dims,options,cx.ent?.id),
-    rayAll: (from: unknown, direction: unknown, max: unknown, options?: unknown): unknown => rayQuery(c.map, rayTargets(options), dims, from, direction, max, options, cx.ent?.id, true),
+    rays: (options?: unknown): unknown => raySnapshot(currentMap,rayTargets(options),dims,options,cx.ent?.id),
+    rayAll: (from: unknown, direction: unknown, max: unknown, options?: unknown): unknown => rayQuery(currentMap, rayTargets(options), dims, from, direction, max, options, cx.ent?.id, true),
     sweep: (self: unknown, delta: unknown, o?: unknown): unknown => {
       const e = mine(self, 'world.sweep');
       charge(20 + 4 * ents.size);
       const d = V(delta);
+      if(currentMap.wrap){
+        const list=own(o,'ignore'),ignore:string[]=[];
+        if(Array.isArray(list))for(let i=0;i<list.length&&i<IGNORE_MAX;i++){const id=own(list,i);if(typeof id==='string')ignore.push(id);}
+        const scene=raySnapshot(currentMap,rayTargets(undefined),dims,{radius:e.kind.body?.radius??0,height:e.kind.body?.height||2*(e.kind.body?.radius??0),shape:e.kind.body?.shape==='circle'?'sphere':e.kind.body?.shape??'sphere',ignore},e.id);
+        const body={pos:e.pos,grounded:e.grounded};const hit=scene.sweep(body,d);
+        e.pos=V(wrapPoint(body.pos,currentMap.wrap));e.grounded=body.grounded;return hit;
+      }
       const radius = e.kind.body?.radius ?? 0;
       // The ids to pass through: the first few of a list, read as plain texts. A longer list is not searched once for every entity.
       const list = own(o, 'ignore');
@@ -733,7 +767,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
         e.grounded = Boolean(support && support.nz > 0.5);
         return hit ? Object.freeze({ ...(hit.id ? { entity: hit.id } : {}), at: e.pos, normal: V({ x: hit.nx, y: hit.ny, z: hit.nz }) }) : undefined;
       }
-      const cast = castMap(c.map, e.pos.x, e.pos.y, d.x, d.y, radius);
+      const cast = castMap(currentMap, e.pos.x, e.pos.y, d.x, d.y, radius);
       let best: Hit | null = cast.hit;
       for (const other of ents.values()) {
         if (other === e || !other.kind.body || ignore.has(other.id)) continue;
@@ -778,14 +812,15 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const row = colliderRow(e.id,e.pos,e.kind.body,e.kind.collider,e.f,e.kind.name,e.kind.query);
       return row ? [row] : [];
     });
-    const text = JSON.stringify(rows);
-    if (!collisionPrevious || text !== collisionText) {collisionText=text;collisionPrevious=[...(collisionPrevious ? [tick,tick+1] : opts.restore?.collision ?? [tick,tick+1]) as [number,number],rows];}
+    const metadata={...(currentMap.wrap?{wrap:currentMap.wrap}:{}),...((pendingMap??mapRevision)?{map:pendingMap??mapRevision,...(pendingMap&&mapRevision?{previousMap:mapRevision}:{})}:{})};
+    const text = JSON.stringify(Object.keys(metadata).length ? [rows,metadata] : rows);
+    if (!collisionPrevious || text !== collisionText) {collisionText=text;collisionPrevious=[...(collisionPrevious ? [tick,tick+1] : opts.restore?.collision ?? [tick,tick+1]) as [number,number],rows,...(Object.keys(metadata).length?[metadata]:[])];}
     return collisionPrevious;
   };
-  let moveGeometry = c.map as import('./math.ts').MapShapes;
+  let moveGeometry = currentMap as import('./math.ts').MapShapes;
   const queries = collisionQueries(() => moveGeometry, () => moveShape, dims, () => cx.ent?.id);
   const moveWorld = brand(Object.freeze(queries));
-  const moveMap = brand(Object.freeze({ name: c.map.name, spot: mapApi.spot, spots: mapApi.spots, ...queries }));
+  const moveMap = brand(Object.freeze({ get name(){return currentMap.name;}, spot: mapApi.spot, spots: mapApi.spots, ...tileApi(()=>currentMap), ...queries }));
   let moveShape = { shape: 'sphere', radius: 0, height: 0 };
   const moveCtx = brand({} as Record<string, unknown>);
   for (const [name, get] of Object.entries({ tick: () => tick, dt: () => dt, tune: () => c.publicTune, math: () => math, map: () => moveMap, world: () => moveWorld })) Object.defineProperty(moveCtx, name, { get, enumerable: true });
@@ -1037,6 +1072,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   /* ---------------------------------------------------------------- one tick */
 
   function inArea(a: any, p: Vec3): boolean {
+    if(currentMap.wrap) p = relativePoint(p, a.k === 'b' ? {x:(a.min.x+a.max.x)/2,y:(a.min.y+a.max.y)/2,z:(a.min.z+a.max.z)/2} : a.at, currentMap.wrap);
     if (a.k === 'b') return p.x >= a.min.x && p.x <= a.max.x && p.y >= a.min.y && p.y <= a.max.y && (dims === 2 || p.z >= a.min.z && p.z <= a.max.z);
     const dx = p.x - a.at.x; const dy = p.y - a.at.y;
     const dz = dims === 3 ? p.z - a.at.z : 0;
@@ -1049,6 +1085,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   }
   function step(inputs: ReadonlyMap<number, StepInput> = new Map(), guides?: () => void): void {
     tick = (tick + 1) >>> 0;
+    if(pendingMap&&pendingMap[0]<=tick){currentMap=pendingGeometry!;mapRevision=pendingMap;currentMapCells=pendingMapCells;mapCells=currentMapCells;pendingMapCells=0;pendingMap=null;pendingGeometry=null;moveGeometry=currentMap;}
     // The tick pays first for the state it sends: what the last snapshot packed. A room that holds more than a tick can send has nothing left for its handlers, and ends as any room does whose budget trips on every tick.
     left = c.settings.budget.tick - SNAP * snapCells;
     cut = false; stopped = false; threw = null;
@@ -1107,7 +1144,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       }
       guides?.();
       // All movers see the same world, independent of entity iteration order.
-      if (hasColliders) { left -= 64 * ents.size; moveGeometry = collisionMap(c.map, collisionState()[2]); }
+      if (hasColliders) { left -= 64 * ents.size; moveGeometry = collisionMap(currentMap, collisionState()[2]); }
       // Phase 1: one input step and `move` for every body.
       for (const e of [...ents.values()]) {
         if (e.dead || !e.kind.body) continue;
@@ -1140,7 +1177,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
             // Owner movement: the browser says where its body is, and the server holds the claim to maxSpeed.
             e.allow = Math.min(e.allow + body.maxSpeed * dt * 1.02, body.maxSpeed * 0.25 + 0.05);
             if (claim && claim.r === e.r) {
-              const dx = claim.pos.x - e.pos.x; const dy = claim.pos.y - e.pos.y;
+              const dx = periodicDelta(e.pos.x,claim.pos.x,currentMap.wrap?.x); const dy = periodicDelta(e.pos.y,claim.pos.y,currentMap.wrap?.y);
               const dist = Math.sqrt(dx * dx + dy * dy);
               const go = Math.min(dist, e.allow);
               // The browser ran the game's own `move` and came further than `maxSpeed` allows: the body is held back.
@@ -1153,7 +1190,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
               e.grounded = dims === 2;
               // The support cast is map work even when a browser supplies the pose.
               // Keep it under the same movement quota as a server-driven body's sweep.
-              if (dims === 3) run(k.name, 'move', e, 'move', () => { e.grounded = restsOnMap(c.map, e.pos, body); }, 'body');
+              if (dims === 3) run(k.name, 'move', e, 'move', () => { e.grounded = restsOnMap(currentMap, e.pos, body); }, 'body');
             }
             continue;
           }
@@ -1245,7 +1282,8 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   function save(): SavedCore {
     return {
       v: SAVE_REVISION, tick, epoch, rng, nextId, seq, round: [round.n, round.phase === 'live' ? 1 : 0, round.endsAt, round.startedAt], overAt, match: [playing, restartAt], trips,
-      ...(hasColliders?{collision:collisionState().slice(0,2) as [number,number]}:{}),
+      ...((hasColliders||mapRevision||pendingMap)?{collision:collisionState().slice(0,2) as [number,number]}:{}),
+      ...((mapRevision||pendingMap)?{maps:{current:mapRevision,pending:pendingMap}}:{}),
       ...(historyTicks?{history:poseHistory.map(([at,rows])=>[at,rows.map(row=>[...row])] as SavedCore['history'])}:{}),
       shared: packFields(c.shared, shared, dims), policy: { ...policy }, intent: restartAsked ? [endAsked ? 1 : 0, finishing ? 1 : 0, 1] : [endAsked ? 1 : 0, finishing ? 1 : 0], asks: pendingAsks, guideViews: [...guideViews],
       ents: [...ents.values()].map(saveEnt), spawns: spawns.map(saveEnt),
@@ -1264,8 +1302,12 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       check(Array.isArray(value) && JSON.stringify(value) === JSON.stringify(packFields(list, unpackFields(list, value, dims), dims)));
     };
     check(r.v === SAVE_REVISION);
+    if(r.maps!==undefined){
+      check(r.maps&&Object.keys(r.maps).length===2&&'current' in r.maps&&'pending' in r.maps&&Object.keys(r.maps).every(k=>k==='current'||k==='pending'));
+      for(const [name,value] of Object.entries(r.maps)){if(value===null)continue;check(Array.isArray(value)&&value.length===2&&uint(value[0])&&(name==='pending'?value[0]===r.tick+1:value[0]<=r.tick));prepareMapReplacement(value[1],c.map);}
+    }
     if(r.collision!==undefined)check(Array.isArray(r.collision)&&r.collision.length===2&&uint(r.collision[0])&&uint(r.collision[1])&&r.collision[0]<=r.tick&&r.collision[1]===r.collision[0]+1);
-    check(Object.keys(r).every(k => ['v', 'tick', 'epoch', 'rng', 'nextId', 'seq', 'round', 'overAt', 'match', 'trips', 'shared', 'policy', 'intent', 'asks', 'guideViews', 'ents', 'spawns', 'seats', 'queue', 'areas', 'ops', 'history', 'collision'].includes(k)));
+    check(Object.keys(r).every(k => ['v', 'tick', 'epoch', 'rng', 'nextId', 'seq', 'round', 'overAt', 'match', 'trips', 'shared', 'policy', 'intent', 'asks', 'guideViews', 'ents', 'spawns', 'seats', 'queue', 'areas', 'ops', 'history', 'collision', 'maps'].includes(k)));
     const askNames = new Set();
     check(Array.isArray(r.asks));
     for (const a of r.asks) {
@@ -1311,7 +1353,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       for (const i of [7, 8, 9]) check(JSON.stringify(w[i]) === JSON.stringify(packVec(unpackVec(w[i], 3), 3)));
       const goal = w[15] as any;
       if (goal !== null) check(goal && typeof goal === 'object' && !Array.isArray(goal) && Object.keys(goal).every(k => ['goal', 'args', 'from', 'at', 'asked', 'state'].includes(k)) && typeof goal.goal === 'string' && goal.args && typeof goal.args === 'object' && !Array.isArray(goal.args) && ['brain', 'floor'].includes(goal.from) && uint(goal.at) && goal.at <= r.tick && typeof goal.asked === 'boolean' && goal.state === 'active');
-      const pos = unpackVec(w[7] as number[], 3), bounds = c.map.bounds;
+      const pos = unpackVec(w[7] as number[], 3), bounds = currentMap.bounds;
       check(pos.x >= bounds.min.x && pos.x <= bounds.max.x && pos.y >= bounds.min.y && pos.y <= bounds.max.y && (dims === 3 ? pos.z >= bounds.min.z && pos.z <= bounds.max.z : pos.z === 0));
       check(Number.isInteger(w[11]) && (w[11] as number) >= -1 && (w[11] as number) < c.seats && ['person', 'bot', 'ai'].includes(w[12] as string) && typeof w[13] === 'string' && w[13].length <= 128);
       if (k.player) { check(!bodySeats.has(w[11])); bodySeats.add(w[11]); }
@@ -1398,6 +1440,12 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     }
     pendingAsks = r.asks.map(a => ({ ...a, state: deepFreeze(a.state) }));
     if ([opts.restoreEpoch].some((e) => e !== undefined && (!Number.isSafeInteger(e) || e <= 0))) throw new Error('restored epoch is invalid');
+    if(r.maps){
+      mapRevision=r.maps.current;pendingMap=r.maps.pending;
+      if(mapRevision){const p=prepareMapReplacement(mapRevision[1],c.map);mapRevision=Object.freeze([mapRevision[0],p.raw]);currentMap=p.map;currentMapCells=p.cells;mapCells=p.cells;}
+      if(pendingMap){const p=prepareMapReplacement(pendingMap[1],c.map);pendingMap=Object.freeze([pendingMap[0],p.raw]);pendingGeometry=p.map;pendingMapCells=p.cells;mapCells=currentMapCells+pendingMapCells;}
+      moveGeometry=currentMap;
+    }
     tick = r.tick; epoch = opts.restoreEpoch ?? r.epoch; rng = r.rng; nextId = r.nextId; seq = r.seq; overAt = r.overAt; playing = r.match[0]; restartAt = r.match[1]; trips = r.trips;
     endAsked = r.intent?.[0] === 1; finishing = r.intent?.[1] === 1; restartAsked = r.intent?.[2] === 1;
     round = { n: r.round[0], phase: r.round[1] === 1 ? 'live' : 'over', endsAt: r.round[2], startedAt: r.round[3] };
@@ -1416,7 +1464,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     });
     areas = r.areas.map((a: any[]) => ({ from: a[0], fromId: a[1], seq: a[2], shape: a[3], ev: a[4], data: deepFreeze(coerceFields(c.events[a[4]] ?? [], a[5], dims)) }));
     ops = r.ops as typeof ops;
-    if(hasColliders)collisionState();
+    if(hasColliders||mapRevision||pendingMap)collisionState();
   } else startMatch();
 
   function decisionResult(value: unknown): Record<string, unknown> {
@@ -1501,8 +1549,8 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       const list = [...ents.values()].map((e) => packEntity(e.kind, e, dims));
       // Include all three components of position, velocity and heading in a 3D snapshot.
       snapCells = packed.n + (dims === 3 ? 13 : 10) * list.length;
-      const collision = hasColliders ? collisionState() : null;
-      if (collision) snapCells += 3 + collision[2].length * 8;
+      const collision = hasColliders||mapRevision||pendingMap ? collisionState() : currentMap.wrap ? [0,0,[],{wrap:currentMap.wrap}] : null;
+      if (collision) snapCells += 3 + collision[2].length * 8 + mapCells;
       return [[round.n, round.phase === 'live' ? 1 : 0, round.endsAt], list, ...(collision ? [collision] : [])];
     },
     shared: () => packFields(c.shared, shared, dims),

package/rules/host.ts

@@ -1,3 +1,4 @@
+import { periodicDelta } from './topology.mjs';
 import { stageTimings } from './timing.mjs';
 /*
  * host.ts — the host runtime: a rules module playing the host's part on the wire.
@@ -675,7 +676,7 @@ export function createHost(o: HostOptions): Host {
           const watching = all.filter((_, n) => { const a = x.list[n][3]; return !a || a[0] >= 0; });
           for (const seat of present.keys()) {
             const l = bodies.get(seat);
-            const mine = !l ? watching : all.filter((_, n) => { const a = x.list[n][3]; return !a || a[1].includes(l.id) || (a[0] >= 0 && a[2] !== null && Math.hypot(a[2][0] - l.pos.x, a[2][1] - l.pos.y, a[2][2] - l.pos.z) <= a[0]); });
+            const mine = !l ? watching : all.filter((_, n) => { const a = x.list[n][3]; return !a || a[1].includes(l.id) || (a[0] >= 0 && a[2] !== null && Math.hypot(periodicDelta(l.pos.x,a[2][0],o.compiled.map.wrap?.x), periodicDelta(l.pos.y,a[2][1],o.compiled.map.wrap?.y), periodicDelta(l.pos.z,a[2][2],o.compiled.map.wrap?.z)) <= a[0]); });
             if (mine.length) o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, mine], to: seat });
           }
           if (watching.length) o.send({ t: 'ev', from: null, k: 'fx', d: [x.tick, watching], to: -1 });