Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

Upgrade replays: every released home shape is frozen and replayed (reliability plan)

Gauthier Piarrette7a4b42c13a08
diff --git a/Scripts/snapshot-home.sh b/Scripts/snapshot-home.sh
new file mode 100755
index 0000000..a82418d
--- /dev/null
+++ b/Scripts/snapshot-home.sh
@@ -0,0 +1,25 @@
+#!/bin/zsh
+# Upgrade replay fixture: the exact files this build writes for a fresh home (engine manifest,
+# bottle settings, library index), frozen under Tests/Fixtures/homes/<version>/ so every later
+# build proves it still reads them (Tests/HighballKitTests/UpgradeReplayTests.swift). The 0.8.0
+# regression (#21) was an on-disk shape nobody had frozen. Run at each release and commit the
+# folder. Needs the network for the engine unless the real home's download cache is seeded.
+# Usage: Scripts/snapshot-home.sh <version>
+set -euo pipefail
+cd "$(dirname "$0")/.."
+V="${1:?version, e.g. 0.9.0}"
+HB=.build/debug/highball; [ -x "$HB" ] || swift build >/dev/null
+H="${TMPDIR:-/tmp}/hb-snapshot-$V"; rm -rf "$H"; mkdir -p "$H/downloads"
+# Reuse cached tarballs so the engine install takes seconds, not minutes.
+for f in "$HOME/Library/Application Support/Highball/downloads"/*; do [ -f "$f" ] && ln "$f" "$H/downloads/$(basename "$f")" 2>/dev/null || true; done
+HIGHBALL_HOME="$H" "$HB" engine install spike/engine-manifest.json >/dev/null
+HIGHBALL_HOME="$H" "$HB" bottle create Games >/dev/null
+OUT="Tests/Fixtures/homes/$V"; rm -rf "$OUT"; mkdir -p "$OUT/engine" "$OUT/bottle"
+ENGINE_ID=$(python3 -c "import json;print(json.load(open('spike/engine-manifest.json'))['id'])")
+cp "$H/engines/$ENGINE_ID/manifest.json" "$OUT/engine/manifest.json"
+cp "$H/bottles/Games/bottle.json" "$OUT/bottle/bottle.json"
+[ -f "$H/library.json" ] && cp "$H/library.json" "$OUT/library.json"
+(cd "$H" && find . -maxdepth 3 -not -path './downloads*' -not -path '*/drive_c/*' -not -path '*/engine/*' -not -path '*/frameworks/*' -not -path '*/renderers/*' | sort) > "$OUT/listing.txt"
+printf '{"version": "%s", "engine": "%s", "date": "%s"}\n' "$V" "$ENGINE_ID" "$(date +%Y-%m-%d)" > "$OUT/snapshot.json"
+rm -rf "$H"
+echo "snapshot $V: $(ls "$OUT" | tr '\n' ' ')"
diff --git a/Tests/Fixtures/homes/0.9.0/bottle/bottle.json b/Tests/Fixtures/homes/0.9.0/bottle/bottle.json
new file mode 100644
index 0000000..bd94c79
--- /dev/null
+++ b/Tests/Fixtures/homes/0.9.0/bottle/bottle.json
@@ -0,0 +1,29 @@
+{
+ "advertiseAVX" : false,
+ "commandIsControl" : true,
+ "created" : "2026-09-08T01:15:21Z",
+ "dllOverrides" : "",
+ "dpiScale" : 96,
+ "dxvkAppConfig" : {
+
+ },
+ "dxvkAsync" : false,
+ "engineID" : "x64-sikarugir10.0_6-r2",
+ "environment" : {
+
+ },
+ "formatVersion" : 3,
+ "fpsCap" : 0,
+ "metalHUD" : false,
+ "name" : "Games",
+ "pins" : [
+
+ ],
+ "recipes" : [
+
+ ],
+ "renderer" : "dxmt",
+ "rendererExplicit" : false,
+ "sync" : "msync",
+ "windowsVersion" : "win10"
+}
\ No newline at end of file
diff --git a/Tests/Fixtures/homes/0.9.0/engine/manifest.json b/Tests/Fixtures/homes/0.9.0/engine/manifest.json
new file mode 100644
index 0000000..f118895
--- /dev/null
+++ b/Tests/Fixtures/homes/0.9.0/engine/manifest.json
@@ -0,0 +1,107 @@
+{
+ "acceptedLicenses" : [
+
+ ],
+ "arch" : "x86_64",
+ "baseEnv" : {
+ "DYLD_FALLBACK_FRAMEWORK_PATH" : "${frameworks}",
+ "DYLD_FALLBACK_LIBRARY_PATH" : "${frameworks}:${frameworks}/GStreamer.framework/Versions/1.0/lib",
+ "GST_PLUGIN_PATH" : "${frameworks}/GStreamer.framework/Versions/1.0/lib/gstreamer-1.0",
+ "WINEDEBUG" : "fixme-all"
+ },
+ "components" : {
+ "d3dmetal-tsshim" : {
+ "extract" : {
+ "into" : "renderers/d3dmetal-tsshim/wine",
+ "subpath" : "renderers/d3dmetal-tsshim/wine"
+ },
+ "kind" : "renderer",
+ "license" : "MIT",
+ "note" : "D3DMetal timestamp shim: goes on WINEDLLPATH_PREPEND in front of the D3DMetal overlay for D3DMetal launches only (Bottle.environment), never a renderer of its own. At launch Highball hard-links D3DMetal's d3d12.dll beside it as d3d12_d3dmetal.dll and symlinks its x86_64-unix/d3d12.so, because Wine resolves builtin modules by base name. HB_D3D12_TSSHIM=0 leaves it idle.",
+ "order" : 1,
+ "sha256" : "1ac868e6a4a9f713cd4ed22b8b53b2b7dde2e702a39aa23aa19a58448dd4e731",
+ "size" : 46096,
+ "url" : "https://github.com/gauthierpiarrette/highball-engine/releases/download/d3dmetal-tsshim-20260907/d3dmetal-tsshim-20260907.tar.xz",
+ "version" : "20260907"
+ },
+ "dxmt" : {
+ "extract" : {
+ "into" : "renderers/dxmt/wine",
+ "subpath" : "v0.80"
+ },
+ "kind" : "renderer",
+ "license" : "MIT",
+ "sha256" : "8f260e36b5739e68f3bad613381441385c4dc7b85b78ba8de653d5a6a264529d",
+ "size" : 18681669,
+ "url" : "https://github.com/3Shain/dxmt/releases/download/v0.80/dxmt-v0.80-builtin.tar.gz"
+ },
+ "moltenvk" : {
+ "extract" : {
+ "into" : "frameworks/libMoltenVK.dylib",
+ "subpath" : "libMoltenVK.dylib"
+ },
+ "kind" : "runtime",
+ "license" : "Apache-2.0",
+ "note" : "MoltenVK 1.4.1 rebuilt with Highball's shadow-import patch (spike/patches/moltenvk-shadow-import.patch, Scripts/build-moltenvk.sh). Replaces the Template's libMoltenVK.dylib. Off unless a launch sets MVK_SHADOW_IMPORT=1: with it, Wine's wow64 host-memory imports are backed by a private Metal buffer synced on every submit, which is what makes 32-bit native-Vulkan games (The Sims Legacy Collection) render instead of losing the device on every vkQueueSubmit.",
+ "order" : 1,
+ "sha256" : "fbed7b80d6dc2aeaba6fa7047c1fe64827d5004c28029fb43c2bc34f80c35228",
+ "size" : 1674937,
+ "url" : "https://github.com/gauthierpiarrette/highball/releases/download/engine-components/moltenvk-1.4.1-shadow-import-1-x86_64.tar.gz",
+ "version" : "1.4.1+shadow-import-1"
+ },
+ "runtime" : {
+ "extract" : {
+ "into" : "frameworks",
+ "subpath" : "Template-1.0.11.app/Contents/Frameworks"
+ },
+ "kind" : "frameworks",
+ "license" : "mixed (LGPL-2.1 GStreamer, Apache-2.0 MoltenVK, LGPL gnutls, ...)",
+ "sha256" : "9fa15479e7ff6abd99c1d07be285fb95f41fc6991586502427152b1f7d6ccb8a",
+ "size" : 84533420,
+ "url" : "https://github.com/Sikarugir-App/Wrapper/releases/download/v1.0/Template-1.0.11.tar.xz"
+ },
+ "wine" : {
+ "extract" : {
+ "into" : "engine",
+ "strip" : "wswine.bundle"
+ },
+ "kind" : "engine",
+ "license" : "LGPL-2.1+",
+ "sha256" : "9da7ee0cbf386522f3a9906943726d9c3c125dbbd9ab120e3cde80e88d6091b2",
+ "size" : 166304096,
+ "url" : "https://github.com/Sikarugir-App/Engines/releases/download/v1.0/WS12WineSikarugir10.0_6.tar.xz",
+ "version" : "wine-10.0 (Sikarugir) revision 6"
+ },
+ "winetricks" : {
+ "kind" : "tool",
+ "license" : "LGPL-2.1",
+ "note" : "Pinned to upstream commit 5a59ea07 (20260125+dev, 2026-08-07) — the exact bytes 0.7.x verified with dotnet48. The old branch URL drifted and broke every fresh engine install (issues #27/#28); URLs here must be immutable.",
+ "sha256" : "f35c29737ca08a583569e6a3752d52fbe23333c5acfad5f16c4177d25eaf3f4b",
+ "url" : "https://raw.githubusercontent.com/Winetricks/winetricks/5a59ea07513b24093bd90fad943ecf9543cf05bc/src/winetricks"
+ }
+ },
+ "displayName" : "Wine 10.0 (Sikarugir) + DXMT 0.80 + D3DMetal 3.0 + MoltenVK 1.4.1 (shadow-import patch)",
+ "id" : "x64-sikarugir10.0_6-r2",
+ "licenses" : {
+ "apple-gptk-license-2023-08-17" : {
+ "applies" : [
+ "renderers/d3dmetal (bundled in the Sikarugir Template: D3DMetal.framework sha1 1405e5c6… identical to GPTK 3.0-3)"
+ ],
+ "summary" : "Apple Game Porting Toolkit license: non-commercial use/distribution only; no modification; use scoped to developing, testing or evaluating games on Apple hardware.",
+ "text" : "spike/d3dmetal-license.txt"
+ }
+ },
+ "minMacOS" : "14.0",
+ "notes" : [
+ "Engine is Gcenx's Sikarugir build of upstream Wine 10.0: exports macdrv_functions from winemac.so (required by both DXMT and D3DMetal bridges) and supports WINEDLLPATH_PREPEND for per-bottle renderer overlays.",
+ "Vanilla Gcenx wine-devel 11.15 lacks the macdrv_functions export -> DXMT and D3DMetal do NOT work on it. Verified 2026-08-23 with nm.",
+ "Runtime dylibs (GStreamer, MoltenVK, gnutls, freetype, SDL2, icu...) are NOT inside the engine; they come from the Sikarugir Wrapper Template's Frameworks/ and are found via DYLD_FALLBACK_LIBRARY_PATH.",
+ "Wine 10 still ships a wine64 binary but the loader is `wine`; use `wine` so Wine 11 engines work unchanged.",
+ "D3DMetal is NOT downloaded separately: the Template's frameworks/renderer/d3dmetal overlay is used, but only exposed once the user has accepted the Apple GPTK license (recorded in manifest.json as acceptedLicenses).",
+ "r1 (2026-09-02): adds the moltenvk component. Everything else is byte-identical to r0, so existing downloads are reused; only the 5 MB MoltenVK tarball is new.",
+ "r2 (2026-09-07): adds the d3dmetal-tsshim component, a d3d12.dll in front of D3DMetal's that serves DirectX 12 timestamp queries (D3DMetal 3.0 resolves them to zero at a reported 60 Hz, which crashes Guardians of the Galaxy, highball#63). Everything else is byte-identical to r1, so existing downloads are reused; only the 46 KB shim tarball is new. Source: spike/tsshim, Scripts/build-tsshim.sh."
+ ],
+ "requires" : [
+ "rosetta2"
+ ]
+}
\ No newline at end of file
diff --git a/Tests/Fixtures/homes/0.9.0/listing.txt b/Tests/Fixtures/homes/0.9.0/listing.txt
new file mode 100644
index 0000000..fbf3927
--- /dev/null
+++ b/Tests/Fixtures/homes/0.9.0/listing.txt
@@ -0,0 +1,28 @@
+.
+./.trash
+./bottles
+./bottles/Games
+./bottles/Games/.update-timestamp
+./bottles/Games/bottle.json
+./bottles/Games/dosdevices
+./bottles/Games/drive_c
+./bottles/Games/system.reg
+./bottles/Games/user.reg
+./bottles/Games/userdef.reg
+./engines
+./engines/x64-sikarugir10.0_6-r2
+./engines/x64-sikarugir10.0_6-r2/engine
+./engines/x64-sikarugir10.0_6-r2/frameworks
+./engines/x64-sikarugir10.0_6-r2/manifest.json
+./engines/x64-sikarugir10.0_6-r2/renderers
+./engines/x64-sikarugir10.0_6-r2/tools
+./logs
+./logs/2026-09-08T011521Z-Games-wineboot.log
+./logs/2026-09-08T011603Z-Games-reg-2.log
+./logs/2026-09-08T011603Z-Games-reg.log
+./logs/2026-09-08T011604Z-Games-reg-2.log
+./logs/2026-09-08T011604Z-Games-reg.log
+./logs/2026-09-08T011605Z-Games-reg-2.log
+./logs/2026-09-08T011605Z-Games-reg.log
+./logs/2026-09-08T011606Z-Games-reg.log
+./manifests
diff --git a/Tests/Fixtures/homes/0.9.0/snapshot.json b/Tests/Fixtures/homes/0.9.0/snapshot.json
new file mode 100644
index 0000000..8888b52
--- /dev/null
+++ b/Tests/Fixtures/homes/0.9.0/snapshot.json
@@ -0,0 +1 @@
+{"version": "0.9.0", "engine": "x64-sikarugir10.0_6-r2", "date": "2026-09-07"}
diff --git a/Tests/HighballKitTests/UpgradeReplayTests.swift b/Tests/HighballKitTests/UpgradeReplayTests.swift
new file mode 100644
index 0000000..7df4038
--- /dev/null
+++ b/Tests/HighballKitTests/UpgradeReplayTests.swift
@@ -0,0 +1,58 @@
+import XCTest
+@testable import HighballKit
+
+/// Replays every home shape a released build wrote (Tests/Fixtures/homes/<version>, captured by
+/// Scripts/snapshot-home.sh): the bottle settings still decode and list as real, the engine
+/// manifest still loads, the library still shows the game. One fixture per release, forever.
+final class UpgradeReplayTests: XCTestCase {
+ private static var fixturesDir: URL {
+ URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().appending(path: "Fixtures/homes")
+ }
+
+ func testEveryReleasedHomeShapeStillReads() throws {
+ let fm = FileManager.default
+ let versions = (try? fm.contentsOfDirectory(atPath: Self.fixturesDir.path))?.filter { !$0.hasPrefix(".") }.sorted() ?? []
+ try XCTSkipIf(versions.isEmpty, "no snapshots yet: run Scripts/snapshot-home.sh <version>")
+ for version in versions {
+ let fixture = Self.fixturesDir.appending(path: version)
+ let home = fm.temporaryDirectory.appending(path: "hb-replay-\(version)-\(UUID().uuidString)")
+ defer { try? fm.removeItem(at: home) }
+ let paths = HighballPaths(home: home)
+ // The bottle, with a Steam game inside, the way a real home has it.
+ let bottle = paths.bottles.appending(path: "Games")
+ let steam = bottle.appending(path: "drive_c/Program Files (x86)/Steam")
+ try fm.createDirectory(at: steam.appending(path: "steamapps/common/Portal"), withIntermediateDirectories: true)
+ try fm.createDirectory(at: bottle.appending(path: "drive_c/windows"), withIntermediateDirectories: true)
+ try Data().write(to: steam.appending(path: "steam.exe"))
+ try fm.copyItem(at: fixture.appending(path: "bottle/bottle.json"), to: bottle.appending(path: "bottle.json"))
+ try """
+ "AppState"\n{\n\t"appid"\t\t"400"\n\t"name"\t\t"Portal"\n\t"installdir"\t\t"Portal"\n\t"StateFlags"\t\t"4"\n\t"SizeOnDisk"\t\t"1000"\n}
+ """.write(to: steam.appending(path: "steamapps/appmanifest_400.acf"), atomically: true, encoding: .utf8)
+ // The engine's manifest as written by that build.
+ let snapshot = try JSONSerialization.jsonObject(with: Data(contentsOf: fixture.appending(path: "snapshot.json"))) as? [String: Any]
+ let engineID = try XCTUnwrap(snapshot?["engine"] as? String)
+ let engineDir = paths.engine(engineID)
+ try fm.createDirectory(at: engineDir, withIntermediateDirectories: true)
+ try fm.copyItem(at: fixture.appending(path: "engine/manifest.json"), to: engineDir.appending(path: "manifest.json"))
+ if fm.fileExists(atPath: fixture.appending(path: "library.json").path) {
+ try fm.copyItem(at: fixture.appending(path: "library.json"), to: home.appending(path: "library.json"))
+ }
+
+ let store = BottleStore(paths: paths)
+ let bottles = try store.list()
+ XCTAssertEqual(bottles.map(\.name), ["Games"], "\(version): the environment lists")
+ XCTAssertTrue(try store.damaged().isEmpty, "\(version): and is not damaged")
+ XCTAssertEqual(bottles.first?.settings.engineID, engineID, "\(version): on its engine")
+ let engines = try EngineStore(paths: paths).installedEngines()
+ XCTAssertEqual(engines.map(\.id), [engineID], "\(version): the engine manifest loads")
+ let games = bottles.first.map { SteamLibrary.games(in: $0) } ?? []
+ let items = LibraryIndex.build(bottles: bottles, steamByBottle: ["Games": games], epicOwned: [], epicInstalls: [:],
+ plays: LibraryStore(paths: paths).load())
+ XCTAssertEqual(items.first?.title, "Portal", "\(version): the library shows the game")
+ XCTAssertNoThrow(LibraryStore(paths: paths).rendererOverrides(), "\(version): the library file reads")
+ // And today's encoder still writes what that build can read back: a round trip.
+ if var b = bottles.first { b.settings.renderer = b.settings.renderer; XCTAssertNoThrow(try b.save(), "\(version): settings save") }
+ XCTAssertTrue(try store.damaged().isEmpty, "\(version): still not damaged after a save")
+ }
+ }
+}