# fuerchter/rayman-ps1-decomp architecture

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

- Interactive diagram: https://gitdiagram.com/fuerchter/rayman-ps1-decomp
- Repository: https://github.com/fuerchter/rayman-ps1-decomp

## Overview

##### Main components
a. External Input
- PS1 Game Disc Image (SLUS-000.05)
b. Extraction & Data Layer
- mk-splat build scripts (mk-splat.mk, mk-nugget.mk)
- splat tool (extracts segments into src/data and include/data headers)
c. Source Code Modules
- Header files (include/) matching each module
- src/data/* (auto-extracted data C files)
d. Decompilation & Matching Tools
- m2c, m2ctx.py, maspsx, asm-differ, decomp-permuter, permuter_settings.toml
- diff_settings.py (configures matching rules)
e. Build Toolchain
- PSX cross-compiler (gcc-2.5.7 cc1 under tools/gcc-2.5.7/)
- cpp-mipsel-linux-gnu / binutils-mipsel-linux-gnu
- psyq libraries (tools/psyq-3.0-converted)
f. Linker & Packaging
- Link object files into final PSX executable (.exe/EXE)
- Embed headers, data segments, produce binary matching original CRC
g. Continuous Integration
- .github/workflows/build.yml (GitHub Actions to run make, sha1 check)

##### Relationships and data flows
– Tools inspect compiled objects vs original ASM to drive matching

##### Architectural/design principles
- Modular partitioning by game subsystem (collision, rendering, input, audio, world)
- Data-driven decompilation: raw binary segments → auto-gen data C → build
- Iterative compile-compare cycle with decomp tools until match
- Separation of concerns:
– Extraction layer vs source layer vs decomp-tool layer vs build layer

##### Call out key technologies
- PSX cross-compilation (gcc-2.5.7, psyq)
- splat for extraction/repacking
- m2c & m2ctx for context-based C generation
- asm-differ & decomp-permuter for diff-based matching
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Input"
        Ext["PS1 Disc Image (SLUS-000.05)"]:::external
    end
    click Ext "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/slus-000.05.yaml"
    click Ext "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/slus-000.05.sha1"

    subgraph "Extraction & Data Layer"
        MS["mk-splat.mk"]:::data
        MN["mk-nugget.mk"]:::data
        Nug["Extraction Tool: tools/nugget"]:::data
        DataC["Auto-extracted Data (src/data, include/)"]:::data
    end
    click MS "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/mk-splat.mk"
    click MN "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/mk-nugget.mk"
    click Nug "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/nugget"
    click DataC "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/data/"
    click DataC "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/"

    Ext --> MS
    Ext --> MN
    MS --> Nug
    MN --> Nug
    Nug --> DataC

    subgraph "Source Code Modules"
        Coll["Collision Module"]:::source
        Draw["Draw Module"]:::source
        Obj["Obj Module"]:::source
        Ray["Ray Module"]:::source
        Menu["Menu Module"]:::source
        Demo["Demo Modules"]:::source
    end
    click Coll "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/collision/"
    click Coll "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/collision/"
    click Draw "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/draw/"
    click Draw "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/draw/"
    click Obj "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/obj/"
    click Obj "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/obj/"
    click Ray "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/ray/"
    click Ray "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/ray/"
    click Menu "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/src/menu/"
    click Menu "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/menu/"
    click Demo "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/src/demo_*.c"
    click Demo "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/include/demo_*.h"

    DataC --> Coll
    DataC --> Draw
    DataC --> Obj
    DataC --> Ray
    DataC --> Menu
    DataC --> Demo

    subgraph "Decompilation & Matching Tools"
        M2C["m2c"]:::tools
        M2Ctx["m2ctx.py"]:::tools
        MAS["maspsx"]:::tools
        DiffASM["asm-differ"]:::tools
        Perm["decomp-permuter"]:::tools
        PermSet["permuter_settings.toml"]:::tools
        DiffCfg["diff_settings.py"]:::tools
    end
    click M2C "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/m2c"
    click M2Ctx "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/tools/m2ctx.py"
    click MAS "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/maspsx"
    click DiffASM "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/asm-differ"
    click Perm "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/decomp-permuter"
    click PermSet "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/tools/permuter_settings.toml"
    click DiffCfg "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/diff_settings.py"

    Coll --> M2C
    Draw --> M2C
    Obj --> M2C
    Ray --> M2C
    Menu --> M2C
    Demo --> M2C
    DataC --> M2C

    M2Ctx --> M2C
    MAS --> M2C
    DiffASM --> M2C
    Perm --> M2C
    PermSet --> Perm
    DiffCfg --> M2C

    M2C --> Coll
    M2C --> Draw
    M2C --> Obj
    M2C --> Ray
    M2C --> Menu
    M2C --> Demo
    M2C --> DataC

    subgraph "Build Toolchain & Linker"
        Libs["PSX Libraries (psyq & tools/psyq-3.0-converted)"]:::toolchain
        CC["Compiler"]:::toolchain
        LD["Linker"]:::toolchain
    end
    click Libs "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/include/psyq_3_0_missing/"
    click Libs "https://github.com/fuerchter/rayman-ps1-decomp/tree/main/tools/psyq-3.0-converted/"

    Coll --> CC
    Draw --> CC
    Obj --> CC
    Ray --> CC
    Menu --> CC
    Demo --> CC
    DataC --> CC
    CC --> LD
    Libs --> LD

    subgraph "Output"
        BIN["Final PSX Binary"]:::output
    end
    LD --> BIN

    subgraph "Continuous Integration"
        CI["GitHub Actions CI"]:::ci
    end
    click CI "https://github.com/fuerchter/rayman-ps1-decomp/blob/main/.github/workflows/build.yml"
    CI --> Ext
    CI --> DataC
    CI --> Coll

    classDef external fill:#e0f7fa,stroke:#00838f,color:#006064;
    classDef data fill:#e8f5e9,stroke:#388e3c,color:#1b5e20;
    classDef source fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef tools fill:#ffe0b2,stroke:#f57c00,color:#e65100;
    classDef toolchain fill:#d1c4e9,stroke:#7e57c2,color:#4a148c;
    classDef output fill:#ffccbc,stroke:#d84315,color:#b71c1c;
    classDef ci fill:#eeeeee,stroke:#9e9e9e,color:#424242;
```
