Merge the fixes line: the stutter, memory, flicker and crash fixes, co-op, the mesh shader fallback and the launcher fixes.

Brought onto the line with FSR 4, its frame generation and the debug menu. Where both sides had added to the same
place, both stay: the patch table keeps the pickup count and the free camera, the settings list keeps both sides'
names, the menu includes the co-op page and the debug menu, and the launcher builder takes the pipeline list and the
FSR 4 folder. Both sides had added the menu's typed-character event; one definition stays, with the window code that
passes characters outside the basic plane.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
chrg6
2026-11-11 08:18:01 -05:00
213 changed files with 39872 additions and 1598 deletions

View File

@@ -13,7 +13,7 @@ downloads included, and keeps the game up to date. This page is the same build b
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.
- About 34 GB free on the disk you build to, besides the dump.
## One-time setup (about 15 minutes)
@@ -58,7 +58,7 @@ last draws the Xbox, PlayStation, Steam Deck and keyboard and mouse button promp
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.
1.5 GB) afterwards.
## Linux
@@ -78,6 +78,17 @@ RADV). It takes clang, clang++ and lld from `PATH` and links against the system'
(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.
The Vulkan headers must be release 363 (1.4.363) or newer: the runtime names extensions that older headers do not
declare (`VK_KHR_pipeline_binary` among them), and distributions with long support package older ones. The
AppImage carries the pinned headers (`toolchain/vulkan-headers/`, `tools/vulkan_pin.py`) and builds against them
whatever the system has; a build from a kit or a source checkout uses the system's when they are new enough and
otherwise fetches the pinned ones there once and checks their hash. The loader's library still comes from the
system (`vulkan-icd-loader`, `libvulkan-dev`, `vulkan-loader-devel`).
The compiler is the system's too. The releases are built with clang 23; an older one works as far as it compiles
the runtime (one without `#embed`, before clang 19, takes the menu's font from a header the kit carries). Before
its long steps the build checks every runtime source with that compiler and links against the libraries, so a
compiler, a header or a library it cannot use stops it in the first seconds, with the compiler's own words, and
not after the RomFS image.
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. A kit also carries the
@@ -133,8 +144,9 @@ switches at once, with a *DLSS multiplier* of 2x to 6x (above 2x on RTX 50 cards
frames needed to reach the display's refresh rate (`framegen = dlss` and `fg_mult` in `nx2navi.ini`). The log says
`ngxfg: DLSS Frame Generation available` when NGX found the library.
`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
`tools/make_appimage.py` packs this kit into one `NX2navi-Linux-<version>-x86_64.AppImage` with its own Python and the
pinned Vulkan headers, for players without a source checkout: it checks for the packages above (their Vulkan headers
are not needed), 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.
@@ -149,14 +161,18 @@ beside the game.
driver keeps the prepared shaders' libraries in that cache, and a smaller limit drops the oldest as new ones come in
(a 2048 MB cache could not hold them): every start then builds them again in the background, and play stutters, with
some things missing for a few frames, until that is done. The log's `library warm` lines say when this happens.
- With 16 GB of RAM, give Windows a fixed page file whose initial size is at least 32 GB (System, About, Advanced
system settings, Performance Settings, Advanced, Virtual memory: untick the automatic management, Custom size with
an initial size of 32768 MB or more, Set, then restart). Windows counts the game's video memory
against RAM plus page file, and a page file Windows sizes itself grows too slowly for Hyrule Field: the game then
lets textures go and the ground can flash white or black. The log says `system commit low` when this happens.
- **Screen** in the menu has Texture filtering (anisotropic, up to 16x, at once), Texture detail (Reduced and Low
leave out the largest versions of the big surface textures so that the game fits the video memory of 6 and 8 GB
cards; Automatic picks by the card), Upscaling (DLSS on NVIDIA RTX cards,
FSR 3.1 on any card where `amd_fidelityfx_vk.dll` loads, FSR 4 on the Radeon cards AMD's FSR 4 libraries list it
for), Frame generation (NVIDIA DLSS on RTX 40 and 50 cards, with
a DLSS multiplier of 2x, or 3x and 4x on RTX 50 cards; FSR 3.1 on any card where it loads; it needs DLSS or FSR 3.1
upscaling on, and the frame limit then counts the frames on screen; with no limit chosen it is the display's refresh
rate), 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
upscaling on; the frame limit counts the frames the game draws and the generated ones come on top), 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. A setting that takes effect only when the game starts again says "after restart" once you change it,
until you set it back, and the Restart button at the bottom then counts the settings waiting for it.
- **Controls** in the menu has Button prompts: the game's own, or Xbox, PlayStation, Steam Deck or keyboard and mouse ones when

View File

@@ -45,6 +45,8 @@ from other projects, with its license, is listed in [THIRD_PARTY_NOTICES.md](../
order it logged them: a line waits for the queue's lock, and one that finds the queue full is written after
everything queued before it. A fatal error, the crash report and the end of the process write the queue out first
(`rt_log_sync`). `NX2NAVI_LOG_ASYNC=0` writes each line where it is logged.
- Co-op (`coop.c`, `coop_proto.c`, [coop.md](coop.md)): a host thread with a UDP socket to a relay (`tools/coop_relay.py`),
rooms of up to 8 players and a channel for messages between them; it never holds a virtual core.
- OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`).
#### Threads and cores
@@ -128,10 +130,39 @@ keeps per-core data without locks and relies on that, so the host models it (`ru
their stand-in, and the frame's later refreshes skip them (`runtime/vk_exec_draw.c` `pool_refill`). An area load
spreads over several frames instead of holding one for 200-400 ms.
- Mesh and task shaders run as `VK_EXT_mesh_shader`; indirect mesh draws read NVN's `{count, first}` record through a
ring of Vulkan `{x, y, z}` records filled on the GPU.
ring of Vulkan `{x, y, z}` records filled on the GPU. The copy cannot be recorded inside a pass, so the first such
draw of a pass fills the records of the mesh draws that follow it too, and the pass is not cut at each of them
(`runtime/vk_exec_draw.c` `mesh_ring_entry`).
- Mesh fallback (`mesh_fallback`: `auto` on a device without the extension, `1` on any device for testing): the task
and mesh stages run as compute dispatches and the result is drawn as ordinary triangles.
- The modules come from the translations the shader cache already holds, not from the translator
(`runtime/mesh_fb.c`): a translated task or mesh module is the program as a compute function over shared memory
plus an entry function that hands that memory to the mesh pipeline, and the fallback replaces the entry function
by one that copies the memory into a storage buffer. The translator, its identity and every cache key stay as
they are, so a device with mesh shaders keeps its shaders and never sees these modules, and a device without
needs no other cache or prepared shader list.
- A draw is: its record (the workgroup count, copied on the GPU when the game's record holds it); the task
dispatch, which writes each task workgroup's payload into the task buffer; a scan (`shaders/meshfb_scan.comp`)
that lists the mesh workgroups the tasks started, in task order, and writes their number into the record; the
mesh dispatch, which writes each workgroup's vertex lines and primitive bytes into its slot of the mesh buffer;
and an instanced indirect draw, one instance per slot, whose generated vertex stage looks the vertex of each
primitive corner up in the slot (`runtime/vk_exec_draw.c` `mfb_draw`, `runtime/vk_mesh_fb.c`).
- Each step reads what the one before wrote, so full barriers stand between them and every such draw ends its pass:
a village frame's 45 mesh draws are 45 passes cut, 90 to 135 dispatches and about 270 barriers more than with mesh
shaders. The buffers (`mesh_fallback_mb`, 128 MiB) are reused by every draw, so they hold the largest draw, not
a frame; a draw that emits more loses what does not fit, and the log says how much it needed.
- A program's modules and compute pipelines are made on a thread of their own at its first draw, which is skipped
until they are ready; they are not recorded for the next start, where the pipeline cache makes them quick.
Not carried: the far shadow cascades' coarser shading rate, a draw's first workgroup other than 0, and more
workgroups in one draw than one compute dispatch may have.
- Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it: stage libraries compiled ahead, a fast link
at a new state, an optimised pipeline replacing it from a background thread. A draw whose pipeline is not ready is
skipped when one of its pass's targets was rendered in the previous frame, and waits otherwise. Three things keep
skipped when its pass is one the game renders frame after frame: one of its targets was rendered in the last few
frames, or in eight frames or more at any time, which keeps the first frame after a loading screen from reading as
all new (`runtime/vk_target_frames.h`). A draw into a target rendered for the first time, and a full-screen draw,
wait instead, from one pool of 50 ms a presented frame (`pipe_frame_wait_ms`; `runtime/vk_exec_draw.c`
`prepare_draw_ex`, `frame_wait`); what is not ready when the pool is spent is skipped and built on a worker, so no
frame waits for pipelines much longer than that. Three things keep
that short on a first visit (`runtime/vk_pipeline.c`): a pipeline whose fragment shader reads a target of its own
pass is fast-linked like any other, the feedback loop flags being part of the fragment output library alone
(`gpl_feedback`); the library workers also link the pipelines of skipped draws, so a burst of new materials is
@@ -146,12 +177,19 @@ keeps per-core data without locks and relies on that, so the host models it (`ru
is built ahead only when a run has dispatched it: a pipeline of one holds about 100 MiB of device memory whether it
is used or not, also after it is destroyed, and the list has about twenty of them that the game never dispatches
(`runtime/vk_pipeline.c`, "compute pipelines the boot keeps").
The pipeline cache is two files beside the game. `pipeline-cache.bin` holds what the preparation built and what
earlier runs made; what a run compiles goes into `pipeline-cache-play.bin`, so one new pipeline in play writes a
small file and not hundreds of megabytes. A cache is written only when its data grew. The small file is merged
into the large one at a start once it reached `pipeline_cache_play_mb`, and by every preparation; the stage
libraries the library warm builds in play go to the driver's own cache alone (`runtime/vk_pipeline.c`, "the play
cache", `cache_save`).
- The game's tensor-core upscaler is replaced by a decode-and-scale pass (`vk_tonemap.c`); `vk_fsr.c` runs AMD FSR 1
(EASU, RCAS) on the present when the window is larger than the picture.
- HDR (`vk_hdr.c`): the game tonemaps its scene into a float target, upscales it, draws the HUD into a second float
target and copies that into the 8-bit sRGB window texture it presents. With `NX2NAVI_HDR=1` the tonemap shader gets
the function of `shaders/hdr_tonemap.frag` spliced in where its SDR curve clamps each channel, so the float picture
holds the HDR picture relative to the HUD's white; the game's FSR 1 pass loses its output clamp; the present reads
holds the HDR picture relative to the HUD's white (the function gets the values the curve takes, and the scene
before the game's exposure gain with that gain, which its default tone mapper anchors mid grey on); the game's FSR 1 pass loses its output clamp; the present reads
the float picture in place of the window texture and `shaders/hdr_encode.comp` writes PQ for an HDR10 swapchain.
`NX2NAVI_HDR=native` reports an HDR10 display to the game, which then renders and presents its own PQ picture.
The menu switches between off and `1` during a run: the splice, the HDR extensions and the settings in the support

View File

@@ -4,24 +4,27 @@ The runtime connects Ocarina's polling `nn::audio` input calls to SDL3's default
microphone or audio interface as the operating system's default input and enable the game's microphone control.
Both a hummed note and an instrument received by that input go through the game's own note recognition.
Audio capture opens when the game calls `OpenInputStream` and starts only on `StartInputStream`. The runtime does
not write recordings to disk. SDL converts the input device's format to the requested PCM format and sample rate.
At `OpenInputStream` the runtime checks that a default input exists and prepares a buffer. It opens the recording
device at `StartInputStream` and releases it at stop or close. After a stop, the game can still read or purge the
buffered frames and start capture again. Recordings stay in memory. SDL converts the input device's format to the
requested PCM format and sample rate.
The capture callback uses a bounded ring: unread overflow drops the oldest complete frames instead of retaining
an unlimited recording while the game is paused. Stop, purge and close are distinct operations. Purging an unopened
or failed stream is safe, including the null-stream path that previously crashed in `InputStreamImpl::Purge`.
This implements the non-event polling overload used by Ocarina 1.1.1. Event-based streams, per-device selection,
hot-unplug recovery and packed 24-bit PCM are not implemented. Statistics return a neutral 24-byte structure.
Unsupported formats and a denied or missing recording device return an input error rather than reporting a
successfully opened stream. Input currently follows the operating system's default recording device; there is no
new runtime menu setting.
An unsupported format or missing default device returns an error at open. If the device disappears or access is
denied when capture starts, start returns an input error and the game can retry. Input follows the operating system's
default recording device; there is no new runtime menu setting.
## Validation
`python tests/audio_input_check.py --toolchain C:/msys64/ucrt64` builds and runs headless checks using SDL's dummy
audio driver. They require no game files and do not open a physical microphone. They cover sample ordering across
ring wrap and overflow, frame counts, start/stop, repeated open/close, purge, unsupported formats and purge/read
after a failed open. On Linux, omit `--toolchain` and install SDL3's development package and pkg-config.
audio driver. They require no game files or physical microphone. They check that idle streams leave the device
closed, that a denied start can be retried, and that stopping one stream releases its device and preserves unread
frames. They also cover ring wrap and overflow, frame counts, repeated open/close, unsupported formats and
purge/read after a failed open. On Linux, omit `--toolchain` and install SDL3's development package and pkg-config.
A separate local real-device check received mono signed PCM16 at 48 kHz, verified the 4800-frame ring remained
bounded, and opened and closed the device three times. In an Ocarina 1.1.1 Windows session built from the 0.5.0

View File

@@ -24,7 +24,7 @@ Versions are the ones the build was verified with; newer patch releases are fine
MSYS2 packages, after `pacman -Syuu` (run it twice; the first pass updates the core and exits):
```sh
pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-{clang,lld,ninja,gcc,make,pkgconf,sdl3,opus,libvpx,zstd,vulkan-devel,\
pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-{clang,lld,ninja,gcc,make,pkgconf,sdl3,opus,libvpx,dav1d,zstd,vulkan-devel,\
vulkan-memory-allocator,vulkan-validation-layers,shaderc,spirv-tools} base-devel git unzip
```
@@ -94,6 +94,9 @@ of them.
.venv\Scripts\python tools\build_game.py --version <ver>
```
The menu's font comes into `runtime/ui/menu.cpp` with `#embed`; for a compiler without it (before clang 19, which
a Linux build with the distribution's compiler can meet) the same step writes the font's bytes as
`runtime/ui/roboto_ttf.h` (git ignores it), which `menu.cpp` then includes.
The runtime's own shaders (upscaling, HDR, texture decode and the like) are in the repository as source only:
GLSL and SPIR-V assembly in `runtime\shaders\`, and two small ones assembled by `tools\make_dlaa_mask.py` and
`tools\make_mvobj_fs.py`. `build_game.py` compiles them into `runtime\<name>_spv.h` (git ignores these) before it
@@ -155,6 +158,28 @@ of them.
version; they build at their first draw instead, another driver version builds them again, and so does deleting the
file.
What this step leaves for play, and the shared pipeline list. The step translates every shader's default variant
and the shader list's variants and builds each one's stage library or compute pipeline. A whole graphics pipeline
is built ahead only at the start of a game folder that has drawn it before (`pipeline-keys.bin`); a pipeline met
for the first time is linked from its stage libraries in 2 to 6 ms, except a mesh pipeline, which has no libraries
and compiles whole (0.2 to 1.1 s, its draws left out of the picture meanwhile). `tools/pipeline_list.py merge`
folds the `pipeline-keys.bin` and `shader-answers.bin` of game folders that were played into a pipeline list;
`prepare_shaders.py` reads it from `tools\data\pipeline_list.bin` (`data\pipeline_list.bin` in a release folder, or
`--pipeline-list`), adds the shader variants it names to the seed and writes its records next to the game as
`seed-pipeline-keys.bin`, and `--prepare-shaders` builds the mesh pipelines among them into the pipeline cache and
the driver's (`runtime/vk_pipeline.c` `seed_pipelines`; `NX2NAVI_PREPARE_PIPELINES=all` builds the vertex pipelines
too). `--warm-shaders` builds them again, and `nx2navi.exe --prepare-pipelines` does that step alone. The list is
derived from game data: it is not in the repository (`tools/check_content.py` refuses it), and a kit, a launcher
release or an installer release takes one with `--pipeline-list` (`tools/make_kit.py`, `make_launcher.py`,
`make_release.py`). A list belongs to the record layout of the runtime that wrote it; another runtime says so and
builds nothing from it. `python tests\pipeline_list_test.py` checks the tool on made-up folders.
What a game folder's shader cache holds can be checked without the game:
`python tools\validate_shader_cache.py <game folder>\shader-cache` reads every translated shader from the pack and
the loose files, applies the checks the game makes when it loads one (those that fail are translated again at
their next use) and runs `spirv-val` on the rest; `--every N` samples, `--out FILE` lists the failed ones. It writes
nothing to the cache. `python tests\validate_shader_cache_test.py` checks the tool on a made-up cache.
7. Run. The game keeps running when its window loses the focus (`assume_focus = 1` in `nx2navi.ini`, the default; the
Game tab switches it). With 0 it pauses, as it does on the Switch when Home is pressed.
@@ -213,12 +238,16 @@ Requirements:
- Packages on Arch:
```sh
pacman -S --needed clang lld ninja make sdl3 opus libvpx zstd vulkan-headers vulkan-icd-loader \
pacman -S --needed clang lld ninja make sdl3 opus libvpx dav1d zstd vulkan-headers vulkan-icd-loader \
vulkan-validation-layers shaderc spirv-tools dotnet-sdk uv git
```
Vulkan Memory Allocator is a single header (AUR `vulkan-memory-allocator`). Without it, `build_game.py` fetches the
version the Windows release pins (3.4.0) into `toolchain/vma/` on first use and checks its hash.
The Vulkan headers must be release 363 (1.4.363, the one MSYS2 supplies on Windows) or newer: the runtime names
extensions older headers lack. Where the system's are older, `build_game.py` and `make_game.py` fetch that release
into `toolchain/vulkan-headers/` on first use, check its hash and put it ahead of the system's (`tools/vulkan_pin.py`,
`build_game.py` `vulkan_include`).
The steps are the Windows ones with POSIX paths: `.venv/bin/python` in place of `.venv\Scripts\python`, and `nx2navi` in
place of `nx2navi.exe`. `build_game.py` takes clang, lld and Ninja from PATH (or the ones in `<dir>/bin` with
@@ -249,17 +278,33 @@ writes come back at its fence. Pages both sides write keep a base copy, so each
a VRAM mirror's write-back merge marks the pages it changed, and only those are compared at the fence; a lookup that
reads guest memory itself (the uniform snapshot, `vk_mem_lookup`) does not queue its pool for the copy-in. In Kokiri
Forest (1.1.1, RTX 4090) that costs about 1 ms a frame (copy-in 0.5 ms, write-back 0.6 ms), and the copies hold about
5 GB. `NX2NAVI_SHADOW=1` turns it on under Windows too. The Steam Deck's RADV has `VK_EXT_external_memory_host` as
5 GB. The GPU's bytes reach guest memory in the fence's completion callback, later than an import's, so the wait
after a frame's first submission covers the write-backs there (`runtime/vk_sync.c`, "the executed timeline"): the game
rewrites what those passes wrote without a fence, and a write-back that landed after the rewrite left the GPU adding
light onto its own last output, the whole scene brighter for a frame. `NX2NAVI_SHADOW=1` turns it on under Windows too. The Steam Deck's RADV has `VK_EXT_external_memory_host` as
well: the shadow copies are chosen for the measured cost above, not for a missing extension.
The device address table (`runtime/vk_gpa.c`) names a pool's shadow copy as it names an import, so shaders follow guest
pointers into either. A shader that reads through the table resolves nothing, so the pool it reaches is not queued for
the copy-in: a part whose pipelines declare the table is marked at its draws and dispatches, and its prologue brings
the shadow of every pool in the table up to date with the pages the CPU wrote and queues the same pages for those
pools' VRAM mirrors (`vk_memory.c` `vk_mem_gpa_sync`). That copies the written pages of every CPU-visible pool in
each such part, which the cost above does not include. What a shader stores through the table into a shadow copy does
not come back to guest memory. `--probe-vkmem` checks the read: a shader follows the table to a word of a pool that is
never bound, and must read `0x13579BDF` and, after a plain CPU write, `0x2468ACE0`. On Linux, run it for each backing:
the copy-in: a guest submission whose record binds the table (`vk_exec_draw.c` `ssbo_info`) brings the shadow of
every pool in the table up to date with the pages the CPU wrote, once, before the first part recorded after the
binding is submitted, and queues the same pages for those pools' VRAM mirrors (`vk_memory.c` `vk_mem_shadow_sync`).
That copies the written pages of every CPU-visible pool once in each such guest submission, which the cost above does
not include. What a shader stores through the table lands in the shadow copy
and in the pool's VRAM mirror, and no binding names it, so nothing notes it as a GPU write: it does not come back to
guest memory, and the next whole copy-in of its page (the CPU rewrites other words of the same records) puts guest
memory's stale bytes back over it in both copies. In the runs measured so far that copy-in always came before the
frame's stores, which does no harm. `NX2NAVI_SHADOW_TABLE_STORES=1` keeps the stores instead: the copy-ins then keep a
hash of each page they write, a page whose shadow no longer matches its hash was stored into, keeps a base copy from
then on like a page with a noted GPU write, and has its stores written back to guest memory at the fence of every
submission that uses the table. It is off by default (`runtime/vk_memory.c`, "Pages a shader stores into", says why).
`NX2NAVI_SHADOW_CHECK=1` logs every 60 frames how often a copy-in overwrote such a store and for which pools, how many
write-backs landed on pages the CPU had written since their copy-in, and what the copy-ins cost and where they went.
`--probe-vkmem` checks the sync: the shadow of a pool that is never bound must hold `0x13579BDF`, keep it through a
plain CPU write and a guest submission that does not bind the table, and hold the written `0x2468ACE0` after one that
does; and with `NX2NAVI_SHADOW_TABLE_STORES=1` the store: a GPU
write into a shadow page that nothing notes must survive the CPU's writes of that page and reach guest memory. On
Linux, run it for each backing:
```sh
for shadow in 0 1; do for memory in import mirror; do
@@ -278,6 +323,13 @@ Before a commit:
`git config core.hooksPath .githooks` runs it before each local commit.
- `build\<ver>\nx2navi.exe --selftest`: layout, dispatch table and host-function registry, without game files.
GPU page faults: `NX2NAVI_VA_REPORT=1` keeps the driver's GPU address bind/unbind reports
(VK_EXT_device_address_binding_report, `runtime/vk_vaddr.c`); `=2` also keeps the host call stack of ranges of 1 MiB
or more. After a lost device, the log names the reports whose range covered each faulting page, or the nearest ranges
when none did, and `vaddr-history.txt` beside the log holds the whole history. Stack frames are module offsets: add
the executable's load address (the link map's base) before looking them up in `ocarina.map`. Each bind and unbind
costs a callback, and `=2`'s stack walks enough to hide a timing-dependent fault.
A change to the in-game menu's look (`runtime/ui/menu_skin.cpp`, `option_rows.cpp`, `perf_panel.cpp`) can be looked at
without game files: `python tools/menu_preview.py` builds the menu's own drawing code with the host's clang++ and
writes the Screen tab, the full performance overlay and the boot screen to `build/menu-preview/` (`menu.png`,
@@ -299,6 +351,13 @@ A change to the step Ocarina is given each frame (`runtime/frame_rate.c` `ocarin
display times: a held 60 fps limit gives exactly one frame every frame, a 240 fps limit never less than a quarter
frame, uneven frame times one steady step, and game time follows the clock. No game files.
A change to the mouse camera (`runtime/mouse_direct.c`, the mouse path of `runtime/input.c`, the set `mouse_direct` of
`recomp/patches-v111.txt` or `patches-v143.txt`) passes `python tests\mouse_direct_check.py --cc <clang> --deps
<ucrt64>\include`, which builds `mouse_direct.c`, and `input.c` with `--deps`, with the rest of the runtime stubbed and
calls the camera hooks as their patch sites do, for each game version: the registers a site hands over and gets back,
the same turn for the same mouse distance at every frame rate and stick camera speed, a single count, the idle bit, the
pause after a camera reset, the capture and the mode, and scripted mouse counts. No game files.
A change to which waits a signalled event or an ended thread wakes (`runtime/kernel.c` `wake_sync_waiters`, the
`WaitSynchronization` service) passes `python tests\sync_wake_check.py`, which builds `kernel.c` with the platform
layer and the rest of the runtime stubbed and runs guest threads whose entries are host functions: a signal wakes the
@@ -316,12 +375,92 @@ instead of timing one. No game files.
A change to the button prompts (`tools/make_romfs_patches.py --prompts`, `tools/button_icons.py`) passes
`.venv-py314\Scripts\python tests\romfs_prompts_test.py`, which runs the tool on a RomFS it makes itself (no game
files); a change to the settings passes `nx2navi.exe --probe-cfg`.
files); a change to the settings passes `nx2navi.exe --probe-cfg`; a change to the co-op layer (`runtime/coop*.c`,
`tools/coop_relay.py`) passes `python tests\coop_relay_test.py` and `nx2navi.exe --probe-coop` ([coop.md](coop.md)).
A change to the action prompt's diamond of face buttons (`runtime/action_prompt.c`) or to the SARC and zstd dictionary
helpers (`runtime/sarc.c`) passes `python tests\action_prompt_check.py`. It builds them alone, with the
undefined-behaviour sanitizer, on a layout file, archives and dictionaries it makes from the format `action_prompt.c`'s
header comment describes, and checks that:
- by label every place, cross, flip and bubble moves and no other byte, in every copy of the layout in the archive;
- a second run changes nothing, and by label then by position gives the game's file back;
- a file that is not the expected one is refused and left as it was: one value off, half laid out, one copy of four,
damaged offsets, a pane record laid over the records that lead to another field, more than 16 copies, copies that
share some of their bytes;
- the packed file names the dictionary the original named, found by its id in the pack of dictionaries.
No game files. `--romfs <folder with romfs.bin and index.json>` also runs it on the game's own archive: four copies laid
out, 208 fields, the same dictionary and unpacked size, and no byte changed outside the layout's copies.
A change to what the library warm logs when the driver's cache of stage libraries is cold (`runtime/vk_warm_hint.h`,
`runtime/vk_pipeline.c` `lw_main`) passes `python tests\warm_hint_check.py`, which builds the header alone and checks
the added text by GPU vendor and by why the cache was cold. No game files.
A change to how a run ends when the GPU device is lost (`runtime/vk_device.c` `vk_device_lost_check`, the checks of
`vk_lost` in the replay, upload and present paths, `runtime/vk_sync.c` `completion_main`) passes
`python tests\device_lost_check.py <game exe>`, which runs the executable's `--probe-devlost`: with the device marked
lost no completion callback runs and the submit, upload and wait paths return at once, and four threads that report a
loss at the same moment end the process with exit code 72, one device report and one FATAL line. It needs a Vulkan
device and opens no window; the device is not really lost, so what a driver answers after a loss is not covered.
`device_lost_at = <n>` in `nx2navi.ini` ends a real run the same way at its n-th hand-over to the GPU queue.
A change to the memory gate of the background pipeline builds (`runtime/vk_build_gate.h`, `runtime/vk_pipeline.c`
`gate_enter`) passes `python tests\build_gate_check.py [<game exe>]`, which builds the header alone and checks what it
admits and refuses and that builds under way count through their reservations. With the executable it also runs
`--probe-buildgate` (no device, no window, no build) with the settings in effect, with `build_free_mb = 0` and with a
value no machine has free. What the builders do when they are refused (`warm_builder`, `pipe_worker`, `lb_worker`,
`lw_worker`) shows in a run's log: start the game with `build_free_mb` set above the machine's free commit and read the
`vk_pipeline:` lines that name the commit headroom.
A change to when the pipeline caches are saved in play (`runtime/vk_save_retry.h`, `runtime/vk_pipeline.c`
`autosave_once`) passes `python tests\save_retry_check.py`, which builds the header alone: a save for new content, none
without, and after a save that did not happen a bounded row of tries at the save interval.
A change to how FSR 3.1's pipelines reach the pipeline caches (`runtime/vk_ffx.cpp` `vk_ffx_proc_addr`,
`runtime/vk_pipeline.c` `vk_pipeline_create_foreign`) passes `python tests\ffx_cache_check.py <game exe>`. It runs
`--probe-ffx-cache` (one upscaling context on the device; no window, no game) twice on pipeline cache files of its own
and once with `ffx_pipe_cache = 0`: the library's pipelines must come through the runtime's creates, the second run
must compile none of them, and with the setting off none may come through. The executable needs
`amd_fidelityfx_vk.dll` beside it; without it the probe and the test skip. The graphics driver's own cache can serve
the first run too, so to see the files alone do it, run the probe from a copy of the executable under a name the
driver has not seen: its first run compiles, its second does not.
A change to the start's memory warning (`runtime/mem_need.h`, `runtime/memory.c` `mem_start_note`) passes
`python tests\mem_need_check.py [<game exe>]`, which builds the header alone and checks when the game's need counts
as short. With the executable it also runs `--probe-memneed` (it prints the machine's commit and the answer and
starts nothing) with `mem_need_mb` at 0, at 1 and at a value no machine has, and reads the warning line of the last.
A change to how `pipeline-cache.bin` is read (`runtime/vk_cache_file.h`, `runtime/vk_pipeline.c` `cache_load`) passes
`python tests\pipeline_cache_file_check.py`, which builds the header alone and reads a sparse file just over 2 GB
through it: measured and read whole without a size limit, refused by its real size under one. No game files, no GPU;
about 2 GB of memory for a few seconds.
A change to the layout of `shader-prepared.bin` (`runtime/prp_file.h`, `runtime/gfx_shader.c`
`gfx_shader_prepare_seed`, `tools/make_game.py` `prepared_from`) passes `python tests\prp_file_check.py`, which builds
the header alone, checks the parse of both versions and has `make_game.py` read the list the C side wrote. No game
files, no GPU.
A change to where the lazy write-back is on by default (`runtime/wb_lazy_choice.h`, `runtime/vk_memory.c`
`vk_mem_lazy_decide`) passes `python tests\wb_lazy_check.py`, which builds the header alone and checks the choice and
its reason by platform, by GPU driver and by what the player set. No game files, no GPU.
A change to what writes `nx2navi.ini` outside the game (`launcher/gameini.py`, `installer/ini.py`, `tools/make_game.py`,
`launcher/updater.py`) passes the settings-file tests of `tests\launcher_test.py` (`PlayerIniTest`, and the tests named
`..._settings_file` of `BackgroundUpdateTest` and `MakeGameTest`): a player's file with lines that are no settings of
the game comes through an update and a rebuild byte for byte. The game's own writer, the settings menu, is checked by
`--probe-cfg` with the same lines.
A change to the mouse camera's stick deflection (`runtime/input_map.c` `input_mouse_stick`) passes
`python tests\mouse_stick_check.py`, which builds that file with the rest of the runtime stubbed and checks the
deflection at each camera speed: a slow movement is divided by the factor, a fast flick reaches full tilt. No game
files.
A change to which render passes count as drawn frame after frame (`runtime/vk_target_frames.h`: a draw into one is
skipped while its pipeline builds, a draw into any other waits) passes `python tests\target_frames_check.py`, which
builds the header alone and replays an area change after a loading screen from a player's log: the scene, probe and
half-resolution passes are per-frame again at once, a lookup table, a volume's slices and an icon capture still wait,
and an image taken over by another texture starts without the history of the one before. No GPU, no game files.
The lifter (`recomp/`) and the CPU headers (`runtime/cpu.h`, `runtime/simd.h`) are checked against Unicorn. Every lifter
change passes these, all run with `.venv`:
@@ -347,6 +486,12 @@ Runtime probes, each a mode of `nx2navi.exe` (the list is at the top of `runtime
part of `--probe-vkexec` translate shaders of the census below: they look for `build/<ver>/shaders/jobs.json` of the
exe's own version first, then of the other one.
`--probe-vkmem` also checks CPU-backed texture uploads and rewrites, GPU-written texture aliases, and memory write watches.
`--probe-meshfb` (no game files) draws mesh programs of the runtime's own, with and without a task stage and with
direct and GPU-written workgroup counts, through `VK_EXT_mesh_shader` and through the mesh fallback, and compares the
pictures; on a device without mesh shaders only the fallback draws. A change to `runtime/mesh_fb.c`,
`runtime/vk_mesh_fb.c` or the fallback's part of `runtime/vk_exec_draw.c` passes it. With
`NX2NAVI_PROBE_MESHFB_DIR=<folder>` it converts the game's own task and mesh translations instead, for `spirv-val`
(the top of `runtime/mesh_fb_probe.c` says what the folder holds).
A change to the texture detail (`runtime/vk_texture.c` "texture detail": `detail_skip`, `upload`, `astc_bl_regions`)
passes it three times, with `NX2NAVI_TEXTURE_DETAIL` set to `full`, `reduced` and `low`: each time ASTC textures are
uploaded and rewritten, and every level and layer of their images must hold the game's level it stands for.

View File

@@ -21,6 +21,22 @@ The log names the layout in effect (`input: gamepad layout ...`) and each gamepa
(`input: gamepad "...": first press`); the menu shows the layout under *Automatic*. The game's prompts show the Switch
letters unless *Button prompts* says otherwise (below).
The action prompt (top right) shows the four face buttons as a diamond. The game draws it in the Switch places (A right,
B bottom, X top, Y left), which `nintendo` keeps. Under `xbox`, `playstation` and `auto` the diamond follows such a
pad instead (A bottom, B right, X left, Y top), whatever *Button prompts* is.
The game reads the diamond once at start, before a gamepad is open:
- `auto` gets the Xbox diamond, so a Switch Pro Controller under `auto` sees A at the bottom although its A is on the
right. Pick `nintendo` for that pad.
- A change of layout shows after a restart; until then *Button prompts* says *prompts change after restart*.
- A RomFS mod that changes the action prompt keeps its own diamond. A mod that replaces the same archive for other
reasons gets the diamond moved on top of its changes.
The log says what happened in a line that starts with `action prompt:`. How the layout is changed:
`runtime/action_prompt.c` (`DoCommand_00` in `UI/Layout2Archive/Common.Product.100.Nin_Ounce_NVN2.blarc.zs`, served
from `<profile>/action-prompt/`).
## Button prompts
`NX2NAVI_PROMPTS` (`prompts`, the *Button prompts* row on the Controls tab) picks the buttons the game's prompts show: `nintendo` (default, the game's own), `xbox`, `playstation`, `steamdeck` or `pc` (*Keyboard and mouse*). It changes three things the game draws:
@@ -108,14 +124,18 @@ bind_Y = pad:north, key:mouse_l
## Mouse camera
Mouse motion (raw input) becomes right-stick deflection. Each presented frame takes the counts moved since the last frame, divides by the frame time and sets the deflection to `counts per second * NX2NAVI_MOUSE_SENS / 3000` of full, held for that frame, so the turn rate does not depend on the frame rate. This is not mouselook: the game's stick curve and dead zone still apply, so very slow movements do nothing and a fast flick saturates. The mouse deflection competes with the gamepad and arrow keys by the larger-deflection rule.
Mouse motion (raw input) becomes right-stick deflection. Each presented frame takes the counts moved since the last frame, divides by the frame time and sets the deflection to `counts per second * NX2NAVI_MOUSE_SENS / 3000` of full, held for that frame, so the turn rate does not depend on the frame rate. This is not mouselook: the game's stick curve and dead zone still apply, so very slow movements do nothing and a fast flick saturates. With a camera speed other than 1 (`NX2NAVI_STICK_SENS`) the deflection is divided by that factor before it is limited to full tilt: the turn for a given movement stays the same, and the fastest turn a flick reaches is the game's top speed with the factor in it. The mouse deflection competes with the gamepad and arrow keys by the larger-deflection rule.
`NX2NAVI_MOUSE_SENS` (0 to 10, default 1; higher turns faster, 0 turns the mouse camera and the cursor capture off). While the window is the foreground window the cursor is hidden and confined to the client area. It is released on focus loss, minimise, while F11 changes the window, during a size or move loop and while a text entry is open. Esc releases it by hand: the cursor shows, the mouse camera and mouse buttons stop, and the window can be moved, minimised or closed. A mouse click inside the client area captures it again; that click does not reach the game. Activating the window by a click on its title bar or border does not capture, so it can be dragged or closed right away; Alt+Tab or a click in the client area captures as before. `NX2NAVI_INPUT=none` disables the capture too.
`NX2NAVI_MOUSE_MODE` (`mouse_mode`, the *Mouse camera* row on the Controls tab, live) chooses that right-stick deflection (`stick`) or mouselook (`direct`, the default). In `direct` the camera's input update (`main+0x37c300`) takes the raw counts itself, after the game's stick dead zone, clamp and response curve (`recomp/patches-v111.txt`, set `mouse_direct`; `runtime/mouse_direct.c` `camera_input_oot`). The camera turns by how far the mouse moved, the same on both axes: about 0.08 degrees a count at `NX2NAVI_MOUSE_SENS` 1, at any frame rate and any `NX2NAVI_STICK_SENS`, with no dead zone and no top speed. The game's own camera sensitivity (its Options) scales the mouse as it scales the stick. A gamepad's right stick and the arrow keys still go through the game's response and add to the mouse. While the game takes no camera input (it switched camera input off, or the pause after a camera reset runs) the mouse is the right stick as above. `NX2NAVI_MOUSE_DIRECT_PATCH=0` turns the patch set off, and the mouse is the right stick whatever the mode. `NX2NAVI_MOUSE_TRACE=1` logs each camera input update (the stick, the counts taken and what they added) and, with `dlaa` on (DLAA, DLSS or FSR 3.1, which read the game's camera), the camera's direction in each frame, for measuring the turn per count.
`NX2NAVI_MOUSE_SENS` (the *Mouse camera sensitivity* row, live; 0 to 10, default 1; higher turns faster, 0 turns the mouse camera and the cursor capture off, the row goes down to 0.05). While the window is the foreground window the cursor is hidden and confined to the client area. It is released on focus loss, minimise, while F11 changes the window, during a size or move loop and while a text entry is open. Esc releases it by hand: the cursor shows, the mouse camera and mouse buttons stop, and the window can be moved, minimised or closed. A mouse click inside the client area captures it again; that click does not reach the game. Activating the window by a click on its title bar or border does not capture, so it can be dragged or closed right away; Alt+Tab or a click in the client area captures as before. `NX2NAVI_INPUT=none` disables the capture too.
`NX2NAVI_STICK_DEADZONE` (0 to 50, default 8) is the gamepad stick dead zone in percent of full deflection, the same for both sticks. It is round: a stick inside the circle reads centred, and the rest of its travel is scaled to start at 0 at the edge, so full deflection still reaches full. Raise it for a stick that drifts. The game's own dead zone applies after it. `NX2NAVI_LSTICK_DEADZONE` and `NX2NAVI_RSTICK_DEADZONE` (the *Left/Right stick dead zone* rows under *Analog sticks* on the Controls tab) set one stick each and fall back to `NX2NAVI_STICK_DEADZONE` while unset, so a worn stick can get a larger zone than the other. With a gamepad connected each row shows its stick's deflection now, before the dead zone (*stick now*): let go of the stick and set the row a few percent above the value it rests at.
The stick direction bits (`StickLLeft` to `StickRDown`) are derived from the sticks at 50% deflection. With no gamepad connected the log says `input: no gamepad`.
Keys tilt a stick all the way, so on the keyboard alone Link always runs. `NX2NAVI_WALK_KEY` (`walk_key`, the *Walk key* row under *Analog sticks* on the Controls tab) names a key that, while held, scales the stick values the keys give (movement and camera keys) to `NX2NAVI_WALK_SCALE` of full (`walk_scale`, the *Walk scale* row; 0.2 to 0.9, default 0.51), so Link walks. The value is a key name of the `bind_` lines, or `none` (the default: off). The row offers Shift, Alt, Ctrl, Tab and Caps Lock and names the button a chosen key also presses: with the default bindings Shift is A, Ctrl is B and Tab is Plus, while Alt and Caps Lock are free. The gamepad's sticks and the mouse camera are not scaled. The default is just above half because half of a key's full value falls one short of the 50% the direction bits need. Both settings apply at once while the game runs.
## Nintendo Switch 2 controllers
Windows does not present the Switch 2 Pro Controller as a gamepad SDL can open (the log says `input: no gamepad`), so it needs a bridge program that wakes it and creates a virtual gamepad, for example one that emulates a DualSense: that gives buttons, rumble, gyro and accelerometer. The log then shows `input: gamepad "DualSense Wireless Controller" ... (rumble, gyro and accelerometer, ...)` and `input: motion sensors on`. Bridges that output a DualShock 4 whose gyro and accelerometer never change give buttons and rumble but no motion. Run one bridge at a time; Steam Input can also claim the controller, so close Steam if the bridge does not find it. With several virtual and real gamepads connected the game follows whichever one is pressed.

618
docs/coop.md Normal file
View File

@@ -0,0 +1,618 @@
# Co-op
Each player runs their own game and save; the co-op layer connects the games of up to 8 players through a relay. The
game has no multiplayer of its own and its `nn::socket` stays offline: the layer is a host thread of the runtime
(`runtime/coop.c`) with its own UDP socket.
What exists so far: rooms, the relay, a sealed channel for messages between the players, progress sync (below) and the
menu's Co-op tab (below), which makes, joins, accepts and leaves a room. The other players are not shown in your
world, and where your Link is never leaves your PC ("Other players in the world").
## What joining a room means for your save
Read this before you join a room.
- **Nothing from a room reaches your game until you accept it.** When you join, the menu's Co-op tab and the log name
the other players (each by the name and the key fingerprint their game signed), the room's rules and the key that
signs them; the tab asks you to accept, and the log gives the room's offer a number: `put coop_accept = 1a2b3c4d
into nx2navi.ini [coop] while the game runs`. Accept on the tab or do that. Until then your game takes nothing from
the room. You accept players by
their keys, not their names: a new player, a player whose game restarted, a removed player who comes back, or a
second player with a name you know is a new offer, and so are a key you accepted that now carries another name (it
is accepted under the name it had when you accepted it), other rules, rules signed by another key, and another
save loaded in the room; nothing more is taken until you accept that one too. A key you accepted that comes back
under its own name as another member number (the relay numbers players as they come) is no new offer; the log says
so, and it says when a member presents another key than the one it was identified by. A player in the room whose game never
says who it is keeps the room from being accepted at all. The number is random for each start of the game, so nobody
can put the right one into a file in advance. Accepting every room without asking (`NX2NAVI_COOP_ACCEPT=always`)
works only from the environment, never from `nx2navi.ini`.
- **Your game takes values only from players you accepted.** What a player you did not accept sends is not kept, not
passed on and never applied, also after that player leaves or is removed. Every message that can change your save is
signed by the player who sent it, so this holds also against someone who knows the room's secret and runs the relay,
or sends from its address on your network: they can make no message in another player's name that changes your save.
For story flags and items acceptance is passed along: a player you accepted hands on what they took from the players
*they* accepted, so a stranger someone else let in reaches you through them. Pools are not passed along: your game
counts in a pool only what you and the players you accepted brought, picked up and spent, and joins the pools only
once you accepted the room (another save loaded in it joins only once you accepted that one too). What remains with
the maker: a player uses the pools at all only once the maker's game admitted them, which it does for every player
the maker accepted; a player who left before you accepted is not counted in your pools; and while a player you
accepted counts a stranger in their pools, what they claimed when they joined a pool counts that stranger too, until
the maker removes the stranger.
- **Your save is copied first.** The moment you accept a room, the game copies your whole save (every slot) to
`coop-backup/` in the profile folder, and takes nothing from the room until the copy is made. The first copy for a
room in each start of the game is `first-<date-time>` and is kept until you delete it; later copies (another save
loaded in the room, say) are `<date-time>`, of which the newest eight are kept. A room the relay lost and that the
game reaches again is still accepted and copied. "Going back" below says how to restore a copy. A game that has
not saved yet has no save on the disk to copy: it takes nothing from the room until it has saved once (the log says
so), and a copy that cannot be written keeps the room closed as well.
- **What the room can change in your save** is what its rules share (progress, items, songs, quest items; small keys,
rupees and ammunition in a pool): every value is checked against your game's own table of flags before it is
stored, passed on or applied. A flag can only be set to "done", an item count only up to 999, small keys only up to
15, a pooled counter only within its capacity. Anything else is dropped, counted in the log, and a player who sends a
few dozen of those is ignored for as long as they stay in the room.
- **What a player you let in can still do.** A player in the room plays with you: with progress shared, what they do
in their world (open a chest, beat a boss, set a story flag) happens in yours, and a player who wants to can send
such flags without playing for them. With small keys in a pool, a player you accepted can spend the keys you share:
their spends count at most up to what entered the pool (what the players brought and picked up), so they can empty a
dungeon's pool, and the keys picked up after that, but no more than the dungeon has, and a record that claims less
than nothing counts as nothing. The maker's removal of that player, also after they left, or a pool reset after they
left, gives back what they took, in every game, and each game makes its claim to the pool again as if that player
had never been in it, so keys you brought while their gains were in the pool stay yours, and a claim made while
their spends were in it does not leave the pool fuller than what the others brought. A pool reset while that player
is still in the room carries what they took into the new pools, and removing them afterwards does not give it back:
remove first, then reset (the reset's log line, the maker's hint and the Co-op tab's Reset the pools say so). Keys a
removed player's gains handed out stay as doors already opened, and in the claim of a player who saved with them and
joined the pools again with that save before the removal. With rupees or ammunition in a pool (off by default) the
same holds for them.
Flags stay set when a player is removed. None of this can be undone inside the game otherwise: go back to the copy
of your save. Invite only people you trust with your save, as you would hand them your controller.
- **Who can get in.** Only someone who knows the room's secret: 18 characters (85 bits) that the game makes when a room
is made and that the maker passes on to the others (by voice, a chat message). The relay never learns it. Someone who
sees your traffic on the network, or who runs the relay, cannot read the messages, change them, make new ones or
guess the secret from them. Someone who also knows the secret can read the room's messages, but can still make none
in a player's name: each player signs what they send with their own key.
- **Removing a player.** The room's maker can remove a player by their key's fingerprint, which the log and the Co-op
tab show beside each member (Remove on the player's row of the tab, or `coop_remove = <fingerprint>` in `nx2navi.ini`
while the game runs; while they are in the room or after they left): the maker's game signs the removal, every game drops that player's key and keeps it
dropped (their messages are ignored, their pool records dropped, so what they took from a pool comes back), and the
relay drops them and refuses them again (the session the maker's game listed for them at that moment, so a player
given the number since is not the one dropped). A member number in the file is not taken, since numbers pass to other
players as members come and go, and each value acts once, so a line left in the file or read again after a moment in
which the file could not be read removes nobody else. Someone who knows the secret can still come back under a new
key (everyone then gets a new offer to accept or not); to be sure, make a new room, which has a new secret. The maker
can also reset the pools (`coop_reset_pools = 1`, then 2 the next time, or 0 and then 1 again): every game joins them
again with what they held for the players in the room, which recovers a pool that a player who left had emptied,
also when the maker resets twice before the games joined again. What a game held at the reset is its claim from then
on, also while that player is at the title screen, so a key another player picks up after the reset comes on top of
it. A player who is not in the room at the reset, or whom the maker has not admitted to the pools yet, is carried
for nobody: what it brought and picked up leaves the other games' pools until it plays again in the room, when its
game joins them with what it holds. If the maker resets again before such a player's game joined, that game keeps
the larger of its two carries, so keys the others used in between can come back (more keys, never fewer). Remove a
player who emptied a pool and is still in the room first (both lines in one save of `nx2navi.ini` act
in that order). The key the maker's game signs the room's rules and
removals with is kept in the profile folder (`coop-keys/`, readable by your account only: the folder 0700, the file
0600 on Linux; on Windows an access list of its own with your account alone), so a maker whose game restarted is still the room's maker. That file, together with the room's
secret, lets whoever has both act as the room's maker: never hand out a copy of your profile folder. A game that sees
another member present its own key says so in the log (that member stays not identified, so nobody can accept the
room while it is there), and a key file that is damaged or cannot be read is logged too. Deleting the file ends your
say over rooms you made before.
### Who can see what
| Who | Sees | Cannot |
|---|---|---|
| The relay's operator, and anyone on the network path | that a room exists (a random id and the locator, a value derived from the secret that does not give the secret back), the players' names, their IP addresses, when and how much they send | read, change or make any message between the players; learn the secret; change anyone's save or the room's rules (moving the relay's maker mark changes nothing for a player who accepted). It can drop, delay and send again what a player sent; a player takes one again only as "Replay" below says. |
| Someone who knows the secret and runs the relay, or sends from its address on your network | all of the above, and every message of the room | make a section, identity, pool record or set of rules in another player's name that a game acts on (each is signed by its maker); change your save other than through a player you accepted, or the rules of a player who accepted. It can also: send a member's messages again (see "Replay": within the last 64 they are refused, but four older ones in a row let it send the member's whole present session again); seal a message in a member's name with a counter far ahead, which costs a player that member's next three messages, each time it does so (one after every three of the member's keeps them out while it keeps sending); send rosters, or identities of another key for a member's session, that keep players from being identified or the room from being accepted while it keeps sending and up to 10 s after; send sections and digests in a member's name that use up what a player checks and takes from that member (128 signatures and 48 KB a second), which delays that member's own while it keeps sending; send digests in a member's name with sums of its choosing (see the sync messages); and, to a player who has not accepted the room yet, make every member's digest carry rules of a key of its own (a member does not sign its digest, only the rules in it are signed, by whoever made them): with no maker in the room, or one it controls, that player's game shows those rules and their key in the offer, so compare that key with the maker's before you accept (step 3 below). None of that changes a save, and none of it lasts longer than said once it stops |
| The other players in the room | your name, your progress (what the rules share), your messages | your IP address (the relay forwards everything), your account or profile (the id the relay knows you by is random for each start of the game and never shown to them) |
| Your log and "Copy system info" | a three-character label hashed from the room's secret (no part of the secret) and the offer's number; system info shows that `coop_room`, `coop_server`, `coop_name` and `coop_accept` are set, not their values | the secret, the relay's address (it appears only with `NX2NAVI_TRACE=coop`) |
### Going back to your save from before a session
1. Close the game.
2. In the profile folder, open `coop-backup` and pick the copy to go back to: `first-<date-time>` is the save as it
was before you first accepted that room, `<date-time>` a later acceptance (the time is UTC).
3. Delete the folder `save-tx` (it may hold a save that was being written; it would otherwise be finished over the copy
at the next start).
4. Move the folder `save/<numbers>` aside (keep it until you are sure), and copy the contents of the backup folder into
a new `save/<numbers>` of the same name.
5. Start the game: every slot is as it was when you accepted the room. Progress made after that, in any slot, is in the
folder you moved aside, not in the copy.
## The menu's Co-op tab
The menu (F1, or the pad's combo) has a Co-op tab, usable with the keyboard, the mouse and a pad.
- **Not in a room:** your name and the relay's address (each row opens a field to type in; with a pad, A on the field
brings up the system's on-screen keyboard where it has one), Make a room, Join a room (a field for the secret, in any
case, with or without dashes, and a Paste button that takes the clipboard's text), a line that says what the layer is
doing or why it stopped (no answer from the relay, no room with that secret, refused), the rules of a room you make,
and the co-op switch. Make and Join turn co-op on when it is off.
- **In a room:** while the room waits for your answer, who is in it (a player whose game has not said who it is, or
whose session two keys present at once, is marked "not identified"; a player whose key you accepted under another
name is marked "a key you accepted as <that name>", and that is a new offer), what its rules share, the fingerprint
of the key that signs the rules, to compare with the one the maker reads out to you by voice or chat, and Accept or
not; while any player is not identified the tab says so and why the room cannot be accepted, and Accept is greyed.
Then the players, with who made the room, how long ago each was last heard and each one's key (and the name you
accepted it as, when it now signs another); the maker sees its own key to read out, and Remove on each other
player's row, which removes by the key (a player who is not identified has no key and is removed by member number,
only while the same session still holds it). The maker also has a Pools group: every key that took more from the
pools than it brought, in the room or not, with what it took and a Remove of that key, and Reset the pools, which
says to remove such a player first. What it took can change, up or down, when the maker removes a player or a
player accepts more keys, also while that player's game is at its title screen. Then the
room's secret, hidden until you press its row, and a row that copies it to the clipboard; the rules (the room's
creator changes them, everyone else reads them; a change is a new offer for everyone); Leave the room. The status
line says when the relay lost the room and the game is getting back into it, and when the relay takes no more joins
from your network and the game tries again in a minute.
- **Nothing is accepted, removed, reset or left by accident.** Accept or not, Remove, Reset the pools and Leave each
open a window whose cursor starts on the safe button (Not now, Cancel, Stay), whenever it opens; only Right reaches
the acting button, and pressing the button that opened the window again, holding it, or a double tap lands on the
safe one. A new player or other rules while the Accept window is open replace what it shows and put the cursor back
on Not now: Accept takes only the offer you read. The window says that your whole save is copied to `coop-backup`
first, and before your first Accept in each start of the game it shows the three warnings of "Before you join a room
with strangers" below.
- **While the menu is closed** a short note at the top of the screen says when a player joined or left the room and
when the room waits for your answer.
- The name, the relay, the rules and the switch are settings (written to `nx2navi.ini` like every row); the secret is
not a setting, is not written to the log, and is shown only when you ask.
## Running a relay
```
python tools/coop_relay.py [--host 0.0.0.0] [--port 24680] [--log-addrs] [--log-joins] [--max-rooms 1000] [--rooms-per-network 8]
```
Python 3, standard library only. A player who can reach it by UDP (forward the port on the router, open it in the
firewall) is all it takes; the others put its address into `coop_server`. The relay forwards the sealed datagrams of a
room and can read none of what the players send each other. It keeps only who is in which room, writes nothing to
disk, and loses its rooms when it stops: the room's maker makes it again under the same secret. Its log has one line
per room made, join, leave and removal, with names, member ids and a random room id (never the secret or the locator);
addresses only with `--log-addrs`; a line when a network's joins ran out (at most every 10 s); and with `--log-joins`,
where each network's joins went.
- A room holds up to 8 players, is closed 10 minutes after the last one left (a minute, if nobody but its maker was ever
in it), and a player the relay has not heard from for 15 s is dropped (the member id is kept for a minute so that the
same game, with its rejoin token, joins again as the same member).
- The roster (who is in the room, each one's session, which one made it) goes out at a change, again 0.25 s and 0.75 s
later, and every 5 s: a datagram is lost now and then, and nothing is acknowledged.
- Limits: a source address answers a cookie challenge before the relay sends it anything larger than it sent; each
member is limited to 200 datagrams and 64 KB per second, a datagram forwarded to seven counted seven times; each
network (an IPv4 /24, an IPv6 /48) to 20 challenges a second, a join every 3 s after a burst of 20, and 8 open rooms;
each room that forwarded to someone in the last 2 s to an equal share of the forwarding (rooms that send nothing, or
send to nobody, take nothing); the relay as a whole to 5000 challenges a second and 8 MB/s of forwarding. A join
attempt costs its network one join whatever the answer, and the same attempt sent again (its answer was lost, or it
asks again for a room that is not there yet) is answered from memory without a charge while the answer is the same
refusal; the game asks for a room that is not there at most every 10 s and, while it keeps its room, waits a minute
when the relay refuses it for its network's joins instead of ending the session, so players behind one address who
wait for a room do not use up each other's joins. The relay keeps the budgets of at most 4096 networks and forgets a
budget that is full again, and checks its own challenge budget first, so a flood from spoofed addresses leaves no
state behind. A member that rejoins with its token from its own address and in its own session needs no challenge;
from another address, or with a new session (every rejoin draws one), it answers one first, so someone who saw its
CONNECT cannot take its place. The challenges for a CONNECT with a member's valid token come from that member's own
challenges (2 a second, 8 at once, kept apart for its own network and for the others), never from its packets, and
from a share set aside for rejoins: 1000 a second split equally among the open rooms for CONNECTs from other networks
than the member's, and 1000 a second split among the rooms and then among the eight member numbers of each for
CONNECTs from the member's own network (each 8 at once at least, so a member can rejoin eight times at once even on
a relay with its full 1000 rooms, and then once every 8 s). So the tokens of rooms someone made to flood with take
only those rooms' shares, and a flood of CONNECTs with a member's token, someone else's or seen on the way, from
another network neither drops the member's messages nor keeps its rejoin from its own network out of the room. What
such a flood can take is the room's share for other networks: a member that comes back from another network (a
phone that changed networks) may wait for as long as it lasts, and so may one whose own network someone sends from
with its token. A game whose roster shows
another session for it joins again, at most once
every 15 s. A session that was in the room before is refused (the last 4096 of each room are kept). A flood from many
networks can still use up the relay's 5000 challenges a second for newcomers: a relay has finite capacity, and its
operator's firewall is the place for more.
- `--host ::` listens for IPv6 as well as IPv4. The game's own socket is IPv4 and IPv6 in one; Windows may show its firewall
prompt the first time the game opens it.
## Rooms and secrets
A room is its secret: 18 characters of `23456789BCDFGHJKMNPRSTVWXYZ` (no vowels, no 0/1/O/I/L), typed in any case,
with or without `-` and spaces, shown `XXXXXX-XXXXXX-XXXXXX`. The game makes a new random one for each room it makes;
`coop_room` names one for `coop_auto` (tests, LAN parties). A create of a secret whose room is open on the relay is
refused (it is not a join), so nobody can be put into a room they did not mean to join.
## Settings
`nx2navi.ini`, section `[coop]` (`nx2navi.ini.example` has the text); the environment variable is the key with `NX2NAVI_`.
| Key | Default | |
|---|---|---|
| `coop` | `0` | on or off, at once; off: no socket and nothing running |
| `coop_name` | empty | at most 24 bytes; empty: `Player-` and four random hex digits |
| `coop_server` | none | `host`, `host:port` or `[v6]:port`, default port 24680; with none set the layer stays idle and logs why |
| `coop_port` | `0` | local UDP port, 0 = any; read at start |
| `coop_accept` | `ask` | `ask`: nothing from a room is applied until its offer is accepted; a number (the eight hex digits the log shows, random for each start of the game): accepts that offer, set while the game runs (the file's line as it is now counts before the one read at start); `always`, from the environment only (`NX2NAVI_COOP_ACCEPT=always`; an `nx2navi.ini` line is ignored): every room is accepted (the save is still copied first) |
| `coop_auto` | `off` | `create` or `join` starts a session at launch (a join needs `coop_room`); no menu row |
| `coop_room` | empty | the room secret of `coop_auto`; no menu row |
| `coop_remove` | empty | the room's maker removes a player by its key's fingerprint (in the room or after it left; the relay drops it too while it is in the room); each value acts once; a member number is not taken from the file; the Co-op tab's Remove does the same |
| `coop_reset_pools` | empty | the room's maker resets the pools when the value changes to a new one other than `0` (1, then 2; or 0, then 1 again); the Co-op tab's Reset the pools does the same |
| `coop_drop` | `0` | test: percent of received datagrams thrown away; no menu row |
| `coop_test_set` | empty | test, environment only (`NX2NAVI_COOP_TEST_SET`): `hash=value@frame,...` sets those flags (hash in hex) at those frames of play; an `nx2navi.ini` line is ignored |
| `coop_progress` ... `coop_ammo` | see below | the rules of a room this player makes (Progress sync) |
With `coop_auto` a room the relay lost (it restarted) is made again under the same secret by its maker, or waited for,
for as long as the session runs (asked for every 10 s; a refusal for the network's joins waits a minute); a maker who
finds it made again by someone else joins it, and the rules stay the ones its key signed. A player who leaves ends the
session. An `nx2navi.ini` someone else gave you can name a room and join it at launch (`coop_auto`, `coop_room`), but
it cannot accept the room for you: that needs the number of this start of the game, or the environment. The game reads
`coop_accept`, `coop_remove` and `coop_reset_pools` from the file as it is now once a second while it is in a room
(never out of one), as it reads the file at start (a BOM, a repeated key's later line, quotes), and skips a reading
when the file cannot be read or is empty for a moment, as while an editor saves it; values in the file at start, and
at the first reading after the start, act on nothing.
## Progress sync
When one player gains progress, the others' games gain it too, while they play; a player who joins later catches up
with everything the room has, and the room with what the joiner brings. Each player's own save keeps what it got: the
game saves it as its own progress.
The game keeps its progress as flags (a database keyed by 32-bit hashes of flag names). Between two frames the runtime
reads the flags that changed, and sets the ones the room has and this game lacks through the game's own set routines,
as if the player had done it. Nothing is read or set while the game is on its title screen, loading a save or changing
scene, and not while its clock stands (the pause menu): what arrives meanwhile is set afterwards. A chest or a door
another player opened shows open the next time the area loads; an item shows in the menu the next time it opens.
What one room merged belongs to that room and that save: leaving the room, joining another, or loading another save
forgets it. A save loaded while in a room is a new offer: nothing reaches it before you accept again, and the save is
copied again first. Once accepted, it gets the room's progress, and that holds what every save played in the room
brought, the last one's too (the others hold it); no way exists to tell one save's flags from another's in a merged
state, so the new offer and the copy are the answer.
### What is shared
| Category | Rule key | Modes (default first) | What |
|---|---|---|---|
| progress | `coop_progress` | `shared`, `own` | story, world and dungeon flags: events, talks, chests, doors, switches, bosses, map and compass |
| items | `coop_items` | `shared`, `own` | equipment, key items, bottles owned, wallet, bag and quiver sizes, magic meter size |
| songs | `coop_songs` | `shared`, `own` | |
| quest | `coop_quest` | `shared`, `own` | medallions, spiritual stones, the stone of agony, the gerudo card |
| keys | `coop_keys` | `pool`, `own` | small keys, per dungeon |
| rupees | `coop_rupees` | `own`, `pool` | |
| ammo | `coop_ammo` | `own`, `pool` | bombs, bombchus, arrows, deku nuts, seeds and sticks, magic beans |
- `shared`: a flag set by anyone stays set for everyone; of a count (an item, an upgrade) the highest wins.
- `own`: not synced; switching to it stops the merge and keeps what was merged.
- `pool`: one count that every player adds to and spends from. Each player's gains and spends are counted apart (in a
record their game signs) and add up, so two players spending at once both pay; a pool that two spends at once took
below zero shows 0 and the next gain pays the debt first. A player's spends count only up to what that player gained
plus the counter's limit (999 rupees or ammunition), and never beyond what entered the pool (the highest count a
player brought, at least 0, plus every gain): nobody takes more than the pool really had, so a dungeon's key pool
loses at most the keys that dungeon has, and in a rupee pool a player who spends more than 999 rupees beyond what they
gained is not charged for the rest; a count brought below zero counts as zero, so no record turns the others' keys
into a debt. A joiner whose count is higher raises the pool to it; a game that restarts and rejoins does not add its
count again; a game that joins a pool in debt (as a drain leaves it) pays the debt with its count, so the count comes
back with the drainer's removal. A pool above a counter's capacity shows the capacity. Each game counts in its pools
only the records of the players its player accepted, and its own; it stores and passes on every admitted record, so
the games hold the same records, and games whose players accepted the same players show the same pools. A game joins
the pools once its player accepted the room and the maker's game admitted its key, which it does for each player the
maker accepted (up to 24 keys per pool reset); until then its counts stay its own.
- Small keys in the pool: a key anyone picks up goes into the dungeon's pool, a door anyone opens takes one out, and the
pickup and the door are progress, so they are gone and open for everyone. Two players who each used the last key
on a different door at the same moment open one door more than the keys paid for.
- Items, songs and quest items can be `own` only with `coop_progress = own`: in a shared world a chest one player
opened is empty for the others. With progress `own`, keys are `own` too (each world has its own doors). A room's maker
whose settings break this gets the nearest valid set, and the log says which.
Never shared, by design or because no reliable way exists yet:
- Where Link is, his health (the game republishes it from the player several times a second, so it cannot be set
through the flags), the magic in the meter (likewise outside the flags), the time of day (the clock runs in the
game's world manager, not in a flag), bottle contents and the equipment worn.
- Heart containers and pieces and gold skulltula tokens: most of their pickups are flags of single objects in the world
that this layer does not write, so a shared count would pay one piece or token twice; the reward flags the game names
for them stay with each player too, so everyone can collect them.
- Items the game takes away again (the trade sequence, rented masks, the knife that breaks, amiibo items): a shared
highest count would hand them back.
- Flags that the game itself resets at a scene change, a new day or a load, and counters that are not progress (puzzle
positions, minigame records, enemies defeated).
### The room's rules
The rules belong to the room: every game in it merges the same way. They are the settings of the player who made the
room, signed with that player's key: a game takes rules only signed by the key its player accepted (pinned at the
first acceptance in the room). Before that, a game that made the room itself takes its own; otherwise it takes the
key of the player the relay marks as the maker, but only while no other player carries rules signed by another key
(the relay's mark cannot outvote the rules the players' digests carry, and a mark the relay puts on your own name does
not make you the maker); with no maker in the room it takes the rules every member's digest carries. A member does
not sign its digest, so before you accept, someone who knows the secret and runs the relay can make every member's
digest to you carry rules of a key of its own, which your game then takes (with no maker in the room, or a maker it
controls): the offer shows the key that signs the rules, and comparing it with the maker's is what tells you (step 3
of "Before you join a room with strangers"). When the members' rules disagree it takes
none, applies nothing, and the log and the offer say so: ask the maker which key fingerprint is theirs. No other
player's settings are used, and a member the relay marks later (after a restart, or a relay that lies) changes
nothing for a player who accepted; the offer then says that the relay names another maker. The signed rules travel
with the sync messages, so a joiner and a game that rejoins after a relay restart get them from anyone. If the maker
has left, the players keep the rules they have. The maker can change a rule during the session: switched to shared or
pool, the category merges from then on (after each player accepts the new offer); switched to own, it stops, and
nothing already merged is taken back. A maker whose game restarted keeps the room's key (from `coop-keys/` in the
profile), takes its own rules back from the others and can change them, remove players and reset the pools again.
### Messages
Sync rides in the room's sealed messages. Each game sends a digest (a sum per section of its state, and the rules)
every 2 s and at once to a player who joins; a section whose sum differs is sent to that player, so lost messages are
repaired and a late joiner catches up within a few seconds. A change goes out at once and again 80 and 250 ms later.
Sending is paced at 32 KB/s, under the relay's limit per member, with the players who asked for sections served in
turn (one that asks for everything all the time gets its share, not all of it), and each game takes at most 48 KB/s
from any one player. Games merge only with the same schema: this layer's version, the game's version, and the whole table of what
is shared and up to which value, so two builds that classify a flag differently do not merge.
## The room's secret and the wire
For a reviewer: what is derived from what, what each datagram carries and what a receiver checks. The code is
`runtime/coop_proto.c` (C) and `tools/coop_relay.py` (the relay's side, Python); `tests/coop_vectors.txt` holds byte
vectors of every message that both are checked against.
**Library.** Monocypher 4.0.2 (`runtime/third_party/monocypher/`, two files, unmodified, BSD-2-Clause, dual-licensed
with CC0) for BLAKE2b and XChaCha20-Poly1305. It is small, has no dependencies, builds the same on Windows and Linux,
and its primitives are standard (RFC 7693, and the XChaCha20-Poly1305 construction of the IETF draft). It is used only
in `coop_proto.c`, behind four functions (`coop_room_keys`, `coop_seal`, `coop_open`, and BLAKE2b inside the first), so
another library can replace it there; the sync layer's signatures (EdDSA over Curve25519 with BLAKE2b, the library's
`crypto_eddsa`) go through `coop_sign_keypair`, `coop_sign`, `coop_sign_check` and `coop_blake2b` there too. The relay
needs no library: it uses Python's own BLAKE2b and HMAC.
**The secret.** 18 symbols, each drawn uniformly from 27 (bytes from the operating system's random source, a byte
below 243 taken modulo 27): log2(27^18) = 85.6 bits. It is made by the client that creates the room and never sent to
the relay or written to a log; players pass it on themselves.
**Derivation.** With `S` the 18 canonical ASCII characters as the key of BLAKE2b:
- locator `L` = BLAKE2b-128(key `S`, "nx2navi-coop/2 room"): the relay's name for the room, and the key of the tags of
datagrams between a client and the relay. The relay and anyone who sees a CONNECT learn `L`; getting `S` from it is a
search over 2^85.6 secrets.
- message key `K` = BLAKE2b-256(key `S`, "nx2navi-coop/2 messages"): seals every message between the players. Only
holders of `S` have it.
**The client and relay datagrams.** A 24-byte header (magic, version 2, type, the relay's room id, src, dst, length,
sequence) and an 8-byte tag, HMAC-SHA256(`L`, header[0:16] ‖ payload)[0:8]. CONNECT carries `L`, a client id (random
for each start of the game), a session (random for each join), a nonce (random for each attempt), the name, the
relay's cookie and the rejoin token. CHALLENGE, JOINED and ERROR echo the nonce and carry `L`'s tag; the client takes
only answers with its own nonce and its own `L`, so a datagram someone else sends from the relay's address neither
ends an attempt nor puts the player into another room (an untagged "protocol version" error is taken only as the
first answer of an attempt). JOINED carries a rejoin token, random per member: the relay gives a member's id (and the
maker's mark) back only to a CONNECT with it. The ROSTER lists each member's id, flags (away, maker), session and
name. KICK (maker to relay) names a member and its session. These datagrams are authenticated against outsiders who
do not know `L` only; the relay and an observer of a CONNECT can make them, which lets them disturb the session
(drop, reorder, invent members that cannot speak), not change a save. So a roster is taken only up to 2^20 ahead of
the last one's number (the relay's counter moves with its own datagrams), and after the silence time and 4 s without
a roster taken, the next one counts whatever its number, so one forged far ahead does not cut a player off; no roster
ends a session for progress sync (a session ends only when its member's identity in a later one names it, below), and
neither does a relay that says the room is gone; a roster that lists another session for this player makes it join
again at most once per 15 s, and its game keeps signing for the session it joined with. A relay or observer that keeps
sending rosters changes the roster for as long as it sends, as it can drop datagrams for as long as it likes.
**The player message envelope** (the payload of DATA, version byte 1):
```
u8 envelope version (1) | u64 sender's session | u32 counter | XChaCha20-Poly1305 ciphertext of (u8 kind, message) | u8[16] tag
nonce (24 bytes) = session (8, LE) | counter (4, LE) | sender's member id (1) | 11 zero bytes
associated data = destination member id, envelope version
```
A session is drawn for every join and the counter starts at 1, so a nonce never repeats under `K` (two sessions
collide with probability about n²/2^65). The kind byte and the message are inside the ciphertext: a new kind of message
(a pose, say) needs only a number, and a later envelope version can change the outer fields without touching the
messages. A message is at most `COOP_MAX_MESSAGE` = 1146 bytes after its kind.
**What a receiver checks, in order:** the sender is in the roster and is not itself, the destination is it or
everyone, the envelope's session is the one the roster lists for that sender, the counter is new within a window of
the last 64 of that session, the tag opens with `K` for that sender and destination; only then is the counter recorded
and the message delivered. A counter older than the window is refused, unless it opens and is the fourth of that
sender's messages in a row below the window, each later than the one before: then the window starts again from it and
it is delivered. `K` is the whole room's, so whoever knows the secret can seal one message in a member's name with a
counter far ahead, which leaves that member's later messages below the window; the member's next four start it again,
and the first three of them are lost. That is per forged message: one sent again after every three of the member's
keeps that member's messages from a player for as long as it keeps sending.
**Replay.** A message recorded before a player joined again carries the old session, which the roster no longer
lists: refused. Within a session the window refuses only what it still remembers: a message sent again within the
last 64 it took is refused, and an older one alone is refused too. But four older ones in a row, each later than the
one before, start the window again (that is how it recovers from a counter far ahead), and from then on the window
has forgotten what it took: anyone who recorded a member's messages of its present session (the relay too, without
the secret) can have every one of them delivered again, in order. Someone who knows the secret can also seal a
recorded message again under a new counter. So the envelope does not make a message arrive once; a layer for which a
repeat matters checks a counter of its own. A sync section carries its sender's own counter inside its signature for
that: a section is taken once, and only within the last 64 of its sender's session; a digest taken again repeats what
it said (until its sender's next one, 2 s later). A relay that lists an old session in a forged roster could replay
that session's messages to a player whose game never saw the session end; they are messages the sender really signed,
and sync messages only raise values, so this brings nothing new into a save.
**The sync messages (version 4).** `runtime/coop_state.c` has the byte layout. Each game makes a signing key for each
room and start of the game (EdDSA, from a random value of the start and the room's secret, so nothing ties a player
across rooms; the maker's from 32 random bytes kept in the profile for that room, mixed with the secret, so that it
outlives a restart) and sends in every DIGEST its identity: the key, its name, the session it held in the room before
this one (0 none) and a signature over the room's context (BLAKE2b-128 keyed with the secret), its member id, the
session it joined with and that session before. A game takes values only from a member whose identity checks out; an
identity belongs to one session, a session a member's later identity names as the one before is never taken again
(the latest 1024 of each key the player accepted are kept apart, where no other member's churn removes them; the
others share the last 65536), and a key another member holds is refused, so an identity cannot be copied to another
member or slot; the relay also refuses a session that was in the room before. An identity of another key for a
session that is identified already (only one of them is the member's) makes the game take that member as neither
while both are presented; once one of them has not been presented for 10 s, the other takes the place. Only the key's
holder ends its sessions
that way: a forged roster, a relay that says the room is gone, or a replayed message or identity ends none. A game
announces its identity at once when its session changes. A name is checked as signed and shown cleaned (control and
reordering characters replaced). Every SECTION (a push of a change or an answer to a digest) ends with its sender's
counter (8 bytes) and its signature (64 bytes) over "nx2navi-coop/4 section", the room's context, the sender's
member id and session and the section's bytes, checked against the identified key before anything of the section is
stored, applied or passed on: 72 bytes and one signature per section whatever it carries, about 35 µs to sign and
100 µs to check one (measured on the runtime's -O2 build of Monocypher on an x64 desktop). Flags are taken only from a
member whose key the player accepted. The DIGEST also carries the
maker's charter: the rules, the keys admitted to the pools (8-byte key ids), the last 16 keys removed and the pools'
epoch, with an epoch the maker raises at each change (saturating at 2^32−1), signed by the maker's key; each game
keeps every removal it saw in the room. A pool record (one per contributor and pool) carries the contributor's key,
the pools' epoch, a sequence number, its base, gains and spends, and its signature; a game keeps the record with the
highest sequence of each key (its own too: a room that comes back hands it its own newest record) and stores only
records of admitted keys of the current pools' epoch, checking the signature before it stores or passes one on; its
pools count only the records of keys its player accepted, and its own. A game remembers (in memory) its last 8 joins
of each pool in the epoch, each with what it joined with and the records it saw then; its base is the highest of
their claims, each made as if the game had counted then the keys it counts now, and made again whenever that changes
(a removal, or its player accepting more). An older join keeps the claim it had when the ninth was made, so after
nine saves loaded in one pools' epoch (a game over and continue counts) a removal leaves that claim as it was until
that save is loaded again. A reset carries this game's own claim as it would be with only the players the reset
admits, and the game signs it at once as its record in the new epoch (a game the reset does not admit claims it when
it joins). A digest's sums are not signed: a forged one can make a game send its sections or join a pool before it
heard every record, as dropping messages can.
**Rules and the maker.** A game takes a charter signed by the key its player accepted; before any acceptance, its own
for a room this session made; else by the key of the member the relay marks as the maker while no identified member
carries a charter of another key; else, with no maker in the room, by the one key every identified member's charter
carries (each member's first digest is waited for, up to 5 s, so the quickest does not win). A charter of the same key
counts only with a later epoch.
**Per-member limits in each game.** Every value is checked against the local table before it is stored, passed on or
applied; at most 48 KB/s is taken from one member; 32 refused flags, or pool records whose contributor's signature
fails, in sections that member signed, and the member is ignored while it stays. Nothing that fails inside a digest
counts against the member it names (an identity, a charter in the maker's name), and neither does a section whose
signature fails: anyone with the secret can send either in its name. A pool record this game cannot count is dropped
without counting against its sender, since an honest member may hold a newer charter for a moment. A signature check
that failed is not made again for the same signature, key and signed bytes (a changed copy of a genuine message fails
on its own and leaves the genuine one to be checked), and each member gets at most 128 signature checks a second (256
at once), sections' included;
the register index is keyed (SipHash-2-4 with a random key of the process); a pool stores at most 24 records (the
admitted keys), a record's base, gains and spends are at most 2^20 either way, and nobody but a record's key holder
can make or change it. Without the system's random source (no client id, session, nonce or key a stranger cannot
guess) co-op stays off.
## Before you join a room with strangers
1. **Keep a save you can go back to.** Join only with a save you are ready to restore from
`coop-backup/first-<date-time>`. Anyone you accept can set story flags in your save, and so can anyone a player you
accepted let in. A player in your pools can empty a dungeon's small keys while they play; the maker's removal of
that player, or a pool reset after they were removed or left, gives back what they took, but no removal takes a
flag back, and a reset while they are still in the room keeps their drain: remove first, then reset.
2. **Your acceptance is yours, the room is not.** A player you did not accept reaches neither your flags nor, by
themselves, your pools, also when they know the secret and run the relay. But the players you accept pass on the
flags of the players they accepted, a player you accepted who counts a stranger in their pools claims against a
pool with that stranger in it until the maker removes them, and the maker alone decides who may use the pools at
all. If anyone you do not know is in the room, even one you declined, do not accept: leave, and ask the maker for a
new room (a new secret) for the people you know.
3. **Check the keys, and keep yours to yourself.** Before you accept, compare the fingerprint of the key that signs
the room's rules with the maker's, and each player's with that player's, by voice or chat: a name is what a member
says it is, and someone who knows the secret and runs the relay can hold back a player's own identity and show its
own key under that player's name and member number until that player's arrives. Never start the game with
`NX2NAVI_COOP_ACCEPT=always`,
or with a script or `nx2navi.ini` someone hands you. Never hand out a copy of your profile folder: its `coop-keys`
folder makes whoever has it, with a room's secret, the maker of that room (your game logs a member that presents its
key).
What nothing can prevent: everyone who knows the secret can join and read the room; a member or the relay can disturb
it (leave messages out, delay them, send one again as "Replay" says, flood within its limits, keep the rules from
being agreed, change the offer so that nothing is applied until you accept again, keep the room unaccepted by never
saying who it is, send rosters or identities that keep a player unidentified for as long as it keeps sending, or seal
messages with a counter far ahead, each of which costs a player three of a member's messages); and the relay sees who plays
with whom and when, with names and addresses. None of that changes a save.
## Other players in the world
Not in this build. The protocol has a message for it (POS in `runtime/coop_proto.h`: the area, a position, a facing
and what Link's animation slots play), and its codec and its counter against replayed poses are in the build and
checked by `--probe-coop`, but nothing sends one and nothing draws another player: a POS that arrives is dropped. So
no position leaves your PC, whatever the settings.
## In the log
State changes only: `coop: connecting to the relay`, `the relay answered in N ms`, `room XXX… created`, `joined room
XXX… as member N`, `<name> (member N) joined the room` and `left the room`, `relay lost; rejoining`, `left room (<why>)`.
A cause that repeats (a message that does not open, a replay, no server) logs once per 30 s; a counters line follows
every minute in a room. Peer addresses are never logged; the relay's only with `NX2NAVI_TRACE=coop`, which also adds a
line per datagram.
Progress sync: `coop: sync: playing a save: N progress flags, ...` when a save is being played (and `... nothing is read
or written until a save is played` when it stops), `a room to accept; in the room: ...; rules: ...` followed by `put
coop_accept = <number> into nx2navi.ini [coop]` (or, while a member is not identified, `N member(s) in the room are
not identified`; when the members carry rules of different keys, a line that says so), `room accepted`, `the save
as it was before this room is in <folder>`, `the key this game signs the room's rules with is kept in <folder>` (the
maker), `the room's rules: progress shared, ...`, `took N values from the room (progress a, items b)` at most every
5 s, `N values from the room were refused`, `member N sent values this game does not take; nothing more is taken from
it`, for the maker `key K (member N, name | not in the room) took N keys ... from the pools beyond what it brought;
coop_remove = K removes it`, `key K removed`, `coop_remove = N in nx2navi.ini names a member number` (not taken), `the
pools are reset`, `member N presents this game's own key`, `member N presents another key than the one it was identified
by in its session`, `member N (name, key K) presents a key you accepted as member M | under the name ...: under this
name it is a new offer`, and `the room's key file ... is damaged | cannot be read`.
`NX2NAVI_TRACE=coop` adds `sent`,
`received` and `applied` lines by category, hash and value. With `coop = 0` nothing of this is logged and the game's
frames do no more than check the setting.
## The interface for the layers above
`runtime/coop.h`: `coop_send(kind, bytes, n)` and `coop_send_to(member, ...)` send a sealed message to the others (it is
a datagram: it may be lost, arrive out of order or, recorded, arrive again: see "Replay"), `coop_on_message(kind, fn, user)` receives
them on the coop thread, `coop_on_view(fn, user)` reports the state and the roster (with each member's maker mark and
whether its messages opened), `coop_view_get(&view)` copies them, `coop_command(COOP_CMD_CREATE | COOP_CMD_JOIN |
COOP_CMD_LEAVE, secret)` drives the room, `coop_remove_member(id)` is the maker's removal (progress sync signs it
through `coop_on_remove`). `runtime/coop_offer.h` holds the menu's calls, none of which waits for the sync engine (what
they read is a copy the coop thread publishes at each step, what they ask it carries out at its next step):
`coop_game_offer(&offer)` and `coop_game_accept(number)` show a room and accept it (`CoopOffer` in
`runtime/coop_state.h`: each member's signed name, key fingerprint, whether it is identified or removed, how many
members never identified (the room cannot be accepted while there are any), whether the members' rules disagree, the
rules and the key that signs them, whether another save is played and whether the copy is made),
`coop_game_reset_pools()` is the maker's pool reset, `coop_game_remove_key(fingerprint)` the maker's removal of a key
(also of a player who left; a member in the room with that key is removed at the relay too), and
`coop_game_contributors()` lists the pools' contributors with what each took beyond what it brought, per pool and in
the room or not (a player who used keys others found is among them). `CoopView.made` is this session's own creation of
the room, `CoopView.name` the player's own name. The wire format is `runtime/coop_proto.h`. Progress sync uses
`coop_on_tick(fn, user)` for its timers.
## Checks
- `python tests/coop_relay_test.py`: the relay (rooms, rejoin with the token, timeouts, limits per member, per network
and in all, removal by the maker, bad tags, a stolen client id, challenge and room floods, fan-out, garbage from a
member, the log without secrets, a join attempt asked again without a charge, two players behind one address who
wait ten minutes for a room, a rejoin during a challenge flood, rooms that send to nobody, a rejoin while the members
of four other rooms flood with their tokens, and a rejoin on a relay with its full 1000 rooms while someone floods
with every token of the room and a member of it with its own) on a fake clock and over
UDP, and the codec against the vectors. With `NX2NAVI_EXE=<game>/ocarina` it also runs the probe against a relay it
starts (with `--log-joins`, whose log a failure shows), with and without 30 % loss, and restarts that relay in the
middle.
- `ocarina --probe-coop`: the sockets, the codec and its cryptography (known answers, a sealed message that does not
open when changed or sent by another), a fuzz of every parser, the POS message's counter (a pose sent again, one
recorded 35000 poses earlier, another session in the same member number, one forged far ahead), which members count
as shown (only those accepted and identified), and two sessions in
one process that make and join a
room, exchange messages, take garbage and forgeries from a hostile relay (a changed message, one it sealed itself,
a replay after a rejoin, lies while a player connects), lose the relay and find each other again, and in which the
maker removes a player. Needs no window, GPU or game files. It runs its own small relay;
`NX2NAVI_COOP_RELAY=host:port` uses a real one, `NX2NAVI_COOP_DROP=30` drops that share of what the sessions
receive, `NX2NAVI_COOP_VECTORS=tests/coop_vectors.txt` checks the byte vectors. Its sync part runs the merge engine
between fake games on a fake network: merging, late joiners, loss, the rules and pools, nothing carried from one room
or save to the next, a hostile member (refused values, pool records it did not sign or that nobody admitted, its own
records against a pool, removal), identities (a removed player back, a copied identity, a second name, the accepted
list), the offer's number, rules that wait for acceptance, another save in the room, the maker's pinned key, an
honest base above the limit, fair answers, the third review's cases: flags only from accepted keys (through
another member, after a declined member left or was removed, from a member that never identified), a key drain with
the maker's game restarted and the absent drainer removed, a pool reset, an identity replayed after 64 sessions or a
room the relay lost, the relay's maker mark against the members' rules, signed names, failed signatures, a game's own
pool record after the room came back, and a removal 17 removals ago; and the fourth review's: a record with the
lowest base, pools that follow the player's own acceptance, two resets in a row, a forged roster's sessions, what a
contributor took per pool, an accepted key's ended session after 65600 others; and the fifth review's: sections in
another member's name made with the secret alone (and a flood of them), a member's session after a forged roster
with a replayed message, a roster without it, a relay that says the room is gone, and a replayed identity of a
session the game never saw end, claims made again after a removal (keys brought while a removed player's gains
counted, a claim made while its spends counted, honest games that agree, a game at its title screen), another save
that joins only once accepted; and the sixth review's: digests in a member's name whose charter does not check out,
a changed copy of a member's digest and of the maker's charter sent first, another key's identity for a member's
session sent first, and a reset's carry with a player who comes after it and with a removal in the same charter;
and the seventh review's: a key the player accepted in another member's place under that member's name, and a relay
restart that hands the players other numbers;
and a randomised run (a few seeds by default; `NX2NAVI_COOP_ADVERSARY=first:count` runs those seeds alone,
`NX2NAVI_COOP_ADVERSARY_TRACE=1` prints its events and the engines' lines) of hostile members who hold the secret,
admitted or not, and of an attacker with the secret and no accepted key who forges senders and rosters, replays
messages and identities, sends changed copies of digests and sections and identities of its own key in a member's
place, against invariants of flags, acceptance, identification, ignored members, the maker's charter and a ledger
of the honest players' joins, carries, pickups and uses. The session part adds rosters forged
far and a little ahead, rosters that list another session again and again, a message in a member's name sealed with
the room's key 2^31 − 1 ahead, a refusal for the network's joins, and a
room that is not there. `ocarina --probe-fs` checks that the first copy
of a save outlasts the rotation.
- `python tests/coop_page_check.py`: the menu's Co-op tab without the game, driven with the keyboard's and the pad's
events: typing a name, a relay and a secret (Q and E are letters there, not tab keys), Make, Join with a wrong secret
and a pasted one, the offer accepted and declined, the maker's key to compare, the three warnings before the first
Accept only, a player not identified (Accept greyed, removed by member number only while the same session holds
it), a key accepted under another name (said in the offer, the row and the Accept window), Remove by key, a pool
contributor's key removed, Reset the pools, Leave, the relay's join limit and a lost room,
the maker's rules and the others' read-only ones; Accept, Remove, Reset and Leave never act on a second press, a held
button or a double tap, and a new offer under an open Accept window puts the cursor back on Not now. It then runs
again with a deliberate fault (each such window opens with the cursor moved onto its acting button) and passes only
when that run fails. Needs a C++ compiler only.

View File

@@ -148,7 +148,8 @@ llvm/ llvm-mingw, x86_64-only subset (Apache-2.0 with LLVM excep
runtime/ libnx2navirt.a, libnx2navirt-v2.a and the headers the generated code and modules.c/romfs.c/patches.c
include
bin/ nx2navi_xlate.exe, hactool.exe, SDL3.dll, libopus-0.dll, ninja.exe
data/ shader_list.tsv (MIT, THIRD_PARTY_NOTICES.md); pgo-<ver>.profdata + .json, the execution profile an
data/ shader_list.tsv (MIT, THIRD_PARTY_NOTICES.md); pipeline_list.bin when the release was made with
one (building.md, step 6); pgo-<ver>.profdata + .json, the execution profile an
update's code and the runtime libraries compile with (building.md, "Profile-guided build")
THIRD_PARTY_NOTICES.md
nx2navi.ini.example, VERSION the default ini; the release string (the repository's VERSION plus the commit)

View File

@@ -14,7 +14,7 @@ it. The code is `launcher/`, the release is made by `tools/make_launcher.py`, an
drive, and proposes `<launcher>\game` as the install folder (or `X:\Games\NX2navi` on the drive with the most
free space when that drive has less than 40 GB). Both rows can be changed.
3. Selects **Begin Installation**. The launcher downloads the build tools (about 170 MB, once), checks the dump,
unpacks it, translates and compiles the game: 10 to 25 minutes. It keeps the PC awake meanwhile.
unpacks it, translates and compiles the game: 20 to 45 minutes. It keeps the PC awake meanwhile.
4. Selects **Play**. The launcher hides while the game runs and comes back when it exits.
From then on the launcher looks for a new version when it opens and every hour while it runs, also while it is
@@ -136,11 +136,17 @@ A path the Windows ANSI code page cannot hold breaks the MSYS2 tools, so the too
complete. No MSYS2 shell or pacman runs. Then zbic: the wheel for the bundled Python from PyPI, checked against
PyPI's sha256, into `pydeps/`.
2. **Inspect Your Game** to **Compile**: `tools/make_game.py --nup <dump> --out <game> --msys <toolchain> --events`,
whose `@@` progress lines drive the rows (check, exefs, romfs, lift, compile). How it keeps the build short:
whose `@@` progress lines drive the rows (check, exefs, romfs, lift, compile). Before the first long step it
looks at what can be known to fail later: the disk space of every step that will run (the RomFS image and 1 GiB,
2 GiB for the build cache, 4 GiB for the prepared shaders; `check_space` names each part and how much is
missing), and that the build tools compile and link an empty program (`probe_toolchain`). How it keeps the build
short:
- The RomFS image (26 GB, mostly disk work) is packed beside the lift and the compile (processor work), so a first
build takes about as long as the longer of the two. Only `romfs.c`, which includes the RomFS index's
`romfs_config.h`, waits for the image.
- Every logical processor compiles, the largest files first, so no big file starts last and runs on alone.
- Every logical processor compiles, the largest files first, so no big file starts last and runs on alone; fewer
compiles run when memory is short, as many as 80 % of the free memory holds at 768 MiB each (`make_game.py`
`default_jobs`).
- The lifted code compiles with MSYS2 CLANG64's clang when the toolchain has it: the same LLVM release as
UCRT64's, built with profile-guided optimisation, about a fifth faster on this code and writing the same objects
(it reads UCRT64's headers; `make_game.py` `fast_clang` checks that both report the same version and target).
@@ -159,14 +165,20 @@ A path the Windows ANSI code page cannot hold breaks the MSYS2 tools, so the too
and writes the Xbox, PlayStation, Steam Deck and keyboard and mouse prompts into `romfs-patches-*` beside the game (about
30 s), which the game's Controls > Button prompts loads. The keyboard and mouse prompts show the keys of
`nx2navi.ini`'s `bind_` lines, so Rebuild the Game after rebinding keys draws them again; the step's key names
all it reads (the RomFS, the art, the tools, those lines), so it runs again only when one changed or a folder is
gone, and runs no other step again. Without art the row is not shown and the game keeps its own prompts.
all it reads (the RomFS, the art, those lines) and the version of the tools (`make_game.py` `PROMPT_TOOLS`, changed
by hand when a change to them changes what they write: an edit of a script alone does not draw the prompts
again), so it runs again only when one changed or a folder is gone, and runs no other step again. Without art
the row is not shown and the game keeps its own prompts.
5. **Check the Game Files**: make_game.py's last step runs `tools/romfs_check.py`, once for each copy of the game data
(about 4 minutes, in worker threads, never while the game runs). It decompresses every file, writes
(about 4 minutes on players' PCs up to 0.7.1, in worker threads, never while the game runs; its key holds the
check's version, `SCAN_TOOL`, in the same way). It decompresses every file, writes
`romfs-check.json` beside the game, and for each damaged texture puts a stand-in, another texture of the same kind
under the damaged one's name, in `mods/Damaged file stand-ins`, so the game can load what needs it. A damaged file
of any other kind is only reported: only a clean dump restores it. In play the game logs a file it keeps opening
and cannot load (runtime/romfs.c `open_note`).
and cannot load (runtime/romfs.c `open_note`). The launcher shows what the check found (`jobs.Job.note_scan`):
the count in the step's row ("4 Flagged, 3 Stand-Ins"), and after a job in which the check ran a sentence on the
home screen and in `launcher.log`. The four files the check flags on every copy of the game (`jobs.SCAN_EXPECTED`)
are told as that, with nothing for the player to do; other files are counted and `romfs-check.json` named.
6. The game's Cetra Display is decoded for the window.
## Updating
@@ -180,6 +192,10 @@ directly. Every address is https (plain http only to this PC), a redirect to htt
sent on when a redirect leaves the host it was meant for (`launcher/net.py`). A manifest that does not give a file's
size and sha256 is refused.
GitHub allows an address 60 such requests an hour. The Updates row and F5 therefore start no check within a minute
of the last one (`FORCED_CHECK_PAUSE`), and a check GitHub refuses says when the allowance is whole again, from the
answer's `X-RateLimit-Reset` (`feed.retry_text`). A failed check is one line in `launcher.log`.
### In the background
The player never waits for a download and play is never interrupted. A check that finds a newer release (the check
@@ -251,18 +267,33 @@ The stub swaps `python.next` in while no Python runs, then starts the new versio
objects of 0.5.0 and earlier); Rebuild the Game compiles it for this processor's (`--retune`), and runs the
compile step for that even when nothing else changed (`retune_due`).
6. **Swap In the New Build**: lld links `ocarina.exe.new`, which replaces `ocarina.exe` only once it is complete. A
failed rebuild leaves the old build playable; Rebuild the Game tries again.
failed rebuild leaves the old build playable; Rebuild the Game tries again. A rebuild that lifted again and then
stopped has no finished compile on record (`build.built_version` is empty), but the old exe and the unpacked game
files are there: the launcher still counts the game as installed (`build.installed`), opens on home, where
Rebuild the Game reads "Not Finished", and never asks for the dump again. Begin Installation into a folder whose
game files are already unpacked builds on from them as well (`jobs.InstallJob.args`).
7. **Prepare the Shaders** is skipped once shaders were prepared before (`shader-prepared.bin`): the game keeps using
them and translates them again with the new translator in the background (`NX2NAVI_SHADER_CARRY`). With
`shader_carry = 0`, or nothing prepared yet, the step prepares them all as at the install.
`shader_carry = 0`, or nothing prepared yet, the step prepares them all as at the install. So it does when the
list was prepared from another shader seed than the one this kit writes: `shader-prepared.bin` carries the digests
of the two seed files and the translator identity (`runtime/prp_file.h`), the step writes the seed first
(`prepare_shaders.py --no-run`, seconds) and compares (`make_game.py` `seed_changed`); a list from before it
recorded its seed is prepared again once. Another translator alone does not prepare again. The step still builds
the prepared shaders into the graphics driver's cache again (`make_game.py` `warm_driver_cache`): seconds while
the driver has them, 20 minutes on a player's PC when the update changed what they are built with. Its bar
follows that count from 0 to 100 %, and the Updates row says an update takes from a few minutes to half an hour
or more (`launcher/ui/app.py` `UPDATE_TAKES`).
8. **Draw the Button Prompts**, with button art in the new version: only when the art, the prompt tools or the key
bindings changed, or a prompt folder is missing (a first version with art draws them all).
9. Every version but the current and the previous one is deleted, except a staged release newer than the current
one.
When the new version fails to start (exit code 86 from `start.pyw`, or any error within six seconds), the stub sets
`current.txt` back to `previous.txt`'s version and starts it with `--rolled-back`. The game is never rebuilt while it
runs. Keep Build Cache off deletes the lifted C and the objects (about 5 GB) after each build but keeps
`current.txt` back to `previous.txt`'s version and starts it with `--rolled-back`. `start.pyw` writes the failure to
`data/logs/crash.log` and shows it in a message box only when there is no version to go back to, when Steam started
it, or when the six seconds are over (`quiet_exit`): a box holds the exit code back until it is closed, and the
broken version then stayed the current one. The game is never rebuilt while it
runs. Keep Build Cache off deletes the lifted C and the objects (about 1.5 GB) after each build but keeps
`build-cache/state.json`, so updates still rebuild without the dump (compiling everything).
## Sharing a save
@@ -273,7 +304,9 @@ save. Saves (home, under Game Folder; `launcher/saves.py`) and the Saves rows of
**Export.** Export Save writes `NX2navi-save-<date>_<time>.zip` into the Downloads folder (Export To chooses another
folder) and opens the folder with the zip selected, ready to drag into a bug report. With Add Log and Settings on (the
default) it is `...-bug-report.zip` and also holds the game's latest log and its `nx2navi.ini`. In the game, Export
default) it is `...-bug-report.zip` and also holds the game's latest log and its `nx2navi.ini`; while the game has no
save yet (it stopped before its first one) the launcher then writes `NX2navi-log-<date>_<time>-bug-report.zip` with
those two alone, which an import refuses as a zip without a save. In the game, Export
save and Export save for a bug report write the same two zips into Downloads; the second holds the log of the run in
progress. The zip:
@@ -420,9 +453,23 @@ refuses: no manifest, another format or game, a newer format, paths outside the
job with a fake
`make_game.py` (with and without the prompts row), and the window's selftest when a display is there.
What goes wrong around a build is tested the same way, on made-up folders and stand-in processes: an update that
stops in its compile (the game stays installed, home says how to finish, the install goes on from the unpacked
files), `start.pyw` on a version that cannot be imported (exit code 86 at once, no message box, with a version to go
back to), a cut RomFS image and the free space, the object cache written while the compile runs and kept when it is
cut, a RomFS step that does not repeat the lift, the update's duration text and the warm-up's bar, a damaged dump
named by its file and an unexpected error by its message, the file check's result in its row and on home, the
game's FATAL line after exit codes 70 and 71, the job count by free memory and the build's priority class, a line
handler that raises and a log that cannot be written, one forced update check a minute and GitHub's reset time, a
game folder with characters outside the Basic Multilingual Plane (its `modules.c` compiled when a C compiler is
there), the file check at both piece sizes against the check as it was, the disk space of every step and the build
tools' test compile, and the prompt tool's unpacking. Two tests record the logic of `tools/romfs_check.py` and of
the three prompt scripts (their code without comments and docstrings) beside `SCAN_TOOL` and `PROMPT_TOOLS`: they
fail when that logic changes, to ask whether the step must run again on every install.
## Requirements and limits
- Windows 10 or 11, x86-64; the build's own requirements (README-BuildKit.md): 16 GB of RAM, about 30 GB free for
- Windows 10 or 11, x86-64; the build's own requirements (README-BuildKit.md): 16 GB of RAM, about 34 GB free for
the game and 1.5 GB for the launcher and its tools, a Vulkan 1.3 GPU.
- The programs are not signed: SmartScreen warns on the first start of the setup.
- English only for now.

View File

@@ -79,3 +79,33 @@ 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
card, so please report whether the game stays up.
- 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).
## 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 ...").
- **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.