fix(dev): a Tracy build captures at full rate again (fibres off unless asked for), and the game-code zones give a valid capture #1546

Merged
HumanBean merged 1 commit from HumanBean/Longshot:fix/tracy-game-zones into main 2026-11-18 03:51:15 +00:00
Owner

Type: fix · Risk: low · Tested on: Linux, RTX 3090 (NVIDIA 620.70) · Needs: none beyond #1543's (Windows, a build with the option on)

TL;DR

The Tracy profiler build that came in with #1543 captured at a fraction of the game's frame rate (10 to 19 fps in a scene that runs at 65), and its zones in the game's own code stopped a capture within milliseconds. This PR fixes both: the same scene now captures at 36 fps with every zone on, and a 20 s capture with the game-code zones is valid (723 frames, 11.0 million zones). Only builds made with LONGSHOT_TRACY=1 change; a player's build compiles none of it.

Breakdown

  • Who it helps: developers taking a Tracy capture; no player's build has any of this.
  • What was wrong: the build told Tracy about the game's fibers, which sends every zone through one locked queue; and the lifted code held Tracy's zone context in the wrong size, so each of its zones lost its end.
  • What changes: fibers are told to Tracy only in a build that asks (LONGSHOT_TRACY_FIBERS=1); the lifted code carries its zone as 16 bytes of the host's own; the game-code zones are on by default in a Tracy build again.
  • What does not change: every build without LONGSHOT_TRACY=1, apart from one row's text in the switch table.
  • How it was checked: headless captures of the same scene before and after, read back with a small summary tool; the game-free checks.
  • What is still open: the samples of the lifted code are not named yet (a fix is being checked, not in this PR); Windows, AMD and Intel, and the viewer GUI as in #1543.
  • Risk: low: Tracy builds only.

Why

#1543 was merged with two faults that only a capture shows. First, its last commits added TRACY_FIBERS while a failing capture was being chased; fibers turned out to have nothing to do with it, and the define costs most of the frame rate while a capture is taken. Second, the zones in the game's own code (HOS_TRACY_GAME=1, off by default there because they did not work) stopped a capture with "Invalid order of zone begin and end events". This is a regression fix for that PR; no issue is open for it.

How to reproduce

Seen on: Linux, RTX 3090, NVIDIA 620.70
Settings and switches: a build of main @ ef6038ab made with LONGSHOT_TRACY=1; for the second fault also HOS_TRACY_GAME=1
Steps: start the game, go into play (Kokiri Forest), run tracy-capture -a 127.0.0.1 -o run.tracy for 20 s
Expected: the game keeps most of its frame rate while the capture is taken; the capture runs until it is stopped
Actual: 10 to 19 fps while capturing against 65 before; with HOS_TRACY_GAME=1 the capture ends after a few milliseconds ("Invalid order of zone begin and end events"), or tracy-capture crashes while saving

What changed

Two fixes in the Tracy build and the defaults that follow from them.

  • build (nx2/build.py): TRACY_FIBERS is defined only with LONGSHOT_TRACY_FIBERS=1; host/hos_tracy.h's HT_FIBER_ENTER / HT_FIBER_LEAVE are empty without it. The fiber switch in host/hos_thread.c still logs the first five switches that happen with a game zone open, which is when the option would be needed; none was seen.
  • the lifted code's zones (host/hos_tracy_game.c, nx2/tracy_funcs.py): Tracy's zone context is 16 bytes with TRACY_ON_DEMAND and 8 without. The header the job loops' chunk is compiled with now declares the zone as HtCallZone, 16 bytes of the host's own, and the host copies Tracy's context in and out of it (hos_tracy_call_begin / hos_tracy_call_end, with a _Static_assert on the size); the chunk includes nothing of Tracy.
  • defaults: HOS_TRACY_GAME is on again in a Tracy build (=0 none, funcs or calls one kind); the row in gpu/vk/switches.def says so.
  • docs: docs/development/tracy.md (fibers as a sub-option and why, the capture's cost, the game-code zones as working, the samples' names as not yet).
  • tests: tests/test_tracy_funcs.py follows the header's new zone type.

