Skip to content

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

A game verified on a preview engine is one click away, and a new environment takes the installed game along. Microsoft Flight Simulator 2024's first outside tester (M1 Max, 2026-10-17) needed a Terminal command to see the native arm64 engine, then a new environment and a fresh 50 GB download; without the command Play launched the game on its Rosetta engine, where it cannot start, because a recipe pinned to a hidden preview engine was ignored (EngineChannels.hidesPin). Now Play asks ("… runs on a preview engine": Use the preview engine, Play without it, Not now). Accepting adds that one engine to previewEngineOptIns, not every preview engine, and Play goes on to the usual engine ask; an environment already on that engine counts as the player's choice, and the game page is unchanged. A new environment made from the engine ask clones the game installed where Play started (SteamGameCarryOver: clonefile(2), the appmanifest copied beside it, the new Steam stopped first so it reads the record): no download, no extra disk, the original untouched. A clone the file system refuses (another volume, not APFS) leaves nothing and falls back to the download; a game folder that links to another environment's copy is resolved first, so a second Steam never shares a folder. The done row then offers Play instead of Install, and the engine ask says the game comes along. A recipe's minMemoryGB (MSFS: 32, highball-db 1276b50) makes the preview and engine asks say when this Mac has less. 564 tests pass (new: EngineChannelsTests opt-ins and previewToOffer, SteamGameCarryOverTests with a real clone, RecipeMemoryFloorTests). Clicked through on an M1 Pro in a throwaway Highball home with an Intel environment holding a stand-in MSFS install: the preview ask with the memory sentence, the opt-in stored, the engine ask, a new environment with Steam installed by its recipe and the game cloned byte for byte in about 40 seconds, the done row offering Play; the no-fit ask's wording seen separately. The owner's preferences were backed up and restored around the test.

