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.

It is usual to name the returned UnitDef table the internal unitName desired for the unit.

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 the image to be used as the build picture.

• objectName - type: string - default: ""

The filename of the 3D model file for this unit, assumes Objects3D/ directory.

• script - type: string - default: unitName + ".cob"

The filename of the animation script file for this unit, assumes Scripts/ directory. Default assumes .cob file but LUS should be preferred.

• 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.

• iconType - type: string - default: "default"

The name of the radar icon type this unit should use. See Icontypes.lua.

• corpse - type: string - default: ""

The name of the feature this unit should leave behind as a wreck when it dies (See Units-FeatureDefs).

• explodeAs - type: string - default: ""

The name of the weapon this unit should explode as when it is killed (See Units-WeaponDefs).

• selfDestructAs - type: string - default: ""

The name of the weapon this unit should explode as when it self destructs (See Units-WeaponDefs). Also used as the kamikaze weapon.

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.

• extractSquare - type: bool - default: false

is the metal extractors extraction area circular or square?

• 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.

• activateWhenBuilt - type: bool - default: false

Should the unit's activation status be on or off when it is created?

• 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).

• losEmitHeight - type: float - default: 20.0 New in version 0.83.x

How high up the unit is the point used to calculate it's LOS vs. the terrain?

• radarEmitHeight - type: float - default: 20.0 New in version 0.83.x

How high up the unit is the point used to calculate it's radar vs. the terrain?

• radarDistance - type: int - default: 0

The radius of the units radar.

• sonarDistance - type: int - default: 0

The radius of the units sonar.

• radarDistanceJam - type: int - default: 0

The radius of the units radar jamming.

• sonarDistance - type: int - default: 0

The radius of the units sonar jamming.

• stealth - type: bool - default: false

Is the unit undetectable by radar?

• sonarStealth - type: bool - default: false

Is the unit undetectable by sonar?

• cloakCost - type: float - default: -1.0

The energy cost per tick to cloak the unit while it is stationary. Values < 0 means the unit cannot cloak.

• cloakCostMoving - type: float - default: cloakCost

The energy cost per tick to cloak the unit while it is moving.

• initCloaked - type: bool - default: false

Is the unit cloaked as soon as it is created?

• minCloakDistance - type: float - default: 0.0

The minimum distance (radius) which the unit must be from any enemy units to remain cloaked.

• decloakSpherical - type: bool - default: true

Does minCloakDistance apply in 3D or only 2D? i.e. can aircraft flying above the unit decloak it?

• decloakOnFire - type: bool - default: true

Does the unit deloak when it fires a weapon?

• cloakTimeout - type: int - default: 128

The minimum time, in frames, between a decloak and subsequent re-cloak.

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.

• canResurrect - type: bool - default: false

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

• canCapture - type: bool - default: false

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

• moveState - type: int - default: -1 for mobile units, 1 for structures

The initial movement state for the unit. Can be -1 - Inherits from factory, 0 - Hold Position, 1 - Manoeuvre or 2 - Roam.

• fireState - type: int - default: -1 for units without noAutoFire, 2 otherwise

The initial firing state for the unit. Can be -1 - Inherits from factory, 0 - Hold Fire, 1 - Return Fire or 2 - Fire At Will.

• noAutoFire - type: bool - default: false

Controls whether or not the unit has a fire state button.

• canDGun - type: bool - default: false

Can the unit be issued DGun commands? A DGun command will fire any weapons with the commandfire tag (See Units-WeaponDefs).

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?

• showNanoSpray - type: bool - default: true

Does the builder emit OTA-style nanospray whilst constructing?

• nanoColor - type: float[3] - default: {0.2, 0.7, 0.2} aka green

The RGB colour of a builders' emitted nano particles if showNanoSpray is true. Also controls the RBG colour of a unit's own nanoframe if showNanoFrame is true.

• 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.

• isAirbase - type: bool - default: false

Is this unit an airbase? Aircraft may land and repair on units which are airbases.

Movement & Placement

• footprintX - type: int - default: 1

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

• footprintZ - type: int - default: 1

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

• yardmap - type: string - default: ""

A string of characters which defines in detail each 'footprint square' of a structure. Each footprint square may be y - Always open, unblocking, c - Open and unblocking only while constructing (for factories, controlled via COB.YARD_OPEN see Animation-LuaCallouts#Other), g - Must be placed over a geoThermal feature (See Units-FeatureDefs), or o - Always closed, blocking. Also used to determine a structure from a mobile unit.

• movementClass - type: string - default: ""

The name of the movement type a mobile, non aircraft, unit should use. See Movedefs.lua. Other tag usage should be consistent with this i.e. canHover = true IFF using a HOVER based movetype.

• canHover - type: bool - default: false

Is the unit a hovercraft? Hovercraft can cross water of any depth without a speed penalty. Hover's must also have HOVER within the name of their movementClass (see Movedefs.lua).

• floater - type: bool - default: true if the unit has the waterline tag, false otherwise

When a mobile unit is crossing water, or a structure is placed on water, does it float on top of the water or crawl / lay on the sea bed?

• 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. Mobile unit's use the maxSlope set in their movementClass (see Movedefs.lua). The value is in degrees and is clamped between 0.0 and 89.0. This value is converted to a "maximum allowed height difference" (call it M), which involves a hard-coded constant. When a building gets placed, the height of each of its footprint squares is compared to a reference height (calculated for the build position). If the difference exceeds M for any square, that build position is rejected.

• 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 Movedefs.lua).

