Menu engine, menu table and screen graph (Menu/.ssb, Menu/.alr + executable)

How the menu screens run on top of the script VM (“Menu script VM”): which script is which menu, how screens follow each other, what the items are, how a screen’s art is loaded and drawn, and which built-ins a screen needs. Addresses are for Store build 1.3.25854.2. Read in the executable and in the user’s own _en scripts with ssbdump.py; M unless marked. No script text is reproduced here: screens are named by their file name, strings by their role.

This section corrects three statements of the hudtext run (fixed in place above): 0x2040 is “go to menu id”, 0x1010 / 0x1011 are music play / stop, 0x20AE / 0x20AF are per-menu saved words.

Files

87 records × 24 bytes; the record index is the menu id used by every “go to menu” built-in.

Offset Type Field
+0x00 pointer script base name (file name without language suffix)
+0x08 s16 × 4 saved words: 0x20AE(menu, i) reads, 0x20AF(menu, i, v) writes; they survive menu changes (used as “came back from sub-screen” markers and remembered rows)
+0x10 pointer loaded script module (0 = not loaded)

Ids (file base names): 1 = no menu (closing), 2 menu1, 3 command, 4 option, 5 vsmode, 6 shop, 7 playdatasel, 8 mainmenu, 9 bgmtest, 10 vsmenu, 11–26 mb01–mb16, 27 skillbuy, 28 skillsell, 29 junkbuy, 30 arsenalbuy, 31 arsenalsell, 32 muoutput, 33 mapintro, 34 chapter, 35 and 42 livelogon, 36 livemain, 37 livequick, 38 livesearch, 39 livecreategame, 40 livetrade, 41 liveranking, 43 livesession, 44 livelobby, 45 laboratory, 46 livecharasel, 47 livestagesel, 48 liverulesel, 49 pausemenu, 51 livestart, 52 liveend, 53 liveerror, 54 livelobbyres, 56 ending, 57 slinkstart, 58 slinkend, 59 slinkmenu, 60 slinksearch, 61 slinkcreate, 62 slinkname, 63 labostock, 64 arsenaledit, 65 talkselect, 66 battleend, 67 livearsel, 68 liveoption, 70 vslobby, 71 townstart, 72 battlestart, 73 missionselect, 74 livedbtl, 75 livedbtlres, 76 movietest, 77 compe, 78 compe_res, 79 E3MENU, 80 title, 81 liveaware, 82 livetrade_h, 83 livetrade_c, 84 livegterr, 85 liveinvite, 86 livejoinssn (H, read from the table; ids 50, 55, 69 are empty).

Context object ([0x140533c58], 0x10a90 bytes)

Offset Field
+0x40 16 item records × 0x103C
+0x10400 pad mask word: bit 0 = pad 1 may drive the menu, bit 1 = pad 2
+0x10402 current item (target of the “current item” built-ins)
+0x10408 item being drawn
+0x10410 focus item (the one that gets input; −1 none)
+0x10414 / +0x10418 event code / event parameter of this tick
+0x1041c four ints (0x2048 read, 0x204A write)
+0x10530 texture set slots, 64 × 0x20: +0 name, +0x10 load id, +0x18 handle table
+0x105b0 name save stack, 8 deep (index at +0x105f0)
+0x105f4 current menu id (0x20B0 reads)
+0x105f6 seven words (0x2080 write / 0x2081 read), saved with the history entry
+0x10608 current menu table record
+0x10610 / +0x1061e tick function name / draw function name
+0x1062c pending task name
+0x1063c text mode (0x205A)
+0x10a40 the script thread

Other globals: state 0x140533744 (1 loading, 2 running, 3 closed); menu arguments 0x140533c10 (0x204D(i, v) write / 0x204E(i) read; native code passes values to a screen here, for example the result kind to battleend); history 0x140533b00 (16 entries × 16 bytes: menu id + the seven words; index 0x140533c50); menu variables (0x209A(i, v) write / 0x2099(i) read), which survive between scenes of one screen.

Open, go to, back

