Gamedev:UnitDefs

Location

UnitDef files are .lua files stored in the Units/ directory of a Spring Game.

Purpose

UnitDef files have one purpose; to define the properties of units. They are the main description file for what attributes your unit should have and how it should behave.

Source

The engine source code which loads the tags from these files is viewable here:

https://github.com/spring/spring/blob/master/rts/Sim/Units/UnitDef.cpp

Data Types

Tags may be one of the following data types:

• int - An integer number
• float - A number with decimals.
• bool - A value which can be true or false.
• string - Text, or more precisely a string of alphanumeric characters.
• float[3] - A vector, with three float components, representing x, y and z axes (y is 'up').

Details

There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the lowerkeys function on your final table to ensure the keys are properly cased.

General

• name - type: string - default: ""

This is simply the name of the unit as it appears to the player.

• description - type: string - default: name

This is the tooltip description of the unit seen by the player. It defaults to the name of the unit.

• buildPic - type: string - default: ""

The filename of of the image to be used as the build picture.

• maxDamage - type: float - default: 0.0

The base 'hitpoints' the unit will have.

• autoHeal - type: float - default: 0.0

How much health the unit will regain every second.

• idleAutoHeal - type: float - default: 10.0

How much health the unit will regain every second whilst it is idle.

• idleTime - type: int - default: 600

The time in gameframes taken until a unit is considered to be idle.

• buildCostMetal - type: float - default: 0.0

The amount of metal resource the unit costs to build. Defaults to 0.0 but cannot actually be below 1.0.

• buildCostEnergy - type: float - default: 0.0

The amount of energy resource the unit costs to build.

• buildTime - type: float - default: 0.0

The time taken to build the unit, in conjunction with the workerTime of the constructor. Effectively, Time to build = unit buildTime / constructor workerTime. Defaults to 0.0 but cannot actually be below 1.0.

• mass - type: float - default: buildCostMetal

The mass of the unit, used in weapon impulse calculations. Any value <= 0.0 will default to the buildCostMetal.

• reclaimable - type: bool - default: true

Can the unit be reclaimed by a builder?

• capturable - type: bool - default: true

Can a unit be stolen by a builder using the capture command?

• repairable - type: bool - default: true

Can the unit be repaired by a builder?

• maxRepairSpeed - type: float - default: 1e20

The maximum cumulative speed at which this unit can be repaired.

Resources

• metalStorage - type: float - default: 0.0

The amount of the metal resource storage the unit contributes.

• energyStorage - type: float - default: 0.0

The amount of the energy resource storage the unit contributes.

• extractsMetal - type: float - default: 0.0

The amount of the metal resource the unit extracts from the ground. The amount extracted depends on the metal map defined in the map itself. Works only for structures.

• windGenerator - type: float - default: 0.0

The amount of the energy resource the unit generates which is dependant on the map wind. Works only for structures.

• tidalGenerator - type: float - default: 0.0

The amount of the energy resource the unit generates which is dependant on the maps tidal power. Clearly, this only works on water structures.

• metalUse - type: float - default: 0.0

The amount of the metal resource the unit consumes per game 'tick'.

• energyUse - type: float - default: 0.0

The amount of the energy resource the unit consumes per game 'tick'.

• metalMake - type: float - default: 0.0

The amount of the metal resource the unit generates unconditionally per game 'tick'.

• energyMake - type: float - default: 0.0

The amount of the energy resource the unit generates unconditionally per game 'tick'.

• makesMetal - type: float - default: 0.0

The amount of the energy resource the unit turns into the metal resource per game 'tick'.

Sensors

• onoffable - type: bool - default: false

Does the unit have an on/off button? Currently the activation status tied to this button also turns sensors (other than LOS) on and off.

• sightDistance - type: float - default: 0.0

The radius of the units sight (LOS is circular in Spring)

• airSightDistance - type: float - default: 1.5 * sightDistance

How far away the unit can see aircraft (and some FX).

Commands

• canMove - type: bool - default: false

Can the unit be issued Move orders?

• canAttack - type: bool - default: true

Can the unit be issued Attack orders?

• canFight - type: bool - default: true

Can the unit be issued Fight orders?

• canPatrol - type: bool - default: true

Can the unit be issued Patrol orders?

• canGuard - type: bool - default: true

Can the unit be issued Guard orders?

• canRepeat - type: bool - default: true

Can the unit be issued Guard orders?

• canSelfDestruct - type: bool - default: true

Can the unit be issued a self destruct order?

