# StarCraft Asset Organization Guide

This document describes the organization and structure of assets extracted from `Starcraft.mpq` for use with alternative game engines.

## Directory Structure

After extraction, assets are organized into the following categories:

```
assets/
├── audio/          # Sound effects, music, voice lines
├── graphics/       # Sprites, tiles, images
├── video/          # Cinematics and video files
├── data/           # Game data tables and binary files
├── maps/           # Map files
├── fonts/          # Font definitions
├── text/           # String tables and text files
├── scripts/        # AI and scripting files
└── unknown/        # Unclassified or unknown file types
```

## Asset Categories

### 🔊 Audio (`audio/`)

**File Types**: `.wav`, `.ogg`, `.mp3`

Contains all audio assets including:
- **Sound Effects**: Unit sounds, weapon sounds, UI feedback
- **Music**: Background music tracks
- **Voice Lines**: Unit acknowledgments, mission briefings
- **Ambient Sounds**: Environmental audio

**Format Notes**:
- Most audio files are in WAV format (PCM or compressed)
- Some files may use proprietary Blizzard compression
- Sample rates vary (typically 22050 Hz or 44100 Hz)

**Common Patterns**:
- `File000*.wav` - Sound effect files (numbered)
- Files with size=0 in metadata still contain valid audio data

### 🎨 Graphics (`graphics/`)

**File Types**: `.pcx`, `.grp`, `.dds`, `.tga`, `.bmp`

Contains visual assets:
- **PCX Files**: Image files (256-color palette-based)
  - UI elements
  - Menu backgrounds
  - Portraits
  - Loading screens

- **GRP Files**: Sprite/graphic files (proprietary format)
  - Unit sprites
  - Building sprites  
  - Effects and animations
  - Terrain tiles

**Format Notes**:
- `.pcx` - Standard PCX image format (256 colors)
- `.grp` - Blizzard's proprietary sprite format with frame data
- Sprites may contain multiple frames for animations
- Palette information stored separately (`.pal`, `.wpe` files in `data/`)

**Usage**:
- PCX files can be opened with standard image tools
- GRP files require custom parsers or conversion tools

### 🎬 Video (`video/`)

**File Types**: `.smk`, `.bik`, `.avi`

Contains cinematic and video content:
- **SMK Files**: Smacker video format (older)
- **BIK Files**: Bink video format (newer)
- Mission briefings
- Campaign cinematics
- Victory/defeat sequences

**Format Notes**:
- Smacker (.smk) is a legacy video codec
- Requires specific decoders (libsmacker, RAD Game Tools)
- Resolution typically 640x480 or lower
- May include embedded audio

### 📊 Data (`data/`)

**File Types**: `.dat`, `.bin`, `.pal`, `.wpe`, `.cv5`, `.vf4`, `.vx4`, `.vr4`

Contains game logic and configuration data:

**DAT Files** - Database tables:
- `units.dat` - Unit statistics and properties
- `weapons.dat` - Weapon damage, range, behavior
- `upgrades.dat` - Upgrade definitions
- `techdata.dat` - Technology tree
- `sprites.dat` - Sprite definitions
- `images.dat` - Image/animation data
- `sfxdata.dat` - Sound effect mappings
- `orders.dat` - Unit order/command definitions

**Palette Files**:
- `.pal` - Color palette data (256 colors)
- `.wpe` - Warp/special effect palettes

**Tileset Files**:
- `.cv5` - Terrain tile definitions
- `.vf4` - Tile graphics (4-byte)
- `.vx4` - Extended tile data
- `.vr4` - Terrain rendering data

**Format Notes**:
- DAT files are binary tables with fixed-width records
- Use tools like PyDAT, DatEdit, or custom parsers
- Palette files define 256 RGB colors (768 bytes)
- Tileset files work together to render terrain

**Parsing Libraries**:
- Consider using existing SC format parsers:
  - `scbw` (Rust)
  - `PyMS` (Python)
  - `BWAPI` structures (C++)

### 🗺️ Maps (`maps/`)

**File Types**: `.chk`, `.scm`, `.scx`

Contains map and scenario files:
- **CHK Files**: Map scenario data (inside MPQ/SCM/SCX)
- **SCM Files**: StarCraft Map (single-player)
- **SCX Files**: StarCraft Expansion Map (Brood War)

**Structure**:
- Maps are themselves MPQ archives containing:
  - `scenario.chk` - Core map data
  - Trigger definitions
  - Unit placement
  - Terrain layout
  - String tables

**Format Sections**:
- `VER` - Version
- `DIM` - Dimensions
- `ERA` - Tileset
- `UNIT` - Unit placements
- `THG2` - Triggers
- `MBRF` - Map briefing
- And many more...

**Tools**:
- ScmDraft - Map editor
- PyMS - Python parser
- BWAPI map parsers

### 🔤 Fonts (`fonts/`)

**File Types**: `.fnt`, `.ttf`

Font rendering data:
- Bitmap font definitions
- Character glyph data
- Font metrics and kerning

**Format**:
- Custom bitmap font format
- Contains character width, height, offset data
- Pre-rendered glyphs for each character

### 📝 Text (`text/`)

**File Types**: `.txt`, `.tbl`, `.rtf`

String tables and localized text:
- **TBL Files**: String table format
  - UI text
  - Unit names
  - Campaign dialogue
  - Error messages

**Format**:
- Binary format with string offsets
- Null-terminated strings
- String IDs referenced by game code
- Localization support (different files per language)

**Common Files**:
- `stat_txt.tbl` - Main string table
- Mission briefing strings
- Campaign storyline text

### 🤖 Scripts (`scripts/`)

**File Types**: `.ais`, `.aiscript`, `.ai`

