fool-cardgame/docs/CODE_MODE_SETUP.md

# 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.)

## Known issue: the setter tools take arrays, not a single path

[CODE_MODE_TOOLS.md](CODE_MODE_TOOLS.md) is generated from the manual the
extension serves, and for `inspectorSetInstanceProperties` /
`inspectorSetSettingsProperties` that manual advertises a singular
`propertyPath` + `value` pair. The implementation actually loaded
([set-properties-tool.js](../extensions/cocos-code-mode/dist/utcp/tools/set-properties-tool.js))
expects parallel arrays, and the singular form fails with the unhelpful
`Cannot read properties of undefined (reading 'length')`.

Use:

```js
CocosEditor.inspectorSetSettingsProperties({
  settingsType: 'ProjectSettings',
  propertyPaths: ['general.designResolution.width', 'general.fitWidth'],
  values: [1080, true],
});
```

## Known issue: `nodeCreate` puts nodes on the wrong layer for UI

A node created with `nodeCreate` lands on the **DEFAULT** layer
(`1073741824`). A Canvas camera is normally set to render **UI_2D**
(`33554432`) only, so every node authored through the tools is invisible at
runtime — the camera draws its clear colour and nothing else, which looks like
the game has frozen on a blank coloured screen.

The editor's own "create node" menu assigns UI_2D, so this only bites
automation, and nothing in the editor viewport reveals it: the scene-view camera
renders every layer, so the scene looks perfectly fine while the build does not.

**Always set the layer after creating a UI node:**

```js
const UI_2D = 33554432;
CocosEditor.inspectorSetInstanceProperties({
  reference: newNode, propertyPaths: ['layer'], values: [UI_2D],
});
```

To check a whole scene, walk `nodeGetTree` and assert every node's `layer`.