Skip to content

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

0.10.21: a game's engine that needs a newer macOS, carry-over with an update waiting, memory note wording (#389)

Gauthier Piarrettec157c7521100
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 4ea76e4..b1652bf 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -410,11 +410,19 @@ final class AppState {
return recipe
}
+ /// The game's own recipe from the database, whatever the channel of the engine it names (fixRecipe hides a recipe
+ /// pinned to a hidden engine), for what Play checks before anything else. An opt-in recipe stays the page's
+ /// business, as everywhere.
+ func gameRecipe(for item: LibraryItem) -> HighballKit.Recipe? {
+ guard let entry = gameDB.entry(for: item), let recipe = Self.recipe(entry.id), recipe.kind == .game, !recipe.isOptIn
+ else { return nil }
+ return recipe
+ }
+
/// The preview engine a game's recipe pins while this Mac does not see it (EngineChannels.previewToOffer): Play
/// asks the player before anything changes. An opt-in recipe stays the page's business, as everywhere.
func previewOffer(for item: LibraryItem) -> (recipe: HighballKit.Recipe, manifest: EngineManifest)? {
- guard let entry = gameDB.entry(for: item), let recipe = Self.recipe(entry.id), recipe.kind == .game, !recipe.isOptIn
- else { return nil }
+ guard let recipe = gameRecipe(for: item) else { return nil }
let defaults = UserDefaults.standard
guard let manifest = EngineChannels.previewToOffer(pin: recipe.engine, bundled: Self.bundledManifests,
beta: defaults.bool(forKey: UpdateChannels.betaDefaultsKey),
@@ -438,6 +446,16 @@ final class AppState {
guard let bottleName = item.bottleName,
let found = bottles.first(where: { $0.name == bottleName }) else { return }
var bottle = found
+ // A recipe whose engine needs a newer macOS than this Mac runs, on every revision the app ships (the arm64 line
+ // needs macOS 26.5, the D3DMetal 4 revisions macOS 27): say so before any question or download. Until 0.10.21
+ // Play offered such an engine on any macOS and nothing stopped its install. An environment already on that
+ // engine plays as it is.
+ if let recipe = gameRecipe(for: item), let id = recipe.engine,
+ let floor = recipe.engineMacOSFloor(bundled: Self.bundledManifests),
+ !(engine(for: bottle).map { EngineManifest.isAtOrAfter(current: $0.manifest.id, wanted: id) } ?? false) {
+ pendingMacOS = (recipe, floor, item, bottle, renderer)
+ return
+ }
// A recipe pinned to a preview engine this Mac does not see yet: before 0.10.19 Play launched the game here
// as if the recipe did not exist, which for Microsoft Flight Simulator 2024 was a Rosetta engine it cannot
// start on. An environment already on that engine counts as the player's choice, and so does one on an
@@ -1483,6 +1501,17 @@ final class AppState {
launch(pending.item, in: pending.bottle, renderer: pending.renderer)
}
+ /// A game whose recipe's engine needs a newer macOS than this Mac runs, asked from Play (Recipe.engineMacOSFloor).
+ var pendingMacOS: (recipe: HighballKit.Recipe, floor: String, item: LibraryItem, bottle: Bottle, renderer: Renderer?)?
+
+ /// The macOS ask's way out that keeps playing: on the current engine, as before the ask existed.
+ func playWithoutMacOSFix() {
+ guard let pending = pendingMacOS else { return }
+ pendingMacOS = nil
+ appendLog("\(pending.item.title): its fix needs macOS \(pending.floor) or later; playing without it.")
+ launch(pending.item, in: pending.bottle, renderer: pending.renderer)
+ }
+
/// An environment on an earlier revision of the preview line its game's recipe pins, asked from Play
/// (Recipe.previewRevisionToOffer). `current` is the revision the environment runs.
var pendingPreviewMove: (recipe: HighballKit.Recipe, bottle: Bottle, current: EngineManifest, manifest: EngineManifest,
diff --git a/Sources/HighballApp/EngineAsk.swift b/Sources/HighballApp/EngineAsk.swift
index af2eba0..9d8b274 100644
--- a/Sources/HighballApp/EngineAsk.swift
+++ b/Sources/HighballApp/EngineAsk.swift
@@ -84,10 +84,20 @@ extension GamePageCopy {
recipe.title, revisionName(manifest), revisionName(current), download)
}
- /// One sentence when the recipe names a memory floor this Mac is under, empty otherwise.
+ /// A game whose recipe's engine needs a newer macOS than this Mac runs (AppState.pendingMacOS). `current` is
+ /// "major.minor.patch", shown without a patch of 0.
+ static func macOSAsk(recipe: HighballKit.Recipe, floor: String, current: String) -> String {
+ let shown = current.hasSuffix(".0") ? String(current.dropLast(2)) : current
+ return String(format: L("%@'s fix runs on an engine that needs macOS %@ or later, and this Mac runs macOS %@. Once macOS is updated, Play sets it up. You can also play without the fix, as before."),
+ recipe.title, floor, shown)
+ }
+
+ /// One sentence when the recipe names a memory floor this Mac is under, empty otherwise. The floor is the memory
+ /// the game was tested with, so the sentence says that rather than a hard requirement: smaller Macs are untested,
+ /// not ruled out (2026-10-19).
static func memoryNote(recipe: HighballKit.Recipe, memoryMB: Int) -> String {
guard let short = recipe.memoryShortfall(memoryMB: memoryMB) else { return "" }
- return " " + String(format: L("It needs about %d GB of memory and this Mac has %d GB, so it is unlikely to run here."),
+ return " " + String(format: L("It was tested on Macs with %d GB of memory and this Mac has %d GB, so it may not run well here."),
short.needGB, short.haveGB)
}
diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swift
index 9b2d1c4..c4c6585 100644
--- a/Sources/HighballApp/HighballApp.swift
+++ b/Sources/HighballApp/HighballApp.swift
@@ -229,6 +229,7 @@ struct ContentView: View {
.updateAsk(state)
.previewAsk(state)
.previewMoveAsk(state)
+ .macOSAsk(state)
.uninstallAsk(state)
.rendererTrialAsk(state)
.modesetTrialAsk(state)
@@ -448,6 +449,17 @@ private extension View {
Text(GamePageCopy.previewAsk(recipe: pending.recipe, manifest: pending.manifest))
}
}
+ /// A game whose recipe's engine needs a newer macOS than this Mac runs (AppState.pendingMacOS).
+ @MainActor func macOSAsk(_ state: AppState) -> some View {
+ self.alert(state.pendingMacOS.map { String(format: L("%@ needs macOS %@"), $0.recipe.title, $0.floor) } ?? "",
+ isPresented: .init(get: { state.pendingMacOS != nil }, set: { if !$0 { state.pendingMacOS = nil } }),
+ presenting: state.pendingMacOS) { _ in
+ Button(L("Play without it")) { state.playWithoutMacOSFix() }
+ Button(L("Not now"), role: .cancel) { state.pendingMacOS = nil }
+ } message: { pending in
+ Text(GamePageCopy.macOSAsk(recipe: pending.recipe, floor: pending.floor, current: EngineManifest.currentMacOS))
+ }
+ }
/// An environment on an earlier revision of the preview line its game's recipe pins (AppState.pendingPreviewMove).
@MainActor func previewMoveAsk(_ state: AppState) -> some View {
self.alert(state.pendingPreviewMove.map { String(format: L("A newer preview engine for %@"), $0.recipe.title) } ?? "",
@@ -736,6 +748,7 @@ struct ErrorDetailsSheet: View {
@MainActor func debugAsks(_ state: AppState) -> String {
"engine ask \(state.pendingEngine.map { "for \($0.manifest.id)" } ?? "not raised"), "
+ "preview ask \(state.pendingPreview.map { "for \($0.manifest.id)" } ?? "not raised"), "
- + "preview move \(state.pendingPreviewMove.map { "from \($0.current.id) to \($0.manifest.id)" } ?? "not raised")"
+ + "preview move \(state.pendingPreviewMove.map { "from \($0.current.id) to \($0.manifest.id)" } ?? "not raised"), "
+ + "macOS ask \(state.pendingMacOS.map { "for macOS \($0.floor)" } ?? "not raised")"
}
#endif
diff --git a/Sources/HighballApp/L10n.swift b/Sources/HighballApp/L10n.swift
index e0759ba..af85076 100644
--- a/Sources/HighballApp/L10n.swift
+++ b/Sources/HighballApp/L10n.swift
@@ -323,6 +323,11 @@ enum L10n {
"%@ nécessite une configuration unique pour fonctionner comme vérifié.",
"Install the fix first": "Installer d'abord le correctif",
"Play without it": "Jouer sans",
+ "%@ needs macOS %@": "%@ nécessite macOS %@",
+ "%@'s fix runs on an engine that needs macOS %@ or later, and this Mac runs macOS %@. Once macOS is updated, Play sets it up. You can also play without the fix, as before.":
+ "Le correctif de %@ utilise un moteur qui nécessite macOS %@ ou plus récent, et ce Mac utilise macOS %@. Une fois macOS mis à jour, Jouer le configure. Vous pouvez aussi jouer sans le correctif, comme avant.",
+ "It was tested on Macs with %d GB of memory and this Mac has %d GB, so it may not run well here.":
+ "Il a été testé sur des Mac avec %d Go de mémoire et ce Mac en a %d, il risque donc de mal fonctionner ici.",
"A newer preview engine for %@": "Un moteur en préversion plus récent pour %@",
"Play on %@": "Jouer sur %@",
"%@ is now verified on %@ of its preview engine, and this environment still runs %@. Moving the environment switches it there%@ and keeps the game and everything else installed. The Windows setup re-runs, which takes a minute or two. Highball asks this once, and the environment's Engine setting can move it later.":
diff --git a/Sources/HighballKit/EngineStore.swift b/Sources/HighballKit/EngineStore.swift
index c10692b..6d0b02a 100644
--- a/Sources/HighballKit/EngineStore.swift
+++ b/Sources/HighballKit/EngineStore.swift
@@ -232,6 +232,12 @@ public struct EngineStore: Sendable {
progress: DownloadProgress? = nil
) async throws -> InstalledEngine {
try paths.ensure()
+ // An engine measured only on a newer macOS is neither offered nor installed on an older one (highball#85).
+ // The engine picker and the updates filtered on it, but Play's engine ask could still install one: the arm64
+ // line on macOS 26.4, where it cannot start (2026-10-19).
+ guard manifest.runs(onMacOS: EngineManifest.currentMacOS) else {
+ throw HighballError.failed("The \(manifest.displayName) engine needs macOS \(manifest.minMacOS) or later, and this Mac runs macOS \(EngineManifest.currentMacOS).")
+ }
// An arm64 engine runs through the signed loader in Highball.app and nothing else, so
// without it the download would only end in an engine that cannot start (WineLoaderHelper).
if manifest.isNativeARM64, WineLoaderHelper.locate() == nil {
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swift
index b4aef5f..3a5aaef 100644
--- a/Sources/HighballKit/Recipe.swift
+++ b/Sources/HighballKit/Recipe.swift
@@ -678,6 +678,18 @@ public extension Recipe {
return offer
}
+ /// The macOS version this recipe's engine needs when no revision the app ships of it runs on `macOS`: the arm64
+ /// line needs features Apple added in macOS 26.5 (4 KB pages for a process, x86 memory ordering per thread), and
+ /// the D3DMetal 4 revisions need macOS 27. Play says so before any question or download, where 0.10.20 offered such
+ /// an engine on any macOS and nothing stopped its install. Nil when a shipped revision runs here, when the recipe
+ /// names no engine, or when the app does not ship it (engineUnknown answers that). `bundled` is every manifest the
+ /// app ships, hidden channels included.
+ func engineMacOSFloor(bundled: [EngineManifest], macOS: String = EngineManifest.currentMacOS) -> String? {
+ guard let id = engine, let wanted = bundled.first(where: { $0.id == id }) else { return nil }
+ let revisions = bundled.filter { EngineManifest.satisfies(current: $0, wanted: wanted) }
+ return revisions.contains { $0.runs(onMacOS: macOS) } ? nil : wanted.minMacOS
+ }
+
/// The engine this recipe names when no manifest this build ships carries it and the
/// environment is not already on it or a later revision of its line: the fix reached the
/// database before the Highball that ships its engine (The Last Flame's r11 pin,
diff --git a/Sources/HighballKit/SteamGameCarryOver.swift b/Sources/HighballKit/SteamGameCarryOver.swift
index 1ab8e54..29649f2 100644
--- a/Sources/HighballKit/SteamGameCarryOver.swift
+++ b/Sources/HighballKit/SteamGameCarryOver.swift
@@ -17,8 +17,10 @@ public enum SteamGameCarryOver {
/// Whether `game` can come along to a new environment made under `bottlesRoot`: fully installed, its folder
/// there, and on the same volume, which a clone needs (a library on an external drive is not copied in full).
+ /// A game with an update waiting comes along too, and the new environment's Steam downloads only the update,
+ /// where 0.10.19 and 0.10.20 left it behind and the new environment downloaded the whole game.
public static func canCarry(_ game: SteamGame, toBottlesRoot bottlesRoot: URL) -> Bool {
- guard game.isReady, let folder = game.installFolder?.resolvingSymlinksInPath(),
+ guard game.isFullyInstalled, let folder = game.installFolder?.resolvingSymlinksInPath(),
FileManager.default.fileExists(atPath: folder.path) else { return false }
return sameVolume(folder, bottlesRoot)
}
@@ -37,7 +39,7 @@ public enum SteamGameCarryOver {
/// Steam on a shared folder (a cloned Steam once downgraded a shared Forza Horizon 6 install, 2026-10-06).
public static func carry(_ game: SteamGame, into destSteamapps: URL,
clone: (URL, URL) throws -> Void = SteamGameCarryOver.cloneTree) -> Outcome {
- guard game.isReady else { return .skipped("it is not fully installed there (Steam state \(game.stateFlags))") }
+ guard game.isFullyInstalled else { return .skipped("it is not fully installed there (Steam state \(game.stateFlags))") }
guard let root = game.libraryRoot, let folder = game.installFolder?.resolvingSymlinksInPath() else {
return .skipped("its install folder is unknown")
}
diff --git a/Sources/HighballKit/SteamLibrary.swift b/Sources/HighballKit/SteamLibrary.swift
index 0a0a218..6b9b7a5 100644
--- a/Sources/HighballKit/SteamLibrary.swift
+++ b/Sources/HighballKit/SteamLibrary.swift
@@ -44,6 +44,11 @@ public struct SteamGame: Identifiable, Sendable, Hashable {
}
/// StateFlags 4 = fully installed; anything else is updating/downloading/broken.
public var isReady: Bool { stateFlags == 4 }
+ /// Every file of the installed build is in its folder: fully installed, at most with an update waiting (StateFlags
+ /// 6, update required). Steam stages an update's files elsewhere until it applies them, so such a folder is whole,
+ /// and a Steam that finds its record updates it as it would any copy. Anything else (downloading, updating, paused,
+ /// files missing) is not.
+ public var isFullyInstalled: Bool { stateFlags & 4 != 0 && stateFlags & ~6 == 0 }
/// Steam CDN artwork (no key needed).
public var headerImage: URL { URL(string: "https://cdn.akamai.steamstatic.com/steam/apps/\(appid)/header.jpg")! }
diff --git a/Tests/HighballKitTests/BundledEngineTests.swift b/Tests/HighballKitTests/BundledEngineTests.swift
index e5550c4..995ef5a 100644
--- a/Tests/HighballKitTests/BundledEngineTests.swift
+++ b/Tests/HighballKitTests/BundledEngineTests.swift
@@ -27,6 +27,18 @@ final class BundledEngineTests: XCTestCase {
}
}
+ /// The arm64 line rests on what Apple added in macOS 26.5 (4 KB pages for a process, the x18 register, x86 memory
+ /// ordering per thread), so no arm64 manifest may say it runs on anything older: 0.10.20 shipped r1, r3 and r5 with
+ /// a floor of 15.0 and Play offered them on any macOS.
+ func testEveryArm64EngineNeedsMacOS26_5() throws {
+ let arm64 = try manifests().filter(\.isNativeARM64)
+ XCTAssertFalse(arm64.isEmpty)
+ for m in arm64 {
+ XCTAssertFalse(m.runs(onMacOS: "26.4.9"), "\(m.id) says it runs below macOS 26.5")
+ XCTAssertTrue(m.runs(onMacOS: "26.5"), "\(m.id) refuses macOS 26.5")
+ }
+ }
+
func testR6CarriesGPTK4D3DMetalOnMacOS27WithTheMetal4BackendOff() throws {
let r6 = try XCTUnwrap(try manifests().first { $0.id == "x64-sikarugir10.0_6-r6" }, "r6 manifest missing")
XCTAssertEqual(r6.minMacOS, "27.0")
diff --git a/Tests/HighballKitTests/EngineChannelsTests.swift b/Tests/HighballKitTests/EngineChannelsTests.swift
index 8575cbd..670f928 100644
--- a/Tests/HighballKitTests/EngineChannelsTests.swift
+++ b/Tests/HighballKitTests/EngineChannelsTests.swift
@@ -8,8 +8,8 @@ final class EngineChannelsTests: XCTestCase {
URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
}
- private func manifest(id: String, channel: String?) throws -> EngineManifest {
- var json: [String: Any] = ["id": id, "displayName": id, "arch": "arm64", "minMacOS": "26.5", "components": [String: Any]()]
+ private func manifest(id: String, channel: String?, minMacOS: String = "26.5") throws -> EngineManifest {
+ var json: [String: Any] = ["id": id, "displayName": id, "arch": "arm64", "minMacOS": minMacOS, "components": [String: Any]()]
if let channel { json["channel"] = channel }
return try JSONDecoder().decode(EngineManifest.self, from: JSONSerialization.data(withJSONObject: json))
}
@@ -101,6 +101,26 @@ final class EngineChannelsTests: XCTestCase {
XCTAssertNil(try recipe(engine: "x64-line-r24").previewRevisionToOffer(current: x64, known: [x64, x64Later], macOS: "27.0"))
}
+ /// The arm64 line needs macOS 26.5 and the D3DMetal 4 revisions macOS 27. On an older macOS Play says so before any
+ /// question or download, instead of offering an engine that cannot start there (2026-10-19).
+ func testARecipeWhoseEngineNeedsANewerMacOSSaysWhichOne() throws {
+ let r5 = try manifest(id: "arm64-line-r5", channel: "preview", minMacOS: "26.5")
+ let game = try recipe(engine: "arm64-line-r5")
+ XCTAssertEqual(game.engineMacOSFloor(bundled: [r5], macOS: "26.4.1"), "26.5")
+ XCTAssertEqual(game.engineMacOSFloor(bundled: [r5], macOS: "15.7"), "26.5")
+ XCTAssertNil(game.engineMacOSFloor(bundled: [r5], macOS: "26.5"))
+ XCTAssertNil(game.engineMacOSFloor(bundled: [r5], macOS: "27.0.0"))
+ let d3dmetal4 = try manifest(id: "x64-line-r18", channel: nil, minMacOS: "27.0")
+ let d3dmetal4Later = try manifest(id: "x64-line-r24", channel: nil, minMacOS: "27.0")
+ XCTAssertEqual(try recipe(engine: "x64-line-r18").engineMacOSFloor(bundled: [d3dmetal4, d3dmetal4Later], macOS: "26.6"), "27.0")
+ XCTAssertNil(try recipe(engine: "x64-line-r18").engineMacOSFloor(bundled: [d3dmetal4, d3dmetal4Later], macOS: "27.0"))
+ // A later revision that runs here is enough.
+ let r6 = try manifest(id: "arm64-line-r6", channel: "preview", minMacOS: "26.0")
+ XCTAssertNil(game.engineMacOSFloor(bundled: [r5, r6], macOS: "26.4"))
+ // A pin the app does not ship keeps its own answer (engineUnknown), and no pin needs nothing.
+ XCTAssertNil(try recipe(engine: "arm64-line-r9").engineMacOSFloor(bundled: [r5], macOS: "15.0"))
+ }
+
func testEveryEngineThePlayersHaveTodayHasNoChannel() throws {
let dir = repo.appending(path: "spike/engines")
let files = try FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)
diff --git a/Tests/HighballKitTests/SteamGameCarryOverTests.swift b/Tests/HighballKitTests/SteamGameCarryOverTests.swift
index 14167e6..808028c 100644
--- a/Tests/HighballKitTests/SteamGameCarryOverTests.swift
+++ b/Tests/HighballKitTests/SteamGameCarryOverTests.swift
@@ -53,6 +53,22 @@ final class SteamGameCarryOverTests: XCTestCase {
guard case .skipped = SteamGameCarryOver.carry(game, into: dest) else { return XCTFail("a game Steam is still writing must not be cloned") }
XCTAssertFalse(FileManager.default.fileExists(atPath: dest.appending(path: "common/MSFS2024").path))
XCTAssertFalse(SteamGameCarryOver.canCarry(game, toBottlesRoot: tmp))
+ // Paused, or files missing, on top of an installed build: not whole either.
+ for state in [4 | 512, 4 | 32, 4 | 2 | 1024] {
+ XCTAssertFalse(SteamGameCarryOver.canCarry(try library("old\(state)", state: state), toBottlesRoot: tmp), "state \(state)")
+ }
+ }
+
+ /// Fully installed with an update waiting (StateFlags 6): the files of the installed build are all there, so the game
+ /// comes along with its record as it is, and the new environment's Steam downloads only the update.
+ func testAGameWithAnUpdateWaitingComesAlongAndKeepsItsRecord() throws {
+ let game = try library("old", state: 6)
+ let dest = try steamapps("new")
+ XCTAssertTrue(SteamGameCarryOver.canCarry(game, toBottlesRoot: tmp))
+ XCTAssertEqual(SteamGameCarryOver.carry(game, into: dest), .carried)
+ XCTAssertEqual(try String(contentsOf: dest.appending(path: "common/MSFS2024/Packages/one.fsarchive"), encoding: .utf8), "package")
+ let record = try String(contentsOf: dest.appending(path: "appmanifest_2537590.acf"), encoding: .utf8)
+ XCTAssertTrue(record.contains("\"StateFlags\" \"6\""), "the record still says an update is required")
}
func testANewEnvironmentThatHasTheGameAlreadyIsLeftAlone() throws {
diff --git a/spike/engines/arm64-wine11.18-r1.json b/spike/engines/arm64-wine11.18-r1.json
index dcef5a2..43bba34 100644
--- a/spike/engines/arm64-wine11.18-r1.json
+++ b/spike/engines/arm64-wine11.18-r1.json
@@ -3,7 +3,7 @@
"id": "arm64-wine11.18-r1",
"displayName": "Wine 11.18 native arm64 (preview) r1",
"arch": "arm64",
- "minMacOS": "15.0",
+ "minMacOS": "26.5",
"requires": [],
"channel": "preview",
"direct3D9": "wined3d",
diff --git a/spike/engines/arm64-wine11.18-r3.json b/spike/engines/arm64-wine11.18-r3.json
index b364010..a298b48 100644
--- a/spike/engines/arm64-wine11.18-r3.json
+++ b/spike/engines/arm64-wine11.18-r3.json
@@ -3,7 +3,7 @@
"id": "arm64-wine11.18-r3",
"displayName": "Wine 11.18 native arm64 (preview) r3",
"arch": "arm64",
- "minMacOS": "15.0",
+ "minMacOS": "26.5",
"requires": [],
"channel": "preview",
"direct3D9": "wined3d",
diff --git a/spike/engines/arm64-wine11.18-r5.json b/spike/engines/arm64-wine11.18-r5.json
index 0459373..6ca6c13 100644
--- a/spike/engines/arm64-wine11.18-r5.json
+++ b/spike/engines/arm64-wine11.18-r5.json
@@ -3,7 +3,7 @@
"id": "arm64-wine11.18-r5",
"displayName": "Wine 11.18 native arm64 (preview) r5",
"arch": "arm64",
- "minMacOS": "15.0",
+ "minMacOS": "26.5",
"requires": [],
"channel": "preview",
"direct3D9": "wined3d",