Movedefs.lua

Movedefs.lua

Location

movedefs.lua is a file in the Gamedata/ directory of a Spring Game.

Purpose

This file defines MoveClasses which are used to determine pathing for units.

Source

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

• rts/Sim/MoveTypes/MoveDefHandler.cpp

Data Types

int

An integer number. eg. 5

float

A number with decimals. eg 1.023

bool

A value which can be true or false. eg true

string

Text, or more precisely a string of alphanumeric characters. eg "string of characters"

rgb

Three float components, representing red, green and blue components, ranged from 0.0 to 1.0. eg {0.0, 0.0, 0.0}

float3

Three float components, eg {0.0, 0.0, 0.0}

float4

Four float components, eg {0.0, 0.0, 0.0, 0.0}

Details

A mobile unit is assigned a MoveClass using the movementClass tag. The engine determines the unit's pathfinding based on the properties of the MoveClass, so analogous properties (e.g. footprintX) in the UnitDef should be the same for optimal behaviour.

All MoveClasses must belong to one of four possible types. A MoveClass is assigned a type simply by including it within the name string e.g. Tank_MyMoveClassName. Types are used in TypeMaps of Spring maps, which allow mappers to set per-type speed multipliers.

Types

• Bot - A ground based MoveClass. The default type if no matching type string is found.
• Tank - A ground based MoveClass. Identical to Bot other than interaction with TypeMaps.
• Ship or Boat - Are synonyms. All ships / boat MoveClasses must belong to this type to behave as ships.
• Hover - All hovercraft MoveClasses (traverse any depth of water without speed reduction) must belong to this class.

MoveClass Tags

string name  default: "" 

The name of the MoveClass. Usually passed by the sub-table variable name rather than using this tag (See #Example). Prior to 9.50 this had to contain "tank", "hover", "ship" or "boat" respectively for non-Bot types. This is now set using speedModClass.

int speedModClass  default: 1 New in version 95.0

Determines the speed modifier class used (See Mapdev:terraintype). Accepted values are 0 = Tank, 1 = KBot, 2 = Hover, 3 = Ship.

int footprintX  default: 1 

How wide the MoveClass is in footprint units, left to right. 1 footprint unit = 16 elmos. Cannot be below 1. For mobile units this should be the same as the footprintX of its UnitDef.

int footprintZ  default: footprintX 

How wide the MoveClass is in footprint units, top to bottom. 1 footprint unit = 16 elmos. Cannot be below 1. For mobile units this should be the same as the footprintZ of its UnitDef.

float crushStrength  default: 10.0 

Power of a unit with this MoveClass to crush features and units. Any features with a crushResistance less than this value will be crushed on contact. Any units with crushing enabled via Spring.SetUnitBlocking), in an impact where collider impulse exceeds collidee impulse and whose crushResistance is less than this value will also be crushed.

float maxSlope  default: 60.0 (15.0 for hover types) 

The maximum steepness of slope a unit with this MoveClass can climb in degrees. For further details see #How_slope_is_determined.

float slopeMod  default: 4.0 / (maxSlope + 0.001) 

How much a slope will slow a unit, 0 means no slowdown.

bool avoidMobilesOnPath  default: true 

Do the units attempt to avoid other mobile units when pathing?

• Pro: groups moving without a ctrl-order clump much less
• Contra: groups moving with a ctrl-order are less organized

bool allowTerrainCollisions  default: true New in version 96.0

