Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

Onboarding hints that NVN games need Xcode 27.1 and macOS 26.6

v0lumehi2ad23c010b2e
diff --git a/frontend/Onboarding.md b/frontend/Onboarding.md
index 1048e583..7443ed4b 100644
--- a/frontend/Onboarding.md
+++ b/frontend/Onboarding.md
@@ -11,12 +11,14 @@ NSPB_ONBOARDING_DEMO=xcodeReady swift run
NSPB_ONBOARDING_DEMO=keysInvalid swift run
NSPB_ONBOARDING_DEMO=xcodeFailed swift run
NSPB_ONBOARDING_DEMO=noGames swift run
+NSPB_ONBOARDING_DEMO=oldMac swift run
```
- `fresh`: Start, select a platform, Continue, Get Xcode, wait, Finish setup, confirm the found keys, review the games, Continue, Open library.
- `xcodeReady`: the same path, with Xcode already present; its checks tick through automatically.
- `keysInvalid`: confirming the found file fails validation. Choose or drop another file to exercise recovery. The mock does not read it.
- `xcodeFailed`: setup fails with a plain explanation and expandable diagnostics. Retry, then Finish setup to recover.
+- `oldMac`: the `fresh` path with the NVN hints on (below).
- `noGames`: the mock folder scan finds no NSPs and shows a hint. Use Back or Set up later.
Set up later preserves an in-memory snapshot; Resume setup restores it. The mock persists nothing; the real driver does (below).
@@ -59,6 +61,10 @@ Persist the current step and selections before handling `skipForLater`; inject t
- Xcode: missing opens the App Store and polls /Applications for it; setup is one administrator prompt (`OnboardingAdmin.source`: `xcode-select -s`, `xcodebuild -license accept`, `-runFirstLaunch`), then the Metal Toolchain and, for iPhone or both, the iOS platform without it. A cancelled prompt returns to `needsSetup`.
- Keys are found in `~/.switch`, `~/Downloads` and the games folder, checked by `KeyCheck`, and only the path goes into the keys slot. Games use `GameLibrary.sourceGames`, `BuildModel.scan` and `GameLibrary.setFolder`.
+## NVN hints
+
+NVN games' shaders need the Metal compiler of Xcode 27.1, which needs macOS 26.6. `OnboardingState.osTooOldForNVN` (macOS below 26.6, from `OnboardingEnvironment.osVersion`) adds a calm note to Welcome; `xcodeTooOldForNVN` (the probe's `xcodebuild -version` below 27.1; an unreadable version never counts) adds a secondary line in the Xcode card. Neither gates anything: other games build with an older Xcode.
+
## Presentation choices
The flow retains the launcher's dark appearance, palette, Manrope, cream capsule primary button, secondary button style and 1.8:1 cover crop. The app currently forces dark mode, so onboarding does too. Background preparation stays beside Xcode, while a fixed footer keeps the primary action visible at the launcher's 900 × 680 minimum window size. Long content scrolls. The two Xcode cards share one fixed height across all of that step's states (content scrolls inside a card rather than resizing it), and the platform, keys and games cards keep their size between states.
diff --git a/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift b/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
index bb8b3cbd..206cee40 100644
--- a/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
+++ b/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
@@ -18,6 +18,7 @@ struct XcodeProbe: Equatable {
var selectedIsXcode = false // `xcode-select -p` points into an Xcode.app, not the Command Line Tools
var licenseAccepted = false
var firstLaunchDone = false
+ var version: String? // from `xcodebuild -version` of appPath ("27.1"); nil when unreadable
var developerDir: String? { appPath.map { $0 + "/Contents/Developer" } }
var needsAdmin: Bool { !(selectedIsXcode && licenseAccepted && firstLaunchDone) }
}
@@ -29,6 +30,7 @@ struct OnboardingEnvironment {
var defaults: UserDefaults = .standard
var home = NSHomeDirectory()
var freeBytes: () -> Int64? = { OnboardingEnvironment.homeVolumeFreeBytes() }
+ var osVersion: () -> OperatingSystemVersion = { ProcessInfo.processInfo.operatingSystemVersion }
/// Whether a working Xcode is there, for the poll while the App Store installs it: `xcodebuild -version` must exit 0,
/// because the App Store creates Xcode.app while it is still downloading. Runs off the main thread.
var xcodeInstalled: () async -> Bool = { await Task.detached { OnboardingEnvironment.xcodeApps().first != nil }.value }
@@ -93,6 +95,16 @@ struct OnboardingEnvironment {
probe.selectedIsXcode = true
probe.appPath = String(selected[..<r.lowerBound]) + ".app"
} else { probe.appPath = xcodeApps().first }
+ if let dir = probe.developerDir {
+ let v = Process()
+ v.executableURL = URL(fileURLWithPath: "/usr/bin/xcodebuild"); v.arguments = ["-version"]
+ v.environment = ["DEVELOPER_DIR": dir, "PATH": "/usr/bin:/bin"]
+ let out = Pipe(); v.standardOutput = out; v.standardError = FileHandle.nullDevice
+ if (try? v.run()) != nil {
+ let data = out.fileHandleForReading.readDataToEndOfFile(); v.waitUntilExit()
+ if v.terminationStatus == 0 { probe.version = OnboardingNVN.xcodeVersion(from: String(data: data, encoding: .utf8) ?? "") }
+ }
+ }
if probe.selectedIsXcode {
probe.licenseAccepted = BuildModel.runOK("/usr/bin/xcodebuild", ["-license", "check"])
probe.firstLaunchDone = BuildModel.runOK("/usr/bin/xcodebuild", ["-checkFirstLaunchStatus"])
@@ -427,6 +439,7 @@ enum OnboardingLaunch {
let (xcode, _) = OnboardingXcode.evaluate(probe: probe, metalReady: dep("metal")?.present ?? false,
iosReady: dep("xcode")?.present ?? false, includesIOS: state.selectedPlatform?.includesIOS == true)
if xcode != .ready { state.step = .xcode; persistStep() }
+ updateWelcome()
}
// MARK: Welcome
@@ -445,6 +458,8 @@ enum OnboardingLaunch {
// Whole GB as Finder counts them (10^9). Without a reading the volume is taken to have room: nothing to warn about.
let free = env.freeBytes().map { Int($0 / 1_000_000_000) } ?? needed
state.welcome = .requirements(freeGB: free, neededGB: needed)
+ state.osTooOldForNVN = OnboardingNVN.osTooOld(env.osVersion())
+ state.xcodeTooOldForNVN = probed && probe.appPath != nil && OnboardingNVN.xcodeTooOld(probe.version)
}
// MARK: Xcode
diff --git a/frontend/Sources/NSPortBuilder/Localization.swift b/frontend/Sources/NSPortBuilder/Localization.swift
index c7fe38f4..5bb42896 100644
--- a/frontend/Sources/NSPortBuilder/Localization.swift
+++ b/frontend/Sources/NSPortBuilder/Localization.swift
@@ -45,6 +45,8 @@ enum L10n {
"onboarding.welcome.note": ("\u{7ea6} 15 \u{5206}\u{949f}\u{ff0c}\u{5373}\u{53ef}\u{5728} Mac \u{4e0a}\u{539f}\u{751f}\u{8fd0}\u{884c}\u{4f60}\u{7684} Switch \u{6e38}\u{620f}\u{3002}", "Play your Switch games natively on your Mac, in about 15 minutes."),
"onboarding.platform.title": ("\u{4f60}\u{60f3}\u{5728}\u{54ea}\u{91cc}\u{73a9}\u{ff1f}", "Where do you want to play?"),
"onboarding.platform.note": ("\u{9009}\u{62e9}\u{6e38}\u{73a9}\u{8bbe}\u{5907}\u{ff0c}\u{6211}\u{4eec}\u{4f1a}\u{51c6}\u{5907}\u{6240}\u{9700}\u{7684}\u{5de5}\u{5177}\u{3002}", "Choose where you will play. We will prepare just what you need."),
+ "onboarding.nvn.os": ("\u{90e8}\u{5206}\u{6e38}\u{620f}\u{9700}\u{8981} Xcode 27.1\u{ff0c}\u{800c}\u{5b83}\u{9700}\u{8981} macOS 26.6 \u{6216}\u{66f4}\u{9ad8}\u{7248}\u{672c}\u{3002}\u{5728}\u{8fd9}\u{53f0} Mac \u{4e0a}\u{ff0c}\u{4f7f}\u{7528} NVN \u{7684}\u{6e38}\u{620f}\u{65e0}\u{6cd5}\u{6784}\u{5efa}\u{ff0c}\u{5176}\u{4ed6}\u{6e38}\u{620f}\u{4e0d}\u{53d7}\u{5f71}\u{54cd}\u{3002}", "Some games need Xcode 27.1, which needs macOS 26.6 or later. On this Mac, games that use NVN won\u{2019}t build; others will."),
+ "onboarding.nvn.xcode": ("\u{8fd9}\u{4e2a} Xcode \u{4f4e}\u{4e8e} 27.1\u{ff0c}\u{800c}\u{4f7f}\u{7528} NVN \u{7684}\u{6e38}\u{620f}\u{9700}\u{8981} 27.1\u{3002}\u{5982}\u{679c}\u{4f60}\u{7684} macOS \u{652f}\u{6301}\u{ff0c}\u{8bf7}\u{5728} App Store \u{4e2d}\u{66f4}\u{65b0} Xcode\u{ff1b}\u{5176}\u{4ed6}\u{6e38}\u{620f}\u{7528}\u{5f53}\u{524d}\u{7248}\u{672c}\u{5373}\u{53ef}\u{6784}\u{5efa}\u{3002}", "This Xcode is older than 27.1, which games that use NVN need. Update Xcode in the App Store if your macOS allows it; other games build with this one."),
"onboarding.xcode.title": ("\u{51c6}\u{5907}\u{597d}\u{4f60}\u{7684} Mac\u{3002}", "Let\u{2019}s get your Mac ready."),
"onboarding.xcode.note": ("Xcode \u{63d0}\u{4f9b}\u{6784}\u{5efa}\u{6e38}\u{620f}\u{6240}\u{9700}\u{7684} Apple \u{5de5}\u{5177}\u{3002}\u{6211}\u{4eec}\u{5c06}\u{5f15}\u{5bfc}\u{4f60}\u{5b8c}\u{6210}\u{8bbe}\u{7f6e}\u{3002}", "Xcode provides Apple\u{2019}s tools for building your games. We will guide you through the setup."),
"onboarding.keys.title": ("\u{6dfb}\u{52a0}\u{4f60}\u{7684}\u{5bc6}\u{94a5}\u{3002}", "Bring your own keys."),
diff --git a/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift b/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift
index dcb20c6f..faa4b213 100644
--- a/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift
+++ b/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift
@@ -2,7 +2,7 @@ import Foundation
/// A scripted demo only. No detection, file reads, installs, preferences or subprocesses.
@MainActor final class MockOnboardingDriver: OnboardingDriver {
- enum Scenario: String, CaseIterable { case fresh, xcodeReady, keysInvalid, xcodeFailed, noGames }
+ enum Scenario: String, CaseIterable { case fresh, xcodeReady, keysInvalid, xcodeFailed, noGames, oldMac }
@Published private(set) var state: OnboardingState
private(set) var resumeSnapshot: OnboardingState?
let scenario: Scenario
@@ -20,6 +20,7 @@ import Foundation
init(scenario: Scenario = .fresh, state: OnboardingState = MockOnboardingDriver.sampleState, lang: Lang = .initial(), animated: Bool = true) {
self.scenario = scenario; self.state = state; self.lang = lang; self.animated = animated
+ if scenario == .oldMac { self.state.osTooOldForNVN = true; self.state.xcodeTooOldForNVN = true }
if animated { enterStep() }
}
deinit { jobs.values.forEach { $0.cancel() } }
diff --git a/frontend/Sources/NSPortBuilder/OnboardingState.swift b/frontend/Sources/NSPortBuilder/OnboardingState.swift
index 0db84f86..33559f5d 100644
--- a/frontend/Sources/NSPortBuilder/OnboardingState.swift
+++ b/frontend/Sources/NSPortBuilder/OnboardingState.swift
@@ -7,6 +7,33 @@ enum OnboardingStep: String, CaseIterable, Codable {
var titleKey: String { "onboarding.\(rawValue).title" }
}
+/// What NVN games' shaders need: the Metal compiler of Xcode 27.1, which itself needs macOS 26.6.
+enum OnboardingNVN {
+ static let minimumXcode = [27, 1]
+ static let minimumOS = OperatingSystemVersion(majorVersion: 26, minorVersion: 6, patchVersion: 0)
+
+ static func osTooOld(_ v: OperatingSystemVersion) -> Bool {
+ (v.majorVersion, v.minorVersion, v.patchVersion) < (minimumOS.majorVersion, minimumOS.minorVersion, minimumOS.patchVersion)
+ }
+
+ /// `xcodebuild -version` prints "Xcode 27.1" first. An unreadable version is not reported as too old.
+ static func xcodeVersion(from output: String) -> String? {
+ for line in output.split(whereSeparator: \.isNewline) where line.hasPrefix("Xcode ") {
+ let v = line.dropFirst(6).split(separator: " ").first.map(String.init) ?? ""
+ if v.split(separator: ".").allSatisfy({ Int($0) != nil }), !v.isEmpty { return v }
+ }
+ return nil
+ }
+
+ static func xcodeTooOld(_ version: String?) -> Bool {
+ guard let version else { return false }
+ var parts = version.split(separator: ".").compactMap { Int($0) }
+ while parts.count < minimumXcode.count { parts.append(0) }
+ for (a, b) in zip(parts, minimumXcode) where a != b { return a < b }
+ return false
+ }
+}
+
enum OnboardingPlatform: String, CaseIterable {
case mac, iphone, both
var includesIOS: Bool { self != .mac }
@@ -100,6 +127,9 @@ struct OnboardingState: Equatable {
var games: Games = .empty
var done: Done = .celebrating
var exit: Exit? = nil
+ /// NVN games need the Metal compiler of Xcode 27.1, which needs macOS 26.6. Hints only: setup continues either way.
+ var osTooOldForNVN = false
+ var xcodeTooOldForNVN = false
var selectedPlatform: OnboardingPlatform? {
if case let .selected(value) = platform { return value }
diff --git a/frontend/Sources/NSPortBuilder/OnboardingView.swift b/frontend/Sources/NSPortBuilder/OnboardingView.swift
index 538cc522..26ad6f8a 100644
--- a/frontend/Sources/NSPortBuilder/OnboardingView.swift
+++ b/frontend/Sources/NSPortBuilder/OnboardingView.swift
@@ -174,6 +174,11 @@ import UniformTypeIdentifiers
Text(t("onboarding.require.diskWarning")).foregroundStyle(LauncherPalette.building)
.opacity(state.welcome.hasSpace ? 0 : 1).accessibilityHidden(state.welcome.hasSpace)
}
+ // A fact about this Mac, constant during setup: a calm note, not a warning, and no gate.
+ if state.osTooOldForNVN {
+ Text(t("onboarding.nvn.os")).font(.manrope(13)).foregroundStyle(.secondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
}.modifier(OnboardingCard())
}
@@ -253,6 +258,11 @@ import UniformTypeIdentifiers
}
case let .failed(failure): failureView(failure)
}
+ // Inside the fixed card (it scrolls when longer), so the card heights stay as they are.
+ if state.xcodeTooOldForNVN, state.xcode != .checking {
+ Text(t("onboarding.nvn.xcode")).font(.manrope(12)).foregroundStyle(.secondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
}
}
fixedCard {
diff --git a/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift b/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
index 87a67f06..83862062 100644
--- a/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
+++ b/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
@@ -15,6 +15,7 @@ import XCTest
var keyOutcome = KeyCheck.Outcome.fits
var games: [LibraryGame] = []
var xcodeWorks: Bool? // nil: follows the probe
+ var os = OperatingSystemVersion(majorVersion: 26, minorVersion: 6, patchVersion: 0)
}
func dep(_ id: String, present: Bool) -> BuildModel.Dep {
@@ -45,6 +46,7 @@ import XCTest
env.defaults = defaults
env.home = home.path
env.freeBytes = { 100_000_000_000 }
+ env.osVersion = { fake.os }
env.xcodeInstalled = { fake.xcodeWorks ?? (fake.probe.appPath != nil) }
env.xcodeFolderExists = { fake.probe.appPath != nil }
env.xcodeProbe = { fake.probe }
@@ -424,4 +426,46 @@ import XCTest
XCTAssertTrue(defaults.bool(forKey: OnboardingDefaults.completed))
XCTAssertFalse(defaults.bool(forKey: OnboardingDefaults.inProgress))
}
+
+ // MARK: NVN hints (macOS 26.6 / Xcode 27.1)
+
+ func testOSHintFollowsMacOSVersion() {
+ let fake = Fake()
+ for (v, old) in [((13, 0, 0), true), ((26, 5, 9), true), ((26, 6, 0), false), ((26, 6, 1), false), ((27, 0, 0), false)] {
+ fake.os = OperatingSystemVersion(majorVersion: v.0, minorVersion: v.1, patchVersion: v.2)
+ let (driver, _) = make(fake, deps: [])
+ XCTAssertEqual(driver.state.osTooOldForNVN, old, "\(v)")
+ }
+ }
+
+ func testXcodeHintFollowsProbeVersion() async {
+ let fake = Fake()
+ for (version, old) in [("26.4", true), ("27.0", true), ("27", true), ("27.1", false), ("27.2", false), ("28.0", false), (nil, false)] as [(String?, Bool)] {
+ fake.probe.version = version
+ let (driver, _) = make(fake, deps: [dep("metal", present: true), dep("xcode", present: true)])
+ await driver.refreshXcode()
+ XCTAssertEqual(driver.state.xcodeTooOldForNVN, old, "\(version ?? "nil")")
+ }
+ }
+
+ func testNoXcodeMeansNoXcodeHint() async {
+ let fake = Fake()
+ fake.probe = XcodeProbe(appPath: nil, version: "26.0")
+ let (driver, _) = make(fake, deps: [])
+ await driver.refreshXcode()
+ XCTAssertFalse(driver.state.xcodeTooOldForNVN)
+ }
+
+ func testHintsDoNotGateSetup() {
+ let fake = Fake(); fake.os = OperatingSystemVersion(majorVersion: 14, minorVersion: 0, patchVersion: 0)
+ let (driver, _) = make(fake, deps: [])
+ XCTAssertTrue(driver.state.osTooOldForNVN)
+ XCTAssertTrue(driver.state.canAdvance)
+ }
+
+ func testXcodeVersionParsing() {
+ XCTAssertEqual(OnboardingNVN.xcodeVersion(from: "Xcode 27.1\nBuild version 17A1\n"), "27.1")
+ XCTAssertEqual(OnboardingNVN.xcodeVersion(from: "Xcode 16.4 beta 2\n"), "16.4")
+ XCTAssertNil(OnboardingNVN.xcodeVersion(from: "xcode-select: error: tool 'xcodebuild' requires Xcode"))
+ }
}
diff --git a/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift b/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift
index affed05e..74c45bac 100644
--- a/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift
+++ b/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift
@@ -216,5 +216,28 @@ final class OnboardingTests: XCTestCase {
.write(to: output.appendingPathComponent("xcode-\(name)-en.png"))
window.orderOut(nil)
}
+ // The NVN hints (old macOS on Welcome, old Xcode on the Xcode step).
+ for lang: Lang in [.en, .zh] {
+ for step in [OnboardingStep.welcome, .xcode] {
+ var s = MockOnboardingDriver.sampleState
+ s.step = step; s.platform = .selected(.mac); s.xcode = .ready
+ s.setup = [.selected: .done, .license: .done, .firstLaunch: .done, .metal: .done]
+ s.background = [.python: .done, .dotnet: .done, .tools: .done]
+ s.osTooOldForNVN = true; s.xcodeTooOldForNVN = true
+ let driver = MockOnboardingDriver(state: s, lang: lang, animated: false)
+ let host = NSHostingView(rootView: OnboardingView(driver: driver, lang: lang))
+ let window = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 900, height: 680),
+ styleMask: [.titled, .closable, .resizable], backing: .buffered, defer: false)
+ window.contentView = host
+ window.orderFront(nil)
+ RunLoop.main.run(until: Date().addingTimeInterval(0.4))
+ host.layoutSubtreeIfNeeded()
+ let rep = try XCTUnwrap(host.bitmapImageRepForCachingDisplay(in: host.bounds))
+ host.cacheDisplay(in: host.bounds, to: rep)
+ try XCTUnwrap(rep.representation(using: .png, properties: [:]))
+ .write(to: output.appendingPathComponent("nvn-hint-\(step.rawValue)-\(lang.rawValue).png"))
+ window.orderOut(nil)
+ }
+ }
}
}