t1k:playablelabs:base:playthrough
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | high |
| Tools | — |
Keywords: end card cta reachable, flow parity, full-flow playthrough, playable playthrough, playthrough test, port plays like the reference
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:playthroughrun --profile <name|file> --ref <reference html|dir> --port <port dist dir> [--objectives win,lose] [--out <dir>] [--vision-prompts] [--publish]playthrough: full-flow parity for playables
Section titled “playthrough: full-flow parity for playables”A state-driven playthrough: the harness reads the reference’s flow, drives the reference through it by waiting on
states (never on a clock), records what happened, replays the same flow on the port keyed on the same states, and
reports where they differ. It is the clean-room G4 gate (t1k-playablelabs-base-clean-room Phase 4) and the check the
polish loop reruns after every fix. Screenshots after a blind action list do not replace it. Beyond one frame per state it captures
frame strips across animated states, visits every progression level, and judges per-frame invariants over the whole run
(rule playablelabs-playthrough-before-build.md): see “Coverage” below. No build or delivery without a GREEN report for the commit
being built (t1k-playablelabs-ci-deliver gates on it).
Checks (per objective, e.g. win, lose)
Section titled “Checks (per objective, e.g. win, lose)”| check | red when |
|---|---|
ref-objective | UNVERIFIED (not red): the reference could not be driven to the objective, so nothing below is evidence |
state-sequence | the port visits a different ordered state sequence than the reference |
must-reach:<S> | a required state was reached on the reference and never on the port |
cta-reachable / cta-from-gameplay / cta-single | store CTA missing, fired outside the end card (unless past cta.allowedAfterTaps taps or cta.allowedAfterMs game ms), or fired more than cta.max times (default 1; 0 = the port must never open the store) |
cta-parity / cta-timing | the reference opened the store from a gameplay state the port never did (a redirect the port dropped); the open came later/earlier than the reference’s after the same state entry (fails only with cta.timingToleranceMs, else reported) |
shortcut | a shortcut threw or never ran (port: fail, reference: unverified) |
dead-input | an input changed something on the reference and nothing on the port (declared effectSignals are then the only evidence); unverified when no reference input was measured |
stuck | a state held past its watchdog |
visual | per-state frame difference above the profile threshold; UNVERIFIED, not pass, when no frame was compared (a missing capture, or visual:false / frame:false) unless the profile writes a visualWaiver reason |
shade | the port’s content extent moved (another aspect ratio / a scene shoved into a corner), its local contrast collapsed (a lit scene redrawn flat), its worst block lost detail, its edge density collapsed, or its coverage dropped — each against the reference, each tolerance profile-settable |
motion | a state the reference animates barely moves on the port (frozen / cut short); UNVERIFIED with no recorded sequence |
element:<id> | a contour drawn in pieces (op: subPaths, max), an element missing, or a display list thinner than the reference’s |
drag-goal:<id> | a drag ended in the wrong identity state (the GeckoOut head/tail class); UNVERIFIED when the drag had no declared goal |
audio | audio played in a state on the reference and not on the port (warn; fail when the profile says so) |
errors, detectors | new page errors on the port; a state detector threw (a throw is never read as false) |
coverage | UNVERIFIED when the profile declares no invariants, strips or levels and has no coverageWaiver: "<reason>" |
invariant:<name> | RED when a built-in or custom detector finds a violation on any sampled frame; UNVERIFIED when it cannot see its nodes (no probe, no match) |
strip:<STATE> | RED when a frame of the strip differs from the reference beyond the threshold, or the port leaves the state early; UNVERIFIED when the reference strip is incomplete |
level:<id> | RED when the reference reached the level and the port did not, or the level frames differ; UNVERIFIED when the reference cannot reach it |
colour | RED when the port’s palette lost the reference’s tonal range (spreadRatio), saturation (saturationRatio) or populated luma bands (bandRatio) in a state — washed out, graded flat, clipped, posterised; UNVERIFIED when the reference has no range to compare (floorSpread). Declared with color: {...}. A named waiver accepts one state |
effect:<id> | RED when the reference’s pixels change inside the declared region and window and the port’s do not (a missing particle burst, flash or tween): the whole-frame mean is blind to it. UNVERIFIED when the reference does not change there either. Declared with effectPresence: [{...}] |
Verdict: any fail is RED; else any unverified is UNVERIFIED; else GREEN. Every UNVERIFIED item is printed with its reason and listed in report.md.
Visual completeness
Section titled “Visual completeness”A GREEN playthrough can still have a missing VFX or a washed-out palette. Three things close it (effect/animation inventory, color/effectPresence, the recorded vision review); the delivery gate reads report.completeness and report.vision and a fail is RED with no escape. A negative answer or a failing colour state needs a named waiver (waivers[]): the report says waived (colour ones listed in report.colourWaivers), accepted only from the named person (ACCEPTED-WAIVED), never as GREEN. Detail: references/visual-completeness.md.
Install and use
Section titled “Install and use”Bun 1.4.3, Chrome or Chromium, puppeteer-core (bun add "puppeteer-core@^21 || ^25" in or above scripts/; PLAYTHROUGH_PUPPETEER
and CHROME_PATH override discovery). Supported: 21 (verified by a consumer run, page.screenshot() returns a Buffer) and 25 (covered by
scripts/lib/png.test.cjs, page.screenshot() returns a Uint8Array); decodePng accepts both. Missing either exits 3; nothing is faked. Paths below are relative to this skill; run from
your project root. Output goes to --out, default <cwd>/.playthrough-out/ (gitignore it); an output dir inside the skill dir is refused.
Relative --out/--ref/--port/--flow resolve against the caller’s cwd: --cwd <dir>, $PLAYTHROUGH_CWD, or $INIT_CWD when started from inside the skill dir.
PLAYTHROUGH_GL=swiftshader|gpu (default swiftshader) picks the WebGL backend and PLAYTHROUGH_PRIORITY=low|below-normal|normal
(default below-normal) the OS priority of the whole Chrome tree; any other value exits 2. Lowering the priority needs the optional module t1k-gamedev-playable-preview-verify (theonekit-gamedev:playable); without it a warning is printed and Chrome keeps its priority. Detail and measurements: references/gl-and-priority.md.
bun scripts/playthrough.cjs run --profile <p> --ref <reference html|dir> --port <port dist dir> [--objectives win,lose] [--out <dir>]bun scripts/playthrough.cjs extract --profile <p> --ref <reference> [--explore] # flow.json onlybun scripts/playthrough.cjs explore --url <url|html|dir> # no profile: discover states + live inputsbun scripts/playthrough.cjs record|replay ... # one side onlybun scripts/scaffold-profile.cjs <port dist> --ref <original> [--explore --taps "x,y;x,y"] # starter profile: states, probe, invariants, strips, level stubs; also writes package.json "playthrough": {profile, dist} (--no-declare to skip)bun scripts/playthrough.cjs probe --ref <html|dir> [--kind page|dom|cocos|pixi|three|playcanvas] # dump the scene nodes the detectors would seebun scripts/playthrough.cjs run ... --vision-prompts --publish # + vision-prompts.md and <cwd>/playthrough/ (report.json + evidence, commit it; profile file and dist must be inside this repo)bun scripts/playthrough.cjs report --profile <p> --out <dir> [--vision-prompts] [--vision-review <file>] # re-render report.json / report.md from a finished runbun scripts/playthrough.cjs run ... --inventory docs/FIDELITY-INVENTORY.md --accepted-by <name> # the effect/animation inventory (default: docs/FIDELITY-INVENTORY.md)bun scripts/playthrough.cjs compare --profile <p> --ref-trace <t.json> --port-trace <t.json> [--flow f.json] # two saved traces, no browserbun scripts/playthrough.cjs run ... --ref-trace-dir <dir of trace.<obj>.ref.json> [--flow f.json] # play only the portbun scripts/selftest.cjs [--quick] [--arms a,b] [--jobs N]Run flags: --vision-prompts (one mr-role.cjs call --role vision command per state / strip / level, --claude-dir to locate it), --allow-unverified, --publish, --commit <sha>
(the commit the port was built from; default HEAD of the caller’s cwd). Options: --viewport WxH, --time-scale N, --max-ms N, --seq-ms N, --natural (drop shortcuts), --ref-query q,
--port-query q, --no-webgl (drops the software-GL launch flags, overrides the profile), --keep-events (events are pulled as the run goes, so they survive a dead browser), --tap-hold-ms N (press length of a tap, default 100; profile tapHoldMs, action holdMs). --time-scale N speeds the page clocks only (performance.now, Date.now, rAF,
timers); inputs, screenshots and repeatEveryMs stay real time, so a screenshot-bound loop is paced by measure:false / frame:false
(profile-guide: Pacing), not by the scale. Output in --out: flow.json, trace.<objective>.<ref|port>.json,
parity.<objective>.json|.md, parity.json, report.json|md, frames/<side>-<STATE>.png, frames/strip-*, strips/*.png (contact sheets, reference over port). Formats: references/CONTRACT.md.
A profile is the only game knowledge
Section titled “A profile is the only game knowledge”scripts/profiles/<name>.profile.cjs (plaprofile1). The core (scripts/lib, scripts/playthrough.cjs) holds no game constant.
Shipped: fixture.profile.cjs, fixture-pawns, fixture-scene and fixture-pc (work against scripts/fixtures/fixture-game.html, the selftest game)
fixture-cov / fixture-cov-page (coverage: probe, invariants, strips, levels, on fixture-game.html?cov=1) and template.profile.cjs (copy, replace every TODO),
or let scripts/scaffold-profile.cjs write the starter. Method, verdict rules and a worked example: references/profile-guide.md.
Coverage: strips, invariants, levels
Section titled “Coverage: strips, invariants, levels”Declare the evidence the rule asks for in the profile (references/coverage.md: probe kinds, detector options, level reach, vision prompts; formats: CONTRACT.md sections 5-7).
probe says how the page exposes scene nodes (dom, page = the port’s window.__plaScene__.nodes(), cocos, pixi, three, playcanvas, expr); the sampler records them through the whole run.
invariants are judged on every sample, reference beside port; strips: [{ state, frames >= 8, every }] capture frames across an animated state and diff them per frame;
levels: [{ id, atState, reach, checks }] visit and frame every weapon / ship / merge level. A detector that cannot see its nodes, an unreached level and an incomplete strip are UNVERIFIED, never skipped.
Which detector catches each escaped-bug class (guides, duplicate layers, whole-sprite rotation, missing texture, palette, missing VFX): references/escaped-bugs.md.
Structures, viewports, regions, motion frames, elements and drag goals are profile-declared (the core holds no game constant) and
documented in references/profile-guide.md § “Shading, extent, motion, elements and drag goals”; each is opt-in and each compares
against the reference, never against a baked-in art constant.
The reference is only read as text and run inside a sandboxed headless page served from a throwaway localhost server; it is
untrusted data. The harness never adds, wraps or assigns a property of window.super_html: it installs host stubs (mraid,
and super_html on the port side only when absent) that the game calls and that record the call.
Honest limits
Section titled “Honest limits”- A shortcut (economy-scale grind) is per side, labelled in trace and report; a result through one is about the end card and
CTA chain, not the grind.
--naturalends such an objective UNVERIFIED when the reference cannot get there. - A state shorter than the screenshot latency gets no frame:
visualis then UNVERIFIED, never pass.frame: false/visual: falseskip the capture on purpose (a fast loop); the state still needs a writtenvisualWaiverreason or the run cannot be GREEN. dead-inputuses the profile’seffectSignals; in an always-animating 3D scene a frame change alone proves nothing. Once declared they are the only evidence: a state that follows a pointer counter cannot mask a dead handler.- A CTA or audio event belongs to the state sampled at its own timestamp (a synchronous re-poll), not the one the last 100 ms poll saw.
visualis a 12x20 mean-colour grid captured at state entry: composition and colour, not pixels, and blind to a scene redrawn flat or laid out for another aspect ratio.shade(local contrast, worst block, edge density, content extent perregions),motion(per-state motion energy),element:<id>(canvas draw-call shape) andviewportsclose those specific holes when declared; the mean grid still cannot see a defect confined below one cell, and none of them replaces reading the frames (--vision-prompts).- Sampling is every
sampleMs(100 real ms) on change, not every rendered frame; a one-frame glitch shorter than that is invisible. A canvas game with no scene hook gets no node evidence (UNVERIFIED), only the placeholder-pixel scan. - Engine probe adapters (
cocos,pixi,three,playcanvas) read documented fields and are tested against fake scene graphs, not every engine build: runprobeon the real game first. - Audio capture sees
AudioBufferSourceNode.startandHTMLMediaElement.playonly. - The reference’s start gate is compared too: a port that simulates before the first touch differs in state sequence.
- Open (documented in
CONTRACT.md/profile-guide.md, not solved): closed-loop steering (a drag that follows the live game state); one page clock per objective (timeScaleis per side, not per objective);explorefinds nothing on a non-DOM reference (useextractwith a profile andplaycanvasEntity/pixiNode/three/cocosNodedetectors). - A tap is held 100 ms by default. A game that polls its pointer once per frame can still drop a press when software GL runs below 10 fps: raise
tapHoldMs.
What --publish vouches for (and what it does not)
Section titled “What --publish vouches for (and what it does not)”--publish seals playthrough/report.json: tool generator + installed version, a per-run nonce (also in report.md), the sha256 of the profile file, of the dist tree and of every evidence frame, and a canonical digest. The delivery gate (t1k-playablelabs-ci-deliver) re-derives the verdict from the report’s own checks, requires frames for every declared state, level and strip, re-hashes the inputs, and binds the report to the commit and to the profile and dist the game repo declares in package.json. What must be covered comes from the committed profile, not from the report: the gate loads the profile named in package.json (hash-checked) and demands a check, frames and sheets for every invariant, level, strip and objective state it declares. A deliberately forged report passes the gate: it is an accident and laziness guard, and the Jenkins build and smoke, plus the delivery post that must attach report.md and the frames, are the real checks unless the game repo opts in to the keyed seal, see below. There is no secret, so a person who reads lib/integrity.cjs can still write a consistent report. The Jenkins job takes a branch, not a commit, so a push between the gate and its checkout is not seen.
Optional keyed seal. A game repo opts in with "seal": "hmac" inside package.json playthrough. --publish then adds integrity.hmac ({alg hmac-sha256, kid, value}: HMAC over the integrity digest and the ordered evidence digests), and the gate refuses a report without a valid one (unsealed, bad-hmac, or no-seal-key when the gate host cannot read the key; none of these has an escape). The key is the vault secret playablelabs-playthrough-seal (t1k vault get playablelabs-playthrough-seal; CI may inject it as PLAYTHROUGH_SEAL_KEY); it is never in a repo. Whoever publishes reports and the delivery host hold read access; a person with only the repo cannot forge a report the gate accepts. If the key is unreadable at --publish the tool prints a WARNING and writes an unsealed report. Rotation: t1k vault put the new value, then every game repo republishes its report (--publish, commit): an old report fails as bad-hmac with a rotated-key hint until then. Repos that do not opt in are unchanged.
Selftest: the harness must be able to fail
Section titled “Selftest: the harness must be able to fail”Run bun scripts/selftest.cjs (quick mode and the browser, coverage and inject-dud arms, with the CPU-load caveat): references/selftest.md. Exit 0 means every check passed; any RED exits non-zero and 3 means the environment is missing.
Hard rules
Section titled “Hard rules”PLAYTHROUGH_GL=gpuis opt-in and NOT valid for the delivery gate: it is lighter on the CPU, but two diff checks fail on GPU that pass on SwiftShader (cause not investigated), so--publishrefuses it. Use it for local iteration only; the sealed report comes from the default.- UNVERIFIED on a required state does not satisfy G4: fix the profile or input, never drop the state from
mustReach. - A GREEN report with
visual: unverifiedon every playing state is not a pass:frame: falseskips the capture, so declareregions/motionFrames/elements(or write thevisualWaiverreason) rather than silently skipping the states that matter. viewportsreplay the whole objective per viewport, so a wide profile multiplies the run’s wall clock: declare only the aspect ratios the game ships.- Add vocabulary for static discovery in
scripts/lib/vocab.json; a new game goes in a new profile, not inlib/. SDK lifecycle words (gameReady/gameStart/gameEnd) are weak: never a state without a profile naming the term. - A new detector
kindor output field is aCONTRACT.mdchange: bump the schema number for a breaking one.
Executed by
Section titled “Executed by”Running the playthrough and the selftest and parsing the report are mechanical; deciding whether a RED is a port defect, a
profile gap or a flake is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run playthrough.cjs / selftest.cjs, tabulate per-check PASS/RED and exit code | t1k-tester |
| Parse the report and trace, list failing checks per objective | t1k-data-verifier |
| Judge a RED: port defect vs profile gap vs flake, and what to fix | t1k-playablelabs-base-packer-engineer (sonnet, native) |