Spring - User contributions [en]

Gamedev:WeaponDefs

2015-03-14T08:52:18Z

Cleanrock: /* Targeting & Accuracy */

[[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 <strike>non-instant-hit</strike> [https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 hitscan] 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 (+/- ~18 degrees)
|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 = firetolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle then it will not 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. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{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}} only once for each salvo (<code>true</code>) or for every round in a burst (<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 = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{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==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Gamedev:WeaponDefs

2015-03-14T08:39:59Z

Cleanrock: /* Targeting & Accuracy */

[[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 <strike>non-instant-hit</strike> [https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 hitscan] 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 (+/- 9 degrees)
|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 = firetolerance
|type = float
|default = 32768.0 (+/- 90 degrees)
|description = The amount to which the weapon's "real" aim can be off while the weapon will still being able to 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. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{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}} only once for each salvo (<code>true</code>) or for every round in a burst (<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 = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{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==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Lua:Callins

2014-07-12T12:08:47Z

Cleanrock: /* Units */

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = Used to set the default command when a unit is selected.
}}

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|params = serverFrameNum
|return = none
|description = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = AddConsoleLine
|params = msg, priority
|return = none
|description = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|params = zip
|return = none
|description = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|params = ???
|return = ???
|description = ???
}}

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = none
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = none
|description = Called when the key is released.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is released. Please note that in order to have Spring call <code>MouseRelease</code>, you need to have a <code>MousePress</code> call-in in the same addon that returns <code>true</code>.
}}

