LumaDock 0.2.10

LumaDock 0.2.10

Changes

• Read every package in merged NSP/XCI files. Register the base game, embedded updates and DLC from their own content metadata, while keeping one managed copy of the physical container. Reimport repairs older single-package records; after preparing the updated engine reader, existing managed containers are rescanned automatically. Extraction selects the requested title and version instead of choosing an arbitrary NCA of the same type.
• Prepare the imported version with recent nxnative engines. When the selected engine provides the derived-profile API, use the newest imported game version and generate a private profile and shader tables when registered builds or their shader inputs do not match. Registered builds retain their applicable fixes. Derived builds use their own shader inputs, C1/CB tables, cache identity and experimental status. Older engines retain explicit version requirements; games with no matching profile remain unsupported.
• Preserve successful work on failure. Validate shader input stamps and iOS shader platforms before checkpointing. Cancellation, shader failures and failed installation preserve the previous runtime and saves; retry verifies reusable extraction, rewrite and shader-split stages.
• Unify the task banner. Place the global task banner within the content area's background and use the same native Liquid Glass surface as the other controls. Remove its extra button background and the toolbar keyboard button; input mapping remains available in Settings and game details.
• Protect running applications during packaging. Refuse to replace an output app while its executable or runtime children are running. Build and validate a complete signed app in a staging directory; restore the previous app if publication or relocated-runtime validation fails. --output-dir supports independent local builds. Verify the bundled Python can launch the bundled spirv-cross with a GUI-style PATH, both before and after relocation. Missing spirv-cross now reports shader_tool_missing rather than game shader incompatibility.

Installation and validation

The release workflow builds LumaDock-0.2.10-arm64.dmg and its source archive. Verify SHA256SUMS, quit any running LumaDock copy and its tasks, then replace the app in Applications. Requires Apple Silicon and macOS 26+. This release still uses ad-hoc signing and is not notarized; a valid local code signature does not guarantee Gatekeeper approval. A Developer ID Application certificate and Apple notarization are required for normal identified-developer distribution.

After upgrading, prepare the engine tools again in Settings to update the container reader. Existing managed game files can then be rescanned without another import. A shader task interrupted by an app replacement can be retried after reopening the complete app; keep the sources, keys and successful caches.

Local verification passed 156 Python tests and 61 Swift Release tests, plus the later appearance/progress regression subset after the toolbar adjustment. Synthetic pipelines cover derived Mac/iOS preparation, cache reuse, cancellation, failures, wrong shader stamps and wrong iOS shader platforms. The actual nxnative derivation API was checked with synthetic input. Read-only inspection of a player's merged XCI identified both its base and embedded update, and the version planner selected the update without requiring another registered version. The native metadata reader compiled against LibHac 0.19. Signed local apps passed runtime, nested spirv-cross execution and distribution-boundary checks; a separate synthetic window was visually checked in light, dark and high-contrast appearances.

Validation limits: these checks do not establish successful full compilation or gameplay of the player's 1.0.1 game, iOS device compatibility, or Gatekeeper/notarization acceptance. Tag CI rebuilds and validates public artifacts before publishing them; its completion is not claimed by these local results.

No engine, games, updates, DLC, firmware, player keys, artwork, saves or player caches are included. Third-party notices remain in the bundled documentation.

---

中文说明

• 完整识别合并容器。 按各自内容元数据登记 NSP/XCI 中的本体、内置更新及 DLC，共用一份托管副本。重新导入可修复旧记录；准备新版读取器后，自动重扫已有托管文件。解包器明确选择标题与版本，避免取错同类型 NCA。
• 接入 nxnative 动态派生。 所选引擎提供相应接口时，选择已导入的最新游戏版本；登记版本或着色器素材不匹配时，在私有缓存生成独立配置和着色器表。登记版本保留对应修复；派生版本使用自己的着色器、C1/CB 表与缓存，并标为实验性。旧引擎继续校验指定版本，没有对应游戏配置时仍不能构建。
• 保留成功阶段。 着色器输入标记与 iOS 编译平台验证通过后才写检查点。取消、着色器失败和安装失败保留上次成功运行版本与存档；重试会验证并复用解包、代码重写和着色器提取等已完成阶段。
• 统一界面材质。 底部任务栏移入内容区，共用背景和系统 Liquid Glass 材质；去掉按钮额外底色及右上角键盘按钮。设置和游戏详情保留输入映射入口。
• 避免打包打断任务。 目标应用或其运行时子进程仍运行时拒绝覆盖。完整包先在暂存目录签名、验证，再发布；发布或搬移后验证失败会恢复旧包。新增 --output-dir 独立输出目录；搬移前后验证内置 Python 在 GUI PATH 下能启动内置 spirv-cross。缺少工具时报告 shader_tool_missing，不再误报游戏着色器不兼容。

工作流生成 LumaDock-0.2.10-arm64.dmg 和源码包。核对 SHA256SUMS，退出运行中的应用和任务后再替换“应用程序”中的副本。需要 Apple Silicon、macOS 26 及以上。此版仍为 临时签名、未公证；本地签名校验通过不代表通过 Gatekeeper。正常的已识别开发者分发仍需 Developer ID Application 证书和 Apple 公证。

升级后在设置中重新准备引擎工具，即可更新读取器并重扫已有托管文件，无需重新导入。若着色器任务曾因应用被替换而中断，重新打开完整应用后重试即可；保留源文件、密钥及成功缓存。

本地通过 156 项 Python、61 项 Swift Release 测试，工具栏调整后另通过相关外观与进度回归。合成流程覆盖 Mac/iOS 派生配置、缓存、取消、失败、错误输入标记及 iOS 平台校验；使用合成数据核对真实 nxnative 派生接口。对玩家合并 XCI 的只读检查识别出本体与内置更新，版本规划无需另一登记版本。元数据读取器通过 LibHac 0.19 编译；本地包通过签名、内置 Python/spirv-cross 子进程及分发边界检查；独立合成窗口检查了浅色、深色和高对比外观。

