# Godot 战斗竖切实施计划 > 日期:2026-09-19 > 状态:实施中 > 前置文档:[《Godot 联机接入与 UI 草案》](./Godot联机接入与UI草案.md)、[《Godot 地图与素材制作建议》](./Godot地图与素材制作建议.md) ## 1. 目的 本阶段的目标是把已经完成的 Godot 联网脚手架推进为第一条可实际游玩的战斗竖切:玩家能够连接现有 Solo WebAPI、开始对局、选择角色、在二等角战场中看到全部单位,并通过点击单位或逻辑格完成移动与普通攻击。 本阶段不重写 FunGame.Core 规则,也不重构 Server-v3。Godot 继续只负责显示权威状态和提交玩家意图,行动是否合法及其结果均由服务器决定。 ## 2. 当前基线 Godot 客户端当前已具备: - Godot 4.7 .NET / C# 工程与 `src/` 目录结构; - `GameSession`、`BattleStore`、`AssetCatalog`、`UiRouter` 和 `GameSettings` 五个 Autoload; - WebSocket 与 Mock 传输层; - 默认连接地址 `ws://localhost:11030/ws/solo`; - `system.ping` / `system.pong` 心跳; - `gaming.start`、`gaming.state`、`gaming.request`、`gaming.action` 等真实协议消息; - 角色选择、基础行动、技能、物品、目标和逻辑格决策的初步控件; - 2D 二等角投影、灰盒地图、范围网格、相机和贴边 HUD; - 自动连接、开局、选人和接收首个权威快照的冒烟测试。 当前端到端验证结果: ```text SOLO_SMOKE_OK game= round=0 characters=2 units=2 SOLO_VERTICAL_OK game= moves=1 attackTargetSubmitted=true rejectionRecovered=true units=2 ``` ### 执行进度 - [x] 阶段 A:`UnitView`、按 GUID 实例协调、格子定位、阵营/行动者/HP/淘汰/AI 托管显示; - [x] 阶段 B 基础:合法格集合高亮、单位直接点击选择目标、提交前确认; - [x] 阶段 B 完整:移动与普攻的真实端到端竖切回归、服务器拒绝后的决策恢复; - [ ] 阶段 C:完整决策类型与行动配额; - [ ] 阶段 D:断线恢复; - [ ] 阶段 E:动画、日志、结算与输入完善。 阶段 A 已通过真实 Solo WebAPI 冒烟测试:权威快照含 2 名角色时,`UnitsLayer` 生成且仅生成 2 个 `UnitView`。 阶段 B 已通过真实 Solo WebAPI 竖切测试:客户端可通过合法格完成移动、通过点击单位提交普通攻击;提交期间会锁定重复输入,取消会发送协议取消意图,非法格被服务器拒绝后可以恢复并继续选择。 现有 WebAPI 的 SoloMap 为 `12 × 12`,而美术竖切建议值为 `16 × 12`。客户端不得写死地图尺寸,必须以服务器 `MapDto.length` 与 `MapDto.width` 为准动态构建显示层。 ## 3. 竖切完成后的玩家流程 ```text 启动 WebAPI ↓ Godot 连接 /ws/solo ↓ 开始新局并选择角色 ↓ 收到完整权威快照 ↓ 生成地图与全部单位 ↓ 收到 ActionType 决策 ├─ 移动 → 显示合法格 → 选择 → 确认 └─ 普攻 → 显示合法目标 → 选择 → 确认 ↓ 等待服务器计算 ↓ 根据新快照更新位置、HP、队列和决策点 ``` 客户端不得在提交后自行移动角色或预扣 HP。提交期间只显示选择结果与“等待服务器”状态;收到新快照后才更新权威画面。 ## 4. 分层职责 ```text BattleScreen / UnitView / GridOverlay2D ↓ 显示 ViewModel、提交 Intent BattleStore ↓ 解析快照、保存待处理决策 GameSession ↓ 信封、心跳、连接与重连 WebSocketTransport ↓ WebAPI /ws/solo(权威计算) ``` ### GameSession - 维护 WebSocket 生命周期和连接状态; - 为发出消息生成递增序号; - 定时发送心跳; - 将后台接收的数据排队后交回 Godot 主线程; - 后续负责重连退避和 `gaming.resume`。 ### BattleStore - 解析 Solo 协议信封; - 保存最近一次完整权威快照; - 保存唯一待处理的 `gaming.request`; - 丢弃不属于当前 `gameId` 的旧局消息; - 向场景发出快照、决策和错误信号; - 不保存服务器规则对象,不计算伤害或合法范围。 ### BattleScreen - 将快照映射到地图、单位和 HUD; - 根据决策种类切换输入状态; - 把鼠标、触屏或手柄输入统一转换为决策负载; - 提交后锁定相关输入,等待服务器返回。 ## 5. 权威数据到场景的映射 | 服务器字段 | Godot 消费位置 | 用途 | |---|---|---| | `state.gameId` | `BattleStore` | 防止不同对局消息串线 | | `state.map.grids` | 地图显示与 `GridOverlay2D` | 格子 ID、坐标及角色占位 | | `state.characters[].guid` | `UnitsLayer` | `UnitView` 的稳定实例键 | | `state.characters[].gridId` | `UnitView` | 查找逻辑坐标并计算屏幕位置 | | `state.characters[].hp/mp/ep` | `UnitView` 与角色 HUD | 权威资源显示 | | `state.currentActorGuid` | `UnitView`、队列 | 当前行动者高亮 | | `state.queue` | `TopTurnQueue` | 行动顺序显示 | | `state.playerDP` | 行动坞、角色 HUD | 决策点和行动配额 | | `request.kind` | 输入状态机 | 决定当前允许的交互方式 | | `request.payload.gridIds` | `GridOverlay2D` | 只显示和接受合法格子 | | `request.payload.targets` | `UnitView` | 只允许选择合法单位 | 服务器目前没有正式的 `stateRevision` 字段。第一阶段按 WebSocket 顺序处理完整快照;正式重连和增量同步前,应在协议中补充单调递增的状态版本。 ## 6. 场景新增与调整 ### 6.1 UnitView 新增可复用单位场景: ```text UnitView (Node2D) ├─ Shadow (Sprite2D / Polygon2D) ├─ SelectionRing (Node2D) ├─ Body (AnimatedSprite2D,第一版可用临时剪影) ├─ HitArea (Area2D) │ └─ CollisionShape2D ├─ HpBar (Control) ├─ StatusIcons (HBoxContainer) └─ NameLabel (Label) ``` 职责: - 以角色 GUID 绑定一个角色快照; - 脚底中心与逻辑格中心对齐; - 显示己方、敌方、当前行动者、可选目标、死亡和 AI 托管状态; - 只发出“被点击”信号,不直接提交网络消息; - 正式角色动画未完成前使用统一临时剪影,不以头像代替战场人物。 ### 6.2 UnitsLayer `BattleScreen` 保存 `Dictionary`: 1. 快照中出现新 GUID 时实例化; 2. 已存在 GUID 时更新位置与状态; 3. GUID 从快照消失时移除; 4. `isEliminated` 为真时播放或显示失败状态; 5. 更新完成后根据脚底 `screenY` 进行 Y 排序。 ### 6.3 GridOverlay2D 从“整张地图统一着色”改为接受明确集合: - `SetReachableCells(IEnumerable)`; - `SetAttackCells(IEnumerable)`; - `SetAffectedCells(IEnumerable)`; - `SetSelectedCell(long?)`; - `ClearInteraction()`。 格子 ID 与坐标的转换由当前地图快照提供,不假设 ID 等于数组索引。 ## 7. 实施阶段 ### 阶段 A:快照生成战场单位 任务: - 建立 `UnitView.tscn` 与 C# 控制脚本; - 从 `map.grids[].characters` 或角色 `gridId` 建立占位关系; - 在 `UnitsLayer` 中按 GUID 对单位实例进行增删改; - 将当前行动者、己方和敌方用不同轮廓表示; - HUD 和单位头顶血条同步显示服务器 HP。 验收: - 首个快照到达后,所有角色都出现在正确格子; - 连续接收快照不会重复创建单位; - 角色位置、HP 或淘汰状态变化后画面正确更新; - 地图尺寸变化时不需要修改场景代码。 ### 阶段 B:地图与单位直接交互 任务: - `TargetGrid` 仅高亮 `payload.gridIds`; - 点击非法格不产生可提交选择; - `Targets` 仅让 `payload.targets` 中的 `UnitView` 可选; - 选择后显示预览,必须再次确认才发送; - `WaitingServer` 期间锁定重复点击。 验收: - 移动决策可以通过地图完成; - 普通攻击可以通过点击单位完成; - 重复点击确认不会重复执行行动; - 服务器拒绝时能够恢复当前决策或显示错误。 ### 阶段 C:补齐决策类型 任务: - 根据 `playerDP.quotas` 控制行动按钮; - 区分 `CastSkill`、`PreCastSkill` 和 `CastSuperSkill`; - 实现技能与物品详情、冷却、消耗和不可用原因; - 支持 `TargetGrids`、多目标、`selectAll`、`Inquiry` 与 `Continue`; - 显示服务器提供的决策倒计时。 验收: - 所有 `DecisionKind` 都有可完成或可取消的 UI; - 不可用技能仍能查看说明,但无法提交; - 决策超时后 UI 能反映 AI 托管状态。 ### 阶段 D:断线恢复 任务: - 对局进行中断线后按退避间隔重连; - 重连成功后发送 `gaming.resume`; - 清除旧的本地选择与动画队列; - 根据补发快照重建地图、单位、队列和待处理决策; - 显示重连与 AI 托管遮罩。 验收: - 强制断开连接后服务器继续运行; - 客户端恢复连接后不会收到其他旧局数据; - 恢复后的单位位置、资源和决策与服务器一致。 ### 阶段 E:表现与信息完整性 任务: - 比较前后快照,生成移动、受击、治疗和淘汰动画任务; - 动画积压或重连时允许跳过; - 加入战斗日志抽屉、结果页和服务器错误提示; - 完成键鼠与基础手柄焦点导航。 验收: - 动画不会阻塞快照接收; - 跳过动画后画面立即对齐最新快照; - 16:9 窗口缩放时 HUD 不遮挡关键操作区。 ## 8. 测试策略 ### 自动检查 - C# 工程构建必须保持 0 错误; - 保留 `--solo-smoke-test`,验证连接、开局、选人和首个快照; - 为协议反序列化保存最小 JSON 样本,验证 WebAPI 字段变更不会静默破坏客户端; - 为 `GridProjector` 增加格子到屏幕、屏幕到格子的往返测试。 ### 手工竖切测试 1. 启动 WebAPI; 2. 启动 Godot 并连接默认地址; 3. 开始新局并选择角色; 4. 确认地图单位数量与快照一致; 5. 完成一次移动; 6. 完成一次普通攻击; 7. 观察 HP、队列和 DP 更新; 8. 中途断线并恢复; 9. 结束对局并查看结果。 ## 9. 竖切完成定义 同时满足以下条件,才视为第一条战斗竖切完成: - 玩家无需使用调试控制台即可完成选人、移动、普攻和结束行动; - 所有单位来自服务器快照,并位于正确逻辑格; - 客户端没有本地计算伤害、射程或行动合法性; - 合法格和合法目标严格来自当前 `gaming.request`; - 断线重连后可以从完整快照恢复; - 鼠标可以完成全部核心流程; - 自动冒烟测试和手工竖切测试均通过。 ## 10. 暂不包含 - Server-v3 登录、房间和匹配; - 房主模式与 NAT 穿透; - 正式地图图集和全部角色动画; - 战争迷雾; - 多层高度、视线与完整掩体规则; - 回放编辑器、观战与增量状态同步; - 移动端发布和 Web 导出。 ## 11. 下一项开发任务 立即进入阶段 A:创建 `UnitView`,并在 `BattleScreen` 中实现按 GUID 对权威快照进行实例协调。第一小步只使用临时剪影和 HP 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。