• canRestore - type: bool - default: builder

Can the unit be issued restore terrain commands? For builders only.

• canRepair - type: bool - default: builder

Can the unit be issued repair commands? For builders only.

• canReclaim - type: bool - default: builder

Can the unit be issued reclaim commands? For builders only.

Builder

• builder - type: bool - default: false

Is the unit a builder?

• buildDistance - type: float - default: 128.0

How far away from itself the unit can build, measured to the centre of the unit being built. The minimum value is 38.0.

• buildRange3D - type: bool - default: false

Does the builders buildDistance apply in all 3 dimensions or only 2?

• workerTime - type: float - default: 0.0

How fast the builder builds, used in conjunction with the buildTime of the unit being built. Effectively, Time to build = unit buildTime / constructor workerTime. If this value is <= 0.0 then builder is set to false.

• repairSpeed - type: float - default: workerTime

How fast the builder can repair other units.

• reclaimSpeed - type: float - default: workerTime

How fast the builder can reclaim other units and features.

• resurrectSpeed - type: float - default: workerTime

How fast the builder can resurrect corpse features back into living units.

• captureSpeed - type: float - default: workerTime

How fast the builder can capture other units.

• terraformSpeed - type: float - default: workerTime

How fast the builder levels and restores terrain.

• canAssist - type: bool - default: builder

Can the builder assist other constructions?

• canBeAssisted - type: bool - default: true

Can the builder be assisted by other builders?

• canSelfRepair - type: bool - default: false

Can the builder repair itself?

• fullHealthFactory - type: bool - default: false

If true, units are repaired before they are allowed to leave the factory i.e. units from this factory will be healed back to 100% health if they are damaged during construction.

Movement & Placement

• canSubmerge - type: bool - default: false

If the unit is a ship, is it a submarine? If the unit is an aircraft, can it land underwater?

• upright - type: bool - default: false

Does the unit follow the terrain or always remain upright? Generally used for walkers.

• maxSlope - type: float - default: 0.0

The maximum slope a building can be placed on. Clamped between 0.0 and 89.0. Mobile unit's use the maxSlope set in their movementClass (see Units:MoveTypes). To convert a value in degrees: maxSlope = 1 - cos(degrees * 1.5 * PI / 180).

• minWaterDepth - type: float - default: -10e6

The minimum depth of water a building can be placed on. Mobile unit's use the minWaterDepth set in their movementClass (see Units:MoveTypes).

• maxWaterDepth - type: float - default: 10e6

The maximum depth of water a building can be placed on. Mobile unit's use the maxWaterDepth set in their movementClass (see Units:MoveTypes).

• waterline - type: float - default: 0.0

How low in the water does a ship sit? Higher values means the ship is lower in the water.

• minCollisionSpeed - type: float - default: 1.0

The minimum net impact speed that will cause a unit to be damaged by collisions with another unit.

• pushResistant - type: bool - default: false

Can the unit be pushed around by other units? Turning it on doesn't remove all pushing but is a marked improvement.

Can the unit be issued Guard orders?

• maxVelocity - type: float - default: 0.0

The maximum speed attainable by the unit. Units are in map grids per second, where 1 map grid = 16 elmos. If the value is -ve, the absolute value is used.

• maxReverseVelocity - type: float - default: 0.0

The maximum speed attainable by the unit in reverse. Units are in map grids per second, where 1 map grid = 16 elmos. If the value is -ve, the absolute value is used.

• acceleration - type: float - default: 0.5

The acceleration of the unit, in map grids per second², where 1 map grid = 16 elmos. If the value is -ve, the absolute value is used.

• brakeRate - type: float - default: 3.0 * acceleration

The deceleration of the unit, in map grids per second², where 1 map grid = 16 elmos. If the value is -ve, the absolute value is used. For units with canFly this is multiplied by 0.1.

Aircraft

• canFly - type: bool - default: false

Can the unit fly, i.e. is it an aircraft?

• factoryHeadingTakeoff - type: bool - default: true

Controls the take-off behaviour of aircraft with hoverAttack. true means planes start matching their factory's heading right after taking off from the pad, false means they maintain the heading of the pad until reaching cruiseAlt.

• collide - type: bool - default: true

Does the unit collide with other aircraft, or can it occupy the same space?

Other

• decoyFor - type: string - default: ""

The unitdef name (not human name) which this unit is a decoy for.

Can the unit be issued Guard orders?

• selfDestructCountdown - type: int - default: 5

The length in seconds taken between issuing self destruct order and the unit exploding.