Skip to content

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

56.7 KB
Raw Blame
import Foundation

/// A recipe is declarative data (JSON, CC0 in gin-db) describing how to install and configure
/// a launcher or game inside a bottle. Steps run in order; each is idempotent where possible.
public struct Recipe: Codable, Sendable, Identifiable {
    public enum Kind: String, Codable, Sendable { case launcher, game, tweak }

    public enum Step: Codable, Sendable {
        /// Download a file (verified if sha256 given) and run it inside the bottle.
        /// `slow` is a user-facing expectation for long steps ("takes 20-40 min, can look idle");
        /// the app shows it while the step runs so nobody has to guess whether it froze (#31).
        case installer(url: URL, sha256: String?, arguments: [String], label: String, slow: String?, okExitCodes: [Int32]?)
        /// `wine reg add`.
        case registry(key: String, name: String, type: String, data: String)
        /// Run winetricks verbs (unattended). `slow` as on `installer`.
        case winetricks(verbs: [String], slow: String?)
        /// Set a persistent environment variable on the bottle.
        case environment(name: String, value: String)
        /// Set the bottle's renderer.
        case renderer(Renderer)
        /// Set the bottle's synchronization mode (none | esync | msync).
        case sync(SyncMode)
        /// Set the prefix's Windows version. Needed because winetricks verbs like dotnet48
        /// step the version during install and leave it on win7 — which broke Steam
        /// (deprecation banner) and AC for every dotnet48 user until restored.
        case winver(WindowsVersion)
        /// Write a text file inside drive_c.
        case file(path: String, contents: String)
        /// Copies one file from the engine into the environment: `from` is relative to the
        /// engine's directory and must stay inside it, `to` is relative to `drive_c`. A DLL put
        /// beside a game's executable is what its loader takes first, so this gives one game a
        /// Direct3D of its own (wined3d's d3d9 for legacy CS:GO) while the environment, and the
        /// Steam client in it, keep their graphics mode.
        /// With `asNative`, the copy loses Wine's builtin marker, so a per-application load order
        /// of `n,b` (a `registry` step under `AppDefaults\<exe>\DllOverrides`) makes the game's
        /// loader take it. A Direct3D imported by name from a DLL in the game's own `bin` folder
        /// is found there and nowhere else (legacy CS:GO's shaderapidx9.dll).
        case copy(from: String, to: String, asNative: Bool)
        /// Add a pinned program to the bottle.
        case pin(Pin)
        /// Free-text instruction the UI surfaces to the user after install.
        case note(String)
        /// A WINEDLLOVERRIDES entry the bottle keeps, e.g. "amd_ags_x64=" to disable AMD's AGS
        /// library. Appended to whatever the renderer sets, and mirrored into the prefix registry
        /// so it also reaches a game launched by an already-running Steam. This is how a game's
        /// need to avoid a vendor library ships as data instead of app code.
        case dllOverride(String)
        /// The environment's frame cap, the same setting as in its Graphics settings, set only where the player has
        /// none: a game whose even pacing depends on a cap gets it on its first start and keeps the player's choice.
        case frameCap(Int)
        /// Per-app DXVK options ("csgo.exe" → dxvk.enableAsync=False…), stored on the bottle
        /// and rendered into its dxvk.conf at every DXVK launch. This is how game-specific
        /// DXVK knowledge ships as data instead of app code.
        case dxvkConfig(exe: String, options: [String: String])

        private enum CodingKeys: String, CodingKey { case type, url, sha256, arguments, label, slow, okExitCodes, key, name, value, valueType, data, verbs, renderer, sync, winver, path, contents, from, to, asNative, pin, text, exe, options }

        public init(from decoder: Decoder) throws {
            let c = try decoder.container(keyedBy: CodingKeys.self)
            switch try c.decode(String.self, forKey: .type) {
            case "installer":
                self = .installer(url: try c.decode(URL.self, forKey: .url),
                                  sha256: try c.decodeIfPresent(String.self, forKey: .sha256),
                                  arguments: try c.decodeIfPresent([String].self, forKey: .arguments) ?? [],
                                  label: try c.decodeIfPresent(String.self, forKey: .label) ?? "installer",
                                  slow: try c.decodeIfPresent(String.self, forKey: .slow),
                                  okExitCodes: try c.decodeIfPresent([Int32].self, forKey: .okExitCodes))
            case "registry":
                self = .registry(key: try c.decode(String.self, forKey: .key), name: try c.decode(String.self, forKey: .name),
                                 type: try c.decodeIfPresent(String.self, forKey: .valueType) ?? "REG_DWORD", data: try c.decode(String.self, forKey: .data))
            case "winetricks": self = .winetricks(verbs: try c.decode([String].self, forKey: .verbs),
                                                  slow: try c.decodeIfPresent(String.self, forKey: .slow))
            case "environment": self = .environment(name: try c.decode(String.self, forKey: .name), value: try c.decode(String.self, forKey: .value))
            case "renderer": self = .renderer(try c.decode(Renderer.self, forKey: .renderer))
            case "sync": self = .sync(try c.decode(SyncMode.self, forKey: .sync))
            case "winver": self = .winver(try c.decode(WindowsVersion.self, forKey: .winver))
            case "file": self = .file(path: try c.decode(String.self, forKey: .path), contents: try c.decode(String.self, forKey: .contents))
            case "copy": self = .copy(from: try c.decode(String.self, forKey: .from), to: try c.decode(String.self, forKey: .to),
                                      asNative: try c.decodeIfPresent(Bool.self, forKey: .asNative) ?? false)
            case "pin": self = .pin(try c.decode(Pin.self, forKey: .pin))
            case "note": self = .note(try c.decode(String.self, forKey: .text))
            case "dlloverride": self = .dllOverride(try c.decode(String.self, forKey: .value))
            case "framecap": self = .frameCap(try c.decode(Int.self, forKey: .value))
            case "dxvkconfig": self = .dxvkConfig(exe: try c.decode(String.self, forKey: .exe),
                                                  options: try c.decode([String: String].self, forKey: .options))
            case let other: throw HighballError.invalid("unknown recipe step type '\(other)'")
            }
        }

