XPlor/README.md

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:

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:

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