From 36d9843812b94267b65cefae0f1e33e6e8445312 Mon Sep 17 00:00:00 2001 From: ali Date: Mon, 3 Aug 2026 16:03:41 -0400 Subject: [PATCH] Add macOS setup docs and build/run helper scripts Personal setup for building and running reVC on Apple Silicon (M5): - docs/MACOS_SETUP.md: full instructions (build, game data, audio, windowed mode, controls) - scripts/build_macos.sh: one-shot build using Apple's clang (Homebrew LLVM breaks librw) and generating the gitignored GitSHA1.cpp - scripts/run.sh: launch reVC from the game data folder --- docs/MACOS_SETUP.md | 131 +++++++++++++++++++++++++++++++++++++++++ scripts/build_macos.sh | 42 +++++++++++++ scripts/run.sh | 18 ++++++ 3 files changed, 191 insertions(+) create mode 100644 docs/MACOS_SETUP.md create mode 100755 scripts/build_macos.sh create mode 100755 scripts/run.sh diff --git a/docs/MACOS_SETUP.md b/docs/MACOS_SETUP.md new file mode 100644 index 000000000..f2afe62b8 --- /dev/null +++ b/docs/MACOS_SETUP.md @@ -0,0 +1,131 @@ +# reVC on macOS (Apple Silicon) — Setup Notes + +Personal setup notes for building and running **reVC** (GTA: Vice City reverse-engineering) +on an Apple Silicon Mac (arm64), tested on macOS 26.x (M5). + +## Summary + +- Build system: **premake** (gmake2), target `debug_macosx-arm64-librw_gl3_glfw-oal` + (OpenGL 3 + GLFW windowing + OpenAL audio). +- The game is a clean-room engine re-implementation and **requires a legitimate copy of + GTA: Vice City** for its data files (`models/gta3.img`, `data/`, `audio/`, `text/`, + `anim/`, ...). It ships **no** copyrighted content. +- Two gotchas are handled by `scripts/build_macos.sh`: + 1. **Homebrew LLVM breaks the build** — premake's makefiles set `CC=clang`/`CXX=clang++`, + which resolve to Homebrew LLVM 21.x on this machine and fail to compile `librw` + (libc++ `stdlib.h` errors about `size_t`, `lldiv_t`, `FP_NAN`, ...). Fix: force + Apple's clang via `make CC=/usr/bin/clang CXX=/usr/bin/clang++`. + 2. **`src/extras/GitSHA1.cpp` is generated at build time** — it is gitignored and missing + on a fresh checkout. Generate it with `./printHash.sh src/extras/GitSHA1.cpp`. + +## Prerequisites (Homebrew) + +```bash +brew install glfw openal-soft mpg123 libsndfile unshield p7zip premake +``` + +- `glfw` (>= 3.3), `openal-soft`, `mpg123`, `libsndfile` — build/runtime deps of reVC. +- `unshield` — extracts the InstallShield `.cab` files on the original game discs + (`7z`/`bsdtar` can't read them). +- `p7zip` — general archive work. +- `premake` — only needed to (re)generate the build tree. + +## Build + +```bash +# from the repo root +./scripts/build_macos.sh # = debug build for arm64 +# or a release build +./scripts/build_macos.sh release_macosx-arm64-librw_gl3_glfw-oal +``` + +The script does the equivalent of: + +```bash +# generate premake build tree (only if build/Makefile is missing) +premake5 --with-librw gmake2 + +# generate the git hash source file (gitignored, normally made by a prebuild step) +if [ ! -f src/extras/GitSHA1.cpp ]; then ./printHash.sh src/extras/GitSHA1.cpp; fi + +# compile with APPLE's clang (the Homebrew LLVM on PATH breaks librw) +cd build +make -j"$(sysctl -n hw.ncpu)" CC=/usr/bin/clang CXX=/usr/bin/clang++ \ + config=debug_macosx-arm64-librw_gl3_glfw-oal +``` + +Binary output: `bin/macosx-arm64-librw_gl3_glfw-oal/Debug/reVC` +(or `Release/reVC` for a release build). + +> If the premake build tree already exists (`build/Makefile`), premake is skipped — +> you can just run `make` directly in `build/` with the `CC`/`CXX` overrides above. + +## Game data setup + +Build a game folder (here `~/GTA-VC`) with the original GTA: Vice City data. Example +when the game comes as `VC PC.rar` containing `CD1.iso` and `CD2.iso`: + +```bash +# 1. Extract the rar and mount the images +bsdtar -xf 'VC PC.rar' +hdiutil attach 'VC PC/CD1.iso' -nobrowse -mountpoint /tmp/vccd1 +hdiutil attach 'VC PC/CD2.iso' -nobrowse -mountpoint /tmp/vccd2 + +# 2. The game data lives inside InstallShield .cab archives on CD1 (7z fails; use unshield) +mkdir -p /tmp/gtavc_extract +unshield x /tmp/vccd1/data2.cab -d /tmp/gtavc_extract # main game data +# -> /tmp/gtavc_extract/App_Executables/ is the game root + +# 3. Assemble the game folder +mkdir -p ~/GTA-VC +cp -R /tmp/gtavc_extract/App_Executables/. ~/GTA-VC/ + +# 4. Radio + cutscene audio (from CD2) and the repo's extra gamefiles + the binary +mkdir -p ~/GTA-VC/Audio/Stream +cp /tmp/vccd2/Audio/*.mp3 ~/GTA-VC/Audio/Stream/ +rsync -a /tmp/vccd2/Audio/ ~/GTA-VC/Audio/ # .adf stations + cutscene mp3s +cp bin/macosx-arm64-librw_gl3_glfw-oal/Debug/reVC ~/GTA-VC/reVC +cp -R gamefiles/. ~/GTA-VC/ +chmod +x ~/GTA-VC/reVC +xattr -d com.apple.quarantine ~/GTA-VC/reVC 2>/dev/null || true +``` + +### Audio format note (important) + +The reVC "miami" fork (config `PS2_AUDIO_PATHS`) expects radio audio as +**XOR-0x22 encrypted `.adf`** files in `Audio/` (e.g. `Audio/WILD.ADF`) plus plain +`.mp3` ambience/cutscene files. The original Vice City CDs already ship exactly these +(`WILD.adf`, `FLASH.adf`, ... on CD2's `Audio/`), so copying CD2's `Audio/` contents into +the game's `Audio/` makes sound (radio, SFX, cutscenes) work. Without them reVC **hard +aborts** with "reVC Error! Can't open 'AUDIO\WILD.ADF'". + +## Run + +```bash +cd ~/GTA-VC && ./reVC +# or: ~/GTA-VC/run.sh (see scripts/run.sh) +``` + +### Controls / input + +- **Menus are keyboard-driven** (authentic): Arrow/WASD to move, **Enter** to confirm, + **Backspace** to go back. Mouse clicks do **not** operate menus. +- **In-game mouse**: left = fire, right = lock target, wheel = cycle weapon/radio. +- Mouse bindings live in `~/GTA-VC/reVC.ini` → `[Bindings]`. + +### Window size / windowed vs fullscreen + +Edit `~/GTA-VC/reVC.ini` → `[VideoMode]`: + +```ini +[VideoMode] +Width=1280 +Height=720 +Depth=32 +Subsystem=0 +Windowed=1 ; 1 = windowed, 0 = fullscreen +``` + +If the game window ever "doesn't accept clicks", make sure it is the **frontmost/focused +window** (click its title bar, or `osascript` activation). + diff --git a/scripts/build_macos.sh b/scripts/build_macos.sh new file mode 100755 index 000000000..e72ca1af8 --- /dev/null +++ b/scripts/build_macos.sh @@ -0,0 +1,42 @@ +#!/bin/bash +# Build reVC for macOS (Apple Silicon) using Apple's clang. +# Handles the two gotchas that otherwise break a fresh build: +# 1) Homebrew LLVM on PATH breaks librw -> force CC/CXX to Apple's clang. +# 2) src/extras/GitSHA1.cpp is gitignored/generated -> create it if missing. +set -e +cd "$(dirname "$0")/.." +ROOT="$(pwd)" + +CONFIG="${1:-debug_macosx-arm64-librw_gl3_glfw-oal}" + +echo "== reVC macOS build -- config: $CONFIG ==" + +# 1) Ensure the premake build tree exists +if [ ! -f build/Makefile ]; then + if ! command -v premake5 >/dev/null; then + echo "premake5 not found. Install it: brew install premake" >&2 + exit 1 + fi + echo "== Generating premake build tree ==" + premake5 --with-librw gmake2 +fi + +# 2) Generate the git hash source file if missing +if [ ! -f src/extras/GitSHA1.cpp ]; then + echo "== Generating src/extras/GitSHA1.cpp ==" + ./printHash.sh src/extras/GitSHA1.cpp +fi + +# 3) Build (Apple clang only — Homebrew LLVM breaks librw) +echo "== make -j$(sysctl -n hw.ncpu) config=$CONFIG ==" +cd build +make -j"$(sysctl -n hw.ncpu)" CC=/usr/bin/clang CXX=/usr/bin/clang++ config="$CONFIG" + +if [[ "$CONFIG" == debug_* ]]; then BUILDCFG=Debug +elif [[ "$CONFIG" == release_* ]]; then BUILDCFG=Release +else BUILDCFG="?" +fi +PLATFORM="${CONFIG#debug_}" +PLATFORM="${PLATFORM#release_}" +echo +echo "Done. Binary: $ROOT/bin/$PLATFORM/$BUILDCFG/reVC" diff --git a/scripts/run.sh b/scripts/run.sh new file mode 100755 index 000000000..0170a8eff --- /dev/null +++ b/scripts/run.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Launch reVC from the game data folder. +# +# Usage: +# ./scripts/run.sh [GAME_DIR] +# Default game dir: ~/GTA-VC +set -e + +GAME="${1:-$HOME/GTA-VC}" + +if [ ! -f "$GAME/reVC" ]; then + echo "reVC binary not found in '$GAME'." >&2 + echo "Build it first (./scripts/build_macos.sh) and copy bin/*/Debug/reVC into the game folder." >&2 + exit 1 +fi + +cd "$GAME" +exec ./reVC