        public func encode(to encoder: Encoder) throws {
            var c = encoder.container(keyedBy: CodingKeys.self)
            switch self {
            case let .installer(url, sha256, arguments, label, slow, okExitCodes):
                try c.encode("installer", forKey: .type); try c.encode(url, forKey: .url)
                try c.encodeIfPresent(sha256, forKey: .sha256); try c.encode(arguments, forKey: .arguments); try c.encode(label, forKey: .label)
                try c.encodeIfPresent(slow, forKey: .slow)
                try c.encodeIfPresent(okExitCodes, forKey: .okExitCodes)
            case let .registry(key, name, type, data):
                try c.encode("registry", forKey: .type); try c.encode(key, forKey: .key); try c.encode(name, forKey: .name)
                try c.encode(type, forKey: .valueType); try c.encode(data, forKey: .data)
            case let .winetricks(verbs, slow):
                try c.encode("winetricks", forKey: .type); try c.encode(verbs, forKey: .verbs)
                try c.encodeIfPresent(slow, forKey: .slow)
            case let .environment(name, value): try c.encode("environment", forKey: .type); try c.encode(name, forKey: .name); try c.encode(value, forKey: .value)
            case let .renderer(r): try c.encode("renderer", forKey: .type); try c.encode(r, forKey: .renderer)
            case let .sync(m): try c.encode("sync", forKey: .type); try c.encode(m, forKey: .sync)
            case let .winver(v): try c.encode("winver", forKey: .type); try c.encode(v, forKey: .winver)
            case let .file(path, contents): try c.encode("file", forKey: .type); try c.encode(path, forKey: .path); try c.encode(contents, forKey: .contents)
            case let .copy(from, to, asNative):
                try c.encode("copy", forKey: .type); try c.encode(from, forKey: .from); try c.encode(to, forKey: .to)
                if asNative { try c.encode(true, forKey: .asNative) }
            case let .pin(p): try c.encode("pin", forKey: .type); try c.encode(p, forKey: .pin)
            case let .note(t): try c.encode("note", forKey: .type); try c.encode(t, forKey: .text)
            case let .dllOverride(v): try c.encode("dlloverride", forKey: .type); try c.encode(v, forKey: .value)
            case let .frameCap(n): try c.encode("framecap", forKey: .type); try c.encode(n, forKey: .value)
            case let .dxvkConfig(exe, options):
                try c.encode("dxvkconfig", forKey: .type); try c.encode(exe, forKey: .exe)
                try c.encode(options, forKey: .options)
            }
        }

        /// Short human description for progress display ("Step 2 of 3 — Battle.net-Setup").
        public var progressLabel: String? {
            switch self {
            case let .installer(_, _, _, label, _, _): return label
            case let .winetricks(verbs, _): return verbs.joined(separator: " ")
            case .registry: return nil
            case .environment, .renderer, .sync, .winver, .file, .copy, .pin, .note, .dxvkConfig, .dllOverride, .frameCap: return nil
            }
        }

        /// The step's slow-expectation text, if the recipe declared one.
        public var slowHint: String? {
            switch self {
            case let .installer(_, _, _, _, slow, _): return slow
            case let .winetricks(_, slow): return slow
            default: return nil
            }
        }

        /// Exit statuses that count as success for this step.
        ///
        /// Windows installers report success in more than one way, and the number Swift sees is
        /// twice-truncated (WiX Burn returns HRESULT_CODE, then POSIX keeps 8 bits): 3010
        /// "restart required" arrives as 194 and 1641 "restart initiated" as 105 — both are
        /// documented by Microsoft as success — and 1638 "a newer version is already installed"
        /// arrives as 102, which for a step whose job is to install that runtime means the goal
        /// is already met. Accepting these by default is deliberate: it is generic Windows
        /// knowledge, not per-app knowledge, so no recipe has to know it (issue #36, where the
        /// strict `== 0` guard aborted the VC++ recipe at step 1 of 14 and left the DLL
        /// overrides unapplied). A recipe can still widen the set for an installer with its own
        /// conventions via `okExitCodes`.
        public func accepts(exitStatus: Int32) -> Bool {
            guard case let .installer(_, _, _, _, _, okExitCodes) = self else { return exitStatus == 0 }
            return exitStatus == 0 || [102, 194, 105].contains(exitStatus)
                || (okExitCodes ?? []).contains(exitStatus)
        }

        /// True when the step is safe to run silently at Play time: touches no wine process
        /// (registry/winver spawn wine and can die on the msync mismatch, issue #32) and
        /// takes no meaningful time (installer/winetricks can take 20-40 minutes).
        public var isAutoApplicable: Bool {
            switch self {
            case .file, .copy, .renderer, .sync, .environment, .pin, .note, .dxvkConfig, .dllOverride, .frameCap: return true
            case .installer, .winetricks, .registry, .winver: return false
            }
        }
    }

    /// True when every step can run silently at Play time — the app then applies the recipe
    /// as part of pressing Play ("make it work like the db verified it"), no clicks needed.
    /// Recipes with heavy or wine-touching steps get an honest prompt instead.
    public var isAutoApplicable: Bool { steps.allSatisfy(\.isAutoApplicable) }

    /// False when a file a `copy` step placed is gone: the game was reinstalled or Steam put its
    /// files back, and the environment still records the recipe as applied. Play then treats the
    /// recipe as not applied, so the copy comes back before the launch (2026-09-11: CS:GO Legacy
    /// reinstalled without its d3d9.dll would have launched on the wrong Direct3D).
    /// `steamGames` are the environment's Steam games, so a copy placed in a game's folder on
    /// another library counts (see `target(of:driveC:steamGames:)`).
    public func artifactsPresent(driveC: URL, steamGames: [SteamGame] = []) -> Bool {
        steps.allSatisfy { step in
            if case let .copy(_, to, _) = step {
                return FileManager.default.fileExists(atPath: Self.target(of: to, driveC: driveC, steamGames: steamGames).path)
            }
            return true
        }
    }

