unity-explorer-mcp

Unity Explorer MCP 场景迭代

explorer MCP 连接失败或缺失是预期的起始状态，而非阻碍。 MCP 服务运行在 Explorer 进程内部，因此 ConnectionRefused 或完全没有 explorer 服务，只表示 Explorer 尚未运行——继续进入下方的意图门控；Setup 会启动它并绑定工具。绑定后，mcp__explorer__* 工具会自述信息，是权威目录：请在那里查看名称、参数和输出结构，而不要假定某个工具不存在。

通过 Creator Hub MCP 接入？ 当 Creator Hub 的编辑器 MCP 已连接（技能 creator-hub-mcp；工具 mcp__creator-hub__*）时，可通过它访问 Explorer：launch_preview 会启动场景预览，并启用此 MCP 服务；下方的运行时工具会实时重新发布为 explorer_<name>（explorer_screenshot、explorer_walk 等；绑定期间可用 explorer_call(tool, arguments) 作为备用方式）。这种情况下，完全跳过下方的 Setup——无需 claude mcp add、绑定门控或探测端口 8123——直接使用这些工具名称进入迭代循环。参考文件仍适用，无需更改。此路径还需遵守一条额外规则：调用 launch_preview 前，检查 preview_status 和操作系统进程列表（macOS 上运行 pgrep -fl '[M]acOS/Explorer'，Windows 上运行 Get-Process Decentraland），因为 stop_preview 可能返回 {ok: true}，但 Explorer 仍在运行，导致下一次启动始终无法连接——参见 creator-hub-mcp 中的“预览生命周期”。

Explorer 运行时，绝不要一次性批量写入场景文件。 每次更改都必须作为一次写入完成（迭代循环第 1 步）。下次写入前，先检查 get_scene_state；如果要进行多文件补丁或运行生成器脚本，则先停止开发服务器。两次保存间隔仅几秒，可能导致加载不完整的程序包；只有重启 Explorer 才能恢复（Locksmith，2026-10：两天内重启了四次）。

操作前请阅读：

操作前……	阅读
set_camera_mode 或 set_camera_pose	reference/camera-and-movement.md（先检查 camera.modeChangeAllowed）
任何点击、悬停、press_input 或 ui_* 调用	reference/interaction.md（两种 ID 空间）
统计、终止或重启 Explorer 进程	reference/recovery.md（带方括号的 pgrep；watchdog 的命令行也包含 Explorer 路径）

门控

此技能中的某些环节属于门控：你提出问题后，不再调用任何工具，并等待用户回答。只有用户回复后，门控才会开放——不能依靠自己的判断，不能因用户沉默而开放，也不能因为你有可用的变通方法而开放。作为子 Agent 运行时，你根本无法开放任何门控——因为没有用户可供询问：请停止操作，并向调用方报告尚待决定的事项及你的建议，而不是擅自越过门控。即使变通方法恰好有效，这样做仍违反门控要求。门控按顺序为：技能安装门控和重启门控（下文）、意图门控（预检）、启动/终止门控（Setup 第 1 步）以及绑定门控（Setup 第 2 步）。

加载 SDK 技能（无论如何，都要先做）

此技能仅涵盖如何驱动 Explorer；SDK7 API 知识（组合优先规则、组件参考）位于此技能所属的 decentraland/sdk-skills 软件包中的其他主题技能里（入口为 sdk-scenes）。无论最终是否会用到 Explorer，你都需要这些技能，因此请在下方的预检之前加载。

加载技能：先加载会话技能，然后从文件系统加载——场景本地技能（场景文件夹中的 .claude/skills/）和全局技能（~/.claude/skills/）。当你能够说出可用的主题技能名称时，才算完成——仅仅注意到它们存在还不够。如果无法加载——例如只安装了 unity-explorer-mcp 本身，而没有安装整个软件包——则触发技能安装关卡：建议从同一来源拉取软件包中其余的主题技能。用户同意后，询问要安装到哪个层级——场景本地还是全局——然后运行相应的命令：

npx skills add decentraland/sdk-skills --all       # scene-local (run inside the scene folder)
npx skills add decentraland/sdk-skills --all -g    # global (user-level, ~/.claude/skills)

