t1k:cocos:playable:editor-tools
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: ConfigWatcher, editor tools, extension, parameter JSON
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:editor-toolsEditor Tools — ConfigWatcher & Package Manager Extension
Section titled “Editor Tools — ConfigWatcher & Package Manager Extension”Two distinct editor tools: ConfigWatcher (auto-generates dashboard JSON) and package-manager extension (CPM registry UI). Also includes Cocos MCP Server (action-based MCP tools for AI-assisted editor control). See also: t1k-cocos-playable-parameter (PlayableConfig that ConfigWatcher reads), t1k-cocos-playable-sdk-core.
Quick Reference
Section titled “Quick Reference”| Tool | File | Purpose |
|---|---|---|
| ConfigWatcher | assets/PlayableParamterTool/json-generate/ConfigWatcher.ts | Generates playable-config.json and parameter-assets.json on start() in a visible editor (not on refresh or asset-db events; references/configwatcher.md) |
| Package Manager | extensions/package-manager/ | CPM registry UI — install/sync PlayableLabs packages |
| Cocos MCP Server | extensions/cocos-mcp-server/ | Action-based MCP tools for AI-assisted editor control |
Details
Section titled “Details”- ConfigWatcher internals, hash detection, file writing, asset tracking (
references/configwatcher.md) - Package Manager architecture, NpmService, SyncService, auth (
references/package-manager.md) - Cocos MCP Server tools:
manage_assetactions, and the ones that do NOT exist (references/cocos-mcp-server.md) - Component authoring gotchas —
@propertyEnum load-order trap, node-ref-into-a-component-field (references/hard-rules.md) - Scene/prefab JSON authoring gotchas — compressed uuid for type (
references/cocos-playable-editor-tools-hard-rules.md)
Common Mistakes
Section titled “Common Mistakes”- Editing files in
ParameterToolBuild/— they are overwritten by ConfigWatcher. - Calling
require('fs')in non-editor scripts — crashes at runtime; always guard withif (!EDITOR) return. - Forgetting
@executeInEditMode(true)on a component that needs editor-only behavior. - Package Manager extension source is TypeScript in
source/— compiled output is indist/. Edit source, not dist. SyncServiceusesfs-extra(not nativefs) forensureDir,copy,remove— ensurefs-extrais in the extension’snode_modules.Editor.Message.requestis async — alwaysawaitit inside anasyncfunction.
Hard rules
Section titled “Hard rules”- Editor scripts run in a different process —
cc.directoris undefined — never share runtime singletons across editor/runtime. - Editor menu items are registered once at launch — code changes need an editor restart, not an editor reload.
- ConfigWatcher regeneration right after a scene reimport blanks image-asset defaults — the removal pass has not settled, so
logs/asset-removal-report.loglists fewer[REMOVED]assets (CocosBubbleFishSortPLA: 23, then 29 on a second run) and six spritedefaultvalues are written"". After a reimport, regenerate again until the removed count stops changing (or via Preview-in-Editor), then diff both JSONs against HEAD before committing. The code lives in the vendored@playablelabs/parameter-toolpackage, not this kit; mechanism and upstream-fix proposal:t1k-cocos-playable-parameter→skills/t1k-cocos-playable-parameter/references/references-and-hard-rules.md§ “edit-mode ConfigWatcher regeneration blanks[REMOVED]-derived sprite defaults”. Refs theonekit-cocos#1739. @propertyinspectorEnum()MUST use a local static literal, NOT an imported barrel/registry enum — a barrel value may beundefinedduring module-eval bundle ordering; the resulting throw silently de-registers EVERY@ccclassin the package (all show as “missing or invalid”). See hard-rules (references/hard-rules.md).- Authoring
.scene/.prefabJSON outside the editor: use the Cocos compressed uuid for custom-script__type__, NOT the raw 36-char uuid — raw uuid deserializes as “missing or invalid” even though the script compiles fine. See cocos-playable-editor-tools-hard-rules (references/cocos-playable-editor-tools-hard-rules.md). - Scene fog defaults to per-vertex, which tints a long mesh from its far vertices — a 320-unit prop reads pink/white near the camera instead of its actual color. Set
cc.FogInfo._accurate: trueon disk (the MCP has no knob for it), thenmanage_asset reimportthe scene ANDmanage_editor reload_scene—manage_scene openon an already-open scene is a no-op andget_infokeeps reporting the MCP’s own cached values. See cocos-playable-editor-tools-hard-rules (references/cocos-playable-editor-tools-hard-rules.md). - A component-typed
@propertyMUST be wired with a COMPONENT ref, never a node ref — a node ref written into@property(Component)/@property(SomeComponent)reports success and serializes cleanly, but resolves positionally to the node’s FIRST component (cc.UITransformin any UI hierarchy), so the field binds the wrong object and throws on the first method call at runtime. Read the.sceneback and assert the target__type__is the expected script class, not merely non-null. Worst when the type comes throughimport type {}(the usual circular-value-import breaker): no editor-side type check exists at all — prefer the owner binding itself inonLoad(this.board.bindController(this)). See hard-rules (references/hard-rules.md). - See also — Cocos MCP tool-call gotchas (
manage_node movereorder no-op,manage_prefab updatereverting scene edits, unwritable array/material properties, FBX sub-asset lookup) live int1k-cocos-playable-tooling-gotchas, not here.