LumaNX, formerly LumaDock

LumaNX is a third-party graphical frontend for nxnative on Apple Silicon Macs. Import your game files, prepare a Mac runtime, launch from your library, or export an unsigned IPA for iPhone and iPad. nxnative provides native execution and Metal graphics; LumaNX brings the workflow into a SwiftUI interface.

Switch 2 games supported by the bundled nxnative snapshot are now supported on Mac through keyless NUP or decrypted-folder import. Game/version compatibility follows the engine's registered profiles; preparation is incremental by stage.

From files to a ready library

Workspace	What you can do
Game library	Add NSP/XCI/NSZ/XCZ files or scan folders; manage base games, updates and DLC. Compressed files are decompressed before import.
Game preparation	Prepare code, shaders and runtime files with validated caches. Follow stage progress, counters and reference time estimates; cancel or retry tasks.
Mac and mobile	Launch prepared games on Mac, or generate an unsigned iPhone / iPad IPA from game details.
File conversion	Convert NSP/XCI, compress or decompress NSZ/XCZ, and merge packages using bundled conversion tools.
Save recovery	Back up and verify saves, restore a backup, or switch prepared runtime versions with an automatic save backup.
Preferences	Choose English or Simplified Chinese, light or dark appearance, and game language. Configure input where supported by the engine.

Switch Pro, Xbox and PlayStation controllers connect through Apple's GameController framework. The native button policy maps Switch A / Xbox A / PlayStation cross to game A. Re-prepare existing games after an engine update to apply runtime changes.

Current release: 0.3.0 · Release notes

Get started

You need an Apple Silicon Mac running macOS 26 or later. Game preparation requires full Xcode and its Metal components. The packaged app includes nxnative, the metadata reader, shader translator and runtime dependencies.

1. Download the ARM64 DMG from Releases, check its SHA-256 against the release notes, and drag LumaNX.app into Applications. Packages currently use ad-hoc signing and are not notarized.
2. Open LumaNX. Use the setup assistant to check your environment and prepare engine tools.
3. Choose a game library and add games, updates and DLC that you are authorized to use. Packages require your own prod.keys; NUP files and decrypted Switch 2 folders need no keys, so you can skip that setup step.
4. Prepare a game, then choose Launch game. For mobile, choose Generate IPA… in game details.

IPA export also needs Xcode's iOS platform and XcodeGen (brew install xcodegen). Sign the exported IPA with your installation tool before installing it.

Compatibility varies by game, version and engine. Preparation success does not establish full gameplay compatibility; iOS device compatibility has not been validated. Back up saves before upgrading or experimenting.

Decrypted Switch 2 games (Mac, experimental)

Choose Add games and select a .nup file (or scan a folder containing NUPs), or select the root folder containing base/exefs and base/romfs. LumaNX validates program and module build IDs, copies the trees into the library, and prepares and launches them using bundled nxnative without prod.keys. A registered nxnative profile and its required versions are necessary. Upstream documents opening-area Mac gameplay for Donkey Kong Bananza (040074A01BF12000, update 458752); this does not establish compatibility with every Switch 2 title or the full game.

DonkeyKongBananza/
  base/exefs/                       main, main.npdm, sdk, rtld, etc.
  base/romfs/
  updates/458752/exefs/              optional update; decimal version number
  updates/458752/romfs/              complete patched resources, not a delta
  dlc/040074a01bf13001/0/romfs/       optional DLC

NUP imports verify the container and every file hash, keep one managed copy for its base, updates and DLC, and read the name, version and cover from control data when present. Resources and DLC are packed directly into images. An empty base placeholder or a missing base is accepted according to upstream rules: updates without a base record must be marked standalone_update, and must contain complete code and resources. The required profile versions still apply; no artificial v0 is created. NUP and directory imports require registered game profiles and do not generate provisional profiles.

Updates are used as complete trees without overlaying the base again. Missing required versions or mismatched build IDs block preparation. A game cannot mix NUP, package and directory sources. Directory imports use the library's existing caches, saves and runtime rollback. Only Mac preparation is enabled; IPA export is disabled. LumaNX automated checks use synthetic files; real-game acceptance still requires gameplay testing. Compare upstream's folder format and game notes.

Interface

Captured on 2026-10-30 from a 0.2.19 UI preview build, in light appearance with an isolated, empty data directory. No games, keys or player data are shown. The setup assistant illustrates components needing attention in this preview.

