@homie-rocks/studio 0.14.4 → 0.16.0

package/package.json

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

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/hud.ts

@@ -4,7 +4,8 @@
  * results card between rounds. Everything is text on small translucent chips;
  * nothing opaque sits in the middle of the screen during play; names are set
  * with textContent (people type them). A big screen (a spectator) gets the
- * same board without any "you".
+ * same board without any "you"; a watcher following a player (NETPLAY.md
+ * section 16) sees that player's row and result marked the way "you" is.
  *
  * A game with its own HUD should draw the same facts itself (clock from
  * room.clock(), results from room.results()) instead.
@@ -59,19 +60,21 @@ export function createHud<B extends BodyBase>(room: Room<B, any, any>, opts: Hud
   const paint = (): void => {
     const c = room.clock();
     clock.textContent = c.phase === 'none' ? 'Joining…' : c.phase === 'live' ? `Round ${c.n} · ${Math.floor(c.secondsLeft / 60)}:${String(c.secondsLeft % 60).padStart(2, '0')}` : `Next round in ${c.secondsLeft}`;
-    const me = room.mySeat();
+    // A watcher's followed player is marked as "you" is (net.watchedSeat says it without claiming the camera follows).
+    const me = room.net.watching ? room.net.watchedSeat : room.mySeat();
+    const watchingSeat = room.net.watching && me !== null;
     const rows = room.view().slice().sort((a, b) => b.score - a.score || Number(a.bot) - Number(b.bot)).slice(0, phone ? 4 : 5);
     board.textContent = '';
     for (const b of rows) {
       const d = document.createElement('div');
-      const mine = !spectator() && me !== null && b.seat === me && !b.bot;
+      const mine = (watchingSeat || !spectator()) && me !== null && b.seat === me && !b.bot;
       d.className = mine ? 'me' : b.bot ? 'bot' : '';
-      d.textContent = `${mine ? 'You' : b.name}${b.bot ? ' · bot' : ''}  ${b.score}`;
+      d.textContent = `${mine && !watchingSeat ? 'You' : b.name}${b.bot ? ' · bot' : ''}  ${b.score}`;
       board.append(d);
     }
     const r = room.round;
     if (r && r.phase === 'over' && r.results) {
-      const key = `${r.n}:${r.endsAt}`;
+      const key = `${r.n}:${r.endsAt}:${me}`;
       if (key !== lastResults) {
         lastResults = key;
         results.textContent = '';
@@ -79,8 +82,8 @@ export function createHud<B extends BodyBase>(room: Room<B, any, any>, opts: Hud
         const ol = document.createElement('ol');
         for (const row of r.results.slice(0, 6)) {
           const li = document.createElement('li');
-          const mine = !spectator() && me !== null && row.seat === me && !row.bot;
-          li.textContent = `${mine ? 'You' : row.name}${row.bot ? ' (bot)' : ''} — ${row.score}${opts.unit ? ` ${opts.unit}` : ''}`;
+          const mine = (watchingSeat || !spectator()) && me !== null && row.seat === me && !row.bot;
+          li.textContent = `${mine && !watchingSeat ? 'You' : row.name}${row.bot ? ' (bot)' : ''} — ${row.score}${opts.unit ? ` ${opts.unit}` : ''}`;
           if (mine) li.style.color = 'var(--hp-accent,#ffd166)';
           ol.append(li);
         }

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 }
@@ -83,6 +89,16 @@ export interface Room<B extends BodyBase, F = unknown, S = unknown> {
   readonly round: RoundInfo | null;
   /** My seat (0 when offline: a solo game with bots, the way a plain file or a dev server plays). */
   mySeat(): number | null;
+  /**
+   * WATCHING (NETPLAY.md section 16): whose camera and HUD to draw. My own seat when I play (0 offline); for a
+   * watcher, the seat it follows, or null for the overview camera. Point your camera at `viewBody()` (for your own
+   * seat, keep drawing your local body) and your HUD at its numbers; null: your spectator overview.
+   */
+  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. */
@@ -123,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;
@@ -134,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);
@@ -149,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);
   }
@@ -177,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 };
@@ -189,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 {
@@ -204,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();
     }
@@ -244,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); }
@@ -266,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);
@@ -283,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;
@@ -320,6 +350,14 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     get bodies() { return bodies; },
     get round() { return hosting ? round : (net.roundInfo ?? round); },
     mySeat,
