Syplheed-Reborn/docs/re/structures/isl-builtins.md

The 147 ISL built-ins

Status: ✅ table encoding, calling convention and the ScriptPhase state layout; ✅ ~135 of 147 handlers characterised from the disassembly; 🟡 three resolved only partially; ❔ the interpreter-command table is only partly recovered.

Companion to isl-bytecode (the instruction encoding) and mission-phase-advance (why phases hinge on these).

✅ Table and calling convention

0x8227226C … 0x822724B7 is 147 big-endian absolute VAs — no base-relative offsets. Verified structurally: the table starts immediately after the bctr at 0x82272268, 0x8227226C + 147·4 = 0x822724B8 is exactly where the first handler begins, and every target lies inside sub_82272220.

Six ids are unused defaults (0, 0x41–0x44, 0x7A) and about ten more are deliberate stubs returning a constant.

Arguments do not live in the instruction. Every handler starts addi r3,r31,20 ; bl 0x82454A40 — std::string::c_str() — so [phase+20] is a packed operand blob, which is what the local[] staging in isl-bytecode fills.

Return codes: 0 continue, 2 yield (re-execute next frame), 3 coroutine control. Five built-ins skip the pc advance on 2 and so genuinely block: 97, 120, 137, 142, 143.

✅ ScriptPhase state layout

offset	meaning
+88	32-entry float register file
+120	32-entry flag register file
+160	frame-wait counter
+164 / +176	int / double result register
+196	phase-finished flag
+232 / +236	code base / end-event offset
+244	symbol table 1 base (route + message names)
+272	trigger queue
+300	1 = not last phase, 2 = last
+304…+320	mission timer (elapsed, t0, limit, running, enabled)
+324	runtime unit array, indexed by symbol table 2 index

Per-unit record: +4 live object (NULL = absent), +16 state (2 = active; 1/3/4 = gone/dead/invalid), +32/40/48 position, +128/132 HP / max HP, +140 flag bitmask.

That is the hook into the data: blob fields indexing [phase+244] are symtab-1 indices and fields indexing [phase+324] are symtab-2 indices — the two tables already parsed in mission-script-ssb.

✅ The conditions a phase can test

id	name	what it tests
6 / 62	END_PHASE / FORCE_END_PHASE	sets [+196], with / without the end event
39 / 40	MARK_LAST_PHASE / mark_not_last	[+300] = 2 / 1
69 / 70	unit_state / unit_alive	a named unit's lifecycle state; state == 2
20 / 95	hp_pct_test / unit_hp_pct	unit HP as a percentage of max
18	dist_lt	3-D distance between two named units below a threshold
24 / 72	squad_survival_pct / group_ratio_pct	current ÷ initial squadron members × 100
56 / 94	unit_relation / is_engaged	relation between units; is anything engaging this one
33 / 34	global_counter0/1	two global counters read straight into [+164]
132–134	player gauges	speed/boost ratios and a player byte
73, 123–127	timer family	start / resume / stop / reset / read elapsed / read limit
8 / 9 / 93	set_flag / read_freg / clear_flag	latch a result into the 32-entry files
100 / 115	push_trigger / named_event	the engine→script edge

The state machine is therefore: a trigger fires a coroutine → the coroutine tests one of the predicates → it latches the answer with set_flag → some later thread reaches END_PHASE.

Two spot-checks I ran against the disassembly rather than taking on trust:

• id 4 (wait_s) — c_str(), li r3,2 (yield), lfd f0,0(r11), stfd f0,8(r30): a double seconds value into the thread countdown. Exactly as described.
• id 24 (squad_survival_pct) — indexes [phase+324] by [arg+4], rejects a NULL object and state 1, then calls 823011B0 (initial, packed hi<<16|lo) and 82301118 (current). Exactly as described.

✅ What Stage 02 actually uses — and it settles a standing question

Counting call sites in Stage02.ssb (data/isl-stage02.txt):

built-in	sites
unit_state	255
hp_pct_test	167
dist_lt	92
unit_alive	71
unit_relation	52
set_flag / clear_flag / push_trigger	12 each
END_PHASE / MARK_LAST_PHASE / FORCE_END_PHASE	12 / 8 / 3

Not used at all in Stage 02: squad_survival_pct, group_ratio_pct, global_counter0/1, is_engaged, player_gauge*, prompt_yes_no, deploy_and_wait.

