mirror of
https://github.com/tangerineturtle1/NX2navi.git
synced 2026-11-18 02:39:57 -04:00
Make F8 write a bug capture and add a test run that starts from one.
F8 now always writes a folder under logs/captures: the area, Link's position and rotation, the camera of the frame on screen and the game's own, the presented frame as a PNG, frame times around the press, the machine, the settings that differ from the defaults, the end of the log, the save, and the game's flags and texts. A note on screen names the capture. The flight recorder's F8 dump goes into the capture's folder. NX2NAVI_CAPTURE_REPLAY starts a run on a capture's settings, teleports to its area, walks Link to where he stood and puts the free camera where the camera was; tools/capture_run.py prepares the profile from the capture's save, runs it and compares the two captures. docs/bug-capture.md has the files and the steps. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
@@ -223,8 +223,9 @@ keeps per-core data without locks and relies on that, so the host models it (`ru
|
||||
whose size it uses, is made whole (`gfx_shader.c` `reflect_exact`). `auto` picks by the device-local budget.
|
||||
- Occlusion queries never block the CPU; a result that is not ready counts as visible.
|
||||
- Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`NX2NAVI_DUMP`,
|
||||
`vk_dump.c`), a sampling profiler (`NX2NAVI_PROFILE`, `tools/prof_report.py`) and a flight recorder
|
||||
(`NX2NAVI_FLIGHT`). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application.
|
||||
`vk_dump.c`), a sampling profiler (`NX2NAVI_PROFILE`, `tools/prof_report.py`), a flight recorder
|
||||
(`NX2NAVI_FLIGHT`) and bug captures, which a player's F8 writes and a test run starts from (`bugcap.c`,
|
||||
[bug-capture.md](bug-capture.md)). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application.
|
||||
|
||||
Maxwell behaviour the back end has to match: [maxwell.md](maxwell.md).
|
||||
|
||||
|
||||
120
docs/bug-capture.md
Normal file
120
docs/bug-capture.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Bug captures
|
||||
|
||||
A bug capture records where and how the game was when a player saw something wrong, so that the bug can be looked for
|
||||
again at that place instead of somewhere else. The player presses **F8**; a test run then starts from what the press
|
||||
wrote. Code: `runtime/bugcap.c`, `tools/capture_run.py`. Ocarina of Time 1.1.1 (the place and the camera come from the
|
||||
debug tools, `runtime/debug_tools.c`); on other game versions a capture still has the picture, the timing, the
|
||||
settings and the save.
|
||||
|
||||
## For the player
|
||||
|
||||
When you see a bug, press **F8** while the game window is in front. About a second later a note at the top of the
|
||||
screen says *Bug capture 3 saved* with the folder's name. Tell whoever looks into the bug the number ("capture 3") and
|
||||
what you saw; nothing else is needed. Press it as often as you like: each press is its own capture, and a press while
|
||||
the one before is still being written is skipped.
|
||||
|
||||
The captures are in the game folder under `logs\captures`, one folder each, named by number and time
|
||||
(`003-20261113-141502`). *Menu > Open log folder* shows `logs`. A capture is between one and a few megabytes; delete
|
||||
old ones whenever you like. Nothing leaves your PC: a capture is files on your disk.
|
||||
|
||||
## What a capture holds
|
||||
|
||||
| File | What |
|
||||
|---|---|
|
||||
| `capture.txt` | Written last: a folder that has it is complete. `key = value` lines under `[sections]`, see below |
|
||||
| `frame.png` | The frame on screen as the window got it, the overlay included, without the capture's own note (an HDR picture converted to sRGB) |
|
||||
| `frames.tsv` | The last 600 presents before the press and the 30 after: frame, interval and replay time in ms |
|
||||
| `log-tail.txt` | The last 256 KB of the run's log |
|
||||
| `settings.ini` | Every setting that had a value (from `nx2navi.ini`, the menu or the environment) as `nx2navi.ini` lines, without the private ones (`runtime/cfg_private.h`) |
|
||||
| `NX2navi-save-<time>.zip` | The save the game would load next, as *Menu > Export save* writes it |
|
||||
| `flags.tsv`, `texts.tsv` | The game's on/off flags and its 64-character texts, by the hash of their names |
|
||||
| `flight/` | With `flight = 1`: the flight recorder's dump of the same moment (`tools/flight_view.py` reads it) |
|
||||
|
||||
`capture.txt`:
|
||||
|
||||
- `[capture]`: `number`, `name`, `time`, `time_utc`, `trigger` (`F8`, `NX2NAVI_CAPTURE_AT`, `replay`), the NX2navi and
|
||||
game versions, the presented `frame`, `run_seconds`, `menu_open`.
|
||||
- `[place]`: `area` (the game's own name, which says child or adult for the outdoor areas: `HyruleField_Adult`),
|
||||
`player_pos` in metres (`none` at the title screen and while loading), `player_rot` (Link's 3x3 rotation by rows) and
|
||||
`player_yaw`, and `nearest_start`, the area's start position nearest to him, when the list of start positions was
|
||||
read (the debug menu or a test reads it).
|
||||
- `[camera]`: `camera_pos`, `camera_dir`, `camera_yaw` and `camera_pitch` (radians; the camera looks along
|
||||
`(cos pitch sin yaw, sin pitch, cos pitch cos yaw)`, the free camera's convention) with `camera_source`: the frame on
|
||||
screen when DLSS, DLAA or FSR runs (then also `camera_fov_y_degrees`, `camera_aspect`, the near and far planes),
|
||||
else the free camera when it is on, else the game's own camera. `game_camera_pos` / `game_camera_target` and
|
||||
`event_camera_pos` / `event_camera_target` are the game's two scene cameras as its camera update chose them in the
|
||||
frames after the press, whatever was drawn.
|
||||
- `[picture]`: the window's size, the game image's size, HDR, the scaler, the present mode, the display's rate.
|
||||
- `[timing]`: over the presents before the press: the average frame rate, the median, 95th and 99th percentile and
|
||||
the longest frame time, how many frames took over 33 and 50 ms, the last 30 intervals before and the first after,
|
||||
and the performance overlay's numbers when it was on.
|
||||
- `[system]`: OS, CPU, RAM, GPU, driver.
|
||||
- `[settings that differ from the defaults]`: the settings whose value is not the default; a private one shows only
|
||||
that it is set.
|
||||
|
||||
Position, rotation, area and the camera of the frame on screen are read on the render thread at the press, so they
|
||||
belong to the frame the timing ends with; the picture is the next present.
|
||||
|
||||
## Starting a test run from a capture
|
||||
|
||||
```
|
||||
python tools/capture_run.py 3
|
||||
python tools/capture_run.py "C:\...\game\logs\captures\003-20261113-141502" --set FSR4=0 --hold 30
|
||||
```
|
||||
|
||||
The argument is a capture's folder or its number under the installed game's `logs\captures` (`--game` names another
|
||||
game folder). The script
|
||||
|
||||
1. refuses to start while a game is running (one game at a time);
|
||||
2. makes a throwaway profile: the game's own profile without its saves, with the capture's save as a waiting import,
|
||||
which the game makes the save when it starts;
|
||||
3. starts the game with `NX2NAVI_CAPTURE_REPLAY=<the capture's folder>`, in a window of the capture's size that takes
|
||||
neither the focus nor your input (`--foreground` and `--fullscreen` change that), co-op and Discord off;
|
||||
4. waits while the game presses A through the title screen and the file menu, teleports to the capture's area,
|
||||
walks Link to where he stood, puts the free camera where the camera was and takes a capture of its own;
|
||||
5. closes the game and prints both captures side by side: area, positions, the distance between them, cameras, and
|
||||
the mean difference of the two pictures.
|
||||
|
||||
The run's log and its capture are in `<capture>/replays` (`--out` names another folder). `--set KEY=VALUE` puts one
|
||||
setting on top of the capture's for this run, which is how a suspected setting is tried: run once as captured and
|
||||
once with `--set`. `--hold <seconds>` keeps the game open after its capture; `--no-camera` leaves the camera to the
|
||||
game, for a bug that is about the camera itself. Any other test setting can ride along with `--set` (`DUMP`, `SHOT_DIR`
|
||||
and `SHOT_EVERY`, `DBG_TEST`, `TRACE`).
|
||||
|
||||
What the game does in such a run (`NX2NAVI_CAPTURE_REPLAY`, environment only):
|
||||
|
||||
- The capture's `settings.ini` stands in for `nx2navi.ini`, which is neither read nor written; the environment still
|
||||
wins over it. The log's first lines say so and list the settings.
|
||||
- Until Link appears the pad presses A (four reads in every hundred).
|
||||
- Three seconds later the game changes area as its own doors do (`dbg_warp`), to the start position of the capture's
|
||||
area that is nearest to the captured place; when the save already starts within 60 m of it, there is no teleport.
|
||||
A refused teleport (an event still running after the load) is asked again, up to six times.
|
||||
- Link runs to the captured `x z` (`dbg_route_to`), walking the last three metres, steered by the game's own camera, and counts as there within half a
|
||||
metre. He is walked, not put: his position cannot be written (`debug_tools.c`). When something is in the way he
|
||||
sidesteps, and after ten tries the walk is given up where he is.
|
||||
- The free camera is turned on standing (the pad still plays the game) and put at `camera_pos`, `camera_yaw`,
|
||||
`camera_pitch`. `NX2NAVI_CAPTURE_REPLAY_CAMERA=0` leaves the game's camera.
|
||||
- Three seconds later the log says `capture: replay of <name> ready: ...` with how far Link is from the captured
|
||||
place, and the run takes its own capture (`trigger = replay`), whose `capture.txt` adds `replay_of`,
|
||||
`replay_player_off_metres`, `replay_walk` and `replay_camera`.
|
||||
|
||||
What a replay does not bring back: the time of day, enemies and other actors, Link's pose and what he holds, an event
|
||||
or cutscene that was running, and progress made since the last save (the save is the one on disk at the press; the
|
||||
flags that differed are in `flags.tsv`). A capture taken at the title screen or while loading has no area: its replay
|
||||
applies the settings and stops.
|
||||
|
||||
Without the script: set `NX2NAVI_CAPTURE_REPLAY` to the folder and start the game with `--profile <a copy of a
|
||||
profile>`; `NX2NAVI_CAPTURE_DIR` says where the run's own capture goes (default `<capture>/replays`).
|
||||
|
||||
## Test settings
|
||||
|
||||
Environment or `nx2navi.ini`, for runs without a keyboard:
|
||||
|
||||
- `NX2NAVI_CAPTURE_AT=<frame>[,<frame>...]`: a capture at each of those presented frames (up to 16).
|
||||
- `NX2NAVI_CAPTURE_DIR=<folder>`: the folder captures go to, in place of `logs/captures`.
|
||||
|
||||
## The flight recorder
|
||||
|
||||
`flight = 1` keeps a ring of the last frames with a small picture each (`runtime/flight.c`). Its dump on F8 now
|
||||
belongs to the capture: it goes to the capture's `flight` folder. Its other dumps (a frame over `flight_spike_ms`,
|
||||
`NX2NAVI_FLIGHT_AT`, `NX2NAVI_FLIGHT_EVERY`) go to the `flight` folder beside the game folder as before.
|
||||
@@ -89,6 +89,7 @@ The game's *Swap Jump Controls* option trades B and X (jump on B, put away on X)
|
||||
| Key | Gamepad | Action |
|
||||
|---|---|---|
|
||||
| F1 or Esc | Minus and Plus together | open or close the settings menu; the game gets no input while it is open |
|
||||
| F8 | | bug capture: saves where you are, the camera, the picture, the settings, the log's end and your save into `logs\captures`, and a note on screen names it ([bug-capture.md](bug-capture.md)) |
|
||||
| F10 | L3 + R3 (both stick clicks) | performance overlay: off, frame rate, full panel |
|
||||
| F11 | | borderless fullscreen on or off, saved to `nx2navi.ini`; not with Ctrl, Shift or Alt held, which overlays and capture tools use |
|
||||
|
||||
@@ -102,7 +103,7 @@ The sound plays on the system default device, and follows it when the Windows de
|
||||
|
||||
## Remapping
|
||||
|
||||
The *Controls* tab of the settings menu lists, under the button layout, every Switch button and the eight stick directions the keys drive (movement and camera), each with two key cells and a controller cell. Each row's description says what the button does in the game. Select a cell, press A or Enter, then press the new key, mouse button or controller button; Esc or five seconds without a press cancel, and a controller button cancels a key cell. Delete, Backspace or X clears the selected cell. A key another action has moves to the new one (the description names the action it left); a controller button swaps with the one it replaces. A remapped controller button is physical: from then on the face buttons (A B X Y) stay where they are in both layouts, until the buttons are put back as the layout in use has them or *Reset all buttons* is chosen. F1, F8, F10, F11 and Esc cannot be bound (the menu, the flight recorder and the window keep them). Punctuation keys are named by their place on a US keyboard; the menu shows the character the keyboard layout in use puts there.
|
||||
The *Controls* tab of the settings menu lists, under the button layout, every Switch button and the eight stick directions the keys drive (movement and camera), each with two key cells and a controller cell. Each row's description says what the button does in the game. Select a cell, press A or Enter, then press the new key, mouse button or controller button; Esc or five seconds without a press cancel, and a controller button cancels a key cell. Delete, Backspace or X clears the selected cell. A key another action has moves to the new one (the description names the action it left); a controller button swaps with the one it replaces. A remapped controller button is physical: from then on the face buttons (A B X Y) stay where they are in both layouts, until the buttons are put back as the layout in use has them or *Reset all buttons* is chosen. F1, F8, F10, F11 and Esc cannot be bound (the menu, the bug capture and the window keep them). Punctuation keys are named by their place on a US keyboard; the menu shows the character the keyboard layout in use puts there.
|
||||
|
||||
The tab writes `nx2navi.ini` lines, one per Switch button or stick direction: `bind_<button> = <entry>, <entry>, ...`. The button is `A B X Y L R ZL ZR PLUS MINUS LEFT UP RIGHT DOWN LCLICK RCLICK`, or a stick direction `LSTICK_LEFT LSTICK_UP LSTICK_RIGHT LSTICK_DOWN` (movement, W A S D by default) and `RSTICK_...` (camera, the arrow keys). An entry is `pad:<name>` or `key:<name>`:
|
||||
|
||||
|
||||
@@ -34,6 +34,13 @@
|
||||
yet: the other players as a Link model, shared enemies, and invites that start the game for a friend who has it
|
||||
closed. Everyone needs the same NX2navi version. `docs/coop.md` has the details and how to go back to a save.
|
||||
|
||||
- **F8 saves a bug capture.** When you see something wrong, press F8: the game writes where Link stands, the area,
|
||||
the camera, the picture on screen, your settings, the frame times around the press, the end of the log and your
|
||||
save into one folder under `logs\captures`, and a note on screen gives the capture its number. Telling us "capture
|
||||
3" is then enough: a test run starts at that place with that camera and those settings
|
||||
(`python tools/capture_run.py 3`, `docs/bug-capture.md`) instead of somewhere else on another save. Until now F8
|
||||
did something only with the flight recorder on (`flight = 1`); its F8 dump now goes into the capture's folder.
|
||||
|
||||
## Changed
|
||||
|
||||
- **The draw replay on several CPU cores is off by default again** (`replay_workers = 0`). With three workers on by
|
||||
|
||||
Reference in New Issue
Block a user