UnoState

UNO 插件在 GameState 上的 zone id 与 variable key 常量，以及类型安全的访问器函数。

概述

UnoState.ts 集中定义 UNO 插件使用的 zone id 与 variable key，避免在多个 Rule / Handler 中以魔法字符串散落，并提供类型安全的读取入口（getUnoCurrentColor / isPendingColorChoice）。

常量

名称	类型	值	说明
UNO_DECK_ZONE_ID	string	'deck'	牌堆 zone id，存放未发出的牌
UNO_DISCARD_ZONE_ID	string	'discard'	弃牌堆 zone id，存放已打出的牌；最顶张决定下一手的合法颜色 / 牌面
UNO_VAR_CURRENT_COLOR	string	'uno.currentColor'	当前生效颜色的 variable key
UNO_VAR_PENDING_COLOR	string	'uno.pendingColorChoice'	"是否等待玩家指定颜色"的 variable key

UNO_VAR_CURRENT_COLOR 行为

• 实色牌打出后即更新为该牌颜色。
• Wild 牌打出后保持不变，直到玩家通过 CHOOSE_COLOR_ACTION 指定后才更新。
• 翻初始牌时设置为该数字牌的颜色。

UNO_VAR_PENDING_COLOR 行为

• Wild / Wild Draw Four 打出后置为 true，阻塞回合切换。
• CHOOSE_COLOR_ACTION 处理后置回 false。
• setup 时初始化为 false。

方法

getUnoCurrentColor()

function getUnoCurrentColor(state: GameState): UnoColor | undefined

读取当前生效颜色。

参数

名称	类型	说明
state	GameState	引擎当前游戏状态

返回值

UnoColor | undefined：当前颜色；游戏开始翻初始牌之前为 undefined。

行为

直接读取 state.variables[UNO_VAR_CURRENT_COLOR] 并断言为 UnoColor | undefined。

isPendingColorChoice()

function isPendingColorChoice(state: GameState): boolean

是否正在等待玩家为刚打出的 Wild 牌指定颜色。

参数

名称	类型	说明
state	GameState	引擎当前游戏状态

返回值

boolean：UNO_VAR_PENDING_COLOR === true 时返回 true。

行为

用于 CHOOSE_COLOR_ACTION 的合法性校验（见 chooseColorValidRule）：仅在 pending === true 时允许该 Action。

示例

import { GameEngine, TurnPlugin, DrawPlugin } from 'decklet'
import {
  UnoPlugin,
  UNO_DECK_ZONE_ID,
  UNO_DISCARD_ZONE_ID,
  UNO_VAR_CURRENT_COLOR,
  UNO_VAR_PENDING_COLOR,
  getUnoCurrentColor,
  isPendingColorChoice
} from 'decklet/uno'

const engine = new GameEngine()
engine.use(TurnPlugin).use(DrawPlugin).use(UnoPlugin)
engine.createGame({
  players: [
    { id: 'p1', name: 'Alice', seat: 1 },
    { id: 'p2', name: 'Bob', seat: 2 }
  ]
})
engine.start()

const state = engine.getState()

// 通过常量直接访问
const deckCount = state.zones[UNO_DECK_ZONE_ID]!.cards.length
const discardTop = state.zones[UNO_DISCARD_ZONE_ID]!.cards.at(-1)
const currentColor = state.variables[UNO_VAR_CURRENT_COLOR]
const pending = state.variables[UNO_VAR_PENDING_COLOR] === true

// 通过访问器函数（类型安全）
const color = getUnoCurrentColor(state) // UnoColor | undefined
const awaiting = isPendingColorChoice(state) // boolean

console.log({ deckCount, discardTop, currentColor, pending, color, awaiting })

注意事项

• UNO_DECK_ZONE_ID / UNO_DISCARD_ZONE_ID 与 DrawPlugin 的抽牌堆重洗策略配合：setup 中将 DRAW_VAR_RESHUFFLE_FROM 设为 UNO_DISCARD_ZONE_ID，抽牌堆耗尽时从弃牌堆回收洗回（保留顶张）。
• 这些常量同时也被 UnoStateSerializer（Server 序列化器）用于构造对外 PublicGameState 的 table 字段。
• getUnoCurrentColor / isPendingColorChoice 仅做读取与类型断言，不会修改状态。