新安装的技能会写入磁盘，但不会自动绑定——技能在会话开始时加载，只有用户才能重启。触发重启关卡：现在重启以加载新技能，还是在本次会话中继续？建议重启——在重启之前，Skill 工具无法按名称加载新技能。重启仅对自动发现和原生 MCP 绑定有必要：有文件系统访问权限的 Agent 可以在同一会话中读取磁盘上已安装的 SKILL.md 并遵循其中的说明。

拒绝任一关卡都没问题——仍然可以实现该场景，只是效率较低。在技能实际加载之前，迭代循环中的过时记忆规则适用于你编写的每一项 SDK7 API。

意图确认关卡（预检，先执行此步骤）

此技能会自行触发——只要存在 mcp__explorer__* 工具，就会触发——因此用户通常并未要求使用它，此技能却已加载。在探测服务、启动 Explorer 或编辑场景之前，先确认用户是否想通过 Unity Explorer MCP 服务驱动场景："你想通过运行中的 Decentraland Explorer 和 Unity Explorer MCP 服务来构建／测试此场景吗？这会启动／连接到 Explorer，并在游戏世界中进行迭代。"

• 是 — 继续执行下方的设置。
• 否 — 不执行此技能中的任何设置、启动或 MCP 步骤。不使用 Explorer 处理场景（编辑代码，并借助刚加载的主题技能），如果用户之后改变主意，再让他们重新调用此技能。

设置（每个会话执行一次）

1. 探测是否已有正在运行的 MCP 服务，然后启动场景。 优先使用 Harness：如果会话中有 mcp__explorer__* 工具，则调用 get_scene_state——收到响应即表示服务已启动。仅当工具不存在时才回退到 curl：

   curl -s -m 2 http://127.0.0.1:8123/unity-explorer-mcp -X POST \
     -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
   

   在 Play Options > Desktop Client 中勾选 Enable MCP Server 后，Creator Hub 的 Play 按钮会像 CLI 一样启动同一个服务——这与探测到的服务无法区分，绝不会导致连接失败；在下方任何需要启动的地方，它都是有效响应。

   找到服务（工具响应或 serverInfo 结果）——触发启动／终止关卡：使用已运行的 Explorer，还是使用 MCP 标志从头启动场景？

   • 使用现有服务：不启动任何内容。如果端口 8000 未服务目标场景文件夹（运行 lsof -nP -i :8000 -sTCP:LISTEN，然后检查该 PID 的工作目录），则终止占用端口的进程并运行 npm run start -- --no-client。如果工具已可用，则跳过第 2 步。
   • 从头启动：在执行任何操作之前，先追加询问同一关卡的问题——终止先前运行的场景服务，还是保留它并并行运行第二套堆栈？
     • 终止它：终止端口 8000 上的开发服务，让用户关闭正在运行的 Explorer 客户端，然后继续下方步骤。
     • 保留它：保持现有服务及其 Explorer 不变，并使用独立端口启动第二套堆栈——参见 reference/setup.md 中的“运行第二套堆栈”。 未找到服务——在场景文件夹中用一条命令提供场景并启动 Explorer（让它在后台持续运行；如果端口 8000 已被其他程序占用，请按照上文相同的方式询问是结束占用程序还是保留，并设置端口覆盖值）：

   npm install && npm run start -- --mcp --skip-auth-screen true
   

   此命令会在 http://127.0.0.1:8000 提供场景，启动已安装的 Decentraland 客户端并连接到该场景，同时在端口 8123 上启动 MCP 服务；每当源文件发生变化时，场景都会热重载。端口覆盖值、其他启动标志，以及两种启动错误（--mcp 被拒绝为未知选项；“Please download & install the Decentraland Desktop Client”）请参阅 reference/setup.md 中的“启动标志和错误”。

