Objects are a high-level abstract tag, meaning they serve as a base for many other tag types but cannot be directly created themselves. Generally, they are "things" with a position in the world but are distinct from the "level" itself. Some examples include elevators, trees, warthogs, and the player.

Some capabilities available to objects (though not used by every subtype) are:

Functions

Functions are values of objects that can change over time and/or react to external stimulus. They can be combined in complex ways and used to drive dynamic changes across various aspects of the object, like its appearance, sound, and attachments. Some examples are Jackal shields changing colour in reaction to damage, Warthog headlights turning on when you enter the vehicle, Banshee wingtips emitting contrails when banking, and the Assault Rifle's compass pointing north.

Objects can receive up to 4 sources of input from the engine called A in, B in, C in, and D in. These can be used as inputs by your functions or change colors. Every type of object has access to sources from the export to functions section. However, certain types of objects can override these base sources with additional sources related to that object type. To name a few, devices have access to position and power while vehicles have access to speed and slide.

The next relevant section is the functions block. This is where you can define functions and how the change over time, and if they use any of the export to functions inputs. Each function produces a simple numeric value over time, typically between 0 and 1. This could be as simple as an oscillating sine wave or as complex as a noise value scaled by recent damage and clipped to a certain range. You can create up to 4 functions.

The outputs of functions can be used by a variety of other tags related to the object, including but not limited to:

Shadows and lighting

For most dynamic objects, Halo uses shadow mapping with their render model, unless the object's "does not cast shadow" flag is true or render_shadows is disabled. Scenery shadows are baked into the lightmap using the object's collision geometry instead, regardless of the "does not cast shadow" flag. Static objects can be forced to use shadow mapping if the cast shadow by default flag is set.

Objects receive a few parameters from the environment as inputs to their lighting model. These include up to two distant light sources (direction and colour), ambient light, reflection tint, shadow direction, and shadow colour. Lighting is calculated when objects are created and also when dynamic objects move. To do this the game casts a ray straight down to a BSP ground point up to 10 world units away (device_machine can optionally sample nearby surfaces instead) to determine its lighting and can result in a few scenarios:

  1. If a ground point is found within 10 units, that surface's lightmap colour is used to light the object. This is why even an object in direct sunlight can appear dark when it is sampling the ground beneath it. The shadow vector is an interpolation of lightmap vertex normals. In this scenario you will see a coloured vector drawn over objects with debug_object_lights 1.
  2. If a ground point is not found and the BSP tag has a non-zero red value for default ambient color field, BSP default lighting fields will apply.
  3. Otherwise the object receives hard-coded white light from the +x +y direction and casts shadows straight down.

You can test the latter two scenarios by setting debug_collision_skip_vectors 1 to make the ray cast always fail. Objects which are outside the BSP will fail to find a valid ground point and therefore receive default lighting. Objects above phantom BSP and nearly coplanar faces may fail to do so too.

BSP switches do not cause fixed objects to resample lighting.

Related HaloScript

Function/global

Type

(debug_objects [boolean])

When enabled, toggles if debug information is visible on objects (such as bounding sphere and collision models). Individual debug features can be toggled with the debug_objects_* commands. In H1A this now has debug_objects_root_node enabled by default; turn it off if you don't want the orange text.

Global
(debug_objects_biped_autoaim_pills [boolean])

When debug_objects is enabled, displays biped autoaim pills in red.

Global
(debug_objects_biped_physics_pills [boolean])

When debug_objects is enabled, displays biped physics pills in white.

Global
(debug_objects_bounding_spheres [boolean])

When debug_objects is enabled, displays yellow spheres for object bounding radius. The sphere will be black when the object is inactive. This setting defaults to true in HEK Sapien but not H1A Sapien.

Global
(debug_objects_collision_models [boolean])

When debug_objects is enabled, displays green meshes for object collision models. This setting defaults to true in HEK Sapien but not H1A Sapien.

