SCE Editor MCP 工具速查

SCE Editor 接入 MCP 后，AI 助手可以直接调用下列工具，无需手动输入编辑器命令。

本页按 MCPServer.Tools 当前注册表整理；关键参数以 JSON Schema required 为准，表中 ? 表示可选。项目/场景生命周期的调用顺序、ready 状态、未保存策略和删除安全门见 Editor 生命周期 MCP Skill；触发器细节见 触发器 MCP Skill；项目 Shader 编译和 Technique 应用见 项目自定义 Shader Skill 与 项目自定义 Shader 与 Technique 指南；调试启动与 Runtime MCP 细节见 DebugTools Skill，多人 Gameplay 目标选择见 Runtime MCP 多人目标路由 Skill；UI 编辑器自动化见 UI Authoring MCP Skill。独立 TriggerMcpHost 下须 GET /health 中 mapReady: true 后再调 trigger_*；ui_*、debug_*、editor_get_context、runtime_*、uiauthoring_* 和 shader_* 等依赖完整编辑器、真实 PIE 或调试客户端的工具不适合作为独立 Host 的主要入口。

当 AI 客户端已经直接暴露这些 MCP 工具时，优先直接调用工具。若客户端没有直接暴露工具，但已有完整编辑器运行，可用项目生成的 ai/tools/Invoke-SceEditorMcp.ps1 作为 HTTP helper（单实例自动发现，多实例先 -ListInstances 再 -InstanceId）：它会先执行 MCP initialize / notifications/initialized，再 tools/list / tools/call，并默认拒绝连接到 TriggerMcpHost。

.\ai\tools\Invoke-SceEditorMcp.ps1 -Context -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -ListTools -ToolPrefix runtime_ -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool editor_get_context -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool runtime_call_tool -ArgumentsJson '{"name":"ui.snapshot","arguments":{"maxDepth":4,"maxNodes":200},"timeout_ms":10000}' -Pretty

---

数据编辑器（Data Editor）

表、条目与字段查询

工具	说明	关键参数
data_list_tables	列出所有数据表	无
data_get_table	获取数据表详情	tableIdOrPath
data_list_entries	按类型或名称筛选条目	filterMetaType?, filterEntryName?
data_get_entry	获取条目的完整 JSON	entryIdOrPath
data_get_field	获取指定字段值	entryIdOrPath, fieldPath
data_get_local_data	仅获取本地覆盖字段	entryIdOrPath
data_get_base_data	获取继承来的基础数据	entryIdOrPath
data_get_inherit	获取继承链	entryIdOrPath
data_get_field_status	查看字段来源：local / inherited / default	entryIdOrPath, fieldPath

GameData 类型、模板与符号

工具	说明	关键参数
gamedata_list_types	列出当前 GameData 类型系统中的类型	filter?, category?, instantiableOnly?
gamedata_get_type_schema	获取指定 GameData 类型的权威字段 schema	typeName
data_list_templates	按 MetaType、类别或名称列出 ScopeDataTemplate 模板条目	filterMetaType?, category?, filterName?, maxResults?
data_create_from_template	基于模板条目创建新条目并写入 $inherit	tableIdOrPath, entryName, templateEntryIdOrPath, entryData?
gamedata_get_generated_symbols	查询条目在生成代码中的内部符号、公开 Link 符号和脚本路径	entryIdOrPath

Link、资源与校验

工具	说明	关键参数
data_list_link_candidates	根据条目和字段路径列出合法 GameData Link 候选	entryIdOrPath, fieldPath
data_find_references	扫描当前 DataManager 数据，查找引用指定条目的字符串字段	entryIdOrPath, includeTemplates?
data_resolve_entry_links	解析单个条目的 GameData Link 字段和原始字符串引用	entryIdOrPath, includeRawReferences?
data_validate_links	校验单个条目或当前项目 ScopeData 的 Link/引用	entryIdOrPath?, includeTemplates?, includeRawReferences?, maxIssues?
gamedata_validate_entry	校验单个 GameData 条目的类型、字段、继承和 Link	entryIdOrPath
gamedata_validate_project	校验当前项目的 GameData 条目并汇总问题	includeTemplates?, includeWarnings?, maxReportedEntries?
resource_search	按资源类型和关键词搜索模型、图标、特效、音效、动画文件	query?, resourceType?, maxResults?, maxScannedFiles?

编辑器资源目录

工具	说明	关键参数
resource_catalog_list_categories	列出编辑器素材库分类树，可选返回通用标签，用于先探索云素材分类	resourceType?, includeLabels?, maxDepth?
resource_catalog_search	搜索编辑器公共资源、云素材库，以及当前项目/依赖库的 res/ 与 ui/ 资源	query?, resourceType?, category?, labels?, source?, rootKind?, maxResults?
resource_catalog_get_detail	按资源路径获取素材详情，确认来源、类型、分类、标签和本地可用状态	pathOrId
resource_get_preview_info	读取受支持资源的结构化预览摘要，不返回资源文件明文	pathOrId, includeCatalog?
resource_download	下载一个完整云资源到编辑器资源缓存	path
resource_download_batch	批量下载完整云资源，逐项返回结果	paths
resource_export	将已下载资源导出为项目可读取的明文文件；模型 prefab 和粒子 effect 默认保留目录依赖	path, destinationRoot, includeDependencies?, overwrite?, dryRun?, downloadIfMissing?
resource_export_batch	批量导出明文资源，逐项返回结果	paths, destinationRoot, includeDependencies?, overwrite?, dryRun?, downloadIfMissing?
resource_import_model_package	导入静态 XML/UMD2 模型包，解析 UUID、生成星火 prefab 并适配不透明 PBR 材质	sourcePath, destination, entryPoint?, displayName?, sourceUpAxis?, targetWidth? / scale?, alignGround?, roughness?, metallic?, dryRun?
resource_reload	重载当前项目指定资源目录的缓存并刷新资源树	path
resource_open_preview	请求打开美术资源库并定位当前项目 prefab	path

