Gamedev:WeaponDefs

Location

WeaponDef files are .lua files stored in the Weapons/ directory of a Spring Game. Alternatively they can be integrated into UnitDefs.

Purpose

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

Source

The engine source code which loads the tags from these files is viewable here:rts/Sim/Weapons/WeaponDefHandler.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 WeaponDef table the internal weaponName desired for the weapon.

Universal

The following tags work for all or almost all WeaponTypes.

General

string weaponType  default: "Cannon" 

Spring has 14 WeaponTypes which provide game developers with basic behaviours which they can customise to an extent with the WeaponDef tags. Some tags are specific to certain WeaponTypes and not implemented for others, this two-way table indicates which tags work for which types. The possible values are:

• AircraftBomb
• BeamLaser
• Cannon
• Dgun
• EmgCannon
• Flame
• LaserCannon
• LightningCanon
• Melee
• MissileLauncher
• Rifle
• Shield
• StarburstLauncher
• TorpedoLauncher

string name  default: "Weapon" 

The descriptive name of the weapon as listed in FPS mode.

bool turret  default: false 

Does the unit aim within an arc (up-to and including full 360° turret traverse) or always aim along the owner's heading?

bool noSelfDamage  default: false 

Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.

bool impactOnly  default: false 

Does the weapon only deal damage through direct hits and not 'splash' damage through areaOfEffect?

bool noExplode  default: false 

Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the collision volume of an object, underground or under water, massively multiplying their damage.

bool burnblow  default: false 

Does the weapon explode when it reaches its maximum range or continue on its path? The name is an OTAism.

float range  default: 10.0 

The maximum range in elmos that the weapon can fire at.

float weaponVelocity  default: 0.0 

The velocity in elmos per second of the weapon projectile.

float reloadTime  default: 1.0 

The time in seconds between shots fired.

float metalPerShot  default: 0.0 

Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a stockpile weapon will cost to build.

float energyPerShot  default: 0.0 

Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a stockpile weapon will cost to build.

float myGravity  default: 0.0 

Overrides the map gravity for ballistic weapons. The default of 0.0 disables the tag in favour of map gravity.

float fireStarter  default: 0.0 

The percentage chance (0.0 to 100.0) of the weapon setting fire to static map features on impact.

Collision & Avoidance

bool avoidFriendly  default: true 

Should the weapon avoid firing if a friendly unit is in the line of fire?

bool avoidFeature  default: true 

Should the weapon avoid firing if a static map feature is in the line of fire?

bool avoidNeutral  default: false 

Should the weapon avoid firing if a neutral unit is in the line of fire?

bool collideEnemy  default: true 

Does the weapon projectile collide with enemy units or pass through?

bool collideFriendly  default: true 

Does the weapon projectile collide with friendly units or pass through?

bool collideFeature  default: true 

Does the weapon projectile collide with static map features or pass through?

bool collideNeutral  default: true 

Does the weapon projectile collide with neutral units or pass through?

bool collideGround  default: true 

Does the weapon projectile collide with terrain or pass through?

Targeting & Accuracy

float tolerance  default: 3000.0 

The amount to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For turret = false or fixedlauncher = true weapons this determines in what arc the unit will fire.

bool canAttackGround  default: true 

Determines if the weapon can be force-fired on ground positions or only fire on targeted units.

bool waterWeapon  default: false 

Determines if the weapon can pass through water and target underwater units.

bool fireSubmersed  default: waterWeapon 

Determines if the weapon can fire whilst underwater.

bool tracks  default: false 

Can the weapon projectile track a moving target? Currently only works with #MissileLauncher, #StarburstLauncher and #TorpedoLauncher.

