@homie-rocks/studio 0.5.0 → 0.7.0

package/netplay/NETPLAY.md

@@ -1,8 +1,19 @@
-# Homie netplay contract, v1 (revision 2)
-
-Status: **v1, revision 2** (2026-09-26). The wire version is `v: 1`. Everything revision
-2 added is either an optional field or a new message type, and both sides ignore types
-they do not know. A change to the contract bumps `v` and keeps v1 working.
+# Homie netplay contract, v1 (revision 3)
+
+Status: **v1, revision 3** (2026-09-30, `@homie-rocks/studio` 0.6.0). The wire version is
+`v: 1`. Everything revision 2 and 3 added is either an optional field, a new message type,
+or a change of pace inside the old caps, and both sides ignore types they do not know. A
+change to the contract bumps `v` and keeps v1 working.
+
+**What revision 3 added** (nothing on the wire changed; every v1 game plays on it):
+- **Rooms of up to 32 seats**, sized by the game's netplay manifest (section 3).
+- **One address may hold every seat plus four sockets** (section 6), so a party on one
+  Wi-Fi fills a 32-seat room with a TV beside it.
+- **The checkpoint, round and roster caps double for 17–32 seats** (section 6): a
+  32-seat courier game's checkpoint measured 56 KB against the 64 KB cap.
+- **Idle input keepalive** in the helper: an unchanged input frame goes out at most four
+  times a second (section 11).
+- Measured cost and free-plan headroom of a 32-seat room (section 11).
 
 **What revision 2 added:**
 - Interpolation measures transit time.
@@ -95,8 +106,12 @@ code.
 | `colour` | `seat % 12` | An index into a 12-colour palette. |
 
 - **Every visitor gets a seat at once**, phone or desktop. There is no gathering.
-- **Room size.** `maxPlayers` comes from the manifest. On the site the Table reads it.
-  Locally, the first visitor of an empty room sends it in `hello.max`.
+- **Room size.** `maxPlayers` comes from the game's netplay manifest: game.json's
+  `netplay.maxPlayers`, or a `netplay.json` beside game.json or in the game's build
+  (`maxPlayers` or `players.max`), else game.json's `players.max`, else 8. **A room holds
+  at most 32** (`SEAT_MAX`). `homie-studio build` writes the number into the catalogue and
+  the site's Table takes it from there; the first visitor of an empty room may lower it
+  (`hello.max`), never raise it.
 - **A dropped seat is held 60 s** for its token, which covers a reload or a network blip.
   **A visitor who is present beats one who left:** when no seat is free, the relay
   reclaims the seat that has been absent longest. Visitors who leave can never lock a
@@ -259,13 +274,15 @@ so `ev.origin` is `"null"`.
 | `in` | < 256 B | 2 KB | 20 Hz, plus an immediate flush (≤ 60 Hz) on a press edge | 60 |
 | `ev` | < 1 KB | 4 KB (512 B from a screen) | as needed | host 30, replica 10, screen 2 |
 | `state` | < 2 KB per key | 8 KB per key; **64 keys and 64 KB per room** → `state-full` | only on change | 64 |
-| `ckpt` | < 32 KB | 64 KB | 1 Hz | 4 |
-| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB | on change | 4 / 8 |
+| `ckpt` | < 32 KB | 64 KB (128 KB for 17–32 seats) | 1 Hz | 4 |
+| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB (16 / 8 KB for 17–32 seats) | on change | 4 / 8 |
 | `ping` | — | 256 B | every 2 s | 8 |
 
 **Sockets.**
-- At most `maxPlayers + 16` per room, and **12 per client address per room**. The Worker
-  passes `CF-Connecting-IP` as `conn.ip`.
+- At most `maxPlayers + 16` per room, and per client address per room **12, or every seat
+  plus four when that is more** (`perAddress`: 12 for 8 seats, 20 for 16, 36 for 32). The
+  Worker passes `CF-Connecting-IP` as `conn.ip`. Measured before revision 3: 32 visitors on
+  one address got 12 seats and 20 `too-many` refusals.
 - A client dropping more than 100 messages over the caps within 5 s is closed (`flood`).
 
 **Keep it small.**
