Start here

↑ ↓ to move, Enter to openKeyword search
Game internals

Blam Script (HSC) in Halo Campaign Evolved

Build
2026.06.26.1097863.1-Rel-i343-Meteorite-2606-CU2 (Steam)
Crates
crates/blam-hsc, exposed through mjolnir script, mjolnir scripting and mjolnir compile
Artifacts
defs/hce/scripting.json
Date
2026-08-03

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

Build: 2026.06.26.1097863.1-Rel-i343-Meteorite-2606-CU2 (Steam) Crates: crates/blam-hsc, exposed through mjolnir script, mjolnir scripting and mjolnir compile Artifacts: defs/hce/scripting.json Date: 2026-08-03

Build label: this note is stamped CU2; the installed build is CU4 (see build_lock.md). defs/hce/scripting.json was regenerated and stamped CU4 on 2026-08-18, and the --verify and --recompile tables below were re-measured on CU4 on 2026-09-29.

Summary

Halo Campaign Evolved's missions are scripted in HSC, the same S-expression language Bungie shipped from Halo: Combat Evolved onward, and it lives in the scenario tag. Two findings make it unusually tractable:

  1. The original .hsc source ships verbatim, comments and all. a30 alone carries nine source files totalling 231 KB, the largest 4,449 lines. Nothing had to be recovered to read the campaign's scripting — it is sitting in the tag.
  2. The compiled expression tree ships too, so the two can be checked against each other. Across the thirteen campaign scenarios: 215,775 live expression nodes, 6,827 scripts, 1,801 globals (6,829 scripts on CU4).

The opcode table is Halo Campaign Evolved's own — of the 483 opcodes the campaign calls, 24 agree with Halo Reach's table and 7 with Halo 4's — but it did not need reverse-engineering out of HaloSimulation_tag_release.dll, for the same reason the tag definitions did not: the data describes itself. See tag_body_format.md.

Reproduction:

$env:HCE_PAKS = "<install>\Meteorite\Content\Paks"

cargo run --release -p blam-cli -- script --tag a30 --declarations
cargo run --release -p blam-cli -- script --tag a30 --source a30
cargo run --release -p blam-cli -- script --tag a15 --decompile f_md_3d_play
cargo run --release -p blam-cli -- script --verify
cargo run --release -p blam-cli -- script --recompile
cargo run --release -p blam-cli -- scripting --build "<build string>"

# No game installation needed; reads the committed corpus.
cargo run --release -p blam-cli -- compile my_mod.hsc --show

Where it lives

Seven fields of scenario_block_struct, all in one run at 0x3c8:

OffsetFieldBlockHolds
0x3c8scriptshs_scripts_block (max 2048)name, type, return type, root expression
0x3d4globalshs_globals_block (max 512)name, type, initializer expression
0x3e0referenceshs_references_block (max 512)tags the scripts pull in
0x3ecsource fileshs_source_files_block (max 16)the original .hsc text
0x3f8scripting datacs_script_data_blockAI point sets
0x450hs unit seatshs_unit_seat_blockseat mappings
0x498hs syntax datumshs_syntax_datum_block (max 64512)the compiled tree

Plus script string data, a data field holding the string blob every node's string_offset points into (35–68 KB per scenario).

The blob ends with a 0x1000-byte reserve. In all thirteen shipped scenarios the last string ends exactly 4,096 bytes before the blob does, and those bytes hold leftovers — non-zero in every one of the thirteen — rather than strings. It is room the engine keeps for strings it adds at runtime, such as a line typed at the console, so a writer that packs the blob tight hands those writes whatever follows it. The compiler appends the same 4,096 bytes, as zeros (blam_hsc::emit::STRING_DATA_RESERVE), and mjolnir script --rebuild-check checks the blob, reserve included, reads back unchanged.

The expression datum

hs syntax datums is a Blam datum array, not a list: nodes address each other by handle, and freed slots stay in place. 24 bytes each:

OffsetSizeFieldNotes
0x002generationPairs with the array index to form this node's handle
0x022opcodeEngine function, script index, or global index
0x042value typeIndexes the scenario's own value-type enum
0x062flagsWhat the node is; a bitfield, see below
0x084nextHandle of the next sibling
0x0c4string or source offsetInto script string data for a name, string or variable read; into the source files for a call or a number (below)
0x104dataFirst child for a call; the literal payload otherwise
0x142line number1-based, in the source file it came from
0x162—The definitions call it HMM; zero in every shipped datum

