mkw-recomp README

The project's README from github.com/adriadam10/mkw-recomp. As one markdown file: README.md.

mkw-recomp logo

mkw-recomp

Mario Kart World (Nintendo Switch 2) recompiled to run natively on Linux and Windows.

Download the latest release for Windows Download the latest release for Linux (AppImage) Download the latest release for Linux on ARM (AppImage)

Releases · Help wiki · Discord · Changelog · Contributing · Sources · Roadmap · Performance · Issues · Discussions · Archive

English · 简体中文 · Español · العربية · हिन्दी · Português (Brasil) · Português (Portugal) · Deutsch

A static recompilation of Mario Kart World (Nintendo Switch 2, versions 1.0.0 and 1.8.0) into a native PC program for Linux and Windows. It needs your own copy of the game, dumped from your own console: nothing of the game is in this repository or in its releases.

It is a recompilation, not an emulator. The game's AArch64 code is translated to C ahead of time and compiled for the PC's CPU (x86-64, or AArch64 on Linux); there is no CPU interpreter or JIT. The GPU is not emulated either: NVN2, the Switch 2 graphics API, is reimplemented on top of Vulkan at the API level, and the game's SM86 shaders are translated to SPIR-V ahead of time. Nintendo SDK functions (nn::*) are replaced by name with our own code.

Status

Early, and moving fast. On 12/11/2026:

Roadmap

The main open work, in order; the details are in docs/project/roadmap.md.

* Measured on 09/11/2026 on our test machine: Radeon 660M APU (Ryzen 5 7535HS), Linux, 720p internal resolution.

Performance

Measured frame times, each with the version it ran, are in docs/project/performance.md. To add your machine, open a performance report: it goes into the table with the version it reports. The times are the game's own frames: frame generation shows more frames but does not shorten them. 16.7 ms is 60 fps; Frame rate on Automatic (the console's) drops to 30 fps when 60 is out of reach, and a frame over 33.3 ms runs the race slower than real time.

Date GPU Internal resolution Race fps Race frame time
11/11/2026 RX 7900 XTX (Windows) 2160p 60 16.7 ms
11/11/2026 RX 9070 XT (Linux, RADV) 720p to 2160p 60 16.7 ms
10/11/2026 RTX 3060 (Windows) 1080p ~48 ~21 ms
11/11/2026 RTX 3050 Laptop (Windows) 720p ~37 26.7 ms
09/11/2026 Radeon 660M (Linux, RADV) 720p 30-32 31-33 ms
11/11/2026 GTX 1650 SUPER (Windows) 1080p ~24 ~41 ms
09/11/2026 GTX 1050 Ti (Windows) 1080p 22-24 42-45 ms

Playing

Stuck or have a question? Search the wiki first: installation, settings, controls, known errors by their log line and a FAQ.

The start screen once the game is set up

