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:

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. However, with scenery, shadows are baked into the lightmap using the object's collision geometry instead, regardless of the "does not cast shadow" flag.

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 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. Scenery which are outside the BSP will also fail to get a ground point and therefore receive default 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.

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 H1CE 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 H1CE 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

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
bounding radiusfloat
  • Unit: world units

The bounding radius sets the approximate maximum size of the object and is used for a variety of optimizations by the game:

  • Culling objects for rendering which are not partially on screen.
  • Setting the shadow map size for dynamic object shadows.
  • Selecting an appropriate LOD.
  • Skipping collision checks.

The radius should contain this object completely, but not be too large. Setting it too high will cause the object to draw unccessarily when off-screen, but 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:

  • Jakey (Explaining modifier shaders.)
  • Kavawuvi (Invader tag definitions)
  • MosesOfEgypt (Tag structure research)
  • Satania (Explaining acceleration scale.)