A native PC port of Animal Crossing: New Horizons, made by static recompilation.

ACNHRecomp turns the Switch code of Animal Crossing: New Horizons (title ID 01006F8002326000; version 3.0.2 recommended, 3.0.3, 2.0.7 and 1.0.0 supported) into native code for your computer. It is not an emulator: the game's AArch64 machine code is translated ahead of time into C++ and compiled for the host, the system services the game calls are reimplemented natively, and the game's NVN graphics calls are translated to Vulkan. It is built on the framework of SuperMarioWonderRecomp.

Whether you're playing, helping test builds across different hardware, or following the project's progress, everyone is welcome!

• 🏝️ Community & Discussion: Hang out, share your island, and discuss Animal Crossing recompilation.
• 💬 Help & Support: Get quick guidance with building and troubleshooting.
• ⚙️ Testing & Hardware: Share logs, test results across different CPUs and GPUs, and report bugs.
• 📢 Development Updates: Get real-time announcements, test builds, and sneak peeks at upcoming features.

• Community
• Features
• Status
• Disclaimer
• Requirements
• Installation
• Playing
• Settings
• Controls
• Saves
• Languages and mods
• Building from source
• Troubleshooting and FAQ
• Repository layout
• How it works
• Credits and references
• License

• Native code, no emulation. The main, sdk and subsdk0 modules are recompiled to C++ and compiled with clang; game pointers are host pointers.
• NVN to Vulkan. The game's graphics API is implemented over Vulkan; its Maxwell GPU shaders are translated offline to SPIR-V with the Ryujinx (Ryubing) shader translator.
• In-game settings screen (F1, or Minus + Plus on a controller) styled after the game, with its menu in 12 languages detected from the system.
• Resolution and display options: 1080p (TV mode) or 720p (handheld mode), AMD FSR 1 upscaling with adjustable sharpness, wider aspect ratios (16:10, 21:9, 32:9 and phone ratios), windowed or fullscreen.
• Controllers: any controller SDL3 recognises (Xbox, PlayStation, Switch Pro Controller / Joy-Con, generic pads), a Switch or Xbox/PlayStation confirm-button layout, and in-game button icons redrawn for Xbox, PlayStation or Switch. Fully remappable keyboard controls.
• Mouse and keyboard: the mouse works as the console's touch screen (window buttons, list items and dialogue choices take a click; a click while a message waits advances it), and the PC keyboard types names and messages wherever the game's text entry is open.
• Save management: import from Switch backups (JKSV, Checkpoint), from emulators (yuzu and its forks, Ryujinx/Ryubing) or from another ACNHRecomp; export in a format JKSV and Checkpoint can restore on a console; automatic backups.
• All 14 game languages, plus Brazilian Portuguese through a fan translation you install yourself, loaded as a RomFS mod (LayeredFS).
• DLC (add-on content) from your game folder's aoc/.
• Island clock follows your computer's date, time and time zone, as on the console.
• Performance work for modest hardware: presets for integrated GPUs, an option to bypass the CPU-heavy audio reverb, pipelined GPU submits, AES-NI acceleration of the game's data decryption during loads, and a shader pre-compilation pass at startup.

The project is a work in progress. Everything below was measured on Linux x86-64 with an Intel Iris Xe (Mesa) GPU; see docs/STATUS.md for the full, regularly updated log.

Known issues

• Some villagers (birds) may render with part of the head black. Starting villagers are random, so it does not always reproduce.
• 60 fps is not native yet. The game's logic advances once per frame, so presenting at 60 fps makes the whole game run twice as fast. A real 60 fps mode requires halving the step of every frame-counting system and is not done yet. Play at 30 fps.
• The first save only happens at the end of the first in-game day, and that path has not been verified end to end in a full playthrough. Back up and be prepared for surprises.
• Online play is not available: the game sees a console with no internet connection.

Platforms

ACNHRecomp is an unofficial fan project. It is not affiliated with, endorsed by or sponsored by Nintendo. Animal Crossing is a trademark of Nintendo. The project does not provide, and will not help you obtain, game files, keys or firmware, and contains no tool to decrypt or unpack them. It only works with a copy of the game you prepared yourself from hardware and software you own.

A pre-commit hook (tools/check_no_game_data.sh) refuses commits that contain game files, keys, shader binaries, recompiled game code or binary blobs. Everything derived from your dump stays in private/, which is ignored by git.

This project was built with AI: nearly all new code, tools and documentation were written by Claude (Anthropic, via Claude Code), directed and tested by a person. Its base, SuperMarioWonderRecomp, was also AI-assisted.

