t1k:cocos:playable:parameter-guide

Auto-generated

🔒 Auto-generated from The1Studio/theonekit-cocos@0.0.0 — edit the source kit, not this page.

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.

Related

• 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