SDModKit Entwickler-Dokumentation

Überblick

SDModKit („StellarDrive Mod Kit“) ist eine gemeinsame MelonLoader-Bibliothek von Krunk, auf der viele StellarDrive-Mods aufbauen. Sie nimmt dir die schwierigen Teile des Moddings ab: neue Bauteile ins Spiel klonen, Baumenü-Einträge anlegen, Sockets und Kabel, Konfigurationsmenüs, Speichern im Spielstand, Multiplayer-Synchronisation, Keybinds und ein eigenes Ingame-Mod-Menü.

Wichtig vorab

Die wichtigsten Datentypen

Viele Fehler in Visual Studio entstehen durch falsche Typen. Die Kernfelder eines Parts sind:

Normalerweise erzeugst du ContentPartDef nicht selbst im Code, sondern schreibst eine JSON-Datei. SDModKit liest sie ein und baut alles automatisch.

Ordnerstruktur

Alle Dateien von SDModKit liegen im UserData-Ordner von MelonLoader im Spielverzeichnis. Der Basispfad im Code ist ConfigFile.Folder.

StellarDrive/
├─ Mods/
│  ├─ SDModKit.dll                  ← das Mod Kit selbst
│  └─ ExampleMod.dll                   ← deine C#-Mod (optional)
└─ UserData/
   └─ SDModKit/                     ← ConfigFile.Folder
      ├─ modkit.cfg                 ← Mod-Schalter (an/aus) aller Mods
      ├─ stellardrive.modkit.cfg    ← Einstellungen + Keybinds des Kits
      ├─ handshake-skew.cfg         ← Versionsabgleich (ModVersionSkew)
      ├─ <deinemod>.cfg             ← ConfigFile.For("deinemod")
      ├─ Content/                   ← ContentRegistry.UserFolder
      │  └─ MeinPack/
      │     ├─ pack.json            ← jede *.json wird geladen (rekursiv)
      │     ├─ models/plant.obj
      │     └─ icons/plant.png
      └─ Dumps/                     ← Diagnose-Dumps (Dump.Folder)

Zusätzlich schreibt SDModKit beim Speichern eine Datei sdmodkit-content.json neben den Spielstand der Welt. Darin stehen die Einstellungen deiner platzierten Parts (siehe Speicherung).

Zwei Wege zur Mod

Beide Wege lassen sich kombinieren: Die C#-Mod liefert ein Behaviour, die JSON-Datei verweist per "behaviour" darauf.

Erster Part ohne Code

In fünf Schritten zu einer Topfpflanze im Baumenü – ohne Unity und ohne Visual Studio.

1. Modell in Blender exportierenDatei → Exportieren → Wavefront (.obj). UVs und Normalen aktivieren, Maßstab 1 m = 1 Einheit. Details unter OBJ aus Blender.
2. Ordner anlegenStellarDrive/UserData/SDModKit/Content/Pflanzen/models/ und die Datei plant.obj dort ablegen.
3. pack.json schreibenIm Ordner Pflanzen/ eine Datei pack.json mit folgendem Inhalt anlegen.
4. Spiel startenIm MelonLoader-Log sollte Pflanzen-Pack 1.0.0 loaded: 0 items, 1 parts, 0 techs stehen.
5. Welt ladenDer Part erscheint im Baumenü direkt hinter dem Signal-Splitter.

{
  "id": "example.plants",
  "name": "Pflanzen-Pack",
  "version": "1.0.0",
  "parts": [
    {
      "id": 1200,
      "asset": "PottedPlant",
      "label": "Topfpflanze",
      "description": "Ein bisschen Grün für dein Schiff.",
      "donor": "SignalSplitter",
      "buildMenuAfter": "SignalSplitter",
      "mass": 5,
      "visual": {
        "meshes": [
          { "resource": "models/plant.obj", "material": "PartMetal", "color": [0.35, 0.75, 0.4] }
        ]
      }
    }
  ]
}

Erste C#-Mod

