Hookshot
Hookshot is a native Windows port of The Legend of Zelda: Ocarina of Time with an in-game menu for frame generation and resolution scaling.
- Type: PC port
- Game: The Legend of Zelda: Ocarina of Time
- Runs on Windows and Linux
- By Hookshot
- Latest release v2.3.2, 2026-11-15
- Source: https://git.notrexed.dev/Hookshot/Hookshot
README
Hookshot
The Legend of Zelda: Ocarina of Time (Nintendo Switch 2) running natively on Windows & Linux, with no emulator.
Status | Install and play | In-game menu | Problems | Build from source | How it works | Want to help? | Credits | License
Documentation · Common issues and answers · Report a bug
Hookshot is a static recompilation. The game's code is translated to C and compiled into a Windows or Linux program,
the console's system software is reimplemented, and the Switch 2 graphics are rebuilt on Vulkan. All of this happens
on your PC, from your own copy of the game.
Warning
Some users report the file in releases to be a Trojan - it is not. Feel free to run it through any antivirus software
Discord: https://discord.gg/rexed
Important
This repository does not contain the game, keys or an executable, and it does not explain how to get them. You
need your own copy. Everything the build creates (hookshot.exe, the generated code, the shader caches and your
saves) comes from your game and stays on your PC. Never share those files.
Project status
Experimental. Players have reported on many PCs, from Kokiri Forest to the dungeons: the table says what works and what does not yet. Open problems are collected in tracking issues, linked below.
| What | Status |
|---|---|
| Kokiri Forest: reaching gameplay and walking around | ✅ Works |
| Sound, controller, keyboard and saves | ✅ Works |
| In-game menu, frame generation and upscaling | ✅ Works |
| Flicker (the picture flashing too bright while moving) | ✅ Fixed in v2.0.2 (#645) |
| Ground fog vanishing when looking down | ✅ Fixed in v2.0.2 (#638) |
| Models with missing pieces (doors, fences, parts of trees) | ✅ Fixed where tested, more play needed |
| Stutter when entering new areas | ⚠️ Still happens the first time you visit a place. The next visits are smooth |
| Performance | ⚠️ Depends on the PC: some reach a steady 60 fps, others stay below it, more so in Hyrule Field |
| Hyrule Field, Castle Town, Kakariko and the dungeons | ⚠️ Players got there, with open bugs: lighting and shadows (#1004), crashes and freezes (#2507) |
| Ultrawide and 4:3 | ✅ Works. The Aspect ratio row's default, Monitor's shape, widens the 3D to the screen (#2119); the HUD keeps its 16:9 size with its corners at the screen's edges, or in the middle 16:9 with the HUD layout row; movies stay in the middle 16:9 |
| NVIDIA cards | ✅ Works. The most tested |
| AMD cards | ⚠️ Many tested: reports from the RX 6600, RX 6800 XT, RX 7800 XT, RX 7900 XTX and RX 9070 XT. On Windows, the RX 6000 cards (Navi 21 and 22) draw task and mesh shaders through the compute fallback by default, as the driver lost the GPU with them (#1747, #1992, #2215). Driver crashes and device lost are still reported (#996) |
| Intel cards | ❓ Few reports, many of them black screens or crashes (#999) |
| Cards without mesh shaders (such as AMD RX 5000 and older) | ❌ Not supported: parts of the picture are missing. Since v2.0.6 a fallback runs the mesh programs as compute shaders on cards with buffer device addresses (#640); it leaves out the mesh draws that take their count from a buffer |
| Linux | ✅ Works with the AppImage. Tested on several distributions (CachyOS, Fedora, Bazzite, SteamOS) and cards, with open problems on some AMD cards (#1000) |
Install and play
The game does not come ready-made: Hookshot Builder builds it on your PC from your copy. You do this once. After that you start the game from its launcher, which also updates it.
What you need
- Your copy of the game at the supported version: program
0400486024DEC000, update v131072, builde0f3ccfa. Other versions do not work. A.nupfile, a.nxfile made from one (NXFormat'snxconvert pack-nup), or theromfsandexefsfolders. - 64-bit Windows 10 or 11, or 64-bit Linux with glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora, Arch, SteamOS ...) and a CPU with AVX2. The Linux AppImage needs AVX2; on Windows, and in a build from source, a CPU without it gets a game built for what it has, a little slower.
- A graphics card with Vulkan 1.3 and mesh shaders, with an up-to-date driver: NVIDIA GeForce RTX 20 series or newer, AMD Radeon RX 6000 series or newer, or Intel Arc. On Linux, Mesa or NVIDIA's driver. Cards without mesh shaders are not supported.
- 8 GB of video memory (VRAM) or more is recommended. Cards with less can use the in-game menu's lower Quality presets.
- 16 GB of RAM or more. A run uses about 10 GB.
- About 60 GB free while building, on an SSD if you can: a hard drive makes the build much slower. You can build on one anyway; the builder says so first.
- An internet connection for the download. Nothing else to install: the builder brings its own compiler and tools.
On Windows
For a portable install on an external SSD, run the downloaded setup with --portable; see
Portable Hookshot Builder for folder, move and repair behavior.
- Open the latest release and download
HookshotBuilder.exe. - Run it. It downloads the rest of Hookshot Builder (about 500 MB), checks it, and opens it.
- Pick your game. The builder looks for
.nupand.nxfiles in your Downloads, Desktop and Documents folders and lists them under Found on this PC. Not listed? Press Browse…, drop the file on the window, or choose romfs and exefs folders. The builder checks that it is the right version. - Under Install the game to, keep the folder (
Games\Hookshotin your user folder) or press Change. Choose the Game language. - Press Build the game. It takes about 10 to 45 minutes, depending on your CPU and memory. You can use your PC in the meantime.
- When it says Your game is ready, press Play. The Desktop shortcut and Start menu entry boxes are ticked: untick them if you don't want them.
Next time, start the game from the Hookshot shortcut, or hookshot.exe in the game folder. That is the launcher: it
has Play, and Update when a newer release is out.
The first start prepares the game's shaders, which takes a while. Later starts are faster.
On Linux
- Open the latest release and download
Hookshot-<version>-x86_64.AppImage. It is Hookshot Builder with everything it needs inside. - Allow it to run as a program. In most file managers: right-click it, open Properties, and turn on
"Allow executing file as program" (the words differ between desktops). Or in a terminal:
chmod +x Hookshot-*-x86_64.AppImage. - Double-click it. The Hookshot Builder window opens.
- Under Game files, choose .nup file (a
.nxfile goes here too) or romfs and exefs, then press Browse to pick them. The builder checks the version. - Under Save the game to, keep
~/Games/Hookshotor choose another folder. Choose a Language. - Press Build. It takes about 10 to 45 minutes, depending on your CPU and memory.
- When it says "Your game is ready", press Play.
The game is also added to your applications menu as "Hookshot". That entry, and hookshot in the game folder, open the
launcher: Play, and Update when a newer release is out. Keep the AppImage where it is: the launcher uses it to
update.
When the desktop gives the launcher its own systemd service, Play waits up to two seconds for the game's
separate scope before closing the window. If that hand-off fails, it cancels that attempt before starting the
game directly, and records the fallback in hookshot_startup.log after the game exits. A direct start still
follows the desktop's original service lifetime; this fallback cannot bypass a desktop that stops its children.
The same AppImage also builds and starts the game without opening the window, for a machine you reach over SSH or for a script: see Linux, the AppImage from the command line.
For fast GPU memory imports on Linux, the game user needs read/write access to /dev/udmabuf (the kernel's
udmabuf module). Without it, Hookshot falls back to host-pointer imports, which can be much slower on AMD/RADV
(NVIDIA's driver refuses these dma-bufs, so on NVIDIA the game uses host-pointer imports, which are not slow there);
permission errors produce a warning on stderr and in hookshot_log.txt. With an NVIDIA card on NVIDIA's own driver
you do not need this access and can ignore that warning: the check runs at the start, before the game knows which
GPU it has. Otherwise, check ls -l /dev/udmabuf and id.
An administrator can add you to the device's owning group, then you must log out and back in. Only use that group
if access to its other devices is intended: kvm also grants virtualization access. For an active local desktop
session using systemd-logind, prefer a device-specific rule in /etc/udev/rules.d/70-hookshot-udmabuf.rules:
SUBSYSTEM=="misc", KERNEL=="udmabuf", TAG+="uaccess" (before 73-seat-late.rules). This grants access to the active
local user, not SSH or service users. For those, an administrator can instead create a dedicated udmabuf group,
add only the game user, and use SUBSYSTEM=="misc", KERNEL=="udmabuf", GROUP="udmabuf", MODE="0660" in that file.
Reload with sudo udevadm control --reload-rules and apply with
sudo udevadm trigger --action=add /sys/class/misc/udmabuf; restart the session/service after a group change.
If the device is absent, the distribution must provide/load the module first (sudo modprobe udmabuf).
Do not run the game as root or make the device world-writable.
Updating
When a new release is out, the launcher says "Update available". Press Update: in hookshot.exe on Windows, or in
hookshot (or the AppImage) on Linux. It downloads only the parts that changed and builds the game again in the same
folder. The build files of the last build are gone by then (see Where the files go), so an
update takes about as long as the first build. Your saves and settings are kept. What changed is on the
Releases page.
What an update keeps and replaces, and updating from the command line
To be safe, copy your saves somewhere first: the user folder in the game folder on Windows, or
~/.local/share/hookshot on Linux.
| Kept | Replaced |
|---|---|
Your saves (user, or ~/.local/share/hookshot on Linux) | The game in bin and its files |
hookshot_options.ini, the in-game menu's choices and your controls | image.bin and the shader list |
hookshot_env.txt | language.txt, written again with the game's language |
texts: the texts reworded for a PC, made again | |
mods | |
mods, and hookshot_mods.txt (the Mods tab's order and switches) | exefs_patches.txt, written again with the ExeFS patches the build applied |
The game files the first build read are kept in the game folder, so an update does not need your .nup again.
From a clone: git pull, then python -I nx2/make_game.py --update <game folder>. The Linux AppImage does the same
with --update <game folder>.
Latest development build
Want a fix before it is in a release? The
latest development build is made from main after every
change, with the same files as a release. It is untested and may break your saves or settings: copy them first (see
above).
- Windows: download
HookshotBuilder.exefrom it and start it from a terminal asHookshotBuilder.exe --tag nightly(without--tag nightlyit installs the latest release instead). - Linux: download
Hookshot-<version>-x86_64.AppImagefrom it and use it as above.
To go back, install the latest release the usual way.
Where the files go
- The build reads your game and never changes it. It writes to the folder you choose and to the builder's own folder:
%LOCALAPPDATA%\HookshotBuilderon Windows,~/.cache/hookshot-builderon Linux. - The romfs is hard-linked instead of copied where the disk allows it.
- The build files (about 4 GB: the translated code and the compiled objects) are deleted once the game is ready. None
of them are needed to play. To keep them, so that an update compiles only what changed, set the environment variable
HOOKSHOT_KEEP_BUILD_FILES=1for the builder; on Windows, Free up space on the "Your game is ready" page then deletes them when you want. The build files folder can be moved before a build (Change, Default). - Saves: the
userfolder in the game folder on Windows,~/.local/share/hookshoton Linux (auserfolder from an earlier Linux build is moved there once).--user <folder>puts them somewhere else (command line arguments). The game also backs your saves up outside the game folder, at each start and after it saves (the last 20, in%LOCALAPPDATA%\Hookshot\save-backupson Windows,~/.local/share/hookshot/save-backupson Linux). A game folder with no saves, such as a new install or one built again into another folder, gets the newest backup back at its first start; a folder that has saves is never touched. To go back to an older backup, copy itssavefolder over the game's own. To carry on with a save from an emulator (Lichii, Eglantine, Orchid, ...) or another PC port, or to take yours there, see using a save from an emulator. - To uninstall, delete the game folder, the builder's folder and the shortcuts.
What Hookshot connects to
Hookshot uploads nothing about you or your PC. It reads no browser data, passwords or session keys. Everything it does on the network or with other programs:
- Downloads from GitHub only. The builder and the updater ask
api.github.comwhich release is the latest, and download that release's files from this repository's Releases ongithub.com(the setup lists, the build parts, the Linux AppImage parts and the shared pipeline list). With DLSS ticked in the builder, NVIDIA's DLSS library comes fromgithub.com/NVIDIA/DLSS. The game checks for a newer release onapi.github.comat start; setHOOKSHOT_NO_UPDATE_CHECK=1to turn that off. - Your Discord status, through the Discord app on this PC. While Discord runs, the game shows "Playing Hookshot" with
the time played. It does this the way every game does: through the Discord app's own local connection, a named pipe on
Windows and the socket
discord-ipc-0in$XDG_RUNTIME_DIR(or$TMPDIR, or/tmp) on Linux. What it sends is "Ocarina of Time", the Hookshot version, the start time and the icon's name. The Discord app then shows it through Discord's servers. Turn it off with Gameplay → Discord status in the Insert menu. - Files it writes outside the game folder: the builder's own folder (above), its settings (
~/.config/hookshoton Linux), the saves (above), and shortcuts if you ask for them. Bug report (Gameplay tab) only writes a folder inbug-reportsin the game folder, with your home folder and user name taken out of its logs, and Save my pipeline list only saves a zip in your Downloads folder: you choose whether to attach them anywhere. - On Linux the game starts through a small script (
play-diagnostics.sh). It keeps the game's first error messages inhookshot_startup.login the game folder, using a private temporary folder there that it removes when the game exits.
Only download Hookshot from this repository's Releases. Each release
lists its files' checksums in SHA256SUMS. A copy from anywhere else may not be ours.
If something goes wrong
| Problem | What to do |
|---|---|
| Where is the log? | hookshot_log.txt in the game folder holds the last run. The four runs before are hookshot_log.1.txt (the last) to .4.txt. Started from a terminal, the game prints there instead. Every 600 frames it has a vk: status: line: the video memory in use of what the driver allows, and DLSS's details while it draws; vk: over the driver's video-memory allowance says when the game passed it |
| A place has a wrong texture, or a floor or wall is missing | Look for hookshot_damaged_files.txt in the game folder. The build writes it when your game dump is incomplete (about 23.3 GB, a complete one is about 23.8 GB): it lists each damaged game file and the file put in its place. Dump the game again and build from the new dump; the file is then removed |
| Linux Builder Play closed before the game log appeared | After the game exits, check hookshot_startup.log in the game folder for up to 64 KiB of startup stderr and its exit status. |
| "Hookshot supports build e0f3ccfa" or "This version isn't supported" | Check that you chose the right game with its update installed |
| The game opens and closes, or the log says "device lost" | Update your graphics driver. On AMD cards there are known crashes (#708, #614) |
| Parts of the picture are missing, or a message says your card has no mesh shader support | The card or its driver has no mesh shaders. Update the driver; older cards are not supported (#640) |
| AMD: blocky textures, solid rectangles in the sky or unusually dark courtyard surfaces | Try the RGBA8 texture workaround. It uses more graphics memory |
Linux, AMD: grass and small plants flicker in and out, and the log says not imported (VkResult -13) and storage buffer NOT bound | The kernel's udmabuf limit (64 MB) is smaller than some of the game's memory pools. Builds with the sparse-queue fix import those through the driver's sparse queue. On older builds, or if the log still says CANNOT be imported, close the game and run echo 2048 | sudo tee /sys/module/udmabuf/parameters/size_limit_mb, then start it again. The setting lasts until a restart of the PC; a line w /sys/module/udmabuf/parameters/size_limit_mb - - - - 2048 in /etc/tmpfiles.d/udmabuf.conf sets it at every start |
| Linux: the game does not start or the picture is broken | The game needs a Vulkan 1.3 driver with mesh shaders. Check with vulkaninfo | grep mesh: it should list VK_EXT_mesh_shader. Update Mesa or the NVIDIA driver |
Steam Deck: the game freezes and closes in Kokiri Forest or the Great Deku Tree (gfx_0.0.0 timeout in journalctl -k) | RX_VK_MESH_NOCULL=2c56dc1006942f74 in hookshot_env.txt gets past it with every model drawn (the culling pass that runs for seconds is turned off). RX_VK_SKIP_CODE=2c56dc1006942f74 also gets pas |