Measurements

Verdict: it helps: the same headless scene captures at 36 fps instead of 10 to 19, with more zones recorded.

Hardware: Linux, RTX 3090, NVIDIA 620.70, Ryzen 9 7900X.
Scene: Kokiri Forest, headless at 2048x1152, the camera turning; frame rate cap 240; about 65 fps before a capture starts.
Method: one session each; tracy-capture for 20 s on a port of its own; frames, zones and file size as tracy-capture reports them, the zone counts from the capture's statistics. Other jobs ran on the PC beside these, so the frame rates are rough: single runs, not medians.
How to reproduce: a pack built with LONGSHOT_TRACY=1, the game started headless into play, timeout -s INT 20 tracy-capture -a 127.0.0.1 -p <port> -o run.tracy -f.

while capturing, per-draw zones on, Tracy's sampler on Before: main @ ef6038ab's settings (fibers told to Tracy) After: this PR (not told)
game-code zones off 382 frames in 20 s (19 fps), 4.86 million zones
the listed functions' zones on 320 frames in 20 s (16 fps), 4.12 million zones
the listed functions' and the calls' zones on 203 frames in 20 s (10 fps), 3.07 million zones (with the context fix; without it the capture ends at once) 723 frames in 19.9 s (36 fps), 11.01 million zones, 82.7 MB file

