SDModKit Developer Documentation

Overview

SDModKit (“StellarDrive Mod Kit”) is a shared MelonLoader library by Krunk that many StellarDrive mods build on. It handles the hard parts of modding for you: cloning new parts into the game, adding build menu entries, sockets and cables, configuration menus, saving into the world save, multiplayer sync, keybinds and its own in-game mod menu.

Read this first

The key data types

Many errors in Visual Studio come from wrong types. The core fields of a part are:

Normally you don't create a ContentPartDef in code yourself – you write a JSON file. SDModKit reads it and builds everything automatically.

Folder structure

All SDModKit files live in MelonLoader's UserData folder inside the game directory. The base path in code is ConfigFile.Folder.

StellarDrive/
├─ Mods/
│  ├─ SDModKit.dll                  ← the Mod Kit itself
│  └─ ExampleMod.dll                   ← your C# mod (optional)
└─ UserData/
   └─ SDModKit/                     ← ConfigFile.Folder
      ├─ modkit.cfg                 ← on/off switches for all mods
      ├─ stellardrive.modkit.cfg    ← settings + keybinds of the kit
      ├─ handshake-skew.cfg         ← version matching (ModVersionSkew)
      ├─ <yourmod>.cfg              ← ConfigFile.For("yourmod")
      ├─ Content/                   ← ContentRegistry.UserFolder
      │  └─ MyPack/
      │     ├─ pack.json            ← every *.json is loaded (recursive)
      │     ├─ models/plant.obj
      │     └─ icons/plant.png
      └─ Dumps/                     ← diagnostic dumps (Dump.Folder)

When saving, SDModKit also writes a file sdmodkit-content.json next to the world save. It holds the settings of your placed parts (see Saving).

Two ways to mod

Both can be combined: the C# mod provides a behaviour, the JSON file references it via "behaviour".

First part without code

Five steps to a potted plant in the build menu – no Unity and no Visual Studio.

1. Export the model from BlenderFile → Export → Wavefront (.obj). Enable UVs and normals, scale 1 m = 1 unit. Details in OBJ from Blender.
2. Create the folderStellarDrive/UserData/SDModKit/Content/Plants/models/ and put plant.obj there.
3. Write pack.jsonCreate a file pack.json in the Plants/ folder with the content below.
4. Start the gameThe MelonLoader log should show Plant Pack 1.0.0 loaded: 0 items, 1 parts, 0 techs.
5. Load a worldThe part appears in the build menu right after the signal splitter.

{
  "id": "example.plants",
  "name": "Plant Pack",
  "version": "1.0.0",
  "parts": [
    {
      "id": 1200,
      "asset": "PottedPlant",
      "label": "Potted plant",
      "description": "A bit of green for your ship.",
      "donor": "SignalSplitter",
      "buildMenuAfter": "SignalSplitter",
      "mass": 5,
      "visual": {
        "meshes": [
          { "resource": "models/plant.obj", "material": "PartMetal", "color": [0.35, 0.75, 0.4] }
        ]
      }
    }
  ]
}

First C# mod

A minimal mod that registers with the kit, creates a setting and a keybind, and loads an embedded content pack. For project setup see Project setup.

using MelonLoader;
using SDModKit;
using SDModKit.Api;
using SDModKit.Configuration;
using SDModKit.Content;
using SDModKit.Input;
using SDModKit.UI;
using SDModKit.Util;
using UnityEngine.InputSystem;

[assembly: MelonInfo(typeof(ExampleMod.Plugin), "Example Mod", "1.0.0", "YourName")]
[assembly: MelonGame("CuriousOwlGames", "StellarDrive")]

namespace ExampleMod
{
    // 1) MelonLoader entry point
    public sealed class Plugin : MelonMod
    {
        public override void OnInitializeMelon()
        {
            // ALWAYS register behaviours before loading the pack
            ContentRegistry.Behaviour("examplemod.plant", () => new PlantBehaviour());

            // pack.json as an EmbeddedResource in the DLL
            ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");

            // register the mod with the kit (own .cfg file under UserData/SDModKit/)
            ModKit.Register(new ExampleKitMod(), ConfigFile.For("examplemod"));
        }
    }

    // 2) The actual SDModKit mod
    public sealed class ExampleKitMod : SDMod
    {
        public override string Id   => "examplemod";
        public override string Name => "Example Mod";

        private ConfigEntry<float> _speed;
        private Keybind _hello;

