Mac Native GamesTHE APPLE SILICON FIELD GUIDE

NXNATIVE / APPLE SILICON MAC

nxnative for Mac: setup, supported games & fixes

Turn your own supported Switch files into a self-contained Mac app. Match the game profile first, choose the Mac-app target, then find the launch settings, saves and logs.

Find your game ↓Start the Mac build ↓
YOUR GAME, BUILT FOR MAC
Base + updateGame.app
Mac-app packaging diagram · game examples from the profile list.

Instructions use seedds/nxnative ae4ec43 · 29 October 2026. Mac-app, developer Mac and iOS outputs are separate choices.

Choose your Mac build route

CORE NXNATIVE

Build from Terminal

Use a fixed checkout, prepare the tools and run the Mac-app command. The guide keeps every file and output path explicit.

Prepare the command-line route →
OPTIONAL GUI FORK

Use NX2Apple

The separate graphical builder collects your files and output choice in a window. Follow its own dependency checker and managed-library controls.

Follow graphical setup →
NX2Apple graphical builder · Mac outputOpen original ↗

01Select This Mac

Actual NX2Apple This Mac choice is selected; the adjacent iPhone/iPad route is separate.

02Start Build game

Actual NX2Apple Build game button at the bottom right.
Choose This Mac, then Build game after supplying your files. This separate GUI fork uses TOTK sample paths in the upstream image; the core command-line route is below. Source ↗
View the complete window
Complete English NX2Apple Build game window, with sample TOTK files, This Mac selected and Build game.

Open original at full resolution ↗

Prepare the build Mac

The computer and tools

  • Apple silicon Mac; macOS 26.6 or later.
  • Full Xcode 27.1 with its Metal toolchain.
  • Native arm64 Python 3.12+, .NET 10 SDK and Homebrew.
  • The Python modules and Homebrew utilities installed below.

The game and workspace

  • Your base game, matching update and prod.keys.
  • A local folder with room for extraction and shaders.
  • Upstream planning estimate: about twice the game size plus 10 GB free.
  • Allow 30–60 minutes for a first build; this varies by game and Mac.

These are build-host requirements. The finished app records its own minimum macOS from the compiled host. A graphical frontend opening on an older OS does not make Xcode 27.1 run there.

01

Select the full Xcode installation

Install Xcode 27.1 and its Metal toolchain from Apple. Open it once to complete setup. Check the selected tools:

Inspect the active Xcode and Metal tool
xcode-select -p
xcodebuild -version
xcrun -f metal

The first line should name the full Xcode developer folder, rather than /Library/Developer/CommandLineTools. If the full app is at the following path, select it:

Only for Xcode installed at /Applications/Xcode.app
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
02

Install dependencies in a native Python environment

Use an arm64 Homebrew installation. Keep the Python packages in a virtual environment so the build uses the same interpreter as the installed modules.

Homebrew tools and .NET SDK
brew install python xcodegen zstd glslang
brew install --cask dotnet-sdk

Confirm dotnet --list-sdks includes 10.x. If Homebrew supplies a different major version, install the .NET 10 SDK from Microsoft’s 10.0 downloads.

Create the build environment
python3 -m venv "$HOME/.venvs/nxnative"
source "$HOME/.venvs/nxnative/bin/activate"
python -m pip install lz4 capstone fonttools nsz
python -m pip install 'backports.zstd; python_version < "3.14"'
python -c 'import platform; print(platform.machine())'

The architecture should be arm64. An Intel Python under Rosetta can start incompatible tool slices even on an Apple silicon Mac.

Build-script dependency and architecture checks ↗

Find the game and its exact profile version

The upstream gallery lists 104 game entries across Mac and iPhone. The list below maps those entries to the source profile’s build version. Open a game’s notes to read which platform, scene and limitations were recorded; a gallery entry is not a complete Mac playthrough.

104 upstream gallery entries

Hades ↗

Profile version: 1.0.38233

0100535012974000

Bastion ↗

Profile version: 1.0.0 (base)

