@homie-rocks/studio 0.45.1 → 0.45.3

package/rules/math.ts

@@ -14,7 +14,7 @@ import { collisionQueries } from './live.ts';
  * Every call is charged 4 units to the running handler's budget (guard.ts), beside what any guarded call costs.
  * =============================================================================
  */
-import { castMap3, restsOnMap, type BodyShape } from './collision.ts';
+import { castMap3, castSolid, restsOnMap, type BodyShape } from './collision.ts';
 import { brand, charge, own, put } from './guard.ts';
 import { num } from './pack.ts';
 
@@ -237,12 +237,24 @@ function rayBounds(px: number, py: number, dx: number, dy: number, b: { min: Vec
   return best;
 }
 /** A circle (or a point, r 0) moved along d against the static map: the first thing in the way, and how many shapes were tested. */
-export function castMap(map: MapShapes, px: number, py: number, dx: number, dy: number, r: number): { hit: Hit | null; tested: number } {
+export function castMap(map: MapShapes, px: number, py: number, dx: number, dy: number, r: number, hits?: Hit[], includeInside = false, square = false): { hit: Hit | null; tested: number } {
   map = nearbyMap(map, {x:px,y:py,z:0}, {x:dx,y:dy,z:0}, r, 0, 2);
   charge(16 + 4 * (map.boxes.length + map.circles.length));
   let best: Hit | null = rayBounds(Math.max(map.bounds.min.x + r, Math.min(map.bounds.max.x - r, px)), Math.max(map.bounds.min.y + r, Math.min(map.bounds.max.y - r, py)), dx, dy, map.bounds, r);
-  for (const b of map.boxes) { const h = rayBox(px, py, dx, dy, b.min, b.max, r); if (h && (!best || h.t < best.t)) best = { ...h, id: (b as any).id }; }
-  for (const c of map.circles) { const h = rayCircle(px, py, dx, dy, c.at.x, c.at.y, c.r + r); if (h && (!best || h.t < best.t)) best = { ...h, id: (c as any).id }; }
+  if (hits && best) hits.push(best);
+  const take=(h: Hit | null,id?:string): void => {if(!h)return;const hit={...h,...(id?{id}:{})};if(hits)hits.push(hit);if(!best||h.t<best.t)best=hit;};
+  const length=Math.sqrt(dx*dx+dy*dy)||1;
+  const inside: Hit={t:0,nx:-dx/length,ny:-dy/length};
+  for (const b of map.boxes) {
+    const min=square?{x:b.min.x-r,y:b.min.y-r,z:0}:b.min,max=square?{x:b.max.x+r,y:b.max.y+r,z:0}:b.max;
+    const embedded=includeInside&&px>min.x&&px<max.x&&py>min.y&&py<max.y;
+    take(embedded?inside:rayBox(px,py,dx,dy,min,max,square?0:r),(b as {id?:string}).id);
+  }
+  for (const c of map.circles) {
+    const embedded=includeInside&&(px-c.at.x)*(px-c.at.x)+(py-c.at.y)*(py-c.at.y)<(c.r+r)*(c.r+r);
+    const h=square?castSolid({min:{x:px-r,y:py-r,z:0},max:{x:px+r,y:py+r,z:1},r:0},{x:dx,y:dy,z:0},{min:{x:c.at.x,y:c.at.y,z:-1},max:{x:c.at.x,y:c.at.y,z:2},r:c.r},includeInside):embedded?inside:rayCircle(px,py,dx,dy,c.at.x,c.at.y,c.r+r);
+    take(h,(c as {id?:string}).id);
+  }
   return { hit: best, tested: 4 + map.boxes.length + map.circles.length };
 }
 
@@ -251,7 +263,7 @@ export function castMap(map: MapShapes, px: number, py: number, dx: number, dy:
  * and a browser both move a body with this, so they agree to the last bit. Returns nothing, or `{ at, normal }`.
  * The 2D path charges 20 units and 4 per shape; 3D also charges each convex cast and terrain tile. With `dims` 2 a body always rests on the ground.
  */
-export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius: number, dims: number, shape: BodyShape = { shape: 'sphere', radius, height: 2 * radius }): unknown {
+export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius: number, dims: number, shape: BodyShape = { shape: 'sphere', radius, height: 2 * radius }, options?: unknown): unknown {
   // Charged before the cast, for every shape of the map it may test.
   charge(20);
   const fr = Math.fround;
@@ -267,7 +279,7 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
     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));
-    put(body, 'pos', at); put(body, 'grounded', restsOnMap(map, at, shape));
+    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);
@@ -285,9 +297,9 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
  * map. One function, so that the browser (view.ts) and the person the build check plays hold the same one. The
  * server's own (core.ts `moveCtx`) is made beside the rest of its world, and charges as that does.
  */
