rr3-server/Tools

RR3 Asset Extraction Tools

Cross-platform command-line tools for extracting and packing Real Racing 3 .z asset files.

What Are .z Files?

RR3 stores game assets (textures, data) as ZLIB-compressed files with .z extension:

• Format: Standard ZLIB/Deflate compression
• Content: Usually DDS textures (ETC2 for Android, BC3 for PC)
• Magic Bytes: 0x78 0x9C or 0x78 0xDA

Available Tools

1. extract_z_asset.sh (Linux/Unix)

Extracts a single .z file to its original format.

chmod +x extract_z_asset.sh
./extract_z_asset.sh sprites_0.etc.dds.z
./extract_z_asset.sh sprites_0.etc.dds.z /custom/output/directory

2. batch_extract_z_assets.sh (Linux/Unix)

Batch extracts all .z files from a directory.

chmod +x batch_extract_z_assets.sh
./batch_extract_z_assets.sh /path/to/assets
./batch_extract_z_assets.sh /path/to/assets /path/to/output

3. pack_z_asset.sh (Linux/Unix)

Packs a file with ZLIB compression to create .z format.

chmod +x pack_z_asset.sh
./pack_z_asset.sh sprites_0.etc.dds
# Output: sprites_0.etc.dds.z

4. extract_z_asset.ps1 (Windows PowerShell)

PowerShell version for Windows systems.

.\extract_z_asset.ps1 -InputFile "C:\assets\sprites_0.etc.dds.z"
.\extract_z_asset.ps1 -InputFile "C:\assets\file.z" -OutputDir "C:\extracted"

Requirements

• Python 3+ (for Linux/Unix scripts)
• PowerShell 5.1+ (for Windows scripts)
• Bash (Linux/Unix/macOS/WSL)

Installation

Ubuntu/Debian:

sudo apt install python3 bash

RedHat/CentOS:

sudo yum install python3 bash

Windows:

• PowerShell is pre-installed
• For bash scripts: Use WSL or Git Bash

Usage Examples

Extract Single Asset

# Extract texture file
./extract_z_asset.sh game_assets/sprites_0.etc.dds.z

# Output: game_assets/sprites_0.etc.dds

Batch Extract Entire Asset Directory

# Extract all .z files from APK assets
./batch_extract_z_assets.sh /path/to/rr3_apk/assets

# Results saved to: /path/to/rr3_apk/assets/extracted/

Modify and Repack

# 1. Extract
./extract_z_asset.sh original.dds.z

# 2. Edit original.dds with image editor (GIMP, Photoshop, etc.)

# 3. Repack
./pack_z_asset.sh modified.dds

# 4. Replace in APK/server
cp modified.dds.z /path/to/server/assets/

Integration with RR3 Server

These tools are also available as C# services in the main server:

// Inject service
public class MyController : ControllerBase
{
    private readonly AssetExtractionService _assetExtraction;
    
    public async Task<IActionResult> ProcessAsset()
    {
        var extracted = await _assetExtraction.ExtractZFileAsync("sprites_0.etc.dds.z");
        return Ok(extracted);
    }
}

See ASSET_EXTRACTION_GUIDE.md for full server integration documentation.

File Format Details

ZLIB Header

• Byte 0: 0x78 (CMF - Compression Method and Flags)
• Byte 1: 0x9C (FLG - Flags, default compression)
  • Or 0xDA (maximum compression)
  • Or 0x01 (no compression)

DDS Texture Format

After extraction, .z files typically reveal DDS textures:

• Header: 128 bytes (DDS magic + DDS_HEADER)
• Format: ETC2_RGBA (Android) or BC3/DXT5 (PC)
• Mipmaps: Usually included for performance

Workflow: Custom Car Textures

# 1. Extract original car texture
./extract_z_asset.sh car_001_body.etc.dds.z

# 2. Convert DDS to PNG (requires ImageMagick or GIMP)
convert car_001_body.etc.dds car_001_body.png

# 3. Edit PNG in image editor
# ... make your changes ...

# 4. Convert back to DDS with ETC2 compression
# (requires AMD Compressonator or similar)
compressonatorcli -fd ETC2_RGBA custom_car.png car_001_body.etc.dds

# 5. Repack to .z
./pack_z_asset.sh car_001_body.etc.dds

# 6. Upload to server or replace in APK

Troubleshooting

"Permission denied"

chmod +x *.sh

"Python 3 not found"

# Check if installed
python3 --version

# Install if missing (Ubuntu/Debian)
sudo apt install python3

"No valid ZLIB blocks found"

The file may not be ZLIB compressed. Check with:

hexdump -C file.z | head
# Should see: 78 9c or 78 da at the start

"Script runs but produces empty file"

The file may be corrupted or use a different compression format. Try:

file sprites_0.etc.dds.z
# Should show: zlib compressed data

Performance

• Single extraction: ~50-200ms per file
• Batch processing: Can handle 1000+ files
• Memory usage: Loads entire file into RAM
  • 10 MB file = ~20 MB RAM (temporary)
  • 100 MB file = ~200 MB RAM (temporary)

Credits

• Original Research: Tankonline's RR3 Texture Extraction Tool
• Cross-Platform Port: RR3 Community Server Team
• ZLIB Library: Python zlib module / .NET System.IO.Compression

License

Part of the RR3 Community Server preservation project. For educational and modding purposes only.