gbxmodel

The Gearbox model tag contains the marker points and render models for objects such as vehicles, scenery, and weapons among others. It is not collideable nor animated on its own, and objects may reference additional model_collision_geometry and model_animations tags. This tag supports LODs and permutations, and includes shader_model references.

Don't confuse this tag with the Xbox-only model, which Gearbox modified for the PC port. It is therefore used in all derivatives of that port, like Mac, Demo, and MCC. Unlike the Xbox version, the Gearbox model uses uncompressed vertices.

Shaders

Each part of a model can reference a different shader, like the Warthog's windscreen using a shader_transparent_glass while its body uses a shader_model. While a model can technically reference any kind of shader, referencing a shader_environment is not recommended when targeting H1CE because it renders incorrectly in atmospheric fog.

Nodes

Nodes can be thought of as the model's "skeleton" and can be animated to move parts of the model. Each vertex can be influenced by up to 2 nodes. H1A and H1CE 1.10 allow up to 63 model nodes. Older versions of H1CE and H1X allow 48.

Markers

Markers are simple named points with orientation attached to a model. Since they are parented by nodes, they can be animated. Markers can be used for a variety of purposes, such as attaching objects together with scripts (e.g. Pelicans carrying Warthogs), attaching widgets like antenna, or firing projectiles from in the case of weapons.

This tag only contains the marker data but other tags usually determine how they are used. However, certain marker names have special behaviour in-engine:

  • head:
    • Determines where AI look at when scripted to talk to another character.
    • Base location for the friendly indicator in multiplayer.
    • Used as a ray origin when testing if AI can see their enemy.
  • primary trigger: Where a weapon's primary trigger projectiles and effects come from. See also the projectiles use weapon origin field.
  • secondary trigger: As above, for secondary triggers (second trigger slot).
  • body
  • front: Possibly used to used to see if you're facing a device_control, if present.
  • ground point: Determines the resting point for items.
  • left hand: Used during the grenade throwing animation.
  • melee: Where melee damage comes from here. If not present, the engine picks an unknown default location.
  • hover thrusters:
    • When used on a vehicle with "alien scout" or "alien fighter" vehicle physics type, creates a dust cloud effect when the vehicle is hovering close to the ground. This can be seen at a piloted Banshee's wingtips when sitting on the ground.
    • When the vehicle physics type is "human plane", creates a similar dust effect if the marker is pointed at nearby ground. Used for the Pelican's thrusters.
  • jet thrusters: Can also be used for vehicles with "human plane" physics to create the Pelican's thruster dust effect.

Tool only includes markers from the superhigh LOD.

Regions

Regions are named sections of the model which can have multiple permutations. Region names are used by the engine to relate parts of the render model with the collision model. For example, a Flood combat form losing an arm. Some regions have special behaviour in-engine:

Regions render in the order they are stored in the tag. When naming regions, consider that they will be sorted by name when compiled into the .gbxmodel. This can be important for skyboxes and objects with multiple layers of alpha-blended transparent shaders which aren't z-culled and need a correct sorting order to be explicitly defined, assuming the object is viewed mostly from one direction.

Permutations

A permutation is a randomly selected variation of a region. They are often used to give bipeds visual variety. Some permutations have special behaviour in-engine:

Permutations are not network synchronized.

Level of detail

Low quality LODs shown for the Chief biped and Warthog. Note the reduced geometric detail.

Models can contain multiple levels of detail (LODs), ranging from simplified meshes with reduced shader count to high detail meshes with numerous complex shaders. The game will select a LOD based on the on-screen diameter of the object's bounding sphere in pixels. Objects which are very distant or small don't need a lot of geometric detail, so they can be rendered using low quality LODs to keep the framerate high in busy scenes.

Halo CE supports 5 LODs whose pixel cutoffs can be configured in this tag. From best to worst quality:

  • super high
  • high
  • medium
  • low
  • super low

When rendering first person models, Halo always uses the lowest quality LOD instead of the highest. When creating FP arms or weapons create a separate FP model from your 3P model which only includes a single super high LOD.

LODs are created by using a special naming convention when compiling models with Tool.

Structure and fields

Field Type Comments
flags bitfield
Flag Mask Comments
blend shared normals 0x1

On map compilation, vertices with the same positions have their normals linearly averaged.

parts have local nodes 0x2
ignore skinning 0x4
node list checksum int32
super high detail cutoff float
  • Unit: pixels
high detail cutoff float
  • Unit: pixels
medium detail cutoff float
  • Unit: pixels
low detail cutoff float
  • Unit: pixels
super low detail cutoff float
  • Unit: pixels
super low detail node count uint16
  • Cache only
  • Unit: nodes
  • Unused
low detail node count uint16
  • Cache only
  • Unit: nodes
  • Unused
