Skip to content

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

A game recipe's environment step applies to that game only, not to everything in the environment

Gauthier Piarrette113aa60b8042
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index faa3883..004d63a 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -258,7 +258,21 @@ final class AppState {
/// other mode"); nil lets the row and the environment decide.
func play(_ item: LibraryItem, renderer: Renderer? = nil) {
guard let bottleName = item.bottleName,
- let bottle = bottles.first(where: { $0.name == bottleName }) else { return }
+ let found = bottles.first(where: { $0.name == bottleName }) else { return }
+ var bottle = found
+ // A game whose recipe was applied before variables were scoped still has them bottle-wide,
+ // where every other program inherits them (highball#198). Move them to the game once; the
+ // launch below then carries them for this game only, and the log says what moved.
+ if let recipe = fixRecipe(for: item), bottle.settings.recipes.contains(recipe.id) {
+ var settings = bottle.settings
+ let moved = HighballKit.Recipe.scopeLeakedEnvironment(of: recipe, in: &settings)
+ if !moved.isEmpty {
+ bottle.settings = settings
+ try? bottle.save()
+ appendLog("\(item.title): \(moved.joined(separator: ", ")) now applies to this game only, not to everything in \(bottle.name).")
+ refresh()
+ }
+ }
// The mode this launch will run with, whoever chose it: the caller, the row (unless the
// environment's mode is an explicit choice), a pinned program's own, or the environment.
// An engine that cannot run it must not be found out by Wine (#61: a fix recipe had set
@@ -1761,6 +1775,8 @@ final class AppState {
let renderer = preferred ?? (bottle.settings.rendererExplicit ? nil : entry?.effectiveRenderer())
// Per-game launch args ride the db (e.g. windowed for legacy CS:GO on macOS 26, #21).
let extraArgs = entry?.effectiveLaunchArgs() ?? []
+ // The variables this game's recipe scoped to it (highball#198); other games get none of them.
+ let gameEnvironment = bottle.settings.environment(forGame: entry?.id)
let markers = SessionWatch.markers(installdir: game.installdir)
// The busy sheet covers the start only: Steam's client outlives the game and its launch
// call says nothing about it, so the game's own processes decide when "starting" ends
@@ -1776,7 +1792,7 @@ final class AppState {
// the game runs on the client's stack, and a report must not claim otherwise.
var headerNote: String?
var served = renderer ?? bottle.settings.renderer
- switch try await runner.restartSteamIfMismatched(renderer: renderer, mayRestart: !sessionRuns(in: bottle)) {
+ switch try await runner.restartSteamIfMismatched(renderer: renderer, extraEnvironment: gameEnvironment, mayRestart: !sessionRuns(in: bottle)) {
case .restarted(let why):
await MainActor.run { self.appendLog("Restarting Steam before \(game.name): \(why).") }
case .kept(let why, let live):
@@ -1792,7 +1808,7 @@ final class AppState {
let box = LaunchOutcome()
let log = logLine(box)
watchedLaunch(box) {
- try await runner.start(steam, arguments: ["-silent", "-applaunch", String(game.appid)] + extraArgs, renderer: renderer, headerNote: note, onOutput: log)
+ try await runner.start(steam, arguments: ["-silent", "-applaunch", String(game.appid)] + extraArgs, renderer: renderer, extraEnvironment: gameEnvironment, headerNote: note, onOutput: log)
}
let handedOff = try await awaitHandoff(box, program: game.name, timeout: 360, exitEndsWait: false) {
SessionWatch.isAlive(markers: markers, ps: await Self.processList())
@@ -2040,9 +2056,11 @@ final class AppState {
appendLog("\(game.app_title): this build has no EpicGamesLauncher.exe stand-in, the Rockstar launcher may not accept the Epic copy")
}
}
+ // The variables this game's recipe scoped to it (highball#198), on top of Legendary's.
+ let gameEnvironment = bottle.settings.environment(forGame: gameDB.byEpicAppName[game.app_name]?.id)
watchedLaunch(box) {
try await runner.start(executable, arguments: arguments,
- renderer: renderer, extraEnvironment: info.environment,
+ renderer: renderer, extraEnvironment: info.environment.merging(gameEnvironment) { _, new in new },
workingDirectory: info.workingDirectory, onOutput: log)
}
let markers = SessionWatch.markers(executable: info.executable)
diff --git a/Sources/HighballKit/Bottle.swift b/Sources/HighballKit/Bottle.swift
index 742a2f0..bb862df 100644
--- a/Sources/HighballKit/Bottle.swift
+++ b/Sources/HighballKit/Bottle.swift
@@ -376,11 +376,30 @@ public struct BottleSettings: Codable, Sendable {
/// is deleted, and the delete confirmation says so.
public var keepFilesInside: Bool = false
public var environment: [String: String] = [:]
+ /// Variables a game's recipe sets for that one game's launches, keyed by the recipe's id (the
+ /// db row's id). A recipe's environment step used to land in `environment` and reach every
+ /// program in the bottle: the Sims recipe's MVK_SHADOW_IMPORT=1 then broke DXVK's Direct3D 9
+ /// for every other game on the Wine 11 engines (highball#198). Merged into the launch after
+ /// `environment`, for the game the recipe is for and nothing else.
+ public var gameEnvironment: [String: [String: String]] = [:]
public var pins: [Pin] = []
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, 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, 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] {
+ gameID.flatMap { gameEnvironment[$0] } ?? [:]
+ }
+
+ /// Every variable name a launch in this bottle can carry beyond the engine's own: the
+ /// bottle-wide ones and every game's scoped ones. A running Steam client started for one game
+ /// carries that game's variables, and the next game must not inherit them, so the restart
+ /// rule compares all of these names, not only the bottle-wide ones.
+ public var customEnvironmentKeys: [String] {
+ Array(Set(environment.keys).union(gameEnvironment.values.flatMap(\.keys)))
+ }
public init(name: String, engineID: String) {
self.name = name
@@ -422,6 +441,7 @@ public struct BottleSettings: Codable, Sendable {
commandIsControl = try c.decodeIfPresent(Bool.self, forKey: .commandIsControl) ?? true
commandIsControlSynced = try c.decodeIfPresent(Bool.self, forKey: .commandIsControlSynced)
environment = try c.decodeIfPresent([String: String].self, forKey: .environment) ?? [:]
+ gameEnvironment = try c.decodeIfPresent([String: [String: String]].self, forKey: .gameEnvironment) ?? [:]
pins = try c.decodeIfPresent([Pin].self, forKey: .pins) ?? []
recipes = try c.decodeIfPresent([String].self, forKey: .recipes) ?? []
created = try c.decodeIfPresent(Date.self, forKey: .created) ?? Date()
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swift
index eaffb9f..1af4d9e 100644
--- a/Sources/HighballKit/Recipe.swift
+++ b/Sources/HighballKit/Recipe.swift
@@ -507,7 +507,16 @@ public struct RecipeRunner: Sendable {
try Shell.capture("/bin/bash", [wt.path, "--unattended"] + verbs, env: env, log: logURL,
logHeader: "# highball winetricks \(verbs.joined(separator: " ")) bottle=\(bottle.name) engine=\(engine.id)")
case let .environment(name, value):
- bottle.settings.environment[name] = value
+ // A game's variable is the game's: bottle-wide it reached every other program
+ // (the Sims' MVK_SHADOW_IMPORT=1 broke DXVK's Direct3D 9 for every game on the
+ // Wine 11 engines, highball#198). Launchers and tweaks keep the bottle-wide
+ // scope: a launcher's variable is for the client and what it starts.
+ if recipe.kind == .game {
+ bottle.settings.gameEnvironment[recipe.id, default: [:]][name] = value
+ if bottle.settings.environment[name] == value { bottle.settings.environment.removeValue(forKey: name) }
+ } else {
+ bottle.settings.environment[name] = value
+ }
case let .renderer(r):
bottle.settings.renderer = r
case let .sync(m):
@@ -534,6 +543,11 @@ public struct RecipeRunner: Sendable {
log?("copied \(source.lastPathComponent) from the engine to \(to)\(asNative ? " as a native DLL" : "")")
case let .pin(p):
if !bottle.settings.pins.contains(where: { $0.path == p.path }) { bottle.settings.pins.append(p) }
+ // The pin is how this game is launched, so the game's variables ride the pin.
+ if recipe.kind == .game, let scoped = bottle.settings.gameEnvironment[recipe.id], !scoped.isEmpty,
+ let i = bottle.settings.pins.firstIndex(where: { $0.path == p.path }) {
+ bottle.settings.pins[i].environment.merge(scoped) { _, new in new }
+ }
case let .note(t):
notes.append(t)
case let .dllOverride(v):
@@ -550,6 +564,7 @@ public struct RecipeRunner: Sendable {
return notes
}
+
private func downloadUnverified(_ url: URL) async throws -> URL {
try paths.ensure()
let dest = paths.downloads.appending(path: url.lastPathComponent)
@@ -591,3 +606,23 @@ public extension Recipe {
return id
}
}
+
+public extension Recipe {
+ /// Moves the variables a game recipe set bottle-wide, before scoping existed, to that game.
+ /// A bottle set up before 0.9.38 carries the recipe's variable in `environment` with the
+ /// recipe's exact value; it moves to `gameEnvironment[recipe.id]` and leaves the bottle-wide
+ /// list, so the next launch of any other game runs without it. A value the owner changed by
+ /// hand is not the recipe's and stays. Returns the names moved, in order, empty when nothing
+ /// was there to move, so a caller can save and say so only when something changed.
+ static func scopeLeakedEnvironment(of recipe: Recipe, in settings: inout BottleSettings) -> [String] {
+ guard recipe.kind == .game else { return [] }
+ var moved: [String] = []
+ for step in recipe.steps {
+ guard case let .environment(name, value) = step, settings.environment[name] == value else { continue }
+ settings.environment.removeValue(forKey: name)
+ settings.gameEnvironment[recipe.id, default: [:]][name] = value
+ moved.append(name)
+ }
+ return moved
+ }
+}
diff --git a/Sources/HighballKit/SteamRestart.swift b/Sources/HighballKit/SteamRestart.swift
index 1aeb49b..490d4ae 100644
--- a/Sources/HighballKit/SteamRestart.swift
+++ b/Sources/HighballKit/SteamRestart.swift
@@ -90,7 +90,9 @@ public enum SteamRestart {
live["WINEDLLOVERRIDES"] != wanted["WINEDLLOVERRIDES"] {
reasons.append("it runs with different DLL overrides than the game wants")
}
- for key in custom.sorted() where key != "WINEDLLOVERRIDES" && !inherited.contains(where: { $0.0 == key }) && live[key] != wanted[key] {
+ // A set: a game's scoped variable arrives both in the bottle's list and in the launch's
+ // extra names, and one difference is one reason.
+ for key in Set(custom).sorted() where key != "WINEDLLOVERRIDES" && !inherited.contains(where: { $0.0 == key }) && live[key] != wanted[key] {
switch (live[key], wanted[key]) {
case (nil, let want?): reasons.append("it runs without \(key)=\(want)")
case (let have?, nil): reasons.append("it runs with \(key)=\(have) and the game does not set it")
@@ -139,12 +141,14 @@ extension WineRunner {
/// process working in a game folder): a wrong environment beats killing someone's game. That
/// case comes back as `.kept` so the caller can say so; silently launching under the client's
/// stack cost highball-db#48 six rounds, the game ran on DXMT while every log said D3DMetal.
- public func restartSteamIfMismatched(renderer: Renderer?, mayRestart: Bool = true) async throws -> SteamRestart.Outcome {
+ public func restartSteamIfMismatched(renderer: Renderer?, extraEnvironment: [String: String] = [:], mayRestart: Bool = true) async throws -> SteamRestart.Outcome {
guard let live = runningSteamEnvironment() else { return .noClient }
- let wanted = try bottle.environment(engine: engine, renderer: renderer)
+ let wanted = try bottle.environment(engine: engine, renderer: renderer, extra: extraEnvironment)
+ // Every game's scoped variables count, not only this game's: a client started for the
+ // Sims carries MVK_SHADOW_IMPORT=1, and the next game must not inherit it (highball#198).
guard let why = SteamRestart.reason(live: live, wanted: wanted,
wantedRenderer: (renderer ?? bottle.settings.renderer).rawValue,
- custom: Array(bottle.settings.environment.keys)) else { return .serves }
+ custom: bottle.settings.customEnvironmentKeys + Array(extraEnvironment.keys)) else { return .serves }
if !mayRestart || steamGameIsRunning() { return .kept(why, live: SteamRestart.rendererName(ofLive: live)) }
try await stopSteam()
return .restarted(why)
diff --git a/Sources/HighballKit/WineRunner.swift b/Sources/HighballKit/WineRunner.swift
index eea2fb2..6cdb9db 100644
--- a/Sources/HighballKit/WineRunner.swift
+++ b/Sources/HighballKit/WineRunner.swift
@@ -275,7 +275,7 @@ public struct WineRunner: Sendable {
let wanted = try bottle.environment(engine: engine, renderer: renderer, extra: extraEnvironment)
guard let why = SteamRestart.reason(live: live, wanted: wanted,
wantedRenderer: (renderer ?? bottle.settings.renderer).rawValue,
- custom: Array(bottle.settings.environment.keys)) else { return nil }
+ custom: bottle.settings.customEnvironmentKeys + Array(extraEnvironment.keys)) else { return nil }
guard ProcessTable.isIdle(prefix: bottle.url) else {
return "the environment's Windows services keep the stack they started with (\(why)); a program is still running, so the environment was not restarted"
}
diff --git a/Tests/HighballKitTests/RecipeScopeTests.swift b/Tests/HighballKitTests/RecipeScopeTests.swift
new file mode 100644
index 0000000..1431f2e
--- /dev/null
+++ b/Tests/HighballKitTests/RecipeScopeTests.swift
@@ -0,0 +1,103 @@
+import XCTest
+@testable import HighballKit
+
+/// A game recipe's environment step belongs to that game, not to the bottle (highball#198: the
+/// Sims recipe's MVK_SHADOW_IMPORT=1, applied bottle-wide, broke DXVK's Direct3D 9 for every
+/// other game on the Wine 11 engines). Launchers and tweaks keep the bottle-wide scope.
+final class RecipeScopeTests: XCTestCase {
+
+ private func recipe(_ json: String) throws -> Recipe {
+ try JSONDecoder.highball.decode(Recipe.self, from: Data(json.utf8))
+ }
+
+ private func fixtures() throws -> (engine: InstalledEngine, bottle: Bottle) {
+ let manifestURL = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+ .appending(path: "spike/engine-manifest.json")
+ let manifest = try EngineManifest.load(from: manifestURL)
+ let root = FileManager.default.temporaryDirectory.appending(path: "hb-scope-engine-\(UUID().uuidString)")
+ let dir = FileManager.default.temporaryDirectory.appending(path: "hb-scope-bottle-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ let bottle = Bottle(url: dir, settings: BottleSettings(name: "t", engineID: manifest.id))
+ return (InstalledEngine(manifest: manifest, root: root), bottle)
+ }
+
+ private let sims = """
+ {"id": "the-sims-legacy-collection", "kind": "game", "title": "The Sims", "requires": ["steam"],
+ "renderer": null, "steps": [{"type": "environment", "name": "MVK_SHADOW_IMPORT", "value": "1"}],
+ "knownIssues": [], "lastVerified": null}
+ """
+ private let launcher = """
+ {"id": "ea-app", "kind": "launcher", "title": "EA app", "requires": [],
+ "renderer": null, "steps": [{"type": "environment", "name": "DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN", "value": "1"}],
+ "knownIssues": [], "lastVerified": null}
+ """
+
+ func testGameRecipeVariableIsScopedToTheGame() async throws {
+ let (engine, bottle) = try fixtures()
+ var runner = RecipeRunner(engine: engine, bottle: bottle)
+ _ = try await runner.apply(try recipe(sims))
+ XCTAssertEqual(runner.bottle.settings.gameEnvironment["the-sims-legacy-collection"], ["MVK_SHADOW_IMPORT": "1"])
+ XCTAssertNil(runner.bottle.settings.environment["MVK_SHADOW_IMPORT"], "must not reach every program in the bottle")
+ // The launch for that game carries it; a launch for anything else does not.
+ XCTAssertEqual(runner.bottle.settings.environment(forGame: "the-sims-legacy-collection")["MVK_SHADOW_IMPORT"], "1")
+ XCTAssertEqual(runner.bottle.settings.environment(forGame: "five-nights-at-freddys"), [:])
+ XCTAssertEqual(runner.bottle.settings.environment(forGame: nil), [:])
+ let saved = try JSONDecoder.highball.decode(BottleSettings.self, from: Data(contentsOf: bottle.url.appending(path: "bottle.json")))
+ XCTAssertEqual(saved.gameEnvironment["the-sims-legacy-collection"]?["MVK_SHADOW_IMPORT"], "1", "survives a save and load")
+ }
+
+ func testLauncherRecipeVariableStaysBottleWide() async throws {
+ let (engine, bottle) = try fixtures()
+ var runner = RecipeRunner(engine: engine, bottle: bottle)
+ _ = try await runner.apply(try recipe(launcher))
+ XCTAssertEqual(runner.bottle.settings.environment["DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN"], "1")
+ XCTAssertTrue(runner.bottle.settings.gameEnvironment.isEmpty)
+ }
+
+ func testLaunchEnvironmentMergesTheGamesVariablesLast() throws {
+ var (engine, bottle) = try fixtures()
+ bottle.settings.gameEnvironment["the-sims-legacy-collection"] = ["MVK_SHADOW_IMPORT": "1"]
+ let sims = try bottle.environment(engine: engine, renderer: .wined3d, extra: bottle.settings.environment(forGame: "the-sims-legacy-collection"))
+ XCTAssertEqual(sims["MVK_SHADOW_IMPORT"], "1")
+ let other = try bottle.environment(engine: engine, renderer: .wined3d, extra: bottle.settings.environment(forGame: "five-nights-at-freddys"))
+ XCTAssertNil(other["MVK_SHADOW_IMPORT"])
+ }
+
+ func testLeakedVariableMovesToTheGameOnce() throws {
+ var settings = BottleSettings(name: "t", engineID: "e")
+ settings.environment = ["MVK_SHADOW_IMPORT": "1", "MY_OWN": "x"]
+ settings.recipes = ["the-sims-legacy-collection"]
+ let r = try recipe(sims)
+ XCTAssertEqual(Recipe.scopeLeakedEnvironment(of: r, in: &settings), ["MVK_SHADOW_IMPORT"])
+ XCTAssertEqual(settings.environment, ["MY_OWN": "x"])
+ XCTAssertEqual(settings.gameEnvironment["the-sims-legacy-collection"], ["MVK_SHADOW_IMPORT": "1"])
+ XCTAssertEqual(Recipe.scopeLeakedEnvironment(of: r, in: &settings), [], "nothing left to move")
+ // A value the owner changed by hand is not the recipe's and stays where they put it.
+ var edited = BottleSettings(name: "t", engineID: "e")
+ edited.environment = ["MVK_SHADOW_IMPORT": "0"]
+ XCTAssertEqual(Recipe.scopeLeakedEnvironment(of: r, in: &edited), [])
+ XCTAssertEqual(edited.environment["MVK_SHADOW_IMPORT"], "0")
+ // A launcher's variable never moves.
+ var l = BottleSettings(name: "t", engineID: "e")
+ l.environment = ["DXMT_ALLOW_CROSS_PROCESS_SWAPCHAIN": "1"]
+ XCTAssertEqual(Recipe.scopeLeakedEnvironment(of: try recipe(launcher), in: &l), [])
+ }
+
+ func testSteamRestartsWhenTheClientCarriesAnotherGamesVariable() {
+ var settings = BottleSettings(name: "t", engineID: "e")
+ settings.gameEnvironment["the-sims-legacy-collection"] = ["MVK_SHADOW_IMPORT": "1"]
+ XCTAssertEqual(settings.customEnvironmentKeys, ["MVK_SHADOW_IMPORT"])
+ let base = ["WINEDLLPATH_PREPEND": "/r/dxvk/wine", "WINEMSYNC": "1", "WINEESYNC": "0"]
+ // The client was started for the Sims; the next game does not set the variable.
+ let live = base.merging(["MVK_SHADOW_IMPORT": "1"]) { $1 }
+ let why = SteamRestart.reason(live: live, wanted: base, wantedRenderer: "dxvk", custom: settings.customEnvironmentKeys)
+ XCTAssertEqual(why, "it runs with MVK_SHADOW_IMPORT=1 and the game does not set it")
+ // The other way round: a client started for another game, and now the Sims want it.
+ let wanted = base.merging(["MVK_SHADOW_IMPORT": "1"]) { $1 }
+ XCTAssertEqual(SteamRestart.reason(live: base, wanted: wanted, wantedRenderer: "dxvk", custom: settings.customEnvironmentKeys + ["MVK_SHADOW_IMPORT"]), // named twice, reported once
+ "it runs without MVK_SHADOW_IMPORT=1")
+ // Same variables both sides: nothing to restart for.
+ XCTAssertNil(SteamRestart.reason(live: live, wanted: wanted, wantedRenderer: "dxvk", custom: settings.customEnvironmentKeys))
+ }
+}