Skip to content

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

Play removes the macOS '._' files beside a game's files when its folder is on a drive that keeps them, as an exFAT drive does. macOS writes a file's extended attributes into a ._name file beside it on a volume with no native place for them, and Windows programs take those for files of their own: Alice Madness Returns failed on the 4,407 in a Steam library on an exFAT drive until they were deleted, and a reinstall brought them all back (highball-db#429). The volume is asked rather than its format named (VOL_CAP_INT_EXTENDED_ATTR, measured 2026-10-23 on disk images: exFAT valid and off, APFS valid and on), so a folder on APFS is not even walked, and the walk reads only directory listings since it runs before every Steam and Epic launch from such a drive. Only a ._name with its name beside it goes, links are not followed. The engine cleanup from 0.10.20 moved into the same AppleDouble helper. 586 tests pass on the M4, among them one that writes a value to a file on an exFAT disk image and checks its ._ file goes.

Gauthier Piarretted5f4c3965126
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 9f4d79d..3995c8c 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -2732,6 +2732,18 @@ final class AppState {
}
}
+ /// A game folder on a drive that keeps Mac metadata in `._` files beside each file (exFAT, FAT,
+ /// some network shares) shows the game those files as its own: Alice: Madness Returns failed on
+ /// the 4,407 in a Steam library on an exFAT drive, and a reinstall brought them back
+ /// (highball-db#429). The ones beside the game's files go before each launch, off the main
+ /// thread; a folder on APFS is not walked.
+ private func removeMacMetadataFiles(from folder: URL?, of title: String) async {
+ guard let folder else { return }
+ let removed = await Task.detached { AppleDouble.cleanGameFolder(folder) }.value
+ guard removed > 0 else { return }
+ appendLog("Removed \(removed) macOS '._' files from \(title)'s folder. Its drive keeps Mac metadata in them, and the game would read them as files of its own.")
+ }
+
/// Launch a Steam game by appid through the bottle's Steam client.
func launchGame(_ game: SteamGame, in bottle: Bottle, renderer preferred: Renderer? = nil) {
guard let engine = engine(for: bottle) else { return }
@@ -2750,6 +2762,8 @@ final class AppState {
// 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)
+ let folder = game.installdir.isEmpty ? nil : game.installFolder
+ ?? bottle.driveC.appending(path: "Program Files (x86)/Steam/steamapps/common/\(game.installdir)", directoryHint: .isDirectory)
// 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
// and a session begins, and the app is free while the game runs (UX plan 0.6).
@@ -2758,6 +2772,7 @@ final class AppState {
stop: .killBottle(bottle, label: L("Stop"))) { [self] in
let runner = WineRunner(paths: paths, engine: engine, bottle: bottle)
await adoptRuntimesInstalledByGames(in: bottle, engine: engine)
+ await removeMacMetadataFiles(from: folder, of: game.name)
// A running client would serve the launch with its own environment; when that is
// not the game's, cold-start first: never under a running game, Steam's or not.
// A kept client is said out loud, in the activity log and in the launch log's header:
@@ -3060,8 +3075,10 @@ final class AppState {
fail(HighballError.failed("\(game.app_title) is already running."))
return
}
+ let folder = epicInstalls[game.app_name].map { URL(fileURLWithPath: $0, isDirectory: true) }
runBusy("Starting \(game.app_title)", done: .handedOff, stop: .killBottle(bottle, label: L("Stop"))) { [self] in
let store = epicStore
+ await removeMacMetadataFiles(from: folder, of: game.app_title)
// Fresh single-use token, fetched off the main thread right before launch.
let info = try await Task.detached { try store.launchInfo(game.app_name) }.value
let runner = WineRunner(paths: paths, engine: engine, bottle: bottle)
diff --git a/Sources/HighballKit/AppleDouble.swift b/Sources/HighballKit/AppleDouble.swift
new file mode 100644
index 0000000..8dee9fc
--- /dev/null
+++ b/Sources/HighballKit/AppleDouble.swift
@@ -0,0 +1,93 @@
+import Foundation
+
+/// macOS keeps a file's extended attributes in a `._name` file beside it on a volume with no native
+/// place for them (exFAT, FAT, some network shares), and Windows programs take those files for their
+/// own. GStreamer tried to load an engine's `._libgst*.dylib` files as plugins (a player with
+/// Highball's home on a non-APFS drive, on Discord, 2026-10-11). Alice: Madness Returns failed on the
+/// 4,407 beside its files in a Steam library on an exFAT drive until they were deleted, and a
+/// reinstall brought them all back (highball-db#429).
+public enum AppleDouble {
+ /// True when the volume holding `url` keeps extended attributes in `._` files: it reports native
+ /// extended attributes as a capability it knows of and lacks. Measured 2026-10-23 on a disk image:
+ /// exFAT reports it valid and off, APFS valid and on, and a value written to a file on the exFAT
+ /// volume appeared as `._name` beside it.
+ public static func volumeKeepsTwins(_ url: URL) -> Bool {
+ var fs = statfs()
+ guard statfs(url.path, &fs) == 0 else { return false }
+ // Volume attributes are only answered for the volume's root.
+ let mount = withUnsafePointer(to: fs.f_mntonname) {
+ $0.withMemoryRebound(to: CChar.self, capacity: Int(MAXPATHLEN)) { String(cString: $0) }
+ }
+ var request = attrlist()
+ request.bitmapcount = u_short(ATTR_BIT_MAP_COUNT)
+ request.volattr = attrgroup_t(ATTR_VOL_INFO) | attrgroup_t(ATTR_VOL_CAPABILITIES)
+ var reply = VolumeCapabilities()
+ guard getattrlist(mount, &request, &reply, MemoryLayout<VolumeCapabilities>.size, 0) == 0 else { return false }
+ let bit = UInt32(VOL_CAP_INT_EXTENDED_ATTR)
+ // Element 1 of each set is VOL_CAPABILITIES_INTERFACES.
+ return reply.caps.valid.1 & bit != 0 && reply.caps.capabilities.1 & bit == 0
+ }
+
+ /// getattrlist's reply to ATTR_VOL_CAPABILITIES alone: its length, then the capability sets.
+ private struct VolumeCapabilities {
+ var length: UInt32 = 0
+ var caps = vol_capabilities_attr_t()
+ }
+
+ /// A game's folder before its launch: on a volume that keeps `._` files, each one beside a file
+ /// of the game goes. A folder on APFS is not walked at all. Returns how many went.
+ public static func cleanGameFolder(_ folder: URL) -> Int {
+ guard volumeKeepsTwins(folder) else { return 0 }
+ return removeTwins(in: folder, recursive: true)
+ }
+
+ /// Removes each `._name` whose `name` sits beside it, nothing else, and returns how many went.
+ /// A walk asks the file system nothing beyond its directory listings: a game folder can hold
+ /// tens of thousands of files, and this runs before every launch from such a drive.
+ @discardableResult
+ public static func removeTwins(in dir: URL, recursive: Bool) -> Int {
+ let fm = FileManager.default
+ var removed = 0
+ func clean(_ folder: URL) {
+ // readdir, not FileManager: Foundation's directory listing leaves `._` files out.
+ guard let entries = rawEntries(in: folder) else { return }
+ let present = Set(entries.map(\.name))
+ for (name, _) in entries where name.hasPrefix("._") && present.contains(String(name.dropFirst(2))) {
+ if (try? fm.removeItem(at: folder.appending(path: name))) != nil { removed += 1 }
+ }
+ guard recursive else { return }
+ for (name, type) in entries where !name.hasPrefix("._") {
+ let child = folder.appending(path: name)
+ switch Int32(type) {
+ case DT_DIR:
+ clean(child)
+ case DT_UNKNOWN:
+ let values = try? child.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])
+ if values?.isDirectory == true, values?.isSymbolicLink != true { clean(child) }
+ default:
+ continue // files, and links, which are never followed
+ }
+ }
+ }
+ clean(dir)
+ return removed
+ }
+
+ /// Every entry of a directory as the file system lists it, `.` and `..` aside.
+ static func rawNames(in dir: URL) -> [String]? { rawEntries(in: dir)?.map(\.name) }
+
+ /// The same with each entry's type as the listing gives it (DT_DIR, DT_REG, DT_LNK, or
+ /// DT_UNKNOWN from a file system that does not say).
+ static func rawEntries(in dir: URL) -> [(name: String, type: UInt8)]? {
+ guard let handle = opendir(dir.path) else { return nil }
+ defer { closedir(handle) }
+ var entries: [(name: String, type: UInt8)] = []
+ while let entry = readdir(handle) {
+ let name = withUnsafePointer(to: entry.pointee.d_name) {
+ $0.withMemoryRebound(to: CChar.self, capacity: Int(MAXPATHLEN)) { String(cString: $0) }
+ }
+ if name != "." && name != ".." { entries.append((name, entry.pointee.d_type)) }
+ }
+ return entries
+ }
+}
diff --git a/Sources/HighballKit/EngineStore.swift b/Sources/HighballKit/EngineStore.swift
index 448797e..399d02c 100644
--- a/Sources/HighballKit/EngineStore.swift
+++ b/Sources/HighballKit/EngineStore.swift
@@ -49,7 +49,9 @@ public struct EngineStore: Sendable {
guard let m = try? EngineManifest.load(from: manifest) else { return nil }
try? linkRuntime(dir) // heals broken runtime links from pre-0.7.9 installs
try? linkSignedLoader(dir, manifest: m) // an app that moved repoints its arm64 engines
- Self.removeAppleDoubleFiles(in: InstalledEngine(manifest: m, root: dir).gstreamerPluginDir, recursive: false)
+ // GStreamer took the plugin folder's `._libgst*.dylib` files for plugins (see AppleDouble); this also
+ // heals engines installed before the cleanup.
+ AppleDouble.removeTwins(in: InstalledEngine(manifest: m, root: dir).gstreamerPluginDir, recursive: false)
return InstalledEngine(manifest: m, root: dir)
}.sorted { $0.manifest.id < $1.manifest.id }
}
@@ -295,7 +297,7 @@ public struct EngineStore: Sendable {
try saved.save(to: staging.appending(path: "manifest.json"))
try linkRuntime(staging)
try linkSignedLoader(staging, manifest: saved)
- Self.removeAppleDoubleFiles(in: staging, recursive: true)
+ AppleDouble.removeTwins(in: staging, recursive: true)
// The unpacked tree must be a whole engine before it replaces anything: an archive that
// unpacked short (a full disk, a file the archive lacks) used to install all the same and
// fail every launch afterwards (highball#118). The archive was checksummed, so the fault
@@ -749,48 +751,3 @@ public struct InstalledEngine: Sendable {
return env
}
}
-
-extension EngineStore {
- /// macOS keeps a file's extended attributes in a `._name` file beside it on a volume with no
- /// place for them (exFAT, FAT, SMB), so an engine unpacked onto such a drive gains one per
- /// file. GStreamer takes every library in its plugin folder for a plugin and tried to load
- /// the `._libgst*.dylib` files too (a player with Highball's home on a non-APFS drive, on
- /// Discord, 2026-10-11). Removes each `._name` whose `name` sits beside it, nothing else, and
- /// returns how many went. A fresh install is cleaned whole; an installed engine has its
- /// plugin folder cleaned whenever engines are read, which also heals earlier installs.
- @discardableResult
- static func removeAppleDoubleFiles(in dir: URL, recursive: Bool) -> Int {
- let fm = FileManager.default
- var removed = 0
- func clean(_ folder: URL) {
- // readdir, not FileManager: Foundation's directory listing leaves `._` files out.
- guard let names = rawNames(in: folder) else { return }
- let present = Set(names)
- for name in names where name.hasPrefix("._") && present.contains(String(name.dropFirst(2))) {
- if (try? fm.removeItem(at: folder.appending(path: name))) != nil { removed += 1 }
- }
- guard recursive else { return }
- for name in names where !name.hasPrefix("._") {
- let child = folder.appending(path: name)
- let values = try? child.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])
- if values?.isDirectory == true, values?.isSymbolicLink != true { clean(child) }
- }
- }
- clean(dir)
- return removed
- }
-
- /// Every entry of a directory as the file system lists it, `.` and `..` aside.
- static func rawNames(in dir: URL) -> [String]? {
- guard let handle = opendir(dir.path) else { return nil }
- defer { closedir(handle) }
- var names: [String] = []
- while let entry = readdir(handle) {
- let name = withUnsafePointer(to: entry.pointee.d_name) {
- $0.withMemoryRebound(to: CChar.self, capacity: Int(MAXPATHLEN)) { String(cString: $0) }
- }
- if name != "." && name != ".." { names.append(name) }
- }
- return names
- }
-}
diff --git a/Tests/HighballKitTests/AppleDoubleCleanupTests.swift b/Tests/HighballKitTests/AppleDoubleCleanupTests.swift
index 4079a27..d1c74a9 100644
--- a/Tests/HighballKitTests/AppleDoubleCleanupTests.swift
+++ b/Tests/HighballKitTests/AppleDoubleCleanupTests.swift
@@ -3,6 +3,7 @@ import XCTest
/// An engine unpacked onto an exFAT or other non-APFS drive gets a `._name` file beside each file,
/// and GStreamer tried to load the `._libgst*.dylib` ones as plugins (a player on Discord, 2026-10-11).
+/// A game folder there gets them too, and Alice: Madness Returns failed on them (highball-db#429).
final class AppleDoubleCleanupTests: XCTestCase {
func testOnlyTheSidecarsOfFilesThatExistGo() throws {
let root = FileManager.default.temporaryDirectory.appending(path: "hb-appledouble-\(UUID().uuidString)", directoryHint: .isDirectory)
@@ -14,12 +15,73 @@ final class AppleDoubleCleanupTests: XCTestCase {
}
for name in ["wine", "._wine"] { try Data().write(to: root.appending(path: name)) }
- XCTAssertEqual(EngineStore.removeAppleDoubleFiles(in: nested, recursive: false), 1)
- let left = try XCTUnwrap(EngineStore.rawNames(in: nested)).sorted()
+ XCTAssertEqual(AppleDouble.removeTwins(in: nested, recursive: false), 1)
+ let left = try XCTUnwrap(AppleDouble.rawNames(in: nested)).sorted()
XCTAssertEqual(left, ["._orphan.dylib", "libgstcoreelements.dylib"], "a ._ file with nothing beside it is not a sidecar")
XCTAssertTrue(FileManager.default.fileExists(atPath: root.appending(path: "._wine").path), "not recursive, the parent is left")
- XCTAssertEqual(EngineStore.removeAppleDoubleFiles(in: root, recursive: true), 1)
+ // A linked folder is someone else's: the walk does not follow it.
+ let outside = FileManager.default.temporaryDirectory.appending(path: "hb-appledouble-out-\(UUID().uuidString)", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: outside, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: outside) }
+ for name in ["save", "._save"] { try Data().write(to: outside.appending(path: name)) }
+ try FileManager.default.createSymbolicLink(at: root.appending(path: "linked"), withDestinationURL: outside)
+
+ XCTAssertEqual(AppleDouble.removeTwins(in: root, recursive: true), 1)
XCTAssertFalse(FileManager.default.fileExists(atPath: root.appending(path: "._wine").path))
+ XCTAssertTrue(FileManager.default.fileExists(atPath: outside.appending(path: "._save").path), "links are not followed")
+ }
+
+ /// A game folder on APFS keeps native extended attributes, so nothing there is a sidecar and the
+ /// folder is not even walked: a `._` file a game ships stays.
+ func testAGameFolderOnAPFSIsLeftAlone() throws {
+ let root = FileManager.default.temporaryDirectory.appending(path: "hb-appledouble-\(UUID().uuidString)", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: root) }
+ for name in ["Game.upk", "._Game.upk"] { try Data().write(to: root.appending(path: name)) }
+ try XCTSkipUnless((try? root.resourceValues(forKeys: [.volumeTypeNameKey]))?.volumeTypeName?.lowercased() == "apfs",
+ "the temporary folder is not on APFS")
+
+ XCTAssertFalse(AppleDouble.volumeKeepsTwins(root))
+ XCTAssertEqual(AppleDouble.cleanGameFolder(root), 0)
+ XCTAssertTrue(FileManager.default.fileExists(atPath: root.appending(path: "._Game.upk").path))
+ }
+
+ /// On exFAT a value written to a file lands in `._name` beside it, which is what a game read as
+ /// its own; the cleanup takes those and leaves the game's files.
+ func testAGameFolderOnExFATLosesItsSidecars() throws {
+ let fm = FileManager.default
+ let work = fm.temporaryDirectory.appending(path: "hb-exfat-\(UUID().uuidString)", directoryHint: .isDirectory)
+ let image = work.appending(path: "volume.dmg"), mount = work.appending(path: "mnt", directoryHint: .isDirectory)
+ try fm.createDirectory(at: mount, withIntermediateDirectories: true)
+ defer { try? fm.removeItem(at: work) }
+ guard Self.hdiutil(["create", "-quiet", "-size", "20m", "-fs", "ExFAT", "-volname", "HBTEST", image.path]),
+ Self.hdiutil(["attach", "-quiet", "-nobrowse", "-mountpoint", mount.path, image.path]) else {
+ throw XCTSkip("no exFAT disk image could be made and attached here")
+ }
+ defer { _ = Self.hdiutil(["detach", "-quiet", "-force", mount.path]) }
+
+ let cooked = mount.appending(path: "CookedPC", directoryHint: .isDirectory)
+ try fm.createDirectory(at: cooked, withIntermediateDirectories: true)
+ let package = cooked.appending(path: "Startup.upk")
+ try Data("package".utf8).write(to: package)
+ XCTAssertEqual(setxattr(package.path, "com.example.highball", "1", 1, 0, 0), 0)
+ XCTAssertTrue(try XCTUnwrap(AppleDouble.rawNames(in: cooked)).contains("._Startup.upk"), "exFAT keeps the value in a ._ file")
+
+ XCTAssertTrue(AppleDouble.volumeKeepsTwins(mount))
+ XCTAssertGreaterThanOrEqual(AppleDouble.cleanGameFolder(mount), 1)
+ XCTAssertFalse(try XCTUnwrap(AppleDouble.rawNames(in: cooked)).contains("._Startup.upk"))
+ XCTAssertEqual(try Data(contentsOf: package), Data("package".utf8), "the game's own file stays as it was")
+ }
+
+ private static func hdiutil(_ arguments: [String]) -> Bool {
+ let process = Process()
+ process.executableURL = URL(fileURLWithPath: "/usr/bin/hdiutil")
+ process.arguments = arguments
+ process.standardOutput = FileHandle.nullDevice
+ process.standardError = FileHandle.nullDevice
+ guard (try? process.run()) != nil else { return false }
+ process.waitUntilExit()
+ return process.terminationStatus == 0
}
}