    /// Where a `file` or `copy` step's file goes. Steps name it under drive C, and a step for a
    /// Steam game names the game's folder in the environment's own library
    /// ("Program Files (x86)/Steam/steamapps/common/Portal 2/portal2/cfg/autoexec.cfg"). Steam
    /// keeps other library folders too, often on an external disk (0.10.13 gave those a drive
    /// letter), and a game installed there never got its fix: the file went into a folder on C
    /// the game never reads. When the game's Steam manifest puts it in another library, the file
    /// goes into the game's folder there. The manifest decides, not a folder on C: the old
    /// behaviour left one behind for every game it missed. Every other path, and every game in
    /// the environment's own library, lands where the step says, as before.
    public static func target(of path: String, driveC: URL, steamGames: [SteamGame]) -> URL {
        // ${user} is the Mac's short user name, the name Wine gives the folder under drive_c/users: a game's
        // settings live in there (Forza Horizon 6's, in AppData/Local).
        let path = path.replacingOccurrences(of: "${user}", with: NSUserName())
        let standard = driveC.appending(path: path)
        let steam = "Program Files (x86)/Steam", common = "\(steam)/steamapps/common/"
        guard path.hasPrefix(common) else { return standard }
        let parts = path.dropFirst(common.count).split(separator: "/", maxSplits: 1).map(String.init)
        guard parts.count == 2, parts[0] != "..", !parts[1].split(separator: "/").contains(where: { $0 == ".." }),
              let game = steamGames.first(where: { $0.installdir.caseInsensitiveCompare(parts[0]) == .orderedSame }),
              let library = game.libraryRoot, let folder = game.installFolder,
              library.standardizedFileURL.path != driveC.appending(path: steam).standardizedFileURL.path,
              FileManager.default.fileExists(atPath: folder.path) else { return standard }
        return folder.appending(path: parts[1])
    }

    /// True when applying the recipe changes what a launch inherits: the renderer, the sync
    /// mode or an environment variable. A Steam client that is already running keeps the
    /// environment it started with (issues #22/#25), so a Play that auto-applied such a recipe
    /// must stop the bottle first or the game it launches never sees the change. The Sims
    /// recipe's MVK_SHADOW_IMPORT=1 is the case that made this visible.
    public var changesLaunchEnvironment: Bool {
        steps.contains { step in
            switch step {
            case .renderer, .sync, .environment, .frameCap: return true
            default: return false
            }
        }
    }

    /// True when a step writes a Windows driver's or service's settings, a registry value under
    /// HKLM\System\CurrentControlSet\Services. A driver reads them when it starts, and Wine starts its drivers
    /// with the environment: the controller driver read winebus's device options once, when Steam brought the
    /// environment up, so stopping the Steam client alone left a Honeycomb Bravo a gamepad (highball#397).
    public var changesDriverSettings: Bool {
        steps.contains { if case let .registry(key, _, _, _) = $0 { return Self.isServiceKey(key) } else { return false } }
    }

