t1k:playablelabs:ref:pla-engine-from-ref
| Field | Value |
|---|---|
| Module | ref |
| Version | 2.9.1 |
| Effort | high |
| Tools | — |
Keywords: complete playable ad, end to end playable, engine host web, lane briefs, pla engine from ref, pla from ref, playable engine, playable from concept, playable from ref, playable from reference, playable orchestrator, quick play link, reference to playable, run log, ship a playable, stage order, three.js playable, web engine playable, xây playable ad hoàn chỉnh
How to invoke
Section titled “How to invoke”/t1k:playablelabs:ref:pla-engine-from-ref<intake prompt | intake.md> [--resume <run-log.md>] [--from-stage <n>] [--dry-run]Playable from a Reference on the web engine: the orchestrator
Section titled “Playable from a Reference on the web engine: the orchestrator”The web / playable-engine twin of the Cocos orchestrator (pla-from-ref in the theonekit-cocos playable module): a layered three.js game packed by the PlayableLabs packer (--engine-host web), not Cocos. Same 20 stages and G-gates as the Cocos skill.
Derived from theonekit-cocos playable 3.75.1 (pla-from-ref). Provenance: provenance.skill.json.
One intake prompt becomes a shipped playable ad: a Quick Play URL a human has played. This skill owns the spine (intake, run log, stages, gates, who runs each lane, delivery); it owns no lane’s method; every stage cites its owner.
First principle: observe the ref, never its text. Every design rule traces to an observation in REFERENCE.md (stage 2).
Install the extract dependency and run the ref module tests first (commands and the --all probes in references/setup.md).
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| Build a web playable from a ref or a concept | Full workflow: intake, then stages 1 to 20 |
| Reference exists, design packed, lanes done | Resume at the stage named in the run log |
| Thin prompt, missing fields | Intake contract and the AskUserQuestion grill |
| A lane came back red / the pack or QA failed | Stage order, then the lane brief of that stage |
| Source is a Cocos project (mode P) | Entry mode P |
| A store URL batch or a publisher page (many games) | t1k-playablelabs-ref-pla-from-store (prefills intake.md per game, calls this skill) |
Intake contract
Section titled “Intake contract”Normalize the prompt into intake.md in the run directory before any lane starts; every required field is asked when missing.
| Field | Required | Notes |
|---|---|---|
| Entry mode | yes | G greenfield (any source below) or P port (a Cocos project path or repo holding assets/**/*.scene) |
Game name, client name, repo The1Studio/<Project>PLA, local clone path | yes | deliver.cjs needs --client and --project; the clone path is asked, never derived |
| Source: Play or App Store URL, web game URL, itch.io URL, local HTML file or folder, Insightrackr creative, video, or concept | yes | observe the ref (stage 2); a concept is stated as such, its design pack authored |
| Scope: level count, main mechanic per level, win/lose, CTA | yes | drives the design pack and the solver gate |
| Visuals: reuse the ref’s extracted assets first, placeholders only for a slot with no counterpart | yes | assetPolicy default reuse-ref; extraction source order in lane-play-reference (references/lane-play-reference.md) 8b; never a wait-for-art blocker |
| Orientation, target networks, size budget in KB (default 5120), playtest owner | ask | never guessed |
| Discord channel id for the project (and its guild id, read back) | ask | AskUserQuestion, never guessed or defaulted; an earlier channel may be ONE option, never applied silently |
| Discord user IDs to tag (playtest owner, QA, requester) | ask | AskUserQuestion, never guessed or inferred from a display name; kept in service-bindings.json (local) |
Four OPTIONAL rows a batch driver sets; never asked, absent means today’s behaviour exactly:
| Field | Required | Notes |
|---|---|---|
stop-after: <stage id> | no | stop after that stage (e.g. 18): write its run-log row, report. Absent: run to 20 |
on-gate-fail: block|ask | no | default ask (AskUserQuestion). block: log the stage and gate, report blocked, return without a question |
spec-dir: <absolute path> | no | a finished spec child output replacing the 8b fetch (lane-play-reference (references/lane-play-reference.md) “8b-spec”); needs the authorized=yes Decision row |
run-log: <absolute path> | no | the ONE run log, made by the batch driver: create or extend it AT that path. Absent: today’s path. Gate 1 reads its Decision row from it |
Any missing field means AskUserQuestion (at most 4 per call), never a silent default. Re-read a bundled answer before the next round. Do not begin stage 1 with an unresolved intake row.
Entry mode P (port)
Section titled “Entry mode P (port)”Mode P changes only stages flagged modeP in references/stage-map.json (deltas: lane-port-mode.md). First read references/port-tools.json and its status. If status != promoted, STOP with exactly this sentence and write no file:
mode P needs the promoted port tools (phase 8B approval pending); see lane-port-mode.md
When a tool the run needs is unpromoted, the stop text is the stopMessage in port-tools.json, verbatim, with {tool} replaced by the registry name:
STOP: mode P needs the port tool {tool}, which is unpromoted (it lives only in a local staging dir, not in any repo). Promoting it is BLOCKED pending user approval (phase 8B). There is no fallback: do not hand-roll it, do not skip it, do not ship a degraded port.
Never a silent fallback to mode G: a port the tools cannot do is a named stop.
Run log: the run’s SSOT
Section titled “Run log: the run’s SSOT”plans/<date>-<game>/run-<game>.md, created at stage 1, one row per stage, never rewritten from memory; first line is the as-of marker. A run-log: row in intake.md names the log, at that path: extended, never recreated, its Decision: rows carried to Decisions. Columns and the two derived rows (build count, wall time): run-log-template (references/run-log-template.md).
Stage clock (mandatory, cost telemetry). Around EVERY stage and sub-step (5b, 9b) run bun scripts/stage-clock.cjs start <game> <stage> --run-dir <run dir> before its lane starts and bun scripts/stage-clock.cjs end <game> <stage> --run-dir <run dir> --game-dir <game clone> --status pass|fail [--gate ID=pass] once its gate verdict is known; a re-run is a second start (ab-protocol (references/ab-protocol.md)).
Stage order
Section titled “Stage order”Every row names its owner; the lane brief holds the method. The table renders references/stage-map.json (a test fails on any id, owner, gate or copy-item difference). Run 6 with 7, and 9 with 10, where the DAG allows.
| # | Stage | Owner | Gate | Copy |
|---|---|---|---|---|
| 1 | Intake, entry mode, run log created | inline | — | K11 |
| 2 | Observe the ref: REFERENCE.md, contact sheet, polish-inventory.json (rows measured or UNOBSERVED, polish-pass (references/polish-pass.md)). Route by source type via t1k-gamedev-playable-ref-capture (its decision tree is the SSOT): Play URL to lane-play-reference (references/lane-play-reference.md); store listing t1k-playablelabs-ref-market-reference; Insightrackr t1k-gamedev-playable-insightrackr; competitor bundle t1k-gamedev-playable-extract. Extract the ref’s assets for reuse (8c: the routable t1k-playablelabs-ref-extractor lane; 8d: emulator capture for a store-URL source; both in lane-play-reference (references/lane-play-reference.md)) | inline | G1, G1b | K2, K11, K14 |
| 3 | Preflight: Bun 1.4.3, clones, bun install --frozen-lockfile, a built PlaybleEngine checkout, Chrome, pla-qa (PLA_QA_BIN, else on PATH from bun add -g @playablelabs/pla-qa), PLA_REF_TOOLS_DIR to t1k-gamedev-playable-ref-tools/scripts; a store-URL source runs the ensure step scripts/ensure-emulator-tools.cjs, never a bare STOP: exit 1 asks the user, exit 2 is BLOCKED, never a silent fallback to store screenshots; other misses are STOP (lane-preflight-scaffold (references/lane-preflight-scaffold.md)) | inline | — | K10, K11 |
| 4 | Scaffold: provision repo (deliver.cjs provision-web-repo), Discord thread, overwrite with the layered web template (scripts/scaffold-web-game.cjs) | inline | — | K16 |
| 5 | Design pack: concept brief, levels, solve.mjs, visual brief, feedback matrix, polish-map.json, asset slots (t1k-gamedev-playable-design-pack) | t1k-designer-base-game-designer | G2 | — |
| 6 | Engine-free domain src/domain/<Game> and vitest (lane-domain (references/lane-domain.md)) | implementer | GR, G3w, GA, GS | K11, K15 |
| 7 | Physics, optional, engine-free solver (same lane file) | implementer | G3w | K11 |
| 8 | Engine adapters src/engine, views src/game/<feature>/view, polish ports (lane-engine-adapters (references/lane-engine-adapters.md)) | implementer | G3w, GA, GS | K11, K15, K16 |
| 9 | Scene as data: scene.json, manifest.json, view builders; early first-frame compare (lane-scene-data (references/lane-scene-data.md)) | implementer | G4w, G4b | K11 |
| 10 | Assets: each slot filled from the ref’s extraction first (assetPolicy reuse-ref), placeholders only for a slot with no counterpart, overwrite in place; the slot input is the stage-2 ref/extract/ inventory (lane-assets (references/lane-assets.md)) | t1k-art-base-2d-artist | GN | K11 |
| 11 | SFX: procedural, loudness band (t1k-designer-audio-sfx-synth; needs theonekit-designer audio, install it or supply recorded audio) | t1k-designer-audio-composer | G5 | — |
| 12 | window.__qa adapter (web template in t1k-playablelabs-ref-gamedev-adapter) and flows (t1k-gamedev-playable-qa-flows) | implementer | — | — |
| 13 | Preview gate on vite preview of dist: flows, liveness, real-click CTA, pre-build parity, polish parity, polish pass, motion strips, ref-compare (t1k-gamedev-playable-preview-verify, pla-qa) | t1k-gamedev-playable-runtime-verifier | G6aw, G4c, G6al, G6ct, G4b, G6c, G6d | — |
| 13b | Local pack and smoke with --engine-host web | t1k-playablelabs-base-packer-engineer | GD, GP, GB | — |
| 14 | Visual review against the ref; G4b, G6c, G6d reports and motion strips are mandatory input; stills alone cannot pass an animation row | t1k-gamedev-playable-visual-director | G6b | — |
| 15 | Fix loop (lane-fix (references/lane-fix.md)) | inline | — | K11 |
| 16 | Jenkins build via deliver.cjs trigger-params (lane-build-deliver (references/lane-build-deliver.md)); no build until the Exit-criteria table below is green locally | inline | G4c, G6ct, G7a, GP, GB, GN | K10 |
| 17 | pla-qa on the built artifact plus serve-dir flows (lane-qa-gate (references/lane-qa-gate.md)) | t1k-gamedev-playable-runtime-verifier | G7b, G4b, G6c, G6d | — |
| 18 | Quick Play link to the user and the Discord thread, tagging the intake’s <@id> people | inline | — | — |
| 19 | Human playtest on the Quick Play build, via AskUserQuestion | inline | G8 | — |
| 20 | Merge the feature branch to <base> (read, never typed) | t1k-git-manager | GZ | — |
Stage 13b is the pack/smoke step. Stage 16 is a build lane and stage 17 a QA-on-build lane: a preview pass substitutes for neither; --url is the preview gate, --serve-dir the build (references/stage-notes.md).
One artifact crosses the order backwards: concept-brief.md. Produced with the stage-5 design pack, consumed by stage 4; author it early (it needs only the intake and the observed ref).
Gate contract: a gate passes only on evidence, not assertion; a failed gate stops the run into AskUserQuestion (on-gate-fail: block records it instead); thresholds live in pla-qa config and the scripts; a gate that cannot be computed (exit 2) is BLOCKED, never skipped (references/gate-contract.md).
The typecheck gate (G3w, B2) is TSRS (bun run typecheck; exit 2 means type errors, not a blocked gate). Details: references/typecheck-tsrs.md.
| Gate | Passes when |
|---|---|
| G1 | REFERENCE.md has frames, a contact sheet and a per-element observed/UNOBSERVED table, plus polish-inventory.json or a stated reason it is unmeasurable; text-only fails. A 3D ref ported flat fails G4c (lane-engine-adapters (references/lane-engine-adapters.md)) |
| G4c | quantified pre-build parity, blocking before the first Jenkins build: at 1080x1920 a measured table (ref frame vs ours) shows geometry within 3 px, per-colour top-face dRGB <= 8, the timeline within one capture step; only the per-region rows are read, never diffPercent alone |
| G2 | solve.mjs exit 0, the ref-fidelity table cites an observation per rule, design review pass |
| G3w | bun run typecheck 0 errors, bun test green with the count reported, GA green, GS green |
| GR | 5b adopt-from-index (--install, scripted) then reuse sweep (lane-domain (references/lane-domain.md)) |
| G4w | check-web-seam.cjs --scene clean (C4 shape, node count printed, every asset id in manifest.json, every out exists), headless boot exit 0 |
| G4b | pla-qa ref-compare (stage 9, 13; full run at 17), then scripts/check-fidelity-gates.cjs: blocking here whatever pla-qa’s enforced; a null tolerance, not-run/error or zero pairs is blocked (exit 2) |
| G1b | t1k-gamedev-playable-ref-capture/scripts/check-ref-truth.cjs <run-dir> exit 0: a RENDER facts table, every row MEASURED/ESTIMATED/UNKNOWN with a source, every MEASURED row naming what implements it, and >= 6 sourced real in-game frames at phone resolution (listing screenshots do not count); exit 1/2 is BLOCKED, and a listing-only fallback is a named owner override |
| G5 | every SFX clip inside its fire-rate loudness band, peak at or below -1 dBFS |
| G6aw | flows exit 0 on vite preview of dist, 0 console errors, 0 exceptions, win ends won and the CTA fires once after the end-card tap, lose ends lost; ctaCalls == expected, never > 0 |
| G6al | liveness.flow.json exit 0 on dist and the packed artifact: a tween advances over >= 2 frames, a fired effect leaves its pool holding non-empty geometry |
| G6ct | cta-real-click.web.flow.json (dev) and cta-real-click.packed.flow.json (packed) exit 0: a trusted CDP mouse click on the end-card button produces exactly one CTA call |
| G6b | the visual verdict; starts only once check-fidelity-gates.cjs passes the render-model rows, per-colour RGB table and input matrix; never overrules a numeric gate |
| G6c | pla-qa polish-parity: every inventory row maps to a measured event via polish-map.json; blocking like G4b; no polish-inventory.json is a named UNOBSERVED block, not a silent exit 2 |
| G6d | check-polish-pass.cjs (polish-pass (references/polish-pass.md)): every measured ref row names symbol + test, blocking; UNOBSERVED report-only; a placeholder at stage 13 blocks the stage 17/18 fidelity claim |
| G7a | the Jenkins artifact answers GET 200 and the verdict is read from the console log, not the colour |
| G7b | pla-qa <dist> with ref args and --win-signal references/win-signal.web.json, plus serve-dir flows win/lose/idle on the packed artifact |
| G8 | the user played the Quick Play build and answered via AskUserQuestion; no agent can satisfy it |
| GA | import layers: domain imports no three, nothing outside src/domain; three only in src/engine and src/game/*/view; ruled by references/layer-rules.json via scripts/check-web-seam.cjs |
| GS | platform seam: super_html, __PLA_* and ad-network SDKs only under src/platform and main.ts; CTA only through src/platform/cta.ts |
| GD | dist shape: index.html at the root, ONE classic top-level game.js, no forbidden files (check-web-seam.cjs --dist) |
| GP | packed artifacts boot with the host they were packed with: pack exit 0, smoke exit 0 for at least applovin and google; exit 2 is blocked, not a pass |
| GB | every packed network row is status: pass against the declared budget; a row over budget goes to t1k-playablelabs-optimize-gate, not before |
| GN | scripts/check-no-ref-assets.cjs exit 0 before stage 16 in reuse mode (assetPolicy reuse-ref): byte-identical ref files are the intended reuse, listed in PROVENANCE.md (“Assets reused from the reference”); --strict (placeholder-only) restores exit 1 on any shared file; exit 2 is never a pass |
| GZ | zero change: this skill never edits the packer or a Cocos path; in mode P the source project is read-only |
Numbers before eyes: a numeric-gate finding (G4b, G6c) is fixed to the number and re-measured; three failed attempts at one gated step means stop and question the architecture; a gate that scanned nothing is exit 2 (references/gate-numbers.md).
Exit criteria for build #1
Section titled “Exit criteria for build #1”One Jenkins build per playtest round. No build until every gate in the build table passes locally, in this order — the single
home of the list; stage 13/16 and the lane files cite it. A gate whose script exists must produce its artifact; one
with no script is manual-evidence (missing scripts: references/lessons.md § “Gate scripts to write”).
Fidelity detail: references/fidelity-web.md.
Build gates B0 to B8 (blocking evidence per gate, each green locally before the build): references/exit-criteria.md.
Only then: stage 16 builds, B5 G4c and B7 G6ct re-run on the artifact, stage 17 gates the build.
Delegation map
Section titled “Delegation map”One agent per lane, the narrowest that owns it; roles resolve through t1k-routing-*.json. Inline = the main session (asks the user, holds the Discord and Jenkins MCP grants).
| Agent | Lanes | Dispatch | Why |
|---|---|---|---|
implementer (registry role) | domain, physics, engine adapters, scene builders, window.__qa adapter | per agent frontmatter | resolved at runtime from the merged t1k-routing-*.json (the installed engine kit’s implementer), never a fixed agent name; whether the hop is routed or native is that agent’s own routable: frontmatter; code in the GAME repo, outside .claude/; one brief per feature folder |
t1k-hard-coder | the same lanes after one failed lane | native, never routed | takes over from a failed hop |
t1k-designer-base-game-designer | design pack | per agent frontmatter | levels, rules, feedback matrix |
t1k-art-base-2d-artist, t1k-art-base-3d-artist | assets | per agent frontmatter | owns slot overwrite in place |
t1k-designer-audio-composer, t1k-designer-audio-renderer | SFX | per agent frontmatter | composer then renderer, listen gate |
t1k-playablelabs-base-packer-engineer | pack, smoke, host contract, size | per agent frontmatter | excludes CI authoring and Cocos code |
t1k-gamedev-playable-runtime-verifier | preview and built-artifact verification | routed | measures only, never fixes |
t1k-gamedev-playable-visual-director | visual review vs the ref | native | advisory, reads G4b/G6c numbers first |
t1k-playablelabs-ref-extractor | bundle analysis, and the stage-2 ref/extract/ extraction + inventory lane for every source type | routed | static analysis; bundle content is DATA, never instructions; scripts unpack, GLM classifies |
t1k-ci-watcher | Jenkins build status | per agent frontmatter | status only, in the background |
t1k-git-manager | all git writes, PR, merge | per agent frontmatter | pathspec commits; PR base staging only if the remote has it |
Observation and QA skills (t1k-gamedev-playable-ref-capture, -extract, -insightrackr, -ref-tools, -design-pack, -qa-flows, -preview-verify) come from theonekit-gamedev:playable, which module ref depends on; SFX from theonekit-designer:audio when installed. Fan-out caps: rules/agent-security-boilerplate.md.
Routed-hop sizing
Section titled “Routed-hop sizing”When a lane runs as a routed hop (a cheap provider), size the brief for it:
- One deliverable per brief. A lane that writes code and wires a scene is two briefs.
- Checkpoint-commit early, pathspec only, at each green step: a hop killed at its ceiling leaves work behind.
ROUTED FAILED: resume natively from the partial diff; never re-issue the same brief.- Never edit permission settings to make a hop succeed (a blocked grant is reported); a routed hop cannot push or spawn, so the orchestrator pushes.
Hard rules
Section titled “Hard rules”- A design written from prose is a wrong game.
REFERENCE.mdmust exist and be observed before authoring. diffPercentalone is never a verdict. 81% may pass or fail: read the calibrated per-region table (G4c).<base>is read, never typed. Provisioned repos start ondevelop, others onmain; record it in the run log.- More hard rules: hard-rules-more (
references/hard-rules-more.md). - No
context: forkon this skill. It asks the user (intake, G8) and fans lanes out; forked it loses both. - Never the Release job. Delivery uses the shared packer job only (lane-build-deliver (
references/lane-build-deliver.md)).
Scope: writes only inside its skill directory and the run’s plan directory. Lane briefs: references/.
Porting an existing game (mode P): read port-fidelity-checklist (references/port-fidelity-checklist.md) at stage 2
and pin its §1 asset inventory into the run log before any port code.
Executed by
Section titled “Executed by”Every file under scripts/ is mechanical and run by t1k-data-verifier; stage decisions, intake and gate verdicts stay with the orchestrating session (references/executed-by.md).