LumaNX README

The project's README from github.com/Xc1Ym/LumaNX. As one markdown file: README.md.

LumaNX icon

LumaNX · 璃游

Graphical Switch game builds & packaging · macOS / iOS / iPadOS

English · 简体中文

Apple Silicon · macOS 26+ · SwiftUI / Liquid Glass

Download for Mac · Build status

LumaNX is a graphical Switch game builder and packager running on Apple Silicon Macs, and a third-party GUI for nxnative. With the bundled nxnative engine, your authorized NSP/XCI files and prod.keys, import games, prepare and launch them on Mac, or export an unsigned iPhone / iPad IPA.

nxnative provides native execution and Metal graphics; LumaNX provides the library and graphical workflow. The engine is included; games, updates, DLC, firmware, keys, game artwork and player caches are not.

nxnative is synchronized from upstream daily, with automated tests before repository updates. To use the latest synchronized engine, build the App or DMG yourself. Releases provide only the DMG, on demand, not daily.

Switch Pro, Xbox and PlayStation controllers use native GameController input: Switch A / Xbox A / PS cross → game A, with no manual key mapping. Prepare existing games again to apply the new engine.

Previously LumaDock. The project is now named LumaNX. The original icon, application identifier, game library and settings are retained.

Features

Get started

Requirements: Apple Silicon and macOS 26+. Preparing games also requires full Xcode with Metal. nxnative, the reader, shader translator and runtime dependencies are included in packaged apps.

  1. Download the latest ARM64 DMG, verify its SHA-256 against the Release notes, and drag LumaNX.app into Applications. Current builds use ad-hoc signing and are not notarized.
  2. Follow setup: check the environment and choose Prepare engine tools; no separate engine download is needed.
  3. Choose a library, import your own prod.keys, then add the base game, updates and DLC as NSP, XCI, NSZ or XCZ files.
  4. Prepare the game and choose Launch game, or choose Generate IPA… in game details. Tasks show progress and support cancellation and retry.

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

Compatibility depends on the selected engine and game version. Successful preparation does not guarantee full gameplay compatibility; iOS device compatibility has not been validated. Back up saves before upgrades or experiments.

Screenshots

LumaNX 0.2.15 in light appearance with an empty test library; no player data or game content.

LumaNX game library
Setup and Settings LumaNX setup assistant LumaNX settings

Documentation and help

Guide Contents
Getting started Setup, IPA export, input, language and data management
Environment and repair Dependencies, installation and toolchain troubleshooting
Development Tests, local builds and CI releases
Release notes Latest changes in English and Chinese
Architecture · Engine interface · Validation record Technical details and bounded test evidence (Chinese)

For failures, open the task's log or copy its redacted error summary. Report an issue with the app, chip, macOS and Xcode versions plus reproduction steps. Review diagnostics before sharing; never upload games, keys, firmware, saves or private caches.

Acknowledgements and license

Special thanks to nxnative for the core execution and graphics capabilities, and to MacNativeGames and d2r-mobile for their upstream contributions. File conversion adapts code from SAK-Mac (MIT). The pinned engine and its license are included. Thanks also to Ryujinx / Spv.Generator, LibHac, SPIRV-Cross, CPython, .NET and other dependencies; see the full third-party notices.

Launcher code and original artwork use the MIT License; third-party components retain their own licenses. The software is provided “AS IS.” Use only content you are authorized to use. Nintendo and game trademarks belong to their respective owners; this project is not affiliated with or endorsed by Nintendo or any game publisher.

Topics

nintendo-switch · nxnative · gui · macos · ios · ipados · apple-silicon · swiftui · metal · game-launcher · game-packaging · native-execution

LumaNX (Xc1Ym/LumaNX)

nintendo-switch
Searching Database…

243 ·GitHub
LumaNX
What is this?LumaNX is a macOS GUI for the nxnative engine that lets you turn your own authorized Nintendo Switch game files (NSP/XCI) into prepared builds you can run on an Apple Silicon Mac, or export as an unsigned IPA for iPhone/iPad.
Is this an emulator, or just a launcher for the engine?It's a native macOS desktop app (GUI) that wraps the bundled nxnative execution engine; nxnative provides native execution and Metal graphics, while LumaNX provides the library UI, build pipeline, save management and IPA export workflow.
How do I install and run it?Download the latest ARM64 DMG, verify its SHA-256 against the release notes, and drag LumaNX.app into Applications, then run the in-app Setup step to prepare engine tools (no separate engine download needed).
What do I need before I can prepare a game?You need an Apple Silicon Mac on macOS 26+, full Xcode with Metal to prepare games, your own authorized NSP/XCI/NSZ/XCZ files and prod.keys, and XcodeGen (brew install xcodegen) if you want to export an IPA.
Is a successful build guaranteed to run well, and is the app signed?No — successful preparation does not guarantee full gameplay compatibility, and iOS device compatibility for exported IPAs has not been validated; current DMG builds are ad-hoc signed and not notarized, so you'll need to sign the exported IPA yourself before installing it.
Does this work on any Mac, or just newer ones?Apple Silicon only, running macOS 26 or later — Intel Macs aren't supported.
What data should I never share when reporting a bug?The app warns you to review diagnostics first and never upload games, keys, firmware, saves or private caches when filing an issue.
Do I need to manually configure my controller?No, Switch Pro, Xbox and PlayStation controllers work out of the box via native GameController input, with button mapping handled automatically (e.g. Switch A / Xbox A / PS cross all map to game A).
Was LumaNX previously known by another name?Yes, the project was previously called LumaDock before being renamed to LumaNX; the original icon, app identifier, library and settings carried over.
What happens to my save files when I switch engine versions?LumaNX automatically creates a save backup before switching between prepared runtime versions, and you can also manually back up and restore saves.
What file formats can I add to my library?You can import NSP, XCI, NSZ or XCZ files directly or scan a folder; NSZ/XCZ are decompressed automatically, and the built-in conversion tools (adapted from SAK-Mac) can convert or merge packages too.
What are similar projects?NX2Apple, sill, Crest, MacNativeGames, WallpaperMachine, LinuxRunner, kumone, highball
Which topics is it in?game-launcher, nintendo-switch, ipados, swiftui, metal, apple-silicon, ios, gui, python, macos
Creator
Xc1Ym
Size
65.4 MB
Stars
243
Updated
CommitNov 01Releasev0.2.19Oct 30
Age
13d
Commits · 90 Days