Tutorial; First Steps - HWRM/KarosGraveyard GitHub Wiki

Original by Fear

Also see a video version of the same topic.

Getting into modding can be pretty daunting. Many guides are out of date, or use outdated tools. This is a very terse step-by-step which will work with HWRM v2.1 on Windows 10/11 with Gearbox-only tooling.

Homeworld Remastered Toolkit

Go to Steam -> Library -> Tools and install the Homeworld Remastered Toolkit. This package includes all the tooling necessary to begin modding, as well as some extra stuff.

The tools will be installed to C:\Program Files (x86)\Steam\steamapps\common\Homeworld\GBXTools\.

Extract Data

Within the \GBXTools\WorkshopTool\ directory exists Archive.exe. This is a command-line tool which can do various things with the compressed data files that store HWRM's moddable data.

  1. Open any Command Line Interface (CLI) on your machine (such as the Command Prompt), and cd into Archive.exe's location:
cd "C:\Program Files (x86)\Steam\steamapps\common\Homeworld\GBXTools\WorkshopTool"
  1. The files we're after are the xxx.big files located in C:\Program Files (x86)\Steam\steamapps\common\Homeworld\HomeworldRM\Data. I prefer to copy these into Archive.exe's directory as it makes the commands much simpler. You can play around with it as you get more comfortable though. When modding, you only need to keep the files you actually want to change - do not bother to include any files you aren't modifying. That means if you want to make changes to a HW2 ship, you're only going to be interested in HW2Ships.big. I'll go forwards with this as an example.
  2. Extract the contents of the big into a folder:
Archive.exe -a {{bigfile}} -e {{folderpath}}

Example:

Archive.exe -a HW2Ships.big -e my_mod

Repeat this step as necessary to add more data to your mod folder.

  1. At this point we should delete any files we're not interested in modifying. If I only cared about making ion frigates twice as fast, I could delete every other file except my_mod\ship\hgn_ioncannonfrigate\hgn_ioncannonfrigate.ship as this is the file I'll need to change.

Start Modding

Let's continue from the example above, and say I want to modify the Hiigaran ion cannon to fly twice as fast. I've already removed all the other files so my mod is essentially only comprised of my_mod\ship\hgn_ioncannonfrigate\hgn_ioncannonfrigate.ship.

Before we can start, we'll also need to add an empty file called keeper.txt to the root directory of our mod like so: my_mod\keeper.txt. This file allows the game to identify where to index data from.

  1. Open up hgn_ioncannonfrigate.ship in your favourite editor (I recommend VS Code, or at least Notepad++)
  2. Modify these lines:
NewShipType.thrusterMaxSpeed=165
NewShipType.mainEngineMaxSpeed=165

to:

NewShipType.thrusterMaxSpeed=330
NewShipType.mainEngineMaxSpeed=330

FYI: The difference between thruster and main, is that truster is the strafing speed of the ship, whereas main is the forwards speed of the ship! Since these values were identical before, let's keep them that way.

  1. Save the file. This is a working mod! Now we have to run it.

Test Your Mod

To run a mod locally in HWRM without needed to publish it for the public, we can use launch options. To do this:

  1. Go to your Steam -> Library and right click on HWRM Properties -> Set Launch Options...
  2. Add the following:
 -moddatapath GBXTools\WorkshopTool\my_mod

You can move your mod around, but keep in mind the game begins its search from the root directory Homeworld folder.

  1. Launch the game to see your changes!

When you're happy with your mod and want others to be able to subscribe to it on Workshop so they can play it too, you'll need to publish it. See the Workshop Guide to do so.

Further Reading / resources

This was a quickstart guide to modding. In reality, to bring something to life, you'll need to be ready to spend quite a bit of time learning how modding for this game works. Depending on the feature, you might need to change a few lines, or hundreds - it's also possible that what you want is impossible!

Karos is an invaluable resource, containing many tutorials and importantly documentation on available functions.

Don't forget you can decompile other people's mods using Archive.exe to see how they work.

With that said, it's dangerous to go alone, take these:

Finally, good luck!