@homie-rocks/studio 0.39.0 → 0.40.0

package/rules/core.ts

@@ -38,6 +38,7 @@
  * that is held to its shape, and paid for, before the handler's budget is closed.
  * =============================================================================
  */
+import { castMap3, castSolid, restsOnMap, solidAt, type BodyShape, type Hit3 } from './collision.ts';
 import { argsWhy, type Vocabulary } from '../agents/agents.ts';
 import { BudgetError, G, brand, charge, deepFreeze, plainData } from './guard.ts';
 import { SKIN, castMap, exact, math, rayCircle, sweepMap } from './math.ts';
@@ -88,7 +89,7 @@ export type CoreOut =
   | { t: 'shared' }
   | { t: 'epoch'; epoch: number }
   | { t: 'fail'; why: 'budget'; kind: string; handler: string };
-export interface CorePolicy { reserved?: number; bots: 'fill' | 'off'; level: number; levelMax: number }
+export interface CorePolicy { kids?: boolean; levelSet?: boolean; guideLevel?: number; guideSeats?: readonly number[]; reserved?: number; bots: 'fill' | 'off'; level: number; levelMax: number }
 export interface Body { seat: number; id: string; kind: string; driver: Driver; owner: string; away: boolean; score: number; r: number }
 
 interface Ent {
@@ -178,7 +179,6 @@ export interface Core {
  * `Adjusted`; also `effect`, `think` and `decision`): the handler, what was done, the field's name and what was written.
  */
 export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: number, input: Readonly<Record<string, unknown>>, before: import('./pack.ts').MoveBody, after: import('./pack.ts').MoveBody) => 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 {
-  if (c.dims !== 2) throw new Error('this release runs rules with space.dims: 2; bodies with height (dims: 3) arrive in a later one');
   const dims = c.dims;
   const tickHz = c.settings.tickHz;
   const dt = 1 / tickHz;
@@ -212,11 +212,13 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   let vocabulary: Vocabulary | null = null;
   const restoredGoals = new Map<number, unknown>();
   const guideViews = new Map<number, Record<string, unknown>>();
+  const EMPTY_GUIDE_SEATS: readonly number[] = Object.freeze([]);
   let policy: CorePolicy = { reserved: 0, bots: 'fill', level: 3, levelMax: 5 };
   function normalizeCorePolicy(p: Partial<CorePolicy>): CorePolicy {
     const levelMax = Math.max(1, Math.min(5, Math.floor(num(own(p, 'levelMax') ?? policy.levelMax)) || 5));
+    const guideSeats = Object.freeze([...new Set(p.guideSeats ?? policy.guideSeats ?? [])].filter(seat => Number.isInteger(seat) && seat >= 0 && seat < c.seats).sort((a, b) => a - b));
     // The keys in the order the room starts with them: a save is compared byte for byte with the save of the room rebuilt from it.
-    return { reserved: Math.max(0, Math.min(c.seats - 1, Math.floor(num(own(p, 'reserved') ?? policy.reserved)) || 0)), bots: p.bots === 'off' ? 'off' : p.bots === 'fill' ? 'fill' : policy.bots, level: Math.max(1, Math.min(levelMax, Math.floor(num(own(p, 'level') ?? policy.level)) || 3)), levelMax };
+    return { reserved: Math.max(0, Math.min(c.seats - 1, Math.floor(num(own(p, 'reserved') ?? policy.reserved)) || 0)), bots: p.bots === 'off' ? 'off' : p.bots === 'fill' ? 'fill' : policy.bots, level: Math.max(1, Math.min(levelMax, Math.floor(num(own(p, 'level') ?? policy.level)) || 3)), levelMax, ...((p.kids ?? policy.kids) ? { kids: true } : {}), ...((p.levelSet ?? policy.levelSet) ? { levelSet: true } : {}), ...((p.guideLevel ?? policy.guideLevel) !== undefined ? { guideLevel: Math.max(1, Math.min(levelMax, Math.floor(num(p.guideLevel ?? policy.guideLevel)) || 3)) } : {}), ...(guideSeats.length ? { guideSeats } : {}) };
   }
   let shared: Record<string, unknown> = initFields(c.shared, dims);
   let sharedRO: Readonly<Record<string, unknown>> = Object.freeze({});
@@ -342,7 +344,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     naming(kind.name, 'fields'); const f = coerceFields(kind.fields, init.fields, dims);
     naming(kind.name, 'motion'); const m = coerceFields(kind.motion, init.motion, dims); naming();
     const e: Ent = {
-      id: `e${n.toString(36)}`, n, kind, pos: clampIn(V(at), kind.body?.radius ?? 0), vel: ZERO, heading: init.heading === undefined ? AHEAD : dir(init.heading, dims), grounded: true,
+      id: `e${n.toString(36)}`, n, kind, pos: clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), vel: ZERO, heading: init.heading === undefined ? AHEAD : dir(init.heading, dims), grounded: dims === 2 || restsOnMap(c.map, clampIn(V(at), kind.body?.radius ?? 0, kind.body ? kind.body.height || 2 * kind.body.radius : 0), kind.body ?? { shape: 'sphere', radius: 0, height: 0 }),
       r: 0, born: tick, arrived: false, why, dead: false,
       f, m,
       seat: player ? player.seat : -1, owner: player ? player.owner : '', driver: player ? player.driver : 'bot', away: false, goal: null,
@@ -351,10 +353,11 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     makeSelf(e);
     return e;
   }
