Intro

Howdy! At last, the first example upload from Gearbox to the Steam Workshop (with more to follow)…

Before I go into details about the example, I want to touch on how and why we’re using the Workshop this way.

The thought was that having a single user people could watch for uploads ([GBX]HWRM_Examples) would be easier for everyone - and by using Workshop we can update examples with bug fixes, extra details, and even larger changes if the toolchain is updated in a way that would force input data changes (new flags, etc).

As that’s the plan I would request that users of these Examples treat the actual paths they are stored to as Read Only. That way any updates we push won’t be destructive.

So - on to the meat of this

What’s Inside

This example focuses on the new ‘HODOR’ tool anyone looking to use our toolchain is going to get very friendly with. This package also contains 2 ‘raw’ data ships: The Kadeshi Swarmer and the Turanic Raiders Mothership (Carrier). These are the actual files used to create these objects in HW:RM.

It will take a rather long time to describe all of the features that HODOR contains - so the goal of this first example is to expose the community to the format and layout of our own assets - a format you will need to mirror in order to effectively make new HOD files.

Here then, is a brief list of the major elements to take note of in this data:

DAE - these files are the primary container for all scene data. That includes visible and collision meshes, LODs, material properties, nav lights, various markers, paths, etc. A single DAE can create a HOD with no other outside data aside from raw textures.

TGA - not surprisingly the TGAs contained in this example are the various surface maps required. Notice that these are not merged into final artwork (Spec/Refl/Glow in a single TGA) - but instead kept as individual files. There are a number of reasons for this, which will be expanded upon shortly.

HODOR - You can find this tool in your GBXTools folder if you have the Workshop toolkit. It is likely to be updated often (along with the scripts it depends on) - so it is best to leave it where it is and treat all files as read-only. When we cover the surface/shader system it will be clear how to adapt some of the inputs for your own use.

HODOR

HODOR itself does quite a few jobs:

Parses the DAE/TGAs and uses knowledge of the requested surface shaders (via SHADERS.MAP) to create a well-formed HOD with the requested image compression, surface layouts and properties.

Creates internal data (scar tables, etc) based on the contents of the DAE.

Handles animation data and creation of MAD files (details and examples coming after this info has had time to settle).

Using HODOR

HODOR is driven by a slew of command-line options, which can be provided on the command-line, but also via files which list them. This is a VERY large list, so for this first example, I’ll attempt to keep it relatively simple.

Internally HODOR keeps a list of symbols - these are strings that can contain other symbols - for example:

-$SHADER_MAP=$[HWRM_BASE]\GBXTools\HODOR\SHADERS.MAP

This command sets the SHADER_MAP symbol to be whatever HWRM_BASE is, followed by the path as shown. The command starts with ‘-$’ - which merely assigns the string, as-is. When code needs this symbol, it is parsed, and the HWRM_BASE symbol at that moment is resolved and burned into a fixed string. Another variant of the syntax would instead start with ‘-$$’ - this tells HODOR to resolve the string at assignment. This distinction may become important in later Examples when we cover things like folder scanning and parsing lists.

If typing a large number of these commands at a command-line sounds like torture, that’s because it is. So, to make things MUCH easier, HODOR will load the contents of a ‘params’ file and execute that from start to finish like so:

HODOR.exe -script=MyParams.hodor

Inside MyParams.hodor (your name my vary!) you could have:

## My HODOR Params - by Timmy = -$HWRM_BASE=C:\Games\Homeworld2 = -$SHADER_MAP=$[HWRM_BASE]\GBXTools\HODOR\SHADERS.MAP and so on...

Each line of a parameters file starts an ‘=’ sign to execute. Starting a line with ‘#’ creates a comment, and any line starting with ‘^’ immediately halts execution of that file.

A few other handy commands to know are:

-wait - when reached will wait for the user to press a key (great at the end of a long script)

-pause=X - halts for X seconds then continues

-echo=STR - prints STR - can contain symbols (which are resolved)

-do=COMMAND - causes a named command to execute (covered below)

-action=COMMAND - used to force the active action to something (relevant when making scan scripts) - often found after any -do

So, with ‘how symbols work’ out of the way, we can cover why symbols exist at all.

HODOR takes a series of commands that are executed in order, setting flags, symbols, and performing actions. Actions are the things that require and respond to the value of specific symbols at the time of the actions execution. This example will cover a single action:

Convert

-do=convert

Convert is used to take an input file ($CONVERT_IN) and create an output (file/files) ($CONVERT_OUT). These are really the most important and most basic symbols. However, many others are used during parsing - which I will list in brief below:

$CONVERT_IN - The input file (a .DAE in this case)

$CONVERT_OUT - The output file (a .HOD in this case)

$SHADER_MAP - A path to the SHADERS.MAP being used

$SHADE_OPT_LOADDAE - A list of flags for options during DAE load

$HOD_SAVE_OPTS - A list of processing steps and values to apply during save

For example:

## My HODOR Params - by Timmy = -$HWRM_BASE=C:\Games\Homeworld2 = -$SHIP_NAME=Kad_Swarmer = -$SHADER_MAP=$[HWRM_BASE]\GBXTools\HODOR\SHADERS.MAP = -$SHADE_OPT_LOADDAE=Force8888 = -$HOD_SAVE_OPTS=ForceScars FilterScars=thruster,bay = -$CONVERT_IN=$[HWRM_BASE]\GBXTools\ShipExample\$[SHIP_NAME]\$[SHIP_NAME].DAE = -$CONVERT_OUT=$[HWRM_BASE]\MyMod\Ships\$[SHIP_NAME]\$[SHIP_NAME].HOD = -do=convert = -action=null = -wait

And there you have it (with some attention paid to how your paths vary!) - a script that will tell HODOR to locate and convert ‘$SHIP_NAME.DAE’ to ‘$SHIP_NAME.HOD’ wherever you’d want it to end up!

I’ll expand this Example later with more info, a larger set of flags for options, and a much more verbose explanation of the things that should exist inside a valid .DAE - for now the existing .DAEs should give plenty for the community to chew on!