- Автор
- adriadam10
- Размер
- 9.6 MB
- Звёзды
- 1.4K
- Обновлён
- КоммитNov 17Релизv0.1.13Nov 16
- Возраст
- 9 д
- Коммиты · 90 дней
README проекта с github.com/adriadam10/mkw-recomp. Одним файлом markdown: README.md.
Mario Kart World (Nintendo Switch 2) recompiled to run natively on Linux and Windows.
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.
Early, and moving fast. On 12/11/2026:
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.
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 |
Stuck or have a question? Search the wiki first: installation, settings, controls, known errors by their log line and a FAQ.


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..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.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.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.
Beyond the console, all optional and off (or at the console's value) by default:
gamecontrollerdb.txt (SDL's format) in the game
folder..nup or .nx file, used where it is;
updates from the start screen.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:
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.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.
The start screen's Mods page installs mods as they are published for the game, and lists them in two tabs:
.zip, .rar or .7z, with romfs/ and/or exefs/ anywhere inside, including the atmosphere/contents/ layout).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.
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).
| 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 |
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:
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.
See CONTRIBUTING.md. Bugs and performance reports go to Issues, questions to Discussions.