🔑 So Stage 02's phases are gated on named-unit tests — destroyed / HP / proximity — and not on any aggregate count. The kill-counter primitives exist in the VM (33, 34) and this mission never calls them.

That is a direct answer to the standing "does the next wave start after N kills or after an event?" question, at least for Stage 02: specific units, not a number. "Certain objectives shot down" is right; "a certain number shot down" is not.

⚠️ Scoped to Stage 02. Other stages may well use squad_survival_pct — the counting is per-file and cheap to repeat.

✅ A real Stage 02 condition, read end to end

With the symbol tables resolved (unit arguments are symbol-table-2 indices), the bytecode reads as mission logic. From Stage02.ssb at 0xF524 (data/isl-stage02-conditions.txt):

unit_state(1, ADN110)     objective_marker(1, 0x01, 0, 8, 0)
unit_state(1, ADN111)     objective_marker(1, 0x02, 0, 8, 0)
unit_state(1, ADN112)     objective_marker(1, 0x05, 0, 8, 0)
                          objective_marker(1, 0x3A, 1, 8, 0)
set_flag(8)

Three named ADAN squadrons are polled for lifecycle state, each with its objective marker updated, and then flag 8 is latched. That is the shape mission-phase-advance predicted from the disassembly alone — trigger → predicate → set_flag → (later) END_PHASE — now seen in the mission's own code with the squadron names the roster tables already gave us.

The 12 END_PHASE sites are, by contrast, outro sequences: wait_cmds_drained → fade_sound(3) → builtin85(3) → wait_s(3) → END_PHASE → yield. The decision is not there; the terminator is.

⚠️ A decode bug that hid every argument

The first version of the argument tracker only followed local[i] = special[0]. But the common form is set.i k=01,03 — an immediate written straight into local[i] — and missing it meant every unit predicate printed with no arguments at all (unit_state rather than unit_state(1, ADN110)). The disassembly looked complete and was silently empty where it mattered most. Both staging forms are now handled.

✅ Correction: the script reads its own flags — no engine reader needed

Last iteration ended with "what reads the flag file is unknown", after an offset search failed and a promising hit in sub_8226D740 turned out to be a trigger record. The framing was wrong. I was looking for an engine-side reader; the consumer is the script itself, through built-in 9 (read_freg), which loads [phase+88][i] into the double result register [phase+176].

Stage02.ssb calls it 12 times — the same count as set_flag (12) and clear_flag (12). So the latch is symmetric and entirely inside the VM:

set_flag(i)   ->  [phase+88][i] = 1.0 , [phase+120][i] = 1
read_freg(i)  ->  [phase+176]   = [phase+88][i]
clear_flag(i) ->  zero entry i, or all 32 when the argument is -1

That closes the middle of the set_flag → … → END_PHASE chain: a condition coroutine latches a flag, and another coroutine reads it back with read_freg and branches on it.

🟡 op10 + op13 look like a switch

Seen repeatedly, e.g. at 0x5774:

op13  -> 0x5448
op10  imm 4
op13  -> 0x54F0
op10  imm 5
op13  -> 0x5598

Consecutive small immediates each paired with their own code offset is the shape of a case/branch dispatch, and op12 is already confirmed as the unconditional jump. Not confirmed — the handlers (0x82271598 for op10, 0x82271830 for op13) have not been read, and I am not going to name them from a pattern alone.

🔴 Correction: unit_state does NOT read +16 — it reads +4 and +104

Disassembling built-in 69's handler (0x8226ADF0) rather than trusting the one-line summary:

lwz  r10, 324(r30)     ; the unit array
lwz  r11, 4(r31)       ; arg blob +4 = the symbol-table-2 index
lwz  r10, 4(r10)       ; records base
lwzx r9,  r11, r10     ; rec = base[idx]
lwz  r9,  4(r9)        ; <-- rec+4
cmplwi r9, 0
beq  0x8226AF44        ; rec+4 == 0  ->  early exit, "absent"
lwz  r4,  4(r11)       ; rec+4 again
bl   0x82301240        ; lifecycle lookup ON rec+4
...
lbz  r11, 104(r11)     ; rec+104, a BYTE, compared against 1
li   r11, 2            ; -> result 2

rec+16 is never touched on this path. The predicate reads the handle at rec+4 — which is why it holds small consecutive integers (26/27/28) rather than pointers; sub_82301240 resolves it — plus the byte at rec+104.

