HowTo:Edit Unit Files

Edit units.csv

HowTos

Editing HUDs

---

EDITING UNIT FILES

File example

Examples taken from the former starting ship 'wayfarer' (now named the llama), for a full description of the XML syntax see below.

 <Unit Scale="1">
   <Cockpit  file="heavy-cockpit.cpt" x="0" y="0" z="0" />
   <Meshfile file="rescue-hull-e.xmesh" />
   <Mount weapon="Ion" size="Light Medium Heavy" x="9.8108" y="1.757" z="11.8091" />
   <Sound>    </Sound>
   <Defense HudImage="wayfarer-hud.spr" >
     <Armor front="250" right="225" left="225" back="240" />
     <Shields front="150.000000" back="150.000000" recharge="30.000000" />
     <Hull strength="200.000000" />
   </Defense>
   <Stats mass="1096" momentofinertia="1096" fuel="40000000" />
   <Thrust >
     <Engine Afterburner="117007" Forward="22523" Retro="27935" Left="22231" Right="22231" Top="22231" Bottom="22231"  />
     <Maneuver yaw="289943" pitch="239988" roll="399637" />
   </Thrust>   <Computer yaw="60.400002" pitch="50.600006" roll="80.400002" afterburner="85" maxspeed="30" />
   <Energy >
     <Reactor recharge="60" limit="400" />
   </Energy>
   <Jump delay="2" jumpenergy="150" />
   <description combatRole="SHUTTLE" >
   Some cool description of the ship.
   </description>
   <Hold volume="125" >
     <Category file="Natural_Products/Natural_Resources" >
       <import price=".8" pricestddev=".2" quantity="0" quantitystddev="5"  />
     </Category>
   </Hold>
   <Light file="supernova.bmp" x="-10.24" y="-2.759" z="-18.302" size="6" />
   <Dock x="0" y="-4.7" z="6" size="10" />
 </Unit>

XML schema

The original description of the xunit syntax from hellcatv is located in SVN (description.xunit) (VSD = 5400 kJ (kilojoules).

<Unit ...> </Unit> - Marks the begin and the end of the unit(file)

• Scale - Sets the scaling of the unit in the game
• <Cockpit .../> - Defines a cockpit for the ship.
  • file - Points to a cockpit file. Extension .cpt
  • x,y,z - Coordinates where the Cockpit should be in the Unit/Ship (in meters)
  • See also HowTo:Edit HUDs.
• <Meshfile .../>
  • file - Points to a xmesh-file of the ship. Extension .xmesh
  • texturestarttime - (optional) Defines the starting delay of a mesh animation. See forums for more.
    • RANDOM - Random start delay.
    • time until mesh animation starts
  • startframe - (optional) Defines the starting-frame of a mesh animation. See forums for more.
    • RANDOM - Random start-frame.
    • number of start-frame
• <ShieldMesh> - (optional) xmesh-file to use for the shield instead of a sphere. Extension .xmesh
• <RapidMesh> - (optional) xmesh-file to load and use for collisions with other units/ships/... instead of the Meshfile from above (not drawn) Extension .xmesh
• <BspMesh> - (optional) xmesh-file to use for beam and bolt collisions (not drawn) Extension .xmesh
• <Mount .../> - (optional)(repeatable) Specifies a weapon mount
  • weapon - Type of weapon (see weapon_list.xml in the data directory)
  • size - size class(es)/type(s) and if they are capable of autotracking. The single entries are separated by spaces. e.g: size="LIGHT MEDIUM AUTOTRACKING"
    • LIGHT
    • MEDIUM
    • HEAVY
    • SPECIAL
    • CAPSHIP-LIGHT
    • CAPSHIP-MEDIUM
    • CAPSHIP-HEAVY
    • AUTOTRACKING
    • SPECIAL-MISSILE
    • LIGHT-MISSILE
    • MEDIUM-MISSILE
    • HEAVY-MISSILE
    • LIGHT-CAPSHIP-MISSILE
    • MEDIUM-CAPSHIP-MISSILE
    • HEAVY-CAPSHIP-MISSILE
  • ammo - how much ammo the gun holds (only needed for ammo needing weapons e.g. missiles,torpedos,...)
  • volume - (optional see "ammo") how much ammo the gun can hold if you refill
  • x,y,z - location of weapon (in meters ;-))
  • ri,rj,rk - (optional) R-vector forward vector) of gun (assume 0,0,1)
  • qi,qj,qk - (optional) Q-vector (up vector) of gun (assume 0,1,0)
