Development:Tools:UnitConverter

Introduction

Raising from the stone age of workflows, in which every task, from texture conversion to editing of unit stats, had to be accomplished manually and only by quite knowledgeable magistrates who new the alchemy of units.csv columns, xmesh files, and had a magic with meshers. Now, UnitConverter shines upon us, still in the distance, but unmovable like a beacon on solid rock, to be the church of the artists, to accommodate the apostles of Blender, CineMut, and LaGrande, to bring the holy spirit of salvation to this compassionate universe of ours.

Quick Start Guide

Configuration

You must first configure the paths under Config including the application in the path:

• path\data (to edit unit stats)
• path\vegastrike.exe (to view model in Vega Strike)
• path\mesher.exe (to convert model to bfxm)
• path\nvcompress (to compress textures)

(There is no need to set the working dir, as this field is purely informational)

Integrating Models

Assuming you have exported:

• ship mesh to Ship.obj
• shield to Ship-Shield.obj
• helpers to Ship-Mounts.obj

... the steps to convert your model are:

• In UnitConverter, under "Model" add all three obj files to workspace.
• Then select the main Ship model in the drop down.
• Under "Textures" you add the ones you have provided.
• Press "Save and Convert"
• Press "Convert Textures"
• Press "Copy Data"
• Under "Unit" press "Save"
• Under "View" press "View"

This will call vegastrike and the modelview.mission with your new unit enabled.

Converting Hud Image

Under "HUDImage":

• Open the "Ship-hud.png" image using the "..." button
• Press "Convert Image"
• Press "Copy Data"
• Under "Unit" press "Save"
• Under "View" press "View"

Using Uncompressed Images

• Under "Config" check the "Bypass compression" option.
• Under "Textures" press "Save and Convert"
• Press "Copy Data"
• Under "View" press "View"

Adding Thruster, Docks, Mounts

• Under "Model" press "Add Model"
• Select the "Ship-Mounts.obj" file with your mount markers.
• Under "Unit" and "Unit2" review the stats
• Under "Unit" press "Save"
• Under "View" press "View"

Editing Stats

• Under "Unit", in "Unit name" write the units.csv key (e.g. Llama.begin)
• Press "Load"
• Edit fields under "Unit" and "Unit2"
• Under "Unit" press "Save"

Getting Help

In case of problems, please report to the Unit Converter thread.

UnitConverter Tool

Requirements, Installation and Starting

The only requirement to run UnitConverter on your system is to have Python 2.5 installed on your system. No additional libraries are required.

You can download the latest version of UnitConverter from the Vega Strike svn repository trunk/modtools/UnitConverter.

To install, copy all files to a directory of your choice.

To run UnitConverter, open command line/shell, change to the installation directory, and depending your operating system type (without the ">" which denotes the command line prompt:

Windows:

> uc

Linux:

> ./uc

Other:

> python unitconverter.py

First thing you'll need to do is to configure the paths for Vega Strike data directory, mesher and nvcompress.

Models Workspace

Models Workspace Screen:

The following operations are available:

• Clear Workspace - to start a new model integration
• Add Model - to add a new model to workspace. The following files are accepted:
  • .obj file containing the model mesh
  • ?-Shield.obj file containing the shield mesh
  • ?-Marker.obj file containing the marker objects as described in the objects marker modeling section
  • .bfxm files to backward convert meshes to obj files
• Clear Model - to remove the selected model from the workspace
• Load Workspace - to load an .ini configuration file of the workspace
• Active Model - change active model on the dropdown to edit its textures

It is important that your first model in workspace should be the main model, as further information like directory name and units.csv entry name will be derived from the main model name.

Under Model/Files the .obj and .mtl files for the active model will be displayed. Under Material Info you can find information on the .obj file's material library and material names.

To edit texture assignments, proceed to the Textures tab on the left.

Textures

Textures Screen:

In this tab you can assign textures to model submeshes:

• Under Submodels select the submesh you'd like to assign textures to. By default the first submesh is selected when the model is activated.
• Add the available Textures 0-5 by pressing the ... buttons between the Input Texture and Output Texture columns and browse to the appropriate file. The output texture name will be set (naming convention: tex_model_submodel_texture.texture)
• Select the appropriate Technique, i.e. leave it empty for conventional shading approach or choose e.g. cinemut_opaque if your input textures are provided with CineMut shader family compatible packing.
• Select Blend mode.
  • For main meshes leave it at ONE ZERO
  • For shield mesh and blink light submeshes choose ONE ONE

Once you have assigned textures to all your submeshes, you can now start the conversion:

• Press Save and Convert to save the texture assignment information and convert your model to Vega Strike compatible bfxm format.
• You may Compress Textures using nvcompress if you have configured the command path previously
• Finally, 'Copy Data will copy textures and bfxm files to the unit directory

To add the HUD image, proceed to the HUDImage tab on the left.

Advanced Usage - Converting faction textures

Faction textures must follow the naming of the default textures with prefixed faction name. When your default diffuse texture is dif.png and tex_000.texture, the faction input and output textures for the Uln faction will be uln_dif.png and uln_tex_000.texture and so on for all the other textures and factions.

Unit converter can assist you with DDS conversion of the input textures provided the naming convention is followed. To convert a faction texture:

• Select the Faction from the drop down, then
• Compress Textures, and when done
• Copy Data to put the faction textures into the unit data directory

HUD Image

HUD Image Screen

Adding a HUD image to the data is fairly easy, simply:

• Browse for the image using the ... button. The appropriate entry will also be created in the Unit editor.
• Compress Image to make it DDS, and
• Copy Data to the unit data directory. This button evokes the same command as the one on the Textures tab. This means, the image, sprite, bfxm, and texture files will be copied together.

To edit the unit properties and parameters, proceed to the Unit tab on the left.

Unit Editor

The Unit Editor provides facilities for editing your most important parameters of the unit:

• Load - loads the unit parameters
• Save - saves the edited parameters
• Reset - reloads unit parameters for active model without previously saving changes

The most critical parameters for successful integration of the unit are:

• Unit description - the text that will be displayed in-game about the unit
• Unit type and Unit role - used in-game and to correctly view vessels and installations as such
• Under Unit dimensions you will find the
  • Dimensions as derived from the obj mesh file.
  • To bring the model up to the expected scale, you'll need to set the Scale parameter. The final size of the model in-game will be the multiplication result of dimensions and the scale.

The remaining entries will be created from your marker object:

• Engine Thruster will be derived from markers named engine_*. You may Update the Thruster type to a different than the default one (supernova.bmp.bfxm).
• Turrets & Subunits will be derived from markers named turret_* or subunit_*. You may browse the Subunit nr. (number) by using the < and > buttons and change the turret type from the Subunit type dropdown and confirmation by Update.
• Docking Ports will be derived from markers named dock_*

To continue editing unit parameters, proceed to the Unit 2 tab on the left.

To add upgrades, under Upgrades' select the Upgrade class and Upgrade type and then Add Upgrade to the unit. To delete an upgrade, simply remove the entries between (and including) the {} brackets.

All other parameters on this tab and the following Unit 3 tab can be manually edited

Don't forget to actually Save your changes before proceeding to View the unit in-game.

Advanced Usage - Independent Unit Editor

You can use built-in Unit editor of the Unit Converter to edit units without having to load the mesh files. To do so:

• On the Model tab do Clear Workspace
• On the Unit tab, manually write the unit key under Unit name
• Load the unit parameters

You can also browse the units.csv file by using the < and > buttons on the sides of the Unit name to row-wise move back and fore between the entries. Browse, Load/Save buttons are also available on Unit 2 and Unit 3 tabs.

Configuration

About