-  function clampIn(p: Vec3, r: number): Vec3 {
+  function clampIn(p: Vec3, r: number, height = 0): Vec3 {
     const b = c.map.bounds;
     const x = Math.max(b.min.x + r, Math.min(b.max.x - r, p.x)); const y = Math.max(b.min.y + r, Math.min(b.max.y - r, p.y));
-    return x === p.x && y === p.y ? p : V({ x, y, z: p.z });
+    const z = dims === 3 ? Math.max(b.min.z, Math.min(b.max.z - height, p.z)) : 0;
+    return x === p.x && y === p.y && z === p.z ? p : V({ x, y, z });
   }
 
   /* ---------------------------------------------------------------- running a handler under the budget */
@@ -475,9 +478,19 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     return sharedRO;
   };
 
+  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);
+    for (const other of ents.values()) {
+      if (!other.kind.body || ignored.has(other.id)) continue;
+      const hit = castSolid(solid, d, solidAt(other.pos, other.kind.body));
+      if (hit && (!best || hit.t < best.t)) best = { ...hit, id: other.id };
+    }
+    return best;
+  }
   const world = brand({} as Record<string, unknown>);
   const getters: Record<string, () => unknown> = {
-    tick: () => tick, dt: () => dt, round: () => roundApi, shared: sharedView, level: () => policy.level, levelMax: () => policy.levelMax,
+    tick: () => tick, dt: () => dt, round: () => roundApi, shared: sharedView, level: () => policy.level, levelMax: () => policy.levelMax, guideLevel: () => policy.guideLevel ?? policy.level, guideSeats: () => policy.guideSeats ?? EMPTY_GUIDE_SEATS, kids: () => Boolean(policy.kids), levelSet: () => Boolean(policy.levelSet),
     stage: () => stage, tune: () => c.tune, math: () => math, map: () => mapApi,
   };
   for (const [name, get] of Object.entries(getters)) Object.defineProperty(world, name, { get, enumerable: true });
@@ -558,9 +571,10 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       charge(10 + 12 * COPY);
       const e = mine(self, 'world.place');
       const vel = own(o, 'vel'); const heading = own(o, 'heading');
-      e.pos = clampIn(V(at), e.kind.body?.radius ?? 0);
+      e.pos = clampIn(V(at), e.kind.body?.radius ?? 0, e.kind.body ? e.kind.body.height || 2 * e.kind.body.radius : 0);
       e.vel = vel !== undefined ? V(vel) : ZERO;
       if (heading !== undefined) e.heading = dir(heading, dims);
+      e.grounded = dims === 2 || restsOnMap(c.map, e.pos, e.kind.body ?? { shape: 'sphere', radius: 0, height: 0 });
       e.r = (e.r + 1) & 0xffff;
       e.allow = 0;
     },
@@ -572,7 +586,8 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       for (const e of ents.values()) {
         if (k && e.kind !== k) continue;
         const dx = e.pos.x - p.x; const dy = e.pos.y - p.y;
-        const d2 = dx * dx + dy * dy;
+        const dz = dims === 3 ? e.pos.z - p.z : 0;
+        const d2 = dx * dx + dy * dy + dz * dz;
         if (d2 <= R * R) { found.push({ d: d2, e }); cost += viewCost.get(e.kind) as number; }
       }
       // Sorting them and handing each out is charged before either is done.
@@ -583,10 +598,10 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     inBox: (box: unknown, kind?: unknown): readonly unknown[] => {
       charge(20 + 2 * ents.size);
       const min = V(own(box, 'min')); const max = V(own(box, 'max')); const k = kindFilter(kind);
-      if (max.x - min.x > 2 * REACH_M || max.y - min.y > 2 * REACH_M) throw new Error(`world.inBox reaches ${REACH_M} m from its centre at most`);
+      if (max.x - min.x > 2 * REACH_M || max.y - min.y > 2 * REACH_M || dims === 3 && max.z - min.z > 2 * REACH_M) throw new Error(`world.inBox reaches ${REACH_M} m from its centre at most`);
       const found: Ent[] = [];
       let cost = 0;
-      for (const e of ents.values()) if ((!k || e.kind === k) && e.pos.x >= min.x && e.pos.x <= max.x && e.pos.y >= min.y && e.pos.y <= max.y) { found.push(e); cost += viewCost.get(e.kind) as number; }
+      for (const e of ents.values()) if ((!k || e.kind === k) && e.pos.x >= min.x && e.pos.x <= max.x && e.pos.y >= min.y && e.pos.y <= max.y && (dims === 2 || e.pos.z >= min.z && e.pos.z <= max.z)) { found.push(e); cost += viewCost.get(e.kind) as number; }
       charge(cost);
       return Object.freeze(found.map(viewOf));
     },
