t1k:cocos:playable:parameter-mcp

Auto-generated

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

Field	Value
Module	playable
Version	0.5.6
Effort	medium
Tools	—

Keywords: assign, batch, cocos-creator, editor, mcp, uuid

How to invoke

/t1k:cocos:playable:parameter-mcp
[assign|batch-set|health]

---

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

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

• URL: http://127.0.0.1:3000/mcp
• Health: curl -s http://127.0.0.1:3000/health
• Requires Cocos Creator Editor to be open with MCP server enabled.

Windows Compatibility

• Single-line curl only. 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

Step 1: Read ParameterController.ts → enumerate @property declarations
Step 2: Match each @property name to a scene node by name / path / fuzzy
Step 3: Batch call manage_component set_properties_batch for the controller's
        component, one property entry per @property
Step 4: Save scene
Step 5: Verify assignments via manage_component get_all

Optimized 3-Call Pattern

# 1. Find ParameterController node UUID
mcp: manage_node find "ParameterController"
-> { "uuid": "abc123...", "name": "ParameterController", "path": "Canvas/ParameterController" }

# 2. Batch set ALL @property references in one call
mcp: 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 scene
mcp: manage_scene save

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)

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)

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_info and look for a component whose name is node<ClassName> (the editor’s display form for a user script component), OR
• match on the script cid returned by get_all rather 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

If MCP tools are unavailable, edit the scene file directly:

1. Parse MainScene.scene JSON array.
2. Find ParameterController component by type hash.
3. Find target node IDs from the scan report’s nodes[].uuid (or __id__ in the scene JSON).
4. Update null properties to { "__id__": targetNodeId }.
5. Check cc.TargetOverrideInfo entries before reporting any property as null (per references/scene-json-resolution.md in the parent skill).
6. Save the scene file.

References

• references/mcp-patterns.md — curl templates and batching
• references/windows-compatibility.md — Platform-specific quirks
• references/retry-logic.md — MCP failure handling
• Parent skill references/mcp-assignment.md — MCP node→property assignment patterns
• Parent skill references/discovery-helpers.md § Scene JSON Property Resolution — TargetOverrideInfo rules

Gotchas

• MCP must be running in Cocos Editor before any assignment.
• Windows curl does 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_batch call to avoid MCP timeouts.
• @property(Sprite) vs @property(Node): the MCP propertyType must match. Use component for typed component refs (@property(Sprite), @property(Label)); use node for @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_script FAIL is usually a false negative — never retry it (each retry adds a duplicate component). Verify via get_info name node<ClassName> or the script cid. New component classes only compile when the editor window is focused. See the “attach_script Verification” section above.