2. 注册 MCP 服务，然后确认其工具确实已绑定（默认端口为 8123）。注册和绑定是两回事——两者都需要完成。

   timeout 15 claude mcp add --transport http --scope user explorer http://127.0.0.1:8123/unity-explorer-mcp
   

   “already exists in local config”表示之前的会话已经注册过它——注册信息保存在持久配置中，无需处理。在非终端运行环境（包括 VS Code 扩展）中，命令可能会挂起且不显示输出：将挂起视为很可能已注册，然后继续进行绑定检查，不要重试——第 1 步的探测已经确认端点可用。

   必须执行——绑定检查：如果你在本次会话中自行启动了 Explorer，一旦就绪探测得到响应，就立即在此停止，不要开始通过 curl 进行迭代循环。 Claude Code 会在会话启动时建立 MCP 连接，而此服务运行在 Explorer 进程内部，因此，在 Explorer 启动前就已开始的会话，其唯一一次连接尝试已经失败，mcp__explorer__* 工具不会自行出现。会话中途，只有显式执行 /mcp 重新连接才能重新绑定；或者在 Explorer 持续运行时启动新的 Claude 会话，新会话会在启动时自动绑定。这两种方式都需要用户操作：你无法通过其他命令实现，因此应询问用户，不要尝试绕过。

   先说明当前情况——“Explorer 已启动，但此 Claude 会话在它启动前就已开始，因此原生 MCP 工具尚未绑定”——然后提供三种方案，按优先顺序排列，并在用户选择备用方案前说明其代价：

   • 重新连接 explorer 服务——最快，而且能保留当前对话。具体操作取决于运行环境：终端 CLI 在 /mcp 下会打开交互式服务菜单，可选择重新连接。VS Code 扩展（以及任何嵌入式聊天面板，例如 Creator Hub 的面板）没有这种菜单——在这些环境中，单独输入 /mcp 只会输出状态行和用法说明，因此应让用户在聊天中输入 /mcp reconnect explorer（或 /mcp reconnect all）。
   • 启动新会话／打开新对话标签页，让 Explorer 继续运行——工具会在新会话启动时自动绑定。在 VS Code 扩展和嵌入式面板中，这只是打开一个新的对话标签页，不需要重启应用或 Explorer——请明确说明，因为用户可能会以为需要重新阅读大量内容而拒绝。只要 /mcp reconnect 返回 “MCP controls aren't available right now — the terminal is still starting up or is showing another view.”，就应在这些环境中优先推荐此方案——这是该运行环境中无法在聊天里修复的故障，而新标签页是可行的解决方案。
   • curl 备用方案——每执行一次玩家操作都需要一条 shell 命令，每种新的调用形式都会触发权限提示，还会消耗更多 token；截图会以 base64 格式返回，必须先解码为文件才能查看（scripts/screenshot.sh 可以完成这一步——请参阅 reference/curl-fallback.md）。速度较慢，但上述所有检查仍可通过此方案完成；不要说无法获取截图。

   如果客户端支持 AskUserQuestion，请使用它，每个方案各设一个选项；将第二个选项标注为 “重启会话／新标签页（Explorer 保持运行）”，避免被误解为要关闭 Explorer。否则，用纯文本列出同样的三个方案，并以 “你更倾向于哪种方案？” 结尾。 只有处于以下三种状态之一时，才能越过此步骤——不存在第四种情况，子 Agent 也只能处于第一种状态：

   • 工具已就绪（Explorer 在本次会话开始前已运行）——此关卡不适用；继续执行步骤 3。
   • 用户重新绑定了工具——通过 /mcp 重新连接，或在 Explorer 保持运行的情况下打开一个新的会话/标签页。通过调用原生 mcp__explorer__* 工具进行验证，然后继续执行步骤 3。（新的会话会结束本次对话；新会话会发现工具已绑定，因此跳过此关卡。）
   • 用户已在本次会话中、获知相关代价后，以书面形式明确选择了 curl 备用方案——只有在这种情况下，才读取 reference/curl-fallback.md，并通过 HTTP 调用端点。curl 探测成功不代表用户拒绝了该方案，保持沉默也不代表拒绝。

   步骤 1 中的探测是越过此关卡前唯一一次 curl 调用。探测得到响应只能证明 Explorer 已启动——这正是需要询问用户的触发条件，而不是继续操作的许可。

   只需提醒一次如何避免此问题，不必每次会话都提醒：在 Claude Code 之前启动 Explorer，或者让它在会话之间保持运行，即可完全跳过此关卡。

   不是在 Claude Code 中运行？ 对于 Cursor、Cline 或自定义 SDK 测试框架，连接详情和配置格式请参阅 reference/setup.md 中的“在 Claude Code 以外的客户端中注册”。Claude Code VS Code 扩展和 Creator Hub 的嵌入式聊天也属于 Claude Code：它们使用上述命令，并遵循绑定关卡中注明的测试框架差异。

