Skip to content

t1k:cocos:playable:tooling-gotchas

FieldValue
Moduleplayable
Version4.33.13
Effortlow
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

/t1k:cocos:playable:tooling-gotchas

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.

IDToolSymptom (short)Reference
1Cocos MCPScene/asset writes land in wrong reporef (references/cocos-mcp-targets-open-project.md)
2Write toolNew script file not imported; @ccclass not registered — and…ref (references/write-tool-files-not-imported.md)
3Prefab JSONNeed to bind a component with no editor / no MCP serverref (references/prefab-component-attach-by-hand.md)
4Node / renderingRuntime-created node under a Canvas renders nothing, no errorref (references/runtime-created-nodes.md)
5Cocos MCPmanage_component add reports “not found after addition” — it…ref (references/manage-component-custom-script.md)
6Cocos MCPmanage_prefab update returns “Editor rejected apply-prefab”…ref (references/manage-prefab-update-false-error.md)
7Cocos MCPmanage_debug get_console_logs returns an empty log list on…ref (references/manage-debug-console-logs-empty.md)
8Cocos MCPmanage_component set_property/set_properties_batch crashes…ref (references/manage-component-array-properties.md)
9Cocos MCPmanage_scene_query soft_reload and manage_scene action=open…ref (references/scene-reload-stale-cache.md)
10Editor saveReopening and saving a scene rewrites UI camera…ref (references/scene-reopen-save-camera-rewrite.md)
11Cocos MCPcc.MeshRenderer with an empty material array:…ref (references/manage-component-mesh-renderer-empty-material.md)
12Prefab JSONDirect edit on a node inside a nested cc.PrefabInstance is…ref (references/prefab-instance-override-table.md)
13Rendering / debugBefore concluding a mesh “does not render”, measure its…ref (references/mesh-not-rendering-pixel-size.md)
14Cocos MCPmanage_asset action=delete is pin-relative: url works, urlOrUUID fails;…ref (references/manage-asset-delete-no-op.md)
15Cocos MCPmanage_component set_property targeting ONE numeric @property…ref (references/manage-component-silent-numeric-zero.md)
16Module resolutionImporting a @playablelabs/game-foundation subsystem by its…ref (references/directory-import-silent-bundle-crash.md)
17Cocos MCPmanage_component set_property on a @property(Node/Component)…ref (references/prefab-boundary-property-refs.md)
18Cocos EditorEvery MCP call fails with Method does not…ref (references/mcp-extension-load-failure.md)
19PrefabPrefab-instantiated node (via manage_node create-from-prefab…ref (references/prefab-instantiate-layer-cull.md)
20Preview / hot-reloadAn edited .ts keeps running old code in the preview until the…ref (references/manage-asset-refresh-not-auto-recompiled.md)
21Cocos MCPmanage_component set_property on cc.MeshRenderer errors on…ref (references/manage-component-mesh-renderer-material.md)
22Cocos MCPmanage_material create writes an empty .mtl; set_property…ref (references/manage-material-empty-on-create.md)
23Cocos MCPmanage_ui create_label/create_sprite ship broken defaults —…ref (references/manage-ui-create-defaults.md)
24Preview scriptingCamera.worldToScreen in a headless preview returns window…ref (references/world-to-screen-window-pixels.md)
25Scene serializationChanging a @property class default doesn’t update…ref (references/stale-serialized-property-default.md)
26Cocos MCPConnectionRefused from the MCP tools doesn’t always mean the…ref (references/mcp-connection-refused-http-fallback.md)
27Cocos MCP / Prefabmanage_prefab create drops transforms, mesh, and materials —…ref (references/manage-prefab-create-drops-transforms.md)
28Sprite / importcc.Sprite with @f9941 renders as a solid-colour…ref (references/sprite-frame-missing-renders-solid-color.md)
29Editor scene cacheA .scene open in the editor is NOT reloaded when git rewrites…ref (references/scene-stale-after-git-checkout.md)
30Scene serializationA scene-placed prefab instance carries CCPropertyOverrideInfo…ref (references/scene-prefab-instance-override.md)
31Preview scriptingcc.Sprite must be in CUSTOM size mode (_sizeMode: 0) before…ref (references/sprite-custom-size-mode.md)
32Preview scriptingcc.UIOpacity / cc.UITransform / cc.Sprite are not reachable…ref (references/global-cc-classes-unreachable.md)
33Cocos MCPMCP port is per project (settings/mcp-server.json; 3000 is…ref (references/mcp-port-resolve-get-is-false-negative.md)
34Cocos MCPset_property with propertyType: nodeArray/componentArray…ref (references/manage-component-array-length-then-index.md)
35Cocos MCPmanage_particle action=add fails “Node not found” on a node…ref (references/manage-particle-add-node-not-found.md)
36Runtime scriptinginstantiate(material) throws TypeError: The instantiate…ref (references/instantiate-material-not-implemented.md)
37Cocos MCP / AssetsEngine-internal assets resolve via manage_asset…ref (references/manage-asset-internal-assets-and-disk-batch.md)
38Cocos MCPNew .ts via manage_asset action=create imports late (~3 s);…ref (references/manage-asset-create-query-has-script.md)
39Template paramsReusing the template’s Camera3D for 3D gameplay gets silently…ref (references/template-parameter-camera-background-traps.md)
40Preview / CDPSynthetic MouseEvents on the canvas reach cc.input;…ref (references/cdp-mouse-events-world-to-screen.md)
41Runtime perfPer-renderer renderer.material = m instances multiply draw…ref (references/instancing-shared-material-drawcalls.md)
42Runtime scriptingcc.Camera component worldToScreen(worldPos, out?) vs the…ref (references/camera-worldtoscreen-argument-order.md)
43Renderingcc.UIOpacity is a silent no-op on a 3D MeshRenderer node — no…ref (references/uiopacity-noop-on-3d-mesh.md)
44Asset recovery / Prefab JSONRe-encoding a decoded cc.Mesh (interleaved float32, stride…ref (references/decoded-mesh-glb-reimport-and-prefab-indexing.md)
45Runtime scriptingA prefab spawned onto an anchor node must copy the anchor’s…ref (references/prefab-spawn-anchor-rotation.md)
46Runtime scriptingrenderer.material allocates and caches a MaterialInstance;…ref (references/renderer-material-instance-to-shared-slot.md)
47Tutorial / FTUETween constants ported from a 3D reference playable are in…ref (references/tutorial-hint-unit-mismatch-and-anchor-projection.md)
48Write tool / Cocos MCPEditing a tracked .ts script with the plain Edit/Write tool…ref (references/editor-reverts-external-script-writes.md)
49Cocos MCPmanage_component set_property on cc.SpriteRenderer (3D)…ref (references/manage-component-sprite-renderer-material.md)
50Cocos MCPmanage_project has no settings setter and…ref (references/manage-project-settings-and-preview-control.md)
51Preview scriptingPreview-page cc.MeshRenderer/cc.SpriteRenderer are not the…ref (references/preview-window-cc-class-identity.md)
52Material / RenderingGiving decor quads an explicit priority below 128 to order…ref (references/material-priority-lowered-decor-hidden-by-default-backdrop.md)
53Cocos MCPmanage_node action=create with nodeType=3DNode silently…ref (references/manage-node-3dnode-attaches-uitransform.md)
54Editor asset cacheA @property added to an EXISTING script edited from outside…ref (references/external-script-edit-stale-property-list.md)
55CLI buildCocosCreator.exe —project —build…ref (references/cocos-cli-build-exit-codes.md)
56Cocos MCPmanage_node action=move to the SAME parent with a new…ref (references/manage-node-move-same-parent-noop.md)
57Cocos MCPmanage_prefab action=update can revert a live scene node’s…ref (references/manage-prefab-update-reverts-scene-props.md)
58Cocos MCPmanage_component set_property cannot write user-declared…ref (references/manage-component-user-array-properties-unwritable.md)
59Cocos MCPmanage_asset get_details reports 0 sub-assets for FBX in…ref (references/manage-asset-fbx-subassets-and-query-uuid-failure.md)
60Cocos MCPmanage_scene action=close reports success but does NOT unload…ref (references/manage-scene-close-does-not-unload.md)
61Prefab JSONA cross-prefab-instance @property(Component) ref serializes…ref (references/prefab-target-override-info-not-unwired.md)
62Cocos MCPmanage_node create unlinkPrefab=true works, but only at…ref (references/manage-node-unlink-prefab-create-only.md)
63Cocos MCPmanage_asset get_info takes urlOrUUID, not url;…ref (references/manage-asset-get-info-param-and-verbose-component-schema.md)
64Cocos Editor / Assetsdb://internal/default_meshes is empty in 3.8.7 — no…ref (references/default-meshes-empty-export-fbx-primitives.md)
65Blender / FBX importAny Blender 5.2 round-trip re-export of a particular skinned…ref (references/blender-reexport-crashes-fbx-gltf-conv.md)
66Blender / FBX exportBlender’s FBX exporter cannot cheaply bake animation for a…ref (references/blender-empty-rig-controllers-bake-anim-fails.md)
67PhysicsA node write made on Director.EVENT_AFTER_PHYSICS never…ref (references/physics-after-physics-write-lost.md)
68Skeletal AnimationA node parented under a bone of a baked cc.SkeletalAnimation…ref (references/skeletal-animation-socket-transform-freeze.md)
69Rendering / debugMeshRenderer.model.worldBounds right after instantiate() is…ref (references/mesh-renderer-worldbounds-stale-until-render.md)
70Cocos MCPmanage_asset action=save_meta takes urlOrUUID, not assetPath…ref (references/manage-asset-save-meta-urloruuid-param.md)
71Cocos MCPsave_meta (userData.type: “sprite-frame”) then reimport races…ref (references/manage-asset-save-meta-reimport-race-sprite-frame.md)
72Asset importA .woff2 under assets/ imports with importer: ”*” (not a…ref (references/woff2-unrecognized-font-and-disk-write-needs-refresh.md)
73Cocos MCPA freshly-added cc.Sprite defaults to sizeMode: TRIMMED —…ref (references/sprite-default-sizemode-trimmed-reverts-contentsize.md)
74Cocos MCPmanage_component set_property/set_properties_batch on a…ref (references/manage-component-vec2-falsy-component-dropped.md)
75Cocos MCPmanage_node action=move (keepWorldTransform=true) on a node…ref (references/manage-node-move-prefab-instance-member-noop.md)
76Cocos MCPmanage_node action=delete on a node already pushed into a…ref (references/manage-node-delete-prefab-instance-member-noop.md)
77Cocos MCPcc.Widget offset set, then a LATER UITransform.contentSize…ref (references/manage-component-widget-offset-contentsize-reflow.md)
78Cocos MCPmanage_component set_property/set_properties_batch cannot…ref (references/manage-component-nodearray-custom-component-write.md)
79Cocos MCPmanage_scene action=open also accepts a .prefab path — it…ref (references/prefab-edit-mode-writes.md)
80Runtime scriptingprefab.data.getComponent(T) only sees the prefab ROOT — an…ref (references/prefab-root-only-getcomponent.md)
81Vendored packageA vendored package’s .cjs entry calling require(‘cc’) crashes…ref (references/vendored-cjs-require-cc-crashes-boot.md)
82Cocos MCPmanage_scene action=save reports success while writing…ref (references/manage-scene-save-noop-when-not-dirty.md)
83Module resolutionAn extensionless db:// import of a vendored .js package entry…ref (references/db-import-missing-js-extension.md)
84Skeletal Animation / Rig imp…A reference implementation’s literal setScale() on a node…ref (references/bone-socket-nonunit-scale.md)
85Cocos MCPA cc.Label at default overflow NONE auto-resizes its node’s…ref (references/label-overflow-none-autosize-reverts-contentsize.md)
86Cocos APINode.getComponentInChildren excludes the node itself…ref (references/getcomponentinchildren-excludes-self.md)
87Project settingsfitHeight: true with fitWidth ABSENT ships SHOW_ALL (policy…ref (references/fitheight-alone-is-showall.md)
88Cocos MCPmanage_prefab action=update is a whole-instance Apply: it…ref (references/manage-prefab-update-false-error.md)
89Cocos MCPThe composite falsy-value drop (row 74) extends beyond…ref (references/manage-component-vec2-falsy-component-dropped.md)
90Runtime scriptingMesh.updateSubMesh(i, geom) pairs buffers with vertex bundles…ref (references/mesh-updatesubmesh-stream-position-pairing.md)
91Font importA .ttf whose FILENAME contains a space never loads (preview…ref (references/font-filename-space-breaks-ttf-load.md)
92Rendering / scene layeringA 3D object drawn by the model-layer camera (a body tube, an…ref (references/model-layer-3d-not-occluded-by-2d-backdrop.md)
93Runtime scriptingnew Material().initialize({ effectName: ‘builtin-standard’ })…ref (references/runtime-material-effect-not-registered.md)
94PhysicsBullet: adding a Collider BEFORE the RigidBody on an ACTIVE…ref (references/bullet-collider-before-rigidbody-nan.md)
95Runtime scriptingCocos 3.8.7 runtime API traps that pass review and structural…ref (references/cocos-387-runtime-api-traps.md)
97Cocos MCPsave_meta with a bare {type} reports success, changes nothing — wrap in userData…ref (references/manage-asset-save-meta-userdata-wrapper.md)
98Cocos MCP / AssetsDeleting a prefab asset the open scene instances leaves “(Missing Node)” children; read-back by name misses themref (references/delete-recreate-referenced-asset-missing-node.md)
99Runtime scriptingA code-built dynamic mesh draws NOTHING (culled): enable the renderer first, ±1e4 bounds, CCW windingref (references/dynamic-mesh-renderer-bounds-winding-traps.md)
100Cocos MCP<array>.length-then-.<i> leaves unset slots undefined; the SAVE drops them. Fill every hole, read back from diskref (references/manage-component-array-length-holes.md)
101Cocos MCPmanage_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)
102RenderingMesh particles invisible in build: FBX quantize=trueref (references/particle-mesh-quantize.md)
103Cocos MCPEvery MCP call times out while /health is fine: a modal TaskDialog blocks the editor; dismiss with IDCANCELref (references/taskdialog-modal-mcp-timeout.md)
104Cocos MCPmanage_prefab instantiate without parentUuid parents to the SELECTED node, baking nesting into the .prefabref (references/manage-prefab-instantiate-default-parent.md)
105Cocos MCPmanage_node set_property on the scene root echoes 75k+ chars, so a success reads as failureref (references/manage-node-set-property-root-output-overflow.md)
106Cocos MCPexecute_script getChildByUuid sees only root-level children; nested nodes return nullref (references/execute-script-getchildbyuuid-toplevel-only.md)
107Cocos MCP / Rig importBone-socket mount under a nested glb inlines the node chain into the .prefabref (references/nested-glb-bone-mount-inlines-node-chain.md)
108Editor / previewA 2nd 3.8.7 editor rewrites the shared preview import-map.json from its own engine.json; spine vanishesref (references/shared-engine-preview-cache.md)
109Editor / previewA spine-3.8 project rewrites the SHARED import-map.json: an open 4.2 project previews on the 3.8 runtimeref (references/preview-spine-version-override-shared-cache.md)
110Editor / previewPreview 500s with ENOENT …<uuid>.tmp.js after %TEMP% is cleared; restore from app.asar, mark read-onlyref (references/preview-500-temp-js-memoised-files.md)
111CLI build / previewA CLI build with the editor open rewrites shared packer chunks; the preview then fails cc.PhysicMaterial. Close the editor firstref (references/cli-build-while-editor-open-breaks-preview.md)
112Runtime scriptingutils.readMesh returns EMPTY positions/normals/uvs in a RELEASE build only. Use Mesh.readAttribute / readIndicesref (references/readmesh-release-build-empty-attributes.md)
113Prefab JSONA stale propertyOverrides entry hijacks a re-ADDED @property of the same name; the class default never appliesref (references/readded-property-hijacked-by-stale-override.md)
114Prefab JSONNode ref reassigned to outside the prefab reverts (old TargetOverrideInfo stays)ref (references/instance-node-ref-reassign-keeps-old-target-override.md)
115Editor asset cacheA .ts saved before its imported module exists keeps a stale Module not found; reimport the IMPORTERref (references/stale-module-not-found-importer-saved-first.md)
116Project settingsChanging 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 firstref (references/design-resolution-change-reanchor.md)

Full symptom text for every row: references/symptom-index-full.md.

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)

Per-gotcha detailed references — see references/details-index.md.

PLA build batch (8 traps): references/pla-build-hard-rules.md.

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.