RitsuLib

https://sts2-ritsulib.ritsukage.com/guide/
Admin
RitsuLib is a modding framework and runtime library for Slay the Spire 2 that provides APIs for...
Tokens:66,283
Snippets:460
Trust Score:5.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install STS2.RitsuLib Package

Source: https://sts2-ritsulib.ritsukage.com/guide/getting-started

Add the package reference to your mod project.

```xml
<PackageReference Include="STS2.RitsuLib" />
```

--------------------------------

### Create I18N instance with CreateModLocalization and example zhs.json (Chinese)

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Chinese version of the I18N creation example. The JSON file shows the expected format for the Chinese localization file (zhs.json).

```csharp
var i18n = RitsuLibFramework.CreateModLocalization(
    modId: "MyMod",
    instanceName: "settings",
    pckFolders: ["res://MyMod/localization/settings"]);

var label = i18n.Get("settings.enabled", "启用");
```

```json
{
  "settings.enabled": "启用"
}
```

--------------------------------

### Register a Secondary Resource

Source: https://sts2-ritsulib.ritsukage.com/guide/secondary-resources

Use RitsuLibFramework.GetSecondaryResourceRegistry to declare a new combat resource. This example demonstrates setting up a resource with a maximum amount, turn-start reset policy, and custom icons.

```csharp
var resources = RitsuLibFramework.GetSecondaryResourceRegistry("MyMod");

var charge = resources.Register("charge", new SecondaryResourceDefinition(
    defaultAmount: 0,
    baseMaxAmount: 3,
    turnStartPolicy: SecondaryResourceTurnStartPolicy.ResetToMax,
    persistencePolicy: SecondaryResourcePersistencePolicy.Combat,
    smallIconPath: "res://MyMod/assets/ui/charge_small.png",
    largeIconPath: "res://MyMod/assets/ui/charge_large.png")
{
    ClampToMaxAmount = true,
});
```

--------------------------------

### Architect dialogue example

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Example JSON for Architect dialogue with a mod character. Uses `THE_ARCHITECT.talk.<CHARACTER_ENTRY>.*` keys. Optional `-attack` values are `None`, `Player`, `Architect`, or `Both`; optional `-visit` keys can override the visit index; explicit `-startattack` and `-endattack` keys set `StartAttackers` and `EndAttackers` respectively.

```json
{
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-0.char": "The exit is yours, but the cost is mine.",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-1.ancient": "Then pay precisely.",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-attack": "Both"
}
```

--------------------------------

### Architect dialogue with startattack/endattack/visit

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Example JSON for Architect dialogue with explicit `-startattack`, `-endattack`, and `-visit` keys. `-startattack` sets `StartAttackers`, `-endattack` sets `EndAttackers`, and `-visit` overrides the visit index.

```json
{
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.1-startattack": "Player",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.1-endattack": "Both",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.1-visit": "3"
}
```

--------------------------------

### Manage Looping Audio Handles

Source: https://sts2-ritsulib.ritsukage.com/guide/fmod-and-audio

Use PlayLoop to start looping audio and retain the returned handle to adjust parameters or stop playback later.

```csharp
var loop = GameAudioService.Shared.PlayLoop(
    AudioSource.Event("event:/MyMod/ambience/engine"),
    new AudioPlaybackOptions
    {
        Routing = new AudioRoutingOptions(Channel: "my_mod_ambience"),
        Scope = AudioLifecycleScope.Run,
    });

loop?.TrySetParameter("danger", 0.5f);
loop?.TryStop();
```

--------------------------------

### Mod ancient dialogue example

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Example JSON for a mod ancient talking to a mod character. Uses `MY_MOD_ANCIENT_MIRROR` and `MY_MOD_CHARACTER_SEER` entries, with a repeating dialogue using `r` after the line index. `ModAncientEventTemplate` reads `{ancient}.talk.firstVisitEver.*` for the first visit ever, `{ancient}.talk.<CHARACTER_ENTRY>.*` for a specific character, and `{ancient}.talk.ANY.*` for character-agnostic fallback.

```json
{
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-0.ancient": "You brought a future with you.",
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-0.next": "Continue",
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-1.char": "Then I should spend it carefully.",

  "MY_MOD_ANCIENT_MIRROR.talk.ANY.0-0r.ancient": "Again, a face in the glass.",
  "MY_MOD_ANCIENT_MIRROR.talk.ANY.0-1r.char": "Again, a choice."
}
```