    static func isServiceKey(_ key: String) -> Bool {
        let k = key.lowercased().replacingOccurrences(of: "/", with: "\\")
        return [#"hklm\system\currentcontrolset\services\"#, #"hkey_local_machine\system\currentcontrolset\services\"#]
            .contains { k.hasPrefix($0) }
    }

    /// The tweaks this recipe requires that an environment has not applied, in order. A recipe can gain a
    /// dependency after environments applied it, and Play applies a recipe once, so without this the
    /// environments that played the game before never got it (Microsoft Flight Simulator 2024's flight controls
    /// tweak, highball#397). Launchers in `requires` say where the game comes from and are not applied.
    public func missingRequiredTweaks(applied: [String], resolve: (String) -> Recipe?) -> [Recipe] {
        (requires ?? []).filter { !applied.contains($0) }.compactMap { resolve($0) }.filter { $0.kind == .tweak }
    }

    public struct KnownIssue: Codable, Sendable {
        public var symptom: String
        public var cause: String?
        public var fix: String?
    }

    /// A recipe the current engine cannot deliver: shown but not runnable, with the reason
    /// and an upstream tracking link. Better one honest disabled tile than an installer
    /// that hangs forever (the Rockstar case).
    public struct Blocked: Codable, Sendable {
        public var reason: String
        public var tracking: String?
    }

    /// Partially works: installable and worth trying, but with known issues. Unlike `blocked`,
    /// it does NOT stop `apply()` — the UI just flags it so the launcher grid stops presenting it
    /// as a clean "Install".
    public struct Flaky: Codable, Sendable {
        public var reason: String
    }

    public struct Verification: Codable, Sendable {
        public var date: String
        public var engine: String
        public var macos: String
        public var chip: String
        public var result: String

        public init(date: String, engine: String, macos: String, chip: String, result: String) {
            self.date = date; self.engine = engine; self.macos = macos; self.chip = chip; self.result = result
        }

        /// A recipe's lastVerified is an object, a row's is a date string. A recipe written with the
        /// row's shape must not vanish from the app: 0.9.8 shipped the Metaphor recipe as a bare
        /// date and every bundled load of it failed silently, so Play never moved the environment
        /// to the engine the recipe asks for (2026-09-12). A bare string is taken as the date.
        public init(from decoder: Decoder) throws {
            if let single = try? decoder.singleValueContainer(), let date = try? single.decode(String.self) {
                self.init(date: date, engine: "", macos: "", chip: "", result: "")
                return
            }
            let c = try decoder.container(keyedBy: CodingKeys.self)
            self.init(date: try c.decode(String.self, forKey: .date),
                      engine: try c.decodeIfPresent(String.self, forKey: .engine) ?? "",
                      macos: try c.decodeIfPresent(String.self, forKey: .macos) ?? "",
                      chip: try c.decodeIfPresent(String.self, forKey: .chip) ?? "",
                      result: try c.decodeIfPresent(String.self, forKey: .result) ?? "")
        }
    }

    public var id: String
    public var kind: Kind
    public var title: String
    public var requires: [String]?
    public var renderer: Renderer?
    /// The engine this recipe needs, by manifest id (the EA app needs the Wine 11 tree, #60).
    /// Highball offers that engine before applying the recipe to an environment on another Wine.
    public var engine: String?
    /// The memory a Mac needs for this game on the recipe's engine, in GB (Microsoft Flight Simulator 2024 holds
    /// about 25 GB on the native arm64 line). Data: Play's engine and preview asks say so on a Mac with less, before
    /// a download that could not run there. nil when the recipe names no floor.
    public var minMemoryGB: Int?
    public var steps: [Step]

    /// The recipe's memory floor and this Mac's memory in GB when the Mac is under it, nil otherwise.
    public func memoryShortfall(memoryMB: Int) -> (needGB: Int, haveGB: Int)? {
        guard let need = minMemoryGB, memoryMB < need * 1024 else { return nil }
        return (need, Int((Double(memoryMB) / 1024).rounded()))
    }
    public var knownIssues: [KnownIssue]?
    public var lastVerified: Verification?
    public var blocked: Blocked?
    /// True for a fix Play must never apply on its own: it helps some Macs and breaks others,
    /// so the page offers it under Advanced and the notes say when to try it. The first one is
    /// RaceRoom's newer Direct3D 9 layer (highball-db#60): it rendered the game for one reporter
    /// and drew it in grayscale for another. An opt-in recipe still counts as the game's fix
    /// for the page's wording and for artifact checks once applied.
    public var optIn: Bool?
    public var isOptIn: Bool { optIn ?? false }

    /// A second way to run this game, on a preview engine the player takes by choice, beside the recipe's own: Forza
    /// Horizon 6 plays on D3DMetal 4 with its copy protection's hitch and on the native arm64 line without it, at a
    /// lower frame rate, and neither is the better one for everybody. An environment on the route's line goes by the
    /// route (`routed(onEngine:)`), every other by the recipe as before, so nothing changes for a player who stays.
    public struct PreviewRoute: Codable, Sendable {
        public var engine: String
        public var renderer: Renderer?
        public var minMemoryGB: Int?
        public var steps: [Step]
        public var knownIssues: [KnownIssue]?
        public var lastVerified: Verification?
        /// What the route changes for the player, added to Play's ask.
        public var note: String?
        /// What the game page's verdict says for this route, the row's own fields being its other route's.
        public var verified: GameDBEntry.VerifiedOn?
    }
    public var previewRoute: PreviewRoute?
    /// Set on the recipe `route` makes: `note` is the route's, and applying it makes the mode the environment's own.
    public var previewRouteNote: String?
    public var isPreviewRoute: Bool { previewRouteNote != nil }
    /// The route's `verified`, on the recipe `route` makes.
    public var previewRouteVerified: GameDBEntry.VerifiedOn?

    /// This recipe as its preview route: the same game and id, so what an environment records for it (the applied list,
    /// the variables scoped to the game) stays where everything looks for it, with the route's engine, mode and steps.
    public var route: Recipe? {
        guard let r = previewRoute else { return nil }
        var copy = self
        copy.engine = r.engine
        copy.renderer = r.renderer ?? renderer
        copy.minMemoryGB = r.minMemoryGB
        copy.steps = r.steps
        copy.knownIssues = r.knownIssues ?? knownIssues
        copy.lastVerified = r.lastVerified ?? lastVerified
        copy.previewRoute = nil
        copy.previewRouteNote = r.note ?? ""
        copy.previewRouteVerified = r.verified
        return copy
    }

    /// The recipe an environment on `engineID` goes by: the route on the route's line, the recipe itself on any other.
    public func routed(onEngine engineID: String?) -> Recipe {
        guard let route, let pin = route.engine, let engineID, let line = EngineManifest.line(of: engineID),
              line == EngineManifest.line(of: pin) else { return self }
        return route
    }
    /// What an installed runtime leaves behind, so the Dependencies panel can tell "installed"
    /// from "our recipe ran": a file under drive_c, or a registry value in system.reg (exact
    /// match or a minimum for dword values). Any one marker satisfied means installed. Data, so
    /// a runtime a game's own prerequisite installed shows as installed too (plan Phase 0.3).
    public var installedMarkers: [InstalledMarker]?

    public struct InstalledMarker: Codable, Sendable {
        /// Path under drive_c, e.g. "windows/system32/vcruntime140.dll".
        public var file: String?
        /// Registry key under HKLM as written in system.reg, e.g.
        /// "Software\\Microsoft\\VisualStudio\\14.0\\VC\\Runtimes\\x64".
        public var registry: String?
        public var value: String?
        /// Exact raw value text, e.g. "dword:00000001".
        public var equals: String?
        /// Minimum for a dword value, decimal.
        public var min: Int?
    }

    /// A tweak made only of registry values (and notes) can be taken back off: deleting each value it
    /// set returns Wine to its own default for it. "Controllers through SDL" asked for it, since a
    /// DualSense gives no input in some games with it on and the app could only install it.
    public var isRemovable: Bool {
        kind == .tweak && !registryValues.isEmpty && steps.allSatisfy {
            switch $0 { case .registry, .note: return true; default: return false }
        }
    }

    /// The registry values this recipe sets, key and name.
    public var registryValues: [(key: String, name: String)] {
        steps.compactMap { if case let .registry(key, name, _, _) = $0 { return (key, name) } else { return nil } }
    }

    /// True when any marker is present in the bottle. Recipes without markers report false; the
    /// caller still knows whether the recipe ran.
    public func isInstalled(in bottle: Bottle) -> Bool {
        guard let markers = installedMarkers, !markers.isEmpty else { return false }
        lazy var systemReg: String = (try? String(contentsOf: bottle.url.appending(path: "system.reg"), encoding: .utf8)) ?? ""
        for m in markers {
            if let f = m.file, FileManager.default.fileExists(atPath: bottle.driveC.appending(path: f).path) { return true }
            if let key = m.registry, let name = m.value, let raw = RegistryText.value(in: systemReg, key: key, name: name) {
                if let eq = m.equals { if raw.lowercased() == eq.lowercased() { return true } else { continue } }
                if let min = m.min, let n = RegistryText.dword(raw), n >= min { return true }
                if m.equals == nil, m.min == nil { return true }
            }
        }
        return false
    }
    public var flaky: Flaky?

    public static func load(from url: URL) throws -> Recipe {
        try JSONDecoder.highball.decode(Recipe.self, from: Data(contentsOf: url))
    }
}

/// Applies a recipe to a bottle.
public struct RecipeRunner: Sendable {
    public let paths: HighballPaths
    public let engine: InstalledEngine
    public var bottle: Bottle
    public let store: EngineStore

