Blam Engine · The Deep Dive · Edition 21

Script → Presentation

Edition 11 documents the HaloScript virtual machine. Edition 10 documents the HUD, the camera and the sound mixer. Between them sits a layer nobody has written down: roughly four hundred tiny *_evaluate shims and the globals they poke, through which a designer's script actually moves the camera, prints to the HUD, plays a sound, opens a door, and — the surprise of this edition — drives a unit as a third pilot alongside the player and the AI. This is the seam, reconstructed from the source that crosses it.

Every claim traces to a file in src/, cited inline. Companion fact ledger: docs/deep_dive/md/21_script_presentation.md. Diagrams recolor with the theme; use the Theme button.

Chapter 01 · The seam

Four Hundred Tiny Functions

The HaloScript function table has 471 entries. Fifty-five of them are the virtual machine's own special forms. The other 416 are shims: three-statement adapters that unpack an argument block, call one engine function, and pack a result back. A hundred and one of those exist purely to change what the player sees, hears, or can operate.

In this chapter

The function table

Everything a script can say to the engine is one row of one array. hs_function_table is a const hs_function_definition *[471], and each entry is a 32-byte record with a variable-length tail: return_type at 0x00, name at 0x04, parse at 0x08, evaluate at 0x0C, documentation and parameters at 0x10 and 0x14, console_flags at 0x18, formal_parameter_count at 0x1A, and then formal_parameters[], an int16_t array of type codes, from 0x1C hs_function_definition.h.

The parse slot is hs_macro_function_parse for every ordinary builtin — compile-time arity and type checking lives there, not in the shim, and edition 11 owns that path device_set_power_definition.c. What makes these descriptors such good evidence is that they ship as literal .rdata records: the reconstructed source in src/data/ carries the decoded image bytes in its banner, so a reader can check every field against the binary without a debugger device_set_power_definition.c.

One descriptor, decoded from the binary

FIG. 01 / 34

The device_set_power row of hs_function_table, at 0x8211A0C0 in .rdata device_set_power_definition.c.

OffsetFieldImage wordMeaning
+0x00return_type0x0004hs_type_void
+0x04name0x82117AA8"device_set_power"
+0x08parse0x837787E0hs_macro_function_parse
+0x0Cevaluate0x83729238device_set_power_evaluate
+0x18console_flags0x00not a console-only command
+0x1Aformal_parameter_count2—
+0x1Cformal_parameters—hs_type_device, hs_type_real

Two pointers into code, one into a string table, and a two-element type list: that is the whole contract between the language and the engine hs_function_definition.h.

Census of 471 builtins

Harvesting all 471 *_definition.c banners in src/data/ and locating each named evaluator in the tree gives an exact census: 471 table entries, 471 distinct script names, and 459 distinct evaluator functions. The gap is the operators — +, -, * and / all point at hs_evaluate_arithmetic device_set_power_definition.c hs_function_definition.h.

Only 55 evaluators live in src/blam/hs/. Those are the VM's own special forms and generic machinery, and they are edition 11's subject. The remaining 416 are subsystem shims, and their distribution is a fair map of what HaloScript was actually used for: AI leads with 97, then game logic with 52 and units with 43, then the presentation families hs_function_definition.h.

471hs_function_table entries
459distinct evaluators
101presentation builtins
357return hs_type_void

Three quarters of the table returns hs_type_void: 357 of 471, against 58 booleans, 20 reals and 20 shorts, with a scattering of object and enum types below that hs_function_definition.h. HaloScript is overwhelmingly a command language, not an expression language. The presentation surface — the subject of this edition — is the union of the sound, interface, cutscene, device, rasterizer, camera and effects families: 101 of the 471 builtins exist to change what the player sees, hears, or can operate device_set_power_definition.c.

Where the 471 evaluators live

FIG. 02 / 34

Each table entry's evaluate pointer, resolved to the directory holding that function. The hs row is edition 11's territory; everything below the rule is a subsystem shim hs_function_definition.h device_set_power_definition.c.

DirectoryEntriesPresentation?
src/blam/hs55VM itself
src/blam/ai97—
src/blam/game52—
src/blam/units43—
src/blam/sound41yes — camera, HUD, sound, player effects
src/blam/main40—
src/blam/objects17—
src/blam/interface15yes — nav points, HUD text
src/blam/cutscene13yes — cinematics, recordings
src/blam/devices12yes — doors, lifts, switches
src/blam/cache10—
src/blam/rasterizer/dx98yes — gamma, near clip, lights
src/blam/saved_games8—
src/blam/networking7—
src/blam/rasterizer6yes — screen effects
src/blam/camera3yes — camera control
src/blam/effects3yes — screen fades
nine more directories1–2 each—

The sound row is the misleading one: it holds the 90-file scripted_* family, which is camera, HUD and player effects as much as it is audio scripted_camera_update.c scripted_hud_show_crosshair.c.

The shim shape

A leaf builtin's evaluator is three statements. Call hs_macro_function_evaluate(function_index, thread_index, initialize), which returns null while argument evaluation is still in flight and the evaluated argument block when it is complete; read typed arguments out of that block and call the engine function; then hs_return(thread_index, packed_result) scripted_hud_show_crosshair_evaluate.c. The whole of scripted_hud_show_crosshair_evaluate at 0x8372D678 is scripted_hud_show_crosshair(*arguments); hs_return(thread_index, 0); scripted_hud_show_crosshair_evaluate.c.

Three statements, and the one that can return null

FIG. 03 / 34

Every ordinary builtin's evaluator. The null return is not an error: it means the VM has more argument expressions to evaluate and will call this shim again next visit scripted_hud_show_crosshair_evaluate.c.

flowchart TD
  A["hs_thread_main() reaches the call node"] --> B["shim: hs_macro_function_evaluate(fn, thread, initialize)"]
  B -->|"returns NULL"| C["more arguments to evaluate — return, revisit next tick"]
  B -->|"returns argument block"| D["read typed slots out of the block"]
  D --> E["call the engine function"]
  E --> F["hs_return(thread, packed result)"]
  G["zero-argument builtin"] --> E

The shim is re-entered until its arguments are ready, so it must be free of side effects before the block arrives — which is exactly why the pattern is three statements and no more scripted_camera_time_evaluate.c.

Reading the argument block

Every argument occupies a four-byte slot, and a sub-word value sits at byte 0 of its slot — the packing rule edition 11 states and proves. In the shims that shows up as a small fixed vocabulary of spellings on one int *arguments pointer: a short at slot n is ((int16_t *)arguments)[2*n], a long or object index is arguments[n], a real is ((float *)arguments)[n], and a leading boolean is *(unsigned char *)arguments scripted_hud_set_timer_position_evaluate.c scripted_camera_set_evaluate.c.

The mixed cases are where the rule earns its keep. scripted_camera_set_evaluate at 0x8372B448 reads short, short, long scripted_camera_set_evaluate.c. player_effect_screen_fade_in_evaluate at 0x8372BF88 reads three reals and then a trailing short as ((int16_t *)arguments)[6] — halfword index 6 is byte 12, the front of slot 3 player_effect_screen_fade_in_evaluate.c. And hud_unit_activate_nav_point_with_flag_evaluate at 0x8372CDE8 manages all three widths in one call hud_unit_activate_nav_point_with_flag_evaluate.c.

Four bytes per argument, narrow values at the front

FIG. 04 / 34

The argument block for (activate_nav_point_flag <nav> <unit> <flag> <radius>), 16 bytes for four arguments of three different widths hud_unit_activate_nav_point_with_flag_evaluate.c activate_nav_point_flag_definition.c.

arguments + 0 + 4 + 8 + 12 slot 0 — short nav point index slot 1 — long unit object index slot 2 — short cutscene flag index slot 3 — real vertical offset bytes 0–1 bytes 2–3 unused bytes 8–9 bytes 10–11 unused *(int16_t *)arguments arguments[1] ((int16_t *)arguments)[4] ((float *)arguments)[3]

A short lives at the low address of its slot, which on this big-endian target is the high end of the word — so halfword index 4 reads slot 2, not slot 4. Getting that backwards is the single most common way to mis-read a shim hud_unit_activate_nav_point_with_flag_evaluate.c.

The return-packing rule

The mirror image governs hs_return. A narrow result is packed into the high end of the 32-bit result word: a boolean becomes (int)((uint8_t)value) << 24 and the VM extracts value >> 24; a short becomes (int)((uint16_t)value) << 16 and the VM extracts (int16_t)(value >> 16); a real is bit-reinterpreted into the whole word with *(float *)&result = ...; a long is passed verbatim; and a void builtin returns literal zero scripted_show_hud_evaluate.c scripted_camera_time_evaluate.c device_get_position_evaluate.c scripted_sound_time_evaluate.c.

recorded_animation_get_time_left_evaluate carries the disassembly detail that makes the rule concrete. A bare sth would leave slot bytes 2 and 3 uninitialised, so the compiler emits stw r11, 0x50(r1) at 0x83727DB0 to zero the whole word first, and only then sth 0x50(r1) at 0x83727DD0 to place the short at halfword 0 recorded_animation_get_time_left_evaluate.c.

Packing a narrow result into the high end of the word

FIG. 05 / 34

Five return shapes, one hs_return scripted_show_hud_evaluate.c recorded_animation_get_time_left_evaluate.c device_group_get_value_evaluate.c.

Declared typeShim writesVM extractsExample
hs_type_boolean((uint8_t)v) << 24value >> 24show_hud
hs_type_short_integer((uint16_t)v) << 16(int16_t)(value >> 16)camera_time
hs_type_real*(float *)&result = vwhole word, bit-identicaldevice_get_position
hs_type_long_integerresult = vwhole wordsound_impulse_time
hs_type_voidhs_return(thread, 0)nothinghud_show_crosshair

This is why so many shims look wrong at a glance: the shift is not arithmetic, it is the calling convention scripted_camera_time_evaluate.c.

Where the decompiler lies most

128 of the 462 *_evaluate.c files in the tree carry a DEVIATION note — an explicit record of a place where the reconstruction had to overrule the decompiler. The dominant class, 70 files, is exactly the packing rule above: the decompiler rendered the packed return as a narrow store through a pointer to the result word, which is correct only on a big-endian target, and each was respelled as an explicit shift ai_scripting_allegiance_broken_evaluate.c scripted_show_hud_evaluate.c. The second class, 21 files, is phantom arity: “the decompiler shows the engine call with three leftover-register arguments” for a function that takes none director_load_camera_evaluate.c.

The float-slot-skip ABI is the third recurring class, and it bites the presentation shims hardest because presentation arguments are floats. player_effect_screen_fade_in is genuinely (float, float, float, int16_t); the decompiler invented extra integer parameters a5, a6 and a7 out of the GPR slots those floats reserve player_effect_screen_fade_in.c. rasterizer_screen_effect_set_filter is worse: the decompiler produced ten parameters where the disassembly shows six — four floats in f1 to f4, an additive byte in r7, and the filter time in f5 rasterizer_screen_effect_set_filter.c. Even accelerate_to_position, the device convergence primitive of chapter 7, arrives bloated with phantom a9 through a12 because it has seven leading float parameters accelerate_to_position.c.

Script name is not C name

The name a designer types and the symbol that implements it are frequently unrelated, which is why the _definition.c banners are the only reliable index into this layer. The device family alone renames five of its six commands, and the pattern is consistent: the script vocabulary talks about positions and immediacy, the engine vocabulary talks about desired and actual values device_group_set_definition.c device_set_position_definition.c.

What the designer types, and what runs

FIG. 06 / 34

Sixteen of the presentation builtins whose script name gives no hint of the implementing symbol device_group_set_definition.c camera_set_definition.c hud_set_help_text_definition.c cinematic_abort_definition.c.

Script nameEvaluator
device_group_setdevice_group_set_desired_value_evaluate
device_group_set_immediatedevice_group_set_actual_value_evaluate
device_set_positiondevice_set_desired_position_evaluate
device_set_position_immediatedevice_set_actual_position_evaluate
device_group_getdevice_group_get_value_evaluate
camera_setscripted_camera_set_absolute_evaluate
camera_set_relativescripted_camera_set_evaluate
camera_controldirector_script_camera_evaluate
enable_hud_help_flashscripted_hud_set_flashing_state_evaluate
hud_set_help_textscripted_hud_set_state_message_evaluate
hud_set_timer_warning_timescripted_hud_set_timer_warning_cutoff_evaluate
recording_playrecorded_animation_play_evaluate
sound_impulse_startscripted_sound_new_evaluate
sound_looping_predictscripted_foley_predict_evaluate
cinematic_abortmain_skip_cinematic_evaluate
fade_inplayer_effect_screen_fade_in_evaluate

