HowTo:Edit Unit Files

From VsWiki
Jump to: navigation, search
arrow_left.png Edit units.csv arrow_up.png HowTos Editing HUDs arrow_right.png

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



arrow_left.png Edit units.csv arrow_up.png HowTos Editing HUDs arrow_right.png