Difference between revisions of "HowTo:Make Weapons"

From VsWiki
Jump to: navigation, search
(tested it)
 
(18 intermediate revisions by 4 users not shown)
Line 8: Line 8:
 
{{attention}}
 
{{attention}}
  
Weapon descriptons are stored in the '''[http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vegastrike/data4.x/weapon_list.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup weapon_list.xml]''' in the data directory.   
+
Weapon descriptions are stored in the '''[http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vegastrike/data4.x/weapon_list.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup weapon_list.xml]''' in the data directory.   
  
Weapons are classified as {{fixme}} ''DIFFERENCES BETWEEN CATEGORIES''
+
Weapons are classified as
 
* Beam
 
* Beam
 
* Bolt
 
* Bolt
Line 16: Line 16:
 
* Missile
 
* Missile
  
 
+
If more than one is given as <code>property1</code> ''or'' <code>property2</code> this means, that they are both read, do the same ''and the latter synonymous property overwrites the former''(!).
 
==Weapon XML Schema==
 
==Weapon XML Schema==
 
{{fixme}} ''ADD DESCRIPTIONS TO SCHEMA''
 
{{fixme}} ''ADD DESCRIPTIONS TO SCHEMA''
 +
 +
===General Properties===
 +
An entry starts with the weapon type. Valid values: <code>Beam</code>, <code>Bolt</code>, <code>Ball</code>, <code>Missile</code>.
 +
 +
<<code>''Weapon_type''</code> '''Name'''="<code>name</code>" '''MountSize'''="<code>Mount_type_1 Mount_type_2 ...</code>" '''Role'''="<code>AI_Role_1 AI_Role_2 ... </code>" '''AntiRole'''="<code>AI_Role_1 AI_Role_2 ... </code>">
 +
* <code>'''Name'''</code> [string] - Its name (duh), the same as used in <code>units.csv</code> for mount attributes.
 +
* <code>'''MountSize'''</code> - Mount size, to be checked against mount attributes in <code>units.csv</code>. 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".
 +
