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 inunits.csv
for mount attributes. -
MountSize
- Mount size, to be checked against mount attributes inunits.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] - Exclusive space-separated list of AI roles (Combat_Role of an unit, aa set inunits.csv
and used in data/ai) against which the weapon will be used. Currently used only for Tractor (but not Heavy Tractor):role="CARGO INERT"
. Empty (or absent) list allows everything. -
AntiRole
[string] - Matters only ifRole
is absent. The same, but gives AI roles against which the weapon will not be used.
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 variablesgraphics/weapon_xyscale
andgraphics/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
orrate
- 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).
- 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
-
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
orrate
- 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. -
radialspeed
- Speed at which bolt/beam reaches its full radius and full damage, in meters/second. -
radius
- Beam radius, in meters -
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
andgun_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 meters3.- For beams, works only if "
physics/reduce_beam_ammo
" variable is set to "true
" (defaultfalse
).
- For beams, works only if "
-
By weapon type
Beam
<Beam ... >
-
Energy
-
consumption
orrate
- Energy requirement is per second. -
stability
- Maximum continuous firing duration. -
refire
-
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 fullradius
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 should be negative, so that the beam texture moved 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
" (defaultfalse
). Currently the only beam with ammo is Jackhammer.
- Works only if "
-
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.
- FIXME Uses a complicated formula; at zero distance the damage is 2x this much, at
-
phasedamage
- Damage is given per shot.- FIXME Currently non-lethal ("negative") phasedamage for missiles is ignored.
-
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 set 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 drones.
-
volume
-
Weapon AI's
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
- then if it won't hunt the unit, AI won't launch it at this unit in the first place. If roles are pre-filtered correctly, AI/Firing/MissileProbability
may be set higher as NPC will not be inclined to waste missiles early on.
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
, andmax_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:
- 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").
- 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".
- 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 |