A handle is index in the low half and a generation counter in the high half; 0xFFFFFFFF is null. Comparing the generation against the target's own is what makes a stale handle detectable rather than silently resolving to whatever later took the slot.

Blam tooling calls this half-word the datum's salt, and the shipped definitions call its field datum header. crates/blam-hsc calls it generation, because that is what it does: an ABA counter for a slab allocator, nothing to do with cryptography.

A free slot reads as 0xBA fill with a zeroed generation. 56,415 of the campaign's 272,190 slots are free; walking the array without checking would decode garbage.

The flags at 0x06 are a bitfield — the definitions name the field flags — not an enum, though only five combinations ever occur:

BitNameSet on
1primitiveevery leaf; clear on a call
2script indexa call whose opcode indexes scripts
4variablea global or parameter read
8permanentevery live node shipped
16parameterparameter reads only — the one bit not in the Reach-era set
ValueBitsKind
8permanentGroup — a call. data points at the child that names the callee
9permanent, primitiveExpression — a leaf: either that name, or a literal
10permanent, script indexScript reference — a call to a script in this scenario
13permanent, variable, primitiveGlobals reference — data indexes globals
29parameter, permanent, variable, primitiveParameter reference

blam_hsc::expr::NodeFlags holds the raw bits, and ExpressionType is the classification of the five; any other combination is carried through untouched.

Recovering the opcode table

A call node points at a child whose string_offset names the callee. Reading that for every Group node across all thirteen scenarios yields 483 opcodes with no disagreement — no opcode ever resolved to two different names, which is the check that the rule is right (mjolnir scripting fails rather than exporting if it ever does).

defs/hce/scripting.json records, per opcode: the name, observed return types, argument count range, per-position argument types, and the call-site and scenario counts behind each. Signatures are inferred from use, not read from the engine: a function the campaign never calls is absent, and 46 of the 483 rest on a single call site. The file carries those counts so a consumer can tell the difference.

Source offsets, and cond

+0x0c is only a string offset on a node that has a string. On a call, and on a number, boolean or void leaf, it is a byte offset into the scenario's source files taken end to end in block order, each file followed by its NUL. The definitions name the field source_offset, and the data agrees: all 72,611 call nodes across the thirteen scenarios land on a (, and all 24,531 numeric and boolean literals that are not a cond's trailing else land on their own token.

That is what makes cond recoverable. It has no opcode — it is desugared to nested if before any node is emitted — but every if and begin the desugaring makes, and the literal it adds as the last clause's else, record the offset of the cond itself: 1,162 ifs across the campaign point at the text (cond. The decompiler puts one back wherever an if does, provided the shape matches exactly:

(if test1 (begin body1…) (if test2 (begin body2…) <zero of the cond's type>))

Every shipped cond ends in that zero: a void leaf in 207 of 230, a boolean or short 0 in the rest. The compiler writes the same shape and the same offsets, so a compiled tree decompiles back to cond too. Without the source files — a stripped scenario — a cond still renders as the ifs it is.

One thing the tree does not preserve: special forms are not marked. The value-type enum has a special_form entry, but no node in any of the 272,190 shipped datums carries it.

Quoting

Whether a literal is written "like this" or bare is not recorded anywhere in the tag — a damage literal and an ai literal are both just a string offset. It is recovered by asking how the source that produced the tree wrote each string, with two corrections that matter:

  • A string the source writes both ways is evidence for neither. easy is a bare game_difficulty in (= (game_difficulty_get_real) easy) and a quoted string in (print "easy") a few tokens away; counting it for both made each type look like the other and inverted the result.
  • Quoting is partly a property of the argument position, not just the type. A string_id is quoted as the marker name in (object_at_marker x "primary_weapon") and bare in plenty of other places, so a position with its own evidence overrules the type-level rule.

Syntax worth knowing

Three things bit the lexer, all confirmed against the shipped source:

  • ;* … *; is a block comment. global_scripts uses them, and reading one as a line comment leaves the rest of the block as stray top-level tokens — and made a30 look like it had an unbalanced paren at line 2030 when it does not.
  • A ; inside a string is text, not a comment. The dialogue lines are full of them.
  • A backslash in a tag path is a literal character, not an escape: "objects\characters\marine" is a path, not an escape for \c.

Source files are NUL-terminated in the tag; the terminator is not whitespace, so a lexer that keeps it reads a stray token at the end of every file.

How well the decompiler does

mjolnir script --verify decompiles all 6,829 campaign scripts and compares each against the source the same scenario carries, as token streams — comments cannot come back, and the compiler coerces -1 to -1.0 and accepts 0 for false. On CU4:

OutcomeScripts
Token-for-token match6,463 (94.6%)
Source used cond, and still differs27
No source block to compare against151
Genuinely differ188

Before cond was recovered the second row was 205. The 27 left are scripts that use cond and have a quoting disagreement: with quotes ignored, all 27 match. Every one of the 188 is a quoting disagreement too — same text, quoted on one side and bare on the other. Nothing else is unexplained.

The compiler

crates/blam-hsc/src/compile.rs goes the other way: HSC source into an expression tree, string blob, and scripts/globals blocks. mjolnir compile <file.hsc> runs it against the committed corpus and needs no game installation.

What it reproduces is the tree semantically, not byte for byte. Three things are deliberately the compiler's own:

  • Datum generations. The shipped arrays use two generation bases per scenario, an artifact of the engine compiler's datum allocator wrapping mid-run. A handle only has to agree with its target, so this emits one base throughout.
  • Free slots. A shipped array is sparse; this emits a dense one.
  • String blob. The shipped blob repeats strings — 9,168 distinct offsets across 2,806 distinct strings in a30 — and this interns instead.

Everything the engine reads is reproduced: expression types, opcodes, value types, sibling chains, source offsets, and the rule that a call's first child names it and carries the same opcode. Compiling a30's own source and walking each script against the shipped tree, all 5,845 call nodes and all 1,937 numeric, boolean and void leaves carry the shipped source offset. Rules confirmed against the shipped data rather than assumed:

Nodeopcodedata
Group (call)the engine functionhandle of the first child
Script referenceindex into scriptshandle of the first child
Globals referencethe value typeindex into globals
Parameter referencethe value typethe parameter's index
Literalits own value typethe packed value, or what a name resolves to

The type of a literal is chosen by asking the position what it usually holds and then checking the token can actually be that. Taking the position's commonest type alone gets real cases wrong: the corpus says set usually takes a boolean, which compiled (set s_music_trigger 30) to true, and it says < usually takes a short, which compiled 0.6 to 0. Candidates are now tried commonest-first and the first one that fits the token wins.

Name literals

A literal carries two types. value type (+4) is what the position takes; opcode (+2) is what the literal itself is. They differ where a name converts: 626 shipped object_name literals sit in object positions, 563 player literals in unit positions, 194 ai literals in object positions. And a name's data is not zero but the index of what it names, which is why the compiler needs the scenario it is compiling for (Compiler::with_names, fed by blam_hsc::read::names). Each encoding below was measured by looking every shipped literal's string up in the block it names, across all thirteen scenarios, and is resolved only because it agreed on every node:

KindBlockdata
object_name, unit_name, vehicle_name, device_nameobject names0xFFFF0000 | index
trigger_volume, cutscene_flag, cutscene_title, zone_set, insertion_point, starting_profile, user_interface_objectivethe block of that name0xFFFF0000 | index
script, ai_command_scriptscripts0xFFFF0000 | index
foldereditor foldersindex
player—n for player<n>
point_referencepoint sets, then its pointsset << 16 | point, point 0xFFFF for a whole set
aisquads, squad groups, a squad's spawn points and designer/cellstop three bits 001 squad, 010 group, 100 spawn point, 111 cell; a member carries its squad in the rest of the high half
string—its own offset into the string blob

String-id names fold - to _ when registered, so tv_checkpoint_bridge_a_pre-gold finds the volume stored as ..._pre_gold. A number is written over a word of 0xFF only as wide as its type — 11,681 of 11,683 shorts read 0xFFFF____, 6,123 of 6,144 booleans 0xFFFFFF__, the exceptions all a cond's trailing zero — and the compiler does the same.

Compiling each scenario's own source against its own names, every literal of these kinds whose two types agree with the shipped node also agrees on data: 3,408 trigger volumes, 2,459 object names of the four kinds, 5,211 ai, 1,934 point references, 2,718 scripts and the rest. Where they differ it is the position's type that was chosen differently, a separate and older question.

Not resolved, because shipped data did not establish the encoding: tag references (sound, effect, damage, animation_graph, object_definition, cinematic_definition — runtime tag handles), string_id, ai_line, unit_seat_mapping, device_group (the high half varies per element), the engine's enum cases (team, game_difficulty, skull, actor_combat_status, model_state), and ai literals naming an objective's task (20 nodes, one literal, whose index is not the task's position). These keep data zero, as before. A name that should resolve and does not is a warning. Across the campaign 860 fire, and in a30 63 of its 69 are engine globals such as ai_current_actor that the compiler does not know and so compiles as literals — the same, older gap that makes a shipped Globals reference come back as a literal.

How well it does

mjolnir script --recompile compiles each scenario's own source files, decompiles the result, and compares against the source that went in:

OutcomeScripts
Token-for-token match6,463 (96.8%)
Source used cond, and still differs27
Differ188
Compile errors0

Again all 215 are the quoting disagreement, which is a decompiler rendering question, not a compiler one. The check that separates the two is the fixpoint: compiling the decompiled output a second time must produce the same tree, since both trees are the compiler's own. All of them reach it (14 of 14 on CU4). 78 literals across the whole campaign had no usable type from either the position or the token, and are reported as warnings.

Writing it back

crates/blam-hsc/src/emit.rs serialises a section into the bytes a scenario holds, and blam_tag::patch::rewrite rebuilds the tag around it. Five things move together:

FieldSection
script string datatgda
hs syntax datumstgbl
scriptstgbl
globalstgbl
source filestgbl

Two facts the shipped data forced, neither of them obvious:

  • A block field carries its element count inline — the first four of its twelve inline bytes — duplicating the one in the tgbl header. A data field carries its byte length the same way. Resizing a block without fixing the enclosing element's copy leaves a scenario claiming a different number of scripts than it has.
  • Nothing outside the script section indexes the datum array. AI task fragments (script_fragment_block) and performance lines reference scripts by name and carry their own source text, so rebuilding the tree cannot dangle them.

Globals, parameters and source files are named in a fixed 32-byte string, so a name is at most 31 bytes. A longer one is a compile error against its line, and an error from the writer as a backstop — never a truncation, which would write two long names sharing their first 31 bytes as the same name.

mjolnir script --rewrite-check writes each shipped section back unmodified and asserts the tag comes out byte for byte identical: 13 of 13. That is the check that the writer is exact rather than approximately right.

mjolnir script --rebuild-check goes the whole way — compile the scenario's own source, write it back, and re-read the result from nothing but the bytes. 13 of 13 rebuild and read back cleanly, each about 100 KB smaller than it shipped, because the datum array comes out dense and the string blob interned.

What a rebuild loses

A rebuild produces only the scripts the source declares, and 150 scripts across the campaign have no source block (151 on CU4) — 9 in a15, 12 in a30. Those disappear. Since task fragments call scripts by name, a missing one can break behaviour far from the file being edited, so the editor reports the exact list before an edit is applied rather than letting the count quietly drop.

The references block is also left as it shipped: a script that newly names a tag will not add it there.

In the tag editor

A scenario tag gets a Script view alongside Form and Tree (and, since tag editor 0.10.0, a World view). The Script view shows the shipped source files with HSC highlighting, an outline of every script and global that jumps to its declaration, and export to .hsc. When a scenario carries no source — a stripped or hand-built mod — it shows decompiled output instead and says so.

Edit makes the current file editable. Compilation runs half a second after typing stops, so errors appear against their lines as you work, and Apply to mod is disabled until it builds. Applying compiles the script into the scenario, records the .hsc files under scripts/<group>/<tag>/ in the project folder, and marks the tag changed; the existing test, export and publish paths bake it like any other edit. The decompiled view is never editable — it is a rendering of the tree, and compiling it back would silently make it the mod's source of truth.

Not done yet

The quoting disagreements — 188, plus 27 in scripts that use cond. Both round-trip directions hit exactly this one class. It is the only thing standing between them and 100%.

Preserving source-less scripts through a rebuild. They could be decompiled and appended, but the decompiler is at 94.6% and injecting output that might be subtly wrong is worse than reporting the loss.