The clean capture with the game-code zones (After, last row): 1,469,461 game call zones (73,800 a second, about 2,000 a frame), the 11 listed functions with counts that fit a frame (the frame's body, the actor batch and the frame wait 719 to 721 times in 723 frames; the two job loops 12,960 and 18,488 times), no zone left open, no failure, and the file reads back.

Flags and settings

One new build sub-option; one switch's default changes. Both exist only for builds made with LONGSHOT_TRACY=1.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
LONGSHOT_TRACY_FIBERS=1 build sub-option always on in a Tracy build off tells Tracy about the game's fibers; every zone then goes through one locked queue costs most of the frame rate while capturing; no capture needed it off
HOS_TRACY_GAME switch off (=1 on, broken) on (=0 off; funcs, calls) records the lifted game code's zones works on Linux on

Testing

Tested: Linux, RTX 3090, NVIDIA 620.70, Ryzen 9 7900X: the headless captures above, in the game, in Kokiri Forest; the After capture read back with a summary of its threads, zones and open zones. Game-free checks: tests/run_all.py --changed through the PC's queue (result in the first comment); tests/test_tracy_funcs.py passes.

Not tested: a played (not headless) session on this PR's build; a capture longer than 20 s with the game-code zones; the names of the lifted code's samples (they show as [unknown] + address: not fixed here); the viewer GUI; AMD and Intel GPUs.

Must be tested:

  • Windows, any GPU: as in #1543, a build with LONGSHOT_TRACY=1 (never compiled there); the game-code zones are Linux's (ELF objects) and are left out on Windows by nx2/build.py (Test Farm: @Beanstalk windows, a build with LONGSHOT_TRACY=1 and a start of the game).

Risks

What could break: nothing in a build without the option. In a Tracy build: a zone open across a fiber's move to another thread would stop a capture ("Invalid order of zone begin and end events"); the log then has tracy: a fiber switch ... with N game call zones open, and LONGSHOT_TRACY_FIBERS=1 is the build for it.

Turning it off: HOS_TRACY_GAME=0 for the game-code zones; revert the commit for the rest.

Compatibility: Nothing changes for a player: the switch table's row for HOS_TRACY_GAME has a new text, nothing else of a build without the option is touched.

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. (a verdict from single runs beside other jobs: interleaved runs and medians still to do)
  • 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.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). (only --changed run; see the first comment)
  • 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.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (single runs)
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • 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. (Windows not built, as in #1543's Must be tested)
  • Docs updated.

🤖 Generated with Claude Code

**Type:** fix · **Risk:** low · **Tested on:** Linux, RTX 3090 (NVIDIA 620.70) · **Needs:** none beyond [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543)'s (Windows, a build with the option on) ## TL;DR The Tracy profiler build that came in with [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543) captured at a fraction of the game's frame rate (10 to 19 fps in a scene that runs at 65), and its zones in the game's own code stopped a capture within milliseconds. This PR fixes both: the same scene now captures at 36 fps with every zone on, and a 20 s capture with the game-code zones is valid (723 frames, 11.0 million zones). Only builds made with `LONGSHOT_TRACY=1` change; a player's build compiles none of it. ## Breakdown - **Who it helps:** developers taking a Tracy capture; no player's build has any of this. - **What was wrong:** the build told Tracy about the game's fibers, which sends every zone through one locked queue; and the lifted code held Tracy's zone context in the wrong size, so each of its zones lost its end. - **What changes:** fibers are told to Tracy only in a build that asks (`LONGSHOT_TRACY_FIBERS=1`); the lifted code carries its zone as 16 bytes of the host's own; the game-code zones are on by default in a Tracy build again. - **What does not change:** every build without `LONGSHOT_TRACY=1`, apart from one row's text in the switch table. - **How it was checked:** headless captures of the same scene before and after, read back with a small summary tool; the game-free checks. - **What is still open:** the samples of the lifted code are not named yet (a fix is being checked, not in this PR); Windows, AMD and Intel, and the viewer GUI as in [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543). - **Risk:** low: Tracy builds only. ## Why [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543) was merged with two faults that only a capture shows. First, its last commits added `TRACY_FIBERS` while a failing capture was being chased; fibers turned out to have nothing to do with it, and the define costs most of the frame rate while a capture is taken. Second, the zones in the game's own code (`HOS_TRACY_GAME=1`, off by default there because they did not work) stopped a capture with "Invalid order of zone begin and end events". This is a regression fix for that PR; no issue is open for it. ## How to reproduce **Seen on:** Linux, RTX 3090, NVIDIA 620.70 **Settings and switches:** a build of `main` @ ef6038ab made with `LONGSHOT_TRACY=1`; for the second fault also `HOS_TRACY_GAME=1` **Steps:** start the game, go into play (Kokiri Forest), run `tracy-capture -a 127.0.0.1 -o run.tracy` for 20 s **Expected:** the game keeps most of its frame rate while the capture is taken; the capture runs until it is stopped **Actual:** 10 to 19 fps while capturing against 65 before; with `HOS_TRACY_GAME=1` the capture ends after a few milliseconds ("Invalid order of zone begin and end events"), or `tracy-capture` crashes while saving ## What changed Two fixes in the Tracy build and the defaults that follow from them. - build (`nx2/build.py`): `TRACY_FIBERS` is defined only with `LONGSHOT_TRACY_FIBERS=1`; `host/hos_tracy.h`'s `HT_FIBER_ENTER` / `HT_FIBER_LEAVE` are empty without it. The fiber switch in `host/hos_thread.c` still logs the first five switches that happen with a game zone open, which is when the option would be needed; none was seen. - the lifted code's zones (`host/hos_tracy_game.c`, `nx2/tracy_funcs.py`): Tracy's zone context is 16 bytes with `TRACY_ON_DEMAND` and 8 without. The header the job loops' chunk is compiled with now declares the zone as `HtCallZone`, 16 bytes of the host's own, and the host copies Tracy's context in and out of it (`hos_tracy_call_begin` / `hos_tracy_call_end`, with a `_Static_assert` on the size); the chunk includes nothing of Tracy. - defaults: `HOS_TRACY_GAME` is on again in a Tracy build (`=0` none, `funcs` or `calls` one kind); the row in `gpu/vk/switches.def` says so. - docs: `docs/development/tracy.md` (fibers as a sub-option and why, the capture's cost, the game-code zones as working, the samples' names as not yet). - tests: `tests/test_tracy_funcs.py` follows the header's new zone type. ## Measurements **Verdict:** it helps: the same headless scene captures at 36 fps instead of 10 to 19, with more zones recorded. Hardware: Linux, RTX 3090, NVIDIA 620.70, Ryzen 9 7900X. Scene: Kokiri Forest, headless at 2048x1152, the camera turning; frame rate cap 240; about 65 fps before a capture starts. Method: one session each; `tracy-capture` for 20 s on a port of its own; frames, zones and file size as `tracy-capture` reports them, the zone counts from the capture's statistics. Other jobs ran on the PC beside these, so the frame rates are rough: single runs, not medians. How to reproduce: a pack built with `LONGSHOT_TRACY=1`, the game started headless into play, `timeout -s INT 20 tracy-capture -a 127.0.0.1 -p <port> -o run.tracy -f`. | while capturing, per-draw zones on, Tracy's sampler on | Before: main @ ef6038ab's settings (fibers told to Tracy) | After: this PR (not told) | |---|---|---| | game-code zones off | 382 frames in 20 s (19 fps), 4.86 million zones | | | the listed functions' zones on | 320 frames in 20 s (16 fps), 4.12 million zones | | | the listed functions' and the calls' zones on | 203 frames in 20 s (10 fps), 3.07 million zones (with the context fix; without it the capture ends at once) | 723 frames in 19.9 s (36 fps), 11.01 million zones, 82.7 MB file | The clean capture with the game-code zones (After, last row): 1,469,461 `game call` zones (73,800 a second, about 2,000 a frame), the 11 listed functions with counts that fit a frame (the frame's body, the actor batch and the frame wait 719 to 721 times in 723 frames; the two job loops 12,960 and 18,488 times), no zone left open, no failure, and the file reads back. ### Flags and settings One new build sub-option; one switch's default changes. Both exist only for builds made with `LONGSHOT_TRACY=1`. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `LONGSHOT_TRACY_FIBERS=1` | build sub-option | always on in a Tracy build | off | tells Tracy about the game's fibers; every zone then goes through one locked queue | costs most of the frame rate while capturing; no capture needed it | off | | `HOS_TRACY_GAME` | switch | off (`=1` on, broken) | on (`=0` off; `funcs`, `calls`) | records the lifted game code's zones | works on Linux | on | ## Testing **Tested:** Linux, RTX 3090, NVIDIA 620.70, Ryzen 9 7900X: the headless captures above, in the game, in Kokiri Forest; the After capture read back with a summary of its threads, zones and open zones. Game-free checks: `tests/run_all.py --changed` through the PC's queue (result in the first comment); `tests/test_tracy_funcs.py` passes. **Not tested:** a played (not headless) session on this PR's build; a capture longer than 20 s with the game-code zones; the names of the lifted code's samples (they show as `[unknown] + address`: not fixed here); the viewer GUI; AMD and Intel GPUs. **Must be tested:** - Windows, any GPU: as in [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543), a build with `LONGSHOT_TRACY=1` (never compiled there); the game-code zones are Linux's (ELF objects) and are left out on Windows by `nx2/build.py` (Test Farm: @Beanstalk windows, a build with LONGSHOT_TRACY=1 and a start of the game). ## Risks **What could break:** nothing in a build without the option. In a Tracy build: a zone open across a fiber's move to another thread would stop a capture ("Invalid order of zone begin and end events"); the log then has `tracy: a fiber switch ... with N game call zones open`, and `LONGSHOT_TRACY_FIBERS=1` is the build for it. **Turning it off:** `HOS_TRACY_GAME=0` for the game-code zones; revert the commit for the rest. **Compatibility:** Nothing changes for a player: the switch table's row for `HOS_TRACY_GAME` has a new text, nothing else of a build without the option is touched. ## 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. - [ ] Measurements has a verdict, or one line saying why there is nothing to measure. (a verdict from single runs beside other jobs: interleaved runs and medians still to do) - [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`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (only `--changed` run; see the first comment) - [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. - [ ] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (single runs) - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] 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. (Windows not built, as in [#1543](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1543)'s Must be tested) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
fix(dev): a Tracy build captures at full rate again (fibres off unless asked for), and the game-code zones give a valid capture
Some checks failed
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
CI / Python source checks (ubuntu-24.04, part 1/2) (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 13s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 24s
Third-party parts / As their notes say (pull_request) Successful in 27s
PR description / Description follows the template (pull_request_target) Failing after 3s
d379fbafd7
TRACY_FIBERS sent every zone through one locked queue: a headless capture ran at 10 to 19 fps with it and 36 without.
It is a build sub-option now (LONGSHOT_TRACY_FIBERS=1). The lifted chunk held Tracy's zone context as 8 bytes where a
TRACY_ON_DEMAND client's is 16, so each game call zone lost its end: it carries 16 bytes of the host's own now, and
HOS_TRACY_GAME is on by default in a Tracy build again.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Author
Owner

Tested in game: RTX 3090, NVIDIA 620.70, Ryzen 9 7900X, Linux, headless in Kokiri Forest with tracy-capture on a port of its own: with fibers told to Tracy (main's setting) 203 to 382 frames in 20 s while capturing (10 to 19 fps; 65 before the capture); without, and with the game-code zones on (HOS_TRACY_GAME=1 set by hand, on the build one edit before this one), 723 frames in 19.9 s, 11.01 million zones, 1,469,461 game call zones, no failure, the file reads back; a 70 s capture with the per-draw zones off: 2,118 frames, 16.6 million zones, 177 MB. Game-free checks, run_all.py --changed through the queue: 59 pass, 6 fail (test_dev_packs, test_failed_compile_keeps_objects, test_link_skip, test_linux_preflight, test_linux_update, test_switch_table), all six among the 36 that fail on a clean checkout of main on this PC. This PR's exact code is built; its own 20 s capture with the default environment is queued and will be a comment here.

Tested in game: RTX 3090, NVIDIA 620.70, Ryzen 9 7900X, Linux, headless in Kokiri Forest with tracy-capture on a port of its own: with fibers told to Tracy (main's setting) 203 to 382 frames in 20 s while capturing (10 to 19 fps; 65 before the capture); without, and with the game-code zones on (HOS_TRACY_GAME=1 set by hand, on the build one edit before this one), 723 frames in 19.9 s, 11.01 million zones, 1,469,461 game call zones, no failure, the file reads back; a 70 s capture with the per-draw zones off: 2,118 frames, 16.6 million zones, 177 MB. Game-free checks, run_all.py --changed through the queue: 59 pass, 6 fail (test_dev_packs, test_failed_compile_keeps_objects, test_link_skip, test_linux_preflight, test_linux_update, test_switch_table), all six among the 36 that fail on a clean checkout of main on this PC. This PR's exact code is built; its own 20 s capture with the default environment is queued and will be a comment here.
HumanBean changed title from WIP: fix(dev): a Tracy build captures at full rate again (fibres off unless asked for), and the game-code zones give a valid capture to fix(dev): a Tracy build captures at full rate again (fibres off unless asked for), and the game-code zones give a valid capture 2026-11-18 03:51:07 +00:00
HumanBean deleted branch fix/tracy-game-zones 2026-11-18 03:51:15 +00:00
Author
Owner

This PR's exact code (d379fbaf), built as a pack and run headless in Kokiri Forest on Linux, RTX 3090, NVIDIA 620.70, with the default environment (the game-code zones and the per-draw zones on, Tracy's sampler on) and a quieter PC than the runs in the description: 1,205 frames in 20 s while capturing (60 fps, against about 65 before a capture), 19.2 million zones (961,000 a second), 2,458,703 game call zones, a 132 MB file, no failure, no zone left open, and the file reads back. A single run.

This PR's exact code (d379fbaf), built as a pack and run headless in Kokiri Forest on Linux, RTX 3090, NVIDIA 620.70, with the default environment (the game-code zones and the per-draw zones on, Tracy's sampler on) and a quieter PC than the runs in the description: 1,205 frames in 20 s while capturing (60 fps, against about 65 before a capture), 19.2 million zones (961,000 a second), 2,458,703 `game call` zones, a 132 MB file, no failure, no zone left open, and the file reads back. A single run.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1546
No description provided.