xiaji/game-cards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
game-cards/docs/superpowers/specs/2026-05-28-guandan-card-game-design.md
xiaji 865eca98c0 Add Guandan card game design spec (v1.0)
2026-05-28 23:29:43 +08:00

50 KiB
Raw Permalink Blame History

掼蛋卡牌游戏 — 设计规格

日期： 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 分），免除投票流程
Reference in New Issue View Git Blame Copy Permalink