验证范围： 未完成玩家 1.0.1 游戏的整套真实编译或游玩验收，未验证 iOS 真机，也未通过 Apple 公证验收。标签 CI 会重建并验证公开附件；本地结果不代表标签 CI 已完成。

不附带引擎、游戏、更新、DLC、固件、玩家密钥、封面、存档或玩家缓存，第三方许可保留在随包文档中。

LumaDock 0.2.9

LumaDock 0.2.9

Changes

• Restore Add games (#13). Fix the #8 regression that sent XCI/NSZ/XCZ selections to the independent File conversion page. Adding files or scanning a mixed-format folder now continues through library import and automatic preparation when required content is available and automatic preparation is enabled.
• Read XCI directly. NSP and XCI are passed directly to the compatible nxnative reader. Managed copies retain their original container extension; XCI is not repacked into NSP. Only NSZ/XCZ archives are automatically decompressed into temporary NSP/XCI files before import, using the library key.
• Preserve task controls. Automatic decompression reports progress, can wait for an active build or game to finish, and supports cancellation and retry. Temporary output is cleaned up. Independent file conversion keeps its own settings and keys.

Installation and validation

Download LumaDock-0.2.9-arm64.dmg, verify SHA256SUMS, and drag LumaDock.app into Applications. Requires Apple Silicon and macOS 26+. Packages use ad-hoc signing and are not notarized. Preparation requires full Xcode, Metal and a compatible external nxnative engine; IPA export also requires the iOS platform and XcodeGen.

The import fix passed 122 Python tests and 60 Swift Release tests, plus the PR's complete CI build, real Metal diagnostics, unsigned UIKit IPA validation, package/signature checks and runtime relocation. An isolated app verified that a synthetic mixed XCI/XCZ folder proceeds from import to preparation and a ready library entry. The tag workflow rebuilds and validates all assets before publishing them.

Validation limits: UI and import tests use synthetic containers with metadata/compiler test doubles. They do not establish successful commercial-game decryption, compilation, gameplay or physical iOS compatibility. The previously documented newer-nxnative NVN IPA C1 inputs-stamp issue is not addressed by this update.

No engine, games, updates, DLC, firmware, player keys, game artwork, saves or player caches are included. Thanks to nxnative, MacNativeGames, d2r-mobile, SAK-Mac, S2Arm and their contributors; full notices remain in the bundled documentation.

---

中文说明

• 恢复添加游戏流程（#13）。 修复 #8 将 XCI/NSZ/XCZ 选择直接转交独立“文件转换”页的问题。添加文件或扫描混合格式文件夹后继续入库；所需内容齐全且开启自动准备时，自动开始编译。
• 直接读取 XCI。 NSP、XCI 直接交给兼容的 nxnative 读取器，托管副本保留原容器扩展名，不将 XCI 重新封装为 NSP。仅 NSZ/XCZ 使用游戏库密钥自动解压为临时 NSP/XCI 后导入。
• 保留任务控制。 自动解压显示进度，可等待已有构建或游戏结束，支持取消、重试及临时产物清理。独立文件转换保留自己的设置和密钥。

下载 LumaDock-0.2.9-arm64.dmg，核对 SHA256SUMS 后拖入“应用程序”。需要 Apple Silicon、macOS 26 及以上。安装包采用 ad-hoc 签名，尚未公证。游戏准备仍需完整 Xcode、Metal 和兼容的外部引擎；IPA 导出还需 iOS 平台与 XcodeGen。

导入修复通过 122 项 Python、60 项 Swift Release 测试，以及 PR 的完整 CI 构建、真实 Metal 诊断、原创 UIKit 未签名 IPA 校验、安装包和签名校验、运行时搬移检查。独立测试应用实际验证合成 XCI/XCZ 混合目录从导入自动进入准备，最终游戏库显示可启动。版本标签流水线会在公开附件前重新执行完整构建与校验。

验证范围： 界面和导入测试使用原创合成容器，元数据读取及编译由测试替身提供，不代表商业游戏解密、编译、游玩或实体 iOS 兼容性验收。本版未处理此前记录的新版 nxnative NVN IPA C1 inputs 标记兼容问题。

项目不附带引擎、游戏、更新、DLC、固件、玩家密钥、游戏封面、存档或玩家缓存。感谢 nxnative、MacNativeGames、d2r-mobile、SAK-Mac、S2Arm 及贡献者；完整致谢与许可保留在随包文档中。

LumaDock 0.2.8

LumaDock 0.2.8

Changes

• Shader preparation fix (#12). Read newer nxnative's shared dm/gfx/nvn/dmsh_chain.h, with fallback to the selected game's header for older engines. This fixes the missing-header crash reported in the #9 follow-up, before shader compilation starts. Missing or invalid headers trigger one private engine-workspace rebuild before an actionable error.
• Milestone progress and time estimates (#11). Game preparation and IPA export show their steps, purposes, elapsed time, estimated remaining time and completion time in both the task page and global task bar. Successful uncached stages train local median estimates by game, target and toolchain. Initial timings are reference estimates; unknown totals do not produce numeric percentages. Adapted from S2Arm with its attribution and MIT notice retained.
• Correct iOS shader progress. Count completed iOS reflection/library pairs instead of the Mac cache, including with older per-game chain headers. A finished Mac cache no longer makes an unfinished iOS shader stage appear complete.

Installation and validation

Download LumaDock-0.2.8-arm64.dmg, verify SHA256SUMS, and drag LumaDock.app into Applications. Requires Apple Silicon and macOS 26+. Packages use ad-hoc signing and are not notarized. Preparation requires full Xcode, Metal and a compatible external nxnative engine; IPA export also requires the iOS platform and XcodeGen.

The combined changes passed 114 Python tests and 57 Swift Release tests, real macOS/iOS Metal checks, original unsigned UIKit IPA validation, and CI package, signature and runtime-relocation checks. Tests exercise both header layouts through actual synthetic header-generation subprocesses and iOS counting while the Mac cache is complete. The tag workflow repeats the full build and validation before publishing assets.

Validation limits: #9's reporter bypassed the missing-file error by copying the header, then reported 0% shader progress. Those logs do not establish successful compilation or a complete game build. Real-game preparation, gameplay and physical iOS devices have not been revalidated. Newer nxnative NVN IPA export has a separate existing C1 table inputs-stamp compatibility issue; this release does not resolve it.

No engine, games, updates, DLC, firmware, player keys, game artwork, saves or player caches are included. Thanks to nxnative, MacNativeGames, d2r-mobile, SAK-Mac, S2Arm and their contributors; full notices remain in the bundled documentation.

---

中文说明

• 修复着色器准备崩溃（#12）。 优先读取新版 nxnative 的共享 dm/gfx/nvn/dmsh_chain.h，兼容旧版每游戏头文件，修复 #9 追评中在编译启动前发生的缺失头文件异常。缺失或无效头文件会触发一次私有引擎工作区重建，仍无效时给出明确提示。
• 里程碑进度与耗时估算（#11）。 游戏准备和 IPA 导出显示阶段、步骤作用、已用时间、预计剩余和完成时刻，任务页与全局底栏同步。成功且未命中缓存的阶段按游戏、目标和工具链积累本机耗时中位数；初始耗时明确为参考估计，未知总量不显示数字百分比。实现参考 S2Arm，保留来源和 MIT 声明。
• 修正 iOS 着色器计数。 IPA 任务读取 iOS 产物，避免 Mac 缓存完成后提前显示 iOS 阶段完成，旧版头文件同样适用。

下载 LumaDock-0.2.8-arm64.dmg，核对 SHA256SUMS 后拖入“应用程序”。需要 Apple Silicon、macOS 26 及以上。安装包采用 ad-hoc 签名，尚未公证。游戏准备仍需完整 Xcode、Metal 和兼容的外部引擎；IPA 导出还需 iOS 平台与 XcodeGen。

组合版本通过 114 项 Python、57 项 Swift Release 测试、真实 macOS/iOS Metal 检查、原创 UIKit 未签名 IPA 校验，以及 CI 的安装包、签名与运行时搬移检查。新增回归实际启动原创头文件生成子进程，并确认 Mac 缓存完成时 iOS 进度不会提前完成。版本标签流水线会在公开附件前重新执行完整构建与校验。

验证范围： #9 报告者仅确认复制头文件后越过缺失文件异常，随后反馈进度停在 0%；附件不能证明编译或完整游戏准备成功。本次未重验真实游戏准备、游玩或 iOS 真机。新版 nxnative 的 NVN IPA 导出另有既存 C1 表 inputs 标记兼容问题，本版尚未处理。

项目不附带引擎、游戏、更新、DLC、固件、玩家密钥、游戏封面、存档或玩家缓存。感谢 nxnative、MacNativeGames、d2r-mobile、SAK-Mac、S2Arm 及贡献者；完整致谢与许可保留在随包文档中。

LumaDock 0.2.7

LumaDock 0.2.7

LumaDock is a game launcher for Apple Silicon Macs running macOS 26 or later, using a player-selected external nxnative engine.

Changes

• Bundled file conversion. Convert NSP/XCI (including NSZ/XCZ inputs), compress or decompress NSZ/XCZ, and merge one game's base, update and DLC packages. The new File conversion page uses bundled tools adapted from SAK-Mac, with NSC_BUILDER, nsz and pinned dependencies. Conversion needs your own valid keys; it does not need a separate Python, Xcode or nxnative installation. Generated NSPs can be imported into the library. (#8)
• Protected inputs and outputs. Conversion runs with private input/backend copies, separate conversion keys, progress, cancellation/retry, task history and log actions. Validated results are exported into a new folder without replacing existing output. Upstream licenses, dependency notices and corresponding GPL/MPL component sources are included.
• DLC preparation fix. Pass the engine source directory to the upstream seven-argument extract_aoc interface. This fixes TypeError: extract_aoc() missing 1 required positional argument: 'logs' during Mac preparation and IPA export. The reported exception was caused by an incorrect call; it did not establish a console/firmware version mismatch. (#9, #10)

Installation and validation

Download LumaDock-0.2.7-arm64.dmg, verify SHA256SUMS, and drag LumaDock.app into Applications. Packages use ad-hoc signing and are not notarized. Game preparation still requires full Xcode, Metal and a compatible external engine; IPA export also requires the iOS platform and XcodeGen.

The combined changes passed 98 Python tests and 51 Swift Release tests, real macOS/iOS Metal success/failure checks, and original unsigned UIKit IPA packaging/validation. DLC regression coverage includes Mac/iOS calls, multiple DLC packages, no DLC, cache reuse and failure/retry. Conversion success tests use original containers and backend protocol fixtures; real bundled backends are checked for startup, relocation and invalid-key rejection. These checks do not establish commercial-game conversion, in-game DLC behavior or physical iPhone/iPad compatibility.

No engine, games, updates, DLC, firmware, player keys, game artwork, saves or player caches are included. Import only content you are authorized to use. The project is not affiliated with Nintendo or any game publisher. Thanks to nxnative, MacNativeGames, d2r-mobile, SAK-Mac and their contributors; full notices remain in the bundled documentation.

---

中文说明

璃游 0.2.7 面向 Apple Silicon Mac、macOS 26 及以上，使用玩家自行提供的外部 nxnative 引擎。

• 内置文件转换。 新增“文件转换”页面，支持 NSP/XCI 转换（可输入 NSZ/XCZ）、压缩解压及同一游戏本体、更新和 DLC 合并。内置参考 SAK-Mac 的调度逻辑、NSC_BUILDER、nsz 和固定版本依赖；导入自己的有效密钥即可使用，无需另装 Python、Xcode 或 nxnative。生成的 NSP 可直接入库。（#8）
• 保护原文件和已有输出。 使用私有输入与后端副本、独立转换密钥，提供进度、取消重试、任务历史、日志和结果入口。校验后导出至新文件夹，不覆盖旧结果；保留上游许可、依赖声明及 GPL/MPL 组件对应源码。
• 修复 DLC 准备失败。 补齐 extract_aoc 所需的引擎源码目录参数，修复 Mac 准备和 IPA 导出时的 missing 1 required positional argument: 'logs'。此异常来自调用参数错误，现有日志没有证明主机或固件版本不匹配。（#9、#10）

下载 LumaDock-0.2.7-arm64.dmg，核对 SHA256SUMS 后拖入“应用程序”。安装包采用 ad-hoc 签名，尚未公证。游戏准备仍需要完整 Xcode、Metal 和兼容的外部引擎；IPA 导出还需要 iOS 平台与 XcodeGen。

组合版本通过 98 项 Python、51 项 Swift Release 测试、真实 macOS/iOS Metal 成功与失败检查，以及原创 UIKit 未签名 IPA 构建校验。DLC 回归覆盖 Mac/iOS、多 DLC、无 DLC、缓存复用和失败重试。转换成功测试使用原创容器和后端协议夹具；真实内置后端检查覆盖启动、搬移和无效密钥拒绝。尚未验证商业游戏转换、游戏内 DLC 加载或实体 iPhone/iPad 兼容性。

项目不附带引擎、游戏、更新、DLC、固件、玩家密钥、游戏封面、存档或玩家缓存；仅导入有权使用的内容。项目与 Nintendo 及游戏发行商无隶属或认可关系。感谢 nxnative、MacNativeGames、d2r-mobile、SAK-Mac 及贡献者；完整致谢和许可保留在随包文档中。

LumaDock 0.2.6

LumaDock 0.2.6

LumaDock is a game launcher for Apple Silicon Macs running macOS 26 or later, using a player-selected external nxnative source directory.

Changes

• Actionable errors. Build failures show the failed stage, error code, suggested repair, redacted compiler output and a link to the specific log. Copy a redacted summary from the alert or task. Diagnostics cover missing Metal/SDK components, shader translation/compilation errors, shader-chain mismatches, disk/permission errors and possible memory exhaustion. Worker startup failures and unexpected exits are also retained.
• Shader warnings stay visible. A shader tool returning success with incomplete shader results produces a warning; no usable shaders stops the build. Warnings survive checkpoint reuse instead of disappearing on retry. A completed build does not guarantee correct graphics in every scene.
• Progress across long operations. A shared linear progress display covers imports, source/copy/cache verification, engine preparation, game/shader builds, IPA export, environment checks, Metal component management, cleanup and diagnostics export. Tasks show measured bytes/files/shaders and percentages when a real total is known; otherwise they show an indeterminate bar, current phase and elapsed time. Progress remains visible outside Tasks and inside setup/Settings. Pure Python work has heartbeats; ordinary messages no longer clear counters.
• Generate IPA. Choose Generate IPA… in game details to export an unsigned iPhone/iPad game package. Mac and iOS builds have separate cache identities; iOS shaders are checked before packaging. Export validates archive structure/CRCs and preserves the previous IPA after failure or cancellation. Xcode's iOS platform, Metal compiler and XcodeGen are required. Sign the IPA with your installation tool before installing it.
• Keep English/Chinese UI and guides synchronized. CI additionally compiles original Metal samples for macOS/iOS, checks real compiler error redaction and builds/validates a small unsigned UIKit fixture IPA. No engine or player content is fetched for these checks.

Installation and validation

Download LumaDock-0.2.6-arm64.dmg, verify SHA256SUMS, and drag LumaDock.app into Applications. Packages use ad-hoc signing and are not notarized. Preparing games requires full Xcode, Metal and your own compatible external engine. IPA export additionally needs the iOS platform and XcodeGen (brew install xcodegen).

Local validation passed 78 Python tests and 45 Swift Release tests, plus English/Chinese UI checks of progress, cancellation/retry, warning/error actions, mapping save and synthetic IPA export. Regression coverage includes library/import/setup flows, keys and source isolation, engine/tool caches, cancellation/retry, input mappings, language/appearance, diagnostics, progress, IPA export and distribution data boundaries. Real Apple tools validate macOS/iOS Metal success and failure paths and a synthetic iOS app archive. These checks do not establish commercial-game preparation, gameplay or physical iPhone/iPad compatibility. See the bundled validation record for the exact scope.

No games, updates, DLC, firmware, player keys, game artwork, saves or player caches are included. Import only content you are authorized to use. Back up important saves. The project is not affiliated with Nintendo or any game publisher. Thanks to nxnative, MacNativeGames, d2r-mobile and their contributors; acknowledgements and third-party licenses remain in the README and bundled guides.

---

中文说明

璃游 0.2.6 面向 Apple Silicon Mac、macOS 26 及以上，继续使用玩家自行提供的外部 nxnative 源码。

• 具体报错与修复建议。 显示失败阶段、错误代码、处理建议和脱敏编译器输出，直接定位对应日志，也可复制错误摘要。区分 Metal/SDK 缺失、着色器转换或编译失败、缓存链不匹配、空间/权限问题及可能的内存不足；工作进程启动失败和异常退出也会保存诊断。
• 保留着色器警告。 进程返回成功但着色器结果不完整时显示警告，没有可用着色器时停止构建；缓存复用后仍显示警告。“准备完成”不代表所有场景画面正常。
• 补齐耗时操作的进度条。 覆盖导入、源文件/副本/缓存校验、引擎准备、游戏与着色器构建、IPA 导出、环境检查、Metal 组件管理、清理和诊断导出。可计数时显示实际字节、文件、着色器数量和百分比；总量未知时使用线形不定进度条，并显示阶段及已用时间。其他页面、设置及向导中也能查看进度，普通消息不会清空计数，纯 Python 任务持续发送心跳。
• 一键生成 IPA。 游戏详情点击“生成 IPA…”即可导出未签名 iPhone/iPad 游戏包。Mac/iOS 缓存隔离，检查 iOS 着色器、IPA 结构及 CRC；失败或取消保留上次 IPA。需要 Xcode iOS 平台、Metal 组件和 XcodeGen；安装到设备前仍需自行签名。
• 同步中英文界面和文档；CI 新增 macOS/iOS 实际 Metal 成功/失败诊断及原创 UIKit 样例 IPA 构建校验，不下载引擎或玩家内容。

下载 LumaDock-0.2.6-arm64.dmg，核对 SHA256SUMS 后拖入“应用程序”。安装包采用 ad-hoc 签名，尚未公证。本地通过 78 项 Python、45 项 Swift Release 测试，以及中英文进度、取消/重试、错误/警告、映射保存及合成 IPA 导出的实际界面检查。回归检查覆盖启动器各工作流程、取消与重试、设置、进度、诊断及数据边界，并使用真实 Apple 编译器与合成 iOS 应用验证；不代表商业游戏准备、游玩或 iPhone/iPad 真机兼容性验收。具体范围见随包验收记录。

项目不附带游戏、更新、DLC、固件、玩家密钥、游戏封面、存档或玩家缓存；仅导入有权使用的内容，并备份重要存档。项目与 Nintendo 及游戏发行商无隶属或认可关系。感谢 nxnative、MacNativeGames、d2r-mobile 及贡献者；README 与随包文档保留上游致谢和第三方许可。

LumaDock 0.2.5

LumaDock 0.2.5

LumaDock is a Mac game launcher for Apple Silicon and macOS 26 or later, built to work with nxnative.

Changes

• External engine only. The app, DMG and source archive no longer include nxnative sources, the NSP reader or shader translator. Obtain a complete compatible nxnative source directory yourself, select its root in setup or Settings, then choose Prepare engine tools. There is no engine download action. The initial tool build requires the .NET 10 SDK for macOS Arm64 and may restore NuGet dependencies. Builds use private copies and leave your original source directory unchanged. Generic Python/.NET runtimes and conversion tools remain bundled.
• Game language (#2). Fix the invalid hardcoded zhHans code to zh-Hans. Choose Launch language in game details, or a Default game language in Settings. Per-game choices persist independently of the interface language and apply on the next launch without rebuilding or importing firmware. The game and engine must support the selected language.
• Setup exit (#1). Leave incomplete setup with Set up later / Esc, or quit normally with Quit LumaDock / ⌘Q, including when environment checks fail or are running. Required checks still gate imports and preparation.
• Validate external source interfaces and fingerprints, isolate private tool caches, and preserve the previous successful runtime after failures. Custom mappings require an external engine implementing DM_INPUT_CONFIG; otherwise the editor explains that the engine's own controls apply.
• Update English/Chinese guides and light-mode screenshots without game content. CI builds the standalone launcher without downloading nxnative.

Installation and validation

Download LumaDock-0.2.5-arm64.dmg, check SHA256SUMS, and drag LumaDock.app into Applications. The community build uses ad-hoc signing and is not notarized. Preparing games also requires full Xcode and Apple's Metal compiler component; the setup assistant checks their actual state and explains installation.

Local validation passed 55 Python tests and 34 Swift Release tests, actual English/Chinese menu checks, package/signature checks and release-artifact verification. No commercial games were run for this release, so these checks do not establish gameplay or in-game language compatibility with arbitrary external engines. GitHub Actions independently verifies and publishes the tag's DMG, source archive and checksums; local results do not confirm the remote run.

No games, updates, DLC, firmware, player keys, game artwork, saves or player caches are included. Import only content you are authorized to use. Experimental native execution can crash, stutter or lose saves; back up important data. The project is not affiliated with or endorsed by Nintendo or any game publisher. Special thanks to nxnative, MacNativeGames, d2r-mobile and their contributors; upstream acknowledgements and third-party licenses remain in the README and bundled documentation.

---

中文说明

璃游 0.2.5 面向 Apple Silicon、macOS 26 及以上。

• 改为外部引擎。 应用、DMG 和源码包不再内置 nxnative 源码、NSP 读取器或着色器翻译器，也没有引擎下载按钮。请自行获取兼容的完整源码，在向导或设置中选择包含 dm 和 scripts 的根目录，再点击“准备引擎工具”。首次需要 .NET 10 SDK（macOS Arm64），可能恢复 NuGet 依赖。所有构建及适配在私有副本中完成，原目录保持不变；通用 Python/.NET 运行时及转换工具仍随应用提供。
• 修复游戏语言（#2）。 将错误的 zhHans 改为 zh-Hans。游戏详情新增“启动语言”，设置新增“默认游戏语言”；每游戏选择独立保存，与界面语言无关，下次启动生效，无需重新准备或导入固件。实际语言取决于游戏和引擎支持。
• 修复向导退出（#1）。 环境失败或检查进行中，也可通过“稍后设置 / Esc”离开，或通过“退出璃游 / ⌘Q”正常退出；必要检查仍会限制导入和准备。
• 增加外部引擎接口、源码指纹和工具完整性检查，隔离缓存并保留上次成功的运行版本。自定义映射需要引擎提供 DM_INPUT_CONFIG；不支持时明确提示并使用引擎默认操作。更新中英文说明及不含游戏内容的浅色截图，CI 不下载 nxnative。

下载 LumaDock-0.2.5-arm64.dmg，核对校验和后拖入“应用程序”。安装包采用本地 ad-hoc 签名，尚未公证；准备游戏还需要完整 Xcode 和 Metal 编译组件，向导会检查实际状态并提供安装方法。

本地通过 55 项 Python、34 项 Swift Release 测试，以及中英文实际菜单、应用签名与发行产物校验。本次未运行商业游戏，不能据此声称任意外部引擎的游玩或游戏内语言验收通过。标签流水线独立校验并发布 DMG、源码包和校验和；本地结果不代表远端已成功。

项目不附带游戏、更新、DLC、固件、玩家密钥、游戏封面、存档或玩家缓存；仅导入有权使用的内容。实验性运行可能崩溃、卡顿或丢失存档，请备份重要数据。项目与 Nintendo 及游戏发行商无隶属或认可关系。特别感谢 nxnative、MacNativeGames、d2r-mobile 及其贡献者；README 与随包文档保留上游致谢、风险及第三方许可。

LumaDock 0.2.4

New in 0.2.4

• Clarify Xcode setup recovery: if setup is already complete, check again or quit and reopen LumaDock first. Review the actual diagnostics before using a manual initialization command.
• Keep the in-app English/Chinese repair instructions and offline environment guides consistent. Environment checks still run once at startup, with manual rechecks and verification after toolchain/library changes.

Local validation: 43 Python tests, 24 Swift Release tests, and app/DMG/source/signature/checksum and bundled-runtime relocation checks passed. No games were run or Apple components installed, removed or licensed during validation. A reported recovery after reopening does not establish a specific root cause or a new gameplay test result. GitHub Actions publishes the release only after its own checks pass; local validation does not confirm the remote run.

0.2.4 更新

• 明确 Xcode 设置恢复步骤：若已完成设置，先重新检查或退出后重开璃游；仍失败时查看实际诊断，确认需要后再使用手动初始化命令。
• 应用内英文、中文提示与离线环境说明保持一致。保留每次启动检查一次、手动检查及工具链或游戏库变化后的验证。

本地通过 43 项 Python 测试、24 项 Swift Release 测试，以及应用、DMG、源码包、签名、校验和与内置运行库搬移检查。本次未运行游戏，未安装、卸载 Apple 组件或接受许可。用户重开后恢复的反馈不代表已确定根因，也不增加游戏游玩验证结论。CI 自身检查通过才会公开 Release；本地通过不代表远端已完成。

LumaDock is a native Mac launcher built on nxnative, for Apple Silicon and macOS 26 or later.

• Guided setup: check the environment, choose a library, import your own prod.keys, then add NSP games.
• Automatic preparation with progress, cancellation, validated caches, and keyboard/mouse/controller configuration.
• Direct Mac runtime generation, a Liquid Glass interface, and Xcode / Metal component management.
• Tested titles: Breath of the Wild 1.9.0 (build and startup passed) and Super Mario Odyssey 1.4.1 (player gameplay test passed). These are limited test results, not full-game completion claims; see the README and validation record.

Download the ARM64 DMG and drag LumaDock into Applications. Packages use local ad-hoc signing and are not notarized. A full Xcode installation and the Metal compiler component are needed to prepare games.

No games, updates, DLC, firmware, keys, game artwork, or player caches are included. Import only content you are authorized to use. This project is not affiliated with Nintendo. Thanks to nxnative, MacNativeGames, d2r-mobile, and their contributors; third-party licenses and notices are preserved.

The release DMG and source archive are built and checked by GitHub Actions; verify them with SHA256SUMS.

---

璃游是基于 nxnative 的原生 Mac 游戏启动器，面向 Apple Silicon、macOS 26 及以上。先检查环境，再选择游戏库、导入玩家密钥及 NSP，支持自动准备、进度显示、缓存复用与键鼠/手柄映射。

历史记录中《旷野之息》1.9.0 构建及启动通过，《奥德赛》1.4.1 玩家游玩测试通过，均不代表全流程验证。《奥德赛》的较长游玩记录使用此前的 10b33338 引擎；更新固定引擎不会扩大这一证据范围。安装包采用本地 ad-hoc 签名，尚未公证；准备游戏需要完整 Xcode 与 Metal 编译组件。

项目不附带游戏、更新、DLC、固件、密钥或玩家缓存，与 Nintendo 没有隶属关系。感谢 nxnative 等上游项目及贡献者。安装包和源码包由 GitHub Actions 生成并校验，可用 SHA256SUMS 核对。

LumaDock 0.2.3

New in 0.2.3

• Check the environment automatically once per app launch. Settings and reopened setup reuse the current result, including failures; manual rechecks and verification after toolchain/library changes remain available.
• Explain Xcode initial setup failures with the selected Developer path, the status command, error output and exit status even when the command returns no text. Distinguish missing Xcode, a reported license error, timeout and other initialization/status failures. A copyable repair command uses the selected Xcode; the user runs it manually after reviewing and agreeing to Apple's license. LumaDock does not execute privileged initialization or accept licenses automatically.
• Open English/Chinese environment instructions and third-party notices in an offline reader inside the app, including from the setup assistant.
• Show bundled component versions first, with full installation paths in an expandable section. Locate Python, extensions and .NET from the current app bundle.
• Remove leftover Homebrew runtime search paths and reject external native dependencies/symlinks during packaging. CI verifies actual bundled tool startup after renaming and moving the app into a path containing Chinese characters and spaces.
• An incomplete packaged app reports its own missing resources instead of falling back to a developer checkout.

Local validation: 43 Python tests, 24 Swift tests, native runtime load-path audits, real UI navigation/offline-guide checks, relocation tests, and DMG/source/signature/checksum verification passed on macOS 27.0.1 with Xcode 27.1. No games were run. The reported initialization failure on another Mac cannot be diagnosed from its old screenshot alone; use the updated diagnostics. Physical macOS 26 testing remains outstanding. GitHub Actions builds and publishes this release only after its checks pass; local results do not confirm the remote run.

0.2.3 更新

• 每次启动自动检查一次；切换设置或重新打开向导复用本次结果，包括失败结果。手动检查、工具链或游戏库变更后的验证保留。
• Xcode 初始设置失败时显示所选 Developer 路径、检查命令、错误输出及退出码；命令无输出也不会只显示通用说明。区分缺少 Xcode、命令报告的许可错误、超时及其他初始化或状态检查失败。修复命令按实际 Xcode 路径生成，由玩家阅读并同意 Apple 许可后手动执行；应用不自动执行管理员初始化或接受许可。
• 环境安装说明与第三方许可改为应用内离线阅读，支持中英文，首次运行向导内也能打开。
• 内置组件默认显示版本，完整位置可展开；Python、扩展及 .NET 根据当前应用包位置定位。
• 清除 Homebrew 备用搜索目录，打包时拒绝外部原生依赖和符号链接；CI 实际验证应用改名、移动至中文和空格目录后仍能启动内置工具。
• 应用包缺少资源时报告本包错误，不回退到开发者源码目录。

本地通过 43 项 Python 测试、24 项 Swift 测试、运行库审计、真实界面切换及离线说明检查、搬移验证，以及 DMG、源码、签名和校验和检查。测试系统为 macOS 27.0.1 / Xcode 27.1；本次没有运行游戏，也未在对方 Mac 上确认初始化失败的具体原因。macOS 26 真机验证仍待补充。CI 全部通过才会公开 Release，本地通过不代表此次远程构建已成功。

LumaDock is a native Mac launcher built on nxnative, for Apple Silicon and macOS 26 or later.

• Guided setup: check the environment, choose a library, import your own prod.keys, then add NSP games.
• Automatic preparation with progress, cancellation, validated caches, and keyboard/mouse/controller configuration.
• Direct Mac runtime generation, a Liquid Glass interface, and Xcode / Metal component management.
• Tested titles: Breath of the Wild 1.9.0 (build and startup passed) and Super Mario Odyssey 1.4.1 (player gameplay test passed). These are limited test results, not full-game completion claims; see the README and validation record.

Download the ARM64 DMG and drag LumaDock into Applications. Packages use local ad-hoc signing and are not notarized. A full Xcode installation and the Metal compiler component are needed to prepare games.

No games, updates, DLC, firmware, keys, game artwork, or player caches are included. Import only content you are authorized to use. This project is not affiliated with Nintendo. Thanks to nxnative, MacNativeGames, d2r-mobile, and their contributors; third-party licenses and notices are preserved.

The release DMG and source archive are built and checked by GitHub Actions; verify them with SHA256SUMS.

---

璃游是基于 nxnative 的原生 Mac 游戏启动器，面向 Apple Silicon、macOS 26 及以上。先检查环境，再选择游戏库、导入玩家密钥及 NSP，支持自动准备、进度显示、缓存复用与键鼠/手柄映射。

历史记录中《旷野之息》1.9.0 构建及启动通过，《奥德赛》1.4.1 玩家游玩测试通过，均不代表全流程验证。《奥德赛》的较长游玩记录使用此前的 10b33338 引擎；更新固定引擎不会扩大这一证据范围。安装包采用本地 ad-hoc 签名，尚未公证；准备游戏需要完整 Xcode 与 Metal 编译组件。

项目不附带游戏、更新、DLC、固件、密钥或玩家缓存，与 Nintendo 没有隶属关系。感谢 nxnative 等上游项目及贡献者。安装包和源码包由 GitHub Actions 生成并校验，可用 SHA256SUMS 核对。

LumaDock 0.2.2

New in 0.2.2

• Complete environment checklist in setup and Settings: hardware, system Metal device, bundled Python and extensions, .NET 10, NSP reader, shader tools, Xcode initialization, macOS SDK, native compilation/signing, actual Metal compilation, and library permissions/free space.
• English and Chinese installation and repair guidance for every item, with actions to get/select/open Xcode, install Metal, reinstall an incomplete app, or change library storage.
• Isolated bundled Python with no silent Homebrew fallback. Missing Python or a failed Worker bootstrap produces an actionable native check instead of leaving setup stuck.
• Separate preparation and launch requirements. Already prepared games can launch without build-only tools; incomplete or failed checks cannot enable Continue early.
• Mac shader-chain checks only require the macOS SDK. Tool and engine changes continue to invalidate affected build caches.
• Redesigned Retina DMG installer with a light glass-style background, aligned drag-to-Applications icons, bilingual instructions, and organized guides/licenses. Packaging verifies the mounted installer layout and preserves the app signature.

Local validation: 38 Python tests, 19 Swift tests, all 18 packaged environment checks, bilingual UI checks, and DMG/source/signature/checksum verification passed on macOS 27.0.1 with Xcode 27.1. No games were run for this update; the historical gameplay evidence is unchanged. Physical macOS 26 testing remains outstanding.

0.2.2 更新

• 首次设置和设置页补齐完整环境检查，实际验证 Python 及扩展、.NET、NSP 读取器、着色器工具、Xcode 初始化、macOS SDK、原生编译与签名、Metal 编译和游戏库存储。
• 每项提供中英文安装与修复方法，可获取、选择或打开 Xcode，安装 Metal、重装完整应用或切换游戏库存储。
• 隔离启动内置 Python，不再自动借用 Homebrew Python。Python 缺失或 Worker 启动失败时，原生界面仍能给出修复入口。
• 区分“准备”和“启动”条件；已准备游戏不依赖仅构建所需的工具，未完成或失败的检查不会提前放行。
• Mac 着色器链只检查 macOS SDK，工具链或引擎变化仍会使对应缓存失效。
• 美化 Retina DMG 安装界面，加入浅色玻璃质感背景、固定图标位置、双语拖拽引导及整理后的文档和许可；验证安装盘布局及应用签名。

本地验证通过：38 项 Python 测试、19 项 Swift 测试、18 项发行应用环境检查、中英文界面检查，以及 DMG、源码、签名与校验和验证。实测系统为 macOS 27.0.1 / Xcode 27.1；本次未运行游戏，不扩大历史游玩结论，macOS 26 真机仍未重新验证。

LumaDock is a native Mac launcher built on nxnative, for Apple Silicon and macOS 26 or later.

• Guided setup: check the environment, choose a library, import your own prod.keys, then add NSP games.
• Automatic preparation with progress, cancellation, validated caches, and keyboard/mouse/controller configuration.
• Direct Mac runtime generation, a Liquid Glass interface, and Xcode / Metal component management.
• Tested titles: Breath of the Wild 1.9.0 (build and startup passed) and Super Mario Odyssey 1.4.1 (player gameplay test passed). These are limited test results, not full-game completion claims; see the README and validation record.

Download the ARM64 DMG and drag LumaDock into Applications. Packages use local ad-hoc signing and are not notarized. A full Xcode installation and the Metal compiler component are needed to prepare games.

No games, updates, DLC, firmware, keys, game artwork, or player caches are included. Import only content you are authorized to use. This project is not affiliated with Nintendo. Thanks to nxnative, MacNativeGames, d2r-mobile, and their contributors; third-party licenses and notices are preserved.

The release DMG and source archive are built and checked by GitHub Actions; verify them with SHA256SUMS.

---

璃游是基于 nxnative 的原生 Mac 游戏启动器，面向 Apple Silicon、macOS 26 及以上。先检查环境，再选择游戏库、导入玩家密钥及 NSP，支持自动准备、进度显示、缓存复用与键鼠/手柄映射。

历史记录中《旷野之息》1.9.0 构建及启动通过，《奥德赛》1.4.1 玩家游玩测试通过，均不代表全流程验证。《奥德赛》的较长游玩记录使用此前的 10b33338 引擎；更新固定引擎不会扩大这一证据范围。安装包采用本地 ad-hoc 签名，尚未公证；准备游戏需要完整 Xcode 与 Metal 编译组件。

项目不附带游戏、更新、DLC、固件、密钥或玩家缓存，与 Nintendo 没有隶属关系。感谢 nxnative 等上游项目及贡献者。安装包和源码包由 GitHub Actions 生成并校验，可用 SHA256SUMS 核对。

LumaDock 0.2.1

New in 0.2.1

• Sync nxnative to 4e2dcdc749668ddd4d61361117ad4a6980fabcf7, preserving the Mac metadata, packaging, and configurable input patches. Existing working runtimes are retained and marked for re-preparation.
• Independent System / Light / Dark appearance settings, with immediate updates and persistence.
• Refreshed bilingual READMEs with real light-mode app screenshots and no Controls chapter.
• English and Simplified Chinese throughout the app, setup assistant, input editor, progress, and application error messages.
• System language by default, with an immediate, persistent override in Settings and setup. Existing task records translate when displayed; game content and raw tool logs remain unchanged.
• Localized application metadata and bundled translation resources checked during packaging.

Engine validation scope: Odyssey completed preparation with 4e2dcdc. Breath of the Wild's rebuild was cancelled at the player's request; new startup and gameplay checks were not performed. The longer player gameplay record below belongs to the previous 10b33338 baseline.

0.2.1 更新

• 同步 nxnative 4e2dcdc，保留 Mac 补丁；引擎更新后提示重新准备，旧的成功运行版本保留。
• 新增独立的跟随系统／浅色／深色外观设置，立即生效并持久化。
• 中英文 README 删除操作映射章节，增加真实浅色界面截图。
• 应用、首次运行向导、输入映射、任务进度和应用错误提示支持英文及简体中文。
• 默认跟随系统，可在设置和向导中立即切换并记住选择；已有任务记录按显示语言翻译，游戏内容与原始工具日志保持原样。
• 打包时检查应用语言元数据和翻译资源。

新版引擎的验证范围：《奥德赛》完整准备通过；《旷野之息》重建按玩家要求取消，未执行新版启动及游玩检查。较长时间的玩家游玩记录基于此前的 10b33338。

LumaDock is a native Mac launcher built on nxnative, for Apple Silicon and macOS 26 or later.

• Guided setup: check the environment, choose a library, import your own prod.keys, then add NSP games.
• Automatic preparation with progress, cancellation, validated caches, and keyboard/mouse/controller configuration.
• Direct Mac runtime generation, a Liquid Glass interface, and Xcode / Metal component management.
• Tested titles: Breath of the Wild 1.9.0 (build and startup passed) and Super Mario Odyssey 1.4.1 (player gameplay test passed). These are limited test results, not full-game completion claims; see the README and validation record.

Download the ARM64 DMG and drag LumaDock into Applications. Packages use local ad-hoc signing and are not notarized. A full Xcode installation and the Metal compiler component are needed to prepare games.

No games, updates, DLC, firmware, keys, game artwork, or player caches are included. Import only content you are authorized to use. This project is not affiliated with Nintendo. Thanks to nxnative, MacNativeGames, d2r-mobile, and their contributors; third-party licenses and notices are preserved.

The release DMG and source archive are built and checked by GitHub Actions; verify them with SHA256SUMS.

---

璃游是基于 nxnative 的原生 Mac 游戏启动器，面向 Apple Silicon、macOS 26 及以上。先检查环境，再选择游戏库、导入玩家密钥及 NSP，支持自动准备、进度显示、缓存复用与键鼠/手柄映射。

历史记录中《旷野之息》1.9.0 构建及启动通过，《奥德赛》1.4.1 玩家游玩测试通过，均不代表全流程验证。《奥德赛》的较长游玩记录使用此前的 10b33338 引擎；更新固定引擎不会扩大这一证据范围。安装包采用本地 ad-hoc 签名，尚未公证；准备游戏需要完整 Xcode 与 Metal 编译组件。

项目不附带游戏、更新、DLC、固件、密钥或玩家缓存，与 Nintendo 没有隶属关系。感谢 nxnative 等上游项目及贡献者。安装包和源码包由 GitHub Actions 生成并校验，可用 SHA256SUMS 核对。