havoc-remaster/docs/FUNCTIONS.md

# Havoc Function Tracker

Progress tracker for reverse-engineered functions in `HAVOC_NOCD.EXE`, kept in git so it's
diffable and gives an honest "how much of this binary do we actually understand" number for
the blog post. This is a curated list of functions worth naming/understanding, not a full
dump of all ~987 functions Ghidra's auto-analysis found.

**Status legend:**
- `unanalyzed` -- known to exist (an address we care about), not yet decompiled/read
- `analyzed` -- decompiled and read, behavior understood, still has a Ghidra default `FUN_*` name
- `named` -- renamed in the Ghidra project (`tools/ghidra_project/`) to reflect what it does
- `documented` -- named *and* has a writeup in one of the other `docs/*.md` files

Update this table whenever a function moves between these states. VA = virtual address
(runtime address with relocations applied; see `docs/HANDOFF.md` section 5 for FO->VA
formulas per section).

## Boot / init / main loop

| VA | Name | Status | Notes |
|---|---|---|---|
| `0x464657` | CRT entry point | documented | See `docs/HANDOFF.md` section 5 |
| `0x407C90` | WinMain | analyzed | Allocs game object, calls init (`0x434040`), then main loop (`0x43AC40`) |
| `0x434040` | main init | analyzed | Allocs ~30 subsystem objects, loads title/GAMIMAGE, palette fade, calls `0x418600` |
| `0x418600` | DirectDraw + archives + sound init | unanalyzed | GRAFIX/world files load during this |
| `0x43AC40` | `main_game_loop` (vtable[7]) | named | State machine, state byte at `[this+0x18]`. No frame limiter -> FPS-coupled. See `docs/METHODOLOGY.md` section 10 |
| `0x436170` | `per_frame_vtable8` | named | Calls `frame_tick_counter_while_playing` then conditionally two more vtable calls gated on state/flags |
| `0x4361d0` | `per_frame_vtable9_state_machine` | named | Sets the 60Hz tick baseline (`DAT_0047e56c`) on first call; handles state transitions 0x47/0x49/0xa1 |
| `0x43adc0` | `msg_pump` (vtable[17]) | named | Linked-list event queue drain, dispatches via `[this]+0x3c` |
| `0x40C8E0` | `busywait_frame_limiter_60hz` | named | ~60/sec via `timeGetTime`; used in palette-fade / state transitions, NOT the gameplay loop |
| `0x40CAE0` | `state_transition_with_limiter` | named | Palette-fade / state-transition context that calls the limiter |
| `0x418870` | `frame_tick_counter_while_playing` | named | Calls `dsound_stream_pump` then, if state==0x47, increments a counter at `this+0x158` |

## FPS-coupling investigation (docs/HANDOFF.md section 7.1)

