Патчи к 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,485 @@
+# 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;
+}
+```