* <code>'''Role'''</code> [string] - Space-separated list of AI roles (Combat_Role of an unit, assigned in <code>units.csv</code> 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 [[HowTo:Make_Weapons#Weapon_and_AI|Weapon and AI]] below. Currently it's used only for Tractor (but not Heavy Tractor): <code>role="CARGO INERT"</code>.
 +
* <code>'''AntiRole'''</code> [string] - Used only if <code>'''Role'''</code> is absent. Works much the same way, but gives AI roles against which the weapon will ''not'' be used, everything else is allowed.
 +
 +
===Appearance===
 +
 +
<code><'''Appearance''' ... /></code>
 +
* <code>file</code> [string/file] Texture file name.
 +
* <code>soundmp3</code> [string/file] Sound file.
 +
* <code>soundwav</code> [string/file] Sound file.
 +
* <code>OffsetX</code> <code>OffsetY</code> <code>OffsetZ</code> [float] - Offset of the muzzle from the mount's coordinates, i.e. location of the weapon model's muzzle. Affected by config variables <code>[[Manual:Config:Advanced:Variables#.22graphics.22_section|graphics]]/'''weapon_xyscale'''</code> and <code>[[Manual:Config:Advanced:Variables#.22graphics.22_section|graphics]]/'''weapon_zscale'''</code>.
 +
* <code>r</code> <code>g</code> <code>b</code> <code>a</code> [float] [0.0 - 1.0] - Color components (with transparency) of the texture.
 +
** E.g.: Tractor and Repulsor use the same texture, but different colors.
 +
* <code>TextureStretch</code> - [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===
 +
 +
* <code><'''Energy''' ... /></code>
 +
** <code>consumption</code> ''or'' <code>rate</code> - Energy requirement, in units of 100s of MJ. Depending on the weapon type, per second or per shot.
 +
** <code>stability</code> - Maximum continuous firing duration. Used only for '''beam'''s.
 +
** <code>refire</code> - 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 <code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''refire_difficutly_scaling'''</code>" variable (default=<code>3.0</code>, 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.
 +
** <code>locktime</code> - 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===
 +
 +
* <code><'''Damage''' ... /></code>
 +
** <code>damage</code> ''or'' <code>rate</code> - Damage output, in units of 5.4 MJ. Depending on the weapon type, per second or per shot.
 +
** <code>phasedamage</code> - Damage (per second) that ignores shields, in units of 5.4 MJ. Depending on the weapon type, per second or per shot.
 +
** <code>longrange</code> - Fraction of damage applied at the maximum range.
 +
 +
===Distance===
 +
 +
* <code><'''Distance''' ... /></code>
 +
** <code>speed</code> - Speed at which projectile or beam head travels linearly through space, in meters/second.
 +
*** If "<code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''gun_speed_adjusted_game_speed'''</code>" variable is set to "<code>true</code>" (default <code>false</code>), speeds are moderated (below 1000 raised, otherwise reduced) and adjusted using <code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''gun_speed'''</code>.
 +
** <code>radialspeed</code> - Speed at which bolt/beam reaches its full radius and full damage, in meters/second. For missiles, determines explosion fall-off profile.
 +
** <code>radius</code> - Beam/bolt radius, in meters. For '''missile''', explosion cut-off radius, in meters (geometry should be given via unit mesh anyway).
 +
** <code>length</code> - Has any effect only for '''bolt'''.
 +
** <code>pulsespeed</code> - Controls visual wave effect. Used only for '''beam'''.
 +
** <code>range</code> - Max damaging range, in meters.
 +
*** "<code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''gun_speed_adjusted_game_speed'''</code> and <code>'''gun_speed'''</code> (see above) control ranges adjustment as well.
 +
** <code>detonationrange</code> - The maximum distance from a target at which the missile detonates, in meters. '''Missile''' only.
 +
** <code>volume</code> - ammo volume (for one shot), in meters<sup>3</sup>.
 +
*** For beams, works only if "<code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''reduce_beam_ammo'''</code>" variable is set to "<code>true</code>" (default <code>false</code>).
 +
 +
==By weapon type==
 +
 
===Beam===
 
===Beam===
<code><'''beam''' ... ></code>
+
 
** <code>name</code>
+
<code><'''Beam''' ... ></code>
** <code>mountsize</code>
+
* <code>'''Energy'''</code>
* <code><'''Energy''' ... /></code>
+
** <code>consumption</code> ''or'' <code>rate</code> - Energy requirement is per second.
** <code>rate</code> - Energy requirement (per second), in units of 100s of MJ
+
** <code>stability</code> - Maximum continuous firing duration.
** <code>stability</code> - Maximum continuous firing duration
+
** <code>refire</code> - Does not depend on whether the weapon was fired for maximum duration or a single frame.
** <code>refire</code> - Rest time, in seconds, between firing
+
** <code>locktime</code> - purely decorative.
** <code>locktime</code> - N/A for beams
 
 
* <code><'''Damage''' ... /></code>
 
* <code><'''Damage''' ... /></code>
** <code>rate</code> - Damage output (per second), in units of 5.4 MJ
+
** <code>rate</code> - Damage rate is given per second.
** <code>phasedamage</code> - Damage (per second) that ignores shields, in units of 5.4 MJ
+
** <code>phasedamage</code> - Damage rate is given per second.
** <code>longrange</code> - Fraction of damage applied at max range
+
** <code>longrange</code>
 
* <code><'''Distance''' ... /></code>
 
* <code><'''Distance''' ... /></code>
** <code>speed</code> - Speed at which beam travels linearly through space, in meters/second (usually rather fast). E.g.: all lasers have 300000000 (light speed).
+
** <code>speed</code> - Speed at which beam expands linearly through space.
** <code>radialspeed</code> - Speed at which beam reaches full radius, and full damage, in meters/second
+
*** Usually rather fast. E.g. all lasers have 300000000 (light speed).
** <code>radius</code> - Beam radius, in meters
+
** <code>radialspeed</code> - Speed at which the beam reaches its full <code>radius</code> and full damage, in meters/second
** <code>length</code> - N/A for beams
+
** <code>radius</code> - Beam radius.
** <code>pulsespeed</code> - Controls visual wave effect in beam. E.g.: tractor beams have negative value, so the beam texture moves not from the weapon, but toward it.
+
** <code>length</code> - N/A
** <code>range</code> - Max damaging range, in meters
+
** <code>pulsespeed</code> - Controls visual wave effect in beam.
** <code>detonationrange</code> - N/A for beams
+
*** E.g. for tractor beams it's negative, because the beam texture should move toward the weapon and not from it.
** <code>volume</code> - ammo volume, in meters<sup>3</sup> ({{fixme}} per second? per shot? currently ammo isn't expended at all). Jackhammer currently is the only beam that uses ammo.
+
** <code>range</code>
* <code><'''Appearance''' ... /></code>
+
** <code>detonationrange</code> - N/A
** <code>file</code>
+
** <code>volume</code> - 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.
** <code>soundwav</code>
+
*** Works only if "<code>[[Manual:Config:Advanced:Variables#.22Physics.22_section|physics]]/'''reduce_beam_ammo'''</code>" variable is set to "<code>true</code>" (default <code>false</code>). Currently the only beam with ammo is Jackhammer.
** <code>r</code> <code>g</code> <code>b</code> <code>a</code> - color components (with transparency) of the beam. E.g.: Tractor and Repulsor use the same texture, but different colors.
 
  
 
===Bolt===
 
===Bolt===
Mostly similar to Beam, with the following difference:
+
 
<code><'''bolt''' ... ></code>
+
<code><'''Bolt''' ... ></code>
 
* <code><'''Energy''' ... /></code>
 
* <code><'''Energy''' ... /></code>
** <code>rate</code> - Energy requirement (per shot), in units of 100s of MJ
+
** <code>rate</code> - Energy requirement is per shot.
** <code>stability</code> - N/A for anything except beams
+
** <code>stability</code> - N/A
 
** <code>refire</code> - Time between shots, in seconds
 
** <code>refire</code> - Time between shots, in seconds
 +
** <code>locktime</code> - purely decorative.
 
* <code><'''Damage''' ... /></code>
 
* <code><'''Damage''' ... /></code>
** <code>rate</code> - Damage output (per shot), in units of 5.4 MJ
+
** <code>rate</code> - Damage is given per shot.
** <code>phasedamage</code> - Damage (per shot) that ignores shields, in units of 5.4 MJ
+
** <code>phasedamage</code> - Damage is given per shot.
 +
** <code>longrange</code>
 
* <code><'''Distance''' ... /></code>
 
* <code><'''Distance''' ... /></code>
** <code>pulsespeed</code> - N/A for anything but beams
+
** <code>speed</code>
** <code>volume</code> - ammo volume (per shot), in meters<sup>3</sup>
+
** <code>radialspeed</code>
 +
** <code>radius</code>
 +
** <code>length</code>
 +
** <code>pulsespeed</code> - N/A
 +
** <code>range</code>
 +
** <code>volume</code>
  
 
===Ball===
 
===Ball===
Mostly similar to Bolt, but is spherical.
+
Mostly similar to Bolt, but is spherical, so there's one difference.
 +
 
 
<code><'''ball''' ... ></code>
 
<code><'''ball''' ... ></code>
 +
* <code><'''Distance''' ... /></code>
 +
** <code>length</code> - N/A
  
 
===Missile===
 
===Missile===
Mostly similar to Bolt, with the following difference:
+
 
 
<code><'''missile''' ... ></code>
 
<code><'''missile''' ... ></code>
 
* <code><'''Energy''' ... /></code>
 
* <code><'''Energy''' ... /></code>
** <code>locktime</code> - Time to lock on the target, in seconds. Should work with any weapon but is used only with missiles, since it doesn't have much sense for most non-guided weapons.
+
** <code>rate</code> - Per shot.
 +
** <code>stability</code> - N/A
 +
** <code>refire</code>
 +
** <code>locktime</code> - Time to lock on the target, in seconds.  
 
* <code><'''Damage''' ... /></code>
 
* <code><'''Damage''' ... /></code>
** <code>rate</code> - Damage output, in units of 5.4 MJ. {{fixme}} Uses a complicated formula; it looks like ot zero distance the damage is twice this much, but don't count on this.
+
** <code>rate</code> - Damage is given per shot.
** <code>phasedamage</code> - Damage that ignores shields, in units of 5.4 MJ.
+
*** {{fixme}} Uses a complicated formula; at zero distance the damage is 2x this much, at <code>radialspeed</code> it's 1x, then fades out.
 +
** <code>phasedamage</code> - Damage is given per shot.
 +
** <code>longrange</code>
 
* <code><'''Distance''' ... /></code>
 
* <code><'''Distance''' ... /></code>
** <code>radius</code> - {{fixme}} Seems to be the radius in which the damage is applied, in meters.
+
** <code>speed</code>
** <code>detonationrange</code> -  {{fixme}} The maximum distance from a target at which the missile detonates, in meters. Negative values are used for drones. Should work for any weapon except beams, but only missiles have radius damage.
+
** <code>radialspeed</code> - {{fixme}} "radial multiplier", sets the explosion profile: at this distance explosion causes 1x nominal damage and the fall-off function changes.
 +
** <code>radius</code> - {{fixme}} Explosion radius, in meters. It doesn't affect the fall-off profile, beyond this point damage is simply not calculated.
 +
** <code>length</code> - N/A
 +
** <code>pulsespeed</code> - N/A
 +
** <code>range</code> - 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.
 +
** <code>detonationrange</code> -  {{fixme}} The maximum distance from a target at which the missile detonates, in meters.
 +
*** Negative values are used for interceptors/drones.
 +
** <code>volume</code>
  
==Weapon AI's==
+
==Weapon and AI==
  
 +
Missiles ''must'' have their own AI files, "unitname"+".xai" (see <code>data/ai/script/</code>). If this file is not found, this "missile" is launched as an interceptor unit instead.
 +
 +
<code>'''Role'''</code> 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 <code>data/ai/VegaPriorities.csv</code> - 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, <code>[[Manual:Config:Advanced:Variables#.22AI.22_section|AI]]/Firing/MissileProbability</code> may be set higher, since NPC will not waste missiles before they get to proper targets.
  
 
==Example 1: Beam Weapon==
 
==Example 1: Beam Weapon==
 
<pre>
 
<pre>
<Beam name="LR_PminusBeamMKIV" mountsize="capship-massive">
+
<Beam name="LR_PminusBeamMKIV" mountsize="capship-heavy">
 
   <Energy rate="1500" stability="8" refire="2" />  
 
   <Energy rate="1500" stability="8" refire="2" />  
 
   <Damage rate="15000" longrange=".8" />  
 
   <Damage rate="15000" longrange=".8" />  
Line 94: Line 173:
 
</pre>
 
</pre>
  
You can make it spin as well by making it an accessory of the missle/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 <code>accessory</code> in its name (e.g call it torpedo_accessory)  
 
* You make it a subunit (turret) at the center, which has the word <code>accessory</code> in its name (e.g call it torpedo_accessory)  
 
* Set the <code>max_yaw</code>, <code>max_pitch</code>, and <code>max_roll</code> to whatever you want it to spin at.
 
* Set the <code>max_yaw</code>, <code>max_pitch</code>, and <code>max_roll</code> to whatever you want it to spin at.
Line 100: Line 179:
  
 
=Creating a weapon upgrade=
 
=Creating a weapon upgrade=
[[prestidigitator]] documented his steps to create new weapons in a [http://vegastrike.sourceforge.net/forums/viewtopic.php?t=8732 forum post].  Here it is:
+
[[prestidigitator]] documented his steps to create new weapons in a [http://forums.vega-strike.org/viewtopic.php?t=8732 forum post].  Here's the part that isn't obsolete yet:
 
+
----
You will need to create an upgrade file for this weapon that appears in [[master_parts_list.csv]] as well as [[units.csv]].
 
 
 
 
Here is what I have done:
 
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").
 
# '''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".
 
# '''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".
 
# '''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".
# '''units/factions/upgrades/''': Copied the "laser_beam/laser_beam" file to "my_laser_beam/my_laser_beam" and changed the "weapon" attribute of the <mount> node from "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.
 
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 ([https://sourceforge.net/p/vegastrike/code/13666/ [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.
  
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.
+
To have a custom mount model (visible when enabled by <code>[[Manual:Config:Advanced:Variables#.22graphics.22_section|graphics]]/'''draw_weapons'''</code> config variable), add it as mounts/mylaserbeam.bfxm (lower case) - this works exactly the same way as with ships and subunits (including [[HowTo:Add_LODs|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=
 
=See also=
 
 
  
  

Latest revision as of 04:03, 5 February 2014

arrow_left.png MOD arrow_up.png HowTos Add Upgrades arrow_right.png

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


arrow_left.png MOD arrow_up.png HowTos Add Upgrades arrow_right.png