diff --git a/SourceCode/Builds/RunReleaseBuildsonMacOS.md b/SourceCode/Builds/RunReleaseBuildsonMacOS.md new file mode 100644 index 00000000..dfc26ea5 --- /dev/null +++ b/SourceCode/Builds/RunReleaseBuildsonMacOS.md @@ -0,0 +1,153 @@ +# Running Generals Zero Hour on macOS (Apple Silicon) + +The game runs through Wine-CrossOver via Heroic Launcher, no native macOS build exists yet. + +## What you need + +- A Mac with Apple Silicon (M1 or later) +- macOS Tahoe (or recent macOS — older versions should work but aren't tested here) +- [Heroic Games Launcher](https://heroicgameslauncher.com/) (tested with 2.22.0) +- A Steam account that owns *Command & Conquer: Generals - Zero Hour* (app ID `2732960`) +- [Homebrew](https://brew.sh/) installed + +## Step 1: Install SteamCMD + +```bash +brew install steamcmd +``` + +Then clear the macOS Gatekeeper quarantine from the install, otherwise steamcmd will fail to load its +own libraries on first run (see Step 2): + +```bash +xattr -dr com.apple.quarantine /opt/homebrew/Caskroom/steamcmd/*/MacOS +``` + +## Step 2: Download the game files + +Run this command. Replace `YOUR_USERNAME` with your Steam username. + +```bash +steamcmd +@sSteamCmdForcePlatformType windows +login YOUR_USERNAME +app_update 2732960 validate +quit +``` + +The `+@sSteamCmdForcePlatformType windows` flag forces Steam to download the Windows version of the game. + +On the first run, steamcmd self-updates and re-downloads its libraries, so macOS may quarantine them again +even though you cleared it in Step 1. If that happens you'll see one or both of these: + +- A popup saying **"Breakpad.framework" was not opened** with **Move to Trash** / **Done** buttons. + Click **Done** - do NOT click Move to Trash. +- steamcmd quits with `Failed to load steamconsole.dylib ... library load disallowed by system policy`. + +Just clear the quarantine again and re-run the steamcmd command above: + +```bash +xattr -dr com.apple.quarantine /opt/homebrew/Caskroom/steamcmd/*/MacOS +``` + +Steam Guard will ask you to confirm on your phone. The download is about 3 GB. + +Files end up in: + +```bash +~/Library/Application Support/Steam/steamapps/common/Command & Conquer Generals - Zero Hour/ +``` + +## Step 3: Install the community patch + +- Go to the [GeneralsGameCode releases page](https://github.com/TheSuperHackers/GeneralsGameCode/releases) +- Download the latest `weekly-*-generalszh` build. + +Extract the files directly into the game folder from Step 2. +If it asks to replace any existing files, check **Apply to All** and choose **Replace**. +The patch ships its own executable (`generalszh.exe`) rather than replacing the original `generals.exe`, +so your base game stays intact. + +## Step 4: Install Wine-CrossOver in Heroic + +Open Heroic Games Launcher. Go to **Wine Manager** (in the sidebar or settings) and install **Wine-CrossOver-Latest**. +Version 23.7.1-1 was used when this was written. + +## Step 5: Add the game to Heroic + +1. Open Heroic and go to **Library** +2. Click **Add Game** +3. Fill in: + - **Name**: Generals Zero Hour (or whatever you want) + - **Platform**: Windows + - **Executable**: browse to `generalszh.exe` in the game folder + +Heroic creates the Wine prefix automatically. No need to configure it manually. + +## Step 6: Set the Wine version + +Click the menu icon (three lines) below your Generals Zero Hour game. +On the **Wine Settings** tab, select **Wine-CrossOver** (not GPTK). +You do not need to change any other settings. + +## Step 7: Launch and play + +Hit play. No Winetricks dependencies are needed, it runs out of the box with Wine-CrossOver. + +Set your resolution in the game's graphics options. 1900x1200 works on a 14" MacBook Pro display. + +## Known issues + +### Mouse gets stuck after changing resolution + +The mouse cursor can get trapped or stop responding after the game launches. +This happened after selecting the new 1900x1200 resolution. +What fixed it: **Cmd+Tab** out of the game, force quit it, then relaunch. The mouse worked again after that. + +## Troubleshooting + +### steamcmd: "Failed to load steamconsole.dylib" or a Breakpad.framework popup + +This is macOS Gatekeeper quarantining steamcmd's self-updated libraries, covered in Step 2. +Click **Done** on any "Breakpad.framework" popup (never Move to Trash), then clear the quarantine and re-run: + +```bash +xattr -dr com.apple.quarantine /opt/homebrew/Caskroom/steamcmd/*/MacOS +``` + +### Game won't start in Heroic + +If the game won't start, right-click the game icon in Heroic and select **Logs**. +Common things to look for: D3D errors, missing DLL calls, or Wine prefix initialization failures. + +## What was (not) tested + +Tested on an M4 Pro MacBook Pro (24 GB RAM) running macOS Tahoe 26.4, +with Heroic 2.20.1 and Wine-CrossOver-Latest 23.7.1-1. +Performance and audio were both fine. + +Not tested: + +- Online multiplayer +- The base *Generals* game (only *Zero Hour* was tested) +- Intel Macs +- Mods + +> **Note:** Cross-platform online multiplayer isn't possible yet. +> An Apple Silicon Mac can't play against Windows players or Intel Macs - +> the game desyncs and ends in a mismatch early on. + +## Background: Why not Game Porting Toolkit? + +GPTK was tested but crashes on the splash screen. +The crash is a memory allocation assertion inside Wine's virtual memory layer when running 32-bit executables +through the `x86_32on64` translation path. +Generals is a 32-bit DX8 game, and GPTK's 32-bit-on-64-bit emulation can't handle it. + +The relevant error from the Heroic log: + +```bash +Assertion failed: (end <= pages_vprot_size << pages_vprot_shift), function alloc_pages_vprot, file virtual.c, line 1032. +0024:err:seh:NtRaiseException Exception frame is not in stack limits => unable to dispatch exception. +``` + +This is a bug in GPTK, not something configurable on your end. +Wine-CrossOver handles 32-bit apps through a more mature emulation path and doesn't hit this issue. +If a future GPTK version fixes 32-bit virtual memory allocation on ARM64, +it may be worth retrying since Apple's DirectX-to-Metal translation is theoretically a better long-term path. diff --git a/SourceCode/_Sidebar.md b/SourceCode/_Sidebar.md index b7400b75..06bfa4e2 100644 --- a/SourceCode/_Sidebar.md +++ b/SourceCode/_Sidebar.md @@ -30,6 +30,11 @@ - [Using Cmake (x86) (Windows)](build_with_msvc22) - [Using Cmake (Linux)](build_with_msvc22_linux) +### **Community Guides**: +- **macOS Guides**: + - [Using Heroic & Wine-CrossOver (Apple Silicon)](macos_heroic_wine_crossover.md) + + ### **Other Forks**: - [MSVC22 (x64) Generals Only (Windows)](build_with_msvc22_x64_jmarshall2323)