t1k:cocos:playable:parameter-guide

Field	Value
Module	`playable`
Version	`2.14.4`
Effort	`low`
Tools	—

Keywords: client-handoff, dashboard-guide, docx, excel, export-parameters, operator-guide, parameter-doc, parameter-documentation, parameter-guide, playable-config guide, word, xlsx

How to invoke

/t1k:cocos:playable:parameter-guide
[--input <playable-config.json>] [--out <dir>] [--formats xlsx,docx]

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

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.

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.

Run

# from the Cocos project root
node ~/.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`
`--formats <list>`	`xlsx,docx`
`--install-deps`	off — install the skill’s own deps if missing, then continue

Output: parameter-guide.xlsx (sheet Parameters — frozen header, a shaded separator row per category, wrapped Description column) and parameter-guide.docx (title, one Heading-1 per category, two-column table: Name + Key + Type · Default on the left, Description on the right).

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.

Dependencies — installed once, in the skill

exceljs and docx live in this skill’s own node_modules, not in any project. install.json installs them when the module is installed; if that step was skipped, install once per machine — npm install inside this skill’s folder:

# kit source layout
npm install --prefix .claude/modules/playable/skills/t1k-cocos-playable-parameter-guide
# installed layout
npm install --prefix ~/.claude/skills/t1k-cocos-playable-parameter-guide

or let the script do it on first run, whatever its location:

node <skill>/scripts/generate-parameter-guide.cjs --install-deps

The script derives its own folder from __dirname, so it never needs to be told where it lives — and the error message it prints on a missing dep already names the correct path for the copy being run.

After that every Cocos project works — including old ones that were never set up for this — with zero changes to their package.json. That is the point of keeping the deps here: a documentation tool should not force a dependency into a shipping game project, and a per-project install would have to be repeated (and committed) for every playable ever made.

Resolution order is skill node_modules → project root → cwd, so a project that already carries its own copies still works as a fallback. A missing dep exits with code 2 and prints the exact install command. Nothing reaches the built playable either way, so the size budget is untouched.

After a t1k modules update refreshes the skill, re-run with --install-deps if the deps were cleared.

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.	Save the project in Cocos so `ConfigWatcher` regenerates, then re-run
`no metadata.parameters block`	The config predates the metadata sidecar. Every description reads `—`.	Regenerate with a `ConfigWatcher` that emits metadata

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.

Gotchas

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