-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 }): unknown {
+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 queries = collisionQueries(() => o.geometry?.() ?? o.map, () => o.shape?.() ?? {shape: 'sphere', radius: o.radius(), height: 2 * o.radius()}, o.dims);
+  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.

package/rules/navigation.ts

@@ -0,0 +1,69 @@
+/** Deterministic routing over an authored, baked walking graph. Full searches
+ * either reach the goal or return no path; never silently truncate a route. */
+import {own,charge} from './guard.ts';
+import type {Solid} from './collision.ts';
+import {castSolid} from './collision.ts';
+export type RouteNode = readonly [number,number,number,readonly number[]];
+const graphs = new WeakMap<object,readonly RouteNode[]>();
+const incoming = new WeakMap<object,readonly (readonly number[])[]>();
+function graphOf(value: unknown, billing=true): readonly RouteNode[] {
+ if(!Array.isArray(value)||value.length>8192)throw new Error('route graph has at most 8192 nodes');
+ if(billing)charge(value.length*12);const cached=graphs.get(value);if(cached)return cached;
+ const nodes:RouteNode[]=[];
+ for(let i=0;i<value.length;i++){
+  const n=own(value,i),links=own(n,3),x=own(n,0),y=own(n,1),z=own(n,2);
+  if(![x,y,z].every(v=>typeof v==='number'&&Number.isFinite(v))||!Array.isArray(links)||links.length>16)throw new Error('route nodes are [x,y,z,links], at most 16 neighbours');
+  const adjacent:number[]=[];for(let j=0;j<links.length;j++){const id=own(links,j);if(typeof id!=='number'||!Number.isInteger(id)||id<0||id>=value.length)throw new Error('route links name graph nodes');adjacent.push(id);}
+  nodes.push(Object.freeze([x as number,y as number,z as number,Object.freeze(adjacent)]));
+ }
+ const result=Object.freeze(nodes);const reverse:number[][]=nodes.map(()=>[]);nodes.forEach((n,i)=>{for(const next of n[3])reverse[next].push(i);});incoming.set(result,reverse);if(Object.isFrozen(value)&&value.every(n=>Object.isFrozen(n)&&Object.isFrozen(own(n,3))))graphs.set(value,result);return result;
+}
+export const prepareGraph=(value:unknown):readonly RouteNode[]=>graphOf(value,false);
+export function routeGraph(value: unknown, origin: unknown, destination: unknown, solids: readonly Solid[], radius: number, height: number, prepared=false): readonly number[] {
+ const nodes=prepared?value as readonly RouteNode[]:graphOf(value);if(prepared)charge(16);
+ if(!Number.isInteger(origin)||!Number.isInteger(destination)||Number(origin)<0||Number(destination)<0||Number(origin)>=nodes.length||Number(destination)>=nodes.length)throw new Error('route endpoints name graph nodes');
+ let start=Number(origin),goal=Number(destination),end=nodes[goal];
+ const buckets=new Map<string,Solid[]>();
+ for(const solid of solids){const minX=Math.floor((solid.min.x-solid.r-radius)/4),maxX=Math.floor((solid.max.x+solid.r+radius)/4),minY=Math.floor((solid.min.y-solid.r-radius)/4),maxY=Math.floor((solid.max.y+solid.r+radius)/4);
+  if((maxX-minX+1)*(maxY-minY+1)>65536)throw new Error('route obstacle spans too many graph cells');
+  for(let x=minX;x<=maxX;x++)for(let y=minY;y<=maxY;y++){charge(2);const key=x+','+y;const rows=buckets.get(key)??[];rows.push(solid);buckets.set(key,rows);}
+ }
+ const blocked=(a:RouteNode,b:RouteNode)=>{
+  const from={min:{x:a[0]-radius,y:a[1]-radius,z:a[2]+.05},max:{x:a[0]+radius,y:a[1]+radius,z:a[2]+height},r:0},delta={x:b[0]-a[0],y:b[1]-a[1],z:b[2]-a[2]};
+  const candidates=new Set<Solid>();
+  for(let x=Math.floor(Math.min(a[0],b[0])/4);x<=Math.floor(Math.max(a[0],b[0])/4);x++)for(let y=Math.floor(Math.min(a[1],b[1])/4);y<=Math.floor(Math.max(a[1],b[1])/4);y++){charge(1);for(const solid of buckets.get(x+','+y)??[])candidates.add(solid);}
+  for(const s of candidates){charge(2);if(Math.max(a[0],b[0])+radius<s.min.x-s.r||Math.min(a[0],b[0])-radius>s.max.x+s.r||Math.max(a[1],b[1])+radius<s.min.y-s.r||Math.min(a[1],b[1])-radius>s.max.y+s.r||Math.max(a[2],b[2])+height<s.min.z-s.r||Math.min(a[2],b[2])+.05>s.max.z+s.r)continue;if(s.r===0){
+    charge(24);let near=0,far=1,hit=true;
+    for(const axis of ['x','y','z'] as const){const low=s.min[axis]-from.max[axis],high=s.max[axis]-from.min[axis],speed=delta[axis];if(!speed){if(low>=0||high<=0){hit=false;break;}}else{let a=low/speed,b=high/speed;if(a>b)[a,b]=[b,a];near=Math.max(near,a);far=Math.min(far,b);if(near>far){hit=false;break;}}}
+    if(hit&&far>=0)return true;
+   }else if(castSolid(from,delta,s,true))return true;}
+  return false;
+ };
+ const endpoint=(id:number,limit:number)=>{
+  if(!blocked(nodes[id],nodes[id]))return id;
+  const p=nodes[id];let best=-1,score=Infinity;
+  for(let i=0;i<nodes.length;i++){charge(4);const q=nodes[i],distance=Math.hypot(q[0]-p[0],q[1]-p[1]);const cost=distance+Math.abs(q[2]-p[2])*2;if(distance>limit||cost>=score||!q[3].length||blocked(q,q))continue;best=i;score=cost;}
+  return best;
+ };
+ start=endpoint(start,4);goal=endpoint(goal,Infinity);if(start<0||goal<0)return Object.freeze([]);end=nodes[goal];
+ type Entry={id:number;f:number;order:number};let sequence=0;
+ const before=(a:Entry,b:Entry)=>a.f<b.f||a.f===b.f&&a.order<b.order;
+ const push=(heap:Entry[],id:number,f:number)=>{const item={id,f,order:sequence++};let i=heap.length;heap.push(item);while(i){const p=(i-1)>>1;if(!before(item,heap[p]))break;heap[i]=heap[p];i=p;}heap[i]=item;};
+ const pop=(heap:Entry[])=>{const first=heap[0],last=heap.pop()!;if(heap.length){let i=0;while(i*2+1<heap.length){let j=i*2+1;if(j+1<heap.length&&before(heap[j+1],heap[j]))j++;if(!before(heap[j],last))break;heap[i]=heap[j];i=j;}heap[i]=last;}return first.id;};
+ const originPoint=nodes[start],potential=(id:number)=>(Math.hypot(nodes[id][0]-end[0],nodes[id][1]-end[1])-Math.hypot(nodes[id][0]-originPoint[0],nodes[id][1]-originPoint[1]))/2;
+ const heaps:Entry[][]=[[],[]],costs=[new Map([[start,0]]),new Map([[goal,0]])],parents=[new Map<number,number>(),new Map<number,number>()],closed=[new Set<number>(),new Set<number>()],reverse=incoming.get(nodes)!;
+ push(heaps[0],start,potential(start));push(heaps[1],goal,-potential(goal));let best=Infinity,meet=-1;
+ // Balanced bidirectional A*: either frontier can prove disconnection. No
+ // expansion limit, and every returned route connects the two endpoints.
+ while(heaps[0].length&&heaps[1].length){
+  if(heaps[0][0].f+heaps[1][0].f>=best)break;
+  const side=heaps[0][0].f<=heaps[1][0].f?0:1,other=1-side,current=pop(heaps[side]);charge(12);if(closed[side].has(current))continue;closed[side].add(current);
+  const cost=costs[side].get(current)!,opposite=costs[other].get(current);if(opposite!==undefined&&cost+opposite<best){best=cost+opposite;meet=current;}
+  for(const next of side?reverse[current]:nodes[current][3]){charge(4);if(closed[side].has(next))continue;const a=nodes[side?next:current],b=nodes[side?current:next];if(blocked(a,b))continue;
+   const score=cost+Math.hypot(b[0]-a[0],b[1]-a[1])+Math.max(0,b[2]-a[2])*.3;if(score>=(costs[side].get(next)??Infinity))continue;
+   costs[side].set(next,score);parents[side].set(next,current);push(heaps[side],next,score+(side?-potential(next):potential(next)));
+   const otherCost=costs[other].get(next);if(otherCost!==undefined&&score+otherCost<best){best=score+otherCost;meet=next;}
+  }
+ }
+ if(meet<0)return Object.freeze([]);const path=[meet];while(path[0]!==start)path.unshift(parents[0].get(path[0])!);while(path[path.length-1]!==goal)path.push(parents[1].get(path[path.length-1])!);charge(path.length);return Object.freeze(path);
+}

package/rules/pack.ts

@@ -21,7 +21,7 @@ import { cellsOf } from './rules.ts';
 import type { Field, FieldList, Vec3 } from './rules.ts';
 import { G, charge, keyCount, own, refusedName } from './guard.ts';
 
-const RANGE: Record<string, [number, number]> = { u8: [0, 255], u16: [0, 65535], u32: [0, 4294967295], i8: [-128, 127], i16: [-32768, 32767], i32: [-2147483648, 2147483647], tick: [0, 4294967295], ticks: [0, 4294967295] };
+const RANGE: Record<string, [number, number]> = { pulse: [0, 255], u8: [0, 255], u16: [0, 65535], u32: [0, 4294967295], i8: [-128, 127], i16: [-32768, 32767], i32: [-2147483648, 2147483647], tick: [0, 4294967295], ticks: [0, 4294967295] };
 /** `f.fix`: steps of 1/4096, to plus or minus 2^31 (a tick count with a fraction fits for the life of any room). */
 export const FIX_STEP = 4096;
 const FIX_MAX = 2147483648;
@@ -262,7 +262,7 @@ export interface MoveBody { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boole
  * `used` is the units it took. What it throws goes to `failed` (the budget's own stop too) and the body is still read.
  */
 export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number } {
-  G.left = quota;
+  G.queryEpoch++; G.left = quota;
   const bag = coerceFields(motion, body.motion, dims);
   const target: Record<string, unknown> = {};
   const work: Record<string, unknown> = {};

package/rules/query.ts

@@ -0,0 +1,103 @@
+/** 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';
+import { castMap } from './math.ts';
+import type { MapShapes } from './math.ts';
+import { castMap3, castSolid, solidAt, type Solid } from './collision.ts';
+import { RAY_REACH_M, type Vec3, type QueryDef } from './rules.ts';
+import type { RayHit } from './types.ts';
+export interface QueryTarget { at?: Vec3; id: string; kind: string; query?: QueryDef; fields: Record<string, unknown>; geometry: boolean; solid: Solid; parts?: readonly {name: string; solid: Solid}[] }
+export function rayQuery(map: MapShapes, targets: readonly QueryTarget[], dims: number, from: unknown, direction: unknown, max: unknown, options?: unknown, self?: string, all = false, includeInside=true): readonly RayHit[] {
+  charge(32 + 8 * targets.length);
+  if (typeof max !== 'number' || !Number.isFinite(max) || max < 0 || max > RAY_REACH_M) throw new Error(`ray reaches 0 to ${RAY_REACH_M} metres`);
+  const p = vec3(from, dims), d = dir(direction,dims), delta = {x:d.x*max,y:d.y*max,z:d.z*max};
+  const radiusOption=own(options,'radius'), shapeOption=own(options,'shape');
+  const radius=radiusOption===undefined?0:radiusOption;
+  if(typeof radius!=='number'||!Number.isFinite(radius)||radius<0||radius>100)throw new Error('ray.radius is 0 to 100 metres');
+  if(shapeOption!==undefined && !['sphere','box','capsule'].includes(shapeOption as string))throw new Error('ray.shape is sphere, box or capsule');
+  const heightOption=own(options,'height'),height=heightOption===undefined?2*radius:heightOption;
+  if(typeof height!=='number'||!Number.isFinite(height)||height<2*radius||height>200)throw new Error('ray.height is at least twice its radius and at most 200 metres');
+  const terrainOption=own(options,'terrain');
+  if(terrainOption!==undefined && terrainOption!=='exact')throw new Error("ray.terrain is 'exact' or omitted");
+  const shape={terrain:terrainOption as 'exact' | undefined,shape:shapeOption==='box'?'box':shapeOption==='capsule'?'capsule':'sphere',radius,height:shapeOption==='sphere'||shapeOption===undefined?2*radius:height};
+  const start={x:p.x,y:p.y,z:p.z-shape.height/2};
+  const ignore = own(options,'ignore');
+  if (ignore !== undefined && (!Array.isArray(ignore) || ignore.length > 16)) throw new Error('ray.ignore holds at most 16 entity refs');
+  const excluded = new Set<string>();
+  if (Array.isArray(ignore)) for (let i=0;i<ignore.length;i++) { const id=own(ignore,i); if(typeof id!=='string') throw new Error('ray.ignore needs entity refs'); excluded.add(id); }
+  if (self && own(options,'ignoreSelf') !== false) excluded.add(self);
+  const profile=own(options,'profile');
+  const layer=own(options,'layer'), kind=own(options,'kind'), tag=own(options,'tag');
+  for(const v of [layer,kind,tag,profile]) if(v!==undefined && (typeof v!=='string' || v.length>32)) throw new Error('ray filters are short names');
+  const where=own(options,'where');
+  if(where!==undefined && (!where || typeof where!=='object' || Array.isArray(where))) throw new Error('ray.where is a field map');
+  const keys=where ? Object.keys(where) : [];
+  if(keys.length>16) throw new Error('ray.where holds at most 16 field tests');
+  const hits: RayHit[]=[];
+  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}:{})}));
+  };
+  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) {
+    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=>{
+      charge(12);let near=0,far=1;const radius=point.r+part.solid.r;
+      for(const k of dims===3?['x','y','z'] as const:['x','y'] as const){const lo=part.solid.min[k]-point.max[k]-radius,hi=part.solid.max[k]-point.min[k]+radius,v=delta[k];if(v===0){if(lo>1e-9||hi< -1e-9)return false;}else{let a=lo/v,b=hi/v;if(a>b)[a,b]=[b,a];near=Math.max(near,a);far=Math.min(far,b);if(near>far+1e-9)return false;}}
+      return true;
+    });
+    if(!parts.length)continue;
+    let match=true;
+    for(const key of keys) {
+      charge(32); const actual=own(target.fields,key), condition=own(where,key);
+      if(condition!==null && typeof condition==='object') {
+        const operators=Object.keys(condition); if(operators.length>5)throw new Error('ray comparison holds at most five operators');
+        for(const op of operators) {
+          if(!['eq','gt','gte','lt','lte'].includes(op)) throw new Error('ray.where supports eq, gt, gte, lt, lte');
+          const n=own(condition,op);
+          if(op==='eq') {if(actual!==n)match=false;}
+          else {if(typeof n!=='number'||!Number.isFinite(n))throw new Error('ray comparison needs a finite number');if(typeof actual!=='number'|| !(op==='gt'?actual>n:op==='gte'?actual>=n:op==='lt'?actual<n:actual<=n))match=false;}
+        }
+      } else if(actual!==condition)match=false;
+    }
+    if(!match)continue;
+    for(const part of parts) {
+      const s=part.solid;
+      const h=dims===3?castSolid(point,delta,s,includeInside):castSolid(
+        {...point,min:{...point.min,z:0},max:{...point.max,z:1}}, {...delta,z:0},
+        {...s,min:{...s.min,z:-1},max:{...s.max,z:2}},includeInside);
+
+      take(h,target.id,part.name||undefined);
+    }
+  }
+  charge(hits.length * (8 + Math.ceil(Math.log2(hits.length+1))));
+  // Stable ties retain static-map order, then entity insertion order and declaration part order.
+  hits.sort((a,b)=>a.dist-b.dist);
+  return Object.freeze(all?hits:hits.slice(0,1));
+}
+export function queryParts(at: Vec3, query?: QueryDef, profile?: string): QueryTarget['parts'] {
+  const parts=profile && query?.profiles?.[profile] ? query.profiles[profile] : query?.parts;
+  if(!parts)return undefined;
+  charge(24*Object.keys(parts).length);
+  return Object.entries(parts).map(([name,p])=>({name,solid:solidAt({x:at.x+(p.offset?.x??0),y:at.y+(p.offset?.y??0),z:at.z+(p.offset?.z??0)},{shape:p.shape,radius:p.radius,height:p.height??2*p.radius})}));
+}
+
+/** A handler-local immutable query scene. Target construction is paid once;
+ * every individual ray still pays for its candidates and geometry traversal. */
+export function raySnapshot(map:MapShapes,targets:readonly QueryTarget[],dims:number,options:unknown,self?:string){
+ const policy=plainData(options??{}, {n:1024}, 6);
+ const scene=targets.map(t=>{charge(24+4*Object.keys(t.fields).length);return {...t,at:t.at?{...t.at}:undefined,fields:Object.fromEntries(Object.entries(t.fields).filter(([,v])=>typeof v==='number'||typeof v==='string'||typeof v==='boolean'))};});
+ 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 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;};
+ return brand(Object.freeze({ray,rayAll:(from:unknown,direction:unknown,max:unknown)=>rayQuery(map,scene,dims,from,direction,max,policy,self,true),sweep,support}));
+}

package/rules/rules.ts

@@ -1,4 +1,7 @@
-import { prepareTile } from './terrain.ts';
+import {prepareGraph,type RouteNode} from './navigation.ts';
+import { prepareTile as prepareExactTile } from './terrain.ts';
+import { prepareTile as prepareLegacyTile } from './terrain-legacy.ts';
+const prepareTile = (tile: MapHeightTile) => { prepareExactTile(tile); prepareLegacyTile(tile); };
 import { indexMap } from './map-index.ts';
 /*
  * rules.ts — the rules contract, version 2: what a rules module declares, and how the runtime reads it.
@@ -37,6 +40,8 @@ export const RULES_CONTRACT = 2;
 export const SAVE_REVISION = 2;
 /** How far a query, a ray or an area event reaches, in metres. */
 export const REACH_M = 64;
+/** Rays visit indexed geometry, rather than a radius-sized entity neighbourhood. */
+export const RAY_REACH_M = 10000;
 /** The most entities one room holds. A spawn past it throws in the handler that asked. */
 export const ENTITY_MAX = 2048;
 /** The current bot-fill ceiling; public admission lives in worker/seats.mjs. */
@@ -49,13 +54,14 @@ export const QUEUE_MAX = 16_384;
 
 /* ------------------------------------------------------------------ field types */
 
-export type FieldKind = 'u8' | 'u16' | 'u32' | 'i8' | 'i16' | 'i32' | 'bit' | 'fix' | 'vec3' | 'dir' | 'tick' | 'ticks' | 'ref' | 'text' | 'list' | 'map' | 'struct' | 'press';
+export type FieldKind = 'u8' | 'u16' | 'u32' | 'i8' | 'i16' | 'i32' | 'bit' | 'fix' | 'vec3' | 'dir' | 'tick' | 'ticks' | 'ref' | 'text' | 'list' | 'map' | 'struct' | 'press' | 'pulse';
 export interface Field {
   readonly t: FieldKind;
   /** The value a new entity starts with. */
   readonly init?: unknown;
   /** On one integer field of a player's body: this is the score a round's results rank by. */
   readonly score?: true;
+  readonly visibility?: 'owner' | 'server' | 'results';
   /** `text`: the most characters. `list` and `map`: the most entries. */
   readonly max?: number;
   /** `list` and `map`: what each entry is. */
@@ -63,11 +69,11 @@ export interface Field {
   /** `struct`: its fields, in order. */
   readonly fields?: Readonly<Record<string, Field>>;
 }
-export interface FieldOptions { init?: unknown; score?: boolean }
+export interface FieldOptions { init?: unknown; score?: boolean; visibility?: 'owner' | 'server' | 'results' }
 export type Fields = Readonly<Record<string, Field>>;
 
 const made = (t: FieldKind, o: FieldOptions | undefined, extra: Partial<Field> = {}): Field =>
-  Object.freeze({ t, ...extra, ...(o && o.init !== undefined ? { init: o.init } : {}), ...(o && o.score === true ? { score: true as const } : {}) });
+  Object.freeze({ t, ...extra, ...(o?.visibility ? {visibility:o.visibility} : {}), ...(o && o.init !== undefined ? { init: o.init } : {}), ...(o && o.score === true ? { score: true as const } : {}) });
 const plain = (t: FieldKind) => (o?: FieldOptions): Field => made(t, o);
 
 /**
@@ -85,6 +91,7 @@ export const f = brand(Object.freeze({
   map: (of: Field, max: number, o?: FieldOptions): Field => made('map', o, { of, max }),
   struct: (fields: Fields, o?: FieldOptions): Field => made('struct', o, { fields: Object.freeze({ ...fields }) }),
   press: (): Field => made('press', undefined),
+  pulse: (): Field => made('pulse', undefined),
 }));
 
 /**
@@ -125,16 +132,20 @@ export type Handler = (world: RuntimeWorld, self: RuntimeSelf, e?: any) => void;
 export type RoomHandler = (world: RuntimeWorld, e?: any) => void;
 export type MoveFn = (body: any, input: any, ctx: any) => void;
 
-export type ColliderDef = true | { size?: string; enabled?: string };
-export interface BodyDef { shape: 'circle' | 'sphere' | 'capsule' | 'box'; radius: number; height?: number; maxSpeed: number; sweep?: boolean; move?: 'owner' }
+export type ColliderDef = true | { size?: string; enabled?: string; fields?: readonly string[] };
+export interface HitRegion { shape: 'sphere' | 'capsule' | 'box'; radius: number; height?: number; offset?: Vec3 }
+export interface QueryDef { layer?: string; tags?: readonly string[]; parts?: Record<string, HitRegion>; profiles?: Record<string, Record<string, HitRegion>> }
+export interface BodyDef { shape: 'circle' | 'sphere' | 'capsule' | 'box'; radius: number; height?: number; maxSpeed: number; sweep?: boolean; move?: 'owner'; terrain?: 'exact' }
 export interface GuideDef { view: (world: RuntimeWorld, self: RuntimeSelf) => unknown; floor?: (world: RuntimeWorld, self: RuntimeSelf, view: any) => unknown }
+export interface RoundRecords {key:string; identity:string; eligible?:string; fields:Readonly<Record<string,string>>}
 export interface EntityDef {
-  player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot' };
+  player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot'; control?: string; takeover?: string };
   fields?: Fields;
   motion?: Fields;
   input?: Fields;
   body?: BodyDef;
   collider?: ColliderDef;
+  query?: QueryDef;
   guide?: GuideDef;
   tick?: Handler;
   think?: (world: RuntimeWorld, self: RuntimeSelf) => Record<string, unknown>;
@@ -153,11 +164,14 @@ export interface RulesDef {
   room?: {
     rounds?: { seconds: number; breakSeconds: number };
     bots?: { keep: number };
+    records?: RoundRecords;
+    historySeconds?: number;
     start?: RoomHandler;
     join?: (ctx: any, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string }) => { kind: string; at: Vec3; heading?: Vec3; fields?: Record<string, unknown>; motion?: Record<string, unknown> };
     on?: Record<string, RoomHandler>;
   };
   asks?: Record<string, AskDef>;
+  navigation?: Record<string,readonly RouteNode[]>;
   map?: string;
 }
 
@@ -184,7 +198,7 @@ export interface RoomSettings {
   view: { radiusM: number | null; precisionM?: number; nearM?: number | null; farHz?: number | null };
   durability: { movementSeconds: number };
   budget: { tick: number };
-  predict: { catchM: number | null; catchUp: number; snapM: number | null; blendMs: number; interpMs: number | null };
+  predict: { idleHold?: boolean; catchM: number | null; catchUp: number; snapM: number | null; blendMs: number; interpMs: number | null };
 }
 /**
  * The default `budget.tick`: 500,000 units at 20 ticks a second or fewer, and less at a faster rate, so a second of
@@ -238,7 +252,7 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
       view: { radiusM: r.view?.radiusM === null ? null : num('view.radiusM', r.view?.radiusM, null), ...(r.view?.precisionM !== undefined ? { precisionM: num('view.precisionM', r.view.precisionM, 0) as number } : {}), ...(r.view?.nearM !== undefined ? { nearM: num('view.nearM', r.view.nearM, null) } : {}), ...(r.view?.farHz !== undefined ? { farHz: whole('view.farHz', r.view.farHz, 1, tickHz, tickHz) } : {}) },
       durability: { movementSeconds: whole('durability.movementSeconds', r.durability?.movementSeconds, 1, 60, 1) },
       budget: { tick: Math.max(1, Math.floor(num('budget.tick', r.budget?.tick, budgetFor(tickHz)) as number)) },
-      predict: { catchM: num('predict.catchM', p.catchM, null), catchUp: num('predict.catchUp', p.catchUp, 1.25) as number, snapM: num('predict.snapM', p.snapM, null), blendMs: num('predict.blendMs', p.blendMs, 100) as number, interpMs: num('predict.interpMs', p.interpMs, null) },
+      predict: { ...(p.idleHold === true ? {idleHold:true} : {}), catchM: num('predict.catchM', p.catchM, null), catchUp: num('predict.catchUp', p.catchUp, 1.25) as number, snapM: num('predict.snapM', p.snapM, null), blendMs: num('predict.blendMs', p.blendMs, 100) as number, interpMs: num('predict.interpMs', p.interpMs, null) },
     },
     problems,
   };
@@ -321,12 +335,13 @@ export type FieldList = readonly (readonly [string, Field])[];
 export interface KindTable {
   name: string;
   index: number;
-  player: null | { away: 'neutral' | 'think'; leave: 'despawn' | 'bot' };
+  player: null | { away: 'neutral' | 'think'; leave: 'despawn' | 'bot'; control?: string; takeover?: string };
   fields: FieldList;
   motion: FieldList;
   input: FieldList;
   collider?: ColliderDef;
-  body: null | { shape: string; radius: number; height: number; maxSpeed: number; sweep: boolean; owner: boolean };
+  query?: QueryDef;
+  body: null | { shape: string; radius: number; height: number; maxSpeed: number; sweep: boolean; owner: boolean; terrain?: 'exact' };
   score: string | null;
   tick: Handler | null;
   think: EntityDef['think'] | null;
@@ -337,6 +352,7 @@ export interface KindTable {
   move: MoveFn | null;
 }
 export interface Compiled {
+  navigation: Readonly<Record<string,readonly RouteNode[]>>;
   contract: 2;
   /** `SAVE_REVISION`, so that what hashes these declarations hashes it too. */
   save: number;
@@ -349,6 +365,8 @@ export interface Compiled {
   effectNames: string[];
   shared: FieldList;
   view: FieldList;
+  records?: RoundRecords;
+  historySeconds?: number;
   rounds: { seconds: number; breakSeconds: number } | null;
   bots: number;
   start: RoomHandler | null;
@@ -371,7 +389,7 @@ export const BUILT_IN_FIELDS = Object.freeze(['id', 'kind', 'pos', 'vel', 'headi
 
 const NAME = /^[a-z][A-Za-z0-9_]{0,31}$/;
 const INTS = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32']);
-const TYPES = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32', 'bit', 'fix', 'vec3', 'dir', 'tick', 'ticks', 'ref', 'text', 'list', 'map', 'struct', 'press']);
+const TYPES = new Set(['u8', 'u16', 'u32', 'i8', 'i16', 'i32', 'bit', 'fix', 'vec3', 'dir', 'tick', 'ticks', 'ref', 'text', 'list', 'map', 'struct', 'press', 'pulse']);
 
 /**
  * One declared field, checked, and made again as the runtime's own: a frozen record of its type, its sizes and its
@@ -385,6 +403,7 @@ function cleanField(fd: unknown, where: string, inInput: boolean): Field {
   const init = own(x, 'init');
   return Object.freeze({
     t: x.t,
+    ...(x.visibility ? {visibility:x.visibility} : {}),
     ...(x.t === 'text' || x.t === 'list' || x.t === 'map' ? { max: x.max } : {}),
     ...(x.t === 'list' || x.t === 'map' ? { of: cleanField(x.of, `${where} (its entries)`, false) } : {}),
     ...(x.t === 'struct' ? { fields: Object.freeze(Object.fromEntries(Object.entries(x.fields ?? {}).map(([key, sub]) => [key, cleanField(sub, `${where}.${key}`, false)]))) } : {}),
@@ -395,8 +414,10 @@ function cleanField(fd: unknown, where: string, inInput: boolean): Field {
 function checkField(fd: unknown, where: string, inInput: boolean): void {
   const x = fd as Field;
   if (!x || typeof x !== 'object' || typeof x.t !== 'string' || !TYPES.has(x.t)) throw new Error(`${where} is not a field type: declare it with f (f.u16(), f.vec3(), f.list(f.ref(), 8)…)`);
-  if (x.t === 'press' && !inInput) throw new Error(`${where}: f.press() is for input only (a button that fires once)`);
-  if (inInput && !(INTS.has(x.t) || x.t === 'bit' || x.t === 'press' || x.t === 'fix')) throw new Error(`${where}: an input field is a whole number, f.fix(), f.bit() or f.press()`);
+  if ((x.t === 'press' || x.t === 'pulse') && !inInput) throw new Error(`${where}: f.press() is for input only (a button that fires once)`);
+  if (inInput && !(INTS.has(x.t) || x.t === 'bit' || x.t === 'press' || x.t === 'pulse' || x.t === 'fix')) throw new Error(`${where}: an input field is a whole number, f.fix(), f.bit() or f.press()`);
+  if (x.visibility !== undefined && !/^entities\.[^.]+\.fields\.[^.]+$/.test(where)) throw new Error(`${where}: visibility belongs on a top-level entity field`);
+  if (x.visibility !== undefined && (!['owner','server','results'].includes(x.visibility) || inInput)) throw new Error(`${where}: visibility is owner, server or results on state fields only`);
   if (x.t === 'text' && !(Number.isInteger(x.max) && (x.max as number) >= 1 && (x.max as number) <= 4096)) throw new Error(`${where}: f.text(max) needs its largest length, 1 to 4096 characters`);
   if (x.t === 'list' || x.t === 'map') {
     if (!(Number.isInteger(x.max) && (x.max as number) >= 1 && (x.max as number) <= 1024)) throw new Error(`${where}: a list or a map declares its largest size, 1 to 1024 entries`);
@@ -508,7 +529,10 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
       if (!p || typeof p !== 'object') throw new Error(`${at}.player is true, or { away, leave }`);
       if (p.away !== undefined && p.away !== 'neutral' && p.away !== 'think') throw new Error(`${at}.player.away is 'neutral' or 'think'`);
       if (p.leave !== undefined && p.leave !== 'despawn' && p.leave !== 'bot') throw new Error(`${at}.player.leave is 'despawn' or 'bot'`);
-      player = { away: p.away ?? 'neutral', leave: p.leave ?? 'despawn' };
+      if (p.control !== undefined && !motion.some(([key, field]) => key === p.control && field.t === 'bit')) throw new Error(`${at}.player.control names a bit in motion`);
+      if (p.takeover !== undefined && !fields.some(([key, field]) => key === p.takeover && ['fix','i8','i16','i32','u8','u16','u32'].includes(field.t))) throw new Error(`${at}.player.takeover names a numeric field`);
+      if (p.control && typeof e.think !== 'function') throw new Error(`${at}.player.control needs think`);
+      player = { away: p.away ?? 'neutral', leave: p.leave ?? 'despawn', ...(p.control ? {control:p.control}:{}), ...(p.takeover ? {takeover:p.takeover}:{}) };
       if ((player.away === 'think' || player.leave === 'bot') && typeof e.think !== 'function') throw new Error(`${at}: away: 'think' and leave: 'bot' need a think(world, self) handler to steer the body`);
     }
     let body: KindTable['body'] = null;
@@ -517,9 +541,10 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
       const shapes = dims === 2 ? ['circle'] : ['sphere', 'capsule', 'box'];
       if (!b || !shapes.includes(b.shape)) throw new Error(`${at}.body.shape is ${shapes.map((s) => `'${s}'`).join(' or ')} when space.dims is ${dims}`);
       if (typeof b.radius !== 'number' || typeof b.maxSpeed !== 'number' || !Number.isFinite(b.radius) || !Number.isFinite(b.maxSpeed) || !(b.radius > 0) || !(b.maxSpeed >= 0)) throw new Error(`${at}.body needs radius (metres) and maxSpeed (metres a second)`);
+      if (b.terrain !== undefined && b.terrain !== 'exact') throw new Error(`${at}.body.terrain is 'exact', or omitted for legacy casts`);
       if (b.move !== undefined && b.move !== 'owner') throw new Error(`${at}.body.move is 'owner', or left out`);
       if (dims === 3 && b.height !== undefined && (!Number.isFinite(b.height) || b.height <= 0 || b.shape === 'capsule' && b.height < b.radius * 2)) throw new Error(`${at}.body.height must be finite, positive and at least twice the radius for a capsule`);
-      body = { shape: b.shape, radius: b.radius, height: dims === 3 && b.shape === 'sphere' ? 2 * b.radius : typeof b.height === 'number' && b.height > 0 ? b.height : 0, maxSpeed: b.maxSpeed, sweep: b.sweep === true, owner: b.move === 'owner' };
+      body = { shape: b.shape, radius: b.radius, height: dims === 3 && b.shape === 'sphere' ? 2 * b.radius : typeof b.height === 'number' && b.height > 0 ? b.height : 0, maxSpeed: b.maxSpeed, sweep: b.sweep === true, owner: b.move === 'owner', ...(b.terrain === 'exact' ? {terrain: 'exact' as const} : {}) };
     }
     if (player && !body) throw new Error(`${at}: a player's kind needs a body`);
     const moveFn = move && typeof move[name] === 'function' ? move[name] as MoveFn : null;
@@ -535,14 +560,34 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
     if (e.collider !== undefined) {
       if (!body || player || body.owner) throw new Error(`${at}.collider needs a non-player body`);
       if (e.collider !== true) {
-        if (!e.collider || typeof e.collider !== 'object' || Object.keys(e.collider).some(k => !['size', 'enabled'].includes(k))) throw new Error(`${at}.collider is true or {size, enabled}`);
+        if (!e.collider || typeof e.collider !== 'object' || Object.keys(e.collider).some(k => !['size', 'enabled', 'fields'].includes(k))) throw new Error(`${at}.collider is true or {size, enabled}`);
+        if (e.collider.fields !== undefined && (!Array.isArray(e.collider.fields) || e.collider.fields.length > 16 || !e.collider.fields.every(name => fields.some(([n,f]) => n === name && !f.visibility && !['struct','map','list','vec3','dir'].includes(f.t))))) throw new Error(`${at}.collider.fields names at most 16 scalar fields`);
         for (const [key, type] of [['size', 'vec3'], ['enabled', 'bit']]) {
           const name = (e.collider as Record<string, unknown>)[key];
           if (name !== undefined && (typeof name !== 'string' || !fields.some(([n, f]) => n === name && f.t === type))) throw new Error(`${at}.collider.${key} must name a ${type} field`);
         }
       }
     }
-    const k: KindTable = { ...(e.collider ? { collider: e.collider } : {}), name, index: kinds.length, player, fields, motion, input, body, score: scores[0]?.[0] ?? null, tick: e.tick ?? null, think: e.think ?? null, on, commands: cmds, onRoom, guide: e.guide ?? null, move: moveFn };
+    if (e.query !== undefined) {
+      const q = e.query;
+      const word = (v: unknown): boolean => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/.test(v);
+      if (!body || !q || typeof q !== 'object' || Object.keys(q).some(k => !['layer','tags','parts','profiles'].includes(k))) throw new Error(`${at}.query needs a body and {layer, tags, parts, profiles}`);
+      if (q.layer !== undefined && !word(q.layer)) throw new Error(`${at}.query.layer is a short name`);
+      if (q.tags !== undefined && (!Array.isArray(q.tags) || q.tags.length > 16 || !q.tags.every(word))) throw new Error(`${at}.query.tags holds at most 16 short names`);
+      const groups: [string, Record<string, HitRegion>][] = [];
+      if(q.parts !== undefined) groups.push(['parts',q.parts]);
+      if(q.profiles !== undefined) {
+        if(!q.profiles || typeof q.profiles!=='object' || Array.isArray(q.profiles) || Object.keys(q.profiles).length>8 || !Object.keys(q.profiles).every(word))throw new Error(`${at}.query.profiles holds at most eight named region sets`);
+        for(const [name,parts] of Object.entries(q.profiles))groups.push([`profiles.${name}`,parts]);
+      }
+      for (const [group,parts] of groups) {
+        if (!parts || typeof parts !== 'object' || Array.isArray(parts) || Object.keys(parts).length > 16) throw new Error(`${at}.query.${group} holds at most 16 shapes`);
+        for (const [name, part] of Object.entries(parts)) {
+          if (!word(name) || !part || !['sphere','capsule','box'].includes(part.shape) || !Number.isFinite(part.radius) || part.radius <= 0 || part.radius > 10000 || part.height !== undefined && (!Number.isFinite(part.height) || part.height <= 0 || part.height > 10000 || part.shape === 'capsule' && part.height < 2*part.radius) || part.offset !== undefined && !['x','y','z'].every(k => Number.isFinite((part.offset as any)[k]) && Math.abs((part.offset as any)[k]) <= 10000)) throw new Error(`${at}.query.${group}.${name} needs a finite shape, radius, height and offset`);
+        }
+      }
+    }
+    const k: KindTable = { ...(e.query ? {query: Object.freeze(e.query)} : {}), ...(e.collider ? { collider: e.collider } : {}), name, index: kinds.length, player, fields, motion, input, body, score: scores[0]?.[0] ?? null, tick: e.tick ?? null, think: e.think ?? null, on, commands: cmds, onRoom, guide: e.guide ?? null, move: moveFn };
     kinds.push(k);
     kindOf[name] = k;
   }
@@ -570,10 +615,21 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
     if (!a.questions || typeof a.questions !== 'object') throw new Error(`asks.${key}.questions is required; for example { advance: { type: 'noul', instructions: 'Should the party advance?' } }`);
     asks[key] = { ...a, stateFields: fieldList(a.state, `asks.${key}.state`) };
   }
+  if(room.records){const rec=room.records;
+    if(!/^server:[A-Za-z0-9_.:-]{1,57}$/.test(rec.key)||!fieldList(d.shared,'shared').some(([n,f])=>n===rec.identity&&f.t==='text')||Object.keys(rec.fields).length>16)throw new Error('room.records needs a server: key, shared text identity and at most 16 fields');
+    for(const k of kinds.filter(k=>k.player)){
+      if(rec.eligible&&!k.fields.some(([n,f])=>n===rec.eligible&&f.t==='bit'))throw new Error('room.records.eligible names a player bit field');
+      for(const [name,source] of Object.entries(rec.fields))if(!/^[a-z][A-Za-z0-9_]{0,31}$/.test(name)||['id','endedAt','place','won'].includes(name)||!k.fields.some(([n,f])=>n===source&&['u8','u16','u32','i8','i16','i32','fix'].includes(f.t)))throw new Error('room.records.fields maps result names to numeric player fields');
+    }
+  }
+  if (room.historySeconds !== undefined && (typeof room.historySeconds !== 'number' || !Number.isFinite(room.historySeconds) || room.historySeconds < 0 || room.historySeconds > 2)) throw new Error('room.historySeconds is from 0 to 2');
   const seats = Math.max(1, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(Number(env.seats)) || 8));
+  const navigation:Record<string,readonly RouteNode[]> = Object.create(null);let graphNodes=0;
+  if(d.navigation){const entries=Object.entries(d.navigation);if(entries.length>8)throw new Error('navigation declares at most 8 graphs');for(const [name,graph] of entries){if(!/^[A-Za-z][A-Za-z0-9_]{0,47}$/.test(name))throw new Error('navigation graph names are identifiers up to 48 characters');navigation[name]=prepareGraph(graph);graphNodes+=navigation[name].length;if(graphNodes>8192)throw new Error('navigation declares at most 8192 nodes in total');}}
+  Object.freeze(navigation);
   return {
-    contract: RULES_CONTRACT, save: SAVE_REVISION, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
-    shared: fieldList(d.shared, 'shared'), view, rounds, bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,
+    navigation, contract: RULES_CONTRACT, save: SAVE_REVISION, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
+    shared: fieldList(d.shared, 'shared'), view, ...(room.records?{records:room.records}:{}), ...(room.historySeconds ? {historySeconds:room.historySeconds}:{}), rounds, bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,
     tune, publicTune, map, settings, seats,
   };
 }
@@ -585,21 +641,31 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
  * bundle, so none of the rules' handlers reach a browser with it.
  */
 export interface Schema {
+  records?: true;
   contract: 2;
   dims: 2 | 3;
   seats: number;
-  kinds: { name: string; player: boolean; owner: boolean; radius: number; shape?: string; height?: number; maxSpeed: number; score: string | null; fields: FieldList; motion: FieldList; input: FieldList }[];
+  kinds: { query?: QueryDef; collider?: ColliderDef; name: string; player: boolean; control?: string; owner: boolean; radius: number; shape?: string; height?: number; terrain?: 'exact'; maxSpeed: number; score: string | null; fields: FieldList; motion: FieldList; input: FieldList }[];
   effects: Record<string, FieldList>;
   effectNames: string[];
   commands: Record<string, FieldList>;
   shared: FieldList;
+  historySeconds?: number;
   rounds: { seconds: number; breakSeconds: number } | null;
   settings: RoomSettings;
 }
+function publicField(field: Field, hidden=false): Field {
+  hidden=hidden||!!field.visibility;
+  if(!hidden)return field;
+  const {init,...clean}=field;
+  if(clean.fields)clean.fields=Object.fromEntries(Object.entries(clean.fields).map(([key,value])=>[key,publicField(value,true)]));
+  if(clean.of)clean.of=publicField(clean.of,true);
+  return clean as Field;
+}
 export function schemaOf(c: Compiled): Schema {
   return {
-    contract: RULES_CONTRACT, dims: c.dims, seats: c.seats,
-    kinds: c.kinds.map((k) => ({ name: k.name, player: Boolean(k.player), owner: Boolean(k.body?.owner), radius: k.body?.radius ?? 0, ...(c.dims === 3 && k.body ? { shape: k.body.shape, height: k.body.height || 2 * k.body.radius } : {}), maxSpeed: k.body?.maxSpeed ?? 0, score: k.score, fields: k.fields, motion: k.motion, input: k.input })),
+    contract: RULES_CONTRACT, dims: c.dims, seats: c.seats, ...(c.records?{records:true as const}:{}),
+    kinds: c.kinds.map((k) => ({ ...(k.query?{query:k.query}:{}), ...(k.collider?{collider:k.collider}:{}), ...(k.body?.terrain ? {terrain:k.body.terrain} : {}), name: k.name, player: Boolean(k.player), ...(k.player?.control ? {control:k.player.control}:{}), owner: Boolean(k.body?.owner), radius: k.body?.radius ?? 0, ...(c.dims === 3 && k.body ? { shape: k.body.shape, height: k.body.height || 2 * k.body.radius } : {}), maxSpeed: k.body?.maxSpeed ?? 0, score: k.score, fields: k.fields.map(([name,field])=>[name,publicField(field)]), motion: k.motion, input: k.input })),
     effects: c.effects, effectNames: c.effectNames, commands: c.commands, shared: c.shared, rounds: c.rounds, settings: c.settings,
   };
 }