Skip to content

t1k:cocos:playable:parameter

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: canvas-scan, config-scan, dashboard, dynamic-config, parameter, playable-config, playable-parameter, ui-composite

/t1k:cocos:playable:parameter
[--ui|--config|--all] [--deep] [--canvas <path>] [--path <folder>] [natural language]

Orchestrator for the flat-primitive parameter architecture.

Every ObjectParameter MUST contain ONLY primitive BaseParameter instances. No ComponentParameter subclass instances. No nested ObjectParameter. Max depth = 2 (ObjectParameter -> primitive). No script enforces it; check by hand in PlayableConfig.ts (see references/type-hierarchy.md § Depth check).

Every other rule in this skill is a corollary of that one. If you must choose between this rule and any example below, the rule wins.

PlayableConfig is serialized to JSON for the dashboard. Nested ObjectParameter or ComponentParameter instances produce structures the dashboard cannot render or edit. Flattening at the config layer keeps dashboard JSON shallow; ComponentParameter reconstruction happens only at apply-time inside the controller.

The CPM package db://assets/packages/@playablelabs/parameter-tool/ owns the runtime. Skill points at it; do not duplicate.

Use asImports from
Primitives in PlayableConfig entriesparameter/BaseParameter: ColorParameter, NumberParameter, BooleanParameter, TextParameter, ImageParameter, SelectParameter, CoordinatesParameter, ObjectParameter
Apply-time component typesparameter/component-parameter/: SpriteComponentParameter, LabelComponentParameter, ButtonComponentParameter, TransformComponentParameter, UIOpacityComponentParameter, …
Apply functionsparameter/ParameterApply: applySpriteComponentParams, applyLabelComponentParams, applyButtonComponentParams, applyTransformComponentParams, applyUIOpacityComponentParams, …
Async trackingparameter/ParameterBinder: ParameterBinder (use only binder.waitForAsync() in v6)
SDK manager basebase/BaseParameterManager: extend in project’s ParameterManager
SDK selection / redirectsdk/voodoo: Vsdk (used for CTA redirect)
Config injectionconfig/PlayableConfigProvider: PlayableConfigProvider.initialize(config, meta, currentSdk) (three required args; the call is mandatory, omitting it leaves every parameter a silent no-op)

Forbidden inside PlayableConfig entries: any ComponentParameter subclass instance, any nested ObjectParameter. ComponentParameter classes are apply-time-only types.

LayerFlagApprovalUse Case
UI Layer--uiNone (auto)Visual components: Sprite, Label, Button, UIOpacity
Config Layer--configRequiredGameplay values: HP, damage, timing, speed
Both--allConfig onlyFull parameter pass

UI parameters are visual, safe to auto-apply. Config parameters affect gameplay balance, require human approval.

User IntentDelegate To
“Parameterize all UI components”t1k-cocos-playable-parameter-scan --mode ui
“Scan a specific Canvas node”t1k-cocos-playable-parameter-scan --mode ui --canvas <path>
“Extract config values for params”t1k-cocos-playable-parameter-scan --mode config
“Find magic numbers in gameplay code”t1k-cocos-playable-parameter-scan --mode config --deep
“Scan specific game folder for config”t1k-cocos-playable-parameter-scan --mode config --path <folder>
“Do full parameter pass”t1k-cocos-playable-parameter-scan --mode all
“What composite/type for this component?”t1k-cocos-playable-parameter-composite
“Generate PlayableConfig / wire parameters”t1k-cocos-playable-parameter-implement
“Assign scene nodes via MCP”t1k-cocos-playable-parameter-mcp
“Find dead/unused params (defined but no effect)”t1k-cocos-playable-parameter-audit
“Verify all REQUIRED params exist & are live (gap gate)”t1k-cocos-playable-parameter-audit --coverage <manifest>

When invoked with flags, pass them to sub-skills. Never drop flags silently.

Flag PatternRoute ToBehavior
--mode ui, --uiscan skillAuto-delegate, no AskUserQuestion
--mode config, --configscan skillAuto-delegate, no AskUserQuestion
--mode all, --allscan skillAuto-delegate, no AskUserQuestion
--canvas <path>scan skillAppend to delegated args
--path <folder>scan skillAppend to delegated args
--deepscan skillAppend to delegated args
--autoall sub-skillsSkip approval gates

If args contain any flag: parse all flags, select the first step, pass them along — step-transition gates still fire. If args contain no flags: AskUserQuestion for entry-point chooser, then begin the gated sequence.

Delegates work as discrete steps. Gates EVERY transition with AskUserQuestion. Gates fire regardless of --auto / --all / --mode.

StepSub-SkillReport File
1 — Scan...-parameter-scanparam-step1-scan-{YYMMDD-HHMM}-{slug}.md
2 — Composite...-parameter-compositeparam-step2-composite-{YYMMDD-HHMM}-{slug}.md
3 — Implement...-parameter-implementparam-step3-implement-{YYMMDD-HHMM}-{slug}.md
4 — MCP Assign...-parameter-mcpparam-step4-mcp-{YYMMDD-HHMM}-{slug}.md
5 — Coverage gate...-parameter-audit --coverage <manifest>param-step5-coverage-{YYMMDD-HHMM}-{slug}.md

