Lab

The Game Lab: one mechanic, New against Today

A studio is the folder with studio.json. The lab is npx --no-install homie-studio lab <game> (from @homie-rocks/studio 0.20.0): a page on this computer that plays a take (games/<game>/lab.json) in New (the working tree, rebuilt on every save) beside Today (HEAD, or --today <ref>). Both run on the lab's clock: frame f is exactly f/fps seconds, the dice are seeded, the presses land on the same frames, so a take plays the same every time and the two builds can be compared frame by frame. The page checks that too: "Replays match" (or where they differ). homie-studio lab check <game> plays the same take headless and writes numbers, a contact sheet and a still.

The game opts in with a few calls from @homie-rocks/studio/lab (every one a no-op outside the lab, so they stay in the game). references/API.md has every call, the take format and the multiplayer rules; references/PRINCIPLES.md has the principles of feel this skill works from, with honest sources.

0. Before anything

• df -h .: keep 10 GB free. Commit or stash what the person is working on: Today is a commit, and the lab never touches git beyond reading it (Today is built from git's own checkout of the ref, in .studio/lab/, git-ignored).
• Name the mechanic in one line with the person ("the bump in Gem Rush: you wave, a body near you flies"), and find it in the code: the input that starts it, the state it changes, where it is drawn. Say which numbers shape it.

1. Instrument it, change nothing, commit

Make the lab able to see the mechanic without changing how it feels (Today must be the game as it is):

1. tunables.json next to game.json: move the numbers that shape the mechanic into it, at their current values, each with a range, a unit, a group and a note in plain words. Read them with const T = lab.tunables(tuning).
2. Phases at its natural beats: lab.phase('LAUNCH', 'Leaves at full speed, slows evenly'), lab.phase(null) when it is over. Short capital names; the note says what the phase is FOR. Name today's phases honestly: a mechanic with no anticipation has no COIL.
3. Tracks that show its motion: speed, height, distance, squash, a camera's offset (lab.track(name, v, unit)). Speed from the position each frame (distance / dt) is honest whatever the code does inside.
4. Poses and overlays: lab.pose('subject', { x, y, sx, sy, a }) each frame, and the game's own onion (ghosts every few frames), arcs (the path with a dot a frame: spacing) and a reach or hit box (lab.overlay), drawn by lab.draw(ctx, scale) in world space.
5. Views: lab.camera({ game: null, close: { zoom: 2.4 }, arena: { whole: true } }); 3D: side, front, top, orbit.
6. Characters (@homie-rocks/studio/animate): pass the lab's tunables to loadCharacter(models, url, { tune: T }) and copy its ANIM_TUNING (fade, walkSpeed, runSpeed, actSpeed, jumpStretch, landSquash, squashHz, lean, flinch, lookAt, spring) into tunables.json's "Motion" group: the clips' blends, the squash and stretch and the lean become sliders too. Report the character's own state (IDLE, RUN, JUMP, FALL, LAND, ATTACK, HIT) as phases when the move is an animation. The hero-rush-3d starter's takes ("jump", "swing") show it; the animate skill has the rest.
7. A stage when the mechanic needs a target (a dummy to hit, a ledge to jump from): lab.stage === 'dummy' where the round starts. Only the lab ever sets it. Keep a real-play take too.
8. A take in lab.json: a few seconds, a seed, the presses ({ "at": 0.5, "key": "Space" }), the view and track to open on. Or record one: press REC in the lab and play it in NEW (both builds get the presses).

Guard allocation: report from one if (lab.on) labReport(dt) a frame. Then:

npx --no-install homie-studio lab check <game>     # phases show, replays match, New = Today
git commit -m "Lab: instrument <the mechanic> (no change to how it feels)"

2. Look for what it is missing, with the person

Open the lab (npx --no-install homie-studio lab <game>, a background task; give the person the link; never open a browser yourself) and read the take at ¼ speed with the onion skin and arcs on. Say what you see in the terms of references/PRINCIPLES.md: no anticipation, no impact moment (hit-stop), even spacing (no ease), a creep and a pop at the end, no follow-through or overlap, a rigid body (no squash and stretch), a camera that never reacts.

References: describe the principle and, if it helps, a well-known game where anyone can see it, in your own words. Never copy another game's art, code, sounds or frame data, and never state another game's exact numbers unless you measured them yourself from footage the person can see or a public source you name.

3. Propose it as phases and tunables, then build New

Write the proposal as the phases the move will have and the number that shapes each one, for example:

HIT-STOP 70 ms (the body holds, white, squashed) → LAUNCH (leaves at 1500 px/s, stretched 30%) → SLIDE (eases into the stop over 185 px, the same at 12 fps as at 60) → SETTLE 260 ms (squash, then a wobble: overlap).

Change the game in the working tree; the lab rebuilds New on save and replays the take. Then:

npx --no-install homie-studio lab check <game>     # New against Today: phases, peaks, JavaScript per frame

Read REPORT.md and look at sheet.png (the lab at each phase's start, New beside Today) before you say anything about it. Tell the person in a few lines: which phases New has that Today did not, the numbers that moved, and what to watch for in the lab. The person tunes with the sliders and presses Keep in code (written into tunables.json, one line a value), or tells you, and you run npx --no-install homie-studio lab set <game> name=value.