@@ -594,6 +609,11 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       // Charged before the cast, for every shape it may test: the map's, and every entity in the room.
       charge(20 + 4 * (mapShapes + ents.size));
       const p = V(from); const d = dir(direction, dims); const far = reach(max, 'world.ray');
+      if (dims === 3) {
+        const delta = { x: d.x * far, y: d.y * far, z: d.z * far };
+        const hit = cast3(p, delta, { shape: 'sphere', radius: 0, height: 0 }, new Set(cx.ent ? [cx.ent.id] : []));
+        return hit ? Object.freeze({ ...(hit.id ? { entity: hit.id } : {}), at: V({ x: p.x + delta.x * hit.t, y: p.y + delta.y * hit.t, z: p.z + delta.z * hit.t }), normal: V({ x: hit.nx, y: hit.ny, z: hit.nz }), dist: far * hit.t }) : undefined;
+      }
       const cast = castMap(c.map, p.x, p.y, d.x * far, d.y * far, 0);
       let best: Hit | null = cast.hit;
       for (const e of ents.values()) {
@@ -609,12 +629,23 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       charge(20 + 4 * (mapShapes + ents.size));
       const d = V(delta);
       const radius = e.kind.body?.radius ?? 0;
-      const cast = castMap(c.map, e.pos.x, e.pos.y, d.x, d.y, radius);
-      let best: Hit | null = cast.hit;
       // The ids to pass through: the first few of a list, read as plain texts. A longer list is not searched once for every entity.
       const list = own(o, 'ignore');
       const ignore = new Set<string>();
       if (Array.isArray(list)) for (let i = 0; i < list.length && i < IGNORE_MAX; i += 1) { const id = own(list, i); if (typeof id === 'string') ignore.add(id); }
+      if (dims === 3) {
+        ignore.add(e.id);
+        const shape = e.kind.body ?? { shape: 'sphere', radius: 0, height: 0 };
+        const hit = cast3(e.pos, d, shape, ignore);
+        const length = Math.sqrt(d.x * d.x + d.y * d.y + d.z * d.z);
+        const t = hit ? Math.max(0, hit.t - (length > 0 ? SKIN / length : 0)) : 1;
+        e.pos = V({ x: e.pos.x + d.x * t, y: e.pos.y + d.y * t, z: e.pos.z + d.z * t });
+        const support = cast3(e.pos, { x: 0, y: 0, z: -2 * SKIN }, shape, ignore);
+        e.grounded = Boolean(support && support.nz > 0.5);
+        return hit ? Object.freeze({ ...(hit.id ? { entity: hit.id } : {}), at: e.pos, normal: V({ x: hit.nx, y: hit.ny, z: hit.nz }) }) : undefined;
+      }
+      const cast = castMap(c.map, e.pos.x, e.pos.y, d.x, d.y, radius);
+      let best: Hit | null = cast.hit;
       for (const other of ents.values()) {
         if (other === e || !other.kind.body || ignore.has(other.id)) continue;
         const h = rayCircle(e.pos.x, e.pos.y, d.x, d.y, other.pos.x, other.pos.y, other.kind.body.radius + radius);
@@ -647,8 +678,9 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   });
   Object.freeze(world);
 
-  const moveMap = brand(Object.freeze({ name: c.map.name, spot: mapApi.spot, spots: mapApi.spots, sweep: (body: unknown, delta: unknown): unknown => sweepMap(c.map, body, delta, moveRadius, dims) }));
+  const moveMap = brand(Object.freeze({ name: c.map.name, spot: mapApi.spot, spots: mapApi.spots, sweep: (body: unknown, delta: unknown): unknown => sweepMap(c.map, body, delta, moveRadius, dims, moveShape) }));
   let moveRadius = 0;
+  let moveShape = { shape: 'sphere', radius: 0, height: 0 };
   const moveCtx = brand({} as Record<string, unknown>);
   for (const [name, get] of Object.entries({ tick: () => tick, dt: () => dt, tune: () => c.publicTune, math: () => math, map: () => moveMap })) Object.defineProperty(moveCtx, name, { get, enumerable: true });
   Object.assign(moveCtx, { ticks: (seconds: unknown): number => { charge(1); return ticks(seconds); } });
