Playtest

Playtest a game

The question is never "does it run". It is: would a stranger who pressed Play stay for a whole round, and come back? Instruments measure what can be measured; a fresh reviewer who never saw the code answers the rest. A builder never grades its own work.

One script: scripts/playtest.mjs in this skill's folder (Claude Code: node "${CLAUDE_PLUGIN_ROOT}/skills/playtest/scripts/playtest.mjs" <command>), run from inside the studio. It needs Node 22, Chrome and the studio's @homie-rocks/studio (for puppeteer-core and its checks). It opens at most two browsers at a time, all muted: nothing plays out loud.

1. Run the site and the instruments

Start the site as a background task that outlives the command (Claude Code: the Bash tool's run_in_background), wait until the play page answers, then:

npm run dev                                     # background: http://127.0.0.1:8787 (another port: npx --no-install homie-studio dev --port <n>)
node <playtest.mjs> run <game id> --url http://127.0.0.1:8787

It takes five to ten minutes; poll its output, never end your turn while it runs, and do not rebuild while it runs (a rebuild under npm run dev can stop the dev server). --only first,look,ui,sound runs some rows; --seconds 30 plays longer. The live site works too (--url the studio's address). Stop the site afterwards with npx --no-install homie-studio dev --stop.

BLOCKED is never PASS. A browser rendering at a few frames a second (a software renderer, a machine under heavy load) makes any game look stuck: the rows say BLOCKED and judge nothing. Run again on a quieter machine. "Could not test" and "tested and fine" must never sound the same. The same goes for the instrument's own faults: a screenshot decoder that does not finish in 20 s is stopped, that device's rows say BLOCKED, the browser is closed and the run exits non-zero; a site address this computer's Node.js cannot look up (a browser may still open it) stops the run as BLOCKED, "network preflight failed, before any page or game was opened" (the words check, perf and port check use for it too), and offers the local site. N/A means the row did not apply to what was on screen. One scripted run is one run: report a gap as measured once, and repeat before concluding.

What the game tells the instruments

Every press and every picture is recorded with the game's state, read from its port probe (exposePort, the port skill) and the play page: round phase and time left, whether the body is the player's to steer (busy), where it is. A game with no probe still runs, and its rows say the phase was unknown. Three optional things make the rows sharper; none is required:

• In exposePort(net, { extra: { ... } }): alive: () => boolean (false: spectating until the next round), mode: () => string (the control mode on screen), loadout: () => string (what the player holds, when it changes which controls show), touchHeld: () => boolean, and drawCalls / triangles (renderer.info.render.calls / .triangles: the look row then reports measured runtime scene cost, which is not the asset inventory's estimate).

• In game.json, the primary action, so a shooter is played by firing and not by the space bar:

  "playtest": { "primary": { "label": "fire",
    "computer": { "mouse": "left" },
    "phone": { "selector": "[data-action=fire]" } } }

  computer is { "key": "<KeyboardEvent.code>" } or { "mouse": "left|right|middle", "at": [x, y] }; phone is { "selector": "<css, in the game's frame>" } or { "region": [x, y, w, h] } (fractions of the screen). Undeclared, the script presses the space bar and taps a fixed spot, says that was a guess, and qualifies anything it concludes from the scores. It does not aim.

• In game.json, "scoring": "together": every result row carries the room's one shared total, so the play row marks the active-against-idle comparison not applicable.

The UI row measures DOM coverage only. A HUD, labels or hints drawn inside the canvas are hidden with the world and are not checked for coverage or overlap; REPORT.md says so beside the result.

The UI row also lays the game's visible DOM HUD against the play page's own controls, which the page draws over the game's frame and reports as window.__shell.rects (the game reads the same as net.shell / net.on('shell')). A HUD element under a control that stays is a WARN with both named; under the "N playing" chip, which fades, it is a note. Fix it by laying the HUD out around net.shell's rectangles, or by moving the page's controls (game.json screen.share, screen.chat). A page that reports no layout (an older studio) is said to be unchecked.

A reading taken while the browser was not in its room is labelled, never judged as play: the helper's link (window.__homieNet.link, and window.__shell.link.state) says reconnecting, alone (the room never answered and the browser hosts by itself), offline or closed, and a press, a picture or a UI frame sampled then is BLOCKED or N/A with "CUT OFF from its room" in its state. The round row says a browser "was seen cut off" beside completion.

The run writes .playtest/<game>/<time>/ in the studio (added to .gitignore): REPORT.md, report.json, contact sheets (sheet-desk.png, sheet-phone.png, sheet-phone-landscape.png), every screenshot (the UI row's pair as *-ui-on-black.png and *-ui-on-white.png), sound-capture.wav and its spectrogram, and the owner-test receipts. Open the contact sheets and look at every picture before believing any number.