t1k:cocos:playable:pla-from-ref
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: complete playable ad, end to end playable, lane briefs, pla from ref, playable from concept, playable from ref, playable from reference, playable orchestrator, quick play link, reference to playable, run log, ship a playable, stage order, xây playable ad hoàn chỉnh
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:pla-from-ref<intake prompt | intake.md> [--resume <run-log.md>] [--from-stage <n>] [--dry-run]Playable from a Reference — the orchestrator
Section titled “Playable from a Reference — the orchestrator”One intake prompt becomes a shipped playable ad: a Quick Play URL a human has played. This skill owns the spine — intake, the run log, stage order, the G1–G8 gates, each lane’s owner, delivery.
First principle — observe the ref, never its text. A design from a store page’s prose is the
wrong game; one from frames of the running reference is the right one. Every design-pack rule traces
to an observation in REFERENCE.md; text alone means stop and capture the ref first (stage 2,
the costliest defect class in run history, lessons L1).
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Xây một playable ad hoàn chỉnh” / build one from a ref | Full workflow: steps 0→5 |
| Reference exists, design packed, lanes done — finish it | Resume at the stage named in the run log |
| “Just the intake fields” / prompt is thin | Intake contract + the AskUserQuestion grill |
| “A lane came back red / the build failed QA” | Stage order → the lane brief for that stage |
| “Ship the dry-run / verify the skillset” | Verification |
Intake contract
Section titled “Intake contract”Normalize the prose prompt into intake.md in the run directory before any lane starts; every field
below is required.
Xây một playable ad hoàn chỉnh từ đầu.Game: tham khảo <store URL | web game URL | video | local html/folder | Insightrackr> — OR — concept: <one paragraph>- Tên: <GameName>PLA — repo The1Studio/<GameName>PLA (private), checkout C:\The1Project\Cocos\<GameName>PLA- Phạm vi: <số level, cơ chế chính từng level, điều kiện thắng/thua, CTA>- Hình ảnh: placeholder được, lấy asset gốc để reskin sau| Field | Required | Notes |
|---|---|---|
| Game name + repo + checkout path | yes | deriveProjectName() must yield <GameName>PLA; the checkout lives beside the other PLAs |
| Source: Play or App Store URL, web game URL, itch.io URL, local HTML file/folder, Insightrackr creative, video, or a one-paragraph concept | yes | anything but a concept ⇒ observe the ref (stage 2, routed by source type); concept ⇒ say so, the design pack is authored not observed. A store or web URL is reachability-checked at intake (GET 200) |
| Scope: level count, the main mechanic per level, win/lose, CTA | yes | drives design-pack and the solver gate |
| Visuals: placeholders now, real assets later | yes | placeholders are the default, never a wait-for-art blocker |
| Orientation, target networks, playtest owner, Discord thread | ask | never guessed |
| Discord channel id for the project (+ its guild id, read back) | ask | AskUserQuestion; never guessed, defaulted or applied silently; lane-preflight-scaffold (references/lane-preflight-scaffold.md) Do.6 |
| Discord user IDs to tag (playtest owner / QA / requester) | ask | AskUserQuestion; never guessed or inferred from a display name; in service-bindings.json; lane-preflight-scaffold (references/lane-preflight-scaffold.md) Do.6 |
Any missing field → AskUserQuestion (≤4 per call), never a silent default. A bundled answer
settles every row it covers; re-read the answers before the next round. Do not begin stage 1 with an
unresolved intake row.
Run log — the run’s SSOT
Section titled “Run log — the run’s SSOT”Live at plans/<date>-<game>/run-<game>.md, created at stage 1, one row appended per stage, never
rewritten from memory; a later session resumes from it. Template and columns:
references/run-log-template.md.
| Stage | Start (UTC) | End (UTC) | Lane (agent) | SHA / artifact | Result | Notes / kit defect ||---|---|---|---|---|---|---|| 6 domain | 05:35Z | 06:40Z | t1k-cocos-base-package-developer | 7388236 | vitest 105/105 | K8 scaffold path |Two derived rows close the run: build count (Jenkins builds to first green) and wall time (branch cut → green QA, user waits separate) — measure, do not estimate.
Stage order
Section titled “Stage order”Stages 1–20. Every row names its owner; the lane brief holds the method. Run lanes 4–8 in parallel where the DAG allows (domain ∥ physics; assets ∥ scene), then 9, then 10.
| # | Stage | Owner | Gate |
|---|---|---|---|
| 1 | Intake → intake.md + run log created | inline | intake complete |
| 2 | Observe the ref → REFERENCE.md, contact sheet, observed vs UNOBSERVED. Route by source type through t1k-gamedev-playable-ref-capture: Play URL → lane-play-reference (references/lane-play-reference.md) (Insightrackr creative first, then gated APK + emulator capture); other store listing → t1k-cocos-playable-market-reference; web/itch.io → drive it; local HTML file/folder → staged, served, unpacked; Insightrackr creative → t1k-gamedev-playable-insightrackr; a web build’s bundle → t1k-gamedev-playable-extract. Ref asset extraction (ref/extract/, stage-10 slot input): lane-play-reference §8c. An HTML-bundle ref also measures polish → polish-inventory.json; then .claude/skills/t1k-gamedev-playable-ref-capture/scripts/check-ref-truth.cjs <run-dir> must exit 0 (G1b) | t1k-gamedev-playable-ref-capture | G1, G1b |
| 3 | Preflight: clones + bun install --frozen-lockfile, template pin, tooling checkouts (an estimate or system design up front → t1k-cocos-playable-preproduction); resolve pla-qa (PLA_QA_BIN, else pla-qa on PATH) and the ref-port tools dir (--ref-tools-dir / PLA_REF_TOOLS_DIR): either missing → STOP, never skip; store-URL source → emulator-capture tools are ENSURED, not STOPped (scripts/ensure-emulator-tools.cjs, tool list and misses: lane-preflight-scaffold (references/lane-preflight-scaffold.md) Do.1c) | lane-preflight-scaffold | — |
| 4 | Repo created from the PlayableAdsTemplate template repo → its SetupProject.bat run (generator = gate + authoring pack only) → Discord thread → Jenkins job (the job takes the thread id) → editor MCP registered | t1k-cocos-playable-gen, t1k-jenkins-job, t1k-git-manager, t1k-cocos-playable-pipeline, editor-tools | — |
| 5 | Design pack: concept-brief.md, levels.json/levels.md, solve.mjs exit 0, visual-brief.md, feedback-matrix.md (from polish-inventory.json), polish-map.json, asset-slots.md | t1k-gamedev-playable-design-pack | G2 |
| 6 | Engine-free domain core/ + .tests/ (vitest) | t1k-cocos-base-package-developer | G3 |
| 7 | Physics lane core/physics/ — optional, for a solver: lane-physics (references/lane-physics.md) | t1k-cocos-base-package-developer | G3 |
| 8 | Engine adapters engine/cocos/ + @playablelabs/cc-polish-kit wiring, including the @property refs it needs in prefabs (editor MCP) | t1k-cocos-playable-feel-developer | G3 |
| 9 | Scene wiring via editor MCP (save → reimport → disk read-back → editor-preview gate); then 9b early compare, below | t1k-cocos-base-developer (one lane with its code; t1k-cocos-base-editor-operator for a scene-only job or repair) | G4, G4b |
| 10 | Assets: slots filled from the ref’s own extracted assets first, placeholders only where no candidate exists, provenance recorded; the stage-2 extraction + inventory arrives on GLM per spawn (lane-play-reference (references/lane-play-reference.md) §8c) | t1k-cocos-playable-asset-producer | — |
| 11 | SFX: procedural reflect, loudness per fire-rate band, verify script (needs theonekit-designer audio installed; without it supply recorded audio), then AudioContainer registration | t1k-designer-audio-sfx-synth; registration by t1k-cocos-base-asset-import (its audio-container-registration reference) | G5 |
| 12 | window.__qa adapter + flow generator (win / lose / hint / idle) | t1k-gamedev-playable-qa-flows | — |
| 13 | Editor-preview gate: flows exit 0 on the live preview; liveness (G6al) and the trusted real-click CTA (G6ct); B5 G4c on the preview frame; pla-qa polish-parity on the flow’s events; remaining keyframes via pla-qa ref-compare | t1k-gamedev-playable-preview-verify + pla-qa | G6a, G6al, G6ct, G4c, G4b, G6c |
| 14 | Visual review vs the ref screenshots; the G4b and G6c reports are mandatory input (the verdict never replaces the numbers) | t1k-gamedev-playable-visual-director | G6b |
| 15 | Fix loop: QA finding → root cause → fix → re-verify the same flow | lane-fix | per finding |
| 16 | Jenkins build: t1k-jenkins-build, artifact GET 200, job branch reverted; no build until “Exit criteria for build #1” is green locally | t1k-devops-engineer / t1k-jenkins-build | G7a, G4c |
| 17 | Official QA gate on the built artifact: pla-qa <dist> … (full command and flags in lane-qa-gate (references/lane-qa-gate.md)); the verifier’s serve-dir flows still run; B5 G4c and B7 G6ct re-run on the build | pla-qa + t1k-gamedev-playable-runtime-verifier | G7b, G4c, G6ct, G4b, G6c |
| 18 | Quick Play link to the user + Discord thread post tagging the intake’s people (<@id>) | inline | — |
| 19 | Human playtest on the Quick Play build | human — AskUserQuestion | G8 |
| 20 | Merge feat/gameplay → <base>, revert the Jenkins job branch, kit-defect batch | t1k-git-manager | — |
Stage 5b: adopt from the capability index (gate GI, BEFORE stage 6): adopt-from-index.cjs, references/adopt-profile.json, --install --verdicts-out; command and exit codes: lane-domain (references/lane-domain.md) Adopt row.
Stage 9b: early compare (the 20 stages are not renumbered). After G4, capture the keyframes reachable before stage 12 (first-frame only; mid-gameplay, end-card and cta need the stage-12 flow) with preview-verify and run pla-qa ref-compare; the rest are compared at stage 13 and in the full stage-17 run. Commands, keyframe table, exit codes: references/lane-qa-gate.md.
A preview pass never substitutes for stage 16 (build) or 17 (QA-on-build): --url is the preview
gate, --serve-dir the build gate.
One artifact crosses the stage order backwards: concept-brief.md. Stage 5 produces it but
stage 4 consumes it (the generator hard-requires --brief), so author it early from the intake and
the observed ref; schema and validator: lane-preflight-scaffold (references/lane-preflight-scaffold.md) § Brief.
theonekit-core/.claude/skills/t1k-cook/references/workflow-gates.md is the contract — no bypass without a named override, evidence not
assertion, a failed gate goes to AskUserQuestion. A gate that cannot be
computed fails the stage: an unmeasured row, a null threshold, a missing input or exit 2 is
BLOCKED, never skipped, unless a named override is recorded.
| Gate | Passes when |
|---|---|
| G1 ref observed | REFERENCE.md carries frames/screens + a contact sheet and a per-element observed / UNOBSERVED table; a text-only design fails; plus polish-inventory.json beside it, or a stated reason the ref is unmeasurable (not an HTML bundle); plus the RENDER rows and the INPUT CAPABILITY MATRIX (each cell a measured probe, never an inference). The projection RENDER row fixes the port’s dimension: a 3D ref ported as flat 2D fails G4c without an override |
| G1b ref-truth | .claude/skills/t1k-gamedev-playable-ref-capture/scripts/check-ref-truth.cjs <run-dir> exits 0 before the first build stage: RENDER facts table present (each row MEASURED / ESTIMATED / UNKNOWN with a source; every MEASURED row names what IMPLEMENTS it, else BLOCKED) and ≥ 6 real in-game frames at phone resolution, each sourced; store screenshots do not count; exit 2 is never a pass; on 1 or 2 BLOCKED, ask for a ref source (lane-play-reference (references/lane-play-reference.md) § 8d) |
| G2 design pack | solve.mjs exit 0 (per-level min moves, winnability, QA win + lose lines), the ref-fidelity table cites an observation per rule, design-perspective review pass |
| GI adopt (stage 5b) | adopt-from-index.cjs exits 0 before stage 6; reuse.md has the verdict lines |
| G3 per code lane | tsc 0 errors, vitest green (report the count), cc-import gate exit 0 (never re-pin), source-scan-guard --changed clean |
| G4 scene | disk read-back: node count, every node layer UI_2D, 0 null @property, 0 frameless sprites, backplate index 0, preview boots |
| G5 SFX | verify script shows every clip inside its fire-rate loudness band, peak ≤ −1 dBFS |
| G4b early ref compare | pla-qa ref-compare (stage 9b, 13; full run at 17): per-region keyframe compare with the ref; report-only until pla-qa’s config says enforced; exit 2 is never a pass |
| G4c quantified pre-build parity | blocking before the first Jenkins build: scripts/visual-compare.cjs --capture <capture.json> exits 0 at 1080x1920: every RENDER-row region on geometry (centre ≤ 3 px, size ratio in band), top-face dRGB ≤ 8, hue class, silhouette IoU, shadow darkness/tint, glyph shape, plus the effect timeline; bands in references/g4c-parity.config.json; diffPercent is never a verdict; exit 2 (could not decide) is never a pass (references/g4c-parity.md) |
| G4d colour parity | blocking before the first Jenkins build, re-run on the stage-16 artifact: per region at 1080x1920, S̄ ±0.04, σ_L ±0.03, channel mean ±8/255 (references/visual-parity.md) |
| G4e runtime performance | blocking before the first Jenkins build, re-run on the stage-16 artifact: packed artifact vs the original, p50/p95, draw calls, alloc; a regression blocks unless a named owner override is recorded (references/runtime-performance.md) |
| G6 preview | flows exit 0, 0 console errors, 0 exceptions, win ends won and CTA fires after the end-card tap, lose ends lost; plus the visual review verdict vs the ref |
| G6al liveness | the liveness flow exits 0 on the editor preview and the built artifact: a cc.Tween advances over ≥ 2 frames and a fired PolishKit effect leaves its pool holding non-empty geometry |
| G6ct cta real click | the CTA flow exits 0: a trusted real-mouse click (through the engine’s input service / button, not a synthetic emit) on the end-card button produces exactly one CTA call, on the preview and the built artifact |
| G6c polish parity | pla-qa polish-parity (stage 13; full run at 17): every polish-inventory.json row maps to a measured event via polish-map.json; report-only like G4b; unmapped or unobserved rows are counted |
| G7 build | artifact HTTP 200, then the same flows exit 0 on the built artifact |
| G8 human playtest | the user has played the Quick Play build and answered via AskUserQuestion; no agent satisfies this |
Numbers before eyes. A finding from a numeric gate (G4b, G4c, G6c) is fixed to the number and re-measured, not argued by eye. G6b’s verdict cannot overrule a gate report. Three failed attempts at any gated step → stop and question the architecture.
Exit criteria for build #1
Section titled “Exit criteria for build #1”One Jenkins build per playtest round. No build until every row below is green locally, in this
order — the single home of the list; stage 13, stage 16 and the lane files cite it. G4c is
references/g4c-parity.md (scripts/visual-compare.cjs).
Shape gates, start-pose validity, shadow layer, provenance, build economy: references/shape-gates-and-pre-build.md.
| Build gate | Blocking evidence green locally before the build |
|---|---|
| B0 · G1b | .claude/skills/t1k-gamedev-playable-ref-capture/scripts/check-ref-truth.cjs <run-dir> exit 0: RENDER facts table complete, every MEASURED row naming what implements it, ≥ 6 sourced in-game frames at phone resolution |
| B1 · G1 | REFERENCE.md carries the RENDER rows and the INPUT CAPABILITY MATRIX (measured, not inferred) |
| B2 · G3 | tsc 0, vitest green, cc-import gate 0, source-scan-guard clean |
| B3 · G4 | scene read-back clean, preview boots |
| B4 · G6 | win / lose / idle flows exit 0, 0 exceptions, 0 console errors, the CTA fires after the end-card tap only |
| B5 · G4c | measured parity: geometry ≤ 3 px, per-colour top-face dRGB ≤ 8, timeline ≤ 1 capture step |
| B5b · G4d | colour parity per region |
| B5c · G4e | packed artifact vs the original, p50/p95 |
| B6 · G6al | liveness: a cc.Tween advances ≥ 2 frames; a fired effect leaves a non-empty pool |
| B7 · G6ct | a trusted real-mouse click on the end-card button → exactly one CTA, preview and build |
| B8 · G6b / G6c | visual review (advisory, depth / lighting / material / shape); polish-parity rows mapped |
Only then does stage 16 build; B5 and B7 re-run on the artifact and 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.
| Lane | Agent | Why this one |
|---|---|---|
Engine-free core (core/, .tests/, physics) | t1k-cocos-base-package-developer | owns pure packages; no cc, no editor |
| Engine adapters + PolishKit wiring + juice cues (stage 8) | t1k-cocos-playable-feel-developer | native opus; owns feel and the prefab @property refs PolishKit needs. Never hand-write confetti / vignette / CTA pulse |
| Other feature code + editor writes (one lane) | t1k-cocos-base-developer | holds the editor MCP grant with the code — never split a feature into a code lane and an editor lane |
| Scene-only / repair (no TS change) | t1k-cocos-base-editor-operator | editor writes with a disk read-back |
| Assets | t1k-cocos-playable-asset-producer | slots, placeholders, overwrite-in-place |
| Runtime verification | t1k-gamedev-playable-runtime-verifier | the read-only verifier role for preview and build |
| Visual parity vs ref | t1k-gamedev-playable-visual-director | design-perspective review, not a code review |
| Design pack | t1k-designer-base-game-designer | levels, rules, feedback matrix |
| Jenkins job + build | t1k-devops-engineer | job config, artifact fetch, branch revert |
| All git writes | t1k-git-manager | the only git actor in the run |
Read-only fan-out uses read-only agents; a verifier never runs on a write-capable
agent. Per-depth fan-out caps: theonekit-core/.claude/modules/t1k-base/rules/agent-security-boilerplate.md —
cite it; do not restate them.
Reuse, read-only
Section titled “Reuse, read-only”t1k-gamedev-playable-ref-tools (theonekit-gamedev) owns the measurement tools (ref-decode,
ref-gl-record, audio-hook.js, frame-compare, curve-compare); stage 2 reaches them only through its
lib/run-ref-tool.cjs wrapper, and pla-qa calls frame-compare and curve-compare through its own
ref-tools.cjs. Never edits ref-port — scripts/check-ref-port-frozen.cjs must exit 0. The
mechanical scripts/ runners are t1k-data-verifier’s; thresholds and waivers stay with the
orchestrator and the owner.
Executed by
Section titled “Executed by”Mechanical scripts/ runners: t1k-data-verifier; the per-script stage map and what each answers is script-inventory (references/script-inventory.md).
Routed-hop sizing
Section titled “Routed-hop sizing”When a lane runs as a routed hop, size its brief: one deliverable per brief (code + a scene is
two briefs); checkpoint-commit pathspec-only at each green step, so a killed hop still leaves work;
on ROUTED FAILED resume natively from the partial diff, never re-issue the brief; never edit
permission/security/allowlist settings to make a hop succeed; the orchestrator pushes (a hop cannot).
Verification
Section titled “Verification”Dry-run the skillset before trusting it on a new game: resolve the preflight, run solve.mjs on an
existing design pack, verify 2–3 generated SFX clips, and run one win flow against a built Quick Play
URL. Record the result in the run log; the target lives in the plan’s skillset doc.
Hard rules
Section titled “Hard rules”- A design written from prose is a wrong game. Check
REFERENCE.mdexists and is observed before authoring anything; a design pack without observations fails G1 (lessons L1). - Preview green ≠ build green. Tap coordinates that hold at 1080x1920 in the editor move under the release build’s canvas fit; the build gets its own QA run (lessons L5).
- Never claim a write you did not read back. Editor MCP
success:trueand reimport “OK” are both lies at times; the disk JSON is the truth. siblingIndexset through the MCP does not persist on create or move — reparent instead.- TS recompiles only while the editor window has focus — a stale preview chunk looks like a code bug and is not one.
- A hidden template node still eats input and can fire the CTA from a gameplay tap; strip or
re-hide template chrome, and check
ctaCalls == expected, notctaCalls > 0. - An invisible game passes logic-only QA. A board that never renders satisfies every state assertion; the board-visible probe is mandatory in every flow.
- The emulator is an adb-reachable instance, and a Play game is installed by the USER, never the
agent (never the user’s LDPlayer instance 0): script-inventory (
references/script-inventory.md) § Emulator and Play-install rules. - Extended gotchas (render-fact gate G1b, ref-port phases, Play link, parity, graded artifact, kit defects, project folder, run log): hard-rules-extended (
references/hard-rules-extended.md) — read before stage 2 and stage 16. <base>is read, never typed. The base branch is derived once at stage 4 and recorded in the run log; no lane hardcodesmasterormain(lane-preflight-scaffold (references/lane-preflight-scaffold.md) Do.4).- No
context: forkon this skill, despiteeffort: high: the orchestrator asks the user (intake fields, G8 playtest) and fans lanes out; forked, it would lose both.
Security & scope: this skill orchestrates Cocos playable delivery; it writes only inside its own
skill directory and the run’s plan directory. Lane methods belong to the skills it names. Lane
briefs live in references/.