Qrow: 1 revision imported

2026-02-24T06:39:02Z

1 revision imported

← Older revision	Revision as of 23:39, 23 February 2026
(No difference)

gamedatainter>Forboding angel: /* system */

2022-07-05T05:23:32Z

system

New page

==Location==
<code>modrules.lua</code> is a file in the <code>Gamedata/</code> 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:

* {{sourcelink|file=rts/Sim/Misc/ModInfo.cpp}}

==Data Types==
{{DataTypes}}

==Details==
<code>Modrules.lua</code> is divided into several sub-tables containing tags specific to each section, as follows:

===capture===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to capture something.
}}

===construction===
{{tag
|name = constructionDecay
|type = bool
|default = true
|description = Do uncompleted building frames begin to decay if no builder is working on them?
}}

{{tag
|name = constructionDecayTime
|type = float
|default = 6.66
|description = The time in seconds before abandoned building frames begin to decay.
}}

{{tag
|name = constructionDecaySpeed
|type = float
|default = 0.03
|description = How fast build progress decays for abandoned building frames. Note that the rate is inversely proportional to the {{xtaglink|Gamedev:UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Gamedev:UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Gamedev:UnitDefs|buildtime}}.
}}

===experience===
{{tag
|name = experienceMult
|type = float
|default = 1.0
|description = Controls the amount of experience gained by units engaging in combat. The formulae used are:
::<code>xp for damage = 0.1 * experienceMult * damage / target_HP * target_power / attacker_power</code>
::<code>xp for kill = 0.1 * experienceMult * target_power / attacker_power</code>.
: Where {{xtaglink|Gamedev:UnitDefs|power}} can be set by the UnitDef tag.
}}

{{tag
|name = powerScale
|type = float
|default = 1.0
|description = Controls how gaining experience changes the relative {{xtaglink|Gamedev:UnitDefs|power}} of the unit. The formula used is <code>Power multiplier = powerScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = healthScale
|type = float
|default = 0.7
|description = Controls how gaining experience increases the {{xtaglink|Gamedev:UnitDefs|maxDamage}} (total hitpoints) of the unit. The formula used is <code>Health multiplier = healthScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = reloadScale
|type = float
|default = 0.4
|description = Controls how gaining experience decreases the {{xtaglink|Gamedev:UnitDefs|reloadTime}} of the unit's weapons. The formula used is <code>Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1))</code>.
}}

===featureLOS===
{{tag
|name = featureVisibility
|type = int
|default = 3
|description = Controls the visibility of features. Can be <code>0</code> - no default LOS for features, <code>1</code> - Gaia features always visible, <code>2</code> - allyteam & Gaia features always visible, or <code>3</code> - all features always visible.
}}

