Modding:Modifiers

Modifiers are a powerful tool to be used in modding. Here is an example for their basic structure (AssaultDoctrine.xml):

<modifiers>
    <modifier>
        <conditions>
            <unit>
                <type name="SpaceMarines/AssaultSpaceMarine"/>
            </unit>
        </conditions>
        <effects>
            <accuracy add="2"/>
        </effects>
    </modifier>
</modifiers>

<modifiers>[]

Contains any number of modifiers.

There are a couple alternatives to the standard <modifiers> tag which trigger during different times and apply to different targets, more information below.

Code	Explanation
<modifiers> </modifiers>	Modifiers that are applied when the unit receives the trait.
<onCombatOpponentModifiers> </onCombatOpponentModifiers>	Modifiers that apply to the target of an attack. Used to apply a trait to an enemy in Concussive.xml.
<opponentModifiers> </opponentModifiers>	Similar to onCombatOpponentModifiers, but only last for the duration of the attack. Used in Lance.xml to limit the enemy's armor value to 8 for the duration of the attack.
<onTraitRemovedModifiers> </onTraitRemovedModifiers>	Modifiers that apply when the trait is removed.
<onTileEnteredModifiers> </onTileEnteredModifiers>	Modifiers that apply to units that entered this tile. Found in ClusterMines.xml
<perTurnModifiers> </perTurnModifiers>	Modifiers that apply at the start of each turn?
<onUnitDisappearedModifiers> </onUnitDisappearedModifiers>	Modifiers that apply when the unit that carries this trait is destroyed. Found in PsychneueinInfestation.xml

<modifier>[]

Contains effects and optionally also triggering conditions.

The <modifier> tag can have the following attributes:

<modifier visible="0">

Causes the modifier effects not to be visible in the tooltip.

<modifier requiredUpgrade="Necrons/CityDefenseBonus">

Causes the modifier effects to require a research upgrade to be unlocked.

<conditions>[]

Contains conditions which have to be true for the effects to be applied. If several conditions are listed, all must be true (AND logic), unless conditions block has <conditions match="Any">, in this case only one single condition must be true (OR logic).

Code	Explanation
<unit> </unit> <building> </building> <weapon> </weapon> <tile> </tile> <player> </player>	Used when the conditions must check this unit, building, weapon, tile or owning player.
<encounter> </encounter>	Used when the conditions check for units in a specific combat encounter. See below for detailed notes.

The tags above are needed for the following checks (see example at the top of the page):

Code	Explanation
<enemy/>	Checks if a unit is an enemy.
<allied/>	Checks if a unit is allied.
<notMovedThisTurn/>	Checks if a unit did not move.
<overwatching/>	Checks if it is during a unit's overwatch attack.
<type name="SpaceMarines/AssaultSpaceMarine"/>	Checks if the object is a specific kind of object. Use '<noType ...' to check if the object is not a specific kind.
<[Stat] greater="X"/>	Checks if a stat of the object is bigger than X. Available stats depends on what object (unit, building, weapon, etc) is referenced.
<[Stat] less="X"/>	Checks if a stat of the object is smaller than X. Available stats depends on what object (unit, building, weapon, etc) is referenced.
<[Stat] equal="X"/>	Checks if a stat of the object is equal to X. Available stats depends on what object (unit, building, weapon, etc) is referenced.
<trait name="Flyer"/>	Checks if a unit has a certain trait. Use '<noTrait ...' for unit that don't have the trait.
<unitsInRange count="1" range="1"></unitsInRange>	Checks if there's at least "count" of units within a certain range around this unit. You can add more conditions inside the block to filter specific units.
<feature name="Forest"/>	Checks about a tile's terrain features. Use '<noFeature ...' to check the absence of a feature.
<enemyMajorityInRange range="1"/>	Checks whether there are more enemy units than allied within the specified range.
<faction name="Neutral"/>	Checks a player's faction. Use '<noFaction ...' for players that don't have the faction. Applies to a unit or a player. In '<unitsInRange ...' block it must be wrapped in '<player>...</player>' to work correctly.