010038600B27E000

Regional profiles may have different title IDs. Use the ID of your base game, not its update or DLC ID. Open the complete source index, including regional profiles ↗.

For Monster Hunter Rise 16.0.2, the dedicated guide explains the input files and 60 FPS report. For the MacNativeGames project’s Zelda route, keep using the separate TOTK build wizard; its arguments and saved data are different.

Build a self-contained Mac app

03

Get the guide’s source in a separate folder

Keep an existing modified checkout intact. The fixed revision below makes the commands and profile list reproducible.

New checkout of the documented source
git clone https://github.com/seedds/nxnative.git nxnative-guide
cd nxnative-guide
git checkout ae4ec43d57845bdaf07f15cdb39a31363f158048
04

Group one game’s input files

Put the base and matching update in one folder. Add owned DLC packages only when needed. Keep unrelated games and older duplicate updates elsewhere: the packer normally selects the newest update in the input folder.

~/Games/MarioWonder/
├─ base.nsp
└─ update.nsp

~/keys/prod.keys

The filenames are examples. Keys remain a separate input; the script reads them locally. Compressed NSZ/XCZ inputs require the nsz dependency.

05

Choose mac-app explicitly

Run from the nxnative-guide checkout · replace paths for your game
source "$HOME/.venvs/nxnative/bin/activate"
python scripts/build_ipa_from_nsp.py "$HOME/Games/MarioWonder" -k "$HOME/keys/prod.keys" --platform mac-app

The default output is the game’s named .app in the input folder. To choose another location, append -o "/path/to/Game.app". Leave the build running while it extracts, rewrites, translates shaders and packages the app.

For a player

--platform mac-app creates the Finder app. Copy or move the entire app after completion; it carries its runtime game data.

Other targets

--platform mac builds the development host. With no platform argument, the script builds an iOS IPA. --romfs separate belongs to iOS, not the Mac command.

06

Open the finished app

Open the completed app in Finder, choose launch settings and press Play. Keep the input and build folders for faster rebuilds even though the self-contained app does not depend on them.

If macOS shows a warning, match the actual downloaded-app message. If the app exits or hangs, use the title-ID log before changing unrelated settings.

Mac-app packaging and build outputs ↗

Prefer a graphical builder?

See the Mac-output controls above ↑

NX2Apple is a separate fork with a graphical library and builder. Its Mac release is NS-Port-Builder-macOS-arm64.zip. Use its own installation instructions and dependency screen.

  1. In initial setup, use Download repository and let its dependency checker finish.
  2. Choose Build game. Select a game folder or provide the base, update, DLC and keys separately.
  3. Select This Mac, choose Save to, then start Build game.
  4. Follow the current build in Builds; open the finished game from Library.

The frontend can open on macOS 13, but the documented shader build still needs macOS 26.6 and Xcode 27.1. Its managed-library folders differ from the core Mac-app folders below; use the fork’s own data controls when backing up that route.

See the fork’s English library and launch controls
NX2Apple library · Play and ManageOpen original ↗

01Play the selected game

Actual English Play button in the NX2Apple library.

02Open game actions

Actual English Manage menu beside the selected game’s Play control.
Play starts the selected library game; Manage opens that fork’s game actions. Its managed data locations differ from the core Mac-app folders. Source ↗
View the complete window
Complete English NX2Apple library with Breath of the Wild selected.

Open original at full resolution ↗

NX2Apple launch options · BOTW exampleOpen original ↗

01Frame-rate choice

Actual frame-rate selector offers 30 fps and 60 fps, with 60 selected.

02Upscaling choice

Actual upscaling selector offers Standard and MetalFX, with MetalFX selected.
These are the fork’s Breath of the Wild controls. Keep the game/profile distinction when choosing settings; this is not a Rise performance preset. Source ↗
View the complete window
Complete English NX2Apple launch-options window for Breath of the Wild.

Open original at full resolution ↗

Set up the first launch

The core Mac app presents a settings window before play. Available options depend on the game profile. Start with its defaults and change one option at a time.