3. 等待场景加载：轮询 get_scene_state，直到 loadingScreenOn 为 false 且场景报告 isReady: true。设置约 90 秒的轮询截止时间，并将结果解析为 JSON：切勿在原始文本中 grep isReady，因为负载中的空格（"isReady": true）会导致字面匹配失败，使轮询永不结束。若轮询持续失败，客户端很可能停留在身份验证界面——只有在缓存了之前会话的有效身份时，--skip-auth-screen true 才会跳过该界面；而额外的 --multi-instance 实例总会要求登录——因此请告知用户登录，等待其完成后再继续。

迭代循环

重复执行，直到每项要求都有证据：通过零售相机模式（first_person/third_person，而非自由相机）采集的截图或状态读取能够证明该要求，同时 get_scene_state 状态正常，日志中没有无法解释的错误。

1. 编辑 src/ 中的场景 TypeScript——编写不太记得准确用法的 API 前，请先阅读对应主题的技能（见下文的记忆过时）。每次更改只写入一次：将多部分更改合并为一次写入；先写入新模块，再接入它们；再次保存前，确认 get_scene_state 仍显示有场景——两次保存间隔仅几秒可能会加载不完整的包，导致场景丢失，只有用户重启客户端才能恢复（reference/recovery.md）。热重载会在几秒内生效；reload_scene 可提供确定性的重置。开发服务器的监视器每次保存都会重写 bin/index.js——服务器运行时绝不要手动运行 sdk-commands build（两个写入者操作同一个文件）；如果更改似乎没有在场景中生效，先在 bin/index.js 中 grep 你编辑时添加的字符串字面量，再调试场景：构建通过并不能证明运行中的包包含了它。放置、下载、转换或导出 3D 模型前，请阅读 reference/assets.md；调整自发光／泛光、UI 覆盖层、天空盒时间或细薄几何体前，请阅读 reference/visuals.md。资源文件比 src/ 更容易频繁变动：在 assets/ 下添加、删除或重命名的每个文件都会单独触发热重载——监视器统计的是文件数，而非命令数，因此一次删除 7 个 GLB 的 rm 操作，在 30 秒内仍触发了 7 次重载，有一次还导致了 Explorer 重启（观察于 2026-10-10）。尽可能在启动预览前处理资源文件，并将操作合并到一条命令中，以缩短触发重载的时间；有人正在进行游戏测试时，绝不要执行此类操作。
2. 确认场景运行正常：调用 get_scene_state——如果 state 为 JavaScriptError 或 EcsError，则说明你的代码导致场景运行时崩溃。
3. 读取运行时输出：调用 get_scene_logs，并将 sinceSeq 设为你看到的最后一个序列号。场景的 console.log 输出和异常会出现在此处；错误滚出屏幕后仍会保留在缓冲区中。
4. 查看并验证：调整视角位置（teleport、move_to、walk、look_at）——look_at 会设置面向方向，而 walk 和 screenshot 会跟随摄像机。然后调用 screenshot，检查图像是否符合场景代码的预期效果。取景、自由摄像机巡视或沿精确路线移动前，请阅读 reference/camera-and-movement.md。
5. 测试行为：走入触发区域、点击、悬停、按下输入、让按住的指针扫过场景、聊天、做表情，并使用 ui_* 工具操作场景自身的 2D UI——随后再次截图，验证是否有相应反馈。这些操作都可能无声失败：首次点击、悬停、按键或调用 UI 前，请阅读 reference/interaction.md。如果仅凭视觉效果无法判断，可使用 list_scene_entities + get_entity_details 查看场景的 ECS 状态。
6. 测量预算和性能：如果问题涉及限制、帧率或优化方向，请使用 get_scene_content_stats、get_scene_content_breakdown 和 get_performance_stats 完成测量闭环——在提出任何建议前，先在真实视点下将内容与测得的 FPS 关联起来。方法和解读说明见 reference/performance-debugging.md。

