STS2 AI Agent

https://github.com/user-attachments/assets/89353468-a299-4315-9516-e520bcbfbd4b

In-Game AI Companion & Autonomous Gameplay Mod for Slay the Spire 2

中文说明 (README.zh-CN) • Current Status • Historical Co-op Evidence • API Docs • MCP Tools Guide

🌟 Key Highlights

• 🎮 In-Game Overlay UI: Press F8 at any time to open the configuration and control window directly inside the game—no external browser required.

• 🤖 OpenAI-Compatible Endpoints: Configure a compatible chat-completions endpoint, with per-model thinking settings. Tool calling, vision, streaming, and usage reporting depend on the provider and model; test chat and play separately.

• 🃏 Autonomous Auto-Play: Uses text state for combat, card drafting, shops, events, pathing, and capstones, with optional screenshot context. Run completion and strategy quality depend on the model and game conditions; see the current status for validation limits.

• 👥 Local Co-op AI Teammate: One-click launch from the main menu spins up an isolated second game instance. You play your character; the AI teammate plays its own character in co-op mode.

• 💬 Live Team Conversation: Talk to your AI teammate in natural language from the human window (e.g., "focus the right cultist", "let's take the shop path"). The AI replies and uses recent context in subsequent decisions.

• 🛡️ Session Budget Guards & Fault Recovery: Tracks reported token usage and request counts, stops new calls when session limits are reached, and bounds retries. Missing usage is shown as unknown; these guards are not a billing guarantee.

• 🔌 Developer-Ready: Built-in local HTTP API (:8080). The overlay Connect tab can expose MCP at /mcp on the same port for Cursor, Claude, and Codex.

Related MCP server: MCPGTCG

🚀 3-Minute Quick Start (Players)

The easiest way to play is the Steam Workshop page. Subscribe, wait for the download, then Steam → Play with Mods. You do not copy any files. That page is a short player guide; this README has extra detail if you need it.

This mod is still in development. Some things may be unfinished or break. Please send suggestions and issues here: GitHub Issues.

Step 1: Install The Mod

Option A: Steam Workshop (recommended)

1. Subscribe on the Workshop page and wait for the download.

2. Start the game from Steam with Play with Mods. You do not copy any files.

3. If the game warns that the code is untrusted: accept, quit fully, enable STS2 AI Agent in Mods, then restart.

Option B: GitHub zip

1. Download sts2-ai-agent-v*-windows.zip from GitHub Releases and unzip it.

2. Copy only these three files from the zip mod/ folder into the game mods/ folder (create it if needed):

   STS2AIAgent.dll
   STS2AIAgent.pck
   mod_id.json

3. Final layout example:

   C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\STS2AIAgent.dll
   C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\STS2AIAgent.pck
   C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\mod_id.json

   Do not copy the whole zip or mcp_server/ into mods/. mcp_server/ is optional for developers.

Do not double-install: if you already subscribed on Workshop and also copied GitHub files, delete the manual copies from mods/ and keep the Workshop item. Two copies can load twice.

Step 2: Launch The Game & Open The Overlay

1. Start Slay the Spire 2 from Steam with Play with Mods.

2. Press F8 (configurable) or click the grey AI tab on the right edge of the screen to open the Agent window.

Step 3: Configure Your LLM Endpoint

1. The overlay opens automatically on first launch. Later, press F8 or click AI. A default URL plus model name is not treated as ready.

2. Open Settings:

   1. Add Endpoint (name, Base URL; API Key may be empty for Ollama / LM Studio)

   2. Add Model and bind it to that endpoint

   3. Choose Chat Model and Play Model (empty play model uses chat)

   4. Click Test Connection (sends a request to your configured service). Chat success is not play success.

   5. Click Save Settings. Unsaved edits are saved when you leave the tab so they are not dropped silently.

3. Thinking intensity, vision, and session budgets are under Show advanced options.

