Modding - Stat Modifiers

## Stat Modifiers

Stat modifiers are a complex type of Modifier that can affect a lot of different things in the game, mainly numbers. A good example of a stat modifier is one that increase Tiny's damage by 5%, or one that increases a building's production by 50%.

## Format

```
modifiers: {
	stats: {
		flux: {
			"prod-speed": 0.30,
			"~spec": "prodgroup-flux",
			"~global": true
		}
		enemies: {
			"df-threat-time": -0.15
			"df-enemy-numbers": 0.2
			"~global": true
		}
	}
}

```

The stat modifiers are all under the "stats" JSON object within the modifiers object. The syntax supports putting the modifier set directly under "stats", or if you need several set with different global or specifier (see below), you can add several JSON objects within the "stats" object - one for each set.

In the example above there are two sets, one for "flux" which increases production speed by 30%, is global, and only affects entities with the "prodgroup-flux" specifier. The second one is a global modifier set, that decrease the threat interval by 15%, and increases amount of enemies by 20%, and it does not have any specifier.

```
"modifiers": {
	"stats": {
		"resourceamount": 0.1,
		"~spec": "objtype-bloodwoodresource",
		"~global": true
	}
}

```

In this simpler example the stat set is directly within the "stats" object, since there is only one set there was no need to add another nesting level. In this example the amount of resources in objects with the "objtype-bloodwoodresource" specifier are increased by 10%, and it is global so it affects all objects with this modifier.

## Global

The global setting determines whether this set of stat modifiers will only apply to the entity that the modifiers are associated with, or if it will apply globally to all entities of all types in the map.

For example, a piece of equipment that gives bonus damage will only affect Tiny (equipment modifiers are associated with Tiny), but if you set it to global, it will affect the damage of everything (including turrets and enemies). You can then add specifiers to limit the effect to turrets only (see below regarding specifiers).

Another example is an upgrade entity that provides a +50% production speed modifier. This modifier will only affect the building that received that upgrade. But you could also make it global so that it will affect all buildings. For example, if you wanted a level 4 city core to increase production of all your buildings by 10%, you could make it global. If you hadn't made it global it would only affect the city core.

## Specifiers

Specifiers are used to limit the modifier set to specific situations. There are different types of specifiers, depending on the situation. For example, you can add an "enemy" specifier to make sure that this modifier set only affects enemies, but won't affect the player. Or you can use a production group specifier when giving bonus to production speed, so that it would only affect a certain group of production recipes (for example, research).

There are many specifier options, and we won't list them all here, and many of them you can configure yourself by setting the "modifier-specifiers" setting of an entity, for example production recipes as in the research example above. Others are hardcoded. Here are some of the more useful specifiers:

**"objtype-[map object id]"** - this specifier will affect only a specific type of object. For example, "objtype-bloodwoodresource" will only affect bloodwood resource nodes.

**"prodrecipe-[production recipe id]"** - this specifier will affect only a specific production recipe. For example, the copper add-on to flux vats only affects the basic flux production, but not those that consume resources.

**"prodgroup-[group name]"** and **"objgroup-[group name]"** - these are used to represent groups of objects or groups of production recipes. These groups are defined with the "modifier-specifiers" setting of the production recipe or map object configuration, and you can modify them or add your own.

**"enemy-unit"** - this specifier is assigned to all enemy units, so use it if you want a modifier to affect enemies but not the player's units or buildings.

**"wpn-melee"** and **"wpn-ranged"** - use these for changes that you only want to affect either melee or ranged weapons. We use this in infrastructure upgrades that increase the damage of only melee or only ranged attacks, for example.

## Stat Modifier Types

There are 4 ways that stat modifiers can be applied to values, and each stat is one of these 4 types:

##### Additive

The most basic modifier type, an absolute value that is the sum of all the modifiers is added to the base value. For example, movement speed uses this, so modifiers that affect Tiny's movement speed are added on top of each other.

##### Multiplier

Multiplier works similarly to Additive, in that the system first sums up all the modifiers as one absolute value, but then, instead of adding the result to the base value, the base value will be multiplied by 1 + sum. For example, if you have two modifiers, 0.2 and 0.3 - their sum is 0.5, so the base value will be multiplied by 1.5 (as in +50%).

##### Exponential

With this modifier type, the base value is multiplied by 1 + each modifier separately. Using the example above, if you had one 0.2 and one 0.3 modifier, the result will be the base value multiplied by 1.2 (+20%), and then the result is multiplied by 1.3 (+30%) - for a total of base value \* 1.56 (+ 56%).

##### Bolean

Boolean works the same way additive does, but is converted to a true or false value - where anything greater than 0 is considered true. We use this, for example, with the ability that makes tiny Untargetable (enemies won't attack it). There is no "value" to being untargetable, it's simply true or false.

## Stats

There are many stat modifiers, you can find them all in the file StatModifiers.json. Here are the most useful ones and an explanation on how they are used.

### Combat / Unit stats

**"dmg"** - Damage. This is a multiplier type modifier, that affects attack damage.

**"attackrate"** - Attack rate. This is a multiplier type modifier that affects the speed in which an entity can attack.

**"attackrange"** - Attack range. This is an additive type modifier that affects the range of attacks.

**"cdn"** - Cooldown. This is a multiplier type modifier that affects cooldown time for abilities.

**"max-health"** - Maximum health. This is a multiplier type modifier that affects the maximum health of the entity.

**"receive-dmg"** - Received damage. This is a multiplier type modifier that affects the amount of damage received.

**"speed"** - Movement speed. This is an additive type modifier that affects a unit's movement speed.

**"cart-speed"** - Rail Cart Speed. This is a multiplier type modifier that affects the speed of rail carts. This should always be used in a global scope.

### Economy

**"prod-speed"** - Production Speed. This is an exponential type modifier that affects the production speed (both input consumption speed, and output production speed).

**"prod-outputamount"** - Production output. This is a multiplier type modifier that affects the production output rate, without affecting the consumption speed. This essentially changes the efficiency of the production recipe (amount produced vs raw materials used).

**"prod-inputamount"** - Production input. This is a multiplier type modifier that is the exact opposite of the prod-outputamount - it modifies the speed at which raw materials are consumed without affecting the output.

**"upkeep-inputamount"** - Upkeep Resources. This is an exponential type modifier that affects the rate at which resources are consumed for upkeep (doesn't affect the production, only the building upkeep). This won't affect assigned resources like workers.

**"upkeep-assigned"** - Upkeep Assigned. This is an exponential type modifier that affects the amount of assigned resources used to upkeep the building - ie how many workers are required.

### Other

**"building-weight"** - Weight. This is an exponential type modifier that affects the weight of a building.

**"carry-weight"** - Carry Weight. This is an exponential type modifier that affects the carry capacity of a building that provides carry capacity.

**"launch-costs"** - Launch Costs. This is an exponential type modifier that affects the fuel take-off costs of a building that provides carry capacity.

**"build-costs"** - Build Costs. This is an exponential type modifier that affects the costs of building.

**"demolish-refund"** - Demolish Refund Amount. This is a multiplier type modifier that affects the amount of resources refunded when demolishing a building.

**"threat-interval"** - Threat Interval. This is a multiplier type modifier that affects how long it takes for the threat level to increase.

**"global-difficulty-time"** - Global Difficulty Interval. This is a multiplier type modifier that affects how long it takes the global infestation level to increase.