STS2-RitsuLib

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.

What It Covers

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]

Install

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.

Package Choices

Every runtime package installs one complete mods/STS2-RitsuLib/ folder. Its root STS2-RitsuLib.dll is the loader. Common code, reusable UI, and settings live in shared/; the compatibility facade and game integration live in compat/<api-version>/. A variant pack includes several API versions while storing shared modules once. Install the whole folder, including both subdirectories and the module manifest; copying only the root DLL is insufficient.

Images, translations, and bundled themes are distributed in the installation's assets.zip, shared across game versions. Keep this archive with the runtime, including development Debug builds.

Your NuGet package reference and existing namespaces remain supported. NuGet supplies all compile-time modules, and the compatibility facade forwards existing public types for previously compiled mods. Manual assembly references must include the facade, Runtime, Shared, Ui, and Settings DLLs from the same package. Reflection that enumerates a single assembly must account for types now belonging to separate assemblies.

For directory references, import the installation's RitsuLib.References.props to add all five assembly references. A single-version installation selects its only target automatically. For a bundle, set the compile-time target first:

<PropertyGroup>
    <RitsuLibReferenceTarget>0.111.0</RitsuLibReferenceTarget>
</PropertyGroup>
<Import Project="path/to/STS2-RitsuLib/RitsuLib.References.props" />

These references do not copy the framework into your mod directory; install the complete runtime separately.

Reusable controls, layout containers, shell themes, and toasts are provided by the UI module without a Settings assembly dependency. New general-purpose entry points include RitsuControlFactory, RitsuVerticalStack, and RitsuFixedWidthScrollContent; existing ModSettings* control names remain available for compatibility.

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.

Main Entry Points

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.

Documentation

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

SlayTheSpire2 Modding Tutorials

Related Libraries

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.

Optional Analyzer

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 (Miooowo.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.

Contributing

See the contribution guide for development setup, code and public API conventions, validation, and pull request preparation.

The library uses standard .NET Debug and Release configurations. GodotSharp and its source generators are explicit dependencies; building RitsuLib does not require a Godot project, editor, or export workflow.

Acknowledgements

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

License

MIT