HowTo:Make Weapons

MOD

HowTos

Add Upgrades

---

Adding weapons to the weapon list

Weapon descriptions are stored in the weapon_list.xml in the data directory.

Weapons are classified as

• Beam
• Bolt
• Ball
• Missile

If more than one is given as property1 or property2 this means, that they are both read, do the same and the latter synonymous property overwrites the former(!).

Weapon XML Schema

FIXME ADD DESCRIPTIONS TO SCHEMA

General Properties

An entry starts with the weapon type. Valid values: Beam, Bolt, Ball, Missile.

<Weapon_type Name="name" MountSize="Mount_type_1 Mount_type_2 ..." Role="AI_Role_1 AI_Role_2 ... " AntiRole="AI_Role_1 AI_Role_2 ... ">

• Name [string] - Its name (duh), the same as used in units.csv for mount attributes.
• MountSize - Mount size, to be checked against mount attributes in units.csv. Valid values currently are "light", "medium", "heavy", "capship-light", "capship-heavy", "special", "light-missile", "medium-missile", "heavy-missile", "light-capship-missile", "heavy-capship-missile", "special-missile", "autotracking".
• Role [string] - Space-separated list of AI roles (Combat_Role of an unit, assigned in units.csv and used in data/ai) against which the weapon will be used. Exclusive, but empty list or absent field allows everything. Note that it's applied after - and thus added to - the restrictions of a carrying unit's own Role, and if the weapon launches an unit (missile), it will act upon its own Role only. See also Weapon and AI below. Currently it's used only for Tractor (but not Heavy Tractor): role="CARGO INERT".
• AntiRole [string] - Used only if Role is absent. Works much the same way, but gives AI roles against which the weapon will not be used, everything else is allowed.

Appearance

<Appearance ... />

• file [string/file] Texture file name.
• soundmp3 [string/file] Sound file.
• soundwav [string/file] Sound file.
• OffsetX OffsetY OffsetZ [float] - Offset of the muzzle from the mount's coordinates, i.e. location of the weapon model's muzzle. Affected by config variables graphics/weapon_xyscale and graphics/weapon_zscale.
• r g b a [float] [0.0 - 1.0] - Color components (with transparency) of the texture.
  • E.g.: Tractor and Repulsor use the same texture, but different colors.
• TextureStretch - [float] Stretches textures along the beam.
  • Currently used only in code for beam. So you can use the same texture for different beams with different looks or adjust for speed.

Energy

• <Energy ... />
  • consumption or rate - Energy requirement, in units of 100s of MJ. Depending on the weapon type, per second or per shot.
  • stability - Maximum continuous firing duration. Used only for beams.
  • refire - Rest time, in seconds, between firing.
    • If game difficulty is > 0.98 or weapon name doesn't end on "_Computer". If it is, this rate is scaled, inversely proportional to difficulty value and using physics/refire_difficutly_scaling" variable (default=3.0, with 1 scaling to the given value).
    • Multiplied by the unit's Heat_Sink_Rating - applying to all mounts indiscriminately, which is why it's discarded for now.
  • locktime - Time to lock on the target, in seconds. Could work with any weapon but is actually checked only for missiles, since it doesn't have much sense for most non-guided weapons.

Damage

• <Damage ... />
  • damage or rate - Damage output, in units of 5.4 MJ. Depending on the weapon type, per second or per shot.
  • phasedamage - Damage (per second) that ignores shields, in units of 5.4 MJ. Depending on the weapon type, per second or per shot.
  • longrange - Fraction of damage applied at the maximum range.

Distance

• <Distance ... />
  • speed - Speed at which projectile or beam head travels linearly through space, in meters/second.
    • If "physics/gun_speed_adjusted_game_speed" variable is set to "true" (default false), speeds are moderated (below 1000 raised, otherwise reduced) and adjusted using physics/gun_speed.
  • radialspeed - Speed at which bolt/beam reaches its full radius and full damage, in meters/second. For missiles, determines explosion fall-off profile.
  • radius - Beam/bolt radius, in meters. For missile, explosion cut-off radius, in meters (geometry should be given via unit mesh anyway).
  • length - Has any effect only for bolt.
  • pulsespeed - Controls visual wave effect. Used only for beam.
  • range - Max damaging range, in meters.
    • "physics/gun_speed_adjusted_game_speed and gun_speed (see above) control ranges adjustment as well.
  • detonationrange - The maximum distance from a target at which the missile detonates, in meters. Missile only.
  • volume - ammo volume (for one shot), in meters³.
    • For beams, works only if "physics/reduce_beam_ammo" variable is set to "true" (default false).

By weapon type

Beam

<Beam ... >

• Energy
  • consumption or rate - Energy requirement is per second.
  • stability - Maximum continuous firing duration.
  • refire - Does not depend on whether the weapon was fired for maximum duration or a single frame.
  • locktime - purely decorative.
• <Damage ... />
  • rate - Damage rate is given per second.
  • phasedamage - Damage rate is given per second.
  • longrange
