Files
Oshima-Game/docs/Godot战斗竖切实施计划.md
T

32 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:12030/ws/solo;
  • system.ping / system.pong 心跳;
  • gaming.start、gaming.state、gaming.request、gaming.action 等真实协议消息;
  • 角色选择、基础行动、技能、物品、目标和逻辑格决策的初步控件;
  • 2D 二等角投影、灰盒地图、范围网格、相机和贴边 HUD;
  • 自动连接、开局、选人和接收首个权威快照的冒烟测试。

当前端到端验证结果:

SOLO_SMOKE_OK dialogFits=true clickableList=true clickSubmits=true game=<gameId> round=0 characters=10 units=10
SOLO_VERTICAL_OK game=<gameId> moves=32 attackTargetSubmitted=true rejectionRecovered=true attackAttempts=1 attackCancelled=0 attackReachableRounds=1 attackGateVerified=True preciseAttackSignal=true continueObserved=true units=2
SOLO_RECONNECT_OK game=<gameId> reconnected=true attempts=1 serverRunningDuringDrop=true resumeSent=true staleDecisionCleared=true snapshotsAfterResume=1 stateMatchesServer=true units=2
PHASE_C_DECISIONS_OK quotas=true details=true attackReachability=true inquiry=true continue=true cancellation=true shapePreview=true
PHASE_E_OK diff=true animator=true cancellation=true ground=true hudLayout=true

执行进度

  • 阶段 A:UnitView、按 GUID 实例协调、格子定位、阵营/行动者/HP/淘汰/AI 托管显示;
  • 阶段 B 基础:合法格集合高亮、单位直接点击选择目标、提交前确认;
  • 阶段 B 完整:移动与普攻的真实端到端竖切回归、服务器拒绝后的决策恢复;
  • 阶段 C:完整决策类型与行动配额;
  • 阶段 D:断线恢复;
  • 阶段 E:动画、日志、结算与输入完善。

阶段 A 已通过真实 Solo WebAPI 冒烟测试:权威快照含 2 名角色时,UnitsLayer 生成且仅生成 2 个 UnitView。

阶段 B 已通过真实 Solo WebAPI 竖切测试:客户端可通过合法格完成移动、通过点击单位提交普通攻击;提交期间会锁定重复输入,取消会发送协议取消意图,非法格被服务器拒绝后可以恢复并继续选择。

阶段 C 已通过真实 Solo WebAPI 竖切测试(--solo-vertical-smoke-test,连跑 5 次全绿)与静态协议自检(--phase-c-smoke-test):配额门控、技能/物品详情、Inquiry 三种输入、Continue 与范围形状预览均按服务端字段解析;真实对局中移动、拒绝恢复、普通攻击与 Continue 串通在同一条链路上(continueObserved=true)。

阶段 C 落地时确立了「权威服务器原则」的三条客户端铁律:

  1. 客户端不推算射程、合法性或可选目标 —— 合法性只来自 TargetGrid.gridIds / Targets.targets;
  2. ActionType.enemyOptions / enemys 是引擎在当前位置按「攻击可达 ∪ 施法可达」过滤后的敌人(见 GamingQueue 中 canAttackGrids ∪ canCastGrids 的过滤),列表为空即普通攻击必被取消,因此按钮直接禁用;
  3. 「提交被拒绝」没有回执 —— 服务器不会告诉你「你这个行动不合法」,只能靠紧邻的那条决策类型判断:回到 ActionType 即取消,否则进入自己的下一步。DecisionUiRules.DetectCancelledAction 负责这条判定,BattleScreen 据此提示玩家。 注意区分另一种情况:服务器主动放弃一条挂起决策(对局结束 / 玩家被接管 / 断线)现在会发 gaming.resolved { requestId, kind, reason },客户端据此立刻收尾,不必再靠超时去猜。

