909 lines
50 KiB
Markdown
909 lines
50 KiB
Markdown
# 掼蛋卡牌游戏 — 设计规格
|
||
|
||
**日期：** 2026-05-28
|
||
**引擎：** Godot 4.x
|
||
**语言：** GDScript
|
||
|
||
---
|
||
|
||
## 一、分层架构
|
||
|
||
```
|
||
UI 层 (Godot) → 业务逻辑层 (纯 GDScript) → 数据层 (纯 GDScript)
|
||
↓
|
||
网络层 (Godot ENet，后期)
|
||
```
|
||
|
||
| 层 | 职责 | 技术选型 | 说明 |
|
||
|---|------|----------|------|
|
||
| **UI 层** | 场景渲染、手牌布局、拖拽出牌、按钮交互、动画、音效 | Godot Control 节点 / Tween | 唯一依赖 Godot API 的层，纯"表现" |
|
||
| **业务逻辑层** | 牌型识别、比较大小、出牌合法性、回合流转、得分计算、AI 决策 | 纯 GDScript（零 Godot 依赖） | 核心层，不引用任何 Godot 场景/节点类 |
|
||
| **数据层** | 牌、牌堆、手牌、回合状态、玩家数据、配置表 | 纯 GDScript 数据结构 | 不可变数据结构优先，便于状态回滚 |
|
||
| **网络层** | 联机消息格式、同步协议、断线重连 | Godot ENet | 后期开发，前置预留接口 |
|
||
|
||
**交互规则：**
|
||
- UI 层通过信号/回调调用逻辑层（如 `logic.play_cards(player, cards)`）
|
||
- 逻辑层返回结果后，UI 层负责渲染
|
||
- 逻辑层完全不感知 UI、网络或 AI 的存在（依赖倒置）
|
||
|
||
**异常码定义：**
|
||
|
||
- 逻辑层所有操作统一返回 `Result` 类型：`{ok: bool, error_code: int, data: Variant}`
|
||
- 错误码在 `constants.gd` 中定义枚举：`ERR_INVALID_CARDS`、`ERR_NOT_YOUR_TURN`、`ERR_CANNOT_PASS`、`ERR_CARD_NOT_FOUND`、`ERR_HAND_EMPTY` 等
|
||
- UI 层根据 `error_code` 做对应提示文案，支持多语言
|
||
|
||
**线程安全约束：**
|
||
|
||
- `core/` 和数据层禁止写全局变量，所有状态通过参数传入、返回值传出
|
||
- 避免联机/异步场景下的数据竞争，逻辑层保持无状态函数风格
|
||
- 若需缓存计算结果（如 AI 评分），使用局部闭包而非全局状态
|
||
|
||
**逻辑纯函数约束：**
|
||
|
||
- 核心判定函数（牌型识别、比较大小、合法性校验）必须为纯函数：相同输入必须返回相同输出，无副作用
|
||
- 禁止在核心函数中操作文件、网络、定时器等外部资源
|
||
- 便于单元测试、并行 AI 计算、状态回滚验证
|
||
|
||
**逻辑层的异步执行方案：**
|
||
|
||
- AI 计算（尤其 L2/L3 枚举所有合法出牌组合）是 CPU 密集型操作，同步调用会卡死 UI 线程
|
||
- 利用 Godot 4.x `WorkerThreadPool` 将 AI 决策放入后台线程计算，通过信号或 `await` 将结果回传给 UI 层
|
||
- `move_generator` 的枚举计算同样异步化，`game_controller` 负责协调异步调用链
|
||
|
||
**多线程 AI 的数据竞争防护：**
|
||
|
||
- Godot 4 的 `WorkerThreadPool` 执行 GDScript 时，**严禁子线程直接读取或修改主线程的 `GameState`**（GDScript 的 Dictionary/Array 非线程安全，会导致崩溃或脏数据）
|
||
- AI 线程只能接收**序列化后的纯数据快照**，在子线程完成计算后，仅将生成的 `Action` 序列传回主线程
|
||
- 快照格式不可使用 JSON 字符串（频繁编解码导致内存抖动和 CPU 耗时反向超标），应使用**原生包装数组（PackedInt32Array / PackedByteArray）**，利用位掩码（Bitmask）传递手牌和已出牌状态
|
||
- 主线程的 `game_controller` 统一调用 `Action.apply()` 修改状态，确保同一时刻只有主线程操作数据
|
||
|
||
**状态回滚策略 — 命令模式 + Action 重放：**
|
||
|
||
- GDScript 中深拷贝（`duplicate(true)`）大型 `GameState` 性能极差，不可行
|
||
- 采用 **命令模式（Command Pattern）**：每次操作生成 `Action`，执行 `Action.apply(GameState)` 修改状态
|
||
- 回滚时从初始状态重放 Action 日志到目标点，而非存储完整快照
|
||
- 若需中间快照（如 AI 推演分支），仅对变化的局部数据（Hand、PlayedZone）做浅拷贝，不全局深拷贝
|
||
|
||
**全局事件总线（EventBus）：**
|
||
|
||
- 在 `autoload/` 中增加 `event_bus.gd`（全局信号中心），用于广播游戏事件
|
||
- 事件类型：`PLAYER_PLAYED_CARDS`、`BOMB_DETONATED`、`TRIBUTE_TRIGGERED`、`ROUND_END`、`GAME_OVER` 等
|
||
- UI 组件之间通过订阅 EventBus 信号解耦，避免网状硬编码依赖
|
||
- `core/` 层不依赖 EventBus，仅 `game/` 胶水层和 `ui/` 层使用
|
||
|
||
**EventBus 内存泄漏防护：**
|
||
|
||
- UI 节点（如动态生成的 `card_node.tscn`）若连接全局 EventBus 信号但在销毁时未断开，会导致严重内存泄漏和野指针崩溃
|
||
- 在 UI 基类中重写 `_exit_tree()`，自动遍历并断开所有与 EventBus 的连接
|
||
- 或利用 Godot 4 的 `Callable` 弱引用特性（`bind_weak()`）管理信号订阅，节点销毁时自动失效
|
||
|
||
**配置数据的 Resource 化：**
|
||
|
||
- 静态配置（卡牌属性、音效映射、AI 权重参数、牌型分值表）优先定义为继承自 `Resource` 的自定义类
|
||
- 示例：`class_name CardConfig extends Resource`、`class_name AIParams extends Resource`
|
||
- 优势：可直接利用 Godot 编辑器 Inspector 面板可视化调参；底层 C++ 序列化的性能和安全性远超手写 JSON 解析
|
||
- `config_loader.gd` 保留用于运行时动态配置（如服务器下发的活动参数），静态配置一律用 `.tres` Resource 文件
|
||
|
||
**状态不可变性统一规范：**
|
||
|
||
- GDScript 天生偏可变，需明确不可变性边界：
|
||
- **绝对不可变对象：** `Card`、`PlayedCards`、`Action`（创建后其字段不可修改）
|
||
- **允许局部修改：** `Round`（回合内状态可变）、`GameState`（通过 Action.apply 修改）
|
||
- **禁止共享引用：** 所有 getter 返回副本或只读包装（`duplicate(false)`），禁止返回内部 Array/Dictionary 的原始引用
|
||
- `Array` 和 `Dictionary` 类型的成员变量外部访问时一律浅拷贝
|
||
|
||
**资源生命周期管理：**
|
||
|
||
- 场景退出时必须执行清理，防止残留线程、孤儿节点和隐性内存增长：
|
||
- **线程取消：** `_exit_tree()` 中取消所有 `WorkerThreadPool` 未完成任务，`await` 超时后强制丢弃
|
||
- **Replay 中止：** 场景切换时中断回放录制/播放，保存当前进度
|
||
- **节点对象池上限：** `ObjectPool` 设置 `MAX_POOL_SIZE`，超出部分直接 `queue_free()`
|
||
- **Tween 清理：** `_exit_tree()` 中 `stop_all()` 并 `kill()` 所有活跃 Tween
|
||
- **信号断开：** 调用 `disconnect_all()` + 从 EventBus 取消订阅
|
||
|
||
**日志系统分级：**
|
||
|
||
- 除 Action 游戏日志外，需另建调试日志系统（`log_manager.gd`，autoload）：
|
||
- `DEBUG`：详细调试信息，Release 默认关闭
|
||
- `INFO`：关键流程节点（发牌、进贡、出牌、升级）
|
||
- `WARN`：异常但可恢复（AI 超时降级、心跳超时、状态不一致）
|
||
- `ERROR`：致命错误（Action 失败、状态机非法转移）
|
||
- `NETWORK`：联机消息日志
|
||
- `AI_TRACE`：AI 决策明细日志
|
||
- `PERF`：性能基准日志
|
||
- **安全约束：** `INFO` 及以上禁止打印完整手牌内容；联机模式 `DEBUG` 默认关闭；日志支持写入文件 + 按大小轮转
|
||
|
||
**多人异步事件顺序约束：**
|
||
|
||
- 常见冲突场景：动画未播完时收到下一 Action、Pass 与清场同时发生、接风与结算同时触发
|
||
- 解决方案：
|
||
- **Event Queue（事件队列）：** `game_controller` 维护优先级事件队列，按时间戳串行消费
|
||
- **UI Transition Lock：** 动画/过渡期间锁住输入，动画结束回调释放锁
|
||
- **强制事件串行化：** 同一帧内只处理一个状态变更，防止 UI 状态错乱
|
||
- 事件优先级：`FATAL_ERROR > GAME_OVER > PLAYER_ACTION > ANIMATION > IDLE`
|
||
|
||
**配置热更新边界：**
|
||
|
||
- 配置分为三层，每层有不同的更新约束：
|
||
|
||
| 层级 | 说明 | 更新时机 | 示例 |
|
||
|------|------|----------|------|
|
||
| Immutable Match Config | 对局开始后不可变 | 仅在房间创建时 | 牌数、逢人配规则、炸弹规则 |
|
||
| Runtime Tweak Config | 可运行时调整 | 对局中或局间 | AI 难度、音效音量、UI 动画速度 |
|
||
| Client Cosmetic Config | 纯本地配置 | 随时 | 卡牌皮肤、背景主题、语言 |
|
||
|
||
- `RuleConfig`（不可变）在联机房间中由房主下发，参与状态哈希；对局中修改需重开房间
|
||
|
||
---
|
||
|
||
## 二、核心数据模型
|
||
|
||
### 卡牌
|
||
|
||
掼蛋使用两副牌（108张），含大小王。
|
||
|
||
```
|
||
Card: 整数 ID 0-107（两副牌），位运算高效比较大小
|
||
card_id: 0-107 全局唯一 ID，用于日志追踪、网络同步和 UI 渲染
|
||
card_value: 花色 + 点数编码，用于规则比对（忽略唯一 ID）
|
||
Suit: 4 花色 (♠ ♥ ♣ ♦) + Joker
|
||
Rank: 2-14 (2=2, ..., 10=10, J=11, Q=12, K=13, A=14) + 小王=15 + 大王=16
|
||
original_id: 0-53，标记该牌来自第几副牌的第几张，区分两副牌中相同点数花色的牌
|
||
Deck: 108 张 Card 列表 → 洗牌、发牌
|
||
Hand: 玩家手牌，按 Rank→Suit 排序
|
||
```
|
||
|
||
**card_id 与 card_value 区分：**
|
||
- `card_id`（0-107）：全局唯一，日志/同步/渲染时使用
|
||
- `card_value`（Suit + Rank 编码）：规则比对时使用，两副牌中相同花色点数的牌共享同一 `card_value`
|
||
- 牌型识别、比较大小等核心函数统一按 `card_value` 比较，忽略 `card_id`
|
||
|
||
### 出牌
|
||
|
||
```
|
||
PlayedCards: 带类型的联合
|
||
{type: TYPE_SINGLE | TYPE_PAIR | TYPE_TRIPLE | ... | TYPE_ROCKET,
|
||
cards: [...],
|
||
primary_rank: 主牌点数,
|
||
is_pure_bomb: bool} # 炸弹是否为纯炸（无逢人配参与）
|
||
```
|
||
|
||
牌型识别是纯函数：输入 `[Card]` → 输出 `PlayedCards | null`
|
||
|
||
**多合一牌型歧义与推荐优先级：**
|
||
|
||
当手牌同时拥有多张逢人配时，同一组牌可能对应多种牌型。例如手牌 `4、5、6` + 两张逢人配：
|
||
- 可构成顺子：`4、5、6、逢(7)、逢(8)`
|
||
- 可构成连对：`4、4、5、5、6`（逢人配转写为 4 和 5 的对子）
|
||
- 可构成三带二：`4、4、4、5、6`（逢人配转写为三同张）
|
||
|
||
`hand_evaluator.gd` 需定义**牌型推荐优先级枚举**，当同一组牌存在多种合法解释时，按优先级返回默认牌型：
|
||
|
||
| 优先级 | 牌型 | 说明 |
|
||
|--------|------|------|
|
||
| 1 | 火箭（四王） | 最高 |
|
||
| 2 | 炸弹（含纯炸 > 混炸） | 优先组成更大炸弹 |
|
||
| 3 | 同花顺 | |
|
||
| 4 | 钢板（三连对） | |
|
||
| 5 | 连对 | |
|
||
| 6 | 顺子 | |
|
||
| 7 | 三带二 | |
|
||
| 8 | 三不带 | |
|
||
| 9 | 对子 | |
|
||
| 10 | 单张 | 最低 |
|
||
|
||
UI 层在检测到歧义牌型时，允许玩家通过按钮切换可选分支（"以顺子出" / "以连对出"）。
|
||
|
||
**同花顺配牌花色转写：** 逢人配（红桃级牌）参与拼凑非红桃同花顺时，其自身花色强制转写为目标花色，结算时仅作为目标花色的点数存在，丧失原本的红桃属性。
|
||
|
||
### 游戏状态
|
||
|
||
```
|
||
Round: 当前回合状态（谁出牌、出的什么、本轮出牌历史）
|
||
GameState: 完整一局状态（4个玩家、牌堆、得分、升级、贡牌信息）
|
||
round_seq: 局次编号，支持多局连胜/积分统计
|
||
current_rank: 当前打的级牌等级（2-A），决定逢人配（红桃级牌为万能牌）
|
||
```
|
||
|
||
**2v2 队伍模型（Team）：**
|
||
|
||
- 掼蛋为 2v2 对战：1、3 号位为一队（Team A），2、4 号位为一队（Team B）
|
||
- 算分、升级、进贡、还贡、AI 配合逻辑全部强依赖队伍关系
|
||
- `GameState` 引入 `Team` 结构：`{team_id, players: [Player], score, current_level}`
|
||
- 每局胜利条件：一队中两人都先出完即为"双下"（大胜），一人先出完为"头游"（小胜）
|
||
|
||
**局间流转状态机：**
|
||
|
||
掼蛋完整循环不仅是出牌，还包含复杂的局间阶段。`GameState` 的状态机：
|
||
|
||
```
|
||
INIT → DEAL → TRIBUTE_PHASE → PLAY_PHASE → LEVEL_UP_PHASE → DEAL（下一局）/ GAME_OVER
|
||
```
|
||
|
||
| 阶段 | 说明 | 关键校验 |
|
||
|------|------|----------|
|
||
| `INIT` | 初始化，确定级牌、洗牌 | — |
|
||
| `DEAL` | 发牌 27 张/人 | 两副牌 108 张全部分发 |
|
||
| `TRIBUTE_PHASE` | 进贡 / 还贡 / 抗贡 | 双下进贡分配逻辑、抗贡条件（对家也是进贡方则互抵） |
|
||
| `PLAY_PHASE` | 出牌循环，直到三人出完 | 牌型合法性、回合轮转、过牌规则、三人连续 Pass 触发清场（CLEARED） |
|
||
| `LEVEL_UP_PHASE` | 根据名次判定升级 | 头游队升 1 级，双下游队向胜队进贡；双下则胜队升 3 级 |
|
||
|
||
**级牌与逢人配动态判定：**
|
||
|
||
- `GameState.current_rank` 维护当前打的级牌等级
|
||
- 红桃花色 + 当前级牌点数 = 逢人配（万能牌），在牌型评估时动态赋予百搭属性
|
||
- `rule_engine` / `hand_evaluator` 在识别牌型时，必须结合 `current_rank` 判定是否为逢人配
|
||
|
||
**CLEARED 状态（清场规则）：**
|
||
|
||
- 掼蛋规则中，若连续三人弃牌（Pass），最后出牌者获得自由出牌权，即该轮"清场"
|
||
- `Round` 状态机需增加 `CLEARED` 子状态标识
|
||
- UI 层配合：播放"桌面旧牌收起"动画 + 音效，明确提示玩家当前可出任意合法牌型
|
||
- 清场后当前玩家开始新一轮出牌，本轮历史出牌记录归档至出牌历史侧边栏
|
||
|
||
**接风规则（Catch-Up）：**
|
||
|
||
- 掼蛋核心规则：当某玩家打出最后一手牌，且全场 Pass（该玩家成为头游），下一轮的自由出牌权（接风权）转移给其 **对家（队友）**，而非下家
|
||
- `round.gd` 在检测到玩家手牌清空（`HAND_EMPTY`）且其余人 Pass 时，强制执行接风拦截：下轮 `active_player` 直接指定为当前出完牌玩家的 `teammate`
|
||
- 接风后队友获得自由出牌权（等同于 CLEARED 状态），可出任意牌型
|
||
- 若接风者同时也是最后一名有空牌的玩家，则本局结束
|
||
|
||
**逢人配"纯度"降级规则：**
|
||
|
||
- 含逢人配的炸弹（如 3 张真牌 + 1 张逢人配）在比较时，必须 **小于** 同等点数的纯炸（4 张真牌）
|
||
- 逢人配 **不能** 参与组成天王炸（四王 / 火箭）
|
||
- `PlayedCards.is_pure_bomb` 标记记录炸弹纯度；`rule_engine` 在比较炸弹时，纯度作为高于点数的第一优先级：
|
||
1. 先比类型（火箭 > 普通炸弹）
|
||
2. 再比纯度（纯炸 > 混炸）
|
||
3. 再比点数（Rank 大的 > Rank 小的）
|
||
4. 最后比张数（炸弹张数多的 > 少的）
|
||
|
||
**进贡/还贡具体边界校验：**
|
||
|
||
- 进贡阶段合法性校验：
|
||
- 进贡必须出手牌中 **最大的牌**（受当前级牌/逢人配排除规则约束，依具体规则变体而定）
|
||
- 不能进贡逢人配（红桃级牌），不能进贡当前级牌
|
||
- 双下进贡：末游向头游进贡、次末游向头游队友进贡
|
||
- 还贡阶段合法性校验：
|
||
- 还贡必须是 **单张**
|
||
- 还贡不能是逢人配
|
||
- 还贡点数不能大于 10（依规则变体可配置）
|
||
- 抗贡条件：双方均为进贡方（互为进贡对象）时互抵，既不进也不还
|
||
|
||
**大王抗贡的唯一性校验：**
|
||
|
||
- 掼蛋规定"双大王抗贡"，两副牌共 2 张大王
|
||
- 抗贡必须由 **同一个人** 同时抓到 2 张大王（`Rank.16`），才触发全场抗贡
|
||
- 若队友各执一张大王，不触发抗贡
|
||
- `tribute_phase` 校验逻辑：遍历单人手牌，检查单人 `hand` 中 `Rank.16` 数量 ≥ 2
|
||
|
||
**进贡最大牌的"同点数次级判定"：**
|
||
|
||
- 当玩家需要进贡最大牌，但手牌中最大点数有两张（如两张不同花色的 K），且都不属于级牌
|
||
- 次级判定规则：
|
||
1. 优先进贡非红桃的牌（避免将逢人配进贡出去）
|
||
2. 若点数花色均相同（两副牌中同一张牌），系统随机选择或提供 UI 让玩家勾选
|
||
3. 逢人配（红桃级牌）绝对不可进贡，已在主规则中排除
|
||
|
||
### Action 日志
|
||
|
||
```
|
||
Action: {player, action_type, cards, timestamp}
|
||
action_type: PLAY | PASS | TRIBUTE_GIVE | TRIBUTE_RETURN | RESHUFFLE | GAME_END
|
||
```
|
||
|
||
状态变更生成 `Action` 记录，构成不可变日志。这是联机同步和观战回放的基础。
|
||
|
||
**贡牌/还贡专用 Action：** 使用独立类型 `TRIBUTE_GIVE` 和 `TRIBUTE_RETURN`，避免与普通出牌混同导致逻辑混乱和校验冲突。
|
||
|
||
**逢人配来源标记：** 每张用于配牌的逢人配 Card 附带 `wild_source: GRADE_CARD | SYSTEM_ALLOC` 标记，支持规则变体（是否允许级牌做配牌、系统自动配牌上限等）。
|
||
|
||
### RuleConfig（规则变体配置化）
|
||
|
||
掼蛋在不同地区存在规则差异，所有核心规则必须数据驱动，不得硬编码在逻辑中。
|
||
|
||
```
|
||
RuleConfig: {
|
||
same_suit_straight_beats_bomb: bool, # 同花顺是否大于普通炸弹
|
||
double_down_levels: int, # 双下升几级（默认 3）
|
||
can_tribute_wild: bool, # 是否允许红桃级牌进贡
|
||
tribute_return_max_rank: int, # 还贡点数上限（默认 10，0=不限）
|
||
straight_extends_to_ace: bool, # 顺子是否可延伸到 A
|
||
bomb_compare_priority: enum, # 炸弹比较优先级：BOMB_BY_RANK 点数优先 / BOMB_BY_COUNT 张数优先
|
||
wild_count: int, # 逢人配数量（默认 2）
|
||
team_formation: enum, # 队伍构成：FIXED_1_3 固定 1/3 号位 / RANDOM 随机
|
||
}
|
||
```
|
||
|
||
**使用约束：**
|
||
- `RuleConfig` 是 Immutable Match Config，对局开始后不可修改
|
||
- 联机时由房主下发统一 `RuleConfig`，参与 `GameState` 状态哈希校验
|
||
- 核心规则函数（`rule_engine`、`hand_evaluator`、`game_state`）的参数中必须包含 `RuleConfig` 引用
|
||
- 单机模式下可通过菜单选择预设规则（"标准" / "淮安" / "安徽" 等）
|
||
|
||
---
|
||
|
||
## 三、AI 架构
|
||
|
||
| 层级 | 名称 | 适用场景 | 逻辑 |
|
||
|------|------|----------|------|
|
||
| **L1** | 基础 AI | 训练模式"简单"难度 | 能出就出最少的牌，规则合规即可 |
|
||
| **L2** | 规则 AI | 训练模式"中等"、单机普通 | 启发式评分：保留炸弹、拆牌优先短顺、配牌合理使用 |
|
||
| **L3** | 策略 AI | 训练模式"困难"、单机困难 | 记忆出牌、推理队友意图、控制炸弹节奏 |
|
||
|
||
**技术细节：**
|
||
|
||
- AI 与玩家调用同一个 `logic.play_cards()` 接口
|
||
- L2/L3 使用启发式评分：每个合法出牌组合 → 计算策略评分 → 选最优
|
||
- L3 加入对战历史分析，通过复盘 `Action` 日志做状态推演
|
||
- 训练模式的"牌型提示"展示 L2 AI 的最优解
|
||
|
||
**AI 安全与性能约束：**
|
||
|
||
- **防死循环机制：** AI 决策若超过 3 秒未返回，自动降级到 L1 基础 AI，确保对局不卡死
|
||
- **可禁用提示开关：** 训练模式的牌型提示可通过配置关闭，避免干扰正式对局或高阶玩家
|
||
- **统一决策耗时上限：** 所有 AI 层级共用 `MAX_AI_DECISION_MS` 配置项，防止卡顿主线程；复杂计算使用分帧/线程池处理
|
||
|
||
**队伍配合意识（Teammate Awareness）：**
|
||
|
||
- L2/L3 AI 的启发式评分函数必须引入队友和对手状态权重：
|
||
- **队友剩余牌数**：队友剩 1-2 张时优先出小单张/对子"送牌"助攻
|
||
- **队友头游判定**：队友已出完时切换到保级策略
|
||
- **对手压制权重**：对手剩 1-2 张时提升炸弹/大牌的出牌优先级，避免对手跑掉
|
||
- 评分公式示例：`score = hand_quality * 0.4 + teammate_context * 0.3 + opponent_threat * 0.3`
|
||
|
||
**宏观局势与目标管理：**
|
||
|
||
- AI 需根据当前积分差和升级规则，动态切换策略模式：
|
||
- **保守策略**：本局只需保一人头游即可升级时，优先保护已有优势，减少激进出牌
|
||
- **激进策略**：落后方必须抓双下才能反超时，主动拆炸弹、保留大牌组合冲击双下
|
||
- 策略模式切换由 `GameState` 的积分差和 `current_rank` 自动计算
|
||
|
||
**记牌与算牌维度（L3 专用）：**
|
||
|
||
- L3 维护"场外信息池"（Hidden Information Pool），追踪三类信息：
|
||
1. **记大牌**：王、级牌、A 的已出数量，推算剩余威胁
|
||
2. **记断门**：某花色已出完 13 张时，推断对手不可能持有该花色的同花顺/炸弹
|
||
3. **记剩余牌数**：结合已出牌总数，推算对手手中最多几张炸弹，判断压制可能性
|
||
- 信息池在每轮出牌后增量更新，不依赖回放全量重算
|
||
|
||
**L3 手牌推断（Hand Inference）：**
|
||
|
||
- 仅有"记牌池"不足以支撑 L3 高级决策，还需根据对手行为概率化推测其手牌分布
|
||
- 在 `utils/probability.gd` 中增加贝叶斯推断模块：
|
||
- 对手进贡了一张红桃A → 推断对手手中缺大牌 → 后续可大胆用中等牌型压制
|
||
- 对手多轮不出某花色 → 推定该花色可能为断门或预留炸弹
|
||
- 还贡牌型（小单张）→ 推断对手在清杂牌准备冲刺
|
||
- 推断结果以概率分布形式存入 Hidden Information Pool，供评分函数加权使用
|
||
|
||
**伪随机数生成器（PRNG）种子注入：**
|
||
|
||
- `deck.gd` 的洗牌算法（Fisher-Yates）必须支持外部注入随机种子（Seed）
|
||
- AI 决策中涉及随机选择的部分（如多个同等评分出牌）同样使用可复现的 PRNG
|
||
- 目的：跑 GUT 自动化测试时，可复现完全相同的发牌序列和 AI 决策路径，实现确定性测试
|
||
- 正式对局使用系统真随机（`randf()`），测试用固定种子
|
||
|
||
**AI 可观测性与调试工具：**
|
||
|
||
- AI 决策对玩家和开发者不透明，需提供可观测性支持：
|
||
- **AI Decision Trace：** 决策树日志，记录每一轮 AI 考虑的所有合法出牌组合及其评分明细
|
||
- **评分明细展示：** 调试模式下显示"为什么出这手牌"面板：`手牌质量: 0.7 | 队友权重: 0.8 | 对手威胁: 0.5 = 总分 2.0`
|
||
- **AI HeatMap：** 手牌上颜色覆盖显示关键牌/危险牌权重（红色=炸弹候选，蓝色=顺子候选，黄色=配牌候选）
|
||
- **Replay + AI Debug Overlay：** 回放模式下叠加 AI 决策过程，可逐帧回溯 AI 思路
|
||
- 调试模式通过配置开关控制（`enable_ai_debug`），正式对局关闭
|
||
|
||
**AI 与规则引擎的隔离边界：**
|
||
|
||
- AI 推演必须在沙盒环境中完成，防止隐性修改真实状态：
|
||
- AI **禁止直接修改**任何 `GameState` 或其子对象的字段
|
||
- AI **不允许缓存**任何可变引用（如 `GameState.players` 数组的引用）
|
||
- AI 推演时必须基于 `GameState` 的只读快照（`PackedInt32Array`），在沙盒中操作临时状态
|
||
- AI 唯一输出为 `Action` 对象或 `null`（弃牌），由 `game_controller` 统一 apply
|
||
|
||
---
|
||
|
||
## 四、项目文件结构
|
||
|
||
```
|
||
game-cards/
|
||
├── project.godot
|
||
├── addons/ # 第三方插件（按需）
|
||
├── assets/
|
||
│ ├── cards/ # 52 张卡面图 + 2 王牌 + 牌背
|
||
│ ├── ui/ # UI 贴图、按钮、桌布背景
|
||
│ ├── audio/ # 音效、BGM
|
||
│ └── fonts/ # 字体
|
||
│
|
||
├── localization/ # 多语言文本
|
||
│ ├── zh_cn.csv # 简体中文
|
||
│ └── en.csv # 英文
|
||
│
|
||
├── save/ # 存档目录（运行时生成）
|
||
│ ├── settings.cfg # 用户设置
|
||
│ └── records/ # 对局记录
|
||
│
|
||
├── tools/ # 工具脚本
|
||
│ ├── card_generator.gd # 批量生成卡牌资源
|
||
│ └── config_converter.gd # 配置文件格式转换
|
||
│
|
||
├── src/
|
||
│ ├── core/ # ★ 业务逻辑层（零 Godot 依赖）
|
||
│ │ ├── card.gd # Card 类型、牌组定义、排序比较
|
||
│ │ ├── deck.gd # 洗牌、发牌
|
||
│ │ ├── hand.gd # 手牌管理、排序
|
||
│ │ ├── hand_evaluator.gd # 牌型识别：判断给定牌组属于何种牌型
|
||
│ │ ├── move_generator.gd # 合法出牌生成：枚举手牌所有合法出牌组合（含剪枝优化）
|
||
│ │ ├── rule_engine.gd # 出牌合法性校验 + 牌型比较大小
|
||
│ │ ├── round.gd # 回合流转状态机
|
||
│ │ ├── game_state.gd # 全局游戏状态（计分、升级、贡牌、队伍）
|
||
│ │ ├── actions.gd # Action 日志定义 + apply/rollback
|
||
│ │ ├── config_loader.gd # 配置表解析（JSON/CSV，AI 参数、关卡等）
|
||
│ │ └── constants.gd # 枚举、配置常量
|
||
│ │
|
||
│ ├── utils/ # 通用工具库
|
||
│ │ ├── combinatorics.gd # 组合数学（C(n,m)、排列枚举、剪枝辅助）
|
||
│ │ ├── shuffle.gd # 洗牌算法（Fisher-Yates）
|
||
│ │ └── probability.gd # 概率计算辅助
|
||
│ │
|
||
│ ├── ai/ # AI 模块
|
||
│ │ ├── base_ai.gd # AI 基类接口
|
||
│ │ ├── l1_basic_ai.gd # 简单 AI
|
||
│ │ ├── l2_rule_ai.gd # 规则 AI（带启发式评分）
|
||
│ │ └── l3_strategy_ai.gd # 策略 AI
|
||
│ │
|
||
│ ├── game/ # 游戏控制器（胶水层）
|
||
│ │ ├── game_controller.gd # 单机对战的流程控制
|
||
│ │ ├── training_controller.gd # 训练模式控制
|
||
│ │ └── replay_recorder.gd # 回放录制
|
||
│ │
|
||
│ ├── network/ # 联机层（后期开发）
|
||
│ │ ├── network_interface.gd # 抽象接口
|
||
│ │ ├── client.gd # 客户端同步
|
||
│ │ └── server.gd # 服务器端
|
||
│ │
|
||
│ ├── ui/ # UI 场景和脚本
|
||
│ │ ├── scenes/
|
||
│ │ │ ├── main_menu.tscn
|
||
│ │ │ ├── game_table.tscn # 主牌桌
|
||
│ │ │ ├── training_room.tscn # 训练室
|
||
│ │ │ ├── lobby.tscn # 大厅（联机）
|
||
│ │ │ └── spectator.tscn # 观战
|
||
│ │ └── components/ # 可复用 UI 组件
|
||
│ │ ├── card_node.tscn # 单张卡牌控件
|
||
│ │ ├── hand_area.tscn # 手牌区域
|
||
│ │ ├── played_zone.tscn # 出牌展示区
|
||
│ │ ├── card_type_hint.tscn # 牌型提示浮窗（训练模式）
|
||
│ │ ├── play_history_sidebar.tscn # 出牌历史侧边栏（可折叠）
|
||
│ │ └── scoreboard.tscn # 记分板
|
||
│ │
|
||
│ └── autoload/ # Godot Autoload 单例
|
||
│ ├── config.gd # 全局配置
|
||
│ ├── event_bus.gd # 全局事件总线（信号中心），解耦 UI 组件通信
|
||
│ ├── audio_manager.gd # 音频管理
|
||
│ └── scene_manager.gd # 场景切换
|
||
│
|
||
└── tests/ # 测试（逻辑层）
|
||
├── test_cards.gd
|
||
├── test_deck.gd
|
||
├── test_hand_evaluator.gd
|
||
├── test_move_generator.gd
|
||
├── test_rule_engine.gd
|
||
├── test_game_state.gd
|
||
├── test_tribute.gd # 进贡/还贡/抗贡边界
|
||
├── test_state_recovery.gd # 断线重连状态恢复
|
||
└── test_ai.gd
|
||
```
|
||
|
||
**关键原则：**
|
||
- `core/` 目录下任何文件不引用 `res://src/ui/`、`res://src/game/` 或 Godot 节点类
|
||
- `game/` 是桥接层，串联 core + UI（或 core + network）
|
||
- test 只测 core 层，不依赖场景
|
||
|
||
**rule_engine 拆分理由：**
|
||
- 带有逢人配（百搭）时，合法出牌组合数量呈指数级爆炸，`rule_engine.gd` 职责过重
|
||
- 拆分为三个模块：
|
||
- `hand_evaluator.gd`：判断给定牌组属于何种牌型（纯判定，轻量）
|
||
- `rule_engine.gd`：出牌合法性校验 + 比较大小（规则比对）
|
||
- `move_generator.gd`：生成当前手牌所有合法出牌组合（含剪枝优化，供 AI 专用）
|
||
|
||
**move_generator 剪枝策略（防组合爆炸）：**
|
||
|
||
逢人配 + 双副牌导致合法出牌组合数呈指数级失控，必须硬性剪枝：
|
||
|
||
- **等价状态去重：** 相同牌型、相同点数的出牌只保留一种（如两张不同的黑桃A组成的对子视为等价）
|
||
- **对称配牌剪枝：** 多张逢人配可互换位置时，只保留一种枚举（如两张逢人配当 `7` 和 `8` 与当 `8` 和 `7` 等价）
|
||
- **Beam Search 上限：** L2/L3 评分阶段保留前 `BEAM_WIDTH`（默认 50）个最优候选，丢弃低分分支
|
||
- **最大枚举节点数：** 单次 `move_generator` 枚举上限 `MAX_ENUM_NODES`（默认 10000），超限后自动降级为启发式搜索
|
||
- **降级策略：** 枚举超限时切换为贪心出牌（按牌型优先级选择最大牌组合），保证回合不超时
|
||
|
||
### 新增文件
|
||
|
||
```
|
||
├── src/core/
|
||
│ ├── rule_config.gd # RuleConfig 资源类（定义规则变体）
|
||
│ └── ...
|
||
├── src/
|
||
│ ├── statistics/ # 数值统计模块
|
||
│ │ └── stats_tracker.gd # 胜率、双下率、炸弹率等统计
|
||
│ │
|
||
│ ├── debug/ # 调试与可观测性
|
||
│ │ ├── ai_trace.gd # AI 决策日志
|
||
│ │ └── debug_overlay.gd # 调试叠加层
|
||
│ │
|
||
│ ├── logging/ # 日志系统
|
||
│ │ └── log_manager.gd # 分级日志管理
|
||
```
|
||
|
||
---
|
||
|
||
## 五、测试策略
|
||
|
||
| 测试类型 | 范围 | 工具 | 内容 |
|
||
|----------|------|------|------|
|
||
| **单元测试** | `core/` 所有模块 | GUT (Godot Unit Test) | 牌型识别、比较大小、得分计算、洗牌发牌 |
|
||
| **集成测试** | `core/` + `ai/` | GUT | AI 对不同局面的决策、完整一局流程 |
|
||
| **回归测试** | `core/` 规则引擎 | GUT | 固定测试套件，每次修改规则引擎必须全过 |
|
||
| **恶意输入测试** | `core/` 所有入口 | GUT | 空牌、重复牌、越界牌、非法牌型组合 |
|
||
| **性能基准** | `core/` + `ai/` | GUT + 计时 | 牌型识别 <1ms、AI决策 <3s、状态序列化 <50ms |
|
||
| **UI 测试** | `ui/` 场景 | 手动 + 截图对比 | 手牌渲染、动画、交互 |
|
||
|
||
**重点测试用例：**
|
||
- 掼蛋所有牌型识别覆盖（单张、对子、三不带、三带二、顺子、钢板、连对、同花顺、炸弹、火箭）
|
||
- 配牌（逢人配）边界情况 — 最高/最低配、多配同时可选
|
||
- 炸弹升级场景（四炸 → 五炸 → … → 火箭）
|
||
- 逢人配被炸弹压制的优先级
|
||
- CI 每次提交跑 `gut` 命令行，全绿才算合格
|
||
|
||
**回归测试集要求：** 维护一份固定的 `tests/regression/` 目录，包含 50+ 覆盖各种边界的牌型场景，每次修改规则引擎必须全部通过。
|
||
|
||
**恶意输入测试覆盖：**
|
||
- 传入空数组、重复卡片 ID、越界 ID（<0 或 >107）
|
||
- 不符合任何牌型的非法卡牌组合
|
||
- 同一张牌在牌组中出现超过 4 次（两副牌最多每种 4 张）
|
||
|
||
**性能基准阈值：**
|
||
- 单次牌型识别 < 1ms
|
||
- `move_generator` 最坏情况（手牌 15 张含 2 张逢人配）：枚举所有合法组合 < 16ms（保证异步处理不超时）
|
||
- AI 决策（L2）< 2s，（L3）< 5s，超时自动降级
|
||
- 完整状态序列化/反序列化 < 50ms
|
||
|
||
**进贡/还贡/抗贡边界测试用例：**
|
||
- 双下进贡分配逻辑：谁向谁进贡、进几张、大小牌选择
|
||
- 抗贡条件判定：双方均为进贡方时互抵（不进不还）的精确条件
|
||
- 还贡牌型合法性：还贡必须是单张、不能还逢人配、不能还级牌
|
||
- 进贡阶段 Action 日志完整性
|
||
|
||
**断线重连状态恢复测试：**
|
||
- 基于 Action 日志重放恢复 `GameState` 的集成测试
|
||
- 确保重连后双方状态绝对一致：已出的牌、剩余牌数、当前分数、谁在回合中
|
||
- 测试中断场景：进贡中掉线、出牌中掉线、结算中掉线
|
||
|
||
**测试数据生成器：**
|
||
|
||
- **随机牌局生成器（Fuzz）：** `tools/fuzz_dealer.gd`，自动生成 10000+ 局随机发牌，喂入 AI 对打，自动发现崩溃/卡死/非法状态
|
||
- **特殊边界牌局生成器：** `tools/edge_case_generator.gd`，预设边界场景（全炸弹手、全逢人配、空手回溯等）
|
||
- **Monte Carlo 对局生成：** 随机发牌 × 多 AI 难度 × 多规则配置的批量对局，输出胜率统计和性能分布
|
||
- **Fuzz 测试集成至 CI：** 每次提交跑 500 局随机对局，发现异常自动标记
|
||
|
||
---
|
||
|
||
## 六、开发顺序
|
||
|
||
1. **训练模式** — 核心逻辑 + L1/L2 AI + 牌型提示 UI
|
||
2. **单机对战** — 完整四人局 + L3 AI + 完整 UI
|
||
3. **联机** — Action 同步协议 + 匹配 + 房间
|
||
4. **观战** — Action 流回放 + 观战 UI
|
||
|
||
**各阶段接口冻结点：**
|
||
|
||
| 阶段 | 冻结接口 | 说明 |
|
||
|------|----------|------|
|
||
| 训练模式完成 | Card、Deck、Hand、PlayedCards、rule_engine | 核心数据结构和牌型判定不再变更 |
|
||
| 单机对战完成 | GameState、Round、Action、AI 基类接口 | 状态管理和 AI 接口定型 |
|
||
| 联机开始 | NetworkInterface 抽象层 | 联机协议可独立迭代不影响上层 |
|
||
|
||
每个阶段冻结后，后续重构只影响当前阶段模块，不回溯修改已冻结接口。
|
||
|
||
**训练模式优先完成：**
|
||
- 牌型校验全覆盖（所有牌型 + 边界 + 逢人配），全部回归测试通过
|
||
- 再做 AI 集成与 UI 开发，避免"功能在前，正确性在后"导致返工
|
||
|
||
**单机模式全流程验证：**
|
||
- 必须先跑通"发牌 → 进贡 → 还贡 → 出牌循环 → 升级判定 → 结算"完整链路
|
||
- 验证多局连胜、级牌升级、炸弹升级等长期状态正确性
|
||
|
||
---
|
||
|
||
## 七、约束与边界
|
||
|
||
**单局最大时长限制：** 配置项 `MAX_GAME_DURATION_SEC`，超时判定为强制结束/平局，防止一方故意拖延。
|
||
|
||
**防重复出牌校验：** 同一套牌（相同 `original_id` 组合）不能在同一轮连续打出，尤其针对"过牌后再出同一套"的边界。
|
||
|
||
**出牌区最大显示数量：** 中央出牌区每次最多显示 4 组（各玩家最新一轮出牌），旧牌自动收起，避免 UI 溢出。
|
||
|
||
**级牌、主牌、逢人配优先级判定流程：**
|
||
1. 判定当前级牌等级（从 `GameState.level` 读取）
|
||
2. 主牌 = 级牌 + 两张逢人配（系统配）
|
||
3. 逢人配可用于补齐任意牌型（顺子、钢板、连对等），但必须在炸弹压制规则下低于同点数炸弹
|
||
4. 逢人配不参与火箭（大小王）判定
|
||
|
||
**终端状态分支：**
|
||
- `GAME_END_NORMAL`：一方升至A并获胜
|
||
- `GAME_END_SURRENDER`：一方投降
|
||
- `GAME_END_TIMEOUT`：超时强制结束
|
||
- `GAME_END_DRAW`：平局（双方同分且均未升级）
|
||
- `GAME_END_DISCONNECT`：联机中一方掉线超时
|
||
|
||
**断线托管机制：** 联机模式下，离线玩家自动交由 AI（默认 L2）托管，并在 UI 显示托管标识和倒计时；重连后恢复玩家控制。
|
||
|
||
**异常恢复策略：**
|
||
|
||
- 不可恢复的异常（Fatal Error）需分级处理：
|
||
- **Action apply 失败：** 日志记录 + 拒绝该 Action + 请求服务端全量状态同步
|
||
- **非法状态进入：** 自动回退到最近合法快照（每 N 轮自动保存快照），从快照重放
|
||
- **Action 日志损坏：** 标记损坏段 + 请求全量同步 + 客户端重建 UI
|
||
- **回放中断：** 保存进度 + 允许从中断点续播
|
||
- **网络包缺失：** 基于 `action_seq` 检测空洞 + 发送补发请求 + 超时后请求全量同步
|
||
- **崩溃日志导出：** 发生 Fatal Error 时自动导出崩溃栈 + 最近 100 条 Action 日志到 `save/crash/`
|
||
|
||
**多人托管切换边界：**
|
||
|
||
- 托管玩家重连时的冲突场景需要明确定义：
|
||
- **所有权转移时机：** 托管状态下，AI 已产生但未 apply 的 Action 在玩家重连瞬间丢弃；正在执行的 AI 计算可等结果返回，但标记为"AI 建议"而非强制执行
|
||
- **AI 行为不可撤销：** 已 apply 的 AI Action 不可回退，玩家重连后从当前状态继续
|
||
- **重连保护期：** `RECONNECT_GRACE_PERIOD`（默认 2s），重连后 2 秒内禁用托管自动出牌，给玩家恢复操作时间
|
||
- 托管模式下 UI 显示闪烁边框 + "AI Auto-Play" 标签
|
||
|
||
---
|
||
|
||
## 八、UI 交互规范
|
||
|
||
**手牌布局规则：**
|
||
- 自动对齐：手牌按 Rank→Suit 排序后均匀分布，中心对齐
|
||
- 重叠防遮挡：手牌扇形/横向排列，重叠率 50%-65%，被选中牌抬高 20px
|
||
- 长牌适配：手牌 >20 张时自动缩小间距和卡牌尺寸，确保全部可见
|
||
|
||
**27 张手牌的"智能理牌/折叠"：**
|
||
|
||
- 起手 27 张牌（进贡后可达 28 张），在移动端或小屏幕上极其拥挤，拖拽框选极易误触
|
||
- **按牌型分类视图：** 手牌区分为单张区、对子区、三同张区、炸弹区、顺子区，玩家可切换视图
|
||
- **自动折叠：** 连续的顺子、钢板、三同张自动折叠显示为一组，点击展开
|
||
- **手动标记：** 玩家可手动将多张牌标记为一组，组内牌共享高亮颜色
|
||
- 折叠/展开状态持久化，保存到用户设置
|
||
|
||
**出牌历史侧边栏：**
|
||
|
||
- 中央出牌区收起旧牌后，玩家算牌极为困难
|
||
- 在 UI 边缘增加可折叠的"出牌历史侧边栏"，以紧凑文本或微缩图形式记录最近 3-5 轮各家的出牌明细
|
||
- 显示格式：`[轮次] 玩家1: 过 | 玩家2: 对2 | 玩家3: 对K（压）| 玩家4: 过`
|
||
- 辅助玩家手动算牌、也为 L3 AI 的记牌模块提供快速回溯入口
|
||
|
||
**滑动框选防误触（V-Filtering 重叠度阈值）：**
|
||
|
||
- 移动端 27 张牌极度紧凑，框选时极易连带选中目标牌左右两侧的边缘牌
|
||
- 引入 **滑动轨迹重叠度阈值**：手指滑动的 X/Y 轴轨迹覆盖某张卡牌 **中心区域超过 40%** 时才判定选中
|
||
- 仅擦过卡牌边缘（覆盖率 <10%）的不触发悬起/选中
|
||
- 阈值可配置（`SELECTION_OVERLAP_THRESHOLD`），桌面端可适当降低
|
||
|
||
**逢人配智能吸附：**
|
||
|
||
- 玩家手持逢人配且正在构建不完整牌型时（如已选 `3、4、5、6`），点击"提示"或长按空白区
|
||
- UI 自动将手牌中的逢人配牌弹起并闪烁，提示玩家此牌可补齐当前残缺牌型（如当 `7` 完成顺子）
|
||
- 发生多歧义时（既可补顺子也可补连对），弹出小型选项菜单供玩家选择
|
||
|
||
**卡牌 UI 节点轻量化设计：**
|
||
|
||
- 同屏可能超过 150+ 个卡牌 Control 节点（4 人 × 27 张 + 出牌区 + 历史记录），每个节点挂载独立 Tween/信号监听在低端设备极易掉帧
|
||
- **分级渲染策略：**
|
||
- **暗牌（非玩家手牌）**：仅渲染微缩"数量标签（Label）"或单一共享九宫格动态图，不生成独立的卡牌实体节点
|
||
- **明牌（玩家手牌 + 中央出牌区）**：实例化为独立的 `card_node.tscn`，但禁用不必要的关系检测和碰撞
|
||
- 对局中动态销毁已出牌的节点，复用节点对象池（Object Pool），避免频繁 `instantiate` / `queue_free`
|
||
|
||
**出牌二次确认：**
|
||
- 玩家点击"出牌"按钮后出现确认提示，显示即将打出的牌型和点数
|
||
- 训练模式可选关闭确认，单机/联机默认开启
|
||
- 支持"自动出牌"快捷键：选中牌后双击或按 Enter 直接出
|
||
|
||
**多牌选择交互：**
|
||
- 单击选中/取消单张牌
|
||
- 长按拖拽框选连续区域
|
||
- Ctrl+点击连选多张
|
||
- "提示"按钮一键选中 AI 推荐的最优出牌组合
|
||
|
||
**回合计时与状态屏蔽：**
|
||
- 每回合显示倒计时进度条（默认 30s），超时自动过牌
|
||
- 等待他人出牌时，手牌区灰显 + 禁用操作
|
||
- 出牌结束到下一回合之间显示过渡动画（0.5s），期间屏蔽输入
|
||
|
||
**输入系统冲突裁定：**
|
||
|
||
- 同时存在点击、长按、滑动框选、双击、Ctrl 连选等多种输入方式，需定义冲突优先级：
|
||
- **输入状态机：** `InputFSM` 管理空闲（IDLE）→ 轻触（TOUCH_DOWN）→ 拖动（DRAGGING）→ 长按激活（LONG_PRESS）→ 释放（RELEASED）
|
||
- **Gesture Priority：** 滑动优先于长按（手指移动 >5px 进入 DRAGGING，取消长按计时）；双击 < 300ms 且位移 <5px 判定双击；Ctrl 状态与触摸并存时优先解析为 Ctrl 连选
|
||
- **PC / Mobile 分离输入策略：** 桌面端优先键盘快捷键 + 鼠标操作；移动端优先触摸手势；同一事件不触发双份响应
|
||
|
||
**移动端性能边界：**
|
||
|
||
- **最低目标机型：** iPhone X（2017） / 骁龙 665 中端 Android，保持 ≥ 30 FPS
|
||
- **FPS 目标：** 桌面 ≥ 60 FPS，移动端 ≥ 30 FPS
|
||
- **最大内存占用：** 桌面 < 256MB，移动端 < 128MB
|
||
- **动态降级策略：** FPS 持续 < 20 时自动关闭动画（Tween）、降低卡牌分辨率、减少出牌历史保留轮数
|
||
- **低端机配置开关：** `LOW_PERF_MODE`，关闭粒子特效、阴影、抗锯齿，使用预烘焙卡牌贴图
|
||
|
||
**跨平台适配：**
|
||
|
||
- **分辨率适配：** 支持 16:9、21:9、4:3 主流比例；采用 `Control.anchor` + `Control.expand` 响应式布局
|
||
- **横竖屏：** 强制横屏（landscape），卡牌游戏竖屏无法容纳 27 张手牌
|
||
- **DPI 缩放：** 使用 Godot `Theme` 系统和 `DisplayServer.screen_get_dpi()` 自动调整字体/控件尺寸
|
||
- **安全区（Safe Area）：** 适配刘海屏/挖孔屏，使用 `DisplayServer.get_display_safe_area()` 避让
|
||
- 平板设备使用特殊 UI 布局（更大卡牌、更宽手牌区域）
|
||
|
||
---
|
||
|
||
## 九、数据与序列化
|
||
|
||
**状态哈希校验：** 每局结束计算 `GameState` 的 SHA-256 哈希，客户端和服务器（或双方客户端）比对，防止联机数据篡改。
|
||
|
||
**日志裁剪策略：**
|
||
- `Action` 日志按局分割，开局清空上局日志
|
||
- 单局日志上限 10000 条（约 500 轮出牌），超出自动截断头部
|
||
- 完整日志仅在开启回放录制时保留，写入 `save/records/`
|
||
|
||
**存档格式版本：**
|
||
- 所有序列化数据头部包含 `version: int` 字段
|
||
- 当前版本 V1，后续升级需提供 `migrate_vN_to_vN+1()` 迁移函数
|
||
- 读取存档时校验版本号，不兼容版本提示用户更新
|
||
|
||
**状态重放的随机数种子绑定：**
|
||
|
||
- Action 日志用于回滚/重放时，若涉及 `RESHUFFLE`（洗牌）或 AI 决策中的 PRNG 动作，必须强制绑定该局开局的 `seed` 值
|
||
- 断线重连重放 Action 时，若随机数种子不一致，AI 会产生与掉线前完全不同的决策分支，导致前后端状态彻底跑飞
|
||
- `Action` 日志起始位置记录 `{seed: int, timestamp: int}`，重放时还原相同种子
|
||
- `deck.gd` 的洗牌和 AI 的随机选择全部使用可注入种子的 PRNG
|
||
|
||
**Replay 确定性保证（多平台一致性）：**
|
||
|
||
仅绑定 seed 不足以保证跨平台回放一致，还须满足严格条件：
|
||
- Action 执行顺序绝对固定（按时间戳严格递增，禁止并发 apply）
|
||
- Dictionary 遍历不能参与逻辑（GDScript Dictionary 迭代顺序不保证，改用 Array + 排序）
|
||
- 所有排序必须使用稳定排序算法（`sort_custom` + 稳定比较器）
|
||
- AI 随机源禁止使用系统随机（`randf()` / `randi()`），强制使用种子 PRNG
|
||
- 时间戳不能参与规则逻辑（仅用于日志标记和 UI 动画节奏，不用于状态判定）
|
||
|
||
**数值统计体系：**
|
||
|
||
- 长期统计数据用于匹配、AI 调优和平衡分析：
|
||
- `stats_tracker.gd` 记录每个玩家的：总对局数、胜率、双下率、被双下率
|
||
- AI / 实战统计：平均出牌时长、炸弹使用率、逢人配使用次数、进贡胜率
|
||
- Replay 元数据：对局时长、回合数、局次、规则配置、参与者信息
|
||
- 统计数据存储在 `save/stats/`，格式为结构化 JSON，支持导出分析
|
||
- AI 难度统计分离记录（"L1 胜率" vs "L2 胜率"），辅助 AI 调优
|
||
|
||
---
|
||
|
||
## 十、网络层（预留）
|
||
|
||
**同步模式选型：**
|
||
|
||
| 模式 | 原理 | 适用 |
|
||
|------|------|------|
|
||
| **状态同步（推荐）** | 服务器计算权威状态，客户端接收后渲染 | 回合制卡牌，延迟容忍度高 |
|
||
| 帧同步 | 同步操作指令，各端独立计算 | 实时操作类游戏，此处不适用 |
|
||
|
||
选择状态同步模型，同步频率为每轮出牌结束时触发一次。
|
||
|
||
**客户端作弊防护（Server-Authoritative）：**
|
||
|
||
所有 Action 必须在服务端做权威校验，客户端仅允许发送"意图"：
|
||
|
||
- **非法 Action 注入防范：** 服务端 `validate_action(game_state, action)` 校验每一项 Action，包括：出牌合法性、回合归属、seq_id 连续性
|
||
- **客户端手牌篡改防范：** 客户端不持有完整 GameState，服务端维护权威手牌；客户端只收到自身手牌信息
|
||
- **重放攻击防范：** Action 增加 `seq_id`（严格递增）+ `nonce`（随机盐），服务端拒绝重复 seq_id
|
||
- **Action_seq 回退检测：** 服务端记录每个连接的最后 `ack_seq`，拒绝 < ack_seq 的 Action
|
||
- **客户端伪造 AI 托管结果防范：** 托管由服务端发起，AI 计算在服务端完成；托管期间客户端发送的 Action 一律拒绝
|
||
- **防作弊时效：** 出牌合法性只在服务端最终裁定，客户端可以做本地预判以优化 UI 响应，但服务端结果始终覆盖客户端
|
||
|
||
**联机同步冲突恢复（Authoritative Rollback）：**
|
||
|
||
客户端预测状态与服务端权威状态不一致时的处理：
|
||
|
||
- 客户端每次提交 Action 后，服务端回传 `{action_seq, state_hash}`
|
||
- 客户端比对自身状态的哈希：若一致则确认；若不一致则触发回滚
|
||
- **回滚流程：** 暂停 UI 输入 → 请求从 `action_seq` 开始的全量状态同步 → 重建 UI（手牌重排、出牌区清空重渲染）→ 播放"重同步"过渡动画 → 恢复输入
|
||
- UI 层必须支持**状态全量重建**：接收到新的 `GameStateView` 后完全重建手牌、出牌区、计分板，而非增量 patch
|
||
|
||
**网络协议版本兼容：**
|
||
|
||
- 存档版本（`data_version`）≠ 联机协议版本（`protocol_version`），两者独立管理
|
||
- `protocol_version` 定义在 `NetworkInterface` 中，起手握手阶段交换
|
||
- **客户端最低兼容版本：** `MIN_COMPATIBLE_PROTOCOL`，低于此版本的客户端拒绝连接，提示更新
|
||
- **热更新后的版本协商：** Lobby 阶段交换支持的 protocol 范围，若房主与客户端版本不兼容则显示提示
|
||
- 协议变更需提供 `protocol_migrate_vN_to_vN+1()` 迁移处理
|
||
|
||
**观战一致性：**
|
||
|
||
- **手牌可见性：** 非好友房观战默认隐藏所有手牌，仅显示公共出牌区；好友房可经房主授权后显示队友手牌
|
||
- **延迟观战：** 观战者看到的画面延迟 N 回合（默认 3 回合 / 可配置），防止实时观战泄露信息给对战者
|
||
- **中途加入：** 允许中途加入观战，从加入时刻最近的 `CLEARED` 状态开始重放，不追溯更早回合
|
||
- **透视作弊防护：** 观战者持有独立的 `spectator_view` 视野过滤器，与对局玩家网络通道完全隔离
|
||
- 观战人数上限：每局最多 50 名观战者，超出拒绝新加入
|
||
|
||
**联机状态机正式定义：**
|
||
|
||
完整的房间生命周期状态图，确保 network / game / ui 三层状态同步：
|
||
|
||
```
|
||
创建房间
|
||
↓
|
||
┌───────────────── IDLE ──────────────────┐
|
||
│ ↓ 有人加入 │
|
||
│ WAITING (等待满员) │
|
||
│ ↓ 4人齐 │
|
||
│ READY_CHECK │
|
||
│ ╱ ╲ │
|
||
│ ALL_READY TIMEOUT │
|
||
│ ↓ ↓ │
|
||
│ IN_GAME 返回 WAITING │
|
||
│ ↓ │
|
||
│ ┌─── PLAYING ───┐ │
|
||
│ │ ↓ 掉线 │ │
|
||
│ │ HOSTING │ (托管中) │
|
||
│ │ ↓ 重连 │ │
|
||
│ │ RECONNECTING │ │
|
||
│ │ ↓ │ │
|
||
│ └→ PLAYING ←┘ │
|
||
│ ↓ 对局结束 │
|
||
│ FINISHED │
|
||
│ ↓ │
|
||
│ VOTE_PHASE (投降投票/再开投票) │
|
||
│ ↓ │
|
||
└── IDLE ─────────────────────────────────┘
|
||
↓ 房主解散房间
|
||
DESTROYED
|
||
```
|
||
|
||
**各状态约束：**
|
||
- `PLAYING` → `HOSTING`：心跳超时触发，AI 自动托管，UI 标记托管状态
|
||
- `HOSTING` → `RECONNECTING`：客户端发起重连，服务端追帧
|
||
- `RECONNECTING` → `PLAYING`：状态同步完成，`RECONNECT_GRACE_PERIOD` 内禁止托管出牌
|
||
- `FINISHED` → `VOTE_PHASE`：允许投降投票（联机）/ 下一局投票，对手否决权生效
|
||
- `VOTE_PHASE` → `IDLE`：投票通过或超时，房间解锁
|
||
|
||
**房间与开局条件：**
|
||
- `NET_ROOM_CREATED` → `NET_PLAYER_JOINED` × 4 → `NET_ALL_READY` → `NET_GAME_START`
|
||
- 4 名玩家全部准备后房主点击开局
|
||
- 等待中可设 AI 补位开关
|
||
|
||
**心跳与异常处理：**
|
||
- 客户端每 5s 发送心跳包
|
||
- 服务端 15s 未收到心跳判定断线，触发托管
|
||
- 重连后追帧：客户端发送最后收到的 `action_seq`，服务端补发缺失的 Action 列表
|
||
|
||
**房间锁、准备状态：**
|
||
- 开局后房间上锁，禁止新玩家加入
|
||
- 对局中任意时间仅房主可发起投降投票（需队友同意）
|
||
- 对局结束后房间自动解锁，返回等待状态
|
||
|
||
**断线重连的视野过滤（Vision Filter / Fog of War）：**
|
||
|
||
- 服务端序列化状态发送给特定客户端时，**必须经过视野过滤器**
|
||
- 只打包该玩家有权知道的信息：自身手牌、公共出牌区、已公开的进贡/还贡牌、历史出牌记录
|
||
- **绝对禁止**将包含所有玩家手牌的完整内存对象直接下发，防止抓包窥牌
|
||
- `NetworkInterface` 中实现 `filter_state_for_player(game_state, player_id): GameStateView` 方法，返回裁剪后的可见状态
|
||
|
||
**进贡阶段的动态视野变化：**
|
||
|
||
- 进贡和还贡不是同时发生的：A 进贡给 B 时，B 可见此牌，但 C 和 D 不可见
|
||
- 直到还贡结束或出牌阶段该牌被打出，其他玩家才可见该牌的去向
|
||
- 服务端的 `filter_state_for_player` 必须动态感知 `TRIBUTE_PHASE` 内的"卡牌所有权临时移交状态"
|
||
- 防止联机时外挂通过抓包提前得知他人的进贡牌
|
||
|
||
**投降机制的对手否决权：**
|
||
|
||
- 掼蛋涉及"升 3 级（双下）"和"升 1 级"的巨大差异，一方提前投降会损害对手抓双下的收益
|
||
- 投降不仅需要队友同意，**还必须发起对手接受投票**
|
||
- 流程：发起方 → 队友同意 → 发起对手投票 → 对手两人中至少一人接受 → 投降生效
|
||
- 若对手拒绝投降，游戏必须继续，直至产生实际的名次结算
|
||
- 单机模式中对 AI 可配置投降阈值（如分差 > 100 分），免除投票流程
|