| VA | Name | Status | Notes |
|---|---|---|---|
| `0x0047da88` (data) | game/window object ptr | analyzed | Same object as `this` in the main loop `0x43AC40` -- confirmed by reading its vtable at `0x4791A0` and matching slots 7/8/9/17 to the known main-loop callees. Assigned once in `FUN_00426560` (a window-init routine: `ShowWindow`/`UpdateWindow`/`SetWindowLongA`, offset `+0x943` = HWND) |
| offset `+0x92a` | **CORRECTED: common base "Window" class active/shown flag, not cockpit/HUD-specific** | analyzed | Scanned all instructions program-wide for this offset (`ScanForOffset.java`, since it's a struct offset not a fixed global address) -- found ~29 distinct functions across a huge address range (`0x415262` to `0x4624e0`) reading/writing it. This is a shared base-class member used by many menu/dialog/window objects throughout the UI system, not specific to the top-level game object or to cockpit/HUD mode. Retracts the earlier "possible cockpit/HUD-mode flag" guess |
| `0x426170` / `0x4264d0` / `0x426470` | base Window class `Init` / `Show` / `Hide` | analyzed | Found clustered together (same class impl). `0x426170`: constructor-like, zeroes a large field block, sets `+0x92a=0`. `0x4264d0` (**Show**): calls vtable[31] (`+0x7c`) then sets `+0x92a=1`. `0x426470` (**Hide**): sets `+0x92a=0`, calls `0x418a30`, conditional sub-object cleanup. This is the base class every menu/dialog screen likely inherits -- relevant to the keyboard-reassignment graphics bug investigation below |
| vtable slot `0x54` (21, `0x4188c0`) on the base vtable `0x4791A0` | base-class default stub, likely NOT a bug on its own | analyzed | Still just `MOV AX,1 / RET` on the *base* class. Given `+0x92a` is now known to be a common "active" flag checked by many classes, this being a no-op default for the plain base/top-level window is plausible and not necessarily wrong -- the real per-menu-screen override would live on each menu's own derived vtable, not this one. Not re-litigated as the FPS-coupling mechanism (still correctly ruled out for that), but also not confirmed as unrelated to the keyboard-menu bug -- would need to find the *keyboard-reassignment dialog's own object/vtable* specifically, not the top-level game object's |
| `0x418870` | `frame_tick_counter_while_playing` | named | Calls `dsound_stream_pump()` unconditionally, then if state==0x47 (playing) increments a counter at `this+0x158`. Not the physics update itself |
| `0x40a3f0` | `dsound_stream_pump` -- **dead end for physics** | named | References `"DSound Error: SoundBuf->Lock fail..."` / `"...BackgroundBuf->Lock..."` strings and `Lock`/`Unlock`-style vtable calls. This is double-buffered audio streaming, not physics |
| `0x40ecb0` | `player_turn_smoothing_substep` (called only while state==0x47) | named | Takes `DAT_0047c488` (see below) and runs a proportional-smoothing loop `DAT_0047c488` times on a value at `param_1+0xbd`/`+0x121` (steering/turn smoothing?). Confirms `DAT_0047c488` is consumed as a sub-step count, i.e. treated as elapsed ticks |
| `0x40e980` | `player_cooldown_timers_tick` (called only while state==0x47) | named | Subtracts `DAT_0047c488` from several countdown timers on the player/vehicle object (`param_1+0x1a1/0x1a5/0x1a9/0x1ad` -- cooldowns/animation timers), firing side effects (sound events via `DAT_0046ea30`/`DAT_0047c038` vtables) when they expire |
| **`0x4092d0`** | **`compute_frame_delta_ticks_60hz_min1_clamp` -- THE key find** | named | `DAT_0047c488 = FUN_004092d0()` is called once per frame from `0x40e980`. Converts `timeGetTime()` (ms) to a 60Hz tick count (`ms*60/1000`), diffs against the stored value from last call, returns the tick delta. **Min-1 clamp:** `if (iVar2 == 0) iVar2 = 1;` -- if the game is rendering faster than 60fps, less than one 60Hz tick elapses between calls (delta rounds to 0), but the function clamps the minimum return value to 1 tick anyway. Net effect: above 60fps, simulation time is credited faster than real time, in direct proportion to render rate -- a clean, **deterministic linear speedup**, not glitchy/non-deterministic breakage (confirmed by the user: "physics does not break above 60fps, it's deterministic and doesn't seem to behave any differently than 'FASTER'" -- exactly what this clamp predicts). At or below 60fps the delta is accurate (real elapsed ticks, never hits the clamp), which is exactly why the dgVoodoo `FPSLimit=30` workaround works. This is a real per-frame delta-time system with one specific min-clamp causing the speedup, not a naive "no delta timing at all" -- worth correcting the `docs/HANDOFF.md` characterization of "no frame limiter = FPS-coupled" to the more precise "has delta timing, but a >60fps min-tick clamp makes simulation speed scale with framerate above that threshold" |
| `0x0047c488` (data) | per-frame delta value (ticks) | analyzed | Recomputed by `0x4092d0` each call; consumed by `0x40ecb0` (sub-step loop count) and `0x40e980` (timer decrement amount) |
| `0x435610` (vtable slot 12) | unanalyzed | unanalyzed | Real function (not a stub) on the same vtable, unexplored |
| `0x437370` (vtable slot 15) | unanalyzed | unanalyzed | Real function (not a stub) on the same vtable, unexplored |
| **Open question, REVISED** | cockpit ("normal") vs. full-viewport ("maximized") speed difference | unanalyzed | User testing (2026-07-03) with `FPSLimit=0` + `[DirectX] ForceVerticalSync=true` (both views now genuinely vsync-locked to the same real 60fps): **"normal" now runs at exactly the correct speed; "maximized" runs at exactly 2x normal's speed** -- and the 2x ratio is unchanged from before the dgVoodoo tuning (only "normal"'s absolute speed was fixed by the config change). Since both views are confirmed at the *same actual framerate* now, the render-cost/"naturally throttled below 60fps" theory from `docs/PATCHES.md` **cannot explain a persisting 2x gap** -- framerate parity should mean parity in the `compute_frame_delta_ticks_60hz_min1_clamp` clamp behavior too, since neither view exceeds 60fps anymore. This points instead to a genuine **code-level difference**: something in the full-viewport/"maximized" path likely calls the per-frame update/tick machinery (`player_cooldown_timers_tick`/`player_turn_smoothing_substep`, or whatever drives them) an extra time per rendered frame, independent of actual framerate. Not yet located -- the `+0x92a` flag and its vtable-slot-21 gate (still just a base-class stub on the object checked so far) remain a lead, but given the flag is a generic base-class field used by ~29 unrelated functions, the real mode-switch code is more likely in whatever toggles between the cockpit-dashboard render path and the full-viewport render path (bound to the `+` key) -- not yet found. **Do not re-attempt the previous FPS patch approach (min-clamp removal) to explain this** -- that was a different, already-reverted-as-unsafe mechanism (see "FPS-coupling" section in `docs/PATCHES.md`) and doesn't explain a framerate-independent 2x multiplier anyway |

