# jayveer/gcx architecture

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

- Interactive diagram: https://gitdiagram.com/jayveer/gcx
- Repository: https://github.com/jayveer/gcx

## Overview

##### Project type and purpose
- Gcx is a native C++ command-line tool for decompiling GCX binary script files used by Metal Gear Solid games (MGS3+ and MGS4).
- It reads GCX files, optionally exports embedded resources, applies a dictionary for hashed strings, formats output, and emits Game Command Language (GCL) scripts.

##### File structure
Top-level artifacts:
- main.cpp – entry point
- gcx.sln/vcxproj – Visual Studio solution and project files
- .gitignore, README.md
Modular directories:
- interface/cli – parses command-line options, presents usage, invokes core logic
- decompiler – core GCX parsing and bytecode→GCL translation
- dictionary – loads and queries a commands.txt dictionary for resolving hashed identifiers
- indentation – post-processing formatter for pretty-printing decompiled scripts
- mgs/common – shared utilities (file I/O, hash algorithms) and game-specific constants (strcode, game parameters)
- mgs/script – high-level orchestration of decompilation for specific game versions (gcx.cpp/h)

##### README insights
- Describes supported game versions, default modes, options (-MGS3, ‑MGS4, ‑res).
- Explains GCL structure, resource extraction, hash algorithm, encoding (EUC-JP, UTF-8).
- Mentions optional use of dictionary and formatting fixes as TODOs.

- GCX Parser & Decompiler (decompiler module) – green
- Script Orchestrator (mgs/script/gcx) – light green
- Game-Specific Logic (mgs/common/game, strcode) – teal
3. Dictionary Service (dictionary module) – yellow
4. Formatter (indentation module) – orange
5. File I/O & Utilities (mgs/common/fileutil) – gray
6. Output Sink – terminal/stdout files (decompiled .gcl, resource folders) – white
1. User → CLI Layer: command-line args (-mgs3/-mgs4, ‑res, input path)
2. CLI Layer → Core Engine: invokes Decompile(input, options)
3. Core Engine → File I/O: read raw GCX file
4. Core Engine → Game-Specific Logic: apply hash decoding, version constants
5. Core Engine → Dictionary Service: lookup hashed commands/strings (optional)
6. Core Engine → Script Orchestrator: assemble decompiled tokens into GCL AST
7. Script Orchestrator → Formatter: pretty-print AST to text
8. Formatter → Output Sink: write .gcl script
9. Core Engine → Output Sink (if ‑res): export binary resources
c. Architectural patterns and principles:
- Layered architecture – CLI → Core → Output
- Single Responsibility per module (parsing, dictionary, formatting)
- Plug-in style extensibility for game versions (mgs/script + flags)
- Clear separation of concerns: parsing vs. formatting vs. resource extraction
d. Key technologies/frameworks:
- C++17 (or later) – core language
- Visual Studio solution/project (.sln, .vcxproj) – build system
- Standard Library for I/O, file handling

##### Essential details
- Dictionary file as an external dependency
- Two output channels: decompiled script and binary resources
- Encoding differences (EUC-JP vs. UTF-8) as a note on the Script Orchestrator

## Diagram (Mermaid)

```mermaid
flowchart TD
    user((User)):::user
    subgraph "CLI Layer"
        CLI_CPP["cli.cpp"]:::cli
        CLI_H["cli.h"]:::cli
    end
    subgraph "Core Engine"
       subgraph "GCX Parser & Decompiler"
           DECOMP_CPP["decompiler.cpp"]:::core
           DECOMP_H["decompiler.h"]:::core
       end
       subgraph "Script Orchestrator"
           GCX_CPP["gcx.cpp"]:::core
           GCX_H["gcx.h"]:::core
       end
       subgraph "Game-Specific Logic"
           GAME_CPP["game.cpp"]:::core
           GAME_H["game.h"]:::core
           STRCODE_H["strcode.h"]:::core
       end
    end
    subgraph "Dictionary Service"
         DICT_CPP["dictionary.cpp"]:::dict
         DICT_H["dictionary.h"]:::dict
    end
    subgraph "Formatter"
         IND_CPP["indentation.cpp"]:::fmt
         IND_H["indentation.h"]:::fmt
    end
    subgraph "Utilities"
         FILEUTIL_H["fileutil.h"]:::util
    end
    INPUT_GCX[(GCX File)]:::datastore
    DICTFILE[(commands.txt)]:::datastore
    OUTPUT_SCRIPT((.gcl Script)):::output
    OUTPUT_RES((Resources)):::output
    PROJECT_META["README.md\n.gitignore"]:::meta
    BUILD_CFG["gcx.sln\nvcxproj\nvcxproj.filters\nvcxproj.user"]:::meta

    user -->|"args (-MGS3/-MGS4, -res)"| CLI_CPP
    CLI_CPP -->|"Decompile(input,options)"| DECOMP_CPP
    DECOMP_CPP -->|"read file"| INPUT_GCX
    DECOMP_CPP -->|"use utils"| FILEUTIL_H
    DECOMP_CPP -->|"apply version logic"| GAME_CPP
    DECOMP_CPP -.->|"optional lookup"| DICT_CPP
    DECOMP_CPP -->|"emit tokens"| GCX_CPP
    GCX_CPP -->|"format AST"| IND_CPP
    IND_CPP -->|"write script"| OUTPUT_SCRIPT
    DECOMP_CPP -.->|"export resources"| OUTPUT_RES

    click CLI_CPP "https://github.com/jayveer/gcx/blob/master/interface/cli/cli.cpp"
    click CLI_H "https://github.com/jayveer/gcx/blob/master/interface/cli/cli.h"
    click DECOMP_CPP "https://github.com/jayveer/gcx/blob/master/decompiler/decompiler.cpp"
    click DECOMP_H "https://github.com/jayveer/gcx/blob/master/decompiler/decompiler.h"
    click GCX_CPP "https://github.com/jayveer/gcx/blob/master/mgs/script/gcx.cpp"
    click GCX_H "https://github.com/jayveer/gcx/blob/master/mgs/script/gcx.h"
    click DICT_CPP "https://github.com/jayveer/gcx/blob/master/dictionary/dictionary.cpp"
    click DICT_H "https://github.com/jayveer/gcx/blob/master/dictionary/dictionary.h"
    click IND_CPP "https://github.com/jayveer/gcx/blob/master/indentation/indentation.cpp"
    click IND_H "https://github.com/jayveer/gcx/blob/master/indentation/indentation.h"
    click GAME_CPP "https://github.com/jayveer/gcx/blob/master/mgs/common/game/game.cpp"
    click GAME_H "https://github.com/jayveer/gcx/blob/master/mgs/common/game/game.h"
    click STRCODE_H "https://github.com/jayveer/gcx/blob/master/mgs/common/strcode.h"
    click FILEUTIL_H "https://github.com/jayveer/gcx/blob/master/mgs/common/fileutil.h"
    click BUILD_CFG "https://github.com/jayveer/gcx/blob/master/gcx.sln"
    click PROJECT_META "https://github.com/jayveer/gcx/blob/master/README.md"

    classDef user fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef cli fill:#0000FF,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef dict fill:#FFFF00,stroke:#000,stroke-width:1px
    classDef fmt fill:#FFA500,stroke:#000,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5
    classDef output fill:#FFFFFF,stroke:#000,stroke-width:1px
    classDef meta fill:#F0F0F0,stroke:#000,stroke-width:1px
```
