t1k:cocos:playable:parameter-composite

Field	Value
Module	`playable`
Version	`0.5.6`
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 `references/component-registry.md`
”Group these N nodes for the dashboard”	Assign all N a shared `UILayer-{Group}` category; each stays a separate top-level entry

Submodule ComponentParameter Registry (apply-time only)

These classes live in db://assets/PlayableParamterTool/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 references/component-registry.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. The default is FULL coverage of every field the component exposes (see parent references/field-coverage.md + Critical Rule 9). E.g. the Image row below shows spriteColor/spriteFrame/opacity, but cc.Sprite also offers spriteType/spriteFillType/spriteFillStart/spriteFillRange/spriteSizeMode/spriteTrim — emit those too unless the user notes a narrower set. Trim from the full set only on explicit instruction or code evidence.

Preset	Components	Primitives Emitted
Button	Node + UITransform + Sprite + Label + Button + UIOpacity	`spriteColor`, `spriteFrame`, `labelString`, `labelColor`, `labelFontSize`, `buttonTransition`, `buttonZoomScale`, `buttonNormalColor`, `buttonPressedColor`, `opacity`
Image	Node + UITransform + Sprite + UIOpacity	`spriteColor`, `spriteFrame`, `opacity`
Text	Node + UITransform + Label + UIOpacity	`labelString`, `labelColor`, `labelFontSize`, `labelEnableOutline`, `labelOutlineColor`, `labelOutlineWidth`, `opacity`
Slider	Node + UITransform + Sprite + Slider + UIOpacity	`spriteColor`, `sliderProgress`, `sliderDirection`, `opacity`
Toggle	Node + UITransform + Sprite + Toggle + UIOpacity	`spriteColor`, `toggleChecked`, `opacity`
ProgressBar	Node + UITransform + Sprite + ProgressBar + UIOpacity	`spriteColor`, `progressValue`, `progressTotalLength`, `opacity`

Multi-Node Patterns

For logical multi-node UI (CurrencyUI, HPBar, IconLabel, RewardCard), the preset describes the collection of nodes and the implement step emits N top-level ObjectParameter entries — one per node — all sharing a category.

Pattern	Nodes	Produces (N entries)	Shared Category
CurrencyUI	root, icon (Sprite), counter (Label)	`Currency{Money}Icon` (Sprite shape), `Currency{Money}Counter` (Label shape)	`UILayer-Currency`
HPBar	bar (Sprite), bg (Sprite), text (Label)?	`HPBar{Player}Bar`, `HPBar{Player}Bg`, `HPBar{Player}Label` (if Label present)	`UILayer-HPBar` (or `UILayer-Player`/`UILayer-Enemy`)
Countdown	root, prep (Label), number (Label)	`Countdown{Prep}Label`, `Countdown{Number}Label`	`UILayer-Countdown`
IconLabel	root, icon (Sprite), text (Label)	`{Name}Icon`, `{Name}Label`	`UILayer-{Screen}`
RewardCard	card (Sprite), icon (Sprite), amount (Label)	`RewardCard{N}Card`, `RewardCard{N}Icon`, `RewardCard{N}Amount`	`UILayer-WinScreen` (or wherever it appears)

Each row is N separate ObjectParameter entries, NOT one wrapper. Category collapses them in the dashboard sidebar. Naming prefix (Currency{Money}, HPBar{Player}, etc.) keeps them adjacent in source.

Widgets Routed via Method

Custom widgets that expose colors through methods (e.g. hpBar.setBarColor(...)) use semantic names without component prefix:

Semantic primitive	Routed by
`mainBarColor`	`widget.setBarColor(p.mainBarColor.default)`
`indicatorBarColor`	`widget.setIndicatorColor(p.indicatorBarColor.default)`
`backgroundColor`	`widget.setBackgroundColor(p.backgroundColor.default)`

These live in a single ObjectParameter because they all act on the same widget instance via the widget’s API — not via direct Cocos component property writes.

Custom NodePreset Registration

Projects can register domain-specific presets that emit prefixed primitives:

import { NodePreset, NodePresetRegistry } from "PlayableParamterTool/parameter/node-preset";

const ScopePreset: NodePreset = {
    name: "Scope",
    components: ["cc.Node", "cc.UITransform", "cc.Sprite", "cc.Mask", "cc.UIOpacity"],
    primitives: {
        spriteColor: { type: "ColorParameter", default: "#FFFFFF" },
        opacity:     { type: "NumberParameter", default: 255 },
    },
    description: "Scope overlay with circular mask"
};

NodePresetRegistry.register(ScopePreset);

The advisor reads primitives to suggest the flat-primitive shape; nothing else.

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, labelString, buttonTransition); single-field components skip the prefix (opacity).
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.

References

references/component-registry.md — Full ComponentParameter field tables (apply-time)
references/preset-catalog.md — NodePreset definitions and registration patterns
Parent skill references/field-coverage.md — Component → prefixed-primitive tables
Parent skill 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.
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 (references/component-registry.md / parent field-coverage.md). Under-listing — e.g. a Label preset without lineHeight/overflow/align/outline/shadow/wrapText — produces an under-qualified config.