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
home location: probe the volume instead of trusting a format name
Gauthier Piarrette6a11c716c17c
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swiftindex 62c1706..6bb694b 100644--- a/Sources/HighballApp/AppState.swift+++ b/Sources/HighballApp/AppState.swift@@ -372,7 +372,7 @@ final class AppState {let panel = NSOpenPanel()panel.canChooseDirectories = true; panel.canChooseFiles = false; panel.canCreateDirectories = truepanel.prompt = L("Use this folder")- panel.message = L("Highball will keep its engines and environments in this folder. It must be on an APFS volume (external drives formatted as exFAT cannot hold a Windows environment).")+ panel.message = L("Highball will keep its engines and environments in this folder. Pick a drive with room to spare: Highball checks the folder before moving anything, and says so if the drive cannot hold an environment.")guard panel.runModal() == .OK, let url = panel.url else { return }if let why = HighballPaths.locationProblem(url) { errorMessage = why; return }if url.standardizedFileURL == paths.home.standardizedFileURL { return }diff --git a/Sources/HighballApp/L10n.swift b/Sources/HighballApp/L10n.swiftindex aca4a66..357bd77 100644--- a/Sources/HighballApp/L10n.swift+++ b/Sources/HighballApp/L10n.swift@@ -132,7 +132,7 @@ enum L10n {"Moving Highball's data back to the default location": "Retour des données de Highball à l'emplacement par défaut","Back to ~/Library/Application Support/Highball, with the data": "Retour dans ~/Library/Application Support/Highball, avec les données","as long as copying your games takes; nothing is removed until the copy checks out": "le temps de copier vos jeux, rien n'est supprimé avant vérification de la copie",- "Highball will keep its engines and environments in this folder. It must be on an APFS volume (external drives formatted as exFAT cannot hold a Windows environment).": "Highball gardera ses moteurs et environnements dans ce dossier. Il doit être sur un volume APFS (un disque externe en exFAT ne peut pas contenir un environnement Windows).",+ "Highball will keep its engines and environments in this folder. Pick a drive with room to spare: Highball checks the folder before moving anything, and says so if the drive cannot hold an environment.": "Highball gardera ses moteurs et environnements dans ce dossier. Choisissez un disque avec de la place : Highball vérifie le dossier avant de rien déplacer, et vous le dit si le disque ne peut pas contenir un environnement.","Highball keeps its engines and environments in %@, and that location is not available right now. Connect the drive and relaunch, or go back to the default location on this Mac.": "Highball garde ses moteurs et environnements dans %@, et cet emplacement n'est pas disponible pour le moment. Branchez le disque et relancez, ou revenez à l'emplacement par défaut sur ce Mac.","Engines, environments and downloads copy to %@, get checked, and are then removed from %@. Highball relaunches when it is done. Nothing is removed until the copy checks out.": "Les moteurs, environnements et téléchargements sont copiés vers %@, vérifiés, puis supprimés de %@. Highball se relance ensuite. Rien n'est supprimé avant vérification de la copie.","Mode for this game": "Mode pour ce jeu",diff --git a/Sources/HighballKit/GamePageCopy.swift b/Sources/HighballKit/GamePageCopy.swiftindex e609676..ee78a3b 100644--- a/Sources/HighballKit/GamePageCopy.swift+++ b/Sources/HighballKit/GamePageCopy.swift@@ -133,6 +133,7 @@ public enum GamePageCopy {case let .file(path, _): return "Write \(URL(fileURLWithPath: path).lastPathComponent)"case .pin: return nilcase let .note(text): return text+ case let .dllOverride(v): return "Set the Windows library override \(v)"case let .dxvkConfig(exe, _): return "Configure DXVK for \(exe)"}}diff --git a/Sources/HighballKit/Paths.swift b/Sources/HighballKit/Paths.swiftindex de9fc19..c64311e 100644--- a/Sources/HighballKit/Paths.swift+++ b/Sources/HighballKit/Paths.swift@@ -56,10 +56,17 @@ public struct HighballPaths: Sendable {}}- /// Why a folder cannot hold Highball's data, or nil when it can. Wine builds an environment's- /// drive letters out of symbolic links, so a volume without them (exFAT, FAT) cannot hold one;- /// the folder must exist and be writable; and it must not sit inside the default home, which- /// would move the data into itself.+ /// Why a folder cannot hold Highball's data, or nil when it can. The folder must exist and be+ /// writable, must not sit inside the default home (which would move the data into itself), and+ /// the volume must do the two things Wine needs: symbolic links, for an environment's drive+ /// letters, and an execute bit that survives, because the engine's own binaries run from here.+ ///+ /// Those last two are probed rather than inferred. The previous check read+ /// `volumeSupportsSymbolicLinks` and refused exFAT by name, but macOS reports exFAT as+ /// supporting symbolic links and does in fact create them, so the check never fired and the+ /// refusal the release notes promised never happened. Measured 2026-09-09 on an exFAT volume:+ /// the flag reads true, links are created, and a bottle moved there launches and runs. Asking+ /// the volume directly also catches what a format name never could.public static func locationProblem(_ url: URL, defaultHome: URL = defaultHome) -> String? {let fm = FileManager.defaultvar isDir: ObjCBool = false@@ -67,11 +74,39 @@ public struct HighballPaths: Sendable {guard fm.isWritableFile(atPath: url.path) else { return "Highball cannot write in that folder." }let target = url.standardizedFileURL.path + "/", base = defaultHome.standardizedFileURL.path + "/"if target.hasPrefix(base) || base.hasPrefix(target) { return "Pick a folder outside Highball's own data folder." }- if let values = try? url.resourceValues(forKeys: [.volumeSupportsSymbolicLinksKey, .volumeIsReadOnlyKey]) {- if values.volumeIsReadOnly == true { return "That volume is read only." }- if values.volumeSupportsSymbolicLinks == false {- return "That drive's format (exFAT or FAT) cannot hold a Windows environment: Wine needs symbolic links. Format it as APFS, or pick another drive."- }+ if (try? url.resourceValues(forKeys: [.volumeIsReadOnlyKey]))?.volumeIsReadOnly == true {+ return "That volume is read only."+ }+ // FAT32 stops at one byte under 4 GiB per file, and game files pass that routinely. macOS+ // reports the real limit, so this asks rather than matching on a format name (measured+ // 2026-09-09: FAT32 4294967295, exFAT and APFS effectively unlimited).+ if let max = (try? url.resourceValues(forKeys: [.volumeMaximumFileSizeKey]))?.volumeMaximumFileSize,+ max < 4 << 30 {+ return "That drive cannot store a file larger than \(max >> 30) GB, and game files are often bigger. Format it as APFS, or pick another drive."+ }+ return volumeProblem(url)+ }++ /// Makes and removes a scratch folder inside `url` to check what Wine actually needs from the+ /// volume. Leaves nothing behind, including when a check fails.+ static func volumeProblem(_ url: URL, uuid: String = UUID().uuidString) -> String? {+ let fm = FileManager.default+ let probe = url.appending(path: ".highball-probe-" + uuid.prefix(8))+ defer { try? fm.removeItem(at: probe) }+ do { try fm.createDirectory(at: probe, withIntermediateDirectories: true) }+ catch { return "Highball cannot write in that folder." }+ do { try fm.createSymbolicLink(atPath: probe.appending(path: "link").path, withDestinationPath: "target") }+ catch {+ return "That drive cannot hold a Windows environment: an environment's drive letters are symbolic links, and this volume does not support them. Format it as APFS, or pick another drive."+ }+ let bin = probe.appending(path: "bin")+ guard fm.createFile(atPath: bin.path, contents: Data("#!/bin/sh\nexit 0\n".utf8),+ attributes: [.posixPermissions: 0o755]) else {+ return "Highball cannot write in that folder."+ }+ let mode = ((try? fm.attributesOfItem(atPath: bin.path))?[.posixPermissions] as? NSNumber)?.uint16Value ?? 0+ guard mode & 0o100 != 0 else {+ return "That drive cannot hold a Windows environment: Highball runs its engine from here, and this volume does not keep the execute permission. Format it as APFS, or pick another drive."}return nil}diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swiftindex 46aac6f..0619023 100644--- a/Sources/HighballKit/Recipe.swift+++ b/Sources/HighballKit/Recipe.swift@@ -30,6 +30,11 @@ public struct Recipe: Codable, Sendable, Identifiable {case pin(Pin)/// Free-text instruction the UI surfaces to the user after install.case note(String)+ /// A WINEDLLOVERRIDES entry the bottle keeps, e.g. "amd_ags_x64=" to disable AMD's AGS+ /// library. Appended to whatever the renderer sets, and mirrored into the prefix registry+ /// so it also reaches a game launched by an already-running Steam. This is how a game's+ /// need to avoid a vendor library ships as data instead of app code.+ case dllOverride(String)/// Per-app DXVK options ("csgo.exe" → dxvk.enableAsync=False…), stored on the bottle/// and rendered into its dxvk.conf at every DXVK launch. This is how game-specific/// DXVK knowledge ships as data instead of app code.@@ -59,6 +64,7 @@ public struct Recipe: Codable, Sendable, Identifiable {case "file": self = .file(path: try c.decode(String.self, forKey: .path), contents: try c.decode(String.self, forKey: .contents))case "pin": self = .pin(try c.decode(Pin.self, forKey: .pin))case "note": self = .note(try c.decode(String.self, forKey: .text))+ case "dlloverride": self = .dllOverride(try c.decode(String.self, forKey: .value))case "dxvkconfig": self = .dxvkConfig(exe: try c.decode(String.self, forKey: .exe),options: try c.decode([String: String].self, forKey: .options))case let other: throw HighballError.invalid("unknown recipe step type '\(other)'")@@ -86,6 +92,7 @@ public struct Recipe: Codable, Sendable, Identifiable {case let .file(path, contents): try c.encode("file", forKey: .type); try c.encode(path, forKey: .path); try c.encode(contents, forKey: .contents)case let .pin(p): try c.encode("pin", forKey: .type); try c.encode(p, forKey: .pin)case let .note(t): try c.encode("note", forKey: .type); try c.encode(t, forKey: .text)+ case let .dllOverride(v): try c.encode("dlloverride", forKey: .type); try c.encode(v, forKey: .value)case let .dxvkConfig(exe, options):try c.encode("dxvkconfig", forKey: .type); try c.encode(exe, forKey: .exe)try c.encode(options, forKey: .options)@@ -98,7 +105,7 @@ public struct Recipe: Codable, Sendable, Identifiable {case let .installer(_, _, _, label, _, _): return labelcase let .winetricks(verbs, _): return verbs.joined(separator: " ")case .registry: return nil- case .environment, .renderer, .sync, .winver, .file, .pin, .note, .dxvkConfig: return nil+ case .environment, .renderer, .sync, .winver, .file, .pin, .note, .dxvkConfig, .dllOverride: return nil}}@@ -134,7 +141,7 @@ public struct Recipe: Codable, Sendable, Identifiable {/// takes no meaningful time (installer/winetricks can take 20-40 minutes).public var isAutoApplicable: Bool {switch self {- case .file, .renderer, .sync, .environment, .pin, .note, .dxvkConfig: return true+ case .file, .renderer, .sync, .environment, .pin, .note, .dxvkConfig, .dllOverride: return truecase .installer, .winetricks, .registry, .winver: return false}}@@ -349,6 +356,11 @@ public struct RecipeRunner: Sendable {if !bottle.settings.pins.contains(where: { $0.path == p.path }) { bottle.settings.pins.append(p) }case let .note(t):notes.append(t)+ case let .dllOverride(v):+ // Semicolon separated, and idempotent: a recipe re-run must not stack duplicates.+ var parts = bottle.settings.dllOverrides.split(separator: ";").map(String.init)+ if !parts.contains(v) { parts.append(v) }+ bottle.settings.dllOverrides = parts.joined(separator: ";")case let .dxvkConfig(exe, options):bottle.settings.dxvkAppConfig[exe] = options}diff --git a/Tests/HighballKitTests/HomeLocationTests.swift b/Tests/HighballKitTests/HomeLocationTests.swiftindex 56fda78..c050a70 100644--- a/Tests/HighballKitTests/HomeLocationTests.swift+++ b/Tests/HighballKitTests/HomeLocationTests.swift@@ -41,6 +41,36 @@ final class HomeLocationTests: XCTestCase {XCTAssertNotNil(HighballPaths.locationProblem(tmp, defaultHome: tmp.appending(path: "default")), "the default's own parent is refused too")}+ // The volume check asks the volume instead of trusting a name. The old check read+ // volumeSupportsSymbolicLinks and refused exFAT by name, but macOS reports exFAT as supporting+ // symbolic links and creates them, so it never fired and the promised refusal never happened+ // (measured 2026-09-09: a home moved to exFAT was accepted and the bottle ran).+ // FAT32 caps a file at one byte under 4 GiB and game files pass that routinely, so a drive+ // that reports a small maximum is refused. Runs only where such a volume is mounted.+ func testSmallMaximumFileSizeIsRefused() throws {+ let fat = URL(fileURLWithPath: "/Volumes/FAT32TEST")+ try XCTSkipUnless(FileManager.default.fileExists(atPath: fat.path), "no FAT32 volume mounted")+ let problem = HighballPaths.locationProblem(fat, defaultHome: tmp)+ XCTAssertNotNil(problem)+ XCTAssertTrue(problem?.contains("larger than") == true, "says why, not just no: \(problem ?? "nil")")+ }++ func testVolumeProbePassesOnAWritableFolderAndLeavesNothing() throws {+ let dir = tmp.appending(path: "vol")+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ XCTAssertNil(HighballPaths.volumeProblem(dir, uuid: "fixed-uuid"))+ XCTAssertEqual(try FileManager.default.contentsOfDirectory(atPath: dir.path), [],+ "the probe cleans up after itself, including the symlink and the executable")+ }++ func testVolumeProbeReportsAnUnwritableFolder() throws {+ let dir = tmp.appending(path: "ro")+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ try FileManager.default.setAttributes([.posixPermissions: 0o500], ofItemAtPath: dir.path)+ defer { try? FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: dir.path) }+ XCTAssertNotNil(HighballPaths.volumeProblem(dir), "a folder it cannot write in is refused")+ }+func testMoveCopiesChecksThenRemovesAndKeepsLinks() throws {let src = tmp.appending(path: "src"), dst = tmp.appending(path: "dst")let fm = FileManager.defaultdiff --git a/Tests/HighballKitTests/RegressionTests.swift b/Tests/HighballKitTests/RegressionTests.swiftindex afeaf4e..d46f470 100644--- a/Tests/HighballKitTests/RegressionTests.swift+++ b/Tests/HighballKitTests/RegressionTests.swift@@ -1316,6 +1316,36 @@ extension RegressionTests {}}+ // A game that must avoid a vendor library ships that as data, not app code. Guardians of the+ // Galaxy calls agsCheckDriverVersion, and D3DMetal presents the Apple GPU as an AMD card, so+ // the game takes AMD's vendor path and warns that the driver is too old (2026-09-09).+ func testDllOverrideStepIsDataDriven() throws {+ let json = """+ {"id":"g","kind":"game","title":"G","steps":[{"type":"dlloverride","value":"amd_ags_x64="}]}+ """+ let r = try JSONDecoder.highball.decode(Recipe.self, from: Data(json.utf8))+ XCTAssertTrue(r.isAutoApplicable, "setting an override touches no wine process, so Play may apply it")+ guard case let .dllOverride(v) = r.steps[0] else { return XCTFail("expected a dllOverride step") }+ XCTAssertEqual(v, "amd_ags_x64=")+ // Round trips, so a recipe read back from a bottle keeps the step.+ let back = try JSONDecoder.highball.decode(Recipe.self, from: try JSONEncoder().encode(r))+ guard case .dllOverride("amd_ags_x64=") = back.steps[0] else { return XCTFail("did not round trip") }+ }++ // Applying the same recipe twice must not stack duplicate entries: WINEDLLOVERRIDES is+ // semicolon separated and a repeated Play would otherwise grow it without bound.+ func testDllOverrideAppliesIdempotently() {+ var overrides = ""+ for _ in 0..<3 {+ for v in ["amd_ags_x64=", "version=n,b"] {+ var parts = overrides.split(separator: ";").map(String.init)+ if !parts.contains(v) { parts.append(v) }+ overrides = parts.joined(separator: ";")+ }+ }+ XCTAssertEqual(overrides, "amd_ags_x64=;version=n,b")+ }+// Tech-debt migration (#21): per-app DXVK options are data now. Recipe-set values// override the built-in csgo fallback, other exes render their own sections, and the// fallback survives untouched for bottles without the recipe.