Eine minimale Mod, die sich beim Kit registriert, eine Einstellung und einen Keybind anlegt und ein eingebettetes Content-Pack lädt. Projekt-Setup siehe Projekt einrichten.

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-Einstiegspunkt
    public sealed class Plugin : MelonMod
    {
        public override void OnInitializeMelon()
        {
            // Behaviours IMMER vor dem Laden des Packs registrieren
            ContentRegistry.Behaviour("examplemod.plant", () => new PlantBehaviour());

            // pack.json als EmbeddedResource in der DLL
            ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");

            // Mod beim Kit anmelden (eigene .cfg-Datei unter UserData/SDModKit/)
            ModKit.Register(new ExampleKitMod(), ConfigFile.For("examplemod"));
        }
    }

    // 2) Die eigentliche 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, "Geschwindigkeit");
            _hello = Keybinds.Register(Config, "Keys", "Hello", Key.H, "Hallo sagen");
            AddPage("Einstellungen", DrawPage);
        }

        public override void OnWorldEnter() => Log.Info("Welt geladen");

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

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

Aufbau eines Packs

Ein Content-Pack ist eine JSON-Datei. Sie wird von ContentPack.Parse mit Newtonsoft.Json gelesen. Auf oberster Ebene gibt es nur sieben Felder:

Gemeinsame Werteformate

parts – Bauteile

Jeder Eintrag in parts wird zu einer ContentPartDef. SDModKit klont dafür das Prefab des Donors (eines vorhandenen Spiel-Parts), ersetzt die Optik durch deine Meshes und trägt das Ergebnis als neue PartSettings ins Spiel ein.

Was beim Bauen passiert

ContentBuilder.Configure arbeitet die Definition in dieser Reihenfolge ab:

1. Label, Beschreibung, State-Klasse und Masse auf die geklonten PartSettings schreiben.
2. Snapping setzen (nur wenn angegeben) und Baukosten eintragen.
3. Optik des Donors entfernen (wenn clearDonor = true) und deine Meshes unter einem Kindobjekt SDModKitMeshes einhängen.
4. Sockets neu aufbauen (wenn sockets vorhanden).
5. Bounds aus allen Renderern messen (wenn bounds fehlt) und ShipPartBounds setzen.
6. Interaktions-Collider auf die Bounds anpassen (wenn fitInteraction = true).
7. Hover-Umriss verknüpfen und Icon setzen.

Bounds & Snapping

Bounds bestimmen Platzbedarf, Kollisionsprüfung beim Bauen und die Hitbox. Gibst du weder center noch size an, misst SDModKit alle Renderer des Parts (ohne Sockets). Standard bei fehlendem Modell: Mitte [0, 0.25, 0], Größe [0.9, 0.5, 0.9], Mindestgröße 0,1 je Achse.

Snapping legt fest, wie der Part beim Platzieren einrastet. Der Wert ist ein Name aus dem Spiel-Enum SnappingStyle. Die verfügbaren Namen listet der Dump-Abschnitt snapping bzw. die „Snapping table“ im Mod-Menü auf.

Donor wählen

Der Donor bestimmt alles, was du nicht selbst überschreibst: Physik-Komponenten, Netzwerk-Zustand, Interaktion und Menü. Bekannte Asset-Namen aus dem Code:

visual – Meshes

Das Objekt visual steuert die Optik eines Parts. Jedes Element in meshes wird zu einem Kindobjekt (MeshDef).

Mesh-Felder

Die Mesh-Quelle wird in dieser Reihenfolge gesucht: resource → donorPath → shape. Sonderfälle sind shape: "text" und 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 – Anschlüsse

Sockets sind die Steckplätze für Kabel und Leitungen. SDModKit kopiert dafür echte Socket-Objekte aus Vanilla-Parts als Vorlage.

Socket-Typen

"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

Neue Items (Ressourcen, Flüssigkeiten, Gase) werden in die Item-Liste des Spiels eingefügt (ContentItems) und können in Baukosten und Forschung verwendet werden.

