This guide takes you from your own dump of Pokémon Pokopia to the game running as a Mac app: building it, updating it, the graphics refresh, the controls and the Mac's own settings.
The same download also builds the iPhone app; Playing on your iPhone has the phone's side. Back to the overview.
On this page
- What you need
- Get the download
- Build with the app
- The builder window
- The command line
- Play
- The shaders, and Refresh the graphics
- Controls
- The launcher's settings
- Playing together and your save
- The app icon
- Updating
- Problems
What you need
- A Mac with Apple silicon (M1 or newer) and about 20 GB of free disk. The game's code is arm64, the instruction set of Apple's own chips, so an Intel Mac can't run it.
- 16 GB of memory is recommended. The game itself uses about 6 GB, so on an 8 GB Mac it can run out of graphics memory once macOS and your other apps have taken their share.
- Xcode 27, with its command line tools and the Metal toolchain (Xcode → Settings → Components). For the iPhone app you also need the
iOS platform from that same screen, and
xcodegen(brew install xcodegen). - Python 3.12 or newer, with the builder's own environment (next section).
- The .NET 10 runtime, which the shader translator runs on:
brew install --cask dotnet-sdk. - Your dump (below).
The app's check (or python3.12 nxs2.py doctor) checks all of this and tells you how to get whatever is missing.
The builder's Python environment
Homebrew's Python takes no pip packages of its own (pip stops with "externally-managed-environment"), so the builder's packages go into a private environment: a folder with its own Python and its own packages. Make it once, in Terminal:
brew install python@3.12 python-tk@3.12
python3.12 -m venv ~/.pokopia-native/venv
~/.pokopia-native/venv/bin/python -m pip install "capstone>=5,<6" lz4 fonttools pillow zstandard
(Pillow is only for the app icon; zstandard reads .nup files.) Pokopia Native.app uses this environment by itself (else a
python3.12 or newer from Homebrew). When it finds no Python 3.12 or newer, its check says so; run the commands above, then open it again.
For the commands in these guides, run source ~/.pokopia-native/venv/bin/activate first in each Terminal window: python3.12 and pip are
then the environment's.
Your dump
The game's files as your dumping tool wrote them, with the update:
<your folder>/updates/<version>/exefs/ main main.npdm rtld sdk subsdk0
<your folder>/updates/<version>/romfs/ LD_C0_R.BIN LI_C0_R.IDX motor_asset_re/ movie_asset/
(exefs holds the game's code, romfs its data.)
- A folder that holds
exefs/andromfs/directly works too. - So does a
.nupfile, a container of an already-decrypted dump: pick it with .nup file… in the builder, or give its path tonxs2.py build. The builder unpacks the update it needs into the build folder once (7 to 10 GB more). It reads.nupfiles with Python'szstandardmodule, in the builder's own environment:~/.pokopia-native/venv/bin/python -m pip install zstandard(one made before 1.5.1 lacks it; an install intopython3.12itself isn't seen by the builder). - Two updates of Pokémon Pokopia (title
0400A3A01EE4C000) are supported, and the builder tells you which one you have: 2.0.1 (v655360) and 1.0.5 (v327680). The base game alone isn't enough, and another version won't build until it is added, because the patch recipe and the camera's address are different for each version. - Copy the dump in binary mode. If you move it off the console with FTP, set the transfer type to Binary (FileZilla: Transfer →
Transfer type → Binary). The default "auto" mode treats files without an extension as text and quietly drops bytes from
main,sdkandsubsdk0. The builder checks for this and tells you.
Get the download
Download Pokopia Native for Macs (the newest release) and unzip it into a folder of its own. Pokopia Native.app in it builds the Mac app and, if you want it, the iPhone app. Keep it in that folder: it builds with the tools beside it. The iPhone app has to be signed by a paid Apple Developer team: read Playing on your iPhone before you choose it.
The first time you open the app, macOS blocks it, because it isn't signed by a registered developer. Control-click it and choose
Open, then Open again; or try to open it once, then go to System Settings → Privacy & Security and press Open Anyway. Or, once,
in Terminal: xattr -dr com.apple.quarantine "<the unzipped folder>". A copy you cloned with git opens directly.
Build with the app
Double-click Pokopia Native.app. The first time, it takes you through four steps:
- Game files. It looks for your dump (or a
.nupfile) in Downloads, Desktop, Documents, Games and your home folder, and says which game version it is. Choose another folder or Use a .nup file picks one by hand. - Check. It checks your Mac: Apple silicon, Metal, the build tools (Xcode with its Metal toolchain, Python and .NET) and the free space. Whatever is missing is marked with how to get it; fix it and press Check again.
- Build. Start building runs Setup once for this download (it fetches nxnative into the download's folder), then the build. It uses every core at low priority: Apple silicon takes that, and you can keep using your Mac. The first build takes about an hour, nearly all of it compiling the game's shaders for Metal; after that, rebuilds take a couple of minutes. Quitting is safe: the next build carries on where it stopped.
- Play. Press Play.
After that the app opens on Home: Play, your save and its backups, the Expansion Pass, the iPhone app and Refresh the graphics. Its other sections:
- Build: this Mac's game (Build again redoes only what changed or is missing; Check this Mac; the other game version; the last build's logs; the game folder; Refresh for the graphics), and Set up the iPhone app (the iPhone guide).
- Link Play: on a Mac it's chosen in the game's own launcher (below).
- Saves and DLC: your save's backups, Bring my save from another device, and Add my DLC.
- Settings: Controls (the same keys and buttons as the game's own settings) and App (the daily update check, starting straight into the game, and the versions on this Mac).
- Help: the common problems, and Report a problem, which makes one file with the logs for the Discord.
Mods (Modtopia) are on Windows and Linux only.
Coming from the builder window: the app reads what the builder recorded, your game files and your build folder, so a Mac game you built before is ready in it. If an older version built it, Home offers Update my game first.
The builder window
Pokopia Native Builder.app, the window the Mac download had before the app, is still in the download: it builds the same way, step by step. Its Advanced view (top right) has every button on one screen, for when you know your way around:
- What to make: Mac app; iPhone IPA (the iPhone app, unsigned); Xcode project, team ID: with your Apple developer team ID, for signing with Xcode (the iPhone guide); and Mac only, which skips the iPhone's shader libraries and is faster.
- Full speed: off, the build uses all cores at low priority; on, the same at normal priority.
- The buttons, in order of use: Check tools, Setup (once for each new download), Build, Refresh shaders and Sign IPA. Open build folder shows the build folder in Finder.
The command line
The command line does the same as the app. In Terminal, with the builder's environment active:
git clone https://github.com/xFractals/pokopia-native.git
cd pokopia-native
python3.12 nxs2.py setup
python3.12 nxs2.py build "/path/to/your dump folder" --mac-app --ipa
setup fetches nxnative (the project the Mac and iPhone apps run on, see How it works) at the exact commit this release
is made for, applies the Switch 2 patch to it, and builds the shader lowering tool. It takes about a minute, once for each new download.
build does everything else. It makes a build folder beside your dump (<dump folder>_native; --out names another place) and goes
through these stages. If it stops, or you stop it, run it again and it continues where it was.
| Stage | What happens | Time on an M4 Mac |
|---|---|---|
| extract | your ExeFS copied, the RomFS files packed into one image (6 to 7 GB) | seconds |
| rewrite | the game's three code modules rewritten so Apple's kernel can run them | 20 s |
| host | the Mac host compiled with this game's profile | 15 s |
| corpus, lower, package | 4,012 shader programs found in the game files, lowered, packaged with their tables | 25 s |
| chain | the Metal compile of every shader, for the Mac and the phone | 30 to 45 min |
| outputs | the Mac app, the IPA, or the Xcode project | 1 to 3 min |
Outputs land in <build folder>/out/:
Pokemon Pokopia.app: the Mac app (Play).PokemonPokopia-unsigned.ipa: the iPhone app without the game files. With--xcode --team-id <your team>you get an Xcode project to sign with your team instead (the iPhone guide).
More:
--no-iosbuilds for the Mac only: it halves the compile.python3.12 nxs2.py run "<build folder>"plays straight from the build folder in a window, which is handy while you try things out.python3.12 nxs2.py status "<build folder>"says what the build folder has and what it still lacks.nxs2.py -vshows each stage's full output live.
Play
Press Play in Pokopia Native, or double-click Pokemon Pokopia.app in <build folder>/out/ yourself. macOS asks once whether to open it:
right-click the app → Open, or System Settings → Privacy & Security → Open Anyway. The app can't be notarized (checked and approved by
Apple), because it maps the game's code as executable, which Apple's hardened runtime doesn't allow.
The app's launcher, a settings window, comes up first (its settings). Press Play.
- Your save lives in
~/Library/Application Support/nxnative/0400A3A01EE4C000/save, outside the app, and the logs in~/Library/Logs/nxnative/. - The game files inside the app are APFS clones of the build folder's image, so the app doesn't take another 6 GB on the same disk.
- On the first launch the title screen is black apart from its text. That's expected: see the next section.
- F1 or Settings… (⌘,) opens the game's settings while you play (Controls).
The shaders, and Refresh the graphics
Shaders are the small programs the graphics card runs to draw each thing on screen. The build translates every shader in the game's files for Metal. But Pokopia also makes some shaders itself while it runs: 140 are known on game version 1.0.5, and 2.0.1 makes 14 more (154 in all). A fresh build can't contain them, so when the game asks for one your build doesn't have yet, that one effect or object isn't drawn. Nothing crashes. The title screen alone uses about 20 of them, so on the very first launch it is black apart from the version number and "Settings". The music plays and A still works. It isn't a broken build, and it's gone after the first refresh.
The app records each such shader the moment the game makes it. To build them in:
- Play a few minutes into the game: the opening, the character creator, the first area. Then quit the app.
- In Pokopia Native, press Refresh the graphics on Home (or Refresh in Build; in the builder window, Refresh the graphics; from
Terminal:
python3.12 nxs2.py refresh "<build folder>"). It finds the Mac app's recordings by itself, translates the new shaders in a couple of minutes, not another hour, and rebuilds the app (and the iPhone app, if your build folder has one). - Open the app again.
Repeat when you reach new places and notice something missing; after the opening and the first area you usually have them all. The build
tells you where you stand: shaders: 3813 from the game files; 0 of the 140 known run-time shaders right after the first build, and
140 of the 140 (on 2.0.1: 154 of the 154) after a refresh with a full set of recordings. If you have never run setup in this folder,
run it once before you refresh from Terminal.
After every rebuild (an update, say), run Refresh the graphics again.
If the build finds run-time shaders beyond the known ones, tell us in the issues with the count it prints, so the list can grow. Don't attach the recordings: they are game code. Why the Mac works this way: How it works.
Controls
- Mouse: click the game picture and the mouse is captured. Move it to look around; left click is A, right click is B, and the middle button resets the camera. Esc gives the mouse back.
- Keyboard: WASD moves, J K U I are A B X Y, Q E are L R, Z C are ZL ZR, Return is + and Tab is −.
- Trackpad: works like the mouse. A MacBook's trackpad ignores your finger while keys are held down (palm rejection), so the camera doesn't turn while you hold a movement key. An external mouse or a controller doesn't have that problem.
- A controller works too.
- Look sensitivity and Invert look up and down are in the launcher, under Controls.
- For the smoothest mouse camera, turn the game's own Camera Auto-Follow off (in the game's Settings, Camera tab). With it on, the game turns the camera itself while you walk sideways, and the app has to steer it the way a stick would, in small steps. With it off, the mouse and the trackpad turn the camera directly.
Settings during the game: press F1 (fn-F1 on most Mac keyboards) or choose Settings… (⌘,) in the app menu. A window opens over the game: - Keyboard keys: click an action, then press the key you want for it. - Controller buttons: one map for every controller. - Player 1: pick which controller it is; it's remembered. - Graphics: console mode, upscaling, and the window or fullscreen.
The keys and buttons are kept in the same controls.json file as on Windows.
The launcher's settings
The launcher is the settings window the Mac app shows before the game starts. Besides the frame rate, the ones worth knowing:
- Console mode: handheld or docked (TV). Docked lets the game pick its higher resolution.
- Display mode: Window or Fullscreen.
- Upscaling: Standard or MetalFX (Apple's upscaler): how the game's picture is scaled up to fill your window or screen.
- Controls: Look sensitivity and Invert look up and down.
- Link Play: Link Play on this network, Join address, Internet play, Room code, Interact everywhere and Story co-op (Playing together).
The Mac app runs on its own Metal engine, so Windows' Resolution setting, Wide view and in-game settings window aren't on the Mac.
Playing together and your save
- Link Play works between the Mac, Windows PCs, iPhones and the Linux beta: Playing together. You turn it on in the launcher. To host over the internet from a Mac, forward a port on your router by hand, or use a VPN.
- Your save is in
~/Library/Application Support/nxnative/0400A3A01EE4C000/save(Finder → Go → Go to Folder…). To bring one from Windows, the iPhone or Linux, quit the game and use Bring my save in Pokopia Native's Saves and DLC: it keeps the save you have beside it. By hand: Moving your save.
Your DLC
If you bought the game's DLC, the Mac app can use it too, from your own dump of it, made the same way as your dump of the game:
- In Pokopia Native, press Add my DLC in Saves and DLC (in the builder window: on its last page, or DLC… in Advanced) and
choose the folder your dumping tool made from your DLC: its RomFS, or the folder holding it. From Terminal:
python3.12 nxs2.py import-dlc "<build folder>" "<your DLC folder>". - It's copied into your build folder's
dlcfolder, and the builder packs the Mac app again with it inside (the iPhone app too, if the build folder has one: see Playing on your iPhone). The app owns it from its next start. Your folder is only read.python3.12 nxs2.py import-dlc "<build folder>" --removetakes it out again and packs the app without it. - Only your own DLC. Pokopia Native never downloads, makes or unlocks DLC: without your dump of it, the game has none. Never share your DLC folder, a build folder that holds one, or an app made with it.
The app icon
Out of the box the apps get Pokopia Native's own icon, because the game's own icon isn't part of a dump. python3.12 nxs2.py icon "<build folder>"
makes one from your game instead: it starts the game on a copy of your save, takes a picture of the title screen and cuts the Pokopia logo out of it.
It needs a save that is past the game's opening (play a little first, or point it at one with --save <folder>). Or give it a screenshot of
the title screen from your Switch 2 (Capture button): python3.12 nxs2.py icon "<build folder>" title.jpg. Then build again with the same
command; it only repacks the apps.
Updating
Your build folder, the shaders you have recorded and your save all carry over. Pokopia Native tells you when a new version is out (it asks the website and GitHub once a day; Settings, App turns that off), and Update now does steps 1 and 2 for you: it downloads the new version beside this one, backs up your save, and opens the new app, which updates your game. The version you had stays on your Mac: Settings, App, Versions switches back to it in seconds. By hand:
- Download the new version (Get the download) and unzip it into a new folder.
- Open Pokopia Native from the new folder. It offers Update my game: it runs Setup and builds again into the same build folder.
(From Terminal:
python3.12 nxs2.py setup, then the samebuildcommand as before.) Only what changed is redone, so it's much quicker than the first build. - Run Refresh the graphics again afterwards.
- If you keep a copy of the app somewhere else (in Applications, say), replace it with the new one. Your save is outside the app and stays.
- iPhone: sign the new app and install it over the old one. Never delete the app first: that deletes its save (the iPhone guide).
Link Play needs matching versions on every device (which versions play together), so update them all.
Problems
- Every build stage writes its full output to
<build folder>/logs/<stage>.log, andpython3.12 nxs2.py status "<build folder>"says what the build folder has and what it still lacks. The game's own logs are in~/Library/Logs/nxnative/. - The common Mac problems, with what to do: an 8 GB Mac running out of graphics memory, the trackpad and mouse look, Python's "externally-managed-environment", a failing Metal check, macOS refusing to open the builder or the app, a different Xcode version: Troubleshooting.
- Still stuck? Ask in the Discord, or open an issue with the stage, the last lines of its log and your Mac, macOS and Xcode versions. Never attach game files, build folders or recordings.