AI and scripting files:
- AI behavior scripts
- Build orders
- Unit micro commands
- Campaign AI definitions

**Format**:
- Text-based scripts (in some cases)
- Binary AI bytecode (in others)
- References units, buildings, and actions from DAT files

### ❓ Unknown (`unknown/`)

Files that couldn't be automatically categorized:
- Files with `.xxx` extension (placeholder)
- Files without extensions
- Unknown or proprietary formats

**Common Cases**:
- Temporary files
- Internal debug data
- Encrypted or packed data
- Format unknown without reverse engineering

## File Naming Conventions

### Numbered Files

Many files use numeric naming patterns:
- `File00000123.wav` - Sound file #123
- `File00000456.pcx` - Image file #456

These numbers typically correspond to:
- Internal asset IDs
- References in DAT files (e.g., `images.dat` row 123)
- Sound ID mappings in `sfxdata.dat`

### Structured Paths

Some files maintain directory structure:
- `glue/PalNl/` - UI palette files
- `unit/` - Unit-related assets
- `rez/` - Resources

Preserve these paths as they often indicate asset relationships.

## Integration Guide

### For Game Engine Developers

1. **Start with Data Files**:
   - Parse `units.dat`, `weapons.dat` to understand game entities
   - Build a data model based on DAT structure
   - Reference existing parsers for format details

2. **Load Graphics**:
   - Convert PCX to your engine's format (PNG, DDS, etc.)
   - Write GRP parser for sprite data
   - Extract frame information for animations
   - Load palettes from PAL/WPE files

3. **Audio System**:
   - Convert WAV files to your preferred format
   - Build sound effect mapping from `sfxdata.dat`
   - Implement audio triggers based on game events

4. **Map Loading**:
   - Parse CHK format for map data
   - Extract tileset references
   - Load unit placements
   - Implement trigger system

5. **Rendering Pipeline**:
   - Use tileset data (CV5, VF4, VX4, VR4) for terrain
   - Render sprites from GRP files
   - Apply palette effects
   - Implement proper layering (terrain, units, effects)

### Recommended Workflow

```bash
# 1. Extract assets
python extract_starcraft_assets.py

# 2. Inspect extracted files
ls -R assets/

# 3. Start with a simple asset
# For example, load a PCX image:
from PIL import Image
img = Image.open('assets/graphics/SomImage.pcx')
img.show()

# 4. Reference existing tools
# - PyMS for DAT parsing
# - scbw for Rust integration
# - BWAPI for C++ examples
```

## File Format Resources

### Documentation

- **Staredit.net**: Community wiki with format specs
- **BWAPI Documentation**: API for StarCraft modding
- **Farty's Resource Pages**: Comprehensive format details
- **Campaign Creations**: SC modding forums

### Tools & Libraries

- **PyMS**: Python tools for SC assets
  - https://github.com/poiuyqwert/PyMS
  
- **scbw**: Rust library for SC formats
  - Parse DAT, GRP, CHK files
  
- **ScmDraft**: Map editor (Windows)
  - Visual inspection of map structure

- **DatEdit**: DAT file editor
  - Useful for understanding table structure

### Parsing Examples

**Python - Read a PAL file**:
```python
def read_palette(path):
    with open(path, 'rb') as f:
        data = f.read(768)  # 256 colors * 3 bytes (RGB)
        palette = [(data[i], data[i+1], data[i+2]) 
                   for i in range(0, 768, 3)]
    return palette
```

**Python - Basic TBL reader**:
```python
def read_tbl(path):
    with open(path, 'rb') as f:
        count = int.from_bytes(f.read(2), 'little')
        offsets = [int.from_bytes(f.read(2), 'little') 
                   for _ in range(count)]
        
        strings = []
        for offset in offsets:
            f.seek(offset)
            string = b''
            while True:
                char = f.read(1)
                if char == b'\x00':
                    break
                string += char
            strings.append(string.decode('latin-1'))
    return strings
```

## Legal Considerations

⚠️ **Important**: StarCraft assets are copyrighted by Blizzard Entertainment.

- These assets are extracted for **educational purposes** and **personal use**
- Creating alternative engines for **personal learning** is generally acceptable
- **Distribution** of extracted assets is **prohibited**
- **Commercial use** requires proper licensing from Blizzard
- Always respect Blizzard's intellectual property rights

For legitimate projects:
- Use assets only for testing and development
- Create your own original assets for distribution
- Consider open-source alternatives (OpenRA, etc.)
- Contact Blizzard for licensing if planning commercial release

## Troubleshooting

### Corrupted Files

Some files may fail to extract:
- Try extracting with different tools
- Files with metadata size=0 may still be valid
- Check if file is actually used by the game

### Missing Assets

If expected assets aren't found:
- Check other MPQ files (e.g., `BroodWar.mpq`, `Patch_rt.mpq`)
- Assets may be in expansion or patch archives
- Some assets generated at runtime (not in MPQ)

### Format Unknown

For unknown formats:
- Check community resources (staredit.net)
- Use hex editor to inspect file structure
- Compare with similar known formats
- Community may have reverse-engineered specs

## Additional Resources

- **StarCraft Wiki**: https://starcraft.fandom.com/
- **Staredit Network**: http://www.staredit.net/
- **BWAPI**: https://github.com/bwapi/bwapi
- **PyMS GitHub**: https://github.com/poiuyqwert/PyMS

## Credits

- **Blizzard Entertainment**: Original StarCraft assets and game
- **StormLib**: Ladislav Zezula - MPQ archive library
- **PyStorm**: Python bindings for StormLib
- **Community**: Countless modders and reverse engineers who documented formats

---

**Happy Modding!** 🎮

For questions or issues with asset extraction, please refer to the PyStorm documentation or community resources.