@@ -887,14 +919,15 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
   /* ---------------------------------------------------------------- one tick */
 
   function inArea(a: any, p: Vec3): boolean {
-    if (a.k === 'b') return p.x >= a.min.x && p.x <= a.max.x && p.y >= a.min.y && p.y <= a.max.y;
+    if (a.k === 'b') return p.x >= a.min.x && p.x <= a.max.x && p.y >= a.min.y && p.y <= a.max.y && (dims === 2 || p.z >= a.min.z && p.z <= a.max.z);
     const dx = p.x - a.at.x; const dy = p.y - a.at.y;
-    const d2 = dx * dx + dy * dy;
+    const dz = dims === 3 ? p.z - a.at.z : 0;
+    const d2 = dx * dx + dy * dy + dz * dz;
     if (d2 > a.r * a.r) return false;
     if (a.k === 's' || d2 === 0) return true;
     const l = Math.sqrt(d2);
     // Inside the cone: the angle to its axis is at most half its opening, compared by cosine.
-    return (dx * a.dir.x + dy * a.dir.y) / l >= exact.cos(a.half);
+    return (dx * a.dir.x + dy * a.dir.y + dz * a.dir.z) / l >= exact.cos(a.half);
   }
   function step(inputs: ReadonlyMap<number, StepInput> = new Map(), guides?: () => void): void {
     tick = (tick + 1) >>> 0;
@@ -992,10 +1025,14 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
               // The browser ran the game's own `move` and came further than `maxSpeed` allows: the body is held back.
               if (go < dist) stats.held += 1;
               e.allow -= go;
-              if (dist > 0) e.pos = clampIn(V({ x: e.pos.x + (dx / dist) * go, y: e.pos.y + (dy / dist) * go, z: 0 }), body.radius);
+              e.pos = clampIn(V({ x: e.pos.x + (dist > 0 ? (dx / dist) * go : 0), y: e.pos.y + (dist > 0 ? (dy / dist) * go : 0), z: dims === 3 ? claim.pos.z : 0 }), body.radius, body.height || 2 * body.radius);
               const sp = Math.sqrt(claim.vel.x * claim.vel.x + claim.vel.y * claim.vel.y);
-              e.vel = sp > body.maxSpeed && sp > 0 ? V({ x: (claim.vel.x / sp) * body.maxSpeed, y: (claim.vel.y / sp) * body.maxSpeed, z: 0 }) : V(claim.vel);
+              e.vel = sp > body.maxSpeed && sp > 0 ? V({ x: (claim.vel.x / sp) * body.maxSpeed, y: (claim.vel.y / sp) * body.maxSpeed, z: claim.vel.z }) : V(claim.vel);
               e.heading = dir(claim.heading, dims);
+              e.grounded = dims === 2;
+              // The support cast is map work even when a browser supplies the pose.
+              // Keep it under the same movement quota as a server-driven body's sweep.
+              if (dims === 3) run(k.name, 'move', e, 'move', () => { e.grounded = restsOnMap(c.map, e.pos, body); }, 'body');
             }
             continue;
           }
@@ -1003,13 +1040,13 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
         if (!k.move) continue;
         const b = { pos: e.pos, vel: e.vel, heading: e.heading, grounded: e.grounded, motion: e.mself };
         const beforeMove = opts.moved ? { pos: e.pos, vel: e.vel, heading: e.heading, grounded: e.grounded, motion: { ...e.m } } : null;
-        moveRadius = body.radius;
+        moveRadius = body.radius; moveShape = body;
         run(k.name, 'move', e, 'move', () => (k.move as NonNullable<KindTable['move']>)(b, e.input, moveCtx), 'body');
         // The runtime rounds to 32-bit floats, here and in the browser, so both step from exactly the same numbers.
         // `b` is the runtime's own object: what `move` left in it is read by its own data properties and cannot throw.
         // (A listener hears of a position that was not a number here too, as `move`'s.)
         if (noted) G.note = (what, at, written) => noted(k.name, 'move', what, at, written);
-        naming('body', 'pos'); e.pos = clampIn(V(own(b, 'pos')), body.radius); naming('body', 'vel'); e.vel = V(own(b, 'vel')); naming('body', 'heading'); e.heading = dir(own(b, 'heading'), dims); naming();
+        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 } });
@@ -1128,7 +1165,10 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     const duration = r.round[1] === 1 ? ticks(c.rounds?.seconds ?? 0) : Math.max(3, ticks(c.rounds?.breakSeconds ?? 0));
     check(r.round[3] <= r.tick && r.round[2] <= r.tick + duration && !(r.round[1] === 1 && !duration && r.round[2] !== 0));
     check(r.policy && ['fill', 'off'].includes(r.policy.bots) && Number.isInteger(r.policy.level) && Number.isInteger(r.policy.levelMax) && r.policy.level >= 1 && r.policy.level <= r.policy.levelMax && r.policy.levelMax <= 5);
-    check(Object.keys(r.policy).every((key) => ['bots', 'level', 'levelMax', 'reserved'].includes(key)));
+    check(r.policy.guideLevel === undefined || Number.isInteger(r.policy.guideLevel) && r.policy.guideLevel >= 1 && r.policy.guideLevel <= r.policy.levelMax);
+    check(r.policy.guideSeats === undefined || Array.isArray(r.policy.guideSeats) && r.policy.guideSeats.length > 0 && r.policy.guideSeats.length <= c.seats && r.policy.guideSeats.every((seat, i, seats) => uint(seat) && seat < c.seats && (i === 0 || seat > seats[i - 1])));
+    check((r.policy.kids === undefined || r.policy.kids === true) && (r.policy.levelSet === undefined || r.policy.levelSet === true));
+    check(Object.keys(r.policy).every((key) => ['bots', 'level', 'levelMax', 'reserved', 'kids', 'levelSet', 'guideLevel', 'guideSeats'].includes(key)));
     check(r.policy.reserved === undefined || uint(r.policy.reserved) && r.policy.reserved < c.seats);
     fields(c.shared, r.shared);
     check(Array.isArray(r.ents) && Array.isArray(r.spawns) && r.ents.length + r.spawns.length <= ENTITY_MAX);
