Guía de la API de Modding Sandustry

La API de Modding Sandustry es el framework de modding oficial publicado por Lantto Games junto con el anuncio v0.5.5+ del 29 de agosto de 2026. Soporta Lua (nivel iniciación, ideal para mods QoL sencillos) y C# (para sistemas complejos que necesitan acceso directo al motor de juego). Esta guía completa cubre la configuración del entorno de scripting, la escritura de tu primer mod funcional y la navegación por la documentación oficial de la API. Ya sea que quieras crear un simple script para mejorar el rendimiento del oro o implementar una cadena de producción completamente nueva, esta guía te acompaña en cada paso.

Lo que la API puede y no puede hacer

Antes de comenzar con el modding, es esencial entender exactamente qué posibilidades ofrece la API Sandustry y dónde están sus límites. La API fue diseñada deliberadamente como una capa de extensión segura que preserva la integridad del juego base.

La API te permite:

• Crear edificios personalizados con nuevas recetas de entrada/salida, consumo de energía personalizado y sprites visuales — puedes definir edificios de fábrica completamente nuevos que se integran perfectamente en el juego.
• Reemplazar la generación procedural para terreno, biomas y distribución de recursos — puedes adaptar la generación del mundo según tus preferencias.
• Agregar, eliminar o reordenar nodos del árbol de investigación — tienes control total sobre el progreso de investigación.
• Definir nuevos comportamientos de materiales y su interacción con el calor, la presión y los sistemas de juego existentes.
• Agregar paneles UI personalizados, tooltips y opciones de menú para enriquecer la experiencia del jugador.

La API NO te permite:

• Agregar contenido multijugador — eso requiere cambios a nivel del motor más allá de la capa de scripting, que la API no puede proporcionar.
• Reemplazar la física principal del sandbox — la simulación de arena, agua y calor está implementada a nivel del motor y no puede ser modificada por scripts.
• Acceder directamente a formatos de archivos de guardado — usa Fluxloader como solución separada para manipulación de guardados.

Descripción general de edificios de automatización de fábricas Sandustry

Configuración del entorno de scripting

Instalación del loader de Lua

La instalación del loader de Lua es el camino más sencillo para comenzar con el modding. Lua es ideal para principiantes porque no requiere herramientas de compilación y los cambios pueden probarse inmediatamente.

1. Abre Sandustry y navega a Settings → Mods → Script Loaders.
2. Activa Lua Script Loader con un clic en el interruptor correspondiente.
3. El juego crea automáticamente una carpeta scripts/lua/ en tu directorio de usuario personal bajo %AppData%\sandustry\scripts\lua\ en Windows.
4. Simplemente coloca un archivo .lua en esta carpeta — se cargará automáticamente al siguiente inicio del juego, sin necesidad de configuración adicional.

Instalación del loader de C#

El loader de C# ofrece acceso completo al motor de juego pero requiere un poco más de configuración. Es la elección correcta para mods complejos que necesitan máximo rendimiento y funcionalidad a nivel del motor.

1. Instala Fluxloader primero — el loader de C# oficial depende de él. Consulta Instalar Fluxloader para instrucciones detalladas.
2. Luego activa C# Script Loader en Settings → Mods → Script Loaders.
3. Crea un proyecto C# usando la plantilla oficial incluida en la documentación de la API — contiene todas las referencias necesarias y una estructura base.
4. Compila el proyecto a archivo .dll y colócalo en el directorio %AppData%\sandustry\scripts\csharp\.

Tu primer mod de Lua en 10 minutos

El mod de inicio clásico: un script de Gold Bonus que agrega un pequeño bonus de oro cada vez que un Shaker produce oro. Este ejemplo demuestra la interceptación de materiales, los hooks de eventos y las notificaciones UI — los tres pilares fundamentales de la mayoría de los mods de Sandustry.

-- gold_bonus.lua
-- Agrega +5% de rendimiento de oro a los Shakers (se apila con tasas existentes)

local BONUS_RATE = 0.05

-- Escucha el evento 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
      -- Agrega oro bonus a la salida del Shaker
      shaker:AddOutput("Gold", bonus)
      
      -- Muestra una pequeña notificación
      Game.Notify("Gold Bonus!", "+" .. bonus .. " gold from shaker yield", "icons/gold")
    end
  end
end)