--------------------------------

### HarmonyAsyncIl.RedirectAwaitedCalls example

Source: https://sts2-ritsulib.ritsukage.com/guide/patching-guide

Use for async state-machine transpilers. RedirectAwaitedCalls only redirects calls directly awaited by the state machine and requires the replacement to preserve stack shape and exact awaitable return type. The example validates the rewrite with RequireSucceeded, RequireExactly(1), and InstructionsChecked.

```csharp
var rewriter = HarmonyIlRewriter.From(instructions);
var report = HarmonyAsyncIl.RedirectAwaitedCalls(
    rewriter,
    "Redirect awaited OnPlay",
    originalOnPlayMethod,
    wrapperMethod,
    code => code.Any(instruction => HarmonyIl.IsCallTo(instruction, wrapperMethod)));

report.RequireSucceeded();
report.RequireExactly(1);
return rewriter.InstructionsChecked("Redirect awaited OnPlay");
```

--------------------------------

### Architect dialogue example (Chinese)

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Example JSON for Architect dialogue with a mod character (Chinese version). Uses `THE_ARCHITECT.talk.<CHARACTER_ENTRY>.*` keys. Optional `-attack` values are `None`, `Player`, `Architect`, or `Both`; optional `-visit` keys can override the visit index; explicit `-startattack` and `-endattack` keys set `StartAttackers` and `EndAttackers` respectively.

```json
{
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-0.char": "出口属于你，但代价由我承担。",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-1.ancient": "那就精确地支付。",
  "THE_ARCHITECT.talk.MY_MOD_CHARACTER_SEER.0-attack": "Both"
}
```

--------------------------------

### Create I18N instance with CreateModLocalization and example eng.json

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Creates an I18N instance for key-value JSON files outside the game's model tables. The JSON file shows the expected format for the fallback language (eng.json).

```csharp
var i18n = RitsuLibFramework.CreateModLocalization(
    modId: "MyMod",
    instanceName: "settings",
    pckFolders: ["res://MyMod/localization/settings"]);

var label = i18n.Get("settings.enabled", "Enabled");
```

```json
{
  "settings.enabled": "Enabled"
}
```

--------------------------------

### Mod ancient dialogue example (Chinese)

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Example JSON for a mod ancient talking to a mod character (Chinese version). Uses `MY_MOD_ANCIENT_MIRROR` and `MY_MOD_CHARACTER_SEER` entries, with a repeating dialogue using `r`. `ModAncientEventTemplate` reads `{ancient}.talk.firstVisitEver.*` for the first visit ever, `{ancient}.talk.<CHARACTER_ENTRY>.*` for a specific character, and `{ancient}.talk.ANY.*` for character-agnostic fallback.

```json
{
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-0.ancient": "你带来了一份未来。",
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-0.next": "继续",
  "MY_MOD_ANCIENT_MIRROR.talk.MY_MOD_CHARACTER_SEER.0-1.char": "那我应该谨慎地使用它。",

  "MY_MOD_ANCIENT_MIRROR.talk.ANY.0-0r.ancient": "又一次，镜中映出一张脸。",
  "MY_MOD_ANCIENT_MIRROR.talk.ANY.0-1r.char": "又一次，一个选择。"
}
```

--------------------------------

### Get content and keyword registries and register a card and keyword

Source: https://sts2-ritsulib.ritsukage.com/guide/content-packs-and-registries

Shows how to obtain the content and keyword registries for a mod ID and use them to register a card and a keyword. The keyword registration uses RegisterCardKeywordOwnedByLocNamespace.

```csharp
var content = RitsuLibFramework.GetContentRegistry("MyMod");
content.RegisterCard<MyCardPool, MyStrike>();

var keywords = RitsuLibFramework.GetKeywordRegistry("MyMod");
keywords.RegisterCardKeywordOwnedByLocNamespace("bleeding");
```

--------------------------------

### 添加共享 Tooltip 到动态变量（中文示例）

Source: https://sts2-ritsulib.ritsukage.com/guide/card-dynamic-var-toolkit

Chinese version of the shared tooltip example. The JSON keys provide localized title and description text for the tooltip. Use this when the game UI is in Chinese.

```csharp
ModCardVars.Int("heat", Heat)
    .WithSharedTooltip("MY_MOD_HEAT", "res://MyMod/images/ui/heat.png");
```

