Mods

This section is a work in progress!

Setup

Creating a mod

1. If it doesn't already exist, create a Mods folder inside %userprofile%\appdata\LocalLow\Codebyfire Ltd\The Colonists\
2. Create a folder for your mod inside the Mods folder, e.g. MyAmazingMod
3. Everything then goes inside MyAmazingMod. You can use subfolders to organise content or keep it all in the main directory, the mod loader in the game will just look at the name of the file to determine what it is.
4. Best Practice recommendation is to allow the game to create initial files. Start The Colonist and Enable your mod as shown below. There should now be a file within the %userprofile%\appdata\LocalLow\Codebyfire Ltd\The Colonists\Mods folder of your mods
   1. meta.json - Will have entries for Title. Description, version, and versionBundle.
   2. thumbnail.jpg - can be placed now or modified per below.

Publishing a mod

1. With a new mod placed in the folder %userprofile%\appdata\LocalLow\Codebyfire Ltd\The Colonists\Mods start The Colonists
   1. Selecting Mods from the main menu will show 2 options:
      1. Workshop Subscribed and unsubscribed Mods on the Steam Workshop - Subscribe/Unsubscribe to Mods here
      2. My Mods Published and unpublished Mods in your local folder - Publish/Unpublish your mods and change Workshop visibility here
2. There should now be 2 files within the %userprofile%\appdata\LocalLow\Codebyfire Ltd\The Colonists\Mods folder of your mods
   1. meta.json - enter the Mod Title and Description for Steam Workshop in this file
   2. thumbnail.jpg - the image file for the mod on Steam Workshop and Mod Panel (a default will be provided if omitted).
3. When a Mod is published the file Published FileId.txt containing the Mod ID will be created
4. Subscribed mods will be in the folder ``C:\Program Files (x86)\Steam\steamapps\workshop\content\677340\0123456789`` `where 0123456789` is the Mod ID
   1. The Mod ID can be found in 2 places:
      1. In the Published FileId.txt file in the local mod folder
      2. In the link to the mod on the workshop from the Mod Manager interface. e.g. "/filedetails/?id=0123456789"

Enabling mods

1. Enable mods in either Sandbox, Random Map, or when creating a new Custom Map
   1. Sandbox - "Active Mods" will open Mod Manager with Available and Workshop tabs for activating mods.
   2. Random Map - "Active Mods" will open Mod Manager with Available and Workshop tabs for activating mods.
   3. Custom Map - "Active Mods" available when creating a new Custom Map, will open Mod Manager with Available and Workshop tabs for activating mods. You can change active mods once the map has been created but be careful when doing so, in particular when removing content that is in use in your map. Published Custom Maps with mods will include the mod(s) for subscribers.
2. When a game is started all selected mods will be activated and their content processed, i.e. json files, images etc.
3. All activated mods for the current game are listed in the Info panel, accessed in the top left of the screen.

Hot Reloading

Hot Reloading is intended as a mod development aid to quickly iterate on certain changes. Not all changes can be hot reloaded. For example a building model change that was generated using Unity AssetBundles will not be updated. However, changes to json files will iterate.

An "IOException: Sharing Violation..." is most often caused when the translations.csv file is open in an editor.

If you're using a local mod, you can update the contents of your mod and then reload the mod mid-game using the 'Reload' button in the Info panel. Be careful though! Some things may go wrong when reloading the codex mid-game, depending on the changes you make! For example, removing a building or resource may not go down well.

Mods in Saved Games

Placeholder for Mod behavior in saved games - for local vs published mods. Custom Maps with Mods... A) Mod in Save is older than current Mod (Local vs Steam?) B) Mod in Save, local Mod no longer available/missing.

Example Mods

Below is a list of Example Mods that can be downloaded and placed on your local mods folder for testing.

Custom Building

Custom Natural Resource

Custom Techs

Custom Land Route

Custom Bot Materials

Custom Terrain Types

Codex

The codex controls all the main content objects in the game, from buildings to boats to bots. You can add new objects in or change the properties of existing objects through json files.

Base Codex Files

You can download all of the base json files from this Github repository: https://github.com/codebyfire/colonists-base-codex

Note: if you're using the development branch of the game, check the dev branch of the repository for the latest dev-compatible versions.
https://github.com/codebyfire/colonists-base-codex/tree/dev

Understanding and Modding Codex Objects

See Codex List for a list of Objects and explanation of JSON files for the base game of The Colonists.

Note many objects can be disabled in their main json file. See DisabledObjects.

User Interface

The game interface can be changed using the ui.json file. This can be modded to change Resource Storage and Building Menu displays.

Scripting Interface (C#)

A scripting interface for modding the game can be found here: Scripting (C#).

Text Localisation

Text Content

Use the translations.csv file to set dynamic and localised text content in the game. This is also used to provide the text for newly created buildings and resources.

Bot Names

You can set bot names for a mod with the text file bot_names.txt containing a separate name on each line.
PLACEHOLDER - check if this is implemented without using a mod.

Existing IDs

ID's are used to identify the variety of buildings, resources, units (bots), technology, and other aspects of the game. For mods of existing json files it is good to know how to identify these existing IDs. A table of links to various ID tables that are currently used can be found here: Existing IDs

Footprint Rendering & Unit Colliders

The render.json file can be used to change or define the footprint rendering of:

Buildings

Tree Fields

Plantable Fields

Structures

Terrain Color

Terrain Detail Types

The render.json file can also be used to define unit colliders for:

Which units will use colliders on building floors.

Which buildings units will use colliders on building floors

The LandRouteFloor file can be used to change or define the footprint rendering of:

LandRoutes (aka Paths and Roads)

Modding in Unity and Asset Bundles

Details on modding The Colonists using Unity can be found in Modding in Unity

File Naming Conventions in Mods

A summary of files recognized as valid in mods and their naming convention can be found in Naming Conventions in Mods .