4. Invite a teammate only after the play model shows connectivity success.

Step 4: Play!

Option A: Auto-Play

• Start a standard single-player run.

• Switch to the Play tab and click Start Auto-Play (or Step Once).

• The model evaluates live state and dispatches cards, rewards, and route decisions autonomously.

Option B: Co-op With An AI Teammate (Recommended!)

• Go to the game's Main Menu.

• Switch to the AI Teammate tab and click Invite AI Teammate.

• A second game window will launch automatically and join the co-op lobby. You play your character; the AI controls its character!

• The main window shows whether the teammate is connected, waiting on you/the game/the model, or why it stopped and what to click next. Pause teammate gives immediate feedback; already submitted actions still finish.

• Use team chat to coordinate in plain English or Chinese.

• By default the teammate takes the preselected character and readies up by itself. To pick its character yourself (in the teammate window, or through the companion API with select_character then embark), set companionAutoSelectCharacter to false in the mod's settings.json; the teammate then waits on the character screen without a timeout.

🎮 Core Features

1. Autonomous Gameplay (Auto-Play)

• Compact State Engine: Actionable text state covering cards, energy, intents, relics, HP, and potion slots. Vision is optional; offline state and action tests do not prove full-run completion.

• Optional Vision Augmentation: When using a vision-capable model, screenshots are captured on demand to provide rich visual context.

• Real-Time Counters: The overlay displays prompt, completion, total tokens, and request counts live.

2. Dual-Instance Local Co-op

• Zero-Collision Isolation: Propagates --force-steam off and increments clientId in offline mode. Automatically derives and clones settings.companion.json so both instances never write over each other's configurations or save slots.

• Team Conversation:

  • Chat directly with the AI teammate during multiplayer runs.

  • Teammate replies using its play model, and recent discussions inform subsequent play decisions.

  • Read-only safety: The chat interface never plays cards for the human or unpauses a paused companion.

  • Conversation is player-initiated by default. An optional, off-by-default proactive chat lets the teammate speak one short line when a fight starts and ends, with a selectable tone (轻松搭档 / 沉稳参谋 / 简短简报). It never plays for you and stays under the session budget.

3. Interactive In-Game Advisor

• Use the Chat tab to ask strategic advice.

• Enable "Attach State" to pass full live game context (deck, relics, route) to the model for tactical guidance.

🛡️ Reliability & Safety Guards

🛠️ Advanced Users & Developers Guide

System Architecture