• 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 Movedefs.lua).

• 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 in elmos per frame. 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 in elmos per frame. If the value is -ve, the absolute value is used.

• acceleration - type: float - default: 0.5

The acceleration of the unit, in elmos per frame². If the value is -ve, the absolute value is used.

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

The deceleration of the unit, in elmos per frame². If the value is -ve, the absolute value is used. For units with canFly this is multiplied by 0.1.

• turnRate - type: float - default: 0.0

How fast the unit can turn. degrees per seconds = 0.16 * turnRate

• turnInPlace - type: bool - default: true

Does the unit turn on the spot (like a person or tank) or must it be moving forwards to turn (like a car).

• turnInPlaceSpeedLimit - type: float - default: A complex formula based on turnRate and maxVelocity

For units with turnInPLace = false, this defines the minimum speed it will slow down to (the speed at which the turn is actually performed can be higher depending on the angular difference and turnRate).

Flanking

For a deeper explanation of these tags, see Units:FlankingBonus.

• flankingBonusMode - type: int - default: flankingBonus.defaultMode set in Modrules.lua

The mode of operation of Spring's inbuilt flanking system. 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.

• flankingBonusMax - type: float - default: 1.9

The maximum multiplier to the damage dealt, when a unit is hit from the opposite direction to flankingBonusDir.

• flankingBonusMin - type: float - default: 0.9

The minimum multiplier to the damage dealt, when a unit is hit from the opposite direction to flankingBonusDir.

• flankingBonusDir - type: float[3] - default: {0.0, 0.0, 1.0}

This is the direction vector where the armour is facing; i.e. where the least damage is applied. The default is straight forwards.

• flankingBonusMobilityAdd - type: float - default: 0.01

This defines the ability of flankingBonusDir to move over time. Its value is added to the mobility every SlowUpdate. When the unit is attacked, the build up mobility value is multiplied by a vector facing the attack, which is added to flankingBonusDir.

Aircraft

• canFly - type: bool - default: false

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

• canSubmerge - type: bool - default: false

Can the aircraft land underwater?

• 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?

• hoverAttack - type: bool - default: false

Controls whether the aircraft flys and attacks like a fighter/bomber or a helicopter/gunship.

• airStrafe - type: bool - default: true

For aircraft with hoverAttack = true, controls if the unit strafes side to side while attacking or remains stationary.

• cruiseAlt - type: float - default: 0.0

The altitude in elmos which the unit attempts to fly at while cruising.

• airHoverFactor - type: float - default: -1.0

For aircraft with hoverAttack = true, less then 0 means it can land and >= 0 indicates how much the unit will move during hovering on the spot.

• bankingAllowed - type: bool - default: true

For aircraft with hoverAttack = true, controls whether or not the unit banks when moving turning.

• useSmoothMesh - type: bool - default: true

Does the aircraft follow the real map terrain or the special smoothed out navigation mesh generated by Spring specifically for aircraft?

• maxFuel - type: float - default: 0.0

The maximum flight time in seconds before aircraft must return to an airbase to refuel.

• refuelTime - type: float - default: 5.0

The time in seconds required to refuel the aircraft at an airbase.

• minAirbasePower - type: float - default: 0.0

The minimum workerTime an airbase must have to repair / refuel this aircraft.

Advanced Tags

The following set of tags are not well understood and using non-default values can lead to undesired flight behaviours.

• wingDrag - type: float - default: 0.07

The drag caused by the aircraft's wing. Clamped between 0.0 and 1.0.

• wingAngle - type: float - default: 0.08

The angle between the front and the wing plane.

• frontToSpeed - type: float - default: 0.1

Fudge factor for lining up speed and front of plane.

• speedToFront - type: float - default: 0.07

Fudge factor for lining up speed and front of plane.

• myGravity - type: float - default: 0.4

As Spring aircraft are slower than real aircraft this tag allows to lower gravity to compensate. Multiplies against map gravity.

• crashDrag - type: float - default: 0.005

The drag used when crashing. Clamped between 0.0 and 1.0.

• maxBank - type: float - default: 0.8

The maximum roll (z-axis rotation) the aircraft can achieve.

• maxPitch - type: float - default: 0.45

