Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

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.md
index d4791a3..d870a6a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,5 +11,10 @@ Every recipe carries `lastVerified` so stale data is visible rather than silentl
bundle. Match the style around you. By contributing you license your work under GPL-3.0 (code) or
CC0 (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 never
hosts 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.swift
index 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: String
public var title: String
public 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.swift
new file mode 100644
index 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.swift
index 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 report
struct Report: AsyncParsableCommand {