The Game files page, where the setup takes the player's dump

  1. Dump Mario Kart World 1.0.0 or 1.8.0 from your Switch 2 (exefs/ and romfs/, decrypted; 1.8.0 with the update merged into the base game's RomFS), or the same dump packed as one .nup or .nx file.
  2. Download the launcher for your system from Releases: on Linux the .AppImage (-aarch64 on ARM; the default game folder is ~/.local/share/mkw-recomp; glibc 2.31 or newer: Debian 11, Ubuntu 20.04, SteamOS and later), on Windows the .zip, unpacked into a folder. Either needs about 30 GB free.
  3. Run the AppImage (chmod +x first) or mkw.exe, open Game files, optionally use Choose game folder to select where the game will be installed (or an existing installation), then point it at your dump (Choose folder or Choose .nup or .nx file) and press Set up. The launcher remembers the installation folder; the compiled game, prepared files, saves, settings and caches live there. Selecting another folder keeps existing files in place. The first setup takes a while (it compiles the whole game and downloads NVIDIA's nvdisasm and ptxas, 84 MB on Linux and 126 MB on Windows, to describe the shader encoding on your machine); after that, Play.
  4. When a newer release is out, the start screen offers it (Update to vX): it downloads it, checks it, replaces the program and sets up again only what changed. Settings → Menu → Check for updates turns the check off.

Requirements: x86-64 CPU with AVX2 (or, on Linux, AArch64 with ARMv8.2: LSE, FP16, RCpc, DotProd, CRC32), a GPU with Vulkan 1.3 (VK_EXT_mesh_shader recommended; without it, task and mesh shaders run as compute), 16 GB of RAM recommended. In a Docker or Podman container on Linux, allow userfaultfd in its seccomp profile (Docker's default refuses it): without it the port cannot tell which game memory changed, and runs several times slower.

Extra features

Beyond the console, all optional and off (or at the console's value) by default:

Switch 2 controllers over USB on Windows

These controllers only start after a command sent to their second USB interface, which Windows leaves without a driver an app can use. Once per controller, with Zadig:

  1. Plug the controller in with a USB-C cable and open Zadig.
  2. Options → List All Devices, then pick the controller's Interface 1 (USB ID 057E and 2069 for the Pro Controller, 2066/2067 for the right/left Joy-Con, 2073 for the GameCube controller). Not Interface 0: that one is the controller's normal input, and replacing it hides the controller from every other app.
  3. Driver WinUSB, then Replace Driver (or Install Driver).

The same steps apply to a virtual controller that shows up with those USB IDs (Switch2Connect's USB/IP mode). To undo it, uninstall that interface's device in Device Manager with "delete the driver" ticked.

Mods

The start screen's Mods page installs mods as they are published for the game, and lists them in two tabs:

Mods that replace game files (romfs/: skins, textures, texts, courses) take effect at the next start. Mods that change the game's code (exefs/ .ips or .pchtxt patches, such as 200cc or 30 FPS) are built into the game code: turning one on or off rebuilds it before you play (a few minutes). Two mods that change the same archive are merged file by file, and the page asks which one wins where both change the same file. The page warns about mods that replace the game's graphics settings or shaders, which the port handles its own way.

Mods are made by other people and are not tested by this project: one can crash the game or damage your save. Read a mod's page before installing it, keep a copy of your save, and report a mod's problems to its author; when you report a bug here, say which mods were on (the log lists them), or try again without them first.

Building from source

Linux, with uv, clang, lld, ninja, SDL3, Opus, libvpx, zstd, xxHash, the Vulkan headers and VMA 3.4.0 (details in tools/build/README.md). Put your dump in game/ (game/exefs, game/romfs) or set MKW_GAME=<dir>, then from the repo root:

uv run python recomp/gen.py --exefs game/exefs --jobs 8  # --out/--patches default to the dump's version (1.8.0: build/generated-180)
uv run tools/shaders/extract.py && uv run tools/shaders/translate.py
uv run tools/build/build.py              # build/mkw; --target windows builds mkw.exe with llvm-mingw (windeps.py)
build/mkw

Shortcuts for these flows and the release ones: make build, make appimage (make help lists them all).

On Windows itself (uv, CMake and MSYS2 UCRT64's Ninja; no Linux machine, WSL or Wine): windeps.py then build.py --target windows, see tools/build/README.md. From a packed dump (.nup, .nx) and for Linux on AArch64: tools/build/README.md and its AArch64 section.

Translating the shaders needs the SM86 encoding specification, generated from NVIDIA's nvdisasm (not shipped): see tools/shaders/README.md. Everything generated goes to build/, never to git.

Folder Contents
recomp/ The generator: AArch64 → C
runtime/ What plays the console: kernel, memory, SDK replacements, NVN2 over Vulkan, audio, input, menus and launcher
sm86/ The shader translator: SM86 SASS → GLSL → SPIR-V
i18n/ The menu, start screen and setup texts in every language (gettext .po)
tools/ Analysis, setup, build, game runs and diagnostics
tests/ Tests without the game or a GPU, in the CI on Linux and Windows
docs/ Research, sources and performance
.github/ CI, issue and pull request templates

At the root: pyproject.toml and uv.lock (the Python environment of the tools), .gitignore, LICENSE, CONTRIBUTING.md, CHANGELOG.md (each release's changes, its notes), AGENTS.md (a guide for coding agents) and Makefile (shortcuts for the build flows: make help).

Design decisions (30/10/2026)

Topic Decision Why
CPU AArch64→C lifter based on totk-pc-recomp's (MIT), extended to ARMv8.1-8.3: LSE atomics, CAS, LDAPR; PAC as identity, MTE tags as 0 Same engine family as MKW, and it already scales to a large executable
System The SDK's nn::* functions replaced by name; signatures from the mangled names of main's 1 289 imports No console services to emulate
Graphics NVN2 over Vulkan: 529 of its 699 functions share their name with NVN1 (signatures known from totk-pc-recomp and nxnative); 170 are new Recompilation, not GPU emulation
Shaders Our own SM86→SPIR-V translator, offline, with a decoder generated from the DocumentSASS / nvsass-disassembler specification Covers mesh/task and what Maxwell lacks
Optional Switch 2 features HDR on by itself when the display is in HDR, as on the console (Settings > Screen > HDR: Automatic or Off); DLSS, ray tracing and touch behind options, off by default; off, their NVN2 functions exist but do nothing so the game keeps its normal path Console hardware extras, not needed to play
Defaults The console's look and resolution; lower settings are options The player chooses

How it was made

This port was written with Claude (Anthropic's coding agent) doing most of the typing, under my direction, in about ten days of full-time work: 489 commits from 30/10/2026, every one of them reviewed, measured or tested before it went in. It was not one prompt and done. Behind it:

Licenses and credits

This project is under the MIT License. Code taken from other projects keeps its own license, next to it (LICENSE.* files in recomp/, runtime/, sm86/decode/ and runtime/third_party/): totk-pc-recomp, nvsass-disassembler, Dear ImGui, bc7enc, stb_image, AMD FidelityFX FSR 1 and Roboto. Every source used, with its license and what was taken from it (code from MIT projects only; from GPL projects, ideas only), is listed in docs/project/research.md.

Mario Kart World is © Nintendo. This project is not affiliated with or endorsed by Nintendo, contains no game code or assets, and does not help to obtain them.

Mods belong to their authors and come under their own licenses. This project is not affiliated with or endorsed by GameBanana or any mod's author, does not host, review or distribute mods, and is not responsible for what a mod does: the start screen only shows GameBanana's public listing and downloads a mod from GameBanana when you ask it to.

Contributing

See CONTRIBUTING.md. Bugs and performance reports go to Issues, questions to Discussions.

mkw-recomp (adriadam10/mkw-recomp)

Searching Database…

What is this?A static recompilation of Mario Kart World (Nintendo Switch 2, version 1.0.0) into a native program for Linux and Windows. It works from your own dumped copy of the game, since nothing of the game is in the repository.
Is it an emulator?No. The game's AArch64 code is translated to C ahead of time and compiled for x86-64, and the graphics API is reimplemented on Vulkan. There is no CPU interpreter or JIT.
How do I get it running?Dump Mario Kart World 1.0.0 from your Switch 2, download the AppImage (Linux) or zip (Windows) from Releases, run it, open Game files, point it at your dump and press Prepare.
Does it need the internet to play?Only for the first setup and for update checks. Setup downloads NVIDIA's nvdisasm and ptxas, while the game itself runs from your local copy.
How fast does it run on an average GPU?Races reach about 30 fps on a Radeon 660M at 720p and less on a GTX 1050 Ti at 1080p (42-45 ms per frame). 60 fps is the goal and is not reached yet.
Why was it built with Claude, and how much of it did AI write?The author says Claude did most of the typing over about ten days (489 commits), under the author's direction. Every commit was reviewed, measured or tested before it went in.
What is the main work needed for 60 fps?Recording the Vulkan back end's big submit (about 19 ms) is on the critical path. The plan is to record with less CPU: dynamic state only when it changes, draw caches across frames, parallel recording and a faster game thread.
Will later game versions like 1.8.0 be supported?They are planned after 1.0.0. Each version is a different executable to recompile, so it needs a contributor who owns that game version (see issue #19).
Are DLSS, HDR, ray tracing and touch supported?They are designed as options that are off by default. When off, their NVN2 functions exist but do nothing, so the game keeps its normal path.
Creator
adriadam10
Size
9.6 MB
Stars
1.4K
Age
9d
Commits · 90 Days