Skip to content

t1k:cocos:playable:ready-figma

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: author prefab nodes, cocos playable install package, playable ready figma, ready template figma match, runtime node pooling, ui-loading-endcard

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

SkillCovers
t1k-cocos-base-figma-to-uiBuild NEW UI screens from a Figma file from scratch, via the Figma REST API + Cocos MCP
t1k-cocos-playable-parameterThis kit’s flat-primitive @playablelabs/parameter-tool dashboard system
this skillInstall 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.

IntentPath
Install the package + wire GameView onlySteps 0–2, stop before step 3
Move runtime new Node/destroy() into the prefabSteps 0, 3
Match the game to its Figma designSteps 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)”
  1. 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-root CLAUDE.md or a design-tracking doc) — this skill does not hardcode any studio’s Figma file key or game roster.
  2. $FIGMA_TOKEN present in the environment — needed for step 4 even if this run stops earlier.
  3. Cocos Creator CLOSED on this project — hard gate, no override. A single running Editor spawns roughly a dozen CocosCreator.exe HELPER 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 on CaseOpeningPLA 2026-09-22: 13 CocosCreator.exe matches, the sole --project argument 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):
    Terminal 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 }"
    Replace <project-dir-name> with the target project’s folder name (the root identified in item 1). A helper-process row with no --project argument is not evidence the gate should fail — only a GATE FAIL row naming the target project’s own path is. On macOS/Linux, check for a running CocosCreator process 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, and t1k-cocos-base-editor-mcp-truth for the general write/read-back protocol this same failure mode motivates.
  4. 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).
  5. 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 status is 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.

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

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.

  1. Type-check. A temp tsconfig.json INSIDE the project directory (a config placed elsewhere resolves include against the wrong root), extending Cocos’s generated ./temp/tsconfig.cocos.json (NOT the project-root tsconfig.json — that one carries "types": [] which drops Cocos’s cc declarations and manufactures ~245 phantom errors). Do NOT override "types" — let Cocos’s generated cc type declarations through. Filter to files this run touched:
    Terminal window
    bunx --package typescript@5.4 tsc --noEmit -p <tmp-tsconfig-in-project-dir>
    Engine .d.ts and extensions/package-manager errors are pre-existing noise — filter to assets/. Prove the check can fail before trusting a clean pass: plant an obviously-wrong line once, confirm tsc reports it, then remove the plant and re-run for real (theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.md reasoning applies — a check never seen failing is unproven).
  2. Prefab validator. Prefab.load(path).validate() on every prefab this run touched — see references/node-authoring.md § “Validator contract”.
  3. PIL composite vs Figma render. Diff the authored values against the render from step 4.
  4. Ask the user to play-test in the Editor — nothing above proves the game still RUNS correctly; only a human pressing Play does.
  5. 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>
  • 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_subtree walking bug. Walking ALL refs from a node (not just downward ones) leaks into cc.PrefabInfo.root/.asset — shared, must never be touched. prefab_node_author.py hard-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 .scene that instances that prefab can carry cc.TargetOverrideInfo/CCPropertyOverrideInfo entries pointing at the fileIds you just deleted, and pruning only the list entry (not the override OBJECT itself) still leaves a .target/targetInfo ref into the doomed subtree, which aborts a later remap with a dangling-ref error. Use find_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 — see references/node-authoring.md § “find_scene_target_overrides”.
  • tsconfig location matters. A temp tsconfig OUTSIDE the project directory resolves include against 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[].color from 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.ts needs no change to keep compiling against the base types; retyping to the package’s own classes is optional. See uipack-wiring-map.md for 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.

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.

  • t1k-cocos-playable-parameter — this kit’s OWN dashboard orchestrator (@playablelabs/parameter-tool, flat-primitive ObjectParameter rule). A different package family from the @playablelabs/playable-params shared-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.

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.