+    viewSeat: () => (net.offline ? 0 : net.viewSeat),
+    viewBody() {
+      const s = net.offline ? 0 : net.viewSeat;
+      if (s === null) return null;
+      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/port/touch.ts

@@ -113,7 +113,10 @@ function isTouchDevice(): boolean {
 }
 
 export function createTouchControls(opts: TouchOptions = {}): TouchControls {
-  const enabled = Boolean(opts.force) || isTouchDevice();
+  // A spectator (a big screen, or a watcher: NETPLAY.md section 16) plays nothing: no stick, no buttons on its glass.
+  const shell = (globalThis as { HOMIE_NET?: { want?: string; watch?: boolean } }).HOMIE_NET;
+  const spectator = shell?.watch === true || shell?.want === 'screen';
+  const enabled = Boolean(opts.force) || (isTouchDevice() && !spectator);
   type StickCfg = { zone: [number, number, number, number]; radius: number; dead: number; keys: Partial<Record<Dir, string>> | false; fourWay: boolean };
   const stickOpt: StickCfg | null = opts.stick === false ? null : { zone: [0, 0.3, 0.55, 1], radius: 56, dead: 7, keys: false, fourWay: false, ...(opts.stick ?? {}) } as StickCfg;
   const lookOpt = opts.look ? { zone: [0.45, 0, 1, 1] as [number, number, number, number], ...opts.look } : null;

package/site/SITE.md

@@ -29,6 +29,8 @@ songs (each with a `cover`), videos (each with a `poster`), the latest posts, an
 (`homie-studio stats share on`) it also says "played this week": `played` for the whole studio and each game's own
 (`games[].played`, `{ "days": 7, "plays", "rounds" }`). To keep the studio's rooms off the hub, studio.json takes
 `"rooms": { "share": false }`: the manifest then names no `rooms` (the studio's own pages still list them).
+Each room in `/api/rooms` carries `play` and, unless its game says `"watch": false`, `watch` (its watch door), so
+the hub offers Watch beside Join.
 
 ## A game's landing: `/<id>/`
 
@@ -164,6 +166,75 @@ The game runs in a sandboxed frame with an opaque origin, which is why its allow
 (`fullscreen *; autoplay *; gamepad *`): Safari refuses a bare `gamepad` there (`getGamepads()` throws a
 SecurityError), so a controller would not work.
 
+## The watch door: `/<id>/watch?room=<room>`
+
+Anyone can watch a live room from any player's view (NETPLAY.md section 16). Every room row (Home, Rooms, a
+game's landing) has a **Watch** button beside Join, and a landing offers "Watch a live room" while somebody plays.
+The page is the game itself, drawn by the watcher's own browser as a watcher: a screen that never takes a seat.
+
+- **The top bar:** LIVE, the game and the room, the round's clock, how many are watching, and **Play** (into
+  this room). **The caption** says whose view this is ("Watching Velvet Comet", "Auto · following the action").
+- **The strip** at the bottom: **Auto**, each player (their colour, name and live score when the game exposes
+  `scores`; the leader's score lit), and **Whole room**. A tap switches; on a computer keys 1-9 pick the n-th
+  player, A is Auto, O (or 0) the whole room, the arrows the next or previous player, F full screen. The address
+  keeps the view (`&follow=<seat>|auto|overview`), so a copied link watches the same player.
+- It fits a phone (the strip scrolls sideways), a computer, and a TV-sized screen (bigger type; `?hand=tv`). The
+  bars fade after five seconds without a touch, a move or a key, and come back with one.
+- With no `room`, it watches the busiest public room (`/<id>/api/watch`, which reserves nothing); with nobody
+  playing it says so, offers Play, and finds a room the moment one starts. A room everyone left, a kick, a closed
+  room and a full one are each said plainly, with the way on.
+- **What a game decides.** A game that draws `net.viewSeat` lets the watcher switch; one that does not is watched
+  as its overview, and the strip only names the players. game.json `"watch": "overview"` keeps watchers on the
+  whole room (hidden hands or roles); `"watch": false` removes the door (the page says the game is played, not
+  watched, and the socket is refused).
+- **The same door as Play:** a private or invite-only game is watched only by those it lets in, with their
+  ticket; a kick holds the browser out of watching that room too. A browser that holds a seat in a room watches
+  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 ("First Light · Beginner"; tap: 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); the chip says "4 playing · 2 AI"; every AI row and result carries an AI pill.
+- **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
+  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

@@ -14,8 +14,16 @@
  * The host decides who killed what and sends the killer a `loot` event; only the hero's own browser changes the
  * hero and saves it. A hardcore hero who falls becomes a memorial in the Hall of the Fallen, and its save is wiped
  * in the same step (saves.fall). Canvas 2D on purpose: the point is the pattern, in a few hundred lines.
+ *
+ * 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;
@@ -35,11 +43,14 @@ 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];
 
 /* ------------------------------------------------------------------ the save */
+/** A spectator (a watcher, or a big screen) has no hero of its own: it never loads, makes or saves one. */
+const shellCfg = (globalThis as { HOMIE_NET?: { want?: string; watch?: boolean } }).HOMIE_NET;
+const lookOnly = shellCfg?.watch === true || shellCfg?.want === 'screen';
 const saves = createSaves({ game: 'ember-vale' });
 let hero: Hero | null = null;
 let heroLoaded = false;
@@ -50,6 +61,7 @@ function saveSoon(): void {
   saveTimer = setTimeout(() => { if (hero) void saves.set('hero', hero); }, 1000);
 }
 async function loadHero(): Promise<void> {
+  if (lookOnly) { heroLoaded = true; ui.paint(); return; }
   const h = await saves.get<Hero>('hero');
   hero = h && h.v === 1 ? h : null;
   heroLoaded = true;
@@ -140,6 +152,7 @@ net.on('event', (e: NetEvent) => {
   const d = (e.d ?? {}) as { xp?: number; gold?: number; cause?: string; to?: number };
   if (e.k === 'loot' && d.to === room.mySeat()) gain(Math.max(0, Number(d.xp) || 0), Math.max(0, Number(d.gold) || 0));
   if (e.k === 'down' && d.to === room.mySeat()) void fell(String(d.cause ?? 'a slime').slice(0, 40));
+  if (e.k === 'slain' && typeof (e.d as { seat?: unknown })?.seat === 'number') net.spotlight((e.d as { seat: number }).seat);
 });
 function tell(b: Body, k: 'loot' | 'down', d: Record<string, unknown>): void {
   if (b.bot || b.seat === null) return;
@@ -158,6 +171,8 @@ function strike(b: Body, now: number): void {
       const gold = s.size === 3 ? 50 : 2 + Math.floor(Math.random() * 4) * s.size;
       b.score += xp;
       tell(b, 'loot', { xp, gold });
+      // Everyone hears who slew it (a watcher on Auto cuts to them); the loot itself is the slayer's alone.
+      if (!b.bot && b.seat !== null) room.send('slain', { seat: b.seat });
     }
   }
   slimes = slimes.filter((s) => s.hp > 0);
@@ -179,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;
@@ -299,10 +323,12 @@ function draw(t: number): void {
     ctx.fillStyle = 'rgba(0,0,0,.5)'; ctx.fillRect(x - r, y + r + 4, r * 2, 4);
     ctx.fillStyle = '#ff7a59'; ctx.fillRect(x - r, y + r + 4, (r * 2 * clamp(hp, 0, max)) / max, 4);
   }
-  const mySeat = room.mySeat();
+  // The hero whose view this is: my own, or the one a watcher follows (null: the vale, nobody in gold).
+  const viewS = room.viewSeat();
   for (const b of room.view()) {
-    const self = !b.bot && b.seat === mySeat;
-    const x = self && !room.hosting ? me.x : b.x; const y = self && !room.hosting ? me.y : b.y;
+    const self = !b.bot && b.seat === viewS;
+    const local = self && !room.hosting && !net.watching;
+    const x = local ? me.x : b.x; const y = local ? me.y : b.y;
     const isDown = Boolean(b.flags & DOWN);
     ctx.globalAlpha = isDown ? 0.35 : 1;
     if ((b.flags & STRIKING) || (self && performance.now() - me.flashAt < 160)) { ctx.strokeStyle = 'rgba(255,207,110,.7)'; ctx.lineWidth = 4; ctx.beginPath(); ctx.arc(x, y, STRIKE_RANGE * 0.8, 0, Math.PI * 2); ctx.stroke(); }
@@ -313,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);
@@ -325,8 +352,23 @@ function hud(t: number): void {
   const x0 = 14; const y0 = 14;
   ctx.fillStyle = 'rgba(10,14,9,.62)'; ctx.fillRect(x0, y0, 240, 62);
   ctx.textAlign = 'left'; ctx.font = '700 16px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#ffcf6e';
-  ctx.fillText(hero ? `${hero.name}${hero.hardcore ? ' ☠' : ''} · Lv ${hero.level}` : heroLoaded ? 'No hero yet' : 'Loading your hero…', x0 + 10, y0 + 22);
-  if (hero) {
+  if (lookOnly) {
+    // A watcher's panel is the followed hero's, as the room has them (their save stays in their own browser).
+    const v = room.viewBody();
+    if (v) {
+      ctx.fillText(`${v.name} · Lv ${v.level}`, x0 + 10, y0 + 22);
+      ctx.fillStyle = 'rgba(255,255,255,.12)'; ctx.fillRect(x0 + 10, y0 + 32, 140, 6);
+      ctx.fillStyle = '#7ad35a'; ctx.fillRect(x0 + 10, y0 + 32, (140 * clamp(v.hp, 0, v.maxHp)) / Math.max(1, v.maxHp), 6);
+      ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
+      ctx.fillText(`${v.score} xp tonight${v.flags & DOWN ? ' · down' : ''}`, x0 + 10, y0 + 54);
+    } else {
+      const heroes = room.view().filter((b) => !b.bot).length;
+      ctx.fillText('Watching the vale', x0 + 10, y0 + 22);
+      ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
+      ctx.fillText(`${heroes} ${heroes === 1 ? 'hero' : 'heroes'} · ${(room.fast() ?? []).length} slimes`, x0 + 10, y0 + 46);
+    }
+  } else ctx.fillText(hero ? `${hero.name}${hero.hardcore ? ' ☠' : ''} · Lv ${hero.level}` : heroLoaded ? 'No hero yet' : 'Loading your hero…', x0 + 10, y0 + 22);
+  if (hero && !lookOnly) {
     ctx.fillStyle = 'rgba(255,255,255,.12)'; ctx.fillRect(x0 + 10, y0 + 32, 140, 6);
     ctx.fillStyle = '#ffcf6e'; ctx.fillRect(x0 + 10, y0 + 32, (140 * hero.xp) / xpFor(hero.level), 6);
     ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
@@ -341,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();
@@ -359,6 +401,7 @@ const ui = {
   paint(): void {
     const p = saves.player;
     $('who').textContent = p.local ? 'Playing here only' : p.signedIn ? `${p.name}${p.owner ? ' · owner' : ''}` : 'Guest · keep my hero';
+    $('who').hidden = lookOnly;
   },
   make(): void {
     ($('hero-name') as HTMLInputElement).value = '';
@@ -416,6 +459,9 @@ function frame(t: number): void {
   requestAnimationFrame(frame);
 }
 
+// Tonight's experience per hero: the watch page's live scores, and who Auto follows when nobody is slaying.
+net.expose({ scores: () => room.view().map((b) => ({ slot: b.slot, seat: b.seat, bot: b.bot, score: b.score })) });
+
 exposePort(net, {
   view: 'top',
   self: () => (me.has && room.mySeat() !== null ? { x: me.x, y: me.y } : null),