Location

FeatureDef files are .lua files stored in the Features/ directory of a Spring Game.

Purpose

FeatureDef files have one purpose; to define the properties of features. They are the main description file for what attributes your features should have and how units interact with them.

Source

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

• rts/Sim/Features/FeatureHandler.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 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 FeatureDef table the internal featureName desired for the unit.

General

string description Default: ""  

This is the tooltip description of the feature seen by the player.

float damage Default: 0.0  

How much damage this feature can take before being destroyed. Analogous to maxDamage = for units.

string featureDead Default: ""  

The featureName of the feature to spawn when this feature is destroyed. Used to make chains of features which 'disintegrate' as they are further damaged. Analogous to corpse = for units.

bool indestructible Default: false  

Can the feature be destroyed or not? If true the feature will not even take damage.

bool flammable Default: false (true for engine trees)  

Can the feature be set on fire? The size of the flame particle is determined by the model radius. The duration of the fire in frames is a random number in the range [200, 230].

bool noSelect Default: false  

If true the cursor won't change to `reclaim` when hovering the feature.

float mass Default: 0.4 * metal + 0.1 * damage  

The mass of the feature, used in unit/feature crushing calculations (See Movedefs.lua). Minimum value is 1.0.

float crushResistance Default: mass New in version 85.0 

How resistant is the feature to being crushed? Any MoveClass with a crushStrength = greater than this will crush the feature.

Visual

string object Default: ""  

The filename of the 3D model file for this unit, assumes Objects3D/ directory. Analagous to objectName = for units.

int smokeTime Default: 300  

How many frames a corpse feature should emit smoke for after unit death.

int drawType Default: 0  

What kind of drawing type is the feature. Can be 0 - A loaded model, -1 - Nothing rendered for this feature at all (used for geovents), values >= 1 are used for the engine default trees. Generally speaking you should ignore this tag.

Reclaim & Resources

bool reclaimable Default: true if not indestructible = , false otherwise  

Can this feature be reclaimed by a construction unit?

bool autoReclaimable Default: reclaimable  

Should this feature be reclaimed by a construction unit executing a patrol or area-reclaim command?

float reclaimTime Default: (metal + energy) * 6.0  

The time taken to reclaim this feature. Related to unit reclaimSpeed = such that Time taken to reclaim = feature reclaimTime / unit reclaimSpeed.

float metal Default: 0.0  

How much metal resource this feature gives the player when reclaimed.

float energy Default: 0.0  

How much energy resource this feature gives the player when reclaimed.

int resurrectable Default: -1  

Can this feature be resurrected back into a living unit? Can be the following values -1 - Only resurrectable if it is the 1st level corpse = of the UnitDef, 0 - Not resurrectable, 1 - Always ressurrectable.

bool geoThermal Default: false New in version 83.0 

Does this feature act as a geothermal vent?

Placement

int footprintX Default: 1  

How wide the feature is in footprint units, left to right. 1 footprint unit = 16 elmos. Cannot be below 1.

int footprintZ Default: 1  

How wide the feature is in footprint units, top to bottom. 1 footprint unit = 16 elmos. Cannot be below 1.

bool blocking Default: true  

Does this feature block the movement of units or can they pass right through it? Features that are non-blocking are also ignored by weapon aiming.

bool upright Default: false  

Does the feature tilt with the slope of the terrain or remain upright?

bool floating Default: false New in version 90.0 

Does this feature float on the top of water or is it placed on the seabed?

Decals

bool useBuildingGroundDecal Default: false  

For structures, do they display a ground decal on the terrain under their model?

string buildingGroundDecalType Default: ""  

The filename of the image to be used as ground decal. Assumed to be in Unittextures/.

int buildingGroundDecalSizeX Default: 4  

How wide the decal is left to right, in footprint units.

int buildingGroundDecalSizeY Default: 4  

How wide the decal is top to bottom, in footprint units.

float buildingGroundDecalDecaySpeed Default: 0.1  

A measure of how quickly the decal should fade out if the structure dies. Essentially this value is multiplied by the time since death and subtracted from the original alpha until the decal is fully transparent.

Collision Volumes

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

string collisionVolumeType Default: ""  

What shape should the feature's collision volume be? Can be box, ellipsoid or a cylinder aligned to an axis; cylX, cylY, cylZ.

float[3] collisionVolumeScales Default: {0.0, 0.0, 0.0}  

The length of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.

float[3] collisionVolumeOffsets Default: {0.0, 0.0, 0.0}  

The offset from the unit centre to the hit volume centre in each axis.

bool useFootPrintCollisionVolume Default: false New in version 92.0 

Replaces any defined collision volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).

int collisionVolumeTest Default: 0 Removed in 90.0 (Now always continuous) 

The type of test used to detect collisions. Can be 0 (discrete) or 1 (continuous). Use the latter for catching high speed projectiles which may otherwise 'skip through' small collision volumes, but beware of the increased performance cost.

Sub Tables

customParams

The customParams subtable of a FeatureDef allows the game designer to give their features 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

'Evolution RTS' FeatureDefs

Many games include unit corpse features into the UnitDef (See Units-UnitDefs#Examples)