tangerineturtle1/NX2navi v0.8.0 on GitHub

A performance, fix and feature release for The Legend of Zelda: Ocarina of Time for Nintendo Switch 2 (game version
1.1.1): fewer hitches after entering an area, more frames on NVIDIA and AMD cards, the single-frame flickers and black
frames found and fixed, AMD FSR 4 upscaling, a debug menu for testing, a fallback for video cards without mesh
shaders, and co-op over the internet as a hidden beta. No game files are included: the setup builds the game on
your PC from your own dump.

Install or update

Already have 0.6.0 or newer: start the launcher; it offers 0.8.0, updates itself and keeps the game it compiled
and the shaders it prepared. Only what changed is compiled again, and the shaders translated before carry over to
this version's shader translator.
Already have 0.5.0: the same, and the game's code 0.5.0 compiled is kept as it was compiled (for any x86-64
processor); Rebuild the Game in the launcher's home compiles it again for yours.
New install: download NX2navi-Setup-0.8.0.exe below, put it next to your .nup dump of the game and start
it. Windows SmartScreen warns on the first start because the setup is not signed: choose More info and Run
anyway. The launcher checks your game files, builds the game (10 to 25 minutes, once), prepares every shader and
starts it.

Requirements: Windows 10 or 11; an x86-64 CPU with SSE4.2; 16 GB of RAM; about 30 GB free for the game and 1.5 GB
for the launcher; a GPU with Vulkan 1.3 and VK_EXT_external_memory_host (current NVIDIA and AMD cards). A GPU without
VK_EXT_mesh_shader now gets a fallback (see New), untested on such a card.

Faster

Fewer hitches in the seconds after entering an area. Memory the game has not written for a while is
write-protected in 2 MiB pieces, so that it need not be checked for changes every frame. Protecting a piece takes
microseconds as a rule, but 8 to 17 ms each in the seconds after an area has loaded, and up to 32 pieces were
protected in one go: frames of 50 to 90 ms, in clusters for some 20 seconds after Kakariko, the Market or the
Graveyard came up. The work now stops after a millisecond a pass and waits when a piece was slow. Walking from
Kakariko into Hyrule Field on an RTX 5090, the time lost to such calls after the load went from 1,374 ms to 115 ms
and a 78 ms frame is gone (freeze_budget_us = 0 in nx2navi.ini brings the old behaviour back).
A long stall at some area loads is gone. When the game gave back a block of video memory, it waited until the
card had finished everything queued, the new area's texture uploads included: 418 ms in one frame on entering
Kokiri Forest. It now waits only for the game's own work (pool_fini_idle = 1 brings the old wait back).
More frames on NVIDIA cards than 0.7.1 in the places measured on an RTX 5090 at 1440p: Kakariko 145 to 149 fps
instead of 119, the Market 177 instead of 147, Hyrule Field by day 109 instead of 91. Among the reasons:
- The texture list the game's shaders index is checked through a list of its entries instead of a walk over all of
  its 33,000 slots: about 7 % more frames where the CPU is the limit (Kokiri Forest, five runs, 93.6 to 100.7 fps
  among them).
- On NVIDIA cards the video card is held back only where the game's own barriers ask for it, not before every pass
  and every compute dispatch (barrier_game; NVIDIA only, since the game placed its barriers for NVIDIA hardware).
- The Market no longer stops every eighth frame: a list of texture slots there grew to 160,000 entries in a minute,
  and each walk over it held a lock for 15 to 30 ms.
