Gamedev:FeatureDefs

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

• description - type: string - default: ""

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

• damage - type: float - default: 0.0

How much damage this feature can take before being destroyed. Analogous to maxDamage for units (See Units-UnitDefs#General).

• featureDead - type: string - 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 (See Units-UnitDefs#General).

• indestructible - type: bool - default: false

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

• flammable - type: bool - default: false

Can the feature be set on fire? Engine trees default to true. 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].

• noSelect - type: bool - default: false

If true the feature cannot be selected or be the target of a unit order.

• mass - type: float - 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.

Visual

• object - type: string - default: ""

The filename of the 3D model file for this unit, assumes Objects3D/ directory. Analagous to objectName for units (See Units-UnitDefs#General)

• smokeTime - type: int - default: 300

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

• drawType - type: int - 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

• reclaimable - type: bool - default: true if not indestructible, false otherwise

Can this feature be reclaimed by a construction unit?

• autoReclaimable - type: bool - default: reclaimable

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

• reclaimTime - type: float - 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

• metal - type: float - default: 0.0

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

• energy - type: float - default: 0.0

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

• resurrectable - type: int - 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.

• geoThermal - type: bool - default: false New in 0.83.x

Does this feature act as a geothermal vent?

Placement

• footprintX - type: int - default: 1

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

• footprintZ - type: int - default: 1

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

• blocking - type: bool - default: true

Does this feature block the movement of units or can they pass right through it?

• upright - type: bool - default: false

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

• nodrawundergray - type: bool - default: false

Does this feature float on the top of water or is it placed on the seabed? Features which are not blocking cannot float. The strange name of this tag is a vestige of OTA.

Collision Volumes

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

• collisionVolumeType - type: string - default: ""

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

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

The length of the collision volume in each of the three axes.

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

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

• collisionVolumeTest - type: int - default: 0

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)