Start here

↑ ↓ to move, Enter to openKeyword search
Game internals

Reading the Simulation's Game State: Objects and Players

Build
2026.08.11.1121610.2-Rel-i343-Meteorite-2607-CU4 (Steam), tag module C8C14440…3BF7
Code
crates/blam-live/src/gamestate.rs, crates/blam-live/src/world.rs, mjolnir live objects|players|arrays
Date
2026-09-29

Rendered from the repository, where it is written as the work happens: it keeps its history, and a status line above says when it describes a design rather than something shipped.

Build: 2026.08.11.1121610.2-Rel-i343-Meteorite-2607-CU4 (Steam), tag module C8C14440…3BF7 Code: crates/blam-live/src/gamestate.rs, crates/blam-live/src/world.rs, mjolnir live objects|players|arrays Date: 2026-09-29

Summary

Verified: every per-game table the simulation keeps (objects, players, actors, squads, script threads and about fifty more) is a Blam data array, and the pointer to each array's header is stored in the tag module's static thread-local storage on the simulation thread. None of them is a module global. So the tables are found without a signature or a per-build address:

  1. The TLS slot number comes from the module's own PE TLS directory (AddressOfIndex, RVA 0xD72730 on CU4). The block is 0x650 bytes.
  2. Each thread's TEB + 0x58 (ThreadLocalStoragePointer), indexed by that slot, gives the thread's copy of the block.
  3. Only the simulation thread's copy is populated. It is the one holding a pointer to a header named object with the d@t@ magic at +0x28.

Measured in mission A30, from the menu through New Game. Of ~170 threads, one (the simulation thread) held 59 arrays. At the frontend the same 59 were already there, but marked invalid.

The header layout is shared by every array, tag instance included. The object datum and player layouts below are CE's own. They descend from Reach, not from the Xbox engine.

Data array header (0x70 bytes)

Read off the players constructor (RVA 0x181010) and the object/lights constructors (inside 0x59c520).

OffsetFieldNotes
+0x00name, char[32]NUL-terminated, so at most 31 characters survive: collision hierarchy element hea
+0x20element size, u64
+0x28magic 0x64407440 (d@t@)
+0x2Cmaximum count, u32
+0x31valid, u8set once reset for a game; 0 at the menu
+0x32flags, u16constructors OR in 4
+0x38allocator
+0x44high water (first unallocated), u32
+0x48live count, u32
+0x4Cnext identifier (salt), u16
+0x50elements pointerheader + 0x70 when allocated inline
+0x58in-use bitset pointer
+0x60offset to elements, 0x70
+0x68offset to bitset0x70 + max × size

Every element starts with its u16 salt, and a handle is salt << 16 | index. The first salt is the name's first two bytes, little-endian, with the top bit set, and each allocation takes the next one. So object handles start at 0xE26F, players at 0xEC70, tag instance at 0xE174. A handle's high word says which array it came from.

Where the arrays sit

A selection of the CU4 block. mjolnir live arrays prints all of it. The reader finds arrays by name, so a slot moving in a later build costs nothing.

TLS offsetArrayElementMaximum
+0x020object0x182048
+0x028actor0xD1096
+0x030players0x4B016
+0x058squad0xEC512
+0x138fire team0xD416
+0x178lights0xBC600
+0x2F0hs globals0x84096 (1,475 in use in A30)
+0x360det hs thread0x52C320
+0x3A0megalo_objects0x94512

hs globals holding 1,475 values fits the script compiler's engine-global references running past index 1471, far beyond the 260 globals in defs/hce/console.json.

Object header entry (0x18 bytes)

OffsetField
+0x00salt, u16
+0x02flags, u8 (0x87 on the player's Spartan, 0x81 on most others)
+0x04object type, u16: Reach's enum
+0x06datum size, u16
+0x08datum offset in the object pool, u32. Consecutive datums sit size + 0x10 apart
+0x0Cthe object's index on the host, u16. On a host that is the entry's own index, and the reader refuses the table if it does not match. On a fireteam client it is not: two test copies on 2026-11-09 read 139 and 140 in the client's entries 84 and 88, the host's indices for the same two units. A check against it works only on a host (lua_native_audit.md)
+0x10datum pointer

Type codes seen with a matching tag group: 0 biped (bipd), 2 weapon (weap), 3 equipment (eqip), 4 terminal (term), 7 machine (mach), 13 effect scenery (efsc). The rest follow the same enum: 1 vehicle, 5 projectile, 6 scenery, 8 control, 9 sound scenery, 10 crate, 11 creature, 12 giant.

Object datum

OffsetField
+0x00definition tag handle: resolves in the tag table
+0x0Cnext sibling object handle
+0x10first child object handle
+0x14parent object handle
+0x20bounding sphere centre (3 floats) and radius
+0x44position. Relative to the parent when attached: a held rifle reads (0.00, 0.02, 0.01)
+0x50forward vector
+0x5Cup vector
+0x68translational velocity
+0x74angular velocity
+0x80scale
+0x108maximum body vitality (Spartan 45, marine 100)
+0x10Cmaximum shield vitality (Spartan 70)
+0x174damage section records: byte size, u16
+0x176damage section records: offset from the datum, u16

Vitality lives in the section records, 0x18 bytes each. The float at +0x10 is the current vitality as a fraction, and +0x0E is -1 for a section not in play.

  • Body: object_get_health (RVA 0x5b7e60) reads section 0.
  • Shield: unit_get_shield (0x5b8230) reads the section named by the model. The chain (0x5b83b0) is:
    1. the object tag's handle at +0x00;
    2. that tag's root +0x60, the model reference's handle;
    3. that model's root +0xF0, an i16 shield section index. The Spartan's is 2.

Checked live: unit_set_current_vitality (player_get 0) 20 35 put section 0 at 0.469 and section 2 at 0.578 on the next 10 Hz sample. The shield recharged to 1.0 within 1.2 s and the body regenerated over about 8 s. unit_get_shield answered 0.672 in the middle of that. The marines around the crashed lifeboat at the start of A30 read 0: they are the dead crew.

Player datum (0x4B0 bytes)

OffsetField
+0x00salt (0xEC70 for player 0)
+0x28controlled unit handle: what player_get (RVA 0x1b21e0) returns
+0x34the same handle again in A30. Meaning not established
+0x38a position near the unit's
+0xADteam, i8: 0 red, 1 blue … 8 neutral, -1 none. A player with no team never spawns (CU4 0x2ae6f0). Read since 2026-10-01

The gamertag is not in the datum.

Using it

mjolnir live arrays                       every data array, offset, fill, size
mjolnir live players                      each player, its team, unit and position
mjolnir live objects [--group bipd] [--filter marine] [--tsv out.tsv]
mjolnir live status                       now also names the simulation thread

A call takes about half a second, because the whole process's thread list is walked once. arrays needs no build profile. objects and players also name each object's tag, so they use the tag table's profile, as live tags does.

What this does not do yet

  • Reads only. Writing position or vitality is a plain write at these offsets. But object state is game state: a checkpoint revert restores it, and the simulation overwrites the transform of anything physics or animation is driving.
  • The datum offsets are CU4's. A game update keeps the TLS walk and the array headers working. It can move the datum fields, and the entry self-index and tag-handle checks are what would notice.