306 lines
11 KiB
Markdown
306 lines
11 KiB
Markdown
# 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 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。
|