build(release): a pipeline list converted from Fritchii's shader reci… #2133

Merged

pmwork-personal merged 1 commit from feat/fritchii-recipe-list into main

2026-11-11 21:32:33 +00:00

pmwork-personal commented

2026-11-11 04:30:10 +00:00

(Migrated from github.com)

Fritchii ships a recipe of the pipelines Ocarina of Time draws, and 1,461 of them are pipelines no list here holds that convert to whole HKSTATE2 records. This adds them as contrib/pmwork-personal-fritchii-recipe, as discussed in #dev-work.

What the recipe is. Fritchii (a Lichii fork) ships OoT v131072 (cache v54).nx2recipe: the pipelines its testers' sessions drew plus the states it predicts. Each shader is named by a fingerprint, and the recipe holds no code (its format is in nx2_recipe.h / nx2_shader_extract.h on Fritchii's oot-gather-fix branch).

How it maps.

Shaders. The fingerprint is SHA-256 of the stage's control section (first 0x48 bytes, +0x30..0x33 zeroed), then its code area. code_key hashes the same control and code bytes with FNV, so a player's hookshot_shaders.bin names the recipe's shaders by code key: 41,165 of 41,216.
Render state. It maps by meaning:
- target and depth formats (Maxwell render-target formats to NVN's, one to one for every format OoT uses)
- samples and topology class
- blend factors and equations, into nvn_blend_st
- channel mask, polygon mode, depth clamp and alpha to coverage

What it can't hold. The recipe was recorded with dynamic vertex input, so it has no vertex formats or divisors. It has no texture answers either. So a pipeline is in this list only when:

main's lists fix both for its program (one vertex input for the vertex stage and one variant), or
it needs neither: mesh draws take no vertex input, and a program none of whose stages asks about a texture or image has variant 0. All 40 such programs in main's lists have variant 0 there.

Point-topology states that the recipe predicts for programs main's lists draw as triangles are left out: 728 of the 734 checkable ones disagreed with main.

Checked against main. I converted every recipe pipeline main's lists already hold the same way. 13,323 of 19,738 match one of their records field for field, including blend, masks and clamp. The rest are:

other states of the same draws, e.g. additive vs alpha blend; or
blend enables past the last target, which Lichii clears and Hookshot keys only on a GPU without dynamic blend state.

There was no systematic difference in any field.

Files.

assets/pipeline_states/contrib/pmwork-personal-fritchii-recipe.bin.xz and .md, written by nx2/pipeline_states.py add. The note says how the list was made.
assets/pipeline_states/README.md: one paragraph saying the lists named pmwork-personal-fritchii-recipe* are converted, not recorded. They hold the same records and nothing more.

The converter is a small script (recipe + hookshot_shaders.bin + main's merged list → HKSTATE2). It isn't in this PR; happy to add it under scripts/ if you want the list reproducible.

Tested.

nx2/pipeline_states.py check: merged list 26,712 pipelines (main 25,251 + 1,461).
Tests: test_pipeline_states, test_pipeline_state_sources, test_pipeline_state_counts, test_pipeline_state_portable, test_ship_state_list.
python -I -B tests/run_all.py on main with both PRs (Windows): 342 passed, 2 failed, 30 skipped (Linux-only). The two (test_precompile_compute_guard.py, test_recorder_sync.py) fail the same on main without these changes on this PC.
In the game's preparation: a build of main with this list and the follow-up's (#2134) ran the Builder's shader preparation (RTX 5090, driver 621.14):

vk: state list: 38697 pipelines (38697 shipped, version 2), 14866 programs (1200 translated now, 0 with stages not in the seed), 953 variants by their textures (953 made), 4798 by nothing bound (4798 made), 38584 noted (2438 native mesh, 0 mesh fallback, 11985 by nothing bound), 113 whose program variant was not made, in 10.2 s

Every record of this list was noted. The 113 not made are records main's lists already hold that were noted without answers (1,285 such records there, none here).

Credit: the recipe is Fritchii's (Frizti), built from its testers' sessions.

🤖 Generated with Claude Code

Fritchii ships a recipe of the pipelines Ocarina of Time draws, and 1,461 of them are pipelines no list here holds that convert to whole HKSTATE2 records. This adds them as `contrib/pmwork-personal-fritchii-recipe`, as discussed in #dev-work. **What the recipe is.** Fritchii (a Lichii fork) ships `OoT v131072 (cache v54).nx2recipe`: the pipelines its testers' sessions drew plus the states it predicts. Each shader is named by a fingerprint, and the recipe holds no code (its format is in `nx2_recipe.h` / `nx2_shader_extract.h` on Fritchii's `oot-gather-fix` branch). **How it maps.** - **Shaders.** The fingerprint is SHA-256 of the stage's control section (first 0x48 bytes, +0x30..0x33 zeroed), then its code area. `code_key` hashes the same control and code bytes with FNV, so a player's `hookshot_shaders.bin` names the recipe's shaders by code key: 41,165 of 41,216. - **Render state.** It maps by meaning: - target and depth formats (Maxwell render-target formats to NVN's, one to one for every format OoT uses) - samples and topology class - blend factors and equations, into `nvn_blend_st` - channel mask, polygon mode, depth clamp and alpha to coverage **What it can't hold.** The recipe was recorded with dynamic vertex input, so it has no vertex formats or divisors. It has no texture answers either. So a pipeline is in this list only when: - main's lists fix both for its program (one vertex input for the vertex stage and one variant), or - it needs neither: mesh draws take no vertex input, and a program none of whose stages asks about a texture or image has variant 0. All 40 such programs in main's lists have variant 0 there. Point-topology states that the recipe predicts for programs main's lists draw as triangles are left out: 728 of the 734 checkable ones disagreed with main. **Checked against main.** I converted every recipe pipeline main's lists already hold the same way. 13,323 of 19,738 match one of their records field for field, including blend, masks and clamp. The rest are: - other states of the same draws, e.g. additive vs alpha blend; or - blend enables past the last target, which Lichii clears and Hookshot keys only on a GPU without dynamic blend state. There was no systematic difference in any field. **Files.** - `assets/pipeline_states/contrib/pmwork-personal-fritchii-recipe.bin.xz` and `.md`, written by `nx2/pipeline_states.py add`. The note says how the list was made. - `assets/pipeline_states/README.md`: one paragraph saying the lists named `pmwork-personal-fritchii-recipe*` are converted, not recorded. They hold the same records and nothing more. The converter is a small script (recipe + `hookshot_shaders.bin` + main's merged list → HKSTATE2). It isn't in this PR; happy to add it under `scripts/` if you want the list reproducible. **Tested.** - `nx2/pipeline_states.py check`: merged list 26,712 pipelines (main 25,251 + 1,461). - Tests: `test_pipeline_states`, `test_pipeline_state_sources`, `test_pipeline_state_counts`, `test_pipeline_state_portable`, `test_ship_state_list`. - `python -I -B tests/run_all.py` on main with both PRs (Windows): 342 passed, 2 failed, 30 skipped (Linux-only). The two (`test_precompile_compute_guard.py`, `test_recorder_sync.py`) fail the same on main without these changes on this PC. - In the game's preparation: a build of main with this list and the follow-up's (#2134) ran the Builder's shader preparation (RTX 5090, driver 621.14): `vk: state list: 38697 pipelines (38697 shipped, version 2), 14866 programs (1200 translated now, 0 with stages not in the seed), 953 variants by their textures (953 made), 4798 by nothing bound (4798 made), 38584 noted (2438 native mesh, 0 mesh fallback, 11985 by nothing bound), 113 whose program variant was not made, in 10.2 s` Every record of this list was noted. The 113 not made are records main's lists already hold that were noted without answers (1,285 such records there, none here). Credit: the recipe is Fritchii's (Frizti), built from its testers' sessions. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Joey-Magnus (Migrated from github.com) reviewed

2026-11-11 20:06:46 +00:00

Joey-Magnus (Migrated from github.com) left a comment

question (maintainer) assets/pipeline_states/README.md:5-7: the folder's rule until now was "only lists written by Hookshot and this folder's tool go in here". This PR adds an exception for one named list. That deserves an explicit yes from the maintainer, since it opens the door to converted lists in general. Related: the recipe is Fritchii's data, built from its testers' sessions. Credit is given, but the PR doesn't say under what terms it may be redistributed inside a GPL-3.0 repo. Was permission given (the #dev-work discussion?), or is the recipe published under a licence that allows this? A link or a line in the .md note would settle it. The list holds only hashes and draw state, so this isn't a game-data problem. It's a question of whose data it is.

should fix: the converter isn't in the PR (the body offers to add it). For a list that is converted rather than recorded, the script is the only way to review or regenerate it. That matters when main's lists change (inclusion depends on "main's lists fix one vertex input and one variant"), and when code_key or the record format changes. Please add it under scripts/ (standard library only, per CONTRIBUTING), and have the note name the command that produced this file.

should fix: predicted states. The recipe holds "the pipelines its testers' sessions drew plus the states it predicts". Your own check found that the point-topology predictions disagreed with main in 728 of 734 checkable cases. That is a strong signal that the prediction isn't reliable, and the other predicted states are kept. A wrong record costs a pipeline compiled for nothing during the Builder's preparation, on every player's PC. Could you split the 1,461 into drawn and predicted? Then either ship only the drawn ones, or show what share of the predicted ones match main where they overlap.

minor: the note says that blend enables past the last target are cleared by Lichii, and that Hookshot keys on them only on GPUs without dynamic blend state. On those GPUs, such records will not match what the game asks for. They are harmless but wasted there. Worth a sentence in the note so nobody later reads the mismatch as a bug.

I didn't review the .bin.xz record by record. CI's test_pipeline_state* checks validate its format, and they pass.

Nice piece of cross-checking: matching 13,323 of 19,738 field for field against main's lists is good evidence that the mapping is right. The merge is clean and CI is green. Before this goes in, I think it needs a maintainer decision and a couple of changes, because it is the first list in `assets/pipeline_states/` that Hookshot did not record. **question (maintainer)** `assets/pipeline_states/README.md:5-7`: the folder's rule until now was "only lists written by Hookshot and this folder's tool go in here". This PR adds an exception for one named list. That deserves an explicit yes from the maintainer, since it opens the door to converted lists in general. Related: the recipe is Fritchii's data, built from its testers' sessions. Credit is given, but the PR doesn't say under what terms it may be redistributed inside a GPL-3.0 repo. Was permission given (the #dev-work discussion?), or is the recipe published under a licence that allows this? A link or a line in the `.md` note would settle it. The list holds only hashes and draw state, so this isn't a game-data problem. It's a question of whose data it is. **should fix**: the converter isn't in the PR (the body offers to add it). For a list that is converted rather than recorded, the script is the only way to review or regenerate it. That matters when main's lists change (inclusion depends on "main's lists fix one vertex input and one variant"), and when `code_key` or the record format changes. Please add it under `scripts/` (standard library only, per CONTRIBUTING), and have the note name the command that produced this file. **should fix**: predicted states. The recipe holds "the pipelines its testers' sessions drew plus the states it predicts". Your own check found that the point-topology predictions disagreed with main in 728 of 734 checkable cases. That is a strong signal that the prediction isn't reliable, and the other predicted states are kept. A wrong record costs a pipeline compiled for nothing during the Builder's preparation, on every player's PC. Could you split the 1,461 into drawn and predicted? Then either ship only the drawn ones, or show what share of the predicted ones match main where they overlap. **minor**: the note says that blend enables past the last target are cleared by Lichii, and that Hookshot keys on them only on GPUs without dynamic blend state. On those GPUs, such records will not match what the game asks for. They are harmless but wasted there. Worth a sentence in the note so nobody later reads the mismatch as a bug. I didn't review the `.bin.xz` record by record. CI's `test_pipeline_state*` checks validate its format, and they pass.

Joey-Magnus (Migrated from github.com) reviewed

2026-11-11 21:25:58 +00:00

Joey-Magnus (Migrated from github.com) left a comment

This is the first list in assets/pipeline_states/ that Hookshot didn't record, so it needs a maintainer yes or no on converted lists, and a word on whether Fritchii's recipe may be redistributed under GPL-3.0. There's no game data in it.

If it goes in:

The converter should be under scripts/, so the list can be reviewed and regenerated when code_key changes.
Predicted states should be split from drawn ones. 728 of the 734 checkable point-topology predictions disagreed with main, though 13,323 of the 19,738 overlapping pipelines match field for field.

The title is cut off with "…".

This is the first list in `assets/pipeline_states/` that Hookshot didn't record, so it needs a maintainer yes or no on converted lists, and a word on whether Fritchii's recipe may be redistributed under GPL-3.0. There's no game data in it. If it goes in: - The converter should be under `scripts/`, so the list can be reviewed and regenerated when `code_key` changes. - Predicted states should be split from drawn ones. 728 of the 734 checkable point-topology predictions disagreed with main, though 13,323 of the 19,738 overlapping pipelines match field for field. The title is cut off with "…".