103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# 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.)
|