## Alt-tab / focus-loss investigation

Triggered by a real symptom report: menu appears to "reset" when alt-tabbing out and back in
while running via dgVoodoo2. Also connects to a second observation: the game renders as a
borderless-but-resizable window, not true OS fullscreen or a titled window.

| VA | Name | Status | Notes |
|---|---|---|---|
| `0x40b5b0` | `wndproc_dispatch` | named | Main WndProc. Handles `WM_DESTROY` (2, sets state=0xf0), `WM_ACTIVATEAPP` (0x1c), `WM_SETFOCUS`-family (7/0xf), plus DirectDraw palette/mouse messages (0x201/0x202/0x203) and custom app messages 0x401-0x405 |
| `0x436070` | `on_deactivate_force_pause_state` (vtable slot 13 / `0x34`) | named | On `WM_ACTIVATEAPP(0)`: skips if state==0xf0 (exiting). Otherwise backs up current state to `DAT_0047e578`, force-sets state to `0xB0` (pause), calls `0x40a8b0`, a vtable[23] call on a secondary object, then `state_transition_with_limiter` |
| `0x4360e0` | `on_reactivate_restore_state` (vtable slot 14 / `0x38`) | named | On `WM_ACTIVATEAPP(1)`: **correctly restores** the state backed up in `DAT_0047e578`. Calls `ddraw_full_display_reinit`, then vtable[30]/[34] calls on a secondary object, conditionally `0x40a910`, then `dsound_stream_pump`, then `state_transition_with_limiter`. The state machine itself is NOT the bug -- it round-trips cleanly |
| `0x40bd30` | `ddraw_full_display_reinit` | named | **The actual heavy-lifter.** Full DirectDraw teardown/rebuild: `SetDisplayMode`, `CreateSurface` (primary+back, with retry loop on `DDERR_SURFACELOST`/`DDERR_WASSTILLDRAWING`), `Lock`, `CreatePalette`. This is the exclusive-fullscreen "recreate everything after losing the display device" path, not a lightweight `IDirectDrawSurface::Restore()`. Explains both symptoms: (1) the visible "reset" flash on alt-tab-back-in is a real full surface recreation, and (2) it only makes sense if the game requested `DDSCL_EXCLUSIVE\|DDSCL_FULLSCREEN` -- which is consistent with dgVoodoo2 presenting it as a borderless-but-resizable window rather than a normal titled window (dgVoodoo's own rendering of a wrapped exclusive-fullscreen DirectDraw app) |
| **Conclusion, PARTIALLY REVISED (two distinct symptoms, not one)** | state machine confirmed not buggy; two separate "reset" triggers exist | -- | Internal game state survives alt-tab correctly at the state-machine level (confirmed originally, still true). Two *different* real-world symptoms both got called "resets to menu" during testing, and they have different causes: **(1) alt-tab while paused, staying away/paused too long** -- this was the pause-loop message-queue hang (see `docs/PATCHES.md` "Pause-loop hang"); confirmed fixed by `HAVOC_NOCD_PAUSEFIX_v1.EXE` (2026-07-03 test: alt-tab away while paused, return, unpause -> continues normally). **(2) alt-tab while NOT paused** -- user confirmed (2026-07-03, same session, same `HAVOC_NOCD_PAUSEFIX_v1.EXE` binary) this STILL resets to the menu on refocus, so it is a genuinely separate, still-unresolved issue -- the pause-loop fix did not touch it. Since the WM_ACTIVATEAPP handlers (`on_deactivate_force_pause_state`/`on_reactivate_restore_state`) run unconditionally on every alt-tab regardless of pause state, and we already confirmed those two functions round-trip the state variable correctly, the cause of symptom (2) is still open -- likely either in `ddraw_full_display_reinit`'s surface recreation actually failing to restore the correct visual content (not just the state int), or some other object beyond the one game-state variable we've traced so far. **Do not assume this is resolved** -- re-open investigation if picked back up |
| **Tested** | mouse input in menu, fresh launch vs. post-alt-tab | -- | User confirmed (2026-07-03): mouse responds correctly in the menu both on fresh launch and after alt-tabbing. An earlier report of "menu doesn't respond to mouse" was transient/not reproducible -- not a real regression from the `ddraw.dll` permission fix, the `FPSLimit`/`ForceVerticalSync` tuning, or this investigation |
| **Live-confirmed (2026-07-04)** | state transition 0x47->0xB0 on alt-tab, MCP debug agent | -- | Hardware watchpoint on `game_object+0x18` (runtime addr `0x2361064`) fired during active gameplay (state==0x47). Write at `0x4360A7` (`MOV [ECX+18h], 0xB0`) inside `on_deactivate_force_pause_state`. At stop: `eax=0x47` (old state just read), `esi=0x1c` (WM_ACTIVATEAPP - exact match), `DAT_0047E578=0x47` (prev-state global saved as expected), `game_object+0x20=0x47` (target state still 0x47). State machine round-trips correctly - confirms existing static analysis. The still-unresolved symptom-2 (reset to menu on re-focus during gameplay) is not in this state write; it lies further along in `on_reactivate_restore_state`/`ddraw_full_display_reinit`. |

## Keyboard-reassignment menu graphics bug (first genuine bug found this session)

Symptom: on the "Change Keyboard Settings" screen, the dynamic elements (the list of game
functions + their currently-assigned keys, since the static menu chrome loads fine) flash
for a fraction of a second on menu load, then disappear and never redraw.

Confirmed the string table for this screen: `INTRFACE.FF` resource `STR#7A62`
(`tools/out_intrface/raw/STR#7A62.dat`): `"Press a key to assign to selected game function." /
"Cancel" / "Save Settings" / "Restore Default Settings"`. The parent Options menu is
`STR#7A44`: `"Change Game Settings" / "Change Viewscreen Settings" / "Change Keyboard
Settings" / "Change Joystick Settings" / "Return to Main Screen"`.

**Initial hypothesis (retracted, see the `+0x92a` correction above):** thought the
per-frame vtable[21] stub on the top-level game object was the missing dynamic-redraw call.
Scanning showed `+0x92a` is a common base "Window" class active-flag used by ~29 different
functions across the codebase -- not specific to this menu. The stub at `0x4188c0` is the
*base class's* default and is plausibly correct/intentional there; it doesn't mean every
derived window's slot 21 is a stub.

**Progress: found the Options-menu construction function as a template.** `0x4596c0`
(scanned via the `0x7a44` resource-ID search) builds the whole "Change Game/Viewscreen/
Keyboard/Joystick Settings" screen: allocates a button widget per string ID starting at
`0x7a45` (looping, each with its own vtable -- `PTR_LAB_004795b0`, `PTR_LAB_004794e0`,
`PTR_FUN_00479610`, `PTR_LAB_00479448`, `PTR_LAB_00479478`, `PTR_FUN_00479070` are all
distinct widget-subclass vtables: buttons, labels, sliders), sets a title via `0x426240`
(likely `SetTitleString(resourceId)`), then finishes with `FUN_00426240(param_1, 0x7a44)`
followed by `FUN_004264d0(param_1)` -- **that's the base-class `Show` method we identified**,
called on the newly-built screen object itself. Confirms the general pattern: every menu
screen is its own object instance with its own per-widget vtables, constructed by a
dedicated "build this screen" function, finished off by the common `Show`.

Also found `0x458350`, a widget message handler that references `0x7a62` (computing a
string-ID offset based on a selection index for what looks like a status/tooltip line, matching
STR#7A44's `"Move the mouse over a button for a description of its function."`) -- likely a
*shared* button/widget message handler reused across multiple screens, not specific to the
keyboard-reassignment screen's own construction.

**Still open, next step:** find the keyboard-reassignment screen's own construction function
-- the equivalent of `0x4596c0` but building buttons/labels from string IDs starting around
`0x7a63` (the item after `STR#7A62`'s header string) instead of `0x7a45`. Once found, check
whether its per-widget-type vtables (for whatever draws the dynamic key-binding list
specifically) have a real per-frame update/redraw implementation or a stub -- that's where
the actual bug should surface. Given "flash once then disappear" (not "never drawn at all"),
the initial static draw works -- something about the *per-frame* redraw path for this
screen's dynamic list specifically is what's missing or broken.

## Copy-protection / file loading (docs/PATCHES.md)

| VA | Name | Status | Notes |
|---|---|---|---|
| `0x0042a480` | WORLDS\ data-file loader | documented | The copy-protection check function; patched. See `docs/PATCHES.md` |
| `0x0042a880` | fn_init_file_objects | analyzed | |
| `0x0042db00` | delete_savegame | analyzed | `DeleteFileA` wrapper |
| `0x0042dab0` | strcpy_to_obj | analyzed | |
| `0x0042d920` | error_display_6 | analyzed | |
| `0x0042d970` | show_error_dialog | documented | Patched to `RET` (Patch N3) to silence popups |
| `0x00438d80` | get_strdata_string | analyzed | |
| `0x004274e0` | alloc_obj | analyzed | |
| `0x00444db0` | GRAFIX0N.DAT loader | documented | Byte-swaps BE records; template for other WORLDS loaders. See `docs/FORMATS.md` |

## Not yet started (from docs/HANDOFF.md section 7)

| Target | Status | Notes |
|---|---|---|
| Cheat code handler (`mmm`/`vvv`/`sss`/`hhh`/`aaa`) | unanalyzed | Find the keyboard-buffer matcher |
| Weapon system (6 primary + 14 secondary) | unanalyzed | See `docs/WEAPONS.md` for the string-table side |
| Player/vehicle physics | unanalyzed | |
| Enemy AI | unanalyzed | |
| MAP/LAND/STUF loaders | unanalyzed | Also finishes the asset-cracking stream |

## How to update this

1. Decompile with the headless scripts in `tools/ghidra_scripts/` (e.g. `DecompileFPS.java`,
   `DecompileHavoc.java` -- extend their `TARGET_VAS` arrays, or add a new script for a new
   investigation topic).
2. Read the output in `tools/ghidra_decompile*.txt`, update the row's status here.
3. If you rename a function in the Ghidra GUI/project, bump status to `named` here too.
4. If it gets a real writeup elsewhere in `docs/`, bump to `documented` and link it.