t1k:cocos:playable:ready-figma
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: author prefab nodes, cocos playable install package, playable ready figma, ready template figma match, runtime node pooling, ui-loading-endcard
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:ready-figma[<game-project-path>]Cocos Playable Ready — install ui-loading-endcard, author the hierarchy, match Figma
Section titled “Cocos Playable Ready — install ui-loading-endcard, author the hierarchy, match Figma”Applies changes directly on the target game. No report-only default. Every step below writes
to the game’s own repo and ends in a commit. Scoped to games built from the @playablelabs/ template-ready base template (the “Ready” family) — this is NOT the general parameter-dashboard
migration workflow, and NOT the general Figma-to-UI reconstruction skill:
| Skill | Covers |
|---|---|
t1k-cocos-base-figma-to-ui | Build NEW UI screens from a Figma file from scratch, via the Figma REST API + Cocos MCP |
t1k-cocos-playable-parameter | This kit’s flat-primitive @playablelabs/parameter-tool dashboard system |
| this skill | Install a specific package into an EXISTING “Ready”-family game, author its runtime nodes into the prefab, and pixel-match EXISTING elements to an already-designed Figma section |
Known hard prerequisite (not shipped by this kit today): step 2 depends on the game already
being migrated to a shared end-card config layer shaped like @playablelabs/playable-params
(createSharedConfig + BaseParameterController + SharedConfigRegistry — see “Hidden
cross-dependency” in references/uipack-wiring-map.md). That
migration is not the same system as this kit’s t1k-cocos-playable-parameter /
@playablelabs/parameter-tool orchestrator above — it is a separate, newer package family used by
the “Ready” template line, and the skill that performs that migration is not yet part of this kit.
Until it is contributed, either perform that migration by hand against the shape documented in
uipack-wiring-map.md, or stop before step 2 if the game isn’t on that layer yet.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| Install the package + wire GameView only | Steps 0–2, stop before step 3 |
Move runtime new Node/destroy() into the prefab | Steps 0, 3 |
| Match the game to its Figma design | Steps 0, 4 |
| Full pass (what the user usually wants) | All of steps 0–5, in order |
Step 0 — Preflight (HARD GATE, every failure stops the run)
Section titled “Step 0 — Preflight (HARD GATE, every failure stops the run)”- Identify the project root (the folder with
package.json+creator:field) and the game’s Figma SECTION name. Ask the user, or read it from the project’s own shared docs if the project keeps one Figma file with a section per game (studios commonly document this mapping in a monorepo-rootCLAUDE.mdor a design-tracking doc) — this skill does not hardcode any studio’s Figma file key or game roster. $FIGMA_TOKENpresent in the environment — needed for step 4 even if this run stops earlier.- Cocos Creator CLOSED on this project — hard gate, no override. A single running Editor
spawns roughly a dozen
CocosCreator.exeHELPER processes (crashpad-handler, gpu-process, network utility, several renderers, audio utility) alongside the one main-Editor process — only that ONE process carries--project <path>in its command line; the helpers carry no project argument at all. A bare process-name match therefore reads as “an editor is open” for EVERY project on the machine, not just this one, and fails the gate even when the target project is closed (measured onCaseOpeningPLA2026-09-22: 13CocosCreator.exematches, the sole--projectargument pointed at a different project’s path, and an unfiltered run of this gate nearly caused an unrelated project’s editor to be closed). Filter to the target project’s command line (Windows):ReplaceTerminal window powershell -NoProfile -Command "$p = Get-CimInstance Win32_Process -Filter \"Name='CocosCreator.exe'\" -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -like '*<project-dir-name>*' }; if ($null -eq $p) { 'GATE PASS' } else { 'GATE FAIL'; $p | Select-Object ProcessId, CommandLine | Format-List }"<project-dir-name>with the target project’s folder name (the root identified in item 1). A helper-process row with no--projectargument is not evidence the gate should fail — only aGATE FAILrow naming the target project’s own path is. On macOS/Linux, check for a runningCocosCreatorprocess for the target project path instead. Re-check immediately before every disk write in steps 2/3/4 — the process lingers a few seconds while closing and a stale “closed” read is not evidence: an open Editor can silently revert a prefab/scene edit on its next save, or even on an unrelated asset import triggering a background resave — see the Gotchas section below, andt1k-cocos-base-editor-mcp-truthfor the general write/read-back protocol this same failure mode motivates. git status— clean enough to diff (uncommitted unrelated changes make the eventual commit unreadable; ask before proceeding over a dirty tree that isn’t this skill’s own prior work).- Commit the clean starting point before any edit (even an empty “start: ready-figma pass” is
fine if nothing to commit — skip only if
git statusis already clean at HEAD).
Step 1 — Install @playablelabs/ui-loading-endcard
Section titled “Step 1 — Install @playablelabs/ui-loading-endcard”Headless path (no Editor needed), manual copy — never playableSync — peer-dep version check
(template-ready >=1.0.2, game-foundation >=1.1.4, motion >=0.1.3):
references/package-install.md.
Step 2 — Wire the package into GameView
Section titled “Step 2 — Wire the package into GameView”Read the package’s own scripts AND the game’s GameView.ts (or equivalent flow controller).
Build a concrete call-site → API mapping. Fully covered → retype fields/imports onto the
package’s classes. Missing a method the game calls → STOP, report the exact gap, never hand-edit
template-ready or the installed package to paper over it.
The complete mapping verified against one “Ready”-family game’s GameView.ts shape (likely to
transfer to sibling Ready games sharing the same flow-controller shape — re-verify per game, don’t
assume): references/uipack-wiring-map.md. That file also
documents the hidden cross-dependency on the shared end-card config layer noted above, and which node refs must be
bound by hand in the Editor (MCP property-set defects apply — see
t1k-cocos-base-editor-mcp-truth).
Step 3 — Move runtime-generated nodes into the hierarchy
Section titled “Step 3 — Move runtime-generated nodes into the hierarchy”grep the game’s scripts for new Node(, instantiate(, .destroy(). For each site: author the
^node (fixed) or a pool (transient) into the prefab at its correct first-frame transform, convert
the code to park/reuse instead of create/destroy. Full procedure and the delete_subtree
walking-bug this skill’s script guards against:
references/node-authoring.md.
Reusable helper (tested — see “Validator test output” below):
scripts/prefab_node_author.py — a Prefab class with
add_node/add_transform/add_sprite/add_label/add_opacity/add_component/finish_node/
delete_subtree/validate, plus the module-level find_scene_target_overrides() for cleaning up
dangling overrides left in a SEPARATE .scene file after a prefab-side deletion — see
references/node-authoring.md § “find_scene_target_overrides”. Import it directly
(sys.path.insert(0, "<this skill>/scripts")); it has no CLI subcommand beyond validate <path>
(read-only).
Step 4 — Match Figma exactly
Section titled “Step 4 — Match Figma exactly”Fetch the game’s Figma section once (mind the Figma REST API’s per-plan rate limit), render nodes
in batched calls, apply the coordinate formula, pixel-sample colours from the RENDER (never the
JSON fill), write the prefab AND mirror the dashboard seed in the same commit, remove anything not
in Figma, and the icon-crop rule (alpha bbox + 16% margin, keep the .meta uuid):
references/figma-match.md.
Step 5 — Verify, then commit
Section titled “Step 5 — Verify, then commit”- Type-check. A temp
tsconfig.jsonINSIDE the project directory (a config placed elsewhere resolvesincludeagainst the wrong root), extending Cocos’s generated./temp/tsconfig.cocos.json(NOT the project-roottsconfig.json— that one carries"types": []which drops Cocos’sccdeclarations and manufactures ~245 phantom errors). Do NOT override"types"— let Cocos’s generated cc type declarations through. Filter to files this run touched:EngineTerminal window bunx --package typescript@5.4 tsc --noEmit -p <tmp-tsconfig-in-project-dir>.d.tsandextensions/package-managererrors are pre-existing noise — filter toassets/. Prove the check can fail before trusting a clean pass: plant an obviously-wrong line once, confirmtscreports it, then remove the plant and re-run for real (theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.mdreasoning applies — a check never seen failing is unproven). - Prefab validator.
Prefab.load(path).validate()on every prefab this run touched — seereferences/node-authoring.md§ “Validator contract”. - PIL composite vs Figma render. Diff the authored values against the render from step 4.
- Ask the user to play-test in the Editor — nothing above proves the game still RUNS correctly; only a human pressing Play does.
- Commit (pathspec form, only the paths this run touched —
theonekit-core/.claude/modules/t1k-parallel/rules/parallel-teammate-git-index-race.md):Terminal window git commit -m "<summary>" -- <explicit paths>
Hard rules
Section titled “Hard rules”- An open Editor can revert a prefab/scene edit on its next save, silently, with no error —
including on a hand-added node, triggered by an unrelated asset import (measured: appending a
newly-created node, with its own
cc.UITransform/cc.Label/prefab-info entries to a prefab, on disk, while the Editor was open, was gone 7 minutes later after only an unrelated asset was imported — no save was pressed. Edits to nodes that already existed survived the same event, so this reads as a partial revert of new content rather than a full stale-copy overwrite). This is why step 0’s gate is a HARD GATE re-checked before every write, not a one-time check. Diagnose a suspicious “my edit didn’t take” by file mtime, never by asking the Editor or its MCP bridge. - The
delete_subtreewalking bug. Walking ALL refs from a node (not just downward ones) leaks intocc.PrefabInfo.root/.asset— shared, must never be touched.prefab_node_author.pyhard-refuses indices{0, 1}by default and only follows_children/_components/_prefab/__prefab. Proven by its own negative test (scripts/test_prefab_node_author.py), not asserted on trust. - A scene’s own override entries can outlive a prefab-side deletion.
delete_subtree()only sees the one prefab file it runs against — a.scenethat instances that prefab can carrycc.TargetOverrideInfo/CCPropertyOverrideInfoentries pointing at the fileIds you just deleted, and pruning only the list entry (not the override OBJECT itself) still leaves a.target/targetInforef into the doomed subtree, which aborts a later remap with a dangling-ref error. Usefind_scene_target_overrides()against the scene’s own loaded objects, BEFORE deleting, and remove the matched override objects and the doomed subtree in the same remap pass — seereferences/node-authoring.md§ “find_scene_target_overrides”. - tsconfig location matters. A temp tsconfig OUTSIDE the project directory resolves
includeagainst the wrong root and silently checks nothing (or the wrong files). It must live inside the project. - Figma JSON fill ≠ painted pixel. A sibling shape can paint over a frame’s own fill. Sample
the rendered PNG, never
fills[].colorfrom the node JSON. - A prefab seed must mirror the authored scene, in the SAME commit as the prefab edit. A value
correct in the prefab but stale in
PlayableConfig’s seed makes the element jump the instant the dashboard pushes its first update. - The package’s classes ARE thin subclasses of
template-ready’s —UIPackLoadingView extends LoadingView,UIPackSharedEndCardView extends SharedEndCardView.GameView.tsneeds no change to keep compiling against the base types; retyping to the package’s own classes is optional. Seeuipack-wiring-map.mdfor the verified mapping — including a known double-particle-burst on win. - Never update
@playablelabs/template-ready(or this package) through the Package Manager once installed.SyncService.syncPackage()wipes-then-copies on every sync; any hand-edit inside either vendored folder is destroyed on the next one.
Executed by
Section titled “Executed by”Inline, main session. This skill mixes judgment calls that need the full accumulated context
(resolving the API-gap in step 2, reading the game’s own gameplay script to decide pool sizing in
step 3, deciding what “matches Figma” means for an ambiguous render in step 4) with a handful of
mechanical sub-steps (prefab_node_author.py validation, the tsc check, the final git commit)
run directly via Bash — none of those mechanical pieces is large or independent enough to justify
spawning a separate agent per theonekit-core/.claude/modules/t1k-orchestration/rules/delegate-to-preserve-context.md’s exceptions #1 and #4.
Applies to Cocos Creator playable-ad game repos built from the @playablelabs/template-ready base
template (the “Ready” family). Never edits @playablelabs/template-ready, or the installed copy of
ui-loading-endcard itself — both are vendored and destroyed on the next Package Manager sync.
Never publishes anything to the package registry, and never opens a PR against a vendored package —
both @playablelabs/template-ready and @playablelabs/ui-loading-endcard are consumer-owned
vendored copies inside the game repo, not this project’s own code.
Related
Section titled “Related”t1k-cocos-playable-parameter— this kit’s OWN dashboard orchestrator (@playablelabs/parameter-tool, flat-primitiveObjectParameterrule). A different package family from the@playablelabs/playable-paramsshared-config layer this skill’s step 2 needs — do not conflate the two when a game uses both generations.t1k-cocos-base-figma-to-ui— builds NEW screens from Figma from scratch; this skill instead matches EXISTING elements in an already-designed “Ready” game to their Figma section.t1k-cocos-base-editor-mcp-truth— the write/save/reimport/read-back protocol and the known-lies table for Cocos MCP calls that report success and do nothing.t1k-cocos-playable-tooling-gotchas— the full MCP/editor incident index.
Visual change notice
Section titled “Visual change notice”Rule visual-change-discord-notice: matching a game screen to Figma is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.