@@ -1147,7 +1187,7 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
       const goal = w[15] as any;
       if (goal !== null) check(goal && typeof goal === 'object' && !Array.isArray(goal) && Object.keys(goal).every(k => ['goal', 'args', 'from', 'at', 'asked', 'state'].includes(k)) && typeof goal.goal === 'string' && goal.args && typeof goal.args === 'object' && !Array.isArray(goal.args) && ['brain', 'floor'].includes(goal.from) && uint(goal.at) && goal.at <= r.tick && typeof goal.asked === 'boolean' && goal.state === 'active');
       const pos = unpackVec(w[7] as number[], 3), bounds = c.map.bounds;
-      check(pos.x >= bounds.min.x && pos.x <= bounds.max.x && pos.y >= bounds.min.y && pos.y <= bounds.max.y && pos.z === 0);
+      check(pos.x >= bounds.min.x && pos.x <= bounds.max.x && pos.y >= bounds.min.y && pos.y <= bounds.max.y && (dims === 3 ? pos.z >= bounds.min.z && pos.z <= bounds.max.z : pos.z === 0));
       check(Number.isInteger(w[11]) && (w[11] as number) >= -1 && (w[11] as number) < c.seats && ['person', 'bot', 'ai'].includes(w[12] as string) && typeof w[13] === 'string' && w[13].length <= 128);
       if (k.player) { check(!bodySeats.has(w[11])); bodySeats.add(w[11]); }
       fields(k.fields, w[17]); fields(k.motion, w[18]); fields(k.input, w[19]);
