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
import Foundation
public struct LaunchResult: Sendable {
public let exitStatus: Int32
public let duration: TimeInterval
public let log: URL
/// Set when the launch ran with a different graphics mode than the bottle asked for (#61);
/// the same sentence is in the log header.
public var note: String? = nil
/// Heuristic: exited non-zero (or at all) within 10 s of launch. The app uses this to suggest another renderer.
public var crashedEarly: Bool { duration < 10 && exitStatus != 0 }
}
/// Windows face names that macOS installs under a different family name. GDI+ looks up the
/// Windows name and draws no text when the family is missing. The prefix stores the map in
/// `HKLM\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes`.
public enum MacFontSubstitutes {
public static let registryKey = #"HKLM\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes"#
/// Key text as `system.reg` writes it.
static let fileKey = #"Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes"#
/// Palatino Linotype is the Windows name. macOS ships that family as Palatino.
public static let pairs: [(windowsName: String, macName: String)] = [
("Palatino Linotype", "Palatino"),
]
/// Pairs whose Windows name has no value yet. A value already stored is left as it is,
/// including one a player or a recipe set to another face.
public static func missing(in systemReg: String) -> [(windowsName: String, macName: String)] {
pairs.filter { pair in
RegistryText.value(in: systemReg, key: fileKey, name: pair.windowsName) == nil
}
}
}
/// Launches Wine processes for a bottle and captures their output to `logs/`.
public struct WineRunner: Sendable {
public let paths: HighballPaths
public let engine: InstalledEngine
public let bottle: Bottle
public init(paths: HighballPaths = HighballPaths(), engine: InstalledEngine, bottle: Bottle) {
self.paths = paths
self.engine = engine
self.bottle = bottle
}
/// Windows installer exit codes arrive twice-truncated: WiX Burn returns HRESULT_CODE
/// (low 16 bits, so 0x80070666 → 1638) and POSIX keeps only the low 8 (1638 → 102).
/// Without this note a log reads "exit=102", which means nothing to anyone.
static func exitCodeNote(for status: Int32) -> String {
switch status {
case 102: return " (Windows 1638: a newer version is already installed)"
case 194: return " (Windows 3010: success, restart required)"
case 105: return " (Windows 1641: success, restart initiated)"
default: return ""
}
}
/// A log URL that cannot overwrite an existing one. The ISO 8601 stamp is second-resolution
/// and `createFile` truncates, so two launches inside the same second used to destroy one
/// another's log — routine during Repair, which fires reg, reg and wineboot back to back.
/// The name is also flattened: `label` falls back to `args.first`, which can be a full path.
static func uniqueLogURL(in directory: URL, named name: String) -> URL {
let flat = name.replacingOccurrences(of: "/", with: "_")
let base = directory.appending(path: "\(flat).log")
guard FileManager.default.fileExists(atPath: base.path) else { return base }
for n in 2...99 {
let candidate = directory.appending(path: "\(flat)-\(n).log")
if !FileManager.default.fileExists(atPath: candidate.path) { return candidate }
}
return base
}
/// What the process will really synchronize with, which is not always the bottle's setting:
/// a pin's own environment is merged LAST and wins, and Steam's pin persists
/// WINEMSYNC=0/WINEESYNC=0 so its interface stays responsive. Every game launched from that
/// Steam window therefore inherits sync-off whatever the bottle says — the reason "try
/// sync=none" was a no-op in issue #21 and the reporter's negative result meant nothing.
static func effectiveSync(env: [String: String], settings: BottleSettings) -> String {
let actual: SyncMode
if env["WINEMSYNC"] == "1" { actual = .msync }
else if env["WINEESYNC"] == "1" { actual = .esync }
else { actual = SyncMode.none }
return actual == settings.sync ? actual.rawValue : "\(actual.rawValue) (bottle asks \(settings.sync.rawValue))"
}
/// `env` with the sync mode of the prefix's running wineserver, when one runs with another.
/// Wine fixes the mode when the server starts, and a process started with a different one
/// dies before doing anything (issue #32). Every way into a prefix goes through this, the
/// winetricks step included: it skipped it, so winetricks' first `wine cmd /c echo %AppData%`
/// printed nothing and .NET 4.8 failed in 0 s whenever a Steam window, started with sync
/// off, was open (highball#241, #336, reproduced on an M4 2026-10-22).
public static func joiningLiveServer(_ env: [String: String], prefix: URL) -> [String: String] {
joining(env, liveSync: ProcessTable.liveServerSync(forPrefix: prefix))
}
/// Pure core of `joiningLiveServer`, for tests.
static func joining(_ env: [String: String], liveSync: SyncMode?) -> [String: String] {
guard let live = liveSync, live != SyncMode(environment: env) else { return env }
return env.merging(live.environment) { $1 }
}
/// The log's opening block. Beyond the command line it records the few settings that decide
/// which graphics and synchronization stack the process actually got.
///
/// Allowlisted on purpose, never the whole environment: this text is pre-filled into a public
/// 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"]
static let headerSwitchNames: Set<String> = ["GALLIUM_DRIVER", "LIBGL_ALWAYS_SOFTWARE", "MESA_LOADER_DRIVER_OVERRIDE"]
/// 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 headerSwitchNames.contains(key) || headerSwitchPrefixes.contains { key.hasPrefix($0) } }
.compactMap { key in env[key].flatMap { $0.count <= 200 ? "# \(key)=\($0)\n" : nil } }
.joined()
}
/// Launch arguments whose values are secrets or identify the player. Launchers pass them on the
/// command line: an Epic game started through legendary gets its one-time exchange code as
/// -AUTH_PASSWORD, its account name and its account id, and the header printed them into a
/// public issue (highball#420, 2026-10-21).
static let secretArgumentPrefixes = ["-auth_password=", "-epicusername=", "-epicuserid=", "-epicovt=", "-ticket=", "-token=", "-password="]
/// The arguments as the header prints them, secret values replaced.
static func redactedForReport(_ args: [String]) -> [String] {
args.map { arg in
guard let prefix = secretArgumentPrefixes.first(where: { arg.lowercased().hasPrefix($0) }) else { return arg }
return String(arg.prefix(prefix.count)) + "[redacted]"
}
}
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"
out += "# wine \(redactedForReport(args).joined(separator: " "))\n"
out += "# sync=\(Self.effectiveSync(env: env, settings: bottle.settings))"
out += " winver=\(bottle.settings.windowsVersion.rawValue) dpi=\(bottle.settings.dpiScale)"
if bottle.settings.retinaAt100 && bottle.settings.dpiScale <= 96 { out += " retina" }
out += " dxvkAsync=\(bottle.settings.dxvkAsync)"
switch bottle.frameGenStatus(engine: engine, environment: env) {
case .off: out += " frameGen=off\n"
case .active(let m): out += " frameGen=\(m)x(requested\(env["LSFGM_PACING_MODE"] == "adaptive" ? ", adaptive" : "")\(env["LSFGM_FLOW_SCALE"].map { ", flow \($0)" } ?? "")\(env["LSFGM_PERFORMANCE_MODE"] == "1" ? ", performance" : ""))\n"
case .unavailable: out += " frameGen=off(unavailable)\n"
}
// The Mac's output rate: a sound report is unanswerable without it (highball#127).
if let audio = AudioOutput.headerLine(sampleRate: AudioOutput.defaultOutputSampleRate()) { out += audio }
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,
let conf = try? String(contentsOf: bottle.dxvkConfigURL, encoding: .utf8) {
out += Bottle.dxvkConfigHeaderLines(conf).map { "# \($0)\n" }.joined()
}
return out
}
/// Runs `wine <args>` and waits. `onOutput` receives each line of combined stdout/stderr.
@discardableResult
public func run(
_ args: [String],
renderer: Renderer? = nil,
extraEnvironment: [String: String] = [:],
label: String? = nil,
workingDirectory: URL? = nil,
restoreMscoreeFirst: Bool = true,
headerNote: String? = nil,
onOutput: (@Sendable (String) -> Void)? = nil
) async throws -> LaunchResult {
try paths.ensure()
// A boot that died halfway would leave the bottle's real .NET shim set aside (see
// setAsideForeignMscoree); put it back before anything runs in this prefix. The boot
// itself is the one launch that must not, since it just set the file aside on purpose.
if restoreMscoreeFirst { Self.restoreMscoree(bottle: bottle) }
// DXVK reads its options from the generated conf (async toggle + per-game profiles like
// [csgo.exe], issue #21) — refresh it before the spawn. Every renderer but wined3d gets
// DXVK's d3d9 attached, so every one of them needs the conf, not just .dxvk.
// A bottle set to a renderer its engine cannot run degrades to one it can (#61); the
// note goes in the header and to the caller so the substitution is never silent.
let resolved = try bottle.effectiveRenderer(requested: renderer, engine: engine)
try bottle.prepareDLSSBridge(engine: engine, renderer: resolved.renderer)
if resolved.renderer != .wined3d { try? bottle.writeDxvkConfig() }
var env = try bottle.environment(engine: engine, renderer: renderer, extra: extraEnvironment)
bottle.prepareVkd3dCache(environment: env)
// Wine fixes the sync mode when the prefix's wineserver starts; a process started with a
// different one dies at msync_init before doing anything (issue #32: a registry write
// "succeeding" in 0 s while a Steam window, cold-started with sync off, was open). So a
// launch that joins a running server takes that server's mode, whatever the bottle or
// the caller asked for; the bottle's setting applies to the next cold start. The header
// below records the adoption ("bottle asks ...").
env = Self.joiningLiveServer(env, prefix: bottle.url)
let stamp = ISO8601DateFormatter().string(from: Date()).replacingOccurrences(of: ":", with: "")
let logURL = Self.uniqueLogURL(in: paths.logs, named: "\(stamp)-\(bottle.name)-\(label ?? args.first ?? "wine")")
FileManager.default.createFile(atPath: logURL.path, contents: nil)
let logHandle = try FileHandle(forWritingTo: logURL)
var header = Self.launchHeader(engine: engine, bottle: bottle,
renderer: resolved.renderer, env: env, args: args)
if let note = resolved.note {
header += "# note: \(note)\n"
onOutput?("note: \(note)")
}
// The caller's own caveat, e.g. a Steam client kept with another renderer: the header is
// what a report quotes, so the truth about the stack the game got must be in it.
if let headerNote { header += "# note: \(headerNote)\n" }
// report why frame generation is unavailable
if case .unavailable(let why) = bottle.frameGenStatus(engine: engine, environment: env) {
header += "# note: frame generation is off: \(why)\n"
onOutput?("note: frame generation is off: \(why)")
}
logHandle.write(Data(header.utf8))
let process = Process()
process.executableURL = engine.wineBinary
process.arguments = args
let inherited = ProcessInfo.processInfo.environment.filter {
!$0.key.hasPrefix("LSFGM_") && $0.key != "DISABLE_LSFGM"
}
process.environment = inherited.merging(env) { $1 }
// drive_c only exists after the first wineboot — fall back to the bottle root on fresh prefixes.
process.currentDirectoryURL = workingDirectory
?? (FileManager.default.fileExists(atPath: bottle.driveC.path) ? bottle.driveC : bottle.url)
let pipe = Pipe()
process.standardOutput = pipe
process.standardError = pipe
let start = Date()
do { try process.run() } catch {
try? logHandle.close()
// EBADARCH: macOS will not run Intel code, so Rosetta is missing or broken. Say that,
// not "Bad CPU type in executable" (issue #101).
if (error as NSError).code == 86 || error.localizedDescription.contains("Bad CPU type") {
// Only an Intel engine can mean that. An arm64 engine's loader is a link to the
// signed helper in Highball.app (WineLoaderHelper), and this error there means the
// link points at something that is not a Mac program any more.
if engine.manifest.requiresRosetta {
throw HighballError.failed("Rosetta, Apple's layer for Intel programs, is not working on this Mac, and Highball's Wine engine needs it. In Terminal run: softwareupdate --install-rosetta --agree-to-license, then try again.")
}
throw HighballError.failed("macOS refused to start the Wine loader of engine \(engine.id) (\(engine.wineBinary.path)). Quit and reopen Highball, which repairs the link to its loader, then try again.")
}
throw error
}
let reader = pipe.fileHandleForReading
// Wine's "Library x.dll ... not found" lines, kept so a failed run can be told apart
// from an engine whose files are gone (EngineIntegrity, highball#151/#153). Only those
// lines are kept: the rest of a launch's output can run to megabytes.
let importFailures = Collector()
// The exit code used to be computed and thrown away: a failed install produced a log
// shape-identical to a successful one, so user-submitted reports were undiagnosable
// (issue #36 cost two research passes to answer). It is now a footer, written below.
let status: Int32 = await withTaskCancellationHandler {
await withCheckedContinuation { cont in
process.terminationHandler = { p in cont.resume(returning: p.terminationStatus) }
// Drain on a background thread. The drain is the log handle's SOLE owner: it closes it
// only after EOF. Closing from the main flow raced the last writes — FileHandle's
// legacy write raises an ObjC exception on a closed handle, uncaught on this thread,
// and aborted the whole app (issues #13/#15, crash report confirmed). The throwing
// write(contentsOf:) can't raise; a failed log write is dropped, never fatal.
DispatchQueue.global(qos: .utility).async {
var buffer = Data()
// Repeated lines are collapsed and the log is capped (LogFilter, highball#224),
// for the file and for the live log alike.
var filter = LogFilter()
while true {
let chunk = reader.availableData
if chunk.isEmpty { break }
buffer.append(chunk)
var out = ""
while let nl = buffer.firstIndex(of: 0x0A) {
let line = String(decoding: buffer[..<nl], as: UTF8.self)
buffer.removeSubrange(...nl)
if line.contains("import_dll") { importFailures.append(line) }
for kept in filter.feed(line) {
out += kept + "\n"
onOutput?(kept)
}
}
if !out.isEmpty { try? logHandle.write(contentsOf: Data(out.utf8)) }
}
var rest = filter.finish()
if !buffer.isEmpty { rest += filter.feed(String(decoding: buffer, as: UTF8.self)) + filter.finish() }
for kept in rest { onOutput?(kept) }
if !rest.isEmpty { try? logHandle.write(contentsOf: Data((rest.joined(separator: "\n") + "\n").utf8)) }
try? logHandle.close()
}
}
} onCancel: {
// The busy op was stopped: end the process so the wait returns instead of hanging
// on a wineboot/installer that ignores its parent (review #12).
process.terminate()
}
let duration = Date().timeIntervalSince(start)
// Footer with the exit code. Written here, not in the drain: the drain blocks on
// availableData until every write end of the pipe closes, and wineserver outlives the
// process, so EOF often never arrives — a footer written there would never appear
// (measured). A second handle is safe because the process has already exited, so the
// drain has nothing left to write; the throwing write can't raise on a closed handle.
let footer = "# exit=\(status)\(Self.exitCodeNote(for: status)) after \(Int(duration))s\n"
if let tail = try? FileHandle(forWritingTo: logURL) {
_ = try? tail.seekToEnd()
try? tail.write(contentsOf: Data(footer.utf8))
try? tail.close()
}
onOutput?(footer.trimmingCharacters(in: .newlines))
// A run that failed while Wine could not find its own DLLs is not a failure of what was
// run: the engine has been emptied out under Highball (an antivirus quarantine is the
// usual cause), and every launch in it will fail the same way until it is installed
// again. Say so here, once, rather than leaving each caller to offer "try again with a
// fresh copy" for a download that was never the problem (highball#151, #153).
let gone = EngineIntegrity.gone(fromEngineAt: engine.root,
notFound: EngineIntegrity.librariesNotFound(in: importFailures.lines.joined(separator: "\n")),
arch: engine.manifest.arch)
if status != 0, !gone.isEmpty {
throw HighballError.engineDamaged(engine: engine.id, files: gone)
}
return LaunchResult(exitStatus: status, duration: duration, log: logURL, note: resolved.note)
}
/// Runs the executable directly under `wine` (not `start /unix`) so the process stays attached and
/// everything it and its children print lands in the log. The call returns when the program exits.
/// `program` replaces the executable's Mac path on Wine's command line (a Windows path through
/// a link the Mac does not see), while `executable` still names the log and the checks.
@discardableResult
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()
await syncKeyboardRegistry()
var note = headerNote
if linkedSteamView {
let text = "linked HKCU\\Software\\Wow6432Node\\Valve to Software\\Valve so 32-bit lookups find Steam (Rockstar launcher error 113)"
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
// the next start (measured 2026-10-06 with wmic). So an idle environment restarts, the way
// a stack mismatch restarts it below, and one running a program is left alone.
let linked = bottle.syncExternalDrives()
if !linked.isEmpty {
var text = "external drives linked: " + linked.map { "\($0.letter.uppercased()): \($0.path)" }.joined(separator: ", ")
if ProcessTable.liveServer(forPrefix: bottle.url) != nil {
if ProcessTable.isIdle(prefix: bottle.url) {
_ = try kill()
try? await Task.sleep(for: .seconds(2))
text += "; restarted the idle environment so Windows lists them"
} else {
text += "; Windows lists them after the environment's next start, a program is still running"
}
}
onOutput?("note: \(text)")
note = [note, text].compactMap { $0 }.joined(separator: "; ")
}
if let rebooted = try await rebootIdleEnvironmentIfMismatched(renderer: renderer, extraEnvironment: extraEnvironment) {
onOutput?("note: \(rebooted)")
note = [note, rebooted].compactMap { $0 }.joined(separator: "; ")
}
return try await run([program ?? executable.path] + arguments, renderer: renderer, extraEnvironment: extraEnvironment, label: executable.lastPathComponent, workingDirectory: workingDirectory, headerNote: note, onOutput: onOutput)
}
/// Restarts the environment's Wine server before a program launch when the server, and so
/// every Windows service in it, was booted under a different stack than this launch gets,
/// and nothing a person started is running. Returns the note for the log, nil when the
/// server serves as is or does not run.
///
/// A prefix boots `services.exe` once, from whichever process starts the server, and every
/// service it later starts inherits that first environment, not the launching program's.
/// On a fresh environment that process is a setup step (the first boot, a registry write,
/// an installer), all of which run without a renderer overlay. The Rockstar launcher's
/// self-update then restarts it through its own service, so the restarted launcher and its
/// browser ran under wined3d and the Sign In window stayed empty on every first launch
/// after install (highball#124, measured 2026-09-18: `services.exe` and the restarted
/// launcher had no WINEDLLPATH_PREPEND while the launch that started it did). A stop and a
/// second Play fixed it, which is what this does on its own. Never while something a
/// person started is running: a wrong stack for the services beats ending their program,
/// and that case is noted instead.
func rebootIdleEnvironmentIfMismatched(renderer: Renderer?, extraEnvironment: [String: String]) async throws -> String? {
guard let live = ProcessTable.liveServerEnvironment(forPrefix: bottle.url) else { return nil }
let wanted = try bottle.environment(engine: engine, renderer: renderer, extra: extraEnvironment)
guard let why = SteamRestart.reason(live: live, wanted: wanted,
wantedRenderer: (renderer ?? bottle.settings.renderer).rawValue,
custom: bottle.settings.customEnvironmentKeys + Array(extraEnvironment.keys)) else { return nil }
guard ProcessTable.isIdle(prefix: bottle.url) else {
return "the environment's Windows services keep the stack they started with (\(why)); a program is still running, so the environment was not restarted"
}
_ = try kill()
try? await Task.sleep(for: .seconds(2))
return "restarted the environment before the launch so its Windows services get this stack: \(why)"
}
/// Runs the pinned program, honouring its own renderer/env/args.
@discardableResult
public func start(pin: Pin, extraEnvironment: [String: String] = [:], onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult {
// A program behind a link a Windows installer made (the EA app) is found through Wine's
// stub. A Mac symlink an older Highball made beside the stub goes first: Wine took it for a
// folder and could not remove the link, which stopped the EA app's repair (highball-db#318).
let named = pin.launchURL(driveC: bottle.driveC)
WineReparsePoint.dematerializeAlong(named, driveC: bottle.driveC)
let exe = pin.executableURL(driveC: bottle.driveC)
// A pin whose target no longer exists otherwise dies deep in Wine with an opaque
// c0000135 ("failed to open"). Catch it here with a message the user can act on.
// Pins written before 0.7.6 stored only a filename, so old entries resolve to a
// drive_c-root path that isn't there (issue #23).
guard FileManager.default.fileExists(atPath: exe.path) else {
throw HighballError.invalid("\(pin.name) points at \(pin.path), which isn't there. If this was added by an older Highball, remove it and drag the program in again.")
}
let env = pin.environment.merging(extraEnvironment) { $1 }
// A pin's own mode is a preference recorded by a recipe or a person, not a demand: when
// this engine cannot run it, the environment's mode applies (and degrades in turn if it
// must), with a note, rather than a launch that dies before Wine (#61).
var renderer = pin.renderer
if let wanted = renderer, let why = wanted.unavailableReason(in: engine) {
onOutput?("note: \(pin.name) asks for \(Renderer.displayName(wanted)), but \(why) Using the environment's mode.")
renderer = nil
}
// cwd = the exe's folder, as a Windows shortcut would — games with relative asset paths need it.
// Wine gets the path through the link by its Windows name, since that path has no Mac side.
let throughLink = exe.path != named.path
return try await start(exe, arguments: pin.arguments, renderer: renderer, extraEnvironment: env,
workingDirectory: exe.deletingLastPathComponent(),
program: throughLink ? WineReparsePoint.windowsPath(for: named, driveC: bottle.driveC) : nil, onOutput: onOutput)
}
/// Steam's first self-update sometimes dies at a known Wine WoW64 spot and resumes cleanly
/// on relaunch (see recipes/launchers/steam.json knownIssues). Launches the pin and, if that
/// crash marker appears in the output, relaunches once so the update continues by itself.
public func startResumingKnownSteamCrash(pin: Pin, extraEnvironment: [String: String] = [:], onOutput: (@Sendable (String) -> Void)? = nil) async throws -> (result: LaunchResult, resumed: Bool) {
let collector = Collector()
let tap: @Sendable (String) -> Void = { line in collector.append(line); onOutput?(line) }
var result = try await start(pin: pin, extraEnvironment: extraEnvironment, onOutput: tap)
guard collector.lines.contains(where: { $0.contains("nested exception on signal stack") }) else {
return (result, false)
}
onOutput?("Steam's updater hit a known Wine crash — relaunching so it resumes…")
try? await Task.sleep(for: .seconds(3))
result = try await start(pin: pin, extraEnvironment: extraEnvironment, onOutput: onOutput)
return (result, true)
}
/// `force` adds -f: re-runs the inf installs even when the prefix looks current, which is
/// how a prefix missing its 32-bit half gets a second chance (issue #37).
/// Suffix of a `mscoree.dll` set aside for the duration of a `wineboot` run.
public static let asideSuffix = ".highball-wineboot"
/// The bottle's two `mscoree.dll` copies and the engine builtin each would be on a Wine-made
/// prefix, as (bottle file, engine file) pairs.
static func mscoreePairs(engine: InstalledEngine, bottle: Bottle) -> [(URL, URL)] {
[("windows/system32/mscoree.dll", "lib/wine/\(engine.manifest.pe64LibDir)/mscoree.dll"),
("windows/syswow64/mscoree.dll", "lib/wine/\(EngineManifest.pe32LibDir)/mscoree.dll")].map {
(bottle.driveC.appending(path: $0.0), engine.engineDir.appending(path: $0.1))
}
}
/// Whether the bottle carries Microsoft's .NET shim rather than Wine's `mscoree.dll`, which
/// is what the dotnet48 recipe leaves behind. A Wine-made prefix holds byte copies of the
/// engine builtins, so a size mismatch on either copy is the tell.
public static func hasForeignMscoree(engine: InstalledEngine, bottle: Bottle) -> Bool {
mscoreePairs(engine: engine, bottle: bottle).contains { pair in
guard let a = try? FileManager.default.attributesOfItem(atPath: pair.0.path)[.size] as? UInt64,
let b = try? FileManager.default.attributesOfItem(atPath: pair.1.path)[.size] as? UInt64 else { return false }
return a != b
}
}
/// Moves a foreign `mscoree.dll` (both halves) aside for a boot; `restoreMscoree` puts it back.
///
/// `wineboot -u` re-runs wine.inf's setup sections, which call `DllRegisterServer` on a fixed
/// list of DLLs, `mscoree.dll` among them. In a bottle where the dotnet48 recipe installed
/// Microsoft's .NET Framework that file is the real .NET shim, the registry marks it native,
/// and the shim's registration loads the CLR and never returns under wow64: wineboot waits
/// on the 32-bit rundll32 forever. Reproduced 2026-09-03 on the Gaming bottle (real .NET 4.8
/// + Steam): Repair and the engine-update wineboot hang at `do_register_dll ... mscoree.dll`,
/// on two engines, with and without leftover processes. Fresh bottles boot fine.
///
/// The tools one would reach for first do not work. A `mscoree=b` override makes Wine's
/// mscoree register, which calls `mscorwks.DllRegisterServerInternal`; the real mscorwks
/// has no such export and Wine aborts the process into a debugger. A `mscoree=d` override is
/// honoured by the 64-bit half and ignored by 32-bit processes under wow64 (the trace shows
/// them loading the real file as native regardless). And wineboot's inf comes from ntdll's
/// own data directory, so a filtered wine.inf cannot be pointed at through `WINEDATADIR`.
///
/// With the file absent, both halves fail to load it (the native-only override rules out a
/// builtin fallback), setupapi records one `could not load` and continues, and the boot
/// completes: 15 s where it used to hang. The inf's fake-DLL step drops Wine's mscoree into
/// the gap meanwhile, which is why the restore overwrites rather than checks. The real
/// installer already registered the runtime, so skipping that one entry loses nothing.
public static func setAsideForeignMscoree(engine: InstalledEngine, bottle: Bottle) throws -> Bool {
guard hasForeignMscoree(engine: engine, bottle: bottle) else { return false }
for (file, _) in mscoreePairs(engine: engine, bottle: bottle) where FileManager.default.fileExists(atPath: file.path) {
let aside = URL(fileURLWithPath: file.path + asideSuffix)
try? FileManager.default.removeItem(at: aside)
try FileManager.default.moveItem(at: file, to: aside)
}
return true
}
/// Puts back any `mscoree.dll` set aside by `setAsideForeignMscoree`, overwriting whatever the
/// boot left in its place. Safe to call when nothing is aside. Also run before every launch,
/// so a boot that died halfway (crash, force quit) cannot leave the bottle without its .NET.
public static func restoreMscoree(bottle: Bottle) {
for dir in ["windows/system32", "windows/syswow64"] {
let file = bottle.driveC.appending(path: "\(dir)/mscoree.dll")
let aside = URL(fileURLWithPath: file.path + asideSuffix)
guard FileManager.default.fileExists(atPath: aside.path) else { continue }
try? FileManager.default.removeItem(at: file)
try? FileManager.default.moveItem(at: aside, to: file)
}
}
public func wineboot(force: Bool = false) async throws -> LaunchResult {
let aside = try Self.setAsideForeignMscoree(engine: engine, bottle: bottle)
defer { if aside { Self.restoreMscoree(bottle: bottle) } }
return try await run(["wineboot", force ? "-fu" : "-u"], renderer: .wined3d, label: "wineboot",
restoreMscoreeFirst: false)
}
/// Stops the bottle: asks the server to kill its clients, waits for the server to go, then
/// ends whatever is still attached to the prefix. Returns the process ids it had to end
/// itself, which is normally none (see `ProcessTable` for why it is not always none).
@discardableResult
/// Whether a Steam client already runs in this bottle, by its command line.
public func steamIsRunning() -> Bool { Self.steamIsRunning(inPrefix: bottle.url) }
/// Pure: does a command line's program name end in steam.exe (Windows or Unix separators).
public static func isSteamExecutable(_ argv0: String) -> Bool {
argv0.replacingOccurrences(of: "\\", with: "/").lowercased().hasSuffix("/steam.exe")
}
/// What a `run <bottle> Steam [args]` should do. A running client stays: a second
/// steam.exe forwards its command line to it over Steam's own IPC and exits, so arguments
/// such as `-applaunch` still reach the game (highball#75); without arguments the only
/// thing to do is show the window (#33). No client: start one with the arguments.
public enum SteamInvocation: Equatable { case start, showWindow, forward }
public static func steamInvocation(clientRunning: Bool, arguments: [String]) -> SteamInvocation {
guard clientRunning else { return .start }
return arguments.isEmpty ? .showWindow : .forward
}
/// Hands a command line to the running Steam client: a second steam.exe forwards it and
/// exits. Nil when no client runs.
public func forwardToRunningSteam(_ arguments: [String], onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult? {
guard steamIsRunning() else { return nil }
let steam = bottle.driveC.appending(path: "Program Files (x86)/Steam/steam.exe")
return try await start(steam, arguments: arguments, onOutput: onOutput)
}
/// If a Steam client is already running in the bottle, asks it to show its window and
/// returns that launch; nil when no client runs (the caller then starts one).
///
/// After a game launch (`steam -silent -applaunch`) the silent client stays up. Starting
/// steam.exe again then only forwards to that instance and exits: no window, no error,
/// a dead button (issue #33). `steam://open/main` forwarded the same way makes the running
/// instance open its window, without restarting the wineserver under a game that may still
/// be running. Verified 2026-09-03: silent instance, open/main, Steam window up in seconds.
public func showRunningSteam(onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult? {
guard steamIsRunning() else { return nil }
let steam = bottle.driveC.appending(path: "Program Files (x86)/Steam/steam.exe")
return try await start(steam, arguments: ["steam://open/main"], onOutput: onOutput)
}
public func kill() throws -> [pid_t] {
let env = try bottle.environment(engine: engine, renderer: .wined3d)
// `-k` fails when no server holds the lock, which is exactly the crashed-server case
// the reaper below exists for, so its failure must not end the stop early.
try? Shell.run(engine.wineserverBinary.path, ["-k"], env: env)
// `wineserver -w` blocks until the server has released its lock. Bounded: a wedged
// server must not turn a Stop into a hang, the reaper below covers that case too.
let waiter = Process()
waiter.executableURL = engine.wineserverBinary
waiter.arguments = ["-w"]
waiter.environment = ProcessInfo.processInfo.environment.merging(env) { $1 }
try? waiter.run()
let deadline = Date().addingTimeInterval(10)
while waiter.isRunning && Date() < deadline { usleep(100_000) }
if waiter.isRunning { waiter.terminate() }
let leftovers = ProcessTable.processes(ofPrefix: bottle.url)
ProcessTable.terminate(leftovers)
return leftovers
}
// MARK: Registry helpers
public func regAdd(key: String, name: String, type: String, data: String) async throws {
_ = try await run(["reg", "add", key, "/v", name, "/t", type, "/d", data, "/f"], renderer: .wined3d, label: "reg")
}
public func regDelete(key: String, name: String) async throws {
_ = try await run(["reg", "delete", key, "/v", name, "/f"], renderer: .wined3d, label: "reg")
}
public func regQuery(key: String, name: String) async throws -> String? {
var lines: [String] = []
let collector = Collector()
_ = try await run(["reg", "query", key, "/v", name], renderer: .wined3d, label: "reg") { collector.append($0) }
lines = collector.lines
guard let line = lines.first(where: { $0.contains("REG_") }) else { return nil }
return line.split(whereSeparator: \.isWhitespace).last.map(String.init)
}
/// Parses a WINEDLLOVERRIDES-style string ("version=n,b;dxgi,d3d9=n") into per-dll registry
/// entries. Anything that isn't override syntax (pasted Proton launch options, quotes, spaces)
/// is skipped: the env var still carries the raw string, only the registry mirror filters.
/// Pure so it's unit-tested without a prefix.
public static func parseDllOverrides(_ overrides: String) -> [(name: String, order: String)] {
var entries: [(String, String)] = []
for entry in overrides.split(separator: ";") {
let parts = entry.split(separator: "=", maxSplits: 1, omittingEmptySubsequences: false)
guard parts.count == 2 else { continue }
let order = parts[1].trimmingCharacters(in: .whitespaces)
// n / b / native / builtin, optionally comma-paired; empty or d = disabled.
guard order.range(of: "^((n|b|native|builtin)(,(n|b|native|builtin))?|d|disabled)?$", options: .regularExpression) != nil else { continue }
for rawName in parts[0].split(separator: ",") {
var name = rawName.trimmingCharacters(in: .whitespaces).lowercased()
if name.hasSuffix(".dll") { name = String(name.dropLast(4)) }
guard !name.isEmpty, name.range(of: "^[a-z0-9_.+-]+$", options: .regularExpression) != nil else { continue }
entries.append((name, order))
}
}
return entries
}
/// The entries of a DLL-overrides field that `parseDllOverrides` would drop, so the settings
/// sheet can say so instead of losing them silently (2026-09-11 walkthrough).
public static func dllOverridesIgnored(_ overrides: String) -> [String] {
overrides.split(separator: ";").map { $0.trimmingCharacters(in: .whitespaces) }
.filter { !$0.isEmpty && parseDllOverrides($0).isEmpty }
}
static let dllOverridesKey = #"HKCU\Software\Wine\DllOverrides"#
/// Writes the Mac font names that stand in for Windows face names. One write per name that
/// has no value yet, then nothing: a value already stored is kept. The prefix registry is
/// what every later process reads, including a game that an already-running Steam starts.
/// `start` calls this. A registry file that does not exist yet (a bottle still in its first
/// boot) is left alone.
func syncMacFontSubstitutes() async {
let regURL = bottle.url.appending(path: "system.reg")
guard let text = try? String(contentsOf: regURL, encoding: .utf8) else { return }
for pair in MacFontSubstitutes.missing(in: text) {
try? await regAdd(key: MacFontSubstitutes.registryKey, name: pair.windowsName, type: "REG_SZ", data: pair.macName)
}
}
/// Mirrors the bottle's DLL-overrides field into the prefix registry. The env var reaches only
/// process trees Highball spawns itself; a game launched through an already-running Steam client
/// inherits Steam's environment from before the setting changed and never sees the override, so
/// mods like Cyber Engine Tweaks stay silent (issues #22/#25). Every new Wine process reads this
/// registry key live, no matter who spawned it. No-ops unless the field changed since the last
/// successful sync; on failure the marker stays stale so the next launch retries.
public func syncDllOverridesRegistry() async {
let current = bottle.settings.dllOverrides
guard current != (bottle.settings.dllOverridesSynced ?? "") else { return }
let entries = Self.parseDllOverrides(current)
let previous = Self.parseDllOverrides(bottle.settings.dllOverridesSynced ?? "")
let names = Set(entries.map(\.name))
// Removals are best-effort: a value that's already gone makes reg exit non-zero anyway.
for old in previous where !names.contains(old.name) {
try? await regDelete(key: Self.dllOverridesKey, name: old.name)
}
var allAdded = true
for entry in entries {
let status = try? await run(["reg", "add", Self.dllOverridesKey, "/v", entry.name, "/t", "REG_SZ", "/d", entry.order, "/f"],
renderer: .wined3d, label: "reg").exitStatus
if status != 0 { allAdded = false }
}
guard allAdded else { return }
markSynced { $0.dllOverridesSynced = current }
}
/// The marker `syncEngineAppDefaults` records: the engine and its defaults in a fixed order,
/// so the same set on the same engine compares equal whatever the dictionary order.
public static func appDefaultsMarker(engineID: String, defaults: [String: [String: String]]) -> String {
let body = defaults.keys.sorted().map { exe in
exe + "{" + defaults[exe]!.keys.sorted().map { "\($0)=\(defaults[exe]![$0]!)" }.joined(separator: ";") + "}"
}.joined(separator: ",")
return engineID + ":" + body
}
/// Mirrors the engine's per-executable registry defaults (EngineManifest.appDefaults) into the
/// prefix under HKCU\Software\Wine\AppDefaults\<exe>. Once per engine and value set: the marker
/// in the settings records what was written, so a launch on the same engine costs nothing and
/// an engine change or a manifest update rewrites. Values an earlier engine wrote are left in
/// place: they name that engine's own switches (patch 0006's CommandLineAppend), which other
/// trees ignore. On failure the marker stays stale so the next launch retries.
public func syncEngineAppDefaults() async {
let defaults = engine.manifest.appDefaults ?? [:]
let wanted = Self.appDefaultsMarker(engineID: engine.id, defaults: defaults)
guard wanted != (bottle.settings.engineAppDefaultsSynced ?? "") else { return }
var allAdded = true
for exe in defaults.keys.sorted() {
for name in defaults[exe]!.keys.sorted() {
let status = try? await run(["reg", "add", #"HKCU\Software\Wine\AppDefaults\"# + exe, "/v", name, "/t", "REG_SZ", "/d", defaults[exe]![name]!, "/f"],
renderer: .wined3d, label: "reg").exitStatus
if status != 0 { allAdded = false }
}
}
guard allAdded else { return }
markSynced { $0.engineAppDefaultsSynced = wanted }
}
/// Records a "last mirrored into the prefix registry" marker. Re-reads from disk rather than
/// saving `bottle`, which is a snapshot taken when the runner was built: saving it whole also
/// rewrites every other setting as it stood then, so a second sync in the same launch would
/// revert the marker the first one just wrote.
private func markSynced(_ apply: (inout BottleSettings) -> Void) {
guard var fresh = try? Bottle.load(bottle.url) else { return }
apply(&fresh.settings)
try? fresh.save()
}
/// Windows UI scaling. LogPixels is the Windows system DPI (96 = 100%, 240 = 250%): DPI-aware
/// apps and launchers follow it, though many full-screen games set their own render resolution and
/// ignore it. At 96 the Mac driver renders at 1x unless `retinaAt100` asks for native pixels;
/// above that it always switches to native Retina pixels (crisper, ~4x GPU work at native res) so
/// the scaled UI stays sharp. Clamped to the 96..240 range Wine accepts. Pure so the mapping is
/// unit-tested without touching a prefix.
public static func dpiRegistry(for logPixels: Int, retinaAt100: Bool = false) -> (retinaMode: String, logPixels: Int) {
let clamped = min(max(logPixels, 96), 240)
return (clamped > 96 || retinaAt100 ? "y" : "n", clamped)
}
public func setDpi(logPixels: Int, retinaAt100: Bool = false) async throws {
let v = Self.dpiRegistry(for: logPixels, retinaAt100: retinaAt100)
try await regAdd(key: #"HKCU\Software\Wine\Mac Driver"#, name: "RetinaMode", type: "REG_SZ", data: v.retinaMode)
try await regAdd(key: #"HKCU\Control Panel\Desktop"#, name: "LogPixels", type: "REG_DWORD", data: String(v.logPixels))
}
/// Wine's fallback D3D reports a fake NVIDIA GPU (GeForce 8800 GTX class) when it can't
/// recognize the Apple driver, which makes some games demand NVAPI and die. Pin an AMD
/// identity instead. The pair MUST exist in Wine's GPU table or the override is silently
/// discarded ("Invalid GPU override" in winediag): 0x1002:0x73bf is Radeon RX 6800/6900 XT,
/// present in Wine 10's table. Applied at bottle creation and by Repair.
/// AMD RX 6800/6900 XT. Regression-tested: changing this to a pair absent from Wine's
/// GPU table silently reverts bottles to the fake-NVIDIA identity (the 0.7.1 bug).
public static let gpuIdentity: (vendor: Int, device: Int) = (0x1002, 0x73bf)
/// Windows services translated cold by Rosetta can take 20+ seconds to reach RUNNING;
/// upstream Wine's SCM gives up after 10. CrossOver quadruples the timeout in code
/// (CW HACK 20218, for the Rockstar service); upstream honors this registry override.
/// 60 s ceiling, no cost when services start fast. Applied at bottle creation and Repair.
public static let servicesPipeTimeoutMs = 60000
public func setServiceTimeout() async throws {
try await regAdd(key: #"HKLM\System\CurrentControlSet\Control"#, name: "ServicesPipeTimeout",
type: "REG_SZ", data: String(Self.servicesPipeTimeoutMs))
}
/// Wine's Mac driver leaves the Command keys acting as Alt, so Cmd+C / Cmd+V reach Windows
/// apps as Alt+C / Alt+V — nothing pastes and macOS beeps. Mapping Command to Ctrl fixes
/// copy/paste everywhere (Steam's login and store pages are the common report).
///
/// Option must be mapped to Alt in the same breath: with both Command keys taken, winemac.drv
/// itself warns "there is no way to send an Alt key to Windows applications", which would break
/// Alt-driven game bindings. The four values move together or not at all.
///
/// Pure so the mapping is unit-tested without touching a prefix.
public static func keyboardRegistry(commandIsControl: Bool) -> [(name: String, data: String)] {
// Mac Driver settings are REG_SZ "y"/"n", not DWORD — a DWORD 1 is read as absent and the
// mapping silently stays off, which is exactly how this was first shipped and had to be fixed.
let on = commandIsControl ? "y" : "n"
return [
("LeftCommandIsCtrl", on), ("RightCommandIsCtrl", on),
("LeftOptionIsAlt", on), ("RightOptionIsAlt", on),
]
}
/// Applies the Command→Ctrl mapping when it differs from what the prefix already has, so an
/// existing bottle picks it up on its next launch and the settings toggle takes effect without
/// a Repair. Same shape as syncDllOverridesRegistry.
public func syncKeyboardRegistry() async {
let current = bottle.settings.commandIsControl
guard current != bottle.settings.commandIsControlSynced else { return }
guard (try? await setKeyboardMapping(commandIsControl: current)) != nil else { return }
var copy = bottle
copy.settings.commandIsControlSynced = current
try? copy.save()
}
public func setKeyboardMapping(commandIsControl: Bool) async throws {
for v in Self.keyboardRegistry(commandIsControl: commandIsControl) {
try await regAdd(key: #"HKCU\Software\Wine\Mac Driver"#, name: v.name,
type: "REG_SZ", data: v.data)
}
}
public func setGpuIdentity() async throws {
try await regAdd(key: #"HKCU\Software\Wine\Direct3D"#, name: "VideoPciVendorID", type: "REG_DWORD", data: String(Self.gpuIdentity.vendor))
try await regAdd(key: #"HKCU\Software\Wine\Direct3D"#, name: "VideoPciDeviceID", type: "REG_DWORD", data: String(Self.gpuIdentity.device))
}
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 {
private let lock = NSLock()
private var storage: [String] = []
func append(_ s: String) { lock.lock(); storage.append(s); lock.unlock() }
var lines: [String] { lock.lock(); defer { lock.unlock() }; return storage }
}