[FifteenPen]

What and why

Ocarina of Time's pso_manifest.tsv has 123 M rows (native task / mesh pipelines, PR #1368 / #1488 / bf420fd), recorded in Kokiri Forest, Hyrule Field, Castle Town and Hyrule Castle. Task / mesh pipelines are not in the bundled offline archive (pso_offline.py leaves mesh pairs to the draw), so one outside the list is compiled on the submit thread at its first draw. On a cold Metal cache that is 50 ms to 1.7 s per pipeline.

This adds 41 M rows: 39 model pipelines behind the task shader a5288d0a6c4971fd_b and 2 foliage pipelines without one. They come from a play log of later areas, Death Mountain Trail among them, recorded by a host whose M rows match main's byte for byte (118 of main's 123 rows appear in that log as they are), and 11 of them were also recorded by main's own host on Death Mountain Trail in the runs below. All 164 rows parse and build in the prepare step (pipeline prewarm: 164 native task / mesh pipelines; … 164 built and captured).

No code change; the game note's entry on native mesh pipelines gets the numbers.

Checked

Cold first start as the Mac app starts it (DM_PSO_PREPARE=1, the prepare step before the first frame), Metal's shader cache and the device pipeline archive emptied before every run, a build of main 04811a6 with other open PRs applied (none of them touches the prewarm or task / mesh pipelines) and its bundled archive, bench.py route field-run from a Death Mountain Trail save (window 85-130 s), M4 Pro, macOS 27.2, alternating:

run	prepare step	task / mesh pipelines built at their first draw	worst frame	fps
123 rows	29.6 s	9 (2.7 s, worst 1,742 ms)	1,775 ms	57.4
164 rows	32.1 s	0	25.6 ms	60.0
123 rows	29.3 s	10 (4.2 s, worst 1,627 ms)	1,657 ms	54.7
164 rows	31.0 s	0	18.5 ms	60.0

• With a warm Metal cache the same pipelines build at the draw in 0.1-2.3 ms, so the gain is a first start's (or a first visit's) on a device.
• Tests: test_game_profile.py, test_docs.py; docs_symptoms.py --check.
• Not run: regress.py check (a profile list only, no shader or host change), iOS.

Docs

• The finding is in its game note (the "Native mesh pipelines compiled at their first draw" entry under Found on this game).
• No game files, keys or data extracted from a game in the change or the attachments.

[FifteenPen]

This PR has a substantial playability benefit. The vast majority of pre-existing stutters are eliminated with this. Things that reliably cause stuttering (like moving the camera around while standing still in Hyrule Castle Town) will no longer do that.

[seedds]

Landed as dbf8499 on main, with you as co-author: your 41 rows and the game-note entry as they were, plus one line in docs/reference/shaders.md that now links the game note for the M-row count instead of saying 123. Thanks for the alternating cold-cache runs; they made this an easy call. Building these mesh pipelines into the bundled archive (pso_offline.py) would remove the extra ~2 s in the prepare step; that stays open in the reference entry.