Skip to content

t1k:cocos:playable:pla-gen-metadata

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: aiHints, catalog, dashboard, gen-metadata, metadata, parameter metadata, ParameterMeta, PLAYABLE_CATALOG, PlayableCatalogMeta, PlayableConfigMeta, template selection

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

  1. PLAYABLE_CATALOG: PlayableCatalogMeta - what the template is, so an agent can pick it for a client prompt.
  2. A ParameterMeta entry for EVERY PlayableConfig key - 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.

PlayableConfigMeta is Record<keyof typeof PlayableConfig, ParameterMeta>; a new key without an entry is a TS compile error. This skill diffs PlayableConfig against it:

StateDefinitionAction
MISSINGkey in PlayableConfig, no entrywrite entry
PLACEHOLDERdescription is "TODO" or ""overwrite with a real entry
ORPHANkey in PlayableConfigMeta not in PlayableConfigwarn only, never delete
DONEreal description presentskip (idempotent)
  1. 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.
  2. Compute MISSING / PLACEHOLDER / ORPHAN / DONE for the parameters.
  3. Write the PLAYABLE_CATALOG block following references/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[].key must be a real PlayableConfig key, copied exactly.
  4. For each MISSING + PLACEHOLDER key, write { description, aliases?, aiHints?, examples? } per the guidance and limits below. Final quality: specific, accurate, no review markers.
  5. Edit PlayableConfigMeta.ts (export PLAYABLE_CATALOG, add/replace parameter entries). Leave DONE entries untouched.
  6. Ensure the project passes PLAYABLE_CATALOG to the config tooling (see “Emission”).
  7. Validate after the next ConfigWatcher run: bun <skill>/scripts/validate-catalog.cjs <game>/assets/ParameterToolBuild/playable-config.json Output is JSON { ok, errors[], warnings[] }; exit 0 valid, 1 invalid, 2 unreadable. Fix every error and re-run until ok: true.
  8. Report: { catalog: written|refreshed|unchanged, drafted: N, skipped: M, orphans: [...], validator: ok|errors }. For orphans, tell the dev to remove them manually.

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.

  • Never delete PlayableConfigMeta entries automatically: orphans are reported, the dev decides.
  • Reads PlayableConfig.ts, scenes, scripts and README/CLAUDE.md read-only; writes only PlayableConfigMeta.ts.
  • Skip any key whose description is 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.

Keep the metadata block token-cheap (~80-150 tokens/param).

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

Infer content from the parameter’s type (see t1k-cocos-playable-parameter for the type hierarchy):

  • SpriteParameter / ButtonParameter: aliases like “button”/“image”; aiHints on spriteColor (hex tint), enable, and (button) string/fontSize label fields.
  • LabelParameter / RichTextParameter: aliases like “text”/“label”; aiHints on string, fontSize, color, and (rich) autoHideDelay/entranceAnimation.preset.
  • RangeParameter / NumberParameter: aiHints state min..max and step (e.g., “Range 0..1 with 0.1 step”).
  • ColorParameter: value is hex #RRGGBB.
  • BooleanParameter: frame as on/off; note what false disables.
  • NodeParameter / UINodeParameter: aiHints on position/rotation/scale; UI coords (negative y toward bottom) vs 3D scene units.
  • CameraParameter: position z zooms, rotation x tilts, fov widens.
  • 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.

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

StepAgent
Run scripts/validate-catalog.cjs (report-only) and label each error/warning by patht1k-list-classifier
Write PLAYABLE_CATALOG and ParameterMeta entries into PlayableConfigMeta.tst1k-cocos-base-developer (write-capable; t1k-list-classifier has no Edit/Write)
Decide template facts from gameplay (genre, outcome, notFor), or request a vocabulary additionstays on the reasoning tier (orchestrating skill/user) - a judgment call
  • Overwriting a DONE entry: only fill MISSING + PLACEHOLDER.
  • Leaving // TODO: review or 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, EndCardLogo as prize): see “Accuracy rules” in catalog-authoring.md.
  • Inventing facts: every catalog claim must trace to code, scenes or README; narrow the claim when unsure.
  • Free-typing enum values or assetSlots keys: both are checked against catalog-vocabulary.json / PlayableConfig.
  • Marketing prose in summary/description: write what the player does, not adjectives (see catalog-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.