Skip to main content
Glama

UPilot

让 Codex、Claude Code、Cursor、OpenCode 等 AI Agent 直接操作 Unity Editor。

UPilot 会在 Unity 中启动本地 MCP 服务,并为常见 Agent 自动写入项目级连接配置。配置完成后,你可以直接让 Agent 查看场景、检查编译错误、读取 Console、修改 GameObject、管理资源、运行测试或构建任务。

Unity:2022.3 或更高

正式版使用独立 MCP Server,由 UPilot 下载并管理,无需另外安装运行环境。

默认 MCP 地址:http://127.0.0.1:8011/mcp

教程截图来自 Windows 上的 Unity 2022.3。不同 Unity 版本或编辑器主题下,界面外观可能略有差异,请以实际界面提示为准。

2 分钟上手

安装 Unity 包 → 按向导安装服务并配置 Agent → 验证连接,即可开始使用。首次下载和 Unity 编译的耗时取决于网络与项目规模。

1. 安装 Unity 包

在 Unity 中打开:

Window > Package Manager

点击左上角 +,选择 Add package from git URL...,输入:

https://github.com/codingriver/upilot.git#v0.3.44

点击 Add,等待 Unity 完成包导入和脚本编译。这里以固定发布版本 v0.3.44 为例;安装其他正式版本时,将链接末尾的标签替换为对应的 vMAJOR.MINOR.PATCH。

在 Package Manager 中输入 UPilot Git URL

输入 UPilot Git URL 后点击右侧 Add。

2. 在 Unity 中安装服务并配置 Agent

包导入完成后,Unity 会自动打开 UPilot 设置界面。如果没有自动打开,请选择:

UPilot > 打开 UPilot

然后:

  1. 在设置向导的 网络端口 步骤使用推荐端口,点击 下一步。

  2. 在 服务安装 步骤点击 下一步。UPilot 会下载、校验并保存独立服务配置,成功后自动进入 Agent 配置。

  3. 选择你正在使用的 Agent:Codex、Claude Code、Cursor 或 OpenCode,支持多选。

  4. 保持启动选项勾选,点击 写入配置并启动,等待主界面显示 已就绪。

UPilot 首次配置界面

按设置向导安装服务、选择常用 Agent,再写入配置并启动。

UPilot 会自动选择可用端口、写入所选 Agent 的 MCP 配置,并同步所需的 Skill/规则。

3. 重启 Agent 并验证

首次写入配置后,请重新启动 Agent 客户端,或重新加载当前项目窗口,使 MCP 工具列表刷新。

然后对 Agent 说:

请调用 unity_mcp_status,确认 UPilot 已连接,并检查当前 Unity 工程路径。

成功时应满足:

  • connected: true

  • serverReady: true

  • 返回的 Unity 工程路径与当前项目一致

现在可以开始使用 UPilot。

在 高级设置 → 常规 → 周期与超时 中,可配置心跳、Health、Domain Reload 复核、窗口观察、包更新恢复、重连和界面刷新。详见周期与超时配置及四阶段实施清单。Bridge 心跳默认 3 秒,HTTP Health 默认 10 秒;服务验证就绪后,Health 由服务统一持有,所有窗口关闭后仍运行,多开窗口不增加检查器。周期设置调整后续调度,有限观察保留开始时固定的期限;长心跳间隔不会放宽 Editor 主线程新鲜度要求。四阶段实现、规范项目定向验收和服务刷新已完成,证据及未覆盖范围见2026-10-14 验证记录。

Related MCP server: Unity MCP Server

UPilot 能做什么

UPilot 是 AI Agent 与 Unity Editor 之间的桥梁:Agent 通过 MCP 工具读取真实的 Unity 状态,并在授权后执行修改,而不只是生成一段代码供你手动粘贴。

功能

可以让 Agent 做什么

项目与场景检查

读取工程路径、Editor 状态、已打开场景、对象层级和组件信息

场景与对象编辑

创建或修改 GameObject、Transform、Component,管理场景与 Prefab

资源与项目设置

查找、导入和管理资源,处理材质、贴图及项目设置

编译与 Console 诊断

查看 Unity 编译结果、定位 Error/Warning,修改脚本后同步并等待编译验证

