# minimal-c/rollcageextractor architecture

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

- Interactive diagram: https://gitdiagram.com/minimal-c/rollcageextractor
- Repository: https://github.com/minimal-c/rollcageextractor

## Overview

##### Project type and purpose
- This is a command-line tool (CLI) written in Rust ("rollcage-extractor") whose sole purpose is to parse and extract game assets (textures, models, tracks) from Rollcage IDX/IMG data files.
- It consists of:
- A binary crate (`src/main.rs`) implementing the CLI interface.
- A library crate (`Rollcage-File-Parser/`) containing parsing logic and per-format decoders.

##### High-level file-structure analysis
- Top level:
- Cargo.toml (workspace/member crates)
- `src/main.rs` (the executable entrypoint)
- `Rollcage-File-Parser/` (Rust library crate)
- Inside the library crate:
- `src/lib.rs` (public API for parsing pipelines)
- `src/file_formats/` with modules: `bitmap.rs`, `btp.rs`, `gfxm.rs`, `gt.rs`, `idx.rs`, `modl.rs`
- The CLI uses `clap` (for flags, args) to accept an IDX file (and optional IMG), forwards them into the parser library, and then writes extracted assets (PNG, raw models, tracks) to disk.

##### Key README insights
- Usage pattern (`rollcage-extractor.exe [OPTIONS] <idxFile> [imgFile]`)
- Automatic BTP→PNG conversion; other formats currently spit out raw data.
- Tested on Windows & Linux.

##### Main components & interactions
a. Components:
1) CLI Frontend (main.rs + clap)
2) Parser Library (“RollcageFileParser” crate)
- IDX Loader (`file_formats/idx.rs`)
- IMG Loader (if separate)
- Format Decoders:
- BTP Decoder (`btp.rs`)
- Bitmap (wrapper/helper) (`bitmap.rs`)
- GFXM, GT, MODL decoders
3) File I/O layer (Rust std::fs)
4) Image Writer (uses `image` crate to encode PNG)
5) Output Filesystem (folder on disk)
b. Relationships & data flow:
- User invokes CLI → CLI Frontend parses args → invokes Parser API
- Parser API opens IDX file → streams records to appropriate format decoder → each decoder returns in-memory asset object
- Asset objects passed to Output Writer:
– BTP → PNG via Image Writer
– Other formats → raw dumps or stub output
- Files written to Output directory
c. Architectural patterns & design principles
- Separation of concerns: CLI logic vs. parsing logic vs. I/O
- Modular decoders: one module per file format for maintainability
- Single binary linking a reusable library crate
d. Key technologies/frameworks/libraries
- Rust 2021 edition / Cargo
- clap (for CLI parsing)
- image or similar (for PNG encoding)
- std::fs for filesystem I/O

## Diagram (Mermaid)

```mermaid
graph TB
    %% User and CLI
    UserTerminal("User Terminal"):::external
    CLIFrontend("CLI Frontend\n(src/main.rs)"):::internal
    UserTerminal -->|"invokes"| CLIFrontend
    CLIFrontend -->|"parses args"| ParserAPI
    CLIFrontend -->|"uses"| ClapLib

    %% External Dependencies
    ClapLib("clap (CLI Parser)"):::thirdparty
    ImageWriter("Image Writer\n(image crate)"):::thirdparty
    FS("File I/O\n(std::fs)"):::thirdparty

    %% Input and Output
    InputFiles("Input Files\n(IDX/IMG)"):::storage
    OutputDir("Output Directory"):::output

    InputFiles -->|"streams records"| ParserAPI
    ParserAPI -->|"writes files"| OutputDir

    %% Library Subgraph
    subgraph "Rollcage-File-Parser Library"
        ParserAPI("Parser Library API\n(src/lib.rs)"):::internal
        subgraph "FileFormats Modules"
            IDXLoader("IDX Loader\n(idx.rs)"):::internal
            BTPDecoder("BTP Decoder\n(btp.rs)"):::internal
            BitmapHelper("Bitmap Helper\n(bitmap.rs)"):::internal
            GFXMDecoder("GFXM Decoder\n(gfxm.rs)"):::internal
            GTDecoder("GT Decoder\n(gt.rs)"):::internal
            MODLDecoder("MODL Decoder\n(modl.rs)"):::internal
        end
        ParserAPI -->|"dispatches to"| IDXLoader
        ParserAPI -->|"dispatches to"| BTPDecoder
        ParserAPI -->|"dispatches to"| BitmapHelper
        ParserAPI -->|"dispatches to"| GFXMDecoder
        ParserAPI -->|"dispatches to"| GTDecoder
        ParserAPI -->|"dispatches to"| MODLDecoder

        %% I/O and Image Writer usage
        BTPDecoder -->|"encodes PNG"| ImageWriter
        IDXLoader -->|"uses FS"| FS
        BTPDecoder -->|"uses FS"| FS
        BitmapHelper -->|"uses FS"| FS
        GFXMDecoder -->|"uses FS"| FS
        GTDecoder -->|"uses FS"| FS
        MODLDecoder -->|"uses FS"| FS
    end

    %% Click Events
    click CLIFrontend "https://github.com/minimal-c/rollcageextractor/blob/main/src/main.rs"
    click ParserAPI "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/lib.rs"
    click ClapLib "https://github.com/minimal-c/rollcageextractor/blob/main/Cargo.toml"
    click IDXLoader "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/idx.rs"
    click BTPDecoder "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/btp.rs"
    click BitmapHelper "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/bitmap.rs"
    click GFXMDecoder "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/gfxm.rs"
    click GTDecoder "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/gt.rs"
    click MODLDecoder "https://github.com/minimal-c/rollcageextractor/blob/main/Rollcage-File-Parser/src/file_formats/modl.rs"
    click FS "https://github.com/minimal-c/rollcageextractor/blob/main/Cargo.toml"
    click ImageWriter "https://github.com/minimal-c/rollcageextractor/blob/main/Cargo.toml"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#004080,stroke-width:1px
    classDef thirdparty fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#FDEBD0,stroke:#A04000,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#707070,stroke-width:1px,stroke-dasharray: 2 2
    classDef output fill:#FFF4C1,stroke:#D4A017,stroke-width:1px
    class storage cylinder
    class output folder
```
