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

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

  1. 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.
  2. 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.
  3. ssbdump.py --calls over a menu set gives the list of built-ins a screen needs.