t1k:cocos:playable:tooling-gotchas
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | low |
| Tools | — |
Keywords: @font-face, 404, app.asar, backdrop occluder, blender, bone mount, camera visibility, can not find class, clearFlags, cli build editor open, console logs, contentSize, createDynamicMesh, cull, dangling asset ref, db:// import, delete and recreate asset, depth-only, dynamic mesh, ENOENT temp, execute_script, fbx, font, font filename, font-family, foreign instance, getChildByUuid, gotcha, import, import-map.json, inline node chain, invalid timeline type, isPlugin, label, link-prefab, manage_asset, manage_component, manage_debug, manage_material, manage_prefab, manage_scene open prefab, manage_ui, MCP timeout, mesh buffer, missing node, modal dialog, model camera, model layer, module not found, nested glb, node conversion failed, occluder, occlusion, output overflow, overflow, packer-driver, parentUuid, PhysicMaterial, physics, playableSync, prefab-edit mode, preview 500, preview server, query_classes, read-only temp file, reimport, require cc, rigidbody, save_meta, scenario scripts do not exist, script, second editor, selected node, shared preview cache, should_hide_in_hierarchy, skeletal animation, socket, sp.Skeleton missing node, spine 4.2, spine missing module, spine-version override, sprite-frame, targetOverrides, TaskDialog, tmp.js, ttf, tunnel, updateSubMesh, urlOrUUID, vendored package, vertex stream, woff2, worldBounds, worldPosition, write tool
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:tooling-gotchasCocos Playable — Tooling Hard Rules
Section titled “Cocos Playable — Tooling Hard Rules”Known failure modes of Cocos MCP tools and the Write tool when authoring playable ads. Each entry links a reference with evidence and the fix.
Hard rules
Section titled “Hard rules”| ID | Tool | Symptom (short) | Reference |
|---|---|---|---|
| 1 | Cocos MCP | Scene/asset writes land in wrong repo | ref (references/cocos-mcp-targets-open-project.md) |
| 2 | Write tool | New script file not imported; @ccclass not registered — and… | ref (references/write-tool-files-not-imported.md) |
| 3 | Prefab JSON | Need to bind a component with no editor / no MCP server | ref (references/prefab-component-attach-by-hand.md) |
| 4 | Node / rendering | Runtime-created node under a Canvas renders nothing, no error | ref (references/runtime-created-nodes.md) |
| 5 | Cocos MCP | manage_component add reports “not found after addition” — it… | ref (references/manage-component-custom-script.md) |
| 6 | Cocos MCP | manage_prefab update returns “Editor rejected apply-prefab”… | ref (references/manage-prefab-update-false-error.md) |
| 7 | Cocos MCP | manage_debug get_console_logs returns an empty log list on… | ref (references/manage-debug-console-logs-empty.md) |
| 8 | Cocos MCP | manage_component set_property/set_properties_batch crashes… | ref (references/manage-component-array-properties.md) |
| 9 | Cocos MCP | manage_scene_query soft_reload and manage_scene action=open… | ref (references/scene-reload-stale-cache.md) |
| 10 | Editor save | Reopening and saving a scene rewrites UI camera… | ref (references/scene-reopen-save-camera-rewrite.md) |
| 11 | Cocos MCP | cc.MeshRenderer with an empty material array:… | ref (references/manage-component-mesh-renderer-empty-material.md) |
| 12 | Prefab JSON | Direct edit on a node inside a nested cc.PrefabInstance is… | ref (references/prefab-instance-override-table.md) |
| 13 | Rendering / debug | Before concluding a mesh “does not render”, measure its… | ref (references/mesh-not-rendering-pixel-size.md) |
| 14 | Cocos MCP | manage_asset action=delete is pin-relative: url works, urlOrUUID fails;… | ref (references/manage-asset-delete-no-op.md) |
| 15 | Cocos MCP | manage_component set_property targeting ONE numeric @property… | ref (references/manage-component-silent-numeric-zero.md) |
| 16 | Module resolution | Importing a @playablelabs/game-foundation subsystem by its… | ref (references/directory-import-silent-bundle-crash.md) |
| 17 | Cocos MCP | manage_component set_property on a @property(Node/Component)… | ref (references/prefab-boundary-property-refs.md) |
| 18 | Cocos Editor | Every MCP call fails with Method does not… | ref (references/mcp-extension-load-failure.md) |
| 19 | Prefab | Prefab-instantiated node (via manage_node create-from-prefab… | ref (references/prefab-instantiate-layer-cull.md) |
| 20 | Preview / hot-reload | An edited .ts keeps running old code in the preview until the… | ref (references/manage-asset-refresh-not-auto-recompiled.md) |
| 21 | Cocos MCP | manage_component set_property on cc.MeshRenderer errors on… | ref (references/manage-component-mesh-renderer-material.md) |
| 22 | Cocos MCP | manage_material create writes an empty .mtl; set_property… | ref (references/manage-material-empty-on-create.md) |
| 23 | Cocos MCP | manage_ui create_label/create_sprite ship broken defaults —… | ref (references/manage-ui-create-defaults.md) |
| 24 | Preview scripting | Camera.worldToScreen in a headless preview returns window… | ref (references/world-to-screen-window-pixels.md) |
| 25 | Scene serialization | Changing a @property class default doesn’t update… | ref (references/stale-serialized-property-default.md) |
| 26 | Cocos MCP | ConnectionRefused from the MCP tools doesn’t always mean the… | ref (references/mcp-connection-refused-http-fallback.md) |
| 27 | Cocos MCP / Prefab | manage_prefab create drops transforms, mesh, and materials —… | ref (references/manage-prefab-create-drops-transforms.md) |
| 28 | Sprite / import | cc.Sprite with | ref (references/sprite-frame-missing-renders-solid-color.md) |
| 29 | Editor scene cache | A .scene open in the editor is NOT reloaded when git rewrites… | ref (references/scene-stale-after-git-checkout.md) |
| 30 | Scene serialization | A scene-placed prefab instance carries CCPropertyOverrideInfo… | ref (references/scene-prefab-instance-override.md) |
| 31 | Preview scripting | cc.Sprite must be in CUSTOM size mode (_sizeMode: 0) before… | ref (references/sprite-custom-size-mode.md) |
| 32 | Preview scripting | cc.UIOpacity / cc.UITransform / cc.Sprite are not reachable… | ref (references/global-cc-classes-unreachable.md) |
| 33 | Cocos MCP | MCP port is per project (settings/mcp-server.json; 3000 is… | ref (references/mcp-port-resolve-get-is-false-negative.md) |
| 34 | Cocos MCP | set_property with propertyType: nodeArray/componentArray… | ref (references/manage-component-array-length-then-index.md) |
| 35 | Cocos MCP | manage_particle action=add fails “Node not found” on a node… | ref (references/manage-particle-add-node-not-found.md) |
| 36 | Runtime scripting | instantiate(material) throws TypeError: The instantiate… | ref (references/instantiate-material-not-implemented.md) |
| 37 | Cocos MCP / Assets | Engine-internal assets resolve via manage_asset… | ref (references/manage-asset-internal-assets-and-disk-batch.md) |
| 38 | Cocos MCP | New .ts via manage_asset action=create imports late (~3 s);… | ref (references/manage-asset-create-query-has-script.md) |
| 39 | Template params | Reusing the template’s Camera3D for 3D gameplay gets silently… | ref (references/template-parameter-camera-background-traps.md) |
| 40 | Preview / CDP | Synthetic MouseEvents on the canvas reach cc.input;… | ref (references/cdp-mouse-events-world-to-screen.md) |
| 41 | Runtime perf | Per-renderer renderer.material = m instances multiply draw… | ref (references/instancing-shared-material-drawcalls.md) |
| 42 | Runtime scripting | cc.Camera component worldToScreen(worldPos, out?) vs the… | ref (references/camera-worldtoscreen-argument-order.md) |
| 43 | Rendering | cc.UIOpacity is a silent no-op on a 3D MeshRenderer node — no… | ref (references/uiopacity-noop-on-3d-mesh.md) |
| 44 | Asset recovery / Prefab JSON | Re-encoding a decoded cc.Mesh (interleaved float32, stride… | ref (references/decoded-mesh-glb-reimport-and-prefab-indexing.md) |
| 45 | Runtime scripting | A prefab spawned onto an anchor node must copy the anchor’s… | ref (references/prefab-spawn-anchor-rotation.md) |
| 46 | Runtime scripting | renderer.material allocates and caches a MaterialInstance;… | ref (references/renderer-material-instance-to-shared-slot.md) |
| 47 | Tutorial / FTUE | Tween constants ported from a 3D reference playable are in… | ref (references/tutorial-hint-unit-mismatch-and-anchor-projection.md) |
| 48 | Write tool / Cocos MCP | Editing a tracked .ts script with the plain Edit/Write tool… | ref (references/editor-reverts-external-script-writes.md) |
| 49 | Cocos MCP | manage_component set_property on cc.SpriteRenderer (3D)… | ref (references/manage-component-sprite-renderer-material.md) |
| 50 | Cocos MCP | manage_project has no settings setter and… | ref (references/manage-project-settings-and-preview-control.md) |
| 51 | Preview scripting | Preview-page cc.MeshRenderer/cc.SpriteRenderer are not the… | ref (references/preview-window-cc-class-identity.md) |
| 52 | Material / Rendering | Giving decor quads an explicit priority below 128 to order… | ref (references/material-priority-lowered-decor-hidden-by-default-backdrop.md) |
| 53 | Cocos MCP | manage_node action=create with nodeType=3DNode silently… | ref (references/manage-node-3dnode-attaches-uitransform.md) |
| 54 | Editor asset cache | A @property added to an EXISTING script edited from outside… | ref (references/external-script-edit-stale-property-list.md) |
| 55 | CLI build | CocosCreator.exe —project | ref (references/cocos-cli-build-exit-codes.md) |
| 56 | Cocos MCP | manage_node action=move to the SAME parent with a new… | ref (references/manage-node-move-same-parent-noop.md) |
| 57 | Cocos MCP | manage_prefab action=update can revert a live scene node’s… | ref (references/manage-prefab-update-reverts-scene-props.md) |
| 58 | Cocos MCP | manage_component set_property cannot write user-declared… | ref (references/manage-component-user-array-properties-unwritable.md) |
| 59 | Cocos MCP | manage_asset get_details reports 0 sub-assets for FBX in… | ref (references/manage-asset-fbx-subassets-and-query-uuid-failure.md) |
| 60 | Cocos MCP | manage_scene action=close reports success but does NOT unload… | ref (references/manage-scene-close-does-not-unload.md) |
| 61 | Prefab JSON | A cross-prefab-instance @property(Component) ref serializes… | ref (references/prefab-target-override-info-not-unwired.md) |
| 62 | Cocos MCP | manage_node create unlinkPrefab=true works, but only at… | ref (references/manage-node-unlink-prefab-create-only.md) |
| 63 | Cocos MCP | manage_asset get_info takes urlOrUUID, not url;… | ref (references/manage-asset-get-info-param-and-verbose-component-schema.md) |
| 64 | Cocos Editor / Assets | db://internal/default_meshes is empty in 3.8.7 — no… | ref (references/default-meshes-empty-export-fbx-primitives.md) |
| 65 | Blender / FBX import | Any Blender 5.2 round-trip re-export of a particular skinned… | ref (references/blender-reexport-crashes-fbx-gltf-conv.md) |
| 66 | Blender / FBX export | Blender’s FBX exporter cannot cheaply bake animation for a… | ref (references/blender-empty-rig-controllers-bake-anim-fails.md) |
| 67 | Physics | A node write made on Director.EVENT_AFTER_PHYSICS never… | ref (references/physics-after-physics-write-lost.md) |
| 68 | Skeletal Animation | A node parented under a bone of a baked cc.SkeletalAnimation… | ref (references/skeletal-animation-socket-transform-freeze.md) |
| 69 | Rendering / debug | MeshRenderer.model.worldBounds right after instantiate() is… | ref (references/mesh-renderer-worldbounds-stale-until-render.md) |
| 70 | Cocos MCP | manage_asset action=save_meta takes urlOrUUID, not assetPath… | ref (references/manage-asset-save-meta-urloruuid-param.md) |
| 71 | Cocos MCP | save_meta (userData.type: “sprite-frame”) then reimport races… | ref (references/manage-asset-save-meta-reimport-race-sprite-frame.md) |
| 72 | Asset import | A .woff2 under assets/ imports with importer: ”*” (not a… | ref (references/woff2-unrecognized-font-and-disk-write-needs-refresh.md) |
| 73 | Cocos MCP | A freshly-added cc.Sprite defaults to sizeMode: TRIMMED —… | ref (references/sprite-default-sizemode-trimmed-reverts-contentsize.md) |
| 74 | Cocos MCP | manage_component set_property/set_properties_batch on a… | ref (references/manage-component-vec2-falsy-component-dropped.md) |
| 75 | Cocos MCP | manage_node action=move (keepWorldTransform=true) on a node… | ref (references/manage-node-move-prefab-instance-member-noop.md) |
| 76 | Cocos MCP | manage_node action=delete on a node already pushed into a… | ref (references/manage-node-delete-prefab-instance-member-noop.md) |
| 77 | Cocos MCP | cc.Widget offset set, then a LATER UITransform.contentSize… | ref (references/manage-component-widget-offset-contentsize-reflow.md) |
| 78 | Cocos MCP | manage_component set_property/set_properties_batch cannot… | ref (references/manage-component-nodearray-custom-component-write.md) |
| 79 | Cocos MCP | manage_scene action=open also accepts a .prefab path — it… | ref (references/prefab-edit-mode-writes.md) |
| 80 | Runtime scripting | prefab.data.getComponent(T) only sees the prefab ROOT — an… | ref (references/prefab-root-only-getcomponent.md) |
| 81 | Vendored package | A vendored package’s .cjs entry calling require(‘cc’) crashes… | ref (references/vendored-cjs-require-cc-crashes-boot.md) |
| 82 | Cocos MCP | manage_scene action=save reports success while writing… | ref (references/manage-scene-save-noop-when-not-dirty.md) |
| 83 | Module resolution | An extensionless db:// import of a vendored .js package entry… | ref (references/db-import-missing-js-extension.md) |
| 84 | Skeletal Animation / Rig imp… | A reference implementation’s literal setScale() on a node… | ref (references/bone-socket-nonunit-scale.md) |
| 85 | Cocos MCP | A cc.Label at default overflow NONE auto-resizes its node’s… | ref (references/label-overflow-none-autosize-reverts-contentsize.md) |
| 86 | Cocos API | Node.getComponentInChildren excludes the node itself… | ref (references/getcomponentinchildren-excludes-self.md) |
| 87 | Project settings | fitHeight: true with fitWidth ABSENT ships SHOW_ALL (policy… | ref (references/fitheight-alone-is-showall.md) |
| 88 | Cocos MCP | manage_prefab action=update is a whole-instance Apply: it… | ref (references/manage-prefab-update-false-error.md) |
| 89 | Cocos MCP | The composite falsy-value drop (row 74) extends beyond… | ref (references/manage-component-vec2-falsy-component-dropped.md) |
| 90 | Runtime scripting | Mesh.updateSubMesh(i, geom) pairs buffers with vertex bundles… | ref (references/mesh-updatesubmesh-stream-position-pairing.md) |
| 91 | Font import | A .ttf whose FILENAME contains a space never loads (preview… | ref (references/font-filename-space-breaks-ttf-load.md) |
| 92 | Rendering / scene layering | A 3D object drawn by the model-layer camera (a body tube, an… | ref (references/model-layer-3d-not-occluded-by-2d-backdrop.md) |
| 93 | Runtime scripting | new Material().initialize({ effectName: ‘builtin-standard’ })… | ref (references/runtime-material-effect-not-registered.md) |
| 94 | Physics | Bullet: adding a Collider BEFORE the RigidBody on an ACTIVE… | ref (references/bullet-collider-before-rigidbody-nan.md) |
| 95 | Runtime scripting | Cocos 3.8.7 runtime API traps that pass review and structural… | ref (references/cocos-387-runtime-api-traps.md) |
| 97 | Cocos MCP | save_meta with a bare {type} reports success, changes nothing — wrap in userData… | ref (references/manage-asset-save-meta-userdata-wrapper.md) |
| 98 | Cocos MCP / Assets | Deleting a prefab asset the open scene instances leaves “(Missing Node)” children; read-back by name misses them | ref (references/delete-recreate-referenced-asset-missing-node.md) |
| 99 | Runtime scripting | A code-built dynamic mesh draws NOTHING (culled): enable the renderer first, ±1e4 bounds, CCW winding | ref (references/dynamic-mesh-renderer-bounds-winding-traps.md) |
| 100 | Cocos MCP | <array>.length-then-.<i> leaves unset slots undefined; the SAVE drops them. Fill every hole, read back from disk | ref (references/manage-component-array-length-holes.md) |
| 101 | Cocos MCP | manage_prefab create reports “node conversion failed”: .prefab IS written, only the link fails (scene:link-prefab) | ref (references/manage-prefab-conversion-failed-and-instance-guard.md) |
| 102 | Rendering | Mesh particles invisible in build: FBX quantize=true | ref (references/particle-mesh-quantize.md) |
| 103 | Cocos MCP | Every MCP call times out while /health is fine: a modal TaskDialog blocks the editor; dismiss with IDCANCEL | ref (references/taskdialog-modal-mcp-timeout.md) |
| 104 | Cocos MCP | manage_prefab instantiate without parentUuid parents to the SELECTED node, baking nesting into the .prefab | ref (references/manage-prefab-instantiate-default-parent.md) |
| 105 | Cocos MCP | manage_node set_property on the scene root echoes 75k+ chars, so a success reads as failure | ref (references/manage-node-set-property-root-output-overflow.md) |
| 106 | Cocos MCP | execute_script getChildByUuid sees only root-level children; nested nodes return null | ref (references/execute-script-getchildbyuuid-toplevel-only.md) |
| 107 | Cocos MCP / Rig import | Bone-socket mount under a nested glb inlines the node chain into the .prefab | ref (references/nested-glb-bone-mount-inlines-node-chain.md) |
| 108 | Editor / preview | A 2nd 3.8.7 editor rewrites the shared preview import-map.json from its own engine.json; spine vanishes | ref (references/shared-engine-preview-cache.md) |
| 109 | Editor / preview | A spine-3.8 project rewrites the SHARED import-map.json: an open 4.2 project previews on the 3.8 runtime | ref (references/preview-spine-version-override-shared-cache.md) |
| 110 | Editor / preview | Preview 500s with ENOENT …<uuid>.tmp.js after %TEMP% is cleared; restore from app.asar, mark read-only | ref (references/preview-500-temp-js-memoised-files.md) |
| 111 | CLI build / preview | A CLI build with the editor open rewrites shared packer chunks; the preview then fails cc.PhysicMaterial. Close the editor first | ref (references/cli-build-while-editor-open-breaks-preview.md) |
| 112 | Runtime scripting | utils.readMesh returns EMPTY positions/normals/uvs in a RELEASE build only. Use Mesh.readAttribute / readIndices | ref (references/readmesh-release-build-empty-attributes.md) |
| 113 | Prefab JSON | A stale propertyOverrides entry hijacks a re-ADDED @property of the same name; the class default never applies | ref (references/readded-property-hijacked-by-stale-override.md) |
| 114 | Prefab JSON | Node ref reassigned to outside the prefab reverts (old TargetOverrideInfo stays) | ref (references/instance-node-ref-reassign-keeps-old-target-override.md) |
| 115 | Editor asset cache | A .ts saved before its imported module exists keeps a stale Module not found; reimport the IMPORTER | ref (references/stale-module-not-found-importer-saved-first.md) |
| 116 | Project settings | Changing the design resolution moves only Widget-stretched nodes: re-anchor every screen/popup root and fixed-offset label by newH - oldH; a root with no Widget keeps the old height. Count the roots first | ref (references/design-resolution-change-reanchor.md) |
Full symptom text for every row: references/symptom-index-full.md.
Quick Decision Guide
Section titled “Quick Decision Guide”Action-oriented Q&A for when each gotcha fires — see references/quick-decision-guide.md.
manage_scene save after node/component mutations: on disk? Don’t trust success: true; parse the .scene on disk. recipe (references/manage-scene-save-noop-when-not-dirty.md)
Porting setScale() onto a node under a rig bone socket? Divide the literal by abs(socket.scale.x). detail (references/bone-socket-nonunit-scale.md)
Importing a vendored ESM dist/index by db:// URL? Write dist/index.js explicitly. recipe (references/db-import-missing-js-extension.md)
Details
Section titled “Details”Per-gotcha detailed references — see references/details-index.md.
PLA build batch (8 traps): references/pla-build-hard-rules.md.
Executed by
Section titled “Executed by”check-fit-settings.cjs is a scripted read-only check: t1k-data-verifier runs it and reports its output verbatim. Applying a fix through the editor MCP stays on t1k-cocos-base-developer (reasoning tier). Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md.