```json
{
  "MY_MOD_HEAT.title": "热量",
  "MY_MOD_HEAT.description": "部分卡牌会根据当前热量改变效果。"
}
```

--------------------------------

### Event key construction with ModEventTemplate (C# and JSON)

Source: https://sts2-ritsulib.ritsukage.com/guide/localization-and-keywords

Shows the C# helper methods for building localization keys and a JSON example for event entry MY_MOD_EVENT_QUIET_DOOR. The keys combine the event entry, page name, and option name. Keep page and option names stable after release because they are part of the player's localization and event-choice history.

```csharp
protected string ModOptionKey(string pageName, string optionName);
protected string InitialOptionKey(string optionName);
protected LocString PageDescription(string pageName);
```

```json
{
  "MY_MOD_EVENT_QUIET_DOOR.pages.INITIAL.description": "A quiet door waits in the wall.",
  "MY_MOD_EVENT_QUIET_DOOR.pages.INITIAL.options.OPEN": "[Open] Step through.",
  "MY_MOD_EVENT_QUIET_DOOR.pages.DONE.description": "The room is quiet again."
}
```

--------------------------------

### Register Card, Relic, and Character with Attributes

Source: https://sts2-ritsulib.ritsukage.com/guide/content-authoring-toolkit

Shows attribute registration on concrete model types. Abstract classes are skipped. The example registers a card, a relic, and a character using the corresponding attributes.

```csharp
[RegisterCard(typeof(MyCardPool))]
public sealed class MyStrike
    : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

[RegisterRelic(typeof(MyRelicPool))]
public sealed class MyStarterRelic : ModRelicTemplate
{
}

[RegisterCharacter]
public sealed class MyCharacter
    : ModCharacterTemplate<MyCardPool, MyRelicPool, MyPotionPool>
{
}
```

--------------------------------

### Read and Write Data Store Settings

Source: https://sts2-ritsulib.ritsukage.com/guide/persistence-guide

Use this snippet to read and write settings in a data store. Get<T> returns the live object, Modify<T> mutates it, and Save() persists changes explicitly unless another layer calls Save() for you.

```csharp
var store = RitsuLibFramework.GetDataStore("MyMod");

var settings = store.Get<MySettings>("settings");

store.Modify<MySettings>("settings", data =>
{
    data.Volume = 60;
});

store.Save("settings");
```

--------------------------------

### Register starter content using a content pack

Source: https://sts2-ritsulib.ritsukage.com/guide/character-and-unlock-scaffolding

Use a content pack for a centralized way to review and register starter lists, cards, and relics.

```csharp
RitsuLibFramework.CreateContentPack("MyMod")
    .Character<MyCharacter>(c => c
        .AddStartingRelic<MyStarterRelic>(1, order: 0)
        .AddStartingCard<MyStrike>(4, order: 10)
        .AddStartingCard<MyDefend>(4, order: 20))
    .Card<MyCardPool, MyStrike>()
    .Card<MyCardPool, MyDefend>()
    .Relic<MyRelicPool, MyStarterRelic>()
    .Apply();
```

--------------------------------

### Register FMOD Banks and GUID Mappings

Source: https://sts2-ritsulib.ritsukage.com/guide/fmod-and-audio

Register banks and GUID mappings before attempting to use their associated events.

```csharp
FmodStudioDeferredBankRegistration.RegisterBank("res://MyMod/audio/MyMod.bank");
FmodStudioDeferredBankRegistration.RegisterStudioGuidMappings("res://MyMod/audio/guid_map.json");
```

--------------------------------

### Register Starter Card with Order

Source: https://sts2-ritsulib.ritsukage.com/guide/content-authoring-toolkit

Registers a starter card with an explicit Order. Starter lists are resolved by Order, then by registration order. Lower Order values run earlier within the same phase.

```csharp
[RegisterCard(typeof(MyCardPool))]
[RegisterCharacterStarterCard(typeof(MyCharacter), 4, Order = 10)]
public sealed class MyStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}
```

--------------------------------

### Example entry ID: MY_MOD_CARD_MY_STRIKE

Source: https://sts2-ritsulib.ritsukage.com/guide/content-authoring-toolkit

Example of the entry ID for a card named MyStrike in mod MyMod. The entry is used by saves, model IDs, localization keys, asset defaults, unlock rules, and cross-mod references, and should be treated as stable after release.

```text
MY_MOD_CARD_MY_STRIKE
```