┌───────────────────────────────────────────────────────────┐
│                    Slay the Spire 2                       │
│  ┌─────────────────────────────────────────────────────┐  │
│  │             STS2AIAgent (C# Mod)                    │  │
│  │  - Godot In-Game Overlay UI (F8)                    │  │
│  │  - OpenAI-compatible Client & Budget Guard          │  │
│  │  - Autoplay Decision Loop & Recovery Controller     │  │
│  │  - GameThread Action / State Synchronizer           │  │
│  │  - Local Dual-Instance Process Launcher             │  │
│  └───────────────────────┬─────────────────────────────┘  │
└──────────────────────────┼────────────────────────────────┘
                           │ Local HTTP API (:8080)
                           │ Optional MCP (:8080/mcp)
                           ▼
        External Agents (Cursor / Claude Desktop / Codex)

Local HTTP API

The mod runs an embedded HTTP server on http://127.0.0.1:8080 (with dynamic fallback on port contention):

• GET /health: Health check, returns api_port, instance_role, mcp_enabled, and process PID.

• GET /state: Full raw game state JSON.

• GET /actions/available: Currently available legal actions and schema.

• GET /events/stream: Real-time SSE stream for game events.

• POST /action: Dispatch an action (e.g., play_card, choose_map_node, proceed).

• GET /data/{collection}: Export a bundled game metadata collection (cards, relics, monsters, potions, events, powers, characters).

• POST /session/control: Start or pause autoplay for this instance ({"running": true|false}).

• POST /companion/control / POST /companion/message: Control or message the AI teammate instance (local dual-instance only).

• POST /mcp: Optional MCP (Streamable HTTP). Off by default; enable it on the overlay Connect tab.

Which MCP entry to use

External clients: F8 → Connect → enable Open MCP service → copy the URL or JSON. It shares the HTTP API port and listens on 127.0.0.1 only. Do not hard-code 8080 or 8765.

The Python sidecar is not required for players and is not the recommended entry.

Default shape (replace the port with the one on the Connect tab):

{
  "mcpServers": {
    "sts2-ai-agent": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Built-in MCP tools add health_check on top of the surface in-game Auto-Play uses: get_game_state, get_available_actions, act, get_game_data_*, wait_until_actionable.

In-game Auto-Play already follows the bundled play contract. If you drive the game from an external agent over MCP (Cursor, Claude, Codex, or the optional Python sidecar), also load the companion skill sts2-mcp-player. Connecting tools without that skill can click legal actions; the skill is what matches in-game play quality.

🧪 Building From Source & Automated Testing

Standalone core and MCP contract tests run without the game client. Godot UI, real-game actions, multiplayer, saves, and installation channels require separate live validation:

The GitHub zip includes only the optional sidecar launch and profile-check scripts under scripts/. The build, preflight, and live-game commands below require a source checkout.

Build Mod

⚠️ Close the game first so the DLL file is not locked by the OS.

# Windows
powershell -ExecutionPolicy Bypass -File ".\scripts\build-mod.ps1" -Configuration Release

# Linux / macOS
./scripts/build-mod.sh --configuration Release

Run Tests

• C# Core Unit Tests:

  dotnet run --project STS2AIAgent.Tests/STS2AIAgent.Tests.csproj

  Covers the session budget guard, autoplay recovery backoff, run-boundary interception, offline dual-instance isolation, HTTP port fallback, and native save switching, among others.

• Python MCP Contract Tests:

  cd mcp_server
  uv run python -m unittest discover -s tests -v

• Full Release Preflight Check:

  powershell -ExecutionPolicy Bypass -File ".\scripts\preflight-release.ps1"

❓ FAQ

Q1: Pressing F8 does not open the overlay.

1. Workshop: start with Play with Mods. GitHub: copy the three files from the zip mod/ folder into the game mods/ folder. Do not keep both Workshop and a manual copy.

2. Confirm files were copied into the Steam game installation directory, not the repository directory.

3. Look for the grey AI tab on the right screen edge and click it directly.

Q2: Autoplay stopped unexpectedly. How do I resume?

1. Read the AI Teammate status line and the suggested next click. Config errors do not retry forever; fix settings, test, then Resume play without restarting the whole game.

2. If tokens show unknown, the provider omitted usage; that is not a zero spend. Request caps still work.

3. Use Export diagnostics. The copy excludes API keys, Authorization headers, and session tokens, and does not include chat bodies by default.

Q3: Dual-instance companion window fails to start.

1. Local co-op runs through the internal multiplayer test lobby.

2. The launcher sets --force-steam off and steps clientId automatically. Check if third-party antivirus software blocked launching the child process.

3. If ports are in use, the mod automatically selects an available fallback port.

📁 Repository Layout

STS2-Agent/
├── STS2AIAgent/          # C# In-Game Mod (Overlay UI, LLM Client, Decision Loop, Budget Guard)
├── STS2AIAgent.Tests/    # Standalone C# tests (no game client required)
├── mcp_server/           # FastMCP Server implementation
├── scripts/              # Build, packaging, startup, and preflight scripts
├── skills/               # State-first gameplay skill specifications
├── docs/                 # Developer reference and API documentation
├── PRODUCT_PLAN_CURRENT.md # Current product status and evidence boundary
└── COOP_DELIVERY.md      # Historical co-op evidence index

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).