"items": [
  {
    "id": 9001,
    "name": "Kühlflüssigkeit",
    "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 – Forschung

Forschungsknoten werden beim Betreten der Welt in den Tech-Tree eingefügt (ContentResearch.Apply). Sie schalten Parts und Spielfunktionen frei.

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

attach – Vanilla erweitern

attach hängt einen zusätzlichen Socket-Typ (und optional ein Behaviour) an bestehende Spiel-Parts. SDModKit geht dabei alle Vanilla-Parts durch, die

• keine Hüllen-Parts sind,
• ein Inventar besitzen,
• noch keinen Socket dieses Typs haben,
• und nicht in exclude stehen.

Laut Log werden dabei je Part zwei Sockets ergänzt. Das Prefab wird vorher geklont, beim Verlassen der Welt wird alles zurückgesetzt.

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

Vollständiges Beispiel

Ein Pack mit eigenem Item, einem Part mit Screen, Sockets, Kosten und Forschung.

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

  "items": [
    { "id": 9101, "name": "Schaltkreis", "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": "Zeigt Live-Daten auf einem 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 aus Blender

SDModKit hat einen eigenen OBJ-Parser (MeshData.FromObj). Er wird automatisch genutzt, wenn der Dateiname auf .obj endet.

Was der Parser kann

• Liest v (Vertices), vt (UVs), vn (Normalen), f (Flächen) und usemtl.
• Spiegelt die X-Achse und dreht die Dreiecks-Reihenfolge – das ist die übliche Umrechnung von Blender (rechtshändig) nach Unity (linkshändig). Du musst nichts von Hand drehen.
• Vielecke werden als Fächer trianguliert. Nicht-konvexe N-Gons daher besser vorher in Blender triangulieren.
• Fehlen Normalen an einer Fläche, werden alle Normalen neu berechnet.
• Über 65.000 Vertices schaltet er automatisch auf 32-Bit-Indizes.
• Jedes usemtl wird ein eigenes Submesh. .mtl-Dateien werden ignoriert.

Empfohlene Export-Einstellungen

JSON-Mesh-Format

Jede Mesh-Ressource, die nicht auf .obj endet, wird als JSON-Mesh gelesen (MeshData.FromJson). Das Format ist ein direkter Abzug eines Unity-Meshes – nützlich, wenn du Meshes per Skript erzeugst.

{
  "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] ]
}

Texte & Screens

Fester Text

"shape": "text" erzeugt ein TextMeshPro-Objekt mit automatischer Schriftgröße. scale.x und scale.y sind die Breite und Höhe des Textfelds.

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

Dynamischer Screen

"shape": "screen" (oder einfach ein gesetztes "screen"-Feld) erzeugt ein Display-Panel mit Textfeld. Den Inhalt liefert deine Mod über einen Kanal. Der Inhalt wird alle 0,1 Sekunden abgefragt.

using SDModKit.Content;
using UnityEngine;

// einmalig, z. B. in OnRegistered()
Screens.Provide("example.status", screenObject => new ScreenFrame
{
    Text      = "Leistung: " + Mathf.RoundToInt(Time.time % 100) + " kW",
    Scroll    = true,                      // Lauftext mit "columns" Zeichen
    TextColor = new Color(0.4f, 1f, 0.6f), // optional
    Image     = null                       // Texture2D statt Text anzeigen
});

Texturen, Icons & Materialien

Bilder werden über ContentAssets.Texture(pack, pfad) geladen, Pfade sind immer relativ zum Pack-Ordner (Schrägstrich / funktioniert auch unter Windows). Texturen und Meshes werden pro Pack zwischengespeichert.

Der Standard PartMetal ist das normale Metall-Material der Spiel-Parts. Weitere Materialnamen kannst du über einen Dump der Donor-Prefabs herausfinden. Mit color wird eine eingefärbte Kopie des Materials angelegt – das Original bleibt unverändert.

Packs in der DLL

Für C#-Mods kannst du pack.json, Modelle und Icons als EmbeddedResource in deine DLL packen. Dann gibt es nur eine Datei im Mods-Ordner.

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

ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");
// alternativ: JSON selbst erzeugen
ContentRegistry.LoadJson(typeof(Plugin).Assembly, jsonText, "generated.json");

Wie Ressourcen gefunden werden

.NET benennt eingebettete Dateien als Namespace.ordner.datei.ext. SDModKit wandelt models/plant.obj in models.plant.obj um und sucht in dieser Reihenfolge:

1. exakter Ressourcenname,
2. ein Name, der auf .models.plant.obj endet,
3. ein Name, der auf .plant.obj endet (nur der Dateiname).

Projekt einrichten

Eine SDModKit-Mod ist eine normale MelonLoader-Mod (Klassenbibliothek für .NET Framework 4.7.2), die zusätzlich SDModKit.dll referenziert.

1. Projekt anlegenVisual Studio → „Klassenbibliothek (.NET Framework)“ oder ein SDK-Projekt mit net472. Kein .NET 6/8.
2. Referenzen setzenDie DLLs aus dem Spielordner referenzieren (siehe csproj unten), jeweils mit Private=false, damit sie nicht mitkopiert werden.
3. Bauen & kopierenDie fertige DeineMod.dll nach StellarDrive/Mods/ kopieren – neben SDModKit.dll.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
    <LangVersion>latest</LangVersion>
    <AssemblyName>ExampleMod</AssemblyName>
    <RootNamespace>ExampleMod</RootNamespace>
    <!-- Wird von SDModKit als "examplemod@1.0.0" im Spielstand vermerkt -->
    <Version>1.0.0</Version>
    <!-- Pfad zu deinem Spielordner anpassen -->
    <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: nach dem Build automatisch in den Mods-Ordner kopieren -->
  <Target Name="CopyToMods" AfterTargets="Build">
    <Copy SourceFiles="$(TargetPath)" DestinationFolder="$(GameDir)\Mods" />
  </Target>
</Project>

Benötigte usings

SDMod & ModKit

Jede Mod leitet von SDModKit.Api.SDMod ab und wird einmal mit ModKit.Register angemeldet – typischerweise in OnInitializeMelon deiner MelonMod.

SDMod – Mitglieder

ModKit – statische API

Einstellungen (ConfigFile)

ConfigFile.For("name") öffnet UserData/SDModKit/name.cfg (pro Name nur einmal). Das Format ist ein einfaches INI:

[General]
# Geschwindigkeit
Speed = 1.5

[Keys]
Hello = H

ConfigEntry<float> speed   = Config.Bind("General", "Speed", 1.5f, "Geschwindigkeit");
ConfigEntry<bool>  enabled = Config.Bind("General", "Enabled", true, "Funktion an/aus");
ConfigEntry<Mode>  mode    = Config.Bind("General", "Mode", Mode.Auto, "Betriebsart"); // Enums gehen auch

float v = speed.Value;   // lesen
speed.Value = 2f;        // schreiben → wird automatisch gespeichert
float d = speed.DefaultValue;

• Unterstützt alle Typen, die sich per Convert in Text umwandeln lassen (int, float, bool, string …) sowie Enums. Zahlen werden kulturunabhängig (Punkt als Dezimaltrenner) geschrieben.
• Kommentare beginnen mit # oder ;.
• Geänderte Werte werden 2 Sekunden nach der letzten Änderung, beim Weltwechsel und beim Beenden gespeichert. Sofort: file.Save() oder ConfigFile.SaveAllDirty().

Keybinds

Keybinds werden in einer Config-Datei gespeichert und erscheinen automatisch auf der Keybinds-Seite des Mod-Menüs, wo Spieler sie neu belegen können.

using SDModKit.Input;
using UnityEngine.InputSystem;

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

public override void OnUpdate()
{
    if (Keybinds.Typing) return;          // Spieler tippt gerade in ein Textfeld
    if (toggle.Pressed)  DoToggle();      // in diesem Frame gedrückt
    if (grab.Held)       DragObject();    // gehalten
    if (grab.Released)   Drop();          // losgelassen
}

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

Part-Behaviours

Ein PartBehaviour ist die Logik hinter einem Content-Part. Es gibt eine Instanz pro Part-Typ, nicht pro platziertem Exemplar – die Daten eines Exemplars stehen in part.Config.

Registrieren

// VOR dem Laden des Packs – die Verknüpfung passiert beim Laden
ContentRegistry.Behaviour("examplemod.plant", () => new PlantBehaviour());
ContentRegistry.LoadEmbedded(typeof(Plugin).Assembly, "pack.json");

Im Pack steht dann "behaviour": "examplemod.plant". Alternativ kannst du den vollen Klassennamen angeben ("ExampleMod.PlantBehaviour"); SDModKit sucht ihn in der Pack-Assembly, per Type.GetType und in allen geladenen Assemblys (Groß/klein egal). Die Klasse braucht dann einen parameterlosen Konstruktor.

Callbacks

ContentPart

Alle Callbacks bekommen ein ContentPart (struct) mit: Ship (IShipStateWrite, auf Clients null), ShipId, PartId, Part (StatefulPart), Def, Config, Valid, Label und LocalPosition.

Vollständiges Beispiel

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

namespace ExampleMod
{
    public sealed class PlantBehaviour : PartBehaviour
    {
        // Host: Wasser sinkt langsam
        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) => "Topfpflanze";

        // Host + Client: Menüzeilen
        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 = "Pflanze" });
            rows.Add(new ConfigRow
            {
                Label      = "Wasser",
                Value      = Mathf.RoundToInt(water * 100f) + " %",
                ValueColor = water < 0.2f ? Theme.Bad : Theme.Good
            });
            rows.Add(new ConfigRow
            {
                Label    = "Modus",
                Value    = mode == 0 ? "Normal" : "Sparsam",
                Choices  = new[] { "Normal", "Sparsam" },
                OnChoose = i => part.Config.Set("mode", i)      // Menü aktualisiert sich danach selbst
            });
            rows.Add(new ConfigRow
            {
                Label    = "Gießen",
                Choices  = new[] { "Jetzt gießen" },
                OnChoose = _ => ContentActions.Send(part, "water") // läuft auf dem Host
            });
        }

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

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

Weitere Laufzeit-Helfer

Konfigurationsmenü

Wenn ein Spieler mit einem Content-Part interagiert, fängt SDModKit das Öffnen des Storage-Menüs ab (StorageMenuActivator.ShowMenu) und baut dein Menü aus den Zeilen von DescribeConfig.

ConfigRow – Felder

Verhalten im Multiplayer

• Auf dem Client zeigt das Menü zuerst „Waiting for the host's settings“, bis die Config vom Host da ist.
• Ändert der Client per OnChoose die Config, wird die ganze Config an den Host geschickt.
• Liefert DescribeConfig keine Zeilen, steht „Nothing to configure“ im Menü.
• Von außen neu zeichnen: ContentConfigMenu.Refresh(). Änderungen abonnieren: ContentConfigMenu.Changed.

Aktionen

ContentActions.Send(part, "name") schickt eine Aktion an den Host, der dann OnAction aufruft. Der Host führt sie nur aus, wenn der Spieler gerade mit genau diesem Part interagiert – ideal für Buttons wie „Start“, „Leeren“ oder „Gießen“.

Daten speichern

PartConfig – pro platziertem Part

Jedes platzierte Exemplar hat eine eigene PartConfig (intern ein JObject). Startwerte kommen aus "config" im Pack. Sie wird im Spielstand gespeichert und an Clients synchronisiert.

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");   // z. B. Item-IDs

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

Direkter Zugriff über PartData: PartData.For(shipId, partId, def), TryGet, Forget, Count.

WorldData – pro Welt

Einfache Schlüssel/Wert-Paare (Strings), die mit der Welt gespeichert werden:

WorldData.Set("examplemod.lastVisit", System.DateTime.Now.ToString("o"));
string last = WorldData.Get("examplemod.lastVisit");   // null, wenn nicht gesetzt

Seiten im Mod-Menü

Das Mod-Menü ist IMGUI-basiert. Deine Draw-Funktion wird jeden Frame aufgerufen, solange die Seite offen ist. ModUi liefert passende Bausteine im Kit-Stil.

private string _filter = "";

public override void OnRegistered()
{
    AddPage("Einstellungen", DrawSettings);
    ModPage dev = AddPage("Debug", "Werkzeuge", DrawTools);
    dev.Available = () => SDModKit.Game.GameRefs.InWorld;   // nur in einer Welt anzeigen
}

private void DrawSettings()
{
    ModUi.Section("Allgemein", () =>
    {
        ModUi.Row("Aktiv",  () => _enabled.Value = ModUi.Toggle(_enabled.Value, "an"));
        ModUi.Row("Tempo",  () => _speed.Value   = ModUi.Slider(_speed.Value, 0f, 5f));
        ModUi.Row("Anzahl", () => _count.Value   = ModUi.Int(_count.Value, 1, 64));
        ModUi.Note("Änderungen werden automatisch gespeichert.");
    });

    ModUi.Fold("Erweitert", () =>
    {
        _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("Dump schreiben")) SDModKit.Util.Dump.Everything();
}

Harmony-Patches

SDModKit nutzt HarmonyDontPatchAll und patcht gezielt. Für eigene Patches gibt es ModPatches, das fehlgeschlagene Patches sammelt statt die Mod abstürzen zu lassen.

using HarmonyLib;
using SDModKit.Patching;

// alle [HarmonyPatch]-Klassen der eigenen Assembly anwenden
bool ok = ModPatches.ApplyAll("examplemod", typeof(Plugin).Assembly, Log);

// oder eine einzelne Patch-Klasse
ModPatches.Apply("examplemod", typeof(MyPatch), Log);

// alle Patches dieser ID entfernen
ModPatches.Remove("examplemod");

ModPatches.For(id) liefert die Harmony-Instanz, Handler(owner, method) eine HarmonyMethod, BrokenHandlers die Liste fehlgeschlagener Patches (im Mod-Menü unter „Patches that did not bind“).

Logging

Log.Info("geladen");                 // SDMod.Log – Präfix = Mod-Name
Log.Trace("nur bei VerboseLog");     // erscheint nur, wenn Log.Verbose = true
Log.Warn("Achtung");
Log.Error("kaputt", ex);

// Code absichern: Ausnahme wird geloggt, Rückgabe false
Log.Guard("Inventar lesen", () => ReadInventory());

var other = SDModKit.Util.Log.For("ExampleMod.Netz");   // eigener Logger

Log.Verbose wird über die Kit-Einstellung Diagnostics.VerboseLog geschaltet. Content-Meldungen (Packs, Behaviours) laufen über ContentLog: die letzten 400 Einträge stehen im Mod-Menü, ab Warn zusätzlich in der MelonLoader-Konsole.

UI-Helfer im Spiel

GameModal.Open("Schiff zurücksetzen?", "Alle Einstellungen gehen verloren.", new[]
{
    new ModalChoice { Label = "Abbrechen" },
    new ModalChoice { Label = "Zurücksetzen", Bad = true, OnPick = () => ResetAll() }
});

Spiel-Helfer

Der Namespace SDModKit.Game kapselt häufige Zugriffe auf das Spiel, damit du nicht selbst in Assembly-CSharp suchen musst.

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

Items per Taste geben

Ein kleines Test-Werkzeug: Ein Druck auf F6 gibt dem Host-Spieler 10 Einheiten eines Items. Nützlich, um Baukosten und Rezepte schnell auszuprobieren.

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, die vergeben wird");
        _amount = Config.Bind("Give", "Amount", 10, "Menge pro Tastendruck");
        _give   = Keybinds.Register(Config, "Keys", "Give", Key.F6, "Item geben");
    }

    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("Fehlgeschlagen: " + error);   // z. B. "not hosting"
    }
}