Guarda esto como gold_bonus.lua y coloca el archivo en la carpeta de scripts Lua. En el próximo inicio, la salida del Shaker aumentará automáticamente un 5 % — sin necesidad de reiniciar el juego si usas Hot-Reload.

Edificios personalizados en Lua

Los edificios personalizados son el corazón de muchos mods de Sandustry. La API Buildings te permite registrar edificios de producción completamente nuevos que aparecen y funcionan como edificios nativos del juego.

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

Después de cargar este script, una tarjeta de edificio Glass Furnace aparecerá en la categoría Refining tan pronto como el jugador alcance el nivel de investigación correspondiente. Puedes definir tantos materiales de entrada y salida como necesites, especificar requisitos de calor y electricidad, y establecer los costos de construcción en varios recursos.

Modificaciones del árbol de investigación

Con la API Research, tienes control total sobre el árbol de investigación. Puedes agregar nuevos nodos, modificar los existentes o reestructurar rutas enteras.

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

Este ejemplo agrega un nuevo nodo de investigación llamado “Advanced Smelting” en el Tier 3 de la categoría Refining. Una vez que el jugador ha invertido los puntos de investigación requeridos, el edificio CustomGlassFurnace se desbloquea automáticamente.

C# — Cuándo usarlo

Elige C# cuando tu mod cumpla con alguno de estos requisitos: acceso completo al motor de juego a través de clases de nivel motor, código crítico para el rendimiento donde cada milisegundo cuenta (C# es significativamente más rápido que Lua para lógicas de tick intensivas), renderizado personalizado o manipulación de sprites, o integración con bibliotecas .NET externas. La API C# refleja la API Lua pero expone todas las clases de nivel motor. La documentación oficial incluye una plantilla de proyecto C# completa con un ejemplo de edificio personalizado funcional.

Depuración y prueba de mods

La depuración efectiva es crucial para el desarrollo de mods. Sandustry ofrece múltiples herramientas integradas para ayudarte a encontrar y corregir errores rápidamente.

• Consola in-game: Presiona F5 (configurable en ajustes) para abrir la consola Sandustry. Los errores de mods se muestran aquí con nombres de archivo y números de línea, lo que acelera enormemente la búsqueda de problemas.
• Archivos de log: Los logs de mods se escriben en %AppData%\sandustry\logs\scripting.log. Consulta este archivo si un mod no se carga en absoluto o falla silenciosamente — el log frecuentemente contiene mensajes de error detallados que no aparecen en la consola.
• Orden de carga de Fluxloader: Si usas tanto el loader API oficial como Fluxloader, Fluxloader carga primero. Los mods que dependen entre sí deben declarar su orden de carga en fluxloader.json para evitar conflictos.
• Hot-reload: Guarda tu archivo .lua o .dll mientras el juego está corriendo — el loader intentará recargarlo automáticamente. Si el hot-reload falla, sal al menú principal y reinicia.

Publicación de tu mod

Cuando tu mod esté listo para la comunidad, sigue estos pasos para una publicación exitosa:

1. Prueba exhaustivamente en una partida fresca — no solo en una partida existente, ya que los mods pueden interactuar de maneras inesperadas con otros scripts o datos guardados.
2. Escribe un README claro que explique qué hace el mod, qué requisitos tiene, qué versión del juego necesita y para qué nivel de jugador es adecuado.
3. Publica en Steam Workshop usando el menú in-game Mods → Publish. Usa etiquetas descriptivas como Lua o C# según el lenguaje, y API para una mejor descubribilidad en la comunidad.
4. Actualiza tu página de Workshop con cada nueva versión — los suscriptores son notificados automáticamente y reciben la última versión.

Páginas relacionadas

• Compartir Blueprints SandPrints — Comparte y descarga layouts de fábricas desde la base de datos de blueprints comunitarios.
• Instalar Fluxloader — Instala Fluxloader antes de usar mods C#.
• Mod Cooperativo SandTogether — El mod cooperativo construido usando el pipeline de Fluxloader.
• Mapas Personalizados — Loader de mapas comunitarios para terreno predefinido.
• Mods Hub — Todas las herramientas comunitarias en un solo lugar.
• Updates Hub — Notas de parches oficiales y señales de roadmap.

Hacer mods en Sandustry es la forma más profunda de dominio — si entiendes el bucle de fábrica lo suficientemente bien como para enseñárselo a un script, estás listo para llamarte ingeniero de Sandustry.