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

481 lines
32 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:12030/ws/solo`;
- `system.ping` / `system.pong` 心跳;
- `gaming.start`、`gaming.state`、`gaming.request`、`gaming.action` 等真实协议消息;
- 角色选择、基础行动、技能、物品、目标和逻辑格决策的初步控件;
- 2D 二等角投影、灰盒地图、范围网格、相机和贴边 HUD;
- 自动连接、开局、选人和接收首个权威快照的冒烟测试。
当前端到端验证结果:
```text
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
```
### 执行进度
- [x] 阶段 A:`UnitView`、按 GUID 实例协调、格子定位、阵营/行动者/HP/淘汰/AI 托管显示;
- [x] 阶段 B 基础:合法格集合高亮、单位直接点击选择目标、提交前确认;
- [x] 阶段 B 完整:移动与普攻的真实端到端竖切回归、服务器拒绝后的决策恢复;
- [x] 阶段 C:完整决策类型与行动配额;
- [x] 阶段 D:断线恢复;
- [x] 阶段 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. 竖切完成后的玩家流程
```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` | 只允许选择合法单位 |
| `ActionType.enemyOptions` / `enemys` | 行动坞 | 当前位置攻击可达 ∪ 施法可达的敌人;为空则禁用普通攻击 |
| `ActionType.dp.quotas` | 行动坞按钮 | 每种行动类型的配额 / 剩余 / 决策点消耗 |
| `request.timeoutMs` | `TimeoutLabel` | 服务器决策倒计时 |
| `state.aiEscalated` | 角色 HUD、`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~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`:
```csharp
attackRange = _map.GetGridsByRange(realGrid, character.ATR, true);
enemys = [.. enemys.Where(attackRange.SelectMany(g => g.Characters).Contains)];
```
**修法(不需要改 FunGame.Core)**:在 `OnDecideAction` 里用同一个公开接口复现这一步,作为新字段下发:
```csharp
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` 与回归测试都改用它。真实对局中抓到的字段组合证实了修复的必要性:
```text
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。