Some PR review ruleset

This commit is contained in:
Valiantsin Dzerakh committed 2026-11-07 20:22:50 +03:00
1 parent 214ba53a2a
commit ce19a35bce
6 files changed
+458

No files matched your search

+91
View File
@@ -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.
+97
View File
@@ -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.
+92
View File
@@ -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.
+97
View File
@@ -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.
+49
View File
@@ -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:`.
+32
View File
@@ -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.