Global
(debug_objects_names [boolean])

Toggles the display of object names, for named objects. The names are shown in purple.

Global
(debug_objects_pathfinding_spheres [boolean])

When debug_objects is enabled, displays object pathfinding spheres in blue.

Global
(debug_objects_physics)

When debug_objects is enabled, displays physics mass points as white spheres.

Global
(debug_objects_position_velocity)

When debug_objects is enabled, displays red, green, and blue object-space reference axes and a yellow velocity vector on each object.

Global
(debug_objects_root_node)

When debug_objects is enabled, displays red, green, and blue object-space reference axes and orange text including object ID, class, and tag name on each object. Defaults to true in H1A.

Global
(debug_objects_unit_seats)

When debug_objects is enabled, displays blue markers at unit seat locations, red markers at their entry points, and a yellow marker at the object origin.

Global
(debug_objects_unit_vectors)

When debug_objects is enabled, displays white and red vectors on objects. Their meaning is unknown.

Global
(debug_object_lights)

Shows the incoming light colour and vector for all objects which results from sampling lightmap data at the ground point beneath the object. This data is used to shade the object and cast its shadow.

Global
(object_light_ambient_base)

Sets the amount of ambient light all objects receive. Note that this only affects moving objects when their lighting updates, so you will not see any change on scenery. Setting this to 1 makes objects fullbright. Defaults to 0.03.

Global
(object_light_ambient_scale)

Scales ambient light from the lightmap. Defaults to 0.4.

Global
(object_light_interpolate)

Toggles if object lighting transitions smoothly when the object moves between different ground point surfaces or default lighting.

Global
(object_light_secondary_scale)

Scales secondary light on objects, but doesn't apply to default lighting. Defaults to 1.

Global
(rasterizer_environment_shadows [boolean])

Toggles dynamic shadow mapping for objects. Same effect as render_shadows.

Global
(render_shadows [boolean])

Toggles the display of dynamic object shadows. Same effect as rasterizer_environment_shadows.

Global

Structure and fields

FieldTypeComments
object typeenum
  • Volatile
  • Hidden
OptionValueComments
biped0x0
vehicle0x1
weapon0x2
equipment0x3
garbage0x4
projectile0x5
scenery0x6
device machine0x7
device control0x8
device light fixture0x9
placeholder0xA
sound scenery0xB
flagsbitfield
FlagMaskComments
does not cast shadow0x1

Prevents this object from casting dynamic shadows. Does not apply to scenery, which cast shadows in lightmaps using their collision model.

transparent self occlusion0x2
brighter than it should be0x4

Causes the object to have extra ambient lighting so it's easier to see in dark spaces. This is used for items which are important to gameplay like weapons and powerups.

not a pathfinding obstacle0x8
extension of parent0x10
  • H1A only
  • Unused

Planned H2 backport, currently unused. In H2 this is documented as "passes all function values to parent and uses parent's markers".

cast shadow by default0x20
  • H1A only

Forces static objects like scenery to have dynamic shadows, unless does not cast shadow is also set. This flag does not prevent such objects from also casting lightmapped shadows, so it is best used for objects which have been added to a map after baking like scenery which is scripted to appear.

does not have remastered geometry0x40
  • H1A only

The object does not appear in anniversary/remastered graphics mode. Used for campaign moas.

bounding radiusfloat
  • Unit: world units

The bounding radius sets the approximate maximum size of the object and is used for various optimizations and gameplay purposes, including but likely not limited to:

The radius should contain this object completely, but not be too large or else the object will draw unccessarily when off-screen, block spawn points, or prevent AI from pathfinding effectively. Setting it too low will cause the object to have clipped shadows, pop in and out of visibility at the edges of the screen, and have inconsistent collision with other objects.

The bounding radius can be visualized in Sapien or Standalone using debug_objects_bounding_spheres.

