Sandustry Modding-API-Leitfaden

Die Sandustry Modding-API ist das offizielle Modding-Framework von Lantto Games, veröffentlicht mit der v0.5.5+-Ankündigung am 29. August 2026. Sie unterstützt sowohl Lua (Einstiegsebene, ideal für einfache QoL-Mods und Einsteiger) als auch C# (für komplexe Systeme, die direkten Zugriff auf die Spiel-Engine erfordern). Dieser umfassende Leitfaden erklärt die vollständige Einrichtung der Skripting-Umgebung, das Schreiben deines ersten funktionierenden Mods und die Navigation durch die offizielle API-Dokumentation. Egal, ob du ein einfaches Skript für bessere Gold-Ausbeute schreiben möchtest oder eine vollständig neue Produktionskette implementieren willst — hier findest du alle Grundlagen.

Voraussetzungen — Was die API kann und was sie nicht kann

Bevor du mit dem Modding beginnst, ist es wichtig zu verstehen, welche Möglichkeiten die API tatsächlich bietet und wo ihre Grenzen liegen. Die Sandustry Modding-API wurde bewusst als sichere Erweiterungsschicht konzipiert, die das Kernspiel unberührt lässt.

Die API erlaubt dir:

• Benutzerdefinierte Gebäude mit neuen Input/Output-Rezepten, individueller Stromaufnahme und visuellen Sprites erstellen — du kannst vollständig neue Fabrikgebäude definieren, die sich nahtlos ins Spiel einfügen.
• Override der prozeduralen Generierung für Terrain, Biomes und Ressourcenverteilung vornehmen — so kannst du die Weltgenerierung nach deinen Wünschen anpassen.
• Forschungsbaumknoten hinzufügen, entfernen oder umordnen — du hast die volle Kontrolle über den Forschungsfortschritt.
• Neue Materialverhaltensweisen definieren und deren Interaktion mit Hitze, Druck und bestehenden Spielsystemen festlegen.
• Benutzerdefinierte UI-Panels, Tooltips und Menüoptionen hinzufügen, um das Spielerlebnis zu erweitern.

Die API erlaubt NICHT:

• Multiplayer-Funktionalität hinzuzufügen — das erfordert grundlegende Engine-Änderungen jenseits der Skriptschicht, die von der API nicht abgedeckt werden.
• Die Kern-Sandbox-Physik zu ersetzen — Sand-, Wasser- und Wärmesimulation sind engine-level implementiert und können nicht durch Skripte verändert werden.
• Direkten Zugriff auf Speicherdateiformate — dafür existiert Fluxloader als separate Lösung.

Sandustry Fabrik-Automatisierungs-Gebäude-Übersicht

Einrichtung der Skripting-Umgebung

Lua-Loader installieren

Die Installation des Lua-Loaders ist der einfachste Weg, um mit dem Modding zu beginnen. Lua ist ideal für Einsteiger, da es keine Compiler-Tools erfordert und Änderungen sofort getestet werden können.

1. Öffne Sandustry und navigiere zu Settings → Mods → Script Loaders.
2. Aktiviere Lua Script Loader mit einem Klick auf den Umschalter.
3. Das Spiel erstellt automatisch einen scripts/lua/-Ordner in deinem persönlichen Sandustry-Benutzerverzeichnis unter %AppData%\sandustry\scripts\lua\ auf Windows.
4. Platziere einfach eine .lua-Datei in diesem Ordner — sie wird automatisch beim nächsten Spielstart geladen, ohne dass zusätzliche Konfiguration erforderlich ist.

C#-Loader installieren

Der C#-Loader bietet vollen Zugriff auf die Spiel-Engine, erfordert aber etwas mehr Setup-Aufwand. Er ist die richtige Wahl für komplexe Mods, die maximale Leistung und engine-level Funktionalität benötigen.

1. Installiere zuerst Fluxloader — der offizielle C#-Loader ist davon abhängig. Eine detaillierte Anleitung findest du unter Fluxloader installieren.
2. Aktiviere dann C# Script Loader in Settings → Mods → Script Loaders.
3. Erstelle ein C#-Projekt mit dem offiziellen Vorlagenpaket aus den API-Dokumentationen — es enthält alle notwendigen Referenzen und ein Grundgerüst.
4. Kompiliere das Projekt zur .dll-Datei und platziere sie im Verzeichnis %AppData%\sandustry\scripts\csharp\.