The maximum pitch (x-axis rotation) the aircraft tries to keep.

• turnRadius - type: float - default: 500.0

Hint to Spring unit AI about the required turning radius.

• verticalSpeed - type: float - default: 3.0

The speed of takeoff and landing, at least for gunships (hoverAttack = true)

• maxAileron - type: float - default: 0.015

The maximum turn speed around the roll (z) axis.

• maxElevator - type: float - default: 0.01

The maximum turn speed around the pitch (x) axis.

• maxRudder - type: float - default: 0.004

The maximum turn speed around the yaw (y) axis.

• maxAcc - type: float - default: 0.065

The maximum acceleration or 'engine power' of the aircraft.

Transports

• transportSize - type: int - default: 0

The size of units that the transport can pick up, in terms of the passengers footprintX.

• minTransportSize - type: int - default: 0

The smallest size of unit that the transport can pick up, in terms of the passengers footprintX.

• transportCapacity - type: int - default: 0

The total number of units that the transport can pick up. If this tag is not present, then any AttachUnit and DropUnit call in the animation script will be ignored (See Animation-LuaCallouts#Other)

• transportMass - type: float - default: 100000.0

The total cumulative mass of passengers the transport can carry.

• minTransportMass - type: float - default: 0.0

The total minimum mass passenger the transport can carry.

• loadingRadius - type: float - default: 220.0

How far away in elmos can the transporter pick up and drop units?

• unloadSpread - type: float - default: 1.0

How spread out the passengers are when unloaded. Is multiplied by the passengers radius.

• isFirePlatform - type: bool - default: false

Can transported units still aim and shoot while loaded by this transport?

• holdSteady - type: bool - default: false

If true - passengers are slaved to orientation of transporter attachment piece, if false - passengers are slaved to orientation of transporter body.

• releaseHeld - type: bool - default: false

Does the transporter unload it's passengers when it dies?

• cantBeTransported - type: bool - default: false for mobile units true for structures

Controls if a unit is transportable at all or not. If false it is overridden by Modrules.lua transportability subtable tags.

• transportByEnemy - type: bool - default: true

Controls if a unit can be transported by an enemy transport. i.e. can it be kidnapped.

• transportUnloadMetod - type: int - default: 0

For air transports. Can be 0 - Land to unload individually, 1 - Flyover drop (i.e. Parachute), or 2 - Land and flood unload all passengers. Can be used on ground transports with mixed results.

• fallSpeed - type: float - default: 0.2

For air transports with transportUnloadMethod = 1. The speed in elmos per second which units will fall at when released from the transport.

• unitFallSpeed - type: float - default: 0.0

Allows you to override fallSpeed for an individual passenger.

Categories

For a deeper explanation of these tags, see Unit_Categories.

• category - type: string - default: ""

The category tag is a string of separate words, each representing a category of units. There are a maximum of 32 categories. The primary purpose of categories is weapon targeting (See #Weapons).

• noChaseCategory - type: string - default: ""

The unit will still target enemies with a matching category, but will not chase after it if it moves out of weapon range.

Collision Volumes

For a deeper explanation of these tags, see Unit Collision Volumes.

Attack Behaviours

• highTrajectory - type: int - default: 0

Can the unit fire it's (ballistic) weapons in a high trajectory arc? Can be 0 - Low trajectory only, 1 - High trajectory only, or 2 - Toggle button.

• kamikaze - type: bool - default: false

Does the unit attack its target by blowing itself up?

• kamikazeDistance - type: float - default: 0.0

How close to the target, in elmos, the unit must get before detonating. Measured in 3D, not 2D.

• kamikazeUseLOS - type: bool - default: false

Does the target unit have to be in LOS when detonating or only within kamikazeDistance.

Other

• decoyFor - type: string - default: ""

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

• selfDestructCountdown - type: int - default: 5

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

• damageModifier - type: float - default: 1.0

The multiplier applied to weapon damage when the units ARMORED status (See Lua_ConstCOB) is turned on

• isTargetingUpgrade - type: bool - default: false

Does the unit upgrade the targeting so that units shoot accurately at enemy units which are in radar but not in LOS.

• isFeature - type: bool - default: false

Does the unit immediately die into it's corpse feature when built? Used mainly for making walls.

• hideDamage - type: bool - default: false

Should the units current health be invisible to enemy players?

• showPlayerName - type: bool - default: false

Should the unit display it's controlling player as its name instead of name. Generally used for commander or hero units.

• showNanoFrame - type: bool - default: true

Does the unit show an OTA-style nanoframe whilst being constructed?

• unitRestricted - type: int - default: MAX_UNITS

How many of this unit type may a player control at once? Defaults to being the maximum amount of units controllable. Is overridden by lobby unit restrictions.

• power - type: float - default: buildCostMetal + (buildCostEnergy / 60.0)

The relative power of the unit. Used in weapon targeting priority and experience gain calculations.