Homeworld 2 continues the epic struggle of the Hiigarans and their leader Karan S'jet. Many thought their hardships would end when they returned to Hiigara, yet fate has not been so kind to the Exiles. Now the Hiigarans face a new and bitter enemy, a renegade clan from the eastern fringes of the galaxy, who wield the power of the ancients. Homeworld 2 chronicles the valiant journey of the Mothership and its crew into the oldest regions of the galaxy to confront their new foe and discover the truth behind their exile.

Post tutorial Report article RSS Feed Setting up a New Race

Almost always the basic goal of most modders, to add a whole new race to Homeworld 2, but how? Well, for all you newcomers to Homeworld 2 modding, I am about to show you the basics.

Posted by Mr.Grim on Jul 30th, 2006
Basic Client Side Coding.

Almost always the basic goal of most modders, to add a whole new race to Homeworld 2, but how? Well, for all you newcomers to Homeworld 2 modding, I am about to show you the basics.

[page=The Race.lua File]
The File
Ahh yes, the Race.lua file. Where it all begins. Before you add your new ships, weapons, etc. you need to define the name, prefix, and hyperspace effect/time. Now, I assume you know how to extract the necessary files. The Race.lua file can be found in the scripts folder. Now open it up. It should look similar to this:

NotPlayable = 0
Playable = 1

races =
  	{"Invalid",  "Invalid", "", "", 0, NotPlayable,"" },
	{"Hiigaran", "$1100", "hyperspace_gate", "etg/special/SPECIAL_ABILITIES_HYPERSPACE_IN", 9.5, Playable,"HGN_"},
	{"Vaygr",    "$1101", "hyperspace_gate_vgr", "etg/special/SPECIAL_ABILITIES_HYPERSPACE_IN", 9.5, Playable,"VGR_"},
	{"Keeper",  "$1102", "hyperspace_gate_kpr", "etg/special/SPECIAL_ABILITIES_HYPERSPACE_IN", 12.5, NotPlayable,"KPR_"},
	{"Bentusi",  "$1103", "hyperspace_gate_bentusi", "etg/special/SPECIAL_ABILITIES_HYPERSPACE_IN", 18.5, NotPlayable,"BEN_"}, 
	{ "Random", "$3226", "", "", 0, Playable, "", }

Before you add anything, please keep in mind not to delete any of the existing races, unless you plan on replacing them. Their is also a limit on how many races you can add on. I am not certain, but it is about 2-3 extra races.

The Breakdown
Now, if you just want to make one of the existing races playable, it's a fairly easy change. Just change "NotPlayable" to "Playable" for that race. Now, to add an extra race. Just add:

{"US Navy",  "US Navy", "hyperspace_gate", "etg/special/SPECIAL_ABILITIES_HYPERSPACE_IN", 9.5, NotPlayable,"USN_"}, 

Now, to break that down. This is a basic breakdown for the code we added:


: The name of your race.
: The name of the race displayed in-game.
: The type of hyperspace gate to use. (etg. gold, green, blue)
: The amount of time (in seconds) for the effect to last.
: Is the race playable by the user? (Yes = Playable; No = NotPlayable)
[code]: The prefix used for your race. (etg. Kpr_, Hgn_, etc.) Should reflect your races name.
[page=The Ships Folder]
Okay, so you have you new race defined, but it still needs ships. So you have the models or ship files ready, time to put them into the Ships folder. In here is where all the ships in the game will be stored. To add a new ship to your new race, make a new folder and name it USN_Destroyer. You can change it to what ever you like, but it has to be . (etg. Kpr_Destroyer, Hgn_Scout, etc.) Inside the folder, the *.ship, *.events, and *.hod files (and the *.madstate and *.mad files if your ship contains animation). They should be also named the same way as the folder.

That about wraps up the ships.