• <Sound> </Sound> - FIXME nothing yet ???
• <Defense ...> </Defense> - FIXME
  • HudImage - sprite file to use when targetted FIXME relative to what?
  • ExplosionAni - (optional) special explosion to use
  • RepairDroid - (optional) strength of repair system (0-6)
  • ECM - (optional) type of ECM (Electronic Counter Measure)
  • <Armor .../> - Specifies the ships physical armor
    • front - Forward max armor in VSD
    • right - Right armor in VSD
    • left - Left armor in VSD
    • back - Back armor in VSD
  • <Shields .../> - Specifies the ships Shield (electric armor)
    • front - Forward max shields in VSD
    • back - Back shields in VSD
    • recharge - Shield regeneration if not violating speed limit in VSD/s
    • leak - (optional) how much leak these shields have (usually 0%) between 0 and 100
    • left - (optional) Left shields in VSD
    • right - (optional) Right shields in VSD
    • top - (optional) Top shields) in VSD
    • bottom - (optional)bottom shields in VSD
  • <Hull .../> - Specifies the ships Hull
    • strength - Max hull in VSD
  • <Cloak .../> - (optional) Specifies the ships cloak device
    • missing - if 1, then no cloak is here. also missing in absence of optional tag
    • cloakmin - minimum percentage of cloakedness
    • cloakglass - boolean whether or not effect 2 is used
    • cloakrate - time per second to cloak in decimal per second
    • cloakenergy - how much energy this takes in 100kJ
• <Stats .../> - Specifies the statics of the ship
  • mass - mass in metric tonnes (kkg)
  • momentofinertia - mass*m*m in (metric tonnes * meter * meter)
  • fuel - amount of fuel
• <Thrust>...</Thrust> - Specifies the ships thrust
  • <Engine /> - Specifies the ships engine
    • Afterburner - Thrust with afterburners in metric tonnes meters per second squared
    • Forward - Thrust without afterburners in kkg*m/s^2
    • Retro - Reverse thrust in kkg*m/s^2
    • Left - Left thrust in kkg*m/s^2
    • Right - Right thrust in kkg*m/s^2
    • Top - Top thrust in kkg*m/s^2
    • Bottom - Bottom thrust in kkg*m/s^2
  • <Maneuver .../> - Specifies the ships maneuver data
    • yaw - Right yaw in metric tonnes degrees per second squared
    • pitch - Right pitch in kkg*deg/s^2
    • roll - Right roll in kkg*deg/s^2
• <Computer ...> ... </Computer>-
  • yaw - max yaw in degrees per second
  • pitch - max pitch in dps
  • roll - max roll in dps
  • afterburner - Max safe speed with afterburners in m/s
  • maxspeed - Max safe speed without afterburner in m/s
  • slidestart - (optional) number of tenths of seconds before fully reacting to keyboard (smoothing)
  • slideend - (optional) number of tenths of seconds to stop
  • <Radar .../> - Specifies the ships radar system
    • itts - if the unit has ability to target track with lead
    • color - if unit has color radar
    • range - maximum range of radar
    • error - (optional) currently unused
    • trackingCone - cosine of cone at which guns may track
    • lockcone - cosine of cone at which missiles gain locking time
    • mintargetsize - unused...but supposedly minimum target this can do
• <Energy> ... </Energy> -
  • <Reactor .../> - Specifies the ships poer unit (reactor)
    • recharge - recharging of reactor in 100 MJ/s
    • limit - max storage of reactor in 100 MJ/s
• <Jump .../> - (optional)
  • delay - seconds before jump drive initiates
    • jumpenergy - energy to jump
  • wormhole - forces units to teleport upon touching this one
  • missing - boolean whether the jump drive is missing (assumed missing in absence of tag)
• <description ...>... </description> - (repeatable)
  • combatrole - combat role that the ship has (see ai/VegaPriorities.csv )
  • lang - (optional) Language code for the language the description is written in.
    • e.g lang='DE' for German language
    • See this link for all codes:
    • If no lang attribute is specified the description is meant to be English. (is this correct'?')
  • Some cool description of the ship.