Dein erstes Lua-Mod in 10 Minuten

Der klassische Starter-Mod: Ein Gold-Bonus-Skript, das jedes Mal einen kleinen Gold-Bonus hinzufügt, wenn ein Shaker Gold produziert. Dieses Beispiel demonstriert Material-Abfang, Event-Hooks und UI-Benachrichtigungen — die drei Grundpfeiler der meisten Sandustry-Mods.

-- gold_bonus.lua
-- Fügt +5% Gold-Ausbeute von Shakern hinzu (stapelt mit bestehenden Raten)

local BONUS_RATE = 0.05

-- Lauscht auf das ShakerOutput-Event
Events.OnShakerOutput(function(event)
  local shaker = event.shaker
  local goldProduced = event.gold
  
  if goldProduced > 0 then
    local bonus = math.floor(goldProduced * BONUS_RATE)
    if bonus > 0 then
      -- Fügt Bonus-Gold zur Shaker-Ausgabe hinzu
      shaker:AddOutput("Gold", bonus)
      
      -- Zeigt eine kleine Benachrichtigung
      Game.Notify("Gold Bonus!", "+" .. bonus .. " gold from shaker yield", "icons/gold")
    end
  end
end)

Speichere dies als gold_bonus.lua und lege die Datei in den Lua-Skripte-Ordner. Beim nächsten Spielstart wird die Shaker-Ausgabe automatisch um 5 % erhöht — ohne das Spiel neu starten zu müssen, wenn du Hot-Reload nutzt.

Benutzerdefinierte Gebäude in Lua

Eigene Gebäude sind das Herzstück vieler Sandustry-Mods. Die Buildings-API ermöglicht es dir, vollständig neue Produktionsgebäude zu registrieren, die im Spiel erscheinen und funktionieren wie native Gebäude.

Buildings.Register("CustomGlassFurnace", {
  DisplayName = "Glass Furnace",
  Description = "Smelts Sand into Glass using heat.",
  Category = "refining",
  Size = { width = 2, height = 2 },
  Cost = { Gold = 500 },
  Inputs = { { material = "Sand", rate = 2 } },
  Outputs = { { material = "Glass", rate = 1 } },
  HeatRequired = true,
  PowerDraw = 10,
  OnTick = function(building)
    local sand = building:GetInput("Sand")
    if sand >= 2 then
      building:ConsumeInput("Sand", 2)
      building:ProduceOutput("Glass", 1)
    end
  end
})

Nach dem Laden dieses Skripts erscheint eine Glass Furnace-Gebäudekarte in der Refining-Kategorie, sobald der Spieler die entsprechende Forschungsstufe freigeschaltet hat. Du kannst beliebig viele Eingabe- und Ausgabematerialien definieren, Wärme- und Stromanforderungen festlegen und die Baukosten in verschiedenen Ressourcen angeben.

Forschungsbaum-Modifikationen

Mit der Research-API hast du vollständige Kontrolle über den Forschungsbaum. Du kannst neue Knoten hinzufügen, die bestehenden ändern oder ganze Pfade umgestalten.

Research.AddNode({
  id = "CustomSmelting",
  name = "Advanced Smelting",
  description = "Unlocks the Glass Furnace.",
  cost = 1000,
  tier = 3,
  category = "refining",
  unlock = function(player)
    player:UnlockBuilding("CustomGlassFurnace")
  end
})

Dieses Beispiel fügt einen neuen Forschungsnode namens “Advanced Smelting” in Tier 3 der Refining-Kategorie hinzu. Sobald der Spieler die erforderlichen Forschungspunkte investiert hat, wird automatisch das CustomGlassFurnace-Gebäude freigeschaltet.

C# — Wann man es verwendet

Wähle C# als Sprache, wenn dein Mod eine der folgenden Anforderungen erfüllt: Zugriff auf die vollständige Spiel-Engine über engine-level Klassen, leistungskritischer Code, der jede Millisekunde zählt (C# ist deutlich schneller als Lua bei rechenintensiven Tick-Logiken), benutzerdefinierte Rendering- oder Sprite-Manipulation, oder die Integration mit externen .NET-Bibliotheken. Die C#-API spiegelt die Lua-API wider, legt aber alle engine-level Klassen offen. Die offiziellen Dokumentationen enthalten eine vollständige C#-Projektvorlage mit einem funktionierenden Beispielgebäude und Forschungsnode.

