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.

Tested with v0.111.0 (Steam public-beta, build 24724944). After updating the installed game in Steam, rerun ./setup.sh to refresh the engine DLLs, patches, and official English/Chinese localization, then rebuild. Other game versions may require adapter changes.

For a compatibility check, run python3 python/play_full_run.py 5 Ironclad (repeat for Silent, Defect, Regent, and Necrobinder). A completed run reaches victory or defeat; crashes, stalls, and timeouts return a nonzero exit code.

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

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。

已验证 v0.111.0（Steam public-beta，构建 24724944）。通过 Steam 更新游戏后， 请重新运行 ./setup.sh，同步游戏 DLL、补丁和官方中英文文本并重新编译。 其他游戏版本可能需要修改适配代码。

可运行 python3 python/play_full_run.py 5 Ironclad 检查兼容性，并依次替换为 Silent、Defect、Regent、Necrobinder。“完成”指正常胜利或死亡；崩溃、卡住和超时 会返回非零退出码。

玩

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 离开

角色支持

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 (本地化)