v1.2.2

v1.2.2: Fix for the iPhone and iPad shared app shader library copy, and end-to-end nxbuild in the experimental builder.

English

New

• Experimental builder runs nxb build end to end: when Settings, Use experimental builder is turned on, the Mac launcher now runs nxb build for the whole game build and does not run the Python build script at all, for a Mac app and for the iPhone and iPad options. It reads NSP, NSZ, XCI, merged packages, a Switch 2 NUP, a game folder and DLC, and surveys a game with no profile. There is no fallback to the script: a case nxb does not take, or a failure, shows nxb's exit code and its last error line. The app bundles nxbuild 0.5.1. The setting is off by default and nothing changes for a default build (#749, #794)
• Controller texts in French, Italian and Swedish: 26 controller and Steam Controller (2026) strings are now translated into French, Italian and Swedish, waiting for a native review. By @v0lumehi (#789)
• Guide: updating a built Mac game: the English and Chinese player guides now walk through Rebuild, the update picker and the existing output folder, say which work the build can reuse, and explain why the same title keeps its saves. This documents the current workflow and is not an in-place updater. Asked in #796. By @thehobbit85 (#796, #805)
• Windows: NX2Apple.exe and in-app update: the Windows launcher is now NX2Apple/NX2Apple.exe inside NX2Apple-windows-x64.zip and no longer NS Port Builder. The old settings folder and library stay where they are, so downloaded tools and the game library carry over. The launcher checks the latest release for the Windows zip, verifies its SHA-256 digest when there is one, and swaps the install in place with a small updater, with an update button in Settings and a pill in the top bar. The updater also removes the old NS Port Builder.exe. Paths with non-ASCII characters are handled (#812)
• Engine pin 88c7e03f51e3 (28 upstream commits): the Legend of Zelda: Ocarina of Time on Switch 2 plays on the Mac at about 59 fps through Kokiri Forest and uses about 4 GB less memory on an external drive (seedds/nxnative#1299). Kirby Air Riders on Switch 2 plays on the Mac at 60 fps through whole races, at about 10 GB. Both are Mac only, by upstream's notes, and nobody has played them on this fork yet. The engine_id is now 88c7e03f51e3934dc227089ea81ec64fcd525b03-5d39f3354ad8 (#813)

Fixed

• iPhone and iPad shared app build (FAIL: copy the shader libraries): since the 1.2.0 engine pin 7249ee9f95ed, an NVN game's iOS shader library is packed into the single file shader/ios/b-<chain>.img and the folder b-<chain>/ is removed. The framework build step for the shared iPhone and iPad app still looked for the folder, so every NVN game build for the shared shell stopped at rsync: .../shader/ios/b-223f10d34f97/: (l)stat: No such file or directory and FAIL: copy the shader libraries. It now copies b-<chain>.img into the game framework's msl/ folder, where the host loads it. Reported by @zhukangyu26-stack, @tnt739660506-prog and @caixukun1919810114514. By @xiaofeng-han (#781, #795, #800, #782)
• Switch 2 library cover banners: the eight Switch 2 and Nintendo Classics games not yet listed in titledb now have fallback horizontal cover banners in the Mac and Windows launchers (#808)
• Windows game folder build (FileNotFoundError: [WinError 2] at pack v...): pack_dump.py tried cp -c for an APFS clone before falling back to shutil.copy2, which raised FileNotFoundError on Windows where cp does not exist. The Windows driver and shim now copy directly without spawning cp or xattr (#803)
• Windows shader split on 32+ thread CPUs (ValueError: max_workers must be <= 61): the Windows build environment and ProcessPoolExecutor now cap worker count at 61, CPython's WaitForMultipleObjects limit on Windows (#803)
• Windows iOS shader build in Chinese or non-ASCII folders (no iOS shader libraries): Apple's Windows metal.exe and metallib.exe fail to open paths containing non-ASCII characters or spaces. The Windows xcrun shim and shader cache/PCH helpers now stage non-ASCII inputs and outputs through a pure-ASCII temporary folder (#810)
• Shader split sitting at 99%: the Mac launcher's build activity bar can stay at 99% for several minutes while the last batch of shader files is scanned. When the engine reports 1 to 16 files left in the splitting step, the bar now says that scanning the last few files can take several minutes, in all six languages. The scan time itself is not changed. By @thehobbit85 (#489, #806)
• iPhone data transfer skipped for an updated game with the same size: the Mac launcher could say an iPhone already held the game data when an update produced a different romfs.img of exactly the same size. It now compares the RomFS identity (size, a hash of the header and index, and the framework version and build) with a receipt of the last successful copy for that title, device and app container, and copies the image when the receipt is missing or different. The receipt only knows this Mac's copies, and a change confined to payload bytes under the same version and index is not seen. The prompt text about the version change from #261 stays open. By @thehobbit85 (#261, #807)
• Qt launcher tests on macOS's Python 3.9: the pre-push check failed nine tests with the system Python 3.9.6. The Windows shim installer used a Python 3.10-only keyword and now writes the exact UTF-8 bytes, keeps timestamps on a second install, and four Qt-free tests call the underlying function. The README now says Python 3.9 or later for the launcher and its tests, and 3.12 or later for the game build scripts. Reported by @Koshindai. By @thehobbit85 (#799, #804)
• iOS 26.0 crash before the first frame: with Metal 4 pipelines on, the specialization descriptor was owned twice. It is now owned once, whether the driver returns it retained or autoreleased. Upstream PR #1213 by @mmkzer0, engine commit 88c7e03f (#813)
• Games with a big memory layout: the Mac's alias region is now the Switch's 64 GB, so a game can lay out its regions past the iPhone-sized value, and a provisional profile keeps the alias region out of the heap. A game whose memory pool does not fit an iPhone's memory limit keeps its guest memory in files (new switches DM_GUEST_FILE, DM_GUEST_FILE_CHUNK, DM_GUEST_FILE_DIR, DM_GUEST_FILE_MIN_FREE) (#813)
• Audio: each renderer plays from its own PCM blocks, and the SDK 22 audio update lock is found again, which fixes a render thread crash in Ocarina of Time (#813)
• No repacking of game data after a reboot: the RomFS image identity no longer includes st_dev, which macOS changes at each mount. Upstream PR #1354 by @lunks (#813)
• Build checks and shader tables: the NSP script looks for the zbic package before it extracts anything, so a game with ZBIC modules fails at the start and not after the whole RomFS is unpacked. An Oodle shader table is proven by a decode, and a package that does not read costs only itself, so OCTOPATH TRAVELER II no longer stops its split at 11,832 of 13,980 shaders (#813)
• Game fixes from the engine: Mario Strikers: Battle League shaders from revision-4 archives and its movie decoder thread, both by @sen-6ei. Assassin's Creed Revelations event pool query, by @Fbenhaddou. Axiom Verge sky on iOS. Super Smash Bros. Ultimate update pages. Fire Emblem Fortune's Weave depth mode. Super Mario Galaxy 2 cutscene crop. Splatoon Raiders cube arrays. Breath of the Wild tile functions. Unreal dynamic buffers keep 4 copies. A workaround for the Pokemon Legends: Arceus capture demo (#813)
• Library game strip on Windows: with many games, the horizontal strip widened the whole Library page and the hero banner to 2760 pixels. It is now clipped, scrolls with wheel and trackpad, and keeps the selected card in view (#812)
• Windows first-run setup assistant: opening the Windows launcher for the first time now presents the guided setup dialog automatically once dependency detection finishes (#803)

Known issues

• Experimental builder (nxb build): the iPhone and iPad path and the new input kinds have not yet been run on a device with real game files (#749, #794)
• Every NVN game built before is built again once: the shader chain moved from 223f10d34f97 to adec7d81d970 with the engine pin (#449, #813)
• Engine pin 88c7e03f51e3: we have not run a real game on this build. The Ocarina of Time and Kirby Air Riders numbers are upstream's, from its own Mac tests (#813)
• Windows update and new name: the self-update and the NX2Apple.exe rename are covered by unit tests in the pull request. Nobody has run an update from a real release on Windows yet (#812)
• Shader split hint and iPhone data receipt: both were checked with synthetic progress events and a synthetic device container on an Apple Silicon Mac, not with a real game build or a real iPhone (#806, #807)
• Qt shim installer: the fix was tested on macOS with Python 3.9.6 and 3.14.6, and the Windows execution was not run (#804)

Requires

• iOS or iPadOS 26 or later
• To build NVN games on a Mac: Xcode 27.2 and macOS 26.6 or later

中文

新增

• 实验性构建器全程运行 nxb build：开启设置里的「使用实验性构建器」后，Mac 启动器现在直接运行 nxb build 完成整个游戏构建，完全不运行 Python 构建脚本，Mac App 和 iPhone、iPad 选项都是如此。它读取 NSP、NSZ、XCI、合并包、Switch 2 NUP、游戏文件夹和 DLC，并勘测没有配置的游戏。不会退回脚本：nxb 不支持的情况或失败时，会显示 nxb 的退出代码和最后一条错误。App 内置 nxbuild 0.5.1。该设置默认关闭，默认构建不受影响（#749、#794）
• 法语、意大利语和瑞典语手柄设置本地化：补齐 26 条手柄设置与 Steam Controller（2026）的法语、意大利语和瑞典语翻译，等待母语者审校。作者 @v0lumehi（#789）
• 指南：更新已构建的 Mac 游戏：中英文玩家指南现在逐步说明「重新构建」、更新包选择和已有的输出文件夹，指出构建可以复用哪些工作，并解释为什么同一游戏的存档会保留。这记录的是现有流程，不是原地更新功能。需求见 #796。作者 @thehobbit85（#796、#805）
• Windows：NX2Apple.exe 和应用内更新：Windows 启动器现在是 NX2Apple-windows-x64.zip 里的 NX2Apple/NX2Apple.exe，不再叫 NS Port Builder。旧的设置文件夹和游戏库保持原位，已下载的工具和游戏库会继续使用。启动器会检查最新发布里的 Windows 压缩包，有 SHA-256 摘要时会校验，并用一个小更新程序原地替换安装，设置里有更新按钮，顶栏有更新提示。更新程序还会删除旧的 NS Port Builder.exe。含非 ASCII 字符的路径也能处理（#812）
• 引擎固定点 88c7e03f51e3（上游 28 个提交）：《塞尔达传说：时之笛》Switch 2 版在 Mac 上穿过科奇里森林时约 59 fps，在外置硬盘上少用约 4 GB 内存（seedds/nxnative#1299）。Switch 2 版 Kirby Air Riders 在 Mac 上整场比赛 60 fps，约 10 GB。两者按上游说明都只限 Mac，我们这个分支还没有人玩过。engine_id 现在是 88c7e03f51e3934dc227089ea81ec64fcd525b03-5d39f3354ad8（#813）

修复

• iPhone 和 iPad 共用壳 App 构建（FAIL: copy the shader libraries）：从 1.2.0 的引擎版本 7249ee9f95ed 起，NVN 游戏的 iOS 着色器库会被打包成单个文件 shader/ios/b-<chain>.img 并删除原文件夹 b-<chain>/。共用 iPhone 和 iPad 壳 App 的框架构建步骤仍在查找原文件夹，导致所有 NVN 游戏的共用壳构建都在最后停在 rsync: .../shader/ios/b-223f10d34f97/: (l)stat: No such file or directory 和 FAIL: copy the shader libraries。现在它会把 b-<chain>.img 复制进游戏框架的 msl/ 目录供宿主直接读取。由 @zhukangyu26-stack、@tnt739660506-prog 和 @caixukun1919810114514 报告。作者 @xiaofeng-han（#781、#795、#800、#782）
• Switch 2 游戏库封面横幅：为 titledb 尚未收录的 8 款 Switch 2 与 Nintendo Classics 游戏在 Mac 和 Windows 启动器中补齐了横向封面横幅（#808）
• Windows 游戏文件夹构建（pack v... 阶段报 FileNotFoundError: [WinError 2]）：pack_dump.py 在回退到 shutil.copy2 前会先尝试运行 cp -c 做 APFS 克隆，而在没有 cp 命令的 Windows 上直接抛出了 FileNotFoundError。现在 Windows 驱动和垫片层直接复制文件，不再调用 cp 或 xattr（#803）
• Windows 32 线程及以上 CPU 在 shader split 阶段报 ValueError: max_workers must be <= 61：Windows 构建环境与 ProcessPoolExecutor 现在将工作进程数上限封顶在 61（Windows 版 Python WaitForMultipleObjects 的硬上限）（#803）
• Windows 中文或非 ASCII 目录构建 iOS 着色器失败（no iOS shader libraries）：苹果 Windows 版 metal.exe 与 metallib.exe 无法打开含中文或空格的路径。现在 Windows xcrun 垫片及着色器预编译头/编译缓存会自动通过纯 ASCII 临时目录暂存并回写输入输出文件（#810）
• 着色器拆分停在 99%：Mac 启动器的构建活动条在扫描最后一批着色器文件时可能停在 99% 数分钟。当引擎报告拆分步骤还剩 1 到 16 个文件时，活动条现在会提示扫描最后几个文件可能需要几分钟，六种语言都有。扫描时间本身没有变。作者 @thehobbit85（#489、#806）
• 更新后大小相同的游戏被跳过 iPhone 数据传输：更新生成了大小完全相同但内容不同的 romfs.img 时，Mac 启动器可能误判 iPhone 已有游戏数据。现在它会比较 RomFS 标识（大小、头部与索引的哈希、框架版本和构建号）与该游戏、设备和 App 容器上次成功复制的回执，回执缺失或不同就复制镜像。回执只记录这台 Mac 的复制，只改动数据内容而版本和索引不变的变化看不到。#261 中提示框要说明版本变化的需求仍未完成。作者 @thehobbit85（#261、#807）
• Qt 启动器测试在 macOS 自带的 Python 3.9 上失败：推送前检查在系统 Python 3.9.6 上有九个测试失败。Windows 垫片安装器用了只有 Python 3.10 才有的参数，现在改为写入精确的 UTF-8 字节，第二次安装保留时间戳，四个不依赖 Qt 的测试改为调用底层函数。README 现在写明启动器及其测试需要 Python 3.9 或更高，游戏构建脚本需要 3.12 或更高。由 @Koshindai 报告，作者 @thehobbit85（#799、#804）
• iOS 26.0 在第一帧前崩溃：开启 Metal 4 管线时，特化描述符被持有了两次。现在无论驱动返回的是已保留还是自动释放的对象，都只持有一次。上游 PR #1213，作者 @mmkzer0，引擎提交 88c7e03f（#813）
• 内存布局很大的游戏：Mac 的别名区域现在是 Switch 的 64 GB，游戏可以把区域布置在 iPhone 大小的数值之后，临时配置的堆检查会让别名区域不进入堆。内存池放不进 iPhone 内存上限的游戏，会把来宾内存放在文件里（新开关 DM_GUEST_FILE、DM_GUEST_FILE_CHUNK、DM_GUEST_FILE_DIR、DM_GUEST_FILE_MIN_FREE）（#813）
• 音频：每个渲染器从自己的 PCM 块播放，SDK 22 的音频更新锁重新被找到，修复了时之笛渲染线程的崩溃（#813）
• 重启后不再重新打包游戏数据：RomFS 镜像标识不再包含 macOS 每次挂载都会变的 st_dev。上游 PR #1354，作者 @lunks（#813）
• 构建检查和着色器表：NSP 脚本在解压任何文件之前先检查 zbic 包，含 ZBIC 模块的游戏会在开始时就失败，而不是解完整个 RomFS 才失败。Oodle 着色器表由解码来证明，读不出的包只影响它自己，所以 OCTOPATH TRAVELER II 的拆分不再停在 13,980 个着色器中的 11,832 个（#813）
• 引擎带来的游戏修复：Mario Strikers: Battle League 的第 4 版档案着色器和视频解码线程，作者都是 @sen-6ei。Assassin's Creed Revelations 的事件内存池查询，作者 @Fbenhaddou。iOS 上 Axiom Verge 的天空、Super Smash Bros. Ultimate 更新页面、Fire Emblem Fortune's Weave 深度模式、Super Mario Galaxy 2 过场裁剪、Splatoon Raiders 立方体数组、Breath of the Wild 图块函数、Unreal 动态缓冲保留 4 份，以及 Pokemon Legends: Arceus 捕捉演示的临时处理（#813）
• Windows 游戏库横向条：游戏很多时，横向条会把整个游戏库页面和主横幅撑到 2760 像素宽。现在会被裁剪，支持滚轮和触控板滚动，并让选中的卡片保持在视野内（#812）
• Windows 首次启动设置向导：全新首次打开 Windows 启动器时，依赖检测完成后会自动弹出引导式设置向导（#803）

已知问题

• 实验性构建器（nxb build）：iPhone 和 iPad 路径以及真实游戏文件的新输入类型尚未在真机上运行过（#749、#794）
• 以前构建的每个 NVN 游戏都要重新构建一次：着色器链随引擎固定点从 223f10d34f97 变为 adec7d81d970（#449、#813）
• 引擎固定点 88c7e03f51e3：我们没有在这个构建上运行过真实游戏。时之笛和 Kirby Air Riders 的数字来自上游自己的 Mac 测试（#813）
• Windows 更新和新名称：自更新和 NX2Apple.exe 改名有单元测试覆盖，还没有人在 Windows 上用真实发布版本运行过一次更新（#812）
• 着色器拆分提示和 iPhone 数据回执：两者只在 Apple 芯片 Mac 上用模拟的进度事件和模拟的设备容器检查过，没有用真实的游戏构建或真实的 iPhone（#806、#807）
• Qt 垫片安装器：修复在 macOS 上用 Python 3.9.6 和 3.14.6 测试过，没有在 Windows 上运行（#804）

系统要求

• iOS 或 iPadOS 26 或更高版本
• 在 Mac 上构建 NVN 游戏：Xcode 27.2 和 macOS 26.6 或更高版本

---

What's Changed

Features

• Controller texts in French, Italian and Swedish by @v0lumehi in #789
• Engine: bump the pin to 88c7e03f (Ocarina of Time on Switch 2 and more) by @v0lumehi in #813

Patch queue and engine

• iOS shell: copy a game's packed shader image into its framework by @xiaofeng-han in #782

Documentation

• Experimental builder: the launcher runs nxb build, not the script (nxbuild 0.5.1, version 1.2.2) by @v0lumehi in #794
• docs: add #782 to the 1.2.2 changelog and release notes by @LNPANDY in #801
• fix(win): fix pack_dump clone, high-core ProcessPoolExecutor cap, and first-launch onboarding by @LNPANDY in #803
• fix(win): stage Metal shader compiles when game or build paths contain non-ASCII characters by @LNPANDY in #810
• Docs: explain how to update a built Mac game and keep its saves by @thehobbit85 in #805
• Keep Qt pre-push tests working on macOS’s Python 3.9 by @thehobbit85 in #804
• docs: update v1.2.2 changelog and release notes for rc4 by @LNPANDY in #811

Other changes

• Launcher: add fallback banners for Switch 2 titles missing from titledb by @LNPANDY in #808
• Explain why the last shader files can take minutes to scan by @thehobbit85 in #806
• Copy updated iPhone game data when the RomFS image keeps its size by @thehobbit85 in #807

New Contributors

• @xiaofeng-han made their first contribution in #782

Full Changelog: v1.2.1...v1.2.2