Make the release 0.8.0, with its notes.

The draft notes for the release after 0.7.1 become the notes of 0.8.0: every change since 0.7.1, the install and
update steps, the requirements (mesh shaders are no longer required, with the fallback untested on such a card), the
known issues and the thanks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
chrg6
2026-11-11 09:16:23 -05:00
parent a516025760
commit 7f01711087
2 changed files with 173 additions and 58 deletions

View File

@@ -1 +1 @@
0.7.1
0.8.0

View File

@@ -1,7 +1,46 @@
Draft notes for the release after 0.7.1. The version number is not decided yet.
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, co-op over the internet to try, a debug menu for testing, and a fallback
for video cards without mesh shaders. **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
@@ -15,18 +54,16 @@ Draft notes for the release after 0.7.1. The version number is not decided yet.
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 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.
- **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
@@ -48,6 +85,13 @@ Draft notes for the release after 0.7.1. The version number is not decided yet.
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, to try** (off by default; the Co-op tab of the menu). Players in a room share progress by
the room's rules, each in their own save. It needs a relay server you or a friend run: 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
@@ -64,62 +108,45 @@ Draft notes for the release after 0.7.1. The version number is not decided yet.
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 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.
- **Co-op over the internet, to try** (off by default; the Co-op tab of the menu). Players in a room share progress by
the room's rules. It needs a relay server you or a friend run: the game has no address built in.
- **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 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 menu opens when the controller in use disconnects** and no other is connected, where the game played on with
nothing pressed.
## Fixed
- 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.
- 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.
- Your own background picture in the launcher is no longer partly hidden under the top bar: it now starts right
below it, and keeps its shape.
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.
- 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 (`wb_split` in `nx2navi.ini`: 0 waits for
everything, 3 is the old behaviour). Seen gone in play; its cost in frame rate is not measured yet.
- 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.
- 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 dark frame at the Market's gate: a new shadow map started with what the memory under it held before.
- 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.
- 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 setup's check of free disk space counts shaders it has already prepared, and a failed build is reported as
such.
- 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
@@ -128,16 +155,79 @@ Draft notes for the release after 0.7.1. The version number is not decided yet.
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.
- AMD RX 6000 and older cards: the game should no longer end (code 71) when an enemy is 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; a
player with an RX 5700 XT reported the same ending. 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. One player's finding on one card; none of us has such a
- 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 (it turned Windows line ends into Unix ones and dropped a byte order mark).
`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
@@ -151,10 +241,35 @@ Draft notes for the release after 0.7.1. The version number is not decided yet.
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.
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.