HowTo:Add Ships

HowTos

Create Models

---

---

Introduction

This article is a general guide on how to take your ship mesh all the way from your modeling suite of choice into the bowels of Vega Strike.

Before we begin, here are the files/executables you need to know about:

• .OBJ+.MTL - The standard alias wavefront mesh format.
• .WINGS - Wings3D file format. See Creating a 3D-model using Wings3D for detailed information on using Wings3D to create your model.
• .XMESH - XML-Mesh format. A simple, manually editable file format designed for Vega Strike.
• .BFXM - (Binary Formatted XMesh) A compiled .xmesh. Loads much faster than an .xmesh, and can contain multiple xmeshes (for LODs, animations, or models consisting of multiple components).
• Mesher - A command-line utility for converting between .obj+.mtl, .bfxm, and .xmesh formats.
• units.csv - A comma-seperated value spreadsheet which contains information on units that can be used by the game.

→ See also: Development:Scripts & Tools

Last, we recommend following the processes below in order, until you know what you're doing.

Part Three: From Modeling Suite File Format to BFXM

Now, it's go time! The first step in getting your cool new model into Vega Strike is to export it to a format that Vega Strike understands. Currently, Vega Strike is able to read .obj, .xmesh, and .bfxm files. However, it is best to use the native BFXM format because it is fast, so this guide is written with that in mind.

OBJ is a standard, widely supported mesh format. Nearly all modern 3D suites support some form of OBJ import/export. If your modeller can't export to OBJ, see if it can export to some other standard format (like 3DS). You will have to find a 3D converter that can go from that format to OBJ. However, the assumption is that your modeller can export to OBJ. Note that when using Wings3D, the file format saved is .wings, which is not supported by Vega Strike. However, a Wings3D plugin by pontiac is available to convert .wings to .xmesh when saving the file, along with a standard OBJ export option.

Okay, so now you've got an OBJ file (and probably an MTL file as well). Windows users should move these files into the "bin" folder inside the main Vega Strike directory. Now, start up a command prompt or terminal of some sort, and change your directory to WHEREVER\bin\ . We will use mesher.exe to compile your mesh.

Linux users will have to compile mesher from source with the command "make mesher" after following the standard bootstrap/configure procedure HowTo:Compile_from_SVN_on_Linux#Make. Mesher can be made available anywhere by creating an alias for it in your shell (usually ~/.bashrc), or adding the vegastrike directory to your path.

If you run mesher without any arguments, it will print a list of available commands.

FIXME - Add information on klauss' new mesher switches in SVN

Mesher does not try to detect what kind of file you're feeding it, so you need to specify a three-character conversion code as part of the argument. You just want to go from OBJ+MTL to BFXM right now, so run mesher with the following arguments:

mesher whatever.obj whatever.bfxm obc

The command obc means "obj to bfxm, create output file".

Should mesher throw an error, you may check if the obj file actually references the mtl file correctly, i.e. with the same base name as the obj file (in Derivative.obj):

mtllib Derivative.mtl

Okay, so now you've got a bfxm. Great! The problem with BFXM is that you can't really edit it by hand in order to add the additional functionality Vega Strike supports (like specularity, damage, or glow maps). There are two ways to do this.

Editing Textures via MTL File (new method)

If you are running mesher from the latest SVN, it will respect the settings specified in the MTL file. This means you can set materials and texture maps by editing the MTL file before converting your mesh to BFXM, hopefully avoiding the need to convert to XMESH. The texture maps can be specified in the MTL file like so:

map_kd diffuse.texture
map_ks spec.texture
map_ke glow.texture
map_damage damage.texture
map_normal normal.texture

or more generically:

map_0   main_tex_000.texture
map_1   main_tex_001.texture
map_2   main_tex_002.texture
map_3   main_tex_003.texture
map_4   main_tex_004.texture 

Further, make sure that the following parameters are set to values given here for the textures to go unchanged into the shader:

kd 1.0 1.0 1.0
ks 1.0 1.0 1.0
ka 0.0 0.0 0.0
ke 0.0 0.0 0.0

There's a way to specify blend mode:

BLEND 1   -- equivalent to ONE ONE
BLEND 0.5 -- equivalent to SRCALPHA INVSRCALPHA
BLEND 0   -- equivalent to ONE ZERO 

