@homie-rocks/studio 0.30.2 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.30.2",
+  "version": "0.31.1",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,6 +50,14 @@
       "types": "./assets/animate.ts",
       "default": "./assets/animate.ts"
     },
+    "./personas": {
+      "types": "./port/personas.ts",
+      "default": "./port/personas.ts"
+    },
+    "./powerups": {
+      "types": "./port/powerups.ts",
+      "default": "./port/powerups.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -69,6 +77,7 @@
     "media/",
     "site/",
     "chat/",
+    "parts/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

package/parts/PARTS.md

@@ -0,0 +1,169 @@
+# Game parts
+
+Games build on each other by sharing **parts**: a piece of a game that its studio chooses to share, so somebody
+making another game can use it. A creature from one game, a level from another, a bot brain from a third. That is
+the whole idea. Without parts, a creator's AI has to come up with everything on its own.
+
+Mashing up is not a command: it is making a game with parts from several games.
+
+## The rules
+
+1. **A part is a piece of a game, never the whole game.** Remix, which handed over an entire game, is retired;
+   parts are what replaces it.
+2. **A part can take any form** that suits the piece: code, assets, data, a JSON description, a tuned config, or a
+   mix. Form is not restricted.
+3. **Private until shared.** A studio shares a part on purpose, with a licence (an SPDX identifier) and an
+   attribution. A part records the game and the studio it came from.
+4. **Homie packages are not parts.** The `@homie-rocks/*` packages are general mechanisms (camera, input, audio,
+   effects, netplay), installed from npm. They are never in the catalogue. A part may say which packages it builds
+   on; npm installs and resolves them. There is no resolver, no version ranges, no lockfile and no registry of
+   Homie's: nothing here rebuilds what already works.
+5. **Creators work in chat.** A person never types a command. The tools are few and named like the asset tools:
+   `parts_find`, `part_add`, `part_new` and `part_share` (sharing and un-sharing). Anything else is plumbing behind
+   those.
+6. **Agents look for parts first.** When planning or making a game, the agent checks the packages for general
+   mechanisms and `parts_find` for pieces other studios shared, before writing from scratch; it records in the
+   game's CODEX and its credits what came from where.
+
+## In chat
+
+- "What parts are there for a chase camera?" (`parts_find`)
+- "Add the Pickup field part from owls.example/pickup-field to my game." (`part_add`)
+- "Make the creature in my game a part." (`part_new`)
+- "Share the creature part under CC BY." / "Stop sharing it." (`part_share`)
+
+## How a part moves
+
+**Share.** The creator asks. `part_new` lifts a piece out of one of their games into `parts/<id>/`: the files
+move, each module's old path keeps a line that re-exports the part's, and the game still builds and plays the same.
+A file that reaches into the rest of the game is refused by name (pass what it needs in as an argument first), and
+so is the game's own entry, page or `game.json`: a part is never the whole game. `part_share` marks it shared with
+its licence. It is **live after the studio's next deploy**, not before. The studio's site lists its shared parts at
+`/.well-known/homie-parts.json` and serves their content; **a private part is never reachable**.
+
+**Catalogue.** `https://homie.rocks/parts/` indexes the shared parts of studios that are already listed (it never
+lists a studio), searchable by kind, tag, licence and what a part builds on; each part shows its game, studio,
+licence, attribution and a preview. `/parts/index.json` there is what `parts_find` reads. When it cannot be
+reached, `parts_find` says so plainly and still answers with the studio's own parts: an empty list never stands in
+for "could not look".
+
+**Use.** The creator asks for a piece. `part_add` fetches **one exact version** (the latest shared unless one is
+named), checks its integrity (every file's SHA-256 and size, before a byte is written), copies it into the studio
+at `parts/_vendor/<host>/<id>/` (theirs to tune from then on), records where it came from in `parts/origins.json`,
+adds the credit to the game's `credits.json`, and lets npm install any packages it builds on. Adding it again
+later brings the newer version: what changed is shown, local tuning (`tuning.json`) is kept, and a file the studio
+edited is never replaced without saying so.
+
+**Publishing a game that uses parts** shows their licences and attributions, and says plainly when licences cannot
+be combined.
+
+## A part on disk
+
+`parts/<id>/part.json`, with the part's files beside it (`id`: lowercase letters, digits and hyphens; the folder is
+named after it):
+
+```json
+{
+  "id": "pickup-field",
+  "name": "Pickup field",
+  "kind": "mechanic",
+  "version": "1.0.0",
+  "summary": "Host-authoritative pickups on spawn spots.",
+  "license": "CC-BY-4.0",
+  "attribution": "Night Owls",
+  "share": false,
+  "tags": ["pickups", "netplay"],
+  "from": { "game": "gem-cave", "studio": "Night Owls" },
+  "entry": "src/index.ts",
+  "files": [{ "path": "src/index.ts", "sha256": "…", "bytes": 1234 }],
+  "preview": { "page": "preview/index.html", "image": "preview/cover.jpg", "aspect": "4:3", "phoneAspect": "3:4" },
+  "requires": { "packages": { "@homie-rocks/camera": "^0.2.0" }, "parts": ["other-studio.example/some-part"] },
+  "physical": { "units": "metres", "scale": 1, "pivot": "feet", "collision": "collision.json" },
+  "skeleton": { "rig": "humanoid-v1", "clips": ["idle", "run"] },
+  "contract": { "inputs": {}, "state": {}, "netplay": "host-authoritative" },
+  "cost": { "triangles": 0, "drawCalls": 0, "textureMB": 0, "bytes": 0, "measuredOn": "…" },
+  "provenance": { "source": "original", "notes": "" }
+}
+```
+
+| Field | What it is |
+| --- | --- |
+| `id`, `name`, `kind`, `version`, `summary` | `version` is three numbers; a shared version never changes, so a change is a new version. `summary` is one sentence. |
+| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. There is no kind for a whole game. |
+| `license`, `attribution` | Needed to share: an SPDX identifier, and who a game using the part credits. |
+| `share` | **Default `false`.** The part's own switch, and the only thing that decides whether it is shared. |
+| `from` | The game and studio the part came out of. Written when a part is lifted out of a game. |
+| `entry` | For a part with code: the module a game imports. A part of assets or data has none. |
+| `files` | Every file with its SHA-256 and size, **written by the tool, never by hand**. A file may carry `"rights"` (below). |
+| `preview` | `page`: a self-contained HTML page shown in a sandboxed frame. `image`: a still. `aspect`: the frame's shape as `"W:H"` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; default `"16:9"`). `phoneAspect`: the shape when the frame is narrower than 600 px. |
+| `requires.packages` | The npm packages it builds on, as `package.json` would name them. npm reads them; nothing else does. |
+| `requires.parts` | Other parts it needs: a plain list of `"<host>/<id>"`. Named to the person, never solved. |
+| `physical`, `skeleton`, `contract`, `cost` | Optional descriptions for whoever uses the piece: its scale, pivot and collision data; its rig and clips; its inputs, state and who decides in a room (`host-authoritative`, `replicated`, `local`); device costs that were measured (never guessed). |
+| `provenance` | `source`: `original`, `generated` or `imported` (with `origin`). Needed to share. |
+
+A field this file does not name is kept and ignored. A field whose name starts with `_` never leaves the studio.
+`tuning.json` in a part holds its tunables: it ships as the author's defaults and is the one file a newer version
+never overwrites (the new defaults arrive beside it as `tuning.upstream.json`).
+
+**Sharing is refused**, in plain words, when: there is no SPDX licence; the licence asks for credit and nobody is
+named; the part does not say where it came from; or the rights to a file are unknown. A file's rights are its own
+`"rights"` (`{ "license": "<SPDX>" }` or `"unknown"`), else the record of a game asset with the same bytes
+(`games/<id>/assets/manifest.json`: a store-licensed or bought file cannot be shared inside a part), else the
+part's `provenance`.
+
+**Licences that cannot be combined** (shown when a part is added and before a game goes online): two parts under
+different share-alike licences in one game; a non-commercial part in a studio with a shop; a no-derivatives part
+whose files were changed locally; a part with no licence; credit owed and missing from the game's credits. A
+share-alike part is pointed out for the person's decision, and a licence the toolkit does not know is said to be
+one to read.
+
+## What a studio's site serves
+
+`sharedPartsOf(studio)` (`lib/parts.mjs`) is the single answer to what a studio shares: its parts with
+`share: true` that have a packed version. The build writes exactly that into the site, and the site, the
+well-known file and through them the hub read nothing else.
+
+- `GET /.well-known/homie-parts.json` → `{ "v": 1, "studio": { "name", "url" }, "parts": [ … ] }`. Each entry is the
+  part's `part.json` (latest version), plus `"url": "/parts/<id>/<version>/"`, `"page": "/parts/<id>/"`,
+  `"versions": [ … ]`, `"add": "<host>/<id>"`, and for a part from one of the studio's public games
+  `"from": { "game", "name", "studio", "page", "play" }`, so a catalogue can show and group by game. CORS open for
+  GET. No shared part: the same shape with `"parts": []`.
+- `GET /parts/<id>/<version>/part.json` and `/parts/<id>/<version>/<file path>`: the content exactly as hashed,
+  immutable (a year's cache), CORS open, GET and HEAD only. An HTML file among them (a preview) is served
+  sandboxed, so it runs without the site's cookies or storage.
+- `GET /parts/` and `/parts/<id>/`: the studio's own pages in its own look (each part's game, licence,
+  attribution, preview, what it builds on and costs, and what to say in chat to add it), and a **Parts from this
+  game** band on a game's landing page.
+
+**Declare the shape of an interactive preview.** The default frame is 16:9, and across a 390 px phone that is
+about 197 px tall: a heading and two buttons fill it, and what the preview draws below them is cut off with no
+error to notice. Say `"aspect"` and `"phoneAspect"` in `preview` for a preview somebody plays with. With neither, a
+narrow frame is at least 320 px tall (70% of a short screen), and every preview has an **Open the preview** link
+that shows it in a tab of its own.
+
+Sharing packs the part: the exact bytes of that version are kept in `parts/_packed/<id>/<version>/`, and every
+packed version of a shared part is served, so "one exact version" stays true after a newer one ships.
+
+## Using a part in a game
+
+```ts
+import { createPickupField } from '@parts/owls.example/pickup-field';   // a part brought in
+import { chasePose } from '@parts/chase-camera';                        // one of the studio's own
+import table from '@parts/owls.example/loot-table/table.json';          // any file of a part
+```
+
+The build resolves `@parts/<host>/<id>` to the part's `entry` in `parts/_vendor/<host>/<id>/`, and `@parts/<id>`
+to `parts/<id>/`, and bundles it into the game. A game that imports a brought-in part is credited for it by the
+build, whether or not the add named the game.
+
+## For whoever works on the toolkit
+
+- `lib/parts.mjs` the format, hashes, lifting, sharing checks, `sharedPartsOf`, licences; `lib/parts-store.mjs`
+  find, add, share (one injectable `fetch`, one injectable npm runner: tests touch neither the network nor the
+  registry); `lib/parts-build.mjs` the build's three call-outs; `lib/parts-tools.mjs` the four chat tools;
+  `worker/parts.mjs` everything the site serves.
+- Packages: `npm ls <name>@<spec>` says whether the studio has one; `npm install --save-exact <name>@<spec>`
+  installs what is missing, after one line saying what and why; npm's output and errors are relayed as they are.
+  A package the studio's own `package.json` already names at a version npm says does not fit is explained and left
+  alone.
+- The plumbing behind the tools is `homie-studio parts find | new | add | share | unshare | check`.

package/port/index.ts

@@ -15,6 +15,10 @@
  *   createHud    a minimal clock / scores / results overlay
  *   BotBrain, seek, nearest, rubberBand
  *                bot scaffolds; `skill` makes a bot play at the room's dial (NETPLAY.md section 17)
+ *   createPersonaBrain, PERSONAS, botStats
+ *                bots that want different things (port/personas.ts; also @homie-rocks/studio/personas, with no port shims)
+ *   createPowerups, stepPowerups, collectPowerups, resolveHit, packPowerups
+ *                host-owned pickups whose timers survive a host change (port/powerups.ts; also @homie-rocks/studio/powerups)
  *   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)
