Perf

Make a game faster, honestly

The question is never "does it feel faster". It is: is this build measurably better than the one before it, beyond the noise, without looking or playing any differently, and does it still work? Every number here comes from a real Chrome on this computer's GPU, two browsers in a room (the host runs the rules and the bots, the replica draws from snapshots), playing the same seeded presses every run.

One script: scripts/perf.mjs in this skill's folder (Claude Code: node "${CLAUDE_PLUGIN_ROOT}/skills/perf/scripts/perf.mjs" <command>), run from inside the studio. It drives the studio's own @homie-rocks/studio (0.19.0 or later: homie-studio perf, perf compare, check, build --maps; 0.19.1 also reads whether each big script is minified), opens at most two browsers at a time, all muted, and writes everything it measures under .perf/<game>/ (git-ignored). It prints paths and a few numbers, never the data: read the files it names.

0. Before anything

• df -h .: keep 10 GB free (it keeps every build it measures). The computer may be shared: every run records the load, waits for a calm minute, and a run that started busy is taken again and left out. Never start other heavy work (a render, a build of something else, more browsers) while a loop runs.
• Start the site as a background task that outlives the command (Claude Code: the Bash tool's run_in_background): npm run dev (another port: npx --no-install homie-studio dev --port <n>). Never npm run build by hand while a loop runs: the script builds and swaps builds itself and checks the site serves exactly the build it means to measure (every file by SHA-256, and the game page as built). Scripts the site's Worker adds to the game page are the site's, not the build's: HOMIE_NET, and any a studio's own Worker injects (a small shim) are set aside, listed in BASELINE.md, and must stay the same through the loop. Don't change the Worker in the middle of a loop; start a new one.
• Commit or stash what the person is working on first: try only ever touches games/<game>/, and a revert puts that folder back to the kept build.

1. The baseline

node <perf.mjs> baseline <game> --url http://127.0.0.1:8787 [--goal phone.host.frame.p95] [--runs 6] [--seconds 15]

It builds the game keeping its source map (never shipped), runs the two-browser check (it must pass: a game that does not work is not made faster), measures --runs runs per device, profiles one run per device, and writes BASELINE.md in the loop's folder: every number with its run-to-run spread, the load during each run, the hottest functions (read through the source map: draw (src/main.ts:620), not Xe), what a player downloads, and what to try first, each hint naming the number it read. Ten to fifteen minutes; poll its output, never end your turn while it runs.

The goal is one metric, lower is better (perf.mjs goals lists them):

Read BASELINE.md before choosing. If frames already keep pace with the display (p95 about 16.7 ms), a faster frame cannot show on this profile: aim at busy (CPU per frame is battery and headroom on a slower phone), or measure a slower phone with --cpu 6 or 8. A goal can be changed per change with try --goal (a change aimed at load time is judged on load time); everything else stays guarded.

2. One change at a time

Pick the change from the profile and the hints, smallest first. Make one change in games/<game>/, then:

node <perf.mjs> try <game> --name "<the one change, in a line>" --looks same --plays same

It builds, runs the two-browser check (two fresh browsers must finish a round together), then measures the kept build and the changed one in turns (before, after, after, before, …), --runs each per device. Each before-run and the after-run beside it are a pair, so a computer that got busier halfway hits both sides of every pair and cancels. Then homie-studio perf compare:

• KEEP only when the goal is better beyond the noise: a one-sided signed-rank test on the pairs (Wilcoxon, exact) p < 0.05 (with 6 pairs: the change wins at least 5 and loses only the closest), the 95% bootstrap interval of the change below zero, and at least 3% better (--min at baseline). And no guard got worse (frame time, main thread per frame, time to playable, heap, the host's upload: worse in every pair, or p < 0.01, and at least 5%).
• REVERT otherwise: games/<game>/ goes back to the kept source (that folder only; files the change added are removed) and the kept build is served again. A change that measures the same is reverted: it costs reading, not frames. Never re-run a REVERT hoping for a luckier draw; change something else.
• BLOCKED: too many runs started on a busy computer. Nothing is decided and the change stays in place: run the same try again later, or revert.

--looks and --plays are required, every time. same is a promise the screenshots are checked against (brightness, contrast, detail, colour of each run's host screen, against their own run-to-run spread); anything else is said in words (--looks "shadows are softer at the edge") and goes into the report. A change made for how a move feels (the lab skill: a hit-stop, sparks, a squash) is measured here when it costs frames: its --looks and --plays name it. Never trade how the game looks or plays for frames without the person agreeing first; then say it. Fewer bots, a lower resolution, fewer particles, shorter view distance and fewer physics steps are all trades, not optimisations.

--measure (a change kept for another reason: how a move feels, from the lab skill): the same build, check, paired runs and comparison, reported as MEASURED with the verdict and every number, and nothing is reverted: the change stays in games/<game>/ and is served, and the build to beat stays what it was. Say what it costs in those numbers.

Each try takes ten to twenty minutes. Its folder (experiments/<n>-<name>/) has RESULT.md, change.patch, the runs and compare.json. status <game> lists the loop so far; revert <game> drops a change you made but never measured.

What usually helps, roughly in order (references/METHOD.md has the detail and the traps):

1. Work you do every frame that you could do once: gradients, paths, strings, new arrays and objects, measureText, querying the DOM, reading location or localStorage.
2. Work per thing that can be work per group: one path for many shapes, instancing in three.js, fewer state changes (composite modes, materials), fewer draw calls.
3. Garbage: a high gcPct or hitches every few seconds mean allocation in the loop.
4. Downloads: nothing that is never imported, big things after the first frame, and a minified copy (the same library version) of a script BASELINE.md says is not minified. That is read from the code (whitespace, comments, names), never from how well it gzips: minified JavaScript gzips about as well as source text, and a bundle with three.js in it carries the shaders as GLSL source in strings, which no minifier touches. Minifying it again gains nothing.
5. Netplay: snapshots that send what did not change; the host's upload grows with every seat (net.kbOut).