# happyhavoc/th06 architecture

> Architecture diagram of the GitHub repository happyhavoc/th06, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/happyhavoc/th06
- Repository: https://github.com/happyhavoc/th06

## Overview

##### Project Type & Purpose
- The project is a game reimplementation that leverages reverse engineering techniques; its goal is to reconstruct and decompile the original game executable (東方紅魔郷.exe version 1.02h).
- The README emphasizes both the reverse engineering workflow and the reimplementation process (using objdiff to compare original object files with freshly rebuilt ones). It communicates that the project is in early stages but already includes a comprehensive build pipeline, decompilation scripts using Ghidra, and traditional C++ source code modules.

##### Analyzing the File Structure
- Top-Level Directories:
- src/: Contains all the C++ source and header files representing the game’s engine, logic, and subsystems (graphics, audio, game state management, etc.).
- scripts/: Includes numerous Python scripts that handle the build process, dependency setup, Ghidra integration (e.g., exporting/importing mappings), decompilation support, and task automation (like generating function stubs and diffs).
- config/: Has configuration files for Ghidra mappings and other CSV/toml files that define what is implemented, stubbed out, or how to map names. These files are central in bridging original executable artifacts and the reimplementation.
- tests/: Contains test files used to validate some of the functionality, such as comparing parsed object data (for instance for pbg3).
- 3rdparty/: Contains external libraries (like Detours and munit) that are used in either the build process or runtime for the game.
- resources/: Stores assets like the game executable (to be copied manually by the user), a progress indicator, and maybe other run-time assets.
- Build & Dependency Tools:
- The project provides a build.py script that triggers ninja builds after generating a ninja build file.
- There are additional Python scripts for environment setup (create_devenv.py, create_th06_prefix) and for integration with Ghidra (export/import scripts in scripts/ghidra).
- Build configuration files like .clang-format, .gitignore, and GitHub workflows hint at automated CI/CD and code formatting support.

a. Main Components:
- Build System: Python scripts (build.py, create_devenv.py, create_th06_prefix) and configuration files that handle dependency management and code building.
- Reverse Engineering Integration: Ghidra integration modules (under scripts/ghidra) and configuration CSV/TOML files (in config) that map original executable data to source code artifacts.
- Core Game Engine: The C++ source code (in src) composed of multiple game systems—managing graphics, audio, game logic, UI (MainMenu, GameWindow), and more.
- External Dependencies & Third-Party Libraries: Components under 3rdparty (e.g., Detours) and any external tools (msiextract, wine, Visual Studio 2002/DirectX 8.0).
- Testing Framework: Located in tests/ to validate functionality and ensure correct behavior.
- Assets/Resources: Managed in the resources/ directory such as the original game exe and the progress graphics.

b. Relationships & Data Flow:
- How the Build System (Python scripts) orchestrates the entire Pipeline:
- Downloading dependencies, environment setup, invoking the compiler, and generating a ninja build file.
- Interactions between the Reverse Engineering Module and Core Game Engine:
- Ghidra scripts export object and mapping data, which is then used to guide decompilation efforts and function stub generation.
- Integration with external repositories (e.g., the companion th06-re Ghidra output repository) and tools like objdiff for validating the reimplementation against the original binary.
- Test flows between tests/ and the core engine to ensure that the diff output or game logic is correct.

c. Architectural Patterns or Design Principles:
- Separation of Concerns: The project clearly separates reversing tasks, build orchestration, and actual game code.
- Modular Design: Each subsystem (e.g., EnemyManager, BulletManager, etc. within src) can be treated as independent modules which are tied together via the game manager or supervisor.
- Integration of Legacy Toolchains: The system makes dedicated use of legacy tools and environments (Visual Studio 2002/DirectX 8.0) to closely mimic the original build environment.

d. Relevant Technologies, Frameworks, or Libraries:
- C++ for the core game engine.
- Python3 for scripting the build process and reverse engineering integrations.
- Ghidra for reverse engineering along with custom Java and Python scripts for data export/import.
- Ninja build system (to be generated and invoked via build.py).
- External libraries such as Detours and testing libraries (munit).
- DirectX 8.0 and elements from the Visual Studio ecosystem.

- Clear labeling of each major component:
- Build System (Python scripts: build.py, create_devenv.py, etc.)
- Reverse Engineering & Mapping Layer (scripts/ghidra subdirectory, config mapping files)
- Core Game Engine (C++ modules in src; you might further break this down into game logic, UI, audio, etc.)
- External Tools and Dependencies (3rdparty libraries, Visual Studio, DirectX)
- Test Framework (tests/)
- Resources/Assets (resources/)
- How build scripts trigger ninja builds.
- Data flow from the original executable (resources/game.exe) to the processing scripts (export_ghidra_database.py, export_ghidra_objs.py) and then to the reimplementation in the source.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies Layer
    subgraph "External Dependencies Layer"
        D["External Dependencies & Third-Party Libraries"]:::dependency
    end

    %% Build & Reverse Engineering Tools Layer
    subgraph "Build & Reverse Engineering Tools Layer"
        BS["Build System"]:::build
        REM["Reverse Engineering Module"]:::reverse
        MC["Mapping Configs"]:::reverse
        BS -->|"provides"| REM
        MC -->|"supports"| REM
    end

    %% Core Game Engine Layer
    subgraph "Core Game Engine Layer"
        CE["Core Game Engine"]:::engine
    end

    %% Testing & Assets Layer
    subgraph "Testing & Assets Layer"
        TF["Testing Framework"]:::test
        AR["Assets & Resources"]:::assets
    end

    %% Connections between layers
    D -->|"dependencies"| BS
    D -->|"libraries"| CE
    BS -->|"triggersBuild"| CE
    REM -->|"mappingIntegration"| CE
    AR -->|"assetInjection"| CE
    CE -->|"validatedBy"| TF

    %% Click Events
    click BS "https://github.com/happyhavoc/th06/blob/master/scripts/build.py"
    click REM "https://github.com/happyhavoc/th06/tree/master/scripts/ghidra"
    click MC "https://github.com/happyhavoc/th06/tree/master/config"
    click CE "https://github.com/happyhavoc/th06/tree/master/src/"
    click D "https://github.com/happyhavoc/th06/tree/master/3rdparty/"
    click TF "https://github.com/happyhavoc/th06/tree/master/tests/"
    click AR "https://github.com/happyhavoc/th06/tree/master/resources/"

    %% Styles
    classDef build fill:#f8c291,stroke:#e58e26,stroke-width:2px;
    classDef reverse fill:#9b59b6,stroke:#843c8b,stroke-width:2px;
    classDef engine fill:#82ccdd,stroke:#1e90ff,stroke-width:2px;
    classDef dependency fill:#55efc4,stroke:#0c7b93,stroke-width:2px;
    classDef test fill:#f6e58d,stroke:#f9ca24,stroke-width:2px;
    classDef assets fill:#fab1a0,stroke:#e17055,stroke-width:2px;
```