在 Creator Hub 的 launch_preview 下，Explorer 就是创作者自己的窗口。你操作的实例正是创作者正在体验的实例：move_to、reload_scene、摄像机模式更改以及资源文件变动都会影响他们的游戏测试。操作前，请读取 get_player_state（位置、速度）以及近期的 get_scene_logs，确认他们是否正在体验；检查视角时，优先使用 set_camera_pose（自由摄像机——不会移动 avatar），而不是 move_to；之后则恢复你发现的摄像机模式（first_person / drone_view），不要不加判断地切换到 third_person。观察于 2026-10-10。请参阅 creator-hub-mcp 技能中的预览生命周期规则。 记忆已过时 — 你对 SDK7 API 的记忆已不再准确。 SDK 包含比你的训练数据更新的组件（包括原生 TriggerArea 和 triggerAreaEventsSystem），因此想不起某个 API 并不能证明它不存在，你记得的版本号也不能。当你想不起某个 API 的确切用法，或发现自己正手动编写变通方案（轮询玩家的 Transform 来检测触发区域、修改 engine.PlayerEntity 来移动玩家）时，请先阅读负责该功能的主题技能，再编写变通方案 — 技能描述会指出对应的负责人，sdk-scenes 则索引其余内容。只有在没有技能涵盖时才查阅官方文档，并在这样做时说明。

交叉核验每个结论：用状态读取核实每项视觉判断（通过 get_entity_details 读取 ECS 值、日志、get_player_state 读取位置），并用像素核实每项状态判断。某个渠道经常会撒谎 — 有些碰撞体在像素中不可见，实体渲染不可见但状态看起来正常，动画也可能悄无声息地无法播放。**世界内文字是状态读取结果，不是图片：**几米之外，缩小后的截图里就看不清 TextShape 告示牌；而对其实体调用 get_entity_details 会返回确切的 PBTextShape 字符串，只需消耗截图令牌数的一小部分。参考文件会指出必须交叉核验的地方。

必须遵守 — 完成前清理摄像机。 每当你停止工作（任务结束、交还给用户或暂停等待用户输入）时，都要在最后一次摄像机操作中恢复场景预期的正式模式 — 默认使用 set_camera_mode third_person；如果场景刻意强制第一人称（CameraModeArea 或摄像机锁覆盖了游戏空间），则使用 first_person；摄像机绝不能留在 free 模式 — 如果中间任何操作可能失败，请通过 get_player_state → camera.mode 确认。

截图频率与成本

每次 screenshot 工具返回的结果都会以图片形式进入你的上下文（1280×720 时约 1.2k 令牌，随像素数变化）。偶尔通过工具截图没有问题，每批工具调用只截一张 screenshot：同时发起两次会发生冲突，第二次会失败并显示“另一次截图捕获正在进行；请在完成后重试” — 请单独重新发起。频繁截图或连续截图应改用捆绑脚本，它会将帧保存到磁盘，零上下文成本，并且只打印说明文字。请使用绝对路径调用它 — 你的当前工作目录是场景文件夹，而不是此技能的目录；<skill-dir> 是加载此技能时报告的基础目录，运行 -h 可查看参数。

<skill-dir>/scripts/screenshot.sh -o /tmp/shot.jpg     # single frame to a file
<skill-dir>/scripts/screenshot.sh -n 10 -i 0.5         # burst, for time-based behavior (tweens, animations)

帧默认保存到 $TMPDIR/mcp-shots，有意放在场景文件夹之外：项目中留下的任何内容都会在部署时上传，并计入每个地块的 MB 限额，因此也要确保 -d/-o 的目标位于场景之外（或在 .dclignore 中忽略该目录）。多拍，少读：要进行前后对比时，将两张图都保存到磁盘，只读取这两张。

场景健康状态

• scene.json 的更改（出生点、显示字段）不会热重载 — 重启 npm run start 进程，然后执行 reload_scene。**更改 scene.base、scene.parcels 或 worldConfiguration 需要额外操作：仅执行 reload_scene 不够。**开发服务器会在启动时构建一次 realm 的 localSceneParcels，因此请重启服务器，然后在新的 scene.base 处重新启动 Explorer，切勿使用之前启动时的位置。重启 npm run start 且不带 --position 即可完成这两步。