阶段 D 已通过真实断线恢复测试(--solo-reconnect-smoke-test):非计划中断(ClientWebSocket.Abort(),不发送关闭握手)后客户端按退避重连(1s→2s→4s→8s→15s),重连成功自动补发 gaming.resume,服务器把新连接接管回原对局并补发完整快照与待处理决策。测试为了让「客户端画面 == 服务器状态」成为可精确比对的断言,会先用 gaming.pause 把服务器冻结,再通过 REST /api/solo/state 逐项比对单位集合、格子、血量、淘汰标记与回合数。

阶段 E 已通过静态自检(--phase-e-smoke-test)与真实对局回归:快照差分产出移动/受击/治疗/淘汰/复活任务,表现队列可合并、可跳过、有上限且永不阻塞快照接收;战斗日志抽屉、结算页、错误提示条与焦点导航均已接入。

注意 BattleScreen 已拆成两个 partial 文件:BattleScreen.cs(世界 / 单位 / 决策)与 BattleScreen.Overlays.cs(覆盖层 / 日志 / 结算 / 表现控制)。新增 UI 相关代码请加到后者。

现有 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 只允许选择合法单位
ActionType.enemyOptions / enemys 行动坞 当前位置攻击可达 ∪ 施法可达的敌人;为空则禁用普通攻击
ActionType.dp.quotas 行动坞按钮 每种行动类型的配额 / 剩余 / 决策点消耗
request.timeoutMs TimeoutLabel 服务器决策倒计时
state.aiEscalated 角色 HUD、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~E 均已闭环。下一步不再由本计划驱动,候选方向:

  1. 接入真实素材:把 UnitView 的占位剪影换成正式角色动画(阶段 E 的补间接口已经就位,只需 Body 的 AnimatedSprite2D 有帧);
  2. 手工竖切回归:按 §8 的九步流程走一遍,重点看动画积压与 16:9 缩放下 HUD 的表现;
  3. 回到 Server-v3:登录、房间与匹配(本计划明确不包含)。

开工前需要先和服务端对齐两点:

  • gaming.resume 当前的语义与「旧局不自动挂载」策略(Program.cs 的 /ws/solo 注释)如何共存;
  • 服务器目前没有 stateRevision,重连后只能靠完整快照对齐,是否需要先补一个单调递增的状态版本。

12. 实施过程中记录的问题

按发现顺序记录,标注归属(服务端 / 客户端 / 测试环境)。已修复的直接写结论,未修复的保留为待办。

已修复

# 现象 根因 处理
1 requireContinue=true 但收不到 Continue 客户端用曼哈顿距离猜「能否普攻」,敌人只在施法射程内时仍提交,被服务器作废后回到 ActionType,连续 4 次同类决策触发防打转护栏 → 玩家被 AI 托管 → OnTurnEnd 不再下发 Continue 阶段 C:只按服务器列出的敌列表 + dp.quotas 决策,被作废的行动同回合不再重复提交
2 玩家点了普攻却毫无反馈 服务器对不可行提交没有拒绝回执 阶段 C:DecisionUiRules.DetectCancelledAction 按「紧邻的决策类型」判定作废并提示
3 重连后界面可能卡在一条已经作废的决策上 服务端 MarkDisconnected / EscalatePlayerToAI 只清 _pending,不清 _pendingRequests,AttachSink 会把历史请求一并补发(SoloGameSession.cs:216/261 对比 197-209) 两层都修了:客户端记录已答复的 requestId 忽略重复项(BattleStore);服务端后续实现 DropPendingDecisions 时在兜底解决的三处一并清掉 _pendingRequests(见 §13-4 第 9 条),并改发 gaming.resolved 通知客户端 —— 重连后不再补发死决策
4 重连后决策没有倒计时 AttachSink 补发请求时只带 requestId/kind/payload,丢了 timeoutMs 客户端如实显示「重连后无倒计时」;建议服务端补上该字段

