Skip to content

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

An engine can ask for per-executable registry defaults, mirrored into the environment before a launch

Gauthier Piarrette9c88484b4490
diff --git a/Sources/HighballKit/Bottle.swift b/Sources/HighballKit/Bottle.swift
index e4fe970..86bde40 100644
--- a/Sources/HighballKit/Bottle.swift
+++ b/Sources/HighballKit/Bottle.swift
@@ -372,6 +372,10 @@ public struct BottleSettings: Codable, Sendable {
/// inherits Steam's environment from before the setting changed and never sees it
/// (issues #22/#25). Launches re-mirror when this differs from dllOverrides.
public var dllOverridesSynced: String?
+ /// What WineRunner.syncEngineAppDefaults last wrote into the prefix (engine id plus its
+ /// per-executable defaults), so a launch on the same engine skips the registry and an engine
+ /// change or a manifest update rewrites.
+ public var engineAppDefaultsSynced: String?
/// Game files stay inside the environment: the user's Documents is a real folder under
/// drive_c instead of a link to the macOS Documents (which is what wineboot makes, and why
/// Dark Souls' or the Sims' save folders land in ~/Documents, discussion #157). Off keeps the
@@ -389,7 +393,7 @@ public struct BottleSettings: Codable, Sendable {
public var recipes: [String] = []
public var created: Date = Date()
- enum CodingKeys: String, CodingKey { case formatVersion, name, engineID, renderer, rendererExplicit, windowsVersion, sync, metalHUD, advertiseAVX, dxvkAsync, fpsCap, frameGen, frameGenAdaptive, frameGenFlowScale, frameGenPerformance, frameGenForceVsync, commandIsControl, commandIsControlSynced, dpiScale, dllOverrides, dxvkAppConfig, dllOverridesSynced, keepFilesInside, environment, gameEnvironment, pins, recipes, created }
+ enum CodingKeys: String, CodingKey { case formatVersion, name, engineID, renderer, rendererExplicit, windowsVersion, sync, metalHUD, advertiseAVX, dxvkAsync, fpsCap, frameGen, frameGenAdaptive, frameGenFlowScale, frameGenPerformance, frameGenForceVsync, commandIsControl, commandIsControlSynced, dpiScale, dllOverrides, dxvkAppConfig, dllOverridesSynced, engineAppDefaultsSynced, keepFilesInside, environment, gameEnvironment, pins, recipes, created }
/// The variables `gameID`'s recipe scoped to it; empty for a game without any, or with no id.
public func environment(forGame gameID: String?) -> [String: String] {
@@ -440,6 +444,7 @@ public struct BottleSettings: Codable, Sendable {
}
dllOverrides = try c.decodeIfPresent(String.self, forKey: .dllOverrides) ?? ""
dllOverridesSynced = try c.decodeIfPresent(String.self, forKey: .dllOverridesSynced)
+ engineAppDefaultsSynced = try c.decodeIfPresent(String.self, forKey: .engineAppDefaultsSynced)
keepFilesInside = try c.decodeIfPresent(Bool.self, forKey: .keepFilesInside) ?? false
commandIsControl = try c.decodeIfPresent(Bool.self, forKey: .commandIsControl) ?? true
commandIsControlSynced = try c.decodeIfPresent(Bool.self, forKey: .commandIsControlSynced)
diff --git a/Sources/HighballKit/EngineStore.swift b/Sources/HighballKit/EngineStore.swift
index d09b2ea..3458b01 100644
--- a/Sources/HighballKit/EngineStore.swift
+++ b/Sources/HighballKit/EngineStore.swift
@@ -164,6 +164,7 @@ public struct EngineStore: Sendable {
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) }
}
diff --git a/Sources/HighballKit/Manifest.swift b/Sources/HighballKit/Manifest.swift
index fd81648..6597e83 100644
--- a/Sources/HighballKit/Manifest.swift
+++ b/Sources/HighballKit/Manifest.swift
@@ -71,6 +71,14 @@ public struct EngineManifest: Codable, Sendable, Identifiable {
/// keeps DXVK's d3d9 whatever this says: there Direct3D 9 through DXVK is the point (CS:GO
/// Legacy's CSM check needs it, highball#21).
public var direct3D9: String?
+ /// Registry values this engine wants under HKCU\Software\Wine\AppDefaults\<exe>, per
+ /// executable: value name to REG_SZ data. Highball mirrors them into every environment on the
+ /// engine before a launch (WineRunner.syncEngineAppDefaults), so an environment that moved to
+ /// the engine gets them without a recipe re-run. First use: on the Wine 11 tree Steam's browser
+ /// (steamwebhelper.exe) composites on the GPU into steam.exe's window and DXVK presents that
+ /// black, while the Wine 10 engine's Steam never touches Direct3D 11, so the engine asks for
+ /// CommandLineAppend = --disable-gpu (patch 0006), the software path (highball#202, 2026-09-26).
+ public var appDefaults: [String: [String: String]]?
public var components: [String: Component]
public var baseEnv: [String: String]?
/// License ids that gate optional renderers (e.g. `apple-gptk-license-2023-08-17` → d3dmetal).
diff --git a/Sources/HighballKit/WineRunner.swift b/Sources/HighballKit/WineRunner.swift
index 6cdb9db..6cb8e7d 100644
--- a/Sources/HighballKit/WineRunner.swift
+++ b/Sources/HighballKit/WineRunner.swift
@@ -245,6 +245,7 @@ public struct WineRunner: Sendable {
@discardableResult
public func start(_ executable: URL, arguments: [String] = [], renderer: Renderer? = nil, extraEnvironment: [String: String] = [:], workingDirectory: URL? = nil, headerNote: String? = nil, onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult {
await syncDllOverridesRegistry()
+ await syncEngineAppDefaults()
await syncKeyboardRegistry()
var note = headerNote
if let rebooted = try await rebootIdleEnvironmentIfMismatched(renderer: renderer, extraEnvironment: extraEnvironment) {
@@ -545,6 +546,37 @@ public struct WineRunner: Sendable {
markSynced { $0.dllOverridesSynced = current }
}
+ /// The marker `syncEngineAppDefaults` records: the engine and its defaults in a fixed order,
+ /// so the same set on the same engine compares equal whatever the dictionary order.
+ public static func appDefaultsMarker(engineID: String, defaults: [String: [String: String]]) -> String {
+ let body = defaults.keys.sorted().map { exe in
+ exe + "{" + defaults[exe]!.keys.sorted().map { "\($0)=\(defaults[exe]![$0]!)" }.joined(separator: ";") + "}"
+ }.joined(separator: ",")
+ return engineID + ":" + body
+ }
+
+ /// Mirrors the engine's per-executable registry defaults (EngineManifest.appDefaults) into the
+ /// prefix under HKCU\Software\Wine\AppDefaults\<exe>. Once per engine and value set: the marker
+ /// in the settings records what was written, so a launch on the same engine costs nothing and
+ /// an engine change or a manifest update rewrites. Values an earlier engine wrote are left in
+ /// place: they name that engine's own switches (patch 0006's CommandLineAppend), which other
+ /// trees ignore. On failure the marker stays stale so the next launch retries.
+ public func syncEngineAppDefaults() async {
+ let defaults = engine.manifest.appDefaults ?? [:]
+ let wanted = Self.appDefaultsMarker(engineID: engine.id, defaults: defaults)
+ guard wanted != (bottle.settings.engineAppDefaultsSynced ?? "") else { return }
+ var allAdded = true
+ for exe in defaults.keys.sorted() {
+ for name in defaults[exe]!.keys.sorted() {
+ let status = try? await run(["reg", "add", #"HKCU\Software\Wine\AppDefaults\"# + exe, "/v", name, "/t", "REG_SZ", "/d", defaults[exe]![name]!, "/f"],
+ renderer: .wined3d, label: "reg").exitStatus
+ if status != 0 { allAdded = false }
+ }
+ }
+ guard allAdded else { return }
+ markSynced { $0.engineAppDefaultsSynced = wanted }
+ }
+
/// Records a "last mirrored into the prefix registry" marker. Re-reads from disk rather than
/// saving `bottle`, which is a snapshot taken when the runner was built: saving it whole also
/// rewrites every other setting as it stood then, so a second sync in the same launch would
diff --git a/Tests/HighballKitTests/EngineAppDefaultsTests.swift b/Tests/HighballKitTests/EngineAppDefaultsTests.swift
new file mode 100644
index 0000000..5913138
--- /dev/null
+++ b/Tests/HighballKitTests/EngineAppDefaultsTests.swift
@@ -0,0 +1,61 @@
+import XCTest
+@testable import HighballKit
+
+/// An engine can ask for registry values under HKCU\Software\Wine\AppDefaults\<exe>
+/// (`EngineManifest.appDefaults`), mirrored into the prefix before a launch. First use: the Wine
+/// 11 tree's Steam browser drawing black in the DXVK mode (highball#202).
+final class EngineAppDefaultsTests: XCTestCase {
+
+ func testMarkerIsStableAcrossDictionaryOrder() {
+ let a = WineRunner.appDefaultsMarker(engineID: "e", defaults: ["steamwebhelper.exe": ["CommandLineAppend": "--disable-gpu", "Other": "x"], "a.exe": ["K": "v"]])
+ let b = WineRunner.appDefaultsMarker(engineID: "e", defaults: ["a.exe": ["K": "v"], "steamwebhelper.exe": ["Other": "x", "CommandLineAppend": "--disable-gpu"]])
+ XCTAssertEqual(a, b)
+ XCTAssertEqual(a, "e:a.exe{K=v},steamwebhelper.exe{CommandLineAppend=--disable-gpu;Other=x}")
+ XCTAssertNotEqual(a, WineRunner.appDefaultsMarker(engineID: "f", defaults: ["a.exe": ["K": "v"]]), "a different engine rewrites")
+ XCTAssertEqual(WineRunner.appDefaultsMarker(engineID: "e", defaults: [:]), "e:")
+ }
+
+ func testManifestRoundTripsTheDefaults() throws {
+ let manifestURL = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+ .appending(path: "spike/engine-manifest.json")
+ var m = try EngineManifest.load(from: manifestURL)
+ XCTAssertNil(m.appDefaults)
+ m.appDefaults = ["steamwebhelper.exe": ["CommandLineAppend": "--disable-gpu"]]
+ let dir = FileManager.default.temporaryDirectory.appending(path: "hb-appdefaults-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: dir) }
+ try m.save(to: dir.appending(path: "manifest.json"))
+ XCTAssertEqual(try EngineManifest.load(from: dir.appending(path: "manifest.json")).appDefaults, m.appDefaults)
+ }
+
+ func testInstalledEnginesAdoptTheDefaultsFromKnownManifests() throws {
+ let home = FileManager.default.temporaryDirectory.appending(path: "hb-appdefaults-home-\(UUID().uuidString)")
+ defer { try? FileManager.default.removeItem(at: home) }
+ let paths = HighballPaths(home: home)
+ let store = EngineStore(paths: paths)
+ let manifestURL = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+ .appending(path: "spike/engine-manifest.json")
+ var base = try EngineManifest.load(from: manifestURL)
+ base.appDefaults = nil
+ for id in ["x64-crossover26.3-r12", "x64-sikarugir10.0_6-r7"] {
+ var m = base; m.id = id
+ let dir = paths.engine(id)
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ try m.save(to: dir.appending(path: "manifest.json"))
+ }
+ var known = base; known.id = "x64-crossover26.3-r12"; known.appDefaults = ["steamwebhelper.exe": ["CommandLineAppend": "--disable-gpu"]]
+ XCTAssertEqual(store.adoptKnownFacts(known: [known]), ["x64-crossover26.3-r12"])
+ XCTAssertEqual(try store.engine("x64-crossover26.3-r12").manifest.appDefaults, known.appDefaults)
+ XCTAssertNil(try store.engine("x64-sikarugir10.0_6-r7").manifest.appDefaults)
+ XCTAssertEqual(store.adoptKnownFacts(known: [known]), [], "a second pass changes nothing")
+ }
+
+ func testSettingsKeepTheSyncMarker() throws {
+ var s = BottleSettings(name: "t", engineID: "e")
+ s.engineAppDefaultsSynced = "e:steamwebhelper.exe{CommandLineAppend=--disable-gpu}"
+ let data = try JSONEncoder().encode(s)
+ XCTAssertEqual(try JSONDecoder().decode(BottleSettings.self, from: data).engineAppDefaultsSynced, s.engineAppDefaultsSynced)
+ }
+}