星火 2.0 开发文档

主题

多开编辑器与 MCP 调试连接 ​

多开编辑器时，通常不必手工安排端口。每个 GUI 编辑器有独立的实例 ID 和 Editor MCP 端口；启动调试后，编辑器自动发现对应 Runtime 的实际端口，并在转发请求时校验实例身份。需使用配套新版编辑器、启动脚本与 WasiCoreSDK；已有项目重新生成 AI 上下文后取得更新的 helper。

先选编辑器，再选运行中的玩家 ​

Editor MCP 管理当前项目、编译和调试；Runtime MCP 读取或操作正在运行的游戏。同进程的多个 PIE 玩家共享 Runtime 端口，通过 target_id 区分；独立客户端进程有自己的 Runtime 端口和实例 ID。

AI 环境已提供编辑器 MCP 工具时，先调用 editor_get_context 核对项目路径和 mcp.editor_instance_id。查看其它窗口时使用 editor_list_instances。没有直接提供 MCP 工具时，项目内 HTTP helper 支持：

powershell
./ai/tools/Invoke-SceEditorMcp.ps1 -ListInstances -Pretty
$editorId = '<上一步返回的 instance_id>'
./ai/tools/Invoke-SceEditorMcp.ps1 -InstanceId $editorId -Context -Pretty
./ai/tools/Invoke-SceEditorMcp.ps1 -InstanceId $editorId -Tool debug_start -ArgumentsJson '{"game_in_editor":false}' -Pretty

只有一个有效实例时 helper 可以自动选择；多个实例时要求传 -InstanceId。显式 -Port 或 -BaseUrl 仍可用于固定配置。发现记录中的 project_path_hint 是启动时的提示，连接后以 editor_get_context.project.path 为准，切换项目后应重新核对。

通过 GUI MCP 配置项目横竖屏 ​

配套新版 GUI 编辑器提供 project_get_orientation 和 project_set_orientation。先核对 editor_get_context.project.path，再调用 project_get_orientation 读取方向。结果包含 orientation、is_landscape、config_path 和 has_pending_orientation。修改时调用 project_set_orientation：

json
{"orientation":"portrait"}

portrait 为竖屏，landscape 为横屏；工具立即保存项目 config.ini 的 [map].is_landscape 并回读确认，返回 saved=true 及是否发生变化的 changed。未配置时默认横屏。已打开的项目设置面板会同步方向，但其它尚未保存的设置不会被提交。

若面板中已有未保存的横竖屏修改，工具返回 project_settings_unsaved；请先通过面板保存或取消，再重试。项目切换或 MCP 发布未结束时等待完成再写入。旧版 GUI 没有这些工具时使用项目设置面板并保存。Headless 暂不提供这两个 GUI 工具，按无头项目横竖屏配置编辑 INI。

配置用于后续调试与发布，不会调整已经运行的客户端窗口；屏幕方向、实际调试窗口尺寸仍需分别核验。

启动调试并取得连接信息 ​

debug_start、debug_start_no_compile 和 debug_start_with_resource_statistics 支持 game_in_editor：true 为 PIE，false 为连接服务端的独立客户端；省略时沿用编辑器调试设置。

取得 operation_id 后调用 debug_wait 或 debug_status。返回的 runtime_mcp 包含：

字段含义
statepending、ready、failed；操作已被替代时可能为 not_current
instance_id当前 Runtime 连接的实例 ID
port、endpoint已绑定的实际端口和 TCP 地址；未就绪时端口为 0
process_id、editor_process_idRuntime 与所属编辑器进程
operation_id、project_path启动操作与调试路径，可能为编辑器生成的副本
discovery_path本次启动的连接回报文件

当前连接也可从 editor_get_context.mcp.runtime 读取。端口就绪不等于游戏已开局：随后调用 runtime_list_targets 选择玩家，通过 debug.ping 核对项目、玩家、运行模式和新的 session_id。界面验收还应等待框架开局与加载页结束。

通常省略 Runtime 转发工具的 port，让宿主使用本次启动的实际连接：

json
{"name":"debug.ping","arguments":{},"target_id":"gameplay:42"}

新调试正在编译或等待连接时，自动转发不会回退到上一局。失败时检查调试状态和 runtime_mcp.error，不要复用旧端口或旧 target_id。

不同项目的远程调试局 ​

