ACNHRecomp

ACNHRecomp

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.

Community

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.

Contents

• 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

Features

• 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. Party Play on macOS and Linux: up to four controllers, one per player, joining as on the console (the first to press a button is player 1).
• 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.

Status

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.

Area	State
CPU recompilation (main, sdk, subsdk0)	Working: about 19 million instructions, 0 unhandled
Shaders (Maxwell to SPIR-V)	Working: 6,200+ distinct blocks, 0 invalid
Boot, system services, audio, clock, input	Working
Opening: Nook Inc. counter scene in 3D, character creation	Working
Opening movie (VP9 + Vorbis), arrival on the island	Working
Free roaming on the island	Working, 30 fps on an Intel Iris Xe
First save (written at the end of the first day)	Not yet verified in a full playthrough
60 fps	Not native yet (see below)
Online features (visits, Nook Link, Dream Suite)	Unavailable

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

Platform	State
Linux x86-64	Tested (Ubuntu, clang 21, Intel Iris Xe / Mesa ANV)
macOS (Apple Silicon, MoltenVK)	Tested (M1, macOS 26/27, Homebrew's MoltenVK)
Windows x86-64	Builds with tools/setup_acnh.py (clang-cl, SDL3); the launcher is in the releases. Contributed by a fork, not fully tested here
Android (Snapdragon, Turnip)	Tested (Galaxy S20 FE / Snapdragon 865: a steady 30 fps drawn at 900 rows and upscaled with FSR 1 to the screen, battery under ~41 °C after 20 minutes; frame generation optional). The app holds no game and is in the releases; it asks for the game folder your computer prepares from your own game, see docs/ANDROID.md

Disclaimer

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.

Requirements

Your game folder

A folder prepared by ACNHRecomp-Importer from your own copy of the game.

ACNHRecomp only accepts game folders made by ACNHRecomp-Importer. The launcher and tools/setup_acnh.py refuse any other folder, including an ExeFS + RomFS dump extracted with other tools. ACNHRecomp-Importer is a separate companion app (Windows, macOS, Linux and Android) that turns your NSP or XCI, its update and your console's keys into this folder, and recompiles the game's code on the way. It is available on our Discord: discord.gg/VJW9Dtdu7a. Get it there, prepare your own copy with it, and point the launcher (or tools/setup_acnh.py --game) at the folder it writes.

The folder's layout:

Path	Contents	Required
exefs/	main, sdk, subsdk0 (the game's executables, NSO) and main.npdm	Yes
romfs/	The game's files, with the update applied (about 10.5 GB). extract/romfs/ is accepted too	Yes
aoc/<index>/	Add-on content (DLC), one folder per add-on	Optional
game.ini, .import/	What ACNHRecomp-Importer imported (title, update version, main's build id) and its record of a finished import: how the launcher and the setup recognise its folders	Yes
gen/	The game's code recompiled to C++ by the importer. When it was made by the same recompiler as this repository's recomp/, the setup uses it instead of recompiling	Optional

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.

Computer

	Linux (x86-64)	macOS (Apple Silicon, untested)
Compiler	clang 18 or newer (tested with 21)	Xcode command line tools / Homebrew LLVM
GPU	Vulkan 1.3 (tested: Intel Iris Xe, Mesa ANV)	MoltenVK
RAM	16 GB (32 GB recommended to compile with more jobs)	16 GB
Disk	About 30 GB free (10.5 GB RomFS, 1.6 GB generated C++, object files)	Same

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.

Installation

Downloads

The releases are ready to play: none of them has any part of the game, and none needs a compiler. You need two things:

1. Your game folder, made by ACNHRecomp-Importer (on our Discord) from your own copy of the game. Run it once and keep the folder it writes.
2. The package for your system from the latest release:

File	System
ACNHRecomp-<version>-windows-x64.zip	Windows 10/11, x64
ACNHRecomp-<version>-macOS-arm64.zip	macOS 14 or newer, Apple Silicon (M1 or newer)
ACNHRecomp-<version>-linux-x64.tar.gz	Linux x86-64, glibc 2.35+ (Ubuntu 22.04, Fedora 36, Debian 12 and newer)
ACNHRecomp-<version>-android.apk	Android 10+, Snapdragon (Adreno 6xx or newer): see docs/ANDROID.md
libvulkan_freedreno.so	The Turnip Vulkan driver (Mesa, MIT), already inside the APK; for tools/android_install.sh

Windows

1. Unzip ACNHRecomp-<version>-windows-x64.zip into a folder of your own (for example Documents\ACNHRecomp), not inside the zip viewer.
2. Double-click ACNHRecomp Launcher.exe (or Start ACNHRecomp.bat). If SmartScreen warns about an unknown app: More info > Run anyway.
3. Choose your game folder. The game starts.
4. On the launcher's home page, Add to desktop puts a shortcut with the ACNHRecomp icon on the desktop and in the Start menu (search for "ACNHRecomp"). Keep the unzipped folder where it is: the shortcut points into it.

macOS

1. Unzip ACNHRecomp-<version>-macOS-arm64.zip. It holds ACNHRecomp.app and Start ACNHRecomp.command.
2. The first time, double-click Start ACNHRecomp.command: the app is not signed by Apple, and this lets macOS open it (it removes the download quarantine) and then opens it. If macOS still refuses, right-click ACNHRecomp.app > Open > Open, or System Settings > Privacy & Security > Open Anyway.
3. Choose your game folder. The game starts.
4. On the launcher's home page, Install in Applications copies ACNHRecomp.app into Applications (or ~/Applications without administrator rights) and puts it on the desktop. From then on open it from Launchpad, Spotlight or the Dock like any app; the downloaded folder can be deleted.

Linux

1. Extract the package: tar -xzf ACNHRecomp-<version>-linux-x64.tar.gz.
2. Run ./Start ACNHRecomp.sh in the ACNHRecomp folder (or double-click it in your file manager). You need a Vulkan driver: sudo apt install mesa-vulkan-drivers (or your distribution's, or NVIDIA's).
3. Choose your game folder. The game starts.
4. On the launcher's home page, Add to desktop adds ACNHRecomp, with its icon, to the applications menu and to the desktop (~/.local/share/applications/io.github.acnhrecomp.desktop). Keep the extracted folder where it is.

The first start, updates and versions

• Brazilian Portuguese and 60 FPS come with the package: the first start copies the pt-BR fan translation and the files of tmouh's 60 FPS SpeedFix into your game folder (no download). Português (Brasil) is then in the game's languages (chosen by itself on a Portuguese system), and the game runs at 60 FPS at its normal speed unless you pick 30. A game folder whose code was prepared without the SpeedFix stays at 30. A new package with newer files copies them again; game.mod_fetch = off in config.ini turns the copy off.
• New versions: the launcher looks for a newer release on GitHub each time it opens and says so on its home page, with a button to its download page. Settings > Look for new versions when the launcher opens turns it off. To update, download the new package and replace the old folder (or app): your game folder, saves and settings are not in it, so nothing is lost.
• The version in use is at the bottom of the launcher's Settings, and in the game's settings (F1) > About.
• The icon: the launcher, the game's window, the taskbar / Dock and the shortcuts all show the ACNHRecomp icon.

The launcher asks for one thing, the game folder ACNHRecomp-Importer wrote, and starts the game; the player beside it (acnh) loads the game's code from that folder (game/<platform>/, see Building from source). Each package carries what it needs (SDL3, and on macOS the Vulkan loader and MoltenVK); a GPU with a Vulkan 1.3 driver is the one requirement. The packages are made by the repository's Build workflow (.github/workflows/build.yml, tools/package_release_*.sh; the icons are in assets/).

The sections below are for building from this repository instead (developers, other versions of the game).

From the repository, with the launcher

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

On macOS, double-clicking Jogar ACNH.command does the same (and, once the game is set up, starts it).

The short way. The first time, the launcher opens straight on the system's folder dialog: pick your game folder, and if this computer has what it needs the setup runs by itself and the game starts when it is done (a pt-BR .zip in Downloads is taken along). The pages below only show up when something is missing or fails, or when the dialog is closed. Later the launcher starts the game after a 3-second countdown; a click or a key keeps it open on its home page (launcher.autostart = 0 in launcher.ini: no countdown).

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).

From the command line

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/