StarCraft: Brood War for iOS

A native iOS port of StarCraft: Brood War using OpenBW, bringing the classic RTS experience to iPhone and iPad with touch controls and Metal-accelerated rendering.

🎮 Features

Full StarCraft Experience: Play melee games with all original units, buildings, and mechanics
Native iOS Integration: Built with Swift and UIKit/SwiftUI for smooth iOS performance
Touch Controls: Custom RTS touch interface for unit selection, movement, and commands
Metal Rendering: Hardware-accelerated graphics using Apple's Metal framework
Original Assets: Uses authentic StarCraft MPQ archives for sprites, sounds, and maps
Universal App: Optimized for both iPhone and iPad

📱 Screenshots

_{Initial Setup} _{Configure StarCraft data files path}	_{Zerg Gameplay} _{Command interface with touch controls}
_{Terran Base} _{Full RTS experience on iOS}	_{Unit Selection} _{Multi-unit control with minimap}

Interface Features Shown

Resource Display: Minerals, gas, and supply count in top-left
Control Groups: Numbers 1-10 for quick unit/building access
Command Grid: 3x3 button layout for unit commands (Move, Attack, Hold, Patrol, Stop, Build, Train, etc.)
Minimap: Real-time tactical overview in bottom-left
Unit Selection: Multi-select with detailed unit information
Pause Control: Game speed management in top-right

🏗️ Architecture

The project uses a three-layer bridge architecture to connect Swift UI with the C++ OpenBW engine:

┌─────────────────────────────────────┐
│   Swift UI Layer                    │
│   (StarCraftApp/)                   │
│   - MetalGameView.swift             │
│   - TouchInputManager.swift         │
└─────────────────┬───────────────────┘
                  │ Bridging Header
┌─────────────────▼───────────────────┐
│   Objective-C++ Bridge              │
│   (OpenBWBridge/)                   │
│   - OpenBWBridge.h/mm               │
│   - Exposes game state to Swift     │
└─────────────────┬───────────────────┘
                  │ Direct C++ Access
┌─────────────────▼───────────────────┐
│   OpenBW Core                       │
│   (OpenBWCore/)                     │
│   - OpenBWGameRunner.mm             │
│   - OpenBWRenderer.mm               │
│   - MetalRenderer.mm                │
│   - MPQLoader.mm                    │
└─────────────────┬───────────────────┘
                  │ C++ Includes
┌─────────────────▼───────────────────┐
│   OpenBW Engine                     │
│   (openbw/ submodule)               │
│   - Header-only C++ library         │
│   - Core StarCraft game logic       │
└─────────────────────────────────────┘

Key Components

OpenBW Core (`ios/OpenBW-iOS/Sources/OpenBWCore/`)

OpenBWGameRunner.mm: Main game loop, sprite collection, melee game initialization
OpenBWRenderer.mm: GRP sprite rendering with RLE decompression, selection circles, health bars
MetalRenderer.mm: Converts 8-bit indexed framebuffer to RGBA Metal textures
MPQLoader.mm: StarCraft MPQ asset archive loading

Objective-C++ Bridge (`ios/OpenBW-iOS/Sources/OpenBWBridge/`)

OpenBWBridge.h/.mm: Exposes OpenBWEngine, OpenBWGameState, OpenBWUnit classes to Swift
Only uses Objective-C compatible types (no C++ in headers visible to Swift)

Swift UI Layer (`ios/OpenBW-iOS/Sources/StarCraftApp/`)

MetalGameView.swift: Metal rendering view with integrated game controller
TouchInputManager.swift: Touch gesture handling optimized for RTS gameplay
GameView.swift: Main game view controller

📋 Prerequisites

Required Tools

Xcode 14.0+ with iOS SDK
CMake 3.20+
Git with submodules support
iOS 15.0+ device or simulator

Required Assets

You must provide your own StarCraft: Brood War game files (version 1.16.1 or 1.18):

StarDat.mpq (~60MB)
BrooDat.mpq (~24MB)
Patch_rt.mpq (~1MB)

