fool-cardgame/docs/CODE_MODE_TOOLS.md

# Code Mode tool reference (`CocosEditor`)

Generated from the live UTCP manual served by the `cocos-code-mode` extension
(UTCP 1.0.1, 24 tools). Regenerate with the command in
[CODE_MODE_SETUP.md](CODE_MODE_SETUP.md) whenever the extension is updated.

All tools are called as `CocosEditor.<name>({ ... })` inside a `utcp run` script.
Calls look synchronous — the host bridges the async work, so no `await` is needed.

## Conventions

Nodes, components and assets are passed around as UUID handles:

```ts
interface IInstanceReference { id: string; type?: string; } // e.g. { id: "a1b2…", type: "cc.Sprite" }
```

Work **discover, then act**: get the tree, get the type definition, then set properties by name.
Never guess property names — `inspectorGetInstanceDefinition` returns the real TypeScript class.

## Scene graph

### `nodeGetTree`

Get the hierarchy tree of specific node or scene root if no reference is provided. Children have recursive structure.

```ts
CocosEditor.nodeGetTree(args: {
  reference?: {
    id: string;
    type?: string;
  };
}): {
  path?: string;
  reference: {
    id: string;
    type?: string;
  };
  name: string;
  active: boolean;
  components: {
    id: string;
    type?: string;
  }[];
  children: Record<string, unknown>[];
}
```

### `nodeGetAtPath`

Get nodes at specific path in the scene hierarchy. Usually returns one node, but can return multiple nodes with the same name.

```ts
CocosEditor.nodeGetAtPath(args: {
  hierarchyPath: string; // Path to the node in the scene hierarchy"
}): {
  references?: {
    id: string;
    type?: string;
  }[];
}
```

### `nodeCreate`

Create a new node in the scene. If no parent is specified, root node is used. Returns reference to the new node.

