How minimal-c/rollcageextractor works
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