Files
Oshima-Game/docs/Godot战斗竖切实施计划.md
T
2026-09-19 17:24:02 +08:00

306 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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=<gameId> round=0 characters=2 units=2
SOLO_VERTICAL_OK game=<gameId> 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<string, UnitView>`:
1. 快照中出现新 GUID 时实例化;
2. 已存在 GUID 时更新位置与状态;
3. GUID 从快照消失时移除;
4. `isEliminated` 为真时播放或显示失败状态;
5. 更新完成后根据脚底 `screenY` 进行 Y 排序。
### 6.3 GridOverlay2D
从“整张地图统一着色”改为接受明确集合:
- `SetReachableCells(IEnumerable<long>)`;
- `SetAttackCells(IEnumerable<long>)`;
- `SetAffectedCells(IEnumerable<long>)`;
- `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 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。