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
/// What a failure looks like on the primary surface: one sentence about what happened, one
/// about what it means, and at most one button that does the next thing (UX plan §3.6). Raw
/// output and exit codes never appear here; they stay behind a details view. A cause is named
/// only when the app actually detected it: a 60-second timeout is not "your connection dropped".
public struct Recovery: Equatable, Sendable {
public enum Action: Equatable, Sendable {
/// Run the same operation again (installs, downloads, recipe steps).
case retry
/// Re-run the bottle's Windows setup.
case repairBottle
/// Download and unpack this engine again over the damaged copy.
case reinstallEngine(String)
/// Nothing automatic; the details and a report are the next step.
case none
}
public var headline: String
public var meaning: String
public var actionTitle: String?
public var action: Action
public init(headline: String, meaning: String, actionTitle: String? = nil, action: Action = .none) {
self.headline = headline; self.meaning = meaning; self.actionTitle = actionTitle; self.action = action
}
/// The mapping from what actually failed to what the user sees. Unknown failures keep their
/// own message as the headline so nothing is hidden, and get no button.
public static func describe(_ error: Error) -> Recovery {
if let url = error as? URLError {
switch url.code {
case .notConnectedToInternet, .networkConnectionLost, .cannotFindHost, .cannotConnectToHost, .dnsLookupFailed:
return Recovery(headline: "The download could not reach the server.",
meaning: "Highball keeps what it already received and continues from there.",
actionTitle: "Try again", action: .retry)
case .timedOut:
return Recovery(headline: "The download stopped waiting for data.",
meaning: "Highball keeps what it already received and continues from there.",
actionTitle: "Try again", action: .retry)
default:
return Recovery(headline: "The download stopped.",
meaning: "Highball keeps what it already received and continues from there.",
actionTitle: "Try again", action: .retry)
}
}
guard let known = error as? HighballError else {
return Recovery(headline: (error as NSError).localizedDescription, meaning: "")
}
switch known {
case let .engineDamaged(engine, files):
// The files came back as "not found" from inside Wine, so the loader's own words
// ("could not load ...") are useless here: say where the files went and offer the
// one thing that brings them back. The exclusion matters more than the download —
// without it the fresh engine is quarantined again within the hour (#153).
return Recovery(headline: "Files are missing from Highball's engine.",
meaning: "\(EngineIntegrity.list(files)) left engine \(engine) after it was installed, so no Windows program can start in it. Antivirus software quarantining Highball's folder is what this looks like from the inside: add ~/Library/Application Support/Highball to its exclusions first, then install the engine again.",
actionTitle: "Install the engine again", action: .reinstallEngine(engine))
case .checksumMismatch:
return Recovery(headline: "The download didn't arrive intact.",
meaning: "This is usually a network problem. Highball discards the damaged file and downloads it again.",
actionTitle: "Download again", action: .retry)
// Before any other failed command, because this one is the environment rather than the
// step: while the licence sits unaccepted, macOS refuses every Xcode-provided tool, and
// winetricks' own closing line then names something unrelated ("wine cmd.exe ... returned
// empty string"). highball#180 spent three rounds looking at downloads and SourceForge
// before the reporter found it themselves. Retry is still the right button, because it is
// the right one once they have accepted.
case let .processFailed(_, _, output) where Self.xcodeLicenceUnaccepted(output):
return Recovery(headline: "Xcode's licence has not been accepted on this Mac.",
meaning: "Until it is, the developer tools this step needs refuse to run, so it stops partway and says something unrelated. Open Terminal, run sudo xcodebuild -license, read it through and accept it, then try again here.",
actionTitle: "Try again", action: .retry)
case let .processFailed(command, _, _) where command.hasPrefix("wineboot"):
return Recovery(headline: "The Windows environment didn't finish setting up.",
meaning: "Highball can run the setup again.",
actionTitle: "Repair", action: .repairBottle)
case let .processFailed(command, _, output) where command.contains("winetricks"):
// The command is "/bin/bash <winetricks> --unattended <verbs>": naming bash helps
// nobody (highball#135 read "/bin/bash didn't finish" and offered a fresh download).
let words = command.split(separator: " ").map(String.init)
let verbs = words.drop(while: { $0 != "--unattended" }).dropFirst().joined(separator: " ")
let what = verbs.isEmpty ? "The winetricks step" : "Installing \(verbs) with winetricks"
// The reason is the script's own last line, and asking for it under Details cost
// #135 two rounds with nothing pasted back. Say it up front.
var meaning = "It downloads its files from the internet as it runs, and those servers refuse now and then, so trying again in a few minutes often works."
// Where the whole run is, so a report can carry it: the newest winetricks file in the
// logs folder, which Troubleshooting opens. Said before the script's own words, because
// the reason stays the last thing anyone reads (highball#135).
meaning += " The full output is in Highball's logs folder, in the newest file with winetricks in its name."
if let reason = Self.winetricksReason(output) { meaning += " It said: \(reason)" }
return Recovery(headline: "\(what) didn't finish.", meaning: meaning,
actionTitle: "Try again", action: .retry)
case let .processFailed(command, _, _):
let name = command.split(separator: " ").first.map(String.init) ?? "The installer"
return Recovery(headline: "\(name) didn't finish.",
meaning: "Highball can try again with a fresh copy.",
actionTitle: "Try again", action: .retry)
case let .invalid(what) where what.contains("32-bit"):
return Recovery(headline: "The Windows environment didn't finish setting up.",
meaning: "Its 32-bit half is missing, which most installers need. Highball can repair it.",
actionTitle: "Repair", action: .repairBottle)
case let .missing(what):
return Recovery(headline: "Something Highball needs is missing.", meaning: what)
case let .invalid(what), let .failed(what):
return Recovery(headline: what, meaning: "")
}
}
}
extension Recovery {
/// macOS refuses every Xcode-provided command line tool until the licence has been accepted,
/// and prints this one sentence when it does. It can land anywhere in a step's output rather
/// than at the end, so it is matched across the whole of it: in highball#180 it appeared four
/// times in the middle of a corefonts run whose last real line was about `%AppData%`.
static func xcodeLicenceUnaccepted(_ output: String) -> Bool {
output.contains("You have not agreed to the Xcode license agreements")
}
/// The last line of a winetricks run that says something, skipping its progress noise and
/// the shell's own "exited with" footer. Nil when the output is empty.
static func winetricksReason(_ output: String) -> String? {
let noise = ["warning: taskset", "Executing", "------", "[mvk-", "fixme:", "exited with"]
let lines = output.split(separator: "\n").map { $0.trimmingCharacters(in: .whitespaces) }
return lines.last { line in
!line.isEmpty && !noise.contains { line.hasPrefix($0) || line.contains($0) }
}.map { String($0.prefix(200)) }
}
}