Per-frame tick (0x140248230)

  1. Clear the event (code 0, parameter −1).
  2. State 1: when the script has loaded, start InitMenu and go to state 2.
  3. Run the focus item’s type input function (it may set the event).
  4. Run the screen’s tick function by name (if set).
  5. Start the pending task (if a name is set) as the thread’s function; run the thread with a budget of 0x2000 instructions.
  6. Run each of the 16 items’ type tick functions.

Drawing is separate: the screen’s draw function (by name) runs every frame and draws items with 0x206A(item) and its own sprites and text.

Scenes. 0x204C(name) sets tick = “m” + name and draw = “d” + name. The usual tick function is one line: 0x2046(prefix + name), which starts the task named prefix + name + suffix when an event came in. So a screen is a set of scenes, and each scene is: a draw function, a tick function, and one task function per event it handles.

Event code Suffix Raised by
2 / 3 / 4 _OK / _YE / _NO message box closed: confirm / yes / no
5 / 6 _TA / _TB A / B (B and Back raise 6 on lists)
7 _BL
8 / 9 _TX / _TY X / Y
10 _WH right shoulder
11 / 12 _TL / _TR
13 / 14 _ST / _BA Start / Back
15 / 16 _LT / _RT triggers
17–20 _U / _D / _L / _R directions (lists raise 19 / 20)
100–611 _S<n> (n = code − 100) list row chosen (row index, or the row’s own value)

(table 0x1402f6700; codes ≤ 0 start nothing.) 0x2049(code, param) raises an event from script; 0x2047() / 0x204B() read code / parameter. 0x2042(name, n) sets the pending task directly (name, or name + number); 0x2043(name) / 0x2044(name) set tick / draw alone (0 clears); 0x208D–0x2090 push / pop names on the save stack (sub-scenes such as a message box over a list); 0x2045() resets; 0x2060() destroys all items.

Items

16 retained records; a script creates them in its draw or init code and destroys them when the scene changes.

Offset Type Field
+0x00 s16 × 4 x, y, width, height
+0x08 s16 type
+0x0A s16 state word (0x207E)
+0x10 s16 (0x2073)
+0x12 s16 selected row (0x2074 set; 0x20B5(item, row))
+0x16 s16 entry count
+0x18 s16 visible rows (0x2072)
+0x1A s16 top row (0x2067)
+0x1C s16 style bits (0x207D)
+0x24 pointer × n entry text pointers; the same area read as s32 from index 0x100 on holds per-row values
+0x1024 pointer caption (0x2066)
+0x102C pointer user pointer (0x206E)
+0x1034 pointer row-draw callback: a script function called per visible row with (x, y, row, entry); the scripts set it as entry index 0x202 through 0x2069 / 0x2076 (0x140207e40 has no index bound) (menus r2)

Generic field access: 0x206D(field) / 0x2077(item, field) read, 0x2071(field, v) / 0x2078(item, field, v) write; field < 16 = s16 at 2 · field, field ≥ 16 = s32 at +0x24 + 4 · (field − 16). Others: 0x2061(id, type) create, 0x2070(id) destroy, 0x2062 / 0x2063 set / get current item, 0x2068(text) add entry, 0x207B(row, text) set a row, 0x2069 / 0x2076(i, text), 0x206F / 0x2079(item, i) read an entry pointer, 0x2075(dst, src) copy the selected row, 0x206B / 0x206C set / get focus, 0x206A(id) draw.

Types (table 0x1402dcaf0, 24 slots; each type = {create, tick, draw, input} functions). Use counts are over the non-story _en scripts.

