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
verify: automated compatibility harness (silent-Steam applaunch, Windows-path process detection, luminance-based black-screen check, anti-cheat skip guard, jsonl provenance) — scope-limited to installed games by policy
Gauthier Piarrette358c01a3ee4c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex d4791a3..d870a6a 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -11,5 +11,10 @@ Every recipe carries `lastVerified` so stale data is visible rather than silentlbundle. Match the style around you. By contributing you license your work under GPL-3.0 (code) orCC0 (data).+**Automated verification** (`highball verify`): tests only games *you already installed*, one at a+time, exactly as a player launching them would — via Steam's own documented `-applaunch` flag. It+never touches the store, never installs anything, and skips anti-cheat titles by default. Keep it+that way: batch auto-installing or store automation is out of scope by policy, not oversight.+**Engines**: manifest PRs bumping pinned SHA-256s, with a note on what you verified. Highball neverhosts binaries and never carries Wine patches — that's a design rule, not a preference.diff --git a/Sources/HighballKit/SteamLibrary.swift b/Sources/HighballKit/SteamLibrary.swiftindex 665a989..6e7f360 100644--- a/Sources/HighballKit/SteamLibrary.swift+++ b/Sources/HighballKit/SteamLibrary.swift@@ -60,6 +60,11 @@ public enum SteamLibrary {/// 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: Stringpublic var title: Stringpublic var steam_appid: Int?@@ -67,6 +72,7 @@ public struct GameDBEntry: Codable, Sendable {public var renderer: Renderer?public var provenance: String?public var notes: String?+ public var anticheat: AnticheatInfo?public var isBlocked: Bool { status == "blocked-anticheat" }}@@ -74,6 +80,11 @@ public struct GameDBEntry: Codable, Sendable {public struct GameDB: Sendable {public let byAppID: [Int: 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] = [:]for dir in directories {diff --git a/Sources/HighballKit/Verifier.swift b/Sources/HighballKit/Verifier.swiftnew file mode 100644index 0000000..7849a1c--- /dev/null+++ b/Sources/HighballKit/Verifier.swift@@ -0,0 +1,120 @@+import CoreGraphics+import Foundation+import ImageIO++/// Automated compatibility runs: launch a Steam game under a renderer, watch whether it+/// survives and actually draws something, and record a provenance-complete verdict.+public struct VerifyOutcome: Codable, Sendable {+ public enum Verdict: String, Codable, Sendable { case renders, blackScreen, crashed, neverStarted }+ public var appid: Int+ public var title: String+ public var renderer: Renderer+ public var verdict: Verdict+ public var secondsAlive: Int+ public var meanLuminance: Double+ public var date: String+ public var engine: String+ public var chip: String+ public var macos: String+ public var log: String+}++public struct Verifier {+ 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+ }++ /// Kills the bottle, launches `game` through a silent Steam under `renderer`, waits for the+ /// game process, samples the screen, and classifies the outcome.+ public func run(game: SteamGame, renderer: Renderer, runSeconds: Int = 90, log: (@Sendable (String) -> Void)? = nil) async throws -> VerifyOutcome {+ // Wine processes show Windows-style command lines (backslashes); cover both separators.+ let markers = ["steamapps/common/\(game.installdir)/", "steamapps\\common\\\(game.installdir)\\"]+ func gameAlive() -> Bool {+ guard let ps = try? Shell.capture("/bin/ps", ["axww"]) else { return false }+ return markers.contains { ps.contains($0) }+ }+ // Keep the display awake for the whole observation (screenshots of a sleeping display are black).+ let caffeinate = Process()+ caffeinate.executableURL = URL(fileURLWithPath: "/usr/bin/caffeinate")+ caffeinate.arguments = ["-diu", "-t", String(runSeconds + 420)]+ try? caffeinate.run()+ defer { caffeinate.terminate() }++ // Cold start so the renderer/sync environment actually applies.+ try? WineRunner(paths: paths, engine: engine, bottle: bottle).kill()+ try? await Task.sleep(for: .seconds(8))++ let runner = WineRunner(paths: paths, engine: engine, bottle: bottle)+ let steam = bottle.driveC.appending(path: "Program Files (x86)/Steam/steam.exe")+ log?("[\(game.name)] launching via silent Steam (\(renderer.rawValue))…")+ let launch = Task {+ try await runner.start(steam, arguments: ["-silent", "-applaunch", String(game.appid)], renderer: renderer)+ }++ // Wait up to 6 minutes for the game process (cold silent Steam needs ~2 min first).+ var waited = 0+ while !gameAlive() && waited < 360 { try await Task.sleep(for: .seconds(5)); waited += 5 }+ let started = gameAlive()+ var alive = 0+ var luminances: [Double] = []+ if started {+ log?("[\(game.name)] game process up after \(waited)s; observing \(runSeconds)s…")+ while alive < runSeconds && gameAlive() {+ try await Task.sleep(for: .seconds(10)); alive += 10+ if alive >= 30, let lum = Self.screenLuminance() { luminances.append(lum) }+ }+ }+ let survived = gameAlive()+ // Tear down.+ try? WineRunner(paths: paths, engine: engine, bottle: bottle).kill()+ launch.cancel()++ let meanLum = luminances.isEmpty ? 0 : luminances.reduce(0, +) / Double(luminances.count)+ let verdict: VerifyOutcome.Verdict =+ !started ? .neverStarted :+ (!survived && alive < runSeconds ? .crashed :+ (meanLum < 0.02 ? .blackScreen : .renders))++ let chip = (try? Shell.capture("/usr/sbin/sysctl", ["-n", "machdep.cpu.brand_string"]).trimmingCharacters(in: .whitespacesAndNewlines)) ?? "unknown"+ let macos = (try? Shell.capture("/usr/bin/sw_vers", ["-productVersion"]).trimmingCharacters(in: .whitespacesAndNewlines)) ?? "unknown"+ let outcome = VerifyOutcome(appid: game.appid, title: game.name, renderer: renderer, verdict: verdict,+ secondsAlive: alive, meanLuminance: (meanLum * 1000).rounded() / 1000,+ date: ISO8601DateFormatter().string(from: Date()),+ engine: engine.id, chip: chip, macos: macos, log: "")+ try append(outcome)+ log?("[\(game.name)] \(renderer.rawValue): \(verdict.rawValue) (alive \(alive)s, luminance \(outcome.meanLuminance))")+ return outcome+ }++ func append(_ o: VerifyOutcome) throws {+ try paths.ensure()+ let file = paths.logs.appending(path: "verify-results.jsonl")+ let line = String(decoding: try JSONEncoder().encode(o), as: UTF8.self) + "\n"+ if let handle = try? FileHandle(forWritingTo: file) { handle.seekToEndOfFile(); handle.write(Data(line.utf8)); try? handle.close() }+ else { try line.write(to: file, atomically: true, encoding: .utf8) }+ }++ /// Mean luminance of the main display, 0…1. Requires Screen Recording permission and an awake display.+ public static func screenLuminance() -> Double? {+ let tmp = FileManager.default.temporaryDirectory.appending(path: "hb-verify-\(UUID().uuidString).png")+ defer { try? FileManager.default.removeItem(at: tmp) }+ guard (try? Shell.run("/usr/sbin/screencapture", ["-x", "-t", "png", tmp.path])) != nil,+ let src = CGImageSourceCreateWithURL(tmp as CFURL, nil),+ let img = CGImageSourceCreateThumbnailAtIndex(src, 0, [+ kCGImageSourceCreateThumbnailFromImageAlways: true,+ kCGImageSourceThumbnailMaxPixelSize: 64] as CFDictionary) else { return nil }+ guard let data = img.dataProvider?.data as Data? else { return nil }+ let bpp = img.bitsPerPixel / 8+ guard bpp >= 3, data.count >= bpp else { return nil }+ var total = 0.0; var count = 0+ for i in stride(from: 0, to: data.count - bpp, by: bpp) {+ total += (Double(data[i]) + Double(data[i + 1]) + Double(data[i + 2])) / (3 * 255)+ count += 1+ }+ return count > 0 ? total / Double(count) : nil+ }+}diff --git a/Sources/highball/main.swift b/Sources/highball/main.swiftindex a5ba656..7d68309 100644--- a/Sources/highball/main.swift+++ b/Sources/highball/main.swift@@ -7,7 +7,7 @@ struct Highball: AsyncParsableCommand {static let configuration = CommandConfiguration(commandName: "highball",abstract: "Highball — run Windows games on Apple Silicon. Free, open, engine-agnostic.",- subcommands: [Engine.self, Bottle.self, Run.self, Recipe.self, Tricks.self, Env.self, Report.self],+ subcommands: [Engine.self, Bottle.self, Run.self, Recipe.self, Tricks.self, Env.self, Report.self, Verify.self],defaultSubcommand: nil)}@@ -238,6 +238,52 @@ struct Tricks: AsyncParsableCommand {}}+// MARK: - highball verify++struct Verify: AsyncParsableCommand {+ static let configuration = CommandConfiguration(abstract: "Automated compatibility runs: launch installed Steam games under one or more renderers, detect crashes and black screens, and record provenance-complete verdicts. Keep the display awake.")+ @Argument var bottle: String+ @Option(parsing: .upToNextOption, help: "Steam appids to test (default: every installed, ready game).") var games: [Int] = []+ @Option(parsing: .upToNextOption, help: "Renderers to test (default: dxvk dxmt d3dmetal if available).") var renderers: [HighballKit.Renderer] = []+ @Option(help: "Observation seconds per run.") var seconds: Int = 90+ @Flag(help: "Also test titles with known anti-cheat (skipped by default: automated runs of AC games are needless account risk).") var includeAnticheat = false++ func run() async throws {+ let b = try BottleStore().get(bottle)+ let eng = try EngineStore().engine(b.settings.engineID)+ var library = SteamLibrary.games(in: b).filter(\.isReady)+ if !games.isEmpty { library = library.filter { games.contains($0.appid) } }+ if !includeAnticheat {+ // Compliance guard: never auto-run titles with anti-cheat. Verifying those is a+ // deliberate human decision (--include-anticheat), not something a batch does.+ let db = GameDB(directories: GameDB.defaultDirectories())+ let skipped = library.filter { db[$0.appid]?.anticheat != nil || db[$0.appid]?.isBlocked == true }+ if !skipped.isEmpty { print("skipping (anti-cheat): " + skipped.map(\.name).joined(separator: ", ")) }+ library.removeAll { db[$0.appid]?.anticheat != nil || db[$0.appid]?.isBlocked == true }+ }+ if library.isEmpty { fail("no installed games matched") }+ var rs = renderers+ if rs.isEmpty {+ rs = [.dxvk, .dxmt]+ if eng.rendererDir("d3dmetal") != nil { rs.append(.d3dmetal) }+ }+ print("verifying \(library.count) game(s) × \(rs.map(\.rawValue).joined(separator: ",")) — \(seconds)s each; display must stay awake")+ let verifier = Verifier(engine: eng, bottle: b)+ var results: [VerifyOutcome] = []+ for game in library {+ for r in rs {+ do {+ let o = try await verifier.run(game: game, renderer: r, runSeconds: seconds) { print($0) }+ results.append(o)+ } catch { print("[\(game.name)] \(r.rawValue): error \(error)") }+ }+ }+ print("\n=== results (also in logs/verify-results.jsonl) ===")+ for o in results { print([o.title, o.renderer.rawValue, o.verdict.rawValue, "\(o.secondsAlive)s"].joined(separator: " ")) }+ print("\nSubmit interesting rows with: highball report \(bottle) \"<title>\" --rating N --notes \"…\"")+ }+}+// MARK: - highball reportstruct Report: AsyncParsableCommand {