That is exactly why poking +16 to 4 changed nothing (script-runtime-probe): the value was written into a field the condition does not consult. +16 still tracks deployed/active/destroyed faithfully as an observable — the arrival and death transitions were real — but it is a readout, not the input.

The corrected way to simulate "this squadron is gone" is rec+4 = 0, which takes the documented early exit. That is the next experiment.

⚠️ General lesson for this table: it was assembled by a subagent from handler behaviour, and this is the second field description that did not survive contact with the disassembly. Treat the per-offset meanings as leads to verify, not as facts — the identifications (which built-in does what) have held up well.

🟡 Not settled

• Three handlers resisted: id 55 (vt35, 411 instructions, returns a float), id 75 (vt52, message/HUD-ish), id 105 (vt73, meaning of unit field +600).
• The 1024-slot interpreter-command table is only partly recovered — 57 slots, by simulating the constant/stack dataflow of sub_822FE040.
• Names here are from handler behaviour, not from symbols; isl.py prints a bare builtinN for anything unread rather than guessing.

✅ The trigger queue at phase+272 — layout, and a readable pending count

Chasing what makes the phase-1 condition re-evaluate (the polls do not run continuously — see script-runtime-probe).

Two method corrections first, because both nearly sent me the wrong way:

• Searching the VM's address range for 272(rN) returns mostly vtable slot offsets, not accesses to the phase field. 0x82273174 lwz r11,272(r11) is followed by mtctr; bctrl — it is a virtual call through slot 68, nothing to do with [phase+272].
• [phase+272] is not a pointer to a queue — it is an embedded container. vt2 (sub_82265DD0) is literally addi r3,r3,272 ; b 0x8226E3B8, i.e. it passes phase+272 as this into the push.

Container layout, from the push/pop pair

sub_8226E3B8 (push, reached from built-in 100) and sub_8226E220 (pop, called every frame from sub_8226D740):

offset in the container	meaning
+12	list head/sentinel (addi r31, r30, 12)
+16	current node pointer
+20	element count — zero means empty; the pop tests it first and returns 0
+24	scratch: the popped node is stashed here

The pop hands the record out through out-parameters, reading from node+8: +0, +4, +8 as u32s, +16 as a double, +24 as another u32 — which matches sub_8226D740 passing six pointers into local slots.

🎯 [phase + 272 + 20] is a live "pending triggers" counter

That is the useful part: a single u32 that says how many triggers are queued, readable from /dev/shm with no debugger. Watching it alongside [ScriptMission+40] should show when the engine hands the script an event — which is exactly the moment the condition coroutines get started, and the thing every phase experiment so far has been blind to.

✅ Verified live

Read from a running Stage 02 mission (ScriptPhase 0xBE14DD80, container at 0xBE14DE90):

+272+12 = 0x000A0009      +272+16 = 0xBC28E620   (a node pointer)
+272+20 = 0                +272+24 = 0

[   0.0s] pending=0  phase=1 finished=0
[  68.0s] pending=1  phase=1 finished=0
[ 108.1s] pending=2  phase=1 finished=0

+20 moves, 0 → 1 → 2, while the phase ordinal stays 1. So it is a real counter of currently registered triggers — the script arming watches as it goes (Stage 02 has 12 push_trigger sites) — and it is readable live with no debugger. That is the first direct view of what the script is waiting for.

🟡 +12 is not a list head after all, or not only that: it reads 0x000A0009, which is not a pointer. The addi r31, r30, 12 in the push made "list head" the obvious reading and the value does not support it. Recorded as unresolved rather than quietly kept.

🟡 Walking the trigger queue live — structure confirmed, contents not

Walked the container's linked list from +16 for 200 s of a Stage 02 mission:

[  0s] count=0 head=0xBC28E610
[ 80s] count=1 head=0xBC28E610
       node 0 @0xBC28E610: f0=0xBC63.. f4=0xBC40.. f8=0xBC25.. dbl=-0.000 f24=0xBC25..
[120s] count=2 head=0xBC28E610
       node 1 @0xBC28E630: f0=0xBC65.. f4=0        f8=0xBC25.. dbl=-0.000 f24=0xBC25..

✅ The structure holds: the count at +20 tracks the number of nodes, the nodes chain through their first word, and new entries appear as the mission runs (0 → 1 → 2, stable thereafter).

