Skip to content

t1k:cocos:playable:editor-tools

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: ConfigWatcher, editor tools, extension, parameter JSON

/t1k:cocos:playable:editor-tools

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

ToolFilePurpose
ConfigWatcherassets/PlayableParamterTool/json-generate/ConfigWatcher.tsGenerates playable-config.json and parameter-assets.json on start() in a visible editor (not on refresh or asset-db events; references/configwatcher.md)
Package Managerextensions/package-manager/CPM registry UI — install/sync PlayableLabs packages
Cocos MCP Serverextensions/cocos-mcp-server/Action-based MCP tools for AI-assisted editor control
  • 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_asset actions, and the ones that do NOT exist (references/cocos-mcp-server.md)
  • Component authoring gotchas — @property Enum 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)
  • Editing files in ParameterToolBuild/ — they are overwritten by ConfigWatcher.
  • Calling require('fs') in non-editor scripts — crashes at runtime; always guard with if (!EDITOR) return.
  • Forgetting @executeInEditMode(true) on a component that needs editor-only behavior.
  • Package Manager extension source is TypeScript in source/ — compiled output is in dist/. Edit source, not dist.
  • SyncService uses fs-extra (not native fs) for ensureDir, copy, remove — ensure fs-extra is in the extension’s node_modules.
  • Editor.Message.request is async — always await it inside an async function.
  • Editor scripts run in a different process — cc.director is 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.log lists fewer [REMOVED] assets (CocosBubbleFishSortPLA: 23, then 29 on a second run) and six sprite default values 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-tool package, 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.
  • @property inspector Enum() MUST use a local static literal, NOT an imported barrel/registry enum — a barrel value may be undefined during module-eval bundle ordering; the resulting throw silently de-registers EVERY @ccclass in the package (all show as “missing or invalid”). See hard-rules (references/hard-rules.md).
  • Authoring .scene/.prefab JSON 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: true on disk (the MCP has no knob for it), then manage_asset reimport the scene AND manage_editor reload_scene — manage_scene open on an already-open scene is a no-op and get_info keeps 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 @property MUST 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.UITransform in any UI hierarchy), so the field binds the wrong object and throws on the first method call at runtime. Read the .scene back and assert the target __type__ is the expected script class, not merely non-null. Worst when the type comes through import type {} (the usual circular-value-import breaker): no editor-side type check exists at all — prefer the owner binding itself in onLoad (this.board.bindController(this)). See hard-rules (references/hard-rules.md).
  • See also — Cocos MCP tool-call gotchas (manage_node move reorder no-op, manage_prefab update reverting scene edits, unwritable array/material properties, FBX sub-asset lookup) live in t1k-cocos-playable-tooling-gotchas, not here.