Location

modrules.lua is a file in the Gamedata/ directory of a Spring game.

Purpose

This file controls various global parameters of the game, for example how fast units gain experience, what unit types can be transported, how fine grained the LOS system is, etc.

Source

The engine source code which parses the data from this file is viewable here:

• rts/Sim/Misc/ModInfo.cpp

Details

Modrules.lua is divided into several sub-tables containing tags specific to each section, as follows:

capture

float energyCostFactor Default: 0.0  

How much of the original energy cost it requires to capture something.

construction

bool constructionDecay Default: true  

Do uncompleted building frames begin to decay if no builder is working on them?

float constructionDecayTime Default: 6.66  

The time in seconds before abandoned building frames begin to decay.

float constructionDecaySpeed Default: 0.03  

How fast build progress decays for abandoned building frames. Note that the rate is inversely proportional to the buildtime = i.e. a building with a larger buildtime = will decay more slowly for a given value of this tag than a building with a shorter buildtime = .

experience

float experienceMult Default: 1.0  

Controls the amount of experience gained by units engaging in combat. The formulae used are:

xp for damage = 0.1 * experienceMult * damage / target_HP * target_power / attacker_power

xp for kill = 0.1 * experienceMult * target_power / attacker_power.

Where power = can be set by the UnitDef tag.

float powerScale Default: 1.0  

Controls how gaining experience changes the relative power = of the unit. The formula used is Power multiplier = powerScale * (1 + xp / (xp + 1)).

float healthScale Default: 0.7  

Controls how gaining experience increases the maxDamage = (total hitpoints) of the unit. The formula used is Health multiplier = healthScale * (1 + xp / (xp + 1)).

float reloadScale Default: 0.4  

Controls how gaining experience decreases the reloadTime = of the unit's weapons. The formula used is Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1)).

featureLOS

int featureVisibility Default: 3  

Controls the visibility of features. Can be 0 - no default LOS for features, 1 - Gaia features always visible, 2 - allyteam & Gaia features always visible, or 3 - all features always visible.

fireAtDead

bool fireAtKilled Default: false  