测试与构建

运行 Unity 测试或构建任务,查询进度并获取最终结果和产物

截图与日志取证

获取编辑器画面、采集 Console 日志,为问题定位和测试保留证据

自动化步骤(UPilot Step)

将业务测试组织为完整步骤计划,由执行器统一处理超时、取消、清理和报告

受控 C# 执行

调用已加载方法、验证并执行受限 C# 语句,用会话管理跨调用状态

Agent 自动配置

为 Codex、Claude Code、Cursor、OpenCode 配置 MCP 连接,并同步规则和 Skill

多项目连接

为不同 Unity 项目分配独立端口,通过返回的工程路径确认操作目标

可选高级功能

UPilot Flow 编排 Editor 界面操作;UPilot 追踪器按过滤条件观察对象事件

具体工具是否可调用取决于当前 Unity 连接、功能开关与项目授权。Flow 和追踪器默认关闭,入门使用无需启用。修改脚本、资源或项目设置前,请确认目标并按界面提示授权。

环境要求

项目

要求

Unity

2022.3 或更高版本

系统

当前正式版独立服务提供 Windows x64 可执行程序

Agent

Codex、Claude Code、Cursor、OpenCode,或支持 Streamable HTTP MCP 的客户端

Git

Unity 通过 Git URL 安装包时需能调用 Git

网络

首次安装 Unity 包和独立服务时需要访问 GitHub

UPilot 默认只监听本机地址 127.0.0.1。Unity Editor 必须保持打开,Agent 才能操作当前项目。

完整安装教程

方式一:通过 Unity Package Manager 安装(推荐)

  1. 打开 Unity 项目。

  2. 选择 Window > Package Manager。

  3. 点击左上角 +。

  4. 选择 Add package from git URL...。

  5. 输入以下地址并点击 Add:

从 Package Manager 打开 Git URL 安装入口

点击左上角加号,然后选择“Add package from git URL...”。

https://github.com/codingriver/upilot.git#v0.3.44

安装完成后,Package Manager 中应显示包名 UPilot,包标识为:

io.github.codingriver.upilot

方式二:手动修改 manifest.json

如果 Package Manager 无法添加 Git URL,可以打开 Unity 项目的 Packages/manifest.json,在 dependencies 中加入:

{
  "dependencies": {
    "io.github.codingriver.upilot": "https://github.com/codingriver/upilot.git#v0.3.44"
  }
}

如果文件中已有其他依赖,请只增加这一项,并注意上一项末尾的逗号。保存后返回 Unity,等待包解析和脚本编译完成。

首次配置教程

使用设置向导(推荐)

首次导入正式版 UPilot 后,按设置向导完成以下操作:

  1. 使用推荐的网络端口,进入下一步。

  2. 在 服务安装 步骤点击 下一步,直接开始下载独立 MCP Server。下载、文件校验与配置保存完成后,自动进入 Agent 配置。

  3. 选择常用 Agent,保持启动选项勾选,点击 写入配置并启动。

  4. 等待主界面状态变为 已就绪。

如果匹配的服务已就绪,点击 下一步 即可继续;也可以通过 选择本地服务文件 指定已下载的正式版独立服务,按界面提示完成检查。

服务安装过程中会显示下载与校验进度,主按钮暂时禁用;可以取消下载,取消后留在当前步骤。安装失败时显示具体原因,点击 重试 重新安装。服务启动与连接验证在第 3 步点击 写入配置并启动 后进行。

UPilot 首次配置界面

Codex、Claude Code、Cursor 和 OpenCode 可以单选或多选。

选择多个 Agent 时,UPilot 会同时写入这些 Agent 的项目级 MCP 配置。之后也可以在主界面的 Agent 配置 区域单独添加其他 Agent。

配置过程中会发生什么

UPilot 会自动处理以下内容:

  • 下载、校验并管理独立 MCP Server(首次安装服务时)。

  • 为当前 Unity 项目选择可用的本地端口。

  • 启动 Unity Bridge 和 MCP 服务。

  • 写入所选 Agent 的项目级 MCP 连接。

  • 写入或更新 UPilot 管理的 Agent 规则。

  • 同步 UPilot Skill:Codex、Cursor 与 OpenCode 使用共享的 .agents/skills 安装,Claude Code 使用 .claude/skills 安装。