待办(未修复)

  • 表现与权威不一致(客户端):GreyboxMap2D._Draw 硬编码了 4 个掩体((5,4) (6,4) (10,7) (11,7)),与服务端 MapDto 无关。当前 SoloMap 是 12 × 12,(10,7) / (11,7) 会被画成服务器上并不存在的掩体。要么让服务端下发格子属性,要么先删掉硬编码。详见 §13-3。
  • 同一种子不可复现(宿主):根因已定位在 FunGame.Testing-v3/WebAPI/Services/SoloGameSession.cs 的 6 处 Random.Shared,详见 §13-1。
  • ActionType 阶段缺普攻可达的精确信号:敌人仅落在施法射程内时客户端无法预判,每回合会白提交一次普攻(现由客户端提示兜底)。修法与等价性证明见 §13-2。

测试环境(不涉及产品,但会浪费排查时间)

  • 本机 Bash 工具的 PATH 是坏的(dirname / ls / head 全部 not found),每条命令前要 export PATH="/usr/bin:/bin:/mingw64/bin:$PATH"。
  • PowerShell 工具不回显 stdout,只能看 exit code;要看输出必须走 Bash。
  • 把多个 Godot 无头测试串在同一个 shell 循环里会超出工具超时被 SIGTERM,而管道缓冲会让全部输出丢失(看起来像「什么都没跑」)。逐个跑,或用 run_in_background。
  • GD.PushWarning 会打印完整 C# 调用栈,测试输出噪音很大;过滤时用 grep -E "^(SOLO_|PHASE_)"。
  • Godot 的 CreateTween 要求节点在场景树内;静态自检里故意不入树的 BattleAnimator 必须在用例结束时 Free(),否则退出时报 ObjectDB instance was leaked。

13. 三条遗留问题的修复优先级排序

排序依据:先修「让度量本身不可信」的问题,再修「体验/协议不精确」的问题,最后修「纯表现」的问题。

状态:三条全部已实现并通过回归(验证结果见本节末尾)。修复过程中另外挖出 4 个问题,其中 2 个是真实产品缺陷,见 §13-4。

顺序 问题 优先级 难度 归属仓库 一句话理由
1 同一种子不可复现 P0 低 FunGame.Testing-v3 它让「回归通过/失败」无法区分改动效果与抽签结果
2 ActionType 缺普攻可达信号 P1 低-中 Testing-v3 + osm-game 消除每回合一次白提交与客户端猜算,且能顺带让 #1 的度量更干净
3 灰盒地图与权威不一致 P2 极低 osm-game 纯表现、无玩法影响,4 个子问题里 3 个当前触发不了

13-1(P0)同一种子不可复现 —— 根因已定位

不是「客户端决策时序」也不是「队列里某个未受种子控制的输入」。Seed 确实传进了 GamingQueue(GamingQueue.cs:421-422 用 Seed 构造 Random),问题在于开局装配整段发生在队列之外,用的是进程级 Random.Shared:

行号 代码 后果
SoloGameSession.cs:313 .OrderBy(_ => Random.Shared.Next()) + Take(CharacterCount) 每局抽到的角色及其顺序都不同 —— 测试又取 Characters.FirstOrDefault(),等于每局随机换人
SoloGameSession.cs:665 FunGameService.Skills.OrderBy(_ => Random.Shared.Next()).Take(3) 每局随机 3 个技能
SoloGameSession.cs:672 CommonPassiveSkills...Take(3) 每局随机 3 个被动
SoloGameSession.cs:679 CommonSuperSkills...Take(3) 每局随机 3 个爆发技
SoloGameSession.cs:394 free[Random.Shared.Next(free.Count)] 出生格随机
SoloGameSession.cs:651 BuildTeams 里的洗牌 团队模式分队随机(本测试 teamMode=false,暂不触发)

补充证据:Character.Random => GamingQueue?.Random ?? Random.Shared(Character.cs:30),而 PrepareCharacters(:315)跑在 character.NormalAttack.GamingQueue = queue(:389)之前 → 这段里任何走实体的随机都退化成 Random.Shared。

修法:RunGame 开头建一个 Random rng = new(options.Seed ?? Random.Shared.Next());,把上述 6 处换成 rng,并给 PrepareCharacters 加一个 Random 参数;同时把 character.NormalAttack.GamingQueue = queue 提到装配之前,让实体自身的随机回退也吃到种子。

