1 Rewrite plan
HumanBean edited this page 2026-11-17 19:37:05 -05:00

Rewrite plan

Status: draft proposal (2026-11-17), for discussion. Nobody is assigned to anything here and nothing is scheduled. This page plans a complete rewrite of Longshot: a new code base that ports the parts that are proven and rewrites the rest to a design written down first. It goes further than the Renderer rework plan, which reworks four files in place and keeps everything else. Until the rewrite reaches the same pictures and features, the current code stays the game players get, and the rework plan's tools are what this plan stands on.

Contents: 1 Why · 2 What it can and cannot give · 3 Ported, rewritten, dropped · 4 The design's rules · 5 Upstreams to pull at the start · 6 Milestones · 7 What waits for what · 8 Questions to answer first · 9 Decisions needed · 10 Rules for the work · 11 Risks

1. Why

Longshot is the fourth project on one code line (TOTKPort, mkw-recomp, Hookshot, Longshot). Each added fixes on top of the last one's structure. What follows was read from a checkout of main on 2026-11-17 (4b9f173d); nothing in this section was measured for this page.

Part What the code shows
Renderer size gpu/vk holds about 60,800 lines of .cpp. Four files hold 31,900 of them: vk_draw.cpp 11,788, vk_replay.cpp 7,142, vk_memory.cpp 7,064, vk_texture.cpp 5,867
Switches gpu/vk/switches.def has 679 live rows (281 diagnostic, 104 tuning, 103 kill, 81 attempt, 60 per-hardware, 50 player) and 139 removed ones
Memory sync Six mechanisms layered on one another: imports, mirrors, submit-time captures, late pages (with a wait, a GPU fix pass, a recheck at replay and a deferral), write-back with a diff against shadows, and readback pages. Each fixed a real bug in the one before
Frame pipeline The replay reads the game's memory and state as they are when it runs, not as they were at the submit. A frame gate holds the render thread until the frame is whole, because starting earlier gave black frames
Threads Three ways to spread the work exist (render thread, recorder thread, parallel replay) and they exclude one another: the parallel replay is refused with the recorder thread and turns two memory fixes off
Per draw Each draw derives its program, its pipeline key and its whole dynamic state again from the game's NVN state, then compares them with the last draw's
Host sync One global lock for every virtual-core hand-over, with 1 ms timed waits when no core is free. Events, semaphores and queues wake every waiter on every signal, with no fast path when nobody waits
Lifted code Guest registers live in a context structure in memory. Players' builds compile it at -O1 with the inliner off. Every guest store outside the stack also writes two page marks for the renderer
Tests Many checks cut a function out of a source file by its text, because the code cannot be linked in pieces

The rework plan's section 1 has the forge's side of this: the open crash, memory and stale-texture reports.

2. What it can and cannot give

The rework plan's measurements (2026-11-17, RTX 3090, Ryzen 9 7900X, 2560x1440) set the limits. A rewrite does not move them by itself:

  • The GPU's work caps Kokiri Forest near 85 to 95 fps on that PC. It is the game's own draws and dispatches.
  • The Market is limited by the game's own loop, about 13.1 ms. The renderer's side finishes in about 12.3 ms.
  • The hot lifted functions at -O2 with a profile gave about 3% fps for 9 to 17% more build time (issue 505).
  • From the port's side on that PC: the mid-80s to mid-90s in the heavy areas, from 66 to 73 today. 120 fps there needs the game's own simulation or geometry to cost less.

What the rewrite is for:

Goal Why the rewrite can reach it
Fewer crashes, stale textures and one-frame glitches One owner for each range of memory and one ordering for CPU and GPU writes, in place of six mechanisms
Fewer stutters No draw waits for a compile; no import of memory on the frame's path; no frame gate
Much better speed on PCs with fewer than 12 logical processors Today the replay runs on the game's thread there, so a frame costs the game's time plus the replay's. A thin encoder on its own threads removes most of that sum. Estimated, not measured
The remaining port-side fps on strong PCs The port's fixed GPU work (about 2 ms a frame in Kokiri Forest) and the host's work on the game's threads
Code that can be changed safely Parts that link and test by themselves, a tenth of the switches, checks that call functions

3. Ported, rewritten, dropped

Ported (brought over with their tests, their provenance and their licence, then improved in place):

