Skip to content

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

Five fixes from the 2026-10-20 sweep.

Gauthier Piarrettef85dd6894fa4
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index b1652bf..848c5ac 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -1567,7 +1567,7 @@ final class AppState {
func createEnvironment(for recipe: HighballKit.Recipe, on manifest: EngineManifest, item: LibraryItem? = nil) {
pendingEngine = nil
guard !busy else { return }
- let name = BottleStore.freeName(recipe.title, taken: Set(bottles.map(\.name)))
+ let name = BottleStore.freeName(BottleStore.safeName(fromTitle: 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
@@ -2735,7 +2735,18 @@ final class AppState {
switch outcome {
case .failure(let error): throw error
case .success(let result):
- if result.crashedEarly, !stopRequested { crashed(result); return false }
+ if result.crashedEarly, !stopRequested {
+ // A program that hands itself to its launcher exits at once with an error code
+ // and comes back moments later, started by the launcher: Star Wars Galaxy of
+ // Heroes through the EA app read as a crash and Highball offered another mode
+ // for a game that was running fine (highball-db#566). It gets 20 s to appear.
+ for _ in 0..<10 {
+ if await started() { box.handedOff = true; return true }
+ if stopRequested { return false }
+ try await Task.sleep(for: .seconds(2))
+ }
+ crashed(result); return false
+ }
if exitEndsWait { return false }
exited = true
}
@@ -3091,6 +3102,27 @@ final class AppState {
return ids.contains(recipe.id)
}
+ /// Takes a registry-only tweak back off an environment: each value it set is deleted, so Wine
+ /// uses its own default again, and the environment stops if nothing runs in it, since drivers
+ /// such as the controller bus read their options when the environment starts. A DualSense player
+ /// with "Controllers through SDL" installed had no way back short of regedit (Discord, 2026-10-19).
+ func removeTweak(_ recipe: HighballKit.Recipe, from bottle: Bottle) {
+ guard recipe.isRemovable, let engine = engine(for: bottle) else { return }
+ runBusy(String(format: L("Removing %@"), recipe.title)) { [self] in
+ let runner = WineRunner(paths: paths, engine: engine, bottle: bottle)
+ for value in recipe.registryValues { try await runner.regDelete(key: value.key, name: value.name) }
+ let stopped = ProcessTable.liveServer(forPrefix: bottle.url) != nil && ProcessTable.isIdle(prefix: bottle.url)
+ if stopped { _ = try? runner.kill() }
+ await MainActor.run {
+ var copy = self.bottles.first { $0.name == bottle.name } ?? bottle
+ copy.settings.recipes.removeAll { $0 == recipe.id }
+ self.update(copy)
+ self.appendLog("\(recipe.title) removed from \(bottle.name): its registry values are gone, so Wine uses its defaults again"
+ + (stopped ? "; the idle environment stopped so its next start reads them." : ". Stop the environment once so programs see it."))
+ }
+ }
+ }
+
/// A runtime a game's own first-run setup installed (Steam runs the Visual C++ redist for
/// most games) registers itself like Highball's install does, but leaves Wine's built-in
/// copies of its DLLs in front of the real ones, and a launcher that checks those files
diff --git a/Sources/HighballApp/BottleView.swift b/Sources/HighballApp/BottleView.swift
index 79a35af..d681676 100644
--- a/Sources/HighballApp/BottleView.swift
+++ b/Sources/HighballApp/BottleView.swift
@@ -593,6 +593,9 @@ struct EnvironmentSettingsPage: View {
let live = state.bottles.first { $0.name == bottle.name } ?? bottle
if live.settings.recipes.contains(r.id) || state.tweakIsInstalled(r, in: live) {
Label(L("Installed"), systemImage: "checkmark.circle.fill").foregroundStyle(.green).labelStyle(.titleAndIcon)
+ if r.isRemovable {
+ Button(L("Remove")) { state.removeTweak(r, from: live) }.controlSize(.small).disabled(state.busy)
+ }
} else {
Button(L("Install")) {
state.applyRecipe(r.id, to: state.bottles.first { $0.name == bottle.name } ?? bottle)
diff --git a/Sources/HighballKit/BottleStore.swift b/Sources/HighballKit/BottleStore.swift
index 8c08a81..870765c 100644
--- a/Sources/HighballKit/BottleStore.swift
+++ b/Sources/HighballKit/BottleStore.swift
@@ -43,6 +43,33 @@ public struct BottleStore: Sendable {
return candidate
}
+ /// A name `nameProblem` accepts, made from a game's title, for an environment Highball creates
+ /// for that game. A fifth of the database's titles carry a character Windows forbids in paths,
+ /// mostly a colon, and "Onimusha: Way of the Sword Benchmark" refused to become an environment
+ /// (highball#391). A colon before a space reads as " - ", any other colon, slash or bar as "-",
+ /// the other forbidden characters and control characters go, spaces close up, leading and
+ /// trailing dots and dashes go, and the name stops at 60 characters so freeName's " 2" still fits.
+ public static func safeName(fromTitle title: String) -> String {
+ let chars = Array(title)
+ var out = ""
+ for (i, ch) in chars.enumerated() {
+ if ch.unicodeScalars.contains(where: { CharacterSet.controlCharacters.contains($0) }) { out += " "; continue }
+ switch ch {
+ case ":": out += (i + 1 < chars.count && chars[i + 1] == " ") ? " -" : "-"
+ case "/", "\\", "|": out += "-"
+ case "*", "?", "\"", "<", ">": continue
+ default: out.append(ch)
+ }
+ }
+ func tidy(_ s: String) -> String {
+ s.split(separator: " ", omittingEmptySubsequences: true).joined(separator: " ")
+ .trimmingCharacters(in: CharacterSet(charactersIn: " .-"))
+ }
+ var name = tidy(out)
+ if name.count > 60 { name = tidy(String(name.prefix(60))) }
+ return name.isEmpty ? "Game" : name
+ }
+
public static func nameProblem(_ name: String) -> String? {
let trimmed = name.trimmingCharacters(in: .whitespaces)
if trimmed.isEmpty { return "The bottle name is empty." }
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swift
index 3a5aaef..7f59844 100644
--- a/Sources/HighballKit/Recipe.swift
+++ b/Sources/HighballKit/Recipe.swift
@@ -316,6 +316,20 @@ public struct Recipe: Codable, Sendable, Identifiable {
public var min: Int?
}
+ /// A tweak made only of registry values (and notes) can be taken back off: deleting each value it
+ /// set returns Wine to its own default for it. "Controllers through SDL" asked for it, since a
+ /// DualSense gives no input in some games with it on and the app could only install it.
+ public var isRemovable: Bool {
+ kind == .tweak && !registryValues.isEmpty && steps.allSatisfy {
+ switch $0 { case .registry, .note: return true; default: return false }
+ }
+ }
+
+ /// The registry values this recipe sets, key and name.
+ public var registryValues: [(key: String, name: String)] {
+ steps.compactMap { if case let .registry(key, name, _, _) = $0 { return (key, name) } else { return nil } }
+ }
+
/// True when any marker is present in the bottle. Recipes without markers report false; the
/// caller still knows whether the recipe ran.
public func isInstalled(in bottle: Bottle) -> Bool {
diff --git a/Sources/HighballKit/WineRunner.swift b/Sources/HighballKit/WineRunner.swift
index 3ad9d43..45830f8 100644
--- a/Sources/HighballKit/WineRunner.swift
+++ b/Sources/HighballKit/WineRunner.swift
@@ -91,6 +91,15 @@ public struct WineRunner: Sendable {
/// GitHub issue, and a bottle's env can hold personal paths or tokens. Without it a report
/// cannot separate "the config was never delivered" from "the config was delivered and did
/// not help", which is exactly where issue #21 stalled for two rounds.
+ static let headerSwitchPrefixes = ["DXMT_", "D3DM_", "SDL_", "MVK_", "HB_", "WINE_NO_DELAYED_FORK"]
+
+ /// The header lines for those switches, in name order, short values only.
+ static func headerSwitchLines(_ env: [String: String]) -> String {
+ env.keys.sorted().filter { key in headerSwitchPrefixes.contains { key.hasPrefix($0) } }
+ .compactMap { key in env[key].flatMap { $0.count <= 200 ? "# \(key)=\($0)\n" : nil } }
+ .joined()
+ }
+
static func launchHeader(engine: InstalledEngine, bottle: Bottle, renderer: Renderer,
env: [String: String], args: [String]) -> String {
var out = "# gin \(engine.id) bottle=\(bottle.name) renderer=\(renderer)\n"
@@ -109,6 +118,10 @@ public struct WineRunner: Sendable {
for key in ["WINEDLLPATH_PREPEND", "WINEDLLOVERRIDES", "ROSETTA_ADVERTISE_AVX", "MTL_HUD_ENABLED", "CX_FWD_COMPAT_GL_CTX", "DXVK_CONFIG_FILE", "DXVK_LOG_PATH", "DXVK_CONFIG", "VKD3D_SHADER_MODEL", "VKD3D_FEATURE_LEVEL", "VKD3D_CONFIG", "VKD3D_SHADER_CACHE_PATH", "LSFGM_MULTIPLIER", "LSFGM_PACING_MODE", "LSFGM_FLOW_SCALE", "LSFGM_DLL_PATH"] {
if let value = env[key] { out += "# \(key)=\(value)\n" }
}
+ // Renderer and controller switches a player or a recipe sets: settings, never personal, and
+ // a report can't tell whether one was set without them (highball#371 asked whether
+ // DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN was in the environment, and the log couldn't say).
+ out += headerSwitchLines(env)
// The generated dxvk.conf decides per-game behaviour, so quote it rather than making the
// reader ask for a second file that Repair may already have rewritten.
if env["DXVK_CONFIG_FILE"] != nil,
@@ -289,6 +302,7 @@ public struct WineRunner: Sendable {
public func start(_ executable: URL, arguments: [String] = [], renderer: Renderer? = nil, extraEnvironment: [String: String] = [:], workingDirectory: URL? = nil, headerNote: String? = nil, program: String? = nil, onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult {
// First, while no server holds the hive: the syncs below start the environment's server.
let linkedSteamView = (try? SteamRegistryView.repair(prefix: bottle.url)) == true
+ let prefixVersion = Self.prefixWindowsVersion(prefix: bottle.url)
await syncMacFontSubstitutes()
await syncDllOverridesRegistry()
await syncEngineAppDefaults()
@@ -299,6 +313,15 @@ public struct WineRunner: Sendable {
onOutput?("note: \(text)")
note = [note, text].compactMap { $0 }.joined(separator: "; ")
}
+ // highball#396: winetricks verbs and some installers set the prefix to Windows 7 and leave it.
+ // Steam then warned it would stop running on Windows 7 and RDR2 refused to start, while the
+ // environment's setting, and the header below, still said Windows 11. The setting wins.
+ let wantedVersion = bottle.settings.windowsVersion.rawValue
+ if let found = prefixVersion, found != wantedVersion, (try? await setWindowsVersion(bottle.settings.windowsVersion)) != nil {
+ let text = "the prefix reported \(found), set back to \(wantedVersion) as the environment's settings say"
+ onOutput?("note: \(text)")
+ note = [note, text].compactMap { $0 }.joined(separator: "; ")
+ }
// External Mac drives get letters of their own, so Steam can offer them for a library.
// Windows lists drives through Wine's mount manager, which reads the links when the
// environment's server starts: a letter linked while the server ran stayed unlisted until
@@ -759,6 +782,34 @@ public struct WineRunner: Sendable {
public func setWindowsVersion(_ v: WindowsVersion) async throws {
_ = try await run(["winecfg", "-v", v.rawValue], renderer: .wined3d, label: "winecfg")
}
+
+ /// The Windows version a prefix reports, from its registry files, as winecfg names it, or nil
+ /// when the files can't be read or say nothing. Wine takes HKCU\Software\Wine's Version first
+ /// (winetricks and older winecfg write it) and otherwise the machine's CurrentBuild, which
+ /// `winecfg -v` writes while it removes the per-user value.
+ public static func prefixWindowsVersion(prefix: URL) -> String? {
+ let user = (try? String(contentsOf: prefix.appending(path: "user.reg"), encoding: .utf8)) ?? ""
+ let system = (try? String(contentsOf: prefix.appending(path: "system.reg"), encoding: .utf8)) ?? ""
+ return prefixWindowsVersion(userReg: user, systemReg: system)
+ }
+
+ static func prefixWindowsVersion(userReg: String, systemReg: String) -> String? {
+ func unquoted(_ raw: String) -> String { raw.trimmingCharacters(in: CharacterSet(charactersIn: "\" ")).lowercased() }
+ if let raw = RegistryText.value(in: userReg, key: #"Software\Wine"#, name: "Version"), !unquoted(raw).isEmpty {
+ return unquoted(raw)
+ }
+ guard let raw = RegistryText.value(in: systemReg, key: #"Software\Microsoft\Windows NT\CurrentVersion"#, name: "CurrentBuild"),
+ let build = Int(unquoted(raw)) else { return nil }
+ switch build {
+ case 22000...: return "win11"
+ case 10240..<22000: return "win10"
+ case 9600: return "win81"
+ case 9200: return "win8"
+ case 7600, 7601: return "win7"
+ case 6000...6002: return "vista"
+ default: return "build \(build)"
+ }
+ }
}
final class Collector: @unchecked Sendable {
diff --git a/Tests/HighballKitTests/LaunchChecksTests.swift b/Tests/HighballKitTests/LaunchChecksTests.swift
new file mode 100644
index 0000000..bc02e93
--- /dev/null
+++ b/Tests/HighballKitTests/LaunchChecksTests.swift
@@ -0,0 +1,54 @@
+import XCTest
+@testable import HighballKit
+
+/// The checks a launch makes before the program starts, and the tweak removal next to them.
+final class LaunchChecksTests: XCTestCase {
+
+ /// highball#396: Steam warned it would stop running on Windows 7 in an environment whose setting
+ /// said Windows 11. The prefix's own version is what Wine reports, read from its registry files.
+ func testPrefixWindowsVersionComesFromTheRegistryFiles() {
+ func system(_ build: String) -> String {
+ "WINE REGISTRY Version 2\n\n[Software\\\\Microsoft\\\\Windows NT\\\\CurrentVersion] 1788462370\n\"CurrentBuild\"=\"\(build)\"\n\"CurrentVersion\"=\"6.3\"\n"
+ }
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: "", systemReg: system("7601")), "win7", "what winetricks win7 leaves")
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: "", systemReg: system("19045")), "win10")
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: "", systemReg: system("22000")), "win11")
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: "", systemReg: system("9600")), "win81")
+ XCTAssertNil(WineRunner.prefixWindowsVersion(userReg: "", systemReg: ""), "nothing to read, nothing to change")
+ // The per-user value wins in Wine, so it wins here.
+ let user = "WINE REGISTRY Version 2\n\n[Software\\\\Wine] 1788462370\n\"Version\"=\"win7\"\n\n[Software\\\\Wine\\\\Direct3D] 1788462370\n\"Version\"=\"win11\"\n"
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: user, systemReg: system("22000")), "win7")
+ XCTAssertEqual(WineRunner.prefixWindowsVersion(userReg: "[Software\\\\Wine\\\\Direct3D] 1\n\"Version\"=\"win7\"\n", systemReg: system("22000")), "win11",
+ "a value of the same name under another key is not the version")
+ }
+
+ /// highball#371: the log could not show whether DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN was set.
+ func testTheHeaderShowsRendererAndControllerSwitchesOnly() {
+ let env = ["DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN": "1", "SDL_JOYSTICK_MFI": "0", "HOME": "/Users/someone",
+ "STEAM_TOKEN": "secret", "MVK_CONFIG_USE_MTLHEAP": "0", "WINE_NO_DELAYED_FORK": "1",
+ "D3DM_LONG": String(repeating: "x", count: 300)]
+ XCTAssertEqual(WineRunner.headerSwitchLines(env),
+ "# DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN=1\n# MVK_CONFIG_USE_MTLHEAP=0\n# SDL_JOYSTICK_MFI=0\n# WINE_NO_DELAYED_FORK=1\n")
+ }
+
+ /// A DualSense player had "Controllers through SDL" installed and no way back but regedit.
+ func testRegistryOnlyTweaksCanBeRemoved() throws {
+ let sdl = try JSONDecoder.highball.decode(Recipe.self, from: Data("""
+ {"id": "controller-sdl", "kind": "tweak", "title": "Controllers through SDL", "steps": [
+ {"type": "registry", "key": "HKLM\\\\System\\\\CurrentControlSet\\\\Services\\\\winebus", "name": "DisableHidraw", "valueType": "REG_DWORD", "data": "1"},
+ {"type": "registry", "key": "HKLM\\\\System\\\\CurrentControlSet\\\\Services\\\\winebus", "name": "Enable SDL", "valueType": "REG_DWORD", "data": "1"},
+ {"type": "note", "text": "Restart the environment."}]}
+ """.utf8))
+ XCTAssertTrue(sdl.isRemovable)
+ XCTAssertEqual(sdl.registryValues.map(\.name), ["DisableHidraw", "Enable SDL"])
+ let runtime = try JSONDecoder.highball.decode(Recipe.self, from: Data("""
+ {"id": "xact", "kind": "tweak", "title": "XACT", "steps": [{"type": "winetricks", "verbs": ["xact"]},
+ {"type": "registry", "key": "HKCU\\\\Software\\\\Wine\\\\DllOverrides", "name": "xaudio2_7", "valueType": "REG_SZ", "data": "native"}]}
+ """.utf8))
+ XCTAssertFalse(runtime.isRemovable, "a runtime that installed files can't be taken off by deleting values")
+ let notesOnly = try JSONDecoder.highball.decode(Recipe.self, from: Data("""
+ {"id": "n", "kind": "tweak", "title": "N", "steps": [{"type": "note", "text": "x"}]}
+ """.utf8))
+ XCTAssertFalse(notesOnly.isRemovable, "nothing to remove")
+ }
+}
diff --git a/Tests/HighballKitTests/RecipeDBTests.swift b/Tests/HighballKitTests/RecipeDBTests.swift
index c1436c9..8bb54f1 100644
--- a/Tests/HighballKitTests/RecipeDBTests.swift
+++ b/Tests/HighballKitTests/RecipeDBTests.swift
@@ -39,6 +39,28 @@ final class RecipeDBTests: XCTestCase {
XCTAssertTrue(recipe.isInstalled(in: bottle), "the real runtime counts")
}
+ /// highball#391: every title in the database and every recipe's title makes a usable
+ /// environment name, a fifth of them through BottleStore.safeName's replacements.
+ func testEveryTitleMakesAnEnvironmentName() throws {
+ guard FileManager.default.fileExists(atPath: dbRoot.appending(path: "db/games").path) else {
+ throw XCTSkip("no highball-db checkout beside the repo and no .build/highball-db clone")
+ }
+ var titles: [String] = []
+ for dir in ["db/games", "recipes/games", "recipes/launchers", "recipes/tweaks"] {
+ let files = (try? FileManager.default.contentsOfDirectory(at: dbRoot.appending(path: dir), includingPropertiesForKeys: nil)) ?? []
+ for f in files where f.pathExtension == "json" {
+ if let o = try? JSONSerialization.jsonObject(with: Data(contentsOf: f)) as? [String: Any],
+ let t = o["title"] as? String { titles.append(t) }
+ }
+ }
+ XCTAssertGreaterThan(titles.count, 400)
+ for t in titles {
+ let name = BottleStore.safeName(fromTitle: t)
+ XCTAssertNil(BottleStore.nameProblem(name), "\(t) -> \(name)")
+ XCTAssertNil(BottleStore.nameProblem(BottleStore.freeName(name, taken: [name])), "\(t) with a suffix")
+ }
+ }
+
func testAllShippedRecipesDecode() throws {
let recipes = dbRoot.appending(path: "recipes")
guard FileManager.default.fileExists(atPath: recipes.path) else {
diff --git a/Tests/HighballKitTests/RecipeEngineTests.swift b/Tests/HighballKitTests/RecipeEngineTests.swift
index 3858e0f..5755ca5 100644
--- a/Tests/HighballKitTests/RecipeEngineTests.swift
+++ b/Tests/HighballKitTests/RecipeEngineTests.swift
@@ -215,4 +215,24 @@ final class RecipeEngineTests: XCTestCase {
XCTAssertEqual(BottleStore.freeName("EA app", taken: ["EA app"]), "EA app 2")
XCTAssertEqual(BottleStore.freeName("EA app", taken: ["EA app", "EA app 2"]), "EA app 3")
}
+
+ /// highball#391: a new environment for "Onimusha: Way of the Sword Benchmark" failed, since its
+ /// name came straight from the title and a bottle name can't hold a colon.
+ func testSafeNameFromTitle() {
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "Onimusha: Way of the Sword Benchmark"), "Onimusha - Way of the Sword Benchmark")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "Seven Knights Re:BIRTH"), "Seven Knights Re-BIRTH")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "Fate/Stay Night"), "Fate-Stay Night")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "Who's Your Daddy?!"), "Who's Your Daddy!")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "\"Quoted\" <Game>"), "Quoted Game")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "PEAK"), "PEAK", "a usable title stays as it is")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "...Dots..."), "Dots")
+ XCTAssertEqual(BottleStore.safeName(fromTitle: "???"), "Game")
+ let long = BottleStore.safeName(fromTitle: "BRAZILIAN DRUG DEALER 3: I OPENED A PORTAL TO HELL IN THE FAVELA TRYING TO REVIVE MIT AIA I NEED TO CLOSE IT")
+ XCTAssertLessThanOrEqual(long.count, 60)
+ for title in ["Onimusha: Way of the Sword Benchmark", "Seven Knights Re:BIRTH", "a|b\\c*d", "x\ty", " : ", long] {
+ let name = BottleStore.safeName(fromTitle: title)
+ XCTAssertNil(BottleStore.nameProblem(name), "\(title) -> \(name)")
+ XCTAssertNil(BottleStore.nameProblem(BottleStore.freeName(name, taken: [name])), "with freeName's suffix")
+ }
+ }
}