星火 2.0 开发文档

主题

技能试验场 ​

本 Skill 用于技能试验场的双端调试。开始前从用户实际 SDK/API 和调试工具 schema 确认能力。功能要求 Game.IsDebugTestMode 和真实服务端调试局，生产对局拒绝入口；纯客户端运行不能替代权威施法验证。

进入面板 ​

  • 当前 GameDataGameMode 使用 AbilityTestArena / AbilityTestArenas 引用 GameDataSkillTestArena；旧字段仍兼容读取。未配置时服务端回退到 SceneList 第一个场景和当前主控单位，并以枚举结果报告缺少场景或主控的原因。
  • 用编辑器普通调试流程完成服务端上传、调试 Host 开局和客户端连接。进入正常游戏阶段后，点击 PIE 顶部调试栏的 技能调试；它仅在调试对局中请求真实服务端会话，不占用项目游戏画面中的 UI。面板单次施放默认以当前主控为目标，单位/地点目标通过 ability_test.command 传入。
  • 打开后先读 ability_test.snapshot 或执行 Refresh，再从最新快照取得 session、generation、setup revision 和 presentation revision。需要自动化打开面板时使用 ability_test.open；不要用 F9 或旧快照游标代替进入和校验。

配置与进入 ​

  • 使用作者制作的普通场景及已有玩家/队伍配置。GameDataSkillTestArena 配置场景、兜底单位、出生位置/朝向、优先复用开关与可选项目适配 key；由当前 GameMode 引用默认/可选配置。不要增加测试技能或候选技能配置。
  • 在项目已有主控的阶段进入可复用同一真实对象。无主控或复用失败允许创建指定单位，并检查原因；不以同模型克隆冒充复用。
  • 使用正常编译、服务端上传、调试 Host 开局与客户端连接链路。日常迭代先推进代码，在关键切片完成后集中双端验证；遵循用户对 Jenkins/本地构建的要求。
  • 未配置试验场时，场景回退到 SceneList 第一个有效场景、出生点回退到场景中心，默认控件选项均为自动创建。GameSystemUI 会在客户端调试会话中按这两个选项创建并清理自己创建的默认控件；显式项目适配器也可通过 SkillTestArenaContext.Options 管理自定义控件。
  • 项目的任务、波次、掉落、存档与胜负需要显式隔离 lease/业务入口接入。SuppressProgressWrites 只有项目真正接入的写入路径才生效，不宣称所有业务已自动隔离。
  • 服务端进入接口使用 AbilityTestEntryStatus 返回可判断的失败枚举；记录该状态和诊断后再决定是否继续读取会话快照。

操作真实会话 ​

  1. 读取 ability_test.snapshot。确认服务端状态、实际单位/技能实例、session、generation、布置版本和当前选中完整 target/表现 revision。
  2. 从运行时已注册的完整单位/技能目录搜索，按稳定身份选择。目录包括项目、依赖与动态注册定义；未执行的注册不靠代码静态扫描补造。不要筛掉被动、非人形或项目类型。
  3. 清空/添加/换角只改变当前实例布置，结果以真实容器为准。自动重新授予要显示实际列表；换角恢复原借用对象，不销毁它，新角色保持自己的默认技能。
  4. 根据 Fields 的生效时机编辑受支持字段。多字段一次确认形成一个事务，保留 Undo/Redo；不能任意反射改共享 GameData。未知项目字段用明确的扩展适配契约。
  5. 发命令后用返回 request ID 读取 ability_test.response。发送接受、响应成功、资源准备确认与实际施法成功分别检查；pending 不是成功。版本过期先刷新，不能为旧请求套用最新 target。
  6. 等待客户端确认完整目标与 revision，再施放。面板的单次施放默认使用自身目标；需要单位或地点目标时由 MCP 命令提供。
  7. 在面板的“试验会话选项”中按需开启自动连续施法、忽略冷却或不造成伤害；这些设置只保留到当前会话结束。

表现、Sequence 与资源 ​

  • Original 使用原 Formula 和归一化；Fixed 输入最终前摇/施法/持续施法/后摇时长，仅作为测试覆盖，不再次归一化。保留原 Formula，除非用户明确要求转换语义。
  • 成功修改停止后续循环；正在施法的旧版本继续完成自己的快照，新版本需客户端准备确认。
  • 当前 AnimationDefinitions 承载动画定义的实例级投影；Sequence 包含片段、Actor、事件与 TriggerEvents，每条使用稳定 EntryId。列表命令依据实际 API/schema，不臆造路径。
  • 片段是连续顺序播放。源切片、Scale、实际 PlaybackDuration、混合时长分清楚；Actor/Event 使用 Sequence 绝对偏移，重排片段不自动移动它们。当前不把任意空隙、重叠片段或 seek 当成已有能力。
  • 使用真实事件目录中的键，例如 WaitForPlayerInput、ApplyPlayerState；不要编造 ApplyDamage。事件打点不自动实现服务端伤害或玩家业务。暂停事件必须有恢复/取消路径。
  • 新动画引用先准备当前模型与动画，检查 Ready/Queued/Running/Failed/Unsupported。烘焙在后台时继续读取状态；不伪造 Ready、不通过重命名引用绕过资源校验。

草稿回写 ​

草稿运行时路径为 user_files/skill_test/<name>.json，项目实际路径为 ui/AppBundle/user_files/skill_test/<name>.json。名称为 1–64 个 ASCII 字母/数字/下划线/连字符。

先区分采纳差异与复现布置，再从 canonical definition identity 定位真实源条目。运行时统一 GameData；只有回写时关注具体源文件/条目。不要修改 DataGenerated、共享缓存、下载的依赖产物，或把本次清空/添加列表自动写成单位默认技能。

保留源 Formula、Link 与列表身份，记录实际采纳的资源，补资源统计和模型动画烘焙。退出并清理全部临时覆盖，停止旧局，再通过项目正常双端编译、上传与开局重开，从源定义确认结果。旧局仍带覆盖不算回写验证。

需要操作示例、恢复对照或回写检查时读 references/reproduction.md。完整用户指南见 SkillTestArena.md；模板例子见 code_sample/src/SkillTestArenaSample/README.md。