cascette-rs

Rust implementation of Blizzard's NGDP (Next Generation Distribution Pipeline) for World of Warcraft emulation.

🎯 Project Status

Current Version: 0.4.3

Core Components

Component	Version	Status	Description
ngdp-bpsv	0.4.3	✅ Stable	BPSV parser/writer for NGDP formats
ribbit-client	0.4.3	✅ Stable	Ribbit protocol client with signature verification
tact-client	0.4.3	✅ Stable	TACT HTTP client with retry logic and batching
tact-parser	0.4.3	✅ Stable	TACT file format parser (encoding, install, etc.)
ngdp-cdn	0.4.3	✅ Stable	CDN client with fallback hosts and connection pooling
ngdp-cache	0.4.3	✅ Stable	Comprehensive caching layer with LRU eviction
blte	0.4.3	✅ Stable	BLTE decompression with memory pooling
ngdp-crypto	0.4.3	✅ Stable	Modern encryption with Salsa20 and key service
ngdp-client	0.4.3	✅ Stable	CLI tool for NGDP operations
casc-storage	0.4.3	🚧 Beta	CASC storage implementation (in development)
ngdp-patch	0.4.3	🚧 Beta	Patch file support (in development)

Implementation Progress

• ✅ Version Discovery: HTTP-first approach with HTTPS endpoints, Ribbit fallback for compatibility
• ✅ TACT Protocol: HTTP/HTTPS clients for version and CDN queries with retry logic
• ✅ BPSV Format: Parser and builder with zero-copy optimizations
• ✅ TACT Parsers: Support for encoding, install, download, size, build config, TVFS
• ✅ BLTE Decompression: Compression modes (ARC4/Frame deprecated in v0.4.0)
• ✅ Encryption: Salsa20 cipher with key management (ARC4 deprecated)
• ✅ CDN Operations: Parallel downloads, streaming, retry logic, rate limiting
• ✅ Caching: HTTP-first caching with fallbacks and TTL support
• ✅ Install Command: Client installation with .build.info generation for restoration
• ✅ Build Config: Uncompressed handling and download order (encoding before manifests)
• 🚧 CASC Storage: Local storage implementation (in development)
• 🔄 TVFS: Parser implemented, needs real-world data testing

🚀 Quick Start

Library Usage

Add to your Cargo.toml:

[dependencies]
ribbit-client = "0.4.3"
ngdp-bpsv = "0.4.3"
tact-parser = "0.4.3"
blte = "0.4.3"
ngdp-crypto = "0.4.3"

Basic example (HTTP-first approach):

use ngdp_cache::hybrid_version_client::HybridVersionClient;
use ribbit_client::Region;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a hybrid client (HTTP primary, Ribbit fallback)
    let client = HybridVersionClient::new(Region::US).await?;

    // Request WoW versions with HTTPS endpoints
    let versions = client.get_product_versions("wow").await?;

    // Print version information
    for entry in &versions.entries {
        println!(
            "{}: {} (build {})",
            entry.region, entry.versions_name, entry.build_id
        );
    }

    Ok(())
}

🧪 Testing with Real WoW Data

Many tests and examples can work with real WoW installation data for comprehensive testing. This is optional - all tests will skip gracefully if no data is available.

Setup Environment Variables

Set environment variables pointing to your WoW installation Data directories:

# Classic Era (1.15.x)
export WOW_CLASSIC_ERA_DATA="$HOME/Downloads/wow/1.15.2.55140.windows-win64/Data"

# Classic with expansions
export WOW_CLASSIC_DATA="$HOME/Downloads/wow/classic/Data"

# Retail (current)
export WOW_RETAIL_DATA="$HOME/Downloads/wow/retail/Data"

Valid Data Directory Structure

The Data directory should contain CASC structure:

Data/
├── data/          # CASC archive files (required)
├── indices/       # CASC index files
├── config/        # CASC configuration files
└── ...

Running Tests with Real Data

# Run all tests (will skip those requiring WoW data if not available)
cargo test

# Run specific integration tests
cargo test -p casc-storage --test real_data_integration

# Run examples that use real data
cargo run -p casc-storage --example list_casc_files

Tests and examples will automatically:

• Use environment variables when available
• Fall back to common installation paths
• Skip gracefully with helpful setup instructions if no data found
• Work in CI environments without WoW data

📦 Installation

CLI Tool

Install with Cargo

cargo install ngdp-client