resourceType 支持 any、model、image、icon、particle、sound、animation、ui。source 支持 any、local、cloud、project。rootKind 用于项目资源过滤，支持 any、currentMap、editableLib、dependencyLib、project；例如 source=project, rootKind=currentMap 只列出当前项目自身 res/ / ui/ 资源，避免把依赖库资源混进短列表。

无项目状态下完整 Editor MCP 仍可启动，local / cloud 可用，project 会返回空结果和 warning；项目打开后，返回中的 availableSources 会包含 project，可扫描当前项目和依赖库资源。source=any 会尝试补充 cloud catalog，但 cloud 分支有耗时预算；如果返回 warning，应优先使用已返回的 local/project 结果，只有明确需要云素材时再改用 source=cloud、分类或标签缩小范围。

resource_get_preview_info 当前覆盖 prefab/mdl 模型、图片/图标、音效、动画、粒子和 UI 文件元数据。模型会返回 bbox、顶点数、三角面、材质和贴图摘要；图片/图标返回尺寸、格式、alpha 等 header 信息；音效返回时长、采样率、声道；动画返回长度、轨道和关键帧摘要；粒子返回 emitter、贴图/颜色帧等配置摘要；UI 文件返回格式和文件大小等 metadata。项目本地 res/ / ui/ 文件在 native preview 不可加载时会降级为本地文件 header metadata。预览工具只返回结构化摘要；需要阅读和修改文件内容时，使用 resource_export / resource_export_batch 获取项目副本，也不应依赖 fullPath / rootPath 这类内部路径字段。

资源选择工作流见 官方资源选择 Skill；云资源下载、明文导出和 AI 手写 .effect / prefab 样例见 云资源目录与明文导出 Skill 和 云资源 MCP 下载与明文导出指南。

模型依赖诊断新增 meshLoaded、dependenciesReady 和 diagnostics。依赖错误时 preview 保留部分元数据，但 success=false、loadStatus=loaded_with_dependency_errors；GPU shader 变体不由摘要工具验证。资源包导入先 dryRun 再执行，默认不覆盖已有资源。resource_open_preview 返回请求状态，仍需查看实际画面。完整步骤见 项目模型资源包导入。项目 res 内资源不要求资源统计。

---

项目自定义 Shader

这些工具要求完整 Editor MCP、当前项目已打开，并且 Editor 使用 DX11。它们只操作项目自己的 res/Shaders/BLGL 与 editor/shaders.precompile.json，不会重编官方 shadercacheextra。详细流程见 项目自定义 Shader Skill。

工具	说明	关键参数
shader_list_sources	列出项目 GLSL 源码，标记是否已进入预编译清单	无
shader_get_plan	读取并校验 editor/shaders.precompile.json	无
shader_save_plan	原子保存完整 Shader 清单；可用 expected_json 做并发修改保护	plan, expected_json?
shader_compile_project	按清单生成项目 res/Shaders/BLGL/Compiled；不传 apply 只 dry-run	apply?, platforms?
shader_scan_missing_variants	从 Compile Shader / Failed Compile / No Compile Result 日志提取阶段和 defines	log_paths?, max_files?
shader_validate_technique	只读检查 Technique XML 的 VS/PS/CS 引用和缺失源码	path

推荐顺序是 shader_list_sources -> shader_get_plan -> shader_validate_technique / shader_scan_missing_variants -> shader_save_plan -> shader_compile_project dry-run -> shader_compile_project with apply: true。编译成功后再启动 PIE，并用 Runtime material.probe 确认客户端实际 Technique、pass 和 defines。

创建、修改、删除

工具	说明	关键参数
data_create_table	创建新数据表	tablePath, tableType?
data_create_entry	在数据表中创建新条目	tableId, entryName, entryData?
data_set_field	设置单个字段	entryIdOrPath, fieldPath, value
data_set_fields	批量设置多个字段	entryIdOrPath, fields
data_update_entry	危险：用完整 JSON 覆盖条目本地数据，普通修改优先用字段级工具	entryIdOrPath, entryData
data_insert_field	在数组指定位置插入元素	entryIdOrPath, fieldPath, value
data_move_field	移动或重命名字段路径	entryIdOrPath, oldPath, newPath
data_move_table	移动或重命名数据表	fromPath, toPath
data_remove_field	完全删除本地字段	entryIdOrPath, fieldPaths[]
data_reset_field	重置字段到继承值	entryIdOrPath, fieldPaths[]
data_reset_entry	清空条目的所有本地覆盖	entryIdOrPath
data_delete_entry	删除条目	entryIdOrPath
data_delete_table	删除数据表及其所有条目	tableIdOrPath

保存与生成

工具	说明	关键参数
data_save	保存所有数据编辑器改动	无
data_save_and_generate	保存 DataManager 状态，校验并生成 src/DataGenerated，返回保存、校验、生成和文件变更摘要	generateAll?, validate?, failOnValidationErrors?, maxReportedEntries?
gamedata_generate_code	生成 GameData 代码到 src/DataGenerated；可选先保存或仅生成内存态数据	generateAll?, saveData?, validate?, failOnValidationErrors?, maxReportedEntries?

制作人工作流