Other parameters in MTL files:

Ns 30       -- set shininess power=30
illum 2     -- illumination strength (0=off, 1=on, 2=on); not used by the shader, can be left out
Ni 1.000000 -- unknown and unused parameter
d 1.000000  -- unknown and unused parameter
detail_plane 0 1 0 -- generates a new set of coordinates by projecting into that plane
technique A -- specify technique to use with this object

Editing Textures via XMESH File (old method)

When in doubt, you can always convert your BFXM to XMESH. Run mesher with these arguments to do so:

mesher whatever.bfxm whatever.xmesh bxc

Currently, you have to use XMESH if you need to implement complicated mesh features such as LODs. You'll also need to use this method if you have an old version of mesher.

So, prepare to get your hands dirty. Whip out your favorite text editor, cause it's XMESH time!

Manual XMESHin'

Under ideal conditions, you won't have to hack the xmesh much. To assign specularity maps (which you must do, unless you want your ship to look like a giant mirror), all you need to do is add an attribute to the <Mesh> tag at the beginning of the file. Your basic xmesh header looks like this:

<Mesh scale="1.000000" reverse="0" forcetexture="0" sharevert="0" polygonoffset="0.000000" 
blend="ONE ZERO" texture="mycoolship.png" >

The attributes you can add are texture1, texture2, and/or texture3, which correspond to specularity map, damage map, and glowmap respectively.

<Mesh scale="1.000000" reverse="0" forcetexture="0" sharevert="0" polygonoffset="0.000000"
blend="ONE ZERO" texture="mycoolship.png" 
texture1="mycoolshipPPL.png" texture2="mycoolshipDMG.png" texture3="mycoolshipGLO.png" >

(FIXME : PPL is correct nomenclature for specmaps, but I made up DMG and GLO. What should these files be named?)

→ Main article: HowTo:Add Per Pixel Lighting

→ See also: HowTo:Edit XMESH files

Damage maps and glowmaps are optional. If you don't want to make a specmap, or if you want your ship to be completely matte (nonreflective), simply assign the common texture "black.png" (a 1x1 black image) to texture1.

While you have your imaging tools out, now is a good time to cope with a little bug in mesher. It inverts the UV coordinates of your mesh, so you'll need to flip your texture vertically and re-save it. If your texture is in a lossy format like JPEG, work from the master if possible. PNG shouldn't be an issue. Note: If you are running the latest SVN, this bug in mesher has been fixed, making the previous step unneccessary.

Once you have all your additional maps referenced in the <Mesh> tag, you're ready to go back to BFXM. Run mesher with the following argument:

mesher whatever.xmesh whatever.bfxm xbc

Your mesh is now primed and ready for insertion into Vega Strike!

Damage and glow maps

The sole purpose of damage maps are, as their name so aptly suggests, to add a scorched and damaged look to your model. Esentially it is a regular texture that fades in when the unit takes hull damage. When the unit is polished, shiny and unharmed, its regular texture will be shown at full opacity and the damage texture at zero opacity. As the units takes hits the damage texture will be faded in, to end with the exact opposite result - the regular texture will have zero opacity and the damage texture will be shown at full opacity.

Glow maps are RGB textures that light the diffuse texture regardless of the light conditions. Painting a region of your glow map blue will cause the same region of your diffuse texture to be lit with blue light. A typical example of the use for glow maps is to evoke the feeling of light flowing out of windows.

Multiple Xmeshes

In some cases, mesher will generate multiple xmeshes from a single bfxm. If this is the case, you'll need to reconstruct the bfxm by first converting the main xmesh file to bfxm normally, and then running mesher as many times as needed with the following argument:

mesher #_#.xmesh whatever.bfxm xba

Where xba means "xmesh to bfxm, append". Usually, #_# will be something like 1_0 (N_M.xmesh marks a file as being the Nth mesh and the Mth LOD thereof - only top-level meshes need to be appended, LODs are included based on references from each top level mesh). Once you have appended all the additional xmeshes to the bfxm file, you should be good to go.

Levels of Detail

To append an LOD to a top-level xmesh file, use a tag like so:

<LOD meshname="EXAMPLE.xmesh" size="1600" />