Frame rate

Choose the game’s offered target. 60 is a target, not a promise for every scene. Use 30 to compare power use and pacing.

Render scale & mode

Render scale changes internal resolution. Console mode changes the game’s docked/handheld behavior; it is a separate choice.

Advanced settings

Upscaling and the Mac Performance HUD live here when offered. The phone’s frame-rate-counter option is not the Mac HUD.

  1. Choose the available frame rate, render scale and language.
  2. Choose Window or Fullscreen, then Play or Return. Ctrl–Cmd–F also toggles fullscreen during play.
  3. If you hid this window, hold Option while opening the app to show it again.
  4. To undo experiments, choose Reset to tested defaults. A setting fixed by env.txt remains overridden until that override is removed.

Pair a controller with macOS before launching. DualSense/DualShock 4 motion is documented by the project; do not assume an unmerged controller PR is already included in this revision.

Core settings and precedence · Playing and controller notes ↗

Find saves, settings and the launch log

For the core Mac-app output, replace TITLE_ID with the 16-character ID from the lookup. Rise uses 0100B04011742000.

Finder → Go → Go to Folder · core Mac-app data
~/Library/Application Support/nxnative/TITLE_ID/
TITLE_ID/
├─ save/           ← saved progress
├─ env.txt         ← optional launch overrides
├─ pso_user.tsv    ← learned pipeline data
└─ …
Launch log location · substitute the title ID
~/Library/Logs/nxnative/TITLE_ID.log

The previous launch log uses .prev.log. Quit the game and duplicate the whole title-ID data folder to a dated backup before changing source or game version. Keep that copy outside the active folder.

To test a restore, keep the current data folder under another name, put a copy of the backup at the original title-ID location, then launch and check progress. Restore the kept current folder if the test fails. Do not treat pipeline data as a substitute for save/.

Fix the first stage that fails

The script builds an IPA or never produces a Finder app
  1. Check the command used for this run.
  2. Use --platform mac-app; mac is the development host and the default is ios.
  3. Look for the completed .app in the input folder or the explicit -o location.
Metal compiler or developer-tool check stops the build
  1. Run xcodebuild -version and xcrun -f metal.
  2. Select the full Xcode 27.1 installation and finish its toolchain setup.
  3. Retry the same command; do not use a compiler-bypass flag to conceal a mismatch.
Python modules or .NET cannot be found
  1. Activate the same virtual environment used to install the modules.
  2. Confirm Python reports arm64 and dotnet --list-sdks includes 10.x.
  3. Read the first missing-module/runtime line before reinstalling anything.
The game version differs from the profile
  1. Compare the base title ID and selected update with the profile notes.
  2. Move unrelated or unintended newer updates out of the input folder.
  3. A newly derived profile may build but still miss game-specific patches; do not assume equal compatibility.
The app opens but settings are grey or the window is hidden
  1. Hold Option while opening to restore the settings window.
  2. Inspect env.txt for fixed values; retain a copy before removing an override.
  3. Use Reset to tested defaults after removing the relevant override.
The app hangs, exits or draws incorrectly
  1. Keep the exact game version, source revision and first failing scene.
  2. Read Library/Logs/nxnative/TITLE_ID.log and compare the game’s Open notes.
  3. Retry the original defaults without extra overrides. Known rendering gaps may require source work rather than another settings combination.

nxnative, MacNativeGames or an emulator?

nxnative

A multi-game ARM64 host with per-game profiles, NVN-to-Metal translation and Mac/iOS outputs. It grew from d2r-mobile; it is not the next release of MacNativeGames.

Follow the Rise-specific route →

MacNativeGames

A separate project and script, with its own accepted Zelda versions, tools, settings and save folders. Keep its commands separate from nxnative.

Compare the three builders →

Sharing the ARM64 processor family removes one kind of CPU translation, but system services, graphics translation and game-specific fixes still matter. “Native” does not establish universal compatibility or a zero-cost performance advantage over an emulator.

Browse all community projects →