        public override void OnRegistered()
        {
            _speed = Config.Bind("General", "Speed", 1.5f, "Speed");
            _hello = Keybinds.Register(Config, "Keys", "Hello", Key.H, "Say hello");
            AddPage("Settings", DrawPage);
        }

        public override void OnWorldEnter() => Log.Info("World loaded");

        public override void OnUpdate()
        {
            if (_hello.Pressed) Toasts.Show("Hello from ExampleMod");
        }

        private void DrawPage()
        {
            ModUi.Section("General", () =>
            {
                ModUi.Row("Speed", () =>
                    _speed.Value = ModUi.Slider(_speed.Value, 0f, 5f));
            });
        }
    }
}

Pack structure

A content pack is a JSON file. It is read by ContentPack.Parse using Newtonsoft.Json. At the top level there are only seven fields:

Common value formats

parts – Parts

Each entry in parts becomes a ContentPartDef. SDModKit clones the prefab of the donor (an existing game part), replaces its visuals with your meshes and registers the result as new PartSettings in the game.

What happens during the build

ContentBuilder.Configure processes the definition in this order:

1. Write label, description, state class and mass to the cloned PartSettings.
2. Set snapping (only if given) and add the build cost.
3. Remove the donor visuals (if clearDonor = true) and attach your meshes under a child object SDModKitMeshes.
4. Rebuild the sockets (if sockets is present).
5. Measure the bounds from all renderers (if bounds is missing) and set ShipPartBounds.
6. Fit the interaction collider to the bounds (if fitInteraction = true).
7. Hook up the hover outline and set the icon.

Bounds & snapping

Bounds define the footprint, the collision check while building and the hitbox. If you give neither center nor size, SDModKit measures all renderers of the part (excluding sockets). Default without a model: centre [0, 0.25, 0], size [0.9, 0.5, 0.9], minimum 0.1 per axis.

Snapping defines how the part snaps when placed. The value is a name from the game enum SnappingStyle. The available names are listed in the dump section snapping or the “Snapping table” dump in the mod menu.

Choosing a donor

The donor determines everything you don't override yourself: physics components, network state, interaction and menu. Asset names known from the code:

visual – Meshes

The visual object controls how a part looks. Each element in meshes becomes a child object (MeshDef).

Mesh fields

The mesh source is resolved in this order: resource → donorPath → shape. Special cases are shape: "text" and shape: "screen".

"visual": {
  "clearDonor": true,
  "meshes": [
    { "shape": "cube",     "position": [0, 0.15, 0], "scale": [0.8, 0.3, 0.8], "color": [0.2, 0.25, 0.3] },
    { "shape": "cylinder", "position": [0, 0.40, 0], "scale": [0.3, 0.1, 0.3], "material": "PartMetal" },
    { "shape": "text",     "position": [0, 0.15, -0.41], "scale": [0.6, 0.2, 1], "text": "EX-01", "textColor": [0.3, 0.8, 1] }
  ]
}

sockets – Connectors

Sockets are the plug points for cables and lines. SDModKit copies real socket objects from vanilla parts as templates.

Socket types

"sockets": [
  { "id": 0, "type": "item",  "position": [-0.45, 0.2, 0] },
  { "id": 1, "type": "item",  "position": [ 0.45, 0.2, 0] },
  { "id": 2, "type": "power", "position": [ 0, 0.2, 0.45], "facing": [0, 180, 0] }
]

items – Items

New items (resources, fluids, gases) are added to the game's item list (ContentItems) and can be used in build costs and research.

"items": [
  {
    "id": 9001,
    "name": "Coolant",
    "icon": "icons/coolant.png",
    "mass": 0.5,
    "maxStack": 100,
    "isFluid": true,
    "fluidColor": [0.2, 0.7, 1.0, 1.0],
    "model": { "meshes": [ { "shape": "capsule", "scale": [0.15, 0.15, 0.15], "color": [0.2, 0.7, 1] } ] }
  }
]

research – Research

Research nodes are inserted into the tech tree when entering a world (ContentResearch.Apply). They unlock parts and game features.

"research": [
  {
    "id": 4100,
    "name": "Hydroponics",
    "position": [6, 2],
    "requires": [12],
    "parts": ["PottedPlant"],
    "cost": { "9001": 20 }
  }
]

attach – Extend vanilla

attach adds an extra socket type (and optionally a behaviour) to existing game parts. SDModKit goes through all vanilla parts that

• are not hull parts,
• have an inventory,
• don't have a socket of that type yet,
• and are not listed in exclude.

According to the log, two sockets are added per part. The prefab is cloned first, and everything is reverted when leaving the world.