1. RegistrierenIn OnInitializeMelon: ModKit.Register(new ItemGiverMod(), ConfigFile.For("example.itemgiver"));
2. Welt als Host startenTryGive funktioniert nur auf dem Host (sonst Meldung not hosting).
3. TestenF6 drücken – das Item landet im Inventar. Item-ID und Menge in UserData/SDModKit/example.itemgiver.cfg ändern.

Zähler-Part mit Menü

Ein Part, der beim Interagieren ein Menü mit Zählerstand und zwei Buttons zeigt. Zeigt das Zusammenspiel von DescribeConfig, ContentActions.Send und OnAction – funktioniert auch im Multiplayer.

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

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

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

        rows.Add(new ConfigRow { Section = "Zählerstand" });
        rows.Add(new ConfigRow
        {
            Label      = "Wert",
            Value      = count.ToString(),
            ValueColor = count > 0 ? Theme.Good : Theme.TextDim
        });
        rows.Add(new ConfigRow
        {
            Label    = "Aktion",
            Choices  = new[] { "+1", "Zurücksetzen" },
            OnChoose = i => ContentActions.Send(part, i == 0 ? "inc" : "reset")
        });
    }

    // läuft nur auf dem Host
    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": "Zähler",
      "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. State-Klasse prüfenStorageChestState ist ein Platzhalter. Den echten Namen liefert der Dump (F9 auf eine Kiste zielen).
