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. Gearbox Software created this tag class for the PC port, and it is therefore used in all derivatives of that port, like Mac, Demo, and MCC. Unlike model, this tag 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, spawns an 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.

Commonly used marker names without hard-coded behaviour include:

  • primary ejection: Used to indicate where casings fly out when firing the primary trigger.

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 variation of a region that can be randomly selected. They are often used to give bipeds visual variety. Some permutations have special behaviour in-engine:

  • ~blur: Switched to depending on weapon rate of fire and vehicle speed to fake motion blur. Used for the Warthog tires and chaingun when spinning fast enough.
  • ~damaged: Switched to depending how much damage the object takes based on Damage Threshold

Permutations can also be set via script or the Desired Permutation field when placing objects in a Scenario. In order to use the Desired Permutation field the model's permutations must be named in a specific way: Permutation_name-###

Randomly selected 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 and this tag's LOD cutoffs. 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. 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.

LODs are currently not behaving as expected in Halo CE, both in tools and in the Master Chief Collection. This can cause only the super high LOD to be visible at all times, no matter the on-screen diameter of an object's bounding sphere.

Related HaloScript

Function/global

Type

(rasterizer_models [boolean])

Toggles the rendering of all models. When disabled, all objects like scenery, units, projectiles, and even the skybox and FP arms will become invisible. The BSP and effects like particles and decals are still visible.

Global
(rasterizer_model_transparents [boolean])

Toggles the rendering of transparent shaders in models. For example, the Warthog's windshield.

Global
(render_model_index_counts [boolean])

If true, displays a red number above each object with its model index count. If render_model_vertex_counts is also enabled, the vertex count and index count are separated by a slash like "<vertices>/<indices>".

Global
(render_model_markers [boolean])

If enabled, all model markers will be rendered in 3D with their name and rotation axis.

Global
(render_model_nodes [boolean])

If enabled, all model skeletons will be rendered. Nodes are shown as axis gizmos and connected to their parents by white lines.

Global
(render_model_vertex_counts [boolean])

If true, displays a red number above each object with its model vertex count. If render_model_index_counts is also enabled, the vertex count and index count are separated by a slash like "<vertices>/<indices>".

Global

Structure and fields

FieldTypeComments
flagsbitfield
FlagMaskComments
blend shared normals0x1

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

parts have local nodes0x2
ignore skinning0x4
node list checksumint32
super high detail cutofffloat
  • Unit: pixels
high detail cutofffloat
  • Unit: pixels
medium detail cutofffloat
  • Unit: pixels
low detail cutofffloat
  • Unit: pixels
super low detail cutofffloat
  • Unit: pixels
super low detail node countuint16
  • Cache only
  • Unit: nodes
  • Unused
low detail node countuint16
  • Cache only
  • Unit: nodes
  • Unused
medium detail node countuint16
  • Cache only
  • Unit: nodes
  • Unused
high detail node countuint16
  • Cache only
  • Unit: nodes
  • Unused
super high detail node countuint16
  • Cache only
  • Unit: nodes
  • Unused
base map u scalefloat
  • Default: 1

UV map scale is derived upon model import as a box that encompasses all the vertices in UV space, where 1 unit is 1 tile of the texture. The U scale will be set by the length of the box on the U direction. For example, if the furthest point in the U coordinate is 1.5 texture tiles away from the center, this value will become 1.5. The same thing happens for the V scale.

If new geometry parts are added and the model rebuilt, and the vertices are mapped in UV space inside the space already mapped by the existing geometry, the scale in the gbxmodel will not change. If they are further from the origin, the scale will increase. Using tools such as Mozzarilla to import/export geometry in the tag directly will only look correct if the source and destination UV map scale values are the same.

Note that shader_transparent_chicago has its own UV scale.

Values of 0 will default to 1.

base map v scalefloat
  • Default: 1

See base map u scale.

markersBlock
  • HEK max count: 256
  • Hidden

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

  • Read-only
FieldTypeComments
nameTagString
magic identifierint16
instancesBlock
  • HEK max count: 32
  • Read-only
