# stackboom/lunahook architecture

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

- Interactive diagram: https://gitdiagram.com/stackboom/lunahook
- Repository: https://github.com/stackboom/lunahook

## Overview

##### Project Type and Purpose
- LunaHook is a native C++ hooking library and host application for extracting and processing in-game text (for translation).
- It consists of two main deliverables:
a. The “LunaHook” injection module (DLL) that you inject into a target (32-bit or 64-bit) game process.
b. The “LunaHost” process (GUI/CLI) that receives extracted text, manages plugins, and forwards text to translators or other extensions.

##### Top-Level Components
- **LunaHook (injectable module):**
- Core hooking engine (MinHook, YY-Thunks)
- Engine backends (`engine32/`, `engine64/`, `enginecollection32.cpp`, `enginecollection64.cpp`) for dozens of game scripting systems (KiriKiri, Ren’Py, Unity/Mono, Unreal, PPSSPP, etc.)
- Utilities (`util/` subfolders: disassembler, dynamic SJIS codec, memory debugger, string filters, etc.)
- Hook control and finder (`hookfinder.cc`, `enginecontrol.cpp`)
- Resource files and language headers (`Lang/`)
- **LunaHost (host process):**
- GUI application (Qt-based): main window, plugin manager, config helper, text thread, HTTP helper
- Plugins (`GUI/Plugin/extensions/`): translation wrappers (Google, DeepL, Bing, Systran, Papago), filters (regex, markup, repeat removal), dev tools, network interceptors, clipboard helpers, etc.
- CLI and DLL host modes (`LunaHostCLI.cpp`, `LunaHostDll.cpp`)
- **Build & Packaging:**
- `CMakeLists.txt` at root plus subfolder CMake files
- `build.py` and `.bat` scripts for 32/64-bit builds, XP compatibility
- Third-party libs under `libs/` (MinHook, YY-Thunks, nlohmann/json, yapi.hpp)

##### Core Interactions and Data Flow
- **Injection & Hooking:**
1. User launches LunaHost or triggers injection via plugin.
2. LunaHook DLL is injected into the game process (Win32 or x64).
3. Hook engine identifies the game’s scripting engine (via `enginefinder`) and loads the corresponding backend.
4. When the game calls text-rendering or text-loading APIs, the hook intercepts those calls, extracts text buffers.
- **IPC to Host:**
- Extracted text is packaged (possibly JSON via nlohmann/json) and sent over an IPC channel (e.g., named pipe or shared memory) to the LunaHost process.
- LunaHost’s `textthread.cpp` listens for incoming messages.
- **Plugin Pipeline:**
- LunaHost receives raw text → pushes it into a locked queue → Plugin Manager invokes each enabled extension in series.
- Extensions can transform text (filters), send to external translation APIs (HTTP), modify formatting, copy to clipboard, or display in dev tools.
- **UI Rendering & User Action:**
- Processed text is displayed in the GUI window.
- User actions (enable/disable plugin, copy, manual edit) flow back through the host, not directly into the game.

