Rooms and saves

Moving between rooms

Rooms moves between screens as the game does: a fade to black, the room changer's events, then the next room. Each call returns false, doing nothing, when it can't be done now: another room change is under way (IsChanging), or it isn't the screen for it.

// Go into the room you're in again, as a door to it would: the room saved, a fade, rebuilt from its save.
if (Gm.InGame && !Game.IsBusy)
    Rooms.Change(Rooms.Current);

Entering and leaving rooms

Rooms.OnEntered(context, room => context.Log($"Entered {Rooms.CurrentName}"));
Rooms.OnLeaving(context, room => context.Log("Leaving"));

Rooms.OnEntered runs once the game has gone into a room of the game being played, on the frame after it started, its instances all set up. Rooms.OnLeaving runs as the game leaves one: its instances are still there, and the place is already saved if it's saved. Each floor of a dungeon counts, since it's the same room started again.

Saves on disk: SaveSlots

SaveSlots reads the saved games on disk, as the game's save menu shows them: character folders (slots, "character_1" up to 10), newest first, each with its info and its saves.

using System.Linq;

foreach (var slot in SaveSlots.All)
{
    context.Log($"{slot.Name}: {slot.Info?.CharacterName ?? "?"}, saved {slot.Info?.SavedAt}, {slot.Saves.Count} save(s)");
    foreach (var save in slot.Saves)
        context.Log($"  {save.Name} ({save.Kind}): {save.Info?.LocationTitleKey}");
}

// Load the newest save:
var newest = SaveSlots.All.SelectMany(slot => slot.Saves.Take(1)).FirstOrDefault();
if (newest != null)
    Rooms.LoadSave(newest);

SaveSlot has Name, Number, Exists, Info (SlotInfo: CharacterName, IsPermadeath, IsPrologue, SavedAt, and any value by name) and Saves. Each SaveFile has Slot, Name, Kind (SaveKind.Manual, Auto or Exit) and Info (SaveInfo: CharacterName, LocationTitleKey, Avatar, SavedAt, IsValid...).

A mod's values in the save menu - here, how many saves were made with the mod on:

SaveSlots.OnInfoSaving(context, (slot, info) =>
    info["example_saves"] = (slot.Info?["example_saves"] is { Kind: GmKind.Real } count ? count.AsInt : 0) + 1);

SaveSlots.SetTitle(context, slot => slot.Info is { } info && info["example_saves"] is { Kind: GmKind.Real } count
    ? $"{info.CharacterName ?? "?"} - {count.AsInt} save(s) with Example Mod"
    : null);

The game being played: SaveData

SaveData is the save data of the game being played (the game's global.saveDataMap): everything a save writes, in sections. It's live: the game keeps changing it and writes it to disk as it saves. It's there only in a game: check SaveData.Available.

if (SaveData.Available)
{
    context.Log($"Sections: {string.Join(", ", SaveData.Sections)}");
    string? character = SaveData.CharacterJson();   // who's playing, without their world
}

Keeping a mod's own data in saves

var mine = SaveData.ModData(context);           // values only this mod uses
mine["gold"] = mine["gold"].AsInt + 10;

DsMap stash = SaveData.ModMap("mymod_stash");   // a whole map of your own, made empty the first time
stash["gold"] = stash.Get("gold", 0) + 10;

SaveData.ModData keeps values under keys only your mod uses (see ModData). With ModMap, use a key of your mod's own: the game's sections are the save data's other keys.

When saves are read and written

SaveData.OnLoaded(context, save => context.Log($"Loaded {save.Name}"));
SaveData.OnSaving(context, save => SaveData.ModData(context)["saved_at"] = Time.Turns);

The world map's fog and paper are written into the save data only as the game saves. Call WorldMap.Save() before handing the save data to anything that will load it (see the world map).

Save backups

StoneForge backs up every save before the game writes over it or deletes it: see Save backups.

// Keep the save being played, for good, before something risky.
if (SaveBackups.Keep("mymod-before-import") is { } where)
    context.Log($"Kept a copy in {where}");