"attach": [
  {
    "id": "item-ports",
    "socket": { "type": "item", "face": "front" },
    "behaviour": "examplemod.itemport",
    "menu": "config",
    "config": { "mode": "push" },
    "exclude": ["StorageChest"]
  }
]

Complete example

A pack with a custom item, a part with a screen, sockets, cost and research.

{
  "id": "example.monitor",
  "name": "Example Monitor",
  "version": "1.0.0",

  "items": [
    { "id": 9101, "name": "Circuit", "icon": "icons/chip.png", "maxStack": 50,
      "model": { "meshes": [ { "shape": "cube", "scale": [0.2, 0.04, 0.15], "color": [0.1, 0.5, 0.2] } ] } }
  ],

  "parts": [
    {
      "id": 1210,
      "asset": "StatusMonitor",
      "label": "Status monitor",
      "description": "Shows live data on a display.",
      "donor": "SignalSplitter",
      "behaviour": "ExampleMod.MonitorBehaviour",
      "buildMenuAfter": "SignalSplitter",
      "mass": 8,
      "icon": "icons/monitor.png",
      "visual": {
        "meshes": [
          { "resource": "models/monitor.obj" },
          { "shape": "screen", "screen": "example.status", "position": [0, 0.32, -0.051],
            "scale": [0.5, 0.28, 1], "columns": 18, "speed": 8 }
        ]
      },
      "sockets": [
        { "id": 0, "type": "signal", "position": [0, 0.05, 0.1] },
        { "id": 1, "type": "power",  "position": [0.2, 0.05, 0.1] }
      ],
      "cost": { "9101": 2 },
      "config": { "mode": 0 }
    }
  ],

  "research": [
    { "id": 4110, "name": "Status displays", "position": [7, 3], "parts": ["StatusMonitor"], "cost": { "9101": 10 } }
  ]
}

OBJ from Blender

SDModKit has its own OBJ parser (MeshData.FromObj). It is used automatically when the file name ends in .obj.

What the parser supports

• Reads v (vertices), vt (UVs), vn (normals), f (faces) and usemtl.
• Mirrors the X axis and flips the triangle winding – the usual conversion from Blender (right-handed) to Unity (left-handed). You don't need to rotate anything by hand.
• Polygons are triangulated as fans. Better triangulate non-convex n-gons in Blender first.
• If any face lacks normals, all normals are recalculated.
• Above 65,000 vertices it switches to 32-bit indices automatically.
• Each usemtl becomes its own submesh. .mtl files are ignored.

Recommended export settings

JSON mesh format

Every mesh resource that does not end in .obj is read as a JSON mesh (MeshData.FromJson). The format is a direct copy of a Unity mesh – handy if you generate meshes with a script.

{
  "name": "Wedge",
  "vertices":  [0,0,0,  1,0,0,  0,1,0,  0,0,1],
  "normals":   [0,0,-1, 0,0,-1, 0,0,-1, 0,-1,0],
  "uv":        [0,0,  1,0,  0,1,  1,1],
  "submeshes": [ [0,2,1,  0,1,3,  0,3,2,  1,2,3] ]
}

Text & screens

Fixed text

"shape": "text" creates a TextMeshPro object with automatic font size. scale.x and scale.y are the width and height of the text box.

{ "shape": "text", "text": "REACTOR 1", "position": [0, 0.5, -0.3], "scale": [0.6, 0.15, 1], "textColor": [1, 0.6, 0.1] }

Dynamic screen

"shape": "screen" (or simply a set "screen" field) creates a display panel with a text box. Your mod supplies the content through a channel. The content is polled every 0.1 seconds.

using SDModKit.Content;
using UnityEngine;

// once, e.g. in OnRegistered()
Screens.Provide("example.status", screenObject => new ScreenFrame
{
    Text      = "Power: " + Mathf.RoundToInt(Time.time % 100) + " kW",
    Scroll    = true,                      // ticker with "columns" characters
    TextColor = new Color(0.4f, 1f, 0.6f), // optional
    Image     = null                       // show a Texture2D instead of text
});

Textures, icons & materials

Images are loaded via ContentAssets.Texture(pack, path); paths are always relative to the pack folder (forward slashes / work on Windows too). Textures and meshes are cached per pack.

The default PartMetal is the normal metal material of game parts. Further material names can be found through a dump of the donor prefabs. With color a tinted copy of the material is created – the original stays unchanged.

Packs inside the DLL

