Sandustry launches into Early Access on August 13, 2026, and from day one it ships with dedicated modding tools baked into the core experience. The official website states that the game is built with modding in mind, covering custom maps, new buildings, processes, and full overhauls. That means a Sandustry custom recipes mod is not a niche experiment — it is a first-class feature that the developer actively supports. When you define your own inputs and outputs, you reshape how production chains behave, which lets you tune difficulty, create entirely new progression paths, or simply fix a recipe that always felt unbalanced. This matters because recipe logic sits at the heart of every automation loop in the game, so mastering it unlocks the deepest layer of creative control.
The developer also shares modding tools and community mods through the official Sandustry Discord, which makes it easy to see what other players are building before you write your first file. If you have never touched a mod before, do not worry — this guide walks through the entire process from folder structure to JSON syntax, and it assumes zero prior knowledge. By the end, you will have a working custom recipe mod that you can load into the game, plus the confidence to experiment with more ambitious projects like full overhaul mods.
Understanding the Recipe System Before You Mod
Every machine in Sandustry processes inputs into outputs through a recipe definition, and these definitions live in JSON files that the game reads at startup. When you create a Sandustry custom recipes mod, you are essentially telling the game to replace or extend those JSON definitions with your own versions. The core fields you need to understand are the input list, the output list, the processing time, and the machine type that the recipe applies to. Each field has a specific syntax, and getting that syntax right is the difference between a mod that loads cleanly and one that throws errors in the console.
The game's simulation rewrite, which the developer showcased in a before-and-after video on YouTube, changed how recipes are processed under the hood. That update made the system more flexible for modders, but it also means you should always check that your recipe files match the current version of the game. Community reports indicate that recipes written for older builds sometimes fail silently, so it is worth verifying your mod after each game update. The recipe system uses a simple key-value structure, and once you internalize the pattern, you can apply it to every machine in the game.
The Anatomy of a Recipe File
A recipe file follows a predictable structure that mirrors how the game itself defines its default recipes. You start with a JSON object that contains a recipe ID, then you define the input items with their quantities, followed by the output items and their quantities. The processing time is measured in ticks, and the machine type determines which building can run the recipe. Here is the basic shape you will be working with:
{
"id": "my_custom_smelting",
"machine": "furnace",
"inputs": [{"item": "iron_ore", "amount": 2}],
"outputs": [{"item": "iron_ingot", "amount": 1}],
"time": 40
}
The **recipe ID** must be unique across all mods, because the game uses it to resolve conflicts. The **machine field** tells the game which building should accept this recipe, and the **inputs and outputs arrays** define the actual transformation. The **time field** controls how many ticks the machine needs to complete the process, and this directly affects your production throughput calculations. When you start experimenting, try changing just the time value first — it is the safest way to see the system respond without breaking anything else.
### How the Game Resolves Recipe Conflicts
When multiple mods define recipes for the same machine, the game needs a deterministic way to decide which one wins. According to community testing, the game uses a priority system where higher numbers take precedence, and if two mods have the same priority, the game falls back to load order. This matters because a Sandustry custom recipes mod that conflicts with another popular mod can silently override it, producing unexpected results in your factory. The table below summarizes how the resolution works in practice:
| Priority Value | Load Order | Result |
|----------------|------------|--------|
| 100 | Any | Always wins over default recipes |
| 50 | First | Wins over other priority-50 mods |
| 50 | Second | Loses to the first priority-50 mod |
| 0 | Any | Loses to all modded recipes |
The practical takeaway is that you should set a clear priority value in your mod manifest and document it for other players. If you are building a mod for personal use, the default priority is fine, but if you plan to share it through the Sandustry workshop, you want to think about how it interacts with the broader modding ecosystem. A good rule of thumb is to start with priority 50 and adjust only when you encounter a specific conflict.
## Setting Up Your First Mod Project
Before you can write any recipe definitions, you need to create the folder structure that the game expects. The process is straightforward, but it is also where many beginners stumble, so take your time with this section. The game looks for mods in a dedicated directory inside your Sandustry installation folder, and each mod needs its own subfolder with a manifest file that describes the mod to the game. The manifest is a small JSON file that contains the mod name, version, and a list of content files that should be loaded.
The official modding tools shipped with the game include a validator that checks your files for common errors before you even launch Sandustry. This tool is a lifesaver, because it catches typos in item IDs and malformed JSON that would otherwise crash the game at startup. Community reports suggest that most beginner errors come from copying item names incorrectly, so the validator saves hours of frustration. Once your project passes validation, you can load it into the game and test it immediately.
### Creating the Mod Folder Structure
Your mod folder needs to follow a specific layout that the game recognizes. The root folder should have a name that matches your mod ID, and inside it you place the manifest file plus a content folder for your recipe definitions. Here is the structure you should create:
- **Mod root folder** — named after your mod ID, for example `my_custom_recipes`
- **manifest.json** — describes the mod, its version, and its priority
- **content/recipes/** — holds all your custom recipe JSON files
- **content/items/** — optional, for custom items that your recipes reference
The manifest file is the most important piece, because the game reads it first to understand what your mod contains. A minimal manifest looks like this:
```json
The **id field** must match your folder name exactly, and the **content array** lists every JSON file that the game should load. If you add more recipe files later, you need to update this array, which is a common source of confusion for beginners. The validator tool will remind you if you forget, but it is good to understand the relationship between the manifest and your content files.
### Using the Modding Tools That Ship with the Game
Sandustry includes a set of modding tools that the developer updates alongside the main game, and these tools are your best friend when you are learning. The validator catches syntax errors, the item browser lets you look up exact item IDs, and the live reload feature lets you test changes without restarting the game. According to the official website, these tools are a core part of the game's design, not an afterthought, which means they are polished and reliable.
The **item browser** is especially valuable when you are defining a Sandustry custom recipes mod, because it eliminates the guesswork around item names. Instead of typing `iron_ore` and hoping it is correct, you can search for the item and copy its exact ID. This might sound trivial, but community data shows that item ID typos account for a large share of beginner modding errors. The **live reload** feature is the other game-changer, because it lets you tweak recipe values and see the effect immediately, which makes experimentation much more enjoyable.
## Designing Recipes That Improve Gameplay
Once you have the technical basics down, the fun part begins: designing recipes that actually make the game better. A Sandustry custom recipes mod can fix balance issues, create new progression paths, or enable entirely new playstyles. The key is to think about the production chain as a whole rather than individual recipes in isolation. When you change one recipe, you affect everything downstream, so a thoughtful approach produces much better results than random tweaks.
The most common use case reported by players is rebalancing recipes that feel too expensive or too cheap relative to their position in the tech tree. For example, you might decide that a certain component takes too long to craft, so you reduce the processing time or the input quantity. Alternatively, you might want to make a late-game item more accessible by adding a new recipe that uses earlier materials. Both approaches are valid, and the modding system gives you the freedom to explore them.
### Comparing Recipe Balance Strategies
Different players have different philosophies about what makes a good recipe, and understanding these perspectives helps you make better design decisions. The table below compares three common approaches that community modders use when they create custom recipes:
| Strategy | Core Idea | Best For | Risk |
|----------|-----------|----------|------|
| Efficiency Boost | Reduce input costs or processing time | Players who find vanilla recipes grindy | Can trivialize progression |
| Alternative Paths | Add new recipes using different materials | Players who want more flexibility | Can create unintended shortcuts |
| Difficulty Increase | Raise costs or add new intermediate steps | Veterans seeking a harder challenge | Can frustrate casual players |
The **efficiency boost** approach is the most popular for personal mods, because it directly addresses the friction points that players feel during normal play. The **alternative paths** strategy is more creative, but it requires you to think carefully about what materials are available at each stage of the game. The **difficulty increase** approach is rare but valuable for players who have mastered the vanilla game and want a fresh challenge. Whichever strategy you choose, the modding system supports it fully.
### Practical Recipe Examples You Can Copy
To give you a concrete starting point, here are three recipe examples that demonstrate different design goals. The first one reduces the cost of a common building material, the second adds a new way to produce a late-game resource, and the third creates a more expensive but faster alternative. Each example is self-contained and can be dropped into your mod folder after adjusting the item IDs to match your game version:
- **Cheaper bricks** — change the brick recipe to use 1 clay instead of 2, making early construction faster
- **Alternative circuits** — add a recipe that produces circuits from copper wire and iron plates instead of the default materials
- **Fast alloy** — create a high-cost, low-time recipe for steel that uses more coal but completes in half the ticks
These examples illustrate the range of what you can do with a Sandustry custom recipes mod, and they are simple enough to debug when something goes wrong. Start with one of these, get it working, and then experiment with your own ideas. The more you practice, the more natural the JSON syntax becomes, and soon you will be writing complex recipe chains without looking anything up.
## Debugging Recipe Logic and Conflicts
Testing is where many modding projects succeed or fail, and Sandustry gives you solid tools to make the process manageable. The live reload feature is your primary testing tool, because it lets you change a recipe value and see the result in seconds. When you are iterating on a design, this speed is invaluable, and it encourages experimentation rather than cautious guesswork. The validator tool catches structural errors before you load the game, which saves you from the most frustrating type of bug.
However, not all bugs are structural, and some only appear when the recipe interacts with the rest of the game. For example, a recipe might load fine but produce an item that no machine can use, or it might reference a machine type that does not exist. These logical errors require manual testing, and the best approach is to build a small test setup in a creative world. Place the machine, feed it the inputs, and watch what happens. If the recipe does not appear in the machine's menu, the machine type is wrong; if it appears but does not run, the inputs are probably incorrect.
### Common Errors and How to Fix Them
The table below lists the most common errors that community members report when they create custom recipes, along with the typical causes and fixes. This is not an exhaustive list, but it covers the issues that beginners encounter most frequently:
| Error Symptom | Likely Cause | Fix |
|---------------|--------------|-----|
| Recipe does not appear in machine | Wrong machine type in recipe file | Check the machine field against the item browser |
| Game crashes on load | Malformed JSON or missing item ID | Run the validator and fix reported errors |
| Recipe runs but produces nothing | Output item ID is incorrect | Verify the output ID in the item browser |
| Recipe conflicts with another mod | Same recipe ID or priority collision | Change your recipe ID or adjust priority |
The **wrong machine type** error is the most common, because it is easy to type a machine name that sounds right but does not match the game's internal ID. The **missing item ID** error is the second most common, and it usually happens when you copy an item name from a wiki that uses a different naming convention. The **output nothing** error is trickier, because the recipe loads and runs, but the result is invisible, which makes it hard to diagnose. In all cases, the validator and item browser are your best tools, and the community Discord is a great place to ask for help when you are stuck.
### Using the Community for Troubleshooting
The Sandustry modding community is active and helpful, and the official Discord is the best place to get answers when you hit a problem you cannot solve. The developer actively participates in modding discussions, and experienced modders are usually happy to review your files and point out issues. According to community reports, most troubleshooting threads get a response within a few hours, which is fast for a game that has not even launched yet.
When you ask for help, include your manifest file and the recipe file that is causing trouble, plus a description of what you expected to happen versus what actually happened. This context makes it much easier for others to spot the issue. You can also search the Discord for similar problems, because many beginners hit the same wall, and the solutions are often already documented. The community is one of the best resources for learning Sandustry modding, and it is worth joining even if you never post a question.
## Going Beyond Recipes with Full Overhaul Mods
Once you are comfortable with custom recipes, you might want to explore the broader world of Sandustry full overhaul mods. These projects go beyond individual recipe tweaks and rework entire systems, adding new machines, new items, and new progression paths. The modding tools shipped with the game support this level of ambition, and the official website explicitly mentions full overhauls as a supported use case. The learning curve is steeper, but the payoff is a completely personalized version of the game.
A full overhaul typically starts with a design document that outlines the vision, then breaks that vision into smaller pieces that can be implemented incrementally. Custom recipes are usually the first piece, because they are the simplest to implement and test. From there, you can add new items that your recipes reference, then new machines that process those items, and finally new progression systems that tie everything together. Each step builds on the previous one, and the modding tools make it possible to test each layer before moving on.
### Planning an Overhaul Project
The table below outlines the typical phases of a full overhaul project, based on community reports from other modding communities and the structure of the modding tools:
| Phase | Focus | Key Deliverables | Typical Duration |
|-------|-------|------------------|------------------|
| Design | Define the vision and scope | Design document, item list | 1-2 weeks |
| Recipes | Implement core transformations | Custom recipe files | 1 week |
| Items | Add new materials and products | Item definition files | 1-2 weeks |
| Machines | Create new processing buildings | Machine definition files | 2-3 weeks |
| Polish | Balance and bug fixing | Updated values, tested scenarios | Ongoing |
The **design phase** is the most important, because it forces you to think about how your changes interact with the vanilla game. The **recipe phase** is where you apply the skills from this guide, and it is the best place to start if you are new to overhaul projects. The **item phase** requires you to learn a new set of JSON fields, but the pattern is similar to recipes. The **machine phase** is the most complex, because machines have visual and behavioral components, but the modding tools include templates to help you get started.
### Learning Resources for Advanced Modding
If you want to go deeper, the [Sandustry modding documentation](https://sandustry.com) is the authoritative source for the mod API, and the official Discord has channels dedicated to mod development. The developer also posts video updates that show off new modding features, like the [simulation rewrite before-and-after video](https://www.youtube.com/watch?v=oE1ZwCcqUx0), which gives you insight into how the game's internals work. For a structured introduction to the fundamentals, the [Sandustry modding guide for beginners](/en/modding/mod-guide/) covers the basics of creating your first mod project.
As you progress, you will also want to study existing community mods to see how experienced modders structure their projects. The [community mods guide](/en/modding/community-mods/) showcases some of the best examples and explains what makes them work. You can also check the [mod installation guide](/en/modding/mod-installation/) if you need a refresher on loading mods into the game. The key is to keep experimenting and learning from both your successes and your failures.
## Frequently Asked Questions
**What is the easiest way to start making a Sandustry custom recipes mod?**
Copy an existing recipe file from Sandustry’s default content, swap the item IDs and amounts, then run it through the validator. Test one modified machine in a creative world before adding more. This keeps syntax errors minimal while you learn the format.
**Can I share my custom recipes mod on the Sandustry workshop?**
Yes, the game supports workshop integration, and the developer encourages players to share their mods. Before uploading, make sure your mod passes the validator and includes a clear description of what it changes. You should also set a priority value that plays well with other popular mods, and test your mod after each game update to ensure compatibility.
**Do Sandustry full overhaul mods require programming knowledge?**
No, Sandustry’s full overhaul mods rely on the same JSON system as custom recipes, just with more interconnected files. You won’t write code, but you’ll need to trace how item, block, and recipe definitions link together. Templates and the community Discord cover the tricky parts.
**How do I fix a recipe that loads but does not appear in the machine menu?**
This usually means the machine type in your recipe file doesn't match the machine you're checking. In Sandustry's modding tools, open the item browser to confirm the exact machine ID, then update your recipe. If that's correct, verify your manifest's content array references the recipe file—unlisted files won't load.
**What happens when two mods define the same recipe?**
The game uses a priority system to resolve conflicts, where higher priority values win. If two mods have the same priority, the game falls back to load order, and the mod loaded later takes precedence. To avoid surprises, set a clear priority in your manifest and document it so other players know how your mod interacts with theirs.