Skip to content

Slay the Spire 2 Modding Handbook

This handbook describes the current local modding contract of Slay the Spire 2 and then applies it to one coherent example containing a card, potion, relic, map event, and custom overlay. The game is the primary source: the installed assembly defines behavior, while the main PCK defines resource paths and localization conventions.

Source Hierarchy

  1. release_info.json, sts2.runtimeconfig.json, and the installed assemblies
  2. decompiled implementation in sts2.dll
  3. resources and localization in SlayTheSpire2.pck
  4. runtime logs and a clean installation test
  5. observed release packages and community documentation

This order matters during Early Access. A working pattern from an older release is evidence of what once worked, not proof of the current contract.

Current Baseline

Item Verified value
STS2 version v0.103.3
Commit 460a0ece
Release metadata date 2026-05-29T13:36:05-07:00
Target framework net9.0
Bundled .NET runtime 9.0.7
Main PCK format Godot 4.5.1

The current loader recursively scans <STS2>/mods for JSON manifests. Each manifest owns the directory that contains it and declares whether sibling <id>.dll and <id>.pck files must be loaded. The recommended installation is therefore:

mods/
  MyMod/
    MyMod.json
    MyMod.dll
    MyMod.pck

The PCK is optional for code-only mods. There is no second embedded manifest contract in v0.103.3.

Foundation

  1. 01. Environment Setup
  2. 02. Game Layout And Loader Surface
  3. 03. Project Skeleton, Build, And Manifest
  4. 04. Reverse-Engineering The Game
  5. 05. Behavior Mods, Harmony, And Hooks
  6. 06. Content Infrastructure, Assets, And Localization
  7. 07. Native UI And Runtime Inspection
  8. 08. Debugging And Fast Iteration
  9. 09. Packaging, Installing, And Verifying

Applied Content Tutorial

The following chapters build a small fictional content set called FieldNotes. The name is only a stable namespace for examples; each chapter can be used independently.

  1. 10. Custom Cards
  2. 11. Custom Potions
  3. 12. Custom Relics
  4. 13. Custom Act Events
  5. 14. Custom GUI

The sequence deliberately repeats the same lifecycle:

  1. define a concrete AbstractModel subtype
  2. let ModelDb discover the type from the loaded assembly
  3. place it in the game system that can select it
  4. supply localization and resources under the paths the model resolves
  5. test gameplay, inspect, hover, unlock, and save/load behavior separately

Reference

The tutorial assumes basic familiarity with C#, async methods, Harmony attributes, and the Godot scene tree. It focuses on STS2-specific contracts rather than general language instruction.