验收:同 Seed 连跑 3 次,SOLO_VERTICAL_OK 里的 moves / attackAttempts 必须完全一致。

实施结果:SoloGameSession.RunGame 开头建 Random rng = new(options.Seed ?? Random.Shared.Next()),6 处 Random.Shared 全部换成 rng(PrepareCharacters / BuildTeams 增加 Random 参数)。同种子连跑 3 次结果:moves=15 attackAttempts=0 attackReachableRounds=0 —— 逐字一致(修复前同 seed 会出现 moves 1 与 4、attackAttempts 1 与 13)。

13-2(P1)ActionType 缺普攻可达信号

现状口径:GamingQueue.cs:1261 交给 OnDecideAction 的 enemys 是「攻击可达 ∪ 施法可达」,而 SoloGameSession 把它原样当 enemys / enemyOptions 下发(:817-819)。所以客户端只能判断「有没有敌人」,判断不了「打不打得着」。

等价性证明:引擎真正选普攻目标前会再用 ATR 收窄一次 —— GamingQueue.cs:1578-1585:

attackRange = _map.GetGridsByRange(realGrid, character.ATR, true);
enemys = [.. enemys.Where(attackRange.SelectMany(g => g.Characters).Contains)];

修法(不需要改 FunGame.Core):在 OnDecideAction 里用同一个公开接口复现这一步,作为新字段下发:

Grid? actorGrid = _map?.GetCharacterCurrentGrid(actor);
HashSet<Character> inAttackRange = actorGrid is null
    ? []
    : [.. _map!.GetGridsByRange(actorGrid, actor.ATR, true).SelectMany(g => g.Characters)];
// payload 新增:attackTargets = ctx.Enemys.Where(inAttackRange.Contains).Select(c => ToTargetOption(c, actor))

客户端 ActionTypePayload 加 AttackTargets,普攻按钮门控与回归测试都改用它 → 白提交消失(attackAttempts 应恒为 1)。

成本/风险:GetGridsByRange 是 O(range²),但 SoloMap 已覆写把 range 压到 (12-1)+(12-1)=22(SoloGameSession.cs:1506-1510),每回合一次,可忽略。

实施结果:服务端在 OnDecideAction 里下发 attackTargets(TargetOption 列表)与 canNormalAttack;客户端 ActionTypePayload 增加两个可空字段,DecisionUiRules.IsNormalAttackReachable 统一口径(严格口径优先,旧服务端退回宽口径),BattleScreen 与回归测试都改用它。真实对局中抓到的字段组合证实了修复的必要性:

payload kind=ActionType actorGrid=69 atr=3 enemys=1 enemyOptions=1 attackTargets=0 canNormalAttack=False

enemys=1 而 attackTargets=0 —— 旧客户端看到前者就会提交普通攻击并被服务器作废,正是白提交的来源,现在被精确排除。

门控的真实验证:回归测试原先「打一次就不再移动」,导致敌人永远进不了 ATR、门控验证不到。改成「先保证走一步 → 能打就打 → 打不着继续靠近」后,真实局面里拿到了 attackReachableRounds=1 attackAttempts=1 attackCancelled=0 attackGateVerified=True: 服务器说可达 → 客户端据此提交普通攻击 → 进入选目标阶段且零作废,门控闭环。连跑 3 次结果逐字一致。

13-3(P2)灰盒地图与权威不一致

拆成 4 个独立子问题,只有 1a 今天可见:

子问题 现状 今天能否触发
1a 硬编码 4 个掩体 协议里根本没有掩体概念(GridDto 只有 Id/X/Y/Z/Color/Characters,计划 §10 明确不含掩体规则),纯装饰 ✅ 能(画出不存在的掩体,误导玩家)
1b 从不消费 grid.color 全代码库没有任何地方给 Grid.Color 赋值 → 全图都是默认 Gray ❌ 消费了也不改画面,只是协议诚实性
1c 地面绘制忽略 grid.Z 单位位置已经用了 Z(BattleScreen.cs:999/1034),但地面始终按 Z=0 画 ❌ SoloMap.Height = 1
1d 地面按 0..Length × 0..Width 稠密矩形绘制,不读服务器坐标 与 GridOverlay2D 用服务器坐标的做法不一致 ❌ 当前 GameMap.Load 就是稠密矩形且从 (0,0) 起

