t1k:cocos:playable:gen
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: brief to playable, concept brief, corpus hits, gen playable, generate playable, generation log, mechanic tags, one command playable, pla-generator, playable gen, reuse plan, scaffold playable
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:gen<concept-brief.md> [--out <fresh-empty-dir>] [--model <id>] [--repo <pla-generator-checkout>] [--mechanic-index-dir <checkout>]Generate a Playable from a Brief — one command
Section titled “Generate a Playable from a Brief — one command”Drives the S2 generator CLI (The1Studio/pla-generator) from a concept-brief.md and closes
the two steps that CLI cannot do itself: the corpus sweep (Step 2) and, in the current generator, authoring the gameplay composition (Step 3b) — per
plans/reports/260923-1800-s2-direction-decision.md’s sequenced step 2, code generation is a
model’s job, run as this agent session, never the CLI’s. --corpus-hits is an agent-only input —
resolve-mechanics.mjs says so in its header, because mcp__knowledge-retrieval__doc_search is
reachable from an agent turn, not a plain Node process; --gameplay-from is agent-only for the
same reason, one level up — composing a mechanic from a brief needs judgment, not just corpus
access. This skill is the caller AND the gameplay author: prepare the CLI’s inputs, compose the
gameplay files, run it, report. The CLI’s own steps — scaffold, patches, syntax check, QA flow,
manifest, log — stay deterministic; never re-implement THOSE in prose.
Executed by
Section titled “Executed by”The index, tag and claim lookups (capability-lookup.cjs, resolve-mechanic-tags.cjs, check-stdlib-claims.cjs) are scripted: t1k-data-verifier runs them and reports the tables verbatim. Authoring the gameplay composition and driving the generator stay on t1k-cocos-base-developer (reasoning tier). Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md.
Scope — the stage ladder, and where it always stops here
Section titled “Scope — the stage ladder, and where it always stops here”scaffold = the directory copied from PlayableAdsTemplate · tsc = syntaxCheck() clean over the
scaffolded scripts · qa = only after a real dist/index.html exists.
There is no build stage on this host — no Cocos Creator, Jenkins credentials unconfigured
(programme repo plans/260922-generation-loop/README.md § Fixed facts). Every v0 run stops at tsc,
and GENERATION-LOG.md carries shipped: false — a known, reported gap in
generation-log.schema.json’s checkRuns (filed in docs/schema-fit-gaps.md), surfaced into the
run’s failures, never swallowed. Never say a build was produced, or that QA passed.
Step 0 — Locate the CLI (preflight)
Section titled “Step 0 — Locate the CLI (preflight)”Three checkouts feed this skill; each needs its OWN bun install --frozen-lockfile before the run, not diagnosed after
a raw stack trace mid-run — a fresh pla-modules clone with no bun install --frozen-lockfile throws
ERR_MODULE_NOT_FOUND 'yaml' from src/cli-resolve.mjs, the child process --mechanic-index-dir
spawns, exactly this way (hit on the ArrowBloxPLA dry run).
| Source | Flag / locator | Preflight |
|---|---|---|
pla-generator | --repo (default: programme repo submodule) | ls <repo>/src/cli.mjs <repo>/vendor/contracts; ls -d <repo>/node_modules/yaml |
pla-modules:feat/mechanic-index | --mechanic-index-dir / PLA_MECHANIC_INDEX_DIR — required for --scaffold-only (Step 3b), together with --corpus-hits: a brief tag with no package and either input missing makes gen refuse. A full gen run still accepts it absent → every tag unresolved plus a failures entry | ls -d <dir>/node_modules/yaml — bun install --frozen-lockfile there too if absent |
cocos-stdlib | never a --repo-style flag — located at runtime by Step 1’s and Step 2’s own 4-arm locator | a fresh clone up front is the fast, reliable arm (avoids gh api rate limits and 6h cache staleness) — taxonomy-lookup.md (references/taxonomy-lookup.md), capability-index-lookup.md (references/capability-index-lookup.md) |
bun -e "console.log(require('<repo>/package.json').engines.node)" — node >= 22.
A miss on any of the three is a stop, not a workaround — bun install there writes to someone
else’s repo; name the missing piece and the directory that needs it.
Step 1 — Validate the brief
Section titled “Step 1 — Validate the brief”The brief is Markdown with YAML front matter; S2 reads only the front matter — if you had to open
the prose to build, the brief is incomplete and fails S7’s DoD. Schema:
contracts/schemas/concept-brief.schema.json in the programme repo (the generator reads the read-only
mirror at <repo>/vendor/contracts/schemas/).
Do not pre-validate by hand — the CLI validates and throws, and that check is the real one. Confirm
only what a schema cannot: exactly one concepts[] with selected: true (the CLI rejects 0 or 2+),
and that each mechanic_tag phrases a sweep query (Step 2). Report game_slug, the selected
concept.id and its est_modules — fields, enums and per-gap failure text in
contracts-and-cli.md (references/contracts-and-cli.md).
Then resolve every tag against the vocabulary — never sweep an unresolved tag. Run
bun scripts/resolve-mechanic-tags.cjs --brief <brief.md> --json: 0 = every tag known (ok) or
renamed (mapped — sweep under the new names, report the deprecation); 1 = a tag is not in the
vocabulary — fix the brief or add it to cocos-stdlib’s docs/taxonomy.md first, and do not
sweep; 2 = the vocabulary could not be located, and the message names all four places it tried.
That file is the tag SSOT, located at runtime and never copied into this kit — the four arms
(--taxonomy → $COCOS_STDLIB_DIR → a sibling checkout found by walking up → a cached gh api
fetch), the provenance mapping and the exit codes: taxonomy-lookup.md (references/taxonomy-lookup.md).
Step 2 — The capability index, then the corpus sweep
Section titled “Step 2 — The capability index, then the corpus sweep”Check the capability index BEFORE sweeping. capability-index.json
(The1Studio/cocos-stdlib, Phase 3) is a per-tag catalogue of every shipped package — faster and
more precise than a corpus sweep for the tags it already knows. Run it once, batched over every
resolved tag from Step 1 (ok as-is, a mapped tag’s to[] targets):
bun scripts/capability-lookup.cjs <resolved-tag> [<resolved-tag>…] [--index <path>]Prints one line per tag: index-hit: <tag> → <pkg>[, <pkg>…] (consumers: N|unknown) or
index-miss: <tag>. An index-hit needs no sweep for that tag — report it directly as
REUSE (install the named package(s)). index-miss, and a tag with an empty package list, both
fall through to the corpus sweep below. The index is located at runtime and may legitimately not
exist yet (index: unavailable, exit 0) — that is NOT a failure, it means every tag falls through
to the sweep, same as if each had come back index-miss. Locator order, the exit-2 cases (a wrong
explicit --index, or a located index that fails meta.schema validation), and why this is a
separate script from resolve-mechanic-tags.cjs:
capability-index-lookup.md (references/capability-index-lookup.md).
Installing the index-hit packages is not this step’s job: t1k-cocos-playable-pla-from-ref stage 5b runs adopt-from-index.cjs (theonekit-gamedev, t1k-gamedev-playable-adopt-from-index) with --install before any domain code. Run it yourself when this skill is used without the orchestrator.
The corpus sweep runs only for index-miss tags and tags with an empty package list.
One entry per such tag, per rules/knowledge-sweep-cocos.md and
t1k-cocos-base-knowledge-sweep — cite them, do not re-derive their mechanics.
1-2. Query as a capability, not as the tag, and filter to Cocos assemblies via t1k-cocos-base-knowledge-sweep/assets/cocos-assemblies.json: references/corpus-sweep-steps.md.
2. Label every hit’s verdict — reuse | wrong-engine | false-positive | miss — with a note
saying why. This is the step’s whole value: resolve-mechanics.mjs calls a tag a reuse gap only
when every hit is not reuse, so an unlabelled wrong-engine hit silently claims coverage the studio
does not have. A Unity/.NET member is wrong-engine; a render-depth sort utility on a
sort-the-falling-object question is false-positive.
3. Write the file — shape, verdict table and examples: corpus-hits.md (references/corpus-hits.md).
Each tag maps to an ARRAY of { query, hits } rounds, never a bare object — the CLI calls
.every() on it (resolve-mechanics.mjs:60), so the object form throws
TypeError: row.corpusHits.every is not a function and the run dies before the scaffold. Keep it
outside --out (Step 3). A swept tag with nothing found gets "hits": [], never an omitted
key — absent and “swept, found nothing” are different facts and only one is a gap.
MCP unavailable? The sweep did not run: report discovery: mcp-unavailable, label the reuse plan
unverified, and name the unassessed tags. Never write a fabricated --corpus-hits.
Step 3b — Author the gameplay composition (the step this half of S2.4 exists for)
Section titled “Step 3b — Author the gameplay composition (the step this half of S2.4 exists for)”Compose the gameplay yourself before the CLI runs; the full procedure (four inputs, scaffold rules,
sustained-input declaration, idle hints, ownership and margin traps, the input block) is in
references/step-3b-gameplay-composition.md — read it before authoring. Non-negotiables kept here:
- HARD CONTRACT — the entry component MUST be a class named
RoundDirectorin a file namedRoundDirector.ts.--gameplay-fromvalidates shape only. gen --scaffold-onlyruns on the realPlayableAdsTemplate, never the vendored slice, with--mechanic-index-dir; never fall back to the golden-reference template, and never use--allow-template-gapsin an authoring run. The CLI throws on a bad input — fix it, never retry the same input.- Idle behaviour may only HINT; it must never change game state toward an outcome, never a win.
Auto-play that reaches an outcome in a headless run MUST NOT ship — QA sends real input via
qa-flow.json. - Use
RoundOutcome, never a hand-writtenROUND_DURATION_S/endRound()pair. A refused call (nullticket,false,{accepted:false}) must never be ignored. - A round won by sustained tapping MUST declare where and how often (
gameplay-plan.json’sinput).
Step 3 — Run the generator
Section titled “Step 3 — Run the generator”bun --prefix <repo> run gen -- --brief <brief.md> --out <out-dir> \ --model <model-id> --corpus-hits <hits.json> --gameplay-from <gameplay-dir> \ [--mechanic-index-dir <pla-modules-checkout>]The code-generation lane is a pinned choice, not a free one. --model defaults to
deepseek-flash; S2’s DoD requires at least two models (one premium, one cheap) on the same
framework — record the lane this run used (this is the model that authored Step 3b’s composition,
not a scaffolding detail). --out must be fresh and empty — the scaffolder refuses a non-empty
directory, so never point it at one already holding the Step-2 hits file or the Step-3b gameplay
directory. --gameplay-from <dir> is Step 3b’s output directory — its gameplay-plan.json and
listed files get copied into the scaffold and wired into GameView.ts’s boot the same way the
golden-reference emitter is; omitting it falls back to that golden-reference tap-to-shoot emitter,
which is now a regression fixture, not the product. --mechanic-index-dir <checkout> is the only
source that resolves a tag to a reuse level. Every flag, the result keys, and the
failure-string map: contracts-and-cli.md (references/contracts-and-cli.md).
Step 4 — Report the reuse plan, the gaps, and the stage
Section titled “Step 4 — Report the reuse plan, the gaps, and the stage”Read the CLI’s stdout JSON plus <out-dir>/GENERATION-LOG.md, and report these three, in order — fixed
shape in stage-report.md (references/stage-report.md):
- Reuse plan — per tag: resolved level · packages to install · a verdict line (
reuse-verdict: REUSE|EXTEND|NEW|CONTRIBUTE|KEEP|unverified — <symbol> — scope: <N> Cocos assemblies; NEW adds— reason: <game-specific part>). When a tag maps to a shipped@playablelabs/mechanic-*package the plan says “install package”, never “lift from project”: siblingCocos*PLAprojects are prior-art evidence, not installable code, and copying one re-creates the duplication those packages exist to remove — map and recipe in reuse-packages.md (references/reuse-packages.md). - Gaps —
reuseGaps[](nothing confirmed from either source);failures[]attributed to the layer that raised it (scaffold:/tsc:/playable.json (contract review):/GENERATION-LOG.md (contract review, known v0 gap…)); the MCP-absent note from Step 2; and, when this run used--gameplay-from, the invisible-mid-round gap from Step 3b — never omit it just because the syntax check passed. - Stage reached —
scaffold/tsc/none, withwallClockSandtscFilesChecked. Also reportgenerationMode("agent"when--gameplay-fromwas used,"template"when the golden-reference emitter ran) and which model authored the composition —playable.json’smodel_used[].roleis"codegen"for an agent-authored run,"scaffold"for the template path.
A run with failures is not a failed report. failures non-empty with stageReached: "tsc" is the
normal v0 outcome; both facts go in, neither replaces the other.
Step 5 — QA is a pointer, not a step
Section titled “Step 5 — QA is a pointer, not a step”Once a real build exists (dist/index.html, which needs Cocos Creator or Jenkins — not this host),
the next command is pla-qa <dist> (the pla-qa CLI, installed from the private CPM registry, S5): size, load, console, CTA, screenshots at
3 sizes, then the 8-network export. This skill does not run it. Before any Jenkins build, the editor
preview must pass t1k-gamedev-playable-preview-verify’s board-visible idle flow (t1k-cocos-base-developer §
“Editor writes”); kit defects met while building are queued, not fixed inline (§ “Kit defects”). If
asked for a build with no Cocos Creator/Jenkins on the host, name the gap — never substitute a scaffold.
Hard rules
Section titled “Hard rules”- Two vendored snapshots lag the published packages, and they are not the same file. The
pla-modulesmechanic index (--mechanic-index-dir) gates reuse-level;pla-generator’s ownvendor/cocos-stdlib-packages/packages.jsongates materialization at Step 3 — anindex-hittag can still be refused there with “removed, renamed, or needs a re-sync”, naming the Step-3 snapshot, never the capability index. Reconcile before reporting “no package” and date the snapshot — reuse-packages.md (references/reuse-packages.md) § “Three vendored snapshots gate this”. - A package name or version belongs in a lookup, never in this file’s prose. The index is the
catalogue;
capability-lookup.cjsprints the names andpackages/<name>/package.jsononmainprints the version and the peers.scripts/check-stdlib-claims.cjsexits 1 on a name, version or tag row that disagrees with the index (3 when it cannot find one) — run it after editing any markdown here; CI runs its suite against a LIVE cocos-stdlib read. - Search the small units too, not just the mechanic. Idle hint, difficulty ramp, delayed hit, merge board, cell hit test, round clock and once-only latch; the once-per-entity traps are in
reuse-packages.md (
references/reuse-packages.md) § “Reach for these”. - CPM still does not resolve peers, but
gennow auto-wires the closure for tag-resolved packages — a hand-added package still needs its peers added by hand: contracts-and-cli.md (references/contracts-and-cli.md) § “Reused packages vs wired packages”. --scaffold-only’s stage ceiling is not fixed — readstageReached, never assume it. It may return before the CLI’s owntscstage;pla-generatorcan close that gap without notice here.- Never merge
pla-modules#1.feat/mechanic-indexis read-only by contract — read it, pass a checkout via--mechanic-index-dir, do not merge it. Same forvendor/contracts/*: read-only mirrors, re-synced per theirSOURCE.md. - A schema gap is reported, never patched.
contracts/changes only in the programme repo; theshipped: falserule and theoutcomeenum gap are already filed in docs/schema-fit-gaps.md — cite it, do not invent a fourthoutcomevalue in code. - A tag with no hit is not greenfield. Carry the swept scope (
no hit across N Cocos assemblies, dated) —theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md; never calldoc_list_assemblieshere (~110K chars). - The
RoundDirectornaming contract is not enforced by--gameplay-from’s validation — it checks shape only, so a wrong class or file name passes it and the syntax check, then fails only at the Cocos build. Re-verify before Step 3 — contracts-and-cli.md (references/contracts-and-cli.md) § HARD CONTRACT. - A green
tscstage is not a visible playable. Composing correctly and passing the syntax check proves the mechanic logic parses, not that anything renders. The invisible-mid-round gap (Step 3b) survives a clean run; never readstageReached: "tsc"as “the playable is done.” - A drag
fromthat is not over the draggable node is a drag the mechanic never sees (Cocos routes a touch to the node it started on). Read the node’s editor position; the mechanism and dispatch order are in plan-input.md (references/plan-input.md).
Related
Section titled “Related”- capability-index-lookup.md (
references/capability-index-lookup.md) — the pre-sweep index lookup: locator order, theunavailable-is-fine vs. schema-mismatch-is-fatal split, and why it is a separate script fromresolve-mechanic-tags.cjs. - plan-input.md (
references/plan-input.md) — thegameplay-plan.jsoninput contract: thespaceframes, the y-up design origin, the refusal list, and worked tap/drag examples. - winnability.md (
references/winnability.md) — the margin a real player needs, and the pure-data hit-test rule. t1k-cocos-base-knowledge-sweep— the sweep Step 2 delegates to (scoping, allowlist, traps).rules/knowledge-sweep-cocos.md— the reuse loop and itsreuse-verdict:line.t1k-cocos-playable-pipeline— repo provisioning, Plane tracking, Jenkins job: everything downstream of a scaffold this skill does not do.- Programme repo, the
pla-generatorCLI and the binding rules behind Step 3b:references/related.md.
Related: pla-generator#15, #38, #52