Bring the published docs up to date for the public repository

The README now names the three test machines, the installer, remapping and the mouse camera, and lists the open bugs. The backlog drops the dated diary, finished steps and local paths and keeps every open item with its evidence. Citations into our code name functions instead of line numbers that had drifted, build/ notes are no longer cited, and the toolchain doc lists opus and libvpx.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Valiantsin DzerakhandClaude Opus 5.5 committed 2026-10-26 08:53:19 +03:00
1 parent 31b864380f
commit 283e1f18cf
15 files changed
+384 -464

No files matched your search

+1 -1
View File
@@ -22,7 +22,7 @@ prints `<log>: rc=<code>`. The game window opens behind the user's windows witho
| `user-save-2026-10-21-monsters` | Moblins and Zonai constructs attack at once; use with `--script tools/input/fight.txt` |
| `user-save-2026-10-21` | Hyrule field facing the castle, rainy; distant sky over the castle |
| `user-save-2026-10-23-pillars` | Hyrule field by standing stone pillars, about 17:40, a Zonai construct beside Link; use with `--script tools/input/backrun.txt` (runs backward from 1550: phantom rocks, a one-frame glitch at about 1605) |
| `user-save-2026-10-24-brightbloom` | Cave, about 20:40: a Brightbloom plant at the lower left (its bulb floats beside the stem, `build/v121-bloom/NOTES.md`), teal Moblin and Bokoblin ahead or Zonai constructs (runs differ) |
| `user-save-2026-10-24-brightbloom` | Cave, about 20:40: a Brightbloom plant at the lower left (its bulb sits in its cup; it floated beside the stem before ddd0ce8), teal Moblin and Bokoblin ahead or Zonai constructs (runs differ) |
| `user-save-2026-10-22-island` | Sky island edge; use with `--script tools/input/island.txt` (runs off, skydives, opens the paraglider with B at frame 1975; X does nothing in a dive) |
`--frames` counts presents. Pick `1500 + the frames you need in-world`.
+2 -1
View File
@@ -46,7 +46,8 @@ Setup and verify commands: [docs/toolchain-windows.md](docs/toolchain-windows.md
- Game code build (`.venv`): `recomp\gen.py --exefs build\extracted\v121\exefs --out generated\v121 --patches recomp\patches-v121.txt` writes the C (about 15 s). The patch table holds the 60 fps and real-time frame step code patches, switchable at run time (`recomp/patches.py`); `.venv-py314\Scripts\python tools\make_romfs_patches.py` writes their RomFS half to `build\v121\romfs-patches`. `tools\build_game.py` compiles and links `build\v121\totk.exe` with Ninja (about 200 s clean, incremental after). `recomp/layout.py` alone decides module bases. Jump tables are resolved by `recomp/jumptables.py`; after changing it, `tests\jumptables_check.py` must report 0 disagreements with its Unicorn oracle.
- Shader census (`.venv-py314`): `tools\shader_census.py --version v121 [--translate]` extracts every Maxwell shader to `build/v121/shaders/` and runs it through `build\xlate\totk_xlate.exe` and `spirv-val`; failure groups go to `failures.txt`. `tools\xlate_smoke.py` checks the translator alone, without game files.
- Shader preparation (`.venv-py314`, once per build dir and translator): `tools\prepare_shaders.py build\v121` translates the variants of the MacNativeGames shared shader list (read from `refs/` at run time) into the build's shader cache and builds their stage libraries into the driver cache (`totk.exe --prepare-shaders`, about 5 min, 1.3 GB); play then translates and compiles only variants the list lacks.
- The plan by stage and the proposed fixes with their evidence: [docs/backlog.md](docs/backlog.md).
- Open work with its evidence: [docs/backlog.md](docs/backlog.md).
- Installer (`installer/`, `tools/make_release.py`), which builds the game on a player's machine: [docs/installer.md](docs/installer.md).
- Running, measuring or frame-dumping the game, save backups, task worktrees and their builds: [docs/agent-playbook.md](docs/agent-playbook.md).
- Project skills (`.claude/skills/`): `private-build` before changing runtime/ or tools/ code and building totk.exe (one git worktree per task); `run-game` to run a build into gameplay from a save.
- hactool: `toolchain/hactool/hactool.exe`. From an MSYS2 shell pass `-k <keys>` explicitly; the shell's `HOME` hides the default key location.
+17 -10
View File
@@ -16,15 +16,19 @@ The Switch code is lifted from ARM64 to C ahead of time, compiled with Clang, an
## Status
This is an early build. Version 1.2.1 starts, shows the title screen, loads saves and runs in the world at 60 fps, with keyboard or gamepad input and with sound. Graphics, stability and speed are still being worked on: visual bugs and crashes are expected. You build it from source; nothing is packaged for download.
This is an early build. Version 1.2.1 starts, shows the title screen, loads saves and runs in the world at 60 fps, with keyboard, mouse or gamepad input and with sound. Graphics, stability and speed are still being worked on: visual bugs and crashes are expected. No release has been published yet. You build the game from source, or assemble the installer described in [docs/installer.md](docs/installer.md), which builds it on the player's machine from the player's own files.
It is developed and measured on one machine (Ryzen 9 7900X, Radeon RX 9070). NVIDIA and older AMD GPUs are expected to work but are barely tested; [docs/tester-guide.md](docs/tester-guide.md) says what to send back.
It is developed on a Ryzen 9 7900X with a Radeon RX 9070 and tested on two more machines: a laptop with a GeForce GTX 1050 Ti and an 8th- to 10th-generation Core i7, and a Core i7 of the same generations with Intel UHD Graphics 630. An RTX 3090 Ti has also been measured. On the GTX 1050 Ti laptop the game is limited by the CPU and runs at 25 to 45 fps. Other GPUs are expected to work but are barely tested; [docs/tester-guide.md](docs/tester-guide.md) says what to send back.
To report a problem, open an issue and follow [CONTRIBUTING.md](CONTRIBUTING.md). Include the GPU and driver, the log, and the steps that get there. Screenshots are fine.
### Known problems
- For one frame, a rock or pillar can appear in the wrong place, or nearby objects vanish, most often while running or falling from a sky island. The leading suspect is thread ordering the game expects from the Switch scheduler; see [docs/backlog.md](docs/backlog.md).
The full list, with the evidence for each item, is in [docs/backlog.md](docs/backlog.md).
- For one frame, a rock or pillar can appear in the wrong place, or nearby objects vanish, most often while running or falling from a sky island.
- Yunobo fades out and disappears when his ability is used.
- On the GTX 1050 Ti, black patches appear for a moment, for example when the Purah Pad opens.
- Without `tools\prepare_shaders.py` (build step 6) the first launch compiles shaders and pipelines and stutters until the caches fill. With it, a fight on a cleared driver cache had 1 slow frame instead of 37.
- Newly streamed areas still have single slow frames while their textures upload.
- Far terrain can turn flat gray or brown for a few frames after Link is knocked down.
@@ -32,9 +36,9 @@ To report a problem, open an issue and follow [CONTRIBUTING.md](CONTRIBUTING.md)
### Not in yet
- macOS and Linux
- Running 1.0.0, 1.1.2 or 1.4.3 (the extractor recognises those updates; the host is built for 1.2.1)
- Button remapping
- A package that builds the game code on a player's machine. Today you compile it yourself
- Running 1.0.0, 1.1.2 or 1.4.3. The extractor recognises those updates, but the host is built for 1.2.1. Work on 1.4.3 has started.
- An in-game settings menu. Settings are edited in `totk.ini`.
- A published installer release
## Features
@@ -43,7 +47,8 @@ To report a problem, open an issue and follow [CONTRIBUTING.md](CONTRIBUTING.md)
- Title screen, save loading and play, including the overworld, combat and the map.
- 60 fps with the game running at real-time speed: MacNativeGames' 60 fps and frame-step patches are built in and can be switched off (`TOTK_FPS60=0`, `TOTK_REALTIME=0`).
- F11 switches between the window and borderless fullscreen.
- Keyboard and the first SDL3 gamepad, merged into one controller. Buttons are taken by position, so the south face button is B. The key map is in [docs/controls.md](docs/controls.md). Keys count only while the game window is in front.
- Keyboard, mouse and the first SDL3 gamepad, merged into one controller. Buttons are taken by position, so the south face button is B. The mouse turns the camera (`mouse_sens` sets the speed) and Esc releases the cursor. Every button can be rebound in `totk.ini` (`bind_*` lines). The key map and the remapping syntax are in [docs/controls.md](docs/controls.md). Keys count only while the game window is in front.
- Rumble with adjustable strength and response curve, and motion controls on gamepads that have a gyro.
- Sound through the game's own audio renderer, played with SDL3, including Opus voice.
- Language from the Windows locale, or from `TOTK_LOCALE`. A locale the game does not ship becomes `en-US`. `TOTK_LANG` sets a Switch code directly (`en-US`, `ja`, `zh-Hant`, …).
- Docked mode by default, which reports the boost performance configuration. `TOTK_OPERATION_MODE=handheld` reports the normal one.
@@ -58,8 +63,8 @@ The design and the research it rests on are in [docs/architecture.md](docs/archi
1. **Input.** Your base game and the 1.2.1 update are decrypted and unpacked locally with your own `prod.keys`. File hashes are checked against known retail dumps.
2. **CPU.** `main`, `sdk` and `subsdk0` are lifted to C, one function per guest function. NEON and floating point are lowered to C that follows ARM rounding. Guest addresses are host addresses. Jump tables are resolved by a symbolic pass in the generator.
3. **Host.** Threads, memory, the RomFS, saves, time, account, language and the audio renderer are implemented on Windows. Every guest thread is a host thread, but only three run game code at once: the host models the Switch's three application cores and its priority preemption, because the game keeps per-core data without locks and orders some work by thread priority alone. Input and audio output go through SDL3.
4. **Graphics.** The NVN front end records what the game submits. A Vulkan 1.3 back end replays it, uploading the memory the CPU wrote and writing GPU results back when the CPU reads them. The Ryujinx Maxwell translator, built as `totk_xlate.exe`, turns shaders into SPIR-V. Pipelines are linked from precompiled stages on first use (`VK_EXT_graphics_pipeline_library`) and optimised in the background.
3. **Host.** Threads, memory, the RomFS, saves, time, account, language and the audio renderer are implemented on Windows. Every guest thread is a host thread, but only three run game code at once: the host models the Switch's three application cores and its priority preemption, because the game keeps per-core data without locks and orders some work by thread priority alone. A thread that waits for a core interrupts a lower-priority holder that is running game code, as MacNativeGames does. Input and audio output go through SDL3.
4. **Graphics.** The NVN front end records what the game submits. A Vulkan 1.3 back end replays it, uploading the memory the CPU wrote and writing GPU results back when the CPU reads them. On a discrete GPU, memory the game binds as buffers is mirrored in video memory. The Ryujinx Maxwell translator, built as `totk_xlate.exe`, turns shaders into SPIR-V. Pipelines are linked from precompiled stages on first use (`VK_EXT_graphics_pipeline_library`) and optimised in the background. ASTC textures are decoded by a compute shader, or uploaded as they are where the GPU samples ASTC.
## How this project is made
@@ -70,7 +75,7 @@ Most of the code and documentation here is written by AI coding agents (Claude C
- Players and testers: [controls](docs/controls.md), [tester guide](docs/tester-guide.md).
- How it works: [architecture](docs/architecture.md), with research notes on the upstream projects, Maxwell GPU behaviour and what other ports learned in [docs/research/](docs/research/).
- What is being worked on: [backlog](docs/backlog.md).
- Building: [toolchain-windows.md](docs/toolchain-windows.md), [toolchain-msys2-python.md](docs/toolchain-msys2-python.md).
- Building: [toolchain-windows.md](docs/toolchain-windows.md), [toolchain-msys2-python.md](docs/toolchain-msys2-python.md), and the [installer](docs/installer.md) that builds the game on a player's machine.
- Coding agents: [AGENTS.md](AGENTS.md) and [docs/agent-playbook.md](docs/agent-playbook.md).
## Building from source
@@ -171,6 +176,7 @@ This project stands on two MIT codebases and the projects they came from. Code t
- **[hactool](https://github.com/SciresM/hactool)** by SciresM (ISC) extracts NCA and update containers.
- **[SDL 3](https://libsdl.org)** (zlib) is the gamepad and the audio output.
- **[libopus](https://opus-codec.org)** (BSD) decodes voice.
- **[libvpx](https://chromium.googlesource.com/webm/libvpx)** (BSD) decodes the cutscene movies.
- **[Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)** (MIT) allocates GPU memory.
- **[deko3d](https://github.com/devkitPro/deko3d)** (zlib) is the source of the block-linear image layout, via MacNativeGames, and a reference for Maxwell command semantics.
- **[SavageWindRecomp](https://github.com/Revivedx/SavageWindRecomp)** (MIT), a static recompilation of *Breath of the Wild*, is the model for preemption at indirect calls and a reference for frame pacing and the platform split.
@@ -195,6 +201,7 @@ Third-party code keeps its own license. The full list, with the commit each copy
| SDL 3 | 3.4.18 | zlib | `SDL3.dll` next to `totk.exe` (gamepad, audio) |
| libiconv | 1.19 | LGPL 2.1+ | `libiconv-2.dll`, unmodified, a dependency of SDL 3 |
| libopus | 1.6.1 | BSD 3-clause | `libopus-0.dll` next to `totk.exe` (voice) |
| libvpx | 1.17.0 | BSD 3-clause, with the WebM patent grant | linked statically into `totk.exe` (movies) |
| Vulkan Memory Allocator | 3.4.0 | MIT | compiled into `totk.exe` |
| Ryujinx shader translator | 1.3.2 | MIT | `build\xlate\totk_xlate.exe`, a separate process |
| GCC runtime (`libstdc++`) | 16.2.0 | GPL 3.0 with the GCC Runtime Library Exception | linked into `totk.exe` |
+10 -10
View File
@@ -6,20 +6,20 @@ Code copied or adapted from another project is listed here with its source, the
|---|---|---|---|
| MacNativeGames extraction scripts and verification hashes | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11`, Copyright (c) 2026 MacNativeGames contributors | MIT | `tools/vendor/macnativegames/` (unmodified), `tools/data/expected-v*.json` |
| LAS Recomp lifter, code generator, FP/SIMD lowering, CPU headers and differential tests | https://github.com/peiikai/LASRecomp @ `da35b83a9611d046a9a681aae668d7085954d37f`, Copyright (c) 2026 Peiikai | MIT | `recomp/lifter.py`, `recomp/simd_c.py`, `recomp/nso.py`, `recomp/gen.py`, `recomp/module.py`, `tests/jumptables_check.py`, `runtime/cpu.h`, `runtime/simd.h`, `runtime/simd_fp.h`, `tests/diff/` |
| LAS Recomp host runtime: NSO loader, host-function table, guest-space reservation and re-execution, guest thread start | https://github.com/peiikai/LASRecomp @ `da35b83a9611d046a9a681aae668d7085954d37f`, Copyright (c) 2026 Peiikai | MIT | `runtime/loader.c`, `runtime/hostfn.c`, `runtime/memory.c`; M3 tasks T2 and T6: `runtime/kernel.c`, `runtime/boot.c`; M4 T2: `runtime/vk_device.c`, `runtime/gfx_window.c`, M4 T5a: `runtime/tex_astc.c` (`runtime/nvn/astc.c`; its decode ported to GLSL in `runtime/shaders/astc_decode.comp`, compiled into `runtime/astc_decode_spv.h`, and its tables copied into `runtime/vk_astc.c`), `runtime/vk_formats.c` (format table of `runtime/nvn/vulkan/textures.c`), M4 T5b: `runtime/vk_memory.c` (page write generations of `runtime/nvn/vulkan/exec.c`, deferred destruction of `textures.c`), `runtime/vk_texture.c` (image creation, uploads and samplers of `runtime/nvn/vulkan/textures.c`), M4 T6a: `runtime/vk_sync.c` (timeline submissions and waits of `runtime/nvn/vulkan/exec.c`), M4 T6b: `runtime/vk_pipeline.c` (blend, compare and stencil mappings, vertex format table with its 3-component fallback and pipeline cache file of `runtime/nvn/vulkan/exec.c` and `device.c`), M4 T6c1: `runtime/vk_exec.c` (pass begin and end, scissor clip and attachment clears of `runtime/nvn/vulkan/exec.c`), M4 T6c3: `runtime/vk_exec_xfer.c` (copies of `runtime/nvn/vulkan/exec.c`), M4 T6c2: `runtime/vk_exec_draw.c` (uniform buffer spans, texture and sampler descriptors and dispatch flow of `runtime/nvn/vulkan/exec.c`) |
| MacNativeGames TotK host runtime: dynamic linking, identity check, module permissions, guest memory and SVCs, threads, IPC, audio renderer, system services, RomFS and save storage, boot sequence | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/runtime/`, `games/totk/scripts/prepare_runtime.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/loader.c`, `runtime/memory.c`; M3 tasks T2-T6: `runtime/kernel.c`, `runtime/svc.c`, `runtime/ipc.c`, `runtime/ipc.h`, `runtime/audren.c`, `runtime/audren.h`, `runtime/audio_mixer.c`, `runtime/audio_effects.c`, `runtime/audio_effects.h`, `runtime/audio_reverb.c`, `runtime/audio_reverb.h` (M5; SDL3 output replaces CoreAudio), `runtime/ov_system.c` (also `shared_font.c`: the BFTTF layout behind nn::pl), `runtime/ov_input.c` (also `hid_feedback.c`: vibration and six-axis handles and calls), `runtime/motion_fusion.c` (six-axis fusion of `motion_fusion.c`), `runtime/ov_media.c` (M5: hardware Opus decoder over libopus), `runtime/swkbd_win.c` (`swkbd_host.c`: ShowKeyboardArg offsets, UTF-8/UTF-16 conversion, disabled-key filter, result codes; Win32 window replaces the macOS text bar), `runtime/ov_gfx.c`, `runtime/romfs.c`, `runtime/romfs_path.h`, `runtime/fs_host.c`, `runtime/fs.h`, `runtime/boot.c`; M4 T2: `runtime/gfx_window.c` |
| LAS Recomp host runtime: NSO loader, host-function table, guest-space reservation and re-execution, guest thread start | https://github.com/peiikai/LASRecomp @ `da35b83a9611d046a9a681aae668d7085954d37f`, Copyright (c) 2026 Peiikai | MIT | `runtime/loader.c`, `runtime/hostfn.c`, `runtime/memory.c`; `runtime/kernel.c`, `runtime/boot.c`; `runtime/vk_device.c`, `runtime/gfx_window.c`, `runtime/tex_astc.c` (`runtime/nvn/astc.c`; its decode ported to GLSL in `runtime/shaders/astc_decode.comp`, compiled into `runtime/astc_decode_spv.h`, and its tables copied into `runtime/vk_astc.c`), `runtime/vk_formats.c` (format table of `runtime/nvn/vulkan/textures.c`), `runtime/vk_memory.c` (page write generations of `runtime/nvn/vulkan/exec.c`, deferred destruction of `textures.c`), `runtime/vk_texture.c` (image creation, uploads and samplers of `runtime/nvn/vulkan/textures.c`), `runtime/vk_sync.c` (timeline submissions and waits of `runtime/nvn/vulkan/exec.c`), `runtime/vk_pipeline.c` (blend, compare and stencil mappings, vertex format table with its 3-component fallback and pipeline cache file of `runtime/nvn/vulkan/exec.c` and `device.c`), `runtime/vk_exec.c` (pass begin and end, scissor clip and attachment clears of `runtime/nvn/vulkan/exec.c`), `runtime/vk_exec_xfer.c` (copies of `runtime/nvn/vulkan/exec.c`), `runtime/vk_exec_draw.c` (uniform buffer spans, texture and sampler descriptors and dispatch flow of `runtime/nvn/vulkan/exec.c`) |
| MacNativeGames TotK host runtime: dynamic linking, identity check, module permissions, guest memory and SVCs, threads, IPC, audio renderer, system services, RomFS and save storage, boot sequence | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/runtime/`, `games/totk/scripts/prepare_runtime.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/loader.c`, `runtime/memory.c`; `runtime/kernel.c`, `runtime/svc.c`, `runtime/ipc.c`, `runtime/ipc.h`, `runtime/audren.c`, `runtime/audren.h`, `runtime/audio_mixer.c`, `runtime/audio_effects.c`, `runtime/audio_effects.h`, `runtime/audio_reverb.c`, `runtime/audio_reverb.h` (SDL3 output replaces CoreAudio), `runtime/ov_system.c` (also `shared_font.c`: the BFTTF layout behind nn::pl), `runtime/ov_input.c` (also `hid_feedback.c`: vibration and six-axis handles and calls), `runtime/motion_fusion.c` (six-axis fusion of `motion_fusion.c`), `runtime/ov_media.c` (hardware Opus decoder over libopus), `runtime/swkbd_win.c` (`swkbd_host.c`: ShowKeyboardArg offsets, UTF-8/UTF-16 conversion, disabled-key filter, result codes; Win32 window replaces the macOS text bar), `runtime/ov_gfx.c`, `runtime/romfs.c`, `runtime/romfs_path.h`, `runtime/fs_host.c`, `runtime/fs.h`, `runtime/boot.c`; `runtime/gfx_window.c` |
| MacNativeGames TotK frame-rate patches: 60 fps present-interval controller, real-time frame step and its present sampling, hair and cloth clock, trampoline slow-motion check (instruction words and 1.2.1 sites), player position chain; quick-menu capture background RomFS overlay | https://github.com/ly05010419/MacNativeGames @ `ebe621de99bfc48f3c42f2d2aa73e04fbcc6eae2` (`games/totk/runtime/game_patches.c`, `game_version.h`, `world_survey.c`, `games/totk/scripts/make_romfs_patches.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/frame_rate.c`, `recomp/patches-v121.txt`, `tools/make_romfs_patches.py` |
| MacNativeGames TotK virtual-core preemption: asynchronous preemption of an owner in top-level game code, priority inheritance through guest mutexes, the SDK's preemption-disable protocol (TLR+0x100/+0x102, SVC 0x36), the core-wait diagnostics | https://github.com/ly05010419/MacNativeGames @ `33e8fa83052ea1ae09a3583137008e9797e12950` (`games/totk/runtime/threads.c`, commits 8bf0893 and 19730cd), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/kernel.c` (SuspendThread and a register-saving stub replace SIGUSR2), `runtime/hostfn.c`, `runtime/svc.c` (host depth) |
| MacNativeGames RomFS index builder (`TOTKRFS1` layout) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/scripts/prepare_romfs_backend.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `tools/romfs_index.py` |
| d2r-mobile host thread environment (TLR, TLS, thread object), the origin of MacNativeGames' thread layer; d2r-mobile NVN host object layouts, command record format and NVN front end, as adapted for TotK in MacNativeGames' `d2r_gfx` copy | https://github.com/jhaizhou-ops/d2r-mobile @ `53e7c5bb9ca3ea53e2160005be8fbe920cd9cb53` (`dm/host/thread.c`, `dm/host/hle_thread.c`); the NVN layouts and front end via https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/nvn/nvn_obj.h`, the two types of `nvn_tex.h`, `hle_nvn.c`, `totk_nvn_ext.c`, `nvn_impl.h`, `nvn_hmap.h`, `nvn_pool_index.h`, the request checks and mapping semantics of `totk_vpool.c`, the generation stamps of `nvn_dirty.c`, texture mirroring and texel copies of `nvn_mtl.m`; licence in `games/totk/third_party/d2r_gfx/LICENSE`), Copyright (c) 2026 jhaizhou | MIT | M3 task T2: `runtime/kernel.c`; M4 task T1: `runtime/nvn_obj.h`; M4 task T3c: `runtime/nvn_api.h`, `runtime/nvn_api_core.c`, `runtime/nvn_hmap.h`, `runtime/nvn_pool_index.h`; M4 task T3d: `runtime/nvn_api_obj.c` (also `nvn_pace.h`); M4 task T3e: `runtime/nvn_api_cmd.c`, `runtime/nvn_ext.c`; M4 task T5b: `runtime/vk_memory.c`, `runtime/vk_texture.c`; M4 task T6a: `runtime/vk_sync.c` (side effects written after GPU completion, `hle_nvn.c`); M4 task T6b: `runtime/vk_pipeline.c` (pipeline key and state mapping of `nvn_mtl.m` `pso_key_fill` / `pso_desc`, its `vfmt` vertex formats and the missing-varying fix-up of `msl_varyings`); M4 task T6c1: `runtime/vk_exec.c`, `runtime/vk_exec.h` (op loop, pure-state ops and state defaults of `nvn_mtl.m` `mtl_exec` / `state_op` / `state_reset`); M4 task T6c3: `runtime/vk_exec_xfer.c` (copy, clear, event, counter and conditional-render semantics of `nvn_mtl.m` `copy_t2b` / `copy_b2t` / `copy_t2t` / `clear_tex` / `cond_eval`); M4 task T6c2: `runtime/vk_exec_draw.c` (bind ops, draw and dispatch flow, vertex streams of `nvn_mtl.m` `state_op` / `bind_vertex_streams` / `draw_inner` / `dispatch`) |
| nxnative NVN front end (d2r-mobile's successor): texture view depth-stencil mode bits, stencil-view rule, `Downsample` and indirect draw and dispatch records | https://github.com/seedds/nxnative @ `d5b380b3a80495609c2e751bb994911a638935ad` (`dm/gfx/nvn/hle_nvn.c`, `nvn_obj.h`, `nvn_mtl.m`), Copyright (c) 2026 jhaizhou | MIT | M5: `runtime/nvn_obj.h`, `runtime/nvn_ext.c`, `runtime/nvn_api_cmd.c`, `runtime/vk_exec_draw.c` |
| d2r-mobile host thread environment (TLR, TLS, thread object), the origin of MacNativeGames' thread layer; d2r-mobile NVN host object layouts, command record format and NVN front end, as adapted for TotK in MacNativeGames' `d2r_gfx` copy | https://github.com/jhaizhou-ops/d2r-mobile @ `53e7c5bb9ca3ea53e2160005be8fbe920cd9cb53` (`dm/host/thread.c`, `dm/host/hle_thread.c`); the NVN layouts and front end via https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/nvn/nvn_obj.h`, the two types of `nvn_tex.h`, `hle_nvn.c`, `totk_nvn_ext.c`, `nvn_impl.h`, `nvn_hmap.h`, `nvn_pool_index.h`, the request checks and mapping semantics of `totk_vpool.c`, the generation stamps of `nvn_dirty.c`, texture mirroring and texel copies of `nvn_mtl.m`; licence in `games/totk/third_party/d2r_gfx/LICENSE`), Copyright (c) 2026 jhaizhou | MIT | `runtime/kernel.c`; `runtime/nvn_obj.h`; `runtime/nvn_api.h`, `runtime/nvn_api_core.c`, `runtime/nvn_hmap.h`, `runtime/nvn_pool_index.h`; `runtime/nvn_api_obj.c` (also `nvn_pace.h`); `runtime/nvn_api_cmd.c`, `runtime/nvn_ext.c`; `runtime/vk_memory.c`, `runtime/vk_texture.c`; `runtime/vk_sync.c` (side effects written after GPU completion, `hle_nvn.c`); `runtime/vk_pipeline.c` (pipeline key and state mapping of `nvn_mtl.m` `pso_key_fill` / `pso_desc`, its `vfmt` vertex formats and the missing-varying fix-up of `msl_varyings`); `runtime/vk_exec.c`, `runtime/vk_exec.h` (op loop, pure-state ops and state defaults of `nvn_mtl.m` `mtl_exec` / `state_op` / `state_reset`); `runtime/vk_exec_xfer.c` (copy, clear, event, counter and conditional-render semantics of `nvn_mtl.m` `copy_t2b` / `copy_b2t` / `copy_t2t` / `clear_tex` / `cond_eval`); `runtime/vk_exec_draw.c` (bind ops, draw and dispatch flow, vertex streams of `nvn_mtl.m` `state_op` / `bind_vertex_streams` / `draw_inner` / `dispatch`) |
| nxnative NVN front end (d2r-mobile's successor): texture view depth-stencil mode bits, stencil-view rule, `Downsample` and indirect draw and dispatch records | https://github.com/seedds/nxnative @ `d5b380b3a80495609c2e751bb994911a638935ad` (`dm/gfx/nvn/hle_nvn.c`, `nvn_obj.h`, `nvn_mtl.m`), Copyright (c) 2026 jhaizhou | MIT | `runtime/nvn_obj.h`, `runtime/nvn_ext.c`, `runtime/nvn_api_cmd.c`, `runtime/vk_exec_draw.c` |
| NVN type definitions reconstructed from Darksiders II DWARF information, with MacNativeGames' TotK size annotations | h1k421, via https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/nvn/include/nvn.h`), Copyright (c) 2020 h1k421 | MIT | `runtime/nvn.h` (unmodified) |
| Ryujinx.Audio voice state and effects, as ported in MacNativeGames' audio renderer | https://github.com/Ryujinx/Ryujinx, via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/runtime/audio_renderer.c`, `audio_effects.c`, `audio_reverb.c`; licence text in `games/totk/third_party/licenses/Ryujinx-Audio.txt`), Copyright (c) Ryujinx Team and Contributors | MIT | M3 task T3: `runtime/audren.c` |
| REA agent skill `reverse-engineer-anything` | https://github.com/morluto/rea @ `799e8265b254e225dc1dabdd25e56f0ab7f86bd3`, Copyright (c) 2026 morluto | MIT | `.claude/skills/reverse-engineer-anything/`, `.agents/skills/reverse-engineer-anything/` (pinned in `skills-lock.json`) |
| Ryujinx shader translator 1.3.2 (`Ryujinx.Graphics.Shader`, `Spv.Generator`, `Ryujinx.Common`) with MacNativeGames' four optimizer patches and `totk_xlate` tool | https://github.com/Ryujinx/Ryujinx, via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`vendor/ryujinx`, `games/totk/tools/totk_xlate/`), Copyright (c) Ryujinx Team and Contributors; tool Copyright (c) 2026 jhaizhou | MIT | `tools/vendor/ryujinx/` (unmodified), `tools/xlate/`, `runtime/gfx_shader.c` (job layout from `tools/shader_census.py`; M4 T6b: c2 handle ranges of `totk_xlate/Service.cs` for the reflection), `runtime/vk_pipeline.c` (M4 T6b: the translator's set/binding and support-buffer conventions) |
| deko3d block-linear image layout, as ported in MacNativeGames' `nvn_tex.c` (Apple parts dropped, layout math unchanged; licence text in `games/totk/third_party/d2r_gfx/LICENSE.deko3d`, reproduced in the file header) | https://github.com/devkitPro/deko3d (`source/dk_image.cpp`), via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/nvn/nvn_tex.c`, `nvn_tex.h`), Copyright (C) 2018-2020 fincs | zlib | M4 task T3b: `runtime/nvn_tex.c`, `runtime/nvn_tex.h` |
| MacNativeGames texture auto-layout goldens (40 original-SDK size and block-height cases) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/tests/texture_auto_layout/probe.c`), Copyright (c) 2026 jhaizhou | MIT | M4 task T3b: `runtime/nvn_tex_probe.c`; T3f: `runtime/nvn_probe.c` (four of the cases, through the procs) |
| MacNativeGames block-linear deswizzler (address function; copy loop split out as `tex_bl_copy`) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/tex/nvn_deswizzle.c`), Copyright (c) 2026 jhaizhou | MIT | M4 task T5a: `runtime/tex_deswizzle.c`, `runtime/tex.h` |
| Ryujinx.Audio voice state and effects, as ported in MacNativeGames' audio renderer | https://github.com/Ryujinx/Ryujinx, via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/runtime/audio_renderer.c`, `audio_effects.c`, `audio_reverb.c`; licence text in `games/totk/third_party/licenses/Ryujinx-Audio.txt`), Copyright (c) Ryujinx Team and Contributors | MIT | `runtime/audren.c` |
| REA agent skill `reverse-engineer-anything` | https://github.com/morluto/rea @ `799e8265b254e225dc1dabdd25e56f0ab7f86bd3`, Copyright (c) 2026 morluto | MIT | `.claude/skills/reverse-engineer-anything/`, `.agents/skills/reverse-engineer-anything/` (pinned in `.claude/skills/skills-lock.json`) |
| Ryujinx shader translator 1.3.2 (`Ryujinx.Graphics.Shader`, `Spv.Generator`, `Ryujinx.Common`) with MacNativeGames' four optimizer patches and `totk_xlate` tool | https://github.com/Ryujinx/Ryujinx, via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`vendor/ryujinx`, `games/totk/tools/totk_xlate/`), Copyright (c) Ryujinx Team and Contributors; tool Copyright (c) 2026 jhaizhou | MIT | `tools/vendor/ryujinx/` (unmodified), `tools/xlate/`, `runtime/gfx_shader.c` (job layout from `tools/shader_census.py`; c2 handle ranges of `totk_xlate/Service.cs` for the reflection), `runtime/vk_pipeline.c` (the translator's set/binding and support-buffer conventions) |
| deko3d block-linear image layout, as ported in MacNativeGames' `nvn_tex.c` (Apple parts dropped, layout math unchanged; licence text in `games/totk/third_party/d2r_gfx/LICENSE.deko3d`, reproduced in the file header) | https://github.com/devkitPro/deko3d (`source/dk_image.cpp`), via MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/nvn/nvn_tex.c`, `nvn_tex.h`), Copyright (C) 2018-2020 fincs | zlib | `runtime/nvn_tex.c`, `runtime/nvn_tex.h` |
| MacNativeGames texture auto-layout goldens (40 original-SDK size and block-height cases) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/tests/texture_auto_layout/probe.c`), Copyright (c) 2026 jhaizhou | MIT | `runtime/nvn_tex_probe.c`; `runtime/nvn_probe.c` (four of the cases, through the procs) |
| MacNativeGames block-linear deswizzler (address function; copy loop split out as `tex_bl_copy`) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/third_party/d2r_gfx/gfx/tex/nvn_deswizzle.c`), Copyright (c) 2026 jhaizhou | MIT | `runtime/tex_deswizzle.c`, `runtime/tex.h` |
| SDL 3.4.18, dynamic link, `SDL3.dll` copied next to `totk.exe`. Developer builds use the MSYS2 build (`mingw-w64-ucrt-x86_64-sdl3`, which imports `libiconv-2.dll`, LGPL-2.1, unmodified, copied beside it); the installer release ships the upstream release `SDL3-3.4.18-win32-x64.zip`, which imports no libiconv | https://libsdl.org, Copyright (c) 1997-2026 Sam Lantinga | zlib | `runtime/input_win.c` (gamepad input, rumble, gyro and accelerometer) |
| libopus (MSYS2 `mingw-w64-ucrt-x86_64-opus`), dynamic link, `libopus-0.dll` copied next to `totk.exe` | https://opus-codec.org, Copyright (c) 2001-2023 Xiph.Org, Skype Limited, Octasic, Jean-Marc Valin, Timothy B. Terriberry, CSIRO, Gregory Maxwell, Mark Borgerding, Erik de Castro Lopo, Mozilla, Amazon | BSD-3-Clause | `runtime/ov_media.c` (nn::codec hardware Opus decoder) |
| Vulkan Memory Allocator 3.4.0 (MSYS2 `mingw-w64-ucrt-x86_64-vulkan-memory-allocator`), header-only, compiled into `totk.exe` | https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator, Copyright (c) 2017-2026 Advanced Micro Devices, Inc. | MIT | `runtime/vk_vma.cpp` (the allocator behind `runtime/vk_memory.c`) |
+15 -14
View File
@@ -8,8 +8,7 @@ Read this before you run the game, take a frame dump or measure performance. Thi
Start, build, hand back and clean up a task with the `private-build` skill (`.claude/skills/private-build/SKILL.md`): a git worktree on `task/<tag>` and a build dir `build/v121-<tag>`.
The pipeline cache, `pipeline-keys.bin`, `shader-cache`, `shader-programs.bin` and `shader-answers.bin` live next to
each `totk.exe`, so a task build starts cold: seed it by copying `build/v121`'s five before timing anything. A build seeded
from an older one stalls on pipeline and shader builds, and its slow frames say nothing about the change. (Until 2026-10-22 every task build wrote into
`build/v121`'s caches, and task builds broke each other's runs.)
from an older one stalls on pipeline and shader builds, and its slow frames say nothing about the change.
## Running
@@ -39,7 +38,7 @@ other `totk.exe` or `ninja.exe` runs. The log's first and last lines record the
- `TOTK_PROFILE=<path> TOTK_PROFILE_FRAMES=lo-hi`: sampling profiler (`runtime/prof_win.c`), read with
`tools/prof_report.py <profile> <totk.map>`. With `TOTK_PROFILE_RENDER=1` it samples the render thread only and keeps
call chains: the report adds inclusive time per function and the exe callers of the driver and system DLLs.
- `tools/regress.py <build> --base build/v121-m4 [--routes fight,rock,island,field] [--repeat 3] [--cold] [--validation]
- `tools/regress.py <build> [--base <build>] [--routes fight,rock,island,field] [--repeat 3] [--cold] [--validation]
[--out dir]`: runs the routes through `run_game.py --quiet`, scores logs and `TOTK_SHOTS` frames
(`tools/regress_score.py`, tested by `tests/regress_score_test.py`) and prints median and worst per metric. Run the candidate alone and judge it against
the targets: max fps, no slow frames (`perf: slow frame`), no black or flat frames, no new validation errors.
@@ -52,7 +51,7 @@ other `totk.exe` or `ninja.exe` runs. The log's first and last lines record the
- `fight.txt`: 59.1 fps mean, 60 median, replay 13.6 ms, 0 CPU-side slow frames; the slow frames left are
pipeline and shader-translation waits.
- `--validation` runs work in the world (1800 frames checked). The layer prints each message kind 10 times, so it
gives no totals; the known messages left are in the backlog correctness queue, item 8.
gives no totals; the known messages left are in the backlog, item 6.
## Frame dumps
@@ -63,7 +62,7 @@ copies and clears. `TOTK_DUMP_BUF=addr:size[:off:stride:w:h]` dumps a guest buff
- A draw's argument lines come before its pass header.
- Pass numbers shift between runs. Find a pass by its draw count instead: the g-buffer pass has about 1990 draws.
RenderDoc cannot capture: the driver hides `VK_EXT_external_memory_host`.
RenderDoc cannot capture: it hides `VK_EXT_external_memory_host` ([controls.md](controls.md), "RenderDoc capture").
## Other GPUs
@@ -72,27 +71,29 @@ Vulkan code queries the feature, extension, format or limit it uses and keeps a
it is missing (`vk_pipeline.c` provoking vertex and subgroup size pinning are examples). Never hard-code what this GPU
reports: alignments, subgroup size, depth formats, `maxPushDescriptors`.
Numbers from this machine do not carry over. Measured on the user's other machines (2026-10-24/25, logs and analysis
in `build/mem-plan.md`):
Numbers from this machine do not carry over. The user's other machines (the test machines of
[backlog.md](backlog.md)) measured:
- GTX 1050 Ti (4 GiB, 214 MiB BAR, no ReBAR; i7 8th-10th gen) and RTX 3090 Ti: GPU time 110-120 ms per frame in the
world against 4.3 ms here, because the GPU reads imported host pools over PCIe. The VRAM mirror (cd6f490) brings
the 1050 Ti to 10-11 ms; that machine is now CPU-bound at 25-45 fps (replay 25-30 ms per frame, backlog 0b).
the 1050 Ti to 10-11 ms; that machine is now CPU-bound at 25-45 fps (replay 25-30 ms per frame, backlog item 8).
- The same write-watch scan costs about 3x the CPU time it costs here.
- NVIDIA has no ASTC: first texture uploads decode on the CPU, 0.4-0.7 s load frames (backlog 5a.2).
- NVIDIA and AMD desktop GPUs have no ASTC: textures decode in a compute shader (`TOTK_ASTC`). Before that, CPU
decodes made 0.4-0.7 s load frames on the 1050 Ti. The UHD 630 reports ASTC, so it takes the native upload path
(not yet confirmed in a run).
- `cannot alias its pool memory` fills its 16-line log limit on NVIDIA and on the RX 9070 alike (1920x1080, 1600x900,
800x450 render targets); a suspect for the black patches of backlog 0a (`build/alias-plan.md`).
800x450 render targets); a suspect for the black patches of backlog item 2.
A run on another machine goes through the user: copy `build/release/TotK-perf-log.vbs` next to the `totk.exe` you
hand over. It starts the game with `TOTK_TRACE=perf` and writes `logs\perf-<date>-<time>.log`. Ask for the log; the
user cannot run scripted input there.
A run on another machine goes through the user: hand over a build that starts with `TOTK_TRACE=perf` (the
environment, or `trace = perf` in its `totk.ini`) and writes stderr to a log file, and ask for the log. The user
cannot run scripted input there.
## Checks before handing back
`totk.exe --probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex` and `--probe-shader` run from the build directory and
must pass. CPU-header changes also need `tests\diff\simd.py`, `lift.py` and `func.py` (AGENTS.md).
`tools\build_game.py` hashes every object against `obj/objects.sha256` before it links and recompiles a mismatch (the
faulty RAM flipped bits in stored objects once, `build/BOOTCRASH.md`). The line `objects verified: N, recompiled after
faulty RAM flipped bits in stored objects once). The line `objects verified: N, recompiled after
a hash mismatch: M` should show M of 0; a nonzero M means rerun the probes. A task build checks the shared objects against
the main build's manifest, so build `build/v121` first.
+10 -8
View File
@@ -24,7 +24,7 @@ MacNativeGames cannot run on x86-64 as is: its CPU path executes ARM64 code nati
- ExeFS and RomFS extraction: MacNativeGames' Python extractor (Python 3.14 for `compression.zstd`, `.venv-py314`).
- Update merging: hactool at `1d64a83`, with MacNativeGames' BKTR patches (`toolchain/hactool`).
- Verification: MacNativeGames' `expected-v*.json` hashes of ExeFS, RomFS and fonts.
- Primary version: 1.2.1, the update most players have. MacNativeGames supports it with the same build path as the others. 1.0.0, 1.1.2 and 1.2.1 share `sdk`, `subsdk0` and `rtld` byte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; only `main` differs. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a separate, later target.
- Primary version: 1.2.1, the update most players have. MacNativeGames supports it with the same build path as the others. 1.0.0, 1.1.2 and 1.2.1 share `sdk`, `subsdk0` and `rtld` byte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; only `main` differs. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a separate target; work on it has started on a branch and is not merged.
- Windows driver: `tools/extract.py` runs the vendored extractors (`tools/vendor/macnativegames/`) and identifies the update by the SHA-256 of its `main`. hactool has no Darwin `funopen` here, so the base Program NCA is copied out of the NSP before the BKTR merge (about 17 GB of temporary space).
### 2. CPU: lift ARM64 to C
@@ -47,7 +47,7 @@ MacNativeGames cannot run on x86-64 as is: its CPU path executes ARM64 code nati
- Portable C from MacNativeGames: threads and synchronisation, IPC, memory services, fs/RomFS, time, account, applet, audio renderer and effects. The Apple pieces (mach VM, CommonCrypto, AudioToolbox, GameController) are replaced with Win32 and SDL3.
- SDK boundary at the `nn::*` function level, matching MacNativeGames. Only `audren:u` and `sm:` are real IPC services.
- Window, input, controllers and audio output: SDL3. Voice: libopus (BSD). Movies: the SDK's `movie::Decoder` is replaced by a host VP9 decoder over libvpx (BSD, static; `runtime/ov_movie.c`), because FFmpeg from MSYS2 is a GPL build.
- OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`), so a Linux or macOS host adds one file instead of touching the rest. `tools/check_platform.py` keeps Win32 calls out of the other files.
- OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`), so a Linux or macOS host adds one file instead of touching the rest. The split is not finished: `tools/check_platform.py` lists the Win32 uses left in the other files.
#### Threads and cores
@@ -71,13 +71,15 @@ Other ports and what they changed about scheduling: [port-lessons.md](research/p
- NVN front end from MacNativeGames (`nvn_api_*.c`, `nvn_obj.h`, texture layout and deswizzle). The game records command buffers through it; nothing reaches the GPU until the game submits.
- Vulkan 1.3 back end in place of MacNativeGames' Metal one. At `QueueSubmitCommands` the recorded NVN commands are replayed into Vulkan command buffers (`vk_exec*.c`).
- Memory pools. Apple's unified memory let MacNativeGames use the game's pools zero-copy. On a discrete GPU the back end uploads the pages the CPU wrote (write watch, above) before a replay, and writes GPU-rendered textures back when the CPU reads them (`vk_texture.c`).
- Memory pools. Apple's unified memory let MacNativeGames use the game's pools zero-copy. The back end imports the pools as host memory (`VK_EXT_external_memory_host`). On a discrete GPU, pools bound as buffers are mirrored in device-local memory and the pages the CPU wrote (write watch, above) are uploaded before a replay; idle pool regions are made read-only so the write-watch queries skip them (`vk_memory.c`). GPU-rendered textures are written back when the CPU reads them: on a pool invalidate, on a CPU copy, and for small targets once the CPU waits for a fence (`vk_texture.c`).
- Replay thread. `TOTK_REPLAY_ASYNC=1` moves the replay off the submitting thread onto a queue at most one frame behind the game; reads of GPU results wait for the newest writer instead of draining the queue (`vk_backend.c`). It is off by default because no timing has shown a gain yet.
- Driver data. The NVN driver keeps a per-stage constant bank (c0) that shaders read for things like point size, dispatch size and base instance. The back end fills it the way the driver does.
- Shaders: the Ryujinx translator 1.3.2 with MacNativeGames' patches and ours (`tools/xlate/patches/`), built with .NET 10 NativeAOT as `totk_xlate.exe` and run as a separate process. Its SPIR-V goes to Vulkan directly. Translated shaders are cached on disk.
- Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it. Shader stages are compiled ahead into libraries; a draw that meets a new state links them at once (fast link), and an optimised pipeline replaces the linked one when a background thread finishes it. Pipeline keys seen in play are saved and built at boot. Without the extension, a missing pipeline is built on a worker and the draw waits or is skipped.
- Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it. Shader stages are compiled ahead into libraries; a draw that meets a new state links them at once (fast link), and an optimised pipeline replaces the linked one when a background thread finishes it. Pipeline keys seen in play are saved and built at boot. 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, so one-shot passes are never lost (`TOTK_PIPE_SKIP`); the stage libraries a waiting draw needs are built on idle workers in parallel (`TOTK_PIPE_WAIT`). Without the extension, a missing pipeline is built on a worker and the draw waits or is skipped by the same rule.
- Occlusion queries never block the CPU; a result that is not ready counts as visible.
- ASTC textures are decoded on the CPU when the GPU has no ASTC support (`tex_astc*.c`).
- Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`TOTK_DUMP`, `vk_dump.c`) and a flight recorder (`TOTK_FLIGHT`). RenderDoc cannot capture, because the driver hides `VK_EXT_external_memory_host` from it.
- ASTC textures are uploaded as they are where the device samples ASTC (`textureCompressionASTC_LDR`, Intel iGPUs), and decoded by a compute shader everywhere else (`vk_astc.c`, `TOTK_ASTC`). The CPU decoder (`tex_astc*.c`) is the fallback and the test oracle.
- Draw state. A draw whose program, bound state and textures repeat reuses the previous draw's shaders and skips rebuilding its descriptor sets; descriptor sets are written through update templates (`vk_exec_draw.c`, `vk_pipeline.c`).
- Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`TOTK_DUMP`, `vk_dump.c`) and a flight recorder (`TOTK_FLIGHT`). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application.
Maxwell behaviour the back end has to match, and the TotK bugs other ports fixed: [maxwell.md](research/maxwell.md).
@@ -93,7 +95,7 @@ Why Vulkan rather than D3D12 or wgpu:
- Host code: the same Clang, C11.
- Builds: `tools/build_game.py` writes a Ninja file and runs MSYS2 Ninja. Every object is hashed before linking, because a faulty RAM module once flipped bits in stored objects.
- Analysis: Ghidra with the Switch loader, Capstone, `llvm-objdump`.
- Later, for players: build the game code on their machine with a bundled `zig cc`, as LAS Recomp does, so no recompiled code is ever distributed.
- Players: the installer ([installer.md](installer.md)) builds the game code on the player's machine with a bundled llvm-mingw, so no recompiled code is ever distributed.
## Milestones
@@ -105,6 +107,6 @@ Why Vulkan rather than D3D12 or wgpu:
| M3 | Host boots | The exe reaches the first NVN call with threads, memory and RomFS working | Done |
| M4 | Playable | Vulkan back end draws the title screen and the world; input and audio work | Done |
| M5 | Renderer foundation | Fewer stutters and visual glitches, a render thread with room for 60 fps | In progress |
| M6 | Release shape | Build-on-player-machine packaging, Linux, 60 fps | |
| M6 | Release shape | Build-on-player-machine packaging, Linux, 60 fps without dips | Installer done; Linux open |
Open problems, in the order they are worked on: [backlog.md](backlog.md).
+183 -284
View File
@@ -1,299 +1,198 @@
# Backlog: the plan and the proposed fixes
# Backlog
Priorities: no artifacts and no crashes first, then 60+ fps without dips, then other GPUs and platforms. Each item
names its evidence; Maxwell item numbers refer to [research/maxwell.md](research/maxwell.md). Remove an item when it is
merged or dropped.
The open work, in priority order: no artifacts and no crashes first, then 60 fps without dips, then other GPUs and
platforms. Each item states its evidence and the number or observation that decides it. Maxwell item numbers refer to
[research/maxwell.md](research/maxwell.md), lesson ids (S1, G3, ...) to [research/port-lessons.md](research/port-lessons.md).
Remove an item when it is merged or dropped.
## Open work (2026-10-25)
Test machines: A, Ryzen 9 7900X + RX 9070 (development); B, laptop with a GTX 1050 Ti (4 GiB, no ReBAR) and an 8th- to
10th-generation Core i7; C, Core i7 of the same generations with Intel UHD 630. An RTX 3090 Ti was measured once. Only
machine A runs scripted routes; B and C send logs from the user's play.
Everything still to do, in one list. Items below this section give older detail. Merged into main on 2026-10-25:
shader memo and push skip, page-indexed pool resolve cache, region-only Read/WriteTexels, GOB-wide swizzle, Intel
legacy vertex-input fallback, all-thread profile chains (04fb67b); descriptor build skip and update templates
(283bc70; field replay 8.87 to 7.99 ms); ASTC decode in a compute shader and native ASTC where sampled (0a0584e;
monsters2 worst frame 340 to 139 ms); waiting draws' stage libraries on idle workers and skipping draws into passes
with a per-frame target (3753939; cold monsters2 worst 257 to 131 ms). Dropped after measuring: narrower guest-written
marks for WriteTexels and box-only image updates (re-uploads after WriteTexels are 0.003-0.05% of frame time;
`build/v121-astcgpu/texels-narrow.patch`, `build/v121-texbox/texbox-wip.patch`).
## Bugs
Measure before building: every item states the number that decides it.
1. **Yunobo vanishes.** He fades out of the main view about 45 frames after his ability is triggered (the ball fades
over 15 frames, then is gone); his shadow-map draws stay. Ruled out: occlusion counts, CPU readback of GPU targets,
missing NVN entry points, GPU-side resources. The game itself stops issuing his main-view draws. Leading hypothesis:
game logic fades the model alpha (material c11[33].w) and drops it from the draw queues on a CPU-side input
(camera-near fade, GfxColFade, CancelDraw distance or an AI fade). Next: a cheap check with the 60 fps and
real-time patches off; then find his c11 buffer, watch writes to c11[33].w and walk up from the writer in Ghidra.
Repro: the user's recorded session `yunobo-cast2` from save `user-save-2026-10-24-yunobo1`, 1360 frames.
2. **Black patches for a moment on machine B**, every time the Purah Pad opens (right stick click, keyboard C). Not
the VRAM mirror: a verify run that caught the glitch compared 4.45 million mirror pages with 0 mismatches. Leading
hypothesis: a new texture descriptor over a GPU-rendered texture fails `alias_compatible` and starts as a
zero-cleared image in its own memory (`vk_texture.c` `entry_of`, `create_tex`, `init_image`). The run's two largest
`left uninitialised` counts (33, 41) fall in its last seconds, where the glitch was. `cannot alias its pool memory`
fills its 16-line log limit on NVIDIA and on the RX 9070 alike. Next: per-alias diagnostic lines and a
`TOTK_TEX_FILL=magenta` knob, then a user run. Same class as yuzu PR 10418 ("areas black for a frame on camera
changes", Maxwell 2.3 / check 7).
3. **Phantom objects and the flat far field**: for one frame a rock or log stands in place of pillars, or a surface
fills the sky, most often while running or falling from a sky island. The game's producer rewrites its per-object
uniform blocks 14-24 ms after the submit that reads them, with no fence; NVN starts the GPU within microseconds,
our replay takes longer. A guard in `nvn_api_core.c` holds the producer until the newest submit has completed;
whether it removes every case is waiting for play. Any replay or frame-overlap change must keep that guarantee.
Scheduling experiments so far: port-lessons S1, S4.
4. **Lantern texture bug**: waiting for the user's description or a cropped screenshot.
5. **Fire on grass deals no damage and grass does not burn.** The CPU reads GPU-written data in GPU-only pools that
are never written back (Maxwell 4.1). Recheck first: GPU textures are now written back on pool invalidates and
fence waits (01889c7, which brought grass cutting back).
6. **Validation messages left** in world runs: `cp_t_tcb_20` samples an R32F view with depth compare in
`vkCmdDispatch` (VUID-vkCmdDispatch-None-06479; needs a D32 copy of the 4x4 R32F placeholder, Maxwell check 20);
"VkDescriptorSet 0x0 does not have a binding for vp_c1" in `vkCmdDrawIndexed`; a fragment write to Location 0
with no colour attachment.
7. **To check in play**: F11, menus, movies, rumble and gyro; the game's actions on the keyboard layout and the order
of the D-pad keys 1-4. Gyro: the user's logs show only Xbox pads, which have no gyro. With a DualSense or Pro
Controller, check Steam Input (it presents pads as a virtual Xbox pad without sensors) and the game's own
motion-aiming option.
**Freezes and frame time**
## Frame time and freezes
1. Replay thread (5a.1): `task/replayq`, `build/v121-replayq/HANDOFF.md`. Ported onto current main, probes pass; game
checks and async against sync timings unfinished. The laptop is replay-bound (25-30 ms per frame, item 0b).
2. Texture uploads in gameplay, now the largest cause of long frames: `task/texasync`,
`build/v121-texasync/HANDOFF.md`. Step 1 splits the cost (image and memory creation, CPU deswizzle, staging,
copies, locks) before choosing a worker-thread upload, GPU deswizzle, image pooling or a per-frame budget.
3. Virtual-core preemption as Horizon does (MacNativeGames 8bf0893 / e4b4601, PR #488: asynchronous preemption of an
owner in game code, priority inheritance, the SDK's preemption-disable protocol; Mac worst-1% frame 18.4 to 10.6
ms): `task/preempt`, `build/v121-preempt/NOTES.md`. Ported (`TOTK_ASYNC_PREEMPT`, on by default; 0 restores the old
scheduling, 2 keeps inheritance and the disable protocol without interrupting). It cuts the waits it targets
(`TOTK_CORE_DIAG`: game-class waits of 1 ms or more 53 / 41 / 27 to 4 / 10 / 18 in field / fight / monsters2), but
the A/B timings show no mean-fps gain: fight >25 ms frames base 62, port 96 over four pairs (fps 58.7 / 58.2,
inside run-to-run noise); one of three base field runs froze 7 s at frame 2388 with the render thread blocked on
nothing, no port run did. Next: user play with it on, `TOTK_ASYNC_PREEMPT=0` first on a new hang or stutter; if
fight stays worse, try a shorter first spin (`AP_FIRST_NS`, 250 us) or mode 2.
4. Start-up re-warm when the driver cache does not match the exe path or device (5a.3): `task/rewarm` (main merged
in, 0b3bc73), untested in game. Needed before the laptop package.
5. Shared shader list: the newer MacNativeGames lists collapse variants that differ only in texture kind into `"*"`
rows, which our runtime cannot match (it translates for the exact kind). `tools/prepare_shaders.py` reads `"*"`
as 2D (uncommitted), and `build/shader-lists/union.tsv` unions every list revision since b75be8c. Option: match
`"*"` rows at run time as MacNativeGames does (`prepare_shader_seed.py:60-76`).
6. Freeze census: a 10-15 minute user session on current main with `TOTK_FLIGHT=1`, `TOTK_TRACE=perf` and
`TOTK_INPUT_RECORD`, ranking every frame over 50 ms by cause. Decides items 7-9.
7. `TOTK_PIPE_SKIP=fullscreen` as default (cold monsters2: 0 frames over 100 ms, 1% low 33.9 to 41.7 fps; risk: one
frame without a full-screen pass the first time its pipeline appears). Decide from item 6.
8. ASTC per-frame decode budget (4b): the largest batch, the 169 M texel 8x8 array at boot, scales to about 375 ms of
GPU time on a GTX 1050 Ti. Split by mips with `minLod` if laptop runs (`TOTK_ASTC_TIME=1`) show decodes in play.
9. ASTC to BC7 re-encode on the GPU for 4 GB cards: the same array is 677 MB as RGBA8 against 42 MB of blocks.
10. Spin-wait gates (MacNativeGames a038e6b, from nxnative 066f2af / 6d34984, MIT): loops polling memory hand the
core to a queued thread after 50 us. Survey TotK 1.2.1 for such loops first.
11. Over the GPU memory budget, wait for running work and drain deferred releases before failing (MacNativeGames
4de7b4e); 4 GB cards.
12. Later: recording on several threads, descriptor buffers or bindless (touches the translator), CPU/GPU frame
overlap as LAS Recomp 13398126d (only with item 1; keeps the phantom-object guard), an x86-64-v2 build for CPUs
without AVX2/FMA (SavageWindRecomp ae42014b4).
13. Laptop package and test after items 1-5 (GTX 1050 Ti and UHD 630). Untested there: native ASTC on Intel, the
Intel `minStorageBufferOffsetAlignment` padding of the ASTC path, the legacy-driver vertex-input fallback.
**Bugs**
14. Yunobo fades out and vanishes from the main view about 45 frames after the user presses A (ball fades at
1335-1350, gone at 1352; his shadow-map draws stay). Repro: `run_game.py build/v121-yunobo --save
user-save-2026-10-24-yunobo1 --script build/recordings/yunobo-cast2.txt --frames 1360`. Ruled out: occlusion
counts, CPU readback of GPU targets, missing NVN entry points, GPU-side resources: the game itself stops issuing
his main-view draws. Leading hypothesis: game logic fades the model alpha (material c11[33].w) and drops it from
the queues on a CPU input (camera-near fade, GfxColFade, CancelDraw distance or an AI fade). Next: find his c11
buffer, write-watch c11[33].w to its writer, walk up in Ghidra; cheap check first: fps60 and real-time patches
off from present 1316. Debug tools uncommitted in `.worktrees/yunobo` (`build/v121-yunobo/debug-tools.diff`);
detail in `build/v121-yunobo/HANDOFF.md`.
15. Black patches for a moment on the GTX 1050 Ti (item 0a below, `task/alias`, `build/alias-plan.md`).
16. Lantern texture bug (item 6 below): waiting for the user's description or a cropped shot.
17. Validation: `cp_t_tcb_20` R32F view sampled with depth compare in `vkCmdDispatch` (correctness item 8), "VkDescriptorSet
0x0 does not have a binding for vp_c1" in `vkCmdDrawIndexed` (also in `build/v121/logs/val-base.log`), a fragment
write to Location 0 with no colour attachment.
18. The correctness queue below.
**Machine and housekeeping**
19. Faulty RAM: about 25 bugchecks in three days, also at 4800 without EXPO; each stick alone passed MemTest86 test
5. Since 2026-10-25 21:08 one stick (BD100C33) runs in channel A, single-channel, so timings from then on are not
comparable with dual-channel ones. Next: one stick in slot B; if clean, the pair is the fault (RMA the kit).
After the fix: clean `gen.py` and `build_game.py`, all diff tests and probes. Zero-filled cache files from the
2026-10-22 crash are in `build/quarantine-zero-cache-20261025`.
20. Waiting for the user's approval to commit: `docs/backlog.md`, `docs/agent-playbook.md`, `totk.ini.example`,
`tools/prepare_shaders.py`.
21. Clean up merged worktrees and build dirs (bindskip, astcgpu, pipewait, texbox): notes to `build/archive/`.
22. Paused branches: `task/menu` (in-game menu, 2 commits), `task/v143` (game version 1.4.3, item 22).
## Plan (agreed 2026-10-23)
Work the stages in order. At most three agents at once, at most two of them running the game. Done 2026-10-23 and
removed: validation-layer crash (`build/archive/v121-val`), frame-time summary in the default log
(`build/archive/v121-fts`), shader prebuild (`build/archive/v121-sl`), 1.4.3 recon (`build/v143-recon`), agent docs
and README, settings file `totk.ini` (`runtime/cfg.c`, `--probe-cfg`; a new variable needs a row in `known[]`;
`build/archive/v121-ini`), portable folder (`tools/package_build.py`, README build step 7; `build/archive/v121-port`),
freezes on new pipelines in fights (cold fight 53.9 to 59.7 fps mean, frames over 50 ms 10 to 0;
`TOTK_GPL_DRAW_BUILD=0` turns it off; `build/archive/v121-pfh`), agent tasks in git worktrees (`tools/worktree.py`,
`private-build` skill), rumble strength and curve (`rumble_strength`, `rumble_curve`, `rumble_triggers`), even
present cadence by back-edge pacing (fight intervals outside 16.7 +- 1 ms 24.5% to 2.4%, +3.3 ms latency;
`TOTK_TRACE=present`; `build/archive/v121-pace`), PC keyboard and mouse layout with the mouse camera (`input_map.c`,
`mouse_sens`; `build/archive/v121-kbm`; the game's button actions and the D-pad order 1-4 still to check in game).
**Stage 1: before the tester weekend**
0a. Black screen patches for a moment, seen by the user on the GTX 1050 Ti in the field (2026-10-25). Not the VRAM
mirror: a verify run that caught the glitch compared 4.45 million mirror pages with 0 mismatches. Leading
hypothesis: a new texture descriptor over a GPU-rendered texture fails `alias_compatible` and starts as a
zero-cleared own-memory image (`vk_texture.c` `entry_of`, `create_tex`, `init_image`). The run's two largest
`left uninitialised` counts (33, 41) fall in its last seconds, where the glitch was. Repro every time: open the
Purah Pad with a right stick click (keyboard C). Next: `task/alias`, per-alias
diagnostic lines and a `TOTK_TEX_FILL=magenta` knob, then a user run. Details: `build/alias-plan.md`.
0b. CPU-bound replay on weaker CPUs: with the mirror the 1050 Ti machine (8th-10th gen i7) renders the GPU part in
10-11 ms, but replay takes 25-30 ms per frame (5.2 ms on the RX 9070 machine), so 25-45 fps. The same machine
replayed in 7-13 ms at 8 fps in import mode. Mirror bookkeeping explains 2-3 ms. A `sched` run rules out core
contention: the render thread spends 79-88% of the wall time on the CPU inside `nvnQueueSubmitCommands`; guest threads
never preempt it and the OS takes about 5%. Suspects: NVIDIA driver cost per command, mirror and texture checks inside replay. Next: a
render-thread profile from the 1050 Ti (7f2f332 writes it on window close). Details: `build/cpu-plan.md`.
1. User play test of the prepared build: F11, menus, movies, rumble and gyro still to check. First report
(2026-10-23): flying smooth, short freezes in fights with monsters.
5a. Fight hitches and stutters on new content, the user's main complaint. GPU memory mirror merged (cd6f490,
`build/mem-plan.md`; 1050 Ti GPU time 110-120 to 10-11 ms). Order now: 2 (ASTC), 3 (re-warm), 1 (replay thread,
also a candidate fix for 0b). In a warm fight (`fight.txt`, frames 1500+) the game runs 58.3 fps mean,
52.9% of frames over 16.7 ms, 6.3% over 20 ms; frames over 20 ms are 87% replay (19 ms) with no pipeline or
shader waits. The user's play added 0 shader translations and 29 full pipelines.
1. Uneven frames: replay off the critical path. Translate command buffers at `EndRecording` or on a queued replay
thread, so `QueueSubmitCommands` only queues. Merged 2026-10-26 (eb17360) off by default:
`TOTK_REPLAY_ASYNC=1` turns it on. Reads wait for the texture's newest writer, releases are queued, drain
waits give the virtual core up; checks and validation clean (`build/archive/v121-replayq/NOTES.md`). On the
RX 9070 no fps gain: fight and monsters2 are bound by the game threads, field render busy 10 to 1.3 ms. With
the replay itself longer than the frame (the 1050 Ti case) there is nothing to overlap: the game's main thread
waits each frame for the previous frame's GPU work. Next: a user test on the laptops with `replay_async = 1`.
2. Hitches when something new appears: first texture uploads decode ASTC on the CPU inside the frame (367 ms at
frame 219 of `fight.txt` on the RX 9070; 402-714 ms load frames on the GTX 1050 Ti, `build/mem-plan.md`).
Desktop AMD and NVIDIA have no ASTC; Intel Gen9-11 iGPUs do (check that `vk_texture.c` uses it when the
device reports `textureCompressionASTC_LDR`). Plan, after the VRAM mirror:
1. Measure per load: ASTC bytes, decode time, block-linear deswizzle time (`PERF_ASTC` already times decode).
2. Licence check: Granite (Themaister, MIT) is believed to ship an ASTC compute decoder; yuzu's
`astc_decoder.comp` is GPL, read only.
3. Compute-shader decoder (plain Vulkan 1.1 compute, no extension, so every GPU we run on). Oracle: decode
every ASTC texture of the 1.2.1 RomFS with it and with `astc_decode_ldr_mt`, bit-exact match required.
4. In `vk_texture.c`: raw blocks go to staging (4-16x less PCIe traffic), a dispatch writes RGBA8 into the
image; `TOTK_ASTC=cpu` keeps the CPU path. VRAM use stays as today (decoded RGBA8); GPU re-encode to BC7
(yuzu's ASTC recompression) only if 2-4 GB cards run out.
3. Driver pipeline cache after a copy or driver update: the AMD driver keys its cache by exe path, so a moved folder
stutters until `--prepare-shaders` runs again. `task/rewarm` (1f3cd49, WIP) stamps `shader-prepared.bin` with
device, driver and exe path and re-warms at start on a mismatch; builds, probes pass, never run in game. Next
steps in `build/v121-rewarm/HANDOFF.md`. Whether NVIDIA caches pipeline libraries the same way: item 8.
6. Lantern texture bug: waiting for the user's description or a cropped shot.
**Stage 2: tester weekend (2026-10-24/25)**
8. Runs on other GPUs and CPUs (NVIDIA, Vega 7, weaker CPUs, [tester-guide.md](tester-guide.md)). One table: GPU,
driver, CPU, game version, fps in field and fight, hitches, errors and crashes, with a log per machine (the
`[host] frametime:` lines give the causes). Check whether NVIDIA and older AMD drivers cache pipeline libraries
like the RX 9070 does (the drawing thread builds them for a waiting draw, 0.77 ms average here); the AMD driver keys
that cache by exe path, so each copied folder runs `totk.exe --prepare-shaders` once.
**Stage 3: release next week**
9. Fix what stops play on the tested machines; the rest goes into this file.
10. Commit with the user's approval, GitHub repository, push.
11. Reddit: a post with the repo link (r/decomps, News flair), or the held preview post if the moderators approve it.
**Stage 4: after release, speed and stability**
13. GPU memory over long sessions (details below); 6-8 GB cards are the risk.
16. The correctness queue below, in its order.
**Stage 5: platforms and launcher** (each gets a written design first, agreed with the user)
17. Platform layer: no Win32 outside `runtime/platform/` (`tools/check_platform.py`: 1195 uses in 41 files; FAIL in
`motion_fusion.c`, `movie_probe.c`, `ov_movie.c`, `swkbd_win.c`, `vk_exec_draw.c`).
18. Linux: `runtime/platform/linux.c`, as SavageWindRecomp splits windows, linux and macos files. Write tracking
(`host.h` `mem_written_pages`, `mem_freeze`/`mem_thaw`/`mem_frozen`, used by the VRAM mirror and texture checks):
freezing maps to `mprotect` + a `SIGSEGV` handler; a kernel write (`read()` into guest memory) returns `EFAULT`
instead of faulting, so the same thaw-before-read sites apply. Written pages: `PAGEMAP_SCAN` ioctl with
write-protect matching (kernel 6.7+, made for Wine's `GetWriteWatch`); older kernels: write-protect the mirrored
and texture-bound pages after each sync and mark them in the fault handler (Ryujinx), uploading pools the game
rewrites every frame whole instead of tracking them. Soft-dirty (`/proc/self/clear_refs`) is process-wide and
slow, last resort. Under Proton the Windows build already works: Wine emulates both.
19. Steam Deck: RADV offers Vulkan 1.3 and `VK_EXT_external_memory_host`; 4 Zen 2 cores, so expect 30-40 fps.
20. Launcher (details below).
**Later**
21. Button remapping.
22. Game version 1.4.3. Paused 2026-10-23 by the user. Recon in `build/v143-recon` (extracted and verified in
`build/extracted/v143`; copies to continue from in `build/v143-port`). The generator runs unchanged; estimate one
day to the title, two to three to play at 60 fps. Steps:
1. `stg` no-op lift, DT_RELR in `recomp/nso.py` and `runtime/loader.c` (decoder in
`build/v143-recon/recomp/nso.py`), symbol count from DT_GNU_HASH for sdk/subsdk0.
2. Jump tables: 26 disagreements and 83 unresolved sites to 0 unexplained, v121 still at 0.
3. Tools take a version instead of `v121`; re-measure `loader.c:518-526` and `boot.c:22-24`; new boot anchors
(`boot.c:19-20`).
4. RELRO (`nn::ro::ProtectRelro`) and the new SDK imports; run to the title.
5. `recomp/patches-v143.txt` from MNG `game_patches_v143.c` (fps60, bounce, cloth; real time rewritten for the
`sys+0x1da` coefficient); player position for `frame_rate.c:89`; `make_romfs_patches.py --version`
(`Common.Product.140`).
6. Audio REV15 is mostly in place (`audren.c`, `audio_mixer.c`): fix the REV11 self-test; check override
signatures (biquad, font decode); render differences in play.
23. Community ExeFS patches.
24. Frame rates above 60 and VRR.
## Waiting for a play test
- 60 fps at real-time speed (2026-10-23): MacNativeGames' controller patch, real-time frame step, hair and cloth clock
and trampoline fix as generator patches (`recomp/patches-v121.txt`, switches `TOTK_FPS60`, `TOTK_REALTIME`,
`TOTK_CLOTH_REALTIME`, `TOTK_HIGHFPS_FIX`); the pacer ignores the game's interval while the step is real-time.
- Phantom objects and the flat far field (one frame of a rock or log in place of pillars, or a surface filling the
sky), 2026-10-23. The game's producer rewrites its per-object uniform blocks 14-24 ms after the submit that reads
them, with no fence; NVN starts the GPU within microseconds, our replay takes longer. A guard in `nvn_api_core.c`
holds the producer until the newest submit has completed. Item 5a.1 must keep that guarantee.
8. **Replay on weaker CPUs.** With the VRAM mirror, machine B renders the GPU part in 10-11 ms, but the replay takes
25-30 ms per frame (5.2 ms on machine A), so 25-45 fps. A `sched` run rules out core contention: the render thread
spends 79-88% of the wall time on the CPU inside `nvnQueueSubmitCommands`, guest threads never preempt it and the
OS takes about 5%. Mirror bookkeeping explains 2-3 ms. Suspects: NVIDIA driver cost per command, mirror and texture
checks inside the replay. Since then the descriptor build skip, update templates and the shader memo cut the
field replay on machine A from 8.87 to 7.99 ms. Next: a render-thread profile from machine B
(`TOTK_PROFILE_RENDER=1`; the profile is written when the window closes).
9. **Replay thread** (`TOTK_REPLAY_ASYNC=1`, merged off by default). On machine A no fps gain: fights are bound by
the game threads, field render busy time drops from 10 to 1.3 ms. Where the replay is longer than the frame
(machine B) there is nothing to overlap: the game's main thread waits each frame for the previous frame's GPU
work. Next: a user run on machine B with `replay_async = 1`.
10. **Texture uploads in gameplay**, now the largest cause of long frames. Step 1 splits the cost (image and memory
creation, CPU deswizzle, staging, copies, locks) before choosing between a worker-thread upload, GPU deswizzle,
image pooling or a per-frame budget. Dropped after measuring: narrower guest-written marks for `WriteTexels` and
box-only image updates (re-uploads after `WriteTexels` are 0.003-0.05% of frame time).
11. **Asynchronous virtual-core preemption** (`TOTK_ASYNC_PREEMPT`, merged on by default; port-lessons S7). It cuts
the waits it targets (`TOTK_CORE_DIAG`: game-class waits of 1 ms or more 53 / 41 / 27 to 4 / 10 / 18 in field /
fight / a larger fight), but A/B timings show no mean-fps gain: fight frames over 25 ms 62 without, 96 with, over
four pairs (58.7 / 58.2 fps, inside run-to-run noise). One of three field runs without it froze 7 s with the render
thread blocked on nothing; no run with it did. Next: user play with it on, and `TOTK_ASYNC_PREEMPT=0` first on any
new hang or stutter. If fights stay worse, try a shorter first spin (`AP_FIRST_NS`, 250 us) or mode 2.
12. **Driver cache re-warm.** The AMD driver keys its pipeline library cache by exe path, so a moved folder stutters
until `totk.exe --prepare-shaders` runs again. Branch `task/rewarm` (not merged, never run in game) stamps
`shader-prepared.bin` with device, driver and exe path and re-warms at start on a mismatch. Check whether NVIDIA
and older AMD drivers cache the same way. Needed before machines B and C get an installer build.
13. **Shared shader list.** Newer MacNativeGames lists collapse variants that differ only in texture kind into `"*"`
rows, which our runtime cannot match (it translates for the exact kind); `tools/prepare_shaders.py` reads `"*"` as
2D. Option: match `"*"` rows at run time, as MacNativeGames' `prepare_shader_seed.py` does.
14. **Freeze census**: a 10-15 minute user session with `TOTK_FLIGHT=1`, `TOTK_TRACE=perf` and `TOTK_INPUT_RECORD`,
ranking every frame over 50 ms by cause. Decides items 15-17.
15. `TOTK_PIPE_SKIP=fullscreen` as the default. On a cold larger fight: 0 frames over 100 ms, 1% low 33.9 to 41.7 fps.
Risk: one frame without a full-screen pass the first time its pipeline appears.
16. **ASTC decode budget.** The largest batch, the 169 M texel 8x8 array at boot, scales to about 375 ms of GPU time on
a GTX 1050 Ti. Split it by mip level with `minLod` if runs on machine B (`TOTK_ASTC_TIME=1`) show decodes in play.
17. **ASTC to BC7 re-encode on the GPU** for 4 GB cards: the same array is 677 MB as RGBA8 against 42 MB of blocks.
18. **Spin-wait gates** (MacNativeGames a038e6b, from nxnative 066f2af / 6d34984, MIT): loops polling memory hand the
core to a queued thread after 50 us. Survey TotK 1.2.1 for such loops first (port-lessons S3).
19. **Over the GPU memory budget**, wait for running work and drain deferred releases before failing (MacNativeGames
4de7b4e). Matters on 4 GB cards.
20. **GPU memory over long sessions** (port-lessons P3), never measured. MacNativeGames' TotK reached its 5000 MB GPU
budget after 2 h 43 min (their issue #72) and grew from 4.5 to 6.25 GiB resident; their dead-serial hash sets
reached about 1 GiB after 3 h. Our textures are destroyed when their pool range goes or a new texture takes the
address (`vk_texture.c` `entry_of`, `vk_texture_range_gone`), pools at Finalize, Vulkan objects deferred. Next: a
memory line every 1800 frames (VMA heaps, textures, pools, pipelines), a list of growing containers, then a 2-3 h
session. 6-8 GB cards are the risk.
21. **Later**: recording on several threads; descriptor buffers or bindless (touches the translator); CPU/GPU frame
overlap as LAS Recomp 13398126d (only after item 9, and it must keep the guard of item 3); an x86-64-v2 build for
CPUs without AVX2/FMA (SavageWindRecomp ae42014b4); render passes ended by uniform updates and clear-only work
(port-lessons P2); faster save loading; asynchronous texture write-back; menus, chests and cutscenes at 30 fps under
the 60 fps patch, as SavageWindRecomp does (`runtime/hle/framepace.c`, [prior-art.md](research/prior-art.md)
section E); a trimmed pipeline key (SavageWindRecomp).
## Correctness queue
1. Shader census for the open graphics lessons ([port-lessons.md](research/port-lessons.md) G3, G6), offline with no
game run: how many TotK shaders fetch from buffer textures and how many clears use a partial mask.
2. Image aliasing over GPU-only pool memory (Maxwell 2.3 / check 7, yuzu PR 10418 "areas black for a frame on camera
changes"): count distinct texture keys per address per frame; flight recorder counts new aliases.
3. Fire on grass deals no damage, grass does not burn (`build/archive/v121-fire2/HANDOFF.md`): the CPU reads GPU-written data in
GPU-only pools that we never write back (Maxwell 4.1). Recheck after the occlusion merge first.
4. `VK_KHR_index_type_uint8` (check 9): drops the CPU widening of 130-170 byte-index draws per frame.
5. Texture gather rounding on AMD (Maxwell 2.10): yuzu's sub-pixel offset at `ImageGather` fixed BotW shadow edges.
6. Horizon scheduling fidelity beyond the phantom work (port-lessons S1, S3, S5, S6): wake a better-priority thread on
the signaller's core at SVC return, pin ideal-core -2 and main threads to core 0. Count each case with
`TOTK_TRACE=svc,sched` first; fight.txt fps must not drop.
7. Line width 4.5 (check 14): dynamic `wideLines`.
8. VUID-vkCmdDispatch-None-06479 (check 20): a D32 copy of the 4x4 R32F placeholder sampled with depth compare.
Still reported with in-world validation (2026-10-23), together with a fragment write to Location 0 with no
colour attachment.
12. `vk_memory.c` `defer()` (unverified, `build/archive/v121-val/NOTES.md`): an object destroyed while frame F is
recorded is stamped with F-1 and may be freed before F's commands that use it are submitted.
9. Masked clears (Maxwell 1.3 / check 3): fix written and parked in `build/archive/v121-clr`; merge if the census finds a
partial-mask clear.
10. GPU timestamps (port-lessons T1): find whether dynamic resolution reads the report difference before writing real
Worked in this order.
22. Shader census for the open graphics lessons (port-lessons G3, G6), offline with no game run: how many TotK shaders
fetch from buffer textures and how many clears use a partial mask.
23. Image aliasing over GPU-only pool memory (Maxwell 2.3 / check 7): count distinct texture keys per address per
frame; the flight recorder counts new aliases. Likely the cause of item 2.
24. `VK_KHR_index_type_uint8` (Maxwell check 9): drops the CPU widening of 130-170 byte-index draws per frame.
25. Texture gather rounding on AMD (Maxwell 2.10): yuzu's sub-pixel offset at `ImageGather` fixed BotW shadow edges.
26. Horizon scheduling fidelity (port-lessons S1, S2, S3, S5, S6): wake a better-priority thread on the signaller's core
at SVC return; pin ideal-core -2 and main threads to core 0. Count each case with `TOTK_TRACE=svc,sched` first;
fight fps must not drop.
27. Line width 4.5 (Maxwell check 14): dynamic `wideLines`.
28. `vk_memory.c` `defer()` (unverified): an object destroyed while frame F is recorded is stamped with F-1 and may be
freed before F's commands that use it are submitted.
29. Masked clears (Maxwell 1.3 / check 3): a fix was written and parked; merge one if the census (item 22) finds a
partial-mask clear.
30. GPU timestamps (port-lessons T1): find whether dynamic resolution reads the report difference before writing real
GPU times per report.
11. MacNativeGames since our pin `b75be8c` (245 commits, fetched): kernel sync `dab728a` (S6), NVN texture sizes
`3c482a7`, CPU reads of small render targets `8a29e0a` (item 3), border colour `29dd997`. Add lessons, move the
pin and fix the `refs/MacNativeGames` line citations in `docs/`.
31. MacNativeGames since our pin `b75be8c` (245 commits): kernel sync `dab728a` (S6), NVN texture sizes `3c482a7`,
CPU reads of small render targets `8a29e0a` (item 5), border colour `29dd997`. Add the lessons, move the pin and fix
the `refs/MacNativeGames` line citations in `docs/`.
32. Maxwell sources not read yet (maxwell.md section 8).
## Details for later items
## Release and platforms
- In-game menu, agreed with the user 2026-10-23. Base: LAS Recomp's menu (MIT, same Vulkan base as ours):
`refs/LASRecomp/runtime/nvn/vulkan/imgui_glue.cpp` (Dear ImGui on our device and dynamic rendering),
`runtime/ui/menu.mm`, `option_rows.mm`, `controls_ui.mm`; SavageWindRecomp has the same menu. Opens with F1/Esc or
Minus+Plus. While it is open, the game gets no input and keeps running (no pause). Every setting is saved to
`totk.ini`. Drawn after the blit of the game image into the swapchain image (`gfx_window.c` around line 536).
Linux comes later (SDL3 window, item 17): the menu and settings code stays free of Win32; only a thin adapter feeds
window and input events to ImGui. Menu text goes through a translation catalog (SavageWindRecomp
`runtime/ui/i18n.mm`), English and Russian. Stages, one branch each:
1. Frame: ImGui, open and close, input, live settings with `cfg_save`, catalog; pages video (fullscreen and window
size, FPS counter, frame limit 30 or 60), controls (rumble strength and curve, gyro on or off), sound (volume),
quit.
2. The remapping page (`controls_ui.mm`; the bindings of `input_map.c` and
[controls.md](controls.md) become the defaults) and mouse sensitivity.
Each platform item gets a written design first, agreed with the maintainer.
Later pages: AMD FSR 1 or bilinear scaling of the 900p image to the window (LAS Recomp's Windows upscaler); a
frame-time graph with the wait breakdown of `TOTK_TRACE=perf` (also on F10); VSync (FIFO) for 60 Hz displays
without VRR, if testers report double frames under back-edge pacing; gyro sensitivity.
33. **Release**: fix what stops play on the test machines, then publish the repository and a first installer release
([installer.md](installer.md)). Runs on more GPUs (NVIDIA, Vega, weaker CPUs, [tester-guide.md](tester-guide.md))
go into one table: GPU, driver, CPU, game version, fps in field and fight, hitches, errors and crashes, with a log
per machine.
34. **Platform layer**: no Win32 outside `runtime/platform/`. `tools/check_platform.py` counts 1479 uses in 41 files
and fails on `astc_probe.c`, `gfx_abi_probe.c`, `input.h`, `motion_fusion.c`, `movie_probe.c`, `ov_movie.c`,
`swkbd_win.c`, `vk_astc.c` and `vk_exec_draw.c`.
35. **Linux**: `runtime/platform/linux.c`, split as SavageWindRecomp splits its windows, linux and macos files. Write
tracking (`host.h` `mem_written_pages`, `mem_freeze` / `mem_thaw` / `mem_frozen`, used by the VRAM mirror and the
texture checks): freezing maps to `mprotect` plus a `SIGSEGV` handler; a kernel write (`read()` into guest memory)
returns `EFAULT` instead of faulting, so the same thaw-before-read sites apply. Written pages: the `PAGEMAP_SCAN`
ioctl with write-protect matching (kernel 6.7+, made for Wine's `GetWriteWatch`); on older kernels, write-protect
the mirrored and texture-bound pages after each sync and mark them in the fault handler (Ryujinx), uploading pools
the game rewrites every frame whole instead of tracking them. Soft-dirty (`/proc/self/clear_refs`) is process-wide
and slow, a last resort. Under Proton the Windows build already works: Wine emulates both.
36. **Steam Deck**: RADV offers Vulkan 1.3 and `VK_EXT_external_memory_host`; 4 Zen 2 cores, so expect 30-40 fps.
37. **Launcher**: one exe for Windows and Linux, SDL3 and Dear ImGui (SavageWindRecomp `runtime/ui/launcher.mm`), with
Play, Settings, Game files and Quit. Settings that need a restart go there, and it is the recovery path when a
setting stops the boot. The installer already covers checking, extracting, building and preparing shaders.
Live settings: today each module reads its `cfg_get` string once and keeps the value (`rumble_cfg` in
`ov_input.c`). The menu needs `cfg_set` and a version counter that consumers check (cheap; per-frame readers
re-read only when it changes), and `cfg_save` that rewrites only the changed lines of `totk.ini`, keeps the user's
comments and adds a missing key under its section (LAS Recomp's `settings_save` rewrites the whole file). A key
set in the environment shows greyed out in the menu. Settings read only at start (RomFS mods, shader preparation,
operation mode) are marked "after restart".
## Later
Later: async shader builds, the software keyboard moved onto SavageWindRecomp's `osk.mm`. Rendering above the
game's 900p is a separate study (a game-side resolution patch, as Switch mods do, or scaling every render target
ourselves); MacNativeGames has neither (render scale fixed at 1).
- Gyro: the user's logs show only Xbox One and Series X pads, which have no gyro. With a DualSense or Pro Controller,
check Steam Input (it presents pads as a virtual Xbox pad without sensors) and the game's own motion-aiming option.
- Launcher (plan item 20): one exe for Windows and Linux, SDL3 and Dear ImGui (SavageWindRecomp
`runtime/ui/launcher.mm`, `tools/fetch_zig.sh`).
- The player picks the base game (XCI or NSP), the 1.2.1 update and keys. The launcher checks the version,
extracts, generates and compiles the game code with a bundled compiler (Zig, `zig cc`) and an embedded Python or
a native generator, then prepares the shaders. About 4 minutes on 12 cores, longer on a Steam Deck.
- Configuration screen: Play, Settings, Game files, Quit. Settings that need a restart go there.
- It is the recovery path when a setting stops the boot.
- The package ships no game code.
- GPU memory over long sessions (port-lessons P3): never measured. MacNativeGames' TotK reached its 5000 MB GPU
budget after 2 h 43 min (their issue #72) and grew from 4.5 to 6.25 GiB resident; their dead-serial hash sets
reached ~1 GiB after 3 h. Our textures are destroyed when their pool range goes or a new texture takes the address
(`vk_texture.c` `entry_of`, `vk_texture_range_gone`), pools at Finalize, Vulkan objects deferred. Started in
`build/archive/v121-mem` (paused 2026-10-23): a memory line every 1800 frames (VMA heaps, textures, pools, pipelines) and
a list of growing containers; then a 2-3 h session.
- Attachment feedback loops (`build/archive/v121-fb/HANDOFF.md`, Maxwell 1.9 / check 10): 425-667 draws per frame sample
G-buffer targets of the open pass, all at the fragment's own pixel. A spec violation with no visible symptom tied to
it; the v1 fix lost grass (image recreation). Parked until a captured glitch points here.
- Render passes ended by uniform updates and clear-only work (port-lessons P2).
- Map tour (the user's idea): teleport Link across the map by writing position, time of day and weather in guest
memory, to fill the caches on a first run and to serve as an automatic test (crashes, validation, fps per region).
- Community ExeFS patches (`.ips`, `.pchtxt` for 1.2.1): apply them through the generator's patch table
(`recomp/patches.py`); RomFS mods already load (`romfs.c`, `TOTK_ROMFS_MODS`). Code-module mods (exlaunch
`subsdk9`) need porting one by one.
- Faster save loading, asynchronous texture write-back. With 60 fps, keep menus, chests and cutscenes at 30 as
SavageWindRecomp does (`runtime/hle/framepace.c`; [prior-art.md](research/prior-art.md) section E). A trimmed
pipeline key (SavageWindRecomp).
- Maxwell sources not read yet (maxwell.md section 8).
38. **In-game menu** (branch `task/menu`, in progress). Base: LAS Recomp's menu (MIT, same Vulkan base as ours):
`refs/LASRecomp/runtime/nvn/vulkan/imgui_glue.cpp` (Dear ImGui on our device and dynamic rendering),
`runtime/ui/menu.mm`, `option_rows.mm`, `controls_ui.mm`; SavageWindRecomp has the same menu. It opens with F1/Esc
or Minus+Plus; while it is open the game gets no input and keeps running. Every setting is saved to `totk.ini`.
It is drawn after the blit of the game image into the swapchain image (`gfx_window.c`). The menu and settings code
stays free of Win32; a thin adapter feeds window and input events to ImGui. Menu text goes through a translation
catalog (SavageWindRecomp `runtime/ui/i18n.mm`), English and Russian. Stages, one branch each:
1. Frame: ImGui, open and close, input, live settings with `cfg_save`, the catalog; pages for video (fullscreen
and window size, FPS counter, frame limit 30 or 60), controls (rumble strength and curve, gyro on or off),
sound (volume) and quit.
2. The remapping page (`controls_ui.mm`; the bindings of `input_map.c` and [controls.md](controls.md) are the
defaults) and mouse sensitivity.
Later pages: AMD FSR 1 or bilinear scaling of the 900p image to the window (LAS Recomp's Windows upscaler); a
frame-time graph with the wait breakdown of `TOTK_TRACE=perf`; VSync (FIFO) for 60 Hz displays without VRR, if
testers report double frames under back-edge pacing; gyro sensitivity.
Live settings: today each module reads its `cfg_get` string once and keeps the value (`rumble_cfg` in
`ov_input.c`). The menu needs `cfg_set` and a version counter that consumers check (per-frame readers re-read only
when it changes), and a `cfg_save` that rewrites only the changed lines of `totk.ini`, keeps the user's comments and
adds a missing key under its section (LAS Recomp's `settings_save` rewrites the whole file). A key set in the
environment shows greyed out. Settings read only at start (RomFS mods, shader preparation, operation mode) are
marked "after restart".
Rendering above the game's 900p is a separate study (a game-side resolution patch, as Switch mods do, or scaling
every render target ourselves); MacNativeGames has neither. The software keyboard could move onto
SavageWindRecomp's `osk.mm`.
39. **Game version 1.4.3** (branch `task/v143`, paused). The 1.4.3 files extract and verify, and the generator runs on
them unchanged. Estimate: one day to the title screen, two to three to play at 60 fps. Steps:
1. `stg` no-op lift, DT_RELR in `recomp/nso.py` and `runtime/loader.c`, symbol count from DT_GNU_HASH for `sdk`
and `subsdk0`.
2. Jump tables: 26 disagreements and 83 unresolved sites down to 0 unexplained, with 1.2.1 still at 0.
3. Tools take a version instead of `v121`; re-measure the `--probe-loader` table (`loader.c` `expect[]`) and
`boot.c` `expected_inits`; new boot anchors (`boot.c` `CHECKPOINT_RET`, `NVN_RET`).
4. RELRO (`nn::ro::ProtectRelro`) and the new SDK imports; run to the title screen.
5. `recomp/patches-v143.txt` from MacNativeGames `game_patches_v143.c` (fps60, bounce, cloth; the real-time step
rewritten for the `sys+0x1da` coefficient); the player position of `frame_rate.c` `player_pos`;
`make_romfs_patches.py --version` (`Common.Product.140`).
6. Audio REV15 is mostly in place (`audren.c`, `audio_mixer.c`): fix the REV11 self-test, check the override
signatures (biquad, font decode), and listen for render differences in play.
40. **Community ExeFS patches** (`.ips`, `.pchtxt` for 1.2.1): apply them through the generator's patch table
(`recomp/patches.py`). RomFS mods already load (`romfs.c`, `TOTK_ROMFS_MODS`). Code-module mods (exlaunch
`subsdk9`) need porting one by one.
41. **Frame rates above 60 and VRR.**
42. **Map tour**: teleport Link across the map by writing position, time of day and weather in guest memory, to fill
the caches on a first run and to serve as an automatic test (crashes, validation, fps per region).
+8 -8
View File
@@ -6,7 +6,8 @@ holds only the game; the installer and its tools stay outside it.
## What the player does
1. Downloads `TotK-Setup-<version>-windows.zip` from GitHub Releases, unpacks it anywhere and starts `TotK-Setup.exe`.
1. Downloads `TotK-Setup-<version>-windows.zip` from GitHub Releases (none is published yet), unpacks it anywhere and
starts `TotK-Setup.exe`.
2. Picks:
- the base game (XCI or NSP) and the 1.2.1 update (NSP);
- their `prod.keys`;
@@ -41,8 +42,7 @@ release that changes nothing game-derived skips the rebuild.
2. **Extract** ExeFS and RomFS into the install folder and verify the hashes.
3. **Lift** the ExeFS to C (`recomp/gen.py`, `recomp/patches-v121.txt`) into a temp folder next to the installer.
4. **Compile** the generated C, `modules.c` and `romfs.c` (they bake per-install layout and RomFS hashes) and link
them with the prebuilt runtime library into `totk.exe` (`build_game.py --runtime-lib`, proven on task/llvmmingw:
3 min on 24 cores).
them with the prebuilt runtime library into `totk.exe` (`build_game.py --runtime-lib`; about 3 min on 24 cores).
5. **Prepare** the RomFS patches and the shaders (`tools/make_romfs_patches.py`, `tools/prepare_shaders.py`,
`totk.exe --prepare-shaders`) in the install folder.
6. **Clean up** the temp folder (generated C and objects, about 1.3 GB).
@@ -79,7 +79,7 @@ python -m installer --base FILE --update FILE --keys FILE --lang CODE --dest DIR
## Release layout
The unpacked release; `tools/make_release.py` assembles it, CI zips it:
The unpacked release; `tools/make_release.py` assembles it and `--zip` packs it:
```
TotK-Setup.exe starts python/pythonw.exe -m installer.gui (installer/launcher/launcher.c, no console)
@@ -96,7 +96,8 @@ totk.ini.example, VERSION the default ini; the release string (git describe of
- SDL3 comes from the upstream release, not MSYS2: MSYS2's DLL imports the LGPL libiconv.
- Every bundled third-party piece gets a row in `THIRD_PARTY_NOTICES.md`.
- The release contains nothing game-derived; `tools/check_content.py` runs over it in CI.
- The release contains nothing game-derived; `make_release.py` runs `tools/check_content.py` over the folder before it
finishes.
## Constraints
@@ -106,7 +107,7 @@ totk.ini.example, VERSION the default ini; the release string (git describe of
...`), which prints one JSON progress event per line. Tests and CI use the CLI.
- Paths may hold any Unicode characters (a Cyrillic user name puts the temp and install folders under it). Every exe
the setup runs or builds reads its arguments and paths as UTF-8 through an `activeCodePage` manifest: hactool
(`toolchain/hactool/unicode-patches.diff`), totk.exe (`runtime/totk.rc`), ninja (upstream). The Python steps write
(our patch, [toolchain-msys2-python.md](toolchain-msys2-python.md)), totk.exe (`runtime/totk.rc`), ninja (upstream). The Python steps write
their files and logs as UTF-8, and `build_game.py` quotes paths with spaces on its Ninja command lines.
- A game file whose data fails its hash checks or ends early stops the setup with `check.input_damaged`, which names
the file and asks to copy it again (`extract.DamagedFile`). A failed merge checks the base Program NCA alone to tell
@@ -115,6 +116,5 @@ totk.ini.example, VERSION the default ini; the release string (git describe of
## Later
- Re-warm the driver cache on start after a move, GPU or driver change (WIP on task/rewarm: stamp in
`shader-prepared.bin`).
- Re-warm the driver cache on start after a move, GPU or driver change ([backlog.md](backlog.md) item 12).
- NSZ and XCZ input. Linux release.
+61 -63
View File
@@ -2,8 +2,8 @@
Reference for diagnosing graphics bugs. Each item: what Maxwell (GM20B, 3D class `B197`, compute `B1C0`) and NVN do,
what Vulkan / AMD (RDNA4, our GPU0) do instead, how emulators and ports handle it, and the source. Items are ordered by
how likely they are to cause visible artifacts. "Ours:" marks what our runtime does (grep-level look, see the last
section). Licensing: yuzu/suyu are GPL, cited for behaviour only.
how likely they are to cause visible artifacts. "Ours:" marks what our runtime does (grep-level look, see section 7;
our code is cited by file and function). Licensing: yuzu/suyu are GPL, cited for behaviour only.
Source shorthands:
@@ -32,7 +32,7 @@ Source shorthands:
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 1.1 | **Colour target the fragment shader does not write keeps its old texel**, even with blending enabled. | Undefined value written/blended. | NXN: zero write mask and no blend for unwritten outputs (`reflection colors`). Already fixed here. | NXN:122; MNG `games/totk/tests/metal_semantics/probe.m:5` |
| 1.2 | **Unwritten vertex outputs read as (0, 0, 0, 1)** in the next stage, including the unwritten components of a partly written output (VS writes xyz, FS divides by w). | FS input with no VS output: interface mismatch, value undefined; an unwritten component of a written output is undefined (AMD: whatever the register holds, often 0). | Ryujinx initialises exactly the components the next stage reads, but only when stages are linked (`Translation/Translator.cs:212-227`, `NextInputAttributesComponents`); position starts (0,0,0,1) (`:259`). NXN Link's Awakening: sun shadow lookups divided by w = 0, scene dim, no shadows. Ours: missing outputs padded with **zero**, partial outputs not initialised (section 7, check 2). | NXN:84, NXN:151 |
| 1.2 | **Unwritten vertex outputs read as (0, 0, 0, 1)** in the next stage, including the unwritten components of a partly written output (VS writes xyz, FS divides by w). | FS input with no VS output: interface mismatch, value undefined; an unwritten component of a written output is undefined (AMD: whatever the register holds, often 0). | Ryujinx initialises exactly the components the next stage reads, but only when stages are linked (`Translation/Translator.cs:212-227`, `NextInputAttributesComponents`); position starts (0,0,0,1) (`:259`). NXN Link's Awakening: sun shadow lookups divided by w = 0, scene dim, no shadows. Ours: missing outputs padded with (0, 0, 0, 1), unlinked outputs initialised by translator patch 0006 (section 7, check 2). | NXN:84, NXN:151 |
| 1.3 | **Clears honour the scissor and the clear's own channel / stencil write mask**, and may come between draws inside a pass. `SET_CLEAR_SURFACE_CONTROL` (0x10f8) has `RESPECT_STENCIL_MASK`, `USE_CLEAR_RECT`, `USE_SCISSOR0`, `USE_VIEWPORT_CLIP0`. | `vkCmdClearAttachments` takes a rect but **ignores the colour write mask**; load-op clears are whole-attachment. | NXN/MNG draw a triangle with the clear's mask (`clear_color_tri`, `clear_ds_tri`); TotK uses mid-pass, partial-mask and partial-scissor clears (NXN:174). yuzu: "red dot" was clears hitting the wrong RT index (YZ-2305, PR 10243). Hardware recipe (DK3D): `CLEAR_BUFFERS` (`0x674` = 0x19d0) carries the colour channel mask (bits 2-5), depth (0), stencil (1), target id (6-9) and layer (10-20) in one word; `ClearBufferFlags` (`0x43E` = 0x10f8) is set once to `StencilMask | Scissor` (`maxwell/gpu_3d_base.cpp:69`), so every clear is cut by scissor 0 and its stencil bits by the stencil front write mask register, and DK3D's colour clear does not program `ColorWriteMask` (`0x680`). A stencil clear writes `StencilFrontMask` (`0x4E7`) and `ClearStencil` (`0x368`) just before the clear and restores the shadowed state after (`gpu_3d_base.cpp:497-510`). Multisample raster is switched off around a colour clear (`:459, :465`). Arrays: an MME macro repeats the clear for every layer (`maxwell/clear_buffers.mme:5-22`). No pass concept: clears sit between draws. Ours: masked colour and stencil clears are **skipped** (check 3). | OGD 0x10f8; NXN:81, NXN:174; DK3D `maxwell/gpu_3d_base.cpp:444-512`, `engine_3d.def:305, 644` |
| 1.4 | **Conditional rendering** (`SET_RENDER_ENABLE_A..C` 0x1550-0x1558, NVN `SetRenderEnableConditional`) compares two 64-bit counters at `addr` and `addr+16` on the GPU, in command order. TotK wraps nearly every clear in it. A `TIMESTAMP` report writes 0 to the counter field. | `VK_EXT_conditional_rendering` tests one 32-bit word against zero. | NXN: honouring it fixed the black 3D scene (light-volume depth never cleared). deko3d has no conditional rendering at all (no `SET_RENDER_ENABLE` in `engine_3d.def`), so it cannot settle the compare rule. Ours: evaluated on the CPU at record time; a report from an unfinished submission counts as 0 (check 5). | OGD; NXN:173 |
| 1.5 | **Depth mode** is runtime state: `nvnDeviceSetDepthMode` near = -w (GL, NVN default) or 0. Register `SET_VIEWPORT_Z_CLIP` (0x0d7c) `NEGATIVE_W_TO_POSITIVE_W` / `ZERO_TO_POSITIVE_W`. | Vulkan clips z < 0 unless `VK_EXT_depth_clip_control` `negativeOneToOne`. | Ryujinx infers the mode from the viewport transform, falling back to the register (`GetDepthMode`, RYU-SU). NXN: wrong mode either clips everything (black window) or puts all depth in 0.5..1 (DOF blurs the screen). Ours: `negativeOneToOne` from NVN state. DK3D programs both halves: `SetDepthMode` (`0x35F` = 0xd7c) selects the pre-transform clip range, and the viewport transform maps z to [near, far] itself: scale z = `0.5 * (far - near)` and offset z = `0.5 * (near + far)` for -1..1, scale `far - near` and offset `near` for 0..1 (`maxwell/gpu_3d_base.cpp:143-147, 336-343`). Same maths as Vulkan `negativeOneToOne`. | OGD 0x0d7c; NXN:55-64, NXN:150; DK3D `maxwell/gpu_3d_base.cpp:136-147, 321-362` |
@@ -44,9 +44,9 @@ Source shorthands:
| 1.11 | **Per-target write masks**: `RtColorMask[i]`, or entry 0 for all when `RtColorMaskShared`. `SET_SINGLE_CT_WRITE_CONTROL` (0x0f90). A colour target with format 0 is disabled. | Per-attachment `colorWriteMask`. | RYU-SU `UpdateRtColorMask`, `IsRtEnabled` ("Colors are disabled by writing 0 to the format"). | OGD 0x0f90 |
| 1.12 | **sRGB render target views**: NVN encodes on write when the view format is sRGB over a linear texture. Maxwell also has a global `SET_SRGB_WRITE` (0x15b8). | Format of the attachment view decides; needs `MUTABLE_FORMAT`. | NXN Mario: attaching the base texture stored linear values, picture darker. Ours: RT views take the view format (`view_format`). | OGD 0x15b8; NXN:69 |
| 1.13 | **Compressed and 3D targets**: agl's GPU BC4 encoder renders blocks through an `RGBA16UI` view, one plane of a 32×32×32 BC4 3D texture per pass. NVN renders a 3D texture slice by slice. | Needs `BLOCK_TEXEL_VIEW_COMPATIBLE` + `EXTENDED_USAGE`, `2D_ARRAY_COMPATIBLE`. | NXN shadow textures (`bcrt_attach`). yuzu: wrong block depth on 3D slices gave Gloom textures on terrain (YZ-2305, PR 10433). Already fixed here. | NXN:132, NXN:176 |
| 1.14 | **Draw with no render target** (fragment shader only writes an SSBO, 1×1 viewport) runs normally. | Needs an attachment-less pass with explicit render area. | NXN `bare_dims`: cave ambient light came back. Ours: area of viewport 0 (`vk_exec.c:229`). | NXN:177 |
| 1.14 | **Draw with no render target** (fragment shader only writes an SSBO, 1×1 viewport) runs normally. | Needs an attachment-less pass with explicit render area. | NXN `bare_dims`: cave ambient light came back. Ours: area of viewport 0 (`vk_exec.c` `resolve_rt`). | NXN:177 |
| 1.15 | **Window origin**: NVN default lower-left (GL); TotK switches to upper-left. Y flip and scissor flip follow. | Vulkan upper-left; negative viewport height to flip. | Ryujinx flips scissor against screen height when Y-negate is on (RYU-SU `UpdateScissorState`). | NXN:145 |
| 1.16 | **Multiple viewports / scissors** (16), selected by `ViewportIndex` output. | Needs `multiViewport` and `shaderOutputViewportIndex`. | Ours: one viewport, one scissor; differing scissors logged (`nvn_api_cmd.c:499-508`). | OGD 0x192c |
| 1.16 | **Multiple viewports / scissors** (16), selected by `ViewportIndex` output. | Needs `multiViewport` and `shaderOutputViewportIndex`. | Ours: one viewport, one scissor; differing scissors logged (`nvn_api_cmd.c`). | OGD 0x192c |
| 1.17 | **Fragment output saturation** per target: `SET_PS_SATURATE` (0x13a8) clamps output n to 0..1 or -1..1 in fixed function. NVN does not expose it (GLSLC emits `.SAT` in code). | None. | Not emulated by Ryujinx; listed so a clamp difference is not chased in the wrong place. | OGD 0x13a8 |
| 1.18 | **New memory reads as zero** (fresh pool pages); feedback effects never clear their state texture. | New image content undefined. | NXN `tex_zero_fill`. | NXN:80 |
| 1.19 | **MSAA**: `nvnCommandBufferDownsample` resolves; depth-stencil downsamples are copies the game does itself. | `vkCmdResolveImage` colour only; integer formats pick one sample. | NXN LA: stencil lost in the half-size depth copy, no AO. | NXN:148 |
@@ -55,19 +55,19 @@ Source shorthands:
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 2.1 | **Automatic block height**: NVN truncates `height_in_blocks * 1.5 / 8` before picking the GOB power of two (deko3d rounds up). Wrong H reads padding: 160×160 BC3 warp pad half black. Allocation size is the same, so size checks do not catch it. Mip levels shrink the block height while the level fits in half of it. | Opaque optimal tiling. | MNG fixed (40 SDK-measured cases, `games/totk/tests/texture_auto_layout/probe.c`). Ours: truncating form already (`runtime/nvn_tex.c:149`). DK3D reads: height in block rows (rounded up), x 1.5, then `(h + 7) / 8` rounded up, then the largest power of two <= that, capped at 16 GOBs (`dk_image.cpp:444-447`, `pickTileSize` `:13-20`); 3D uses `depth + depth / 2` directly as the GOB count (`:451-454`); video images are fixed at 2 GOBs (`:438`). Per level, the shift drops while `unit << (shift - 1) >= level dimension` with unit 8 rows / 1 slice (`adjustTileSize` `:23-37`, used at `:89-91`), width tile is always 0. Array layers are padded to the block shrunk to the full height / depth (`alignLayerSize` `:57-72`). Every one of these matches `nvn_tex.c:60-66, 115-125, 149-150` except the rounding. | MNG `docs/how-it-works.md:47-53`; DK3D `dk_image.cpp:13-37, 57-72, 80-103, 436-455` |
| 2.2 | **Textures filled by the CPU with no NVN flush** (TotK terrain: two 121-layer ASTC 8×8 arrays, 42 MB each; BC4 material textures read back with `ReadTexels` and copied into a 5120×5120 roughness atlas). The CPU and GPU share memory, so no flush is needed on the Switch. | Host images are copies; must detect CPU writes. | NXN write-protects texture pages (`tex_dirty_upload`); zero ASTC decodes magenta, zero BC black. yuzu: small CPU writes into GPU-used pages not invalidated gave slow rain/snow particles and teleport particle corruption (YZ-2306, PR 10942). Ours: `GetWriteWatch` generations (`vk_memory.c:349-380`). | NXN:174-175 |
| 2.1 | **Automatic block height**: NVN truncates `height_in_blocks * 1.5 / 8` before picking the GOB power of two (deko3d rounds up). Wrong H reads padding: 160×160 BC3 warp pad half black. Allocation size is the same, so size checks do not catch it. Mip levels shrink the block height while the level fits in half of it. | Opaque optimal tiling. | MNG fixed (40 SDK-measured cases, `games/totk/tests/texture_auto_layout/probe.c`). Ours: truncating form already (`runtime/nvn_tex.c`, the block-height pick). DK3D reads: height in block rows (rounded up), x 1.5, then `(h + 7) / 8` rounded up, then the largest power of two <= that, capped at 16 GOBs (`dk_image.cpp:444-447`, `pickTileSize` `:13-20`); 3D uses `depth + depth / 2` directly as the GOB count (`:451-454`); video images are fixed at 2 GOBs (`:438`). Per level, the shift drops while `unit << (shift - 1) >= level dimension` with unit 8 rows / 1 slice (`adjustTileSize` `:23-37`, used at `:89-91`), width tile is always 0. Array layers are padded to the block shrunk to the full height / depth (`alignLayerSize` `:57-72`). Every one of these matches `nvn_tex.c` except the rounding. | MNG `docs/how-it-works.md:47-53`; DK3D `dk_image.cpp:13-37, 57-72, 80-103, 436-455` |
| 2.2 | **Textures filled by the CPU with no NVN flush** (TotK terrain: two 121-layer ASTC 8×8 arrays, 42 MB each; BC4 material textures read back with `ReadTexels` and copied into a 5120×5120 roughness atlas). The CPU and GPU share memory, so no flush is needed on the Switch. | Host images are copies; must detect CPU writes. | NXN write-protects texture pages (`tex_dirty_upload`); zero ASTC decodes magenta, zero BC black. yuzu: small CPU writes into GPU-used pages not invalidated gave slow rain/snow particles and teleport particle corruption (YZ-2306, PR 10942). Ours: `GetWriteWatch` generations (`vk_memory.c`, `mem_written_pages`). | NXN:174-175 |
| 2.3 | **Same storage, new texture object every frame** (transient targets, deferred handles). Same storage with a different descriptor reinterprets the same block-linear bytes. | Two `VkImage`s over one allocation with optimal tiling do not share a defined layout (AMD tiling and DCC metadata are per image); a new image starts `UNDEFINED`. | NXN shares host textures by `(pool, offset, description)`; MNG keeps a "live texture at address" redirect. yuzu: whole areas black for a frame on camera changes from texture-cache alias/overlap ordering (YZ-2305, PR 10418). Ours: GPU-only pool textures are `VkImage`s bound onto pool memory (check 7). | NXN:70; MNG `docs/how-it-works.md:67-71` |
| 2.4 | **Deferred texture handles** (`BindTexturesDeferred`): the GPU reads the handle from memory when the command runs; BotW records command blocks once and writes handles later. | n/a | NXN BotW: handles copied at record time were zero, 3D scene black. | NXN:129 |
| 2.5 | **Border colours**: any RGBA (TSC words 4-7, plus sRGB border fields). TotK/BotW grass interaction map clamps to (0.5, 0.5, 0.5, 0.5), its "untouched" value. | Three fixed colours unless `VK_EXT_custom_border_color` (+ `customBorderColorWithoutFormat`); integer formats need `INT_CUSTOM`. | MNG emulates in the shader; with transparent black, grass away from the player lay flat and showed no cut (MNG issue #49). Ours: custom border when supported, else transparent black (check 11). | G80TEX; MNG `games/totk/third_party/d2r_gfx/gfx/nvn/nvn_mtl.m:5041-5045` |
| 2.6 | **sRGB decode** is a TIC bit (`G80_TIC_2_SRGB_CONVERSION`) separate from the format; TSC has its own `SRGB_CONVERSION` (word 0 bit 13). NVN exposes sRGB as formats. | Format decides. | NVN-level translation by format is enough. | G80TEX:197, :377 |
| 2.7 | **Swizzles** per texture and per view (`TextureBuilderSetSwizzle`, `TextureViewSetSwizzle`); BotW layout captures rebuild a texture on the same storage with (1, 1, 1, R) or alpha 1. Default per-format mapping R8 → (R, 0, 0, 1). | `VkComponentMapping` on the view. | NXN: font atlas white boxes, HUD dark boxes without it. Ours: mapped (`vk_exec_draw.c:328`). | NXN:68, NXN:140 |
| 2.7 | **Swizzles** per texture and per view (`TextureBuilderSetSwizzle`, `TextureViewSetSwizzle`); BotW layout captures rebuild a texture on the same storage with (1, 1, 1, R) or alpha 1. Default per-format mapping R8 → (R, 0, 0, 1). | `VkComponentMapping` on the view. | NXN: font atlas white boxes, HUD dark boxes without it. Ours: mapped (`vk_exec_draw.c` `get_view`). | NXN:68, NXN:140 |
| 2.8 | **Sample dimension comes from the instruction**: a non-array sample of an array texture reads layer 0; 1,512 BotW shaders sample a cube as a cube array. | View type must match the declared type. | NXN: 2D array bound as 2D gave one pale colour (washed-out scene); cubes created as 6-layer arrays with cube / cube-array views. Ours: views per resource type (`get_view`). | NXN:121, NXN:131 |
| 2.9 | **LOD**: TSC min/max LOD clamp, LOD bias, `TWO_D_NO_MIPMAP` texture type, a min filter without mips stays on the base level; TIC carries its own max anisotropy and aniso quality fields. | `minLod`/`maxLod`, `mipLodBias` limited by `maxSamplerLodBias`. | yuzu: anisotropy heuristics for mods forcing trilinear (YZ-2306, PR 10744). Ours: non-mip filter → `maxLod = minLod + 0.25`, bias clamped (`vk_texture.c:1008-1013`). | G80TEX |
| 2.9 | **LOD**: TSC min/max LOD clamp, LOD bias, `TWO_D_NO_MIPMAP` texture type, a min filter without mips stays on the base level; TIC carries its own max anisotropy and aniso quality fields. | `minLod`/`maxLod`, `mipLodBias` limited by `maxSamplerLodBias`. | yuzu: anisotropy heuristics for mods forcing trilinear (YZ-2306, PR 10744). Ours: non-mip filter → `maxLod = minLod + 0.25`, bias clamped (`vk_texture.c` `make_sampler`). | G80TEX |
| 2.10 | **Texture gather rounding**: Maxwell sub-texel precision differs from AMD/Intel; edge texels picked by TLD4 differ by one. | Implementation-defined `subTexelPrecisionBits`. | yuzu adds a sub-pixel offset to gathers on non-NVIDIA hosts: fixed BotW shadow artifacts at object edges ("shader_recompiler: Add subpixel offset for correct rounding at ImageGather", <https://git.openpunk.com/OpenPunk/yuzu/src/commit/780240e6979b198e7bd10feaad5399b8b4b63762>, title only). | — |
| 2.11 | **Gather offsets**: `TLD4.PTP` takes four per-texel offsets, possibly from registers. | `ConstOffsets` must be constant. | Ours: `QueryHostSupportsNonConstantTextureOffset() => false` makes Ryujinx emulate register offsets (`tools/xlate/Program.cs:96-99`). | RYU-SH `Translation/Optimizations` (TexturePass) |
| 2.12 | **Depth compare** (`TSC` depth compare + `TIC_4_DEPTH_TEXTURE`), min/max reduction filtering. | `compareEnable`; reduction mode needs `samplerFilterMinmax` and is not allowed with compare. | Ours: reduction dropped when compare is on (`vk_texture.c:1037`). | G80TEX |
| 2.13 | **ASTC / BC**: native ASTC; zero ASTC block = error colour on hosts. | RX 9070 lacks ASTC: CPU decode to RGBA8. yuzu offered ASTC recompression to BC1/BC3 for low VRAM (YZ-2305, PR 10398). | Ours: `tex_astc.c`. | `runtime/tex_astc.c` |
| 2.11 | **Gather offsets**: `TLD4.PTP` takes four per-texel offsets, possibly from registers. | `ConstOffsets` must be constant. | Ours: `QueryHostSupportsNonConstantTextureOffset() => false` makes Ryujinx emulate register offsets (`tools/xlate/Program.cs`). | RYU-SH `Translation/Optimizations` (TexturePass) |
| 2.12 | **Depth compare** (`TSC` depth compare + `TIC_4_DEPTH_TEXTURE`), min/max reduction filtering. | `compareEnable`; reduction mode needs `samplerFilterMinmax` and is not allowed with compare. | Ours: reduction dropped when compare is on (`vk_texture.c` `make_sampler`). | G80TEX |
| 2.13 | **ASTC / BC**: native ASTC; zero ASTC block = error colour on hosts. | AMD and NVIDIA desktop GPUs lack ASTC: decode to RGBA8. yuzu offered ASTC recompression to BC1/BC3 for low VRAM (YZ-2305, PR 10398). | Ours: native upload where the device samples ASTC, else a compute-shader decode (`vk_astc.c`, `TOTK_ASTC`), CPU decode (`tex_astc.c`) as the fallback. | `runtime/vk_astc.c` |
| 2.14 | **Linear CPU-written textures** (`FLAGS_LINEAR`, small ramps, glyph caches): CPU writes visible to the GPU directly. | Must re-upload or use linear images over host memory. | NXN Mario: sky black without its 64×1 RGBA16F ramps. | NXN:75 |
## 3. Shader math
@@ -81,8 +81,8 @@ Source shorthands:
| 3.5 | **Discard (`KIL`)** keeps the quad's derivatives valid (demote semantics). | `OpKill` terminates; later derivatives in the quad undefined. | Ryujinx emits `OpKill` (`CodeGen/Spirv/Instructions.cs:508`). | — |
| 3.6 | **Implicit-LOD sampling in divergent control flow** works on Maxwell (TEX unit uses quad neighbours). | Undefined in non-uniform control flow; AMD whole-quad mode usually works. | — | VKSPEC (derivatives) |
| 3.7 | **Integer division** does not exist (compiled to `XMAD`/`IMAD` sequences); MUFU.RCP(0) = +Inf, LG2(0) = -Inf. | Same IEEE edge cases through `1/x`, `Log2`. | Low risk. | — |
| 3.8 | **FP64** in some TotK cutscene shaders. | No FP64 on some hosts. | yuzu FP64 → FP32 (YZ-2306, PR 10693); ours: `softfloat64` job flag (`tools/xlate/Program.cs:101`). | — |
| 3.9 | **Integer vertex inputs read as raw bits** (bone indices `R8UI`). | Float-declared inputs convert integers. | NXN Mario: stretched characters; re-translated with `uint` inputs. Ours: attribute types passed to `QueryGraphicsState` (`Program.cs:86-88`). | NXN:76 |
| 3.8 | **FP64** in some TotK cutscene shaders. | No FP64 on some hosts. | yuzu FP64 → FP32 (YZ-2306, PR 10693); ours: `softfloat64` job flag (`tools/xlate/Program.cs` `QueryHostSupportsShaderFloat64`). | — |
| 3.9 | **Integer vertex inputs read as raw bits** (bone indices `R8UI`). | Float-declared inputs convert integers. | NXN Mario: stretched characters; re-translated with `uint` inputs. Ours: attribute types passed to `QueryGraphicsState` (`Program.cs`). | NXN:76 |
## 4. Memory model
@@ -93,25 +93,25 @@ Source shorthands:
| 4.3 | **Semaphores / events** written by the GPU in order; CPU polls them. | Writes on a completion thread after the fence. | Ours: `vk_completion_add`, submit order. | — |
| 4.4 | **Inline uniform updates** (`UpdateUniformBuffer`) happen in command order between draws; reading the buffer at record time gives the last value. | Must snapshot. | NXN: snapshotted at encode time; Mario's wave sim diverged when two writes reordered. | NXN:71, NXN:79, NXN:82 |
| 4.5 | **GPU-written index buffers** (8-bit indices written earlier in the same submission). | No `uint8` index type without `VK_EXT_index_type_uint8`; CPU widening reads stale bytes. | NXN widens on the GPU (`wide_run`). Ours: CPU widening at record time; device-local byte indices skipped (check 9). | NXN:175 |
| 4.6 | **Compute shared memory**: 48 KiB per block on GM20B. | AMD 64 KiB. | Ours: `QueryComputeSharedMemorySize` from job (`Program.cs:82`). | OGD `clb1c0.h` |
| 4.6 | **Compute shared memory**: 48 KiB per block on GM20B. | AMD 64 KiB. | Ours: `QueryComputeSharedMemorySize` from job (`Program.cs`). | OGD `clb1c0.h` |
| 4.7 | **Virtual memory pools** map physical pool pages; the same bytes reachable at two GPU addresses. | Two `VkBuffer`s over one allocation need alias-aware barriers. | MNG `MTL4VisibilityOptionResourceAlias`. | MNG `docs/how-it-works.md:67-71` |
| 4.8 | **Command list calls**: a `CallCommands` / `CallList` is not a GPU subroutine. DK3D `dkCmdBufCallList` stores a `Call` control entry (`dk_cmdbuf.cpp:327-338`); `dkQueueSubmitCommands` walks the entries on the CPU and recurses into the called list at submit (`dk_queue.cpp:287-296`), emitting gpfifo entries that point at the command words, which the GPU fetches later (prefetch can be switched off per entry, `:176`). So list structure is fixed at submit, command words are read when fetched. | n/a | Ours: `OP_CALL` is walked at replay, `CallCommands` inlines the recording at record time (`nvn_api_cmd.c:399-404`, `vk_exec.c:571-574`). Equivalent for control flow; deferred bind handles are the data read late (2.4). | DK3D `dk_cmdbuf.cpp:327`, `dk_queue.cpp:280-298` |
| 4.8 | **Command list calls**: a `CallCommands` / `CallList` is not a GPU subroutine. DK3D `dkCmdBufCallList` stores a `Call` control entry (`dk_cmdbuf.cpp:327-338`); `dkQueueSubmitCommands` walks the entries on the CPU and recurses into the called list at submit (`dk_queue.cpp:287-296`), emitting gpfifo entries that point at the command words, which the GPU fetches later (prefetch can be switched off per entry, `:176`). So list structure is fixed at submit, command words are read when fetched. | n/a | Ours: `OP_CALL` is walked at replay, `CallCommands` inlines the recording at record time (`vk_exec.c` `walk`, `nvn_api_cmd.c` `inline_recording`). Equivalent for control flow; deferred bind handles are the data read late (2.4). | DK3D `dk_cmdbuf.cpp:327`, `dk_queue.cpp:280-298` |
## 5. Fixed function
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 5.1 | **Provoking vertex: last** (GL convention, NVN default; `SET_PROVOKING_VERTEX` 0x1684, NVN 55 `SetProvokingVertexMode`). Flat-interpolated outputs (instance/particle ids, material indices, flat normals) come from the last vertex. | **First vertex** unless `VK_EXT_provoking_vertex` with `provokingVertexMode = LAST_VERTEX`. | Ours: extension queried (`vk_device.c:205`) but no pipeline sets last-vertex mode (check 1). DK3D: `ProvokingVertexLast` (`0x5A1`) is set to 1 at queue setup and per rasterizer state from `DkProvokingVertex` (`maxwell/gpu_3d_base.cpp:76`, `gpu_3d_state.cpp:67`); `DkRasterizerState` defaults to Last (`include/deko3d.h:823`). Confirms last as the hardware-side default. | OGD 0x1684; `runtime/nvn_ext.c:396-400`; DK3D `include/deko3d.h:794-823` |
| 5.1 | **Provoking vertex: last** (GL convention, NVN default; `SET_PROVOKING_VERTEX` 0x1684, NVN 55 `SetProvokingVertexMode`). Flat-interpolated outputs (instance/particle ids, material indices, flat normals) come from the last vertex. | **First vertex** unless `VK_EXT_provoking_vertex` with `provokingVertexMode = LAST_VERTEX`. | Ours: last-vertex mode where `provokingVertexLast` is available (`vk_pipeline.c` `create_graphics`; check 1). DK3D: `ProvokingVertexLast` (`0x5A1`) is set to 1 at queue setup and per rasterizer state from `DkProvokingVertex` (`maxwell/gpu_3d_base.cpp:76`, `gpu_3d_state.cpp:67`); `DkRasterizerState` defaults to Last (`include/deko3d.h:823`). Confirms last as the hardware-side default. | OGD 0x1684; `runtime/nvn_ext.c`; DK3D `include/deko3d.h:794-823` |
| 5.2 | **Primitive restart**: any index value, compared against the raw index for any index size; can apply to lists (`SET_DA_PRIMITIVE_RESTART_TOPOLOGY_CHANGE`) and to non-indexed draws (`..._VERTEX_ARRAY` 0x0de8). | Restart only at all-ones of the index type; lists need `primitiveTopologyListRestart`. | Ryujinx enables it for draw-arrays only on GL (RYU-SU comment). NXN: TotK terrain strips use 0xffff. Ours: non-all-ones restart not replayed, logged. DK3D: `PrimitiveRestartEnable` (`0x591` = 0x1644) + `PrimitiveRestartIndex` (`0x592` = 0x1648), index written only when enabled; any value; `PrimitiveRestartWithDrawArrays` (`0x37A` = 0x0de8) is forced 0 at setup (`maxwell/gpu_3d_ibo.cpp:21-30`, `gpu_3d_base.cpp:73`). Nothing on lists vs strips beyond that. | OGD 0x1644, 0x1648; DK3D `maxwell/gpu_3d_ibo.cpp:21-30` |
| 5.3 | **Point size**: `SET_POINT_SIZE` (0x1518) when the shader does not write it; GLSLC clamps a written size to a driver constant. | Point size must be written by the shader. | Ryujinx writes the `PointSize` from graphics state at VS start (`Translation/EmitterContext.cs:84-88`); ours passes 1.0 (`Program.cs:92`) and logs `SetPointSize` (`nvn_ext.c:371-373`). | NXN:41 |
| 5.3 | **Point size**: `SET_POINT_SIZE` (0x1518) when the shader does not write it; GLSLC clamps a written size to a driver constant. | Point size must be written by the shader. | Ryujinx writes the `PointSize` from graphics state at VS start (`Translation/EmitterContext.cs:84-88`); ours reads the `SetPointSize` state from the support buffer (translator patch 0008). | NXN:41 |
| 5.4 | **Line width**, smooth lines (`SET_LINE_WIDTH_FLOAT` 0x13b0, `SET_ANTI_ALIASED_LINE`). | `wideLines`, `VK_EXT_line_rasterization`. | Ours: 1 px, logged. | OGD |
| 5.5 | **Polygon offset units** are twice the API value in the register; NVN API takes GL units. | `depthBiasConstantFactor` in format-dependent r. | Ryujinx `units / 2f` from the register (RYU-SU). Ours takes NVN API units (right) but D32F instead of D24 (1.7). DK3D `constantFactor * 2.0f` (1.7). | OGD 0x15bc, 0x187c; DK3D `maxwell/gpu_3d_state.cpp:154` |
| 5.6 | **Dual-source blending**: SRC1 factors read the shader's second output. | Needs fragment output `Location 0, Index 1`. | Ryujinx declares `Index` only when `DualSourceBlendEnable` (`Translation/Translator.cs:196`, `CodeGen/Spirv/Declarations.cs:608-617`). Ours: SRC1 factors mapped (`vk_pipeline.c:253-256`) but the translator is always given `false` (`Program.cs:92`) (check 12). | — |
| 5.7 | **Alpha-to-coverage** with dither (`SET_ALPHA_TO_COVERAGE_DITHER_CONTROL` 0x12e0), alpha test (fixed function on Maxwell). | A2C without dither; no alpha test. | Ryujinx emulates alpha test and A2C dither in the shader from graphics state; ours passes `AlphaTestOp.Always`, A2C false to the translator (`Program.cs:91-93`). | OGD 0x12e0, 0x16b4 |
| 5.6 | **Dual-source blending**: SRC1 factors read the shader's second output. | Needs fragment output `Location 0, Index 1`. | Ryujinx declares `Index` only when `DualSourceBlendEnable` (`Translation/Translator.cs:196`, `CodeGen/Spirv/Declarations.cs:608-617`). Ours: SRC1 factors mapped (`vk_pipeline.c` `blend_factor`) but the translator is always given `false` (`Program.cs` `QueryGraphicsState`) (check 12). | — |
| 5.7 | **Alpha-to-coverage** with dither (`SET_ALPHA_TO_COVERAGE_DITHER_CONTROL` 0x12e0), alpha test (fixed function on Maxwell). | A2C without dither; no alpha test. | Ryujinx emulates alpha test and A2C dither in the shader from graphics state; ours passes `AlphaTestOp.Always`, A2C false to the translator (`Program.cs` `QueryGraphicsState`). | OGD 0x12e0, 0x16b4 |
| 5.8 | **Logic ops** on colour targets. | `logicOp` feature; ignored on float targets. | Ours: in the pipeline key. | OGD 0x19c4 |
| 5.9 | **Vertex formats**: `*SCALED` 8/16-bit, RGB10A2 SNORM/SCALED, 3-component formats, 32-bit scaled. | No 32-bit SCALED; 3-component formats often unsupported. | Ours: 32-bit scaled read as integers (logged), 3-component widened (`vk_pipeline.c:382-413`). | — |
| 5.10 | **Transform feedback**, rasterizer discard. | `VK_EXT_transform_feedback`. | Ours: rasterizer discard without XFB = no draw (`nvn_api_cmd.c:530`). | OGD 0x0744 |
| 5.11 | **Depth bounds, sample mask, conservative raster**. | Optional features. | Ours: ignored, logged (`nvn_ext.c:377-394`). | OGD 0x0fa4 |
| 5.9 | **Vertex formats**: `*SCALED` 8/16-bit, RGB10A2 SNORM/SCALED, 3-component formats, 32-bit scaled. | No 32-bit SCALED; 3-component formats often unsupported. | Ours: 32-bit scaled read as integers (logged), 3-component widened (`vk_pipeline.c` vertex format table). | — |
| 5.10 | **Transform feedback**, rasterizer discard. | `VK_EXT_transform_feedback`. | Ours: rasterizer discard without XFB = no draw (`nvn_api_cmd.c`). | OGD 0x0744 |
| 5.11 | **Depth bounds, sample mask, conservative raster**. | Optional features. | Ours: ignored, logged (`nvn_ext.c`). | OGD 0x0fa4 |
| 5.12 | **Blend factors on targets without alpha** (RGBX emulated as RGBA). | Destination alpha reads the stored value. | Ryujinx replaces DST_ALPHA factors on no-alpha targets (`FilterBlendFactor`, RYU-SU). | RYU-SU |
## 6. Known BotW / TotK issues in other projects
@@ -146,73 +146,71 @@ Source shorthands:
## 7. Checks for our runtime
Grep-level look on 2026-10-22; "saw" is what the grep and short reads showed, not a test result.
Grep-level look on 2026-10-22, statuses updated 2026-10-26; "saw" is what the grep and short reads showed, not a test result.
1. **Provoking vertex.** *Stale as of 2026-10-23: `vk_pipeline.c:223, 1324-1328, 1438` enable `provokingVertexLast` and chain
LAST_VERTEX; re-check, then mark fixed.* Earlier look: `grep -n provokingVertex runtime/vk_pipeline.c` → no hits; `vk_device.c:205` only queries
`VK_EXT_provoking_vertex`. Vulkan draws flat outputs from the first vertex, NVN from the last. Fix: enable the feature
and chain `VkPipelineRasterizationProvokingVertexStateCreateInfoEXT{LAST_VERTEX}` in the pipeline create. **Mismatch.**
2. **Unwritten vertex outputs.** `spirv_add_outputs` (`vk_pipeline.c:551-554`, `:946`) adds **zero**-initialised outputs
for FS inputs the VS lacks; Maxwell gives (0, 0, 0, 1). Partly written outputs get nothing: our translator never links
stages (`grep SetNextStage tools/xlate/Program.cs` → none), so Ryujinx's `InitializeVertexOutputs` initialises no
user output. **Mismatch**: w = 0 breaks perspective divides (NXN:151 shadows).
3. **Masked clears.** `vk_exec.c:418-421` skips colour clears with a partial channel mask; `clear_ds` skips stencil
1. **Provoking vertex.** Vulkan draws flat outputs from the first vertex, NVN from the last. `vk_pipeline.c` enables
`provokingVertexLast` and chains `VkPipelineRasterizationProvokingVertexStateCreateInfoEXT{LAST_VERTEX}` in
`create_graphics`; without the feature it logs that flat outputs come from the first vertex. **Fixed.**
2. **Unwritten vertex outputs.** `spirv_add_outputs` (`vk_pipeline.c`) adds outputs initialised to (0, 0, 0, 1) for
FS inputs the VS lacks. Our translator never links stages, so Ryujinx's `InitializeVertexOutputs` would initialise
no user output; translator patch 0006 initialises the unlinked outputs. **Fixed.**
3. **Masked clears.** `vk_exec.c` skips colour clears with a partial channel mask (`W_CLEAR_MASK`); `clear_ds` skips stencil
clears with a partial mask (`W_STENCIL_MASK`). TotK issues such clears (NXN:174). Check the log for
`colour clear with channel mask` and `stencil clear with mask`. DK3D (1.3) confirms what the replay must do: colour clear = scissor 0 + channel mask, stencil clear = `value & mask` merged under the front write mask; so a draw with `colorWriteMask` / `stencilWriteMask` set to the clear mask is the exact equivalent. **Missing.**
4. **D24 → D32F.** `vk_formats.c:43` maps D24S8 to `D32_SFLOAT_S8_UINT`; `vk_exec_draw.c:710` passes NVN units
4. **D24 → D32F.** `vk_formats.c` maps D24S8 to `D32_SFLOAT_S8_UINT`; `vk_exec_draw.c` `record_fixed` passes NVN units
unscaled. Depth EQUAL passes and decal offsets can z-fight. Look at: per-pass depth-test op histogram, EQUAL passes
against D24 targets. **N/A for TotK**: a census of the field and fight saves (2026-10-22) saw depth targets
0x34 (DEPTH32F) and 0x32 (DEPTH16) only; biased draws (units -5 and 1, factor -0.5 and -0.2) are on DEPTH32F.
5. **Counters and conditional rendering.** `vk_exec_xfer.c:11-18, 83-88`: every report writes `{0, time}`;
5. **Counters and conditional rendering.** `vk_exec_xfer.c` (as of 2026-10-22): every report writes `{0, time}`;
SAMPLES_PASSED is always 0; a condition is read on the CPU at record time and an unfinished report reads 0. Grep the
NVN log for counter types other than TIMESTAMP; any occlusion-driven visibility (flares, culling) is off. **Fixed 2026-10-22**:
SAMPLES_PASSED counts come from Vulkan occlusion queries between RESET and REPORT (`vk_exec_xfer.c`, ~4 queries
per frame in the field, ~21 in a fight); the game's CPU reads them (guest f_70010c3298) to cull objects.
6. **Subgroup size.** `grep -n -i subgroup runtime/vk_*.c tools/xlate/Program.cs` → none. Translator assumes 32;
RDNA4 may run fragment shaders in wave64. Fix: `VkPipelineShaderStageRequiredSubgroupSizeCreateInfo{32}` for
modules using `GroupNonUniform*` (or `QueryHostSubgroupSize` = actual size). **Risk.**
7. **Images aliased onto GPU-only pool memory.** `vk_texture.c:263-270` binds each `VkImage` into its pool allocation;
textures are keyed by address plus descriptor, and each new image starts `UNDEFINED` (`:310`). Two descriptors over the
6. **Subgroup size.** The translator assumes 32; RDNA4 may run fragment shaders in wave64. `vk_caps.c` and
`vk_pipeline.c` `pin_subgroup32` pin stages to 32 lanes with `VkPipelineShaderStageRequiredSubgroupSizeCreateInfo`
where `subgroupSizeControl` allows it, and otherwise tell the translator the GPU's own size
(`TOTK_VK_SUBGROUP_PIN=0` forces that). **Fixed.**
7. **Images aliased onto GPU-only pool memory.** `vk_texture.c` `bind_pool_memory` binds each `VkImage` into its pool
allocation; textures are keyed by address plus descriptor, and each new image starts `UNDEFINED` (`init_image`). Two descriptors over the
same storage, or bytes written through a buffer, do not see each other's data on AMD. Check: count distinct keys per
address per frame. **Risk** (yuzu PR 10418 class).
8. **GPU writes into CPU-visible pools.** `note_gpu_write` (`vk_exec_xfer.c:65-71`) stamps pages when the fence
8. **GPU writes into CPU-visible pools.** `note_gpu_write` (`vk_exec_xfer.c`) stamps pages when the fence
completes, so a texture sampled later in the same submission keeps its old upload; GPU-only pools are skipped.
MNG saw at most one buffer copy per frame in TotK, so low priority. **Risk.**
9. **Index buffers.** `vk_exec_draw.c:888-897`: byte indices widened on the CPU at record time, skipped in
device-local memory; `:865-876` non-all-ones restart index logged and dropped. Census (2026-10-22): 130-170 byte-index draws/frame widened on the
9. **Index buffers.** `vk_exec_draw.c` `op_draw_idx`: byte indices widened on the CPU at record time, skipped in
device-local memory; `restart_for`: a non-all-ones restart index logged and dropped. Census (2026-10-22): 130-170 byte-index draws/frame widened on the
CPU, 0 device-local, 0 non-all-ones restarts. **OK**; `VK_KHR_index_type_uint8` (supported) would drop the CPU cost.
10. **Feedback loops.** `grep -n -i feedback runtime/vk_exec*.c` → none. NVN barriers end the pass (`vk_exec.c:316-327`),
but a draw that samples a currently attached image without an NVN barrier is not detected. Census (2026-10-22):
425/frame (field) to 667 (fight), G-buffer material/decal shaders sampling the 1600x900 targets of the open pass.
**Mismatch**: needs `VK_EXT_attachment_feedback_loop_layout` (supported). Shader keys: build/archive/v121-chk/NOTES.md.
Confirmed 2026-10-23 (`build/archive/v121-sq/SQUARES.md`): the terrain G-buffer pass reads its own albedo, normal and R32F
targets at the fragment's pixel; on the RX 9070 the reads return stale data as ~16x14 px dark rectangles on the
ground, and the sage spirit next to Link is not drawn. Ending the pass behind a barrier before such a draw fixes
both.
11. **Border colours.** `vk_texture.c:1025-1035`: custom colour only with `customBorderColorWithoutFormat`, else transparent
10. **Feedback loops.** Census (2026-10-22): 425/frame (field) to 667 (fight), G-buffer material/decal shaders
sampling the 1600x900 targets of the open pass. The terrain G-buffer pass reads its own albedo, normal and R32F
targets at the fragment's pixel; on the RX 9070 the reads returned stale data as ~16x14 px dark rectangles on the
ground, and the sage spirit next to Link was not drawn. `vk_exec_draw.c` (feedback loops) now detects such a draw:
with `VK_EXT_attachment_feedback_loop_layout` and `dynamicRenderingLocalRead` the target moves to the feedback
layout and a by-region barrier precedes the draw; without them the pass restarts behind a full barrier
(`TOTK_FEEDBACK`). **Fixed.**
11. **Border colours.** `vk_texture.c` `make_sampler`: custom colour only with `customBorderColorWithoutFormat`, else transparent
black; integer formats use the float path. Confirm the RX 9070 reports the feature (grass map needs 0.5).
**OK if supported.**
12. **Dual-source blend.** `vk_pipeline.c:253-256` maps SRC1 factors; `Program.cs:92` always passes
12. **Dual-source blend.** `vk_pipeline.c` `blend_factor` maps SRC1 factors; `Program.cs` `QueryGraphicsState` always passes
`dualSourceBlendEnable = false`, so no `Index 1` output exists. Log pipelines with SRC1 factors. **Mismatch if used.**
13. **FMZ / NaN.** Count `FMUL/FFMA/FMUL32I/FFMA32I` words with the `Fmz` field set (`Decoders/InstDecoders.cs:1901`
bit positions) in `build/v121/shaders/`; FMin/FMax/FClamp NaN results are undefined (3.1). Census (2026-10-22):
FMZ in 1 instruction of 12397 shaders, FTZ in 12241 shaders, FMNMX in 7457. The translator emits GLSL.std.450
FMin/FMax (Ryujinx `GenerateMinimum`), not NMin/NMax. **FMZ: no fix needed. FMNMX: OK** (RX 9070 test: FMin/FMax(NaN, 1) = 1 both orders, FClamp(NaN, 0, 1) = 0).
14. **Point size / line width.** `nvn_ext.c:367-373` log non-default values; the translator writes `PointSize = 1`.
Census: `SetLineWidth 4.5` ~1/frame (2 line draws into a 144x144 R8 target), `SetPointSize 5` ~14/frame; 4 point
VS rely on it. **Mismatch, minor.**
15. **Block height.** `nvn_tex.c:149` truncates like NVN (2.1). DK3D rounds up (`dk_image.cpp:446`); every other step matches. **OK.**
16. **Depth mode and clamp.** `vk_pipeline.c:978-983` (`negativeOneToOne` from `nvn_depth_minus_w`, `depthClampEnable`
14. **Point size / line width.** Census: `SetLineWidth 4.5` ~1/frame (2 line draws into a 144x144 R8 target),
`SetPointSize 5` ~14/frame; 4 point VS rely on it. Point size: translator patch 0008 reads it from the support
buffer, **fixed**. Line width: 1 px, non-default values logged (`nvn_ext.c`), **mismatch, minor**.
15. **Block height.** `nvn_tex.c` truncates like NVN (2.1). DK3D rounds up (`dk_image.cpp:446`); every other step matches. **OK.**
16. **Depth mode and clamp.** `vk_pipeline.c` `create_graphics` (`negativeOneToOne` from `nvn_depth_minus_w`, `depthClampEnable`
from NVN state). DK3D agrees on the z maths (1.5) and the clamp switch (1.6). **OK.**
17. **Depth bias argument order.** `vk_exec_draw.c:710` (units, clamp, factor); DK3D takes the same three and doubles units for the register (1.7). **OK.**
18. **Sampler LOD.** `vk_texture.c:1008-1013`. **OK.**
19. **Viewport / scissor arrays.** Single viewport (`vk_exec_draw.c:700-702`), extra scissors logged. Census: 0 differing. **OK.**
17. **Depth bias argument order.** `vk_exec_draw.c` `record_fixed` (units, clamp, factor); DK3D takes the same three and doubles units for the register (1.7). **OK.**
18. **Sampler LOD.** `vk_texture.c` `make_sampler`. **OK.**
19. **Viewport / scissor arrays.** Single viewport (`vk_exec_draw.c` `record_fixed`), extra scissors logged. Census: 0 differing. **OK.**
20. **Depth-compare sampling in compute** (VUID-vkCmdDispatch-None-06479): one compute shader samples a 4x4 R32F
CPU-written placeholder through an R32_SFLOAT view with compare on, ~1/frame. Needs a D32 copy. **Minor.**
21. **Report timestamps: unit and instant.** `write_counter` (`vk_exec_xfer.c:88-91`) writes host `ns * 12 / 625` (19.2 MHz
21. **Report timestamps: unit and instant.** `write_counter` (`vk_exec_xfer.c`) writes host `ns * 12 / 625` (19.2 MHz
ticks) at fence completion for every report; `nvnDeviceGetTimestampInNanoseconds` converts back with the same factor
(`nvn_ext.c:52-56`). DK3D: GPU ticks convert at 625/384 ns (614.4 MHz), TIMESTAMP is written when the ROP has retired
(`nvn_ext.c`). DK3D: GPU ticks convert at 625/384 ns (614.4 MHz), TIMESTAMP is written when the ROP has retired
the earlier work, TIMESTAMP_TOP when the command processor reaches it (4.2). Two consequences for port-lessons T1:
(a) if the 1.2.1 consumer scales raw report ticks with its own constant rather than the NVN conversion call, our
19.2 MHz unit is 32x off from the hardware's; find that consumer before fixing the unit; (b) the delta needs
+40 -35
View File
@@ -5,7 +5,8 @@ Sources: nxnative (MIT, `refs/nxnative` at `d5b380b`, 2026-10-22; `docs/agents/0
`05-debugging.md`, `docs/development.md`, the TotK profile `dm/games/0100F2C0115B6000/game.tsv`) and MacNativeGames
([macnativegames.md](macnativegames.md)). nxnative runs TotK 1.4.3, so its `main+` addresses do not carry over to 1.2.1.
Maxwell semantics live in [maxwell.md](maxwell.md); a lesson that is also a Maxwell check names its number (`mx N` =
maxwell.md section 7 check N). Our side was checked by reading the code on 2026-10-22 and updated 2026-10-23; `file:line` refers to that state.
maxwell.md section 7 check N). Our side was checked by reading the code on 2026-10-22 and updated 2026-10-26. Our code is cited by file and function
or SVC number, so the citations survive edits; `file:line` citations point into `refs/`.
Status: **open** (missing or partial), **unknown** (not checked), **done**, **parked**.
@@ -35,9 +36,9 @@ new commits and `git diff <pin> origin/HEAD -- docs` their notes. Add lessons he
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| T1 | GPU-bound scenes run in slow motion; dynamic resolution never drops | The Zelda engine's GPU time is the `TIMESTAMP` report at the end of the frame minus `TIMESTAMP_TOP` at its start, read after the frame fence; the interval controller and dynamic resolution use it. One time per submission made it 0-6 ticks (BotW). Fix: each report gets the GPU start or end of its command segment (`gpu_timestamps segment`, `DM_NVN_GPU_TS`; 04-graphics.md) | open: every report gets the host time at fence completion (`vk_exec_xfer.c:90-94, 259-276`), so the difference is microseconds. Counter word 0 is right (conditional clears need it). 1.2.1's interval controller does not read it: `[x1+0x118]` (`0x8f26c8`) is `GetSystemTick` minus the frame start (`f_70008f24bc`); dynamic resolution not checked | find a reader of the report difference; then `vkCmdWriteTimestamp` (top of pipe for `TIMESTAMP_TOP`) converted to 19.2 MHz ticks with calibrated timestamps |
| T2 | frame-rate counter wanders 50-60 | the vsync event and the window acquire each kept a 60 Hz clock and drifted apart; both follow one display tick now (03-bringup.md) | open: `gfx_window.c:92-104` and `nvn_api_obj.c:640-680` run separate clocks | derive acquire slots from the vsync thread's tick |
| T3 | a 30 Hz thread runs at 27 Hz, slow cutscenes | host sleep overshoot; `sleep_precise` | unknown: high-resolution waitable timer (`kernel.c:685-697`), overshoot not measured | measure `SleepThread` at 1, 5, 16 and 33 ms |
| T1 | GPU-bound scenes run in slow motion; dynamic resolution never drops | The Zelda engine's GPU time is the `TIMESTAMP` report at the end of the frame minus `TIMESTAMP_TOP` at its start, read after the frame fence; the interval controller and dynamic resolution use it. One time per submission made it 0-6 ticks (BotW). Fix: each report gets the GPU start or end of its command segment (`gpu_timestamps segment`, `DM_NVN_GPU_TS`; 04-graphics.md) | open: every report gets the host time at fence completion (`vk_exec_xfer.c` `write_counter`), so the difference is microseconds. Counter word 0 is right (conditional clears need it). 1.2.1's interval controller does not read it: `[x1+0x118]` (`0x8f26c8`) is `GetSystemTick` minus the frame start (`f_70008f24bc`); dynamic resolution not checked | find a reader of the report difference; then `vkCmdWriteTimestamp` (top of pipe for `TIMESTAMP_TOP`) converted to 19.2 MHz ticks with calibrated timestamps |
| T2 | frame-rate counter wanders 50-60 | the vsync event and the window acquire each kept a 60 Hz clock and drifted apart; both follow one display tick now (03-bringup.md) | open: `gfx_window.c` `vsync_main` and the pacer of `nvn_api_obj.c` (`pace`, `present_period`) run separate clocks | derive acquire slots from the vsync thread's tick |
| T3 | a 30 Hz thread runs at 27 Hz, slow cutscenes | host sleep overshoot; `sleep_precise` | unknown: high-resolution waitable timer (`kernel.c` `sleep_ns`), overshoot not measured | measure `SleepThread` at 1, 5, 16 and 33 ms |
## Open: thread scheduling
@@ -46,37 +47,36 @@ A one-step ordering difference between two engine threads can show as one frame
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| S1 | state read one step early; use-after-free between threads | a woken better-priority thread pinned to the signaller's core runs before the signaller's next instruction (`dm_yield_to_core_peers`, `core_preempt`; 03-bringup.md) | open: the preempt flag is honoured at the holder's next SVC (same design as MacNativeGames `threads.c:120-151`). Tried 2026-10-23 (`build/archive/v121-preempt/NOTES.md`): a check at every host call made phantom rocks rarer (0/10 to 4/6 clean runs) but added 50-75 ms CPU-side hitches, so it was reverted; a nxnative-style waker handoff did not help | none until a symptom is traced to it alone |
| S2 | per-core data races, different thread order | `CreateThread` with ideal core -2 and the main thread get the default core and a mask of that core only; `SetThreadCoreMask` -2 means core 0 / mask 1 | open: mask 7 for negative cores and the main thread (`kernel.c:646, 777`); `SetThreadCoreMask` -2 keeps the old ideal core (`kernel.c:879-890`) | count -2 creations with `TOTK_TRACE=svc`, then pin |
| S3 | worker threads burn cores, late frames | 843 SVC-free spin loops in TotK `main`; nxnative's rewriter makes them poll 2 ms, then sleep | open: a lifted spin loop keeps its virtual core with no preemption point (`kernel.c:363-371`) | measure core-wait while a holder spins (sched trace `preempt` latency) |
| S4 | rare hang or lost wake | `SignalToAddress` type 2, count <= 0 with waiters: Ryujinx, yuzu and nxnative set `value - 2` | done: `kernel.c:1017` writes `value - 1` and the count > 0 branch writes `nw <= count ? value - 1 : value`, both as mesosphere master `kern_k_address_arbiter.cpp`; 1.2.1 calls type 2 only with count 1, and `value - 2` did not change the phantom rocks (2026-10-23, `build/archive/v121-lock/NOTES.md`) | none |
| S5 | the main thread holds a core a worker needs | yield types 0 / -1 / -2 differ on Horizon; TotK's render-graph wait is a poll plus yield | unknown: all three hand the core only to an equal or better waiter (`kernel.c:835-846`) | trace which yield type 1.2.1's frame-end poll uses |
| S1 | state read one step early; use-after-free between threads | a woken better-priority thread pinned to the signaller's core runs before the signaller's next instruction (`dm_yield_to_core_peers`, `core_preempt`; 03-bringup.md) | open: the preempt flag is honoured at the holder's next SVC or indirect call (`dispatch.c` `dispatch_preempt`; MacNativeGames `threads.c:120-151` checks at SVCs), and a waiter interrupts a holder in game code after 250 us (S7), but a woken thread does not run before the signaller's next instruction. Tried 2026-10-23: a check at every host call made phantom rocks rarer (0/10 to 4/6 clean runs) but added 50-75 ms CPU-side hitches, so it was reverted; a nxnative-style waker handoff did not help | none until a symptom is traced to it alone |
| S2 | per-core data races, different thread order | `CreateThread` with ideal core -2 and the main thread get the default core and a mask of that core only; `SetThreadCoreMask` -2 means core 0 / mask 1 | open: mask 7 for negative cores and the main thread (`kernel.c` SVC 0x08 `CreateThread` and the main thread's `thr_new`); `SetThreadCoreMask` -2 keeps the old ideal core (`kernel.c` SVC 0x0F) | count -2 creations with `TOTK_TRACE=svc`, then pin |
| S3 | worker threads burn cores, late frames | 843 SVC-free spin loops in TotK `main`; nxnative's rewriter makes them poll 2 ms, then sleep | partly: a better-priority waiter takes the core at the spinning holder's next indirect call or interrupts it after 250 us (S7); a spin loop still burns a host core and keeps equal-priority waiters out | measure core-wait while a holder spins (sched trace `preempt` latency) |
| S4 | rare hang or lost wake | `SignalToAddress` type 2, count <= 0 with waiters: Ryujinx, yuzu and nxnative set `value - 2` | done: `kernel.c` SVC 0x35 writes `value - 1` and the count > 0 branch writes `nw <= count ? value - 1 : value`, both as mesosphere master `kern_k_address_arbiter.cpp`; 1.2.1 calls type 2 only with count 1, and `value - 2` did not change the phantom rocks (2026-10-23) | none |
| S5 | the main thread holds a core a worker needs | yield types 0 / -1 / -2 differ on Horizon; TotK's render-graph wait is a poll plus yield | unknown: all three hand the core only to an equal or better waiter (`kernel.c` SVC 0x0B) | trace which yield type 1.2.1's frame-end poll uses |
| S6 | lost or extra wakes | MacNativeGames `dab728a`: `SignalToAddress` wake-all, `SystemEvent` rebinding, targeted wakes | unknown | read the commit, compare with `kernel.c` |
| S7 | stutter: a better thread waits milliseconds for a core whose owner runs game code | MacNativeGames 8bf0893 (PR #488, on by default e4b4601): the waiter signals the owner, which gives the core up when interrupted in top-level game code; priority inheritance through guest mutexes; the SDK's preemption disable (TLR+0x100 / +0x102, SVC 0x36); without the last two their game hung at "Continue". 1.1.2: 58% of long core waits were this class; Mac worst-1% frame 18.4 to 10.6 ms | ported on `task/preempt` (`TOTK_ASYNC_PREEMPT`, SuspendThread and a register-saving stub instead of a signal; `build/v121-preempt/NOTES.md`). `TOTK_CORE_DIAG=1` measured this class at 0.47 / 0.83 / 1.06 ms of thread-time per frame (field / fight / monsters2) with our indirect-call checkpoints, waits to 16+ ms; with the port 0.29 / 0.34 / 0.84 and the waits of 1 ms or more 53 / 41 / 27 to 4 / 10 / 18. 1.2.1's SDK has the disable protocol (sdk f_70051242a8, f_7005124360). A first stub clobbered the flags before saving them (`sub` before `pushfq`) and crashed at boot | see the backlog item for the A/B timings |
| S7 | stutter: a better thread waits milliseconds for a core whose owner runs game code | MacNativeGames 8bf0893 (PR #488, on by default e4b4601): the waiter signals the owner, which gives the core up when interrupted in top-level game code; priority inheritance through guest mutexes; the SDK's preemption disable (TLR+0x100 / +0x102, SVC 0x36); without the last two their game hung at "Continue". 1.1.2: 58% of long core waits were this class; Mac worst-1% frame 18.4 to 10.6 ms | done: merged, on by default (`TOTK_ASYNC_PREEMPT`; SuspendThread and a register-saving stub, `kernel.c` `kern_ap_stub`, instead of a signal). `TOTK_CORE_DIAG=1` measured this class at 0.47 / 0.83 / 1.06 ms of thread-time per frame (field / fight / monsters2) with our indirect-call checkpoints, waits to 16+ ms; with the port 0.29 / 0.34 / 0.84 and the waits of 1 ms or more 53 / 41 / 27 to 4 / 10 / 18. 1.2.1's SDK has the disable protocol (sdk f_70051242a8, f_7005124360). A first stub clobbered the flags before saving them (`sub` before `pushfq`) and crashed at boot | A/B timings: [backlog](../backlog.md) item 11 |
## Open: graphics
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| G3 | light or decal lists, particle data read 0 | buffer textures read by 1D integer fetches; bound as 2D rows | open: buffer textures bind a zero view (`vk_exec_draw.c:657-659`) | census; Vulkan texel buffer views need no 2D trick |
| G4 | textures read as the dummy | bindless handles stored in the game's own uniform buffers (`tex_ubo`) | not in 1.2.1: 0 of 75k descriptors take a handle from cbuf >= 3 and no startup shader has a `_B` texture op (`build/g4/G4.md`, 2026-10-22); only c2 handles are mapped (`tools/xlate/Program.cs:49-54`) | if a later version needs it: nxnative `ubo_read` (`dm/gfx/nvn/nvn_mtl.m:4199-4215`) |
| G5 | garbage in feedback effects | new GPU textures start at zero | open: depth starts cleared, GPU-only colour images start undefined (`vk_texture.c:307-308`; mx 7) | clear new GPU-only colour images |
| G6 | 50x50 black tiles, masks not cleared | clears with a partial channel or stencil mask | parked: fix in `build/archive/v121-clr` (mx 3, backlog) | merge if the census shows partial-mask clears |
| G7 | garbage geometry on title or load screens | 8-bit indices written by a copy in the same submission read stale by CPU widening | open: CPU widening at record time (`vk_exec_draw.c:888-897`; mx 9) | `VK_KHR_index_type_uint8` (backlog) |
| G3 | light or decal lists, particle data read 0 | buffer textures read by 1D integer fetches; bound as 2D rows | open: buffer textures are not replayed and bind a stand-in (`vk_exec_draw.c` `bind_resources`) | census; Vulkan texel buffer views need no 2D trick |
| G4 | textures read as the dummy | bindless handles stored in the game's own uniform buffers (`tex_ubo`) | not in 1.2.1: 0 of 75k descriptors take a handle from cbuf >= 3 and no startup shader has a `_B` texture op (2026-10-22); only c2 handles are mapped (`tools/xlate/Program.cs` `TexSlot`) | if a later version needs it: nxnative `ubo_read` (`dm/gfx/nvn/nvn_mtl.m:4199-4215`) |
| G5 | garbage in feedback effects | new GPU textures start at zero | open: depth starts cleared, GPU-only colour images start undefined (`vk_texture.c` `init_image`; mx 7) | clear new GPU-only colour images |
| G6 | 50x50 black tiles, masks not cleared | clears with a partial channel or stencil mask | parked: a fix was written and not merged (mx 3, backlog item 29) | merge if the census shows partial-mask clears |
| G7 | garbage geometry on title or load screens | 8-bit indices written by a copy in the same submission read stale by CPU widening | open: CPU widening at record time (`vk_exec_draw.c` `op_draw_idx`; mx 9) | `VK_KHR_index_type_uint8` (backlog item 24) |
| G8 | cave stone blocks get no torch light | `ReadTexels` of a CPU-filled BC4 atlas returned the never-uploaded copy | open: ported, not checked on the 5120x5120 atlas | dump the cave save |
| G9 | scattered squares in albedo | G-buffer attaches one texture at two slots | unknown | validation on a G-buffer frame |
| G10 | stale 32x32 blocks where pre-pass and G-buffer disagree | identical position math must give identical depth (invariance) | unknown | grep a dumped VS SPIR-V for `Invariant` |
| G11 | characters stretched into streaks | integer vertex inputs vs the format's type | unknown | count `VUID-vkCmdDraw-Input-08734` |
| G12 | one flat ambient colour | a 1-layer 2D array sampled as 2D | unknown | read view creation in `vk_exec_draw.c:290-300` |
| G12 | one flat ambient colour | a 1-layer 2D array sampled as 2D | unknown | read view creation in `vk_exec_draw.c` `get_view` |
| G13 | magenta streamed textures | sparse textures use a 64 KB tile layout | unknown | look for virtual pools in the NVN log |
| G14 | upside-down UI text | lower-left window origin | unknown: origin recorded (`nvn_api_core.c:220-223`) | grep the NVN log for the origin |
| G15 | magenta 16x16 blocks | same-pass feedback sampling | parked (mx 10, backlog "Later") | only if a captured glitch points here |
| G14 | upside-down UI text | lower-left window origin | unknown: origin recorded (`nvn_api_core.c` `nvnDeviceSetWindowOriginMode`) | grep the NVN log for the origin |
## Open: performance
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| P2 | low fps outdoors | inline uniform updates and clear-only passes end render passes; deferring them cut TotK's attachment traffic from 1,100 to 700 MB a frame (`DM_NVN_UB_PARTIAL`, `DM_NVN_LAZY_CLEAR`, `cb_extent.tsv`) | unknown: `vkCmdUpdateBuffer` is illegal inside a pass, so ours likely end one (`vk_exec_draw.c:933-946`) | count passes per frame and those ended by an update in a `TOTK_DUMP` |
| P2 | low fps outdoors | inline uniform updates and clear-only passes end render passes; deferring them cut TotK's attachment traffic from 1,100 to 700 MB a frame (`DM_NVN_UB_PARTIAL`, `DM_NVN_LAZY_CLEAR`, `cb_extent.tsv`) | open: `UpdateUniformBuffer` is a buffer copy between full barriers, which end the pass (`vk_exec_draw.c` `op_update_ub`) | count passes per frame and those ended by an update in a `TOTK_DUMP` |
| P3 | out-of-memory after minutes | dead textures re-entered tables | unknown | log VMA bytes and live images every 1000 frames |
## Open: debugging tools
@@ -85,7 +85,7 @@ A one-step ordering difference between two engine threads can show as one frame
|---|---|---|
| D1 | Per-shader highlight, depth override and skip (`DM_NVN_HILITE`, `DEPTHOVR`) split "rejected by depth" from "never drawn" and bisect a glitch to one shader | open: `TOTK_DUMP` has none |
| D2 | First-use texture info with the count of non-zero guest bytes (`TEXINFO`, `TEXRAW`, `ZBLOCK`) shows a texture the CPU filled but we did not upload | open: dump lines carry address, mirror state and upload count only |
| D3 | Crash reports with a stack scan and the words at `*xN` | open: vectored handler (`main.c:118-160`) |
| D3 | Crash reports with a stack scan and the words at `*xN` | open: vectored handler (`main.c` `crash_handler`) |
## Done
@@ -95,28 +95,33 @@ Confirm the fix still holds before re-deriving any of these.
generator patches (`recomp/patches-v121.txt`, `runtime/frame_rate.c`); the pacer ignores the game's interval while
the step is real-time (`nvn_api_obj.c` `present_period`).
- Driver constant bank c0 (G2, fog that never parts, flicker in tile rows): a c0 bank per stage with the dispatch
size at 0x200, point size at 0x610 and base instance at 0x644, `vk_exec_draw.c:602-618`.
size at 0x200, point size at 0x610 and base instance at 0x644, `vk_exec_draw.c` `vk_c0_fill`.
- GPU idle while the replay records (P1): the replay is submitted in parts between passes every `TOTK_SPLIT_DRAWS`
(64) draws, only the last part signals, `vk_exec.c:564-575`.
(64) draws, only the last part signals, `vk_exec.c` `maybe_split`.
- Unwritten vertex outputs read (0,0,0,1) (no sun shadows in Link's Awakening): translator patch
`tools/xlate/patches/0006-initialise-unlinked-vertex-outputs.patch` (mx 2).
- Conditional clears on counter words; a timestamp report writes 0 in the counter word: `vk_exec_xfer.c:90-94, 278-301`.
- CPU-filled textures without a flush (magenta cave walls): write-watched pool mirrors, `vk_texture.c:124-139`. The same
- Conditional clears on counter words; a timestamp report writes 0 in the counter word: `vk_exec_xfer.c`.
- CPU-filled textures without a flush (magenta cave walls): write-watched pool mirrors, `vk_memory.c` (`mem_written_pages`) and `vk_texture.c`. The same
path covers BotW's sky (tables memcpy'd into a CPU-cached pool, flushed, sampled from a zero texture: brown sky).
- Deferred texture binds read at execution (3D scene black): `nvn_api_cmd.c:621-660`.
- `nvnTextureCompare` compares the channel mapping (HUD prompt boxes, black stamina wheel): `nvn_api_obj.c:231-234`.
- BC textures drawn through an RGBA16UI view (BC4 encoder): block-texel-view-compatible images, `vk_texture.c:190, 255`.
- Fragment draws with no render target: `vk_exec.c:229`. Output types from attachment formats: `vk_pipeline.c:500`.
- Block-height rounding: `nvn_tex.c:149` (mx 15). Depth mode: `vk_pipeline.c:978-983` (mx 16).
- Deferred texture binds read at execution (3D scene black): `nvn_api_cmd.c` `Bind*Deferred`.
- `nvnTextureCompare` compares the channel mapping (HUD prompt boxes, black stamina wheel): `nvn_api_obj.c` `nvnTextureCompare`.
- BC textures drawn through an RGBA16UI view (BC4 encoder): block-texel-view-compatible images, `vk_texture.c` `block_views_ok`.
- Fragment draws with no render target: `vk_exec.c` `resolve_rt`. Output types from attachment formats: `vk_pipeline.c`
`vk_pipeline_answers`.
- Block-height rounding: `nvn_tex.c`, the block-height pick (mx 15). Depth mode: `vk_pipeline.c` `create_graphics` (mx 16).
- Same-pass feedback sampling (magenta or dark 16x16 blocks, G15): feedback-loop layout and a by-region barrier, or a pass
restart without the extension (`vk_exec_draw.c` feedback loops, `TOTK_FEEDBACK`; mx 10).
- Cubes sampled as cube arrays, 1D textures, swizzles, sRGB views, scaled copies, targets outside the output map keep
texels: see the playbook's "Bug classes already fixed".
- `GetCommandMemoryUsed` follows the driver's sizes and resets at `AddCommandMemory`: `nvn_api_cmd.c:321-347`. The game
- `GetCommandMemoryUsed` follows the driver's sizes and resets at `AddCommandMemory`: `nvn_api_cmd.c` `nvnCommandBufferGetCommandMemoryUsed`. The game
sizes model heaps from it, so a larger host record crashes world loads.
- `nvnQueueFinish` waits for the GPU only: `nvn_api_core.c:516-519`.
- Yield back-off: none (`kernel.c:835-846`); one that starts before 2 ms of yields drops TotK to 20 fps.
- Condition-variable waiters wake in arrival order within a priority: `kernel.c:184-191`.
- The guest clock never freezes: `main.c:106-115`. Focus message 15 only under focus modes 1 and 2: `gfx_window.c:178-180`.
- Alias region and heap: `memory.c:27-30`. Adr-relative jump tables: `recomp/jumptables.py`.
- `nvnQueueFinish` waits for the GPU only: `nvn_api_core.c` `nvnQueueFinish`.
- Yield back-off: none (`kernel.c` SVC 0x0B); one that starts before 2 ms of yields drops TotK to 20 fps.
- Condition-variable waiters wake in arrival order within a priority: `kernel.c` (`kern_test_cv_old_order` restores the old order
for tests).
- The guest clock never freezes: `main.c` `rt_ticks`. Focus message 15 only under focus modes 1 and 2: `gfx_window.c`
`WM_ACTIVATEAPP`, `ov_system.c` `SetFocusHandlingMode`.
- Alias region and heap: `memory.c` (`HEAP_CAP`, `ALIAS_SIZE`). Adr-relative jump tables: `recomp/jumptables.py`.
- Scripted and recorded input by frame: `TOTK_INPUT_SCRIPT`, `TOTK_INPUT_RECORD`.
Not applicable to us: Metal and iOS limits (big-stack entry points, TBDR store order, encoder order, display-link rates,
+18 -13
View File
@@ -137,7 +137,7 @@ and deterministic state-hash mode.
## D. Performance techniques in other Switch recomps (2026-10-21)
Clones read at `build/research/` (ignored): HWDER (https://github.com/sonsegajp/HWDER, MIT), B2recomp
Clones read locally (not in `refs/`): HWDER (https://github.com/sonsegajp/HWDER, MIT), B2recomp
(https://github.com/K0NL/B2recomp, GPL-3.0; its runtime is a copy of ssbu-recomp), SuperMarioWonderRecomp
(https://github.com/BelmanteGu/SuperMarioWonderRecomp, MIT), ssbu-recomp (GPL-3.0). GPL code: read only.
@@ -173,17 +173,18 @@ Clones read at `build/research/` (ignored): HWDER (https://github.com/sonsegajp/
MIT (`LICENSE:1-4`), pinned in `tools/fetch_refs.sh`. 430 files, 8 commits, one week old. Its notes (`docs/SAVAGE-WIND.md`, Spanish, 904 lines, cited
as `SW.md:line` = first line of the entry) are a dated log of BOTW 1.8.2 bring-up fixes. Most are bugs TotK 1.2.1 hits too. Paths are relative to
`refs/SavageWindRecomp/`. BOTW addresses do not carry over to TotK; the mechanisms do.
`refs/SavageWindRecomp/`; our code is cited by file and function, and the Ours column was updated 2026-10-26. BOTW
addresses do not carry over to TotK; the mechanisms do.
| Area | Theirs | Ours | Differs |
|---|---|---|---|
| Cores | 4 tokens, ticket queue per core (`runtime/kernel.c:96-235`); mask used only if single-bit (`kernel.c:867-880`) | 3 cores, mask-aware grant, preempt flag (`runtime/kernel.c:230-360`) | Yes |
| Preemption points | SVCs plus every indirect call (`runtime/dispatch.c:167`) | SVCs only (`runtime/svc.c:140`) | Yes |
| Exclusive monitor | Value CAS (`runtime/cpu.h:73-97`); pairs unsupported (`tools/lifter.py:391-392`) | Same macro plus 128-bit pair (`runtime/cpu.h:73-118`) | No (ours is a superset) |
| Call/CopyCommands | Record `CMD_CALL`, executed recursively at submit (`runtime/nvn/cmdbuf.c:687-688`, `runtime/nvn/vulkan/exec.c:4689-4695`) | Inlined at record time (`runtime/nvn_api_cmd.c:395-410`) | Yes |
| UpdateUniformBuffer | Applied at execution into guest memory, skipped if bytes equal (`exec.c:4863-4871`) | Recorded, written at replay (`nvn_api_cmd.c:430-441`) | Partly |
| Submit | Host queue thread, part-wise GPU submit (`runtime/nvn/objects.c:157-170`, `exec.c:1015-1017`) | Replay on the submitting thread (`runtime/nvn_api_core.c:520-530`) | Yes |
| Frame pacing | Patches VFR and the vsync wait (`tools/patches.py:186-223`) | none yet | Yes |
| Cores | 4 tokens, ticket queue per core (`runtime/kernel.c:96-235`); mask used only if single-bit (`kernel.c:867-880`) | 3 cores, mask-aware grant, preempt flag, asynchronous preemption of a holder in game code (ours: `kernel.c` `core_take`, `kern_ap_stub`) | Yes |
| Preemption points | SVCs plus every indirect call (`runtime/dispatch.c:167`) | SVCs and every indirect call (ours: `svc.c`, `dispatch.c` `dispatch_preempt`), plus the waiter's interrupt | No |
| Exclusive monitor | Value CAS (`runtime/cpu.h:73-97`); pairs unsupported (`tools/lifter.py:391-392`) | Same macro plus 128-bit pair (ours: `cpu.h` `EXCL`) | No (ours is a superset) |
| Call/CopyCommands | Record `CMD_CALL`, executed recursively at submit (`runtime/nvn/cmdbuf.c:687-688`, `runtime/nvn/vulkan/exec.c:4689-4695`) | Inlined at record time (ours: `nvn_api_cmd.c` `inline_recording`) | Yes |
| UpdateUniformBuffer | Applied at execution into guest memory, skipped if bytes equal (`exec.c:4863-4871`) | Recorded, written at replay (ours: `nvn_api_cmd.c` `nvnCommandBufferUpdateUniformBuffer`) | Partly |
| Submit | Host queue thread, part-wise GPU submit (`runtime/nvn/objects.c:157-170`, `exec.c:1015-1017`) | Replay on the submitting thread, submitted in parts every 64 draws; a queued replay thread behind `TOTK_REPLAY_ASYNC=1` (ours: `nvn_api_core.c` `nvnQueueSubmitCommands`, `vk_backend.c`) | Partly |
| Frame pacing | Patches VFR and the vsync wait (`tools/patches.py:186-223`) | MacNativeGames' present-interval and real-time frame-step patches, back-edge present pacing (ours: `frame_rate.c`, `vk_backend.c`) | Yes |
### a. Threads
- Core gate like ours: a token per core, best priority then ticket order (`kernel.c:96-165`). Reason given: BOTW shares a sead heap without a lock between threads pinned to one core (`kernel.c:97-103`).
@@ -191,7 +192,7 @@ as `SW.md:line` = first line of the entry) are a dated log of BOTW 1.8.2 bring-u
Ours takes any free allowed core and keeps the ideal core for -2/-3, closer to Horizon.
- Preemption at indirect calls: `rt_dispatch` compares `g_core_best_wait[core]` with the running priority and yields (`dispatch.c:167`, `kernel.c:120-130, 220-229`).
Reason: a prio-48 job thread ran about 5 ms of guest code without a syscall once a second while a prio-44 worker on the same core, which the main thread waited for, sat waiting (a frame 10 ms longer each second) (`SW.md:540`).
Measured p99 frame time 23.6-24.8 ms without, 17.4-20.6 ms with (`SW.md:553`). Ours preempts only at SVCs (`runtime/kernel.c:354-362`, `runtime/svc.c:140`).
Measured p99 frame time 23.6-24.8 ms without, 17.4-20.6 ms with (`SW.md:553`). Ours has the same indirect-call check (`dispatch.c` `dispatch_preempt`).
- Host work releases the core: the submit and present path calls `kernel_host_work_begin/end` (`kernel.c:196-205`, `runtime/nvn/objects.c:132, 245-249, 292-294`). Reason: the translation took about 10 ms a frame on the core token (`SW.md:295`).
- Yield and `SleepThread(0)`: release then reacquire, so same-priority waiters go first (`kernel.c:231-236, 838`). `SignalProcessWideKey` and `ArbitrateUnlock` yield after unlocking, not before (`kernel.c:735-741`, `SW.md:256`).
- `svcWaitProcessWideKeyAtomic`: releasing the mutex before marking the condvar hung half the runs (`SW.md:224`); a timed-out wait returns without the mutex, and a timeout racing a wake does not count as expired (`SW.md:253`). Same family as port-lessons S6.
@@ -217,11 +218,11 @@ as `SW.md:line` = first line of the entry) are a dated log of BOTW 1.8.2 bring-u
Havok, stamina, time of day and animation all read the ratio; a ratio that alternated made Link's camera judder.
- Dynamic resolution: BOTW picks 1600x900 or 1280x720 from GPU time in `ReportCounter`; their translation time dropped the open world to 720p. Fix: every counter in a frame gets the same timestamp (`exec.c:4890-4902`, `SW.md:414`).
- Render-thread layout: the main thread records about 30 of 62 lists per frame, two workers the rest; the sead render thread (`0x7000d81100`) submits one list a frame and presents (`SW.md:503`).
- FPCR.FZ is set at thread start (`0x7000b4de30`, `0x70000c4e3c`). Software flushing cost about 40 % of main-thread time; they mirror FZ into MXCSR (`runtime/simd.h:53-58, 239`; `SW.md:516`). Ours already mirrors it (`runtime/cpu.h:21`).
- Depth clamp: BOTW enables it for the three sun-shadow cascades and the sun query. Ignored, geometry nearer than a cascade's near plane was clipped; tree shadows appeared, were cut and moved with the camera (`SW.md:593`). Ours records and applies it (`runtime/nvn_api_cmd.c:528`, `runtime/vk_pipeline.c:242`).
- FPCR.FZ is set at thread start (`0x7000b4de30`, `0x70000c4e3c`). Software flushing cost about 40 % of main-thread time; they mirror FZ into MXCSR (`runtime/simd.h:53-58, 239`; `SW.md:516`). Ours already mirrors it (ours: `cpu.h` `fpcr_host`).
- Depth clamp: BOTW enables it for the three sun-shadow cascades and the sun query. Ignored, geometry nearer than a cascade's near plane was clipped; tree shadows appeared, were cut and moved with the camera (`SW.md:593`). Ours records and applies it (ours: `nvn_api_cmd.c` `nvnCommandBufferSetDepthClamp`, `vk_pipeline.c` `depthClampEnable`).
`SAMPLES_PASSED` returns 0 and `SetRenderEnableConditional`/`SetRasterizerDiscard` are no-ops (`SW.md:593`).
- Same-pass feedback: the terrain fragment shader ORs bits into the G-buffer's own pixel, about 240 draws a frame. Copying the 1600x900 target before each draw cost 8.5 of 16 ms GPU. They use `VK_EXT_attachment_feedback_loop_layout` plus `VK_KHR_dynamic_rendering_local_read` with an in-pass barrier: copies 8.5 to 0.4 ms (`SW.md:325`).
Ours parks this (`docs/backlog.md:51-54`); TotK has 425-667 such draws.
Ours does the same since 2026-10-23 (`TOTK_FEEDBACK`, [maxwell.md](maxwell.md) check 10); TotK has 425-667 such draws.
- Submit in parts: a pass boundary about every 300 draws (`exec.c:1015-1017`, `SW.md:302`), except after a shader storing to guest memory (about 10 dispatches a frame). Ranges those storage buffers can write are tracked; a UBO inside them is read in place from the imported heap, and any other CPU copy of that memory waits for the GPU (`SW.md:524`). Holding the rest of the list caused device-lost in 1 of 7 loads when copying half-written data.
- Present on its own thread with a second queue; NVIDIA `vkQueuePresentKHR` blocked on the GPU for 13-18 ms in one frame of five (`runtime/nvn/vulkan/device.c:563-593`, `SW.md:306`).
- Shaders and pipelines: translation cached in memory and on disk (`cache/xlate/`, `SW.md:309`); `vk_pipelines.bin` with a GPU/driver/translator header plus `vk_pipelines.list`, replayed by worker threads at start-up, first world frame waits for it (`SW.md:337`, `device.c:310-384`).
@@ -248,6 +249,10 @@ Nothing in the issues or the log describes objects teleporting for a frame, or a
- Linux needs a 4 KB or 16 KB page kernel (`docs/linux.md`).
### What to adopt, ranked by expected effect on glitches and stutter
Status 2026-10-26: 1 and 2 are in, 3 is in part (part-wise submit; the queue is off by default), the feedback-loop
layout is in.
1. Preemption at indirect calls in `rt_dispatch`, plus the host-work core release. Small change, removes a periodic 5-10 ms frame spike they measured (p99 23.6-24.8 to 17.4-20.6 ms). Needs TotK confirmation with our sched trace.
2. Persistent pipeline list pre-warmed at start-up, with a key that holds only the used targets. Removes the 40-100 ms first-use hitches that read as stutter (frames over 40 ms 56 to 5 on their walk).
3. Host submission queue with part-wise GPU submit (about 300 draws) and the guest-memory-write tracking for storing shaders. Their p99 went 38-43 ms to 29-34 ms with queue, MXCSR FZ and range tracking together (`SW.md:550-552`).
+5 -6
View File
@@ -19,12 +19,11 @@ from it may be shared.
with your own paths, extraction, the shader translator, then lifting and linking. The result is
`build\v121\totk.exe`.
3. Check the build without the game: `build\v121\totk.exe --selftest` must print a pass.
4. To run the build on another of your machines, `.venv\Scripts\python tools\package_build.py` writes
`build\v121-portable` (about 2.4 GB). Copy it over; it needs no MSYS2, Python or .NET. The 16 GB RomFS is not in it:
copy `build\extracted\v121\romfs\romfs.bin` into `romfs\` there, or run the packager with `--with-romfs`.
Then run `totk.exe --prepare-shaders` once in the copied folder (about a minute): the driver caches pipeline
libraries per exe path, and without it the first fights stutter.
The folder holds game code: for your own machines only.
4. To run the build on another of your machines, package a portable folder as in step 7 of "Building from source"
in the README, and run `totk.exe --prepare-shaders` once in the copied folder. The folder holds game code: for your
own machines only.
5. The installer ([installer.md](installer.md)) is the other route to a machine without the toolchain: it builds the
game there from your own files. No installer release is published yet.
## Run and collect the log
+12 -10
View File
@@ -9,8 +9,8 @@ Update: `C:\msys64\usr\bin\bash.exe -lc "pacman -Syuu --noconfirm"` (twice: firs
Install:
pacman -S --needed --noconfirm make mingw-w64-ucrt-x86_64-{clang,lld,sdl3,ffmpeg,vulkan-devel,shaderc,spirv-tools,
pkgconf,gdb,vulkan-memory-allocator,vulkan-validation-layers,nasm,cmake,ninja,gcc,make} base-devel git unzip zip p7zip
pacman -S --needed --noconfirm make mingw-w64-ucrt-x86_64-{clang,lld,sdl3,opus,libvpx,ffmpeg,vulkan-devel,shaderc,
spirv-tools,pkgconf,gdb,vulkan-memory-allocator,vulkan-validation-layers,nasm,cmake,ninja,gcc,make} base-devel git unzip zip p7zip
| Package | Version |
|---|---|
@@ -18,7 +18,9 @@ Install:
| gcc | 16.2.0 |
| make (msys) / mingw32-make | 4.4.1 |
| sdl3 | 3.4.18 |
| ffmpeg | 9.0.2 (MSYS2 build is GPLv3; LASRecomp ships an LGPL build via `tools/build_deps_windows.sh`) |
| opus | 1.6.1 (`libopus-0.dll`, voice) |
| libvpx | 1.17.0 (`libvpx.a`, linked statically for the movies) |
| ffmpeg | 9.0.2 (never linked: the MSYS2 build is GPLv3) |
| vulkan-devel group (headers, loader, utility libs, spirv-headers, spirv-tools, validation layers) | 1.4.363 |
| shaderc (glslc) | 2026.4 |
| vulkan-memory-allocator | 3.4.0, header at `/ucrt64/include/vma/vk_mem_alloc.h` |
@@ -27,16 +29,16 @@ Install:
| nasm / gdb | 3.02 / 18.1 |
| git / unzip / zip / p7zip | 2.56.0 / 6.0 / 3.0 / 17.06 |
Use from Git Bash: `export PATH="/c/msys64/ucrt64/bin:/c/msys64/usr/bin:$PATH"`. Built exes need
`C:\msys64\ucrt64\bin` on PATH at run time (SDL3, FFmpeg, Vulkan, shaderc DLLs).
Use from Git Bash: `export PATH="/c/msys64/ucrt64/bin:/c/msys64/usr/bin:$PATH"`. `tools/build_game.py` copies
`SDL3.dll`, `libiconv-2.dll` and `libopus-0.dll` next to `totk.exe`, so the game runs without MSYS2 on `PATH`.
Verify:
clang --version; ld.lld --version
pkgconf --modversion sdl3 vulkan libavcodec
pkgconf --modversion sdl3 vulkan opus vpx
glslc --version; ffmpeg -version; spirv-val --version
### Vulkan back end of M4
### Vulkan back end
# all part of the install line above plus spirv-cross and glslang; --needed makes this a check
pacman -S --needed mingw-w64-ucrt-x86_64-{vulkan-devel,vulkan-memory-allocator,vulkan-validation-layers,shaderc,spirv-tools,spirv-cross,glslang}
@@ -88,14 +90,14 @@ Verify:
hactool source: `toolchain\src\hactool` (git checkout of the pinned commit). Build: UCRT64 gcc, `config.mk` =
`CC=gcc EXEEXT=.exe CFLAGS=-O2 ... LDFLAGS=... -static`, `make -j8`.
Applied the portable part of MacNativeGames `build_app.py:build_hactool()` (diff in
`toolchain\hactool\portable-patches.diff`):
Applied the portable part of MacNativeGames `build_app.py:build_hactool()` (kept as
`toolchain\hactool\portable-patches.diff` in the local toolchain folder, not in the repository):
1. `MNG_TITLE_KEYS` env var selects the title-key file.
2. BKTR: allow 0x200-aligned padding after the subsection table (`nca.c`).
3. BKTR: accept the subsection total-size layout of newer cumulative updates (`nca.c`).
Ours (`toolchain\hactool\unicode-patches.diff`): `hactool.manifest` with `<activeCodePage>UTF-8</activeCodePage>`,
Ours (kept locally as `toolchain\hactool\unicode-patches.diff`): `hactool.manifest` with `<activeCodePage>UTF-8</activeCodePage>`,
embedded through `hactool.rc` (Makefile rule `hactool.res.o`, `windres`). hactool converts argv, `HOME` and
`USERPROFILE` from UTF-8 to UTF-16 (`filepath.c`); without the manifest they arrive in the ANSI code page, and a
non-ASCII user profile or path stops it with `Failed to convert ... to UTF-16!`. Needs Windows 10 1903 or later.
+1 -1
View File
@@ -18,7 +18,7 @@ Versions are the ones verified on 2026-10-20. Newer patch releases are fine unle
| Ghidra | 12.1.2 (pinned: SwitchLoader targets it; REA accepts 12.1.x) | Release zip from github.com/NationalSecurityAgency/ghidra into `toolchain/ghidra/` | `toolchain\ghidra\ghidra_12.1.2_PUBLIC\support\analyzeHeadless.bat` |
| Ghidra SwitchLoader | 1.6.1-c600d05 for Ghidra 12.1.2 | Release zip from github.com/Adubbz/Ghidra-Switch-Loader, extracted into `<ghidra>\Ghidra\Extensions\SwitchLoader` | Ghidra lists "Nintendo Switch Binary" as a loader |
| RenderDoc | 1.46 (`e4bd23b`) | Signed MSI from renderdoc.org, unpacked without installing: `msiexec /a <msi> /qn TARGETDIR=<tmp>`, then move `<tmp>\PFiles\RenderDoc\*` to `toolchain/renderdoc/` (drop `System`/`System64`, the VC++ runtime Windows already has). For Vulkan captures, once, as administrator: `renderdoccmd vulkanlayer --register --system` | `renderdoccmd version`; `renderdoccmd vulkanlayer --explain` reports the layer registered |
| REA | rea-agents 6.7.0 | Skill in the repo (`skills-lock.json`); MCP server registered per clone, see [AGENTS.md](../AGENTS.md) | `claude mcp get rea`; `npx -y rea-agents@6.7.0 doctor --json` shows the Ghidra provider available |
| REA | rea-agents 6.7.0 | Skill pinned in `.claude/skills/skills-lock.json`; MCP server registered per clone, see [AGENTS.md](../AGENTS.md) | `claude mcp get rea`; `npx -y rea-agents@6.7.0 doctor --json` shows the Ghidra provider available |
## PATH
+1
View File
@@ -17,6 +17,7 @@
# async_preempt = 1
# Replay NVN submissions on their own thread, at most one frame behind the game (1 = on).
# replay_async = 0
[display]
# Presentation mode: mailbox (default when the driver offers it, vsync otherwise), fifo (vsync) or immediate.
# vk_present = mailbox