🎖️ Command & Conquer Generals: Native Apple Silicon Port

This project brings Command & Conquer Generals: Zero Hour to macOS, iPhone, and iPad. This isn't emulation; it is a native implementation of the original 2003 engine compiled for ARM64.

🛠️ Technical Architecture

The project leverages the $GPL_{v3}$ source released by EA, building upon a legacy of community efforts from TheSuperHackers, Fighter19 (the original Unix port), and fbraz3/GeneralsX. This specific fork introduces critical engine fixes and the first-ever iOS/iPadOS support.

The Rendering Pipeline

To get a DirectX 8 game running on Apple's Metal API, the data travels through a complex translation chain:

📱 The iOS Challenge: More Than Just a "Port"

Bringing a 2003 Windows RTS to a modern mobile OS was an uphill battle. iOS is a friendly hostile environment for legacy software.

"Porting" is an understatement. The journey involved rewriting how the engine interacts with the OS and solving deep-seated architectural conflicts.

Overcoming Obstacles

• Filesystem Rigidity: The engine expects a writable directory everywhere. Every save path, cache, and configuration write had to be rerouted to the app bundle.
• The DXVK Gap: DXVK had never been built for iPhoneOS. This required a Meson cross-build and a specific patch to the Vulkan loader (Patches/dxvk-ios.patch) because iOS restricts dlopen to the bundle.
• Memory & State: A critical bug was found where the OS would seize the Metal drawable during app-switching; attempting to draw a single frame upon resume would cause an immediate crash.

🕹️ RTS Touch Interface

Since SDL3 provides raw events, a custom semantic layer was built to translate touches into RTS commands:

🐛 Bug Archaeology

The development process involved hunting "zombie" bugs:

1. The Void Map: The minimap rendered as pure black because a legacy texture fallback accidentally stripped the alpha channel.
2. The Silent EVA: The voice-over would randomly mute because a "zombie" audio stream held a global "do not interrupt" flag indefinitely.

For more details, see the docs/port/PORTING_PLAYBOOK.md or the docs/port/PORTING_PATTERNS.md.

🤖 A Human-AI Partnership

This project was a symbiotic collaboration between a human and Claude Code (Anthropic's Fable model).

• The AI: Handled the heavy lifting of C++ engineering, complex cross-builds, and deep device debugging.
• The Human: Acted as the director and playtester, identifying symptoms (e.g., "I hear chirping" or "the map is black") and making all final architectural decisions.

---

🚀 Quick Start Guide

💻 macOS Setup

• Install Toolchain
• Configure vcpkg
• Install Vulkan SDK

# 1. Toolchain
xcode-select --install
brew install cmake ninja meson pkgconf
brew install --cask steamcmd

# 2. vcpkg (Full clone required for manifest baselines)
git clone https://github.com/microsoft/vcpkg ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=~/vcpkg # Add to shell profile

# 3. LunarG Vulkan SDK (Manual install from https://vulkan.lunarg.com/sdk/home)
export VULKAN_SDK=$HOME/VulkanSDK/version/macOS # Add to shell profile

Build and Launch:

git clone https://github.com/ammaarreshi/Generals-Mac-iOS-iPad.git GeneralsX
cd GeneralsX
./scripts/build/macos/build-macos-zh.sh    # Build
./scripts/build/macos/deploy-macos-zh.sh   # Deploy to ~/GeneralsX/GeneralsZH
./scripts/get-assets.sh your_steam_username # Fetch game data
cd ~/GeneralsX/GeneralsZH
./run.sh -win

📱 iPhone / iPad Setup

In addition to the macOS steps above, you will need:

• Full Xcode (signed in with Apple ID).
• brew install xcodegen.
• An Apple Developer team account (Free or Paid).

cd GeneralsX
git submodule update --init references/fbraz3-dxvk # Essential for iOS DXVK