@homie-rocks/studio 0.49.0 → 0.50.1

package/guides/playtest/references/METHOD.md

@@ -0,0 +1,124 @@
+# The method behind the rows
+
+How a game gets judged honestly, and the ways a test lies. Everything here was measured on games that
+passed their tests and still failed people.
+
+## Play it like a person
+
+Hold a direction for most of a second, not one frame. Press the thing whose label sounds fun. Try the
+control you would try first if nobody had told you anything. A script that presses every button in
+order is a conformance test, and conformance is not what is wrong with a boring game.
+
+## The five numbers a round owes you
+
+| | say | why |
+| --- | --- | --- |
+| how long | seconds from start to finish, against the clock the game set | a 150-second round that ends at 40 means nobody has seen most of the game |
+| how it ended | who won and by how much | if you cannot tell, a stranger cannot either |
+| the tense moment | one sentence about the best five seconds, or "there wasn't one" | the answer that unsticks a stalled game |
+| what did nothing | any control that produced no visible change | a dead control is the first thing people notice |
+| what you wanted | the one thing you reached for and could not do | the next change |
+
+Add **lead changes** (the number that separates a race from a procession) and **whether doing nothing
+scores as well as playing** (the `play` row measures both humans).
+
+## Different strategies in different seats
+
+Seats that all play the same way can only prove the game runs. Give simulated seats different
+standing strategies, one per side of the decision the game claims to be about: the greedy one that
+takes the risk the design says should pay, the safe one, the one that goes near other players on
+purpose, the middle. Then read which one scored zero. On one game whose whole idea was "carrying more
+makes you a target", the greedy runner finished on 0, 0 and 0 in three rounds because at a full carry
+it was slower than the hunter and could never escape: the exciting strategy was arithmetic, and the
+game everyone described was never actually played. No screenshot and no reading of the code found it;
+three rounds with four strategies did, in two minutes.
+
+## The do-nothing test
+
+Write it first: a player who stops touching anything, at every place a player plausibly stops, for
+longer than anyone's patience. The game must come to get them (a nudge, a timer, the round moving on),
+never freeze, never go black, never soft-lock the room. Continuous worlds must also be tuned in real
+seconds: a decay tuned on a fast test clock empties a real room in a minute. Simulate a long idle
+stretch and read the state before and after.
+
+## Every scenario before "finished"
+
+1. One person alone, with bots, on a computer.
+2. One person on a phone, portrait and landscape (a game that needs landscape says so and survives the
+   turn).
+3. Two strangers who pressed Play at different times, including one who arrives mid-round and takes a
+   bot's place (and its score: a joiner inherits the body, so only a round that starts after both are in
+   says how they played).
+4. The host leaving mid-round: someone else continues the same round, clock where it was.
+5. The big screen (`/<id>/tv`): a spectator with no body, a join QR, the game moving.
+6. Nobody touching anything.
+
+Say which you tried. "We could not test it" and "we tested it and it was fine" must never sound alike.
+
+## The ten-second test
+
+Ten seconds of silent video, no context, on a phone someone is scrolling past: do they stop? Every
+change should leave one moment worth clipping (a knockout that reads from across a room, a comeback you
+can see coming, something that happens once a round and is unmistakable). A change that produced
+nothing you would cut fifteen seconds around produced polish; polish compounds slowly and nobody shares
+it. Take a swing (a hazard, a rule that changes the last ten seconds) rather than tuning a number.
+Readable at a distance: whose is that, what just happened, who is winning. Punctuate: silence, then a
+hit. A thing that happens constantly is wallpaper; once a round it is an event.
+
+## Judging, not building
+
+- **The builder never grades its own work.** A reviewer gets the goal, the bar and the running game,
+  never the builder's reasons.
+- **Measure, don't assert.** "I differenced the two frames: nothing moved more than 8 of 255" ends an
+  argument that prose cannot.
+- **Two instruments on the same build.** A reviewer given only pictures grades the picture: one scored
+  a game 34/100 for a hunted player drawn at 1.14:1 contrast against the searchlight meant to mark
+  him, while a play measurement of the same build found the round always ended at 40 s of 150 and the
+  risky strategy scored zero. Neither could see what the other saw. When they disagree, the fight
+  outranks the frame.
+- **The whole frame and a real round, regularly.** A reviewer shown a crop can only ask about the crop:
+  thirty-five changes in a row once went into one decorative prop, each winning its own comparison,
+  while the game as a whole did not improve.
+- **Judge the set.** Twenty screens that each passed review were one layout repeated fourteen times.
+  Put the whole set in front of one reviewer: squint, how many distinct shapes are there?
+- **A reference is a bar, not a template.** Ask "is it as good as that", never "is it shaped like that".
+- **Group findings by cause** before assigning work; five findings, one cause, one fix in the shared layer.
+- **A finding that names a relation has two sides**: "the brightest thing is not a player" can be fixed
+  by darkening the floor or brightening the player; move one side on purpose and check the other.
+- **Stop on a regression.** A change that is not clearly better than the one before is worse. Scores
+  like 48, 54, 58, 50, 42 mean the peak was 58: go back to it.
+
+## Measured bars
+
+| what | bar |
+| --- | --- |
+| seated and moving | under 10 s from pressing Play, first press moves you within about a second |
+| hold a direction 5 s | one straight line the pressed way on screen, camera yaw change under 10° |
+| alternate directions 10 s | every press goes the pressed way within 600 ms |
+| UI during play | at most about 12% of the screen, nothing opaque in the middle third |
+| look | no black or one-colour frame; detail at several scales (edge share of a finished-looking frame is several times a placeholder's) |
+| sound | starts on the first touch; every action answers; -16 to -12 LUFS while played; nothing clips; little lost on a phone |
+| rounds | two strangers meet in one room and both see a round finish; a killed host hands over in 5 s; a late joiner takes a bot's place |
+
+## How instruments lie
+
+- **A software renderer fakes a stuck game.** Headless Chrome without the GPU draws a WebGL game at 1-2
+  fps; count animation frames first and say BLOCKED under ~20 fps. With the GPU flags a headless shot
+  matches the real screen within a fraction of a luma point.
+- **Reading a WebGL canvas from a script returns black** unless it is read inside a late animation frame;
+  use a screenshot of the page (the compositor's picture) instead.
+- **A full-page screenshot stretches the viewport**, so phone-landscape media queries stop matching; take
+  the viewport only.
+- **Emulated phones pass while real phones fail.** Real touch on iPhone Safari differs (coalesced
+  moves, passive listeners, pointer ids, 120 Hz); the iOS Simulator is the closest thing to an iPhone
+  on a Mac (`xcrun simctl openurl booted <url>`, mouse drags become real touches). Say when a result
+  is emulation only.
+- **A delivered press is not a correct press.** Only the body's movement on screen proves direction.
+- **Gate on the thing itself.** "A sound file plays" and "a texture is bound", not a number a hiss and a
+  flat cube would pass. Ask what the cheapest thing that passes the check would be.
+- **A still is not the game.** A title card or the moment before a round starts is a picture of
+  nothing happening; shoot while it is being played.
+- **Another run can replace what you are judging.** Note the build you judged (a digest, a commit) before
+  and after.
+- A reviewer that shares your working folder can "tidy" your half-written file: commit before you hand
+  work to one.

package/guides/playtest/references/REVIEWER.md

@@ -0,0 +1,78 @@
+# Blind review: {{GAME}}
+
+You are reviewing a multiplayer web game you did not make. You have not seen its code, its plan or its
+maker's notes, and you must not read them: judge only what a player gets. You are demanding and fair,
+you have played the best browser party games, and your job is to find what would make a stranger
+leave, not to encourage the maker.
+
+The game: {{URL}} (strangers who press Play land in the same public room; bots fill empty seats; rounds
+end and restart by themselves). The playtest instruments already ran; their folder is `{{FOLDER}}`.
+
+## Look at these yourself, every one, before you read any number
+
+{{PICTURES}}
+
+## What the instruments measured
+
+{{NUMBERS}}
+
+`report.json` in the folder has every number. A BLOCKED row measured nothing; never read it as a pass.
+
+## Play it
+
+Play at least one full round yourself in a headless Chrome on the GPU
+(`--use-angle=metal --enable-gpu-rasterization --ignore-gpu-blocklist` on a Mac): once as a computer
+with the keyboard, and once as a phone (390x844, touch events: a thumb that lands, slides and holds).
+Take your own screenshots at moments you choose. Close every browser you open, at most two at a time.
+If you cannot play it, say so and score only what you saw.
+
+## Score it
+
+Each part 0-10, then an overall 0-100 that is your honest judgement, not the average:
+
+1. **First ten seconds**: in, seated and moving, knowing what to do, with no instructions read.
+2. **Controls**: every press means the same thing every second; the camera never turns on its own; a
+   phone thumb is as good as a keyboard.
+3. **The round**: a goal you understand, tension that rises, a finish you can see coming, results
+   that say who won and why. Does playing well beat doing nothing?
+4. **Look**: does it look finished at phone size, readable at arm's length, with a clear subject, detail
+   at more than one scale, and nothing flat or placeholder-like?
+5. **Sound**: does every action answer, does the music carry the round and change with it, is it
+   balanced and clean on a phone speaker?
+6. **Phone**: one-thumb play, UI out of the way (the middle of the screen clear), portrait and landscape.
+7. **Strangers**: with bots and other people, is it fun together, and does a late joiner fit in?
+8. **Clip test**: ten seconds of silent video on a phone someone is scrolling past. Do they stop?
+
+Then answer plainly: would you play another round? Would you send it to a friend? Would you pick it
+over the best browser party game you know? "No, and here is why" is a useful answer.
+
+## Rules for your findings
+
+- **Measure, don't assert.** "The score text is 11 px on a 390 px screen" beats "the HUD is small".
+  Every gap names its evidence: a picture and what is in it, or a number from the report or your own play.
+- **The fight outranks the frame.** If the pictures look fine and the round is boring, say the round is
+  boring; if doing nothing scores as well as playing, that is the biggest finding there is.
+- **Group by cause.** Five findings with one cause (no lighting, one missing sound bus) are one gap.
+- **One concrete fix per gap**, the smallest change that would move it, and which side of a relation
+  it moves ("make the player brighter than the floor" can be done from either side: say which).
+- **Impact 1-10**: how much fixing it would raise your overall score.
+- Say what you verified yourself and what you could not test.
+
+## Return exactly this JSON (save it as `{{FOLDER}}/VERDICT.json`)
+
+```json
+{
+  "score": 0,
+  "parts": { "first10": 0, "controls": 0, "round": 0, "look": 0, "sound": 0, "phone": 0, "strangers": 0, "clip": 0 },
+  "wouldPlayAgain": false,
+  "wouldSendToAFriend": false,
+  "summary": "two or three sentences a person could act on",
+  "verified": ["what you checked yourself, with how"],
+  "couldNotTest": ["what you could not test, and why"],
+  "gaps": [
+    { "title": "", "evidence": "", "fix": "", "impact": 0 }
+  ]
+}
+```
+
+Gaps sorted by impact, the largest first. No praise padding; no gap without evidence.

package/guides/playtest/scripts/lib/exit.mjs

@@ -0,0 +1,31 @@
+/**
+ * Ending a controller: after its report is written and its browsers are closed, the process leaves, with the exit
+ * code its result earned.
+ *
+ * Why this exists: a full run wrote its report, its sheets and the reviewer command, every Chrome and ffmpeg it
+ * owned had closed, and the Node process stayed. Node only leaves by itself when nothing is left on its event loop,
+ * and a controller that drives browsers collects things that sit there: a socket puppeteer kept, a pipe a child's
+ * helper inherited, a race's losing timer, an AbortSignal's timer. Which one it was that time was never isolated,
+ * so the end does not depend on finding it: run the cleanup (bounded), flush what was printed, then exit.
+ *
+ * The exit code is the one already decided (`process.exitCode`, or `code`): a failed run still exits non-zero.
+ */
+
+/** Race `p` against `ms`; the losing timer is cleared, so the race itself leaves nothing on the event loop. */
+export function within(p, ms, fallback = null) {
+  let timer = null;
+  const late = new Promise((r) => { timer = setTimeout(() => r(fallback), ms); });
+  return Promise.race([Promise.resolve(p).catch(() => fallback), late]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Run `cleanup` (at most `graceMs`), wait for stdout and stderr to drain (at most 2 s), then exit with `code`
+ * (default: process.exitCode, else 0). `exit` is process.exit (a test passes its own).
+ */
+export async function finish({ code = null, cleanup = null, graceMs = 15_000, exit = (c) => process.exit(c) } = {}) {
+  if (cleanup) await within(Promise.resolve().then(cleanup), graceMs);
+  // A pipe (a caller reading our JSON) takes writes asynchronously: an exit before the drain would cut the report.
+  const drained = (s) => new Promise((r) => { if (!s?.writableLength) r(); else s.write('', () => r()); });
+  await within(Promise.all([drained(process.stdout), drained(process.stderr)]), 2000);
+  exit(code ?? process.exitCode ?? 0);
+}