    public init(paths: HighballPaths = HighballPaths(), engine: InstalledEngine, bottle: Bottle) {
        self.paths = paths; self.engine = engine; self.bottle = bottle; self.store = EngineStore(paths: paths)
    }

    /// The file a `copy` step reads, or nil when `from` is absolute, climbs out of the engine
    /// with `..`, or does not exist. Recipes are data from the database, so a step must not be
    /// able to read anything but the engine it was written for.
    /// Wine stamps its builtin PE DLLs with "Wine builtin DLL" at offset 0x40; blanking it makes
    /// the loader treat the file as native, which is what a per-application `n,b` order selects.
    static func withoutBuiltinMarker(_ data: Data) -> Data {
        let marker = Data("Wine builtin DLL\0".utf8)
        guard data.count >= 0x40 + marker.count, data[0x40..<0x40 + marker.count] == marker else { return data }
        var out = data; out.replaceSubrange(0x40..<0x40 + marker.count, with: Data(count: marker.count)); return out
    }

    public static func copySource(engineRoot: URL, _ from: String) -> URL? {
        guard !from.hasPrefix("/"), !from.split(separator: "/").contains("..") else { return nil }
        let url = engineRoot.appending(path: from).standardizedFileURL
        guard url.path.hasPrefix(engineRoot.standardizedFileURL.path + "/") else { return nil }
        var isDir: ObjCBool = false
        guard FileManager.default.fileExists(atPath: url.path, isDirectory: &isDir), !isDir.boolValue else { return nil }
        return url
    }

    /// The renderer a recipe may set, or nil when the user's explicit choice must stand (#29) or
    /// the bottle's engine cannot run it (#61: a fix recipe set D3DMetal on a bottle whose engine
    /// had no licence accepted for it, and every later launch in that bottle died before Wine).
    public static func rendererToApply(recipeRenderer: Renderer?, settings: BottleSettings, available: Bool = true) -> Renderer? {
        guard let r = recipeRenderer, !settings.rendererExplicit, available else { return nil }
        return r
    }

    /// The processes an installer left behind: those that appeared during the step, and only
    /// when the environment was idle before it. A busy environment gets none, because a new
    /// pid there may belong to the running program, not the installer. Plumbing that appeared
    /// (the server and the Windows services the installer's own launch booted on a cold
    /// prefix) is never a leftover: ending those by signal is what printed "wineserver crashed"
    /// in the middle of the VC++ install on nightly-e2e (#160); the environment reset after
    /// the step stops them properly. Pure, for the tests.
    public static func installerLeftovers(before: Set<pid_t>, after: [pid_t], wasIdle: Bool,
                                          isPlumbing: (pid_t) -> Bool = { _ in false }) -> [pid_t] {
        guard wasIdle else { return [] }
        return after.filter { !before.contains($0) && !isPlumbing($0) }
    }

    /// The variables a winetricks step adds on top of the environment's own. WINE_BIN,
    /// WINESERVER_BIN and WINE_BINDIR are winetricks' overrides for setups where its binary
    /// detection fails; without them dotnet48 and friends abort on this engine (2026-08-25,
    /// highball#16). HB_AUDIOBUF=0 keeps the audio buffer library out: winetricks runs under
    /// /bin/bash and Apple's own tools, which are arm64e and cannot load a library built for
    /// x86_64 and arm64, and where DYLD variables reach them (SIP off, the hosted CI runner)
    /// dyld ends the process on the spot, which failed every dotnet48 install on the nightly
    /// (highball#248). A Mac with SIP on drops the variable before bash sees it, which is why
    /// the app never showed it. No installer needs the audio cap.
    public static func winetricksExtras(engine: InstalledEngine) -> [String: String] {
        [
            "WINE": engine.wineBinary.path,
            "WINESERVER": engine.wineserverBinary.path,
            "WINE_BIN": engine.wineBinary.path,
            "WINESERVER_BIN": engine.wineserverBinary.path,
            "WINE_BINDIR": engine.wineBinary.deletingLastPathComponent().path,
            "HB_AUDIOBUF": "0",
        ]
    }

    /// How long an installer's helpers get to finish on their own before they count as
    /// leftovers. A bootstrapper's parent exits while its engine keeps installing: the VC++
    /// redistributable returned 0 after 8 s with its Burn engine still writing the x64 runtime,
    /// and ending it then left the runtime half installed (nightly-e2e 2026-09-19, #160). The
    /// leftovers this exists for, Battle.net's Agent and Rockstar's service, never exit, so
    /// they are ended once the minute is up.
    public static let installerGrace: TimeInterval = 60

