Configuration File Structure

This page explains how configuration files are built and how you can change them with mods. For more info on creating and uploading mod files, see the Modding Guide.

## Syntax

All configuration files are JSON files with more lenient syntax. A well structured JSON file will always work, but even less well-formed files can be read, to make it easier to create and edit them. Commas are not required to separate different variables within the same node, and variable names may contain some special characters like dash (-) without having to be encased in quotes. If you are unsure, just use a string JSON format, that would be safest.

## Dot separated values

The JSON format can also be replaced by dot-separated-value. If you enter several variables with a dot between them, the configuration files will consider them as nested variables. This is used in the original configs sometimes. For example, the following are equivalent:

```
modifiers: {
 free-construction: {
 citytile: 1
 }
}

```
JSON hierarchy

```
"modifiers.free-construction.citytile": 1,
```
Dot separated value

## Making changes

To make changes to the game data, you only need to include in your mod files the JSON elements that you want to change.

You can either overwrite a value (leaf node), overwrite an entire JSON node, delete a value or node, and add a new value or node. Lists are a bit different, you cannot add or remove elements to/from lists, you can only replace the whole list.

### Changing a value

To change a value, include the full JSON hierarchy in your configuration file and assign it the new value that you want. There’s no need to include any nodes or variables that are not direct parents of the variable you wish to change.

```
 respawn: {
 health: 0.5 // percent of health when tiny respawns
 attack-meter: 2 // how many cycles does the threat level advance after dying
 base-cost: 50 // flux costs of dying
 cost-per-level: 20 // increase in flux costs per infrastructure upgrade level
 }

```
Original configuration

```
 respawn: {
 health: 0.75 // percent of health when tiny respawns
 }

```
Mod file

```
 respawn: {
 health: 0.75 // this value has been replaced by the mod file
 attack-meter: 2
 base-cost: 50
 cost-per-level: 20
 }

```
Adjusted configuration file (this is what the program will see when the mod is active)

The mod configuration file above will change the amount of health Tiny respawns with to 75%, but will not affect any of the other respawn settings such as the flux costs and threat level advance.

### Adding a value or node

Adding a new value or node is similar to changing an existing one, you need to include its full JSON hierarchy. It will be added to its parent node without affecting any of its sibling nodes.

```
 gamestart: {
 freebuildings: {
 woodwarper: 1
 }
 }

```
Original configuration

```
 gamestart: {
 freebuildings: {
 expansion: 1
 }
 }

```
Mod file

```
gamestart: {
 freebuildings: {
 woodwarper: 1
 expansion: 1
 }
 }

```
Adjusted configuration file (this is what the program will see when the mod is active)

The mod above will add the “expansion” variable with a value of “1” to the “freebuildings” node. The new node will now include both its original children and the new "expansion" child.

Adding an entire node works the same way, instead of giving it a value of “1” you can give it a JSON node as a value.

### Removing a value/node

Removing a value or node works the same as changing a value, include its full JSON hierarchy, and then give it the value “null”. This will remove the original value or node with all its children from the configuration, without affecting its siblings or parents.

```
 hud: {
 itemcount: {
 funds: {
 type: "Global" // used for tracking global resources
 }
 fuel: {
 type: "Global"
 }
 }
 }

```
Original configuration

```
 hud: {
 itemcount: {
 fuel: null
 }
 }

```
Mod file

```
 hud: {
 itemcount: {
 funds: {
 type: "Global" // used for tracking global resources
 }
 }
 }

```
Adjusted configuration file (this is what the program will see when the mod is active)
The example above will remove the entire “fuel” node from the “itemcount” JSON parent, leaving the “funds” child intact. You can remove an entire node the same way:

```
 hud: {
 itemcount: null
 }

```
This will remove the entire "itemcount" node with both its children "fuel" and "funds".

### Replacing a whole node

You can also replace a whole JSON node, so that the program completely disregards the original version of this node and uses only the one in the mod file. This can be useful in some situations when you want to completely change a node and make sure that there are no leftovers from the original.

To replace a node, include its full JSON hierarchy, and then add a “~!” to the replaced node’s variable name.

```
 gamestart: {
 inventory: {
 funds: 750
 worker: 9
 food: 200
 power: 100
 }
 freebuildings: {
 woodwarper: 1
 }
 }

```
Original configuration

```
 gamestart: {
 ~!inventory: {
 funds: 1000
 worker: 5
 warpedwood: 100
 featherstone: 100
 }
 }

```
Mod file

```
 gamestart: {
 inventory: {
 funds: 1000
 worker: 5
 warpedwood: 100
 featherstone: 100
 }
 freebuildings: {
 woodwarper: 1
 }
 }

```
Adjusted configuration file (this is what the program will see when the mod is active)

In the example above, the entire “inventory” node was replaced with the one in the mod file. The “food” and “power” values were completely removed because they don’t appear in the mod file, while the “warpedwood” and “featherstone” values were added. The “funds” and “worker” were replaced with the modified values.

If we hadn’t used the “~!” syntax before the “inventory” node - then the funds and worker values would have still been replaced by the new ones, and the warpedwood and featherstone values would have been added, but the food and power would have been kept.

Note that in the example above only the inventory node was replaced, the “freebuildings” node remained as it was.

## Inheritance

Inheritance is a very useful feature that we use extensively in the original configuration files. It allows a JSON node to inherit all the contents of another JSON node, and then modify them if necessary. The modifications within the inheriting node work exactly the same way as mod files, so you can change a value, add/remove values or nodes, or completely replace a node.

To have a node inherit another node, within the inheriting node create a list called “parents” (this is a reserved word), and within it enter the full path of the inherited node separated by dots.

A node may inherit multiple parent nodes, and the order matters. The nodes will be processed in the order they appear in the "parents" list. Those appearing later in the list will be processed last, and their values will override the values of those appearing earlier, if there are conflicts.

```
 items: {
 base: {
 resource: {
 can-track: true
 show-gamepedia: true
 }

 produced: {
 parents: [ "items.base.resource" ]
 produced: true
 show-gamepedia: false
 }

 important: {
 show-gamepedia: true
 }
 }

 entity: {
 starwood: {
 parents: [ "items.base.produced", "items.base.important" ],
 cartprefab: "cartstarwoodboard1"
 }
 }
 }

```
Example

This example includes multiple inheritance. The “produced” node inherits the “items.base.resource” node, but it changes the “show-gamepedia” value from true to false. It also adds a new “produced: true” value.

The calculated “produced” node would look like this:

```
 produced: {
 can-track: true
 produced: true
 show-gamepedia: false
 }

```
Calculated "produced" node
The “starwood” entity node then inherits both the “produced” node and the “important” node. Both nodes have different values for the “show-gamepedia” variable, in which case the one appearing later in the inheritance list will determine the value - in this case the value defined in the “important” node.

```
 starwood: {
 can-track: true // defined in “resource” and transferred to “produced” through inheritance
 produced: true // “defined in “produced”
 show-gamepedia: true // defined in “produced” and overridden in “important”
 cartprefab: "cartstarwoodboard1" // defined in “starwood” itself
 }

```
Final, calculated "starwood" node

**Note**: there can only be one “parents” variable per node. Adding one in a mod file to a node that already has a “parents” variable in the original config will cancel the original config’s inheritance and replace it with yours. Make sure you keep that in mind.