mirror of
https://github.com/valentderah/totk-pc-recomp.git
synced 2026-11-19 12:25:56 +00:00
Merge branch 'dev' into carry/sync-ahead
This commit is contained in:
7 files changed
+459
-1
No files matched your search
@@ -0,0 +1,91 @@
|
||||
# Rules for taking a PR
|
||||
|
||||
## 1. What to review first
|
||||
|
||||
1. Fixes before features. A PR that fixes a bug, a glitch or a crash goes first; feature PRs wait.
|
||||
2. Order fixes by reach: how many players the bug hits and how badly. Windows and default settings first, rare
|
||||
hardware and unusual setups later.
|
||||
3. Scale the depth of the checks to the reach. A crash many players hit and anything on the frame path get the full
|
||||
checks. A rare case (a CPU without AVX, an unusual setup) gets the minimal fix, one targeted check and a short
|
||||
note. A crash fix on rare hardware is still worth taking: cut the checks around it, not the fix.
|
||||
4. Before testing, find out where the bug reproduces: OS, GPU vendor and generation, game version, settings. If the
|
||||
symptom cannot appear on the hardware at hand (an NVIDIA paging bug on an AMD machine), say so and do not run
|
||||
tests that cannot decide it.
|
||||
5. Check a feature PR against the designs in `docs/milestones/`. A feature with a design (mods, cheats) goes in as
|
||||
part of that design.
|
||||
6. Several PRs on one topic: compare them before taking either. Another PR may already do it right.
|
||||
|
||||
## 2. How to read the diff
|
||||
|
||||
- The author's claim is a hypothesis. Read the whole diff: races, wrong semantics, edge cases, leaks, lock order.
|
||||
- Check the behaviour against evidence: how yuzu, Ryujinx, LAS Recomp, SavageWindRecomp, nxnative and MacNativeGames
|
||||
do the same thing in `refs/` (`tools/fetch_refs.sh` recreates it); the Vulkan spec; hardware docs
|
||||
([docs/maxwell.md](../../docs/maxwell.md)); upstream issues.
|
||||
- Weigh two things for every change: its cost on the hot path, and how it fails (device lost, hang, stale data, weak
|
||||
or non-AVX CPUs, other GPU vendors, Wine/Proton).
|
||||
- Read the code a hypothesis depends on before running the game: the game's functions in Ghidra or
|
||||
`generated/<ver>`, our path in `runtime/`. A run confirms what the code could not rule out. It is one run, not a
|
||||
series of variants.
|
||||
- Order the work so the cheapest check that could refute the PR's idea runs first. Refuted: stop, write down why,
|
||||
no build, no benches.
|
||||
|
||||
## 3. What a PR needs
|
||||
|
||||
- **Proof.** The bug reproduced before the fix, the same repro after, both results side by side: a screenshot, a log
|
||||
line, a probe, a differential test. A fix without a reproduced failure is not proof. Where a repro is impossible
|
||||
on the hardware at hand, say so; the fix is then taken only on strong static evidence in the code. Where a repro is
|
||||
risky (device lost or a TDR can hang the machine), write the recipe and let the owner decide.
|
||||
- **Frame-path changes** get whole runs of the heavy scene with the switch off and on, at least two each
|
||||
([02-performance.md](02-performance.md)). Zero new slow frames is a hard bar.
|
||||
- **A switch.** A change on the hot path or in rendering sits behind an env or `totk.ini` switch, so a player can turn
|
||||
it off and we can compare.
|
||||
- **Nothing changes for players outside the feature.** The DLSS PRs touched shared code; they went in once every
|
||||
path that runs without DLSS was gated on DLSS being on.
|
||||
- **A fix for one setup keeps the default for everyone.** The PRs that raised the low memory block from 6 to 10 GiB for
|
||||
all players were rejected; the right shape is 6 GiB plus the extra where it is needed.
|
||||
- **Parts we cannot run** (Linux-only code, an HDR display, RTX-only paths) are gated so they cannot touch anyone
|
||||
else, or wait for a report from someone with that hardware. Note them as unrun.
|
||||
- **Project tests** from [03-correctness.md](03-correctness.md): lifter differential tests, probes, `--selftest`,
|
||||
`tools/check_content.py --staged`.
|
||||
- **Text the player sees** goes into the catalog: `runtime/ui_text.h` ids and `runtime/ui_text.c` entries in every
|
||||
language the menu has (English, Russian, Brazilian Portuguese, Simplified Chinese), and `installer/text/*.json` for
|
||||
the installer. No hardcoded sentences, no second string table.
|
||||
- **A new setting** is described in `totk.ini.example` and [docs/settings.md](../../docs/settings.md).
|
||||
- **Licences.** MIT, BSD, ISC, zlib and Apache-2.0 code may be copied, with its header and a row in
|
||||
`THIRD_PARTY_NOTICES.md`. yuzu, suyu and other GPL code is read for behaviour only; we write our own.
|
||||
|
||||
## 4. Reasons to reject or rework
|
||||
|
||||
- No test or repro for a change that is not trivial.
|
||||
- Slow: a state copy per draw, a global atomic counter on the hot path, synchronous file I/O or a GPU allocation on a
|
||||
game or render thread, new slow frames.
|
||||
- Changes behaviour for everyone to serve one setup, or is on by default without a run in a scene where it acts.
|
||||
- "Fixes" a crash by turning a feature off for a vendor. A crash that goes away with a feature off points at the bug;
|
||||
the feature gets fixed.
|
||||
- Breaks another feature (a preview that loses anti-aliasing).
|
||||
- Fake features: labelled FSR4 or frame generation, and not that.
|
||||
- Wrong measurements: percentiles over window means, counters over the wrong set.
|
||||
- Generated C edited by hand instead of the generator (`recomp/`).
|
||||
- A disallowed licence or pasted GPL code.
|
||||
|
||||
## 5. Finishing a good PR
|
||||
|
||||
A good PR that misses the project's scheme (hardcoded text, conflicts, layout, comment style) is brought to it while
|
||||
merging, not sent back to the author for another round. When only part of a PR is good, take that part and note what
|
||||
was left out and why.
|
||||
|
||||
A bug found outside the PR under review is not fixed on the spot: search the open PRs on that topic, report the bug
|
||||
with them, and let the owner decide.
|
||||
|
||||
## 6. Merging, branches, commits
|
||||
|
||||
- Each PR or wave of PRs gets its own branch `task/<tag>` from a fresh `dev` and its own build dir. It merges into
|
||||
`dev`.
|
||||
- Once the review is done, the symptom is gone on one paired shot and the probes pass, merge into `dev` and hand the
|
||||
build to players: they test in game faster and wider than our routes. The wider checks (other routes, validation,
|
||||
fps cost) follow as a separate diff. Speed never skips the review of the diff itself.
|
||||
- `main` only with the owner's explicit yes. Push only when told to.
|
||||
- A commit message is a plain English sentence, no `feat:`/`fix:` prefixes.
|
||||
- The version lives in the repo-root `VERSION` file; the owner decides when it moves.
|
||||
- After a merge, record which PRs went in, what was reworked, what was rejected and why. The reason for a rejection
|
||||
goes into the PR as a plain English comment.
|
||||
@@ -0,0 +1,97 @@
|
||||
# Performance: no lost frames on weak hardware
|
||||
|
||||
## Who we tune for
|
||||
|
||||
- The goal is many more fps on modest hardware, and Steam Deck later (Zen 2 4c/8t APU, shared LPDDR5, the exe runs
|
||||
through Proton/Wine).
|
||||
- The developer's machine (Ryzen 9 7900X + RX 9070) is fast and its numbers do not carry over. A laptop with an
|
||||
i7-9750H and a GTX 1050 Ti is a sample of a weak machine, not the target to fit constants to.
|
||||
- What weak hardware measured:
|
||||
- GTX 1050 Ti (4 GiB, 214 MiB BAR, no ReBAR): the GPU read imported host pools over PCIe, 110-120 ms a frame
|
||||
against 4.3 ms on the RX 9070. The VRAM mirror brought it to 10-11 ms; that machine is now CPU-bound at 25-45 fps,
|
||||
replay 25-30 ms a frame.
|
||||
- The same write-watch scan costs about 3x the CPU time there.
|
||||
- NVIDIA and desktop AMD GPUs have no ASTC: textures decode in a compute shader. CPU decodes before that made
|
||||
0.4-0.7 s load frames on the 1050 Ti.
|
||||
- Wine emulates `GetWriteWatch` with `mprotect` and a fault per first write. Anything relying on cheap OS memory
|
||||
tricks (write-watch, `VirtualProtect` freezing, fault handlers) is checked against Wine's implementation.
|
||||
- The port uses about half of even a weak CPU, so the frame's critical path is the limit, not throughput. TotK keys
|
||||
per-core data by `GetCurrentProcessorNumber` without locks, so the game's threads share three virtual cores on any
|
||||
host. In a fight the main thread and five job workers keep 2.6 of the 3 busy: guest code speed sets the fps.
|
||||
- Perf work builds and measures 1.4.3. A 1.2.1 build is for a change about to merge with a large gain.
|
||||
|
||||
## Gain ceiling first
|
||||
|
||||
Before writing or taking a perf change, compute its ceiling: the share of the code it removes times the share of the
|
||||
frame that code holds on the critical path, on weak hardware. A ceiling of a few percent or less is not worth it.
|
||||
|
||||
- Use the critical path (`TOTK_CRIT` + `tools/crit_path.py`, heavy frames only), not one thread's profile. On the weak
|
||||
laptop the submit thread is 55% replay, yet the critical path of heavy frames is 67% guest code, 15%
|
||||
`nvnSyncWait`, 13% core waits and wake latency.
|
||||
- Changes that can move the frame by 10% or more are usually design changes. Polishing a hot function from a flat
|
||||
profile almost always gives zero.
|
||||
|
||||
## A neutral safe change stays
|
||||
|
||||
An optimization that measures neutral on the fast machine stays on by default when:
|
||||
|
||||
- upstream (`refs/`, other ports) reports a gain for it, especially on weak CPUs or GPUs;
|
||||
- the static read leaves no hazard, and the probe or differential test passes;
|
||||
- whole heavy-scene runs off/on x2 show no fps loss and no new slow frames;
|
||||
- a switch turns it off.
|
||||
|
||||
"No gain here" is not a reason to drop a safe change with upstream evidence. A regression or a hazard nobody ruled
|
||||
out is.
|
||||
|
||||
## How to measure
|
||||
|
||||
- **By game time, never by frame counts.** Run length, analysis windows, A/B blocks and input scripts go by the world
|
||||
clock (`--seconds`, `TOTK_CRIT=w<lo>-<hi>`, `TOTK_PROFILE_FRAMES=w<lo>-<hi>`, `TOTK_SHOTS=w<lo>-<hi>:<step>`). The
|
||||
same frame count at another fps is another scene.
|
||||
- **Check a scripted run reached the world.** Title menus on a slow boot eat button presses; confirm the run is in the
|
||||
world before trusting its numbers.
|
||||
- **Whole runs off and on, two each at least.** An in-run A/B on a moving scene lies: the A and B blocks land on the
|
||||
same game seconds every run, so a content difference repeats. One in-run A/B showed "-11% replay"; whole runs gave
|
||||
5.84/5.73 against 5.76/5.73 ms, nothing. In-run A/B only on a static scene (standing still).
|
||||
- **Spread.** One script on near-identical builds gave 1% lows from 31.5 to 50 fps. Compare medians of three runs,
|
||||
never one run against one run.
|
||||
- **A quiet machine.** `tools/run_game.py --quiet` takes the machine-wide lock; no other `totk.exe`, build or test runs
|
||||
meanwhile. One game at a time.
|
||||
- **A warm shader cache, prepared properly.** Shader and pipeline caches are not copied between build dirs:
|
||||
`totk.exe --prepare-shaders` or `--warm-shaders` in that dir. The AMD driver cache is keyed to the exe path and
|
||||
limited in size: preparing another build dir can evict this one's libraries (40-220 ms per new effect in play).
|
||||
- **A heavy scene.** A fight with a large enemy and a crowd, fps limit at the maximum (`TOTK_FPS_LIMIT=360`). Compare
|
||||
one shot with the scene's reference before trusting numbers.
|
||||
- **No base runs by habit.** Run the candidate alone and judge it against the targets: max fps, zero slow frames
|
||||
(`perf: slow frame`), no black or flat frames, no new validation errors. Glitches are found by looking at shots and
|
||||
frame dumps, not by diffing metrics. Run a base build only when a specific question needs a side-by-side.
|
||||
|
||||
| What | How |
|
||||
|---|---|
|
||||
| fps, worst frame, render-thread buckets, GPU busy, VRAM | `--env TOTK_TRACE=perf,sched`, then `python tools/perf_summary.py <log> <lo> <hi>` |
|
||||
| the frame's critical path | `TOTK_CRIT=w<lo>-<hi>` + `TOTK_CRIT_OUT=<path>`, then `python tools/crit_path.py <file>` |
|
||||
| sampling profiler | `TOTK_PROFILE=<path>` + `TOTK_PROFILE_FRAMES=w<lo>-<hi>`, then `tools/prof_report.py <profile> <totk.map>` |
|
||||
| A/B on a static scene | `TOTK_AB=<seconds>`, then `tools/ab_summary.py --skip <seconds>` |
|
||||
| VRAM pressure on a large card | `TOTK_VRAM_LIMIT_MIB=<MiB>` caps the budget the port sees |
|
||||
|
||||
## What the hot path must not do (Windows host)
|
||||
|
||||
- **Files.** The game threads (main, job workers) and the render thread never open, read, write or flush a file, and
|
||||
never wait for a thread that does. Opening a 20-byte file in a 139k-file folder: 0.1 ms idle, 11-40 ms in play while
|
||||
the translator, the pipeline cache and the save wrote to the same volume. A save's `FlushFileBuffers` and
|
||||
`MOVEFILE_WRITE_THROUGH`: 93-135 ms. Saving the pipeline cache under its lock on the present thread froze the replay
|
||||
every 20 s. File I/O goes to a background thread; results come back in memory.
|
||||
- **Waits.** Short waits spin on the counter; waits over 1 ms use the high-resolution timer. A waitable timer wakes
|
||||
0.3-0.5 ms late; the SDK's 20 us sleeps took 460-515 us. A 1 ms timer thread does not help: it gave more slow frames.
|
||||
- **GPU allocations.** VMA's `vkAllocateMemory` of a 256 MiB block under its lock: 8-23 ms. A new block on the render
|
||||
thread is a hitch.
|
||||
- **128-bit division.** `(unsigned __int128)t * num / den` compiles to the library call `__udivti3`; counter
|
||||
conversions that way took a tenth of the game threads' time in a fight. Use the precomputed scale (`platform.h`
|
||||
`PlatScale`).
|
||||
- **Per-draw copies and counters.** A pipeline-state copy per draw, a global atomic counter, a scan of every page each
|
||||
frame: on a weak CPU each is frames.
|
||||
- **Memory kept per frame.** Anything allocated per texture initialization or per frame must be freed. One copy kept
|
||||
per texture init grew host memory by ~44 MiB a game minute until a commit failure after hours (#670). Check private
|
||||
memory over a few idle minutes for a PR that stores per-object state.
|
||||
- **Scheduling.** Any timing or scheduling change is checked for slow frames. A preempt check at every host call made
|
||||
one bug rarer but added 50-75 ms CPU hitches and was reverted.
|
||||
@@ -0,0 +1,92 @@
|
||||
# Correctness: checks that keep behaviour intact
|
||||
|
||||
## Lifter and generated C
|
||||
|
||||
- Generated C is never edited by hand: change the generator in `recomp/`.
|
||||
- `recomp/layout.py` alone decides module bases.
|
||||
- Every change to the lifter or the CPU headers (`runtime/cpu.h`, `runtime/simd.h`) passes the differential tests
|
||||
against Unicorn, all run with `.venv`:
|
||||
|
||||
| Test | Checks |
|
||||
|---|---|
|
||||
| `tests\diff\lift.py` | instructions sampled from the modules; `--coverage` lists the words the lifter rejects |
|
||||
| `tests\diff\simd.py` | the whole FP/SIMD encoding space |
|
||||
| `tests\diff\atomic.py` | exclusive load/store and ARMv8.1 atomics |
|
||||
| `tests\diff\func.py` | whole functions as the generator emits them: loops, jump tables, calls |
|
||||
| `tests\flags_check.py` | the function-local flag helpers against the packed ones |
|
||||
| `tests\excl_mt.py` | the exclusive monitor under contention and ABA, on several threads |
|
||||
| `tests\jumptables_check.py` | `recomp/jumptables.py` against Unicorn: 0 disagreements on 1.2.1 and 1.4.3 |
|
||||
|
||||
- A `--cpu v2` build (no AVX2) passes the same tests with `--cflags=-march=x86-64-v2`. Players without AVX exist.
|
||||
- A compile error in generated C on a line the generator could not have written is a bit flip on disk or in memory.
|
||||
Regenerate and compare hashes; leave `recomp/` alone.
|
||||
|
||||
## Runtime
|
||||
|
||||
- From the build dir: `totk.exe --selftest`, `--probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex`, `--probe-shader`
|
||||
pass.
|
||||
- Settings: `totk.exe --probe-cfg` and `python tests\settings_doc_check.py`.
|
||||
- Button prompts: `.venv-py314\Scripts\python tests\romfs_prompts_test.py`. Build dirs carry only `romfs-patches`; to
|
||||
test PC or Xbox prompts in game, generate the overlay first:
|
||||
`.venv-py314\Scripts\python tools\make_romfs_patches.py --version <ver> --prompts pc --out build\<dir>\romfs-patches-pc`,
|
||||
then restart the game.
|
||||
- Installer: `tests\installer_gui_test.py` (event model, form, catalogs, cancel, display scale).
|
||||
- Shaders: `tools\shader_census.py --version <ver> --translate`, `tools\xlate_smoke.py`. A translator patch
|
||||
(`tools/xlate/patches/`) needs `build/xlate` rebuilt and changes shader hashes: anything keyed to a shader hash
|
||||
breaks with it.
|
||||
|
||||
## GPU portability
|
||||
|
||||
- New Vulkan code queries the feature, extension, format or limit it uses and keeps a working path or a logged
|
||||
fallback without it (provoking vertex and subgroup size pinning in `vk_pipeline.c` are examples).
|
||||
- Never hardcode what one GPU reports: alignments, subgroup size (RDNA4 may run wave64, old AMD Vega is wave64 only),
|
||||
depth formats, `maxPushDescriptors`.
|
||||
- One queue: every submit and present takes `vk_queue_lock`. Presenting from its own thread on a second queue gave
|
||||
device lost on GTX 10-series in another port.
|
||||
- RDNA1/2 bugs do not reproduce on RDNA4 (another driver branch); NVIDIA bugs do not reproduce on AMD. A Ryzen 7000
|
||||
iGPU is RDNA2 and runs the RDNA1/2 driver branch: a cheap testbed for those reports.
|
||||
- Validation: a `--validation` run in the world shows no new messages.
|
||||
|
||||
## Maxwell / NVN behaviour
|
||||
|
||||
The port must do what the Switch GPU does, not what Vulkan does by default. The full list with sources:
|
||||
[docs/maxwell.md](../../docs/maxwell.md), section 7. The traps a PR breaks most easily:
|
||||
|
||||
- Provoking vertex: Vulkan takes the first vertex, NVN the last.
|
||||
- Unwritten vertex outputs read (0, 0, 0, 1).
|
||||
- A colour target outside the fragment shader's output map keeps its texel (write mask 0). AMD writes garbage there.
|
||||
- Feedback loops: the G-buffer pass reads its own targets. It needs the feedback layout and a by-region barrier.
|
||||
- Depth bias argument order, depth mode, depth clamp: checked against deko3d.
|
||||
- Report timestamps: the engine's GPU time comes from them, and dynamic resolution and game speed follow it.
|
||||
|
||||
## Timers and the real-time step
|
||||
|
||||
- With `realtime` set, the game steps by a measured ratio, not whole 30 Hz units. A countdown remainder in
|
||||
(0, FLT_EPSILON] is never stepped again, and a consumer testing `> 0` sees it active forever. That was "weapons
|
||||
cannot be changed after a Fuse until a reload" (#18).
|
||||
- Symptoms of this class: stuck until a reload or teleport, locked after an action, works sometimes.
|
||||
- A PR touching the frame step, the pacer or the fps limit is checked for this class.
|
||||
|
||||
## Threads and scheduling
|
||||
|
||||
- ARMv8 `stlr` then `ldar` is ordered (RCsc); C11 release/acquire lets x86 reorder that store and load. Changes to
|
||||
the lifter's barriers or atomics pass `tests\diff\atomic.py` and `tests\excl_mt.py`.
|
||||
- A scheduler change is judged from one `TOTK_TRACE=sched` run by how long a ready, better thread waits for a core it
|
||||
may use, plus the slow-frame count. Not by statistics over many runs.
|
||||
- A crash that looks like a race: rule out the save first. One reported crash was the save itself; it crashed the
|
||||
same way on a real Switch.
|
||||
|
||||
## Files and caches
|
||||
|
||||
- A crash leaves zero-filled files. Caches are validated on load, not trusted because they exist.
|
||||
- The pipeline cache is dropped when vendor, device or `pipelineCacheUUID` change.
|
||||
- Unicode paths: W APIs with UTF-8 to UTF-16 conversion.
|
||||
- A failure that happens once and does not come back: rerun before debugging it as a code bug. Broken caches and bit
|
||||
flips happen.
|
||||
|
||||
## Game content boundary
|
||||
|
||||
- The repository is public. No game files, and nothing extracted or generated outside `build/` and `generated/`.
|
||||
- Keys never appear in logs, commands, files, issues or comments.
|
||||
- Every file the generator emits carries the `GENERATED_MARKER` defined in `tools/check_content.py`.
|
||||
- `python tools/check_content.py --staged` before every commit. CI runs the same check.
|
||||
@@ -0,0 +1,97 @@
|
||||
# Knowledge base
|
||||
|
||||
Before investigating a symptom, or trusting a PR that "fixes" it, look for it here. Search by what the player sees
|
||||
(black, magenta, flicker, slow motion, missing, stale, streaks) and by the object (sky, grass, shadow, fog, HUD).
|
||||
|
||||
## Invariants of recent changes
|
||||
|
||||
A PR that touches these areas must keep them.
|
||||
|
||||
- **Queue order.** When anything is submitted, every earlier part is already on the queue. Present, uploads, readbacks
|
||||
from guest threads and the `vkDeviceWaitIdle` sites rely on it. The recorder thread now begins, ends and submits
|
||||
the parts it records; the submitting thread still waits for that submission, so the order holds.
|
||||
`TOTK_REC_END=0` restores the old split.
|
||||
- **GPU-written memory is never frozen.** Storage-buffer stores, copies and fills land in imported guest memory
|
||||
without a fault or a write-watch bit, so a region only the GPU writes looks idle. Such regions are never frozen
|
||||
read-only, and a frozen region is thawed before a GPU write. LAS Recomp never changes the protection of imported
|
||||
memory because of NVIDIA. A suspected cause of NVIDIA "write invalid" device faults (#788, #802), not proven.
|
||||
- **VRAM pressure.** Under pressure, released textures whose storage the game has given to another texture go first:
|
||||
30 s after release and once no finalized slot has bound them for 600 submits. Clean mirrored entries wait 5 s.
|
||||
Both stop once use is back under the line. A PR touching texture lifetime is tested with `TOTK_VRAM_LIMIT_MIB`.
|
||||
- **Texture pins are freed.** Each pin counts the recording copies naming it and is freed 1200 submits after its last
|
||||
use unless the replay holds it as a render target. Before that, pins leaked ~44 MiB a game minute (#670).
|
||||
|
||||
## Fixed bug classes
|
||||
|
||||
If a PR touches this code, confirm the fix still holds.
|
||||
|
||||
| Symptom | Cause | Where the fix is |
|
||||
|---|---|---|
|
||||
| lime silhouettes in grass; rectangles in the sky | a target outside the output map must keep its texel; zero-filling it wiped the half-res depth | `vk_pipeline.c` `target_wmask` |
|
||||
| stale grass maps in the far terrain for a second after a hit | write-back of a texture the CPU had rewritten | `vk_texture.c` `write_back` |
|
||||
| cut grass stays standing; fire does not spread (#132) | CPU reads of GPU-rendered textures without an invalidate | `vk_texture.c` `vk_texture_write_back_small`, `nvn_ext.c` `nvn_pool_invalidate` |
|
||||
| cloud and fog volumes empty for the session | a one-shot draw skipped instead of waiting for its pipeline | `vk_exec_draw.c` `prepare_draw` |
|
||||
| tile rectangles | storage buffers bound by Ryujinx first-use order, not the c0 slot | `vk_exec_draw.c` `ssbo_slot` |
|
||||
| black dialog background and loading map | 3D targets rejected, the grading LUT never written | `vk_exec.c` `resolve_target` |
|
||||
| streaks on cliffs | primitive restart ignored | `vk_exec_draw.c` `restart_for` |
|
||||
| streaky map screen | the newest texture picked at shared storage | `vk_texture.c` `vk_texture_by_id` |
|
||||
| dark 16x16 blocks on the ground, sage spirit not drawn | G-buffer feedback loop | `vk_exec_draw.c`, `TOTK_FEEDBACK` |
|
||||
| magenta cave walls, brown sky | CPU-filled textures without a flush | write-watched mirrors, `vk_memory.c`, `vk_texture.c` |
|
||||
| black 3D scene | deferred texture binds | `nvn_api_cmd.c` `Bind*Deferred` |
|
||||
| HUD prompt boxes, black stamina wheel | `nvnTextureCompare` ignored the channel mapping | `nvn_api_obj.c` |
|
||||
| crash on world load | `GetCommandMemoryUsed` did not follow the driver's sizes; the game sizes model heaps from it | `nvn_api_cmd.c` |
|
||||
| 20 fps | a yield back-off starting before 2 ms | `kernel.c` SVC 0x0B: no back-off |
|
||||
| weapons locked after a Fuse (#18) | timer remainder in (0, FLT_EPSILON] with the real-time step | patch under the `realtime` setting |
|
||||
| magenta/blue garbage or device lost on RDNA1/2 (#5) | writes into 3D BC block views | in `dev` |
|
||||
| black window after a driver update | a pipeline cache from another driver | `vk_pipeline.c` drops the cache by UUID |
|
||||
|
||||
## Known open risks
|
||||
|
||||
A PR touching these needs stronger proof.
|
||||
|
||||
- Buffer textures are not replayed and bind a stand-in: light and decal lists may read 0.
|
||||
- New GPU-only colour images start undefined; feedback effects may show garbage.
|
||||
- Clears with a partial channel or stencil mask are skipped (`W_CLEAR_MASK`, `W_STENCIL_MASK`).
|
||||
- 8-bit indices are widened on the CPU at record time; a copy in the same submission gives stale indices.
|
||||
- `UpdateUniformBuffer` is a copy between full barriers and ends the render pass (fps outdoors).
|
||||
- Report timestamps carry host time at fence completion: the engine's GPU time is wrong.
|
||||
- The game's SVC-free spin loops burn a host core (843 in `main`).
|
||||
- Images aliased onto one GPU-only pool allocation do not see each other's data on AMD.
|
||||
|
||||
## Past PR decisions
|
||||
|
||||
| PR | Decision | Why |
|
||||
|---|---|---|
|
||||
| #690 shrine snapshots | rejected | a pass restart per copy, a `VkPipeState` copy per draw, broken `bind_sig` skip; fps loss |
|
||||
| #674 | rejected | a global STXR counter on the hot path |
|
||||
| #660 | rejected | the preview loses anti-aliasing |
|
||||
| #713, #576 | rejected | low memory block 10 GiB for everyone; should be 6 GiB plus the extra where needed |
|
||||
| #573 | rejected | dynamic resolution off by default for everyone, the 1.4.3 site never run |
|
||||
| #568, #569 | rejected | fake FSR4 and frame generation |
|
||||
| #487 | rejected | wrong metrics: percentiles over window means, counters over the wrong set |
|
||||
| #451, #380 | rejected | not painless to take |
|
||||
| #566, #594, #534 DLSS | taken with changes | #594's shared paths gated on DLSS being on; nothing changes without DLSS |
|
||||
| #489 | partly taken | the runtime part checked by a frame dump; the installer's DLL download was the owner's call, its pinned hash re-checked |
|
||||
| #519, #582 amiibo | rewritten by us | took the data-format fixes; left out the features and the Linux event rework |
|
||||
| #483 vs #585 | #585's mapping kept | #483's stick glyph mapping was rewritten unasked while #585 already had it right |
|
||||
| #528 rain | taken after a check | code review fine, merged only after a run on a rain save |
|
||||
| #767 | taken with our fix | the default was skipped with `prompts = xbox|pc` when those folders did not exist |
|
||||
| #625 frame queue | taken, off by default | a new frame queue, one field run with it on |
|
||||
| #743 UB overlay | waiting | +25% in a Depths fight on an RTX 4080; needs review, fight runs x2 and shots on AMD |
|
||||
|
||||
## Our mistakes, not to repeat
|
||||
|
||||
- **"-11%" was an A/B artifact** of a moving scene. Whole runs off/on showed zero.
|
||||
- **Micro-optimizations from a flat profile** (1-3% of samples each) gave 26.2 against 26.4 ms on the weak laptop:
|
||||
nothing. Nobody had computed a ceiling.
|
||||
- **A scheduler patch merged on run statistics** added 50-75 ms hitches. Slow frames are a hard bar.
|
||||
- **Ten game runs on lock theories** where one Ghidra read of the game's code narrowed it at once.
|
||||
- **45 minutes of builds and benches** on an idea its own first thread census had refuted: the game pins 53 of 56
|
||||
threads itself. The cheapest refuting check goes first; when it refutes, stop and write the idea down.
|
||||
- **Tests of a bug that could not appear on the hardware at hand** (NVIDIA paging on an AMD machine): 245k tokens and
|
||||
37 minutes for nothing. Ask first where the bug reproduces.
|
||||
- **Turning the recorder off for a vendor** instead of finding its bug. Stopped: the feature gets fixed, not silenced.
|
||||
- **Bisecting code when every build crashed the same way at once.** The cause was a bad page of a game file in the OS
|
||||
file cache. When all builds fail identically, suspect inputs and caches first.
|
||||
- **A duplicate issue closed with a bare "Same as #N"** lost the logs and links. Move everything useful to the issue
|
||||
that stays open first: hardware, driver, version, when it happens, workarounds, links from comments.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Per-PR checklist
|
||||
|
||||
## Before reading
|
||||
|
||||
- [ ] Fix or feature? Fixes first, ordered by how many players they reach.
|
||||
- [ ] Where does the bug reproduce: OS, GPU vendor and generation, game version, settings? Can the hardware at hand
|
||||
show it?
|
||||
- [ ] Is the symptom in [04-knowledge.md](04-knowledge.md) or `docs/maxwell.md`?
|
||||
- [ ] Another open PR on the same topic? Compare them.
|
||||
- [ ] Feature: is there a design in `docs/milestones/`?
|
||||
|
||||
## Reading the diff
|
||||
|
||||
- [ ] The whole diff read, not the description: races, edge cases, lock order, leaks.
|
||||
- [ ] Behaviour checked against `refs/` (Ryujinx, yuzu, LAS, SavageWind, nxnative, MacNativeGames), the Vulkan spec,
|
||||
`docs/maxwell.md`.
|
||||
- [ ] Hot-path cost: no file I/O, GPU allocations, waits, per-draw copies or global atomics on game or render threads.
|
||||
- [ ] No memory kept per frame or per object without a free.
|
||||
- [ ] Failure modes: device lost, hang, stale data, CPUs without AVX, NVIDIA/Intel/old AMD, Wine/Proton.
|
||||
- [ ] New Vulkan code queries the feature and has a fallback; nothing hardcoded for one GPU.
|
||||
- [ ] Invariants kept: queue order, GPU-written memory never frozen, VRAM pressure path, pins freed.
|
||||
- [ ] Players without the feature see no change. The default for everyone stays for one setup's sake.
|
||||
- [ ] New behaviour behind a switch. A new setting described in `totk.ini.example` and `docs/settings.md`.
|
||||
- [ ] Player-visible text in the catalogs, in every menu language (`runtime/ui_text.c`, `installer/text/*.json`).
|
||||
- [ ] Copied code: allowed licence, header kept, row in `THIRD_PARTY_NOTICES.md`. No GPL code.
|
||||
- [ ] Generated C not edited by hand.
|
||||
- [ ] Parts we cannot run (Linux, HDR, RTX-only) gated away from everyone else and noted as unrun.
|
||||
|
||||
## Proof
|
||||
|
||||
- [ ] Repro before the fix and the same repro after, side by side.
|
||||
- [ ] Lifter or CPU headers: differential tests against Unicorn; `jumptables_check.py` 0 disagreements.
|
||||
- [ ] Runtime: `--selftest` and the four probes pass.
|
||||
- [ ] Settings: `--probe-cfg` and `tests\settings_doc_check.py`. Prompts: `romfs_prompts_test.py`, overlay generated
|
||||
for a game check.
|
||||
- [ ] Frame path: whole heavy-scene runs off/on, two each at least, by game time, quiet machine, warm cache prepared
|
||||
in that build dir. No fps loss, zero new slow frames.
|
||||
- [ ] Rendering: shots or a frame dump in a scene where the change acts; no black or flat frames; no new validation
|
||||
errors.
|
||||
- [ ] Perf PR: gain ceiling computed for weak hardware.
|
||||
|
||||
## Decision
|
||||
|
||||
- [ ] Taken, partly taken or rejected, with the reason written down and posted to the PR.
|
||||
- [ ] What missed the project's scheme brought to it while merging.
|
||||
- [ ] Bugs found outside the PR reported, not fixed on the spot.
|
||||
- [ ] Merged into `dev` from `task/<tag>`. `main` only with the owner's yes.
|
||||
- [ ] `python tools/check_content.py --staged` before the commit.
|
||||
- [ ] Commit message: a plain English sentence, no `feat:`/`fix:`.
|
||||
@@ -0,0 +1,32 @@
|
||||
# PR review kit
|
||||
|
||||
Rules and background for a tester or reviewer who takes community PRs into `dev`. One goal: no PR breaks the
|
||||
game's behaviour or costs frames on weak hardware.
|
||||
|
||||
## The short version
|
||||
|
||||
1. A PR description and "works for me" prove nothing. Read the diff yourself and check it against `refs/`, the
|
||||
Vulkan spec and upstream issues.
|
||||
2. Almost every change needs a test: a repro before and after, a probe, a differential test, or whole runs with the
|
||||
switch off and on.
|
||||
3. The developer's machine is fast; players run weak machines. "Neutral here" says nothing about them, in either
|
||||
direction.
|
||||
4. A player without the problem sees no change: the new path sits behind a switch and the old path stays as it was.
|
||||
5. Nothing goes into `main` without the project owner's explicit yes. Accepted work lives in `dev` first.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Covers |
|
||||
|---|---|
|
||||
| [01-rules.md](01-rules.md) | triage order, what a PR needs, reasons to reject, merging and commits |
|
||||
| [02-performance.md](02-performance.md) | target hardware, gain ceiling, how to measure, what the hot path must not do |
|
||||
| [03-correctness.md](03-correctness.md) | lifter, tests and probes, GPU portability, Maxwell behaviour, timers, threads, game content |
|
||||
| [04-knowledge.md](04-knowledge.md) | invariants of recent changes, fixed bug classes, open risks, past PR decisions, our mistakes |
|
||||
| [05-checklist.md](05-checklist.md) | the per-PR checklist |
|
||||
|
||||
The public docs this kit builds on: [docs/architecture.md](../../docs/architecture.md),
|
||||
[docs/building.md](../../docs/building.md) ("Checks"), [docs/maxwell.md](../../docs/maxwell.md),
|
||||
[docs/settings.md](../../docs/settings.md), [docs/tester-guide.md](../../docs/tester-guide.md), `AGENTS.md`.
|
||||
Working with a coding agent: give it this folder and `AGENTS.md` before the first review.
|
||||
|
||||
State as of 2026-11-06. The code and `docs/` win over this text where they differ.
|
||||
Reference in new issue
Block a user