@homie-rocks/studio 0.2.0 → 0.5.0

package/port/hud.ts

@@ -0,0 +1,96 @@
+/*
+ * A small room HUD for a port that has none of its own: the round clock
+ * (top-left chip), the top scores (top-right, four rows at most), and the
+ * 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".
+ *
+ * A game with its own HUD should draw the same facts itself (clock from
+ * room.clock(), results from room.results()) instead.
+ */
+import type { BodyBase, Room } from './room';
+
+export interface HudOptions {
+  /** What a point is called on the board ("gems", "tiles"). */
+  unit?: string;
+  /** A short controls line shown for the first seconds ("Drag to move · tap to jump"). */
+  hint?: { phone: string; desk: string };
+  /** Accent colour for "you". */
+  accent?: string;
+}
+
+const CSS = `
+.hp-hud{position:fixed;z-index:2147482000;pointer-events:none;font:600 14px/1.25 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;color:#eef1f8;text-shadow:0 1px 2px rgba(0,0,0,.7)}
+.hp-chip{background:rgba(6,9,18,.55);border-radius:10px;padding:5px 9px;backdrop-filter:blur(4px)}
+.hp-clock{left:calc(10px + env(safe-area-inset-left));top:calc(10px + env(safe-area-inset-top))}
+.hp-board{right:calc(10px + env(safe-area-inset-right));top:calc(10px + env(safe-area-inset-top));text-align:right;min-width:92px}
+.hp-board div{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:42vw}
+.hp-board .me{color:var(--hp-accent,#ffd166)}
+.hp-board .bot{opacity:.62}
+.hp-results{left:50%;top:50%;transform:translate(-50%,-50%);min-width:220px;max-width:min(360px,86vw);padding:14px 16px;border-radius:14px;background:rgba(6,9,18,.82)}
+.hp-results h2{margin:0 0 8px;font-size:15px;letter-spacing:.04em;text-transform:uppercase;color:var(--hp-accent,#ffd166)}
+.hp-results ol{margin:0;padding-left:20px}
+.hp-hint{left:50%;bottom:calc(14px + env(safe-area-inset-bottom));transform:translateX(-50%);opacity:.85;transition:opacity .8s}
+@media (max-width:540px){.hp-hud{font-size:13px}}
+`;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createHud<B extends BodyBase>(room: Room<B, any, any>, opts: HudOptions = {}): { destroy(): void } {
+  if (typeof document === 'undefined') return { destroy() {} };
+  const style = document.createElement('style');
+  style.textContent = CSS;
+  document.head.append(style);
+  const mk = (cls: string): HTMLDivElement => { const d = document.createElement('div'); d.className = `hp-hud ${cls}`; return d; };
+  const clock = mk('hp-chip hp-clock');
+  const board = mk('hp-chip hp-board');
+  const results = mk('hp-results');
+  results.style.display = 'none';
+  const hint = mk('hp-chip hp-hint');
+  if (opts.accent) document.documentElement.style.setProperty('--hp-accent', opts.accent);
+  const phone = Math.min(innerWidth, innerHeight) <= 540;
+  const spectator = (): boolean => !room.net.offline && room.net.seat === null;
+  if (opts.hint && !spectator()) hint.textContent = phone ? opts.hint.phone : opts.hint.desk; else hint.style.display = 'none';
+  const mount = (): void => { document.body.append(clock, board, results, hint); };
+  if (document.body) mount(); else document.addEventListener('DOMContentLoaded', mount, { once: true });
+  const bornAt = performance.now();
+  let lastResults = '';
+
+  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();
+    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;
+      d.className = mine ? 'me' : b.bot ? 'bot' : '';
+      d.textContent = `${mine ? '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}`;
+      if (key !== lastResults) {
+        lastResults = key;
+        results.textContent = '';
+        const h = document.createElement('h2'); h.textContent = `Round ${r.n}`;
+        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}` : ''}`;
+          if (mine) li.style.color = 'var(--hp-accent,#ffd166)';
+          ol.append(li);
+        }
+        results.append(h, ol);
+      }
+      results.style.display = 'block';
+    } else results.style.display = 'none';
+    if (hint.style.display !== 'none' && performance.now() - bornAt > 9000) hint.style.opacity = '0';
+  };
+  const timer = setInterval(paint, 200);
+  paint();
+  return { destroy() { clearInterval(timer); clock.remove(); board.remove(); results.remove(); hint.remove(); style.remove(); } };
+}

package/port/index.ts

