t1k:cocos:playable:parameter-mcp
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: assign, batch, mcp assign, uuid assign
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:parameter-mcp[assign|batch-set|health]Cocos Playable Parameter MCP
Section titled “Cocos Playable Parameter MCP”Editor bridge for assigning scene nodes to generated parameter @property references. Process-oriented; agnostic to the parameter shape produced by the implement step (works for both top-level entries and grouped containers).
Decision Tree
Section titled “Decision Tree”| Intent | Action |
|---|---|
| “Assign scene nodes to my parameters” | Batch MCP assignment workflow |
| “Check if MCP is connected” | Health check + diagnostics |
| “Batch set component properties” | manage_component set_properties_batch |
MCP Endpoint
Section titled “MCP Endpoint”references/mcp-endpoint.md is the SSOT for the endpoint — other Cocos skills reference it
rather than repeating the literal. Read it before any probe. In short:
- Resolve the port; never assume it.
--mcp-url→$COCOS_MCP_URL→<project>/settings/mcp-server.json→http://127.0.0.1:3000/mcp(last resort). The port is per project;3000is only the extension’s shipped default. - A refused probe does not mean the editor is closed. Wrong port, then server not started
(
autoStartdefaults tofalse), then closed — in that order. Never silently downgrade to fallback mode on a refused probe. - Liveness is proved by a tool call returning at all, not by
curland not by any field in the payload —manage_server get_status’sserverRunningis a hardcoded literal. manage_serverreports the editor server port (745x), not the MCP port.
Requires Cocos Creator Editor open and the MCP server started in its panel.
The writes below are executed by an editor-writing agent
Section titled “The writes below are executed by an editor-writing agent”Everything in this skill that ends in a manage_* write — set_property,
set_properties_batch, attach_script — is a call shape, not a grant this skill or its
activating agent holds. The write is run by t1k-cocos-base-developer (feature work) or
t1k-cocos-base-editor-operator (editor-only/repair), the agents that own mcp__cocos-creator__*, the per-project preflight, and the save → reimport → read-from-disk
protocol (t1k-cocos-base-editor-mcp-truth). If you are activating this skill without that grant,
hand the assignment to one of them instead of driving the HTTP endpoint yourself — going around it
through curl writes to the editor’s memory with no read-back and no identity check.
Windows Compatibility
Section titled “Windows Compatibility”- Single-line
curlonly. No\continuations. - Use
$TEMP(or%TEMP%) not/tmp/. - Escape JSON carefully for PowerShell/Bash. For multi-line bodies, write to a temp file and pass
-d @path.
Assignment Workflow
Section titled “Assignment Workflow”Step 1: Read ParameterController.ts → enumerate @property declarationsStep 2: Match each @property name to a scene node by name / path / fuzzyStep 3: Batch call manage_component set_properties_batch for the controller's component, one property entry per @propertyStep 4: Save sceneStep 5: Verify assignments via manage_component get_allOptimized 3-Call Pattern
Section titled “Optimized 3-Call Pattern”# 1. Find ParameterController node UUIDmcp: manage_node find "ParameterController"-> { "uuid": "abc123...", "name": "ParameterController", "path": "Canvas/ParameterController" }
# 2. Batch set ALL @property references in one callmcp: manage_component set_properties_batch { "nodeUuid": "abc123...", "componentType": "<ParameterController type hash>", "properties": [ {"property": "mainCamera", "propertyType": "node", "value": "<camera-uuid>"}, {"property": "ctaButtonSprite", "propertyType": "component", "value": "<sprite-uuid>"}, {"property": "titleLabel", "propertyType": "component", "value": "<label-uuid>"}, {"property": "endCardRootNode", "propertyType": "node", "value": "<node-uuid>"} ]}
# 3. Save scenemcp: manage_scene saveUUID Matching Algorithm
Section titled “UUID Matching Algorithm”| Order | Match | Example |
|---|---|---|
| 1 | Exact name match | @property ctaButton → node named ctaButton |
| 2 | Path suffix match | Canvas/UI/Btn_CTA matches Btn_CTA |
| 3 | Strip type-suffix + fuzzy | ctaButtonSprite → strip Sprite → match ctaButton |
| 4 | Levenshtein on node name | Last resort |
Ambiguous matches → escalate to user via AskUserQuestion.
Property Container Pattern (OPTIONAL Project Convention)
Section titled “Property Container Pattern (OPTIONAL Project Convention)”When the controller uses property containers (@property({ type: SomeContainerClass, group: 'Some Group' })) to organize references by screen, the MCP assignment still operates on the controller node — the container is an in-component nested type, not a separate node. Assign each container’s inner fields by path:
mcp: manage_component set_properties_batch { "nodeUuid": "<controller-uuid>", "componentType": "<ParameterController type hash>", "properties": [ {"property": "endCard.bgSprite", "propertyType": "component", "value": "<sprite-uuid>"}, {"property": "endCard.titleLabel", "propertyType": "component", "value": "<label-uuid>"}, {"property": "endCard.continueButton", "propertyType": "node", "value": "<node-uuid>"} ]}If the MCP doesn’t support dotted-path property keys, fall back to per-field set_property calls in a loop.
attach_script Verification (CRITICAL — avoid duplicate components)
Section titled “attach_script Verification (CRITICAL — avoid duplicate components)”attach_script frequently reports FAIL for user scripts even when the attach actually succeeded. The false negative happens because manage_component get_all lists components by their script cid, not by class name — so a post-attach lookup by class name finds nothing and the tool concludes failure.
Do NOT retry on a reported FAIL. Each retry attaches another copy → duplicate components on the node.
Verify the attach succeeded by one of these instead:
manage_node get_infoand look for a component whose name isnode<ClassName>(the editor’s display form for a user script component), OR- match on the script cid returned by
get_allrather than the class name.
Compilation gotcha: a newly added component class only compiles — and therefore only becomes attachable / resolvable — when the Cocos Creator editor window is focused. If a freshly created script class isn’t found, focus the editor to trigger compilation before re-checking (still do NOT re-issue attach_script).
Fallback: Direct Scene JSON Edit
Section titled “Fallback: Direct Scene JSON Edit”Only when the MCP is genuinely unavailable and the editor is closed on that asset — an
out-of-band disk write against a scene the editor has open is overwritten by the next editor save,
silently. Per t1k-cocos-base-editor-mcp-truth (e): do the disk edit with the editor closed, or
reimport afterwards, never interleaved with an MCP write on the same asset.
- Parse
MainScene.sceneJSON array. - Find
ParameterControllercomponent by type hash. - Find target node IDs from the scan report’s
nodes[].uuid(or__id__in the scene JSON). - Update null properties to
{ "__id__": targetNodeId }. - Check
cc.TargetOverrideInfoentries before reporting any property as null (per parent skillt1k-cocos-playable-parameter/references/discovery-helpers.md§ Scene JSON Property Resolution). - Save the scene file.
- If the editor was open at any point, reimport the asset and re-read it from disk to confirm the write survived before reporting it.
References
Section titled “References”references/mcp-endpoint.md— SSOT for port resolution, refused-probe triage, and what actually proves liveness- Parent skill
t1k-cocos-playable-parameter/references/mcp-assignment.md— MCP node→property assignment patterns - Parent skill
t1k-cocos-playable-parameter/references/discovery-helpers.md§ Scene JSON Property Resolution —TargetOverrideInforules
Hard rules
Section titled “Hard rules”- MCP must be running in Cocos Editor before any assignment.
- A refused
/healthon3000does NOT mean the editor is closed. The MCP port is per project (settings/mcp-server.json);3000is only the shipped default. Resolve the port first, and confirm with an MCP tool call, before concluding MCP is unavailable — seereferences/mcp-endpoint.md. Never skip MCP verification silently on a refused probe. - A tool call proves liveness by returning, not by what it says.
manage_server get_statusreportsserverRunning: trueunconditionally — it is a hardcoded literal, neverfalse. Do not quote it as evidence. manage_server get_status/get_portreturns the editor server port (745x), not the MCP port. It cannot build your/mcpURL.- Windows
curldoes not support multi-line JSON bodies easily — use temp files. - Node UUIDs change when scenes are re-saved. Re-run assignment after scene edits.
- Batch size: keep under 20 properties per
set_properties_batchcall to avoid MCP timeouts. @property(Sprite)vs@property(Node): the MCPpropertyTypemust match. Usecomponentfor typed component refs (@property(Sprite),@property(Label)); usebunfor@property(Node).- Property containers do NOT change the host node — assignments still target the controller node, just with dotted-path or per-field property names.
attach_scriptFAIL is usually a false negative — never retry it (each retry adds a duplicate component). Verify viaget_infonamenode<ClassName>or the script cid. New component classes only compile when the editor window is focused. See the “attach_script Verification” section above.- Array-typed
@property(cc.Node[],cc.Sprite[], any@property([Type])) is pin-relative. Before #139d687372anodeArray/componentArraywrite throwsCannot read properties of undefined; wire those elements in the Cocos Editor manually, or set per-index single refs only if the slots already exist. From #139 pass the whole array withnodeArray/componentArray, andassetArray(#129+) for an asset array such asPrefab[]. Read the saved array back from disk. An array on a component inside a prefab instance is a separate wall on every pin:t1k-cocos-base-editor-mcp-truthskills/t1k-cocos-base-editor-mcp-truth/references/known-lies-table.md. @property(SpriteFrame)needs the sprite-frame sub-asset UUID, not the texture sub-asset UUID. A single imported PNG generates two sub-asset UUIDs in its.metasubMetas: one for thesprite-frameimporter and one for thetextureimporter. These UUIDs differ (e.g....@f9941vs...@6c48a) and are easy to confuse when copy-pasting from a scan or asset list. Before wiring aSpriteFrameslot, read the image’s.metafile and confirm which sub-asset entry has"importer": "sprite-frame"— binding the texture UUID into aSpriteFrameproperty silently assigns the wrong asset type.