For C# mods you can embed pack.json, models and icons as an EmbeddedResource in your DLL. Then there is only one file in the Mods folder.

<ItemGroup>
  <EmbeddedResource Include="pack.json" />
  <EmbeddedResource Include="models\*.obj" />
  <EmbeddedResource Include="icons\*.png" />
</ItemGroup>

ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");
// alternatively: generate the JSON yourself
ContentRegistry.LoadJson(typeof(Plugin).Assembly, jsonText, "generated.json");

How resources are found

.NET names embedded files Namespace.folder.file.ext. SDModKit converts models/plant.obj into models.plant.obj and searches in this order:

1. exact resource name,
2. a name ending in .models.plant.obj,
3. a name ending in .plant.obj (file name only).

Project setup

An SDModKit mod is a normal MelonLoader mod (class library for .NET Framework 4.7.2) that additionally references SDModKit.dll.

1. Create the projectVisual Studio → “Class Library (.NET Framework)” or an SDK project with net472. Not .NET 6/8.
2. Add referencesReference the DLLs from the game folder (see the csproj below), each with Private=false so they are not copied.
3. Build & copyCopy the finished YourMod.dll to StellarDrive/Mods/ – next to SDModKit.dll.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
    <LangVersion>latest</LangVersion>
    <AssemblyName>ExampleMod</AssemblyName>
    <RootNamespace>ExampleMod</RootNamespace>
    <!-- Recorded by SDModKit as "examplemod@1.0.0" in the world save -->
    <Version>1.0.0</Version>
    <!-- Adjust the path to your game folder -->
    <GameDir>C:\Program Files (x86)\Steam\steamapps\common\StellarDrive</GameDir>
    <Managed>$(GameDir)\StellarDrive_Data\Managed</Managed>
  </PropertyGroup>

  <ItemGroup>
    <Reference Include="MelonLoader"><HintPath>$(GameDir)\MelonLoader\net35\MelonLoader.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="0Harmony"><HintPath>$(GameDir)\MelonLoader\net35\0Harmony.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="SDModKit"><HintPath>$(GameDir)\Mods\SDModKit.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="Assembly-CSharp"><HintPath>$(Managed)\Assembly-CSharp.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="UnityEngine.CoreModule"><HintPath>$(Managed)\UnityEngine.CoreModule.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="UnityEngine.IMGUIModule"><HintPath>$(Managed)\UnityEngine.IMGUIModule.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="Unity.InputSystem"><HintPath>$(Managed)\Unity.InputSystem.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="Unity.TextMeshPro"><HintPath>$(Managed)\Unity.TextMeshPro.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="Newtonsoft.Json"><HintPath>$(Managed)\Newtonsoft.Json.dll</HintPath><Private>false</Private></Reference>
    <Reference Include="FishNet.Runtime"><HintPath>$(Managed)\FishNet.Runtime.dll</HintPath><Private>false</Private></Reference>
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Include="pack.json" />
    <EmbeddedResource Include="models\**\*.obj" />
    <EmbeddedResource Include="icons\**\*.png" />
  </ItemGroup>

  <!-- Optional: copy to the Mods folder after each build -->
  <Target Name="CopyToMods" AfterTargets="Build">
    <Copy SourceFiles="$(TargetPath)" DestinationFolder="$(GameDir)\Mods" />
  </Target>
</Project>

Required usings

SDMod & ModKit

Every mod derives from SDModKit.Api.SDMod and is registered once with ModKit.Register – typically in OnInitializeMelon of your MelonMod.

SDMod – members

ModKit – static API

Settings (ConfigFile)

ConfigFile.For("name") opens UserData/SDModKit/name.cfg (only once per name). The format is a simple INI:

[General]
# Speed
Speed = 1.5

[Keys]
Hello = H

ConfigEntry<float> speed   = Config.Bind("General", "Speed", 1.5f, "Speed");
ConfigEntry<bool>  enabled = Config.Bind("General", "Enabled", true, "Feature on/off");
ConfigEntry<Mode>  mode    = Config.Bind("General", "Mode", Mode.Auto, "Operating mode"); // enums work too

float v = speed.Value;   // read
speed.Value = 2f;        // write → saved automatically
float d = speed.DefaultValue;

• Supports all types that can be converted to text via Convert (int, float, bool, string …) plus enums. Numbers are written culture-invariant (dot as decimal separator).
• Comments start with # or ;.
• Changed values are saved 2 seconds after the last change, on world change and on exit. Immediately: file.Save() or ConfigFile.SaveAllDirty().

Keybinds