@@ -0,0 +1,29 @@
+/*
+ * @homie-rocks/studio/port — the toolkit the port skill uses to make an existing
+ * single-player web game multiplayer on the netplay contract.
+ *
+ *   early        sandbox shims + first-touch audio (import first)
+ *   createRoom   the host scaffold: bots, join-in-progress, rounds, host migration, snapshots
+ *   createControls / createTouchControls / createKeys / synthKey
+ *                keys on computers, a floating stick and small buttons on phones
+ *   groundBasis / screenToGround / PlayerYaw
+ *                the camera rules: input on screen axes, a yaw only the player turns
+ *   exposePort   what `homie-studio port check` reads (owner tests)
+ *   createHud    a minimal clock / scores / results overlay
+ *   BotBrain, seek, nearest, rubberBand
+ *                bot scaffolds
+ * and everything from @homie-rocks/studio/netplay.
+ */
+import './early';
+
+export * from '../netplay/netplay';
+export { installSandboxShims, sandboxReport, type SandboxReport } from './sandbox';
+export { installAudioUnlock, audioReport } from './audio';
+export { createKeys, synthKey, holdKey, tapKey, keyInfo, releaseAllSynthKeys, type Keys, type Dir } from './keys';
+export { createTouchControls, type TouchControls, type TouchOptions, type TouchButton } from './touch';
+export { createControls, type Controls, type ControlsOptions } from './controls';
+export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLike } from './camera';
+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';

package/port/keys.ts

@@ -0,0 +1,102 @@
+/*
+ * Keys on computers, and keys synthesized from touch on phones.
+ *
+ * Most single-player web games read the keyboard. A port keeps that code and
+ * lets the touch kit press the same keys (a stick held left presses ArrowLeft,
+ * a button presses Space), so the game's own input code stays the one truth.
+ * The synthetic events carry the legacy keyCode/which/charCode too, because
+ * older games (and jQuery) read those rather than `key` or `code`.
+ */
+
+export type Dir = 'left' | 'right' | 'up' | 'down';
+
+const CODES: Record<string, [key: string, keyCode: number]> = {
+  ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40],
+  Space: [' ', 32], Enter: ['Enter', 13], Escape: ['Escape', 27], Tab: ['Tab', 9], Backspace: ['Backspace', 8],
+  ShiftLeft: ['Shift', 16], ShiftRight: ['Shift', 16], ControlLeft: ['Control', 17], AltLeft: ['Alt', 18],
+};
+
+/** `key`, `keyCode` for a KeyboardEvent.code ('KeyW', 'Digit1', 'ArrowLeft', 'Space', …). */
+export function keyInfo(code: string): { key: string; keyCode: number } {
+  const known = CODES[code];
+  if (known) return { key: known[0], keyCode: known[1] };
+  const letter = /^Key([A-Z])$/.exec(code);
+  if (letter) return { key: (letter[1] as string).toLowerCase(), keyCode: (letter[1] as string).charCodeAt(0) };
+  const digit = /^Digit([0-9])$/.exec(code);
+  if (digit) return { key: digit[1] as string, keyCode: 48 + Number(digit[1]) };
+  return { key: code, keyCode: 0 };
+}
+
+/** Where synthetic keys go: the focused element (it bubbles to document and window), else the body. */
+function keyTarget(): EventTarget {
+  const a = typeof document !== 'undefined' ? document.activeElement : null;
+  return a && a !== document.documentElement ? a : (document.body ?? document);
+}
+
+const synthDown = new Set<string>();
+
+/** Dispatch one synthetic key event that old and new games both understand. */
+export function synthKey(type: 'keydown' | 'keyup', code: string, target: EventTarget = keyTarget()): void {
+  const { key, keyCode } = keyInfo(code);
+  const ev = new KeyboardEvent(type, { key, code, bubbles: true, cancelable: true, composed: true, repeat: false });
+  for (const [prop, value] of [['keyCode', keyCode], ['which', keyCode], ['charCode', type === 'keydown' ? 0 : 0]] as const) {
+    try { Object.defineProperty(ev, prop, { get: () => value }); } catch { /* read-only on this engine */ }
+  }
+  if (type === 'keydown') synthDown.add(code); else synthDown.delete(code);
+  target.dispatchEvent(ev);
+}
+
+/** Hold `code` down (once) or let it go; no repeats, like a real key held still. */
+export function holdKey(code: string, down: boolean): void {
+  if (down && !synthDown.has(code)) synthKey('keydown', code);
+  else if (!down && synthDown.has(code)) synthKey('keyup', code);
+}
+
+/** A quick press and release (a swipe on a board game, a tap). */
+export function tapKey(code: string, holdMs = 40): void {
+  synthKey('keydown', code);
+  setTimeout(() => synthKey('keyup', code), holdMs);
+}
+
+export function releaseAllSynthKeys(): void { for (const c of [...synthDown]) synthKey('keyup', c); }
+
+/** The keyboard, read directly: WASD and arrows as a move vector, and edges for buttons. */
+export interface Keys {
+  /** Screen-space move: x right, y DOWN, length ≤ 1. */
+  move(): { x: number; y: number };
+  down(code: string): boolean;
+  /** True once per press (consumed). */
+  pressed(code: string): boolean;
+  destroy(): void;
+}
+
+export function createKeys(target: Window | HTMLElement = window): Keys {
+  const held = new Set<string>();
+  const edges = new Set<string>();
+  const kd = (e: Event): void => {
+    const k = e as KeyboardEvent;
+    if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Space'].includes(k.code)) k.preventDefault();
+    if (!held.has(k.code)) edges.add(k.code);
+    held.add(k.code);
+  };
+  const ku = (e: Event): void => { held.delete((e as KeyboardEvent).code); };
+  // A lost focus releases keys (a key-up we never saw would hold a direction forever). It never touches fingers.
+  const blur = (): void => { held.clear(); };
+  target.addEventListener('keydown', kd);
+  target.addEventListener('keyup', ku);
+  window.addEventListener('blur', blur);
+  return {
+    move() {
+      let x = 0; let y = 0;
+      if (held.has('KeyA') || held.has('ArrowLeft')) x -= 1;
+      if (held.has('KeyD') || held.has('ArrowRight')) x += 1;
+      if (held.has('KeyW') || held.has('ArrowUp')) y -= 1;
+      if (held.has('KeyS') || held.has('ArrowDown')) y += 1;
+      const len = Math.hypot(x, y);
+      return len > 1 ? { x: x / len, y: y / len } : { x, y };
+    },
+    down: (code) => held.has(code),
+    pressed(code) { const had = edges.has(code); edges.delete(code); return had; },
+    destroy() { target.removeEventListener('keydown', kd); target.removeEventListener('keyup', ku); window.removeEventListener('blur', blur); },
+  };
+}