[page=The StartingFleets Folder]
Okay, so your race is defined, you have ships...but when you start a game, what do you start out with? The StartingFleets folder is where all the information is kept. If you notice that the existing files are named in a specific way. 00.lua (that?s the number "0", not the letter "O"). If you open up the vaygr00.lua file, you will see this:
[code]PersistantData = {
StrikeGroups = {
Squadrons = {
type = "Vgr_MotherShip",
subsystems = {
shiphold = {
name = "",
size = 1,
type = "Vgr_ResourceCollector", -- ship name
subsystems = {
shiphold = {
name = "",
size = 1, -- only 1 in each squadron
number = 6, -- start with 6 of these
type = "Vgr_Carrier",
subsystems = {
shiphold = {
name = "",
size = 1,
number = 1,
Research = {
As you can see, the comments explain the code. You can just change the code to the appropriate ship name, number, and squadron size.

[page=The Building and Research Folder]
The Folders and Files
So, you have your race, your ships, and the starting fleets, but you still need some build and research options, as the game would be boring without those. Everything is located in the Building and Research folder. Inside, you will see more folders. These are for each race. When adding a new race, just copy and paste one folder, and re-name it to your races name. Inside this folder will be two files, build.lua and research.lua. I think you know which one is for which.

The Build.lua File
If you open it up, it will be pretty long. I won't post he whole this, just a small snippet.
Type = Ship,
ThingToBuild = "Vgr_CommandCorvette", -- the name of the ship
RequiredResearch = "CorvetteCommand", --which research(s) are required. (use "|" for "or" and "&" for "and")
RequiredShipSubSystems = "CorvetteProduction", -- required subsystem(s) to build. (use "|" for "or" and "&" for "and")
DisplayPriority = 110, -- order displayed in the UI menu. smaller numbers being on top.
DisplayedName = "$7144", -- name to be displayed on the build menu
Description = "$7145" -- description of the ship in the build menu
The comments in the code should explain the function of each line.

The Researc.lua File
Now, the other file.
Name = "CorvetteTech", -- the name of the research item
RequiredResearch = "", -- list of prerequisite research items
RequiredSubSystems = "Research", -- list of prerequisite sub systems
Cost = 500, -- cost of the research item
Time = 40, --time (in seconds) to fully finish research
DisplayedName = "$7176", -- name displayed on the UI menu
DisplayPriority = 20, -- order displayed in the UI menu. smaller numbers being on top.
Description = "$7177", -- description in the research menu
TargetType = Family, -- only used if upgrades all ships within this family
TargetName = "Corvette", -- name of the family or ship
Icon = Icon_Tech, -- icon to use (listed at the top of the Research.lua file)
ShortDisplayedName = "$7180", --short name used in the games UI
I hope the comments in the file have explained it well enough.

[page=Hints and Tips]
That's all their is to setting up a new race. Here are some hints, tips and links to help you out.

Look for existing patterns
When adding in a new ship, try to add it in a way similar to that of what is already there. It will help ensure that it works.

Check for typos
This is the most important thing to remember, a single extra or missing letter, comma, or bracket can make the whole file useless. It has caused me so much trouble at times. It can save you allot of trouble to do it right the first time, even if it takes a little extra time or work.

If you?re stuck, ask for help
It's as simple as that, their are plenty of forums out their who can help. A great place to ask is at Relicnews Forums, a great community of Relic games and their mods.

Other Homeworld tutorials by me
Make sure to check out my Enable AI to Build New Ships tutorial. Their are more to come. :)

Post comment Comments
djphild Aug 24 2006 says:

Ok. So im brand net to this whole modding business. i was reading the tutorial "setting up a new race" for homeworld 2 and i cant seem to find the race.lua file.

any help will be greatly appreciated.


+1 vote     reply to comment
Augis Nov 29 2006 says:

How to create lua file?

+1 vote     reply to comment
djphild Aug 25 2006 says:

Please disregard the previous post as I have found the necessary files and folders to mod my game. For those who dont know where to get them, click on the link below.




+1 vote     reply to comment
C-ie-K Sep 2 2006 says:

Its in the homeworld2.big file (in your data folder). but you wil need a big extractor. all tools cn be find here Wiki.hw2.info . try it


+1 vote     reply to comment
EhraniNavy Oct 12 2006 says:

The race.lua file should be in data:scripts/race.lua where data is the data folder from homeworld2.big (if you extract the big or dl a pre-decompiled big).


+1 vote     reply to comment
RINGLEADER Oct 15 2006 says:

how would u set up the resaourcing for the keepers, would you have to change the hardpoints?

+1 vote     reply to comment
RINGLEADER Dec 8 2006 says:

why does it shw my name when you type in HOMEWORLD 2 RINGLESDER it brings you to theis site

+1 vote     reply to comment
Lordkeroth Jul 16 2009 says:

hey I followed your thing and my game crashes whenever I try to play as them.
I took a race made in another mod and added them to the warlords mod any Idea how to make the new race work?

+1 vote     reply to comment
HornetS Oct 5 2009 says:

what do i use to open the race file?

+1 vote     reply to comment
HornetS Mar 27 2010 says:

never mind... how do I get the hod files? I downloaded the files from the internet but they don't include the .hod files.

+1 vote     reply to comment
Peacevan Apr 26 2012 says:

So I added a new race in the race.lua file just like you did but whenever I try to play as this race my game crashes at "Universe" on the loading screen. Any light to this issue?

+1 vote     reply to comment
Post a Comment
click to sign in

You are not logged in, your comment will be anonymous unless you join the community today (totally free - or sign in with your social account on the right) which we encourage all contributors to do.

2000 characters limit; HTML formatting and smileys are not supported - text only

Homeworld 2
Windows, Mac
Custom Built
Send Message
Official Page
Release Date
Released 2003
Game Watch
Track this game
Report Abuse
Report article
Related Games
Homeworld 2
Homeworld 2 Single, Multiplayer & Co-Op Real Time Strategy
Related Groups
Sierra Entertainment
Sierra Entertainment Developer & Publisher