    /// Runs every step. Returns the notes the UI should show afterwards.
    public mutating func apply(_ recipe: Recipe,
                               resolve: (@Sendable (String) -> Recipe?)? = nil,
                               log: (@Sendable (String) -> Void)? = nil) async throws -> [String] {
        if let b = recipe.blocked {
            var msg = "'\(recipe.title)' is blocked on this engine: \(b.reason)"
            if let t = b.tracking { msg += " Tracked at \(t)" }
            throw HighballError.invalid(msg)
        }
        var notes: [String] = []
        // Dependencies first. A recipe that declares requires: ["steam", "dotnet48"] means the game
        // does not work without .NET, and until 2026-09-10 that field was read by nothing: pressing
        // Play launched Assetto Corsa without .NET and it died with "Configuration system failed to
        // initialize", while the recipe's only mention of it was a note telling the owner to go and
        // install it themselves. Only tweaks are applied here; a launcher in `requires` is a
        // statement about where the game comes from, not something to install on its behalf.
        for id in recipe.requires ?? [] where !bottle.settings.recipes.contains(id) {
            guard let dep = resolve?(id), dep.kind == .tweak else { continue }
            log?("[\(recipe.id)] needs \(dep.id) first")
            notes += try await apply(dep, resolve: resolve, log: log)
        }
        // A recipe's renderer is a default, never an override: an explicit user choice wins
        // (issue #29 — the Steam recipe silently reset a d3dmetal bottle to dxmt).
        if let r = recipe.renderer {
            let why = r.unavailableReason(in: engine)
            if let applied = Self.rendererToApply(recipeRenderer: r, settings: bottle.settings, available: why == nil) {
                bottle.settings.renderer = applied
            } else if r.availability(in: engine) == .notShipped {
                // A recipe written for every engine (Steam's suggests DXMT) on an engine that has
                // no such mode at all (the arm64 line): nothing to fix, so no advice to switch engines.
                notes.append("Kept this bottle's renderer (\(bottle.settings.renderer.rawValue)); the recipe suggests \(r.rawValue), which engine \(engine.id) does not have.")
            } else if let why {
                notes.append("Kept this bottle's renderer (\(bottle.settings.renderer.rawValue)); the recipe suggests \(r.rawValue): \(why)")
            } else {
                notes.append("Kept this bottle's renderer (\(bottle.settings.renderer.rawValue)); the recipe suggests \(r.rawValue).")
            }
        }
        // A route's mode is the environment's own, or the row's mode for the game's other route would replace it at
        // every launch (D3DMetal, which the native arm64 line does not have).
        if recipe.isPreviewRoute { bottle.settings.rendererExplicit = true }
        // Read once, for the file and copy steps of a game installed in another Steam library.
        let steamGames = recipe.steps.contains {
            switch $0 { case .file, .copy: return true; default: return false }
        } ? SteamLibrary.games(in: bottle) : []
        for (i, step) in recipe.steps.enumerated() {
            // The app parses these two lines into its progress display (#31): the step line
            // becomes the stage, the hint line the "this is slow, don't worry" text under it.
            if let desc = step.progressLabel {
                log?("[\(recipe.id)] step \(i + 1)/\(recipe.steps.count) — \(desc)")
            } else {
                log?("[\(recipe.id)] step \(i + 1)/\(recipe.steps.count)")
            }
            if let slow = step.slowHint { log?("[\(recipe.id)] hint: \(slow)") }
            let runner = WineRunner(paths: paths, engine: engine, bottle: bottle)
            switch step {
            case let .installer(url, sha256, arguments, label, _, _):
                let component = EngineManifest.Component(kind: "installer", url: url, sha256: sha256 ?? "", size: nil, license: nil, optional: nil, acceptance: nil, extract: nil, note: nil, version: nil)
                let file: URL
                if sha256 != nil {
                    file = try await store.download(component, name: label)
                } else {
                    file = try await downloadUnverified(url)
                }
                // A Mac symlink an older Highball made beside a Windows link stops an installer that
                // repairs or replaces the link (the EA app's repair: "Failed to remove reparse point",
                // error 145, highball-db#318). Wine follows its own links, so they go.
                for link in WineReparsePoint.dematerializeTree(under: bottle.driveC, driveC: bottle.driveC) {
                    log?("[\(recipe.id)] removed the Mac link beside \(link.lastPathComponent), Wine follows the Windows link itself")
                }
                let isMSI = file.pathExtension.lowercased() == "msi" || url.lastPathComponent.lowercased().contains(".msi")
                let wineArgs = isMSI ? ["msiexec", "/i", file.path, "/qn"] + arguments : [file.path] + arguments
                let before = Set(ProcessTable.processes(ofPrefix: bottle.url))
                let wasIdle = ProcessTable.isIdle(prefix: bottle.url)
                let result = try await runner.run(wineArgs, renderer: .wined3d, label: label, onOutput: log)
                // An installer must not leave processes behind. Battle.net's setup leaves its
                // Agent running and Rockstar's starts its service, both under the setup-time
                // environment (no renderer overlay, the sync mode the first boot had), and the
                // first Play then hands the real client to that agent, which spawns it with the
                // stale stack (measured 2026-09-18: the Battle.net client ran with WINEMSYNC=1
                // and no WINEDLLPATH_PREPEND under a DXMT pin). Ending them here, and the server
                // with them when nothing else runs, makes the next launch a cold start with the
                // recipe's final settings.
                // Only when nothing a person started was running before the installer: a pid that
                // is new since then can otherwise be a running game's own child (a launcher it
                // spawned, a crash handler), and a pid difference cannot tell the two apart. In
                // that case the leftovers stay, and the note says so.
                let prefix = bottle.url
                let currentLeftovers = {
                    Self.installerLeftovers(before: before, after: ProcessTable.processes(ofPrefix: prefix), wasIdle: wasIdle,
                                            isPlumbing: { ProcessTable.isPlumbing($0, prefix: prefix) })
                }
                var leftovers = currentLeftovers()
                if !leftovers.isEmpty {
                    // Helpers still finishing the install get a grace period first (see installerGrace).
                    let started = Date()
                    let deadline = started.addingTimeInterval(Self.installerGrace)
                    while !leftovers.isEmpty, Date() < deadline {
                        try await Task.sleep(nanoseconds: 1_000_000_000)
                        leftovers = currentLeftovers()
                    }
                    let waited = Int(Date().timeIntervalSince(started))
                    if waited > 0 { log?("[\(recipe.id)] waited \(waited) s for the installer's helpers to finish") }
                }
                if !leftovers.isEmpty {
                    ProcessTable.terminate(leftovers)
                    log?("[\(recipe.id)] ended \(leftovers.count) process\(leftovers.count == 1 ? "" : "es") the installer left running")
                } else if !wasIdle {
                    log?("[\(recipe.id)] a program was running before the installer, so anything it left running stays; stop the environment before the next launch if it misbehaves")
                }
                if wasIdle, ProcessTable.isIdle(prefix: bottle.url), ProcessTable.liveServer(forPrefix: bottle.url) != nil {
                    _ = try? runner.kill()
                    log?("[\(recipe.id)] stopped the environment so the next launch starts it with the recipe's settings")
                }
                guard step.accepts(exitStatus: result.exitStatus) else {
                    throw HighballError.processFailed(command: label, status: result.exitStatus,
                                                      output: WineRunner.exitCodeNote(for: result.exitStatus).isEmpty
                                                        ? "see \(result.log.path)"
                                                        : "\(WineRunner.exitCodeNote(for: result.exitStatus))\nsee \(result.log.path)")
                }
                if result.exitStatus != 0 {
                    log?("[\(recipe.id)] \(label) exited with \(result.exitStatus)\(WineRunner.exitCodeNote(for: result.exitStatus)) — treating as done")
                }
            case let .registry(key, name, type, data):
                try await runner.regAdd(key: key, name: name, type: type, data: data)
            case let .winetricks(verbs, _):
                guard let wt = engine.winetricks else { throw HighballError.missing("winetricks in engine \(engine.id)") }
                // winetricks ends its verbs with `wineserver -w`, which waits for every Windows program in the
                // environment to end, so with a Steam window open the step never finished once it could start
                // (measured on the M4, 2026-10-26: `winetricks win10` beside a running program still waited after
                // 90 s, 28 s alone). The Steam client is stopped the way Play stops it, then the environment when
                // only Wine's own processes are left, and a program the owner started stops the step with a
                // message instead of a wait without end.
                if ProcessTable.liveServer(forPrefix: bottle.url) != nil {
                    try? await runner.stopSteam()
                    // Steam's web helpers can outlive the client by a moment.
                    for _ in 0..<10 where !ProcessTable.isIdle(prefix: bottle.url) { try await Task.sleep(for: .milliseconds(500)) }
                    guard ProcessTable.isIdle(prefix: bottle.url) else {
                        throw HighballError.failed("A program is still running in \(bottle.name), and Windows components install only once it has closed. Quit it, or use Stop all processes, then try again.")
                    }
                    _ = try? runner.kill()
                    log?("[\(recipe.id)] stopped \(bottle.name) first, since winetricks waits for every program in it to end")
                }
                // WINE_BIN/WINESERVER_BIN/WINE_BINDIR are winetricks' own overrides for setups where
                // its binary detection fails; without them dotnet48 and friends abort on this engine
                // (verified 2026-08-25, issue #16). bash rather than sh for the same reason winetricks
                // documents on macOS.
                var env = try bottle.environment(engine: engine, renderer: .wined3d, extra: Self.winetricksExtras(engine: engine))
                // winetricks starts its own wine processes, so it joins a running server's sync mode
                // the way a launch does, or each of them dies on the spot (highball#241, #336).
                let joined = WineRunner.joiningLiveServer(env, prefix: bottle.url)
                if joined != env { log?("[\(recipe.id)] the environment runs with sync \(SyncMode(environment: joined).rawValue), so winetricks uses it too") }
                env = joined
                // The library paths reach winetricks' wine through a script, past bash (see WinetricksWine).
                env = WinetricksWine.environment(env, wine: engine.wineBinary, script: try WinetricksWine.installScript(in: paths))
                // cabextract and the other tools winetricks shells out to (see WinetricksWine.pathWithTools).
                env["PATH"] = WinetricksWine.pathWithTools(env["PATH"])
                // Its own log, named like every other one in the folder. Without it the step was
                // invisible: what winetricks said lived only in the error dialog's Details, so
                // three reports of the core fonts failing came with a game's launch log attached
                // and none of them could be answered (highball#135, #180, #183).
                let stamp = ISO8601DateFormatter().string(from: Date()).replacingOccurrences(of: ":", with: "")
                let logURL = WineRunner.uniqueLogURL(in: paths.logs,
                                                     named: "\(stamp)-\(bottle.name)-winetricks-\(verbs.joined(separator: "-"))")
                log?("[\(recipe.id)] log: \(logURL.path)")
                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):
                // 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):
                bottle.settings.sync = m
            case let .winver(v):
                bottle.settings.windowsVersion = v
                try await runner.setWindowsVersion(v)
            case let .file(path, contents):
                let url = Recipe.target(of: path, driveC: bottle.driveC, steamGames: steamGames)
                try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
                try contents.write(to: url, atomically: true, encoding: .utf8)
                if url != Recipe.target(of: path, driveC: bottle.driveC, steamGames: []) { log?("[\(recipe.id)] wrote \(url.path), the game's folder in another Steam library") }
            case let .copy(from, to, asNative):
                guard let source = Self.copySource(engineRoot: engine.root, from) else {
                    throw HighballError.invalid("copy step: '\(from)' is not a file inside the engine")
                }
                let dest = Recipe.target(of: to, driveC: bottle.driveC, steamGames: steamGames)
                if dest != bottle.driveC.appending(path: to) { log?("[\(recipe.id)] copying to \(dest.path), the game's folder in another Steam library") }
                try FileManager.default.createDirectory(at: dest.deletingLastPathComponent(), withIntermediateDirectories: true)
                if FileManager.default.fileExists(atPath: dest.path) { try FileManager.default.removeItem(at: dest) }
                if asNative {
                    try Self.withoutBuiltinMarker(Data(contentsOf: source)).write(to: dest)
                } else {
                    try FileManager.default.copyItem(at: source, to: dest)
                }
                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):
                // Semicolon separated, and idempotent: a recipe re-run must not stack duplicates.
                var parts = bottle.settings.dllOverrides.split(separator: ";").map(String.init)
                if !parts.contains(v) { parts.append(v) }
                bottle.settings.dllOverrides = parts.joined(separator: ";")
            case let .dxvkConfig(exe, options):
                bottle.settings.dxvkAppConfig[exe] = options
            case let .frameCap(n):
                if bottle.settings.fpsCap == 0 { bottle.settings.fpsCap = n }
            }
        }
        if !bottle.settings.recipes.contains(recipe.id) { bottle.settings.recipes.append(recipe.id) }
        try bottle.save()
        return notes
    }


    private func downloadUnverified(_ url: URL) async throws -> URL {
        try paths.ensure()
        let dest = paths.downloads.appending(path: url.lastPathComponent)
        // Same stall protection as engine downloads: URLSession.shared's 7-day resource timeout
        // let a dead CDN connection hang a recipe forever (GOG installer, 2026-08-25).
        let cfg = URLSessionConfiguration.ephemeral
        cfg.timeoutIntervalForRequest = 60
        cfg.timeoutIntervalForResource = 3600
        let session = URLSession(configuration: cfg)
        defer { session.finishTasksAndInvalidate() }
        let (tmp, response) = try await session.download(from: url)
        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
            throw HighballError.invalid("HTTP \(http.statusCode) for \(url)")
        }
        try? FileManager.default.removeItem(at: dest)
        try FileManager.default.moveItem(at: tmp, to: dest)
        return dest
    }
}

