@homie-rocks/studio 0.22.0 → 0.23.0

package/port/view.ts

@@ -11,6 +11,10 @@
  *                         label is placed first and nothing covers it; a moved label keeps its new spot while it is
  *                         free (no flicker), and labels fade in and out rather than pop.
  *
+ *   createBubbles()       speech bubbles over characters (room chat, NETPLAY.md section 19): what a player said, over
+ *                         their body for a few seconds, the player's own placed first, never covering another bubble;
+ *                         `paintBubbles` draws them on a canvas, and their boxes keep the name labels off them.
+ *
  * Everything is in CSS pixels (screen) and world units; the game draws. See the starters (gem-rush, ember-vale).
  */
 
@@ -211,3 +215,237 @@ export function createLabels(opts: LabelOptions = {}): { place(labels: LabelIn[]
     },
   };
 }
+
+/* ------------------------------------------------------------------ speech bubbles (room chat, NETPLAY.md section 19) */
+
+export interface BubbleOptions {
+  /** A line's width as drawn, CSS px: `(t) => ctx.measureText(t).width` with the bubble's font set (paintBubbles uses BUBBLE_FONT). */
+  measure: (text: string) => number;
+  /** A text line's height, CSS px (default 17). */
+  lineHeight?: number;
+  /** The widest a bubble's text gets before it wraps, CSS px (default 190). */
+  maxWidth?: number;
+  /** Lines at most; the rest is cut with "…" (default 3). */
+  maxLines?: number;
+  /** How long a message stays, ms: default 4 s and 50 ms a character (at most 9 s); an emoji 2.6 s. */
+  ms?: (b: { text: string; kind: 'text' | 'line' | 'react' }) => number;
+  /** Space inside the bubble, CSS px (default x 8, y 5). */
+  pad?: { x: number; y: number };
+  /** The tail under the bubble, CSS px (default 7). */
+  tail?: number;
+  /** CSS px kept clear between two bubbles (default 4). */
+  gap?: number;
+  /** The screen, so a bubble is never pushed off it (default the window). */
+  screen?: () => { w: number; h: number };
+  /** Milliseconds now (default performance.now()). */
+  now?: () => number;
+  /** Boxes bubbles keep clear of, CSS px (a game's own speech bubbles, a panel): a bubble moves up past them. */
+  avoid?: () => LabelBox[];
+}
+
+export interface BubbleIn {
+  /** Whose bubble: the key `say(key, …)` was given (a seat, a slot). */
+  key: string | number;
+  /** Where the tail points, CSS px: just over the body's name label (its box's top middle) or its head. */
+  x: number;
+  y: number;
+  /** The player's own (or the player a watcher follows): placed first. */
+  self?: boolean;
+}
+
+export interface BubbleOut extends LabelBox {
+  key: string | number;
+  id: string;
+  kind: 'text' | 'line' | 'react';
+  /** The text, wrapped: one string per line (one line with the glyph for an emoji). */
+  lines: string[];
+  /** An emoji-only bubble (a reaction): draw it bigger, no words. */
+  emoji: boolean;
+  lineHeight: number;
+  pad: { x: number; y: number };
+  /** Where the tail points (the anchor), and the bubble's middle. */
+  tip: { x: number; y: number };
+  cx: number;
+  cy: number;
+  /** 0..1: fading in and out. `scale` pops in from 0.86. */
+  alpha: number;
+  scale: number;
+}
+
+export interface Bubbles {
+  /** A message over `key`'s character: it replaces what that key was saying. `id` lets `remove(id)` take it down. */
+  say(key: string | number, text: string, o?: { id?: string; kind?: 'text' | 'line' | 'react' }): void;
+  /** The studio took a message down (net.on('unchat')): its bubble goes at once. */
+  remove(id: string): void;
+  /** Every bubble, or one key's, goes. */
+  clear(key?: string | number): void;
+  /** Each frame: where every speaking key's anchor is now. Keys not in the list are not drawn (off screen). */
+  place(anchors: BubbleIn[], dt?: number): BubbleOut[];
+  /** The boxes placed last frame: give them to createLabels' `avoid` so names keep off the bubbles. */
+  boxes(): LabelBox[];
+  /** How many keys are speaking now. */
+  readonly size: number;
+}
+
+/** The bubble's font (paintBubbles draws with it; measure with it too). */
+export const BUBBLE_FONT = '600 14px ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif';
+
+/** Words to lines no wider than `max` (a word wider than a line is broken), at most `n` lines (the last cut with …). */
+export function wrapText(text: string, max: number, measure: (t: string) => number, n = 3): string[] {
+  const words = String(text ?? '').replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
+  const lines: string[] = [];
+  let cur = '';
+  const push = (s: string): void => { lines.push(s); };
+  for (const w0 of words) {
+    let w = w0;
+    // A word wider than a line: broken by characters.
+    while (measure(w) > max) {
+      let cut = [...w].length - 1;
+      const chars = [...w];
+      while (cut > 1 && measure(chars.slice(0, cut).join('')) > max) cut -= 1;
+      if (cur) { push(cur); cur = ''; }
+      push(chars.slice(0, cut).join(''));
+      w = chars.slice(cut).join('');
+    }
+    const next = cur ? `${cur} ${w}` : w;
+    if (measure(next) <= max) cur = next; else { if (cur) push(cur); cur = w; }
+  }
+  if (cur) push(cur);
+  if (lines.length <= n) return lines;
+  const kept = lines.slice(0, n);
+  let last = `${kept[n - 1]}…`;
+  while (measure(last) > max && last.length > 2) last = `${[...last].slice(0, -2).join('')}…`;
+  kept[n - 1] = last;
+  return kept;
+}
+
+/**
+ * Speech bubbles over characters: what a player said in the room's chat, over their body, for a few seconds. Feed it
+ * from the netplay helper (`net.on('say', (s) => bubbles.say(s.seat, s.text, { id: s.id, kind: s.kind }))` and
+ * `net.on('unchat', (e) => e.ids.forEach((id) => bubbles.remove(id)))`), place it each frame with every speaking
+ * body's anchor (over its name label), and draw what comes back (`paintBubbles` on a canvas, or your own). Bubbles
+ * never cover each other: a bubble that would sits above the one in its way; the player's own is placed first.
+ */
+export function createBubbles(opts: BubbleOptions): Bubbles {
+  const lh = opts.lineHeight ?? 17;
+  const maxW = opts.maxWidth ?? 190;
+  const maxLines = opts.maxLines ?? 3;
+  const pad = opts.pad ?? { x: 8, y: 5 };
+  const tail = opts.tail ?? 7;
+  const gap = opts.gap ?? 4;
+  const clock = opts.now ?? ((): number => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+  const screen = opts.screen ?? ((): { w: number; h: number } => ({ w: typeof innerWidth === 'number' ? innerWidth : 1e9, h: typeof innerHeight === 'number' ? innerHeight : 1e9 }));
+  const life = opts.ms ?? ((b: { text: string; kind: string }): number => (b.kind === 'react' ? 2600 : Math.min(9000, 4000 + 50 * [...b.text].length)));
+  type Live = { id: string; key: string | number; kind: 'text' | 'line' | 'react'; text: string; lines: string[]; w: number; h: number; at: number; until: number };
+  const live = new Map<string | number, Live>();
+  let last: LabelBox[] = [];
+  let seq = 0;
+  return {
+    say(key, text, o = {}) {
+      const kind = o.kind ?? 'text';
+      const t = String(text ?? '').trim();
+      if (!t) return;
+      const emoji = kind === 'react';
+      const lines = emoji ? [t] : wrapText(t, maxW, opts.measure, maxLines);
+      const w = emoji ? lh * 1.6 : Math.max(...lines.map((l) => opts.measure(l)));
+      const h = emoji ? lh * 1.6 : lines.length * lh;
+      const at = clock();
+      seq += 1;
+      live.set(key, { id: o.id ?? `b${seq}`, key, kind, text: t, lines, w, h, at, until: at + life({ text: t, kind }) });
+    },
+    remove(id) { for (const [k, b] of live) if (b.id === id) live.delete(k); },
+    clear(key) { if (key === undefined) live.clear(); else live.delete(key); },
+    get size() { return live.size; },
+    boxes() { return last; },
+    place(anchors) {
+      const t = clock();
+      for (const [k, b] of live) if (t >= b.until) live.delete(k);
+      const { w: sw, h: sh } = screen();
+      const keep = opts.avoid?.() ?? [];
+      const placed: LabelBox[] = [];
+      const out: BubbleOut[] = [];
+      // The player's own first, then the newest: a new message keeps its spot and an older one moves up.
+      const order = anchors.filter((a) => live.has(a.key)).sort((a, b) => Number(Boolean(b.self)) - Number(Boolean(a.self)) || (live.get(b.key)!.at - live.get(a.key)!.at));
+      for (const a of order) {
+        const b = live.get(a.key)!;
+        const bw = b.w + pad.x * 2;
+        const bh = b.h + pad.y * 2;
+        const left = Math.max(2, Math.min(sw - bw - 2, a.x - bw / 2));
+        let bottom = a.y - tail;
+        let box = { left, top: bottom - bh, right: left + bw, bottom };
+        const hits = (x: LabelBox): boolean => box.left < x.right + gap && x.left < box.right + gap && box.top < x.bottom + gap && x.top < box.bottom + gap;
+        for (let i = 0; i < 6; i += 1) {
+          const other = placed.find(hits) ?? keep.find(hits);
+          if (!other) break;
+          bottom = other.top - gap;
+          box = { left, top: bottom - bh, right: left + bw, bottom };
+        }
+        if (box.top < 0 || box.left > sw || box.right < 0 || a.y > sh + bh) continue;
+        placed.push(box);
+        const age = t - b.at;
+        const leftMs = b.until - t;
+        const alpha = Math.max(0, Math.min(1, age / 120, leftMs / 400));
+        const scale = 0.86 + 0.14 * Math.min(1, age / 160);
+        out.push({ ...box, key: b.key, id: b.id, kind: b.kind, lines: b.lines, emoji: b.kind === 'react', lineHeight: lh, pad, tip: { x: Math.max(box.left + 8, Math.min(box.right - 8, a.x)), y: a.y }, cx: (box.left + box.right) / 2, cy: (box.top + box.bottom) / 2, alpha: Math.round(alpha * 100) / 100, scale: Math.round(scale * 1000) / 1000 });
+      }
+      last = placed;
+      return out;
+    },
+  };
+}
+
+export interface BubbleStyle {
+  font?: string;
+  /** The bubble's paper and ink (default white paper, near-black ink), its edge, and the player's own bubble's edge. */
+  paper?: string;
+  ink?: string;
+  edge?: string;
+  selfEdge?: string;
+  /** Corner radius, CSS px (default 10). */
+  radius?: number;
+}
+
+/** Draw placed bubbles on a 2D canvas (CSS px, the context's transform already set for the device pixel ratio). */
+export function paintBubbles(ctx: CanvasRenderingContext2D, list: BubbleOut[], style: BubbleStyle = {}): void {
+  const font = style.font ?? BUBBLE_FONT;
+  const paper = style.paper ?? '#ffffff';
+  const ink = style.ink ?? '#15171f';
+  const edge = style.edge ?? 'rgba(0,0,0,0.18)';
+  const r = style.radius ?? 10;
+  for (const b of list) {
+    if (b.alpha <= 0) continue;
+    ctx.save();
+    ctx.globalAlpha = b.alpha;
+    const cx = b.cx;
+    const cy = b.bottom;
+    ctx.translate(cx, cy);
+    ctx.scale(b.scale, b.scale);
+    ctx.translate(-cx, -cy);
+    ctx.fillStyle = paper;
+    ctx.strokeStyle = edge;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.roundRect(b.left, b.top, b.right - b.left, b.bottom - b.top, Math.min(r, (b.bottom - b.top) / 2));
+    ctx.fill();
+    ctx.stroke();
+    // The tail: a small triangle from the bubble's bottom to where it points.
+    const tx = b.tip.x;
+    ctx.beginPath();
+    ctx.moveTo(tx - 6, b.bottom - 1);
+    ctx.lineTo(tx, Math.min(b.tip.y, b.bottom + 7));
+    ctx.lineTo(tx + 6, b.bottom - 1);
+    ctx.closePath();
+    ctx.fill();
+    ctx.fillStyle = ink;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    if (b.emoji) {
+      ctx.font = font.replace(/\d+(?:\.\d+)?px/, `${Math.round(b.lineHeight * 1.35)}px`);
+      ctx.fillText(b.lines[0] ?? '', b.cx, b.cy + 1);
+    } else {
+      ctx.font = font;
+      b.lines.forEach((line, i) => ctx.fillText(line, b.cx, b.top + b.pad.y + b.lineHeight * (i + 0.5) + 0.5));
+    }
+    ctx.restore();
+  }
+}

package/site/SITE.md

@@ -30,7 +30,17 @@ songs (each with a `cover`), videos (each with a `poster`), the latest posts, an
 (`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.
+the hub offers Watch beside Join. From 0.23.0 a room whose chat is on and whose rules let homie.rocks show it
+(`hub`, on by default) also says `chat: true`: the hub's room card then has Chat, which opens the room's own watch
+socket from the visitor's browser and shows its lines and reactions live (NETPLAY.md section 19). A visitor there
+sends what a watcher may send (reactions and quick lines when the room's `react` is `anyone`), never types.
+
+## Room chat on the play, watch and TV pages
+
+Every play page, big screen and watch page carries room chat (worker/chat-page.mjs; chat/CHAT.md): the Chat pill
+and its sheet, the float, the ticker, the big screen's corner. Reports go to `POST /<id>/api/chat/report` (this
+site's pages only); the owner's tools are `/_studio/api/chat`, `/_studio/api/chat/rules`, `/_studio/api/chat/remove`,
+`/_studio/api/chat/report` (dismiss) and `/_studio/api/chat/budget`, and `mute`/`kick` take a chat line.
 
 ## A game's landing: `/<id>/`
 

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

@@ -43,7 +43,7 @@
  * The take "strike" (lab.json) stands a big training slime in front of the hero (lab.stage "dummy"). Outside the lab
  * every lab call is a no-op.
  */
-import { AI_MARK, createControls, createLabels, createRoom, createSaves, easeView, exposePort, fitView, jitter, q, standoff, stripAi, type BodyBase, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
+import { AI_MARK, BUBBLE_FONT, createBubbles, createControls, createLabels, createRoom, paintBubbles, type BubbleIn, type BubbleOut, createSaves, easeView, exposePort, fitView, jitter, q, standoff, stripAi, type BodyBase, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
 import { useAgents, type Goal, type Vocabulary } from '@homie-rocks/studio/agents';
 import vocabulary from '../agents.json';
 // The Game Lab: tunables, phases, tracks and overlays (no-ops outside the lab).
@@ -712,8 +712,14 @@ const INSET = { top: 124, bottom: 100 }; // the hero panel and its pills; STRIKE
 let cam: Fit | null = null;
 let lastDraw = 0;
 // Names keep clear of the guides' bubbles and of the ask panel (a page element over the canvas).
-const labels = createLabels({ screen: () => ({ w: vw, h: vh }), avoid: () => { const p = document.getElementById('asks'); return p && !p.hidden ? [...bubbleBoxes, p.getBoundingClientRect()] : bubbleBoxes; } });
+const labels = createLabels({ screen: () => ({ w: vw, h: vh }), avoid: () => { const p = document.getElementById('asks'); const all = [...bubbleBoxes, ...chatBubbles.boxes()]; return p && !p.hidden ? [...all, p.getBoundingClientRect()] : all; } });
 let bubbleBoxes: { left: number; top: number; right: number; bottom: number }[] = [];
+// Room chat (NETPLAY.md section 19): what a hero's player says in the room's chat shows over the hero for a few seconds,
+// clear of the guides' own bubbles. The studio taking a message down takes its bubble too.
+const chatBubbles = createBubbles({ measure: (t) => { ctx.font = BUBBLE_FONT; return ctx.measureText(t).width; }, screen: () => ({ w: vw, h: vh }), avoid: () => bubbleBoxes });
+net.on('say', (e) => chatBubbles.say(e.seat, e.text, { id: e.id, kind: e.kind }));
+net.on('unchat', (e) => { for (const id of e.ids) chatBubbles.remove(id); });
+let shownChat: BubbleOut[] = [];
 let shownLabels: LabelOut[] = [];
 function aim(): Fit {
   const v = lookOnly ? room.viewBody() : null;
@@ -772,6 +778,7 @@ function draw(t: number): void {
   ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
   const names: LabelIn[] = [];
   const said: { x: number; y: number; head: number; text: string }[] = [];
+  const heads = new Map<number, { x: number; y: number; seat: number; self: boolean }>();
   const mine: ScreenBox[] = []; // your own hero and its name: no bubble covers them
   const meAt = (() => { const v = room.view().find((b) => !b.bot && b.seat === viewS); return v ? { x: v.x, y: v.y } : null; })();
   for (const b of room.view()) {
@@ -801,6 +808,7 @@ function draw(t: number): void {
     const body = { left: sx(x - 24), top: sy(y - R - 12), right: sx(x + 24), bottom: sy(y + R) };
     if (body.right < 0 || body.left > vw || body.bottom < 0 || body.top > vh) continue; // off screen: no name at the edge
     if (self) { const w = ctx.measureText(text).width; mine.push(body, { left: sx(x) - w / 2 - 6, top: body.top - 4 - fs * 1.2, right: sx(x) + w / 2 + 6, bottom: body.top }); }
+    if (!b.bot && b.seat !== null && b.seat !== undefined) heads.set(b.slot, { x: sx(x), y: body.top - 3, seat: b.seat, self });
     names.push({ key: b.slot, text, x: sx(x), y: body.top - 3, w: ctx.measureText(text).width, h: fs * 1.2, below: body.bottom + 4 + fs * 1.2, body, self, rank: (b.bot ? (isGuide ? 1 : 2) : 0) * 10_000 + near });
     const line = bubbles.get(b.slot);
     // The bubble's tail stops just above the guide's own name, so the name keeps its spot while it speaks.
@@ -830,6 +838,16 @@ function draw(t: number): void {
     ctx.fillText(l.text, l.cx, l.cy);
   }
   ctx.globalAlpha = 1; ctx.textBaseline = 'alphabetic';
+  // Room chat's bubbles: over each speaking hero's name (your own placed first), clear of the guides' bubbles.
+  if (chatBubbles.size) {
+    const anchors: BubbleIn[] = [];
+    for (const [slot, h] of heads) {
+      const l = shownLabels.find((x) => x.key === slot && x.alpha > 0 && !x.moved);
+      anchors.push({ key: h.seat, x: l ? l.cx : h.x, y: l ? l.top - 1 : h.y, self: h.self });
+    }
+    shownChat = chatBubbles.place(anchors);
+    paintBubbles(ctx, shownChat, { paper: '#f6efdc', ink: '#1a1710', edge: 'rgba(40,30,10,.35)' });
+  } else shownChat = [];
   ctx.setTransform(1, 0, 0, 1, 0, 0);
   hud(t);
 }
@@ -1116,6 +1134,8 @@ function frame(t: number): void {
 
 // Tonight's experience per hero: the watch page's live scores, and who Auto follows when nobody is slaying.
 net.expose({
+  // Room chat's bubbles on this screen now: whose, what, and where (an end-to-end test reads them).
+  chatBubbles: () => shownChat.map((b) => ({ seat: b.key, text: b.lines.join(' '), alpha: b.alpha, left: Math.round(b.left), top: Math.round(b.top), right: Math.round(b.right), bottom: Math.round(b.bottom) })),
   scores: () => room.view().map((b) => ({ slot: b.slot, seat: b.seat, bot: b.bot, score: b.score })),
   // The guides, for the e2e probe: each guide's goal now, and the log of goals, asks and lines (seats and ids only).
   guides: () => ({

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

@@ -39,7 +39,7 @@
 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: its probe (what `homie-studio port check` reads for the owner tests, and sandbox + audio shims),
 // and a flat world on every screen (port/view.ts: the camera, and name labels that never pile up).
-import { createLabels, exposePort, fitView, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
+import { BUBBLE_FONT, createBubbles, createLabels, exposePort, fitView, paintBubbles, type BubbleIn, type BubbleOut, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
 // The Game Lab: tunables, phases, tracks and overlays (no-ops outside the lab).
 import { lab } from '@homie-rocks/studio/lab';
 import tuning from '../tunables.json';
@@ -768,6 +768,12 @@ resize();
 
 const cam = { x: W / 2, y: H / 2, scale: 0 };
 const labels = createLabels({ screen: () => ({ w: innerWidth, h: innerHeight }) });
+// Room chat (NETPLAY.md section 19): what a player says in the room's chat (the play page's Chat, or a quick line) shows
+// over their body for a few seconds, when they want it there. The studio taking a message down takes its bubble too.
+const bubbles = createBubbles({ measure: (t) => { ctx.font = BUBBLE_FONT; return ctx.measureText(t).width; }, screen: () => ({ w: innerWidth, h: innerHeight }) });
+net.on('say', (s) => bubbles.say(s.seat, s.text, { id: s.id, kind: s.kind }));
+net.on('unchat', (e) => { for (const id of e.ids) bubbles.remove(id); });
+let shownBubbles: BubbleOut[] = [];
 let shownLabels: LabelOut[] = [];
 let lastDraw = 0;
 /** Where a seat's body is drawn now (host: the real body; replica: interpolated), or null. */
@@ -868,6 +874,7 @@ function draw(t: number): void {
   const fs = Math.round(Math.max(15, Math.min(22, (15 * Math.min(cw, ch)) / 720)));
   ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
   const tags: LabelIn[] = [];
+  const heads = new Map<number, { x: number; y: number; seat: number; mine: boolean }>();
   const viewAt = list.find((a) => a.mine) ?? null;
   for (const a of list) {
     const colour = colourOf(a.slot, a.bot ? null : a.seat);
@@ -884,6 +891,7 @@ function draw(t: number): void {
     const text = a.mine && !net.watching ? 'You' : label(a.name, a.bot);
     const sx = cw / 2 + (a.x - cam.x) * scale; const sy = ch / 2 + (a.y - cam.y) * scale; const r = (R_AV + (a.mine ? 7 : 0)) * scale;
     if (sx + r < 0 || sx - r > cw || sy + r < 0 || sy - r > ch) continue; // off screen: no name at the edge
+    if (a.seat !== null && !a.bot) heads.set(a.slot, { x: sx, y: sy - r - 5, seat: a.seat, mine: a.mine });
     // People before bots, nearer the view's body first; each keeps off the others' bodies when it can.
     tags.push({ key: a.slot, text, x: sx, y: sy - r - 5, w: ctx.measureText(text).width, h: fs * 1.2, below: sy + r + 4 + fs * 1.2, body: { left: sx - r, top: sy - r, right: sx + r, bottom: sy + r }, self: a.mine, rank: (a.bot ? 10_000 : 0) + (viewAt ? Math.hypot(a.x - viewAt.x, a.y - viewAt.y) : 0) });
   }
@@ -909,6 +917,16 @@ function draw(t: number): void {
     ctx.fillText(l.text, l.cx, l.cy);
   }
   ctx.globalAlpha = 1; ctx.textBaseline = 'alphabetic';
+  // Speech bubbles (room chat): over each speaker's name, the view's own player first.
+  if (bubbles.size) {
+    const anchors: BubbleIn[] = [];
+    for (const [slot, h] of heads) {
+      const l = shownLabels.find((x) => x.key === slot && x.alpha > 0 && !x.moved);
+      anchors.push({ key: h.seat, x: l ? l.cx : h.x, y: l ? l.top - 1 : h.y, self: h.mine });
+    }
+    shownBubbles = bubbles.place(anchors);
+    paintBubbles(ctx, shownBubbles);
+  } else shownBubbles = [];
 
   hud(cw, ch, phone, list);
   if (stick.active) {
@@ -985,6 +1003,8 @@ function frame(t: number): void {
 }
 
 net.expose({
+  // Room chat's bubbles on this screen now: whose, what, and where (an end-to-end test reads them).
+  bubbles: () => shownBubbles.map((b) => ({ seat: b.key, text: b.lines.join(' '), alpha: b.alpha, left: Math.round(b.left), top: Math.round(b.top), right: Math.round(b.right), bottom: Math.round(b.bottom) })),
   self: () => (me.has ? { x: me.x, y: me.y } : null),
   peer: (seat: number) => {
     if (hosting) { const b = [...bodies.values()].find((x) => x.seat === seat); return b ? { x: b.x, y: b.y } : null; }

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

@@ -45,7 +45,7 @@ import { createModels, instancedCopies, placeCopy, repaint, stylize, type Copies
 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: its probe (what `homie-studio port check` and `perf` read, and sandbox + audio shims), and name
 // labels that never pile up (port/view.ts).
-import { createLabels, exposePort, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
+import { createBubbles, createLabels, exposePort, paintBubbles, type BubbleIn, type BubbleOut, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
 // The Game Lab: tunables, phases, tracks and overlays (no-ops outside the lab).
 import { lab } from '@homie-rocks/studio/lab';
 import tuning from '../tunables.json';
@@ -1659,6 +1659,13 @@ resize();
 let zoneMark: { left: number; top: number; right: number; bottom: number } | null = null;
 const labels = createLabels({ screen: () => ({ w: innerWidth, h: innerHeight }), avoid: () => (zoneMark ? [zoneMark] : []) });
 let shownLabels: LabelOut[] = [];
+// Room chat (NETPLAY.md section 19): what a player says in the room's chat shows over their animal for a few seconds,
+// on the HUD's own paper (one UI with the names, the clock and the board). The studio taking a message down takes it too.
+const BUBBLE_TYPE = `600 14px ${FONT_BODY}`;
+const bubbles = createBubbles({ measure: (t) => { ctx.font = BUBBLE_TYPE; return ctx.measureText(t).width; }, screen: () => ({ w: innerWidth, h: innerHeight }), avoid: () => (zoneMark ? [zoneMark] : []) });
+net.on('say', (s) => bubbles.say(s.seat, s.text, { id: s.id, kind: s.kind }));
+net.on('unchat', (e) => { for (const id of e.ids) bubbles.remove(id); });
+let shownBubbles: BubbleOut[] = [];
 let lastDraw = 0;
 /** Where a seat's body is drawn now (host: the real body; replica: interpolated), or null. */
 function seatPos(seat: number): { x: number; y: number } | null {
@@ -1823,6 +1830,7 @@ function draw(t: number, dt: number): void {
   const fs = Math.round(Math.max(15, Math.min(22, (15 * Math.min(cw, ch)) / 720)));
   ctx.font = `700 ${fs}px ${FONT_BODY}`;
   const tags: LabelIn[] = [];
+  const heads = new Map<number, { x: number; y: number; seat: number; mine: boolean }>();
   const viewAt = list.find((a) => a.mine) ?? null;
   for (const a of list) {
     const text = a.mine && !net.watching ? 'You' : label(a.name, a.bot);
@@ -1833,6 +1841,7 @@ function draw(t: number, dt: number): void {
     const r = Math.max(6, Math.hypot(side.x - mid.x, side.y - mid.y));
     if (mid.x + r < 0 || mid.x - r > cw || head.y > ch || mid.y + r < 0) continue; // off screen: no name at the edge
     const foot = onScreen(a.x, a.y, 0, cw, ch);
+    if (a.seat !== null && !a.bot) heads.set(a.slot, { x: head.x, y: head.y - 3, seat: a.seat, mine: a.mine });
     // People before bots, nearer the view's body first; each keeps off the others' bodies when it can.
     tags.push({ key: a.slot, text, x: head.x, y: head.y - 3, w: ctx.measureText(text).width, h: fs * 1.2, below: foot.y + r * 0.6 + 4 + fs * 1.2, body: { left: mid.x - r, top: head.y, right: mid.x + r, bottom: foot.y + r * 0.4 }, self: a.mine, rank: (a.bot ? 10_000 : 0) + (viewAt ? Math.hypot(a.x - viewAt.x, a.y - viewAt.y) * 50 : 0) });
   }
@@ -1855,6 +1864,16 @@ function draw(t: number, dt: number): void {
     ctx.fillText(l.text, l.cx, l.cy);
   }
   ctx.globalAlpha = 1; ctx.textBaseline = 'alphabetic';
+  // Speech bubbles (room chat): over each speaker's name pill, the view's own player first.
+  if (bubbles.size) {
+    const anchors: BubbleIn[] = [];
+    for (const [slot, h] of heads) {
+      const l = shownLabels.find((x) => x.key === slot && x.alpha > 0 && !x.moved);
+      anchors.push({ key: h.seat, x: l ? l.cx : h.x, y: l ? l.top - 3 : h.y, self: h.mine });
+    }
+    shownBubbles = bubbles.place(anchors);
+    paintBubbles(ctx, shownBubbles, { font: BUBBLE_TYPE, paper: PAPER, ink: TEXT, edge: mixHex(TEXT, PAPER, 0.7) });
+  } else shownBubbles = [];
 
   hud(cw, ch, phone, list);
   if (stick.active) {
@@ -2028,6 +2047,8 @@ function frame(t: number): void {
 }
 
 net.expose({
+  // Room chat's bubbles on this screen now: whose, what, and where (an end-to-end test reads them).
+  bubbles: () => shownBubbles.map((b) => ({ seat: b.key, text: b.lines.join(' '), alpha: b.alpha, left: Math.round(b.left), top: Math.round(b.top), right: Math.round(b.right), bottom: Math.round(b.bottom) })),
   self: () => (me.has ? { x: me.x, y: me.y } : null),
   peer: (seat: number) => {
     if (hosting) { const b = [...bodies.values()].find((x) => x.seat === seat); return b ? { x: b.x, y: b.y } : null; }

package/worker/agents.mjs

@@ -74,10 +74,10 @@ export function encodeFacts(value) {
   for (const b of bytes) s += String.fromCharCode(b);
   return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-/** The reverse, or null for anything that is not one (at most 4 KB). */
-export function decodeFacts(text) {
+/** The reverse, or null for anything that is not one (at most 4 KB, or `max`: a room's chat rules may be longer). */
+export function decodeFacts(text, max = 4096) {
   const t = String(text ?? '');
-  if (!t || t.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(t)) return null;
+  if (!t || t.length > max || !/^[A-Za-z0-9_-]+$/.test(t)) return null;
   try {
     const s = atob(t.replace(/-/g, '+').replace(/_/g, '/'));
     const bytes = Uint8Array.from(s, (c) => c.charCodeAt(0));