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.

WeaponTypes

Spring has 15 WeaponTypes which provide game developers with basic behaviours which they can customise to an extent with the WeaponDef tags. Some of these types are more useful, flexible and reliable than others; particularly Cannon, LaserCannon and MissileLauncher. Some tags are specific to certain WeaponTypes and not implemented for others, this two-way table indicates which tags work for which types.

• 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. See the #AircraftBomb section for tags specific to this type.

• 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. See the #BeamLaser section for tags specific to this type.

• 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. See the #Cannon section for tags specific to this type.

• 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. See the #DGun section for tags specific to this type.

• 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. See the #EmgCannon section for tags specific to this type.

• Flame

TODO

• LaserCannon

A particularly versatile line-of-sight weapon. Visually drawn like a Star Wars Blaster-style laser weapon, or a 3D model. See the #LaserCannon section for tags specific to this type.

• LightningCannon

An instant-hit weapon similar to the BeamLaser. Visually drawn like Star Wars 'Force Lightning' or CnC: Red Alert Tesla Coil weapons, the effect is not very customisable. See the #LightningCannon section for tags specific to this type.

• 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. See the #Melee section for tags specific to this type.

• MissileLauncher

Shoots a smoke-emitting projectile. It can use acceleration, etc. The projectile's lifetime depends on range/maxspeed so a slowly accelerating missile will fall short. It can also use trajectoryheight to have the shot arc but that has trouble with aiming at targets higher or lower than the shooter (see bug report, this REALLY could use some fixing). Pretty versatile weapon overall, if the laser rendering code was ported into this we could pretty much axe the LaserCannon completely.

• Rifle

TODO

• Shield

TODO

• StarburstLauncher

TODO

• TorpedoLauncher

TODO

• NoWeapon

TODO

General

float tagToCopyPaste  default: 0.0 

Lorem ipsum dolor sit amet.

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