工具	说明	关键参数
workflow_create_content_folder	一次性创建某个玩法内容根目录下的一组规范 ScopeData 表	contentRoot?, tables?
workflow_create_unit	创建或更新单位 Root，处理模板、显示名、资源、属性、技能 Link	entryName, contentRoot?, template?, templateEntryIdOrPath?, displayName?, stats?, abilities?, resources?, resourceHints?, fields?
workflow_create_ability	创建或更新技能 Root，可选创建 Effect 子条目并挂到单位	entryName, contentRoot?, template?, displayName?, description?, effect?, attachToUnits?, fields?
workflow_attach_ability_to_unit	把技能追加到单位的 Abilities 字段	unitEntryIdOrPath, abilityEntryIdOrPath, fieldPath?
workflow_create_spawner	创建通用生成器或生产建筑条目，并创建生成配置条目	entryName, contentRoot?, template?, displayName?, cost?, spawnEntries?, spawnIntervalSeconds?, spawnCount?, maxLevel?, fields?, config?
workflow_create_game_mode	创建玩法入口所需的 GameMode 和 PlayerSettings 条目	entryName?, contentRoot?, template?, displayName?, scene?, players?, teams?, playerSettings?, fields?
workflow_create_map_from_plan	根据通用玩法 plan 一次性创建目录、条目、Link、GameMode，并可保存、生成、校验	contentRoot?, createDefaultFolders?, tables?, entries?, links?, attachments?, gameMode?, save?, generateCode?, validate?

---

触发器编辑器（Trigger Editor）

普通 LibModule（触发器模块） 与并列的 Validator 校验器模块 为两套文件列表；parentPath / nodePath 首段须为对应列表中的文件名（与 trigger_list_files 或 trigger_list_validator_files 返回的 name 一致）。对 Validator 树内节点做 重命名 / 删除 / 启用 / 替换函数体 时须传 scope: "validator"（默认 trigger 仅解析触发器模块树）。

已无独立手动生成工具。trigger_create_*、trigger_rename、trigger_delete、trigger_set_enabled、trigger_replace_function_body 等写操作成功前会自动刷新 src/TriggerGenerated/；仍需 trigger_save 持久化触发器模型。

trigger_delete 已提供显式安全幂等模式和结构化写入结果。自动化应读取 outcome、changed、safeToRetry 与 persistence；若返回 outcome: "unknown"，表示模型可能已改变但生成结果无法确认，必须停止自动重试并先检查现场。

查询、API 与校验

工具	说明	关键参数
trigger_list_files	列出触发器模块侧文件（非 Validator）	env?
trigger_get_file	获取某触发器模块文件的树形概要	filePath
trigger_list_validator_files	列出 Validator 模块文件（与普通列表对称）	env?
trigger_get_validator_file	获取某 Validator 文件的树形概要	filePath
trigger_search	按名称搜索节点；结果含 tree（trigger 或 validator）	query, nodeType?, env?, scope?
trigger_inspect_references	只读检查节点的正向、反向与失效引用；路径或 Declaration ID 二选一	nodePath?, nodeId?, env?, scope?, maxResults?
trigger_get_editor_state	获取触发器编辑器当前状态	无
trigger_get_api_schema	查询当前触发器类型系统中的类、函数、事件、属性、Preset 摘要	query?, env?, kind?, maxResults?
trigger_validate_project	刷新生成代码，收集代码生成、节点错误和可选 Roslyn 编译诊断	env?, includeCompilation?, includeWarnings?, maxDiagnostics?

创建

工具	说明	关键参数
trigger_create_folder	在资源树中创建文件夹（仅分组，不改变生成目录结构）	name, parentPath?, env?
trigger_create_trigger	按 TriggerParser 约定从 C# 创建 Trigger 节点；单一事件类型使用强类型 Register，动态/多事件触发器使用 AddEvent<T>	env, code, parentPath?
trigger_create_function	在 partial class Scope 语义下解析，创建静态函数节点	env, code, parentPath?
trigger_create_variable	在 Scope 语义下解析静态字段	env, code, parentPath?
trigger_create_class	解析首个 class/struct/record，非嵌套在 Scope 内	env, code, parentPath?
trigger_create_preset	解析首个 enum，生成 Preset 节点	env, code, parentPath?
trigger_create_custom_event	创建 CustomEvent：主构造 + Events.ITriggerEvent<自身> 等约定	env, code, parentPath?
trigger_create_validator	在 Validator 模块中创建静态校验函数（partial class Validator 语义）	env, code, parentPath?

修改、删除与保存

工具	说明	关键参数
trigger_rename	重命名节点；同父级下新名须唯一	nodePath, newName, scope?
trigger_set_enabled	启用或禁用节点	nodePath, enabled, scope?
trigger_replace_function_body	仅替换已有静态函数或类成员函数的函数体；code 中方法名必须为 TempFunctionBody	parentPath, functionName, env, code, scope?
trigger_delete	安全删除节点；默认严格，ignoreIfMissing 仅在父路径精确有效且末级节点已不存在时幂等成功；存在外部引用时拒绝	nodePath, scope?, env?, ignoreIfMissing?
trigger_save	保存触发器改动	saveDependLibs?

---

UI 状态查询（数据编辑器）

工具	说明	关键参数
ui_get_editor_state	获取数据编辑器整体状态，包括当前表、选中条目、选中字段、未保存状态等	无
ui_get_current_table	获取当前打开的数据表	无
ui_get_selected_entry	获取当前选中的条目	无
ui_get_selected_field	获取当前选中的字段	无

---

UI 编辑器自动化（UI Authoring）