@@ -32,10 +36,12 @@ export { createControls, type Controls, type ControlsOptions } from './controls'
 export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLike } from './camera';
 export { fitView, easeView, toScreen, createLabels, type Fit, type FitOptions, type LabelIn, type LabelOut, type LabelOptions, type LabelBox } from './view';
 export { createBubbles, paintBubbles, wrapText, BUBBLE_FONT, type Bubbles, type BubbleOptions, type BubbleIn, type BubbleOut, type BubbleStyle } from './view';
-export { exposePort, type PortProbeOptions, type View } from './probe';
-export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
+export { exposePort, PORT_EXTRA_NAMES, type PortExtra, type PortProbeOptions, type View } from './probe';
+export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt, type TakeoverInfo, type Fallback, type Standing } from './room';
 export { createHud, type HudOptions } from './hud';
 export { BotBrain, brainOf, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';
 export { jitter, engages, standoff } from './skill';
+export * from './personas';
+export * from './powerups';
 export { lab, type TunableSpec, type TunableFile, type Tuned } from '../lab/lab';
 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/personas.ts

@@ -0,0 +1,275 @@
+/*
+ * @homie-rocks/studio/personas: bots that want different things.
+ * =============================================================================
+ *
+ * A room of bots that all run the same "go to the nearest thing" code reads as one bot drawn several times. What
+ * makes them read as characters is not smarter code, it is DIFFERENT WANTS: one crosses the map for the biggest
+ * prize, one hunts other players, one keeps its speed up, one tidies up scraps, one stays away from everybody.
+ *
+ * So a persona here is a row of weights and nothing else, over one scorer:
+ *
+ *     score = kind weight x value^valuePow / (distance + near)^distPow x facing x sight x company x size
+ *
+ *   facing    a target behind costs up to `heading` of its score (a racer will not turn round; a glutton will)
+ *   sight     a target with a wall in the way costs up to `blind` of it (line of sight over the game's own
+ *             `solid(x, y)`: the same function its walls already answer)
+ *   company   every rival near the target raises (a bully) or lowers (a sneak) it by `crowd`
+ *   size      a rival bigger than the bot costs up to `bigger` of it: nobody picks a fight they lose
+ *
+ * FIVE ARE BUILT IN (glutton, bully, racer, scavenger, sneak) and a game extends one with `persona('sneak', {...})`
+ * or writes its own row. The kinds they weigh ('food', 'scrap', 'rival', 'power', 'gate') are only names: a game
+ * tags its candidates with whichever fit, and any other kind scores at the persona's `other`.
+ *
+ * IT FITS THE PORT KIT'S BotBrain, it does not replace it. BotBrain is the bot's LIMITS (it reacts late, aims a
+ * little off, commits for a while: the room's skill dial); a persona is what it WANTS. `brain.chooser(...)` is the
+ * `choose` function BotBrain.think takes, so the dial keeps working:
+ *
+ *     const who = createPersonaBrain(PERSONAS.bully, { rng, arena: { solid } });
+ *     const stick = botBrain.think(now, pos, who.chooser(() => self, () => candidates, () => rivals));
+ *     const push = who.steer(self, stick);            // the same push, turned off any wall ahead
+ *
+ * TELEMETRY IS PART OF IT, because "the personas differ" is a claim, and a weight table that produces five bots
+ * who all end up eating the nearest pellet is the usual result of tuning by eye. Every brain counts what it picked
+ * (`stats()`), `botStats` puts brains side by side, and `personaSpread` is one number for how unlike each other
+ * they were. A game's own test runs its arena and asserts on those.
+ *
+ * DETERMINISTIC: the only randomness is the `rng` you pass (`seededRng(seed)` is one), drawn once a pick and only
+ * when the persona is `fickle`. The host owns the bots, so the same seed and the same world give the same game.
+ *
+ * Positions are the game's own flat units: `x, y` on the ground plane (a 3D game passes x and z).
+ * =============================================================================
+ */
+import type { V2 } from './bots';
+
+/** Something a bot could go for. `value` is the game's own measure (points, mass, seconds saved): more is better. */
+export interface Candidate extends V2 {
+  kind: string;
+  value: number;
+  id?: string | number;
+  /** For a `rival`: how big it is, in the same measure as the bot's own `size`. */
+  size?: number;
+}
+/** Another body in the arena, for `crowd`: a player or a bot, not the bot itself. */
+export interface Rival extends V2 { size?: number }
+/** The bot: where it is, which way it faces (radians, `atan2(y, x)`), and how big it is. */
+export interface BotSelf extends V2 { heading: number; size?: number }
+
+/** A row of weights. Every field is a number a game may change. */
+export interface Persona {
+  name: string;
+  /** How much each kind of candidate is wanted. A kind not listed scores at `other`. */
+  kinds: Record<string, number>;
+  other: number;
+  /** How much a bigger prize matters: 0 ignores value, 1 is proportional, 2 chases the jackpot. */
+  valuePow: number;
+  /** How much distance matters: 0 ignores it, 1 is value per metre, 2 hardly leaves the spot. */
+  distPow: number;
+  /** 0 to 1: the share of a target's score lost when it is directly behind. */
+  heading: number;
+  /** 0 to 1: the share lost when a wall is between the bot and the target. */
+  blind: number;
+  /** For each rival near the target: above 0 raises its score by this share, below 0 lowers it. */
+  crowd: number;
+  /** 0 to 1: the share of a rival's score lost when the rival is bigger than the bot. */
+  bigger: number;
+  /** How hard it turns away from a wall ahead (0 not at all, 1 fully). */
+  wall: number;
+  /** 0 to 1: random spread on every score, from the injected rng. 0 draws nothing. */
+  fickle: number;
+}
+
+export type PersonaName = 'glutton' | 'bully' | 'racer' | 'scavenger' | 'sneak';
+
+/** The five. Frozen: extend one with `persona()`. */
+export const PERSONAS: Readonly<Record<PersonaName, Persona>> = Object.freeze({
+  /** Crosses the arena for the biggest prize and barely notices anybody. */
+  glutton: Object.freeze({ name: 'glutton', kinds: { food: 1, scrap: 0.5, power: 0.6, rival: 0.05, gate: 0.2 }, other: 0.3, valuePow: 2, distPow: 0.5, heading: 0.1, blind: 0.2, crowd: 0, bigger: 0.9, wall: 0.7, fickle: 0 }),
+  /** Goes for other bodies, smaller ones first, and for whatever they are near. */
+  bully: Object.freeze({ name: 'bully', kinds: { rival: 4, power: 1, food: 0.3, scrap: 0.4, gate: 0.1 }, other: 0.3, valuePow: 1, distPow: 1, heading: 0.3, blind: 0.5, crowd: 0.4, bigger: 0.9, wall: 0.7, fickle: 0 }),
+  /** Keeps its line: what is ahead beats what is better, and gates beat everything. */
+  racer: Object.freeze({ name: 'racer', kinds: { gate: 4, power: 1.2, food: 0.5, scrap: 0.2, rival: 0.05 }, other: 0.3, valuePow: 0.5, distPow: 1, heading: 0.95, blind: 0.6, crowd: 0, bigger: 0.9, wall: 1, fickle: 0 }),
+  /** Takes the nearest small thing, and scraps before anything fresh. */
+  scavenger: Object.freeze({ name: 'scavenger', kinds: { scrap: 4, food: 1, power: 0.5, rival: 0.02, gate: 0.1 }, other: 0.5, valuePow: 0.25, distPow: 2, heading: 0.2, blind: 0.7, crowd: -0.15, bigger: 1, wall: 0.7, fickle: 0 }),
+  /** Wants whatever nobody is near, and power-ups most of all. */
+  sneak: Object.freeze({ name: 'sneak', kinds: { power: 2.5, food: 1, scrap: 1.5, rival: 0.3, gate: 0.2 }, other: 0.5, valuePow: 0.6, distPow: 1, heading: 0.2, blind: 0.1, crowd: -0.9, bigger: 1, wall: 0.8, fickle: 0 }),
+});
+
+/** A built-in persona with some weights changed (its `kinds` are merged, not replaced). */
+export function persona(base: PersonaName | Persona, change: Partial<Persona> = {}): Persona {
+  const b = typeof base === 'string' ? PERSONAS[base] : base;
+  return { ...b, ...change, kinds: { ...b.kinds, ...(change.kinds ?? {}) } };
+}
+
+/** What a persona's choices are made in. */
+export interface Arena {
+  /** The game's own collision: true where a body cannot be. Without it nothing is ever blind or avoided. */
+  solid?: (x: number, y: number) => boolean;
+  /** Units between samples along a line of sight (default 0.5). Smaller than the thinnest wall. */
+  sightStep?: number;
+  /** Units added to every distance, so a thing underfoot does not score infinitely (default 1). */
+  near?: number;
+  /** How close to a target a rival counts as company (default 6). */
+  crowdRadius?: number;
+  /** How far ahead a bot feels for walls (default 3). */
+  look?: number;
+}
+
+/** Whether a straight line between two points is free of `solid`, sampled every `step`. The ends are not tested. */
+export function lineOfSight(a: V2, b: V2, solid: (x: number, y: number) => boolean, step = 0.5): boolean {
+  const d = Math.hypot(b.x - a.x, b.y - a.y);
+  const n = Math.ceil(d / Math.max(1e-6, step));
+  for (let i = 1; i < n; i += 1) if (solid(a.x + (b.x - a.x) * (i / n), a.y + (b.y - a.y) * (i / n))) return false;
+  return true;
+}
+
+/** One candidate's score for one persona, with the parts it was made from (they are what the telemetry counts). */
+export interface Scored { c: Candidate; score: number; dist: number; facing: number; seen: boolean; company: number }
+
+export function scoreCandidate(self: BotSelf, c: Candidate, p: Persona, arena: Arena = {}, rivals: readonly Rival[] = []): Scored {
+  const dx = c.x - self.x; const dy = c.y - self.y; const dist = Math.hypot(dx, dy);
+  // 1 dead ahead, -1 directly behind; a thing underfoot is "ahead".
+  const facing = dist < 1e-9 ? 1 : (dx * Math.cos(self.heading) + dy * Math.sin(self.heading)) / dist;
+  const seen = arena.solid ? lineOfSight(self, c, arena.solid, arena.sightStep ?? 0.5) : true;
+  const r = arena.crowdRadius ?? 6;
+  let company = 0;
+  // A rival that IS the candidate (the same spot) is not its own company.
+  for (const o of rivals) if (!(o.x === c.x && o.y === c.y) && Math.hypot(o.x - c.x, o.y - c.y) <= r) company += 1;
+  let score = (p.kinds[c.kind] ?? p.other) * Math.pow(Math.max(0, c.value), p.valuePow) / Math.pow(dist + (arena.near ?? 1), p.distPow);
+  score *= 1 - p.heading * (1 - facing) / 2;
+  if (!seen) score *= 1 - p.blind;
+  score *= Math.max(0, 1 + p.crowd * company);
+  if (c.kind === 'rival' && c.size !== undefined && self.size !== undefined && c.size > self.size) score *= 1 - p.bigger;
+  return { c, score, dist, facing, seen, company };
+}
+
+/** The best candidate for a persona, or null when there is none worth anything. Ties go to the one listed first. */
+export function pickCandidate(self: BotSelf, candidates: readonly Candidate[], p: Persona, arena: Arena = {}, rivals: readonly Rival[] = [], rng?: () => number, keep?: Candidate | null): Scored | null {
+  let best: Scored | null = null;
+  for (const c of candidates) {
+    const s = scoreCandidate(self, c, p, arena, rivals);
+    // A little loyalty to the target it already has, so two near-equal prizes do not make it dither between them.
+    if (keep && (c === keep || (c.id !== undefined && c.id === keep.id))) s.score *= 1.25;
+    if (p.fickle > 0 && rng) s.score *= 1 + (rng() - 0.5) * 2 * p.fickle;
+    if (s.score > 0 && (!best || s.score > best.score)) best = s;
+  }
+  return best;
+}
+
+/**
+ * Turn a push away from a wall ahead: three feelers (ahead, and 40 degrees to each side) `look` units long over the
+ * game's `solid`. A blocked feeler turns the push toward the open side by `strength`. `steered` says it had to.
+ */
+export function avoidWalls(pos: V2, push: V2, solid: (x: number, y: number) => boolean, look = 3, strength = 1): V2 & { steered: boolean } {
+  const m = Math.hypot(push.x, push.y);
+  if (m < 1e-9 || strength <= 0) return { x: push.x, y: push.y, steered: false };
+  const a = Math.atan2(push.y, push.x);
+  // How far each feeler gets before something solid, as a share of its length.
+  const feel = (off: number): number => {
+    for (let i = 1; i <= 6; i += 1) { const d = (look * i) / 6; if (solid(pos.x + Math.cos(a + off) * d, pos.y + Math.sin(a + off) * d)) return (i - 1) / 6; }
+    return 1;
+  };
+  const ahead = feel(0); const left = feel(0.7); const right = feel(-0.7);
+  if (ahead >= 1 && left >= 1 && right >= 1) return { x: push.x, y: push.y, steered: false };
+  // Turn toward whichever side is more open; with nothing to choose between them, left, every time.
+  const turn = (left >= right ? 1 : -1) * strength * (1 - Math.min(ahead, left, right)) * 1.2;
+  return { x: Math.cos(a + turn) * m, y: Math.sin(a + turn) * m, steered: true };
+}
+
+/** What one brain did, counted. The numbers a game's test asserts on to show its personas differ. */
+export interface BotStats {
+  persona: string;
+  /** Times it was asked, and times it changed to a different target. */
+  thinks: number; picks: number;
+  /** Picks of each kind. */
+  byKind: Record<string, number>;
+  /** Means over its picks: the prize's value, the distance to it, how far ahead it was (1 ahead, -1 behind), rivals near it. */
+  meanValue: number; meanDist: number; meanFacing: number; meanCompany: number;
+  /** Picks made with a wall in the way, and pushes that had to be turned off a wall. */
+  blindPicks: number; wallSteers: number;
+}
+
+export interface PersonaBrain {
+  readonly persona: Persona;
+  /** The target in force (the last pick), or null. */
+  readonly target: Candidate | null;
+  /** Pick now. Counted as a pick only when the target changes. */
+  choose(self: BotSelf, candidates: readonly Candidate[], rivals?: readonly Rival[]): Candidate | null;
+  /** The same, shaped as the `choose` BotBrain.think takes. */
+  chooser(self: () => BotSelf, candidates: () => readonly Candidate[], rivals?: () => readonly Rival[]): () => Candidate | null;
+  /** A push (a stick vector) turned away from walls, by this persona's `wall` weight. */
+  steer(self: V2, push: V2): V2;
+  stats(): BotStats;
+  /** Forget the target and the counts (a new round). */
+  reset(): void;
+}
+
+export function createPersonaBrain(p: Persona, opts: { rng?: () => number; arena?: Arena } = {}): PersonaBrain {
+  const arena = opts.arena ?? {};
+  let target: Candidate | null = null;
+  let n = { thinks: 0, picks: 0, value: 0, dist: 0, facing: 0, company: 0, blind: 0, steers: 0, byKind: {} as Record<string, number> };
+  const same = (a: Candidate | null, b: Candidate | null): boolean => a === b || (!!a && !!b && a.id !== undefined && a.id === b.id);
+  const brain: PersonaBrain = {
+    persona: p,
+    get target() { return target; },
+    choose(self, candidates, rivals = []) {
+      n.thinks += 1;
+      // A target that is gone (eaten, expired) is not kept: it is no longer among the candidates.
+      const keep = target && candidates.some((c) => same(c, target)) ? target : null;
+      const best = pickCandidate(self, candidates, p, arena, rivals, opts.rng, keep);
+      if (best && !same(best.c, target)) {
+        n.picks += 1; n.value += best.c.value; n.dist += best.dist; n.facing += best.facing; n.company += best.company;
+        if (!best.seen) n.blind += 1;
+        n.byKind[best.c.kind] = (n.byKind[best.c.kind] ?? 0) + 1;
+      }
+      target = best ? best.c : null;
+      return target;
+    },
+    chooser(self, candidates, rivals) { return () => brain.choose(self(), candidates(), rivals ? rivals() : []); },
+    steer(self, push) {
+      if (!arena.solid) return push;
+      const out = avoidWalls(self, push, arena.solid, arena.look ?? 3, p.wall);
+      if (out.steered) n.steers += 1;
+      return { x: out.x, y: out.y };
+    },
+    stats() {
+      const k = Math.max(1, n.picks);
+      return { persona: p.name, thinks: n.thinks, picks: n.picks, byKind: { ...n.byKind }, meanValue: n.value / k, meanDist: n.dist / k, meanFacing: n.facing / k, meanCompany: n.company / k, blindPicks: n.blind, wallSteers: n.steers };
+    },
+    reset() { target = null; n = { thinks: 0, picks: 0, value: 0, dist: 0, facing: 0, company: 0, blind: 0, steers: 0, byKind: {} }; },
+  };
+  return brain;
+}
+
+/** Brains side by side: one row each, in the order given. */
+export function botStats(brains: readonly PersonaBrain[]): BotStats[] { return brains.map((b) => b.stats()); }
+
+/** The share of a brain's picks that were of one kind (0 with no picks). */
+export const kindShare = (s: BotStats, kind: string): number => (s.picks ? (s.byKind[kind] ?? 0) / s.picks : 0);
+
+/**
+ * How unlike each other a set of bots behaved: for every pair, the distance between what they picked (the share of
+ * each kind), 0 for identical and 1 for nothing in common; the answer is the SMALLEST pair's. A value near 0 means
+ * two of them are the same bot under two names, whatever their weights say.
+ */
+export function personaSpread(rows: readonly BotStats[]): number {
+  let least = Infinity;
+  for (let i = 0; i < rows.length; i += 1) for (let j = i + 1; j < rows.length; j += 1) {
+    const a = rows[i] as BotStats; const b = rows[j] as BotStats;
+    let d = 0;
+    for (const k of new Set([...Object.keys(a.byKind), ...Object.keys(b.byKind)])) d += Math.abs(kindShare(a, k) - kindShare(b, k));
+    least = Math.min(least, d / 2);
+  }
+  return Number.isFinite(least) ? least : 0;
+}
+
+/** A small seeded generator (mulberry32): the same seed, the same numbers, on every browser. */
+export function seededRng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}