event_script: event script modules

Source

docs/formats/event_script.md

SHA-256

e0767c10…0a0036a9

A compiled event script: one or more scripts of stack-machine bytecode, each with its functions and jump targets, plus the module's integer and float constants, variables and the lists of functions its opcodes start on other scripts. The script VM in the executable runs it (Event scripts). Modules sit as pakd entries in event/scene/*.dat and event/event_data.dat; they have no text magic, only a header word 0x8000000C. The layout is Gibbed's (Gibbed.TacticsOgre.ScriptFormats, written for the PSP release), which every module fits. Terms are as in the glossary.

Where modules are

• confirmed: modules are in many of the event/scene/*.dat files, one or more in each, and in event/event_data.dat (#9 and #13). In the scene files they are the first entries of the top-level pakd, before any other kind; in event_data.dat they come after other entries. Source: DuckDB over each file's entries.jsonl (R36).
• confirmed: each module's entry is its total_size plus 16 zero bytes, the pakd entry padding (containers.md). Source: DuckDB (R36): every module's total_size is its entry's size − 16, and the 16 bytes after it are zero.
• likely: the event code hands a scene's module to VM context 0 (0x1402d0600 → 0x14034e780, 0x14034e9d0). Source: static analysis.

Header

0x64 bytes. Offsets are from the start of the module, and every _offset field is an offset from the start of the module.

• confirmed: every module passes Gibbed's header checks (the fields above it requires to be constant, and unk_0x40_offset as ScriptFileHeader works it out from module_vars_size). Source: DuckDB over header.jsonl and the modules' bytes (R36).
• confirmed: in every module, the script table, the variable table and the unk_0x30_offset lists lie inside total_size where their offsets and counts say, and every script's instruction_count instructions walk with the Opcodes sizes. Source: the R19 decode and round trip, all 1,656 (see Method). A round trip passes with any split of a record into fields, so the fields' meanings keep their confidence.
• confirmed: the regions the offsets point at come, in most modules, in this order: unk_0x44 (0 in most), unk_0x10, author, source, unk_0x14, module vars, unk_0x40, unk_0x5C, ints, floats, variables, scripts, unk_0x2C, autostart, unk_0x30, unk_0x48, strings. Source: DuckDB over header.jsonl (R36: each offset no greater than the next).

Scripts

0x30 bytes each, after the table's s32 count.

Variables

8 bytes each, after the table's s32 count.

Scope

Bits 24–26 of location: where the variable's storage is (0x14034d500, 0x14034e780).

The unk_0x30_offset lists

At unk_0x30_offset: an s32 count of lists, then each list's u32 offset. Each list is a u32 count, then its items, below: the functions opcodes 95, 97 and 99 start on other scripts' threads (0x14034de80, 0x14034df10, not read). Likely; Gibbed RequestHeader.

Code

• likely: an instruction is an opcode byte; opcodes 0x47 (71) and up are followed by a u16 operand, so they take 3 bytes, and the rest take 1. Source: 0x14034a1b0 (reads the operand when the opcode is above 0x46); the size field of each opcode's record (exe.script_opcodes); Gibbed OpcodeHelpers.HasImmediate. confirmed: walking every script's instruction_count instructions with this rule finds only opcodes 0–99, in every module (the round trip, R36: the decode walks with the Opcodes sizes, which are this rule's for every opcode a script uses, and refuses an opcode not in it).
• likely: each opcode's name and what its case does are in Event scripts; the numbers are Gibbed's (reference_tools/Gibbed.LetUsClingTogether/docs/cutscene_scripting/opcodes.md). Its size and operand are below.
• likely: a call opcode's operand is a native's number (natives); a jump's is an index into the script's jump table; a variable opcode's is an index into the variable table; push_int_table and push_float_table index the int and float tables; push_int_immediate carries the value. Source: 0x14034a1b0, 0x14034d500, 0x14046c3b0.

Opcodes

Size counts the opcode byte and its operand, as the interpreter steps by it: the size of each opcode's record at 0x140C9E300 (exe.script_opcodes). Operand names the u16 that follows (Gibbed's operand_kind in the same records, Event scripts); — for none. Opcodes 0–2 have size 0 and 71 has size 1 though the interpreter reads a u16 operand for every opcode above 0x46; no script uses any of them (the R19 decode). Confidence: likely, from the records; the round trip shows only that every script walks with these sizes.

Operands: variable an index into the variable table; tag_index into the unk_0x2C_offset table; int_index and float_index into the int and float tables; value the signed value pushed; jump an index into the script's jump table; native a native's number; list an index into the unk_0x30_offset lists; unk_operand read by no code (98's record has operand_kind 0).

Decoded data

tor export writes each module as a folder <n>.event_script/ with one .jsonl per section (toolchain/README.md (../../toolchain/README.md#decoded-data)):

The other regions (the int, float and string tables, the function and jump tables, unk_0x14, unk_0x40, unk_0x44, unk_0x48, unk_0x5C, the module variables and the variables' initial values) aren't decoded yet; they are kept as they are (Rebuilding) and are in the entry's .bin.

Rebuilding

A module is rebuilt in place: its original bytes, with each decoded section's records written over their own bytes. confirmed for unchanged rows: all 1,656 modules rebuild byte for byte from their rows (see Method).

1. header: every Header field, at 0x00–0x63.
2. scripts, variables and the list items: each row's fields over its record, in order; a section keeps its row count (a list, its item count).
3. code: each script's instructions, in order, from its first instruction's offset: the opcode byte, then the operand as its type. A script keeps its instruction count and its code's length in bytes, so an opcode may change only to one of the same size.
4. Every other byte is kept, the pakd padding after total_size included.

Rows that would add, remove or move a record or an instruction, or change a script's code length, are refused with an error: that needs the regions after it moved and every offset into them rewritten, which the toolchain doesn't do yet (lead below). Offsets in edited rows (code_offset, name_offset …) are written as given and not checked.

How the game reads it

• likely: the game reads only the header fields 0x14, 0x20–0x2C, 0x38, 0x40, 0x48, 0x50 and 0x54 when it loads a module, the unk_0x30_offset lists from the interpreter, and the scripts and variables through those. It checks nothing: not the magic or total_size. Source: 0x14034e780, 0x14034e9d0, 0x14034a1b0.

Leads

• A byte map of a whole module: decode the regions still kept as bytes (the int, float, string, function and jump tables, unk_0x44, unk_0x48, the module vars, the variables' initial values), so the docs describe every byte.
• Rebuilding with a new layout: adding or removing instructions, functions, variables or strings means moving every region after it and rewriting the header's and records' offsets and the jump tables; needed before a mod can change a script's length.
• What table_index, unk_0x18_offset, unk_0x1C_offset and unk_0x22 do, and the second u16 of a variable's initial value.
• The unk_0x30_offset lists: 0x14034de80 and 0x14034df10 would confirm the {script_index, function_index} pairs and give unk_0x30_offset a name.
• Script names are Shift-JIS by Gibbed; check whether Reborn's are all ASCII.
• The format and the VM share a word: event_script for the format, "script VM" for the interpreter (ScriptVm_*, views exe.script_*).