GeneralsX on Apple Silicon — setup + HD texture toolkit

Run Command & Conquer: Generals — Zero Hour natively on Apple Silicon Macs via GeneralsX — no emulation, no Rosetta — and optionally generate a 4× AI-upscaled HD texture pack (and, for the adventurous, HD terrain) from your own game files.

This repo is a toolkit: setup scripts, tuned config, a reproducible HD-texture build pipeline, an optional engine patch for HD terrain, and step-by-step guides. It contains no game engine and no game assets — you bring your own legally-owned copy of the game.

⚠️ You must own Command & Conquer: Generals — Zero Hour. This project ships only tools and configuration. EA open-sourced the game engine (GPL v3, Feb 2025); the game assets (textures, audio, .big data) remain EA's copyright and are not included here. Every script operates on files you supply from your own installation.

Verified working: M5 Max MacBook Pro 16", macOS 26 (Tahoe), GeneralsX-Beta-13.

What's here

• Native setup — build GeneralsX for arm64, deploy the runtime, optional .app bundle.
• Tuned config — resolution, anti-aliasing, anisotropic filtering (config/).
• HD texture pack builder — AI-upscales your game's textures 4× and packages them as a drop-in mod (personal use only — see below). Standalone: works against a stock, unmodified engine build.
• HD terrain (optional, advanced) — AI-upscales terrain tiles 4×, but the stock engine hardcodes a 64px tile size, so this track also ships a source patch you apply and rebuild the engine with. Not standalone — it's a two-piece kit (patched engine + terrain pack) and the two must be used together.

Two tracks, different commitment levels: the HD texture pack drops onto any working GeneralsX build — no engine changes. HD terrain requires rebuilding GeneralsX from a patched source tree first. Skip terrain entirely and you still get the full texture upgrade.

Prerequisites

Core (engine build + game):

• Apple Silicon Mac (M1 or newer).
• LunarG Vulkan SDK — required. Do not substitute brew install vulkan-headers; it lacks the MoltenVK ICD JSON (the #1 build blocker).
• brew install cmake ninja meson pkgconf ffmpeg glm
• brew install --cask steamcmd (downloads the Windows game files in step 2)
• A legally-owned copy of the game. Both titles are free on Steam: Generals 2229870, Zero Hour 2732960.

HD texture pack (optional):

• brew install imagemagick
• brew install --cask upscayl (bundles the Real-ESRGAN upscaler + models)
• texconv (DDS encoder) + the optional 1x de-artifact NCNN model — vendored locally, not via Homebrew. See tools/README.md for exact fetch/build steps.

HD terrain (optional, advanced):

• Everything the texture pack needs, plus:
• A GeneralsX source checkout you can patch and rebuild (see patches/README.md).
• Upscayl's remacri-4x model installed (terrain is organic detail; remacri-4x is tuned for it, unlike the texture pack's per-class models).

Setup (engine build)

1. Clone the engine

git clone https://github.com/fbraz3/GeneralsX ~/GeneralsX
cd ~/GeneralsX && git checkout GeneralsX-Beta-13     # the version this was verified against

2. Get the game data (your own copy)

Steam has no Mac depot for these titles, so pull the Windows files with steamcmd's force-windows flag (steamcmd comes from the Homebrew cask in Prerequisites):

steamcmd \
  +@sSteamCmdForcePlatformType windows \
  +login <your_steam_user> \
  +app_update 2229870 validate +app_update 2732960 validate +quit

Files land in ~/Library/Application Support/Steam/steamapps/common/. Copy the Zero Hour install (including its ZH_Generals/ base-data subfolder) into ~/GeneralsX/GeneralsZH/.

3. Build, deploy, bundle

cd ~/GeneralsX
./scripts/build/macos/build-macos-zh.sh     # native arm64 build (CMake preset macos-vulkan + Ninja)
./scripts/build/macos/deploy-macos-zh.sh    # stage binary + dylibs + MoltenVK ICD into GeneralsZH/
./scripts/build/macos/bundle-macos-zh.sh    # optional: /Applications/GeneralsXZH.app (ad-hoc signed)

Exact copies of these scripts at the verified version are vendored in scripts/macos/, in case upstream changes them. Upstream keeps them one directory deeper (scripts/build/macos/), so the paths above are correct as written. Note that the vendored run-macos-zh.sh is upstream's developer run helper — it is not the deployed run.sh launcher. The deployed launcher, with the HD-mod auto-load wiring, is config/run.sh; deploy generates run.sh into GeneralsZH/.

4. Apply the config + launch

