Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Swift apple-siliconcustom-formathomebrewiosipaipadipadosiphonemetalnative-portnintendo-switchnxnativeromfsswitch-games
Onboarding hints that NVN games need Xcode 27.1 and macOS 26.6
v0lumehi2ad23c010b2e
diff --git a/frontend/Onboarding.md b/frontend/Onboarding.mdindex 1048e583..7443ed4b 100644--- a/frontend/Onboarding.md+++ b/frontend/Onboarding.md@@ -11,12 +11,14 @@ NSPB_ONBOARDING_DEMO=xcodeReady swift runNSPB_ONBOARDING_DEMO=keysInvalid swift runNSPB_ONBOARDING_DEMO=xcodeFailed swift runNSPB_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 choicesThe 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.swiftindex 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 Toolsvar licenseAccepted = falsevar firstLaunchDone = false+ var version: String? // from `xcodebuild -version` of appPath ("27.1"); nil when unreadablevar developerDir: String? { appPath.map { $0 + "/Contents/Developer" } }var needsAdmin: Bool { !(selectedIsXcode && licenseAccepted && firstLaunchDone) }}@@ -29,6 +30,7 @@ struct OnboardingEnvironment {var defaults: UserDefaults = .standardvar 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 = trueprobe.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) } ?? neededstate.welcome = .requirements(freeGB: free, neededGB: needed)+ state.osTooOldForNVN = OnboardingNVN.osTooOld(env.osVersion())+ state.xcodeTooOldForNVN = probed && probe.appPath != nil && OnboardingNVN.xcodeTooOld(probe.version)}// MARK: Xcodediff --git a/frontend/Sources/NSPortBuilder/Localization.swift b/frontend/Sources/NSPortBuilder/Localization.swiftindex 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.swiftindex 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: OnboardingStateprivate(set) var resumeSnapshot: OnboardingState?let scenario: Scenario@@ -20,6 +20,7 @@ import Foundationinit(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.swiftindex 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, bothvar includesIOS: Bool { self != .mac }@@ -100,6 +127,9 @@ struct OnboardingState: Equatable {var games: Games = .emptyvar done: Done = .celebratingvar 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 = falsevar selectedPlatform: OnboardingPlatform? {if case let .selected(value) = platform { return value }diff --git a/frontend/Sources/NSPortBuilder/OnboardingView.swift b/frontend/Sources/NSPortBuilder/OnboardingView.swiftindex 538cc522..26ad6f8a 100644--- a/frontend/Sources/NSPortBuilder/OnboardingView.swift+++ b/frontend/Sources/NSPortBuilder/OnboardingView.swift@@ -174,6 +174,11 @@ import UniformTypeIdentifiersText(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.swiftindex 87a67f06..83862062 100644--- a/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift+++ b/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift@@ -15,6 +15,7 @@ import XCTestvar keyOutcome = KeyCheck.Outcome.fitsvar 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 XCTestenv.defaults = defaultsenv.home = home.pathenv.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 XCTestXCTAssertTrue(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.swiftindex 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)+ }+ }}}