pystorm/STARCRAFT_ASSETS.md

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

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

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:

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.