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 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:

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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

inspectorGetSettingsDefinition

Generates TypeScript definition for specific settings.

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

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

inspectorGetSettingsProperties

Gets plain object of properties for the specific settings.

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.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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;
}