pystorm/ASSET_EXTRACTION.md

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:

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:

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:

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 - Complete guide to file formats and organization
• TESTING.md - PyStorm testing and debugging info

Usage Examples

Extract with Custom Options

# 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

# 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

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
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 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! 🚀