Modrules.lua

2013-08-14T18:19:21Z

Nixtux:

==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}}

==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|Units-UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Units-UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Units-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|Units-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|Units-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|Units-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|Units-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===
For a deeper explanation of the flanking system, see [[Units:FlankingBonus]].

{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Units-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
|description = Multiplies all unit's {{xtaglink|Units-UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 2
|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.
}}

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

===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}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Units-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|Units-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|Units-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|Units-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.
}}

===system===
{{tag
|name = luaThreadingModel
|type = int
|default = 2
|description = Controls if and how the game supports Asynchronous Simulation, a more detailed explanation can be found [[Asynchronous_Simulation#Lua_Threading_Models|here]].
3 and greater is experimental/unstable!

Can be:
::<code>0</code> - No MT, single threaded;
::<code>1</code> - Single state;
::<code>2</code> - Single state, batching of unsynced events;
::<code>3</code> - Dual states for synced, batching of unsynced events, synced/unsynced communication via EXPORT table and SendToUnsynced;
::<code>4</code> - Dual states for synced, batching of unsynced events, synced/unsynced communication via SendToUnsynced only;
::<code>5</code> - Dual states for all, all synced/unsynced communication (widgets included) via SendToUnsynced only;
::<code>6</code> - Dual states for all, all synced/unsynced communication (widgets included) is unmanaged and via SendToUnsynced only.}}

{{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 or <code>1</code> - Quad-Tree Pathfinder System ([[QTPFS]]).}}

===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:
<code><pre>
return {}
</pre></code>
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:
<code>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</code>

===External Examples===
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/gamedata/modrules.lua 'Balanced Annihilation' Modrules.lua]

[http://trac.caspring.org/browser/trunk/mods/ca/gamedata/modrules.lua 'Complete Annihilation' Modrules.lua]

[http://code.google.com/p/conflictterra/source/browse/games/CT/gamedata/modrules.lua 'Conflict Terra' Modrules.lua]

[https://code.google.com/p/evolutionrts/source/browse/trunk/evolutiondev.sdd/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

[http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/gamedata/modrules.lua?&view=markup 'Spring: 1944' Modrules.lua]

[http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/gamedata/modrules.lua 'ZeroK' Modrules.lua]

[[Category:gamedata]]

Spring - User contributions [en]

Modrules.lua