# StarCraft Asset Extraction & Organization

Complete toolset for extracting and organizing StarCraft MPQ assets for use with alternative game engines.

## Quick Start

### 1. Extract Assets

Extract all assets from Starcraft.mpq:

```bash
source venv/bin/activate
python extract_starcraft_assets.py
```

This will create an `assets/` directory with organized files:

```
assets/
├── audio/          # 500+ sound files
├── graphics/       # Sprites, images, tiles  
├── video/          # Cinematics
├── data/           # Game data tables
├── maps/           # Map files
├── fonts/          # Font data
├── text/           # String tables
├── scripts/        # AI scripts
└── unknown/        # Unclassified files
```

### 2. Explore Extracted Assets

Use the demo script to explore what was extracted:

```bash
python demo_assets.py
```

Interactive menu:
1. List all assets by category
2. Analyze audio files  
3. Analyze graphics files
4. Search for specific files

Or use command line:
```bash
python demo_assets.py list
python demo_assets.py audio
python demo_assets.py graphics
python demo_assets.py search "unit"
```

### 3. Read the Documentation

- **[STARCRAFT_ASSETS.md](STARCRAFT_ASSETS.md)** - Complete guide to file formats and organization
- **[TESTING.md](TESTING.md)** - PyStorm testing and debugging info

## Usage Examples

### Extract with Custom Options

```bash
# Extract to different directory
python extract_starcraft_assets.py --output my_assets/

# Extract from different MPQ
python extract_starcraft_assets.py --mpq /path/to/BroodWar.mpq

# List files without extracting
python extract_starcraft_assets.py --list-only

# Quiet mode (less output)
python extract_starcraft_assets.py --quiet
```

### Search for Specific Files

```bash
# Find all unit-related files
python demo_assets.py search unit

# Find specific sound
python demo_assets.py search "000123"

# Find graphics
python demo_assets.py search .pcx
```

### Programmatic Usage

```python
from pathlib import Path
from pystorm import MPQArchive

# Open MPQ
archive = MPQArchive("Starcraft.mpq")

# List all files
files = archive.find_files("*")
print(f"Found {len(files)} files")

# Extract specific file
archive.extract_file("File00000123.wav", "output/sound.wav")

# Close
archive.close()
```

## File Organization

### By Category

Assets are automatically categorized based on file type:

| Category | Extensions | Description |
|----------|-----------|-------------|
| **audio** | .wav, .ogg, .mp3 | Sound effects, music, voices |
| **graphics** | .pcx, .grp, .dds | Images, sprites, tiles |
| **video** | .smk, .bik, .avi | Cinematics, briefings |
| **data** | .dat, .bin, .pal | Game data, tables, palettes |
| **maps** | .chk, .scm, .scx | Map and scenario files |
| **fonts** | .fnt, .ttf | Font definitions |
| **text** | .txt, .tbl | String tables, localization |
| **scripts** | .ais, .aiscript | AI and scripting |

### File Naming

- `File00000###.ext` - Numbered asset files (referenced by ID)
- Path structure preserved where present
- Files organized logically for game engine integration

## Integration Guide

### For Game Developers

1. **Extract assets**: Run `extract_starcraft_assets.py`
2. **Read documentation**: Review [STARCRAFT_ASSETS.md](STARCRAFT_ASSETS.md)
3. **Parse data files**: Use existing tools (PyMS, scbw) or write parsers
4. **Convert formats**: PCX → PNG, WAV → OGG, etc.
5. **Load into engine**: Integrate with your rendering/audio systems

### Recommended Libraries

**Python**:
- `PyMS` - StarCraft asset parser
- `PIL/Pillow` - Image processing
- `wave` - Audio file handling
- `struct` - Binary data parsing

**Other Languages**:
- `scbw` (Rust) - SC format library
- `BWAPI` (C++) - StarCraft modding API

## File Format Details

### Audio Files (.wav)

- Format: PCM WAV (usually 22050 Hz)
- Some use proprietary compression
- Most are mono, some stereo
- Files with metadata size=0 still contain valid data

### Graphics (.pcx, .grp)

- **PCX**: Standard 256-color images
- **GRP**: Proprietary sprite format with frames
- Require palette files (.pal, .wpe) for colors
- May contain multiple animation frames

### Data (.dat)

Binary tables with game data:
- `units.dat` - Unit statistics
- `weapons.dat` - Weapon properties  
- `sprites.dat` - Sprite definitions
- And many more...

See [STARCRAFT_ASSETS.md](STARCRAFT_ASSETS.md) for complete format documentation.

## Tools Included

### extract_starcraft_assets.py

Main extraction tool with categorization:
- Extracts all files from MPQ
- Organizes by file type
- Shows progress and statistics
- Preserves directory structure

### demo_assets.py

Asset exploration and analysis:
- List assets by category
- Analyze audio/graphics files
- Search functionality
- File information display

### mpq_inspector.py

GUI tool for MPQ inspection:
- Visual file browser
- Extract files interactively
- View compression stats
- Archive verification

## Legal Notice

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

- Assets extracted for **educational** and **personal use** only
- **Do not distribute** extracted assets
- **Commercial use** requires Blizzard licensing
- Create **original assets** for public distribution

This toolset is for:
- Learning game development
- Understanding file formats
- Creating personal game engines
- Educational reverse engineering

Always respect intellectual property rights.

## Performance

Extraction performance:
- **Starcraft.mpq** (578 MB, 890 files): ~10-30 seconds
- Depends on: disk speed, CPU, file size
- Progress displayed during extraction

## Troubleshooting

### "No archive loaded"
- Check MPQ file path
- Ensure file is valid StarCraft MPQ

### "Extraction failed"
- Some files may be corrupted/encrypted
- Check permissions on output directory
- Try extracting specific categories only

### Missing files
- Check other MPQs (BroodWar.mpq, patches)
- Some assets generated at runtime
- Verify with --list-only first

## Additional Resources

- **StormLib**: https://github.com/ladislav-zezula/StormLib
- **PyMS**: https://github.com/poiuyqwert/PyMS  
- **Staredit.net**: Community wiki and forums
- **BWAPI**: https://github.com/bwapi/bwapi

## Contributing

Found a bug or want to add features?
- Check existing issues
- Submit pull requests
- Document new file format discoveries

## Credits

- **Blizzard Entertainment** - StarCraft
- **Ladislav Zezula** - StormLib library
- **SC Community** - Format documentation
- **PyStorm** - Python MPQ bindings

---

**Ready to extract?** Run `python extract_starcraft_assets.py` to begin! 🚀