--------------------------------

### Register character and starter content with attributes

Source: https://sts2-ritsulib.ritsukage.com/guide/character-and-unlock-scaffolding

Register the character, starter cards, and starter relics using attributes. Ensure character names and pronouns are defined in characters.json.

```csharp
[RegisterCharacter]
public sealed class MyCharacter
    : ModCharacterTemplate<MyCardPool, MyRelicPool, MyPotionPool>
{
}

[RegisterCard(typeof(MyCardPool))]
[RegisterCharacterStarterCard(typeof(MyCharacter), 4, Order = 10)]
public sealed class MyStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

[RegisterRelic(typeof(MyRelicPool))]
[RegisterCharacterStarterRelic(typeof(MyCharacter), Order = 0)]
public sealed class MyStarterRelic : ModRelicTemplate
{
}
```

--------------------------------

### Batch Registration with Content Pack

Source: https://sts2-ritsulib.ritsukage.com/guide/getting-started

Use RitsuLibFramework.CreateContentPack to register multiple content types in a single batch.

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

--------------------------------

### Set lobby values before run start

Source: https://sts2-ritsulib.ritsukage.com/guide/persistence-guide

Writes lobby values before a run starts via the slot's Lobby accessor. Lobby values are committed into the run snapshot when the new run begins. If SyncLobbyOnChange is enabled, Set and Modify also push the local contribution in multiplayer.

```csharp
public static void SetLobbyChallenge(StartRunLobby lobby, string challengeId)
{
    ChallengeData.Lobby.Modify(lobby, data =>
    {
        data.ChallengeId = challengeId;
    });
}

public static void SetLocalLoadout(StartRunLobby lobby, string loadoutId)
{
    PlayerData.Lobby.Modify(lobby, lobby.NetService.NetId, data =>
    {
        data.LoadoutId = loadoutId;
    });
}

```

--------------------------------

### Create and apply a content pack with RitsuLibFramework.CreateContentPack

Source: https://sts2-ritsulib.ritsukage.com/guide/content-authoring-toolkit

Use a content pack when a batch is more readable than scattered attributes. Registers cards, relics, potions, powers, act events, and a keyword owned by a localization namespace. Do not register the same model through both attributes and a content pack unless you intentionally accept duplicate handling being skipped; pick one source of truth per content family.

```csharp
RitsuLibFramework.CreateContentPack("MyMod")
    .Card<MyCardPool, MyStrike>()
    .Relic<MyRelicPool, MyStarterRelic>()
    .Potion<MyPotionPool, MyPotion>()
    .Power<MyPower>()
    .ActEvent<MyAct, MyEvent>()
    .CardKeywordOwnedByLocNamespace("bleeding")
    .Apply();
```

--------------------------------

### Error response JSON

Source: https://sts2-ritsulib.ritsukage.com/guide/telemetry-backend

Error response example. Use a stable machine-readable error string.

```json
{
  "error": "invalid_schema",
  "message": "schema must be ritsulib.telemetry.batch.v1"
}
```

--------------------------------

### Register Data with BeginModDataRegistration

Source: https://sts2-ritsulib.ritsukage.com/guide/persistence-guide

Register a settings class inside BeginModDataRegistration so initialization happens after the batch is complete. Use classes rather than primitive values so you can add fields later without changing the storage slot.

```csharp
public sealed class MySettings
{
    public bool Enabled { get; set; } = true;
    public int Volume { get; set; } = 80;
}

using (RitsuLibFramework.BeginModDataRegistration("MyMod"))
{
    var store = RitsuLibFramework.GetDataStore("MyMod");
    store.Register(
        key: "settings",
        fileName: "settings.json",
        scope: SaveScope.Global,
        defaultFactory: () => new MySettings(),
        autoCreateIfMissing: true);
}
```

--------------------------------

### Successful response JSON

Source: https://sts2-ritsulib.ritsukage.com/guide/telemetry-backend

Successful response example. Return HTTP 200 or 202 with this JSON body.

```json
{
  "ok": true,
  "accepted": 2,
  "rejected": 0,
  "request_id": "optional-log-correlation-id"
}
```

--------------------------------

### SetupCustomCombatAnimationStateMachine with ModAnimStateMachines.Standard

Source: https://sts2-ritsulib.ritsukage.com/guide/creature-visuals-and-animation

Use when explicit animation state transitions are needed. Return null to let the normal vanilla animation path run. Merchant and rest-site state machines receive the same combat trigger names (Idle, Dead, Hit, Attack, Cast, Relaxed, Revive); world animation names are normalized before reaching the state machine.

```csharp
protected override ModAnimStateMachine? SetupCustomCombatAnimationStateMachine(
    Node visualsRoot,
    CharacterModel character)
{
    return ModAnimStateMachines.Standard(
        CompositeBackendFactory.FromNode(visualsRoot));
}
```

--------------------------------

### Chinese LocString JSON with DynamicVars placeholder

Source: https://sts2-ritsulib.ritsukage.com/guide/loc-string-placeholder-resolution

Chinese localization example for the same card, keeping the {damage} placeholder in the description.

```json
{
  "MY_MOD_CARD_MY_STRIKE.title": "精准打击",
  "MY_MOD_CARD_MY_STRIKE.description": "造成 {damage} 点伤害。"
}
```

--------------------------------

### LocString JSON with DynamicVars placeholder

Source: https://sts2-ritsulib.ritsukage.com/guide/loc-string-placeholder-resolution

Example of a game localization JSON entry using the LocString pipeline. The description keeps the {damage} placeholder for a DynamicVars value.

```json
{
  "MY_MOD_CARD_MY_STRIKE.title": "Measured Strike",
  "MY_MOD_CARD_MY_STRIKE.description": "Deal {damage} damage."
}
```

--------------------------------

### Initialize RitsuLib in Mod Entry

Source: https://sts2-ritsulib.ritsukage.com/guide/getting-started

Register your assembly for RitsuLib discovery using the ModInitializer attribute. EnsureGodotScriptsRegistered is only required if your mod uses C# scripts attached to .tscn scenes.

```csharp
using System.Reflection;
using MegaCrit.Sts2.Core.Logging;
using MegaCrit.Sts2.Core.Modding;
using STS2RitsuLib;
using STS2RitsuLib.Interop;
using STS2RitsuLib.Patching.Core;

[ModInitializer(nameof(Initialize))]
public static class MyModEntry
{
    public const string ModId = "MyMod";
    public static Logger Logger { get; private set; } = null!;

    public static void Initialize()
    {
        var assembly = Assembly.GetExecutingAssembly();

        Logger = RitsuLibFramework.CreateLogger(ModId);
        ModTypeDiscoveryHub.RegisterModAssembly(ModId, assembly);
        RitsuLibFramework.EnsureGodotScriptsRegistered(assembly, Logger);

        var patcher = RitsuLibFramework.CreatePatcher(ModId, "main");
        patcher.RegisterPatches<MyModPatches>();
        RitsuLibFramework.ApplyRequiredPatcher(patcher, DisableMod);
    }

    private static void DisableMod()
    {
        // Mark your own mod disabled when a required patch cannot apply.
    }
}
```

--------------------------------

### Generate Initial Options with InitialOptionKey

Source: https://sts2-ritsulib.ritsukage.com/guide/custom-events

Defines initial event options using a namespaced key. Keep page and option names stable after release to maintain the localization contract.

```csharp
protected override IReadOnlyList<EventOption> GenerateInitialOptions()
{
    return
    [
        new EventOption(this, OpenDoor, InitialOptionKey("OPEN"))
    ];
}
```

--------------------------------

### HarmonyIlRewriter TryInsertAfterFirst with pattern

Source: https://sts2-ritsulib.ritsukage.com/guide/patching-guide

Use for transpilers that must edit IL. The example inserts a call to overrideMethod after the first occurrence of a pattern, then validates the rewrite with report expectations and InstructionsChecked.

```csharp
var rewriter = HarmonyIlRewriter.From(instructions);
var pattern = HarmonyIlPattern.Sequence(
    HarmonyIl.IsLdstr("prefix"),
    HarmonyIl.IsLdloc(),
    HarmonyIl.IsCall(concatMethod),
    HarmonyIl.IsStloc());

var report = rewriter.TryInsertAfterFirst(
    "MyPatch insert override",
    pattern,
    [
        HarmonyIl.Ldarg(0),
        HarmonyIl.Call(overrideMethod),
    ],
    code => code.Any(instruction => HarmonyIl.IsCallTo(instruction, overrideMethod)));

report.RequireSucceeded();
if (report.Applied > 0)
    report.RequireExactly(1);

return rewriter.InstructionsChecked("MyPatch insert override");
```
Tokens:
Raw