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:
```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