rr3-server/Tools/README.md

# 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.

```bash
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.

```bash
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.

```bash
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.

```powershell
.\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:**
```bash
sudo apt install python3 bash
```

**RedHat/CentOS:**
```bash
sudo yum install python3 bash
```

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

## Usage Examples

### Extract Single Asset
```bash
# 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
```bash
# 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
```bash
# 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:

```csharp
// 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

```bash
# 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"
```bash
chmod +x *.sh
```

### "Python 3 not found"
```bash
# 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:
```bash
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:
```bash
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.