已有配置文件中的其他 MCP 服务和用户内容会尽量保留。UPilot 管理的内容使用独立标记或独立配置项进行更新。

MCP 地址

默认地址是:

http://127.0.0.1:8011/mcp

实际地址会显示在 UPilot 主界面的 MCP 地址 区域,点击 复制 即可复制。

请始终使用界面显示的实际地址。多项目或端口冲突时,UPilot 可能会选择其他 HTTP 端口。

不要把 Unity Bridge 的 WebSocket 地址配置给 Agent。WebSocket 仅供 UPilot 内部连接使用。

Codex、Claude Code、Cursor 与 OpenCode

推荐通过 Unity 的 UPilot 界面自动配置。以下内容仅用于检查配置或自动配置不可用时手动处理。

Codex

项目配置文件:

.codex/config.toml

配置内容:

[mcp_servers.upilot]
url = "http://127.0.0.1:8011/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 300

Codex 还会使用项目中的 AGENTS.md 和 .agents/skills/upilot-unity-mcp。因此,除了 MCP 配置外,建议同时在 UPilot 界面更新 Skill。

Claude Code

项目配置文件:

.mcp.json

配置内容:

{
  "mcpServers": {
    "upilot": {
      "type": "http",
      "url": "http://127.0.0.1:8011/mcp"
    }
  }
}

Claude Code 的 UPilot 使用规则会同步到项目规则文件中,按需工作流安装在:

.claude/skills/upilot-unity-mcp

Cursor

项目配置文件:

.cursor/mcp.json

配置内容:

{
  "mcpServers": {
    "upilot": {
      "url": "http://127.0.0.1:8011/mcp"
    }
  }
}

Cursor 的 UPilot 规则位于:

.cursor/rules/upilot-unity-mcp.mdc

Cursor 官方支持项目级 .agents/skills,因此与 Codex 共享:

.agents/skills/upilot-unity-mcp

OpenCode

项目配置文件优先使用:

opencode.json

如果项目已经使用 opencode.jsonc,UPilot 会保留该文件并只更新其中的 mcp.upilot:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upilot": {
      "type": "remote",
      "url": "http://127.0.0.1:8011/mcp",
      "enabled": true,
      "timeout": 30000
    }
  }
}

OpenCode 原生读取项目根目录 AGENTS.md,并与 Codex、Cursor 共享:

.agents/skills/upilot-unity-mcp

OpenCode 还会发现 .claude/skills 和 .opencode/skills。如果多个目录存在同名 upilot-unity-mcp,UPilot 会比较内容哈希;内容不同会显示为 Skill 冲突,不能标记为已就绪。

手动修改配置后,请重启或刷新 Agent 客户端。

如何确认安装成功

在 Unity 中确认

打开 UPilot > 打开 UPilot,检查:

  • 顶部状态为 已就绪。

  • 主界面显示 MCP 地址。

  • 常用 Agent 显示 MCP 已配置。

  • Codex、Claude Code、Cursor 和 OpenCode 都显示独立的规则、MCP 配置与 Skill 状态。

在浏览器中检查服务

打开:

http://127.0.0.1:8011/health

如果 UPilot 使用了其他端口,请把 8011 替换成主界面显示的端口。

直接用浏览器打开 /mcp 可能返回 406 Not Acceptable,这是正常现象,因为 /mcp 是 MCP 通信端点,不是普通网页。健康检查应使用 /health。

在 Agent 中确认

发送:

请调用 unity_mcp_status,并告诉我:
1. connected 和 serverReady 是否为 true;
2. 当前连接的 Unity 工程路径;
3. Unity 是否正在编译或进入 Play Mode。

如果返回的工程路径不是你正在处理的项目,请先停止操作,切换到正确的 MCP 地址后再继续。

第一次使用 UPilot

建议先从只读任务开始,确认连接和项目识别都正确。

查看项目与场景

请使用 UPilot 检查当前 Unity 项目、已打开场景和场景层级,只做分析,不修改任何内容。