Type Uses What it is Functions
1 101 list / menu: framed window, rows, cursor draw 0x14024a780, input 0x14024b000
2 84 text box: framed window with its entries as lines; height = 24 · lines + 2 when the style is not negative draw 0x140249bc0
3 77 caption / help bar (rectangle + one text) draw 0x140249420
5 394 message box: opens the shared dialog 0x140169d60 (position, a style letter from table 0x1402f6bc0, caption), then raises event 2 / 3 / 4 with parameter = item id input 0x140249590
6 a second dialog kind input 0x140249710
8 skill detail panel, 162×56, drawn by 0x14016f2c0 (skill id = the item’s selected row, style, x, y, 8 label entries) draw 0x14024a0a0
9 the skill card (uifix 11-14 correction; was “plain coloured panel”): card routine 0x140168410 with skill id = the item’s selected row, see “Arsenal editor, skill lists and the card panel” create 0x140249d70, draw 0x140249df0
21 99 value row (label + value, left / right changes) 0x140249250 / 0x1402493a0 / 0x140249270
12, 14 skill stock lists (shop / laboratory), (uifix 11-14) 12: 0x140249e40 / draw 0x14024a050 / input 0x140249fa0; 14: 0x14024a0d0 / 0x14024a3b0 / 0x14024a100
16, 17 arsenal name header and the arsenal editor grid (uifix 11-14) 16: 0x140248ea0 / 0x140249050 / 0x140248ef0; 17: 0x140248b30 / draw 0x140248e10 / input 0x140248b50
7, 10, 13, 15, 18–23 few not read (L: text entry, gauges, number pickers by their use) see the type table

List input (type 1, 0x14024b000), for the pads allowed by the mask:

Frame drawing (M / L): windows are drawn by 0x14016cb40(window object [0x1404c0140], x, y, w, h, colour A, colour B, −1, 0): a vertical two-colour fill plus border pieces from the shared window set (WusMn), through helpers 0x14016cf30, 0x14016cd00 and 0x14016b350. Colours read: list fill 0xff38574d → 0xff001e1a, list text 0xff5cac95; text box fill 0xff32524e → 0xff123e35, text 0xff73e1cf. The list draw can hand each row to a script function for custom drawing (0x140245830). The border sprite numbers and corner sizes were not read.

Texture sets, sprites, fader, labels

Group 0 and 1 built-ins used by menus

Id Meaning
0x0000–0x0004, 0x0007 nothing (debug prints left in the scripts)
0x0005(n) random 0..n−1
0x0006(name) name hash
0x0008(name, x) / 0x0009() / 0x000A() request another script module / loaded? / unload
0x000E / 0x000F, 0x0012 / 0x0013 byte and s16 peek / poke on a pointer
0x0010 / 0x0011 static word read / write
0x1010(track) / 0x1011() play music track / stop music
0x1013(v) / 0x1014(frames, v) music volume (0x1000 = full) / fade to a volume
0x1016–0x1022, 0x1023 sound-test lists (only bgmtest) / stop and reset
0x1024 / 0x1025 / 0x1026 (pad) buttons held / newly pressed / auto-repeat
0x1029(a, skip) a < 0 resets; else the first of the four raw pads (other than skip) that newly pressed A or Start, or −1: the “player 2 press a button” poll
0x102A string length
0x102B(cue) play a system sound cue
0x102D, 0x1034, 0x1035 format, UTF-8 copy / truncate, clear a buffer

Music tracks by screen: playdatasel, mainmenu 31; option 33; vsmode, vsmenu 34; livemain 35; battleend 37 / 38; laboratory 29; shop 60.

Data queries (group 2, 0x2095–0x2097)