Will units continue to target and fire on enemies which are running their Killed() animation? (See Animation-LuaCallins#Generic)

bool fireAtCrashing Default: false  

Will units continue to target and fire on enemy aircraft which are in the 'crashing' state? (See Lua_SyncedCtrl#Unit_Control)

flankingBonus

For a deeper explanation of the flanking system, see Units:FlankingBonus.

int defaultMode Default: 1  

The default flankingBonusMode = for units. Can be 0 - No flanking bonus. Mode 1 builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode 2 also can swing, but moves with the unit as it turns. Mode 3 stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.

los

int losMipLevel Default: 1  

Controls the resolution of the LOS calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the LOS map in both x and y direction. Must be between 0 and 6 inclusive.

float losMul Default: 1.0  

Multiplies all unit's sightDistance = by this value. Generally speaking you should always use the default.

int airMipLevel Default: 2  

Controls the resolution of the LOS vs. aircraft calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the air-LOS map in both x and y direction. Must be between 0 and 30 inclusive.

float airLosMul Default: 1.0  

Multiplies all unit's airSightDistance = by this value. Generally speaking you should always use the default.

movement

bool allowAirPlanesToLeaveMap Default: true  

Are (gunship) aircraft allowed to fly outside the bounds of the map?

bool allowAircraftToHitGround Default: true New in version 90.0 

Are aircraft allowed to hit the ground whilst manoeuvring?

bool allowPushingEnemyUnits Default: false New in version 83.0 

Can enemy ground units push each other during collisions?

bool allowCrushingAlliedUnits Default: false New in version 85.0 

Can allied ground units crush each other during collisions? Units still have to be explicitly set as crushable using the crushable parameter of Spring.SetUnitBlocking.

bool allowUnitCollisionDamage Default: false New in version 85.0 

Do unit-unit (skidding) collisions cause damage?

bool allowUnitCollisionOverlap Default: true New in version 89.0 

Can mobile units collision volumes overlap one another? Allows unit movement like this (video) at the cost of more 'clumping'.

bool allowGroundUnitGravity Default: true New in version 92.0 

Allows fast moving mobile units to 'catch air' as they move over terrain.

bool allowHoverUnitStrafing Default: true if using QTPFS pathfinder New in version 92.0 

Allows hovercraft units to slide in turns.

bool useClassicGroundMoveType Default: false New in version 89.0 

A ticket back to unit movement circa 2009: no reversing, no turninplace = false, no smooth collision handling, no nothing. For comparison of pathfinding code.

nanospray

bool allow_team_colors Default: true  

Are players allowed to use teamcolour nanospray? Set by the TeamNanoSpray key in the config file.

paralyze

bool paralyzeOnMaxHealth Default: true  

Are units paralyzed when the level of emp is greater than their current health or their maximum health?

reclaim

int multiReclaim Default: 0  

Can multiple units reclaim a feature or only one? 0 implies the latter, all other values the former.

int reclaimMethod Default: 1  

Controls how features are reclaimed. Can be 0 - gradual reclaim, 1 - all reclaimed at end, any other positive value n - reclaim in n chunks.

int unitMethod Default: 1  

Controls how units are reclaimed. Can be 0 - gradual reclaim, 1 - all reclaimed at end, any other positive value n - reclaim in n chunks.

float featureEnergyCostFactor Default: 0.0  

How much energy should reclaiming a feature cost? Multiplier against the fraction of the features' metal = content reclaimed.

float unitEnergyCostFactor Default: 0.0  

How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's buildCostEnergy = reclaimed.

float unitEfficiency Default: 1.0  

How much metal should reclaiming a unit return? Multiplier against the unit's buildCostMetal = .

bool allowEnemies Default: true  

Can enemy units be reclaimed?

bool allowAllies Default: true  

Can allied units be reclaimed?

repair

float energyCostFactor Default: 0.0  

How much of the original energy cost it requires to repair something.

resurrect

float energyCostFactor Default: 0.5  

How much of the original energy cost it requires to resurrect something.

sensors

bool requireSonarUnderWater Default: true  

If true then when underwater, units only get LOS if they also have sonar.

system

int luaThreadingModel Default: 2  

Controls if and how the game supports Asynchronous Simulation, a more detailed explanation can be found here.

3 and greater is experimental/unstable!

Can be:

0 - No MT, single threaded;

1 - Single state;

2 - Single state, batching of unsynced events;

3 - Dual states for synced, batching of unsynced events, synced/unsynced communication via EXPORT table and SendToUnsynced;

4 - Dual states for synced, batching of unsynced events, synced/unsynced communication via SendToUnsynced only;

5 - Dual states for all, all synced/unsynced communication (widgets included) via SendToUnsynced only;

6 - Dual states for all, all synced/unsynced communication (widgets included) is unmanaged and via SendToUnsynced only.

int pathFinderSystem Default: 0 New in version 85.0 

Which pathfinder does the game use? Can be 0 - The legacy default pathfinder or 1 - Quad-Tree Pathfinder System (QTPFS).

transportability

bool transportAir Default: false  

Can aircraft be transported?

bool transportShip Default: false  

Can ships be transported?

bool transportHover Default: false  

Can hovercraft be transported?

bool transportGround Default: true  

Can ground units be transported?

bool targetableTransportedUnits Default: false New in version 89.0 

Can transported units be targeted by weapons? true allows both manual and automatic targeting.

Examples

Empty

modrules.lua can simply return an empty table like this:

return {}

If you do this, Spring will use the default values.

Configurable by modoptions

Interestingly modrules.lua can read modoptions, so these parameters can be scripted to be configurable from the lobby. For example to allow selecting either legacy default pathfinder or QTPFS via a modoption:

 system = {
   pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
 },

External Examples

'Balanced Annihilation' Modrules.lua

'Complete Annihilation' Modrules.lua

'Conflict Terra' Modrules.lua

'Evolution RTS' Modrules.lua

'Spring: 1944' Modrules.lua

'ZeroK' Modrules.lua