cp config/Options.ini "$HOME/Library/Application Support/GeneralsX/GeneralsZH/Options.ini"
cp config/dxvk.conf   ~/GeneralsX/GeneralsZH/dxvk.conf
~/GeneralsX/GeneralsZH/run.sh          # fullscreen  (add -win for windowed)

Add -noshellmap only if it ever hangs on the shell map at boot. First launch is slow (shader-cache compile), fast afterward.

HD texture pack (optional)

scripts/build-hd-texture-mod.sh builds a 4×-upscaled HD texture pack from your own game files and installs it as a drop-in mod that both launchers auto-load.

brew install imagemagick
brew install --cask upscayl          # bundles the Real-ESRGAN upscaler + models
# fetch texconv + (optional) the de-artifact model — see tools/README.md
./scripts/build-hd-texture-mod.sh    # writes the pack to ~/GeneralsX-HD/

What it does, end to end:

• Extracts every color texture ≤512px from TexturesZH.big, plus a curated set of additions (1024px UI screens, TGAs, a handful of EnglishZH backdrops, and MapsZH minimap previews — 3,663 files total; see the coverage table below).
• Alpha-safe upscaling: bleeds edge color into fully-transparent regions before upscaling (fixes a dark-halo artifact around cutouts), then upscales the alpha channel as its own pass through the same 4x model instead of letting the upscaler blur it.
• Optional de-artifact pre-pass: if the 1x de-artifact model is installed (tools/README.md), it runs before the 4x upscale to clean up existing DXT block-compression artifacts so they don't get amplified.
• Per-class calibrated models: --calibrate scores every installed 4x model against sample textures from each filename-prefix class (by downscale-consistency) and picks the best model per class, instead of using one fixed model for everything.
• Encodes DXT1 via texconv, DXT5 via ImageMagick. texconv produces cleaner mip chains, but its BC3 (DXT5) codec alpha-weights color and darkens edges under transparency — so opaque textures go through texconv and textures with an alpha channel go through ImageMagick's encoder instead. See tools/README.md for why.
• Splits the result into sub-2 GiB .big archives (see the warning below) and writes them to ~/GeneralsX-HD/.

Why the split matters: the BIG archive format stores file offsets as a signed 32-bit int, so any single .big over 2 GiB wraps to a negative offset and its textures render as the magenta missing-texture placeholder. The build script keeps each mod archive under ~1.8 GB automatically.

Both launchers auto-load ~/GeneralsX-HD when it exists (they append -mod for you) — see the block near the bottom of config/run.sh. A rebuild/redeploy of the engine regenerates run.sh from GeneralsX's own template and drops that block; reapply it (copy it from config/run.sh, or see the "Launcher wiring" note in docs/texture-upgrade-plan.md) to both ~/GeneralsX/GeneralsZH/run.sh and /Applications/GeneralsXZH.app/Contents/MacOS/run.sh after every redeploy.

⚠️ The upscaled textures are a derivative of EA's copyrighted assets. Keep them for your own use; do not redistribute them. This tool exists so each user generates the pack from their own game — that's the legal, intended path.

v1 → v2, what changed

The pipeline shipped once (v1, 3,482 textures, single fixed model) and was then reworked (v2, current). If you're rebuilding fresh you're already on v2 — this is background for anyone comparing against the old writeup:

Area	v1	v2
Alpha edges	upscaler saw garbage color under transparent pixels → dark halos	edge color bled into alpha=0 first; alpha upscaled as its own pass
Encoder	ImageMagick DDS writer (tent-filter mips, no gamma)	texconv for DXT1, ImageMagick for DXT5 (BC3 alpha-color bug)
Pre-pass	none	optional 1x de-artifact model, cleans DXT block artifacts before upscaling
Model selection	one fixed model (ultrasharp-4x) for everything	--calibrate picks the best model per filename-prefix class, gated by an SSIM QA check
Coverage	3,482 textures (TexturesZH.big only)	3,663 — adds 1024px screens, TGAs, 8 EnglishZH backdrops, 109 MapsZH previews

Full engineering notes, verified assumptions, and the terrain-patch design are in docs/texture-v2-and-terrain-plan.md.

HD terrain (optional, advanced)

The stock GeneralsX engine — like the original 2003 game — hardcodes terrain tiles to a fixed 64×64 pixel size with a matching fixed mip chain. Dropping higher-resolution terrain textures in without changing that ceiling doesn't render sharper terrain; the loader misreads the extra pixels as unrelated tile variants and the map comes out scrambled. So HD terrain is a two-part kit:

1. An engine patch (patches/hd-terrain-256.patch, documented in patches/README.md) that raises the tile size to 256px, restructures the mip chain to match, and adds a loader-side fallback so stock 64px terrain (and every existing custom map) keeps working unpatched. Apply it to a GeneralsX source checkout and rebuild.
2. The terrain pack itself (scripts/build-hd-terrain-pack.sh), which 4×-upscales each terrain tile independently (wrap-padded so tile borders don't bleed into each other) and writes a separate HDTerrainZH.big.

⚠️ The terrain pack requires the patched engine. Do not load HDTerrainZH.big on a stock (unpatched) build — the 256px tile sheets will be misread the same way oversized TGAs are on stock GeneralsX, and terrain will render incorrectly. The patch and the pack are a matched set; only use them together.

Graphics tuning

Config lives in ~/Library/Application Support/GeneralsX/GeneralsZH/Options.ini. See config/Options.ini:

IdealStaticGameLOD = High
StaticGameLOD = High
Resolution = 2560 1600
AntiAliasing = 4
TextureFilter = Anisotropic
AnisotropyLevel = 16

• Resolution — the port pillarboxes the game resolution down to your display's logical resolution. Set it at or above your desktop resolution and the game presents at your desktop's full logical size (e.g. 2560 1600 raised the swapchain from the 1024×768 default to 1728×1084 on a 16" panel at default scaling).
• The retina ceiling — the port renders at your desktop logical resolution, not the panel's native physical resolution (full HiDPI is incomplete upstream). To go sharper, set System Settings → Displays → "More Space" before launching; the game follows the desktop.
• Anisotropic filtering (TextureFilter + AnisotropyLevel) sharpens textures at oblique angles (terrain/roads into the distance) — the best native lever short of the HD pack above.
• Game LOD (IdealStaticGameLOD + StaticGameLOD = High) pins the detail preset so the engine's auto-detect can't quietly drop model/effect quality.

DXVK-level options (d3d8→d3d9 path) live in config/dxvk.conf.

Troubleshooting / known limitations

• Build fails looking for a Vulkan ICD → you're on brew vulkan-headers instead of the LunarG SDK. Install the SDK; the launcher sets VK_ICD_FILENAMES to the MoltenVK ICD.
• codesign --deep fails on the app bundle → a stray symlink in Contents/MacOS/. Remove it, then codesign --force --sign - <app> (no --deep).
• Magenta textures after installing an HD pack → a single .big exceeded 2 GiB (see the split note above). Rebuild with the script, which keeps each archive under the limit.
• Gatekeeper → a locally built app has no com.apple.quarantine xattr, so it double-clicks clean. spctl --assess reports "unnotarized," which is moot without quarantine.
• LAN/online multiplayer is broken upstream.
• Incomplete HiDPI support (the retina cap above; a known mouse-offset gap on Retina).
• Young renderer — minor texture/minimap glitches are possible.
• HD terrain specifically: visible seams at some tile boundaries are possible (the upscaler runs per-tile, not on the assembled map), and per-tile working memory grows roughly 16× (~21 MB → ~333 MB worst case on a large map) — fine on modern hardware, but worth knowing if you're on a memory-constrained Mac.

Repo layout

config/                            Options.ini, dxvk.conf, and the deployed run.sh launcher
patches/                           engine patches (HD terrain) — see patches/README.md
patches/hd-terrain-256.patch       the HD terrain tile-size patch
tools/                             vendored texconv + de-artifact model — see tools/README.md
scripts/build-hd-texture-mod.sh    the AI HD-texture-pack builder (entry point)
scripts/build-hd-terrain-pack.sh   the AI HD-terrain-pack builder (entry point)
scripts/hdtex/                     the texture/terrain pipeline itself (Python)
scripts/macos/                     vendored copies of upstream's macOS build/deploy/bundle scripts
docs/texture-upgrade-plan.md       v1 build + debug writeup (superseded by the v2 doc below)
docs/texture-v2-and-terrain-plan.md   v2 texture pipeline + HD terrain engineering notes
sync.sh                            pull live config back into config/ (maintenance helper)

Credits

• GeneralsX (fbraz3) — the macOS/Linux port this builds on.
• TheSuperHackers / GeneralsGameCode — upstream engine maintenance.
• Electronic Arts — for open-sourcing the Generals engine (Feb 2025) and the original game.
• Upscayl / Real-ESRGAN — the texture upscaler used by the HD builder.

License

Tooling in this repo is licensed under GPL v3 (LICENSE), matching the GeneralsX ecosystem it builds on. The vendored scripts/macos/ build scripts are from GeneralsX (GPL v3, © the GeneralsX / TheSuperHackers authors). No game engine or assets are included — those are EA's property; supply your own legally-owned copy.

EA has not endorsed and does not support this project. All trademarks are the property of their respective owners.