Keybinds are stored in a config file and automatically appear on the Keybinds page of the mod menu, where players can rebind them.

using SDModKit.Input;
using UnityEngine.InputSystem;

Keybind toggle = Keybinds.Register(Config, "Keys", "Toggle", Key.G, "Toggle feature");
Keybind grab   = Keybinds.RegisterMouse(Config, "Keys", "Grab", MouseBind.Middle, "Grab");

public override void OnUpdate()
{
    if (Keybinds.Typing) return;          // player is typing in a text field
    if (toggle.Pressed)  DoToggle();      // pressed this frame
    if (grab.Held)       DragObject();    // held
    if (grab.Released)   Drop();          // released
}

MouseBind: None, Left, Right, Middle, Forward, Back.

Part behaviours

A PartBehaviour is the logic behind a content part. There is one instance per part type, not per placed instance – the data of an instance lives in part.Config.

Registering

// BEFORE loading the pack – binding happens at load time
ContentRegistry.Behaviour("examplemod.plant", () => new PlantBehaviour());
ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");

The pack then contains "behaviour": "examplemod.plant". Alternatively you can give the full class name ("ExampleMod.PlantBehaviour"); SDModKit looks for it in the pack assembly, via Type.GetType and in all loaded assemblies (case-insensitive). The class then needs a parameterless constructor.

Callbacks

ContentPart

All callbacks receive a ContentPart (struct) with: Ship (IShipStateWrite, null on clients), ShipId, PartId, Part (StatefulPart), Def, Config, Valid, Label and LocalPosition.

Complete example

using System.Collections.Generic;
using SDModKit.Content;
using SDModKit.UI;
using UnityEngine;

namespace ExampleMod
{
    public sealed class PlantBehaviour : PartBehaviour
    {
        // Host: water slowly drains
        public override void ServerTick(ContentPart part, float dt)
        {
            float water = part.Config.GetFloat("water", 1f);
            float rate  = part.Config.GetInt("mode", 0) == 1 ? 0.005f : 0.01f;
            float next  = Mathf.Max(0f, water - rate * dt);
            if (Mathf.Abs(next - water) > 0.001f) part.Config.Set("water", next);
        }

        public override string ConfigTitle(ContentPart part) => "Potted plant";

        // Host + client: menu rows
        public override void DescribeConfig(ContentPart part, List<ConfigRow> rows)
        {
            float water = part.Config.GetFloat("water", 1f);
            int   mode  = part.Config.GetInt("mode", 0);

            rows.Add(new ConfigRow { Section = "Plant" });
            rows.Add(new ConfigRow
            {
                Label      = "Water",
                Value      = Mathf.RoundToInt(water * 100f) + " %",
                ValueColor = water < 0.2f ? Theme.Bad : Theme.Good
            });
            rows.Add(new ConfigRow
            {
                Label    = "Mode",
                Value    = mode == 0 ? "Normal" : "Economy",
                Choices  = new[] { "Normal", "Economy" },
                OnChoose = i => part.Config.Set("mode", i)      // menu refreshes itself afterwards
            });
            rows.Add(new ConfigRow
            {
                Label    = "Water now",
                Choices  = new[] { "Water" },
                OnChoose = _ => ContentActions.Send(part, "water") // runs on the host
            });
        }

        // Host: action from the player
        public override void OnAction(ContentPart part, TrackedPlayerServer player, string action)
        {
            if (action == "water") part.Config.Set("water", 1f);
        }
    }
}

{ "id": 1200, "asset": "PottedPlant", "label": "Potted plant",
  "donor": "StorageChest", "state": "StorageChestState",
  "behaviour": "examplemod.plant", "menu": "config",
  "config": { "water": 1.0, "mode": 0 } }

More runtime helpers

Configuration menu

When a player interacts with a content part, SDModKit intercepts the opening of the storage menu (StorageMenuActivator.ShowMenu) and builds your menu from the rows returned by DescribeConfig.

ConfigRow – fields

Behaviour in multiplayer

• On the client the menu first shows “Waiting for the host's settings” until the config arrives from the host.
• If the client changes the config via OnChoose, the whole config is sent to the host.
• If DescribeConfig returns no rows, the menu shows “Nothing to configure”.
• Redraw from outside: ContentConfigMenu.Refresh(). Subscribe to changes: ContentConfigMenu.Changed.

Actions

ContentActions.Send(part, "name") sends an action to the host, which then calls OnAction. The host only runs it if the player is currently interacting with exactly that part – ideal for buttons like “Start”, “Empty” or “Water”.