2. BauenDen orangen Würfel aus dem Baumenü platzieren.
3. TestenInteragieren → Menü „Zähler“ erscheint. „+1“ erhöht den Wert, „Zurücksetzen“ setzt ihn auf 0. Nach Speichern und Neuladen bleibt der Wert erhalten.

Live-Display

Ein Part mit Bildschirm, der laufend die Spielzeit und die Rolle (Host/Client) anzeigt. Zeigt shape: "screen" und 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. BauenDen Part platzieren – der Bildschirm zeigt sofort Rolle und Zeit.
2. Lauftext testenScroll = true im ScreenFrame setzen und im JSON "columns": 12 ergänzen.

Einstellungsseite mit Reset

Eine Seite im Mod-Menü mit Schalter, Regler und einem „Zurücksetzen“-Button, der vorher einen Bestätigungsdialog im Spieldesign zeigt.

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, "Funktion an/aus");
        _strength = Config.Bind("General", "Strength", 0.5f, "Stärke 0–1");
        AddPage("Einstellungen", Draw);
    }

    private void Draw()
    {
        ModUi.Section("Allgemein", () =>
        {
            ModUi.Row("Aktiv",  () => _enabled.Value  = ModUi.Toggle(_enabled.Value, "an"));
            ModUi.Row("Stärke", () => _strength.Value = ModUi.Slider(_strength.Value, 0f, 1f));
            ModUi.Note("Aktueller Wert: " + _strength.Value.ToString("0.00"));
        });

        if (ModUi.Button("Auf Standard zurücksetzen"))
        {
            GameModal.Open("Zurücksetzen?", "Alle Werte dieser Mod gehen verloren.", new[]
            {
                new ModalChoice { Label = "Abbrechen" },
                new ModalChoice { Label = "Zurücksetzen", Bad = true, OnPick = () =>
                {
                    _enabled.Value  = _enabled.DefaultValue;
                    _strength.Value = _strength.DefaultValue;
                    Toasts.Show("Einstellungen zurückgesetzt");
                }}
            });
        }
    }
}

