# 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, switch, break/continue) |
| `StratCompiler` | script language → assembly (new behaviour) |
| `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 (not parsed back). Stack code folded into expressions (`self.y = self.floorHeight + 204`),
properties as `self.x`, `player.y`, `parent.v3`, `camera.…`. Control flow is rebuilt from the jumps
where the blocks nest:

| Jumps | Shown as |
|---|---|
| forward `jz`/`jnz` over a block (+ `jmp` over a second block) | `if (…) {…} else {…}`; an `if` that is the whole else part → `} else if (…) {`; an empty then-part is negated |
| backward `jmp`/`jmpYield` | `loop {… yield}`; first statement `if (c) break` → `while (!c) {…}` |
| backward conditional jump | `do {…} while (c)` (`/*yield*/` for jzYield/jnzYield; empty body: `do {} while (c) /*yield*/`) |
| jump to the end / head of the innermost loop | `break` / `continue` (also as `if (c) break`) |
| `switch` + `jmp end` with the cases in between | `switch (v) { case 1.0: … break … }` (`default:` when the jmp goes to a case-like block) |

Everything else stays `goto label` (mostly multi-level breaks out of nested loops and `||` chains
that jump to a common far target). Over all 1461 units: **11 019 → 400 gotos** (2026-11-07;
guarded by `StratPseudoTest`, which also checks balanced blocks and that every remaining goto has
its 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 }
```

## Script language (`StratCompiler`) – writing NEW behaviour

A small structured language in the style of the script view, compiled to the assembly above (so
everything the assembler checks still applies). Implemented slice (2026-11-07): strats, subroutines,
aliases, assignments, expressions, if/else if/else, while, loop, do-while, break/continue, yield,
calls of any opcode by name. Tests: `StratCompilerTest`; verified in game (village 1:
`img/mods/strats_script_game.jpg`).

```
// bobs one cell up and down and turns
strat Bobber {
    alias base = v0              // .alias base = v0
    alias phase = v1
    setModel(model:5)            // any opcode: name<inline operands>(stack arguments)
    base = self.y + 1.0
    phase = 0
    loop {
        phase = phase + 4deg
        self.y = base + sin(phase)
        turnLeft(4deg)
        yield                    // last statement of a loop → the loop's jmpYield back edge
    }
}

sub wobble {                     // called with "call wobble", ends with return
    self.rotZ = sin(self.rotY) * 0.1
}
```

| Construct | Compiles to |
|---|---|
| `strat Name { … }` | `.string "Name"`, label `Name:`, `debugName "Name"`, body, `end` unless the body cannot fall through |
| `sub name { … }` / `call name` / `return` | label, body, `return` / `call name` / `return` |
| `x = e`, `x += e` (`-=`, `*=`, `/=`) | e, pop op of x; `x += 1.0` / `x -= 1.0` → address + `inc`/`dec` |
| places | `vN`, alias, `gN`, `self.prop`, `player.prop`, `parent.prop`, `parent.vN`, `camera.`/`target.`/`target2.`/`boss.`/`dialog.prop` (props.tsv names or `propN`) |
| literals | as in the assembly: `10.0` = ten, `10` = 10 raw units (1/4096), `90deg`, `0x10`; 16-bit values use `pushShort`, others `push` |
| references | `model:N`, `anim:N`, `unit:N` (`address`), `sound:N` (`soundAddress`), `tex:N` (`push`) |
| operators (low → high) | `||` `|` (or) · `&&` (and) · `&` · `==` `!=` · `<` `>` `<=` `>=` · `<<` `>>` · `+` `-` · `*` `/` · unary `-` `!` |
| `op<a, b>(e1, e2)` | e1, e2, `op a, b`; the argument count must match the opcode's pops; a value-returning op used as a statement is followed by `pop` |
| `if (c) {…} else if … else {…}` | `c; jz else; …; jmp end; else: …` |
| `while (c) {…}` / `loop {…}` | head label, `c; jz end`, body, `jmp`/`jmpYield head` |
| `do {…} while (c)` | body, `c; jnz head` |
| `break` / `continue` / `yield` / `end` | `jmp end` / `jmp head` (do: the condition) / `jmpYield next` / `end` |

The generated assembly starts with the script as `;| ` comment lines, so the editor can show the
script again (*Edit type…*). Comments: `//`, `/* */`; `;` and newlines separate statements.

**Next steps (not implemented)**: event handlers (`on touched { … }` → `.event` table + `onEvent`),
`switch`, `spawn` with typed arguments, local names for parameters from the object schema, `for`,
constant folding, typed numbers (int vs fixed) instead of the assembly's literal rules,
short-circuit `&&`/`||` (now: both sides are evaluated, like the original `and`/`or` opcodes).

## 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).
* **Edit type… / Delete type…** (Script panel, Inspector *Script* section of a custom object):
  edit opens the same dialog with the type's source (script or assembly), *Apply* rebuilds all
  custom units (`TypeEdits.edit`, one undo step) and the placed objects move to the new entry.
  Delete warns with the number of objects that use the type and removes them with it
  (`TypeEdits.delete`: `Edits.delete` of the users + the type list change, one undo step).
  Creating is undoable too (`TypeEdits.create`), except when imported types follow the custom
  block (then appended as before).
* **Language** (dialog): *Assembly* or *Script* (compiled by `StratCompiler`, see above);
  switching Script → Assembly shows the generated code.
* **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 are edited and deleted as a whole list: the custom units are cut off the code and
  appended again (objects follow their type's new entry). Not possible while object types imported
  after the custom ones sit behind them in the code (save and reopen the project first; on load the
  custom types always come last). A custom type that addresses another custom type's unit with
  `unit:N` breaks when that index changes. 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).