@@ -1327,8 +1367,8 @@ export function createCore(c: Compiled, opts: { moved?: (kind: string, tick: num
     snapshot: () => {
       packed.n = 0;
       const list = [...ents.values()].map((e) => packEntity(e.kind, e, dims));
-      // Ten values an entity for what every entity carries (its id, its place, its velocity and heading), and one for each value of its fields.
-      snapCells = packed.n + 10 * list.length;
+      // Include all three components of position, velocity and heading in a 3D snapshot.
+      snapCells = packed.n + (dims === 3 ? 13 : 10) * list.length;
       return [[round.n, round.phase === 'live' ? 1 : 0, round.endsAt], list];
     },
     shared: () => packFields(c.shared, shared, dims),

package/rules/host.ts

@@ -290,6 +290,10 @@ export function createHost(o: HostOptions): Host {
     agents.on('ask', (d) => o.send({ t: 'ev', k: 'agent:ask', d }));
   }
   function guideBeat(): void {
+    // Roles come from admitted peers and reserved server seats, never player input.
+    const guideSeats = agentSlots().filter(slot => slot.agent?.role === 'guide').map(slot => slot.slot).sort((a, b) => a - b);
+    const previous = (core.world as { guideSeats: readonly number[] }).guideSeats;
+    if (guideSeats.length !== previous.length || guideSeats.some((seat, i) => seat !== previous[i])) core.setPolicy({ guideSeats });
     if (!agents) return;
     const bodies = core.bodies();
     for (const b of bodies) {
@@ -498,7 +502,7 @@ export function createHost(o: HostOptions): Host {
             speech: raw.speech === 'off' || raw.speech === 'lines' ? raw.speech : 'game' };
           if (previous.kind !== policy.kind || previous.aiSeats !== policy.aiSeats || previous.guides !== policy.guides) rosterText = '';
         }
-        if (p) core.setPolicy({ bots: p.bots === 'off' ? 'off' : 'fill', level: num(own(own(p, 'skill'), 'level') ?? own(p, 'level')), levelMax: num(own(p, 'levelMax')), reserved: policy.kind === 'hybrid' || policy.kind === 'beginner' ? policy.aiSeats + policy.guides : 0 });
+        if (p) core.setPolicy({ kids: own(p, 'kids') === true, ...(own(p, 'level') !== undefined ? { guideLevel: num(own(p, 'level')) } : {}), levelSet: Boolean(own(p, 'by')), bots: p.bots === 'off' ? 'off' : 'fill', level: num(own(own(p, 'skill'), 'level') ?? own(p, 'level')), levelMax: num(own(p, 'levelMax')), reserved: policy.kind === 'hybrid' || policy.kind === 'beginner' ? policy.aiSeats + policy.guides : 0 });
         return;
       }
       default: return;

package/rules/math.ts

@@ -12,6 +12,7 @@
  * 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 { brand, charge, own, put } from './guard.ts';
 import { num } from './pack.ts';
 
@@ -181,7 +182,7 @@ export const exact = Object.freeze({ sin, cos, atan, atan2, exp, log, pow });
 /* ------------------------------------------------------------------ the ground plane: a point or a circle against the map */
 
 /** The shapes of a map the sweep reads (rules.ts `GameMap` has them). */
-export interface MapShapes { bounds: { min: Vec3; max: Vec3 }; boxes: readonly { min: Vec3; max: Vec3 }[]; circles: readonly { at: Vec3; r: number }[] }
+export interface MapShapes { bounds: { min: Vec3; max: Vec3 }; boxes: readonly { min: Vec3; max: Vec3 }[]; circles: readonly { at: Vec3; r: number }[]; spheres?: readonly { at: Vec3; r: number }[]; capsules?: readonly { at: Vec3; r: number; height: number }[]; heightTiles?: readonly import('./rules.ts').MapHeightTile[] }
 /** How close a swept body stops to what it hit, in metres. */
 export const SKIN = 0.001;
 
@@ -244,9 +245,9 @@ export function castMap(map: MapShapes, px: number, py: number, dx: number, dy:
 /**
  * `ctx.map.sweep(body, delta)`: move `body.pos` along `delta` and stop at the first static shape in the way. The server
  * and a browser both move a body with this, so they agree to the last bit. Returns nothing, or `{ at, normal }`.
- * Charged 20 units and 4 for each shape of the map. With `dims` 2 a body always rests on the ground.
+ * 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): unknown {
+export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius: number, dims: number, shape: BodyShape = { shape: 'sphere', radius, height: 2 * radius }): unknown {
   // Charged before the cast, for every shape of the map it may test.
   charge(20 + 4 * (4 + map.boxes.length + map.circles.length));
   const fr = Math.fround;
@@ -256,6 +257,15 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
   const pos = own(body, 'pos');
   const dx = num(own(delta, 'x')); const dy = num(own(delta, 'y'));
   const px = num(own(pos, 'x')); const py = num(own(pos, 'y'));
+  if (dims === 3) {
+    const p = v(px, py, num(own(pos, 'z'))), d = v(dx, dy, num(own(delta, 'z')));
+    const h = castMap3(map, p, d, shape);
+    const length = Math.sqrt(dx * dx + dy * dy + d.z * d.z);
+    const t = h ? Math.max(0, h.t - (length > 0 ? SKIN / length : 0)) : 1;
+    const at = v(fr(px + dx * t), fr(py + dy * t), fr(p.z + d.z * t));
+    put(body, 'pos', at); put(body, 'grounded', restsOnMap(map, at, shape));
+    return h ? Object.freeze({ at, normal: v(h.nx, h.ny, h.nz) }) : undefined;
+  }
   const { hit: h } = castMap(map, px, py, dx, dy, radius);
   put(body, 'grounded', true);
   if (!h) { put(body, 'pos', v(fr(px + dx), fr(py + dy), 0)); return undefined; }
@@ -271,12 +281,12 @@ 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; dims: number }): 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 }): unknown {
   const none = Object.freeze([]);
   return brand(Object.freeze({
     get tick() { return o.tick(); }, dt: 1 / o.tickHz, tune: o.tune, math,
     // As the server's `ctx.ticks` reads it: a plain number, or nothing.
     ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * o.tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
-    map: brand(Object.freeze({ name: o.name, spot: (name: string) => (own(o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(o.spots, name) ?? none, sweep: (body: unknown, delta: unknown) => sweepMap(o.map, body, delta, o.radius(), o.dims) })),
+    map: brand(Object.freeze({ name: o.name, spot: (name: string) => (own(o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(o.spots, name) ?? none, sweep: (body: unknown, delta: unknown) => sweepMap(o.map, body, delta, o.radius(), o.dims, o.shape?.()) })),
   }));
 }

package/rules/rules.ts

@@ -71,7 +71,7 @@ const plain = (t: FieldKind) => (o?: FieldOptions): Field => made(t, o);
 /**
  * The types of declared state. Whole numbers (`u8` to `u32`, `i8` to `i32`) are held to their range; `bit` is true or
  * false; `fix` is a fixed-point number in steps of 1/4096; `vec3` is a position or a velocity in metres; `dir` is a
- * unit vector on the ground plane; `tick` is a moment and `ticks` a length on the room's clock; `ref` is the id of an
+ * unit vector in the declared dimensions; `tick` is a moment and `ticks` a length on the room's clock; `ref` is the id of an
  * entity or a player; `text`, `list` and `map` name their largest size. `press` (in `input` only) is a button that
  * fires once.
  */
@@ -236,7 +236,8 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
 
 export interface MapBox { readonly min: Vec3; readonly max: Vec3 }
 export interface MapCircle { readonly at: Vec3; readonly r: number }
-export interface GameMap { readonly name: string; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
+export interface MapHeightTile { readonly at: Vec3; readonly size: Readonly<{ x: number; y: number }>; readonly heights: readonly [number, number, number, number] }
+export interface GameMap { readonly name: string; readonly heightTiles: readonly MapHeightTile[]; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spheres: readonly MapCircle[]; readonly capsules: readonly (MapCircle & { height: number })[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
 
 const vecOf = (a: unknown, what: string): Vec3 => {
   const p = Array.isArray(a) ? { x: a[0], y: a[1], z: a[2] ?? 0 } : a as { x?: unknown; y?: unknown; z?: unknown } | null;
@@ -247,8 +248,7 @@ const vecOf = (a: unknown, what: string): Vec3 => {
 
 /**
  * One map file (`games/<id>/map/<name>.json`), checked: `bounds` (the world's edges), `boxes` and `circles` (solid
- * shapes on the ground plane) and named `spots`. Positions are metres, `z` up. Height tiles, spheres and capsules
- * arrive with 3D bodies.
+ * shapes on the ground plane), spheres, upright capsules, height tiles and named `spots`. Positions are metres, `z` up.
  */
 export function compileMap(raw: unknown, name = 'main'): GameMap {
   const m = raw && typeof raw === 'object' ? raw as Record<string, any> : {};
@@ -256,7 +256,7 @@ export function compileMap(raw: unknown, name = 'main'): GameMap {
   if (!m.bounds) throw new Error(`${where} needs "bounds": { "min": [x, y], "max": [x, y] }, the edges of the world in metres`);
   const box = (b: any, what: string): MapBox => {
     const min = vecOf(b?.min, `${what}.min`); const max = vecOf(b?.max, `${what}.max`);
-    if (!(max.x > min.x) || !(max.y > min.y)) throw new Error(`${what}: "max" is above and to the right of "min"`);
+    if (!(max.x > min.x) || !(max.y > min.y) || max.z < min.z) throw new Error(`${what}: "max" is above and to the right of "min"`);
     return Object.freeze({ min, max });
   };
   const spots: Record<string, readonly Vec3[]> = {};
@@ -264,13 +264,33 @@ export function compileMap(raw: unknown, name = 'main'): GameMap {
     if (!/^[a-z][A-Za-z0-9_-]{0,31}$/.test(key) || !Array.isArray(list)) throw new Error(`${where} spots.${key}: a spot name is a short word and holds a list of points`);
     spots[key] = Object.freeze(list.map((p, i) => vecOf(p, `${where} spots.${key}[${i}]`)));
   }
+  const roundShape = (c: any, what: string): MapCircle => {
+    const r = Number(c?.r);
+    if (!Number.isFinite(r) || !(r > 0)) throw new Error(`${what} needs a finite positive radius`);
+    return Object.freeze({ at: vecOf(c?.at, `${what}.at`), r });
+  };
+  if ([m.boxes, m.circles, m.spheres, m.capsules, m.heightTiles].some(list => list !== undefined && !Array.isArray(list))) throw new Error(`${where}: shapes are lists`);
+  if ([m.boxes, m.circles, m.spheres, m.capsules, m.heightTiles].reduce((n, list) => n + (list?.length ?? 0), 0) > 4096) throw new Error(`${where}: at most 4096 static shapes`);
   return Object.freeze({
     name,
+    heightTiles: Object.freeze((m.heightTiles ?? []).map((t: any, i: number) => {
+      const what = `${where} heightTiles[${i}]`;
+      const at = vecOf(t?.at, `${what}.at`);
+      if (!Array.isArray(t.size) || t.size.length !== 2 || t.size.some((v: unknown) => typeof v !== 'number' || !Number.isFinite(v) || v <= 0)) throw new Error(`${what}: size is two positive finite lengths`);
+      if (!Array.isArray(t.heights) || t.heights.length !== 4 || t.heights.some((v: unknown) => typeof v !== 'number' || !Number.isFinite(v))) throw new Error(`${what}: heights are four finite offsets, in row order`);
+      return Object.freeze({ at, size: Object.freeze({ x: t.size[0], y: t.size[1] }), heights: Object.freeze([...t.heights]) as unknown as MapHeightTile['heights'] });
+    })),
+    spheres: Object.freeze((m.spheres ?? []).map((c: any, i: number) => roundShape(c, `${where} spheres[${i}]`))),
+    capsules: Object.freeze((m.capsules ?? []).map((c: any, i: number) => {
+      const shape = roundShape(c, `${where} capsules[${i}]`);
+      if (!Number.isFinite(c.height) || c.height < 2 * shape.r) throw new Error(`${where} capsules[${i}]: height is at least twice the radius`);
+      return Object.freeze({ ...shape, height: c.height });
+    })),
     bounds: box(m.bounds, `${where} bounds`),
     boxes: Object.freeze((Array.isArray(m.boxes) ? m.boxes : []).map((b: unknown, i: number) => box(b, `${where} boxes[${i}]`))),
     circles: Object.freeze((Array.isArray(m.circles) ? m.circles : []).map((c: any, i: number) => {
       const r = Number(c?.r);
-      if (!(r > 0)) throw new Error(`${where} circles[${i}] needs "r", its radius in metres`);
+      if (!Number.isFinite(r) || !(r > 0)) throw new Error(`${where} circles[${i}] needs "r", its radius in metres`);
       return Object.freeze({ at: vecOf(c?.at, `${where} circles[${i}].at`), r });
     })),
     spots: Object.freeze(spots),
@@ -430,6 +450,8 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
   if (dims !== 2 && dims !== 3) throw new Error('rules name their space: space: { dims: 2 } or { dims: 3 }');
   const settings = env.settings ?? ROOM_DEFAULTS;
   const map = env.map ?? compileMap({ bounds: { min: [-32, -32], max: [32, 32] } });
+  if (dims === 2 && (map.spheres.length || map.capsules.length || map.heightTiles.length)) throw new Error('spheres, capsules and height tiles need space.dims: 3');
+  if (dims === 3 && map.bounds.max.z <= map.bounds.min.z) throw new Error('a 3D map needs bounds with positive height');
   const { tune, publicTune } = tunablesOf(env.tune);
 
   const events: Record<string, FieldList> = {};
@@ -475,9 +497,10 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
       const b = e.body;
       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' || !(b.radius > 0) || !(b.maxSpeed >= 0)) throw new Error(`${at}.body needs radius (metres) and maxSpeed (metres a second)`);
+      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.move !== undefined && b.move !== 'owner') throw new Error(`${at}.body.move is 'owner', or left out`);
-      body = { shape: b.shape, radius: b.radius, height: typeof b.height === 'number' && b.height > 0 ? b.height : 0, maxSpeed: b.maxSpeed, sweep: b.sweep === true, owner: b.move === 'owner' };
+      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' };
     }
     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,7 +558,7 @@ export interface Schema {
   contract: 2;
   dims: 2 | 3;
   seats: number;
-  kinds: { name: string; player: boolean; owner: boolean; radius: number; maxSpeed: number; score: string | null; fields: FieldList; motion: FieldList; input: FieldList }[];
+  kinds: { name: string; player: boolean; owner: boolean; radius: number; shape?: string; height?: number; maxSpeed: number; score: string | null; fields: FieldList; motion: FieldList; input: FieldList }[];
   effects: Record<string, FieldList>;
   effectNames: string[];
   commands: Record<string, FieldList>;
@@ -546,7 +569,7 @@ export interface Schema {
 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, maxSpeed: k.body?.maxSpeed ?? 0, score: k.score, fields: k.fields, motion: k.motion, input: k.input })),
+    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 })),
     effects: c.effects, effectNames: c.effectNames, commands: c.commands, shared: c.shared, rounds: c.rounds, settings: c.settings,
   };
 }

package/rules/types.ts

@@ -22,7 +22,7 @@ export interface MapView { readonly name: string; spot(name: string): Vec3 | und
 export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
 export interface Round { readonly n: number; readonly phase: 'live' | 'over'; readonly endsAt: number }
 export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
-  readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number;
+  readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
   readonly shared: Room extends true ? S : ReadonlyState<S>;
   readonly round: Round & (Room extends true ? { end(): void } : {});
   random(): number;
@@ -49,7 +49,7 @@ export type Undeliverable<E> = { [K in keyof E]: { to: string; event: K; data: E
 export type BuiltIns<E = Record<string, never>> = { arrive: { why: 'join' | 'spawn' }; leave: {}; takeover: {}; undeliverable: Undeliverable<E>; answer: { ask: string; by: string; picks: Readonly<Record<string, unknown>>; why?: string } };
 export type RoomEvents<E = Record<string, never>> = RoundEvents & { seatJoined: { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; owner: string; took: boolean }; seatAway: { seat: number; id: string; away: boolean }; seatLeft: { seat: number; id: string }; answer: BuiltIns['answer']; undeliverable: BuiltIns<E>['undeliverable'] };
 export type RoundEvents = { roundStart: { n: number }; roundOver: { n: number; results: readonly { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; score: number; place: number }[] } };
-type GuideWorld<W> = Pick<W, Extract<keyof W, 'tick' | 'dt' | 'ticks' | 'math' | 'map' | 'tune' | 'stage' | 'level' | 'levelMax' | 'round' | 'shared' | 'near' | 'inBox' | 'ray'>>;
+type GuideWorld<W> = Pick<W, Extract<keyof W, 'tick' | 'dt' | 'ticks' | 'math' | 'map' | 'tune' | 'stage' | 'level' | 'levelMax' | 'guideLevel' | 'guideSeats' | 'kids' | 'levelSet' | 'round' | 'shared' | 'near' | 'inBox' | 'ray'>>;
 export type Entity<W, S, I, E, C, V, Answer = BuiltIns['answer'], G = Goal, A = GuideRequest, D = GuideDecision> = {
   player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot' }; fields?: Fields; motion?: Fields; input?: Fields; body?: BodyDef;
   tick?: (world: W, self: S) => void;