AMD cards: about a fifth more frames in open areas, and more even frame times. The game asks the video card
which objects are visible, about a hundred questions a frame in Hyrule Field, and waits for a frame to be finished
on the card before it lets the next one start. The answers were fetched one call at a time, on the thread that also
reports "finished", and on AMD's Windows driver each of those calls goes into the kernel: every frame was reported
finished about 4 ms late, with every thread of the game waiting. They are now fetched a few hundred at a time.
Standing in Hyrule Field on an RX 7900 XT (driver 26.10.1, 3440x1440, FSR): 53 fps instead of 45, and the longest
frame of a minute 46 ms instead of 55 (oq_batch = 0 in nx2navi.ini brings the old readback back).
No more frames drawn one present late. The game signals from the CPU when a frame's data is written, and its
render thread submits the frame's commands without waiting for that signal. When the signal came a millisecond or
two after the submit call, in about every other frame in Hyrule Field, the frame was set aside and drawn at its
present, and frames of 23 and 15 ms took turns. The submit call now waits for the signal, 10 ms at most
(gate_wait_ms): 54.5 fps instead of 53 in the same place and the longest frame 33 ms instead of 46; with
vk_recorder = 1, which AMD cards do not have on by default, 58.6 fps.
Fewer pauses when something is drawn for the first time.
- A frame no longer stops for the pipelines of a pass the game renders frame after frame: such a draw is left out
  for the frames its pipeline needs, instead of making the frame wait.
- FSR 3.1's own pipelines go through the pipeline caches kept across runs, so they are not compiled again at every
  start.
- A pipeline cache larger than 2 GB is read on Windows; before, it was refused and every pipeline was built again.
- A pipeline cache save that did not happen is tried again, and the cache is written only when it grew.
- The game's compressed files are decoded by the PC on 1.1.1 too (checked byte for byte over 31.7 GiB of output).
The frame limit counts the frames the game draws, with frame generation's frames on top: a limit of 60 at 4x is
60 drawn and 240 shown, where it drew 15.

New

AMD FSR 4 upscaling on Radeon RX 6000, RX 7000 and RX 9000 cards (Windows, AMD's driver 26.10.1 or newer):
AMD's machine-learned upscaler, in the menu under Screen, Upscaling, as AMD FSR 4 Native AA, Quality,
Balanced, Performance and Ultra Performance (fsr4 = 1 in nx2navi.ini). It keeps thin things whole that
FSR 3.1 breaks up or smears when the camera moves: grass and leaves, Navi's wings, the edges of Link's hat. It is
off until you choose it, because it costs more than FSR 3.1: standing in Hyrule Field on an RX 7900 XT at
3440x1440, 47 fps in Quality where FSR 3.1 gives 51, and 41 fps in Native AA; it takes about 220 MB of video
memory. The setup brings AMD's two libraries for it (FSR SDK 2.4, amd_fidelityfx_loader_vk.dll and
amd_fidelityfx_upscaler_vk.dll), which ask the driver whether the card can run FSR 4: the rows appear only
where it can, and the log names the version (ffx4:). It works together with FSR 3.1 frame generation, and you
can switch between FSR 3.1 and FSR 4 while playing.
Frame generation from AMD's newer library, to try: in the menu under Screen, Frame generation, as AMD FSR 4
library with its version, a choice of its own after AMD FSR 3.1 (fsr4_fg = 1 in nx2navi.ini). Choosing it
sets Upscaling to FSR 4 as well, which it needs. The frames are then generated by the library FSR 4 comes with (FSR
SDK 2.4, amd_fidelityfx_framegeneration_vk.dll) instead of the FSR 3.1 library. It picks the version for your
card: on a Radeon RX 9000 with Windows 11 that is AMD's machine-learned FSR Frame Generation 4, which nobody has
tested in this game yet; on every other card it is version 3.1.6, which on an RX 7900 XT runs at the same frame
rate as before and showed clean frames in a fast camera turn. It is off unless you set it, and when it fails the FSR
3.1 library takes over. Please report how it looks on an RX 9000.
Co-op over the internet, a beta (hidden: add coop_beta = 1 under [coop] in nx2navi.ini to show the menu's
Co-op tab). Players in a room share progress by the room's rules, each in their own save; you do not see the other
players in your world. It needs a relay server you or a friend run (tools/coop_relay.py in the repository): the
game has no address built in. See docs/coop.md.
A fallback for video cards without mesh shaders. The game draws part of the world with mesh shaders; on a card
without them those draws are now run as compute passes and an ordinary draw (mesh_fallback = auto). It draws the
same picture in our test of the path itself and runs slower than real mesh shaders. Nobody has played with it on
such a card yet: please report how it looks.
A debug menu for testing (off by default: Game tab, Debug menu (F9), or debug_menu = 1 in nx2navi.ini). F9
opens a panel on the left edge, in the performance overlay's look, with the game in view beside it. It has five
tabs. Flags: the game's 11,292 on/off flags with a search box, about 2,250 of them by name (the names are found in
your own game's event files; the rest show their hash), each switched with a click through the game's own function,
with the last changes listed to put back. Teleport: every area of the game with its named start positions, 415
places read from your own game's files, with a search box and buttons for the warp songs' pads, both sides of the
loading zones and the boss rooms. A click takes Link there through the game's own change of area, as a door or a
warp song does, so the area loads as in play, a first visit's cutscene plays and a boss room starts its fight.
Cutscenes: the game's 653 event scripts by name (cutscenes, conversations, scripted moments), each started with a
click as if its trigger had fired. The game takes a teleport or an event only while Link stands free: not during a
cutscene or a conversation, and not while he swims. World: Link's position, the game's speed from 0.05x to 8x,
and a free camera. With it on, the game draws from a camera of your own, in play and in cutscenes: close the menu
and the left stick moves it, the right stick turns it, ZR and ZL raise and lower it, R makes it faster and L slower,
while Link stands; or leave it where it is and play on with the pad. It works inside the game's own camera
update, so the game draws, culls and loads detail for what the camera sees. Memory: a search of the game's memory
for a number (1, 2 or 4 bytes, or a float), narrowed down by equals, changed, unchanged, went up or went down, with
a value to set at a place or to hold there. Changing flags or memory, teleporting and starting events can break a
save, and the game saves by itself after a change of area, so keep a copy first.
A new HDR tone mapping, the default with HDR on (hdr_tonemap in nx2navi.ini chooses between it, the one
before and the game's own).
The mouse turns the camera directly on 1.1.1. mouse_mode = direct was the default but did nothing on this game
version: the mouse always went through the stick emulation, which gave no turn at slow mouse speeds and topped out.
In stick mode the mouse now also reaches the game's top turn speed at a camera speed above 1.
The menu opens when the controller in use disconnects and no other is connected, where the game played on with
nothing pressed.
Add to Steam in Customize Launcher (Windows): adds the game to your Steam library as The Legend of Zelda
Ocarina of Time, with Navi as its icon and the title screen's artwork and logo. Starting it from Steam starts the
game. Steam restarts once while it is added.
Custom color scheme in Customize Launcher: pick your own background, panel and button colors on a color
square with a hue bar, or type a hex code.

Fixed

Pictures:

A flash about every half second in which trees, ground and walls lost their light for one frame, in places such as
Hyrule Field near the Market's gate, and much easier to see with frame generation. Each frame the game asks the video
card which objects are visible, and since 0.7.1 it went on as soon as the card had drawn, before all those answers
had been written back, so it could switch a light off on an old answer. It now goes on only once the answers are
in; the slower copies of other data still wait in the background. On the Kakariko route on an RTX 5090 it runs at
the same frame rate as before (124.9 against 124.8 fps). wb_split in nx2navi.ini: 0 waits for everything, 3 is
the old behaviour.
A black picture for one frame, now and then, mostly with FSR upscaling. The game looks textures up that it has
released; past 2,048 of those the oldest was dropped although the game still drew with it every frame.
Buildings or other objects drawn black, or lit wrongly, for one frame, most often with FSR upscaling: the same list
filled up within a minute there, and what was dropped to make room could still be in use. What goes now is something
nothing has drawn with for a while. Seen gone in play over 30,000 frames with FSR while about 50,000 entries were
dropped.
Pale or see-through patches of ground in Hyrule Field and at Lon Lon Ranch, and Link's hair missing after hours of
play: textures no shader had sampled for a while were given up under memory pressure and did not come back, and a
second description of the same texture memory started empty. The first no longer happens, and the second is filled
from the texture's memory.
White flickering spots with DLSS or DLAA: the upscaler's history was thrown away whenever the game moved its render
targets, 26 times in a run through Kakariko; it is now kept.
A dark frame at the Market's gate: a new shadow map started with what the memory under it held before.
Black and white blocks on AMD RX 5000 and RX 6000 cards: on Navi and on Link next to her, on bright floors near her,
and on the bright outdoors seen through a door or window from inside a house. Every float colour a shader writes is
checked for NaN, so that one bad pixel cannot spread through the blur and bloom passes; those checks, and the
game's own NaN tests in nearly nine of ten shaders, are float comparisons that a shader compiler may decide can
never be true. The Windows driver for these cards uses AMD's older shader compiler (the log reads "AMD proprietary
shader compiler"); with it each NaN test is now made on the bits of the number instead, which no compiler can drop.
It is on by default only with that driver (vk_nan_bits); the first start after the update compiles the pipelines
again. Untested on those cards before this release: please report whether the blocks are gone.
Frame generation never generates a frame from a picture with the HUD in it any more: a frame for which the picture
without the HUD is missing is shown as it is, so the HUD cannot be warped along with the scene behind it. On screen
the item button stayed pixel for pixel in place through a fast camera turn, with both frame generation libraries.
A texture whose ASTC decode found no memory is uploaded again instead of being left unfilled.
Two texture reads the shader translator got wrong: an image read without a declared format, and a texture whose
size query reads its layer count.

Crashes and lost video devices:

AMD RX 6000 and older cards: the game should no longer end (code 71) when an enemy is attacked or killed. A player
with an RX 6700 XT had it at every kill since 0.5 and found that gpl = 0 (no graphics pipeline libraries) stops it;
players with an RX 6650 XT and an RX 5700 XT reported the same ending, one of them when killing a Peahat. That is now
the default with AMD's Windows driver for these cards (the log reads "gpl no ... off by default on AMD's driver for
RDNA 2 and older"). The price: a pipeline the game needs for the first time is built whole while its draw is left
out, so new things can appear some frames late, and the start waits until every pipeline of earlier sessions is
built instead of 20 seconds at most. gpl = 1 in nx2navi.ini turns the libraries back on. None of us has such a
card, so please report whether the game stays up.
The game ending with a lost video device about two seconds after loading a save in Hyrule Field at night
(8 times in 23 loads on an RTX 5090, none in 25 since).
A crash with frame generation (AMD FSR 3.1) set: switching Upscaling to a choice without FSR or DLSS and back, which
the Upscaling row does on its way through its choices, ended the game in AMD's driver. Frame generation was handed
the depth picture of the last frame before the switch, which the game had replaced by then.
PCs with fewer than six processor cores: threads that shared a core could read each other's data and crash.
The game ended when it asked for random bytes from a service the runtime did not have ("sm: service csrng is not
implemented").
Several rare crashes found by an audit of the runtime: a directory listing while another thread closed the folder,
full internal tables ending the process instead of reusing a slot, the menu's dictionaries loaded by two threads at
once, two save writes at the same time, and a save write cut off by a crash.
A lost video device now ends the game at once with exit code 72 and its report, where threads could go on using the
device.
Cards that run out of video memory try a smaller allocation before a texture upload gives up.

Other fixes:

The pick-up window (rupees and the like) closes again above 60 fps; its number stopped counting there.
The microphone is opened only when the game starts recording, instead of being held for the whole session (Windows
showed the microphone as in use).
The walk key's rows are on the Controls tab again, and the action prompt's face buttons follow the pad layout.
A pipeline cache file over its size limit was thrown away at every start and never replaced, so every start built
its pipelines again.
The log says when the PC is short of memory for the game at the start, and background pipeline builds wait when the
system's memory runs low instead of adding to it.
On RTX 50 cards the log no longer says DLSS frame generation needs an RTX 40 card, and says why it is unavailable.

Launcher and setup:

An update that stops during the compile keeps the game installed; the launcher no longer starts on the first-run
screen and asks for the dump.
A version that cannot start rolls back to the one before without waiting for a click.
The setup checks the free disk space it really needs, counting shaders it has already prepared, and the build tools,
before the long steps; it says how long an install or update really takes, and shows 100 % for shaders only when
the last one is built.
The build runs below normal priority, caps its compiles by the free memory, keeps finished objects when it is cut
short, and reports its errors with their message, including the game's FATAL line when it ends with code 70 or 71.
A game on a mapped network drive can be built: the build rides out a short dropout and no longer needs a private
temporary folder on the share.
A comma in the game folder's path no longer breaks the build.
Update checks are held back when GitHub limits them, with the time it takes them again.
The game files are checked faster, and the check says what it found.
Export Save with the bug report box writes the game's log and settings when the game has no save yet.
Your own background picture is no longer partly hidden under the top bar: it now starts right below it, and keeps
its shape.
The older installer's last step no longer writes nx2navi.ini again as a whole to set the language: it changes the
lang line and keeps every other byte.

Linux:

With NVIDIA's own driver, the game's memory is imported directly, as on Windows, instead of copied: in Kokiri
Forest on 0.7.1 (RTX 4090) 51.9 fps against 27.4 with the copies (NX2NAVI_SHADOW=1 brings the copies back).
With the copies (the default with AMD and other drivers), foliage and Navi are drawn through the game's pointer
table again, and a frame no longer flickers brighter when a copy-back landed after the game's own write.
Restart starts the game again on every processor it had, and the AppImage checks its zstd module the way the
build imports it.

Changed

AMD cards: the faster copy-back of 0.7.1 is off by default again. 0.7.1 turned it on for every card on Windows
(what the game's shaders write is copied back from the video card once, and then only when the game's CPU code
touches it). Since then two reports from AMD cards had the game end in play: an RX 6600 lost its video device a
few minutes in with it on, and a player whose game ended in fights played for hours with it off. We found no fault
in the code and cannot say it was the cause, and none of us has played a fight on an AMD card with it on. Until
someone has, the old copy-back at the end of every GPU submission is the default with AMD's Windows driver; open
areas run slower for it, as they did in 0.7.0. The RX 7900 XT figures under Faster come from builds that had it
on by default. wb_lazy = 1 in nx2navi.ini turns it on: if you try it, play a few fights and tell us whether the
game stays up, with the log. NVIDIA cards keep it on. The log says which is in effect and why ("mem: lazy
write-back ...").
Texture detail picks one step lower on a card under 20 GB where ASTC textures stay uncompressed, and the limit on
textures the game has released follows the card's memory as well as the PC's.
A line in nx2navi.ini that is no setting of this version is pointed out. Such a line does nothing; the game
only wrote "unknown key" into its log. The log now lists them in one line at the start, beside a line with every
setting the file does set, and the settings menu shows them in its bottom row. An update or a rebuild never rewrites
nx2navi.ini, and the menu keeps such lines when it saves, so nothing has to be added again after an update.
When the game ends with a fatal error or a crash, the end of the log names the video card, its driver, the memory
mode, whether the lazy write-back was on (with its armed ranges, its fetches so far and one in progress) and the
texture detail, so a report that holds only the last lines of a log still says them; a crash in another program's
module says so.

Known issues

FSR 4, its frame generation, the AMD-only fixes and the mesh shader fallback were not run by us on the cards they
are for before this release. Please report how they behave.
The first visit to an area after an install can still pause while the graphics driver builds what it has not seen,
and the frame in which a new area first appears can take a quarter of a second while its textures are decoded.
When the system's memory is nearly full, towns re-upload many textures and the frame rate drops; closing other
programs helps.
Integrated AMD GPUs can fail at the title screen (their host memory heap is too small for the game's memory).
Nothing in this release was run on Linux by us.

Thanks

Pull requests in this release came from ordinarybob, mooki000, jacc, SleepyYui, Shikakiben, tompipe and DeepDaddyTTV.
Thanks to everyone who sent logs, captures and test reports, among them the crash reports from RX 6000 owners.

Report problems as issues, with the game's log (logs\nx2navi.log in the game folder) and what you were doing; Export
Save with the bug report box ticked packs the log, your settings and your save into one zip.

NX2navi is an independent, non-commercial fan project, not affiliated with or endorsed by Nintendo. The Legend of
Zelda, Ocarina of Time and Nintendo Switch are trademarks of Nintendo.

tangerineturtle1/NX2navi v0.8.0 NX2navi 0.8.0 on GitHub