SkyboundTotk README

The project's README from github.com/NotRexed/SkyboundTotk. As one markdown file: README.md.

SkyboundTOTK

SkyboundTOTK is an experimental Windows x64 static recompilation project for The Legend of Zelda: Tears of the Kingdom, base game version 1.0.0. It is not affiliated with Nintendo. Expect graphical problems and incomplete compatibility; a successful build does not guarantee a complete playthrough.

The project's AArch64 game code is translated ahead of time into C and compiled locally into a native executable. A runtime implements the services the game expects, and the renderer translates its graphics work and shaders for WebGPU. This is a game-specific port, not a general-purpose Switch emulator. Some graphics translation still happens at runtime.

Game files and distribution

You must supply your own legally obtained, already-extracted, unmodified 1.0.0 base-game ExeFS and RomFS. No game files, generated game code, keys, firmware or saves are included in this source project. The build does not extract NSP or XCI files, and other versions or updates are not supported by the game-specific hooks.

Keep your game files, generated code, executable package and saves private. The game/, build/ and dist/ directories are Git-ignored, but check what you are publishing rather than relying on ignore rules alone. The generated standalone package contains copyrighted game-derived data and must not be shared or committed.

Build on Windows

Requirements

Prepare and build

  1. Put the extracted files in the project's game folder. The paths must look like this, not game/exefs/exefs/main or game/romfs/romfs/Event:

    SkyboundTOTK/
  build.bat
  game/
    exefs/
      main
      main.npdm
      rtld
      sdk
      ...
    romfs/
      ActorSystem/
      Event/
      ...

  2. Open an x64 Native Tools Command Prompt, change to the SkyboundTOTK directory and run build.bat. The launcher pauses at the end so you can read any errors.

  3. The script checks the main and sdk module build IDs and a few RomFS directories, lifts the game code, compiles the native executable and copies the runtime and RomFS into dist/SkyboundTOTK/. The checks do not verify the entire RomFS or guarantee that a dump is complete.

  4. Open dist/SkyboundTOTK/SkyboundTOTK.exe to run it. No command-line arguments are needed. Keep image.bin, image.json, romfs/, wgpu_native.dll and SDL2.dll alongside the executable. The standalone folder can be moved as a unit and does not need the original game/ folder to launch.

The first lift and compile can take a long time. The builder reuses a completed lift only when its recorded game and lifter inputs match. If the lift was interrupted or those inputs change, move the existing build/ directory aside before retrying. The script refuses to overwrite a nonempty dist/SkyboundTOTK/: move the existing package aside before a new build. Copy its user/ folder into the new package if you want to retain its saves and settings. Do not delete your only save backup.

The package normally creates its own user/ directory beside the executable; it does not automatically use the saves from another installation. Native renderer pipeline cache data is kept in rxcache/ beside the executable. The executable also accepts an image path and --romfs / --user overrides for advanced use, but they are not needed for normal launching.

Build and launch troubleshooting

Controls and display features

Focus the game window before using the keys. The renderer briefly reports display settings in the window title; changes are saved in user/present.txt for the next launch.

Key Action
F6 Toggle experimental ultrawide. A window wider than 16:9 is required; see the known issue below.
F7 Toggle experimental frame interpolation.
F8 Toggle FSR 1 upscaling.
F9 Cycle FSR sharpening.
F10 Toggle aspect-preserving presentation versus stretching the image to fill the window.
F11 Toggle fullscreen/windowed mode.

FSR: The current implementation is FidelityFX Super Resolution 1, with EASU upscaling and RCAS sharpening in the presentation pass. It is enabled by default and is used when the presented frame is enlarged; otherwise the renderer uses the normal sampling path. FSR 1 is spatial upscaling, not FSR 2/3 temporal upscaling or AMD frame generation, and does not increase the game's internal render resolution. F9 cycles sharpening from sharper to softer values.

Frame interpolation: This is the project's own experimental image-based optical-flow interpolation, not AMD FSR frame generation. F7 is off by default and inserts estimated frames between real frames, normally targeting twice the displayed frame rate when the hardware can keep up. It does not make the game simulate more frames or reduce input latency; the display runs about one game frame behind. UI and fast motion can smear or distort, and long frame gaps are not interpolated.

Ultrawide: F6 attempts to adjust the camera and HUD and fill a wider window. It is off by default. A wider-than-16:9 window is needed, but a user reported that F6 stretches the image instead of providing a correctly proportioned wider view. Camera hooks are present, but their behavior in that report has not been resolved or independently verified. F10 stretching alone is not true ultrawide.

Keyboard and mouse controls are experimental. WASD moves, IJKL controls the camera, Space jumps, E is action, Shift or Q is run/cancel, F attacks, Z/R are L/R, C/V are ZL/ZR, Ctrl crouches, Enter is Plus, Tab is Minus and the arrow keys are the D-pad. Click the window to capture the mouse, Esc to release it, and use - / = to adjust sensitivity. XInput and SDL-supported controllers are also handled; buttons map by physical position.

Why WebGPU?

The renderer targets the WebGPU API and WGSL so the same general renderer and shader backend can be used by native wgpu and by browser WebGPU experiments rather than maintaining wholly separate graphics implementations. On Windows, wgpu-native translates this API to an available native backend, such as Vulkan or Direct3D 12; choosing WebGPU does not mean the desktop game runs inside a browser. It also has portability and validation tradeoffs, and translation, pipeline compilation and API overhead still require optimization. The root build.bat described here builds the Windows native package; browser functionality and packaging are not promised or validated by that launcher.

Known issues and limitations

These are reports and investigation notes, not a complete compatibility list. Some were observed in earlier TOTKPort builds rather than independently reproduced in standalone Skybound.

