Skip to content

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

15.4 KB
Raw Blame

NX2Apple — Qt front end (Windows and macOS)

The SwiftUI app in ../frontend/ is the macOS-native one. This is the cross-platform counterpart: same job, same strings, built with PySide6 so Windows users get a native window.

Why a second front end

The build pipeline (scripts/build_ipa_from_nsp.py of the engine) is Python and runs on both systems, but the SwiftUI app cannot: it needs macOS. Rather than maintain two unrelated GUIs, this one is written once and runs everywhere Python and Qt do.

SwiftUI (frontend/) Qt (this)
Platforms macOS 13+ Windows 10+, macOS 11+
Language Swift Python 3.9+ for the launcher and its tests
Strings l10n/*.json, read by LocalizationFiles.swift the same files, read by nspb_qt/l10n.py
Build logic runs the Python scripts runs the same scripts

The strings are read from ../frontend/l10n/<code>.json, one file per language, so the two front ends cannot drift apart: a new string is a line in en.json and in zh.json. The language list comes from the files too (Lang.all(), each language's own name and the locale names that select it, Windows ones such as german included, are in its _language entry), so a new language is one new file and no change here. A frozen build carries the folder as l10n (build-qt.yml adds it with --add-data).

Run it

python3 -m venv .venv
.venv/bin/pip install PySide6            # Windows: .venv\Scripts\pip install PySide6
.venv/bin/python -m nspb_qt              # Windows: .venv\Scripts\python -m nspb_qt

From this folder. It looks for the repository checkout next to itself, in ~/NX2Apple, or wherever NSPB_REPO points, and the repository group lets you pick it by hand.

Look

nspb_qt/style.py follows the Mac launcher: near-black background, cream accent, the state colours of its LauncherPalette, and the Manrope typeface (SIL OFL 1.1). The font is not copied here: a source run loads ../frontend/fonts/Manrope.ttf, and the Windows build adds it and its licence to the bundle's fonts folder (build-qt.yml). If the file is missing the system font is used.

What works today

  • Dependency detection per platform: Python + packages, .NET SDK, and either Xcode + iOS SDK + Metal toolchain (macOS) or the Windows cross toolchain (see Windows build), plus xcodegen / zstd / spirv-cross. Each row has an install button when a command can fix it. The interpreter search covers the Pythons uv installs (~/.local/share/uv/python, ~/.local/bin, UV_PYTHON_INSTALL_DIR; %LOCALAPPDATA%\uv\python on Windows) and picks the newest one that runs at 3.12 or newer — the script's own floor — with the build packages.
  • Pick a game folder (or its four inputs separately). Base / update / DLC / prod.keys are recognised from the dump names.
  • Build: runs the same script the SwiftUI app runs, streams its stage lines and log, then packs the RomFS archive and reports where the IPA and archive landed.
  • --work-dir is passed only when the checkout's script declares it (an upstream checkout has no such option — issue #5).
  • Languages: every language that has a file in frontend/l10n (today Chinese, Swedish, German and French) on devices in that language, English elsewhere, and the header button cycles through them.

What is not there yet

  • The Windows build path remains experimental. One Rhythm Heaven Groove 1.0.0 IPA built on Windows installed and launched on an iPhone Air running iOS 27.0.1; Play started the game, and the button mappings were correct. That IPA needed three local changes beyond this branch: seedds/nxnative#591 (the Windows image reader), an updated dmsh_chain.lock with a regenerated DMSH_CHAIN for this machine's SPIRV-Cross and Metal tools, and a two-line declaration of CMMotionManager.deviceMotionBody because the Windows toolchain still ships iPhoneOS26.0.sdk. SDK symlinks were materialized by hand. The current unmodified frontend is not yet verified end to end; other games and longer-term performance remain unverified. See Windows build → Open risks.
  • Self-update (nspb_qt/app_update.py): checks releases/latest for NX2Apple-windows-x64.zip, verifies the SHA-256 digest when present, unpacks and swaps the bundle in place via a detached updater script after the running process exits. Repository download and update buttons also exist (Download repository, Check for updates), logging what git is doing.
  • No per-stage progress bar, no cancel-with-cleanup (cancel terminates the child).

Layout

nspb_qt/
  __main__.py       entry point
  model.py          state, dependency detection, build runner (Qt signals, no widgets)
  ui.py             the window
  platform_util.py  per-OS paths, tool discovery, child environment
  i18n.py           language choice
  l10n.py           the texts, read from ../frontend/l10n/*.json (the SwiftUI app reads the same files)
  win/              the Windows build path; imported only when sys.platform is win32
tests/test_win.py   the Windows-path tests that can run on macOS

Windows build

On a Windows PC the pipeline cannot call xcrun, xcodebuild or xcodegen, and scripts/build_ipa_from_nsp.py does not even import (pwd is a POSIX-only module). So the app does not run the script directly on Windows. It runs nspb_qt/win/driver.py, which loads the upstream file as a module, replaces the steps that assume a Mac, and calls its cli().

The upstream file is never edited, so the daily sync cannot conflict with this work.

What each macOS step becomes

macOS Windows
xcodegen + xcodebuild LLVM clang per source file, linked by ld64.lld
Launcher.swift (SwiftUI) win/ios/Launcher.m (UIKit, same dm_show_launcher contract)
xcrun -sdk iphoneos metal Apple's Metal Developer Tools for Windows: metal.exe / metallib.exe
xcrun -sdk iphoneos clang LLVM-MinGW clang.exe with -target arm64-apple-ios26.0 -isysroot <SDK>
actool asset catalog loose PNGs named in CFBundleIcons (Pillow)
sips / plutil Pillow / plistlib
Darwin compiler-rt (@available) win/ios/compat_rt.c, linked only when LLVM has no libclang_rt.ios.a
make -n -B dmhost (source list) the Makefile rules reproduced in build_app.host_sources(), checked against the Makefile text
dmsh_xlate apphost (a Mach-O) dotnet dmsh_xlate.dll, the same locked build
which, python3, ctypes.CDLL(None) sitecustomize.py rewrites them at the subprocess boundary
app icon via actool Pillow, five sizes
codesign ad-hoc + entitlements skipped, since the sideloader re-signs the IPA anyway
the IPA's Unix x bit win/fix_ipa_modes.py rewrites the zip's central directory in place

What you need to install

The app installs everything it can itself: the Dependencies panel has an Install button per row and Install all missing, and the rows it can fetch are .NET SDK, LLVM-MinGW and the iPhoneOS SDK. What it cannot fetch is Apple's Metal Developer Tools (an Apple ID login) and the optional Vulkan/GL tools.

Everything it downloads goes to %LOCALAPPDATA%\NS Port Builder\tools, outside the app folder, so updating the app (re-extracting its zip) does not throw the 182 MB LLVM archive away.

Run this first if you prefer the command line. It lists what is missing and where to get it:

python -m nspb_qt.win.doctor
  1. Python 3.12+ for the game build scripts, then pip install PySide6 lz4 capstone fonttools zbic pillow (and backports.zstd before Python 3.14).

  2. .NET SDK 10 — the app downloads it (the zip, not the installer: no administrator rights, about 287 MB), or get it from https://dotnet.microsoft.com/download/dotnet/10.0 (SDK, x64). nx_extract targets net10.0, so SDK 8 or 9 alone is not enough, and the dependency row says so rather than failing halfway through a build.

  3. LLVM-MinGW 20261020 — the app's Dependencies panel downloads and verifies it, or:

    python -m nspb_qt.win.doctor --fix
    

    Pinned SHA-256 (also in toolchain.py):

    archive SHA-256
    llvm-mingw-20261020-ucrt-x86_64.zip fd5462b7f5d93b2ff981fcd3f9c7e427e47f3203c64ea91c27bcc444eebd74cd

    Only the x86-64 archive is published by this app, so a Windows-on-ARM machine runs it under emulation (the dependency panel says so in a host architecture row).

    The official LLVM-*-win64.msi from llvm.org works too (same clang, same LLD).

  4. An iPhoneOS SDK 26.x — either route works:

    python -m nspb_qt.win.doctor --sdk                     :: git, no Apple ID
    python -m nspb_qt.win.doctor --sdk-xip Xcode_26.5.xip  :: Apple's own, free Apple ID
    python -m nspb_qt.win.doctor --import-sdk D:\SDKs\iPhoneOS26.0.sdk
    

    The git route sparse-clones one SDK out of xybp888/iOS-SDKs. The .xip route streams Apple's archive and writes only Platforms/iPhoneOS.platform/Developer/SDKs/.

  5. Metal Developer Tools for Windows 6.x — https://developer.apple.com/download/all/?q=metal%20developer%20tools (free Apple ID). The app cannot download this for you: Apple gates it behind a login.

  6. spirv-cross and zstd — Windows builds. The Vulkan SDK has spirv-cross (and glslangValidator), and zstd has releases on GitHub.

If auto-detection picks the wrong folder, set it in %LOCALAPPDATA%\NS Port Builder\toolchain.json:

{
  "llvm_dir": "D:\\tools\\llvm-mingw-20261020-ucrt-x86_64",
  "ios_sdk": "D:\\SDKs\\iPhoneOS26.0.sdk",
  "dotnet_dir": "C:\\Program Files\\dotnet",
  "metal_dir": "C:\\Program Files\\Metal Developer Tools",
  "spirv_cross_dir": "C:\\VulkanSDK\\1.4.321.0\\Bin",
  "zstd_dir": "C:\\tools\\zstd"
}

Each key also has an environment variable (NSPB_LLVM_DIR, NSPB_IOS_SDK, NSPB_DOTNET_DIR, NSPB_METAL_DIR, …), which wins over the file.

Downloads, mirrors, and no console windows

Three things about how the app fetches its tools are worth knowing, because each of them was a bug report from a handheld PC on a mainland connection:

Mirrors. GitHub release assets are the slow ones. Every download tries the direct URL plus two mirrors (ghfast.top, gh-proxy.com), and picks between them by timing a 256 KB ranged request — the report that prompted this was a 974-second download that succeeded, so failing over on errors alone would never have helped. The pinned SHA-256 is the only thing that decides what gets unpacked: a mirror serving different bytes is rejected exactly like a corrupted download. Microsoft's CDN (the .NET SDK) is not mirrored, because it is fast enough on its own.

Where tools land. %LOCALAPPDATA%\NS Port Builder\tools. Not inside the app folder: the app ships as a zip that gets re-extracted for every update, which would take 182 MB of LLVM with it. Older builds used <app>\_internal\.tools and that path is still read, so an existing install keeps working.

No console windows. The app is a windowed process, so every child it started — git, clang, lld, the PortableGit self-extractor, and the repository's own Python scripts — used to get its own black console window. On a handheld that read as "a command line appears, shows nothing, and the install stops". platform_util.hide_console_for_children() patches subprocess.Popen once at start-up, so children of children inherit an invisible console too.

Verify each step

nspb_qt.win.toolchain does not trust that a path exists — it runs the tool:

check what it proves
probe_compile clang -target arm64-apple-ios26.0 -isysroot <SDK> -c writes a 0xfeedfacf arm64 MH_OBJECT
probe_link ld64.lld links an arm64 MH_EXECUTE with LC_BUILD_VERSION platform 2 (iOS)
probe_metal metal.exe → .air, then metallib.exe → a non-empty .metallib
python -m nspb_qt.win.doctor            :: human-readable, runs the probes
python -m nspb_qt.win.doctor --json     :: for a bug report

Exit code 0 means every required row passed its probe.

The one thing llvm-mingw gets wrong

llvm-mingw's release script (strip-llvm.sh) deletes ld64.lld.exe, so the zip only has ld.lld.exe. That is not a dead end: LLD is one binary containing every driver and picks one from argv[0]. Copying ld.lld.exe to ld64.lld.exe gives the Mach-O linker, and the app does that automatically (toolchain.ensure_ld64_lld). A build of LLD that was stripped down to ELF only is detected (MachO / ld64.lld strings absent) and reported instead of failing at link time.

Known unsupported game types

These need the game's own arm64 code to run, which upstream does inside a Mac host. No Windows PC can do that, so the build stops with an explanatory message rather than producing a broken IPA:

  • Run-time shader capture — GLSLC capture (Fire Emblem: Three Houses, Portal), Vulkan capture (Super Mario Galaxy), GL capture of a non-LÖVE game. The game compiles its shaders only while running.
  • Unreal / Oodle decoding — games whose shaders sit inside Oodle-compressed or Trinity packs (Pokémon Legends: Z-A, PlatinumGames titles, DRAGON QUEST XI S, …). Upstream decodes them by running the game's own decoder.
  • The heap check for a provisional profile. Replaced by an estimate (a 2 GB pool for a game with virtual address memory). See driver.heap_check.
  • The pipeline archive (pso_offline.py / metal-tt). Apple's Windows Metal tools do not ship metal-tt, so DM_PSO_GPUS is forced to none: the device builds those pipeline bases on its first start instead (slower first launch, same result).
  • --prepare-xcode, --platform mac and --platform mac-app. Refused up front.

Games whose shaders are in the RomFS — Mario Wonder, Odyssey, Mario Kart 8 Deluxe, the Zelda titles, Metroid Dread — do not need any of that.

Run a build

python -m nspb_qt.win.driver D:\Games\MarioWonder -k D:\keys\prod.keys

The options are the upstream script's (-h). The IPA is unsigned, as on a Mac: sign it with Sideloadly (Windows), AltStore, or similar, and enable the Increased Memory Limit capability if the tool offers it. The IPA name and the RomFS archive come out where the macOS build puts them.

Open risks

The frontend's setup has run on Windows, and one locally patched Windows build installed, launched and started the game on an iPhone. That test does not settle these risks for other games or for an unmodified checkout:

  1. Shader libraries on the device. They come from the Windows Metal compiler, not Xcode's. They must load and render on iOS 26+ (newLibraryWithURL). own_compilers.py accepts a different compiler version, so the build will not fail — only a device run proves it.
  2. The real rewritten modules. Sections hundreds of MB, linked by ld64.lld, then signed by the sideloader.
  3. The UIKit launcher. win/ios/Launcher.m is a hand port of Launcher.swift. It honours section grouping, a toggle's on/off values, env-file locking and Reset, but no one has tapped through it on a device.
  4. Icons without an asset catalog on iOS 26.
  5. Line endings. The checkout must keep LF. The shader chain hashes source bytes, so a CRLF checkout breaks dmsh_xlate --source-sha. .gitattributes enforces this, but a ZIP download with autocrlf on can still break it.

nspb_qt/win/doctor.py is the fastest way to narrow a failure: it separates "a tool is missing" from "the tool exists but cannot do the job".