t1k:cocos:playable:parameter-implement
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: bind, codegen, flat-primitive, generate, implement playable parameter, ParameterController, PlayableConfig, wire
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:parameter-implement[scan-report-json] or [node-list]Cocos Playable Parameter Implementation
Section titled “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
Section titled “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 |
| Assign / split parameter categories | One job per category; split only when a category mixes distinct operator jobs — size is not the signal | Parent skill t1k-cocos-playable-parameter/references/category-design.md |
Output Files
Section titled “Output Files”PlayableConfig.ts— Top-levelObjectParameterentries; bodies contain prefixed primitiveBaseParameterinstances only.ParameterController.ts— Either flat-dump (≤20 entries) or sectioned (>20 entries) shape. ReconstructsComponentParameterfrom flat primitives at apply-time.- (optional)
FlatParamHelpers.ts— Project-side adapters bridging flat primitives →ComponentParameter.
Shape Selection Rule
Section titled “Shape Selection Rule”total entries ≤ 20 AND subtree groups ≤ 2 → flat-dump controllertotal 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
Section titled “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
getComponentin 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’sXxxConfiginterface (read it fromdb://assets/packages/@playablelabs/parameter-tool/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
primitiveShapeas primitive defaults. - One scanned node → one top-level
ObjectParameter. Max depth = 2. - Component-prefixed primitives on multi-component nodes (
spriteColor,buttonTransition). Single-field components skip the prefix (opacity). Acc.Labelis not expanded at all — oneformattedTextkey holding aFormattedTextParameter. - A font field applies through
FontService.applyFont— NEVER a hand-written font applier, and never a barelabel.fontFamily = value.fontFamilyis the one Label field NO package applier covers:applyLabelComponentParamsandFormattedTextParameter.applyboth assignlabel.fontFamilydirectly, which resolves system families only. A custom face inresources/font/never loads,label.font/useSystemFontare never touched, and the label silently keeps the typeface it was authored with. EmitFontService.applyFont(this.<labelRef>, value)and drain its promise beforeAllAsyncParametersReadySignalfires. Seereferences/code-templates.md§ Font and skillt1k-cocos-playable-font-service. - NEVER generate nested
ObjectParameter,ComponentParameterinstances inside config, orCustomParameter.tswrappers (retired in v6). - At >20 entries OR ≥3 subtree groups, MUST emit sectioned controller — see
references/sectioned-controller.md. - Every entry MUST carry a category drawn from the declared
Categoriesconst — never emit an entry with no category, and never inline a raw category string at the call site. Assigning (or reusing) the category is a mandatory codegen step, not an afterthought: before emitting a new entry, decide which existingCategoriesmember is the same operator job, or declare a new one. Full doctrine: parent skillt1k-cocos-playable-parameter/references/category-design.md.
Naming Conventions
Section titled “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: readable
{Domain} — {Facet}(em dash, Title Case) —UI — End Card,Gameplay — Combat,Audio. Replaces the retired code-ishUILayer-{Screen}/Gameplay-{Domain}prefix. Full naming rules, the homogeneous-vs-heterogeneous split signal, and the worked example: parent skillt1k-cocos-playable-parameter/references/category-design.md. - Sectioned controller: section class
ParameterController_{Section}Section, controller field{section}Section(camelCase). - Child
label(the dashboard-facing string, first constructor arg):"{ParentLabel} — {Component} {Field}"— e.g.new ColorParameter("CTA Button — Sprite Color", "#FFFFFF"). Drop the component token only for single-field components (… — Opacity), theactiveenable seam, method-routed custom-widget fields, and non-UI params. Keys are unaffected. Full rules: parent skillt1k-cocos-playable-parameter/references/label-convention.md.
References
Section titled “References”references/code-templates.md— FullPlayableConfig.ts+ flat-dumpParameterController.tstemplates, optionalFlatParamHelpersconvention.references/sectioned-controller.md— Sectioned controller template, group-metadata contract, section-boundary rules.- Parent skill
t1k-cocos-playable-parameter/references/type-hierarchy.md— Two-stage model (config-stage primitives vs apply-stageComponentParameter). - Parent skill
t1k-cocos-playable-parameter/references/field-coverage.md— Per-component prefixed-primitive tables. - Parent skill
t1k-cocos-playable-parameter/references/workflow-steps.md— End-to-end steps + doctor. - Parent skill
t1k-cocos-playable-parameter/references/category-design.md— Category naming, the homogeneous/heterogeneous split signal, and theparam-lint.cjschecks that back it.
Hard rules
Section titled “Hard rules”- Primitive names must match host macro replacement exactly — case-sensitive.
- Every
ObjectParameterneeds a matching@property(or container reference) AND abindcall. A scanned node not wired in the controller will silently never apply. - Async sprite loading: binder tracks promises via
binder.waitForAsync(); fireAllAsyncParametersReadySignalafter it resolves. - Do not generate store-link parameters — those are SDK-managed.
- The cast
(data as ObjectParameter<T>)insidebind<T>is required because the submodule’sBaseParameter.onUpdatesignature is(arg0: BaseParameter) => void. Don’t drop the cast. ComponentParameterconstructors take an empty{}; assign fields directly afterward.- Cherry-picking component fields is the most common under-qualification defect. Absent a specific note, emit ALL fields the
XxxConfiginterface (orfield-coverage.mdtable) offers. Verify against the interface, not from memory. cc.Labelis the one component that is NOT expanded into atoms. Emit exactly oneFormattedTextParameterper Label —{ text, fontColor, fontFamily, fontSize, alignment, strokeColor, strokeWidth }— in both the basic and advanced profiles. Do NOT also emitlabelString/labelColor/labelFontSize/labelOutline*beside it, and do NOT emit atoms for label fields the formatted-text shape lacks (shadow, lineHeight, overflow, verticalAlign, bold/italic/underline, wrapText) — the dashboard cannot render them, so they land as undefined controls. Prefer the package templateFormattedTextComponentParameter+applyFormattedTextComponentParams(parameter/component-parameter/FormattedTextComponentParameter.core) — it takes theLabelConfigseed shape, flattens throughfields()as one row, bakes the non-formatted fields, and derivesenableOutlinefromstrokeWidth > 0. Only hand-roll the mapping when the vendored tool lacks it. Parent skillt1k-cocos-playable-parameter/references/field-coverage.md§cc.Label.FontService.applyFontis the ONLY sanctioned font applier — do NOT write your own. Generating a localapplyFont/setFont/loadFonthelper, or assigninglabel.fontFamilystraight from the param value, ships a dashboard font control that moves a string and changes nothing on screen for every custom face.FormattedTextParameter.apply()does NOT close this gap: its field set carriesfontFamilybut nofontand nouseSystemFont, so the formatted-text path needs the same follow-up call. Import the package one:It isimport { FontService } from "db://assets/packages/@playablelabs/game-foundation/ui/utils/FontService";// inside onUpdate, AFTER the formatted-text / label apply:this._pendingFonts.push(FontService.applyFont(this.titleLabel, p.formattedText.fontFamily));async, andParameterBinderexposes no public way to enrol a promise (_asyncPromisesis private; onlycomponent()/formatted()feed it). So a hand-writtenonUpdatemust hold its own pending array and drain it besidebinder.waitForAsync()— template inreferences/code-templates.md§ Font. An un-drained call racesAllAsyncParametersReadySignaland the first frame renders the old face.- Two children of one
ObjectParametermay never share a label. Distinct KEYS do not save you — the label is a separate string and the atoms default to generic ones. Shipped defect:CtaButtonemittedspriteColorandlabelColor(distinct keys) with labels"Color"and"Color", so the dashboard showed two identical rows and the operator could not tell the button tint from the text colour. Before emitting an entry, check its child labels are pairwise unique. - Flat-dump @property at scale is unreadable. Validate generator output: at >20 entries it MUST be sectioned per
references/sectioned-controller.md. Verify withgrep -c '^class ParameterController_.*Section'. - A 1-param category is a smell; a mixed category is a smell at ANY size — count alone proves neither. Mirrors
param-lint.cjs’scategory-singleton(an isolated entry — merge it into the sibling that shares its job, unless it is a deliberate standalone top-level control) andcategory-stray-param(an entry whose label reads as another domain’s — e.g.Sound On First Touchsitting inDatawhile anAudiocategory already exists two groups away) checks, both warn-only. Do not “fix” a long but homogeneous category (one job, however many params) by splitting it — that is the inverse defect the doctrine explicitly calls out. Seeskills/t1k-cocos-playable-parameter/references/category-design.md.