If you have ever wanted to bend the rules of your salvage runs, this Ostranauts modding tutorial walks you through every step from folder setup to publishing a working mod on Steam Workshop. Built on the same engine that powers NEO Scavenger, the game ships with full plain-text data files that any player can read, edit, and repackage without touching the executable. That openness is exactly why the community has produced hundreds of mods ranging from balance tweaks to entirely new ship parts, and the rest of this Ostranauts modding tutorial gives you the shortest reliable path to joining them.
Understanding the Ostranauts Modding Ecosystem
The first thing to grasp before opening any file is how the game loads its data. Ostranauts stores nearly every gameplay value — from thruster thrust ratings to crew morale decay rates — in human-readable JSON files bundled under the install directory. When you launch the game, it reads those files first and then overlays anything found in your user mod folder, which means mods behave more like override sheets than compiled plugins. For a deeper breakdown of the philosophy and ecosystem, see our Ostranauts modding guide.
The modding scene split into two practical camps early on: creators who publish through Steam Workshop and creators who distribute raw folders on Discord. Workshop integration came with the 1.0 release on August 3, 2026, so older mods that lived only on community Discords now have a one-click install path for newcomers. Either workflow is valid, and the data layer treats them identically.
| Distribution Channel | Install Effort | Update Delivery | Discoverability |
|---|---|---|---|
| Steam Workshop | One click | Automatic via Steam | High (built-in search) |
| Manual folder (Documents) | Drag and drop | Manual re-download | Low (Discord/forum only) |
| Nexus-style external hub | Varies | Manual | Medium |
| GitHub release zip | Download + extract | Manual | Low (developer-only) |
The choice mostly affects your players, not your code. For your first attempt at following this Ostranauts modding tutorial, manual installation is the fastest feedback loop because you can edit, relaunch, and reload in under thirty seconds without ever opening Steam. Once the design feels stable, repackaging for Workshop is a five-minute job.
Setting Up Your Modding Environment
You do not need a heavy IDE to start. Most modders begin with a lightweight text editor and a copy of the base game files for reference. The community generally treats three tools as the default stack, and our Ostranauts modding tools article expands the list with screenshots.
Required Software and Folder Locations
The base install lives at SteamLibrary/steamapps/common/Ostranauts/ on PC. Inside that folder you will find a data/ directory containing the JSON sources and an ostranauts_Data/ directory holding compiled Unity assets that you generally should not touch. Your user mod folder sits one level above, under SteamLibrary/steamapps/workshop/content/1022980/ for subscribed Workshop items and Documents/Ostranauts/mods/ for manual installs.
Editor Recommendations
A good editor should at minimum support JSON syntax highlighting, bracket matching, and UTF-8 encoding without BOM. Visual Studio Code with the Even Better TOML extension, Notepad++ with the JSON Viewer plugin, and Sublime Text 4 are the three most common picks reported by modders on the official wiki. Save every file with Unix line endings (LF) if you plan to share the mod cross-platform, because Windows-style CRLF breaks some Steam Workshop uploaders and forces players to fix encoding errors before the mod will load.
Exploring Ostranauts Data Files
Before you write a single line, spend an hour reading the originals. The base data/ folder contains roughly two dozen JSON files, each scoped to a single game system, and our Ostranauts data files reference covers every one in detail. The five you will edit most often during early experiments are listed below.
| File Name | System Controlled | Common Edits |
|---|---|---|
ships.json | Ship hulls, parts, grid layouts | Add new ship templates |
items.json | Cargo, tools, weapons, consumables | Tweak prices, weights, effects |
crew.json | NPC stats, traits, needs | Adjust morale, hunger, oxygen curves |
world.json | Solar system, stations, trade goods | Add new zones or commodities |
dialogue.json | Conversation trees | Rewrite NPC barks |
Reading the JSON Safely
Every JSON file in Ostranauts begins with a version integer (for example "version": 4) and a top-level array. Editing one number — say, the oxygen consumption rate for crew — is as simple as finding the matching key inside the crew.json array, copying the entire object, and changing just that value. Always duplicate the file before any change so you have an immediate rollback if the game refuses to launch.
Asset Files Beyond JSON
Sprite swaps and audio replacements require touching the ostranauts_Data/StreamingAssets/AssetBundles/ folder, which is a different workflow. For pure data mods — the kind most beginners should start with — you can stay inside data/ and never unpack a single Unity asset. That keeps your mod under 50 KB, easy to version control, and trivially diffable in Git when you compare revisions later.
Creating Your First Ostranauts Mod Step by Step
Once you know where the files live, a real mod takes about twenty minutes to produce. The walkthrough below targets a beginner-friendly goal: doubling the salvage value of every wreck in K-Leg so you can afford a better ship faster. Treat it as the canonical first project for any Ostranauts modding tutorial because the result is easy to verify in-game without breaking progression.
Step 1: Build the Mod Folder
Create a new directory called KLegDoubleSalvage/ anywhere convenient on your drive. Inside, mirror the original structure with a data/ subfolder. When the game loads, it merges everything inside your mod's data/ folder on top of the base files, so the path inside your mod must match the path inside the game exactly — capitalization, slashes, and file extensions all matter.
Step 2: Copy and Modify the Target File
Copy world.json from the base data/ folder into your mod's data/ folder. Open the copy and locate the salvageValue keys inside the K-Leg station entries. Change each numeric value, multiply by 2, and save. Resist the urge to rename the file, because the loader matches on path, not on internal IDs, and renaming will simply make your edits invisible to the engine.
Step 3: Create the Manifest
Every mod needs a small text descriptor so the launcher can show a name and version. Create a mod.json at the root of your mod folder with the following fields:
| Field | Required | Purpose |
|---|---|---|
name | Yes | Display name in the mod list |
version | Yes | SemVer string for update checks |
author | Yes | Creator handle |
description | No | One-line summary in launcher |
dependencies | No | Array of required mod IDs |
loadOrder | No | Integer for forced ordering |
Step 4: Install Manually and Test
Drop the entire KLegDoubleSalvage/ folder into Documents/Ostranauts/mods/, launch the game, and check the Mods screen on the main menu. Your mod should appear with a green checkmark. Load a save, dock at K-Leg, and scrap the nearest wreck. If the credit payout doubled, the mod is working. If the launcher shows a red X, re-open world.json and look for a missing comma or unmatched brace — those two errors account for roughly eighty percent of first-upload failures, according to community data shared on the official Ostranauts wiki.
Step 5: Publish to Steam Workshop
Open the in-game Mod Manager, click Upload, and point it at your mod folder. Steam will handle thumbnail generation, versioning, and distribution. Once uploaded, your mod lives next to the official Ostranauts on Steam page, and most first-time uploads are visible to subscribers within an hour because the validation is purely syntactic.
Advanced Techniques and Best Practices
Once your first mod works, a handful of habits separate a one-off tweak from a polished release. The community has converged on a few conventions over the past few years of modding the same engine family, and adopting them early makes the rest of your Ostranauts modding tutorial journey much smoother.
Versioning and Changelogs
Tag every release with SemVer and keep a CHANGELOG.md inside the mod folder. Players will report bugs against specific versions, and you need to know whether the bug exists in 1.2.0 or only in 1.3.0. A clean log also makes you look professional when cross-promoting with other creators on Discord, and it doubles as a public record of your design intent for newcomers reading your code.
Avoiding Common Pitfalls
The two most frequent beginner mistakes reported on community threads are editing compiled assets by accident and forgetting to delete the mod folder on rollback tests. Always keep your mod folder separate from the base install, and always back up Documents/Ostranauts/saves/ before testing anything that touches crew, dialogue, or economy files, because those are the systems where a broken mod can soft-lock a save and force a reload from an earlier backup.
Compatibility With Other Mods
When two mods both edit items.json, the one loaded last wins. Use the optional loadOrder field in mod.json to force a deterministic ordering, and document any required load position in your description. Mods that only add new entries rarely conflict, while mods that edit existing numbers almost always do, which is why load-order etiquette matters so much in this Ostranauts modding tutorial workflow.
Testing, Debugging, and Sharing Your Work
A mod is not really finished until at least three other people have launched it without crashes. The Ostranauts community is small and friendly, and the Workshop hub makes it easy to find beta testers willing to sanity-check a new release before you tag it stable.
Reading the Log File
Every launch writes a verbose log to Documents/Ostranauts/logs/latest.log. If your mod fails to load, the log will print the exact file path and the JSON parse error, which usually points to a stray comma or a missing closing brace. Search the log for mod load failed to jump straight to the relevant block and save the ten-minute scroll through thousands of info lines.
Iterating Quickly
The fastest feedback loop is: edit, save, alt-tab, launch, reload save. With practice, the round trip takes under a minute. If you are modding a values-heavy file such as crew.json, keep a small spreadsheet of the original numbers so you can compare deltas at a glance instead of diffing raw JSON by eye, and you will catch regressions that pure text editing would otherwise hide for hours.
Frequently Asked Questions
Do I need programming experience for an Ostranauts modding tutorial?
No. The Ostranauts modding tutorial workflow is built around plain JSON editing, so any player who can copy a folder and use a text editor can ship a functional mod. If you can balance a checkbook, you can adjust the salvage payout values referenced earlier. For deeper mods involving scripting or new sprites, basic familiarity with JSON and Unity helps but is not required to start.
Where do I find the base game data files?
The base files live inside your Steam install directory at SteamLibrary/steamapps/common/Ostranauts/data/. You can reach it by right-clicking the game in Steam, choosing Manage → Browse local files. Copy, never edit, those files directly, because every change belongs in your own mod folder so the base install stays clean for verification.
Will mods break my save files?
Most balance and content mods do not corrupt saves, but mods that restructure crew needs, dialogue trees, or ship layouts can leave older saves in an inconsistent state. Always back up Documents/Ostranauts/saves/ before testing a new mod, and avoid loading a save made with a mod active into a vanilla install. According to community reports on the official wiki, reverting to a pre-mod save is the fastest recovery path when something goes wrong.
Can I publish a mod made from someone else's edits?
Only if you have explicit permission or the original mod uses a permissive license such as MIT or CC0. The default expectation in the Ostranauts community, as reported by long-time modders, is attribution and source disclosure. When in doubt, link the original mod in your description and credit the author in mod.json. Players and creators both reward transparency, and the Workshop hub makes plagiarism easy to spot anyway.
How do I update an existing Steam Workshop mod?
Open the in-game Mod Manager, select your mod, and click Upload New Version. Steam will reuse your existing thumbnail and description while bumping the version number. Players subscribed to your mod will receive the update automatically the next time they launch, which is why versioning with SemVer matters — it tells users whether the change is a hotfix or a breaking refactor that might require them to start a fresh save.