Where meshname is the name of the LOD (usually something like 1_1.xmesh) and the size is the amount of pixels taken up by the model when the LOD kicks in. Size is a product of the square resolution, so 1600 would mean a 40x40 area.

→ Main article: HowTo:Add LODs

Part Four: Units.csv

Note: The following section details how to make a new game unit for your model. If you just want to quickly test how your mesh looks in-game without mucking about in units.csv, see the Swapping mesh files subsection.

Now comes the time to get into the real nitty-gritty and associate some data with your mesh that will tell the game how it should be used. Most spreadsheet programs can open .csv files. You can use popular software such as Microsoft Excel or OpenOffice.org Calc to edit units.csv. As an alternative, GAlex has written a nice, lightweight .csv editor tailored to work well with units.csv. (Get it here.)

Once you've loaded up units.csv, start by looking in the first column for a ship that you think is reasonably similar to your own. If you're not sure, llama.begin is a good place to start. The data for each ship occupy a single row, so once you've found it, select the entire line and duplicate it. Change the unit name to whatever your shipname is. Avoid spaces and special characters in column one, since it is a name used internally by vegastrike. (FIXME - Is that even true?)

In column two, change the pathname to whatever directory you want to place your ship in. "./whatever" Means "VSINSTALLDIR\units\whatever\", so you'll want to make a new folder called "whatever" in the units directory and copy your BFXM and textures into it.

→ Main article: HowTo:Edit units.csv

You probably want to specify what types of mount points your ship has (various missiles, guns, turrets, etc.) These can be edited in the "Mounts" column. To the left of the mounts column is the "Light" column, which gives the location and type of your ship's engine flare graphics. Light, mount, and even cockpit positions are specified with X,Y,Z coordinates on your mesh.

→ Main article: HowTo:Add Engine Glow

Part Five: Testin' Time

Okay, that's enough to test your ship in-game.

Since your new ship isn't yet listed as a purchasable item, you'll have to hack a save file to test it (if you want to make it purchaseable immediately, skip to Part Six). Start by going into your VSINSTALLDIR\.vegastrike\save\ directory and copying one of your save files. Then, open the copy up in a text editor. The first line should resemble this:

Crucible/Cephid_17^13500000.000000^whatever 209160449.772106 -62167111.692738 193000385.631824

After the second caret (^) symbol, you should see a ship name. Change this to whatever you named your ship in the first column of its units.csv row, and save.

You are now ready to see your ship in action! Load up Vega Strike and load your new save game file.

Now, you can either stop, satisfied with your achievement, or return to units.csv and toil endlessly to balance your ship's stats correctly. Which will it be? :-P

Swapping mesh files

If you don't need to create a game unit immediately and only want to test the mesh itself in-game, you can quickly swap it with another mesh. For instance, if you are flying a llama in your current game, rename llama.bfxm to something like llama.real.bfxm, and then call your new mesh llama.bfxm. Note that you will still be flying a llama, with llama stats and engine/mount placements, but it will look like your new ship.

This method should only be used for quickly seeing how meshes look in-game, and for testing their integrity. For modding purposes, it is recommended that you create an actual unit as described above.

Part Six: Making your ship purchasable

You need to do two things to make something purchasable:

1. Add the appropriate entry to the master_part_list.csv. Feel free to make up whatever category you want your ship to be in, but if you use an existing category, you will have less work in step 2.
2. Add entries to units.csv in the cargo_import field for EVERY unit that you want your ship to be purchased or sold. If your category is starships/Imperial/Medium and you want the price to be at the value in master_part_list.csv with no variance, with 10 ships in that category available with a variance of 2 then your entry would be {starships/Imperial/Medium;1;0;10;2}.

The engine will automatically drill-down the categories in the purchase screen.

Part Seven: Giving the ship to NPC

Ships are assigned for spawn in data/modules/faction_ships.py - look for lines like

capitals = (...

... ("Ox","Mule","Mule","Mule","Cultivator","Cultivator"), #shaper_citizen

...

Find the general type (there are fighters, capital ships, etc) and add an entry to the lines of factions you think should have this ship. It will be randomly picked from the list. Also, note that there are separate names for basic ship configurations, such as "<name>.stock" with corresponding lines in units.csv, and try to use them the same way - auto-upgrade routine is supposed to use these.

---

HowTos

Create Models