Skip to content

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

Guided renderer trial, per-game graphics modes, same-Wine engine auto-update, the native-Vulkan flag (#66, #67, #44, ux-plan 1 and 9)

Gauthier Piarrettea36cfac3e617
diff --git a/Scripts/game-smoke.sh b/Scripts/game-smoke.sh
index 129aff1..fbc1e8f 100755
--- a/Scripts/game-smoke.sh
+++ b/Scripts/game-smoke.sh
@@ -34,6 +34,7 @@ GAMES=(
"244210|d3dmetal|Assetto|assetto|"
"230410|dxmt|Warframe|warframe|"
"3314060|dxvk|Sims|sims|"
+ "319510|dxvk|Five Nights|fnaf|"
)
only=("$@")
results=(); passed=true
@@ -53,7 +54,9 @@ for row in "${GAMES[@]}"; do
# Capture three frames ten seconds apart. Prefer the per-window grab, but some games use a
# layer-hosted (Metal) window that screencapture -l cannot image (it returns nothing/black);
# fall back to a full-screen shot cropped to the window rect, which works for any window type.
- geo=$("$WINLIST" 2>/dev/null | grep -E "id=$id|^$id" | head -1); geo=$("$WINLIST" 2>/dev/null | awk -v id="$id" '$1==id{print $5}')
+ # Geometry sits in the two fields before "layer=", never at a fixed index: a title with
+ # spaces ("Five Nights at Freddy's") shifts the columns and broke the parse on 2026-09-08.
+ geo=$("$WINLIST" 2>/dev/null | awk -v id="$id" '$1==id{print $(NF-3), $(NF-2)}')
gx=${geo%%,*}; rest=${geo#*,}; gy=${rest%% *}; wh=${geo##* }; gw=${wh%%x*}; gh=${wh##*x}
grab(){ local out="$1"; screencapture -x -l "$id" "$out" 2>/dev/null
# if the -l grab is missing or ~uniformly black, use full-screen + crop
diff --git a/Scripts/release.sh b/Scripts/release.sh
index adcd1b4..c14d4f8 100755
--- a/Scripts/release.sh
+++ b/Scripts/release.sh
@@ -15,6 +15,22 @@ case "${1:-}" in
--promote)
PV="${2:?usage: release.sh --promote <version>}"
git diff-index --quiet HEAD -- || { echo "tracked files modified; commit before promoting" >&2; exit 1; }
+ # Cadence (2026-09-08): a stable rollout takes seven days, so promoting again inside that window
+ # restarts the clock for everyone and makes beta testers chase daily builds. Betas ship as often
+ # as needed; a promotion waits for the previous one to finish unless HB_CADENCE_OK=1 says the
+ # new build fixes something stable users are hitting now.
+ python3 - <<'PY' || { echo "set HB_CADENCE_OK=1 to promote anyway" >&2; exit 1; }
+import os, re, sys, time
+from email.utils import parsedate_to_datetime
+s = open('appcast.xml').read()
+last = None
+for item in re.findall(r'<item>.*?</item>', s, re.S):
+ if 'phasedRolloutInterval' in item:
+ m = re.search(r'<pubDate>(.*?)</pubDate>', item)
+ if m: last = max(last or 0, parsedate_to_datetime(m.group(1)).timestamp())
+if last and time.time() - last < 7 * 86400 and os.environ.get('HB_CADENCE_OK') != '1':
+ print(f"release cadence: the previous stable promotion was {(time.time() - last) / 86400:.1f} days ago and its seven-day rollout is still running.", file=sys.stderr); sys.exit(1)
+PY
HB_VERSION="$PV" HB_DATE="$(date -R 2>/dev/null || date "+%a, %d %b %Y %H:%M:%S %z")" python3 - <<'PY'
import os, re, xml.dom.minidom
v = os.environ['HB_VERSION']
diff --git a/Sources/HighballApp/ActivityStrip.swift b/Sources/HighballApp/ActivityStrip.swift
index 074c6d0..754b3ba 100644
--- a/Sources/HighballApp/ActivityStrip.swift
+++ b/Sources/HighballApp/ActivityStrip.swift
@@ -127,15 +127,9 @@ struct ActivityStrip: View {
Text(String(format: L("%d min"), record.seconds / 60)).font(.caption.monospacedDigit()).foregroundStyle(.secondary)
Spacer(minLength: 12)
Button(L("It played fine")) { state.reportPlay(record) }.controlSize(.small)
- Button(L("Had problems")) {
- state.postPlay = nil
- let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
- // The report samples live games for a few seconds; never on the main thread.
- Task.detached {
- let url = BugReport.url(version: version)
- await MainActor.run { NSWorkspace.shared.open(url) }
- }
- }.controlSize(.small)
+ // A bad session first gets the one thing that most often fixes it, another mode for this
+ // game, and the report from inside that ask (guided renderer trial, ux-plan item 1).
+ Button(L("Had problems")) { state.offerRendererTrial(for: record) }.controlSize(.small)
Button(L("Not now")) { state.postPlay = nil }.controlSize(.small).buttonStyle(.link)
}
.padding(.horizontal, 14).padding(.vertical, 8)
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 3198e2d..d7dc869 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -99,6 +99,66 @@ final class AppState {
var seconds: Int
/// Another installed engine to offer as the second way out, when there is one.
var alternateEngine: InstalledEngine? = nil
+ /// The library item this launch belongs to, when it is a game: accepting then changes the
+ /// mode for that game alone, never the whole environment.
+ var itemID: String? = nil
+ }
+
+ /// A game that ran, badly by the player's account, with another mode to try next time (the
+ /// guided renderer trial, ux-plan item 1). One click sets it for this game only.
+ struct RendererTrial {
+ let itemID: String
+ let title: String
+ let current: Renderer
+ let next: Renderer
+ }
+ var rendererTrial: RendererTrial?
+
+ /// Graphics modes chosen per game (library id), the store's copy for the views.
+ var libraryOverrides: [String: Renderer] = [:]
+ func rendererOverride(for item: LibraryItem) -> Renderer? { libraryOverrides[item.id] }
+ func setRendererOverride(_ renderer: Renderer?, for id: String) {
+ libraryStore.setRendererOverride(renderer, for: id)
+ libraryOverrides = libraryStore.rendererOverrides()
+ appendLog(renderer.map { "\(id): graphics mode set to \($0.rawValue) for this game" } ?? "\(id): graphics mode back to the environment's")
+ }
+
+ /// "Had problems" on the post-play row: offer the next mode for this game, then the report.
+ func offerRendererTrial(for record: SessionRecord) {
+ postPlay = nil
+ guard let bottle = bottles.first(where: { $0.name == record.bottle }), let engine = engine(for: bottle),
+ let item = libraryItems.first(where: { $0.steamAppID != nil && $0.steamAppID == record.appid })
+ ?? libraryItems.first(where: { $0.title == record.title && $0.bottleName == record.bottle }) else { return }
+ let current = record.renderer.flatMap(Renderer.init(rawValue:)) ?? rendererOverride(for: item) ?? bottle.settings.renderer
+ let next = Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil,
+ vkd3dAvailable: engine.rendererDir("vkd3d") != nil)
+ rendererTrial = RendererTrial(itemID: item.id, title: item.title, current: current, next: next)
+ }
+ func acceptRendererTrial() {
+ guard let trial = rendererTrial else { return }
+ setRendererOverride(trial.next, for: trial.itemID)
+ rendererTrial = nil
+ }
+
+ /// A component-only engine update (same Wine) applies itself, once per launch, when nothing
+ /// runs in any environment: the move kills a bottle's Wine processes, so a running game or
+ /// Steam client makes it wait for the next launch (EngineStore.autoUpdateAllowed).
+ private var autoUpdateTried = false
+ func maybeAutoUpdateEngine() {
+ guard !autoUpdateTried, !busy, !needsOnboarding, runningSessions.isEmpty,
+ let update = engineUpdate, let current = defaultEngine,
+ EngineStore.autoUpdateAllowed(from: current.manifest, to: update) else { return }
+ autoUpdateTried = true
+ let prefixes = bottles.map(\.url)
+ Task { [weak self] in
+ let steamUp = await Task.detached { prefixes.contains { WineRunner.steamIsRunning(inPrefix: $0) } }.value
+ await MainActor.run {
+ guard let self else { return }
+ if steamUp { self.appendLog("engine \(update.id) is ready; it applies itself once Steam is closed"); self.autoUpdateTried = false; return }
+ self.appendLog("engine \(update.id) is the same Wine as \(current.id): applying it now, no click needed")
+ self.updateEngine()
+ }
+ }
}
/// The engine the crash alert offers next to the renderer suggestion, if another one is installed.
@@ -172,9 +232,11 @@ final class AppState {
// the engine simply lacks degrades to one it has, and the log says so.
var renderer = renderer
if let engine = engine(for: bottle) {
- let rowMode = bottle.settings.rendererExplicit ? nil : gameDB.entry(for: item)?.effectiveRenderer()
+ let entry = gameDB.entry(for: item)
let pinMode = item.pinID.flatMap { id in bottle.settings.pins.first { $0.id == id }?.renderer }
- let wanted = renderer ?? rowMode ?? pinMode ?? bottle.settings.renderer
+ let wanted = Renderer.choose(requested: renderer, gameOverride: rendererOverride(for: item), row: entry?.effectiveRenderer(),
+ environmentExplicit: bottle.settings.rendererExplicit, pin: pinMode,
+ environment: bottle.settings.renderer, nativeVulkan: entry?.nativeVulkan == true)
switch wanted.availability(in: engine) {
case .available:
break
@@ -364,8 +426,10 @@ final class AppState {
installWatcher?.watch(bottles.flatMap(installDirectories))
startSteamClientWatch()
libraryPlays = libraryStore.load()
+ libraryOverrides = libraryStore.rendererOverrides()
rebuildLibrary()
epicRefresh()
+ maybeAutoUpdateEngine()
if gameDB.byAppID.isEmpty {
var dirs: [URL] = []
if let res = Bundle.main.resourceURL { dirs.append(res.appending(path: "db-games")) }
@@ -1257,7 +1321,7 @@ final class AppState {
self.crashSuggestion = CrashSuggestion(program: game.name, bottleName: bottle.name,
renderer: Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil, vkd3dAvailable: engine.rendererDir("vkd3d") != nil),
logPath: result.log.path, current: current, seconds: Int(result.duration),
- alternateEngine: self.alternateEngine(for: bottle))
+ alternateEngine: self.alternateEngine(for: bottle), itemID: "steam:\(game.appid)")
}
guard handedOff else { return }
beginSession(GameSession(title: game.name, bottleName: bottle.name, appid: game.appid, markers: markers,
diff --git a/Sources/HighballApp/GameDetailView.swift b/Sources/HighballApp/GameDetailView.swift
index 568735b..cd7c640 100644
--- a/Sources/HighballApp/GameDetailView.swift
+++ b/Sources/HighballApp/GameDetailView.swift
@@ -27,7 +27,7 @@ struct GameDetailView: View {
private var verdict: GamePageCopy.Verdict { GamePageCopy.verdict(entry, myChip: state.machineChip) }
private var willDo: [GamePageCopy.WillDo] {
GamePageCopy.willDo(entry, recipe: fixRecipe, applied: fixApplied, bottleRenderer: bottle?.settings.renderer ?? .dxvk,
- explicit: bottle?.settings.rendererExplicit ?? false)
+ explicit: bottle?.settings.rendererExplicit ?? false, gameOverride: state.rendererOverride(for: item))
}
private var engineName: String? { bottle.flatMap { state.engine(for: $0) }?.displayName }
@@ -200,9 +200,26 @@ struct GameDetailView: View {
DisclosureGroup(isExpanded: $showAdvanced) {
VStack(alignment: .leading, spacing: 10) {
if let bottle {
- HStack(alignment: .top, spacing: 12) {
- Text(L("Graphics mode")).font(.caption).foregroundStyle(.secondary).frame(width: 110, alignment: .leading).padding(.top, 4)
- GraphicsModePicker(bottle: bottle)
+ if entry?.nativeVulkan == true {
+ row(L("Graphics mode"), L("Does not apply: this game draws with Vulkan directly, not through any Direct3D layer."))
+ } else {
+ if let engine = state.engine(for: bottle) {
+ HStack(alignment: .top, spacing: 12) {
+ Text(L("Mode for this game")).font(.caption).foregroundStyle(.secondary).frame(width: 110, alignment: .leading).padding(.top, 4)
+ Picker("", selection: Binding(
+ get: { state.rendererOverride(for: item)?.rawValue ?? "" },
+ set: { state.setRendererOverride(Renderer(rawValue: $0), for: item.id) })) {
+ Text(L("Environment's mode")).tag("")
+ ForEach(Renderer.allCases.filter { $0.availability(in: engine) == .available }, id: \.self) { r in
+ Text(GamePageCopy.plainName(r)).tag(r.rawValue)
+ }
+ }.labelsHidden().frame(maxWidth: 360)
+ }
+ }
+ HStack(alignment: .top, spacing: 12) {
+ Text(L("Environment's mode")).font(.caption).foregroundStyle(.secondary).frame(width: 110, alignment: .leading).padding(.top, 4)
+ GraphicsModePicker(bottle: bottle)
+ }
}
row(L("Engine"), (state.engine(for: bottle)?.displayName).map { "\($0) · \(bottle.settings.engineID)" } ?? bottle.settings.engineID)
HStack(alignment: .firstTextBaseline, spacing: 12) {
diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swift
index f15ad4f..0a6a3d8 100644
--- a/Sources/HighballApp/HighballApp.swift
+++ b/Sources/HighballApp/HighballApp.swift
@@ -252,6 +252,19 @@ struct ContentView: View {
} message: { pending in
Text(GamePageCopy.engineAsk(recipe: pending.recipe, manifest: pending.manifest, installed: state.engines.contains { $0.id == pending.manifest.id }))
}
+ .alert(state.rendererTrial.map { String(format: L("Try %@ for %@ next time?"), GamePageCopy.plainName($0.next), $0.title) } ?? "",
+ isPresented: .init(get: { state.rendererTrial != nil }, set: { if !$0 { state.rendererTrial = nil } }),
+ presenting: state.rendererTrial) { trial in
+ Button(String(format: L("Use %@ for this game"), GamePageCopy.plainName(trial.next))) { state.acceptRendererTrial() }
+ Button(L("Report how it went…")) {
+ state.rendererTrial = nil
+ let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
+ Task.detached { let url = BugReport.url(version: version); await MainActor.run { NSWorkspace.shared.open(url) } }
+ }
+ Button(L("Not now"), role: .cancel) { state.rendererTrial = nil }
+ } message: { trial in
+ Text(String(format: L("It ran with %@. Another mode often suits a game better on this Mac, and old DirectX 9 games in particular do badly on Wine's own Direct3D. This changes the mode for this game only; the environment keeps its own. Undo it any time under Advanced on the game's page."), GamePageCopy.plainName(trial.current)))
+ }
.sheet(isPresented: $state.showEpicSignIn) { EpicSignInSheet() }
// A partial delete succeeded — the bottle is gone and the name is free — so framing it as
// a failure, with an invitation to file a bug, misreads what happened. Same alert, honest
@@ -289,8 +302,10 @@ struct ContentView: View {
}
.alert(crashTitle, isPresented: Binding(get: { state.crashSuggestion != nil }, set: { if !$0 { state.crashSuggestion = nil } }),
presenting: state.crashSuggestion) { s in
- Button("Use \(s.renderer.rawValue.uppercased())") {
- if var bottle = state.bottles.first(where: { $0.name == s.bottleName }) {
+ Button(s.itemID == nil ? "Use \(s.renderer.rawValue.uppercased())" : String(format: L("Use %@ for this game"), s.renderer.rawValue.uppercased())) {
+ if let itemID = s.itemID {
+ state.setRendererOverride(s.renderer, for: itemID) // this game only; the environment keeps its mode
+ } else if var bottle = state.bottles.first(where: { $0.name == s.bottleName }) {
bottle.settings.renderer = s.renderer
bottle.settings.rendererExplicit = true // the user picked it; recipes must not clobber it (#29)
state.update(bottle)
diff --git a/Sources/HighballApp/L10n.swift b/Sources/HighballApp/L10n.swift
index d7dda2d..796e3e5 100644
--- a/Sources/HighballApp/L10n.swift
+++ b/Sources/HighballApp/L10n.swift
@@ -116,6 +116,13 @@ enum L10n {
"D3DMetal — D3D11/12, Apple": "D3DMetal — D3D11/12, Apple",
"DXVK — D3D9/10/11 → Vulkan": "DXVK — D3D9/10/11 → Vulkan",
"Get beta builds": "Recevoir les versions bêta",
+ "Mode for this game": "Mode pour ce jeu",
+ "Environment's mode": "Mode de l'environnement",
+ "Use %@ for this game": "Utiliser %@ pour ce jeu",
+ "Try %@ for %@ next time?": "Essayer %@ pour %@ la prochaine fois ?",
+ "Report how it went…": "Signaler comment ça s'est passé…",
+ "It ran with %@. Another mode often suits a game better on this Mac, and old DirectX 9 games in particular do badly on Wine's own Direct3D. This changes the mode for this game only; the environment keeps its own. Undo it any time under Advanced on the game's page.": "Il a tourné avec %@. Un autre mode convient souvent mieux à un jeu sur ce Mac, et les vieux jeux DirectX 9 en particulier tournent mal avec le Direct3D de Wine. Cela change le mode pour ce jeu seulement, l'environnement garde le sien. Annulable à tout moment dans Avancé sur la page du jeu.",
+ "Does not apply: this game draws with Vulkan directly, not through any Direct3D layer.": "Sans effet : ce jeu dessine directement avec Vulkan, sans couche Direct3D.",
"%@ needs the %@ engine": "%@ a besoin du moteur %@",
"New environment for %@": "Nouvel environnement pour %@",
"Move this environment": "Déplacer cet environnement",
diff --git a/Sources/HighballKit/Bottle.swift b/Sources/HighballKit/Bottle.swift
index 791dd71..ee2518d 100644
--- a/Sources/HighballKit/Bottle.swift
+++ b/Sources/HighballKit/Bottle.swift
@@ -629,3 +629,16 @@ extension JSONDecoder {
return d
}
}
+
+public extension Renderer {
+ /// The mode a launch runs with, most specific choice first: the caller's (the D3DMetal ask's
+ /// "play with the other mode"), the game's own override, the database row unless the
+ /// environment's mode is an explicit choice, a pinned program's own, then the environment's.
+ /// A native-Vulkan title ignores rows and overrides: no Direct3D layer draws it, so the
+ /// environment's mode is as good as any (#44).
+ static func choose(requested: Renderer?, gameOverride: Renderer?, row: Renderer?, environmentExplicit: Bool,
+ pin: Renderer?, environment: Renderer, nativeVulkan: Bool = false) -> Renderer {
+ if nativeVulkan { return requested ?? environment }
+ return requested ?? gameOverride ?? (environmentExplicit ? nil : row) ?? pin ?? environment
+ }
+}
diff --git a/Sources/HighballKit/EngineStore.swift b/Sources/HighballKit/EngineStore.swift
index 678f597..1d5f13d 100644
--- a/Sources/HighballKit/EngineStore.swift
+++ b/Sources/HighballKit/EngineStore.swift
@@ -57,6 +57,14 @@ public struct EngineStore: Sendable {
?? 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).
diff --git a/Sources/HighballKit/GamePageCopy.swift b/Sources/HighballKit/GamePageCopy.swift
index 14f077c..e609676 100644
--- a/Sources/HighballKit/GamePageCopy.swift
+++ b/Sources/HighballKit/GamePageCopy.swift
@@ -56,10 +56,14 @@ public enum GamePageCopy {
/// What Play applies, in order, from the row and the fix recipe. `applied` means the recipe
/// already ran in this environment, so its steps read as done.
public static func willDo(_ entry: GameDBEntry?, recipe: Recipe?, applied: Bool,
- bottleRenderer: Renderer, explicit: Bool = false,
+ bottleRenderer: Renderer, explicit: Bool = false, gameOverride: Renderer? = nil,
osMajor: Int = ProcessInfo.processInfo.operatingSystemVersion.majorVersion) -> [WillDo] {
var items: [WillDo] = []
- if explicit {
+ if entry?.nativeVulkan == true {
+ items.append(WillDo(text: "Let it draw with Vulkan directly; the graphics mode does not apply to this game"))
+ } else if let gameOverride {
+ items.append(WillDo(text: "Use \(plainName(gameOverride)) for this game (set by you); the environment stays on \(plainName(bottleRenderer))"))
+ } else if explicit {
items.append(WillDo(text: "Use \(plainName(bottleRenderer)), the environment's setting (set by you)"))
} else if let wanted = entry?.effectiveRenderer(osMajor: osMajor) {
items.append(WillDo(text: wanted == bottleRenderer
diff --git a/Sources/HighballKit/Library.swift b/Sources/HighballKit/Library.swift
index 90384f1..bd2ece7 100644
--- a/Sources/HighballKit/Library.swift
+++ b/Sources/HighballKit/Library.swift
@@ -134,6 +134,11 @@ public struct LibraryStore: Sendable {
private struct FileShape: Codable {
var formatVersion: Int = 1
var items: [String: PlayRecord] = [:]
+ /// A graphics mode chosen for one game, by library id: the guided trial's answer (item 1,
+ /// #66 and #67 were users stuck on Wine's own Direct3D for old DirectX 9 games with no way
+ /// to change one game without changing the whole environment). Optional so files written
+ /// before it still decode.
+ var overrides: [String: Renderer]?
}
public let paths: HighballPaths
@@ -148,8 +153,26 @@ public struct LibraryStore: Sendable {
return shape.items
}
+ public func rendererOverrides() -> [String: Renderer] { loadShape().overrides ?? [:] }
+
+ /// Sets, or with nil clears, the graphics mode this one game runs with.
+ public func setRendererOverride(_ renderer: Renderer?, for id: String) {
+ var shape = loadShape()
+ var overrides = shape.overrides ?? [:]
+ overrides[id] = renderer
+ shape.overrides = overrides.isEmpty ? nil : overrides
+ try? paths.ensure()
+ if let data = try? JSONEncoder.highball.encode(shape) { try? data.write(to: fileURL, options: .atomic) }
+ }
+
+ private func loadShape() -> FileShape {
+ guard let data = try? Data(contentsOf: fileURL),
+ let shape = try? JSONDecoder.highball.decode(FileShape.self, from: data) else { return FileShape() }
+ return shape
+ }
+
public func recordPlay(id: String, bottle: String?, date: Date = Date()) {
- var shape = FileShape(items: load())
+ var shape = loadShape()
shape.items[id] = PlayRecord(lastPlayedAt: date, bottle: bottle)
try? paths.ensure()
if let data = try? JSONEncoder.highball.encode(shape) {
@@ -159,10 +182,12 @@ public struct LibraryStore: Sendable {
/// Drops records whose items no longer exist (uninstalled games, deleted pins).
public func prune(validIDs: Set<String>) {
- let current = load()
+ let whole = loadShape()
+ let current = whole.items
let kept = current.filter { validIDs.contains($0.key) }
- guard kept.count != current.count else { return }
- let shape = FileShape(items: kept)
+ let keptOverrides = (whole.overrides ?? [:]).filter { validIDs.contains($0.key) }
+ guard kept.count != current.count || keptOverrides.count != (whole.overrides ?? [:]).count else { return }
+ let shape = FileShape(items: kept, overrides: keptOverrides.isEmpty ? nil : keptOverrides)
if let data = try? JSONEncoder.highball.encode(shape) {
try? data.write(to: fileURL, options: .atomic)
}
diff --git a/Sources/HighballKit/SteamLibrary.swift b/Sources/HighballKit/SteamLibrary.swift
index 1c5a5bc..902f420 100644
--- a/Sources/HighballKit/SteamLibrary.swift
+++ b/Sources/HighballKit/SteamLibrary.swift
@@ -78,6 +78,9 @@ public struct GameDBEntry: Codable, Sendable {
public var epic_app_name: String?
public var status: String // verified-local | reported-upstream | community | blocked-anticheat
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?
diff --git a/Tests/HighballKitTests/GuidedRendererTests.swift b/Tests/HighballKitTests/GuidedRendererTests.swift
new file mode 100644
index 0000000..3e218e0
--- /dev/null
+++ b/Tests/HighballKitTests/GuidedRendererTests.swift
@@ -0,0 +1,71 @@
+import XCTest
+@testable import HighballKit
+
+/// Per-game graphics modes (the guided renderer trial, ux-plan item 1), the one resolution rule
+/// for a launch, the native-Vulkan flag (#44), and the same-Wine engine auto-update (item 9).
+final class GuidedRendererTests: XCTestCase {
+ private var home: URL!
+ override func setUpWithError() throws {
+ home = FileManager.default.temporaryDirectory.appending(path: "hb-guided-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: home, withIntermediateDirectories: true)
+ }
+ override func tearDownWithError() throws { try? FileManager.default.removeItem(at: home) }
+
+ func testOverridesPersistBesidePlaysAndSurviveOldFiles() throws {
+ let store = LibraryStore(paths: HighballPaths(home: home))
+ store.recordPlay(id: "steam:319510", bottle: "Games")
+ XCTAssertEqual(store.rendererOverrides(), [:], "nothing chosen yet")
+ store.setRendererOverride(.dxvk, for: "steam:319510")
+ XCTAssertEqual(store.rendererOverrides(), ["steam:319510": .dxvk])
+ XCTAssertNotNil(store.load()["steam:319510"], "setting a mode keeps the play record")
+ store.setRendererOverride(nil, for: "steam:319510")
+ XCTAssertEqual(store.rendererOverrides(), [:], "nil clears it")
+ // A file from before overrides existed still loads.
+ try #"{"formatVersion":1,"items":{"steam:400":{"lastPlayedAt":"2026-09-01T00:00:00Z","bottle":"Games"}}}"#
+ .write(to: home.appending(path: "library.json"), atomically: true, encoding: .utf8)
+ XCTAssertEqual(store.rendererOverrides(), [:])
+ XCTAssertNotNil(store.load()["steam:400"])
+ }
+
+ func testPruneDropsOverridesOfGamesThatAreGone() {
+ let store = LibraryStore(paths: HighballPaths(home: home))
+ store.setRendererOverride(.wined3d, for: "steam:1")
+ store.setRendererOverride(.dxmt, for: "steam:2")
+ store.prune(validIDs: ["steam:2"])
+ XCTAssertEqual(store.rendererOverrides(), ["steam:2": .dxmt])
+ }
+
+ func testTheResolutionRuleMostSpecificFirst() {
+ XCTAssertEqual(Renderer.choose(requested: .dxmt, gameOverride: .dxvk, row: .d3dmetal, environmentExplicit: false, pin: .wined3d, environment: .dxvk), .dxmt, "the caller's choice wins")
+ XCTAssertEqual(Renderer.choose(requested: nil, gameOverride: .dxvk, row: .d3dmetal, environmentExplicit: false, pin: nil, environment: .dxmt), .dxvk, "the game's own override beats the row")
+ XCTAssertEqual(Renderer.choose(requested: nil, gameOverride: nil, row: .d3dmetal, environmentExplicit: false, pin: nil, environment: .dxmt), .d3dmetal, "the row applies")
+ XCTAssertEqual(Renderer.choose(requested: nil, gameOverride: nil, row: .d3dmetal, environmentExplicit: true, pin: nil, environment: .dxmt), .dxmt, "an explicit environment choice silences the row")
+ XCTAssertEqual(Renderer.choose(requested: nil, gameOverride: nil, row: nil, environmentExplicit: false, pin: .wined3d, environment: .dxmt), .wined3d, "a pinned program's own mode")
+ XCTAssertEqual(Renderer.choose(requested: nil, gameOverride: .dxvk, row: .d3dmetal, environmentExplicit: false, pin: nil, environment: .dxmt, nativeVulkan: true), .dxmt, "a native-Vulkan title ignores rows and overrides")
+ }
+
+ func testNativeVulkanRowDecodesAndSpeaks() throws {
+ let json = #"{"id":"sims","title":"The Sims Legacy Collection","steam_appid":3314060,"status":"verified-local","renderer":"dxvk","nativeVulkan":true}"#
+ let entry = try JSONDecoder().decode(GameDBEntry.self, from: Data(json.utf8))
+ XCTAssertEqual(entry.nativeVulkan, true)
+ let lines = GamePageCopy.willDo(entry, recipe: nil, applied: false, bottleRenderer: .dxmt)
+ XCTAssertTrue(lines.first?.text.contains("draw with Vulkan directly") == true, "the page says the mode does not apply: \(lines.first?.text ?? "")")
+ let plain = try JSONDecoder().decode(GameDBEntry.self, from: Data(#"{"id":"x","title":"X","status":"community"}"#.utf8))
+ XCTAssertNil(plain.nativeVulkan)
+ let chosen = GamePageCopy.willDo(plain, recipe: nil, applied: false, bottleRenderer: .dxmt, gameOverride: .dxvk)
+ XCTAssertTrue(chosen.first?.text.contains("for this game (set by you)") == true, "a per-game choice is named as such: \(chosen.first?.text ?? "")")
+ }
+
+ func testSameWineUpdateMayApplyItselfAndADifferentWineMayNot() throws {
+ func manifest(_ id: String, wine: String) throws -> EngineManifest {
+ try JSONDecoder().decode(EngineManifest.self, from: Data("""
+ {"id": "\(id)", "displayName": "x", "arch": "x86_64", "minMacOS": "14.0",
+ "components": {"wine": {"kind": "engine", "url": "https://example.invalid/w.tar.gz", "sha256": "\(wine)"}}}
+ """.utf8))
+ }
+ let r1 = try manifest("x64-sikarugir10.0_6-r1", wine: "same"), r2 = try manifest("x64-sikarugir10.0_6-r2", wine: "same")
+ let wine11 = try manifest("x64-crossover26.3-r4", wine: "other")
+ XCTAssertTrue(EngineStore.autoUpdateAllowed(from: r1, to: r2), "component-only update")
+ XCTAssertFalse(EngineStore.autoUpdateAllowed(from: r1, to: wine11), "a different Wine waits for a click")
+ }
+}