Gauthier Piarrette8c883ad052e3
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 24dd101..fa6aa38 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -405,10 +405,24 @@ final class AppState {
let defaults = UserDefaults.standard
if EngineChannels.hidesPin(recipe.engine, bundled: Self.bundledManifests,
beta: defaults.bool(forKey: UpdateChannels.betaDefaultsKey),
- preview: defaults.bool(forKey: EngineChannels.previewDefaultsKey)) { return nil }
+ preview: defaults.bool(forKey: EngineChannels.previewDefaultsKey),
+ optedIn: Self.previewOptIns) { 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 }
+ let defaults = UserDefaults.standard
+ guard let manifest = EngineChannels.previewToOffer(pin: recipe.engine, bundled: Self.bundledManifests,
+ beta: defaults.bool(forKey: UpdateChannels.betaDefaultsKey),
+ preview: defaults.bool(forKey: EngineChannels.previewDefaultsKey),
+ optedIn: Self.previewOptIns) else { return nil }
+ return (recipe, manifest)
+ }
+
/// The "never pick a bottle first" guarantee: every Play in the library resolves the
/// item's own bottle and dispatches by source. Play also means "make it work the way
@@ -424,6 +438,18 @@ final class AppState {
guard let bottleName = item.bottleName,
let found = bottles.first(where: { $0.name == bottleName }) else { return }
var bottle = found
+ // 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; any other asks first.
+ if fixRecipe(for: item) == nil, let offer = previewOffer(for: item) {
+ if let current = engine(for: bottle), EngineManifest.satisfies(current: current.manifest, wanted: offer.manifest) {
+ Self.optInPreview(offer.manifest.id)
+ play(item, renderer: renderer, windowsBuild: windowsBuild)
+ } else {
+ pendingPreview = (offer.recipe, bottle, offer.manifest, item, renderer)
+ }
+ return
+ }
// A game whose recipe was applied before variables were scoped still has them bottle-wide,
// where every other program inherits them (highball#198). Move them to the game once; the
// launch below then carries them for this game only, and the log says what moved. Then the
@@ -1423,6 +1449,34 @@ final class AppState {
/// still run it without the fix, or nil when the page's own button asked for the fix.
var pendingUpdate: (recipe: HighballKit.Recipe, engineID: String, play: (item: LibraryItem, bottle: Bottle, renderer: Renderer?)?)?
+ /// A game whose recipe pins a preview engine this Mac does not see yet, asked from Play (previewOffer).
+ var pendingPreview: (recipe: HighballKit.Recipe, bottle: Bottle, manifest: EngineManifest, item: LibraryItem, renderer: Renderer?)?
+
+ /// The preview ask's way in: that engine is offered on this Mac from now on, and Play goes on to the usual
+ /// engine ask, which makes the environment (the game coming along when it can).
+ func acceptPreview() {
+ guard let pending = pendingPreview else { return }
+ pendingPreview = nil
+ Self.optInPreview(pending.manifest.id)
+ appendLog("\(pending.item.title): the \(pending.manifest.id) preview engine is offered on this Mac from now on")
+ play(pending.item, renderer: pending.renderer)
+ }
+
+ /// The preview ask's way out that keeps playing: as before the ask existed, on the current engine.
+ func playWithoutPreview() {
+ guard let pending = pendingPreview else { return }
+ pendingPreview = nil
+ appendLog("\(pending.item.title): its fix needs the \(pending.manifest.id) preview engine; playing without it.")
+ launch(pending.item, in: pending.bottle, renderer: pending.renderer)
+ }
+
+ /// Whether the game Play started from `bottle` can come along to a new environment as a clone.
+ func canCarryGame(_ item: LibraryItem?, from bottle: Bottle) -> Bool {
+ guard let item, item.source == .steam, let appid = item.steamAppID,
+ let game = (gamesByBottle[bottle.name] ?? []).first(where: { $0.appid == appid }) else { return false }
+ return SteamGameCarryOver.canCarry(game, toBottlesRoot: paths.bottles)
+ }
+
/// The ask's first way out: a new environment on the engine the recipe names, the recipe
/// applied; the engine downloads first when it is not installed. A new environment starts
/// without the game, so for a Steam game the done row's button hands it to that environment's
@@ -1433,10 +1487,24 @@ final class AppState {
let name = BottleStore.freeName(recipe.title, taken: Set(bottles.map(\.name)))
let accepted = Set(engines.flatMap { $0.manifest.acceptedLicenses ?? [] })
let done: DoneState
+ // The game installed where Play started comes along as a clone when it can (SteamGameCarryOver): no second
+ // download, no extra disk, the original untouched. The done row then offers Play; `carried` says what
+ // actually happened, so a clone the file system refuses at the last moment still ends in Install.
+ let source = item.flatMap { item in bottles.first { $0.name == item.bottleName } }
+ let carries = source.map { canCarryGame(item, from: $0) } ?? false
+ let carried = CarryFlag()
if let item, item.source == .steam {
done = DoneState(title: String(format: L("The %@ environment is ready"), name),
- ctaTitle: String(format: L("Install %@"), displayTitle(item)),
- cta: { [weak self] in self?.installSteamGame(item.homed(in: name)) })
+ ctaTitle: String(format: carries ? L("Play %@") : L("Install %@"), displayTitle(item)),
+ cta: { [weak self] in
+ guard let self else { return }
+ if carried.value {
+ self.refresh()
+ self.play((self.libraryItems.first { $0.id == item.id } ?? item).homed(in: name))
+ } else {
+ self.installSteamGame(item.homed(in: name))
+ }
+ })
} else {
done = DoneState(title: String(format: L("%@ installed"), recipe.title), ctaTitle: nil, cta: nil)
}
@@ -1469,10 +1537,30 @@ final class AppState {
}
notes += try await runner.apply(recipe, resolve: { Self.recipe($0) }) { line in Task { @MainActor in self.appendLog(line) } }
for n in notes { await MainActor.run { self.appendLog("note: \(n)") } }
+ if carries, let item, let appid = item.steamAppID, let source,
+ let game = SteamLibrary.games(in: source).first(where: { $0.appid == appid }),
+ let steam = SteamLibrary.steamRoot(of: runner.bottle) {
+ // The new environment's Steam reads the record when it next starts, so it is stopped first; a Steam
+ // already running would offer to download the game Play is about to find installed.
+ try? await WineRunner(paths: paths, engine: engine, bottle: runner.bottle).stopSteam()
+ let outcome = SteamGameCarryOver.carry(game, into: steam.appending(path: "steamapps", directoryHint: .isDirectory))
+ await MainActor.run {
+ switch outcome {
+ case .carried:
+ carried.value = true
+ self.appendLog("\(item.title): carried over from '\(source.name)' as a clone, no download and no extra disk space")
+ case .skipped(let why):
+ self.appendLog("\(item.title): not carried over from '\(source.name)': \(why); the new environment's Steam installs it")
+ }
+ }
+ }
await MainActor.run { self.selectedBottle = name }
}
}
+ /// What the carry-over in createEnvironment did, read by the done row's button.
+ @MainActor final class CarryFlag { var value = false }
+
/// The update ask's way out that keeps playing: the game launches as it would have before
/// the recipe existed, on the current engine, and the log says which fix it went without.
func playWithoutTheFix() {
@@ -2875,7 +2963,20 @@ final class AppState {
let defaults = UserDefaults.standard
let beta = defaults.bool(forKey: UpdateChannels.betaDefaultsKey)
let preview = defaults.bool(forKey: EngineChannels.previewDefaultsKey)
- return bundledManifests.filter { EngineChannels.visible(channel: $0.channel, beta: beta, preview: preview) }
+ let optedIn = previewOptIns
+ return bundledManifests.filter { EngineChannels.visible($0, beta: beta, preview: preview, optedIn: optedIn) }
+ }
+
+ /// Preview engines the player took from Play for a game (EngineChannels.optInDefaultsKey).
+ static var previewOptIns: Set<String> {
+ Set(UserDefaults.standard.stringArray(forKey: EngineChannels.optInDefaultsKey) ?? [])
+ }
+
+ static func optInPreview(_ id: String) {
+ var ids = UserDefaults.standard.stringArray(forKey: EngineChannels.optInDefaultsKey) ?? []
+ guard !ids.contains(id) else { return }
+ ids.append(id)
+ UserDefaults.standard.set(ids, forKey: EngineChannels.optInDefaultsKey)
}
/// Every engine manifest the app ships, visible or not: the default one plus
diff --git a/Sources/HighballApp/EngineAsk.swift b/Sources/HighballApp/EngineAsk.swift
index 47f2dda..5cb346b 100644
--- a/Sources/HighballApp/EngineAsk.swift
+++ b/Sources/HighballApp/EngineAsk.swift
@@ -27,25 +27,58 @@ extension GamePageCopy {
/// in it; the ask then offers it first (highball-db#318).
/// `canMove` is false when the environment's engine is of another architecture than the
/// recipe's (EngineStore.sameArch): only a new environment is offered then.
+ /// `carriesGame` is true when the game installed in this environment can come along to a new one as an APFS
+ /// clone (SteamGameCarryOver): no second download, no extra disk. `memoryMB` is this Mac's memory, checked
+ /// against the recipe's minMemoryGB.
static func engineAsk(recipe: HighballKit.Recipe, manifest: EngineManifest, installed: Bool, others: Int,
- existing: (name: String, holdsGame: Bool)? = nil, canMove: Bool = true) -> String {
+ existing: (name: String, holdsGame: Bool)? = nil, canMove: Bool = true,
+ carriesGame: Bool = false, memoryMB: Int = Machine.memoryMB) -> String {
guard let existing else {
- guard canMove else { return engineAskOtherArch(recipe: recipe, manifest: manifest, installed: installed) }
+ guard canMove else {
+ return engineAskOtherArch(recipe: recipe, manifest: manifest, installed: installed, carriesGame: carriesGame)
+ + memoryNote(recipe: recipe, memoryMB: memoryMB)
+ }
return engineAskBody(recipe: recipe, manifest: manifest, installed: installed, others: others)
+ + memoryNote(recipe: recipe, memoryMB: memoryMB)
}
- return existing.holdsGame
+ return (existing.holdsGame
? String(format: L("'%@' is already on the %@ engine and has the game installed, so it plays there. This environment stays as it is."), existing.name, shortEngineName(manifest))
- : String(format: L("'%@' is already on the %@ engine. Using it installs the game there, with what it needs, and this environment stays as it is."), existing.name, shortEngineName(manifest))
+ : String(format: L("'%@' is already on the %@ engine. Using it installs the game there, with what it needs, and this environment stays as it is."), existing.name, shortEngineName(manifest)))
+ + memoryNote(recipe: recipe, memoryMB: memoryMB)
}
- private static func engineAskOtherArch(recipe: HighballKit.Recipe, manifest: EngineManifest, installed: Bool) -> String {
+ private static func engineAskOtherArch(recipe: HighballKit.Recipe, manifest: EngineManifest, installed: Bool,
+ carriesGame: Bool) -> String {
let download = installed ? "" : String(format: L(", after a download of about %@"), downloadSize(manifest))
+ if carriesGame {
+ let text = manifest.isNativeARM64
+ ? L("%@ is verified on the %@ engine, which runs natively on Apple silicon. This environment's engine runs through Rosetta, so the environment cannot move to it. A new environment gets a Steam of its own%@, and the game installed here comes along without a new download or extra disk space. This environment stays as it is.")
+ : L("%@ is verified on the %@ engine, which runs through Rosetta. This environment's engine runs natively on Apple silicon, so the environment cannot move to it. A new environment gets a Steam of its own%@, and the game installed here comes along without a new download or extra disk space. This environment stays as it is.")
+ return String(format: text, recipe.title, shortEngineName(manifest), download)
+ }
let text = manifest.isNativeARM64
? L("%@ is verified on the %@ engine, which runs natively on Apple silicon. This environment's engine runs through Rosetta, so the environment cannot move to it. A new environment starts empty%@, and the game has to be installed again.")
: L("%@ is verified on the %@ engine, which runs through Rosetta. This environment's engine runs natively on Apple silicon, so the environment cannot move to it. A new environment starts empty%@, and the game has to be installed again.")
return String(format: text, recipe.title, shortEngineName(manifest), download)
}
+ /// A recipe pinned to a preview engine this Mac does not see yet: Play asks before anything changes. Before
+ /// 0.10.19 Play launched such a game on the current engine as if the recipe did not exist, which for Microsoft
+ /// Flight Simulator 2024 was a Rosetta engine it cannot start on.
+ static func previewAsk(recipe: HighballKit.Recipe, manifest: EngineManifest, memoryMB: Int = Machine.memoryMB) -> String {
+ let text = manifest.isNativeARM64
+ ? L("%@ is verified on the %@ engine, which runs natively on Apple silicon and is still in preview: the game plays, with the rough edges its page lists. Highball offers that engine for this game, sets it up in an environment of its own, and leaves this one as it is.")
+ : L("%@ is verified on the %@ engine, which is still in preview: the game plays, with the rough edges its page lists. Highball offers that engine for this game, sets it up in an environment of its own, and leaves this one as it is.")
+ return String(format: text, recipe.title, shortEngineName(manifest)) + memoryNote(recipe: recipe, memoryMB: memoryMB)
+ }
+
+ /// One sentence when the recipe names a memory floor this Mac is under, empty otherwise.
+ 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."),
+ short.needGB, short.haveGB)
+ }
+
private static func engineAskBody(recipe: HighballKit.Recipe, manifest: EngineManifest, installed: Bool, others: Int) -> String {
let download = installed ? "" : String(format: L(", after a download of about %@"), downloadSize(manifest))
if others == 0 {
diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swift
index 1d17b0f..7b83097 100644
--- a/Sources/HighballApp/HighballApp.swift
+++ b/Sources/HighballApp/HighballApp.swift
@@ -227,6 +227,7 @@ struct ContentView: View {
.d3dMetalAsk(state)
.engineAsk(state)
.updateAsk(state)
+ .previewAsk(state)
.uninstallAsk(state)
.rendererTrialAsk(state)
.modesetTrialAsk(state)
@@ -425,9 +426,23 @@ private extension View {
Text(GamePageCopy.engineAsk(recipe: pending.recipe, manifest: pending.manifest, installed: state.engines.contains { $0.id == pending.manifest.id },
others: state.otherProgramCount(in: pending.bottle, besides: pending.recipe),
existing: pending.fit.map { ($0.name, pending.item?.otherBottles.contains($0.name) == true) },
- canMove: state.canMove(pending.bottle, to: pending.manifest)))
+ canMove: state.canMove(pending.bottle, to: pending.manifest),
+ carriesGame: state.canCarryGame(pending.item, from: pending.bottle)))
}
}
+ /// A game whose recipe pins a preview engine this Mac does not see yet (AppState.previewOffer).
+ @MainActor func previewAsk(_ state: AppState) -> some View {
+ self.alert(state.pendingPreview.map { String(format: L("%@ runs on a preview engine"), $0.recipe.title) } ?? "",
+ isPresented: .init(get: { state.pendingPreview != nil }, set: { if !$0 { state.pendingPreview = nil } }),
+ presenting: state.pendingPreview) { _ in
+ Button(L("Use the preview engine")) { state.acceptPreview() }
+ Button(L("Play without it")) { state.playWithoutPreview() }
+ Button(L("Not now"), role: .cancel) { state.pendingPreview = nil }
+ } message: { pending in
+ Text(GamePageCopy.previewAsk(recipe: pending.recipe, manifest: pending.manifest))
+ }
+ }
+
@MainActor func updateAsk(_ state: AppState) -> some View {
self.alert(state.pendingUpdate.map { String(format: L("%@ needs a newer Highball"), $0.recipe.title) } ?? "",
isPresented: .init(get: { state.pendingUpdate != nil }, set: { if !$0 { state.pendingUpdate = nil } }),
diff --git a/Sources/HighballKit/EngineChannels.swift b/Sources/HighballKit/EngineChannels.swift
index dfef827..9f88a92 100644
--- a/Sources/HighballKit/EngineChannels.swift
+++ b/Sources/HighballKit/EngineChannels.swift
@@ -11,6 +11,9 @@ public enum EngineChannels {
/// The UserDefaults key that shows preview engines. No UI on purpose:
/// `defaults write app.highball.Highball previewEngines -bool true`.
public static let previewDefaultsKey = "previewEngines"
+ /// Preview engines a player took from Play for a game whose recipe asks for one (the ask's "Use the
+ /// preview engine"), by engine id: seen from then on as with the preview key, for those engines only.
+ public static let optInDefaultsKey = "previewEngineOptIns"
public static func visible(channel: String?, beta: Bool, preview: Bool) -> Bool {
switch channel {
@@ -20,12 +23,30 @@ public enum EngineChannels {
}
}
+ /// The same rule for one engine, counting the player's opt-ins: a preview engine they took for a game.
+ public static func visible(_ manifest: EngineManifest, beta: Bool, preview: Bool, optedIn: Set<String>) -> Bool {
+ visible(channel: manifest.channel, beta: beta, preview: preview)
+ || (manifest.channel == Self.preview && optedIn.contains(manifest.id))
+ }
+
/// Whether a recipe's engine pin names a bundled engine this install may not see. Such a recipe
/// is not offered at all: without this, Play would find the pin missing from the visible engines
/// and tell the player to update Highball, though no update would show it either. A pin no
/// bundled manifest carries is not hidden; that case keeps its own "update Highball" answer.
- public static func hidesPin(_ pin: String?, bundled: [EngineManifest], beta: Bool, preview: Bool) -> Bool {
+ public static func hidesPin(_ pin: String?, bundled: [EngineManifest], beta: Bool, preview: Bool,
+ optedIn: Set<String> = []) -> Bool {
guard let pin, let manifest = bundled.first(where: { $0.id == pin }) else { return false }
- return !visible(channel: manifest.channel, beta: beta, preview: preview)
+ return !visible(manifest, beta: beta, preview: preview, optedIn: optedIn)
+ }
+
+ /// The preview engine a recipe pins while this install does not see it: Play offers it instead of
+ /// launching the game as if the recipe did not exist, which for Microsoft Flight Simulator 2024 meant
+ /// a Rosetta engine the game cannot start on (2026-10-18). nil for a visible pin, a pin on another
+ /// hidden channel (beta lines reach players through beta builds) or a pin no bundled manifest carries.
+ public static func previewToOffer(pin: String?, bundled: [EngineManifest], beta: Bool, preview: Bool,
+ optedIn: Set<String>) -> EngineManifest? {
+ guard let pin, let manifest = bundled.first(where: { $0.id == pin }), manifest.channel == Self.preview,
+ !visible(manifest, beta: beta, preview: preview, optedIn: optedIn) else { return nil }
+ return manifest
}
}
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swift
index 3e75961..dfbf7e0 100644
--- a/Sources/HighballKit/Recipe.swift
+++ b/Sources/HighballKit/Recipe.swift
@@ -276,7 +276,17 @@ public struct Recipe: Codable, Sendable, Identifiable {
/// The engine this recipe needs, by manifest id (the EA app needs the Wine 11 tree, #60).
/// Highball offers that engine before applying the recipe to an environment on another Wine.
public var engine: String?
+ /// The memory a Mac needs for this game on the recipe's engine, in GB (Microsoft Flight Simulator 2024 holds
+ /// about 25 GB on the native arm64 line). Data: Play's engine and preview asks say so on a Mac with less, before
+ /// a download that could not run there. nil when the recipe names no floor.
+ public var minMemoryGB: Int?
public var steps: [Step]
+
+ /// The recipe's memory floor and this Mac's memory in GB when the Mac is under it, nil otherwise.
+ public func memoryShortfall(memoryMB: Int) -> (needGB: Int, haveGB: Int)? {
+ guard let need = minMemoryGB, memoryMB < need * 1024 else { return nil }
+ return (need, Int((Double(memoryMB) / 1024).rounded()))
+ }
public var knownIssues: [KnownIssue]?
public var lastVerified: Verification?
public var blocked: Blocked?
diff --git a/Sources/HighballKit/SteamGameCarryOver.swift b/Sources/HighballKit/SteamGameCarryOver.swift
new file mode 100644
index 0000000..1ab8e54
--- /dev/null
+++ b/Sources/HighballKit/SteamGameCarryOver.swift
@@ -0,0 +1,77 @@
+import Darwin
+import Foundation
+
+/// A Steam game installed in one environment, handed to a new environment's Steam as an APFS clone (2026-10-18).
+/// Moving to an engine of the other architecture needs a new environment (an environment never moves between
+/// Rosetta and native engines), and that environment used to start empty: Microsoft Flight Simulator 2024's first
+/// outside tester downloaded the game again, about 50 GB, to try the native arm64 engine. A clone shares every
+/// block with the original until either side writes, so the copy costs no disk and no time, and the original stays
+/// exactly as it was. The Steam record (appmanifest) goes beside it, so the new environment's Steam finds the game
+/// installed and only fetches what an update changed.
+public enum SteamGameCarryOver {
+ public enum Outcome: Equatable, Sendable {
+ case carried
+ /// Why nothing was written, for the log. The new environment's Steam then installs the game as before.
+ case skipped(String)
+ }
+
+ /// 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).
+ public static func canCarry(_ game: SteamGame, toBottlesRoot bottlesRoot: URL) -> Bool {
+ guard game.isReady, let folder = game.installFolder?.resolvingSymlinksInPath(),
+ FileManager.default.fileExists(atPath: folder.path) else { return false }
+ return sameVolume(folder, bottlesRoot)
+ }
+
+ static func sameVolume(_ a: URL, _ b: URL) -> Bool {
+ guard let va = (try? a.resourceValues(forKeys: [.volumeIdentifierKey]))?.volumeIdentifier as? NSObject,
+ let vb = (try? b.resourceValues(forKeys: [.volumeIdentifierKey]))?.volumeIdentifier as? NSObject else { return false }
+ return va.isEqual(vb)
+ }
+
+ /// Clones the game's folder into `common/<installdir>` under `destSteamapps` and copies its appmanifest beside
+ /// it, the record last, so a Steam that looks never finds a record before its files. Nothing stays behind when
+ /// anything is in the way: a source not fully installed, files or record missing, the game already in the new
+ /// environment, or a clone the file system refuses (another volume, not APFS). A source folder that is a link to
+ /// another environment's copy is resolved first: the new environment gets files of its own, never a second
+ /// 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 let root = game.libraryRoot, let folder = game.installFolder?.resolvingSymlinksInPath() else {
+ return .skipped("its install folder is unknown")
+ }
+ let record = root.appending(path: "steamapps/appmanifest_\(game.appid).acf")
+ let fm = FileManager.default
+ guard fm.fileExists(atPath: folder.path), fm.fileExists(atPath: record.path) else {
+ return .skipped("its files or its Steam record are missing")
+ }
+ let destFolder = destSteamapps.appending(path: "common/\(game.installdir)", directoryHint: .isDirectory)
+ let destRecord = destSteamapps.appending(path: "appmanifest_\(game.appid).acf")
+ guard !fm.fileExists(atPath: destFolder.path), !fm.fileExists(atPath: destRecord.path) else {
+ return .skipped("the new environment has it already")
+ }
+ do {
+ try fm.createDirectory(at: destFolder.deletingLastPathComponent(), withIntermediateDirectories: true)
+ try clone(folder, destFolder)
+ } catch {
+ try? fm.removeItem(at: destFolder)
+ return .skipped("its folder could not be cloned (\(error.localizedDescription))")
+ }
+ do {
+ try fm.copyItem(at: record, to: destRecord)
+ } catch {
+ try? fm.removeItem(at: destFolder)
+ return .skipped("its Steam record could not be copied (\(error.localizedDescription))")
+ }
+ return .carried
+ }
+
+ /// clonefile(2): the whole tree in one call, every block shared with the source until either side writes. It
+ /// refuses across volumes (EXDEV) and off APFS, which is what keeps a carry-over from ever being a full copy.
+ public static func cloneTree(_ source: URL, _ destination: URL) throws {
+ guard clonefile(source.path, destination.path, UInt32(CLONE_NOOWNERCOPY)) == 0 else {
+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+ }
+ }
+}
diff --git a/Tests/HighballKitTests/EngineChannelsTests.swift b/Tests/HighballKitTests/EngineChannelsTests.swift
index 1dc1cf4..dc31625 100644
--- a/Tests/HighballKitTests/EngineChannelsTests.swift
+++ b/Tests/HighballKitTests/EngineChannelsTests.swift
@@ -44,6 +44,33 @@ final class EngineChannelsTests: XCTestCase {
XCTAssertFalse(EngineChannels.hidesPin("x64-line-r10", bundled: bundled, beta: false, preview: false))
}
+ func testAPreviewEngineTakenForAGameIsSeenAndNoOtherIs() throws {
+ let line = try manifest(id: "arm64-line-r1", channel: "preview")
+ let other = try manifest(id: "arm64-line-r2", channel: "preview")
+ let betaLine = try manifest(id: "x64-beta-r1", channel: "beta")
+ XCTAssertTrue(EngineChannels.visible(line, beta: false, preview: false, optedIn: ["arm64-line-r1"]))
+ XCTAssertFalse(EngineChannels.visible(other, beta: false, preview: false, optedIn: ["arm64-line-r1"]))
+ // An opt-in reaches preview engines only: a beta line stays with beta builds.
+ XCTAssertFalse(EngineChannels.visible(betaLine, beta: false, preview: false, optedIn: ["x64-beta-r1"]))
+ XCTAssertFalse(EngineChannels.hidesPin("arm64-line-r1", bundled: [line], beta: false, preview: false, optedIn: ["arm64-line-r1"]))
+ XCTAssertTrue(EngineChannels.hidesPin("arm64-line-r1", bundled: [line], beta: false, preview: false, optedIn: []))
+ }
+
+ func testPlayOffersAHiddenPreviewPinAndNothingElse() throws {
+ let bundled = [try manifest(id: "arm64-line-r1", channel: "preview"), try manifest(id: "x64-line-r9", channel: nil),
+ try manifest(id: "x64-beta-r1", channel: "beta")]
+ XCTAssertEqual(EngineChannels.previewToOffer(pin: "arm64-line-r1", bundled: bundled, beta: false, preview: false, optedIn: [])?.id,
+ "arm64-line-r1")
+ // Seen already (the key, or taken once for a game): the usual engine ask takes over.
+ XCTAssertNil(EngineChannels.previewToOffer(pin: "arm64-line-r1", bundled: bundled, beta: false, preview: true, optedIn: []))
+ XCTAssertNil(EngineChannels.previewToOffer(pin: "arm64-line-r1", bundled: bundled, beta: false, preview: false,
+ optedIn: ["arm64-line-r1"]))
+ XCTAssertNil(EngineChannels.previewToOffer(pin: "x64-line-r9", bundled: bundled, beta: false, preview: false, optedIn: []))
+ XCTAssertNil(EngineChannels.previewToOffer(pin: "x64-beta-r1", bundled: bundled, beta: false, preview: false, optedIn: []))
+ XCTAssertNil(EngineChannels.previewToOffer(pin: "x64-line-r10", bundled: bundled, beta: false, preview: false, optedIn: []))
+ XCTAssertNil(EngineChannels.previewToOffer(pin: nil, bundled: bundled, beta: false, preview: false, optedIn: []))
+ }
+
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/RecipeMemoryFloorTests.swift b/Tests/HighballKitTests/RecipeMemoryFloorTests.swift
new file mode 100644
index 0000000..ef3c139
--- /dev/null
+++ b/Tests/HighballKitTests/RecipeMemoryFloorTests.swift
@@ -0,0 +1,26 @@
+import XCTest
+@testable import HighballKit
+
+/// A recipe's memory floor: data the asks read, absent from every recipe written before it.
+final class RecipeMemoryFloorTests: XCTestCase {
+ private func recipe(_ json: String) throws -> Recipe {
+ try JSONDecoder().decode(Recipe.self, from: Data(json.utf8))
+ }
+
+ func testAFloorIsReadAndARecipeWithoutOneHasNone() throws {
+ let with = try recipe(#"{"id":"g","kind":"game","title":"G","engine":"arm64-wine11.18-r3","minMemoryGB":32,"steps":[]}"#)
+ XCTAssertEqual(with.minMemoryGB, 32)
+ let without = try recipe(#"{"id":"g","kind":"game","title":"G","steps":[]}"#)
+ XCTAssertNil(without.minMemoryGB)
+ }
+
+ func testOnlyAMacUnderTheFloorIsTold() throws {
+ let r = try recipe(#"{"id":"g","kind":"game","title":"G","minMemoryGB":32,"steps":[]}"#)
+ XCTAssertNil(r.memoryShortfall(memoryMB: 32_768))
+ XCTAssertNil(r.memoryShortfall(memoryMB: 65_536))
+ let short = try XCTUnwrap(r.memoryShortfall(memoryMB: 16_384))
+ XCTAssertEqual(short.needGB, 32)
+ XCTAssertEqual(short.haveGB, 16)
+ XCTAssertNil(try recipe(#"{"id":"g","kind":"game","title":"G","steps":[]}"#).memoryShortfall(memoryMB: 8_192))
+ }
+}
diff --git a/Tests/HighballKitTests/SteamGameCarryOverTests.swift b/Tests/HighballKitTests/SteamGameCarryOverTests.swift
new file mode 100644
index 0000000..14167e6
--- /dev/null
+++ b/Tests/HighballKitTests/SteamGameCarryOverTests.swift
@@ -0,0 +1,99 @@
+import XCTest
+@testable import HighballKit
+
+/// A game handed to a new environment as a clone. A wrong answer here either downloads 50 GB again for nothing or,
+/// worse, gives a second Steam a folder another environment uses.
+final class SteamGameCarryOverTests: XCTestCase {
+ private var tmp: URL!
+
+ override func setUpWithError() throws {
+ tmp = FileManager.default.temporaryDirectory.appending(path: "carryover-\(UUID().uuidString)", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
+ }
+
+ override func tearDownWithError() throws {
+ try? FileManager.default.removeItem(at: tmp)
+ }
+
+ /// A library folder holding one installed game, as Steam lays it out.
+ private func library(_ name: String, appid: Int = 2537590, installdir: String = "MSFS2024", state: Int = 4) throws -> SteamGame {
+ let root = tmp.appending(path: name, directoryHint: .isDirectory)
+ let game = root.appending(path: "steamapps/common/\(installdir)", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: game.appending(path: "Packages"), withIntermediateDirectories: true)
+ try Data("exe".utf8).write(to: game.appending(path: "FlightSimulator2024.exe"))
+ try Data("package".utf8).write(to: game.appending(path: "Packages/one.fsarchive"))
+ try Data("\"AppState\" { \"appid\" \"\(appid)\" \"StateFlags\" \"\(state)\" }".utf8)
+ .write(to: root.appending(path: "steamapps/appmanifest_\(appid).acf"))
+ return SteamGame(appid: appid, name: "Game", installdir: installdir, sizeOnDisk: 1, stateFlags: state, lastPlayed: nil,
+ libraryRoot: root)
+ }
+
+ private func steamapps(_ name: String) throws -> URL {
+ let dir = tmp.appending(path: "\(name)/steamapps", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ return dir
+ }
+
+ func testTheGameAndItsRecordArriveAndTheOriginalStaysAsItWas() throws {
+ let game = try library("old")
+ let dest = try steamapps("new")
+ XCTAssertEqual(SteamGameCarryOver.carry(game, into: dest), .carried)
+ let copied = dest.appending(path: "common/MSFS2024")
+ XCTAssertEqual(try String(contentsOf: copied.appending(path: "Packages/one.fsarchive"), encoding: .utf8), "package")
+ XCTAssertEqual(try String(contentsOf: copied.appending(path: "FlightSimulator2024.exe"), encoding: .utf8), "exe")
+ XCTAssertTrue(FileManager.default.fileExists(atPath: dest.appending(path: "appmanifest_2537590.acf").path))
+ // The clone is a copy of its own: writing to it leaves the original alone.
+ try Data("changed".utf8).write(to: copied.appending(path: "FlightSimulator2024.exe"))
+ XCTAssertEqual(try String(contentsOf: game.installFolder!.appending(path: "FlightSimulator2024.exe"), encoding: .utf8), "exe")
+ }
+
+ func testAGameStillDownloadingOrUpdatingStaysWhereItIs() throws {
+ let game = try library("old", state: 1026)
+ let dest = try steamapps("new")
+ 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))
+ }
+
+ func testANewEnvironmentThatHasTheGameAlreadyIsLeftAlone() throws {
+ let game = try library("old")
+ let dest = try steamapps("new")
+ try FileManager.default.createDirectory(at: dest.appending(path: "common/MSFS2024"), withIntermediateDirectories: true)
+ guard case .skipped = SteamGameCarryOver.carry(game, into: dest) else { return XCTFail("an existing install must not be overwritten") }
+ XCTAssertFalse(FileManager.default.fileExists(atPath: dest.appending(path: "appmanifest_2537590.acf").path))
+ }
+
+ func testARefusedCloneLeavesNothingBehind() throws {
+ let game = try library("old")
+ let dest = try steamapps("new")
+ let outcome = SteamGameCarryOver.carry(game, into: dest) { _, to in
+ try FileManager.default.createDirectory(at: to, withIntermediateDirectories: true) // a partial tree
+ throw POSIXError(.EXDEV) // another volume: clonefile refuses
+ }
+ guard case .skipped = outcome else { return XCTFail("a refused clone must not count as carried") }
+ XCTAssertFalse(FileManager.default.fileExists(atPath: dest.appending(path: "common/MSFS2024").path))
+ XCTAssertFalse(FileManager.default.fileExists(atPath: dest.appending(path: "appmanifest_2537590.acf").path))
+ }
+
+ func testAFolderLinkedToAnotherEnvironmentBecomesFilesOfItsOwn() throws {
+ // The M4's FH6 environment kept its game as a link to another environment's copy.
+ let real = try library("shared")
+ let linked = tmp.appending(path: "linked/steamapps/common", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: linked, withIntermediateDirectories: true)
+ try FileManager.default.createSymbolicLink(at: linked.appending(path: "MSFS2024"), withDestinationURL: real.installFolder!)
+ try FileManager.default.copyItem(at: real.libraryRoot!.appending(path: "steamapps/appmanifest_2537590.acf"),
+ to: tmp.appending(path: "linked/steamapps/appmanifest_2537590.acf"))
+ let game = SteamGame(appid: 2537590, name: "Game", installdir: "MSFS2024", sizeOnDisk: 1, stateFlags: 4, lastPlayed: nil,
+ libraryRoot: tmp.appending(path: "linked", directoryHint: .isDirectory))
+ let dest = try steamapps("new")
+ XCTAssertEqual(SteamGameCarryOver.carry(game, into: dest), .carried)
+ let copied = dest.appending(path: "common/MSFS2024")
+ let kind = try FileManager.default.attributesOfItem(atPath: copied.path)[.type] as? FileAttributeType
+ XCTAssertEqual(kind, .typeDirectory, "the new environment must get a folder, not a link to a shared one")
+ }
+
+ func testAGameOnThisVolumeCanComeAlong() throws {
+ let game = try library("old")
+ XCTAssertTrue(SteamGameCarryOver.canCarry(game, toBottlesRoot: tmp))
+ }
+}