##### Architectural Patterns & Principles
- **Modular Backends:** Each game engine backend is its own component (source & header pair) loaded conditionally.
- **Plugin Architecture:** Host uses Qt plugin system to load extensions at runtime, enabling ease of adding new translation or filter modules.
- **Separation of Concerns:**
- Hook DLL isolates low-level process memory manipulation and instruction patching.
- Host process handles all user-facing logic and external network calls.
- **Cross-Architecture Support:** Two build targets for 32-bit and 64-bit, but most code is shared via `enginecollection` files and conditional compilation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Processes
    Game["Target Game Process"]:::process
    subgraph "LunaHook DLL" 
        direction TB
        HookMain["main.cc /.h"]:::hook
        CoreEngine["Core Hooking Engine"]:::hook
        Engine32["Engine Backends (32-bit)"]:::hook
        Engine64["Engine Backends (64-bit)"]:::hook
        EngineCol32["enginecollection32.cpp"]:::hook
        EngineCol64["enginecollection64.cpp"]:::hook
        HookControl["hookfinder.cc /.h<br/>enginecontrol.cpp"]:::hook
        Utils["Utilities (util/)"]:::hook
        LangRes["Resource Files & Language Headers (Lang/)"]:::hook
    end

    IPC["IPC Channel<br/>(Named Pipe / Shared Memory)"]:::ipc

    subgraph "LunaHost Process" 
        direction TB
        subgraph "GUI Core" 
            GUICore["Qt-based GUI Core"]:::host
            ConfigHelper["confighelper.cpp /.h"]:::host
            PluginMgr["pluginmanager.cpp /.h"]:::host
            QtLoader["Plugin Loader (QtLoader.cpp)"]:::host
            QtUtils["QtUtils.cmake"]:::host
        end
        TextThread["textthread.cpp /.h"]:::host
        HTTPHelper["http.hpp"]:::host
        LockedQueue["lockedqueue.hpp"]:::host
        subgraph "Plugin Extensions" 
            direction TB
            Extensions["extensions/"]:::plugin
        end
        CLIHost["LunaHostCLI.cpp"]:::host
        DLLHost["LunaHostDll.cpp"]:::host
    end

    subgraph "Build & Packaging" 
        CMakeRoot["CMakeLists.txt (root)"]:::build
        CMakeHook["LunaHook/CMakeLists.txt"]:::build
        CMakeHost["LunaHost/CMakeLists.txt"]:::build
        BuildScript["build.py & .bat scripts"]:::build
    end

    subgraph "Third-Party Libraries"
        MinHook["MinHook"]:::lib
        YYThunk["YY-Thunks"]:::lib
        JSONLib["nlohmann/json.hpp"]:::lib
        YAPI["yapi.hpp"]:::lib
    end

    %% Data Flow
    Game -->|Injection| HookMain
    HookMain -->|loads| CoreEngine
    CoreEngine -->|loads| Engine32
    CoreEngine -->|loads| Engine64
    CoreEngine -->|conditional compile| EngineCol32
    CoreEngine -->|conditional compile| EngineCol64
    CoreEngine --> HookControl
    CoreEngine --> Utils
    CoreEngine --> LangRes
    HookMain -->|intercept API calls| HookControl
    HookControl -->|extract text| IPC
    IPC -->|JSON over pipe| TextThread
    TextThread --> LockedQueue
    LockedQueue --> PluginMgr
    PluginMgr --> Extensions
    Extensions -->|transform/send| HTTPHelper
    Extensions -->|output| GUICore
    GUICore -->|user actions| PluginMgr
    CLIHost -.->|CLI mode| TextThread
    DLLHost -.->|DLL mode| TextThread

    %% Build & Packaging Flow
    CMakeRoot --> CMakeHook
    CMakeRoot --> CMakeHost
    CMakeHook --> BuildScript
    CMakeHost --> BuildScript
    BuildScript -->|produces| HookMain
    BuildScript -->|produces| LunaHost

    %% Third-Party libs usage
    CoreEngine --> MinHook
    CoreEngine --> YYThunk
    HookMain --> JSONLib
    HookMain --> YAPI
    TextThread --> JSONLib

    %% Styles
    classDef process fill:#f9f,stroke:#333,stroke-width:1px
    classDef hook fill:#eee,stroke:#666,stroke-width:1px
    classDef host fill:#def,stroke:#036,stroke-width:1px
    classDef plugin fill:#cfc,stroke:#484,stroke-width:1px
    classDef ipc fill:#ffd,stroke:#aa0,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#fdd,stroke:#a00,stroke-width:1px
    classDef lib fill:#ddf,stroke:#00a,stroke-width:1px

    %% Click Events
    click HookMain "https://github.com/stackboom/lunahook/blob/main/LunaHook/main.cc"
    click HookMain "https://github.com/stackboom/lunahook/blob/main/LunaHook/main.h"
    click CoreEngine "https://github.com/stackboom/lunahook/tree/main/libs/minhook/"
    click CoreEngine "https://github.com/stackboom/lunahook/tree/main/libs/YY-Thunks-1.0.7-Binary/"
    click Engine32 "https://github.com/stackboom/lunahook/tree/main/LunaHook/engine32/"
    click Engine64 "https://github.com/stackboom/lunahook/tree/main/LunaHook/engine64/"
    click EngineCol32 "https://github.com/stackboom/lunahook/blob/main/LunaHook/enginecollection32.cpp"
    click EngineCol64 "https://github.com/stackboom/lunahook/blob/main/LunaHook/enginecollection64.cpp"
    click HookControl "https://github.com/stackboom/lunahook/blob/main/LunaHook/hookfinder.cc"
    click HookControl "https://github.com/stackboom/lunahook/blob/main/LunaHook/hookfinder.h"
    click HookControl "https://github.com/stackboom/lunahook/blob/main/LunaHook/enginecontrol.cpp"
    click Utils "https://github.com/stackboom/lunahook/tree/main/LunaHook/util/"
    click LangRes "https://github.com/stackboom/lunahook/tree/main/Lang/"
    click GUICore "https://github.com/stackboom/lunahook/tree/main/LunaHost/GUI/"
    click PluginMgr "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/pluginmanager.cpp"
    click PluginMgr "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/pluginmanager.h"
    click ConfigHelper "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/confighelper.cpp"
    click ConfigHelper "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/confighelper.h"
    click TextThread "https://github.com/stackboom/lunahook/blob/main/LunaHost/textthread.cpp"
    click TextThread "https://github.com/stackboom/lunahook/blob/main/LunaHost/textthread.h"
    click HTTPHelper "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/http.hpp"
    click LockedQueue "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/lockedqueue.hpp"
    click Extensions "https://github.com/stackboom/lunahook/tree/main/LunaHost/GUI/Plugin/extensions/"
    click QtLoader "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/Plugin/QtLoader.cpp"
    click QtUtils "https://github.com/stackboom/lunahook/blob/main/LunaHost/GUI/Plugin/QtUtils.cmake"
    click CLIHost "https://github.com/stackboom/lunahook/blob/main/LunaHost/LunaHostCLI.cpp"
    click DLLHost "https://github.com/stackboom/lunahook/blob/main/LunaHost/LunaHostDll.cpp"
    click CMakeRoot "https://github.com/stackboom/lunahook/blob/main/CMakeLists.txt"
    click CMakeHook "https://github.com/stackboom/lunahook/blob/main/LunaHook/CMakeLists.txt"
    click CMakeHost "https://github.com/stackboom/lunahook/blob/main/LunaHost/CMakeLists.txt"
    click BuildScript "https://github.com/stackboom/lunahook/blob/main/build.py"
    click MinHook "https://github.com/stackboom/lunahook/tree/main/libs/minhook/"
    click YYThunk "https://github.com/stackboom/lunahook/tree/main/libs/YY-Thunks-1.0.7-Binary/"
    click JSONLib "https://github.com/stackboom/lunahook/blob/main/libs/nlohmann/json.hpp"
    click YAPI "https://github.com/stackboom/lunahook/blob/main/libs/yapi.hpp"
```
