How to use nxnative

Q: Can I change the game language?

Yes. Pick one when packing with --language (for example -l ja or -l French); it must be one the game has. You can also change it on the settings screen without rebuilding.

Q: Where are my saves?

In the Files app, under the app’s name, in save/. Some sideloading tools give a reinstalled app a new data folder; copy save/ and pso_user.tsv over to keep your progress.

Q: Can I play on a Mac instead?

Yes. Pack with --platform mac-app to get a Mac app you open from Finder (Apple silicon).

Using nxnative means three things: building an app from your own game on a Mac, installing it on your iPhone or iPad, and playing. This is the official process in plain order. It assumes you already have your own game files and keys; this site does not cover obtaining them.

Step 1: get nxnative and its tools (once)

On a Mac with Xcode and Homebrew:

git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd spirv-cross glslang
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools "backports.zstd; python_version < '3.14'"

Step 2: put one game in a folder

One folder per game, with the base game plus its update and DLC if you have them. Compressed NSZ and XCZ files also work; the script converts them once. The newest version in the folder is the one that gets packed.

Step 3: run the script

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys

The IPA appears in the same folder. Useful options: -o sets the output path, --app-name the app’s name, --language the game language, --show-fps shows the frame rate, and --platform mac-app builds a Mac app instead. Run it with -h for the full list.

Step 4: install the IPA

Install it with your sideloading tool: AltStore, Sideloadly, LiveContainer or similar. Sign it with the Increased Memory Limit capability if your tool can, so bigger games are not closed by iOS. The app gets the game’s name, icon and version. With an Apple developer account you can instead use --prepare-xcode and install from Xcode.

Step 5: play

Settings screen. Before the game starts you can pick frame rate, render scale, docked or handheld mode, language and an FPS counter. Tap Play.
Touch controls. Switch between 2D and 3D layouts at the top. In 3D, swipe on the right third of the screen for the camera. A controller hides the touch controls.
Rumble. Uses the iPhone’s haptics or a compatible controller, with its own on/off and strength settings.
Saves and logs are in the Files app under the app’s name. If something goes wrong, the project asks for log.txt.

Easier option: NX2Apple

NX2Apple is a community fork with a macOS app that runs the same pipeline without the command line, and packs game files more compactly for a slimmer IPA. It is a separate project.

How-to questions

How long does building take?

The first build takes 30–60 minutes, later ones about 10.

Can I change the game language?

Yes. Pick one when packing with --language (for example -l ja or -l French); it must be one the game has. You can also change it on the settings screen without rebuilding.

Where are my saves?

In the Files app, under the app’s name, in save/. Some sideloading tools give a reinstalled app a new data folder; copy save/ and pso_user.tsv over to keep your progress.

Why does it stutter the first time?

The app compiles graphics the first time a new scene appears and remembers them for the next launch. Short stutters on first visits are normal.

Can I play on a Mac instead?

Yes. Pack with --platform mac-app to get a Mac app you open from Finder (Apple silicon).

Developer details are in the official development guide. See also the games list.