===fireAtDead===
{{tag
|name = fireAtKilled
|type = bool
|default = false
|description = Will units continue to target and fire on enemies which are running their <code>Killed()</code> animation? (See [[Animation-LuaCallins#Generic]])
}}

{{tag
|name = fireAtCrashing
|type = bool
|default = false
|description = Will units continue to target and fire on enemy aircraft which are in the 'crashing' state? (See [[Lua_SyncedCtrl#Unit_Control]])
}}

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. Can be <code>0</code> - No flanking bonus. Mode <code>1</code> builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode <code>2</code> also can swing, but moves with the unit as it turns. Mode <code>3</code> stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.
}}

===los===
{{tag
|name = losMipLevel
|type = int
|default = 1
|description = 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 <code>0</code> and <code>6</code> inclusive.
}}

{{tag
|name = losMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 1
|description = 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 <code>0</code> and <code>30</code> inclusive. [http://springrts.com/mantis/view.php?id=4031#c11709] - jK describe for you what the value means.
}}

{{tag
|name = airLosMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|airSightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = radarMipLevel
|type = int
|default = 2
|description = Controls the resolution of the radar. See description of airMipLevel for details.
}}

===movement===
{{tag
|name = allowAirPlanesToLeaveMap
|type = bool
|default = true
|description = Are (gunship) aircraft allowed to fly outside the bounds of the map?
}}

{{tag
|name = allowAircraftToHitGround
|type = bool
|default = true
|special = {{new|90.0}}
|description = Are aircraft allowed to hit the ground whilst manoeuvring?
}}

{{tag
|name = allowPushingEnemyUnits
|type = bool
|default = false
|special = {{new|83.0}}
|description = Can enemy ground units push each other during collisions?
}}

{{tag
|name = allowCrushingAlliedUnits
|type = bool
|default = false
|special = {{new|85.0}}
|description = Can allied ground units crush each other during collisions? Units still have to be explicitly set as crushable using the <code>crushable</code> parameter of [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]].
}}

{{tag
|name = allowUnitCollisionDamage
|type = bool
|default = false
|special = {{new|85.0}}
|description = Do unit-unit (skidding) collisions cause damage?
}}

{{tag
|name = allowUnitCollisionOverlap
|type = bool
|default = true
|special = {{new|89.0}}
|description = Can mobile units collision volumes overlap one another? Allows unit movement like [http://www.youtube.com/watch?v=mRtePUdVk2o this (video)] at the cost of more 'clumping'.
}}

{{tag
|name = allowGroundUnitGravity
|type = bool
|default = true
|special = {{new|92.0}}
|description = Allows fast moving mobile units to 'catch air' as they move over terrain.
}}

{{tag
|name = allowHoverUnitStrafing
|type = bool
|default = true if using QTPFS pathfinder
|special = {{new|92.0}}
|description = Allows hovercraft units to slide in turns.
}}

{{tag
|name = useClassicGroundMoveType
|type = bool
|default = false
|special = {{new|89.0}} {{removed|102.0}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Gamedev:UnitDefs|turninplace|false}}, no smooth collision handling, no nothing. For comparison of pathfinding code.
}}

===paralyze===
{{tag
|name = paralyzeOnMaxHealth
|type = bool
|default = true
|description = Are units paralyzed when the level of emp is greater than their current health or their maximum health?
}}

===reclaim===
{{tag
|name = multiReclaim
|type = int
|default = 0
|description = Can multiple units reclaim a feature or only one? <code>0</code> implies the latter, all other values the former.
}}

{{tag
|name = reclaimMethod
|type = int
|default = 1
|description = Controls how features are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = unitMethod
|type = int
|default = 1
|description = Controls how units are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = featureEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a feature cost? Multiplier against the fraction of the features' {{xtaglink|Gamedev:FeatureDefs|metal}} content reclaimed.
}}

{{tag
|name = unitEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's {{xtaglink|Gamedev:UnitDefs|buildCostEnergy}} reclaimed.
}}

{{tag
|name = unitEfficiency
|type = float
|default = 1.0
|description = How much metal should reclaiming a unit return? Multiplier against the unit's {{xtaglink|Gamedev:UnitDefs|buildCostMetal}}.
}}

{{tag
|name = allowEnemies
|type = bool
|default = true
|description = Can enemy units be reclaimed?
}}

{{tag
|name = allowAllies
|type = bool
|default = true
|description = Can allied units be reclaimed?
}}

===repair===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to repair something.
}}

===resurrect===
{{tag
|name = energyCostFactor
|type = float
|default = 0.5
|description = How much of the original energy cost it requires to resurrect something.
}}

===sensors===
{{tag
|name = requireSonarUnderWater
|type = bool
|default = true
|description = If <code>true</code> then when underwater, units only get LOS if they also have sonar.
}}
{{tag
|name = alwaysVisibleOverridesCloaked
|type = bool
|default = false
|special = {{new|101.0}}
|description = If <code>true</code> then units will be visible even when cloaked (probably?).
}}
{{tag
|name = separateJammers
|type = bool
|default = true
|special = {{new|101.0}}
|description = When <code>true</code> each allyTeam only jams their own units.
}}

===system===
{{tag
|name = pathFinderSystem
|type = int
|default = 0
|special={{new|85.0}}
|description = Which pathfinder does the game use? Can be <code>0</code> - The legacy default pathfinder, <code>1</code> - Quad-Tree Pathfinder System ([[QTPFS]])}} or <code>-1</code> - disabled.

{{tag
|name = pathFinderUpdateRate
|type = float
|default = 0.007
|special={{new|98.0}}
|description = Controls how often the pathfinder updates; larger values means more rapid updates.}}

{{tag
|name = pathFinderRawDistMult
|type = float
|default = 1.25
|special={{new|105.+ BAR}}
|description = Engine does raw move with a limited distance, this multiplier adjusts that}}

{{tag
|name = allowTake
|type = bool
|default = true
|special = {{new|103.0}}
|description = Enables and disables the {{var|/take}} [[UI_commands|UI command]].}}

===transportability===
{{tag
|name = transportAir
|type = bool
|default = false
|description = Can aircraft be transported?
}}

{{tag
|name = transportShip
|type = bool
|default = false
|description = Can ships be transported?
}}

{{tag
|name = transportHover
|type = bool
|default = false
|description = Can hovercraft be transported?
}}

{{tag
|name = transportGround
|type = bool
|default = true
|description = Can ground units be transported?
}}

{{tag
|name = targetableTransportedUnits
|type = bool
|default = false
|special = {{new|89.0}}
|description = Can transported units be targeted by weapons? <code>true</code> allows both manual and automatic targeting.
}}

==Examples==

===Empty===

<code>modrules.lua</code> can simply return an empty table like this:
<pre>
return {}
</pre>
If you do this, Spring will use the default values.

===Configurable by modoptions===
Interestingly <code>modrules.lua</code> can read [[Modoptions.lua|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:
<pre>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</pre>

===External Examples===
[https://github.com/EvolutionRTS/Evolution-RTS/blob/master/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

[[Category:gamedata]]

Modrules.lua - Revision history

Qrow: 1 revision imported

gamedatainter>Forboding angel: /* system */