Note: This project does not include game assets. You must own a legitimate copy of StarCraft: Brood War.

Filename casing matters. The iOS simulator emulates iOS's case-sensitive filesystem even though macOS is case-insensitive, and OpenBW opens Patch_rt.mpq by hardcoded name. Use exactly StarDat.mpq, BrooDat.mpq, Patch_rt.mpq.

A StarCraft Remastered install will not work — it stores data as CASC, not MPQ. The CDs don't hold the archives in the clear either; they sit inside INSTALL.EXE, itself a self-extracting MPQ. Extraction procedure: docs/backlog/2026-07-31-task-documenter-extraction-mpq/CARD.md.

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/yourusername/sc-ios.git
cd sc-ios
git submodule update --init --recursive

This pulls the openbw/ engine. Note that CMakeLists.txt lives in ios/, not at the repo root — the build commands below must be run from ios/.

2. Build C++ Libraries

The iOS app depends on C++ libraries that must be built first using CMake.

For iOS Simulator (x86_64/arm64)

cd ios
mkdir -p build-sim
cd build-sim
cmake .. -DCMAKE_TOOLCHAIN_FILE=../ios-simulator.toolchain.cmake \
         -DCMAKE_BUILD_TYPE=Debug \
         -GXcode
cmake --build . --config Debug
cd ../..

For iOS Device (arm64)

cd ios
mkdir -p build-device
cd build-device
cmake .. -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake \
         -DCMAKE_BUILD_TYPE=Release \
         -GXcode
cmake --build . --config Release
cd ../..

3. Copy StarCraft Assets

Place your StarCraft MPQ files in the assets directory:

mkdir -p ios/Assets
cp /path/to/your/starcraft/StarDat.mpq ios/Assets/
cp /path/to/your/starcraft/BrooDat.mpq ios/Assets/
cp /path/to/your/starcraft/Patch_rt.mpq ios/Assets/
cp -r /path/to/your/starcraft/maps ios/Assets/

4. Build and Run the iOS App

Using Xcode (Recommended)

open ios/StarCraft.xcodeproj

Select your target device or simulator
Build and run (⌘R)

Using Command Line

cd ios
xcodebuild -project StarCraft.xcodeproj \
           -scheme StarCraft \
           -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
           -configuration Debug \
           build

5. Install Assets on Simulator

The app needs MPQ files in its Documents folder at runtime:

# Install the app
xcrun simctl install booted /path/to/DerivedData/.../Debug-iphonesimulator/StarCraft.app

