Tutorial; First Steps - HWRM/KarosGraveyard GitHub Wiki
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.
- 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"
- The files we're after are the
xxx.big
files located inC:\Program Files (x86)\Steam\steamapps\common\Homeworld\HomeworldRM\Data
. I prefer to copy these intoArchive.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 inHW2Ships.big
. I'll go forwards with this as an example. - 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.
- 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.
- Open up
hgn_ioncannonfrigate.ship
in your favourite editor (I recommend VS Code, or at least Notepad++) - 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.
- 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:
- Go to your
Steam -> Library
and right click on HWRMProperties
->Set Launch Options...
- 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.
- 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:
- Lua 4 Manual (HWRM use Lua 4)
- Homeworld Discord
Finally, good luck!