t1k:cocos:playable:parameter-guide
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | low |
| Tools | — |
Keywords: before-after-screenshot, capture-dashboard-screens, client-handoff, dashboard-guide, dashboard-screenshot, docx, excel, export-parameters, gameplay-diff, operator-guide, parameter-doc, parameter-documentation, parameter-guide, parameter-location, playable-config guide, playwright-core, word, xlsx
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:parameter-guide[--input <playable-config.json>] [--out <dir>] [--extras <guide-extras.json>] [--formats xlsx,docx] [--lang en|vi] [--screens <dir>] (capture: --url <customization url> [--port 9333] [--only Key,Key]; capture-gameplay-diff: same flags + [--extras <file>] [--max-wait 30] [--threshold 2])Cocos Playable Parameter Guide
Section titled “Cocos Playable Parameter Guide”Turns the parameter system into a document a non-engineer can read. The ad operator sees ~40 controls on the dashboard and has no way to know what any of them does; this skill emits that answer as a spreadsheet and a Word document.
What it reads — and why not the TypeScript
Section titled “What it reads — and why not the TypeScript”assets/ParameterToolBuild/playable-config.json is generated by ConfigWatcher
on every editor save and already contains both halves of the guide:
| Half | Where in the JSON | Authored in |
|---|---|---|
| Dashboard shape — label, type, category, default, options | parameters[key] | PlayableConfig.ts |
| Meaning — the description | metadata.parameters[key].description | PlayableConfigMeta.ts |
Reading the JSON means the guide can never disagree with the dashboard the
operator actually gets, and label/nesting logic is not re-implemented. Parsing
the two .ts files would duplicate that logic and drift from it.
Cost of this choice: the JSON must be current. The script compares mtimes and
warns when either .ts is newer than the JSON — save in the Cocos editor first.
Executed by
Section titled “Executed by”The guide is generated by a deterministic Node script (no LLM); screenshots are scripted capture. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run generate-parameter-guide.cjs and report the XLSX/DOCX paths and the warnings it emits | t1k-cocos-base-tester |
Run capture-dashboard-screens.cjs / capture-gameplay-diff.cjs and list the images written | t1k-cocos-base-tester |
Fill guide-extras.json size and notes | t1k-cocos-base-developer — reasoning tier |
Scope — top-level parameters only
Section titled “Scope — top-level parameters only”One row per top-level key. An ObjectParameter becomes a single row whose
Default reads (group of N settings); its children are not listed.
This is deliberate: descriptions in PlayableConfigMeta are authored per
top-level key, so child rows would repeat the parent’s text ~150 times and bury
the 39 decisions an operator actually makes. If per-child guidance is ever
needed, ParameterMeta has to grow child-level descriptions first — do not
fake it by inheriting the parent’s.
# from the Cocos project rootbun ~/.claude/skills/t1k-cocos-playable-parameter-guide/scripts/generate-parameter-guide.cjs| Flag | Default |
|---|---|
--input <file> | auto-discovered: assets/ParameterToolBuild/playable-config.json |
--out <dir> | <input dir>/guide |
--extras <file> | guide-extras.json beside the input — optional; absent means no size column values and no notes block |
--formats <list> | xlsx,docx |
--install-deps | off — install the skill’s own deps if missing, then continue |
--lang <code> | en — language of the guide’s own headings, column names, type labels and placeholders (en or vi). Config content (labels, categories, descriptions) is copied as authored, never translated |
Output: parameter-guide.xlsx (sheet Parameters — an optional notes block above
the header, then a frozen header, a shaded separator row per category, wrapped
Description column) and parameter-guide.docx (title, the same notes as bullets,
one Heading-1 per category, two-column table: Name + Key + Type · Default +
current size on the left, Description on the right).
The DOCX keeps size in the left cell rather than gaining a third column — the fixed-twips layout below has no room to spare, and an operator reads size as a property of the slot anyway.
Both keep the dashboard’s own ordering — categories in first-appearance order, declaration order within a category — so the document can be read alongside the dashboard top to bottom.
Dashboard location screenshots
Section titled “Dashboard location screenshots”Optional: show, per top-level parameter, a screenshot of WHERE it lives on the PlayableLabs dashboard. Two steps, capture then generate:
bun <skill>/scripts/capture-dashboard-screens.cjs --url "https://app.playablelabs.ai/<org>/customization?versionId=<uuid>"bun <skill>/scripts/generate-parameter-guide.cjs # picks up <out>/screens automatically- Capture writes a cropped
<Key>.jpg(JPEG q80; Categories sidebar + Editing panel only, phone Preview hidden during the shot; red frame on the category and the card) to<input dir>/guide/screens;--outchanges it,--only Key,Keylimits it. It ends with captured/skipped counts and a reason per skipped key; exit 0 if at least one was captured, 3 if none. - The generator embeds them when the screens folder exists (
--screens <dir>, default<out>/screens;<Key>.jpg, legacy<Key>.pngalso accepted): DOCX gets a full-width row under the parameter, XLSX a “Dashboard location” column. Parameters without a PNG are listed as a non-fatal warning. No screens folder means an unchanged guide. - Read-only guarantee. The only click is a category button; the list is scrolled. Save / Reset / Export, inputs and colour pickers are never touched, cards are never expanded. A unit test pins this.
- Auth. It attaches to a real Chrome over CDP (port 9333). If none is running it starts one with a persistent profile in
~/.playablelabs-auth/chrome-profileand waits up to 15 min for you to log in. That profile holds your login: keep it out of repos. - Needs
playwright-core(in this skill’spackage.json; lazily loaded only by the capture script). Missing: exit 2 and the exact install command. - Gotchas: Google OAuth refuses Playwright-launched browsers (use real Chrome + CDP); the login redirect drops
versionId(re-open the full URL, check the hostname); the parameter list is virtualized (scroll until the label appears). Detail:references/dashboard-screens.md.
Gameplay before/after screenshots
Section titled “Gameplay before/after screenshots”Optional, slower, and it edits dashboard values (locally). The preview is not deterministic, so nothing is
matched across a run: for each colour / text / boolean / select parameter it replays the game with the
original value and with a test value, waits until the preview has settled (identical frames in a row),
and compares the two settled frames against a noise floor measured in the same session. Captured pairs are
saved as <Key>.before.jpg + <Key>.after.jpg; each value is reverted.
bun <skill>/scripts/capture-gameplay-diff.cjs --url "<customization url>" [--only Key,Key] [--extras <file>]bun <skill>/scripts/generate-parameter-guide.cjs # embeds the pairs- Nothing is saved: values change only in the page’s local state, each is reverted through its card’s own
“Reset to original” and verified, a
finallyresets leftovers, and the run exits 4 if anything stays modified. It exits 5 (nothing reported) when the noise floor is not believable, e.g. a loading screen taken as the baseline (--max-noise,--baseline-attempts). Save / Export / Share / uploads / Add Row are never touched; uploads and tables areskipped:<type>. - Per key:
captured/no-visible-change/unsettled/skipped:<type>/error. The run ends with the list of keys that showed nothing on the settled screen. If those matter, you can try declared steps (EXPERIMENTAL; settled mode is the supported path) inguide-extras.json:"gameplay": { "<Key>": { "steps": [{ "wait": 3000 }, { "tap": [x, y] }] } }(preview-verify’s step format,waitandtaponly;tapis relative to the preview). Steps are fixed-clock and load time varies per run, so a tap can land on a different screen in the original and test runs; a tap into live gameplay never settles. Read every steps pair before shipping it.fieldandvalueoverrides live there too. - Pixel diff reuses
t1k-gamedev-playable-preview-verify’spng.cjs; steps are parsed by itsflow.cjs. Settle rule, compare rule and limits:references/gameplay-diff.md.
guide-extras.json — the size column and the notes block
Section titled “guide-extras.json — the size column and the notes block”The config records that a parameter is an image / audio / 3D slot. It does not
record which shipped file that slot overwrites — that link lives in the view
code (replaceParameterSprite(this.ctaButton, …)), which this script deliberately
does not parse. So it is authored once, per project, in a sidecar next to
playable-config.json:
{ "budget": { "currentMB": 4.09, "maxMB": 4.8 }, "notes": ["Free-form line shown as a bullet, in the project's own words."], "assets": { "CTAButton": ["assets/Sprite/Playnow.png"], "WinBearSpine": ["assets/…/bear.json", "assets/…/bear.atlas.txt", "assets/…/bear.webp"] }}Paths are project-root-relative. Every field is optional — with no sidecar the
guide renders exactly as it did before, with the size column reading —.
What the script adds on top of what is authored:
- Sizes are measured, never authored.
staton each file at generation time, so a re-export that doubles a texture shows up on the next run instead of quietly disagreeing with a number someone typed months ago. - Multi-file slots list their parts. A spine set reads
Total 482 KBwith a line per file — an operator replacing one has to supply all three, and the breakdown is what tells them which is the heavy one. - The budget line is computed from
currentMB/maxMB, headroom included. - The replaceable total is deduped by path, so one asset shared by two parameters (a hand spine on both end cards) is counted once. That total is also the honest ceiling on what a like-for-like swap can reclaim.
- An upload slot with no
assetsentry is reported, by key, at the end of the run — a blank size cell would otherwise read as “nothing ships here”, which for an upload slot is never true.
Why sizes are the source files, not the built bytes. The source file is what
the operator compares their replacement against, and it is measurable now without
a build. Two things it does not capture, both worth a notes line when they
apply to the project: uploaded assets are embedded as base64 (≈ +33% over the
binary), and a mesh source (.fbx) is compressed at build time, so its build
contribution is smaller than the file on disk.
Size is a yardstick because the original is removed. The parameter tool drops
a shipped asset from the build once every reference to it is parameter-owned
(ParameterToolBuild/logs/asset-removal-report.log records what it took). So a
like-for-like swap is net-zero — but an asset referenced from somewhere the
parameter does not own stays in the build, and the replacement’s full size is
added on top. That case is worth naming explicitly in notes.
Dependencies — installed once, in the skill
Section titled “Dependencies — installed once, in the skill”exceljs and docx live in this skill’s own node_modules, not in any project: install once per machine (bun install --cwd <skill dir>) or run the generator with --install-deps. Resolution order, why deps stay out of game projects, and the post-update step: references/dependencies.md.
Warnings the script emits (non-fatal)
Section titled “Warnings the script emits (non-fatal)”| Warning | Meaning | Fix |
|---|---|---|
N parameter(s) have no description | Key exists in PlayableConfig but has no metadata.parameters[key].description. The row reads —. | Add the entry in PlayableConfigMeta.ts, or run /pla:gen-metadata to draft it |
playable-config.json is OLDER than its source | The .ts was edited after the last editor save; the guide documents a stale dashboard. | Bring the Cocos editor to the foreground and reopen MainScene so a fresh ConfigWatcher regenerates (a save or manage_asset refresh does not; see t1k-cocos-playable-editor-tools skills/t1k-cocos-playable-editor-tools/references/configwatcher.md), then re-run |
no metadata.parameters block | The config predates the metadata sidecar. Every description reads —. | Regenerate with a ConfigWatcher that emits metadata |
N upload slot(s) have no entry in guide-extras.json | An image/audio/3D parameter whose shipped counterpart was never mapped. Its size cell reads —, which an operator reads as “nothing ships here”. | Add the path(s) under assets in the sidecar |
guide-extras.json is not valid JSON | The sidecar failed to parse. Sizes and notes are skipped; the rest of the guide still generates. | Fix the JSON |
Parameters injected by shared packages (@playablelabs/share-parameter —
EntranceVideo, IntroZoom, TopBanner, IQBar, …) commonly land in the first
row: they are declared outside the project’s own PlayableConfigMeta, so they
need descriptions added there before they read well in a client-facing guide.
Hard rules
Section titled “Hard rules”- Output lives under
assets/. Cocos will importparameter-guide.xlsx/.docxand generate a.metafor each, exactly as it already does for the.logfiles inParameterToolBuild/logs/. They sit outsideresources/and are referenced by no scene, so they are not packed into the build. - DOCX table widths must stay in twips.
WidthType.PERCENTAGEin thedocxpackage takes OOXML fiftieths of a percent, sosize: 100renders as 2% and collapses every column to one character wide (one letter per line). The tables useWidthType.DXAwith an explicitcolumnWidths+TableLayoutType.FIXEDagainst a 9360-twip content width — do not “simplify” that back to percentages. - Not byte-reproducible. XLSX and DOCX are zip containers that embed creation
timestamps, so re-running always produces a different binary even when the
content is identical. Expect a git diff on every run; if that churn is
unwanted, gitignore the
guide/folder and treat it as an export. - Do not hand-edit the output. It is regenerated wholesale. Guide wording is
fixed by editing
descriptioninPlayableConfigMeta.ts, which also improves the dashboard LLM’s understanding — one edit, two payoffs.
Related
Section titled “Related”t1k-cocos-playable-parameter— the parameter system orchestratort1k-cocos-playable-parameter-audit— finds parameters that do nothingt1k-cocos-playable-pla-gen-metadata— drafts missingPlayableConfigMetaentries