Outfit.xml

From Naevwiki
Jump to: navigation, search

Note: THIS FILE NO LONGER EXISTS, AND HAS BEEN SUBDIVIDED INTO UNIQUE XML FILES IN naev/dat/outfits/*/*.xml

Every outfit available to the player in Naev is indexed in an XML file called outfit.xml, which can be found within the naev/dat/ directory. This page documents the tags used to describe Naev outfits in XML.

For examples of outfit XML used by Naev, look at the source of naev/dat/outfit.xml.

The function of outfits in general are to serve as items which can be purchased and equipped to enhance or modify a vessel. They are generally limited by several factors including mass, cost, CPU, and slot availability. Therefore, outfits may affect different classes of ships to varying extremes, and must be designed to work properly on a wide variety of vessels.

The form of outfit.xml

Like any XML document, outfit.xml contains exactly one root element. In this case, the <Outfits> tag and it's corresponding </Outfits> closing tag begin and end the outfit.xml document. The root tag contains multiple <outfit> tags, which define individual outfits.

A Sample Outfit Tag

The following XML snippet demonstrates the structure of all the possible tags that can make up the XML portion of a Naev outfit:

<outfit name="Example Cannon MK1">
  <general>
   <slot>weapon</slot>
   <size>light</size>   
   <license>Medium Weapon License</license>
   <mass>10</mass>
   <price>100</price>
   <description>Description of Item</description>
   <gfx_store>laser</gfx_store>
   <limit>mutex_string</limit>
  </general>
  <specific type="example">
  </specific>
 </outfit>

<specific> Tag Structure Types

Note that there are varying additional tags which must be put inside the <specific> tag depending on the category of outfit used. These structures follow their own standard formats, which are listed below:

A-M

Specific Type Afterburner- Afterburners are activated outfits which temporarily increase speed and thrust at a significant energy-per-second cost. They are generally only used in a utility slot, and only one afterburner can be equipped on a ship at a time. The structure of the <specific> tag of afterburners is shown here:

 <specific type="afterburner">
  <cpu>6</cpu>
  <duration>5</duration>
  <cooldown>6</cooldown>
  <rumble>0.9</rumble>
  <sound>afterburner</sound>
  <thrust>300</thrust>
  <speed>45</speed>
  <energy>65</energy>
  <mass_limit>250</mass_limit>
</specific>


Specific Type Ammo- This includes the actual ammunition used by any type of non-turreted launcher. Missiles are typical examples. The structure of the <specific> tag of this type of ammunition is shown below:

 <specific type="ammo">
  <gfx>example</gfx> 
  <sound>example</sound>
  <sound_hit>example_exp1</sound_hit> 
  <spfx_shield>ExpM</spfx_shield>
  <spfx_armour>ExpM</spfx_armour> 
  <duration blowup="armour">8</duration> 
  <lockon>1</lockon> 
  <thrust>500</thrust>
  <turn>50</turn>
  <speed>800</speed>
  <damage type="kinetic" penetrate="10">50</damage>
  <ai>seek</ai> 
 </specific>


Specific Type Beam- Any non-turreted beam weapon falls into this category. Beam weapons are distinct from cannons in that they fire a continuous stream of "projectiles" rather than individual shots. The structure of the <specific> tag of these weapons is shown below:

 <specific type="beam" secondary="1"> 
  <cpu>20</cpu> 
  <delay>1000</delay>
  <duration>4</duration>
  <range>400</range>
  <energy>50</energy>
  <heatup>60</heatup>
  <damage type="energy" penetrate="20">100</damage>
  <spfx_shield>ShiS</spfx_shield>
  <spfx_armour>ExpS</spfx_armour> 
  <gfx>ExampleBeam</gfx> 
  <sound>Example</sound>
  <sound_off>Example2</sound_off>
 </specific>


Specific Type Bolt- This category includes all cannon based weapons. Generally any weapon that is not a beam, does not use ammo, and is not turreted falls into this category. The structure for the <specific> tag of these weapons is shown below:

 <specific type="bolt">
  <cpu>10</cpu>
  <gfx>ExampleImage</gfx>
  <sound>ExampleSound</sound>
  <spfx_shield>ShiS</spfx_shield>
  <spfx_armour>ExpS</spfx_armour>
  <delay>100</delay>
  <speed>200</speed>
  <range>600</range>
  <falloff>400</falloff>
  <gfx_end>ExampleImage2</gfx_end>
  <energy>5</energy>
  <heatup>25</heatup>
  <track>1.5</track>
  <swivel>10</swivel>
  <damage type="energy" penetrate="20">30</damage>
 </specific>


Specific Type Fighter- This includes any sort of internal escorts which are stored in a fighter bay. Once launched, escorts can follow various commands such as following the player and attacking specific targets. Note that escorts destroyed in combat are considered "lost" and must be repurchased. The structure of the <specific> tag of fighters is shown here:

 <specific type="fighter">
  <ship>Example Ship</ship>
 </specific>


Specific Type Fighter Bay- This includes the storage/launching facilities for internal escorts. Each bay can hold a limited number of a specific escort type. Escort bays are generally used in a weapon slot. The structure of the <specific> tag of fighter bays is shown here:

 <specific type="fighter bay" secondary="1">
  <cpu>50</cpu>
  <ammo>Example Fighter</ammo>
  <delay>2000</delay>
  <amount>4</amount>
 </specific>


Specific Type GUI- When purchased, this outfit allows the player to select another GUI to use other than the default. GUIs must be programmed in LUA in the general format shown by the examples in the naev/dat/gui folder. The structure of the <specific> tag of GUIs is shown here:

 <specific type="gui">
  <gui>brushed</gui> 
 </specific>


Specific Type Jammer- Jammers are activated outfits that slow down missiles close to the ship that runs the jammer. The structure of the <specific> tag of jammers is shown here:

 <specific type="jammer">
  <cpu>4</cpu>
  <range>170</range>
  <power>35</power>
  <energy>-15</energy>
</specific>


Specific Type Launcher- This includes all non-turreted projectile launchers that use ammunition. Most missile launchers will fall into this category. The structure of the <specific> tag of this type of launcher is shown below:

 <specific type="launcher" secondary="1">
  <cpu>15</cpu>
  <ammo>Example Missile</ammo>
  <delay>500</delay>
  <amount>20</amount>
 </specific>


Specific Type License- This includes any licenses, which function as requirements for other outfits. They are not intended to be equipped and remain permanently attached to the player regardless of the vessel they are using. No tags are included within the <specific> tag for licenses.

 <specific type="license" />


Specific Type Modification- This includes all equipment which modify the statistics of a ship and do not function as a weapon. This generally includes all items which would normally be equipped in Structure and Utility slots, excluding missile jammers and afterburners. Note that there many possible modifier tags, most of which will not be used in a given item. The structure of the <specific> tag of modifier items is shown below:

 <specific type="modification">
  <cpu>10</cpu>
  <armour>10</armour>
  <armour_rel>10</armour_rel>
  <armour_regen>10</armour_regen>
  <shield>10</shield>
  <shield_rel>10</shield_rel>
  <shield_regen>10</shield_regen>
  <speed>10</speed>
  <speed_rel>10</speed_rel>
  <thrust>10</thrust>
  <thrust_rel>10</thrust_rel>
  <turn>10</turn>
  <turn_rel>10</turn_rel>
  <mass_rel>10</mass_rel> 
  <energy>-10</energy>
  <energy_regen>-1</energy_regen>
  <hide>1</hide>
 </specific>

N-Z

Specific Type Turret Ammo- This includes the actual ammunition used by any type of turreted launcher. Grenades are typical examples. The structure of the <specific> tag of this type of ammunition is shown below:

 <specific type="ammo">
  <gfx>example</gfx> 
  <sound>example</sound>
  <sound_hit>example_exp1</sound_hit> 
  <spfx_shield>ExpM</spfx_shield>
  <spfx_armour>ExpM</spfx_armour> 
  <duration blowup="armour">8</duration> 
  <lockon>1</lockon> 
  <thrust>500</thrust>
  <turn>50</turn>
  <speed>800</speed>
  <damage type="emp" penetrate="10">50</damage>
  <ai>smart</ai> 
 </specific>


Specific Type Turret Beam- Any turreted beam weapon falls into this category. Beam weapons are distinct from cannons in that they fire a continuous stream of "projectiles" rather than individual shots. The structure of the <specific> tag of these weapons is shown below:

 <specific type="beam" secondary="1"> 
  <cpu>20</cpu> 
  <delay>1000</delay>
  <duration>4</duration>
  <range>400</range>
  <turn>35</turn>
  <energy>50</energy>
  <heatup>60</heatup>
  <damage type="energy" penetrate="20">100</damage>
  <spfx_shield>ShiS</spfx_shield>
  <spfx_armour>ExpS</spfx_armour> 
  <gfx>ExampleBeam</gfx> 
  <sound>Example</sound>
  <sound_off>Example2</sound_off>
 </specific>


Specific Type Turret Bolt- This category includes most turret based weapons. Generally any weapon that is not a beam, does not use ammo, and is turreted falls into this category. The structure of the <specific> tag of these weapons is shown below:

 <specific type="turret bolt">
  <cpu>10</cpu>
  <gfx>ExampleImage</gfx>
  <sound>ExampleSound</sound>
  <spfx_shield>ShiS</spfx_shield>
  <spfx_armour>ExpS</spfx_armour>
  <delay>100</delay>
  <speed>200</speed>
  <range>600</range>
  <falloff>400</falloff>
  <gfx_end>ExampleImage2</gfx_end>
  <energy>5</energy>
  <heatup>25</heatup>
  <track>1.5</track>
  <damage type="energy" penetrate="20">30</damage>
 </specific>


Specific Type Turret Launcher- This includes all non-turreted projectile launchers that use ammunition. Turreted grenade launchers are an example of items that would fall into this category. The structure of the <specific> tag of this type of launcher is shown below:

 <specific type="launcher" secondary="1">
  <cpu>15</cpu>
  <ammo>Example Missile</ammo>
  <delay>500</delay>
  <amount>20</amount>
 </specific>

Tag by Tag Explanation of the Outfit XML

The <outfit> XML tag and its children determine the basic attributes of each outfit. The following explains what each does:

Outfit Tag

Each outfit tag has a name attribute, declared in the form name="sample_name" before the concluding > of the opening tag. The <outfit> tag must contain a <general> tag and a <specific> tag.

General Tag

This tag simply holds general purpose tags which describe the basic traits and limitations of outfits. Possible inner tags include <slot>, <size>, <license>, <mass>, <price>, <description>, and <gfx_store>. The <slot> and <size> tags have special default values if not used, and the <license> tag is entirely optional. All other tags should be included with every outfit.

Tags Included in <general>

Description Tag- This is a text description shown when browsing an item in an outfit shop.


GFX Store Tag- This is the name of the image used when displaying an outfit in shops and in the equipment screen. These images are placed in naev/gfx/outfit/store.


License Tag- Marks which license the player is required to own before they can purchase a specific outfit. Not including this tag will allow a player to purchase an outfit by default.


Mass Tag- The mass of a ship is increased by this value when the outfit is equipped.


Price Tag- Indicates the amount of credits a player must spend to purchase an outfit.


Size Tag- Indicates the minimum slot size required for an outfit. Possible values include "light", "medium", and "heavy". Not including this tag will cause an outfit to automatically become light if it's mass is under 10 tons, medium if it is between 10 and 30, and heavy if it is over 30.


Slot Tag- Indicates the type of slot an outfit will use. Possible values include "weapon", "structure", and "utility". Not including this tag will make an outfit impossible to equip (useful for ammunition-based outfits such as fighters and missiles).


Limit Tag- Defines a group of outfits. The player can only have a maximum of 1 outfit of this group installed at any one time.


Specific Tag

This tag simply holds tags which are specific to each type of outfit. Each <specific> tag has a "type" attribute, declared in the format type="sample_type". The possible values for "type" are described in the "<specific> Tag Structure" section above. <specific> tags also have an optional "secondary" attribute, set to 0 by default. If "secondary=1" is included, the outfit will automatically function as a secondary weapon when equipped in a weapon slot.

Tags Included in <specific>

A-H

AI Tag- Determines the type of tracking used by a projectile. Tracking is constantly updated, but the ability of a projectile to hit a target can differ significantly depending on the type of tracking used. Possible values include "smart", "seek", and "dumb". Smart tracking uses velocity to estimate where the target ship will be upon impact, and aims for that point. Seek tracking only aims for where the target ship is located at that particular moment. Dumb tracking causes projectiles to only fly in a straight line.


Ammo Tag- Sets the type of ammunition used by outfits of the "launcher" and "turret launcher" type. This also sets the type of escort used by outfits of the "launcher bay" type.


Amount Tag- Sets the amount of ammunition which can be stored by a single outfit of the "launcher" or "turret launcher" type. This also sets the number of escorts which can be held by an outfit of the "launcher bay" type.


Armour Tag- Directly increases a ship's armor by the given value.


Armour Rel Tag- Increases a ship's armor by the given percentage.


Armour Regen Tag- Increases the ship's armor regeneration rate by the given value.


Chance Tag- Sets the chance of a "ammo" or "turret ammo" projectile being destroyed when it enters within range of the equipping ship as defined by the "range" tag.


CPU Tag- Sets the CPU cost of a specific outfit. Negative values increase maximum CPU capacity instead.


Damage Tag- Sets the damaged caused to a ship by a fired projectile. Note that when used with outfits of the "beam" or "turret beam" type, it defines the amount of damage dealt if a target is continuously hit for one second. In both cases, it contains two mandatory attributes- "type" and "penetrate".

The possible values for "type" include "energy", "kinetic", "emp", and "ion". Ion attacks do additional damage to shields and less to armor, whereas kinetic does more to armor and less to shields. Energy attacks do equal damage to both. EMP attacks are similar to energy, but will only disable vessels, not destroy them.

The "penetrate" attribute directly reduces the effect of damage absorption on a target vessel by a given value. For example, if a missile with 20 penetration hits a ship with 50 damage absorption, the impact will be treated as if the ship only had 30 damage absorption. Setting this to 0 allows full damage absorption to take place.


Delay Tag- Sets the rate of fire for projectile weapons. The lower this value is, the faster a weapon will fire. When used with outfits of the "fighter bay" type, this determines how quickly fighters will be launched. When used with outfits of the "beam" or "turret beam" type, this determines how fast a beam weapon will recover after being deactivated. In this case, the player must wait through the maximum delay will regardless of whether they manually deactivated the beam or waited the full fire length as defined in the <duration> tag.


Duration Tag- When used with outfits of the "beam" or "turret beam" type, this sets the maximum number of seconds that a beam can be continuously active before it shuts off and the weapon must go through the <delay> period to be used again.

When used with an outfit of the type "ammo" or "turret ammo", this determines how long these types of projectiles will remain in motion before dissipating. In this instance <duration> requires the attribute "blowup", which has two possible values- "armour" and "shield". Ammo which hits a target will only activate the special effect targeted by blowup as explained in the descriptions for the <spfx_shield> and <spfx_armour> tags.


Energy Tag- Sets the energy-per-second cost of an outfit when it is continuously used. Note that when this is used with an outfit of the "modifier" type, it instead directly modifies the maximum available energy of a ship by the given value. When used with an outfit of the "jammer" type, it directly reduces the energy regeneration rate of a ship by the given value.


Energy Regen Tag- Increases the ship's energy regeneration rate by the given value.


Falloff Tag- Causes a projectile to deal significantly reduced damage when it has traveled past the listed distance. Note that this tag is optional, but should be set to a lower value than <range> if used.


GFX Tag- Defines the name of the sprite sheet which determines how a fired projectile will appear to the player. These sprite sheets are stored in naev/gfx/outfit/space.


GFX End Tag- Causes a projectile's sprite as described in the <gfx> tag to gain an increased alpha value as it travels, gradually changing into the sprite described here. These sprites are also located at naev/gfx/outfit/space. This tag is optional where it is listed.


GUI Tag- Defines the name of the GUI file used when activated by the player. GUI files are stored in the naev/dat/gui folder.


Heatup Tag- A weapon outfit with this tag can be fired for the given number of seconds before it will begin to overheat. When this happens, accuracy will rapidly begin to degrade, and the player must wait a considerable amount of time for weapon heat to gradually reset.


Hide Tag- An absolute bonus to the ship's hide factor.


I-P

Lockon Tag- This sets the number of seconds it takes for a projectile to "activate" and begin to home in on the target. If a projectile makes contact with the target before the lockon time is reached, it will simply pass through the target instead.


Mass Limit Tag- Sets the maximum mass a ship may be before an outfit of the "afterburner" type begins to lose effectiveness.


Mass Rel Tag- Increases a ship's mass by the given percentage.


Q-Z

Range Tag- Sets how far a projectile will travel before dissipating. Setting this higher will allow a projectile to travel further. When used on an outfit of the "jammer" type, this will cause the jammer to potentially destroy an incoming projectile of the "ammo" or "turret ammo" types when it comes within the given range.


Rumble Tag- Sets the intensity of the screen shaking effect caused when an outfit of the "afterburner" type is used. The higher the number, the more noticeable the rumble.


Shield Tag- Directly increases a ship's shields by the given value.


Shield Rel Tag- Increases a ship's shields by the given percentage.


Shield Regen Tag- Increases the ship's shield regeneration rate by the given value.


Ship Tag- Defines the name of the type of ship to be used with an outfit of the "fighter" type. Ships data is found in the naev/dat/ship.xml file.


Sound Tag- Defines the name of the sound file played when a weapon is fired. Note that outfits of the "beam", "turret beam", and "afterburner" types will continuously play this sound effect while active. These sound files are stored in naev/snd/sounds.


Sound Hit Tag- Contains the name of the sound file to be played when a projectile hits a target. These sound files are stored in naev/snd/sounds.


Sound Off Tag- Defines the name of the sound file played when the continuous fire effect of a "beam" or "turret beam" outfit type has ended. These sound files are stored in naev/snd/sounds.


Speed Tag- Sets how fast a projectile will travel. The higher this value is, the faster a projectile will move. When used on an outfit of the "afterburner" type, this increases the ship's maximum speed by the given percentage while the afterburner is active. When used on an outfit of the "modifier" type, this directly increases the ship's maximum speed by the given value.


Speed Rel Tag- Increases a ship's maximum speed by the given percentage.


SPFX Armour Tag- Defines the name of the special effect used when a projectile hits a ship's armour. Note that outfits of the "ammunition" and "turret ammo" types require the "blowup" attribute in the "duration" tag, which sets a specific SPFX type to be used on impact. This means means that only the SPFX type listed (armour or shield) will ever be used in these cases.


SPFX Shield Tag- Defines the name of the special effect used when a projectile hits a ship's shields. Note that outfits of the "ammunition" and "turret ammo" types require the "blowup" attribute in the "duration" tag, which sets a specific SPFX type to be used on impact. This means means that only the SPFX type listed (armour or shield) will ever be used in these cases.


Swivel Tag- Sets the amount of degrees a cannon is able to rotate from its central point in order to hit a targeted enemy. When set to a very high value, this will cause cannons to visibly "bend" in the direction of an enemy when fired. Note that the ability of a swivel cannon to hit targets is still controlled by the <track> tag, meaning that a weapon with high swivel and low track will still regularly miss moving targets.


Thrust Tag- Similar to the function of thrust when used in ships. The higher the value given for <thrust>, the faster a projectile can rapidly regain speed when changing direction. When used on an outfit of the "modifier" type, this directly increases a ship's thrust by the given value. When used on an outfit of the "afterburner" type, this increases the ship's thrust by the given percentage while the afterburner is active.


Thrust Rel Tag- Increases a ship's thrust by the given percentage.


Track Tag- Determines how accurately a turret or the swivel of a cannon can hit a target even when not directly aimed at by the player. Generally values between 0 and 3 should be used, with 0.3 only being able to hit the slowest of capital ships and 2 being able to hit all but the fastest fighters. In combat, track is modified by the overall heat and relative velocity of the target vessel.


Turn Tag- Determines how quickly a turreted weapon can swivel its beam to hit the enemy while continuously fired. The higher the number, the faster it can turn. When used with an outfit of the "ammo" or "turret ammo" type, this tag defines how quickly a projectile can turn when homing in on a target. The higher the value, the faster a projectile can turn.

When used with an outfit of the "modifier" type, this directly increases a ship's turn rate by the given value.


Turn Rel Tag- Increases a ship's turn rate by the given percentage.