Skip to content

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

home location: probe the volume instead of trusting a format name

Gauthier Piarrette6a11c716c17c
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 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 = true
panel.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.swift
index 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.swift
index 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 nil
case 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.swift
index 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.default
var 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.swift
index 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 label
case 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 true
case .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.swift
index 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.default
diff --git a/Tests/HighballKitTests/RegressionTests.swift b/Tests/HighballKitTests/RegressionTests.swift
index 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.