Decompilation of the Gepard3D engine
------------------------------------

This project is decompilation of the original Panzers Phase 1 exe, with the end goal of creating a buildable source compatible with the original datafiles. The work is primarily being done in Ghidra, with clean implementation of some functions to validate understanding and build separate libraries for (eventually) making better tools for manipulating data files.

Building and booting (branch boot-to-menu)
------------------------------------------

The `src/` tree is a 32-bit (x86) rebuild. It boots the 2016 HD release's data
to the main menu. It is based on the game-agnostic Gepard engine modules of a
S.W.I.N.E. HD decomp (core, common, 3dengine, window, sound, mdec, platform).
Panzers' own startup, file system, Miles sound, Bink intro and main menu are
lifted from the HD PANZERS.exe. Any function lifted from Panzers is marked
`// PANZERS 0xADDR`.

Requirements: Visual Studio with C++ (x86), CMake 3.10+, Python 3, and the
DirectX SDK (June 2010) found via `DXSDK_DIR`.

    cmake -S . -B build -G "Visual Studio 18 2026" -A Win32 -DGEPARD_AUDIO_BACKEND=miles
    cmake --build build --config Release --parallel

Each build prints a census, e.g.
`CENSUS: 153 lifted bodies + 1331 SWINE-shared bodies + 26 stubs`. Check it
after every build: an unexpected change means code was dropped or duplicated.

To run, copy `build/src/main/Release/panzers.exe` into a copy of your own
install (the folder with the .pak files, mss32.dll, binkw32.dll and miles/), then
run it with `-nointro` to skip the Bink intro. Game data is never part of
this repo.

Mods
----

Mods are opt-in. Each one has its own CMake switch, OFF by default, so the
default build stays the faithful one; the switches are listed in
src/core/mods.h. Build a mod build in a separate build directory:

    cmake -S . -B build-mod -G "Visual Studio 18 2026" -A Win32 -DPANZERS_MOD_WIDESCREEN=ON
    cmake --build build-mod --config Release --parallel

- PANZERS_MOD_WIDESCREEN: widescreen window. The original stretches its
  1024x768 menus to any window size and crops the 3D view at the top and
  bottom. With the mod, a window wider than 4:3 shows more of the 3D scene
  at the sides (same vertical field of view, Hor+). The menus keep their
  4:3 shape: the top and bottom bars run the full width, the logo and
  centred screens stay centred, and the main menu stays at the right edge.
  Runtime toggle: `[Mods] Widescreen = 0` in panzers.ini turns it off.
- PANZERS_MOD_BUGFIXES: fixes for bugs of the original game. So far:
  closing the window on the Credits screen no longer ends in the panic
  "SWidget::~SWidget: Children widgets should be removed first" (HD's
  SSuperWindow::OnDestroy forgets to delete the credits screen).

Comparing with the original
---------------------------

reccmp (pip install reccmp) scores every lifted function against the HD
PANZERS.exe. One-time setup: create `reccmp-user.yml` (gitignored) with the path
to your original exe:

    targets:
      PANZERS:
        path: 'D:/path/to/a/copy/of/PANZERS.exe'

Optionally export the original's function extents once (Ghidra + pyghidra), which
makes the scores more accurate:

    python tools/ghidra/funcbounds.py --exe D:/path/to/PANZERS.exe --out build/pz_funcs.tsv

Then, after a Release build:

    python tools/reccmp_run.py

This regenerates reccmp-functions.csv from the `// PANZERS 0xADDR` markers
(tools/reccmp_gen.py), runs reccmp (build/reccmp-report.html/.json) and writes
build/reccmp-rescore.tsv, the per-function drift table, worst first. See
docs/RECCMP.md for how to read it.

Docs:
- docs/RECCMP.md          reccmp setup, similarity buckets, worst functions, SWINE reuse check
- docs/re/TRIAGE.md      HD exe triage: boot path, libraries, symbol sources
- docs/FORMATS.md         pak, ini and menu.ini string table
- docs/ENGINE_DIFF.md     Panzers HD vs SWINE engine: struct/vtable drift, renderer, sound
- docs/MENU3D_INTERFACES.md  3D menu background: HD interfaces, Gepard facade, owners, -menu3d
- docs/STUBS_HIT.md       stubs reached at runtime, with their HD addresses
- docs/IMPORT_NOTES.md    what was imported from the SWINE engine, and what was cut
- tools/ghidra/           headless pyghidra helpers (decompile by address/string)
- tools/addr2func.py      crash RVA -> function name, using the map file

Note: phase1-raw-ghidra-export/ comes from a 2004 retail build, not the HD
exe. Its names and structs are useful, but its addresses do not apply.