Skip to content

t1k:playablelabs:base:playthrough

FieldValue
Modulebase
Version2.29.2
Efforthigh
Tools—

Keywords: end card cta reachable, flow parity, full-flow playthrough, playable playthrough, playthrough test, port plays like the reference

/t1k:playablelabs:base:playthrough
run --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).

checkred when
ref-objectiveUNVERIFIED (not red): the reference could not be driven to the objective, so nothing below is evidence
state-sequencethe 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-singlestore 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-timingthe 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)
shortcuta shortcut threw or never ran (port: fail, reference: unverified)
dead-inputan 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
stucka state held past its watchdog
visualper-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
shadethe 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
motiona 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
audioaudio played in a state on the reference and not on the port (warn; fail when the profile says so)
errors, detectorsnew page errors on the port; a state detector threw (a throw is never read as false)
coverageUNVERIFIED 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
colourRED 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.

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.

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 only
bun scripts/playthrough.cjs explore --url <url|html|dir> # no profile: discover states + live inputs
bun scripts/playthrough.cjs record|replay ... # one side only
bun 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 see
bun 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 run
bun 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 browser
bun scripts/playthrough.cjs run ... --ref-trace-dir <dir of trace.<obj>.ref.json> [--flow f.json] # play only the port
bun 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.

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.

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.

  • 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. --natural ends such an objective UNVERIFIED when the reference cannot get there.
  • A state shorter than the screenshot latency gets no frame: visual is then UNVERIFIED, never pass. frame: false / visual: false skip the capture on purpose (a fast loop); the state still needs a written visualWaiver reason or the run cannot be GREEN.
  • dead-input uses the profile’s effectSignals; 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.
  • visual is 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 per regions), motion (per-state motion energy), element:<id> (canvas draw-call shape) and viewports close 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: run probe on the real game first.
  • Audio capture sees AudioBufferSourceNode.start and HTMLMediaElement.play only.
  • 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 (timeScale is per side, not per objective); explore finds nothing on a non-DOM reference (use extract with a profile and playcanvasEntity / pixiNode / three / cocosNode detectors).
  • 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.

  • PLAYTHROUGH_GL=gpu is 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 --publish refuses 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: unverified on every playing state is not a pass: frame: false skips the capture, so declare regions / motionFrames / elements (or write the visualWaiver reason) rather than silently skipping the states that matter.
  • viewports replay 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 in lib/. SDK lifecycle words (gameReady/gameStart/gameEnd) are weak: never a state without a profile naming the term.
  • A new detector kind or output field is a CONTRACT.md change: bump the schema number for a breaking one.

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”.

StepAgent
Run playthrough.cjs / selftest.cjs, tabulate per-check PASS/RED and exit codet1k-tester
Parse the report and trace, list failing checks per objectivet1k-data-verifier
Judge a RED: port defect vs profile gap vs flake, and what to fixt1k-playablelabs-base-packer-engineer (sonnet, native)