Part From Why it is kept
The instruction translator and its tests third_party/a64-kit, nx2/insn.py, nx2/test_insn.py, nx2/test_leaf.py 742 instruction forms and whole functions checked against Unicorn bit for bit
The loader and image builder nx2/ (unpack, RELR, image layout, discovery, chunks) It works, and nothing measured points at it
The shader recompiler gpu/vk/eden The only translator for the Switch 2's shader binaries, with about 290 local fixes
What the Horizon layer knows host/: the 485 replaced SDK functions, the service answers, file system, audio, input, movies Each is a fact about the game's SDK that cost a boot to learn. The behaviour is ported; the threading and sync core under it is rewritten
Driver knowledge The per-GPU rules, the driver-fault quarantine, the workarounds with an issue number Ported as a table of rules, each with its reason and its issue
Upscalers and frame generation vk_dlss.cpp, vk_fsr3*.cpp, vk_fsr4.cpp, vk_xess.cpp, vk_framegen.cpp, vk_temporal.cpp Not where the failures are; they attach to the new frame's outputs
The menu's content, texts and translations vk_menu.cpp, menu_i18n.h The rows and their texts are kept; the drawing code is tidied when it moves
Mods, saves, controls, crash reports host/mods.c, the save and options code, host/control.c, the crash window Players' data and habits must keep working
The build's outside The Builder, the launcher, releases, the Test Farm, the forge tooling Outside the game's code

Rewritten to section 4's rules:

Part Replaces
The renderer's core: recording, encoding, memory, textures, pipelines vk_draw.cpp, vk_replay.cpp, vk_memory.cpp, vk_texture.cpp, vk_recorder.h, the policy headers
The NVN2 layer host/nvn_native.c: it records resolved draws, not NVN operations
Threads, sync and virtual cores host/hos_thread.c, host/nn_os_sync.c
What the lifter emits The code generation around the translator: registers, calls, write marks, optimisation levels
Switches One table from the first commit, with a budget (section 4)
The build pipeline nx2/build.py and nx2/make_game.py, as steps with declared inputs
Tests Checks that link the part they test

Dropped: the WebGPU renderer's remains (gpu/render's unused parts, gpu/third_party/suyu's unused parts), MKW's hooks, the emulator-hosted build, and every switch that is a kill switch for a path the new code does not have.

4. The design's rules

The renderer

  1. Nothing is read from the game's live memory after a submit. A submit hands over a frame packet that owns what it needs: the resolved draws and a copy of the small per-draw data (uniforms, indirect arguments). Large buffers are named by page version (rule 3). No frame gate.
  2. State is resolved when the game binds it, on the thread that binds it, with dirty bits. A recorded draw names its pipeline and its resources. The encoder looks nothing up and compares nothing.
  3. One timeline for memory. Every page of memory the GPU can see has a version, ordered by submit number, for the CPU's writes and the GPU's alike. It replaces captures, late pages, the late fix, shadows and the write-back diff. A read of GPU results by the game waits for exactly the version it needs.
  4. Encoding is parallel by pass. Each worker writes a command buffer of its own from the frame packet. No dry pass, no recorder thread, no global lock inside the encoding.
  5. Resources are bound through tables. One table for textures and samplers, one ring for uniform data, where the device allows; a second path for devices that do not, chosen once at start.
  6. No draw waits for a compile and none is skipped for one. Shaders and pipelines are prepared before the game and out of its process. A miss draws through a fast path that is always ready.
  7. Memory is budgeted by one accountant for VRAM and RAM together, with one eviction rule.
  8. A device feature is asked once, into one capabilities record. No Vulkan call is made without it.

The host

  1. Sync objects live in the guest's own memory words, as the SDK keeps them: a compare-and-swap when free, a wake only when a waiter bit is set, one waiter woken at a time. No object table.
  2. Virtual cores are kept (the game keys data on its core number without locks), but each core is a wait word of its own: no global lock and no timed polling.
  3. The game's idle workers sleep on their queue's wake, not on a 20 us poll, where the game's job queue can be hooked safely.

The lifted code

  1. Guest registers are locals inside a function, written back at calls, wherever the function's shape allows.
  2. Write marks are the renderer's cost and are budgeted as one. Stores that cannot reach GPU-visible memory mark nothing; the rest mark once.
  3. A committed hot list and play profile, if the measured gain justifies its build time (section 8). The player's build time does not grow by more than an agreed amount (section 9).

Everywhere

  1. A switch has a row from its first commit, and the table has a budget: player and per-hardware rows as needed, diagnostics behind one logging system, and no kill switch older than two releases.
  2. Every part links by itself and has checks that call it.
  3. Recording and playing a frame is part of the renderer, not a tool beside it: every bug report can carry a trace made on the player's PC and played on the developer's own copy of the game.

5. Upstreams to pull at the start

The start is the one moment a newer upstream is cheap, because everything is checked again anyway.

