11 KiB
Godot 战斗竖切实施计划
日期:2026-09-19
状态:实施中
前置文档:《Godot 联机接入与 UI 草案》、《Godot 地图与素材制作建议》
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;
- 自动连接、开局、选人和接收首个权威快照的冒烟测试。
当前端到端验证结果:
SOLO_SMOKE_OK game=<gameId> round=0 characters=2 units=2
SOLO_VERTICAL_OK game=<gameId> moves=1 attackTargetSubmitted=true rejectionRecovered=true units=2
执行进度
- 阶段 A:
UnitView、按 GUID 实例协调、格子定位、阵营/行动者/HP/淘汰/AI 托管显示; - 阶段 B 基础:合法格集合高亮、单位直接点击选择目标、提交前确认;
- 阶段 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. 竖切完成后的玩家流程
启动 WebAPI
↓
Godot 连接 /ws/solo
↓
开始新局并选择角色
↓
收到完整权威快照
↓
生成地图与全部单位
↓
收到 ActionType 决策
├─ 移动 → 显示合法格 → 选择 → 确认
└─ 普攻 → 显示合法目标 → 选择 → 确认
↓
等待服务器计算
↓
根据新快照更新位置、HP、队列和决策点
客户端不得在提交后自行移动角色或预扣 HP。提交期间只显示选择结果与“等待服务器”状态;收到新快照后才更新权威画面。
4. 分层职责
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
新增可复用单位场景:
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>:
- 快照中出现新 GUID 时实例化;
- 已存在 GUID 时更新位置与状态;
- GUID 从快照消失时移除;
isEliminated为真时播放或显示失败状态;- 更新完成后根据脚底
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增加格子到屏幕、屏幕到格子的往返测试。
手工竖切测试
- 启动 WebAPI;
- 启动 Godot 并连接默认地址;
- 开始新局并选择角色;
- 确认地图单位数量与快照一致;
- 完成一次移动;
- 完成一次普通攻击;
- 观察 HP、队列和 DP 更新;
- 中途断线并恢复;
- 结束对局并查看结果。
9. 竖切完成定义
同时满足以下条件,才视为第一条战斗竖切完成:
- 玩家无需使用调试控制台即可完成选人、移动、普攻和结束行动;
- 所有单位来自服务器快照,并位于正确逻辑格;
- 客户端没有本地计算伤害、射程或行动合法性;
- 合法格和合法目标严格来自当前
gaming.request; - 断线重连后可以从完整快照恢复;
- 鼠标可以完成全部核心流程;
- 自动冒烟测试和手工竖切测试均通过。
10. 暂不包含
- Server-v3 登录、房间和匹配;
- 房主模式与 NAT 穿透;
- 正式地图图集和全部角色动画;
- 战争迷雾;
- 多层高度、视线与完整掩体规则;
- 回放编辑器、观战与增量状态同步;
- 移动端发布和 Web 导出。
11. 下一项开发任务
立即进入阶段 A:创建 UnitView,并在 BattleScreen 中实现按 GUID 对权威快照进行实例协调。第一小步只使用临时剪影和 HP 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。