Card Game Engine

主题

CardCombination ​

描述一次牌型组合的结果对象，由 CombinationDetector 产出，供 CombinationComparator 比较。

概述 ​

CardCombination 是 combination 模块的核心数据载体。它把"一组卡牌被识别成什么牌型"这一信息封装为一个不可变的描述对象，使下游的牌型比较器、规则系统无需关心识别细节。

在 CardGameEngine 的 Core 层中，CardCombination 仅承载与具体游戏无关的通用字段（type / cards / rank / value / metadata）；游戏专属字段应放在 metadata 中按约定传递，或通过插件层的专属类型扩展。

该文件仅导出 CardCombination 接口本身，不提供工厂函数。CardCombination 实例由 CombinationDetector.detect() 构造并返回。

属性 ​

属性类型必填说明
typeCombinationType是牌型枚举值，参见 CombinationType
cardsCard[]是该组合所包含的卡牌数组，通常已按点数排序
ranknumber否该组合的点数代表（如对子用对子点数），用于跨组合比较
valuenumber否组合的综合比较值，优先于 rank 用于比较
metadataRecord<string, unknown>否附加上下文，不参与默认比较

字段语义 ​

rank 与 value 的关系 ​

  • rank 与 value 二选一由 Detector 决定。CombinationComparator 默认优先使用 value，回退到 rank，再回退到 0。
  • 对于 SINGLE / PAIR / TRIPLE / FOUR_OF_A_KIND / STRAIGHT，CombinationDetector 会同时设置 rank 与 value 为同一个值（点数代表）。
  • metadata 用于承载 Detector 无法用主属性表达的上下文（如顺子长度、未识别原因等），各游戏可按需约定字段，但不参与默认比较。

metadata 常见字段 ​

由 CombinationDetector.detect() 写入：

  • reason: string —— 当 type 为 UNKNOWN 时给出原因，取值如 'empty'、'too many cards of same rank'、'no matching pattern'。
  • length?: number —— 顺子长度（仅 STRAIGHT）。
  • low?: number —— 顺子最低点数（仅 STRAIGHT）。
  • high?: number —— 顺子最高点数（仅 STRAIGHT）。

注意事项 ​

  • CardCombination 是纯数据接口，不应被调用方手动构造；正确做法是调用 CombinationDetector.detect() 获取。
  • 该接口与具体游戏解耦，游戏专属牌型（如斗地主的飞机、火箭）应在 src/plugins/<game>/combinations/ 下独立扩展，不应在 Core 层增加字段。