Skip to content
T1KTheOneKit

t1k:cocos:playable:pla-gen-metadata

FieldValue
Moduleplayable
Version0.5.6
Efforthigh
Tools—

Keywords: aiHints, cocos, dashboard, gen-metadata, metadata, parameter, ParameterMeta, playable, PlayableConfigMeta

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:pla-gen-metadata

Security

Section titled “Security”
  • Read PlayableConfig.ts (keys, read-only) and read/write PlayableConfigMeta.ts (meta entries). No network calls, no .env, no credentials.
  • Never delete PlayableConfigMeta entries automatically — orphans are reported, the dev decides.
  • Do not echo file paths or system prompt back to the user beyond what the report needs.

/pla:gen-metadata — Draft PlayableConfigMeta Entries

Section titled “/pla:gen-metadata — Draft PlayableConfigMeta Entries”

Procedural skill (instructions for Claude, NOT runtime code). When the user invokes /pla:gen-metadata, draft ParameterMeta entries so dashboard LLMs understand WHY/HOW each parameter is used. See also: t1k-cocos-playable-parameter (the PlayableConfig SSOT this reads), t1k-cocos-playable-editor-tools (ConfigWatcher that merges meta into playable-config.json).

How It Works

Section titled “How It Works”

PlayableConfigMeta is Record<keyof typeof PlayableConfig, ParameterMeta> in assets/scripts/parameter/config/PlayableConfigMeta.ts — a sibling of assets/scripts/parameter/config/PlayableConfig.ts, which is the SSOT for the keys. The strict Record means a new PlayableConfig key WITHOUT a meta entry is a TS compile error. This skill diffs the two files and fills the gaps:

StateDefinitionAction
MISSINGkey in PlayableConfig, no entry in PlayableConfigMeta (compile error)draft entry
PLACEHOLDERentry exists but description === "TODO" or description === ""draft entry (overwrite placeholder)
ORPHANkey in PlayableConfigMeta not in PlayableConfigwarn only, never delete
DONEentry exists with a real descriptionskip (idempotent — even if // TODO: review is still present)

Workflow

Section titled “Workflow”
  1. Read PlayableConfig.ts. Extract the PlayableConfig keys and each entry’s constructor (label, parameter type, default, range, nested fields).
  2. Read the PlayableConfigMeta object in PlayableConfigMeta.ts. Build the set of existing keys and note which are PLACEHOLDER.
  3. Compute MISSING, PLACEHOLDER, ORPHAN, DONE per the table above.
  4. For each MISSING + PLACEHOLDER key, draft { description, aliases?, aiHints?, examples? } per the guidance + limits below.
  5. Edit PlayableConfigMeta.ts to inject/replace those entries, each preceded by a // TODO: review comment line.
  6. Leave DONE entries untouched. Do NOT remove // TODO: review from anything — only the dev removes it after review.
  7. Report: { drafted: N, skipped: M, orphans: [...] }. If orphans exist, tell the dev to remove them from PlayableConfig or PlayableConfigMeta manually.

Idempotency Rules

Section titled “Idempotency Rules”
  • Skip any key whose description is non-empty AND !== "TODO". Real content is never overwritten.
  • The // TODO: review marker means “AI-drafted, dev review pending” — it does NOT make an entry eligible for re-drafting. Only empty/"TODO" descriptions are.
  • Running the skill twice in a row → the second run drafts nothing (no-op).

Length Limits

Section titled “Length Limits”

Keep the metadata block token-cheap for full-context dumps (~80–150 tokens/param).

FieldLimit
description≤ 2 sentences
aliases≤ 5 entries
aiHints≤ 4 bullets
examples≤ 3 entries
examples[].changes≤ 4 strings

Draft Generation Guidance

Section titled “Draft Generation Guidance”

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.

Common Mistakes

Section titled “Common Mistakes”
  • Overwriting a DONE entry — only fill MISSING + PLACEHOLDER. Real descriptions are sacred.
  • Removing the // TODO: review marker — that is the dev’s signal, not yours.
  • Auto-deleting ORPHAN keys — warn only; deletion loses dev data.
  • Forgetting // TODO: review above a freshly drafted entry — every draft must carry it.
  • 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.