Guide to porting Gearbox (PC) maps to Xbox - SnowyMouse/invader GitHub Wiki
This document is a guide for porting Halo PC maps to Xbox using Invader. The Xbox version uses an older version of the Halo engine than the Gearbox engine. It is also far more optimized for systems with limited storage and memory. As such, the limitations are more strenuous than on Gearbox. Various things have also been changed, so things like HUD meters, multipurposes, and model tags will have to be converted. For maps that use the stock tagset from the HEK, this is mostly trivial since you can use many of the Xbox tags which are already formatted correctly. Otherwise, you may have to perform several conversions.
Table of contents
Key differences between Xbox and Gearbox Halo
Tag space limits
Xbox Halo has a 22 MiB tag space limit (slightly higher on some localizations of the game). It also puts model data in the tag space, further limiting the amount of tags you can have. Large font tags, animation tags, models, collision geometry, and BSPs can result in this tag space being exceeded fairly easily, although models and BSPs use compressed vertices which take up less than half of the space of uncompressed vertices.
Gearbox Halo, on the other hand, has a 23 MiB tag space limit, and model data is put into a separate buffer. This means you'll have around 3-6 MiB less tag space on Xbox than you would on the PC version of the game.
File size limits
Xbox Halo has a fixed file size for uncompressed cache files:
- 278 MiB for singleplayer maps
- 47 MiB for multiplayer maps
- 35 MiB for user interface maps
One of the most common reasons a map will not work is because these limits are exceeded. Attempting to load a map that exceeds these limits will result in the game crashing. Invader will also refuse to build such a map unless you pass -E to invader-build, which basically puts the onus of that map working on you.
You can work around the multiplayer limit by setting the 16-bit integer at offset 0x60 in the map file to 0. This will force the game to store it in a singleplayer cache rather than a multiplayer cache. You cannot work around the user interface or singleplayer limit with this.
It's worth noting that the demo from the Official Xbox Magazine can be trivially modified to accept larger caches, but this version of the game does not support multiplayer. The offsets for the user interface limits are at 0x37B57, 0x37BE5, 0x37C0D, 0x37C28, 0x38934, 0x38C00. The offsets for the singleplayer limits are at 0x37B46, 0x37BD4, 0x37BFB, 0x37C17, 0x38922, 0x38BEF. These are set to 23 MiB (0x1700000) for user interface and 215 MiB (0xD700000) for singleplayer, which is only just large enough to hold ui.map and b30.map, respectively, but they can be modified to use a higher value. Take care that there is only a limited amount of space on the cache partition.
Globals
Xbox globals properly references bitmaps such as the goo effect. The Gearbox version, on the other hand, references a number of extra weapons, sounds, and vehicles that would waste tag space on Xbox since they would go unused. Therefore, it is recommended to use an Xbox globals tag.
UI widgets
Each version of the game use their own set of UI widget definitions. The Gearbox version, for example, has online multiplayer, and the entire menu system is intended to be navigated with a mouse. The Xbox version, on the other hand, has system link and co-op, and the entire menu system is intended to be navigated with a controller, complete with button prompts and a virtual keyboard that is interacted with using a controller.
Models
Xbox uses model tags and Gearbox Halo uses gbxmodel which has local nodes. Invader will refuse to compile a map that uses the wrong model type.
Converting
Use invader-convert to convert between gbxmodels and models.
$ invader-convert -T gbxmodel-to-model -t <input-tags-dir> <tag-path.gbxmodel>
Refactoring
Use invader-refactor to change all gbxmodel references to model. Note that all Halo Editing Kit tools (i.e. Sapien, Guerilla, tool.exe) will automatically associate model as gbxmodel.
$ invader-refactor -M no-move -t <input-tags-dir> -t <output-tags-dir> -c gbxmodel model
Sound formats
Xbox Halo cannot decode Ogg Vorbis, and it will refuse to play uncompressed 16-bit PCM. Such tags will have to be re-encoded as Xbox ADPCM.
Converting
You can use last-resort to convert these tags if you do not have source data.
$ last-resort -T sound-to-xbox-adpcm -t <input-tags-dir> -o <output-tags-dir> <tag-path.sound>
Shader differences
Besides a number of bugs introduced into the Gearbox renderer, there are some actual technical differences between Xbox and PC shaders.
HUD meters
The channels used for HUD meters are flipped. As such, HUDs made for the Gearbox version are not compatible with the Xbox version and, as such, will not work correctly without conversion.
| Usage | Xbox channel | Gearbox channel |
|---|---|---|
| Mask | Alpha | Luminosity (RGB) |
| Meter | Luminosity (RGB) | Alpha |
Note: Technically, the Xbox version treats the blue channel as luminosity and ignores everything else, but you should use white to take advantage of monochrome's lossless space savings (50% for A8Y8 and 75% for A8, Y8, and AY8) over 32-bit.
The mask defines the shape of the meter. The meter the portion shown when the meter is at a given value.
Converting
You can use last-resort to convert HUD meters.
$ last-resort -T hud-meter-swap -t <input-tags-dir> -o <output-tags-dir> <tag-path.bitmap>
shader_model
One feature of shader_model tags is that they can have multipurpose bitmaps. However, the channel order is different on each version of the game.
| Usage | Xbox channel | Gearbox channel |
|---|---|---|
| Auxiliary | Alpha | Red |
| Specular/detail mapping | Red |
Blue |
| Self illumination | Green |
Green |
| Color change | Blue |
Alpha |
Using a bitmap in the wrong channel order will cause issues with the appearance of the shader, so these will require conversion.
Converting
You can use last-resort to convert multipurpose bitmaps.
$ last-resort -T multi-gbx-to-xbox -t <input-tags-dir> -o <output-tags-dir> <tag-path.bitmap>
shader_transparent_chicago_extended
In order to support fixed function cards, Gearbox added a class shader_transparent_chicago_extended. These tags are functionally identical to shader_transparent_chicago except that they have a separate two stage maps for when the fixed function renderer is used. It is not worth supporting the fixed function renderer as it is completely broken, anyway, so shader_transparent_chicago_extended should be considered deprecated.
Xbox Halo does not support shader_transparent_chicago_extended tags, and Invader will refuse to build an Xbox map with them. It is advised to convert these to regular shader_transparent_chicago tags, instead, and re-reference them. Or, if there is a shader_transparent_generic version of the tag, you should use that instead as it is often times a better version of the shader.
Converting
invader-convert can be used to convert shader_transparent_chicago_extended tags into regular shader_transparent_chicago.
$ invader-convert -T chicago-extended-to-chicago -t <input-tags-dir> <tag-path.shader_transparent_chicago_extended>
Refactoring
You can use invader-refactor to change all shader_transparent_chicago_extended references to the shader_transparent_chicago, if such tags are present.
$ invader-refactor -M no-move -t <input-tags-dir> -t <output-tags-dir> -c shader_transparent_chicago_extended shader_transparent_chicago
shader_transparent_generic
Gearbox removed the shader_transparent_generic shader from the game. This shader is used for a number of visual effects that cannot be properly replicated using any of the other shader tags. Gearbox Halo will not render anything if this shader is used, and Sapien will spam itself with errors, causing it to become unusable due to the lag. It is recommended to re-reference any shader_transparent_chicago and shader_transparent_chicago_extended tags as shader_transparent_generic with invader-refactor, as they are often times a better version of the shader.
Refactoring
You can use invader-refactor to change all references to the better tag class if they're available.
This will change all shader_transparent_chicago_extended references to shader_transparent_generic if the generic tag exists.
$ invader-refactor -M no-move -t <input-tags-dir> -t <output-tags-dir> -t <xbox-tags-dir> -c shader_transparent_chicago_extended shader_transparent_generic
This will change all shader_transparent_chicago references to shader_transparent_generic if the generic tag exists.
$ invader-refactor -M no-move -t <input-tags-dir> -t <output-tags-dir> -t <xbox-tags-dir> -c shader_transparent_chicago shader_transparent_generic
Bitmap formats
While 32-bit bitmaps can be used on Xbox, there is a limited amount of memory available, thus it should be used sparingly. The PC releases of the game do not have such a restriction, thus there is no reason to use anything except a lossless format.
Xbox Halo supports height compression (P8) as well as uncompressed monochrome (A8, Y8, AY8, A8Y8). The Gearbox version does not support any of these formats. It is technically not necessary to use these formats, but the space savings (without loss in quality) can be extremely helpful.
Converting a completely monochrome texture to the monochrome format can save a significant amount of space over 32-bit without quality loss. In some cases, such as with most reticles and HUD backgrounds, monochrome textures can even use the same amount of space as DXT3 and DXT5 without any loss in quality as seen in the table below:
| Format | Bits per pixel | Quality loss |
|---|---|---|
| DXT1 | 4 | Yes |
| DXT3 | 8 | Yes |
| DXT5 | 8 | Yes |
| P8 | 8 | Yes |
| A8 | 8 | No, if input is monochrome |
| Y8 | 8 | No, if input is monochrome |
| AY8 | 8 | No, if input is monochrome |
| A8Y8 | 16 | No, if input is monochrome |
| 16-bit | 16 | Yes |
| 32-bit | 32 | No |
P8 can be used for bumpmaps and vector maps, although there may be some loss in quality. However, the benefit to using P8 is that there isn't any block artifacts and you aren't going to see the texture rendered as itself, so it technically provides the best tradeoff in quality and space.