检查编译错误

请使用 UPilot 检查当前 Unity 编译状态和编译错误,说明错误原因,暂时不要修改代码。

检查 Console

请使用 UPilot 读取最近的 Unity Console Error 和 Warning,并按优先级汇总。

修改场景对象

请使用 UPilot 在当前场景创建一个名为 TestRoot 的空 GameObject,创建前先确认当前场景,完成后再次读取对象验证结果。

修复代码并编译

请分析当前编译错误,修复相关 C# 代码,然后让 Unity 同步并编译,最后确认没有新的编译错误。

运行测试或长任务

请使用 UPilot 运行项目的 EditMode 测试,持续查询任务状态,直到成功、失败或取消,并汇总最终结果。

对于测试、构建和其他异步任务,仅“开始执行”不代表完成。应要求 Agent 持续查询,直到得到最终结果。

主界面说明

通过 UPilot > 打开 UPilot 打开主界面。

UPilot 已就绪主界面

主界面优先显示整体状态、Agent 是否可用和 MCP 地址;版本、端口与内部连接信息收纳在“运行详情”中。

服务状态

  • 已就绪:可以直接让 Agent 操作 Unity。

  • 正在启动/正在重启:等待几秒钟,不需要重复点击。

  • 需要修复:点击 自动修复,UPilot 会尝试修复服务路径、端口或连接。

  • 已停止:点击 启动 UPilot。

重启 UPilot

服务已就绪时,点击右上角 ⋮ > 重新启动。重启会同时重建 MCP 服务和 Unity 连接,常用于:

  • Agent 突然无法调用工具。

  • Unity 重新加载脚本后连接未恢复。

  • 修改端口或服务设置后重新连接。

  • MCP 工具调用持续超时。

重启 UPilot 后,如果 Agent 的工具列表仍未刷新,再重启或重新加载 Agent 客户端。

Agent 配置

主界面会列出 Codex、Claude Code、Cursor 和 OpenCode,默认只显示“已就绪”“需更新”“未配置”或“异常”等最终状态。展开任意 Agent 后,都会以相同顺序和相同视觉权重显示三项:Agent 规则、MCP 配置、Skill 技能。

每一项都提供 Tooltip:鼠标悬停时会显示可用的绝对文件/目录路径、当前版本与目标版本、MCP 当前/目标 URL、内容哈希、错误或适用性说明。状态检查与更新入口彼此独立,不再把 Agent 规则和 Skill 合并成一个状态。

MCP 配置 Tooltip 会区分已注册、当前可用和当前可调用的 MCP 工具数量,并显示工具注册表版本及主要分类。可调用数量会受到 Unity 连接、功能开关和项目写入授权影响。

Skill 技能 Tooltip 显示该 Agent 项目级 Skill 根目录、已安装 Skill 数量和名称、UPilot Skill 数量、能力覆盖,以及 Skill 文档实际引用的 MCP 工具数量和主要关联工具。Skill 数量与 MCP 工具数量是两个不同维度,不应共用同一个数字。

  • 配置:当前 Agent 还没有 UPilot MCP 配置,点击后新增配置。

  • 更新配置:当前 Agent 已有 UPilot 配置。点击后会二次确认,只更新该 Agent 的 UPilot MCP 配置项。

  • 更新规则:为当前 Agent 更新对应的 UPilot Agent 规则。

  • 更新 Skill:权威同步所有 UPilot Skill 目标;Codex、Cursor 与 OpenCode 共用 .agents/skills,Claude 使用独立的 .claude/skills。

  • 更新全部:更新已启用 Agent 的现有 UPilot MCP 连接条目,并权威同步全部 UPilot Skill/Agent 规则;若已启用 Agent 缺少 MCP 配置,会先提示选择“补齐并更新”或“仅更新现有”。

  • 检查配置:位于“更新全部”右侧的下拉菜单中,只刷新状态,不修改文件。

  • 强制重新配置全部已启用 Agent:只为用户已启用的 Agent 创建或更新 MCP 配置,并重新生成共享的 UPilot Skill/Agent 规则;不会自动启用或写入未使用的客户端。