Upstream Pull the newest?
The shader recompiler (Eden, by way of Lichii and Fritchii) Yes. Rebase the local fixes onto the newest. The local Lichii tree of 2026-11-08 has passes Longshot lacks (register pressure, trap guards, storage write extents, descriptor limits). 60 files differ and both sides built some features separately, so it is weeks of work and every player's shaders are translated again
The lifter kit (a64-kit) Check first. Longshot's copy is TOTKPort's of 2026-10-30 with local changes. Look for work on local registers and emitted code
mkw-recomp and Hookshot No. They share the structure this plan leaves. Their game fixes and driver findings are still read
Lichii's renderer No, as a base. It emulates the GPU below NVN2 and copies memory in and out of caches; importing the game's memory in place is better. Its descriptor queue and update templates are worth porting
suyu's translator No. It is checked bit for bit as it is
Libraries (ImGui, zstd, Opus, SDL, the upscalers' headers) Only for a fix or feature that is needed

6. Milestones

Milestone Done when
R0 Reference traces The current code records a named set of scenes (Kokiri Forest, the Market, Hyrule Field, a dungeon, a menu, a movie) with #1334's recorder, and plays each back to the live run's pictures. A tool compares two renderers' pictures of one trace
R1 The new tree A new code base builds on Windows and Linux with the ported translator, loader and recompiler, each with its provenance and its tests passing
R2 One frame The new renderer plays one recorded frame to the same picture as the old one, with no game running
R3 The scene set It plays every R0 trace to the old pictures, clean under validation, on one card of each vendor
R4 Gameplay The game boots in the new tree on the new host core and plays Kokiri Forest with the new renderer
R5 Memory holds A tour of the overworld has no stale texture and no missed write by the audit, and stays inside the budgets on a 6 GB card
R6 Features Upscalers, frame generation, the menu, mods, saves, controls, crash reports, the Builder and the launcher work as in the current release
R7 Lifted code Each change to what the lifter emits has its fps and its build time measured; the ones that pay are in
R8 Switch-over On the Test Farm's configurations the new build is no slower and has no picture difference left unexplained. Players move to it; the old code is archived

7. What waits for what

  • R0 waits for nothing. It is work in the current code and is worth having even if the rewrite stops.
  • R1 waits for the decisions of section 9. R2 needs R0 and R1. R3 needs R2.
  • R4 needs R3 and the host core. The host core can be built beside R2 and R3, checked with the lifter's own tests.
  • R5 needs R4. R6 needs R4 and can run beside R5.
  • R7 waits for nothing but R1, and is a track of its own.
  • R8 needs everything.

8. Questions to answer first

Each is a measurement or a small experiment in the current code, made before the part it decides is designed.

  1. How much do write marks cost this game's threads? A build with RX_NO_GUEST_MARKS says (the kit's note is about 1 ms a frame, for another game).
  2. What do local registers give? A64_LOCAL_REGS exists as an experiment: its fps and its build time on the hot functions.
  3. What does a hand-over between virtual cores cost the frame? The test running on 2026-11-17 answers it. If it is nothing, rule 10 is tidying, not speed.
  4. How large is a frame packet's owned data? The submit-time captures are about 9 MB by the code's note. Rule 1 needs the small per-draw data to be a small part of that.
  5. Can state be resolved at bind time for this game? Its render conditions read reports made earlier in the same stream, so some answers exist only at replay. Count how many draws that touches.
  6. Does every tested driver allow rule 5's tables? If not, how many players need the second path.
  7. How large is a trace, and is it the same twice? (The rework plan's questions 1 and 2, for R0's scene set.)
  8. What has Fritchii changed in the recompiler since the Lichii tree of 2026-11-08? It is not on any team PC that was checked.

9. Decisions needed

  1. A clean break or a second tree? A new repository with its own rules, or a new tree inside this one behind vk_api.h. The first is cleaner; the second lets players get the new renderer before the rest is done.
  2. Who keeps the current code alive while the rewrite is built, and which fixes it still takes.
  3. What happens to the rework plan's remaining work. Its switch pull requests are merged (#1309, #1390). Proposed: finish the tools (#1334, open), which R0 needs; the rest only where players gain before R8.
  4. The lowest card and PC the new code promises to hold (the rework plan proposes 4 GB of VRAM and 16 GB of RAM).
  5. How much longer a player's build may take for faster lifted code.
  6. Whether the recompiler is rebased onto its newest upstream at the start (section 5), with its retranslation.
  7. The name and the licence notices of the new tree. The translator and the recompiler keep it GPL.

10. Rules for the work

  • The current code is the reference. A difference in a picture is the new code's bug until shown otherwise on a trace.
  • A ported part comes with its provenance, its licence and the commit it was taken at.
  • Design first. A part's rules are written on this page before its code, and changed here when the code shows them wrong.
  • Measured. A claim about speed or memory names its PC, its scene and its runs, interleaved with the reference.
  • Nothing made from the game leaves the PC. Traces, captures, pipeline lists and lifted code are game files.
  • Run in the game before a pull request opens, as today.

11. Risks

  • Months without the new code reaching players. The second tree of decision 1 is the way to shorten that.
  • Bugs fixed once come back. The old code's fixes are facts about drivers and about the game; R0's traces and the ported rules table are the guard, and they will not catch everything.
  • Fps on strong PCs moves little (section 2). If that is the main goal, the rewrite is the wrong tool and the game's own loop is the place to look.
  • Two code bases split the team's attention. Fixes to the old code slow the new one, and the reverse.
  • The design's rules may not fit the game. Questions 4 and 5 can each sink a rule; they are asked first for that reason.