Your first nxnative build

What nxnative does

nxnative builds an Apple app from game files and keys you supply. The game code runs on Apple hardware, with a host providing the expected system services and graphics translated to Metal. You choose a target before you build: a Mac application or an iPhone/iPad IPA. This guide is for deciding that route before spending time on a build.

Before you begin

Keep the device you will play on separate from the Mac you will build on. Read the device checklist first. Prepare your own game files, the matching update you intend to use and your own prod.keys. Keep unrelated games in different folders. If you already have progress in an older app, make a separate backup before replacing anything.

Step 1: Check the game, platform and version

1. Find the title in the upstream game profiles.
2. Open that game’s notes and compare its documented version with your files.
3. Look for evidence for your intended platform. A Mac check does not answer an iPhone question.
4. Record the game version and the nxnative commit you plan to use. Keep that note with the output so a later retry can be compared.

Our compatibility finder covers selected source-linked records; it is not the full upstream game catalog. No result in our index does not mean that a game is unsupported upstream.

Step 2: Choose your route

Your goal	Route	What to look for at the end
Open the game from Finder on an Apple silicon Mac	Mac app build	A game .app bundle, using --platform mac-app
Install on iPhone or iPad	IPA build and installation	An IPA that still needs signing and installation
Compare the two projects before starting	nxnative vs MacNativeGames	A matching game profile and device requirement in the chosen project

--platform mac is the developer-host route. It is useful for development, but it is not the same deliverable as the Finder app.

Step 3: Checkpoint for each milestone

Use this sequence as a progress note: build finished → app installed or opened → title screen reached → input works → save can be loaded. Write down the first failed milestone rather than calling every failure a crash. A successful step only establishes that step; reaching a title screen is not a full-playthrough result.

For the first session, start with the documented settings. Keep a note of changes instead of changing several options and the build at once. Before an update, repeat the backup step and keep the known working output until the replacement has been checked.

If a step fails

• No build output: keep the terminal’s first error and the command you used, with private paths and keys removed.
• IPA cannot install: check the signing and installation stage in the mobile guide.
• App closes after launch: use the iPhone crash checklist.
• Mac stays on Preparing pipelines: compare the specific pipeline report with your setup.
• Progress is missing after reinstall: stop replacing the app and check the backup and restore locations.

Return to the guide library for all routes. We have reviewed documentation and reports, not built or played these games ourselves.