1. Mod-Menü öffnenMit Dev-Mod über Einfg, sonst per ModKit.OpenMenu() (siehe Das Mod-Menü).
2. TestenWerte ändern, Spiel neu starten – die Werte stehen in UserData/SDModKit/example.settings.cfg und bleiben erhalten.

Lebenszyklus

Die Reihenfolge, in der SDModKit und deine Mod aufgerufen werden:

Multiplayer

StellarDrive nutzt FishNet. SDModKit trennt sauber zwischen Host und Client:

Nützlich für Prüfungen: GameRefs.IsServer, GameRefs.IsClient, ModUi.Hosting().

Speicherung

Beim Speichern der Welt schreibt ContentSave die Datei sdmodkit-content.json in den Ordner des Spielstands. Beim Laden (GameLoader.LoadState) wird sie wieder eingelesen.

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

API-Index

Alle öffentlichen Klassen von SDModKit 1.3.3 mit ihren öffentlichen Mitgliedern – automatisch aus dem Quellcode erzeugt. Tippe in das Feld, um zu filtern.

Konstanten & Standardwerte

Das Mod-Menü

SDModKit bringt ein eigenes Ingame-Menü mit. Jede Mod bekommt dort ihre Seiten, dazu kommen die Kit-Seiten Keybinds, Content und Diagnostics.

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

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

