WIP: fix(perf): perf samples follow the camera, land in the relay's own cells, and skip cutscenes and the title #1502

Draft
mooki wants to merge 1 commit from mooki/Longshot:fix/perf-pose-bins-1383 into main
Member

Type: fix · Risk: low · Tested on: Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), windowless in the game; game-free checks; the relay's rules by a Python port of its public source · Needs: Windows, any GPU; the real relay (not reachable from the test PC)

TL;DR

The performance statistics merged in #1383 sent every camera angle as 0, filed half the positions one relay cell off, and still sampled cutscenes. This PR takes yaw and pitch from the camera's eye and target, sends positions as the relay's own cells, and sends no sample in a cutscene, at the title or across a map change. In a ten-minute Linux run all 299 samples were in the relay's range and on its cells; 84 % matched the camera's bins, 98 % the relay's cell of the real position, and 4 fell in cutscenes (102 of 278 before). Windows and the real relay are untested.

Breakdown

  • Who it helps: whoever reads the team's performance dashboards (where in a map, and facing which way, the game stutters), and the players who ticked the option: a summary with one angle outside the relay's range is refused whole and deleted, so their data was at risk.
  • What was wrong:
    • the yaw and pitch came from two fields of camera zero's view that read 0.0 all through a game: all 1,443 samples of the review's Linux run carried yaw 0.393 and pitch 0.262, the middles of the first bins;
    • a position was sent as the middle of its 100-unit cell (50, 150, -50), which is exactly a tie of the relay's rounding (the nearest multiple of 100, halves away from zero): 49 to 51 % of each axis's values (88 % of whole positions, on some axis) were filed one cell off, and the cell around 0 never came out;
    • cutscenes were still sampled (the camera-type check keeps other camera objects out, not events), a second at the title could carry Link's last place, and a new map's name could carry the old map's pose.
  • What changes: yaw and pitch are computed from the gameplay view's eye and target, in radians inside the relay's range; a position goes as its nearest multiple of 100; angles go as the middle of the relay's bins, with pi wrapped to the first yaw bin and straight up in the top pitch bin; no pose while an event plays, while there is no map, or from a map change until Link's next update.
  • What does not change: the summary's format (the relay's version 1), the size fitting from #1383 (a summary stays under the sender's 60 KiB; this PR only adds tests of it), the tick, the sender, the cost per frame (the pose is still read at most four times a second), and no switch or menu row is added.
  • How it was checked: one ten-minute run of this build in the game on Linux (every summary judged by the relay's rules, every sample compared with the camera the bridge reports), and two new game-free tests (the host's pose code run on a made-up guest; the relay's own rules applied to 20,363 exact places and views and what was sent for them) that fail on main; 22 mutants; the whole suite; and the Windows-target syntax check of the changed fixture.
  • What is still open: Windows (nothing was run there), the real relay (its rules were applied by a Python port of its public source, Go not being installed here), the way back to the title in the real game (no route was found; only the test covers it), the 60 KiB thinning in the game (a 14-minute interval; the tests cover it), and the cost: not measured as a speed (see Risks), so the checklist's "nothing gets worse" box is left unticked.
  • Risk: low. A wrong guess would show as the first bin or a wrong cell again, or as a second without a sample; nothing in the game's own behaviour depends on the pose.

Why

dyst's #1383 (on top of #1372 by gab9281) made the opt-in performance summaries fit the sender's limit, took the pose from Link at most four times a second, and left out stale ones. Our review of #1383 found three more problems in how the position and the view are sent and sampled; a Linux run of the merged code (its head, 36de9b0ce, which is main's code in these files) confirmed them with the game's own numbers. This PR fixes them and adds the tests that would have caught them; the size fitting, the best part of #1383, is untouched.

Refs #1383. Follows our review of #1383 (review 1676).

How to reproduce

Seen on: Linux (Arch), RTX 4090, NVIDIA 615.78.08, windowless; the build of #1383's head (v3.0.0-rc.7-5-g36de9b0ce), the same code as main in these files
Settings and switches: Send performance statistics ticked (send=1 in longshot_perf.ini), RX_VK_PERF_INTERVAL=60 (a summary every minute), HOS_CONTROL on for the bridge's camera
Steps: start a save in Kokiri Forest, turn the camera with the right stick, walk, let a cutscene play; read the samples of the summaries in perf_pending/ (or perf_sent/), beside status.game.camera and status.game.pos of the control bridge (docs/control.md)
Expected: yaw follows the camera (the bridge's camera in degrees, times pi/180), pitch follows the stick, x, y and z are the relay's cell of Link's place, and a cutscene's seconds have no sample
Actual: on main every sample has yaw 0.393 and pitch 0.262 whatever the camera does; x, y and z are 50 mod 100 (an exact position of (-46.09, 118.44, 15.39) is sent as (-50, 150, 50), which the relay files under x=-100, y=200, z=100 instead of x=0, y=100, z=0: 0 of 263 and 0 of 176 aligned samples in two runs landed in the cell the relay gives the exact place); in the review's runs the cutscene seconds were sampled in four of six

What changed

The pose now follows the camera and is sent in the relay's own terms, and a second that has no honest pose has no sample. The yaw and pitch come from the gameplay view's eye and target the way oot_state_tap.c's state_camera makes the bridge's camera; positions go out as the relay's own cell; and the host stops giving a pose during an event, at the title and across a map change.

  • host/hos_main.c:
    • oot_camera_angles() (new) takes yaw and pitch from the view's eye (+96) and target (+120), three doubles each: yaw is atan2(dx, dz) (0 toward +z, pi/2 toward +x, so status.game.camera in radians), pitch is atan2(dy, hypot(dx, dz)) (positive looking up). oot_float_within() keeps the stored float no further from 0 than the double, so pi is never stored as a float above it. A view that has no direction (looking straight up or down, the eye on the target) or a value that is not a number gives no pose. The old guard of 64 on the angles is gone.
    • oot_perf_pose(): no pose while oot_event_playing() (as the flight and oot_fov.c do), then the view's type check, the angles, and Link's place; last is documented as Link's update, which holds cheats_lock.
    • hos_perf_info(): no pose while the map is empty (the title).
    • oot_inventory_refresh(): the pose is cleared where the map line changes (as it is at the title).
  • gpu/vk/perf_report.h: cell_of() sends a position as round(v / 100) * 100 (no negative zero); yaw_bin_middle() wraps a yaw of pi into the first bin as the relay's fmod does; pitch_bin_middle() puts straight up in the top bin, so every sent angle is inside the relay's range. bin_middle() is removed with its callers.
  • tests:
    • tests/test_perf_pose.py and tests/perf_pose_test.c (new) cut oot_perf_pose, hos_perf_info, oot_event_playing, oot_gameplay_view and oot_inventory_refresh out of host/hos_main.c and run them on a made-up guest: 41 checks.
    • tests/test_perf_report.cpp: the cells and bins by name (ties, negative zero, pi, straight up, a sweep of every angle), and it writes the size cases and 20,363 exact places and views with what was sent for each.
    • tests/test_perf_report.py: re-encodes every size case the way the sender does (json.dumps), sends them with the sender, and judges the pairs by the relay's rules (a short statement of the relay's cell, view bins and range, from its public source); -D_CRT_SECURE_NO_WARNINGS on the compile line lets the Windows-target syntax check pass for this fixture (it failed on main).
  • docs: docs/performance-statistics.md, the README's paragraph and the perf_info comment in gpu/vk/vk_api.h say what is sent now (they said the relay rounds, and "floor", which was wrong for positions). A comment only: MKWVK_API_VERSION is unchanged.

Unchanged: nx2/perf_report.py (its "64 KiB" comment is stale since the relay took 192 KiB; the sender's MAX_BODY stays 60 KiB as #1383 set it), the thinning, the one-second sample clock.

Measurements

Verdict: it helps, and the game shows it: in a ten-minute run of this build every one of the 299 samples is inside the relay's range and on its cells (the first version sent one yaw and one pitch value and cells on the relay's ties), the angles follow the camera (251 of 298 aligned samples share the relay's yaw and pitch bins with the camera of that second, 89 of 108 where the camera was steady; the alignment is good to about a second), the sent cell is the relay's cell of the bridge's position for 292 of 298 samples, and cutscene seconds are left out (4 of 299 samples near an event window, against 102 of 278 before). It is not clean: the 47 samples whose bins differ and the 6 whose cell differs all sit at a camera command, a map change or an event edge, where a one-second alignment cannot settle them; the way back to the title, Windows and the real relay were not exercised.

Hardware: Linux (Arch), kernel 7.2.15, RTX 4090 (NVIDIA 615.78.08), i9-13900K, 94 GB; windowless, ordinary class, other sessions on the machine (load average 8.7 at the start of the run, 45.7 at its end)
Scene: Kokiri Forest and Hyrule Field (child), a kept save that starts in Link's house; camera turned with the right stick; Saria's scene as the cutscene; two debug teleports between the two areas; a pause
Method: the performance statistics ticked, a summary every 60 s and one at the end; the control bridge polled four times a second for camera, pos, map, event and loading, and the gameplay view's eye and target read from guest memory (read-only); the samples aligned to the polls by counting the seconds Link was updated; every summary judged by a Python port of the relay's validation and binning, and sent by the real sender to a collector on this PC inside a network namespace with no route out
How to reproduce: as in "How it was tested" below

Baseline: the "Before" column is the Linux run of #1383's head (36de9b0ce) by our review, because that code is main's in these files (git diff 36de9b0ce c14641a6f touches none of gpu/vk/perf_report.*, host/oot_state_tap.c, the pose code of host/hos_main.c); main @ c14641a6f itself was not run.

Before: #1383's head @ 36de9b0ce After: this PR @ 9dd58d631
samples written 1,443 (6 runs) 299 (1 run of 550 s, 10 summaries)
distinct yaw values sent / pitch values sent 1 (0.393) / 1 (0.262) 8 (-2.749 to 2.749) / 5 (-1.309 to 0.785); none outside -pi..pi or -pi/2..pi/2
samples whose yaw and pitch bin equals the bin of the camera in that second not applicable (the bins never moved) 251 of 298 (yaw alone 260, pitch alone 286); 89 of 108 where the camera was steady for 3 s
x, y and z as multiples of 100 0 of 176 (all 50 mod 100) 299 of 299, no "-0" written
samples in the cell the relay gives the exact place 0 of 176 and 0 of 263 292 of 298 (289 of 295 where Link stood still); the relay's labels x=200,y=200,z=300: 109, x=-100,y=100,z=0: 100, x=0,y=100,z=0: 90
samples inside an event the bridge reported 102 of 278 in one run; about +100 samples over the seconds Link was free in four of six runs 4 of 299 within half a second of 18 event windows (the longest 118 s: Saria's conversation after a teleport, answered by the chain with A); no sample in the 60 s summary that lay inside it
summaries the relay port accepts all (6 of 6; 2 of 2) all 10 (1,160 to 10,326 B), at 192 KiB and at 64 KiB; the sender sent 10, refused 0
run fix1383 exit=0 wall=557.8s span=550.3s frames=30201(headless-renderer) shots=50 1280x720 fatal=0 crash=0 devlost=0 nocore=0 kernel=0 nvrm=0 dev=0:NVIDIA_GeForce_RTX_4090 load 8.73 10.44 16.31 -> 45.70 41.86 30.08 journal=complete
[hos host] longshot v3.0.0-rc.7-10-g9dd58d631 (source f4165d7a)
vk: performance statistics on (the launcher's Send performance statistics): a summary every 60 s into perf_pending
sender (nx2/perf_report.py, to a collector on 127.0.0.1 in a network namespace): {'sent': 10, 'refused': 0, 'left': 0}
collector: 5678 B -> 200 ok samples=24 maps=2 | 4388 B -> 200 ok samples=20 maps=1 | 9400 B -> 200 ok samples=47 maps=2 | 5587 B -> 200 ok samples=23 maps=2 | 1160 B -> 200 ok samples=0 maps=1 | 5736 B -> 200 ok samples=24 maps=2 | 10326 B -> 200 ok samples=52 maps=2 | 9689 B -> 200 ok samples=48 maps=2 | 10018 B -> 200 ok samples=50 maps=2 | 2962 B -> 200 ok samples=11 maps=1
yaw: min -2.749 max 2.749, 8 distinct; pitch: min -1.309 max 0.785, 5 distinct; |yaw| > pi: 0; |pitch| > pi/2: 0
299 of 299 samples have x, y and z as multiples of 100 (negative zeros written: 0)
seconds Link was updated by the polls: 477.8, 183.3 of them with an event playing; samples written: 299 (nearer the count with the event seconds dropped, 294.5, than kept, 477.8)
the bridge's camera against atan2(target.x - eye.x, target.z - eye.z) read from guest memory: 1743 polls, median difference 0.0245 degrees

Flags and settings

None.

Testing

Tested:

Environment: Arch Linux (Omarchy), kernel 7.2.15-1, RTX 4090 with NVIDIA 615.78.08, i9-13900K, 94 GB, clang 23.1.3, g++ 16.2.1, the project's pinned Python 3.12 for the suite; the tests, the mutants and the game run are of this PR's head 9dd58d631 on main c14641a6f, where the game run was made; the whole suite was also run on de69ec582, its rebased twin on current main 310e7c9df (52 commits after c14641a6f; some, such as #1299 and #1459, touch tests/test_perf_report.py's docstring and host/hos_main.c elsewhere), whose code is identical: git range-diff 9dd58d631~1..9dd58d631 310e7c9df..de69ec582 shows only the context of that test file's docstring and imports changed; 17 Nov 2026; the game windowless at 1280x720 pictures; load average 9 to 84 across the checks (the machine is shared).

How each check was made, step by step:

  1. The new tests, on this PR and on main.
    • python -I -B tests/test_perf_report.py --cxx g++: 92 checks pass. It compiles tests/test_perf_report.cpp against gpu/vk/perf_report.h (buckets, hitches, pacing, the JSON, the cells and bins by name, what a frame costs to add) and runs it with a folder: the C++ test writes there the eight size cases (16 maps with every count set and a sample a second for 840 s with names of 1, 2, 3 and 4 UTF-8 bytes a character, the widest numbers, one map for five and for 14 minutes) and pairs.tsv, 20,363 exact places and views (every multiple of 25, 20,000 random places and views, every edge of the yaw and pitch bins and the floats beside it, pi and pi/2) beside the JSON the game makes of each. Python then (a) re-encodes each size case the way the sender does (json.dumps(..., separators=(",", ":")), what nx2/perf_report.py sends), checks it is at most MAX_BODY, and has the sender itself send all eight to a stand-in relay (none refused and deleted); (b) judges each pair by the relay's rules, a short statement written from the relay's public source (totals.go: the cell is math.Round(v / 100) * 100; summary.go: |yaw| <= pi, |pitch| <= pi/2, else the whole summary is refused with a 400): the sent sample must be one the relay takes, and be filed under the same cell and view bins as the exact one (the cell compared as a number: the relay's own label of an exact place in (-50, 0) is x=-0, Go printing a negative zero).
    • python -I -B tests/test_perf_pose.py: 41 checks pass. The Python driver cuts the real functions out of host/hos_main.c by their text (tests/srccut.py, as many tests here do) into a header and compiles it with tests/perf_pose_test.c, which makes up the rest: the camera manager's pointer chain to the gameplay view, its eye and target, the event manager, Link's place, the clock, the locks (a lock taken twice or released unheld is counted) and what the save says (the map, loaded or not). Nothing is taken from a dump. It checks the yaw and pitch over a whole turn at three heights against the bridge's camera (the same arithmetic as oot_state_tap.c, which the driver also asserts is the one in the file), the relay's range for every direction (3,601 yaws at 61 pitches, straight behind from either side of the axis included), no pose for straight up or down, an eye on the target, a value that is not a number or infinite, a stray place, another kind of camera object, an event playing (the pose before it goes too), an update less than 250 ms after the last, 999 ms and 1001 ms after the last update, unticked, the map line changing, and the title (no map: no pose, even for a Link update just after the clear).
    • The same two tests against main's source (git archive of c14641a6f, the new test files copied in): test_perf_report.py fails 6 checks (one of them a consequence: the C++ test stops at its first failing check), among them "per-second position and view, as cells and bins" (-150 where the nearest 100 is -100), "the relay files each sample under the cell it files the exact place under (17,854 of 20,363 differ)" and "the relay takes every sample the game sends (4 of 20,363 are out of range: pi and pi/2 edges)"; test_perf_pose.py fails 19 of 41 (yaw and pitch that do not follow the camera, no event, title and map-change handling, straight up). The output of both is attached to the first comment.
  2. Mutants. A script copies the tree, breaks one line of the fix, and runs the named test, which must fail: 22 mutants (yaw from the wrong axis, pitch sign, the view's old fields again, pi stored above pi, straight up with a yaw, no finite check, events sampled, camera type unchecked, title pose served, map change keeping the pose, no rate limit, a two-second staleness, a stray place taken, cells as middles, cells floored, halves to even, negative zero, yaw pi out of range, pitch up out of range, sent_size counting no escapes, kMaxBody at 64 KiB, thinning taking the first N) are all killed. (On #1383's tests the sent_size mutant survived: its size test measured with the function under test.)
  3. The whole suite, through the workbench's idle-class gate with a fresh HOME: python -I -B tests/run_all.py --jobs 6 --strict: 671 passed, 37 failed, 17 skipped in 276 s. That run is of 9dd58d631. The same 37 names fail with the same messages on main @ c14641a6f on this PC (run on a clean git archive of main), so none is this PR's; main's own suite is red (for example tests/test_fsr_uniform_ownership.py cuts code that uses FpsRtWait without its header). On de69ec582, the rebased twin of this PR on main 310e7c9df (code identical, range-diff above), it gave 708 passed, 43 failed, 17 skipped in 555 s. Those 43 were then run on a clean git archive of main 310e7c9df (18 Nov): 0 passed, 43 failed, the same 43 names with the same first error line each, among them the nine that were not in the first list (test_compute_warm_apart, test_dev_packs, test_draw_stream_visibility, test_fsr_image_retirement, test_invalidate_quick, test_libc_hooks, test_log_open_failure, test_psychov35_fsr3_fg, test_switch_table: for example an unused variable under -Werror, a fixture that uses host_read_barrier or hos_log_redact_file before main has them in its header). None of the 43 is a perf check, and none passes on main. The 37 that fail on this PR's own base c14641a6f, also failing there on main with the same messages, are: 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_target_image_pool, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_walk_key. The lists are attached to the first comment.
  4. The Windows-target syntax check of the changed fixture, with llvm-mingw (20261104): tests/test_perf_report.cpp passes (-D_CRT_SECURE_NO_WARNINGS was needed and is now on its compile line); tests/test_perf_pose.py skips Windows (its locks and Interlocked calls are made up for POSIX). Syntax is not Windows execution.
  5. The game on Linux, one run of this exact build:
    • Build: native Linux, the project's builder from commit 9dd58d631 (the game logs v3.0.0-rc.7-10-g9dd58d631, source f4165d7a), compiled with clang 23.1.3 in 4 min 51 s (compile 1 min 42 s); the object store of the earlier build of #1383's head was reused (the lifted code is identical, nx2/ being unchanged between the two) so only the units whose source changed were compiled. The game run is of this build; the rebase onto dcb7b47c2 changed no line of the patch (so the run is carried, not rerun, and the game's version line names 9dd58d631). The shader caches of that build were reused too: the translator's inputs are unchanged between the two commits (git diff of the files the stamp holds is empty).
    • The save: a kept save that starts with Link in his house (copied for the run, never used in place); the opt-in is longshot_perf.ini with send=1 in the game folder, RX_VK_PERF_INTERVAL=60, read-only guest reads on for the camera probe (HOS_CONTROL_MEM=ro, never rw).
    • Driven by the workbench's pilot script (it boots the game from the save through the workbench's headless, GPU-gated run wrapper and plays the steps through the control bridge, docs/control.md): a short stand, then the chain's own connection to the bridge's socket: the right stick held and released for the camera (stick), the house door and Saria's arrival scene and her talk (the pilot's proven route: an event, status.game.event true), a 6-second pause (press PLUS), ten debug teleports between the two areas (!cheat 1000 and 1001 through the live input file; nine arrived, one was refused while a conversation held Link), with four camera turns after each; Saria's conversation that starts at the arrival point in the forest is answered with A, and finally quit, the only exit that writes the last summary. Four times a second the chain read status (frame, camera in degrees, pos, map, event, loading) and the gameplay view's eye and target (mem_read at the camera manager's first camera's view), and kept every reply.
    • The run was queued in the workbench's shared lane (one game at a time on the quiet machine) with a 12-minute hold; it waited 4 h 36 min for the lane and ran 572 s; the PC's load and pressure were read at the start and the end. No Xid or kmemsysDoCacheOp line in the kernel log over the run, and no core dump of the game (the journal has qemu-aarch64-static crashes of another job 35 s before the hold started).
    • Numbers: the summaries as the game wrote them (perf_pending/) were read by a script that (a) judges each with the relay port, (b) aligns the samples to the polls by counting the seconds Link was being updated inside each summary's own window (a sample is a second of frames with a pose and the samples have no clock; a summary's file name is its end time and its maps' seconds its length, so the count restarts at each summary; a first version counted over the whole run and was seconds off, and its 89 of 294 is not reported), (c) compares each sample's yaw and pitch bins with the bins of the cameras read from guest memory within 1.5 s of it, and where the camera was steady for three seconds (so the alignment cannot matter), (d) compares the relay's cell of each sample with the relay's cells of the bridge's positions within 1.5 s, (e) counts the samples whose aligned time falls in an event window the bridge reported, (f) lists the gaps (pause, loads). Of the 298 samples with polls around them, 47 differ in a bin from the camera within 1.5 s and 6 in the cell, all of them at a camera command, a map change or an event edge (the chain commands the camera every 5 to 10 s, so that alone is not a proof of cause); none is more than a bin or a cell off.
    • Nothing left the PC: the game never sends (the launcher does); the summaries were sent with the real sender (nx2/perf_report.py of this commit) to a collector on 127.0.0.1 in a network namespace with no route out (unshare -Urn; the script refuses to start when a route out exists). The collector is a Python port of the relay's validation and binning; its self-test is the relay's own test expectation.
    • To run it again: build, tick the option, play, and read perf_pending/; python -I nx2/perf_report.py <game folder> prints what would be sent.

Two frames of that run: 1. at a house door with the game's event flag on (samples here are left out); 2. the forest tunnel mouth after the first debug teleport.

Not tested:

  • Windows: no game run, no Windows build of host/hos_main.c (the new code uses atan2, hypot, nextafterf and fabs only, all in the C runtime), and no Windows execution of tests/test_perf_report.cpp or tests/perf_pose_test.c (only the syntax check of the first).
  • Windows in the game: a Windows player's session of a nightly (nightly-455) shows the same defect on main (945 samples, all yaw 0.393 and pitch 0.262, reported in the comment of 18 Nov by futondestroyer) and a Windows llvm-mingw fixture of the same function agrees on the direction convention; this head's camera has not been run in a Windows game (see the reply of 18 Nov).
  • The real relay: its rules were applied by a Python port of its public source at eadbca4 (Go is not installed on the test PC); its own tests and a real POST were not run.
  • The way back to the title in the real game (no route was found for the scripted pilot): the title behaviour is tested by the stub test on the real functions, not in the game.
  • The 60 KiB thinning in the game (it needs a 14-minute interval over many maps): the size cases cover it game-free.
  • AMD, Intel and other GPUs: nothing here depends on the GPU, but nothing was run on one.
  • A game run of the rebased twin de69ec582 (main 310e7c9df): none; its code is identical to the tested head's and it is kept local until it has had its own run.
  • Frame times: not measured yet (this change does not touch the frame path; the pose is read at most four times a second as before; the paired timing is planned, see Risks). The frame times of the run above are an ordinary loaded run, no speed claim.

Not testable by hand: the relay's side. Whether the real relay takes these summaries and files them under the cells and bins shown can't be run from the test PC (the relay is not reachable from it, and nothing may be sent to it from a test); a Python port of its public validation and binning, applied to every summary the game wrote and to 20,363 exact places and views, stands in for it. A tester with the real relay (the team) can read the dashboard's cells after the first summaries of a build with this change.

Must be tested:

  • Windows, any GPU: tick Send performance statistics, play five minutes with camera turns, a cutscene (the first scene with Saria) and a door, then open the files in perf_sent/ (or perf_pending/), expecting every x, y and z a multiple of 100 with 0 among them, yaw and pitch changing with the camera, none outside -pi..pi and -pi/2..pi/2, and no sample from the cutscene's seconds (by hand: a Windows player; or the Test Farm: @Beanstalk windows, the opt-in on, five minutes of play with camera turns and a cutscene).

Risks

What could break: a second without a pose has no sample, so a camera looking exactly straight up or down, an event, a pause longer than a second and the first quarter second after a door or a teleport leave a gap in the one-second samples (they never carried a place before for those seconds that was right); the position's cell is the nearest 100, so a place just beside a cell's edge is in the neighbour cell, as it is for the relay's own rounding of the exact place; a pose could pair a new map's place with the old map's name for up to half a second after a door (the map line is read twice a second; the pose is cleared where the line changes, not before it does). The wrong guesses would show as the first yaw bin again, a cell off, or a sample in a cutscene, all of which the new tests check.

Cost: none that I know of, but not measured, so the checklist's "Nothing gets worse that I know of ... measured and in Risks" box is left unticked: a speed measurement needs a quiet-machine hold I did not have. What the change adds, with the option ticked, at most four times a second: one event-manager read, six doubles loaded and an atan2/hypot pair (the first version already read the view and the place); add_frame and the frame path are untouched. The frame times of the run above (mean 54.9 fps, 1% low 12.9 fps on a PC at load 8 to 46) are an ordinary loaded run, not a measurement. With the option off nothing is read. Measured: not yet. A paired exclusive timing, main c14641a6f against this head 9dd58d631 (the PR's own base, both with the option ticked, the same save and scene, main, head, main, head in one 470 s hold of the shared worker), is planned for the night of 18 to 19 Nov in the main lane (its warm-up run is queued first). This paragraph and the box are updated with its numbers, or with the reason it was not accepted (a run that is not valid or not quiet gives no number). What it can show is small: the pose is read at most four times a second, so a difference inside the run-to-run spread is the expected result, and it is not a measurement of the opt-in's whole cost on a player's PC.

Turning it off: untick the option (the pose is not read while it is off), or revert the commit.

Compatibility: nothing changes for a player's files, saves or settings; the summary's format is the relay's version 1 as before; a build before this PR sends its angles in the first bins and its places on the relay's ties, so the relay's old data for those fields is not comparable with the new.

Overlaps

Of the 338 open pull requests, 107 change one of the files this PR touches (mostly README.md, gpu/vk/vk_api.h and host/hos_main.c, which are everyone's). The scan and the trial merges were made with main at c14641a6f; the PR head 9dd58d631 merges with main 310e7c9df without a conflict (trial merge). A trial merge (git merge-tree) of each head against this branch and against main gives the same conflicts as main for all of them except #1372 (the stack base of #1383, whose commits are in main since #1383), which also conflicts with this branch in README.md, the paragraph this PR rewrites. The pull requests that change the performance statistics' files: #1368 (the sender's send lock, issue #1265) is based on a commit before #1383 and conflicts with main already in docs/performance-statistics.md, the same file with this branch, while tests/test_perf_report.py merges cleanly; #1299 (nx2/perf_report.py and its test) has since merged into main and the rebase took it without a conflict; #206 (the first version of the statistics) conflicts with main already.

Issues

See #1383.

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: on main @ c14641a6f, where the game run was made; merges with main @ 310e7c9df without a conflict; a rebased twin is ready once it has had its own game run.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • 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.
  • 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.
  • Docs updated.

New on this forge; not opened on GitHub.

**Type:** fix · **Risk:** low · **Tested on:** Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), windowless in the game; game-free checks; the relay's rules by a Python port of its public source · **Needs:** Windows, any GPU; the real relay (not reachable from the test PC) ## TL;DR The performance statistics merged in #1383 sent every camera angle as 0, filed half the positions one relay cell off, and still sampled cutscenes. This PR takes yaw and pitch from the camera's eye and target, sends positions as the relay's own cells, and sends no sample in a cutscene, at the title or across a map change. In a ten-minute Linux run all 299 samples were in the relay's range and on its cells; 84 % matched the camera's bins, 98 % the relay's cell of the real position, and 4 fell in cutscenes (102 of 278 before). Windows and the real relay are untested. ## Breakdown - **Who it helps:** whoever reads the team's performance dashboards (where in a map, and facing which way, the game stutters), and the players who ticked the option: a summary with one angle outside the relay's range is refused whole and deleted, so their data was at risk. - **What was wrong:** - the yaw and pitch came from two fields of camera zero's view that read 0.0 all through a game: all 1,443 samples of the review's Linux run carried yaw 0.393 and pitch 0.262, the middles of the first bins; - a position was sent as the middle of its 100-unit cell (50, 150, -50), which is exactly a tie of the relay's rounding (the nearest multiple of 100, halves away from zero): 49 to 51 % of each axis's values (88 % of whole positions, on some axis) were filed one cell off, and the cell around 0 never came out; - cutscenes were still sampled (the camera-type check keeps other camera objects out, not events), a second at the title could carry Link's last place, and a new map's name could carry the old map's pose. - **What changes:** yaw and pitch are computed from the gameplay view's eye and target, in radians inside the relay's range; a position goes as its nearest multiple of 100; angles go as the middle of the relay's bins, with pi wrapped to the first yaw bin and straight up in the top pitch bin; no pose while an event plays, while there is no map, or from a map change until Link's next update. - **What does not change:** the summary's format (the relay's version 1), the size fitting from #1383 (a summary stays under the sender's 60 KiB; this PR only adds tests of it), the tick, the sender, the cost per frame (the pose is still read at most four times a second), and no switch or menu row is added. - **How it was checked:** one ten-minute run of this build in the game on Linux (every summary judged by the relay's rules, every sample compared with the camera the bridge reports), and two new game-free tests (the host's pose code run on a made-up guest; the relay's own rules applied to 20,363 exact places and views and what was sent for them) that fail on main; 22 mutants; the whole suite; and the Windows-target syntax check of the changed fixture. - **What is still open:** Windows (nothing was run there), the real relay (its rules were applied by a Python port of its public source, Go not being installed here), the way back to the title in the real game (no route was found; only the test covers it), the 60 KiB thinning in the game (a 14-minute interval; the tests cover it), and the cost: not measured as a speed (see Risks), so the checklist's "nothing gets worse" box is left unticked. - **Risk:** low. A wrong guess would show as the first bin or a wrong cell again, or as a second without a sample; nothing in the game's own behaviour depends on the pose. ## Why dyst's #1383 (on top of #1372 by gab9281) made the opt-in performance summaries fit the sender's limit, took the pose from Link at most four times a second, and left out stale ones. Our review of #1383 found three more problems in how the position and the view are sent and sampled; a Linux run of the merged code (its head, `36de9b0ce`, which is main's code in these files) confirmed them with the game's own numbers. This PR fixes them and adds the tests that would have caught them; the size fitting, the best part of #1383, is untouched. Refs #1383. Follows our review of #1383 (review 1676). ## How to reproduce **Seen on:** Linux (Arch), RTX 4090, NVIDIA 615.78.08, windowless; the build of #1383's head (`v3.0.0-rc.7-5-g36de9b0ce`), the same code as main in these files **Settings and switches:** Send performance statistics ticked (`send=1` in `longshot_perf.ini`), `RX_VK_PERF_INTERVAL=60` (a summary every minute), `HOS_CONTROL` on for the bridge's camera **Steps:** start a save in Kokiri Forest, turn the camera with the right stick, walk, let a cutscene play; read the `samples` of the summaries in `perf_pending/` (or `perf_sent/`), beside `status.game.camera` and `status.game.pos` of the control bridge (`docs/control.md`) **Expected:** yaw follows the camera (the bridge's `camera` in degrees, times pi/180), pitch follows the stick, x, y and z are the relay's cell of Link's place, and a cutscene's seconds have no sample **Actual:** on main every sample has yaw 0.393 and pitch 0.262 whatever the camera does; x, y and z are 50 mod 100 (an exact position of (-46.09, 118.44, 15.39) is sent as (-50, 150, 50), which the relay files under x=-100, y=200, z=100 instead of x=0, y=100, z=0: 0 of 263 and 0 of 176 aligned samples in two runs landed in the cell the relay gives the exact place); in the review's runs the cutscene seconds were sampled in four of six ## What changed The pose now follows the camera and is sent in the relay's own terms, and a second that has no honest pose has no sample. The yaw and pitch come from the gameplay view's eye and target the way `oot_state_tap.c`'s `state_camera` makes the bridge's camera; positions go out as the relay's own cell; and the host stops giving a pose during an event, at the title and across a map change. - `host/hos_main.c`: - `oot_camera_angles()` (new) takes yaw and pitch from the view's eye (+96) and target (+120), three doubles each: yaw is `atan2(dx, dz)` (0 toward +z, pi/2 toward +x, so `status.game.camera` in radians), pitch is `atan2(dy, hypot(dx, dz))` (positive looking up). `oot_float_within()` keeps the stored float no further from 0 than the double, so pi is never stored as a float above it. A view that has no direction (looking straight up or down, the eye on the target) or a value that is not a number gives no pose. The old guard of 64 on the angles is gone. - `oot_perf_pose()`: no pose while `oot_event_playing()` (as the flight and `oot_fov.c` do), then the view's type check, the angles, and Link's place; `last` is documented as Link's update, which holds `cheats_lock`. - `hos_perf_info()`: no pose while the map is empty (the title). - `oot_inventory_refresh()`: the pose is cleared where the map line changes (as it is at the title). - `gpu/vk/perf_report.h`: `cell_of()` sends a position as `round(v / 100) * 100` (no negative zero); `yaw_bin_middle()` wraps a yaw of pi into the first bin as the relay's `fmod` does; `pitch_bin_middle()` puts straight up in the top bin, so every sent angle is inside the relay's range. `bin_middle()` is removed with its callers. - tests: - `tests/test_perf_pose.py` and `tests/perf_pose_test.c` (new) cut `oot_perf_pose`, `hos_perf_info`, `oot_event_playing`, `oot_gameplay_view` and `oot_inventory_refresh` out of `host/hos_main.c` and run them on a made-up guest: 41 checks. - `tests/test_perf_report.cpp`: the cells and bins by name (ties, negative zero, pi, straight up, a sweep of every angle), and it writes the size cases and 20,363 exact places and views with what was sent for each. - `tests/test_perf_report.py`: re-encodes every size case the way the sender does (`json.dumps`), sends them with the sender, and judges the pairs by the relay's rules (a short statement of the relay's cell, view bins and range, from its public source); `-D_CRT_SECURE_NO_WARNINGS` on the compile line lets the Windows-target syntax check pass for this fixture (it failed on main). - docs: `docs/performance-statistics.md`, the README's paragraph and the `perf_info` comment in `gpu/vk/vk_api.h` say what is sent now (they said the relay rounds, and "floor", which was wrong for positions). A comment only: `MKWVK_API_VERSION` is unchanged. Unchanged: `nx2/perf_report.py` (its "64 KiB" comment is stale since the relay took 192 KiB; the sender's `MAX_BODY` stays 60 KiB as #1383 set it), the thinning, the one-second sample clock. ## Measurements **Verdict:** it helps, and the game shows it: in a ten-minute run of this build every one of the 299 samples is inside the relay's range and on its cells (the first version sent one yaw and one pitch value and cells on the relay's ties), the angles follow the camera (251 of 298 aligned samples share the relay's yaw and pitch bins with the camera of that second, 89 of 108 where the camera was steady; the alignment is good to about a second), the sent cell is the relay's cell of the bridge's position for 292 of 298 samples, and cutscene seconds are left out (4 of 299 samples near an event window, against 102 of 278 before). It is not clean: the 47 samples whose bins differ and the 6 whose cell differs all sit at a camera command, a map change or an event edge, where a one-second alignment cannot settle them; the way back to the title, Windows and the real relay were not exercised. Hardware: Linux (Arch), kernel 7.2.15, RTX 4090 (NVIDIA 615.78.08), i9-13900K, 94 GB; windowless, ordinary class, other sessions on the machine (load average 8.7 at the start of the run, 45.7 at its end) Scene: Kokiri Forest and Hyrule Field (child), a kept save that starts in Link's house; camera turned with the right stick; Saria's scene as the cutscene; two debug teleports between the two areas; a pause Method: the performance statistics ticked, a summary every 60 s and one at the end; the control bridge polled four times a second for `camera`, `pos`, `map`, `event` and `loading`, and the gameplay view's eye and target read from guest memory (read-only); the samples aligned to the polls by counting the seconds Link was updated; every summary judged by a Python port of the relay's validation and binning, and sent by the real sender to a collector on this PC inside a network namespace with no route out How to reproduce: as in "How it was tested" below Baseline: the "Before" column is the Linux run of #1383's head (`36de9b0ce`) by our review, because that code is main's in these files (`git diff 36de9b0ce c14641a6f` touches none of `gpu/vk/perf_report.*`, `host/oot_state_tap.c`, the pose code of `host/hos_main.c`); main @ `c14641a6f` itself was not run. | | Before: #1383's head @ 36de9b0ce | After: this PR @ 9dd58d631 | |---|---|---| | samples written | 1,443 (6 runs) | 299 (1 run of 550 s, 10 summaries) | | distinct yaw values sent / pitch values sent | 1 (0.393) / 1 (0.262) | 8 (-2.749 to 2.749) / 5 (-1.309 to 0.785); none outside -pi..pi or -pi/2..pi/2 | | samples whose yaw and pitch bin equals the bin of the camera in that second | not applicable (the bins never moved) | 251 of 298 (yaw alone 260, pitch alone 286); 89 of 108 where the camera was steady for 3 s | | x, y and z as multiples of 100 | 0 of 176 (all 50 mod 100) | 299 of 299, no "-0" written | | samples in the cell the relay gives the exact place | 0 of 176 and 0 of 263 | 292 of 298 (289 of 295 where Link stood still); the relay's labels x=200,y=200,z=300: 109, x=-100,y=100,z=0: 100, x=0,y=100,z=0: 90 | | samples inside an event the bridge reported | 102 of 278 in one run; about +100 samples over the seconds Link was free in four of six runs | 4 of 299 within half a second of 18 event windows (the longest 118 s: Saria's conversation after a teleport, answered by the chain with A); no sample in the 60 s summary that lay inside it | | summaries the relay port accepts | all (6 of 6; 2 of 2) | all 10 (1,160 to 10,326 B), at 192 KiB and at 64 KiB; the sender sent 10, refused 0 | ``` run fix1383 exit=0 wall=557.8s span=550.3s frames=30201(headless-renderer) shots=50 1280x720 fatal=0 crash=0 devlost=0 nocore=0 kernel=0 nvrm=0 dev=0:NVIDIA_GeForce_RTX_4090 load 8.73 10.44 16.31 -> 45.70 41.86 30.08 journal=complete [hos host] longshot v3.0.0-rc.7-10-g9dd58d631 (source f4165d7a) vk: performance statistics on (the launcher's Send performance statistics): a summary every 60 s into perf_pending sender (nx2/perf_report.py, to a collector on 127.0.0.1 in a network namespace): {'sent': 10, 'refused': 0, 'left': 0} collector: 5678 B -> 200 ok samples=24 maps=2 | 4388 B -> 200 ok samples=20 maps=1 | 9400 B -> 200 ok samples=47 maps=2 | 5587 B -> 200 ok samples=23 maps=2 | 1160 B -> 200 ok samples=0 maps=1 | 5736 B -> 200 ok samples=24 maps=2 | 10326 B -> 200 ok samples=52 maps=2 | 9689 B -> 200 ok samples=48 maps=2 | 10018 B -> 200 ok samples=50 maps=2 | 2962 B -> 200 ok samples=11 maps=1 yaw: min -2.749 max 2.749, 8 distinct; pitch: min -1.309 max 0.785, 5 distinct; |yaw| > pi: 0; |pitch| > pi/2: 0 299 of 299 samples have x, y and z as multiples of 100 (negative zeros written: 0) seconds Link was updated by the polls: 477.8, 183.3 of them with an event playing; samples written: 299 (nearer the count with the event seconds dropped, 294.5, than kept, 477.8) the bridge's camera against atan2(target.x - eye.x, target.z - eye.z) read from guest memory: 1743 polls, median difference 0.0245 degrees ``` ### Flags and settings None. ## Testing **Tested:** Environment: Arch Linux (Omarchy), kernel 7.2.15-1, RTX 4090 with NVIDIA 615.78.08, i9-13900K, 94 GB, clang 23.1.3, g++ 16.2.1, the project's pinned Python 3.12 for the suite; the tests, the mutants and the game run are of this PR's head `9dd58d631` on main `c14641a6f`, where the game run was made; the whole suite was also run on `de69ec582`, its rebased twin on current main `310e7c9df` (52 commits after `c14641a6f`; some, such as #1299 and #1459, touch `tests/test_perf_report.py`'s docstring and `host/hos_main.c` elsewhere), whose code is identical: `git range-diff 9dd58d631~1..9dd58d631 310e7c9df..de69ec582` shows only the context of that test file's docstring and imports changed; 17 Nov 2026; the game windowless at 1280x720 pictures; load average 9 to 84 across the checks (the machine is shared). How each check was made, step by step: 1. **The new tests, on this PR and on main.** - `python -I -B tests/test_perf_report.py --cxx g++`: 92 checks pass. It compiles `tests/test_perf_report.cpp` against `gpu/vk/perf_report.h` (buckets, hitches, pacing, the JSON, the cells and bins by name, what a frame costs to add) and runs it with a folder: the C++ test writes there the eight size cases (16 maps with every count set and a sample a second for 840 s with names of 1, 2, 3 and 4 UTF-8 bytes a character, the widest numbers, one map for five and for 14 minutes) and `pairs.tsv`, 20,363 exact places and views (every multiple of 25, 20,000 random places and views, every edge of the yaw and pitch bins and the floats beside it, pi and pi/2) beside the JSON the game makes of each. Python then (a) re-encodes each size case the way the sender does (`json.dumps(..., separators=(",", ":"))`, what `nx2/perf_report.py` sends), checks it is at most `MAX_BODY`, and has the sender itself send all eight to a stand-in relay (none refused and deleted); (b) judges each pair by the relay's rules, a short statement written from the relay's public source ([totals.go](https://git.magicbean.dev/MagicBeanDev/DataServicesAPI/src/commit/eadbca4c0bb47a9e128f4c314cf2a9c9916fec15/telemetry/perf/totals.go#L205): the cell is `math.Round(v / 100) * 100`; [summary.go](https://git.magicbean.dev/MagicBeanDev/DataServicesAPI/src/commit/eadbca4c0bb47a9e128f4c314cf2a9c9916fec15/telemetry/perf/summary.go#L471): `|yaw| <= pi`, `|pitch| <= pi/2`, else the whole summary is refused with a 400): the sent sample must be one the relay takes, and be filed under the same cell and view bins as the exact one (the cell compared as a number: the relay's own label of an exact place in (-50, 0) is `x=-0`, Go printing a negative zero). - `python -I -B tests/test_perf_pose.py`: 41 checks pass. The Python driver cuts the real functions out of `host/hos_main.c` by their text (`tests/srccut.py`, as many tests here do) into a header and compiles it with `tests/perf_pose_test.c`, which makes up the rest: the camera manager's pointer chain to the gameplay view, its eye and target, the event manager, Link's place, the clock, the locks (a lock taken twice or released unheld is counted) and what the save says (the map, loaded or not). Nothing is taken from a dump. It checks the yaw and pitch over a whole turn at three heights against the bridge's camera (the same arithmetic as `oot_state_tap.c`, which the driver also asserts is the one in the file), the relay's range for every direction (3,601 yaws at 61 pitches, straight behind from either side of the axis included), no pose for straight up or down, an eye on the target, a value that is not a number or infinite, a stray place, another kind of camera object, an event playing (the pose before it goes too), an update less than 250 ms after the last, 999 ms and 1001 ms after the last update, unticked, the map line changing, and the title (no map: no pose, even for a Link update just after the clear). - The same two tests against main's source (`git archive` of `c14641a6f`, the new test files copied in): `test_perf_report.py` fails 6 checks (one of them a consequence: the C++ test stops at its first failing check), among them "per-second position and view, as cells and bins" (-150 where the nearest 100 is -100), "the relay files each sample under the cell it files the exact place under (17,854 of 20,363 differ)" and "the relay takes every sample the game sends (4 of 20,363 are out of range: pi and pi/2 edges)"; `test_perf_pose.py` fails 19 of 41 (yaw and pitch that do not follow the camera, no event, title and map-change handling, straight up). The output of both is attached to the first comment. 2. **Mutants.** A script copies the tree, breaks one line of the fix, and runs the named test, which must fail: 22 mutants (yaw from the wrong axis, pitch sign, the view's old fields again, pi stored above pi, straight up with a yaw, no finite check, events sampled, camera type unchecked, title pose served, map change keeping the pose, no rate limit, a two-second staleness, a stray place taken, cells as middles, cells floored, halves to even, negative zero, yaw pi out of range, pitch up out of range, `sent_size` counting no escapes, `kMaxBody` at 64 KiB, thinning taking the first N) are all killed. (On #1383's tests the `sent_size` mutant survived: its size test measured with the function under test.) 3. **The whole suite**, through the workbench's idle-class gate with a fresh `HOME`: `python -I -B tests/run_all.py --jobs 6 --strict`: 671 passed, 37 failed, 17 skipped in 276 s. That run is of `9dd58d631`. The same 37 names fail with the same messages on main @ `c14641a6f` on this PC (run on a clean `git archive` of main), so none is this PR's; main's own suite is red (for example `tests/test_fsr_uniform_ownership.py` cuts code that uses `FpsRtWait` without its header). On `de69ec582`, the rebased twin of this PR on main `310e7c9df` (code identical, range-diff above), it gave 708 passed, 43 failed, 17 skipped in 555 s. Those 43 were then run on a clean `git archive` of main `310e7c9df` (18 Nov): `0 passed, 43 failed`, the same 43 names with the same first error line each, among them the nine that were not in the first list (`test_compute_warm_apart`, `test_dev_packs`, `test_draw_stream_visibility`, `test_fsr_image_retirement`, `test_invalidate_quick`, `test_libc_hooks`, `test_log_open_failure`, `test_psychov35_fsr3_fg`, `test_switch_table`: for example an unused variable under `-Werror`, a fixture that uses `host_read_barrier` or `hos_log_redact_file` before main has them in its header). None of the 43 is a perf check, and none passes on main. The 37 that fail on this PR's own base `c14641a6f`, also failing there on main with the same messages, are: `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_target_image_pool`, `test_upscaler_round_trip`, `test_upscaler_rows`, `test_vcore_escape`, `test_vk_occlusion_queries`, `test_walk_key`. The lists are attached to the first comment. 4. **The Windows-target syntax check** of the changed fixture, with llvm-mingw (20261104): `tests/test_perf_report.cpp` passes (`-D_CRT_SECURE_NO_WARNINGS` was needed and is now on its compile line); `tests/test_perf_pose.py` skips Windows (its locks and Interlocked calls are made up for POSIX). Syntax is not Windows execution. 5. **The game on Linux**, one run of this exact build: - Build: native Linux, the project's builder from commit `9dd58d631` (the game logs `v3.0.0-rc.7-10-g9dd58d631`, source `f4165d7a`), compiled with clang 23.1.3 in 4 min 51 s (compile 1 min 42 s); the object store of the earlier build of #1383's head was reused (the lifted code is identical, `nx2/` being unchanged between the two) so only the units whose source changed were compiled. The game run is of this build; the rebase onto `dcb7b47c2` changed no line of the patch (so the run is carried, not rerun, and the game's version line names `9dd58d631`). The shader caches of that build were reused too: the translator's inputs are unchanged between the two commits (`git diff` of the files the stamp holds is empty). - The save: a kept save that starts with Link in his house (copied for the run, never used in place); the opt-in is `longshot_perf.ini` with `send=1` in the game folder, `RX_VK_PERF_INTERVAL=60`, read-only guest reads on for the camera probe (`HOS_CONTROL_MEM=ro`, never `rw`). - Driven by the workbench's pilot script (it boots the game from the save through the workbench's headless, GPU-gated run wrapper and plays the steps through the control bridge, `docs/control.md`): a short stand, then the chain's own connection to the bridge's socket: the right stick held and released for the camera (`stick`), the house door and Saria's arrival scene and her talk (the pilot's proven route: an event, `status.game.event` true), a 6-second pause (`press PLUS`), ten debug teleports between the two areas (`!cheat 1000` and `1001` through the live input file; nine arrived, one was refused while a conversation held Link), with four camera turns after each; Saria's conversation that starts at the arrival point in the forest is answered with A, and finally `quit`, the only exit that writes the last summary. Four times a second the chain read `status` (frame, `camera` in degrees, `pos`, `map`, `event`, `loading`) and the gameplay view's eye and target (`mem_read` at the camera manager's first camera's view), and kept every reply. - The run was queued in the workbench's shared lane (one game at a time on the quiet machine) with a 12-minute hold; it waited 4 h 36 min for the lane and ran 572 s; the PC's load and pressure were read at the start and the end. No Xid or `kmemsysDoCacheOp` line in the kernel log over the run, and no core dump of the game (the journal has qemu-aarch64-static crashes of another job 35 s before the hold started). - Numbers: the summaries as the game wrote them (`perf_pending/`) were read by a script that (a) judges each with the relay port, (b) aligns the samples to the polls by counting the seconds Link was being updated inside each summary's own window (a sample is a second of frames with a pose and the samples have no clock; a summary's file name is its end time and its maps' seconds its length, so the count restarts at each summary; a first version counted over the whole run and was seconds off, and its 89 of 294 is not reported), (c) compares each sample's yaw and pitch bins with the bins of the cameras read from guest memory within 1.5 s of it, and where the camera was steady for three seconds (so the alignment cannot matter), (d) compares the relay's cell of each sample with the relay's cells of the bridge's positions within 1.5 s, (e) counts the samples whose aligned time falls in an event window the bridge reported, (f) lists the gaps (pause, loads). Of the 298 samples with polls around them, 47 differ in a bin from the camera within 1.5 s and 6 in the cell, all of them at a camera command, a map change or an event edge (the chain commands the camera every 5 to 10 s, so that alone is not a proof of cause); none is more than a bin or a cell off. - Nothing left the PC: the game never sends (the launcher does); the summaries were sent with the real sender (`nx2/perf_report.py` of this commit) to a collector on 127.0.0.1 in a network namespace with no route out (`unshare -Urn`; the script refuses to start when a route out exists). The collector is a Python port of the relay's validation and binning; its self-test is the relay's own test expectation. - To run it again: build, tick the option, play, and read `perf_pending/`; `python -I nx2/perf_report.py <game folder>` prints what would be sent. ![Two frames of that run: 1. at a house door with the game's event flag on (samples here are left out); 2. the forest tunnel mouth after the first debug teleport.](https://git.magicbean.dev/attachments/91814d14-f601-4bcd-9ab0-b80c8d56bc32) **Not tested:** - Windows: no game run, no Windows build of `host/hos_main.c` (the new code uses `atan2`, `hypot`, `nextafterf` and `fabs` only, all in the C runtime), and no Windows execution of `tests/test_perf_report.cpp` or `tests/perf_pose_test.c` (only the syntax check of the first). - Windows in the game: a Windows player's session of a nightly (nightly-455) shows the same defect on main (945 samples, all yaw 0.393 and pitch 0.262, reported in the comment of 18 Nov by futondestroyer) and a Windows llvm-mingw fixture of the same function agrees on the direction convention; this head's camera has not been run in a Windows game (see the reply of 18 Nov). - The real relay: its rules were applied by a Python port of its public source at `eadbca4` (Go is not installed on the test PC); its own tests and a real POST were not run. - The way back to the title in the real game (no route was found for the scripted pilot): the title behaviour is tested by the stub test on the real functions, not in the game. - The 60 KiB thinning in the game (it needs a 14-minute interval over many maps): the size cases cover it game-free. - AMD, Intel and other GPUs: nothing here depends on the GPU, but nothing was run on one. - A game run of the rebased twin `de69ec582` (main `310e7c9df`): none; its code is identical to the tested head's and it is kept local until it has had its own run. - Frame times: not measured yet (this change does not touch the frame path; the pose is read at most four times a second as before; the paired timing is planned, see Risks). The frame times of the run above are an ordinary loaded run, no speed claim. **Not testable by hand:** the relay's side. Whether the real relay takes these summaries and files them under the cells and bins shown can't be run from the test PC (the relay is not reachable from it, and nothing may be sent to it from a test); a Python port of its public validation and binning, applied to every summary the game wrote and to 20,363 exact places and views, stands in for it. A tester with the real relay (the team) can read the dashboard's cells after the first summaries of a build with this change. **Must be tested:** - Windows, any GPU: tick **Send performance statistics**, play five minutes with camera turns, a cutscene (the first scene with Saria) and a door, then open the files in `perf_sent/` (or `perf_pending/`), expecting every `x`, `y` and `z` a multiple of 100 with 0 among them, `yaw` and `pitch` changing with the camera, none outside -pi..pi and -pi/2..pi/2, and no sample from the cutscene's seconds (by hand: a Windows player; or the Test Farm: @Beanstalk windows, the opt-in on, five minutes of play with camera turns and a cutscene). ## Risks **What could break:** a second without a pose has no sample, so a camera looking exactly straight up or down, an event, a pause longer than a second and the first quarter second after a door or a teleport leave a gap in the one-second samples (they never carried a place before for those seconds that was right); the position's cell is the nearest 100, so a place just beside a cell's edge is in the neighbour cell, as it is for the relay's own rounding of the exact place; a pose could pair a new map's place with the old map's name for up to half a second after a door (the map line is read twice a second; the pose is cleared where the line changes, not before it does). The wrong guesses would show as the first yaw bin again, a cell off, or a sample in a cutscene, all of which the new tests check. **Cost:** none that I know of, but **not measured**, so the checklist's "Nothing gets worse that I know of ... measured and in Risks" box is left unticked: a speed measurement needs a quiet-machine hold I did not have. What the change adds, with the option ticked, at most four times a second: one event-manager read, six doubles loaded and an `atan2`/`hypot` pair (the first version already read the view and the place); `add_frame` and the frame path are untouched. The frame times of the run above (mean 54.9 fps, 1% low 12.9 fps on a PC at load 8 to 46) are an ordinary loaded run, not a measurement. With the option off nothing is read. Measured: not yet. A paired exclusive timing, main `c14641a6f` against this head `9dd58d631` (the PR's own base, both with the option ticked, the same save and scene, main, head, main, head in one 470 s hold of the shared worker), is planned for the night of 18 to 19 Nov in the main lane (its warm-up run is queued first). This paragraph and the box are updated with its numbers, or with the reason it was not accepted (a run that is not valid or not quiet gives no number). What it can show is small: the pose is read at most four times a second, so a difference inside the run-to-run spread is the expected result, and it is not a measurement of the opt-in's whole cost on a player's PC. **Turning it off:** untick the option (the pose is not read while it is off), or revert the commit. **Compatibility:** nothing changes for a player's files, saves or settings; the summary's format is the relay's version 1 as before; a build before this PR sends its angles in the first bins and its places on the relay's ties, so the relay's old data for those fields is not comparable with the new. ## Overlaps Of the 338 open pull requests, 107 change one of the files this PR touches (mostly `README.md`, `gpu/vk/vk_api.h` and `host/hos_main.c`, which are everyone's). The scan and the trial merges were made with main at `c14641a6f`; the PR head `9dd58d631` merges with main `310e7c9df` without a conflict (trial merge). A trial merge (`git merge-tree`) of each head against this branch and against main gives the same conflicts as main for all of them except #1372 (the stack base of #1383, whose commits are in main since #1383), which also conflicts with this branch in `README.md`, the paragraph this PR rewrites. The pull requests that change the performance statistics' files: #1368 (the sender's send lock, issue #1265) is based on a commit before #1383 and conflicts with main already in `docs/performance-statistics.md`, the same file with this branch, while `tests/test_perf_report.py` merges cleanly; #1299 (`nx2/perf_report.py` and its test) has since merged into main and the rebase took it without a conflict; #206 (the first version of the statistics) conflicts with main already. ## Issues See #1383. ## 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. - [ ] 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. - [ ] Rebased on current `main`: on main @ `c14641a6f`, where the game run was made; merges with main @ `310e7c9df` without a conflict; a rebased twin is ready once it has had its own game run. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [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] 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] Docs updated. --- New on this forge; not opened on GitHub.
fix(perf): perf samples follow the camera, land in the relay's own cells, and skip cutscenes and the title
Some checks failed
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 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
9dd58d6313
Follows #1383 (dyst), which fit the performance summaries under the sender's limit and stopped stale poses. A Linux run of
that merge showed what its tests could not: every sample's yaw and pitch were 0 (all in the first bins), every position
was a half-way tie of the relay's rounding, a cutscene was still sampled, and a title-screen second could carry a place.

- yaw and pitch (host/hos_main.c oot_camera_angles): from the gameplay view's eye and target, the way the control bridge's
  camera is made (oot_state_tap.c state_camera), in radians, yaw in [-pi, pi] and pitch in [-pi/2, pi/2], the range the
  relay takes (it refuses a whole summary for one sample outside it). The first version read +0x1a4 and +0x18c of camera
  zero's view, which read 0.0 all through a game. Straight up or down has no yaw, and no pose.
- cells (gpu/vk/perf_report.h cell_of): a place is sent as its nearest multiple of 100, which is what the relay's
  math.Round(v / 100) * 100 files an exact place under (and leaves a sent one where it is). The middles of the cells (50,
  150, -50) are its ties: half of each axis's values (49 to 51 % of 20,000 random places) land one cell off, 88 % of whole
  places on some axis. Yaw pi goes to the first yaw bin, as the relay wraps it, and the last pitch bin takes straight up,
  so a sent angle is always in the relay's range.
- no pose while an event plays (oot_event_playing, as the flight and the field of view do), while there is no map (the
  title: hos_perf_info), and from the map line's change until Link's next update.
- tests: tests/test_perf_pose.py runs the host's pose code (oot_perf_pose, hos_perf_info, the map line's refresh) cut out
  of host/hos_main.c on a made-up guest (tests/perf_pose_test.c); tests/test_perf_report.py re-encodes every size case the
  way the sender does (json.dumps), sends them with the sender, and judges 20,000 exact places and views and what was sent
  for them by the relay's rules (the sent one is in its range, and filed under the cell and bins of the exact one).
- docs: performance-statistics.md, the README and the MkwVkHost comment say what is sent now.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Member

Independent Windows evidence for the camera-angle defect this PR covers: a nightly-455-b8f3d547 gameplay session on Windows 11 / RTX 4070 / NVIDIA 621.01 contained 945 position samples, all with yaw 0.393 and pitch 0.262. The raw session artifacts remain local.

I independently traced this to oot_perf_pose reading controller float offsets from the rendered LookAtCamera. A Windows llvm-mingw fixture exercising the actual function over synthetic guest memory fails on unchanged main 310e7c9d when a view looking along +X returns yaw zero instead of pi/2. A small local repair using target minus eye passes cardinal/diagonal/tilt and invalid/opt-out cases, and rejects deliberately broken variants.

That is corroboration of the baseline defect and the direction convention, not a test or review of this PR's head. I have not built or run 9dd58d631 on Windows, exercised the real relay, or measured overhead. This PR already covers the same repair plus cell/bin and cutscene handling, so I will not open a competing camera PR. The remaining useful Windows check is this head's in-game camera rotation and elevation, with summary samples checked against the bridge and relay rules, including map/event edges.

Independent Windows evidence for the camera-angle defect this PR covers: a nightly-455-b8f3d547 gameplay session on Windows 11 / RTX 4070 / NVIDIA 621.01 contained 945 position samples, all with yaw 0.393 and pitch 0.262. The raw session artifacts remain local. I independently traced this to `oot_perf_pose` reading controller float offsets from the rendered LookAtCamera. A Windows llvm-mingw fixture exercising the actual function over synthetic guest memory fails on unchanged main `310e7c9d` when a view looking along +X returns yaw zero instead of pi/2. A small local repair using target minus eye passes cardinal/diagonal/tilt and invalid/opt-out cases, and rejects deliberately broken variants. That is corroboration of the baseline defect and the direction convention, **not a test or review of this PR's head**. I have not built or run `9dd58d631` on Windows, exercised the real relay, or measured overhead. This PR already covers the same repair plus cell/bin and cutscene handling, so I will not open a competing camera PR. The remaining useful Windows check is this head's in-game camera rotation and elevation, with summary samples checked against the bridge and relay rules, including map/event edges.
Author
Member

Thank you: a second platform's evidence for the defect is exactly what I could not get. 945 samples at yaw 0.393 and pitch 0.262 on Windows 11 / RTX 4070 matches what I saw on Linux before the fix (all 1,443 samples of six runs at the same two values), and your fixture agrees with the direction convention this PR uses: yaw 0 looking along +z, pi/2 looking along +x, the bridge's camera in radians.

Where this head stands. Linux only. One game run of 9dd58d631 on Linux (the numbers are in the description): angles follow the camera, positions are the relay's cells, no samples in cutscenes. On Windows I have only the syntax check of the changed C++ fixture with llvm-mingw. tests/test_perf_pose.py (the stub test of the real pose functions) skips Windows because its locks are made up for POSIX, so on Windows your fixture is the only thing that runs the actual function. I have not run this head in a Windows game, and nothing was sent anywhere: the game never sends, the launcher does.

What I can do.

  • Not yet: I do not have a date for a Windows run of this head; I will say here when one has happened.
  • When it can run: the head built for Windows, the option ticked (longshot_perf.ini with send=1), RX_VK_PERF_INTERVAL=60, the control bridge on; the right stick held in each direction, a cutscene, a door and a map change; the game closed from its window so the last summary is written; the summaries in perf_pending/ read offline against status.game.camera and status.game.pos of the bridge, with the relay's rules (range, cells, bins) applied by a script. The analysis is the one used for the Linux run.

What would help from you, if you can. You said the useful remaining Windows check is this head's camera rotation and elevation in the game. If you build 9dd58d631 (or take a nightly that has it once it is merged) and do the same by hand (tick the option, turn the camera in all four directions and up and down for a minute or two, a door, then read the x, y, z, yaw and pitch in perf_pending/*.json): expected are x, y and z multiples of 100, yaw between -3.14 and 3.14 and following the camera (0 looking along +z, about 1.57 along +x), pitch between -1.57 and 1.57 (below 0 looking down), no sample in the seconds of a cutscene, and a summary that your relay rules accept. Your fixture run against this head's oot_camera_angles and oot_perf_pose (not main's) would also tell whether the Windows compile of the new code behaves as the Linux one does. The stub test's own fixture (tests/perf_pose_test.c, with the functions cut out of host/hos_main.c by tests/test_perf_pose.py) compiles cleanly here for x86_64-w64-mingw32 with -Wall -Wextra -Werror (compile only: I cannot link or run it on this PC), so running it natively on Windows is possible too, and a pass there would be the Windows execution of this head's pose code that I do not have. A differing number, with the camera angle beside it, is what I would want to see; please keep the raw session local, as you did.

Thank you: a second platform's evidence for the defect is exactly what I could not get. 945 samples at yaw 0.393 and pitch 0.262 on Windows 11 / RTX 4070 matches what I saw on Linux before the fix (all 1,443 samples of six runs at the same two values), and your fixture agrees with the direction convention this PR uses: yaw 0 looking along +z, pi/2 looking along +x, the bridge's `camera` in radians. **Where this head stands.** Linux only. One game run of `9dd58d631` on Linux (the numbers are in the description): angles follow the camera, positions are the relay's cells, no samples in cutscenes. On Windows I have only the syntax check of the changed C++ fixture with llvm-mingw. `tests/test_perf_pose.py` (the stub test of the real pose functions) skips Windows because its locks are made up for POSIX, so on Windows your fixture is the only thing that runs the actual function. I have not run this head in a Windows game, and nothing was sent anywhere: the game never sends, the launcher does. **What I can do.** - Not yet: I do not have a date for a Windows run of this head; I will say here when one has happened. - When it can run: the head built for Windows, the option ticked (`longshot_perf.ini` with `send=1`), `RX_VK_PERF_INTERVAL=60`, the control bridge on; the right stick held in each direction, a cutscene, a door and a map change; the game closed from its window so the last summary is written; the summaries in `perf_pending/` read offline against `status.game.camera` and `status.game.pos` of the bridge, with the relay's rules (range, cells, bins) applied by a script. The analysis is the one used for the Linux run. **What would help from you, if you can.** You said the useful remaining Windows check is this head's camera rotation and elevation in the game. If you build `9dd58d631` (or take a nightly that has it once it is merged) and do the same by hand (tick the option, turn the camera in all four directions and up and down for a minute or two, a door, then read the `x`, `y`, `z`, `yaw` and `pitch` in `perf_pending/*.json`): expected are x, y and z multiples of 100, yaw between -3.14 and 3.14 and following the camera (0 looking along +z, about 1.57 along +x), pitch between -1.57 and 1.57 (below 0 looking down), no sample in the seconds of a cutscene, and a summary that your relay rules accept. Your fixture run against this head's `oot_camera_angles` and `oot_perf_pose` (not main's) would also tell whether the Windows compile of the new code behaves as the Linux one does. The stub test's own fixture (`tests/perf_pose_test.c`, with the functions cut out of `host/hos_main.c` by `tests/test_perf_pose.py`) compiles cleanly here for `x86_64-w64-mingw32` with `-Wall -Wextra -Werror` (compile only: I cannot link or run it on this PC), so running it natively on Windows is possible too, and a pass there would be the Windows execution of this head's pose code that I do not have. A differing number, with the camera angle beside it, is what I would want to see; please keep the raw session local, as you did.
Some checks failed
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 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
This pull request is marked as a work in progress.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'fix/perf-pose-bins-1383:mooki-fix/perf-pose-bins-1383'
git switch 'mooki-fix/perf-pose-bins-1383'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 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!1502
No description provided.