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
/// A game installed by the Windows Steam client inside a bottle, read from
/// `steamapps/appmanifest_<appid>.acf`.
public struct SteamGame: Identifiable, Sendable, Hashable {
public let appid: Int
public let name: String
public let installdir: String
public let sizeOnDisk: Int64
public let stateFlags: Int
/// Steam's own LastPlayed from the ACF (unix seconds; 0 = never). Seeds the library's
/// Continue shelf so it works on first run and tracks plays Steam started without us.
public let lastPlayed: Date?
/// The Steam library folder the game is installed in, the directory holding `steamapps`.
/// Steam keeps more than one, the second often on an external disk, so the install path
/// cannot be derived from the bottle alone. nil for a game built without one.
public let libraryRoot: URL?
/// The Steam client that installed the game, as the ACF's LauncherPath records it: a Windows
/// path for Steam in an environment (`C:\\Program Files (x86)\\Steam\\steam.exe`), a Mac
/// path for Steam for Mac. nil when the manifest has none.
public let launcherPath: String?
/// The 64-bit Steam ID of the account that installed the game (or updated it last), as the
/// ACF's LastOwner records it; nil when it has none. Who installed it, not who owns it: two
/// accounts on one Steam may both own a game (SteamAccounts).
public let lastOwner: UInt64?
public init(appid: Int, name: String, installdir: String, sizeOnDisk: Int64, stateFlags: Int, lastPlayed: Date?,
libraryRoot: URL? = nil, launcherPath: String? = nil, lastOwner: UInt64? = nil) {
self.appid = appid; self.name = name; self.installdir = installdir; self.sizeOnDisk = sizeOnDisk
self.stateFlags = stateFlags; self.lastPlayed = lastPlayed; self.libraryRoot = libraryRoot
self.launcherPath = launcherPath; self.lastOwner = lastOwner
}
/// Installed by a Windows Steam, the one in an environment. A library folder both clients use
/// (an external drive, say) shows Steam for Mac the Windows client's manifests too, and a
/// Windows-only game then read as installed in Steam for Mac and played there: Forza Horizon 6
/// got "Play on Mac" and never its own fix (Discord, 2026-10-09).
public var installedByWindowsSteam: Bool {
guard let path = launcherPath else { return false }
return path.lowercased().hasSuffix(".exe") || path.range(of: #"^[A-Za-z]:\\"#, options: .regularExpression) != nil
}
public var id: Int { appid }
/// Where the game's files are, when the library folder is known.
public var installFolder: URL? {
guard let libraryRoot, !installdir.isEmpty else { return nil }
return libraryRoot.appending(path: "steamapps/common/\(installdir)", directoryHint: .isDirectory)
}
/// StateFlags 4 = fully installed; anything else is updating/downloading/broken.
public var isReady: Bool { stateFlags == 4 }
/// Every file of the installed build is in its folder: fully installed, at most with an update waiting (StateFlags
/// 6, update required). Steam stages an update's files elsewhere until it applies them, so such a folder is whole,
/// and a Steam that finds its record updates it as it would any copy. Anything else (downloading, updating, paused,
/// files missing) is not.
public var isFullyInstalled: Bool { stateFlags & 4 != 0 && stateFlags & ~6 == 0 }
/// Steam CDN artwork (no key needed).
public var headerImage: URL { URL(string: "https://cdn.akamai.steamstatic.com/steam/apps/\(appid)/header.jpg")! }
public var capsuleImage: URL { URL(string: "https://cdn.akamai.steamstatic.com/steam/apps/\(appid)/library_600x900.jpg")! }
}
public enum SteamLibrary {
/// Path of the Windows Steam install inside a bottle, if present.
public static func steamRoot(of bottle: Bottle) -> URL? {
steamRoot(driveC: bottle.driveC)
}
/// Path of the Windows Steam install under a `drive_c` we only have the path of.
static func steamRoot(driveC: URL) -> URL? {
let root = driveC.appending(path: "Program Files (x86)/Steam")
return FileManager.default.fileExists(atPath: root.appending(path: "steam.exe").path) ? root : nil
}
/// All games known to the bottle's Steam library folders: the one inside the environment and
/// every folder Steam's library list adds to it.
public static func games(in bottle: Bottle) -> [SteamGame] {
guard let root = steamRoot(of: bottle) else { return [] }
return games(steamRoot: root, bottleURL: bottle.url)
}
static func games(steamRoot root: URL, bottleURL: URL) -> [SteamGame] {
var seen = Set<Int>(), games: [SteamGame] = []
for library in libraryFolders(steamRoot: root, bottleURL: bottleURL) {
// Resolved first: players move steamapps to an external disk and leave a symlink in its
// place, and FileManager's URL listing refuses a symlink ("Not a directory"), so the
// whole library read as empty (highball-db#316, steamapps on /Volumes/MEDIA_DEV).
let steamapps = library.appending(path: "steamapps").resolvingSymlinksInPath()
guard let entries = try? FileManager.default.contentsOfDirectory(at: steamapps, includingPropertiesForKeys: nil) else { continue }
for url in entries where url.lastPathComponent.hasPrefix("appmanifest_") && url.pathExtension == "acf" {
guard let game = parseManifest(url, libraryRoot: library),
game.appid != 228980, // Steamworks Common Redistributables, not a game
seen.insert(game.appid).inserted else { continue } // the environment's own copy wins
games.append(game)
}
}
return games.sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
}
/// The Steam library folders of a bottle: the one inside the environment first, then the
/// ones Steam's `libraryfolders.vdf` names, in Steam's order. Steam writes those as Windows
/// paths (`D:\SteamLibrary`), which the bottle's drive letters turn back into Mac paths; a
/// letter the bottle does not map, or a folder that is not there (an external disk left at
/// home), is skipped. Before this a game installed in a second library folder never reached
/// the library at all (highball-db#316, a Steam library on /Volumes/MEDIA_DEV). Steam keeps the
/// list in `config` too, the only copy left where `steamapps` itself can't be read, such as a
/// Finder alias left in its place (highball#603).
static func libraryFolders(steamRoot root: URL, bottleURL: URL) -> [URL] {
var folders = [root.standardizedFileURL]
let lists = ["steamapps/libraryfolders.vdf", "config/libraryfolders.vdf"]
.compactMap { try? String(contentsOf: root.appending(path: $0), encoding: .utf8) }
for path in lists.flatMap(libraryPaths(in:)) {
guard let url = unixURL(windowsPath: path, bottleURL: bottleURL)?.standardizedFileURL,
!folders.contains(url),
FileManager.default.fileExists(atPath: url.appending(path: "steamapps").path) else { continue }
folders.append(url)
}
return folders
}
/// The `steamapps` folder of each library folder, the environment's own first, symlinks
/// resolved: where Steam writes its install records. The library's watcher covers all of
/// them, since an install into a second library folder (an external drive) used to reach
/// the game's page only with the next full refresh (highball#286).
public static func steamappsDirectories(of bottle: Bottle) -> [URL] {
guard let root = steamRoot(of: bottle) else { return [] }
return steamappsDirectories(steamRoot: root, bottleURL: bottle.url)
}
static func steamappsDirectories(steamRoot root: URL, bottleURL: URL) -> [URL] {
libraryFolders(steamRoot: root, bottleURL: bottleURL).map { $0.appending(path: "steamapps").resolvingSymlinksInPath() }
}
/// A cheap fingerprint of the install records: each appmanifest's path and modification date
/// across the library folders. Steam writes a record as an install starts, advances and
/// finishes, so the Steam client watch compares this every few seconds and catches what the
/// directory watcher cannot hear, such as a library folder added while the app runs or a
/// steamapps Steam recreated under a watch. In highball#286 an Age of Empires II HD install
/// finished in Steam while its page kept offering Install.
public static func installSignature(of bottle: Bottle) -> String {
guard let root = steamRoot(of: bottle) else { return "" }
return installSignature(steamRoot: root, bottleURL: bottle.url)
}
static func installSignature(steamRoot root: URL, bottleURL: URL) -> String {
var records: [String] = []
for steamapps in steamappsDirectories(steamRoot: root, bottleURL: bottleURL) {
let entries = (try? FileManager.default.contentsOfDirectory(at: steamapps, includingPropertiesForKeys: [.contentModificationDateKey])) ?? []
for url in entries where url.lastPathComponent.hasPrefix("appmanifest_") && url.pathExtension == "acf" {
let date = (try? url.resourceValues(forKeys: [.contentModificationDateKey]))?.contentModificationDate
records.append("\(url.path) \(date?.timeIntervalSince1970 ?? 0)")
}
}
return records.sorted().joined(separator: "\n")
}
/// The `"path"` values of a libraryfolders.vdf, their doubled backslashes made single.
static func libraryPaths(in text: String) -> [String] {
text.matches(of: #/"path"\s+"([^"]*)"/#).map { String($0.1).replacingOccurrences(of: "\\\\", with: "\\") }
}
/// A Windows path through the bottle's drive letters: `dosdevices/d:` is a symlink to the Mac
/// folder the letter stands for (`c:` to `../drive_c`, `z:` to `/`), so the path's components
/// go on the end of that. nil for a letter the bottle does not map.
static func unixURL(windowsPath: String, bottleURL: URL) -> URL? {
let parts = windowsPath.split(separator: "\\", omittingEmptySubsequences: true).map(String.init)
guard let drive = parts.first, drive.count == 2, drive.hasSuffix(":"), let letter = drive.first?.lowercased() else { return nil }
let dosdevices = bottleURL.appending(path: "dosdevices", directoryHint: .isDirectory)
var base: URL
if let dest = try? FileManager.default.destinationOfSymbolicLink(atPath: dosdevices.appending(path: "\(letter):").path) {
base = dest.hasPrefix("/") ? URL(fileURLWithPath: dest, isDirectory: true) : dosdevices.appending(path: dest, directoryHint: .isDirectory)
} else if letter == "c" {
base = bottleURL.appending(path: "drive_c", directoryHint: .isDirectory)
} else if letter == "z" {
base = URL(fileURLWithPath: "/", isDirectory: true)
} else {
return nil
}
for part in parts.dropFirst() { base = base.appending(path: part, directoryHint: .isDirectory) }
return base
}
/// Minimal ACF (Valve KeyValues) reader: flat `"key" "value"` pairs are all we need.
static func parseManifest(_ url: URL, libraryRoot: URL? = nil) -> SteamGame? {
guard let text = try? String(contentsOf: url, encoding: .utf8) else { return nil }
var fields: [String: String] = [:]
let pattern = #/"([A-Za-z]+)"\s+"([^"]*)"/#
for match in text.matches(of: pattern) where fields[String(match.1)] == nil {
fields[String(match.1)] = String(match.2)
}
guard let appidText = fields["appid"], let appid = Int(appidText), let name = fields["name"] else { return nil }
let played = TimeInterval(fields["LastPlayed"] ?? "") ?? 0
return SteamGame(
appid: appid,
name: name,
installdir: fields["installdir"] ?? "",
sizeOnDisk: Int64(fields["SizeOnDisk"] ?? "") ?? 0,
stateFlags: Int(fields["StateFlags"] ?? "") ?? 0,
lastPlayed: played > 0 ? Date(timeIntervalSince1970: played) : nil,
libraryRoot: libraryRoot,
launcherPath: fields["LauncherPath"],
lastOwner: UInt64(fields["LastOwner"] ?? "").flatMap { $0 == 0 ? nil : $0 }
)
}
}
// MARK: - Compatibility database (db/games entries from highball-db)
/// One entry of the open compatibility database, as published in highball-db `db/games/*.json`.
public struct GameDBEntry: Codable, Sendable {
public struct AnticheatInfo: Codable, Sendable {
public var names: [String]
public var macVerdict: String?
public var note: String?
}
public var id: String
public var title: String
public var steam_appid: Int?
/// Legendary's app name for the Epic copy (#63: an Epic copy of a row's game matched nothing,
/// so Play never asked for D3DMetal and DXMT refused the DirectX 12 game).
public var epic_app_name: String?
public var status: String // verified-local | reported-upstream | community | blocked-anticheat | blocked-publisher
public var renderer: Renderer?
/// The game draws with Vulkan directly (The Sims Legacy Collection): every graphics mode is a
/// Direct3D layer, so none applies, and the page must say so instead of offering a choice (#44).
public var nativeVulkan: Bool?
public var provenance: String?
public var notes: String?
public var anticheat: AnticheatInfo?
/// The date of the last local verification, "YYYY-MM-DD".
public var lastVerified: String?
/// Extra arguments appended to the game's launch (Steam forwards -applaunch trailing args
/// to the game). Data, not code: game-specific knowledge stays in the db (issue #21's
/// windowed workaround for legacy CS:GO's macOS 26 fullscreen freeze is the first user).
public var launchArgs: [String]?
/// Apply launchArgs only at or above this macOS version ("26.0"). A workaround for one OS
/// must not change behaviour for users where the game already works (14.x fullscreen is
/// fine); nil means the args apply everywhere.
public var launchArgsMinMacOS: String?
/// `renderer` applies at or above this macOS version ("15.0"); below it `rendererBelow`
/// applies instead (nil there means the bottle's own setting). DXMT wants macOS 15 or newer
/// and paints nothing on 14, so a verdict taken on a newer OS must not send an older Mac to
/// a black screen. Data, not code: the row decides.
public var rendererMinMacOS: String?
public var rendererBelow: Renderer?
/// The machine and build the verdict was taken on, for the game page's sentence: "Verified
/// on an M1 Pro. About 70 frames per second on macOS 26.6.2". Free-text `provenance` stays
/// for the site; this is the structured part the app can compare with the reader's Mac.
public struct VerifiedOn: Codable, Sendable, Equatable {
public var chip: String? // "Apple M1 Pro"
public var macos: String? // "26.6.2"
public var engine: String? // engine id
public var fps: String? // "about 70", "60 to 82"; words, never a computed number
public init(chip: String? = nil, macos: String? = nil, engine: String? = nil, fps: String? = nil) {
self.chip = chip; self.macos = macos; self.engine = engine; self.fps = fps
}
}
public var verified: VerifiedOn?
/// Per-renderer outcomes ("works", "fails", ...) with a detail sentence, the data nobody
/// else publishes; the game page shows them under "Why these settings?".
public struct RendererResult: Codable, Sendable, Equatable {
public var verdict: String
public var detail: String?
}
public var rendererResults: [String: RendererResult]?
/// A native macOS edition. Highball marks the ones on Steam (the same purchase); `available:
/// false` marks a Mac port that no longer runs, which outranks the store's flag (MacSteamBuild).
public var nativeMac: NativeMacInfo?
/// A sentence the activity strip shows under the running game while it starts, for a game
/// whose own loading is long enough that a player would think it failed: Microsoft Flight
/// Simulator 2024 on the arm64 engine prepares its shaders for 6 to 7 minutes behind a still
/// window, after its process has appeared and Highball's start sheet has closed. Shown for
/// `startNoticeMinutes` after that, 15 when the row does not say. Data, not code.
public var startNotice: String?
public var startNoticeMinutes: Int?
/// Any kind of block: kernel anti-cheat, or a publisher that stops the game on macOS on purpose
/// (World of Warships). The game cannot run, so no renderer advice and no Play.
public var isBlocked: Bool { status.hasPrefix("blocked-") }
/// The renderer the row recommends on the given OS version, nil for "the bottle's own".
public func effectiveRenderer(osMajor: Int = ProcessInfo.processInfo.operatingSystemVersion.majorVersion) -> Renderer? {
guard let gate = rendererMinMacOS, let want = Int(gate.split(separator: ".").first ?? "") else { return renderer }
return osMajor >= want ? renderer : rendererBelow
}
/// The launch args that apply on the given OS version. Pure for testability.
public func effectiveLaunchArgs(osMajor: Int = ProcessInfo.processInfo.operatingSystemVersion.majorVersion) -> [String] {
guard let args = launchArgs else { return [] }
if let gate = launchArgsMinMacOS, let want = Int(gate.split(separator: ".").first ?? "") {
guard osMajor >= want else { return [] }
}
return args
}
}
public struct GameDB: Sendable {
public let byAppID: [Int: GameDBEntry]
/// Rows by Legendary app name, for Epic copies.
public let byEpicAppName: [String: GameDBEntry]
/// Rows by normalized title, the fallback for a copy from a store the row does not name.
public let byTitle: [String: GameDBEntry]
/// Rows by title with the spaces removed too: a program added from its executable is named
/// after the file, "HogwartsLegacy", not "Hogwarts Legacy" (highball-db#48).
public let byCompactTitle: [String: GameDBEntry]
/// Default lookup locations for a CLI/dev context: a sibling highball-db checkout, or ./db/games.
public static func defaultDirectories() -> [URL] {
["../highball-db/db/games", "db/games"].map { URL(fileURLWithPath: $0) }
}
public init(directories: [URL]) {
var index: [Int: GameDBEntry] = [:], epic: [String: GameDBEntry] = [:], titles: [String: GameDBEntry] = [:]
for dir in directories {
guard let files = try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil) else { continue }
for file in files where file.pathExtension == "json" {
guard let data = try? Data(contentsOf: file),
let entry = try? JSONDecoder().decode(GameDBEntry.self, from: data) else { continue }
if let appid = entry.steam_appid { index[appid] = entry }
if let name = entry.epic_app_name { epic[name] = entry }
let key = Self.normalizedTitle(entry.title)
if !key.isEmpty, titles[key] == nil { titles[key] = entry }
}
}
byAppID = index; byEpicAppName = epic; byTitle = titles
var compact: [String: GameDBEntry] = [:]
for (key, entry) in titles { let c = key.replacingOccurrences(of: " ", with: ""); if compact[c] == nil { compact[c] = entry } }
byCompactTitle = compact
}
public subscript(appid: Int) -> GameDBEntry? { byAppID[appid] }
/// Lowercased letters, digits and single spaces, apostrophes dropped: "Marvel's Guardians of
/// the Galaxy™" and "Marvels Guardians Of The Galaxy" are the same title. Exact after that,
/// never fuzzy.
public static func normalizedTitle(_ title: String) -> String {
let apostrophes: Set<Unicode.Scalar> = ["'", "\u{2019}", "\u{2018}"]
let kept = title.lowercased().unicodeScalars.compactMap { scalar -> Character? in
if apostrophes.contains(scalar) { return nil }
return CharacterSet.alphanumerics.contains(scalar) ? Character(scalar) : " "
}
return String(kept).split(separator: " ").joined(separator: " ")
}
/// The row for a library item, whatever store it came from: the Steam id first (for a GOG copy,
/// the Steam id GOG's database gives it), then the Epic app name, then the normalized title. Nil for a program the database does not know.
public func entry(for item: LibraryItem) -> GameDBEntry? {
if let appid = item.steamAppID ?? item.gogSteamAppID, let e = byAppID[appid] { return e }
if let name = item.epicAppName, let e = byEpicAppName[name] { return e }
let normalized = Self.normalizedTitle(item.title)
if let e = byTitle[normalized] { return e }
return byCompactTitle[normalized.replacingOccurrences(of: " ", with: "")]
}
}