这些工具面向编辑器内 UI Authoring 的 AI 自动化操作与验证。AI 助手可以启动真实 UI 编辑器 PIE、读取当前 GameUI hierarchy、按源数据或运行时 handle 选择控件、切换 Edit/Interact、刷新 hierarchy，并打开或关闭真实 Workbench。它们不是普通项目运行时代码 API，也不是 Runtime MCP 的替代入口；需要完整 Editor MCP 和已打开的项目。

工具	说明	关键参数
uiauthoring_start	启动当前项目的 UI Authoring PIE，立即返回异步 operation_id	viewport_id?, mobile_renderer_emulation?, timeout_ms?
uiauthoring_status	查询 uiauthoring_start 操作状态	operation_id
uiauthoring_wait	等待启动操作进入 succeeded、failed 或 cancelled；超时返回当前阶段	operation_id, timeout_ms?
uiauthoring_stop	停止当前 UI Authoring PIE，并等待原生 session 失效	viewport_id?, timeout_ms?
uiauthoring_get_state	返回原生 session/hierarchy 与真实 Workbench window/host snapshot 的组合结构化状态	viewport_id?, include_hierarchy_flat?
uiauthoring_refresh	通过原生 UIAuthoring manager 刷新 hierarchy，并返回 request/result	viewport_id?, timeout_ms?
uiauthoring_set_mode	切换 Edit / Interact 模式，并返回 mode 与 input gate 状态	mode, viewport_id?, timeout_ms?
uiauthoring_select	按 handle、source_entry_id、source_definition_hash 或 source_definition_id 选择 live 节点；歧义时返回候选列表	selector, viewport_id?, timeout_ms?
uiauthoring_open_workbench	打开或激活真实 UIAuthoringWindow，不重启已有效 session	timeout_ms?
uiauthoring_close_workbench	调用真实 WinUI Window.Close() 路径关闭 Workbench，并等待 host/snapshot 消失	timeout_ms?

常见自动化顺序：

uiauthoring_start -> uiauthoring_wait -> uiauthoring_get_state -> uiauthoring_open_workbench -> uiauthoring_select -> uiauthoring_set_mode -> uiauthoring_refresh -> uiauthoring_close_workbench -> uiauthoring_get_state -> uiauthoring_stop

uiauthoring_get_state 在 Workbench 关闭后仍应能读取 native session；Workbench 部分会明确报告 window/host/snapshot 不可用。自动化中途失败时优先调用 uiauthoring_stop 清理 PIE。更完整的使用流程见 UI 编辑器自动化 MCP Skill。

更新编辑器及配套脚本后，启动构建失败会保留实际 phase，例如 generating_code；uiauthoring_status / uiauthoring_wait 的可选 build 对象包含 build_id、state、phase、message、is_terminal、failure_kind、exit_code、diagnostic_count、diagnostic_summary、result_path、log_path 和 log_paths，并保留关联 request_id。摘要最多取前三条错误并截短；完整诊断用返回的 build_id 查询 build_status / build_diagnostics，或读取 result_path 和完整日志。代码生成异常另写 generating_code-failure.log，包含内部异常。信息列表的 UIAuthoring 来源也会持久显示本次失败、阶段和构建编号。修复生成错误后重新启动，不以跳过编译掩盖失败。

没有直接 MCP 工具暴露时，可用 HTTP helper 跑内置 P0 smoke：

.\ai\tools\Invoke-SceEditorMcp.ps1 -Smoke UiauthoringP0 -Pretty

---

调试与 Runtime MCP

发布当前项目

完整编辑器支持由 AI 发起项目上传并查询后台发布结果。需更新编辑器及配套 XDEditor、Script，并先登录。发布沿用当前编辑器环境和项目原有后台配置；依赖库使用其独立上传流程。

工具	说明	关键参数
project_publish_start	保存、生成代码与资源统计、复制发布文件并上传当前项目，返回操作编号	project_path
project_publish_status	查询本次操作的阶段、受理情况、最终结果及诊断	operation_id
project_publish_wait	等待后台最终结果；等待超时不会取消发布	operation_id, timeout_ms?

先通过 editor_get_context 获取当前项目的绝对路径，作为 project_publish_start.project_path；路径不匹配会拒绝发布。启动未收到响应时返回 start_timed_out 和操作编号，先查询该编号，避免重复上传。

project_publish_wait.timeout_ms 范围为 0 到 20000，默认 20000，为外层传输的 30 秒时限预留响应时间。等待超时返回 timed_out: true、原 operation_id 和当前状态；继续用同一编号调用 status 或 wait。等待超时不表示发布失败，也不应再次发起上传。

accepted 只确认上传已受理，succeeded 才表示后台发布成功。failed 表示明确失败，详细原因见 phase、message、details；unknown 表示上传或处理结果尚未确认，应继续查询或查看返回的 backend_url。publish_completed 表示已收到后台最终结果，upload_accepted 表示上传已被确认受理。准备和上传期间会拒绝重复启动。

未上传的依赖资源会返回 dependency_resources 阶段及资源列表，需要先上传这些资源再重试。工具不会自动替用户发布依赖资源，也不执行创作者中心的审核、上架或环境晋级。状态保留在当前编辑器进程内，最多保留最近 128 个操作；后台结果来自现有通知，通知监听最多保留 30 分钟，断线或重启后应到创作者中心确认结果。

核对发布包中的 UI 图集

配套发布服务更新后，成功终态会带 publish_identity：project_id、environment、正整数 version 和 platform_variants 数组。列表来自本次实际上传成功的公开平台归档，工具不自行猜测平台。旧操作不回填身份；缺少身份时先核对发布服务及编辑器脚本版本，不能手填版本或 URL 代替。

