Патчи к code mode и доки по его настройке

2026-09-13 10:03:08 +03:00
parent 55959b6e7f
commit 7e3498bd7b
6 changed files with 1402 additions and 3 deletions
@@ -0,0 +1,102 @@
+# Code Mode setup
+
+The `cocos-code-mode` extension (in [extensions/cocos-code-mode](../extensions/cocos-code-mode))
+runs an HTTP server inside the Cocos Creator editor and exposes scene, asset and
+inspector operations as [UTCP](https://www.utcp.io/) tools. That is how the editor
+is driven from outside the UI — see [CODE_MODE_TOOLS.md](CODE_MODE_TOOLS.md) for
+the tool reference.
+
+## Prerequisites
+
+- Cocos Creator 3.8.8 must be **running with this project open**. The tool server
+  lives inside the editor process; if the editor is closed, there are no tools.
+- The extension registers itself in `~/.utcp_config.json` on startup.
+
+## The port changes on every editor restart
+
+The server binds to `127.0.0.1` on an OS-assigned port, and rewrites
+`~/.utcp_config.json` each time. Always read the config file rather than
+remembering a port:
+
+```bash
+cat ~/.utcp_config.json
+```
+
+## Running a tool chain
+
+Pass the config path via `UTCP_CONFIG_FILE`. The script body runs as an async
+function; tool calls look synchronous and `return` gives back the result.
+
+```bash
+UTCP_CONFIG_FILE="$USERPROFILE/.utcp_config.json" npx -y @utcp/code-mode-cli run <<'EOF'
+const tree = CocosEditor.nodeGetTree({});
+return { name: tree.name, children: (tree.children || []).map(c => c.name) };
+EOF
+```
+
+Discover tools by task instead of guessing names:
+
+```bash
+UTCP_CONFIG_FILE="$USERPROFILE/.utcp_config.json" npx -y @utcp/code-mode-cli search "add a sprite to a node"
+```
+
+## Working discipline
+
+The tools are built around **discover, then act**:
+
+1. `nodeGetTree` / `assetGetTree` — find the thing.
+2. `inspectorGetInstanceDefinition` — get its real TypeScript class.
+3. `inspectorSetInstanceProperties` — set properties by confirmed name.
+
+`inspectorSetInstanceProperties` states it outright: if a property path or type
+has not been confirmed via an `inspectorGet*` call, do not call a setter. Property
+names differ from the engine docs often enough that guessing corrupts scenes.
+
+Batch reads and writes into one `run` script — each `npx` invocation re-registers
+the manual, which costs a few seconds.
+
+## Regenerating the tool reference
+
+After updating the extension:
+
+```bash
+curl -s "$(node -p "require(require('os').homedir()+'/.utcp_config.json').manual_call_templates[0].url")" -o manual.json
+node docs/scripts/gen-tool-reference.js manual.json docs/CODE_MODE_TOOLS.md
+```
+
+## Known issue: `sharp` / libvips conflict on Windows
+
+**Symptom.** The editor logs `The plug-in main process failed to load` with either
+`Could not load the "sharp" module using the win32-x64 runtime` or
+`TypeError: Cannot read properties of undefined (reading 'output')` at
+`node_modules/sharp/lib/utility.js`. No `~/.utcp_config.json` appears and no tools
+are reachable.
+
+**Cause.** Two things stacked:
+
+1. The released extension zip was packaged on macOS, so its bundled `sharp` ships
+   only `darwin-arm64` binaries.
+2. More fundamentally, Cocos Creator already has its own `sharp` **0.32.6**
+   (libvips 8.14) resident in the same process. On Windows a second libvips cannot
+   be loaded beside the first, so the extension's `sharp` 0.34.x binds against the
+   editor's older DLL. That DLL has no JPEG 2000 support, `format.jp2k` comes back
+   undefined, and the module throws while initialising — taking the whole plugin
+   with it.
+
+**Fix.** [asset-tools.js](../extensions/cocos-code-mode/dist/utcp/tools/asset-tools.js)
+now loads `sharp` lazily, prefers the editor's own resident build under
+`process.resourcesPath/app.asar.unpacked/node_modules/sharp`, and tolerates it
+being unavailable. `sharp` is only a fast path for `assetGetPreview`, which
+already had a renderer-based fallback, so a missing image library no longer stops
+the tool server from starting.
+
+That file is tracked by git, so the fix survives — but **re-importing the extension
+from a release zip will overwrite it.** If the extension is ever re-imported,
+re-apply the patch and, on Windows, also install the matching native binaries:
+
+```bash
+cd extensions/cocos-code-mode && npm install --no-save --os=win32 --cpu=x64 --include=optional sharp@0.34.5
+```
+
+(`extensions/cocos-code-mode/node_modules` is gitignored, so that install does not
+survive a clean checkout either.)