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

11 KiB
Raw Blame History

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>:

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