Seite Content

Übersicht über alle geladenen Packs, Parts und Items mit ihren Problemen sowie die letzten Meldungen aus ContentLog (Button „Clear“ leert das Log).

Seite Diagnostics

Zeigt den Part im Fadenkreuz („Aiming at“), die Liste Patches that did not bind (fehlgeschlagene Harmony-Patches, z. B. nach Spiel-Updates) und den Bereich Write a dump mit einzelnen Dump-Buttons: Everything, Aimed part, Menu prefabs, Snapping table, Cables, Content parts und Vanilla part.

Kit-Einstellungen in stellardrive.modkit.cfg: Diagnostics.VerboseLog (Trace-Meldungen) und Diagnostics.DumpOnWorldEnter (Dump bei jedem Weltstart).

Dumps

Dumps sind Textdateien unter UserData/SDModKit/Dumps/. Sie sind das wichtigste Werkzeug, um Asset-Namen, State-Klassen, Kind-Pfade (für donorPath) und Materialien herauszufinden.

string path = SDModKit.Util.Dump.Everything();   // alles
SDModKit.Util.Dump.Write("meinDump", sb => sb.AppendLine("eigener Inhalt"));
// letzter Pfad: SDModKit.Util.Dump.LastPath

Log-Meldungen

Die Meldungen erscheinen im MelonLoader-Log (MelonLoader/Latest.log) und auf der Content-Seite des Mod-Menüs. Filtere nach einem Stück des Textes:

Häufige Fragen