Skip to content

t1k:cocos:playable:parameter-guide

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

/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])

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:

HalfWhere in the JSONAuthored in
Dashboard shape — label, type, category, default, optionsparameters[key]PlayableConfig.ts
Meaning — the descriptionmetadata.parameters[key].descriptionPlayableConfigMeta.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.

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

StepAgent
Run generate-parameter-guide.cjs and report the XLSX/DOCX paths and the warnings it emitst1k-cocos-base-tester
Run capture-dashboard-screens.cjs / capture-gameplay-diff.cjs and list the images writtent1k-cocos-base-tester
Fill guide-extras.json size and notest1k-cocos-base-developer — reasoning tier

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.

Terminal window
# from the Cocos project root
bun ~/.claude/skills/t1k-cocos-playable-parameter-guide/scripts/generate-parameter-guide.cjs
FlagDefault
--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-depsoff — 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.

Optional: show, per top-level parameter, a screenshot of WHERE it lives on the PlayableLabs dashboard. Two steps, capture then generate:

Terminal window
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; --out changes it, --only Key,Key limits 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>.png also 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-profile and 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’s package.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.

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.

Terminal window
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 finally resets 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 are skipped:<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) in guide-extras.json: "gameplay": { "<Key>": { "steps": [{ "wait": 3000 }, { "tap": [x, y] }] } } (preview-verify’s step format, wait and tap only; tap is 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. field and value overrides live there too.
  • Pixel diff reuses t1k-gamedev-playable-preview-verify’s png.cjs; steps are parsed by its flow.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. stat on 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 KB with 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 assets entry 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.

WarningMeaningFix
N parameter(s) have no descriptionKey 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 sourceThe .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 blockThe 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.jsonAn 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 JSONThe 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.

  • Output lives under assets/. Cocos will import parameter-guide.xlsx / .docx and generate a .meta for each, exactly as it already does for the .log files in ParameterToolBuild/logs/. They sit outside resources/ and are referenced by no scene, so they are not packed into the build.
  • DOCX table widths must stay in twips. WidthType.PERCENTAGE in the docx package takes OOXML fiftieths of a percent, so size: 100 renders as 2% and collapses every column to one character wide (one letter per line). The tables use WidthType.DXA with an explicit columnWidths + TableLayoutType.FIXED against 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 description in PlayableConfigMeta.ts, which also improves the dashboard LLM’s understanding — one edit, two payoffs.
  • t1k-cocos-playable-parameter — the parameter system orchestrator
  • t1k-cocos-playable-parameter-audit — finds parameters that do nothing
  • t1k-cocos-playable-pla-gen-metadata — drafts missing PlayableConfigMeta entries