feat(vk): bug reports and the log say where Link stands (map, x y z, facing, age, time of day) #1408

Open
mooki wants to merge 2 commits from mooki/Longshot:bug-report-place into main
Member

Type: feat · Risk: low · Tested on: Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08) · Needs: Windows, any GPU

Why

A bug report names the map and nothing else, so nobody can go to the spot: "Kokiri Forest" is a whole area. The Insert menu's Bug report (Gameplay tab) and the game's log now say where the player stood, exactly, as one line a person can paste:

KokiriForest_Child (child), x -52.5 y 149.9 z 180.2, facing 90, 13:20 (made-up numbers)

It is the map as the game spells it, the age, Link's position (metres, one decimal: the control bridge's pos), his facing in degrees and the game's clock. A tester can paste the numbers into the !place X Y Z line of #1351 (after the Debug tab's Teleport to the map), so the spot of a report can be visited. The automated test player and bug hunter of #1198 get findings that name where they happened, and scenarios that can start at one exact spot. A game that crashes leaves its last place in the log, so a report built from the log has it too. Positions are not personal and nothing else is added: no name, no path, nothing of a save.

What changed

The host reads the place twice a second while the game updates Link, with the state tap's readers (works with HOS_CONTROL off, which is how players run), keeps it as text for the renderer, and writes place: <line> into the log when it is worth a line. The Bug report asks the host for it when its key is pressed and prints it as the first line of "Where in the game" (also the link's where field); the second line says where it came from.

  • host/oot_place.c, oot_place.h (new): the line's format (one decimal, facing -180..179, HH:MM, a part that cannot be read is left out with its comma, no negative zero), the log rule, the live snapshot (a lock, no torn lines), hos_place_loaded (back at the title the place is forgotten).
  • The log rule: a line when the map or the age changes (at once), else only when Link is 3 units from the last line and 5 s have passed: standing still writes nothing, running about one 85-byte line per 5 s. A load reads Link where it put him and with the facing of the map before (his entry moves him and turns him in the next second), so a line at a map or age change is followed 2 s later by one more when it would then say something else. The map: line is unchanged.
  • host/oot_state_tap.c: hos_oot_place_read (the map, age, position, facing, and the game's clock read as docs/oot/environment.md "The clock" says). host/hos_main.c: a few lines in Link's update and in the inventory refresh.
  • host/rx_backend.c, gpu/vk/vk_api.h: MkwVkHost.place, API 29 -> 30, appended after monitor_select. The host function is hos_oot_place_line: PR 1351 has a global hos_oot_place, so the two PRs build together (a combined build of this branch and 1351's commit compiled).
  • gpu/vk/vk_menu.cpp, vk_bug_report.cpp/.h: the press asks the host; "Where in the game" says: read from the game now / N s before (the game's pause menu and loading screens do not update Link) / the last place: line of this run's log / the last map: line / not known. "The run before was last at ..." names where a crashed run ended.
  • docs/images/guide/manifest.json: the Graphics illustration's reviewed source hashes advance (check_guide_screenshots.py --review-sources, the guide-screenshots workflow, asks for it because this change touches vk_api.h, vk_bug_report.h and vk_menu.cpp). The game-free menu fixture's Graphics view on main and on this branch differs in the version label's " dev" suffix only.
  • Docs: docs/development.md "Where Link is" (grammar, rule, API), README, docs/common-issues.md, the game problem form's Where field.
  • Not in the line: a room (the game has no room number to read). Not here: #983's crash window still takes map from the map: line; sending the place with it is a follow-up (its relay field belongs to the relay).

Measurements

Nothing to time: one clock read per Link update and, twice a second, a few bounded guest reads; the log grows by under 0.1 MB an hour of continuous running. What was checked is that it is right, in Testing.

Flags and settings

None. (gpu/vk/vk_menu.cpp changes only what the Bug report's key press asks the host for: no menu row, label, ini key or switch is added or changed.)

Testing

Tested: Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), i9-13900K, headless, 2026-11-17; main @ 544229a26.

  • The new tests, both ways. tests/test_oot_place.py (new: every format case and the grammar, the log rule and its walks: 13 lines in 60 s of running, 11 crawling, 1 standing 10 minutes, map and age changes at once, the arrival's second line, the title; the live read and a thread reading while another writes; the reader over bounded synthetic guest memory; the wiring) passes with gcc and clang. tests/test_bug_report.py (extended: the live place, a stale one, the log's last place, a log with only a map, the run before's place, the link within 2000 characters with 98 switches, a place after a NUL byte and past 10 MB) passes. On main @ 544229a26 the same two files fail: oot place: Link's update does not take the place under its lock, after the state tap (due -1, read -1, note -1) and bug report: bug_report_save does not ask the host for the place (MkwVkHost::place) when the report is made. The arrival's second line was red first (rule 'arrived 2 s ago, Link has moved 0.7': 0, wanted 1).

  • The whole suite, tests/run_all.py --jobs 6 --strict, fresh home, on main @ 544229a26 and on this PR @ 6dc899a58: main 664 passed, 40 failed, 17 skipped; this PR 665 passed, 40 failed, 17 skipped (the one more pass is the new test). The same 40 names fail on both (compared by name with a script; none fails only on the PR): test_bug_report_defaults, test_cpu_report, test_crt_options, test_damage_debug_menu, test_display_startup_failure, test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership, test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_linux_preflight, test_linux_pressure, test_linux_update, test_mirror_budget, test_missing_nup, test_mods_size_table, test_nonuniform_image_arrays, test_parallel_init_order, test_pending_guest_import, test_pipeline_play_cache, test_present_thread, test_profiling_mode, test_readback_timeout_source, test_replay_write_order, test_rumble_menu, test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool, test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_vk_swapchain_compat, test_walk_key.

  • The API. 29 -> 30, one callback appended after monitor_select; tests/test_audio_output_devices.py (layout offsets, table slots, version) follows it (updated, not weakened); tests/test_microphone_test_gain.py passes unchanged; tests/test_oot_place.py checks the table slot and the header.

  • Guide check. check_guide_screenshots.py --review-sources fails on this branch before the manifest change (3 files) and passes on main and after it.

  • In the game, hold 1 (before the last fix). A full build of the branch before the rebase and the arrival's second line (220ffa599, on 17394b711) ran one windowless game (RTX 4090, 333 s, 21,564 frames, fatal=0 crash=0 devlost=0 kernel=0 nvrm=0): the Insert menu's keys pressed Bug report four times while the driver teleported Kokiri Forest -> Hyrule Field -> a 6 s walk -> Kokiri Forest. All four report.txt first lines had the right map, and Link's position, facing and the game's clock agreed with the control bridge's status sample taken at the same moment and the clock read through the bridge's memory read (0.045 to 0.064 m, facing exact, clock equal); the walk's heading (-73 degrees) fits the facing (-70); the link at the end of report.txt carries the line in field:where. It found that the log's place: line at a map change had the previous map's facing and Link 0.7 m short of where he then stood: fixed by the arrival's second line, above.

  • In the game, hold 2: a report, then !place with its numbers, then the report again. A full build of this branch (03233d094, the tree of 6dc899a58 but for the guide manifest) with the one commit of PR 1351 (!place) on top, one windowless game on the RTX 4090 (378 s, 24,488 frames, fatal=0 crash=0 devlost=0 nocore=0 kernel=0 nvrm=0, no core dump), started from a copied save with HOS_CONTROL (guest memory read-only) and HOS_INPUT_LIVE. The Insert menu's keys pressed Bug report five times; between the presses the driver teleported Kokiri Forest -> Hyrule Field, walked 6 s, !placed, teleported back to Kokiri Forest, walked 6 s, !placed. Every report's place line has the right map, and its position is 0.040 to 0.064 m from the bridge's status sample taken at the same moment (inside the one decimal), its facing is exact and its clock equals the game's clock read through the bridge.

    Step Link before !place with the numbers read from Link's distance from those numbers (bridge) The report made after
    Hyrule Field, after a 6 s walk 14.4 m from report 2's spot report 2's line 0.01 m (0.29 s after the line was sent, held for 2 s) none in that map
    Kokiri Forest, after a 6 s walk 25.9 m from report 4's spot report 4's line 0.04 m (0.28 s, held for 2 s) report 5: the same line, character for character, as report 4 (0.0 m)

    Each warp has both lines in longshot_log.txt, in order, with the sent numbers: hid: live command at 284.3 s: !place X Y Z then cheats: returned to X Y Z (and the same at 336.1 s). After each of the three map changes the log has the arrival's place: line and, 2 s later, the settled one (the facing was the map before's at the arrival: 0 then 90, 90 then -70, -70 then 90). Pictures, each looked at: bug-report-place-five-reports.jpg (the five report pictures), bug-report-place-round-trip-field.jpg and bug-report-place-round-trip-kokiri.jpg (the report's picture, Link away after the walk, Link back 1.5 s after !place; in Kokiri Forest also report 5's picture), bug-report-place-menu-after-press.jpg (the Insert menu after the key: where the folder is). !place does not set the facing, so report 5's facing is the walk's.

The five report pictures of the second run: Kokiri Forest, Hyrule Field at the tunnel mouth, Hyrule Field after a walk, Kokiri Forest at the first spot again, and Kokiri Forest after a walk and !place with report 4's numbers.

Hyrule Field: where Link stood for report 2, 14 m away after the walk, and back 1.5 s after !place with report 2's numbers.

Kokiri Forest: the same round trip with report 4's numbers, and report 5's picture made afterwards.

  • Windows, compiled, not run. The Windows-target syntax check (llvm-mingw 20261104) of the changed fixtures: tests/test_bug_report.py and tests/test_oot_place.py PASS (stopped before running them); tests/test_audio_output_devices.py fails the same way on main (-Werror=deprecated-declarations on memmove and tmpfile; compiled with the deprecation warnings off, it passes). A cross-build on Linux with the project's build plan: the renderer DLL linked, 63 of 63 host sources compiled for Windows, 0 warnings under the project's flags; no game executable linked, nothing ran on Windows.

Not tested: Windows (nothing of this ran there); the two PRs merged on main (the round trip ran on the combined build, not on main); AMD and Intel; adult Link and maps other than Kokiri Forest and Hyrule Field; a place inside a dungeon (no room exists); a real crash (the crash path is tested on a log, not on a crash); a real window (the runs were windowless); hold 2's build had the tree of 03233d094, not 6dc899a58 (they differ in the guide manifest only).

Must be tested:

  • Windows, any GPU: press Bug report in play (Insert menu, Gameplay), open report.txt, expecting the first line of "Where in the game" to be the map, x y z, facing and time of day, and the second line "read from the game just now" (by hand, or a Windows request to the Test Farm: Bug report in Kokiri Forest, the first line of Where in the game).

Risks

What could break: the host table and MkwVkHost grow by one slot (API 30): host and renderer are built together, as always; whoever lands second of the PRs that bump the API renumbers (the control overlay branch also takes 30). The host adds a few guest reads twice a second in Link's update, under the lock the state tap already takes. A very chatty log can push the last place: line out of the last 200 lines the crash window shows; it takes facts from the whole log.

Turning it off: revert the commits; there is no switch (the line is small and a position is not personal).

Compatibility: nothing for saves, longshot_options.ini or caches; a new log line place:; reports gain a line.

Issues

See #1198.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main (544229a26).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named): the 40 failures are main's own and named in Testing.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost changed).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.
  • Docs updated.

New on this forge; not opened on GitHub.

**Type:** feat · **Risk:** low · **Tested on:** Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08) · **Needs:** Windows, any GPU ## Why A bug report names the map and nothing else, so nobody can go to the spot: "Kokiri Forest" is a whole area. The Insert menu's Bug report (Gameplay tab) and the game's log now say where the player stood, exactly, as one line a person can paste: `KokiriForest_Child (child), x -52.5 y 149.9 z 180.2, facing 90, 13:20` (made-up numbers) It is the map as the game spells it, the age, Link's position (metres, one decimal: the control bridge's `pos`), his facing in degrees and the game's clock. A tester can paste the numbers into the `!place X Y Z` line of https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1351 (after the Debug tab's Teleport to the map), so the spot of a report can be visited. The automated test player and bug hunter of https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1198 get findings that name where they happened, and scenarios that can start at one exact spot. A game that crashes leaves its last place in the log, so a report built from the log has it too. Positions are not personal and nothing else is added: no name, no path, nothing of a save. ## What changed The host reads the place twice a second while the game updates Link, with the state tap's readers (works with `HOS_CONTROL` off, which is how players run), keeps it as text for the renderer, and writes `place: <line>` into the log when it is worth a line. The Bug report asks the host for it when its key is pressed and prints it as the first line of "Where in the game" (also the link's `where` field); the second line says where it came from. - `host/oot_place.c`, `oot_place.h` (new): the line's format (one decimal, facing -180..179, HH:MM, a part that cannot be read is left out with its comma, no negative zero), the log rule, the live snapshot (a lock, no torn lines), `hos_place_loaded` (back at the title the place is forgotten). - The log rule: a line when the map or the age changes (at once), else only when Link is 3 units from the last line **and** 5 s have passed: standing still writes nothing, running about one 85-byte line per 5 s. A load reads Link where it put him and with the facing of the map before (his entry moves him and turns him in the next second), so a line at a map or age change is followed 2 s later by one more when it would then say something else. The `map:` line is unchanged. - `host/oot_state_tap.c`: `hos_oot_place_read` (the map, age, position, facing, and the game's clock read as `docs/oot/environment.md` "The clock" says). `host/hos_main.c`: a few lines in Link's update and in the inventory refresh. - `host/rx_backend.c`, `gpu/vk/vk_api.h`: `MkwVkHost.place`, **API 29 -> 30**, appended after `monitor_select`. The host function is `hos_oot_place_line`: PR 1351 has a global `hos_oot_place`, so the two PRs build together (a combined build of this branch and 1351's commit compiled). - `gpu/vk/vk_menu.cpp`, `vk_bug_report.cpp/.h`: the press asks the host; "Where in the game" says: read from the game now / N s before (the game's pause menu and loading screens do not update Link) / the last `place:` line of this run's log / the last `map:` line / not known. "The run before was last at ..." names where a crashed run ended. - `docs/images/guide/manifest.json`: the Graphics illustration's reviewed source hashes advance (`check_guide_screenshots.py --review-sources`, the guide-screenshots workflow, asks for it because this change touches `vk_api.h`, `vk_bug_report.h` and `vk_menu.cpp`). The game-free menu fixture's Graphics view on main and on this branch differs in the version label's " dev" suffix only. - Docs: `docs/development.md` "Where Link is" (grammar, rule, API), README, `docs/common-issues.md`, the game problem form's Where field. - Not in the line: a room (the game has no room number to read). Not here: #983's crash window still takes `map` from the `map:` line; sending the place with it is a follow-up (its relay field belongs to the relay). ## Measurements Nothing to time: one clock read per Link update and, twice a second, a few bounded guest reads; the log grows by under 0.1 MB an hour of continuous running. What was checked is that it is right, in Testing. ### Flags and settings None. (`gpu/vk/vk_menu.cpp` changes only what the Bug report's key press asks the host for: no menu row, label, ini key or switch is added or changed.) ## Testing **Tested:** Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), i9-13900K, headless, 2026-11-17; main @ 544229a26. - **The new tests, both ways.** `tests/test_oot_place.py` (new: every format case and the grammar, the log rule and its walks: 13 lines in 60 s of running, 11 crawling, 1 standing 10 minutes, map and age changes at once, the arrival's second line, the title; the live read and a thread reading while another writes; the reader over bounded synthetic guest memory; the wiring) passes with gcc and clang. `tests/test_bug_report.py` (extended: the live place, a stale one, the log's last place, a log with only a map, the run before's place, the link within 2000 characters with 98 switches, a place after a NUL byte and past 10 MB) passes. On main @ 544229a26 the same two files fail: `oot place: Link's update does not take the place under its lock, after the state tap (due -1, read -1, note -1)` and `bug report: bug_report_save does not ask the host for the place (MkwVkHost::place) when the report is made`. The arrival's second line was red first (`rule 'arrived 2 s ago, Link has moved 0.7': 0, wanted 1`). - **The whole suite**, `tests/run_all.py --jobs 6 --strict`, fresh home, on main @ 544229a26 and on this PR @ 6dc899a58: main 664 passed, 40 failed, 17 skipped; this PR 665 passed, 40 failed, 17 skipped (the one more pass is the new test). The same 40 names fail on both (compared by name with a script; none fails only on the PR): test_bug_report_defaults, test_cpu_report, test_crt_options, test_damage_debug_menu, test_display_startup_failure, test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership, test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_linux_preflight, test_linux_pressure, test_linux_update, test_mirror_budget, test_missing_nup, test_mods_size_table, test_nonuniform_image_arrays, test_parallel_init_order, test_pending_guest_import, test_pipeline_play_cache, test_present_thread, test_profiling_mode, test_readback_timeout_source, test_replay_write_order, test_rumble_menu, test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool, test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_vk_swapchain_compat, test_walk_key. - **The API.** 29 -> 30, one callback appended after `monitor_select`; `tests/test_audio_output_devices.py` (layout offsets, table slots, version) follows it (updated, not weakened); `tests/test_microphone_test_gain.py` passes unchanged; `tests/test_oot_place.py` checks the table slot and the header. - **Guide check.** `check_guide_screenshots.py --review-sources` fails on this branch before the manifest change (3 files) and passes on main and after it. - **In the game, hold 1 (before the last fix).** A full build of the branch before the rebase and the arrival's second line (220ffa599, on 17394b711) ran one windowless game (RTX 4090, 333 s, 21,564 frames, `fatal=0 crash=0 devlost=0 kernel=0 nvrm=0`): the Insert menu's keys pressed Bug report four times while the driver teleported Kokiri Forest -> Hyrule Field -> a 6 s walk -> Kokiri Forest. All four `report.txt` first lines had the right map, and Link's position, facing and the game's clock agreed with the control bridge's `status` sample taken at the same moment and the clock read through the bridge's memory read (0.045 to 0.064 m, facing exact, clock equal); the walk's heading (-73 degrees) fits the facing (-70); the link at the end of `report.txt` carries the line in `field:where`. It found that the log's `place:` line at a map change had the previous map's facing and Link 0.7 m short of where he then stood: fixed by the arrival's second line, above. - **In the game, hold 2: a report, then `!place` with its numbers, then the report again.** A full build of this branch (03233d094, the tree of 6dc899a58 but for the guide manifest) with the one commit of PR 1351 (`!place`) on top, one windowless game on the RTX 4090 (378 s, 24,488 frames, `fatal=0 crash=0 devlost=0 nocore=0 kernel=0 nvrm=0`, no core dump), started from a copied save with `HOS_CONTROL` (guest memory read-only) and `HOS_INPUT_LIVE`. The Insert menu's keys pressed Bug report five times; between the presses the driver teleported Kokiri Forest -> Hyrule Field, walked 6 s, `!place`d, teleported back to Kokiri Forest, walked 6 s, `!place`d. Every report's place line has the right map, and its position is 0.040 to 0.064 m from the bridge's `status` sample taken at the same moment (inside the one decimal), its facing is exact and its clock equals the game's clock read through the bridge. | Step | Link before | `!place` with the numbers read from | Link's distance from those numbers (bridge) | The report made after | |---|---|---|---|---| | Hyrule Field, after a 6 s walk | 14.4 m from report 2's spot | report 2's line | 0.01 m (0.29 s after the line was sent, held for 2 s) | none in that map | | Kokiri Forest, after a 6 s walk | 25.9 m from report 4's spot | report 4's line | 0.04 m (0.28 s, held for 2 s) | report 5: the same line, character for character, as report 4 (0.0 m) | Each warp has both lines in `longshot_log.txt`, in order, with the sent numbers: `hid: live command at 284.3 s: !place X Y Z` then `cheats: returned to X Y Z` (and the same at 336.1 s). After each of the three map changes the log has the arrival's `place:` line and, 2 s later, the settled one (the facing was the map before's at the arrival: 0 then 90, 90 then -70, -70 then 90). Pictures, each looked at: `bug-report-place-five-reports.jpg` (the five report pictures), `bug-report-place-round-trip-field.jpg` and `bug-report-place-round-trip-kokiri.jpg` (the report's picture, Link away after the walk, Link back 1.5 s after `!place`; in Kokiri Forest also report 5's picture), `bug-report-place-menu-after-press.jpg` (the Insert menu after the key: where the folder is). `!place` does not set the facing, so report 5's facing is the walk's. ![The five report pictures of the second run: Kokiri Forest, Hyrule Field at the tunnel mouth, Hyrule Field after a walk, Kokiri Forest at the first spot again, and Kokiri Forest after a walk and `!place` with report 4's numbers.](https://git.magicbean.dev/attachments/3db97acc-7be9-449f-896a-a0f2738bda66) ![Hyrule Field: where Link stood for report 2, 14 m away after the walk, and back 1.5 s after `!place` with report 2's numbers.](https://git.magicbean.dev/attachments/597dd3eb-9cbe-451e-a783-814566a0e7e2) ![Kokiri Forest: the same round trip with report 4's numbers, and report 5's picture made afterwards.](https://git.magicbean.dev/attachments/4de9b151-addf-4d3f-9a9f-9f74abd32e08) - **Windows, compiled, not run.** The Windows-target syntax check (llvm-mingw 20261104) of the changed fixtures: `tests/test_bug_report.py` and `tests/test_oot_place.py` PASS (stopped before running them); `tests/test_audio_output_devices.py` fails the same way on main (`-Werror=deprecated-declarations` on `memmove` and `tmpfile`; compiled with the deprecation warnings off, it passes). A cross-build on Linux with the project's build plan: the renderer DLL linked, 63 of 63 host sources compiled for Windows, 0 warnings under the project's flags; no game executable linked, nothing ran on Windows. **Not tested:** Windows (nothing of this ran there); the two PRs merged on main (the round trip ran on the combined build, not on main); AMD and Intel; adult Link and maps other than Kokiri Forest and Hyrule Field; a place inside a dungeon (no room exists); a real crash (the crash path is tested on a log, not on a crash); a real window (the runs were windowless); hold 2's build had the tree of 03233d094, not 6dc899a58 (they differ in the guide manifest only). **Must be tested:** - Windows, any GPU: press Bug report in play (Insert menu, Gameplay), open `report.txt`, expecting the first line of "Where in the game" to be the map, x y z, facing and time of day, and the second line "read from the game just now" (by hand, or a Windows request to the Test Farm: Bug report in Kokiri Forest, the first line of Where in the game). ## Risks **What could break:** the host table and `MkwVkHost` grow by one slot (API 30): host and renderer are built together, as always; whoever lands second of the PRs that bump the API renumbers (the control overlay branch also takes 30). The host adds a few guest reads twice a second in Link's update, under the lock the state tap already takes. A very chatty log can push the last `place:` line out of the last 200 lines the crash window shows; it takes facts from the whole log. **Turning it off:** revert the commits; there is no switch (the line is small and a position is not personal). **Compatibility:** nothing for saves, `longshot_options.ini` or caches; a new log line `place:`; reports gain a line. ## Issues See #1198. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main` (544229a26). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named): the 40 failures are main's own and named in Testing. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [x] Docs updated. New on this forge; not opened on GitHub.
Link's update reads where he is twice a second (the map, his age, x y z, facing, the game's
clock: the state tap's readers, host/oot_state_tap.c hos_oot_place_read, with HOS_CONTROL on
or off) and keeps it as one line (host/oot_place.c):

    KokiriForest_Child (child), x -52.5 y 149.9 z 180.2, facing 90, 13:20

The log gets "place: <line>" when the map or the age changed, else only after 5 s and 3 units
of movement: standing still writes nothing, running one line every 5 s at most. A load reads
Link where it put him and with the facing of the map before (his entry moves him a little and
turns him in the next second), so a line at the change is followed 2 s later by one more when
it would then say something else. The map: line is as it was. MkwVkHost.place (API 29 -> 30,
appended after monitor_select) gives the renderer the newest place and its age in ms, for the
Bug report.

Rooms are not included: the game has no room number to read.

tests/test_oot_place.py: the line and its grammar, the log's rule (the arrival's second line
included), the live read (and a thread reading it while another writes), the reader out of
bounded synthetic guest memory, the wiring. tests/test_audio_output_devices.py names the API
version and the host table's last slot: they read 30 and place. docs/development.md: "Where
Link is".

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
feat(vk): the Bug report's "Where in the game" says where Link stands
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 8s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 18s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 26s
PR description / Description follows the template (pull_request_target) Successful in 10s
6dc899a586
The Insert menu's Bug report asks the host for the place when its key is pressed (MkwVkHost.place)
and writes it as the first line of "Where in the game", which is also the link's where field:

    KokiriForest_Child (child), x -52.5 y 149.9 z 180.2, facing 90, 13:20

