[ksolenk38ze]

What and why

Updates the The Legend of Zelda: Ocarina of Time (0400486024DEC000) prewarm pipeline manifest (pso_manifest.tsv, 40,154 entries regenerated on current main covering Kokiri Forest, the Great Deku Tree, Hyrule Field, Kakariko Village, Dodongo's Cavern, Zora's Domain, Jabu-Jabu's Belly, and the Forest Temple through Phantom Ganon), expands shader_seen.tsv (7,278 -> 25,261 shader keys, covering all keys referenced by pso_manifest.tsv plus all 520 mesh/task shaders and their 1,000 paired pixel shaders from shader_pairs.tsv so --seen-shaders partial Mac builds cover the same route and mesh pairs), and updates the game notes (README.md).

Related

• Related to Test support for The Legend of Zelda: Ocarina of Time #1265, Ocarina of Time (0400486024DEC000 v131072, Mac M3 Pro): black picture with sound from the first frame; Game's upscaler = MetalFX (DM_UPSCALER=metalfx) brings the picture back #1477, Ocarina of Time: a prewarm seed list (9,784 rows), so a first start prepares its pipelines instead of freezing for them in play #1488, Ocarina of Time's first start no longer shows a black picture with the title music for minutes: pso_manifest.tsv seeds the prepare step #1493, and The host reports the task / mesh draws it dropped while their pipeline was still being built #1720 (0400486024DEC000 pipeline prewarm coverage, --seen-shaders key list, and game notes).
• Companion profile PR to nvn: implement nvnCommandBufferWaitEvent and per-queue command parking #1728, nvn: pre-pass indirect draw conversion and indirect dispatch/mesh clamp #1729, nvn: merge contiguous gmem pool runs and harden MTL4Archive pipeline loading #1730, and nvn: preserve texture upgrades, BC render targets, and retired descriptor bounds #1731; split from The Legend of Zelda: Ocarina of Time (0400486024DEC000): renderer, shader and pipeline archive fixes through the Forest Temple #1590 (superseding The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000, v0 & v131072): playable at 60 fps through Dodongo's Cavern #1444).

Checked

• Tests: python3 dm/tools/docs_symptoms.py, python3 -m unittest dm/tools/tests/test_game_profile.py dm/tools/tests/test_docs.py (18/18 OK)
• Games run, with title ID and version: The Legend of Zelda: Ocarina of Time (0400486024DEC000, v131072, SDK 22.2.8), verified prewarm archive generation and 60 fps gameplay on Mac.
• Devices and OS: Apple Silicon Mac, macOS 26.2

Docs

• The finding is in its game note or its docs/reference/<subsystem>.md entry, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• No game files, keys or data extracted from a game in the commit

[ZhaowTao]

A partial build on a wider route misses 2,614 keys, and this list covers all of them

Independent playtest data, in case it helps judge whether 25,261 is enough.

Setup. Mac app built with --seen-shaders at chain adec7d81d970, engine 641d1480 (2026-11-03). Its partial library is 8,648 keys in a 3.59 GB b-adec7d81d970.img, and its pso_manifest.tsv has 2 rows, so no pipeline is prewarmed. Apple M5, 24 GB, macOS 26.6.2, v131072.

Method. Two ordinary play sessions, about 11 and 29 minutes of play before a GPU address fault stopped the picture (the host kept presenting afterwards: issue 1326). I scanned both host logs for the lines the missing library produces:

[nvn-mtl] [RED] failed to load shader <key>_b: cannot open
    .../msl/b-adec7d81d970/<key>_b.metallib

Result. 2,358 keys in the first log, 1,391 in the second, 2,614 unique keys together. Every one of them is a key of the v131072 shader_map.tsv (checked against the map at main, 42,848 keys). By stage:

stage	keys
vertex	1,204
pixel	1,151
compute	259

Coverage against the two lists.

list	of the 2,614
main's shader_seen.tsv (7,278 keys)	0
this PR's shader_seen.tsv (25,261 keys)	2,614
in neither	0

What the gap is made of. Not places, effect and enemy tables:

• by package: vs_effect.bin 813, ps_shader.bin 683, ps_effect.bin 464, vs_shader.bin 387, cs_effect.bin 252, cs_shader.bin 7, vs_lib.bin 4, ps_lib.bin 4
• by source column: 1,529 under /Effect, 1,077 under /Shader
• enemies: Enemy_Peahat 119, Enemy_Stalchild 58, Enemy_Keese 48, Enemy_Peahat_Larva 32, Enemy_Guay 30, Enemy_ReDead 19, Enemy_Gibdo 15
• weather and fog: EftLoc_Hyrule_Fog_HyruleLakeArea 50, EftLoc_Kakariko_Fog 26, ..._DeathMountain 24, ..._HyruleCastle 22, ..._ZoraArea 17
• water: EftLoc_HrlField_WaterFall_ZoraTerrain_A 21, ..._WaterFallBottom 19

Why I think this supports the PR. The 7,278 list is the main route. A player who fights at night, crosses the lake in fog or walks the Zora waterfalls leaves it almost at once, and the picture loses those draws until someone rebuilds. This PR's list does not depend on a route at all: it is the keys pso_manifest.tsv references plus every mesh and task shader with its pairs, so it happens to cover the effect tables a route-based list never asks for. Our 2,614 missing keys came out of it with no additions, which is the first evidence I have that the "whole map, not a walk" rule is the right one for this title.

One observation I can only report, not explain: of the 259 missing compute keys, cs_effect.bin holds 252, and in those sessions the picture showed wrong-colour patches (magenta and a red glow) rather than dropping those draws. That is the opposite of what issue 1519 describes for a missing shader, so I am not claiming a cause. DM_NVN_ZBLOCK=1 on the next build should say whether the textures those passes fill are all-zero blocks.

A doc nit: the game note still reads listed in shader_seen.tsv (7,276; building them took about 10 minutes when most came from the previous chain's libraries), while this PR takes the list to 25,261. The build time of the new list is also much larger than ten minutes, so that sentence may want the new figure.

I am not asking for changes to the list; I wanted to hand over a route that reaches past it, since 25,261 is a big number and this says where it stops being one.

[ksolenk38ze]

Thank you @ZhaowTao for the independent verification against your 2,614 missing shader keys! That is a great confirmation that deriving shader_seen.tsv from the full pso_manifest.tsv plus all 520 mesh/task shaders and their 1,000 paired pixel shaders covers the effect, weather, fog, and night enemy tables outside a single walk.

We also updated line 26 of dm/games/0400486024DEC000/README.md to reflect the new 25,261 figure as noted.

[ycarogabriel-lgtm]

Base M1 data on the shader key list (MacBook Pro M1, 16 GB, macOS 26.6.2; OoT v131072; local branch, chain 90e8d82142f4).

Measured: our shader map has 42,848 keys; the app library we built from a seen-list had 18,563 of them. One 25-minute session logged 592 failed to load shader keys, none benign (enemy and object effects in the Deku Tree, 22 Model.Product ones), and the repo's shader_seen.tsv of that time covered 0 of the 592. Separately, the foliage compute e28c9a738fbd99fe and 3 Weapon_Sword shaders were missing; the host skips the dispatch ("the dispatched program has no compute shader"), so foliage disappears for about 3 frames at each sword hit. We built those 33 as an overlay.
Hypothesis/plan, not yet done: we are building the other 23,322 keys. We have not checked whether the 25,261 keys here cover our 592; we can post that overlap. We would share the key list and method, not compiled libraries, which are chain-specific.

[ycarogabriel-lgtm]

A data point on how far the list can go, from a base M1 (MacBook Pro, 16 GB, macOS 26.6.2), measured against this PR's head (shader_seen.tsv = 25,261 unique keys).

• We built the whole dm/games/0400486024DEC000/shader_map.tsv offline: 42,848 unique keys, of which 42,847 produced a metallib. The one failure is c58be4c13dd41495 (listed in shader_map.tsv as agl_common.sharcb#BAHS): the translator stops with "Ampere instruction 481 not implemented". The word it chokes on, 020c0481, looks like the first word of a vertex shader's header rather than an instruction, so this is probably a false BAHS entry of the kind the shader splitter already filters (the same word shows up in Mario Kart World 1.8.0 (v917504): plays on the Mac; iOS kills it for memory when the first race loads (iPhone 18 Pro Max) #1237 for another game); we have not re-run the split to check that the current rule removes this key, so treat it as a lead, not a finding.
• Cost on that machine: about 4 hours of wall time including pauses for memory guards (12 batches of 2,000 keys, 3 to 7 workers), and a 9 GB library. With only the build running, memory stayed comfortable at those worker counts (free memory above 60% in the batches we sampled); running a game next to it pushed swap to about 4 GB and we paused the build.
• 17,587 keys of shader_map.tsv are not in this PR's shader_seen.tsv; 0 keys in the PR's list are absent from shader_map.tsv, so the list has no stray entries. In one 25-minute Deku Tree walk with an app library of 18,563 keys, we logged 592 failed to load shader keys; the walk stopped logging any once the library covered the whole map (a 55-minute session afterwards: 0 such lines).
• The 17,587 are simply the rest of the existing shader_map.tsv, so a complete list needs no new information, only a decision to include them. We can share the plain key list (one hash per line) if useful. We are not sharing binaries, metallibs or MSL, since they derive from the game.

[XIIYAZ]

This PR conflicts with main in pso_manifest.tsv and the README. How I merged it for my Ocarina of Time build:

• pso_manifest.tsv: the union of main's rows and this PR's, sorted and with duplicates dropped. Later Ocarina of Time: prewarm list rows for the Great Deku Tree entry #2518, Ocarina of Time: prewarm list rows from 1 h 40 min of play (Hyrule Field, Lake Hylia, Castle Town) #2531 and game: Ocarina of Time prewarms 89 more task / mesh pipelines #2550 merged the same way on top (44,736 lines in all).
• README: main's text kept where the two differ, because main's Shaders and Status lines are newer than this PR's.

The game ran with that list for several days on an M4 Max: no pipeline stalls I could see, in areas that stuttered before.