Freelancer VMesh Converter v0.7b
---------------------------------------------------------------

Syntax : MESHCONV VMeshData_filename VMeshRef_filename ( /g )

This utility accepts the VMeshData and VMeshRef sections from an exporter Freelancer .cmp file and modifies them so that different objects in the model are correctly defined.  It also calculates the 'Bounding Box' (min/max x, y and z) values for each object and writes them to the VMeshRef file as these are missing from the originals.

By default it will read in each mesh (group in Milkshape) and rewrite it as a separate object.  So a model with 5 groups in Milkshape will output the VMeshData file as being a model with 5 groups and 5 VMeshRef files will be written, one for each object in the .cmp.  

Using the '/g' switch allows user specified mesh groups.  This allows several Milkshape groups to be combined into one object.  First a prompt will ask how many objects in total the model codes for.  After this it will ask how many meshes (groups in Milkshape) each object is composed of.  For several groups to compose an object they must be sequential.  All being well it will then output the VMeshData accordingly and write one VMeshRef segment for each group.


EXAMPLES
-------------------

**Each Milkshape Group as a separate object **
--------------------------------------------------------------------------------------


Suppoose you have a ship in Milkshape composed of 4 groups :

Hull
Left Wing
Right Wing
Top Fin

For realism this ship should be composed of 4 objects which can then be defined as destructable and/or have specific Hp's mapped to them.  When you export to .cmp the VMeshData is written as if the ship was one object spanning 4 meshes.  One VMeshRef segment is provided defining one object spanning all meshes/vertices in the VMeshData segment.  To convert the VMesh segments to 4 groups is very simple :

1.  Open the exported .cmp.  Export the VMeshLibrary -> 'Your_first_group_name'.lod0.vms -> VMeshData node to a file in the directory where you have MESHCONV.EXE - say you call the file 'MyShip_VMeshData'.  Then export the 'Your_first_group_name'.3db -> Multilevel -> Level0 -> VMeshPart -> VMeshRef node to a file in the same directory - say you call this one 'MyShip_VMeshRef'.

2.  Open a command prompt and get to the directory where MESHCONV.EXE and your MyShip_VMeshData/Ref files are.  As each mesh (Milkshape group) is going to compose one separate object there is no need to manually enter group information as this is the default mode.  Run the converter with the following line :

MESHCONV MyShip_VMeshData MyShip_VMeshRef

If all goes well your new VMeshData segment will be written to the file 'newvdata' and 4 VMeshRef segments will be written to the files 'meshref01' - 'meshref04'.  


**All Milkshape groups as one object**
----------------------------------------------------------------------

Suppose you have a ship composed of the following Milkshape groups :

Mid Section
Front Section
Rear Section

Although the exporter will correctly output the VMeshData segment the VMeshRef segment does not contain Bounding Box (important for large objects) figures or number of vertices/referenced vertices (although this doesnt seem to matter for one object VMeshData segments).  To obtain the correct segments :

1.  Open your .cmp and export the VMeshData and VMeshRef segments (see above for details).  This time say they are called 'Largeship_VMeshData' and 'Largeship_VMeshRef'.

2. Open a command prompt and get to the directory where you have MESHCONV.EXE and the VMesh files.  As the default mode would split the model into 3 objects (one for each mesh) so you must use the /g switch to spectify groups manually :

MESHCONV Largeship_VMeshData Largeship_VMeshRef /g

You will receive the following prompts :

How many groups/objects in the model? : __ <--------- Enter '1' as the whole model codes for one object
Number of meshes in group 1 : __ <---------------------------- Enter '3' as all 3 Milkshape groups compose this object

The converter will then output the VMeshData segment to 'newvdata' (this should be identical to the original file 'Largeship_VMeshData') and the new VMeshRef segment to 'meshref01'.  Importing the new VMeshRef section into the .cmp is all that remains after this.


**Several objects with multiple meshes**
---------------------------------------------------------------------------

This time say you have a gun composed of the following Milkshape groups :

Base
Upper Base
Barrels
Barrel Viewports
Muzzels

Guns must be composed of at least two groups, the base which connects to the ship and rotates left/right and the barrel/gun which connects to the base and rotates left/right and up/down.  Connections between groups are dealt with in the Cmpnd node in the .cmp, see Templates section of this file for more details.  While it would be possible to declare all 5 groups as separate objects and join them this is far more work than just declaring and joining 2 objects.  So the structure we want is :

Base		}	Group 1
Upper Base	}	'Base'

Barrels		}	Group 2 
Barrel Viewports	}	'Barrel'
Muzzels		}

1. Export the model as a .cmp.  Extract the VMeshData and VMeshRef segemnts as files to the directory where MESHCONV.EXE is located.  Say the files are named Gun_VMeshData and Gun_VMeshRef

2.  As the model is being split into user defined groups the /g switch must be used.  To group the meshes as above use the command line:

MESHCONV Gun_VMeshData Gun_VMeshRef /g

You will receive the following prompts :