Documentation

Guide	Contents
Getting started	Setup, IPA export, controllers, language and data management
Environment and repair	Dependencies and toolchain troubleshooting
Development	Tests, local App / DMG builds and CI
Release notes	Changes in English and Chinese
Architecture · Engine interface · Validation record	Implementation and recorded validation scope (Chinese)

For a failure, open the task log or copy its redacted error summary. Include the app, chip, macOS and Xcode versions, plus reproduction steps, in your issue. Review diagnostics before sharing and exclude games, keys, firmware, saves and private caches.

Engine updates and releases

nxnative is synchronized from upstream once a day, with updates committed to main only after CI passes. If an upstream change fails validation, the previous verified snapshot is retained.

When there are no regular feature updates, LumaNX releases once a week to include the accumulated nxnative updates. Feature updates follow their own release schedule. Daily engine synchronization and the weekly DMG release are separate: an installed app uses the engine bundled with that build.

To use the latest successfully synchronized nxnative before the next release, build from the current main branch using the steps below. Re-prepare games to apply the new engine to their runtimes.

Build from source

Use an Apple Silicon Mac running macOS 26 or later, with a native arm64 terminal (uname -m). Install Homebrew and the .NET 10 SDK for macOS Arm64. Open the full Xcode app once, accept its license and finish initial component installation. Adjust DEVELOPER_DIR below if Xcode is installed elsewhere.

1. Get the latest verified sources and prepare the toolchain. dotnet --list-sdks must show a 10.0.x SDK, and the Metal command must report an Apple Metal compiler version.

   git clone --branch main https://github.com/Xc1Ym/LumaNX.git
   cd LumaNX
   export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
   xcodebuild -version
   xcodebuild -downloadComponent MetalToolchain
   xcrun --sdk macosx metal --version
   dotnet --list-sdks
   
   brew install python@3.14 spirv-cross zstd xcodegen actionlint
   mkdir -p work
   "$(brew --prefix python@3.14)/bin/python3.14" -m venv work/python-venv
   work/python-venv/bin/python -m pip install -r requirements-runtime.txt -r requirements-build.txt
   

2. Run the launcher checks from the repository root.

   actionlint .github/workflows/*.yml
   work/python-venv/bin/python -B -m unittest discover -s tests -v
   swift test --disable-sandbox --cache-path "$PWD/work/spm-cache" -c release
   

3. Build in this order. The scripts download pinned conversion dependencies, collect the portable runtime, compile the metadata reader, then build and sign the app and create the DMG. Internet access is required during dependency collection and the first reader build.

   swift scripts/make_icons.swift
   work/python-venv/bin/python -B scripts/bundle_converter.py
   work/python-venv/bin/python -B scripts/bundle_runtime.py
   work/python-venv/bin/python -B scripts/bundle_engine.py
   work/python-venv/bin/python -B scripts/package.py
   work/python-venv/bin/python -B scripts/source_archive.py
   work/python-venv/bin/python -B scripts/verify_release.py
   

The outputs are release/LumaNX.app, release/LumaNX-<version>-arm64.dmg, the source ZIP and release/SHA256SUMS; <version> comes from product.json. The last command verifies signatures, the DMG, source contents, checksums and runtime relocation. Close any running copy built into this output directory before rebuilding. Packaging uses ad-hoc signing and needs no Apple Developer signing account.

For a later update, run git pull --ff-only in this main checkout and repeat the checks and build steps. The bundled engine revision is recorded in Engine/nxnative/manifest.json. For native-engine and iOS checks, see the CI workflow and development guide; the Metal/iOS fixture check also requires Xcode's iOS platform. Building the launcher and its distribution does not require games or keys.

LumaNX was previously called LumaDock. The original icon, application identifier, library and settings remain compatible with existing installations.

Credits and license

Thanks to nxnative for execution and graphics, and to MacNativeGames and d2r-mobile for upstream contributions. Conversion tools adapt SAK-Mac. See third-party notices for these components and dependencies including Ryujinx / Spv.Generator, LibHac, SPIRV-Cross, CPython and .NET.

Launcher code and original artwork use the MIT License. Third-party components retain their own licenses. Games, updates, DLC, firmware, keys, game artwork and player caches are not included. Use only content you are authorized to use. Nintendo and game trademarks belong to their owners; LumaNX is not affiliated with or endorsed by Nintendo or game publishers.