Gamedev:WeaponDefs

2014-10-04T19:06:00Z

Sprunk: update some differences to lua WeaponDefs

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|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:

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
{{DataTypes}}

==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 <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = 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, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = 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 [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = 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 {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = 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 {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = 0 (See description)
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. The defaults are as follows:
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = The radius used in collision calculations. For non-instant-hit weapons which do not use a 3D {{taglink|model}}.}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0
|description = 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 {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = 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.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = 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.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = 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 {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} for every round in a burst (<code>true</code>) or only once for each salvo (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = 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 {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|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 [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = 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]].

There are no tags specific to this '''WeaponType'''.

===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 {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming '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 {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = acceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===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 (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|repulsor|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

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

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|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.

{{tag
|name = subMissile
|type = bool
|default = false
|description = 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 created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = repulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = force
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = maxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = interceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = smart
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exterior
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = radius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = power
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = powerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = powerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = rechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visible
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = badColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = goodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = alpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> 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==
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/weapons 'Balanced Annihilation' WeaponDefs]

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fweapons 'Conflict Terra' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd%2FWeapons 'Evolution RTS' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[https://github.com/spring1944/spring1944/tree/master/weapons 'Spring: 1944' WeaponDefs] (Implements an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance])

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FWeapons 'Spring Tutorial Game' WeaponDefs]

[[Category: Game Dev]]

Spring - User contributions [en]

Talk:Clans/TS

Talk:Clans/KoS

Gamedev:WeaponDefs