Cocos Code Mode

Cocos Creator的代码模式

代码模式 将Cocos Creator Editor变成一个人工智能可控的工具。它在编辑器内运行一个HTTP服务器，通过以下方式将场景操作、资产管理和属性检查作为结构化工具调用公开 UTCP协议 --让AI代理以开发人员通过UI的方式构建、检查和修改Cocos Creator项目。 这些工具组合在一起 UTCP编码模式 环境，为AI代理实现最大的性能和令牌效率，让他们在隔离的JS沙箱中调用工具。

快速启动

1. 安装扩展 在Cocos Creator项目中
2. 整合 使用CodeMode MCP服务器进行扩展
3. 为您的代理或用户设计一个系统提示 提供示例
4. 请人工智能帮助你，看看它是如何学习的！

什么是代码模式？

与始终保持在LLM上下文中的严格MCP工具防御相反，CodeMode是一种帮助AI以最熟悉的方式调用工具的方法——通过基于TypeScript工具防御编写JavaScript代码。这有助于人工智能保持低令牌消耗，实现复杂任务的循环和链式调用，以紧凑的形式组织输出，并在一个JavaScript执行上下文中重用来自不同现有服务器和端点的输出，将LLM上下文与不必要的数据隔离开来。 这为不同环境之间的互动开辟了无限的可能性。以下是一些示例：

1. 使用以下命令从混合器中移动场景 搅拌机MCP，将特定对象作为FBX直接导出到Cocos项目中
2. 使用 Figma MCP 从figma获取UI布局，并以智能的方式在项目中实现这些布局，而不是盲目地重新创建每个面板
3. 使用 Unity代码模式 在引擎之间执行游戏移植
4. 带上你自己的例子🙃

所有这一切都可以通过UTCP团队提供的社区友好、灵活和开放的解决方案来实现： 代码模式 它是MCP服务器。 您可以在以下论文中阅读更多关于代码模式概念的信息： Anthropic, 苹果 和 云耀.

工具

Tools <> UI Mapping

运作原理

此扩展架构遵循 发现，然后行动 图案。AI代理从不猜测属性名称或组件结构——它们首先查询真实的定义。

1. Get the scene tree         →  find the node you need
2. Get its type definition    →  learn its actual properties
3. Set properties by name     →  make precise changes

示例

// Find the camera node
const tree = CocosEditor.nodeGetTree({});
const cameraRef = tree.children[0].components[0]; // component reference

// Discover what properties Camera has
const def = CocosEditor.inspectorGetInstanceDefinition({ reference: cameraRef });
// → "export class Camera { fov: number; near: number; far: number; ... }"

// Set multiple properties in one call
CocosEditor.inspectorSetInstanceProperties({
  reference: cameraRef,
  propertyPaths: ["fov", "near", "far"],
  values: [60, 0.1, 1000]
});

建筑

工具执行

该扩展在可配置端口上运行Express.js HTTP服务器（默认：自动分配）。工具处理程序使用Cocos Creator的编辑器消息API异步执行-所有编辑器交互都经过 Editor.Message.request，它将调用编组到相应的编辑器子系统。

• 阅读工具 （GET）——查询场景状态并立即返回结构化数据。
• 编写工具 （POST）--改变场景状态并调用 Editor.Message.request('scene', 'snapshot') 将更改注册为可撤消步骤。

这意味着AI代理可以安全地链接读取调用和批处理写入，而不会阻塞编辑器。

工具发现

工具是用以下代码装饰的TypeScript类方法 @utcpToolThe ToolRegistry 在启动时收集它们，从内联定义构建JSON模式，并在 /utcp 终点。

export class SceneTools {

    @utcpTool(
        'nodeGetTree',
        'Get the hierarchy tree of specific node or scene root if no reference is provided.',
        {
            type: 'object',
            properties: {
                reference: InstanceReferenceSchema
            }
        },
        SceneTreeItemSchema, "GET", ['scene', 'graph', 'node', 'hierarchy', 'tree']
    )
    async nodeGetTree(args: { reference?: IInstanceReference }): Promise {
        // ...
    }
}

实例引用

节点、组件和资产作为基于UUID的轻量级句柄传递：