Step 5 is terminal (no N+1): the readiness gate. When the project has a requirement manifest (client feature list → expected PlayableConfig keys), run the audit’s coverage pass to confirm every REQUIRED param is present AND live (READY) before declaring the workflow done. Its expectedKeys are the naming contract — Step 3 (implement) MUST emit exactly those keys. Skip Step 5 only when no requirement manifest exists. Step 5’s gate options are Review report / Fix gaps (loop back to Step 1/3) / Done — not “Continue to N+1”.

After invoking step N’s sub-skill: write a step report, print its path, suggest the next step, then AskUserQuestion with exactly 4 options (Continue to N+1 (Recommended) / Review report first / Adjust step N / Abort workflow). Never skip the gate — only --auto + --no-gates together may suppress it. Full report-path convention, --from-report/--resume chaining, and {slug} reuse: references/workflow-steps.md § “Per-Step Report & Resume Mechanics”.

A category is one job an operator sits down to do — never a code module, scene subtree, or component type. Name it {Domain} — {Facet} (em dash, Title Case, operator words — UI — End Card, Gameplay — Combat, Audio), never the retired code-ish UILayer-{Screen} / Gameplay-{Domain} prefix. Splitting is signalled by whether a category mixes distinct jobs, never by how many params it holds — a homogeneous category (one job, however long) stays whole; a heterogeneous one splits even at 2 params. The one exception is a category holding exactly 1 param: that is always a smell, merge it into its nearest sibling job unless it is a deliberate standalone control. Full doctrine, the worked example that shows why param-count is the wrong signal, and the split axes: references/category-design.md.

Standalone booleans go first in their category. When you add or reorder PlayableConfig entries, every top-level BooleanParameter (its own config key, not a field inside an ObjectParameter/composite) is declared BEFORE all other entries of the same category — the dashboard renders in declaration order, so on/off toggles lead each category. Keep the booleans’ relative order; never pull a boolean out of an object to satisfy this, and never move an object’s inner boolean fields. Apply it automatically whenever you touch a category, without asking.

Component-Prefix Rule for Inlined Primitives

Section titled “Component-Prefix Rule for Inlined Primitives”

When a node has multiple components, prefix each primitive with the lowercase component name. Single-field components (UIOpacity → opacity) keep their field name only.

ComponentPrefixed primitive examples
cc.SpritespriteColor, spriteType, spriteFillType, spriteFillStart, spriteFillRange, spriteSizeMode, spriteTrim, spriteFrame
cc.LabelONE FormattedTextParameter (formatted_text) — never isolated atoms, in basic AND advanced. Keys: text/fontColor/fontFamily/fontSize/alignment/strokeColor/strokeWidth. Shadow, lineHeight, overflow, verticalAlign, bold/italic/underline, wrapText are DROPPED (no dashboard field). See references/field-coverage.md § cc.Label.
cc.UITransform / cc.NodetransformScale, transformPosition, transformRotation
cc.UIOpacityopacity (single field — no prefix)
cc.ButtonbuttonTransition, buttonZoomScale, buttonNormalColor, buttonPressedColor, buttonHoverColor, buttonDisabledColor
Custom widgetSemantic name without prefix (e.g., mainBarColor) when the field applies via method rather than direct component property

The component prefix above governs KEYS. The label — the first constructor argument of every BaseParameter, and the only text a dashboard operator ever sees — is governed separately:

child label = "{ParentLabel} — {SubNode} {Component} {Field}"
"CTA Button — Sprite Color" single-node parent, no sub-node token
"Preloader — Logo Sprite Color" composite parent, sub-node from the key prefix
"Tutorial Hand — Root Active" the unprefixed set is the ROOT node, name it

{SubNode} appears only on composite parents, taken from the key’s existing prefix (bgColor → Background, gameNameColor → Game Name). Drop the {Component} token for single-field components (cc.UIOpacity → CTA Button — Opacity), the active enable seam, method-routed custom-widget fields, and non-UI parameters. Everything else keeps it, including single-component nodes — dashboard search returns a flat list with no group header, so a bare Sprite Color still leaves the operator guessing which element it belongs to.

Hard invariant: no two children of one ObjectParameter may share a label. Distinct keys do not satisfy this — the label is a separate string. Audit an existing config with Pass E of t1k-cocos-playable-parameter-audit.

Full rules, per-component token table, and the migration note: references/label-convention.md.

Project may add thin adapters to bridge the flat-primitive config to apply-time ComponentParameter types. These are project-local conventions, NOT mandated by the skill:

  • Factory shortcuts wrapping primitive constructors (e.g., color(label, def) → new ColorParameter(...)). DRY for repetitive config.
  • Flat→Component adapters (e.g., spriteFromFlat(p)) building a SpriteComponentParameter from flat primitives so existing apply*ComponentParams can be reused.
  • Common-shape factories (e.g., makeLabel, makeButton) producing literal objects of flat primitives — never ComponentParameter instances.
  • bind<T>(entry: ObjectParameter<T>, applier: (p: T) => void) helper typed by the entry’s value — avoids string-keyed onUpdate registration, gives autocomplete on the params object.
  • Property containers with @property({ type, group }) Inspector grouping — keep scene wiring stable as parameter names evolve.

