Table of Contents

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.

Launchers

A weapon with more than one <Missile> sub-element is automatically considered a launcher. Launchers take up a different slot and are fired with a different trigger. Moreover, the player may select which missile to fire with the launcher. [In contrast, non-launchers can only fire a single type of projectile.]

Fire Direction

By default a weapon fires forward at 0 degrees. You may change the direction of fire with the following attributes:

NOTE: A weapon's fire direction interacts with the fire direction specified in the device slot (the <Devices> section of the <ShipClass>). In effect there are three classes of fire direction:

Since both the weapon and the device slot can specify a fire direction, there are nine possible results: 

                                      DEVICE SLOT
                    omni                swivel              fixed
WEAPON -------------------------------------------------------------------------
omni   |            omni                 omni                omni
       |
       |
swivel |            omni              device slot          swivel in
       |                                swivel          fixed direction
       |
fixed  |            omni              device slot      fixed in weapon+device
       |                                swivel             direction
Device Slot
Fire Direction omnidirectional swivel fixed
Weapon omnidirectional omnidirectional omnidirectional omnidirectional
swivel omnidirectional device slot swivel Swivel in fixed direction
fixed omnidirectional device slot swivel Fixed in weapon+slot direction

For example, a swivel device slot always overrides any swiveling in the weapon; but a fixed device slot combines with the fire direction of the weapon.

Linked Fire Controls

By default a weapon only fires when it is the selected weapon and when the player presses the appropriate fire key ([Ctrl] for primaries, [Shift] for launchers).

In general, forward-facing weapons should use the always value while others should use the whenInFireArc value.

Configurations

A weapon can fire multiple projectiles at the same time. There are two ways to specify this.

<Configuration>

A better way to specify how projectiles are fired is to use the <Configuration> sub-element.

For example: 

   <Configuration aimTolerance="5" alternating="true">
      <Shot posAngle="90" posRadius="12" angle="3d5-9"/>
      <Shot posAngle="270" posRadius="12" angle="3d5-9"/>
   </Configuration>

You can place aimTolerance=“how much angle you want the weapon to deviate from a straight line” within <Configuration>. In addition, alternating=true can be placed within <Configuration> to make the weapon fire each shot sequentially. The advantage of using alternating=true in <Configuration> as opposed to specifying configuration=“alternating” under <Weapon> is that the former allows a weapon to fire more than two shots in sequence; the sequence is determined by the order in which each <Shot> is placed inside <Configuration>. In the above example, <Shot posAngle=“90” posRadius=“12” angle=“3d5-9”/> will always be fired first, followed by <Shot posAngle=“270” posRadius=“12” angle=“3d5-9”/>. 

<Weapon
            type=            "missile"
            
            damage=            "kinetic:0"
            repeating=          "150000"
            fireRate=         "30"
            hitPoints=         "25"
            interaction=      "5"
            hitEffect=         "&efShieldHit1;"
            missileSpeed=      "17"
            accelerationFactor=   "75"
            lifetime=         "10d5-7"
            powerUse=         "100"
            deviceSlots=      "0"
            noFriendlyFire=      "true"
            >            
         <Configuration aimTolerance="5">
            <Shot posAngle="180" posRadius="20" angle="0-180"/>   
            <Shot posAngle="180" posRadius="20" angle="360-181"/>
            <Shot posAngle="180" posRadius="20" angle="0-180"/>   
            <Shot posAngle="180" posRadius="20" angle="360-181"/>
            <Shot posAngle="180" posRadius="20" angle="0-180"/>   
            <Shot posAngle="180" posRadius="20" angle="360-181"/>
         </Configuration>
         <Effect>
            <Image imageID="&rsParticles;" imageX="0" imageY="0" imageWidth="16" imageHeight="16" imageFrameCount="4" imageTicksPerFrame="1" randomStartFrame="true"/>
         </Effect>
      </Weapon>
<shot>

means one shot. In this example, 6 shots are fired at the same time each time the weapon is fired. 

posAngle="180"

posAngle is the angle you want it to fire from. 0 is facing upwards (as in the nose of the Sapphire at the 1st facing.) 

posRadius="20"

means how far you want the shot to appear from the angle [in pixels] , which means that the shot shows up 20 pixels from center, towards the nose of the craft. 

angle="0-180"

means how much you want the shot to deviate (as in it can fire from angle x to y) from the initial firing. Since some of it is 0-180, and others are 360-181, that means all of the shots cover the full 360 degrees. This is different from posAngle and posRadius because posAngle and posRadius determine where the shot comes out, angle determines where the shot goes. Angles 0 and 360 is the same from what I've seen, and 90 is to the left of the playership. If you want a smaller angle, use something like 355-10 to have a narrow cone in front of your ship.

Additional Parameters

maxHPBonus If specified, this is the maximum HP bonus enhancement for the device. For example, a value of 100 means that the weapon cannot be enhanced beyond 100% bonus damage. The default is 150. [API Version 17]

Defining Projectiles

The following attributes may be used in the <Weapon> element to define a single projectile type or they may be used in a <Missile> sub-element.

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

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.

type=area

Used to make shockwaves

type=particles

Releases a cloud of particles

type=radius

<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

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.

Standard Stats

Level Damage (per 180 ticks) 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
Damage Level
laser 1
kinetic 1
particle 4
blast 4
ion 7
thermo 7
positron 10
plasma 10
antimatter 13
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

damagePerProjectile

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>).

<OnCreateShot>

<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.

<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.

<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.

<OnDamageAbandoned>

<OnDestroyShot>

<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.

<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.

1)
CSystem.cpp, 453, Metric MAX_AUTO_TARGET_DISTANCE
2)
CMissile.cpp, 575-648
3)
CSpaceObject.cpp, 4874-4890, InteractsWith
4)
TSEWeaponFireDesc.cpp, 455, IsTrackingTime
5)
CWeaponFireDesc.cpp, 1987
6)
TSEWeaponFireDesc.h, 521, int m_iManeuverRate
7)
CWeaponFireDesc.cpp, 1985
8)
TSEWeaponFireDesc.cpp, 528, DiceRange m_ExpansionSpeed;
9)
TSEWeaponFireDesc.cpp, 529, DiceRange m_AreaDamageDensity;
10)
TSEWeaponFireDesc.h, 525, DiceRange m_MinDamage
11)
CRadiusDamage.cpp, 113, DamageAll
12)
TSEWeaponFireDesc.h, 537, int m_iProximityFailsafe;
13)
CWeaponClass.cpp, 1898, CalcDamage