PokerRulesPlugin

把通用 combination 系统（CombinationDetector / DefaultCombinationComparator / RankResolver）以 variable 形式注入到 state.variables 的插件。

概述

PokerRulesPlugin 位于 src/plugins/PokerRulesPlugin.ts。它本身不实现任何 Action handler 或 Rule，而是在 setup 阶段将通用的牌型识别、比较、点数解析器注入到 state.variables 中，供后续的 Rule 与 Action handler 通过 getter 函数取用。

这种"variable 注入"模式让游戏专属 Rule 可以独立地引用通用的牌型系统，而无需在每个 Rule 中重新构造 detector / comparator 实例。

导出

POKER_RULES_VARIABLES

Poker 规则在 state.variables 中使用的 key 集合。

export const POKER_RULES_VARIABLES = {
  detector: 'poker.detector',
  comparator: 'poker.comparator',
  resolver: 'poker.resolver'
} as const

字段	值	说明
detector	'poker.detector'	牌型检测器（CombinationDetector）的 variable key
comparator	'poker.comparator'	牌型比较器（DefaultCombinationComparator）的 variable key
resolver	'poker.resolver'	点数解析器（RankResolver，可选）的 variable key

PokerRulesPluginOptions

createPokerRulesPlugin 的可选项。

export interface PokerRulesPluginOptions {
  resolver?: RankResolver
  minStraightLength?: number
}

字段	类型	必填	说明
resolver	RankResolver	否	自定义点数解析器；不传则使用默认解析
minStraightLength	number	否	顺子所需的最小长度

getPokerDetector()

从 context 读取已注入的牌型检测器；未注入时返回 undefined。

function getPokerDetector(ctx: {
  getVariable<T>(key: string): T | undefined
}): CombinationDetector | undefined

参数

参数	类型	必填	默认值	说明
ctx	{ getVariable<T>(key: string): T | undefined }	是	—	提供按 key 读取 variable 的上下文（如 GameContext 或 RuleContext）

返回值

CombinationDetector | undefined：注入的检测器实例；未注入则返回 undefined。

getPokerComparator()

从 context 读取已注入的牌型比较器；未注入时返回 undefined。

function getPokerComparator(ctx: {
  getVariable<T>(key: string): T | undefined
}): DefaultCombinationComparator | undefined

参数

同 getPokerDetector。

返回值

DefaultCombinationComparator | undefined：注入的比较器实例；未注入则返回 undefined。

getPokerResolver()

从 context 读取已注入的点数解析器；未注入时返回 undefined。

function getPokerResolver(ctx: {
  getVariable<T>(key: string): T | undefined
}): RankResolver | undefined

参数

同 getPokerDetector。

返回值

RankResolver | undefined：注入的解析器；未注入（即创建插件时未传 resolver）则返回 undefined。

createPokerRulesPlugin()

创建 PokerRulesPlugin。setup 幂等地注入 Detector / Comparator / Resolver（回放模式下 setup 会再次执行，故每个 variable 写入前都做存在性检查）。

function createPokerRulesPlugin(options: PokerRulesPluginOptions = {}): GamePlugin

参数

参数	类型	必填	默认值	说明
options	PokerRulesPluginOptions	否	{}	可选项

返回值

GamePlugin：配置好的 PokerRulesPlugin 实例。

行为（setup）

1. 若 variables['poker.detector'] 未设置，写入 new CombinationDetector({ resolver: options.resolver, minStraightLength: options.minStraightLength })。
2. 若 variables['poker.comparator'] 未设置，写入 new DefaultCombinationComparator()。
3. 若 options.resolver 已传且 variables['poker.resolver'] 未设置，写入 options.resolver。

三个写入均做了存在性检查，保证幂等性。

返回的插件字段

字段	值	说明
id	'poker-rules'	插件唯一标识
name	'Poker Rules'	插件名
version	'1.0.0'	插件版本
setup	注入 detector / comparator / resolver	见上
rules / actions / events	无	未定义

PokerRulesPlugin

使用默认选项创建的 PokerRulesPlugin 实例（即 createPokerRulesPlugin() 的返回值）。

export const PokerRulesPlugin: GamePlugin = createPokerRulesPlugin()

示例

默认配置

import { GameEngine } from 'decklet'
import {
  PokerRulesPlugin,
  StandardDeckPlugin
} from 'decklet/plugins'

const engine = new GameEngine({ seed: 42, gameId: 'g1' })
engine.use(StandardDeckPlugin)
engine.use(PokerRulesPlugin)

engine.createGame({ players: [...] })
// setup 阶段：
//   variables['poker.detector'] = new CombinationDetector()（默认 StandardPokerRankResolver，minStraightLength=5）
//   variables['poker.comparator'] = new DefaultCombinationComparator()
//   'poker.resolver' 未设置（未传 options.resolver）

自定义配置

import { LowAceRankResolver } from 'decklet'
import { createPokerRulesPlugin } from 'decklet/plugins'

const plugin = createPokerRulesPlugin({
  resolver: new LowAceRankResolver(),
  minStraightLength: 3
})
// setup 阶段：
//   variables['poker.detector'] = new CombinationDetector({ resolver: LowAceRankResolver, minStraightLength: 3 })
//   variables['poker.comparator'] = new DefaultCombinationComparator()
//   variables['poker.resolver'] = new LowAceRankResolver()

在 Rule / Action handler 中使用

import { createCard } from 'decklet'
import {
  getPokerDetector,
  getPokerComparator
} from 'decklet/plugins'

const myRule = {
  id: 'can-beat',
  name: 'Can Beat',
  appliesTo: ['PLAY_CARD'],
  validate(c) {
    const detector = getPokerDetector(c)
    const comparator = getPokerComparator(c)
    if (!detector || !comparator) {
      return deny('poker rules not installed', 'NO_POKER_RULES')
    }
    // detector.detect(cards) / comparator.compare(a, b) ...
    return ok()
  }
}

注意事项

• 该插件未定义 rules / actions / events；它只负责把 detector / comparator / resolver 放进 variables，由后续 Rule 与 Action handler 通过 getPokerDetector / getPokerComparator / getPokerResolver 取用。
• setup 严格幂等：每次写入前都做存在性检查，回放模式下 setup 重复执行不会重新构造 detector / comparator 实例。
• poker.resolver 仅在创建插件时传入了 options.resolver 才会被注入；不传时该 key 不存在，getPokerResolver 会返回 undefined。注意：detector 内部仍可能使用 options.resolver（如传入了），但 getPokerResolver 仅返回显式注入的 resolver。
• 该插件的 id 为 'poker-rules'；不可在同一 PluginManager 中重复注册。