@homie-rocks/studio 0.45.2 → 0.46.0

package/lib/template-history.json

@@ -2649,6 +2649,90 @@
      }
     }
    }
+  },
+  "0.45.3": {
+   "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)": "214aa46eb3a895d5",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "159151b8861fc051",
+     "## 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": "c48971c1437414c2",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "2cdd530e48170bfd"
+      }
+     }
+    }
+   }
+  },
+  "0.46.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)": "214aa46eb3a895d5",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "159151b8861fc051",
+     "## 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": "c48971c1437414c2",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "2cdd530e48170bfd"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -2106,7 +2106,9 @@ from outside the studio run on its server.
 The Table writes the whole room to its SQLite `save` table in one synchronous transaction:
 entities, motion, shared state, rounds, seats and their tokens, pending events, timers and
 inputs, RNG state, tick, epoch, state hash and build hash. Saves larger than 2 MB use several
-rows in that transaction. The default interval is `room.durability.movementSeconds: 1`;
+rows in that transaction. The default interval is `room.durability.movementSeconds: 1`
+(30 for a `lifetime: "persistent"` world, which writes its `durable` fields to a journal the moment they change and
+saves the rest on this interval);
 round end, `world.finish()` and pause save immediately. Both elapsed ticks and elapsed wall
 time bound the interval, including ticks that catch up after a delay. Cloudflare's output
 gate holds outgoing frames until preceding writes are confirmed.

package/netplay/netplay.ts

@@ -2395,6 +2395,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         return;
       }
       case 'state': if (typeof m['k'] === 'string') applyState(m['k'], m['d']); return;
