Guide de l'API Modding Sandustry

L’API Modding Sandustry est le framework de modding officiel publié par Lantto Games avec l’annonce v0.5.5+ du 29 août 2026. Elle supporte Lua (niveau débutant, idéal pour les mods QoL simples) et C# (pour les systèmes complexes nécessitant un accès direct au moteur de jeu). Ce guide complet couvre la configuration de l’environnement de scripting, l’écriture de votre premier mod fonctionnel et la navigation dans la documentation API officielle. Que vous souhaitiez créer un simple script d’amélioration du rendement ou implémenter une chaîne de production entièrement nouvelle, ce guide vous accompagne à chaque étape.

Ce que l’API peut et ne peut pas faire

Avant de commencer le modding, il est essentiel de bien comprendre les possibilités et les limites de l’API Sandustry. Celle-ci a été conçue comme une couche d’extension sécurisée qui préserve l’intégrité du jeu de base.

L’API vous permet :

• Créer des bâtiments personnalisés avec de nouvelles recettes d’entrée/sortie, une consommation d’énergie personnalisée et des sprites visuels — vous pouvez définir des bâtiments d’usine entièrement nouveaux qui s’intègrent parfaitement au jeu.
• Remplacer la génération procédurale pour le terrain, les biomes et la distribution des ressources — modifiez la génération du monde selon vos préférences.
• Ajouter, supprimer ou réorganiser les nœuds de l’arbre de recherche — vous avez un contrôle total sur la progression de la recherche.
• Définir de nouveaux comportements de matériaux et leur interaction avec la chaleur, la pression et les systèmes de jeu existants.
• Ajouter des panneaux UI personnalisés, des infobulles et des options de menu pour enrichir l’expérience joueur.

L’API ne vous permet PAS :

• Ajouter du contenu multijoueur — cela nécessite des modifications au niveau du moteur qui dépassent le cadre de la couche de script.
• Remplacer la physique principale du bac à sable — la simulation du sable, de l’eau et de la chaleur est implémentée au niveau du moteur et ne peut pas être modifiée par des scripts.
• Accéder directement aux formats de fichiers de sauvegarde — utilisez Fluxloader pour les mods de manipulation de sauvegarde.

Vue d'ensemble des bâtiments d'automatisation de factory Sandustry

Configuration de l’environnement de scripting

Installation du loader Lua

L’installation du loader Lua est la voie la plus simple pour commencer le modding. Lua est idéal pour les débutants car il ne nécessite aucun outil de compilation et les modifications peuvent être testées immédiatement.

1. Ouvrez Sandustry et allez dans Settings → Mods → Script Loaders.
2. Activez Lua Script Loader en basculant l’interrupteur correspondant.
3. Le jeu crée automatiquement un dossier scripts/lua/ dans votre répertoire utilisateur personnel sous %AppData%\sandustry\scripts\lua\ sur Windows.
4. Placez simplement un fichier .lua dans ce dossier — il se chargera automatiquement au prochain lancement du jeu, sans configuration supplémentaire nécessaire.

Installation du loader C#

Le loader C# offre un accès complet au moteur de jeu mais demande un peu plus de configuration. Choisissez-le pour les mods complexes qui nécessitent des performances maximales et des fonctionnalités au niveau du moteur.

1. Installez d’abord Fluxloader — le loader C# officiel en dépend. Consultez Installer Fluxloader pour des instructions détaillées.
2. Activez ensuite C# Script Loader dans Settings → Mods → Script Loaders.
3. Créez un projet C# en utilisant le modèle officiel fourni dans la documentation API — il contient toutes les références nécessaires et une structure de base.
4. Compilez le projet en fichier .dll et placez-le dans le répertoire %AppData%\sandustry\scripts\csharp\.

Votre premier mod Lua en 10 minutes

Le mod de démarrage classique : un script Gold Bonus qui ajoute un petit bonus d’or à chaque production de Shaker. Cet exemple démontre l’interception de matériaux, les hooks d’événements et les notifications UI — les trois piliers fondamentaux de la plupart des mods Sandustry.

-- gold_bonus.lua
-- Ajoute +5% de rendement en or aux Shakers (se cumule avec les taux existants)

local BONUS_RATE = 0.05

-- Écoute l'événement ShakerOutput
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
      -- Ajoute l'or bonus à la sortie du Shaker
      shaker:AddOutput("Gold", bonus)
      
      -- Affiche une petite notification
      Game.Notify("Gold Bonus!", "+" .. bonus .. " gold from shaker yield", "icons/gold")
    end
  end
end)