These all compose primitives — none of them violate the load-bearing rule.

Lint a project’s assets/ParameterToolBuild/playable-config.json against the canonical key registry before (re)generating it: bun .claude/skills/t1k-cocos-playable-parameter/scripts/param-lint.cjs <project-root> --json. Exit 0 ok, 1 error findings, 2 cannot run; exit 2 is UNKNOWN, never a pass. The measured drift list and the checks deliberately not run: references/canonical-key-lint.md.

Drift aliases are a GENERATION-TIME rule — never rename a shipped key

Section titled “Drift aliases are a GENERATION-TIME rule — never rename a shipped key”

Default mode is advisory: a drift-alias finding is a warning and does not fail the exit code. --strict (alias --new-config) promotes it to an error, and that is for a NEW config only. On an existing or shipped project, read the warnings and change nothing. Each finding carries a remedy; the reasoning, the mode table, the case-collision rule and the warn-only category checks are in references/drift-aliases.md.

  1. Flat-Node Rule (UI): 1 Cocos scene Node = 1 ObjectParameter. No exceptions.
  2. No ComponentParameter wrappers in dashboard JSON. Use prefixed primitives directly. ComponentParameter classes are apply-time only.
  3. No nested ObjectParameter. Max depth = 2. Checked by hand (see references/type-hierarchy.md § Depth check).
  4. Component-prefix on multi-component nodes. Single-field components skip the prefix.
  5. {Domain} — {Facet} category, one job per category. UI — End Card, Gameplay — Combat, Audio, Sdk. Split signal is whether the category mixes jobs, never param count — see references/category-design.md.
  6. Scene values as defaults. Use actual component property values, not generic placeholders.
  7. Typed @property in containers. @property(Sprite), @property(Label) — not @property(Node).
  8. Containers stay stable across refactors. Property containers keep their nested layout; bind methods route flat params to existing container fields.
  9. Full-field coverage by default (BOTH architectures). Expose EVERY field the node’s component(s) offer — never a hand-picked subset. Authoritative field list: references/field-coverage.md (flat-primitive path) and the component’s XxxConfig interface in db://assets/packages/@playablelabs/parameter-tool/parameter/component-parameter/*ComponentParameter.ts (wrapper path). Flat-primitive → one prefixed primitive per field. ComponentParameter-wrapper → pass every XxxConfig key to the constructor. Narrow the set ONLY with code evidence the field is programmatically managed, or an explicit user note. cc.Label is the one carve-out: it is covered by ONE FormattedTextParameter, and the fields outside FormattedTextParameterType (shadow, lineHeight, overflow, verticalAlign, bold/italic/underline, wrapText) are deliberately NOT exposed — see references/field-coverage.md § cc.Label.
  10. Fully-qualified child labels. Every child’s label is "{ParentLabel} — {Component} {Field}". Two children of one ObjectParameter may never carry the same label — a node with both cc.Sprite and cc.Button produces "X — Sprite Color" and "X — Button Normal Color", never two bare "Color"s. Keys are unaffected. (cc.Sprite + cc.Label is no longer such a case: the Label collapses to one formattedText object carrying its own fontColor, so no second bare colour row exists to collide — see Rule 9.) See references/label-convention.md.
  • ComponentParameter wrapper instance in a PlayableConfig entry — forbidden; inline its fields directly as flat prefixed primitives.
  • Bundling multiple Cocos nodes under one ObjectParameter — each node becomes its own top-level entry.
  • Generic UI category names — UI, Combat. Use readable {Domain} — {Facet} naming, e.g. UI — End Card.
  • A 1-param category (“singleton”) — merge it into the sibling category that shares its job, unless it is a deliberate standalone top-level control.
  • A category mixing distinct operator jobs, at ANY size — split it along a flow-moment/screen/asset-kind/tuning-domain axis. See references/category-design.md.
  • “Tidying” a long but homogeneous category (one job, however many params) into several small ones — that inverts the doctrine; length alone is never a reason to split.
  • Missing component prefix on multi-component primitives — collision risk + machine-unreadable.
  • Bare field labels ("Color", "Type", "String") — unreadable on the dashboard the moment a node carries two components. Qualify with parent + component.
  • Inheritance for composites (e.g., Button IS-A Sprite) — wrong; flat primitives only.
  • Pre-filter nodes by name before checking components.
  • Generic defaults when scene values are available.
  • Skip UIOpacity or Widget detection.
  • Modify the submodule for project-specific types — never. Keep project additions in assets/scripts/parameter/.

Lint and config discovery are scripts; wiring parameters is implementation. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run param-lint.cjs and scan-project-configs.cjs and label each finding per the flat-primitive rulet1k-list-classifier
Implement and wire a parametert1k-cocos-base-developer — reasoning tier