mirror of https://github.com/tangerineturtle1/NX2navi.git synced 2026-11-15 19:19:58 -04:00

Files

Claude c403547c8b Add the NX2navi launcher: a one-click setup that builds the game from the player's dump, starts it and keeps it up to date.

NX2navi-Setup.exe installs the launcher into %LOCALAPPDATA%\Programs\NX2navi without administrator rights, with
shortcuts and an Apps entry. The launcher finds the player's .nup, downloads the build tools itself (the MSYS2 UCRT64
packages toolchain.lock.json pins, checked by sha256 and unpacked without pacman, and zbic from PyPI) and runs
tools/make_game.py, whose steps it shows with their progress. Its window follows the game's options menu: colours
sampled from it, the menu's filigree, the white glowing cursor, the Triforce in the title band and as the programs'
icon, and all text in the game's Cetra Display, decoded from the player's own dump. Mouse, keyboard and an XInput
pad drive it.

Updates come from GitHub releases (NX2navi-update.json): the new version is downloaded, checked and staged beside
the running one, the stub restarts into it and falls back to the previous version when it fails to start, and the
game is rebuilt without the dump. make_game.py now keys its exefs and romfs steps on the game files alone, has
--rebuild and --events, compiles only the files whose source, headers, flags or compiler changed, and replaces
ocarina.exe only once the new one links. tools/make_launcher.py builds the release on Windows or Linux.

Tested: tests/launcher_test.py (19 tests), the real toolchain download and install, and under Wine 11 the setup,
the stub, the window on the bundled Windows Python, an update from a local feed by clicking Updates, the rollback
of a version that fails to start, and the downloaded clang compiling and linking a program against the game's
libraries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merged onto the current port: make_game.py keeps the launcher's step keys, cached link and in-place swap, and its
own runtime manifest (windres), AMD's FidelityFX library and the shader preparation, which becomes a step of its own
("shaders") that the launcher shows in its install, rebuild and update jobs. make_launcher.py ships the shader tools
and, with --ffx, AMD's library.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-07 14:50:52 -05:00

4.3 KiB

Raw Blame History

NX2navi build kit

This kit builds The Legend of Zelda: Ocarina of Time (Nintendo Switch 2, game version 1.1.1) as a native Windows program on your PC, from your own copy of the game. The kit contains no game code or data. Everything the build writes (ocarina.exe, the RomFS image, the shader cache, your saves) comes from your game: keep it to yourself.

The NX2navi launcher (NX2navi-Setup.exe, launcher.md) does everything below for you, the downloads included, and keeps the game up to date. This page is the same build by hand.

What you need

64-bit Windows 10 or 11, 16 GB of RAM, a Vulkan 1.3 graphics card with mesh shaders and a current driver (tested on NVIDIA).
Your own dump of the game as a .nup file (or its exefs and romfs folders), with the 1.1.1 update: program 0400486024DEC000, main build e0f3ccfa. Other versions are refused.
About 30 GB free on the disk you build to, besides the dump.

One-time setup (about 15 minutes)

Python 3.12 or later from python.org. Tick "Add python.exe to PATH" in the installer. Then, in a Command Prompt:
```
py -m pip install numpy lz4 zstandard zbic
```
zbic unpacks the game's compressed program files. It is a separate GPL-2.0 package you install yourself; the kit only calls it.

MSYS2 from msys2.org, installed to the default C:\msys64. Open MSYS2 UCRT64 from the Start menu and paste:

pacman -S --needed mingw-w64-ucrt-x86_64-clang mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-sdl3 mingw-w64-ucrt-x86_64-opus mingw-w64-ucrt-x86_64-libvpx mingw-w64-ucrt-x86_64-dav1d mingw-w64-ucrt-x86_64-zstd mingw-w64-ucrt-x86_64-vulkan-headers mingw-w64-ucrt-x86_64-vulkan-loader mingw-w64-ucrt-x86_64-vulkan-memory-allocator

Answer Y when it asks. If MSYS2 is somewhere other than C:\msys64, add --msys <folder>\ucrt64 to the build command.

Build (about 10 to 15 minutes, once)

Unpack this kit anywhere, open a Command Prompt in its folder and run:

py -I tools\make_game.py --nup "C:\path\to\your game.nup" --out "C:\Games\Ocarina"

With extracted folders instead, use --exefs "C:\path\exefs" --romfs "C:\path\romfs" in place of --nup. To only check that your dump is the right version, add --check (it builds nothing).

The build checks the version, unpacks the program files, packs the 26 GB RomFS image (every file is checked against the dump's own checksums), turns the game's code into C and compiles it (about 6 minutes on a 16-thread Ryzen 7; longer on fewer cores), then prepares every one of the game's shaders for your graphics card (about 5 more minutes), so the game does not stop to compile shaders while you play. You can use your PC meanwhile. If it stops, run the same command again: finished steps are skipped.

When it says finished, start C:\Games\Ocarina\ocarina.exe. You can delete C:\Games\Ocarina\build-cache (about 5 GB) afterwards.

Playing

F1 opens the settings menu. Settings are saved in nx2navi.ini beside the game; saves go to profile\.
Every shader was prepared during the build. After an update of your graphics driver, the next start shows "Preparing shaders" once while the driver rebuilds them.
Screen in the menu has Upscaling (DLSS on NVIDIA RTX cards, FSR 3.1 on any card), Frame generation (FSR 3.1; it needs DLSS or FSR 3.1 upscaling on), HDR (Native is the game's own HDR; turn HDR on in Windows first) and the resolution. Those marked "after restart" take effect when the game starts again.
DLSS needs nvngx_dlss.dll from NVIDIA beside ocarina.exe (the kit does not include it); FSR 3.1's amd_fidelityfx_vk.dll is copied there by the build.
Logs are in logs\. When reporting a problem, say where you were in the game and which graphics card you have, and attach logs\nx2navi.log. Never send game files.

If something goes wrong

Message	What to do
`not game version 1.1.1`	Install the 1.1.1 update and dump the game again
`the Python package ... is missing`	Run the `pip install` line above
`...\clang.exe is missing`	Run the `pacman` line above in MSYS2 UCRT64
`needs ... GB free`	Free space on the `--out` disk, or build to another one
The game opens and closes	Update your graphics driver, then send `logs\nx2navi.log`

4.3 KiB Raw Blame History