工具	说明	关键参数
project_publish_verify_resources	启动后台只读校验，立即返回 verification_id	project_path, 发布 operation_id, platform_variant, timeout_ms?, retry_failed?
project_publish_verify_resources_status	查询当前状态或完整终态报告	verification_id
project_publish_verify_resources_wait	有界等待；超时后任务继续	verification_id, timeout_ms?

项目路径必须匹配当前打开的项目及原发布操作；操作须已成功完成，platform_variant 必须从该次 publish_identity.platform_variants 精确选择。调用方不能传入下载地址、版本或跨项目路径。当前下载契约支持标准 sce-maps-<environment> 上海 OSS 桶中的 .7z 平台包；不满足此契约时明确拒绝，不猜测其它存储位置。运行环境需可用的 7z.exe。

{
  "name": "project_publish_verify_resources",
  "arguments": {
    "project_path": "C:/Projects/MyGame",
    "operation_id": "<本次成功发布的操作编号>",
    "platform_variant": "<该次身份返回的实际变体>"
  }
}

启动结果返回 verification_id、publish_operation_id、state 和 created_at。同一发布操作及变体重复启动会续查同一校验，不重复下载。后台总时限 timeout_ms 为 1000..300000，默认 120000；wait 的等待时间为 0..20000，默认 10000。wait 返回 timed_out: true 或 HTTP 请求取消时，后台任务继续，使用原 verification_id 查询。总时限超出则保留 state: "failed"、report.error_code: "verification_timeout"；需要重新下载时显式传入 retry_failed: true。进程内最多同时运行两个校验，保留最近 32 个任务，重启后不保留。

终态为 succeeded 或 failed，附 completed_at 和 report。报告包含发布身份、包大小及 SHA-256、文件哈希、纹理实际容器/格式/尺寸、区域清单和 issues。清单与区域 JSON 逐字节核对，差异为 published_json_mismatch 错误；区域缺失、重复逻辑名、越界、非法路径和损坏的 KTX 数据也会报错。相同矩形及区域重叠属于警告。没有 ui/atlas/atlas.json 时明确报告缺失，此工具并非全部项目资源的通用完整性证明。

纹理检查当前支持 KTX 1 容器，包含 BC7 数据长度检查；源 PNG 转换为压缩纹理后哈希不同不直接判为错误。pixel_check: "not_checked_decoder_unavailable" 明确表示没有解码比对像素，其他容器会报告不支持。校验通过不能替代目标客户端截图和实际进局验收。资源制作及边缘排查见自定义 UI 图集。

编辑器调试启动

工具	说明	关键参数
debug_start	执行编辑器「调试」流程：保存地图、编译 GameEntry 并启动调试	game_in_editor?, runtime_mcp_port?
debug_start_no_compile	执行「调试(不编译)」流程：保存地图并启动调试，跳过编译	game_in_editor?, runtime_mcp_port?
debug_stop	请求关闭当前编辑器内嵌调试游戏，通知调试 Host 销毁当前对局	find_last_game?
resource_statistics_generate_animations	执行「资源统计和动画重定向/统计资源并生成」流程，生成 ref/model_animation.json 并烘焙 Humanoid 动画	无
debug_start_with_resource_statistics	先全量资源统计并生成 Humanoid 烘焙动画，再启动编辑器调试	skip_compile?, game_in_editor?, runtime_mcp_port?
debug_status / debug_wait	查询或等待调试操作，并附带关联构建结果	operation_id, timeout_ms?
build_status / build_diagnostics	查询构建阶段、日志及分页错误/警告；省略 ID 时取当前项目最近一次构建	build_id?, operation_id?, offset?, limit?
build_start	保存数据/触发器、生成代码、编译双端并部署 AppBundle，不开局；支持依赖库	无
editor_dialog_snapshot	读取共享编辑器消息框的内容、用途、稳定 ID 和按钮状态	无
editor_dialog_choose	按匹配 ID 选择可用按钮并走原有回调	dialog_id, choice
build_wait / build_cancel	等待或取消构建，等待超时不取消后台任务	build_id?, timeout_ms?

普通代码修改可使用 debug_start → debug_wait，失败后按返回的 build_id 调用 build_diagnostics。新版编辑器在信息面板“编译”模块显示错误，完整日志位于 <EditorRoot>/logs/build/，具体路径由构建结果返回。构建成功代表编译与部署完成，游戏局启动仍以调试操作和 Runtime MCP 为准。上述构建工具需要更新完整编辑器。

依赖库或只验证编译的游戏项目使用 build_start → build_wait(build_id)：保存与生成数据/触发器，编译 Server-Debug、Client-Debug 并部署后结束，不创建游戏局。启动超时先按 operation_id 查询 build_status；编译失败按该 build_id 读取 build_diagnostics。直接调试依赖库会返回 dependency_library_requires_test_project，运行行为应在引用该库的游戏项目中验收。完整步骤见只生成与编译。

共享消息框阻挡操作时，先用 editor_dialog_snapshot 读取内容与可用按钮，再以同一 dialog_id 调用 editor_dialog_choose。choice 为 confirm、cancel 或 close；窗口变化返回 dialog_changed，隐藏或禁用按钮返回 dialog_button_unavailable。工具执行原有按钮回调，不处理系统文件选择框与进度窗口。

