For version 0.17.x

Beta: Mod support is still under development. Features, supported content, and file formats may change between updates.

Modding in Wanderers’ Outpost currently focuses on game data, localization, and assets. Mods cannot include GDScript, plugins, or any other executable code.

1. Current support and limitations

At the moment, mods can:

include a mod.json manifest;
add new catalog entries or replace existing ones using supported TSV files;
add or override UI translations;
replace Archivist notification templates;
add or replace supported game assets;
be enabled, disabled, and reordered before starting a new game; and
record the active mod IDs and versions inside save files.

Mods cannot currently:

include GDScript, scenes, autoloads, editor plugins, or any executable code;
automatically resolve or enforce load_after and load_before;
be installed through Steam Workshop;
repair saves when content is removed;
override every res:// asset. Only assets loaded through the mod-aware loader can be replaced; or
partially override TSV rows. Replacing a row always replaces the entire record.

The built-in base mod is always enabled and always loads first. If multiple mods provide the same row ID or asset path, the version from the mod loaded later takes priority.

2. Find the mods folder

For the Steam or standalone release, place your mods in the mods folder next to the game executable:

WanderersOutpost.exe
mods/
  base/
  your_mod/

If you’re running the game from source, use the project’s top-level mods/ directory instead.

When both locations exist, the game always prefers the mods folder beside the executable.

Each folder directly inside mods/ is treated as a separate mod. Avoid placing your mod inside an extra nested folder.

3. Create a mod

Every mod starts with a folder containing a mod.json file.

Minimum structure:

mods/
  my_mod/
    mod.json

Only create the folders your mod actually needs. The directory structure inside your mod should mirror the game’s own paths.

For example:

mods/my_mod/
  mod.json
  assets/
    icons/
      my_icon.png
  resources/
    catalog/
      items/
        my_items.tsv
    i18n/
      ui_en.tsv

Whenever possible, use lowercase filenames and stable IDs.

Catalog schemas can differ between content types and may change between game versions, so always copy the header from the matching file in mods/base/ instead of creating one from scratch.

4. Write the manifest

Every mod requires a mod.json file.

At minimum, it should contain:

{
  "id": "my_mod",
  "name": "My Mod",
  "version": "1.0.0"
}

The game also displays these optional fields:

{
  "id": "my_mod",
  "name": "My Mod",
  "version": "1.0.0",
  "author": "Author Name",
  "description": "Adds new materials and recipes."
}

Manifest rules

id is the mod’s permanent identifier and is recorded in save files. Use only lowercase letters, numbers, and underscores.
Every installed mod must have a unique id.
The reserved ID base cannot be used.
The folder name is only where the mod is installed—it does not have to match the mod ID.
version is shown in the Mods menu and stored in save metadata. Update it whenever you release a new version.
Additional fields are ignored for now, but keeping them won’t cause any problems.

If mod.json is missing, unreadable, or contains invalid JSON, the game skips the mod.

If id, name, or version is missing, the loader currently supplies fallback values. Even so, you should always include all three fields to ensure your mod is identified correctly.

5. Add or Override Catalog Content

Most game data is stored in TSV files under the catalog directory.

The game automatically discovers TSV files placed anywhere under these folders:

resources/catalog/items/
resources/catalog/recipes/
resources/catalog/actors/
resources/catalog/objects/
resources/catalog/tiles/

Some additional catalog files are loaded from fixed locations:

resources/catalog/paperdoll/
resources/catalog/sfx/runtime.tsv
resources/catalog/loot/generic.tsv

The files included in mods/base/resources/catalog/ are the best reference for how each catalog is structured.

Recommended workflow

Find the matching base TSV for the type of content you want to add.
Copy its header into a new TSV file inside your mod.
Add your own rows using tab characters, not spaces or commas.
Give every normal catalog entry a unique id.
Keep all required columns for that catalog.

For example:

mods/my_mod/resources/catalog/items/my_materials.tsv

TSV format

Blank lines are ignored.
Lines beginning with # (after trimming whitespace) are treated as comments.
Quoted fields and escaped quotes ("") are supported.
Rows are parsed according to the schema for that catalog.
Boolean values should be written as true or false.
Lists, maps, and other structured values should follow the same format used in the matching base file.
If two rows use the same id, the later one completely replaces the earlier row.
Rows without an id cannot override normal catalog entries. Some specialized tables—such as runtime SFX and generic loot—use different keys, so copy those files exactly when editing them.

Overriding existing content

To replace an existing entry, copy the entire row from the base catalog, keep the same id, and edit the values you want to change.

Don’t copy only the columns you’ve changed. Catalog overrides always replace the entire row.

Any references you add—such as output_id, ingredients, build costs, station IDs, sprite paths, or unlock switches—must point to IDs and assets that exist.

There is currently no complete validation tool for mods, so it’s good practice to test your changes in a fresh save and verify that every affected system behaves as expected.

6. Add UI Translations

Place UI translation files here:

mods/my_mod/resources/i18n/ui_<language>.tsv

Examples include:

ui_en.tsv
ui_ms.tsv
ui_ja.tsv
ui_zh_cn.tsv

The language code in the filename determines which language the file belongs to.

Translation files use this format:

