Splendor RL

强化学习环境与工具集合，基于桌游 Splendor 的规则实现与训练脚本。

本仓库包含：

• 核心规则实现与环境封装（splendor_rl/env/）
• 训练与评测脚本（splendor_rl/train/）——包含 PPO / IPPO 的训练入口与自博弈池
• 基线对手与 UI（splendor_rl/env/bots、splendor_rl/ui/）
• 配置与卡牌/贵族数据（splendor_rl/configs/）
• 单元测试（splendor_rl/tests/）

目的是为强化学习算法提供一个规则严谨、可测试、并能与 PettingZoo 类似接口配合使用的多玩家环境。

快速开始

建议在虚拟环境中运行（示例使用 Windows PowerShell）：

# 创建并激活虚拟环境（Windows PowerShell）
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -U pip
# 安装项目为可编辑包（会根据 pyproject.toml 安装依赖）
pip install -e .

如果你使用 conda，也可以使用仓内提供的 environment.yml：

conda env create -f environment.yml
conda activate splendor

运行 CLI 交互对战

仓内提供了一个简易 CLI，用于两人或四人对战与回放保存：

python -m splendor_rl.ui.cli_play

说明：CLI 会打印当前状态并列出可选动作。最近的交互已支持按类别分组动作与数字索引选择；若筹码超限，会列出所有一次性弃筹（discard_*）组合供选择。

训练与评测

训练入口（PPO/IPPO）位于：

• splendor_rl/train/ppo_ippo.py
• splendor_rl/train/selfplay_pool.py（自博弈池）
• splendor_rl/train/eval_arena.py（评测）

示例运行（根据具体 config 调整）：

python -m splendor_rl.train.ppo_ippo --config splendor_rl/configs/train_4p_full.yaml
python -m splendor_rl.train.eval_arena --model checkpoints/step_2000k.pt --opponent greedy --episodes 200

配置文件

主要配置位于 splendor_rl/configs/：

• cards_tiers.yaml：卡牌分层及信息
• nobles.yaml：贵族信息（本项目统一采用顶层 nobles: 列表格式）
• train_*.yaml, eval.yaml：训练/评测参数

环境与规则实现

核心文件：

• splendor_rl/env/splendor_core.py：规则引擎、动作/回合逻辑、弃筹与贵族结算等。
• splendor_rl/env/components.py：Card/Noble/Deck/BoardState 的数据结构与加载函数。
• splendor_rl/env/state_codec.py：观察/动作编码、掩码生成（训练使用）。

几处实现说明：

• 弃筹逻辑：玩家执行每次动作后，若筹码总数超过 10，环境会强制进入一次性弃筹流程。legal_actions 会在超限时返回所有合法的 discard_* 组合（一次性弃到 10 个），step 会优先解析并执行 discard_...。
• 贵族（Nobles）：初始化时会对 nobles 列表洗牌并从中按玩家数抽取（num_players + 1 个）；贵族只能被未被其他玩家获得的玩家触发领取。
• 卡组（Decks）：在 reset 时会根据给定 seed 洗牌，保证可复现性。

测试

运行项目内的单元测试（pytest）：

pytest -q

目录结构（概要）

splendor/
├─ splendor_rl/
│  ├─ env/
│  │  ├─ components.py
│  │  ├─ splendor_core.py
│  │  ├─ state_codec.py
│  │  └─ bots/
│  ├─ train/
│  ├─ ui/
│  └─ configs/
├─ tests/
├─ environment.yml
├─ pyproject.toml
└─ README.md