@homie-rocks/studio 0.30.2 → 0.31.1

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

@@ -49,6 +49,13 @@
  * byte). A model that is refused or not there is drawn as a stand-in in the same colours: a round never waits on, or
  * breaks for, a model.
  *
+ * HEADINGS, AND THERE ARE TWO: a body's facing (`fa`, drawn as `yaw`) is `Math.atan2(dx, dy)` in the game's own x and y, so yaw 0 faces +y
+ * (three.js's +z, the way the models are built) and it goes straight into `rotation.y`. That is also the yaw
+ * `@homie-rocks/camera` means (0 faces +Z, positive turns toward +X, radians), so a follow or chase camera from that
+ * package takes a body's facing as it stands. The knock and aim angles (`ang`, `base`) are the OTHER kind,
+ * `Math.atan2(dy, dx)`: 0 faces +x. Never hand one of those to a camera or to `rotation.y` without converting it:
+ * `headingFrom({ zero: '+x', toward: '+z' })` from `@homie-rocks/camera/heading.js` is the adapter.
+ *
  * PHONE BUDGETS: under 100 draw calls and 150k triangles a frame (the `drawCalls` and `triangles` probes read
  * renderer.info), the pixel ratio at most 1.5 on a phone and 2 on a computer, and no shadow map on a phone: a soft
  * disc under each body, coin, tree and rock (a computer draws the sun's real shadows). Repeated things are one
@@ -70,7 +77,7 @@ import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js
 import { createModels, instancedCopies, placeCopy, repaint, stylize, type Copies } from '@homie-rocks/studio/assets';
 // Characters that move well: clips from the skeleton's clip library, blended, layered and tuned (Game Lab tunables).
 import { crowd, loadCharacter, type Character } from '@homie-rocks/studio/animate';
-import { createNetplay, Roster, q, lerp, capMove, skillPreset, PALETTE, AI_MARK, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
+import { createNetplay, guardGestures, Roster, q, lerp, capMove, skillPreset, PALETTE, AI_MARK, type Peer, 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 { createBubbles, createLabels, exposePort, paintBubbles, type BubbleIn, type BubbleOut, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
@@ -153,7 +160,7 @@ interface Gem { id: number; x: number; y: number }
 /** Slow state, on the keyed state channel (net.state('zone', ...)), not in the 20 Hz snapshot. */
 interface Zone { n: number; x: number; y: number; r: number; until: number }
 /** `firstRound`: each person's first whole round here (seat, round), so a promoted host eases the same round. */
-interface Ckpt { round: RoundInfo; bodies: Body[]; gems: Gem[]; roster: Slot[]; tick: number; gemSeq: number; firstRound?: [number, number][] }
+interface Ckpt { round: RoundInfo; bodies: Body[]; gems: Gem[]; roster: Slot[]; tick: number; gemSeq: number; occ?: [number, number][]; firstRound?: [number, number][] }
 
 /* --------------------------------------------------------------- the net */
 /**
@@ -165,6 +172,9 @@ const MOVEMENT: 'owner' | 'host' = (() => { try { return new URLSearchParams(loc
 // caps: its bots read the dial ('skill'), and its Roster takes an AI's slot for it ('agents': the join passes p.agent).
 // arrival 'game': the play page's arrival card stays until this game says it is playable (THE ARRIVAL, by the HUD).
 const net = createNetplay<Snap, Avatar, Ckpt>({ game: 'hero-rush-3d', maxPlayers: MAX_SLOTS, movement: MOVEMENT, snapshotHz: 20, inputHz: 20, checkpointMs: 1000, caps: ['skill', 'agents'], arrival: 'game', checkpoint: () => checkpoint() });
+// A touch game guards its own page (NETPLAY.md section 24): a long press on the canvas never selects text or raises
+// the copy/paste callout on a phone, and a touch on it never pans or zooms the page.
+guardGestures({ touch: 'canvas' });
 /** The Roster keeps the server's AI seats (revision 6): the policy is read whenever it fills. */
 const policy = () => net.policy;
 
@@ -243,9 +253,12 @@ function newZone(n: number): Zone {
 function setZone(z: Zone): void { zone = z; net.state('zone', z); }
 
 /** A round starts with every hero on its spawn ring facing the camera (fa 0): a line-up the hero intro opens on. */
-function startRound(n: number): void {
+function startRound(n: number, rollover = false): void {
   const now = net.now();
   roster.trim();
+  // The next round of a running room: the trim is what makes room (the seats a server no longer keeps for AI go
+  // here), so whoever was seated with no body is given one now, before the bodies are placed.
+  if (rollover && !net.offline) seatWaiting();
   syncBodiesFromRoster();
   let i = 0;
   for (const b of [...bodies.values()].sort((a, c) => a.slot - c.slot)) {
@@ -290,7 +303,9 @@ function becomeHost(e: RoleChange<Snap, Ckpt>): void {
     welcome(seat);
   }
   // Whoever is connected now is who plays: seats that left during the gap become bots.
-  const peers = net.offline ? [{ seat: 0, name: 'You' }] : [...net.peers.values()].filter((p) => p.seat !== null).map((p) => ({ seat: p.seat, name: p.name, agent: p.agent ?? 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, occ: p.occ ?? null }));
+  // `occ` (NETPLAY.md section 25): which stay in its seat each peer's is, so a seat number that changed hands while
+  // nobody was hosting is claimed afresh instead of inheriting the last player's body in silence.
   const { claimed } = roster.reconcile(peers);
   syncBodiesFromRoster();
   for (const s of claimed) welcome(s.seat);
@@ -308,7 +323,7 @@ function becomeHost(e: RoleChange<Snap, Ckpt>): void {
 function restore(e: RoleChange<Snap, Ckpt>): void {
   const ck = e.ckpt?.d ?? null;
   if (ck) {
-    roster = Roster.from(ck.roster, { min: MIN_SLOTS, max: MAX_SLOTS, botName, policy });
+    roster = Roster.from(ck.roster, { min: MIN_SLOTS, max: MAX_SLOTS, botName, policy }, ck.occ ?? null);
     bodies = new Map(ck.bodies.map((b) => [b.slot, { ...b }]));
     gems = ck.gems.map((g) => ({ ...g }));
     gemSeq = ck.gemSeq;
@@ -352,6 +367,8 @@ function checkpoint(): Ckpt {
     bodies: [...bodies.values()].map((b) => ({ ...b })),
     gems: gems.map((g) => ({ ...g })),
     roster: roster.toJSON(),
+    // Whose stay each body is, beside the roster: how the next host tells a player who came back from a new one.
+    occ: roster.occupants(),
     tick,
     gemSeq,
     firstRound: [...firstRound],
@@ -362,16 +379,31 @@ net.on('role', (e) => {
   if (e.role === 'host') becomeHost(e);
   else { hosting = false; }
 });
-net.on('join', (p) => {
-  if (!hosting || p.seat === null) return;
+/** Host: a body for somebody the relay seated. False when every body is somebody's (they wait: see seatWaiting). */
+function giveBody(p: Peer): boolean {
+  if (p.seat === null) return false;
   // An AI takes a seat kept for AI, a person never does (revision 6: the Roster needs p.agent for that).
-  const c = roster.claim(p.seat, p.name, p.agent ? { role: p.agent.role, hands: p.agent.hands } : null);
-  if (!c) return; // full: they watch
+  const c = roster.claim(p.seat, p.name, p.agent ? { role: p.agent.role, hands: p.agent.hands } : null, p.occ ?? null);
+  if (!c) return false;
   welcome(p.seat);
   syncBodiesFromRoster();
   const b = bodies.get(c.slot.slot);
   // The arriving human takes over the bot's body where it stands, score and all (reset = "adopt this position").
   if (b) { b.vx = 0; b.vy = 0; b.kvx = 0; b.kvy = 0; b.knockUntil = 0; hostMoved(b); }
+  return true;
+}
+/**
+ * SEAT WHOEVER IS WAITING (NETPLAY.md section 28). The relay seats a person; this host gives them a body. A claim that
+ * found every body taken (a server's AI seats were still kept, say) used to be tried once: that player watched for the
+ * rest of the visit, online, with nothing said. It is tried again whenever a body frees up and at every round start.
+ */
+function seatWaiting(): boolean {
+  let any = false;
+  for (const p of net.peers.values()) if (p.seat !== null && !roster.bySeat(p.seat) && giveBody(p)) any = true;
+  return any;
+}
+net.on('join', (p) => {
+  if (!hosting || !giveBody(p)) return;
   publishRoster();
   net.snapshot(buildSnap(), tick, true);
 });
@@ -380,7 +412,10 @@ net.on('leave', (p) => {
   roster.release(p.seat); // their body stays, driven by a bot
   firstRound.delete(p.seat); // whoever sits in this seat next is new here
   syncBodiesFromRoster();
+  // A body just went to a bot: somebody seated with none takes it now.
+  const seated = seatWaiting();
   publishRoster();
+  if (seated) net.snapshot(buildSnap(), tick, true);
 });
 // The server's policy changed: its AI seats come (or go between rounds) at once.
 net.on('policy', () => { if (!hosting) return; roster.fill(); syncBodiesFromRoster(); publishRoster(); });
@@ -882,7 +917,7 @@ function stepHost(dt: number): void {
       }
     }
     if (now >= round.endsAt) endRound();
-  } else if (round && round.phase === 'over' && now >= round.endsAt) startRound(round.n + 1);
+  } else if (round && round.phase === 'over' && now >= round.endsAt) startRound(round.n + 1, true);
   if (net.snapshotDue()) net.snapshot(buildSnap(), tick);
 }
 
@@ -2475,7 +2510,8 @@ function hud(cw: number, ch: number, phone: boolean, list: { slot: number; seat:
       ctx.fillText(`${TOGETHER ? '' : `${row.place}. `}${mine && !net.watching ? 'You' : label(row.name, row.bot)}${mine && net.watching ? ' ◂' : ''} — ${row.score}`, cw / 2, ry + 1);
     });
   }
-  if (!net.offline && !net.connected && net.role !== 'host') {
+  // Only a browser that WAS in its room is reconnecting; one still joining, or stopped for good, is not (section 22).
+  if (net.link === 'reconnecting' && net.role !== 'host') {
     ctx.textAlign = 'center'; ctx.font = `700 15px ${FONT_BODY}`;
     const text = 'Reconnecting…'; const tw = ctx.measureText(text).width;
     chip(cw / 2 - tw / 2 - 12, ch - pad - 24, tw + 24, 26);
@@ -2576,6 +2612,9 @@ exposePort(net, {
   self: () => (me.has && mySeat() !== null ? { x: me.x, y: me.y } : null),
   size: R_AV,
   score: () => { const seat = mySeat(); const b = hosting ? [...bodies.values()].find((x) => x.seat === seat) : [...drawn.values()].find((x) => x.seat === seat); return b ? b.score : null; },
+  // The renderer's own counters, by the names `homie-studio perf` and the playtest read on the port probe (measured
+  // scene cost while playing; port/probe.ts PortExtra). Nobody dies in this game, so there is no `alive` to say.
+  extra: { drawCalls: () => renderer.info.render.calls, triangles: () => renderer.info.render.triangles },
 });
 
 void net.ready.then(() => {

package/worker/arrival.mjs

@@ -136,7 +136,10 @@ export const ARRIVAL_JS = String.raw`(function () {
   var stepEl = el.querySelector('[data-arrive-step]');
   var roomEl = el.querySelector('[data-arrive-room]');
   var bar = el.querySelector('[data-arrive-bar]');
-  var a = { phase: 'room', step: stepEl.textContent, p: 0.06, lookMs: null, liftedMs: null, by: null, mode: null };
+  // mode: who was to say when the game is playable ('auto': the helper, 'game': the game, 'seat': an older helper);
+  // explicitMs: when the game itself said so (the page's clock; null: it never did); lateMs: how long after an
+  // automatic arrival had already lifted the card that was (null: it was not late). The shell's script fills both.
+  var a = { phase: 'room', step: stepEl.textContent, p: 0.06, lookMs: null, liftedMs: null, by: null, mode: null, explicitMs: null, lateMs: null };
   api.state = a;
   // The card's first frame on the screen: what perf reads as the time to the first meaningful frame.
   frame(function () { frame(function () { a.lookMs = Math.round(now()); mark('homie:look'); }); });

package/worker/discover.mjs

@@ -8,17 +8,17 @@
  *   /sitemap.xml     every public page (Home, Games and each landing, Music, Videos, Rooms, Posts, the studio's own
  *                    pages), with lastmod only where a real date says when it changed
  *   /llms.txt        the llms.txt convention (an H1, a > summary, then ## sections of links): what the studio is, each
- *                    public game with its pitch, players, Play, Watch, the big screen and whether and how it can be
- *                    remixed (the licence, the source, the words to say to Claude Code or Codex with Homie), songs,
+ *                    public game with its pitch, players, Play, Watch, the big screen, the licence it names and the
+ *                    game it was based on (when it has either), songs,
  *                    videos, posts with their feeds, the studio's own pages, and a link to homie.rocks's llms.txt
  *   /llms-full.txt   the same, with each game's whole description, how to play, controls and credits, and every
  *                    post's text
  *
- * Only public games are ever named (a private or invite-only game is in none of them), and a game is offered for
- * remixing only when its owner's remix switch is on, its source is shared and its licence allows it. A file of the
+ * Only public games are ever named (a private or invite-only game is in none of them), and no game is offered to
+ * be taken whole (the pieces a studio shares are its parts, at /parts/, worker/parts.mjs). A file of the
  * studio's own in site/public (robots.txt, sitemap.xml, llms.txt, llms-full.txt) wins over the made one.
  */
-import { licenseOf, LICENSE_KINDS, remixRow } from './license.mjs';
+import { basedOnRow, licenseLabel } from './license.mjs';
 
 export const DISCOVERY_FILES = ['/robots.txt', '/sitemap.xml', '/llms.txt', '/llms-full.txt'];
 
@@ -111,15 +111,6 @@ export function sitemapXml(cat, origin, opts = {}) {
 
 /* ------------------------------------------------------------------ llms.txt */
 
-const HOMIE_INSTALL = 'in Claude Code, `/plugin marketplace add homie-rocks/homie` and then `/plugin install homie@homie` (Codex takes the same marketplace)';
-
-function licenceWords(g) {
-  const l = licenseOf(g.license);
-  const name = `${LICENSE_KINDS[l.kind]}${l.spdx ? `, ${l.spdx}` : ''}`;
-  if (l.kind === 'remix-freely') return `${name}: a credit is welcome, not asked for`;
-  return `${name}: a remix says "Remix of ${one(g.name, 80)} by ${one(g.studio, 80)}" with a link back`;
-}
-
 function summaryOf(cat, origin) {
   const name = studioName(cat);
   const tag = one(cat.studio?.tagline, 140);
@@ -137,8 +128,8 @@ function summaryOf(cat, origin) {
   ];
 }
 
-/** /llms.txt. `remixable(g)`: the owner's remix switch is on, the source is shared, and the licence allows it. */
-export function llmsTxt(cat, origin, { remixable = () => false, directory = 'https://homie.rocks', full = false, posts = null, all = null } = {}) {
+/** /llms.txt (and, with `full`, /llms-full.txt). */
+export function llmsTxt(cat, origin, { directory = 'https://homie.rocks', full = false, posts = null, all = null } = {}) {
   const name = studioName(cat);
   const games = (cat.games ?? []).map((g) => ({ ...g, studio: name }));
   const songs = cat.songs ?? [];
@@ -154,9 +145,10 @@ export function llmsTxt(cat, origin, { remixable = () => false, directory = 'htt
       const L = g.landing ?? {};
       const doors = [`Play: ${origin}/${g.id}/play`, ...(watchable(g) ? [`Watch a live room: ${origin}/${g.id}/watch`] : []), ...(tv(g) ? [`On a TV: ${origin}/${g.id}/tv`] : [])];
       const facts = [players(g), rounds(g.roundSeconds), ...(Array.isArray(g.genre) ? g.genre : g.genre ? [g.genre] : [])].filter(Boolean).join(', ');
-      const lineage = remixRow(g.remixOf);
-      const open = remixable(g);
-      out.push(`- [${label(g.name)}](${origin}/${g.id}/): ${one(L.pitch || g.blurb, 240)}${/[.!?]$/.test(one(L.pitch || g.blurb)) ? '' : '.'} ${facts}.${lineage ? ` A remix of ${one(lineage.name, 80)}${lineage.studio ? ` by ${one(lineage.studio, 80)}` : ''}.` : ''} ${doors.join('. ')}. ${open ? `Open to remix (${LICENSE_KINDS[licenseOf(g.license).kind]}${licenseOf(g.license).spdx ? `, ${licenseOf(g.license).spdx}` : ''}): see Remix below.` : 'Not open to remix.'}`);
+      // The credit a game owes the one it was made from, and the licence it names for itself: facts, when it has them.
+      const lineage = basedOnRow(g.basedOn ?? g.remixOf);
+      const licence = licenseLabel(g.license);
+      out.push(`- [${label(g.name)}](${origin}/${g.id}/): ${one(L.pitch || g.blurb, 240)}${/[.!?]$/.test(one(L.pitch || g.blurb)) ? '' : '.'} ${facts}.${lineage ? ` Based on ${one(lineage.name, 80)}${lineage.studio ? ` by ${one(lineage.studio, 80)}` : ''}.` : ''} ${doors.join('. ')}.${licence ? ` Licence: ${licence}.` : ''}`);
       if (full) {
         const C = L.credits ?? {};
         const lines = [];
@@ -173,12 +165,6 @@ export function llmsTxt(cat, origin, { remixable = () => false, directory = 'htt
         for (const l of lines) out.push(`  ${l}`);
       }
     }
-    const open = games.filter((g) => remixable(g));
-    if (open.length) {
-      out.push('', '## Remix', '');
-      out.push(`Homie is a plugin for Claude Code and Codex that makes multiplayer games in a studio of your own, on your own free Cloudflare account. To remix one of these games, ${HOMIE_INSTALL}, then say "Remix <game> from <its source address> into a game of my own in my Homie studio". The plugin's \`game_remix\` tool (or \`npx --no-install homie-studio game remix <source address> --id <new-id>\` in a studio's folder) copies it in and writes the credit its licence asks for.`, '');
-      for (const g of open) out.push(`- [${label(g.name)} source](${origin}/games/${g.id}/source.json): ${licenceWords(g)}. Say: "Remix ${one(g.name, 80)} from ${origin}/games/${g.id}/source.json into a game of my own in my Homie studio".`);
-    }
   }
   if (songs.length) {
     out.push('', '## Music', '');