Cocos Creator的代码模式
代码模式 将Cocos Creator Editor变成一个人工智能可控的工具。它在编辑器内运行一个HTTP服务器，通过以下方式将场景操作、资产管理和属性检查作为结构化工具调用公开 UTCP协议 --让AI代理以开发人员通过UI的方式构建、检查和修改Cocos Creator项目。 这些工具组合在一起 UTCP编码模式 环境，为AI代理实现最大的性能和令牌效率，让他们在隔离的JS沙箱中调用工具。
快速启动
什么是代码模式？
与始终保持在LLM上下文中的严格MCP工具防御相反，CodeMode是一种帮助AI以最熟悉的方式调用工具的方法——通过基于TypeScript工具防御编写JavaScript代码。这有助于人工智能保持低令牌消耗，实现复杂任务的循环和链式调用，以紧凑的形式组织输出，并在一个JavaScript执行上下文中重用来自不同现有服务器和端点的输出，将LLM上下文与不必要的数据隔离开来。 这为不同环境之间的互动开辟了无限的可能性。以下是一些示例：
- 使用以下命令从混合器中移动场景 搅拌机MCP，将特定对象作为FBX直接导出到Cocos项目中
- 使用 Figma MCP 从figma获取UI布局，并以智能的方式在项目中实现这些布局，而不是盲目地重新创建每个面板
- 使用 Unity代码模式 在引擎之间执行游戏移植
- 带上你自己的例子🙃
所有这一切都可以通过UTCP团队提供的社区友好、灵活和开放的解决方案来实现： 代码模式 它是MCP服务器。 您可以在以下论文中阅读更多关于代码模式概念的信息： Anthropic, 苹果 和 云耀.
工具
| 类别 | 工具 | 目的 |
|---|---|---|
| 场景 | nodeGetTree, nodeGetAtPath, nodeCreate, nodeCreatePrimitive, nodeOperate | 导航并构建场景层次结构 |
| 组件 | nodeComponentsGet, nodeComponentAdd, nodeComponentRemove, nodeGetAvailableComponentTypes | 连接、拆卸和查找组件 |
| 检查员 | inspectorGetInstanceDefinition, inspectorGetSettingsDefinition, inspectorGetInstanceProperties, inspectorGetSettingsProperties, inspectorSetInstanceProperties, inspectorSetSettingsProperties | 内省类型和读/写属性 |
| 资产 | assetGetTree, assetGetAtPath, assetCreate, assetImport, assetOperate, assetGetPreview | 浏览、创建和管理项目资产 |
| 编辑 | editorOperate, editorGetLogs, editorGetScenePreview | 控制编辑器状态和捕获预览 |
运作原理
此扩展架构遵循 发现，然后行动 图案。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--引擎和项目配置。
安装
从发布
- 从此存储库下载最新版本。
- 打开Cocos Creator，转到 扩展→ 扩展管理器，然后单击
Import Extension File(.zip)按钮（带箭头的图标）。 - 选择下载的zip文件。
- UTCP服务器自动启动并在中注册
~/.utcp_config.json默认情况下。
从源代码构建
- 克隆此存储库。
- 安装
node和npm. - 跑
git clone https://github.com/romarogov/cocos-code-mode.git
cd cocos-code-mode
npm i
npm run package- 如果一切顺利，
cocos-code-mode.zip文件应出现在存储库根目录中。 - 在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文件:
扩展程序会自动维护 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