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:rts/Sim/Units/UnitDef.cpp
The engine source which reads the <a _fcknotitle="true" href="#sounds">#sounds</a> subtable can be found here:rts/Sim/Units/UnitDefHandler.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 betrueorfalse. -
string- Text, or more precisely a string of alphanumeric characters. -
float[3]- A vector, with threefloatcomponents, 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
Resources
Sensors
Cloaking
For units with <a href="Units-UnitDefs#Commands">canCloak</a> set to true:
Template:TagfckLR
Commands
Builder Commands
Builder
Movement & Placement
{{tag
|name = yardmap |type = string |default = "" |description = Used to determine a structure from a mobile unit. A string of characters which defines in detail each 'footprint square' of the structure. Each footprint square may be:
-
y- 'Yard' - Always open, unblocking, -
c- 'Construction' - Open and unblocking only while constructing (for factories, controlled viaCOB.YARD_OPENsee <a _fcknotitle="true" href="Animation-LuaCallouts#Other">Animation-LuaCallouts#Other</a>), -
i- 'Inversed Construction' - Closed and blocking only while constructing (for factories, controlled viaCOB.YARD_OPENsee <a _fcknotitle="true" href="Animation-LuaCallouts#Other">Animation-LuaCallouts#Other</a>) (New in version 89.0), -
g- 'Geothermal' - Flags that the unit must be placed over ageoThermalfeature, does not actually count as a square (See <a _fcknotitle="true" href="Units-FeatureDefs">Units-FeatureDefs</a>), o- 'Obstacle' - Always closed, blocking, all other chars are treated the same way.
-
- Tip: 'Draw' out the yardmap over multiple lines. Prior to 89.0 newlines should be replaced with spaces as newlines are treated as
o.
Flanking
For a deeper explanation of these tags, see <a _fcknotitle="true" href="Units:FlankingBonus">Units:FlankingBonus</a>.
Aircraft
Advanced Air Tags
The following set of tags are not well understood and using non-default values can lead to undesired flight behaviours. Template:TagfckLR
Flares
The following set of tags are rarely used and are hardcoded to only work vs. missile weapons. The texture is hardcoded to be flareprojectiletexture defined in <a _fcknotitle="true" href="Resources.lua">Resources.lua</a>.
Template:TagfckLR
Transports
Categories
For a deeper explanation of these tags, see <a _fcknotitle="true" href="Unit Categories">Unit Categories</a>. Template:TagfckLR
Decals
Collision Volumes
For a deeper explanation of these tags, see <a href="Unit collision volumes"> Unit Collision Volumes</a>. Template:TagfckLR
Attack Behaviours
Other
Sub Tables
weapons
The weapons subtable of a UnitDef tells Spring which weapons the unit has. It is a simple array (number indexed table) of weaponNames (not the human readable name!).
The following additional tags are associated with this subtable:
buildOptions
The buildOptions subtable of a UnitDef tells Spring which other units the unit can build (in the case of a builder) or produce (in the case of a factory).
It is a simple array (number indexed table) of unitNames (not the human readable name!).
There are no additional tags specific to this subtable.
SFXTypes
The SFXTypes subtable of a UnitDef tells Spring which <a _fcknotitle="true" href="CEG">CEG</a> effects are associated with the unit. It consists of two further subtables, with no additional tags specific to them.
explosionGenerators
The explosionGenerators subtable of SFXTypes tells Spring which <a _fcknotitle="true" href="CEG">CEG</a>s the unit's script can call, via the EmitSFX() callout (See <a _fcknotitle="true" href="Animation-LuaCallouts#Effects">Animation-LuaCallouts#Effects</a>). It is a simple array (number indexed table) of CEG names, prefaced by the string "custom:".
pieceExplosionGenerators
New in version 83.0
The pieceExplosionGenerators subtable of SFXTypes tells Spring which <a _fcknotitle="true" href="CEG">CEG</a>s the unit's script can pick at random to attach to a flying unit piece, created from the Explode() callout (See <a _fcknotitle="true" href="Animation-LuaCallouts#Effects">Animation-LuaCallouts#Effects</a>). It is a simple array (number indexed table) of CEG names, with no prefix.
Forum thread (with examples): pieceExplosionGenerators
sounds
The sounds subtable of a UnitDef tells Spring which sound files to play when the unit triggers various events.
Files are assumed to be in the Sounds/ directory; accepted formats are .wav and .ogg, the former being assumed if no extension is given.
Sounds can be defined in one of three ways:
- Each event can be used as though it were a
stringtag referring to the filename. - Each event can be the name of a subtable, which is a simple array containing the filenames. One sound is picked at random from the list each time the event occurs.
- Each event can be the name of a subtable, which is a simple array containing further tables, which contain the following tags:
Spring checks any referenced sound filename to see if a SoundItem has been created, which allows greater control over how it is played (See <a _fcknotitle="true" href="Sounds.lua">Sounds.lua</a>).
sounds Example
For clarification, here is an example of all three methods:
sounds = {
-- Method 1
ok = 'oksound', -- .wav appended
-- Method 2
arrived = {
'arrived1.wav',
'arrived2.wav',
},
-- Method 3
select = {
{ file = 'selsound1.ogg', volume = 2.0 },
{ file = 'selsound2.ogg', volume = 2.5 },
},
}sounds Events
The events called by the engine are as follows:
-
ok
- Unit is issued a command.
-
select
- Unit is selected by the player.
-
arrived
- Unit has arrived at its destination. Mobile ground units only.
-
build
- Unit begins building. Called for both factories and mobile construction units.
-
activate
- Unit is activated, i.e. Is turned on. Also called when a mobile ground unit starts moving.
-
deactivate
- Unit deactivates, i.e. Is turned off.
-
cant
- Unit cannot carry out this order. Loaded but not currently called by the engine.
-
underattack
- Unit gets attacked. Loaded but not currently called by the engine.
customParams
The customParams subtable of a UnitDef allows the game designer to give their units custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.
There are no additional tags specific to this subtable
Examples
<a href="http://imolarpg.dyndns.org/trac/balatest/browser/trunk/units">'Balanced Annihilation' UnitDefs</a>
<a href="http://trac.caspring.org/browser/trunk/mods/ca/units">'Complete Annihilation' UnitDefs</a>
<a href="http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Funits">'Conflict Terra' UnitDefs</a>
<a href="https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd%2FUnits">'Evolution RTS' UnitDefs</a>
<a href="http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FUnits">'Spring Tutorial Game' UnitDefs</a>
<a href="http://code.google.com/p/zero-k/source/browse/trunk#trunk%2Fmods%2Fzk%2Funits">'ZeroK' UnitDefs</a>
Unit development
Game development