配套新版 2.0 GUI、Headless 与 Host 分配服务按“登录账号 + 项目 ID”分配远程 Host。同账号不同项目可各自保留调试局；同账号同项目重新调试会复用 Host 并结束上一局。每个 Host 仍服务一个项目，资源不足时需要等待。项目 ID 来自项目设置的 ProjectName，复制目录或改目录名不代表另一个项目。

远程 Host 分配与本地 Editor/Runtime 的端口、实例 ID、target_id 分别核对。为不同项目选择各自宿主，保留各自的调试操作和游戏局关联，停止时只操作目标项目。同一项目内的多个玩家属于同一调试局，继续通过玩家目标或动态客户端工具管理。

服务需先支持项目分配，再使用配套新版编辑器与脚本。host_lease_scope_unsupported 表示服务确认的范围缺失或不匹配，应升级匹配服务，不能静默回退后开局。旧客户端保持原分配方式，升级前先结束旧调试局。

固定端口与单次覆盖 ​

Editor MCP 默认首选 8765，占用时直接绑定其它候选端口；Runtime 默认由操作系统分配端口。Editor MCP 的 HTTP 监听器不支持直接绑定 0，因此使用有界的实际绑定重试，不采用先探测再释放端口的分配方式。

需要固定端口时，可在启动编辑器时传 --mcp-port=8766 -runtime_mcp_port=18776。--mcp-port=0 和 -runtime_mcp_port=0 表示自动模式。调试工具的 runtime_mcp_port 也接受 0，可单独为本次调试恢复自动分配。

优先级为：本次 MCP 调试参数 → 编辑器启动参数 → 自动分配。单次覆盖不改变下次默认值。显式端口占用时报告失败，不会悄悄换号或关闭原进程。已有 PIE 运行时，需先停止它，才能切换端口或改用独立客户端。

身份校验与直接连接 ​

编辑器发现记录位于当前用户临时目录的 SCE.Editor.MCP/instances/。正常退出时移除；发现过程过滤已退出进程和 PID 被复用的记录，HTTP helper 还核对 /health 的 instanceId。后续请求携带 X-SCE-Editor-Instance-Id；端口属于另一实例时，服务端会在执行请求前返回 editor_instance_mismatch。自定义 MCP 客户端也可通过 params._meta["sce/editorInstanceId"] 指定预期实例。

Runtime 回报位于同一用户临时目录的 SCE.Runtime.MCP/，按本次连接生成唯一文件名。宿主读取指定文件、校验端口与进程，并在请求信封的 params.runtime_instance_id 中携带实例 ID。不匹配时返回 runtime_instance_mismatch，目标工具不会执行。这些 ID 用于识别连接，不是认证凭据。

显式通过转发工具连接其它 Runtime 时，同时传入从该实例启动结果取得的 port 和 runtime_instance_id。仅在官方转发入口不可用或诊断 TCP 时，才直接使用 helper：

powershell
# 使用启动结果中的 runtimeMcp.port / runtimeMcp.instanceId。
./ai/tools/Invoke-SceRuntimeMcp.ps1 -Port $runtimePort -RuntimeInstanceId $runtimeId -Ping -Wait

项目内 Start-SceClientOnlyDebug.ps1 启动结果的 runtimeMcp 返回实际端口、实例 ID 和发现文件。-ResolveOnly 只返回计划，自动模式下 port=0，不能作为连接地址。已保存固定端口的旧配置仍沿用该值，可通过 -ExtraArgs @('-runtime_mcp_port=0') 改为自动模式。

本节 Editor/Runtime 自动发现流程适用于 GUI 编辑器与独立调试客户端。Headless 的内部 Native Control 在配套新版程序中也默认自动分配：省略 --native-service-port / --publish-service-port 或设为 0，由各自原生辅助进程绑定空闲端口并回报给无头编辑器；正数固定端口被占用时严格失败。Native Control 不属于 MCP，AI 通常通过 Editor MCP 发起操作，无需直接连接它。

Headless 的 Editor MCP、客户端 Runtime 端口及动态玩家接入仍按其当前工具 schema 和回执使用，不能将内部控制端口当成 Runtime 端口。详见无头编辑器指南。跨进程统一代理、多个视口同时独立注入输入属于其它能力；多人目标选择详见 Runtime MCP 调试指南。