This is an old revision of the document!
Overview
Weapons are item types that fire projectiles. The <Weapon> element defines both the way in which projectiles are fired (e.g., the rate of fire, the power consumed, etc.) and the nature of the projectiles themselves (e.g., the speed of the projectile, the damage caused, etc.)
Some weapons fire a single type of projectile; in that case, the definition of the weapon and the projectile are both included in the <Weapon> element. See: Example 1.
Other times, the weapon fires more than one type of projectile. In that case, the definition of the projectiles are in the <Missiles> sub-element. See: Example 2.
Here is a comprehensive thread that describes how weapons are defined:
Weapons Overview (basic++)
Basic Parameters
These are the attributes for a weapon that define how the projectiles are fired.
fireRate= The number of game seconds that elapse between shots. By default, a game second is half a tick, so this is twice the number of ticks between shots.
powerUse= The amount of power consumed each tick while the weapon is firing. Power is expressed in tenths of megawatts, so a value of 10 equals 1 MW.
idlePowerUse= The amount of power consumed each tick while the weapon is not firing. Optional. Defaults to 10% of powerUse. (New in 1.06)
recoil= If non-zero, this accelerates the ship opposite to the direction of fire. The acceleration is proportional to the square of the value (e.g., a value of 2 has a recoil four times stronger than a value of 1).
failureChance= The % chance that the weapon will fail when it fires.
charges= If true, the weapon uses up a charge when it is fired. The weapon will not fire if it has no charges left.
counter= Used to limit how often a weapon can be fired in a certain time period. “temperature” makes the counter represent the weapon's temperature, which should start at 0 and increase with each shot. At 100, the weapon begins to overheat; if fired, an overheating weapon may fire normally, get jammed, become disabled, or damage itself, each with a 25% chance. At 120, the weapon always jams. “capacitor” means that the counter represents the weapon's stored power, which should start at 100 and decrease with each shot. When the capacitor is low, the weapon usually cannot fire as fast.
counterActivate= The change in the counter value every time the weapon is fired. Should be positive for “temperature” counters and negative for “capacitor” counters. For “capacitor” counters, this is also the minimum counter value required to fire the weapon.
counterUpdate= The change in the counter value every time the counter updates. Should be negative for “temperature” counters and positive for “capacitor” counters.
counterUpdateRate= The ticks between each counter update
Number of seconds to deplete the counter once = 100 / ((60 / fireRate) * counterActivate - (30 / counterUpdateRate) * |counterUpdate|)
Number of shots the deplete the counter once = (60 / fireRate) * 100 / ((60 / fireRate) * counterActivate - (30 / counterUpdateRate) * |counterUpdate|)
Number of seconds to recharge the counter once = 100 / ((30 / counterUpdateRate) * |counterUpdate|)
Number of ticks between shots when the counter is depleted = (30 * counterActivate) / ((30 / counterUpdateRate) * |counterUpdate|)
Fire rate when the counter is depleted = counterActivate / 1)
multiTarget= If true, then each projectile can have its own target. Not all projectiles may aim for the selected target, but at least one projectile will as long as it is in range. If the number of projectiles is greater than the number of targets, then one target can have multiple projectiles.
passthrough= If specified, this is the chance that the projectile will continue in its path even after it hits and damages an object. NOTE: For area weapons the default is 80; for all others the default is 0.
sound= The sound effect UNID to be played when the projectile is fired.
Be careful when using type=“whatever”. Some weapons, like beam, do not accept tags like <effect>.
type=beam
Certain weapontypes only take certain effects:
“beam” is known to take these configurations:
“starblaster”→ Used on the katana.
can specify colors using hexadecimal.
beamType= "starblaster"
primaryColor= "0x00, 0x80, 0xff"
secondaryColor= "0x80, 0xc0, 0xff"
“lightning”→ Used on the Ares lightning turret.
Can specify colors using hexadecimal as well as intensity
beamType= "lightning"
primaryColor= "0xf0, 0xff, 0xa0"
secondaryColor= "0xa9, 0xff, 0x00"
intensity= "5"
“blaster”→ used on the bolide
beamType= "blaster"
“heavyblaser”→ used on the TeV9
beamType= "heavyblaster"
primaryColor= "0x33, 0xff, 0x33"
secondaryColor= "0x00, 0x99, 0x00"
intensity= "5"
“laser”→ used on the mining laser
beamType= "laser"
primaryColor= "0xf1, 0x5f, 0x2a"
secondaryColor= "0xff, 0x00, 0x00"
sound= "&snLaserCannon;"
“greenparticle”→ cool looking one. Used on the lancer cannon
beamType= "greenparticle"
“blueparticle”→ not used in Vanilla, is the same as greenparticle, only blue.
beamType= "blueparticle"
NOTE:
intensity is a parameter used by SOME beam type weapon projectiles.
Valid beams include heavy blaster & lightning.
Note that intensity of less than 4 will not work on beams due to a strange bug that causes them to disappear at 0, 90 180 and 270 degrees.
Intensity will basically increase the size of the projectile.
type=missile
The following attributes are exclusive to missiles
accelerationFactor= The percentage at which the projectile's speed increases by every 10 ticks (1/3 seconds).
maxMissileSpeed= The maximum speed that a projectile can reach, due to accelerationFactor= or otherwise.
stealth= The stealth value of the projectile.
hitPoints= The amount of damage needed to destroy this projectile in flight. 2) If applicable, projectiles automatically detonate upon destruction.
interaction= The solidity of the projectile; the chance that this projectile may interact with other projectiles, or vice versa. Defaults to 0 for beams and 100 for everything else (this ensures that beams never collide with each other unless they are specified to).3)
If two projectiles collide and one of them has 100 interaction, then they will interact. If the two both have 0 interaction, then they will just pass through each other. Otherwise, the highest interaction of the two is the percent chance that they will interact.
maneuverability= The time in ticks that this projectile takes in between maneuvering.4) Defaults to 1 if maneuverRate is defined.5) Automatically makes this projectile tracking.
maneuverRate= The maximum angle that this projectile can turn when maneuvering.6) If maneuverability is defined, this defaults to 18.7)
type=area
Used to make shockwaves
expansionSpeed= The speed (in % of light-speed) at which the damaging travel outward. Defaults to 20.8)
areaDamageDensity= The number of damaging points along the edge of the shockwave. Defaults to 32.9)
type=particles
Releases a cloud of particles
minDamage= The minimum damage done by each projectile 10)
type=radius
minRadius== All objects inside this radius take full damage.
maxRadius= Damage inside this radius is decreased by inverse square law. Damage = Damage * (MaxRadius - Distance) / (MaxRadius - MinRadius)11)
<Effect>
The <Effect> sub-element defines how to paint the projectile. If the element is omitted, the projectile will be invisible. See the page on Effects for a full description.
<HitEffect>
This optional sub-element defines how to paint the explosion that results when the projectile hits a target. If the element is omitted, a default hit effect is used. See the page on Effects for a full description.
<FireEffect>
This optional sub-element defines how to paint the muzzle-flash effect when a weapon fires. If the element is omitted, no fire effect is painted. See the page on Effects for a full description.
Vapor Trail
vaporTrailLength= integer, probably pixels, default is 64
vaporTrailWidth= integer, probably pixels
vaporTrailWidthInc= integer, has something to do with how trapezoidal the trail is probably, default is 25
vaporTrailColor= presumably the same color formats as are used elsewhere
quick notes from looking at one place in the source –Weaver
Fragments
All projectiles with non-periodic fragmentation automatically detonate within range of a target. Fragments can have the same attributes as weapons.
count= The number of projectiles released per detonation.
failsafe= Minimum ticks until the projectile can detonate 12)
fragmentInterval= The number of ticks between each detonation. Sets fragmentation to be periodic and disables proximity detonation.
fragmentTarget= If “true”, then projectiles from this fragment will be aimed towards a target upon detonation.
targetRequired= If “true”, then detonation cannot occur unless there is a target.
Standard Stats
Level | Damage | Power | Cost | Ammo Cost | Over | Under |
1 | 4 | 10 | 350 | 0.6 | 0 | 0 |
2 | 5 | 20 | 800 | 1.2 | 0 | -20 |
3 | 7 | 50 | 1850 | 3.0 | 0 | -50 |
4 | 9 | 100 | 4000 | 6.0 | 0 | -100 |
5 | 12 | 200 | 8500 | 12.0 | 5 | -170 |
6 | 16 | 300 | 18500 | 18.0 | 5 | -250 |
7 | 21 | 500 | 39000 | 30.0 | 5 | -300 |
8 | 27 | 1000 | 78500 | 60.0 | 10 | -300 |
9 | 35 | 2000 | 158000 | 120.0 | 10 | -300 |
10 | 46 | 3000 | 320000 | 180.0 | 10 | -300 |
11 | 60 | 4000 | 640000 | 240.0 | 25 | -300 |
12 | 78 | 6000 | 1300000 | 360.0 | 25 | -300 |
13 | 101 | 8000 | 2700000 | 480.0 | 25 | -300 |
14 | 131 | 10000 | 5300000 | 600.0 | 100 | -300 |
15 | 170 | 12000 | 10600000 | 720.0 | 100 | -300 |
16 | 221 | 15000 | 21300000 | 900.0 | 100 | -300 |
17 | 287 | 20000 | 42600000 | 1200.0 | 200 | -300 |
18 | 373 | 25000 | 85200000 | 1500.0 | 200 | -300 |
19 | 485 | 30000 | 170000000 | 1800.0 | 200 | -300 |
20 | 631 | 35000 | 341000000 | 2100.0 | 200 | -300 |
21 | 820 | 40000 | 682000000 | 2400.0 | 200 | -300 |
22 | 1066 | 50000 | 1400000000 | 3000.0 | 200 | -300 |
23 | 1386 | 60000 | 2700000000 | 3600.0 | 200 | -300 |
24 | 1802 | 70000 | 5500000000 | 4200.0 | 200 | -300 |
25 | 2343 | 80000 | 10900000000 | 4800.0 | 200 | -300 |
The standard fire delay is 8 ticks (or 3.75 shots per second)
The standard range is 60 ls
The standard ammo mass is 10.0 kg
The Over and Under values are Balance Points; they are used when determining the overpoweredness or underpoweredness of a weapon. Rather than being chosen based on the level of the weapon, they are chosen based on the difference between
Damage | Level |
laser | 1 |
kinetic | 1 |
particle | 4 |
ion | 4 |
thermo | 7 |
positron | 7 |
plasma | 10 |
antimatter | 10 |
nano | 13 |
graviton | 16 |
singularity | 16 |
darkAcid | 19 |
darkSteel | 19 |
darkLightning | 22 |
darkFire | 22 |
This table shows the standard weapon level that each damage type is associated with.
Fields
Properties
ammoTypes= If the weapon uses ammo, this is a list of UNIDs for every compatible ammo item type.
averageDamage= This is the average unadjusted damage dealt every time the weapon is fired. This assumes that all projectiles hit the same target.
balance= The percentage to which the weapon is overpowered relative to its level
balanceDamage=
balanceCost=
balanceExcludeCost=
damage=
damagePerProjectile=
damageWMD180=
damaged=
effectiveRange=
fireArc=
fireDelay=
fireRate=
linkedFireOptions=
maxDamage=
minDamage=
omnidirectional=
secondary=
stdCost=
tracking=
Balance
Notes | Balance Points |
Compare this weapon's damage per 180 ticks to the standard damage per 180 ticks for its level. | 100 * log₂(Damage180 / StdDamage180) |
If the damage type's standard level is greater than the weapon's level, then add balance points from the Over column based on the difference | Over[damageLevel - weaponLevel] |
If the damage type's standard level is less than the weapon's level, then add balance points from the Under column based on the difference | Under[damageLevel - weaponLevel] |
If the weapon uses ammo or charges, it loses 100 balance points | -100 |
Find the percentage difference between our ammo unit cost and the standard firing cost at our level. The standard firing cost is found by multiplying the standard unit cost with the ratio between our fire rate and the standard fire rate. Subtract 0.2 Balance Points for every percentage point that our cost is above the standard. If the cost is below standard, add instead. | StdAmmoFiringCost = StdAmmoCost[Level] * FireRate / StdFireRate[Level]
-0.2 | 100 * (AmmoCost - StdAmmoFiringCost) / StdAmmoFiringCost |
Find the percentage difference between our ammo unit mass and the standard firing mass at our level. The standard firing mass is found by multiplying the standard unit mass with the ratio between our fire rate and the standard fire rate. Subtract 0.25 Balance Points for every percentage point that our mass is above the standard. If the mass is below standard, add instead | StdAmmoMass = 10
StdAmmoFiringMass = StdAmmoMass * FireRate / StdFireRate
-0.25 * 100 * (AmmoMass - StdAmmoFiringMass) / StdAmmoFiringMass |
If the weapon can rotate, add up to 100 Balance Points | 100 * √(FireArc / 360) |
If the weapon has tracking or any of its fragments have tracking, then add Balance Points | 100 |
Compare the weapon range to the standard range. For each light-second distance that the weapon's range is greater than the standard range, add 0.35 Balance Points (up to 21 max) | 0.35 * (RangeLS - StdRangeLS[Level]) |
Compare the weapon range to the standard range. For each light-second distance that the weapon's range is less than the standard range, subtract 1.0 Balance Points | 1.0 * (RangeLS - StdRangeLS[Level]) |
Subtract up to 25 Balance Points based on missile speed | -25 * (1 - √(MissileSpeed / 100)) |
Add up to 5 Balance Points for not having interaction | 5 * (100 - Interaction) / 100 |
Add up to 10 Balance Points as projectile hp approaches standard damage | 10 * HitPoints / StdDamage[Level] |
If this weapon is a primary, Find the difference between its power use and the adjusted standard (10% of the standard if we use ammo, 100% otherwise). Divide this difference by the unadjusted standard and multiply by 100. | StdPowerAdjusted = 0.1 * StdPower[Level]
StdPowerAdjusted = Power[Level]
100 * (Power - StdPowerAdjusted) / StdPower[Level] |
If this weapon is a primary, compare its value to the standard value at its level. For each percentage point difference from standard, subtract 0.5 Balance Points if our value is greater. Otherwise, add. | -0.5 * 100 * (Value - StdValue[Level]) / StdValue[Level] |
If the weapon is slotless, add 20 Balance Points | 20 |
If the weapon takes one slot, then no Balance Points | 0 |
If the weapon takes more than one slot, subtract 40 Balance Points for each additional slot | -40 * (Slots - 1) |
If the weapon has linked-fire, add 25 Balanced Points | 25 |
Subtract 2.5 points for each point of recoil | 2.5 * Recoil |
Subtract 40 Balance Points if external | -40 |
Add 30 Balance Points if this weapon has radiation | 30 |
Add 3 Balance Points for each percent chance of device disruption (up to 50%) | 3 * DeviceDisruptChance |
Add 3 Balance Points for each percent chance of device damage (up to 50%) | 3 * DeviceDamageChance |
Add 100 Balance Points if this weapon has disintegration | 100 |
Add 12 Balance Points for each point of Shatter | 12 * Shatter |
Add 0.25 Balance Points for each percent chance of shield penetration | 0.25 * ShieldPenetrateChance |
Shield Buster | 10 * (3 + Shield - Level) |
Armor Penetrate | 20 * (3 + Armor - Level) |
Add 0.1 for every percentage point chance of mining | MiningChance[Mining] = 2 * Mining² + 2
0.1 * MiningChance[Mining] |
Add 0.5 Balance Points for each percentage point of adjustment for non-standard WMD damage | 0.5 * WMDAdj[WMD] |
Source
Variants
Events
Weapon items support the following events (which can be added in the <Events> element for an <ItemType>).
<OnDamageArmor>
This event is called when a projectile from this weapon hits the armor of a ship. If the event returns an integer, the value is interpreted as the amount of damage to do to armor (before adjustments for damage type). If the event returns Nil, the original damage amount is unchanged.
gSource is the object that was hit by the projectile.
aArmorSeg is the armor segment on the object that was hit.
aAttacker is the object that fired the projectile.
aCause is the projectile object.
aDamageHP is the adjusted damage (in hit points) that reached the armor.
aDamageType is the type of damage.
aHitDir is the absolute direction that the projectile came from.
aHitPos is the vector position where the shot hit.
aOrderGiver is the object that ordered the attacker.
aWeaponType is the UNID of the weapon (for missile weapons, this is the UNID of the missile).
<OnDamageOverlay>
This event is called when a projectile from this weapon hits an overlay on a ship. If the event returns an integer, the value is interpreted as the amount of damage to pass to shields (before adjustments for damage type). If the event returns Nil, the original damage amount is unchanged.
gSource is the object that was hit by the projectile.
aAttacker is the object that fired the projectile.
aCause is the projectile object.
aDamageHP is the adjusted damage (in hit points) that reached the armor.
aDamageType is the type of damage.
aArmorSeg is the armor segment that would be hit if it penetrates overlay and shields.
aHitDir is the absolute direction that the projectile came from.
aHitPos is the vector position where the shot hit.
aOrderGiver is the object that ordered the attacker.
aOverlayID is the ID of the overlay that was hit.
aWeaponType is the UNID of the weapon (for missile weapons, this is the UNID of the missile).
<OnDamageShields>
This event is called when a projectile from this weapon hits the shields on a ship.
If the event returns Nil, the shields process the damage normally.
If the event returns an integer, then the shields are by-passed and the value is interpreted as the amount of damage to do to armor.
If the event returns the string “reflect”, then the projectile is reflected and neither shields nor armor take any damage.
If the event returns a list, then the list must have three elements. The first element is either the string “reflect” or Nil. The second element is the number of HP to subtract from the current shield level. The third element is the number of HP to do to armor.
gSource is the object that was hit by the projectile.
aArmorDamageHP is the number of hit points of damage that will be passed to armor after the shields absorb some.
aAttacker is the object that fired the projectile.
aCause is the projectile object.
aDamageHP is the amount of damage (in hit points) that reached the armor. It has not been adjusted for damage type.
aDamageType is the type of damage.
aDeviceItem is the shield item.
aArmorSeg is the armor segment that would be hit if it penetrates shields.
aHitDir is the absolute direction that the projectile came from.
aHitPos is the vector position where the shot hit.
aOrderGiver is the object that ordered the attacker.
aOriginalArmorDamageHP if the shot will be reflected, this is the number of hit points that would have been dealt to armor if the shot had not been reflected.
aOriginalShieldDamageHP if the shot will be reflected, this is the number of hit points that would have been dealt to shields if the shot had not been reflected.
aShieldDamageHP is the number of hit points of damage that the hit will do to shields.
aShieldHP is the current number of hit points on the shields.
aShieldReflect is the string “reflect” is the shield will reflect this projectile. Otherwise, its value is Nil.
aWeaponType is the UNID of the weapon (for missile weapons, this is the UNID of the missile).
<OnFireWeapon>
This event is called on weapon items when the weapon fires. For weapons with multi-projectile configurations or for repeating weapons, the event is called once per projectile. The event may use sysCreateWeaponFire to create projectiles. If the event returns Nil, then the normal projectile is created.
gSource is the object that fired the weapon.
gItem is the weapon itself (for missile weapons, this is the launcher).
aFireAngle is the angle that the weapon fired at.
aFirePos is the position where the weapon fire originates.
aTargetObj is the target object (if any).
aWeaponBonus is the %bonus confered by any enhancements.
aWeaponType is the UNID of the weapon (for missile weapons, this is the UNID of the missile).
<OnFragment>
This event is called on a weapon when a shot from that weapon fragments due to either proximity or reaching the end of its lifetime.
aNearestObj The object that triggered the fragmentation (or Nil)
aTargetObj The object that the attacker was targeting (or Nil if no target)
aHitPos The detonation position
aHitDir The direction that the shot was traveling
aWeaponType The UNID of the weapon that fired
aWeaponFragment An identifier for the fragmentation (in case a fragment also fragments)
aCause The shot object
aAttacker The attacker
aOrderGiver The object that ordered the attack (in case aAttacker is an auton)