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 CryptoKit
import Foundation
public enum HighballError: Error, CustomStringConvertible {
case checksumMismatch(file: String, expected: String, actual: String)
case processFailed(command: String, status: Int32, output: String)
case missing(String)
case invalid(String)
/// Wine's own DLLs are gone from an installed engine, so nothing Windows can start in it
/// (highball#151, #153: an antivirus quarantine emptying parts of Highball's folder).
case engineDamaged(engine: String, files: [String])
/// A message already written for the user. Carries no prefix, so it reads as a sentence
/// rather than as a category the reader has to decode.
case failed(String)
public var description: String {
switch self {
case let .checksumMismatch(file, expected, actual):
return "checksum mismatch for \(file): expected \(expected), got \(actual)"
case let .processFailed(command, status, output):
return "\(command) exited with \(status)\n\(output)"
case let .engineDamaged(engine, files):
return "engine \(engine) is missing Wine's own \(files.joined(separator: ", "))"
case let .missing(what): return "missing: \(what)"
case let .invalid(what): return "invalid: \(what)"
case let .failed(message): return message
}
}
}
/// Progress callback: (component name, bytes received, total bytes or nil).
public typealias DownloadProgress = @Sendable (String, Int64, Int64?) -> Void
/// Downloads, verifies and lays out engines from manifests.
///
/// Installed layout: `engines/<id>/{engine, frameworks, renderers/<name>/..., manifest.json}`
public struct EngineStore: Sendable {
public let paths: HighballPaths
public init(paths: HighballPaths = HighballPaths()) { self.paths = paths }
// MARK: Query
public func installedEngines() throws -> [InstalledEngine] {
guard FileManager.default.fileExists(atPath: paths.engines.path) else { return [] }
let dirs = try FileManager.default.contentsOfDirectory(at: paths.engines, includingPropertiesForKeys: nil)
return dirs.compactMap { dir in
let manifest = dir.appending(path: "manifest.json")
guard let m = try? EngineManifest.load(from: manifest) else { return nil }
try? linkRuntime(dir) // heals broken runtime links from pre-0.7.9 installs
try? linkSignedLoader(dir, manifest: m) // an app that moved repoints its arm64 engines
// GStreamer took the plugin folder's `._libgst*.dylib` files for plugins (see AppleDouble); this also
// heals engines installed before the cleanup.
AppleDouble.removeTwins(in: InstalledEngine(manifest: m, root: dir).gstreamerPluginDir, recursive: false)
return InstalledEngine(manifest: m, root: dir)
}.sorted { $0.manifest.id < $1.manifest.id }
}
/// The engine to use by default: the one the bundled manifest names when it is installed,
/// else the newest installed. Newest is the highest id under numeric-aware ordering, so
/// `…-r10` beats `…-r9` and `…-r2`. After an engine update two engines coexist, and the
/// CLI, which has no bundled manifest, created bottles on the old one while the app used
/// the new one (found 2026-09-04: a bottle created from the CLI ran r0 next to the app's r1).
public static func defaultEngine(installed: [InstalledEngine], bundledID: String?) -> InstalledEngine? {
installed.first { $0.id == bundledID }
?? installed.max { $0.id.compare($1.id, options: .numeric) == .orderedAscending }
}
/// Whether an engine update may apply itself without a click: only when the Wine build is the
/// same (a component-only update, r1's MoltenVK or r2's timestamp shim), so no environment is
/// re-run and nothing can regress. Users kept appearing on old engines because the update
/// needed a click (#61's reporter was on r0 with 0.8.3; ux-plan item 9).
public static func autoUpdateAllowed(from installed: EngineManifest, to update: EngineManifest) -> Bool {
!EngineManifest.needsPrefixRefresh(from: installed, to: update)
}
/// Engines nothing references any more: not the default, not the engine of any bottle, and
/// not one the app still offers (`keep`: the bundled manifests, so an engine someone
/// downloaded for rollback survives the next update even with no bottle on it right now).
/// An engine update never removes an engine a bottle still runs on; a bottle keeps its
/// engine until its owner switches it (per-bottle choice, not migration).
public static func unreferencedEngines(installed: [InstalledEngine], referencedIDs: Set<String>, defaultID: String?, keep: Set<String> = []) -> [InstalledEngine] {
installed.filter { $0.id != defaultID && !referencedIDs.contains($0.id) && !keep.contains($0.id) }
}
/// Which licences a newly installed engine records as accepted: the ones asked for, plus any
/// already accepted on an engine installed here. Same id means the same licence text, so a
/// second engine carrying the same D3DMetal does not ask again. Not carrying them left an
/// engine that has D3DMetal but will not serve it, so a bottle set to Apple's DirectX 12
/// silently fell back on every launch with nothing obviously wrong (highball#61, reproduced
/// here 2026-09-09 when a fresh install of r5 dropped the acceptance made on r4).
public static func acceptances(requested: Set<String>, installed: [InstalledEngine]) -> [String] {
Array(requested.union(installed.flatMap { $0.manifest.acceptedLicenses ?? [] })).sorted()
}
/// Whether an engine update may move a bottle onto `fresh` without re-running the Windows
/// first boot. The question is about the bottle's OWN engine: comparing the previous default
/// instead walked bottles across Wine builds whenever the default's own step was
/// component-only (2026-09-09, a 0.8.9 build moved Wine 11 bottles onto its Wine 10 default
/// because r1 to r2 was same-Wine, and their prefixes are a different format).
/// A bottle whose engine is not installed here returns false: this build cannot tell.
///
/// Same Wine is not enough on its own: the move must also keep what the bottle's engine
/// offers. The GPTK 4 line (r6, r12, r14) shares the default line's Wine build and adds Apple's
/// D3DMetal 4, and 0.10.0's update walked those bottles onto the default engine, taking
/// D3DMetal 4 away without a word. `shipped` names every component this app still ships in any
/// of its manifests: one the bottle's engine has and `fresh` lacks holds the bottle back, unless
/// no manifest ships it any more (lsfg, withdrawn at its author's request, must not keep r7 and
/// r9 bottles off every later engine).
public static func canMoveBottle(on bottleEngine: EngineManifest?, to fresh: EngineManifest, shipped: Set<String>? = nil) -> Bool {
guard let bottleEngine, !EngineManifest.needsPrefixRefresh(from: bottleEngine, to: fresh) else { return false }
return componentsLost(from: bottleEngine, to: fresh, shipped: shipped).isEmpty
}
/// The components a move from `old` to `new` would take away, among those still shipped.
public static func componentsLost(from old: EngineManifest, to new: EngineManifest, shipped: Set<String>?) -> [String] {
guard let shipped else { return [] }
return old.components.keys.filter { shipped.contains($0) && new.components[$0] == nil }.sorted()
}
/// Where a bottle the default engine's update left behind should go instead: among `known`,
/// a later revision of the bottle's own engine line that runs on this macOS and takes the
/// bottle there without a first boot and without losing a shipped component. Of those, the
/// one adding the fewest components (the same variant, not a bigger one: the default line and
/// the GPTK 4 line share revision numbers), then the newest. A GPTK 4 bottle on r14 gets r16
/// this way when the default moves from r13 to r15, and an r13 bottle would get r15, not r16.
public static func successor(for bottleEngine: EngineManifest, among known: [EngineManifest],
shipped: Set<String>, macOS: String = EngineManifest.currentMacOS) -> EngineManifest? {
let candidates = known.filter { m in
m.id != bottleEngine.id
&& EngineManifest.isAtOrAfter(current: m.id, wanted: bottleEngine.id)
&& m.runs(onMacOS: macOS)
&& canMoveBottle(on: bottleEngine, to: m, shipped: shipped)
}
func added(_ m: EngineManifest) -> Int { m.components.keys.filter { bottleEngine.components[$0] == nil }.count }
return candidates.min { a, b in
if added(a) != added(b) { return added(a) < added(b) }
return a.id.compare(b.id, options: .numeric) == .orderedDescending
}
}
/// The one engine an update may delete: the default it just superseded, and only when no
/// bottle is left on it. Everything else stays, including an engine this build does not
/// recognise, because a newer Highball may have installed it and removing it both discards a
/// large download and strands the bottles that use it.
public static func engineToRemoveAfterUpdate(oldID: String, freshID: String,
referencedIDs: Set<String>,
installed: [InstalledEngine]) -> InstalledEngine? {
guard oldID != freshID, !referencedIDs.contains(oldID) else { return nil }
return installed.first { $0.id == oldID }
}
/// The engines the owner may remove from Settings: installed, not the default, and no
/// environment's engine. Only the engine an update supersedes goes on its own
/// (engineToRemoveAfterUpdate), so every other one stayed until the folder was cleared by hand
/// (Hayden asked for a way on Discord, 2026-10-23). A recipe that asks for one again
/// downloads it then. Oldest first.
public static func removableEngines(installed: [InstalledEngine], referencedIDs: Set<String>,
defaultID: String?) -> [InstalledEngine] {
installed.filter { $0.id != defaultID && !referencedIDs.contains($0.id) }
.sorted { $0.id.compare($1.id, options: .numeric) == .orderedAscending }
}
/// The bytes an engine's folder takes on disk, for the Settings row. Zero when it can't be read.
public static func diskBytes(of root: URL) -> Int64 {
let keys: Set<URLResourceKey> = [.totalFileAllocatedSizeKey, .isRegularFileKey]
guard let walk = FileManager.default.enumerator(at: root, includingPropertiesForKeys: Array(keys)) else { return 0 }
var total: Int64 = 0
for case let url as URL in walk {
guard let values = try? url.resourceValues(forKeys: keys), values.isRegularFile == true else { continue }
total += Int64(values.totalFileAllocatedSize ?? 0)
}
return total
}
/// The engine to offer when a program fails on `currentID`: the default engine when the
/// bottle is not on it (the newer one, usually), else the newest other installed engine.
/// nil with a single engine installed.
public static func alternateEngine(for currentID: String, installed: [InstalledEngine], defaultID: String?) -> InstalledEngine? {
let arch = installed.first { $0.id == currentID }?.manifest.arch
let movable = installed.filter { sameArch(current: arch, target: $0.manifest.arch) }
if let d = movable.first(where: { $0.id == defaultID }), d.id != currentID { return d }
return movable.filter { $0.id != currentID }
.max { $0.id.compare($1.id, options: .numeric) == .orderedAscending }
}
/// Whether an environment on an engine of the `current` architecture may move to an engine of
/// the `target` one. No prefix has been moved between the Intel engines and the native arm64
/// line, in either direction, so the picker, the failure advice and a recipe's engine ask
/// offer a new environment instead. An unknown current architecture (the engine's folder is
/// gone) keeps every engine offered, as before.
public static func sameArch(current: String?, target: String) -> Bool { current == nil || current == target }
/// The UserDefaults key behind Show older engine revisions in an environment's Advanced settings.
public static let showOlderRevisionsKey = "showOlderEngineRevisions"
/// One row per engine the app can put a bottle on: every installed engine, then every
/// bundled manifest that is not installed yet (it downloads when chosen). Newest first
/// within each group, by numeric-aware id order. When the bottle's own engine is in
/// neither list (its directory is gone), it is appended as a `missing` row so the picker
/// still shows what the bottle is on instead of a blank selection.
public struct OfferedEngine: Equatable, Sendable {
public let id: String
public let installed: Bool
public let missing: Bool
/// The manifest's display name, which says what sets revisions apart (a D3DMetal 4 beta, say).
/// The pickers showed bare ids, so a player looking for Game Porting Toolkit 4 could not tell
/// r26 from r27 (highball#546). Nil for a missing engine, whose manifest is gone with it.
public let displayName: String?
public init(id: String, installed: Bool, missing: Bool = false, displayName: String? = nil) {
self.id = id; self.installed = installed; self.missing = missing; self.displayName = displayName
}
/// What a picker row says: the display name and the id players and replies refer to, the same
/// "name · id" the game page shows when only one engine is offered.
public var label: String { displayName.map { "\($0) · \(id)" } ?? id }
}
///
/// A download row is only worth offering when it is the newest of its kind: every revision of a line is
/// cumulative, so r3 under r29 is noise, and the pickers had grown to 48 rows on macOS 27 (Hayden on Discord,
/// 2026-10-29). `allRevisions` false keeps, per line and macOS floor, the newest revision among those installed
/// and offered, the floor being what sets a line's flavours apart (a D3DMetal 4 revision needs macOS 27, the
/// plain one beside it does not). Installed engines and the bottle's own always stay listed.
public static func offeredEngines(installed: [InstalledEngine], known: [EngineManifest], current: String? = nil,
macOS: String = EngineManifest.currentMacOS, allRevisions: Bool = true) -> [OfferedEngine] {
let newestFirst: (String, String) -> Bool = { $0.compare($1, options: .numeric) == .orderedDescending }
let ids = Set(installed.map(\.id))
let arch = installed.first { $0.id == current }?.manifest.arch ?? known.first { $0.id == current }?.arch
let have = installed.filter { sameArch(current: arch, target: $0.manifest.arch) }
.sorted { newestFirst($0.id, $1.id) }.map { OfferedEngine(id: $0.id, installed: true, displayName: $0.manifest.displayName) }
// A manifest with a macOS floor above this Mac is not offered: it would download and
// then run untested (r6's D3DMetal was measured on 27 only). Installed engines stay listed.
let flavour: (EngineManifest) -> String = { "\(EngineManifest.line(of: $0.id) ?? $0.id)|\($0.minMacOS)" }
var newestOfFlavour: [String: String] = [:]
for m in installed.map(\.manifest) + known where m.runs(onMacOS: macOS) {
if let seen = newestOfFlavour[flavour(m)], !newestFirst(m.id, seen) { continue }
newestOfFlavour[flavour(m)] = m.id
}
let more = known.filter { !ids.contains($0.id) && $0.runs(onMacOS: macOS) && sameArch(current: arch, target: $0.arch) }
.filter { allRevisions || newestOfFlavour[flavour($0)] == $0.id }
.sorted { newestFirst($0.id, $1.id) }
.map { OfferedEngine(id: $0.id, installed: false, displayName: $0.displayName) }
var rows = have + more
if let current, !rows.contains(where: { $0.id == current }) { rows.append(OfferedEngine(id: current, installed: false, missing: true)) }
return rows
}
/// The engines New environment offers besides the default: the newest revision of each line built
/// for another architecture than the default engine's, installed or known. An environment never
/// changes architecture (`sameArch`), so before this the native arm64 line was reachable only
/// through a game recipe that pins it, whatever the preview key said (highball-db#537). Empty when
/// every engine this install sees shares the default's architecture, which is nearly everyone,
/// and New environment then asks nothing.
public static func newEnvironmentAlternatives(defaultArch: String, installed: [InstalledEngine], known: [EngineManifest],
macOS: String = EngineManifest.currentMacOS) -> [String] {
var ids = Set(installed.filter { $0.manifest.arch != defaultArch }.map(\.id))
ids.formUnion(known.filter { $0.arch != defaultArch && $0.runs(onMacOS: macOS) }.map(\.id))
var lines = Set<String>()
return ids.sorted { $0.compare($1, options: .numeric) == .orderedDescending }
.filter { lines.insert(EngineManifest.line(of: $0) ?? $0).inserted }
}
/// The engine Get started sets up on when the bundled one needs Rosetta and Rosetta could not be
/// installed: the newest engine this install sees that runs without it on this macOS, nil when it
/// sees none (no preview key). A Mac on macOS 27 whose update server never answered failed setup
/// in under a second while the native line sat in the bundle and the preview key was set (highball#413).
public static func startingEngineWithoutRosetta(known: [EngineManifest], macOS: String = EngineManifest.currentMacOS) -> EngineManifest? {
known.filter { !$0.requiresRosetta && $0.runs(onMacOS: macOS) }
.max { $0.id.compare($1.id, options: .numeric) == .orderedAscending }
}
public func engine(_ id: String) throws -> InstalledEngine {
let root = paths.engine(id)
let m = try EngineManifest.load(from: root.appending(path: "manifest.json"))
try? linkRuntime(root) // heals broken runtime links from pre-0.7.9 installs
try? linkSignedLoader(root, manifest: m)
return InstalledEngine(manifest: m, root: root)
}
/// Copies facts a newer bundled manifest states about an engine into the installed copy of
/// that engine's manifest, so an engine installed before the fact was known behaves as the
/// app now knows it should (the r11 and r12 Direct3D 9 rule, highball#198). Only fields the
/// installed manifest does not set are written; returns the ids updated.
@discardableResult
public func adoptKnownFacts(known: [EngineManifest]) -> [String] {
var updated: [String] = []
for engine in (try? installedEngines()) ?? [] {
guard let fact = known.first(where: { $0.id == engine.id }) else { continue }
var m = engine.manifest
var changed = false
if m.direct3D9 == nil, let d9 = fact.direct3D9 { m.direct3D9 = d9; changed = true }
if m.appDefaults == nil, let defaults = fact.appDefaults { m.appDefaults = defaults; changed = true }
guard changed else { continue }
if (try? m.save(to: engine.root.appending(path: "manifest.json"))) != nil { updated.append(engine.id) }
}
return updated
}
// MARK: Install
/// Installs every component of `manifest`. Optional components are skipped unless their
/// `acceptance` id is in `accepted` (or they have no acceptance requirement and `includeOptional`).
public func install(
_ manifest: EngineManifest,
accepted: Set<String> = [],
includeOptional: Bool = true,
progress: DownloadProgress? = nil
) async throws -> InstalledEngine {
try paths.ensure()
// An engine measured only on a newer macOS is neither offered nor installed on an older one (highball#85).
// The engine picker and the updates filtered on it, but Play's engine ask could still install one: the arm64
// line on macOS 26.4, where it cannot start (2026-10-19).
guard manifest.runs(onMacOS: EngineManifest.currentMacOS) else {
throw HighballError.failed("The \(manifest.displayName) engine needs macOS \(manifest.minMacOS) or later, and this Mac runs macOS \(EngineManifest.currentMacOS).")
}
// An arm64 engine runs through the signed loader in Highball.app and nothing else, so
// without it the download would only end in an engine that cannot start (WineLoaderHelper).
if manifest.isNativeARM64, WineLoaderHelper.locate() == nil {
throw HighballError.failed("The \(manifest.displayName) engine runs through Highball's signed Wine loader, which comes with Highball.app. Install Highball in Applications (or point \(WineLoaderHelper.environmentKey) at its WineLoader.app) and try again.")
}
let root = paths.engine(manifest.id)
let staging = paths.engines.appending(path: ".\(manifest.id).partial", directoryHint: .isDirectory)
try? FileManager.default.removeItem(at: staging)
try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)
for (name, component) in manifest.orderedComponents {
// A Stop between components, or during unpack, ends the install here rather than
// finishing with "Engine ready" behind the user's back.
try Task.checkCancellation()
if component.isOptional {
if let acceptance = component.acceptance, !accepted.contains(acceptance) { continue }
if component.acceptance == nil, !includeOptional { continue }
}
let archive = try await download(component, name: name, progress: progress)
try extract(archive, component: component, name: name, into: staging)
}
// A licence the owner already accepted on another installed engine carries over. It is the
// same licence text under the same id, and not carrying it leaves an engine that has
// D3DMetal but will not serve it, so a bottle set to Apple's DirectX 12 silently falls back
// on every launch with nothing obviously wrong (highball#61, and again here 2026-09-09 when
// a fresh install of r5 dropped the acceptance made on r4). updateEngine() already gathered
// acceptances this way; doing it here covers every path, including first run and the CLI.
var saved = manifest
saved.acceptedLicenses = Self.acceptances(requested: accepted, installed: (try? installedEngines()) ?? [])
try saved.save(to: staging.appending(path: "manifest.json"))
try linkRuntime(staging)
try linkSignedLoader(staging, manifest: saved)
AppleDouble.removeTwins(in: staging, recursive: true)
// The unpacked tree must be a whole engine before it replaces anything: an archive that
// unpacked short (a full disk, a file the archive lacks) used to install all the same and
// fail every launch afterwards (highball#118). The archive was checksummed, so the fault
// is local; the staging tree goes and the next attempt starts over.
if manifest.components["wine"] != nil {
let missing = InstalledEngine(manifest: saved, root: staging).missingFiles
if !missing.isEmpty {
try? FileManager.default.removeItem(at: staging)
throw HighballError.failed("The engine unpacked incomplete, \(missing.joined(separator: ", ")) missing. Check the free space on this disk and try again.")
}
}
try? FileManager.default.removeItem(at: root)
try FileManager.default.moveItem(at: staging, to: root)
try stripQuarantine(root)
return InstalledEngine(manifest: saved, root: root)
}
/// Records acceptance of a license for an already-installed engine.
public func accept(license id: String, engine: InstalledEngine) throws -> InstalledEngine {
var m = engine.manifest
var set = Set(m.acceptedLicenses ?? []); set.insert(id)
m.acceptedLicenses = set.sorted()
try m.save(to: engine.root.appending(path: "manifest.json"))
return InstalledEngine(manifest: m, root: engine.root)
}
/// Downloads to `downloads/<basename>` and verifies SHA-256. Reuses a cached file if it verifies.
///
/// Resumable and retried: the bytes land in `<basename>.partial` as they arrive, a retry asks
/// for the rest with `Range` and `If-Range` on the ETag the first response carried, and up to
/// three attempts with a short backoff run before the user sees anything. The checksum at the
/// end stays the integrity backstop, so a bad resume can never install; a checksum failure
/// discards the partial so the next attempt starts clean. A 60 s no-data timeout keeps a
/// stalled connection from hanging forever.
public func download(_ component: EngineManifest.Component, name: String, progress: DownloadProgress? = nil) async throws -> URL {
try paths.ensure()
// verify local archives too
if component.url.isFileURL {
let actual = try sha256(of: component.url)
guard actual == component.sha256.lowercased() else {
throw HighballError.checksumMismatch(file: component.url.lastPathComponent,
expected: component.sha256, actual: actual)
}
return component.url
}
let dest = paths.downloads.appending(path: component.url.lastPathComponent)
if FileManager.default.fileExists(atPath: dest.path), try sha256(of: dest) == component.sha256.lowercased() {
return dest
}
// Named by checksum so two installs sharing a basename (or an asset that changed under
// the same name) never append into each other's file.
let partial = dest.appendingPathExtension("\(component.sha256.prefix(12)).partial")
let etagFile = dest.appendingPathExtension("\(component.sha256.prefix(12)).etag")
let expected = Int64(component.size ?? 0)
let cfg = URLSessionConfiguration.ephemeral
cfg.timeoutIntervalForRequest = 60
cfg.timeoutIntervalForResource = 3600
let session = URLSession(configuration: cfg)
defer { session.finishTasksAndInvalidate() }
var lastError: Error?
for attempt in 1...3 {
do {
try await fetch(component.url, into: partial, etagFile: etagFile, session: session) { received, total in
progress?(name, received, total > 0 ? total : expected)
}
lastError = nil
break
} catch {
// A stop from the user is not a transient network failure: no retry, the
// partial file stays for the next attempt.
if error is CancellationError || (error as? URLError)?.code == .cancelled || Task.isCancelled { throw error }
lastError = error
if attempt < 3 { try? await Task.sleep(for: .seconds([2, 5][attempt - 1])) }
try Task.checkCancellation() // a Stop during the backoff must not start another attempt
}
}
if let lastError { throw lastError }
try? FileManager.default.removeItem(at: dest)
try FileManager.default.moveItem(at: partial, to: dest)
try? FileManager.default.removeItem(at: etagFile)
// Partials of other versions of the same file are dead weight once this one verified.
if let siblings = try? FileManager.default.contentsOfDirectory(at: paths.downloads, includingPropertiesForKeys: nil) {
for f in siblings where f.lastPathComponent.hasPrefix(dest.lastPathComponent + ".") && (f.pathExtension == "partial" || f.pathExtension == "etag") {
try? FileManager.default.removeItem(at: f)
}
}
let actual = try sha256(of: dest)
guard actual == component.sha256.lowercased() else {
try? FileManager.default.removeItem(at: dest)
throw HighballError.checksumMismatch(file: dest.lastPathComponent, expected: component.sha256, actual: actual)
}
progress?(name, expected > 0 ? expected : 1, expected > 0 ? expected : 1)
return dest
}
/// One attempt: append to `partial` from its current size when the server honours the range,
/// restart from zero when it does not (or the ETag changed). Streams to disk, reporting every
/// ~2 MB (the app once showed a blank sheet for a whole 270 MB download).
func fetch(_ url: URL, into partial: URL, etagFile: URL, session: URLSession,
onProgress: @escaping (Int64, Int64) -> Void) async throws {
let fm = FileManager.default
let have = (try? fm.attributesOfItem(atPath: partial.path)[.size] as? Int64) ?? 0
let etag = try? String(contentsOf: etagFile, encoding: .utf8)
var request = URLRequest(url: url)
if let range = DownloadResume.rangeHeaders(partialBytes: have, etag: etag) {
for (k, v) in range { request.setValue(v, forHTTPHeaderField: k) }
}
let (bytes, response) = try await session.bytes(for: request)
guard let http = response as? HTTPURLResponse else { throw HighballError.invalid("no HTTP response for \(url.absoluteString)") }
let decision = DownloadResume.decide(status: http.statusCode, partialBytes: have)
switch decision {
case .failed: throw HighballError.invalid("HTTP \(http.statusCode) for \(url.absoluteString)")
case .restart: try? fm.removeItem(at: partial)
case .append: break
}
if let newTag = http.value(forHTTPHeaderField: "ETag") { try? newTag.write(to: etagFile, atomically: true, encoding: .utf8) }
if !fm.fileExists(atPath: partial.path) { fm.createFile(atPath: partial.path, contents: nil) }
let handle = try FileHandle(forWritingTo: partial)
defer { try? handle.close() }
try handle.seekToEnd()
var written = decision == .append ? have : 0
// A chunked response reports -1; then the caller's manifest size drives the bar.
let total: Int64 = http.expectedContentLength < 0 ? 0 : (decision == .append ? have + http.expectedContentLength : http.expectedContentLength)
var buffer = Data(); buffer.reserveCapacity(1 << 20)
var lastReported: Int64 = written
for try await byte in bytes {
buffer.append(byte)
if buffer.count >= 1 << 20 {
try handle.write(contentsOf: buffer); written += Int64(buffer.count); buffer.removeAll(keepingCapacity: true)
if written - lastReported >= 2_000_000 { lastReported = written; onProgress(written, total) }
}
}
if !buffer.isEmpty { try handle.write(contentsOf: buffer); written += Int64(buffer.count) }
onProgress(written, total)
}
/// Non-nil, with the reason, when placing a directory at `dest` would take over a directory
/// that already has contents. A single-file target and an empty or absent directory are fine.
static func directoryCollision(at dest: URL, sourceIsDirectory: Bool) -> String? {
guard sourceIsDirectory else { return nil }
var isDir: ObjCBool = false
guard FileManager.default.fileExists(atPath: dest.path, isDirectory: &isDir), isDir.boolValue else { return nil }
let count = (try? FileManager.default.contentsOfDirectory(atPath: dest.path).count) ?? 0
return count == 0 ? nil : "which already holds \(count) items"
}
func extract(_ archive: URL, component: EngineManifest.Component, name: String, into root: URL) throws {
guard let ex = component.extract else {
// Plain file (e.g. winetricks script): copy into tools/.
let tools = root.appending(path: "tools", directoryHint: .isDirectory)
try FileManager.default.createDirectory(at: tools, withIntermediateDirectories: true)
let dest = tools.appending(path: archive.lastPathComponent)
try? FileManager.default.removeItem(at: dest)
try FileManager.default.copyItem(at: archive, to: dest)
try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: dest.path)
return
}
let scratch = root.appending(path: ".extract-\(name)", directoryHint: .isDirectory)
try FileManager.default.createDirectory(at: scratch, withIntermediateDirectories: true)
try Shell.run("/usr/bin/tar", ["-xf", archive.path, "-C", scratch.path])
let source: URL
if let sub = ex.subpath ?? ex.strip {
source = scratch.appending(path: sub)
} else {
source = scratch
}
guard FileManager.default.fileExists(atPath: source.path) else {
throw HighballError.missing("\(ex.subpath ?? ex.strip ?? "") inside \(archive.lastPathComponent)")
}
// `into` names a directory (a whole overlay) or a single file: a component that replaces
// one file another component installed, like a patched libMoltenVK.dylib on top of the
// runtime's. A file target leaves the rest of the parent directory alone.
var isDir: ObjCBool = false
_ = FileManager.default.fileExists(atPath: source.path, isDirectory: &isDir)
let dest = root.appending(path: ex.into, directoryHint: isDir.boolValue ? .isDirectory : .notDirectory)
if let why = Self.directoryCollision(at: dest, sourceIsDirectory: isDir.boolValue) {
// highball#76: a directory component that lands on a directory another component
// filled used to replace it wholesale (the first r7 candidate lost its whole Wine
// tree this way and still reported "installed"). Refuse and say which.
throw HighballError.invalid("component '\(name)' would replace \(ex.into), \(why). A component adds a directory of its own or replaces one file; to add a file to another component's directory, name that file as 'into'.")
}
try FileManager.default.createDirectory(at: dest.deletingLastPathComponent(), withIntermediateDirectories: true)
try? FileManager.default.removeItem(at: dest)
try FileManager.default.moveItem(at: source, to: dest)
try? FileManager.default.removeItem(at: scratch)
}
/// Symlinks the Template's runtime dylibs into engine/lib so Wine binaries resolve
/// @loader_path/../lib/… and @rpath names without any DYLD_* environment (which SIP
/// strips when a restricted binary like /bin/sh sits in the exec chain — winetricks does).
///
/// Targets MUST be relative: install() links inside the .partial staging dir and then
/// renames it into place, so absolute targets died with the staging path — every fresh
/// install shipped broken links until 0.7.9 (caught by the dotnet48 E2E gate; games
/// still ran because launches carry DYLD_FALLBACK_LIBRARY_PATH, winetricks did not).
/// A link with any other target is replaced, which also heals engines installed by
/// older versions when this runs again from installedEngines()/engine(_:).
func linkRuntime(_ root: URL) throws {
let fm = FileManager.default
let engineLib = root.appending(path: "engine/lib", directoryHint: .isDirectory)
guard fm.fileExists(atPath: engineLib.path) else { return }
var handled = Set<String>()
func link(_ name: String, to relativeTarget: String) {
guard handled.insert(name).inserted else { return } // first source dir wins, as before
let dest = engineLib.appending(path: name)
if let existing = try? fm.destinationOfSymbolicLink(atPath: dest.path) {
if existing == relativeTarget { return }
try? fm.removeItem(at: dest) // absolute/staging target from a pre-0.7.9 install
} else if fm.fileExists(atPath: dest.path) {
return // a real file — leave it alone
}
try? fm.createSymbolicLink(atPath: dest.path, withDestinationPath: relativeTarget)
}
for sub in ["frameworks", "frameworks/GStreamer.framework/Versions/1.0/lib"] {
let dir = root.appending(path: sub, directoryHint: .isDirectory)
guard let entries = try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil) else { continue }
for entry in entries where entry.pathExtension == "dylib" {
link(entry.lastPathComponent, to: "../../\(sub)/\(entry.lastPathComponent)")
}
}
// GStreamer.framework itself, for modules that reference it by framework path.
link("GStreamer.framework", to: "../../frameworks/GStreamer.framework")
}
/// Points an arm64 engine's `wine` at Highball's signed loader (WineLoaderHelper). Wine's ntdll
/// starts every child process through `<directory of ntdll.so>/wine`, so that file becomes a
/// symlink to the helper and `bin/wine` a relative link to it, the way Wine installs its own;
/// the engine's loader, built unsigned by CI, is set aside once as `wine.unsigned`. Redone on
/// every read of the engine, like linkRuntime, so an app that moved, or was updated (the helper
/// is the app's), heals its engines on the next launch. Nothing happens for an Intel engine, or
/// when no helper is on this Mac (the CLI without the app; `missingFiles` then says so).
func linkSignedLoader(_ root: URL, manifest: EngineManifest, helper: URL? = WineLoaderHelper.locate()) throws {
guard manifest.isNativeARM64, let helper else { return }
let fm = FileManager.default
let unixDir = root.appending(path: "engine/lib/wine/\(manifest.unixLibDir)", directoryHint: .isDirectory)
for (link, target) in [(unixDir.appending(path: "wine"), helper.path),
(root.appending(path: "engine/bin/wine"), "../lib/wine/\(manifest.unixLibDir)/wine")] {
if let existing = try? fm.destinationOfSymbolicLink(atPath: link.path) {
if existing == target { continue }
try fm.removeItem(at: link) // a stale link, dangling or to an old app location
} else if fm.fileExists(atPath: link.path) {
let aside = link.appendingPathExtension("unsigned")
try? fm.removeItem(at: aside)
try fm.moveItem(at: link, to: aside) // the engine's own loader: kept, never used
}
try fm.createDirectory(at: link.deletingLastPathComponent(), withIntermediateDirectories: true)
try fm.createSymbolicLink(atPath: link.path, withDestinationPath: target)
}
}
func stripQuarantine(_ url: URL) throws {
try? Shell.run("/usr/bin/xattr", ["-dr", "com.apple.quarantine", url.path])
}
public func sha256(of url: URL) throws -> String {
let handle = try FileHandle(forReadingFrom: url)
defer { try? handle.close() }
var hasher = SHA256()
while let chunk = try handle.read(upToCount: 4 << 20), !chunk.isEmpty {
hasher.update(data: chunk)
}
return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
}
/// An engine that has been laid out on disk.
public struct InstalledEngine: Sendable {
public let manifest: EngineManifest
public let root: URL
public var id: String { manifest.id }
/// Direct3D 9 stays with Wine's own Direct3D in the automatic modes on this engine (see
/// `EngineManifest.direct3D9`).
public var direct3D9UsesWined3d: Bool { manifest.direct3D9 == "wined3d" }
/// Short human name for UI ("Wine 10.0 (Sikarugir)" beats a manifest id).
public var displayName: String {
manifest.components["wine"]?.version ?? manifest.displayName
}
public var engineDir: URL { root.appending(path: "engine", directoryHint: .isDirectory) }
public var frameworksDir: URL { root.appending(path: "frameworks", directoryHint: .isDirectory) }
/// Where GStreamer looks for its plugins (GST_PLUGIN_PATH in baseEnvironment).
var gstreamerPluginDir: URL { frameworksDir.appending(path: "GStreamer.framework/Versions/1.0/lib/gstreamer-1.0", directoryHint: .isDirectory) }
/// The library that keeps Wine's audio pulls under half a period (highball#127) and, since
/// 20261008, limits a mix over full scale (highball-db#349), when the engine ships it as a
/// component. Bottle.environment inserts it into Wine's processes.
public var audioBufferLibrary: URL? {
let lib = frameworksDir.appending(path: "libhbaudiobuf.dylib")
return FileManager.default.fileExists(atPath: lib.path) ? lib : nil
}
/// athei's x87sidecar (MIT), when the engine ships it as a component. Wine re-executes a
/// 32-bit program through it when ROSETTA_X87_PATH names it (the Wine 11 engines' patch 0012,
/// cooperative attach, no entitlements), and it compiles the program's x87 maths much faster
/// than Rosetta does: Tale of Wuxia's maps went from 4.4 to 45 fps (highball-db#352).
public var x87Sidecar: URL? {
let tool = root.appending(path: "x87sidecar/x87sidecar")
return FileManager.default.isExecutableFile(atPath: tool.path) ? tool : nil
}
public var renderersDir: URL { root.appending(path: "renderers", directoryHint: .isDirectory) }
public var wineBinary: URL { engineDir.appending(path: "bin/wine") }
public var wineserverBinary: URL { engineDir.appending(path: "bin/wineserver") }
/// Files no engine runs without: the Wine loader, its server, the kernel DLLs of both
/// halves and the Unix side of ntdll. An engine missing any of them fails every launch
/// with "could not load kernel32.dll" (highball#118, an unpack that stopped early), so an
/// install refuses to finish without them and the app reinstalls its own when they are gone.
public static let requiredFiles = requiredFiles(for: EngineManifest(id: "", displayName: "", arch: "x86_64", minMacOS: "", components: [:]))
/// The same list for an engine of either architecture. An arm64 engine also needs FEX, in the
/// two DLLs Wine loads under its emulator names and the Unix helper each of them loads by name:
/// without them it runs ARM64 Windows programs only, which no game is.
public static func requiredFiles(for manifest: EngineManifest) -> [String] {
var files = ["engine/bin/wine", "engine/bin/wineserver",
"engine/lib/wine/\(manifest.pe64LibDir)/kernel32.dll", "engine/lib/wine/\(manifest.pe64LibDir)/ntdll.dll",
"engine/lib/wine/\(EngineManifest.pe32LibDir)/kernel32.dll", "engine/lib/wine/\(manifest.unixLibDir)/ntdll.so"]
if manifest.isNativeARM64 {
files += ["engine/lib/wine/\(manifest.pe64LibDir)/xtajit64.dll", "engine/lib/wine/\(manifest.pe64LibDir)/xtajit.dll",
"engine/lib/wine/\(manifest.unixLibDir)/libarm64ecfex.so", "engine/lib/wine/\(manifest.unixLibDir)/libwow64fex.so"]
}
return files
}
/// How the loader shows up in `missingFiles` when an arm64 engine's `wine` is not Highball's
/// signed helper: its own loader is there, so the file check alone would pass.
public static let signedLoaderName = "engine/bin/wine (Highball's signed Wine loader)"
/// Which of `requiredFiles` are absent, relative to the engine's root.
public var missingFiles: [String] {
var missing = Self.requiredFiles(for: manifest).filter { !FileManager.default.fileExists(atPath: root.appending(path: $0).path) }
if manifest.isNativeARM64, !usesSignedLoader { missing.append(Self.signedLoaderName) }
return missing
}
public var isComplete: Bool { missingFiles.isEmpty }
/// Whether this engine's Unix-side `wine`, the path Wine's ntdll starts child processes
/// through, is a link to Highball's signed loader (EngineStore.linkSignedLoader).
public var usesSignedLoader: Bool {
let link = engineDir.appending(path: "lib/wine/\(manifest.unixLibDir)/wine")
guard let dest = try? FileManager.default.destinationOfSymbolicLink(atPath: link.path) else { return false }
return WineLoaderHelper.isHelperPath(dest) && FileManager.default.isExecutableFile(atPath: dest)
}
/// resolves the shim directory and repairs the real-driver link; it touches the disk, so the app caches it per engine
public func resolveLsfgShimDir() -> URL? {
let dir = renderersDir.appending(path: "lsfg", directoryHint: .isDirectory)
let shim = dir.appending(path: "libMoltenVK.dylib")
guard (try? shim.resolvingSymlinksInPath().resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) == true,
FileManager.default.isReadableFile(atPath: shim.path) else { return nil }
// use a different filename to avoid loading the shim recursively
let fm = FileManager.default
let driver = frameworksDir.appending(path: "libMoltenVK.dylib")
guard (try? driver.resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) == true,
fm.isReadableFile(atPath: driver.path) else { return nil }
let link = dir.appending(path: Self.lsfgRealDriverName)
let target = "../../frameworks/libMoltenVK.dylib"
let current = try? fm.destinationOfSymbolicLink(atPath: link.path)
// repair links without replacing regular files
if current != target && (current != nil || !fm.fileExists(atPath: link.path)) {
do {
if current != nil { try fm.removeItem(at: link) }
try fm.createSymbolicLink(atPath: link.path, withDestinationPath: target)
} catch { return nil }
}
guard fm.isReadableFile(atPath: link.path),
(try? link.resolvingSymlinksInPath().resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) == true,
link.resolvingSymlinksInPath() != dir.appending(path: "libMoltenVK.dylib").resolvingSymlinksInPath() else { return nil }
return dir
}
/// alternate filename for the real driver
public static let lsfgRealDriverName = "libMoltenVK.real.dylib"
public var winetricks: URL? {
let t = root.appending(path: "tools/winetricks")
return FileManager.default.fileExists(atPath: t.path) ? t : nil
}
/// Renderer overlay directory: Gin's own `renderers/<name>` wins over the Template's `frameworks/renderer/<name>`.
/// Whether the engine carries a renderer at all, licence aside: D3DMetal ships inside the
/// runtime template and `rendererDir` hides it until the licence is accepted.
public func ships(_ name: String) -> Bool {
let own = renderersDir.appending(path: name, directoryHint: .isDirectory).appending(path: "wine")
let template = frameworksDir.appending(path: "renderer/\(name)", directoryHint: .isDirectory).appending(path: "wine")
return FileManager.default.fileExists(atPath: own.path) || FileManager.default.fileExists(atPath: template.path)
}
public func rendererDir(_ name: String) -> URL? {
if let gate = EngineManifest.gatedRenderers[name], !(manifest.acceptedLicenses ?? []).contains(gate) { return nil }
let own = renderersDir.appending(path: name, directoryHint: .isDirectory)
if FileManager.default.fileExists(atPath: own.appending(path: "wine").path) { return own }
let template = frameworksDir.appending(path: "renderer/\(name)", directoryHint: .isDirectory)
if FileManager.default.fileExists(atPath: template.appending(path: "wine").path) { return template }
return nil
}
/// The D3DMetal timestamp shim overlay, laid out for launch, or nil when the engine has none.
/// The shim's d3d12.dll cannot load the real one under its own name, so the real PE is laid out
/// beside the shim as apd12.dll ("Apple's d3d12"), with its Mach-O half symlinked as
/// x86_64-unix/apd12.so into the licensed D3DMetal overlay. The copy differs from Apple's file
/// in nine bytes: its internal export name, because Wine 10 tells builtin modules apart by file
/// name but CrossOver's Wine 11 by that internal name, and with it untouched the copy came back
/// as the shim itself (no DirectX 12 device at all, 2026-09-08). Idempotent, and redone when the
/// D3DMetal files change. The copy is compared by content: D3DMetal 4.0 beta 2 and beta 3 ship
/// d3d12.dll at the same size, and a file unpacked from an archive keeps its build date, older
/// than a copy made earlier, so a size and date check kept beta 2's copy in front of beta 3 in an
/// engine whose D3DMetal was replaced in place (2026-10-15).
public func timestampShimDir(d3dmetal: URL) -> URL? {
guard let shim = rendererDir("d3dmetal-tsshim") else { return nil }
let fm = FileManager.default
let realPE = d3dmetal.appending(path: "wine/\(manifest.pe64LibDir)/d3d12.dll")
let realSO = d3dmetal.appending(path: "wine/\(manifest.unixLibDir)/d3d12.so")
let pe = shim.appending(path: "wine/\(manifest.pe64LibDir)/\(Self.shimRealName).dll")
let so = shim.appending(path: "wine/\(manifest.unixLibDir)/\(Self.shimRealName).so")
do {
let wanted = try PEExportName.patched(Data(contentsOf: realPE), to: "\(Self.shimRealName).dll")
if (try? Data(contentsOf: pe)) != wanted {
try? fm.removeItem(at: pe)
try wanted.write(to: pe)
}
try fm.createDirectory(at: so.deletingLastPathComponent(), withIntermediateDirectories: true)
if (try? fm.destinationOfSymbolicLink(atPath: so.path)) != realSO.path {
try? fm.removeItem(at: so)
try fm.createSymbolicLink(at: so, withDestinationURL: realSO)
}
// The 0.9.0 layout (a hard link under this name) is the one that collided.
for stale in ["wine/\(manifest.pe64LibDir)/d3d12_d3dmetal.dll", "wine/\(manifest.unixLibDir)/d3d12_d3dmetal.so"] {
try? fm.removeItem(at: shim.appending(path: stale))
}
return shim
} catch {
return nil
}
}
/// Base name of the real D3DMetal d3d12 laid out beside the shim: a name of the same length as
/// "d3d12" so the export-name patch fits, and distinct enough to never match a DLL a game ships.
public static let shimRealName = "apd12"
public func wineVersion() throws -> String {
try Shell.capture(wineBinary.path, ["--version"], env: baseEnvironment()).trimmingCharacters(in: .whitespacesAndNewlines)
}
/// Environment every Wine process needs for this engine, before bottle/renderer settings.
public func baseEnvironment() -> [String: String] {
let fw = frameworksDir.path
// An arm64 engine's Wine opens its host libraries by leaf name (patch 0030 looks beside
// Wine only when that fails), and the GStreamer framework carries a stock libMoltenVK of
// its own: with the framework's lib on the fallback path alone, winevulkan got that copy
// instead of the engine's patched one, and DXVK refused the device (no Vulkan 1.3) on the
// first launch through the app (2026-10-15). The engine's lib goes first on this line.
var fallback = "\(fw):\(fw)/GStreamer.framework/Versions/1.0/lib"
if manifest.isNativeARM64 { fallback = engineDir.appending(path: "lib").path + ":" + fallback }
var env: [String: String] = [
"DYLD_FALLBACK_LIBRARY_PATH": fallback,
"DYLD_FALLBACK_FRAMEWORK_PATH": fw,
"GST_PLUGIN_PATH": "\(fw)/GStreamer.framework/Versions/1.0/lib/gstreamer-1.0",
]
for (k, v) in manifest.baseEnv ?? [:] {
env[k] = v.replacingOccurrences(of: "${frameworks}", with: fw)
.replacingOccurrences(of: "${renderers}", with: renderersDir.path)
}
return env
}
}