首次设置会保存用户勾选的 Agent;旧项目会从已有、可识别的 mcp.upilot 条目迁移启用状态,没有既有条目的全新项目默认只启用 Codex。未启用的客户端以中性 未启用 显示,不计入配置问题;在对应行点击 启用并配置 后才会写入其 MCP 配置。

Claude Code、Codex、Cursor 和 OpenCode 都支持 UPilot Skill。Claude Code 使用 .claude/skills;Codex、Cursor 和 OpenCode 默认共享 .agents/skills,避免重复维护。Cursor 与 OpenCode 的 Tooltip 会列出其可发现的项目级 Skill 目录,按 Skill 名称去重统计,并在同名副本内容哈希不一致时显示冲突。

UPilot 的规则 managed block 与固定目标下的 upilot-unity-mcp Skill 和包版本深度绑定,因此首次安装、重复安装、UPM 升级与自动刷新都会权威同步。检测到本地修改、无元数据或无法验证的旧副本时,会先备份到 .upilot/backups/agent-integrations/,再覆盖受管内容;自动流程和普通更新不再弹出本地定制二次确认。Agent managed block 外的项目业务规则以及非 UPilot MCP 配置保持不变。

授权与运行详情

已授权时,主界面不再常驻显示授权状态、授权时间或撤销按钮。未授权时,状态卡下方会显示“需要授权”提示和 允许授权 按钮;Agent 仍可执行只读检查,但修改脚本、资源和项目设置前需要授权。

授权时间、撤销授权和完整项目路径位于 高级设置 > Agent > Agent 操作授权。

展开主界面的 运行详情 可以查看运行状态、UPM/服务版本、运行方式、发布通道、MCP 端口、Unity Bridge 端口和 Bridge 连接状态。Unity Bridge 端口仅用于 MCP Server 与 Unity Editor 的内部连接,不能配置为 Agent 的 MCP 地址。

自定义项目规则

项目自己的业务约束应写在 AGENTS.md 等规则文件的 UPilot 管理块之外。UPilot 生成的规则和 Skill 会随包更新同步;本地修改会先备份到 .upilot/backups/agent-integrations/,不要直接维护生成文件。

需要开发或维护 UPilot 规则模板时,请查看 Agent/Skill 安装与同步指南,普通使用无需执行模板生成命令。

高级设置、停止与诊断

普通使用不需要进入高级设置。需要停止服务、修改端口或查看详细诊断时,点击主界面的 高级设置…,或选择:

UPilot > 高级设置

UPilot 高级设置界面

高级设置提供运行检查、重启、停止、端口和诊断功能。

停止 UPilot

停止按钮只在高级设置中提供,并以红色显示。点击 停止 后还需要二次确认。

停止后,Agent 将暂时无法操作 Unity。界面会显示“正在停止”或“已停止”,需要恢复时点击 启动 UPilot。

高级设置可以做什么

  • 查看 Unity Bridge、MCP 服务和 Agent 连接状态。

  • 启动、重启或停止 UPilot。

  • 开启或关闭自动启动。

  • 修改 HTTP 和内部 WS 端口。

  • 查看操作日志、通信日志和完整诊断结果。

  • 在普通停止无效时,按诊断提示处理残留的 UPilot 服务进程。

结束所有疑似 MCP 服务进程属于故障恢复操作,只应在普通停止无效、端口持续被占用时使用。

Python 开发环境

源码开发安装默认使用 Python 配置。正式版需要调试或自定义环境时,可从 UPilot > 高级设置 > 服务运行方式 选择 Python;日常使用保持默认的独立服务方式即可。

Python 方式需要 Python 3.11 或更高版本,可选择:

  • 自动配置环境:检测到可用的基础解释器后,点击 配置并继续,创建环境、安装依赖并验证。目标环境已存在时先验证,验证失败会显示原因并保留现有文件,修复后重新检测。

  • 使用已有环境:选择解释器的完整路径,点击 验证并继续。UPilot 严格验证该解释器的版本与运行依赖,失败时显示具体原因和路径,不使用其他 Python 环境代替,也不覆盖已有环境。

缺少基础解释器时,请先安装 Python 3.11 或更高版本,再点击 重新检测。配置过程中可以取消;失败或取消会留在当前步骤,不会报告配置成功。