Call Kinds
0x2095(kind + 0x100 · player, index, sub) (0x14024c220) 31 arsenal count; 33 skill id sub of arsenal index; 34 arsenal name; 35 arsenal record pointer (0x64 bytes: name +4, 30 skill ids s16 from +0x14, school word +0x50); 36 / 41 a per-arsenal byte read / write; 38 skill name; 39, 40, 42 skill record words (+0xE, +0x12, +0x28; records 0x90 bytes at [0x1404bdc50])
0x2096(kind, i) (0x14024c410) (corrected by the menus run 11-12: this is the character table, not the stages) 40 count; 41 / 42 the run-time character entry’s name / display name (entries 0xA0 bytes, read from 0x1404c01e8 = table 0x1404c01e0 + 8, so +0 / +8 here are the entry’s second and third strings); 43 s32 at +0x70 here = entry +0x78 = the colour variant count (charaset +0x3A; the versus screen opens its colour pick when ≥ 2); 44 unlocked (bitset 0x1404616a4, < 56); 46 unlock
0x2097(kind, i) (0x14024c500) (corrected 11-12: the stage table, 0x28-byte entries at 0x140509ba0, count 0x14050a5d0, from stageset) 50 count; 51 / 52 / 53 full / short / internal name (+0 / +8 / +0x10 pointers); 54 stage number (+0x18); 55 variant count (+0x1C); 56 selectable flag (+0x20); 57 unlocked (bit 27 + i); 59 unlock. The split-screen stage list walks a 17-entry table of stage indices in the script and lists the rows with 56 and 57 set
0x507A(player, arsenal, flags) (0x14015b9e0) arsenal usable test; flag bits 32, 64, 128, 256, 16384 select which rule to test (too few skills, school limits …; bit meanings L)

Split-screen versus: settings and start (H for the path)

Settings block, written by 0x201A(kind, i, v) and read by 0x201B(kind, i) (0x1401d0630 / 0x1401d06d0):

Kind Field Stored at
1 character of player i s32 0x1405b1848 + 8 · i
2 arsenal slot of player i s16 0x1405b184c + 8 · i
3 stage s16 0x1405b1858
4 return menu id s16 0x1405b185c
6 game rule (mode row) s16 0x1405b185a
8 extra word used by the single-battle start s16 0x1405b1860

0x201C(i, v) runs entry i of table 0x1403ed940 (16-byte stride). Entry 4 = split-screen battle setup 0x1401d0750: builds two player records (0x48 bytes: present, index, character …); for each player loads the chosen arsenal (the kind-35 query above) and sets it as the battle deck (0x14014f830), and takes the school factor from the arsenal’s school word (1..3 → a float of the common parameter block, else 1.0) into 0x1404bc958[i]; then calls the match setup 0x140128990 with game mode 6, the records, the return menu and the stage, sets match mode 0x1404bc5dc = the game rule, 0x1404bca04 = 4, 0x1404bc8b8 = 2. Rule 2 skips the per-player arsenal load. Entry 5 = single battle (game mode 2).

Screen order of the offline versus mode:

  1. title (logos, then “press start”) → playdatasel (profile) → mainmenu.
  2. mainmenu rows → story (71), options (4), online (51), versus (5); back → 7.
  3. vsmode (id 5): player 2 joins: 0x1029 polls the other pads for A / Start, then the second player’s profile is picked (memory-unit and profile built-ins 0x209D / 0x209E, 0x208A–0x208C). → 10; back → 8.
  4. vsmenu (id 10), one script with these scenes: top menu (start, shop → 6, arsenal laboratory → 45), rule list, stage list, character list for player 1 then 2, arsenal list for player 1 then 2 (with an arsenal contents view), an options scene and a final “lobby” confirmation scene. Menu variables: 0 rule, 1 stage, 2 / 3 characters, 4 / 5 arsenal slots, 6 “came from the confirmation scene” (a change returns there), 11 view toggle. On entry they are loaded from the settings block (0x201B). Each list writes its variable on A and goes to the next scene; B goes one scene back; back from the top → 5.
  5. On confirm: music fades (0x1014(15, 0)), the six settings are written (0x201A kinds 3, 6, 1, 1, 2, 2), the return menu is set to 70, 0x201C(4, 0) sets the battle up, the screen fades, waits until 0x41CC reports the battle loaded, fades out fast (0x2055 with step 0x55) and closes the menu system with 0x2040(1). The battle then opens battlestart (72).
  6. After the battle: battleend (66) → back; the battle flow opens the return menu 70 = vslobby, a stub that goes straight to 10, so the players land in vsmenu again with their settings kept.

Other game built-ins of these screens: 0x41CC battle loaded?; 0x41CE(id) set the return menu; 0x3173 a save byte + 1; 0x42A3(v) and 0x4359(v) set a mode word / a camera or background preset for the menu backdrop (L).

Pause menu (id 49)

