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 aircraft allowed to fly outside the bounds of the map?

bool allowPushingEnemyUnits  default: false New in version 83.0 

Can enemy units push each other out of the way?

bool allowCrushingAlliedUnits  default: false New in version 85.0 

Can allied units crush each other? 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 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 cost it requires to repair something.

resurrect

float energyCostFactor  default: 0.5 

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

capture

float energyCostFactor  default: 0.0 

How much of the original 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 gain for damaging a unit = 0.1 * experienceMult * damage / target's HP * target's power / attacker's power and XP gain for killing a unit = 0.1 * experienceMult * target's power / attacker's 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

Examples

Empty

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

return {}

if you do this, Spring will use its hardcoded default values.

Complete

This is the full modrules.lua of the zeroK game:

local modrules  = {

  construction = {
    constructionDecay      = false; -- defaults to true
    constructionDecayTime  = 6.66;  -- defaults to 6.66
    constructionDecaySpeed = 0.03;  -- defaults to 0.03
  },

  reclaim = {
    multiReclaim  = 1;    -- defaults to 0
    reclaimMethod = 0;    -- defaults to 1
    unitMethod    = 0;    -- defaults to 1

    unitEnergyCostFactor    = 0;  -- defaults to 0
    unitEfficiency          = 0.5;  -- defaults to 1
    featureEnergyCostFactor = 0;  -- defaults to 0

    allowEnemies  = false;  -- defaults to true
    allowAllies   = false;  -- defaults to true
  },


  repair = {
    energyCostFactor = 1/3,  -- defaults to 0
  },


  resurrect = {
    energyCostFactor = 1.2,  -- defaults to 0.5
  },


  capture = {
    energyCostFactor = 1,  -- defaults to 0
  },
  
  
  paralyze = {
    paralyzeOnMaxHealth = true, -- defaults to true
  },

  sensors = {
    requireSonarUnderWater = true,  -- defaults to true
    
    los = {
      losMipLevel = 3,  -- defaults to 1
      losMul      = 1,  -- defaults to 1
      airMipLevel = 4,  -- defaults to 2
      airMul      = 1,  -- defaults to 1
    },
  },


  transportability = {
    transportGround = 1;   -- defaults to 1
    transportHover  = 1;   -- defaults to 0
    transportShip   = 0;  -- defaults to 0
    transportAir    = 0;  -- defaults to 0
  },


  flankingBonus = {
    -- defaults to 1
    -- 0: no flanking bonus  
    -- 1: global coords, mobile  
    -- 2: unit coords, mobile  
    -- 3: unit coords, locked 
    defaultMode=0;
  },


  experience = {
    experienceMult = 1.0; -- defaults to 1.0

    -- these are all used in the following form:
    --   value = defValue * (1 + (scale * (exp / (exp + 1))))
    powerScale  = 0.7;  -- defaults to 1.0
    healthScale = 0;  -- defaults to 0.7
    reloadScale = 0.5;  -- defaults to 0.4
  },


  fireAtDead = {
    fireAtKilled   = false;  -- defaults to false
    fireAtCrashing = false;   -- defaults to false
  },


  nanospray = {
    allow_team_colors = true;  -- defaults to true
  },
  
  featureLOS = {
    -- 0 - no default LOS for features
    -- 1 - gaia features always visible
    -- 2 - allyteam/gaia features always visible
    -- 3 - all features always visible
    -- default 3
    featureVisibility = 1;
  },

  -- new in >84.0
  movement = {
    allowAirPlanesToLeaveMap = true;  -- defaults to true
    allowPushingEnemyUnits   = false; -- defaults to false
    allowCrushingAlliedUnits = false; -- defaults to false
    allowUnitCollisionDamage = false; -- defaults to false
  },

  -- new in >84.0
  system = {
    luaThreadingModel = 2;
    pathFinderSystem  = 0;
  },
}

return modrules