Shared framework library for Slay the Spire 2 mods.

Documentation | Releases | Chinese README

RitsuLib gives mod authors a stable layer for content registration, lifecycle hooks, Harmony patching, persistence, settings UI, localization, audio, runtime UI, diagnostics, and compatibility helpers. It sits beside the base game API and other libraries such as BaseLib instead of replacing them.

flowchart LR
    Mod[Your mod] --> NuGet[STS2.RitsuLib NuGet]
    Mod --> Manifest[mod_manifest dependency]
    Manifest --> Runtime[STS2-RitsuLib runtime mod]
    Runtime --> Registries[Content and UI registries]
    Runtime --> Lifecycle[Lifecycle and patching]
    Runtime --> Data[Persistence and settings]
    Runtime --> Diagnostics[Diagnostics and compatibility]

Add the NuGet package to your mod project:

<PackageReference Include="STS2.RitsuLib" />

Then declare the runtime dependency in mod_manifest.json.

For game API 0.105.x and newer, use the object form:

{
  "dependencies": [
    { "id": "STS2-RitsuLib" }
  ]
}

For older game API branches, use the legacy string form because older manifest parsers may fail on dependency objects:

{
  "dependencies": [
    "STS2-RitsuLib"
  ]
}

If your project does not use Central Package Management, let your package manager or IDE choose the current compatible package version instead of copying a pinned version from this README.

The variant pack installs one mods/STS2-RitsuLib/ folder. Its root STS2-RitsuLib.dll is a loader, while the API-specific builds live under lib/<api-version>/. This only changes how players install the runtime mod; it does not change your compile-time NuGet reference.

The main STS2.RitsuLib package follows the highest Slay the Spire 2 API supported by this repository. Because the game's highest API is often on a beta branch, use a compat package when your mod is meant for another public game branch.

Most mods start from these APIs:

Minimal content-pack registration:

RitsuLibFramework.CreateContentPack("MyMod")
    .Card<MyCardPool, MyStrike>()
    .Relic<MyRelicPool, MyStarterRelic>()
    .Apply();

Start with the getting-started guide, then use the topic pages for the feature you are adding.

RitsuLib's own docs are concise feature references. For a broader Chinese walkthrough of Slay the Spire 2 modding, use:

SlayTheSpire2 Modding Tutorials

Original repository for this tutorial: GlitchedReme/SlayTheSpire2ModdingTutorials

For minion, summon, companion-card, or guardian-style mechanics, prefer MinionLib. It focuses on creating and summoning minions, minion actions, minion-card interactions, guardian behavior, custom targeting, and minion positioning. RitsuLib remains the general framework layer and does not try to replace that specialized library.

The old companion analyzer STS2-ModAnalyzers-RitsuLib (STS2.ModAnalyzers.RitsuLib) is archived and no longer maintained.

For RitsuLib-style mods, the recommended optional analyzer is STS2RitsuLibModAnalyzers (Nothing.STS2RitsuLib.ModAnalyzers). It provides Roslyn diagnostics for RitsuLib localization and resource paths, and its package can automatically pass common project files to the analyzer through buildTransitive.

This analyzer is provided, maintained, and supported by a third party. RitsuLib does not guarantee that it fully matches current RitsuLib capabilities or that all analyzer behavior is correct.

Use local.props.template to point the project at a Slay the Spire 2 install or API signature folder. RitsuLib is a DLL-only mod (has_pck: false), so normal validation is a DLL build for each declared compatibility target.

See ACKNOWLEDGEMENTS.md for the people and users who helped shape RitsuLib.

MIT