Storing data

PartConfig – per placed part

Each placed instance has its own PartConfig (internally a JObject). Initial values come from "config" in the pack. It is stored in the world save and synced to clients.

int    n    = part.Config.GetInt("count", 0);
float  f    = part.Config.GetFloat("rate", 1f);
bool   on   = part.Config.GetBool("enabled", true);
string name = part.Config.GetString("name", "");
List<uint> filter = part.Config.GetIds("filter");   // e.g. item IDs

part.Config.Set("count", n + 1);
part.Config.SetIds("filter", new uint[] { 12, 15 });
bool exists = part.Config.Has("count");

Direct access via PartData: PartData.For(shipId, partId, def), TryGet, Forget, Count.

WorldData – per world

Simple key/value pairs (strings) stored with the world:

WorldData.Set("examplemod.lastVisit", System.DateTime.Now.ToString("o"));
string last = WorldData.Get("examplemod.lastVisit");   // null if not set

Mod menu pages

The mod menu is IMGUI-based. Your draw function is called every frame while the page is open. ModUi provides building blocks in the kit's style.

private string _filter = "";

public override void OnRegistered()
{
    AddPage("Settings", DrawSettings);
    ModPage dev = AddPage("Debug", "Tools", DrawTools);
    dev.Available = () => SDModKit.Game.GameRefs.InWorld;   // only show inside a world
}

private void DrawSettings()
{
    ModUi.Section("General", () =>
    {
        ModUi.Row("Enabled", () => _enabled.Value = ModUi.Toggle(_enabled.Value, "on"));
        ModUi.Row("Speed",   () => _speed.Value   = ModUi.Slider(_speed.Value, 0f, 5f));
        ModUi.Row("Count",   () => _count.Value   = ModUi.Int(_count.Value, 1, 64));
        ModUi.Note("Changes are saved automatically.");
    });

    ModUi.Fold("Advanced", () =>
    {
        _filter = ModUi.Search(_filter);
        foreach (var it in SDModKit.Game.ItemCatalog.All)
            if (ModUi.Matches(it.itemName, _filter)) ModUi.Label(it.id + "  " + it.itemName);
    });
}

private void DrawTools()
{
    if (ModUi.Button("Write dump")) SDModKit.Util.Dump.Everything();
}

Harmony patches

SDModKit uses HarmonyDontPatchAll and patches selectively. For your own patches there is ModPatches, which collects failed patches instead of crashing the mod.

using HarmonyLib;
using SDModKit.Patching;

// apply all [HarmonyPatch] classes of your own assembly
bool ok = ModPatches.ApplyAll("examplemod", typeof(Plugin).Assembly, Log);

// or a single patch class
ModPatches.Apply("examplemod", typeof(MyPatch), Log);

// remove all patches of this ID
ModPatches.Remove("examplemod");

ModPatches.For(id) returns the Harmony instance, Handler(owner, method) a HarmonyMethod, BrokenHandlers the list of failed patches (in the mod menu under “Patches that did not bind”).

Logging

Log.Info("loaded");                  // SDMod.Log – prefix = mod name
Log.Trace("only with VerboseLog");   // only appears if Log.Verbose = true
Log.Warn("careful");
Log.Error("broken", ex);

// guard code: exception is logged, returns false
Log.Guard("read inventory", () => ReadInventory());

var other = SDModKit.Util.Log.For("ExampleMod.Net");   // separate logger

Log.Verbose is switched by the kit setting Diagnostics.VerboseLog. Content messages (packs, behaviours) go through ContentLog: the last 400 entries are shown in the mod menu, and from Warn upwards also in the MelonLoader console.

In-game UI helpers

GameModal.Open("Reset ship?", "All settings will be lost.", new[]
{
    new ModalChoice { Label = "Cancel" },
    new ModalChoice { Label = "Reset", Bad = true, OnPick = () => ResetAll() }
});

Game helpers

The SDModKit.Game namespace wraps common game access so you don't have to dig through Assembly-CSharp yourself.

foreach (var it in SDModKit.Game.ItemCatalog.All)
    Log.Info(it.id + " = " + SDModKit.Game.ItemCatalog.DisplayName(it));

Give items with a key

A small test tool: pressing F6 gives the host player 10 units of an item. Handy for quickly trying out build costs and recipes.

using SDModKit.Api;
using SDModKit.Configuration;
using SDModKit.Game;
using SDModKit.Input;
using SDModKit.Util;
using UnityEngine.InputSystem;

