t1k:cocos:playable:parameter-composite

Field	Value
Module	`playable`
Version	`2.14.4`
Effort	`medium`
Tools	—

Keywords: component-parameter, composite, CurrencyUI, HPBar, NodePreset, parameter-types, prefixed-primitives, preset

How to invoke

/t1k:cocos:playable:parameter-composite
[preset-name] or [component-list]

Cocos Playable Parameter — Node Shape Advisor

Maps Cocos component combinations on a scanned node to prefixed-primitive shape for PlayableConfig entries. Multi-node logical groupings (HP bar, currency display, reward card) become N separate top-level ObjectParameter entries sharing one category — never wrapper classes, never nested ObjectParameter. See parent skill SKILL.md ## The Load-Bearing Rule.

Decision Tree

Intent	Action
”What primitives should this node emit?”	Match component signature → emit prefixed-primitive shape
”Create a preset for this node pattern”	Define a NodePreset (shape template only — no wrapper class)
“What fields does cc.Sprite map to?”	Look up parent skill `t1k-cocos-playable-parameter/references/field-coverage.md`
”Group these N nodes for the dashboard”	Assign all N a shared `UILayer-{Group}` category; each stays a separate top-level entry

Package ComponentParameter Registry (apply-time only)

These classes live in db://assets/packages/@playablelabs/parameter-tool/parameter/component-parameter/ and are used only inside apply*ComponentParams calls in ParameterController.onUpdate. They MUST NOT appear inside any ObjectParameter value in PlayableConfig.

ComponentParameter	Maps To	Apply Function
`TransformComponentParameter`	`cc.Node`	`applyTransformComponentParams`
`UIOpacityComponentParameter`	`cc.UIOpacity`	`applyUIOpacityComponentParams`
`WidgetComponentParameter`	`cc.Widget`	`applyWidgetComponentParams`
`SpriteComponentParameter`	`cc.Sprite`	`applySpriteComponentParams`
`LabelComponentParameter`	`cc.Label`	`applyLabelComponentParams`
`ButtonComponentParameter`	`cc.Button`	`applyButtonComponentParams`
`CameraComponentParameter`	`cc.Camera`	`applyCameraComponentParams`
`ProgressBarComponentParameter`	`cc.ProgressBar`	`applyProgressBarComponentParams`
`SliderComponentParameter`	`cc.Slider`	`applySliderComponentParams`
`ToggleComponentParameter`	`cc.Toggle`	`applyToggleComponentParams`
`LayoutComponentParameter`	`cc.Layout`	`applyLayoutComponentParams`
`MaskComponentParameter`	`cc.Mask`	`applyMaskComponentParams`

See parent skill t1k-cocos-playable-parameter/references/field-coverage.md for full field lists per class. The advisor uses these to know what fields each component CAN expose; the implement step uses these to reconstruct apply-time values from the flat primitives.

NodePreset Catalog (Shape Templates)

A NodePreset says: “this node-component signature → emit these prefixed primitives.” Presets do NOT emit wrapper classes. Preset primitive lists are illustrative MINIMUMS, not the cap — full-field coverage (parent t1k-cocos-playable-parameter/references/field-coverage.md + Critical Rule 9) is the default; trim only on explicit instruction or code evidence.

6 built-in single-node presets (Button, Image, Text, Slider, Toggle, ProgressBar), 5 multi-node patterns (CurrencyUI, HPBar, Countdown, IconLabel, RewardCard), widget-routed semantic names, and custom preset registration — see references/preset-catalog.md for the full catalog, multi-node pattern table, and registration example.

Composition Rules

One Cocos Node = one top-level ObjectParameter in PlayableConfig.
No wrapper classes (no HPBarUIParameter, no CurrencyUIParameter, no CustomParameter.ts types).
No nested ObjectParameter. Doctor-checked.
For multi-node groupings (HPBar, CurrencyUI, …): emit N separate top-level entries sharing one shared category (e.g., UILayer-HPBar).
Use component-prefixed primitives on multi-component nodes (spriteColor, buttonTransition); single-field components skip the prefix (opacity); a cc.Label collapses to one formattedText object.
Custom widgets routed via method use semantic names without prefix (mainBarColor).
Project-side adapters (e.g., spriteFromFlat(p)) bridge flat primitives → ComponentParameter at apply-time. OPTIONAL convenience; not the advisor’s concern.
Every primitive the advisor names also carries a dashboard label of "{ParentLabel} — {Component} {Field}". The Primitives Emitted column above lists KEYS; when advising, state the label alongside. A Button preset on a node labeled CTA Button emits key spriteColor with label CTA Button — Sprite Color, and key buttonNormalColor with label CTA Button — Button Normal Color — the two components’ colours must be distinguishable on screen, not just in code. The Label on that node is NOT a labelColor atom: it collapses to one formattedText object carrying its own fontColor (see the Label gotchas below). Parent skill t1k-cocos-playable-parameter/references/label-convention.md.

References

references/preset-catalog.md — NodePreset definitions and registration patterns
Parent skill t1k-cocos-playable-parameter/references/field-coverage.md — Component → prefixed-primitive tables (full field lists per class)
Parent skill t1k-cocos-playable-parameter/references/type-hierarchy.md — Two-stage model (config-stage primitives vs apply-stage ComponentParameter)

Gotchas

Primitive names must match host macro replacement exactly — case-sensitive.
Each primitive expands into one dashboard slot. Count against the network parameter cap.
RichText is a separate component from Label in Cocos 3.8+. Do not conflate.
A preset that puts two components on one node ALWAYS produces a label collision unless labels are qualified. Button (Sprite + Label) and ProgressBar/Slider/Toggle (Sprite + widget) all expose more than one color. The keys differ; the default labels do not. Always advise the fully-qualified label form.
Button transition-specific fields — COLOR transition uses the color primitives; SPRITE transition uses sprite-asset primitives. Only emit the primitives relevant to your transition mode.
NodePreset is a SHAPE TEMPLATE, not a wrapper class definition. It tells the implement step what primitives to put in the ObjectParameter body — no class generation.
N nodes ≠ 1 wrapper. A HPBar with bar+bg+text is 3 top-level entries sharing UILayer-HPBar, never one HPBarParameter instance.
Presets are minimums; full-field coverage is the default. The catalog rows enumerate the COMMON primitives, not the maximum. Absent a specific note, cover every field the component offers (parent t1k-cocos-playable-parameter/references/field-coverage.md).
cc.Label is the exception to “expand into primitives” — it collapses instead. Advise ONE FormattedTextParameter per Label (text/fontColor/fontFamily/fontSize/alignment/strokeColor/strokeWidth), in the basic AND advanced profiles alike. Never advise labelString/labelColor/labelFontSize/labelOutline* atoms, and never advise atoms for label fields the formatted-text shape lacks (shadow, lineHeight, overflow, verticalAlign, bold/italic/underline, wrapText) — the dashboard has no widget for them and they surface as undefined. Parent t1k-cocos-playable-parameter/references/field-coverage.md § cc.Label.
The Label collapse also removes the Button label-vs-sprite colour collision. With the Label as one formatted-text object, a Button node emits spriteColor (tint) and one formatted-text entry — there is no second bare color row to disambiguate.