bounding offsetPoint3D
FieldTypeComments
xfloat
yfloat
zfloat
origin offsetPoint3D?
acceleration scalefloat
  • Min: 0
scales change colorsuint32
  • Cache only
model
TagDependency
animation graphTagDependency: model_animations
collision modelTagDependency: model_collision_geometry
physicsTagDependency: physics
modifier shaderTagDependency: shader
creation effectTagDependency: effect
render bounding radiusfloat
  • Unit: world units
a inenum
OptionValueComments
none0x0
body vitality0x1
shield vitality0x2
recent body damage0x3
recent shield damage0x4
random constant0x5
umbrella shield vitality0x6
shield stun0x7
recent umbrella shield vitality0x8
umbrella shield stun0x9
region0xA
region 10xB
region 20xC
region 30xD
region 40xE
region 50xF
region 60x10
region 70x11
alive0x12
compass0x13
b inenum?
c inenum?
d inenum?
hud text message indexuint16
forced shader permutation indexuint16
attachmentsBlock
  • HEK max count: 8
FieldTypeComments
type
TagDependency (6)
markerTagString
primary scaleenum
OptionValueComments
none0x0
a out0x1
b out0x2
c out0x3
d out0x4
secondary scaleenum?
change colorenum
OptionValueComments
none0x0
a0x1
b0x2
c0x3
d0x4
widgetsBlock
  • HEK max count: 4
FieldTypeComments
reference
TagDependency (5)
functionsBlock
  • HEK max count: 4
  • Max: 4
  • Processed during compile
FieldTypeComments
flagsbitfield
FlagMaskComments
invert0x1
additive0x2
always active0x4
periodfloat
  • Unit: seconds
  • Default: 1
scale period byenum
OptionValueComments
none0x0
a in0x1
b in0x2
c in0x3
d in0x4
a out0x5
b out0x6
c out0x7
d out0x8
functionenum
OptionValueComments
one0x0
zero0x1
cosine0x2
cosine variable period0x3
diagonal wave0x4
diagonal wave variable period0x5
slide0x6
slide variable period0x7
noise0x8
jitter0x9
wander0xA
spark0xB
scale function byenum?
wobble functionenum?
wobble periodfloat
  • Unit: seconds
wobble magnitudefloat
  • Unit: percent
square wave thresholdfloat
step countuint16
map toenum
OptionValueComments
linear0x0
early0x1
very early0x2
late0x3
very late0x4
cosine0x5
sawtooth countuint16
addenum?
scale result byenum?
bounds modeenum
OptionValueComments
clip0x0
clip and normalize0x1
scale to fit0x2
boundsBounds
  • Default: 0,1
FieldTypeComments
minfloat
maxfloat
turn off withint16
scale byfloat
inverse boundsfloat
  • Cache only
inverse sawtoothfloat
  • Cache only
inverse stepfloat
  • Cache only
inverse periodfloat
  • Cache only
usageTagString
change colorsBlock
  • HEK max count: 4
  • Max: 4
  • Processed during compile
FieldTypeComments
darken byenum?
scale byenum?
flagsbitfield
FlagMaskComments
blend in hsv0x1
more colors0x2
color lower boundColorRGB
color upper boundColorRGB
permutationsBlock
  • HEK max count: 8
FieldTypeComments
weightfloat
  • Default: 1
color lower boundColorRGB
color upper boundColorRGB
predicted resourcesBlock
  • HEK max count: 1024
  • Cache only
FieldTypeComments
typeenum
OptionValueComments
bitmap0x0
sound0x1
resource indexuint16
taguint32

Acknowledgements

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

  • Connor Dawn (Explaining cast shadow by default)
  • Conscars (Shadow behaviour testing)
  • Jakey (Explaining modifier shaders.)
  • Kavawuvi (Invader tag definitions)
  • MosesOfEgypt (Tag structure research)
  • Satania (Explaining acceleration scale)