```ts
CocosEditor.nodeCreate(args: {
  name: string;
  parentReference?: {
    id: string;
    type?: string;
  };
  assetReference?: {
    id: string;
    type?: string;
  };
  unwrapPrefab?: boolean; // default: false
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `nodeCreatePrimitive`

Create a new node with predefined primitive geometry MeshRenderer. If no parent is specified, root node is used. Returns reference to the new node.

```ts
CocosEditor.nodeCreatePrimitive(args: {
  name: string;
  primitiveType: "Capsule" | "Cone" | "Cube" | "Cylinder" | "Plane" | "Quad" | "Sphere" | "Torus";
  parentReference?: {
    id: string;
    type?: string;
  };
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `nodeOperate`

Perform operation on referenced node, including prefab operations.

```ts
CocosEditor.nodeOperate(args: {
  operation: "move" | "copy" | "delete" | "create_prefab" | "revert_prefab" | "apply_prefab" | "unwrap_prefab" | "unwrap_prefab_completely" | "open_prefab";
  reference: {
    id: string;
    type?: string;
  };
  newParentReference?: {
    id: string;
    type?: string;
  };
  newPrefabPath?: string; // For create_prefab: target db:// path
  siblingIndex?: integer; // For move/copy: target index in parent children array
}): {
  success?: boolean;
  createdPrefabAssetReference?: {
    id: string;
    type?: string;
  };
  updatedNodeReference?: {
    id: string;
    type?: string;
  };
  copiedNodeReference?: {
    id: string;
    type?: string;
  };
}
```

## Components

### `nodeComponentsGet`

Get components of specific type on a node. If componentType is not provided, returns all components on the node.

```ts
CocosEditor.nodeComponentsGet(args: {
  reference: {
    id: string;
    type?: string;
  };
  componentType?: string;
}): {
  references: {
    id: string;
    type?: string;
  }[];
}
```

### `nodeComponentAdd`

Add a component to a referenced node, returns reference to the new component

```ts
CocosEditor.nodeComponentAdd(args: {
  reference: {
    id: string;
    type?: string;
  };
  componentType: string;
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `nodeComponentRemove`

Remove referenced component from node it is attached to.

```ts
CocosEditor.nodeComponentRemove(args: {
  reference: {
    id: string;
    type?: string;
  };
}): {
  success: boolean;
  error?: string;
}
```

### `nodeGetAvailableComponentTypes`

Get list of globally available component types (class names) at the moment.

```ts
CocosEditor.nodeGetAvailableComponentTypes(args: {
  includeInternal: boolean; // Whether to include internal engine components. — default: false
  filter?: string; // Optional filter string to match component types or categories (case-insensitive substring match).
}): {
  componentTypes: string[];
}
```

## Inspector (types & properties)

### `inspectorGetInstanceDefinition`

Generates TypeScript definition based on properties and descriptions of instance (Node, Component, Asset).

```ts
CocosEditor.inspectorGetInstanceDefinition(args: {
  reference: {
    id: string;
    type?: string;
  };
}): {
  definition: string;
}
```

### `inspectorGetSettingsDefinition`

Generates TypeScript definition for specific settings.

```ts
CocosEditor.inspectorGetSettingsDefinition(args: {
  settingsType: "CommonTypes" | "CurrentSceneGlobals" | "ProjectSettings";
}): {
  definition: string;
}
```

### `inspectorGetInstanceProperties`

Gets plain object of properties, with no serialization info for any instance (scene node, component, asset).

```ts
CocosEditor.inspectorGetInstanceProperties(args: {
  reference: {
    id: string;
    type?: string;
  };
}): {
  dump: Record<string, unknown>;
}
```

### `inspectorGetSettingsProperties`

Gets plain object of properties for the specific settings.

```ts
CocosEditor.inspectorGetSettingsProperties(args: {
  settingsType: "CurrentSceneGlobals" | "ProjectSettings";
}): {
  dump: Record<string, unknown>;
}
```

### `inspectorSetInstanceProperties`

Sets a property on instance of Node, Component or Asset. If a property path or type is not confirmed via inspectorGet* tools, you MUST NOT call any setter.

```ts
CocosEditor.inspectorSetInstanceProperties(args: {
  reference: {
    id: string;
    type?: string;
  };
  propertyPaths: string[]; // Plain paths to the properties (e.g., ['position.x', 'rotation.y']). Don't support code execution. Arrays are reached by indexes. (e.g. 'sharedMaterials.0')
  values: array,object,string,number,boolean,null[];
}): {
  success: boolean;
  error?: string;
}
```

### `inspectorSetSettingsProperties`

Sets a property on the specific settings. If a property path or type is not confirmed via inspectorGet* tools, you MUST NOT call any setter.

```ts
CocosEditor.inspectorSetSettingsProperties(args: {
  settingsType: "CurrentSceneGlobals" | "ProjectSettings";
  propertyPath: string; // Plain path to the property (e.g., 'ambient.skyLightingColor.r'). Don't support code execution.
  value: array,object,string,number,boolean,null;
}): {
  success: boolean;
  error?: string;
}
```

## Assets

### `assetGetTree`

Get the asset and subAsset hierarchy tree. Children have recursive structure.

```ts
CocosEditor.assetGetTree(args: {
  reference?: {
    id: string;
    type?: string;
  };
  assetPath?: string; // Root path to start from
}): {
  filesystemPath?: string;
  reference: {
    id: string;
    type?: string;
  };
  name: string;
  children: Record<string, unknown>[];
}
```

### `assetGetAtPath`

Get asset reference by given local path and name, including extension. Can be used for subassets too. Returns reference to the asset.

```ts
CocosEditor.assetGetAtPath(args: {
  assetPath: string;
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `assetCreate`

Create empty asset or folder of given type. Automatically handles folders creation along the path. Returns reference to the new asset.

```ts
CocosEditor.assetCreate(args: {
  assetPath: string;
  preset: "folder" | "material" | "effect" | "scene" | "prefab" | "typescript" | "animation-clip" | "render-texture" | "physics-material" | "animation-graph" | "animation-graph-variant" | "animation-mask" | "auto-atlas" | "effect-header" | "label-atlas" | "terrain"; // Preset type for the new asset
  options?: {
    overwrite?: boolean;
    rename?: boolean;
  }; // Additional options for the operation
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `assetImport`

Import an external file as an asset into the project. Path must end with the extension. Returns reference to the new asset.

```ts
CocosEditor.assetImport(args: {
  sourceFilesystemPath: string; // Source filesystem path of the file to import
  targetAssetPath: string; // Target path in the asset database
  imageType?: "raw" | "texture" | "normal-map" | "sprite-frame" | "texture-cube"; // For image files, specify how to import them
  options?: {
    overwrite?: boolean;
    rename?: boolean;
  }; // Additional options for the operation
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `assetOperate`

Perform operations on assets (move, copy, delete, open). Returns reference to the affected asset (for delete/open returns the source asset reference).

```ts
CocosEditor.assetOperate(args: {
  operation: "move" | "copy" | "delete" | "open" | "refresh" | "reimport";
  reference: {
    id: string;
    type?: string;
  };
  targetAssetPath?: string; // Target path (for move/copy/import)
  options?: {
    overwrite?: boolean;
    rename?: boolean;
  }; // Additional options for the operation
}): {
  reference: {
    id: string;
    type?: string;
  };
}
```

### `assetGetPreview`

Returns preview image of the asset (Prefab, Image, Model or Material is supported). IMPORTANT: To visualize the image, you must return the result of this function DIRECTLY as the final value of your code, do NOT wrap it in an object.

```ts
CocosEditor.assetGetPreview(args: {
  reference: {
    id: string;
    type?: string;
  };
  imageSize?: number; // Size of the preview image (square) — default: 512
  jpegQuality?: integer; // JPEG Quality of the preview image — default: 80
  transparentColor?: {
    r: integer;
    g: integer;
    b: integer;
  }; // Background color for transparent images in RGB format
}): {
  type: string;
  data: string;
  mimeType: string;
}
```

## Editor

### `editorOperate`

Common editor operations for scene and prefab view, game preview controls and asset database refresh

```ts
CocosEditor.editorOperate(args: {
  operation: "save_scene_or_prefab" | "close_scene_or_prefab" | "play_preview" | "pause" | "step" | "stop" | "refresh";
}): {
  success: boolean;
  error?: string;
}
```

### `editorGetLogs`

Get last N editor log entries

```ts
CocosEditor.editorGetLogs(args: {
  count: number; // Number of log entries to retrieve — default: 10
  showStack?: boolean; // Return full stack trace for each log entry
  order: "newest-to-oldest" | "oldest-to-newest"; // Order of logs — default: "newest-to-oldest"
}): {
  logLines: string[];
}
```

### `editorGetScenePreview`

Returns preview image of scene view. IMPORTANT: To visualize the image, you must return the result of this function DIRECTLY as the final value of your code, do NOT wrap it in an object.

```ts
CocosEditor.editorGetScenePreview(args: {
  imageSize?: {
    width?: number; // default: 512
    height?: number; // default: 512
  };
  jpegQuality?: integer; // default: 80
  cameraPosition: {
    x: number;
    y: number;
    z: number;
  }; // Camera world position
  targetPosition: {
    x: number;
    y: number;
    z: number;
  }; // Point the camera looks at
  orthographic?: boolean; // Whether to use orthographic projection — default: false
  orthographicSize?: number; // Orthographic size (only applies if orthographic is true) — default: 10
}): {
  type: string;
  data: string;
  mimeType: string;
}
```