Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
101 lines (85 loc) · 5.12 KB

ARCHITECTURE.md

File metadata and controls

101 lines (85 loc) · 5.12 KB
Raw

Architecture and binary inventory

Exact target

The only accepted target is the original Japanese TH08 v1.00d executable. Its identity is recorded by the SHA-256 in reccmp-project.yml; every analysis or comparison must resolve to these facts:

Property Value
Architecture 32-bit x86 PE GUI executable
File size 840,704 bytes
SHA-256 330fbdbf58a710829d65277b4f312cfbb38d5448b3df523e79350b879213d924
Image base 0x00400000
Entry point 0x004A619E
.text virtual range 0x00402000–0x004B3B77 (inclusive)
Toolchain family Visual C++ .NET 2002 (VC7)

Function starts and extents in Ghidra, IDA, and CSV exports are analysis artifacts. Tail chunks, alignment, shared code, and missed instructions must be reconciled against the exact target before they become comparison boundaries.

Provenance

The repository is a history-preserving continuation of GensokyoClub/th08. The upstream source, configuration, build tools, and contributor commits form the initial baseline. Continuation changes should be additive commits by their actual authors; do not squash or re-author the imported history.

Runtime subsystems

The current src/ layout follows the upstream engine responsibilities:

  • Supervisor, main, window/input, callback chains, timing, and globals;
  • ANM loading/VM/rendering, ASCII text, GUI, and screen effects;
  • background, enemy, bullet, item, player, spell-card, and game managers;
  • title, music room, replay, score, ending, and result screens;
  • sound/MIDI and the zwave implementation;
  • PBG archive, file, memory, and LZSS support under src/pbg/.

These filenames are useful source-ownership hypotheses. Only target evidence and linked-object comparison can establish original translation-unit boundaries.

Repository structure

  • src/: reconstructed C++ and ABI-facing headers.
  • config/mapping.csv: address/type mapping used by upstream analysis tools.
  • config/reccmp-*.csv: function, global, float, string, and comparison maps. reccmp-relocations.csv is a relocation-only allowlist for attested IAT slots, import thunks, and data symbols; its rows are not function inventory and never contribute authored progress.
  • config/implemented.csv: symbols with authored source; inclusion is not itself an exact-match result.
  • config/match-units.toml and config/matches.csv: strict function-level comparison definitions and accepted exact results.
  • config/library-provenance.toml, config/library-match-units.toml, and config/library-matches.csv: SHA-pinned target-linked archive provenance, library-specific comparison definitions, and accepted library exact results. They are intentionally separate from authored progress.
  • config/mapping-overlaps.csv: explicit target-proven nested-funclet overlap exceptions; stale or unclassified overlap state is rejected/reported by the tracking validator.
  • config/claims.csv: retired claim schema, kept header-only for compatibility with earlier history; it is not current task state.
  • scripts/: environment acquisition, Ninja generation, target verification, focused matching, typed target facts, and progress helpers. Reusable read-only investigations live under scripts/analysis/; completed phase-specific reproducers live under scripts/analysis/historical/.
  • reccmp-project.yml: exact target hash and reccmp data sources.
  • objdiff.json: reconstructed/original COFF unit mapping.
  • 3rdparty/: the pinned Detours submodule used only by the optional DLL build.
  • resources/: non-source inputs and progress artwork; the private target is expected here but must not be committed.
  • build/: generated executables, objects, maps, and reports.
  • .analysis/: ignored, disposable scratch evidence for the active bounded investigation. It must not be treated as status or durable instructions.

scripts/progress.py derives source-presence and strict exact-match views in docs/PROGRESS.md. Its SVG uses authored exact bytes for the progress bar and adds explicitly separate playable-platform delivery cards. Source presence comes from config/implemented.csv; exact coverage counts only accepted rows in config/matches.csv. CI checks these generated files but cannot replay private target comparisons.

The library rows in config/reccmp-functions.csv describe code linked into the original TH08 image, principally VC7 CRT/runtime and D3DX bodies. They are not the same thing as repository dependencies under 3rdparty/. Detours is used by the optional DLL build and is not a target library-reconstruction milestone.

Evidence relationship to adjacent games

The N0zoM1z0/th07 reconstruction supplies this repository's workflow and structure. TH07 and TH06 share engine concepts, compiler idioms, and many subsystem names with TH08, so their source can quickly suggest candidates for migration, but TH08 changed gameplay systems, layouts, control flow, globals, and translation-unit boundaries. Treat every migrated declaration or implementation as an unverified hypothesis until TH08 1.00d disassembly and comparison confirm it.