public sealed class ItemGiverMod : SDMod
{
    public override string Id   => "example.itemgiver";
    public override string Name => "Item Giver";

    private ConfigEntry<int> _itemId;
    private ConfigEntry<int> _amount;
    private Keybind _give;

    public override void OnRegistered()
    {
        _itemId = Config.Bind("Give", "ItemId", 1, "Item ID to give");
        _amount = Config.Bind("Give", "Amount", 10, "Amount per key press");
        _give   = Keybinds.Register(Config, "Keys", "Give", Key.F6, "Give item");
    }

    public override void OnUpdate()
    {
        if (!GameRefs.InWorld || Keybinds.Typing || !_give.Pressed) return;

        if (PlayerAccess.TryGive((uint)_itemId.Value, _amount.Value, out string error))
            Toasts.Show(_amount.Value + "× " + ItemCatalog.NameOf((uint)_itemId.Value));
        else
            Toasts.Show("Failed: " + error);   // e.g. "not hosting"
    }
}

1. RegisterIn OnInitializeMelon: ModKit.Register(new ItemGiverMod(), ConfigFile.For("example.itemgiver"));
2. Start a world as hostTryGive only works on the host (otherwise the message is not hosting).
3. TestPress F6 – the item lands in your inventory. Change item ID and amount in UserData/SDModKit/example.itemgiver.cfg.

Counter part with a menu

A part that shows a menu with a counter value and two buttons when you interact with it. Demonstrates how DescribeConfig, ContentActions.Send and OnAction work together – also in multiplayer.

using System.Collections.Generic;
using SDModKit.Content;
using SDModKit.UI;

public sealed class CounterBehaviour : PartBehaviour
{
    public override string ConfigTitle(ContentPart part) => "Counter";

    public override void DescribeConfig(ContentPart part, List<ConfigRow> rows)
    {
        int count = part.Config.GetInt("count", 0);

        rows.Add(new ConfigRow { Section = "Count" });
        rows.Add(new ConfigRow
        {
            Label      = "Value",
            Value      = count.ToString(),
            ValueColor = count > 0 ? Theme.Good : Theme.TextDim
        });
        rows.Add(new ConfigRow
        {
            Label    = "Action",
            Choices  = new[] { "+1", "Reset" },
            OnChoose = i => ContentActions.Send(part, i == 0 ? "inc" : "reset")
        });
    }

    // runs on the host only
    public override void OnAction(ContentPart part, TrackedPlayerServer player, string action)
    {
        int count = part.Config.GetInt("count", 0);
        if (action == "inc")   part.Config.Set("count", count + 1);
        if (action == "reset") part.Config.Set("count", 0);
    }
}

{
  "id": "example.counter",
  "name": "Counter Example",
  "version": "1.0.0",
  "parts": [
    {
      "id": 1300,
      "asset": "ExampleCounter",
      "label": "Counter",
      "donor": "StorageChest",
      "state": "StorageChestState",
      "behaviour": "example.counter",
      "menu": "config",
      "buildMenuAfter": "StorageChest",
      "config": { "count": 0 },
      "visual": { "meshes": [ { "shape": "cube", "position": [0, 0.25, 0], "scale": [0.5, 0.5, 0.5], "color": [0.9, 0.6, 0.2] } ] }
    }
  ]
}

ContentRegistry.Behaviour("example.counter", () => new CounterBehaviour());
ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");

1. Check the state classStorageChestState is a placeholder. The dump gives you the real name (aim at a chest and press F9).
2. BuildPlace the orange cube from the build menu.
3. TestInteract → the “Counter” menu appears. “+1” increases the value, “Reset” sets it to 0. The value survives saving and reloading.

Live display

A part with a screen that continuously shows the play time and the role (host/client). Demonstrates shape: "screen" and Screens.Provide.

{
  "id": 1301,
  "asset": "ExampleDisplay",
  "label": "Info display",
  "buildMenuAfter": "SignalSplitter",
  "visual": {
    "meshes": [
      { "shape": "cube",   "position": [0, 0.2, 0],      "scale": [0.6, 0.4, 0.1], "color": [0.15, 0.17, 0.2] },
      { "shape": "screen", "screen": "example.clock",    "position": [0, 0.2, -0.051], "scale": [0.52, 0.32, 1] }
    ]
  }
}

Screens.Provide("example.clock", screen =>
{
    int t = (int)UnityEngine.Time.time;
    string role = SDModKit.Game.GameRefs.IsServer ? "HOST" : "CLIENT";
    return new ScreenFrame
    {
        Text = role + "\n" + (t / 60).ToString("00") + ":" + (t % 60).ToString("00")
    };
});

