Skip to content

t1k:cocos:playable:gen

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

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

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.

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

SourceFlag / locatorPreflight
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 entryls -d <dir>/node_modules/yaml — bun install --frozen-lockfile there too if absent
cocos-stdlibnever a --repo-style flag — located at runtime by Step 1’s and Step 2’s own 4-arm locatora 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.

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

Terminal window
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 RoundDirector in a file named RoundDirector.ts. --gameplay-from validates shape only.
  • gen --scaffold-only runs on the real PlayableAdsTemplate, never the vendored slice, with --mechanic-index-dir; never fall back to the golden-reference template, and never use --allow-template-gaps in 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-written ROUND_DURATION_S/endRound() pair. A refused call (null ticket, false, {accepted:false}) must never be ignored.
  • A round won by sustained tapping MUST declare where and how often (gameplay-plan.json’s input).
Terminal window
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):

  1. 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”: sibling Cocos*PLA projects 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).
  2. 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.
  3. Stage reached — scaffold / tsc / none, with wallClockS and tscFilesChecked. Also report generationMode ("agent" when --gameplay-from was used, "template" when the golden-reference emitter ran) and which model authored the composition — playable.json’s model_used[].role is "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.

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.

  • Two vendored snapshots lag the published packages, and they are not the same file. The pla-modules mechanic index (--mechanic-index-dir) gates reuse-level; pla-generator’s own vendor/cocos-stdlib-packages/packages.json gates materialization at Step 3 — an index-hit tag 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.cjs prints the names and packages/<name>/package.json on main prints the version and the peers. scripts/check-stdlib-claims.cjs exits 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 gen now 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 — read stageReached, never assume it. It may return before the CLI’s own tsc stage; pla-generator can close that gap without notice here.
  • Never merge pla-modules#1. feat/mechanic-index is read-only by contract — read it, pass a checkout via --mechanic-index-dir, do not merge it. Same for vendor/contracts/*: read-only mirrors, re-synced per their SOURCE.md.
  • A schema gap is reported, never patched. contracts/ changes only in the programme repo; the shipped: false rule and the outcome enum gap are already filed in docs/schema-fit-gaps.md — cite it, do not invent a fourth outcome value 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 call doc_list_assemblies here (~110K chars).
  • The RoundDirector naming 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 tsc stage 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 read stageReached: "tsc" as “the playable is done.”
  • A drag from that 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).
  • capability-index-lookup.md (references/capability-index-lookup.md) — the pre-sweep index lookup: locator order, the unavailable-is-fine vs. schema-mismatch-is-fatal split, and why it is a separate script from resolve-mechanic-tags.cjs.
  • plan-input.md (references/plan-input.md) — the gameplay-plan.json input contract: the space frames, 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 its reuse-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-generator CLI and the binding rules behind Step 3b: references/related.md.

Related: pla-generator#15, #38, #52