UltraTears

UltraTears is an unofficial native PC port of The Legend of Zelda: Tears of the Kingdom (Nintendo Switch, version 1.4.3) for Windows. Steam Deck and Linux support is planned and is a high priority. It is not an emulator: the game's program code is translated ahead of time (static recompilation, ARM64 → C → x86-64), and the Switch system and its NVN graphics API are replaced by the port's own implementations on Windows and Vulkan. Shaders and textures are converted for PC graphics cards when the game is built, not while you play.

This repository contains no game code, no game assets, no Nintendo SDK code, no firmware and no keys, and it does not tell you where to get any of them. It does nothing without a copy of the game you dumped yourself from your own console. Everything made from the game (the translated code, the compiled game, shaders, textures) is made on your PC from your files and must stay there: do not share it, and do not open issues asking for it.

UltraTears is not affiliated with or endorsed by Nintendo. The Legend of Zelda and Tears of the Kingdom are trademarks of Nintendo; the name is used only to say which game this works with.

Русская версия: README.ru.md.

Early. Measured on the developer's PC (Windows 10, Ryzen, 16 threads, GeForce RTX 3060):

Known issues: hitches the first time an effect or place is seen (shader compilation); the controller layout follows the Switch (A is the right face button); no settings menu yet (window size, resolution, upscaling come later).

There is no downloadable game-filled UltraTears.exe. You download a builder, and it translates and compiles the game on your PC from your own extracted dump. There are two ways to do that:

Both methods produce the same playable folder. The Releases package already carries every build tool. The source build downloads the same tool bundle first, then performs the same game build.

• Windows 10/11 x64 and a processor with AVX2 (Intel Haswell / AMD Ryzen or newer).

• A graphics card with a current Vulkan 1.3 driver and VK_EXT_shader_object (recent NVIDIA, AMD and Intel drivers).

• 16 GB of RAM.

• About 32 GB free for the build output, plus about 16 GB for the original game dump. The original dump in the working folder is no longer needed after a successful build.

• Your own extracted copy of Tears of the Kingdom version 1.4.3 as two ordinary folders:

  game\
  ├── exefs\    main, subsdk0, sdk, main.npdm, ...
  └── romfs\    Actor\, Pack\, Shader\, ... (about 304,000 files, 16 GB)
  

  You obtain these folders yourself from your own console and copy of the game with update 1.4.3 installed. This project does not provide or point to extraction tools. .nsp, .xci, .nca and other encrypted packages do not work: UltraTears decrypts nothing and reads no keys.

Download this file from the Releases page:

UltraTears-builder-<version>-windows-x86_64.zip

Extract the entire archive into its own folder, for example:

D:\Games\UltraTears

Do not run files from inside the ZIP. After extraction, setup.bat and the deps, tools and game folders should be next to one another.

The layout should be:

D:\Games\UltraTears\
├── setup.bat
├── deps\
├── tools\
└── game\
    ├── exefs\
    └── romfs\

If the dump already lives elsewhere, you do not need to copy 16 GB: drag the folder that contains exefs and romfs onto setup.bat.

Double-click setup.bat and leave its window open. The builder runs these steps in order:

Times depend on the CPU, disk and antivirus. The build is complete only after the Done message. If the PC shuts down or the window closes, run setup.bat again; completed work is reused.

Run:

D:\Games\UltraTears\UltraTears.exe

Do not move the EXE by itself. It needs ultratears.cfg and the data folder beside it. Saves are stored in userdata; keep that folder when moving or updating the game.

Use this method when changing the code or building the newest commit. Install Git and Python 3, open PowerShell, then run:

git clone https://github.com/kuraeow/ultratears.git
cd ultratears

Put exefs and romfs in ultratears\game as shown above, then run:

python tools/setup.py

This one command performs the entire process:

1. Creates dist inside the repository.
2. Copies the current tracked source files there.
3. Downloads missing Python, Clang and the shader translator from the latest builder release.
4. Finds the dump: first in the output folder's game, then in the repository's game.
5. Builds the complete game into dist.

If the selected output folder already has its own populated game, that copy takes priority. --dump always selects the dump explicitly and removes any ambiguity.

The executable appears here:

ultratears\dist\UltraTears.exe

To build directly into another folder:

python tools/setup.py --output D:\Games\UltraTears

The original dump remains in ultratears\game, while the completed data is written to D:\Games\UltraTears\data. If the dump is elsewhere, name it explicitly:

python tools/setup.py --output D:\Games\UltraTears --dump D:\Dumps\TOTK-1.4.3

Run the same command again after changing the source: unchanged data and object files are reused. More options and implementation details are in BUILDING.md.

The original exefs and romfs are never run directly or moved. The builder reads them and creates a PC-ready copy inside the output folder:

game\exefs  ──→ data\exefs + data\generated ──→ UltraTears.exe
game\romfs  ──→ data\romfs\romfs.bin
             ├→ data\shaders
             └→ data\textures

After the Done message, the game reads only data beside UltraTears.exe. You may remove the working copies of game\exefs and game\romfs if the original dump is backed up safely elsewhere. Never delete data from the built game.

The finished folder looks roughly like this:

UltraTears\
├── UltraTears.exe      ← run this file
├── ultratears.cfg      ← paths to the data
├── data\               ← built game data; do not delete
├── userdata\           ← saves
├── build\              ← intermediate files for fast rebuilds
└── deps\               ← build tools

Keyboard: WASD moves, arrow keys move the camera, J = A, K / Space = B, I = X, U = Y, Q / E = L / R, left Alt / Shift = ZL / ZR, Enter = +, Tab / Esc = − (map), T F G H = d-pad, Z / C = stick buttons, and F11 or Alt+Enter toggles full screen. Xbox, DualSense, Switch Pro and other controllers work through SDL3. The face-button layout follows the Switch: A is the right button.

To update a Releases build, extract the new builder package over the old folder and run setup.bat again. Keep userdata to preserve saves. For a Git build, run git pull, then repeat the same python tools/setup.py command and options.

Steam Deck and Linux are not supported yet. The Windows build does not work through Proton because its memory access method is incompatible with winevulkan. A native Linux and Steam Deck version is planned and is one of the project's high-priority tasks.

• The python command is not found — install Python 3 from python.org and enable Add python.exe to PATH, or try py tools/setup.py.
• exefs\main is not the one ... 1.4.3 — the ExeFS is not from version 1.4.3.
• the RomFS is not the one ... 1.4.3 — the RomFS lacks the required update, is damaged or contains mods.
• encrypted packages are not accepted — .nsp, .xci or .nca was supplied instead of ordinary exefs and romfs folders.
• A Vulkan error or black window — update the graphics driver; Vulkan 1.3 with VK_EXT_shader_object is required.
• After correcting the cause, run the same command or setup.bat again. You do not need to repeat successful steps manually.

• Nothing of the game is in this repository or in a release: no code (also none translated from the game), no assets, shaders, textures, fonts, keys or firmware. Everything derived from the game is made on the player's PC from the player's own dump and stays there.
• UltraTears decrypts nothing and reads no keys: it takes the ExeFS and RomFS the player has already extracted.
• No Nintendo SDK code or headers are used; the system and graphics layers are the port's own implementations.
• Only the facts needed to run are in the source: addresses, hashes, short instruction replacements.
• The icon (assets/icon.ico) is the author's own drawing, not Nintendo artwork.
• UltraTears is not affiliated with or endorsed by Nintendo; you need your own purchased copy of the game.

UltraTears is free software under the GNU General Public License v3.0 or later (LICENSE). Third-party code keeps its own license: third_party/README.md; the builder package adds THIRD-PARTY-NOTICES.md and licenses\ for the tools it carries.