首次配置在验证并保存成功后自动进入 Agent 配置;已配置项目从高级设置切换运行方式时,仍通过 应用并重启服务 生效。

同时打开多个 Unity 项目

每个 Unity 项目必须使用不同的 HTTP 和内部 WS 端口。

UPilot 首次配置或自动修复时会优先寻找空闲端口。多项目同时运行时:

  1. 分别打开每个项目的 UPilot > 打开 UPilot。

  2. 确认每个项目显示的 MCP 地址不同。

  3. 在每个项目中更新对应 Agent 配置。

  4. 在 Agent 中调用 unity_mcp_status,核对 Unity 工程路径。

不要仅根据端口判断项目,实际操作前始终核对 unityProjectAbsolute 返回的工程路径。

更新 UPilot

更新 Unity 包

使用固定版本 Git URL 时,把 Packages/manifest.json 中的版本标签改为目标正式版本。例如,升级到 v0.3.44 时使用:

https://github.com/codingriver/upilot.git#v0.3.44

保存后等待 Unity 完成包更新和脚本编译。

更新独立 MCP Server

按照 UPilot 界面的服务更新提示更新独立 MCP Server,等待下载和校验完成后再启动服务。如果手动选择本地服务文件,请使用与目标发布版本匹配的独立程序。

同步 Agent 配置

更新完成后:

  1. 打开 UPilot > 打开 UPilot。

  2. 点击 更新全部。

  3. 确认提示“将更新已有的 UPilot MCP 连接条目,重新同步全部 UPilot Skill/AGENT规则”。

  4. 重启 UPilot。

  5. 重启或刷新 Agent 客户端。

  6. 再次调用 unity_mcp_status 验证连接和项目路径。

常见问题

Unity 中没有出现 UPilot 菜单

  1. 在 Package Manager 中确认 io.github.codingriver.upilot 已安装。

  2. 等待 Unity 完成脚本编译。

  3. 检查 Console 是否有其他 C# 编译错误;项目中任何编译错误都可能阻止 Editor 菜单加载。

  4. 关闭并重新打开 Unity 项目。

安装服务失败,或写入配置后一直停留在启动中

  1. 确认安装的是固定发布标签版本,并已在 服务安装 步骤点击 下一步,完成独立服务安装。

  2. 下载失败时,检查是否能访问 GitHub、下载目录是否可写,以及安全软件是否拦截独立服务。

  3. 点击 自动修复,根据界面显示的错误处理。

  4. 仍未恢复时打开 高级设置,检查服务文件路径、HTTP/WS 端口和诊断日志。

如果使用 选择本地服务文件,请确认文件存在,并且与当前系统和目标发布版本匹配。

Agent 看不到 UPilot 工具

  1. 确认 Unity 中 UPilot 显示 已就绪。

  2. 确认 Agent 对应行显示 MCP 已配置。

  3. 复制主界面的 MCP 地址,确认配置文件中的 URL 一致。

  4. 重启或刷新 Agent 客户端,使工具列表重新加载。

  5. 让 Agent 调用 unity_mcp_status;如果该工具也不可见,说明客户端尚未加载 UPilot MCP 配置。

健康检查正常,但 Agent 仍然无法操作 Unity

健康检查正常只表示 HTTP 服务可访问,不代表 Unity 已完成连接。请在 Agent 中调用 unity_mcp_status,确认:

  • connected 为 true

  • serverReady 为 true

  • 工程路径正确

Agent 连接到了错误的 Unity 项目

停止当前操作,打开目标项目的 UPilot 主界面,复制它显示的 MCP 地址,然后更新当前 Agent 配置。重启 Agent 后再次检查工程路径。

端口被占用

在主界面点击 自动修复。UPilot 会尝试选择空闲端口并重新启动。端口变化后,还需要更新 Agent 配置并刷新 Agent 客户端。

修改了 Skill/规则,更新后内容被恢复

UPilot 会权威同步固定目标下的 Skill 和 Agent managed block,以保证它们与当前 UPM 包版本一致。覆盖前会自动备份本地修改到 .upilot/backups/agent-integrations/<UTC时间>-<随机ID>/;备份失败时对应目标不会被修改。项目业务规则应写在 Agent managed block 外,不要直接维护生成的 Skill 文件。