public extension Recipe {
    /// The engine to offer before applying this recipe to an environment on `current`: the
    /// manifest the recipe names unless `current` already satisfies it (the same engine, or a
    /// later revision of the same Wine build, since revisions are cumulative), or the app does
    /// not know the manifest. Same Wine is not enough on its own: r7 adds a builtin DLL r6
    /// lacks, and a bottle on r6 needs the offer.
    func engineToOffer(current: EngineManifest, known: [EngineManifest],
                       macOS: String = Machine.macOSVersion()) -> EngineManifest? {
        guard let id = engine, let wanted = known.first(where: { $0.id == id }) else { return nil }
        if EngineManifest.satisfies(current: current, wanted: wanted) { return nil }
        // The newest shipped revision that carries the pin, not the pin itself. A pin names the
        // revision a game was verified on, and the later revisions of its line fix what was
        // found since (msync's leak in r13, among others), while a non-default engine never
        // moves on its own. Offering the pin sent every new Red Dead player of 0.10.2 to the
        // September r7 (highball-db#272). A revision this Mac cannot run is skipped.
        return known.filter { EngineManifest.satisfies(current: $0, wanted: wanted) && $0.runs(onMacOS: macOS) }
            .max { (EngineManifest.revision(of: $0.id) ?? 0) < (EngineManifest.revision(of: $1.id) ?? 0) } ?? wanted
    }

