t1k:cocos:playable:parameter-implement

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	playable
Version	0.5.6
Effort	high
Tools	—

Keywords: bind, codegen, flat-primitive, generate, implement, ParameterController, PlayableConfig, wire

How to invoke

/t1k:cocos:playable:parameter-implement
[scan-report-json] or [node-list]

---

Cocos Playable Parameter Implementation

Code generator for the flat-primitive parameter architecture. Accepts scan output and produces TypeScript parameter definitions + controller wiring. Every generated ObjectParameter contains primitive BaseParameter instances only — no ComponentParameter wrappers, no nested ObjectParameter. See parent skill ## The Load-Bearing Rule.

Decision Tree

Intent	Action	Reference
Generate PlayableConfig entries	One top-level ObjectParameter per scanned node, prefixed primitives	references/code-templates.md
Wire entries into ParameterController (≤20 entries)	Flat-dump @property + bind<T> per entry	references/code-templates.md
Wire entries into ParameterController (>20 entries OR ≥3 groups)	Sectioned controller — one section class per group	references/sectioned-controller.md
Optional terser apply code	Project-side FlatParamHelpers (spriteFromFlat, …)	references/code-templates.md § Adapters

Output Files

1. PlayableConfig.ts — Top-level ObjectParameter entries; bodies contain prefixed primitive BaseParameter instances only.
2. ParameterController.ts — Either flat-dump (≤20 entries) or sectioned (>20 entries) shape. Reconstructs ComponentParameter from flat primitives at apply-time.
3. (optional) FlatParamHelpers.ts — Project-side adapters bridging flat primitives → ComponentParameter.

Shape Selection Rule

total entries ≤ 20  AND  subtree groups ≤ 2   →  flat-dump controller
total entries > 20  OR   subtree groups ≥ 3   →  sectioned controller (MANDATORY)
any single section > 15 entries               →  sub-split by functionality (MANDATORY)
any single section ≤ 3 entries                →  consider merging into adjacent or `Misc`

Section boundaries: start by subtree (UICanvas/{Subtree}/...), then sub-split functional clusters within any subtree exceeding 15 entries. Functional cluster signals and anti-criteria: references/sectioned-controller.md.

Codegen Rules

• Use typed @property(Sprite), @property(Label) for visual components; @property(Node) only when the apply target is the node itself (Button, UIOpacity).
• Direct component refs only — no getComponent in the controller.
• One prefixed primitive per Cocos component field present on the node.
• Full-field coverage by default. Emit EVERY field the component exposes — never a hand-picked subset. Flat-primitive path: one primitive per field in field-coverage.md. Wrapper path (ObjectParameter<XxxComponentParameter>): pass EVERY key of the component’s XxxConfig interface (read it from db://assets/PlayableParamterTool/parameter/component-parameter/XxxComponentParameter.ts). Narrow ONLY with code evidence or an explicit user note. See parent skill Critical Rule 9.
• Use actual scene values from the scan report’s primitiveShape as primitive defaults.
• One scanned node → one top-level ObjectParameter. Max depth = 2.
• Component-prefixed primitives on multi-component nodes (spriteColor, labelString, buttonTransition). Single-field components skip the prefix (opacity).
• NEVER generate nested ObjectParameter, ComponentParameter instances inside config, or CustomParameter.ts wrappers (retired in v6).
• At >20 entries OR ≥3 subtree groups, MUST emit sectioned controller — see references/sectioned-controller.md.

Naming Conventions

• PascalCase entry names: CtaButton, TitleLabel, BackgroundSprite, HPBarPlayerBar.
• Multi-node logical groupings: prefix child names with the grouping (HPBarPlayer{Bar|Bg|Label}, RewardCard1{Card|Icon|Amount}).
• Categories: UI uses UILayer-{Screen}; non-UI uses Gameplay-{Domain} / Audio / Sdk.
• Sectioned controller: section class ParameterController_{Section}Section, controller field {section}Section (camelCase).

References

• references/code-templates.md — Full PlayableConfig.ts + flat-dump ParameterController.ts templates, optional FlatParamHelpers convention.
• references/sectioned-controller.md — Sectioned controller template, group-metadata contract, section-boundary rules.
• Parent skill references/type-hierarchy.md — Two-stage model (config-stage primitives vs apply-stage ComponentParameter).
• Parent skill references/field-coverage.md — Per-component prefixed-primitive tables.
• Parent skill references/workflow-steps.md — End-to-end steps + doctor.

Gotchas

• Primitive names must match host macro replacement exactly — case-sensitive.
• Every ObjectParameter needs a matching @property (or container reference) AND a bind call. A scanned node not wired in the controller will silently never apply.
• Async sprite loading: binder tracks promises via binder.waitForAsync(); fire AllAsyncParametersReadySignal after it resolves.
• Do not generate store-link parameters — those are SDK-managed.
• The cast (data as ObjectParameter<T>) inside bind<T> is required because the submodule’s BaseParameter.onUpdate signature is (arg0: BaseParameter) => void. Don’t drop the cast.
• ComponentParameter constructors take an empty {}; assign fields directly afterward.
• Cherry-picking component fields is the most common under-qualification defect. A LabelComponentParameter emitted with only { string, color, fontSize } silently drops lineHeight/overflow/align/bold/italic/underline/outline/shadow/wrapText. Absent a specific note, emit ALL fields the XxxConfig interface (or field-coverage.md table) offers. Verify against the interface, not from memory.
• Flat-dump @property at scale is unreadable. Validate generator output: at >20 entries it MUST be sectioned per references/sectioned-controller.md. Verify with grep -c '^class ParameterController_.*Section'.