Overview

Tachyon Travels supports data-only mods. A mod can rebalance gameplay, add or replace content, provide translations, and override supported visual or audio assets without GDScript.

Mod Structure

my_mod/
├── mod.json                    # Manifest (required)
├── preview.png                 # Workshop thumbnail (optional, at most 1 MB)
├── data/
│   ├── config/
│   │   ├── enemy_ai.json
│   │   └── status_effects.json
│   ├── books/
│   │   └── my_books.csv
│   └── enemies.csv
├── translations/
│   └── my_mod.en.po
└── assets/
    └── echoes/unit/roman/
        └── basic.png

Only mod.json is required. Add data, translation, and asset folders as your mod needs them.

The mod.json Manifest

{
  "mod_id": "my_balance_mod",
  "mod_type": "community",
  "mod_version": "1.0.0",
  "mod_name": "My Balance Mod",
  "mod_author": "Your Name",
  "mod_description": "Adjusts status effects and enemy AI",
  "game_version_min": "0.1.0",
  "content": {
    "status_effects": [{"file": "data/config/status_effects.json"}],
    "enemy_ai": [{"file": "data/config/enemy_ai.json"}]
  }
}

The manifest requires these seven non-empty string fields:

• mod_id: a stable identifier for the mod.
• mod_type: use community for community mods.
• mod_version: the version of your mod.
• mod_name: the player-facing name.
• mod_author: the player-facing author name.
• mod_description: a short player-facing description.
• game_version_min: the oldest compatible Tachyon Travels version.

The content object is optional. Each key is a supported content type, and its value is an array of declarations. The Content Type Reference lists the public types, formats, merge rules, key fields, dependencies, and example paths.

For any new community row that has an origin field, set it to lore. historical and mythological are reserved for game-owned catalogue records and cannot be used for standalone new rows in a community mod. When overriding an existing game-owned historical or mythological row, preserve every catalogue-reference field already present on that row.

{
  "content": {
    "status_effects": [
      {"file": "data/config/status_effects.json"}
    ],
    "books": [
      {"file": "data/books/my_books.csv", "id_column": "book_id"}
    ],
    "bosses": [
      {"id": "my_boss", "file": "data/bosses/my_boss.json"}
    ]
  }
}

{
  "dependencies": {
    "requires": {"library_core": ">=1.2.0"},
    "optional": {"extra_maps": "*"},
    "conflicts": {"legacy_balance": "*"},
    "load_after": ["library_core"]
  }
}

Common Content Types

Merge and Deletion Rules

• replace_record: entries with the same key fields replace earlier entries.
• merge_object: objects are merged recursively; specify only the values you want to change.
• replace_all: the mod replaces the complete data set for that type.
• merge_by_id: incoming entries replace matching ids and add new ids.
• merge_append: incoming entries are appended in mod load order.

Deletion is available only when the type's Deletion column in the Content Type Reference says yes. For a supported replace_record type, a deletion row uses _op: "delete" together with the type's key fields:

{"_op": "delete", "id": "entry_id"}

For a supported merge_object type, remove nested values with _delete_paths:

{"_delete_paths": ["field.to.remove"]}

Asset Overrides

Put replacement assets under your mod's assets/ folder using the supported canonical relative path. Higher-priority mods take precedence, and missing assets fall back to the base game.

For example:

assets/echoes/unit/roman/basic.png

Icon-token data should point to textures inside the owning mod's assets/ folder. Absolute paths, parent-directory traversal, and paths that escape the mod root are rejected.

Localization

Put gettext .po catalogs or compiled .mo catalogs in the mod's translations/ folder. Enabled mods load their catalogs at startup. Prefix translation keys with your mod ID to reduce collisions with the base game and other mods.

Installation

Install a local mod at:

user://mods/local/your_mod/

The in-game Mods screen has an Open Mods Folder button that creates and opens this directory. user:// resolves to the Tachyon Travels data directory:

• Windows: %APPDATA%\Tachyon_Travels\
• macOS: ~/Library/Application Support/Tachyon_Travels/

Steam Workshop subscriptions are discovered automatically on the next game start. Enabling or disabling a mod takes effect after restart.

Testing and Troubleshooting

Restart the game after changing mod.json. Restarting is also the most reliable way to verify data and asset changes through the complete loading process.

The Mods screen shows each discovered mod's state and validation messages. Additional details are written to logs/godot.log below the same data directory used by user://.

If the game fails only when mods are installed, temporarily disable the suspect mods on the Mods screen. You can also start the game with -- --no-user-mods to load only the base game and official game content.

Common causes of load failure include:

• a missing required manifest field;
• a manifest path that does not match the file's location;
• malformed JSON or CSV;
• a missing required dependency;
• a content key with the wrong type;
• an unsupported file or an unsafe resource reference.

Saves and Mods

Saves record the community mod set that was active when they were written. Loading a save with a different mod set shows an advisory rather than blocking the load. Removing content used by an existing save can still change gameplay or leave referenced content unavailable, so keep backups while developing.

Publishing to the Steam Workshop

1. Develop and test the mod under user://mods/local/your_mod/.
2. Add optional workshop_tags and a preview.png at most 1 MB.
3. Open the Mods screen, select the local mod, and choose Publish to Workshop.
4. Accept the Steam Workshop legal agreement if Steam requests it.
5. Keep the workshop_id written to mod.json after the first publish.

The game validates the manifest and files before upload. Later publishes update the same Workshop item. If an upload is interrupted, restart the game and retry from the same local mod so the saved publish state can be recovered.

Workshop updates apply after the game restarts; they are never applied in the middle of a running session.

Load Priority

When two mods change the same entry, the higher-priority source wins. Ordering within a priority also follows declared dependencies and load-order hints.

Security

Community mods are data-only. Supported file extensions are .csv, .json, .png, .jpg, .jpeg, .ogg, .wav, .tscn, .tres, .po, .mo, .md, and .txt. GDScript (.gd) is not allowed.

The security scan includes hidden files. Remove operating-system and version-control metadata such as .DS_Store, Thumbs.db, and .git* before installing or publishing a mod. Scenes and resources must not contain script attachments or references that escape the mod directory.

achievements

Achievement definitions, predicates, and presentation.

audio

Audio buses, events, mix states, music, and soundtrack profiles.

characters

Playable characters and their configuration.

combat

Combat systems: enemies, bosses, weapons, waves, arenas.

economy_balance

Balance tables, exchange rates, and difficulty.

guidance

Guidance facts, graphs, and teaching flows.

horde

Horde run content, modifiers, and rewards.

items

Items, artifacts, chests, and drops.

library

Books, the book reader, and library presentation.

localization

Languages and translation assets.

modes_runtime

Game modes and runtime profiles.

mothership

Mothership systems, frames, imprints, drones, and tasks.

planets_sites

Planets, sites, geography, and overview content.

quotes_media

Quotations and player-facing item media.

story

Story beats, dialogue, and narrative content.

ui

Screens, layout families, icons, palettes, and cameras.