Install & Set up guide

Required game dump layout (Version 2.0.1a)

Recompia includes zero Nintendo code or assets. Before running Set up, prepare your own extracted copy of Pokémon Pokopia version 2.0.1a in one of two formats accepted directly by PokopiaLauncher:

• Extracted folder layout: a parent directory (for example Pokopia_v2.0.1a/) containing both base/ and updates/ side by side. Both base and updates must contain their own exefs/ (main, sdk, subsdk0, rtld, main.npdm) and romfs/ subdirectories.
• Single .nup package: select the .nup file directly in the launcher; it extracts the contents into nup_dump/ automatically. (Encrypted single-file console images are not read directly; extract them to folders first with your own dumping tool.)

Pokopia_v2.0.1a/             <-- pick this outer folder in PokopiaLauncher
├── base/
│   ├── exefs/               (main, sdk, subsdk0, rtld, main.npdm)
│   └── romfs/               (base game data archives)
└── updates/
    ├── exefs/               (2.0.1a patched executables)
    └── romfs/               (2.0.1a patched data archives)

Binary FTP transfer warning: If you copy your dump from a console over FTP, set your FTP client (such as FileZilla) to Binary transfer mode (Transfer > Transfer type > Binary). Copying in ASCII/Text mode corrupts main, sdk, and subsdk0, and the launcher will halt with a text-mode warning.

Windows 10/11 installation steps

Follow these three steps to compile and run pkp.exe on a 64-bit Windows 10 or Windows 11 PC:

1. Download PokopiaRecomp-0.11.1-win64.zip (180.2 MB) from Download & SHA-256 and extract it into a plain, non-synced directory such as C:\Pokopia (avoid folders synced by OneDrive or restricted by antivirus).
2. Run PokopiaLauncher.exe. If Windows SmartScreen appears, verify the SHA-256 hash and click More info → Run anyway.
3. Select your 2.0.1a dump folder (or .nup file) and press Set up:
   • Stage 1: Code compilation (~7 minutes): lifts the four AArch64 modules and links pkp.exe on your CPU using the bundled Zig toolchain.
   • Stage 2: Shader translation (1 to 2 hours, pausable): translates the 99,012 console shaders. Tick Use fewer cores if you want to keep using your PC during the build; you can close or pause the launcher at any point and resume later without losing finished batches.
4. Press Play. Press F1 in-game to open the settings overlay, or click the middle mouse button to toggle Joy-Con 2 mouse mode for placing and breaking blocks.

Linux, SteamOS & macOS ARM64 setup

Recompia supports both Proton-backed Linux builds (v0.11.1 Stable) and native POSIX builds (v0.12.0-beta.1 Testing):

• Linux & Steam Deck (v0.11.1 Stable via Proton): install Proton Experimental in Steam (Library > Tools), extract PokopiaRecomp-0.11.1-linux-x64.tar.gz, and run ./PokopiaLauncher.AppImage (use --appimage-extract-and-run if your distro lacks FUSE). On first run it downloads ~100 MB of build tools (Python and Zig), compiles the game, and builds the shader cache through Proton. See our Steam Deck & Linux guide for Game Mode launch flags (--play).
• Native Linux (v0.12.0-beta.1 Testing, no Proton): extract PokopiaRecomp-0.12.0-beta.1-linux-x64.tar.gz on any distribution with glibc 2.35+ (Ubuntu 22.04+, Debian 12+, Fedora 36+, SteamOS 3). The launcher links a native Linux executable against libpkp_rt.so and SDL3.
• macOS ARM64 Apple Silicon (v0.12.0-beta.1 Testing): extract Recompia-0.12.0-beta.1-macos-arm64.zip (54.1 MB), launch PokopiaLauncher from inside PokopiaRecomp-0.12.0-beta.1/, allow the unsigned binary once in System Settings > Privacy & Security, and run Set up. It links a native Apple Silicon Mach-O executable against libpkp_rt.dylib, Metal (via MoltenVK), CoreAudio, and SDL3.

Importing saves from Eden or Ryujinx & multiple profiles

Already have an island started in an emulator? Open Settings in PokopiaLauncher:

• One-click emulator import: click the import button in Settings to automatically locate your Eden or Ryujinx save and copy it into Recompia. Your emulator’s original save is left untouched, and any existing Recompia save is backed up to a timestamped folder first.
• Manual folder import: point the importer at any directory containing the B00, G00, and S00 save subfolders.
• Multiple player profiles: added in v0.8.1 (#282) under Settings > Saves > Profiles. Each profile gets its own save and unique Link Play player ID while sharing the same compiled pkp.exe and 26 GB shader_cache/.

Updating from an older version

From v0.7.5 onward, click Update on the launcher’s Home tab (or under Settings > About). You can also switch between the Stable and Testing update channels there. When a release updates the code generator or adds mod hook points, the Home button shows Finish update (or Set up again): clicking it rebuilds only pkp.exe in ~4.5–7 minutes while keeping all of your saves, settings, and translated shaders intact.

Where saves, logs & shader cache live

All runtime files sit inside your chosen game folder next to PokopiaLauncher.exe and pkp.exe (launcher path preferences live in %APPDATA%\org.pkp-recomp.launcher\launcher.json on Windows):