sts2-bot/docs/MOD_SETUP.md

Mod source and Linux setup

The bot pins its STS2MCP fork as a Git submodule at vendor/STS2MCP. The fork is private: your desktop needs SSH access to git.rasyidanaf.com. The upstream project and its MIT license remain in the submodule.

Get both repositories

For a new checkout:

git clone --recurse-submodules git@git.rasyidanaf.com:0xrsydn/sts2-bot.git
cd sts2-bot

For an existing checkout:

git pull --ff-only
git submodule sync --recursive
git submodule update --init --recursive

An old, unmanaged vendor/STS2MCP directory can block initialization. Preserve any local changes by moving that directory outside the checkout before initializing. Do not delete it blindly. Do not use git submodule update --remote for normal setup: that bypasses the revision tested with this bot.

Jujutsu does not populate submodule working trees. After a jj checkout/update, use git submodule update --init --recursive in a colocated repository. Submodule revision changes require Git; ordinary bot changes can continue to use jj.

Build on CachyOS / Linux

Enter the pinned development environment with direnv allow (nix-direnv) or nix develop. It includes .NET SDK 9; see DEVELOPMENT.md. Install the native Linux Steam version of Slay the Spire 2 separately. Check that dotnet --list-sdks lists a 9.x SDK. Set GAME_DIR to the actual Steam library path; custom libraries and Flatpak Steam use different paths.

From the bot repository root:

GAME_DIR="$HOME/.local/share/Steam/steamapps/common/Slay the Spire 2"
test -f "$GAME_DIR/data_sts2_linuxbsd_x86_64/sts2.dll"
dotnet build vendor/STS2MCP/STS2_MCP.csproj -c Release \
  -p:STS2GameDir="$GAME_DIR" -o /tmp/sts2-mcp-build

Outside the shell, prefix the build command with nix develop --command. This uses the repository lock file rather than your machine's nixpkgs registry. Build against your installed game assemblies. A successful Mac build does not prove compatibility with a different Linux game version.

Install with the game closed

Back up existing files before replacing them:

MODS_DIR="$GAME_DIR/mods"
BACKUP_DIR="$HOME/.local/state/sts2-bot/mod-backups/$(date +%Y%m%dT%H%M%S)"
mkdir -p "$MODS_DIR" "$BACKUP_DIR"
for file in STS2_MCP.dll STS2_MCP.json; do
  if [ -f "$MODS_DIR/$file" ]; then cp -p "$MODS_DIR/$file" "$BACKUP_DIR/"; fi
done
cp /tmp/sts2-mcp-build/STS2_MCP.dll "$MODS_DIR/STS2_MCP.dll"
cp vendor/STS2MCP/mod_manifest.json "$MODS_DIR/STS2_MCP.json"

Do not use the historical DLL files in the bot's vendor/ root. They predate this API extension. Keep configuration files and other mods unchanged. Launch the game through Steam and accept mod loading if prompted.

Read-only health check:

curl --fail --silent --show-error 'http://localhost:15526/api/v1/singleplayer?format=json'

At the main menu, no player/deck/reward data is expected. In a run, inspect player.permanent_deck. On a card reward screen, inspect card_reward.alternatives. Do not expose the unauthenticated local API publicly.

Current integration limits

The mod extension builds and passed isolated action-guard tests. On macOS, loading and a main-menu GET were verified. Live deck/alternative serialization and Linux execution still require verification. The bot does not yet consume the new fields. Composite scoring remains opt-in; automatic composite skipping is not implemented.

See the submodule's docs/reward-observations.md for the API contract and the audit for the remaining work.