The second line says where it comes from: read from the game just now; read from the game but N s
before (Link is not updated in the game's own pause menu, a loading screen or the title); when the
host has read none (a start), the last place: line of this run's log, then its last map: line, then
"Not known". "The run before was last at ..." gives the place the run before ended at: where the
game crashed, when it did.

vk_bug_report.cpp takes the place: line out of the logs as it takes the map: line (a log over 10 MB
and a log with NUL bytes included). tests/test_bug_report.py: the live place, a stale one, the log's
last place, a log with only a map, the run before's place, the link within 2000 characters with 98
switches, and the wiring of the press.

README.md, docs/common-issues.md and the game problem form's Where field say what the report now
carries.

docs/images/guide/manifest.json: the Graphics illustration's reviewed source hashes (vk_api.h, vk_bug_report.h,
vk_menu.cpp, which this change touches) advance after a comparison, as scripts/check_guide_screenshots.py
--review-sources (the guide-screenshots workflow) asks: the game-free menu fixture's Graphics view on main and on
this branch differs in the version label's " dev" suffix only. No new rendering is claimed.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
mooki changed title from WIP: feat(vk): bug reports and the log say where Link stands (map, x y z, facing, age, time of day) to feat(vk): bug reports and the log say where Link stands (map, x y z, facing, age, time of day) 2026-11-17 13:11:59 +00:00
Collaborator

