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.
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.
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.
The device_set_power row of hs_function_table, at
0x8211A0C0 in .rdata
device_set_power_definition.c.
| Offset | Field | Image word | Meaning |
|---|---|---|---|
+0x00 | return_type | 0x0004 | hs_type_void |
+0x04 | name | 0x82117AA8 | "device_set_power" |
+0x08 | parse | 0x837787E0 | hs_macro_function_parse |
+0x0C | evaluate | 0x83729238 | device_set_power_evaluate |
+0x18 | console_flags | 0x00 | not a console-only command |
+0x1A | formal_parameter_count | 2 | — |
+0x1C | formal_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.
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.
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.
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.
| Directory | Entries | Presentation? |
|---|---|---|
src/blam/hs | 55 | VM itself |
src/blam/ai | 97 | — |
src/blam/game | 52 | — |
src/blam/units | 43 | — |
src/blam/sound | 41 | yes — camera, HUD, sound, player effects |
src/blam/main | 40 | — |
src/blam/objects | 17 | — |
src/blam/interface | 15 | yes — nav points, HUD text |
src/blam/cutscene | 13 | yes — cinematics, recordings |
src/blam/devices | 12 | yes — doors, lifts, switches |
src/blam/cache | 10 | — |
src/blam/rasterizer/dx9 | 8 | yes — gamma, near clip, lights |
src/blam/saved_games | 8 | — |
src/blam/networking | 7 | — |
src/blam/rasterizer | 6 | yes — screen effects |
src/blam/camera | 3 | yes — camera control |
src/blam/effects | 3 | yes — screen fades |
| nine more directories | 1–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.
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.
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.
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.
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.
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 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.
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 type | Shim writes | VM extracts | Example |
|---|---|---|---|
hs_type_boolean | ((uint8_t)v) << 24 | value >> 24 | show_hud |
hs_type_short_integer | ((uint16_t)v) << 16 | (int16_t)(value >> 16) | camera_time |
hs_type_real | *(float *)&result = v | whole word, bit-identical | device_get_position |
hs_type_long_integer | result = v | whole word | sound_impulse_time |
hs_type_void | hs_return(thread, 0) | nothing | hud_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.
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.
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.
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 name | Evaluator |
|---|---|
device_group_set | device_group_set_desired_value_evaluate |
device_group_set_immediate | device_group_set_actual_value_evaluate |
device_set_position | device_set_desired_position_evaluate |
device_set_position_immediate | device_set_actual_position_evaluate |
device_group_get | device_group_get_value_evaluate |
camera_set | scripted_camera_set_absolute_evaluate |
camera_set_relative | scripted_camera_set_evaluate |
camera_control | director_script_camera_evaluate |
enable_hud_help_flash | scripted_hud_set_flashing_state_evaluate |
hud_set_help_text | scripted_hud_set_state_message_evaluate |
hud_set_timer_warning_time | scripted_hud_set_timer_warning_cutoff_evaluate |
recording_play | recorded_animation_play_evaluate |
sound_impulse_start | scripted_sound_new_evaluate |
sound_looping_predict | scripted_foley_predict_evaluate |
cinematic_abort | main_skip_cinematic_evaluate |
fade_in | player_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.
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.
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.
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 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.
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.
| Symbol | Address | Shape | Chapter |
|---|---|---|---|
camera_script_globals | 0x84177CA0 | 64-byte struct, data-init | 3 |
hud_scripted_globals | 0x8445CE6C | pointer to a 4-byte struct | 4 |
hud_messaging_globals | — | pointer to a 2280-byte struct | 4 |
unit_hud_globals | 0x84429FC0 | pointer; carries script_flags | 4 |
weapon_hud_globals | 0x84429C08 | pointer; carries script_flags | 4 |
cinematic_globals | 0x8441E654 | pointer to a 28-byte struct | 5 |
music_gain_in_profile | 0x8417476C | float, ships 0xBF800000 | 5 |
animation_threads | 0x8445D3D4 | pointer to 64 × 100-byte data_array | 6 |
device_groups_data | 0x8465C984 | pointer to 1024 × 8-byte data_array | 7 |
player_effect_globals | 0x8445FEFC | pointer to a 532-byte struct | 8 |
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.
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.
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.
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.
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.
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.
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.
| Setter | Mode | Timer source | Also writes |
|---|---|---|---|
scripted_camera_set | 0 point | tick_count / 30 | point, forward, up, FOV, camera_point_index, relative object |
..._set_camera_point_relative | 0 point | tick_count / 30 | point, forward, up, FOV; camera_point_index = -1 |
..._set_camera_point_absolute | 0 point | tick_count / 30 | tail call with relative_to_object_index = -1 |
..._set_animation | 1 animation | frame_count / 30 | animation_index, graph index, FOV forced to 70° |
..._set_first_person | 2 first person | untouched | relative_object_index only |
..._set_dead | 3 dead cam | untouched | relative_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.
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.
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.
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.
The mode-0 anchored path, in the order the code computes it scripted_camera_update.c.
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.
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.
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.
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.
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.
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.
| Word | Bit | Name | Script command | Sense |
|---|---|---|---|---|
unit_hud_globals | 0 | _hud_panel_health_dont_show_bit | hud_show_health | cleared to show |
unit_hud_globals | 1 | _hud_panel_health_blink_bit | hud_blink_health | set to blink |
unit_hud_globals | 2 | _hud_panel_shield_dont_show_bit | hud_show_shield | cleared to show |
unit_hud_globals | 3 | _hud_panel_shield_blink_bit | hud_blink_shield | set to blink |
unit_hud_globals | 4 | _hud_panel_motion_sensor_dont_show_bit | hud_show_motion_sensor | cleared to show |
unit_hud_globals | 5 | _hud_panel_motion_sensor_blink_bit | hud_blink_motion_sensor | set to blink |
weapon_hud_globals | 0 | _hud_crosshair_show_bit | hud_show_crosshair | set 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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() 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.
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.
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 name | Parameters | Implemented in |
|---|---|---|
cinematic_screen_effect_start | boolean | rasterizer_screen_effect_start |
cinematic_screen_effect_stop | — | rasterizer_screen_effect_stop_evaluate |
cinematic_screen_effect_set_filter | 4 reals, boolean, real | rasterizer_screen_effect_set_filter |
cinematic_screen_effect_set_filter_desaturation_tint | 3 reals | rasterizer_screen_effect_set_filter_desaturation_tint_evaluate |
cinematic_screen_effect_set_convolution | 2 shorts, 3 reals | rasterizer_screen_effect_set_convolution_evaluate |
cinematic_screen_effect_set_video | short, real | rasterizer_screen_effect_set_video_evaluate |
cinematic_set_near_clip_distance | real | rasterizer_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.
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.
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.
unit_controlThe 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.
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.
The animation_thread datum, DB layout
animation_thread.h
recording_thread_flags.h.
| Offset | Field | Role |
|---|---|---|
0x00 | identifier | datum salt |
0x04 | unit_index | the driven unit |
0x08 | ticks_left | counts down from the recording's tick count |
0x0A | flags | finished, killed, unit_was_controlled, delete_on_complete, hover_on_complete |
0x0C | relative_ticks | the codec's tick cursor |
0x10 | event_stream | const char * cursor into the tag data |
0x14 | controller | a whole 64-byte unit_control_data |
0x54 | animation_state | 12-byte animation_playback_controller |
0x60 | version | doubles as the playback-codec selector |
Seventy-six of the hundred bytes are state the codec mutates; the rest is bookkeeping animation_thread.h.
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.
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.
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.
.dataEvery 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 version | Slot | Image word | Codec | apply_event_stream |
|---|---|---|---|---|
| 1 | +0x00 | 0x84177D1C | v1_playback | 0x837F6C00 |
| 2 | +0x04 | 0x84177D1C | v1_playback | 0x837F6C00 |
| 3 | +0x08 | 0x84177D1C | v1_playback | 0x837F6C00 |
| 4 | +0x0C | 0x84177D14 | current_playback | 0x837F7478 |
Each animation_playback is two function pointers:
initialize_event_stream at +0x00 and
apply_event_stream at +0x04
animation_playback.h.
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.
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.
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.
Both tables reconstructed from binary relocations, 92 bytes each apply_funcs.c apply_funcs_0.c playback_v1_event_type.h.
| Index | apply_funcs (v1) | apply_funcs_0 (current) |
|---|---|---|
| 0–1 | NULL — nothing, end | NULL |
| 2 | apply_animation_state | apply_animation_state_0 |
| 3 | apply_aiming_speed | apply_aiming_speed_0 |
| 4 | apply_control_flags | apply_control_flags_0 |
| 5 | apply_weapon_index | apply_weapon_index_0 |
| 6 | apply_throttle | apply_throttle_0 |
| 7–8 | NULL — vectors synchronize / desynchronize | apply_vector_char_difference |
| 9–11 | apply_facing_vector, apply_aiming_vector, apply_looking_vector | apply_vector_char_difference |
| 12–14 | apply_multi_vector | apply_vector_char_difference |
| 15 | apply_multi_vector | apply_vector_short_difference |
| 16–22 | apply_angle_vector | apply_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.
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.
unit_control_data grew, one field at a timeThe 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.
| Generation | Byte-swap definition | Size | Offset | Field |
|---|---|---|---|---|
| v1 | _byte_bs_definition | 1 | 0x00 | animation_state |
| v1 | _byte_bs_definition | 1 | 0x01 | aiming_speed |
| v1 | _word_bs_definition | 2 | 0x02 | control_flags |
| v1 | _word_bs_definition | 2 | 0x04 | weapon_index |
| v1 | _word_bs_definition | 2 | -1 | skipped — a field that was dropped |
| v1 | real_vector2d_bs_definition | 8 | 0x0C | throttle, first 8 bytes |
| v1 | real_vector3d_bs_definition | 12 | 0x1C | facing_vector |
| v1 | real_vector3d_bs_definition | 12 | 0x28 | aiming_vector |
| v1 | real_vector3d_bs_definition | 12 | 0x34 | looking_vector |
| v2 | long_bs_definition | 4 | 0x18 | primary_trigger — the analog trigger arrives |
| v3 | _word_bs_definition | 2 | 0x06 | grenade_index |
| v4 | _word_bs_definition | 2 | 0x08 | zoom_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 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.
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.
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.
.dataThe non-null slots of device_data_definition, with the image
words the binary ships device_data_definition.c.
| Slot | Image word | Function |
|---|---|---|
initialize | 0x837B4A08 | devices_initialize |
dispose | 0x837B4A40 | devices_dispose |
initialize_for_new_map | 0x837B54E8 | devices_initialize_for_new_map |
dispose_from_old_map | 0x837B4A48 | devices_dispose_from_old_map |
datum_new | 0x837B4A58 | device_new |
datum_delete | 0x837B5598 | device_delete |
datum_update | 0x837B5658 | device_update — the convergence step |
datum_export_function_values | 0x837B4AA0 | device_export_function_values — chapter 8 |
datum_preprocess_node_orientations | 0x837B4C88 | device_preprocess_node_orientations |
render_debug | 0x837B4E30 | device_render_debug |
| all networking slots | 0x00000000 | devices 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.
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.
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.
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.
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.
device_updatePower 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.
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.
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.
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 name | Return | Parameters | Evaluator |
|---|---|---|---|
device_group_get | real | device_group | device_group_get_value_evaluate |
device_group_set | boolean | device_group, real | device_group_set_desired_value_evaluate |
device_group_set_immediate | void | device_group, real | device_group_set_actual_value_evaluate |
device_group_change_only_once_more_set | void | device_group, boolean | device_group_change_only_once_more_set_evaluate |
device_get_position | real | device | device_get_position_evaluate |
device_set_position | boolean | device, real | device_set_desired_position_evaluate |
device_set_position_immediate | void | device, real | device_set_actual_position_evaluate |
device_get_power | real | device | device_get_power_evaluate |
device_set_power | void | device, real | device_set_power_evaluate |
device_one_sided_set | void | device, boolean | device_one_sided_set_evaluate |
device_operates_automatically_set | void | device, boolean | device_operates_automatically_set_evaluate |
device_set_never_appears_locked | void | device, boolean | device_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.
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.
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.
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_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.
Which script command writes which part of
player_effect_globals
player_effect_globals_definition.h
scripted_player_effect_definition.h.
| Region | Offset | Written by | Note |
|---|---|---|---|
local_player_effect_data[2] | 0x000 | the non-scripted effect system | 472 bytes |
screen_fade | 0x1D8 | fade_in, fade_out | colour, ticks, start_time, fading_out |
scripted_effect.max_translation | 0x1EC | player_effect_set_max_translation | world units |
scripted_effect.max_rotation | 0x1F8 | player_effect_set_max_rotation | degrees in, radians stored |
scripted_effect.max_intensity | 0x204 | player_effect_start | — |
scripted_effect.timer / total_time | 0x208 | both player_effect_start and _stop | attack or decay, in ticks |
global_flags | 0x20C | player_effect_start, _stop | running bit, ending bit |
| (not in this block) | — | player_effect_set_max_vibrate | thunks 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.
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.
What each device_function_mode exports into
object.incoming_function_values[slot]
device_function_mode.h
device_export_function_values.c.
| Mode | Name | Exported value |
|---|---|---|
| 0 | none | slot skipped entirely — not even zeroed |
| 1 | power | device.power |
| 2 | change_in_power | abs(power_velocity) / runtime_maximum_power_velocity |
| 3 | position | device.position |
| 4 | change_in_position | abs(position_velocity) / runtime_maximum_powered_position_velocity |
| 5 | locked | 1.0 when depowered, one-shot fired, non-automatic or one-sided; forced back to 0 when fully open or never_appears_locked |
| 6 | delay | delay_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.
(device_group_set door 1.0) to a moving doorThe 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 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.
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.
Every diagram in this edition, in reading order. The swatch is the figure's dominant category: script, render, sim, io, infra.