Strat language (LlamaMod's assembly for the strat VM)

Object behaviour ("strats") is bytecode for the VM at groove.exe FUN_0054d180, stored per level in the STPC chunk as code units (one per compiled source file; notes/editor-cross-import.md). format.strat turns a unit into text and back:

Class	Role
`OpTable`	opcode/property names and docs (resources `ops.tsv`, `props.tsv`; notes/strat-opcodes.md)
`StratListing`	unit → assembly text (+ per-line metadata: offsets, editable constants)
`StratAssembler`	text → unit words; layout = where the unit goes + model/anim/unit offsets
`StratPseudo`	read-only structured view (expressions, if/else, loops)
`Num`	literals: `42`, `0x2a`, `1.5` (20.12), `90deg`

Round trip (golden test StratRoundTripTest): disassemble → assemble is byte-identical for all 1461 units of all 34 level WADs (670 555 words), with no instruction emitted as raw words. Own syntax; the style is loosely inspired by Stratigise (knowledge only, no code used).

Syntax

One statement per line; ; starts a comment; name: defines a label (several per line allowed).

; unit 4 (139 words at STPC 0x422fce): Coin
.unit Coin
ev_0000:
        .event 4, 0, L_0084                  ; handler entry
L_000c:
        .string "Coin", "WARNING: Coin "
        .word 0x6f200020
L_0084:
        pushProp damageTaken
        push 2048.0                          ; = 8388608
        notEqual
        jz L_013c
        ...
Coin:
        debugName "Coin"
        address model:5                      ; model
        setModel
        onEvent ev_0000, 0                   ; event type 4 → L_0084
        pushVar snapToFloor                  ; v0 (alias from the object schema)
        jz L_018c
        ...
L_0218:
        push 5.625deg                        ; = 64.0
        turnLeft
        jmpYield L_0218
        end

Directives

Directive	Words	Meaning
`.unit NAME`	0	unit name (informational)
`.alias name = vN`	0	variable alias; the listing declares one per schema parameter
`.word a, b, …`	n	raw words (numbers or `@label` = absolute address of a label)
`.string "a", "b"`	⌈(bytes)/4⌉	packed NUL-terminated strings, zero padded to the next word (`\"`, `\\` escapes)
`.event type, param, target`	3	event table entry; `rel` is computed against the `onEvent` that names this entry's label (exactly one must)
`.switch n` + n × `.case v, target` / `.case imm v, target`	1 + 2/3 each	switch table (case as 0x44 short or 0x45 immediate); targets relative to the `switch` naming the table's label
`.at name, k`	0	defines `name` = next statement + k bytes (labels inside an instruction; not needed by the CD levels)

Instructions

mnemonic operand, operand… – mnemonics from notes/strat-opcodes.md (case-insensitive) or op_XX for any opcode.

Opcode kind	Operand syntax
short ops (< 0x45)	one operand, encoded in the high 16 bits (−32768…32767)
– variables (pushVar, popVar, pushVarAddr, parent vars)	`v3` or an alias
– globals (pushGlobal, popGlobal, …)	`g12`
– properties (pushProp, popProp, pushPlayerProp, …)	name from props.tsv (`x`, `rotY`, `floorHeight`) or `prop17`
– branches/calls (jz jnz jzYield jnzYield jmp jmpYield call callYield pushCodeWord pushCodeAddr popCodeWord)	label (or a number = raw word offset)
– `switch`	label of the `.switch` table
– `onEvent entry, slot[, hi=N]`	label of the `.event` entry, slot number
– `skipArgs`/`print` (0x02/0x03)	raw words: count, items… (`hi=N` first if the opcode word has high bits)
`push v` (0x45)	number; `tex:N` marks a texture index (before shadowTexture/spawnParticle/…)
`address ref` (0xb2)	`model:N[+off]`, `anim:N[+off]`, `unit:N[+off]`, `@label[+off]` (own unit), or a number (negative = DEFANIM.WAD animation)
`soundAddress sound:N` (0xd7), `topSay text:N` … (0xf0/0xfa)	level sound / text index
`debugName "Name"[, k]` (0xd4 0xea rel)	name string: the k-th (default first) occurrence of the string + NUL in the unit that starts a word or follows a NUL; or a label
other long ops	as many numbers as inline words (`spawn 3, 6, 0, 0, 0`)

Numbers: decimal, 0x…/-0x…, fixed point with a dot (1.5 → 6144), angles 90deg (360deg = 0x1000000). The listing prints fixed point when the value reads naturally as one (≥ 64 raw, ≤ 3 decimals), degrees for constants consumed by turn/tilt/sin/cos/popProp rot* (only when exact).

Assembler rules

Two passes (sizes are fixed per mnemonic/directive, then encoding). Errors carry line numbers (unknown mnemonic/label, operand count, 16-bit overflow, missing onEvent/switch for a table, unknown model/anim/unit index). Layout: base = STPC offset of the unit's first word (@label and own-unit addresses), plus the model/animation/unit offsets of the target STPC for model:N etc.

Script view (`StratPseudo`)

Read-only. Stack code folded into expressions (self.y = self.floorHeight + 204), properties as self.x, player.y, parent.v3, camera.…; forward jz/jnz → if {…} (with else when the block ends in a forward jmp), backward jmp/jmpYield → loop {… yield}; blocks are only built when they nest, everything else stays goto label. Inline operands in <>: spawn<3, 6, 0, 0, 0>(10.0, 204, 450, unit:35+0x28). Example (Coin):

strat Coin:
setModel(model:5)
collRadius(409)
onEvent ev_0000, 0  // event type 4 → L_0084
if (v1) { collisionOn<32768>() ... }
if (v0) {
    if (self.floorMaterial == -1.0) { skipArgs … } else {
        self.y = self.floorHeight + 204
        self.rotY = rnd(4096.0)
    }
}
loop { turnLeft(5.625deg); yield }

Editing in the level editor (`editor.tools.strats`)

Script panel (bottom dock, View → Panels → Script, Ctrl+Shift+K): unit chooser (all code units with their type names, custom ones marked), Follow selection, Script/Assembly view, Find, Uses (all lines with the selected operand), help for the selected line (opcode semantics, property docs, constant values), side panel with parameters (schema aliases + use counts), "referenced from" (units whose address operands point into this unit = who spawns it) and instance count. Inspector section "Script" with Open script.
Constants (double-click / Edit value…): push, pushShort, sound, texture and text operands. Undoable (ConstantEdit), applied to reference + scene, stored in level.json stratEdits.constants as {unit, name, at (byte offset in the unit), old, new, short}; on load the old value is checked first (mismatch → warning, skipped). Edited lines are orange.
New types (Clone as new type… in the panel, Level → New object type from script…): source text (the cloned unit's listing with the strat renamed, or a template), entry label, type fields/parameters taken from an existing type. Check assembles and verifies; Create appends the unit at the end of the STPC code region (nothing else moves), adds the type to the catalogue (Assets → Objects), stores stratEdits.types {name, basedOn, entry, source, proto}. Verification: the merged STPC is disassembled again (no decode errors, entry decoded, every address operand of the new unit hits a model, animation set or code, and the new unit's listing re-assembles to the same words).
Load order (ProjectIO.LoadHook.order()): constants of base units (−10) → imported types (CrossImport, 0) → constants of imported units and custom types (+10). Custom units are always last on load; if types were imported after a custom type in the session, the stored strat codes are remapped with the saved custom block position (stratEdits.session).

Limits

Custom types cannot be removed or re-edited in place (clone again; the old unit stays as dead code until the project is recreated). Constants of custom types are changed through their source.
pushShort holds only −8.0…7.99; bigger values need a source edit (push).
The script view is a reading aid (gotos where blocks do not nest; expressions assume the documented pop/push counts; ops with variable stack use are shown raw).
Names/semantics of low-confidence opcodes and properties are guesses (see confidence column).

8.3 KiB Raw Blame History Unescape Escape