# Copy assets to app's Documents directory
APP_DATA=$(xcrun simctl get_app_container booted com.openbw.starcraft data)
mkdir -p "$APP_DATA/Documents"
cp ios/Assets/*.mpq "$APP_DATA/Documents/"
cp -r ios/Assets/maps "$APP_DATA/Documents/"

# Launch the app
xcrun simctl launch booted com.openbw.starcraft

🎯 Roadmap

Current Status

✅ Core game engine integration
✅ Basic rendering pipeline
✅ Touch input handling, including pinch-to-zoom and box selection
✅ MPQ asset loading
🚧 Melee game — starts and renders; the economic loop (harvesting, building, training, combat) has not been validated end to end yet
🚧 Minimap — draws terrain and units, but terrain reads as a flat colour

Detailed specs and backlog: docs/backlog/, indexed by docs/backlog/2026-07-31-spec-portage-ios-openbw/CARD.md.

Planned Features

Multiplayer support (LAN/Internet)
Campaign mode
Replay system
Sound and music playback (audio session is configured, playback is not implemented)
Game speed controls
Save/load game state
Settings and configuration UI
Map editor integration
Bot/AI integration via BWAPI

Future Enhancements

iPadOS optimizations (mouse/keyboard support)
Game Center integration
Cloud save synchronization
Performance profiling and optimization
Accessibility features

🛠️ Development

Project Structure

sc-ios/
├── openbw/              # OpenBW engine (git submodule)
├── docs/backlog/        # Specs and tasks (faru cards)
├── ios/
│   ├── CMakeLists.txt   # Build entry point — NOT at repo root
│   ├── StarCraft.xcodeproj
│   ├── Assets/          # MPQ files (not in repo)
│   ├── OpenBW-iOS/
│   │   └── Sources/
│   │       ├── OpenBWCore/      # C++ game engine wrapper
│   │       ├── OpenBWBridge/    # Objective-C++ bridge
│   │       └── StarCraftApp/    # Swift UI layer
│   ├── build-sim/       # CMake build output (simulator)
│   └── build-device/    # CMake build output (device)
├── CLAUDE.md            # AI assistant guidance
└── README.md            # This file

Building for Different Configurations

# Debug build (simulator)
cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../ios-simulator.toolchain.cmake
cmake --build . --config Debug

# Release build (device)
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake
cmake --build . --config Release

Code Conventions

C++: C++14 standard, header-only patterns for OpenBW integration
Objective-C++: ARC enabled, OpenBW* class prefix, NS_ASSUME_NONNULL blocks
Swift: SwiftUI where possible, Apple naming conventions, @Published for reactive state

Debugging

Enable debug logging in OpenBWGameRunner.mm:

#define OPENBW_DEBUG 1

View console logs in Xcode's debug area or via:

xcrun simctl spawn booted log stream --predicate 'processImagePath contains "StarCraft"'

🐛 Troubleshooting

Library Not Found Errors

Ensure CMake build completed successfully and Xcode's LIBRARY_SEARCH_PATHS points to:

$(PROJECT_DIR)/build-sim/Debug-iphonesimulator/ (simulator)
$(PROJECT_DIR)/build-device/Release-iphoneos/ (device)

MPQ Loading Failures

Verify MPQ files exist in simulator's Documents folder:

APP_DATA=$(xcrun simctl get_app_container booted com.openbw.starcraft data)
ls -lh "$APP_DATA/Documents/"

Check file permissions (should be readable)
Verify MPQ files are from version 1.16.1 or 1.18

App Won't Launch

Verify bundle identifier: com.openbw.starcraft

Reinstall the app:

xcrun simctl uninstall booted com.openbw.starcraft
xcrun simctl install booted /path/to/StarCraft.app

Check Xcode signing settings

Build Errors

"asio.hpp not found": Run git submodule update --init --recursive
"Unknown type name 'OpenBWEngine'": Clean build folder and rebuild C++ libraries
Linker errors: Ensure both libopenbw_core.a and libopenbw_ios_platform.a are built

🤝 Contributing

Contributions are welcome! This project needs help with:

iOS UI/UX: Improving touch controls and game interface
Performance: Optimizing rendering and game loop
Features: Implementing sound, multiplayer, campaigns
Testing: Bug reports and compatibility testing
Documentation: Code comments, guides, tutorials

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly on both simulator and device
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure:

Code follows existing conventions
No game assets are committed to the repository
Changes don't break existing functionality
Include tests where appropriate

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Important: While this code is MIT licensed, you must own a legitimate copy of StarCraft: Brood War to use this software. This project does not include or distribute any Blizzard Entertainment assets.

🙏 Acknowledgments

OpenBW - The open-source StarCraft engine that makes this possible
BWAPI - Bot API for StarCraft: Brood War
Blizzard Entertainment - For creating the timeless classic that is StarCraft
The StarCraft modding and reverse-engineering community

📧 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star History

If you find this project interesting, please consider giving it a star! It helps others discover the project and motivates continued development.

Disclaimer: This is an unofficial, fan-made project and is not affiliated with or endorsed by Blizzard Entertainment. StarCraft and StarCraft: Brood War are registered trademarks of Blizzard Entertainment, Inc.

Name		Name	Last commit message	Last commit date
docs		docs
ios		ios
openbw @ 8265ec4		openbw @ 8265ec4
screenshots		screenshots
.DS_Store		.DS_Store
.env		.env
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation