Skip to content

Persistence

Register each saved concept as a class. Do it inside BeginModDataRegistration so initialization happens after the batch is complete.

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);
}

Use classes rather than primitive values so you can add fields later without changing the storage slot.

ScopeUse for
SaveScope.GlobalMod settings, account-wide preferences, caches shared by all game profiles.
SaveScope.ProfileProgression, unlock-like data, and anything tied to the current game profile.
SaveScope.InMemoryTemporary process-local data that should use the same store API but never writes to disk.
SaveScope.RunSidecarPer-run sidecar data with an explicit StorageContext; use only when you are working with run-scoped files.

RunSidecar cannot use the simple Register<T>(key, fileName, scope, ...) overload. It needs the overload with contextProvider, or higher-level run-sidecar helpers.

var store = RitsuLibFramework.GetDataStore("MyMod");
var settings = store.Get<MySettings>("settings");
store.Modify<MySettings>("settings", data =>
{
data.Volume = 60;
});
store.Save("settings");

Get<T> returns the live object. Modify<T> mutates that object. Saving is explicit unless another layer, such as a settings binding, calls Save() for you.

Add migrations before publishing a breaking data shape.

store.Register<MySettings>(
"settings",
"settings.json",
SaveScope.Global,
defaultFactory: () => new MySettings(),
migrationConfig: new ModDataMigrationConfig(
currentDataVersion: 2,
minimumSupportedDataVersion: 1),
migrations:
[
new SettingsV1ToV2Migration(),
]);

Keep fileName and key stable after release. Change the schema version when the JSON shape changes in a way old files cannot deserialize directly.

Use AttachedState<TKey,TValue> for runtime-only state attached to reference objects. Use SavedAttachedState<TKey,TValue> only for model objects that already pass through the game’s SavedProperties serialization.

private static readonly SavedAttachedState<CardModel, int> BonusDamage =
new("bonus_damage", () => 0);
BonusDamage[card] = 3;

For normal mod settings, progression, and feature data, prefer ModDataStore.