How GML maps to C# code

Stoneshard is a GameMaker game: everything in it - the player, enemies, items, menus, the save data - is GML objects, scripts, variables and data structures. StoneForge doesn't replace any of that. It gives C# a way in, in layers, each built on the one under it:

You can mix layers freely. A typed instance always has its untyped Instance underneath (player.Instance["any_variable"]), and every generated script is also callable by name (Game.CallScript("scr_atr", ...)).

Where the generated API comes from

The generated API is made from the game's own data at build time: StoneForge.DataDump reads Stoneshard's data.win (the VM build's: on the native branch it uses the last VM data it kept), and a source generator turns it into C#:

Because these are generated, a typo is a compile error rather than a silent failure in game, and your editor can autocomplete the game's names.

A tour in one mod

using StoneForge;
using StoneForge.Objects;

// Scripts this mod hooks are declared, so the patcher makes them hookable on the VM modbranch.
[assembly: HookScript(nameof(Scripts.scr_player_move))]

namespace MyMod;

public class MyMod : IStoneMod, ITickable
{
    private ModContext _context = null!;

    public void Load(ModContext context)
    {
        _context = context;

        // Generated event, typed instance: player.HP rather than player.Get("HP").
        Events.o_player.Step_0.After(context, player =>
        {
            if (player.HP < player.max_hp * 0.25)
                context.Log("Low health!");
        });

        // Generated script hook: runs whenever the game calls scr_player_move.
        Scripts.scr_player_move.Before(context, call =>
        {
            context.Log($"{call.Name}({string.Join(", ", call.Args)})");
            return false;   // false: let the game's own code run
        });
    }

    public void Tick(double deltaTime)
    {
        // Typed helpers: find the player, read a built-in variable.
        if (Keyboard.Pressed(Keyboard.F4) && Instances.First<GameInstance>(GameObjectId.o_player) is { } player)
        {
            // By name: call any game script with any arguments.
            Game.CallScript("scr_atr_incr", player.Instance, "SP", 1);
            _context.Log($"An ability point, at ({player.X}, {player.Y})");
        }
    }

    public void Unload() { }
}

Rules that apply everywhere

• Write your usings. Mods are compiled by the game without implicit usings: add using System;, using System.Collections.Generic; and using System.Linq; where you use Math, Random, collections or LINQ.
• Game thread only. Every call into the game must happen on its thread: in Load, a Tick, an event or hook handler, a UI callback or DrawGui. Don't call into the game from a Task or another thread.
• Not before the game runs. While mods load, the game isn't set up yet. Game.Running is false until it starts running frames; calls before then throw instead of crashing the game. Register things in Load; do things in events, Tick or UI callbacks.
• Missing values aren't errors. Reading a variable that doesn't exist gives GmValue.Undefined, and reading a value as the wrong type gives that type's default (a string read as a number is 0). Check Kind or IsUndefined when it matters.
• Failed calls throw. A built-in or script call the bridge can't complete throws GameCallException, naming the function and why.
• Handlers are isolated. A handler that throws is logged and skipped: it doesn't take the game, or other mods, down.

Where next

• Values: GmValue, and the game's arrays, structs, maps and lists.
• Instances and objects: finding, reading and changing what's in the room.
• Calling the game: built-ins, scripts and globals.
• Hooks: scripts and events: running your code around the game's.
• Your own GML: shipping GML functions with your mod and calling them from C#.