Opened by the pause object (0x1401674b0 family, at 0x1401676c4) with menu arguments 0 and 2 set. One script with a scene per situation: offline battle, online battle, town, a “disconnect” variant, and a PC options scene. It draws by the pad mask (0x2098 kind 0 gives the pausing pad the menu), tests 0x4290 / 0x4291 (flag bits 2 and 4 of 0x14050d220: which rows to show), and its rows are: resume (0x2041), options (→ 68 liveoption, or the PC option rows through the 0xA0xx group), help (opens a web page through 0xA001: stub), quit (0x40D3: sets the end reason 5 and ends the battle), story-only rows (0x30E3). On open it sets label flags and the global flag bit 0x100000; closing clears them. (11-12 correction) Every exit goes through one helper: 0x40D3 (end reason 5, then 0x14012dca0), menu argument 1 = the exit code (128 resume; 129 the second row and 132 quit, both after a confirm), then 0x2041. The pause object sets argument 0 = its u16 +0x12 (the scene; 0 = the offline battle’s five rows) and argument 2 = its +0x54 (the pausing pad). The caller reads argument 1 after the close: the battle only ends for a quit. vsmenu’s init goes to the online screen (51) when flag 0x100000 is set, argument 0 ≠ 0 and its first saved value is 0, so the flag must be clear again when the pause is over.

Online and PC-port built-ins (to stub)

Rebuild implementation (menus) (11-12)

godot/scripts/menu/pd_menu.gd (engine), pd_font.gd (font, rich text), menu_flow.gd (the session around the battle), converter/menuexport.py (scripts, sets, font, character table). Decoded while building it (PC exe 1.3.25854.2):

media/ leftovers

Not read

Implementation notes for the rebuild

  1. Interpret the user’s scripts at run time rather than re-drawing each screen by hand: the layout numbers, row texts and flow all live in the scripts, so this is the only way to be 1:1 without copying game text. Needed: the VM (32 opcodes, already specified), this section’s engine (context, tick order, scenes and event suffixes, 16 items, history, saved words, menu variables), and a built-in table that returns 0 for unknown ids.
  2. Built-ins needed for the offline + our-netplay flow, in order: (a) flow: 0x2040–0x204F, 0x2080 / 0x2081, 0x208D–0x2090, 0x2098 kinds 0 / 5 / 7 / 8, 0x2099 / 0x209A, 0x20AE– 0x20B0; (b) items: 0x2060–0x207E, 0x20B5, types 1, 2, 3, 5, 21 first; (c) drawing: 0x2050–0x205F, 0x209F, the fader; (d) input and sound: 0x1024–0x1026, 0x1029, 0x102B, 0x1010 / 0x1011 / 0x1013 / 0x1014, formatting 0x102A / 0x102D; (e) data: 0x2095–0x2097, 0x507A, backed by our arsenal store, stage list and character list; (f) versus: 0x201A / 0x201B / 0x201C, 0x41CC, 0x41CE.
  3. First target: vsmenu alone (enter at id 10 with both players present), ending in our own match start in place of 0x201C(4): rule → match mode row, stage, two characters, two arsenals. Then battlestart / battleend, pausemenu (offline scene), vsmode, mainmenu, title.
  4. For netplay keep our own lobby transport but drive it from the game’s livelobby, livecharasel, livestagesel, liverulesel and livearsel screens later: stub the prelude built-ins as “signed in, no error”, and map the session settings (game type, rule, including heavy = rule 4) onto our session. Until those screens are read, the split-screen vsmenu flow can serve as the netplay set-up screen for the host.
  5. Stub: groups 9 and 10, web page calls, memory-unit and profile calls (answer “one profile, ready”), trade, ranking, the CPU battle livedbtl.
  6. Sprites: convert each Menu/<Set>.alr with the HUD converter (hudconv.py) at run time on the user’s machine; set numbers −1 / −2 map to WusMn<Lang> / BtMenu<Lang>.
  7. Windows: until the border sprites are read, draw the decoded two-colour fill with a plain 1-pixel border and list that as a placeholder.