camera_set and camera_set_relative are the same engine function twice: scripted_camera_set_absolute is literally scripted_camera_set(index, ticks, -1) scripted_camera_set_absolute.c.

Sources: hs_function_definition.h device_set_power_definition.c scripted_hud_show_crosshair_evaluate.c scripted_camera_time_evaluate.c director_load_camera_evaluate.c scripted_hud_set_timer_position_evaluate.c scripted_camera_set_evaluate.c player_effect_screen_fade_in_evaluate.c hud_unit_activate_nav_point_with_flag_evaluate.c activate_nav_point_flag_definition.c scripted_show_hud_evaluate.c device_get_position_evaluate.c device_group_get_value_evaluate.c scripted_sound_time_evaluate.c recorded_animation_get_time_left_evaluate.c ai_scripting_allegiance_broken_evaluate.c player_effect_screen_fade_in.c rasterizer_screen_effect_set_filter.c accelerate_to_position.c device_group_set_definition.c device_set_position_definition.c camera_set_definition.c hud_set_help_text_definition.c cinematic_abort_definition.c scripted_camera_set_absolute.c scripted_camera_update.c scripted_hud_show_crosshair.c scripted_camera_set_animation.c recorded_animation_write_unit_control.c control_toggle.c.

Chapter 02 · Contract

Poke a Global, Wait for the Tick

No shim in this edition ever draws anything, plays anything, or moves anything. Each one writes a value into a small global block, and a later stage of the same tick — or the next tick's stage — reads it. The ordering inside game_tick is the contract the whole edition rests on.

In this chapter

Where scripts run inside a tick

game_tick runs its subsystems in a fixed order, and three facts about that order do most of the explaining in this edition. hs_update() — where every shim in chapter 1 fires — runs after units_update(), so a control packet a script writes this tick is consumed by the unit on the next one. recorded_animations_update() runs immediately after hs_update(), so a recording started by script this tick begins driving its unit in the same tick. And hud_update() and player_effect_update() run last, after objects_update(), so a HUD or camera-shake poke is picked up before the frame is drawn game_tick.c.

The device family sits inside objects_update(): device_update is the datum_update slot of the device object type, so every placed door and lift converges toward its group's value in the middle of the tick, after the scripts that may have moved that value device_data_definition.c device_update.c.

One tick, in order — where the poke lands and where it is read

FIG. 07 / 34

The subsystem order inside game_tick, with the stages this edition cares about game_tick.c.

flowchart TD
  U["units_update() — units consume last tick's control"] --> AI["ai_update()"]
  AI --> P1["players_update_before_game_server()"]
  P1 --> EF["effects_update()"]
  EF --> VF["vibrate_update() · first_person_weapons_update()"]
  VF --> GE["game_engine_update() · editor_update()"]
  GE --> HS["hs_update() — every *_evaluate shim fires here"]
  HS --> RA["recorded_animations_update() — pushes unit_control()"]
  RA --> OU["objects_update() — device_update() converges"]
  OU --> PA["players_update_after_game()"]
  PA --> HU["hud_update()"]
  HU --> PE["player_effect_update()"]

A script's poke is never the effect. It is a value left behind for one of the four stages below it, and for units_update that means a one-tick delay game_tick.c.

The blocks a script pokes

The scripted-presentation state is not one structure. It is ten separate symbols in src/data/, nine of which ship as zero and are filled by game_state_malloc or game_state_data_new during subsystem initialisation cinematic_initialize.c devices_initialize.c recorded_animations_initialize.c.

The exception is worth pausing on. music_gain_in_profile at 0x8417476C ships with image bytes 0xBF800000 — a literal -1.0f baked into .data. That is the “no gain saved” sentinel cinematic_start tests before stashing the player's music volume, and it is the reason a cutscene that ends twice does not restore the wrong level music_gain_in_profile.c cinematic_start.c cinematic_stop.c.

camera_script_globals at 0x84177CA0 is the only one of the ten that is a struct rather than a pointer, and its 64 initialised bytes are quotable in full: mode = 0xFFFF, camera_point_index = 0xFFFF, forward = (0, 0, 1), up = (0, 1, 0), field_of_view = 0x3F9C61AA — that is 1.22173047f, exactly 70 degrees — relative_object_index = 0xFFFFFFFF, animation_graph_index = 0xFFFFFFFF, everything else zero camera_script_globals.c.

Ten symbols the scripted-presentation layer writes

FIG. 08 / 34

Every address is the symbol's own location in .data, decoded from the binary record in its src/data/ banner camera_script_globals.c hud_scripted_globals.c cinematic_globals.c device_groups_data.c.

SymbolAddressShapeChapter
camera_script_globals0x84177CA064-byte struct, data-init3
hud_scripted_globals0x8445CE6Cpointer to a 4-byte struct4
hud_messaging_globals—pointer to a 2280-byte struct4
unit_hud_globals0x84429FC0pointer; carries script_flags4
weapon_hud_globals0x84429C08pointer; carries script_flags4
cinematic_globals0x8441E654pointer to a 28-byte struct5
music_gain_in_profile0x8417476Cfloat, ships 0xBF8000005
animation_threads0x8445D3D4pointer to 64 × 100-byte data_array6
device_groups_data0x8465C984pointer to 1024 × 8-byte data_array7
player_effect_globals0x8445FEFCpointer to a 532-byte struct8

Two of the ten are data_array pools rather than flat structs — recorded animations and device groups are the two script-driven systems with more than one instance in flight recorded_animations_initialize.c devices_initialize.c.

Sources: game_tick.c device_data_definition.c device_update.c cinematic_initialize.c devices_initialize.c recorded_animations_initialize.c music_gain_in_profile.c cinematic_start.c cinematic_stop.c camera_script_globals.c hud_scripted_globals.c cinematic_globals.c device_groups_data.c unit_hud_globals.c weapon_hud_globals.c player_effect_globals.c animation_threads.c hud_messaging_globals_definition.h.

Chapter 03 · Camera

Sixty-Two Bytes That Own the View

Taking the camera away from the player is not a flag the normal camera checks. It is a function-pointer swap inside the director: script control replaces each local player's camera procedure with scripted_camera_update, which every frame reads one 62-byte struct and emits an observer command. Six setters write that struct. One of them, in the reconstructed source, writes it backwards.

In this chapter

The state block

camera_script_globals is DB-verified against the anonymous type $49197FBDBC1AD3D1BAA83ADB63B3EA44, and its 62 used bytes hold everything the scripted camera knows: enabled at 0x00, first_update at 0x01, mode at 0x02, camera_point_index at 0x04, timer at 0x08 in seconds, point at 0x0C, forward at 0x18, up at 0x24, field_of_view at 0x30, relative_object_index at 0x34, animation_graph_index at 0x38, and animation_index at 0x3C camera_script_globals.h.

Four modes, from the headers_ref enum _C88BF5B7086AEE7EF472F9DDBF6F9F07: _camera_script_mode_point (0), _camera_script_mode_animation (1), _camera_script_mode_first_person (2), and _camera_script_mode_dead (3) camera_script_mode.h scripted_camera_update.c.

Taking control

The script command is camera_control, which routes through director_script_camera_evaluate to director_script_camera(enabled) at 0x836E5118. For both local players it sets debug_input_scale = 1.0f, points director->camera_proc at scripted_camera_update, clears debug_controls, and calls scripted_camera_enable(enabled). Disabling reverts each player through director_choose_game_perspective(local_player, 1) director_script_camera.c.

scripted_camera_enable at 0x83704DC0 also sets first_update = 1, so the next update snaps to the new viewpoint instead of interpolating toward it — the same flag every setter raises scripted_camera_enable.c.

Script control is a function-pointer swap, not a flag

FIG. 09 / 34

What (camera_control true) actually does to the director director_script_camera.c scripted_camera_enable.c.

sequenceDiagram
  participant S as script thread
  participant E as director_script_camera_evaluate
  participant D as director_globals
  participant C as camera_script_globals
  participant U as scripted_camera_update
  S->>E: (camera_control true)
  E->>D: director_camera_scripted = 1
  loop both local players
    E->>D: debug_input_scale = 1.0, debug_controls = 0
    E->>D: camera_proc = scripted_camera_update
  end
  E->>C: scripted_camera_enable(1) — enabled = 1, first_update = 1
  Note over D,U: every later frame, the director calls camera_proc
  D->>U: camera_proc(camera, controls, result)
  U->>C: read mode, timer, point, forward, up
  U-->>D: observer_command

Disabling does not restore a saved pointer — it calls director_choose_game_perspective(local_player, 1), which re-derives the right procedure from the player's current state director_script_camera.c.

The six setters

scripted_camera_set(camera_point_index, tick_count, relative_to_object_index) at 0x83704F68 is the workhorse. It reads a 104-byte scenario_cutscene_camera_point — position at 0x28, euler angles at 0x34, field of view at 0x40 — converts the angles through vectors3d_from_euler_angles3d, substitutes 1.2217305f when the tag's field of view is zero, sets mode 0 and first_update, and sets timer = tick_count / 30 as integer division, exactly as compiled. Then it calls director_update(0.0f) and observer_update(0.000099999997f, 0) so the new viewpoint takes effect on the spot rather than next frame scripted_camera_set.c.

scripted_camera_set_camera_point_relative at 0x83705040 is the same thing from an explicit position/forward/up frame rather than a tag camera point, and its _absolute twin is a bare tail call — li r8, -1; b scripted_camera_set_camera_point_relative, confirmed in disassembly, not the blr the decompiler suggested scripted_camera_set_camera_point_relative.c scripted_camera_set_camera_point_absolute.c.

The three cheap setters latch a unit and a mode and do nothing else: scripted_camera_set_first_person at 0x83704ED8 and scripted_camera_set_dead at 0x83704F00 both no-op on -1 scripted_camera_set_first_person.c scripted_camera_set_dead.c. scripted_camera_set_animation at 0x83704DD8 requires the graph's type word to be 1, linear-searches the 180-byte animation records for a case-insensitive name match, then sets mode 1, forces field_of_view = 1.2217305f, and sets timer = anim->frame_count / 30 scripted_camera_set_animation.c.

Two readers complete the surface. scripted_camera_time() at 0x83705518 converts the timer back to ticks with (uint16_t)(int)(timer * 30.0f) scripted_camera_time.c, and scripted_camera_object_is_first_person_camera(object_index) at 0x83704F28 is the query the rest of the engine uses: enabled, mode 2, and bound to that object scripted_camera_object_is_first_person_camera.c.

Six setters, four modes, one struct

FIG. 10 / 34

Which fields of camera_script_globals each setter writes scripted_camera_set.c scripted_camera_set_animation.c scripted_camera_set_first_person.c scripted_camera_set_dead.c.

SetterModeTimer sourceAlso writes
scripted_camera_set0 pointtick_count / 30point, forward, up, FOV, camera_point_index, relative object
..._set_camera_point_relative0 pointtick_count / 30point, forward, up, FOV; camera_point_index = -1
..._set_camera_point_absolute0 pointtick_count / 30tail call with relative_to_object_index = -1
..._set_animation1 animationframe_count / 30animation_index, graph index, FOV forced to 70°
..._set_first_person2 first personuntouchedrelative_object_index only
..._set_dead3 dead camuntouchedrelative_object_index only

Modes 2 and 3 never touch the timer, so a first-person or death-cam handoff runs until something else changes the mode — there is no duration argument for either scripted_camera_set_first_person.c.

The consumer

scripted_camera_update(camera, controls, result) at 0x83705140 produces one observer_command per frame. It always sets result->flags to 1 << _observer_command_force_time_bit, adds the freeze bit when game_time_get_paused(), and finishes by decrementing the script timer by controls->seconds_elapsed * game_time_get_speed(), clamped at zero, and clearing first_update scripted_camera_update.c.