id	text	context
my_mod.greeting	Welcome, {name}!	Greeting used by My Mod

id is the translation key.
text is the displayed text.
context is optional and intended for translators or documentation.
Named placeholders use {name} syntax and should be preserved exactly.

If multiple mods define the same translation key for the same language, the version from the later-loaded mod is used.

When a translation is missing in the active language, the game falls back to English. If no English translation exists either, the translation key itself is displayed.

Although data-only mods cannot create new scripted interfaces, they can replace existing text and provide translations for supported game content.

To find existing keys, refer to:

mods/base/resources/i18n/ui_en.tsv

7. Override Archivist Notifications

Archivist notification templates are stored in:

mods/my_mod/resources/archivists/notification_templates.tsv

Start by copying the header from the base file.

The first column, key, uniquely identifies each notification. The remaining columns contain the text for each Archivist persona.

To replace an existing notification, reuse the same key and provide the complete replacement row.

If a notification contains placeholders, keep them exactly as they appear unless you’re also changing the code that supplies those values.

The original design specification describes language-specific notification files such as:

notification_templates_<language>.tsv

However, the current version of the game only supports the single, unsuffixed file:

notification_templates.tsv

Until language-specific versions are implemented, avoid relying on the filename variants described in the design document.

8. Add or Replace Assets

Assets follow the same folder structure as the game itself.

For example, if a catalog entry references:

res://assets/icons/my_icon.png

your mod should contain:

mods/my_mod/assets/icons/my_icon.png

To replace an existing asset, use the same relative path.

To add a new asset, place it inside the matching directory and reference it using its res://assets/... path from your catalog data.

Supported asset types

Textures loaded through the mod-aware texture loader support:

PNG
JPG / JPEG
WebP
SVG

Other resource types may also work, provided the relevant game system loads them through the mod-aware resource loader and Godot supports that resource type at runtime.

Assets loaded using preload(), ordinary load(), or direct scene references bypass the mod loader completely.

If replacing an asset has no visible effect, that asset is most likely not being loaded through a moddable path.

9. Enable and Order Mods

From the main menu, open Mods to manage your installed mods.

Here you can:

enable or disable player mods;
change their load order; and
save the current selection by choosing Apply For New Games.

A few things to keep in mind:

The built-in base mod is always enabled and isn’t shown in the list.
Mods lower in the list load later, so they take priority when multiple mods replace the same content.
Your selected load order only affects new games.
Existing saves keep the mod list and load order they were created with. If a required mod is missing when loading a save, the game will display a warning.
Your mod configuration is stored in mod_settings.json inside the game’s user data.

Avoid removing, renaming, or changing the IDs of mods that are already being used by an active save. Although the game records which mods were present, it cannot automatically repair missing or incompatible content.

10. Test and Troubleshoot

Before releasing a mod, it’s worth running through a quick test to make sure everything works as expected.

Recommended testing checklist

Launch the game and confirm your mod appears in the Mods menu with the correct name and version.
Enable it, place it in the desired load order, and select Apply For New Games.
Start a new game.
Check that every new item, object, recipe, translation, or asset appears where expected.
Save the game, quit, and reload to verify that all referenced IDs still resolve correctly.
Test once with only the built-in base mod and your mod enabled. This makes it much easier to identify conflicts with other mods.

Common issues

Problem	Likely cause
Mod doesn’t appear	Extra folder nesting, missing `mod.json`, invalid JSON, empty ID, or duplicate ID
Catalog entries don’t load	Wrong directory, malformed TSV, missing `id`, or unsupported catalog location
Override doesn’t work	The replacement row is missing required columns from the original row
Another mod overrides yours	Your mod loads earlier than the conflicting mod
Missing texture or asset	Incorrect path, filename case mismatch, unsupported format, or the asset isn’t loaded through a moddable path
Translation shows the key instead of text	The key is missing in both the active language and English
Existing save reports missing content	A required mod has been removed, renamed, disabled, reordered, or changed in an incompatible way

Tip: Some operating systems treat filenames as case-sensitive. To avoid cross-platform issues, always use consistent capitalization for filenames, folder names, and IDs.

11. Package and Update a Mod

When distributing your mod, package it so extracting the archive produces:

mods/
  my_mod/
    mod.json

and not:

mods/
  my_mod/
    my_mod/
      mod.json

Don’t include the built-in base mod or any unrelated game files.

Before publishing an update

Keep the manifest id the same.
Increase the manifest version.
Avoid changing or removing content IDs that existing saves may reference.
If IDs have been removed or renamed, clearly document that the update may break older saves.
Mention which version of the game the mod was tested with.
Test your mod alongside other popular mods, both before and after them in the load order, to check for conflicts.

12. Reference Files

The following files are useful when creating or updating mods:

mods/base/mod.json — Example manifest.
mods/base/resources/catalog/ — Catalog schemas, headers, and base content.
mods/base/resources/i18n/ui_en.tsv — English UI translation keys.
mods/base/resources/archivists/notification_templates.tsv — Archivist notification templates and schema.
docs/mod_support_spec.md — Design goals and planned functionality. If this document differs from the guide, the guide reflects the behavior currently implemented in the game.

Wanderers’ Outpost Modding Guide 0.17.x

Table of Contents