+      case 'probe': if (typeof m.n === 'string') raw({t:'probeAck',n:m.n}); return;
       case 'pong': return onPong(m);
       case 'announce': {
         if (typeof m['id'] !== 'string') return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.45.2",
+  "version": "0.46.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

@@ -1,12 +1,13 @@
 import { castTerrain } from './terrain.ts';
+import { castTerrain as legacyTerrain } from './terrain-legacy.ts';
 import { nearbyMap } from './map-index.ts';
 /** Upright 3D collision. Positions are feet; a rounded box is a box plus a sphere.
  * Capsules are a vertical segment plus a sphere. No engine-specific maths or time.
  */
-import { charge } from './guard.ts';
+import { charge, G } from './guard.ts';
 import type { Vec3, MapBox, MapCircle, MapHeightTile } from './rules.ts';
 
-export interface BodyShape { shape: string; radius: number; height: number }
+export interface BodyShape { shape: string; radius: number; height: number; terrain?: 'exact' }
 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 {
@@ -14,7 +15,7 @@ export interface Map3 {
   bounds: MapBox; boxes: readonly MapBox[]; circles: readonly MapCircle[];
   heightTiles?: readonly MapHeightTile[];
   spheres?: readonly MapCircle[];
-  capsules?: readonly (MapCircle & { height: number })[];
+  capsules?: readonly (MapCircle & { height: number; terrain?: 'exact' })[];
 }
 const EPS = 1e-7;
 const point = (x: number, y: number, z: number): {x: number; y: number; z: number} => ({ x, y, z });
@@ -33,8 +34,15 @@ function separation(a: Solid, b: Solid, d: Vec3, t: number): Vec3 {
 /** Continuous convex cast: each separating plane gives a lower bound on impact.
  * Every iteration is charged, and a fixed cap bounds grazing contacts as well.
  */
-export function castSolid(a: Solid, d: Vec3, b: Solid): Hit3 | null {
+export function castSolid(a: Solid, d: Vec3, b: Solid, includeInside = false): Hit3 | null {
   charge(30);
+  if (includeInside) {
+    const gap = separation(a, b, d, 0);
+    const sq = gap.x*gap.x + gap.y*gap.y + gap.z*gap.z;
+    const radius=a.r+b.r;
+    const inside = radius > 0 ? sq < radius*radius : a.max.x > b.min.x && a.min.x < b.max.x && a.max.y > b.min.y && a.min.y < b.max.y && a.max.z > b.min.z && a.min.z < b.max.z;
+    if (inside) {const length = Math.sqrt(d.x*d.x+d.y*d.y+d.z*d.z)||1; return {t:0,nx:-d.x/length,ny:-d.y/length,nz:-d.z/length};}
+  }
   let t = 0;
   const r = a.r + b.r;
   let normal = point(0, 0, 0);
@@ -94,12 +102,27 @@ function castHeightTile(tile: MapHeightTile, p: Vec3, d: Vec3): Hit3 | null {
   return best;
 }
 
-export function castMap3(map: Map3, p: Vec3, d: Vec3, body: BodyShape): Hit3 | null {
+let memoEpoch = -1;
+let castMemo = new WeakMap<object, Map<string, Hit3 | null>>();
+export function castMap3(map: Map3, p: Vec3, d: Vec3, body: BodyShape, hits?: Hit3[], includeInside = false): Hit3 | null {
+  // Exact casts can reuse identical immutable-scene queries within one handler.
+  // The epoch resets at every authority handler, including after restore.
+  if(body.terrain !== 'exact' || hits || !Number.isFinite(G.left)) return castMap3Uncached(map,p,d,body,hits,includeInside);
+  if(memoEpoch!==G.queryEpoch){memoEpoch=G.queryEpoch;castMemo=new WeakMap();}
+  charge(16);
+  let rows=castMemo.get(map);if(!rows){rows=new Map();castMemo.set(map,rows);}
+  const key=[p.x,p.y,p.z,d.x,d.y,d.z,body.shape,body.radius,body.height,includeInside].join(',');
+  if(rows.has(key))return rows.get(key)!;
+  const hit=castMap3Uncached(map,p,d,body,hits,includeInside);
+  if(rows.size<512)rows.set(key,hit);
+  return hit;
+}
+function castMap3Uncached(map: Map3, p: Vec3, d: Vec3, body: BodyShape, hits?: Hit3[], includeInside = false): Hit3 | null {
   map = nearbyMap(map, p, d, body.radius, body.height || body.radius * 2);
   charge(24);
   const a = solidAt(p, body), r = body.radius, height = body.height || r * 2;
   let best: Hit3 | null = null;
-  const take = (h: Hit3 | null, id?: string): void => { if (h && h.t >= 0 && h.t <= 1 && (!best || h.t < best.t)) best = id ? {...h, id} : h; };
+  const take = (h: Hit3 | null, id?: string): void => { if (h && h.t >= 0 && h.t <= 1) { const hit = id ? {...h, id} : h; if (hits) {charge(8); hits.push(hit);} if (!best || h.t < best.t) best = hit; } };
   for (const axis of ['x', 'y', 'z'] as const) {
     const low = map.bounds.min[axis] + (axis === 'z' ? 0 : r);
     const high = map.bounds.max[axis] - (axis === 'z' ? height : r);
@@ -107,12 +130,29 @@ export function castMap3(map: Map3, p: Vec3, d: Vec3, body: BodyShape): Hit3 | n
     const n = point(0, 0, 0); n[axis] = d[axis] > 0 ? -1 : 1;
     take({ t: ((d[axis] > 0 ? high : low) - p[axis]) / d[axis], nx: n.x, ny: n.y, nz: n.z });
   }
-  for (const tile of map.heightTiles ?? []) take(tile.base === undefined ? castHeightTile(tile, p, d) : castTerrain(tile, a, d));
-  for (const b of map.boxes) take(castSolid(a, d, { ...b, r: 0 }), (b as any).id);
+  const exactTerrain = body.terrain === 'exact';
+  const terrain = [...(map.heightTiles ?? [])];
+  if(exactTerrain && d.z<0){charge(terrain.length*Math.ceil(Math.log2(terrain.length+1)));terrain.sort((a,b)=>(b.at.z+Math.max(...b.heights))-(a.at.z+Math.max(...a.heights)));}
+  // Visit the nearest possible tile contacts first so later casts are shortened.
+  // All-hit queries retain authored ordering; legacy casts retain cost and behavior.
+  if(exactTerrain && (d.x||d.y) && !hits){
+    const first=(t:MapHeightTile)=>{let near=0;for(const k of ['x','y'] as const){if(d[k])near=Math.max(near,((d[k]>0?t.at[k]-r:t.at[k]+t.size[k]+r)-p[k])/d[k]);}return near;};
+    charge(terrain.length*(16+Math.ceil(Math.log2(terrain.length+1))));const order=new Map(terrain.map(t=>[t,first(t)]));terrain.sort((a,b)=>order.get(a)!-order.get(b)!);
+  }
+  for (const tile of terrain) {
+    if(exactTerrain && !hits && best?.t===0)break;
+    // Once a nearer surface is known, later solids only need to beat that time.
+    // This also bounds work on densely tessellated terrain behind the first hit.
+    const limit = exactTerrain && !hits && best ? best.t : 1;
+    const delta = limit < 1 ? point(d.x * limit, d.y * limit, d.z * limit) : d;
+    const hit = tile.base === undefined ? castHeightTile(tile, p, delta) : (exactTerrain ? castTerrain : legacyTerrain)(tile, a, delta);
+    if (hit) take({...hit, t: hit.t * limit});
+  }
+  for (const b of map.boxes) take(castSolid(a, d, { ...b, r: 0 }, includeInside), (b as any).id);
   // Legacy map circles are vertical columns in a 3D map.
-  for (const c of map.circles) take(castSolid(a, d, { min: point(c.at.x, c.at.y, map.bounds.min.z - r), max: point(c.at.x, c.at.y, map.bounds.max.z + r), r: c.r }), (c as any).id);
-  for (const s of map.spheres ?? []) take(castSolid(a, d, { min: s.at, max: s.at, r: s.r }), (s as any).id);
-  for (const c of map.capsules ?? []) take(castSolid(a, d, solidAt(c.at, { shape: 'capsule', radius: c.r, height: c.height })), (c as any).id);
+  for (const c of map.circles) take(castSolid(a, d, { min: point(c.at.x, c.at.y, map.bounds.min.z - r), max: point(c.at.x, c.at.y, map.bounds.max.z + r), r: c.r }, includeInside), (c as any).id);
+  for (const s of map.spheres ?? []) take(castSolid(a, d, { min: s.at, max: s.at, r: s.r }, includeInside), (s as any).id);
+  for (const c of map.capsules ?? []) take(castSolid(a, d, solidAt(c.at, { shape: 'capsule', radius: c.r, height: c.height }), includeInside), (c as any).id);
   return best;
 }
 export function restsOnMap(map: Map3, p: Vec3, body: BodyShape): boolean {

package/rules/core.ts

@@ -1,3 +1,5 @@
+import {routeGraph} from './navigation.ts';
+import { rayQuery, raySnapshot, type QueryTarget } from './query.ts';
 import { colliderSolid, castCollider2, colliderRow, collisionMap, collisionQueries, type CollisionRevision } from './live.ts';
 /*
  * core.ts — one room's world, stepped a tick at a time from a compiled rules module.
@@ -77,7 +79,7 @@ export const IGNORE_MAX = 16;
 export const ANSWER_MAX = 256;
 
 export type Driver = 'person' | 'bot' | 'ai';
-export interface SeatInfo { seat: number; driver: Driver; owner: string }
+export interface SeatInfo { seat: number; driver: Driver; owner: string; character?: import('./rules.ts').Character | null }
 /** One seat's step for a tick: its input values (already held to their types) and, for an owner-moved body, its claim. */
 export interface StepInput { values: Record<string, unknown>; claim?: { pos: Vec3; vel: Vec3; heading: Vec3; r: number } | null }
 export interface ResultRow { seat: number; id: string; driver: Driver; score: number; place: number }
@@ -133,7 +135,9 @@ function errorText(error: unknown): string {
 export interface SavedCore {
   v: number; tick: number; epoch: number; rng: number; nextId: number; seq: number;
   round: [number, number, number, number]; overAt: number; match: [number, number]; trips: number;
-  shared: unknown[]; policy: CorePolicy; intent?: [number, number];
+  shared: unknown[]; policy: CorePolicy; intent?: [number, number, number?];
+  collision?: [number,number];
+  history?: [number, [string, number, number, number, number][]][];
   asks: PendingAsk[];
   guideViews: [number, Record<string, unknown>][];
   ents: unknown[][]; spawns: unknown[][]; seats: [number, string, string, string | null, number][]; queue: unknown[][]; areas: unknown[][]; ops: unknown[];
@@ -159,6 +163,7 @@ export interface Core {
   round(): Extract<CoreOut, { t: 'round' }>;
   bodies(): Body[];
   /** The body in a seat, as the host runtime needs it for the input protocol. */
+  character(seat: number): import('./rules.ts').Character | null;
   bodyOf(seat: number): { id: string; kind: KindTable; r: number; away: boolean; driver: Driver } | null;
   /** What happened since the last call: rounds, effects, a changed roster, changed shared state, a new epoch, a failure. */
   drain(): CoreOut[];
@@ -179,7 +184,7 @@ export interface Core {
  * `noted`: told, as it happens, of a value the rules wrote that the runtime changed to make it fit, or dropped (pack.ts
  * `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: { 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) => 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 {
+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 {
   const dims = c.dims;
   const tickHz = c.settings.tickHz;
   const dt = 1 / tickHz;
@@ -210,6 +215,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   let restartAt = 0;
   let finishing = false;
   let endAsked = false;
+  let restartAsked = false;
   let vocabulary: Vocabulary | null = null;
   const restoredGoals = new Map<number, unknown>();
   const guideViews = new Map<number, Record<string, unknown>>();
@@ -369,6 +375,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
    * budget; and the counter and the scope are put back whatever happens. Nothing of the rules' is touched after this
    * returns.
    */
+  let dispatchDepth = 0;
   function run(kind: string, handler: string, ent: Ent | null, scope: Ctx['scope'], fn: () => void, always: boolean | 'body' = false): boolean {
     if (left <= 0) {
       cut = true;
@@ -387,7 +394,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     const E = Error as unknown as { stackTraceLimit?: number };
     const limit = E.stackTraceLimit;
     E.stackTraceLimit = 0;
-    G.left = quota;
+    G.queryEpoch++; G.left = quota;
     // The build check is told of every written value that had to be changed to fit (pack.ts), with the handler it was in.
     if (noted) G.note = (what, at, written) => noted(kind, handler, what, at, written);
     let bad = false; let thrown: unknown;
@@ -463,7 +470,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   }));
   let roundApi: Readonly<Record<string, unknown>> = Object.freeze({});
   const refreshRound = (): void => {
-    roundApi = brand(Object.freeze({ n: round.n, phase: round.phase, endsAt: round.endsAt, end: (): void => { need('room', 'world.round.end()'); endAsked = true; } }));
+    roundApi = brand(Object.freeze({ n: round.n, phase: round.phase, endsAt: round.endsAt, end: (): void => { need('room', 'world.round.end()'); endAsked = true; }, restart: (): void => { need('room', 'world.round.restart()'); restartAsked = true; } }));
   };
   refreshRound();
   /** `world.shared`: in room scope the writable face of the stored record, held to its types as it is written; everywhere else a frozen record of the same stored values. */
@@ -478,6 +485,32 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     return sharedRO;
   };
 
+  const historyTicks = Math.ceil((c.historySeconds ?? 0) * tickHz);
+  let poseHistory: [number, [string, number, number, number, number][]][] = [];
+  function rayTargets(options?: unknown): QueryTarget[] {
+    charge(8 * ents.size);
+    const targets: QueryTarget[] = [];
+    const filterKind=own(options,'kind'),filterLayer=own(options,'layer'),filterTag=own(options,'tag'),geometryOnly=own(options,'geometryOnly')===true;
+
+    const requested = own(options,'atTick');
+    if (requested !== undefined && (typeof requested !== 'number' || !Number.isFinite(requested))) throw new Error('ray.atTick is a finite simulation tick');
+    if (requested !== undefined && !historyTicks) throw new Error('ray.atTick needs room.historySeconds');
+    const allowance = cx.ent?.driver === 'person' ? Math.min(historyTicks,Math.max(0,opts.rewindTicks?.(cx.ent.seat) ?? 0)) : historyTicks;
+    const wanted = typeof requested === 'number' ? Math.max(tick-allowance,Math.min(tick,requested)) : tick;
+    let before: typeof poseHistory[number] | undefined, after: typeof poseHistory[number] | undefined;
+    if(wanted<tick)for(const frame of poseHistory){charge(2);if(frame[0]<=wanted)before=frame;if(frame[0]>=wanted){after=frame;break;}}
+    before ??= poseHistory[0];after ??= poseHistory[poseHistory.length-1];
+    for(const e of ents.values()) {
+      if(e.dead || !e.kind.body || typeof filterKind==='string'&&e.kind.name!==filterKind || geometryOnly&&!e.kind.collider || typeof filterLayer==='string'&&filterLayer!==(e.kind.query?.layer??(e.kind.collider?'geometry':'body')) || typeof filterTag==='string'&&!e.kind.query?.tags?.includes(filterTag))continue;
+      charge(64);
+      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};}}
+      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);
     const solid = solidAt(p, shape);
@@ -514,6 +547,23 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       if (cx.scope !== 'ent' && cx.scope !== 'room') throw new Error('world.send is for handlers');
       push({ due: tick + 1, to: typeof target === 'string' ? target.slice(0, 24) : '', kind: 'ev', ev: ev as string, data: shapeData(c.events, ev, 'the event', data), at: tick });
     },
+    dispatch: (target: unknown, ev: unknown, data?: unknown): boolean => {
+      charge(SEND);
+      if (cx.scope !== 'ent' && cx.scope !== 'room') throw new Error('world.dispatch is for handlers');
+      if (dispatchDepth >= 8) throw new Error('world.dispatch permits at most eight nested deliveries');
+      const payload = shapeData(c.events, ev, 'the event', data);
+      const e = typeof target === 'string' ? ents.get(target) : undefined;
+      const fn = e && typeof ev === 'string' ? e.kind.on[ev] : undefined;
+      if (!e || e.dead || !fn) return false;
+      // Synchronous delivery shares the caller's remaining quota. Each handler
+      // still writes only its own entity, and collection settlement stays scoped.
+      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);
+      try { fn(world,e.self,payload); }
+      finally { try { settle(); } finally { cx=parent; touched=parentTouched; G.note=note; dispatchDepth--; } }
+      return true;
+    },
     sendRoom: (ev: unknown, data?: unknown): void => {
       charge(SEND);
       if (cx.scope !== 'ent' && cx.scope !== 'room') throw new Error('world.sendRoom is for handlers');
@@ -608,7 +658,8 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       charge(cost);
       return Object.freeze(found.map(viewOf));
     },
-    ray: (from: unknown, direction: unknown, max: unknown): unknown => {
+    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];
       // 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');
@@ -630,6 +681,14 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       if (!best) return undefined;
       return Object.freeze({ ...(best.id ? { entity: best.id } : {}), at: V({ x: p.x + d.x * far * best.t, y: p.y + d.y * far * best.t, z: 0 }), normal: V({ x: best.nx, y: best.ny, z: 0 }), dist: far * best.t });
     },
+    route: (graph: unknown, from: unknown, to: unknown, options?: unknown) => {
+      const radius=own(options,'radius')??.5,height=own(options,'height')??1.8;
+      if(typeof radius!=='number'||!Number.isFinite(radius)||radius<0||radius>100||typeof height!=='number'||!Number.isFinite(height)||height<0||height>200)throw new Error('route radius/height are finite body dimensions');
+      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),
     sweep: (self: unknown, delta: unknown, o?: unknown): unknown => {
       const e = mine(self, 'world.sweep');
       charge(20 + 4 * ents.size);
@@ -688,13 +747,19 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   Object.freeze(world);
 
   const hasColliders = c.kinds.some(k => k.collider);
-  const collisionState = (): CollisionRevision => [tick, tick + 1, [...ents.values()].flatMap(e => {
-    if (e.dead || !e.kind.collider || !e.kind.body) return [];
-    const row = colliderRow(e.id, e.pos, e.kind.body, e.kind.collider, e.f);
-    return row ? [row] : [];
-  })];
+  let collisionPrevious: CollisionRevision | null = null, collisionText = '';
+  const collisionState = (): CollisionRevision => {
+    const rows = [...ents.values()].flatMap(e => {
+      if (e.dead || !e.kind.collider || !e.kind.body) return [];
+      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];}
+    return collisionPrevious;
+  };
   let moveGeometry = c.map as import('./math.ts').MapShapes;
-  const queries = collisionQueries(() => moveGeometry, () => moveShape, dims);
+  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 }));
   let moveShape = { shape: 'sphere', radius: 0, height: 0 };
@@ -774,7 +839,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     return rows;
   }
   function joinBody(info: SeatInfo): Ent | null {
-    const player = Object.freeze({ seat: info.seat, driver: info.driver, owner: info.owner });
+    const player = Object.freeze({ seat: info.seat, driver: info.driver, owner: info.owner, ...(info.character !== undefined ? { character: deepFreeze(info.character) } : {}) });
     let made: Ent | null = null;
     run('room', 'join', null, 'join', () => {
       // What room.join returns is read by its own data properties, and its fields are charged before they are held to their shapes.
@@ -800,6 +865,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     } else {
       if (e) {
         if (e.kind.on.leave) run(e.kind.name, 'on.leave', e, 'ent', () => e.kind.on.leave(world, e.self, Object.freeze({})));
+        opts.characterSaved?.(e.seat, JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })));
         e.dead = true; ents.delete(e.id);
       }
       seats.delete(s.seat);
@@ -833,13 +899,19 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
         // The seat changed hands without a goodbye: its old holder has left.
         if (s && s.driver !== 'bot') { leaveBody(s); s = seats.get(info.seat); }
         let bot: Ent | null = s && s.id ? ents.get(s.id) ?? null : null;
-        if (!bot && playerBodies().length >= c.bots) {
+        const previousBot = bot;
+        if (!bot && playerBodies().length >= c.bots || bot?.kind.player?.takeover) {
           // A person who joins a full room takes over a bot's body: the bot in the highest seat.
-          for (const e of playerBodies()) if (e.driver === 'bot' && (!bot || e.seat > bot.seat)) bot = e;
+          const priority = (e: Ent): number => e.kind.player?.takeover ? Number(e.f[e.kind.player.takeover]) : 0;
+          for (const e of playerBodies()) if (e.driver === 'bot' && (!bot || priority(e) > priority(bot) || (priority(e) === priority(bot) && e.seat > bot.seat))) bot = e;
         }
         if (bot) {
           const e = bot;
           seats.delete(e.seat);
+          if (previousBot && previousBot !== e) {
+            previousBot.seat = e.seat;
+            seats.set(previousBot.seat, {seat:previousBot.seat, driver:'bot', owner:'', id:previousBot.id, away:false});
+          }
           e.goal = null; e.seat = info.seat; e.driver = info.driver; e.owner = info.owner; e.away = false; e.r = (e.r + 1) & 0xffff; e.allow = 0;
           seats.set(info.seat, { seat: info.seat, driver: info.driver, owner: info.owner, id: e.id, away: false });
           out.push({ t: 'seats' });
@@ -882,6 +954,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       const seat = seats.get(e.seat);
       if (seat) leaveBody(seat);
     }
+    poseHistory = [];
     round = { n: round.n + 1, phase: 'live', endsAt: c.rounds && c.rounds.seconds > 0 ? tick + ticks(c.rounds.seconds) : 0, startedAt: tick };
     overAt = 0;
     refreshRound();
@@ -904,9 +977,10 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       if (tick < restartAt) return;
       startMatch();
       // Seats stay through a finished match: every holder's body is made again, as if it had just joined.
-      for (const s of [...seats.values()]) { seats.delete(s.seat); if (s.driver !== 'bot') ops.push({ op: 'join', info: { seat: s.seat, driver: s.driver, owner: s.owner } }, ...(s.away ? [{ op: 'away' as const, seat: s.seat, away: true }] : [])); }
+      for (const s of [...seats.values()]) { seats.delete(s.seat); if (s.driver !== 'bot') ops.push({ op: 'join', info: { seat: s.seat, driver: s.driver, owner: s.owner, ...(opts.characterForSeat ? { character: opts.characterForSeat(s.seat) } : {}) } }, ...(s.away ? [{ op: 'away' as const, seat: s.seat, away: true }] : [])); }
       return;
     }
+    if (restartAsked) { restartAsked = false; endAsked = false; startRound(); return; }
     if (round.phase === 'live' && (endAsked || (round.endsAt > 0 && tick >= round.endsAt))) endRound();
     endAsked = false;
     if (overAt && tick >= overAt + 2) {
@@ -918,9 +992,12 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     } else if (round.phase === 'over' && !overAt && tick >= round.endsAt) startRound();
   }
   function finishMatch(): void {
-    finishing = false;
+    finishing = false; restartAsked = false;
     out.push({ t: 'round', n: round.n, phase: 'over', endsAt: tick + Math.max(3, ticks(c.rounds ? c.rounds.breakSeconds : 0)), startedAt: round.startedAt, results: results() });
-    for (const e of ents.values()) e.dead = true;
+    for (const e of ents.values()) {
+      if (e.kind.player) opts.characterSaved?.(e.seat, JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })));
+      e.dead = true;
+    }
     ents.clear(); spawns = []; queue = []; pendingAsks = []; areas = []; fx = [];
     for (const s of seats.values()) s.id = null;
     shared = initFields(c.shared, dims); sharedChanged();
@@ -1014,12 +1091,13 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
         const body = k.body as NonNullable<KindTable['body']>;
         let claim: StepInput['claim'] = null;
         if (k.player) {
-          const driven = (e.driver === 'person' || (e.driver === 'ai' && inputs.has(e.seat))) && !e.away;
+          const permitted = !k.player.control || Boolean(e.m[k.player.control]);
+          const driven = permitted && (e.driver === 'person' || (e.driver === 'ai' && inputs.has(e.seat))) && !e.away;
           if (driven) {
             const s = inputs.get(e.seat);
             e.input = Object.freeze(s ? coerceFields(k.input, s.values, dims) : initFields(k.input, dims));
             claim = s?.claim ?? null;
-          } else if (k.think && (e.driver !== 'person' || k.player.away === 'think')) {
+          } else if (k.think && (!permitted || e.driver !== 'person' || k.player.away === 'think')) {
             // `think` returns the step. It is held to the declared input inside the handler's own try and budget; a `think` that throws leaves the input neutral.
             let stepIn: Record<string, unknown> | null = null;
             run(k.name, 'think', e, 'ent', () => {
@@ -1068,7 +1146,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
         naming('body', 'pos'); e.pos = clampIn(V(own(b, 'pos')), body.radius, body.height || 2 * body.radius); naming('body', 'vel'); e.vel = V(own(b, 'vel')); naming('body', 'heading'); e.heading = dir(own(b, 'heading'), dims); naming();
         G.note = null;
         e.grounded = own(b, 'grounded') === true;
-        if (beforeMove) opts.moved!(k.name, tick, e.input, beforeMove, { pos: e.pos, vel: e.vel, heading: e.heading, grounded: e.grounded, motion: { ...e.m } }, moveGeometry);
+        if (beforeMove) opts.moved!(k.name, tick, e.input, beforeMove, { pos: e.pos, vel: e.vel, heading: e.heading, grounded: e.grounded, motion: { ...e.m } }, moveGeometry, e.id);
       }
       // Phase 2: for every entity, its commands and then its tick, starting from a different entity each tick.
       const list = [...ents.values()];
@@ -1109,6 +1187,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       areas = [];
       if (finishing) finishMatch();
     }
+    if(historyTicks){const rows:[string,number,number,number,number][]=[];for(const e of ents.values())if(e.kind.body&&!e.kind.collider&&!e.dead)rows.push([e.id,e.pos.x,e.pos.y,e.pos.z,e.r]);left-=16*rows.length;poseHistory.push([tick,rows]);while(poseHistory.length>historyTicks+1)poseHistory.shift();}
     if (fx.length) { out.push({ t: 'fx', tick, list: fx }); fx = []; }
     if (sharedDirty) { sharedDirty = false; out.push({ t: 'shared' }); }
     stats.tickUnits = c.settings.budget.tick - left;
@@ -1142,7 +1221,9 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   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,
-      shared: packFields(c.shared, shared, dims), policy: { ...policy }, intent: [endAsked ? 1 : 0, finishing ? 1 : 0], asks: pendingAsks, guideViews: [...guideViews],
+      ...(hasColliders?{collision:collisionState().slice(0,2) as [number,number]}:{}),
+      ...(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),
       seats: [...seats.values()].map((s) => [s.seat, s.driver, s.owner, s.id, s.away ? 1 : 0]),
       queue: queue.map((q) => [q.due, q.from, q.fromId, q.seq, q.to, q.kind, q.ev, q.data, q.at, q.builtIn ? 1 : 0]),
@@ -1159,7 +1240,8 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       check(Array.isArray(value) && JSON.stringify(value) === JSON.stringify(packFields(list, unpackFields(list, value, dims), dims)));
     };
     check(r.v === SAVE_REVISION);
-    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'].includes(k)));
+    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)));
     const askNames = new Set();
     check(Array.isArray(r.asks));
     for (const a of r.asks) {
@@ -1175,7 +1257,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       check(Array.isArray(row) && row.length === 2 && uint(row[0]) && row[0] < c.seats && !views.has(row[0])); views.add(row[0]);
       check(JSON.stringify(row[1]) === JSON.stringify(coerceFields(c.view, row[1], dims)));
     }
-    check(r.intent === undefined || Array.isArray(r.intent) && r.intent.length === 2 && r.intent.every(bit));
+    check(r.intent === undefined || Array.isArray(r.intent) && (r.intent.length === 2 || r.intent.length === 3) && r.intent.every(bit));
     for (const v of [r.tick, r.epoch, r.rng, r.nextId, r.seq, r.overAt, r.trips]) check(uint(v));
     check(r.tick < 0xffffffff);
     check(r.rng <= 4294967295 && r.epoch > 0 && r.nextId > 0 && r.seq > 0);
@@ -1284,10 +1366,16 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   if (r) {
     if (r.v !== SAVE_REVISION) throw new Error('this save was written by another version of the runtime');
     validateSave(r);
+    if(historyTicks){
+      if(!Array.isArray(r.history)||r.history.length>historyTicks+1)throw new Error('saved query history is invalid');
+      let previous=-1;
+      for(const frame of r.history){if(!Array.isArray(frame)||frame.length!==2||!Number.isInteger(frame[0])||frame[0]<=previous||frame[0]>r.tick||frame[0]<r.tick-historyTicks||!Array.isArray(frame[1])||frame[1].length>ENTITY_MAX)throw new Error('saved query history is invalid');previous=frame[0];const ids=new Set<string>();for(const p of frame[1]){if(!Array.isArray(p)||p.length!==5||typeof p[0]!=='string'||p[0].length>24||ids.has(p[0])||!p.slice(1,4).every(v=>typeof v==='number'&&Number.isFinite(v))||!Number.isInteger(p[4])||p[4]<0||p[4]>65535)throw new Error('saved query history is invalid');ids.add(p[0]);}}
+      poseHistory=r.history.map(([at,rows])=>[at,rows.map(row=>[...row])]);
+    }
     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');
     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;
+    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] };
     refreshRound();
     shared = unpackFields(c.shared, r.shared, dims); sharedChanged();
@@ -1304,6 +1392,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     });
     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();
   } else startMatch();
 
   function decisionResult(value: unknown): Record<string, unknown> {
@@ -1372,7 +1461,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       if (!floorCall && value) guideViews.set(seat, value);
       return value;
     },
-    seatJoin: (info) => { ops.push({ op: 'join', info: { seat: info.seat, driver: info.driver, owner: String(info.owner ?? '').slice(0, 128) } }); },
+    seatJoin: (info) => { ops.push({ op: 'join', info: { seat: info.seat, driver: info.driver, owner: String(info.owner ?? '').slice(0, 128), ...(info.character !== undefined ? { character: info.character } : {}) } }); },
     seatAway: (seat, away) => { ops.push({ op: 'away', seat, away }); },
     seatLeave: (seat) => { ops.push({ op: 'leave', seat }); },
     setPolicy: (p) => { policy = normalizeCorePolicy(p); },
@@ -1393,6 +1482,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       return [[round.n, round.phase === 'live' ? 1 : 0, round.endsAt], list, ...(collision ? [collision] : [])];
     },
     shared: () => packFields(c.shared, shared, dims),
+    character: (seat) => { const e = playerBodies().find(e => e.seat === seat); return e ? JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })) : null; },
     bodies: () => playerBodies().map((e) => ({ seat: e.seat, id: e.id, kind: e.kind.name, driver: e.driver, owner: e.owner, away: e.away, score: e.kind.score ? Number(e.f[e.kind.score]) || 0 : 0, r: e.r })),
     bodyOf: (seat) => { const s = seats.get(seat); const e = s?.id ? ents.get(s.id) : null; return e ? { id: e.id, kind: e.kind, r: e.r, away: e.away, driver: e.driver } : null; },
     drain: () => { const o = out; out = []; return o; },

package/rules/guard.ts

@@ -37,7 +37,7 @@ export const refusedName = (k: string): boolean => REFUSED_NAMES.has(k) || k.sta
  * of the rules that ran last: the guarded module sets them as it goes, and the runtime reads them when a handler throws.
  * `note` is the build check's listener for a written value that had to be changed to fit (pack.ts); a room has none.
  */
-export const G = { left: Infinity, file: '', line: 0, note: null as null | ((what: string, at: string, written: string) => void) };
+export const G = { queryEpoch: 0, left: Infinity, file: '', line: 0, note: null as null | ((what: string, at: string, written: string) => void) };
 /** The line a guarded call is on, set again after its arguments ran (they may have called into another file). */
 export function l(file: string, line: number): number { G.file = file; G.line = line; return line; }