Sandustry Guide and Wiki

systems

How to Start Modding Sandustry with Sandkit

Players are finding Workshop mods before they find the current API documentation, and the branch names can make a first test look broken. This guide closes that discovery gap with the developer's current announcement, official Sandkit reference and pinned branch instructions. It does not reproduce the API reference, promise backward compatibility, or treat community code as supported game behavior.

Early Access v0.5.6 · modding guidance checked 2026-09-04 · Checked 2026-09-04

Decide whether you need the vanilla or modding branch

Before switching anything, record the branch currently selected in Steam, the game version shown in the interface, and the Workshop items already subscribed. Close the game fully and preserve a known working save through the supported save workflow. This gives you a clean return point if the experimental build or a dependency changes.

Choose the current Mods branch or a compatibility branch

If a Workshop page or repository does not declare a compatible game and API version, treat compatibility as unknown. Do not open your only progressed save to discover the answer. Create a disposable test world, load one mod, and record the exact branch and build. A failure on v0.5.6 does not prove the same mod is broken on its intended older compatibility branch.

Read the official file structure before writing code

Keep the official documentation open and follow its current property names. Do not paste a full third-party mod and rename it: that hides dependencies, risks copying unlicensed work, and makes version errors difficult to isolate. Create your own identifier, name, version and entry file, then add one observable behavior at a time. If the docs change, compare your manifest against the live page rather than an old screenshot or chat excerpt.

Declare version boundaries honestly

Keep a short test matrix beside the project: Sandustry branch, displayed game version, API version, operating system, clean start result, save-load result and known conflicts. When you change a patch or dependency, rerun the smallest affected row. If only 0.5.2 passes, say so. If 0.5.5 is required, make that visible before installation. Unknown should remain unknown until reproduced.

Build and load one minimal vertical slice

Launch the matching experimental branch with only this mod enabled. Record whether the game reaches the menu, creates a new disposable world, reloads it, and exits cleanly. Check the official diagnostic location if the game reports an error, but do not publish logs without reviewing personal paths and identifiers. Once the vertical slice passes twice, add the next capability and repeat.

Diagnose conflicts by reducing the mod set

Do not switch branches repeatedly on the same sole save or delete configuration folders as a first response. Preserve the failing combination, error message and requested log excerpt. Report the smallest reproduction to the creator or official channel named in the current documentation. Community replies can suggest experiments, but they cannot redefine which API surface the developer supports.

Protect saves and achievements from experimental assumptions

Use separate saves for vanilla progression, API development and compatibility testing. Name backups with branch, game version and date. Before removing a mod, check whether the save contains structures, resources or state created by it. A clean startup after removal does not prove that every dependent object was repaired. Keep the original test copy until the replacement state has been inspected and reloaded.

Package and share without overstating support

State the exact branches and versions tested, required dependencies, save risk, known conflicts and a reversible removal boundary. Mark the API as work in progress because the developer does. When a new game or framework build arrives, retest before expanding the compatibility range. A useful release note distinguishes confirmed behavior from plans and gives players enough information to choose a disposable test save first.

Sources and evidence notes

Frequently Asked Questions