The mod context

Every mod gets a ModContext in Load. It's how the mod registers everything it adds to the game, and what StoneForge uses to take it all back when the mod is switched off.

using StoneForge;

namespace MyMod;

public class MyMod : IStoneMod
{
    public void Load(ModContext context)
    {
        context.Log($"Hello from {context.Name} {context.Manifest.Version}");
    }

    public void Unload() { }
}

Lifecycle

What's taken back for you: event and script hooks, ITickables, DrawGui handlers, UI and windows, main menu buttons, settings (saved first), and your items, buffs and skills (removed from the game; a save from before still has them for when the mod is back).

Every frame: ITickable

A mod class that implements ITickable is ticked every frame from when it's loaded:

public class MyMod : IStoneMod, ITickable
{
    public void Tick(double deltaTime)   // seconds since the last frame
    {
        if (Keyboard.Pressed(Keyboard.F7))
            _context.Items.Give(_blade);
    }
    ...
}

Reading keys and the mouse: Keyboard and mouse.

Anything else can be ticked with context.AddTickable(thing) (and stopped with RemoveTickable). Items and buffs that implement ITickable are ticked once they're added.

What the context has

When a handler fails

When one of a mod's handlers throws, StoneForge logs it, shows its error box and carries on without that handler's work. context.Failed tells the mod, the first time each handler throws: where it was ("Tick", "scr_effect_create (script after)"...) and the exception. Use it to look after your players' data: warn them, or keep a copy of their save.

context.Failed += (where, error) =>
{
    SaveBackups.Keep("mymod-error");
    context.Log($"{where} failed: {error.Message}");
};

It runs on the game thread. A Failed handler that throws is only logged. See also Save backups.

Values of your own: ModData

A mod's own values, kept in what the game keeps (an item's data, the save data, an instance's variables), go under keys only that mod uses: two mods' "kills" are two values, and neither touches the game's.

var mine = item.ModData(context);              // an InventoryItem, an Item or a GroundItem
mine["kills"] = mine["kills"].AsInt + 1;

SaveData.ModData(context)["visits"] = 3;        // saved with the game
player.Instance.ModData(context)["marked"] = true;   // a variable on an instance

Pictures and sounds

int icon = context.LoadSprite("icon.png");                       // Assets\icon.png
int strip = context.LoadSprite("fx/spark.png", frames: 6);       // 6 frames side by side
int music = context.LoadSound("theme.ogg");                      // an OGG stream

Paths are relative to the mod's Assets folder. The sprite is owned by the mod: loading the same path again reuses it, and it's retired when the mod unloads (don't delete it yourself). Both return -1 if the file is missing or can't be loaded.

Files

Mods can't use System.IO. context.Files is their file access:

var files = context.Files;
string names = files.ReadAllText(files.AssetPath("names.txt"));
files.WriteAllText("notes.txt", "...");                                  // mods\MyMod\notes.txt
string[] logs = files.ListFiles(files.ModFolder, "*.txt");                // full paths

Exists, DirectoryExists, ReadAllText, ReadAllLines, ReadAllBytes, ListFiles, WriteAllText, AppendAllText, WriteAllBytes, Delete, CreateDirectory. A path outside what's allowed throws UnauthorizedAccessException.

Trusted mods

A mod can ask for full access with "trusted": true in its mod.json: its own DLLs, the whole of .NET (networking, threads, files, reflection) and Game.CallBuiltinUnrestricted. It runs only once the player allows it in the Mods window, warned that it can do anything a program on their PC can. Ask for it only when a mod truly needs it, such as for multiplayer networking.