用户可在“信息列表” → “编辑器”页 → “编译”来源中查看同一构建的诊断。失败或超时会自动切换到该页与来源，清空搜索并显示全部严重级别；具体错误行右侧提供源码路径及行列链接，构建阶段消息右侧提供日志路径链接。源码用系统关联程序打开，暂不自动跳到 IDE 对应行。自动化应按 build_id 查询结果与日志，避免读取项目根目录的旧日志；操作步骤见编译失败时查看错误和日志。

debug_start_no_compile 前应先在地图工程中完成 Server/Client 编译，并把最新 GameEntry.dll 分别复制到 AppBundle/managed/ 与 ui/AppBundle/managed/。细节见 DebugTools Skill。

自动化调试完成后优先调用 debug_stop 清理内嵌调试游戏；编辑器内调试不是独立游戏进程，不应通过外部进程枚举/杀进程来关闭。

编辑器内调试的脚本侧日志通常在 <EditorRoot>\logs 下：服务端 wasm 日志看 server 子目录，客户端 wasm 日志看 client 子目录。

当编辑器调试时出现 dash.ani 等 Humanoid 技能动画播放不出来、项目 res/anim 下缺少烘焙动画时，优先调用 debug_start_with_resource_statistics；它比普通 debug_start 多跑一遍 Client-Resource 资源统计和动画烘焙。

离散瓦片地形 MCP

离散瓦片地形 MCP 已覆盖离散地形的地表风格/纹理、TileSet、高度、水域、道路、装饰物、确定性散布、Undo/Redo、保存与校验。推荐先阅读 离散瓦片地形 MCP Skill 和 离散瓦片地形 MCP 创作指南，再按当前工具 schema 调用。该能力目前为 Preview/Early Access；Runtime terrain.snapshot 返回 observation、sampling、tile_sets、water 和 roads 观测块，必须先按状态字段解释空值。tile_sets.status=catalog_available 表示客户端已加载的 TileSet/style 配置目录可见；当 distribution_status=available 时，distribution 提供实际运行时 tile style 的计数、TileSet 映射和地图瓦片尺寸，无法读取时仍返回明确的 no_data 状态；详细水域/道路拓扑仍明确标记为不支持。

Terrain 修改采用 terrain_preview_* -> terrain_apply_* -> terrain_save_scene -> terrain_validate_scene。离散瓦片地形的高度输入是离散层；不同 TileThickness 的 TileSet 可以共存，但同一次跨厚度非零高度编辑会以 terrain_height_tile_thickness_inconsistent 安全拒绝。新建场景若要跨 reload/reopen 保留场景索引，除 terrain_save_scene 外还必须调用 data_save 或 data_save_and_generate。

能力	工具
场景与状态	terrain_list_scenes、terrain_get_scene_summary、terrain_get_state、terrain_validate_scene
地表与 TileSet	terrain_list_surface_styles、terrain_list_surface_textures、terrain_preview_surface_paint / terrain_apply_surface_paint、terrain_list_tile_sets、terrain_preview_tile_set_paint / terrain_apply_tile_set_paint
项目自定义地表资源	terrain_preview_project_surface_import / terrain_apply_project_surface_import、terrain_preview_project_surface_generate / terrain_apply_project_surface_generate、terrain_project_surface_status / terrain_project_surface_wait
高度与水域	terrain_preview_height_edit / terrain_apply_height_edit、terrain_preview_water_edit / terrain_apply_water_edit
台阶/斜坡	terrain_list_ramp_styles、terrain_preview_ramp_edit / terrain_apply_ramp_edit；旧 terrain_*path_edit 保留相同台阶语义
道路	terrain_list_road_styles、terrain_preview_road_edit / terrain_apply_road_edit
裂缝	terrain_preview_crack_edit / terrain_apply_crack_edit
手绘碰撞	terrain_query_collision、terrain_preview_collision_edit / terrain_apply_collision_edit
视野遮挡	terrain_query_sight、terrain_preview_sight_edit / terrain_apply_sight_edit
装饰物	terrain_list_decoration_resources、terrain_query_decorations、terrain_preview_decoration_edit / terrain_apply_decoration_edit、terrain_preview_decoration_scatter / terrain_apply_decoration_scatter
历史与保存	terrain_list_history、terrain_undo、terrain_redo、terrain_save_scene

手绘碰撞与视野遮挡按区域内格子中心选择；裂缝按地形边中点选择。道路工具使用区域、道路样式和密度，台阶工具使用折线、宽度与台阶样式。手绘碰撞查询不包含烘焙地形/装饰物；Surface2D 静态碰撞需显式保存场景后再调试验收。发射自身并遇静态障碍停止的技能配置见 冲锋静态碰撞 Skill。

场景氛围 .lightgroup MCP

工具	说明
terrain_get_atmosphere	查询当前氛围路径、存储方式、Zone/主光属性目录与主光欧拉角
terrain_preview_atmosphere_edit	只读检查 zone / main_light 部分补丁及 main_light_rotation，返回确认 token/hash
terrain_apply_atmosphere_edit	应用相同补丁及 token/hash，生成单条 terrain.atmosphere_edit 撤销事务，不自动保存

属性名称、类型、枚举选项和可编辑状态以实时查询为准；颜色为 0~1 RGBA 数组，资源填写现存逻辑路径，主光方向为度数欧拉角 [x,y,z]。保存当前场景才会写回引用的 .lightgroup；离散瓦片地形可用 terrain_save_scene，其他地形使用编辑器正常保存。详见 氛围指南 和 氛围 MCP Skill。

项目与场景生命周期

完整调用协议和安全约束见 Editor 生命周期 MCP Skill。