medium detail node count uint16
  • Cache only
  • Unit: nodes
  • Unused
high detail node count uint16
  • Cache only
  • Unit: nodes
  • Unused
super high detail node count uint16
  • Cache only
  • Unit: nodes
  • Unused
base map u scale float
  • Default: 1
base map v scale float
  • Default: 1
markers Block
  • HEK max count: 256
  • Hidden

Generated in postprocessing from the markers in the model's permutations.

  • Read-only
Field Type Comments
name TagString
Field Type Comments
buffer char[32]

Null-terminated string in 32-char buffer.

magic identifier int16
instances Block
  • HEK max count: 32
  • Read-only
Field Type Comments
region index uint8
permutation index uint8
node index uint8
translation Point3D
Field Type Comments
x float
y float
z float
rotation Quaternion
Field Type Comments
i float
j float
k float
w float
nodes Block
  • HEK max count: 64
  • Max: 255
  • Read-only
Field Type Comments
name TagString?
next sibling node index uint16
first child node index uint16
parent node index uint16
default translation Point3D?
default rotation Quaternion?
node distance from parent float
scale float
  • Cache only
rotation Matrix
  • Cache only
Field Type Comments
elements float[9]
translation Point3D?
  • Cache only
regions Block
  • HEK max count: 32
  • Max: 255
  • Read-only
Field Type Comments
name TagString?
permutations Block
  • HEK max count: 32
  • Max: 255
  • Read-only
  • Processed during compile
Field Type Comments
name TagString?
flags bitfield
Flag Mask Comments
cannot be chosen randomly 0x1
permutation number uint16
  • Cache only
super low uint16
low uint16
medium uint16
high uint16
super high uint16
markers Block
  • HEK max count: 64
  • Read-only
Field Type Comments
name TagString?
node index uint16
rotation Quaternion?
translation Point3D?
geometries Block
  • HEK max count: 256
  • Max: 65535
  • Read-only
Field Type Comments
flags bitfield
Flag Mask Comments
unused 0x1
parts Block
  • HEK max count: 32
  • Read-only
  • Processed during compile
Field Type Comments
flags bitfield
Flag Mask Comments
stripped internal 0x1
zoner 0x2
shader index uint16
prev filthy part index uint8
  • Default: 255
next filthy part index uint8
  • Default: 255
centroid primary node uint16
  • Cache only
centroid secondary node uint16
  • Cache only
centroid primary weight float
  • Cache only
centroid secondary weight float
  • Cache only
centroid Point3D?
uncompressed vertices Block
  • HEK max count: 65535
  • Non-cached
  • Read-only
Field Type Comments
position Point3D?
normal Vector3D
Field Type Comments
i float
j float
k float
binormal Vector3D?
tangent Vector3D?
texture coords Point2D
Field Type Comments
x float
y float
node0 index uint16
node1 index uint16
node0 weight float
node1 weight float
compressed vertices Block
  • HEK max count: 65535
  • Non-cached
  • Read-only
Field Type Comments
position Point3D?
normal uint32
binormal uint32
tangent uint32
texture coordinate u int16
texture coordinate v int16
node0 index int8
node1 index int8
node0 weight uint16
triangles Block
  • HEK max count: 65535
  • Non-cached
  • Read-only
Field Type Comments
vertex0 index uint16
vertex1 index uint16
vertex2 index uint16
do not crash the game uint32
  • Cache only
triangle count uint32
  • Cache only
triangle offset uint32
  • Cache only

On Xbox: pointer to the triangle indices. On PC: offset to triangles relative to the end of the map's vertex data.

triangle offset 2 uint32
  • Cache only

On Xbox: pointer to the entry in the second parts list which points to the triangle indices. On PC: same value as the first triangle offset

do not screw up the model uint32
  • Cache only
vertex count uint32
  • Cache only
bullshit uint32
  • Cache only
vertex offset uint32
  • Cache only

On Xbox: pointer to the entry in the second parts list which points to the triangle indices. On PC: offset to first vertex relative to the map's vertex data.

local node count uint8
  • Max: 22
  • Read-only
  • Unused
local node indices uint8[22]
  • Hidden

Local nodes are used to indirectly refer to a real node. So, if local nodes are used, a vertex says node #4, and local node #4 refers to node #5, then the vertex is node #5. There really doesn't seem to be any benefit to using local nodes, considering compressed vertices (which can only address 42 nodes) don't even use them. They just make the models unnecessarily more convoluted while taking up more space.

shaders Block
  • HEK max count: 32
Field Type Comments
shader

TagDependency: shader

  • Non-null
permutation uint16

Acknowledgements

Thanks to the following individuals for their research or contributions to this topic:

  • Fubih (Regions render order tip)
  • gbMichelle (Node limits)
  • Kavawuvi (Invader tag definitions)
  • MosesOfEgypt (Tag structure research)