- Ostranauts modding uses two main systems: JSON data mods and BepInEx C# plugins
- Data modding requires editing JSON files in the StreamingAssets folder structure
- BepInEx plugins enable code injection for advanced features like hotkeys and UI tweaks
- Loading order is critical: always keep "core" first, then add your mods sequentially
- Always back up your base game files before installing or creating any mods
Ostranauts Modding Overview
Ostranauts supports a flexible modding ecosystem that allows players to customize nearly every aspect of the game. Whether you want to add new items, modify ship designs, or inject custom C# code for advanced UI features, the game provides two distinct pathways for modifications.
Video Highlights:
- Step-by-step BepInEx installation and configuration
- How to properly set up the loading order for data mods
- Manual installation of plugins like Speed Hotkeys and Floor & Walls
- Using the Configuration Manager to verify mod functionality
The two primary modding approaches serve different purposes. Data modding (JSON modding) is the most accessible entry point, requiring no programming knowledge. BepInEx modding, on the other hand, allows for deeper modifications through compiled C# code.
| Mod Type | Difficulty | Requirements | Best For |
|---|---|---|---|
| Data (JSON) Mods | Beginner | Text editor (Notepad++) | New items, ships, interactions, conditions |
| BepInEx Plugins | Intermediate to Advanced | BepInEx framework, C# knowledge | Hotkeys, UI changes, code injection, new mechanics |
If you are new to Ostranauts modding, begin with JSON data mods. They require no programming experience and use the same data structure as the base game. You only need a text editor like Notepad++ to get started.
Installing BepInEx and Plugin Mods
BepInEx is a Unity framework that enables code injection for Ostranauts. Many popular community mods—such as Speed Hotkeys, Editor History, and Floor & Walls visibility toggles—rely on this framework to function.
Required Downloads
Before installing any BepInEx-based mods, you need two core components:
| Component | Version | Purpose |
|---|---|---|
| BepInEx | 5.4.23 | Core framework for code injection |
| Configuration Manager | 8.3 | In-game UI to manage mod settings (press F1) |
Do not use BepInEx 6.0. The current working version for most Ostranauts mods is 5.4.23. Using the wrong version can cause mods to fail silently or crash the game on startup.
Plugin Installation Locations
BepInEx plugins go into a different folder than JSON data mods. Understanding this distinction is essential:
| Mod Type | Destination Folder | How to Verify |
|---|---|---|
| BepInEx Plugins | Ostranauts_Data/plugins/ | Press F1 in-game for Configuration Manager |
| Data Mods | Ostranauts_Data/Mods/ | Check Options > Files > Mods in-game |
| Astral Adaptations | Ostranauts_Data/Mods/ | Add to loading_order.json under "core" |
After placing BepInEx files in the game folder, you must launch Ostranauts at least once. This initial launch generates the additional folders (like plugins/) that your mods need. Without this step, the folder structure will not exist.
Data Modding Fundamentals
Data modding is the most accessible way to modify Ostranauts. All base game data lives in the StreamingAssets folder, organized into over 30 different data types. By creating your own mod folder with a matching structure, you can add or override game content without touching the original files.
Core Data Types
| Folder | Contents | Common Use Cases |
|---|---|---|
items/ | Item definitions (tools, equipment, objects) | Add new tools, weapons, or decorative items |
cooverlays/ | Display names and descriptions | Required for every item to show tooltips |
interactions/ | Character actions and behaviors | Create new social actions, animations, or tasks |
conditions/ | Status effects and game states | Add emotional states, buffs, or debuffs |
ships/ | Ship templates and designs | Create custom starter ships or NPC vessels |
condtrigs/ | Condition trigger events | Define what happens when conditions are met |
Do not modify files in the StreamingAssets folder. Always create a separate mod folder. Direct edits to base game files will be overwritten by updates and can cause unpredictable behavior.
Ostranauts Naming Conventions
The game uses a prefix system for all JSON fields. Understanding these prefixes helps you read and write mod data correctly:
| Prefix | Type | Example | Description |
|---|---|---|---|
str | String | strName | Text value (names, descriptions) |
n | Integer | nCols | Whole number (grid columns, counts) |
f | Float | fZScale | Decimal number (scale, duration) |
b | Boolean | bEnabled | True or false flag |
a | Array | aSocketAdds | List of values |
map | Map/Dictionary | mapModeSwitches | Key-value pair collection |
The best way to learn data modding is to study existing game files. Open the StreamingAssets/data/ folder and examine how items, interactions, and conditions are structured. Copy the format and modify values for your own mods.
Creating Your First Mod
Set Up the Mod Folder
Navigate to Ostranauts_Data/Mods/ and create a new folder for your mod. Inside it, create a mod_info.json file with metadata (name, author, version, game version), and subfolders matching the StreamingAssets structure (e.g., data/items/, data/cooverlays/, images/).
Write Your JSON Data
Create JSON files in the appropriate data subfolders. For a new item, place the definition in data/items/my_items.json and a matching COOverlay in data/cooverlays/my_overlays.json. Every item needs a corresponding COOverlay with the same strName to display names and tooltips correctly.
Update loading_order.json
Open Ostranauts_Data/loading_order.json and add your mod folder name to the aLoadOrder array, after "core". The folder name must match exactly—this field is case-sensitive. If the file does not exist, launch the game once with the Mods button to generate it.
Test In-Game
Launch Ostranauts and watch the loading screen for mod messages. Go to Options > Files to confirm your mod shows a green "Loaded" status. Use the Ship Editor to find new items, or open the debug console with the backtick key and type UNLOCKDEBUG to spawn items for testing.
To add new content, use unique strName values that do not exist in the base game. To override existing content, use the same strName as the item you want to replace. Later mods in the loading order take priority over earlier ones.
Sample mod_info.json Structure
| Field | Purpose | Example |
|---|---|---|
strName | Display name of your mod | "My Cool Mod" |
strAuthor | Creator name | "YourName" |
strGameVersion | Compatible game version | "1.3.1" |
strModVersion | Your mod's version number | "1.0.0" |
strNotes | Brief description | "Adds new decorative items" |
Troubleshooting Common Issues
Even well-structured mods can encounter problems. Use this reference table to diagnose and fix the most frequent issues modders face.
| Problem | Likely Cause | Solution |
|---|---|---|
| Mod doesn't appear | Folder name mismatch in loading_order.json | Verify exact case-sensitive match between folder and array entry |
| Item has no name | Missing or mismatched COOverlay | Create a COOverlay entry with the same strName as the item |
| JSON syntax error | Missing comma, extra comma, or unclosed bracket | Validate with JSONLint or VS Code JSON extension |
| Sprite is missing | Image file not in images/ folder or wrong filename | Ensure strImg matches filename without .png extension |
| BepInEx mods not working | Wrong BepInEx version or missing first launch | Use version 5.4.23, launch game once after installing framework |
| Game crashes on startup | Conflicting overrides or invalid JSON | Check output_log.txt in AppData/LocalLow/Blue Bottle Games/Ostranauts/ |
Ostranauts generates detailed log files at C:\Users\<YourName>\AppData\LocalLow\Blue Bottle Games\Ostranauts\output_log.txt. Search for "Error" or "Exception" entries, and look for your mod name or JSON file names to pinpoint loading issues.
Recommended Tools
Notepad++
- Lightweight text editor
- JSON syntax highlighting
- Free and widely used
- Great for quick edits
Visual Studio Code
- Full IDE with JSON validation
- Extension marketplace
- Built-in error detection
- Git integration for versioning
JSONLint
- Online JSON validator
- No installation needed
- Catches syntax errors instantly
- Useful for quick checks
Add one item or change at a time. If something breaks, you will know exactly which modification caused the issue. This approach saves hours of debugging compared to adding everything at once.
Best Practices and Distribution
Modding Best Practices:
- Use descriptive names (ItmPlushBearBrown, not ItmStuff01)
- Test one change at a time to isolate issues
- Study base game data files in StreamingAssets for examples
- Version your changes using Git or GitHub backups
- Document everything in mod_info.json strNotes field
- List compatible game version to help users avoid conflicts
Distribution Channels
Once your mod is ready, you can share it through several platforms:
| Platform | Format | Audience | Notes |
|---|---|---|---|
| Thunderstore | BepInEx plugin wrapper | Broad modding community | Requires plugin wrapper for JSON mods |
| GitHub | Repository | Developers and advanced users | Best for open-source collaboration |
| Nexus Mods | Zip file | General gaming audience | Popular destination for game mods |
| Discord/Forums | Direct download | Ostranauts community | Fastest way to get feedback |
If you distribute mods manually, include clear instructions: download and extract the mod folder, place it in Ostranauts_Data/Mods/, add the mod name to loading_order.json, and launch the game. Simple instructions reduce support requests.
Frequently Asked Questions
Q: What is the difference between data mods and BepInEx plugins in Ostranauts?
Data mods use JSON files to add or modify game content like items, ships, and interactions. They go in the Mods folder and require no programming. BepInEx plugins are compiled C# code that inject new functionality like hotkeys or UI changes. They go in the plugins folder and require the BepInEx framework.
Q: Which BepInEx version should I use for Ostranauts modding?
Use BepInEx version 5.4.23. Version 6.0 is not compatible with most current Ostranauts mods and can cause them to fail. Always check the mod author's requirements page for the specific version they recommend.
Q: Why does my modded item appear in game but has no name or description?
Every item needs a matching COOverlay entry in the data/cooverlays/ folder. The COOverlay must have the same strName as your item, plus strNameFriendly and strDesc fields. Without it, the game cannot display human-readable text for the item.
Q: How do I override an existing base game item instead of adding a new one?
Use the same strName as the base game item you want to replace in your mod's JSON file. The game loads mods after core data, so your definition takes priority. Be cautious, as overriding base game content can conflict with other mods that modify the same item.