float targetBorder  default: 0.0 (1.0 for #Melee) 

Controls whether the weapon aims for the centre or the edge of its target's collision volume. Clamped between -1.0 - target the far border, and 1.0 - target the near border.

float cylinderTargeting  default: 0.0 (1.0 for #Melee) 

Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of cylinderTargeting multiplied by the range. Clamped between 0.0 and 128.0.

float accuracy  default: 0.0 

How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.

float movingAccuracy  default: accuracy 

A weapon's accuracy whilst the owning unit is moving.

float sprayAngle  default: 0.0 

How wide the the angle of a burst from a burst weapon can be. Very similar to accuracy, except that sprayAngle affects each projectile in a burst, whilst the former does not.

float targetMoveError  default: 0.0 

The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.

float leadLimit  default: -1.0 

Limits the maximum distance a unit will lead a target. The default of -1 allows an infinite distance.

float leadBonus  default: 0.0 

Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the leadLimit.

float predictBoost  default: 0.0 (0.5 for burnblow weapons) 

Controls how well the weapon predicts unit speeds. Works in a similar way to targetMoveError except that it is 1-dimensional. predictBoost spreads the shots in a line based on the direction of the target whereas targetMoveError spreads the shots all around based on the movement.

Bouncing

bool waterBounce  default: false 

Does the weapon bounce on water impacts?

bool groundBounce  default: false 

Does the weapon bounce on ground impacts?

float bounceSlip  default: 1.0 

The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.

float bounceRebound  default: 1.0 

The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.

int numBounce  default: -1 

The number of times the weapon will bounce on impact before exploding. The default value of -1 allows infinite bounces (at least until velocity reaches 0).

Area Of Effect, Impulse & Cratering

float areaOfEffect  default: 8.0 

The diameter in elmos in which the weapons explosion will cause damage.

float craterAreaOfEffect  default: areaOfEffect * 0.5 

The radius in elmos in which the weapons explosion will cause terrain cratering.

float edgeEffectiveness  default: 0.0 

Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's areaOfEffect. Falls off from the epicentre according to the formula damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))], a graph of the function for various values is available here.

float impulseFactor  default: 1.0 

A multiplier to the impulse given to units within the explosion areaOfEffect, which is otherwise equal to the damage dealt after edfeEffectiveness is taken into account. For #Melee weapons this is instead multiplied by the owning unit's mass (See Units-UnitDefs#General).

float impulseBoost  default: 0.0 

A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of impulseFactor

float craterMult  default: impulseFactor 

A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.

float craterBoost  default: 0.0 

A constant amount, added to the weapon's cratering depth before the application of craterMult.

Bursts

int burst  default: 1 

How many shots to fire per burst.

float burstRate  default: 0.1 

The time in seconds between shots in a burst. Note that reloadTime starts to count down from the first round fired, not the last so if reloadTime < burst * burstRate the weapon will fire continuously.

int projectiles  default: 1 

How many projectiles released per shot (shotgun style). e.g. a weapon with burst = 5, burstRate = 0.5 and projectiles = 2 will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for reloadTime. Best used in conjunction with sprayAngle or changing the firing piece using ShotX as otherwise they'll all be clumped in one shot.

Visuals

string cegTag  default: "" 

The name, without prefixes, of a CEG to be emitted by the projectile each frame.

float intensity  default: 0.9 

Alpha transparency for non-3D model projectiles. Lower values are more opaque, but 0.0 will cause the projectile to disappear entirely.

AircraftBomb

Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. By default the type automatically calculates its burst and burstRate tags from its reloadTime and uses 5 as its reloadTime instead. This is an OTAism and can be overridden with the manualBombSettings tag. Visually drawn as a billboarded sprite as used by the Cannon, but more commonly used with a 3D model.

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

AircraftBomb Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

BeamLaser

An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be script emitted if it has a beamTime longer than one frame. Visually drawn as a Star Trek Phaser-style laser weapon. The largeBeamLaser tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

float minIntensity  default: 0.0 

The minimum percentage the weapon's damage can fall-off to over its range. Setting to 1.0 will disable fall off entirely. Unrelated to the visual-only intensity tag.

float beamTime  default: 1.0 

How long in seconds to fire the laser before waiting for reloadTime to start. Damage is distributed over the duration of the beamTime, and the weapon will aim to hit the target when the beam is in the middle of its beamTime (i.e. using prediction).

bool beamBurst  default: false 

Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A BeamLaser can do its full damage with every shot if beamBurst is enabled. Disables beamTime in favour of the burst tags.

bool sweepFire  default: false 

Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Somewhat unreliable.

BeamLaser Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

Cannon

The default WeaponType. Fires a ballistic projectile, for the best result (without under/overshooting) the weaponVelocity should be set so as to give an elevation of 45° when firing at the maximum range. Substituting the angle into the trajectory equation and rearranging, we get:

weaponVelocity = √(range * g)

where g is the map gravity, usually around 120 for most Spring maps (You can use the myGravity tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

int highTrajectory  default: 2 

Can this weapon be fired in a high trajectory (>45° angle). Can be 0 - low trajectory only, 1 - high trajectory only or 2 - enables a high/low toggle button on the unit.

Cannon Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

DGun

Fires a line-of-sight or ballistic projectile (selected via the gravityAffected tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are OTAisms.

bool gravityAffected  default: false 

Does the fireball projectile lose height due to map gravity?

EmgCannon

A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the Cannon, however not as customisable, or a 3D model. The name is another OTAism.

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

EmgCannon Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

Flame

A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the colorMap tag (see CColorMap).

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

Flame Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

LaserCannon

A particularly versatile line-of-sight weapon. Visually drawn like a Star Wars Blaster-style laser weapon, or a 3D model.

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

LaserCannon Visuals

float duration  default: 0.05 

Multiplied against weaponVelocity to determine the visual length of the beam projectile.

float fallOffRate  default: 0.5 

Rate at which the beam fades out after it goes past its maximum range. 0.0 is never fade out, 1.0 is finish fading out exactly at maximum range.

LightningCannon

An instant-hit weapon similar to the BeamLaser, but which does all its damage at once. Visually drawn like Star Wars 'Force Lightning' or CnC: Red Alert Tesla Coil weapons, the effect is not very customisable.

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

LightningCannon Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

Melee

A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters 'melee' weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this WeaponType.

MissileLauncher

A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use trajectoryHeight to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional smokeTrail.

bool fixedLauncher  default: false 

Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also works for #StarburstLauncher and #TorpedoLauncher. Weapons may not correctly obey avoidance settings when using this tag.

float startVelocity  default: 0.0 

The initial velocity of the weapon projectile. Also for #StarburstLauncher and #TorpedoLauncher.

float acceleration  default: 0.0 

The initial acceleration of the weapon projectile. Also for #StarburstLauncher and #TorpedoLauncher. Note that if it is 0.0 the weapon can never increase from its startVelocity and will not reach its maximum weaponVelocity.

MissileLauncher Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

Rifle

An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this WeaponType.

Shield

As the name suggests, not a weapon but a defensive shield. Can absorb or reflect (repulsor = true) projectiles. Individual weapons can be set to be intercepted or not by the shield using a bit mask (see Shield_Interception_Tag_Use). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible (visible = false).

bool isShield  default: false 

Is the weapon a shield? Currently required for correct functioning of shields in addition to setting weaponType = "Shield".

See the #shield sub-table section for other tags specific to this type.

StarburstLauncher

Fires a projectile that rises vertically for weaponTimer seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. This is the only weapon that can be targetable and act as an interceptor. Visually represented by a 3D model, with an optional smokeTrail.

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

StarburstLauncher Visuals

float tagToCopyPaste  default: 1.0 

Lorem ipsum dolor sit amet.

TorpedoLauncher

Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with waterWeapon = true so they can fire underwater and target underwater units. An aircraft carrying a TorpedoLauncher is a special case, the weapon turns into an AircraftBomb projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

bool subMissile  default: false 

Can the torpedo leave the water and target units and positions on land?

NoWeapon

Not actually a WeaponType, but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is set by the name being "NOWEAPON" rather than by the weaponType tag.

Sub Tables

customParams

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

'Balanced Annihilation' WeaponDefs

'Conflict Terra' WeaponDefs (Most are integrated into their UnitDefs)

'Evolution RTS' WeaponDefs (Most are integrated into their UnitDefs)

'Spring: 1944' WeaponDefs (Implements an OOP paradigm with inheritance)

'Spring Tutorial Game' WeaponDefs