工具	说明	关键参数
editor_get_context	读取当前 Editor、项目、场景、DataManager、SDK 和生命周期状态	无
editor_list_instances	列出本用户仍在运行的编辑器实例及连接地址；连接后核对项目路径	无
editor_open_project	在当前 Editor 进程打开或切换项目	path, unsaved_strategy
editor_reload_project	重载当前项目并等待 DataManager/GameDataManager ready	unsaved_strategy?
editor_open_scene	打开当前项目 scene/ 下的一级场景目录	scene_path
editor_reload_scene	重载当前场景	无
editor_create_scene	创建一级空白测试场景；可先 Preview	scene_path, preview?
editor_delete_scene	先 Preview，再确认删除非当前、非 default 场景	scene_path, preview?, confirm?
editor_lifecycle_status	查询最近一次或指定生命周期 operation	operation_id?
editor_lifecycle_wait	等待 operation 进入终态	operation_id, timeout_ms?

editor_get_context.ready_state 使用语义状态：无项目为 editor_ready，项目已加载且无场景为 project_ready，场景和 DataManager/GameDataManager 均 ready 为 scene_ready；进行中为 project_loading、scene_loading 或 busy。生命周期工具返回 operation_id 后，必须调用 editor_lifecycle_wait，再用 editor_get_context 验证最终项目、场景和 ready 状态。

unsaved_strategy 必须明确为 save、discard 或 cancel。项目切换和重载只有在 DataManager/GameDataManager 完成加载后才算成功。scene_path 只接受当前项目 scene/ 下的一级目录名，不接受绝对路径、.. 或嵌套目录。MCP 不允许删除当前场景或 default 场景；项目有未保存修改时，确认删除返回 unsaved_changes。

创建测试场景后，若要跨项目 reload/reopen 保留场景索引，必须显式调用 data_save 或 data_save_and_generate；Terrain 修改还需调用 terrain_save_scene。推荐闭环为：

editor_create_scene(preview=true)
-> editor_create_scene
-> editor_lifecycle_wait
-> terrain_save_scene? + data_save
-> editor_reload_scene / editor_reload_project
-> editor_open_scene(保留场景)
-> editor_delete_scene(preview=true)
-> editor_delete_scene(confirm=true)
-> editor_lifecycle_wait
-> editor_get_context + terrain_list_scenes

完整的外部 agent 调用顺序、错误恢复和验收证据要求见 SCE 编辑器项目与场景生命周期 MCP Skill。

调试客户端 Runtime MCP

默认省略 Runtime 端口，由当前编辑器发现并校验本次调试实例；显式连接其它端口时同时提供 runtime_instance_id。自动端口、实例选择、启动参数和单次覆盖详见 多开编辑器与 MCP 调试连接。

工具	说明	关键参数
editor_get_context	返回当前项目、Editor、SDK、helper 安装和 MCP 端口的结构化 readiness 诊断	无
runtime_list_targets	列出当前 Client 进程内可路由的 Gameplay Runtime 目标	port?, runtime_instance_id?, timeout_ms?
runtime_list_tools	通过 bridge 列出指定客户端目标实际注册的 Runtime 工具与 schema	target_id?, port?, runtime_instance_id?, timeout_ms?
runtime_call_tool	调用指定调试客户端目标内的 Runtime MCP 工具；脚本侧工具不会出现在外层 MCP tools/list	name, arguments?, target_id?, port?, runtime_instance_id?, timeout_ms?

常见 Runtime 工具名包括 debug.ping、debug.list_tools、debug.capture_screenshot、scenegraph.materials、material.probe、ui.snapshot、ui.find、ui.get_rect、ui.click、input.pointer、input.key、input.text、input.reset；实际以 runtime_list_tools 或调试客户端内 debug.list_tools 返回为准。scenegraph.materials 和 material.probe 用于检查运行中客户端的 StaticMeshComponent 材质、technique path、base/alpha/depth/singlelayerwater pass 命中、cull/fill/stencil/renderOrder 等状态，适合配合 RenderDoc 排查 GameGraph 3D 材质问题。旧的 shader_path 字段仍会返回以兼容已有工具。Label 快照包含 rich_text_spans，可将控件 id 和 link_id 直接传给 ui.click，无需猜测富文本命中坐标。需要悬停、拖拽、滚轮、组合键或焦点文本输入时再使用 input.*；中断持有输入后调用 input.reset。ui.* 返回的 rect_px 坐标可直接用于嵌入式编辑器调试和纯客户端调试，不要叠加编辑器外框偏移，也不要使用缩放后截图的像素坐标。完整参数和状态语义见 Runtime MCP 调试指南。

多人内嵌调试时，先调用 runtime_list_targets，再按 slot_id、player_id 或唯一 is_foreground=true 目标选择 target_id。多个目标下不得静默使用第一个；runtime_list_tools 和后续 runtime_call_tool 必须持续携带同一个 ID。Gameplay 重建后旧 ID 失效，应重新发现。第一阶段只路由 Runtime/Wasmtime 状态；input.* 仍受进程级焦点限制。需要完整的匹配顺序、错误恢复和证据要求时，遵循 Runtime MCP 多人目标路由 Skill。

通过外层 Editor MCP bridge 读取 Runtime 工具列表时，runtime_list_tools 与 runtime_call_tool(name: "debug.list_tools") 的 Runtime payload 位于返回 JSON 的 result 字段下；请读取 result.tools / result.count，不要把顶层对象当成 runtime 工具列表。direct TCP fallback 直接返回 payload，调用方可统一使用 parsed.result ?? parsed 解包。