Debugging und Testen von Mods

Effektives Debugging ist entscheidend für die Mod-Entwicklung. Sandustry bietet mehrere integrierte Tools, die dir helfen, Fehler schnell zu finden und zu beheben.

• In-Game-Konsole: Drücke F5 (konfigurierbar in den Einstellungen), um die Sandustry-Konsole zu öffnen. Mod-Fehler werden hier mit Dateinamen und Zeilennummern ausgegeben, was die Fehlersuche erheblich beschleunigt.
• Log-Dateien: Mod-Logs werden in %AppData%\sandustry\logs\scripting.log geschrieben. Überprüfe diese Datei, wenn ein Mod gar nicht erst lädt oder stillschweigend fehlschlägt — der Log enthält oft detaillierte Fehlermeldungen, die in der Konsole nicht erscheinen.
• Fluxloader-Ladereihenfolge: Wenn du sowohl den offiziellen API-Loader als auch Fluxloader verwendest, lädt Fluxloader zuerst. Mods, die voneinander abhängen, müssen ihre Ladereihenfolge in fluxloader.json deklarieren, um Konflikte zu vermeiden.
• Hot-Reload: Speichere deine .lua- oder .dll-Datei während das Spiel läuft — der Loader versucht, sie automatisch neu zu laden. Wenn der Hot-Reload fehlschlägt, beende zum Hauptmenü und starte erneut.

Performance-Tipps für benutzerdefinierte Gebäude

Bei der Entwicklung eigener Gebäude solltest du von Anfang an auf Performance achten. Ein schlecht optimiertes Gebäude kann den gesamten Factory-Durchsatz hemmen.

• Material-Lookups zwischenspeichern: Der Aufruf von building:GetInput() in jedem Frame ist teuer — speichere Referenzen bei der Gebäudeerstellung in OnCreate, um wiederholte Lookups zu vermeiden.
• Benachrichtigungen drosseln: Feuere keine UI-Benachrichtigung in jedem einzelnen Tick — verwende einen Cooldown-Zähler, um die Benachrichtigungsrate zu begrenzen und die UI-Last zu reduzieren.
• Vermeide Pixel-genaues Rechnen in OnTick: Halte die Tick-Logik so leicht wie möglich; verlagerst du schwere Berechnungen in eine separate Coroutine, bleibt das Spiel flüssig.
• Vor dem Veröffentlichen profilen: Nutze den In-Game-Profiler (F3 → Performance), um den CPU-Anteil deines Mods zu überprüfen und Engpässe zu identifizieren, bevor andere Spieler dein Mod nutzen.

Veröffentlichung deines Mods

Wenn dein Mod bereit für die Community ist, folge diesen Schritten für eine erfolgreiche Veröffentlichung:

1. Teste gründlich auf einer frischen Speicherdatei — nicht nur auf einem bestehenden Spielstand, da Mods unerwartet mit anderen Skripten oder gespeicherten Daten interagieren können.
2. Schreibe ein aussagekräftiges README, das erklärt, was das Mod macht, welche Anforderungen es gibt, welche Spielversion es benötigt und für welche Spielstufe es geeignet ist.
3. Veröffentliche auf dem Steam Workshop über das In-Game-Menü Mods → Publish. Verwende aussagekräftige Tags wie Lua oder C# sowie API für bessere Auffindbarkeit in der Community.
4. Aktualisiere deine Workshop-Seite regelmäßig bei neuen Versionen — abonnierte Spieler werden automatisch benachrichtigt und erhalten die neueste Version.

Verwandte Seiten

• SandPrints Blueprint-Sharing — Teile und lade Fabrik-Layouts aus der Community-Datenbank herunter.
• Fluxloader installieren — Installiere Fluxloader, bevor du C#-Mods verwendest.
• SandTogether Co-op-Mod — Das Koop-Mod, das die Fluxloader-Pipeline nutzt.
• Custom Maps — Community-Map-Loader für vordefinierte Gelände.
• Mods Hub — Alle Community-Tools an einem Ort.
• Updates Hub — Offizielle Patchnotes und Roadmap-Signale.

Modding bei Sandustry ist die tiefste Form der Beherrschung — wenn du die Factory-Schleife so gut verstehst, dass du sie einem Skript beibringen kannst, bist du bereit, dich als echten Sandustry-Ingenieur zu bezeichnen.