The animated branch is the one with real arithmetic: the frame index is (int16_t)(int)((float)frame_count - timer * 30.0f), clamped to [0, frame_count - 1], and the root matrix at that frame supplies forward from row 0, up from row 2 and position from row 3. Field of view is hardcoded to 1.2217305f here rather than read from the globals, and both focus_distance and result->timer are zeroed scripted_camera_update.c. The first-person branch defers entirely to first_person_camera_fake; the dead branch calls dead_camera_new once on first_update and then dead_camera_update every frame scripted_camera_update.c.

Four branches, then always the timer

FIG. 11 / 34

One frame of scripted_camera_update. The timer decrement runs whatever the mode, including modes that never set it scripted_camera_update.c.

flowchart TD
  A["scripted_camera_update(camera, controls, result)"] --> B["flags = force_time; add freeze if game_time_get_paused()"]
  B --> C{"camera_script_globals.mode"}
  C -->|"0 point"| D{"relative_object_index == -1 ?"}
  D -->|"yes"| E["focus_position = camera_script_globals.point"]
  D -->|"no"| F["focus = object bounding_sphere_center; point becomes a look-at offset"]
  C -->|"1 animation"| G["frame = frame_count - timer*30, clamped"]
  G --> H["animation_get_root_matrix() — forward row 0, up row 2, position row 3"]
  C -->|"2 first person"| I["first_person_camera_fake(relative unit, result)"]
  C -->|"3 dead"| J["dead_camera_new() on first_update, then dead_camera_update()"]
  E --> K["timer -= seconds_elapsed * game_time_get_speed(), clamped at 0"]
  F --> K
  H --> K
  I --> K
  J --> K
  K --> L["first_update = 0"]

Mode 1 hardcodes a 70-degree field of view and ignores the one in the globals; modes 2 and 3 write no timer at all, so the decrement runs against whatever a previous camera_set left there scripted_camera_update.c.

The anchored look-at

Mode 0 has two sub-cases, and the second is the interesting one. With no anchor object the camera simply sits at camera_script_globals.point. With an anchor, the focus moves to the object's bounding_sphere_center and the script point stops being a position at all: it becomes a look-at offset expressed in the camera's own yaw frame scripted_camera_update.c.

The script point is projected onto the view direction, and the projection is clamped to zero or less — a point in front of the camera contributes no distance. focus_distance becomes the negated projection, the residual offset is rotated by angle = atan2(forward.n[1], forward.n[0]), and the rotated components are written into focus_offset scripted_camera_update.c. That atan2 call is one of the recorded DEVIATIONs: the decompiler mis-split a packed double and left the second argument as an uninitialised local, so the whole rotation was reading garbage until it was traced back to forward.n[0] scripted_camera_update.c.

An anchored camera point is an offset, not a position

FIG. 12 / 34

The mode-0 anchored path, in the order the code computes it scripted_camera_update.c.

focus_position object bounding_sphere_center not the script point dot = forward · point clamped: if dot > 0 then dot = 0 focus_distance = -dot offset = point - forward * dot the residual, perpendicular part angle = atan2(forward.n[1], forward.n[0]) focus_offset.n[0] = sin·offset.y + cos·offset.x focus_offset.n[1] = sin·offset.x - cos·offset.y  ·  focus_offset.n[2] = offset.z observer_command position_flags = valid, position_timer = 0

Because the projection is clamped at zero, a script point in front of the camera yields focus_distance = 0 and a pure lateral offset — which is what makes an anchored cutscene camera orbit its subject rather than fly through it scripted_camera_update.c.

A proven defect

One reconstructed file in this family disagrees with the binary, and the disagreement is load-bearing. scripted_camera_set_animation.c as written stores the graph index into relative_object_index and -1 into animation_graph_index, and its DEVIATION comment asserts the binary does this via a single fused 64-bit store scripted_camera_set_animation.c.

The binary does the opposite, in two separate word stores. stw r26, animation_graph_index(r6) at 0x83704EA0 writes the graph index — r26 is the first argument, saved at mr r26, r3 at 0x83704DE4 — and stw r8, relative_object_index(r6) at 0x83704EA4 writes -1, loaded at li r8, -1 at 0x83704E80. The DB's own types_members for the anonymous type puts relative_object_index at offset 52 and animation_graph_index at 56, and IDA renders both stores through that applied type camera_script_globals.h.

The reader settles it. scripted_camera_update's animation branch loads lwz r11, animation_graph_index(r30) at 0x83705388 and uses that word as the tag index for global_tag_instances. The binary is self-consistent; the reconstruction is not. As written, the reconstructed setter would leave camera_set_animation fetching tag index -1 scripted_camera_update.c scripted_camera_set_animation.c. This is reported, not fixed — the source tree belongs to another campaign.

Writer and reader, as reconstructed and as shipped

FIG. 13 / 34

The two fields at offsets 52 and 56, written by the setter and read by the updater scripted_camera_set_animation.c scripted_camera_update.c camera_script_globals.h.

flowchart LR
  W1["binary: stw r26 (graph index) @0x83704EA0"] --> F1["animation_graph_index — offset 56"]
  W2["binary: stw r8 (-1) @0x83704EA4"] --> F2["relative_object_index — offset 52"]
  W3["source: relative_object_index = graph index"] -.-> F2
  W4["source: animation_graph_index = -1"] -.-> F1
  F1 --> R["scripted_camera_update: lwz r11, animation_graph_index @0x83705388"]
  R --> T["TAG_GET(animation_graph, index)"]

Solid edges are the shipped binary, dashed edges the reconstructed source. Follow the dashed pair into the reader and the animated camera tag-gets index -1 scripted_camera_set_animation.c.

Sources: camera_script_globals.h camera_script_globals.c camera_script_mode.h director_script_camera.c scripted_camera_enable.c scripted_camera_set.c scripted_camera_set_camera_point_relative.c scripted_camera_set_camera_point_absolute.c scripted_camera_set_first_person.c scripted_camera_set_dead.c scripted_camera_set_animation.c scripted_camera_time.c scripted_camera_object_is_first_person_camera.c scripted_camera_update.c.

Chapter 04 · HUD

Two Bytes, Two Flag Words, One Timer

Twenty-odd script commands reach the heads-up display, and between them they write remarkably little: two bytes of global visibility, six bits in one flag word, one bit in another, a sixteen-byte timer, two message pointers, and a flash timestamp. Everything else is the renderer reading those and deciding what to draw.

In this chapter

Two bytes and two flag words

hud_scripted_globals_definition is four bytes, of which two matter: show_hud at 0x00 and show_hud_help_text at 0x01 hud_scripted_globals.h. scripted_show_hud(flag) at 0x83707E90 and scripted_show_hud_help_text(flag) at 0x83707EA8 each write their byte and return it, which is why both are declared hs_type_boolean rather than hs_type_void — the same read-back-your-own-argument shape player_camera_control uses scripted_show_hud.c scripted_show_hud_help_text.c show_hud_definition.c.

Panel visibility and blink live in unit_hud_globals->script_flags, indexed by the DB-verified hud_panel_flags enum (types_enum_values _88CA016EC8DEC4DDE83B82E6CF459496): _hud_panel_health_dont_show_bit 0, _hud_panel_health_blink_bit 1, _hud_panel_shield_dont_show_bit 2, _hud_panel_shield_blink_bit 3, _hud_panel_motion_sensor_dont_show_bit 4, _hud_panel_motion_sensor_blink_bit 5, with NUMBER_OF_SCRIPTED_UNIT_PANELS at 6 hud_panel_flags.h.

The polarity is split, deliberately and inconsistently. The three hud_show_* builtins clear a dont_show bit when showing; the three hud_blink_* builtins set a blink bit when blinking — on the same word scripted_hud_show_health.c scripted_hud_blink_health.c. The crosshair lives somewhere else again, in weapon_hud_globals->script_flags, and inverts back to a positive “show” bit: scripted_hud_show_crosshair at 0x836AE990 sets _hud_crosshair_show_bit (0) when the crosshair should be visible scripted_hud_show_crosshair.c hud_crosshair_show_flags.h.

Seven bits, three polarities, two words

FIG. 14 / 34

Every scripted HUD flag in the engine, with the builtin that writes it and the sense in which it is written hud_panel_flags.h hud_crosshair_show_flags.h scripted_hud_show_shield.c scripted_hud_blink_motion_sensor.c.

WordBitNameScript commandSense
unit_hud_globals0_hud_panel_health_dont_show_bithud_show_healthcleared to show
unit_hud_globals1_hud_panel_health_blink_bithud_blink_healthset to blink
unit_hud_globals2_hud_panel_shield_dont_show_bithud_show_shieldcleared to show
unit_hud_globals3_hud_panel_shield_blink_bithud_blink_shieldset to blink
unit_hud_globals4_hud_panel_motion_sensor_dont_show_bithud_show_motion_sensorcleared to show
unit_hud_globals5_hud_panel_motion_sensor_blink_bithud_blink_motion_sensorset to blink
weapon_hud_globals0_hud_crosshair_show_bithud_show_crosshairset to show

Three commands out of seven mean the opposite of what their name suggests at the bit level, which is exactly the kind of detail a re-source campaign has to get from the enum rather than from the call site scripted_hud_show_crosshair.c.

Where the renderer reads them

crosshairs_draw bails out on its first line if (weapon_hud_globals->script_flags & 1) == 0 — a scripted crosshair hide is a whole-function early return, not a transparency crosshairs_draw.c. hud_render_unit_interface tests _hud_panel_shield_dont_show_bit before drawing the shield panel at all, and then folds _hud_panel_shield_blink_bit into the panel's draw flags beside the natural low-shield blink: the condition is shield_vitality < 0.25f or the script bit hud_render_unit_interface.c.

That is the notable design fact here. Script blink and gameplay blink are the same draw flag, so a scripted blink is indistinguishable on screen from a genuine low-shield warning — a deliberate reuse that lets a designer fake a damage warning during a cutscene. The health panel does exactly the same with _object_shield_depleted_bit or _hud_panel_health_blink_bit hud_render_unit_interface.c.

From a script line to a drawn panel

FIG. 15 / 34

The full path for (hud_blink_shield true), across two tick stages scripted_hud_blink_shield.c hud_render_unit_interface.c game_tick.c.

flowchart TD
  A["(hud_blink_shield true)"] --> B["scripted_hud_blink_shield_evaluate — reads *arguments"]
  B --> C["scripted_hud_blink_shield(1) @0x836D6788"]
  C --> D["unit_hud_globals->script_flags |= 1 << _hud_panel_shield_blink_bit"]
  D --> E["…tick ends…"]
  E --> F["hud_render_unit_interface"]
  F --> G{"script_flags & shield_dont_show ?"}
  G -->|"set"| H["panel not drawn at all"]
  G -->|"clear"| I{"shield_vitality < 0.25 OR script blink bit ?"}
  I -->|"either"| J["shield_flags = 1 — blinking meter"]
  I -->|"neither"| K["shield_flags = 0 — steady meter"]

The renderer cannot tell a scripted blink from a real one, because the two conditions are ORed into one flag hud_render_unit_interface.c.

The timer, and its two representations

hud_timer_data_definition is sixteen bytes: reference_time at 0x0, ticks at 0x4, flash_cutoff at 0x6, position at 0x8, corner at 0xC, paused at 0xE, enabled at 0xF hud_timer_data_definition.h. It lives at offset 0x8D8 of the 2280-byte hud_messaging_globals_definition hud_messaging_globals_definition.h.

The subtlety is that ticks means two different things depending on paused. While running, it is a game-time-anchored value that must be corrected against reference_time and the current clock; while paused, it is the absolute remaining count. scripted_hud_pause_timer(paused) at 0x836A4278 does not stop a clock — it converts between the two representations, and only when ticks > 0 scripted_hud_pause_timer.c. scripted_hud_get_timer_ticks() at 0x836A4330 reads them back symmetrically: zero if disabled, the raw value if paused or if ticks is -1, otherwise ticks + reference_time - game_time_get() scripted_hud_get_timer_ticks.c.

One field, two meanings, converted on pause

FIG. 16 / 34

The HUD countdown timer's two states and the arithmetic that moves between them scripted_hud_pause_timer.c scripted_hud_get_timer_ticks.c scripted_hud_set_timer_time.c.

