Skip to content

t1k:cocos:playable:parameter-mcp

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: assign, batch, mcp assign, uuid assign

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

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).

IntentAction
“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

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; 3000 is only the extension’s shipped default.
  • A refused probe does not mean the editor is closed. Wrong port, then server not started (autoStart defaults to false), 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 curl and not by any field in the payload — manage_server get_status’s serverRunning is a hardcoded literal.
  • manage_server reports 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.

  • 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.
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
Terminal window
# 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
OrderMatchExample
1Exact name match@property ctaButton → node named ctaButton
2Path suffix matchCanvas/UI/Btn_CTA matches Btn_CTA
3Strip type-suffix + fuzzyctaButtonSprite → strip Sprite → match ctaButton
4Levenshtein on node nameLast 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:

Terminal window
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_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).

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.

  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 parent skill t1k-cocos-playable-parameter/references/discovery-helpers.md § Scene JSON Property Resolution).
  6. Save the scene file.
  7. 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/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 — TargetOverrideInfo rules
  • MCP must be running in Cocos Editor before any assignment.
  • A refused /health on 3000 does NOT mean the editor is closed. The MCP port is per project (settings/mcp-server.json); 3000 is only the shipped default. Resolve the port first, and confirm with an MCP tool call, before concluding MCP is unavailable — see references/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_status reports serverRunning: true unconditionally — it is a hardcoded literal, never false. Do not quote it as evidence.
  • manage_server get_status/get_port returns the editor server port (745x), not the MCP port. It cannot build your /mcp URL.
  • 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 bun 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.
  • Array-typed @property (cc.Node[], cc.Sprite[], any @property([Type])) is pin-relative. Before #139 d687372 a nodeArray/componentArray write throws Cannot 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 with nodeArray/componentArray, and assetArray (#129+) for an asset array such as Prefab[]. 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-truth skills/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 .meta subMetas: one for the sprite-frame importer and one for the texture importer. These UUIDs differ (e.g. ...@f9941 vs ...@6c48a) and are easy to confuse when copy-pasting from a scan or asset list. Before wiring a SpriteFrame slot, read the image’s .meta file and confirm which sub-asset entry has "importer": "sprite-frame" — binding the texture UUID into a SpriteFrame property silently assigns the wrong asset type.