@@ -494,6 +511,31 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
   writes/h ≈ $0.07/h, 9× everything else), or rewriting a whole log per event.
 - Re-check Cloudflare's published prices before quoting.
 
+**A 32-seat room (measured 2026-09-30, `@homie-rocks/studio` 0.6.0).** Every incoming
+socket message is a Durable Object request (billed 20:1; outgoing messages are free), and
+in a full room the replicas' inputs are nearly all of them:
+
+| 32 seats, one host | Incoming msgs/s at the relay | Requests/hour (20:1) | Free plan (100,000 a day) |
+|---|---|---|---|
+| every replica moving, input 20 Hz | ≈ 630 | ≈ 114 k | ≈ 53 room-minutes a day |
+| a game's own vendored helper, input 30 Hz | ≈ 860 | ≈ 155 k | ≈ 39 room-minutes a day |
+| half the replicas standing still, 0.6.0 helper | ≈ 415 | ≈ 75 k | ≈ 80 room-minutes a day |
+
+  - Put another way, the free plan carries roughly **28 player-hours a day** at 20 Hz input
+    (each seated player costs about one request a second). A studio that plays more than
+    that a day needs Workers Paid ($5 a month), where a full 32-seat room-hour costs about
+    $0.02 in requests plus $0.006 in duration.
+  - **Idle keepalive (helper, 0.6.0):** an input frame identical to the last one sent (same
+    avatar or intent, same held keys, no press, same reset epoch) is re-sent at most every
+    250 ms. The host already holds that frame, so nothing it reads changes. A player standing
+    still costs 4 messages a second instead of 20. A game that vendors its own copy of the
+    helper gets this by updating that copy.
+  - Keep `inputHz` at 20 unless the game needs more: 30 Hz costs 1.5× the requests.
+  - Snapshots of a real 32-seat courier game (32 bodies plus the control table) were 1.1–1.7 KB at
+    20 Hz: about 32 KB/s down per replica, 2 KB/s up. No snapshot delta or compression was
+    needed; the 2 KB target and 16 KB cap hold at 32 seats. Duration (13,000 GB-s a day free)
+    covers one busy room all day.
+
 ## 12. Trust and safety
 
 - **The host is a visitor's browser.** A modified host could fake scores. That is
@@ -569,7 +611,8 @@ npx --no-install homie-studio check my-game --url http://127.0.0.1:8787
     candidate for v2, not in v1.
 - **No lag compensation for hits.** A game can rewind a victim by the attacker's
   `rtt/2 + delay` itself.
-- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B).
+- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B;
+  a 32-body courier game's snapshot: 1.1–1.7 KB).
 - **A reload shows a bot in the player's body for about 1–2 s**, and then the player
   takes the same body back.
 - **The host is a visitor's browser** (section 12).

package/netplay/netplay.ts

