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.

README


Hookshot
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.

WhatStatus
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, build e0f3ccfa. Other versions do not work. A .nup file, a .nx file made from one (NXFormat's nxconvert pack-nup), or the romfs and exefs folders.
  • 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.

  1. Open the latest release and download HookshotBuilder.exe.
  2. Run it. It downloads the rest of Hookshot Builder (about 500 MB), checks it, and opens it.
  3. Pick your game. The builder looks for .nup and .nx files 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.
  4. Under Install the game to, keep the folder (Games\Hookshot in your user folder) or press Change. Choose the Game language.
  5. 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.
  6. 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
  1. Open the latest release and download Hookshot-<version>-x86_64.AppImage. It is Hookshot Builder with everything it needs inside.
  2. 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.
  3. Double-click it. The Hookshot Builder window opens.
  4. Under Game files, choose .nup file (a .nx file goes here too) or romfs and exefs, then press Browse to pick them. The builder checks the version.
  5. Under Save the game to, keep ~/Games/Hookshot or choose another folder. Choose a Language.
  6. Press Build. It takes about 10 to 45 minutes, depending on your CPU and memory.
  7. 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.

KeptReplaced
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 controlsimage.bin and the shader list
hookshot_env.txtlanguage.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.exe from it and start it from a terminal as HookshotBuilder.exe --tag nightly (without --tag nightly it installs the latest release instead).
  • Linux: download Hookshot-<version>-x86_64.AppImage from 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%\HookshotBuilder on Windows, ~/.cache/hookshot-builder on 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=1 for 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 user folder in the game folder on Windows, ~/.local/share/hookshot on Linux (a user folder 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-backups on Windows, ~/.local/share/hookshot/save-backups on 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 its save folder 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.com which release is the latest, and download that release's files from this repository's Releases on github.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 from github.com/NVIDIA/DLSS. The game checks for a newer release on api.github.com at start; set HOOKSHOT_NO_UPDATE_CHECK=1 to 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-0 in $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/hookshot on Linux), the saves (above), and shortcuts if you ask for them. Bug report (Gameplay tab) only writes a folder in bug-reports in 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 in hookshot_startup.log in 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
ProblemWhat 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 missingLook 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 appearedAfter 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 supportThe 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 surfacesTry 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 boundThe 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 brokenThe 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