package/port/probe.ts

@@ -0,0 +1,126 @@
+/*
+ * What `homie-studio port check` reads inside a ported game: one object on
+ * window.__homiePort, sampled every frame into a ring buffer, so the owner
+ * tests can judge motion on SCREEN axes (the camera's, not the game's):
+ *
+ *   hold a direction 5 s     → one straight line the pressed way, camera yaw change < 10°
+ *   alternate directions 10 s → every press goes the pressed way within 600 ms
+ *
+ * A port calls exposePort() once. `self` is the player's own body on the
+ * ground plane; `basis` is the camera's screen axes on that plane (the default
+ * is a flat 2D view: x right, y down). Board and turn-based games have no body:
+ * they report `lastMove` (the direction the game APPLIED) instead, and the
+ * check presses and swipes and compares.
+ */
+import type { Netplay } from '../netplay/netplay';
+import { audioReport } from './audio';
+import { sandboxReport } from './sandbox';
+
+export type View = 'top' | 'side' | 'first-person' | 'board' | 'maze';
+
+export interface PortProbeOptions {
+  /** top: top-down or three-quarter (all four directions move you); side: a side view (left/right run, up jumps);
+   *  first-person: WASD strafes on the camera's axes; board: no body (grid, cards, puzzle); maze: a top view on
+   *  a grid of corridors whose turns are buffered (a turn into a wall waits for the next opening). */
+  view: View;
+  /** My body's position on the ground plane (2D: canvas x, y with y down; 3D: world x and z). null = no body yet. */
+  self?: () => { x: number; y: number } | null;
+  /** The camera's screen-right and screen-up directions on that plane. Default (2D): right (1,0), up (0,-1). */
+  basis?: () => { right: [number, number]; up: [number, number] };
+  /** About how big a body is, in the same units (a radius or half a width). The checks scale distances by it. */
+  size?: number;
+  /** Board games: the last move the game applied ('left' | 'right' | 'up' | 'down' | any word) and a counter. */
+  lastMove?: () => string | null;
+  moves?: () => number;
+  /** My score right now, if the game has one. */
+  score?: () => number | null;
+  /** True while my body is not mine to steer (knocked back, stunned, dead, respawning): the owner tests skip
+   *  those frames, and the recipe's newcomer rule says it should rarely happen in a person's first seconds. */
+  busy?: () => boolean;
+  /** Anything else worth a look in a receipt (numbers or short strings). */
+  extra?: Record<string, () => unknown>;
+  /** The keys that move you (KeyboardEvent.code). Default: the arrows (WASD for first-person). */
+  keys?: { up: string; down: string; left: string; right: string };
+  /** Where the check puts a thumb for the stick, as screen fractions (default [0.24, 0.74]). */
+  thumb?: [number, number];
+  /** CSS selector of the game's own world when it is HTML (a DOM board, a grid of tiles): the check counts it as
+   *  the world, not as UI covering the screen. A canvas game needs nothing here. */
+  world?: string;
+}
+
+interface PortProbe {
+  v: 1;
+  view: View;
+  size: number;
+  keys: { up: string; down: string; left: string; right: string };
+  thumb: [number, number];
+  world: string | null;
+  /** Rows since `t` (performance.now ms): [t, x, y, rightX, rightY, upX, upY, moves, busy (1/0)]. */
+  rows(since?: number): number[][];
+  now(): number;
+  info(): Record<string, unknown>;
+  errors: string[];
+}
+
+const RING = 4000;
+
+export function exposePort(net: Netplay<unknown, unknown, unknown> | null, opts: PortProbeOptions): PortProbe {
+  const rows: number[][] = [];
+  let frames = 0;
+  const frameTimes: number[] = [];
+  const errors: string[] = [];
+  if (typeof window !== 'undefined') {
+    window.addEventListener('error', (e) => { errors.push(String((e as ErrorEvent).message ?? e).slice(0, 300)); if (errors.length > 50) errors.shift(); });
+    window.addEventListener('unhandledrejection', (e) => { errors.push(`unhandled: ${String((e as PromiseRejectionEvent).reason).slice(0, 300)}`); if (errors.length > 50) errors.shift(); });
+  }
+  const flat = (): { right: [number, number]; up: [number, number] } => ({ right: [1, 0], up: [0, -1] });
+  const basisOf = opts.basis ?? flat;
+  const sample = (t: number): void => {
+    frames += 1;
+    frameTimes.push(t); if (frameTimes.length > 120) frameTimes.shift();
+    let me: { x: number; y: number } | null = null;
+    try { me = opts.self ? opts.self() : null; } catch { me = null; }
+    let b = flat();
+    try { b = basisOf(); } catch { /* keep flat */ }
+    let m = 0;
+    try { m = opts.moves ? Number(opts.moves()) || 0 : 0; } catch { /* ignore */ }
+    let busy = 0;
+    try { busy = opts.busy && opts.busy() ? 1 : 0; } catch { /* ignore */ }
+    rows.push([t, me ? me.x : NaN, me ? me.y : NaN, b.right[0], b.right[1], b.up[0], b.up[1], m, busy]);
+    if (rows.length > RING) rows.splice(0, rows.length - RING);
+  };
+  const loop = (t: number): void => { sample(t); requestAnimationFrame(loop); };
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(loop);
+  const probe: PortProbe = {
+    v: 1,
+    view: opts.view,
+    size: opts.size ?? 1,
+    keys: opts.keys ?? (opts.view === 'first-person' ? { up: 'KeyW', down: 'KeyS', left: 'KeyA', right: 'KeyD' } : { up: 'ArrowUp', down: 'ArrowDown', left: 'ArrowLeft', right: 'ArrowRight' }),
+    thumb: opts.thumb ?? [0.24, 0.74],
+    world: opts.world ?? null,
+    rows(since = 0) { return rows.filter((r) => (r[0] as number) >= since); },
+    now: () => performance.now(),
+    info() {
+      const fps = frameTimes.length > 10 ? (frameTimes.length - 1) / (((frameTimes[frameTimes.length - 1] as number) - (frameTimes[0] as number)) / 1000) : null;
+      const extra: Record<string, unknown> = {};
+      for (const [k, f] of Object.entries(opts.extra ?? {})) { try { extra[k] = f(); } catch (e) { extra[k] = `error: ${String(e)}`; } }
+      let lastMove: string | null = null;
+      try { lastMove = opts.lastMove ? opts.lastMove() : null; } catch { /* ignore */ }
+      let score: number | null = null;
+      try { score = opts.score ? opts.score() : null; } catch { /* ignore */ }
+      return {
+        view: opts.view, frames, fps: fps === null ? null : Math.round(fps * 10) / 10,
+        role: net?.role ?? null, seat: net?.seat ?? null, offline: net?.offline ?? null, owned: net?.owned ?? null,
+        round: net?.roundInfo ? { n: net.roundInfo.n, phase: net.roundInfo.phase, endsAt: net.roundInfo.endsAt, leftMs: Math.round(net.roundInfo.endsAt - net.now()) } : null,
+        slots: net?.slots?.map((s) => ({ slot: s.slot, seat: s.seat, bot: s.bot })) ?? null,
+        lastMove, moves: opts.moves ? opts.moves() : null, score,
+        audio: audioReport(), sandbox: sandboxReport(), errors: errors.slice(-10), extra,
+      };
+    },
+    errors,
+  };
+  (window as unknown as { __homiePort: PortProbe }).__homiePort = probe;
+  // The contract's own probes too, so the netplay e2e and any older harness can read this game.
+  try { net?.expose({ self: () => { const s = opts.self?.(); return s ? { x: s.x, y: s.y } : null; }, frames: () => frames }); } catch { /* offline */ }
+  return probe;
+}