homm3-decomp

Work in progress. Most functions of HEROES3.EXE match; the remaining functions and data are being reconstructed.

C++ reconstruction of Heroes of Might and Magic III Complete (HEROES3.EXE, New World Computing, 2000), built with the original Visual C++ 6.0 SP3 toolchain under Wine. The Dreamcast and Classic Mac ports are references for source structure. Retail bytes are authoritative. Supply your own executables.

Match status

<!-- match-score:start -->

Windows HEROES3.EXE: 99.13% matched (MAX) — 4,596 / 4,785 functions exact (96.1%), weighted by size over 1,999,585 bytes of code.

Score	Functions exact	Weighted	Meaning
CUR	4,590	99.12%	last measured score
MAX	4,596	99.13%	best result for each function's current source
HIST	4,607	99.26%	all-time peak across source revisions

MAX by module:

Module	Units	Functions exact MAX	Fuzzy MAX
game	123	3855 / 3997 (96.4%)	99.22%
rmg	6	324 / 370 (87.6%)	97.44%
network	4	279 / 280 (99.6%)	99.99%
zlib-1.1.3	14	69 / 69 (100.0%)	100.00%
codec	4	43 / 43 (100.0%)	100.00%
victor	7	26 / 26 (100.0%)	100.00%

Library and compiler-generated code (outside the scores; each function verified against what produced it):

Category	Functions	Verified	Code (B)	Status	How verified
Platform libraries	912	912	110,461	library, verified	bytes and relocations equal pinned library members (config/retail/runtime-functions.tsv)
EH unwind funclets	5,125	4,624	53,151	compiler-generated, verified with parent	parent's .text$x COMDAT: bytes and every relocation target (library parents: their library section)
init/cleanup thunks	1,173	1,164	95,322	compiler-generated, verified	source-emitted CRT bodies, bytes and named relocations
import thunks	27	26	162	linker-generated, verified	FF 25 through a named IAT slot (and the pinned import library where one exists)

Byte accountability: 1,051 file bytes unclaimed; 0 bytes with conflicting claims; 703 unverified and 0 mismatching game data bytes; 568 bytes of exception records pending their functions' matches; 26,080 bytes of reviewed padding. 12,188 / 12,200 enrolled initializer comparisons exact. 973 source-emitted CRT bodies exact (89,376 bytes). Data reports separate ownership, raw byte comparisons and verified library ranges.

<!-- match-score:end --> <!-- mac-match-score:start -->

Mac reference Heroes_III_raw.pef: 64.14% matched — 713 / 1,546 paired functions exact, over 463,640 compared bytes (last homm3 mac build checkpoint).

<!-- mac-match-score:end --> <!-- h3maped-match-score:start -->

GOG Complete map editor h3maped.exe: 99.52% matched (MAX) — 6,032 / 6,170 functions exact (97.8%), weighted by size over 821,742 bytes of code.

Score	Functions exact	Weighted	Meaning
CUR	5,956	99.40%	last measured score
MAX	6,032	99.52%	best result for each function's current source
HIST	6,045	99.62%	all-time peak across source revisions

MAX by module:

Module	Units	Functions exact MAX	Fuzzy MAX
game	164	5486 / 5551 (98.8%)	99.77%
rmg	6	416 / 472 (88.1%)	97.94%
zlib-1.1.3	12	56 / 56 (100.0%)	100.00%
codec	3	49 / 53 (92.5%)	99.99%
victor	7	25 / 26 (96.2%)	99.99%
(unmatched)	—	0 / 12 (0.0%)	0.0%

Library and compiler-generated code (outside the scores; each function verified against what produced it):

Category	Functions	Verified	Code (B)	Status	How verified
Platform libraries	2,585	2,499	259,423	library, verified	bytes and relocations equal pinned library members (config/retail/runtime-functions.tsv)
EH unwind funclets	4,394	517	47,687	compiler-generated, verified with parent	parent's .text$x COMDAT: bytes and every relocation target (library parents: their library section)
init/cleanup thunks	3,688	1,039	81,830	compiler-generated, verified	source-emitted CRT bodies, bytes and named relocations
import thunks	13	13	78	linker-generated, verified	FF 25 through a named IAT slot (and the pinned import library where one exists)