• <Distance ... />
  • speed - Speed at which beam expands linearly through space.
    • Usually rather fast. E.g. all lasers have 300000000 (light speed).
  • radialspeed - Speed at which the beam reaches its full radius and full damage, in meters/second
  • radius - Beam radius.
  • length - N/A
  • pulsespeed - Controls visual wave effect in beam.
    • E.g. for tractor beams it's negative, because the beam texture should move toward the weapon and not from it.
  • range
  • detonationrange - N/A
  • volume - Ammo volume is set per shot: if used, 1 unit of ammo is fully spent when the beam is fired, even if it's interrupted later.
    • Works only if "physics/reduce_beam_ammo" variable is set to "true" (default false). Currently the only beam with ammo is Jackhammer.

Bolt

<Bolt ... >

• <Energy ... />
  • rate - Energy requirement is per shot.
  • stability - N/A
  • refire - Time between shots, in seconds
  • locktime - purely decorative.
• <Damage ... />
  • rate - Damage is given per shot.
  • phasedamage - Damage is given per shot.
  • longrange
• <Distance ... />
  • speed
  • radialspeed
  • radius
  • length
  • pulsespeed - N/A
  • range
  • volume

Ball

Mostly similar to Bolt, but is spherical, so there's one difference.

<ball ... >

• <Distance ... />
  • length - N/A

Missile

<missile ... >

• <Energy ... />
  • rate - Per shot.
  • stability - N/A
  • refire
  • locktime - Time to lock on the target, in seconds.
• <Damage ... />
  • rate - Damage is given per shot.
    • FIXME Uses a complicated formula; at zero distance the damage is 2x this much, at radialspeed it's 1x, then fades out.
  • phasedamage - Damage is given per shot.
  • longrange
• <Distance ... />
  • speed
  • radialspeed - FIXME "radial multiplier", sets the explosion profile: at this distance explosion causes 1x nominal damage and the fall-off function changes.
  • radius - FIXME Explosion radius, in meters. It doesn't affect the fall-off profile, beyond this point damage is simply not calculated.
  • length - N/A
  • pulsespeed - N/A
  • range - It obviously haven't much practical sense for maneuverable ones, so what it really does is: sets self-destruct to Range/Speed and lets AI know at what range to use it.
  • detonationrange - FIXME The maximum distance from a target at which the missile detonates, in meters.
    • Negative values are used for interceptors/drones.
  • volume

Weapon and AI

Missiles must have their own AI files, "unitname"+".xai" (see data/ai/script/). If this file is not found, this "missile" is launched as an interceptor unit instead.

Role as described above may be used to prevent attempts to waste a heavy missile or bomb on targets both fast and unworthy, like missiles or interceptors. Generally it's a good idea to set the weapon corresponding to the missile's role behaviour set in data/ai/VegaPriorities.csv - so that if it won't hunt the unit, AI doesn't launch it at this unit in the first place. If roles are correctly pre-filtered, AI/Firing/MissileProbability may be set higher, since NPC will not waste missiles before they get to proper targets.

Example 1: Beam Weapon

<Beam name="LR_PminusBeamMKIV" mountsize="capship-heavy">
  <Energy rate="1500" stability="8" refire="2" /> 
  <Damage rate="15000" longrange=".8" /> 
  <Distance speed="300000" radialspeed="60" radius="60" length="8" pulsespeed="36" range="150000" /> 
  <Appearance file="weapons/heavylaserbeam.png" soundwav="beam1.wav" r=".6" g=".1" b=".8" a=".6" /> 
</Beam>

Example 2: Spinning Weapon

You can make it spin as well by making it an accessory of the missile/weapon:

• You make it a subunit (turret) at the center, which has the word accessory in its name (e.g call it torpedo_accessory)
• Set the max_yaw, max_pitch, and max_roll to whatever you want it to spin at.
• Make an invisible (or e.g torpedo casing) main body.

Creating a weapon upgrade

prestidigitator documented his steps to create new weapons in a forum post. Here's the part that isn't obsolete yet:

---

Here is what I have done:

1. weapon_list.xml: Copied the entire <Beam name="LaserBeam' ...> node to the end of the file (just before the </WEAPONS> end tag), changed the name from "LaserBeam" to "MyLaserBeam", and modified the values to be what I wanted (I left the "mountsize" attribute as "light").
2. master_part_list.csv: Copied the line starting with "laser_beam" to the end of the file and changed "laser_beam" to "my_laser_beam".
3. units/units.csv: Copied the line starting with "laser_beam__upgrades" to the end of the file, changed "laser_beam__upgrades" to "my_laser_beam__upgrades", changed "./factions/upgrades/laser_beam" to "./factions/upgrades/my_laser_beam", changed the second "laser_beam" to "my_laser_beam", and finally changed the "LaserBeam" to "MyLaserBeam".

[...] There's an ordering problem. I moved all the additions to immediately after those entries for the laser beam, and it worked. So, I guess if you are trying to do this, consider my steps above to be a mini-HowTo, with the caveat that you should be careful about WHERE in the files you add things.

---

After CSV split ([r13666]), weapon effect parameters still are in data/weapon_list.xml, but upgrade stats are in data/units/weapons.csv and trade in data/parts/trade_equipment.csv; add a line with picture in data/units/units_description.csv like ones for existing weapons, and everything should be covered.

To have a custom mount model (visible when enabled by graphics/draw_weapons config variable), add it as mounts/mylaserbeam.bfxm (lower case) - this works exactly the same way as with ships and subunits (including LODs). It's a good idea to check the model's size on the smallest ship able to carry it and check the muzzle of a weapon other than beam by setting the speed very low.

See also

---

MOD

HowTos

Add Upgrades