建议:把 GreyboxMap2D 的地面改成「按 map.grids 的真实坐标 + color 逐格绘制」(与 GridOverlay2D 同源),一次消掉 1a/1b/1d;1c 属于多层地形,留给后续阶段,先加注释说明。最小改动版:只删掉 DrawCover(...) 四行。

实施结果:采用了「按 map.grids 逐格绘制」的方案,一次消掉 1a/1b/1d:

  • GreyboxMap2D 改为 SetMap(SoloMapDto?),只画服务器给的格子,删掉全部硬编码掩体;
  • 格心用 grid.Z 抬升(顺手消掉 1c 的隐患,与单位位置的算法一致);
  • 服务器显式给过颜色时叠 45% 着色,默认 Gray(= Grid.Color 初始值,全图皆然)时保留灰盒棋盘配色;
  • GridOverlay2D 的坐标表升级为 Vector3I,高亮与地面、单位共用同一个高度;
  • PhaseESmokeTest 新增 ground=true 断言:稀疏地图(2 个格)只能画出 2 个格,设地图尺寸不会凭空造格。

13-4 修这三条时新发现的问题

按发现顺序,已修:

# 问题 归属 影响 处理
5 回归测试把毫秒传给了以「秒」为单位的等待函数:DecisionTimeoutMs = 45_000 osm-game(测试) 每次等待实际是 12.5 小时。服务器一旦停止下发决策(对局结束/玩家被托管),测试就永远挂着 —— 这才是「卡死几分钟」的真凶,与客户端无关 常量改名为 DecisionTimeoutSeconds = 20.0;并区分「服务端主动静默」与故障:!_store.IsStarted 或等不到下一条决策时优雅收尾
6 日志抽屉逐行 AppendText 到开了 fit_content 的 RichTextLabel osm-game(真实缺陷) 每次追加都会重排整段文本,长局(几千行)退化成 O(n²),足以把主循环卡住到「连 SceneTreeTimer 都不再触发」 改为「关闭时只打脏标记、打开时一次性 Text 赋值」,节流 250ms,只渲染最后 500 行
7 WebSocketTransport.SendAsync 没有超时 osm-game(真实缺陷) 半死连接(对端不再读取)会让 SendAsync 永久不返回,把界面/测试挂死 发送 10s 超时、关闭握手 5s 超时;超时即 Abort() 交给自动重连
8 冒烟测试缺少故障可见性 osm-game(测试基建) godot 的 GD.Print 走 C stdio,重定向到文件/管道时是块缓冲;进程被 SIGTERM 时输出整段丢失,只剩引擎启动那几行,表现为「什么都没跑」 新增 SoloTrace(托管 stderr,不带缓冲)+ 300s 看门狗 + 2s 主循环心跳;断言失败先写 stderr 再写 stdout
9 服务端放弃挂起决策时不通知客户端 两端(真实缺陷) 对局结束 / 玩家被托管 / 断线后,客户端只能靠超时判断「为什么轮到我却什么都没发生」;更糟的是被兜底解决的 requestId 会留在 _pendingRequests 里,重连时被当作「仍在等待」重新补发,玩家看到一条回执早已无效的死决策 实现两端早已声明、服务端却从未发送的 gaming.resolved:SoloGameSession.DropPendingDecisions(reason) 在托管 / 断线 / 收尾三处发出 { requestId, kind, reason } 并清掉本地记录(顺手从源头修掉 §12 记的那条);客户端 BattleStore 收到即清掉对应决策、写日志、弹提示,并暴露 DroppedDecisionCount 供测试判断「不必再等」;重连时客户端主动丢弃属于旧连接的挂起决策