• <Hold ...> ... </Hold>
  • volume - volume in cargo units
  • <Category ...> ... </Category> - (optional)(repeatable) A category to use from the Vs-MasterPartList'.
    • file -
      • e.g. file="Natural_Products/Natural_Resources"
    • <import .../> (optional)
      • price - price scale (multiplied by price in list)
      • pricestddev - price scale variation (above adjusted by this)
      • quantity - quantity of this sort of cargo
      • quantitystddev - quantity variation
    • <Cargo .../> (optional)(repeatable)
      • file - name of cargo
      • price - price of cargo
      • quantity - amount of cargo
      • mass - mass in tonnes
      • volume - size of cargo in cargo units
      • description - (optional/unused)
• <Light .../> - (optional)(repeatable) Specifies an engine-flame/light/glow/whatever on your ship
  • file - meshfile (sans .xmesh) for this engine model
    • e.g. "supernova.bmp" it's actually a xmesh file
  • x,y,z - location of light (in meters ;-))
  • size - size of engine (radius, in meters ;-))
  • red,blue,green - (optional)red/blue/green dye of engine
• <Dock .../> - (optional)(repeatable) A place where another unit can dock.
  • x,y,z - location of dock (in meters ;-))
  • size - size of dock port (radius, in meters ;-))
  • dockinternal - (optional/unused) whether the dock port makes the ship disappeared. The ship must be smaller than the size of the dock, otherwise it will remain in open space.
• <SubUnit .../> - (optional)(repeatable) A Subunit is a (not necessarily) small independent part of your unit. In fact the main unit and the subunit are two different ships (units) patched together at a certain point (x,y,z see below). If a subunit is destroyed the remaining parts will fly into space like the remainings of any other ship ... e.g turrets
  • file - unit file that can be referenced from toplevel units
  • siz - size class (which sizes it can hold)
  • x,y,z - location of subunit (in meters ;-))
  • ri,rj,rk - (optional) R-vector (forward vector) of subunit (assume 0,0,1)
  • qi,qj,qk - (optional) Q-vector (up vector) of subunit (assume 0,1,0)
  • restricted - (optional) minimum dot with rj that the turret can have so it can't turn inside itself
• <CockpitDamage .../> - (optional)(repeatable up to 1+NUMGAUGES+MAXVDUS or 29)
  • NOTE: If you have more, strange things may happen, as it will probably overrun the cockpitdamage buffer.
  • damage - float between 0 and 1 depending on the amount of static the vdu has.
• <Upgrade .../> - (optional)(repeatable) an upgrade unit that adds its stats onto this unit (as if you had bought it from the shop).
  • file - the file to upgrade it with.

Turret directions

There are 2 vectors for turrets: r and q

r is the forward vector:

• x component = ri
• y component = rj
• z component = rk

When forward is pointing in the +z direction then rk is 1 and ri and rj are zero (0) hence
ri*ri+rj*rj+rk*rk = 0*0+0*0+1*1 = 1

q is the up vector:

• x component = qi
• y component = qj
• z component = qk

When forward is pointing in the +z direction then qj is 1 and qi and qj are zero (0) hence
qi*qi+qj*qj+qk*qk = 0*0+1*1+0*0 = 1

Fileextension differences

See also this forum thread.

• <file without extension>
  • default unit file
• .blank file
  • As the name already says, this is the 'blank' unit file. This ship doesn't have any weapons or upgrades on it.
  • FIXME
• .template file
  • The template basically defines the maximum and minimum values for a ship/unit. e.g:
    • maximum speed
    • max. yaw
    • max. power
    • ... FIXME
  • The upgrades available to a ship are also located in this file.
    • The actual upgrades and how they behave are defined by unit files located in the units/factions/upgrades directory. Just look at a few of the files in there and it should be pretty straightforward. There need to be a section in the wiki for the description of this :-)
    • A (not always up to date) list of upgrades is under Upgrades.
    • Example:

<Upgrade file="reactor_level_3"/>
<Upgrade file="mult_gun_cooler"/>
<upgrade file="add_reactor_capacitance"/>

• .factionname
  • unit file for the named faction ... e.g dodo.confed

See also

• HowTo:Edit units.csv
• HowTo:Edit HUDs
• Forum posts
  • Unit Differences
  • XML Format

---

Edit units.csv

HowTos

Editing HUDs