stateDiagram-v2
  [*] --> Disabled
  Disabled --> Running : hud_set_timer_time — ticks = 30*(60*m+s), reference_time = now
  Running --> Paused : pause_hud_timer true — ticks += reference_time - now
  Paused --> Running : pause_hud_timer false — ticks = now + ticks - reference_time
  Running --> Disabled : show_hud_timer false
  Paused --> Disabled : show_hud_timer false
  note right of Running : ticks is game-time anchored; readers subtract now
  note right of Paused : ticks is the absolute remaining count

Both conversions are guarded by ticks > 0, so pausing an already-expired timer leaves the stored value alone scripted_hud_pause_timer.c.

Messages, objectives, flashing

scripted_hud_set_state_message(message_index) at 0x836A3FD8 is gated on hud_scripted_globals->show_hud_help_text: with help text turned off, the command silently does nothing. When it does run, it points hud_messaging_globals->help_message at the 64-byte hud_state_message_definition record inside the scenario's HUD-messages tag scripted_hud_set_state_message.c.

scripted_hud_set_objective(message_index) at 0x836A40F0 is pickier: it accepts a message only when it has exactly one element and that element's type is zero. If it passes, the objective's uptime comes not from the script but from the HUD globals tag — up_ticks + fade_ticks read out of hud_globals->messaging.objective_color.custom.objective scripted_hud_set_objective.c.

Flashing is a phase problem solved with a timestamp. scripted_hud_set_flashing_state(flash) at 0x836A4038 records flash_start_time = game_time_get() only on the off-to-on transition, so repeatedly enabling flashing does not restart the animation scripted_hud_set_flashing_state.c; the separate hud_help_flash_restart command exists precisely to re-stamp it, and it only does so while flashing is already on scripted_hud_restart_flashing.c. scripted_hud_messages_clear() at 0x836A4AB0 walks both message_data slots and all four queued messages in each, clearing valid scripted_hud_messages_clear.c.

Nav points

