Menu script VM (Menu/*.ssb, stage and event scripts)
The container (header, function table with
base-40 names, string pool) is documented on the
Modding Wiki’s SSB page and in Esper-RE
(ssb.h); the shared notes list the
header words. The instruction set below
is our own reading of the interpreter
(0x1402aaa30, 32-entry jump table at
0x1402ab3c0) and replaces the partial token list
in “Stage light script” (whose four tokens agree
with it).
converter/ssbdump.py <file.ssb>
disassembles a script (--calls
tallies the native calls; --strings
shows pool texts next to the pushes: never
commit that output); synthetic test
converter/tests/test_ssbdump.py.
Instruction word (little
endian, 4 bytes):
u8 opcode, u8 a, s16 b. Jump and
function distances are in words from the word
after the instruction. Values on the stack are
64-bit in this build (they hold pointers);
floats travel as their 32 bits.
Thread (the object the
interpreter runs): +0x00 state bits
(1 stopped on an error, 2 ended, 4 yielded; any
of them leaves the loop), +0x08
program counter, +0x10 value stack
pointer (grows down, 8 bytes per value),
+0x18 return stack pointer (grows
up), +0x20 frame pointer,
+0x28 result register,
+0x30 current script module,
+0x38 / +0x40 stack
size and base, +0x48 wait counter:
the run entry returns at once and counts it down
while it is above 0, so a yield with a wait
sleeps that many more ticks.
| Op | Name | What it does |
|---|---|---|
| 0x00 | nop | |
| 0x01 | native | calls built-in b with
a arguments: group = b >> 12
(table of group tables at 0x1402ddd00), index =
b & 0xFFF. The built-in gets a pointer to
the arguments, last pushed
first, 8 bytes apart; its return value
goes to the result register; the arguments are
dropped unless the built-in stopped the
thread |
| 0x02 | control | a = 0: yield, wait counter = b; a = 1: stop (error bit); a = 2: end the thread and reset its stacks; a = 3: not followed |
| 0x03 | enter function | pushes pc, frame pointer and module on the return stack; frame pointer = stack pointer; pc += b |
| 0x04 | import | the same through record b of
the module’s import list (a function of another
loaded script; resolver 0x1402aa960); a missing
target is skipped |
| 0x05 | return | pops module, frame pointer, pc; with a ≠ 0
pops one value into the result register; then
drops b values (the caller’s
arguments) |
| 0x06 | locals | reserves b values on the
stack |
| 0x07 | jump | a = 0: always; a = 1: pops, jumps when non-zero; a = 2: pops, jumps when zero; a = 3: pops, and when zero jumps and yields (the “repeat next tick until true” loop every wait in the menus uses) |
| 0x08 | case | compares the stack top with a
(0–255) without popping: equal → pops it and
goes on; else jumps b |
| 0x09 | load | pushes frame slot b (arguments
are slots 0 and up, locals −1 and down) |
| 0x0A | store | pops into frame slot b (a = 0),
adds the popped value to it (a = 1) or subtracts
it (a = 2) |
| 0x0B, 0x0C | (none) | stop with the error bit, like any opcode above 0x1F |
| 0x0D | drop | removes b values |
| 0x0E | push s16 | pushes b, sign-extended |
| 0x0F | push s32 | pushes the next word, sign-extended (two words long) |
| 0x10 | push result | pushes the result register |
| 0x11 | push string | pushes the address of the string at pool
offset b |
| 0x12 / 0x14 | add / mul | pops two, pushes one |
| 0x13 / 0x15 / 0x16 | sub / div / mod | a = 0: (earlier pushed) op (top); a ≠ 0: the other way round; signed 64-bit |
| 0x17 | compare | b = 1 ≠, 2 >, 3 <, 4 ≥, 5 ≤, 6 “all bits of one in the other”, anything else =; a swaps the operands as in sub; pushes 1 or 0 |
| 0x18 / 0x19 / 0x1A | and / or / xor | bitwise |
| 0x1B / 0x1C / 0x1D | not / negate / logical not | on the stack top |
| 0x1E | shift | b = 1 arithmetic right, 2 logical right, else left; a swaps |
| 0x1F | push code address | pushes pc + (the word’s upper 24 bits, signed) words: the address of a static data block or a function inside the script |
Static data. Scripts keep
state and tables in data words between functions
(battlestart has 975 of them: a
30-entry table and fixed-size text buffers).
They are reached with 0x1F and the built-ins
0x0010(block, index) = read and 0x0011(block,
index, value) = write (M: read
from how every script uses them; the handlers
0x1402abdf0 / 0x1402abe30 work on the current
module).
Built-in groups (table 0x1402ddd00, one pointer per group): 0 → 0x140420780 (VM helpers), 1 → 0x1403fafe0 (sound, pad), 2 → 0x1403eede0 (stage light calls at 0x2000…, the menu engine from 0x2040), 3 → 0x1403ef390, 4 → 0x1403f0090 (battle and game state), 5 → 0x1403f1d50 (battle HUD), 6 → 0x1403eff50, 7 → 0x1403f21d0, 8 → 0x1403f2450 (result banners), 9 → 0x1403dd3e0, 10 → 0x1403ddde0 (online), 11 → 0x1403d44d0.
Menu engine (group 2,
context object at [0x140533c58]): a
retained list of items, records
of 0x103C bytes from context + 0x40
(+0x00 x, +0x02 y,
+0x04 width, +0x06
height as int16, +0x08 type,
+0x1C a style word; per-type
functions {create, …, draw} from the table at
0x1402dcaf0), a “current item” index at context
+ 0x10402, a focus item at
- 0x10410, the text mode at + 0x1063C, and
32-bit menu variables the script reads and
writes by index. A screen is a set of script
functions found by name:
initmenu/quitmenu, and per scene a taska<name>…, a per-tick functionm<name>and a draw functiond<name>; custom draw callbacks have names startingdraw_.
Built-ins the two match-flow scripts use, as far as read (M unless marked; arguments in the order they are written, i.e. last pushed first):
| Id | Meaning |
|---|---|
| 0x2040(id) | go to menu id (history push);
id 1 = no menu, which closes the menu system so
the waiting game code sees it finish
(corrected by the menus run: see “Menu
engine”) |
| 0x2042(name, flag) / 0x2046(name) | start / switch to the scene with that name |
| 0x2044(name), 0x2076(i, text) | set the screen’s draw callback; 0x2076 =
0x2069, set entry pointer i of the
current item (unbounded: i = 0x202
is the item’s row-draw callback, below)
(menus r2) |
| 0x204E(i) | read menu argument i (set by the game code that opened the menu) |
| 0x2050(slot, name) / 0x2051(slot) | start loading a texture set / is it loaded |
| 0x2052(texture, n, x, y) | draw a loaded picture at (x, y) |
| 0x2055(kind) / 0x2056(kind) | start a screen fade / has it finished |
| 0x2057(x, y, format, …) | formatted rich text (8 arguments) |
| 0x2058(x, y, string) | rich text in the context’s mode (0x1402477e0) |
| 0x2059() | flush the sprite batch |
| 0x205A(mode) | text glyph mode |
| 0x205B(c0, c1, c2, c3) | the four text corner colours (H: writes 0x14054c9b0..bc) |
| 0x205D(x, y, w, h, argb) | filled rectangle |
| 0x205F(string, …) | text width (0x140247550) |
| 0x2061(id, type) | create item id of a type and
make it current (H for the
record reset) |
| 0x2064(w, h) / 0x2065(x, y) | current item’s size / position (H for the fields) |
| 0x2066(string), 0x2068(string), 0x207B(string, row) | item caption, add an entry, set a row’s text |
| 0x206A(id) | draw item id through its type’s
draw function (H) |
| 0x206B(id) | focus item (−1 none) |
| 0x206D(id, field), 0x2077(id, field) | read an item field |
| 0x2074(row) | select a row of the current item |
| 0x207D(v) | current item’s style word |
| 0x2098(kind, a, b) | 14 small state setters (kind 0 stores a word at context + 0x10400; others reach the fade / camera object) |
| 0x2099(i) / 0x209A(i, v) | menu variable read / write |
| 0x209F(set, sprite, x, y, argb) | draw a sprite of a loaded set |
| 0x20A2(which, v) | text state (H): 0 line step, 1 glyph spacing, 2 sx, 3 sy, 4 line start x (rect x + v), 5 read the first corner colour, 6 wrap width |
| 0x20A3(…) | blend / render state for the following quads |
| 0x20A8(i) | a system string by index (button labels) |
| 0x20AE(menu, i) / 0x20AF(menu, i, v) | read / write one of the four saved words of a menu’s table record (kept for the life of the process) (menus run) |
| 0x1010(track) / 0x1011() | play a music track / stop the music (“Music”); menu sound cues are played by 0x102B(cue) (corrected by the menus run) |
| 0x1025(pad) | buttons newly pressed |
| 0x41C4() | the battle result code (0x1404bbec8) |
| 0x41CC() | “everything loaded and every player ready” (0x140129fb0, the phase 2 test) |
| 0x41CF() | battle set-up (reaches 0x140128fc0) |
| 0x41D5(p) / 0x41D6(p) | sums over the KO tally 0x1404bc970 (knockouts made / taken) |
| 0x41D9(p), 0x41CE(v), 0x41DB() | per-player word at 0x1404bc8a8; write 0x1404bc8a4; the match mode 0x1404bc5dc |
| 0x4238(), 0x422F(p), 0x42A5(p) | local player index; player name; “slot is empty” |
| 0x801E … 0x803D | result banners, next section |
Confidence. Instruction set H (every handler read; the disassembler’s output of the two scripts is consistent: balanced stacks, jumps landing on instruction starts, and the four stage-light tokens match). Thread layout H. Built-in meanings M, a few L where only the argument shape was seen. Import calls (0x04) and control a = 3: L.
Not decoded: the import list layout after load; the loader (0x1402aa7f8 area) and how a module’s header words are rebased; most of the ~450 built-ins outside the lists here; the item types’ draw functions (table 0x1402dcaf0); the fade object.
Implementation notes for the rebuild
- We do not need to run the game’s scripts for the match flow: the two screens below are small and fixed, so rebuild them natively in GDScript from the decoded layout.
- If the full menu system is rebuilt later (menus topic), a script runner is ~200 lines of GDScript from the table above (one frame per run, the yield-on-false jump as the tick boundary) plus the built-ins each screen needs; the converter can ship the code words but not the string pool (game text): strings must come from the user’s files at run time.
ssbdump.py --callsover a menu set gives the list of built-ins a screen needs.