adriadam10/mkw-recomp

What it is

mkw-recomp translates the AArch64 code of Mario Kart World (Nintendo Switch 2, version 1.0.0) into C ahead of time and compiles it for x86-64. It is a recompilation, not an emulator: there is no CPU interpreter or JIT. The Switch 2 graphics API, NVN2, is reimplemented on top of Vulkan, and the game's SM86 shaders are translated offline to SPIR-V. Nintendo SDK functions are replaced by name with the project's own implementations.

The repository ships no game code or assets. You must dump your own copy from your own console. The launcher builds the game on your machine during first setup, which includes downloading NVIDIA's nvdisasm and ptxas to describe shader encoding locally.

It targets players who own the game and want to run it natively on Linux or Windows, and developers interested in static recompilation techniques.

Quick start

Preparation: dump Mario Kart World 1.0.0 from your Switch 2 (exefs/ and romfs/, decrypted). You need about 30 GB of free space, an x86-64 CPU with AVX2, a GPU with Vulkan 1.3 (VK_EXT_mesh_shader recommended), and 16 GB of RAM recommended.

1. Download the launcher for your system from Releases: the .AppImage on Linux (requires glibc 2.31 or newer, e.g. Debian 11, Ubuntu 20.04, SteamOS) or the Windows .zip, unpacked into a folder.
2. On Linux, run chmod +x on the AppImage, then launch it; on Windows, run mkw.exe.
3. Open Game files, point it at your dump, and press Prepare. The first setup compiles the whole game and downloads the shader tools (84 MB on Linux, 126 MB on Windows); later launches go straight to Play.

On Linux the game built by the launcher lives in ~/.local/share/mkw-recomp.

Building from source

Linux is the supported build environment, using uv, clang, lld, ninja, SDL3, Opus, libvpx, zstd, xxHash, Vulkan headers and VMA 3.4.0; see the build instructions for details. Place your dump in game/ (game/exefs, game/romfs) or set MKW_GAME=<dir>, then run from the repo root:

uv run python recomp/gen.py --exefs game/exefs --out build/generated --jobs 8 --patches recomp/patches-mkw.txt
uv run tools/shaders/extract.py && uv run tools/shaders/translate.py
uv run tools/build/build.py
build/mkw

Pass --target windows to tools/build/build.py to build mkw.exe with llvm-mingw. Shader translation needs the SM86 encoding specification generated from nvdisasm, which is not shipped; see the shader tooling notes. All generated output goes to build/.

Current limitations

This is an early build. It boots, plays intro movies, menus and races on both platforms, but mode, character and vehicle select menus still need work. The kart shadow occasionally misses a frame, some audio cuts during movies, and some AMD drivers can cause GPU hangs. Online play is not available. Races run at 31-33 ms per frame on a Radeon 660M at 720p and 42-45 ms on a GTX 1050 Ti at 1080p, measured on 09/11/2026. The Automatic frame rate setting currently flips between 60 and 30 and runs races in slow motion below 60 fps, so set Settings > Screen > Frame rate > 30 in that case. 60 fps is the stated goal of the roadmap.

Code is MIT-licensed, while third-party components keep their own licenses alongside it. The project is not affiliated with Nintendo and contains no game assets.

HotRepo's take

The project entered HotRepo's new-project list on 2026-11-09, its first day of records, with 104 stars and 3 forks gained in a roughly 6.5-hour window. It has no best-rank record on the all-language daily list yet. What stands out is the stated method: about ten days of full-time work, 489 reviewed commits, performance changes measured with A/B runs, rendering fixes checked against console images, and shader translator changes tested on all 11,561 of the game's shader programs before a game run. The README also documents real limitations and per-GPU frame times, which gives a concrete frame of reference for what "it runs" means at this stage.

HotRepo 点评

该项目在 2026-11-09 首次进入 HotRepo 新项目榜记录，约 6.5 小时新增 104 Star、3 Fork，目前还没有全语言日榜名次记录。更值得关注的是 README 披露的工程方法：约十天全职投入、489 次经审查的提交、性能改动用同一次运行内的 A/B 对比测量、渲染修复对照主机画面核验、着色器翻译器改动在全部 11,561 个程序上先在离线环境测试。README 也如实列出当前限制和各 GPU 的帧时间，读者可以据此判断这个早期版本实际能跑到什么程度。