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.

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 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 PublishedFileId.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. Note that you cannot change active mods once the map has been created. Also note that while local mods can be selected for testing, maps containing local mods can not be published to the Steam Workshop. 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 which accessed in the top left of the screen.

Hot Reloading

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. This is intended as a mod development aid to quickly iterate on certain changes. 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.

Example Mods

Below is a lost of Example Mods that may 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

Unity Project Example Assets

A Unity project with some common example assets for mods that can be downloaded and loaded into Unity.
Example Assets Unity Project

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.

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.

Interface

The game interface can be changed using the ui.json file.

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.

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.

Exiting IDs

A tables of links to IDs 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:

1. Buildings
2. Tree Fields
3. Plantable Fields
4. Structures
5. Terrain Color
6. Terrain Detail Types

as well as:

1. Colliders used by units on building floors.

A LandRouteFloor image file can be used to change or define rendering of Paths and Roads.

Modding in Unity and Asset Bundles

Conventions on modding The Colonists in Unity and using the asset bundler tool 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 .