If you need to check for only one condition in the list, use match="Any":

Code	Explanation
<unit match="Any"> <weapon match="Any"> <opponent match="Any"> <... match="Any">	Applicable to all condition blocks. Used to indicate that only one of several conditions listed inside the block must be true for the entire block to pass (OR logic). By default, all conditions listed inside must be true for the entire block to pass (AND logic).

This one seems to work slightly differently because it's found outside of modifiers:

Code	Explanation
<targetConditions> <unit> <trait name="Flyer"/> </unit> </targetConditions>	Similar to weapon <target> conditions. If this trait is applied to a weapon, the weapon will only fire when targetConditions are true. If this trait isn't applied to a weapon, then it does nothing.

Encounter conditions:

Code	Explanation
<encounter> <self> </self> <opponent> </opponent> <opponentTile> </opponentTile> <weapon> </weapon> </encounter>	<self> references this unit, <opponent> references opposing unit. <opponentTile> references the tile under opponent unit (there might be <selfTile> as well). <weapon> references weapon used in the attack. All are optional.
<encounter> <opponent> <attacking/> </opponent> </encounter>	Checks whether opponent is attacking. Use <noAttacking/> to check for the opposite.
<encounter> <opponent> <destroyed/> </opponent> </encounter>	Checks whether opponent was destroyed in the encounter. You can also use it in <self> block.
<encounter> <opponent> <firingMeleeWeapons/> </opponent> </encounter>	Checks whether opponent used melee weapons in the encounter. You can also use it in <self> block.

<effects>[]

Can do a number of different things like change values or spawn and remove units or apply traits to units. For a list of things that can be inserted for [Stat], see Stats

Code	s
<[Stat] set="X"/>	Sets the base value to X. The value can still be increased or decreased by other modifiers.
<[Stat] add="X"/>	Adds or subtracts (if negative) X from the value.
<[Stat] mul="0.5"/>	Adds or subtracts (if negative) a percentage of the base value. All multiplier modifiers are additive to each other - 'mul="0.5"' and 'mul="-0.5"' in a different place will result in value not being modified since both modifiers add to 0.
<[Stat] min="6" max="6"/>	Sets the minimum and maximum value. This can also just be only one of the two.
<[Stat] addMax="6" addMin="2"/>	Used for effects with multiple ranks like hero abilities.
<[Stat] mulMax="0.25" mulMin="0.05"/>	Used for effects with multiple ranks like hero abilities.
<[Stat] minMax="0.5" minMin="0.5"/>	Used for effects with multiple ranks like hero abilities.
<weaponDamage weapon="Blighted"/>	Deals the damage of a specific weapon.
<addTrait duration="1" name="Concussion"/>	Adds a trait for a specific duration.
<removeUnit/>	Removes the unit.
<removeFeature name="ClusterMines"/>	Removes the terrain feature.
<addUnit name="Neutral/Psychneuein"/>	Spawns a unit.
<cooldown add="-1"/>	Changes the cooldown of an ability.

Stats[]

Stats are values that can be changed by effects or checked by conditions.

Basic unit stats[]

These are all the unit stats listed in their default order by the UnitTypeManager.xml file under World\Blueprints.

