t1k:cocos:playable:pla-gen-metadata
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: aiHints, catalog, dashboard, gen-metadata, metadata, parameter metadata, ParameterMeta, PLAYABLE_CATALOG, PlayableCatalogMeta, PlayableConfigMeta, template selection
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:pla-gen-metadata/pla:gen-metadata: Write the Catalog Block and Parameter Metadata
Section titled “/pla:gen-metadata: Write the Catalog Block and Parameter Metadata”Procedural skill (instructions for Claude, NOT runtime code). /pla:gen-metadata writes two things into assets/scripts/parameter/config/PlayableConfigMeta.ts, both at FINAL quality (no // TODO: review markers, no placeholders):
PLAYABLE_CATALOG: PlayableCatalogMeta- what the template is, so an agent can pick it for a client prompt.- A
ParameterMetaentry for EVERYPlayableConfigkey - why/how each parameter is used.
Contract (v2): metadata.version: 2 in playable-config.json carries { playable, parameters }. Vocabularies + limits: references/catalog-vocabulary.json (SSOT). Writing guidance with good/bad examples: references/catalog-authoring.md (read it before drafting). Upgrading a game’s vendored parameter-tool 1.0.x to 2.2.0 first: references/parameter-tool-2x-migration.md. Related: t1k-cocos-playable-parameter (the PlayableConfig SSOT), t1k-cocos-playable-editor-tools (ConfigWatcher).
Types (declare alongside ParameterMeta if absent)
Section titled “Types (declare alongside ParameterMeta if absent)”export type PlayableCatalogMeta = { id: string; title: string; summary: string; description: string; genre: string; mechanics: string[]; inputs: string[]; difficulty: "very-easy" | "easy" | "medium" | "hard"; sessionSeconds: [number, number]; outcome: string; useCases: string[]; verticals: string[]; brandingDepth: "logo-only" | "reskin" | "full-content"; contentDriven: boolean; assetSlots: AssetSlot[]; tags: string[]; matchPrompts: string[]; notFor: string[]; similarTo?: string[];};export type AssetSlot = { key: string; kind: "image" | "audio" | "text" | "color" | "number" | "list"; role: string; count?: number | "multiple"; recommendedSize?: string; notes?: string;};export const PLAYABLE_CATALOG: PlayableCatalogMeta = { /* ... */ };String-literal unions for the vocabulary fields (taken from catalog-vocabulary.json) are optional compile-time sugar; the validator enforces the vocabulary either way.
Parameter states
Section titled “Parameter states”PlayableConfigMeta is Record<keyof typeof PlayableConfig, ParameterMeta>; a new key without an entry is a TS compile error. This skill diffs PlayableConfig against it:
| State | Definition | Action |
|---|---|---|
| MISSING | key in PlayableConfig, no entry | write entry |
| PLACEHOLDER | description is "TODO" or "" | overwrite with a real entry |
| ORPHAN | key in PlayableConfigMeta not in PlayableConfig | warn only, never delete |
| DONE | real description present | skip (idempotent) |
Workflow
Section titled “Workflow”- Read
PlayableConfig.ts(keys, parameter types, defaults, ranges, nested fields),PlayableConfigMeta.ts, scenes and game scripts (core loop, win/lose, end card), the README/CLAUDE.md, and sibling templates when the umbrella repo is available. - Compute MISSING / PLACEHOLDER / ORPHAN / DONE for the parameters.
- Write the
PLAYABLE_CATALOGblock followingreferences/catalog-authoring.md:- New block when absent. When present, refresh stale facts (new/removed parameters ->
assetSlots, changed gameplay) but keep text that is still accurate; do not churn wording. - Every enum value comes from
references/catalog-vocabulary.json. Never free-type outside it; if the right value is missing, stop and ask for a vocabulary addition. assetSlots[].keymust be a realPlayableConfigkey, copied exactly.
- New block when absent. When present, refresh stale facts (new/removed parameters ->
- For each MISSING + PLACEHOLDER key, write
{ description, aliases?, aiHints?, examples? }per the guidance and limits below. Final quality: specific, accurate, no review markers. - Edit
PlayableConfigMeta.ts(exportPLAYABLE_CATALOG, add/replace parameter entries). Leave DONE entries untouched. - Ensure the project passes
PLAYABLE_CATALOGto the config tooling (see “Emission”). - Validate after the next ConfigWatcher run:
bun <skill>/scripts/validate-catalog.cjs <game>/assets/ParameterToolBuild/playable-config.jsonOutput is JSON{ ok, errors[], warnings[] }; exit 0 valid, 1 invalid, 2 unreadable. Fix every error and re-run untilok: true. - Report:
{ catalog: written|refreshed|unchanged, drafted: N, skipped: M, orphans: [...], validator: ok|errors }. For orphans, tell the dev to remove them manually.
Emission (playable-config.json)
Section titled “Emission (playable-config.json)”The JSON is written by ConfigWatcher in the PlayableParamterTool package (not by this kit). For metadata.version: 2 that tool must receive PLAYABLE_CATALOG (for example PlayableConfigProvider.initialize(PlayableConfig, PlayableConfigMeta, CURRENT_SDK, PLAYABLE_CATALOG)) and emit metadata = { version: 2, playable, parameters }. If the installed tool still emits version: 1, the validator reports metadata.version / metadata.playable errors: tell the dev the tool needs the v2 update rather than editing generated JSON.
Idempotency Rules
Section titled “Idempotency Rules”- Never delete
PlayableConfigMetaentries automatically: orphans are reported, the dev decides. - Reads
PlayableConfig.ts, scenes, scripts and README/CLAUDE.md read-only; writes onlyPlayableConfigMeta.ts. - Skip any key whose
descriptionis non-empty and!== "TODO". Real content is never overwritten. - Re-running with no code changes yields no diff: unchanged-and-accurate text is preserved verbatim.
Length Limits (parameter entries)
Section titled “Length Limits (parameter entries)”Keep the metadata block token-cheap (~80-150 tokens/param).
| Field | Limit |
|---|---|
description | <= 2 sentences |
aliases | <= 5 entries |
aiHints | <= 4 bullets |
examples | <= 3 entries |
examples[].changes | <= 4 strings |
Catalog limits (sentence/array counts) live in catalog-vocabulary.json limits.
Draft Generation Guidance (parameters)
Section titled “Draft Generation Guidance (parameters)”Infer content from the parameter’s type (see t1k-cocos-playable-parameter for the type hierarchy):
SpriteParameter/ButtonParameter: aliases like “button”/“image”; aiHints onspriteColor(hex tint),enable, and (button)string/fontSizelabel fields.LabelParameter/RichTextParameter: aliases like “text”/“label”; aiHints onstring,fontSize,color, and (rich)autoHideDelay/entranceAnimation.preset.RangeParameter/NumberParameter: aiHints statemin..maxandstep(e.g., “Range 0..1 with 0.1 step”).ColorParameter: value is hex#RRGGBB.BooleanParameter: frame as on/off; note whatfalsedisables.NodeParameter/UINodeParameter: aiHints onposition/rotation/scale; UI coords (negative y toward bottom) vs 3D scene units.CameraParameter: position z zooms, rotation x tilts,fovwidens.- Composites (
LoadingScreenParameter,EndCardParameter,ProgressBarParameter): describe the screen’s role, then call out the key nested fields (e.g.,Loading.progressBar.fillColor,EndCardWin.title.string,EndCardWin.ctaButton.string).
examples[].changes format: "Key.field = value" for nested (MainCamera.position.z = 10), bare key for scalars (MusicVolume = 0). One prompt -> the minimal set of field changes that satisfy it.
Executed by
Section titled “Executed by”Running the validator and tabulating its findings is mechanical; writing catalog text and metadata entries is authoring. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run scripts/validate-catalog.cjs (report-only) and label each error/warning by path | t1k-list-classifier |
Write PLAYABLE_CATALOG and ParameterMeta entries into PlayableConfigMeta.ts | t1k-cocos-base-developer (write-capable; t1k-list-classifier has no Edit/Write) |
| Decide template facts from gameplay (genre, outcome, notFor), or request a vocabulary addition | stays on the reasoning tier (orchestrating skill/user) - a judgment call |
Common Mistakes
Section titled “Common Mistakes”- Overwriting a DONE entry: only fill MISSING + PLACEHOLDER.
- Leaving
// TODO: reviewor any placeholder text: output is final, the validator and the umbrella catalog consume it as-is. - Inaccurate claims (fixed art called swappable, product-photo prompts without a product slot, wrong
outcome,EndCardLogoasprize): see “Accuracy rules” incatalog-authoring.md. - Inventing facts: every catalog claim must trace to code, scenes or README; narrow the claim when unsure.
- Free-typing enum values or
assetSlotskeys: both are checked againstcatalog-vocabulary.json/PlayableConfig. - Marketing prose in
summary/description: write what the player does, not adjectives (seecatalog-authoring.md). - Auto-deleting ORPHAN keys: warn only; deletion loses dev data.
- Exceeding the length limits: a bloated metadata block defeats the token-budget goal.
- Drafting in
.opencode/: this skill is Claude-only by project decision; there is no OpenCode mirror.