Hey, Space Travelers!
Stardeus has received a major modding upgrade—JSON patching.
This method allows modifications to core JSON files without overwriting them. Mods using this approach will be more reliable and compatible with future updates. Even better, multiple mods can patch the same core file, eliminating override issues.
The rest of this update post is a tutorial on how to create your own mods. If you're interested, keep reading! If not, just know that mods support will be even better going forward!
Stardeus Modding Guide
What is JSON
JSON stands for “JavaScript Object Notation”, a human-readable plain text format. If you want to learn more about JSON, here’s a good resource: https://www.w3schools.com/js/js_json_intro.asp
However, JSON is so simple that you can easily understand it just by looking at a few examples.
How Stardeus uses JSON files
In Stardeus, behaviors are defined in C# code, which you can also mod but it requires programming knowledge and significantly more effort.
Content and various parameters are defined in JSON files that the game loads at runtime. To illustrate this, let’s examine a device.
This is a Charge Station. It has various properties and behaviors. The game recognizes the Charge Station because it loads a JSON file that defines it:
You can find this definition in the Core mod*:
Definitions/Objects/Devices/ChargeStation.json
* To open the contents of the Core mod, run Stardeus, then Main Menu > Mods > Core Game > Open Directory
This file specifies various properties of the Charge Station, such as the research required to unlock it and, most importantly, a list of Components.
Each Component block provides a specific function. Many of these components appear in other device definitions, but the ChargeStation component is what makes this device unique. Removing this component block would strip the Charge Station of its ability to recharge robots.
If you wanted the Charge Station to work twice as fast, you could change the ChargePerHour property from 25.0 to 50.0. However, modifying the Core mod directly means your changes would be overwritten when the game updates. In this guide, we’ll learn how to create mods that edit JSON files without altering the Core mod itself.
Beyond object definitions, Stardeus includes many other JSON files for configuring different aspects of the game. Tunable parameters, story events, species configurations, body parts, inventory items, character traits—even UI colors—are all defined in JSON and fully moddable.
Creating a Mod
The easiest way to create a new mod is to grab a copy of the empty mod here:
https://github.com/kodolinija/stardeus-mod-empty
Download the project as a zip file, extract it in the user mods folder*, rename the extracted folder to match your mod name (I like using the kebab-case when naming folders).
* User mods folder is located next to the Saves folder. You can open it from Stardeus:
Main Menu > Mods > About Mods > Open User Mods Directory
Then open the TODO.md file and go through the checklist:
Run Stardeus and check if your empty mod appears in the Main Menu > Mods list. If it does, you're ready to start modding!
Changing Existing Behaviors and Parameters
Previously, modifying a JSON file required copying the entire file into your mod just to change a few lines. The game would then load the modded version instead of the original. The main problem with this method was that when the Core mod updated, the copied JSON file could become outdated or broken. This often caused older mods to stop working or, worse, silently break parts of the game.
The new approach—JSON patching—solves this issue. Here’s how it works:
- Mods define patches.
- Patches target specific core JSON files.
- A patch contains a list of operations to modify the targeted JSON.
- Operations can add, remove, or replace parts of the original JSON.
This method is based on the RFC 6902 standard, with custom extensions for advanced querying. It’s simpler than it sounds—you’ll see examples soon.
JSON patching support was added in v0.12.17 and I believe this will be a game-changer for modding.
Let’s say we want to mod the Charge Station to double its charging speed. We need to create a patch file inside the Patches directory of the mod. We’ll name it ChargeStation_2xSpeed.json to reflect its purpose.
The patch file looks like this:
Let’s break it down:
- target: The path to the JSON file inside the Core mod directory that we want to patch.
- operations: An array containing one or more operation blocks.
- op: The type of operation. In this case, replace. Valid types are add, replace, and remove.
- path: A query specifying which element of the original JSON file to modify. It may look complex, but it’s straightforward once broken down.
- value: The new value replacing the existing one. Here, we’re changing ChargePerHour from 25.0 to 50.0 to double the charging speed.
Now, let’s analyze the path step by step:
- /Components → Refers to the "Components" key in the original JSON, which contains a list of component blocks.
- /Components[Component=ChargeStation] → Filters this list to find the block where "Component" is set to "ChargeStation".
- /Properties → Refers to the "Properties" key within that block, which contains a list of component properties.
- /Properties[Key=ChargePerHour] → Filters the "Properties" list to find the block where "Key" is "ChargePerHour".
- /Float → Refers to the "Float" key inside that block, which holds the value we want to change.
Since Float is the key that contains the charging speed, this is the final part of the path.
OK, I admit it still looks a bit scary here. But the good news is that it’s the most complex path example I could come up with. If you understand this one, you’re going to be unstoppable!
Now, what happens when the game loads your mod with this patch? Next to the user Mods directory, a Patched directory will be created. If you look inside, you should find the patched ChargeStation.json file that looks something like this:
More examples of how to write various JSON patches can be found here:
https://github.com/kodolinija/stardeus-mod-template/tree/master/Patches
Adding New Content via JSON Files
To add new content, you’ll need to create new JSON files rather than patches. Place these files in the corresponding directories of your mod inside Definitions or Config. Check the Core mod for examples.
When creating new definitions, you can mix and match existing components and add new graphics for your devices. Explore the mod template project and check out these YouTube video tutorials for examples:
https://github.com/kodolinija/stardeus-mod-template
https://www.youtube.com/playlist?list=PLvm1mLYInibc8n0Q5_caRql5nEUiBwvTC
Reference Source Code
If you want to write your own C# mods or understand how certain components work, you can explore the Reference Source Code that comes with the Core mod.
It’s not the complete source code, but it contains about 80% of the game’s codebase. Everything relevant to modding should be there. Unlike decompiled code, it includes comments, and constants are not replaced with literal values, making it much easier to read.
For the remaining 20%, you can decompile and explore the game DLL files using dnSpy or similar tools.
Join the Modding Community
Join the Stardeus Discord Server and visit #stardeus-modding channel to discuss with other modders and get help.
And I will be happy to personally answer any modding related questions there, or here on Steam Forums.
Happy modding!
- spajus