How many groups/objects in the model? : __ <--------- Enter '2' as we want the model to end as 2 .cmp objects
Number of meshes in group 1 : __ <---------------------------- Enter '2' as Group 1 'Base' spans the first 2 meshes
Number of meshes in group 2 : __ <---------------------------- Enter '3' as Group 2 'Barrel' spans the next 3 meshes

Remember for multiple Milkshape groups to comprise a single object in the .cmp they MUST be sequential in Milkshape so they are sequential in the .cmp.

The new VMeshData segment is written to the file 'newvdata' and two VMeshRef segments will be written - one called 'meshref01' (for the Base object) and one called 'meshref02' (for the Barrel object).


**Templates**
--------------------------

Included are blank .cmp files for a ship with destructable parts and a custom weapon model.  They are stripped down to mostly just the bare node structure you need along with any values which are constant.

To use BLANK_SHIP.CMP :

Set up your ship in Milkshape with destructable components defined as separate groups.  Depending on how many meshes form each destructable part follow one of the examples above until you have a new VMeshData file and a set of VMeshRef segments.

Open BLANK_SHIP.CMP in FLUtfEditor and import your new VMeshData segment to the VMeshLibrary -> YOURSHIPNAME.lod0.vms -> VMeshData node.  This template has space for the main hull and five destructable components.  Import your VMeshRef segments into the PARTX_lod1.3db -> Multilevel -> Level0 -> VMeshPart -> VMeshRef nodes.  I.e import meshref01 into the ROOT.3db.... -> VMeshRef node, meshref02 into the PART1_lod1.3db... -> VMeshRef node etc.  At this stage there is only one thing stopping the ship from being functional, the name of the ship in the VMeshLibrary node.  You must change this to "'name_of_first_group_in_your_model (Milkshape group name)'.lod0.vms".  This is because the VMeshRef segments reference this name and they will not find the VMeshData segment if the names dont match.  

You must now add your hardpoints.  I have left a standard set of hardpoints nodes under the ROOT.3db node (they are from the Battleaxe) to save you the hassle of creating and naming all the nodes.  Obviously you will have to copy the Position, Orientation etc. values from your original .cmp file.  Make sure to put Hps that attach to a destructable part under the relevant PARTX_lod1.3db node and not the ROOT.3db node or they will not be destroyed with the component.

It is probably a good idea to rename the PARTX... nodes to something better such as the their Milkshape names, so you know which part is which.  If you change the name of the .3db nodes you must make the same change in the relevant Cmpnd -> Part_PARTX_lod1 -> File name node.  Do not change the Object names.  They match object names in the Fix segment and if these are changed components dont take damage.

Now the .cmp file is set up fine.  Create your .MAT file as normal, you must use the supplied BLANK_SHIP.SUR file tho.  It is actually the .sur file from the Kusari Blood Dragon, which is where the Fix segment is stolen from.  Changing the object names in the Fix segment and matching that change in the Object name node means the parts are displayed correctly but dont take damage.  

For more details about this see : http://www.lancersreactor.com/t/forum/topic.asp?topic_id=21416&forum_id=29&Topic_Title=%2A%2ATUTORIAL%2A%2A+Ships%2FWeapons+w%2F+multiple+components&forum_title=Freelancer+Editing+Tutorial+Forum&cat_title=Freelancer+Editing&M=False


To use BLANK_GUN.CMP :

Again set up your gun in Milkshape as normal.  However the axis which your barrel group is to rotate on MUST be on the origin (x = 0, y = 0, z = 0) , otherwise the gun will not move properly.  Place HpFire0X hardpoints where you want the ammo to come from and an HpConnect hardpoint where the gun attaches to the ship.  Using one of the above examples obtain your new VMeshData and VMeshRef segments.  This time you must convert the model into two groups - the Base which rotates left/right and the Barrels which rotate up and down.  Import your 'newvdata' file to the VMeshLibrary -> YOURGUNNAME.lod0.vms -> VMeshData node.  Import the VMeshRef segment for the Base to the BASE.3db -> VMeshPart -> VMeshRef node.  Import the VMeshRef segment for the Barrels to the BARRELS.3db -> VMeshPart -> VMeshRef node.

Open the BASE.3db -> Hardpoints -> Revolute node.  There are two Hps, HpConnect and HpMount.  Open your original .cmp file and copy the position value from your original HpConnect hardpoint to the Position node under both Hps.    Open the BARRELS.3db -> Hardpoints -> Fixed node.  There are two Hps here, HpFire01 and HpFire02.  Use one/both of these, again copying the position value from your original .cmp to the new one.  You can add more HpFire nodes of your own depending on how many are in your model.

Guns seem different than ships in that the textures and materials are in the .cmp.  Fill the Material library and Texture library nodes as you would a normal .mat file.  The textures must be in .DDS format tho cause .TGAS just dont seem to work (even if the MIPS node is correctly renamed).  Rename the Material library nodes to match your Milkshape materials.

The gun is now ready to go.  Try swapping your new .cmp for a game one just to test it out.  


**** Questions/bugs/feedback etc : robbie@captain.ent or check out the TLR forums  *****