Enregistrez ceci sous gold_bonus.lua et placez le fichier dans le dossier des scripts Lua. Au prochain lancement, la sortie du Shaker augmentera automatiquement de 5 % — sans avoir à redémarrer le jeu si vous utilisez le Hot-Reload.

Bâtiments personnalisés en Lua

Les bâtiments personnalisés sont au cœur de nombreux mods Sandustry. L’API Buildings vous permet d’enregistrer des bâtiments de production entièrement nouveaux qui apparaissent et fonctionnent comme des bâtiments natifs du jeu.

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
})

Après le chargement de ce script, une carte de bâtiment Glass Furnace apparaît dans la catégorie Refining dès que le joueur atteint le niveau de recherche correspondant. Vous pouvez définir autant de matériaux d’entrée et de sortie que nécessaire, spécifier les exigences en chaleur et en électricité, et définir les coûts de construction dans diverses ressources.

Modifications de l’arbre de recherche

Avec l’API Research, vous avez un contrôle total sur l’arbre de recherche. Vous pouvez ajouter de nouveaux nœuds, modifier les existants ou restructurer des chemins entiers.

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
})

Cet exemple ajoute un nouveau nœud de recherche appelé “Advanced Smelting” au Tier 3 de la catégorie Refining. Une fois que le joueur a investi les points de recherche requis, le bâtiment CustomGlassFurnace est automatiquement débloqué.

C# — Quand l’utiliser

Choisissez C# lorsque votre mod répond à l’une de ces exigences : accès complet au moteur de jeu via des classes de niveau moteur, code critique pour les performances où chaque milliseconde compte (C# est significativement plus rapide que Lua pour les logiques de tick intensives), rendu personnalisé ou manipulation de sprites, ou intégration avec des bibliothèques .NET externes. L’API C# reflète l’API Lua mais expose toutes les classes de niveau moteur. La documentation officielle inclut un modèle de projet C# complet avec un exemple de bâtiment personnalisé fonctionnel.

Débogage et test des mods

Un débogage efficace est crucial pour le développement de mods. Sandustry propose plusieurs outils intégrés pour vous aider à trouver et corriger rapidement les erreurs.

• Console in-game : Appuyez sur F5 (configurable dans les paramètres) pour ouvrir la console Sandustry. Les erreurs de mods s’affichent ici avec les noms de fichiers et les numéros de ligne, accélérant considérablement le dépannage.
• Fichiers log : Les logs de mods sont écrits dans %AppData%\sandustry\logs\scripting.log. Consultez ce fichier si un mod ne se charge pas du tout ou échoue silencieusement — le log contient souvent des messages d’erreur détaillés qui n’apparaissent pas dans la console.
• Ordre de chargement Fluxloader : Si vous utilisez à la fois le loader API officiel et Fluxloader, Fluxloader charge en premier. Les mods dépendants doivent déclarer leur ordre de chargement dans fluxloader.json pour éviter les conflits.
• Hot-reload : Enregistrez votre fichier .lua ou .dll pendant que le jeu est en cours — le loader tentera de le recharger automatiquement. Si le hot-reload échoue, quittez vers le menu principal et relancez.

Publication de votre mod

Lorsque votre mod est prêt pour la communauté, suivez ces étapes pour une publication réussie :

1. Testez soigneusement sur une sauvegarde fraîche — pas seulement sur une sauvegarde existante, car les mods peuvent interagir de manière inattendue avec d’autres scripts ou données enregistrées.
2. Rédigez un README clair décrivant ce que fait le mod, ses exigences, la version du jeu requise et le niveau de joueur auquel il convient.
3. Publiez sur Steam Workshop via le menu in-game Mods → Publish. Utilisez des tags pertinents comme Lua ou C# selon le langage, et API pour une meilleure découvrabilité dans la communauté.
4. Mettez à jour votre page Workshop à chaque nouvelle version — les abonnés sont automatiquement notifiés et reçoivent la dernière version.

Pages connexes

• Partage de blueprints SandPrints — Partagez et téléchargez des layouts d’usines depuis la base de données communautaire.
• Installer Fluxloader — Installez Fluxloader avant d’utiliser des mods C#.
• Mod Co-op SandTogether — Le mod coopératif utilisant le pipeline Fluxloader.
• Cartes personnalisées — Loader de cartes communautaires pour terrain prédéfini.
• Mods Hub — Tous les outils communautaires en un seul endroit.
• Updates Hub — Notes de patch officielles et signaux de feuille de route.

Modder Sandustry est la forme la plus profonde de maîtrise — si vous comprenez la boucle d’usine assez bien pour l’enseigner à un script, vous êtes prêt à vous appeler ingénieur Sandustry.