Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
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.shnew file mode 100755index 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.jsonnew file mode 100644index 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 filediff --git a/Tests/Fixtures/homes/0.9.0/engine/manifest.json b/Tests/Fixtures/homes/0.9.0/engine/manifest.jsonnew file mode 100644index 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 filediff --git a/Tests/Fixtures/homes/0.9.0/listing.txt b/Tests/Fixtures/homes/0.9.0/listing.txtnew file mode 100644index 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+./manifestsdiff --git a/Tests/Fixtures/homes/0.9.0/snapshot.json b/Tests/Fixtures/homes/0.9.0/snapshot.jsonnew file mode 100644index 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.swiftnew file mode 100644index 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")+ }+ }+}