Issue Status Details
Shadows / shaders Reported Shadow shader problems have been reported. The standalone startup log also showed three shader-decoder assertions; their visual effect and relationship to the shadow issue are unknown.
Stretched terrain Reported Terrain can appear randomly stretched; cause and reproducibility need investigation.
Incorrect terrain textures Reported Some areas have wrong terrain textures; locations and causes need investigation.
Weapon and shield wheel background Reported The background can be black instead of blurred. An ability-wheel workaround was recorded earlier, but the weapon/shield behavior has not been verified fixed in standalone Skybound.
Ultrawide Unresolved F6 has been reported to stretch the image instead of providing a correctly proportioned wider view. The exact failure is unknown.
Zonai Portable Pot particles Workaround; retest A workaround greatly reduced disappearing-effect spikes in an earlier build, but short stray lines remained and the underlying cause is unknown. Retest in Skybound.
Depths gloom Earlier fix; retest Missing or incorrect ground gloom was reported on the path to Ganon. Earlier notes record a fix for a reproduced case; standalone Skybound and other locations need verification.
Fused-weapon inventory icons Workaround; retest Black icons were seen in earlier testing. A cache-retry workaround was recorded, but the underlying timing issue remains unexplained; retest in Skybound.
Browser new-game loading Previously reported; retest Earlier web experiments had an intermittent loading-screen hang. This is not a verified Windows-launcher issue; the root build does not package a browser release.
Browser interpolation judder Earlier fix; retest Earlier web experiments had interpolation judder; notes record a pacing fix. Browser behavior is not validated by the Windows launcher.
Performance and compatibility Ongoing limitation Frame pacing, shader warm-up and rendering vary by scene and hardware. A build and startup test are not a full-game compatibility test.

To-do

Source and licenses

NotRexed's original project code is offered under the MIT License. The required AArch64 lifting/runtime and renderer sources originated in NotRexed's Rexcomp-based TOTKPort; unrelated Rexcomp kits and applications are not included.

The whole repository and combined build are not MIT-only. The AArch64 kit includes GPL-licensed suyu/yuzu components and other third-party code under their own licenses. Their licenses and applicable GPL obligations still apply; see NOTICE.md and the individual license files. MIT does not grant rights to the game. Before publishing, verify that every contributor whose code is being offered under MIT has agreed, and review the applicable source and binary distribution obligations.

SkyboundTotk (NotRexed/SkyboundTotk)

nintendo-switch
Searching Database…

467 ·GitHub
SkyboundTotk
What is this?SkyboundTotk is an experimental Windows x64 static recompilation project that ports The Legend of Zelda: Tears of the Kingdom (base version 1.0.0) into a native Windows executable, lifting its AArch64 code to C and translating its graphics to WebGPU. It is not affiliated with Nintendo.
Is this a Switch emulator?No, it is a game-specific static recompilation port, not a general-purpose Switch emulator. The game's AArch64 code is translated ahead of time into C and compiled into a native executable, with a runtime emulating the Switch services the game expects and a renderer translating its graphics to WebGPU.
How do I build and run it?Place your own extracted exefs/romfs game files in the project's game/ folder, open an x64 Native Tools Command Prompt, run build.bat from the SkyboundTOTK directory, then launch dist/SkyboundTOTK/SkyboundTOTK.exe once the build finishes.
What do I need installed before building?You need Windows 10/11 x64 with a GPU/driver supported by wgpu-native, 45+ GB free disk space, Python 3.10+ with the lz4 package, Visual Studio 2022 Build Tools (MSVC + Windows SDK), and Clang/clang++/lld (with EMSDK set if those LLVM tools aren't already on PATH).
Does a successful build mean the game actually plays correctly?No, a completed build doesn't guarantee a full playthrough. The known-issues list includes shader-decoder assertions, stretched or incorrect terrain textures, black UI icon backgrounds and other unresolved graphical problems.
Do I need to provide my own game dump?Yes, you must supply your own legally obtained, unmodified, already-extracted 1.0.0 ExeFS/RomFS. No game files, keys, firmware or saves are included, and the resulting package with game-derived data must be kept private, never shared or committed.
What graphics backend does it use and why WebGPU?It targets the WebGPU API and WGSL so the same renderer and shaders can run via native wgpu-native (translated to Vulkan or Direct3D 12 on Windows) or in browser WebGPU experiments, avoiding separate graphics implementations.
Does it support upscaling or frame generation?It ships FidelityFX Super Resolution 1 spatial upscaling (EASU+RCAS, toggle F8/cycle sharpening F9) and its own experimental optical-flow frame interpolation (toggle F7); neither is AMD's FSR2/3 or true frame generation, and interpolation adds about one frame of display latency.
Will it work with other versions of the game?No, only the 1.0.0 base game is supported today; adding support for other TOTK versions is listed as a project to-do.
Can I use a gamepad instead of keyboard and mouse?Yes, XInput and SDL-supported controllers are handled with buttons mapped by physical position, alongside an experimental keyboard/mouse scheme (WASD movement, IJKL camera, etc.).
What are similar projects?BLACK-XBERecomp, LostOdysseyRecomp, dlssg_for_sm86, TheSimpsonsGameRecomp, hells-gate-recomp, gt4-staticrecomp, dlss5-bridge, gravityrush_pc
Which topics is it in?nintendo-switch, recompilation, wgsl, frame-interpolation, sdl2, directx12, aarch64, decompilation, webgpu, upscaling, emulation, gpl
Creator
NotRexed
Size
5.5 MB
Stars
467
Updated
CommitOct 31
Age
5d
Commits · 90 Days