@@ -161,6 +161,8 @@ export interface NetStats {
   snapHzOut: number;
   inputHzIn: number;
   inputHzOut: number;
+  /** Idle input frames not sent (identical to the last one, inside the keepalive interval). */
+  idleInputsSkipped?: number;
   lastSnapBytes: number;
   maxSnapBytes: number;
   bytesInPerS: number;
@@ -507,6 +509,13 @@ const IN_SLOW_CAP_PER_S = 15;
 const IN_SLOW_MS = 8000;
 /** A socket with this much still unsent does not queue another input frame (the newest one waits instead). */
 const IN_BACKLOG_BYTES = 2048;
+/**
+ * An input frame identical to the last one sent (same avatar or intent, same held keys, no press, same reset epoch)
+ * goes out at most this often: a player standing still says so four times a second, not twenty. The host already
+ * holds that frame, so nothing it reads changes; every incoming socket message is a Durable Object request
+ * (billed 20:1), and in a 32-seat room the replicas' inputs are nearly all of them (NETPLAY.md §11).
+ */
+const IDLE_INPUT_MS = 250;
 
 function heldList(held: Iterable<string> | Record<string, boolean> | undefined): string[] {
   if (!held) return [];
@@ -635,9 +644,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let prevHeld = new Set<string>();
   let pendingPresses: Record<string, number> = {};
   let inputTimer: ReturnType<typeof setTimeout> | null = null;
+  /** The last input frame sent, as text (idle frames repeat it at most every IDLE_INPUT_MS). */
+  let lastInputSig = '';
   /** Wall times of the input frames sent in the last second, and until when the slow cap holds. */
   const inSent: number[] = [];
   let inSlowUntil = 0;
+  let idleSkipped = 0;
   /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
   let closedWhy: string | null = null;
   /** Wall time the socket went down (0 while connected): how long a reconnect has taken. */
@@ -1071,12 +1083,17 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     const budget = inputBudgetWait();
     const backlog = (ws?.bufferedAmount ?? 0) > IN_BACKLOG_BYTES;
     if (budget > 0 || backlog) { inputTimer = setTimeout(flushInput, backlog ? Math.max(budget, 30) : budget); return; }
+    // Standing still: the host has this exact frame already. Say it again only as a keepalive.
+    const pressed = Object.keys(pendingPresses).length > 0;
+    let sig = '';
+    try { sig = JSON.stringify([pendingA, pendingHeld, mine.rs]); } catch { sig = ''; }
+    if (!pressed && sig && sig === lastInputSig && wall() - lastInputSentAt < IDLE_INPUT_MS) { idleSkipped += 1; return; }
     inSent.push(wall());
     inSeq += 1;
     const msg: Record<string, unknown> = { t: 'in', q: inSeq, a: pendingA, h: pendingHeld, r: mine.rs };
     if (Object.keys(pendingPresses).length) msg['p'] = pendingPresses;
     if (raw(msg)) {
-      inputOut.hit(wall()); pendingPresses = {};
+      inputOut.hit(wall()); pendingPresses = {}; lastInputSig = sig;
       sentHist.push({ q: inSeq, a: pendingA, h: pendingHeld, at: wall(), r: mine.rs });
       if (sentHist.length > 64) sentHist.shift();
     }
@@ -1095,7 +1112,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     const t = wall();
     return {
       role, seat, host, connected, offline, rtt, offset: Math.round(offset),
-      snapHzIn: snapIn.hz(t), snapHzOut: snapOut.hz(t), inputHzIn: inputIn.hz(t), inputHzOut: inputOut.hz(t),
+      snapHzIn: snapIn.hz(t), snapHzOut: snapOut.hz(t), inputHzIn: inputIn.hz(t), inputHzOut: inputOut.hz(t), idleInputsSkipped: idleSkipped,
       lastSnapBytes, maxSnapBytes, bytesInPerS: perSecond(bytesIn), bytesOutPerS: perSecond(bytesOut),
       interpDelay: Math.round(interpDelay()), snapAgeP90: Math.round(ageP90), starvedPct: +starvedPct.toFixed(3), rejectedSnaps,
       owned: api.owned, pending: sentHist.length, stateKeys: stateMap.size,

package/package.json

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

package/site/SITE.md

@@ -0,0 +1,128 @@
+# The studio site
+
+`npm run build` (`homie-studio build`) makes a studio's whole site from the studio's own folder, and the
+studio's Worker serves it. Every studio site has the same sections as homie.rocks, in the studio's own look,
+and every game gets a landing page. Anything the studio puts in `site/` wins.
+
+## Sections
+
+| Address | What it is | Shown when |
+| --- | --- | --- |
+| `/` | Home: the featured game as a full-bleed hero with Play, the live rooms, the games, the latest posts, videos and music | always |
+| `/games/` | Every game, with its cover, pitch, players playing now, Play and About | the studio has a game |
+| `/music/`, `/videos/` | Songs and videos (`media/MEDIA.md`) | the studio has one published |
+| `/rooms/` | Every public room playing now across the studio's games, each with Join (`/api/rooms` is the same as JSON) | the studio has a game |
+| `/posts/` | The studio's posts, newest first, with `/posts/feed.xml` (Atom) and `/posts/feed.json` (JSON Feed) | the studio has a post |
+
+A section with nothing in it has no tab, and its address answers 404. Every page ends with a
+"Made with Homie" link to https://homie.rocks/studio/. studio.json may add `"tagline"` (one line, on Home and in
+the feeds) and `"site": { "featured": "<game id>" }` (the game on Home; otherwise the first with its own footage).
+
+## A game's landing: `/<id>/`
+
+Made from the game's own files, nothing invented:
+
+- **The hero**, full-bleed: the game's footage when it has some, else its cover (or key art) moving slowly, tinted
+  with the studio's colour so the words read. Footage is looked for in this order: `landing.hero` in game.json;
+  `games/<id>/hero/` by the house brands' names (`wide.mp4` and `tall.mp4`, their AV1 cuts `wide.av1.mp4` and
+  `tall.av1.mp4`, stills `wide.jpg` and `tall.jpg`); a trailer in `videos/manifest.json` whose `for.game` is the
+  game (its 16:9 `video`, 9:16 `vertical` and `poster`). A loop of 8 to 15 s under 3 MB each, muted, plays best.
+- **The pitch** (`landing.pitch`, else the blurb), a big **Play** button that drops into a public room at once,
+  and the live line ("3 players playing right now", refreshed every 15 s from `/<id>/live`).
+- **Phone, computer, TV**: the controls for each (`landing.controls`, else `credits.json` `controls`), a code a
+  phone scans to play, and how to put the game on a TV (`/<id>/tv` shows the room with its own join code).
+- **Live rooms**, each with Join. When studio.json shares its stats (`stats.share`), also "played this week".
+- **How to play**: `landing.about`, `landing.howToPlay` (a few lines), the controls, the room facts.
+- **Credits**: the studio and `landing.credits` (`[{ "role", "name", "url" }]`); for a port, the original, its
+  author and licence and every part inside it (`credits.json`, as the port skill writes it), with the full
+  licence texts on `/<id>/credits`; and Homie's open engine.
+- **Make a game like this**: the two commands that install the Homie plugin and the words to say. When the game
+  shares its source (the default; `"share": { "source": false }` keeps it closed) the words remix it from
+  `/games/<id>/source.json`, and the button goes to `https://homie.rocks/studio/?remix=<that address>`.
+
+game.json's `landing` block, every key optional:
+
+```json
+"landing": {
+  "pitch": "Blast rocks, not friends.",
+  "kicker": "A line above the title",
+  "headline": "The How to play heading",
+  "about": "A paragraph about the game.",
+  "howToPlay": ["Steer with the stick", "Fire at the edge"],
+  "controls": { "phone": "Stick left, FIRE right", "computer": "Arrows and Space", "tv": "Phones are the pads" },
+  "players": { "one": "pilot", "many": "pilots" },
+  "hero": { "video": "hero/wide.mp4", "tall": "hero/tall.mp4", "image": "hero/wide.jpg", "tallImage": "hero/tall.jpg",
+            "alt": "What the footage shows", "focus": "50% 40%", "tint": 30 },
+  "credits": [{ "role": "Music", "name": "Low Tide", "url": "https://example.com" }],
+  "theme": { "accent": "#ff3bd4", "glow": "#00eaff" },
+  "tv": true
+}
+```
+
+## Posts: `posts/*.md`
+
+One markdown file each. The name is the address, `posts/2026-09-30-we-are-live.md` is `/posts/we-are-live/`, dated
+by its prefix unless the frontmatter says `date:` (a day, or a day and a time, UTC).
+
+```markdown
+---
+title: We are live
+date: 2026-09-30
+summary: One line for the cards and the feeds.
+image: /games/crown-thief/cover.jpg
+game: crown-thief
+song: theme
+video: trailer
+author: The studio
+draft: false
+---
+
+The body.
+```
+
+`game:`, `song:` and `video:` link one of the studio's own (a link to one the site does not have is left out,
+and the build says so); the post shows each as a card with Play, Listen or Watch. `draft: true` keeps it off the
+site. README.md and names starting with `_` or `.` are not posts.
+
+The markdown is a safe subset, rendered once at build time: headings (`#` is the page's second level), paragraphs,
+**bold**, *italic*, ~~struck~~, `code`, fenced code, links, images, lists, quotes and rules. Raw HTML is shown as
+text, and a link or an image goes only to `https://…` or a path on the site.
+
+Each post is also a record (`/posts/feed.json`, `_homie.record`): `{ "$type": "rocks.homie.studio.post", title,
+text (the markdown), createdAt, summary, links: [{ kind, id }] }`, the shape it keeps when studios publish posts to
+atproto later. `/.well-known/homie-studio.json` lists the latest posts for the homie.rocks directory.
+
+## What `site/` overrides
+
+| Put it in | What it does |
+| --- | --- |
+| `site/theme.json` | The tokens every page uses: `bg`, `fg`, `accent`, `glow`, `panel`, `accentInk` (colours: `#hex`, `rgb()`, `hsl()`, `oklch()`), `display`, `text`, `mono` (font lists), `fonts` (`[{ "family", "src": "/fonts/x.woff2", "weight": "400 800" }]`, files in `site/public`), `radius` (0 to 40), `mark` (a logo), `icon`, `social` (the share picture), `wordmark`, `uppercase: false`, `scheme: "light"`. Or `palette`: neon, dock, gold, acid, ember, orchid, tide, candy. A value that is not what it should be is dropped, with a warning. |
+| `site/theme.css` | CSS after the site's own, on every generated page: restyle anything. |
+| `site/partials/<name>.html` | A piece of every generated page: `head` (in `<head>`), `header` (the top line and its tabs), `footer` (the "Made with Homie" footer), `home` (a band on Home), `game` (a band on every landing), `game-<id>` (a band on one), `post` (after a post). `{{studio.name}}`, `{{game.name}}`, `{{game.id}}`, `{{game.play}}`, `{{year}}` are filled in. A band partial sits in one of the page's bands, unless it is its own `<section class="band">`. |
+| `site/pages/<path>/index.html` (or `site/pages/<path>.html`) | A whole page at `/<path>/`, served as it is, instead of the generated one (`site/pages/index.html` is Home, `site/pages/<id>/index.html` a game's landing) or beside them (`/about/`). It may borrow the site's parts: `<!-- homie:style -->`, `<!-- homie:header -->`, `<!-- homie:footer -->`, `<!-- homie:script -->`. The rooms, the game files, the API and the owner's pages are never a page's. |
+| `site/public/` | Files served as they are at the same path: fonts, a logo, hero footage, a page's pictures. |
+| `site/src/worker.mjs` | The Worker. A studio that keeps a whole brand site of its own (with its own routes) wraps the template's Worker here, as the house brands do; everything it does not answer goes to the template. |
+
+A studio with its own landing in `site/` keeps it: the template never replaces what the studio made.
+
+## The play page
+
+`/<id>/play` puts the visitor in a public room at once and writes the room into the address, so a reload comes
+back to it and a copied address brings a friend into it. A small room button at the edge (game.json
+`"screen": { "share": "top-left" }` moves it off the game's own HUD; top right by default) opens:
+**Invite** (the phone's share sheet, or the link copied), **Big screen** (`/<id>/tv` of this room, on another
+screen) and the room's code. A room code the relay cannot use (1 to 32 letters, digits, `-` or `_`) is refused
+on the page, never swapped for a public room. A player who typed no name gets a two-word handle.
+
+The game runs in a sandboxed frame with an opaque origin, which is why its allow list delegates with `*`
+(`fullscreen *; autoplay *; gamepad *`): Safari refuses a bare `gamepad` there (`getGamepads()` throws a
+SecurityError), so a controller would not work.
+
+## Headers
+
+Every HTML answer is `no-transform` (a custom domain's edge injects nothing: Web Analytics' automatic beacon
+posts to a `/cdn-cgi/rum` a Worker does not serve). Generated pages are never framed (`x-frame-options: DENY`,
+`frame-ancestors 'none'`), load scripts only from the site, and send `referrer-policy:
+strict-origin-when-cross-origin` (another studio's stats see which site sent a visitor, never the path). The
+play page and the game may be framed by the site itself and by the https origins studio.json lists in
+`"site": { "frameAncestors": ["https://…"] }`.