sts2-cli

English

A CLI for Slay the Spire 2.

Runs the real game engine headless in your terminal — all damage, card effects, enemy AI, relics, and RNG are identical to the actual game. Everything is unlocked from the start: all characters, cards, relics, potions, and ascension levels — no timeline progression required.

Setup

Requirements:

• Slay the Spire 2 on Steam
• .NET 9+ SDK
• Python 3.9+

git clone https://github.com/wuhao21/sts2-cli.git
cd sts2-cli
./setup.sh # copies DLLs from Steam → IL patches → builds

Or just run python3 python/play.py — it auto-detects and sets up on first run.

Play

python3 python/play.py # interactive (Chinese)
python3 python/play.py --lang en # interactive (English)
python3 python/play.py --ascension 10 # Ascension 10
python3 python/play.py --character Silent # play as Silent

Type help in-game:

 help — show help
map — show map
deck — show deck
potions — show potions
relics — show relics
quit — quit
Map: enter path number (0, 1, 2)
Combat: card index / e (end turn) / p0 (use potion)
Reward: card index / s (skip)
Rest: option index
Event: option index / leave
Shop: c0 (card) / r0 (relic) / p0 (potion) / rm (remove) / leave

JSON Protocol

For programmatic control (AI agents, RL, etc.), communicate via stdin/stdout JSON:

dotnet run --project src/Sts2Headless/Sts2Headless.csproj

{"cmd": "start_run", "character": "Ironclad", "seed": "test", "ascension": 0}
{"cmd": "action", "action": "play_card", "args": {"card_index": 0, "target_index": 0}}
{"cmd": "action", "action": "end_turn"}
{"cmd": "action", "action": "select_map_node", "args": {"col": 3, "row": 1}}
{"cmd": "action", "action": "skip_card_reward"}
{"cmd": "quit"}

Each command returns a JSON decision point (map_select / combat_play / card_reward / rest_site / event_choice / shop / game_over). All names are in English.

Game Logs

Every run is automatically logged to logs/ as a JSONL file (one JSON per line), recording each game state and action with timestamps. Logs older than 7 days are cleaned up automatically.

python3 python/play.py --no-log # disable logging

When filing a bug report, please attach the relevant log file from logs/ — it contains the full step-by-step game state needed to reproduce the issue.

Supported Characters

Character	Status
Ironclad	Fully playable
Silent	Fully playable
Defect	Fully playable
Necrobinder	Fully playable
Regent	Fully playable

Architecture

Your code (Python / JS / LLM)
│ JSON stdin/stdout
▼
src/Sts2Headless (C#)
│ RunSimulator.cs
▼
sts2.dll (game engine, IL patched)
+ src/GodotStubs (replaces GodotSharp.dll)
+ Harmony patches (localization)

中文

杀戮尖塔2的命令行版本。

在终端里运行真实游戏引擎 — 所有伤害计算、卡牌效果、敌人AI、遗物触发、随机数都和真实游戏一致。所有内容从一开始就全部解锁：全角色、全卡牌、全遗物、全药水、全渐进难度等级，无需时间线进度。

安装

需要：

• Slay the Spire 2 (Steam)
• .NET 9+ SDK
• Python 3.9+

git clone https://github.com/wuhao21/sts2-cli.git
cd sts2-cli
./setup.sh # 从 Steam 复制 DLL → IL patch → 编译

或者直接运行 python3 python/play.py，首次会自动完成 setup。

玩

python3 python/play.py # 中文交互模式
python3 python/play.py --lang en # English
python3 python/play.py --ascension 10 # 渐进难度 10
python3 python/play.py --character Silent # 选择静默猎手

游戏内输入 help 查看所有命令：

 help — 帮助
map — 显示地图
deck — 查看牌组
potions — 查看药水
relics — 查看遗物
quit — 退出
地图: 输入编号 (0, 1, 2)
战斗: 输入卡牌编号 / e 结束回合 / p0 使用药水
奖励: 输入卡牌编号 / s 跳过
休息: 输入选项编号
事件: 输入选项编号 / leave 离开
商店: c0 买卡 / r0 买遗物 / p0 买药水 / rm 移除 / leave 离开

角色支持

角色	状态
铁甲战士 (Ironclad)	完全可玩
静默猎手 (Silent)	完全可玩
故障机器人 (Defect)	完全可玩
亡灵契约师 (Necrobinder)	完全可玩
储君 (Regent)	完全可玩

JSON 协议

除了交互模式，也可以通过 stdin/stdout JSON 协议编程控制（写 AI agent、RL 训练等）：

dotnet run --project src/Sts2Headless/Sts2Headless.csproj

{"cmd": "start_run", "character": "Ironclad", "seed": "test", "ascension": 0}
{"cmd": "action", "action": "play_card", "args": {"card_index": 0, "target_index": 0}}
{"cmd": "action", "action": "end_turn"}
{"cmd": "action", "action": "select_map_node", "args": {"col": 3, "row": 1}}
{"cmd": "action", "action": "skip_card_reward"}
{"cmd": "quit"}

每个命令返回一个 JSON decision point（map_select / combat_play / card_reward / rest_site / event_choice / shop / game_over），所有名称为英文。

游戏日志

每局游戏会自动记录到 logs/ 目录下的 JSONL 文件中，包含每一步的游戏状态和操作，附带时间戳。超过 7 天的旧日志会自动清理。

python3 python/play.py --no-log # 关闭日志

提交 bug 报告时，请附上 logs/ 中对应的日志文件 — 它包含了复现问题所需的完整游戏步骤。

架构

你的代码 (Python / JS / LLM)
│ JSON stdin/stdout
▼
src/Sts2Headless (C#)
│ RunSimulator.cs
▼
sts2.dll (游戏引擎, IL patched)
+ src/GodotStubs (替代 GodotSharp.dll)
+ Harmony patches (本地化)