actionPointsMax: Action Points Determines how many actions a unit can take in a turn. Shooting consumes one action point.
armor: Armour Determines the unit's armor points.
meleeArmorPenetration: Determines the unit's default melee armor penetration. Can be modified and replaced by the weapon's melee attributes themselves.
cargoSlots: Cargo Slots Determines how many cargo slots the unit has. Each slot represents a unit it can carry.
cargoSlotsRequired: Determines how many cargo slots the unit occupies when inside a transport unit.
experienceGainRate: Determines a multiplicative factor for how fast the unit gains experience points. Example: "1.5" for it to gain 50% more experience than normal.
healingRate: Determines how fast the unit recovers its health when idle for a turn, as percentage value.
itemSlots: Determines how many items the unit can carry.
levelMax: Determines how many levels the unit can gain at most. Default of 9 (up until level 10).
meleeAccuracy: Determines the unit's default melee accuracy. Can be modified and replaced by the weapon's melee attributes themselves.
meleeAttacks: Determines the unit's default melee attacks. Can be modified and replaced by the weapon's melee attributes themselves.
moraleLossFactor: Determines a multiplicative factor for morale loss. Exempple: "0.67" for it to receive only 67% of the morale loss it would normally receive.
moraleMax: Determines the maximum morale points the unit can have.
moraleRegeneration: Determines how fast the morale points the unit recovers when idle.
movementMax: Determines how many hexes the unit can move on its turn.
productionCost: Determines how much production has to be spent in order to produce this unit.
rangedAccuracy: Determines the unit's default ranged accuracy value. Often modified by the weapons through adding or removing accuracy. Can be replaced by a weapon's base values instead.
sight: Determines how many hexes the unit can see as a radius.

There are other attributes that can be used in modifiers, often found in Traits, Weapons, and Actions. The following is a non-exhaustive list of them. They may need to be verified.

hitpointsFraction: Fraction is a fraction of the max hitpoints, but applied to the current hitpoints.
healthPercentage: Might be the remaining health as a percentage. Used for conditions.
movement: Current Movement points.
movementCost: The movement cost of a tile. A forest increases movement cost by 1. A city sets the maximum to 1 for allied units. <movementCost min="100"/> force the move to end.
stealth: Maybe makes units invisible, maybe makes them ignore overwatch? <stealth add="1"/> found in forest.xml.
influencePerExperience: Sets an amount of influenced gained with experience. Used by the Space Marine Captain ability.
hitpointsPerMoraleLoss: How much Hitpoints are lost (maybe gained) by morale loss?

Resource related[]

production: Determines how much a building generates.
productionCost: Determines the cost for the construction of a unit or building.
requisitions, energy, food, ore, influence, research, biomass, loyalty: Produces resources per turn when positive, costs upkeep per turn when negative. When applied as mul to a tile then it will be the tile's resource yield.
requisitionsCost, energyCost, foodCost, oreCost, influenceCost, biomassCost: One time production cost.
requisitionsUpkeep, energyUpkeep, foodUpkeep, oreUpkeep, influenceUpkeep, biomassUpkeep: Upkeep for all resources.
populationRequired: Determines how many population points does the building require to function at full capacity.
slotsRequired: Determines how many building slots available the building requires to be built.
growth: Population Growth for cities.
populationLimit: Determines how many population points the cities city can house.

Combat related[]

accuracy, rangedAccuracy, meleeAccuracy: Total, ranged and melee Accuracy.
damage, rangedDamage, meleeDamage: Total, ranged and melee Damage.
attacks, meleeAttacks: Total, and melee Attacks.
armorPenetration, rangedArmorPenetration, meleeArmorPenetration: Total, ranged and melee Armour Penetration.
attacksTaken: Increases amount of attacks when attacked? Found in swarms.xml.
additionalMembersHit: Applies the weapon damage to multiple members of a squad. Used by blast and template weapons. See damage calculation.
circumstanceMeleeDamage: Melee damage modifier. Used by Fear.xml and Zealot.xml.
minDamageFromHitpointsFraction: Used by Gauss: Scales the minimum damage with the hitpoints of the target unit.
weapons.
damageFromHitpoints: Used by Gauss: Scales the minimum damage with the hitpoints of the target unit.
weapons.
rangedDamageReduction, invulnerableDamageReduction, feelNoPainDamageReduction, witchfireDamageReduction, cityDamageReduction, heroDamageReduction: Types of Damage Reduction. See damage calculation.
rangedDamageReductionBypass: Makes attacks ignore ranged Damage Reduction. <rangedDamageReductionBypass add="1.0"/> will bypass 100%.
damageTaken: Changes how much damage is taken? Found in misfortune.xml.
encounterRange: Allows checking for range of a specific encounter.

Other information[]

For traits, the category="buff" or category="debuff" attribute controls the colour of the icon. Buff is green and debuff red.