Possibly related, for context:

  • PR #1351 feat(input): "!place X Y Z" in the live input puts Link at a position in the map he is in — Companion feature: accepts report coordinates for in-game teleport
Possibly related, for context: - PR #1351 feat(input): "!place X Y Z" in the live input puts Link at a position in the map he is in — Companion feature: accepts report coordinates for in-game teleport
Owner

Brought up to the ready-for-review standard (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know).

  • Tested on my own PC: ticked: Testing's Tested: the author's own in-game runs on Linux with an RTX 4090 on a build of the branch.
  • Nothing gets worse that I know of: ticked: Measurements say nothing to time, and Risks names the per-update guest reads and the log growth.
Brought up to the [ready-for-review standard](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/CONTRIBUTING.md#ready-for-review-out-of-wip) (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know). - *Tested on my own PC*: ticked: Testing's Tested: the author's own in-game runs on Linux with an RTX 4090 on a build of the branch. - *Nothing gets worse that I know of*: ticked: Measurements say nothing to time, and Risks names the per-update guest reads and the log growth.
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 8s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 18s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 26s
PR description / Description follows the template (pull_request_target) Successful in 10s
This pull request has changes conflicting with the target branch.
  • docs/images/guide/manifest.json
  • gpu/vk/vk_api.h
  • host/rx_backend.c
  • tests/test_audio_output_devices.py
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'bug-report-place:mooki-bug-report-place'
git switch 'mooki-bug-report-place'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1408
No description provided.