• 执行 teleport 或 reload_scene 后，交互前请重新检查 get_scene_state；就绪状态可能会延迟几秒。

• 一个 parcel 为 16×16 m；parcel (x, y) 覆盖世界位置 (16x..16x+16, 16y..16y+16)。--position x,y 会在 parcel x,y 处生成；不带此参数时，启动位置为 scene.base。

• 在本地场景开发模式下，teleport 会静默无效：此模式下不允许使用 /goto（聊天中会显示 "Teleport is not allowed in local scene development mode"），但工具仍会回复 "Arrived at (x,y)"。在本地场景会话中，请使用 move_to 重新定位。

• 缺少工具：会话中缺少 mcp__explorer__* 工具意味着触发了绑定门槛 — 返回 Setup 的第 2 步，请用户重新连接服务（在终端 CLI 中使用 /mcp 菜单，在 VS Code 扩展中使用 /mcp reconnect explorer），或在 Explorer 保持运行的情况下打开新的会话／对话标签页，然后结束本轮操作。HTTP 备用方案位于 reference/curl-fallback.md，只有在告知用户其代价并由用户明确选择后才能打开。

• 场景退出、玩家位于 parcel 外、连接丢失或客户端卡死：请参阅 reference/recovery.md。

回归测试装置：149,149-synthetic-input-showcase

sdk7-test-scenes/scenes/149,149-synthetic-input-showcase 是一个由此 MCP 驱动的 2×2 parcel 场景：十个站点（S1-S10）覆盖整个合成输入功能范围 — walk、camera_look、look_at、click_entity、click_at、hover_entity、press_input 和 ui_* 工具，每个站点都带有游戏内读数，因此错误结果一目了然，无需推断。在认定待测场景已损坏之前，请先运行此场景，对 MCP 本身进行健全性检查：如果某个站点行为异常，问题应在工具或 Explorer，而非你的场景。其 MCP_SHOWCASE.md 列出了已知的客户端问题及各站点的操作说明。

模式：将检查逻辑写入场景，而非工具调用

当无法通过任何 MCP 工具读取某项行为时——无论是 Avatar 是否隐藏、修饰区域是否生效，还是碰撞体尺寸是否正确——都应将断言写入场景代码，并从场景内面板读取判定结果。9,99-modifier-areas 提供了可复用的模式（src/qaPanelUi.tsx）：

• 固定在角落的 QA 信息面板 显示操作说明、每项检查对应的 运行 按钮，以及每项检查的通过（绿色）／失败（红色）／未运行状态。只需调用一次 explorer_screenshot，即可报告整个测试套件的结果。
• 每项检查都能自行执行：创建自己的探测实体，将玩家 movePlayerTo 到能够区分通过与失败的位置，等待状态稳定，读取一个可观测的代理值，打印判定结果，然后清理探测实体，以便再次运行。
• 当你关心的属性无法读取时，改用一个可读取的相关属性：场景无法询问 Avatar 是否隐藏，因此改用来自同一碰撞体池的 TriggerArea，并通过断言进入事件来检查；对于相机，则读取 CameraMode。将无法读取的情况作为同一面板中的简短手动步骤保留。
• 每个步骤的日志都带有 [checkName] 前缀，因此 explorer_get_scene_logs 可以说明检查失败的原因，无需再截屏。
• 按住 Alt 使用此类面板（解锁指针），并将探测几何体放在与被测对象不同的实体上——如果在被测实体上使用 MeshRenderer，测试一旦修改该实体，它就会报告错误。

开始点击之前，先编写面板：能够自行报告结果的检查会在整个会话期间保留，而根据截图得出的结论不会。

缺少某项能力时

如果没有已连接的 MCP 工具能够完成工作流所需的操作（例如客户端的快捷键不是 SDK 输入操作——这些快捷键可通过 press_input 处理——或读取工具未公开的值），请停止并交由用户处理：说明你受阻的具体操作，以及现有工具为何无法完成它。MCP 服务和 Explorer 位于此场景仓库之外——是否扩展它们由用户决定。