Data: 2,736 / 16,670 referenced data objects claimed (placements and the image's own DATA() claims).

<!-- h3maped-match-score:end --> <!-- h3ccmped-match-score:start -->

GOG Complete campaign editor h3ccmped.exe: 99.16% matched (MAX) — 1,554 / 1,622 functions exact (95.8%), weighted by size over 266,030 bytes of code.

Score	Functions exact	Weighted	Meaning
CUR	1,550	98.84%	last measured score
MAX	1,554	99.16%	best result for each function's current source
HIST	1,566	99.27%	all-time peak across source revisions

MAX by module:

Module	Units	Functions exact MAX	Fuzzy MAX
game	44	1432 / 1479 (96.8%)	99.20%
zlib-1.1.3	12	56 / 56 (100.0%)	100.00%
codec	3	41 / 41 (100.0%)	100.00%
victor	7	25 / 26 (96.2%)	99.99%
(unmatched)	—	0 / 20 (0.0%)	0.0%

Library and compiler-generated code (outside the scores; each function verified against what produced it):

Category	Functions	Verified	Code (B)	Status	How verified
Platform libraries	2,345	2,280	234,963	library, verified	bytes and relocations equal pinned library members (config/retail/runtime-functions.tsv)
EH unwind funclets	1,624	1,367	16,589	compiler-generated, verified with parent	parent's .text$x COMDAT: bytes and every relocation target (library parents: their library section)
init/cleanup thunks	454	164	5,416	compiler-generated, verified	source-emitted CRT bodies, bytes and named relocations
import thunks	13	13	78	linker-generated, verified	FF 25 through a named IAT slot (and the pinned import library where one exists)

Data: 3,743 / 9,383 referenced data objects claimed (placements and the image's own DATA() claims).

<!-- h3ccmped-match-score:end -->

Scores satisfy CUR ≤ MAX ≤ HIST. Editing a function resets its MAX to its new CUR; HIST above MAX marks a lost peak worth recovering (homm3 status hist-gap lists them; homm3 status last-exact NAME --diff shows what changed since).

Branches

decomp-complete-4.0 (you are here) ----> decomp-loki-1.0

• decomp-complete-4.0 — Complete 4.0 HEROES3.EXE (Sep 2000), VC6 SP3
• decomp-loki-1.0 — Loki Linux 1.0 map editor h3maped, GCC 2.95.2

Pinned executables

HEROES3.EXE is the target; the Dreamcast and Mac builds are evidence. Supply your own copies; sizes and SHA-256 hashes are pinned in config/project.toml.

• HEROES3.EXE: English Complete 4.0, engine 3.2 (MSVC 6.0, Sep 2000)
• h3maped.exe: English Complete 4.0 map editor (MSVC 6.0 SP3, MFC 4.2, Sep 2000)
• h3ccmped.exe: English Complete 4.0 campaign editor (MSVC 6.0 SP3, MFC 4.2, Sep 2000)
• H3.EXE: Dreamcast port, SH-4 with CodeView symbols (Aug 2000)
• Heroes_III_raw.pef: Classic Mac OS port, PowerPC CodeWarrior (Dec 2000)

Quickstart

With Nix flakes enabled, the three executables and the pinned CodeWarrior tools, run from the repository root. homm3 init verifies the inputs and both compilers and sets up Wine; homm3 build compiles and compares every Windows module and runs the checks. It does not yet produce a playable game.

nix develop .#build
gh auth login        # needed for the toolchain download
HOMM3_EXE=/absolute/path/to/HEROES3.EXE \
HOMM3_DREAMCAST_EXE=/absolute/path/to/H3.EXE \
HOMM3_MAC_EXE=/absolute/path/to/Heroes_III_raw.pef \
HOMM3_MAC_TOOLCHAIN=/absolute/path/to/CodeWarrior/tools \
  homm3 init
homm3 build

Retail inputs, the toolchain, Wine state and generated reports stay in ignored build/. The shell also provides clangd and keeps compile_commands.json up to date for editors.

Improve a function

Pick a function whose MAX is below 100%, read the retail assembly and the Dreamcast evidence, edit the C++, and rebuild its unit. The example uses 0x00524dd0 from src/philai.cpp:

homm3 status functions
homm3 sema disasm 0x00524dd0
homm3 dreamcast show 0x00524dd0
homm3 dreamcast asm 0x00524dd0 --blocks
homm3 build --fast philai
homm3 sema diff 0x00524dd0 --summary
homm3 status update --write-readme   # bank the scores and regenerate this README

homm3 mac show, mac diff and mac calls show a function's Mac counterpart; homm3 mac build philai scores the unit's Mac pairs. homm3 status check reports score changes and homm3 status merge-baseline resolves a conflicted score ledger.

Data matching

homm3 compare compares existing objects without rebuilding. homm3 build --data adds byte accounting: unclaimed bytes, overlapping ranges and initializer differences.

Documentation

• Documentation index and reconstruction debt
• Data matching and the Mac tooling guide
• Contributor rules and the full evidence pass are in AGENTS.md

License

Project-authored source and tooling use CC0 1.0. Files with their own notices, notably everything under vendor/, keep their terms; retail inputs, compiler binaries and game assets are excluded.

Thanks

NH3API documented game structures and their layouts, and supplied naming references beyond the Dreamcast symbols.