星火 2.0 开发文档

主题

SCE Editor 包修复 ​

使用独立的 SCEPackageRepair WinUI 工具或 SCEPackageRepair.Cli.exe CLI 检查、重置和清理编辑器依赖包。WinUI 与 CLI 必须使用同一套受控包白名单和路径规则。

包操作的有效更新渠道只有 Update\\editor-*.spark.xd.com。所有 Update 直属目录中以 e. 开头的目录都视为异常下载源，不得用于 list、reset 或 prune；应先用 sources 单独报告，并在用户明确要求后用 remove-sources --apply 删除。

受控包与边界 ​

支持：editor_bcd、global_default、gamesparkcore、gamesystemui、lib_game_options、wasicoresdk。

  • 所有包都可从当前编辑器渠道 Update\\editor-*.spark.xd.com\\VERSION.JSON 移除本地版本记录。
  • global_default、gamesparkcore、gamesystemui、lib_game_options 的缓存位于当前编辑器渠道 Update\\editor-*.spark.xd.com\\res\\_m 对应包目录（包含各版本子目录）；wasicoresdk 位于 Update\\editor-*.spark.xd.com\\res\\_m\\wasm\\wasicoresdk。
  • editor_bcd 首版只清版本记录，不删除当前渠道 res\\editor。该目录还包含其他编辑器资源；独立 engineres 包提供 RenderPath。
  • 不触碰项目的 editor/data、ScopeData、AppBundle、ui、user_files 或自定义依赖库目录。

实际路径必须由工具根据版本记录/清单计算。禁止把用户输入直接拼接成删除路径。

标准流程 ​

  1. 先关闭 SCE Editor、更新器和下载子进程。若进程仍在运行，让工具报告并拒绝写操作。
  2. 先使用 sources --json 检查是否存在 e.* 异常下载源，再使用 CLI list --json 获取安装根目录、有效编辑器渠道、API 版本、包版本、variation、实际包路径和 _m 历史目录。不要仅凭症状猜包。
  3. 将症状映射到高概率包，再检查实际包内容和自定义依赖链。
  4. 先执行 reset ... --dry-run --json，向用户说明将修改的版本记录、备份路径、删除路径和预计释放空间。
  5. 只有用户明确要求应用时才执行 --apply。未知包 ID、越界路径、版本文件解析失败或文件占用时停止，不绕过保护。
  6. 操作后重新运行 list --json，确认版本项已移除、允许清理的缓存已删除、当前渠道 res\\editor 未被删除，并说明下一次更新流程会重新下载。
  7. 若只是回收旧空间而不是修复当前包，使用 prune，保留当前版本；不要用 prune 代替损坏包的 reset。
  8. 操作完成或异常退出后，读取安装根目录的 package-repair.log；若不可写则读取 %LOCALAPPDATA%\SCE\PackageRepair\package-repair.log。结合最后一个 package_started / package_result 或 source_started / source_result 判断处理停在哪个包或异常源。

示例（参数名称以安装包的 --help 为准）：

powershell
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" list --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" diagnose --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" sources --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" remove-sources --all --apply --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" reset --package gamesparkcore --package gamesystemui --dry-run --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" reset --package gamesparkcore --package gamesystemui --apply --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" prune --package gamesparkcore --package wasicoresdk --apply --json

删除物理缓存失败时，不要接受“版本记录已经清掉”的半成功结果；工具应先报告失败并保留可恢复的状态。始终保存结构化 JSON 结果，便于 AI 后续对照。

症状到包的排查映射 ​

项目名称 [nil] 与 配置名称 [lib_game_options] 不符 ​

检查当前 lib_game_options 包：编辑器变体应有 editor 文件夹；客户端变体没有；若包是 .pak 而编辑器包应为散文件，也是不正确的变体。重置 lib_game_options，不要修改项目配置来规避。

数据编辑器模板缺失，或场景列表缺失 ​

先检查 gamesparkcore\\editor 中对应模板 JSON 和 $inherit 路径。模板也可能来自自定义依赖库或项目自身，因此不能把所有模板错误归因于 gamesparkcore。数据编辑器有场景 JSON、地形编辑器却无场景列表时，重点检查 gamesparkcore，并一并检查 global_default、gamesystemui 的版本和依赖链。

触发编辑器没有官方 API ​

优先诊断 global_default。

官方技能摇杆、物品栏、移动摇杆丢失 ​

优先诊断 gamesystemui。

编译时找不到 GameDataScene、GameDataUnit 或命名空间 ​

在排除二义性后，检查 gamesparkcore/gamesystemui。纯命令行 + AI 项目可能直到编译或 patch 依赖库数据时才发现错误；仍需检查项目引用、自定义依赖和生成输出。

地形编辑器场景视图中的镜头、灯光指示器图标丢失 ​

优先诊断 editor_bcd。只清版本记录并让更新器重下；不要删除整个当前渠道 res\\editor，不要删除 engineres。

这些映射是排查起点，不是证据替代品。遇到自定义模板、私有依赖或多个包同时异常时，保留完整诊断 JSON 并按 $inherit、包变体和日志逐层缩小范围。

WinUI 的 reset / prune 在后台任务中执行，界面会暂时禁用相关控件。若 WinUI 仍然无响应或崩溃，先保留 package-repair.log，再检查 Windows WER 的 Application Error、.NET Runtime 和 Windows Error Reporting 事件；不要在没有日志的情况下重复执行物理删除。

输出要求 ​

向用户报告：安装根目录、有效的 editor-*.spark.xd.com 渠道/API 版本、检测到的 e.* 异常下载源、选中的包、旧版本/variation、检测到的物理路径、计划或实际删除路径、备份路径、释放空间、失败原因以及下一步重下载验证。不要报告或请求任意 token、远端凭据或未授权路径。