docs: frontend state machine RE + 47 Ghidra labels

Document the complete frontend navigation state machine:
- Main navigation loop at 0x4E6440 (CWinApp::Run, 19KB)
- g_CurrentScreen (0x6B3504) drives screen dispatch
- 20 dialog constructors mapped to screen IDs
- Bitmap font system: 4 font sizes, glyph renderer, textbox API
- Display wrapper at 0x79D6D4 with 6 backend variants

47 new Ghidra labels applied (functions, globals, dialog ctors).
38 new address.rs constants: dialog ctors, font system, display globals.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

crates/openwa-types/src/address.rs

@@ -187,6 +187,36 @@ pub mod va {
     pub const CDIALOG_DO_MODAL_CUSTOM: u32 = 0x0040_FD60;
     /// Custom message pump (replaces MFC's RunModalLoop)
     pub const CDIALOG_CUSTOM_MSG_PUMP: u32 = 0x0040_FBE0;
+    /// Per-frame idle handler: cursor, mouse, paint dispatch
+    pub const FRONTEND_DIALOG_ON_IDLE: u32 = 0x0040_FF90;
+    /// Traverses control tree, paints dirty controls
+    pub const FRONTEND_DIALOG_PAINT_CONTROL_TREE: u32 = 0x0040_BF60;
+    /// Renders background image for frontend dialog
+    pub const FRONTEND_DIALOG_RENDER_BACKGROUND: u32 = 0x0040_4250;
+    /// Surface blit operation (calls surface->vtable[11])
+    pub const SURFACE_BLIT: u32 = 0x0040_3BF0;
+
+    // === Frontend dialog constructors (from main navigation loop) ===
+
+    pub const FRONTEND_DEATHMATCH_CTOR: u32 = 0x0044_0F40;
+    pub const FRONTEND_LOCAL_MP_CTOR: u32 = 0x0049_C420;
+    pub const FRONTEND_TRAINING_CTOR: u32 = 0x004E_0880;
+    pub const FRONTEND_MISSIONS_CTOR: u32 = 0x0049_9190;
+    pub const FRONTEND_POST_INIT_CTOR: u32 = 0x004C_91B0;
+    pub const FRONTEND_MAIN_MENU_CTOR: u32 = 0x0048_66C0;
+    pub const FRONTEND_SINGLE_PLAYER_CTOR: u32 = 0x004D_69F0;
+    pub const FRONTEND_CAMPAIGN_A_CTOR: u32 = 0x004A_2B70;
+    pub const FRONTEND_CAMPAIGN_B_CTOR: u32 = 0x004A_24D0;
+    pub const FRONTEND_ADV_SETTINGS_CTOR: u32 = 0x0042_79E0;
+    pub const FRONTEND_INTRO_MOVIE_CTOR: u32 = 0x0047_0870;
+    pub const FRONTEND_NETWORK_HOST_CTOR: u32 = 0x004A_DCA0;
+    pub const FRONTEND_NETWORK_ONLINE_CTOR: u32 = 0x004A_CBC0;
+    pub const FRONTEND_NETWORK_PROVIDER_CTOR: u32 = 0x004A_7990;
+    pub const FRONTEND_NETWORK_SETTINGS_CTOR: u32 = 0x004C_23C0;
+    pub const FRONTEND_LAN_CTOR: u32 = 0x0048_0A80;
+    pub const FRONTEND_WORMNET_CTOR: u32 = 0x0047_2400;
+    pub const FRONTEND_LOBBY_HOST_CTOR: u32 = 0x004B_0160;
+    pub const FRONTEND_LOBBY_GAME_START_CTOR: u32 = 0x004B_DBE0;
 
     // === Lobby / network ===
 
@@ -207,10 +237,29 @@ pub mod va {
     pub const WA_MALLOC_MEMSET: u32 = 0x0053_E910;
     pub const WA_FREE: u32 = 0x005D_0D2B;
 
+    // === Bitmap font system ===
+
+    /// Loads all four font sizes from BMP files
+    pub const FONT_LOAD_FONTS: u32 = 0x0041_4680;
+    /// Core glyph renderer: iterates chars, blits from sprite sheet
+    pub const FONT_RENDER_GLYPHS: u32 = 0x0041_43D0;
+    /// Higher-level text draw: measures string, creates surface, renders
+    pub const FONT_DRAW_TEXT: u32 = 0x0042_7830;
+    /// DDDisplay::DrawTextOnBitmap — thiscall(font_id, bitmap, hAlign, vAlign, msg, a7, a8)
+    pub const DDDISPLAY_DRAW_TEXT_ON_BITMAP: u32 = 0x0052_36B0;
+    /// DDDisplay::ConstructTextbox — thiscall(dst, length, fontid)
+    pub const DDDISPLAY_CONSTRUCT_TEXTBOX: u32 = 0x004F_AF00;
+    /// SetTextboxText — stdcall(textbox, msg, textcolor, color1, color2, a6, a7, opacity)
+    pub const SET_TEXTBOX_TEXT: u32 = 0x004F_B070;
+    /// DrawTextboxLocal — draws textbox at screen position
+    pub const DRAW_TEXTBOX_LOCAL: u32 = 0x0054_2200;
+
     // === Global variables (in .data) ===
 
     /// Current screen ID driving the main navigation loop dispatch
     pub const G_CURRENT_SCREEN: u32 = 0x006B_3504;
+    /// Character width table (256 bytes)
+    pub const G_CHAR_WIDTH_TABLE: u32 = 0x006B_2DD9;
     /// Main frontend frame window (CWnd*)
     pub const G_FRONTEND_FRAME: u32 = 0x006B_3908;
     /// Main frontend HWND
@@ -219,8 +268,14 @@ pub mod va {
     pub const G_SKIP_TO_MAIN_MENU: u32 = 0x007A_083D;
     /// Auto-network mode flag
     pub const G_AUTO_NETWORK_FLAG: u32 = 0x007A_083F;
+    /// DDDisplayWrapper pointer (valid during entire frontend lifetime)
+    pub const G_DD_DISPLAY_WRAPPER: u32 = 0x0079_D6D4;
+    /// Font array — 4 fonts, each 0x241C bytes
+    pub const G_FONT_ARRAY: u32 = 0x007A_0F58;
     /// Main menu active flag (0xFF during screen 18)
     pub const G_MAIN_MENU_ACTIVE: u32 = 0x007C_0A20;
+    /// MFC CWinApp singleton
+    pub const G_CWINAPP: u32 = 0x007C_03D0;
     /// Network mode (0=LAN, nonzero=WormNET)
     pub const G_NETWORK_MODE: u32 = 0x007C_0D40;
     /// Network sub-type selector

docs/re-notes/frontend-screens.md

@@ -1,86 +1,191 @@
-# Frontend Screen System
+# Frontend Navigation State Machine
 
-## Architecture
+## Overview
+
+The WA frontend uses MFC `CDialog` modal dialogs driven by a main navigation loop.
+The loop is at `0x4E6440` (`Frontend__MainNavigationLoop`), which is the `CWinApp::Run()`
+virtual method override — a 19KB function that handles initialization and screen dispatch.
 
-The frontend uses **MFC CDialog modal dialogs**, not the CTask class hierarchy.
-Screen transitions work through a centralized dispatcher:
+## Architecture
 
 ```
-FrontendFrame (global at 0x6B3908, constructed at 0x4ECCA0)
-  └── CDialog modal loop (CDialog__DoModal_Custom at 0x40FD60)
-       ├── Button handler calls FrontendChangeScreen(screen_id)
-       ├── FrontendChangeScreen calls CDialog::EndDialog(screen_id)
-       ├── DoModal returns screen_id to caller
-       └── Caller decides next dialog based on return value
+g_CurrentScreen (0x6B3504)
+        │
+        ▼
+┌──────────────────────┐
+│ Main Navigation Loop │  (0x4E6440)
+│ do {                 │
+│   switch(screenId) { │
+│     case 10: ...     │──► Create dialog ──► DoModal() ──► result
+│     case 11: ...     │                                       │
+│     ...              │                                       │
+│   }                  │◄──── store result in g_CurrentScreen ─┘
+│ } while(true);       │
+│                      │
+│ case 15: EXIT        │──► cleanup, return
+└──────────────────────┘
 ```
 
+Each iteration:
+1. Reads `g_CurrentScreen` (0x6B3504)
+2. Dispatches to the matching case → allocates dialog → calls constructor → DoModal
+3. `FrontendChangeScreen(screen_id)` inside the dialog calls `EndDialog(screen_id)`
+4. DoModal returns the result code → stored back into `g_CurrentScreen`
+5. Previous dialog destroyed via `Frontend__PostScreenCleanup` (0x4EB450)
+6. Loop continues
+
 ## FrontendChangeScreen (0x447A20)
 
+`stdcall(screen_id)` with `ESI` = dialog this pointer (MSVC `__usercall`).
+
 Two modes based on `g_FrontendFrame` (0x6B3908):
 
 - **Normal** (g_FrontendFrame != 0): Disable window → palette transition
-  (0x422180) → call vtable method at +0x15C twice → re-enable window →
+  (0x422180) → call vtable[0x15C] twice (args 1, 2) → re-enable window →
   CDialog::EndDialog(screen_id)
-- **Init** (g_FrontendFrame == 0): Store screen_id at ESI+0x44, clear flag bit
+- **Init** (g_FrontendFrame == 0): Store screen_id at dialog+0x44, clear flag
+  bit 0x10 at dialog+0x3C
+
+## Screen Dispatch Table
+
+### Valid main-loop screens (10–30)
+
+| ID | Hex | Name | Constructor | Notes |
+|----|-----|------|-------------|-------|
+| 10 | 0x0A | Deathmatch | 0x440F40 | `PreTransitionCleanup` before |
+| 11 | 0x0B | LocalMultiplayer | 0x49C420 | `PreTransitionCleanup` before |
+| 12 | 0x0C | Training | 0x4E0880 | Palette load before |
+| 14 | 0x0E | Missions | 0x499190 | Palette load before |
+| 15 | 0x0F | **Exit** | — | Cleanup + return from CWinApp::Run |
+| 16 | 0x10 | PostInitMenu | 0x4C91B0 | Calls 0x4E4BD0 after |
+| 17 | 0x11 | MainMenuRedirect | — | Sets g_CurrentScreen = 18 |
+| 18 | 0x12 | **MainMenu** | 0x4866C0 | Primary menu dialog |
+| 21 | 0x15 | SinglePlayer | 0x4D69F0 | Palette load before |
+| 22 | 0x16 | CampaignA | 0x4A2B70 | `PreTransitionCleanup` after |
+| 23 | 0x17 | CampaignB | 0x4A24D0 | `PreTransitionCleanup` after |
+| 24 | 0x18 | AdvancedSettings | 0x4279E0 | Calls 0x4E4BD0 after |
+| 25 | 0x19 | IntroMovie | 0x470870 | Hardcodes next=18, sets g_SkipToMainMenu |
+| 27 | 0x1B | NetworkHostSetup | 0x4ADCA0 | `PreTransitionCleanup` after |
+| 28 | 0x1C | NetworkOnlineSetup | 0x4ACBC0 | `PreTransitionCleanup` after |
+| 29 | 0x1D | NetworkDialogA | 0x4BC970 | `PreTransitionCleanup` after |
+| 30 | 0x1E | NetworkDialogB | 0x4BBC00 | `PreTransitionCleanup` after |
+
+### Network/lobby screens (1700–1707)
 
-## Screen IDs
+| ID | Hex | Name | Constructor | Notes |
+|----|-----|------|-------------|-------|
+| 1700 | 0x6A4 | NetworkProviderSelect | 0x4A7990 | Special post-DoModal logic |
+| 1701 | 0x6A5 | NetworkSettings | 0x4C23C0 | |
+| 1702 | 0x6A6 | LAN | 0x480A80 | |
+| 1703 | 0x6A7 | WormNet | 0x472400 | |
+| 1704 | 0x6A8 | LobbyHost | 0x4B0160 | Fall-through from setup |
+| 1705 | 0x6A9 | LobbyHostContinued | (fall-through) | |
+| 1706 | 0x6AA | LobbyClient | (fall-through) | |
+| 1707 | 0x6AB | LobbyGameStart | 0x4BDBE0 | |
 
-| ID | Hex | Name | Context |
+### Dialog result codes (NOT dispatched by main loop)
+
+These are returned by `EndDialog` from sub-dialogs (button handlers, options screens).
+If they reach the main loop, they hit the default case → `g_CurrentScreen = 0x0F` → exit.
+By that point, the game has already launched or the action has been taken.
+
+| ID | Hex | Name | Meaning |
 |----|-----|------|---------|
-| 0 | 0x00 | Cancel | Return to previous / close dialog |
-| 10 | 0x0A | MainMenu | Main menu screen |
-| 11 | 0x0B | LocalMultiplayer | Local multiplayer setup |
-| 15 | 0x0F | Minimized | Window minimized (IsIconic check) |
-| 16 | 0x10 | InitialLoad | Initial game loading screen |
-| 21 | 0x15 | SinglePlayer | Single player / Deathmatch |
-| 26 | 0x1A | NetworkSubScreen | Network options sub-screen |
-| 35 | 0x23 | StartGameA | Start game (path A) |
-| 36 | 0x24 | StartGameB | Start game (path B) |
-| 37 | 0x25 | NetworkSetupA | Network setup (path A) |
-| 38 | 0x26 | NetworkSetupB | Network setup (path B) |
-| 39 | 0x27 | OptionsAccept | Options saved (writes current.thm) |
-| 1700 | 0x6A4 | NetworkSelection | Network provider selection |
-| 1702 | 0x6A6 | Lan | LAN game |
-| 1703 | 0x6A7 | WormNet | WormNET online lobby |
-| 1704 | 0x6A8 | LobbyHost | Hosting a game |
-| 1706 | 0x6AA | LobbyClient | Joining a game |
-| 1707 | 0x6AB | LobbyGameStart | Lobby → game start |
-
-Note: Some callers pass dynamic screen IDs. There may be additional IDs not
-discovered through static analysis.
+| 0 | 0x00 | Cancel | Return to previous / back |
+| 1 | 0x01 | Splash | Splash/intro trigger |
+| 2 | 0x02 | NetworkOptionA | Network option result |
+| 4 | 0x04 | SinglePlayerPrep | SP prep result |
+| 5 | 0x05 | SinglePlayerConfirm | SP confirm result |
+| 32 | 0x20 | SchemeEditorDone | Return from scheme/weapon editor |
+| 35 | 0x23 | StartGameOffline | Start game, no network |
+| 36 | 0x24 | StartGameOnline | Start game, network available |
+| 37 | 0x25 | MultiplayerLocal | Multiplayer, no network |
+| 38 | 0x26 | MultiplayerOnline | Multiplayer, network available |
+| 39 | 0x27 | OptionsAccepted | Return after applying options + saving theme |
+| 50 | 0x32 | InGameA | In-game state |
+| 52 | 0x34 | InGameB | In-game state |
+| 58 | 0x3A | InGameC | In-game state |
 
-## Key Globals
+#### Offline/Online pairs
 
-| Address | Name | Type | Description |
-|---------|------|------|-------------|
-| 0x6B3908 | g_FrontendFrame | CWnd* | Main application frame window |
-| 0x6B390C | g_FrontendHwnd | HWND | Main window handle |
-| 0x7C0D40 | g_NetworkMode | int | 0=LAN, nonzero=WormNET |
-| 0x7C0D68 | g_NetworkSubtype | int | Network sub-type selector |
+The "Start Game" and "Multiplayer" paths each check a network availability flag
+and branch to an offline/online result code:
+
+- **Start Game** (`this+0x244` flag): 35 (offline) / 36 (online)
+- **Multiplayer** (`this+0x140` flag): 37 (offline) / 38 (online)
+
+Both paths use 0 (Cancel) as the "back to main menu" value.
 
 ## Key Functions
 
 | Address | Name | Purpose |
 |---------|------|---------|
-| 0x40FD60 | CDialog__DoModal_Custom | Custom DoModal returning screen ID |
+| 0x4E6440 | Frontend__MainNavigationLoop | CWinApp::Run override — main dispatch loop |
+| 0x447A20 | FrontendChangeScreen | Ends current dialog via EndDialog(screen_id) |
+| 0x447960 | Frontend__DoModalWrapper | Palette transition + custom DoModal |
+| 0x40FD60 | CDialog__DoModal_Custom | Custom MFC DoModal |
+| 0x40FBE0 | CDialog__CustomMsgPump | Custom message pump (replaces RunModalLoop) |
+| 0x40FF90 | FrontendDialog__OnIdle | Per-frame idle: cursor, mouse, paint dispatch |
+| 0x40BF60 | FrontendDialog__PaintControlTree | Traverse control tree, paint dirty controls |
+| 0x4EB450 | Frontend__PostScreenCleanup | Destroys previous dialog |
+| 0x4E4AE0 | Frontend__PreTransitionCleanup | Cleanup before certain transitions |
 | 0x422180 | Frontend__PaletteAnimation | Palette transition effect |
-| 0x429830 | Frontend__OnInitialLoad | Initial game load handler |
-| 0x441D80 | Frontend__LaunchSinglePlayer | Single player launch |
-| 0x446BA0 | FrontendDialog__Constructor | Dialog constructor |
-| 0x447A20 | FrontendChangeScreen | Central screen transition dispatcher |
-| 0x447AA0 | Frontend__LoadTransitionPalette | Load transition palette |
+| 0x446BA0 | FrontendDialog__Constructor | Base frontend dialog constructor |
 | 0x44E850 | Frontend__OnMultiplayerButton | Multiplayer button handler |
 | 0x44EC10 | Frontend__OnNetworkButton | Network button handler |
-| 0x486A10 | Frontend__OnMinimize | Window minimize handler |
 | 0x48DAB0 | Frontend__OnOptionsAccept | Options accept handler |
-| 0x493CB0 | Lobby__DisplayMessage | Display lobby chat message |
-| 0x4AA990 | Lobby__SendGreentext | Send colored lobby text |
-| 0x4B7E20 | Lobby__PrintUsedVersion | Print version to lobby |
-| 0x4BAE40 | Lobby__OnDisconnect | Handle lobby disconnect |
-| 0x4BAEC0 | Lobby__OnGameEnd | Handle game end in lobby |
-| 0x4BD400 | Lobby__OnMessage | Handle lobby message |
-| 0x4CD9A0 | LobbyDialog__Constructor | Lobby dialog constructor |
-| 0x4D4920 | Network__IsAvailable | Check network availability |
-| 0x4E4AE0 | Frontend__PreTransitionCleanup | Pre-transition cleanup |
-| 0x4ECCA0 | FrontendFrame__Constructor | Frame window constructor |
 | 0x4F14A0 | Frontend__OnStartGameButton | Start game button handler |
+| 0x4D4920 | Network__IsAvailable | Check network availability |
+
+## Key Globals
+
+| Address | Name | Type | Description |
+|---------|------|------|-------------|
+| 0x6B3504 | g_CurrentScreen | u32 | Screen ID driving the main dispatch loop |
+| 0x6B3908 | g_FrontendFrame | CFrameWnd* | Main frame window |
+| 0x6B390C | g_FrontendHwnd | HWND | Main window handle |
+| 0x79D6D4 | g_DDDisplayWrapper | void* | Display backend wrapper (valid during entire frontend) |
+| 0x7A083D | g_SkipToMainMenu | u8 | Skip splash, go directly to main menu |
+| 0x7A083F | g_AutoNetworkFlag | u8 | Auto-network mode flag |
+| 0x7C0A20 | g_MainMenuActive | u8 | 0xFF during screen 18 |
+| 0x7C03D0 | g_CWinApp | CWinApp* | MFC application singleton |
+| 0x7C0D40 | g_NetworkMode | u32 | 0=LAN, nonzero=WormNET |
+| 0x7C0D68 | g_NetworkSubtype | u32 | Network sub-type selector |
+
+## Bitmap Font System
+
+WA uses a custom bitmap font renderer, NOT GDI, for all game/frontend text.
+
+### Font files
+- `Graphics\Font.bmp` + `Data\Gfx\FontExt\%s2.fex` (extended glyphs)
+- Four sizes: `SmlFont2.bmp` (12px), `StdFont2.bmp` (17px), `MedFont2.bmp` (25px), `BigFont2.bmp` (33px)
+
+### Key structures
+- Font array at `0x7A0F58`, each font is `0x241C` bytes
+- Glyph table: 256 entries at `font+0x14`, each `0x24` bytes
+- Character width table at `0x6B2DD9` (256 bytes)
+- Registry options: `LargerFonts` (font+0x20), `FrontendFontDynamicAntialiasing` (font+0x70)
+
+### Key functions
+
+| Address | Name | Description |
+|---------|------|-------------|
+| 0x414680 | Font__LoadFonts | Loads all four font sizes from BMP files |
+| 0x4143D0 | Font__RenderGlyphs | Core glyph renderer: iterates chars, blits from sprite sheet |
+| 0x427830 | Font__DrawText | Higher-level: measures string, creates surface, renders |
+| 0x5236B0 | DDDisplay__DrawTextOnBitmap | thiscall(font_id, bitmap, hAlign, vAlign, msg, a7, a8) |
+| 0x4FAF00 | DDDisplay__ConstructTextbox | thiscall(dst, length, fontid) |
+| 0x4FB070 | SetTextboxText | stdcall(textbox, msg, textcolor, color1, color2, a6, a7, opacity) |
+| 0x542200 | DrawTextboxLocal | Draws textbox at screen position |
+
+### Rendering pipeline
+1. Create surface via `g_DDDisplayWrapper->vtable[22]` (CreateSurface factory)
+2. `Font__RenderGlyphs` iterates characters, looks up glyph data in font table
+3. Each glyph is blitted from the font sprite sheet onto the surface
+4. Surface blitted to screen via `Surface__Blit` (0x403BF0 → surface->vtable[11])
+
+### Display backends
+The display wrapper at `0x79D6D4` (vtable `0x662EC8`, size 0x1C) delegates to one of 6 backends:
+DirectDraw legacy, DirectDraw classic, D3D9 basic, D3D9 shader, OpenGL CPU, OpenGL GPU.
+Concrete backend stored at `wrapper+0x18`. Initialized in the main navigation loop
+before any dialog is created.