Game state is the in-memory data which describes the state of the game world as it is simulated over time. It differs from tags which, although they are also loaded into memory, describe static or initial properties of classes of game objects rather than the current properties of individual ones.

Game state also includes global data for systems like scripting (script globals), multiplayer game modes (scores), and physics (game speed and gravity) to name a few. During each simulation tick (30 per second) the game runs updates across the game state which result in the ongoing changes to the game world as time progresses. As an example, this might include moving a glow particle some distance based on its speed in the glow tag definition.

The game state is saved and loaded from game saves or core saves.

Datum arrays

Much of the game state is maintained in datum arrays, also called tables. Each entry (datum) in these arrays is used to store the current state of some object or effect. The structure and purpose of these datums require reverse engineering to understand.

Since the game world is dynamic, the datum count can rise up to a limit. The following limits are known ("-" if unchanged):

TableLegacy limitH1A limitPurpose
cluster collidable object reference2048-
cluster noncollidable object reference2048-
collidable object cluster reference2048-
noncollidable object cluster reference2048-
cached object render states256-
glow8-Stores the state of glow systems/paths. For example, the energy sword has 2 glow paths so up to 4 energy swords can be glowing.
glow particles512-Stores the state of individual glow particles, like colour and position.
light volumes256-
device groups1024-
cluster light reference2048-
light cluster reference2048-
decals2048-Stores the state of dynamic decals. This likely includes their position, tag ID, and expiry timer.
contrail point1024-
effect location512-
particle systems64-
particle system particles512-
object looping sounds1024-
swarm component256-
prop768-Part of the AI knowledge model and stores a web of relationships between units like allies and enemies. Likely used when determining if actors have more enemies than allies nearby, if enemies are reachable, occluded, etc. Props can be visualized with ai_render_props.
ai pursuit256-
object list header48-Stores object lists returned by scripting functions like ai_actors. These are reference-counted and periodically garbage collected.
list object reference128-Stores object references belonging to object lists (above). These datums reference each other by ID to form linked lists.
hs thread256-
hs globals1024-Stores the state of HS globals, including external globals, not just those in the level script.
recorded animations64-
AI knowledge768-
mounted weapon units8-

Glow datum

Glow datums hold the state of glows. For example, the gold Elite's energy sword is composed of 2 glows, one for the bottom blade and one for the top.

FieldOffset (relative)TypeComments
number of markers0x4uint16
definition index0x224uint32
bitmap dimension0x228uint16
marker order0x22Auint16[5]
total time0x234float
marker time index0x238float[5]
accumulated trailing particle generation ticks0x24Cuint16
number of particles0x24Euint16
head particle offset0x250uint32
tail particle offset0x254uint32

Object list header datum

FieldOffset (relative)TypeComments
reference count0x4uint16
list object reference id0x8uint16

ID of the first (or last?) element of this list, from the list object reference datum array.


Related HaloScript



(ai_show_swarms [boolean])

Displays debug information in the bottom left with the current counts for swarms and swarm component datum arrays. Swarms are groups of Flood infection forms while components are individual infection forms.



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

  • Conscars (Reversing object list header datum)
  • gbMichelle (Reversing stock table limits)