Add comprehensive README documentation
Document: - Project overview and features - Supported game formats (CoD, Asura Engine) - Project structure - Build instructions - XScript language syntax and examples - Usage guide - How to add new format support - Dependencies and acknowledgments 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
64db5a19ed
commit
68d749ee63
148
README.md
148
README.md
@ -1 +1,147 @@
|
|||||||
[Old Demo Gifs]
|
# XPlor
|
||||||
|
|
||||||
|
A Qt-based binary file format explorer and parser using a custom domain-specific language (XScript) for defining file structures.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
XPlor is a desktop application designed to explore, parse, and visualize binary file formats from video games. It uses XScript, a custom DSL (Domain-Specific Language), to define how binary files should be interpreted, making it easy to add support for new file formats without modifying the core application code.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **XScript DSL**: Define binary file structures using a readable, declarative scripting language
|
||||||
|
- **Dynamic File Type Detection**: Automatically identifies file types based on extension and magic bytes
|
||||||
|
- **Tree-Based UI**: Hierarchical view of parsed file structures
|
||||||
|
- **Image Preview**: Built-in preview for texture assets (TGA, DXT, Xbox 360 formats)
|
||||||
|
- **Extensible**: Add support for new file formats by creating XScript definition files
|
||||||
|
- **Multi-Platform Support**: Parse files from PC, Xbox 360, PS3, and other platforms
|
||||||
|
|
||||||
|
## Supported Games/Formats
|
||||||
|
|
||||||
|
### Call of Duty Series
|
||||||
|
- Fast Files (`.ff`)
|
||||||
|
- Various asset types: materials, textures, models, sounds, menus, weapons, etc.
|
||||||
|
|
||||||
|
### Rebellion Asura Engine (Sniper Elite V2)
|
||||||
|
- Archive files (`.asrbe`, `.tsBE`, `.mapBE`, etc.)
|
||||||
|
- Texture archives
|
||||||
|
- Various chunk types
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
XPlor/
|
||||||
|
├── app/ # Main application
|
||||||
|
│ ├── mainwindow.* # Main window UI and logic
|
||||||
|
│ ├── imagepreviewwidget.* # Texture preview widget
|
||||||
|
│ └── xtreewidget.* # Tree view components
|
||||||
|
├── libs/
|
||||||
|
│ ├── core/ # Core utilities and managers
|
||||||
|
│ ├── dsl/ # XScript DSL engine
|
||||||
|
│ │ ├── lexer.* # Tokenizer
|
||||||
|
│ │ ├── parser.* # AST parser
|
||||||
|
│ │ ├── interpreter.* # Runtime interpreter
|
||||||
|
│ │ └── typeregistry.* # Type management
|
||||||
|
│ ├── compression/ # LZO compression support
|
||||||
|
│ └── encryption/ # Salsa20, SHA1 encryption
|
||||||
|
├── definitions/ # XScript format definitions
|
||||||
|
│ ├── cod/ # Call of Duty formats
|
||||||
|
│ └── asura/ # Asura Engine formats
|
||||||
|
├── tools/ # Command-line utilities
|
||||||
|
└── third_party/ # External dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- Qt 6.x (tested with 6.10.0)
|
||||||
|
- MSVC 2022 (Windows)
|
||||||
|
- CMake or qmake
|
||||||
|
|
||||||
|
### Build Steps
|
||||||
|
|
||||||
|
1. Open `XPlor.pro` in Qt Creator
|
||||||
|
2. Configure the project for your Qt kit
|
||||||
|
3. Build the project
|
||||||
|
|
||||||
|
Or from command line:
|
||||||
|
```bash
|
||||||
|
qmake XPlor.pro
|
||||||
|
make # or nmake/jom on Windows
|
||||||
|
```
|
||||||
|
|
||||||
|
## XScript Language
|
||||||
|
|
||||||
|
XScript is a domain-specific language for defining binary file structures. Here's an example:
|
||||||
|
|
||||||
|
```xscript
|
||||||
|
type fastfile [root, display="Fast File"] byteorder LE
|
||||||
|
{
|
||||||
|
criteria {
|
||||||
|
require _ext == "ff";
|
||||||
|
}
|
||||||
|
|
||||||
|
// Read header
|
||||||
|
magic = ascii(read(8));
|
||||||
|
version = u32;
|
||||||
|
|
||||||
|
if (version == 5) {
|
||||||
|
platform = "PC";
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse nested structures
|
||||||
|
asset_count = u32;
|
||||||
|
repeat asset_count {
|
||||||
|
asset = parse_here("asset");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Type definitions** with byte order specification
|
||||||
|
- **Criteria blocks** for file type detection
|
||||||
|
- **Built-in functions**: `read()`, `u32`, `ascii()`, `cstring()`, etc.
|
||||||
|
- **Control flow**: `if/else`, `while`, `repeat`, `for` loops
|
||||||
|
- **Pipeline syntax**: `data | decompress("zlib") | parse("asset")`
|
||||||
|
- **UI annotations**: `[ui, display="Name", readonly]`
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
1. Launch XPlor
|
||||||
|
2. Drag and drop a supported file onto the window, or use File > Open
|
||||||
|
3. The file will be parsed and displayed in a tree structure
|
||||||
|
4. Click on tree items to view their properties
|
||||||
|
5. For texture assets, a preview will be shown
|
||||||
|
|
||||||
|
## Adding New Format Support
|
||||||
|
|
||||||
|
1. Create a new `.xscript` file in `definitions/`
|
||||||
|
2. Define your root type with `[root]` attribute
|
||||||
|
3. Add criteria for file detection
|
||||||
|
4. Define the binary structure using XScript syntax
|
||||||
|
5. Restart XPlor to load the new definition
|
||||||
|
|
||||||
|
## Libraries
|
||||||
|
|
||||||
|
- **Qt 6**: UI framework
|
||||||
|
- **miniLZO**: LZO compression
|
||||||
|
- **Salsa20**: Stream cipher encryption
|
||||||
|
- **zlib**: Deflate compression
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is for educational and research purposes.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! Please feel free to submit pull requests for:
|
||||||
|
- New file format definitions
|
||||||
|
- Bug fixes
|
||||||
|
- Feature improvements
|
||||||
|
- Documentation
|
||||||
|
|
||||||
|
## Acknowledgments
|
||||||
|
|
||||||
|
- Xbox 360 SDK documentation for texture untiling algorithms
|
||||||
|
- Various game modding communities for format documentation
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user