Overview: Levels

The intent of this article is to describe both how levels used to work in the Homeworld 2 paradigm and how they currently work in Homeworld Remastered. If you spot any inaccuracies, omissions, typos, or out of date info feel free to contact me, Siber/EatThePath, about it, or as this is on a wiki edit it yourself to correct it. Letting me know is still preferred so I can verify and also learn myself, but the option is there.

How it used to work
Levels were found in subfolders of data/leveldata/multiplayer, each folder representing the levels used by one or more game rules. Each level is a .level lua file, containing the following components


 * leveDesc: String, name of the level
 * maxPlayers: Integer, number of players supported
 * player: Array, contains tables of information about the player slots. Note: 0-index, not 1-indexed like a lua array
 * players[i].id: Integer, player number, should match array index
 * players[i].name: String, the name of the point used as their start position
 * players[i].resources: Integer, amount of default starting resources
 * players[i].raceID: Integer, uncertain, guess default race for that slot
 * players[i].startPos: Integer, uncertain, guess the starting position number associated with this slot data.
 * DetermChunk * Function, contains gameplay-relevant map construction logic. See http://hw2wiki.net/wiki.hw2.info/ScopeLevel.html
 * NonDetermChunk * Function, contains aesthetic and audio level data. See http://hw2wiki.net/wiki.hw2.info/ScopeLevel.html

How it works now
The level file them selves are largely unchanged, with one exception:


 * players[i].raceName: String, replacing the raceID value. Due to changes to the race system, indexes are no longer appropriate.

Beyond that, level files are no longer read directly by gametypes while on the menu screen. Instead, .levels files found in data/leveldata/multiplayer/ contain tagged lists of levels. These lists are scanned and filtered by their tags to populate the level selection, and level files are left alone until being actually loaded. Level files at present seem unchanged, and are still typically located in the same places as before, but the .levels file contains a path suggesting that levels could be placed anywhere in a mod directory if so-desired. .levels files contain the following


 * Root: String, contains the path to the directory containing .level files
 * ExtFilter: String, the filtering tags for the level set. Some day there should be an Overview: Filtering article, but for now see http://forums.gearboxsoftware.com/t/mod-filtering-just-say-no-to-hacked-files/539459 for information and discussion
 * Tags: String, tags that apply to all levels.
 * LevelList: Table, contains tables of data for each level included in the set
 * LevelList[i].Tags: String, tags that apply to this level individually
 * LevelList[i].Name: String, filename of the level, not including extension. "4p_ironcurtain" rather than "4p_ironcurtain.level" for instance.
 * LevelList[i].Desc: String, displayed name of the level.
 * LevelList[i].MaxPlayers: Integer, number of players supported by the map.

So any mod with custom levels will need a new .levels file listing them, and that should be it. The stock game currently has dm_hw1.levels, dm_hw2.levels, and testmaps.levels, so other names should be used to avoid collisions