[EXAMPLE] Ships #1

(BitVenom) #1


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 :smile:

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 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).


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:


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
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 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
= -$HOD_SAVE_OPTS=ForceScars FilterScars=thruster,bay
= -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!

Needing help starting a mod
How to fix the support frigates and repair corvettes
[TUTORIAL] 3DSMax - Getting a simple ship in game
HODOR/RODOH crash on open
Blender DAE Exporter for HWRM
[TUTORIAL] Blender - Getting a simple ship in game
[MOD] Homeworld 2 : The Dark Wars: Update: Campaign missions needs testing!
Modding tutorials Master Thread
EXAMPLE - Ships #1
First Update coming to Homeworld Remastered Collection
Map editor & mission editor
(Botman) #2

The URL for this Steam workshop example is:


…and after you subscribe to it and download it, the files will be in the following folder on your PC, assuming you use the default Steam install location of “C:\Program Files (x86)”…

C:\Program Files (x86)\Steam\SteamApps\workshop\content\244160\403557412

(BitVenom) #3

Update 3/7/2015

A few points and clarifications:

  • The exact material layout in the DAE isn’t important, HODOR really only cares about the XXX_DIFF files - and uses those (and the requested shader) to determine which source files with other extensions (_TEAM, _STRP, etc) are actually needed.
  • Inside the .DAE specific node names are required to define structures (often starting with HOLD_), others however are defined by the parameters found in their name.
    – Parameters are in the form of XXX[Value], and chained with underscores.
    – At times these may be optional and have reasonable defaults, other times each value is mandatory. Documenting this will take ages, though it may happen. Generally following the ‘style’ seen in an existing item is the best way to work.
  • Compression for a given material is defined in the Material’s name:
    FMT[Format] - valid formats (for now) are:
    – 8888 - Uncompressed 32bit TGA, give or take.
    – DXT1 - RGB 1/4 compression (565 baseline bpc)
    – DXT3 - RGBA 1/2 compression (4 bits per channel)
    – DXT5 - RGBA 1/2 compression (like DXT1 plus alpha)
  • $SHADE_OPT_LOADDAE has many flags:
    – ForceMAP - Force compression based on the settings in the SHADERS.MAP
    – Force8888/DXT1/DXT3/DXT5 - Ignore all other preferences, use Format X
  • $HOD_SAVE_OPTS also has many flags…
    – noOptimize - Don’t strip the HOD of unused junk, extra data, invalid materials, etc.
    – ForceScars - Force every surface to be considered for Scar mapping.
    – FilterScars=XXX - Remove any surface with the shaders named in XXX (comma separated) from the Scar list (scars on thrusters and bays look dumb!)
  • $HOD_OPTIMIZE_OPT is used when optimizing
    – noGoblins - Strip Goblins (defaults to allow Goblins)
    – StripJunk - Find and remove unused or invalid stuff (defaults to false)
    – Unbadge - Looks for ‘old’ single UV badge materials and attempts to re-stitch the badges into the surrounding base-material UVs - remapping the material, but adding a 2nd UV with the 0->1 box for the badge itself. Saves time when it works, goes CRAZY when it doesn’t. (defaults to disabled)
    – LOD_Min=X, LOD_Max=X - Allows removal of unwanted LODs or even skipping of higher LODs

That’s all for now :slight_smile:

[TOOL] Hodorest - Hodor GUI
Example ships hardpoints
[TOOL] Hodorest - Hodor GUI