| 10 | 选人弹窗「点不动」 | osm-game(实机体验缺陷,玩家实测发现) | 详情文本是整张角色说明书(几十行),而弹窗是没有上限的 CenterContainer + 只在 tscn 里给了一个最小尺寸:面板高度完全由内容决定,长文本把它顶到视口之外,确认/取消按钮随之落到屏幕外;同时候选用的是下拉框(一次只显示一项),10 个角色看起来「根本没有能点的地方」 | 三处一起改:① 面板改为按视口比例锚定(16%~84% × 8%~92%),不再由内容决定高度;② 详情放进 ScrollContainer(size_flags_vertical=3),长文本自己滚;③ 选项 > 3 个时改用 ItemList 可点击列表并置于详情上方,≤3 个才用下拉框。另外初始焦点给选择器而不是确认键(避免误按回车确定「10 选 1」的第一项);SoloConnectionSmokeTest 新增 dialogFits / clickableList 断言,用 10 个候选的真实对局把这条钉死。修复后实测:panel=(307,86) 1305×907、list=(307,132) 1305×394 items=10、confirm=(968,945) 140×48、viewport=1920×1080 |

| 11 | 选完角色点确认没反应(玩家实测第二报) | osm-game(实弹缺陷) | 确认处理里留着一句为下拉框写的守卫 if (_dialogValues.Count == 0 \|\| _decisionOptions.Selected < 0) return;。走列表路径时那个下拉框已被 Clear() 并隐藏,Selected 恒为 -1 → 点确认静默返回,什么都不发生。上一轮五条回归全绿也没抓到,因为测试都是直接调 BattleStore.SubmitDecisionAsync,完全绕过了 GUI | 守卫改为只看 _dialogValues.Count,选中项一律从当前生效的控件读(列表 → GetSelectedItems(),下拉框 → Selected)。同时补上真正的 GUI 回归:SOLO_SMOKE 现在会在列表里选第 2 个候选(故意不选第一个)再触发确认按钮的 pressed 信号,并断言服务器开局的角色就是所选的那个——把断言临时改回旧守卫可复现出「点击确认后没有继续:dialogVisible=True」 | | 12 | 候选 guid 与开局状态 guid 不是同一套 | 服务端(FunGame.Testing-v3,待办) | SelectCharacter 候选下发的 guid 与开局后 state.characters[].guid 同名不同 guid(同一角色两个 guid 空间)。服务端按对象/名字选中,对局本身正常;但任何「拿候选 guid 去状态里找角色」的客户端逻辑都会落空。SOLO_SMOKE 因此按名字断言(guidConsistent=false 会打进 trace 供追踪) | 未修。需要在服务端确认候选列表与队列内部角色实例是否被复制成不同对象(Character.Copy() 理论上保留 Guid,实测不成立),归一到同一个 guid 空间 |

踩坑记录(诊断顺序,可复用):心跳仍在跳 ⇒ 主循环健康、是 await 链的问题;心跳停 ⇒ 主循环卡死。这一次就是靠「心跳继续但无新决策」把范围从「客户端卡死」收窄到「等待函数超时单位写错」。

11 条已修 + 1 条服务端待办。 第 10/11 条都是玩家跑实机客户端发现的 —— 五条 headless 回归全绿也照样漏, 因为「能不能点」是版面问题、而「点了有没有用」是 GUI 逻辑问题 —— 两者都测不到逻辑断言里: 前者要量几何(面板是否在视口内、按钮是否可见、列表是否可点), 后者要真的走一遍界面(在列表里选一项 → 触发确认 → 校验服务端用的就是所选的那个)。 现在 --solo-smoke-test 这两层都覆盖了,且已验证它能把旧 bug 复现出来。 第 5~9 条是修前三条的副产品:其中 #6 / #7 / #9 是真实产品缺陷(会影响真人玩家,不只是测试)。回归的收尾方式也从「靠 20s 超时」变成「收到作废通知立刻收尾」,竖切回归单轮耗时由 40s+ 降到 12s。