Disable this to improve handling of large (>4 x 4) footprint units (See #4217 ).

bool allowRawMovement  default: false New in version 104.0

Enables native "raw move" (straight-line path) support (See also Spring.SetUnitMoveGoal and #4412 ).

Heat Tags

These tags are used in unit avoidance.

bool heatMapping  default: false 

This enables/disables generation and usage of path heats.

float heatMod  default: 0.0042 

The pathfinder cost modifier that is multiplied by the heat of the current square.

int heatProduced  default: 30 

How much heat to place on a square if a path goes through it. heat set = max(currentSquareHeat, heatProduced).

Flow Field Tags

These tags are used in unit avoidance.

bool flowMapping  default: true 

This enables/disables flow field mapping.

float flowMod  default: 1.0 

Multiplied by the objects mass for the y-component (up) of the flow vector. No idea what effect this has.

Tank & Bot-Only Tags

float depthMod  default: 0.1 

How much water will slow amphibious units. The deeper the water, the slower the movement.Replaced with a subtable in Spring 86.x

float maxWaterDepth  default: 0.0 

The maximum depth of water in elmos the unit can wade through.

Ship-Only Tags

float minWaterDepth  default: 10.0 

The minimum depth of water in elmos the ship requires to float in.

bool subMarine  default: false 

Is the ship a submarine; can it move underneath other ships?

Sub Tables

depthModParams

Only read for Bot and Tank MoveClasses, the depthModParams group contains several sub-tags. Depthmod is a system for changing the speed of units depending on how deep they are underwater.

      new formula is given by
        if h < depthModParams.minHeight: 1.0
        if h > depthModParams.maxHeight: 0.0
        else:
          depthScale = MAX(0.01, MIN(depthModParams.maxScale, (a * h * h) + (b * h) + c))
          depthMod = 1 / depthScale
      where
        h = unit's absolute height below water surface
        a = depthModParams.quadraticCoeff
        b = depthModParams.linearCoeff
        c = depthModParams.constantCoeff

float minHeight  default: 0.0 

The minimum depth where the depthMod curve applies. If the unit is shallower than the minHeight, no change in speed occurs.

float maxHeight  default: MAX_FLOAT 

The maximum depth where the depthMod curve applies. If the unit is deeper than the maxHeight, the unit is immobilized.

The following tags control the behavior of the unit within the active portion of the curve (depth is greater than minHeight but less than maxHeight). It would be best to simply open up your graphing program of choice and use the provided formula, but if you're scared of graphs you should read the descriptions below:

float maxScale  default: MAX_FLOAT 

This is the cap on how severe the depth effect can be. For example, lets say that you use a maxScale value of 2. If a unit is at the depth where its scale reaches the max (usually near its maximum depth; with a maxScale value of 2), the slowest it will go is half of its maximum speed. In other words, (maxVelocity / maxScale). Therefore, as another example, a value of 4 would cause the unit's maximum speed (near the units maximum depth) to be 25% of it's maxVelocity.

float quadraticCoeff  default: 0.0 

The application of the speed-divider effect is modelled as a quadratic. This is the "depth-squared" component of that. That is, a value set here will be applied exponentially as the unit gets deeper, therefore it is best to use very small numbers for this tag.

float linearCoeff  default: depthMod 

The application of the speed-divider effect is modelled as a quadratic. This component makes divisor increase linearly with the depth of the unit. So with a value of 0.1, for example, a unit would go from 1/2 speed to 1/3 speed and 1/3 speed to 1/4 speed each time it goes 10 units deeper.

float constantCoeff  default: 1.0 

The application of the speed-divider effect is modelled as a quadratic. This is the constant component of the divisor. If you want a gradual decrease of speed and your minHeight = 0 (the waterline) then this value must be 1. Using less than 1 will cause the unit to go faster as it hits the water, and using greater than 1 will cause the unit to abruptly slow down the moment it gets its feet wet. If you're not using minHeight = 0, you'll have to adjust this value accordingly to get a smooth application of the depthMod divider.

speedModMults

New in version 86.0

These previously hard-coded variables allow control over how the pathfinder (default only, not QTPFS, see Modrules.lua) calculates the cost for a MoveClass for squares containing mobile units, if and only if avoidMobilesOnPath = true.

float mobileBusyMult  default: 0.1 

The cost multiplier for mobile units which are 'Busy'; Not currently being built and with a non-empty command queue, but not moving on a path. Clamped to values above 0.01.

float mobileIdleMult  default: 0.35 

The cost multiplier for mobile units which are 'Idle'; Either currently being built or with an empty command queue. Clamped to values above 0.01.

float mobileMoveMult  default: 0.65 

The cost multiplier for mobile units which are 'Moving'; Trying to follow their own path. Clamped to values above 0.01.

How slope is determined

Spring doesn't represent terrain slopes in degrees, internally it uses (1.0 - the terrain normal's y-component) so the slope of vertical faces is 1 and that of horizontal ones 0. A unit's maxSlope value (which is in degrees in its movedef) is converted so that the "can we go here?" (ie "maxSlope > terrainSlope?") comparisons are meaningful, the formula is 1.0 - cos(DEG2RAD(maxSlope * 1.5)). If you want to know the terrain angle in degrees, compute RAD2DEG(arccos(1.0 - terrainSlope)). For a bot with a maxSlope of 36 degrees (~0.41221 in "Spring format"), the maximum tolerable terrain angle is approximately

RAD2DEG(arccos(1.0 - 0.41221))

or 54 degrees. If maxSlope was 30, the MTTA would be 45, and if it was 60 (the highest sensible value due to that 1.5 scalar and the absence of overhanging cliffs) the bot could mount any terrain. In other words you do not need the long mathematical derivation, just remember that maxTerrainAngle = maxSlope * 1.5

--kloot, Thu Jul 31, 2008

Code to check your movdefs

A resource to check movedefs that game developers have used for years and find it quite useful.

Example

External Examples

'Balanced Annihilation' movedefs.lua

'Spring: 1944' movedefs.lua

'Spring Tutorial Game' movedefs.lua

'ZeroK' movedefs.lua