{ id: "a1b2c3d4-...", type: "cc.Camera" }

由树查询、组件查找和创建工具返回。传递回需要针对特定对象的任何工具。

TypeScript定义

Code Mode从实时编辑器属性转储动态生成TypeScript类定义。当AI代理呼叫时 inspectorGetInstanceDefinition，它接收一个完整的TypeScript类，其中包含正确的字段名、类型、枚举和装饰器提示，包括 @property 属性如 min, max, unit，以及 tooltip.

// Example output for a Transform-like node
export class Node {
    readonly uuid: string;
    /** World position */
    worldPosition: Vec3;
    /** World rotation (euler angles) */
    worldRotation: Vec3;
    worldScale: Vec3;
    active: boolean;
}

没有特殊处理的组件会自动从序列化属性转储中反映出来。常见的Cocos数学类型(Vec2, Vec3, Vec4, Color, Rect, Quat, Mat4, Gradient等）始终可通过以下方式获得 inspectorGetSettingsDefinition({ settingsType: 'CommonTypes' }).

设置检查

可以直接检查和修改两种特殊设置类型：

• CurrentSceneGlobals --环境光、天空盒、阴影和其他场景级渲染设置。
• ProjectSettings --引擎和项目配置。

安装

从发布

1. 从此存储库下载最新版本。
2. 打开Cocos Creator，转到 扩展→ 扩展管理器，然后单击 Import Extension File(.zip) 按钮（带箭头的图标）。
3. 选择下载的zip文件。
4. UTCP服务器自动启动并在中注册 ~/.utcp_config.json 默认情况下。

从源代码构建

1. 克隆此存储库。
2. 安装 node 和 npm.
3. 跑

git clone https://github.com/romarogov/cocos-code-mode.git
cd cocos-code-mode
npm i
npm run package

1. 如果一切顺利， cocos-code-mode.zip 文件应出现在存储库根目录中。
2. 在Cocos Creator中安装它 扩展管理器.

添加自定义工具

您应该在扩展包中添加自定义工具，并如上所述从源代码构建它。

实施示例：

import { utcpTool } from './utcp/decorators';

export class MyTools {

    @utcpTool(
        'myCustomTool',
        'Describe what this tool does',
        {
            type: 'object',
            properties: {
                input: { type: 'string' },
                count: { type: 'number', default: 10 }
            },
            required: ['input']
        },
        { type: 'object', properties: { result: { type: 'string' } } },
        "POST",
        ['custom', 'tags']
    )
    async myCustomTool(args: { input: string, count?: number }): Promise {
        // Implementation
    }
}

通过将类导入来注册它 utcp-server.ts工具在启动时自动提供。无需额外注册。

UTCP呼叫模板配置

该扩展提供了 配置 面板可从 代码模式 顶部菜单。它显示了当前服务器端口、UTCP配置文件的路径，并允许您管理其他UTCP调用模板，以将其他与UTCP兼容的工具提供程序（包括MCP服务器）连接到相同的代码模式执行上下文中。

您可以在中找到呼叫模板结构 UTCP文件:

• MCP呼叫模板
• HTTP调用模板 (可流式传输, 上海证券交易所)
• CLI调用模板
• 文本通话模板

扩展程序会自动维护 CocosEditor UTCP配置中指向正在运行的服务器端口的条目。

整合

代码模式适用于任何兼容UTCP的客户端，包括 代码模式MCP服务器 AI助手。

MCP服务器配置

{
  "mcpServers": {
    "code-mode": {
      "command": "npx",
      "args": ["@utcp/code-mode-mcp"],
      "env": {
        "UTCP_CONFIG_FILE": "~/.utcp_config.json"
      }
    }
  }
}

Claude代码配置

要设置Claude Code代理以使用代码模式，请打开项目并运行：

Linux/MacOS：

claude mcp add --transport stdio --env UTCP_CONFIG_FILE="~/.utcp_config.json" -- code-mode npx @utcp/code-mode-mcp

窗户：

claude mcp add --transport stdio --env UTCP_CONFIG_FILE="%userprofile%/.utcp_config.json" -- code-mode cmd /c npx @utcp/code-mode-mcp