    /// The later revision to offer an environment this recipe was applied to while it runs an earlier revision of the
    /// preview line the recipe pins: Microsoft Flight Simulator 2024 set up on r3 when its recipe moved to r5
    /// (2026-10-19). The engine ask comes only before a recipe is applied, so nothing else would offer it, and a
    /// preview line moves fast. Nil for every other line: a Wine 10 or Wine 11 environment never moves on its own. The
    /// offer's bundled manifest says whether the line is in preview, as in EngineChannels.runsLine.
    func previewRevisionToOffer(current: EngineManifest, known: [EngineManifest],
                                macOS: String = Machine.macOSVersion()) -> EngineManifest? {
        guard let id = engine, let line = EngineManifest.line(of: current.id), line == EngineManifest.line(of: id),
              let offer = engineToOffer(current: current, known: known, macOS: macOS),
              offer.channel == EngineChannels.preview, EngineManifest.line(of: offer.id) == line else { return nil }
        return offer
    }

    /// The macOS version this recipe's engine needs when no revision the app ships of it runs on `macOS`: the arm64
    /// line needs features Apple added in macOS 26.5 (4 KB pages for a process, x86 memory ordering per thread), and
    /// the D3DMetal 4 revisions need macOS 27. Play says so before any question or download, where 0.10.20 offered such
    /// an engine on any macOS and nothing stopped its install. Nil when a shipped revision runs here, when the recipe
    /// names no engine, or when the app does not ship it (engineUnknown answers that). `bundled` is every manifest the
    /// app ships, hidden channels included.
    func engineMacOSFloor(bundled: [EngineManifest], macOS: String = EngineManifest.currentMacOS) -> String? {
        guard let id = engine, let wanted = bundled.first(where: { $0.id == id }) else { return nil }
        let revisions = bundled.filter { EngineManifest.satisfies(current: $0, wanted: wanted) }
        return revisions.contains { $0.runs(onMacOS: macOS) } ? nil : wanted.minMacOS
    }

    /// The engine this recipe names when no manifest this build ships carries it and the
    /// environment is not already on it or a later revision of its line: the fix reached the
    /// database before the Highball that ships its engine (The Last Flame's r11 pin,
    /// highball#99, landed while 0.9.32 was the stable). Play tells the owner to update instead
    /// of launching on the current engine as if the recipe had never asked. Nil when the
    /// recipe names no engine.
    func engineUnknown(current: EngineManifest, known: [EngineManifest]) -> String? {
        guard let id = engine, !EngineManifest.isAtOrAfter(current: current.id, wanted: id),
              !known.contains(where: { $0.id == id }) else { return nil }
        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
    }

    /// Brings the variables a game recipe scoped to its game in line with the recipe as it is
    /// now. They are written when the recipe is applied, so a database update that changed or
    /// dropped one never reached an environment set up before it: Planet Coaster 2's recipe
    /// dropped two Metal validation variables after they froze two Macs, and both players'
    /// environments kept them (highball-db#115, #356, 2026-10-06). Only the recipe writes
    /// `gameEnvironment[recipe.id]`, so it follows the recipe exactly. A pin the recipe added
    /// carries a copy, which follows only where it still holds the recipe's old value: a value
    /// changed by hand stays. Returns the names added, changed or dropped, sorted, empty when
    /// the environment already matches.
    static func syncScopedEnvironment(of recipe: Recipe, in settings: inout BottleSettings) -> [String] {
        guard recipe.kind == .game else { return [] }
        var wanted: [String: String] = [:]
        var pinPaths: [String] = []
        for step in recipe.steps {
            switch step {
            case let .environment(name, value): wanted[name] = value
            case let .pin(p): pinPaths.append(p.path)
            default: break
            }
        }
        let had = settings.gameEnvironment[recipe.id] ?? [:]
        let changed = Set(had.keys).union(wanted.keys).filter { had[$0] != wanted[$0] }.sorted()
        guard !changed.isEmpty else { return [] }
        settings.gameEnvironment[recipe.id] = wanted.isEmpty ? nil : wanted
        for i in settings.pins.indices where pinPaths.contains(settings.pins[i].path) {
            for name in changed where settings.pins[i].environment[name] == had[name] {
                settings.pins[i].environment[name] = wanted[name]
            }
        }
        return changed
    }
}