Skip to content

t1k:cocos:playable:pla-from-ref

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
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

/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).

IntentPath
“Xây một playable ad hoàn chỉnh” / build one from a refFull workflow: steps 0→5
Reference exists, design packed, lanes done — finish itResume at the stage named in the run log
“Just the intake fields” / prompt is thinIntake 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

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
FieldRequiredNotes
Game name + repo + checkout pathyesderiveProjectName() 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 conceptyesanything 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, CTAyesdrives design-pack and the solver gate
Visuals: placeholders now, real assets lateryesplaceholders are the default, never a wait-for-art blocker
Orientation, target networks, playtest owner, Discord threadasknever guessed
Discord channel id for the project (+ its guild id, read back)askAskUserQuestion; 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)askAskUserQuestion; 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.

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.

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.

#StageOwnerGate
1Intake → intake.md + run log createdinlineintake complete
2Observe 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-captureG1, G1b
3Preflight: 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—
4Repo 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 registeredt1k-cocos-playable-gen, t1k-jenkins-job, t1k-git-manager, t1k-cocos-playable-pipeline, editor-tools—
5Design 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.mdt1k-gamedev-playable-design-packG2
6Engine-free domain core/ + .tests/ (vitest)t1k-cocos-base-package-developerG3
7Physics lane core/physics/ — optional, for a solver: lane-physics (references/lane-physics.md)t1k-cocos-base-package-developerG3
8Engine adapters engine/cocos/ + @playablelabs/cc-polish-kit wiring, including the @property refs it needs in prefabs (editor MCP)t1k-cocos-playable-feel-developerG3
9Scene wiring via editor MCP (save → reimport → disk read-back → editor-preview gate); then 9b early compare, belowt1k-cocos-base-developer (one lane with its code; t1k-cocos-base-editor-operator for a scene-only job or repair)G4, G4b
10Assets: 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—
11SFX: procedural reflect, loudness per fire-rate band, verify script (needs theonekit-designer audio installed; without it supply recorded audio), then AudioContainer registrationt1k-designer-audio-sfx-synth; registration by t1k-cocos-base-asset-import (its audio-container-registration reference)G5
12window.__qa adapter + flow generator (win / lose / hint / idle)t1k-gamedev-playable-qa-flows—
13Editor-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-comparet1k-gamedev-playable-preview-verify + pla-qaG6a, G6al, G6ct, G4c, G4b, G6c
14Visual review vs the ref screenshots; the G4b and G6c reports are mandatory input (the verdict never replaces the numbers)t1k-gamedev-playable-visual-directorG6b
15Fix loop: QA finding → root cause → fix → re-verify the same flowlane-fixper finding
16Jenkins build: t1k-jenkins-build, artifact GET 200, job branch reverted; no build until “Exit criteria for build #1” is green locallyt1k-devops-engineer / t1k-jenkins-buildG7a, G4c
17Official 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 buildpla-qa + t1k-gamedev-playable-runtime-verifierG7b, G4c, G6ct, G4b, G6c
18Quick Play link to the user + Discord thread post tagging the intake’s people (<@id>)inline—
19Human playtest on the Quick Play buildhuman — AskUserQuestionG8
20Merge feat/gameplay → <base>, revert the Jenkins job branch, kit-defect batcht1k-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.

GatePasses when
G1 ref observedREFERENCE.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 packsolve.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 lanetsc 0 errors, vitest green (report the count), cc-import gate exit 0 (never re-pin), source-scan-guard --changed clean
G4 scenedisk read-back: node count, every node layer UI_2D, 0 null @property, 0 frameless sprites, backplate index 0, preview boots
G5 SFXverify script shows every clip inside its fire-rate loudness band, peak ≤ −1 dBFS
G4b early ref comparepla-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 parityblocking 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 parityblocking 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 performanceblocking 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 previewflows 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 livenessthe 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 clickthe 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 paritypla-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 buildartifact HTTP 200, then the same flows exit 0 on the built artifact
G8 human playtestthe 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.

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 gateBlocking 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 · G1REFERENCE.md carries the RENDER rows and the INPUT CAPABILITY MATRIX (measured, not inferred)
B2 · G3tsc 0, vitest green, cc-import gate 0, source-scan-guard clean
B3 · G4scene read-back clean, preview boots
B4 · G6win / lose / idle flows exit 0, 0 exceptions, 0 console errors, the CTA fires after the end-card tap only
B5 · G4cmeasured parity: geometry ≤ 3 px, per-colour top-face dRGB ≤ 8, timeline ≤ 1 capture step
B5b · G4dcolour parity per region
B5c · G4epacked artifact vs the original, p50/p95
B6 · G6alliveness: a cc.Tween advances ≥ 2 frames; a fired effect leaves a non-empty pool
B7 · G6cta trusted real-mouse click on the end-card button → exactly one CTA, preview and build
B8 · G6b / G6cvisual 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.

One agent per lane, the narrowest that owns it. Roles resolve through t1k-routing-*.json.

LaneAgentWhy this one
Engine-free core (core/, .tests/, physics)t1k-cocos-base-package-developerowns pure packages; no cc, no editor
Engine adapters + PolishKit wiring + juice cues (stage 8)t1k-cocos-playable-feel-developernative 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-developerholds 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-operatoreditor writes with a disk read-back
Assetst1k-cocos-playable-asset-producerslots, placeholders, overwrite-in-place
Runtime verificationt1k-gamedev-playable-runtime-verifierthe read-only verifier role for preview and build
Visual parity vs reft1k-gamedev-playable-visual-directordesign-perspective review, not a code review
Design packt1k-designer-base-game-designerlevels, rules, feedback matrix
Jenkins job + buildt1k-devops-engineerjob config, artifact fetch, branch revert
All git writest1k-git-managerthe 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.

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.

Mechanical scripts/ runners: t1k-data-verifier; the per-script stage map and what each answers is script-inventory (references/script-inventory.md).

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

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.

  • A design written from prose is a wrong game. Check REFERENCE.md exists 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:true and reimport “OK” are both lies at times; the disk JSON is the truth.
  • siblingIndex set 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, not ctaCalls > 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 hardcodes master or main (lane-preflight-scaffold (references/lane-preflight-scaffold.md) Do.4).
  • No context: fork on this skill, despite effort: 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/.