HowTo:Edit Unit Files

If you're wondering why you can't find any examples of xunit files in the Vegastrike data set, that's because this file format isn't used anymore. Unit information is stored in units/units.csv in the data directory instead. You can still use the information on this page to create a unit, just append it to units.csv using objconv/ucsv.py in the source directory once you're done. The result isn't guaranteed to be perfect, but if everything else is in order the unit should be flyable and viewable in-game. You can then use a spreadsheet program to handle the rest of it.

Examples taken from the wayfarer ship (now named the llama), for full description 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>

---

The original desciption of the xunit syntax from hellcatv is located in cvs under units/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 http://vegastrike.sourceforge.net/forums/viewtopic.php?p=9688#9688 for more.
    • RANDOM - Random start delay.
    • time until mesh animation starts
  • startframe - (optional) Defines the starting-frame of a mesh animation. See http://vegastrike.sourceforge.net/forums/viewtopic.php?p=9688#9688 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 (which sizes it can hold) and if it's autotracking (goes inside the long string 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> - nothing yet ???
• <Defense ...> </Defense> -
  • ~HudImage - sprite file to use when targetted
  • ~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 abserce 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|http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/vegastrike/data/ai/VegaPriorities.csv?rev=HEAD&content-type=text/plain] )
  • 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: http://www.xs4all.nl/~margjos/langen.htm
    • 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 - ammount 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 Subunt is a (not necessarily) small independant 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 frmo toplevel units
  • size: 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] - [Link|#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 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 hence qi*qi+qj*qj+qk*qk = 0*0+1*1+0*0=1

---

! #[Unit-Differences] between the various unit files - [Link|#Unit-Differences] See also [this|http://vegastrike.sourceforge.net/forums/viewtopic.php?t=1811] 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.
• .template file
  • The template basically defines the maximum values for a ship/unit. e.g:
    • max speed
    • max yaw
    • max power
    • ...
  • 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 VsManualDbShipUpgrades.
    • Example:

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

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

---

Last updated: Pontiac 2004.01.21 %%%Created: Pontiac 2003.04.27

---

Back to VegastrikeHowtos