浏览器访问 /mcp 返回 406

这是正常现象。/mcp 只用于 MCP 客户端通信,浏览器检查请访问:

http://127.0.0.1:8011/health

卸载

  1. 在 UPilot > 高级设置 中点击红色 停止,并确认停止。

  2. 在 Unity Package Manager 中选择 UPilot,点击 Remove。

  3. 如需清理项目连接,只删除各配置文件中的 upilot MCP 项,不要删除包含其他服务的整个配置文件。

  4. 可选清理 UPilot 管理的规则和 Skill:

.agents/skills/upilot-unity-mcp
.claude/skills/upilot-unity-mcp
.cursor/rules/upilot-unity-mcp.mdc

AGENTS.md、CLAUDE.md 等文件可能包含项目自己的规则。清理时只移除 <!-- upilot:start --> 与 <!-- upilot:end --> 之间的 UPilot 管理块。

通过 Package Manager 正常卸载时,UPilot 会清理自己写入的 UPILOT 编译宏;直接删除包目录或手工删除包引用后,如有残留,需要在 PlayerSettings 中手动移除该宏。独立服务文件可能供多个项目共用,不要在仍有项目使用时删除。

自动化与高级执行

UPilot Step

UPilot Step 是默认的业务自动化测试方式。项目提供业务步骤、断言、测试数据和清理逻辑,UPilot 执行器负责完整计划的验证、执行、超时、取消、Finally 清理、日志采集与报告。

内置步骤支持打开场景、切换运行模式、等待、启动 Console 采集和截图。可以通过 unity_operation_* 提交完整计划、查询状态并获取产物;只有执行结束并验证结果,才代表测试完成。

受控执行工具

工具

用途

unity_reflection_call

调用一个已加载方法或一条受限表达式

csharp_validate

只读预检语法、绑定和后端支持,不执行目标代码

csharp_eval

执行有预算限制的 UPilot C# 子集语句

reflection_emit_type

从结构化描述创建临时 CLR 类型

execution_session

管理跨调用变量、对象、类型和 delegate 句柄

除只读验证外,执行可能产生副作用,需要项目写入授权。取消不会回滚已发生的修改,不应自动重试;优先使用专用 Unity 工具,仅在确有需要时使用这些高级入口。

详细边界见 受控 C# 执行设计 和 执行工具指南。

UPilot Flow

UPilot Flow 是可选的 Unity Editor 界面自动化功能,普通用户不需要启用。

  • 默认关闭,不影响 UPilot 核心功能。

  • 仅支持 Unity 6 或更高版本。

  • 适合需要通过 YAML 编排复杂 EditorWindow 操作的高级场景。

需要使用时请查看 UPilot Flow 文档。

UPilot 追踪器

UPilot 追踪器是默认不启用任何点位的手动 Editor 诊断模块,可按列表选择生命周期、GameObject、Component 和 Transform 点位,并按对象来源、类型、名称、Hierarchy、Scene、Layer/Tag、Prefab、点位/方法/阶段和运行模式过滤后查看或导出事件。

需要使用时请查看 UPilot 追踪器文档。

使用建议

  • 第一次连接先执行只读检查,再进行场景或资源修改。

  • 让 Agent 在修改前确认目标场景、对象或资源。

  • 对删除、覆盖、批量修改、构建发布等操作明确要求二次确认。

  • 使用版本控制,并在重要操作前保存 Unity 场景和项目改动。

  • 同时打开多个 Unity 项目时,每次操作前检查连接的工程路径。

获取帮助

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    Not graded
    maintenance
    Exposes Unity Editor project context and manipulation tools to AI coding agents, enabling automated scene hierarchy analysis, script inspection, and asset management. It supports both read and write operations including GameObject editing, component configuration, and animation authoring within the Unity environment.
    2
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    A Unity Editor plugin that exposes Unity Editor capabilities to external AI agents via the Model Context Protocol. It enables AI agents to interact with Unity through tools for debugging, scene inspection, project management, and build operations.
    7
    MIT