@homie-rocks/studio 0.15.0 → 0.16.1

package/port/bots.ts

@@ -13,7 +13,11 @@
  *   - They are kind to newcomers: no bot targets a person in their first
  *     ~15 s, and a person's first minute is never a pile-on.
  *   - A body a person left keeps playing as a bot, where it stands.
+ *   - They play at the room's skill dial (NETPLAY.md section 17): give BotBrain
+ *     `skill: () => room.skillOf(body)` and the party's vote changes how fast it
+ *     reacts, how well it aims and how long it commits, with no other change.
  */
+import type { Skill } from '../netplay/netplay';
 
 export interface V2 { x: number; y: number }
 
@@ -45,9 +49,20 @@ export function nearest<T extends V2>(from: V2, items: Iterable<T>, taken?: Set<
   return best;
 }
 
+/**
+ * What a skill level means to a bot's brain (section 17): it reacts `reactionMs` late, its aim errs by
+ * `aimNoise x 0.8` radians, and it commits to a target for `2500 x (1.3 - 0.6 x aggression)` ms (an aggressive bot
+ * changes its mind sooner). Level 3, Fair, is 250 ms, 0.12 rad and 2.5 s: what every port's bots always were.
+ */
+export function brainOf(s: Skill): { reactionMs: number; aimError: number; commitMs: number } {
+  return { reactionMs: s.reactionMs, aimError: s.aimNoise * 0.8, commitMs: 2500 * (1.3 - 0.6 * s.aggression) };
+}
+
 /**
  * A bot's intent with a person's limits: it sees the world `reactionMs` late, commits to a target for `commitMs`,
  * and notices when it is stuck. Call `think(now, pos, choose)` every frame; it returns the stick to push.
+ * `skill` (a Skill, or a function that says the current one): the room's dial sets reaction, aim and commitment;
+ * explicit `reactionMs`, `commitMs` or `aimError` still win.
  */
 export class BotBrain<T extends V2 = V2> {
   target: T | null = null;
@@ -56,10 +71,18 @@ export class BotBrain<T extends V2 = V2> {
   private unstickUntil = 0;
   private unstick: V2 = { x: 0, y: 0 };
   private queue: { at: number; v: V2 }[] = [];
-  constructor(readonly opts: { reactionMs?: number; commitMs?: number; stuckMs?: number; stuckDist?: number; aimError?: number } = {}) {}
+  constructor(readonly opts: { reactionMs?: number; commitMs?: number; stuckMs?: number; stuckDist?: number; aimError?: number; skill?: Skill | (() => Skill) } = {}) {}
+
+  /** The dial this brain plays at now (Fair with none). */
+  skill(): Skill | null {
+    const k = this.opts.skill;
+    try { return typeof k === 'function' ? k() : k ?? null; } catch { return null; }
+  }
 
   think(now: number, pos: V2, choose: () => T | null, arrive = 0): V2 {
-    const { reactionMs = 250, commitMs = 2500, stuckMs = 3000, stuckDist = 24, aimError = 0.12 } = this.opts;
+    const sk = this.skill();
+    const dial = sk ? brainOf(sk) : { reactionMs: 250, commitMs: 2500, aimError: 0.12 };
+    const { reactionMs = dial.reactionMs, commitMs = dial.commitMs, stuckMs = 3000, stuckDist = 24, aimError = dial.aimError } = this.opts;
     if (!this.target || now - this.chosenAt > commitMs) { this.target = choose(); this.chosenAt = now; }
     if (!this.lastCheck || now - this.lastCheck.at > stuckMs) {
       if (this.lastCheck && Math.hypot(pos.x - this.lastCheck.x, pos.y - this.lastCheck.y) < stuckDist && this.target) {

package/port/index.ts

@@ -11,7 +11,9 @@
  *   exposePort   what `homie-studio port check` reads (owner tests)
  *   createHud    a minimal clock / scores / results overlay
  *   BotBrain, seek, nearest, rubberBand
- *                bot scaffolds
+ *                bot scaffolds; `skill` makes a bot play at the room's dial (NETPLAY.md section 17)
+ *   jitter, engages, standoff
+ *                the dial for the rest of a bot's decisions (port/skill.ts)
  *   createSaves  player accounts and cloud saves (a character that lasts days, on every device; saves/SAVES.md)
  * and everything from @homie-rocks/studio/netplay.
  */
@@ -27,5 +29,6 @@ export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLi
 export { exposePort, type PortProbeOptions, type View } from './probe';
 export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
 export { createHud, type HudOptions } from './hud';
-export { BotBrain, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';
+export { BotBrain, brainOf, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';
+export { jitter, engages, standoff } from './skill';
 export { createSaves, SAVES_VERSION, type Saves, type SavesOptions, type Player, type SaveEntry, type SetResult, type Memorial, type SavesStatus, type Conflict } from '../saves/saves';

package/port/room.ts

@@ -17,15 +17,21 @@
  *   - Snapshots: one small row per body [slot, seat (-1 = bot), score, ...your
  *     fields], plus your fast world, at 20 Hz; replicas interpolate them.
  *
+ *   - Servers and agent seats (NETPLAY.md section 17): a hybrid server's AI
+ *     seats are kept as AI bodies (the game's bots move them, marked AI), an AI
+ *     that sits takes one, the server's `bots: 'off'` adds no filler bots, and
+ *     `room.skillOf(body)` is the dial a bot plays at (the party votes it).
+ *
  * What stays the game's: the rules (what a body does per frame), the bots'
  * brains, the drawing, and the camera. See the port skill's recipe.
  */
 import {
   capMove, createNetplay, lerp, lerpAngle, Roster,
-  type Movement, type Netplay, type NetplayOptions, type RoleChange, type RoundInfo, type RoundResult, type Slot, type Snapshot,
+  type Movement, type Netplay, type NetplayOptions, type Policy, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot,
 } from '../netplay/netplay';
 
-export interface BodyBase { slot: number; seat: number | null; name: string; bot: boolean; score: number }
+/** A body. `agent` (revision 6): this body is an AI's (a seat kept for AI, or an agent's), always marked AI. */
+export interface BodyBase { slot: number; seat: number | null; name: string; bot: boolean; score: number; agent?: Slot['agent'] }
 
 export interface RoomSnap<F = unknown> { r: [n: number, phase: number, startedAt: number, endsAt: number]; b: number[][]; w?: F }
 export interface RoomCkpt<B, S> { round: RoundInfo | null; roster: Slot[]; bodies: B[]; world: S | null; tick: number }
@@ -91,6 +97,8 @@ export interface Room<B extends BodyBase, F = unknown, S = unknown> {
   viewSeat(): number | null;
   /** The body of viewSeat() as everyone draws it (host: the real one; others: interpolated), or null. */
   viewBody(): B | null;
+  /** The skill dial a bot body plays at now (section 17): the party's vote, a guide's server level, else Fair. */
+  skillOf(body: { slot: number }): Skill;
   /** Host: my own body. Replica: null (draw yours from your local state). */
   mine(): B | null;
   /** Host, every frame: the round clock and the snapshot. Replica: no-op. Call AFTER your rules moved the bodies. */
@@ -131,7 +139,9 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
   const angles = new Set(opts.angles ?? []);
   const discrete = new Set(opts.discrete ?? []);
 
-  let roster = new Roster({ min, max, botName });
+  // The roster keeps the server's AI seats (section 17); the policy is the room's, read when it fills.
+  const policy = (): Policy => net.policy;
+  let roster = new Roster({ min, max, botName, policy });
   let bodies = new Map<number, B>();
   let round: RoundInfo | null = null;
   let hosting = false;
@@ -142,6 +152,8 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     snapshotHz: 20, inputHz: 20, checkpointMs: 1000,
     checkpoint: () => ({ round, roster: roster.toJSON(), bodies: [...bodies.values()].map((b) => ({ ...b })), world: opts.saveWorld ? opts.saveWorld() : null, tick }),
     ...(opts.netplay ?? {}),
+    // createRoom claims an AI's slot for it (its join passes `p.agent`), so its host can move an AI's body.
+    caps: [...new Set([...(opts.netplay?.caps ?? []), 'agents' as const])],
   });
 
   const mySeat = (): number | null => (net.offline ? 0 : net.seat);
@@ -157,8 +169,9 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     for (const s of roster.slots) {
       seen.add(s.slot);
       const b = bodies.get(s.slot);
-      if (!b) { const nb = opts.spawn(s, i++); nb.slot = s.slot; nb.seat = s.seat; nb.name = s.name; nb.bot = s.bot; nb.score = nb.score ?? 0; bodies.set(s.slot, nb); continue; }
+      if (!b) { const nb = opts.spawn(s, i++); nb.slot = s.slot; nb.seat = s.seat; nb.name = s.name; nb.bot = s.bot; nb.score = nb.score ?? 0; if (s.agent) nb.agent = { ...s.agent }; bodies.set(s.slot, nb); continue; }
       b.seat = s.seat; b.name = s.name; b.bot = s.bot;
+      if (s.agent) b.agent = { ...s.agent }; else delete b.agent;
     }
     for (const k of [...bodies.keys()]) if (!seen.has(k)) bodies.delete(k);
   }
@@ -185,6 +198,7 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     for (const s of [...roster.slots].sort((a, c) => a.slot - c.slot)) {
       const fresh = opts.spawn(s, i++);
       fresh.slot = s.slot; fresh.seat = s.seat; fresh.name = s.name; fresh.bot = s.bot; fresh.score = 0;
+      if (s.agent) fresh.agent = { ...s.agent };
       bodies.set(s.slot, fresh);
     }
     round = { n, phase: 'live', startedAt: now, endsAt: now + roundMs };
@@ -197,7 +211,7 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
 
   function rank(): RoundResult[] {
     const ranked = [...bodies.values()].sort((a, b) => b.score - a.score || Number(a.bot) - Number(b.bot) || a.slot - b.slot);
-    return ranked.map((b, i) => ({ slot: b.slot, seat: b.seat, name: b.name, score: b.score, bot: b.bot, place: i + 1 }));
+    return ranked.map((b, i) => ({ slot: b.slot, seat: b.seat, name: b.name, score: b.score, bot: b.bot, place: i + 1, ...(b.agent ? { agent: true as const } : {}) }));
   }
 
   function endRound(): void {
@@ -212,12 +226,12 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
   function restore(e: RoleChange<RoomSnap<F>, RoomCkpt<B, S>>): void {
     const ck = e.ckpt?.d ?? null;
     if (ck) {
-      roster = Roster.from(ck.roster, { min, max, botName });
+      roster = Roster.from(ck.roster, { min, max, botName, policy });
       bodies = new Map(ck.bodies.map((b) => [b.slot, { ...b }]));
       round = ck.round;
       tick = ck.tick;
     } else {
-      roster = Roster.from(e.roster ?? [], { min, max, botName });
+      roster = Roster.from(e.roster ?? [], { min, max, botName, policy });
       bodies = new Map();
       syncBodies();
     }
@@ -252,14 +266,14 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     hosting = true;
     if (e.promoted) restore(e);
     else {
-      roster = new Roster({ min, max, botName });
+      roster = new Roster({ min, max, botName, policy });
       bodies = new Map();
       const seat = mySeat();
       if (seat !== null) roster.claim(seat, net.offline ? 'You' : net.name);
       syncBodies();
       startRound((e.round?.n ?? 0) + 1);
     }
-    const peers = net.offline ? [{ seat: 0, name: 'You' }] : [...net.peers.values()].filter((p) => p.seat !== null);
+    const peers = net.offline ? [{ seat: 0, name: 'You' }] : [...net.peers.values()].filter((p) => p.seat !== null).map((p) => ({ seat: p.seat, name: p.name, agent: p.agent ?? null }));
     const { claimed } = roster.reconcile(peers);
     syncBodies();
     for (const s of claimed) { const b = bodies.get(s.slot); if (b && b.seat !== mySeat()) moved(b); }
@@ -274,7 +288,8 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
   });
   net.on('join', (p) => {
     if (!hosting || p.seat === null) return;
-    const c = roster.claim(p.seat, p.name);
+    // An AI takes a seat kept for AI (its hands say who moves the body); a person never does (section 17).
+    const c = roster.claim(p.seat, p.name, p.agent ? { role: p.agent.role, hands: p.agent.hands } : null);
     if (!c) return; // full: they watch
     syncBodies();
     const b = bodies.get(c.slot.slot);
@@ -291,6 +306,13 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     syncBodies();
     net.roster(roster.toJSON());
   });
+  // The server's policy changed (a new server stamp, the owner): its AI seats come or go at once, filler at the round.
+  net.on('policy', () => {
+    if (!hosting) return;
+    roster.fill();
+    syncBodies();
+    net.roster(roster.toJSON());
+  });
   net.on('control', (e) => {
     if (!e.reset || !opts.adopt) return;
     const snap = e.snap as Snapshot<RoomSnap<F>> | null;
@@ -335,6 +357,7 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
       for (const b of room.view()) if (!b.bot && b.seat === s) return b;
       return null;
     },
+    skillOf: (body) => net.skillOf(body.slot),
     mine: () => (hosting ? bodyOfSeat(mySeat()) : null),
     update() {
       if (!hosting) return;

package/port/skill.ts

@@ -0,0 +1,28 @@
+/*
+ * The skill dial for a port's own bot code (NETPLAY.md section 17). A level is { reactionMs, aimNoise, aggression,
+ * positioning }; `room.skillOf(body)` (or `net.skillOf(slot)`) says which one a bot plays at now. BotBrain reads
+ * reaction, aim and commitment by itself; these three are for the rest of a bot's decisions:
+ *
+ *   jitter(s, maxPx)        how far off its aim lands (aimNoise of maxPx, either way)
+ *   engages(s, dt)          whether it starts a fight this frame (aggression, about once a second at most)
+ *   standoff(s, near, far)  how close to the action it stands: far at positioning 0, near at 1
+ *
+ * Level 1 (Rookie) stays at the back and misses a lot; 5 (Maxed) is a front-line tank that rarely misses.
+ */
+import type { Skill } from '../netplay/netplay';
+
+/** An aim offset: up to `maxPx x aimNoise` either way (0 at a perfect aim). */
+export function jitter(s: Skill, maxPx: number): number {
+  return (Math.random() - 0.5) * 2 * maxPx * Math.max(0, Math.min(1, s.aimNoise));
+}
+
+/** Whether a bot starts a fight (or a wave, a shot, a tackle) this frame: about `aggression` times a second. */
+export function engages(s: Skill, dt: number): boolean {
+  return Math.random() < Math.max(0, Math.min(1, s.aggression)) * Math.max(0, dt);
+}
+
+/** How far from the action to stand: `far` at positioning 0 (behind the party), `near` at 1 (the front line). */
+export function standoff(s: Skill, near: number, far: number): number {
+  const t = Math.max(0, Math.min(1, s.positioning));
+  return far + (near - far) * t;
+}

package/site/SITE.md

@@ -157,6 +157,8 @@ where the game has room, per device:
 - It shows the room's name ("Room 7") for a few seconds, then shrinks to a round icon until it is touched;
   `"label": false` keeps it the icon always (the code is in its sheet), for a corner with little room.
 - A button at the bottom left sends the "finding a room" chip to the bottom right.
+- On a server, the server's pill sits beside the button, on its inner side in the same band, never under it: on a
+  phone held upright it is one more dot; elsewhere its name shows for a few seconds, then it is a dot too.
 
 Look at the play page on a computer and a phone (both ways up) once a round is on: the button must not sit on a
 score, a timer or a bar. A room code the relay cannot use (1 to 32 letters, digits, `-` or `_`) is refused
@@ -192,6 +194,53 @@ The page is the game itself, drawn by the watcher's own browser as a watcher: a
   that room as the whole room only, so a second tab is not a peek.
 - Each opening counts as a `watch` in the studio's stats.
 
+## Servers: `/<id>/servers/` and `/<id>/s/<server>/`
+
+A game's **servers** are named, lasting pools of rooms with their own rules (`worker/servers.mjs`; NETPLAY.md
+section 17 for the room's side). Strangers are matched only inside one server. The game's own public rooms are
+its **Quick play** server (`public`), so every old link keeps working.
+
+- **The landing's Servers band** shows when the game has a server besides Quick play: a card per server (its
+  name, its policy's badge and one line, who is on it now: "9 playing · 4 AI · 41 members", Play and About),
+  and "Quick play →" under it. `/<id>/servers/` lists them all (and every policy's line). A server that is
+  closed, not listed, or has a door (an account or an invite) is left out of the Rooms lists and `/api/rooms`.
+- **The badge and its line**, everywhere a server is shown: *Open* ("anyone can play. AI players are always
+  marked AI."), *Humans only* ("every player here is a person. AI can't join."), *Hybrid · N* ("N seats in every
+  room are AI companions, always marked AI. Your party sets their level."), *Beginner* ("for new players. AI guides
+  help you learn. Chat is quick lines only."); a kids server adds "Players have handles, not names."
+- **A server's page** (`/<id>/s/<server>/`): its name, blurb, badge and line; its live rooms (AI marked); how many
+  belong to it; "☆ Make this my home" for a signed-in player (and Leave); and a big **Play**
+  (`/<id>/s/<server>/play`). A player's home server is where a bare `/<id>/play` takes them; their account page
+  lists their servers.
+- **The door**, then the play page: *open* lets anyone in; *accounts* asks the visitor to sign in with a passkey
+  ("Sign in to play on Night Shift"); *invite* shows the invite-code box (`homie-studio office invite <id> --server
+  <server>` makes codes and links for one server); *beginner* lets in guests and accounts younger than its days
+  (a veteran is told "First Light is for new players… try another server or Quick play"; a mentor gets in, with a
+  Mentor badge). A server whose rooms are all full (its `rooms`) sends the visitor to its fullest room, where they
+  wait for a seat ("First Light is full. You're next for a seat."). The owner always comes in. The watch door is
+  the same door, except that watching a beginner room needs no new account.
+- **When the owner hides Quick play** (`homie-studio servers close <id> public`), Play shows the servers to pick
+  from, and a named `?room=` is off (except for the owner).
+- **The play shell** on a server: a pill beside the room button, in the same band at the room button's place
+  (`screen.share`), never under it ("First Light · Beginner", then a dot after a few seconds; on a phone held
+  upright, the dot from the start; tap: the server's name, the policy's line, "AI level: Steady" with **Change**
+  when the game's bots read the dial, and **Quiet AI**, which hides AI chat on this screen only). A server room's
+  button says "Room 2", as Quick play's does. The chip says "First Light · 4 playing · 2 AI"; every AI row and result
+  carries an AI pill. A game's HUD keeps that band clear (Gem Rush starts its scores under it).
+- **The vote card** ("How strong should the AI be?", five levels, "the middle vote wins") opens by itself at a
+  party's first round with AI seats, from the pill's Change, or from the game; a lone player's tap decides at once,
+  every seated person's vote closes it early, else 15 s. Keys 1-5 on a computer; a bottom sheet on a phone. The card
+  is opaque: nothing of the game shows through it. The
+  result is a toast ("The party set the AI to Steady (3 votes)."). A game that draws its own card says game.json
+  `"agents": { "vote": "game" }` (`false`: none).
+- `/<id>/api/servers` is the servers with their live counts (cacheable 15 s). `/api/rooms` rows say their
+  `server`, `policy` and `ai`.
+
+**An AI's seat** (an agent pass from `homie-studio agents pass`): `POST /<id>/api/agent` with `Authorization:
+Bearer <pass>` and `{ "server": "<id>" }` answers a room with people in it (never an empty one), a ticket, its
+socket and (an AI that runs the game itself) the frame to load. A humans-only server answers 403 "This server is
+for humans only", and so does its socket.
+
 ## Player accounts: `/account/`
 
 A studio whose games keep saves (game.json `"saves": true`, [../saves/SAVES.md](../saves/SAVES.md)) has a player

package/starters/ember-vale/src/main.ts

@@ -18,8 +18,12 @@
  * A watcher (/<game>/watch, contract revision 5) has no hero and makes none: `room.viewSeat()` is the hero it
  * follows, drawn in gold as a hero's own browser draws itself, with that hero's panel; nobody followed, the vale.
  * The host says who slew what (`slain`), so a watcher on Auto cuts to the kill.
+ *
+ * Servers and the skill dial (contract revision 6): the vale's bots hunt at the room's dial (`room.skillOf(body)`:
+ * how soon they notice a slime, how close they stand, how often they strike), and a beginner server's AI guide seats
+ * are kept as AI bodies, marked " · AI". createRoom does the seats; the bots below read the dial.
  */
-import { createControls, createRoom, createSaves, exposePort, q, type BodyBase, type NetEvent } from '@homie-rocks/studio/port';
+import { AI_MARK, createControls, createRoom, createSaves, exposePort, jitter, q, standoff, type BodyBase, type NetEvent } from '@homie-rocks/studio/port';
 
 /* ------------------------------------------------------------------ rules */
 const W = 1600;
@@ -39,7 +43,7 @@ const clamp = (v: number, a: number, b: number): number => Math.max(a, Math.min(
 
 /** The hero: the one thing that lasts. Kept in the save key 'hero'. */
 interface Hero { v: 1; name: string; level: number; xp: number; gold: number; hardcore: boolean; kills: number; deaths: number; born: number }
-interface Body extends BodyBase { x: number; y: number; hp: number; maxHp: number; level: number; face: number; flags: number; downUntil: number; atkAt: number; strikeAt: number; tx: number; ty: number }
+interface Body extends BodyBase { x: number; y: number; hp: number; maxHp: number; level: number; face: number; flags: number; downUntil: number; atkAt: number; strikeAt: number; tx: number; ty: number; seenAt?: number; ax?: number; ay?: number }
 interface Slime { id: number; x: number; y: number; hp: number; maxHp: number; size: number; hitAt: number; lastHit: number }
 type SlimeRow = [id: number, x: number, y: number, hp: number, size: number];
 
@@ -190,14 +194,23 @@ function stepHost(dt: number): void {
     }
     let wants = false;
     if (b.bot) {
-      // Bots are company, not carries: they hunt only what is near them, and strike slower than a person.
+      // Bots are company, not carries: they hunt only what is near them, and strike slower than a person. At the
+      // room's dial (section 17): they notice a slime `reactionMs` late, hunt farther afield the more they lean to
+      // the front (positioning), aim a little off (aimNoise), and strike sooner the more aggressive they are.
+      const s = room.skillOf(b);
       const near = nearestSlime(b.x, b.y);
-      const t = near && Math.hypot(near.x - b.x, near.y - b.y) < 360 ? near : null;
+      const reach = standoff(s, 460, 220);
+      if (!b.seenAt || now - b.seenAt >= s.reactionMs) {
+        b.seenAt = now;
+        const t0 = near && Math.hypot(near.x - b.x, near.y - b.y) < reach ? near : null;
+        b.ax = t0 ? t0.x + jitter(s, 40) : undefined; b.ay = t0 ? t0.y + jitter(s, 40) : undefined;
+      }
+      const t = b.ax !== undefined && b.ay !== undefined ? { x: b.ax, y: b.ay } : null;
       const tx = t ? t.x : b.tx; const ty = t ? t.y : b.ty;
       if (!t && Math.hypot(b.tx - b.x, b.ty - b.y) < 30) { b.tx = 200 + Math.random() * (W - 400); b.ty = 150 + Math.random() * (H - 300); }
       const dx = tx - b.x; const dy = ty - b.y; const dist = Math.hypot(dx, dy) || 1;
       if (dist > 60) { b.x += (dx / dist) * SPEED * 0.75 * dt; b.y += (dy / dist) * SPEED * 0.75 * dt; b.face = Math.atan2(dy, dx); }
-      wants = Boolean(t && dist < STRIKE_RANGE && now - b.atkAt > 900);
+      wants = Boolean(t && dist < STRIKE_RANGE && now - b.atkAt > 1400 - 900 * s.aggression);
     } else if (b.seat === myS) {
       b.x = me.x; b.y = me.y; b.face = me.face; b.level = myLevel(); b.maxHp = maxHpOf(b.level);
       wants = me.strikes > 0; me.strikes = 0;
@@ -326,7 +339,8 @@ function draw(t: number): void {
     ctx.fillStyle = '#7ad35a'; ctx.fillRect(x - 24, y - R - 12, (48 * clamp(b.hp, 0, b.maxHp)) / Math.max(1, b.maxHp), 5);
     ctx.globalAlpha = 1;
     ctx.font = '600 18px ui-sans-serif, system-ui, sans-serif'; ctx.textAlign = 'center'; ctx.fillStyle = self ? '#ffcf6e' : '#e7d9b4';
-    ctx.fillText(`${b.name}${b.bot ? ' · bot' : ''} · ${b.level}`, x, y - R - 18);
+    // An AI's name already ends in " · AI" (a guide, a companion); a plain bot says bot.
+    ctx.fillText(`${b.name}${b.bot && !b.name.endsWith(AI_MARK) ? ' · bot' : ''} · ${b.level}`, x, y - R - 18);
   }
   ctx.restore();
   hud(t);
@@ -369,7 +383,7 @@ function hud(t: number): void {
     ctx.fillStyle = 'rgba(10,14,9,.78)'; ctx.fillRect(cw / 2 - 150, 44, 300, 30 + rows.length * 22);
     ctx.fillStyle = '#ffcf6e'; ctx.fillText('Tonight\'s hunters', cw / 2, 66);
     ctx.font = '600 14px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
-    rows.forEach((r, i) => ctx.fillText(`${r.place}. ${r.name}${r.bot ? ' (bot)' : ''} — ${r.score} xp`, cw / 2, 90 + i * 22));
+    rows.forEach((r, i) => ctx.fillText(`${r.place}. ${r.name}${r.bot && !r.name.endsWith(AI_MARK) ? ' (bot)' : ''} — ${r.score} xp`, cw / 2, 90 + i * 22));
   }
   if (performance.now() < bannerUntil) { ctx.font = '800 22px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#ffcf6e'; ctx.fillText(bannerText, cw / 2, canvas.height / k - 90); }
   const st = saves.status();

package/starters/gem-rush/src/main.ts

@@ -22,9 +22,16 @@
  * nobody followed the whole arena shows. Waves call `net.spotlight(seat)`, so a
  * watcher on Auto cuts to whoever just bumped.
  *
+ * SERVERS AND THE SKILL DIAL (contract revision 6): the bots play at the room's
+ * dial (`net.skillOf(slot)`: how late they see, how well they aim, whether they
+ * fight for the hot zone, how often they bump), which the party votes in the
+ * play page; a hybrid server's AI seats are kept as AI bodies (the Roster's
+ * reserve, marked " · AI"), an AI with a pass takes one, and a humans-only
+ * server's bots are off. The game says so: `caps: ['skill', 'agents']`.
+ *
  * Canvas 2D on purpose: the point is the contract, in ~700 readable lines.
  */
-import { createNetplay, Roster, q, lerp, capMove, PALETTE, type RoleChange, type RoundInfo, type RoundResult, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
+import { createNetplay, Roster, q, lerp, capMove, PALETTE, AI_MARK, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
 // The port toolkit's probe: what `homie-studio port check` reads for the owner tests (and sandbox + audio shims).
 import { exposePort } from '@homie-rocks/studio/port';
 
@@ -48,7 +55,8 @@ const ZONE_MS = 12_000;
 const colourOf = (slot: number, seat: number | null): string => PALETTE[(seat ?? slot) % PALETTE.length] as string;
 const BOT_NAMES = ['Rook', 'Vex', 'Moth', 'Kilo', 'Juno', 'Pike', 'Nyx', 'Ash'];
 const botName = (slot: number): string => BOT_NAMES[slot % BOT_NAMES.length] as string;
-const label = (name: string, bot: boolean): string => (bot ? `${name} · bot` : name);
+/** An AI's name already ends in " · AI" (the relay sees to it); a plain bot says bot. */
+const label = (name: string, bot: boolean): string => (name.endsWith(AI_MARK) ? name : bot ? `${name} · bot` : name);
 
 /* ------------------------------------------------------------ wire shapes */
 /** Snapshot: compact arrays, quantized. ~40 B per body, ~16 B per gem. (Reset epochs ride in the helper's `c` table.) */
@@ -73,10 +81,13 @@ interface Ckpt { round: RoundInfo; bodies: Body[]; gems: Gem[]; roster: Slot[];
  * Default `owner`: each browser moves its own body and the host bounds it.
  */
 const MOVEMENT: 'owner' | 'host' = (() => { try { return new URLSearchParams(location.search).get('movement') === 'host' ? 'host' : 'owner'; } catch { return 'owner'; } })();
-const net = createNetplay<Snap, Avatar, Ckpt>({ game: 'gem-rush', maxPlayers: MAX_SLOTS, movement: MOVEMENT, snapshotHz: 20, inputHz: 20, checkpointMs: 1000, checkpoint: () => checkpoint() });
+// caps: its bots read the dial ('skill'), and its Roster takes an AI's slot for it ('agents': the join passes p.agent).
+const net = createNetplay<Snap, Avatar, Ckpt>({ game: 'gem-rush', maxPlayers: MAX_SLOTS, movement: MOVEMENT, snapshotHz: 20, inputHz: 20, checkpointMs: 1000, caps: ['skill', 'agents'], checkpoint: () => checkpoint() });
+/** The Roster keeps the server's AI seats (revision 6): the policy is read whenever it fills. */
+const policy = () => net.policy;
 
 /* ------------------------------------------------------------ host state */
-let roster = new Roster({ min: MIN_SLOTS, max: MAX_SLOTS, botName });
+let roster = new Roster({ min: MIN_SLOTS, max: MAX_SLOTS, botName, policy });
 let bodies = new Map<number, Body>();
 let gems: Gem[] = [];
 let gemSeq = 0;
@@ -87,6 +98,8 @@ let hosting = false;
 let cheatResets = 0;
 let controlResets = 0;
 let predictionError = 0;
+/** Gems each slot picked up this round (a gem, whatever it scored): the dial's numbers (`pickups` probe). */
+let pickups = new Map<number, number>();
 
 /* ------------------------------------------------ this browser's avatar */
 const me = { x: W / 2, y: H / 2, vx: 0, vy: 0, kvx: 0, kvy: 0, knockUntil: 0, has: false };
@@ -152,6 +165,8 @@ function startRound(n: number): void {
     hostMoved(b);
   }
   gems = Array.from({ length: GEM_COUNT }, newGem);
+  pickups = new Map();
+  sight.clear();
   round = { n, phase: 'live', startedAt: now, endsAt: now + ROUND_MS };
   setZone(newZone((zone?.n ?? 0) + 1));
   net.round(round);
@@ -163,7 +178,8 @@ function endRound(): void {
   if (!round) return;
   const now = net.now();
   const ranked = [...bodies.values()].sort((a, b) => b.score - a.score || Number(a.bot) - Number(b.bot) || a.slot - b.slot);
-  const results: RoundResult[] = ranked.map((b, i) => ({ slot: b.slot, seat: b.seat, name: b.name, score: b.score, bot: b.bot, place: i + 1 }));
+  const agentSlot = (slot: number): boolean => Boolean(roster.slots.find((x) => x.slot === slot)?.agent);
+  const results: RoundResult[] = ranked.map((b, i) => ({ slot: b.slot, seat: b.seat, name: b.name, score: b.score, bot: b.bot, place: i + 1, ...(agentSlot(b.slot) ? { agent: true as const } : {}) }));
   round = { n: round.n, phase: 'over', startedAt: now, endsAt: now + BREAK_MS, results };
   net.round(round);
 }
@@ -173,7 +189,7 @@ function becomeHost(e: RoleChange<Snap, Ckpt>): void {
   hosting = true;
   if (e.promoted) restore(e);
   else {
-    roster = new Roster({ min: MIN_SLOTS, max: MAX_SLOTS, botName });
+    roster = new Roster({ min: MIN_SLOTS, max: MAX_SLOTS, botName, policy });
     bodies = new Map();
     const seat = mySeat();
     if (seat !== null) roster.claim(seat, net.offline ? 'You' : net.name);
@@ -181,7 +197,7 @@ function becomeHost(e: RoleChange<Snap, Ckpt>): void {
     startRound((e.round?.n ?? 0) + 1);
   }
   // Whoever is connected now is who plays: seats that left during the gap become bots.
-  const peers = net.offline ? [{ seat: 0, name: 'You' }] : [...net.peers.values()].filter((p) => p.seat !== null);
+  const peers = net.offline ? [{ seat: 0, name: 'You' }] : [...net.peers.values()].filter((p) => p.seat !== null).map((p) => ({ seat: p.seat, name: p.name, agent: p.agent ?? null }));
   const { claimed } = roster.reconcile(peers);
   syncBodiesFromRoster();
   for (const s of claimed) { const b = bodies.get(s.slot); if (b && b.seat !== mySeat()) hostMoved(b); }
@@ -198,14 +214,14 @@ function becomeHost(e: RoleChange<Snap, Ckpt>): void {
 function restore(e: RoleChange<Snap, Ckpt>): void {
   const ck = e.ckpt?.d ?? null;
   if (ck) {
-    roster = Roster.from(ck.roster, { min: MIN_SLOTS, max: MAX_SLOTS, botName });
+    roster = Roster.from(ck.roster, { min: MIN_SLOTS, max: MAX_SLOTS, botName, policy });
     bodies = new Map(ck.bodies.map((b) => [b.slot, { ...b }]));
     gems = ck.gems.map((g) => ({ ...g }));
     gemSeq = ck.gemSeq;
     round = ck.round;
     tick = ck.tick;
   } else {
-    roster = Roster.from(e.roster ?? [], { min: MIN_SLOTS, max: MAX_SLOTS, botName });
+    roster = Roster.from(e.roster ?? [], { min: MIN_SLOTS, max: MAX_SLOTS, botName, policy });
     bodies = new Map();
     syncBodiesFromRoster();
   }
@@ -250,7 +266,8 @@ net.on('role', (e) => {
 });
 net.on('join', (p) => {
   if (!hosting || p.seat === null) return;
-  const c = roster.claim(p.seat, p.name);
+  // An AI takes a seat kept for AI, a person never does (revision 6: the Roster needs p.agent for that).
+  const c = roster.claim(p.seat, p.name, p.agent ? { role: p.agent.role, hands: p.agent.hands } : null);
   if (!c) return; // full: they watch
   syncBodiesFromRoster();
   const b = bodies.get(c.slot.slot);
@@ -265,6 +282,8 @@ net.on('leave', (p) => {
   syncBodiesFromRoster();
   publishRoster();
 });
+// The server's policy changed: its AI seats come (or go between rounds) at once.
+net.on('policy', () => { if (!hosting) return; roster.fill(); syncBodiesFromRoster(); publishRoster(); });
 net.on('event', (e) => {
   if (e.k === 'wave') addWave(e.d as { slot: number });
   if (e.k === 'knock') addWave(e.d as { slot: number }, true);
@@ -420,28 +439,69 @@ function stepKnocked(b: Body, dt: number): void {
   b.vx = b.kvx; b.vy = b.kvy;
 }
 
+/**
+ * THE BOTS, AT THE ROOM'S DIAL (NETPLAY.md section 17). A bot re-reads the world only every `reactionMs` (what it
+ * last noticed is where it heads, and a miss costs it that long again), aims up to 200 px off at aimNoise 1, leaves
+ * the hot zone to the people at positioning 0 and fights for it at 1, and waves at a rival in reach about
+ * `aggression x 0.8` times a second. Rookie is beatable by anyone, Maxed by few: measured with the
+ * `pickups` probe over 60 s rounds, a Maxed bot picks up a little over twice the gems of a Rookie.
+ */
+const sight = new Map<number, { at: number; tx: number; ty: number; arrived?: boolean }>();
+
 function stepBots(dt: number): void {
   const taken = new Set<number>();
   const now = net.now();
   for (const b of bodies.values()) {
     if (!b.bot) continue;
     if (b.knockUntil > now) { stepKnocked(b, dt); continue; }
-    let best: Gem | null = null; let bd = Infinity;
-    for (const g of gems) {
-      if (taken.has(g.id)) continue;
-      const d = Math.hypot(g.x - b.x, g.y - b.y);
-      if (d < bd) { bd = d; best = g; }
+    const s: Skill = net.skillOf(b.slot); // Fair when nobody set a dial
+    let eye = sight.get(b.slot);
+    if (!eye || now - eye.at >= s.reactionMs) { // REACTION TIME
+      const g = pickGem(b, taken, s); // POSITIONING
+      const miss = 200 * s.aimNoise; // AIM NOISE: up to 200 px off at 1
+      eye = { at: now, tx: g ? g.x + (Math.random() - 0.5) * miss : b.tx, ty: g ? g.y + (Math.random() - 0.5) * miss : b.ty };
+      sight.set(b.slot, eye);
+      if (g) taken.add(g.id);
     }
-    if (best) { taken.add(best.id); b.tx = best.x; b.ty = best.y; }
-    const dx = b.tx - b.x; const dy = b.ty - b.y; const len = Math.hypot(dx, dy) || 1;
+    b.tx = eye.tx; b.ty = eye.ty;
+    const rival = nearestBody(b, KNOCK_RANGE); // AGGRESSION: waves at a rival in reach
+    if (rival && round?.phase === 'live' && Math.random() < s.aggression * 0.8 * dt) hostWave(b);
+    const dx = b.tx - b.x; const dy = b.ty - b.y; const dist = Math.hypot(dx, dy);
+    const len = dist || 1;
+    // Arrived where it aimed: it stands there, and notices what it missed only a reaction later.
+    if (dist < 6 && !eye.arrived) { eye.arrived = true; eye.at = now; }
+    const speed = dist < 6 ? 0 : BOT_SPEED;
     const k = Math.min(1, dt * 5);
-    b.vx += ((dx / len) * BOT_SPEED - b.vx) * k;
-    b.vy += ((dy / len) * BOT_SPEED - b.vy) * k;
+    b.vx += ((dx / len) * speed - b.vx) * k;
+    b.vy += ((dy / len) * speed - b.vy) * k;
     b.x = Math.max(R_AV, Math.min(W - R_AV, b.x + b.vx * dt));
     b.y = Math.max(R_AV, Math.min(H - R_AV, b.y + b.vy * dt));
   }
 }
 
+/** Positioning: 0 leaves the hot zone to the people, 1 fights for it. */
+function pickGem(b: Body, taken: Set<number>, s: Skill): Gem | null {
+  let best: Gem | null = null; let bd = Infinity;
+  for (const g of gems) {
+    if (taken.has(g.id)) continue;
+    const hot = zone !== null && Math.hypot(g.x - zone.x, g.y - zone.y) < zone.r;
+    const d = Math.hypot(g.x - b.x, g.y - b.y) * (hot ? 1.5 - s.positioning : 1);
+    if (d < bd) { bd = d; best = g; }
+  }
+  return best;
+}
+
+/** The nearest other body within `range` (a bot's rival), or null. */
+function nearestBody(b: Body, range: number): Body | null {
+  let best: Body | null = null; let bd = range;
+  for (const o of bodies.values()) {
+    if (o === b) continue;
+    const d = Math.hypot(o.x - b.x, o.y - b.y);
+    if (d < bd) { bd = d; best = o; }
+  }
+  return best;
+}
+
 function stepHost(dt: number): void {
   tick += 1;
   const seat = mySeat();
@@ -483,6 +543,7 @@ function stepHost(dt: number): void {
         const g = gems[i] as Gem;
         if (Math.hypot(g.x - b.x, g.y - b.y) < R_AV + R_GEM) {
           b.score += zone && Math.hypot(g.x - zone.x, g.y - zone.y) < zone.r ? 2 : 1;
+          pickups.set(b.slot, (pickups.get(b.slot) ?? 0) + 1);
           gems[i] = newGem();
         }
       }
@@ -665,9 +726,12 @@ function hud(cw: number, ch: number, phone: boolean, list: { slot: number; name:
   const rows = [...list].sort((a, b) => (scores.get(b.slot) ?? 0) - (scores.get(a.slot) ?? 0)).slice(0, phone ? 4 : 6);
   ctx.font = `600 ${phone ? 14 : 16}px ui-sans-serif, system-ui, sans-serif`;
   ctx.textAlign = 'right';
+  // The play page's room button (and a server's pill beside it) sit at the top right (game.json screen.share's
+  // default): the scores start under that band, so the buttons never cover a score.
+  const board = top + 18 + 44;
   rows.forEach((a, i) => {
     ctx.fillStyle = a.mine ? '#ffffff' : a.bot ? 'rgba(232,236,245,0.55)' : 'rgba(232,236,245,0.85)';
-    ctx.fillText(`${a.mine && !net.watching ? 'You' : label(a.name, a.bot)}  ${scores.get(a.slot) ?? 0}`, cw - pad, top + 18 + i * (phone ? 20 : 22));
+    ctx.fillText(`${a.mine && !net.watching ? 'You' : label(a.name, a.bot)}  ${scores.get(a.slot) ?? 0}`, cw - pad, board + i * (phone ? 20 : 22));
   });
   // role badge
   ctx.textAlign = 'left'; ctx.font = '600 11px ui-monospace, Menlo, monospace'; ctx.fillStyle = 'rgba(125,240,255,0.7)';
@@ -719,6 +783,10 @@ net.expose({
   },
   frames: () => frames,
   scores: () => (hosting ? [...bodies.values()].map((b) => ({ slot: b.slot, seat: b.seat, bot: b.bot, score: b.score })) : [...drawn.values()].map((d) => ({ slot: d.slot, seat: d.seat >= 0 ? d.seat : null, bot: d.seat < 0, score: d.score }))),
+  /** Host: gems each slot picked up this round, the round's age, and the dial each bot plays at (the dial's numbers). */
+  pickups: () => (hosting ? { round: round ? { n: round.n, phase: round.phase, ageMs: net.now() - round.startedAt } : null, slots: [...bodies.values()].map((b) => ({ slot: b.slot, bot: b.bot, gems: pickups.get(b.slot) ?? 0, level: b.bot ? net.skillOf(b.slot).level : null })) } : null),
+  /** Host: when each bot last looked (its reaction clock). */
+  sight: () => (hosting ? [...sight.entries()].map(([slot, e]) => ({ slot, at: e.at })) : null),
   waves: () => wavesSeen,
   knocks: () => knocksSeen,
   zone: () => zone,