mirror of
https://github.com/tangerineturtle1/NX2navi.git
synced 2026-11-15 19:19:58 -04:00
dfc5b90b59
The commit census of the perf trace walked the address space on the presenting thread outside mem_census, which brought back the hitch mem_census was added to remove; it now runs only with mem_census = 1. DLSS's output pass at the mode's share fell back to no pass at all when the scene was not at that share (the first presents, a dynamic resolution step): after such a frame the first pass wider than the scene is taken again for 120 frames. The launcher's nx2navi.ini editor no longer rewrites a file it cannot read, keeps the byte order mark and bytes that are not UTF-8, reads an empty line as the game does, and leaves no temporary file behind. The build kit carries the two modules build_game.py imports on Linux, the Linux steps list the right packages and Python, and stale comments and notes are corrected (Discord on by default, two prebuild threads, Enhanced HDR gone). DLSS Frame Generation needs nx2navi_dlssg.dll, NVIDIA Streamline's runtime and nvngx_dlssg.dll beside the game, which no release carried, so the menu offered it and the game turned it off. tools/make_launcher.py --dlssg and --streamline put them with their licences and a notice in the release's bin/dlssg/, and tools/make_game.py place_dlssg copies the whole set beside the game. THIRD_PARTY_NOTICES.md has the row; the notes and README say RTX 40 and 50. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
135 lines
8.0 KiB
Markdown
135 lines
8.0 KiB
Markdown
# 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](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)
|
|
|
|
1. **Python 3.12 or later** from [python.org](https://www.python.org/downloads/windows/). Tick "Add python.exe to PATH"
|
|
in the installer. Then, in a Command Prompt:
|
|
|
|
```bat
|
|
py -m pip install numpy lz4 zstandard zbic fonttools pillow
|
|
```
|
|
|
|
`zbic` unpacks the game's compressed program files. It is a separate GPL-2.0 package you install yourself; the kit
|
|
only calls it. `fonttools` and `pillow` draw the Xbox, PlayStation and keyboard and mouse button prompts, when the
|
|
kit has a `prompt-art` folder.
|
|
|
|
2. **MSYS2** from [msys2.org](https://www.msys2.org/), installed to the default `C:\msys64`. Open **MSYS2 UCRT64** from
|
|
the Start menu and paste:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```bat
|
|
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) while it 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. When the kit has a `prompt-art` folder, it
|
|
last draws the Xbox, PlayStation and keyboard and mouse button prompts from that art (about a minute) into the
|
|
`romfs-patches-*` folders beside the game. The game it builds is for this PC's processor. 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.
|
|
|
|
## Linux
|
|
|
|
The same command builds a native Linux `ocarina` on an x86-64 Linux 6.7 or later (the write watch needs
|
|
`PAGEMAP_SCAN`) with a Vulkan 1.3 driver that has `VK_EXT_external_memory_host` and `VK_EXT_mesh_shader` (NVIDIA,
|
|
RADV). It takes clang, clang++ and lld from `PATH` and links against the system's libraries; `--msys` is not used.
|
|
|
|
1. Packages, on Arch and its derivatives (other distributions: the same libraries and their `-dev` headers):
|
|
|
|
```sh
|
|
sudo pacman -S --needed clang lld sdl3 opus libvpx dav1d zstd vulkan-headers vulkan-icd-loader \
|
|
python python-fonttools python-pillow python-numpy python-lz4 python-zstandard dotnet-sdk
|
|
```
|
|
|
|
Python 3.10 or later (with 3.14 the RomFS step uses its own `compression.zstd`, else the `zstandard` package; the
|
|
button prompts need `fonttools` and `pillow` when the kit carries button art), then `zbic`, which the kit only calls
|
|
(GPL-2.0): `pip install --user zbic`, or in a virtual environment with the packages above.
|
|
Vulkan Memory Allocator is one header: the system's (AUR `vulkan-memory-allocator`), else the build fetches the
|
|
pinned 3.4.0 into `toolchain/vma/` and checks its hash.
|
|
|
|
2. The shader translator: a kit with `bin/nx2navi_xlate` has it; from a source checkout, build it once with
|
|
`python tools/build_xlate.py` (needs the .NET 10 SDK). The build copies it beside the game.
|
|
|
|
3. Build, then play:
|
|
|
|
```sh
|
|
python3 -I tools/make_game.py --nup "/path/to/your game.nup" --out ~/Games/Ocarina
|
|
~/Games/Ocarina/ocarina
|
|
```
|
|
|
|
With 16 GB of RAM, add `--jobs 4`: the compiles run beside the 26 GB RomFS image, and one clang per logical
|
|
processor can fill memory and swap until the kernel stops processes of the desktop session (about 10 minutes on a
|
|
12-thread Ryzen with 4 jobs). Do not play or prepare shaders while it builds.
|
|
|
|
On NVIDIA, start the game with `NX2NAVI_SHADOW=0` if the 3D world stays black while the HUD draws (issue #72). The
|
|
profile, logs and settings are in the `--out` folder as on Windows.
|
|
|
|
`tools/make_appimage.py` packs this kit into one `NX2navi-Linux-<version>-x86_64.AppImage` with its own Python, for
|
|
players without a source checkout: it checks for the packages above, installs zbic with pip on its first run, picks
|
|
`--jobs` from the memory, builds into `~/Games/Ocarina` (or the folder given after the dump) and writes `play.sh`
|
|
beside the game.
|
|
|
|
## 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. With a driver that has Vulkan's graphics pipeline library
|
|
it lasts at most about 20 seconds once the shaders are translated, and the remaining pipelines are built in the
|
|
background while you play.
|
|
- **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 (the game's picture tone mapped to your display, with its own grading rows, or Native, 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.
|
|
- **Controls** in the menu has Button prompts: the game's own, or Xbox, PlayStation or keyboard and mouse ones when
|
|
the build drew them (a kit with `prompt-art`). It takes effect after a restart. The keyboard and mouse prompts show
|
|
the keys `nx2navi.ini` binds when the build runs: after rebinding keys, run
|
|
`py -I tools\make_game.py --rebuild --out "C:\Games\Ocarina"` to draw them again (it skips everything else).
|
|
- The build copies NVIDIA's DLSS library `nvngx_dlss.dll` (with `nvngx_dlss-NOTICE.txt`, which names its licence)
|
|
and FSR 3.1's `amd_fidelityfx_vk.dll` beside `ocarina.exe` from the kit's `bin\`. To use another DLSS version, put
|
|
your own `nvngx_dlss.dll` there: later builds keep it.
|
|
- 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 |
|
|
| `clang is not on PATH` (Linux) | Install the packages under "Linux" |
|
|
| `nx2navi_xlate is missing` (Linux) | Build the translator with `python tools/build_xlate.py` |
|
|
| `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` |
|