Skip to content

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

An engine on an exFAT or other non-APFS drive no longer feeds GStreamer its ._ sidecar files. macOS keeps a file's extended attributes in a ._name file beside it on such volumes, and every engine file carries com.apple.provenance, so all 207 GStreamer plugins of r26 got a ._libgst*.dylib twin when copied to an exFAT image here, which GStreamer then tried to load as plugins (a player with Highball's home on a non-APFS drive, Discord, 2026-10-11). A fresh install now removes every ._name whose name sits beside it, and reading the installed engines cleans the GStreamer plugin folder, which heals existing installs. The listing uses readdir: Foundation's directory listing leaves ._ files out, which the first version of the test caught. New test.

Gauthier Piarrettef220d3afe30d
diff --git a/Sources/HighballKit/EngineStore.swift b/Sources/HighballKit/EngineStore.swift
index 21f2907..96971aa 100644
--- a/Sources/HighballKit/EngineStore.swift
+++ b/Sources/HighballKit/EngineStore.swift
@@ -49,6 +49,7 @@ 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)
return InstalledEngine(manifest: m, root: dir)
}.sorted { $0.manifest.id < $1.manifest.id }
}
@@ -252,6 +253,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)
// 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
@@ -535,6 +537,8 @@ public struct InstalledEngine: Sendable {
}
public var engineDir: URL { root.appending(path: "engine", directoryHint: .isDirectory) }
public var frameworksDir: URL { root.appending(path: "frameworks", directoryHint: .isDirectory) }
+ /// Where GStreamer looks for its plugins (GST_PLUGIN_PATH in baseEnvironment).
+ var gstreamerPluginDir: URL { frameworksDir.appending(path: "GStreamer.framework/Versions/1.0/lib/gstreamer-1.0", directoryHint: .isDirectory) }
/// The library that keeps Wine's audio pulls under half a period (highball#127) and, since
/// 20261008, limits a mix over full scale (highball-db#349), when the engine ships it as a
/// component. Bottle.environment inserts it into Wine's processes.
@@ -698,3 +702,48 @@ 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
new file mode 100644
index 0000000..4079a27
--- /dev/null
+++ b/Tests/HighballKitTests/AppleDoubleCleanupTests.swift
@@ -0,0 +1,25 @@
+import XCTest
+@testable import HighballKit
+
+/// 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).
+final class AppleDoubleCleanupTests: XCTestCase {
+ func testOnlyTheSidecarsOfFilesThatExistGo() throws {
+ let root = FileManager.default.temporaryDirectory.appending(path: "hb-appledouble-\(UUID().uuidString)", directoryHint: .isDirectory)
+ let nested = root.appending(path: "lib/gstreamer-1.0", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: nested, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: root) }
+ for name in ["libgstcoreelements.dylib", "._libgstcoreelements.dylib", "._orphan.dylib"] {
+ try Data().write(to: nested.appending(path: name))
+ }
+ 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(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)
+ XCTAssertFalse(FileManager.default.fileExists(atPath: root.appending(path: "._wine").path))
+ }
+}