Install with Script (Unix/Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/wowemulation-dev/cascette-rs/main/install.sh | bash

Install with Script (Windows PowerShell)

irm https://raw.githubusercontent.com/wowemulation-dev/cascette-rs/main/install.ps1 | iex

Library Usage

cargo add ribbit-client ngdp-bpsv tact-client tact-parser ngdp-cdn ngdp-cache blte ngdp-crypto

From source

git clone https://github.com/wowemulation-dev/cascette-rs
cd cascette-rs
cargo build --release
# CLI binary will be at target/release/ngdp

🖥️ CLI Usage

The ngdp-client provides a comprehensive command-line interface for NGDP operations:

Install Game Clients

# Install WoW Classic Era (minimal installation)
ngdp install game wow_classic_era --install-type minimal --path ./wow-client

# Full installation with verification
ngdp install game wow --install-type full --verify --path ./wow-retail

# Dry-run to see what would be installed
ngdp install game wow_classic --install-type minimal --dry-run --path ./test

Version and CDN Information

# Query product versions (uses HTTPS endpoints)
ngdp query versions wow

# Get CDN configuration
ngdp query cdns wow

# Inspect build configurations
ngdp inspect build-config <hash>

BPSV and File Analysis

# Parse and display BPSV files
ngdp inspect bpsv ./file.bpsv

# Analyze BLTE files
ngdp inspect blte ./encrypted.blte

All commands support multiple output formats (--format json|text|bpsv) and the install command automatically creates .build.info files for client restoration.

📚 Documentation

• BPSV Format Specification
• BPSV Examples
• Ribbit Protocol
• Ribbit Examples
• TACT Protocol

📚 Online References

• TACT Reference
• Ribbit Reference
• CASC Reference

🔧 Features

Complete

• BPSV Parser/Writer (ngdp-bpsv)

  • ✅ BPSV format support with zero-copy parsing
  • ✅ Type-safe field definitions (STRING, HEX, DEC)
  • ✅ Schema validation and sequence number handling
  • ✅ Builder pattern for document creation
  • ✅ Round-trip compatibility

• Ribbit Protocol Client (ribbit-client)

  • ✅ Blizzard regions (US, EU, CN, KR, TW, SG)
  • ✅ V1 (MIME) and V2 (raw) protocol support
  • ✅ Typed API for all endpoints
  • ✅ PKCS#7/CMS signature verification
  • ✅ Certificate and OCSP support
  • ✅ Retry with exponential backoff
  • ✅ DNS caching for performance

• TACT HTTP Client (tact-client)

  • ✅ Version and CDN configuration queries
  • ✅ Support for V1 (port 1119) and V2 (HTTPS) protocols
  • ✅ Typed response parsing
  • ✅ Retry handling
  • ✅ Blizzard regions supported

• CDN Content Delivery (ngdp-cdn)

  • ✅ Parallel downloads with progress tracking
  • ✅ Streaming operations for large files
  • ✅ Retry with rate limit handling
  • ✅ Content verification
  • ✅ Configurable connection pooling
  • ✅ Fallback to backup CDN servers
  • ✅ Support for community mirrors (arctium.tools, reliquaryhq.com)

• Caching Layer (ngdp-cache)

  • ✅ Transparent caching for all NGDP operations
  • ✅ TTL-based expiration policies
  • ✅ Streaming I/O for memory efficiency
  • ✅ CDN-compatible directory structure
  • ✅ Batch operations for performance

• TACT File Parsers (tact-parser)

  • ✅ Encoding files (CKey ↔ EKey mapping)
  • ✅ Install manifests with tag-based filtering
  • ✅ Download manifests with priority sorting
  • ✅ Size files for installation calculations
  • ✅ Build configurations (key-value format)
  • ✅ TVFS (TACT Virtual File System)
  • ✅ 40-bit integer and varint support

• BLTE Decompression (blte)

  • ✅ Compression modes (None, ZLib, LZ4, Frame, Encrypted)
  • ✅ Multi-chunk file support
  • ✅ Checksum verification
  • ✅ Integration with ngdp-crypto for encrypted blocks
  • ✅ Memory processing

• Encryption Support (ngdp-crypto)

  • ✅ Salsa20 stream cipher (WoW encryption)
  • ✅ ARC4/RC4 cipher (legacy content)
  • ✅ Key management and loading
  • ✅ Multiple key file formats (CSV, TXT, TSV)
  • ✅ TACTKeys repository integration

• CLI Tool (ngdp-client)

  • ✅ Product queries and version information
  • ✅ Certificate operations
  • ✅ BPSV inspection and build config analysis
  • ✅ Encryption key management commands
  • ✅ Inspect commands with BLTE support
  • ✅ Multiple output formats (text, JSON, BPSV)
  • ✅ Terminal formatting

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Special thanks to the WoW emulation community and the documentation efforts at wowdev.wiki.

📄 License

This project is dual-licensed under either:

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

---

Note: This project is not affiliated with or endorsed by Blizzard Entertainment. It is an independent implementation based on reverse engineering efforts by the community for educational and preservation purposes.