Modrules.lua

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:

movement

bool allowAirPlanesToLeaveMap  default: true 

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

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?

nanospray

bool allow_team_colors  default: true 

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

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 constructionDecaySpeed than a building with a shorter buildtime.

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. (See Units-FeatureDefs#Reclaim_&_Resources)

float unitEnergyCostFactor  default: 0.0 

How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's buildCostEnergy reclaimed. (See Units-UnitDefs#General)

float unitEfficiency  default: 1.0 

How much metal should reclaiming a unit return? Multiplier against the unit's buildCostMetal. (See Units-UnitDefs#General)

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.

capture

float energyCostFactor  default: 0.0 

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

paralyze

bool paralyzeOnMaxHealth  default: true 

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

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)

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?

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 (See Units-UnitDefs#Other).

float powerScale  default: 1.0 

Controls how gaining experience changes the relative power of the unit (See Units-UnitDefs#Other). 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 (See Units-UnitDefs#General). 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 (See Units-WeaponDefs). The formula used is Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1)).

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. (See also Units-UnitDefs#Flanking)

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.

sensors

bool requireSonarUnderWater  default: true 

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

los

int losMipLevel  default: 1 

Controls the resolution of the LOS calculations. A higher losMipLevel 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 (See Units-UnitDefs#Sensors) 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 airMipLevel 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 (See Units-UnitDefs#Sensors) by this value. Generally speaking you should always use the default.

system

int luaThreadingModel  default: 2 

Controls which Lua MT optimizations the mod will use by default. Can be:

0 - No MT, single threaded;

1 - Single state;

This mode has a single Lua environment for everything. It will cause a significant slowdown because simulation and rendering threads block each other trying to access the shared Lua environment. Especially problematic is Lua rendering; being inherently time consuming (looping through large amounts of units etc.) it will force the simulation thread to wait. This gives rise to the classic phenomenon of having incredibly high FPS but still lagging behind (high ping) since simulation cannot keep up with the normal pace.

2 - Single state, batching of unsynced events;

This mode is considerably better than mode(1) since it has a separate Lua environment for LuaUI.

All simulation events sent to LuaUI are also batched/delayed to reduce the need for the threads to block each other. For instance, if simulation triggers UnitMoved(), the event will not reach LuaUI right away, but is put in a batch and handled as soon as possible by the rendering thread. The batching system is managed, i.e. if the unit that triggered UnitMoved is about to be deleted (and thus invalidated) the batch is forcefully run before deletion occurs. Because the forced batch run is performed by the simulation thread, locking is required and this can degrade simulation performance for the same reasons as in mode(1).

The other means of unsynced communication, SendToUnsynced and Script.LuaUI.XXX() are also batched and managed to make sure any object ID or such sent are still valid once the message arrives. Note: Script.LuaUI.XXX() does because of the batching NOT have a return value.

This mode unfortunately suffers the same problems as mode(1) for rendering gadgets, since simulation events must be sent to the gadgets directly (without batching) in order not to desync the game.

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

Same as mode(2), but the gadgets have separate Lua environments depending on whether the simulation or rendering thread is invoking it. This alleviates the negative performance impact for rendering gadgets, but makes it impossible to directly share synced gadget data to the unsynced part via _G --> SYNCED. To work around this limitation, this mode introduces _G.EXPORT that is automatically copied to SYNCED.EXPORT. Only small amounts of data should be stored in the EXPORT table, because the copying is performed very frequently. Cyclical and/or very deeply nested tables are not allowed. Larger data can be stored temporarily, e.g.

_G.EXPORT.myhugetable = huge_table

SendToUnsynced("huge_table_available")

_G.EXPORT.myhugetable = nil

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

Same as mode(3) but with the EXPORT table disabled to increase the performance further. You don't need EXPORT, SendToUnsynced alone is sufficient.

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

Same as mode(4), but adds separate Lua environments for LuaUI depending on whether the simulation or rendering thread is invoking it. With dual LuaUI states, batching is no longer needed and therefore disabled. This makes it even faster, since batching overhead is eliminated and forced batch runs (see mode(2)) are not needed. However, this mode adds significant complexity for the programmer, since essentially two instances of the same widget are run, and only the calling thread determines which one is invoked. As a rule of thumb, all simulation events (GameFrame etc.) are invoked by the simulation thread. All UI and rendering events and Update() are invoked by the rendering thread. So, if a variable is modified in GameFrame(), that change cannot be seen in Update(). The widget must instead use SendToUnsynced to communicate any data from the simulation widget instance to the rendering widget instance. Design wise it may be suitable to write the widget similarly to a gadget, with clearly separated "synced" and "unsynced" parts, each with their own variables, functions and call-ins.

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

Same as mode(5) but the SendToUnsynced and Script.LuaUI.XXX() communication is unmanaged. The Lua coder must manually check if object references sent are still valid when the message arrives.

Which mode to use? The default mode(2) is usually good enough unless you need (execution time consuming) rendering gadgets. If you write a new widget/gadget, consider designing it to be compatible with a higher mode.


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).

Examples

Empty

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

return {}

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

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