1. BuildPlace the part – the screen immediately shows role and time.
2. Try the tickerSet Scroll = true in the ScreenFrame and add "columns": 12 in the JSON.

Settings page with reset

A mod menu page with a toggle, a slider and a “Reset” button that shows a confirmation dialog in game style first.

using SDModKit.Api;
using SDModKit.Configuration;
using SDModKit.UI;
using SDModKit.Util;

public sealed class SettingsExampleMod : SDMod
{
    public override string Id   => "example.settings";
    public override string Name => "Settings Example";

    private ConfigEntry<bool>  _enabled;
    private ConfigEntry<float> _strength;

    public override void OnRegistered()
    {
        _enabled  = Config.Bind("General", "Enabled", true, "Feature on/off");
        _strength = Config.Bind("General", "Strength", 0.5f, "Strength 0–1");
        AddPage("Settings", Draw);
    }

    private void Draw()
    {
        ModUi.Section("General", () =>
        {
            ModUi.Row("Enabled",  () => _enabled.Value  = ModUi.Toggle(_enabled.Value, "on"));
            ModUi.Row("Strength", () => _strength.Value = ModUi.Slider(_strength.Value, 0f, 1f));
            ModUi.Note("Current value: " + _strength.Value.ToString("0.00"));
        });

        if (ModUi.Button("Reset to defaults"))
        {
            GameModal.Open("Reset?", "All values of this mod will be lost.", new[]
            {
                new ModalChoice { Label = "Cancel" },
                new ModalChoice { Label = "Reset", Bad = true, OnPick = () =>
                {
                    _enabled.Value  = _enabled.DefaultValue;
                    _strength.Value = _strength.DefaultValue;
                    Toasts.Show("Settings reset");
                }}
            });
        }
    }
}

1. Open the mod menuWith a dev mod via Insert, otherwise via ModKit.OpenMenu() (see The mod menu).
2. TestChange values and restart the game – they are stored in UserData/SDModKit/example.settings.cfg and persist.

Lifecycle

The order in which SDModKit and your mod are called:

Multiplayer

StellarDrive uses FishNet. SDModKit cleanly separates host and client:

Useful for checks: GameRefs.IsServer, GameRefs.IsClient, ModUi.Hosting().

Saving

When the world is saved, ContentSave writes the file sdmodkit-content.json into the save folder. On load (GameLoader.LoadState) it is read back.

{
  "format": 1,
  "game": "0.x.y",
  "mods":  ["modkit@1.3.3", "examplemod@1.0.0"],
  "packs": ["example.plants@1.0.0"],
  "parts": { "…": "PartConfig per ship and part" },
  "world": { "examplemod.lastVisit": "2026-10-13T12:00:00" }
}

API index

All public classes of SDModKit 1.3.3 with their public members – generated automatically from the source code. Type in the field to filter.

Constants & defaults

The mod menu

SDModKit ships its own in-game menu. Every mod gets its pages there, plus the kit pages Keybinds, Content and Diagnostics.

public sealed class DevMod : SDMod
{
    public override string Id   => "examplemod.dev";
    public override string Name => "Example Dev Tools";
    public override bool   Dev  => true;   // unlocks Insert + F9
}

// in OnInitializeMelon:
ModKit.Register(new DevMod(), ConfigFile.For("examplemod.dev"));

Content page

Overview of all loaded packs, parts and items with their problems, plus the latest messages from ContentLog (the “Clear” button empties the log).

Diagnostics page

Shows the part under the crosshair (“Aiming at”), the list Patches that did not bind (failed Harmony patches, e.g. after game updates) and the Write a dump area with individual dump buttons: Everything, Aimed part, Menu prefabs, Snapping table, Cables, Content parts and Vanilla part.

Kit settings in stellardrive.modkit.cfg: Diagnostics.VerboseLog (trace messages) and Diagnostics.DumpOnWorldEnter (dump on every world start).

Dumps

Dumps are text files in UserData/SDModKit/Dumps/. They are the most important tool for finding asset names, state classes, child paths (for donorPath) and materials.

string path = SDModKit.Util.Dump.Everything();   // everything
SDModKit.Util.Dump.Write("myDump", sb => sb.AppendLine("custom content"));
// last path: SDModKit.Util.Dump.LastPath

Log messages

The messages appear in the MelonLoader log (MelonLoader/Latest.log) and on the Content page of the mod menu. Filter by a piece of the text:

FAQ