debug.ping 的 game / project_id、game_session_id、local_player_id 和运行模式来自当前游戏局；startup_arguments 单独保留编辑器进程启动时的参数。更新配套编辑器后，原生路由还会返回所选目标的 target_id、gameplay_uuid、map_path、slot_id 和字符串 player_id，runtime_identity_source 为 native_gameplay。仅更新依赖库、仍使用旧编辑器时，来源为 managed_game，无法取得的路径和原生路由字段为 null；初始化未完成时也可能有未知字段，不应用启动参数补成当前身份。多目标时先列出目标并显式指定 target_id。

没有直接 MCP 工具暴露时，HTTP helper 可以通过完整编辑器调用 bridge，并提供可重复 Runtime smoke：

.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool runtime_list_targets -ArgumentsJson '{"timeout_ms":10000}' -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool runtime_list_tools -ArgumentsJson '{"timeout_ms":10000}' -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool runtime_call_tool -ArgumentsJson '{"target_id":"gameplay:42","name":"ui.snapshot","arguments":{"maxDepth":4,"maxNodes":200},"timeout_ms":10000}' -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Smoke RuntimeMcp -RuntimeDebugStartMode NoCompile -Pretty

-Smoke RuntimeMcp 会按 -RuntimeDebugStartMode 启动编辑器调试、等待 debug_wait、轮询调试客户端刚启动时短暂的 Runtime 不可用状态，并在结束时调用 debug_stop 清理。AI Agent 不应在 debug_start_no_compile 刚返回后立刻手写 runtime_list_tools，否则可能撞上 Wasmtime 状态尚未完成初始化的窗口期。

---

测试工具

工具	说明	关键参数
mcp_test_quick	快速验证 MCP 连接和基本工具是否正常	无
mcp_run_tests	运行 MCP 工具单元测试	category?, verbose?

category 支持：all、data、trigger。

---

常用工作流

修改数据条目

data_list_tables -> data_get_table -> data_get_entry -> gamedata_get_type_schema -> data_set_fields -> data_save_and_generate?

基于模板创建条目

data_list_templates -> data_create_from_template -> data_set_fields? -> gamedata_validate_entry -> data_save_and_generate?

设置 Link 字段

gamedata_get_type_schema -> data_list_link_candidates -> data_set_field -> data_resolve_entry_links -> data_save

删除条目前查引用

data_find_references -> data_delete_entry -> data_save_and_generate?

一次性创建玩法数据

workflow_create_map_from_plan(save: true, generateCode: true, validate: true) -> gamedata_validate_project?

创建新触发器

trigger_get_api_schema? -> trigger_list_files -> trigger_create_folder? -> trigger_create_trigger -> trigger_save -> trigger_validate_project?

仅替换函数体

trigger_search -> trigger_replace_function_body -> trigger_save -> trigger_validate_project?

查找并禁用触发器

trigger_search -> trigger_set_enabled -> trigger_save

Validator 上搜索加 scope: "validator"；禁用同路径须带 scope: "validator"。

创建校验函数（Validator）

trigger_list_validator_files -> trigger_create_validator -> trigger_save -> trigger_validate_project?

启动调试并检查运行时

debug_start 或 debug_start_no_compile -> runtime_call_tool(name: "debug.ping") -> runtime_call_tool(name: "debug.list_tools") -> debug_stop

Humanoid 动画缺失后启动调试

debug_start_with_resource_statistics -> runtime_call_tool(name: "debug.ping") -> 查看客户端日志/信息面板

如果只需要补生成 ref/model_animation.json 和 res/anim，不需要启动游戏：

resource_statistics_generate_animations -> 检查 ref/model_animation.json 和 res/anim/<ModelName>/

---

路径格式说明

• 数据条目路径：GameEntry/ScopeData/GameDataUnit/FireDragonUnit
• 触发器 / Validator 节点路径：文件名/文件夹/节点名（首段为对应环境中的 LibModule 文件名；不要把「仅在库根下创建的文件夹名」当作首段，详见 Skill 中 parentPath 的合法根）
• 字段路径：Stats.MaxHP、Abilities[0].Name
• Runtime MCP 工具名：由调试客户端注册，外层只通过 runtime_call_tool 透传

---

注意事项

1. 触发器手动生成工具已移除；触发器写操作会自动刷新 src/TriggerGenerated/，但仍需 trigger_save 保存触发器模型。
2. 修改数据后需要同步运行时代码时，优先调用 data_save_and_generate 一步完成保存、校验和生成；只保存源数据时调用 data_save。完整编辑器已加载项目但数据编辑器面板未打开时，生成工具会自动加载 DataManager；没有加载项目时会返回 no_project_loaded。
3. data_update_entry、data_delete_entry、data_delete_table、data_move_table 前要先读取现状；删除或替换 Link 目标前先用 data_find_references。
4. data_delete_table 会删除整张表和所有条目，操作不可撤销。
5. 写入类工具（创建、修改、删除、保存、生成、调试启动等）不要并行；须等上一调用返回后再发下一请求。
6. tools/call 返回里先看 isError；trigger_*、runtime_call_tool 等业务失败时 content[0].text 可能是 JSON 字符串，需再解析错误码和消息。
7. debug_start_no_compile 不会编译或复制 DLL；若 AppBundle 中 DLL 过旧，运行结果会和刚编译的源码不一致。
8. debug_start_with_resource_statistics 会额外跑全量资源统计和 Humanoid 动画烘焙，适合修复调试前资源/动画清单，不适合作为每次最快速调试的默认入口。

---

推荐阅读

• SCE Editor MCP 接入指南
• SCE 数据编辑器 Skill
• 数编 MCP 工作流
• SCE 触发器编辑器 MCP Skill
• DebugTools Skill
• 纯客户端调试启动 Skill