Guide 01

Installation

How to build the game from source on macOS, run it against your own THUG1 PC data, and pack a double-clickable app in a disk image.

Goal./build-macos.sh and play. Then ./build_dmg.sh for a THUG.app anyone can drag to Applications.

1Get the tools

Xcode Command Line Tools for clang and flex, Homebrew for cmake and ninja (the script installs those two if they're missing). SDL2, glad, glm, miniaudio and the QScript compiler are vendored and built from source.

shellterminal

xcode-select --install

2Build

One script: configures CMake with Ninja, builds the game and the script compiler, compiles Scripts/*.q into Game/Data/scripts/, and clones your ../Data into Game/Data.

shellterminal

./build-macos.sh                       # Release, data from ../Data
./build-macos.sh Debug ~/Games/THUG/Data
./Game/THUG

The data copy is cp -c, an APFS clone. Gigabytes of skate park, zero bytes of disk. Apple got one right.

excerptbuild-macos.sh

# CMAKE_POLICY_VERSION_MINIMUM: the vendored SDL/glm declare cmake_minimum_required < 3.5,
# which CMake 4.x refuses without this.
cmake -S "$ROOT" -B "$BUILD_DIR" -G Ninja \
	-DCMAKE_BUILD_TYPE="$BUILD_TYPE" \
	-DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
	-Wno-dev
cmake --build "$BUILD_DIR" --parallel

# Never overwrite the scripts compiled by the build
[[ "$name" == "scripts" ]] && continue
cp -cR "$dir" "$ROOT/Game/Data/$name" 2>/dev/null || cp -R "$dir" "$ROOT/Game/Data/$name"

First boot: the main menu, with keyboard hints because the keyboard was the last thing touched.

3Let the build output go somewhere else

The DMG build is a universal (arm64 + x86_64) Release in its own folder, so the executable's output directory became a cache variable instead of a hardcoded Game/.

diffCMakeLists.txt · 97790b7

@@ -1057,8 +1057,9 @@ if(TRUE) # SDL2 + OpenGL platform
-	# Send compiled executable to Game folder
-	set(BUILD_DIRECTORY ${CMAKE_SOURCE_DIR}/Game)
+	# Send compiled executable to Game folder (build_dmg.sh builds it elsewhere)
+	set(THUG_EXECUTABLE_DIR "${CMAKE_SOURCE_DIR}/Game" CACHE PATH "Where the THUG executable is built")
+	set(BUILD_DIRECTORY ${THUG_EXECUTABLE_DIR})

4Teach the game it lives in an app bundle

Inside THUG.app/Contents/MacOS/THUG the data sits in Contents/Resources/Data. Detect the bundle by its folder names and point the data path there.

diffWn32/Code/Plat/Sys/File/p_filesys.cpp · 97790b7

@@ -133,9 +135,26 @@ namespace File
+	// Return the Contents folder if running from a macOS app bundle (THUG.app/Contents/MacOS/THUG)
+	static std::filesystem::path GetBundleContentsPath()
+	{
+#if defined(__APPLE__)
+		std::filesystem::path macos_dir = ModulePath().parent_path();
+		std::filesystem::path contents_dir = macos_dir.parent_path();
+		if (macos_dir.filename() == "MacOS" && contents_dir.filename() == "Contents" && contents_dir.parent_path().extension() == ".app")
+			return contents_dir;
+#endif
+		return {};
+	}
+
 	// Return data path
 	static std::filesystem::path GetDataPath()
 	{
+		// In the app bundle, the data is in Contents/Resources
+		std::filesystem::path contents_path = GetBundleContentsPath();
+		if (!contents_path.empty())
+			return contents_path / "Resources" / "Data";
+
 		// Get module path
 		return ModulePath() / "Data";
 	}

Writable things (saves, config.ini, soundtracks) can't go in the bundle: see How save works.

5Pack the disk image

shellterminal

./build_dmg.sh [path/to/Data]          # -> dist/THUG.dmg
ARCHS="arm64" MACOS_MIN=12.0 VERSION=1.1 DMG_FORMAT=ULFO ./build_dmg.sh

# unsigned app: let Gatekeeper know you meant it
xattr -dr com.apple.quarantine /Applications/THUG.app

The script builds the app (icons from icon.png), draws the window background with macos/dmg_art.swift, and lays out the Finder window (app on the left, an Applications link on the right) by scripting Finder, which is why the first run asks for permission to control it.

If Finder asks whether Terminal may control it: yes. It's moving two icons, not your bank account.

FOR EDUCATION PURPOSES ONLY. Screenshots are captured from the port running the reader's own copy of the game. The diffs are trimmed to the interesting lines (unchanged context is cut, marked ⋯); the repository has the full changes. Paths are relative to the THUG/ folder.