Skip to content

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Sandustry mods

English · Русский

Eleven mods for Sandustry, built on the game's official Sandkit API — no third-party loader, no patched app.asar. Subscribe on the Workshop and they load.

mod what it does Workshop
Steam Turbine Mk2 A second tier of steam turbine that pays out several times the energy from the same steam. 3783707406
Map Studio Generate your own world from a seed in the main menu and play it — and it unlocks the game's own hidden custom-map browser. not published
Stuck Mouse Button Fix Replays a mouse release the game missed, so the vacuum stops spraying on its own and a button cannot stay held down. 3784803741
Atomic Age A full nuclear chain: silicon and acid chemistry, a uranium fuel cycle, and a reactor. Guide 3784544373
Electric Thermal Buffers Thermal Buffers on grid power, heating or chilling to a target — with a click panel on the machine and Filter-style build presets. 3783398003
Flow Meter Throughput readout for belts and filters — how much is actually moving. 3783111599
Power Monitor A compact summary of whether your grid is winning or losing. 3783239581
Mod Inspector Every mod you have loaded and why it failed, a Workshop dashboard with votes and visibility, one-click local-mod upload. 3783397350
Debug Toggle Switches for the game's own built-in debug tools. 3783406459
Creative Mode Cheats, an element brush and an inspector in one floating panel. not published
Extra Video Settings Graphics settings that already work in the game but have no control. not published

Each mod is a folder the game loads directly. Copy one into your mods folder and it runs — no build step.

macOS    ~/Library/Application Support/sandustry/mods/
Windows  %AppData%\sandustry\mods\

Working on them

The game reads mods from its own folder, so the repository and that folder have to be kept in step:

npm run sync              # what differs, in both directions
npm run sync:to-game      # repository  ->  game folder
npm run sync:from-game    # game folder ->  repository

workshop.json is never deleted by a sync — the game writes it, and it carries the published item id. Lose it and the next upload creates a duplicate Workshop entry instead of updating the existing one.

Why not just symlink the folder? Because the game rejects every mod if you do. Its loader checks that modinfo.json sits inside the mod folder by comparing the folder path as given against a realpath'd manifest path, and through a symlink those two never agree — every mod fails with manifest_outside_folder. Its preview.png check resolves both sides and works fine, so the two containment checks disagree with each other. Copying is the workaround until that is fixed.

Conventions

Every mod here follows two rules that are worth adopting more widely:

A mod only appears in Options → Mods if it declares a non-empty configSchema. That is the game's behaviour, not a choice.

The first setting is always enabled. The game has no built-in way to switch a mod off without unsubscribing, so this stands in for one. The reasoning and a proposal for making it a shared convention (ru).

Validating before you launch

The game's own loader is plain CommonJS inside app.asar, so it can be called directly. That catches manifest errors, a missing preview.png, and the syntax mistakes that otherwise fail silently — an import in an entry throws Unexpected token 'export' and the mod simply never runs, with nothing in the UI to say so.

node scripts/validate.js              # every mod
node scripts/validate.js flow-meter   # one of them

It extracts the loader from your own installation on first run, into .loader/ (git-ignored). Set SANDUSTRY_RESOURCES if the game is somewhere unusual.

Notes for anyone writing a mod

Cookbook — "I want to do X" mapped to the mod here that already does it, and the trap that comes with it. examples/starter is a minimal skeleton to copy.

CLAUDE.md is the working notes behind these mods: the traps, the reasons behind non-obvious choices, and what the API does and does not allow. It is written for whoever picks the code up next.

For the API itself, there is a generated map of the whole surface — every method a mod can reach, and the limits that are not documented anywhere: sandkit-surface-map.

Also here: enabling the game's hidden debug menu, which needs no mods at all.

Map Studio — the world editor

Not only a mod — also a page. Map Studio generates a Sandustry world from a seed in your browser, lets you paint on it with the game's own terrain palette, and hands it back to the game two ways: a share code (seed plus sliders, pasted into the in-game panel) or a .custommap file dropped into your custom_maps folder.

The generator lives in one file, docs/map-studio/generator.js. The page loads it; the mod carries a verbatim copy because a mod entry cannot import anything, and npm run test:map-studio renders worlds with both and compares them byte for byte. That is what makes a share code trustworthy — it is only a seed and nine numbers, so two generators disagreeing by one constant would silently open a different world on each side.

Save Doctor

Not a mod — a page. Save Doctor reads a .save file, finds story softlocks in it and repairs them, entirely in your browser. The file is never uploaded anywhere.

It exists because of one dead end in particular: a story step flagged blocksFactoryLevel pins store.factoryLevelCap to your current tier and is supposed to release it on completion. When the step completes and the cap survives, the story asks you to reach the next tier while the leftover cap makes that impossible — and the tech-tree unlock button is disabled by the same condition, so there is no way out from inside the game. Five more desync checks come with it.

Only story-lock state is touched: resources, tech, achievements and store.integrity are left alone. Source and rules in docs/save-doctor.

Status

All eight are alpha. They work, and the descriptions state their limits honestly, but expect rough edges and breaking changes between versions. Bug reports and feedback are welcome.

Licence

MIT. Not affiliated with Sandustry or its developers.

About

Mods for Sandustry, built on the official Sandkit API. No loader required.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages