Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
Backlog
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, lesson ids (S1, G3, ...) to research/port-lessons.md. Remove an item when it is merged or dropped.
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.
Bugs
- 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-cast2from saveuser-save-2026-10-24-yunobo1, 1360 frames. - 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_compatibleand starts as a zero-cleared image in its own memory (vk_texture.centry_of,create_tex,init_image). The run's two largestleft uninitialisedcounts (33, 41) fall in its last seconds, where the glitch was.cannot alias its pool memoryfills its 16-line log limit on NVIDIA and on the RX 9070 alike. Next: per-alias diagnostic lines and aTOTK_TEX_FILL=magentaknob, then a user run. Same class as yuzu PR 10418 ("areas black for a frame on camera changes", Maxwell 2.3 / check 7). - 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.cholds 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. - Lantern texture bug: waiting for the user's description or a cropped screenshot.
- 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).
- Validation messages left in world runs:
cp_t_tcb_20samples an R32F view with depth compare invkCmdDispatch(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" invkCmdDrawIndexed; a fragment write to Location 0 with no colour attachment. - 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.
Frame time and freezes
- 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
schedrun rules out core contention: the render thread spends 79-88% of the wall time on the CPU insidenvnQueueSubmitCommands, 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). - 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 withreplay_async = 1. - 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
WriteTexelsand box-only image updates (re-uploads afterWriteTexelsare 0.003-0.05% of frame time). - 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, andTOTK_ASYNC_PREEMPT=0first on any new hang or stutter. If fights stay worse, try a shorter first spin (AP_FIRST_NS, 250 us) or mode 2. - Driver cache re-warm. The AMD driver keys its pipeline library cache by exe path, so a moved folder stutters
until
totk.exe --prepare-shadersruns again. Branchtask/rewarm(not merged, never run in game) stampsshader-prepared.binwith 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. - 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.pyreads"*"as 2D. Option: match"*"rows at run time, as MacNativeGames'prepare_shader_seed.pydoes. - Freeze census: a 10-15 minute user session with
TOTK_FLIGHT=1,TOTK_TRACE=perfandTOTK_INPUT_RECORD, ranking every frame over 50 ms by cause. Decides items 15-17. TOTK_PIPE_SKIP=fullscreenas 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.- 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
minLodif runs on machine B (TOTK_ASTC_TIME=1) show decodes in play. - 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.
- 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).
- Over the GPU memory budget, wait for running work and drain deferred releases before failing (MacNativeGames 4de7b4e). Matters on 4 GB cards.
- 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.centry_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. - 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 section E); a trimmed pipeline key (SavageWindRecomp).
Correctness queue
Worked in this order.
- 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.
- 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.
VK_KHR_index_type_uint8(Maxwell check 9): drops the CPU widening of 130-170 byte-index draws per frame.- Texture gather rounding on AMD (Maxwell 2.10): yuzu's sub-pixel offset at
ImageGatherfixed BotW shadow edges. - 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,schedfirst; fight fps must not drop. - Line width 4.5 (Maxwell check 14): dynamic
wideLines. vk_memory.cdefer()(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.- 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.
- GPU timestamps (port-lessons T1): find whether dynamic resolution reads the report difference before writing real GPU times per report.
- MacNativeGames since our pin
b75be8c(245 commits): kernel syncdab728a(S6), NVN texture sizes3c482a7, CPU reads of small render targets8a29e0a(item 5), border colour29dd997. Add the lessons, move the pin and fix therefs/MacNativeGamesline citations indocs/. - Maxwell sources not read yet (maxwell.md section 8).
Release and platforms
Each platform item gets a written design first, agreed with the maintainer.
- Release: fix what stops play on the test machines, then publish the repository and a first installer release (installer.md). Runs on more GPUs (NVIDIA, Vega, weaker CPUs, 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.
- Platform layer: no Win32 outside
runtime/platform/.tools/check_platform.pycounts 1479 uses in 41 files and fails onastc_probe.c,gfx_abi_probe.c,input.h,motion_fusion.c,movie_probe.c,ov_movie.c,swkbd_win.c,vk_astc.candvk_exec_draw.c. - Linux:
runtime/platform/linux.c, split as SavageWindRecomp splits its windows, linux and macos files. Write tracking (host.hmem_written_pages,mem_freeze/mem_thaw/mem_frozen, used by the VRAM mirror and the texture checks): freezing maps tomprotectplus aSIGSEGVhandler; a kernel write (read()into guest memory) returnsEFAULTinstead of faulting, so the same thaw-before-read sites apply. Written pages: thePAGEMAP_SCANioctl with write-protect matching (kernel 6.7+, made for Wine'sGetWriteWatch); 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. - Steam Deck: RADV offers Vulkan 1.3 and
VK_EXT_external_memory_host; 4 Zen 2 cores, so expect 30-40 fps. - 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.
Later
-
In-game menu: the first stage is in. F1, Esc or Minus+Plus opens it; the game gets no input while it is open. Tabs Screen, Game, Sound, Controls and Menu show option rows over the
cfgtable (runtime/cfg.c), with the description of the selected row beside them, English and Russian text fromruntime/ui_text.c. Every change goes tototk.ini, keeping the user's comments; a key set in the environment shows greyed out, a key read only at start says "after restart". Dear ImGui is drawn after the blit into the swapchain image (runtime/ui/menu.cpp).Left to do, in this order (unfinished work on branch
task/menu-advanced):- Performance overlay:
TOTK_PERF_OVERLAY(F10 cycles) shows the frame rate, and infullthe mean and longest frame time. Left: CPU and GPU load through PDH and NVML (SavageWindRecompruntime/perfmon.c). - Advanced tab: the remaining
cfgkeys (scheduling, replay thread, pipeline and shader switches), reset of all settings, and a system information block (sysinfo.c) with copy to clipboard and open the log folder. - Game language list without Portuguese (TotK ships ja, en, fr, de, it, es, nl, ru, zh-CN, zh-TW, ko).
- The Presentation row notes the mode the swapchain got when it differs from the setting (mailbox falls back to fifo).
- Not yet checked by hand: keyboard and gamepad navigation, Quit, input right after closing,
totk.inilocked by another program. - Later pages: button remapping (LAS Recomp
runtime/ui/controls_ui.mm), AMD FSR 1 or bilinear scaling of the 900p image, a frame-time graph with the wait breakdown ofTOTK_TRACE=perf, gyro sensitivity.
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. - Performance overlay:
-
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:stgno-op lift, DT_RELR inrecomp/nso.pyandruntime/loader.c, symbol count from DT_GNU_HASH forsdkandsubsdk0.- Jump tables: 26 disagreements and 83 unresolved sites down to 0 unexplained, with 1.2.1 still at 0.
- Tools take a version instead of
v121; re-measure the--probe-loadertable (loader.cexpect[]) andboot.cexpected_inits; new boot anchors (boot.cCHECKPOINT_RET,NVN_RET). - RELRO (
nn::ro::ProtectRelro) and the new SDK imports; run to the title screen. recomp/patches-v143.txtfrom MacNativeGamesgame_patches_v143.c(fps60, bounce, cloth; the real-time step rewritten for thesys+0x1dacoefficient); the player position offrame_rate.cplayer_pos;make_romfs_patches.py --version(Common.Product.140).- 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.
-
Community ExeFS patches (
.ips,.pchtxtfor 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 (exlaunchsubsdk9) need porting one by one. -
Frame rates above 60 and VRR.
-
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).