Eight builtins, all hs_type_void, all in src/blam/interface/, and all four activate forms have a matching deactivate. They vary along two axes: whose display the marker appears on (one unit's player, or a whole team) and what it is anchored to (a cutscene flag, or an object) hud_unit_activate_nav_point_with_flag_evaluate.c activate_nav_point_flag_definition.c.

The unit forms resolve the unit to a player first and no-op when the unit is not player-controlled: player_index_from_unit_index(unit_index), then hud_activate_nav_point(nav_index, player_index, _nav_point_flag, flag_index, vertical_offset) hud_unit_activate_nav_point_with_flag.c. Its DEVIATION is the soft-float trap once more: the vertical offset arrives as a double through the ABI and is a float hud_unit_activate_nav_point_with_flag.c.

Read as a grid, the eight commands vary along exactly two axes — whose display the marker appears on, and what it is anchored to activate_nav_point_flag_definition.c hud_unit_activate_nav_point_with_flag_evaluate.c.

AnchorOne unit's playerA whole team
cutscene flagactivate_nav_point_flag / deactivate_nav_point_flagactivate_team_nav_point_flag / deactivate_team_nav_point_flag
objectactivate_nav_point_object / deactivate_nav_point_objectactivate_team_nav_point_object / deactivate_team_nav_point_object
parametersnavpoint, unit, anchor, realnavpoint, team, anchor, real
deactivate parametersunit, anchorteam, anchor

The activate forms carry a trailing hs_type_real — the vertical offset that lifts the marker off the anchor point hud_unit_activate_nav_point_with_flag.c.

Sources: hud_scripted_globals.h scripted_show_hud.c scripted_show_hud_help_text.c show_hud_definition.c hud_panel_flags.h hud_crosshair_show_flags.h scripted_hud_show_health.c scripted_hud_show_shield.c scripted_hud_show_motion_sensor.c scripted_hud_blink_health.c scripted_hud_blink_shield.c scripted_hud_blink_motion_sensor.c scripted_hud_show_crosshair.c crosshairs_draw.c hud_render_unit_interface.c game_tick.c hud_timer_data_definition.h hud_messaging_globals_definition.h scripted_hud_pause_timer.c scripted_hud_get_timer_ticks.c scripted_hud_set_timer_time.c scripted_hud_set_timer_position.c scripted_hud_show_timer.c scripted_hud_set_timer_warning_cutoff.c scripted_hud_set_state_message.c scripted_hud_set_objective.c scripted_hud_set_flashing_state.c scripted_hud_restart_flashing.c scripted_hud_messages_clear.c hud_unit_activate_nav_point_with_flag.c hud_unit_activate_nav_point_with_flag_evaluate.c activate_nav_point_flag_definition.c.

Chapter 05 · Cutscene

Twenty-Eight Bytes of Cutscene

The entire cinematic system's runtime state is a 28-byte allocation: a letterbox amount, three flag bytes, and four subtitle slots of four bytes each. Everything a cutscene does to the game — muting input, silencing AI chatter, deleting live projectiles, taking the post-process chain — is done by two functions at the boundaries, and the subtitle delay is implemented by storing a negative number.

In this chapter

The globals

cinematic_globals_definition is 28 bytes: letter_box_amount at 0x00 (a float from 0 to 1), letter_box_last_game_time at 0x04, then the three state bytes letter_box, cinematic_in_progress and cinematic_skip_in_progress at 0x08 to 0x0A, cinematic_suppress_bsp_object_creation at 0x0B, and cinematic_title_datum active_titles[4] at 0x0C cinematic_globals_definition.h. Each title slot is four bytes: title_index and title_timer cinematic_title_datum.h.

cinematic_initialize allocates exactly that: game_state_malloc("cinematic globals", 0, 28) cinematic_initialize.c. cinematic_dispose is a no-op — per-subsystem state is freed by tearing down the game-state arena cinematic_dispose.c. cinematic_initialize_for_new_map zeroes the header, sets all four title slots to {-1, -1}, and resets music_gain_in_profile to -1.0f cinematic_initialize_for_new_map.c, while cinematic_dispose_from_old_map clears only letter_box and cinematic_in_progress cinematic_dispose_from_old_map.c.

Start and stop

cinematic_start() at 0x83690EC8 does seven things in order: fires the HCEX host event, calls hcex_start_cine(), saves the current music gain into music_gain_in_profile if that sentinel is still -1.0f and forces music to 1.0f, disables player input, disables AI dialogue triggers, raises the letterbox with a fresh letter_box_last_game_time stamp and sets cinematic_in_progress, and finally calls projectiles_delete_all() — a cutscene starts with no bullets in the air cinematic_start.c.

cinematic_stop() at 0x836917C8 unwinds all of that and rather more besides: it restores the saved gain and resets the sentinel, lowers the letterbox, re-enables input and AI dialogue, clears cinematic_in_progress, calls rasterizer_screen_effects_initialize_for_new_map(), zeroes all four channels of global_rasterizer_model_ambient_reflection_tint, resets the near clip distance to 0.0f, calls display_errors_deferred_until_cinematic_stop(), and then notifies the host cinematic_stop.c. Console errors raised during a cutscene are held back and flushed there — a shipped decision to keep debug spew off the screen during a take cinematic_stop.c.

Skipping is a separate two-bit state. cinematic_skip_start() at 0x83690F78 sets the flag cinematic_skip_start.c; cinematic_skip_stop() at 0x83690F90 restores the music gain through the same -1.0f sentinel dance as cinematic_stop and clears it cinematic_skip_stop.c. Note the name: cinematic_can_be_skipped() at 0x83690F68 returns cinematic_skip_in_progress, so it answers “is a skip already running”, not “is this cutscene skippable” cinematic_can_be_skipped.c. And enable_cinematic_mode(enable) at 0x836B5B80 reaches across the bridge to write haloSoundSystem->isCinematicMode at offset 0x12 of an opaque HCEX C++ object enable_cinematic_mode.c.

What a cutscene takes, and what it gives back

FIG. 17 / 34

The two boundary functions, side by side. Stop does everything start did, plus four resets start never touched cinematic_start.c cinematic_stop.c.

sequenceDiagram
  participant S as script
  participant C as cinematic_globals
  participant G as game systems
  participant H as HCEX host
  S->>H: cinematic_start — hcex_fire_event, hcex_start_cine
  S->>G: save music gain, force to 1.0
  S->>G: player_input_enable(0), ai dialogue triggers off
  S->>C: letter_box = 1, cinematic_in_progress = 1
  S->>G: projectiles_delete_all()
  Note over S,G: …the cutscene plays…
  S->>G: cinematic_stop — restore music gain, sentinel back to -1.0
  S->>C: letter_box = 0, cinematic_in_progress = 0
  S->>G: input on, AI dialogue on
  S->>G: screen effects reset, ambient reflection tint zeroed, near clip 0.0
  S->>G: display_errors_deferred_until_cinematic_stop()
  S->>H: hcex_fire_event, hcex_stop_cine

The asymmetry is deliberate: stop is also the cleanup path for anything the cutscene's own screen-effect and near-clip commands changed cinematic_stop.c.

Titles: the negative-timer trick

cinematic_set_title_delayed(index, delay) at 0x836911D8 finds the first free of the four slots — the one whose title_index reads 0xFFFF — stores the index, and stores the timer as (int16_t)(int)(delay * -30.0f). Negative ticks cinematic_set_title_delayed.c. cinematic_set_title(index) is just the delayed form with 0.0f cinematic_set_title.c, and cinematic_force_title(index) at 0x83691250 skips the search entirely and overwrites slot 0 cinematic_force_title.c.

There is no pending state, no queue, and no separate timer. The delay is implemented entirely by the renderer's fade arithmetic. cinematic_render adds the elapsed ticks to title_timer every frame and computes fade_fraction = title_timer / title->fade_in_time while the timer is below fade_in_time, then clamps the fraction into [0, 1]. A negative timer produces a negative fraction, which clamps to zero: the title is drawn, at zero alpha, every frame until the timer climbs through zero and the real fade-in begins cinematic_render.c.

A delay implemented as a negative number

FIG. 18 / 34

One subtitle slot's title_timer over its life, from a (cinematic_set_title_delayed T 2.0) cinematic_set_title_delayed.c cinematic_render.c.

stateDiagram-v2
  [*] --> Free : title_index = -1, title_timer = -1
  Free --> Delayed : set_title_delayed(T, 2.0) — timer = -60
  Delayed --> FadingIn : timer crosses 0
  FadingIn --> Up : timer >= fade_in_time
  Up --> FadingOut : timer > up_time
  FadingOut --> Free : timer >= up_time + fade_out_time
  note right of Delayed : drawn every frame at alpha 0 — the clamp does the waiting
  note right of Free : cinematic_force_title overwrites slot 0 regardless of state

Four slots, no queue: a fifth cinematic_set_title with all four occupied is silently dropped cinematic_set_title_delayed.c.

cinematic_render

cinematic_render() at 0x83691280 is the per-frame overlay draw, called from interface_draw_fullscreen_overlays cinematic_render.c interface_draw_fullscreen_overlays.c. The letterbox half integrates letter_box_amount by delta_ticks * SECONDS_PER_TICK toward 1 (or away from it when lowering), then draws two opaque black quads at the top and bottom of render.camera.viewport_bounds, each viewport_height * (letter_box_amount * 0.125f) tall — one eighth of the screen per bar at full extension cinematic_render.c.

The title half scales the tag-authored bounds from a 640×480 reference to the live viewport, falls back to hud_globals->defaults.default_title_bounds when the tag's rectangle is degenerate, applies the fade fraction to both the foreground alpha and the shadow alpha, draws through rasterizer_draw_unicode_string, advances the timer by game_time_get_elapsed() — zero while paused — and retires the slot once title_timer >= fade_out_time + up_time cinematic_render.c.

This is also one of the functions the reconstruction refused to take from the decompiler. The letterbox geometry and the tag-bounds scaling block were rebuilt from disasm_range(0x836912D0, 0x83691448) and disasm_range(0x836914F0, 0x8369160C), because the decompiler had round-tripped the rectangle2d locals through 64-bit stack slots and read paired 32-bit field loads as lone 16-bit ones cinematic_render.c.

One overlay frame — bars, then up to four titles

FIG. 19 / 34

The two independent halves of cinematic_render; the title loop runs whether or not the letterbox is up cinematic_render.c.

flowchart TD
  A["cinematic_render()"] --> B{"letter_box set OR amount > 0, and UI widgets inactive ?"}
  B -->|"no"| T["skip bars"]
  B -->|"yes"| C["amount += delta_ticks * SECONDS_PER_TICK — or -= when lowering"]
  C --> D["bar height = viewport_height * amount * 0.125"]
  D --> E["draw_quad top and bottom, colour 0xFF000000"]
  T --> F["for each of 4 active_titles"]
  E --> F
  F --> G{"title_index == -1, or no font, or no help-text tag ?"}
  G -->|"any"| F
  G -->|"none"| H["scale tag bounds 640x480 to viewport, or default_title_bounds"]
  H --> I["fade_fraction from title_timer vs fade_in_time and up_time, clamped 0..1"]
  I --> J["draw string with faded foreground and shadow alpha"]
  J --> K["title_timer += game_time_get_elapsed(), 0 while paused"]
  K --> L{"timer >= up_time + fade_out_time ?"}
  L -->|"yes"| M["slot released — index and timer back to -1"]

The retirement test is skipped entirely in the editor (game_in_editor()), so an editor preview holds a title on screen indefinitely cinematic_render.c.

Screen effects and near clip

Six cinematic_screen_effect_* builtins route out of the cutscene family entirely, into src/blam/rasterizer/ cinematic_screen_effect_start_definition.c. rasterizer_screen_effect_start(clear) at 0x83724328 zeroes the 0x38-byte cinematic_screen_effect_globals on first use or on request, sets initialized, and sets has_control — the script literally takes the post-process block from whatever else was driving it rasterizer_screen_effect_start.c.

rasterizer_screen_effect_set_filter at 0x83724440 stores the light enhancement and desaturation intensity endpoints as interpolation pairs, clears every video-feedback parameter, and sets the interpolation window to [now, now + filter_time] where now = (float)game_time_get() * SECONDS_PER_TICK rasterizer_screen_effect_set_filter.c. Everything is a pair of endpoints and a pair of times, so the effect self-interpolates without any per-frame script involvement.

Seven builtins carry the cinematic_ prefix without being implemented in the cutscene family at all — a naming choice that hides where the work happens cinematic_screen_effect_start_definition.c cinematic_set_near_clip_distance_definition.c.

Script nameParametersImplemented in
cinematic_screen_effect_startbooleanrasterizer_screen_effect_start
cinematic_screen_effect_stop—rasterizer_screen_effect_stop_evaluate
cinematic_screen_effect_set_filter4 reals, boolean, realrasterizer_screen_effect_set_filter
cinematic_screen_effect_set_filter_desaturation_tint3 realsrasterizer_screen_effect_set_filter_desaturation_tint_evaluate
cinematic_screen_effect_set_convolution2 shorts, 3 realsrasterizer_screen_effect_set_convolution_evaluate
cinematic_screen_effect_set_videoshort, realrasterizer_screen_effect_set_video_evaluate
cinematic_set_near_clip_distancerealrasterizer_set_near_clip_distance_evaluate (dx9)

All seven are cleaned up by cinematic_stop, which resets the screen effects and pushes the near clip back to 0.0f whether the cutscene set them or not cinematic_stop.c.

Sources: cinematic_globals_definition.h cinematic_title_datum.h cinematic_initialize.c cinematic_dispose.c cinematic_initialize_for_new_map.c cinematic_dispose_from_old_map.c cinematic_start.c cinematic_stop.c cinematic_skip_start.c cinematic_skip_stop.c cinematic_can_be_skipped.c enable_cinematic_mode.c cinematic_set_title.c cinematic_set_title_delayed.c cinematic_force_title.c cinematic_render.c interface_draw_fullscreen_overlays.c rasterizer_screen_effect_start.c rasterizer_screen_effect_set_filter.c cinematic_screen_effect_start_definition.c cinematic_set_near_clip_distance_definition.c music_gain_in_profile.c.

Chapter 06 · Playback

The Third Driver of a Unit

Edition 03 establishes unit_control as the single point at which an external control packet is applied to a unit, and lists twelve callers. One of them is recorded_animations_update, and that list is the only mention it gets. Behind it is a complete replay engine: a compressed event stream, two codecs, four generations of wire format, and a thread pool that hands a unit back when it is done. Player input, AI output and recorded playback are the three drivers of a unit, and they all end at the same function.

In this chapter

Three drivers, one gamepad

A Blam unit does not read a controller. It reads a unit_control_data packet that something else filled in, and edition 03 documents the packet and the function that applies it. The player path builds one from queued input; the AI path builds one in actor_unit_control from an actor's output block. This chapter is the third producer: recorded_animations_update decodes one out of a byte stream recorded by a designer, and calls unit_control(thread->unit_index, &thread->controller, -1) recorded_animations_update.c unit_control.c.

The -1 in that third argument is the client-update id, and in unit_control it clears did_just_complete_client_update — a recording is not a network update and never claims to be recorded_animations_update.c unit_control.c. Because recorded_animations_update runs after units_update in the tick, the packet a recording writes is consumed on the following tick, exactly like a player's game_tick.c.

Three producers, one unit_control

FIG. 20 / 34

The virtual gamepad of edition 03, with its third driver drawn in unit_control.c recorded_animations_update.c recorded_animation_apply_event_stream.c.

flowchart LR
  P["player input — handle_one_player_input, update_client_queue"] --> UC["unit_control(unit, control_data, id)"]
  A["AI actor output — actor_unit_control"] --> UC
  R["recorded animation — recorded_animations_update"] --> UC
  S["(recording_play unit recording)"] --> T["animation_thread in the 64-slot pool"]
  T --> CD["codec apply_event_stream decodes one tick of events"]
  CD --> R
  UC --> UD["_unit_datum — throttle, control_flags, facing, aiming, looking, weapon, zoom"]

Nothing downstream of unit_control can tell the three apart. A recorded Marine and a played Marine differ only in who filled the packet unit_control.c.

The thread pool

recorded_animations_initialize() at 0x83711FB0 allocates game_state_data_new("recorded animations", 64, 100) — sixty-four playback threads of a hundred bytes each recorded_animations_initialize.c. The per-map hooks are one line apiece: data_make_valid and data_make_invalid recorded_animations_initialize_for_new_map.c recorded_animations_dispose_from_old_map.c.

The thread is mostly a control packet. Of its hundred bytes, 0x40 are a whole unit_control_data and twelve more are an animation_playback_controller — three direction_playback_controller pairs of {yaw, pitch} for facing, aiming and looking, which is the accumulated orientation state the delta-encoded events are applied to animation_thread.h animation_playback_controller.h direction_playback_controller.h.

One hundred bytes per playback

FIG. 21 / 34

The animation_thread datum, DB layout animation_thread.h recording_thread_flags.h.

OffsetFieldRole
0x00identifierdatum salt
0x04unit_indexthe driven unit
0x08ticks_leftcounts down from the recording's tick count
0x0Aflagsfinished, killed, unit_was_controlled, delete_on_complete, hover_on_complete
0x0Crelative_ticksthe codec's tick cursor
0x10event_streamconst char * cursor into the tag data
0x14controllera whole 64-byte unit_control_data
0x54animation_state12-byte animation_playback_controller
0x60versiondoubles as the playback-codec selector

Seventy-six of the hundred bytes are state the codec mutates; the rest is bookkeeping animation_thread.h.

Taking and returning a unit

recorded_animation_play_internal(unit_index, animation_index, extra_flags) at 0x837123E0 validates the unit and the animation index against global_scenario->recorded_animations.count, calls player_index_from_unit_index purely for its validation side effect and discards the result, finds or allocates the unit's thread, and refuses outright if recorded_animation_controlling_unit(unit_index) — one recording per unit recorded_animation_play_internal.c.

Then it seizes the unit. unit_set_actively_controlled(1), latch the unit's previous controllable state into _recording_thread_unit_was_controlled_bit, unit_set_controllable(0), unit_set_possessed(1), object_set_automatic_deactivation(0) — the last of which stops the object manager from putting the unit to sleep mid-performance recorded_animation_play_internal.c. The three script entry points are one-liners over it: recording_play passes no flags, recording_play_and_delete passes the delete bit, and recording_play_and_hover passes the hover bit recorded_animation_play.c recorded_animation_play_and_delete.c recorded_animation_play_and_hover.c.

recorded_animation_definition is 64 bytes, and it carries two independent version numbers that index different tables: version at 0x20, a 1-based codec selector, and unit_control_data_version at 0x22, the control-schema generation. The rest is name[32], flags, ticks at 0x24, and the tag_data holding the event stream at 0x2C recorded_animation_definition.h.

Per tick, recorded_animations_update() at 0x83712008 deletes any thread whose unit has vanished, steps every live thread through its codec and pushes the result to unit_control, and, once a thread's stream is exhausted, hands the unit back: restore the latched controllable state, clear possessed and actively-controlled, re-enable automatic deactivation, then optionally destroy the unit or set its vehicle hovering, then delete the thread recorded_animations_update.c. recorded_animation_kill(unit_index) at 0x83712358 forces that path early by setting finished | killed recorded_animation_kill.c.

Play, tick, hand back

FIG. 22 / 34

A recorded animation's whole life, from the script line to the unit's release recorded_animation_play_internal.c recorded_animations_update.c.

sequenceDiagram
  participant S as script
  participant PI as recorded_animation_play_internal
  participant T as animation_thread
  participant U as unit
  S->>PI: (recording_play_and_delete unit recording)
  PI->>PI: validate unit, index, and no existing recording on this unit
  PI->>T: datum_new, seed ticks_left, event_stream, version
  PI->>T: codec initialize_event_stream over the tag data
  PI->>U: actively_controlled = 1, possessed = 1, controllable = 0
  PI->>U: object_set_automatic_deactivation(0)
  loop each tick, in recorded_animations_update
    T->>T: ticks_left--, apply_event_stream, relative_ticks++
    T->>U: unit_control(unit, &controller, -1)
  end
  Note over T: codec returns 0 — stream exhausted, finished bit set
  T->>U: restore controllable, clear possessed and actively_controlled
  T->>U: object_set_automatic_deactivation(1), then hs_object_destroy
  T->>T: datum_delete

The hand-back and the delete happen on the tick after the stream ends, in the finished branch — a thread always survives one extra visit recorded_animations_update.c.

Two codecs

playback_codec at 0x84177D24 is an animation_playback *[4], sixteen bytes, whose image words are 0x84177D1C three times and then 0x84177D14 — the v1 codec in slots 0 to 2 and the current codec in slot 3 playback_codec.c. Consumers index it as playback_codec[record->version - 1], so recording versions 1 to 3 decode through the v1 codec and version 4 through the current one recorded_animation_play_internal.c recorded_animation_verify.c.

That table is also a small parable about evidence. The reconstruction originally authored the four entries in the reverse order — current three times, then v1 — and the inversion was caught only by decoding the image words. As authored, every legacy recording would have been fed to the current codec and every current recording to the v1 entry point playback_codec.c.

Four table slots, two implementations, decoded from .data

FIG. 23 / 34

Every address here is an image word or a relocation target read out of the binary playback_codec.c current_playback.c v1_playback.c.

Recording versionSlotImage wordCodecapply_event_stream
1+0x000x84177D1Cv1_playback0x837F6C00
2+0x040x84177D1Cv1_playback0x837F6C00
3+0x080x84177D1Cv1_playback0x837F6C00
4+0x0C0x84177D14current_playback0x837F7478

Each animation_playback is two function pointers: initialize_event_stream at +0x00 and apply_event_stream at +0x04 animation_playback.h.

Two event encodings

The v1 stream is flat. Each event is a four-byte header — int16_t type then uint16_t time_delta — and recorded_animation_apply_event_stream_v1 at 0x837F6C00 consumes every event whose delta has elapsed, dispatching apply_funcs[event->type]. The handler advances the stream cursor itself; a NULL slot just skips the header. Type 1, _playback_v1_end, is the terminator, and playback is finished exactly when the cursor sits on it with *ticks == event->time_delta animation_event_v1.h recorded_animation_apply_event_stream_v1.c.

The current stream packs the header into one byte. Two bits select how the time delta is stored and six bits are the event id animation_event_header.h. The two-bit tag is the DB enum recorded_animation_time_delta: _time_delta_zero and _time_delta_one store no delta at all (one-byte header), _time_delta_byte puts the delta in the next byte (two-byte header), and _time_delta_word puts it in the next sixteen bits (three-byte header) recorded_animation_time_delta.h. Most events in a recording advance exactly one tick, so most events cost exactly one header byte.

The two codecs also split the cursor advance differently: in the v1 codec the handler does the whole advance, while in the current codec the caller advances past the event header and the handler advances past its operand recorded_animation_apply_event_stream.c.

Four bytes of header, or one

FIG. 24 / 34

The v1 event header against the current one, with the four header sizes the two-bit time tag selects animation_event_v1.h animation_event_header.h recorded_animation_time_delta.h.

v1 codec — animation_event_v1, always 4 bytes bytes 0–1 int16_t type bytes 2–3 uint16_t time_delta operands, if any, follow — handler advances the cursor current codec — animation_event_header, 1 byte plus 0–2 delta bytes bits 0–1 event_time_type bits 2–7 event_type (id 1 = end) delta storage, chosen by the two-bit tag 0 zero · 1 one · 2 next byte · 3 next word header size = 1 byte (tags 0 and 1) · 2 bytes (tag 2) · 3 bytes (tag 3) the caller advances past the header; the handler advances past its operand tag 3 combines the bytes explicitly as (event[1] << 8) | event[2] — the stream is big-endian

A tick-by-tick recording of a walking Marine costs one byte per event in the common case, which is the whole reason the current format exists recorded_animation_apply_event_stream.c.

The two dispatch tables share indices but not meanings, and comparing them is the clearest statement of what changed between the formats. In v1, orientation is written as whole vectors and whole angle triples; in the current format, the entire upper two thirds of the opcode space is delta encoding — eight slots of char-sized differences and eight of short-sized ones apply_funcs.c apply_funcs_0.c.

Two opcode spaces, same 23 slots

FIG. 25 / 34

Both tables reconstructed from binary relocations, 92 bytes each apply_funcs.c apply_funcs_0.c playback_v1_event_type.h.

Indexapply_funcs (v1)apply_funcs_0 (current)
0–1NULL — nothing, endNULL
2apply_animation_stateapply_animation_state_0
3apply_aiming_speedapply_aiming_speed_0
4apply_control_flagsapply_control_flags_0
5apply_weapon_indexapply_weapon_index_0
6apply_throttleapply_throttle_0
7–8NULL — vectors synchronize / desynchronizeapply_vector_char_difference
9–11apply_facing_vector, apply_aiming_vector, apply_looking_vectorapply_vector_char_difference
12–14apply_multi_vectorapply_vector_char_difference
15apply_multi_vectorapply_vector_short_difference
16–22apply_angle_vectorapply_vector_short_difference

Eleven distinct v1 opcodes share two handlers, because the combined forms read the opcode back out of the event to decide which vectors they are writing. The current codec has only seven distinct handlers for all 23 slots apply_funcs.c apply_funcs_0.c.

Four generations of wire format

This is the most legible piece of data in the subsystem: a running record of how unit_control_data grew, preserved as four tables in .data. A unit_control_data_entry is twelve bytes — a byte-swap definition pointer, a size (-1 terminates the table), and an offset into unit_control_data (or -1 to skip the copy) unit_control_data_entry.h. unit_control_data_map at 0x84186748 points at the four unit_control_data_map.c.

recorded_animation_initialize_unit_control at 0x83826EA0 walks them cumulatively: for a recording declaring schema version n, it walks tables 0 through n − 1 in order, because an old recording only carries the fields its own generation wrote. It memsets the block first and sets zoom_level = -1, and a skipped field — offset -1 — still advances the stream cursor by its size without writing anywhere recorded_animation_initialize_unit_control.c.

How unit_control_data grew, one field at a time

FIG. 26 / 34

The four serialization tables, decoded from .data and matched against the DB-verified struct layout unit_control_v1_map.c unit_control_v2_map.c unit_control_v3_map.c unit_control_v4_map.c unit_control_data.h.

GenerationByte-swap definitionSizeOffsetField
v1_byte_bs_definition10x00animation_state
v1_byte_bs_definition10x01aiming_speed
v1_word_bs_definition20x02control_flags
v1_word_bs_definition20x04weapon_index
v1_word_bs_definition2-1skipped — a field that was dropped
v1real_vector2d_bs_definition80x0Cthrottle, first 8 bytes
v1real_vector3d_bs_definition120x1Cfacing_vector
v1real_vector3d_bs_definition120x28aiming_vector
v1real_vector3d_bs_definition120x34looking_vector
v2long_bs_definition40x18primary_trigger — the analog trigger arrives
v3_word_bs_definition20x06grenade_index
v4_word_bs_definition20x08zoom_level

Version 1 had no analog trigger, no grenade selection and no zoom. Each later revision appended exactly one field — and the word v1 wrote at table slot 4 was dropped, while a word at offset 0x06 came back in v3 unit_control_data.h.

The recording-side tools

The build ships both inverses of the decoder. recorded_animation_write_unit_control at 0x83826F60 serialises a unit_control_data back into the stream over the same cumulative table walk recorded_animation_write_unit_control.c, and recorded_animation_byteswap_unit_control at 0x83826E00 walks the same tables calling byte_swap_data(entry->bs_def, *playback_stream, 1) in place — which is what the bs_def column is for, and it is entirely unused by the read path recorded_animation_byteswap_unit_control.c. recorded_animation_verify at 0x83712188 is the validation pass: initialise the codec over the raw stream and apply every event tick until the codec reports exhaustion recorded_animation_verify.c.

Two smaller initialisation variants complete the family. recorded_animation_initialize_event_stream at 0x837F7388 decodes the control block through the version tables and then copies the full twelve-byte animation_playback_controller verbatim out of the stream; the v1 initialiser does only the first half, because v1 streams carry no controller prologue recorded_animation_initialize_event_stream.c recorded_animation_initialize_event_stream_v1.c. A third, recorded_animation_initialize_event_stream_with_size at 0x837F73F8, reads the whole 64-byte unit_control_data verbatim instead of decoding it at all recorded_animation_initialize_event_stream_with_size.c.

Sources: unit_control.c recorded_animations_update.c game_tick.c recorded_animations_initialize.c recorded_animations_initialize_for_new_map.c recorded_animations_dispose_from_old_map.c animation_thread.h animation_playback.h animation_playback_controller.h direction_playback_controller.h recording_thread_flags.h recorded_animation_play_internal.c recorded_animation_play.c recorded_animation_play_and_delete.c recorded_animation_play_and_hover.c recorded_animation_definition.h recorded_animation_kill.c playback_codec.c current_playback.c v1_playback.c recorded_animation_verify.c animation_event_v1.h animation_event_header.h recorded_animation_time_delta.h recorded_animation_apply_event_stream.c recorded_animation_apply_event_stream_v1.c apply_funcs.c apply_funcs_0.c playback_v1_event_type.h unit_control_data_entry.h unit_control_data_map.c unit_control_v1_map.c unit_control_v2_map.c unit_control_v3_map.c unit_control_v4_map.c unit_control_data.h recorded_animation_initialize_unit_control.c recorded_animation_write_unit_control.c recorded_animation_byteswap_unit_control.c recorded_animation_initialize_event_stream.c recorded_animation_initialize_event_stream_v1.c recorded_animation_initialize_event_stream_with_size.c.

Chapter 07 · Devices

One Float, Shared, With a Latch

Every door, lift, gear and switch in Halo is driven by a shared analog value between zero and one. The group holds one float; each device bound to it holds its own value and velocity and accelerates toward the group's, at a rate interpolated by how much power it has. On top of that sits a one-shot latch, twelve script commands, and a set of tag effects fired on the exact ticks the motion starts and stops.

In this chapter

The object type

device_data_definition at 0x84177828 is a 196-byte object_type_definition, and its image words name the entire device lifecycle without a single guess: name resolves to "device", group_tag is 0x64657669 ('devi'), game_datum_size is 0x0214 — 532 bytes — and the function-pointer slots resolve to devices_initialize, device_new, device_delete, device_update, device_export_function_values, device_preprocess_node_orientations and device_render_debug device_data_definition.c.

Every networking slot in that record is 0x00000000: object_new_to_network, update_baseline, build_update_delta, process_update_delta and the three incremental-send hooks are all null. Devices do not replicate incrementally — they are deterministic functions of a device group, so every machine agrees about the door as long as it agrees about the float device_data_definition.c.

A device's whole lifecycle, read out of .data

FIG. 27 / 34

The non-null slots of device_data_definition, with the image words the binary ships device_data_definition.c.

SlotImage wordFunction
initialize0x837B4A08devices_initialize
dispose0x837B4A40devices_dispose
initialize_for_new_map0x837B54E8devices_initialize_for_new_map
dispose_from_old_map0x837B4A48devices_dispose_from_old_map
datum_new0x837B4A58device_new
datum_delete0x837B5598device_delete
datum_update0x837B5658device_update — the convergence step
datum_export_function_values0x837B4AA0device_export_function_values — chapter 8
datum_preprocess_node_orientations0x837B4C88device_preprocess_node_orientations
render_debug0x837B4E30device_render_debug
all networking slots0x00000000devices do not replicate

datum_place and datum_adjust_placement are null too — placement is handled by the machine and control subtypes, which call device_add_scenario_information themselves machine_place.c control_place.c.

The device group

A device_group_datum is eight bytes: identifier, flags, and one float desired_value device_group_datum.h. devices_initialize() at 0x837B4A08 allocates a thousand and twenty-four of them devices_initialize.c.

It is worth being precise about where the desired-versus-actual split lives, because the names invite the wrong reading. The group has exactly one float. The device carries its own power, power_velocity, position, position_velocity and delay_ticks in the 32-byte _device_datum block at offset 0x1F4 of the 532-byte object — and it is the device that converges device_datum.h device_update.c. Several doors can share one group and be at different points of their travel at the same instant.

Groups arrive two ways. create_initial_device_groups() at 0x837B5440 allocates one datum per scenario-authored group, seeded with its initial_value and with flags set to bit 0 of the scenario definition's flags — the “can change only once” bit — silently skipping any that fail to allocate create_initial_device_groups.c. Anything a placement leaves at -1 gets a runtime group from device_add_scenario_information at 0x837B5B60: the power group is seeded 0.0f when the placement says “initially off” and 1.0f otherwise; the position group is seeded 1.0f when the placement says “initially open” and 0.0f otherwise device_add_scenario_information.c. Only runtime groups are ever deleted: device_group_delete at 0x837B5408 checks _device_group_runtime_bit first, so scenario-authored groups are permanent device_group_delete.c.

Requesting a change, and the latch

device_group_set_desired_value(group_index, desired_value) at 0x837B5938 is where a script's request lands. It clamps to [0, 1], no-ops on -1, and stores the value only if it actually differs and the group is not latched — that is, only if _device_group_can_change_only_once_bit is clear or _device_group_changed_once_bit is clear. Whenever it does store, it always sets _device_group_changed_once_bit device_group_set_desired_value.c device_group_flags.h.

That is the whole latch. The “changed once” bit is set on every successful change; the “can change only once” bit turns that history into a refusal. The script command that arms it, device_group_change_only_once_more_set at 0x837B50C8, sets or clears the first bit as asked and then always clears the second — granting the group exactly one more change, whatever it has done before device_group_change_only_once_more_set.c. Its DEVIATION note is a small delight: the binary writes the flags word twice, once to set and once to clear, and the reconstruction reproduces both stores rather than folding them device_group_change_only_once_more_set.c.

When the value does change, the function walks every device object and, for each whose power group matches, spawns the definition's depowered_effect (value at or below zero) or repowered_effect, dispatching on the referenced tag's group tag: 0x65666665 ('effe') goes to effect_new_from_object, 0x736E6421 ('snd!') goes to object_impulse_sound_new. One tag reference, two possible tag types, decided at runtime device_group_set_desired_value.c.

The immediate form skips all of it. device_group_set_actual_value at 0x837B4F18 clamps, writes the group value, then writes the value straight into every matching device's power or position, zeroes the corresponding velocity, and marks the object animation-changed. No convergence, no effects, no latch check device_group_set_actual_value.c.

Change only once more

FIG. 28 / 34

The two flag bits that make a device group a one-shot, and the command that re-arms it device_group_set_desired_value.c device_group_change_only_once_more_set.c device_group_flags.h.

stateDiagram-v2
  [*] --> Free : create_initial_device_groups — can_change_only_once from the scenario flag
  Free --> Free : device_group_set — value stored, changed_once set
  Free --> Latched : same, when can_change_only_once is set
  Latched --> Latched : device_group_set refused — value unchanged, returns 0
  Latched --> Armed : device_group_change_only_once_more_set — changed_once cleared
  Armed --> Latched : device_group_set — one change allowed, changed_once set again
  note right of Latched : device_export_function_values reads this pair as locked
  note right of Free : device_group_set_immediate bypasses the check entirely

A refused change returns 0, which is exactly what the boolean return of the device_group_set builtin carries back into the script device_group_set_definition.c.

Convergence

device_update(device_index) at 0x837B5658 is the datum_update slot, and it runs two independent convergence steps against accelerate_to_position — a one-dimensional integrator that snaps and returns 1 when it arrives, and returns 0 while it is still moving device_update.c accelerate_to_position.c.

Power converges under fixed limits from the tag (runtime_maximum_power_acceleration and runtime_maximum_power_velocity). Position is the interesting one, because its limits are interpolated by the current power: both the acceleration and the velocity limit are depowered * (1 - power) + powered * power. A door losing power does not stop; it slows down, continuously device_update.c _device_definition.h.

A per-device dwell counter holds a fully-closed device shut. While (float)delay_ticks < runtime_delay_ticks, the position is exactly 0.0f, and the group is asking for something at or above zero, the counter increments and the function returns early — spawning delay_effect exactly once, on the tick the counter reaches 1 device_update.c.

What comes out of the step decides which effect fires. Arriving spawns positive_stop_effect or negative_stop_effect according to the sign the velocity had before the step; still moving, with the velocity having just changed sign, spawns negative_start_effect or positive_start_effect. Six of the seven tag_reference effect slots in _device_definition are consumed by this one function device_update.c _device_definition.h.

One correction in this function is inherited rather than discovered, and it is worth restating precisely because an earlier reading had it wrong. The final argument of the POSITION call — accelerate_to_position's circular-position flag — is the definition's position-loops bit, not zero. lwz r11, 0x17C(r30) loads definition->device.flags (the _device_definition block begins at offset 0x17C inside device_definition) and clrlwi r10, r11, 31 isolates bit 0, _device_position_loops_bit, across 0x837B587C–0x837B5894. The li r10, 0 at 0x837B5700 belongs to the POWER call, whose flag really is zero. Both group indices also carry 0xFFFF sentinel guards device_update.c device_definition.h _device_definition.h device_position_flags.h.

One tick of device_update

FIG. 29 / 34

Power first, then position; the effect spawned depends on whether the step arrived and on the sign of the velocity before it device_update.c accelerate_to_position.c device_effect_new.c.

flowchart TD
  A["device_update(device_index)"] --> B{"power_group_index != 0xFFFF and something to do ?"}
  B -->|"yes"| C["accelerate_to_position on power — fixed tag limits, circular flag 0"]
  C --> D["mark animation_changed if power moved"]
  B -->|"no"| E
  D --> E{"position_group_index != 0xFFFF and something to do ?"}
  E -->|"no"| Z["return"]
  E -->|"yes"| F["limits = depowered*(1-power) + powered*power"]
  F --> G{"delay_ticks < runtime_delay_ticks and position == 0 ?"}
  G -->|"yes"| H["delay_ticks++, spawn delay_effect on the tick it reaches 1, return"]
  G -->|"no"| I["clamp position_velocity to the interpolated limit"]
  I --> J["accelerate_to_position on position — circular flag = position_loops bit"]
  J -->|"arrived"| K["spawn positive_stop_effect or negative_stop_effect by prior velocity sign"]
  J -->|"still moving"| L{"velocity just changed sign ?"}
  L -->|"yes"| M["spawn negative_start_effect or positive_start_effect"]
  L -->|"no"| N["keep moving"]

The reconstructed banner says the function returns 1 when a step “reported completion”, but the body sets its result in the not-arrived branches. Read against accelerate_to_position's documented return, the value means “this device is still in motion” device_update.c accelerate_to_position.c.

Controls and machines

device_touched(device_index, unit_index) at 0x837B5140 dispatches a unit's use interaction on object type: a machine goes to machine_bumped, a control to control_touched device_touched.c, and control_touched at 0x837E9C58 only toggles when the definition's trigger field is zero — the touch-triggered case control_touched.c.

control_toggle(control_index) at 0x837E9B30 computes the desired value from the control's type: a toggle switch flips from the current group value (current <= 0.5f ? 1.0f : 0.0f), an on button forces 1.0f, an off button 0.0f, and a call button uses the definition's call_value. It notifies the HCEX host, drives the group, and spawns on_effect or off_effect on success — or deny_effect when the group refused, which is exactly the latch of the previous section making itself audible control_toggle.c.

machine_update(machine_index) at 0x837BBFC8 runs beside the generic convergence and inverts the usual direction of flow. A gear-type machine advances a 0-to-1 phase by the same power-interpolated increment, wraps it at 1.0, and writes the phase straight into its group's desired_value — a machine driving its own group rather than being driven by it. Auto-open doors run an objects_in_sphere proximity test every fourth tick and prime a -3 auto-close timer; the auto-close stage drives the group shut after the definition's delay; and lift machines translate every object parented to them by the drive node's per-tick delta machine_update.c. Its headline DEVIATION is the FPR-shadow trap yet again: the float radius in f1 reserves GPR r7, so the decompiler's uninitialised local is a dead shadow slot, and the real trailing arguments are the object-index buffer and a maximum count of 2048 — an 8 KB buffer the decompiler had sized at 128 bytes machine_update.c.

Two lifecycle hooks in this family are worth a sentence because they are literally nothing: machines_initialize_for_new_map and controls_initialize_for_new_map are both bare blr, confirmed in disassembly machines_initialize_for_new_map.c controls_initialize_for_new_map.c. All per-map device state comes from placement, through device_new and device_add_scenario_information device_new.c device_add_scenario_information.c.

The script surface

Twelve builtins, every one with a decoded descriptor in src/data/. The pattern across them is consistent and worth naming: a set command requests and converges, a set_immediate command teleports, a get command reads the group float, and three booleans reach past the group entirely to flip machine behaviour flags device_set_power_definition.c device_group_set_immediate_definition.c.

Only two of the twelve return hs_type_boolean — device_group_set and device_set_position — and both get that boolean from device_group_set_desired_value's “did it actually change” result, packed into the high byte by the shim of chapter 1 device_group_set_definition.c device_set_position_definition.c device_group_set_desired_value_evaluate.c. A script can therefore detect a latched door.

Twelve device commands, decoded from their descriptors

FIG. 30 / 34

Script name, declared return, formal parameters, and the evaluator the evaluate pointer resolves to device_get_position_definition.c device_group_get_definition.c device_one_sided_set_definition.c.

Script nameReturnParametersEvaluator
device_group_getrealdevice_groupdevice_group_get_value_evaluate
device_group_setbooleandevice_group, realdevice_group_set_desired_value_evaluate
device_group_set_immediatevoiddevice_group, realdevice_group_set_actual_value_evaluate
device_group_change_only_once_more_setvoiddevice_group, booleandevice_group_change_only_once_more_set_evaluate
device_get_positionrealdevicedevice_get_position_evaluate
device_set_positionbooleandevice, realdevice_set_desired_position_evaluate
device_set_position_immediatevoiddevice, realdevice_set_actual_position_evaluate
device_get_powerrealdevicedevice_get_power_evaluate
device_set_powervoiddevice, realdevice_set_power_evaluate
device_one_sided_setvoiddevice, booleandevice_one_sided_set_evaluate
device_operates_automatically_setvoiddevice, booleandevice_operates_automatically_set_evaluate
device_set_never_appears_lockedvoiddevice, booleandevice_set_never_appears_locked_evaluate

There are thirteen device_*_definition.c files in src/data/, but only twelve are script descriptors — the thirteenth is device_data_definition, the object-type record of the first figure in this chapter device_data_definition.c.

Sources: device_data_definition.c device_group_datum.h device_group_flags.h device_datum.h device_datum_flags.h devices_initialize.c create_initial_device_groups.c device_group_new.c device_group_delete.c device_add_scenario_information.c device_new.c machine_place.c control_place.c machines_initialize_for_new_map.c controls_initialize_for_new_map.c device_group_set_desired_value.c device_group_set_actual_value.c device_group_get_value.c device_group_change_only_once_more_set.c device_set_desired_position.c device_set_actual_position.c device_set_power.c device_can_change_position.c device_update.c device_effect_new.c accelerate_to_position.c device_definition.h _device_definition.h device_position_flags.h device_touched.c control_touched.c control_toggle.c machine_update.c device_set_power_definition.c device_group_set_definition.c device_group_set_immediate_definition.c device_set_position_definition.c device_get_position_definition.c device_group_get_definition.c device_one_sided_set_definition.c device_group_set_desired_value_evaluate.c device_get_power_definition.c device_set_position_immediate_definition.c.

Chapter 08 · Closing

Handles on Tags, and the Last Hop

Scripted sound has no table of its own: the handle for a playing scripted sound is stored inside the sound tag, which quietly makes “one instance per tag, globally” an engine-wide rule. Player effects are a shake, a rumble and a fade sharing one timer pair. And the last hop — the one that turns a script's device command into a moving door and a flickering light — is a four-slot array of exported function values.

In this chapter

The handle lives on the tag

scripted_sound_new(definition_index, source_object_index, scale) at 0x837149B8 stores its playing-sound handle in the sound tag itself: runtime_scripting_sound_index, alongside a predicted end time in runtime_scripting_time. It stops any previous instance first, records the end time as game_time_get() + 30 * runtime_maximum_play_time / 1000, clamps the scale to [0, 1], and then either plays the sound unattached or attaches it to the source object's "head" marker — falling back to global_origin3d and global_forward3d when the marker is missing scripted_sound_new.c.

The consequence is a hard rule nobody has to enforce: one scripted instance per sound tag, globally. A second sound_impulse_start on the same tag stops the first, because the first's handle is the only place the engine remembers it. scripted_sound_stop at 0x83713BD0 reads the handle back off the tag and clears both fields scripted_sound_stop.c; scripted_sound_time at 0x83713B60 returns max(0, end_time - game_time_get()), reproduced from a branchless saturate idiom scripted_sound_time.c. scripted_sound_predict at 0x83713B58 is a no-op in this build scripted_sound_predict.c.

Looping sounds use the same trick through looping_sound_definition.runtime_scripting_sound_index. scripted_looping_sound_start at 0x83714EC8 stops any previous instance, calls scripted_music_stop_all() when the definition carries the “stops music” bit, starts the sound, and flags the resulting datum as scripted scripted_looping_sound_start.c. scripted_looping_sound_stop_internal at 0x837145A0 clears the scripted bit, sets the unattached-stop bit, clears the tag handle, and optionally requests a fixed fadeout scripted_looping_sound_stop_internal.c, while scripted_looping_sound_set_scale at 0x83713CE8 clamps and writes the datum's scale scripted_looping_sound_set_scale.c.

The tag is the handle table

FIG. 31 / 34

Why a scripted sound cannot overlap itself scripted_sound_new.c scripted_sound_stop.c scripted_sound_time.c.

flowchart TD
  A["(sound_impulse_start T obj 1.0)"] --> B["scripted_sound_new(T, obj, 1.0)"]
  B --> C["sound_stop_impulse(tag->runtime_scripting_sound_index) — stop the previous one"]
  C --> D["tag->runtime_scripting_time = now + 30 * runtime_maximum_play_time / 1000"]
  D --> E{"source_object_index == -1 ?"}
  E -->|"yes"| F["sound_new_impulse — world-positioned, identity marker"]
  E -->|"no"| G["object_get_marker_by_name(obj, #quot;head#quot;)"]
  G -->|"found"| H["object_impulse_sound_new at the marker matrix"]
  G -->|"missing"| I["object_impulse_sound_new at global_origin3d / global_forward3d"]
  F --> J["tag->runtime_scripting_sound_index = handle"]
  H --> J
  I --> J
  J --> K["(sound_impulse_time T) reads the end time back off the tag"]

The state is per tag, not per invocation, so two scripts starting the same sound on two objects cannot both be tracked — the second wins and the first is stopped scripted_sound_new.c.

Player effects

player_effect_globals_definition is 532 bytes: local_player_effect_data[2] for 472 of them, a 20-byte screen_fade, a 32-byte scripted_effect, then global_flags and reference_time player_effect_globals_definition.h. The scripted block itself is max_translation, max_rotation, max_intensity, timer and total_time scripted_player_effect_definition.h.

Start and stop write the same two timer fields; only a flag distinguishes them. scripted_player_effect_start(max_intensity, attack) at 0x83737810 sets the running bit, clears the ending bit, and seeds both timer and total_time with (int16_t)(int)(attack * 30.0f) scripted_player_effect_start.c; scripted_player_effect_stop(decay) at 0x83737858 sets the ending bit and reloads the same pair with the decay time scripted_player_effect_stop.c. The direction of the ramp is a bit, not a sign.

scripted_player_effect_set_rotation at 0x837377D8 is the only unit conversion in the entire scripted presentation surface: the yaw, pitch and roll arguments are given in degrees and stored in radians scripted_player_effect_set_rotation.c. Its translation twin at 0x837377C0 stores world units unchanged scripted_player_effect_set_translation.c, and scripted_player_effect_set_vibrate at 0x83737808 is a bare thunk onto vibrate_player_set_scripted_values scripted_player_effect_set_vibrate.c.

fade_in and fade_out are the same eight lines twice: player_effect_screen_fade_in at 0x837379E0 and player_effect_screen_fade_out at 0x83737A30 write the colour, the tick count and start_time = game_time_get(), and differ only in the fading_out byte player_effect_screen_fade_in.c player_effect_screen_fade_out.c. And player_camera_control reaches into a different block again: scripted_player_control_set_camera_control at 0x836DE4C8 clears _player_control_camera_off_bit when enabling and sets it when disabling, returning its own argument scripted_player_control_set_camera_control.c.

Shake, rumble and fade, in one 532-byte block

FIG. 32 / 34

Which script command writes which part of player_effect_globals player_effect_globals_definition.h scripted_player_effect_definition.h.

RegionOffsetWritten byNote
local_player_effect_data[2]0x000the non-scripted effect system472 bytes
screen_fade0x1D8fade_in, fade_outcolour, ticks, start_time, fading_out
scripted_effect.max_translation0x1ECplayer_effect_set_max_translationworld units
scripted_effect.max_rotation0x1F8player_effect_set_max_rotationdegrees in, radians stored
scripted_effect.max_intensity0x204player_effect_start—
scripted_effect.timer / total_time0x208both player_effect_start and _stopattack or decay, in ticks
global_flags0x20Cplayer_effect_start, _stoprunning bit, ending bit
(not in this block)—player_effect_set_max_vibratethunks to the vibration system

Six of the eight script commands in this family write four fields between them; the shake's whole behaviour is two vectors, an intensity and a ramp scripted_player_effect_start.c.

Closing the loop: function values

Everything so far has left a number in a global. The last hop is what makes a device visible, and it happens in the object system rather than the device one. device_export_function_values(device_index) at 0x837B4AA0 is the datum_export_function_values slot of the device object type. For each of four slots, the device tag names a source in definition->device.function_modes[slot], and the exported value is derived from the live device state and written to object.incoming_function_values[slot] device_export_function_values.c device_data_definition.c device_function_mode.h.

The locked mode is the only one that reads the device group's flags, and it is how a spent one-shot door renders as locked: it tests _device_group_can_change_only_once_bit and _device_group_changed_once_bit together, exactly the latch pair of chapter 7 device_export_function_values.c device_group_flags.h. Its own DEVIATION is another decompiler fiction worth quoting: machine.flags was modelled as the high dword of a phantom 64-bit local initialised from an &XBM__CaptureCompletionSignalMarker that has no instruction backing it at 0x837B4AB0, so the & 0x1_00000000LL tests are plain flags & 1 device_export_function_values.c.

Seven function modes, four slots

FIG. 33 / 34

What each device_function_mode exports into object.incoming_function_values[slot] device_function_mode.h device_export_function_values.c.

ModeNameExported value
0noneslot skipped entirely — not even zeroed
1powerdevice.power
2change_in_powerabs(power_velocity) / runtime_maximum_power_velocity
3positiondevice.position
4change_in_positionabs(position_velocity) / runtime_maximum_powered_position_velocity
5locked1.0 when depowered, one-shot fired, non-automatic or one-sided; forced back to 0 when fully open or never_appears_locked
6delaydelay_ticks / runtime_delay_ticks
≥7—0

Mode 0 is not “export zero” — it skips the store, leaving whatever was in the slot. That distinction matters to anything sampling the value later in the frame device_export_function_values.c.

Two consumers read those values back. device_preprocess_node_orientations at 0x837B4C88 drives the device's own mesh: it takes the first entry of the animation graph's device-animations block, computes scaled_position = reversed ? 1 - position : position, picks a reference frame count of frame_count or frame_count - 1 depending on the position-loops bit, and applies the overlay at reference_frame * scaled_position — snapped to an exact frame when the “animation not interpolated” bit is set, blended continuously otherwise. A second selector, if present, applies another continuous overlay driven by device.power device_preprocess_node_orientations.c. That is the end of the chain: a script's device_group_set becomes a door's animation frame.

The other consumer is object_get_function_value, the general read used by the object-attached widget simulations. glow_update at 0x8380CA80 samples it twice per tick — once for the rotational-velocity attachment and once for the translational one — and interpolates the glow's velocity between the definition's lower and upper scale bounds by the sampled value glow_update.c.

From (device_group_set door 1.0) to a moving door

FIG. 34 / 34

The complete path this edition documents, across three tick stages and two subsystems device_group_set_desired_value.c device_update.c device_export_function_values.c device_preprocess_node_orientations.c.

flowchart TD
  A["(device_group_set door 1.0)"] --> B["device_group_set_desired_value_evaluate — short, real"]
  B --> C["device_group_set_desired_value — clamp, latch check, store"]
  C --> D["device_group_datum.desired_value = 1.0"]
  C --> E["depowered_effect or repowered_effect spawned on every bound device"]
  D --> F["objects_update → device_update, next stage of this tick"]
  F --> G["accelerate_to_position — limits interpolated by power"]
  G --> H["device.position creeps toward 1.0 over many ticks"]
  H --> I["device_export_function_values → object.incoming_function_values[0..3]"]
  I --> J["device_preprocess_node_orientations — overlay frame = reference_frame * position"]
  I --> K["object_get_function_value → glow_update, shader inputs"]
  J --> L["the door is drawn open"]

Nine hops from a script line to a pixel, and only the first two are in the script layer. Everything after device_group_datum.desired_value is the engine converging on its own schedule device_update.c.

The visible tail: widgets

The widget family is where those function values are finally consumed for decoration, and it is otherwise undocumented in this corpus. widget_type_definitions at 0x8417DB98 is a widget_type_definition[5], 200 bytes, whose image words name five complete lifecycles by group tag: 0x666C6167 ('flag', the only one with needs_lighting set), 0x616E7421 ('ant!', antennas), 0x676C7721 ('glw!', glows), and two more widget_type_definitions.c. widgets_update(dt) at 0x83756548 simply calls each of the five update procedures that is non-null widgets_update.c.

The heavyweights are worth pointing at even though they are outside this edition's subject. glow_update runs a greedy marker-ordering search on its first call and then two separate particle simulations — marker-riding and released — every tick after that glow_update.c. flag_update at 0x8380EE60 is a per-frame cloth relaxation over a vertex grid, with the column sweep direction alternating so the solver does not bias toward one edge flag_update.c.

Defects proven while writing this

Three findings in the reconstructed source are reported here, not fixed — the src/ tree belongs to a concurrent campaign. First and most consequential, scripted_camera_set_animation.c inverts two stores relative to the binary, and its DEVIATION comment asserts the inversion as evidence; the reader, scripted_camera_update, agrees with the binary, so the reconstructed setter would leave the animated camera fetching tag index -1 scripted_camera_set_animation.c scripted_camera_update.c.

Second, device_group_set_actual_value.c's banner comment swaps two offsets: it describes +0x1F8 as the position group and +0x204 as the power group, where _device_datum puts power_group_index at +0x1F8 and position_group_index at +0x204. The code body is correct; only the comment is wrong device_group_set_actual_value.c device_datum.h. Third, device_update.c's banner inverts its own return — it claims 1 means a step completed, where the body sets the result in the not-completed branches device_update.c accelerate_to_position.c.

Three further findings are faithful reconstructions of shipped behaviour rather than source defects, and belong in a different column: recorded_animation_write_unit_control's missing offset == -1 check, control_toggle's uninitialised desired_value for an out-of-range control type, and device_can_change_position's unguarded power-group index recorded_animation_write_unit_control.c control_toggle.c device_can_change_position.c. All three are the binary's own behaviour, preserved deliberately.

A DEVIATION comment is a claim about the disassembly, not evidence of it. Two of the three source defects above are comments that were never checked against the instructions they describe.

Sources: scripted_sound_new.c scripted_sound_stop.c scripted_sound_time.c scripted_sound_predict.c scripted_looping_sound_start.c scripted_looping_sound_stop_internal.c scripted_looping_sound_set_scale.c player_effect_globals_definition.h scripted_player_effect_definition.h scripted_player_effect_start.c scripted_player_effect_stop.c scripted_player_effect_set_rotation.c scripted_player_effect_set_translation.c scripted_player_effect_set_vibrate.c cinematic_set_title_delayed.c player_effect_screen_fade_in.c player_effect_screen_fade_out.c scripted_player_control_set_camera_control.c device_export_function_values.c device_data_definition.c device_function_mode.h device_group_flags.h device_preprocess_node_orientations.c glow_update.c device_group_set_desired_value.c device_update.c widget_type_definitions.c widgets_update.c flag_update.c scripted_camera_set_animation.c scripted_camera_update.c device_group_set_actual_value.c device_datum.h accelerate_to_position.c recorded_animation_write_unit_control.c control_toggle.c device_can_change_position.c.

Back matter

Index of Figures

Every diagram in this edition, in reading order. The swatch is the figure's dominant category: script, render, sim, io, infra.

Fig.TitleChapterCategory
01One descriptor, decoded from the binaryCh 1 script
02Where the 471 evaluators liveCh 1 script
03Three statements, and the one that can return nullCh 1 script
04Four bytes per argument, narrow values at the frontCh 1 script
05Packing a narrow result into the high end of the wordCh 1 script
06What the designer types, and what runsCh 1 script
07One tick, in order — where the poke lands and where it is readCh 2 sim
08Ten symbols the scripted-presentation layer writesCh 2 infra
09Script control is a function-pointer swap, not a flagCh 3 render
10Six setters, four modes, one structCh 3 script
11Four branches, then always the timerCh 3 render
12An anchored camera point is an offset, not a positionCh 3 render
13Writer and reader, as reconstructed and as shippedCh 3 script
14Seven bits, three polarities, two wordsCh 4 script
15From a script line to a drawn panelCh 4 render
16One field, two meanings, converted on pauseCh 4 render
17What a cutscene takes, and what it gives backCh 5 render
18A delay implemented as a negative numberCh 5 render
19One overlay frame — bars, then up to four titlesCh 5 render
20Three producers, one unit_controlCh 6 sim
21One hundred bytes per playbackCh 6 sim
22Play, tick, hand backCh 6 sim
23Four table slots, two implementations, decoded from .dataCh 6 io
24Four bytes of header, or oneCh 6 io
25Two opcode spaces, same 23 slotsCh 6 io
26How unit_control_data grew, one field at a timeCh 6 io
27A device's whole lifecycle, read out of .dataCh 7 infra
28Change only once moreCh 7 script
29One tick of device_updateCh 7 sim
30Twelve device commands, decoded from their descriptorsCh 7 script
31The tag is the handle tableCh 8 io
32Shake, rumble and fade, in one 532-byte blockCh 8 io
33Seven function modes, four slotsCh 8 render
34From (device_group_set door 1.0) to a moving doorCh 8 render
↑