FieldTypeComments
region indexuint8
permutation indexuint8
node indexuint8
translationPoint3D
FieldTypeComments
xfloat
yfloat
zfloat
rotationQuaternion
FieldTypeComments
ifloat
jfloat
kfloat
wfloat
nodesBlock
  • HEK max count: 64
  • Max: 255
  • Read-only
FieldTypeComments
nameTagString
next sibling node indexuint16
first child node indexuint16
parent node indexuint16
default translationPoint3D?
default rotationQuaternion?
node distance from parentfloat
scalefloat
  • Cache only
rotationMatrix
  • Cache only
FieldTypeComments
elementsfloat[9]
translationPoint3D?
  • Cache only
regionsBlock
  • HEK max count: 32
  • Max: 255
  • Read-only
FieldTypeComments
nameTagString
permutationsBlock
  • HEK max count: 32
  • Max: 255
  • Read-only
  • Processed during compile
FieldTypeComments
nameTagString
flagsbitfield
FlagMaskComments
cannot be chosen randomly0x1
permutation numberuint16
  • Cache only
super lowuint16
lowuint16
mediumuint16
highuint16
super highuint16
markersBlock
  • HEK max count: 64
  • Read-only
FieldTypeComments
nameTagString
node indexuint16
rotationQuaternion?
translationPoint3D?
geometriesBlock
  • HEK max count: 256
  • Max: 65535
  • Read-only
FieldTypeComments
flagsbitfield
FlagMaskComments
unused0x1
partsBlock
  • HEK max count: 32
  • Read-only
  • Processed during compile
FieldTypeComments
flagsbitfield
FlagMaskComments
stripped internal0x1
zoner0x2
shader indexuint16
prev filthy part indexuint8
  • Default: 255

Allows the rendering order of parts to be manually specified for correct transparency sorting. In HEK Tool, this defaults to -1 (unused) if set to 0. In H1A Tool, this defaulting only occurs when both filthy part indices are 0, since 0 should be a useable index.

next filthy part indexuint8
  • Default: 255

Sets the next part to render.

centroid primary nodeuint16
  • Cache only
centroid secondary nodeuint16
  • Cache only
centroid primary weightfloat
  • Cache only
centroid secondary weightfloat
  • Cache only
centroidPoint3D?
uncompressed verticesBlock
  • HEK max count: 65535
  • Non-cached
  • Read-only
FieldTypeComments
positionPoint3D?
normalVector3D
FieldTypeComments
ifloat
jfloat
kfloat
binormalVector3D?
tangentVector3D?
texture coordsPoint2D
FieldTypeComments
xfloat
yfloat
node0 indexuint16
node1 indexuint16
node0 weightfloat
node1 weightfloat
compressed verticesBlock
  • HEK max count: 65535
  • Non-cached
  • Read-only
FieldTypeComments
positionPoint3D?
normaluint32
binormaluint32
tangentuint32
texture coordinate uint16
texture coordinate vint16
node0 indexint8
node1 indexint8
node0 weightuint16
trianglesBlock
  • HEK max count: 65535
  • Non-cached
  • Read-only
FieldTypeComments
vertex0 indexuint16
vertex1 indexuint16
vertex2 indexuint16
do not crash the gameuint32
  • Cache only
triangle countuint32
  • Cache only
triangle offsetuint32
  • 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 2uint32
  • 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 modeluint32
  • Cache only
vertex countuint32
  • Cache only
bullshituint32
  • Cache only
vertex offsetuint32
  • 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 countuint8
  • Max: 22
  • Read-only
  • Unused
local node indicesuint8[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.

shadersBlock
  • HEK max count: 32
FieldTypeComments
shaderTagDependency: shader
  • Non-null
permutationuint16

Acknowledgements

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

  • Fubih (Regions render order tip)
  • Galap (Base map UV scale research)
  • gbMichelle (Node limits and reversing hard-coded markers)
  • Kavawuvi (Invader tag definitions, filthy part index research)
  • Kolshgamer (Common marker name)
  • MosesOfEgypt (Tag structure research)