{{LuaCallin
|name = MouseWheel
|params = up, value
|return = none
|description = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|params = none
|return = none
|description = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

{{LuaCallin
|name = DrawWorldPreUnit
|params =
|return = none
|description = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coords.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

{{LuaCallin
|name = DrawUnit
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|params = unitID, weaponID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|params = projectileID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of weapon (& other) projectiles.
}}

== Synced - Unsynced Shared ==

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|params = winningAllyTeams
|return = none
|description = The parameter is a list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

{{LuaCallin
|name = TeamDied
|params = teamID
|return = none
|description = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

{{LuaCallin
|name = UnitUnitCollision
|params = colliderID, collideeID
|return = none
|description = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|params = colliderID, collideeID
|return = none
|description = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOpts
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|params = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|return = none
|description = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|params = x, y, z, strength, allyTeam, unitID, unitDefID
|return = none
|description = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|params = unitID, unitDefID, action
|return = bool actionAllowed
|description = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams". <code>action</code> is one of following:
* <code>-1</code> Build
* <code>CMD.REPAIR</code> Repair
* <code>CMD.RECLAIM</code> Reclaim
* <code>CMD.RESTORE</code> Restore
* <code>CMD.RESURRECT</code> Resurrect
* <code>CMD.CAPTURE</code> Capture
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = bool used, bool finished
|description = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns <code>used</code> as <code>true</code> the command is dropped, if an addon returns <code>true, true</code> the command is removed because it's done, with <code>true, false</code> it's kept in the queue and <code>CommandFallback</code> gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = bool allow
|description = Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|params = unitDefID, builderID, builderTeam, x, y, z, facing
|return = bool allow
|description = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|params = unitID, unitDefID, oldTeam, newTeam, capture
|return = bool allow
|description = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|params = builderID, builderTeam, unitID, unitDefID, part
|return = bool allow
|description = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|params = featureDefID, teamID, x, y, z
|return = bool allow
|description = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|params = builderID, builderTeam, featureID, featureDefID, part
|return = bool allow
|description = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|params = teamID, res, level
|return = bool allow
|description = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|params = oldTeamID, newTeamID, res, amount
|return = bool allow
|description = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of <code>0</code> - player picked a position, <code>1</code> - player clicked ready, <code>2</code> - game was force-started (player did not click ready) or <code>3</code> the player failed to load. {{new|95.0}} the default 'failed to choose' start-position is now just <code>(0,0,0)</code>, not <code>(0,-500,0)</code>.
}}

{{LuaCallin
|name = AllowDirectUnitControl
|params = unitID, unitDefID, unitTeam, playerID
|return = bool allow
|description = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = bool allow
|description = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag.
}}

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number priority
|description = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value controls the priority of the target (maximum of <code>1.0</code>).
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|params = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = bool allowed
|description = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, ownerTeamID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|params = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = bool stop
|description = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is <code>true</code> the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|params = unitID, unitDefID, unitTeam, data
|return = bool moveCtrlComplete
|description = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than <code>1</code> ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled (<code>false</code>) or return to engine controlled movement (<code>true</code>).
}}

{{LuaCallin
|name = RecvLuaMsg
|params = msg, playerID
|return = none
|description = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, <code>weaponDefID</code> may be one of the following:
* <code>-1</code> - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* <code>-2</code> - ground collision
* <code>-3</code> - object collision
* <code>-4</code> - fire damage
* <code>-5</code> - water damage
* <code>-6</code> - kill damage
* <code>-7</code> - crush damage

{{LuaCallin
|name = UnitPreDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

{{LuaCallin
|name = FeaturePreDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

Lobby Development

2012-04-23T07:10:08Z

Cleanrock: /* Useable lobby clients */

[[Engine_Development|Development]] < {{FULLPAGENAME}}

=Documentation=

==Protocol==
* [http://springrts.com/dl/LobbyProtocol/ HTML] (is updated once a day)
* [https://github.com/spring/LobbyProtocol/blob/master/ProtocolDescription.xml XML] (raw, always latest)

==Download Systems==
* [http://springrts.com/wiki/Dev:LobbyDownloadSystems Lobby Download Systems]

=Lobby client development=

==Useable lobby clients==

===SpringLobby===
cross-platform,
C++,
by BrainDamage &
koshi

SpringLobby is the official lobby client of spring and is bundled with the Spring engine in the installer. It uses the ''wxWidgets'' library. You can browse the sources and submit issues on its [http://springlobby.info/ website].

===Zero-K===
Windows,
C#,
by Licho & quantum

[https://code.google.com/p/zero-k/ Zero-K project page]

===TASClient===
Windows,
Delphi,
by Satirik

You can download the sources from the [http://springrts.com/svn/spring/Lobby/TASClient/ subversion repository] (svn://springrts.com/svn/spring/Lobby/TASClient/) and browse them on the [http://springrts.com/websvn/listing.php?repname=Spring&path=%2FLobby%2FTASClient%2F#_Lobby_TASClient_ websvn]. Latest binary version is always available here:
http://springrts.com/dl/tasclient/TASClientLatest.7z

[http://springrts.com/phpbb/viewtopic.php?f=12&t=18999 How to compile TASClient]

[http://springrts.com/phpbb/viewtopic.php?f=14&t=19014 How to customize TASClient]

===NotaLobby===
cross-platform,
C++,
by danil_kalina, a1983, TruePer

[http://springrts.com/phpbb/viewtopic.php?f=64&t=27289 Forum thread]

===flobby===
Linux,
C++,
by cleanrock

[https://github.com/cleanrock/flobby github page]

==Work in progress or abandoned==

===Alphalobby===
Windows,
C,
unmaintained

Alphalobby is still very much work in progress. If you still wish to use it, source available from the [http://code.google.com/p/alphalobby/source/checkout mercurial repository], binary available on the [http://springfiles.com/spring/lobby-clients/alphalobby springfiles page].

===CheeseLobby===
cross-platform,
Java,
by Cheesecan

[http://springrts.com/phpbb/viewtopic.php?f=64&t=24905 forum thread]

[https://github.com/jahwag/cheeselobby binaries and code]

===QtLobby===
cross-platform,
C++,
unmaintained

[http://code.google.com/p/qtlobby/ project page]

===Weblobby===
online lobby client by CarRepairer

[http://springrts.com/phpbb/viewtopic.php?f=64&t=26414 forum thread]

=Libraries and frameworks=

==Spring-PythonBotFramework==
cross-platform,
Python, by
BrainDamage & koshi

A bot framework written in python. [https://github.com/renemilk/tasbot/wiki GitHub wiki]

==Go SpringLobbyClient==
cross-platform,
Go

A simple client implementation of the lobby protocol in Go.
[https://github.com/Agon/go-slc/ project page]

=Lobby server development=

==SpringLS==
cross-platform,
Java,
hoijui

The longest-running lobby server, created by Betalord. You can fetch the sources through ''git''. Details can be found on the [http://github.com/spring/SpringLS development site].

==UberServer==
cross-platform,
Python,
by aegis

The primary lobby server currently running on springrts.com. All protocol commands in the primary documentation should be fully-functional and compatible between both uberserver and SpringLS. You can get more information and download uberserver at the [https://github.com/lunixbochs/uberserver github page]

[[Category: Lobbies]]