Home / Getting Started

Getting Started

Create your first Burglin' Gnomes mod in under 5 minutes.

ℹ
Prerequisites: Install via the Gnomium Mod Launcher (recommended) or R2ModMan / Thunderstore. You need the Mod Loader Framework and GnomiumAPI before continuing.
1

Create Your Mod Project

Create a new C# Class Library project targeting .NET Standard 2.1. Add references to the game and framework assemblies.

<!-- YourMod.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.1</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <!-- Reference the mod loader -->
    <Reference Include="GnomiumAPIModLoader">
      <HintPath>..\Build\GnomiumAPIModLoader.dll</HintPath>
    </Reference>
    <!-- Reference GnomiumAPI -->
    <Reference Include="GnomiumAPIMod">
      <HintPath>..\Mods\GnomiumAPI\GnomiumAPIMod.dll</HintPath>
    </Reference>
    <!-- Unity Engine references -->
    <Reference Include="UnityEngine.CoreModule" />
  </ItemGroup>
</Project>
2

Implement the IMod Interface

Every mod must implement IMod with three lifecycle methods: OnLoad, OnUpdate, and OnUnload.

using GnomiumAPI;
using UnityEngine;

namespace MyFirstMod
{
    public class MyMod : IMod
    {
        public string ModId  => "com.myname.myfirstmod";
        public string Name   => "My First Mod";
        public string Version => "1.0.0";

        public void OnLoad()
        {
            // Called once when the mod initializes
            ModLoaderAPI.LogInfo("My First Mod loaded!");

            // Subscribe to events
            Events.OnPlayerSpawned += OnPlayerSpawned;
        }

        public void OnUpdate()
        {
            // Called every frame
            if (Keys.Pressed(KeyCode.F5))
            {
                var me = Players.GetLocal();
                Health.HealFull(me);
                Notify.Show("Healed to full!");
            }
        }

        public void OnUnload()
        {
            // Cleanup when mod is unloaded
            Events.OnPlayerSpawned -= OnPlayerSpawned;
        }

        private void OnPlayerSpawned(MonoBehaviour player)
        {
            Notify.Show("Welcome, player!");
        }
    }
}
3

Create Your Mod Manifest

Create a mod.json file that tells the mod loader about your mod:

{
  "Id": "com.myname.myfirstmod",
  "Name": "My First Mod",
  "Author": "My Name",
  "Version": "1.0.0",
  "Description": "Press F5 to heal!",
  "EntryDll": "MyFirstMod.dll",
  "EntryClass": "MyFirstMod.MyMod",
  "GameVersion": "Demo",
  "Dependencies": ["com.gnomiumapi.api"]
}
4

Build and Deploy

Build your project, then copy the DLL and mod.json to your Mods folder:

Mods/
  |- GnomiumAPI/          # Required dependency
  |    |- GnomiumAPIMod.dll
  |    |- mod.json
  |- MyFirstMod/          # Your mod
       |- MyFirstMod.dll
       |- mod.json

Launch the game and press F5 to heal!

Common Patterns

Recipes for common modding tasks using GnomiumAPI.

Harmony Patching

Use ModLoaderAPI.Harmony for runtime patching:

using HarmonyLib;

// In your OnLoad():
var original = AccessTools.Method(
    Game.Type("GameProgressionManager"),
    "EndGameRpc"
);
var prefix = new HarmonyMethod(
    typeof(MyMod).GetMethod("PreventGameOver")
);
ModLoaderAPI.Harmony.Patch(original, prefix: prefix);

public static bool PreventGameOver()
{
    // Return false to skip the original method
    Notify.Show("Game Over prevented!");
    return false;
}

Snapshot & Restore

Save and restore game state:

// Capture player state
var player = Players.GetLocal();
var snapshot = new {
    pos    = Players.GetPosition(player),
    hp     = Health.Get(player),
    items  = Inventory.GetAllItems(player),
    gnomium = Gnomium.GetCarried(player)
};

// Restore later
Players.Teleport(player, snapshot.pos);
Health.Set(player, snapshot.hp);
Gnomium.SetCarried(player, snapshot.gnomium);

Timed Actions

Use Timers for scheduled operations:

// One-shot: after 3 seconds
Timers.After(3f, () => {
    Notify.Show("3 seconds have passed!");
});

// Repeating: every 10 seconds with cancellation
string timerId = Timers.Every(10f, () => {
    Health.HealFull(Players.GetLocal());
}, "auto-heal");

// Cancel later
Timers.Cancel("auto-heal");

Temporary Field Overrides

Use FieldPatch for reversible modifications:

var player = Players.GetLocal();
var movement = Movement.GetMovement(player);

// Double speed (original is saved automatically)
FieldPatch.Multiply(movement, "speed", 2f);

// Restore original speed later
FieldPatch.Restore(movement, "speed");

// Or restore everything at once
FieldPatch.RestoreAll();

IMod Interface

The interface every mod must implement.

interface IMod
interface
MemberTypeDescription
ModIdstringUnique identifier (e.g., "com.author.modname")
NamestringDisplay name for the mod launcher
VersionstringVersion string (e.g., "1.0.0")
OnLoad()voidCalled once at initialization. Set up your mod here.
OnUpdate()voidCalled every frame. Handle input and per-frame logic.
OnUnload()voidCalled at shutdown. Clean up event subscriptions and patches.

ModLoaderAPI

Static helper class for mod-loader interaction, logging, and mod discovery.

string Version
property
Mod loader version string.
string GameName
property
Returns "Burglin' Gnomes".
Harmony Harmony
property
Shared Harmony instance for runtime patching.
void LogInfo(string message)
method
Log an info-level message via BepInEx.
void LogWarning(string message)
method
Log a warning via BepInEx.
void LogError(string message)
method
Log an error via BepInEx.
bool IsModLoaded(string modId)
method
Check if a specific mod is loaded and active.
IMod GetMod(string modId)
method
Get a loaded mod instance by its ID. Returns null if not found.
T GetMod<T>(string modId)
method
Get a loaded mod cast to a specific type.
event Action OnAllModsLoaded
event
Fired when all mods have finished loading. Safe to query other mods here.
🚀
Ready to explore the full API? Check the API Reference for all 80 classes and 844 members, or download example mods to see real-world usage.