cascette-rs Documentation

About This Project

cascette-rs is part of the wowemulation-dev initiative to build open source tooling for World of Warcraft emulation. The project focuses on modern WoW Classic clients (1.13+, 2.5+, 3.4+) which use Blizzard’s NGDP content distribution system.

Why Modern Clients?

The WoW emulation and modding community has historically focused on the 3.3.5a client from 2008. While functional, this approach has limitations:

Outdated technology: MPQ archives, no content addressing, manual patching
Fragmented tooling: Many tools exist only as abandoned Windows binaries
Limited modding: Technical constraints restrict what can be modified

Modern Classic clients differ from 3.3.5a:

Active development: Blizzard continues updating these clients
Better architecture: NGDP/CASC enables content addressing and streaming
Cross-platform: Same content format works on Windows, macOS, and Linux
Preservation: Community CDN mirrors ensure historical builds remain available

What You Can Do with cascette-rs

For Emulator Developers

Download specific WoW Classic builds for server development
Extract game data files (DBCs, maps, models) for server-side use
Verify client installations match expected versions
Serve game content to clients via the Agent API

For Archivists

Mirror complete WoW builds from Blizzard’s CDN
Preserve historical game versions before they disappear
Access builds from community CDN mirrors when Blizzard removes them
Track version history across all WoW products

For Modders

Extract assets from any WoW build for modification
Understand file relationships through encoding and root manifests
Work with modern file formats instead of legacy MPQ tools
Build custom content distribution for modified clients

For Tool Developers

Parse all NGDP/CASC binary formats with the cascette-formats library
Build applications on top of cascette’s CDN and protocol layers
Integrate CASC reading into existing toolchains
Create cross-platform tools that work on Linux, macOS, and Windows

What is NGDP?

NGDP (Next Generation Distribution Pipeline) is Blizzard’s content distribution system. It replaced MPQ/P2P/Torrent distribution with World of Warcraft 6.0 in 2014.

For technical details, see NGDP on wowdev.wiki.

System Overview

NGDP consists of three components:

Ribbit API: Provides product versions, CDN endpoints, and configuration data
CDN Distribution: Delivers game content through HTTP/HTTPS
Agent: Local HTTP service (port 1120) that manages downloads and installations

Key Differences from MPQ

Distribution Method: CDN-based delivery instead of P2P/Torrent
Content Addressing: Files identified by content hashes rather than names
Update Mechanism: Incremental updates through partial file downloads
Archive Format: CASC (Content Addressable Storage Container) replaces MPQ archives
Content Protection: Encryption support for secure pre-release distribution

Benefits of NGDP

For Distribution

Reduced Server Load: CDN infrastructure handles content delivery
Faster Downloads: Users connect to nearest CDN nodes
Incremental Updates: Only changed content needs downloading
Parallel Downloads: Multiple files retrieved simultaneously
Pre-release Distribution: Encrypted content can be distributed before launch

For Development

Content Deduplication: Identical files stored once across versions
Stream Installation: Games playable before download completes
Platform Independence: Same content system across operating systems

Core Concepts

Content Addressing

Files are identified by MD5 hashes of their content. Identical content produces identical hashes, enabling deduplication, integrity verification, and cache efficiency.

System Files

NGDP uses metadata files to manage content:

Root File: Maps game files to content keys
Encoding File: Maps content to compressed versions
Install Manifest: Defines installation requirements
Download Manifest: Sets download priorities

BLTE Format

BLTE (Block Table Encoded) is the container format for game data. It supports:

Block-based compression
Multiple compression algorithms
Encryption per block
Chunked processing

Content Encryption

NGDP supports Salsa20 encryption for distributing content before its release date. Files can be pre-positioned on CDN while remaining inaccessible until decryption keys are provided.

Technical Specifications

Byte Order: Big-endian (network byte order)
Hash Algorithm: MD5 for content identification
Key Size: 128-bit (16 bytes)
Compression: zlib, lz4, and other algorithms per block
Encryption: Salsa20 stream cipher for content protection

Ribbit Protocol - TCP-based discovery and version information API
BPSV Format - Blizzard Pipe-Separated Values format for API responses

CDN Formats

Configuration Files (Text)

Build Config - Build-specific settings (/config/{hash})
CDN Config - CDN server and archive lists (/config/{hash})
Product Config - Product settings and versions (/config/{hash})
Patch Config - Differential patch information (/config/{hash})

Content Files (Binary)

Immutable, content-addressed files served from CDN:

CDN Archives - BLTE containers with game content (/data/{prefix}/{hash}.archive)
CDN Indices - Maps keys to archive locations (/data/{prefix}/{hash}.index)
Encoding File - Maps content to encoding keys (/data/{prefix}/{hash})
Root File - Maps files to content keys (/data/{prefix}/{hash})
Install Manifest - Installation requirements (/data/{prefix}/{hash})
Download Manifest - Download priorities (/data/{prefix}/{hash})
Patch Archives - Delta patches (/patch/{prefix}/{hash}.archive)
Patch Indices - Patch archive index (/patch/{prefix}/{hash}.index)

Modern Additions (WoW 8.2+)

TVFS - Virtual file system manifest (via vfs-* fields in BuildConfig)

CASC Local Formats

Client-side storage structures created and managed by Battle.net:

Local Indices

IDX Journal - Bucket-based local index (Data/indices/{bucket}.idx)
Archive Groups - Combined archive index (client-generated optimization)
Shadow Memory - Memory-mapped cache (Data/shmem)

Local Archives

data.### - Combined CDN archives (Data/data/data.###)
patch.### - Combined patch archives (Data/patch/patch.###)

Local Configuration

.build.info - Local build configuration (root directory), BPSV-formatted
DBCache - Hotfix database cache (Cache/ADB/*.bin)

Shared Formats

Container Formats

BLTE Format - Block compression/encryption (all content storage)
ESpec Format - Encoding specifications (compression definitions)

Cryptographic

MD5 Keys - Content addressing (all key references)
Salsa20 Encryption - Stream cipher (content protection)
TACT Keys - Key management (decryption keys)

Supporting Systems

CDN Architecture - Content distribution network structure
CDN Mirroring - Historical preservation strategies
FileDataId - Persistent file identification across builds

Format Relationships

CDN Download Flow

flowchart TB
    subgraph Discovery
        Ribbit["Ribbit (BPSV)"]
        ProductConfig["Product Config"]
        CDNConfig["CDN Config"]
        BuildConfig["Build Config"]
    end

    subgraph Content
        Archives["CDN Archives + Indices"]
        Encoding["Encoding File"]
        Root["Root File"]
        Manifests["Install/Download Manifests"]
    end

    Ribbit --> ProductConfig --> CDNConfig --> BuildConfig
    BuildConfig --> Archives
    Archives --> Encoding --> Root
    Root --> Manifests

Content Resolution

flowchart LR
    subgraph Input
        File["Filename/FileDataId"]
    end

    subgraph Lookup
        Root["Root File"]
        CKey["Content Key"]
        Encoding["Encoding File"]
        EKey["Encoding Key + ESpec"]
    end

    subgraph Retrieval
        Index["CDN Index"]
        Location["Archive Location"]
        Archive["CDN Archive"]
        BLTE["BLTE Data"]
    end

    subgraph Output
        Decompress["Decompression"]
        Raw["Raw Content"]
    end

    File --> Root --> CKey
    CKey --> Encoding --> EKey
    EKey --> Index --> Location
    Location --> Archive --> BLTE
    BLTE --> Decompress --> Raw

Keyboard shortcuts

cascette-rs