🔴 The record layout does not. I expected node+8 to hold small symbol indices — the pop's out-parameters made that the natural reading. Every field is a guest heap pointer (0xBC…). So the trigger record references objects, not table indices, and what those objects are is unidentified.

⚠️ A false resolution I introduced myself

The [120s] line first printed f4=0(ADN101) — because the raw value is 0 and my formatter mapped index 0 to symbol-table-2's first entry. ADN101 is not in that record; it is my own pretty-printer inventing a name for a null. A resolver must refuse to resolve values that were never indices, and this one had no such guard. Recorded because it is exactly the sort of plausible label that would survive into a conclusion.

🔴 Correction: sub_8226E3B8 is a CLEAR, not a push

The previous section called it the push, reached from built-in 100 via vt2. Its tail refutes that: it decrements a counter, calls an erase helper (sub_8226EAB8), and loops while [+20] != 0 (beq 0x8226E3E4). That is a drain-the-whole-queue routine.

So built-in 100 clears the trigger queue and then rebuilds the thread list via sub_82273BE8 — consistent with the built-in table's own description ("push the argument record ... then drain/rebuild"), and the "push" label was mine, not the disassembly's. xrefs gives it two callers: 0x82265DD4 (vt2, the script side) and 0x8226D420, an engine site — so the engine clears it too. What actually appends a node is still unidentified.

🔴 What appends a trigger node — NOT FOUND this iteration

Three approaches, none of which produced the appender:

• sub_8226E160, flagged earlier as "enqueue a pending trigger", takes a double plus several pointers, rejects arg == -1, and has exactly one caller (0x8226A044). It is a specific operation, not the general append.
• Writes to the count at +20 inside the container code (0x8226DF00–0x8226F200) are only four, and all four are part of a block initialisation — stw to 0, 8, 12, 16, 20, 24 in consecutive instructions, in sub_8226E7D8 and sub_8226E930. Those are constructors (callers 0x8226E560 and 0x822608A0, the latter inside ScriptMission's own constructor), not increments.
• So the increment that takes the count 0 → 1 → 2 — which is measured, live — does not appear as a plain stw rN, 20(rM) anywhere in the container's own code. It is either inlined into a caller, uses a different addressing form (stwx), or the node count is maintained somewhere I have not looked.

Honest state: the queue's structure, its live count and its node chaining are verified; what writes a node into it is not identified, and I do not have a candidate I believe. Guessing from the shape of nearby functions is what produced the "push" mislabel last iteration, so I am not repeating it.

The approach that would settle it costs more but is unambiguous: a gdb watchpoint on the count word during a live mission. The address is known at runtime (ScriptPhase + 272 + 20), the count demonstrably changes within ~2 minutes of flight, and the watchpoint reports the writing instruction directly instead of inferring it from static shape.

🟡 The watchpoint fired — the writer is JIT-compiled GUEST code, not host code

tools/re-capture/trigger_watch.sh + host_addr.py translate the guest VA into a host address and set a gdb watchpoint on it:

mission 0xBC7A2A20  phase 0xBE14DD80  va 0xBE14DEA4  off 0x11E14DEA4 -> host 0x1BE14DEA4
Hardware watchpoint 1: *(unsigned int*)0x1BE14DEA4
Thread 50 "Main XThread" hit it:  Old value = 0    New value = 16777216

✅ Two things confirmed. 16777216 is 0x01000000 — big-endian 1 read little-endian, so this is exactly the count going 0 → 1, independently confirming that [ScriptPhase+272+20] is the field. And the write happens on the guest's own Main XThread, not on an emulator worker.

🔴 But the writer cannot be named from the host stack. The faulting PC is 0xa0c65f23, with no symbol, and the instruction is mov 0x110(%rsi),%rbx — this is Xenia's JIT-compiled guest code. The backtrace above it is garbage (0x45e0000000, 0x100000000), because JIT frames are not host-unwindable.

So the host watchpoint answers when and which guest thread, but not which guest function — the thing I actually wanted. The method has a ceiling here, and it is worth recording rather than re-attempting the same way.

What would get past it: the JIT keeps the guest context in a register (%rsi here, given mov 0x110(%rsi),%rbx), so the guest PC is recoverable from the context block at the moment of the write. Reading the right offset out of $rsi would name the guest instruction. That needs Xenia's context layout — which is in the xenia-rs sources on this box — and is a separate, tractable piece of work rather than another blind run.