A folder with the game's executables and files from your own copy, laid out as an ExeFS + RomFS dump:

Version 3.0.2 (or 3.0.3) gets every fix of the port (native 60 FPS, wide screens, the mouse); 2.0.7 and 1.0.0 play with picture, sound and the mouse; any other version is built as it is (docs/VERSIONS.md). The setup links to this folder instead of copying it: keep it where it is.

Ubuntu / Debian packages:

sudo apt install build-essential clang lld cmake ninja-build patch curl python3-venv spirv-tools pkg-config \
     libvulkan-dev libsdl3-dev libvpx-dev libvorbis-dev mesa-vulkan-drivers vulkan-tools

macOS (Homebrew):

brew install llvm cmake ninja sdl3 molten-vk vulkan-loader libvpx libvorbis

libvpx and libvorbis decode the opening movie (VP9 + Vorbis). Without them the game still runs, but the movie is black.

Windows: Python 3 (winget install Python.Python.3.13) and the Visual Studio C++ build tools (winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"); the setup fetches LLVM (clang-cl) and SDL3 itself.

The setup script downloads everything else into private/third_party/: a Python virtual environment (capstone, lz4, zstandard, fonttools, cmake, ninja, unicorn), Vulkan-Headers 1.4.357, the .NET SDK 10.0.401 (unless the system has .NET 10), the Ryubing shader translator source and Dear ImGui.

The launcher is a small program, built from this repository alone, that does the whole setup with you: it asks for your game folder, checks this computer, recompiles the game and then starts it. It uses the same look as the in-game settings screen, follows the system language (12 languages, changeable at any time from the top right) and works from small laptop screens to 4K.

git clone <this repository> ACNHRecomp && cd ACNHRecomp
tools/launcher.sh            # builds the launcher the first time (cmake, a C++ compiler and SDL3), then opens it

By hand: cmake -S . -B build/launcher -DNX_GAME=acnh && cmake --build build/launcher --target acnhrecomp_launcher, then run build/launcher/acnhrecomp_launcher.

1. Welcome. Choose Set up from my game files, or I already have a recompiled build and pick its folder (an install folder made by the launcher, private/acnh, or this repository).
2. Your game. The game folder (see Requirements) and, optionally, the pt-BR translation .zip (not distributed here). Choose them, let Search find them in your usual folders, or drop them on the window. The folder is checked at once: its layout, its executables and the game version from main's build id (nothing is decrypted or unpacked).
3. Install. Where the game goes (default ~/.local/share/ACNHRecomp, ~/Library/Application Support/ACNHRecomp on macOS), and a check of this computer: compiler, Python, curl/tar, SDL3 development files, Vulkan driver, movie libraries, disk space and memory, with the command that installs what is missing.
4. Build. Runs tools/setup_acnh.py --game <game folder> --out <install folder> and follows it: stages, progress (ninja's own counter during the compile, with an estimate of the time left), the full log, Stop. If a stage fails, the page says which, keeps the log open and offers Copy log, Open logs folder and Try again (finished stages are not redone).
5. Play. Starts the game with its data folder (NX_DATA_ROOT), and the launcher closes.

On later starts the launcher opens on a home page: Play, Settings (game language including pt-BR, display, rendering, upscaling, frame rate; written to the game's config.ini), Rebuild (after updating the repository) and Change build folder. Its own settings are in launcher.ini in the user's settings folder (~/.local/share/ACNHRecomp on Linux).

Windows: the launcher runs tools/setup_acnh.py with Python as on the other systems (the Python launcher py, or python on PATH).

git clone <this repository> ACNHRecomp && cd ACNHRecomp
python3 tools/setup_acnh.py --game ~/ACNH-game          # Windows: py tools\setup_acnh.py --game C:\ACNH-game

To add DLC later, put it in the game folder's aoc/ and run the setup again. tools/setup_acnh.sh runs the same script, for scripts that call it by that name.

--out <folder> puts the game's files (import, generated code, build, logs) in that folder instead of private/acnh; start the game from such a folder with NX_DATA_ROOT=<folder> <folder>/build/acnh.

The script runs in stages and skips every stage whose output already exists. If something fails, fix it and run tools/setup_acnh.py again (once the game folder is linked, no arguments are needed).

To check your game folder: the version stage prints the version and main's build id, and the recompiler ends with unhandled 0 for each of the three modules.

macOS, the simplest way: double-click Jogar ACNH.command in the repository folder. It rebuilds whatever changed in the runtime (a few seconds; nothing when up to date) and starts the game with your settings. To get the same shortcut on the desktop, run once:

tools/install_mac_shortcut.sh

From a terminal:

tools/acnh_linux.sh              # quality: TV mode, 1080p
tools/acnh_linux.sh balanced     # 720p (handheld mode) upscaled with FSR 1
tools/acnh_linux.sh intel        # integrated GPU: 720p, pipelined submits, audio reverb off
tools/acnh_linux.sh lightest     # intel + FSR 1
tools/acnh_mac.sh                # macOS: quality | balanced (default) | performance

The environmental reverb (I3DL2) runs on the CPU, where the console has a DSP, and costs about one CPU core; the light presets bypass it. It can also be turned off on any preset from the settings screen or with NX_AUDIO_REVERB=0.

Useful environment variables (they take precedence over config.ini):

Debugging switches are listed in docs/STATUS.md and docs/upstream/nvn/SWITCHES.md.

Open the settings screen at any time with F1 on the keyboard or Minus + Plus together on a controller. It is styled after the game, scales from laptop screens to 4K (with a vertical layout on narrow windows), and its menu language follows the system: English, Brazilian Portuguese, Spanish, French, German, Italian, Dutch, Russian, Japanese, Korean, Simplified Chinese and Traditional Chinese.

Changes are written to private/acnh/config.ini, which can also be edited by hand. Settings that need a restart are marked on the screen. Environment variables set on the command line override the file.

video.preset sets the most expensive settings together. Chosen on the settings screen, it writes them (changing one of them afterwards turns the preset to custom); written by hand in config.ini, it fills in only the keys the file leaves out.

low is meant for dual/quad-core CPUs, integrated GPUs (Intel UHD/Iris, older AMD APUs, Apple M1) and 4-6 GB of RAM. Measured on an M1 (MoltenVK) in the intro's 3D scenes, GPU time per frame (timestamps per render pass, same scripted input): TV mode at 1080p 14.9 ms, handheld mode (720p) 9.4 ms, handheld mode at 540p 8.2 ms, TV mode at 540p 6.8 ms, which is why low keeps TV mode and lowers video.resolution instead. The game's CPU work per frame does not change with either (the draw replay takes 1.5-2.2 ms in all four); the reverb costs about one CPU core.

The game's logic runs once per frame, so video.frame_rate = 60 also makes it run twice as fast (see Status). For 60 fps on screen at the normal speed, keep the frame rate at 30 and use frame generation: builtin draws an in-between frame for each of the game's frames on the GPU (motion estimated between the two; about 1.5 ms on an Intel Iris Xe at 1080p) and shows it half a frame before the real one, which is the added latency. lsfg uses lsfg-vk instead, with your own copy of Lossless Scaling's Lossless.dll.

Any controller that SDL3 recognises works: Xbox, PlayStation, Switch Pro Controller and Joy-Con, and generic gamepads.

• Confirm / cancel layout: Nintendo (A on the right) or Xbox/PlayStation (confirm on the bottom).
• Button icons: the game's own on-screen button prompts are redrawn for Xbox, PlayStation or Switch, or match the connected controller automatically. The icons are generated during setup from the game's own icon font (tools/make_button_glyphs.py), so no game artwork is shipped.
• Keyboard: every key can be remapped on the Controls page.

Default keyboard layout:

As on the Switch, New Horizons keeps one island per console. The save lives in private/acnh/user/device_save/. The game writes its first save at the end of the first day.

From the Saves page you can import a save from:

• Before every import or restore, the current save is backed up to private/acnh/user/backups/. The 10 newest backups are kept, and "Back up now" makes one on demand.
• Imports are staged next to the save folder and moved in at once, so a failure never leaves a half-written save.
• After an import or restore, quit and restart the game, so it does not write the old island over the new one.
• Export writes the save to a folder (ACNH-<date>-<time>/) or a .zip in the layout that JKSV and Checkpoint restore on a console.

The game language can be any of the 14 languages the game ships with: English (US, UK), Spanish (Spain, Latin America), French (France, Canada), German, Italian, Dutch, Russian, Japanese, Korean, and Simplified and Traditional Chinese. On "Automatic" it follows the system locale.

Brazilian Portuguese is available through a community fan translation. It is not distributed with this project: it consists of modified game files, and its author asks that it not be redistributed. If you have the package, install it from your own copy:

python3 tools/setup_acnh.py --mod ptbr=~/Downloads/<translation package>.zip

Then choose "Português (Brasil)" as the game language (or leave it on Automatic on a Portuguese system). The translation replaces the European Spanish texts, so the console language becomes Spanish and the mod's files are layered on top.

RomFS mods in general work the same way (LayeredFS): --mod <name>=<zip> extracts a zip with a romfs/ folder to private/acnh/mods/<name>/romfs/. When the game opens a file, the first enabled mod that has a file at the same path wins; otherwise the original is used. Mods can only replace files that already exist in the game. Enable mods with game.mods = <name>[,<name>...] in config.ini.

tools/setup_acnh.py is the supported path. What it does, step by step:

P=private/venv/bin/python
# 1. Link the game folder, and the modules as loaded for the shader extraction
ln -s ~/ACNH-game/exefs private/acnh/exefs; mkdir -p private/acnh/extract; ln -s ~/ACNH-game/romfs private/acnh/extract/romfs
for m in main sdk subsdk0; do $P tools/nso2bin.py private/acnh/exefs/$m private/acnh/analysis/$m.bin; done
# 2. Recompile the three modules (main with the hooks of its version: tools/acnh_version.py, games/acnh/versions.txt)
$P -m recomp private/acnh/exefs/main    private/acnh/gen/main    --name main    --base 0x4000000000
$P -m recomp private/acnh/exefs/sdk     private/acnh/gen/sdk     --name sdk     --base 0x4010000000
$P -m recomp private/acnh/exefs/subsdk0 private/acnh/gen/subsdk0 --name subsdk0 --base 0x4018000000
# 3. Extract and translate the shaders
$P tools/extract_shaders.py private/acnh
dotnet private/build/spirv_harness/bin/Release/net10.0/spirv_harness.dll \
    --batch private/acnh/shaders_extracted --out private/acnh/spirv --jobs 8 --spirv-val /usr/bin/spirv-val
# 4. Button icons from the game's own icon font
$P tools/make_button_glyphs.py --romfs private/acnh/extract/romfs --out private/acnh/fonts
# 5. Build
CC=clang CXX=clang++ cmake -S . -B private/acnh/build -G Ninja -DNX_GAME=acnh -DCMAKE_BUILD_TYPE=Release \
    -DNX_VULKAN_INCLUDE=$PWD/private/third_party/Vulkan-Headers-1.4.357/include
ninja -C private/acnh/build acnh

Notes:

• The recompiler is re-run when recomp/emit.py is newer than the generated code.
• Recompiling main needs about 3 GB of RAM; compiling the generated C++ is the long step, and memory, not cores, usually limits the job count.
• Contributors: install the pre-commit hook with ln -s ../../tools/check_no_game_data.sh .git/hooks/pre-commit.
• The recompiler can be checked against Unicorn with tests/difftest.py (differential test of every instruction shape).

Reporting a bug or a crash. Settings (Plus + Minus) > About > Create problem report writes a .zip on the desktop with this session's log, the previous one (where a crash or freeze shows up), your settings and the computer's model, with no game data and your home folder's path replaced by ~. Attach it to a GitHub issue. If the game crashes before the settings screen opens, run NX_REPORT=1 private/acnh/build/acnh once after the crash.

The picture tears in full screen. Settings > Video > VSync (on by default).

Native 60 FPS at the normal game speed. Run tools/setup_60fps.sh once: it downloads tmouh's ACNH 60 FPS + SpeedFix (CC BY-NC 4.0; not part of this repository), builds its parameter file from your dump and recompiles main with it as a second version of every function it changes. Then Settings > Video > Frame rate > 60. The game's speed follows the frame rate, so it plays slower wherever the computer cannot hold 60.

The setup stops with "no game in ...: pass --game". The game folder has not been linked yet: pass --game <your game folder> on the first run.

The setup says the game folder has no exefs/ and romfs/, or that romfs/ has no Shader/ folder. Choose the folder that holds both exefs/ and romfs/ (see Requirements), with the update already applied to romfs/.

The build runs out of memory. Lower the job count, for example JOBS=4 python3 tools/setup_acnh.py.

The opening movie is black. Install libvpx and libvorbis (development packages) and rebuild.

The game runs too slowly on a laptop. Use tools/acnh_linux.sh intel or lightest, turn off the environmental reverb, and keep 720p rendering. Leave "Prepare shaders at startup" on to avoid stutter in places you have already visited.

Everything runs twice as fast. The frame rate is set to 60 fps. Set it back to 30 fps (see Status).

The window does not open on GNOME / Wayland. Some GNOME setups make libdecor/GTK abort the process; the runtime prefers X11/XWayland for that reason. Check private/acnh/nx_play.log.

Can I visit friends or use Nook Link? No. Online services answer as a console without an internet connection.

Does time pass on my island? Yes. The island follows your computer's date, time and time zone.

Where are the logs? private/acnh/nx_play.log for the game and private/acnh/logs/ for the setup stages.

Can I get a prebuilt download? No. A build contains recompiled game code, so it has to be produced from your own dump.

Still need help or ran into an unexpected bug? Join our Discord Community with your hardware details and log files (private/acnh/nx_play.log).

 your game folder (exefs/, romfs/, aoc/)
          |
          |-- ExeFS: main, sdk, subsdk0 --> recomp/ (Python + Capstone): AArch64 -> C++ ---+
          |                                                                                |--> clang --> private/acnh/build/acnh
          |-- RomFS: Maxwell shaders ----> tools/maxwell + Ryubing translator -> SPIR-V ---+
          |                                                                                |
          '-- RomFS: models, textures, audio ... read at run time               runtime/ (C++): Horizon kernel,
                                                                                 IPC/services, nn::* HLE,
                                                                                 NVN -> Vulkan, SDL3

1. Game folder. The setup links your game folder's exefs/, romfs/ and aoc/ into the data folder, reads main's build id to pick the version's hooks (games/acnh/versions.txt), and lays the three modules out as they are loaded (tools/nso2bin.py) for the shader extraction.
2. CPU. Each AArch64 function becomes a C++ function. Guest memory is host memory: the modules are mapped at fixed addresses (0x40_0000_0000 on Linux), so a game pointer is a host pointer, with no translation or byte swapping. Branches inside a function become goto, jump tables become switch, and indirect calls go through a lookup table. ACNH 3.0.2 uses SDK 20.5, so the recompiler gained new instructions (sqshl, sqrshl, uqshl, sli, sri, tbx, byte pmull, and others), each validated against Unicorn, and RELR relocations support.
3. SDK and system. The SDK module (sdk) (libc, libc++, nn::os, nn::fs, ...) is recompiled too, because main embeds its object layouts; subsdk0 (nn::movie) is the third module. The runtime acts as the dynamic loader and a minimal Horizon kernel (threads, synchronization, memory, SVCs) and replaces nn::* functions by name (HLE): file system and saves in host folders, input through SDL3, the clock from the host, audio, and a VP8/VP9 decoder (libvpx) for the opening movie in place of the console's hardware decoder.
4. Graphics. The game asks nvnBootstrapLoader for every NVN function by name; the runtime returns its own, which record command buffers and replay them in Vulkan. Shaders are translated ahead of time from Maxwell to SPIR-V with the Ryujinx/Ryubing translator, keyed by the hash of the code block. Textures are de-tiled from the block-linear layout, and ASTC/BCn are decoded.
5. Performance. Inside each recompiled function the guest's general, vector and flag registers live in C++ locals rather than in the CPU context in memory (recomp/regcache.py). They are written back only around calls, system calls and returns, and only when they may have changed. The host compiler can then keep them in machine registers instead of reloading them after every guest store. The I3DL2 reverb, the costliest guest function, runs about 2.2 times faster this way; the gain is larger on ARM64 hosts, which have as many registers as the guest. The game decrypts its data with AArch64 AES instructions while loading; on x86 they map to AES-NI when the CPU has it (the software path cost about 1000 times more). Vulkan pipelines are cached on disk and can be prepared at startup.

More detail: docs/ACNH.md (the game's modules, RomFS and shader containers), docs/STATUS.md (problems found and fixed) and docs/upstream/ (the framework).

• SuperMarioWonderRecomp (MIT): the base framework: recompiler, runtime, NVN to Vulkan and shader translation pipeline.
• Ryujinx / Ryubing (MIT): the Maxwell shader translator, used offline.
• Dear ImGui (MIT): the settings screen.
• ACNH 60 FPS + SpeedFix by tmouh (CC BY-NC 4.0): the 60 FPS game-speed rescaling, downloaded by tools/setup_60fps.sh and applied on your machine (not redistributed here).
• SDL3, Capstone, Unicorn, libvpx, libvorbis, AMD FidelityFX FSR 1.
• Projects studied before starting (summary in docs/REFERENCES.md): LASRecomp (clock, saves, shared fonts, keyboard), SwitchRecomp (HIPC/CMIF/TIPC specifications, validation) and uDPR (resumable staged setup).
• The authors of the Brazilian Portuguese fan translation, which this project supports loading but does not distribute.

ACNHRecomp is released under the MIT License. Code inherited from SuperMarioWonderRecomp keeps its original copyright notice.

This license covers the project's own source code only. It grants no rights to Animal Crossing: New Horizons, which is the property of Nintendo.