first commit

This commit is contained in:
2026-09-19 17:24:02 +08:00
commit afb343aa49
109 changed files with 13011 additions and 0 deletions
+305
View File
@@ -0,0 +1,305 @@
# 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 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。