From 3d4b63c19e0dde3e6aab138e056e2445dab0c42a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Fri, 23 Oct 2026 15:25:10 +0200
Subject: [PATCH 001/270] wasmtime 48 LTS: one wasm-tools version for the
 runtime, packing and the SDK

wasmtime 36 read WebAssembly with wasm-tools 0.236, wit-component (cargo
horizon-mod, the sandbox tests) used 0.239 and the SDK's wit-bindgen 0.247:
three copies of wasmparser, wasm-encoder, wit-parser and wasm-metadata.
wasmtime 48, the next long-term-support line (fixes until August 2028),
wit-component 0.254 and wit-bindgen 0.60 all use 0.254. No code change;
horizon-mods now needs Rust 1.95.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                        | 541 +++++++++++++-----------------
 crates/horizon-mod-sdk/Cargo.toml |   2 +-
 crates/horizon-mods/Cargo.toml    |  10 +-
 docs/mods.md                      |   8 +-
 4 files changed, 241 insertions(+), 320 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 2f832e248..420f2226c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -20,9 +20,9 @@ checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
 
 [[package]]
 name = "addr2line"
-version = "0.25.1"
+version = "0.26.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+checksum = "59317f77929f0e679d39364702289274de2f0f0b22cbf50b2b8cff2169a0b27a"
 dependencies = [
  "gimli",
 ]
@@ -155,7 +155,7 @@ dependencies = [
  "objc2-foundation 0.3.2",
  "parking_lot",
  "percent-encoding",
- "windows-sys 0.59.0",
+ "windows-sys 0.60.2",
  "wl-clipboard-rs",
  "x11rb",
 ]
@@ -196,6 +196,17 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -572,7 +583,7 @@ dependencies = [
  "jni 0.21.1",
  "js-sys",
  "libc",
- "mach2",
+ "mach2 0.4.3",
  "ndk",
  "ndk-context",
  "num-derive",
@@ -586,6 +597,15 @@ dependencies = [
  "windows 0.54.0",
 ]
 
+[[package]]
+name = "cpp_demangle"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0667304c32ea56cb4cd6d2d7c0cfe9a2f8041229db8c033af7f8d69492429def"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -597,46 +617,48 @@ dependencies = [
 
 [[package]]
 name = "cranelift-assembler-x64"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e92993516bcc43fd4e511b31d2e0c0c24f6b7ac18bb39e32cac2bfc05ea378e"
+checksum = "e6071a4f1df4837aa03d1e4d53067784acafe270ffc7dad66a7f39832204da3f"
 dependencies = [
  "cranelift-assembler-x64-meta",
 ]
 
 [[package]]
 name = "cranelift-assembler-x64-meta"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97eeeb61b08ec484f274119faf3a8a1b80dd300b0208c0247d16d05982fc89fe"
+checksum = "5e3b92a9cc90388fe70e63640af30b734387449445aef0176ab2028e9892d70e"
 dependencies = [
  "cranelift-srcgen",
 ]
 
 [[package]]
 name = "cranelift-bforest"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "782eb44158681a105d157cb0ce63e3dc83f78ef5674266c12234f49da3f5c6e8"
+checksum = "f45c85646c4425cc85b868effaf20c302b437a3fb79bb27a64513dd522f07411"
 dependencies = [
  "cranelift-entity",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "cranelift-bitset"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "edd59af193204c4f025fb2c2d9ee0aeb1f60929edf000b0dfa3d45543a62f264"
+checksum = "94f56b5c7d564cfa03aa269a6b98c916cab4d545196a391d31403a23ef39333a"
 dependencies = [
  "serde",
  "serde_derive",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "cranelift-codegen"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1c29bd985057d790db25f6bc60b369b311aa2d75c2f496a7e9993585bfc7d60"
+checksum = "2c073641ce6e382814a8220331cc1ea2c782a9ea5d5da6d0f7f7c0541192693e"
 dependencies = [
  "bumpalo",
  "cranelift-assembler-x64",
@@ -648,22 +670,26 @@ dependencies = [
  "cranelift-entity",
  "cranelift-isle",
  "gimli",
- "hashbrown 0.15.5",
+ "hashbrown 0.17.1",
+ "libm",
  "log",
+ "postcard",
  "pulley-interpreter",
  "regalloc2",
  "rustc-hash 2.1.3",
  "serde",
+ "serde_derive",
+ "sha2",
  "smallvec",
  "target-lexicon",
- "wasmtime-internal-math",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "cranelift-codegen-meta"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9ef8a8495f19212f92db8425f768ffc67000c5cb417a0664475a8d09596700f"
+checksum = "db226fafea5194921de10dccf35ac2863500313990f770cbe8b26c51eebec4d4"
 dependencies = [
  "cranelift-assembler-x64-meta",
  "cranelift-codegen-shared",
@@ -674,37 +700,39 @@ dependencies = [
 
 [[package]]
 name = "cranelift-codegen-shared"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a3aa5099097666baf45bd68ef036327c8f29d8785fffaaa7db3b3b6b7e94bcc6"
+checksum = "cf8ac46b2c8e328ca979810426ea635ef90ecc8c54fd3296bde31ab470a48a1d"
 
 [[package]]
 name = "cranelift-control"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "26f67f4f4e92c2934f40c2ff4574400bd27326932aad937a438b7fb459f60a63"
+checksum = "6754e0ab97915209ea6ce6549f6443b018e1338142ada4c856cec213ee82e4b8"
 dependencies = [
  "arbitrary",
 ]
 
 [[package]]
 name = "cranelift-entity"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8393d09f0abaa504896069e79f4eb6f15eb1853e5645732b082dac1ed292aaa8"
+checksum = "774d25e36df18696f63a284e9c4ea43455e2ebcca6308e0e02301f18c8e777e2"
 dependencies = [
  "cranelift-bitset",
  "serde",
  "serde_derive",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "cranelift-frontend"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "580cfaecbd11476dd82f6a393123dcbd9dfe583467df8d0c8441c641444d4985"
+checksum = "69cfcb31405e2de2a48e5a6de8e07a3d8b77f35caa3e944d627780734b36c138"
 dependencies = [
  "cranelift-codegen",
+ "hashbrown 0.17.1",
  "log",
  "smallvec",
  "target-lexicon",
@@ -712,15 +740,15 @@ dependencies = [
 
 [[package]]
 name = "cranelift-isle"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8c044843adb7d94b1facebaad846c0a762f79a77953417e3f0182093bcbbdc38"
+checksum = "2f5a26df22db546ab92be6feaf21835ae91082af0a32bbb398b277df3765412f"
 
 [[package]]
 name = "cranelift-native"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9d4c1707214e53f2040e4d13430069ea22623287b2750ed6d62e40eba88d91a"
+checksum = "19f258c08e590f90dcaf9904d25ba142ee2980c3aaeac4bb45f1452b1a407c2a"
 dependencies = [
  "cranelift-codegen",
  "libc",
@@ -729,9 +757,9 @@ dependencies = [
 
 [[package]]
 name = "cranelift-srcgen"
-version = "0.123.18"
+version = "0.135.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d355a35edc49f628db7b793f3527eed31b560e77c3e8ed0e5258aad8df8a5249"
+checksum = "67055b4f315e8f6af3e8eccec74ad38f7407f0fd854adbd49b4b3b27bdb2e3be"
 
 [[package]]
 name = "crc32fast"
@@ -1003,12 +1031,6 @@ version = "3.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7"
 
-[[package]]
-name = "fallible-iterator"
-version = "0.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
-
 [[package]]
 name = "fdeflate"
 version = "0.3.7"
@@ -1101,12 +1123,48 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "futures"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
 [[package]]
 name = "futures-core"
 version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
 
+[[package]]
+name = "futures-io"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
+
+[[package]]
+name = "futures-sink"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
+
 [[package]]
 name = "futures-task"
 version = "0.3.34"
@@ -1119,8 +1177,12 @@ version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
 dependencies = [
+ "futures-channel",
  "futures-core",
+ "futures-io",
+ "futures-sink",
  "futures-task",
+ "memchr",
  "pin-project-lite",
  "slab",
 ]
@@ -1215,11 +1277,12 @@ dependencies = [
 
 [[package]]
 name = "gimli"
-version = "0.32.3"
+version = "0.33.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+checksum = "0bf7f043f89559805f8c7cacc432749b2fa0d0a0a9ee46ce47164ed5ba7f126c"
 dependencies = [
- "fallible-iterator",
+ "fnv",
+ "hashbrown 0.16.1",
  "indexmap",
  "stable_deref_trait",
 ]
@@ -1315,7 +1378,6 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
 dependencies = [
  "foldhash 0.1.5",
- "serde",
 ]
 
 [[package]]
@@ -1336,6 +1398,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 dependencies = [
  "foldhash 0.2.0",
+ "serde",
+ "serde_core",
 ]
 
 [[package]]
@@ -1486,7 +1550,7 @@ dependencies = [
 name = "horizon-mod-sdk"
 version = "0.1.0"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.60.0",
 ]
 
 [[package]]
@@ -1499,8 +1563,8 @@ dependencies = [
  "serde_json",
  "toml",
  "wasmtime",
- "wit-component 0.239.0",
- "wit-parser 0.239.0",
+ "wit-component",
+ "wit-parser",
  "zip",
 ]
 
@@ -2127,6 +2191,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "mach2"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dae608c151f68243f2b000364e1f7b186d9c29845f7d2d85bd31b9ad77ad552b"
+
 [[package]]
 name = "memchr"
 version = "2.8.3"
@@ -2662,12 +2732,12 @@ dependencies = [
 
 [[package]]
 name = "object"
-version = "0.37.3"
+version = "0.39.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+checksum = "2e5a6c098c7a3b6547378093f5cc30bc54fd361ce711e05293a5cc589562739b"
 dependencies = [
  "crc32fast",
- "hashbrown 0.15.5",
+ "hashbrown 0.17.1",
  "indexmap",
  "memchr",
 ]
@@ -2972,21 +3042,21 @@ checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
 
 [[package]]
 name = "pulley-interpreter"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "334ae8982dcf354e5f28e79fc6f935601e028b729cc174d3937eeeaa859057b8"
+checksum = "2b8187c8e7db87d085865fc106502e7b34d5c25f8ce4c272945b21503371f6a0"
 dependencies = [
  "cranelift-bitset",
  "log",
  "pulley-macros",
- "wasmtime-internal-math",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "pulley-macros"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9cd207bca4bc5e46cb4fcea87196dcbd78befc628c64c67d11dc99fce5cd5369"
+checksum = "7f98ce0e381d9e45e63ea1d20bba3cf131797086077f43af9203f1fb7de0ed6b"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3094,15 +3164,16 @@ dependencies = [
 
 [[package]]
 name = "regalloc2"
-version = "0.12.2"
+version = "0.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5216b1837de2149f8bc8e6d5f88a9326b63b8c836ed58ce4a0a29ec736a59734"
+checksum = "757712e8e61590d6d4f5d563483755538b5aa13467837a3b41cd9832509a7f85"
 dependencies = [
  "allocator-api2",
  "bumpalo",
- "hashbrown 0.15.5",
+ "hashbrown 0.17.1",
  "log",
  "rustc-hash 2.1.3",
+ "serde",
  "smallvec",
 ]
 
@@ -3155,6 +3226,12 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rustc-demangle"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b74b56ffa8bb2830709a538c2cbcae9aa062db0d2a42563bfb09bdaae44020eb"
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -3995,7 +4072,7 @@ version = "1.0.4+wasi-0.2.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.57.1",
 ]
 
 [[package]]
@@ -4056,124 +4133,66 @@ dependencies = [
 
 [[package]]
 name = "wasm-encoder"
-version = "0.236.1"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "724fccfd4f3c24b7e589d333fc0429c68042897a7e8a5f8694f31792471841e7"
+checksum = "ebaca0b540bdb15d195ff34fb23074255948708b8916a11a339ba4513dc61906"
 dependencies = [
  "leb128fmt",
- "wasmparser 0.236.1",
-]
-
-[[package]]
-name = "wasm-encoder"
-version = "0.239.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5be00faa2b4950c76fe618c409d2c3ea5a3c9422013e079482d78544bb2d184c"
-dependencies = [
- "leb128fmt",
- "wasmparser 0.239.0",
-]
-
-[[package]]
-name = "wasm-encoder"
-version = "0.247.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30b6733b8b91d010a6ac5b0fb237dc46a19650bc4c67db66857e2e787d437204"
-dependencies = [
- "leb128fmt",
- "wasmparser 0.247.0",
+ "wasmparser",
 ]
 
 [[package]]
 name = "wasm-metadata"
-version = "0.239.0"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "20b3ec880a9ac69ccd92fbdbcf46ee833071cf09f82bb005b2327c7ae6025ae2"
+checksum = "5d1880dd9a848aa68f387966256c34ad49abb4607e3cfa35720d2723d0591cd3"
 dependencies = [
  "anyhow",
  "indexmap",
- "wasm-encoder 0.239.0",
- "wasmparser 0.239.0",
-]
-
-[[package]]
-name = "wasm-metadata"
-version = "0.247.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "665fe59e56cc9b419ca6fcca56673e3421d1a5011e3b65caf6b726fd9e041d10"
-dependencies = [
- "anyhow",
- "indexmap",
- "wasm-encoder 0.247.0",
- "wasmparser 0.247.0",
+ "wasm-encoder",
+ "wasmparser",
 ]
 
 [[package]]
 name = "wasmparser"
-version = "0.236.1"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9b1e81f3eb254cf7404a82cee6926a4a3ccc5aad80cc3d43608a070c67aa1d7"
+checksum = "c5ff8685b587722894b6f25958fc608d315b93b8d23647bfb567664e7006d757"
 dependencies = [
  "bitflags 2.13.2",
- "hashbrown 0.15.5",
+ "hashbrown 0.17.1",
  "indexmap",
  "semver",
  "serde",
 ]
 
-[[package]]
-name = "wasmparser"
-version = "0.239.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8c9d90bb93e764f6beabf1d02028c70a2156a6583e63ac4218dd07ef733368b0"
-dependencies = [
- "bitflags 2.13.2",
- "hashbrown 0.15.5",
- "indexmap",
- "semver",
-]
-
-[[package]]
-name = "wasmparser"
-version = "0.247.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e6fb4c2bee46c5ea4d40f8cdb5c131725cd976718ec56f1c8e82fbde5fa2a80"
-dependencies = [
- "bitflags 2.13.2",
- "hashbrown 0.17.1",
- "indexmap",
- "semver",
-]
-
 [[package]]
 name = "wasmprinter"
-version = "0.236.1"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2df225df06a6df15b46e3f73ca066ff92c2e023670969f7d50ce7d5e695abbb1"
+checksum = "8b03c8f270f3f384f70f42869b5ff7f6253fe4f0aa8590f7edd332c1943e5f51"
 dependencies = [
  "anyhow",
  "termcolor",
- "wasmparser 0.236.1",
+ "wasmparser",
 ]
 
 [[package]]
 name = "wasmtime"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70095b9fe63cc2a87ed206729e11544610decc184c62898c5d201ff1d666d82e"
+checksum = "12300d040e8bea7e7ccde75b9919d27ebba47a217a64b09ba058ae8d3b4290b6"
 dependencies = [
  "addr2line",
- "anyhow",
+ "async-trait",
  "bitflags 2.13.2",
  "bumpalo",
  "cc",
- "cfg-if",
  "encoding_rs",
- "hashbrown 0.15.5",
- "indexmap",
+ "futures",
  "libc",
  "log",
- "mach2",
+ "mach2 0.6.0",
  "memfd",
  "object",
  "once_cell",
@@ -4185,62 +4204,56 @@ dependencies = [
  "serde_derive",
  "smallvec",
  "target-lexicon",
- "wasmparser 0.236.1",
+ "wasmparser",
  "wasmtime-environ",
- "wasmtime-internal-asm-macros",
  "wasmtime-internal-component-macro",
  "wasmtime-internal-component-util",
+ "wasmtime-internal-core",
  "wasmtime-internal-cranelift",
  "wasmtime-internal-fiber",
  "wasmtime-internal-jit-debug",
  "wasmtime-internal-jit-icache-coherence",
- "wasmtime-internal-math",
- "wasmtime-internal-slab",
  "wasmtime-internal-unwinder",
  "wasmtime-internal-versioned-export-macros",
- "wasmtime-internal-winch",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "wasmtime-environ"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a67ea8904b6e369e2218780bd1f9186f1980cb616445eb2c1f3c4e45c8397865"
+checksum = "805d6554eb6dd6e62891061a31383a89d69fd891f785e5ae68f0835a554b7a2a"
 dependencies = [
  "anyhow",
+ "cpp_demangle",
+ "cranelift-bforest",
  "cranelift-bitset",
  "cranelift-entity",
  "gimli",
+ "hashbrown 0.17.1",
  "indexmap",
  "log",
  "object",
  "postcard",
+ "rustc-demangle",
  "semver",
  "serde",
  "serde_derive",
+ "sha2",
  "smallvec",
  "target-lexicon",
- "wasm-encoder 0.236.1",
- "wasmparser 0.236.1",
+ "wasm-encoder",
+ "wasmparser",
  "wasmprinter",
  "wasmtime-internal-component-util",
-]
-
-[[package]]
-name = "wasmtime-internal-asm-macros"
-version = "36.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d0488a52ae93e654baecb08ce04d15d478756eb2168c2bdab7915710109161ce"
-dependencies = [
- "cfg-if",
+ "wasmtime-internal-core",
 ]
 
 [[package]]
 name = "wasmtime-internal-component-macro"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "377e406c3f8e7bea64db3cb3ee0d406c331e8fc09d8cb2e7bf9ad74cb5d3b31a"
+checksum = "b832b80853365d9d3a741681044554be291a4f977aae074b318b55c7a4835f83"
 dependencies = [
  "anyhow",
  "proc-macro2",
@@ -4248,23 +4261,32 @@ dependencies = [
  "syn 2.0.119",
  "wasmtime-internal-component-util",
  "wasmtime-internal-wit-bindgen",
- "wit-parser 0.236.1",
+ "wit-parser",
 ]
 
 [[package]]
 name = "wasmtime-internal-component-util"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97c24503bb712afe2c797dc291b96e57556ee62c35fd951f87e96088324de37c"
+checksum = "4c8a11aaf68d8945991429d45950f32490a30ddcdcdb56629816cb41a255d8fe"
+
+[[package]]
+name = "wasmtime-internal-core"
+version = "48.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea266d6cfb31c324c075c8432386654bcbb1559aa8d29be9d47eacf7dcc41012"
+dependencies = [
+ "hashbrown 0.17.1",
+ "libm",
+ "serde",
+]
 
 [[package]]
 name = "wasmtime-internal-cranelift"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f63ea7ee133de9109a4a1fc63dae3afc9ea32e92b8dada824fa4595dbf175f80"
+checksum = "d427759553b07c296c8ed7bff8ac930a94b9ba99e6a79243ea79bcc51aa58d96"
 dependencies = [
- "anyhow",
- "cfg-if",
  "cranelift-codegen",
  "cranelift-control",
  "cranelift-entity",
@@ -4278,33 +4300,32 @@ dependencies = [
  "smallvec",
  "target-lexicon",
  "thiserror 2.0.21",
- "wasmparser 0.236.1",
+ "wasmparser",
  "wasmtime-environ",
- "wasmtime-internal-math",
+ "wasmtime-internal-core",
+ "wasmtime-internal-unwinder",
  "wasmtime-internal-versioned-export-macros",
 ]
 
 [[package]]
 name = "wasmtime-internal-fiber"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69662a0a4dbe9784d1e8add9e3c5d2db0ca348085c624c27a70992dbe2eff4a3"
+checksum = "b54c8c5b02ea985149a90f917e1761af99734c6c27e6d7fdd5b6f69fc1db3950"
 dependencies = [
- "anyhow",
  "cc",
- "cfg-if",
  "libc",
  "rustix 1.1.5",
- "wasmtime-internal-asm-macros",
+ "wasmtime-environ",
  "wasmtime-internal-versioned-export-macros",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "wasmtime-internal-jit-debug"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "00cb07d23903c0be359d6b920d94774ea322759c3f4d6721b61afa03602e4804"
+checksum = "72bb10c94724f072b6eca515085033e61da9efae65d054545126df37a15530c3"
 dependencies = [
  "cc",
  "wasmtime-internal-versioned-export-macros",
@@ -4312,83 +4333,50 @@ dependencies = [
 
 [[package]]
 name = "wasmtime-internal-jit-icache-coherence"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aa2b47c37a6d026e2755fe2cf7ec5c1f4b0fba62e448ea910cdf6a07a4982c6a"
+checksum = "1b781a27e8958fd07fd3135c0be216f77301efecd15cbf4f14ff210cdad5f169"
 dependencies = [
- "anyhow",
- "cfg-if",
  "libc",
- "windows-sys 0.60.2",
+ "wasmtime-internal-core",
+ "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "wasmtime-internal-math"
-version = "36.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b269f0ba44102c57fd5f94f1bf4395ccd4fc2b84698fc78f627a6f2a47131a62"
-dependencies = [
- "libm",
-]
-
-[[package]]
-name = "wasmtime-internal-slab"
-version = "36.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e35ac9d503d503703cd24d532e53e2e93c86109b451df40a9801500045aee25"
-
 [[package]]
 name = "wasmtime-internal-unwinder"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83ce1d0930da44ed375701e6b4f187b46249f7efe2b1d8c1c77229a4adc82de9"
+checksum = "121188de1b2741b8e35530a9b0c8adf525b3aa5913a2ca3d4522509cfbc0494a"
 dependencies = [
- "anyhow",
- "cfg-if",
  "cranelift-codegen",
  "log",
  "object",
+ "wasmtime-environ",
 ]
 
 [[package]]
 name = "wasmtime-internal-versioned-export-macros"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b6633be262400bd7abab4ff767a16e8b6a41ff117be54bf76dabecea9f96225"
+checksum = "933f1990e4e5177547a4abd51dcfa5cb7616fe42b9fb6f0f2b7423627758223c"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "wasmtime-internal-winch"
-version = "36.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "509d1e1cf8e3b3306f291407c92bca8381d9294f8c54ad74b692538f1f5b23c7"
-dependencies = [
- "anyhow",
- "cranelift-codegen",
- "gimli",
- "object",
- "target-lexicon",
- "wasmparser 0.236.1",
- "wasmtime-environ",
- "wasmtime-internal-cranelift",
- "winch-codegen",
-]
-
 [[package]]
 name = "wasmtime-internal-wit-bindgen"
-version = "36.0.18"
+version = "48.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6d9a5b51b3400b4df1055724c4536ad5aa58fafe83cea5ca94f88cc9eb97563"
+checksum = "417ebd61d2581d86d65413517f3a41294a9ad105da26f0dc7039912a0d97e1ed"
 dependencies = [
  "anyhow",
  "bitflags 2.13.2",
  "heck",
  "indexmap",
- "wit-parser 0.236.1",
+ "wit-component",
+ "wit-parser",
 ]
 
 [[package]]
@@ -4698,26 +4686,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "winch-codegen"
-version = "36.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e470d7e674c41ad32dddc02d8d8a94983e0a4c516028bda60747e6dd862a567"
-dependencies = [
- "anyhow",
- "cranelift-assembler-x64",
- "cranelift-codegen",
- "gimli",
- "regalloc2",
- "smallvec",
- "target-lexicon",
- "thiserror 2.0.21",
- "wasmparser 0.236.1",
- "wasmtime-environ",
- "wasmtime-internal-cranelift",
- "wasmtime-internal-math",
-]
-
 [[package]]
 name = "windows"
 version = "0.54.0"
@@ -5164,42 +5132,48 @@ name = "wit-bindgen"
 version = "0.57.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.60.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a301904d6657d6364c758d869e5389d05d393b16d5b65db60b4f03cbe71bb80d"
 dependencies = [
  "wit-bindgen-rust-macro",
 ]
 
 [[package]]
 name = "wit-bindgen-core"
-version = "0.57.1"
+version = "0.60.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02dee27a2dc20d1008016c742ec9fc6ea498492994ba3750be7454cbc97ff04c"
+checksum = "48521bb96e56cbb9e031ad306c80dc20e89e69e49ada02781ee06f60fbcb545f"
 dependencies = [
  "anyhow",
  "heck",
- "wit-parser 0.247.0",
+ "wit-parser",
 ]
 
 [[package]]
 name = "wit-bindgen-rust"
-version = "0.57.1"
+version = "0.60.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5007dae772945b7a5003d69d90a3a4a78929d41f19d004e980c4259a6af4484"
+checksum = "3df3fe9b9a0066f82fd0c2f07f79d0ffc0f85c53fa5f998516d8722712479042"
 dependencies = [
  "anyhow",
  "heck",
  "indexmap",
  "prettyplease",
  "syn 2.0.119",
- "wasm-metadata 0.247.0",
+ "wasm-metadata",
  "wit-bindgen-core",
- "wit-component 0.247.0",
+ "wit-component",
 ]
 
 [[package]]
 name = "wit-bindgen-rust-macro"
-version = "0.57.1"
+version = "0.60.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "af9237d678e3513ad24e96fe98beacdc0db6405284ba2a2400418cf0d42caa89"
+checksum = "d689c4bc9d6af067c651cfba444766343c9a4bdef15fad1e2efab95c0c277af0"
 dependencies = [
  "anyhow",
  "prettyplease",
@@ -5212,9 +5186,9 @@ dependencies = [
 
 [[package]]
 name = "wit-component"
-version = "0.239.0"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88a866b19dba2c94d706ec58c92a4c62ab63e482b4c935d2a085ac94caecb136"
+checksum = "1c96b3cea6838dbea55173baa56991fcb087896c321b0a770db201e5a0bd3506"
 dependencies = [
  "anyhow",
  "bitflags 2.13.2",
@@ -5223,72 +5197,17 @@ dependencies = [
  "serde",
  "serde_derive",
  "serde_json",
- "wasm-encoder 0.239.0",
- "wasm-metadata 0.239.0",
- "wasmparser 0.239.0",
- "wit-parser 0.239.0",
-]
-
-[[package]]
-name = "wit-component"
-version = "0.247.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d567162a6b9843080e5e0053f696623ff694bae8ae017c9ec536d1873bbe3d8"
-dependencies = [
- "anyhow",
- "bitflags 2.13.2",
- "indexmap",
- "log",
- "serde",
- "serde_derive",
- "serde_json",
- "wasm-encoder 0.247.0",
- "wasm-metadata 0.247.0",
- "wasmparser 0.247.0",
- "wit-parser 0.247.0",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
 ]
 
 [[package]]
 name = "wit-parser"
-version = "0.236.1"
+version = "0.254.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16e4833a20cd6e85d6abfea0e63a399472d6f88c6262957c17f546879a80ba15"
-dependencies = [
- "anyhow",
- "id-arena",
- "indexmap",
- "log",
- "semver",
- "serde",
- "serde_derive",
- "serde_json",
- "unicode-xid",
- "wasmparser 0.236.1",
-]
-
-[[package]]
-name = "wit-parser"
-version = "0.239.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55c92c939d667b7bf0c6bf2d1f67196529758f99a2a45a3355cc56964fd5315d"
-dependencies = [
- "anyhow",
- "id-arena",
- "indexmap",
- "log",
- "semver",
- "serde",
- "serde_derive",
- "serde_json",
- "unicode-xid",
- "wasmparser 0.239.0",
-]
-
-[[package]]
-name = "wit-parser"
-version = "0.247.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ffe4064318cdf3c08cb99343b44c039fcefe61ccdf58aa9975285f13d74d1fc"
+checksum = "22672d61bfb9df46a16b46ce38522293aee1cc4749fc84a3464ce4083b3d5fd6"
 dependencies = [
  "anyhow",
  "hashbrown 0.17.1",
@@ -5299,8 +5218,8 @@ dependencies = [
  "serde",
  "serde_derive",
  "serde_json",
- "unicode-xid",
- "wasmparser 0.247.0",
+ "unicode-ident",
+ "wasmparser",
 ]
 
 [[package]]
diff --git a/crates/horizon-mod-sdk/Cargo.toml b/crates/horizon-mod-sdk/Cargo.toml
index df223b28c..899fb555a 100644
--- a/crates/horizon-mod-sdk/Cargo.toml
+++ b/crates/horizon-mod-sdk/Cargo.toml
@@ -7,7 +7,7 @@ rust-version = "1.85"
 description = "Write Horizon mods in Rust: WebAssembly components for the horizon:mod world (docs/mods.md)"
 
 [dependencies]
-wit-bindgen = { version = "0.57.1", default-features = false, features = ["macros", "realloc"] }
+wit-bindgen = { version = "0.60.0", default-features = false, features = ["macros", "realloc"] }
 
 [lints]
 workspace = true
diff --git a/crates/horizon-mods/Cargo.toml b/crates/horizon-mods/Cargo.toml
index 8db24ac35..d44648691 100644
--- a/crates/horizon-mods/Cargo.toml
+++ b/crates/horizon-mods/Cargo.toml
@@ -3,7 +3,7 @@ name = "horizon-mods"
 version = "0.1.0"
 edition.workspace = true
 license.workspace = true
-rust-version = "1.86"
+rust-version = "1.95"
 description = "Horizon's mod runtime: sandboxed WebAssembly components (docs/mods.md)"
 
 [dependencies]
@@ -12,11 +12,11 @@ serde_json = "1"
 toml = "1.1.6"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 log = "0.4"
-# The 36 LTS line: security fixes until August 2027, and it builds on the client's Rust.
-wasmtime = { version = "36.0.18", default-features = false, features = ["runtime", "cranelift", "component-model", "std"], optional = true }
+# The 48 LTS line: security fixes until August 2028, on the same wasm-tools (0.254) as wit-component and the SDK's wit-bindgen.
+wasmtime = { version = "48.0.7", default-features = false, features = ["runtime", "cranelift", "component-model", "std"], optional = true }
 # Turns a mod's core module into a component (cargo horizon-mod build, the tests).
-wit-component = { version = "0.239", optional = true }
-wit-parser = { version = "0.239", optional = true }
+wit-component = { version = "0.254", optional = true }
+wit-parser = { version = "0.254", optional = true }
 
 [features]
 default = ["runtime"]
diff --git a/docs/mods.md b/docs/mods.md
index 4b356d336..6aef6295a 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -14,7 +14,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
-| Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
+| Runtime | `crates/horizon-mods` | wasmtime 48 LTS, component model |
 | Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run` |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
 | Launcher mod browser (Modrinth, CurseForge with a key) | [mod-browser.md](mod-browser.md) | resource packs, shader packs, modpacks |
@@ -130,8 +130,10 @@ There is no file, socket, process or raw-input interface, on purpose.
 | native `cdylib` plugins | none | no: per OS and arch, unstable Rust ABI | yes | none | unsafe for players |
 | an embedded JVM | none per mod | yes | Java | 100+ MB, seconds of startup | see the research |
 
-wasmtime 36 is a long-term-support line (security fixes until August 2027)
-that builds on the client's Rust 1.90. Only its `runtime`, `cranelift`,
+wasmtime 48 is a long-term-support line (security fixes until August 2028)
+and needs Rust 1.95. It reads WebAssembly with the same wasm-tools release
+(0.254) as the `wit-component` that packs mods and the SDK's `wit-bindgen`, so
+the build carries one copy of them. Only its `runtime`, `cranelift`,
 `component-model` and `std` features are on: no WASI, no async, no GC
 proposal, no profiling. Its cranelift backend generates native code for x86-64
 and ARM64 on Windows, macOS and Linux, which is why one `.hmod` serves them

From 787c3a2f19e52cdbd63069a29a47e1a6507b6d77 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 21:20:34 +0200
Subject: [PATCH 002/270] Website: /mods, Horizon's registry of mods, modpacks
 and resource packs

The list (search, a filter per kind) and a page per project: what a mod
may do in the game's own words, Signed or Unsigned, how to install it
from the launcher, the CLI or by hand, its file, SHA-256 and versions,
and links to its source, its registry entry and the report form. Baked
from the published index at build time (HORIZON_MOD_INDEX for a test
index) and refreshed by the page; Caddy serves /mods/<id> from its baked
page, else the list page, which shows a project published since.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 website/Caddyfile         |  12 ++++-
 website/README.md         |   7 ++-
 website/build.mjs         |  71 +++++++++++++++++++++---
 website/src/mods-page.js  |  66 +++++++++++++++++++++++
 website/src/mods.html     |  37 +++++++++++++
 website/src/mods.js       | 110 ++++++++++++++++++++++++++++++++++++++
 website/src/mods.test.mjs |  42 +++++++++++++++
 website/src/style.css     |  48 +++++++++++++++++
 8 files changed, 383 insertions(+), 10 deletions(-)
 create mode 100644 website/src/mods-page.js
 create mode 100644 website/src/mods.html
 create mode 100644 website/src/mods.js
 create mode 100644 website/src/mods.test.mjs

diff --git a/website/Caddyfile b/website/Caddyfile
index 1571566ad..60554fd20 100644
--- a/website/Caddyfile
+++ b/website/Caddyfile
@@ -20,7 +20,7 @@
 		Referrer-Policy strict-origin-when-cross-origin
 		X-Frame-Options DENY
 		Permissions-Policy "interest-cohort=(), browsing-topics=(), camera=(), microphone=(), geolocation=()"
-		Content-Security-Policy "default-src 'self'; script-src 'self' {$CSP_SCRIPT}; style-src 'self' {$CSP_STYLE}; img-src 'self' data: https://avatars.githubusercontent.com; font-src 'self'; connect-src 'self' https://api.github.com https://raw.githubusercontent.com https://telemetry.playhorizon.dev; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
+		Content-Security-Policy "default-src 'self'; script-src 'self' {$CSP_SCRIPT}; style-src 'self' {$CSP_STYLE}; img-src 'self' data: https://avatars.githubusercontent.com https://ludovic111.github.io; font-src 'self'; connect-src 'self' https://api.github.com https://raw.githubusercontent.com https://telemetry.playhorizon.dev https://ludovic111.github.io; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
 		-Server
 	}
 	@assets path /assets/*
@@ -35,7 +35,15 @@
 	rewrite /benchmarks /benchmarks.html
 	@doc path_regexp doc ^/docs/([a-z-]+)$
 	rewrite @doc /docs/{re.doc.1}.html
-	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /docs /docs/* /sitemap.xml
+	# The registry: /mods, and /mods/<id> baked at build time, else the list page, whose script shows a project
+	# published since.
+	rewrite /mods /mods.html
+	@mod {
+		path_regexp ^/mods/[a-z0-9_]+$
+		file {path}.html /mods.html
+	}
+	rewrite @mod {file_match.relative}
+	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /docs /docs/* /mods /mods.html /mods/* /sitemap.xml
 	header @pages Cache-Control "no-cache"
 	@legal path /LEGAL.md /fonts/*.txt
 	header @legal Content-Type "text/plain; charset=utf-8"
diff --git a/website/README.md b/website/README.md
index 8ac6e3910..52e26ec61 100644
--- a/website/README.md
+++ b/website/README.md
@@ -22,12 +22,14 @@ src/404.html       the not-found page
 src/privacy.html   what the launcher can send when players allow it, retention, deletion (/privacy)
 src/releases.html  every release, newest first, with what it adds and fixes, its notes and downloads (/releases)
 src/benchmarks.html Horizon against vanilla 26.3 on our machines, the hardware picker, players' results (/benchmarks)
+src/mods.html      the registry's list (/mods) and a page per project (/mods/<id>), one template
 src/docs.html      the template of every documentation page (/docs/...), with its left navigation
 src/tokens.css     the design tokens, generated from crates/horizon-theme (do not edit)
 src/style.css      every style, on top of the tokens
 src/main.js        the home page: download buttons, recent releases, links, contributors, nav, tabs, lightbox, motion
 src/chrome.js      the light/dark switch, the phone menu and GitHub fetching, shared by the pages
 src/releases-page.js  the Releases page: the channel filter and the refresh from GitHub
+src/mods.js        the registry's markup (list, project page), shared by build and page; mods-page.js: the filter, the search, the refresh
 src/benchmarks-page.js  the Benchmarks page: players' results from the telemetry server, the picker
 src/bench.js       the Benchmarks tables, shared by build and page
 src/hardware.js    the spec table estimates use (GPU TFLOPS and bandwidth, CPU single-thread score)
@@ -48,14 +50,15 @@ shots/             (gitignored) full-page screenshots at 360–1920 px, a 1250×
 
 ## What comes from where
 
-- **Built in** (`build.mjs`): the parity table, its score, harness count and audit date,
+- **Built in** (`build.mjs`): Horizon's registry (`/mods`, one page per project) from the index ludovic111/horizon-mods
+  publishes (`HORIZON_MOD_INDEX=<file>` builds from a test index; docs/api/mod-index.md); the parity table, its score, harness count and audit date,
   all from `README.md`; the documentation pages (`/docs`) from `website/docs/`; the Discord and Sponsor links from
   `launcher/links.json`; the latest releases and the contributors (`/repos/ludovic111/horizon/contributors`,
   bots left out, the owner first), when GitHub answers; without an answer the build still succeeds and
   the Contributors block and its menu entries stay hidden until the page loads them. Locally these come from
   the checkout; on Railway, which builds only this folder, from `main` on GitHub. The build
   fails if the README has no parity table, so a broken README never deploys.
-- **Fetched by the page**: the releases (the download button picks the newest
+- **Fetched by the page**: the registry's index (a project merged after the build shows at once), the releases (the download button picks the newest
   `launcher-v*` release's asset for the visitor's OS, the home page lists the newest game releases, and
   the Releases page reloads its list when GitHub has a newer release), players' benchmark results
   (`GET https://telemetry.playhorizon.dev/v1/benchmarks/summary`, 3-second timeout), the contributors (avatars come from `avatars.githubusercontent.com`),
diff --git a/website/build.mjs b/website/build.mjs
index 781e838bb..0a813063b 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -16,6 +16,7 @@ import { machinesHtml, playersHtml } from "./src/bench.js";
 import { CPUS, GPUS, singleThread } from "./src/hardware.js";
 import { isGame, isLauncher, launcherVersion, newestFirst } from "./src/versions.js";
 import { contributorsFrom, contributorsHtml } from "./src/contributors.js";
+import { INDEX_URL, KINDS, SUBMIT, listHtml, projectHtml, readIndex } from "./src/mods.js";
 
 const site = dirname(fileURLToPath(import.meta.url));
 const dist = join(site, "dist");
@@ -41,6 +42,21 @@ try {
   console.warn(`links.json: ${e.message}; using the built-in links`);
 }
 
+// Horizon's registry (/mods): the index its repository publishes, or HORIZON_MOD_INDEX (a file or an address) to
+// try a test registry. Without an answer the pages are built empty and load the index themselves.
+let modProjects = [];
+let modIndex = null;
+try {
+  const from = process.env.HORIZON_MOD_INDEX || INDEX_URL;
+  const text = from.startsWith("https://")
+    ? await fetch(from, { signal: AbortSignal.timeout(15000) }).then((r) => (r.ok ? r.text() : Promise.reject(new Error(`${r.status}`))))
+    : await readFile(from, "utf8");
+  modIndex = JSON.parse(text);
+  modProjects = readIndex(modIndex) ?? (console.warn("mod index: a schema this site doesn't read"), []);
+} catch (e) {
+  console.warn(`mod index: ${e.message}; the pages will load it themselves`);
+}
+
 // An optional token (a Railway variable, or `gh auth token` locally) lifts the rate limit.
 const githubHeaders = { Accept: "application/vnd.github+json", ...(process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}) };
 // Every release (the Releases page lists them all), a page of 100 at a time.
@@ -170,7 +186,7 @@ await writeFile(join(dist, "favicon.ico"), Buffer.concat([ico, png32]));
 const names = {};
 const rewrite = (code) => code.replace(/"\.\/(\w+\.js)"/g, (all, file) => (names[file] ? `"./${names[file]}"` : all));
 // Dependencies before what imports them.
-const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "main.js", "releases-page.js", "benchmarks-page.js"];
+const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "main.js", "releases-page.js", "benchmarks-page.js", "mods.js", "mods-page.js"];
 for (const file of modules) {
   const code = rewrite(await readFile(join(site, "src", file), "utf8"));
   names[file] = `${file.replace(".js", "")}.${fingerprint(code)}.js`;
@@ -202,7 +218,7 @@ const baked = {
 const unavailable = `<p class="lede">The release notes could not be loaded here.</p><a class="button secondary" href="https://github.com/${REPO}/releases">Read them on GitHub</a>`;
 
 // The top bar and the footer of the pages beside the home page (Releases, Benchmarks).
-const navLinks = [["/#about", "About"], ["/releases", "Releases"], ["/benchmarks", "Benchmarks"], ["/docs/", "Docs"]];
+const navLinks = [["/#about", "About"], ["/mods", "Mods"], ["/releases", "Releases"], ["/benchmarks", "Benchmarks"], ["/docs/", "Docs"]];
 const siteNav = (current) => `    <header class="nav is-scrolled" id="top">
       <div class="nav-inner">
         <a class="nav-mark" href="/" aria-label="Horizon, home"><svg class="mark" viewBox="0 0 16 16" aria-hidden="true"><path class="mark-stem" d="M4 3h2v4H4zM10 3h2v4h-2z"/><path class="mark-low" d="M4 8h2v4H4zM10 8h2v4h-2z"/><path class="mark-line" d="M1 7h14v1H1z"/></svg>Horizon</a>
@@ -231,7 +247,7 @@ const siteFooter = `    <footer class="footer">
       <div class="container">
         <div class="footer-bar">
           <span class="footer-mark">Made in the open, in Rust.</span>
-          <nav class="footer-links" aria-label="Elsewhere"><a href="/">Home</a><a href="/releases">Releases</a><a href="/benchmarks">Benchmarks</a><a href="/docs/">Docs</a><a href="https://github.com/${REPO}">GitHub</a><a href="/privacy">Privacy</a><a href="/LEGAL.md">Assets</a></nav>
+          <nav class="footer-links" aria-label="Elsewhere"><a href="/">Home</a><a href="/mods">Mods</a><a href="/releases">Releases</a><a href="/benchmarks">Benchmarks</a><a href="/docs/">Docs</a><a href="https://github.com/${REPO}">GitHub</a><a href="/privacy">Privacy</a><a href="/LEGAL.md">Assets</a></nav>
         </div>
       </div>
       <p class="footer-word" aria-hidden="true">horizon</p>
@@ -366,6 +382,49 @@ for (const page of pages) {
   html = html.replace(/href="\/(favicon\.svg|favicon-32\.png|apple-touch-icon\.png)"/g, (all, icon) => `href="/${icon}?v=${iconVersions[icon]}"`);
   await writeFile(join(dist, page), html);
 }
+// The registry: /mods (the list) and /mods/<id> (a page per project), one template.
+const modsTemplate = await readFile(join(site, "src", "mods.html"), "utf8");
+const modsList = `        <p class="kicker"><span>Mods</span>Made for Horizon, reviewed</p>
+        <h1 class="display page-title">Horizon mods</h1>
+        <p class="lede">Mods, modpacks and resource packs made for Horizon. Each one was reviewed before it was listed, and the launcher checks every file before it installs it. Mods run in a sandbox and can only do what their page says.</p>
+        <p class="mod-actions"><a class="button primary" href="${SUBMIT}">Submit yours</a> <a class="button secondary" href="/docs/mods">Make a mod</a></p>
+        <div class="mod-tools">
+          <input class="mod-search" id="mod-search" type="search" placeholder="Search" aria-label="Search the registry" autocomplete="off">
+          <div class="release-filter" role="group" aria-label="Show">
+            <button type="button" class="button secondary small" data-kind-filter="all" aria-pressed="true">All</button>
+${KINDS.map(([k, label]) => `            <button type="button" class="button secondary small" data-kind-filter="${k}" aria-pressed="false">${label}</button>`).join("\n")}
+          </div>
+        </div>
+        <p class="meta release-count" data-mod-count>${modProjects.length} of ${modProjects.length}</p>
+        <div class="mod-list" id="mod-list" aria-live="polite">
+${listHtml(modProjects)}
+        </div>`;
+const modPages = [
+  { file: "mods.html", path: "/mods", title: "Mods", description: "Mods, modpacks and resource packs made for Horizon, reviewed, each with what it may do and how to install it.", main: modsList },
+  ...modProjects.map((p) => ({ file: `mods/${p.id}.html`, path: `/mods/${p.id}`, title: p.name, description: p.summary || p.name, main: projectHtml(p) })),
+];
+await mkdir(join(dist, "mods"), { recursive: true });
+const modsData = JSON.stringify(modIndex && modProjects.length ? { schema: modIndex.schema, projects: modProjects } : null).replace(/</g, "\\u003c");
+for (const page of modPages) {
+  const own = {
+    ...values,
+    SITE_NAV: siteNav("/mods"),
+    MODS_TITLE: escape(page.title),
+    MODS_DESCRIPTION: escape(page.description),
+    MODS_PATH: page.path,
+    MODS_JS: `/assets/${names["mods-page.js"]}`,
+    MODS_MAIN: page.main,
+    MODS_DATA: modsData,
+    MODS_BAKED_AT: escape(modIndex?.generated || ""),
+  };
+  let html = modsTemplate.replace(/\{\{(\w+)\}\}/g, (all, key) => {
+    if (!(key in own)) throw new Error(`mods.html: unknown placeholder ${all}`);
+    return own[key];
+  });
+  html = html.replace(/href="\/(favicon\.svg|favicon-32\.png|apple-touch-icon\.png)"/g, (all, icon) => `href="/${icon}?v=${iconVersions[icon]}"`);
+  await writeFile(join(dist, page.file), html);
+}
+
 const docTemplate = await readFile(join(site, "src", "docs.html"), "utf8");
 for (const { file, values: own } of docPages) {
   let html = docTemplate.replace(/\{\{(\w+)\}\}/g, (all, key) => {
@@ -380,12 +439,12 @@ for (const { file, values: own } of docPages) {
 
 // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS
 // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash.
-const allHtml = (await Promise.all([...pages, ...docPageFiles].map((page) => readFile(join(dist, page), "utf8")))).join("\n");
+const allHtml = (await Promise.all([...pages, ...docPageFiles, ...modPages.map((p) => p.file)].map((page) => readFile(join(dist, page), "utf8")))).join("\n");
 const hashes = (re) => [...new Set([...allHtml.matchAll(re)].map((m) => `'sha256-${createHash("sha256").update(m[1]).digest("base64")}'`))].join(" ");
 await writeFile(join(dist, ".csp-script"), hashes(/<script>([\s\S]*?)<\/script>/g));
 await writeFile(join(dist, ".csp-style"), hashes(/<style>([\s\S]*?)<\/style>/g));
 
-const urls = ["/", "/releases", "/benchmarks", ...docs.map((d) => d.path), "/privacy"];
+const urls = ["/", "/mods", ...modPages.slice(1).map((p) => p.path), "/releases", "/benchmarks", ...docs.map((d) => d.path), "/privacy"];
 await writeFile(
   join(dist, "sitemap.xml"),
   `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.map((u) => `  <url><loc>https://playhorizon.dev${u}</loc></url>`).join("\n")}\n</urlset>\n`,
@@ -393,5 +452,5 @@ await writeFile(
 
 console.log(
   `built dist/ from ${readmeFrom}: ${body.length} subsystems, ${percent}, ${harnesses} harnesses, ` +
-    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages`,
+    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages, ${modProjects.length} registry projects`,
 );
diff --git a/website/src/mods-page.js b/website/src/mods-page.js
new file mode 100644
index 000000000..121ba8067
--- /dev/null
+++ b/website/src/mods-page.js
@@ -0,0 +1,66 @@
+// /mods and /mods/<id>: the registry's list (kind filter, search) and a project's page. The pages are baked from
+// the index at build time; this fetches the published index again so a project merged since shows at once.
+import { INDEX_URL, KINDS, listHtml, matches, projectHtml, readIndex } from "./mods.js";
+import { cached, setUpMenu, setUpTheme } from "./chrome.js";
+
+const root = document.getElementById("mods");
+const baked = readIndex(JSON.parse(document.getElementById("mods-index").textContent || "null")) || [];
+let projects = baked;
+let kind = "all";
+let text = "";
+
+const id = (location.pathname.match(/^\/mods\/([a-z0-9_]+)\/?$/) || [])[1];
+
+function showList() {
+  const list = root.querySelector("#mod-list");
+  if (!list) return;
+  const shown = projects.filter((p) => matches(p, kind, text));
+  list.innerHTML = listHtml(shown);
+  root.querySelector("[data-mod-count]").textContent = `${shown.length} of ${projects.length}`;
+  root.querySelectorAll("[data-kind-filter]").forEach((b) => b.setAttribute("aria-pressed", String(b.dataset.kindFilter === kind)));
+}
+
+function showProject() {
+  const p = projects.find((x) => x.id === id);
+  const page = root.querySelector(".mod-page, .mod-missing");
+  if (!page) return;
+  if (p) {
+    page.outerHTML = projectHtml(p);
+    document.title = `${p.name} · Horizon`;
+  } else {
+    page.outerHTML = `<div class="mod-missing"><h1 class="display page-title">Not in the registry</h1><p class="lede">No project is called ${id} here. It may not be published yet, or it was taken down.</p><a class="button secondary" href="/mods">Every mod</a></div>`;
+  }
+}
+
+function render() {
+  if (id) showProject();
+  else showList();
+}
+
+if (!id) {
+  root.querySelectorAll("[data-kind-filter]").forEach((b) =>
+    b.addEventListener("click", () => {
+      kind = b.dataset.kindFilter;
+      showList();
+    }),
+  );
+  root.querySelector("#mod-search")?.addEventListener("input", (e) => {
+    text = e.target.value;
+    showList();
+  });
+  const wanted = new URLSearchParams(location.search).get("kind");
+  if (KINDS.some(([k]) => k === wanted)) kind = wanted;
+}
+
+setUpTheme();
+setUpMenu();
+render();
+cached("horizon:mod-index", () => fetch(INDEX_URL).then((r) => (r.ok ? r.json() : Promise.reject(new Error(`${r.status}`)))))
+  .then((index) => {
+    const fresh = readIndex(index);
+    if (fresh) {
+      projects = fresh;
+      render();
+    }
+  })
+  .catch(() => {});
diff --git a/website/src/mods.html b/website/src/mods.html
new file mode 100644
index 000000000..0c0e5eea2
--- /dev/null
+++ b/website/src/mods.html
@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+    <title>{{MODS_TITLE}} · Horizon</title>
+    <meta name="description" content="{{MODS_DESCRIPTION}}">
+    <meta name="theme-color" content="#ece7f7" media="(prefers-color-scheme: light)">
+    <meta name="theme-color" content="#0f0d17" media="(prefers-color-scheme: dark)">
+    <meta name="color-scheme" content="light dark">
+    <link rel="canonical" href="https://playhorizon.dev{{MODS_PATH}}">
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="icon" href="/favicon-32.png" sizes="32x32" type="image/png">
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="Horizon">
+    <meta property="og:title" content="{{MODS_TITLE}} · Horizon">
+    <meta property="og:description" content="{{MODS_DESCRIPTION}}">
+    <meta property="og:url" content="https://playhorizon.dev{{MODS_PATH}}">
+    <meta property="og:image" content="https://playhorizon.dev/og.png">
+    <style>{{STYLE}}</style>
+    <script>document.documentElement.classList.replace("no-js", "js"); try { const t = localStorage.getItem("theme"); if (t === "light" || t === "dark") document.documentElement.dataset.theme = t } catch {}</script>
+    <script type="module" src="{{MODS_JS}}"></script>
+  </head>
+  <body class="subpage">
+    <a class="skip" href="#main">Skip to the content</a>
+{{SITE_NAV}}
+    <main id="main" class="section page-main">
+      <div class="container" id="mods" data-baked="{{MODS_BAKED_AT}}">
+{{MODS_MAIN}}
+        <p class="disclaimer">Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.</p>
+      </div>
+    </main>
+{{SITE_FOOTER}}
+    <script type="application/json" id="mods-index">{{MODS_DATA}}</script>
+  </body>
+</html>
diff --git a/website/src/mods.js b/website/src/mods.js
new file mode 100644
index 000000000..236a376ab
--- /dev/null
+++ b/website/src/mods.js
@@ -0,0 +1,110 @@
+// Horizon's registry on the site (/mods): the list with its kind filter and search, and a page per project.
+// Shared by build.mjs (baked into the pages) and mods-page.js (refreshed from the published index).
+// The index's format is docs/api/mod-index.md in the repository.
+import { markdown, escape } from "./markdown.js";
+
+export const INDEX_URL = "https://ludovic111.github.io/horizon-mods/index.json";
+const REGISTRY = "https://github.com/ludovic111/horizon-mods";
+export const SUBMIT = `${REGISTRY}#submit`;
+export const SCHEMA = 1;
+
+// The kinds the site shows, in the filter's order. Kinds a newer index adds are left out until the site knows them.
+export const KINDS = [
+  ["mod", "Mods"],
+  ["modpack", "Modpacks"],
+  ["resourcepack", "Resource packs"],
+  ["shader", "Shader packs"],
+];
+const KIND_NAMES = { mod: "Mod", modpack: "Modpack", resourcepack: "Resource pack", shader: "Shader pack" };
+
+// What a capability lets a mod do, as the game and the launcher say it (horizon_mods::Capability::describe).
+export const CAPABILITIES = {
+  "game-read": "see your position, health and the time",
+  chat: "show you chat messages",
+  hud: "draw text on your screen",
+  storage: "save its own settings to disk",
+  registries: "add blocks and items to your worlds",
+};
+
+// The index's projects this site can show, or null when it isn't an index it reads.
+export function readIndex(index) {
+  if (!index || typeof index !== "object" || index.schema > SCHEMA || !Array.isArray(index.projects)) return null;
+  const known = new Set(KINDS.map(([k]) => k));
+  return index.projects.filter((p) => known.has(p.kind) && /^[a-z0-9_]{1,64}$/.test(p.id) && p.versions?.length);
+}
+
+const https = (url) => (typeof url === "string" && url.startsWith("https://") ? url : "");
+const size = (bytes) => (bytes >= 1 << 20 ? `${(bytes / (1 << 20)).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`);
+const trust = (p) =>
+  p.key ? `<span class="badge badge-signed" title="Every file is signed with the author's key">Signed</span>` : `<span class="badge badge-unsigned" title="The file is pinned by its checksum, not signed">Unsigned</span>`;
+const initial = (p) => escape((p.name || p.id).trim().charAt(0).toUpperCase());
+const icon = (p) =>
+  https(p.icon) ? `<img class="mod-icon" src="${escape(p.icon)}" alt="" width="48" height="48" loading="lazy">` : `<span class="mod-icon" aria-hidden="true">${initial(p)}</span>`;
+
+export function matches(p, kind, text) {
+  if (kind !== "all" && p.kind !== kind) return false;
+  const hay = `${p.id} ${p.name} ${p.summary} ${(p.authors || []).join(" ")}`.toLowerCase();
+  return text.toLowerCase().split(/\s+/).filter(Boolean).every((w) => hay.includes(w));
+}
+
+// The list: a row per project, newest version and kind on the right.
+export function listHtml(projects) {
+  if (!projects.length) return `<p class="lede mod-empty">Nothing here yet. <a href="${SUBMIT}">Submit yours</a>.</p>`;
+  return projects
+    .map(
+      (p) => `<a class="mod-row" href="/mods/${p.id}" data-kind="${escape(p.kind)}" data-search="${escape(`${p.id} ${p.name} ${p.summary} ${(p.authors || []).join(" ")}`.toLowerCase())}">
+  ${icon(p)}
+  <span class="mod-text"><span class="mod-name">${escape(p.name)}</span><span class="mod-summary">${escape(p.summary || "")}</span></span>
+  <span class="mod-side"><span class="badge">${escape(KIND_NAMES[p.kind] || p.kind)}</span><span class="mod-version">${escape(p.versions[0].version)} · ${escape((p.authors || []).join(", "))}</span></span>
+</a>`,
+    )
+    .join("\n");
+}
+
+function installHtml(p, v) {
+  const file = escape(v.file.name);
+  const cli = `horizon-launcher mods install --source horizon ${p.id}`;
+  const where = {
+    mod: `put it in <code>horizon-mods/</code> beside <code>options.txt</code> in the game folder, then turn it on in the game: Options &gt; Mods`,
+    resourcepack: `put it in <code>resourcepacks/</code> beside <code>options.txt</code>, then turn it on in Options &gt; Resource Packs`,
+    modpack: `a modpack lists registry mods: install them one by one, or wait for the launcher to install modpacks`,
+    shader: `Horizon's own shader packs aren't installed yet`,
+  }[p.kind];
+  return `<ol class="mod-steps">
+  <li>In the launcher: <strong>Mods</strong>, pick <strong>Horizon</strong> beside Modrinth, find ${escape(p.name)} and press <strong>Install</strong>. It checks the file's checksum${p.key ? " and signature" : ""} first.</li>
+  <li>From a terminal or an agent: <code>${escape(cli)}</code></li>
+  <li>By hand: download <a href="${escape(https(v.file.url))}">${file}</a> (${size(v.file.size)}), check its SHA-256 below, and ${where}.</li>
+</ol>`;
+}
+
+// One project's page.
+export function projectHtml(p) {
+  const v = p.versions[0];
+  const caps = v.capabilities || [];
+  const capsHtml = caps.length
+    ? `<ul class="mod-caps">${caps.map((c) => `<li>May ${escape(CAPABILITIES[c] || c)}</li>`).join("")}</ul>`
+    : `<p>It asks for nothing beyond writing its own log.</p>`;
+  const requires = (v.requires || []).length
+    ? `<h2 class="heading">Its mods</h2><ul class="mod-caps">${v.requires.map((r) => `<li><a href="/mods/${escape(r.id)}">${escape(r.id)}</a> ${escape(r.version)}</li>`).join("")}</ul>`
+    : "";
+  const versions = p.versions
+    .map((x) => `<li><strong>${escape(x.version)}</strong> <span class="mod-version">${escape(x.published || "")} · for ${escape(x.game)}${x.api ? ` · API ${escape(x.api)}` : ""}</span>${x.changelog ? `<div class="prose">${markdown(x.changelog)}</div>` : ""}</li>`)
+    .join("");
+  return `<article class="mod-page" data-id="${escape(p.id)}">
+  <header class="mod-head">${icon(p)}<div><p class="kicker"><span>${escape(KIND_NAMES[p.kind] || p.kind)}</span>${escape((p.authors || []).join(", "))}</p>
+  <h1 class="display page-title">${escape(p.name)}</h1><p class="lede">${escape(p.summary || "")}</p>
+  <p class="mod-badges">${trust(p)} <span class="badge">${escape(p.license)}</span> <span class="badge">${escape(v.version)}</span>${v.side ? ` <span class="badge">${escape(v.side)}</span>` : ""}</p></div></header>
+  ${p.description ? `<div class="prose">${markdown(p.description)}</div>` : ""}
+  ${p.kind === "mod" ? `<h2 class="heading">What it may do</h2>${capsHtml}<p class="meta">Mods run in a sandbox with no file, network or clock access. The game refuses a mod whose code uses more than this list.</p>` : ""}
+  ${requires}
+  <h2 class="heading">Install</h2>
+  ${installHtml(p, v)}
+  <h2 class="heading">File</h2>
+  <dl class="mod-file"><dt>Name</dt><dd><a href="${escape(https(v.file.url))}">${escape(v.file.name)}</a></dd><dt>Size</dt><dd>${size(v.file.size)}</dd><dt>SHA-256</dt><dd><code>${escape(v.file.sha256)}</code></dd>${p.key ? `<dt>Signing key</dt><dd><code>${escape(p.key)}</code></dd>` : ""}</dl>
+  <h2 class="heading">Versions</h2>
+  <ul class="mod-versions">${versions}</ul>
+  <p class="mod-links">${https(p.source) ? `<a class="link-arrow" href="${escape(p.source)}">Source code<span aria-hidden="true">→</span></a>` : ""}
+  <a class="link-arrow" href="${REGISTRY}/blob/main/mods/${escape(p.id)}.toml">Its entry in the registry<span aria-hidden="true">→</span></a>
+  <a class="link-arrow" href="${REGISTRY}/issues/new?template=report.yml&amp;title=${escape(p.id)}">Report it<span aria-hidden="true">→</span></a></p>
+</article>`;
+}
diff --git a/website/src/mods.test.mjs b/website/src/mods.test.mjs
new file mode 100644
index 000000000..8dc5c0867
--- /dev/null
+++ b/website/src/mods.test.mjs
@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { CAPABILITIES, listHtml, matches, projectHtml, readIndex } from "./mods.js";
+
+const project = (over = {}) => ({
+  id: "coords_hud", kind: "mod", name: "Coordinates HUD", summary: "Where you are.", authors: ["Horizon"],
+  license: "MIT", source: "https://example.org/src",
+  versions: [{ version: "0.1.0", api: "0.1", side: "client", capabilities: ["game-read", "hud"], game: "26.3",
+    file: { name: "coords_hud-0.1.0.hmod", url: "https://github.com/ludovic111/horizon-mods/releases/download/x/coords_hud-0.1.0.hmod", size: 438, sha256: "e".repeat(64) } }],
+  ...over,
+});
+
+test("reads schema 1, keeps the kinds it knows and refuses a newer schema", () => {
+  const index = { schema: 1, projects: [project(), project({ id: "map", kind: "world" }), project({ id: "Bad id" })] };
+  assert.deepEqual(readIndex(index).map((p) => p.id), ["coords_hud"]);
+  assert.equal(readIndex({ schema: 2, projects: [project()] }), null);
+  assert.equal(readIndex(null), null);
+});
+
+test("filters by kind and every word", () => {
+  const p = project();
+  assert.ok(matches(p, "all", "coordinates horizon"));
+  assert.ok(matches(p, "mod", ""));
+  assert.ok(!matches(p, "modpack", ""));
+  assert.ok(!matches(p, "all", "zoom"));
+});
+
+test("escapes what authors wrote and only links https addresses", () => {
+  const evil = project({ name: "<script>x</script>", source: "javascript:alert(1)", summary: '"><img src=x onerror=alert(1)>' });
+  const html = listHtml([evil]) + projectHtml(evil);
+  assert.ok(!html.includes("<script>x"));
+  assert.ok(!html.includes("<img src=x"));
+  assert.ok(!html.includes("javascript:"));
+});
+
+test("a mod's page says what it may do, as the game does", () => {
+  const html = projectHtml(project());
+  assert.ok(html.includes(`May ${CAPABILITIES["game-read"]}`));
+  assert.ok(html.includes("Unsigned"));
+  assert.ok(projectHtml(project({ key: "RWT" })).includes("Signed"));
+  assert.ok(html.includes("horizon-launcher mods install --source horizon coords_hud"));
+});
diff --git a/website/src/style.css b/website/src/style.css
index 323cd6e83..c67c9f8e4 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -741,3 +741,51 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
   .release-detail { padding-left: 0; margin-left: 0; }
   .machine { padding: 16px; }
 }
+
+/* The registry (/mods): a search and the kind filter, rows as panels, then a page per project. */
+.mod-actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 24px; }
+.mod-tools { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; margin-top: 32px; }
+.mod-tools .release-filter { margin-top: 0; }
+.mod-search {
+  height: 36px; min-width: min(320px, 100%); padding: 0 12px; font: var(--text-ui) / 1 var(--sans); color: var(--ink);
+  background: var(--well); border: var(--block-outline) solid var(--outline); border-radius: 0;
+}
+.mod-search:focus-visible { outline: 2px solid var(--accent); outline-offset: 0; }
+.mod-list { display: grid; gap: 8px; }
+.mod-row {
+  display: grid; grid-template-columns: 48px minmax(0, 1fr) auto; align-items: center; gap: 16px; padding: 14px 20px;
+  background: var(--panel); border: var(--block-outline) solid var(--outline); box-shadow: var(--panel-edges); color: var(--ink); text-decoration: none;
+}
+.mod-row:hover { background: var(--raised); }
+.mod-row:hover .mod-name { color: var(--accent); }
+.mod-icon {
+  display: grid; place-items: center; width: 48px; height: 48px; flex: none; image-rendering: pixelated;
+  font: 600 22px / 1 var(--pixel); color: var(--ink); background: var(--well); box-shadow: 0 0 0 var(--block-outline) var(--outline);
+}
+.mod-text { display: grid; gap: 4px; min-width: 0; }
+.mod-name { font: 500 var(--text-heading) / 1.2 var(--pixel); }
+.mod-summary { color: var(--muted); font-size: var(--text-ui); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mod-side { display: grid; justify-items: end; gap: 6px; }
+.mod-side .badge { margin-right: 0; }
+.mod-version { font: var(--text-micro) / 1.4 var(--mono); letter-spacing: var(--text-micro-tracking); color: var(--muted); }
+.mod-empty a { color: var(--accent); }
+.badge-signed { background: color-mix(in srgb, var(--success) 22%, var(--panel)); color: var(--ink); }
+.badge-unsigned { background: color-mix(in srgb, var(--warn) 24%, var(--panel)); color: var(--ink); }
+.mod-page { display: grid; gap: 16px; max-width: calc(var(--measure) + 240px); }
+.mod-page .heading { margin-top: 24px; }
+.mod-head { display: grid; grid-template-columns: 96px minmax(0, 1fr); gap: 24px; align-items: start; }
+.mod-head .mod-icon { width: 96px; height: 96px; font-size: 44px; }
+.mod-head .page-title { margin-top: 0; }
+.mod-badges { margin-top: 16px; }
+.mod-caps, .mod-steps, .mod-versions { display: grid; gap: 8px; padding-left: 20px; font-size: var(--text-ui); }
+.mod-caps li::marker, .mod-steps li::marker { color: var(--accent); }
+.mod-file { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 8px 16px; font-size: var(--text-ui); }
+.mod-file dt { color: var(--muted); }
+.mod-file code, .mod-steps code { font-family: var(--mono); font-size: 13px; overflow-wrap: anywhere; }
+.mod-links { display: flex; flex-wrap: wrap; gap: 24px; margin-top: 24px; }
+@media (max-width: 640px) {
+  .mod-row { grid-template-columns: 40px minmax(0, 1fr); }
+  .mod-side { grid-column: 2; justify-items: start; }
+  .mod-icon { width: 40px; height: 40px; }
+  .mod-head { grid-template-columns: 1fr; }
+}

From fb4897ec0922d20a209498ee4cc0a35c1b893a97 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:10:05 +0200
Subject: [PATCH 003/270] Website: /mods/submit, the registry's submission form

Sign in with GitHub through the registry's service (no scope), then send
the file and its page; the service checks the file, stages it and opens the
pull request, and the page links to it or says what to fix. A file named
<id>-<version>.<ext> fills in its kind, id and version. Shader packs are
listed and disabled until Horizon's own format exists. Caddy sends
/api/mods/* to REGISTRY_UPSTREAM (unset: the form says it isn't open), and
"Submit yours" now leads here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 website/Caddyfile          |  7 +++-
 website/README.md          |  6 ++-
 website/build.mjs          |  9 +++--
 website/src/mods-submit.js | 80 ++++++++++++++++++++++++++++++++++++++
 website/src/mods.js        | 67 ++++++++++++++++++++++++++++++-
 website/src/mods.test.mjs  | 15 ++++++-
 website/src/style.css      | 12 ++++++
 7 files changed, 187 insertions(+), 9 deletions(-)
 create mode 100644 website/src/mods-submit.js

diff --git a/website/Caddyfile b/website/Caddyfile
index 60554fd20..fb96e836d 100644
--- a/website/Caddyfile
+++ b/website/Caddyfile
@@ -35,7 +35,12 @@
 	rewrite /benchmarks /benchmarks.html
 	@doc path_regexp doc ^/docs/([a-z-]+)$
 	rewrite @doc /docs/{re.doc.1}.html
-	# The registry: /mods, and /mods/<id> baked at build time, else the list page, whose script shows a project
+	# The registry's submission service (crates/horizon-mod-registry), over Railway's private network. Unset, the
+	# form says it isn't open.
+	handle /api/mods/* {
+		reverse_proxy {$REGISTRY_UPSTREAM:127.0.0.1:9}
+	}
+	# The registry: /mods, /mods/submit and /mods/<id> baked at build time, else the list page, whose script shows a project
 	# published since.
 	rewrite /mods /mods.html
 	@mod {
diff --git a/website/README.md b/website/README.md
index 52e26ec61..2813ce6dd 100644
--- a/website/README.md
+++ b/website/README.md
@@ -29,7 +29,7 @@ src/style.css      every style, on top of the tokens
 src/main.js        the home page: download buttons, recent releases, links, contributors, nav, tabs, lightbox, motion
 src/chrome.js      the light/dark switch, the phone menu and GitHub fetching, shared by the pages
 src/releases-page.js  the Releases page: the channel filter and the refresh from GitHub
-src/mods.js        the registry's markup (list, project page), shared by build and page; mods-page.js: the filter, the search, the refresh
+src/mods.js        the registry's markup (list, project page, submit form), shared by build and page; mods-page.js: the filter, the search, the refresh; mods-submit.js: the form's sign-in and sending
 src/benchmarks-page.js  the Benchmarks page: players' results from the telemetry server, the picker
 src/bench.js       the Benchmarks tables, shared by build and page
 src/hardware.js    the spec table estimates use (GPU TFLOPS and bandwidth, CPU single-thread score)
@@ -110,7 +110,9 @@ a Caddy stage serves `dist/` on `$PORT` with compression, cache headers, a stric
 Content-Security-Policy and the 404 page. Its watch patterns also redeploy when the README
 or `launcher/links.json` change on main. No variables are needed; an optional
 `GITHUB_TOKEN` (read-only, public repos) lets the build bake the releases even when
-GitHub's anonymous rate limit is hit.
+GitHub's anonymous rate limit is hit. `REGISTRY_UPSTREAM`
+(`horizon-mod-registry.railway.internal:8080`) sends `/api/mods/*` to the registry's submission
+service (`crates/horizon-mod-registry`); unset, `/mods/submit` says the form isn't open.
 
 ## Rules the site keeps
 
diff --git a/website/build.mjs b/website/build.mjs
index 0a813063b..8a6e04abe 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -16,7 +16,7 @@ import { machinesHtml, playersHtml } from "./src/bench.js";
 import { CPUS, GPUS, singleThread } from "./src/hardware.js";
 import { isGame, isLauncher, launcherVersion, newestFirst } from "./src/versions.js";
 import { contributorsFrom, contributorsHtml } from "./src/contributors.js";
-import { INDEX_URL, KINDS, SUBMIT, listHtml, projectHtml, readIndex } from "./src/mods.js";
+import { INDEX_URL, KINDS, SUBMIT, listHtml, projectHtml, readIndex, submitHtml } from "./src/mods.js";
 
 const site = dirname(fileURLToPath(import.meta.url));
 const dist = join(site, "dist");
@@ -186,7 +186,7 @@ await writeFile(join(dist, "favicon.ico"), Buffer.concat([ico, png32]));
 const names = {};
 const rewrite = (code) => code.replace(/"\.\/(\w+\.js)"/g, (all, file) => (names[file] ? `"./${names[file]}"` : all));
 // Dependencies before what imports them.
-const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "main.js", "releases-page.js", "benchmarks-page.js", "mods.js", "mods-page.js"];
+const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "main.js", "releases-page.js", "benchmarks-page.js", "mods.js", "mods-page.js", "mods-submit.js"];
 for (const file of modules) {
   const code = rewrite(await readFile(join(site, "src", file), "utf8"));
   names[file] = `${file.replace(".js", "")}.${fingerprint(code)}.js`;
@@ -401,7 +401,8 @@ ${listHtml(modProjects)}
         </div>`;
 const modPages = [
   { file: "mods.html", path: "/mods", title: "Mods", description: "Mods, modpacks and resource packs made for Horizon, reviewed, each with what it may do and how to install it.", main: modsList },
-  ...modProjects.map((p) => ({ file: `mods/${p.id}.html`, path: `/mods/${p.id}`, title: p.name, description: p.summary || p.name, main: projectHtml(p) })),
+  { file: "mods/submit.html", path: "/mods/submit", title: "Submit to the registry", description: "Submit a mod, a modpack or a resource pack made for Horizon: it is checked, reviewed, then listed here and in the launcher.", main: submitHtml(), js: "mods-submit.js" },
+  ...modProjects.filter((p) => p.id !== "submit").map((p) => ({ file: `mods/${p.id}.html`, path: `/mods/${p.id}`, title: p.name, description: p.summary || p.name, main: projectHtml(p) })),
 ];
 await mkdir(join(dist, "mods"), { recursive: true });
 const modsData = JSON.stringify(modIndex && modProjects.length ? { schema: modIndex.schema, projects: modProjects } : null).replace(/</g, "\\u003c");
@@ -412,7 +413,7 @@ for (const page of modPages) {
     MODS_TITLE: escape(page.title),
     MODS_DESCRIPTION: escape(page.description),
     MODS_PATH: page.path,
-    MODS_JS: `/assets/${names["mods-page.js"]}`,
+    MODS_JS: `/assets/${names[page.js || "mods-page.js"]}`,
     MODS_MAIN: page.main,
     MODS_DATA: modsData,
     MODS_BAKED_AT: escape(modIndex?.generated || ""),
diff --git a/website/src/mods-submit.js b/website/src/mods-submit.js
new file mode 100644
index 000000000..c1024495b
--- /dev/null
+++ b/website/src/mods-submit.js
@@ -0,0 +1,80 @@
+// /mods/submit: signs in with GitHub through the registry's service, then sends the page and the file. The service
+// checks the file and answers with the pull request it opened, or with what to fix.
+import { API, entryFrom } from "./mods.js";
+import { setUpMenu, setUpTheme } from "./chrome.js";
+import { escape } from "./markdown.js";
+
+const auth = document.getElementById("submit-auth");
+const form = document.getElementById("submit-form");
+const result = document.getElementById("submit-result");
+let csrf = "";
+// The form's own controls by name (form.id and form.name are the form's attributes).
+const control = (name) => form.elements.namedItem(name);
+
+function signedOut(message) {
+  auth.innerHTML = `<p class="meta">${message}</p><p class="mod-actions"><a class="button primary" href="${API}/auth/login">Sign in with GitHub</a></p><p class="meta">It only reads your public profile: your GitHub name goes on the pull request and in the project's owners.</p>`;
+  form.hidden = true;
+}
+
+async function start() {
+  let me;
+  try {
+    const r = await fetch(`${API}/me`, { credentials: "same-origin" });
+    if (r.status === 401) return signedOut("Sign in to submit: reviewers and updates go through your GitHub account.");
+    if (!r.ok) throw new Error(String(r.status));
+    me = await r.json();
+  } catch {
+    auth.innerHTML = `<p class="meta">The form isn't open right now. You can <a href="https://github.com/ludovic111/horizon-mods">open a pull request by hand</a>.</p>`;
+    return;
+  }
+  csrf = me.csrf;
+  auth.innerHTML = `<p class="meta">Signed in as <strong>${escape(me.login)}</strong>. <button class="button ghost small" type="button" id="sign-out">Sign out</button></p>`;
+  document.getElementById("sign-out").addEventListener("click", async () => {
+    await fetch(`${API}/auth/logout`, { method: "POST", credentials: "same-origin" });
+    signedOut("Signed out.");
+  });
+  form.hidden = false;
+}
+
+// A file named <id>-<version>.<extension> fills in the two fields and the kind.
+form.querySelector("#f-file").addEventListener("change", (e) => {
+  const name = e.target.files[0]?.name || "";
+  const m = name.match(/^([a-z0-9_]{1,64})-([A-Za-z0-9][A-Za-z0-9._-]*)\.(hmod|hpack|zip)$/);
+  const kind = { hmod: "mod", hpack: "modpack", zip: "resourcepack" }[name.split(".").pop()];
+  if (kind) control("kind").value = kind;
+  if (m) {
+    if (!control("id").value) control("id").value = m[1];
+    if (!control("version").value) control("version").value = m[2];
+  }
+});
+
+form.addEventListener("submit", async (e) => {
+  e.preventDefault();
+  const send = form.querySelector("#f-send");
+  const values = Object.fromEntries(["id", "kind", "name", "summary", "description", "authors", "license", "source", "icon", "key", "version", "game", "changelog"].map((k) => [k, control(k).value]));
+  const sig = form.querySelector("#f-signature").files[0];
+  values.signature = sig ? await sig.text() : "";
+  const body = new FormData();
+  body.append("entry", JSON.stringify(entryFrom(values)));
+  body.append("file", form.querySelector("#f-file").files[0]);
+  send.disabled = true;
+  result.innerHTML = `<p class="meta">Checking the file and opening the pull request…</p>`;
+  try {
+    const r = await fetch(`${API}/submit`, { method: "POST", body, credentials: "same-origin", headers: { "X-CSRF-Token": csrf } });
+    const json = await r.json().catch(() => ({}));
+    if (r.ok && /^https:\/\/github\.com\//.test(json.pull_request || "")) {
+      result.innerHTML = `<p class="lede">Submitted. Follow the review in <a href="${escape(json.pull_request)}">its pull request</a>: the checks' report is there, and reviewers answer there.</p>`;
+      form.reset();
+    } else {
+      result.innerHTML = `<p class="mod-error">${escape(json.error || `The service answered ${r.status}.`)}</p>`;
+    }
+  } catch {
+    result.innerHTML = `<p class="mod-error">The service didn't answer. Try again in a minute.</p>`;
+  } finally {
+    send.disabled = false;
+  }
+});
+
+setUpTheme();
+setUpMenu();
+start();
diff --git a/website/src/mods.js b/website/src/mods.js
index 236a376ab..4819af374 100644
--- a/website/src/mods.js
+++ b/website/src/mods.js
@@ -5,7 +5,9 @@ import { markdown, escape } from "./markdown.js";
 
 export const INDEX_URL = "https://ludovic111.github.io/horizon-mods/index.json";
 const REGISTRY = "https://github.com/ludovic111/horizon-mods";
-export const SUBMIT = `${REGISTRY}#submit`;
+export const SUBMIT = "/mods/submit";
+// The submission form's service (crates/horizon-mod-registry), behind the site's own address.
+export const API = "/api/mods";
 export const SCHEMA = 1;
 
 // The kinds the site shows, in the filter's order. Kinds a newer index adds are left out until the site knows them.
@@ -108,3 +110,66 @@ export function projectHtml(p) {
   <a class="link-arrow" href="${REGISTRY}/issues/new?template=report.yml&amp;title=${escape(p.id)}">Report it<span aria-hidden="true">→</span></a></p>
 </article>`;
 }
+
+// /mods/submit: the form. Its script (mods-submit.js) signs in, then sends the page and the file to the service, which
+// checks the file and opens the pull request the reviewers read.
+const field = (name, label, input, hint = "") =>
+  `<label class="mod-field" for="f-${name}"><span class="mod-label">${label}</span>${input}${hint ? `<span class="meta">${hint}</span>` : ""}</label>`;
+const text = (name, attrs = "") => `<input class="mod-search" id="f-${name}" name="${name}" ${attrs}>`;
+
+export function submitHtml() {
+  return `<p class="kicker"><span>Mods</span>Submit</p>
+        <h1 class="display page-title">Submit to the registry</h1>
+        <p class="lede">A mod, a modpack of registry mods, or a resource pack made for Horizon. The form checks the file and opens a pull request; a reviewer reads it, its source and the checks' report, and merging publishes it to this site and the launcher.</p>
+        <div class="mod-auth" id="submit-auth" aria-live="polite">
+          <p class="meta no-script">The form needs JavaScript. You can also <a href="${REGISTRY}">open a pull request by hand</a>.</p>
+        </div>
+        <form class="mod-form" id="submit-form" hidden>
+          <fieldset><legend class="heading">The file</legend>
+          ${field("kind", "Kind", `<select class="mod-search" id="f-kind" name="kind">${KINDS.map(([k, label]) => `<option value="${k}"${k === "shader" ? " disabled" : ""}>${label.replace(/s$/, "")}${k === "shader" ? " (opens with Horizon's own shader format)" : ""}</option>`).join("")}</select>`)}
+          ${field("file", "File", `<input id="f-file" name="file" type="file" accept=".hmod,.hpack,.zip" required>`, "A .hmod, a .hpack or a resource pack .zip, at most 64 MB. Run <code>cargo horizon-mod check</code> on it first.")}
+          ${field("id", "Id", text("id", `required pattern="[a-z0-9_]{1,64}" placeholder="my_mod" autocomplete="off"`), "Its manifest's id: a-z, 0-9 and _. A resource pack's is yours to pick.")}
+          ${field("version", "Version", text("version", `required pattern="[A-Za-z0-9][A-Za-z0-9._\\-]{0,63}" placeholder="1.0.0"`))}
+          ${field("game", "For Minecraft", text("game", `required value="26.3"`))}
+          ${field("changelog", "What changed", `<textarea class="mod-search" id="f-changelog" name="changelog" rows="3"></textarea>`, "Markdown.")}
+          </fieldset>
+          <fieldset><legend class="heading">Its page</legend>
+          ${field("name", "Name", text("name", `required maxlength="64"`))}
+          ${field("summary", "Summary", text("summary", `required maxlength="160"`), "One line for the list.")}
+          ${field("description", "Description", `<textarea class="mod-search" id="f-description" name="description" rows="6"></textarea>`, "Markdown.")}
+          ${field("authors", "Authors", text("authors", `placeholder="Alice, Bob"`), "Separated by commas.")}
+          ${field("license", "Licence", text("license", `required placeholder="MIT"`), "An SPDX expression.")}
+          ${field("source", "Source code", text("source", `required type="url" pattern="https://.*" placeholder="https://github.com/you/your-mod"`), "Reviewers read it: the file must be built from it.")}
+          ${field("icon", "Icon", text("icon", `type="url" pattern="https://.*" placeholder="https://…/icon.png"`), "Optional, a square PNG.")}
+          </fieldset>
+          <fieldset><legend class="heading">Signature</legend>
+          <p class="meta">Optional, and recommended: with your <a href="https://jedisct1.github.io/minisign/">minisign</a> key on the project, every later version must be signed with it, so nobody else can publish an update in your name.</p>
+          ${field("key", "Public key", text("key", `placeholder="RW…" autocomplete="off"`), "A new project's. Changing a published project's key is a pull request by hand.")}
+          ${field("signature", "Signature", `<input id="f-signature" name="signature" type="file" accept=".minisig">`, "The file's .minisig.")}
+          </fieldset>
+          <label class="mod-check"><input type="checkbox" id="f-mine" required> I made it, or I may publish it under this licence, and its source is at the address above.</label>
+          <p class="mod-actions"><button class="button primary" type="submit" id="f-send">Submit for review</button></p>
+          <div class="mod-result" id="submit-result" role="status" aria-live="polite"></div>
+        </form>`;
+}
+
+// The service's "entry" from the form's values (strings), as it reads it.
+export function entryFrom(v) {
+  const optional = (x) => (x && x.trim() ? x.trim() : undefined);
+  return {
+    id: v.id.trim(),
+    kind: v.kind,
+    name: v.name.trim(),
+    summary: v.summary.trim(),
+    description: v.description || "",
+    authors: (v.authors || "").split(",").map((a) => a.trim()).filter(Boolean),
+    license: v.license.trim(),
+    source: v.source.trim(),
+    icon: optional(v.icon),
+    key: optional(v.key),
+    signature: optional(v.signature),
+    version: v.version.trim(),
+    game: v.game.trim(),
+    changelog: v.changelog || "",
+  };
+}
diff --git a/website/src/mods.test.mjs b/website/src/mods.test.mjs
index 8dc5c0867..75e3ca4c5 100644
--- a/website/src/mods.test.mjs
+++ b/website/src/mods.test.mjs
@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { CAPABILITIES, listHtml, matches, projectHtml, readIndex } from "./mods.js";
+import { CAPABILITIES, entryFrom, listHtml, matches, projectHtml, readIndex, submitHtml } from "./mods.js";
 
 const project = (over = {}) => ({
   id: "coords_hud", kind: "mod", name: "Coordinates HUD", summary: "Where you are.", authors: ["Horizon"],
@@ -40,3 +40,16 @@ test("a mod's page says what it may do, as the game does", () => {
   assert.ok(projectHtml(project({ key: "RWT" })).includes("Signed"));
   assert.ok(html.includes("horizon-launcher mods install --source horizon coords_hud"));
 });
+
+test("the submit form sends what the service reads", () => {
+  const html = submitHtml();
+  for (const name of ["kind", "file", "id", "version", "game", "name", "summary", "license", "source", "key", "signature"]) {
+    assert.ok(html.includes(`id="f-${name}"`), name);
+  }
+  assert.match(html, /<option value="shader" disabled>/);
+  const entry = entryFrom({ id: " my_mod ", kind: "mod", name: "My mod", summary: "s", description: "", authors: "Alice, , Bob", license: "MIT", source: "https://x.test", icon: " ", key: "", signature: "", version: "1.0.0", game: "26.3", changelog: "" });
+  assert.deepEqual(entry.authors, ["Alice", "Bob"]);
+  assert.equal(entry.id, "my_mod");
+  assert.equal(entry.icon, undefined);
+  assert.equal(JSON.parse(JSON.stringify(entry)).key, undefined, "an empty key isn't sent");
+});
diff --git a/website/src/style.css b/website/src/style.css
index c67c9f8e4..c6a2d4b62 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -783,6 +783,18 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 .mod-file dt { color: var(--muted); }
 .mod-file code, .mod-steps code { font-family: var(--mono); font-size: 13px; overflow-wrap: anywhere; }
 .mod-links { display: flex; flex-wrap: wrap; gap: 24px; margin-top: 24px; }
+/* /mods/submit */
+.mod-form { display: grid; gap: 24px; max-width: var(--measure); margin-top: 32px; }
+.mod-form fieldset { display: grid; gap: 16px; margin: 0; padding: 0; border: 0; }
+.mod-form legend { padding: 0; margin-bottom: 8px; }
+.mod-field { display: grid; gap: 6px; }
+.mod-label { font-size: var(--text-ui); font-weight: 500; }
+.mod-form .mod-search { width: 100%; }
+.mod-form textarea.mod-search { height: auto; padding: 10px 12px; line-height: 1.5; resize: vertical; }
+.mod-check { display: flex; gap: 10px; align-items: flex-start; font-size: var(--text-ui); }
+.mod-auth { margin-top: 24px; }
+.mod-error { color: var(--danger); font-size: var(--text-ui); }
+.js .no-script { display: none; }
 @media (max-width: 640px) {
   .mod-row { grid-template-columns: 40px minmax(0, 1fr); }
   .mod-side { grid-column: 2; justify-items: start; }

From d4b2e24535111e7b8e1b839bcc16c4ef126fa663 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Simon=20Dr=C3=A4ger?=
 <20014538+sdraeger@users.noreply.github.com>
Date: Sat, 24 Oct 2026 13:21:23 -0700
Subject: [PATCH 004/270] Add mod command capability and Predator Missile
 example

---
 AGENTS.md                                     |   2 +-
 Cargo.lock                                    |   7 +
 Cargo.toml                                    |   2 +-
 crates/horizon-client/src/game/mods.rs        |  13 ++
 .../examples/predator-missile/Cargo.toml      |  16 ++
 .../predator-missile/horizon-mod.toml         |   8 +
 .../examples/predator-missile/src/lib.rs      | 161 ++++++++++++++++++
 crates/horizon-mod-sdk/src/lib.rs             |   4 +-
 crates/horizon-mod-sdk/wit/horizon.wit        |   9 +
 crates/horizon-mods/src/manifest.rs           |  12 +-
 crates/horizon-mods/src/runtime.rs            |  17 +-
 crates/horizon-mods/tests/sandbox.rs          |  45 ++++-
 docs/api/mods-reference.md                    |  13 +-
 docs/mods.md                                  |   3 +-
 14 files changed, 300 insertions(+), 12 deletions(-)
 create mode 100644 crates/horizon-mod-sdk/examples/predator-missile/Cargo.toml
 create mode 100644 crates/horizon-mod-sdk/examples/predator-missile/horizon-mod.toml
 create mode 100644 crates/horizon-mod-sdk/examples/predator-missile/src/lib.rs

diff --git a/AGENTS.md b/AGENTS.md
index f6f6b463b..fda05c1e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,7 +80,7 @@ python3 tools/agent_control_e2e.py         # horizon-ctl / MCP end to end
   ~25, a file of the client lib ~103, of `horizon-world` ~103–109, of `horizon-core` ~119. Plan for it.
 - Rust integration tests: `crates/horizon-client/tests/` (`lan_bot.rs`, `generation_saves.rs`, `streaming_meshes.rs`).
 - **macOS:** `cargo build/test --workspace` may fail to link the two wasm guest cdylibs (undefined
-  `horizon:mods/events` symbols) until #1446 lands: add `--exclude coords-hud --exclude horizon-mods-test-guest`.
+  `horizon:mods/events` symbols) until #1446 lands: add `--exclude coords-hud --exclude predator-missile --exclude horizon-mods-test-guest`.
   Their real check is `cargo test -p horizon-mods` (builds them for `wasm32-unknown-unknown`).
 - Linux needs `libasound2-dev libudev-dev`; `--no-default-features` drops audio and controllers (the server build).
 - Run and drive the game (starts the `horizon-client` beside `horizon-ctl`; other arguments go to the game):
diff --git a/Cargo.lock b/Cargo.lock
index 27eaad0c4..1468327ce 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2620,6 +2620,13 @@ dependencies = [
  "zerovec",
 ]
 
+[[package]]
+name = "predator-missile"
+version = "0.1.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "presser"
 version = "0.3.1"
diff --git a/Cargo.toml b/Cargo.toml
index f197c34fe..a0feaba87 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "crates/horizon-mod-sdk/examples/predator-missile", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 572f9fe2b..c203d0ca2 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -342,6 +342,19 @@ impl Game<'_> {
                 }
                 Output::Feedback { text, error: false } => Text::literal(text),
                 Output::Feedback { text, error: true } => Text::literal(text).with_color(text::RED),
+                // Vanilla's commands only: a mod running a mod command could loop.
+                Output::Command { line } => {
+                    let name = line.split(' ').next().unwrap_or_default();
+                    // As handle_chat_input, without the chat history.
+                    if !vanilla_command(name) {
+                        // dropped
+                    } else if self.remote.is_some() {
+                        self.send_chat(&format!("/{line}"));
+                    } else {
+                        self.run_command(&line);
+                    }
+                    continue;
+                }
                 Output::Stopped { name, reason } => {
                     self.list_mods();
                     self.sync_mod_commands();
diff --git a/crates/horizon-mod-sdk/examples/predator-missile/Cargo.toml b/crates/horizon-mod-sdk/examples/predator-missile/Cargo.toml
new file mode 100644
index 000000000..a3a77ce0b
--- /dev/null
+++ b/crates/horizon-mod-sdk/examples/predator-missile/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "predator-missile"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "Example Horizon mod: a missile you launch with /missile and steer with the mouse"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../.." }
+
+[lints]
+workspace = true
diff --git a/crates/horizon-mod-sdk/examples/predator-missile/horizon-mod.toml b/crates/horizon-mod-sdk/examples/predator-missile/horizon-mod.toml
new file mode 100644
index 000000000..3baaf7d87
--- /dev/null
+++ b/crates/horizon-mod-sdk/examples/predator-missile/horizon-mod.toml
@@ -0,0 +1,8 @@
+id = "predator_missile"
+name = "Predator Missile"
+version = "0.1.0"
+description = "/missile launches a guided missile 60 blocks above you. Steer it with the mouse; it explodes on whatever it hits. Needs cheats (it runs vanilla commands as you)."
+authors = ["Horizon"]
+api = "0.1"
+side = "client"
+capabilities = ["game-read", "hud", "chat", "command"]
diff --git a/crates/horizon-mod-sdk/examples/predator-missile/src/lib.rs b/crates/horizon-mod-sdk/examples/predator-missile/src/lib.rs
new file mode 100644
index 000000000..75ebbbdec
--- /dev/null
+++ b/crates/horizon-mod-sdk/examples/predator-missile/src/lib.rs
@@ -0,0 +1,161 @@
+//! Example Horizon mod (`docs/mods.md`): `/missile` turns you into a guided
+//! missile 60 blocks up. You fly along your own look, so the mouse steers;
+//! on a block or a mob a stack of primed TNT goes off, and you are put back
+//! where you launched. Built from vanilla commands (capability `command`),
+//! so it needs cheats.
+use horizon_mod_sdk::{
+    Mod, Registration,
+    command::run,
+    game::{self, Player},
+    hud::{self, Corner, Line},
+};
+
+/// Blocks per tick (a fired arrow does about 3).
+const SPEED: f64 = 1.5;
+const ALTITUDE: i32 = 60;
+/// Ticks of flight before the missile detonates on its own.
+const FUEL: u32 = 30 * 20;
+/// Ticks to watch the blast before going back.
+const AFTERMATH: u32 = 40;
+/// Primed TNT per blast: the stack's explosions add up.
+const WARHEAD: usize = 4;
+/// What the impact checks print; the mod hears it through the chat hook.
+const IMPACT: &str = "Predator: impact";
+
+enum State {
+    Idle,
+    Flying { from: Player, ticks: u32 },
+    Aftermath { from: Player, ticks: u32 },
+}
+
+struct Predator {
+    state: State,
+}
+
+fn launch() {
+    run("gamerule send_command_feedback false");
+    run("execute if entity @s[gamemode=creative] run tag @s add pm_creative");
+    run("gamemode spectator");
+    run(&format!("tp @s ~ ~{ALTITUDE} ~ ~ 60"));
+    run("effect give @s night_vision 60 0 true");
+    // The thermal camera: every mob outlined.
+    run("effect give @e[type=!player,distance=..256] glowing 60 0 true");
+}
+
+/// One tick of flight: stop at the surface (the next step would enter a
+/// block or a mob), else move one step along the look.
+fn fly() {
+    run(&format!(
+        "execute at @s unless block ^ ^ ^{SPEED} #minecraft:air run tellraw @s \"{IMPACT}\""
+    ));
+    run(&format!(
+        "execute at @s positioned ^ ^ ^{SPEED} if entity @e[type=!player,distance=..2] run tellraw @s \"{IMPACT}\""
+    ));
+    run(&format!(
+        "execute at @s if block ^ ^ ^{SPEED} #minecraft:air run tp @s ^ ^ ^{SPEED}"
+    ));
+}
+
+fn detonate() {
+    for _ in 0..WARHEAD {
+        run("execute at @s run summon tnt ^ ^ ^1 {fuse:0s}");
+    }
+}
+
+fn land(from: &Player) {
+    run(&format!(
+        "tp @s {} {} {} {} {}",
+        from.x, from.y, from.z, from.yaw, from.pitch
+    ));
+    run("execute if entity @s[tag=pm_creative] run gamemode creative");
+    run("execute unless entity @s[tag=pm_creative] run gamemode survival");
+    run("execute if entity @s[tag=pm_creative] run tag @s remove pm_creative");
+    run("effect clear @s night_vision");
+    // shortcut: assumes feedback was on before launch, as in a new world.
+    run("gamerule send_command_feedback true");
+}
+
+fn panel(p: &Player, ticks: u32) -> Vec<Line> {
+    let green = 0x7CFF7C;
+    let left = (FUEL - ticks.min(FUEL)) / 20;
+    [
+        "PREDATOR".to_string(),
+        format!("ALT {:.0}", p.y),
+        format!("FUEL {left}s"),
+        "Mouse to steer, /missile to detonate".to_string(),
+    ]
+    .into_iter()
+    .map(|text| Line { text, color: green })
+    .collect()
+}
+
+impl Predator {
+    fn impact(&mut self) {
+        if let State::Flying { from, .. } = &self.state {
+            detonate();
+            self.state = State::Aftermath {
+                from: from.clone(),
+                ticks: 0,
+            };
+        }
+    }
+}
+
+impl Mod for Predator {
+    fn init() -> Result<(Self, Registration), String> {
+        let hooks = Registration::new().command("missile").on_tick().on_chat();
+        Ok((Predator { state: State::Idle }, hooks))
+    }
+
+    fn tick(&mut self, _tick: u64) {
+        match &mut self.state {
+            State::Idle => {}
+            State::Flying { ticks, .. } => {
+                *ticks += 1;
+                let ticks = *ticks;
+                if ticks >= FUEL {
+                    return self.impact();
+                }
+                // The first tick waits for the launch teleport.
+                if ticks > 1 {
+                    fly();
+                }
+                if let Some(p) = game::get_player() {
+                    hud::set_panel(Corner::TopLeft, &panel(&p, ticks));
+                }
+            }
+            State::Aftermath { from, ticks } => {
+                *ticks += 1;
+                if *ticks >= AFTERMATH {
+                    land(from);
+                    hud::clear();
+                    self.state = State::Idle;
+                }
+            }
+        }
+    }
+
+    fn chat(&mut self, text: &str) {
+        if text.contains(IMPACT) {
+            self.impact();
+        }
+    }
+
+    fn command(&mut self, _name: &str, _args: &str) -> Result<Option<String>, String> {
+        match self.state {
+            State::Idle => {
+                let from = game::get_player().ok_or("Not in a world")?;
+                launch();
+                self.state = State::Flying { from, ticks: 0 };
+                Ok(Some("Missile away".into()))
+            }
+            State::Flying { .. } => {
+                self.impact();
+                Ok(None)
+            }
+            State::Aftermath { .. } => Err("Wait for the blast to clear".into()),
+        }
+    }
+}
+
+horizon_mod_sdk::export_mod!(Predator);
diff --git a/crates/horizon-mod-sdk/src/lib.rs b/crates/horizon-mod-sdk/src/lib.rs
index 71c36cf80..7efcf20b3 100644
--- a/crates/horizon-mod-sdk/src/lib.rs
+++ b/crates/horizon-mod-sdk/src/lib.rs
@@ -21,7 +21,7 @@
 //! ```
 //!
 //! Every interface but `log` is a capability: list the ones the mod uses in
-//! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`).
+//! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`, `command`).
 
 wit_bindgen::generate!({
     path: "wit",
@@ -32,7 +32,7 @@ wit_bindgen::generate!({
 });
 
 pub use exports::horizon::mods::events::{Guest as __Guest, Registration};
-pub use horizon::mods::{chat, game, hud, log, storage};
+pub use horizon::mods::{chat, command, game, hud, log, storage};
 
 /// The game's calls into a mod. Only the hooks [`Registration`] asks for
 /// are called; the others may stay as their defaults.
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 9f00a12b1..e14913782 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -86,6 +86,14 @@ interface storage {
     delete: func(key: string);
 }
 
+/// Capability `command`: vanilla commands run as the player, with the
+/// player's permissions, after the hook call returns (8 per call). A mod's
+/// own commands are not run this way.
+interface command {
+    /// `line` without its slash; its feedback goes to the chat as if typed.
+    run: func(line: string);
+}
+
 /// What the game calls. Only the hooks `init` asks for are ever called.
 interface events {
     record registration {
@@ -117,5 +125,6 @@ world horizon-mod {
     import chat;
     import hud;
     import storage;
+    import command;
     export events;
 }
diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index a71210883..6f1674e05 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -69,16 +69,19 @@ pub enum Capability {
     Chat,
     Hud,
     Storage,
+    /// Runs vanilla commands as the player, with the player's permissions.
+    Command,
     /// New blocks and items from the mod's `data/` (API 0.2): no WIT
     /// interface, the game reads them before the world loads.
     Registries,
 }
 impl Capability {
-    pub const ALL: [Capability; 5] = [
+    pub const ALL: [Capability; 6] = [
         Capability::GameRead,
         Capability::Chat,
         Capability::Hud,
         Capability::Storage,
+        Capability::Command,
         Capability::Registries,
     ];
     /// The WIT interface it grants, in `horizon:mods`.
@@ -88,6 +91,7 @@ impl Capability {
             Capability::Chat => "chat",
             Capability::Hud => "hud",
             Capability::Storage => "storage",
+            Capability::Command => "command",
             Capability::Registries => "registries",
         }
     }
@@ -98,6 +102,7 @@ impl Capability {
             Capability::Chat => "show you chat messages",
             Capability::Hud => "draw text on your screen",
             Capability::Storage => "save its own settings to disk",
+            Capability::Command => "run commands as you, with your permissions",
             Capability::Registries => "add blocks and items to your worlds",
         }
     }
@@ -128,6 +133,7 @@ impl fmt::Display for Capability {
             Capability::Chat => "chat",
             Capability::Hud => "hud",
             Capability::Storage => "storage",
+            Capability::Command => "command",
             Capability::Registries => "registries",
         };
         f.write_str(name)
@@ -366,6 +372,10 @@ capabilities = ["game-read", "hud"]
             storage,
             Err("uses capability storage, missing from horizon-mod.toml".into())
         );
+        assert_eq!(
+            m.check_imports(["horizon:mods/command@0.1.0"]),
+            Err("uses capability command, missing from horizon-mod.toml".into())
+        );
         let with_storage = EXAMPLE.replace("\"hud\"", "\"hud\", \"storage\"");
         let m = Manifest::parse(&with_storage).unwrap();
         assert_eq!(m.check_imports(["horizon:mods/storage@0.1.0"]), Ok(()));
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 9dd2eb54e..07be81909 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -23,7 +23,7 @@ pub use bindings::horizon::mods::{
 use bindings::{
     HorizonMod,
     exports::horizon::mods::events::Registration,
-    horizon::mods::{chat, game, hud, log as mod_log, storage},
+    horizon::mods::{chat, command, game, hud, log as mod_log, storage},
 };
 
 /// A mod's linear memory cap.
@@ -67,6 +67,9 @@ pub enum Output {
     Chat { name: String, text: String },
     /// A mod command's feedback, red when `error`.
     Feedback { text: String, error: bool },
+    /// `command.run`: a vanilla command line, without its slash, to run as
+    /// the player.
+    Command { line: String },
     /// The mod was turned off: it trapped, overran or failed to start.
     Stopped { name: String, reason: String },
 }
@@ -514,6 +517,18 @@ impl chat::Host for State {
         }
     }
 }
+impl command::Host for State {
+    fn run(&mut self, line: String) {
+        let queued = self
+            .out
+            .iter()
+            .filter(|o| matches!(o, Output::Command { .. }))
+            .count();
+        if queued < CHAT_PER_CALL {
+            self.out.push(Output::Command { line: clip(line) });
+        }
+    }
+}
 impl hud::Host for State {
     fn set_panel(&mut self, corner: Corner, lines: Vec<Line>) {
         let lines = lines
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index a246c07b0..c8e4fb883 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -1,4 +1,5 @@
-//! Loads real mods built with the SDK: the coords-hud example and a guest
+//! Loads real mods built with the SDK: the coords-hud and predator-missile
+//! examples and a guest
 //! that misbehaves on command. Needs `rustup target add wasm32-unknown-unknown`.
 use horizon_mods::{
     Clock, Corner, Mods, Output, Package, Player, Snapshot, Status, manifest::componentize,
@@ -18,7 +19,7 @@ api = "0.1"
 capabilities = ["chat", "storage"]
 "#;
 
-/// Builds both mods once and writes their `.hmod` files; returns the folder.
+/// Builds the mods once and writes their `.hmod` files; returns the folder.
 fn mods_dir() -> &'static Path {
     static DIR: OnceLock<PathBuf> = OnceLock::new();
     DIR.get_or_init(|| {
@@ -31,6 +32,8 @@ fn mods_dir() -> &'static Path {
                 "-p",
                 "coords-hud",
                 "-p",
+                "predator-missile",
+                "-p",
                 "horizon-mods-test-guest",
                 "--target-dir",
             ])
@@ -44,9 +47,13 @@ fn mods_dir() -> &'static Path {
         let built = target.join("wasm32-unknown-unknown/release");
         let dir = target.join("mods");
         std::fs::create_dir_all(&dir).unwrap();
-        let example = root.join("crates/horizon-mod-sdk/examples/coords-hud/horizon-mod.toml");
+        let example = |name: &str| {
+            let path = format!("crates/horizon-mod-sdk/examples/{name}/horizon-mod.toml");
+            std::fs::read_to_string(root.join(path)).unwrap()
+        };
         let mods = [
-            ("coords_hud", std::fs::read_to_string(example).unwrap()),
+            ("coords_hud", example("coords-hud")),
+            ("predator_missile", example("predator-missile")),
             ("horizon_mods_test_guest", GUEST_MANIFEST.to_string()),
         ];
         for (name, manifest) in mods {
@@ -81,6 +88,36 @@ fn player() -> Snapshot {
     }
 }
 
+/// Capability `command`: `/missile` queues vanilla commands, and the chat
+/// line its impact check prints sets off the warhead.
+#[test]
+fn predator_missile_runs_commands() {
+    let mut mods = load("predator_missile.hmod");
+    assert_eq!(mods.entries()[0].status, Status::Running);
+    mods.set_snapshot(player());
+    let commands = |mods: &mut Mods| -> Vec<String> {
+        mods.drain()
+            .into_iter()
+            .filter_map(|o| match o {
+                Output::Command { line } => Some(line),
+                _ => None,
+            })
+            .collect()
+    };
+    assert!(mods.command("missile"));
+    let launch = commands(&mut mods);
+    assert_eq!(launch.len(), 6);
+    assert!(launch.contains(&"gamemode spectator".to_string()));
+    mods.tick(1);
+    mods.tick(2);
+    let flight = commands(&mut mods);
+    assert!(flight.iter().any(|l| l.ends_with("run tp @s ^ ^ ^1.5")));
+    mods.chat("Predator: impact");
+    let blast = commands(&mut mods);
+    assert_eq!(blast.len(), 4);
+    assert!(blast.iter().all(|l| l.contains("summon tnt")));
+}
+
 #[test]
 fn coords_hud_draws_and_answers() {
     let mut mods = load("coords_hud.hmod");
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index ca2fe9d7a..28703e784 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -11,11 +11,12 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `chat` | [`chat`](#chat) | show you chat messages |
 | `hud` | [`hud`](#hud) | draw text on your screen |
 | `storage` | [`storage`](#storage) | save its own settings to disk |
+| `command` | [`command`](#command) | run commands as you, with your permissions |
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
 
 ## World `horizon-mod`
 
-- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`
+- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`, `command`
 - Exports (what the mod provides): `events`
 
 ## `log`
@@ -117,6 +118,16 @@ Capability `storage`: a per-mod folder of small key/value files, quota'd (docs/m
 | `set` | `func(key: string, value: list<u8>) -> result<_, string>` | Errs on a malformed key or over quota (bytes for the whole mod). |
 | `delete` | `func(key: string)` | No error if `key` was already absent. |
 
+## `command`
+
+Access: capability `command`.
+
+Capability `command`: vanilla commands run as the player, with the player's permissions, after the hook call returns (8 per call). A mod's own commands are not run this way.
+
+| Function | Signature | What it does |
+| --- | --- | --- |
+| `run` | `func(line: string)` | `line` without its slash; its feedback goes to the chat as if typed. |
+
 ## `events`
 
 Access: exported by the mod: the game calls it.
diff --git a/docs/mods.md b/docs/mods.md
index d8ea925b3..5d386720b 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -13,7 +13,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 |---|---|---|
 | The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
-| Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
+| Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
 | Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run` |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
@@ -84,6 +84,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) |
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
+| `command` | `command` | `run(line)`: a vanilla command run as the player, with the player's permissions, after the hook returns (8 per call); mods' own commands are not run |
 
 | Hook (export) | When |
 |---|---|

From 7e513d2d5c85eefdf4b23d3e1295699e45cc4886 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:47:37 +0200
Subject: [PATCH 005/270] Launcher: Horizon's registry as a mod browser source

A browser source for Horizon's own registry (docs/api/mod-index.md): it reads index.json
(HORIZON_MOD_INDEX for a test registry, cached in the game folder for when the registry can't
be reached), searches it by kind and words, lists versions with the SHA-256 the index gives,
and blocks the versions it says were taken down. Downloads accept the registry's release host
and check SHA-256; file:// files only from a local index.

Installing, the takedown check before play and the CLI come next.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/Cargo.lock                     |   9 +
 launcher/Cargo.toml                     |   2 +
 launcher/src/browser.rs                 |  40 +++-
 launcher/src/browser/curseforge.rs      |   1 +
 launcher/src/browser/download.rs        |  41 +++-
 launcher/src/browser/horizon.rs         | 280 ++++++++++++++++++++++++
 launcher/src/browser/horizon/tests.rs   |  61 ++++++
 launcher/src/browser/installed/tests.rs |   1 +
 launcher/src/browser/java.rs            |   1 +
 launcher/src/browser/modrinth.rs        |   1 +
 launcher/src/browser/tests.rs           |   4 +-
 11 files changed, 423 insertions(+), 18 deletions(-)
 create mode 100644 launcher/src/browser/horizon.rs
 create mode 100644 launcher/src/browser/horizon/tests.rs

diff --git a/launcher/Cargo.lock b/launcher/Cargo.lock
index 5155420e0..a416a39ff 100644
--- a/launcher/Cargo.lock
+++ b/launcher/Cargo.lock
@@ -2673,6 +2673,7 @@ dependencies = [
  "horizon-bench",
  "horizon-core",
  "horizon-friends",
+ "horizon-mods",
  "horizon-port-pack",
  "horizon-prepare",
  "horizon-release-sign",
@@ -2698,8 +2699,10 @@ name = "horizon-mods"
 version = "0.1.0"
 dependencies = [
  "log",
+ "minisign-verify",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "toml 1.1.8+spec-1.1.0",
  "zip",
 ]
@@ -3470,6 +3473,12 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
 
+[[package]]
+name = "minisign-verify"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "871285dc19d8d0ebe0eef3d0e99a205f2a71363b122632cbbfa4a6c370a960ce"
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
diff --git a/launcher/Cargo.toml b/launcher/Cargo.toml
index a402d0e28..cfe9787d6 100644
--- a/launcher/Cargo.toml
+++ b/launcher/Cargo.toml
@@ -31,6 +31,8 @@ horizon-friends = { path = "../crates/horizon-friends" }
 horizon-bench = { path = "../crates/horizon-bench" }
 # Import modpack: the porting pipeline, run on the player's own files (docs/modpacks.md).
 horizon-port-pack = { path = "../crates/horizon-port-pack" }
+# Horizon's mod registry: its index and the checks a download passes before install.
+horizon-mods = { path = "../crates/horizon-mods", features = ["index"] }
 # Signed updates: archives are checked against the release's signed checksums (docs/security.md).
 horizon-release-sign = { path = "../crates/horizon-release-sign" }
 # Opt-in data collection: the consent, the outbox and its upload (docs/telemetry.md).
diff --git a/launcher/src/browser.rs b/launcher/src/browser.rs
index f02638db5..7f81d5e37 100644
--- a/launcher/src/browser.rs
+++ b/launcher/src/browser.rs
@@ -8,6 +8,7 @@
 pub mod curseforge;
 pub mod details;
 pub mod download;
+pub mod horizon;
 pub mod images;
 pub mod installed;
 pub mod java;
@@ -56,6 +57,8 @@ impl Kind {
 pub enum SourceId {
     Modrinth,
     CurseForge,
+    /// Horizon's own registry of reviewed mods, modpacks and resource packs ([`horizon`]).
+    Horizon,
 }
 
 impl SourceId {
@@ -63,6 +66,7 @@ impl SourceId {
         match self {
             SourceId::Modrinth => "Modrinth",
             SourceId::CurseForge => "CurseForge",
+            SourceId::Horizon => "Horizon",
         }
     }
 }
@@ -132,6 +136,8 @@ pub struct FileRef {
     pub name: String,
     pub size: u64,
     pub sha512: Option<String>,
+    /// What Horizon's registry lists.
+    pub sha256: Option<String>,
     pub sha1: Option<String>,
     pub primary: bool,
 }
@@ -139,11 +145,13 @@ pub struct FileRef {
 impl FileRef {
     /// The strongest checksum the source gives: what the download is checked against.
     pub fn checksum(&self) -> Option<(&'static str, &str)> {
-        match (&self.sha512, &self.sha1) {
-            (Some(h), _) => Some(("SHA-512", h)),
-            (None, Some(h)) => Some(("SHA-1", h)),
-            (None, None) => None,
-        }
+        [
+            ("SHA-512", &self.sha512),
+            ("SHA-256", &self.sha256),
+            ("SHA-1", &self.sha1),
+        ]
+        .into_iter()
+        .find_map(|(algo, h)| Some((algo, h.as_deref()?)))
     }
 }
 
@@ -230,10 +238,11 @@ pub trait Source: Send + Sync {
 /// What the launcher says wherever CurseForge would be.
 pub const CURSEFORGE_SOON: &str = "CurseForge support is coming soon.";
 
-/// The sources this launcher uses: Modrinth. CurseForge support is coming soon: its API needs a
-/// paid key, so no search or install goes to it; `curseforge` is kept for then.
+/// The sources this launcher uses: Modrinth and Horizon's registry. CurseForge support is coming
+/// soon: its API needs a paid key, so no search or install goes to it; `curseforge` is kept for
+/// then.
 pub fn sources() -> Vec<Box<dyn Source>> {
-    vec![Box::new(modrinth::Modrinth)]
+    vec![Box::new(modrinth::Modrinth), Box::new(horizon::Registry)]
 }
 
 /// The source of that id, when this launcher can use it.
@@ -243,6 +252,15 @@ pub fn source(id: SourceId) -> Option<Box<dyn Source>> {
 
 /// How well a project of `kind` made for `game_versions` and `loaders` runs in Horizon.
 pub fn support(kind: Kind, game_versions: &[String], loaders: &[String]) -> Support {
+    if loaders.iter().any(|l| l == horizon::LOADER) {
+        // Made for Horizon and reviewed: it runs when it is for the version Horizon plays.
+        return match newest_release(game_versions)
+            .filter(|_| !game_versions.iter().any(|v| v == GAME))
+        {
+            Some(other) => Support::No(format!("Made for Horizon on {other}.")),
+            None => Support::Works,
+        };
+    }
     match kind {
         Kind::ResourcePack => {
             if game_versions.iter().any(|v| v == GAME) {
@@ -309,6 +327,12 @@ pub fn pick(kind: Kind, versions: &[Version], everything: bool) -> Option<&Versi
     let mut usable = versions
         .iter()
         .filter(|v| v.blocked.is_none() && v.file().is_some());
+    if versions
+        .iter()
+        .any(|v| v.loaders.iter().any(|l| l == horizon::LOADER))
+    {
+        return usable.find(|v| v.game_versions.iter().any(|g| g == GAME));
+    }
     if kind == Kind::Mod {
         let java = |v: &&Version| {
             v.loaders
diff --git a/launcher/src/browser/curseforge.rs b/launcher/src/browser/curseforge.rs
index 4894fe5f0..e17a6b822 100644
--- a/launcher/src/browser/curseforge.rs
+++ b/launcher/src/browser/curseforge.rs
@@ -164,6 +164,7 @@ pub(super) fn parse_file(f: &Value) -> Option<Version> {
                 name: name.clone(),
                 size: f["fileLength"].as_u64().unwrap_or(0),
                 sha512: None,
+                sha256: None,
                 sha1,
                 primary: true,
             }]
diff --git a/launcher/src/browser/download.rs b/launcher/src/browser/download.rs
index 66199fd07..593273245 100644
--- a/launcher/src/browser/download.rs
+++ b/launcher/src/browser/download.rs
@@ -1,16 +1,18 @@
 //! Downloads that reach the game folder only when their checksum matches the source's.
 use super::{safe_name, FileRef};
 use sha1::Sha1;
-use sha2::{Digest, Sha512};
+use sha2::{Digest, Sha256, Sha512};
 use std::fs;
 use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
 
-/// Hosts a file may come from: Modrinth's and CurseForge's file servers.
-const HOSTS: [&str; 3] = [
+/// Hosts a file may come from: Modrinth's and CurseForge's file servers, and the release assets
+/// of Horizon's registry.
+const HOSTS: [&str; 4] = [
     "https://cdn.modrinth.com/",
     "https://edge.forgecdn.net/",
     "https://mediafilez.forgecdn.net/",
+    horizon_mods::index::FILE_HOST,
 ];
 /// Bigger than any pack these sources serve (Modrinth caps uploads at 500 MiB).
 const MAX: u64 = 1 << 30;
@@ -31,10 +33,15 @@ pub(super) fn agent() -> ureq::Agent {
 pub fn refuse(file: &FileRef) -> Option<String> {
     if !HOSTS.iter().any(|h| file.url.starts_with(h)) {
         return Some(format!(
-            "{} isn't on Modrinth's or CurseForge's file servers.",
+            "{} isn't on Modrinth's, CurseForge's or Horizon's file servers.",
             file.url
         ));
     }
+    refuse_file(file)
+}
+
+/// [`refuse`] without the host: the name, the checksum and the size.
+fn refuse_file(file: &FileRef) -> Option<String> {
     if safe_name(&file.name).is_none() {
         return Some(format!("{:?} isn't a plain file name.", file.name));
     }
@@ -50,26 +57,29 @@ pub fn refuse(file: &FileRef) -> Option<String> {
 /// Hashes as they are written: the strongest one the file lists.
 enum Hasher {
     Sha512(Sha512),
+    Sha256(Sha256),
     Sha1(Sha1),
 }
 
 impl Hasher {
     fn for_file(file: &FileRef) -> Self {
-        if file.sha512.is_some() {
-            Hasher::Sha512(Sha512::new())
-        } else {
-            Hasher::Sha1(Sha1::new())
+        match file.checksum() {
+            Some(("SHA-512", _)) => Hasher::Sha512(Sha512::new()),
+            Some(("SHA-256", _)) => Hasher::Sha256(Sha256::new()),
+            _ => Hasher::Sha1(Sha1::new()),
         }
     }
     fn update(&mut self, bytes: &[u8]) {
         match self {
             Hasher::Sha512(h) => h.update(bytes),
+            Hasher::Sha256(h) => h.update(bytes),
             Hasher::Sha1(h) => h.update(bytes),
         }
     }
     fn hex(self) -> String {
         let bytes: Vec<u8> = match self {
             Hasher::Sha512(h) => h.finalize().to_vec(),
+            Hasher::Sha256(h) => h.finalize().to_vec(),
             Hasher::Sha1(h) => h.finalize().to_vec(),
         };
         bytes.iter().map(|b| format!("{b:02x}")).collect()
@@ -81,13 +91,26 @@ impl Hasher {
 /// `progress` gets the fraction done.
 pub fn save(
     file: &FileRef,
-    mut reader: impl Read,
+    reader: impl Read,
     folder: &Path,
     progress: &dyn Fn(f32),
 ) -> Result<PathBuf, String> {
     if let Some(why) = refuse(file) {
         return Err(why);
     }
+    save_from_anywhere(file, reader, folder, progress)
+}
+
+/// [`save`] for a file that comes from no host: a local test registry's.
+pub(super) fn save_from_anywhere(
+    file: &FileRef,
+    mut reader: impl Read,
+    folder: &Path,
+    progress: &dyn Fn(f32),
+) -> Result<PathBuf, String> {
+    if let Some(why) = refuse_file(file) {
+        return Err(why);
+    }
     let (algo, want) = file.checksum().expect("refuse checks for one");
     fs::create_dir_all(folder).map_err(|e| format!("{}: {e}", folder.display()))?;
     let target = folder.join(&file.name);
diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
new file mode 100644
index 000000000..a54bca17f
--- /dev/null
+++ b/launcher/src/browser/horizon.rs
@@ -0,0 +1,280 @@
+//! Horizon's own registry (docs/api/mod-index.md): mods, modpacks and resource packs made for
+//! Horizon, reviewed as pull requests in ludovic111/horizon-mods. One file lists them all,
+//! `index.json`: this is the browser source that searches it and downloads its files, checked
+//! against the SHA-256 it lists. Versions the index says were taken down are blocked.
+use super::{
+    details::{Details, Link},
+    download, FileRef, Kind, Project, Query, Source, SourceId, Version, GAME,
+};
+use horizon_mods::index::{self, Index};
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+/// Where the registry publishes its index (GitHub Pages of ludovic111/horizon-mods).
+pub const INDEX_URL: &str = "https://ludovic111.github.io/horizon-mods/index.json";
+/// The registry's pages on the website, `<SITE>/<id>`.
+const SITE: &str = "https://playhorizon.dev/mods";
+/// The report form of a project.
+const REPORT: &str = "https://github.com/ludovic111/horizon-mods/issues/new?template=report.yml";
+/// The loader name the browser gives registry versions, so `support` and `pick` know them.
+pub const LOADER: &str = "horizon";
+/// How long a fetched index is used before it is fetched again.
+const FRESH: Duration = Duration::from_secs(600);
+/// Larger than any index should be.
+const MAX_INDEX: u64 = 16 << 20;
+/// The last index fetched, kept in the game folder for when the registry can't be reached.
+const CACHE: &str = "mod-browser/horizon-index.json";
+
+/// Where the index comes from: `HORIZON_MOD_INDEX` (a file or an `https://` address, for a
+/// test registry), else [`INDEX_URL`].
+fn location() -> String {
+    std::env::var("HORIZON_MOD_INDEX")
+        .ok()
+        .filter(|v| !v.is_empty())
+        .unwrap_or_else(|| INDEX_URL.to_owned())
+}
+
+/// True when the index is a local file: its files may then be local too (`file://`), for
+/// trying a registry out before it is published.
+pub fn local() -> bool {
+    !location().starts_with("https://")
+}
+
+static LOADED: Mutex<Option<(Instant, Arc<Index>)>> = Mutex::new(None);
+
+/// The index: the one fetched in the last ten minutes, else fetched again (and kept in the game
+/// folder), else the copy kept last time.
+pub fn index() -> Result<Arc<Index>, String> {
+    if let Some((at, index)) = LOADED.lock().unwrap().as_ref() {
+        if at.elapsed() < FRESH {
+            return Ok(index.clone());
+        }
+    }
+    let cache = crate::backend::game_home().join(CACHE);
+    let index = match fetch_index() {
+        Ok((index, text)) => {
+            if let Some(dir) = cache.parent() {
+                let _ = fs::create_dir_all(dir);
+            }
+            let _ = fs::write(&cache, text);
+            index
+        }
+        Err(e) => {
+            let kept = fs::read_to_string(&cache).map_err(|_| e.clone())?;
+            match local() {
+                true => Index::parse_local(&kept),
+                false => Index::parse(&kept),
+            }
+            .map_err(|_| e)?
+        }
+    };
+    let index = Arc::new(index);
+    *LOADED.lock().unwrap() = Some((Instant::now(), index.clone()));
+    Ok(index)
+}
+
+fn fetch_index() -> Result<(Index, String), String> {
+    use std::io::Read;
+    let at = location();
+    let text = if at.starts_with("https://") {
+        let response = download::agent().get(&at).call().map_err(|e| match e {
+            ureq::Error::Status(code, _) => format!("The mod registry answered {code}."),
+            ureq::Error::Transport(t) => format!("The mod registry can't be reached: {t}"),
+        })?;
+        let mut text = String::new();
+        response
+            .into_reader()
+            .take(MAX_INDEX)
+            .read_to_string(&mut text)
+            .map_err(|e| e.to_string())?;
+        text
+    } else {
+        fs::read_to_string(&at).map_err(|e| format!("{at}: {e}"))?
+    };
+    let index = match local() {
+        true => Index::parse_local(&text)?,
+        false => Index::parse(&text)?,
+    };
+    Ok((index, text))
+}
+
+/// The browser's kind for a registry kind; None for one the launcher doesn't install yet
+/// (Horizon modpacks and shader packs, kinds newer than this launcher).
+fn kind_of(kind: &index::Kind) -> Option<Kind> {
+    match kind {
+        index::Kind::Mod => Some(Kind::Mod),
+        index::Kind::ResourcePack => Some(Kind::ResourcePack),
+        index::Kind::Modpack | index::Kind::Shader | index::Kind::Other(_) => None,
+    }
+}
+
+fn project_of(p: &index::Project) -> Option<Project> {
+    let mut game_versions: Vec<String> = p.versions.iter().map(|v| v.game.clone()).collect();
+    game_versions.dedup();
+    Some(Project {
+        source: SourceId::Horizon,
+        id: p.id.clone(),
+        slug: p.id.clone(),
+        title: p.name.clone(),
+        summary: p.summary.clone(),
+        author: p.authors.join(", "),
+        downloads: 0,
+        page: format!("{SITE}/{}", p.id),
+        icon: p.icon.clone(),
+        license: p.license.clone(),
+        kind: kind_of(&p.kind)?,
+        game_versions,
+        loaders: vec![LOADER.into()],
+    })
+}
+
+fn version_of(index: &Index, p: &index::Project, v: &index::Version) -> Version {
+    Version {
+        id: v.version.clone(),
+        number: v.version.clone(),
+        published: v.published.clone(),
+        game_versions: vec![v.game.clone()],
+        loaders: vec![LOADER.into()],
+        files: vec![FileRef {
+            url: v.file.url.clone(),
+            name: v.file.name.clone(),
+            size: v.file.size,
+            sha512: None,
+            sha256: Some(v.file.sha256.clone()),
+            sha1: None,
+            primary: true,
+        }],
+        required: v.requires.iter().map(|r| r.id.clone()).collect(),
+        blocked: index
+            .revoked(&p.id, &v.file.sha256)
+            .map(|r| format!("taken down: {}", r.reason)),
+    }
+}
+
+/// The words of a query found in a project's id, name, summary or authors.
+fn matches(p: &index::Project, text: &str) -> bool {
+    let hay = format!("{} {} {} {}", p.id, p.name, p.summary, p.authors.join(" ")).to_lowercase();
+    text.split_whitespace()
+        .all(|word| hay.contains(&word.to_lowercase()))
+}
+
+/// The projects of the query's kind whose words match, for this game unless `everything`.
+fn search(index: &Index, query: &Query) -> Vec<Project> {
+    index
+        .projects
+        .iter()
+        .filter(|p| kind_of(&p.kind) == Some(query.kind) && matches(p, &query.text))
+        .filter(|p| query.everything || p.versions.iter().any(|v| v.game == GAME))
+        .filter_map(project_of)
+        .skip(query.offset)
+        .take(query.limit)
+        .collect()
+}
+
+/// The registry as a browser source.
+pub struct Registry;
+
+impl Source for Registry {
+    fn id(&self) -> SourceId {
+        SourceId::Horizon
+    }
+
+    fn search(&self, query: &Query) -> Result<Vec<Project>, String> {
+        Ok(search(&*index()?, query))
+    }
+
+    fn project(&self, id: &str) -> Result<Project, String> {
+        let index = index()?;
+        let p = index
+            .project(id)
+            .ok_or_else(|| format!("{id} isn't in Horizon's registry."))?;
+        project_of(p).ok_or_else(|| {
+            format!(
+                "{} is a {} in Horizon's registry: this launcher can't install those yet.",
+                p.name,
+                p.kind.name()
+            )
+        })
+    }
+
+    fn versions(&self, project: &Project) -> Result<Vec<Version>, String> {
+        let index = index()?;
+        let p = index
+            .project(&project.id)
+            .ok_or_else(|| format!("{} isn't in Horizon's registry.", project.title))?;
+        Ok(p.versions
+            .iter()
+            .map(|v| version_of(&index, p, v))
+            .collect())
+    }
+
+    fn details(&self, project: &Project) -> Result<Details, String> {
+        let index = index()?;
+        let p = index
+            .project(&project.id)
+            .ok_or_else(|| format!("{} isn't in Horizon's registry.", project.title))?;
+        let newest = p.versions.first();
+        let mut body = p.description.clone();
+        if let Some(v) = newest.filter(|v| !v.capabilities.is_empty()) {
+            body.push_str("\n\n## What it may do\n\n");
+            for c in &v.capabilities {
+                body.push_str(&format!("- May {}\n", c.describe()));
+            }
+        }
+        Ok(Details {
+            body,
+            links: vec![
+                Link {
+                    label: "Source".into(),
+                    url: p.source.clone(),
+                },
+                Link {
+                    label: "Page".into(),
+                    url: project.page.clone(),
+                },
+                Link {
+                    label: "Report".into(),
+                    url: format!("{REPORT}&title={}", p.id),
+                },
+            ],
+            authors: p.authors.clone(),
+            published: p
+                .versions
+                .last()
+                .map(|v| v.published.clone())
+                .unwrap_or_default(),
+            updated: newest.map(|v| v.published.clone()).unwrap_or_default(),
+            ..Details::default()
+        })
+    }
+
+    fn fetch(
+        &self,
+        file: &FileRef,
+        folder: &Path,
+        progress: &dyn Fn(f32),
+    ) -> Result<PathBuf, String> {
+        fetch(file, folder, local(), progress)
+    }
+}
+
+/// Downloads a registry file, checked; `file://` files only from a local index.
+fn fetch(
+    file: &FileRef,
+    folder: &Path,
+    local: bool,
+    progress: &dyn Fn(f32),
+) -> Result<PathBuf, String> {
+    match file.url.strip_prefix("file://").filter(|_| local) {
+        Some(path) => {
+            let reader = fs::File::open(path).map_err(|e| format!("{path}: {e}"))?;
+            download::save_from_anywhere(file, reader, folder, progress)
+        }
+        None => download::fetch(file, folder, progress),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/launcher/src/browser/horizon/tests.rs b/launcher/src/browser/horizon/tests.rs
new file mode 100644
index 000000000..1ca0cf3ee
--- /dev/null
+++ b/launcher/src/browser/horizon/tests.rs
@@ -0,0 +1,61 @@
+//! The registry source against the sample index of `horizon_mods::index`
+//! (`crates/horizon-mods/tests/index/`), its files served from disk.
+use super::*;
+
+fn fixtures() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../crates/horizon-mods/tests/index")
+}
+
+/// The sample index with its files on disk, as a local test registry lists them.
+fn sample() -> Index {
+    let text = fs::read_to_string(fixtures().join("index-v1.json")).unwrap();
+    let mut index = Index::parse(&text).unwrap();
+    for p in &mut index.projects {
+        for v in &mut p.versions {
+            let path = fixtures().join(&v.file.name);
+            v.file.url = format!("file://{}", path.canonicalize().unwrap_or(path).display());
+        }
+    }
+    index
+}
+
+fn hud(index: &Index) -> Project {
+    project_of(index.project("coords_hud").unwrap()).unwrap()
+}
+
+#[test]
+fn searches_by_kind_and_words() {
+    let index = sample();
+    let found = |text: &str, kind| -> Vec<String> {
+        search(&index, &Query::new(text, kind))
+            .into_iter()
+            .map(|p| p.id)
+            .collect()
+    };
+    assert_eq!(found("", Kind::Mod), ["coords_hud"]);
+    assert_eq!(found("coordinates HUD", Kind::Mod), ["coords_hud"]);
+    assert!(found("zoom", Kind::Mod).is_empty());
+    // Kinds this launcher can't install yet (modpacks, a world) are never offered.
+    assert!(found("", Kind::Modpack).is_empty());
+    assert!(found("skyblock", Kind::ResourcePack).is_empty());
+    let p = hud(&index);
+    assert_eq!(p.support(), super::super::Support::Works);
+    assert_eq!(p.page, "https://playhorizon.dev/mods/coords_hud");
+}
+
+#[test]
+fn registry_versions_run_when_made_for_this_game() {
+    use super::super::{pick, support, Support};
+    let v = |game: &str| vec![game.to_owned()];
+    let horizon = vec![LOADER.to_owned()];
+    assert_eq!(support(Kind::Mod, &v(GAME), &horizon), Support::Works);
+    assert!(!support(Kind::Mod, &v("26.2"), &horizon).installable());
+    let index = sample();
+    let p = index.project("coords_hud").unwrap();
+    let versions: Vec<Version> = p
+        .versions
+        .iter()
+        .map(|x| version_of(&index, p, x))
+        .collect();
+    assert_eq!(pick(Kind::Mod, &versions, false).unwrap().number, "0.1.0");
+}
diff --git a/launcher/src/browser/installed/tests.rs b/launcher/src/browser/installed/tests.rs
index e940ce0f1..cb2814c29 100644
--- a/launcher/src/browser/installed/tests.rs
+++ b/launcher/src/browser/installed/tests.rs
@@ -86,6 +86,7 @@ impl Fake {
                     .map(|b| format!("{b:02x}"))
                     .collect(),
             ),
+            sha256: None,
             sha1: None,
             primary: true,
         };
diff --git a/launcher/src/browser/java.rs b/launcher/src/browser/java.rs
index 76ce43c95..62122d1f5 100644
--- a/launcher/src/browser/java.rs
+++ b/launcher/src/browser/java.rs
@@ -326,6 +326,7 @@ mod tests {
             name: "a.jar".into(),
             size: 1,
             sha512: sha512.map(str::to_owned),
+            sha256: None,
             sha1: sha1.map(str::to_owned),
             primary: true,
         };
diff --git a/launcher/src/browser/modrinth.rs b/launcher/src/browser/modrinth.rs
index 722549742..52e0aa7f0 100644
--- a/launcher/src/browser/modrinth.rs
+++ b/launcher/src/browser/modrinth.rs
@@ -139,6 +139,7 @@ pub(super) fn parse_version(v: &Value) -> Option<Version> {
                 name: f["filename"].as_str()?.to_owned(),
                 size: f["size"].as_u64().unwrap_or(0),
                 sha512: f["hashes"]["sha512"].as_str().map(str::to_ascii_lowercase),
+                sha256: None,
                 sha1: f["hashes"]["sha1"].as_str().map(str::to_ascii_lowercase),
                 primary: f["primary"].as_bool().unwrap_or(false),
             })
diff --git a/launcher/src/browser/tests.rs b/launcher/src/browser/tests.rs
index 6167d5bd9..50bfbae40 100644
--- a/launcher/src/browser/tests.rs
+++ b/launcher/src/browser/tests.rs
@@ -18,6 +18,7 @@ fn version(id: &str, games: &[&str], loaders: &[&str]) -> Version {
             name: format!("{id}.zip"),
             size: 3,
             sha512: Some("ab".into()),
+            sha256: None,
             sha1: None,
             primary: true,
         }],
@@ -305,6 +306,7 @@ fn file_for(body: &[u8], sha512: bool) -> FileRef {
         name: "pack.zip".into(),
         size: body.len() as u64,
         sha512: sha512.then(|| hex(&sha2::Sha512::digest(body))),
+        sha256: None,
         sha1: (!sha512).then(|| hex(&sha1::Sha1::digest(body))),
         primary: true,
     }
@@ -383,6 +385,6 @@ fn live_modrinth_search_pick_and_download() {
 #[test]
 fn curseforge_is_coming_soon_and_never_searched() {
     let ids: Vec<SourceId> = sources().iter().map(|s| s.id()).collect();
-    assert_eq!(ids, [SourceId::Modrinth]);
+    assert_eq!(ids, [SourceId::Modrinth, SourceId::Horizon]);
     assert!(source(SourceId::CurseForge).is_none());
 }

From b49fd602df9dd5ebe00fa23bfd5316390544d729 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:47:51 +0200
Subject: [PATCH 006/270] Launcher: install from Horizon's registry, enable and
 disable, takedowns

Mods install into horizon-mods/<id>.hmod (turned on) and resource packs into
resourcepacks/, each downloaded to mod-browser/downloads/ and checked by
horizon_mods::index::check_file (size, SHA-256, signature, manifest) before it
is moved into place. Files the index takes down are turned off when the index
is read or the game starts, and can't be installed or turned back on. CLI (and
so MCP): --source horizon, mods enable|disable, and search shows whether a
project is signed and what a mod may do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/launcher-commands.md             |  26 +++-
 docs/mod-browser.md                   |  19 +++
 launcher/src/backend.rs               |   1 +
 launcher/src/browser/horizon.rs       | 202 +++++++++++++++++++++++++-
 launcher/src/browser/horizon/tests.rs |  84 +++++++++++
 launcher/src/browser/installed.rs     |   8 +-
 launcher/src/browser/java.rs          |  10 ++
 launcher/src/cli.rs                   |  52 ++++++-
 8 files changed, 393 insertions(+), 9 deletions(-)

diff --git a/docs/launcher-commands.md b/docs/launcher-commands.md
index 9dc4382f4..7c9562441 100644
--- a/docs/launcher-commands.md
+++ b/docs/launcher-commands.md
@@ -323,7 +323,7 @@ Search for packs Horizon loads.
 - `TEXT`
 - `--kind` (mod, resource, modpack)
 - `--everything`: Also what was made for other versions or runs only partly, each marked
-- `--source` (modrinth, curseforge)
+- `--source` (modrinth, curseforge, horizon)
 
 MCP: `mods_search`.
 
@@ -335,7 +335,7 @@ Say how well a Java mod runs in Horizon: its jar is downloaded (checksum checked
 
 - `PROJECT`
 - `--everything`: Allow a version made for another Minecraft version (1.21 and later)
-- `--source` (modrinth, curseforge)
+- `--source` (modrinth, curseforge, horizon)
 
 MCP: `mods_check`.
 
@@ -347,7 +347,7 @@ Install a pack and what it needs, by its id or slug (checksums checked); a Java
 
 - `PROJECT`
 - `--everything`: Allow a version made for another Minecraft version
-- `--source` (modrinth, curseforge)
+- `--source` (modrinth, curseforge, horizon)
 
 MCP: `mods_install`.
 
@@ -372,6 +372,26 @@ Remove a pack the browser installed.
 
 MCP: `mods_remove`, needs `confirm: true`.
 
+## `horizon-launcher mods enable`
+
+Turn on a mod the browser installed (horizon-mods.txt, as the game's Options > Mods does).
+
+    horizon-launcher mods enable <PROJECT>
+
+- `PROJECT`
+
+MCP: `mods_enable`.
+
+## `horizon-launcher mods disable`
+
+Turn off a mod the browser installed; it stays installed.
+
+    horizon-launcher mods disable <PROJECT>
+
+- `PROJECT`
+
+MCP: `mods_disable`.
+
 ## `horizon-launcher servers list`
 
 The servers, their folder and whether they run.
diff --git a/docs/mod-browser.md b/docs/mod-browser.md
index 7a000cb6c..6c961fd42 100644
--- a/docs/mod-browser.md
+++ b/docs/mod-browser.md
@@ -149,6 +149,25 @@ horizon-launcher mods remove faithful-32x
 
 ## Sources
 
+**Horizon's registry.** Mods (`.hmod`) and resource packs made for Horizon, reviewed as pull requests in
+[ludovic111/horizon-mods](https://github.com/ludovic111/horizon-mods) ([api/mod-index.md](api/mod-index.md)). The
+launcher reads its `index.json` (`browser/horizon.rs`; `HORIZON_MOD_INDEX=<file or https address>` reads a test
+registry instead, whose files may then be on disk) at most every ten minutes, and keeps the last copy in
+`mod-browser/horizon-index.json`. Before a result is installed it shows whether its files are signed and, for a mod,
+what it may do, in the words of the game's Options > Mods. A download goes to `mod-browser/downloads/` and is moved
+into place only after `horizon_mods::index::check_file` passes (size, SHA-256, the author's signature when the project
+has a key, the file's own manifest against the index). A mod becomes `horizon-mods/<id>.hmod`, turned on;
+`mods disable` and `mods enable` switch it in `horizon-mods.txt`. When the index takes a file down, the launcher turns
+it off the next time it reads the index or starts the game, says why, and refuses to install it or turn it back on.
+Horizon modpacks (`.hpack`) and shader packs are listed by the index but not installed by this launcher yet.
+
+```sh
+horizon-launcher mods search --source horizon --kind mod coords   # with whether it is signed and what it may do
+horizon-launcher mods install --source horizon coords_hud
+horizon-launcher mods disable coords_hud
+```
+
+
 **Modrinth.** The public API (`api.modrinth.com/v2`) needs no key. The launcher names itself in its user agent, as
 Modrinth asks.
 
diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 104a086a5..957994f16 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -1636,6 +1636,7 @@ pub fn need_prepared(tag: &str) -> Result<(), String> {
 pub fn client(tag: &str) -> Result<Command, String> {
     need_prepared(tag)?;
     complete_packs(tag);
+    crate::browser::horizon::before_play(&game_home());
     let mut cmd = client_command(tag);
     // A sign-in that can't be renewed (no network, expired) still lets the game start, offline.
     if let Err(e) = crate::account::attach_session(&mut cmd, &game_home()) {
diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index a54bca17f..53e426ab0 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -1,12 +1,13 @@
 //! Horizon's own registry (docs/api/mod-index.md): mods, modpacks and resource packs made for
 //! Horizon, reviewed as pull requests in ludovic111/horizon-mods. One file lists them all,
-//! `index.json`: this is the browser source that searches it and downloads its files, checked
-//! against the SHA-256 it lists. Versions the index says were taken down are blocked.
+//! `index.json`; every download is checked against it before it reaches the game folder
+//! (`horizon_mods::index::check_file`: size, SHA-256, the author's signature, the file's own
+//! manifest), and files the index says were taken down are refused and turned off.
 use super::{
     details::{Details, Link},
-    download, FileRef, Kind, Project, Query, Source, SourceId, Version, GAME,
+    download, installed, java, FileRef, Kind, Project, Query, Source, SourceId, Version, GAME,
 };
-use horizon_mods::index::{self, Index};
+use horizon_mods::index::{self, Index, Trust};
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
@@ -110,6 +111,32 @@ fn kind_of(kind: &index::Kind) -> Option<Kind> {
     }
 }
 
+/// What the player reads about a registry project before installing it: whether its files are
+/// signed, and for a mod what it may do, in the game's words (Options > Mods).
+pub fn trust_and_capabilities(id: &str) -> Vec<String> {
+    let Ok(index) = index() else {
+        return Vec::new();
+    };
+    let Some(p) = index.project(id) else {
+        return Vec::new();
+    };
+    let mut lines = vec![match &p.key {
+        Some(_) => "Signed by its author: the launcher checks the signature".to_owned(),
+        None => "Unsigned: the launcher checks its checksum only".to_owned(),
+    }];
+    if let Some(v) = p.versions.first().filter(|_| p.kind == index::Kind::Mod) {
+        lines.extend(
+            v.capabilities
+                .iter()
+                .map(|c| format!("May {}", c.describe())),
+        );
+        if v.capabilities.is_empty() {
+            lines.push("Asks for nothing beyond its own log".into());
+        }
+    }
+    lines
+}
+
 fn project_of(p: &index::Project) -> Option<Project> {
     let mut game_versions: Vec<String> = p.versions.iter().map(|v| v.game.clone()).collect();
     game_versions.dedup();
@@ -276,5 +303,172 @@ fn fetch(
     }
 }
 
+/// What the registry adds to an installed entry.
+fn trust_label(trust: Trust) -> &'static str {
+    match trust {
+        Trust::Verified => "Verified",
+        Trust::Unsigned => "Unsigned",
+    }
+}
+
+/// The game folder path a registry project's file goes to.
+fn relative(kind: Kind, id: &str, file_name: &str) -> Result<String, String> {
+    match kind {
+        Kind::Mod => Ok(format!("{}/{id}.hmod", java::MODS_DIR)),
+        Kind::ResourcePack => Ok(format!("resourcepacks/{file_name}")),
+        Kind::Modpack => {
+            Err("Modpacks from Horizon's registry install from the Modpacks page.".into())
+        }
+    }
+}
+
+/// Installs a registry project into the game folder `home`: its newest version for this game,
+/// downloaded into `mod-browser/downloads/`, checked against the index, then moved into place.
+/// A mod is `horizon-mods/<id>.hmod`, turned on in `horizon-mods.txt`.
+pub fn install(
+    project: &Project,
+    home: &Path,
+    progress: &dyn Fn(&str, f32),
+) -> Result<Vec<installed::Entry>, String> {
+    install_from(&*index()?, local(), project, home, progress)
+}
+
+fn install_from(
+    index: &Index,
+    local: bool,
+    project: &Project,
+    home: &Path,
+    progress: &dyn Fn(&str, f32),
+) -> Result<Vec<installed::Entry>, String> {
+    let p = index
+        .project(&project.id)
+        .ok_or_else(|| format!("{} isn't in Horizon's registry.", project.title))?;
+    let v = p
+        .versions
+        .iter()
+        .find(|v| v.game == GAME && index.revoked(&p.id, &v.file.sha256).is_none())
+        .ok_or_else(|| format!("{} has no version for {GAME} to install.", project.title))?;
+    let relative = relative(project.kind, &p.id, &v.file.name)?;
+    let mut list = installed::Installed::load(home);
+    let ours = |e: &installed::Entry| e.source == SourceId::Horizon && e.project == p.id;
+    let old = list.entries.iter().find(|e| ours(e)).cloned();
+    if old.as_ref().is_some_and(|o| o.version == v.version) {
+        return Ok(vec![old.expect("checked")]);
+    }
+    let target = home.join(&relative);
+    let taken_by = list.entries.iter().find(|e| !ours(e) && e.file == relative);
+    let folder_mod = home.join(java::MODS_DIR).join(&p.id);
+    if let Some(other) = taken_by {
+        return Err(format!(
+            "{relative} belongs to {}: remove it first.",
+            other.title
+        ));
+    }
+    if (target.exists() && old.as_ref().is_none_or(|o| o.file != relative)) || folder_mod.exists() {
+        return Err(format!(
+            "A mod with the id {} is already in {}: move it away first.",
+            p.id,
+            java::MODS_DIR
+        ));
+    }
+    let line = format!("{} {}", p.name, v.version);
+    let file = &version_of(index, p, v).files[0];
+    let staging = home.join("mod-browser/downloads");
+    let path = fetch(file, &staging, local, &|f| progress(&line, f))?;
+    let trust = index::check_file(index, p, v, &path).inspect_err(|_| {
+        let _ = fs::remove_file(&path);
+    })?;
+    if let Some(dir) = target.parent() {
+        fs::create_dir_all(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
+    }
+    fs::rename(&path, &target).map_err(|e| format!("{}: {e}", target.display()))?;
+    if let Some(old) = old.as_ref().filter(|o| o.file != relative) {
+        let _ = fs::remove_file(home.join(&old.file));
+    }
+    if project.kind == Kind::Mod {
+        java::set_enabled(home, &p.id, true)?;
+    }
+    let entry = installed::Entry {
+        source: SourceId::Horizon,
+        project: p.id.clone(),
+        slug: p.id.clone(),
+        title: p.name.clone(),
+        kind: project.kind,
+        version: v.version.clone(),
+        number: v.version.clone(),
+        file: relative,
+        checksum: format!("SHA-256:{}", v.file.sha256),
+        page: project.page.clone(),
+        dependency: false,
+        verdict: Some(trust_label(trust).into()),
+        skipped: Vec::new(),
+        namespaces: Vec::new(),
+    };
+    list.entries.retain(|e| !ours(e));
+    list.entries.push(entry.clone());
+    list.save(home)?;
+    Ok(vec![entry])
+}
+
+/// The mod id of an installed mod (`horizon-mods/<id>` or `horizon-mods/<id>.hmod`).
+pub fn mod_id(entry: &installed::Entry) -> Option<&str> {
+    let rest = entry.file.strip_prefix(java::MODS_DIR)?.strip_prefix('/')?;
+    Some(rest.strip_suffix(".hmod").unwrap_or(rest))
+}
+
+/// Turns the registry's files that were taken down off in the game folder `home`, and says
+/// which. Their files stay, so the player sees them and can remove them.
+pub fn turn_off_revoked(index: &Index, home: &Path) -> Vec<String> {
+    let mut out = Vec::new();
+    for e in installed::Installed::load(home).entries {
+        let hash = e.checksum.strip_prefix("SHA-256:").unwrap_or_default();
+        let Some(r) = (e.source == SourceId::Horizon)
+            .then(|| index.revoked(&e.project, hash))
+            .flatten()
+        else {
+            continue;
+        };
+        if let (Kind::Mod, Some(id)) = (e.kind, mod_id(&e)) {
+            if java::is_enabled(home, id) && java::set_enabled(home, id, false).is_ok() {
+                out.push(format!(
+                    "{} was taken down and is off: {}",
+                    e.title, r.reason
+                ));
+            }
+        } else if e.kind == Kind::ResourcePack {
+            out.push(format!(
+                "{} was taken down: {} Remove it.",
+                e.title, r.reason
+            ));
+        }
+    }
+    out
+}
+
+/// Before the game starts: registry files taken down are turned off, by the index kept last
+/// time (no waiting on the network), and the index is fetched again in the background for the
+/// next start. Nothing happens when nothing came from the registry.
+pub fn before_play(home: &Path) {
+    let from_registry = installed::Installed::load(home)
+        .entries
+        .iter()
+        .any(|e| e.source == SourceId::Horizon);
+    if !from_registry {
+        return;
+    }
+    let kept = fs::read_to_string(home.join(CACHE)).ok();
+    if let Some(index) = kept.and_then(|t| Index::parse(&t).ok()) {
+        for line in turn_off_revoked(&index, home) {
+            eprintln!("{line}");
+        }
+    }
+    let home = home.to_owned();
+    std::thread::spawn(move || {
+        if let Ok(index) = index() {
+            turn_off_revoked(&index, &home);
+        }
+    });
+}
+
 #[cfg(test)]
 mod tests;
diff --git a/launcher/src/browser/horizon/tests.rs b/launcher/src/browser/horizon/tests.rs
index 1ca0cf3ee..b46d7061d 100644
--- a/launcher/src/browser/horizon/tests.rs
+++ b/launcher/src/browser/horizon/tests.rs
@@ -19,6 +19,16 @@ fn sample() -> Index {
     index
 }
 
+fn scratch(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!(
+        "horizon-launcher-registry-{name}-{}",
+        std::process::id()
+    ));
+    let _ = fs::remove_dir_all(&dir);
+    fs::create_dir_all(&dir).unwrap();
+    dir
+}
+
 fn hud(index: &Index) -> Project {
     project_of(index.project("coords_hud").unwrap()).unwrap()
 }
@@ -43,6 +53,80 @@ fn searches_by_kind_and_words() {
     assert_eq!(p.page, "https://playhorizon.dev/mods/coords_hud");
 }
 
+#[test]
+fn installs_checked_turns_on_and_removes() {
+    let index = sample();
+    let home = scratch("install");
+    let p = hud(&index);
+    let done = install_from(&index, true, &p, &home, &|_, _| {}).unwrap();
+    assert_eq!(done[0].file, "horizon-mods/coords_hud.hmod");
+    assert_eq!(done[0].verdict.as_deref(), Some("Verified"));
+    assert!(done[0].checksum.starts_with("SHA-256:e1135345"));
+    assert!(home.join("horizon-mods/coords_hud.hmod").is_file());
+    let list = fs::read_to_string(home.join("horizon-mods.txt")).unwrap();
+    assert_eq!(list, "mod.coords_hud:true\n");
+    assert_eq!(
+        fs::read_dir(home.join("mod-browser/downloads"))
+            .unwrap()
+            .count(),
+        0
+    );
+    // Installed already: nothing to do.
+    let again = install_from(&index, true, &p, &home, &|_, _| {}).unwrap();
+    assert_eq!(again, done);
+
+    let mut revoked = index.clone();
+    revoked.revoked.push(index::Revoked {
+        id: "coords_hud".into(),
+        sha256: None,
+        reason: "Test.".into(),
+        date: String::new(),
+    });
+    let said = turn_off_revoked(&revoked, &home);
+    assert_eq!(said, ["Coordinates HUD was taken down and is off: Test."]);
+    assert_eq!(
+        fs::read_to_string(home.join("horizon-mods.txt")).unwrap(),
+        ""
+    );
+
+    installed::remove(&home, "coords_hud").unwrap();
+    assert!(!home.join("horizon-mods/coords_hud.hmod").exists());
+    assert!(installed::Installed::load(&home).entries.is_empty());
+    fs::remove_dir_all(&home).unwrap();
+}
+
+#[test]
+fn refuses_a_changed_file_a_taken_id_and_local_files_from_the_real_registry() {
+    let index = sample();
+    let p = hud(&index);
+
+    let home = scratch("tampered");
+    let mut tampered = index.clone();
+    let cozy = tampered.projects[1].versions[0].file.url.clone();
+    tampered.projects[0].versions[0].file.url = cozy;
+    let e = install_from(&tampered, true, &p, &home, &|_, _| {}).unwrap_err();
+    assert!(e.contains("larger than its source says"), "{e}");
+    assert!(!home.join("horizon-mods").exists());
+
+    let e = install_from(&index, false, &p, &home, &|_, _| {}).unwrap_err();
+    assert!(e.contains("file servers"), "{e}");
+
+    fs::create_dir_all(home.join("horizon-mods/coords_hud")).unwrap();
+    let e = install_from(&index, true, &p, &home, &|_, _| {}).unwrap_err();
+    assert!(e.contains("already in horizon-mods"), "{e}");
+
+    let mut taken_down = index.clone();
+    taken_down.revoked.push(index::Revoked {
+        id: "coords_hud".into(),
+        sha256: Some(index.projects[0].versions[0].file.sha256.clone()),
+        reason: "Test.".into(),
+        date: String::new(),
+    });
+    let e = install_from(&taken_down, true, &p, &home, &|_, _| {}).unwrap_err();
+    assert!(e.contains("no version"), "{e}");
+    fs::remove_dir_all(&home).unwrap();
+}
+
 #[test]
 fn registry_versions_run_when_made_for_this_game() {
     use super::super::{pick, support, Support};
diff --git a/launcher/src/browser/installed.rs b/launcher/src/browser/installed.rs
index 451bdd43e..c866dd26d 100644
--- a/launcher/src/browser/installed.rs
+++ b/launcher/src/browser/installed.rs
@@ -170,6 +170,9 @@ pub fn install(
     home: &Path,
     progress: &dyn Fn(&str, f32),
 ) -> Result<Vec<Entry>, String> {
+    if project.source == SourceId::Horizon {
+        return super::horizon::install(project, home, progress);
+    }
     if project.kind == Kind::Mod {
         return super::java::install(source, project, everything, home, progress);
     }
@@ -248,7 +251,7 @@ pub fn remove(home: &Path, name: &str) -> Result<Entry, String> {
         .lookup(name)
         .cloned()
         .ok_or_else(|| format!("{name} wasn't installed by the browser."))?;
-    if entry.kind == Kind::Mod {
+    if entry.kind == Kind::Mod && entry.source != SourceId::Horizon {
         super::java::remove(home, &entry)?;
     } else {
         match fs::remove_file(home.join(&entry.file)) {
@@ -257,6 +260,9 @@ pub fn remove(home: &Path, name: &str) -> Result<Entry, String> {
             Err(e) => return Err(format!("{}: {e}", entry.file)),
         }
     }
+    if let Some(id) = super::horizon::mod_id(&entry).filter(|_| entry.source == SourceId::Horizon) {
+        super::java::set_enabled(home, id, false)?;
+    }
     installed
         .entries
         .retain(|e| !(e.source == entry.source && e.project == entry.project));
diff --git a/launcher/src/browser/java.rs b/launcher/src/browser/java.rs
index 62122d1f5..4ac7ae084 100644
--- a/launcher/src/browser/java.rs
+++ b/launcher/src/browser/java.rs
@@ -110,6 +110,16 @@ pub fn check_project(
     Ok((version, check))
 }
 
+/// Whether mod `id` is on in `horizon-mods.txt`.
+pub fn is_enabled(home: &Path, id: &str) -> bool {
+    let key = format!("mod.{id}");
+    fs::read_to_string(home.join(MODS_LIST))
+        .unwrap_or_default()
+        .lines()
+        .filter_map(|l| l.split_once(':'))
+        .any(|(k, v)| k.trim() == key && v.trim() == "true")
+}
+
 /// Turns mod `id` on (or off) in `horizon-mods.txt`, keeping the other lines.
 pub fn set_enabled(home: &Path, id: &str, on: bool) -> Result<(), String> {
     let path = home.join(MODS_LIST);
diff --git a/launcher/src/cli.rs b/launcher/src/cli.rs
index d104fe7eb..4dd5d2d20 100644
--- a/launcher/src/cli.rs
+++ b/launcher/src/cli.rs
@@ -199,6 +199,10 @@ enum ModsCmd {
     },
     /// Remove a pack the browser installed
     Remove { project: String },
+    /// Turn on a mod the browser installed (horizon-mods.txt, as the game's Options > Mods does)
+    Enable { project: String },
+    /// Turn off a mod the browser installed; it stays installed
+    Disable { project: String },
 }
 
 #[derive(Clone, Copy, clap::ValueEnum)]
@@ -213,6 +217,8 @@ enum SourceArg {
     Modrinth,
     /// CurseForge support is coming soon
     Curseforge,
+    /// Horizon's own registry: mods, modpacks and resource packs made for Horizon, reviewed
+    Horizon,
 }
 
 impl SourceArg {
@@ -221,6 +227,7 @@ impl SourceArg {
         let id = match self {
             SourceArg::Modrinth => SourceId::Modrinth,
             SourceArg::Curseforge => SourceId::CurseForge,
+            SourceArg::Horizon => SourceId::Horizon,
         };
         browser::source(id).ok_or_else(|| browser::CURSEFORGE_SOON.into())
     }
@@ -1064,11 +1071,23 @@ fn servers(action: ServersCmd, as_json: bool) -> Result<(), String> {
 }
 
 fn mods(action: ModsCmd, as_json: bool) -> Result<(), String> {
-    use horizon_launcher::browser::{installed, Kind, Query};
+    use horizon_launcher::browser::{horizon, installed, Kind, Query, SourceId};
     use horizon_launcher::modpacks;
     let home = backend::game_home();
     let entry_json = |e: &installed::Entry| serde_json::to_value(e).unwrap_or_default();
     let line = |label: &str, f: f32| progress(label.to_string())(f);
+    let from_registry = installed::Installed::load(&home)
+        .entries
+        .iter()
+        .any(|e| e.source == SourceId::Horizon);
+    if from_registry {
+        if let Ok(index) = horizon::index() {
+            for said in horizon::turn_off_revoked(&index, &home) {
+                eprintln!("{said}");
+            }
+        }
+    }
+    let on = matches!(action, ModsCmd::Enable { .. });
     match action {
         ModsCmd::List => {
             let list = installed::Installed::load(&home).entries;
@@ -1114,11 +1133,19 @@ fn mods(action: ModsCmd, as_json: bool) -> Result<(), String> {
                         "id": p.id, "slug": p.slug, "title": p.title, "summary": p.summary,
                         "author": p.author, "downloads": p.downloads, "page": p.page,
                         "license": p.license, "support": support.label(), "reason": support.reason(),
+                        "about": if p.source == SourceId::Horizon { horizon::trust_and_capabilities(&p.id) } else { Vec::new() },
                     })
                 }).collect());
             } else {
                 for p in &found {
                     let support = p.support();
+                    if p.source == SourceId::Horizon {
+                        println!("{}  ({})  {}\n  {}", p.title, p.slug, p.author, p.summary);
+                        for line in horizon::trust_and_capabilities(&p.id) {
+                            println!("  {line}");
+                        }
+                        continue;
+                    }
                     let unchecked = p.kind == Kind::Mod && support.installable();
                     println!(
                         "{}  ({})  {} · {} downloads\n  {}",
@@ -1251,6 +1278,29 @@ fn mods(action: ModsCmd, as_json: bool) -> Result<(), String> {
             let e = installed::remove(&home, &project)?;
             println!("Removed {} ({}).", e.title, e.file);
         }
+        ModsCmd::Enable { project } | ModsCmd::Disable { project } => {
+            let e = installed::Installed::load(&home)
+                .lookup(&project)
+                .cloned()
+                .ok_or_else(|| format!("{project} wasn't installed by the browser."))?;
+            let id = horizon::mod_id(&e)
+                .filter(|_| e.kind == Kind::Mod)
+                .ok_or_else(|| format!("{} isn't a mod: only mods turn on and off.", e.title))?;
+            if on {
+                if let Some(r) = horizon::index()
+                    .ok()
+                    .filter(|_| e.source == SourceId::Horizon)
+                    .and_then(|i| {
+                        i.revoked(&e.project, e.checksum.trim_start_matches("SHA-256:"))
+                            .cloned()
+                    })
+                {
+                    return Err(format!("{} was taken down: {}", e.title, r.reason));
+                }
+            }
+            horizon_launcher::browser::java::set_enabled(&home, id, on)?;
+            println!("{} is {}.", e.title, if on { "on" } else { "off" });
+        }
     }
     Ok(())
 }

From f602ad6fe303ccd7aafe18514855b29c1dfa6058 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 21:33:42 +0200
Subject: [PATCH 007/270] Launcher Mods page: Horizon's registry beside
 Modrinth

The source switch now picks Modrinth or Horizon (CurseForge stays coming
soon). On Horizon each result says whether its files are signed and what
the mod may do, in the game's words, before Install; no Java check, no
download count, no Modrinth filters. Installed Horizon mods get an
on/off switch (horizon-mods.txt); one the registry took down is turned
off when the page reads the index and can't be turned back on.
Registry icons load from its GitHub Pages. HORIZON_LAUNCHER_SOURCE=horizon
opens the page on it, for screenshots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/browser/horizon.rs |   9 ++
 launcher/src/browser/images.rs  |   4 +-
 launcher/src/mods_page.rs       | 192 ++++++++++++++++++++++++++++----
 launcher/src/mods_project.rs    |   1 +
 4 files changed, 184 insertions(+), 22 deletions(-)

diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index 53e426ab0..410fdd01e 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -45,6 +45,15 @@ pub fn local() -> bool {
 
 static LOADED: Mutex<Option<(Instant, Arc<Index>)>> = Mutex::new(None);
 
+/// The index read last in this run, without asking the network: for what must not wait.
+pub fn known_index() -> Option<Arc<Index>> {
+    LOADED
+        .lock()
+        .unwrap()
+        .as_ref()
+        .map(|(_, index)| index.clone())
+}
+
 /// The index: the one fetched in the last ten minutes, else fetched again (and kept in the game
 /// folder), else the copy kept last time.
 pub fn index() -> Result<Arc<Index>, String> {
diff --git a/launcher/src/browser/images.rs b/launcher/src/browser/images.rs
index fee2f219e..f5029a7af 100644
--- a/launcher/src/browser/images.rs
+++ b/launcher/src/browser/images.rs
@@ -9,10 +9,12 @@ use std::io::Read;
 use std::path::{Path, PathBuf};
 
 /// Hosts images may come from.
-const HOSTS: [&str; 3] = [
+const HOSTS: [&str; 4] = [
     "https://cdn.modrinth.com/",
     "https://media.forgecdn.net/",
     "https://edge.forgecdn.net/",
+    // Horizon's registry's icons (its GitHub Pages).
+    "https://ludovic111.github.io/horizon-mods/",
 ];
 /// The most an image may weigh before decoding.
 pub const MAX_DOWNLOAD: u64 = 8 << 20;
diff --git a/launcher/src/mods_page.rs b/launcher/src/mods_page.rs
index 86e5e2e48..5e60549a1 100644
--- a/launcher/src/mods_page.rs
+++ b/launcher/src/mods_page.rs
@@ -1,11 +1,13 @@
-//! The Mods page: search Modrinth (CurseForge: coming soon) for Java mods, modpacks and resource
-//! packs, see where each comes from and how well it runs (a Java mod's jar is
-//! checked first), install it with its checksum checked, and update or remove what was installed
-//! (`horizon_launcher::browser`). Imported modpacks are listed on its Modpacks tab.
+//! The Mods page: search Horizon's own registry for mods made for Horizon, or Modrinth
+//! (CurseForge: coming soon) for Java mods, modpacks and resource packs, see where each comes
+//! from and how well it runs (a Java mod's jar is checked first; a Horizon mod says whether it is
+//! signed and what it may do), install it with its checksum checked, turn Horizon mods on and
+//! off, and update or remove what was installed (`horizon_launcher::browser`). Imported modpacks
+//! are listed on its Modpacks tab.
 use super::servers_page::{type_key, Key};
 use super::*;
 use horizon_launcher::browser::{
-    self, installed, java, Kind as PackKind, Project, Query, SourceId, Support,
+    self, horizon, installed, java, Kind as PackKind, Project, Query, SourceId, Support,
 };
 use horizon_launcher::modpacks;
 use horizon_port_pack::check::Check;
@@ -20,7 +22,10 @@ const KINDS: [(PackKind, &str, &str); 3] = [
 /// Java mods checked at once.
 const CHECKING: usize = 2;
 /// The sources to pick from; CurseForge is shown beside them as coming soon.
-const SOURCES: [(SourceId, &str); 1] = [(SourceId::Modrinth, "Modrinth")];
+const SOURCES: [(SourceId, &str); 2] = [
+    (SourceId::Modrinth, "Modrinth"),
+    (SourceId::Horizon, "Horizon"),
+];
 const PAGE: usize = 20;
 
 pub(super) enum Event {
@@ -31,6 +36,10 @@ pub(super) enum Event {
     Updates(HashMap<(SourceId, String), String>),
     /// A Java mod's check: its jar read, or why it couldn't be.
     Checked((SourceId, String), Result<Box<Check>, String>),
+    /// What a Horizon registry project says before install: signed or not, what it may do.
+    About(HashMap<String, Vec<String>>),
+    /// Registry files taken down that the launcher turned off.
+    TakenDown(Vec<String>),
     /// A project page's part, an image or a filter's values (`mods_project`).
     Loaded(super::mods_project::Loaded),
 }
@@ -68,6 +77,8 @@ pub(super) struct Mods {
     confirm_remove: Option<String>,
     /// Java mods' checks, by source and project.
     pub(super) checks: HashMap<(SourceId, String), Checking>,
+    /// Horizon registry projects' trust and capabilities, by id ([`horizon::trust_and_capabilities`]).
+    pub(super) about: HashMap<String, Vec<String>>,
     /// The project page, filters and images.
     pub(super) browse: super::mods_project::Browse,
     pub(super) tx: Sender<Event>,
@@ -94,7 +105,11 @@ impl Mods {
             } else {
                 PackKind::Mod
             },
-            source: SourceId::Modrinth,
+            // `HORIZON_LAUNCHER_SOURCE=horizon` opens on Horizon's registry, for screenshots.
+            source: match std::env::var("HORIZON_LAUNCHER_SOURCE").as_deref() {
+                Ok("horizon") => SourceId::Horizon,
+                _ => SourceId::Modrinth,
+            },
             text: String::new(),
             focus: cx.focus_handle().tab_index(0).tab_stop(true),
             focused: false,
@@ -115,6 +130,7 @@ impl Mods {
             updates: HashMap::new(),
             confirm_remove: None,
             checks: HashMap::new(),
+            about: HashMap::new(),
             browse: Default::default(),
             tx,
             rx,
@@ -134,7 +150,7 @@ impl Mods {
     /// How well a result runs: a Java mod's from its check once it has one.
     pub(super) fn support(&self, p: &Project) -> Support {
         let metadata = p.support();
-        if p.kind != PackKind::Mod || !metadata.installable() {
+        if p.kind != PackKind::Mod || p.source == SourceId::Horizon || !metadata.installable() {
             return metadata;
         }
         match self.checks.get(&(p.source, p.id.clone())) {
@@ -231,6 +247,16 @@ impl Launcher {
                     m.checks.insert(key, state);
                 }
                 Event::Loaded(l) => loaded.push(l),
+                Event::About(about) => {
+                    // Rows grow by a line: measure them again (`cull`).
+                    m.about.extend(about);
+                    m.results_list.reset();
+                }
+                Event::TakenDown(lines) => {
+                    m.message = Some(Ok(lines.join("\n")));
+                    m.installed = installed::Installed::load(&backend::game_home()).entries;
+                    m.installed_list.reset();
+                }
             }
         }
         // `HORIZON_LAUNCHER_PROJECT=<slug>` (with `HORIZON_LAUNCHER_PAGE=mods`): opens that
@@ -278,7 +304,63 @@ impl Launcher {
             let result = browser::source(source)
                 .ok_or_else(|| format!("{} isn't set up.", source.label()))
                 .and_then(|s| s.search(&query));
+            let about: HashMap<String, Vec<String>> = match (&result, source) {
+                (Ok(found), SourceId::Horizon) => found
+                    .iter()
+                    .map(|p| (p.id.clone(), horizon::trust_and_capabilities(&p.id)))
+                    .collect(),
+                _ => HashMap::new(),
+            };
             let _ = tx.send(Event::Found(search, offset, result));
+            if !about.is_empty() {
+                let _ = tx.send(Event::About(about));
+            }
+        });
+    }
+
+    /// Reads the registry's index again when something installed came from it, and turns off
+    /// what it took down since (`horizon::turn_off_revoked`).
+    fn mods_taken_down(&mut self) {
+        if !self
+            .mods
+            .installed
+            .iter()
+            .any(|e| e.source == SourceId::Horizon)
+        {
+            return;
+        }
+        let tx = self.mods.tx.clone();
+        std::thread::spawn(move || {
+            let Ok(index) = horizon::index() else {
+                return;
+            };
+            let lines = horizon::turn_off_revoked(&index, &backend::game_home());
+            if !lines.is_empty() {
+                let _ = tx.send(Event::TakenDown(lines));
+            }
+        });
+    }
+
+    /// Turns a Horizon mod the browser installed on or off, as the game's Options > Mods does.
+    fn mods_switch(&mut self, e: &installed::Entry) {
+        let home = backend::game_home();
+        let Some(id) = horizon::mod_id(e) else {
+            return;
+        };
+        let on = !java::is_enabled(&home, id);
+        let revoked = horizon::known_index().and_then(|index| {
+            let hash = e.checksum.trim_start_matches("SHA-256:");
+            index.revoked(&e.project, hash).map(|r| r.reason.clone())
+        });
+        self.mods.message = Some(match revoked.filter(|_| on) {
+            Some(reason) => Err(format!("{} was taken down: {reason}", e.title)),
+            None => java::set_enabled(&home, id, on).map(|()| {
+                format!(
+                    "{} is {}. The game reads this when it starts.",
+                    e.title,
+                    if on { "on" } else { "off" }
+                )
+            }),
         });
     }
 
@@ -288,7 +370,8 @@ impl Launcher {
         let m = &mut self.mods;
         let todo: Vec<Project> = found
             .into_iter()
-            .filter(|p| p.kind == PackKind::Mod && p.support().installable())
+            .filter(|p| p.kind == PackKind::Mod && p.source != SourceId::Horizon)
+            .filter(|p| p.support().installable())
             .filter(|p| !m.checks.contains_key(&(p.source, p.id.clone())))
             .collect();
         if todo.is_empty() {
@@ -403,6 +486,13 @@ impl Launcher {
                         .iter()
                         .map(|e| format!("{} {}", e.title, e.number))
                         .collect();
+                    if p.source == SourceId::Horizon && p.kind == PackKind::Mod {
+                        return Ok(format!(
+                            "Installed {} into horizon-mods and turned it on, checksum checked \
+                             (Options > Mods in the game).",
+                            names.join(", ")
+                        ));
+                    }
                     if p.kind == PackKind::Mod {
                         let skipped = done.last().map_or(0, |e| e.skipped.len());
                         return Ok(format!(
@@ -497,14 +587,15 @@ impl Launcher {
             self.mods.loaded = true;
             self.mods.installed = installed::Installed::load(&backend::game_home()).entries;
             self.mods_check_updates();
+            self.mods_taken_down();
             self.mods_search(0);
         }
         let header = page_header(
             "Mods",
-            "Java mods, modpacks and resource packs. Horizon ports what a Java mod \
-             carries (blocks, items, recipes, worldgen) and says before you install what runs. \
-             Each file is checked against its source's checksum before it reaches your game \
-             folder.",
+            "Mods made for Horizon from its own reviewed registry, and Java mods, modpacks and \
+             resource packs from Modrinth: Horizon ports what a Java mod carries (blocks, items, \
+             recipes, worldgen) and says before you install what runs. Each file is checked \
+             against its source's checksum before it reaches your game folder.",
             &t,
         );
         let this = cx.entity().downgrade();
@@ -543,7 +634,10 @@ impl Launcher {
             }));
         // CurseForge support is coming soon: shown, inert, never searched (like the Microsoft
         // account's "Coming soon").
-        let source_note = div().flex().child(source_switch(&t));
+        let source_note = div().flex().child(self.mods_source_switch(cx));
+        // The registry lists only what was made for Horizon: no "everything", no Modrinth filters.
+        let registry = self.mods.source == SourceId::Horizon;
+        let filters = (!registry).then(|| self.mods_filters(cx));
         let controls = div()
             .flex()
             .flex_col()
@@ -555,10 +649,10 @@ impl Launcher {
                     .items_center()
                     .gap(px(12.))
                     .child(self.mods_field(cx))
-                    .child(toggle),
+                    .when(!registry, |d| d.child(toggle)),
             )
             .child(source_note)
-            .child(self.mods_filters(cx));
+            .children(filters);
         // The kinds are inventory tabs on the panel that holds the open one.
         let body = blocks::panel(&t).flex().flex_col().gap(px(24.)).p(px(20.));
         let page = |body: Div| {
@@ -687,6 +781,30 @@ impl Launcher {
                 }
                 cx.notify();
             }));
+            if e.source == SourceId::Horizon && e.kind == PackKind::Mod {
+                let on = horizon::mod_id(e)
+                    .is_some_and(|id| java::is_enabled(&backend::game_home(), id));
+                let entry = e.clone();
+                right = right.child(
+                    div()
+                        .id(SharedString::from(format!("mods-switch-{}", e.project)))
+                        .flex()
+                        .items_center()
+                        .gap(px(8.))
+                        .cursor_pointer()
+                        // Its id sits under the row's own, so one name serves every row.
+                        .child(switch("mods-switch-knob", on, &t))
+                        .child(text(theme::LABEL).text_color(t.ink_soft).child(if on {
+                            "On"
+                        } else {
+                            "Off"
+                        }))
+                        .on_click(cx.listener(move |this, _: &ClickEvent, _, cx| {
+                            this.mods_switch(&entry);
+                            cx.notify();
+                        })),
+                );
+            }
             right = right.child(remove);
             let detail = div()
                 .flex()
@@ -750,6 +868,8 @@ impl Launcher {
         if m.results.is_empty() {
             let line = if m.searching || !m.searched {
                 "Searching…"
+            } else if m.source == SourceId::Horizon {
+                "Nothing in Horizon's registry matches yet."
             } else if m.everything {
                 "Nothing found."
             } else {
@@ -768,6 +888,7 @@ impl Launcher {
             let busy = m.busy.as_ref().map(|b| b.0.as_str());
             let support = m.support(p);
             let checking = p.kind == PackKind::Mod
+                && p.source != SourceId::Horizon
                 && matches!(
                     m.checks.get(&(p.source, p.id.clone())),
                     None | Some(Checking::Running)
@@ -828,7 +949,9 @@ impl Launcher {
             if !p.author.is_empty() {
                 by.push(format!("by {}", p.author));
             }
-            by.push(format!("{} downloads", count(p.downloads)));
+            if p.source != SourceId::Horizon {
+                by.push(format!("{} downloads", count(p.downloads)));
+            }
             by.push(format!("from {}", p.source.label()));
             if !p.license.is_empty() {
                 by.push(p.license.clone());
@@ -842,6 +965,12 @@ impl Launcher {
                     support
                         .reason()
                         .map(|r| div().text_color(t.ink_soft).child(r.to_string())),
+                )
+                .children(
+                    m.about
+                        .get(&p.id)
+                        .filter(|_| p.source == SourceId::Horizon)
+                        .map(|lines| div().text_color(t.ink_soft).child(lines.join(" · "))),
                 );
             let open = p.clone();
             let name = div()
@@ -884,9 +1013,30 @@ impl Launcher {
     }
 }
 
-/// The source switch while Modrinth is the only source: Modrinth chosen, CurseForge shown as
-/// coming soon and not clickable, like the Microsoft account's "Coming soon".
-fn source_switch(t: &Theme) -> Stateful<Div> {
+impl Launcher {
+    /// The source switch: Modrinth or Horizon's registry, CurseForge shown as coming soon and not
+    /// clickable, like the Microsoft account's "Coming soon".
+    fn mods_source_switch(&self, cx: &mut Context<Self>) -> Stateful<Div> {
+        let this = cx.entity().downgrade();
+        source_switch(&self.theme, self.mods.source, move |source, _, cx| {
+            let _ = this.update(cx, |this, cx| {
+                if this.mods.source != source {
+                    this.mods.source = source;
+                    this.mods.browse.filters = Default::default();
+                    this.mods.browse.open = None;
+                    this.mods_search(0);
+                }
+                cx.notify();
+            });
+        })
+    }
+}
+
+fn source_switch(
+    t: &Theme,
+    current: SourceId,
+    on_pick: impl Fn(SourceId, &mut Window, &mut App) + Clone + 'static,
+) -> Stateful<Div> {
     let soon = div()
         .flex()
         .items_center()
@@ -899,7 +1049,7 @@ fn source_switch(t: &Theme) -> Stateful<Div> {
                 .text_color(t.muted)
                 .child("CurseForge (coming soon)"),
         );
-    segments("mods-source", &SOURCES, SourceId::Modrinth, t, |_, _, _| {}).child(soon)
+    segments("mods-source", &SOURCES, current, t, on_pick).child(soon)
 }
 
 #[cfg(test)]
diff --git a/launcher/src/mods_project.rs b/launcher/src/mods_project.rs
index ad75f58cd..97d23e0aa 100644
--- a/launcher/src/mods_project.rs
+++ b/launcher/src/mods_project.rs
@@ -423,6 +423,7 @@ impl Launcher {
             self.mods.checks.get(&(p.source, p.id.clone())),
             None | Some(Checking::Running)
         ) && p.kind == PackKind::Mod
+            && p.source != SourceId::Horizon
             && p.support().installable();
         let mut action = div().flex().items_center().gap(px(8.)).child(
             caps(if checking {

From dbdc0389fe9ce9d46911f7f0b8bff12b83eb7607 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sat, 24 Oct 2026 22:25:02 +0200
Subject: [PATCH 008/270] Launcher: Horizon modpacks from the registry, each
 its own profile

A registry modpack (.hpack) now shows under Modpacks with the Horizon
source, with its mods and what each may do, and installs into
horizon-packs/<id>/: the checked pack, pack.json and home/, where each of
its mods is downloaded and checked like any registry mod (pinned to the
pack's version and SHA-256) and turned on or off as the pack says. Its
overrides are copied on the first install only. A pack whose mod was taken
down installs nothing and leaves nothing behind. The Modpacks tab lists
installed registry packs with Play and Remove (confirmed); they play through
modpacks::apply_profile with their own HORIZON_HOME, taken-down mods turned
off first. CLI: `mods install --source horizon <pack>`, and `modpack
list|play|remove` see registry packs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/mod-browser.md                   |   9 +-
 launcher/src/browser/horizon.rs       |  65 ++++--
 launcher/src/browser/horizon/pack.rs  | 294 ++++++++++++++++++++++++++
 launcher/src/browser/horizon/tests.rs |   4 +-
 launcher/src/cli.rs                   |  40 +++-
 launcher/src/main.rs                  |   3 +
 launcher/src/modpacks.rs              |   8 +
 launcher/src/modpacks_page.rs         |  80 +++++++
 launcher/src/mods_page.rs             |  10 +
 9 files changed, 497 insertions(+), 16 deletions(-)
 create mode 100644 launcher/src/browser/horizon/pack.rs

diff --git a/docs/mod-browser.md b/docs/mod-browser.md
index 6c961fd42..a803420c3 100644
--- a/docs/mod-browser.md
+++ b/docs/mod-browser.md
@@ -159,12 +159,19 @@ into place only after `horizon_mods::index::check_file` passes (size, SHA-256, t
 has a key, the file's own manifest against the index). A mod becomes `horizon-mods/<id>.hmod`, turned on;
 `mods disable` and `mods enable` switch it in `horizon-mods.txt`. When the index takes a file down, the launcher turns
 it off the next time it reads the index or starts the game, says why, and refuses to install it or turn it back on.
-Horizon modpacks (`.hpack`) and shader packs are listed by the index but not installed by this launcher yet.
+A Horizon modpack (`.hpack`) installs as its own profile (`browser/horizon/pack.rs`): `horizon-packs/<id>/` holds the
+checked pack, `pack.json` and `home/`, the profile's game folder, where each of the pack's mods is downloaded and checked
+like any registry mod and turned on or off as the pack says; its overrides (settings, resource packs, a mod's saved
+settings) are copied in on the first install only, so the player's changes survive updates. A pack whose mod was taken
+down installs nothing. It is listed on the Modpacks tab with **Play** and **Remove**, and plays like an imported pack
+(`modpacks::apply_profile`). Shader packs are listed by the index but not installed by this launcher yet.
 
 ```sh
 horizon-launcher mods search --source horizon --kind mod coords   # with whether it is signed and what it may do
 horizon-launcher mods install --source horizon coords_hud
 horizon-launcher mods disable coords_hud
+horizon-launcher mods install --source horizon cozy               # a modpack: its own profile
+horizon-launcher modpack play cozy
 ```
 
 
diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index 410fdd01e..5333e481d 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -111,12 +111,13 @@ fn fetch_index() -> Result<(Index, String), String> {
 }
 
 /// The browser's kind for a registry kind; None for one the launcher doesn't install yet
-/// (Horizon modpacks and shader packs, kinds newer than this launcher).
+/// (shader packs, kinds newer than this launcher).
 fn kind_of(kind: &index::Kind) -> Option<Kind> {
     match kind {
         index::Kind::Mod => Some(Kind::Mod),
         index::Kind::ResourcePack => Some(Kind::ResourcePack),
-        index::Kind::Modpack | index::Kind::Shader | index::Kind::Other(_) => None,
+        index::Kind::Modpack => Some(Kind::Modpack),
+        index::Kind::Shader | index::Kind::Other(_) => None,
     }
 }
 
@@ -259,6 +260,23 @@ impl Source for Registry {
                 body.push_str(&format!("- May {}\n", c.describe()));
             }
         }
+        if let Some(v) = newest.filter(|v| !v.requires.is_empty()) {
+            body.push_str(
+                "\n\n## Its mods\n\nInstalled with it into its own profile, each checked:\n\n",
+            );
+            for r in &v.requires {
+                let found = index
+                    .project(&r.id)
+                    .and_then(|m| Some((m, m.versions.iter().find(|w| w.version == r.version)?)));
+                let Some((m, w)) = found else { continue };
+                let may: Vec<&str> = w.capabilities.iter().map(|c| c.describe()).collect();
+                let may = match may.is_empty() {
+                    true => String::new(),
+                    false => format!(": may {}", may.join(", ")),
+                };
+                body.push_str(&format!("- {} {}{may}\n", m.name, w.version));
+            }
+        }
         Ok(Details {
             body,
             links: vec![
@@ -325,9 +343,7 @@ fn relative(kind: Kind, id: &str, file_name: &str) -> Result<String, String> {
     match kind {
         Kind::Mod => Ok(format!("{}/{id}.hmod", java::MODS_DIR)),
         Kind::ResourcePack => Ok(format!("resourcepacks/{file_name}")),
-        Kind::Modpack => {
-            Err("Modpacks from Horizon's registry install from the Modpacks page.".into())
-        }
+        Kind::Modpack => Err("A modpack installs as its own profile (pack::install).".into()),
     }
 }
 
@@ -352,17 +368,37 @@ fn install_from(
     let p = index
         .project(&project.id)
         .ok_or_else(|| format!("{} isn't in Horizon's registry.", project.title))?;
-    let v = p
-        .versions
+    let v = newest(index, p)?;
+    install_version(index, local, p, v, home, progress).map(|e| vec![e])
+}
+
+/// A project's newest version for this game that wasn't taken down.
+fn newest<'a>(index: &Index, p: &'a index::Project) -> Result<&'a index::Version, String> {
+    p.versions
         .iter()
         .find(|v| v.game == GAME && index.revoked(&p.id, &v.file.sha256).is_none())
-        .ok_or_else(|| format!("{} has no version for {GAME} to install.", project.title))?;
+        .ok_or_else(|| format!("{} has no version for {GAME} to install.", p.name))
+}
+
+/// Installs version `v` of the registry's mod or resource pack `p` into the game folder `home`.
+fn install_version(
+    index: &Index,
+    local: bool,
+    p: &index::Project,
+    v: &index::Version,
+    home: &Path,
+    progress: &dyn Fn(&str, f32),
+) -> Result<installed::Entry, String> {
+    let project = project_of(p).ok_or_else(|| format!("{} can't be installed here.", p.name))?;
+    if let Some(r) = index.revoked(&p.id, &v.file.sha256) {
+        return Err(format!("{} was taken down: {}", p.name, r.reason));
+    }
     let relative = relative(project.kind, &p.id, &v.file.name)?;
     let mut list = installed::Installed::load(home);
     let ours = |e: &installed::Entry| e.source == SourceId::Horizon && e.project == p.id;
     let old = list.entries.iter().find(|e| ours(e)).cloned();
     if old.as_ref().is_some_and(|o| o.version == v.version) {
-        return Ok(vec![old.expect("checked")]);
+        return Ok(old.expect("checked"));
     }
     let target = home.join(&relative);
     let taken_by = list.entries.iter().find(|e| !ours(e) && e.file == relative);
@@ -416,7 +452,7 @@ fn install_from(
     list.entries.retain(|e| !ours(e));
     list.entries.push(entry.clone());
     list.save(home)?;
-    Ok(vec![entry])
+    Ok(entry)
 }
 
 /// The mod id of an installed mod (`horizon-mods/<id>` or `horizon-mods/<id>.hmod`).
@@ -465,8 +501,12 @@ pub fn before_play(home: &Path) {
     if !from_registry {
         return;
     }
-    let kept = fs::read_to_string(home.join(CACHE)).ok();
-    if let Some(index) = kept.and_then(|t| Index::parse(&t).ok()) {
+    let kept = fs::read_to_string(crate::backend::game_home().join(CACHE)).ok();
+    let parse = |t: String| match local() {
+        true => Index::parse_local(&t).ok(),
+        false => Index::parse(&t).ok(),
+    };
+    if let Some(index) = kept.and_then(parse) {
         for line in turn_off_revoked(&index, home) {
             eprintln!("{line}");
         }
@@ -479,5 +519,6 @@ pub fn before_play(home: &Path) {
     });
 }
 
+pub mod pack;
 #[cfg(test)]
 mod tests;
diff --git a/launcher/src/browser/horizon/pack.rs b/launcher/src/browser/horizon/pack.rs
new file mode 100644
index 000000000..73dcd0cc1
--- /dev/null
+++ b/launcher/src/browser/horizon/pack.rs
@@ -0,0 +1,294 @@
+//! Horizon modpacks from the registry (`.hpack`, docs/api/mod-index.md), each played as its own
+//! profile: `horizon-packs/<id>/` in the game's home holds the pack's file, `pack.json` (what
+//! was installed) and `home/`, the profile's game folder: its saves, its options, and the pack's
+//! mods in `home/horizon-mods/`, each downloaded and checked against the index like any
+//! registry mod, turned on or off as the pack says. The pack's overrides (settings, resource
+//! packs, a mod's saved settings) are copied in once, when it is installed.
+use super::{fetch, index, install_version, local, newest, Index};
+use crate::browser::{java, FileRef};
+use horizon_mods::{index as idx, modpack::Modpack};
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+const RECORD: &str = "pack.json";
+
+/// Where registry modpacks live.
+pub fn packs_dir() -> PathBuf {
+    crate::backend::game_home().join("horizon-packs")
+}
+
+/// What `pack.json` keeps of an installed pack.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Installed {
+    pub id: String,
+    pub name: String,
+    pub version: String,
+    pub sha256: String,
+    /// The pack's mods: `id version`.
+    pub mods: Vec<String>,
+    #[serde(skip)]
+    pub work: PathBuf,
+}
+
+/// The installed registry packs, by name.
+pub fn list() -> Vec<Installed> {
+    list_in(&packs_dir())
+}
+
+fn list_in(dir: &Path) -> Vec<Installed> {
+    let mut packs: Vec<Installed> = fs::read_dir(dir)
+        .into_iter()
+        .flatten()
+        .flatten()
+        .filter_map(|e| read(&e.path()))
+        .collect();
+    packs.sort_by_key(|p| p.name.to_lowercase());
+    packs
+}
+
+fn read(work: &Path) -> Option<Installed> {
+    let text = fs::read_to_string(work.join(RECORD)).ok()?;
+    let mut pack: Installed = serde_json::from_str(&text).ok()?;
+    pack.work = work.to_path_buf();
+    Some(pack)
+}
+
+/// Whether `work` is a registry pack's folder.
+pub fn is_pack(work: &Path) -> bool {
+    work.join(RECORD).is_file()
+}
+
+/// The profile's game folder.
+pub fn home(work: &Path) -> PathBuf {
+    work.join("home")
+}
+
+/// Installs the registry modpack `id`: its newest version for this game, then each of its mods.
+/// Installing it again updates it; its saves and options stay.
+pub fn install(id: &str, progress: &dyn Fn(&str, f32)) -> Result<Installed, String> {
+    install_in(&*index()?, local(), id, &packs_dir(), progress)
+}
+
+fn install_in(
+    index: &Index,
+    local: bool,
+    id: &str,
+    dir: &Path,
+    progress: &dyn Fn(&str, f32),
+) -> Result<Installed, String> {
+    let p = index
+        .project(id)
+        .ok_or_else(|| format!("{id} isn't in Horizon's registry."))?;
+    if p.kind != idx::Kind::Modpack {
+        return Err(format!("{} is a {}, not a modpack.", p.name, p.kind.name()));
+    }
+    let v = newest(index, p)?;
+    let work = dir.join(&p.id);
+    let fresh = !work.exists();
+    let result = install_version_in(index, local, p, v, &work, progress);
+    if result.is_err() && fresh {
+        let _ = fs::remove_dir_all(&work);
+    }
+    result
+}
+
+fn install_version_in(
+    index: &Index,
+    local: bool,
+    p: &idx::Project,
+    v: &idx::Version,
+    work: &Path,
+    progress: &dyn Fn(&str, f32),
+) -> Result<Installed, String> {
+    let line = format!("{} {}", p.name, v.version);
+    let file = FileRef {
+        url: v.file.url.clone(),
+        name: v.file.name.clone(),
+        size: v.file.size,
+        sha512: None,
+        sha256: Some(v.file.sha256.clone()),
+        sha1: None,
+        primary: true,
+    };
+    let path = fetch(&file, &work.join("downloads"), local, &|f| {
+        progress(&line, f)
+    })?;
+    idx::check_file(index, p, v, &path).inspect_err(|_| {
+        let _ = fs::remove_file(&path);
+    })?;
+    let pack = Modpack::read(&path)?;
+    let home = home(work);
+    fs::create_dir_all(&home).map_err(|e| format!("{}: {e}", home.display()))?;
+    let mut mods = Vec::new();
+    for m in &pack.manifest.mods {
+        let found = index
+            .project(&m.id)
+            .and_then(|mp| Some((mp, mp.versions.iter().find(|w| w.version == m.version)?)));
+        let Some((mp, mv)) = found.filter(|(_, mv)| mv.file.sha256 == m.sha256) else {
+            return Err(format!(
+                "{} needs {} {}, which isn't in the registry.",
+                p.name, m.id, m.version
+            ));
+        };
+        install_version(index, local, mp, mv, &home, progress)?;
+        java::set_enabled(&home, &m.id, m.on)?;
+        mods.push(format!("{} {}", m.id, m.version));
+    }
+    // Settings once: the player's own changes to the profile stay on updates.
+    let first = !work.join(RECORD).exists();
+    if first {
+        Modpack::extract_overrides(&path, &home)?;
+    }
+    let kept = work.join(&v.file.name);
+    fs::rename(&path, &kept).map_err(|e| format!("{}: {e}", kept.display()))?;
+    let record = Installed {
+        id: p.id.clone(),
+        name: p.name.clone(),
+        version: v.version.clone(),
+        sha256: v.file.sha256.clone(),
+        mods,
+        work: work.to_path_buf(),
+    };
+    let text = serde_json::to_string_pretty(&record).map_err(|e| e.to_string())?;
+    fs::write(work.join(RECORD), text).map_err(|e| e.to_string())?;
+    Ok(record)
+}
+
+/// Turns the game's command into the pack's profile: its own game folder (the player's
+/// options.txt copied in when the pack brings none), its taken-down mods turned off first.
+pub fn apply(cmd: &mut Command, work: &Path) -> Result<(), String> {
+    if !is_pack(work) {
+        return Err(format!("{} is not an installed modpack.", work.display()));
+    }
+    let home = home(work);
+    fs::create_dir_all(&home).map_err(|e| format!("{}: {e}", home.display()))?;
+    let options = home.join("options.txt");
+    let own = crate::backend::game_home().join("options.txt");
+    if !options.exists() && own.is_file() {
+        let _ = fs::copy(own, &options);
+    }
+    super::before_play(&home);
+    cmd.current_dir(&home).env("HORIZON_HOME", &home);
+    Ok(())
+}
+
+/// Removes an installed pack: its mods and the profile's saves.
+pub fn remove(work: &Path) -> Result<(), String> {
+    if work.parent() != Some(packs_dir().as_path()) || !is_pack(work) {
+        return Err(format!("{} is not an installed modpack.", work.display()));
+    }
+    fs::remove_dir_all(work).map_err(|e| format!("{}: {e}", work.display()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+
+    /// A local registry: the mod and a pack of it, as `file://` files.
+    fn registry(dir: &Path, on: bool, extra: &str) -> Index {
+        let hmod_src = Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("../crates/horizon-mods/tests/index/coords_hud-0.1.0.hmod");
+        let hmod = dir.join("coords_hud-0.1.0.hmod");
+        fs::copy(hmod_src, &hmod).unwrap();
+        let hmod_sha = idx::sha256_file(&hmod).unwrap();
+        let hpack = dir.join("cozy-1.0.0.hpack");
+        let mut zip = zip::ZipWriter::new(fs::File::create(&hpack).unwrap());
+        let o = zip::write::SimpleFileOptions::default();
+        zip.start_file("horizon-modpack.toml", o).unwrap();
+        write!(
+            zip,
+            "format = 1\nid = \"cozy\"\nname = \"Cozy\"\nversion = \"1.0.0\"\ngame = \"26.3\"\n\
+             [[mods]]\nid = \"coords_hud\"\nversion = \"0.1.0\"\nsha256 = \"{hmod_sha}\"\non = {on}\n"
+        )
+        .unwrap();
+        zip.start_file("overrides/options.txt", o).unwrap();
+        zip.write_all(b"renderDistance:8\n").unwrap();
+        zip.finish().unwrap();
+        let size = |p: &Path| fs::metadata(p).unwrap().len();
+        let text = format!(
+            r#"{{"schema": 1, "projects": [
+              {{"id": "coords_hud", "kind": "mod", "name": "Coordinates HUD", "summary": "", "license": "MIT",
+                "source": "https://x.test", "versions": [{{"version": "0.1.0", "api": "0.1", "side": "client",
+                "capabilities": ["game-read", "hud", "chat"], "game": "26.3", "file": {{"name": "coords_hud-0.1.0.hmod",
+                "url": "file://{}", "size": {}, "sha256": "{hmod_sha}"}}}}]}},
+              {{"id": "cozy", "kind": "modpack", "name": "Cozy", "summary": "", "license": "MIT",
+                "source": "https://x.test", "versions": [{{"version": "1.0.0", "api": "1", "game": "26.3",
+                "requires": [{{"id": "coords_hud", "version": "0.1.0", "sha256": "{hmod_sha}"}}],
+                "file": {{"name": "cozy-1.0.0.hpack", "url": "file://{}", "size": {}, "sha256": "{}"}}}}]}}
+            ]{extra}}}"#,
+            hmod.display(),
+            size(&hmod),
+            hpack.display(),
+            size(&hpack),
+            idx::sha256_file(&hpack).unwrap()
+        );
+        Index::parse_local(&text).unwrap()
+    }
+
+    fn scratch(name: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "horizon-launcher-hpack-{name}-{}",
+            std::process::id()
+        ));
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn a_pack_installs_as_a_profile_with_its_mods() {
+        let dir = scratch("install");
+        let index = registry(&dir, false, "");
+        let packs = dir.join("horizon-packs");
+        let pack = install_in(&index, true, "cozy", &packs, &|_, _| {}).unwrap();
+        assert_eq!(pack.mods, ["coords_hud 0.1.0"]);
+        let home = home(&packs.join("cozy"));
+        assert!(home.join("horizon-mods/coords_hud.hmod").is_file());
+        assert!(
+            !java::is_enabled(&home, "coords_hud"),
+            "the pack turns it off"
+        );
+        assert_eq!(
+            fs::read_to_string(home.join("options.txt")).unwrap(),
+            "renderDistance:8\n"
+        );
+        assert_eq!(
+            list_in(&packs),
+            [Installed {
+                work: packs.join("cozy"),
+                ..pack
+            }]
+        );
+        // Settings the player changed stay on an update.
+        fs::write(home.join("options.txt"), "renderDistance:12\n").unwrap();
+        install_in(&index, true, "cozy", &packs, &|_, _| {}).unwrap();
+        assert_eq!(
+            fs::read_to_string(home.join("options.txt")).unwrap(),
+            "renderDistance:12\n"
+        );
+        // Not a modpack, and not there.
+        assert!(install_in(&index, true, "coords_hud", &packs, &|_, _| {})
+            .unwrap_err()
+            .contains("not a modpack"));
+        assert!(install_in(&index, true, "nope", &packs, &|_, _| {}).is_err());
+        fs::remove_dir_all(&dir).unwrap();
+    }
+
+    #[test]
+    fn a_pack_with_a_taken_down_mod_installs_nothing() {
+        let dir = scratch("revoked");
+        let index = registry(
+            &dir,
+            true,
+            r#", "revoked": [{"id": "coords_hud", "reason": "Test."}]"#,
+        );
+        let packs = dir.join("horizon-packs");
+        let e = install_in(&index, true, "cozy", &packs, &|_, _| {}).unwrap_err();
+        assert!(e.contains("taken down: Test."), "{e}");
+        assert!(!packs.join("cozy").exists(), "nothing left behind");
+        fs::remove_dir_all(&dir).unwrap();
+    }
+}
diff --git a/launcher/src/browser/horizon/tests.rs b/launcher/src/browser/horizon/tests.rs
index b46d7061d..caff9cd99 100644
--- a/launcher/src/browser/horizon/tests.rs
+++ b/launcher/src/browser/horizon/tests.rs
@@ -45,8 +45,8 @@ fn searches_by_kind_and_words() {
     assert_eq!(found("", Kind::Mod), ["coords_hud"]);
     assert_eq!(found("coordinates HUD", Kind::Mod), ["coords_hud"]);
     assert!(found("zoom", Kind::Mod).is_empty());
-    // Kinds this launcher can't install yet (modpacks, a world) are never offered.
-    assert!(found("", Kind::Modpack).is_empty());
+    // Modpacks under Modpacks; a kind this launcher can't install yet (a world) never.
+    assert_eq!(found("", Kind::Modpack), ["cozy"]);
     assert!(found("skyblock", Kind::ResourcePack).is_empty());
     let p = hud(&index);
     assert_eq!(p.support(), super::super::Support::Works);
diff --git a/launcher/src/cli.rs b/launcher/src/cli.rs
index 4dd5d2d20..25bbe0bee 100644
--- a/launcher/src/cli.rs
+++ b/launcher/src/cli.rs
@@ -1214,6 +1214,23 @@ fn mods(action: ModsCmd, as_json: bool) -> Result<(), String> {
         } => {
             let source = source.get()?;
             let p = source.project(&project)?;
+            if p.kind == Kind::Modpack && p.source == SourceId::Horizon {
+                let pack = horizon::pack::install(&p.id, &line)?;
+                if as_json {
+                    json(
+                        serde_json::json!({"pack": pack.id, "version": pack.version, "mods": pack.mods, "home": horizon::pack::home(&pack.work)}),
+                    );
+                } else {
+                    println!(
+                        "{} {} is installed as its own profile, with {}.",
+                        pack.name,
+                        pack.version,
+                        pack.mods.join(", ")
+                    );
+                    println!("Play it: horizon-launcher modpack play {}", pack.id);
+                }
+                return Ok(());
+            }
             if p.kind == Kind::Modpack {
                 let folder = modpacks::ports_dir().join("downloads");
                 let file =
@@ -1306,10 +1323,15 @@ fn mods(action: ModsCmd, as_json: bool) -> Result<(), String> {
 }
 
 fn modpack(action: ModpackCmd, as_json: bool) -> Result<(), String> {
+    use horizon_launcher::browser::horizon;
     use horizon_launcher::modpacks::{self, Imported};
     use horizon_port_pack::report::Status;
     let log = &|line: String| eprintln!("{line}");
     let work = |pack: &str| {
+        let registry = horizon::pack::packs_dir().join(pack);
+        if horizon::pack::is_pack(&registry) {
+            return Ok(registry);
+        }
         let work = modpacks::ports_dir().join(pack);
         modpacks::load(&work).map(|_| work)
     };
@@ -1343,10 +1365,26 @@ fn modpack(action: ModpackCmd, as_json: bool) -> Result<(), String> {
     match action {
         ModpackCmd::List => {
             let packs = modpacks::list();
-            if packs.is_empty() && !as_json {
+            let registry = horizon::pack::list();
+            if packs.is_empty() && registry.is_empty() && !as_json {
                 println!("No modpack imported yet: horizon-launcher modpack import <pack>");
             }
             packs.iter().for_each(show);
+            for p in &registry {
+                if as_json {
+                    json(
+                        serde_json::json!({"pack": p.id, "name": p.name, "version": p.version, "source": "horizon", "mods": p.mods}),
+                    );
+                } else {
+                    println!(
+                        "{} {}  ({}, from Horizon's registry)\n  {}",
+                        p.name,
+                        p.version,
+                        p.id,
+                        p.mods.join(", ")
+                    );
+                }
+            }
         }
         ModpackCmd::Import { path } => show(&modpacks::import(&path, log)?),
         ModpackCmd::Port {
diff --git a/launcher/src/main.rs b/launcher/src/main.rs
index 4a68ecdef..7aaeb8d9b 100644
--- a/launcher/src/main.rs
+++ b/launcher/src/main.rs
@@ -202,6 +202,8 @@ struct Launcher {
     /// The Modpacks page: the imported packs (read when the page first opens), the one shown,
     /// the report's filter, and the pipeline step running now with its log.
     packs: Vec<horizon_launcher::modpacks::Imported>,
+    /// Modpacks installed from Horizon's registry, each its own profile.
+    registry_packs: Vec<horizon_launcher::browser::horizon::pack::Installed>,
     packs_loaded: Option<Instant>,
     pack_open: Option<String>,
     pack_filter: Option<horizon_port_pack::report::Status>,
@@ -326,6 +328,7 @@ impl Launcher {
             play_pressed: None,
             bench: perf::Bench::from_env(),
             packs: Vec::new(),
+            registry_packs: Vec::new(),
             packs_loaded: None,
             pack_open: None,
             pack_filter: None,
diff --git a/launcher/src/modpacks.rs b/launcher/src/modpacks.rs
index 909c6cfae..acd8241a5 100644
--- a/launcher/src/modpacks.rs
+++ b/launcher/src/modpacks.rs
@@ -7,6 +7,7 @@
 //! `home/`, the profile's own saves and options. Nothing is uploaded or shared: mod jars are
 //! often All Rights Reserved, so the ports stay on the player's machine.
 use crate::backend;
+use crate::browser::horizon::pack as horizon_pack;
 use horizon_port_pack::{
     fetch::{Fetched, How},
     import::Pack,
@@ -232,6 +233,9 @@ pub fn outcome(pack: &Imported) -> String {
 
 /// Removes an imported pack: its jars, ports and the profile's saves.
 pub fn remove(work: &Path) -> Result<(), String> {
+    if horizon_pack::is_pack(work) {
+        return horizon_pack::remove(work);
+    }
     if work.parent() != Some(ports_dir().as_path()) {
         return Err(format!("{} is not an imported pack", work.display()));
     }
@@ -245,7 +249,11 @@ pub fn profile_home(work: &Path) -> PathBuf {
 
 /// Turns the game's command into this pack's profile: its own home (the player's options.txt
 /// copied in the first time, so keys and video settings carry over) and its carried-over mods.
+/// A modpack from Horizon's registry (`horizon-packs/<id>/`) plays its own profile the same way.
 pub fn apply_profile(cmd: &mut Command, work: &Path) -> Result<(), String> {
+    if horizon_pack::is_pack(work) {
+        return horizon_pack::apply(cmd, work);
+    }
     // Only mods that load together: the game would refuse the later of two sharing a namespace.
     let (mods, _) = pipeline::loadable(&carried(work));
     if mods.is_empty() {
diff --git a/launcher/src/modpacks_page.rs b/launcher/src/modpacks_page.rs
index 6346f8a0b..25df3966f 100644
--- a/launcher/src/modpacks_page.rs
+++ b/launcher/src/modpacks_page.rs
@@ -1,6 +1,7 @@
 //! Imported modpacks, on the Mods page's Modpacks tab: import a pack, read its coverage report,
 //! port what this computer can and play it as its own profile (`horizon_launcher::modpacks`).
 use super::*;
+use horizon_launcher::browser::horizon::pack as horizon_pack;
 use horizon_launcher::modpacks::{self, Imported};
 use horizon_port_pack::report::Status;
 use std::path::PathBuf;
@@ -130,6 +131,7 @@ impl Launcher {
         if self.packs_loaded.is_none() {
             self.mods.report_list.reset();
             self.packs = modpacks::list();
+            self.registry_packs = horizon_pack::list();
             if self.pack_open.is_none() {
                 self.pack_open = self.packs.first().map(|p| p.slug.clone());
             }
@@ -177,6 +179,12 @@ impl Launcher {
         if let Some(e) = &self.pack_error {
             page = page.child(notice(e.clone(), &t));
         }
+        if !self.registry_packs.is_empty() {
+            page = page.child(self.registry_pack_rows(cx));
+        }
+        if self.packs.is_empty() && !self.registry_packs.is_empty() {
+            return page;
+        }
         if self.packs.is_empty() {
             return page.child(
                 text(theme::CAPTION)
@@ -216,6 +224,78 @@ impl Launcher {
         }
     }
 
+    /// The modpacks installed from Horizon's registry: each plays its own profile.
+    fn registry_pack_rows(&self, cx: &mut Context<Self>) -> Div {
+        let t = self.theme;
+        let mut list = div().flex().flex_col();
+        for (i, p) in self.registry_packs.iter().enumerate() {
+            let (play, remove) = (p.work.clone(), p.work.clone());
+            let id = p.id.clone();
+            let key = format!("horizon:{id}");
+            let confirming = self.confirm_remove.as_deref() == Some(key.as_str());
+            let right = div()
+                .flex()
+                .gap(px(8.))
+                .child(
+                    button(format!("play-pack-{id}"), "Play", Kind::Primary, &t).on_click(
+                        cx.listener(move |this, _: &ClickEvent, _, cx| {
+                            this.play_pack(play.clone());
+                            cx.notify();
+                        }),
+                    ),
+                )
+                .child(
+                    button(
+                        format!("remove-pack-{id}"),
+                        if confirming {
+                            "Remove for good"
+                        } else {
+                            "Remove"
+                        },
+                        if confirming {
+                            Kind::Secondary
+                        } else {
+                            Kind::Ghost
+                        },
+                        &t,
+                    )
+                    .when(confirming, |b| b.text_color(t.danger))
+                    .on_click(cx.listener(
+                        move |this, _: &ClickEvent, _, cx| {
+                            if this.confirm_remove.as_ref() == Some(&key) {
+                                match horizon_pack::remove(&remove) {
+                                    Ok(()) => this.packs_loaded = None,
+                                    Err(e) => this.pack_error = Some(e),
+                                }
+                                this.confirm_remove = None;
+                            } else {
+                                this.confirm_remove = Some(key.clone());
+                            }
+                            cx.notify();
+                        },
+                    )),
+                );
+            let detail = format!(
+                "{} from Horizon's registry, its own profile: {}",
+                p.version,
+                p.mods.join(", ")
+            );
+            list = list.child(index_row(
+                i + 1,
+                p.name.clone(),
+                Some(
+                    text(theme::CAPTION)
+                        .text_color(t.muted)
+                        .child(detail)
+                        .into_any_element(),
+                ),
+                Some(right.into_any_element()),
+                &t,
+            ));
+        }
+        list
+    }
+
     fn pack_log_plate(&self, t: &Theme) -> Div {
         let start = self.pack_log.len().saturating_sub(LOG_SHOWN);
         plate(t)
diff --git a/launcher/src/mods_page.rs b/launcher/src/mods_page.rs
index 5e60549a1..50434756c 100644
--- a/launcher/src/mods_page.rs
+++ b/launcher/src/mods_page.rs
@@ -468,6 +468,16 @@ impl Launcher {
                         None => source.project(&id)?,
                     };
                     modpack = p.kind == PackKind::Modpack;
+                    if modpack && p.source == SourceId::Horizon {
+                        let pack = horizon::pack::install(&p.id, &progress)?;
+                        return Ok(format!(
+                            "Installed {} {} as its own profile with {}, each checked. Play it \
+                             from the list above.",
+                            pack.name,
+                            pack.version,
+                            pack.mods.join(", ")
+                        ));
+                    }
                     if modpack {
                         let folder = modpacks::ports_dir().join("downloads");
                         let file = installed::fetch_modpack(&*source, &p, &folder, &|f| {

From 372f918e44a14f984e1359001d4285a5ed3958ef Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 01:18:53 +0200
Subject: [PATCH 009/270] Multiplayer: keep firework flight duration, boost
 gliding players

Two halves of FireworkRocketEntity on a server were missing:

- SetCreativeModeSlot encoded only damage, so a creative-picked rocket
  lost its minecraft:fireworks component (flight_duration and explosions
  gone); the wire codec also had no decoder for it or firework_explosion,
  so a stack carrying them failed to decode at all. The components now
  follow Fireworks.STREAM_CODEC/FireworkExplosion.STREAM_CODEC both ways
  (component ids 71/70).
- A remote rocket never read DATA_ATTACHED_TO_TARGET,
  DATA_ID_FIREWORKS_ITEM or DATA_SHOT_AT_ANGLE, so the server-attached
  boost rocket was an inert marker: attached_to now comes from
  EntityDataSerializers.OPTIONAL_UNSIGNED_INT (the id plus one), the item
  feeds the explosion list, and FireworkRocketEntity.tick's
  isFallFlying boost applies to the local player.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/fireworks.rs   |  9 +-
 crates/horizon-client/src/game/remote.rs      | 48 +++++++++
 .../src/game/remote_projectiles.rs            | 54 +++++++++-
 crates/horizon-protocol/src/item.rs           | 99 +++++++++++++++++++
 4 files changed, 207 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/fireworks.rs b/crates/horizon-client/src/game/fireworks.rs
index 85fccc2de..a0aa276b7 100644
--- a/crates/horizon-client/src/game/fireworks.rs
+++ b/crates/horizon-client/src/game/fireworks.rs
@@ -25,9 +25,12 @@ pub(super) struct Rocket {
     pub(super) velocity: Vec3,
     life: i32,
     lifetime: i32,
-    explosions: Vec<FireworkExplosion>,
+    pub(super) explosions: Vec<FireworkExplosion>,
     /// Boosting the player (attachedToEntity).
     pub(super) attached: bool,
+    /// `DATA_ATTACHED_TO_TARGET`: the server entity the rocket follows;
+    /// boosting happens when it is the local player.
+    pub(super) attached_to: Option<u32>,
     /// `DATA_SHOT_AT_ANGLE` (dispensers): constant velocity, exploding on
     /// the first block it hits.
     pub(super) angled: bool,
@@ -48,6 +51,7 @@ impl Rocket {
             lifetime: i32::MAX,
             explosions,
             attached: false,
+            attached_to: None,
             angled: false,
             item,
         }
@@ -63,7 +67,7 @@ impl Rocket {
         (self.position, self.velocity)
     }
 }
-fn fireworks_of(stack: &ItemStack) -> (u8, Vec<FireworkExplosion>) {
+pub(super) fn fireworks_of(stack: &ItemStack) -> (u8, Vec<FireworkExplosion>) {
     // The item's default component: flight 1, no explosions.
     stack
         .data()
@@ -89,6 +93,7 @@ impl Game<'_> {
             lifetime,
             explosions,
             attached,
+            attached_to: None,
             angled: false,
             item: stack.clone(),
         }
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 45ba4bebe..29a7ab46f 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -596,6 +596,28 @@ impl Game<'_> {
         out.tidy();
         Some(out)
     }
+    /// A wire `FireworkExplosion` as vanilla's NBT codec writes it
+    /// (`FireworkExplosion.Shape`'s BY_ID order).
+    fn fireworks_tag(e: &horizon_protocol::item::FireworkExplosion) -> Tag {
+        const SHAPES: [&str; 5] = ["small_ball", "large_ball", "star", "creeper", "burst"];
+        let ints = |c: &[i32]| Tag::List(c.iter().map(|c| Tag::Int(*c)).collect());
+        Tag::compound([
+            (
+                "shape",
+                Tag::String(
+                    SHAPES
+                        .get(e.shape.max(0) as usize)
+                        .copied()
+                        .unwrap_or("small_ball")
+                        .into(),
+                ),
+            ),
+            ("colors", ints(&e.colors)),
+            ("fade_colors", ints(&e.fade)),
+            ("has_trail", Tag::Byte(i8::from(e.trail))),
+            ("has_twinkle", Tag::Byte(i8::from(e.twinkle))),
+        ])
+    }
     /// The item's patched components as vanilla's `components` compound.
     fn protocol_components(&self, s: &Stack) -> Option<Tag> {
         use horizon_protocol::item::{Component, component};
@@ -633,6 +655,14 @@ impl Game<'_> {
                     ("pages", Tag::List(b.pages.clone())),
                     ("resolved", Tag::Byte(i8::from(b.resolved))),
                 ]),
+                Component::Fireworks { flight, explosions } => Tag::compound([
+                    ("flight_duration", Tag::Byte(*flight as i8)),
+                    (
+                        "explosions",
+                        Tag::List(explosions.iter().map(Self::fireworks_tag).collect()),
+                    ),
+                ]),
+                Component::FireworkExplosion(e) => Self::fireworks_tag(e),
                 Component::Enchantments(list) => {
                     // Enchantments are a synced (data-driven) registry: the
                     // ids index the server's RegistryData, not the builtin
@@ -719,6 +749,24 @@ impl Game<'_> {
                 horizon_protocol::item::Component::Int(s.damage as i32),
             ));
         }
+        if let Some((flight, explosions)) = s.data().and_then(|d| d.fireworks.clone()) {
+            stack.added.push((
+                horizon_protocol::item::component::FIREWORKS,
+                horizon_protocol::item::Component::Fireworks {
+                    flight: i32::from(flight),
+                    explosions: explosions
+                        .iter()
+                        .map(|e| horizon_protocol::item::FireworkExplosion {
+                            shape: e.shape as i32,
+                            colors: e.colors.iter().map(|c| *c as i32).collect(),
+                            fade: e.fade.iter().map(|c| *c as i32).collect(),
+                            trail: e.trail,
+                            twinkle: e.twinkle,
+                        })
+                        .collect(),
+                },
+            ));
+        }
         Some(stack)
     }
     /// A line in the connection's chat, with its styles, click and hover
diff --git a/crates/horizon-client/src/game/remote_projectiles.rs b/crates/horizon-client/src/game/remote_projectiles.rs
index 58f82e3a9..dbf7f3ccf 100644
--- a/crates/horizon-client/src/game/remote_projectiles.rs
+++ b/crates/horizon-client/src/game/remote_projectiles.rs
@@ -2,7 +2,7 @@
 //! end crystals on a server's client (`ClientPacketListener.handleAddEntity`
 //! and `handleSetEntityData`): the server simulates them, the client draws
 //! them where it says and interpolates their moves.
-use super::{FallingBlock, Game};
+use super::{FallingBlock, Game, fireworks::fireworks_of, view_vector};
 use horizon_client::projectiles::{Projectile, ProjectileKind};
 use horizon_core::{geometry::Vec3, position::BlockPos};
 use horizon_protocol::entity_data::Value;
@@ -117,6 +117,37 @@ impl Game<'_> {
     pub(super) fn remote_projectile_data(&mut self, id: i32, values: &[(u8, i32, Value)]) {
         let id = id as u32;
         self.remote_hook_data(id, values);
+        if self.rockets.iter().any(|r| r.id == id) {
+            for (index, _, value) in values {
+                match (index, value) {
+                    // FireworkRocketEntity.DATA_ID_FIREWORKS_ITEM: its
+                    // explosions for `createFireworks`.
+                    (8, Value::Item(stack)) => {
+                        if let Some(stack) = self.to_stack(stack)
+                            && let Some(r) = self.rockets.iter_mut().find(|r| r.id == id)
+                        {
+                            let (_, explosions) = fireworks_of(&stack);
+                            r.explosions = explosions;
+                            r.item = stack;
+                        }
+                    }
+                    // DATA_ATTACHED_TO_TARGET (OptionalInt: the id plus 1).
+                    (9, Value::Id(v)) => {
+                        let v = (*v > 0).then(|| (*v - 1) as u32);
+                        if let Some(r) = self.rockets.iter_mut().find(|r| r.id == id) {
+                            r.attached_to = v;
+                        }
+                    }
+                    // DATA_SHOT_AT_ANGLE.
+                    (10, Value::Bool(a)) => {
+                        if let Some(r) = self.rockets.iter_mut().find(|r| r.id == id) {
+                            r.angled = *a;
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
         if self.potions.has_thrown(id) {
             // ThrowableItemProjectile.DATA_ITEM_STACK: the potion it is.
             for (index, _, value) in values {
@@ -199,9 +230,30 @@ impl Game<'_> {
             let id = t.id;
             t.remote_step(|at| step(id, at));
         }
+        // FireworkRocketEntity.tick: a rocket attached to the gliding local
+        // player boosts it client-side too (attachedToEntity.isFallFlying).
+        let me = self
+            .remote
+            .as_ref()
+            .and_then(|r| u32::try_from(r.entity_id).ok());
         for r in &mut self.rockets {
             let id = r.id;
             r.remote_step(|at| step(id, at));
+            if me.is_some() && r.attached_to == me {
+                if let Some(p) = self.player.as_mut()
+                    && p.fall_flying
+                {
+                    let look = view_vector(self.yaw, self.pitch);
+                    let m = p.velocity;
+                    p.velocity = Vec3::new(
+                        m.x + look[0] * 0.1 + (look[0] * 1.5 - m.x) * 0.5,
+                        m.y + look[1] * 0.1 + (look[1] * 1.5 - m.y) * 0.5,
+                        m.z + look[2] * 0.1 + (look[2] * 1.5 - m.z) * 0.5,
+                    );
+                    r.position = p.position;
+                    r.velocity = p.velocity;
+                }
+            }
         }
         for c in &mut self.crystals {
             c.time += 1;
diff --git a/crates/horizon-protocol/src/item.rs b/crates/horizon-protocol/src/item.rs
index 650fa4baa..753fc7349 100644
--- a/crates/horizon-protocol/src/item.rs
+++ b/crates/horizon-protocol/src/item.rs
@@ -35,6 +35,8 @@ pub mod component {
     pub const CHARGED_PROJECTILES: i32 = 51;
     pub const WRITABLE_BOOK_CONTENT: i32 = 56;
     pub const WRITTEN_BOOK_CONTENT: i32 = 57;
+    pub const FIREWORK_EXPLOSION: i32 = 70;
+    pub const FIREWORKS: i32 = 71;
 }
 
 /// A written book's content (`WrittenBookContent.STREAM_CODEC`): the
@@ -78,6 +80,48 @@ pub enum Component {
     WrittenBook(WrittenBook),
     /// `ChargedProjectiles`: a loaded crossbow's ammunition, as templates.
     Stacks(Vec<Stack>),
+    /// `Fireworks`: flight duration and its explosions.
+    Fireworks {
+        flight: i32,
+        explosions: Vec<FireworkExplosion>,
+    },
+    /// `FireworkExplosion` (a firework star).
+    FireworkExplosion(FireworkExplosion),
+}
+
+/// `FireworkExplosion.STREAM_CODEC`: shape id, colors, fade colors, trail
+/// and twinkle (FireworkExplosion.Shape's BY_ID order).
+#[derive(Clone, Debug, PartialEq)]
+pub struct FireworkExplosion {
+    pub shape: i32,
+    pub colors: Vec<i32>,
+    pub fade: Vec<i32>,
+    pub trail: bool,
+    pub twinkle: bool,
+}
+impl FireworkExplosion {
+    fn read(r: &mut Reader) -> Result<Self> {
+        let ints = |r: &mut Reader| -> Result<Vec<i32>> {
+            let n = r.count(1024)?;
+            (0..n).map(|_| r.i32()).collect()
+        };
+        Ok(Self {
+            shape: r.varint()?,
+            colors: ints(r)?,
+            fade: ints(r)?,
+            trail: r.bool()?,
+            twinkle: r.bool()?,
+        })
+    }
+    fn write(&self, w: &mut Writer) {
+        w.varint(self.shape);
+        w.varint(self.colors.len() as i32);
+        self.colors.iter().for_each(|c| w.i32(*c));
+        w.varint(self.fade.len() as i32);
+        self.fade.iter().for_each(|c| w.i32(*c));
+        w.bool(self.trail);
+        w.bool(self.twinkle);
+    }
 }
 
 /// `Filterable.streamCodec`: the raw value, then an optional filtered one
@@ -224,6 +268,17 @@ impl Component {
                     hidden: (0..n).map(|_| r.varint()).collect::<Result<_>>()?,
                 }
             }
+            FIREWORKS => {
+                let flight = r.varint()?;
+                let n = r.count(256)?;
+                Self::Fireworks {
+                    flight,
+                    explosions: (0..n)
+                        .map(|_| FireworkExplosion::read(r))
+                        .collect::<Result<_>>()?,
+                }
+            }
+            FIREWORK_EXPLOSION => Self::FireworkExplosion(FireworkExplosion::read(r)?),
             other => return Err(Error::new(format!("unsupported item component {other}"))),
         })
     }
@@ -294,6 +349,12 @@ impl Component {
                 w.varint(stacks.len() as i32);
                 stacks.iter().for_each(|s| Template::write(s, w));
             }
+            Self::Fireworks { flight, explosions } => {
+                w.varint(*flight);
+                w.varint(explosions.len() as i32);
+                explosions.iter().for_each(|e| e.write(w));
+            }
+            Self::FireworkExplosion(e) => e.write(w),
             Self::WritableBook(pages) => {
                 w.varint(pages.len() as i32);
                 for page in pages {
@@ -544,6 +605,44 @@ mod tests {
         round::<Option<Hashed>, HashedSlot>(None);
     }
 
+    #[test]
+    fn fireworks_components_round_trip() {
+        let mut rocket = Stack::new(42, 1);
+        rocket.added.push((
+            component::FIREWORKS,
+            Component::Fireworks {
+                flight: 3,
+                explosions: vec![
+                    FireworkExplosion {
+                        shape: 4,
+                        colors: vec![0xff0000, 0x00ff00],
+                        fade: vec![0x0000ff],
+                        trail: true,
+                        twinkle: false,
+                    },
+                    FireworkExplosion {
+                        shape: 0,
+                        colors: vec![],
+                        fade: vec![],
+                        trail: false,
+                        twinkle: true,
+                    },
+                ],
+            },
+        ));
+        rocket.added.push((
+            component::FIREWORK_EXPLOSION,
+            Component::FireworkExplosion(FireworkExplosion {
+                shape: 2,
+                colors: vec![7],
+                fade: vec![],
+                trail: false,
+                twinkle: false,
+            }),
+        ));
+        round::<Option<Stack>, Slot>(Some(rocket));
+    }
+
     #[test]
     fn charged_projectiles_are_item_stack_templates() {
         // A crossbow (id 7) loaded with one arrow (id 9): ChargedProjectiles

From 0f9de6dbb0ce0e1aeef50e5b960a3040357a6132 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 01:39:28 +0200
Subject: [PATCH 010/270] Shader packs, clean room 14: terrain drawn by the
 pack's program

With a pack whose gbuffers_terrain (or a fallback) loads, solid and
cutout terrain is drawn by it into the pack's buffers, in place, between
prepare and deferred, and Horizon's own solid terrain draw is skipped.

- depthtex0 is now a Depth32Float attachment: the blit writes the
  world's depth there (GL window depth, GL rows), terrain tests and
  writes against it, so entities and terrain occlude each other; later
  programs sample it as before.
- The vertex glue reads Horizon's TerrainVertex on both draw paths
  (instanced, and flat with the page tables in bind group 1) and gives
  atlas coordinates, lightmap coordinates in 0-240, the vertex colour,
  mc_midTexCoord at the sprite's centre and mc_Entity = -1. Normals,
  tangents and block ids come later.
- texture/gtexture/tex sample the block atlas, lightmap the lightmap;
  atlasSize is set.
- Occlusion culling is off while a pack draws terrain (it reads the
  depth of Horizon's terrain draw), and flat draws stay on.
- Uniforms a program reads that are not provided yet are reported.
- Program building is shared by quads and terrain (build_pass, bind).
- terrain-test: Horizon's own pack for this slice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/shader_packs.rs   |   3 +-
 crates/horizon-client/src/gfx.rs              | 106 ++-
 crates/horizon-client/src/gfx/flat.rs         |   3 +-
 crates/horizon-client/src/gfx/pack_atlas.rs   |  69 +-
 crates/horizon-client/src/gfx/pack_post.rs    | 716 +++++++++++-------
 crates/horizon-client/src/gfx/pack_post.wgsl  |   7 +-
 .../horizon-client/src/gfx/pack_uniforms.rs   |   5 +
 .../tests/packs/terrain-test/README.md        |   8 +
 .../packs/terrain-test/shaders/composite.fsh  |  19 +
 .../packs/terrain-test/shaders/composite.vsh  |   8 +
 .../terrain-test/shaders/gbuffers_terrain.fsh |  22 +
 .../terrain-test/shaders/gbuffers_terrain.vsh |  16 +
 12 files changed, 702 insertions(+), 280 deletions(-)
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/README.md
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.fsh
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.vsh
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh

diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index 04af297b6..d819eddef 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -42,7 +42,8 @@ impl Game<'_> {
                         );
                     }
                     let folder = dimension_folder(&pack, dimension);
-                    let post = load_post(&pack, &folder, &properties, &macros, None);
+                    let terrain = renderer.pack_terrain_inputs();
+                    let post = load_post(&pack, &folder, &properties, &macros, terrain.as_ref());
                     if let Some((programs, notes)) = renderer.set_shader_pack(dimension, Some(post))
                     {
                         for note in notes {
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 9f05adb65..c117b190f 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -471,6 +471,8 @@ pub struct Renderer {
     pack_post: Option<(i32, Option<pack_post::PackPost>)>,
     /// The block sprites as one atlas, while a shader pack is loaded.
     pack_atlas: Option<pack_atlas::PackAtlas>,
+    /// The pack's terrain program reads flat draws' vertices (`pack_terrain_inputs`).
+    pack_terrain_flat: bool,
     pub hud: HudRenderer,
     /// Vanilla's menu background blur, made on first use.
     menu_blur: Option<crate::menu_blur::MenuBlur>,
@@ -2319,6 +2321,7 @@ impl Renderer {
             world_post,
             pack_post: None,
             pack_atlas: None,
+            pack_terrain_flat: false,
             hud,
             menu_blur: None,
             info,
@@ -2744,17 +2747,50 @@ impl Renderer {
         dimension: i32,
         pack: Option<horizon_shaders::Post>,
     ) -> Option<(Vec<String>, Vec<String>)> {
+        if pack.is_none() {
+            self.pack_atlas = None;
+        }
+        let instance = wgpu::vertex_attr_array![5=>Float32x4];
+        let vertex = wgpu::VertexBufferLayout {
+            array_stride: std::mem::size_of::<TerrainVertex>() as u64,
+            step_mode: wgpu::VertexStepMode::Vertex,
+            attributes: &TERRAIN_ATTRIBUTES,
+        };
+        let instances = wgpu::VertexBufferLayout {
+            array_stride: 16,
+            step_mode: wgpu::VertexStepMode::Instance,
+            attributes: &instance,
+        };
+        let buffers = [Some(vertex), Some(instances)];
+        let flat = self.pack_terrain_flat;
         let post = pack.map(|post| {
+            let world = pack_post::World {
+                atlas: self.pack_atlas.as_ref().map(|a| (a.view.clone(), a.size())),
+                lightmap: self.lightmap_view.clone(),
+                terrain: self.pack_atlas.as_ref().map(|_| pack_post::Geometry {
+                    buffers: if flat { &buffers[..1] } else { &buffers },
+                    table: self.flat.as_ref().filter(|_| flat).map(|f| &f.draw_layout),
+                }),
+            };
             pack_post::PackPost::new(
                 &self.device,
                 &self.queue,
                 post,
                 self.config.format.remove_srgb_suffix(),
+                world,
             )
         });
-        if post.is_none() {
-            self.pack_atlas = None;
-        } else if self.pack_atlas.is_none() {
+        let report = post.as_ref().map(|p| {
+            let programs = p.programs().into_iter().map(str::to_owned).collect();
+            (programs, p.notes.clone())
+        });
+        self.pack_post = Some((dimension, post));
+        report
+    }
+    /// What a shader pack's terrain program reads from Horizon's terrain vertices, in the
+    /// pack's block atlas (made here when missing); `None` when the atlas does not fit.
+    pub fn pack_terrain_inputs(&mut self) -> Option<horizon_shaders::GbuffersInputs> {
+        if self.pack_atlas.is_none() {
             let mut encoder = self.device.create_command_encoder(&Default::default());
             let layers = self
                 .sprite_textures
@@ -2771,12 +2807,13 @@ impl Renderer {
             );
             self.queue.submit([encoder.finish()]);
         }
-        let report = post.as_ref().map(|p| {
-            let programs = p.programs().into_iter().map(str::to_owned).collect();
-            (programs, p.notes.clone())
-        });
-        self.pack_post = Some((dimension, post));
-        report
+        // Flat draws whenever the device has them (`render` keeps them on with a pack).
+        self.pack_terrain_flat = self.flat.is_some() && self.flat_on;
+        Some(
+            self.pack_atlas
+                .as_ref()?
+                .terrain_inputs(self.pack_terrain_flat),
+        )
     }
     /// The dimension the shader pack was last set for.
     pub fn shader_pack_dimension(&self) -> Option<i32> {
@@ -3184,11 +3221,23 @@ impl Renderer {
         // Occlusion culling leaves the sections its last result did not see
         // to phase 2, after the others, with instance counts of 0. Whether
         // the frame has draws enough goes by the last one's.
+        // A shader pack drawing terrain draws all of it: occlusion culling reads the depth of
+        // Horizon's own terrain draw.
+        let pack_terrain = !frame.title
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_terrain());
         let mut cull = self
             .cull
             .as_mut()
             .filter(|c| {
-                self.cull_on && !frame.title && self.multi_draw && self.section_draws >= c.min_draws
+                self.cull_on
+                    && !frame.title
+                    && !pack_terrain
+                    && self.multi_draw
+                    && self.section_draws >= c.min_draws
             })
             .and_then(|cull| cull.begin(&self.device).then_some(cull));
         self.phase2_draws.clear();
@@ -3591,7 +3640,9 @@ impl Renderer {
         }
         let flat_frame = match &mut self.flat {
             Some(flat)
-                if self.flat_on && !self.draws.is_empty() && self.draws.len() >= flat.min_draws =>
+                if self.flat_on
+                    && !self.draws.is_empty()
+                    && (self.draws.len() >= flat.min_draws || pack_terrain) =>
             {
                 let sections = &self.sections;
                 let lods = &self.lods;
@@ -3651,6 +3702,8 @@ impl Renderer {
         }
         // The world's targets: the screen, or the scaled target of `post`.
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
+        // The pack's program reads the vertices this frame's draws bind.
+        let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
         let scaled = self.world_post.prepare(
             &self.device,
             [self.config.width, self.config.height],
@@ -3739,7 +3792,14 @@ impl Renderer {
                     pass.draw(0..3, 0..1);
                 }
             }
-            match self.flat.as_ref().filter(|_| flat_frame) {
+            match self
+                .flat
+                .as_ref()
+                .filter(|_| flat_frame && !pack_draws_terrain)
+            {
+                _ if pack_draws_terrain => {
+                    pass.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
+                }
                 Some(flat) => {
                     pass.set_pipeline(&flat.solid);
                     let vertices = |p| self.arena.buffer(p);
@@ -3947,9 +4007,27 @@ impl Renderer {
         }
         if let Some((color, depth)) = &scaled
             && pack_post
-            && let Some((_, Some(post))) = &mut self.pack_post
+            && let Some((dimension, Some(mut post))) = self.pack_post.take()
         {
             let size = self.world_post.size().unwrap_or([1, 1]);
+            let flat = self.flat.as_ref().filter(|_| flat_frame);
+            let mut terrain = |rp: &mut wgpu::RenderPass<'_>| {
+                if !pack_draws_terrain {
+                    return;
+                }
+                match flat {
+                    Some(flat) => {
+                        flat.draw(rp, &flat.calls[..flat.solid_calls], |p| {
+                            self.arena.buffer(p)
+                        });
+                    }
+                    None => {
+                        rp.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
+                        rp.set_vertex_buffer(1, self.instances.slice(..));
+                        self.draw_sections(rp, &self.indirect, 0, 0, solid_draws);
+                    }
+                }
+            };
             post.run(
                 &self.device,
                 &self.queue,
@@ -3961,7 +4039,9 @@ impl Renderer {
                 &frame.pack,
                 size,
                 [self.config.width, self.config.height],
+                &mut terrain,
             );
+            self.pack_post = Some((dimension, Some(post)));
         } else if scaled.is_some() {
             self.world_post.finish(&mut encoder, &view_target);
         }
diff --git a/crates/horizon-client/src/gfx/flat.rs b/crates/horizon-client/src/gfx/flat.rs
index f6823c5d8..4c337025a 100644
--- a/crates/horizon-client/src/gfx/flat.rs
+++ b/crates/horizon-client/src/gfx/flat.rs
@@ -73,7 +73,8 @@ pub struct Flat {
     phase2_call_data: Vec<[u32; 5]>,
     /// The copy of phase 2's draws, and its ranges.
     phase2_group: Option<(wgpu::BindGroup, u32)>,
-    draw_layout: wgpu::BindGroupLayout,
+    /// The layout of a page's bind group 1 (shader packs' terrain pipelines share it).
+    pub(super) draw_layout: wgpu::BindGroupLayout,
     blocks_per_page: u64,
     pages: Vec<Option<PageTable>>,
     free_ids: Vec<u32>,
diff --git a/crates/horizon-client/src/gfx/pack_atlas.rs b/crates/horizon-client/src/gfx/pack_atlas.rs
index c90fa6ac1..011dff379 100644
--- a/crates/horizon-client/src/gfx/pack_atlas.rs
+++ b/crates/horizon-client/src/gfx/pack_atlas.rs
@@ -3,7 +3,6 @@
 //! layer is copied into a grid, row by row from the top left, and an animated layer again
 //! whenever its frame changes.
 
-#[expect(dead_code, reason = "the gbuffers pass binds it (next slice)")]
 pub(super) struct PackAtlas {
     texture: wgpu::Texture,
     pub view: wgpu::TextureView,
@@ -64,10 +63,6 @@ impl PackAtlas {
     }
 
     /// The atlas's size in pixels (`atlasSize`).
-    #[cfg_attr(
-        not(test),
-        expect(dead_code, reason = "the gbuffers pass reads it (next slice)")
-    )]
     pub fn size(&self) -> [u32; 2] {
         [self.texture.width(), self.texture.height()]
     }
@@ -118,6 +113,70 @@ impl PackAtlas {
     }
 }
 
+impl PackAtlas {
+    /// The vertex inputs of a gbuffers program drawing terrain (`TerrainVertex`, terrain.wgsl's
+    /// `vs_terrain` or, for `flat` draws, `vs_terrain_flat`), in atlas coordinates.
+    pub fn terrain_inputs(&self, flat: bool) -> horizon_shaders::GbuffersInputs {
+        let mut declarations = String::from(
+            "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in uvec2 hz_v_uv;\n\
+             layout(location = 2) in uint hz_v_layer;\nlayout(location = 3) in vec4 hz_v_color;\n\
+             layout(location = 4) in uvec2 hz_v_light;\n",
+        );
+        let origin = if flat {
+            declarations.push_str(
+                "layout(set = 1, binding = 0) readonly buffer HzBlockSlots { uint hz_block_slots[]; };\n\
+                 layout(set = 1, binding = 1) readonly buffer HzSlotOrigins { vec4 hz_slot_origins[]; };\n",
+            );
+            "hz_slot_origins[hz_block_slots[uint(gl_VertexIndex) >> 8u]]"
+        } else {
+            declarations.push_str("layout(location = 5) in vec4 hz_v_origin;\n");
+            "hz_v_origin"
+        };
+        let [width, height] = self.size();
+        let scale = [
+            self.sprite as f32 / width as f32,
+            self.sprite as f32 / height as f32,
+        ];
+        let columns = self.columns;
+        // UVs past a sprite (models up to 2, distant tiles) cannot repeat in an atlas: clamped.
+        let body = format!(
+            "    vec4 hz_origin = {origin};\n    \
+             uint hz_layer = hz_v_layer & 32767u;\n    \
+             hz_cell = vec2(float(hz_layer % {columns}u), float(hz_layer / {columns}u));\n    \
+             hz_scale = vec2({:?}, {:?});\n    \
+             hz_Vertex = vec4(hz_v_pos + hz_origin.xyz, 1.0);\n    \
+             hz_MultiTexCoord0 = vec4((hz_cell + clamp(vec2(hz_v_uv) * hz_origin.w, 0.0, 1.0)) * hz_scale, 0.0, 1.0);\n    \
+             hz_MultiTexCoord1 = vec4(float(hz_v_light.y), float(hz_v_light.x), 0.0, 1.0);\n    \
+             hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+             hz_Color = hz_v_color;\n    \
+             hz_Normal = vec3(0.0, 1.0, 0.0);\n",
+            scale[0], scale[1],
+        );
+        declarations.push_str("vec2 hz_cell; vec2 hz_scale;\n");
+        let attributes = [
+            ("mc_Entity", "vec4(-1.0, -1.0, 0.0, 0.0)"),
+            (
+                "mc_midTexCoord",
+                "vec4((hz_cell + 0.5) * hz_scale, 0.0, 1.0)",
+            ),
+            ("at_tangent", "vec4(1.0, 0.0, 0.0, 1.0)"),
+            ("vaPosition", "hz_Vertex.xyz"),
+            ("vaUV0", "hz_MultiTexCoord0.xy"),
+            ("vaUV2", "hz_MultiTexCoord1.xy"),
+            ("vaColor", "hz_Color"),
+            ("vaNormal", "hz_Normal"),
+        ];
+        horizon_shaders::GbuffersInputs {
+            declarations,
+            body,
+            attributes: attributes
+                .iter()
+                .map(|&(n, v)| (n.to_owned(), v.to_owned()))
+                .collect(),
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index d5aa9fb7c..81a517dba 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -29,6 +29,9 @@ enum Source {
     Dummy,
     /// A 1×1 depth of 1.0 behind a comparison sampler, until shadow maps exist: no shadow.
     Shadow,
+    /// The block atlas (pack_atlas.rs), in gbuffers programs.
+    Atlas,
+    Lightmap,
 }
 
 struct Binding {
@@ -66,9 +69,22 @@ struct Targets {
     depth: wgpu::TextureView,
 }
 
+/// What a pack's gbuffers programs read and draw from the game's world.
+pub(super) struct World<'a> {
+    /// The block atlas and its size.
+    pub atlas: Option<(wgpu::TextureView, [u32; 2])>,
+    pub lightmap: wgpu::TextureView,
+    /// Terrain's geometry, when the pack draws it.
+    pub terrain: Option<Geometry<'a>>,
+}
+
 pub struct PackPost {
     pub notes: Vec<String>,
     passes: Vec<Pass>,
+    /// What draws terrain (`gbuffers_terrain` or its fallback), between `prepare` and `deferred`.
+    terrain: Option<Pass>,
+    atlas: Option<wgpu::TextureView>,
+    lightmap: wgpu::TextureView,
     deferred_pre: u16,
     composite_pre: u16,
     formats: [wgpu::TextureFormat; BUFFERS],
@@ -85,6 +101,7 @@ pub struct PackPost {
     linear: wgpu::Sampler,
     nearest: wgpu::Sampler,
     repeat: wgpu::Sampler,
+    nearest_repeat: wgpu::Sampler,
     blit: (wgpu::RenderPipeline, wgpu::BindGroupLayout),
     /// The blit also writes depthtex0 (some program reads it) and clears these buffers.
     blit_depth: bool,
@@ -133,6 +150,8 @@ fn source(name: &str) -> Source {
     match name {
         "depthtex0" | "gdepthtex" | "depthtex1" | "depthtex2" => Source::Depth,
         "noisetex" => Source::Noise,
+        "texture" | "gtexture" | "tex" => Source::Atlas,
+        "lightmap" => Source::Lightmap,
         n => horizon_shaders::buffer_index(n).map_or(Source::Dummy, Source::Color),
     }
 }
@@ -228,6 +247,7 @@ fn helper(
     entry: &str,
     entries: &[wgpu::BindGroupLayoutEntry],
     targets: &[Option<wgpu::ColorTargetState>],
+    depth: Option<wgpu::DepthStencilState>,
 ) -> (wgpu::RenderPipeline, wgpu::BindGroupLayout) {
     let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
         label: Some("Shader pack helpers"),
@@ -252,7 +272,7 @@ fn helper(
             buffers: &[],
         },
         primitive: Default::default(),
-        depth_stencil: None,
+        depth_stencil: depth,
         multisample: Default::default(),
         fragment: Some(wgpu::FragmentState {
             module: &module,
@@ -306,6 +326,211 @@ fn attach(
     })
 }
 
+/// The game's geometry a gbuffers program draws: its vertex buffers and, for flat draws
+/// (flat.rs), the layout of their bind group 1.
+pub(super) struct Geometry<'a> {
+    pub buffers: &'a [Option<wgpu::VertexBufferLayout<'a>>],
+    pub table: Option<&'a wgpu::BindGroupLayout>,
+}
+
+/// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
+/// wgpu refuses it or it writes nothing.
+fn build_pass(
+    device: &wgpu::Device,
+    p: horizon_shaders::PostProgram,
+    formats: &[wgpu::TextureFormat; BUFFERS],
+    screen: wgpu::TextureFormat,
+    notes: &mut Vec<String>,
+    geometry: Option<&Geometry<'_>>,
+) -> Option<Pass> {
+    let features = device.features();
+    let mask = |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
+    let interface = &p.program.interface;
+    let mut entries = vec![entry(
+        0,
+        wgpu::BindingType::Buffer {
+            ty: wgpu::BufferBindingType::Uniform,
+            has_dynamic_offset: false,
+            min_binding_size: None,
+        },
+    )];
+    let mut samplers = Vec::new();
+    let mut reads = 0u16;
+    for s in &interface.samplers {
+        let mut src = source(&s.name);
+        if src == Source::Atlas && geometry.is_none() {
+            src = Source::Dummy;
+        }
+        let float = wgpu::TextureSampleType::Float { filterable: true };
+        let mut sample_type = match src {
+            Source::Color(n) => formats[n]
+                .sample_type(None, Some(features))
+                .unwrap_or(float),
+            Source::Depth => wgpu::TextureSampleType::Float { filterable: false },
+            // Unfilterable on WebGPU-level devices; the lightmap is sampled at texel centres.
+            Source::Lightmap => float,
+            _ => float,
+        };
+        let int = !matches!(sample_type, wgpu::TextureSampleType::Float { .. });
+        if s.ty == "sampler2DShadow" {
+            (src, sample_type) = (Source::Shadow, wgpu::TextureSampleType::Depth);
+        }
+        let wanted = match s.ty.as_str() {
+            "sampler2DShadow" => true,
+            "sampler2D" => !int,
+            "isampler2D" => sample_type == wgpu::TextureSampleType::Sint,
+            "usampler2D" => sample_type == wgpu::TextureSampleType::Uint,
+            _ => false,
+        };
+        if !wanted {
+            notes.push(format!(
+                "{}: `{} {}` is not provided yet",
+                p.name, s.ty, s.name
+            ));
+            (src, sample_type) = (Source::Dummy, float);
+        }
+        let filtering = sample_type == float;
+        if let Source::Color(n) = src {
+            reads |= 1 << n;
+        }
+        entries.push(texture_entry(s.binding, sample_type));
+        entries.push(entry(
+            s.binding + 1,
+            wgpu::BindingType::Sampler(if src == Source::Shadow {
+                wgpu::SamplerBindingType::Comparison
+            } else if filtering {
+                wgpu::SamplerBindingType::Filtering
+            } else {
+                wgpu::SamplerBindingType::NonFiltering
+            }),
+        ));
+        samplers.push(Binding {
+            source: src,
+            binding: s.binding,
+            filtering,
+        });
+    }
+    let final_pass = p.group == Group::Final;
+    let mut targets = Vec::new();
+    let mut writes = Vec::new();
+    for &location in &interface.outputs {
+        let l = location as usize;
+        if targets.len() <= l {
+            targets.resize(l + 1, None);
+        }
+        if final_pass {
+            if location == 0 {
+                targets[0] = target(screen);
+            }
+        } else if let Some(&buffer) = p.buffers.get(l) {
+            targets[l] = target(formats[buffer as usize]);
+            writes.push((location, buffer as usize));
+        }
+    }
+    if !final_pass && writes.is_empty() {
+        notes.push(format!("{}: writes no buffer; skipped", p.name));
+        return None;
+    }
+    let written = writes.iter().fold(0u16, |m, w| m | 1 << w.1);
+    let kept = p
+        .flips
+        .iter()
+        .filter(|f| !f.1)
+        .fold(0u16, |m, f| m | 1 << f.0);
+    // Gbuffers programs write in place (6.1.6).
+    let flip = if final_pass || geometry.is_some() {
+        0
+    } else {
+        (written & !kept) | mask(&p.flips)
+    };
+    let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some(&p.name),
+        entries: &entries,
+    });
+    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+        label: Some(&p.name),
+        bind_group_layouts: &[Some(&layout), geometry.and_then(|g| g.table)],
+        ..Default::default()
+    });
+    let created = checked(device, || {
+        let module = |m: naga::Module| {
+            device.create_shader_module(wgpu::ShaderModuleDescriptor {
+                label: Some(&p.name),
+                source: wgpu::ShaderSource::Naga(std::borrow::Cow::Owned(m)),
+            })
+        };
+        let (vs, fs) = (module(p.program.vertex), module(p.program.fragment));
+        device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
+            label: Some(&p.name),
+            layout: Some(&pipeline_layout),
+            vertex: wgpu::VertexState {
+                module: &vs,
+                entry_point: Some("main"),
+                compilation_options: Default::default(),
+                buffers: geometry.map_or(&[], |g| g.buffers),
+            },
+            primitive: Default::default(),
+            depth_stencil: geometry.map(|_| wgpu::DepthStencilState {
+                format: wgpu::TextureFormat::Depth32Float,
+                depth_write_enabled: Some(true),
+                depth_compare: Some(wgpu::CompareFunction::LessEqual),
+                stencil: Default::default(),
+                bias: Default::default(),
+            }),
+            multisample: Default::default(),
+            fragment: Some(wgpu::FragmentState {
+                module: &fs,
+                entry_point: Some("main"),
+                compilation_options: Default::default(),
+                targets: &targets,
+            }),
+            multiview_mask: None,
+            cache: None,
+        })
+    });
+    let pipeline = match created {
+        Ok(p) => p,
+        Err(e) => {
+            notes.push(format!("{}: skipped: {e}", p.name));
+            return None;
+        }
+    };
+    let interface = &p.program.interface;
+    let missing: Vec<&str> = interface
+        .uniforms
+        .iter()
+        .filter(|u| !u.name.starts_with("hz_") && pack_uniforms::index(&u.name).is_none())
+        .map(|u| u.name.as_str())
+        .collect();
+    if !missing.is_empty() {
+        notes.push(format!("{}: zero for now: {}", p.name, missing.join(" ")));
+    }
+    Some(Pass {
+        ubo: device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some(&p.name),
+            size: u64::from(interface.uniform_size.max(16)),
+            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        }),
+        block: vec![0; interface.uniform_size as usize],
+        uniforms: interface
+            .uniforms
+            .iter()
+            .map(|u| (pack_uniforms::index(&u.name), u.ty.clone(), u.offset))
+            .collect(),
+        name: p.name,
+        group: p.group,
+        pipeline,
+        layout,
+        samplers,
+        writes,
+        flip,
+        reads,
+        written,
+        groups: HashMap::new(),
+    })
+}
+
 impl PackPost {
     /// Builds the pipelines of `post` for a screen of `screen` format.
     pub fn new(
@@ -313,6 +538,7 @@ impl PackPost {
         queue: &wgpu::Queue,
         post: Post,
         screen: wgpu::TextureFormat,
+        world: World<'_>,
     ) -> Self {
         let features = device.features();
         let formats: [wgpu::TextureFormat; BUFFERS] =
@@ -329,205 +555,56 @@ impl PackPost {
         let mask =
             |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
         let mut used = 1u16;
-        let mut passes = Vec::new();
-        for p in post.programs {
-            let interface = &p.program.interface;
-            let mut entries = vec![entry(
-                0,
-                wgpu::BindingType::Buffer {
-                    ty: wgpu::BufferBindingType::Uniform,
-                    has_dynamic_offset: false,
-                    min_binding_size: None,
-                },
-            )];
-            let mut samplers = Vec::new();
-            let mut reads = 0u16;
-            for s in &interface.samplers {
-                let mut src = source(&s.name);
-                let float = wgpu::TextureSampleType::Float { filterable: true };
-                let mut sample_type = match src {
-                    Source::Color(n) => formats[n]
-                        .sample_type(None, Some(features))
-                        .unwrap_or(float),
-                    Source::Depth => wgpu::TextureSampleType::Float { filterable: false },
-                    _ => float,
-                };
-                let int = !matches!(sample_type, wgpu::TextureSampleType::Float { .. });
-                if s.ty == "sampler2DShadow" {
-                    (src, sample_type) = (Source::Shadow, wgpu::TextureSampleType::Depth);
-                }
-                let wanted = match s.ty.as_str() {
-                    "sampler2DShadow" => true,
-                    "sampler2D" => !int,
-                    "isampler2D" => sample_type == wgpu::TextureSampleType::Sint,
-                    "usampler2D" => sample_type == wgpu::TextureSampleType::Uint,
-                    _ => false,
-                };
-                if !wanted {
-                    notes.push(format!(
-                        "{}: `{} {}` is not provided yet",
-                        p.name, s.ty, s.name
-                    ));
-                    (src, sample_type) = (Source::Dummy, float);
-                }
-                let filtering = sample_type == float;
-                if let Source::Color(n) = src {
-                    reads |= 1 << n;
-                }
-                entries.push(texture_entry(s.binding, sample_type));
-                entries.push(entry(
-                    s.binding + 1,
-                    wgpu::BindingType::Sampler(if src == Source::Shadow {
-                        wgpu::SamplerBindingType::Comparison
-                    } else if filtering {
-                        wgpu::SamplerBindingType::Filtering
-                    } else {
-                        wgpu::SamplerBindingType::NonFiltering
-                    }),
-                ));
-                samplers.push(Binding {
-                    source: src,
-                    binding: s.binding,
-                    filtering,
-                });
-            }
-            let final_pass = p.group == Group::Final;
-            let mut targets = Vec::new();
-            let mut writes = Vec::new();
-            for &location in &interface.outputs {
-                let l = location as usize;
-                if targets.len() <= l {
-                    targets.resize(l + 1, None);
-                }
-                if final_pass {
-                    if location == 0 {
-                        targets[0] = target(screen);
-                    }
-                } else if let Some(&buffer) = p.buffers.get(l) {
-                    targets[l] = target(formats[buffer as usize]);
-                    writes.push((location, buffer as usize));
-                }
-            }
-            if !final_pass && writes.is_empty() {
-                notes.push(format!("{}: writes no buffer; skipped", p.name));
-                continue;
-            }
-            let written = writes.iter().fold(0u16, |m, w| m | 1 << w.1);
-            let kept = p
-                .flips
-                .iter()
-                .filter(|f| !f.1)
-                .fold(0u16, |m, f| m | 1 << f.0);
-            let flip = if final_pass {
-                0
-            } else {
-                (written & !kept) | mask(&p.flips)
-            };
-            used |= reads | written | flip;
-            let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
-                label: Some(&p.name),
-                entries: &entries,
-            });
-            let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
-                label: Some(&p.name),
-                bind_group_layouts: &[Some(&layout)],
-                ..Default::default()
-            });
-            let created = checked(device, || {
-                let module = |m: naga::Module| {
-                    device.create_shader_module(wgpu::ShaderModuleDescriptor {
-                        label: Some(&p.name),
-                        source: wgpu::ShaderSource::Naga(std::borrow::Cow::Owned(m)),
-                    })
-                };
-                let (vs, fs) = (module(p.program.vertex), module(p.program.fragment));
-                device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
-                    label: Some(&p.name),
-                    layout: Some(&pipeline_layout),
-                    vertex: wgpu::VertexState {
-                        module: &vs,
-                        entry_point: Some("main"),
-                        compilation_options: Default::default(),
-                        buffers: &[],
-                    },
-                    primitive: Default::default(),
-                    depth_stencil: None,
-                    multisample: Default::default(),
-                    fragment: Some(wgpu::FragmentState {
-                        module: &fs,
-                        entry_point: Some("main"),
-                        compilation_options: Default::default(),
-                        targets: &targets,
-                    }),
-                    multiview_mask: None,
-                    cache: None,
-                })
-            });
-            let pipeline = match created {
-                Ok(p) => p,
-                Err(e) => {
-                    notes.push(format!("{}: skipped: {e}", p.name));
-                    continue;
-                }
-            };
-            let interface = &p.program.interface;
-            passes.push(Pass {
-                ubo: device.create_buffer(&wgpu::BufferDescriptor {
-                    label: Some(&p.name),
-                    size: u64::from(interface.uniform_size.max(16)),
-                    usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
-                    mapped_at_creation: false,
-                }),
-                block: vec![0; interface.uniform_size as usize],
-                uniforms: interface
-                    .uniforms
-                    .iter()
-                    .map(|u| (pack_uniforms::index(&u.name), u.ty.clone(), u.offset))
-                    .collect(),
-                name: p.name,
-                group: p.group,
-                pipeline,
-                layout,
-                samplers,
-                writes,
-                flip,
-                reads,
-                written,
-                groups: HashMap::new(),
-            });
+        let mut build = |p: horizon_shaders::PostProgram, geometry: Option<&Geometry<'_>>| {
+            let pass = build_pass(device, p, &formats, screen, &mut notes, geometry)?;
+            used |= pass.reads | pass.written | pass.flip;
+            Some(pass)
+        };
+        let terrain = post
+            .terrain
+            .zip(world.terrain.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)));
+        let passes: Vec<Pass> = post
+            .programs
+            .into_iter()
+            .filter_map(|p| build(p, None))
+            .collect();
+        if let Some(t) = &terrain {
+            notes.push(format!("terrain draws with {}", t.name));
         }
         // A clear only matters when a program reads the buffer before one writes all of it
-        // (composite passes cover their whole target); the others are skipped.
+        // (composite passes cover their whole target, terrain does not); the others are skipped.
         let mut cleared = Vec::new();
         for b in 1..BUFFERS {
             let bit = 1u16 << b;
-            let first = passes
-                .iter()
-                .find(|p| (p.reads | p.flip | p.written) & bit != 0);
-            if clears[b].is_some()
-                && first.is_some_and(|p| p.reads & bit != 0 || p.written & bit == 0)
-            {
+            let touched = |p: &&Pass| (p.reads | p.flip | p.written) & bit != 0;
+            let first = terrain.iter().find(touched).map(|_| true).or_else(|| {
+                let p = passes.iter().find(touched)?;
+                Some(p.reads & bit != 0 || p.written & bit == 0)
+            });
+            if clears[b].is_some() && first == Some(true) {
                 cleared.push(b);
             }
         }
-        let blit_depth = passes
-            .iter()
-            .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth));
-        let room = 8 - 1 - usize::from(blit_depth);
+        // Terrain tests against the world's depth (entities...), so the blit copies it then.
+        let blit_depth = terrain.is_some()
+            || passes
+                .iter()
+                .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth));
+        let room = 8 - 1;
         let other_clears = cleared.split_off(room.min(cleared.len()));
         let float = wgpu::TextureSampleType::Float { filterable: true };
-        let mut blit_targets = vec![target(formats[0])];
-        if blit_depth {
-            blit_targets.push(target(wgpu::TextureFormat::R32Float));
-        }
+        let blit_targets = std::iter::once(target(formats[0]));
         // Cleared by the pass's load operation; the shader writes nothing there.
-        blit_targets.extend(cleared.iter().map(|&b| {
-            Some(wgpu::ColorTargetState {
-                format: formats[b],
-                blend: None,
-                write_mask: wgpu::ColorWrites::empty(),
-            })
-        }));
+        let blit_targets: Vec<_> = blit_targets
+            .chain(cleared.iter().map(|&b| {
+                Some(wgpu::ColorTargetState {
+                    format: formats[b],
+                    blend: None,
+                    write_mask: wgpu::ColorWrites::empty(),
+                })
+            }))
+            .collect();
         let blit = helper(
             device,
             "vs_full",
@@ -541,6 +618,14 @@ impl PackPost {
                 texture_entry(1, wgpu::TextureSampleType::Depth),
             ],
             &blit_targets,
+            // GL's window depth, written for depthtex0 and the terrain's depth test.
+            blit_depth.then_some(wgpu::DepthStencilState {
+                format: wgpu::TextureFormat::Depth32Float,
+                depth_write_enabled: Some(true),
+                depth_compare: Some(wgpu::CompareFunction::Always),
+                stencil: Default::default(),
+                bias: Default::default(),
+            }),
         );
         let copy = helper(
             device,
@@ -554,11 +639,15 @@ impl PackPost {
                 ),
             ],
             &[target(screen)],
+            None,
         );
         let white = [255u8; 4];
         Self {
             notes,
             passes,
+            terrain,
+            atlas: world.atlas.as_ref().map(|a| a.0.clone()),
+            lightmap: world.lightmap,
             deferred_pre: mask(&post.deferred_pre),
             composite_pre: mask(&post.composite_pre),
             formats,
@@ -608,12 +697,153 @@ impl PackPost {
                 wgpu::AddressMode::ClampToEdge,
             ),
             repeat: sampler(device, wgpu::FilterMode::Linear, wgpu::AddressMode::Repeat),
+            nearest_repeat: sampler(device, wgpu::FilterMode::Nearest, wgpu::AddressMode::Repeat),
             blit,
             copy,
-            uniforms: FrameUniforms::default(),
+            uniforms: {
+                let mut u = FrameUniforms::default();
+                u.atlas = world.atlas.map_or([0; 2], |a| a.1);
+                u
+            },
         }
     }
 
+    /// Writes `pass`'s uniforms for a target of `out` pixels; its bind group for the buffers'
+    /// current mapping.
+    fn bind(
+        &self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        pass: &mut Pass,
+        out: [u32; 2],
+    ) -> wgpu::BindGroup {
+        let fog = self.uniforms.fog();
+        // Our block members first (`hz_target`, `hz_fog_color`, `hz_fog`), then the pack's.
+        let ours = [
+            [
+                out[0] as f32,
+                out[1] as f32,
+                1.0 / out[0] as f32,
+                1.0 / out[1] as f32,
+            ],
+            fog[0].to_array(),
+            fog[1].to_array(),
+        ];
+        let head: &[u8] = bytemuck::cast_slice(&ours);
+        let n = head.len().min(pass.block.len());
+        pass.block[..n].copy_from_slice(&head[..n]);
+        for (index, ty, offset) in &pass.uniforms {
+            if let Some(v) = index.and_then(|i| self.uniforms.values.get(i)) {
+                v.write(ty, &mut pass.block, *offset as usize);
+            }
+        }
+        if !pass.block.is_empty() {
+            queue.write_buffer(&pass.ubo, 0, &pass.block);
+        }
+        let targets = self.targets.as_ref().expect("resized");
+        let key = self.main & pass.reads;
+        let group = pass.groups.entry(key).or_insert_with(|| {
+            let mut entries = vec![wgpu::BindGroupEntry {
+                binding: 0,
+                resource: pass.ubo.as_entire_binding(),
+            }];
+            for s in &pass.samplers {
+                let filter = if s.filtering {
+                    &self.linear
+                } else {
+                    &self.nearest
+                };
+                let (texture, sampler) = match s.source {
+                    Source::Color(i) => (
+                        targets.color[i]
+                            .as_ref()
+                            .map_or(&self.dummy, |t| &t[usize::from(key & 1 << i != 0)]),
+                        filter,
+                    ),
+                    Source::Depth => (&targets.depth, &self.nearest),
+                    Source::Noise => (&self.noise, &self.repeat),
+                    Source::Dummy => (&self.dummy, &self.linear),
+                    Source::Shadow => (&self.shadow.0, &self.shadow.1),
+                    // Blocks look as the game draws them: nearest texels.
+                    Source::Atlas => (
+                        self.atlas.as_ref().unwrap_or(&self.dummy),
+                        &self.nearest_repeat,
+                    ),
+                    Source::Lightmap => (&self.lightmap, &self.linear),
+                };
+                entries.push(wgpu::BindGroupEntry {
+                    binding: s.binding,
+                    resource: wgpu::BindingResource::TextureView(texture),
+                });
+                entries.push(wgpu::BindGroupEntry {
+                    binding: s.binding + 1,
+                    resource: wgpu::BindingResource::Sampler(sampler),
+                });
+            }
+            device.create_bind_group(&wgpu::BindGroupDescriptor {
+                label: Some(&pass.name),
+                layout: &pass.layout,
+                entries: &entries,
+            })
+        });
+        group.clone()
+    }
+
+    /// Terrain with the pack's program into the buffers it writes, in place, tested against
+    /// the world's depth; `draw` issues the game's draws.
+    fn draw_terrain(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>),
+    ) {
+        let Some(mut pass) = self.terrain.take() else {
+            return;
+        };
+        let group = self.bind(device, queue, &mut pass, size);
+        let targets = self.targets.as_ref().expect("resized");
+        let load = wgpu::Operations {
+            load: wgpu::LoadOp::Load,
+            store: wgpu::StoreOp::Store,
+        };
+        let mut attachments: Vec<Option<wgpu::RenderPassColorAttachment>> = Vec::new();
+        for &(location, buffer) in &pass.writes {
+            let l = location as usize;
+            if attachments.len() <= l {
+                attachments.resize(l + 1, None);
+            }
+            attachments[l] = targets.color[buffer]
+                .as_ref()
+                .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load));
+        }
+        {
+            let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: Some(&pass.name),
+                color_attachments: &attachments,
+                depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
+                    view: &targets.depth,
+                    depth_ops: Some(wgpu::Operations {
+                        load: wgpu::LoadOp::Load,
+                        store: wgpu::StoreOp::Store,
+                    }),
+                    stencil_ops: None,
+                }),
+                ..Default::default()
+            });
+            rp.set_pipeline(&pass.pipeline);
+            rp.set_bind_group(0, &group, &[]);
+            draw(&mut rp);
+        }
+        self.terrain = Some(pass);
+    }
+
+    /// Whether the pack draws terrain itself.
+    pub fn has_terrain(&self) -> bool {
+        self.terrain.is_some()
+    }
+
     /// The names of the programs that run, in order.
     pub fn programs(&self) -> Vec<&str> {
         self.passes.iter().map(|p| p.name.as_str()).collect()
@@ -651,9 +881,9 @@ impl PackPost {
         self.targets = Some(Targets {
             size,
             color,
-            depth: make("depthtex0", wgpu::TextureFormat::R32Float),
+            depth: make("depthtex0", wgpu::TextureFormat::Depth32Float),
         });
-        for pass in &mut self.passes {
+        for pass in self.passes.iter_mut().chain(&mut self.terrain) {
             pass.groups.clear();
         }
     }
@@ -673,6 +903,7 @@ impl PackPost {
         inputs: &PackInputs,
         size: [u32; 2],
         window: [u32; 2],
+        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>),
     ) {
         self.resize(device, size);
         self.uniforms.update(frame, inputs, size);
@@ -751,9 +982,6 @@ impl PackPost {
                 view(self.main, 0, false).expect("colortex0"),
                 overwrite,
             )];
-            if self.blit_depth {
-                attachments.push(attach(&targets.depth, overwrite));
-            }
             for &b in &self.blit_clears {
                 attachments.push(attach(
                     view(self.main, b, false).expect("used buffer"),
@@ -763,6 +991,16 @@ impl PackPost {
             let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some("Shader pack world"),
                 color_attachments: &attachments,
+                depth_stencil_attachment: self.blit_depth.then_some(
+                    wgpu::RenderPassDepthStencilAttachment {
+                        view: &targets.depth,
+                        depth_ops: Some(wgpu::Operations {
+                            load: wgpu::LoadOp::Clear(1.0),
+                            store: wgpu::StoreOp::Store,
+                        }),
+                        stencil_ops: None,
+                    },
+                ),
                 ..Default::default()
             });
             pass.set_pipeline(&self.blit.0);
@@ -770,10 +1008,15 @@ impl PackPost {
             pass.draw(0..3, 0..1);
         }
 
-        let fog = self.uniforms.fog();
+        let mut passes = std::mem::take(&mut self.passes);
         let mut seen = (false, false);
         let mut shown = false;
-        for pass in &mut self.passes {
+        let mut terrain_drawn = self.terrain.is_none();
+        for pass in &mut passes {
+            if !terrain_drawn && pass.group != Group::Prepare {
+                terrain_drawn = true;
+                self.draw_terrain(device, queue, encoder, size, terrain);
+            }
             if pass.group == Group::Deferred && !seen.0 {
                 seen.0 = true;
                 self.main ^= self.deferred_pre;
@@ -783,63 +1026,13 @@ impl PackPost {
                 self.main ^= self.composite_pre;
             }
             let final_pass = pass.group == Group::Final;
-            let out = if final_pass { window } else { size };
-            // Our block members first (`hz_target`, `hz_fog_color`, `hz_fog`), then the pack's.
-            let ours = [
-                [
-                    out[0] as f32,
-                    out[1] as f32,
-                    1.0 / out[0] as f32,
-                    1.0 / out[1] as f32,
-                ],
-                fog[0].to_array(),
-                fog[1].to_array(),
-            ];
-            let head: &[u8] = bytemuck::cast_slice(&ours);
-            let n = head.len().min(pass.block.len());
-            pass.block[..n].copy_from_slice(&head[..n]);
-            for (index, ty, offset) in &pass.uniforms {
-                if let Some(v) = index.and_then(|i| self.uniforms.values.get(i)) {
-                    v.write(ty, &mut pass.block, *offset as usize);
-                }
-            }
-            if !pass.block.is_empty() {
-                queue.write_buffer(&pass.ubo, 0, &pass.block);
-            }
-            let key = self.main & pass.reads;
-            let group = pass.groups.entry(key).or_insert_with(|| {
-                let mut entries = vec![wgpu::BindGroupEntry {
-                    binding: 0,
-                    resource: pass.ubo.as_entire_binding(),
-                }];
-                for s in &pass.samplers {
-                    let filter = if s.filtering {
-                        &self.linear
-                    } else {
-                        &self.nearest
-                    };
-                    let (texture, sampler) = match s.source {
-                        Source::Color(i) => (view(key, i, false).unwrap_or(&self.dummy), filter),
-                        Source::Depth => (&targets.depth, &self.nearest),
-                        Source::Noise => (&self.noise, &self.repeat),
-                        Source::Dummy => (&self.dummy, &self.linear),
-                        Source::Shadow => (&self.shadow.0, &self.shadow.1),
-                    };
-                    entries.push(wgpu::BindGroupEntry {
-                        binding: s.binding,
-                        resource: wgpu::BindingResource::TextureView(texture),
-                    });
-                    entries.push(wgpu::BindGroupEntry {
-                        binding: s.binding + 1,
-                        resource: wgpu::BindingResource::Sampler(sampler),
-                    });
-                }
-                device.create_bind_group(&wgpu::BindGroupDescriptor {
-                    label: Some(&pass.name),
-                    layout: &pass.layout,
-                    entries: &entries,
-                })
-            });
+            let group = self.bind(device, queue, pass, if final_pass { window } else { size });
+            let targets = self.targets.as_ref().expect("resized");
+            let view = |i: usize| {
+                targets.color[i]
+                    .as_ref()
+                    .map(|t| &t[usize::from(self.main & 1 << i == 0)])
+            };
             let mut attachments: Vec<Option<wgpu::RenderPassColorAttachment>> = Vec::new();
             if final_pass {
                 attachments.push(attach(screen, overwrite));
@@ -850,8 +1043,7 @@ impl PackPost {
                     if attachments.len() <= l {
                         attachments.resize(l + 1, None);
                     }
-                    attachments[l] =
-                        view(self.main, buffer, true).and_then(|v| attach(v, overwrite));
+                    attachments[l] = view(buffer).and_then(|v| attach(v, overwrite));
                 }
             }
             {
@@ -861,11 +1053,21 @@ impl PackPost {
                     ..Default::default()
                 });
                 rp.set_pipeline(&pass.pipeline);
-                rp.set_bind_group(0, &*group, &[]);
+                rp.set_bind_group(0, &group, &[]);
                 rp.draw(0..6, 0..1);
             }
             self.main ^= pass.flip;
         }
+        self.passes = passes;
+        if !terrain_drawn {
+            self.draw_terrain(device, queue, encoder, size, terrain);
+        }
+        let targets = self.targets.as_ref().expect("resized");
+        let view = |m: u16, i: usize, alt: bool| {
+            targets.color[i]
+                .as_ref()
+                .map(|t| &t[main(m, i) ^ usize::from(alt)])
+        };
         if !shown {
             let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
                 label: Some("Shader pack colortex0"),
diff --git a/crates/horizon-client/src/gfx/pack_post.wgsl b/crates/horizon-client/src/gfx/pack_post.wgsl
index 30345b00f..75877dddc 100644
--- a/crates/horizon-client/src/gfx/pack_post.wgsl
+++ b/crates/horizon-client/src/gfx/pack_post.wgsl
@@ -1,5 +1,6 @@
 // Helpers of a shader pack's post-processing (pack_post.rs): the world into colortex0 and
-// depthtex0, and colortex0 onto the screen for packs without `final`.
+// depthtex0 (a depth attachment, for terrain's depth test), and colortex0 onto the screen for
+// packs without `final`.
 
 @vertex
 fn vs_full(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
@@ -12,7 +13,7 @@ fn vs_full(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
 
 struct World {
     @location(0) color: vec4<f32>,
-    @location(1) depth: vec4<f32>,
+    @builtin(frag_depth) depth: f32,
 }
 
 // Pack buffers keep GL's rows (row 0 at the bottom), and GL's window depth: Horizon's
@@ -23,7 +24,7 @@ fn fs_blit(@builtin(position) p: vec4<f32>) -> World {
     let at = vec2<i32>(i32(p.x), size.y - 1 - i32(p.y));
     var out: World;
     out.color = textureLoad(source, at, 0);
-    out.depth = vec4<f32>(1.0 - textureLoad(world_depth, at, 0), 0.0, 0.0, 1.0);
+    out.depth = 1.0 - textureLoad(world_depth, at, 0);
     return out;
 }
 
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index 7d2a73a6a..92eac4a75 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -140,11 +140,14 @@ pub const NAMES: &[&str] = &[
     "gbufferProjectionInverse",
     "gbufferPreviousModelView",
     "gbufferPreviousProjection",
+    "atlasSize",
 ];
 
 /// Values carried from frame to frame.
 pub struct FrameUniforms {
     pub values: Vec<Value>,
+    /// The block atlas's size (`atlasSize`), 0 without one.
+    pub atlas: [u32; 2],
     start: std::time::Instant,
     last: Option<std::time::Instant>,
     frame: u32,
@@ -157,6 +160,7 @@ impl Default for FrameUniforms {
     fn default() -> Self {
         Self {
             values: Vec::new(),
+            atlas: [0; 2],
             start: std::time::Instant::now(),
             last: None,
             frame: 0,
@@ -243,6 +247,7 @@ impl FrameUniforms {
                 "worldDay" => Value::i(&[world_day as i32]),
                 "moonPhase" => Value::i(&[world_day.rem_euclid(8) as i32]),
                 "frameCounter" => Value::i(&[self.frame as i32]),
+                "atlasSize" => Value::i(&[self.atlas[0] as i32, self.atlas[1] as i32]),
                 "frameTime" => Value::f(&[dt]),
                 "frameTimeCounter" => Value::f(&[seconds]),
                 "viewWidth" => Value::f(&[size[0] as f32]),
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/README.md b/crates/horizon-shaders/tests/packs/terrain-test/README.md
new file mode 100644
index 000000000..bb8ddd060
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/README.md
@@ -0,0 +1,8 @@
+# terrain-test
+
+Horizon's own shader pack for testing gbuffers terrain (written for Horizon, no other pack's code).
+`gbuffers_terrain` draws blocks from the atlas with their vertex colour and lightmap, tinted by
+the lightmap coordinate's sky light (cooler where the sky is hidden); `mc_midTexCoord` marks each
+face's centre with a dot. `composite` puts the depth buffer's view-space distance into the blue
+channel of the far half. Copy the folder into `shaderpacks/` and run the game with
+`HORIZON_SHADER_PACK=terrain-test`.
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.fsh
new file mode 100644
index 000000000..d473ef240
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.fsh
@@ -0,0 +1,19 @@
+#version 120
+
+uniform sampler2D colortex0;
+uniform sampler2D depthtex0;
+uniform mat4 gbufferProjectionInverse;
+uniform float far;
+
+varying vec2 texcoord;
+
+void main() {
+    vec3 color = texture2D(colortex0, texcoord).rgb;
+    if (texcoord.x > 0.5) {
+        float depth = texture2D(depthtex0, texcoord).r;
+        vec4 view = gbufferProjectionInverse * vec4(vec3(texcoord, depth) * 2.0 - 1.0, 1.0);
+        color.b = clamp(length(view.xyz / view.w) / far, 0.0, 1.0);
+    }
+    /* DRAWBUFFERS:0 */
+    gl_FragData[0] = vec4(color, 1.0);
+}
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.vsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.vsh
new file mode 100644
index 000000000..38e4e455c
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/composite.vsh
@@ -0,0 +1,8 @@
+#version 120
+
+varying vec2 texcoord;
+
+void main() {
+    gl_Position = ftransform();
+    texcoord = gl_MultiTexCoord0.xy;
+}
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
new file mode 100644
index 000000000..902cf3525
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
@@ -0,0 +1,22 @@
+#version 120
+
+uniform sampler2D texture;
+uniform sampler2D lightmap;
+uniform ivec2 atlasSize;
+
+varying vec2 texcoord;
+varying vec2 lmcoord;
+varying vec2 mid;
+varying vec4 glcolor;
+
+void main() {
+    vec4 color = texture2D(texture, texcoord) * glcolor;
+    if (color.a < 0.1) discard;
+    color.rgb *= texture2D(lightmap, lmcoord).rgb;
+    // Less sky light: bluer.
+    color.rgb = mix(color.rgb * vec3(0.6, 0.7, 1.2), color.rgb, lmcoord.y);
+    // A dot at the face's centre, one texel wide.
+    if (length((texcoord - mid) * vec2(atlasSize)) < 1.0) color.rgb = vec3(1.0, 0.0, 1.0);
+    /* DRAWBUFFERS:0 */
+    gl_FragData[0] = color;
+}
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh
new file mode 100644
index 000000000..bc16f4aad
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh
@@ -0,0 +1,16 @@
+#version 120
+
+attribute vec4 mc_midTexCoord;
+
+varying vec2 texcoord;
+varying vec2 lmcoord;
+varying vec2 mid;
+varying vec4 glcolor;
+
+void main() {
+    gl_Position = ftransform();
+    texcoord = (gl_TextureMatrix[0] * gl_MultiTexCoord0).xy;
+    lmcoord = (gl_TextureMatrix[1] * gl_MultiTexCoord1).xy;
+    mid = mc_midTexCoord.xy;
+    glcolor = gl_Color;
+}

From 348675c5387a11a8992a99428b7609bd78047c58 Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:52:19 +0200
Subject: [PATCH 011/270] Packs: open streamed archives the way Java's ZipFile
 does

A resource pack written while it streams (Nexo's server behind
resourcepack.gommehd.io, gommehd.net's required pack) leaves every local
header a stub, every uncompressed size at 0xFFFFFFFF and the END record's
entry counts and disk number at 0 and 0xFFFF. Java tolerates all three;
the zip crate's ZipArchive refuses the END record as multi-disk and empty,
so a required server pack failed its reload and the join never got through
(each retry also rebuilt the renderer, once a second).

Count the real central-directory entries and normalize the END record's
disk and count fields when they disagree with it, and bound the inflate
output when an entry's size is the 0xFFFFFFFF sentinel.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/zip.rs | 108 ++++++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/zip.rs b/crates/horizon-client/src/zip.rs
index 22cab132d..17442858e 100644
--- a/crates/horizon-client/src/zip.rs
+++ b/crates/horizon-client/src/zip.rs
@@ -23,7 +23,8 @@ impl Zip {
     pub fn open(path: &Path) -> io::Result<Self> {
         Self::from_bytes(fs::read(path)?)
     }
-    pub fn from_bytes(data: Vec<u8>) -> io::Result<Self> {
+    pub fn from_bytes(mut data: Vec<u8>) -> io::Result<Self> {
+        normalize_end(&mut data);
         let archive = ZipArchive::new(Cursor::new(Arc::from(data))).map_err(invalid)?;
         let entries = (0..archive.len())
             .filter_map(|i| Some((archive.name_for_index(i)?.replace('\\', "/"), i)))
@@ -51,7 +52,14 @@ impl Zip {
         match method {
             CompressionMethod::Stored => Ok(raw),
             CompressionMethod::Deflated => {
-                miniz_oxide::inflate::decompress_to_vec_with_limit(&raw, size.max(1) * 2 + 1024)
+                // Streamed archives write 0xFFFFFFFF for the uncompressed
+                // size; bound the output instead of trusting it.
+                let limit = if size == u32::MAX as usize {
+                    1 << 30
+                } else {
+                    size.max(1) * 2 + 1024
+                };
+                miniz_oxide::inflate::decompress_to_vec_with_limit(&raw, limit)
                     .map_err(|_| invalid("corrupt deflate stream"))
             }
             _ => Err(invalid("unsupported zip compression")),
@@ -59,6 +67,59 @@ impl Zip {
     }
 }
 
+/// The 22 fixed bytes of the end-of-central-directory record.
+const END_HEADER: usize = 22;
+
+/// Java's `ZipFile` ignores the END record's disk numbers and file counts,
+/// reading the central directory from `cenpos` to `cenpos + cenlen` whatever
+/// they say; the `zip` crate insists the record agrees with the directory.
+/// Packs written while streaming (Nexo serves them for gommehd.net, for one)
+/// leave every file's local header a stub, the uncompressed sizes at
+/// 0xFFFFFFFF and the END counts and disk number at 0 and 0xFFFF — archives
+/// Java opens but the crate refuses. Count the real directory entries and
+/// normalize the record so it does not look multi-disk or empty.
+fn normalize_end(data: &mut [u8]) {
+    if data.len() < END_HEADER {
+        return;
+    }
+    let u16_at = |data: &[u8], at: usize| u16::from_le_bytes(data[at..at + 2].try_into().unwrap());
+    let u32_at = |data: &[u8], at: usize| u32::from_le_bytes(data[at..at + 4].try_into().unwrap());
+    // The END record's comment can hide the signature: scan back through the
+    // last 64 KiB, like every zip reader.
+    let start = data.len().saturating_sub(END_HEADER + u16::MAX as usize);
+    let mut end = None;
+    for pos in (start..=data.len().saturating_sub(END_HEADER)).rev() {
+        if data[pos..pos + 4] == [0x50, 0x4b, 0x05, 0x06]
+            && pos + END_HEADER + u16_at(data, pos + 20) as usize <= data.len()
+        {
+            end = Some(pos);
+            break;
+        }
+    }
+    let Some(end) = end else { return };
+    // The directory's real position and length, as Java derives them; the
+    // recorded offset is relative to the archive's start.
+    let cenlen = u32_at(data, end + 12) as usize;
+    let cenpos = end.saturating_sub(cenlen);
+    let mut count = 0u16;
+    let mut p = cenpos;
+    while p + 46 <= end && data[p..p + 4] == [0x50, 0x4b, 0x01, 0x02] {
+        count = count.saturating_add(1);
+        p += 46
+            + u16_at(data, p + 28) as usize
+            + u16_at(data, p + 30) as usize
+            + u16_at(data, p + 32) as usize;
+    }
+    let disk = u16_at(data, end + 4);
+    let with_directory = u16_at(data, end + 6);
+    if disk == with_directory && u16_at(data, end + 8) == count && u16_at(data, end + 10) == count {
+        return;
+    }
+    data[end + 4..end + 10].fill(0);
+    data[end + 8..end + 10].copy_from_slice(&count.to_le_bytes());
+    data[end + 10..end + 12].copy_from_slice(&count.to_le_bytes());
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -207,4 +268,47 @@ mod tests {
         cut.truncate(cut.len() / 2);
         assert!(Zip::from_bytes(cut).is_err());
     }
+
+    /// A pack as a streaming writer serves it (Nexo/gommehd.net): every
+    /// local header is a stub, the uncompressed sizes are 0xFFFFFFFF and the
+    /// END record's counts and disk numbers are wrong. Java's ZipFile opens
+    /// it anyway; so do we.
+    #[test]
+    fn reads_a_streamed_archive() {
+        let files: [(&str, &[u8], bool); 2] = [
+            ("pack.mcmeta", b"{\"pack\":{}}", true),
+            ("a/b.txt", b"streamed entry", true),
+        ];
+        let mut out = Vec::new();
+        let mut central = Vec::new();
+        for (name, body, _) in files {
+            let data = miniz_oxide::deflate::compress_to_vec(body, 6);
+            let offset = out.len() as u32;
+            out.extend(0x0403_4b50u32.to_le_bytes());
+            out.extend([0; 26]);
+            out.extend(&data);
+            central.extend(0x0201_4b50u32.to_le_bytes());
+            central.extend([20, 0, 20, 0, 0, 0]);
+            central.extend(8u16.to_le_bytes());
+            central.extend([0; 8]);
+            central.extend((data.len() as u32).to_le_bytes());
+            central.extend(u32::MAX.to_le_bytes());
+            central.extend((name.len() as u16).to_le_bytes());
+            central.extend([0; 12]);
+            central.extend(offset.to_le_bytes());
+            central.extend(name.as_bytes());
+        }
+        let start = out.len() as u32;
+        out.extend(&central);
+        out.extend(0x0605_4b50u32.to_le_bytes());
+        out.extend(u16::MAX.to_le_bytes());
+        out.extend([0; 6]);
+        out.extend((central.len() as u32).to_le_bytes());
+        out.extend(start.to_le_bytes());
+        out.extend([0; 2]);
+        let zip = Zip::from_bytes(out).unwrap();
+        assert_eq!(zip.names().collect::<Vec<_>>(), ["a/b.txt", "pack.mcmeta"]);
+        assert_eq!(zip.read("pack.mcmeta").unwrap(), b"{\"pack\":{}}");
+        assert_eq!(zip.read("a/b.txt").unwrap(), b"streamed entry");
+    }
 }

From 1fa46979c84c216f3e5c0d10d0704160db705f12 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:57:26 +0200
Subject: [PATCH 012/270] Server clients: primed TNT falls and burns its fuse
 by itself between updates

PrimedTnt keeps Entity's NO_OP InterpolationHandler and ticks on a client
too: a position packet puts it there at once, its own tick moves it on
(gravity, collisions, bounces, drag) and burns the fuse down, and a client
discards it when the fuse runs out. Horizon interpolated it towards each
update instead, so it trailed about two ticks behind the server.

lan_e2e's falling check now drops primed TNT too and checks that the
guest has it exactly where its fall from rest puts it for the fuse the
server sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/remote.rs      | 19 +++++---
 .../src/game/remote_projectiles.rs            | 19 ++++++--
 crates/horizon-client/src/game/tnt.rs         |  2 +-
 tools/lan_e2e.py                              | 44 +++++++++++++++----
 4 files changed, 64 insertions(+), 20 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 1c7e30abb..4a563f01c 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1465,10 +1465,10 @@ impl Game<'_> {
             if let Some(p) = r.pending_items.get_mut(&id) {
                 p.0 = position;
             }
-            // ItemEntity and FallingBlockEntity keep Entity's NO_OP
-            // InterpolationHandler: moveOrInterpolateTo puts them there at
-            // once, and their own tick moves them on between the server's
-            // updates (`tick_remote_entities`).
+            // ItemEntity, FallingBlockEntity and PrimedTnt keep Entity's
+            // NO_OP InterpolationHandler: moveOrInterpolateTo puts them there
+            // at once, and their own tick moves them on between the server's
+            // updates (`tick_remote_entities`, `tick_remote_projectiles`).
             let at = Vec3::new(position[0], position[1], position[2]);
             if let Some(d) = self.dropped.iter_mut().find(|d| d.id == id as u32) {
                 d.position = at;
@@ -1479,6 +1479,11 @@ impl Game<'_> {
                 f.position = at;
                 return;
             }
+            if let Some(t) = self.tnts.iter_mut().find(|t| t.id == id as u32) {
+                t.position = at;
+                t.on_ground = on_ground;
+                return;
+            }
             // AbstractInterpolationHandler.interpolateTo: without a rotation,
             // the one it was heading for.
             let rotation = rotation.or_else(|| r.lerps.get(&id).and_then(|l| l.rotation));
@@ -2974,14 +2979,16 @@ impl Game<'_> {
         });
     }
     /// `Entity.lerpMotion` (and `recreateFromPacket`'s motion) for the
-    /// entities whose own tick moves them on a client: dropped items and
-    /// falling blocks.
+    /// entities whose own tick moves them on a client: dropped items, falling
+    /// blocks and primed TNT.
     fn remote_motion(&mut self, id: i32, velocity: [f64; 3]) {
         let v = Vec3::new(velocity[0], velocity[1], velocity[2]);
         if let Some(d) = self.dropped.iter_mut().find(|d| d.id == id as u32) {
             d.velocity = v;
         } else if let Some(f) = self.falling.iter_mut().find(|f| f.id == id as u32) {
             f.velocity = v;
+        } else if let Some(t) = self.tnts.iter_mut().find(|t| t.id == id as u32) {
+            t.velocity = v;
         } else if let Some(p) = self
             .remote
             .as_mut()
diff --git a/crates/horizon-client/src/game/remote_projectiles.rs b/crates/horizon-client/src/game/remote_projectiles.rs
index 33c69728b..5098e79da 100644
--- a/crates/horizon-client/src/game/remote_projectiles.rs
+++ b/crates/horizon-client/src/game/remote_projectiles.rs
@@ -181,10 +181,21 @@ impl Game<'_> {
 
     /// One tick of interpolation, as `tick_remote_objects`.
     pub(super) fn tick_remote_projectiles(&mut self, mut step: impl FnMut(u32, Vec3) -> Vec3) {
-        for t in &mut self.tnts {
-            t.previous = t.position;
-            t.position = step(t.id, t.position);
-        }
+        // PrimedTnt.tick runs on a client too: it falls, bounces and burns its
+        // fuse down (the swell and flash follow it) between the server's
+        // updates (every 10 ticks), and a client discards it when the fuse
+        // runs out; only the server explodes it.
+        let (world, collision, assets, facts) = (
+            &self.world,
+            self.collision,
+            &self.pack.assets,
+            self.res.facts(),
+        );
+        self.tnts.retain_mut(|t| {
+            // A fluid lookup that fails leaves it where its move put it.
+            let _ = t.tick(world, collision, assets, facts);
+            t.fuse > 0
+        });
         // FallingBlockEntity.tick runs on a client too: the block falls by
         // itself between the server's updates (every 20 ticks), then waits
         // where it lands for the server to place it and remove it.
diff --git a/crates/horizon-client/src/game/tnt.rs b/crates/horizon-client/src/game/tnt.rs
index fddc02125..6bd2ae956 100644
--- a/crates/horizon-client/src/game/tnt.rs
+++ b/crates/horizon-client/src/game/tnt.rs
@@ -33,7 +33,7 @@ impl PrimedTnt {
             ),
         )
     }
-    fn tick(
+    pub(super) fn tick(
         &mut self,
         world: &horizon_client::world::World,
         collision: &horizon_world::block_collision::BlockCollisionRegistry<'_>,
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index a0fe0e181..fad55dfe8 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -228,9 +228,10 @@ address. The script then checks, from both sides, what a guest's game used to ge
 - villagers: the guest sees each villager's and zombie villager's type, profession and level as the
              host has them, and an unemployed villager that takes a composter becomes a farmer on
              the guest too (the guest used to draw every villager as an unemployed plains one).
-- falling:   an item and a falling block the host summons high up fall smoothly on the guest, a
-             little further every tick between the server's updates (every 20 ticks), as their own
-             client tick moves them (they used to hang, then jump down once a second, #1568).
+- falling:   an item, a falling block and primed TNT the host summons high up fall smoothly on the
+             guest, a little further every tick between the server's updates (every 20 ticks, 10 for
+             TNT), as their own client tick moves them (they used to hang, then jump down once a
+             second, #1568), and the TNT's fuse burns down on the guest too.
 
 Each check is reported on its own (a failing one doesn't stop the others) and the screenshots of
 both sides go to --out (host-*.png, guest-*.png).
@@ -5500,10 +5501,11 @@ CHECK_FNS.update(villagers=check_villagers)
 
 
 def check_falling(host, guest, out):
-    """ItemEntity and FallingBlockEntity tick on a client too (gravity, collisions, drag), and their
-    position packets snap them (Entity's NO_OP InterpolationHandler). The server sends an item's
-    and a falling block's position every 20 ticks, so between two updates the guest's own tick is
-    what moves them: sampled every 2 ticks over the first 16, both are lower nearly every time."""
+    """ItemEntity, FallingBlockEntity and PrimedTnt tick on a client too (gravity, collisions, drag),
+    and their position packets snap them (Entity's NO_OP InterpolationHandler). The server sends an
+    item's and a falling block's position every 20 ticks and TNT's every 10, so between two updates
+    the guest's own tick is what moves them: sampled every 2 ticks over the first 16, all three are
+    lower nearly every time. The TNT's fuse (sent once, at spawn) counts down on the guest too."""
     x, y, z = (int(v // 1) for v in pos_of(guest))
     top = y + 30
     tag = 'falling_e2e'
@@ -5512,7 +5514,10 @@ def check_falling(host, guest, out):
                             f'{{Tags:["{tag}"],Item:{{id:"minecraft:diamond",count:1}},PickupDelay:32767}}')
     host('command', command=f'summon minecraft:falling_block {x + 2.5} {top} {z - 0.5} '
                             f'{{Tags:["{tag}"],BlockState:{{Name:"minecraft:sand"}},DropItem:0b}}')
-    heights = {'item': [], 'falling block': []}
+    # Horizon's selectors don't see primed TNT yet: its fuse ends it in the air, 19 blocks down.
+    host('command', command=f'summon minecraft:tnt {x + 4.5} {top} {z + 0.5} {{fuse:34s}}')
+    heights = {'item': [], 'falling block': [], 'primed tnt': []}
+    fuses = []
     try:
         for _ in range(8):
             items = [e['pos'][1] for e in guest.raw('entities', 48, 'minecraft:item')['entities']
@@ -5520,8 +5525,12 @@ def check_falling(host, guest, out):
             blocks = [o['position'][1] for o in guest('status')['projectiles']
                       if o.get('kind') == 'minecraft:falling_block'
                       and abs(o['position'][0] - x - 2.5) < 0.5 and abs(o['position'][2] - z + 0.5) < 0.5]
+            tnts = [o for o in guest('status')['projectiles'] if o.get('kind') == 'minecraft:tnt'
+                    and abs(o['position'][0] - x - 4.5) < 0.5 and abs(o['position'][2] - z - 0.5) < 0.5]
             heights['item'].append(items[0] if items else None)
             heights['falling block'].append(blocks[0] if blocks else None)
+            heights['primed tnt'].append(tnts[0]['position'][1] if tnts else None)
+            fuses.append(tnts[0]['fuse'] if tnts else None)
             guest.wait(2)
         guest.shot(out, 'falling')
     finally:
@@ -5533,7 +5542,24 @@ def check_falling(host, guest, out):
         drops = sum(b < a for a, b in zip(seen, seen[1:]))
         # A tick or two can pass between two samples with no move; never most of them.
         assert drops >= len(seen) - 2, f'the {name} fell in {drops} of {len(seen) - 1} samples: {heights}'
-    return heights
+    # The server sends the TNT's fuse with each move, so each sample says how many ticks it has
+    # fallen from rest: snapped to the server's place and ticking on, the guest has it exactly
+    # there (it used to trail two ticks behind, interpolating towards each update).
+    fell = [(h, 34 - f) for h, f in zip(heights['primed tnt'], fuses) if f is not None]
+    assert fell and fell[-1][1] > fell[0][1], f'the TNT\'s fuse on the guest: {fuses}'
+    off = max(abs(h - tnt_fall(top, n)) for h, n in fell)
+    assert off < 0.01, f'the guest\'s TNT is {off:.3f} off its fall (height, ticks): {fell}'
+    return {**heights, 'fuse': fuses}
+
+
+def tnt_fall(top, ticks):
+    """PrimedTnt.tick in open air from rest: its height after `ticks` ticks."""
+    y, v = top, 0.0
+    for _ in range(ticks):
+        v -= 0.04
+        y += v
+        v *= 0.98
+    return y
 
 
 CHECKS += ['falling']

From 6c8880fbd887a69af1f12acc5f2f9c3b64cbec85 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:00:40 +0100
Subject: [PATCH 013/270] Shader packs, clean room 15: globals initialized at
 run time, switch options

naga keeps only constant initializers of globals, so every initialized global that is not
`const` (and every conditional one) gets its value from a function of ours that main calls
first, one per declarator, converting as GLSL's initialization does (`vec2 v = atlasSize`).
`vec3 a = x, b = y;` no longer loses `b`.

Program-enable expressions (3.3) now see the pack's switch options that are on by default
(8.1): `#define NAME` with nothing after it, tested with `#ifdef`/`#ifndef` anywhere in the
pack (OQ-13 working answer). BSL's `deferred` (ambient occlusion) and its TAA ran with options
off before.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1, sections 3.3, 8.1;
no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-shaders/src/lib.rs            |   2 +
 crates/horizon-shaders/src/options.rs        |  80 +++++++++++++
 crates/horizon-shaders/src/pack.rs           |  33 ++++++
 crates/horizon-shaders/src/post.rs           |  23 +++-
 crates/horizon-shaders/src/translate/mod.rs  |  15 +++
 crates/horizon-shaders/src/translate/scan.rs | 116 +++++++++++++++----
 6 files changed, 245 insertions(+), 24 deletions(-)
 create mode 100644 crates/horizon-shaders/src/options.rs

diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index e31eaec6f..d29a0a632 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -17,6 +17,7 @@ mod config;
 mod discover;
 mod lang;
 mod macros;
+mod options;
 mod pack;
 mod post;
 mod preprocess;
@@ -28,6 +29,7 @@ pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffe
 pub use discover::{Found, discover};
 pub use lang::Lang;
 pub use macros::{MC_VERSION, Macros, RENDER_STAGES};
+pub use options::switches_on;
 pub use pack::{Pack, PackError};
 pub use post::{Group, Post, PostProgram, dimension_folder, load_post};
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
diff --git a/crates/horizon-shaders/src/options.rs b/crates/horizon-shaders/src/options.rs
new file mode 100644
index 000000000..687fd40e0
--- /dev/null
+++ b/crates/horizon-shaders/src/options.rs
@@ -0,0 +1,80 @@
+//! Switch options (spec 8.1), as far as program-enable expressions (3.3) need them: which are on
+//! by default. A switch is `#define NAME` (on) or `//#define NAME` (off) with nothing after the
+//! name but a comment, in any stage or included file of the pack. Packs keep their options in
+//! included `.glsl` files and test them elsewhere (OQ-13), so the test the spec asks for
+//! (`#ifdef NAME` / `#ifndef NAME`) may be in any file of the pack.
+
+use std::collections::BTreeSet;
+
+use crate::Pack;
+
+const SOURCES: [&str; 8] = ["vsh", "fsh", "gsh", "csh", "tcs", "tes", "glsl", "inc"];
+
+/// The switch options that are on by default.
+pub fn switches_on(pack: &Pack) -> BTreeSet<String> {
+    let (mut on, mut off, mut tested) = (BTreeSet::new(), BTreeSet::new(), BTreeSet::new());
+    for path in pack.all_files() {
+        let ext = path.rsplit_once('.').map_or("", |(_, e)| e);
+        if !SOURCES.contains(&ext) {
+            continue;
+        }
+        let Some(text) = pack.read_text(&path) else {
+            continue;
+        };
+        for line in text.lines() {
+            let line = line.trim();
+            let (commented, rest) = match line.strip_prefix("//") {
+                Some(rest) => (true, rest.trim_start()),
+                None => (false, line),
+            };
+            let Some((directive, rest)) = rest
+                .strip_prefix('#')
+                .map(str::trim_start)
+                .and_then(|r| r.split_once(|c: char| c.is_whitespace()))
+            else {
+                continue;
+            };
+            let mut words = rest.split_whitespace();
+            let Some(name) = words.next() else { continue };
+            match directive {
+                "ifdef" | "ifndef" if !commented => _ = tested.insert(name.to_owned()),
+                "define" if words.next().is_none_or(|w| w.starts_with("//")) => {
+                    let set = if commented { &mut off } else { &mut on };
+                    set.insert(name.to_owned());
+                }
+                _ => {}
+            }
+        }
+    }
+    // Defined both ways is ambiguous (8.1): it keeps its default only where it is on everywhere.
+    on.retain(|name| tested.contains(name) && !off.contains(name));
+    on
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::pack::tests::zip;
+
+    #[test]
+    fn switches_need_a_test_and_no_value() {
+        let pack = Pack::from_zip_bytes(
+            "P.zip",
+            zip(&[
+                (
+                    "shaders/lib/settings.glsl",
+                    "  #define AO // ambient occlusion\n//#define BLOOM\n#define LEVEL 2 //[1 2]\n\
+                     #define SPLIT\n#define UNTESTED\n",
+                ),
+                (
+                    "shaders/world0/deferred.fsh",
+                    "#ifdef AO\n#endif\n#ifndef BLOOM\n#endif\n#ifdef SPLIT\n#endif\n#ifdef LEVEL\n#endif\n",
+                ),
+                ("shaders/world-1/deferred.fsh", "//#define SPLIT\n"),
+                ("shaders/shaders.properties", "#define NOT_SOURCE\n#ifdef NOT_SOURCE\n"),
+            ]),
+        )
+        .unwrap();
+        assert_eq!(switches_on(&pack), BTreeSet::from(["AO".to_owned()]));
+    }
+}
diff --git a/crates/horizon-shaders/src/pack.rs b/crates/horizon-shaders/src/pack.rs
index ae2230618..77aeded35 100644
--- a/crates/horizon-shaders/src/pack.rs
+++ b/crates/horizon-shaders/src/pack.rs
@@ -167,6 +167,39 @@ impl Pack {
         names.sort();
         names
     }
+
+    /// Every file of the pack, by its path inside `shaders`, sorted.
+    pub fn all_files(&self) -> Vec<String> {
+        let mut names = match &self.files {
+            Files::Folder(root) => {
+                let mut names = Vec::new();
+                let mut dirs = vec![String::new()];
+                while let Some(dir) = dirs.pop() {
+                    for e in fs::read_dir(root.join(&dir))
+                        .into_iter()
+                        .flatten()
+                        .flatten()
+                    {
+                        let name = e.file_name().to_string_lossy().into_owned();
+                        let path = if dir.is_empty() {
+                            name
+                        } else {
+                            format!("{dir}/{name}")
+                        };
+                        match e.file_type() {
+                            Ok(t) if t.is_dir() => dirs.push(path),
+                            Ok(t) if t.is_file() => names.push(path),
+                            _ => {}
+                        }
+                    }
+                }
+                names
+            }
+            Files::Zip { entries, .. } => entries.keys().cloned().collect(),
+        };
+        names.sort();
+        names
+    }
 }
 
 /// `a/./b/../c` → `a/c`; `None` for a path that climbs out of `shaders`.
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index cdf7fae80..c96730f0a 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -10,6 +10,8 @@
 //! - A program that fails to translate is reported and treated as missing (2.5).
 //! - Terrain draws with the first program of its fallback chain that loads (2.3).
 
+use std::collections::BTreeSet;
+
 use crate::config::{self, Config};
 use crate::{GbuffersInputs, Macros, Pack, Preprocessed, Program, Properties, Target};
 use crate::{eval_condition, preprocess, translate_composite, translate_gbuffers};
@@ -99,6 +101,7 @@ pub fn load_post(
         folder,
         properties,
         macros,
+        switches: crate::switches_on(pack),
         post: &mut post,
     };
     for (group, base) in GROUPS {
@@ -135,6 +138,7 @@ struct Loader<'a> {
     folder: &'a str,
     properties: &'a Properties,
     macros: &'a Macros,
+    switches: BTreeSet<String>,
     post: &'a mut Post,
 }
 
@@ -156,7 +160,13 @@ impl Loader<'_> {
         if !self.pack.exists(&fsh) || !self.pack.exists(&vsh) {
             return None;
         }
-        if !enabled(self.properties, self.folder, &name, self.macros) {
+        if !enabled(
+            self.properties,
+            self.folder,
+            &name,
+            self.macros,
+            &self.switches,
+        ) {
             return None;
         }
         if self.pack.exists(&path("gsh")) {
@@ -215,8 +225,14 @@ fn diagnostics(pp: &Preprocessed) -> Vec<String> {
 }
 
 /// `program.<name>.enabled` (or `program.<folder>/<name>.enabled`): a boolean expression over
-/// switch options (3.3). An option is on when its macro is defined.
-fn enabled(properties: &Properties, folder: &str, name: &str, macros: &Macros) -> bool {
+/// switch options (3.3): those on by default (8.1) and the defined macros.
+fn enabled(
+    properties: &Properties,
+    folder: &str,
+    name: &str,
+    macros: &Macros,
+    switches: &BTreeSet<String>,
+) -> bool {
     let keys = [
         format!("program.{folder}/{name}.enabled"),
         format!("program.{name}.enabled"),
@@ -230,6 +246,7 @@ fn enabled(properties: &Properties, folder: &str, name: &str, macros: &Macros) -
         match token {
             "true" => condition.push('1'),
             "false" => condition.push('0'),
+            t if switches.contains(t) => condition.push('1'),
             t if t.starts_with(|c: char| c.is_alphabetic() || c == '_') => {
                 condition.push_str(&format!("defined({t})"));
             }
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 32eecb3cc..83dcb3af9 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -472,6 +472,21 @@ mod tests {
         assert_eq!(i.outputs, [0, 1]);
     }
 
+    /// naga drops non-constant global initializers: they run in our `main`, one per declarator,
+    /// converting as GLSL's initialization does.
+    #[test]
+    fn global_initializers_read_uniforms() {
+        let fsh = "#version 120\nuniform float rainStrength;\nuniform ivec2 atlasSize;\n\
+                   vec2 size = atlasSize;\nvec3 a = vec3(rainStrength), b = a * 2.0, c;\n\
+                   const float k = rainStrength > 0.5 ? 1.0 : 0.0;\nfloat w[] = float[](rainStrength, 1.0);\n\
+                   void main() { c = b; gl_FragColor = vec4(a + c, size.x * k + w[0]); }\n";
+        let p = program(
+            &[("composite.vsh", VSH_120), ("composite.fsh", fsh)],
+            Target::Window,
+        );
+        assert!(p.is_ok(), "{:?}", p.err());
+    }
+
     #[test]
     fn core_programs_translate() {
         let vsh = "#version 330 core\nin vec3 vaPosition;\nin vec2 vaUV0;\nuniform mat4 modelViewMatrix, projectionMatrix;\n\
diff --git a/crates/horizon-shaders/src/translate/scan.rs b/crates/horizon-shaders/src/translate/scan.rs
index 6789893f4..392538f03 100644
--- a/crates/horizon-shaders/src/translate/scan.rs
+++ b/crates/horizon-shaders/src/translate/scan.rs
@@ -338,41 +338,115 @@ impl<'p> Stage<'p> {
         }
     }
 
-    /// A global `T name = a ? b : c;`: naga can't evaluate a conditional at global scope, so
-    /// the initializer becomes a function of ours on the same line (`T name; T hz_init_name() {
-    /// return a ? b : c; }`), called by our `main` before the pack's.
+    /// A global `T name = a ? b : c;` or, without `const`, any initialized global: naga only
+    /// evaluates constant initializers at global scope (a conditional is not one; GL drivers
+    /// also take uniforms and other globals there), so each initializer becomes a function of
+    /// ours on the same line (`T a; T hz_init_a() { return T(...); } T b; ...`), called by our
+    /// `main` before the pack's, in file order. The return converts as GLSL's initialization
+    /// does (`vec2 v = ivec2(...)`).
     pub(super) fn initializer(&mut self, words: &[usize], to: usize) {
         let text = |i: usize| self.tokens[i];
         let Some(eq) = words.iter().position(|&i| text(i) == "=") else {
             return;
         };
-        if !words[eq..].iter().any(|&i| text(i) == "?")
-            || words[..eq].iter().any(|&i| text(i) == ",")
-        {
+        // Declarators, split at top-level commas: (first word, `=` if any, end).
+        let mut declarators = Vec::new();
+        let (mut begin, mut nesting, mut assign) = (0, 0i32, None);
+        for (n, &i) in words.iter().enumerate() {
+            match text(i) {
+                "(" | "[" | "{" => nesting += 1,
+                ")" | "]" | "}" => nesting -= 1,
+                "=" if nesting == 0 && assign.is_none() => assign = Some(n),
+                "," if nesting == 0 => {
+                    declarators.push((begin, assign.take(), n));
+                    begin = n + 1;
+                }
+                _ => {}
+            }
+        }
+        declarators.push((begin, assign, words.len()));
+        let constant = words[..eq].iter().any(|&i| text(i) == "const");
+        let conditional =
+            |d: &(usize, Option<usize>, usize)| words[d.0..d.2].iter().any(|&i| text(i) == "?");
+        if constant && !declarators.iter().any(conditional) {
             return;
         }
-        let Some(name_at) = words[..eq].iter().rposition(|&i| is_ident(text(i))) else {
+        // The first declarator's name ends the type.
+        let first_end = declarators[0].1.unwrap_or(declarators[0].2);
+        let Some(name_at) = words[..first_end].iter().rposition(|&i| is_ident(text(i))) else {
             return;
         };
-        let name = text(words[name_at]).to_owned();
-        let array: String = words[name_at + 1..eq].iter().map(|&i| text(i)).collect();
-        let ty: Vec<&str> = words[..name_at]
-            .iter()
-            .map(|&i| text(i))
-            .filter(|&t| t != "const")
-            .collect();
-        let Some(ty) = ty.last() else { return };
+        // The type, with a `vec3[]`'s count written in.
+        let mut ty = String::new();
+        for &i in &words[..name_at] {
+            match text(i) {
+                "const" => {}
+                "]" if ty.ends_with('[') => match self.array_length(i) {
+                    Some(n) => write!(ty, "{n}]").unwrap(),
+                    None => return,
+                },
+                t if ty.is_empty() || t == "[" => ty.push_str(t),
+                // Qualifiers before the type (`highp`...): the type is the last word.
+                t => ty = t.to_owned(),
+            }
+        }
+        if ty.is_empty() {
+            return;
+        }
+        let mut replaced = Vec::new();
+        let mut names = Vec::new();
+        for (n, &(begin, assign, end)) in declarators.iter().enumerate() {
+            let name_at = if n == 0 { name_at } else { begin };
+            let name = text(words[name_at]).to_owned();
+            if !is_ident(&name) {
+                return;
+            }
+            let stop = assign.unwrap_or(end);
+            let mut array: String = words[name_at + 1..stop].iter().map(|&i| text(i)).collect();
+            if array == "[]" {
+                // `T x[] = T[](a, b)`: the count is written in, as the rewrite does for the name.
+                match assign.and_then(|a| self.array_length(words[a - 1])) {
+                    Some(n) => array = format!("[{n}]"),
+                    None => return,
+                }
+            }
+            let next = if n + 1 < declarators.len() {
+                format!(" {ty}")
+            } else {
+                String::new()
+            };
+            let end_token = words.get(end).copied().unwrap_or(to);
+            match assign {
+                Some(a) => {
+                    // Scalars, vectors and matrices convert; arrays and structs must match.
+                    let scalar = array.is_empty()
+                        && !ty.contains('[')
+                        && (matches!(ty.as_str(), "float" | "int" | "uint" | "bool")
+                            || ty.contains("vec")
+                            || ty.starts_with("mat"));
+                    let (open, close) = if scalar {
+                        (format!("{ty}("), ")")
+                    } else {
+                        (String::new(), "")
+                    };
+                    replaced.push((
+                        words[a],
+                        format!("; {ty}{array} hz_init_{name}() {{ return {open}"),
+                    ));
+                    replaced.push((end_token, format!("{close}; }}{next}")));
+                    names.push(name);
+                }
+                None if n + 1 < declarators.len() => replaced.push((end_token, format!(";{next}"))),
+                None => {}
+            }
+        }
         for &i in &words[..name_at] {
             if text(i) == "const" {
                 self.removed.push(i..i + 1);
             }
         }
-        self.replaced.insert(
-            words[eq],
-            format!("; {ty}{array} hz_init_{name}() {{ return"),
-        );
-        self.replaced.insert(to, "; }".into());
-        self.inits.push(name);
+        self.replaced.extend(replaced);
+        self.inits.extend(names);
     }
 
     /// A function definition or prototype: remember which parameters are samplers.

From 505e8e960f9956a51bde92a52b737d4f7f413c69 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:01:48 +0100
Subject: [PATCH 014/270] Shader packs, clean room 16: custom uniforms

`uniform.<type>.<name>` and `variable.<type>.<name>` of shaders.properties (3.4): an
expression parser with C precedence, the function table (math, vectors, `if`, `between`,
`equals`, `smooth`, `random`...), evaluated on the CPU once per frame in file order after the
frame's own uniforms. `smooth` keeps its state per call site and halves the distance to its
target every fade time (OQ-26 working answer). A name neither the frame nor the pack defines
reads 0 and is listed once in the log.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1, section 3.4; no other
loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_post.rs    |  36 +-
 .../horizon-client/src/gfx/pack_uniforms.rs   |  41 ++
 crates/horizon-shaders/src/custom.rs          | 570 ++++++++++++++++++
 crates/horizon-shaders/src/lib.rs             |   2 +
 crates/horizon-shaders/src/post.rs            |   4 +
 crates/horizon-shaders/tests/real_packs.rs    |   7 +
 6 files changed, 656 insertions(+), 4 deletions(-)
 create mode 100644 crates/horizon-shaders/src/custom.rs

diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 81a517dba..6520565ed 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -13,7 +13,7 @@
 
 use std::collections::HashMap;
 
-use horizon_shaders::{Format, Group, Kind, Post};
+use horizon_shaders::{Format, Group, Kind, Post, Val};
 
 use super::pack_uniforms::{self, FrameUniforms, PackInputs};
 
@@ -83,6 +83,8 @@ pub struct PackPost {
     passes: Vec<Pass>,
     /// What draws terrain (`gbuffers_terrain` or its fallback), between `prepare` and `deferred`.
     terrain: Option<Pass>,
+    /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
+    custom: horizon_shaders::Custom,
     atlas: Option<wgpu::TextureView>,
     lightmap: wgpu::TextureView,
     deferred_pre: u16,
@@ -342,8 +344,16 @@ fn build_pass(
     screen: wgpu::TextureFormat,
     notes: &mut Vec<String>,
     geometry: Option<&Geometry<'_>>,
+    custom: &[String],
 ) -> Option<Pass> {
     let features = device.features();
+    // The frame's uniforms, then the pack's custom ones.
+    let index = |name: &str| {
+        pack_uniforms::index(name).or_else(|| {
+            let k = custom.iter().position(|c| c == name)?;
+            Some(pack_uniforms::NAMES.len() + k)
+        })
+    };
     let mask = |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
     let interface = &p.program.interface;
     let mut entries = vec![entry(
@@ -499,7 +509,7 @@ fn build_pass(
     let missing: Vec<&str> = interface
         .uniforms
         .iter()
-        .filter(|u| !u.name.starts_with("hz_") && pack_uniforms::index(&u.name).is_none())
+        .filter(|u| !u.name.starts_with("hz_") && index(&u.name).is_none())
         .map(|u| u.name.as_str())
         .collect();
     if !missing.is_empty() {
@@ -516,7 +526,7 @@ fn build_pass(
         uniforms: interface
             .uniforms
             .iter()
-            .map(|u| (pack_uniforms::index(&u.name), u.ty.clone(), u.offset))
+            .map(|u| (index(&u.name), u.ty.clone(), u.offset))
             .collect(),
         name: p.name,
         group: p.group,
@@ -552,11 +562,27 @@ impl PackPost {
         });
         let mut notes = post.notes;
         notes.extend(post.config.notes);
+        let mut custom = post.custom;
+        let custom_names: Vec<String> = custom.uniforms().map(|u| u.0.to_owned()).collect();
+        // A first run finds the names neither the frame nor the pack defines.
+        custom.eval(0.0, &|n| pack_uniforms::index(n).map(|_| Val::scalar(0.0)));
+        if !custom.notes.is_empty() {
+            notes.push(format!("custom uniforms: {}", custom.notes.join("; ")));
+            custom.notes.clear();
+        }
         let mask =
             |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
         let mut used = 1u16;
         let mut build = |p: horizon_shaders::PostProgram, geometry: Option<&Geometry<'_>>| {
-            let pass = build_pass(device, p, &formats, screen, &mut notes, geometry)?;
+            let pass = build_pass(
+                device,
+                p,
+                &formats,
+                screen,
+                &mut notes,
+                geometry,
+                &custom_names,
+            )?;
             used |= pass.reads | pass.written | pass.flip;
             Some(pass)
         };
@@ -646,6 +672,7 @@ impl PackPost {
             notes,
             passes,
             terrain,
+            custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
             lightmap: world.lightmap,
             deferred_pre: mask(&post.deferred_pre),
@@ -907,6 +934,7 @@ impl PackPost {
     ) {
         self.resize(device, size);
         self.uniforms.update(frame, inputs, size);
+        self.uniforms.eval_custom(&mut self.custom);
         let Some(targets) = &self.targets else { return };
         let main = |m: u16, i: usize| usize::from(m & 1 << i != 0);
         let view = |m: u16, i: usize, alt: bool| {
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index 92eac4a75..5a27e62a0 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -304,6 +304,47 @@ impl FrameUniforms {
     }
 }
 
+impl FrameUniforms {
+    /// Evaluates the pack's custom uniforms with this frame's values and puts them after
+    /// `NAMES`' values, in `custom.uniforms()` order.
+    pub fn eval_custom(&mut self, custom: &mut horizon_shaders::Custom) {
+        self.values.truncate(NAMES.len());
+        let values = &self.values;
+        let builtin = |name: &str| {
+            let v = values.get(index(name)?)?;
+            let n = components(name);
+            Some(match *v {
+                Value::F(f) => horizon_shaders::Val::vector(&f.map(f64::from)[..n]),
+                Value::I(i) => horizon_shaders::Val::vector(&i.map(f64::from)[..n.min(3)]),
+            })
+        };
+        let dt = match index("frameTime").and_then(|i| values.get(i)) {
+            Some(Value::F(f)) => f64::from(f[0]),
+            _ => 0.0,
+        };
+        let out = custom.eval(dt, &builtin);
+        self.values
+            .extend(out.iter().map(|v| Value::f(&v.v.map(|x| x as f32)[..v.n])));
+    }
+}
+
+/// How many components the uniform `name` has (16 for a matrix).
+fn components(name: &str) -> usize {
+    match name {
+        "cameraPosition"
+        | "previousCameraPosition"
+        | "upPosition"
+        | "sunPosition"
+        | "moonPosition"
+        | "shadowLightPosition"
+        | "fogColor"
+        | "skyColor" => 3,
+        "eyeBrightness" | "eyeBrightnessSmooth" | "atlasSize" => 2,
+        n if n.starts_with("gbuffer") || n.starts_with("shadow") && n != "shadowAngle" => 16,
+        _ => 1,
+    }
+}
+
 /// The position of `name` in [`NAMES`].
 pub fn index(name: &str) -> Option<usize> {
     NAMES.iter().position(|n| *n == name)
diff --git a/crates/horizon-shaders/src/custom.rs b/crates/horizon-shaders/src/custom.rs
new file mode 100644
index 000000000..34510247e
--- /dev/null
+++ b/crates/horizon-shaders/src/custom.rs
@@ -0,0 +1,570 @@
+//! Custom uniforms and variables of `shaders.properties` (spec 3.4): `uniform.<type>.<name>` and
+//! `variable.<type>.<name>` expressions, parsed once and evaluated on the CPU every frame in
+//! file order. Uniforms reach every program; variables only later expressions.
+//!
+//! Decisions (impl-plan.md):
+//! - OQ-25: numbers are doubles; booleans are 1 and 0; `%` is C's remainder (`fmod` floors);
+//!   comparisons and logic read the first component; a value takes its declared type at the
+//!   end (`int` truncates toward zero, `bool` is "not zero"). Unknown names read 0 and are
+//!   reported once.
+//! - OQ-26: `smooth` runs per frame with the frame time; its fade times are seconds (1 by
+//!   default) to cover half of the remaining distance, `fadeIn` while rising, `fadeOut` while
+//!   falling. Each call keeps its own state, so the optional id is not needed.
+
+use std::collections::{HashMap, HashSet};
+
+use crate::Properties;
+
+/// A value: up to 16 components (matrices only as names, for `m.row.column`).
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Val {
+    pub v: [f64; 16],
+    /// Components: 1 for a scalar.
+    pub n: usize,
+}
+
+impl Val {
+    pub fn scalar(x: f64) -> Self {
+        let mut v = [0.0; 16];
+        v[0] = x;
+        Self { v, n: 1 }
+    }
+    pub fn vector(c: &[f64]) -> Self {
+        let mut v = [0.0; 16];
+        v[..c.len()].copy_from_slice(c);
+        Self { v, n: c.len() }
+    }
+    fn x(&self) -> f64 {
+        self.v[0]
+    }
+    fn truth(&self) -> bool {
+        self.v[0] != 0.0
+    }
+    /// `f` per component; a scalar operand stretches to the other's size.
+    fn zip(self, o: Val, f: impl Fn(f64, f64) -> f64) -> Val {
+        let n = self.n.max(o.n).min(4);
+        let at = |a: &Val, i: usize| if a.n == 1 { a.v[0] } else { a.v[i] };
+        let mut out = Val::scalar(0.0);
+        out.n = n;
+        for i in 0..n {
+            out.v[i] = f(at(&self, i), at(&o, i));
+        }
+        out
+    }
+    fn map(self, f: impl Fn(f64) -> f64) -> Val {
+        let mut out = self;
+        for i in 0..self.n.min(4) {
+            out.v[i] = f(self.v[i]);
+        }
+        out
+    }
+}
+
+#[derive(Clone, Debug)]
+enum Expr {
+    Num(f64),
+    /// A name and its component (`x`, `2`, `2.1` as row 2, column 1).
+    Name(String, Option<(usize, Option<usize>)>),
+    Call(String, Vec<Expr>, usize),
+    Neg(Box<Expr>),
+    Not(Box<Expr>),
+    Bin(&'static str, Box<Expr>, Box<Expr>),
+}
+
+#[derive(Debug)]
+struct Item {
+    name: String,
+    ty: String,
+    uniform: bool,
+    expr: Expr,
+}
+
+/// The pack's custom uniforms and variables, with the state `smooth` and `random` keep.
+#[derive(Debug, Default)]
+pub struct Custom {
+    items: Vec<Item>,
+    /// `smooth` state per call site.
+    smooth: HashMap<usize, f64>,
+    seed: u64,
+    unknown: HashSet<String>,
+    /// Expressions that did not parse, and unknown names, as `key: message`.
+    pub notes: Vec<String>,
+    calls: usize,
+}
+
+impl Custom {
+    /// Reads every `uniform.*` and `variable.*` key of `properties`, in file order.
+    pub fn parse(properties: &Properties) -> Self {
+        let mut out = Custom {
+            seed: 0x9e37_79b9_7f4a_7c15,
+            ..Default::default()
+        };
+        for e in &properties.entries {
+            let (uniform, rest) = match e.key.split_once('.') {
+                Some(("uniform", r)) => (true, r),
+                Some(("variable", r)) => (false, r),
+                _ => continue,
+            };
+            let Some((ty, name)) = rest.split_once('.') else {
+                continue;
+            };
+            if !matches!(ty, "float" | "int" | "bool" | "vec2" | "vec3" | "vec4") {
+                out.notes
+                    .push(format!("{}: type `{ty}` is not supported", e.key));
+                continue;
+            }
+            match Parser::new(&e.value, &mut out.calls).expr_all() {
+                Ok(expr) => out.items.push(Item {
+                    name: name.to_owned(),
+                    ty: ty.to_owned(),
+                    uniform,
+                    expr,
+                }),
+                Err(m) => out.notes.push(format!("{}: {m}", e.key)),
+            }
+        }
+        out
+    }
+
+    /// The uniforms' names and declared types, in file order.
+    pub fn uniforms(&self) -> impl Iterator<Item = (&str, &str)> {
+        self.items
+            .iter()
+            .filter(|i| i.uniform)
+            .map(|i| (i.name.as_str(), i.ty.as_str()))
+    }
+
+    /// Evaluates everything for a frame `dt` seconds after the last; `builtin` gives the
+    /// values of the game's uniforms and constants (`BIOME_*`...). Returns the uniforms'
+    /// values, in the order of `uniforms`.
+    pub fn eval(&mut self, dt: f64, builtin: &dyn Fn(&str) -> Option<Val>) -> Vec<Val> {
+        let mut vars: HashMap<String, Val> = HashMap::new();
+        let mut out = Vec::new();
+        let items = std::mem::take(&mut self.items);
+        for item in &items {
+            let v = self.value(&item.expr, dt, &vars, builtin);
+            let v = match item.ty.as_str() {
+                "int" => Val::scalar(v.x().trunc()),
+                "bool" => Val::scalar(f64::from(u8::from(v.truth()))),
+                "float" => Val::scalar(v.x()),
+                t => {
+                    let n = (t.as_bytes()[3] - b'0') as usize;
+                    let mut v = v;
+                    if v.n == 1 {
+                        let x = v.v[0];
+                        v.v[1..n].fill(x);
+                    }
+                    v.n = n;
+                    v
+                }
+            };
+            vars.insert(item.name.clone(), v);
+            if item.uniform {
+                out.push(v);
+            }
+        }
+        self.items = items;
+        out
+    }
+
+    fn random(&mut self) -> f64 {
+        self.seed ^= self.seed << 13;
+        self.seed ^= self.seed >> 7;
+        self.seed ^= self.seed << 17;
+        (self.seed >> 11) as f64 / (1u64 << 53) as f64
+    }
+
+    fn value(
+        &mut self,
+        e: &Expr,
+        dt: f64,
+        vars: &HashMap<String, Val>,
+        builtin: &dyn Fn(&str) -> Option<Val>,
+    ) -> Val {
+        let ev = |e: &Expr, s: &mut Self| s.value(e, dt, vars, builtin);
+        match e {
+            Expr::Num(x) => Val::scalar(*x),
+            Expr::Name(name, component) => {
+                let v = match name.as_str() {
+                    "pi" => Some(Val::scalar(std::f64::consts::PI)),
+                    "true" => Some(Val::scalar(1.0)),
+                    "false" => Some(Val::scalar(0.0)),
+                    n => vars.get(n).copied().or_else(|| builtin(n)),
+                };
+                let Some(v) = v else {
+                    if self.unknown.insert(name.clone()) {
+                        self.notes.push(format!("`{name}` is unknown; it reads 0"));
+                    }
+                    return Val::scalar(0.0);
+                };
+                match component {
+                    None => v,
+                    // GLSL's m[column][row] is stored column after column.
+                    Some((row, Some(column))) => Val::scalar(v.v[column * 4 + row]),
+                    Some((i, None)) => Val::scalar(v.v[*i]),
+                }
+            }
+            Expr::Neg(a) => ev(a, self).map(|x| -x),
+            Expr::Not(a) => Val::scalar(f64::from(u8::from(!ev(a, self).truth()))),
+            Expr::Bin(op, a, b) => {
+                let (a, b) = (ev(a, self), ev(b, self));
+                let bool_ = |c: bool| Val::scalar(f64::from(u8::from(c)));
+                match *op {
+                    "+" => a.zip(b, |x, y| x + y),
+                    "-" => a.zip(b, |x, y| x - y),
+                    "*" => a.zip(b, |x, y| x * y),
+                    "/" => a.zip(b, |x, y| x / y),
+                    "%" => a.zip(b, |x, y| x % y),
+                    "<" => bool_(a.x() < b.x()),
+                    "<=" => bool_(a.x() <= b.x()),
+                    ">" => bool_(a.x() > b.x()),
+                    ">=" => bool_(a.x() >= b.x()),
+                    "==" => bool_(a.x() == b.x()),
+                    "!=" => bool_(a.x() != b.x()),
+                    "&&" => bool_(a.truth() && b.truth()),
+                    _ => bool_(a.truth() || b.truth()),
+                }
+            }
+            Expr::Call(f, args, site) => {
+                let a: Vec<Val> = args.iter().map(|e| ev(e, self)).collect();
+                let arg = |i: usize| a.get(i).copied().unwrap_or(Val::scalar(0.0));
+                let x = arg(0).x();
+                let one = |g: fn(f64) -> f64| arg(0).map(g);
+                match f.as_str() {
+                    "sin" => one(f64::sin),
+                    "cos" => one(f64::cos),
+                    "tan" => one(f64::tan),
+                    "asin" => one(f64::asin),
+                    "acos" => one(f64::acos),
+                    "atan" if a.len() == 2 => Val::scalar(x.atan2(arg(1).x())),
+                    "atan" => one(f64::atan),
+                    "atan2" => Val::scalar(x.atan2(arg(1).x())),
+                    "torad" | "radians" => one(f64::to_radians),
+                    "todeg" | "degrees" => one(f64::to_degrees),
+                    "min" => a
+                        .iter()
+                        .copied()
+                        .reduce(|p, q| p.zip(q, f64::min))
+                        .unwrap_or(arg(0)),
+                    "max" => a
+                        .iter()
+                        .copied()
+                        .reduce(|p, q| p.zip(q, f64::max))
+                        .unwrap_or(arg(0)),
+                    "clamp" => arg(0).zip(arg(1), f64::max).zip(arg(2), f64::min),
+                    "abs" => one(f64::abs),
+                    "floor" => one(f64::floor),
+                    "ceil" => one(f64::ceil),
+                    "exp" => one(f64::exp),
+                    "exp2" => one(f64::exp2),
+                    "exp10" => one(|v| 10f64.powf(v)),
+                    "frac" => one(|v| v - v.floor()),
+                    "log" if a.len() == 2 => Val::scalar(arg(1).x().log(x)),
+                    "log" => one(f64::ln),
+                    "log2" => one(f64::log2),
+                    "log10" => one(f64::log10),
+                    "sqrt" => one(f64::sqrt),
+                    "round" => one(f64::round),
+                    "signum" | "sign" => one(|v| if v == 0.0 { 0.0 } else { v.signum() }),
+                    "pow" => arg(0).zip(arg(1), f64::powf),
+                    "fmod" => arg(0).zip(arg(1), |p, q| p - q * (p / q).floor()),
+                    "lerp" => arg(1).zip(arg(2), |p, q| p + (q - p) * x),
+                    "mix" => arg(0).zip(arg(1), |p, q| p + (q - p) * arg(2).x()),
+                    "edge" => Val::scalar(if arg(1).x() < x { 0.0 } else { 1.0 }),
+                    "random" if a.len() == 2 => Val::scalar(x + (arg(1).x() - x) * self.random()),
+                    "random" => Val::scalar(self.random()),
+                    "randomInt" if a.len() == 2 => {
+                        Val::scalar((x + (arg(1).x() - x) * self.random()).floor())
+                    }
+                    "randomInt" => Val::scalar((self.random() * f64::from(i32::MAX)).floor()),
+                    "if" | "ifb" => {
+                        let mut i = 0;
+                        while i + 1 < a.len() {
+                            if a[i].truth() {
+                                return a[i + 1];
+                            }
+                            i += 2;
+                        }
+                        a.last().copied().unwrap_or(Val::scalar(0.0))
+                    }
+                    "smooth" => {
+                        let (val, fade_in, fade_out) = match a.len() {
+                            4 => (arg(1).x(), arg(2).x(), arg(3).x()),
+                            3 => (x, arg(1).x(), arg(2).x()),
+                            2 => (x, arg(1).x(), arg(1).x()),
+                            _ => (x, 1.0, 1.0),
+                        };
+                        let state = self.smooth.entry(*site).or_insert(val);
+                        let fade = if val > *state { fade_in } else { fade_out };
+                        if fade > 0.0 {
+                            *state = val + (*state - val) * 0.5f64.powf(dt / fade);
+                        } else {
+                            *state = val;
+                        }
+                        Val::scalar(*state)
+                    }
+                    "print" => arg(2),
+                    "between" => {
+                        Val::scalar(f64::from(u8::from(x >= arg(1).x() && x <= arg(2).x())))
+                    }
+                    "equals" => {
+                        Val::scalar(f64::from(u8::from((x - arg(1).x()).abs() <= arg(2).x())))
+                    }
+                    "in" => Val::scalar(f64::from(u8::from(a[1..].iter().any(|v| v.x() == x)))),
+                    "vec2" | "vec3" | "vec4" => {
+                        let n = (f.as_bytes()[3] - b'0') as usize;
+                        let mut c: Vec<f64> = a.iter().flat_map(|v| v.v[..v.n].to_vec()).collect();
+                        if c.len() == 1 {
+                            c = vec![c[0]; n];
+                        }
+                        c.resize(n, 0.0);
+                        Val::vector(&c)
+                    }
+                    _ => {
+                        if self.unknown.insert(f.clone()) {
+                            self.notes.push(format!("`{f}()` is unknown; it gives 0"));
+                        }
+                        Val::scalar(0.0)
+                    }
+                }
+            }
+        }
+    }
+}
+
+struct Parser<'a> {
+    tokens: Vec<String>,
+    at: usize,
+    calls: &'a mut usize,
+}
+
+const OPERATORS: [&str; 18] = [
+    "||", "&&", "==", "!=", "<=", ">=", "<", ">", "+", "-", "*", "/", "%", "!", "(", ")", ",", ".",
+];
+
+impl<'a> Parser<'a> {
+    fn new(text: &str, calls: &'a mut usize) -> Self {
+        let mut tokens = Vec::new();
+        let b = text.as_bytes();
+        let mut i = 0;
+        while i < b.len() {
+            let c = b[i] as char;
+            if c.is_whitespace() {
+                i += 1;
+            } else if c.is_ascii_digit()
+                || (c == '.'
+                    && b.get(i + 1).is_some_and(u8::is_ascii_digit)
+                    && !tokens
+                        .last()
+                        .is_some_and(|t: &String| t == "." || is_name(t)))
+            {
+                let start = i;
+                while i < b.len()
+                    && (b[i].is_ascii_alphanumeric()
+                        || b[i] == b'.'
+                        || ((b[i] == b'-' || b[i] == b'+') && matches!(b[i - 1], b'e' | b'E')))
+                {
+                    i += 1;
+                }
+                tokens.push(text[start..i].to_owned());
+            } else if c.is_ascii_alphabetic() || c == '_' {
+                let start = i;
+                while i < b.len() && (b[i].is_ascii_alphanumeric() || b[i] == b'_') {
+                    i += 1;
+                }
+                tokens.push(text[start..i].to_owned());
+            } else {
+                let op = OPERATORS
+                    .iter()
+                    .find(|o| text[i..].starts_with(**o))
+                    .map_or(&text[i..i + c.len_utf8()], |o| o);
+                i += op.len();
+                tokens.push(op.to_owned());
+            }
+        }
+        Parser {
+            tokens,
+            at: 0,
+            calls,
+        }
+    }
+    fn peek(&self) -> Option<&str> {
+        self.tokens.get(self.at).map(String::as_str)
+    }
+    fn eat(&mut self, t: &str) -> bool {
+        let hit = self.peek() == Some(t);
+        self.at += usize::from(hit);
+        hit
+    }
+    fn expr_all(&mut self) -> Result<Expr, String> {
+        let e = self.binary(0)?;
+        match self.peek() {
+            None => Ok(e),
+            Some(t) => Err(format!("unexpected `{t}`")),
+        }
+    }
+    /// Precedence levels from the loosest: `||`, `&&`, equality, relations, sums, products.
+    fn binary(&mut self, level: usize) -> Result<Expr, String> {
+        const LEVELS: [&[&str]; 6] = [
+            &["||"],
+            &["&&"],
+            &["==", "!="],
+            &["<", "<=", ">", ">="],
+            &["+", "-"],
+            &["*", "/", "%"],
+        ];
+        if level == LEVELS.len() {
+            return self.unary();
+        }
+        let mut left = self.binary(level + 1)?;
+        while let Some(op) = self
+            .peek()
+            .and_then(|t| LEVELS[level].iter().find(|o| **o == t))
+        {
+            self.at += 1;
+            let right = self.binary(level + 1)?;
+            left = Expr::Bin(op, Box::new(left), Box::new(right));
+        }
+        Ok(left)
+    }
+    fn unary(&mut self) -> Result<Expr, String> {
+        if self.eat("-") {
+            return Ok(Expr::Neg(Box::new(self.unary()?)));
+        }
+        if self.eat("!") {
+            return Ok(Expr::Not(Box::new(self.unary()?)));
+        }
+        self.eat("+");
+        self.primary()
+    }
+    fn primary(&mut self) -> Result<Expr, String> {
+        let Some(t) = self.peek().map(str::to_owned) else {
+            return Err("the expression ends early".into());
+        };
+        self.at += 1;
+        if t == "(" {
+            let e = self.binary(0)?;
+            return if self.eat(")") {
+                Ok(e)
+            } else {
+                Err("missing `)`".into())
+            };
+        }
+        if t.starts_with(|c: char| c.is_ascii_digit() || c == '.') {
+            return t
+                .trim_end_matches(['f', 'F'])
+                .parse()
+                .map(Expr::Num)
+                .map_err(|_| format!("bad number `{t}`"));
+        }
+        if !is_name(&t) {
+            return Err(format!("unexpected `{t}`"));
+        }
+        if self.eat("(") {
+            let mut args = Vec::new();
+            if !self.eat(")") {
+                loop {
+                    args.push(self.binary(0)?);
+                    if self.eat(")") {
+                        break;
+                    }
+                    if !self.eat(",") {
+                        return Err(format!("missing `)` after the arguments of `{t}`"));
+                    }
+                }
+            }
+            *self.calls += 1;
+            return Ok(Expr::Call(t, args, *self.calls));
+        }
+        let component = if self.eat(".") {
+            let c = self.peek().map(str::to_owned).ok_or("nothing after `.`")?;
+            self.at += 1;
+            let index = |s: &str| match s {
+                "x" | "r" | "s" | "0" => Some(0),
+                "y" | "g" | "t" | "1" => Some(1),
+                "z" | "b" | "p" | "2" => Some(2),
+                "w" | "a" | "q" | "3" => Some(3),
+                _ => None,
+            };
+            Some(match c.split_once('.') {
+                Some((r, col)) => (
+                    index(r).ok_or(format!("bad component `{c}`"))?,
+                    Some(index(col).ok_or(format!("bad component `{c}`"))?),
+                ),
+                None => (index(&c).ok_or(format!("bad component `{c}`"))?, None),
+            })
+        } else {
+            None
+        };
+        Ok(Expr::Name(t, component))
+    }
+}
+
+fn is_name(t: &str) -> bool {
+    t.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_')
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Macros;
+
+    fn custom(text: &str) -> Custom {
+        Custom::parse(&Properties::parse(text, &Macros::standard()))
+    }
+
+    #[test]
+    fn expressions_follow_c_precedence_and_file_order() {
+        let mut c = custom(
+            "variable.float.a = 1 + 2 * 3 - 4 % 3\n\
+             uniform.float.b = a / 2\n\
+             uniform.bool.c = a > 5 && !(b < 1) || false\n\
+             uniform.int.d = -7 / 2\n\
+             uniform.vec3.e = vec3(a, cameraPosition.y, 2) * 2\n\
+             uniform.float.f = if(a < 0, 1, a < 7, 2, 3) + clamp(fmod(-1, 4), 0, 2.5) + min(4, 2, 3)\n\
+             uniform.float.g = gbufferModelView.1.0 + frac(sunAngle - 0.25) + pi * 0\n\
+             uniform.float.h = unknownThing + in(biome, 3, BIOME_DESERT)\n",
+        );
+        assert!(c.notes.is_empty(), "{:?}", c.notes);
+        let names: Vec<_> = c.uniforms().map(|u| u.0).collect();
+        assert_eq!(names, ["b", "c", "d", "e", "f", "g", "h"]);
+        let builtin = |n: &str| match n {
+            "cameraPosition" => Some(Val::vector(&[1.0, 64.0, 2.0])),
+            "sunAngle" => Some(Val::scalar(0.125)),
+            "biome" => Some(Val::scalar(5.0)),
+            "BIOME_DESERT" => Some(Val::scalar(5.0)),
+            "gbufferModelView" => {
+                let mut m = Val::scalar(0.0);
+                m.v[1] = 9.0; // column 0, row 1
+                m.n = 16;
+                Some(m)
+            }
+            _ => None,
+        };
+        let v = c.eval(0.016, &builtin);
+        let x: Vec<f64> = v.iter().map(|v| v.v[0]).collect();
+        assert_eq!(x, [3.0, 1.0, -3.0, 12.0, 2.0 + 2.5 + 2.0, 9.0 + 0.875, 1.0]);
+        assert_eq!(&v[3].v[..3], &[12.0, 128.0, 4.0]);
+        assert_eq!(c.notes, ["`unknownThing` is unknown; it reads 0"]);
+    }
+
+    #[test]
+    fn smooth_halves_the_distance_per_fade_time() {
+        let mut c = custom("uniform.float.s = smooth(1, target, 2, 0.5)\n");
+        let mut target = 0.0;
+        let mut run = |t: f64, dt: f64| {
+            target = t;
+            c.eval(dt, &|n: &str| (n == "target").then(|| Val::scalar(target)))[0].v[0]
+        };
+        assert_eq!(run(0.0, 0.0), 0.0);
+        assert!((run(1.0, 2.0) - 0.5).abs() < 1e-9, "rising: fadeIn");
+        assert!((run(0.0, 0.5) - 0.25).abs() < 1e-9, "falling: fadeOut");
+    }
+
+    #[test]
+    fn bad_expressions_are_reported() {
+        let c = custom("uniform.float.a = (1 + \nuniform.mat4.m = 1\nuniform.float.ok = 2\n");
+        assert_eq!(c.uniforms().count(), 1);
+        assert_eq!(c.notes.len(), 2, "{:?}", c.notes);
+    }
+}
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index d29a0a632..47cbcca11 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -14,6 +14,7 @@
 
 mod condition;
 mod config;
+mod custom;
 mod discover;
 mod lang;
 mod macros;
@@ -26,6 +27,7 @@ mod translate;
 
 pub use condition::eval_condition;
 pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffers};
+pub use custom::{Custom, Val};
 pub use discover::{Found, discover};
 pub use lang::Lang;
 pub use macros::{MC_VERSION, Macros, RENDER_STAGES};
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index c96730f0a..d6142c70a 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -13,6 +13,7 @@
 use std::collections::BTreeSet;
 
 use crate::config::{self, Config};
+use crate::custom::Custom;
 use crate::{GbuffersInputs, Macros, Pack, Preprocessed, Program, Properties, Target};
 use crate::{eval_condition, preprocess, translate_composite, translate_gbuffers};
 
@@ -62,6 +63,8 @@ pub struct Post {
     pub composite_pre: Vec<(u32, bool)>,
     /// What draws solid and cutout terrain, when the game asked for it and one loads.
     pub terrain: Option<PostProgram>,
+    /// The custom uniforms of `shaders.properties` (3.4).
+    pub custom: Custom,
     pub config: Config,
     /// Programs skipped and why, as `program: message` or `file:line: message`.
     pub notes: Vec<String>,
@@ -93,6 +96,7 @@ pub fn load_post(
         deferred_pre: flips(properties, "deferred_pre"),
         composite_pre: flips(properties, "composite_pre"),
         terrain: None,
+        custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
     };
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index d0a28d71d..78ba97bfb 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -182,6 +182,13 @@ fn real_packs_read() {
                 post.notes.len() + post.config.notes.len(),
                 start.elapsed().as_secs_f64() * 1000.0
             );
+            let mut custom = post.custom;
+            custom.eval(0.016, &|_| None);
+            println!(
+                "    {} custom uniforms; notes: {:?}",
+                custom.uniforms().count(),
+                custom.notes.iter().take(4).collect::<Vec<_>>()
+            );
             for n in post.notes.iter().chain(&post.config.notes).take(12) {
                 println!("    {n}");
             }

From a2ec3fc791e773c69b852922ca53af1be298cd47 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:03:17 +0100
Subject: [PATCH 015/270] Shader packs, clean room 17: real packs' buffers and
 samplers

- RGBA16 and R11F_G11F_B10F buffers get their own formats where the device has them
  (16-bit normalized render targets need the adapter's format features): the float stand-in
  kept NaN and values past 1, and BSL's TAA history went black for good.
- Textures share one sampler variable per kind (linear, nearest, repeat, nearest-repeat,
  comparison): devices have as few as 16 sampler slots, Complementary's terrain program
  declares 23 textures.
- A gbuffers pass reading the depth buffer or a buffer it draws into reads a blank texture
  instead (a feedback loop: undefined in GL, refused by wgpu, and a crash here).
- A bind group layout that fails validation skips the program with the error's details
  instead of ending the game.
- shadowModelView / shadowProjection (and inverses) for programs that read them before the
  shadow pass exists: an orthographic camera 160 blocks each side, toward the shadow light.
- HORIZON_SHADER_PACK_SKIP=a,b leaves programs out (a developers' aid to bisect a pack).

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1, sections 6.1, 6.7,
5.2; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              |   9 +-
 crates/horizon-client/src/gfx/pack_post.rs    | 243 ++++++++++++++----
 .../horizon-client/src/gfx/pack_uniforms.rs   |  16 ++
 3 files changed, 209 insertions(+), 59 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index c117b190f..a33d54fa3 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -816,12 +816,17 @@ async fn open_device(
             continue;
         }
         // Mappable primary buffers: section pages that no longer fit in
-        // video memory go to system memory.
+        // video memory go to system memory. Shader packs' 16-bit normalized buffers (render
+        // targets with the adapter's own format features) and R11F_G11F_B10F: a float
+        // stand-in neither clamps nor drops NaN.
         let features = timing::GpuTimer::features(&adapter)
             | cull::Cull::features(&adapter)
             | (adapter.features()
                 & (wgpu::Features::INDIRECT_FIRST_INSTANCE
-                    | wgpu::Features::MAPPABLE_PRIMARY_BUFFERS));
+                    | wgpu::Features::MAPPABLE_PRIMARY_BUFFERS
+                    | wgpu::Features::TEXTURE_FORMAT_16BIT_NORM
+                    | wgpu::Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES
+                    | wgpu::Features::RG11B10UFLOAT_RENDERABLE));
         let driver = format!("{} {}", info.driver, info.driver_info);
         startup_step(format_args!(
             "requesting the device (driver {}) with features [{features}] and the adapter's \
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 6520565ed..0201c7976 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -39,6 +39,82 @@ struct Binding {
     binding: u32,
     /// A filtering sampler (the texture is filterable).
     filtering: bool,
+    /// Where this texture's sampler object is bound: the first texture of each kind binds it
+    /// (`binding + 1`), the others share it (devices have as few as 16 sampler slots).
+    sampler: u32,
+}
+
+/// The sampler objects a pass binds, one slot per kind it uses.
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+enum SamplerKind {
+    Linear,
+    Nearest,
+    Repeat,
+    NearestRepeat,
+    Comparison,
+}
+
+impl SamplerKind {
+    fn of(source: Source, filtering: bool) -> Self {
+        match source {
+            Source::Color(_) | Source::Dummy if !filtering => Self::Nearest,
+            Source::Depth => Self::Nearest,
+            Source::Noise => Self::Repeat,
+            Source::Shadow => Self::Comparison,
+            // Blocks look as the game draws them: nearest texels.
+            Source::Atlas => Self::NearestRepeat,
+            Source::Color(_) | Source::Dummy | Source::Lightmap => Self::Linear,
+        }
+    }
+
+    fn binding_type(self) -> wgpu::SamplerBindingType {
+        match self {
+            Self::Linear | Self::Repeat => wgpu::SamplerBindingType::Filtering,
+            Self::Nearest | Self::NearestRepeat => wgpu::SamplerBindingType::NonFiltering,
+            Self::Comparison => wgpu::SamplerBindingType::Comparison,
+        }
+    }
+}
+
+/// Points every sampler object of `module` at the slot `slot` gives its binding, so that
+/// samplers sharing a slot become one variable (two variables may not share a binding).
+fn share_samplers(module: &mut naga::Module, slot: &HashMap<u32, u32>) {
+    let mut first = HashMap::new();
+    let mut same = HashMap::new();
+    for (h, g) in module.global_variables.iter_mut() {
+        let Some(b) = g.binding.as_mut() else {
+            continue;
+        };
+        if !matches!(module.types[g.ty].inner, naga::TypeInner::Sampler { .. }) {
+            continue;
+        }
+        let Some(&to) = slot.get(&b.binding) else {
+            continue;
+        };
+        b.binding = to;
+        match first.entry(to) {
+            std::collections::hash_map::Entry::Occupied(e) => _ = same.insert(h, *e.get()),
+            std::collections::hash_map::Entry::Vacant(e) => _ = e.insert(h),
+        }
+    }
+    if same.is_empty() {
+        return;
+    }
+    let fix = |expressions: &mut naga::Arena<naga::Expression>| {
+        for (_, e) in expressions.iter_mut() {
+            if let naga::Expression::GlobalVariable(g) = e
+                && let Some(&to) = same.get(g)
+            {
+                *g = to;
+            }
+        }
+    };
+    for (_, f) in module.functions.iter_mut() {
+        fix(&mut f.expressions);
+    }
+    for ep in &mut module.entry_points {
+        fix(&mut ep.function.expressions);
+    }
 }
 
 struct Pass {
@@ -128,7 +204,12 @@ fn texture_format(f: Format, features: wgpu::Features) -> wgpu::TextureFormat {
     let half = pick(T::R16Float, T::Rg16Float, T::Rgba16Float);
     match (f.kind, f.bits) {
         (Kind::Unorm, 10) => T::Rgb10a2Unorm,
-        (Kind::Unorm, 16) if features.contains(wgpu::Features::TEXTURE_FORMAT_16BIT_NORM) => {
+        (Kind::Unorm, 16)
+            if features.contains(
+                wgpu::Features::TEXTURE_FORMAT_16BIT_NORM
+                    | wgpu::Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES,
+            ) =>
+        {
             pick(T::R16Unorm, T::Rg16Unorm, T::Rgba16Unorm)
         }
         (Kind::Unorm, b) if b <= 8 => pick(T::R8Unorm, T::Rg8Unorm, T::Rgba8Unorm),
@@ -229,8 +310,11 @@ fn checked<T>(device: &wgpu::Device, create: impl FnOnce() -> T) -> Result<T, St
     let value = create();
     match pollster::block_on(scope.pop()) {
         Some(e) => {
-            // The details are in the error's sources.
-            let mut message = e.to_string();
+            // The details are in the error's description or its sources.
+            let mut message = match &e {
+                wgpu::Error::Validation { source, .. } => format!("{source:?}"),
+                e => e.to_string(),
+            };
             let mut source = std::error::Error::source(&e);
             while let Some(s) = source {
                 message = format!("{message}: {s}");
@@ -365,12 +449,22 @@ fn build_pass(
         },
     )];
     let mut samplers = Vec::new();
+    let (mut kinds, mut slots) = (HashMap::new(), HashMap::new());
     let mut reads = 0u16;
+    // A gbuffers pass draws into its buffers and the depth buffer: reading them as well would
+    // be a feedback loop (undefined in GL, refused by wgpu), so those read a blank texture.
+    let in_place = match geometry {
+        Some(_) => p.buffers.iter().fold(0u16, |m, &b| m | 1 << b),
+        None => 0,
+    };
     for s in &interface.samplers {
         let mut src = source(&s.name);
-        if src == Source::Atlas && geometry.is_none() {
-            src = Source::Dummy;
-        }
+        let blank = match src {
+            Source::Atlas => geometry.is_none(),
+            Source::Depth => geometry.is_some(),
+            Source::Color(n) => in_place & 1 << n != 0,
+            _ => false,
+        };
         let float = wgpu::TextureSampleType::Float { filterable: true };
         let mut sample_type = match src {
             Source::Color(n) => formats[n]
@@ -399,25 +493,32 @@ fn build_pass(
             ));
             (src, sample_type) = (Source::Dummy, float);
         }
+        if blank {
+            // The blank texture is float: an integer sampler then fails the pipeline (a note).
+            src = Source::Dummy;
+            if int {
+                sample_type = float;
+            }
+        }
         let filtering = sample_type == float;
         if let Source::Color(n) = src {
             reads |= 1 << n;
         }
         entries.push(texture_entry(s.binding, sample_type));
-        entries.push(entry(
-            s.binding + 1,
-            wgpu::BindingType::Sampler(if src == Source::Shadow {
-                wgpu::SamplerBindingType::Comparison
-            } else if filtering {
-                wgpu::SamplerBindingType::Filtering
-            } else {
-                wgpu::SamplerBindingType::NonFiltering
-            }),
-        ));
+        let kind = SamplerKind::of(src, filtering);
+        let sampler = *kinds.entry(kind).or_insert_with(|| {
+            entries.push(entry(
+                s.binding + 1,
+                wgpu::BindingType::Sampler(kind.binding_type()),
+            ));
+            s.binding + 1
+        });
+        slots.insert(s.binding + 1, sampler);
         samplers.push(Binding {
             source: src,
             binding: s.binding,
             filtering,
+            sampler,
         });
     }
     let final_pass = p.group == Group::Final;
@@ -453,24 +554,25 @@ fn build_pass(
     } else {
         (written & !kept) | mask(&p.flips)
     };
-    let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
-        label: Some(&p.name),
-        entries: &entries,
-    });
-    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
-        label: Some(&p.name),
-        bind_group_layouts: &[Some(&layout), geometry.and_then(|g| g.table)],
-        ..Default::default()
-    });
     let created = checked(device, || {
-        let module = |m: naga::Module| {
+        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some(&p.name),
+            entries: &entries,
+        });
+        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+            label: Some(&p.name),
+            bind_group_layouts: &[Some(&layout), geometry.and_then(|g| g.table)],
+            ..Default::default()
+        });
+        let module = |mut m: naga::Module| {
+            share_samplers(&mut m, &slots);
             device.create_shader_module(wgpu::ShaderModuleDescriptor {
                 label: Some(&p.name),
                 source: wgpu::ShaderSource::Naga(std::borrow::Cow::Owned(m)),
             })
         };
         let (vs, fs) = (module(p.program.vertex), module(p.program.fragment));
-        device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
+        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
             label: Some(&p.name),
             layout: Some(&pipeline_layout),
             vertex: wgpu::VertexState {
@@ -496,10 +598,11 @@ fn build_pass(
             }),
             multiview_mask: None,
             cache: None,
-        })
+        });
+        (layout, pipeline)
     });
-    let pipeline = match created {
-        Ok(p) => p,
+    let (layout, pipeline) = match created {
+        Ok(created) => created,
         Err(e) => {
             notes.push(format!("{}: skipped: {e}", p.name));
             return None;
@@ -590,9 +693,12 @@ impl PackPost {
             .terrain
             .zip(world.terrain.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
+        // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
+        let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
             .programs
             .into_iter()
+            .filter(|p| !skip.split(',').any(|s| s == p.name))
             .filter_map(|p| build(p, None))
             .collect();
         if let Some(t) = &terrain {
@@ -775,37 +881,34 @@ impl PackPost {
                 resource: pass.ubo.as_entire_binding(),
             }];
             for s in &pass.samplers {
-                let filter = if s.filtering {
-                    &self.linear
-                } else {
-                    &self.nearest
+                let texture = match s.source {
+                    Source::Color(i) => targets.color[i]
+                        .as_ref()
+                        .map_or(&self.dummy, |t| &t[usize::from(key & 1 << i != 0)]),
+                    Source::Depth => &targets.depth,
+                    Source::Noise => &self.noise,
+                    Source::Dummy => &self.dummy,
+                    Source::Shadow => &self.shadow.0,
+                    Source::Atlas => self.atlas.as_ref().unwrap_or(&self.dummy),
+                    Source::Lightmap => &self.lightmap,
                 };
-                let (texture, sampler) = match s.source {
-                    Source::Color(i) => (
-                        targets.color[i]
-                            .as_ref()
-                            .map_or(&self.dummy, |t| &t[usize::from(key & 1 << i != 0)]),
-                        filter,
-                    ),
-                    Source::Depth => (&targets.depth, &self.nearest),
-                    Source::Noise => (&self.noise, &self.repeat),
-                    Source::Dummy => (&self.dummy, &self.linear),
-                    Source::Shadow => (&self.shadow.0, &self.shadow.1),
-                    // Blocks look as the game draws them: nearest texels.
-                    Source::Atlas => (
-                        self.atlas.as_ref().unwrap_or(&self.dummy),
-                        &self.nearest_repeat,
-                    ),
-                    Source::Lightmap => (&self.lightmap, &self.linear),
+                let sampler = match SamplerKind::of(s.source, s.filtering) {
+                    SamplerKind::Linear => &self.linear,
+                    SamplerKind::Nearest => &self.nearest,
+                    SamplerKind::Repeat => &self.repeat,
+                    SamplerKind::NearestRepeat => &self.nearest_repeat,
+                    SamplerKind::Comparison => &self.shadow.1,
                 };
                 entries.push(wgpu::BindGroupEntry {
                     binding: s.binding,
                     resource: wgpu::BindingResource::TextureView(texture),
                 });
-                entries.push(wgpu::BindGroupEntry {
-                    binding: s.binding + 1,
-                    resource: wgpu::BindingResource::Sampler(sampler),
-                });
+                if s.sampler == s.binding + 1 {
+                    entries.push(wgpu::BindGroupEntry {
+                        binding: s.sampler,
+                        resource: wgpu::BindingResource::Sampler(sampler),
+                    });
+                }
             }
             device.create_bind_group(&wgpu::BindGroupDescriptor {
                 label: Some(&pass.name),
@@ -1130,6 +1233,31 @@ mod tests {
     use super::*;
     use wgpu::TextureFormat as T;
 
+    /// Two textures with a sampler each become two textures sharing one sampler variable.
+    #[test]
+    fn samplers_of_a_kind_share_one_variable() {
+        let mut module = naga::front::wgsl::parse_str(
+            "@group(0) @binding(1) var a: texture_2d<f32>;\n\
+             @group(0) @binding(2) var sa: sampler;\n\
+             @group(0) @binding(3) var b: texture_2d<f32>;\n\
+             @group(0) @binding(4) var sb: sampler;\n\
+             @fragment fn main() -> @location(0) vec4<f32> {\n\
+             return textureSample(a, sa, vec2(0.5)) + textureSample(b, sb, vec2(0.5));\n}\n",
+        )
+        .unwrap();
+        share_samplers(&mut module, &HashMap::from([(2, 2), (4, 2)]));
+        let info = naga::valid::Validator::new(Default::default(), Default::default())
+            .validate(&module)
+            .unwrap();
+        let used: Vec<u32> = module
+            .global_variables
+            .iter()
+            .filter(|(h, _)| !info.get_entry_point(0)[*h].is_empty())
+            .filter_map(|(_, g)| g.binding.as_ref().map(|b| b.binding))
+            .collect();
+        assert_eq!(used, [1, 2, 3]);
+    }
+
     #[test]
     fn pack_formats_map_to_renderable_ones() {
         let f = |name| texture_format(Format::parse(name).unwrap(), wgpu::Features::empty());
@@ -1142,8 +1270,9 @@ mod tests {
         assert_eq!(f("RGBA16"), T::Rgba16Float, "16-bit norm needs a feature");
         assert_eq!(f("RGBA8_SNORM"), T::Rgba16Float, "snorm is not renderable");
         assert_eq!(f("R11F_G11F_B10F"), T::Rgba16Float);
-        let all =
-            wgpu::Features::TEXTURE_FORMAT_16BIT_NORM | wgpu::Features::RG11B10UFLOAT_RENDERABLE;
+        let all = wgpu::Features::TEXTURE_FORMAT_16BIT_NORM
+            | wgpu::Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES
+            | wgpu::Features::RG11B10UFLOAT_RENDERABLE;
         let g = |name| texture_format(Format::parse(name).unwrap(), all);
         assert_eq!(g("RGBA16"), T::Rgba16Unorm);
         assert_eq!(g("R11F_G11F_B10F"), T::Rg11b10Ufloat);
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index 5a27e62a0..c7c4cfd8b 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -141,6 +141,10 @@ pub const NAMES: &[&str] = &[
     "gbufferPreviousModelView",
     "gbufferPreviousProjection",
     "atlasSize",
+    "shadowModelView",
+    "shadowModelViewInverse",
+    "shadowProjection",
+    "shadowProjectionInverse",
 ];
 
 /// Values carried from frame to frame.
@@ -226,6 +230,14 @@ impl FrameUniforms {
             ),
             None => (frame.sky.fog_color, frame.distance * 0.9, frame.distance),
         };
+        // The shadow camera (OQ-6, impl-plan.md): orthographic, `shadowDistance` (160) blocks
+        // each side, 100 blocks from the player toward the shadow light, world +z up.
+        let light = view
+            .inverse()
+            .transform_vector3(if day { sun } else { moon })
+            .normalize();
+        let shadow_view = Mat4::look_at_rh(light * 100.0, Vec3::ZERO, Vec3::Z);
+        let shadow_projection = Mat4::orthographic_rh_gl(-160.0, 160.0, -160.0, 160.0, 0.05, 256.0);
         let day_time = inputs.day_time.rem_euclid(24000) as i32;
         let world_day = inputs.day_time.div_euclid(24000);
         let seconds = (now - self.start).as_secs_f32() % 3600.0;
@@ -247,6 +259,10 @@ impl FrameUniforms {
                 "worldDay" => Value::i(&[world_day as i32]),
                 "moonPhase" => Value::i(&[world_day.rem_euclid(8) as i32]),
                 "frameCounter" => Value::i(&[self.frame as i32]),
+                "shadowModelView" => m4(shadow_view),
+                "shadowModelViewInverse" => m4(shadow_view.inverse()),
+                "shadowProjection" => m4(shadow_projection),
+                "shadowProjectionInverse" => m4(shadow_projection.inverse()),
                 "atlasSize" => Value::i(&[self.atlas[0] as i32, self.atlas[1] as i32]),
                 "frameTime" => Value::f(&[dt]),
                 "frameTimeCounter" => Value::f(&[seconds]),

From 3e2c30a852452a3ee0a4cf778d85aee55b98c205 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:47:14 +0100
Subject: [PATCH 016/270] Shader packs, clean room 18: translucent terrain
 drawn by the pack

With a pack whose gbuffers_water (or a fallback down gbuffers_terrain's
chain) loads, translucent terrain (water, stained glass) is drawn by it
after the deferred programs and before the composites, in place, sorted
back to front as the game sorts it, and Horizon's own translucent
terrain draw is skipped.

- blend.<program> (off, or four GL factors); translucent terrain
  defaults to SRC_ALPHA ONE_MINUS_SRC_ALPHA ONE ONE_MINUS_SRC_ALPHA, and
  only blendable buffer formats blend.
- depthtex1/depthtex2: depth without translucent terrain, a copy taken
  just before it when a later program reads them (before it, depthtex0
  itself). The hand is drawn after the pack, so depthtex2 = depthtex1.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
sections 2.1, 2.3, 3.2 (blend), 6.2 (depthtex1/2); no other loader's
code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs           |  26 ++-
 crates/horizon-client/src/gfx/pack_post.rs | 213 +++++++++++++++++----
 crates/horizon-shaders/src/lib.rs          |   4 +-
 crates/horizon-shaders/src/post.rs         | 130 ++++++++++++-
 crates/horizon-shaders/tests/real_packs.rs |   3 +-
 5 files changed, 327 insertions(+), 49 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index a33d54fa3..9a7356d6e 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -3709,6 +3709,12 @@ impl Renderer {
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
         // The pack's program reads the vertices this frame's draws bind.
         let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
+        let pack_draws_water = pack_draws_terrain
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_water());
         let scaled = self.world_post.prepare(
             &self.device,
             [self.config.width, self.config.height],
@@ -3940,6 +3946,8 @@ impl Renderer {
                 pass.draw(0..4, debug_depth..debug_depth + debug_top);
             }
             match self.flat.as_ref().filter(|_| flat_frame) {
+                // The pack draws translucent terrain after its deferred programs.
+                _ if pack_draws_water => {}
                 Some(flat) => {
                     pass.set_pipeline(&flat.translucent);
                     flat.draw(&mut pass, &flat.calls[flat.solid_calls..], |p| {
@@ -4016,20 +4024,28 @@ impl Renderer {
         {
             let size = self.world_post.size().unwrap_or([1, 1]);
             let flat = self.flat.as_ref().filter(|_| flat_frame);
-            let mut terrain = |rp: &mut wgpu::RenderPass<'_>| {
+            let mut terrain = |rp: &mut wgpu::RenderPass<'_>, translucent: bool| {
                 if !pack_draws_terrain {
                     return;
                 }
                 match flat {
                     Some(flat) => {
-                        flat.draw(rp, &flat.calls[..flat.solid_calls], |p| {
-                            self.arena.buffer(p)
-                        });
+                        let calls = if translucent {
+                            &flat.calls[flat.solid_calls..]
+                        } else {
+                            &flat.calls[..flat.solid_calls]
+                        };
+                        flat.draw(rp, calls, |p| self.arena.buffer(p));
                     }
                     None => {
                         rp.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
                         rp.set_vertex_buffer(1, self.instances.slice(..));
-                        self.draw_sections(rp, &self.indirect, 0, 0, solid_draws);
+                        let (first, count) = if translucent {
+                            (solid_draws, translucent_draws)
+                        } else {
+                            (0, solid_draws)
+                        };
+                        self.draw_sections(rp, &self.indirect, 0, first, count);
                     }
                 }
             };
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 0201c7976..b96da2599 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -24,6 +24,8 @@ const BUFFERS: usize = horizon_shaders::BUFFERS;
 enum Source {
     Color(usize),
     Depth,
+    /// `depthtex1`/`depthtex2`: depth without translucent terrain (a copy taken before it).
+    Depth1,
     Noise,
     /// A 1×1 stand-in for names this slice does not provide yet (custom textures...).
     Dummy,
@@ -58,7 +60,7 @@ impl SamplerKind {
     fn of(source: Source, filtering: bool) -> Self {
         match source {
             Source::Color(_) | Source::Dummy if !filtering => Self::Nearest,
-            Source::Depth => Self::Nearest,
+            Source::Depth | Source::Depth1 => Self::Nearest,
             Source::Noise => Self::Repeat,
             Source::Shadow => Self::Comparison,
             // Blocks look as the game draws them: nearest texels.
@@ -143,6 +145,9 @@ struct Targets {
     /// A and B of each buffer used.
     color: [Option<[wgpu::TextureView; 2]>; BUFFERS],
     depth: wgpu::TextureView,
+    depth_texture: wgpu::Texture,
+    /// `depthtex1`, when a program after translucent terrain reads it.
+    depth1: Option<(wgpu::Texture, wgpu::TextureView)>,
 }
 
 /// What a pack's gbuffers programs read and draw from the game's world.
@@ -159,6 +164,10 @@ pub struct PackPost {
     passes: Vec<Pass>,
     /// What draws terrain (`gbuffers_terrain` or its fallback), between `prepare` and `deferred`.
     terrain: Option<Pass>,
+    /// What draws translucent terrain (`gbuffers_water` or its fallback), after `deferred`.
+    water: Option<Pass>,
+    /// A program after translucent terrain reads `depthtex1`: it is copied before water.
+    depth1: bool,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
     custom: horizon_shaders::Custom,
     atlas: Option<wgpu::TextureView>,
@@ -231,7 +240,9 @@ fn texture_format(f: Format, features: wgpu::Features) -> wgpu::TextureFormat {
 
 fn source(name: &str) -> Source {
     match name {
-        "depthtex0" | "gdepthtex" | "depthtex1" | "depthtex2" => Source::Depth,
+        "depthtex0" | "gdepthtex" => Source::Depth,
+        // The hand is drawn after the pack, so `depthtex2` (without it) is `depthtex1`.
+        "depthtex1" | "depthtex2" => Source::Depth1,
         "noisetex" => Source::Noise,
         "texture" | "gtexture" | "tex" => Source::Atlas,
         "lightmap" => Source::Lightmap,
@@ -392,6 +403,34 @@ fn texture_entry(binding: u32, sample_type: wgpu::TextureSampleType) -> wgpu::Bi
     )
 }
 
+/// `blend.<program>`'s factors as wgpu's, adding both terms.
+fn blend_state(b: horizon_shaders::Blend) -> wgpu::BlendState {
+    use horizon_shaders::Factor as F;
+    use wgpu::BlendFactor as W;
+    let f = |f| match f {
+        F::Zero => W::Zero,
+        F::One => W::One,
+        F::SrcColor => W::Src,
+        F::OneMinusSrcColor => W::OneMinusSrc,
+        F::DstColor => W::Dst,
+        F::OneMinusDstColor => W::OneMinusDst,
+        F::SrcAlpha => W::SrcAlpha,
+        F::OneMinusSrcAlpha => W::OneMinusSrcAlpha,
+        F::DstAlpha => W::DstAlpha,
+        F::OneMinusDstAlpha => W::OneMinusDstAlpha,
+        F::SrcAlphaSaturate => W::SrcAlphaSaturated,
+    };
+    let component = |src, dst| wgpu::BlendComponent {
+        src_factor: f(src),
+        dst_factor: f(dst),
+        operation: wgpu::BlendOperation::Add,
+    };
+    wgpu::BlendState {
+        color: component(b[0], b[1]),
+        alpha: component(b[2], b[3]),
+    }
+}
+
 fn target(format: wgpu::TextureFormat) -> Option<wgpu::ColorTargetState> {
     Some(wgpu::ColorTargetState {
         format,
@@ -462,6 +501,8 @@ fn build_pass(
         let blank = match src {
             Source::Atlas => geometry.is_none(),
             Source::Depth => geometry.is_some(),
+            // Translucent terrain reads the copy; opaque terrain would read itself.
+            Source::Depth1 => p.group == Group::Gbuffers,
             Source::Color(n) => in_place & 1 << n != 0,
             _ => false,
         };
@@ -470,7 +511,7 @@ fn build_pass(
             Source::Color(n) => formats[n]
                 .sample_type(None, Some(features))
                 .unwrap_or(float),
-            Source::Depth => wgpu::TextureSampleType::Float { filterable: false },
+            Source::Depth | Source::Depth1 => wgpu::TextureSampleType::Float { filterable: false },
             // Unfilterable on WebGPU-level devices; the lightmap is sampled at texel centres.
             Source::Lightmap => float,
             _ => float,
@@ -534,7 +575,17 @@ fn build_pass(
                 targets[0] = target(screen);
             }
         } else if let Some(&buffer) = p.buffers.get(l) {
-            targets[l] = target(formats[buffer as usize]);
+            let format = formats[buffer as usize];
+            let mut state = target(format);
+            if let (Some(t), Some(b)) = (&mut state, p.blend)
+                && format
+                    .guaranteed_format_features(features)
+                    .flags
+                    .contains(wgpu::TextureFormatFeatureFlags::BLENDABLE)
+            {
+                t.blend = Some(blend_state(b));
+            }
+            targets[l] = state;
             writes.push((location, buffer as usize));
         }
     }
@@ -693,6 +744,10 @@ impl PackPost {
             .terrain
             .zip(world.terrain.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
+        let water = post
+            .water
+            .zip(world.terrain.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)));
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
@@ -704,25 +759,43 @@ impl PackPost {
         if let Some(t) = &terrain {
             notes.push(format!("terrain draws with {}", t.name));
         }
+        if let Some(w) = &water {
+            notes.push(format!("translucent terrain draws with {}", w.name));
+        }
+        let depth1 = water.is_some()
+            && passes
+                .iter()
+                .filter(|p| matches!(p.group, Group::Composite | Group::Final))
+                .chain(&water)
+                .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth1));
         // A clear only matters when a program reads the buffer before one writes all of it
         // (composite passes cover their whole target, terrain does not); the others are skipped.
         let mut cleared = Vec::new();
         for b in 1..BUFFERS {
             let bit = 1u16 << b;
             let touched = |p: &&Pass| (p.reads | p.flip | p.written) & bit != 0;
-            let first = terrain.iter().find(touched).map(|_| true).or_else(|| {
-                let p = passes.iter().find(touched)?;
-                Some(p.reads & bit != 0 || p.written & bit == 0)
-            });
+            // Gbuffers passes cover part of their targets: a clear is needed if they touch it.
+            let first = terrain
+                .iter()
+                .chain(&water)
+                .find(touched)
+                .map(|_| true)
+                .or_else(|| {
+                    let p = passes.iter().find(touched)?;
+                    Some(p.reads & bit != 0 || p.written & bit == 0)
+                });
             if clears[b].is_some() && first == Some(true) {
                 cleared.push(b);
             }
         }
         // Terrain tests against the world's depth (entities...), so the blit copies it then.
         let blit_depth = terrain.is_some()
-            || passes
-                .iter()
-                .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth));
+            || water.is_some()
+            || passes.iter().any(|p| {
+                p.samplers
+                    .iter()
+                    .any(|s| matches!(s.source, Source::Depth | Source::Depth1))
+            });
         let room = 8 - 1;
         let other_clears = cleared.split_off(room.min(cleared.len()));
         let float = wgpu::TextureSampleType::Float { filterable: true };
@@ -778,6 +851,8 @@ impl PackPost {
             notes,
             passes,
             terrain,
+            water,
+            depth1,
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
             lightmap: world.lightmap,
@@ -886,6 +961,18 @@ impl PackPost {
                         .as_ref()
                         .map_or(&self.dummy, |t| &t[usize::from(key & 1 << i != 0)]),
                     Source::Depth => &targets.depth,
+                    // Before translucent terrain the two are the same.
+                    Source::Depth1 => match &targets.depth1 {
+                        Some(d)
+                            if matches!(
+                                pass.group,
+                                Group::Composite | Group::Final | Group::Translucent
+                            ) =>
+                        {
+                            &d.1
+                        }
+                        _ => &targets.depth,
+                    },
                     Source::Noise => &self.noise,
                     Source::Dummy => &self.dummy,
                     Source::Shadow => &self.shadow.0,
@@ -919,19 +1006,36 @@ impl PackPost {
         group.clone()
     }
 
-    /// Terrain with the pack's program into the buffers it writes, in place, tested against
-    /// the world's depth; `draw` issues the game's draws.
+    /// Terrain (or, `translucent`, translucent terrain) with the pack's program into the
+    /// buffers it writes, in place, tested against the world's depth; `draw` issues the
+    /// game's draws.
     fn draw_terrain(
         &mut self,
         device: &wgpu::Device,
         queue: &wgpu::Queue,
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
-        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>),
+        translucent: bool,
+        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
     ) {
-        let Some(mut pass) = self.terrain.take() else {
+        let slot = if translucent {
+            &mut self.water
+        } else {
+            &mut self.terrain
+        };
+        let Some(mut pass) = slot.take() else {
             return;
         };
+        if translucent
+            && let Some(t) = &self.targets
+            && let Some((copy, _)) = &t.depth1
+        {
+            encoder.copy_texture_to_texture(
+                t.depth_texture.as_image_copy(),
+                copy.as_image_copy(),
+                t.depth_texture.size(),
+            );
+        }
         let group = self.bind(device, queue, &mut pass, size);
         let targets = self.targets.as_ref().expect("resized");
         let load = wgpu::Operations {
@@ -964,9 +1068,13 @@ impl PackPost {
             });
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
-            draw(&mut rp);
+            draw(&mut rp, translucent);
+        }
+        if translucent {
+            self.water = Some(pass);
+        } else {
+            self.terrain = Some(pass);
         }
-        self.terrain = Some(pass);
     }
 
     /// Whether the pack draws terrain itself.
@@ -974,6 +1082,11 @@ impl PackPost {
         self.terrain.is_some()
     }
 
+    /// Whether the pack draws translucent terrain itself.
+    pub fn has_water(&self) -> bool {
+        self.water.is_some()
+    }
+
     /// The names of the programs that run, in order.
     pub fn programs(&self) -> Vec<&str> {
         self.passes.iter().map(|p| p.name.as_str()).collect()
@@ -983,23 +1096,24 @@ impl PackPost {
         if self.targets.as_ref().is_some_and(|t| t.size == size) {
             return;
         }
+        let texture = |label: &str, format, usage| {
+            device.create_texture(&wgpu::TextureDescriptor {
+                label: Some(label),
+                size: wgpu::Extent3d {
+                    width: size[0],
+                    height: size[1],
+                    depth_or_array_layers: 1,
+                },
+                mip_level_count: 1,
+                sample_count: 1,
+                dimension: wgpu::TextureDimension::D2,
+                format,
+                usage: usage | wgpu::TextureUsages::TEXTURE_BINDING,
+                view_formats: &[],
+            })
+        };
         let make = |label: &str, format| {
-            device
-                .create_texture(&wgpu::TextureDescriptor {
-                    label: Some(label),
-                    size: wgpu::Extent3d {
-                        width: size[0],
-                        height: size[1],
-                        depth_or_array_layers: 1,
-                    },
-                    mip_level_count: 1,
-                    sample_count: 1,
-                    dimension: wgpu::TextureDimension::D2,
-                    format,
-                    usage: wgpu::TextureUsages::RENDER_ATTACHMENT
-                        | wgpu::TextureUsages::TEXTURE_BINDING,
-                    view_formats: &[],
-                })
+            texture(label, format, wgpu::TextureUsages::RENDER_ATTACHMENT)
                 .create_view(&Default::default())
         };
         let color = std::array::from_fn(|i| {
@@ -1008,12 +1122,26 @@ impl PackPost {
                 [make(&label, self.formats[i]), make(&label, self.formats[i])]
             })
         });
+        let depth32 = wgpu::TextureFormat::Depth32Float;
+        let depth_texture = texture(
+            "depthtex0",
+            depth32,
+            wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
+        );
+        let depth1 = self.depth1.then(|| {
+            let t = texture("depthtex1", depth32, wgpu::TextureUsages::COPY_DST);
+            let view = t.create_view(&Default::default());
+            (t, view)
+        });
         self.targets = Some(Targets {
             size,
             color,
-            depth: make("depthtex0", wgpu::TextureFormat::Depth32Float),
+            depth: depth_texture.create_view(&Default::default()),
+            depth_texture,
+            depth1,
         });
-        for pass in self.passes.iter_mut().chain(&mut self.terrain) {
+        let gbuffers = self.terrain.iter_mut().chain(&mut self.water);
+        for pass in self.passes.iter_mut().chain(gbuffers) {
             pass.groups.clear();
         }
     }
@@ -1033,7 +1161,7 @@ impl PackPost {
         inputs: &PackInputs,
         size: [u32; 2],
         window: [u32; 2],
-        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>),
+        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
     ) {
         self.resize(device, size);
         self.uniforms.update(frame, inputs, size);
@@ -1143,10 +1271,15 @@ impl PackPost {
         let mut seen = (false, false);
         let mut shown = false;
         let mut terrain_drawn = self.terrain.is_none();
+        let mut water_drawn = self.water.is_none();
         for pass in &mut passes {
             if !terrain_drawn && pass.group != Group::Prepare {
                 terrain_drawn = true;
-                self.draw_terrain(device, queue, encoder, size, terrain);
+                self.draw_terrain(device, queue, encoder, size, false, terrain);
+            }
+            if !water_drawn && matches!(pass.group, Group::Composite | Group::Final) {
+                water_drawn = true;
+                self.draw_terrain(device, queue, encoder, size, true, terrain);
             }
             if pass.group == Group::Deferred && !seen.0 {
                 seen.0 = true;
@@ -1191,7 +1324,10 @@ impl PackPost {
         }
         self.passes = passes;
         if !terrain_drawn {
-            self.draw_terrain(device, queue, encoder, size, terrain);
+            self.draw_terrain(device, queue, encoder, size, false, terrain);
+        }
+        if !water_drawn {
+            self.draw_terrain(device, queue, encoder, size, true, terrain);
         }
         let targets = self.targets.as_ref().expect("resized");
         let view = |m: u16, i: usize, alt: bool| {
@@ -1282,6 +1418,7 @@ mod tests {
     fn sampler_names() {
         assert!(source("gaux1") == Source::Color(4));
         assert!(source("gdepthtex") == Source::Depth);
+        assert!(source("depthtex2") == Source::Depth1);
         assert!(source("noisetex") == Source::Noise);
         assert!(source("shadowcolor0") == Source::Dummy);
     }
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index 47cbcca11..f5819d435 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -33,7 +33,9 @@ pub use lang::Lang;
 pub use macros::{MC_VERSION, Macros, RENDER_STAGES};
 pub use options::switches_on;
 pub use pack::{Pack, PackError};
-pub use post::{Group, Post, PostProgram, dimension_folder, load_post};
+pub use post::{
+    Blend, Factor, Group, Post, PostProgram, TRANSLUCENT_BLEND, dimension_folder, load_post,
+};
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
 pub use translate::{
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index d6142c70a..e50eb4797 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -24,10 +24,67 @@ pub enum Group {
     Deferred,
     Composite,
     Final,
-    /// A gbuffers program: the game draws its geometry with it.
+    /// A gbuffers program: the game draws its geometry with it, before deferred.
     Gbuffers,
+    /// A gbuffers program drawing translucent geometry, after deferred (2.1).
+    Translucent,
 }
 
+/// A blend factor of `blend.<program>` (3.2), as GL names it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Factor {
+    Zero,
+    One,
+    SrcColor,
+    OneMinusSrcColor,
+    DstColor,
+    OneMinusDstColor,
+    SrcAlpha,
+    OneMinusSrcAlpha,
+    DstAlpha,
+    OneMinusDstAlpha,
+    SrcAlphaSaturate,
+}
+
+impl Factor {
+    fn parse(word: &str) -> Option<Self> {
+        Some(match word {
+            "ZERO" => Self::Zero,
+            "ONE" => Self::One,
+            "SRC_COLOR" => Self::SrcColor,
+            "ONE_MINUS_SRC_COLOR" => Self::OneMinusSrcColor,
+            "DST_COLOR" => Self::DstColor,
+            "ONE_MINUS_DST_COLOR" => Self::OneMinusDstColor,
+            "SRC_ALPHA" => Self::SrcAlpha,
+            "ONE_MINUS_SRC_ALPHA" => Self::OneMinusSrcAlpha,
+            "DST_ALPHA" => Self::DstAlpha,
+            "ONE_MINUS_DST_ALPHA" => Self::OneMinusDstAlpha,
+            "SRC_ALPHA_SATURATE" => Self::SrcAlphaSaturate,
+            _ => return None,
+        })
+    }
+}
+
+/// Source and destination factors for colour, then for alpha.
+pub type Blend = [Factor; 4];
+
+/// The default blend of translucent geometry (3.2).
+pub const TRANSLUCENT_BLEND: Blend = [
+    Factor::SrcAlpha,
+    Factor::OneMinusSrcAlpha,
+    Factor::One,
+    Factor::OneMinusSrcAlpha,
+];
+
+/// `gbuffers_water` and its fallbacks (2.3).
+const WATER: [&str; 5] = [
+    "gbuffers_water",
+    "gbuffers_terrain",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
 /// `gbuffers_terrain` and its fallbacks (2.3).
 const TERRAIN: [&str; 4] = [
     "gbuffers_terrain",
@@ -52,6 +109,8 @@ pub struct PostProgram {
     pub buffers: Vec<u32>,
     /// `flip.<name>.<buffer>`: buffers forced to flip (true) or kept (false) after this program.
     pub flips: Vec<(u32, bool)>,
+    /// How a gbuffers program's output blends into its buffers; `None` writes them.
+    pub blend: Option<Blend>,
 }
 
 pub struct Post {
@@ -63,6 +122,8 @@ pub struct Post {
     pub composite_pre: Vec<(u32, bool)>,
     /// What draws solid and cutout terrain, when the game asked for it and one loads.
     pub terrain: Option<PostProgram>,
+    /// What draws translucent terrain (water, stained glass) after deferred.
+    pub water: Option<PostProgram>,
     /// The custom uniforms of `shaders.properties` (3.4).
     pub custom: Custom,
     pub config: Config,
@@ -96,6 +157,7 @@ pub fn load_post(
         deferred_pre: flips(properties, "deferred_pre"),
         composite_pre: flips(properties, "composite_pre"),
         terrain: None,
+        water: None,
         custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
@@ -127,11 +189,24 @@ pub fn load_post(
         }
     }
     if let Some(inputs) = terrain {
-        loader.post.terrain = TERRAIN.iter().find_map(|name| {
-            loader.load(name.to_string(), Group::Gbuffers, |v, f| {
-                translate_gbuffers(v, f, Target::Buffers, inputs)
+        let mut gbuffers = |names: &[&str], group| {
+            names.iter().find_map(|name| {
+                loader.load(name.to_string(), group, |v, f| {
+                    translate_gbuffers(v, f, Target::Buffers, inputs)
+                })
             })
+        };
+        let terrain = gbuffers(&TERRAIN, Group::Gbuffers);
+        // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
+        let water = gbuffers(&WATER, Group::Translucent);
+        loader.post.terrain = terrain;
+        loader.post.water = water.map(|mut p| {
+            p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
+            p
         });
+        if let Some(p) = &mut loader.post.terrain {
+            p.blend = blend(properties, &p.name).flatten();
+        }
     }
     post.config = std::mem::take(&mut post.config).finish();
     post
@@ -211,6 +286,7 @@ impl Loader<'_> {
             group,
             program,
             buffers,
+            blend: None,
         })
     }
 }
@@ -260,6 +336,20 @@ fn enabled(
     eval_condition(&condition, macros).ok() != Some(0)
 }
 
+/// `blend.<program>`: `Some(None)` for `off`, `Some(factors)`, or `None` when absent or not
+/// four known factors.
+fn blend(properties: &Properties, program: &str) -> Option<Option<Blend>> {
+    let value = properties.get(&format!("blend.{program}"))?.trim();
+    if value == "off" {
+        return Some(None);
+    }
+    let factors: Vec<Factor> = value
+        .split_whitespace()
+        .map(Factor::parse)
+        .collect::<Option<_>>()?;
+    Some(Some(factors.try_into().ok()?))
+}
+
 /// `flip.<program>.<buffer>=<bool>` keys of one program.
 fn flips(properties: &Properties, program: &str) -> Vec<(u32, bool)> {
     let prefix = format!("flip.{program}.");
@@ -355,6 +445,38 @@ mod tests {
         assert!(post.programs.iter().any(|p| p.name == "composite3"));
     }
 
+    /// Water falls back to the terrain chain and blends by default; `blend.*` overrides.
+    #[test]
+    fn water_falls_back_to_terrain_and_blends() {
+        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/packs/terrain-test");
+        let pack = Pack::open(&dir).unwrap();
+        let macros = Macros::standard();
+        let inputs = crate::GbuffersInputs {
+            declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
+            body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n    hz_Color = vec4(1.0);\n".into(),
+            attributes: Vec::new(),
+        };
+        let post = load_post(&pack, "", &Properties::default(), &macros, Some(&inputs));
+        let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
+        assert_eq!((terrain.group, terrain.blend), (Group::Gbuffers, None));
+        assert_eq!(water.name, "gbuffers_terrain");
+        assert_eq!(
+            (water.group, water.blend),
+            (Group::Translucent, Some(TRANSLUCENT_BLEND))
+        );
+        let properties = Properties::parse(
+            "blend.gbuffers_terrain = ONE ONE ZERO ONE\nblend.gbuffers_water = off\n",
+            &macros,
+        );
+        let terrain_blend = blend(&properties, "gbuffers_terrain");
+        assert_eq!(
+            terrain_blend,
+            Some(Some([Factor::One, Factor::One, Factor::Zero, Factor::One]))
+        );
+        assert_eq!(blend(&properties, "gbuffers_water"), Some(None));
+        assert_eq!(blend(&properties, "gbuffers_basic"), None);
+    }
+
     #[test]
     fn horizons_test_pack_loads() {
         let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/packs/post-test");
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 78ba97bfb..c5d4defac 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -176,9 +176,10 @@ fn real_packs_read() {
                 Some(&terrain),
             );
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
                 post.terrain.as_ref().map(|t| &t.name),
+                post.water.as_ref().map(|t| &t.name),
                 post.notes.len() + post.config.notes.len(),
                 start.elapsed().as_secs_f64() * 1000.0
             );

From b6345fc61d640de07afc9a2f3695039e02ac3201 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:56:31 +0100
Subject: [PATCH 017/270] Shader packs, clean room 19: GPU time of each pass
 (developers' aid)

HORIZON_SHADER_PACK_TIMING=1 puts timestamps around every pass of a
shader pack, one frame in 30, and logs each pass's median every 30
timed frames. The frame after a timed one waits for the GPU before
reading them (Metal resolves timestamps without waiting for the passes
that write them). Passes overlap on tiled GPUs, so a pass is charged
from the later of its beginning and the previous pass's end.

This is what attributes a pack's cost to its own programs or to ours
when the machine is shared and FPS comparisons are noisy.

Clean-room: Horizon's own tooling, no spec section; no other loader's
code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs             |   1 +
 crates/horizon-client/src/gfx/pack_post.rs   |  11 ++
 crates/horizon-client/src/gfx/pack_timing.rs | 147 +++++++++++++++++++
 3 files changed, 159 insertions(+)
 create mode 100644 crates/horizon-client/src/gfx/pack_timing.rs

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 9a7356d6e..f0987dddd 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -70,6 +70,7 @@ mod lod;
 mod occlusion;
 mod pack_atlas;
 mod pack_post;
+mod pack_timing;
 pub mod pack_uniforms;
 mod page_runs;
 pub mod panorama;
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index b96da2599..739688784 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -168,6 +168,8 @@ pub struct PackPost {
     water: Option<Pass>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
+    /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
+    timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
     custom: horizon_shaders::Custom,
     atlas: Option<wgpu::TextureView>,
@@ -853,6 +855,7 @@ impl PackPost {
             terrain,
             water,
             depth1,
+            timing: super::pack_timing::PassTiming::new(device, queue),
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
             lightmap: world.lightmap,
@@ -1053,9 +1056,11 @@ impl PackPost {
                 .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load));
         }
         {
+            let timestamp_writes = self.timing.as_mut().and_then(|t| t.writes(&pass.name));
             let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some(&pass.name),
                 color_attachments: &attachments,
+                timestamp_writes,
                 depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                     view: &targets.depth,
                     depth_ops: Some(wgpu::Operations {
@@ -1164,6 +1169,9 @@ impl PackPost {
         terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
     ) {
         self.resize(device, size);
+        if let Some(t) = &mut self.timing {
+            t.begin(device, queue);
+        }
         self.uniforms.update(frame, inputs, size);
         self.uniforms.eval_custom(&mut self.custom);
         let Some(targets) = &self.targets else { return };
@@ -1214,6 +1222,7 @@ impl PackPost {
             encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some("Shader pack clear"),
                 color_attachments: &attachments,
+                timestamp_writes: self.timing.as_mut().and_then(|t| t.writes("clear")),
                 ..Default::default()
             });
         }
@@ -1250,6 +1259,7 @@ impl PackPost {
             let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some("Shader pack world"),
                 color_attachments: &attachments,
+                timestamp_writes: self.timing.as_mut().and_then(|t| t.writes("world")),
                 depth_stencil_attachment: self.blit_depth.then_some(
                     wgpu::RenderPassDepthStencilAttachment {
                         view: &targets.depth,
@@ -1314,6 +1324,7 @@ impl PackPost {
                 let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                     label: Some(&pass.name),
                     color_attachments: &attachments,
+                    timestamp_writes: self.timing.as_mut().and_then(|t| t.writes(&pass.name)),
                     ..Default::default()
                 });
                 rp.set_pipeline(&pass.pipeline);
diff --git a/crates/horizon-client/src/gfx/pack_timing.rs b/crates/horizon-client/src/gfx/pack_timing.rs
new file mode 100644
index 000000000..61ab721e5
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_timing.rs
@@ -0,0 +1,147 @@
+//! Developers' aid: `HORIZON_SHADER_PACK_TIMING=1` times every pass of a shader pack on the
+//! GPU, one frame in `EVERY`, and logs each pass's median every `REPORT` timed frames. The
+//! frame after a timed one waits for the GPU before reading the timestamps (Metal resolves
+//! them without waiting for the passes that write them), so timing slows the game.
+
+const EVERY: u32 = 30;
+const REPORT: usize = 30;
+/// Passes timed per frame at most (two timestamps each).
+const CAPACITY: u32 = 64;
+
+pub(super) struct PassTiming {
+    queries: wgpu::QuerySet,
+    resolve: wgpu::Buffer,
+    read: wgpu::Buffer,
+    period_ns: f32,
+    frame: u32,
+    /// The passes timed in the frame being recorded or waiting to be read, in order.
+    names: Vec<String>,
+    timed: bool,
+    samples: Vec<(String, Vec<f32>)>,
+    reports: usize,
+}
+
+impl PassTiming {
+    pub fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Option<Self> {
+        if std::env::var_os("HORIZON_SHADER_PACK_TIMING").is_none()
+            || !device.features().contains(wgpu::Features::TIMESTAMP_QUERY)
+        {
+            return None;
+        }
+        let size = u64::from(CAPACITY) * 2 * 8;
+        let buffer = |label, usage| {
+            device.create_buffer(&wgpu::BufferDescriptor {
+                label: Some(label),
+                size,
+                usage,
+                mapped_at_creation: false,
+            })
+        };
+        Some(Self {
+            queries: device.create_query_set(&wgpu::QuerySetDescriptor {
+                label: Some("Shader pack pass timing"),
+                ty: wgpu::QueryType::Timestamp,
+                count: CAPACITY * 2,
+            }),
+            resolve: buffer(
+                "Shader pack timing resolve",
+                wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC,
+            ),
+            read: buffer(
+                "Shader pack timing read",
+                wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+            ),
+            period_ns: queue.get_timestamp_period(),
+            frame: 0,
+            names: Vec::new(),
+            timed: false,
+            samples: Vec::new(),
+            reports: 0,
+        })
+    }
+
+    /// At the start of a frame: reads the last timed frame's passes, and decides whether this
+    /// one is timed.
+    pub fn begin(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
+        if self.timed && !self.names.is_empty() {
+            self.collect(device, queue);
+        }
+        self.names.clear();
+        self.frame += 1;
+        self.timed = self.frame.is_multiple_of(EVERY);
+    }
+
+    /// Timestamp writes for the pass `name`, in a timed frame.
+    pub fn writes(&mut self, name: &str) -> Option<wgpu::RenderPassTimestampWrites<'_>> {
+        let i = self.names.len() as u32;
+        if !self.timed || i >= CAPACITY {
+            return None;
+        }
+        self.names.push(name.to_owned());
+        Some(wgpu::RenderPassTimestampWrites {
+            query_set: &self.queries,
+            beginning_of_pass_write_index: Some(2 * i),
+            end_of_pass_write_index: Some(2 * i + 1),
+        })
+    }
+
+    fn collect(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
+        // The timed frame first, then the resolve, so every timestamp is written.
+        _ = device.poll(wgpu::PollType::wait_indefinitely());
+        let count = self.names.len() as u32 * 2;
+        let bytes = u64::from(count) * 8;
+        let mut encoder = device.create_command_encoder(&Default::default());
+        encoder.resolve_query_set(&self.queries, 0..count, &self.resolve, 0);
+        encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.read, 0, bytes);
+        queue.submit([encoder.finish()]);
+        let slice = self.read.slice(..bytes);
+        slice.map_async(wgpu::MapMode::Read, |_| {});
+        _ = device.poll(wgpu::PollType::wait_indefinitely());
+        let Ok(data) = slice.get_mapped_range() else {
+            return;
+        };
+        let stamps: Vec<u64> = data
+            .as_chunks::<8>()
+            .0
+            .iter()
+            .map(|b| u64::from_le_bytes(*b))
+            .collect();
+        drop(data);
+        self.read.unmap();
+        // Passes overlap on tiled GPUs (a pass begins before the one before it ends): a pass
+        // costs the time from the later of its beginning and the previous pass's end.
+        let mut previous_end = 0;
+        for (name, pair) in self.names.iter().zip(stamps.as_chunks::<2>().0) {
+            if pair[0] == 0 || pair[1] < pair[0] {
+                continue;
+            }
+            let from = pair[0].max(previous_end).min(pair[1]);
+            previous_end = pair[1];
+            let ms = (pair[1] - from) as f32 * self.period_ns / 1e6;
+            match self.samples.iter_mut().find(|s| s.0 == *name) {
+                Some(s) => s.1.push(ms),
+                None => self.samples.push((name.clone(), vec![ms])),
+            }
+        }
+        self.reports += 1;
+        if self.reports.is_multiple_of(REPORT) {
+            self.report();
+        }
+    }
+
+    fn report(&mut self) {
+        let mut total = 0.0;
+        let mut parts = Vec::new();
+        for (name, v) in &mut self.samples {
+            v.sort_by(f32::total_cmp);
+            let median = v[v.len() / 2];
+            total += median;
+            parts.push(format!("{name} {median:.3}"));
+            v.clear();
+        }
+        log::info!(
+            "shader pack GPU time per pass (median ms of {REPORT} frames): {} = {total:.3}",
+            parts.join(", ")
+        );
+    }
+}

From 1d90d72a64418071f943e404166fa39b09f50981 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 02:14:59 +0100
Subject: [PATCH 018/270] Server dialogs: the packets and the dialog model

show_dialog and clear_dialog in configuration and play, and
custom_click_action, the answer, in both. Dialog.DIRECT_CODEC as
horizon_client::dialog: the five dialog types, their bodies, inputs and
actions with vanilla's defaults, the values inputs hold, and
Action.createAction (a command template's $(key) substitution with
escapeWithoutQuotes, a custom action's payload of every input's tag).

Nothing uses them yet: the screen comes next.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/dialog.rs           | 794 ++++++++++++++++++
 crates/horizon-client/src/lib.rs              |   1 +
 .../src/packets/configuration.rs              |  52 ++
 crates/horizon-protocol/src/packets/play.rs   |  60 +-
 4 files changed, 905 insertions(+), 2 deletions(-)
 create mode 100644 crates/horizon-client/src/dialog.rs

diff --git a/crates/horizon-client/src/dialog.rs b/crates/horizon-client/src/dialog.rs
new file mode 100644
index 000000000..7acd3e86a
--- /dev/null
+++ b/crates/horizon-client/src/dialog.rs
@@ -0,0 +1,794 @@
+//! Server dialogs (`net.minecraft.server.dialog`): what `Dialog.DIRECT_CODEC`
+//! decodes from a `show_dialog` packet, the values its inputs hold, and the
+//! click event an action makes of them (`Action.createAction`).
+use crate::text::Text;
+use horizon_world::nbt::Tag;
+use serde_json::{Value, json};
+
+/// `CommonDialogData` and the type's own fields.
+#[derive(Clone, Debug)]
+pub struct Dialog {
+    pub kind: Kind,
+    pub title: Text,
+    pub external_title: Option<Text>,
+    pub can_close_with_escape: bool,
+    pub pause: bool,
+    pub after_action: AfterAction,
+    pub body: Vec<Body>,
+    pub inputs: Vec<Input>,
+}
+
+/// The dialog types (`DialogTypes`).
+#[derive(Clone, Debug)]
+pub enum Kind {
+    /// `NoticeDialog`: one button, "OK" when the server names none.
+    Notice(Button),
+    Confirmation {
+        yes: Button,
+        no: Button,
+    },
+    MultiAction {
+        actions: Vec<Button>,
+        exit: Option<Button>,
+        columns: i32,
+    },
+    ServerLinks {
+        exit: Option<Button>,
+        columns: i32,
+        button_width: i32,
+    },
+    /// `DialogListDialog`: its dialogs as sent (ids, a tag or inline dialogs).
+    DialogList {
+        dialogs: Tag,
+        exit: Option<Button>,
+        columns: i32,
+        button_width: i32,
+    },
+}
+
+/// `DialogAction`: the screen after an action runs.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AfterAction {
+    Close,
+    None,
+    WaitForResponse,
+}
+
+/// `ActionButton`: `CommonButtonData` and what it does.
+#[derive(Clone, Debug)]
+pub struct Button {
+    pub label: Text,
+    pub tooltip: Option<Text>,
+    pub width: i32,
+    pub action: Option<Action>,
+}
+
+/// `Action`: a fixed click event, or one made from the inputs' values.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Action {
+    /// `StaticAction`: a click event as it is.
+    Static(Click),
+    /// `CommandTemplate`: a command with `$(key)` replaced by input values.
+    RunCommand(String),
+    /// `CustomAll`: a custom click event whose payload is `additions` plus
+    /// every input's value under its key.
+    Custom { id: String, additions: Option<Tag> },
+}
+
+/// `ClickEvent`, the kinds a server may send (`isAllowedFromServer`).
+#[derive(Clone, Debug, PartialEq)]
+pub enum Click {
+    OpenUrl(String),
+    RunCommand(String),
+    SuggestCommand(String),
+    /// The dialog: an id of the `minecraft:dialog` registry or the dialog itself.
+    ShowDialog(Tag),
+    ChangePage(i32),
+    CopyToClipboard(String),
+    Custom {
+        id: String,
+        payload: Option<Tag>,
+    },
+}
+
+/// `DialogBody`.
+#[derive(Clone, Debug)]
+pub enum Body {
+    /// `PlainMessage`: centred text wrapped to `width`.
+    Message { contents: Text, width: i32 },
+    /// `ItemBody`: the item as `ItemStackTemplate` sent it.
+    Item {
+        item: Tag,
+        description: Option<(Text, i32)>,
+        show_decorations: bool,
+        show_tooltip: bool,
+        width: i32,
+        height: i32,
+    },
+}
+
+/// `Input`: the key its value goes by, and its control.
+#[derive(Clone, Debug)]
+pub struct Input {
+    pub key: String,
+    pub control: Control,
+}
+
+/// `InputControl`.
+#[derive(Clone, Debug)]
+pub enum Control {
+    Text {
+        width: i32,
+        label: Text,
+        label_visible: bool,
+        initial: String,
+        max_length: i32,
+        /// `MultilineOptions`: the most lines and the height, when set.
+        multiline: Option<(Option<i32>, Option<i32>)>,
+    },
+    Boolean {
+        label: Text,
+        initial: bool,
+        on_true: String,
+        on_false: String,
+    },
+    SingleOption {
+        width: i32,
+        /// Each option's id, its label and whether it is the initial one.
+        options: Vec<(String, Option<Text>, bool)>,
+        label: Text,
+        label_visible: bool,
+    },
+    NumberRange {
+        width: i32,
+        label: Text,
+        label_format: String,
+        start: f32,
+        end: f32,
+        initial: Option<f32>,
+        step: Option<f32>,
+    },
+}
+
+/// What an input holds while the dialog is open.
+#[derive(Clone, Debug, PartialEq)]
+pub enum InputValue {
+    Text(String),
+    Bool(bool),
+    /// The chosen option's index.
+    Option(usize),
+    /// The slider's position, 0 to 1.
+    Slider(f32),
+}
+
+fn text(t: &Tag) -> Text {
+    crate::scoreboard::comp_text(&crate::scoreboard::tag_to_json(t))
+}
+fn string(t: Option<&Tag>) -> Option<String> {
+    match t? {
+        Tag::String(s) => Some(s.to_string_lossy()),
+        _ => None,
+    }
+}
+fn number(t: Option<&Tag>) -> Option<f64> {
+    Some(match t? {
+        Tag::Byte(v) => f64::from(*v),
+        Tag::Short(v) => f64::from(*v),
+        Tag::Int(v) => f64::from(*v),
+        Tag::Long(v) => *v as f64,
+        Tag::Float(v) => f64::from(f32::from_bits(*v)),
+        Tag::Double(v) => f64::from_bits(*v),
+        _ => return None,
+    })
+}
+fn int(t: &Tag, key: &str, default: i32) -> i32 {
+    number(t.get(key)).map_or(default, |v| v as i32)
+}
+fn boolean(t: &Tag, key: &str, default: bool) -> bool {
+    number(t.get(key)).map_or(default, |v| v != 0.0)
+}
+fn list(t: Option<&Tag>) -> &[Tag] {
+    match t {
+        Some(Tag::List(items)) => items,
+        _ => &[],
+    }
+}
+/// A registry name without its default namespace.
+fn path(id: &str) -> &str {
+    id.strip_prefix("minecraft:").unwrap_or(id)
+}
+
+impl Button {
+    /// `ActionButton.CODEC`.
+    fn parse(t: &Tag) -> Option<Self> {
+        Some(Self {
+            label: text(t.get("label")?),
+            tooltip: t.get("tooltip").map(text),
+            width: int(t, "width", 150),
+            action: t.get("action").and_then(Action::parse),
+        })
+    }
+    /// `NoticeDialog.DEFAULT_ACTION`.
+    fn ok() -> Self {
+        Self {
+            label: Text::translate("gui.ok", &[]),
+            tooltip: None,
+            width: 150,
+            action: None,
+        }
+    }
+}
+
+impl Click {
+    /// `ClickEvent.CODEC`, from its `action` (a click event in a component)
+    /// or `type` (an action) field.
+    pub fn parse(t: &Tag, kind: &str) -> Option<Self> {
+        let s = |key| string(t.get(key));
+        Some(match path(kind) {
+            "open_url" => Self::OpenUrl(s("url")?),
+            "run_command" => Self::RunCommand(s("command")?),
+            "suggest_command" => Self::SuggestCommand(s("command")?),
+            "show_dialog" => Self::ShowDialog(t.get("dialog")?.clone()),
+            "change_page" => Self::ChangePage(int(t, "page", 1)),
+            "copy_to_clipboard" => Self::CopyToClipboard(s("value")?),
+            "custom" => Self::Custom {
+                id: s("id")?,
+                payload: t.get("payload").cloned(),
+            },
+            _ => return None,
+        })
+    }
+}
+
+impl Action {
+    /// `Action.CODEC`, dispatched on `type`.
+    fn parse(t: &Tag) -> Option<Self> {
+        let kind = string(t.get("type"))?;
+        Some(match path(&kind) {
+            "dynamic/run_command" => Self::RunCommand(string(t.get("template"))?),
+            "dynamic/custom" => Self::Custom {
+                id: string(t.get("id"))?,
+                additions: t.get("additions").cloned(),
+            },
+            other => Self::Static(Click::parse(t, other)?),
+        })
+    }
+    /// `createAction`: the click event, given each input's key, control and value.
+    pub fn click(&self, inputs: &[Input], values: &[InputValue]) -> Option<Click> {
+        let values = || inputs.iter().zip(values);
+        Some(match self {
+            Self::Static(click) => click.clone(),
+            Self::RunCommand(template) => Click::RunCommand(substitute(template, &|key| {
+                values()
+                    .find(|(i, _)| i.key == key)
+                    .map(|(i, v)| i.control.substitution(v))
+            })),
+            Self::Custom { id, additions } => {
+                let mut tag = match additions {
+                    Some(t @ Tag::Compound(_)) => t.clone(),
+                    _ => Tag::Compound(Default::default()),
+                };
+                for (input, value) in values() {
+                    if let Tag::Compound(map) = &mut tag {
+                        map.insert(input.key.as_str().into(), input.control.tag(value));
+                    }
+                }
+                Click::Custom {
+                    id: id.clone(),
+                    payload: Some(tag),
+                }
+            }
+        })
+    }
+}
+
+/// `ParsedTemplate.instantiate`: each `$(key)` replaced by its value, or by
+/// nothing for a key no input has.
+fn substitute(template: &str, value: &dyn Fn(&str) -> Option<String>) -> String {
+    let mut out = String::new();
+    let mut rest = template;
+    while let Some(at) = rest.find("$(") {
+        let Some(end) = rest[at..].find(')') else {
+            break;
+        };
+        out.push_str(&rest[..at]);
+        out.push_str(&value(&rest[at + 2..at + end]).unwrap_or_default());
+        rest = &rest[at + end + 1..];
+    }
+    out.push_str(rest);
+    out
+}
+
+/// `StringTag.escapeWithoutQuotes`.
+fn escape(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for c in s.chars() {
+        match c {
+            '"' | '\'' | '\\' => {
+                out.push('\\');
+                out.push(c);
+            }
+            '\u{8}' => out.push_str("\\b"),
+            '\t' => out.push_str("\\t"),
+            '\n' => out.push_str("\\n"),
+            '\u{c}' => out.push_str("\\f"),
+            '\r' => out.push_str("\\r"),
+            c if c < ' ' => out.push_str(&format!("\\x{:02x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out
+}
+
+impl Control {
+    /// `InputControl.MAP_CODEC`, dispatched on `type`.
+    fn parse(t: &Tag) -> Option<Self> {
+        let label = || t.get("label").map(text);
+        Some(match path(&string(t.get("type"))?) {
+            "text" => Self::Text {
+                width: int(t, "width", 200),
+                label: label()?,
+                label_visible: boolean(t, "label_visible", true),
+                initial: string(t.get("initial")).unwrap_or_default(),
+                max_length: int(t, "max_length", 32),
+                multiline: t.get("multiline").map(|m| {
+                    let get = |key| number(m.get(key)).map(|v| v as i32);
+                    (get("max_lines"), get("height"))
+                }),
+            },
+            "boolean" => Self::Boolean {
+                label: label()?,
+                initial: boolean(t, "initial", false),
+                on_true: string(t.get("on_true")).unwrap_or_else(|| "true".into()),
+                on_false: string(t.get("on_false")).unwrap_or_else(|| "false".into()),
+            },
+            "single_option" => Self::SingleOption {
+                width: int(t, "width", 200),
+                // SingleOptionInput.Entry.CODEC: a full entry or just its id.
+                options: list(t.get("options"))
+                    .iter()
+                    .filter_map(|o| match o {
+                        Tag::String(id) => Some((id.to_string_lossy(), None, false)),
+                        o => Some((
+                            string(o.get("id"))?,
+                            o.get("display").map(text),
+                            boolean(o, "initial", false),
+                        )),
+                    })
+                    .collect(),
+                label: label()?,
+                label_visible: boolean(t, "label_visible", true),
+            },
+            "number_range" => {
+                let float = |key| number(t.get(key)).map(|v| v as f32);
+                Self::NumberRange {
+                    width: int(t, "width", 200),
+                    label: label()?,
+                    label_format: string(t.get("label_format"))
+                        .unwrap_or_else(|| "options.generic_value".into()),
+                    start: float("start")?,
+                    end: float("end")?,
+                    initial: float("initial"),
+                    step: float("step"),
+                }
+            }
+            _ => return None,
+        })
+    }
+    /// The value it starts with.
+    pub fn initial(&self) -> InputValue {
+        match self {
+            Self::Text { initial, .. } => InputValue::Text(initial.clone()),
+            Self::Boolean { initial, .. } => InputValue::Bool(*initial),
+            Self::SingleOption { options, .. } => {
+                InputValue::Option(options.iter().position(|o| o.2).unwrap_or(0))
+            }
+            Self::NumberRange {
+                start,
+                end,
+                initial,
+                ..
+            } => InputValue::Slider(to_slider(
+                initial.unwrap_or((start + end) / 2.0),
+                *start,
+                *end,
+            )),
+        }
+    }
+    /// `ValueGetter.asTemplateSubstitution`.
+    pub fn substitution(&self, value: &InputValue) -> String {
+        match (self, value) {
+            (Self::Text { .. }, InputValue::Text(s)) => escape(s),
+            (
+                Self::Boolean {
+                    on_true, on_false, ..
+                },
+                InputValue::Bool(b),
+            ) => if *b { on_true } else { on_false }.clone(),
+            (Self::SingleOption { options, .. }, InputValue::Option(i)) => {
+                options.get(*i).map(|o| o.0.clone()).unwrap_or_default()
+            }
+            (Self::NumberRange { .. }, InputValue::Slider(_)) => {
+                number_string(self.scaled(value).unwrap_or(0.0))
+            }
+            _ => String::new(),
+        }
+    }
+    /// `ValueGetter.asTag`.
+    pub fn tag(&self, value: &InputValue) -> Tag {
+        match (self, value) {
+            (Self::Boolean { .. }, InputValue::Bool(b)) => Tag::Byte(i8::from(*b)),
+            (Self::NumberRange { .. }, _) => {
+                Tag::Float(self.scaled(value).unwrap_or(0.0).to_bits())
+            }
+            (Self::Text { .. }, InputValue::Text(s)) => Tag::String(s.as_str().into()),
+            _ => Tag::String(self.substitution(value).as_str().into()),
+        }
+    }
+    /// `RangeInfo.computeScaledValue`: a number range's value at its slider position.
+    pub fn scaled(&self, value: &InputValue) -> Option<f32> {
+        let (
+            Self::NumberRange {
+                start,
+                end,
+                initial,
+                step,
+                ..
+            },
+            InputValue::Slider(slider),
+        ) = (self, value)
+        else {
+            return None;
+        };
+        let (start, end) = (*start, *end);
+        let in_range = start + slider * (end - start);
+        let Some(step) = step else {
+            return Some(in_range);
+        };
+        let first = initial.unwrap_or((start + end) / 2.0);
+        // Math.round: half up.
+        let steps = ((in_range - first) / step + 0.5).floor() as i32;
+        let result = first + steps as f32 * step;
+        let position = to_slider(result, start, end);
+        if (0.0..=1.0).contains(&position) {
+            return Some(result);
+        }
+        Some(first + (steps - steps.signum()) as f32 * step)
+    }
+}
+
+/// `RangeInfo.scaledValueToSlider`.
+fn to_slider(value: f32, start: f32, end: f32) -> f32 {
+    if start == end {
+        0.5
+    } else {
+        (value - start) / (end - start)
+    }
+}
+
+/// `SliderImpl.valueToString`: whole numbers without a fraction, the rest as
+/// Java's `Float.toString`.
+pub fn number_string(v: f32) -> String {
+    if v == (v as i32) as f32 {
+        (v as i32).to_string()
+    } else {
+        crate::snbt::java_float(v)
+    }
+}
+
+impl Body {
+    /// `DialogBody.DIALOG_BODY_CODEC`.
+    fn parse(t: &Tag) -> Option<Self> {
+        let message = |t: &Tag| -> Option<(Text, i32)> {
+            // PlainMessage.CODEC: the full form or just its contents.
+            match t {
+                Tag::Compound(_) if t.get("contents").is_some() => {
+                    Some((text(t.get("contents")?), int(t, "width", 200)))
+                }
+                t => Some((text(t), 200)),
+            }
+        };
+        Some(match path(&string(t.get("type"))?) {
+            "plain_message" => {
+                let (contents, width) = message(t)?;
+                Self::Message { contents, width }
+            }
+            "item" => Self::Item {
+                item: t.get("item")?.clone(),
+                description: t.get("description").and_then(message),
+                show_decorations: boolean(t, "show_decorations", true),
+                show_tooltip: boolean(t, "show_tooltip", true),
+                width: int(t, "width", 16),
+                height: int(t, "height", 16),
+            },
+            _ => return None,
+        })
+    }
+}
+
+impl Dialog {
+    /// `Dialog.DIRECT_CODEC`; `None` for a type or field it can't read
+    /// (vanilla fails the whole packet then).
+    pub fn parse(t: &Tag) -> Option<Self> {
+        let button = |key: &str| t.get(key).and_then(Button::parse);
+        let kind = match path(&string(t.get("type"))?) {
+            "notice" => Kind::Notice(match t.get("action") {
+                Some(b) => Button::parse(b)?,
+                None => Button::ok(),
+            }),
+            "confirmation" => Kind::Confirmation {
+                yes: button("yes")?,
+                no: button("no")?,
+            },
+            "multi_action" => Kind::MultiAction {
+                actions: list(t.get("actions"))
+                    .iter()
+                    .map(Button::parse)
+                    .collect::<Option<Vec<_>>>()
+                    .filter(|a| !a.is_empty())?,
+                exit: button("exit_action"),
+                columns: int(t, "columns", 2),
+            },
+            "server_links" => Kind::ServerLinks {
+                exit: button("exit_action"),
+                columns: int(t, "columns", 2),
+                button_width: int(t, "button_width", 150),
+            },
+            "dialog_list" => Kind::DialogList {
+                dialogs: t.get("dialogs")?.clone(),
+                exit: button("exit_action"),
+                columns: int(t, "columns", 2),
+                button_width: int(t, "button_width", 150),
+            },
+            _ => return None,
+        };
+        // DialogBody.COMPACT_LIST_CODEC: one body, or a list of them.
+        let body = match t.get("body") {
+            Some(Tag::List(items)) => items.iter().filter_map(Body::parse).collect(),
+            Some(one) => Body::parse(one).into_iter().collect(),
+            None => Vec::new(),
+        };
+        let inputs = list(t.get("inputs"))
+            .iter()
+            .filter_map(|i| {
+                Some(Input {
+                    key: string(i.get("key"))?,
+                    control: Control::parse(i)?,
+                })
+            })
+            .collect();
+        Some(Self {
+            kind,
+            title: text(t.get("title")?),
+            external_title: t.get("external_title").map(text),
+            can_close_with_escape: boolean(t, "can_close_with_escape", true),
+            pause: boolean(t, "pause", true),
+            after_action: match string(t.get("after_action")).as_deref() {
+                Some("none") => AfterAction::None,
+                Some("wait_for_response") => AfterAction::WaitForResponse,
+                _ => AfterAction::Close,
+            },
+            body,
+            inputs,
+        })
+    }
+    /// `onCancel`: what Escape (or closing it) does.
+    pub fn on_cancel(&self) -> Option<&Action> {
+        match &self.kind {
+            Kind::Notice(b) => b.action.as_ref(),
+            Kind::Confirmation { no, .. } => no.action.as_ref(),
+            Kind::MultiAction { exit, .. }
+            | Kind::ServerLinks { exit, .. }
+            | Kind::DialogList { exit, .. } => exit.as_ref().and_then(|b| b.action.as_ref()),
+        }
+    }
+    /// The buttons it draws, in order: the list, then the footer's.
+    pub fn buttons(&self) -> Vec<&Button> {
+        match &self.kind {
+            Kind::Notice(b) => vec![b],
+            Kind::Confirmation { yes, no } => vec![yes, no],
+            Kind::MultiAction { actions, exit, .. } => actions.iter().chain(exit).collect(),
+            Kind::ServerLinks { exit, .. } | Kind::DialogList { exit, .. } => exit.iter().collect(),
+        }
+    }
+    /// What `status` reports of it.
+    pub fn json(&self, values: &[InputValue]) -> Value {
+        let kind = match &self.kind {
+            Kind::Notice(_) => "notice",
+            Kind::Confirmation { .. } => "confirmation",
+            Kind::MultiAction { .. } => "multi_action",
+            Kind::ServerLinks { .. } => "server_links",
+            Kind::DialogList { .. } => "dialog_list",
+        };
+        let inputs: Vec<Value> = self
+            .inputs
+            .iter()
+            .zip(values)
+            .map(|(i, v)| {
+                let kind = match i.control {
+                    Control::Text { .. } => "text",
+                    Control::Boolean { .. } => "boolean",
+                    Control::SingleOption { .. } => "single_option",
+                    Control::NumberRange { .. } => "number_range",
+                };
+                json!({"key": i.key, "type": kind, "value": i.control.substitution(v)})
+            })
+            .collect();
+        json!({
+            "type": kind,
+            "title": self.title.plain(),
+            "body": self.body.iter().map(|b| match b {
+                Body::Message { contents, .. } => contents.plain(),
+                Body::Item { item, .. } => string(item.get("id")).unwrap_or_default(),
+            }).collect::<Vec<_>>(),
+            "inputs": inputs,
+            "buttons": self.buttons().iter().map(|b| b.label.plain()).collect::<Vec<_>>(),
+            "can_close_with_escape": self.can_close_with_escape,
+            "after_action": match self.after_action {
+                AfterAction::Close => "close",
+                AfterAction::None => "none",
+                AfterAction::WaitForResponse => "wait_for_response",
+            },
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn s(v: &str) -> Tag {
+        Tag::String(v.into())
+    }
+
+    /// The register dialog AuthMe 6 sends in configuration (the shape its
+    /// `show_dialog` packet has on the test bed).
+    fn register() -> Tag {
+        Tag::compound([
+            ("type", s("minecraft:multi_action")),
+            ("title", s("Register")),
+            ("can_close_with_escape", Tag::Byte(0)),
+            ("after_action", s("wait_for_response")),
+            (
+                "body",
+                Tag::compound([
+                    ("type", s("minecraft:plain_message")),
+                    ("contents", s("Choose a password")),
+                ]),
+            ),
+            (
+                "inputs",
+                Tag::List(vec![Tag::compound([
+                    ("type", s("minecraft:text")),
+                    ("key", s("password")),
+                    ("label", s("Password")),
+                ])]),
+            ),
+            (
+                "actions",
+                Tag::List(vec![
+                    Tag::compound([
+                        ("label", s("Register")),
+                        (
+                            "action",
+                            Tag::compound([
+                                ("type", s("minecraft:dynamic/custom")),
+                                ("id", s("authme:prejoin-register/submit")),
+                            ]),
+                        ),
+                    ]),
+                    Tag::compound([
+                        ("label", s("Cancel")),
+                        (
+                            "action",
+                            Tag::compound([
+                                ("type", s("minecraft:dynamic/run_command")),
+                                ("template", s("say $(password) $(missing)!")),
+                            ]),
+                        ),
+                    ]),
+                ]),
+            ),
+        ])
+    }
+
+    #[test]
+    fn decodes_a_multi_action_dialog_with_defaults() {
+        let d = Dialog::parse(&register()).unwrap();
+        assert_eq!(d.title.plain(), "Register");
+        assert!(!d.can_close_with_escape);
+        assert!(d.pause);
+        assert_eq!(d.after_action, AfterAction::WaitForResponse);
+        assert!(matches!(&d.body[..], [Body::Message { width: 200, .. }]));
+        let Kind::MultiAction {
+            actions,
+            exit,
+            columns,
+        } = &d.kind
+        else {
+            panic!("{:?}", d.kind)
+        };
+        assert_eq!((actions.len(), exit.is_none(), *columns), (2, true, 2));
+        assert_eq!(actions[0].width, 150);
+        assert!(d.on_cancel().is_none());
+        let [
+            Input {
+                key,
+                control:
+                    Control::Text {
+                        max_length: 32,
+                        width: 200,
+                        ..
+                    },
+            },
+        ] = &d.inputs[..]
+        else {
+            panic!("{:?}", d.inputs)
+        };
+        assert_eq!(key, "password");
+    }
+
+    #[test]
+    fn actions_carry_the_input_values() {
+        let d = Dialog::parse(&register()).unwrap();
+        let values = [InputValue::Text("p\"w".into())];
+        let Kind::MultiAction { actions, .. } = &d.kind else {
+            unreachable!()
+        };
+        let custom = actions[0]
+            .action
+            .as_ref()
+            .unwrap()
+            .click(&d.inputs, &values);
+        assert_eq!(
+            custom,
+            Some(Click::Custom {
+                id: "authme:prejoin-register/submit".into(),
+                payload: Some(Tag::compound([("password", s("p\"w"))])),
+            })
+        );
+        // The template escapes the text; a key no input has becomes nothing.
+        let command = actions[1]
+            .action
+            .as_ref()
+            .unwrap()
+            .click(&d.inputs, &values);
+        assert_eq!(command, Some(Click::RunCommand("say p\\\"w !".into())));
+    }
+
+    #[test]
+    fn a_notice_without_an_action_has_ok() {
+        let d = Dialog::parse(&Tag::compound([("type", s("notice")), ("title", s("Hi"))])).unwrap();
+        let Kind::Notice(b) = &d.kind else {
+            unreachable!()
+        };
+        assert_eq!(b.label, Text::translate("gui.ok", &[]));
+        // Without a title, or with an unknown type, there is no dialog.
+        assert!(Dialog::parse(&Tag::compound([("type", s("notice"))])).is_none());
+        assert!(Dialog::parse(&Tag::compound([("type", s("x")), ("title", s("Hi"))])).is_none());
+    }
+
+    #[test]
+    fn number_ranges_snap_to_their_step() {
+        let mut range = Control::NumberRange {
+            width: 200,
+            label: Text::literal("n"),
+            label_format: "options.generic_value".into(),
+            start: 0.0,
+            end: 10.0,
+            initial: Some(4.0),
+            step: Some(3.0),
+        };
+        assert_eq!(range.initial(), InputValue::Slider(0.4));
+        assert_eq!(range.scaled(&InputValue::Slider(0.62)), Some(7.0));
+        assert_eq!(range.scaled(&InputValue::Slider(1.0)), Some(10.0));
+        let Control::NumberRange { step, .. } = &mut range else {
+            unreachable!()
+        };
+        *step = Some(4.0);
+        // 12 is out of range: one step less.
+        assert_eq!(range.scaled(&InputValue::Slider(1.0)), Some(8.0));
+        assert_eq!(range.substitution(&InputValue::Slider(0.0)), "0");
+        assert_eq!(number_string(2.5), "2.5");
+    }
+}
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index 229f176f9..ce48ce717 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -53,6 +53,7 @@ pub mod datapack;
 pub mod debug_chart;
 pub mod debug_keys;
 pub mod debug_overlay;
+pub mod dialog;
 pub mod dynamic_light;
 pub mod effects;
 pub mod enchant;
diff --git a/crates/horizon-protocol/src/packets/configuration.rs b/crates/horizon-protocol/src/packets/configuration.rs
index a767110eb..ced56dacf 100644
--- a/crates/horizon-protocol/src/packets/configuration.rs
+++ b/crates/horizon-protocol/src/packets/configuration.rs
@@ -45,6 +45,32 @@ packet!(
 packet!(KnownPack { namespace: String => Str, id: String => Str, version: String => Str });
 packet!(SelectKnownPacks { packs: Vec<KnownPack> => List<KnownPack> });
 packet!(CodeOfConduct { text: String => Str });
+packet!(
+    /// ClientboundShowDialogPacket.CONTEXT_FREE_STREAM_CODEC: the dialog
+    /// itself (`Dialog.DIRECT_CODEC` as NBT).
+    ShowDialog { dialog: Tag => Nbt }
+);
+packet!(
+    /// ServerboundCustomClickActionPacket: a `custom` click event's id and
+    /// payload (a dialog's answer).
+    CustomClickAction { id: String => Ident, payload: Option<Tag> => ClickPayload }
+);
+/// ServerboundCustomClickActionPacket.UNTRUSTED_TAG_CODEC: an optional tag
+/// (`End` when there is none) behind its length, 65536 bytes at most.
+pub struct ClickPayload;
+impl Codec<Option<Tag>> for ClickPayload {
+    fn read(r: &mut Reader) -> Result<Option<Tag>> {
+        let n = r.count(65536)?;
+        let tag = Reader::new(r.bytes(n)?).nbt()?;
+        Ok((tag != Tag::End).then_some(tag))
+    }
+    fn write(v: &Option<Tag>, w: &mut Writer) {
+        let mut tag = Writer::new();
+        tag.nbt(v.as_ref().unwrap_or(&Tag::End));
+        w.varint(tag.data.len() as i32);
+        w.bytes(&tag.data);
+    }
+}
 
 packet_enum!(Clientbound, crate::ids::configuration::clientbound {
     CookieRequest(CookieRequest) = COOKIE_REQUEST,
@@ -63,6 +89,7 @@ packet_enum!(Clientbound, crate::ids::configuration::clientbound {
     UpdateTags(UpdateTags) = UPDATE_TAGS,
     SelectKnownPacks(SelectKnownPacks) = SELECT_KNOWN_PACKS,
     ClearDialog(Empty) = CLEAR_DIALOG,
+    ShowDialog(ShowDialog) = SHOW_DIALOG,
     CodeOfConduct(CodeOfConduct) = CODE_OF_CONDUCT,
 });
 
@@ -142,6 +169,7 @@ packet_enum!(Serverbound, crate::ids::configuration::serverbound {
     ResourcePack(ResourcePackResponse) = RESOURCE_PACK,
     SelectKnownPacks(SelectKnownPacks) = SELECT_KNOWN_PACKS,
     AcceptCodeOfConduct(Empty) = ACCEPT_CODE_OF_CONDUCT,
+    CustomClickAction(CustomClickAction) = CUSTOM_CLICK_ACTION,
 });
 
 #[cfg(test)]
@@ -208,6 +236,10 @@ mod tests {
             Clientbound::CodeOfConduct(CodeOfConduct {
                 text: "Be nice".into(),
             }),
+            Clientbound::ShowDialog(ShowDialog {
+                dialog: Tag::compound([("type", Tag::String("minecraft:notice".into()))]),
+            }),
+            Clientbound::ClearDialog(Empty),
         ] {
             round_trip(p, Clientbound::encode, Clientbound::decode);
         }
@@ -219,8 +251,28 @@ mod tests {
             Serverbound::ResourcePack(ResourcePackResponse { id: 5, action: 1 }),
             Serverbound::SelectKnownPacks(SelectKnownPacks { packs: vec![] }),
             Serverbound::AcceptCodeOfConduct(Empty),
+            Serverbound::CustomClickAction(CustomClickAction {
+                id: "authme:prejoin-register/submit".into(),
+                payload: Some(Tag::compound([("password", Tag::String("hunter2".into()))])),
+            }),
+            Serverbound::CustomClickAction(CustomClickAction {
+                id: "minecraft:x".into(),
+                payload: None,
+            }),
         ] {
             round_trip(p, Serverbound::encode, Serverbound::decode);
         }
     }
+
+    /// The bytes vanilla writes: the length, then the tag (a lone `End` byte
+    /// for none).
+    #[test]
+    fn click_payload_is_length_prefixed() {
+        let mut w = Writer::new();
+        ClickPayload::write(&None, &mut w);
+        assert_eq!(w.data, [1, 0]);
+        let mut w = Writer::new();
+        ClickPayload::write(&Some(Tag::Byte(1)), &mut w);
+        assert_eq!(w.data, [2, 1, 1]);
+    }
 }
diff --git a/crates/horizon-protocol/src/packets/play.rs b/crates/horizon-protocol/src/packets/play.rs
index 42e3ba686..7b52b4c13 100644
--- a/crates/horizon-protocol/src/packets/play.rs
+++ b/crates/horizon-protocol/src/packets/play.rs
@@ -13,8 +13,8 @@ use crate::{
     packets::{
         Empty,
         configuration::{
-            ClientInformation, CustomPayload, Disconnect, KeepAlive, Ping, ResourcePackPop,
-            ResourcePackPush, ResourcePackResponse, UpdateTags,
+            ClientInformation, CustomClickAction, CustomPayload, Disconnect, KeepAlive, Ping,
+            ResourcePackPop, ResourcePackPush, ResourcePackResponse, UpdateTags,
         },
         login::Property,
     },
@@ -189,6 +189,35 @@ impl Codec<i32> for HolderId {
         w.varint(v + 1)
     }
 }
+/// `Holder<Dialog>` as Dialog.STREAM_CODEC sends it: an entry of the
+/// `minecraft:dialog` registry the server sent in configuration, or the
+/// dialog itself.
+#[derive(Clone, Debug, PartialEq)]
+pub enum DialogHolder {
+    Registry(i32),
+    Direct(Tag),
+}
+impl Codec<DialogHolder> for DialogHolder {
+    fn read(r: &mut Reader) -> Result<Self> {
+        Ok(match r.varint()? {
+            0 => Self::Direct(r.nbt()?),
+            id => Self::Registry(id - 1),
+        })
+    }
+    fn write(v: &Self, w: &mut Writer) {
+        match v {
+            Self::Registry(id) => w.varint(id + 1),
+            Self::Direct(tag) => {
+                w.varint(0);
+                w.nbt(tag);
+            }
+        }
+    }
+}
+packet!(
+    /// ClientboundShowDialogPacket.
+    ShowDialog { dialog: DialogHolder => DialogHolder }
+);
 packet!(
     /// ChatType.Bound.
     ChatTypeBound { chat_type: i32 => HolderId, name: Tag => Nbt, target: Option<Tag> => Opt<Nbt> }
@@ -1693,6 +1722,8 @@ packet_enum!(Clientbound, crate::ids::play::clientbound {
     UpdateMobEffect(UpdateMobEffect) = UPDATE_MOB_EFFECT,
     UpdateTags(UpdateTags) = UPDATE_TAGS,
     TrackedWaypoint(TrackedWaypoint) = WAYPOINT,
+    ClearDialog(Empty) = CLEAR_DIALOG,
+    ShowDialog(ShowDialog) = SHOW_DIALOG,
 });
 packet!(
     /// ClientboundClearTitlesPacket: whether to also reset the timings.
@@ -2067,6 +2098,7 @@ packet_enum!(Serverbound, crate::ids::play::serverbound {
     ContainerClick(ContainerClick) = CONTAINER_CLICK,
     ContainerClose(ContainerClose) = CONTAINER_CLOSE,
     CustomPayload(CustomPayload) = CUSTOM_PAYLOAD,
+    CustomClickAction(CustomClickAction) = CUSTOM_CLICK_ACTION,
     EditBook(EditBook) = EDIT_BOOK,
     Interact(Interact) = INTERACT,
     KeepAlive(KeepAlive) = KEEP_ALIVE,
@@ -2861,4 +2893,28 @@ mod tests {
         w.varint(101);
         assert!(BookPages::read(&mut Reader::new(&w.data)).is_err());
     }
+
+    /// A registry entry is its id + 1, the dialog itself a 0 then its NBT.
+    #[test]
+    fn dialogs_round_trip() {
+        let notice = Tag::compound([("type", Tag::String("minecraft:notice".into()))]);
+        for dialog in [DialogHolder::Registry(3), DialogHolder::Direct(notice)] {
+            crate::packets::round_trip(
+                Clientbound::ShowDialog(ShowDialog { dialog }),
+                Clientbound::encode,
+                Clientbound::decode,
+            );
+        }
+        let mut w = Writer::new();
+        DialogHolder::write(&DialogHolder::Registry(3), &mut w);
+        assert_eq!(w.data, [4]);
+        crate::packets::round_trip(
+            Serverbound::CustomClickAction(CustomClickAction {
+                id: "minecraft:custom".into(),
+                payload: None,
+            }),
+            Serverbound::encode,
+            Serverbound::decode,
+        );
+    }
 }

From 5e348aa479aafa0ab2f03320fb637a5596f00900 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:03:54 +0100
Subject: [PATCH 019/270] Shader packs, clean room 20: buffer mipmaps

`const bool <buffer>MipmapEnabled = true;` in a deferred, composite or
final program's fragment stage now regenerates that buffer's mip chain
right before the program (6.1.7), on the side programs read, and only
when the buffer changed since its last chain this frame. Each level is
the average of the 2x2 texels above it; levels attach one at a time and
programs sample all of them. Unfilterable buffers (integer, 32-bit
float) get none, with a note.

BSL's bloom read every tap from the full-size buffer before; with its
chain composite4 drops from 0.38 to 0.29 ms at 720p on the Mac mini
(HORIZON_SHADER_PACK_TIMING, the chains included), and blurs as intended.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
section 6.1.7; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_post.rs   | 156 +++++++++++++++++--
 crates/horizon-client/src/gfx/pack_post.wgsl |   8 +
 crates/horizon-shaders/src/post.rs           |  18 ++-
 3 files changed, 172 insertions(+), 10 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 739688784..2f152b893 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -137,9 +137,19 @@ struct Pass {
     reads: u16,
     /// Buffers written.
     written: u16,
+    /// Buffers whose mip chain is regenerated right before it (6.1.7).
+    mipmaps: u16,
     groups: HashMap<u16, wgpu::BindGroup>,
 }
 
+/// One side of a buffer with mipmaps.
+struct Mips {
+    /// Every level, for sampling.
+    all: wgpu::TextureView,
+    /// From the second level down: its attachment, and a bind group over the level above.
+    levels: Vec<(wgpu::TextureView, wgpu::BindGroup)>,
+}
+
 struct Targets {
     size: [u32; 2],
     /// A and B of each buffer used.
@@ -148,6 +158,8 @@ struct Targets {
     depth_texture: wgpu::Texture,
     /// `depthtex1`, when a program after translucent terrain reads it.
     depth1: Option<(wgpu::Texture, wgpu::TextureView)>,
+    /// Both sides' mip chains of the buffers with mipmaps (`color` is their first level).
+    mips: [Option<[Mips; 2]>; BUFFERS],
 }
 
 /// What a pack's gbuffers programs read and draw from the game's world.
@@ -168,6 +180,12 @@ pub struct PackPost {
     water: Option<Pass>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
+    /// Buffers with mipmaps (filterable ones a program asks them for).
+    mipped: u16,
+    /// Buffers whose mip chain matches their first level, this frame.
+    mips_valid: u16,
+    /// The downsampling pipeline of each format with mipmaps.
+    down: HashMap<wgpu::TextureFormat, (wgpu::RenderPipeline, wgpu::BindGroupLayout)>,
     /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
     timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
@@ -693,6 +711,7 @@ fn build_pass(
         flip,
         reads,
         written,
+        mipmaps: p.mipmaps,
         groups: HashMap::new(),
     })
 }
@@ -848,6 +867,39 @@ impl PackPost {
             &[target(screen)],
             None,
         );
+        let filterable = |b: usize| {
+            formats[b].sample_type(None, Some(device.features()))
+                == Some(wgpu::TextureSampleType::Float { filterable: true })
+        };
+        let asked = passes.iter().fold(0u16, |m, p| m | p.mipmaps);
+        let mipped = (0..BUFFERS)
+            .filter(|&b| asked & 1 << b != 0 && filterable(b))
+            .fold(0u16, |m, b| m | 1 << b);
+        if asked & !mipped != 0 {
+            notes.push(format!(
+                "mipmaps of unfilterable buffers are not generated (buffers {:#b})",
+                asked & !mipped
+            ));
+        }
+        let mut down = HashMap::new();
+        for b in (0..BUFFERS).filter(|b| mipped & 1 << b != 0) {
+            down.entry(formats[b]).or_insert_with(|| {
+                helper(
+                    device,
+                    "vs_full",
+                    "fs_down",
+                    &[
+                        texture_entry(0, float),
+                        entry(
+                            2,
+                            wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
+                        ),
+                    ],
+                    &[target(formats[b])],
+                    None,
+                )
+            });
+        }
         let white = [255u8; 4];
         Self {
             notes,
@@ -855,6 +907,9 @@ impl PackPost {
             terrain,
             water,
             depth1,
+            mipped,
+            mips_valid: 0,
+            down,
             timing: super::pack_timing::PassTiming::new(device, queue),
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
@@ -960,9 +1015,14 @@ impl PackPost {
             }];
             for s in &pass.samplers {
                 let texture = match s.source {
-                    Source::Color(i) => targets.color[i]
-                        .as_ref()
-                        .map_or(&self.dummy, |t| &t[usize::from(key & 1 << i != 0)]),
+                    Source::Color(i) => {
+                        let side = usize::from(key & 1 << i != 0);
+                        match (&targets.mips[i], &targets.color[i]) {
+                            (Some(m), _) => &m[side].all,
+                            (None, Some(t)) => &t[side],
+                            (None, None) => &self.dummy,
+                        }
+                    }
                     Source::Depth => &targets.depth,
                     // Before translucent terrain the two are the same.
                     Source::Depth1 => match &targets.depth1 {
@@ -1075,6 +1135,7 @@ impl PackPost {
             rp.set_bind_group(0, &group, &[]);
             draw(&mut rp, translucent);
         }
+        self.mips_valid &= !pass.written;
         if translucent {
             self.water = Some(pass);
         } else {
@@ -1082,6 +1143,32 @@ impl PackPost {
         }
     }
 
+    /// Regenerates the mip chain of buffer `b`'s side that programs read.
+    fn mipmap(&self, encoder: &mut wgpu::CommandEncoder, b: usize) {
+        let (Some(targets), Some((pipeline, _))) = (&self.targets, self.down.get(&self.formats[b]))
+        else {
+            return;
+        };
+        let Some(mips) = &targets.mips[b] else { return };
+        let side = &mips[usize::from(self.main & 1 << b != 0)];
+        for (attachment, group) in &side.levels {
+            let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: Some("Shader pack mipmap"),
+                color_attachments: &[attach(
+                    attachment,
+                    wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
+                        store: wgpu::StoreOp::Store,
+                    },
+                )],
+                ..Default::default()
+            });
+            rp.set_pipeline(pipeline);
+            rp.set_bind_group(0, group, &[]);
+            rp.draw(0..3, 0..1);
+        }
+    }
+
     /// Whether the pack draws terrain itself.
     pub fn has_terrain(&self) -> bool {
         self.terrain.is_some()
@@ -1101,7 +1188,8 @@ impl PackPost {
         if self.targets.as_ref().is_some_and(|t| t.size == size) {
             return;
         }
-        let texture = |label: &str, format, usage| {
+        let full_chain = 32 - size[0].max(size[1]).max(1).leading_zeros();
+        let texture_levels = |label: &str, format, usage, levels| {
             device.create_texture(&wgpu::TextureDescriptor {
                 label: Some(label),
                 size: wgpu::Extent3d {
@@ -1109,7 +1197,7 @@ impl PackPost {
                     height: size[1],
                     depth_or_array_layers: 1,
                 },
-                mip_level_count: 1,
+                mip_level_count: levels,
                 sample_count: 1,
                 dimension: wgpu::TextureDimension::D2,
                 format,
@@ -1117,14 +1205,55 @@ impl PackPost {
                 view_formats: &[],
             })
         };
-        let make = |label: &str, format| {
-            texture(label, format, wgpu::TextureUsages::RENDER_ATTACHMENT)
-                .create_view(&Default::default())
+        let texture = |label: &str, format, usage| texture_levels(label, format, usage, 1);
+        let level = |t: &wgpu::Texture, level: u32| {
+            t.create_view(&wgpu::TextureViewDescriptor {
+                base_mip_level: level,
+                mip_level_count: Some(1),
+                ..Default::default()
+            })
         };
+        let mut mips: [Option<[Mips; 2]>; BUFFERS] = Default::default();
         let color = std::array::from_fn(|i| {
             (self.used & 1 << i != 0).then(|| {
                 let label = format!("colortex{i}");
-                [make(&label, self.formats[i]), make(&label, self.formats[i])]
+                let mipped = self.mipped & 1 << i != 0;
+                let levels = if mipped { full_chain } else { 1 };
+                let attachment = wgpu::TextureUsages::RENDER_ATTACHMENT;
+                let sides =
+                    [0, 1].map(|_| texture_levels(&label, self.formats[i], attachment, levels));
+                if mipped && let Some((_, layout)) = self.down.get(&self.formats[i]) {
+                    mips[i] = Some(sides.each_ref().map(|t| {
+                        Mips {
+                            all: t.create_view(&Default::default()),
+                            levels: (1..levels)
+                                .map(|l| {
+                                    let group =
+                                        device.create_bind_group(&wgpu::BindGroupDescriptor {
+                                            label: Some(&label),
+                                            layout,
+                                            entries: &[
+                                                wgpu::BindGroupEntry {
+                                                    binding: 0,
+                                                    resource: wgpu::BindingResource::TextureView(
+                                                        &level(t, l - 1),
+                                                    ),
+                                                },
+                                                wgpu::BindGroupEntry {
+                                                    binding: 2,
+                                                    resource: wgpu::BindingResource::Sampler(
+                                                        &self.linear,
+                                                    ),
+                                                },
+                                            ],
+                                        });
+                                    (level(t, l), group)
+                                })
+                                .collect(),
+                        }
+                    }));
+                }
+                sides.map(|t| level(&t, 0))
             })
         });
         let depth32 = wgpu::TextureFormat::Depth32Float;
@@ -1144,6 +1273,7 @@ impl PackPost {
             depth: depth_texture.create_view(&Default::default()),
             depth_texture,
             depth1,
+            mips,
         });
         let gbuffers = self.terrain.iter_mut().chain(&mut self.water);
         for pass in self.passes.iter_mut().chain(gbuffers) {
@@ -1277,6 +1407,8 @@ impl PackPost {
             pass.draw(0..3, 0..1);
         }
 
+        // The world and the clears just rewrote the buffers' first levels.
+        self.mips_valid = 0;
         let mut passes = std::mem::take(&mut self.passes);
         let mut seen = (false, false);
         let mut shown = false;
@@ -1299,6 +1431,11 @@ impl PackPost {
                 seen.1 = true;
                 self.main ^= self.composite_pre;
             }
+            let stale = pass.mipmaps & self.mipped & !self.mips_valid;
+            for b in (0..BUFFERS).filter(|b| stale & 1 << b != 0) {
+                self.mipmap(encoder, b);
+            }
+            self.mips_valid |= stale;
             let final_pass = pass.group == Group::Final;
             let group = self.bind(device, queue, pass, if final_pass { window } else { size });
             let targets = self.targets.as_ref().expect("resized");
@@ -1332,6 +1469,7 @@ impl PackPost {
                 rp.draw(0..6, 0..1);
             }
             self.main ^= pass.flip;
+            self.mips_valid &= !pass.written;
         }
         self.passes = passes;
         if !terrain_drawn {
diff --git a/crates/horizon-client/src/gfx/pack_post.wgsl b/crates/horizon-client/src/gfx/pack_post.wgsl
index 75877dddc..299e9207b 100644
--- a/crates/horizon-client/src/gfx/pack_post.wgsl
+++ b/crates/horizon-client/src/gfx/pack_post.wgsl
@@ -53,3 +53,11 @@ fn vs_uv(@builtin(vertex_index) i: u32) -> Full {
 fn fs_copy(v: Full) -> @location(0) vec4<f32> {
     return textureSample(source, linear, v.uv);
 }
+
+// One level of a buffer's mip chain from the level above (6.1.7): the average of the 2×2
+// texels under each destination texel, by one bilinear sample at their shared corner.
+@fragment
+fn fs_down(@builtin(position) p: vec4<f32>) -> @location(0) vec4<f32> {
+    let size = max(textureDimensions(source) / 2u, vec2<u32>(1u));
+    return textureSampleLevel(source, linear, p.xy / vec2<f32>(size), 0.0);
+}
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index e50eb4797..e155cefbe 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -111,6 +111,9 @@ pub struct PostProgram {
     pub flips: Vec<(u32, bool)>,
     /// How a gbuffers program's output blends into its buffers; `None` writes them.
     pub blend: Option<Blend>,
+    /// Bit n: `colortex<n>MipmapEnabled` in its fragment stage, so buffer n's mip chain is
+    /// regenerated right before it (6.1.7; not for gbuffers programs).
+    pub mipmaps: u16,
 }
 
 pub struct Post {
@@ -280,6 +283,16 @@ impl Loader<'_> {
         self.post.config.read(&vertex);
         self.post.config.read(&fragment);
         let buffers = config::draw_buffers(&fragment).unwrap_or_else(|| (0..8).collect());
+        let mipmaps = match group {
+            Group::Gbuffers | Group::Translucent => 0,
+            _ => {
+                let mut own = Config::default();
+                own.read(&fragment);
+                (own.buffers.iter().enumerate())
+                    .filter(|b| b.1.mipmap)
+                    .fold(0, |m, (i, _)| m | 1 << i)
+            }
+        };
         Some(PostProgram {
             flips: flips(self.properties, &name),
             name,
@@ -287,6 +300,7 @@ impl Loader<'_> {
             program,
             buffers,
             blend: None,
+            mipmaps,
         })
     }
 }
@@ -391,7 +405,8 @@ mod tests {
                 ("shaders/deferred.vsh", VSH),
                 (
                     "shaders/deferred.fsh",
-                    "#version 120\nvoid main() { gl_FragColor = vec4(1.0); }\n",
+                    "#version 120\nconst bool colortex5MipmapEnabled = true;\n\
+                     void main() { gl_FragColor = vec4(1.0); }\n",
                 ),
                 ("shaders/composite1.fsh", FSH),
                 ("shaders/composite3.vsh", VSH),
@@ -423,6 +438,7 @@ mod tests {
         assert_eq!(names, ["deferred", "composite", "composite2", "final"]);
         let p = &post.programs;
         assert_eq!(p[0].buffers, (0..8).collect::<Vec<_>>());
+        assert_eq!((p[0].mipmaps, p[1].mipmaps), (1 << 5, 0));
         assert_eq!(p[1].buffers, [3]);
         assert_eq!(p[1].flips, [(3, false)]);
         assert_eq!(p[2].flips, [(4, true)]);

From b9b47f12dabd79ba8c48998d9aa98974e26a3eb4 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:29:21 +0100
Subject: [PATCH 020/270] Shader packs, clean room 21: per-draw uniforms
 (renderStage)

A gbuffers program's renderStage, entityId, blockEntityId and entityColor
(spec 5.3, updated per draw) move to a block of their own at set 2 that
the game picks per draw with a dynamic offset: one slot per render stage.
Terrain draws as TERRAIN_SOLID, translucent terrain as
TERRAIN_TRANSLUCENT. The terrain test pack paints any other stage red.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
5.3, 5.4; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              |  1 +
 crates/horizon-client/src/gfx/pack_draw.rs    | 67 +++++++++++++++++++
 crates/horizon-client/src/gfx/pack_post.rs    | 25 ++++++-
 crates/horizon-shaders/src/lib.rs             |  6 +-
 crates/horizon-shaders/src/macros.rs          |  8 +++
 crates/horizon-shaders/src/translate/mod.rs   | 47 ++++++++++++-
 .../terrain-test/shaders/gbuffers_terrain.fsh |  3 +
 7 files changed, 150 insertions(+), 7 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_draw.rs

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index f0987dddd..354dc8d07 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -69,6 +69,7 @@ pub mod lightning;
 mod lod;
 mod occlusion;
 mod pack_atlas;
+mod pack_draw;
 mod pack_post;
 mod pack_timing;
 pub mod pack_uniforms;
diff --git a/crates/horizon-client/src/gfx/pack_draw.rs b/crates/horizon-client/src/gfx/pack_draw.rs
new file mode 100644
index 000000000..91c77a6bf
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_draw.rs
@@ -0,0 +1,67 @@
+//! The uniforms a shader pack's gbuffers programs read per draw (`HzDraw` at set 2, the
+//! translator's `DRAW_UNIFORMS`): one slot per render stage of a uniform buffer, picked with a
+//! dynamic offset at each draw.
+
+use horizon_shaders::{RENDER_STAGES, render_stage};
+
+/// `HzDraw`'s size: `renderStage`, `entityId`, `blockEntityId`, a pad, `entityColor`.
+const SIZE: u32 = 32;
+
+pub(super) struct DrawUniforms {
+    pub layout: wgpu::BindGroupLayout,
+    group: wgpu::BindGroup,
+    stride: u32,
+}
+
+impl DrawUniforms {
+    pub fn new(device: &wgpu::Device) -> Self {
+        let stride = SIZE.max(device.limits().min_uniform_buffer_offset_alignment);
+        let mut contents = vec![0u8; stride as usize * RENDER_STAGES.len()];
+        for (i, slot) in contents.chunks_mut(stride as usize).enumerate() {
+            slot[..4].copy_from_slice(&(i as i32).to_le_bytes());
+        }
+        let buffer = wgpu::util::DeviceExt::create_buffer_init(
+            device,
+            &wgpu::util::BufferInitDescriptor {
+                label: Some("Shader pack draws"),
+                contents: &contents,
+                usage: wgpu::BufferUsages::UNIFORM,
+            },
+        );
+        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("Shader pack draws"),
+            entries: &[wgpu::BindGroupLayoutEntry {
+                binding: 0,
+                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
+                ty: wgpu::BindingType::Buffer {
+                    ty: wgpu::BufferBindingType::Uniform,
+                    has_dynamic_offset: true,
+                    min_binding_size: wgpu::BufferSize::new(u64::from(SIZE)),
+                },
+                count: None,
+            }],
+        });
+        let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+            label: Some("Shader pack draws"),
+            layout: &layout,
+            entries: &[wgpu::BindGroupEntry {
+                binding: 0,
+                resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
+                    buffer: &buffer,
+                    offset: 0,
+                    size: wgpu::BufferSize::new(u64::from(SIZE)),
+                }),
+            }],
+        });
+        Self {
+            layout,
+            group,
+            stride,
+        }
+    }
+
+    /// Draws that follow read `renderStage` = `MC_RENDER_STAGE_<stage>`, other values zero.
+    pub fn bind(&self, pass: &mut wgpu::RenderPass<'_>, stage: &str) {
+        pass.set_bind_group(2, &self.group, &[self.stride * render_stage(stage)]);
+    }
+}
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 2f152b893..08a2dedcc 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -15,6 +15,7 @@ use std::collections::HashMap;
 
 use horizon_shaders::{Format, Group, Kind, Post, Val};
 
+use super::pack_draw::DrawUniforms;
 use super::pack_uniforms::{self, FrameUniforms, PackInputs};
 
 const BUFFERS: usize = horizon_shaders::BUFFERS;
@@ -139,6 +140,8 @@ struct Pass {
     written: u16,
     /// Buffers whose mip chain is regenerated right before it (6.1.7).
     mipmaps: u16,
+    /// Reads the per-draw block (`DrawUniforms`).
+    draw: bool,
     groups: HashMap<u16, wgpu::BindGroup>,
 }
 
@@ -186,6 +189,8 @@ pub struct PackPost {
     mips_valid: u16,
     /// The downsampling pipeline of each format with mipmaps.
     down: HashMap<wgpu::TextureFormat, (wgpu::RenderPipeline, wgpu::BindGroupLayout)>,
+    /// The per-draw uniforms of gbuffers programs.
+    draws: DrawUniforms,
     /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
     timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
@@ -488,6 +493,7 @@ fn build_pass(
     notes: &mut Vec<String>,
     geometry: Option<&Geometry<'_>>,
     custom: &[String],
+    draws: &wgpu::BindGroupLayout,
 ) -> Option<Pass> {
     let features = device.features();
     // The frame's uniforms, then the pack's custom ones.
@@ -499,6 +505,7 @@ fn build_pass(
     };
     let mask = |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
     let interface = &p.program.interface;
+    let draw = interface.draw;
     let mut entries = vec![entry(
         0,
         wgpu::BindingType::Buffer {
@@ -632,7 +639,11 @@ fn build_pass(
         });
         let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
             label: Some(&p.name),
-            bind_group_layouts: &[Some(&layout), geometry.and_then(|g| g.table)],
+            bind_group_layouts: &[
+                Some(&layout),
+                geometry.and_then(|g| g.table),
+                draw.then_some(draws),
+            ],
             ..Default::default()
         });
         let module = |mut m: naga::Module| {
@@ -712,6 +723,7 @@ fn build_pass(
         reads,
         written,
         mipmaps: p.mipmaps,
+        draw,
         groups: HashMap::new(),
     })
 }
@@ -748,6 +760,7 @@ impl PackPost {
         let mask =
             |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
         let mut used = 1u16;
+        let draws = DrawUniforms::new(device);
         let mut build = |p: horizon_shaders::PostProgram, geometry: Option<&Geometry<'_>>| {
             let pass = build_pass(
                 device,
@@ -757,6 +770,7 @@ impl PackPost {
                 &mut notes,
                 geometry,
                 &custom_names,
+                &draws.layout,
             )?;
             used |= pass.reads | pass.written | pass.flip;
             Some(pass)
@@ -910,6 +924,7 @@ impl PackPost {
             mipped,
             mips_valid: 0,
             down,
+            draws,
             timing: super::pack_timing::PassTiming::new(device, queue),
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
@@ -1133,6 +1148,14 @@ impl PackPost {
             });
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
+            if pass.draw {
+                let stage = if translucent {
+                    "TERRAIN_TRANSLUCENT"
+                } else {
+                    "TERRAIN_SOLID"
+                };
+                self.draws.bind(&mut rp, stage);
+            }
             draw(&mut rp, translucent);
         }
         self.mips_valid &= !pass.written;
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index f5819d435..bed86758e 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -30,7 +30,7 @@ pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffe
 pub use custom::{Custom, Val};
 pub use discover::{Found, discover};
 pub use lang::Lang;
-pub use macros::{MC_VERSION, Macros, RENDER_STAGES};
+pub use macros::{MC_VERSION, Macros, RENDER_STAGES, render_stage};
 pub use options::switches_on;
 pub use pack::{Pack, PackError};
 pub use post::{
@@ -39,6 +39,6 @@ pub use post::{
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
 pub use translate::{
-    Error, GbuffersInputs, Interface, Program, Sampler, Target, Uniform, translate_composite,
-    translate_gbuffers,
+    DRAW_UNIFORMS, Error, GbuffersInputs, Interface, Program, Sampler, Target, Uniform,
+    translate_composite, translate_gbuffers,
 };
diff --git a/crates/horizon-shaders/src/macros.rs b/crates/horizon-shaders/src/macros.rs
index d8a184f41..6c7fb2678 100644
--- a/crates/horizon-shaders/src/macros.rs
+++ b/crates/horizon-shaders/src/macros.rs
@@ -60,6 +60,14 @@ pub const RENDER_STAGES: [&str; 24] = [
     "HAND_TRANSLUCENT",
 ];
 
+/// The value of `MC_RENDER_STAGE_<name>` (OQ-7: its index in `RENDER_STAGES`).
+pub fn render_stage(name: &str) -> u32 {
+    RENDER_STAGES
+        .iter()
+        .position(|s| *s == name)
+        .unwrap_or_else(|| panic!("no render stage {name}")) as u32
+}
+
 impl Macros {
     /// The standard macros that need no renderer (spec 1.5.1): `MC_VERSION`, this system's
     /// `MC_OS_*`, the GL and GLSL versions Horizon's translation accepts, the render stages and
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 83dcb3af9..fe736e4d8 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -45,8 +45,19 @@ pub struct Interface {
     pub samplers: Vec<Sampler>,
     /// The fragment stage's output locations.
     pub outputs: Vec<u32>,
+    /// A gbuffers program reads `DRAW_UNIFORMS`: the block at set 2, binding 0, set per draw.
+    pub draw: bool,
 }
 
+/// The uniforms a gbuffers program reads per draw (5.3's "D"), in a block of their own
+/// (`HzDraw`, std140: three ints, a pad, a vec4; 32 bytes) the game sets for each draw.
+pub const DRAW_UNIFORMS: [(&str, &str); 4] = [
+    ("renderStage", "int"),
+    ("entityId", "int"),
+    ("blockEntityId", "int"),
+    ("entityColor", "vec4"),
+];
+
 #[derive(Clone, Debug, PartialEq)]
 pub struct Uniform {
     pub name: String,
@@ -170,6 +181,17 @@ fn translate(
             samplers.insert(name.clone(), ty.clone());
         }
     }
+    // Per-draw values move to their own block; another type than the documented one keeps
+    // the frame's block (and reads zero).
+    let mut draw = false;
+    if gbuffers.is_some() {
+        for (name, ty) in DRAW_UNIFORMS {
+            if uniforms.get(name).is_some_and(|t| t == ty) {
+                uniforms.remove(name);
+                draw = true;
+            }
+        }
+    }
     let samplers: Vec<Sampler> = samplers
         .into_iter()
         .enumerate()
@@ -203,6 +225,12 @@ fn translate(
             .unwrap();
         }
         h.push_str(" };\n");
+        if draw {
+            h.push_str(
+                "layout(set = 2, binding = 0) uniform HzDraw { int renderStage; int entityId; \
+                 int blockEntityId; int hz_draw_pad; vec4 entityColor; };\n",
+            );
+        }
         for s in &samplers {
             let (texture, sampler) = split_sampler(&s.ty);
             writeln!(
@@ -327,6 +355,7 @@ fn translate(
             uniforms,
             samplers,
             outputs,
+            draw,
         },
     })
 }
@@ -394,7 +423,11 @@ fn compile(stage: &Stage, text: &str, header_lines: usize) -> Result<naga::Modul
 /// The uniform block's size and member offsets, from naga's layout.
 fn block_layout(module: &naga::Module) -> (u32, Vec<(String, u32)>) {
     for (_, var) in module.global_variables.iter() {
-        if var.space != naga::AddressSpace::Uniform {
+        let frame = var
+            .binding
+            .as_ref()
+            .is_some_and(|b| b.group == 0 && b.binding == 0);
+        if var.space != naga::AddressSpace::Uniform || !frame {
             continue;
         }
         if let naga::TypeInner::Struct { members, span } = &module.types[var.ty].inner {
@@ -546,9 +579,9 @@ mod tests {
                    light = (gl_TextureMatrix[1] * gl_MultiTexCoord1).xy;\n    color = gl_Color;\n    \
                    normal = normalize(gl_NormalMatrix * gl_Normal);\n    id = mc_Entity.x + mc_midTexCoord.x;\n}\n";
         let fsh = "#version 120\nuniform sampler2D texture;\nuniform sampler2D lightmap;\nuniform mat4 gbufferModelView;\n\
-                   varying vec2 uv;\nvarying vec2 light;\nvarying vec4 color;\nvarying vec3 normal;\nvarying float id;\n\
+                   uniform int renderStage;\nvarying vec2 uv;\nvarying vec2 light;\nvarying vec4 color;\nvarying vec3 normal;\nvarying float id;\n\
                    void main() {\n    vec4 c = texture2D(texture, uv) * texture2D(lightmap, light) * color;\n    \
-                   /* DRAWBUFFERS:02 */\n    gl_FragData[0] = c * gl_FragCoord.z;\n    \
+                   /* DRAWBUFFERS:02 */\n    gl_FragData[0] = c * gl_FragCoord.z * float(renderStage);\n    \
                    gl_FragData[1] = vec4(normal * 0.5 + 0.5, id);\n}\n";
         let files: Vec<(String, &str)> =
             [("gbuffers_terrain.vsh", vsh), ("gbuffers_terrain.fsh", fsh)]
@@ -586,6 +619,14 @@ mod tests {
             assert!(names.contains(&name), "{name} missing from {names:?}");
         }
         assert_eq!(p.interface.outputs, vec![0, 1]);
+        // renderStage is set per draw, in its own block.
+        assert!(p.interface.draw && !names.contains(&"renderStage"));
+        let per_draw = p.fragment.global_variables.iter().any(|(_, v)| {
+            v.binding
+                .as_ref()
+                .is_some_and(|b| b.group == 2 && b.binding == 0)
+        });
+        assert!(per_draw);
         let inputs: Vec<&str> = p.vertex.entry_points[0]
             .function
             .arguments
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
index 902cf3525..8be409929 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
@@ -3,6 +3,7 @@
 uniform sampler2D texture;
 uniform sampler2D lightmap;
 uniform ivec2 atlasSize;
+uniform int renderStage;
 
 varying vec2 texcoord;
 varying vec2 lmcoord;
@@ -17,6 +18,8 @@ void main() {
     color.rgb = mix(color.rgb * vec3(0.6, 0.7, 1.2), color.rgb, lmcoord.y);
     // A dot at the face's centre, one texel wide.
     if (length((texcoord - mid) * vec2(atlasSize)) < 1.0) color.rgb = vec3(1.0, 0.0, 1.0);
+    // Any other stage than solid terrain (translucent terrain falls back here): red.
+    if (renderStage != MC_RENDER_STAGE_TERRAIN_SOLID) color.rgb = vec3(1.0, 0.0, 0.0);
     /* DRAWBUFFERS:0 */
     gl_FragData[0] = color;
 }

From a7f8650c6b78f140fc0ea8f01bf4f0ecf9387690 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:29:45 +0100
Subject: [PATCH 021/270] Server dialogs: the dialog screen, its buttons and
 their actions

A server's show_dialog (configuration and play) opens vanilla's
DialogScreen instead of being dropped: the header with the title and the
warning button, the message bodies in a scrolling column, the action
buttons packed into columns (MultiButtonDialogScreen) or side by side in
the footer (notice, confirmation). A button runs its click event: a
custom action goes back as custom_click_action, a command runs (in play;
in configuration vanilla only warns), show_dialog opens another dialog,
copy_to_clipboard copies. after_action closes the screen, leaves it, or
opens the WaitingForResponseScreen. The warning button opens the
"custom screen" warning, whose Disconnect leaves the server. clear_dialog
closes it, and so do the level loading screen and a disconnect. The world
and HUD blur behind it as behind any in-game screen.

Inputs come next; here they are not drawn and keep their initial values.

tools/server_e2e.py is a new harness: a vanilla 26.3 dedicated server and
one Horizon client. Its dialog check shows a dialog with /dialog show,
clicks a command button (the server's trigger), a custom action (the
server's debug log shows its payload) and a wait_for_response one, and
clears a dialog with /dialog clear.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/dialog_screen.rs | 304 ++++++++++++++
 crates/horizon-client/src/game.rs          |  25 +-
 crates/horizon-client/src/game/agent.rs    |   4 +
 crates/horizon-client/src/game/control.rs  |   7 +
 crates/horizon-client/src/game/dialogs.rs  | 450 +++++++++++++++++++++
 crates/horizon-client/src/game/remote.rs   |   8 +
 crates/horizon-client/src/lib.rs           |   1 +
 crates/horizon-client/src/net.rs           |  30 ++
 tools/server_e2e.py                        | 194 +++++++++
 9 files changed, 1021 insertions(+), 2 deletions(-)
 create mode 100644 crates/horizon-client/src/dialog_screen.rs
 create mode 100644 crates/horizon-client/src/game/dialogs.rs
 create mode 100644 tools/server_e2e.py

diff --git a/crates/horizon-client/src/dialog_screen.rs b/crates/horizon-client/src/dialog_screen.rs
new file mode 100644
index 000000000..c9434cfc2
--- /dev/null
+++ b/crates/horizon-client/src/dialog_screen.rs
@@ -0,0 +1,304 @@
+//! `DialogScreen` and its kinds (`SimpleDialogScreen`, `MultiButtonDialogScreen`):
+//! where a server dialog's title, body and buttons go in a
+//! `HeaderAndFooterLayout` (a 33 high header, the body in a `ScrollableLayout`,
+//! the footer), and the `WaitingForResponseScreen` an answer can leave open.
+use crate::{
+    dialog::{Body, Dialog, Kind},
+    font::Font,
+    text::Text,
+};
+
+/// `HeaderAndFooterLayout.DEFAULT_HEADER_AND_FOOTER_HEIGHT`.
+const BAR: f32 = 33.0;
+/// `DialogScreen.WARNING_BUTTON_SPRITES`: normal, disabled, highlighted.
+pub const WARNING_SPRITES: [&str; 3] = [
+    "gui/sprites/dialog/warning_button",
+    "gui/sprites/dialog/warning_button_disabled",
+    "gui/sprites/dialog/warning_button_highlighted",
+];
+
+/// One drawn piece; `y` is from the top of the body (before it scrolls) for
+/// the body's parts, from the top of the screen for the footer's.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Part {
+    /// A line of text and where it starts.
+    Line(Text, f32, f32),
+    /// A button of `Dialog::buttons`.
+    Button { index: usize, rect: [f32; 4] },
+}
+
+#[derive(Clone, Debug)]
+pub struct Layout {
+    /// The title and where it is drawn.
+    pub title: (f32, f32),
+    pub warning: [f32; 4],
+    /// The body's visible area (`ScrollableLayout`'s container): x, y, w, h.
+    pub area: [f32; 4],
+    /// The body's full height: more than the area's scrolls.
+    pub content: f32,
+    pub body: Vec<Part>,
+    pub footer: Vec<Part>,
+}
+
+/// A laid-out element of a `LinearLayout` before it is placed.
+struct Element {
+    w: f32,
+    h: f32,
+    parts: Vec<Part>,
+}
+impl Element {
+    /// Its parts moved to `(x, y)`.
+    fn at(self, x: f32, y: f32) -> impl Iterator<Item = Part> {
+        self.parts.into_iter().map(move |p| match p {
+            Part::Line(t, px, py) => Part::Line(t, px + x, py + y),
+            Part::Button { index, rect } => Part::Button {
+                index,
+                rect: shift(rect, x, y),
+            },
+        })
+    }
+}
+fn shift([x, y, w, h]: [f32; 4], dx: f32, dy: f32) -> [f32; 4] {
+    [x + dx, y + dy, w, h]
+}
+/// `FrameLayout.alignInDimension` at 0.5: the offset that centres `inner`.
+fn centre(outer: f32, inner: f32) -> f32 {
+    ((outer - inner) * 0.5).trunc()
+}
+
+/// `FocusableTextWidget` with the body's settings: `width` wide, the text
+/// wrapped to `width - 8` and centred, 4 of padding all round.
+fn message(font: &Font, contents: &Text, width: f32) -> Element {
+    let lines = font.split_lines(contents, width - 8.0);
+    let mid = (width / 2.0).trunc();
+    let parts = lines
+        .into_iter()
+        .enumerate()
+        .map(|(i, (line, _))| {
+            let x = mid - (font.width_text(&line) / 2.0).trunc();
+            Part::Line(line, x, 4.0 + 9.0 * i as f32)
+        })
+        .collect::<Vec<_>>();
+    Element {
+        w: width,
+        h: 9.0 * parts.len() as f32 + 8.0,
+        parts,
+    }
+}
+
+/// `DialogScreen.packControlsIntoColumns`: full rows in a grid 2 apart, what
+/// is left in a centred row under them.
+fn columns(widths: &[f32], columns: usize, first: usize) -> Element {
+    let columns = columns.max(1);
+    let full = widths.len() / columns * columns;
+    let row_width = |ws: &[f32]| ws.iter().sum::<f32>() + 2.0 * (ws.len().max(1) - 1) as f32;
+    let mut col = vec![0.0f32; columns];
+    for (i, w) in widths[..full].iter().enumerate() {
+        col[i % columns] = col[i % columns].max(*w);
+    }
+    let last = &widths[full..];
+    if !last.is_empty() {
+        // GridLayout spreads a cell over every column it spans (Divisor).
+        let spread = row_width(last) - 2.0 * (columns - 1) as f32;
+        let (each, extra) = ((spread / columns as f32).floor(), spread % columns as f32);
+        for (c, w) in col.iter_mut().enumerate() {
+            *w = w.max(each + f32::from(u8::from((c as f32) < extra)));
+        }
+    }
+    let x_of = |c: usize| col[..c].iter().sum::<f32>() + 2.0 * c as f32;
+    let mut parts = Vec::new();
+    for (i, w) in widths[..full].iter().enumerate() {
+        let (r, c) = (i / columns, i % columns);
+        parts.push(Part::Button {
+            index: first + i,
+            rect: [x_of(c) + centre(col[c], *w), 22.0 * r as f32, *w, 20.0],
+        });
+    }
+    let width = x_of(columns - 1) + col[columns - 1];
+    if !last.is_empty() {
+        let y = 22.0 * (full / columns) as f32;
+        let mut x = centre(width, row_width(last));
+        for (i, w) in last.iter().enumerate() {
+            parts.push(Part::Button {
+                index: first + full + i,
+                rect: [x, y, *w, 20.0],
+            });
+            x += w + 2.0;
+        }
+    }
+    let rows = full / columns + usize::from(!last.is_empty());
+    Element {
+        w: width,
+        h: (22.0 * rows as f32 - 2.0).max(0.0),
+        parts,
+    }
+}
+
+impl Layout {
+    /// `DialogScreen.init` and `repositionElements` on a `w` by `h` screen.
+    pub fn new(dialog: &Dialog, font: &Font, (w, h): (f32, f32)) -> Self {
+        // The header: the title, 10 right of it the warning button, both
+        // centred together.
+        let tw = font.width_text(&dialog.title);
+        let (hx, hy) = (centre(w, tw + 30.0), centre(BAR, 20.0));
+        let title = (hx, hy + centre(20.0, 9.0));
+        let warning = [hx + tw + 10.0, hy, 20.0, 20.0];
+
+        let mut elements: Vec<Element> = dialog
+            .body
+            .iter()
+            .filter_map(|b| match b {
+                Body::Message { contents, width } => Some(message(font, contents, *width as f32)),
+                Body::Item { .. } => None,
+            })
+            .collect();
+        let buttons = dialog.buttons();
+        let (listed, footer_buttons, footer_h) = match &dialog.kind {
+            Kind::MultiAction {
+                actions,
+                exit,
+                columns: n,
+            } => {
+                let widths: Vec<f32> = actions.iter().map(|b| b.width as f32).collect();
+                elements.push(columns(&widths, *n as usize, 0));
+                // ButtonListDialogScreen: the exit button in the footer, else a 5 high one.
+                let footer = exit.as_ref().map(|_| actions.len()).into_iter().collect();
+                (
+                    actions.len(),
+                    footer,
+                    if exit.is_some() { BAR } else { 5.0 },
+                )
+            }
+            Kind::ServerLinks { exit, .. } | Kind::DialogList { exit, .. } => {
+                let footer = exit.as_ref().map(|_| 0).into_iter().collect();
+                (0, footer, if exit.is_some() { BAR } else { 5.0 })
+            }
+            // SimpleDialogScreen: the buttons side by side, 8 apart.
+            Kind::Notice(_) | Kind::Confirmation { .. } => {
+                (0, (0..buttons.len()).collect::<Vec<_>>(), BAR)
+            }
+        };
+        debug_assert!(listed + footer_buttons.len() <= buttons.len());
+
+        // The body: a column 10 apart, each element centred in it.
+        let body_w = elements.iter().map(|e| e.w).fold(0.0, f32::max);
+        let content = elements.iter().map(|e| e.h).sum::<f32>()
+            + 10.0 * elements.len().saturating_sub(1) as f32;
+        // ScrollableLayout: 10 each side for the scrollbar (ReserveStrategy.BOTH),
+        // no higher than what the header and footer leave.
+        let area_w = body_w + 20.0;
+        let area_h = content.min(h - BAR - footer_h).max(0.0);
+        let area_y = (BAR + 30.0).min(h - footer_h - area_h);
+        let area_x = centre(w, area_w);
+        let mut body = Vec::new();
+        let mut y = 0.0;
+        for e in elements {
+            let (x, eh) = (area_x + 10.0 + centre(body_w, e.w), e.h);
+            body.extend(e.at(x, y));
+            y += eh + 10.0;
+        }
+
+        let widths: Vec<f32> = footer_buttons
+            .iter()
+            .map(|&i| buttons[i].width as f32)
+            .collect();
+        let row = widths.iter().sum::<f32>() + 8.0 * widths.len().saturating_sub(1) as f32;
+        let (mut x, fy) = (centre(w, row), h - footer_h + centre(footer_h, 20.0));
+        let mut footer = Vec::new();
+        for (&i, bw) in footer_buttons.iter().zip(&widths) {
+            footer.push(Part::Button {
+                index: i,
+                rect: [x, fy, *bw, 20.0],
+            });
+            x += bw + 8.0;
+        }
+        Self {
+            title,
+            warning: Self::in_bounds(warning, w, h),
+            area: [area_x, area_y, area_w, area_h],
+            content,
+            body,
+            footer,
+        }
+    }
+    /// `makeSureWarningButtonIsInBounds`.
+    fn in_bounds(r: [f32; 4], w: f32, h: f32) -> [f32; 4] {
+        if r[0] < 0.0 || r[1] < 0.0 || r[0] > w - 20.0 || r[1] > h - 20.0 {
+            [(w - 40.0).max(0.0), 5.0f32.min(h), 20.0, 20.0]
+        } else {
+            r
+        }
+    }
+    /// Every part where it is drawn with the body scrolled by `scroll`, and
+    /// whether it is in the body (clipped to its area).
+    pub fn placed(&self, scroll: f32) -> impl Iterator<Item = (Part, bool)> + '_ {
+        let dy = self.area[1] - scroll;
+        let body = self.body.iter().map(move |p| {
+            let p = match p.clone() {
+                Part::Line(t, x, y) => Part::Line(t, x, y + dy),
+                Part::Button { index, rect } => Part::Button {
+                    index,
+                    rect: shift(rect, 0.0, dy),
+                },
+            };
+            (p, true)
+        });
+        body.chain(self.footer.iter().map(|p| (p.clone(), false)))
+    }
+}
+
+/// `WaitingForResponseScreen`: its Back button's label after `ticks`, and
+/// whether it shows and works (it shows after a second, works after five).
+pub fn waiting_button(ticks: u32) -> (Text, bool, bool) {
+    let seconds = (ticks / 20).min(5);
+    let label = match seconds {
+        0 => Text::literal(""),
+        5 => Text::translate("gui.back", &[]),
+        s => Text::translate(
+            "gui.waitingForResponse.button.inactive",
+            &[Text::literal((5 - s).to_string())],
+        ),
+    };
+    (label, seconds >= 1, seconds == 5)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn grids_pack_full_rows_and_centre_the_rest() {
+        // AuthMe's two buttons: one row, 2 apart.
+        let two = columns(&[150.0, 150.0], 2, 0);
+        assert_eq!((two.w, two.h), (302.0, 20.0));
+        // Three in two columns: the third alone, centred under them.
+        let three = columns(&[150.0, 150.0, 150.0], 2, 0);
+        assert_eq!((three.w, three.h), (302.0, 42.0));
+        assert_eq!(
+            three.parts[2],
+            Part::Button {
+                index: 2,
+                rect: [76.0, 22.0, 150.0, 20.0]
+            }
+        );
+        // One in two columns spreads over both.
+        let one = columns(&[100.0], 2, 0);
+        assert_eq!(one.w, 100.0);
+    }
+
+    #[test]
+    fn the_waiting_screens_button_counts_down() {
+        assert!(!waiting_button(0).1);
+        assert_eq!(
+            waiting_button(20).0,
+            Text::translate(
+                "gui.waitingForResponse.button.inactive",
+                &[Text::literal("4")]
+            )
+        );
+        assert_eq!(
+            waiting_button(100),
+            (Text::translate("gui.back", &[]), true, true)
+        );
+    }
+}
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index e25732bdd..283bd2cad 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -36,6 +36,7 @@ mod debug_keys;
 mod decorated_pot;
 mod dedicated;
 mod deflect;
+mod dialogs;
 mod dispense_fixture;
 mod dispenser;
 mod dragon;
@@ -1130,6 +1131,7 @@ struct Game<'a> {
     pending_pack_reload: bool,
     /// A server's resource packs (game/server_packs.rs).
     server_packs: server_packs::ServerPackState,
+    dialogs: dialogs::DialogState,
     world_renderer_ready: bool,
     collision: &'a BlockCollisionRegistry<'a>,
     motion: &'a MotionResources,
@@ -4777,11 +4779,14 @@ impl Game<'_> {
     fn hud(&mut self, size: [u32; 2]) -> HudBatch {
         // The pack prompt replaces the connecting screen (setScreen), but
         // in game it opens over the world.
-        let mut batch = if self.server_packs.prompt.is_some() && self.player.is_none() {
+        let mut batch = if (self.server_packs.prompt.is_some() || self.dialog_open())
+            && self.player.is_none()
+        {
             HudBatch::new(size)
         } else {
             self.hud_layers(size)
         };
+        self.draw_dialog(&mut batch);
         self.draw_pack_prompt(&mut batch);
         // Gui.extractRenderState: the debug overlay comes after the screen
         // and the toasts, so it is over everything, menus included.
@@ -10246,6 +10251,7 @@ impl Game<'_> {
             || (self.title.is_none()
                 && self.player.is_some()
                 && (self.screen.blurs_background(self.pause_menu)
+                    || self.dialog_open()
                     || (self.screen == Screen::Win && self.win_screen_pauses())));
         let radius = self.settings.menu_blur as f32;
         (blurred && radius >= 1.0).then_some(radius)
@@ -10936,7 +10942,9 @@ impl ApplicationHandler for Game<'_> {
                         }) * wheel_sensitivity
                     };
                     let d = scaled(raw_y) as f32;
-                    if let Some(title) = &mut self.title
+                    if self.dialog_open() {
+                        self.dialog_scroll(d);
+                    } else if let Some(title) = &mut self.title
                         && self.screen != Screen::Win
                     {
                         let size = self
@@ -11003,6 +11011,11 @@ impl ApplicationHandler for Game<'_> {
                         self.pack_prompt_click()?;
                     }
                 }
+                WindowEvent::MouseInput { state, button, .. } if self.dialog_open() => {
+                    if state == ElementState::Pressed && button == MouseButton::Left {
+                        self.dialog_click()?;
+                    }
+                }
                 WindowEvent::MouseInput { .. } if self.screen == Screen::Win => {}
                 WindowEvent::MouseInput { state, button, .. } if self.screen == Screen::Options => {
                     if self.options_waiting_for_key() && state == ElementState::Pressed {
@@ -11210,6 +11223,13 @@ impl ApplicationHandler for Game<'_> {
                         self.answer_pack_prompt(false)?;
                     }
                 }
+                WindowEvent::KeyboardInput { event, .. } if self.dialog_open() => {
+                    if event.state == ElementState::Pressed
+                        && let PhysicalKey::Code(key) = event.physical_key
+                    {
+                        self.dialog_key(key)?
+                    }
+                }
                 WindowEvent::KeyboardInput { event, .. }
                     if self.screen == Screen::Chat && self.title.is_none() =>
                 {
@@ -11684,6 +11704,7 @@ impl<'a> Game<'a> {
             world_loader: None,
             pending_pack_reload: false,
             server_packs: Default::default(),
+            dialogs: Default::default(),
             world_renderer_ready: false,
             collision: res.collision(),
             motion: res.motion(),
diff --git a/crates/horizon-client/src/game/agent.rs b/crates/horizon-client/src/game/agent.rs
index f6b68aa74..dffa529b9 100644
--- a/crates/horizon-client/src/game/agent.rs
+++ b/crates/horizon-client/src/game/agent.rs
@@ -390,6 +390,9 @@ impl Game<'_> {
         Ok(())
     }
     pub(super) fn screen_label(&self) -> &'static str {
+        if self.dialog_open() {
+            return "dialog";
+        }
         if self.title.is_some() {
             return "title";
         }
@@ -483,6 +486,7 @@ impl Game<'_> {
             })
         });
         json!({
+            "dialog": self.dialog_status(),
             "screen": self.screen_label(),
             "menu": self.title.as_ref().map(|_| self.title_value()),
             "world": (self.title.is_none()).then(|| match &self.integrated {
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index 205a66074..adba0bc05 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -231,6 +231,13 @@ impl Game<'_> {
             "pad" => Ok(Some(self.pad_command(&words)?)),
             "key" => {
                 let key = key_code(arg(1)?).ok_or_else(|| format!("unknown key {}", words[1]))?;
+                // A server's dialog takes the keys, in configuration too.
+                if self.dialog_open() {
+                    if arg(2)? != "up" {
+                        self.dialog_key(key)?;
+                    }
+                    return ok();
+                }
                 self.require_world()?;
                 // The sign editor takes raw presses (Enter, arrows, Backspace, Escape).
                 if self.sign_edit.is_some() {
diff --git a/crates/horizon-client/src/game/dialogs.rs b/crates/horizon-client/src/game/dialogs.rs
new file mode 100644
index 000000000..28a7a7609
--- /dev/null
+++ b/crates/horizon-client/src/game/dialogs.rs
@@ -0,0 +1,450 @@
+//! A server's dialogs bound to the game (`ClientCommonPacketListenerImpl.
+//! showDialog` and `clearDialog`, `DialogScreen`, its `WarningScreen` and the
+//! `WaitingForResponseScreen`): the screen over whatever is open (the
+//! connecting screen in configuration), its inputs, and the actions its
+//! buttons send back.
+use super::Game;
+use horizon_client::{
+    Result,
+    confirm_screen::Confirm,
+    dialog::{AfterAction, Click, Dialog, InputValue},
+    dialog_screen::{Layout, Part, WARNING_SPRITES, waiting_button},
+    hud::{HudBatch, rgba},
+    text::Text,
+    ui,
+};
+use horizon_world::nbt::Tag;
+use std::time::Instant;
+use winit::keyboard::KeyCode;
+
+/// An open `DialogScreen`.
+struct Open {
+    dialog: Dialog,
+    values: Vec<InputValue>,
+    scroll: ui::Scroll,
+}
+
+/// The dialog screens a server can open.
+#[derive(Default)]
+pub(super) struct DialogState {
+    open: Option<Open>,
+    /// `WaitingForResponseScreen`, since when.
+    waiting: Option<Instant>,
+    /// `DialogScreen.WarningScreen`, over the dialog.
+    warning: bool,
+}
+
+fn warning_texts() -> (Text, Text, [Text; 2]) {
+    let t = |key: &str| Text::translate(key, &[]);
+    (
+        t("menu.custom_screen_info.title"),
+        t("menu.custom_screen_info.contents"),
+        [t("menu.disconnect"), t("gui.back")],
+    )
+}
+
+impl Game<'_> {
+    /// Whether a dialog screen takes the input.
+    pub(super) fn dialog_open(&self) -> bool {
+        let d = &self.dialogs;
+        d.open.is_some() || d.waiting.is_some() || d.warning
+    }
+
+    /// `showDialog`: the dialog replaces an open one (and a waiting screen);
+    /// under the warning screen, it is what Back returns to.
+    pub(super) fn show_dialog(&mut self, tag: &Tag) {
+        let Some(dialog) = Dialog::parse(tag) else {
+            log::warn!("Horizon: failed to show dialog for data {tag:?}");
+            return;
+        };
+        let values = dialog.inputs.iter().map(|i| i.control.initial()).collect();
+        self.dialogs.open = Some(Open {
+            dialog,
+            values,
+            scroll: ui::Scroll::default(),
+        });
+        self.dialogs.waiting = None;
+        self.capture(false);
+    }
+
+    /// `clearDialog`: the dialog closes (under the warning screen, Back then
+    /// returns to what was open before it).
+    pub(super) fn clear_dialog(&mut self) {
+        if self.dialogs.open.take().is_some() && !self.dialog_open() {
+            self.dialog_closed();
+        }
+    }
+
+    /// Every dialog screen goes (a disconnect, or the level loading screen).
+    pub(super) fn close_dialogs(&mut self) {
+        self.dialogs = DialogState::default();
+    }
+
+    fn dialog_closed(&mut self) {
+        if self.player.is_some() && self.screen == super::Screen::Playing && self.title.is_none() {
+            self.capture(true);
+        }
+    }
+
+    /// `DialogScreen.runAction`: the click event, then the screen the dialog's
+    /// `after_action` leaves.
+    fn run_dialog_action(&mut self, click: Option<Click>, after: AfterAction) -> Result<()> {
+        match after {
+            AfterAction::None => {}
+            AfterAction::Close => self.dialogs.open = None,
+            AfterAction::WaitForResponse => {
+                self.dialogs.open = None;
+                self.dialogs.waiting = Some(Instant::now());
+            }
+        }
+        match click {
+            Some(Click::Custom { id, payload }) => {
+                if let Some(r) = &self.remote {
+                    r.session.send_custom_click(&id, payload);
+                }
+            }
+            Some(Click::RunCommand(command)) => {
+                // In configuration there is nothing to run it (vanilla warns).
+                if self.player.is_some() {
+                    let command = command.strip_prefix('/').unwrap_or(&command);
+                    self.send_chat(&format!("/{command}"));
+                } else {
+                    log::warn!(
+                        "Horizon: commands are not supported in configuration, trying to run '{command}'"
+                    );
+                }
+            }
+            Some(Click::ShowDialog(dialog)) => self.show_dialog_ref(&dialog),
+            Some(Click::CopyToClipboard(value)) => {
+                use horizon_client::clipboard::Clipboard;
+                self.clipboard.set(&value);
+            }
+            Some(other) => log::info!("Horizon: dialog action {other:?} is not supported yet"),
+            None => {}
+        }
+        if !self.dialog_open() {
+            self.dialog_closed();
+        }
+        Ok(())
+    }
+
+    /// A `show_dialog` click event's dialog: a registry id or the dialog itself.
+    fn show_dialog_ref(&mut self, dialog: &Tag) {
+        match dialog {
+            Tag::String(id) => {
+                let id = id.to_string_lossy();
+                let name = if id.contains(':') {
+                    id.clone()
+                } else {
+                    format!("minecraft:{id}")
+                };
+                let found = self.remote.as_ref().and_then(|r| {
+                    let entries = r.registries.registries.get("minecraft:dialog")?;
+                    entries.iter().find(|(n, _)| *n == name)?.1.clone()
+                });
+                match found {
+                    Some(tag) => self.show_dialog(&tag),
+                    None => log::warn!("Horizon: unknown dialog {id}"),
+                }
+            }
+            tag => self.show_dialog(tag),
+        }
+    }
+
+    /// `ClientboundShowDialogPacket` in play: a registry entry or the dialog.
+    pub(super) fn show_play_dialog(
+        &mut self,
+        dialog: &horizon_protocol::packets::play::DialogHolder,
+    ) {
+        use horizon_protocol::packets::play::DialogHolder;
+        match dialog {
+            DialogHolder::Direct(tag) => self.show_dialog(tag),
+            DialogHolder::Registry(id) => {
+                let tag = self
+                    .remote
+                    .as_ref()
+                    .and_then(|r| r.registries.data("minecraft:dialog", *id).cloned());
+                match tag {
+                    Some(tag) => self.show_dialog(&tag),
+                    None => log::warn!("Horizon: unknown dialog {id}"),
+                }
+            }
+        }
+    }
+
+    fn dialog_layout(&self) -> Option<Layout> {
+        let open = self.dialogs.open.as_ref()?;
+        Some(Layout::new(
+            &open.dialog,
+            &self.gui.atlas.font,
+            self.gui_size(),
+        ))
+    }
+
+    pub(super) fn draw_dialog(&mut self, batch: &mut HudBatch) {
+        if !self.dialog_open() {
+            return;
+        }
+        let (w, h) = (batch.width, batch.height);
+        let cursor = self.cursor;
+        let atlas = &self.gui.atlas;
+        if self.player.is_none() {
+            // In place of the connecting screen, on its background.
+            batch.fill(atlas, 0.0, 0.0, w, h, rgba(20, 20, 20, 255));
+        }
+        ui::menu_background(batch, atlas, 0.0, 0.0, w, h, self.player.is_some());
+        if self.dialogs.warning {
+            let (title, message, [disconnect, back]) = warning_texts();
+            Confirm::new(&atlas.font, (w, h), &title, &message).draw(
+                batch,
+                atlas,
+                cursor,
+                [&disconnect, &back],
+            );
+            return;
+        }
+        if let Some(since) = self.dialogs.waiting {
+            // HeaderAndFooterLayout(33, 0) centred: the title, the button 33 below.
+            let ticks = (since.elapsed().as_millis() / 50) as u32;
+            let (label, visible, active) = waiting_button(ticks);
+            let title = Text::translate("gui.waitingForResponse.title", &[]);
+            let top = ((h - 53.0) / 2.0).trunc();
+            let tw = atlas.font.width_text(&title);
+            batch.text_styled(
+                atlas,
+                &title,
+                ((w - tw) / 2.0).trunc(),
+                top + 12.0,
+                u32::MAX,
+                true,
+            );
+            if visible {
+                let (bx, by) = (((w - 200.0) / 2.0).trunc(), top + 33.0);
+                let hover = ui::hovered(cursor, bx, by, 200.0, 20.0);
+                ui::button(batch, atlas, bx, by, 200.0, 20.0, &label, active, hover);
+            }
+            return;
+        }
+        let Some(layout) = self.dialog_layout() else {
+            return;
+        };
+        let Some(open) = self.dialogs.open.as_mut() else {
+            return;
+        };
+        let atlas = &self.gui.atlas;
+        let [ax, ay, aw, ah] = layout.area;
+        open.scroll.clamp(ay, ay + ah, layout.content);
+        batch.text_styled(
+            atlas,
+            &open.dialog.title,
+            layout.title.0,
+            layout.title.1,
+            u32::MAX,
+            true,
+        );
+        let [wx, wy, ww, wh] = layout.warning;
+        let warn_hover = ui::hovered(cursor, wx, wy, ww, wh);
+        horizon_client::widgets::record("warning", layout.warning, true);
+        batch.sprite_scaled(
+            atlas,
+            WARNING_SPRITES[if warn_hover { 2 } else { 0 }],
+            wx,
+            wy,
+            ww,
+            wh,
+            u32::MAX,
+        );
+        let buttons = open.dialog.buttons();
+        let in_area = |y: f32| y >= ay && y < ay + ah;
+        let mut tooltip = None;
+        let mut start = None;
+        for (part, clipped) in layout.placed(open.scroll.amount) {
+            if clipped && start.is_none() {
+                start = Some(batch.vertices.len());
+            } else if !clipped && let Some(s) = start.take() {
+                batch.clip_since(s, ax, ay, ax + aw, ay + ah);
+            }
+            match part {
+                Part::Line(text, x, y) => {
+                    batch.text_styled(atlas, &text, x, y, u32::MAX, true);
+                }
+                Part::Button { index, rect } => {
+                    let [x, y, bw, bh] = rect;
+                    let hover =
+                        (!clipped || in_area(cursor.1)) && ui::hovered(cursor, x, y, bw, bh);
+                    let b = buttons[index];
+                    ui::button(batch, atlas, x, y, bw, bh, &b.label, true, hover);
+                    if hover && let Some(t) = &b.tooltip {
+                        tooltip = Some(t.clone());
+                    }
+                }
+            }
+        }
+        if let Some(s) = start {
+            batch.clip_since(s, ax, ay, ax + aw, ay + ah);
+        }
+        if layout.content > ah {
+            ui::scrollbar(
+                batch,
+                atlas,
+                ax + aw - 6.0,
+                ay,
+                ay + ah,
+                layout.content,
+                open.scroll.amount,
+            );
+        }
+        if warn_hover {
+            tooltip = Some(Text::translate("menu.custom_screen_info.tooltip", &[]));
+        }
+        if let Some(t) = tooltip {
+            let lines: Vec<Text> = atlas
+                .font
+                .split_lines(&t, 170.0)
+                .into_iter()
+                .map(|l| l.0)
+                .collect();
+            ui::tooltip(batch, atlas, &lines, cursor);
+        }
+    }
+
+    /// A left click on a dialog screen.
+    pub(super) fn dialog_click(&mut self) -> Result<()> {
+        let cursor = self.cursor;
+        if self.dialogs.warning {
+            let (title, message, _) = warning_texts();
+            let answer = Confirm::new(&self.gui.atlas.font, self.gui_size(), &title, &message)
+                .answer_at(cursor);
+            match answer {
+                Some(true) => {
+                    self.audio.play_button_click();
+                    let reason = Text::translate("menu.custom_screen_info.disconnect", &[]);
+                    return self.leave_server(Some(reason.plain()));
+                }
+                Some(false) => {
+                    self.audio.play_button_click();
+                    self.dialogs.warning = false;
+                    if !self.dialog_open() {
+                        self.dialog_closed();
+                    }
+                }
+                None => {}
+            }
+            return Ok(());
+        }
+        if let Some(since) = self.dialogs.waiting {
+            let (w, h) = self.gui_size();
+            let active = waiting_button((since.elapsed().as_millis() / 50) as u32).2;
+            let (bx, by) = (
+                ((w - 200.0) / 2.0).trunc(),
+                ((h - 53.0) / 2.0).trunc() + 33.0,
+            );
+            if active && ui::hovered(cursor, bx, by, 200.0, 20.0) {
+                self.audio.play_button_click();
+                self.dialogs.waiting = None;
+                self.dialog_closed();
+            }
+            return Ok(());
+        }
+        let Some(layout) = self.dialog_layout() else {
+            return Ok(());
+        };
+        let [wx, wy, ww, wh] = layout.warning;
+        if ui::hovered(cursor, wx, wy, ww, wh) {
+            self.audio.play_button_click();
+            self.dialogs.warning = true;
+            return Ok(());
+        }
+        let Some(open) = self.dialogs.open.as_mut() else {
+            return Ok(());
+        };
+        let [_, ay, _, ah] = layout.area;
+        let mut action = None;
+        for (part, clipped) in layout.placed(open.scroll.amount) {
+            if clipped && !(cursor.1 >= ay && cursor.1 < ay + ah) {
+                continue;
+            }
+            match part {
+                Part::Button {
+                    index,
+                    rect: [x, y, w, h],
+                } if ui::hovered(cursor, x, y, w, h) => {
+                    action = Some(index);
+                }
+                _ => {}
+            }
+        }
+        let Some(index) = action else {
+            return Ok(());
+        };
+        self.audio.play_button_click();
+        let d = &open.dialog;
+        let click = d.buttons()[index]
+            .action
+            .as_ref()
+            .and_then(|a| a.click(&d.inputs, &open.values));
+        let after = d.after_action;
+        self.run_dialog_action(click, after)
+    }
+
+    /// The mouse wheel over a dialog: its body scrolls 10 a step.
+    pub(super) fn dialog_scroll(&mut self, delta: f32) {
+        let Some(layout) = self.dialog_layout() else {
+            return;
+        };
+        if let Some(open) = self.dialogs.open.as_mut() {
+            let [_, ay, _, ah] = layout.area;
+            open.scroll.wheel(delta, 10.0, ay, ay + ah, layout.content);
+        }
+    }
+
+    /// A key pressed on a dialog screen: Escape closes what allows it.
+    pub(super) fn dialog_key(&mut self, key: KeyCode) -> Result<()> {
+        let escape = key == KeyCode::Escape;
+        if self.dialogs.warning {
+            if escape {
+                self.dialogs.warning = false;
+                if !self.dialog_open() {
+                    self.dialog_closed();
+                }
+            }
+            return Ok(());
+        }
+        if let Some(since) = self.dialogs.waiting {
+            // shouldCloseOnEsc: once Back works.
+            if escape && waiting_button((since.elapsed().as_millis() / 50) as u32).2 {
+                self.dialogs.waiting = None;
+                self.dialog_closed();
+            }
+            return Ok(());
+        }
+        let Some(open) = self.dialogs.open.as_ref() else {
+            return Ok(());
+        };
+        if escape {
+            if !open.dialog.can_close_with_escape {
+                return Ok(());
+            }
+            // onClose: the cancel action, and the screen closes.
+            let d = &open.dialog;
+            let click = d.on_cancel().and_then(|a| a.click(&d.inputs, &open.values));
+            return self.run_dialog_action(click, AfterAction::Close);
+        }
+        Ok(())
+    }
+
+    /// What `state` reports: the open dialog and its values, or the waiting
+    /// and warning screens.
+    pub(super) fn dialog_status(&self) -> serde_json::Value {
+        let d = &self.dialogs;
+        let screen = if d.warning {
+            Some("warning")
+        } else if d.waiting.is_some() {
+            Some("waiting_for_response")
+        } else {
+            None
+        };
+        let open = d.open.as_ref().map(|open| open.dialog.json(&open.values));
+        serde_json::json!({ "open": open, "screen": screen })
+    }
+}
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index aa0490655..d9ed5bb12 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -468,6 +468,7 @@ impl Game<'_> {
             r.session.disconnect();
         }
         self.server_packs_disconnect();
+        self.close_dialogs();
         // Single player's server thread saves the world before the title shows.
         let single_player = match self.integrated.take() {
             Some(server) => {
@@ -829,6 +830,8 @@ impl Game<'_> {
                 } => {
                     self.set_registries(registries);
                     self.extras_joined();
+                    // handleLogin: the level loading screen replaces any dialog.
+                    self.close_dialogs();
                     if let Some(r) = self.remote.as_mut() {
                         r.joined = true;
                         r.profile = uuid;
@@ -844,6 +847,8 @@ impl Game<'_> {
                 Event::Reconfigured(registries) => self.set_registries(registries),
                 Event::PackPush(p) => self.handle_pack_push(p),
                 Event::PackPop(id) => self.handle_pack_pop(id),
+                Event::ShowDialog(dialog) => self.show_dialog(&dialog),
+                Event::ClearDialog => self.clear_dialog(),
                 Event::DecodeError(e) => {
                     if let Some(r) = self.remote.as_mut() {
                         r.decode_errors += 1;
@@ -2676,6 +2681,9 @@ impl Game<'_> {
             C::SetTitleText(p) => self.titles.set_title(remote_text(&p.text)),
             C::SetSubtitleText(p) => self.titles.set_subtitle(remote_text(&p.text)),
             C::SetTitlesAnimation(p) => self.titles.set_times(p.fade_in, p.stay, p.fade_out),
+            // ClientCommonPacketListenerImpl.handleShowDialog / handleClearDialog.
+            C::ShowDialog(p) => self.show_play_dialog(&p.dialog),
+            C::ClearDialog(_) => self.clear_dialog(),
             C::ClearTitles(p) => {
                 self.titles.clear();
                 if p.value {
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index ce48ce717..e712af780 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -54,6 +54,7 @@ pub mod debug_chart;
 pub mod debug_keys;
 pub mod debug_overlay;
 pub mod dialog;
+pub mod dialog_screen;
 pub mod dynamic_light;
 pub mod effects;
 pub mod enchant;
diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs
index 9cce9e1c6..4a43320f3 100644
--- a/crates/horizon-client/src/net.rs
+++ b/crates/horizon-client/src/net.rs
@@ -48,6 +48,10 @@ pub enum Event {
     PackPush(cfg::ResourcePackPush),
     /// ClientboundResourcePackPopPacket: one pack, or every pack.
     PackPop(Option<u128>),
+    /// `show_dialog` in configuration: the dialog itself.
+    ShowDialog(horizon_world::nbt::Tag),
+    /// `clear_dialog` in configuration.
+    ClearDialog,
     /// The connection ended. `from_server`: the server gave the reason (or
     /// the connection was refused for good), rather than the connection
     /// failing (auto-reconnect retries only failures and shutdowns).
@@ -189,6 +193,25 @@ impl Session {
             w.shutdown();
         }
     }
+    /// ServerboundCustomClickActionPacket (a dialog's answer), in whichever
+    /// phase the connection is.
+    pub fn send_custom_click(&self, id: &str, payload: Option<horizon_world::nbt::Tag>) {
+        let click = cfg::CustomClickAction {
+            id: id.to_owned(),
+            payload,
+        };
+        let mut writer = self.writer.lock().unwrap();
+        let body = if self.configuring.load(Ordering::Relaxed) {
+            cfg::Serverbound::CustomClickAction(click).encode()
+        } else {
+            play::Serverbound::CustomClickAction(click).encode()
+        };
+        if let Some(w) = writer.as_mut()
+            && w.send(&body).is_err()
+        {
+            w.shutdown();
+        }
+    }
     pub fn disconnect(&mut self) {
         if let Some(w) = self.writer.lock().unwrap().take() {
             w.shutdown();
@@ -524,6 +547,13 @@ fn configure(
             cfg::Clientbound::ResourcePackPop(p) => {
                 let _ = send.send(Event::PackPop(p.id));
             }
+            // The game shows it; the answer goes back from there.
+            cfg::Clientbound::ShowDialog(d) => {
+                let _ = send.send(Event::ShowDialog(d.dialog));
+            }
+            cfg::Clientbound::ClearDialog(_) => {
+                let _ = send.send(Event::ClearDialog);
+            }
             cfg::Clientbound::CookieRequest(q) => {
                 reply(cfg::Serverbound::CookieResponse(cfg::CookieResponse {
                     key: q.key,
diff --git a/tools/server_e2e.py b/tools/server_e2e.py
new file mode 100644
index 000000000..397e03549
--- /dev/null
+++ b/tools/server_e2e.py
@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Horizon's client on a vanilla 26.3 dedicated server, end to end.
+
+A vanilla server (the pinned server jar, offline mode, a flat world) and one Horizon game joined to it,
+driven by horizon-ctl. The server's console does what a server or its plugins do; the checks read what
+the game shows and what reaches the server (its console and, for custom click actions, its debug log).
+
+    python3 tools/server_e2e.py --bin-dir target/fast             # every check
+    python3 tools/server_e2e.py --bin-dir target/fast --check dialog
+
+Checks:
+- dialog: `/dialog show` with a multi-action dialog (a message, three buttons): the game shows it,
+          a command runs on the server (`trigger`), a custom action reaches it with its
+          payload (the server's "Received custom click action" line), `wait_for_response` leaves the
+          waiting screen, and `/dialog clear` closes a dialog (servers used to see nothing: the game
+          dropped the packets).
+
+The game runs with fresh HORIZON_HOME, launcher and XDG folders and without audio. Screenshots and both
+logs go to --out.
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lab  # noqa: E402
+import test_rust_parity as base  # noqa: E402
+from agent_control_e2e import Failed  # noqa: E402
+from lan_e2e import Game  # noqa: E402
+from test_dedicated_server_parity import Server  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+PLAYER = 'Steve'
+PROPERTIES = {
+    'online-mode': 'false',
+    'white-list': 'false',
+    'level-type': 'minecraft\\:flat',
+    'generate-structures': 'false',
+    'spawn-protection': '0',
+    'view-distance': '3',
+    'simulation-distance': '3',
+    'pause-when-empty-seconds': '-1',
+}
+# MinecraftServer.handleCustomClickAction logs at debug level: the console shows that logger's debug lines.
+LOG4J = """<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="WARN">
+  <Appenders><Console name="out" target="SYSTEM_OUT"><PatternLayout pattern="[%level] %msg%n"/></Console></Appenders>
+  <Loggers>
+    <Logger name="net.minecraft.server.MinecraftServer" level="debug"/>
+    <Root level="info"><AppenderRef ref="out"/></Root>
+  </Loggers>
+</Configuration>
+"""
+
+
+def snbt(value):
+    """A JSON value as SNBT (strings quoted, booleans as bytes)."""
+    if isinstance(value, bool):
+        return '1b' if value else '0b'
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, list):
+        return '[' + ','.join(snbt(v) for v in value) + ']'
+    if isinstance(value, dict):
+        return '{' + ','.join(f'{k}:{snbt(v)}' for k, v in value.items()) + '}'
+    return str(value)
+
+
+def check_dialog(server, game, out):
+    server.console('scoreboard objectives add answer trigger')
+    server.console(f'scoreboard players enable {PLAYER} answer')
+    dialog = {
+        'type': 'minecraft:multi_action',
+        'title': {'text': 'Sign in', 'color': 'gold'},
+        'body': {'type': 'minecraft:plain_message', 'contents': 'Pick a number.'},
+        'actions': [
+            {'label': 'Send', 'action': {'type': 'minecraft:run_command', 'command': 'trigger answer set 41'}},
+            {'label': 'Submit', 'action': {'type': 'minecraft:dynamic/custom', 'id': 'horizon:e2e',
+                                           'additions': {'tag': 'x'}}},
+            {'label': 'Wait', 'action': {'type': 'minecraft:dynamic/custom', 'id': 'horizon:wait'}},
+        ],
+        'after_action': 'none',
+        'pause': False,  # a pausing dialog must close after an action
+    }
+    shown = {}
+    server.console(f'dialog show {PLAYER} {snbt(dialog)}')
+    game.raw('wait-for', 'screen', 'dialog', '--timeout', 30)
+    state = game('state')
+    shown['shown'] = state['dialog']['open']
+    assert shown['shown']['title'] == 'Sign in', shown
+    assert shown['shown']['buttons'] == ['Send', 'Submit', 'Wait'], shown
+    game.shot(out, 'dialog')
+    game.raw('click', 'send')
+    time.sleep(1)
+    server.console(f'scoreboard players get {PLAYER} answer')
+    server.wait_for(rf'{PLAYER} has 41 \[answer\]', timeout=30)
+    shown['trigger'] = 41
+    # A custom action and its additions.
+    game.raw('click', 'submit')
+    server.wait_for(r'Received custom click action horizon:e2e with payload', timeout=30)
+    line = next(l for l in server.lines if 'horizon:e2e' in l)
+    shown['custom'] = line.split('payload ', 1)[1]
+    assert shown['custom'] == '{tag:"x"}', shown
+    # after_action none: still open. Then clear it.
+    assert game('state')['dialog']['open'], 'the dialog closed after an action with after_action none'
+    server.console(f'dialog clear {PLAYER}')
+    game.raw('wait-for', 'screen', 'playing', '--timeout', 30)
+    # wait_for_response: the waiting screen until the server answers (here, never).
+    server.console(f'dialog show {PLAYER} {snbt(dict(dialog, after_action="wait_for_response"))}')
+    game.raw('wait-for', 'screen', 'dialog', '--timeout', 30)
+    game.raw('click', 'wait')
+    server.wait_for(r'Received custom click action horizon:wait', timeout=30)
+    shown['waiting'] = game('state')['dialog']['screen']
+    game.shot(out, 'waiting')
+    assert shown['waiting'] == 'waiting_for_response', shown
+    # Its Back works after 5 s, and so does Escape (clear_dialog leaves it open, as in vanilla).
+    time.sleep(5.5)
+    game.raw('key', 'esc', 'tap')
+    game.raw('wait-for', 'screen', 'playing', '--timeout', 10)
+    return shown
+
+
+CHECKS = {'dialog': check_dialog}
+
+
+def run(bins, out, checks):
+    lock, jars, libraries = base.verify_artifacts()
+    work = Path(tempfile.mkdtemp(prefix='hz-server-e2e-'))
+    port = lab.free_port()
+    directory = work / 'server'
+    directory.mkdir()
+    props = dict(PROPERTIES, **{'server-port': str(port)})
+    (directory / 'server.properties').write_text(''.join(f'{k}={v}\n' for k, v in props.items()))
+    (directory / 'eula.txt').write_text('eula=true\n')
+    (work / 'log4j2.xml').write_text(LOG4J)
+    classpath = os.pathsep.join(map(str, [jars['server'], *libraries]))
+    server = Server(['java', '-Xmx2g', f'-Dlog4j.configurationFile={work / "log4j2.xml"}', '-cp', classpath,
+                     'net.minecraft.server.Main', 'nogui'], directory, 'vanilla')
+    game = Game('client', bins / 'horizon-ctl', lab.RESOURCES.resolve())
+    for key in ('XDG_DATA_HOME', 'XDG_CONFIG_HOME', 'HORIZON_LAUNCHER_HOME'):
+        game.d.env[key] = str(game.work / key.lower())
+    game.d.env['HORIZON_LAUNCHER_NO_SELF_UPDATE'] = '1'
+    results = {}
+    try:
+        server.wait_for(r'Done \(')
+        server.console('gamerule spawn_mobs false')
+        game('launch', wait=False, offscreen=sys.platform == 'darwin')
+        game.raw('connect', f'127.0.0.1:{port}', PLAYER)
+        game.raw('wait-for', 'loaded', '--timeout', 300)
+        server.wait_for(rf'{PLAYER} joined the game')
+        server.console(f'op {PLAYER}')
+        game.wait(20)
+        for name in checks:
+            try:
+                results[name] = {'pass': True, 'detail': CHECKS[name](server, game, out)}
+            except (Failed, AssertionError, StopIteration, KeyError) as e:
+                results[name] = {'pass': False, 'detail': repr(e)}
+            print(f'[server] {name}: {"PASS" if results[name]["pass"] else "FAIL"} {results[name]["detail"]}')
+    finally:
+        (out / 'client.log').write_text(game.close())
+        server.stop()
+        shutil.copy(server.log_path, out / 'server.log')
+        shutil.rmtree(game.work, ignore_errors=True)
+        shutil.rmtree(work, ignore_errors=True)
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument('--bin-dir', help='prebuilt horizon-client and horizon-ctl (default: build with the fast profile)')
+    parser.add_argument('--check', action='append', choices=list(CHECKS), help='run only these checks (repeatable)')
+    parser.add_argument('--out', default=str(ROOT / '.local/server-e2e'), help='screenshots and logs go here')
+    args = parser.parse_args()
+    if args.bin_dir:
+        bins = Path(args.bin_dir).resolve()
+    else:
+        subprocess.run(['cargo', 'build', '--locked', '--profile', 'fast', '-p', 'horizon-client', '--bins'],
+                       cwd=ROOT, check=True)
+        bins = ROOT / 'target/fast'
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    results = run(bins, out, args.check or list(CHECKS))
+    print(json.dumps(results, indent=1))
+    sys.exit(0 if results and all(r['pass'] for r in results.values()) else 1)
+
+
+if __name__ == '__main__':
+    main()

From 1fdb119587b9cec955f8c925de403ceb85c1cc2a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:30:04 +0100
Subject: [PATCH 022/270] Server menus keep their styled titles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A server's open_screen title is a text component, and container screens
draw it as AbstractContainerScreen does: in the label grey, under the
component's own colours, bold, italics and fonts, with the § codes a
literal holds. Horizon flattened it to a plain string, so a plugin's
gold and bold "Server Selector" menu showed in plain grey (#1645).
Chests, hoppers, dispensers, droppers, brewing stands and the other
workstations now draw the server's title. Before, the workstations
ignored it and showed their default name.

horizon-ctl's `screen` reports the title span by span (text, colour,
bold, italic). server_e2e's new `titles` check names a chest on the
vanilla server with a styled CustomName, opens it, and checks the title.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/agent.rs       | 12 ++++++
 crates/horizon-client/src/game/machines.rs    | 11 +++---
 crates/horizon-client/src/game/remote.rs      | 39 +++++++++----------
 .../src/game/remote_stations.rs               |  2 +-
 crates/horizon-client/src/game/stations.rs    | 26 +++++++------
 crates/horizon-client/src/game/storage.rs     |  8 ++--
 tools/server_e2e.py                           | 25 +++++++++++-
 7 files changed, 80 insertions(+), 43 deletions(-)

diff --git a/crates/horizon-client/src/game/agent.rs b/crates/horizon-client/src/game/agent.rs
index dffa529b9..753f3e096 100644
--- a/crates/horizon-client/src/game/agent.rs
+++ b/crates/horizon-client/src/game/agent.rs
@@ -684,6 +684,18 @@ impl Game<'_> {
             v["craft_size"] = json!(self.craft_size);
             v["station"] = json!(self.station.as_ref().map(|s| format!("{:?}", s.kind)));
             v["container"] = json!(self.container);
+            // The title a server gave the menu, span by span as it is drawn.
+            if let Some(title) = self.remote_menu_title() {
+                let spans = title.spans.iter().map(|s| {
+                    json!({
+                        "text": s.text,
+                        "color": s.style.color.map(|c| format!("#{c:06X}")),
+                        "bold": s.style.is_bold(),
+                        "italic": s.style.is_italic(),
+                    })
+                });
+                v["title"] = json!(spans.collect::<Vec<_>>());
+            }
             // The recipe book's buttons (GUI pixels): the book button, then
             // the recipe buttons of the page, page arrows, filter and tabs.
             let book = self.recipe_book_targets();
diff --git a/crates/horizon-client/src/game/machines.rs b/crates/horizon-client/src/game/machines.rs
index 8ce1940c9..1a53fcb7d 100644
--- a/crates/horizon-client/src/game/machines.rs
+++ b/crates/horizon-client/src/game/machines.rs
@@ -905,15 +905,16 @@ impl Game<'_> {
             batch.rect_uv(ox, oy, 176.0, height, r, u32::MAX);
         }
         let grey = horizon_client::hud::rgba(64, 64, 64, 255);
-        let title = &self
-            .remote_menu_title()
-            .unwrap_or_else(|| self.container_title(title.to_owned()));
+        let title = &self.remote_menu_title().unwrap_or_else(|| {
+            horizon_client::text::Text::literal(self.container_title(title.to_owned()))
+                .resolve_legacy()
+        });
         let title_x = if screen == Screen::Hopper {
             8.0
         } else {
-            (176.0 - horizon_client::hud::HudBatch::text_width(atlas, title)) / 2.0
+            (176.0 - atlas.font.width_text(title)) / 2.0
         };
-        batch.text(atlas, title, ox + title_x, oy + 6.0, grey, false);
+        batch.text_styled(atlas, title, ox + title_x, oy + 6.0, grey, false);
         batch.text(
             atlas,
             "Inventory",
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index d9ed5bb12..3b35d5679 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -58,6 +58,12 @@ fn remote_text(tag: &Tag) -> horizon_client::text::Text {
     comp_text(&tag_to_json(tag))
 }
 
+/// `ClientboundOpenScreenPacket.title` as a container screen draws it: the
+/// component's styles, and the `§` codes a literal holds (`StringDecomposer`).
+fn menu_title(tag: &Tag) -> horizon_client::text::Text {
+    remote_text(tag).resolve_legacy()
+}
+
 /// A section's sky and block light layers from the wire.
 type LightLayers = (Option<Vec<u8>>, Option<Vec<u8>>);
 
@@ -130,8 +136,8 @@ pub(super) struct Remote {
     predictions: HashMap<[i32; 3], (i32, i32)>,
     /// Open container: (window id, menu name).
     pub(super) menu: Option<(i32, String)>,
-    /// The open menu's title as the server named it.
-    pub(super) menu_title: Option<String>,
+    /// The open menu's title as the server named it, with its styles.
+    pub(super) menu_title: Option<horizon_client::text::Text>,
     state_id: i32,
     use_target: Option<[i32; 3]>,
     entities: HashMap<i32, Tracked>,
@@ -4782,14 +4788,7 @@ impl Game<'_> {
             return;
         }
         if let Some(kind) = Self::remote_station_kind(&menu) {
-            let title = plain(
-                &p.title,
-                &self
-                    .remote
-                    .as_ref()
-                    .map(|r| r.lang.clone())
-                    .unwrap_or_default(),
-            );
+            let title = menu_title(&p.title);
             let pos = target.map_or([0, 0, 0], |t| [t.0, t.1, t.2]);
             self.remote_open_station(p.container, menu, kind, title, pos);
             return;
@@ -4853,14 +4852,7 @@ impl Game<'_> {
                 return;
             }
         };
-        let title = plain(
-            &p.title,
-            &self
-                .remote
-                .as_ref()
-                .map(|r| r.lang.clone())
-                .unwrap_or_default(),
-        );
+        let title = menu_title(&p.title);
         if let Some(r) = self.remote.as_mut() {
             r.menu = Some((p.container, menu.clone()));
             r.menu_title = Some(title);
@@ -4904,11 +4896,11 @@ impl Game<'_> {
         Some(self.remote.as_ref()?.menu.as_ref()?.1.as_str())
     }
     /// The title the server gave the menu it opened.
-    pub(super) fn remote_menu_title(&self) -> Option<String> {
+    pub(super) fn remote_menu_title(&self) -> Option<horizon_client::text::Text> {
         self.remote.as_ref()?.menu_title.clone()
     }
     /// A server's chest-like menu (`MenuType.GENERIC_9xN`): its rows and title.
-    pub(super) fn remote_chest_menu(&self) -> Option<(usize, String)> {
+    pub(super) fn remote_chest_menu(&self) -> Option<(usize, horizon_client::text::Text)> {
         let r = self.remote.as_ref()?;
         let rows = r
             .menu
@@ -4917,7 +4909,12 @@ impl Game<'_> {
             .strip_prefix("minecraft:generic_9x")?
             .parse()
             .ok()?;
-        Some((rows, r.menu_title.clone().unwrap_or_default()))
+        Some((
+            rows,
+            r.menu_title
+                .clone()
+                .unwrap_or_else(horizon_client::text::Text::empty),
+        ))
     }
     /// ServerboundPlayerCommandPacket STOP_SLEEPING.
     pub(super) fn remote_stop_sleeping(&mut self) {
diff --git a/crates/horizon-client/src/game/remote_stations.rs b/crates/horizon-client/src/game/remote_stations.rs
index b46725345..5c532f7f5 100644
--- a/crates/horizon-client/src/game/remote_stations.rs
+++ b/crates/horizon-client/src/game/remote_stations.rs
@@ -18,7 +18,7 @@ impl Game<'_> {
         container: i32,
         menu: String,
         kind: Kind,
-        title: String,
+        title: horizon_client::text::Text,
         pos: [i32; 3],
     ) {
         if let Some(r) = self.remote.as_mut() {
diff --git a/crates/horizon-client/src/game/stations.rs b/crates/horizon-client/src/game/stations.rs
index ffe56d699..682f47508 100644
--- a/crates/horizon-client/src/game/stations.rs
+++ b/crates/horizon-client/src/game/stations.rs
@@ -11,6 +11,7 @@ use horizon_client::{
     hud::{HudBatch, rgba},
     items::ItemStack,
     stations::{self, AnvilResult, EnchantOffers},
+    text::Text,
 };
 use horizon_core::random::{LegacyRandom, RandomSource};
 
@@ -1164,15 +1165,15 @@ impl Game<'_> {
                 }
             }
             let default = self.translate("container.brewing", "Brewing Stand");
-            let title = self
-                .station
-                .as_ref()
-                .and_then(|s| self.world.block_names.get(&(s.pos[0], s.pos[1], s.pos[2])))
-                .cloned()
-                .or_else(|| self.remote_menu_title())
-                .unwrap_or(default);
-            let tw = HudBatch::text_width(atlas, &title);
-            batch.text(
+            let title = self.remote_menu_title().unwrap_or_else(|| {
+                let named = self
+                    .station
+                    .as_ref()
+                    .and_then(|s| self.world.block_names.get(&(s.pos[0], s.pos[1], s.pos[2])));
+                Text::literal(named.cloned().unwrap_or(default)).resolve_legacy()
+            });
+            let tw = atlas.font.width_text(&title);
+            batch.text_styled(
                 atlas,
                 &title,
                 ox + (176.0 - tw) / 2.0,
@@ -1199,7 +1200,10 @@ impl Game<'_> {
                 }
             }
         } else if let Some(kind) = self.station.as_ref().map(|s| s.kind) {
-            let title = self.translate(kind.title_key(), "");
+            // A server's menu has the title it was given.
+            let title = self
+                .remote_menu_title()
+                .unwrap_or_else(|| Text::literal(self.translate(kind.title_key(), "")));
             {
                 let atlas = &self.gui.atlas;
                 Self::part(
@@ -1211,7 +1215,7 @@ impl Game<'_> {
                     (ox, oy),
                 );
                 let (tx, ty) = kind.title_pos();
-                batch.text(atlas, &title, ox + tx, oy + ty, GREY, false);
+                batch.text_styled(atlas, &title, ox + tx, oy + ty, GREY, false);
                 batch.text(atlas, &inventory_label, ox + 8.0, oy + 72.0, GREY, false);
             }
             if kind == Kind::Cartography {
diff --git a/crates/horizon-client/src/game/storage.rs b/crates/horizon-client/src/game/storage.rs
index 9b28ce26b..cb8b57ee2 100644
--- a/crates/horizon-client/src/game/storage.rs
+++ b/crates/horizon-client/src/game/storage.rs
@@ -2,7 +2,7 @@
 //! kept in the dropped item's `container` component) and ender chests (the
 //! player's `PlayerEnderChestContainer`, saved as `EnderItems`).
 use super::Game;
-use horizon_client::{containers::BlockEntity, items::ItemStack};
+use horizon_client::{containers::BlockEntity, items::ItemStack, text::Text};
 
 pub(super) fn is_shulker_box(name: &str) -> bool {
     name.ends_with("shulker_box")
@@ -187,7 +187,7 @@ impl Game<'_> {
         generic.then(|| self.container_size() / 9)
     }
     /// The title of the open chest-like menu.
-    fn chest_title(&self, rows: usize) -> String {
+    fn chest_title(&self, rows: usize) -> Text {
         if let Some((_, title)) = self.remote_chest_menu() {
             return title;
         }
@@ -200,7 +200,7 @@ impl Game<'_> {
             _ if rows > 3 => ("container.chestDouble", "Large Chest"),
             _ => ("container.chest", "Chest"),
         };
-        self.container_title(self.translate(key, fallback))
+        Text::literal(self.container_title(self.translate(key, fallback))).resolve_legacy()
     }
     /// `ContainerScreen` / `ShulkerBoxScreen`: the background with its
     /// container rows, the title and the inventory label.
@@ -247,7 +247,7 @@ impl Game<'_> {
             r.u1 = r.u0 + 176.0 * du;
             batch.rect_uv(ox, oy + top, 176.0, 96.0, r, u32::MAX);
         }
-        batch.text(
+        batch.text_styled(
             atlas,
             &self.chest_title(rows),
             ox + 8.0,
diff --git a/tools/server_e2e.py b/tools/server_e2e.py
index 397e03549..ce09c519c 100644
--- a/tools/server_e2e.py
+++ b/tools/server_e2e.py
@@ -14,6 +14,8 @@ Checks:
           payload (the server's "Received custom click action" line), `wait_for_response` leaves the
           waiting screen, and `/dialog clear` closes a dialog (servers used to see nothing: the game
           dropped the packets).
+- titles: a chest named with styles (`CustomName`, as a plugin's menu is): its screen's title keeps
+          the colours and bold (it used to be flattened to plain grey).
 
 The game runs with fresh HORIZON_HOME, launcher and XDG folders and without audio. Screenshots and both
 logs go to --out.
@@ -126,7 +128,28 @@ def check_dialog(server, game, out):
     return shown
 
 
-CHECKS = {'dialog': check_dialog}
+def check_titles(server, game, out):
+    # AbstractContainerScreen draws the title the server sent, its styles included (#1645). A named
+    # chest is what a plugin's menu looks like: its CustomName is the open_screen title.
+    x, y, z = (int(v // 1) for v in game('state')['player']['position'])
+    chest = (x + 2, y, z)
+    name = [{'text': 'Server ', 'color': 'gold', 'bold': True}, {'text': 'Selector', 'color': 'aqua'}]
+    server.console(f'setblock {chest[0]} {chest[1]} {chest[2]} minecraft:chest{{CustomName:{snbt(name)}}}')
+    game.wait(10)
+    game.raw('interact', *chest)
+    game.raw('wait-for', 'screen', 'container', '--timeout', 30)
+    game.wait(5)
+    title = game('screen').get('title')
+    game.shot(out, 'titles')
+    game.raw('key', 'esc', 'tap')
+    # A list is its first component with the rest as its children: they inherit its bold.
+    want = [{'text': 'Server ', 'color': '#FFAA00', 'bold': True, 'italic': False},
+            {'text': 'Selector', 'color': '#55FFFF', 'bold': True, 'italic': False}]
+    assert title == want, title
+    return {'title': title}
+
+
+CHECKS = {'dialog': check_dialog, 'titles': check_titles}
 
 
 def run(bins, out, checks):

From 7d6583dc4d088d794398391aad4c0ced94009883 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:45:24 +0100
Subject: [PATCH 023/270] Shader packs, clean room 22: the sky
 (gbuffers_skybasic)

The pack's gbuffers_skybasic (or gbuffers_basic) draws vanilla's sky
geometry, as Horizon's own sky builds it: the disc at y 16, the sunset
fan while the sun is low, the stars and the void disc, each with its
render stage. One static vertex buffer; the frame's colours and rotations
sit in a small uniform the vertex inputs read. The sky draws after the
world copy and before terrain, at the far plane: only where nothing else
drew, without writing depth. It blends with the translucent default unless
blend.<program> says otherwise. Horizon's world pass then skips its own
sky disc, stars and void. The sun and moon stay Horizon's for now
(gbuffers_skytextured is next): the pack's sky covers them.

load_post takes the game's inputs per geometry (GameInputs);
GbuffersInputs gains statements run after the pack's main.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
2.1, 2.3, 5.4; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/shader_packs.rs   |   4 +-
 crates/horizon-client/src/gfx.rs              |  46 +++-
 crates/horizon-client/src/gfx/pack_atlas.rs   |   1 +
 crates/horizon-client/src/gfx/pack_post.rs    | 157 +++++++++---
 crates/horizon-client/src/gfx/pack_sky.rs     | 229 ++++++++++++++++++
 crates/horizon-shaders/src/lib.rs             |   3 +-
 crates/horizon-shaders/src/post.rs            |  88 +++++--
 crates/horizon-shaders/src/translate/mod.rs   |   6 +-
 .../tests/packs/terrain-test/README.md        |   4 +-
 .../shaders/gbuffers_skybasic.fsh             |  15 ++
 .../shaders/gbuffers_skybasic.vsh             |   8 +
 crates/horizon-shaders/tests/real_packs.rs    |  16 +-
 12 files changed, 502 insertions(+), 75 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_sky.rs
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.fsh
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.vsh

diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index d819eddef..360262640 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -42,8 +42,8 @@ impl Game<'_> {
                         );
                     }
                     let folder = dimension_folder(&pack, dimension);
-                    let terrain = renderer.pack_terrain_inputs();
-                    let post = load_post(&pack, &folder, &properties, &macros, terrain.as_ref());
+                    let inputs = renderer.pack_inputs();
+                    let post = load_post(&pack, &folder, &properties, &macros, &inputs);
                     if let Some((programs, notes)) = renderer.set_shader_pack(dimension, Some(post))
                     {
                         for note in notes {
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 354dc8d07..7444b136a 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -71,6 +71,7 @@ mod occlusion;
 mod pack_atlas;
 mod pack_draw;
 mod pack_post;
+mod pack_sky;
 mod pack_timing;
 pub mod pack_uniforms;
 mod page_runs;
@@ -88,6 +89,19 @@ const COMPLETE_COLUMN: u32 = (1 << (crate::chunk::HEIGHT / 16)) - 1;
 /// its fixed-point UVs (`terrain.wgsl`'s `terrain_uv`).
 /// The world pass again after occlusion culling's test: it loads both
 /// targets (phase 2 draws over phase 1, reading the test's results).
+/// LevelRenderer: no sky inside lava or powder snow (sky fog ends within 2 blocks).
+fn sky_open(frame: &Frame) -> bool {
+    match frame.fog {
+        Some(f) => f.sky_end > 2.0,
+        None => !frame.underwater,
+    }
+}
+
+/// The Overworld-style sky (disc, sunset, stars, void) draws this frame.
+fn sky_visible(frame: &Frame) -> bool {
+    !frame.title && frame.skybox && sky_open(frame)
+}
+
 fn world_pass_after_culling<'e>(
     encoder: &'e mut wgpu::CommandEncoder,
     view: &wgpu::TextureView,
@@ -2777,6 +2791,7 @@ impl Renderer {
                 terrain: self.pack_atlas.as_ref().map(|_| pack_post::Geometry {
                     buffers: if flat { &buffers[..1] } else { &buffers },
                     table: self.flat.as_ref().filter(|_| flat).map(|f| &f.draw_layout),
+                    depth_write: true,
                 }),
             };
             pack_post::PackPost::new(
@@ -2794,9 +2809,16 @@ impl Renderer {
         self.pack_post = Some((dimension, post));
         report
     }
-    /// What a shader pack's terrain program reads from Horizon's terrain vertices, in the
-    /// pack's block atlas (made here when missing); `None` when the atlas does not fit.
-    pub fn pack_terrain_inputs(&mut self) -> Option<horizon_shaders::GbuffersInputs> {
+    /// What a shader pack's gbuffers programs read from Horizon's geometry: the sky's, and
+    /// terrain's in the pack's block atlas (made here when missing; none when it does not fit).
+    pub fn pack_inputs(&mut self) -> horizon_shaders::GameInputs {
+        horizon_shaders::GameInputs {
+            terrain: self.pack_terrain_inputs(),
+            sky: Some(pack_sky::inputs()),
+        }
+    }
+
+    fn pack_terrain_inputs(&mut self) -> Option<horizon_shaders::GbuffersInputs> {
         if self.pack_atlas.is_none() {
             let mut encoder = self.device.create_command_encoder(&Default::default());
             let layers = self
@@ -3711,6 +3733,12 @@ impl Renderer {
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
         // The pack's program reads the vertices this frame's draws bind.
         let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
+        let pack_draws_sky = pack_post
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_sky());
         let pack_draws_water = pack_draws_terrain
             && self
                 .pack_post
@@ -3770,13 +3798,9 @@ impl Renderer {
                 ..Default::default()
             });
             pass.set_bind_group(0, &self.group, &[]);
-            // LevelRenderer: no sky inside lava or powder snow (sky fog ends within 2 blocks).
-            let sky_visible = match frame.fog {
-                Some(f) => f.sky_end > 2.0,
-                None => !frame.underwater,
-            };
+            let sky_visible = sky_open(frame);
             if frame.title || (sky_visible && (frame.skybox || frame.end_sky)) {
-                if !frame.title && frame.skybox {
+                if !frame.title && frame.skybox && !pack_draws_sky {
                     pass.set_pipeline(&self.sky);
                     pass.draw(0..3, 0..1);
                 }
@@ -3796,11 +3820,11 @@ impl Renderer {
                     }
                     pass.set_bind_group(0, &self.group, &[]);
                 }
-                if !frame.title && frame.stars.is_some() {
+                if !frame.title && frame.stars.is_some() && !pack_draws_sky {
                     self.stars.draw(&mut pass);
                     pass.set_bind_group(0, &self.group, &[]);
                 }
-                if !frame.title && frame.dark_disc {
+                if !frame.title && frame.dark_disc && !pack_draws_sky {
                     pass.set_pipeline(&self.dark_disc);
                     pass.draw(0..3, 0..1);
                 }
diff --git a/crates/horizon-client/src/gfx/pack_atlas.rs b/crates/horizon-client/src/gfx/pack_atlas.rs
index 011dff379..1a14a8da9 100644
--- a/crates/horizon-client/src/gfx/pack_atlas.rs
+++ b/crates/horizon-client/src/gfx/pack_atlas.rs
@@ -173,6 +173,7 @@ impl PackAtlas {
                 .iter()
                 .map(|&(n, v)| (n.to_owned(), v.to_owned()))
                 .collect(),
+            after: String::new(),
         }
     }
 }
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 08a2dedcc..2334b84c9 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -16,6 +16,7 @@ use std::collections::HashMap;
 use horizon_shaders::{Format, Group, Kind, Post, Val};
 
 use super::pack_draw::DrawUniforms;
+use super::pack_sky::PackSky;
 use super::pack_uniforms::{self, FrameUniforms, PackInputs};
 
 const BUFFERS: usize = horizon_shaders::BUFFERS;
@@ -120,6 +121,14 @@ fn share_samplers(module: &mut naga::Module, slot: &HashMap<u32, u32>) {
     }
 }
 
+/// The game's geometry a gbuffers pass draws.
+#[derive(Clone, Copy, PartialEq)]
+enum Gbuffers {
+    Sky,
+    Terrain,
+    Water,
+}
+
 struct Pass {
     name: String,
     group: Group,
@@ -181,6 +190,8 @@ pub struct PackPost {
     terrain: Option<Pass>,
     /// What draws translucent terrain (`gbuffers_water` or its fallback), after `deferred`.
     water: Option<Pass>,
+    /// What draws the sky (`gbuffers_skybasic` or its fallback), before terrain, and its vertices.
+    sky: Option<(Pass, PackSky)>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -481,6 +492,8 @@ fn attach(
 pub(super) struct Geometry<'a> {
     pub buffers: &'a [Option<wgpu::VertexBufferLayout<'a>>],
     pub table: Option<&'a wgpu::BindGroupLayout>,
+    /// Writes depth (the sky does not).
+    pub depth_write: bool,
 }
 
 /// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
@@ -664,9 +677,9 @@ fn build_pass(
                 buffers: geometry.map_or(&[], |g| g.buffers),
             },
             primitive: Default::default(),
-            depth_stencil: geometry.map(|_| wgpu::DepthStencilState {
+            depth_stencil: geometry.map(|g| wgpu::DepthStencilState {
                 format: wgpu::TextureFormat::Depth32Float,
-                depth_write_enabled: Some(true),
+                depth_write_enabled: Some(g.depth_write),
                 depth_compare: Some(wgpu::CompareFunction::LessEqual),
                 stencil: Default::default(),
                 bias: Default::default(),
@@ -783,6 +796,15 @@ impl PackPost {
             .water
             .zip(world.terrain.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
+        let sky = post.sky.and_then(|p| {
+            let sky = PackSky::new(device);
+            let geometry = Geometry {
+                buffers: &PackSky::buffers(),
+                table: Some(&sky.layout),
+                depth_write: false,
+            };
+            Some((build(p, Some(&geometry))?, sky))
+        });
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
@@ -797,6 +819,9 @@ impl PackPost {
         if let Some(w) = &water {
             notes.push(format!("translucent terrain draws with {}", w.name));
         }
+        if let Some((s, _)) = &sky {
+            notes.push(format!("the sky draws with {}", s.name));
+        }
         let depth1 = water.is_some()
             && passes
                 .iter()
@@ -810,8 +835,10 @@ impl PackPost {
             let bit = 1u16 << b;
             let touched = |p: &&Pass| (p.reads | p.flip | p.written) & bit != 0;
             // Gbuffers passes cover part of their targets: a clear is needed if they touch it.
-            let first = terrain
+            let first = sky
                 .iter()
+                .map(|s| &s.0)
+                .chain(&terrain)
                 .chain(&water)
                 .find(touched)
                 .map(|_| true)
@@ -826,6 +853,7 @@ impl PackPost {
         // Terrain tests against the world's depth (entities...), so the blit copies it then.
         let blit_depth = terrain.is_some()
             || water.is_some()
+            || sky.is_some()
             || passes.iter().any(|p| {
                 p.samplers
                     .iter()
@@ -920,6 +948,7 @@ impl PackPost {
             passes,
             terrain,
             water,
+            sky,
             depth1,
             mipped,
             mips_valid: 0,
@@ -1084,25 +1113,34 @@ impl PackPost {
         group.clone()
     }
 
-    /// Terrain (or, `translucent`, translucent terrain) with the pack's program into the
-    /// buffers it writes, in place, tested against the world's depth; `draw` issues the
-    /// game's draws.
-    fn draw_terrain(
+    /// The sky, terrain or translucent terrain with the pack's program into the buffers it
+    /// writes, in place, tested against the world's depth; `draw` issues the game's terrain
+    /// draws (`true`: translucent), the sky draws itself.
+    #[allow(clippy::too_many_arguments)]
+    fn draw_gbuffers(
         &mut self,
         device: &wgpu::Device,
         queue: &wgpu::Queue,
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
-        translucent: bool,
+        frame: &super::Frame,
+        which: Gbuffers,
         draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
     ) {
-        let slot = if translucent {
-            &mut self.water
-        } else {
-            &mut self.terrain
-        };
-        let Some(mut pass) = slot.take() else {
-            return;
+        let translucent = which == Gbuffers::Water;
+        let (mut pass, sky) = match which {
+            Gbuffers::Sky => match self.sky.take() {
+                Some((pass, sky)) => (pass, Some(sky)),
+                None => return,
+            },
+            Gbuffers::Terrain => match self.terrain.take() {
+                Some(pass) => (pass, None),
+                None => return,
+            },
+            Gbuffers::Water => match self.water.take() {
+                Some(pass) => (pass, None),
+                None => return,
+            },
         };
         if translucent
             && let Some(t) = &self.targets
@@ -1148,24 +1186,58 @@ impl PackPost {
             });
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
-            if pass.draw {
-                let stage = if translucent {
-                    "TERRAIN_TRANSLUCENT"
-                } else {
-                    "TERRAIN_SOLID"
-                };
-                self.draws.bind(&mut rp, stage);
+            let draws = pass.draw.then_some(&self.draws);
+            match &sky {
+                Some(sky) => sky.draw(queue, &mut rp, frame, &|rp, stage| {
+                    if let Some(d) = draws {
+                        d.bind(rp, stage);
+                    }
+                }),
+                None => {
+                    if let Some(d) = draws {
+                        let stage = if translucent {
+                            "TERRAIN_TRANSLUCENT"
+                        } else {
+                            "TERRAIN_SOLID"
+                        };
+                        d.bind(&mut rp, stage);
+                    }
+                    draw(&mut rp, translucent);
+                }
             }
-            draw(&mut rp, translucent);
         }
         self.mips_valid &= !pass.written;
-        if translucent {
-            self.water = Some(pass);
-        } else {
-            self.terrain = Some(pass);
+        match (which, sky) {
+            (Gbuffers::Sky, Some(sky)) => self.sky = Some((pass, sky)),
+            (Gbuffers::Water, _) => self.water = Some(pass),
+            _ => self.terrain = Some(pass),
         }
     }
 
+    /// The sky, when it shows, then terrain.
+    fn draw_opaque(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        frame: &super::Frame,
+        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
+    ) {
+        if super::sky_visible(frame) {
+            self.draw_gbuffers(device, queue, encoder, size, frame, Gbuffers::Sky, terrain);
+        }
+        self.draw_gbuffers(
+            device,
+            queue,
+            encoder,
+            size,
+            frame,
+            Gbuffers::Terrain,
+            terrain,
+        );
+    }
+
     /// Regenerates the mip chain of buffer `b`'s side that programs read.
     fn mipmap(&self, encoder: &mut wgpu::CommandEncoder, b: usize) {
         let (Some(targets), Some((pipeline, _))) = (&self.targets, self.down.get(&self.formats[b]))
@@ -1197,6 +1269,11 @@ impl PackPost {
         self.terrain.is_some()
     }
 
+    /// Whether the pack draws the sky itself.
+    pub fn has_sky(&self) -> bool {
+        self.sky.is_some()
+    }
+
     /// Whether the pack draws translucent terrain itself.
     pub fn has_water(&self) -> bool {
         self.water.is_some()
@@ -1435,16 +1512,24 @@ impl PackPost {
         let mut passes = std::mem::take(&mut self.passes);
         let mut seen = (false, false);
         let mut shown = false;
-        let mut terrain_drawn = self.terrain.is_none();
+        let mut terrain_drawn = self.terrain.is_none() && self.sky.is_none();
         let mut water_drawn = self.water.is_none();
         for pass in &mut passes {
             if !terrain_drawn && pass.group != Group::Prepare {
                 terrain_drawn = true;
-                self.draw_terrain(device, queue, encoder, size, false, terrain);
+                self.draw_opaque(device, queue, encoder, size, frame, terrain);
             }
             if !water_drawn && matches!(pass.group, Group::Composite | Group::Final) {
                 water_drawn = true;
-                self.draw_terrain(device, queue, encoder, size, true, terrain);
+                self.draw_gbuffers(
+                    device,
+                    queue,
+                    encoder,
+                    size,
+                    frame,
+                    Gbuffers::Water,
+                    terrain,
+                );
             }
             if pass.group == Group::Deferred && !seen.0 {
                 seen.0 = true;
@@ -1496,10 +1581,18 @@ impl PackPost {
         }
         self.passes = passes;
         if !terrain_drawn {
-            self.draw_terrain(device, queue, encoder, size, false, terrain);
+            self.draw_opaque(device, queue, encoder, size, frame, terrain);
         }
         if !water_drawn {
-            self.draw_terrain(device, queue, encoder, size, true, terrain);
+            self.draw_gbuffers(
+                device,
+                queue,
+                encoder,
+                size,
+                frame,
+                Gbuffers::Water,
+                terrain,
+            );
         }
         let targets = self.targets.as_ref().expect("resized");
         let view = |m: u16, i: usize, alt: bool| {
diff --git a/crates/horizon-client/src/gfx/pack_sky.rs b/crates/horizon-client/src/gfx/pack_sky.rs
new file mode 100644
index 000000000..cd99d03b9
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_sky.rs
@@ -0,0 +1,229 @@
+//! The vanilla sky's geometry for a shader pack's `gbuffers_skybasic` (spec 2.3): the sky disc,
+//! the sunset fan, the stars and the void disc, as Horizon's own sky draws them (terrain.wgsl,
+//! stars.rs), built once into a vertex buffer. The frame's colours and rotations sit in a small
+//! uniform (set 1) that the vertex inputs read.
+
+use std::ops::Range;
+
+use wgpu::util::DeviceExt;
+
+/// A sky vertex: a position and what it belongs to (`SKY`...).
+#[repr(C)]
+#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
+struct Vertex {
+    pos: [f32; 3],
+    kind: u32,
+}
+
+const SKY: u32 = 0;
+const SUNSET_APEX: u32 = 1;
+/// Rim of the sunset fan: `pos.xy` is (sin, cos) of its angle.
+const SUNSET_RIM: u32 = 2;
+const STAR: u32 = 3;
+const VOID: u32 = 4;
+
+/// The frame's sky (std140).
+#[repr(C)]
+#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
+struct Uniform {
+    /// Camera-relative world from star space.
+    stars: [[f32; 4]; 4],
+    /// Sky colour, alpha 1.
+    color: [f32; 4],
+    /// Sunset colour and alpha.
+    sunrise: [f32; 4],
+    /// cos and sin of the sunset fan's turn, star brightness.
+    sun: [f32; 4],
+}
+
+pub(super) const ATTRIBUTES: [wgpu::VertexAttribute; 2] =
+    wgpu::vertex_attr_array![0 => Float32x3, 1 => Uint32];
+
+/// What `gbuffers_skybasic` reads from these vertices.
+pub fn inputs() -> horizon_shaders::GbuffersInputs {
+    let declarations =
+        "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in uint hz_v_kind;\n\
+         layout(set = 1, binding = 0) uniform HzSky { mat4 hz_sky_stars; vec4 hz_sky_color; \
+         vec4 hz_sky_sunrise; vec4 hz_sky_sun; };\n"
+            .to_owned();
+    let body = format!(
+        "    vec3 hz_p = hz_v_pos;\n    \
+         hz_Color = hz_sky_color;\n    \
+         if (hz_v_kind == {SUNSET_APEX}u || hz_v_kind == {SUNSET_RIM}u) {{\n        \
+             vec3 hz_l = vec3(0.0, 100.0, 0.0);\n        \
+             hz_Color = hz_sky_sunrise;\n        \
+             if (hz_v_kind == {SUNSET_RIM}u) {{\n            \
+                 hz_l = vec3(hz_v_pos.xy * 120.0, -hz_v_pos.y * 40.0 * hz_sky_sunrise.a);\n            \
+                 hz_Color.a = 0.0;\n        \
+             }}\n        \
+             vec3 hz_r = vec3(hz_l.x * hz_sky_sun.x - hz_l.y * hz_sky_sun.y, hz_l.x * hz_sky_sun.y + hz_l.y * hz_sky_sun.x, hz_l.z);\n        \
+             hz_p = vec3(hz_r.x, -hz_r.z, hz_r.y);\n    \
+         }} else if (hz_v_kind == {STAR}u) {{\n        \
+             hz_p = (hz_sky_stars * vec4(hz_v_pos, 1.0)).xyz;\n        \
+             hz_Color = vec4(hz_sky_sun.z);\n    \
+         }} else if (hz_v_kind == {VOID}u) {{\n        \
+             hz_Color = vec4(0.0, 0.0, 0.0, 1.0);\n    \
+         }}\n    \
+         hz_Vertex = vec4(hz_p, 1.0);\n    \
+         hz_MultiTexCoord0 = vec4(0.0, 0.0, 0.0, 1.0);\n    \
+         hz_MultiTexCoord1 = vec4(0.0, 240.0, 0.0, 1.0);\n    \
+         hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+         hz_Normal = vec3(0.0, 1.0, 0.0);\n"
+    );
+    horizon_shaders::GbuffersInputs {
+        declarations,
+        body,
+        attributes: vec![
+            ("vaPosition".into(), "hz_Vertex.xyz".into()),
+            ("vaColor".into(), "hz_Color".into()),
+            ("vaNormal".into(), "hz_Normal".into()),
+        ],
+        // At the far plane: the sky shows only where nothing else drew, and it writes no depth.
+        after: "    gl_Position.z = gl_Position.w;\n".into(),
+    }
+}
+
+/// A disc fan at height `y`, radius 512, as triangles (SkyRenderer's sky and void discs).
+fn disc(y: f32, kind: u32, out: &mut Vec<Vertex>) {
+    let sign = y.signum();
+    let rim = |i: i32| {
+        let a = (i as f32).to_radians();
+        Vertex {
+            pos: [sign * 512.0 * a.cos(), y, 512.0 * a.sin()],
+            kind,
+        }
+    };
+    let centre = Vertex {
+        pos: [0.0, y, 0.0],
+        kind,
+    };
+    for i in (-180..180).step_by(45) {
+        out.extend([centre, rim(i), rim(i + 45)]);
+    }
+}
+
+pub(super) struct PackSky {
+    vertices: wgpu::Buffer,
+    uniform: wgpu::Buffer,
+    pub layout: wgpu::BindGroupLayout,
+    group: wgpu::BindGroup,
+    /// Vertex ranges of the sky disc, the sunset fan, the stars and the void.
+    ranges: [Range<u32>; 4],
+}
+
+impl PackSky {
+    pub fn new(device: &wgpu::Device) -> Self {
+        let mut v = Vec::new();
+        disc(16.0, SKY, &mut v);
+        let sky = 0..v.len() as u32;
+        let apex = Vertex {
+            pos: [0.0; 3],
+            kind: SUNSET_APEX,
+        };
+        let rim = |i: u32| {
+            let a = i as f32 * std::f32::consts::TAU / 16.0;
+            Vertex {
+                pos: [a.sin(), a.cos(), 0.0],
+                kind: SUNSET_RIM,
+            }
+        };
+        for i in 0..16 {
+            v.extend([apex, rim(i), rim(i + 1)]);
+        }
+        let sunset = sky.end..v.len() as u32;
+        v.extend(
+            super::stars::star_triangles()
+                .into_iter()
+                .map(|pos| Vertex { pos, kind: STAR }),
+        );
+        let stars = sunset.end..v.len() as u32;
+        disc(-4.0, VOID, &mut v);
+        let void = stars.end..v.len() as u32;
+        let vertices = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
+            label: Some("Shader pack sky"),
+            contents: bytemuck::cast_slice(&v),
+            usage: wgpu::BufferUsages::VERTEX,
+        });
+        let uniform = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack sky"),
+            size: std::mem::size_of::<Uniform>() as u64,
+            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("Shader pack sky"),
+            entries: &[wgpu::BindGroupLayoutEntry {
+                binding: 0,
+                visibility: wgpu::ShaderStages::VERTEX,
+                ty: wgpu::BindingType::Buffer {
+                    ty: wgpu::BufferBindingType::Uniform,
+                    has_dynamic_offset: false,
+                    min_binding_size: None,
+                },
+                count: None,
+            }],
+        });
+        let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+            label: Some("Shader pack sky"),
+            layout: &layout,
+            entries: &[wgpu::BindGroupEntry {
+                binding: 0,
+                resource: uniform.as_entire_binding(),
+            }],
+        });
+        Self {
+            vertices,
+            uniform,
+            layout,
+            group,
+            ranges: [sky, sunset, stars, void],
+        }
+    }
+
+    pub fn buffers() -> [Option<wgpu::VertexBufferLayout<'static>>; 1] {
+        [Some(wgpu::VertexBufferLayout {
+            array_stride: std::mem::size_of::<Vertex>() as u64,
+            step_mode: wgpu::VertexStepMode::Vertex,
+            attributes: &ATTRIBUTES,
+        })]
+    }
+
+    /// Draws the frame's sky, each part with its render stage: the disc, the sunset fan while
+    /// the sun is near the horizon, the stars and, with the camera low, the void.
+    pub fn draw(
+        &self,
+        queue: &wgpu::Queue,
+        pass: &mut wgpu::RenderPass<'_>,
+        frame: &super::Frame,
+        stage: &dyn Fn(&mut wgpu::RenderPass<'_>, &str),
+    ) {
+        let sun_angle = frame.sky.sun_angle.to_radians();
+        // The fan turns to the other horizon in the afternoon (terrain.wgsl's sunrise_weight).
+        let flip = if sun_angle.sin() < 0.0 { 180f32 } else { 0.0 };
+        let theta = (flip + 90.0).to_radians();
+        let (rotation, brightness) = frame.stars.unwrap_or_default();
+        let [r, g, b] = frame.sky.sky_color;
+        let uniform = Uniform {
+            stars: rotation.to_cols_array_2d(),
+            color: [r, g, b, 1.0],
+            sunrise: frame.sky.sunrise_color,
+            sun: [theta.cos(), theta.sin(), brightness.clamp(0.0, 1.0), 0.0],
+        };
+        queue.write_buffer(&self.uniform, 0, bytemuck::bytes_of(&uniform));
+        pass.set_bind_group(1, &self.group, &[]);
+        pass.set_vertex_buffer(0, self.vertices.slice(..));
+        let [sky, sunset, stars, void] = self.ranges.clone();
+        let parts = [
+            ("SKY", sky, true),
+            ("SUNSET", sunset, frame.sky.sunrise_color[3] > 0.001),
+            ("STARS", stars, frame.stars.is_some()),
+            ("VOID", void, frame.dark_disc),
+        ];
+        for (name, range, shown) in parts {
+            if shown {
+                stage(pass, name);
+                pass.draw(range, 0..1);
+            }
+        }
+    }
+}
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index bed86758e..853f2f2ba 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -34,7 +34,8 @@ pub use macros::{MC_VERSION, Macros, RENDER_STAGES, render_stage};
 pub use options::switches_on;
 pub use pack::{Pack, PackError};
 pub use post::{
-    Blend, Factor, Group, Post, PostProgram, TRANSLUCENT_BLEND, dimension_folder, load_post,
+    Blend, Factor, GameInputs, Group, Post, PostProgram, TRANSLUCENT_BLEND, dimension_folder,
+    load_post,
 };
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index e155cefbe..56303e67b 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -93,6 +93,9 @@ const TERRAIN: [&str; 4] = [
     "gbuffers_basic",
 ];
 
+/// `gbuffers_skybasic` and its fallback (2.3).
+const SKY: [&str; 2] = ["gbuffers_skybasic", "gbuffers_basic"];
+
 const GROUPS: [(Group, &str); 4] = [
     (Group::Prepare, "prepare"),
     (Group::Deferred, "deferred"),
@@ -127,6 +130,8 @@ pub struct Post {
     pub terrain: Option<PostProgram>,
     /// What draws translucent terrain (water, stained glass) after deferred.
     pub water: Option<PostProgram>,
+    /// What draws the sky (disc, sunset, stars, void) before terrain.
+    pub sky: Option<PostProgram>,
     /// The custom uniforms of `shaders.properties` (3.4).
     pub custom: Custom,
     pub config: Config,
@@ -145,14 +150,22 @@ pub fn dimension_folder(pack: &Pack, id: i32) -> String {
     }
 }
 
-/// Loads the post-processing programs of `folder` and, given the game's terrain vertices, the
-/// program terrain draws with.
+/// The game's geometry a pack may draw with its gbuffers programs: each kind's vertex inputs,
+/// when the game can draw it with a pack.
+#[derive(Clone, Debug, Default)]
+pub struct GameInputs {
+    pub terrain: Option<GbuffersInputs>,
+    pub sky: Option<GbuffersInputs>,
+}
+
+/// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
+/// gbuffers programs it draws with.
 pub fn load_post(
     pack: &Pack,
     folder: &str,
     properties: &Properties,
     macros: &Macros,
-    terrain: Option<&GbuffersInputs>,
+    inputs: &GameInputs,
 ) -> Post {
     let mut post = Post {
         folder: folder.to_owned(),
@@ -161,6 +174,7 @@ pub fn load_post(
         composite_pre: flips(properties, "composite_pre"),
         terrain: None,
         water: None,
+        sky: None,
         custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
@@ -191,17 +205,26 @@ pub fn load_post(
             }
         }
     }
-    if let Some(inputs) = terrain {
-        let mut gbuffers = |names: &[&str], group| {
-            names.iter().find_map(|name| {
-                loader.load(name.to_string(), group, |v, f| {
-                    translate_gbuffers(v, f, Target::Buffers, inputs)
-                })
+    let mut gbuffers = |names: &[&str], group, inputs: &GbuffersInputs| {
+        names.iter().find_map(|name| {
+            loader.load(name.to_string(), group, |v, f| {
+                translate_gbuffers(v, f, Target::Buffers, inputs)
             })
-        };
-        let terrain = gbuffers(&TERRAIN, Group::Gbuffers);
+        })
+    };
+    // The sky blends as vanilla draws its sunset fan and stars unless `blend.*` says otherwise.
+    let sky = inputs
+        .sky
+        .as_ref()
+        .and_then(|i| gbuffers(&SKY, Group::Gbuffers, i));
+    let sky = sky.map(|mut p| {
+        p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
+        p
+    });
+    if let Some(inputs) = &inputs.terrain {
+        let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
-        let water = gbuffers(&WATER, Group::Translucent);
+        let water = gbuffers(&WATER, Group::Translucent, inputs);
         loader.post.terrain = terrain;
         loader.post.water = water.map(|mut p| {
             p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
@@ -211,6 +234,7 @@ pub fn load_post(
             p.blend = blend(properties, &p.name).flatten();
         }
     }
+    loader.post.sky = sky;
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
@@ -433,7 +457,13 @@ mod tests {
         );
         assert_eq!(dimension_folder(&pack, 0), "");
         assert_eq!(dimension_folder(&pack, -1), "world-1");
-        let post = load_post(&pack, "", &properties, &Macros::standard(), None);
+        let post = load_post(
+            &pack,
+            "",
+            &properties,
+            &Macros::standard(),
+            &GameInputs::default(),
+        );
         let names: Vec<&str> = post.programs.iter().map(|p| p.name.as_str()).collect();
         assert_eq!(names, ["deferred", "composite", "composite2", "final"]);
         let p = &post.programs;
@@ -454,14 +484,21 @@ mod tests {
 
         let mut macros = Macros::standard();
         macros.define("HQ", "");
-        let post = load_post(&pack, "world-1", &properties, &macros, None);
+        let post = load_post(
+            &pack,
+            "world-1",
+            &properties,
+            &macros,
+            &GameInputs::default(),
+        );
         let names: Vec<&str> = post.programs.iter().map(|p| p.name.as_str()).collect();
         assert_eq!(names, ["final"]);
-        let post = load_post(&pack, "", &properties, &macros, None);
+        let post = load_post(&pack, "", &properties, &macros, &GameInputs::default());
         assert!(post.programs.iter().any(|p| p.name == "composite3"));
     }
 
-    /// Water falls back to the terrain chain and blends by default; `blend.*` overrides.
+    /// Water falls back to the terrain chain and blends by default, as the sky does; `blend.*`
+    /// overrides.
     #[test]
     fn water_falls_back_to_terrain_and_blends() {
         let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/packs/terrain-test");
@@ -470,12 +507,25 @@ mod tests {
         let inputs = crate::GbuffersInputs {
             declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
             body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n    hz_Color = vec4(1.0);\n".into(),
-            attributes: Vec::new(),
+            ..Default::default()
         };
-        let post = load_post(&pack, "", &Properties::default(), &macros, Some(&inputs));
+        let inputs = GameInputs {
+            terrain: Some(inputs.clone()),
+            sky: Some(inputs),
+        };
+        let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
         assert_eq!((terrain.group, terrain.blend), (Group::Gbuffers, None));
         assert_eq!(water.name, "gbuffers_terrain");
+        let sky = post.sky.unwrap();
+        assert_eq!(
+            (sky.name.as_str(), sky.group, sky.blend),
+            (
+                "gbuffers_skybasic",
+                Group::Gbuffers,
+                Some(TRANSLUCENT_BLEND)
+            )
+        );
         assert_eq!(
             (water.group, water.blend),
             (Group::Translucent, Some(TRANSLUCENT_BLEND))
@@ -504,7 +554,7 @@ mod tests {
             &dimension_folder(&pack, 0),
             &properties,
             &macros,
-            None,
+            &GameInputs::default(),
         );
         assert!(post.notes.is_empty(), "{:?}", post.notes);
         let names: Vec<&str> = post.programs.iter().map(|p| p.name.as_str()).collect();
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index fe736e4d8..35475ddab 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -109,6 +109,8 @@ pub struct GbuffersInputs {
     /// The value of each attribute a pack may declare (`mc_Entity`, `vaPosition`...), as a GLSL
     /// expression of the declared type's size; an attribute not listed reads zero.
     pub attributes: Vec<(String, String)>,
+    /// GLSL statements run last in `main`, with `gl_Position` in wgpu's clip space.
+    pub after: String,
 }
 
 /// Translates a composite-style program (`composite`, `deferred`, `final`...).
@@ -292,7 +294,8 @@ fn translate(
     }
     write!(
         vertex_main,
-        "    hz_main();\n    gl_Position = vec4(gl_Position.x, {flip}gl_Position.y, (gl_Position.z + gl_Position.w) * 0.5, gl_Position.w);\n}}\n"
+        "    hz_main();\n    gl_Position = vec4(gl_Position.x, {flip}gl_Position.y, (gl_Position.z + gl_Position.w) * 0.5, gl_Position.w);\n{}}}\n",
+        gbuffers.map_or("", |g| &g.after)
     )
     .unwrap();
     let mut fragment_main = String::from("\nvoid main() {\n");
@@ -597,6 +600,7 @@ mod tests {
                    hz_MultiTexCoord1 = vec4(240.0, 240.0, 0.0, 1.0);\n    hz_Color = vec4(1.0);\n    hz_Normal = vec3(0.0, 1.0, 0.0);\n"
                 .into(),
             attributes: vec![("mc_midTexCoord".into(), "vec2(game_uv) / 32768.0".into())],
+            ..Default::default()
         };
         let p = translate_gbuffers(
             &preprocess(&pack, "gbuffers_terrain.vsh", &m),
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/README.md b/crates/horizon-shaders/tests/packs/terrain-test/README.md
index bb8ddd060..3fc37bf4d 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/README.md
+++ b/crates/horizon-shaders/tests/packs/terrain-test/README.md
@@ -3,6 +3,8 @@
 Horizon's own shader pack for testing gbuffers terrain (written for Horizon, no other pack's code).
 `gbuffers_terrain` draws blocks from the atlas with their vertex colour and lightmap, tinted by
 the lightmap coordinate's sky light (cooler where the sky is hidden); `mc_midTexCoord` marks each
-face's centre with a dot. `composite` puts the depth buffer's view-space distance into the blue
+face's centre with a dot, and any stage but solid terrain (translucent terrain falls back to it)
+is red. `gbuffers_skybasic` draws the sky in its vertex colour, a little greener, with magenta
+stars and a dark red void. `composite` puts the depth buffer's view-space distance into the blue
 channel of the far half. Copy the folder into `shaderpacks/` and run the game with
 `HORIZON_SHADER_PACK=terrain-test`.
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.fsh
new file mode 100644
index 000000000..8d62f3291
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.fsh
@@ -0,0 +1,15 @@
+#version 120
+
+uniform int renderStage;
+
+varying vec4 glcolor;
+
+void main() {
+    vec4 color = glcolor;
+    // Stars magenta, the void dark red, the sky disc a little greener: each stage is told apart.
+    if (renderStage == MC_RENDER_STAGE_STARS) color.rgb = vec3(1.0, 0.0, 1.0);
+    if (renderStage == MC_RENDER_STAGE_VOID) color.rgb = vec3(0.3, 0.0, 0.0);
+    if (renderStage == MC_RENDER_STAGE_SKY) color.g = min(color.g + 0.2, 1.0);
+    /* DRAWBUFFERS:0 */
+    gl_FragData[0] = color;
+}
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.vsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.vsh
new file mode 100644
index 000000000..7b3bd59ce
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_skybasic.vsh
@@ -0,0 +1,8 @@
+#version 120
+
+varying vec4 glcolor;
+
+void main() {
+    gl_Position = ftransform();
+    glcolor = gl_Color;
+}
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index c5d4defac..a04a31b15 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -167,19 +167,19 @@ fn real_packs_read() {
                 declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
                 body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n    hz_Color = vec4(1.0);\n".into(),
                 attributes: vec![("mc_Entity".into(), "vec4(-1.0)".into())],
+                ..Default::default()
             };
-            let post = load_post(
-                &pack,
-                &folder,
-                &shaders,
-                &Macros::standard(),
-                Some(&terrain),
-            );
+            let inputs = horizon_shaders::GameInputs {
+                terrain: Some(terrain.clone()),
+                sky: Some(terrain),
+            };
+            let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
                 post.terrain.as_ref().map(|t| &t.name),
                 post.water.as_ref().map(|t| &t.name),
+                post.sky.as_ref().map(|t| &t.name),
                 post.notes.len() + post.config.notes.len(),
                 start.elapsed().as_secs_f64() * 1000.0
             );

From 230730d1f5324ed3fc7a658e384767f6d706e713 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 04:02:13 +0100
Subject: [PATCH 024/270] Shader packs, clean room 23: the sun and moon
 (gbuffers_skytextured)

gbuffers_skytextured (or gbuffers_textured, gbuffers_basic) draws the
frame's sun and moon quads, with their render stages, `texture` reading
the shared atlas their sprites live in. The sky's parts draw in vanilla's
order (disc, sunset, sun, moon, stars, void), in one render pass while
consecutive programs write the same buffers. The sun and moon add to the
sky (SRC_ALPHA, ONE) unless blend.<program> says otherwise. Horizon's
world pass skips its own sun and moon when the pack draws them; a part
without a program stays Horizon's.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
2.3, 5.4; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              |  15 +-
 crates/horizon-client/src/gfx/pack_post.rs    | 298 +++++++++++-------
 crates/horizon-client/src/gfx/pack_sky.rs     | 136 ++++++--
 crates/horizon-shaders/src/lib.rs             |   4 +-
 crates/horizon-shaders/src/post.rs            |  35 +-
 .../tests/packs/terrain-test/README.md        |   3 +-
 .../shaders/gbuffers_textured.fsh             |  15 +
 .../shaders/gbuffers_textured.vsh             |  10 +
 crates/horizon-shaders/tests/real_packs.rs    |   6 +-
 9 files changed, 370 insertions(+), 152 deletions(-)
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.fsh
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.vsh

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 7444b136a..bdd8250b8 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2792,7 +2792,13 @@ impl Renderer {
                     buffers: if flat { &buffers[..1] } else { &buffers },
                     table: self.flat.as_ref().filter(|_| flat).map(|f| &f.draw_layout),
                     depth_write: true,
+                    atlas: None,
                 }),
+                celestial: self
+                    .hud
+                    .atlas_texture
+                    .as_ref()
+                    .map(|t| t.create_view(&Default::default())),
             };
             pack_post::PackPost::new(
                 &self.device,
@@ -2815,6 +2821,7 @@ impl Renderer {
         horizon_shaders::GameInputs {
             terrain: self.pack_terrain_inputs(),
             sky: Some(pack_sky::inputs()),
+            celestial: Some(pack_sky::celestial_inputs()),
         }
     }
 
@@ -3739,6 +3746,12 @@ impl Renderer {
                 .as_ref()
                 .and_then(|p| p.1.as_ref())
                 .is_some_and(|p| p.has_sky());
+        let pack_draws_celestial = pack_post
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_celestial());
         let pack_draws_water = pack_draws_terrain
             && self
                 .pack_post
@@ -3814,7 +3827,7 @@ impl Renderer {
                     if frame.end_sky {
                         self.end_sky.draw(&mut pass);
                     }
-                    if celestial_vertices > 0 {
+                    if celestial_vertices > 0 && !pack_draws_celestial {
                         pass.set_vertex_buffer(0, self.celestial_buffer.slice(..));
                         pass.draw_indexed(0..(celestial_vertices as u32 / 4) * 6, 0, 0..1);
                     }
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 2334b84c9..9002ad963 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -121,12 +121,13 @@ fn share_samplers(module: &mut naga::Module, slot: &HashMap<u32, u32>) {
     }
 }
 
-/// The game's geometry a gbuffers pass draws.
-#[derive(Clone, Copy, PartialEq)]
-enum Gbuffers {
-    Sky,
-    Terrain,
-    Water,
+/// The sky's geometry and the programs that draw it: `gbuffers_skybasic` (disc, sunset, stars,
+/// void) and `gbuffers_skytextured` (sun, moon), each with its fallbacks. A part without a
+/// program is Horizon's own.
+struct Sky {
+    geometry: PackSky,
+    basic: Option<Pass>,
+    textured: Option<Pass>,
 }
 
 struct Pass {
@@ -151,6 +152,8 @@ struct Pass {
     mipmaps: u16,
     /// Reads the per-draw block (`DrawUniforms`).
     draw: bool,
+    /// What `texture` reads instead of the block atlas.
+    atlas: Option<wgpu::TextureView>,
     groups: HashMap<u16, wgpu::BindGroup>,
 }
 
@@ -181,6 +184,8 @@ pub(super) struct World<'a> {
     pub lightmap: wgpu::TextureView,
     /// Terrain's geometry, when the pack draws it.
     pub terrain: Option<Geometry<'a>>,
+    /// The atlas of the sun and moon's sprites.
+    pub celestial: Option<wgpu::TextureView>,
 }
 
 pub struct PackPost {
@@ -191,7 +196,7 @@ pub struct PackPost {
     /// What draws translucent terrain (`gbuffers_water` or its fallback), after `deferred`.
     water: Option<Pass>,
     /// What draws the sky (`gbuffers_skybasic` or its fallback), before terrain, and its vertices.
-    sky: Option<(Pass, PackSky)>,
+    sky: Option<Sky>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -494,6 +499,8 @@ pub(super) struct Geometry<'a> {
     pub table: Option<&'a wgpu::BindGroupLayout>,
     /// Writes depth (the sky does not).
     pub depth_write: bool,
+    /// What `texture` reads instead of the block atlas.
+    pub atlas: Option<wgpu::TextureView>,
 }
 
 /// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
@@ -737,6 +744,7 @@ fn build_pass(
         written,
         mipmaps: p.mipmaps,
         draw,
+        atlas: geometry.and_then(|g| g.atlas.clone()),
         groups: HashMap::new(),
     })
 }
@@ -796,15 +804,29 @@ impl PackPost {
             .water
             .zip(world.terrain.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
-        let sky = post.sky.and_then(|p| {
-            let sky = PackSky::new(device);
-            let geometry = Geometry {
+        let sky = (post.sky.is_some() || post.sky_textured.is_some()).then(|| {
+            let geometry = PackSky::new(device);
+            let basic = Geometry {
                 buffers: &PackSky::buffers(),
-                table: Some(&sky.layout),
+                table: Some(&geometry.layout),
                 depth_write: false,
+                atlas: None,
             };
-            Some((build(p, Some(&geometry))?, sky))
+            let basic = post.sky.and_then(|p| build(p, Some(&basic)));
+            let textured = Geometry {
+                buffers: &PackSky::celestial_buffers(),
+                table: None,
+                depth_write: false,
+                atlas: world.celestial.clone(),
+            };
+            let textured = post.sky_textured.and_then(|p| build(p, Some(&textured)));
+            Sky {
+                geometry,
+                basic,
+                textured,
+            }
         });
+        let sky = sky.filter(|s| s.basic.is_some() || s.textured.is_some());
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
@@ -819,8 +841,13 @@ impl PackPost {
         if let Some(w) = &water {
             notes.push(format!("translucent terrain draws with {}", w.name));
         }
-        if let Some((s, _)) = &sky {
-            notes.push(format!("the sky draws with {}", s.name));
+        for (part, pass) in sky
+            .iter()
+            .flat_map(|s| [("sky", &s.basic), ("sun and moon", &s.textured)])
+        {
+            if let Some(p) = pass {
+                notes.push(format!("the {part} draw with {}", p.name));
+            }
         }
         let depth1 = water.is_some()
             && passes
@@ -837,7 +864,7 @@ impl PackPost {
             // Gbuffers passes cover part of their targets: a clear is needed if they touch it.
             let first = sky
                 .iter()
-                .map(|s| &s.0)
+                .flat_map(|s| s.basic.iter().chain(&s.textured))
                 .chain(&terrain)
                 .chain(&water)
                 .find(touched)
@@ -1083,7 +1110,11 @@ impl PackPost {
                     Source::Noise => &self.noise,
                     Source::Dummy => &self.dummy,
                     Source::Shadow => &self.shadow.0,
-                    Source::Atlas => self.atlas.as_ref().unwrap_or(&self.dummy),
+                    Source::Atlas => pass
+                        .atlas
+                        .as_ref()
+                        .or(self.atlas.as_ref())
+                        .unwrap_or(&self.dummy),
                     Source::Lightmap => &self.lightmap,
                 };
                 let sampler = match SamplerKind::of(s.source, s.filtering) {
@@ -1113,46 +1144,12 @@ impl PackPost {
         group.clone()
     }
 
-    /// The sky, terrain or translucent terrain with the pack's program into the buffers it
-    /// writes, in place, tested against the world's depth; `draw` issues the game's terrain
-    /// draws (`true`: translucent), the sky draws itself.
-    #[allow(clippy::too_many_arguments)]
-    fn draw_gbuffers(
+    /// A render pass into the buffers `pass` writes, in place, tested against the world's depth.
+    fn begin<'e>(
         &mut self,
-        device: &wgpu::Device,
-        queue: &wgpu::Queue,
-        encoder: &mut wgpu::CommandEncoder,
-        size: [u32; 2],
-        frame: &super::Frame,
-        which: Gbuffers,
-        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
-    ) {
-        let translucent = which == Gbuffers::Water;
-        let (mut pass, sky) = match which {
-            Gbuffers::Sky => match self.sky.take() {
-                Some((pass, sky)) => (pass, Some(sky)),
-                None => return,
-            },
-            Gbuffers::Terrain => match self.terrain.take() {
-                Some(pass) => (pass, None),
-                None => return,
-            },
-            Gbuffers::Water => match self.water.take() {
-                Some(pass) => (pass, None),
-                None => return,
-            },
-        };
-        if translucent
-            && let Some(t) = &self.targets
-            && let Some((copy, _)) = &t.depth1
-        {
-            encoder.copy_texture_to_texture(
-                t.depth_texture.as_image_copy(),
-                copy.as_image_copy(),
-                t.depth_texture.size(),
-            );
-        }
-        let group = self.bind(device, queue, &mut pass, size);
+        encoder: &'e mut wgpu::CommandEncoder,
+        pass: &Pass,
+    ) -> wgpu::RenderPass<'e> {
         let targets = self.targets.as_ref().expect("resized");
         let load = wgpu::Operations {
             load: wgpu::LoadOp::Load,
@@ -1168,52 +1165,128 @@ impl PackPost {
                 .as_ref()
                 .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load));
         }
-        {
-            let timestamp_writes = self.timing.as_mut().and_then(|t| t.writes(&pass.name));
-            let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
-                label: Some(&pass.name),
-                color_attachments: &attachments,
-                timestamp_writes,
-                depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
-                    view: &targets.depth,
-                    depth_ops: Some(wgpu::Operations {
-                        load: wgpu::LoadOp::Load,
-                        store: wgpu::StoreOp::Store,
-                    }),
-                    stencil_ops: None,
+        let timestamp_writes = self.timing.as_mut().and_then(|t| t.writes(&pass.name));
+        encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: Some(&pass.name),
+            color_attachments: &attachments,
+            timestamp_writes,
+            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
+                view: &targets.depth,
+                depth_ops: Some(wgpu::Operations {
+                    load: wgpu::LoadOp::Load,
+                    store: wgpu::StoreOp::Store,
                 }),
-                ..Default::default()
-            });
+                stencil_ops: None,
+            }),
+            ..Default::default()
+        })
+    }
+
+    /// Terrain (or, `translucent`, translucent terrain) with the pack's program; `draw` issues
+    /// the game's draws.
+    fn draw_terrain(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        translucent: bool,
+        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
+    ) {
+        let slot = if translucent {
+            &mut self.water
+        } else {
+            &mut self.terrain
+        };
+        let Some(mut pass) = slot.take() else {
+            return;
+        };
+        if translucent
+            && let Some(t) = &self.targets
+            && let Some((copy, _)) = &t.depth1
+        {
+            encoder.copy_texture_to_texture(
+                t.depth_texture.as_image_copy(),
+                copy.as_image_copy(),
+                t.depth_texture.size(),
+            );
+        }
+        let group = self.bind(device, queue, &mut pass, size);
+        {
+            let mut rp = self.begin(encoder, &pass);
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
-            let draws = pass.draw.then_some(&self.draws);
-            match &sky {
-                Some(sky) => sky.draw(queue, &mut rp, frame, &|rp, stage| {
-                    if let Some(d) = draws {
-                        d.bind(rp, stage);
-                    }
-                }),
-                None => {
-                    if let Some(d) = draws {
-                        let stage = if translucent {
-                            "TERRAIN_TRANSLUCENT"
-                        } else {
-                            "TERRAIN_SOLID"
-                        };
-                        d.bind(&mut rp, stage);
-                    }
-                    draw(&mut rp, translucent);
-                }
+            if pass.draw {
+                let stage = if translucent {
+                    "TERRAIN_TRANSLUCENT"
+                } else {
+                    "TERRAIN_SOLID"
+                };
+                self.draws.bind(&mut rp, stage);
             }
+            draw(&mut rp, translucent);
         }
         self.mips_valid &= !pass.written;
-        match (which, sky) {
-            (Gbuffers::Sky, Some(sky)) => self.sky = Some((pass, sky)),
-            (Gbuffers::Water, _) => self.water = Some(pass),
-            _ => self.terrain = Some(pass),
+        if translucent {
+            self.water = Some(pass);
+        } else {
+            self.terrain = Some(pass);
         }
     }
 
+    /// The sky's parts in vanilla's order, each with the program that draws it; one render pass
+    /// while consecutive programs write the same buffers.
+    fn draw_sky(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        frame: &super::Frame,
+    ) {
+        let Some(mut sky) = self.sky.take() else {
+            return;
+        };
+        let parts = sky.geometry.prepare(queue, frame);
+        let mut groups = [None, None];
+        for (i, pass) in [&mut sky.basic, &mut sky.textured].into_iter().enumerate() {
+            if let Some(pass) = pass {
+                groups[i] = Some(self.bind(device, queue, pass, size));
+                self.mips_valid &= !pass.written;
+            }
+        }
+        let passes = [&sky.basic, &sky.textured];
+        let mut open: Option<(wgpu::RenderPass<'_>, usize)> = None;
+        for part in parts {
+            let i = usize::from(part.textured);
+            let (Some(pass), Some(group)) = (passes[i], &groups[i]) else {
+                continue;
+            };
+            let current = open.as_ref().map(|o| o.1);
+            if current != Some(i) {
+                let same = current
+                    .and_then(|c| passes[c].as_ref())
+                    .is_some_and(|p| p.writes == pass.writes);
+                if !same {
+                    drop(open.take());
+                    open = Some((self.begin(encoder, pass).forget_lifetime(), i));
+                }
+                let rp = &mut open.as_mut().expect("open").0;
+                rp.set_pipeline(&pass.pipeline);
+                rp.set_bind_group(0, group, &[]);
+                sky.geometry.bind(rp, part.textured);
+                open.as_mut().expect("open").1 = i;
+            }
+            let rp = &mut open.as_mut().expect("open").0;
+            if pass.draw {
+                self.draws.bind(rp, part.stage);
+            }
+            rp.draw(part.range, 0..1);
+        }
+        drop(open);
+        self.sky = Some(sky);
+    }
+
     /// The sky, when it shows, then terrain.
     fn draw_opaque(
         &mut self,
@@ -1225,17 +1298,9 @@ impl PackPost {
         terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
     ) {
         if super::sky_visible(frame) {
-            self.draw_gbuffers(device, queue, encoder, size, frame, Gbuffers::Sky, terrain);
+            self.draw_sky(device, queue, encoder, size, frame);
         }
-        self.draw_gbuffers(
-            device,
-            queue,
-            encoder,
-            size,
-            frame,
-            Gbuffers::Terrain,
-            terrain,
-        );
+        self.draw_terrain(device, queue, encoder, size, false, terrain);
     }
 
     /// Regenerates the mip chain of buffer `b`'s side that programs read.
@@ -1269,9 +1334,14 @@ impl PackPost {
         self.terrain.is_some()
     }
 
-    /// Whether the pack draws the sky itself.
+    /// Whether the pack draws the sky (disc, sunset, stars, void) itself.
     pub fn has_sky(&self) -> bool {
-        self.sky.is_some()
+        self.sky.as_ref().is_some_and(|s| s.basic.is_some())
+    }
+
+    /// Whether the pack draws the sun and moon itself.
+    pub fn has_celestial(&self) -> bool {
+        self.sky.as_ref().is_some_and(|s| s.textured.is_some())
     }
 
     /// Whether the pack draws translucent terrain itself.
@@ -1521,15 +1591,7 @@ impl PackPost {
             }
             if !water_drawn && matches!(pass.group, Group::Composite | Group::Final) {
                 water_drawn = true;
-                self.draw_gbuffers(
-                    device,
-                    queue,
-                    encoder,
-                    size,
-                    frame,
-                    Gbuffers::Water,
-                    terrain,
-                );
+                self.draw_terrain(device, queue, encoder, size, true, terrain);
             }
             if pass.group == Group::Deferred && !seen.0 {
                 seen.0 = true;
@@ -1584,15 +1646,7 @@ impl PackPost {
             self.draw_opaque(device, queue, encoder, size, frame, terrain);
         }
         if !water_drawn {
-            self.draw_gbuffers(
-                device,
-                queue,
-                encoder,
-                size,
-                frame,
-                Gbuffers::Water,
-                terrain,
-            );
+            self.draw_terrain(device, queue, encoder, size, true, terrain);
         }
         let targets = self.targets.as_ref().expect("resized");
         let view = |m: u16, i: usize, alt: bool| {
diff --git a/crates/horizon-client/src/gfx/pack_sky.rs b/crates/horizon-client/src/gfx/pack_sky.rs
index cd99d03b9..007fdc034 100644
--- a/crates/horizon-client/src/gfx/pack_sky.rs
+++ b/crates/horizon-client/src/gfx/pack_sky.rs
@@ -1,7 +1,8 @@
 //! The vanilla sky's geometry for a shader pack's `gbuffers_skybasic` (spec 2.3): the sky disc,
 //! the sunset fan, the stars and the void disc, as Horizon's own sky draws them (terrain.wgsl,
 //! stars.rs), built once into a vertex buffer. The frame's colours and rotations sit in a small
-//! uniform (set 1) that the vertex inputs read.
+//! uniform (set 1) that the vertex inputs read. `gbuffers_skytextured` draws the frame's sun and
+//! moon quads, textured from the shared atlas.
 
 use std::ops::Range;
 
@@ -36,6 +37,21 @@ struct Uniform {
     sun: [f32; 4],
 }
 
+/// A sun or moon vertex: position, atlas UV, RGBA8 colour.
+#[repr(C)]
+#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
+struct Celestial {
+    pos: [f32; 3],
+    uv: [f32; 2],
+    color: u32,
+}
+
+/// Quads of the sun and moon (and room to spare).
+const CELESTIAL_QUADS: usize = 4;
+
+const CELESTIAL_ATTRIBUTES: [wgpu::VertexAttribute; 3] =
+    wgpu::vertex_attr_array![0 => Float32x3, 1 => Float32x2, 2 => Unorm8x4];
+
 pub(super) const ATTRIBUTES: [wgpu::VertexAttribute; 2] =
     wgpu::vertex_attr_array![0 => Float32x3, 1 => Uint32];
 
@@ -83,6 +99,37 @@ pub fn inputs() -> horizon_shaders::GbuffersInputs {
     }
 }
 
+/// What `gbuffers_skytextured` reads from the sun and moon's vertices.
+pub fn celestial_inputs() -> horizon_shaders::GbuffersInputs {
+    horizon_shaders::GbuffersInputs {
+        declarations:
+            "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in vec2 hz_v_uv;\n\
+             layout(location = 2) in vec4 hz_v_color;\n"
+                .into(),
+        body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n    \
+             hz_MultiTexCoord0 = vec4(hz_v_uv, 0.0, 1.0);\n    \
+             hz_MultiTexCoord1 = vec4(0.0, 240.0, 0.0, 1.0);\n    \
+             hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+             hz_Color = hz_v_color;\n    \
+             hz_Normal = vec3(0.0, 0.0, 1.0);\n"
+            .into(),
+        attributes: vec![
+            ("vaPosition".into(), "hz_Vertex.xyz".into()),
+            ("vaUV0".into(), "hz_v_uv".into()),
+            ("vaColor".into(), "hz_Color".into()),
+            ("vaNormal".into(), "hz_Normal".into()),
+        ],
+        after: "    gl_Position.z = gl_Position.w;\n".into(),
+    }
+}
+
+/// One draw of the sky: its render stage, whether `gbuffers_skytextured` draws it, its vertices.
+pub(super) struct Part {
+    pub stage: &'static str,
+    pub textured: bool,
+    pub range: Range<u32>,
+}
+
 /// A disc fan at height `y`, radius 512, as triangles (SkyRenderer's sky and void discs).
 fn disc(y: f32, kind: u32, out: &mut Vec<Vertex>) {
     let sign = y.signum();
@@ -104,6 +151,7 @@ fn disc(y: f32, kind: u32, out: &mut Vec<Vertex>) {
 
 pub(super) struct PackSky {
     vertices: wgpu::Buffer,
+    celestial: wgpu::Buffer,
     uniform: wgpu::Buffer,
     pub layout: wgpu::BindGroupLayout,
     group: wgpu::BindGroup,
@@ -144,6 +192,12 @@ impl PackSky {
             contents: bytemuck::cast_slice(&v),
             usage: wgpu::BufferUsages::VERTEX,
         });
+        let celestial = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack sun and moon"),
+            size: (std::mem::size_of::<Celestial>() * 6 * CELESTIAL_QUADS) as u64,
+            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
         let uniform = device.create_buffer(&wgpu::BufferDescriptor {
             label: Some("Shader pack sky"),
             size: std::mem::size_of::<Uniform>() as u64,
@@ -173,6 +227,7 @@ impl PackSky {
         });
         Self {
             vertices,
+            celestial,
             uniform,
             layout,
             group,
@@ -188,15 +243,18 @@ impl PackSky {
         })]
     }
 
-    /// Draws the frame's sky, each part with its render stage: the disc, the sunset fan while
-    /// the sun is near the horizon, the stars and, with the camera low, the void.
-    pub fn draw(
-        &self,
-        queue: &wgpu::Queue,
-        pass: &mut wgpu::RenderPass<'_>,
-        frame: &super::Frame,
-        stage: &dyn Fn(&mut wgpu::RenderPass<'_>, &str),
-    ) {
+    pub fn celestial_buffers() -> [Option<wgpu::VertexBufferLayout<'static>>; 1] {
+        [Some(wgpu::VertexBufferLayout {
+            array_stride: std::mem::size_of::<Celestial>() as u64,
+            step_mode: wgpu::VertexStepMode::Vertex,
+            attributes: &CELESTIAL_ATTRIBUTES,
+        })]
+    }
+
+    /// Writes the frame's sky and returns its draws in vanilla's order: the disc, the sunset
+    /// fan while the sun is near the horizon, the sun and the moon, the stars and, with the
+    /// camera low, the void.
+    pub fn prepare(&self, queue: &wgpu::Queue, frame: &super::Frame) -> Vec<Part> {
         let sun_angle = frame.sky.sun_angle.to_radians();
         // The fan turns to the other horizon in the afternoon (terrain.wgsl's sunrise_weight).
         let flip = if sun_angle.sin() < 0.0 { 180f32 } else { 0.0 };
@@ -210,20 +268,52 @@ impl PackSky {
             sun: [theta.cos(), theta.sin(), brightness.clamp(0.0, 1.0), 0.0],
         };
         queue.write_buffer(&self.uniform, 0, bytemuck::bytes_of(&uniform));
-        pass.set_bind_group(1, &self.group, &[]);
-        pass.set_vertex_buffer(0, self.vertices.slice(..));
+        // The sun's quad, then the moon's (Game::celestial_geometry), as triangles.
+        let quads = frame
+            .celestial
+            .as_chunks::<4>()
+            .0
+            .iter()
+            .take(CELESTIAL_QUADS);
+        let triangles: Vec<Celestial> = quads
+            .clone()
+            .flat_map(|q| [0, 1, 2, 0, 2, 3].map(|i| q[i]))
+            .map(|v| Celestial {
+                pos: v.pos,
+                uv: v.uv,
+                color: v.color,
+            })
+            .collect();
+        queue.write_buffer(&self.celestial, 0, bytemuck::cast_slice(&triangles));
         let [sky, sunset, stars, void] = self.ranges.clone();
-        let parts = [
-            ("SKY", sky, true),
-            ("SUNSET", sunset, frame.sky.sunrise_color[3] > 0.001),
-            ("STARS", stars, frame.stars.is_some()),
-            ("VOID", void, frame.dark_disc),
-        ];
-        for (name, range, shown) in parts {
-            if shown {
-                stage(pass, name);
-                pass.draw(range, 0..1);
-            }
+        let part = |stage, textured, range| Part {
+            stage,
+            textured,
+            range,
+        };
+        let mut parts = vec![part("SKY", false, sky)];
+        if frame.sky.sunrise_color[3] > 0.001 {
+            parts.push(part("SUNSET", false, sunset));
+        }
+        for (i, stage) in ["SUN", "MOON"].into_iter().enumerate().take(quads.len()) {
+            parts.push(part(stage, true, i as u32 * 6..i as u32 * 6 + 6));
+        }
+        if frame.stars.is_some() {
+            parts.push(part("STARS", false, stars));
+        }
+        if frame.dark_disc {
+            parts.push(part("VOID", false, void));
+        }
+        parts
+    }
+
+    /// Binds the vertices of the `textured` (sun and moon) or other parts.
+    pub fn bind(&self, pass: &mut wgpu::RenderPass<'_>, textured: bool) {
+        if textured {
+            pass.set_vertex_buffer(0, self.celestial.slice(..));
+        } else {
+            pass.set_bind_group(1, &self.group, &[]);
+            pass.set_vertex_buffer(0, self.vertices.slice(..));
         }
     }
 }
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index 853f2f2ba..f33dfec57 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -34,8 +34,8 @@ pub use macros::{MC_VERSION, Macros, RENDER_STAGES, render_stage};
 pub use options::switches_on;
 pub use pack::{Pack, PackError};
 pub use post::{
-    Blend, Factor, GameInputs, Group, Post, PostProgram, TRANSLUCENT_BLEND, dimension_folder,
-    load_post,
+    Blend, CELESTIAL_BLEND, Factor, GameInputs, Group, Post, PostProgram, TRANSLUCENT_BLEND,
+    dimension_folder, load_post,
 };
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 56303e67b..944cf10b8 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -96,6 +96,21 @@ const TERRAIN: [&str; 4] = [
 /// `gbuffers_skybasic` and its fallback (2.3).
 const SKY: [&str; 2] = ["gbuffers_skybasic", "gbuffers_basic"];
 
+/// `gbuffers_skytextured` and its fallbacks (2.3).
+const SKY_TEXTURED: [&str; 3] = [
+    "gbuffers_skytextured",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
+/// The sun and moon's default blend: added to the sky, as vanilla draws them.
+pub const CELESTIAL_BLEND: Blend = [
+    Factor::SrcAlpha,
+    Factor::One,
+    Factor::One,
+    Factor::OneMinusSrcAlpha,
+];
+
 const GROUPS: [(Group, &str); 4] = [
     (Group::Prepare, "prepare"),
     (Group::Deferred, "deferred"),
@@ -132,6 +147,8 @@ pub struct Post {
     pub water: Option<PostProgram>,
     /// What draws the sky (disc, sunset, stars, void) before terrain.
     pub sky: Option<PostProgram>,
+    /// What draws the sun and moon, between the sunset and the stars.
+    pub sky_textured: Option<PostProgram>,
     /// The custom uniforms of `shaders.properties` (3.4).
     pub custom: Custom,
     pub config: Config,
@@ -156,6 +173,7 @@ pub fn dimension_folder(pack: &Pack, id: i32) -> String {
 pub struct GameInputs {
     pub terrain: Option<GbuffersInputs>,
     pub sky: Option<GbuffersInputs>,
+    pub celestial: Option<GbuffersInputs>,
 }
 
 /// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
@@ -175,6 +193,7 @@ pub fn load_post(
         terrain: None,
         water: None,
         sky: None,
+        sky_textured: None,
         custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
@@ -221,6 +240,12 @@ pub fn load_post(
         p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
         p
     });
+    let celestial = inputs.celestial.as_ref();
+    let sky_textured = celestial.and_then(|i| gbuffers(&SKY_TEXTURED, Group::Gbuffers, i));
+    let sky_textured = sky_textured.map(|mut p| {
+        p.blend = blend(properties, &p.name).unwrap_or(Some(CELESTIAL_BLEND));
+        p
+    });
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -235,6 +260,7 @@ pub fn load_post(
         }
     }
     loader.post.sky = sky;
+    loader.post.sky_textured = sky_textured;
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
@@ -511,7 +537,8 @@ mod tests {
         };
         let inputs = GameInputs {
             terrain: Some(inputs.clone()),
-            sky: Some(inputs),
+            sky: Some(inputs.clone()),
+            celestial: Some(inputs),
         };
         let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
@@ -526,6 +553,12 @@ mod tests {
                 Some(TRANSLUCENT_BLEND)
             )
         );
+        // gbuffers_skytextured falls back to gbuffers_textured, then gbuffers_basic.
+        let sun = post.sky_textured.unwrap();
+        assert_eq!(
+            (sun.name.as_str(), sun.blend),
+            ("gbuffers_textured", Some(CELESTIAL_BLEND))
+        );
         assert_eq!(
             (water.group, water.blend),
             (Group::Translucent, Some(TRANSLUCENT_BLEND))
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/README.md b/crates/horizon-shaders/tests/packs/terrain-test/README.md
index 3fc37bf4d..7d2c168cb 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/README.md
+++ b/crates/horizon-shaders/tests/packs/terrain-test/README.md
@@ -5,6 +5,7 @@ Horizon's own shader pack for testing gbuffers terrain (written for Horizon, no
 the lightmap coordinate's sky light (cooler where the sky is hidden); `mc_midTexCoord` marks each
 face's centre with a dot, and any stage but solid terrain (translucent terrain falls back to it)
 is red. `gbuffers_skybasic` draws the sky in its vertex colour, a little greener, with magenta
-stars and a dark red void. `composite` puts the depth buffer's view-space distance into the blue
+stars and a dark red void; `gbuffers_textured` (the fallback of `gbuffers_skytextured`) the sun,
+and the moon tinted green. `composite` puts the depth buffer's view-space distance into the blue
 channel of the far half. Copy the folder into `shaderpacks/` and run the game with
 `HORIZON_SHADER_PACK=terrain-test`.
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.fsh
new file mode 100644
index 000000000..563ddeb7c
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.fsh
@@ -0,0 +1,15 @@
+#version 120
+
+uniform sampler2D texture;
+uniform int renderStage;
+
+varying vec2 texcoord;
+varying vec4 glcolor;
+
+void main() {
+    vec4 color = texture2D(texture, texcoord) * glcolor;
+    // The moon tinted green: the sun and the moon are told apart.
+    if (renderStage == MC_RENDER_STAGE_MOON) color.rb *= 0.3;
+    /* DRAWBUFFERS:0 */
+    gl_FragData[0] = color;
+}
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.vsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.vsh
new file mode 100644
index 000000000..c29b1bba0
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_textured.vsh
@@ -0,0 +1,10 @@
+#version 120
+
+varying vec2 texcoord;
+varying vec4 glcolor;
+
+void main() {
+    gl_Position = ftransform();
+    texcoord = (gl_TextureMatrix[0] * gl_MultiTexCoord0).xy;
+    glcolor = gl_Color;
+}
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index a04a31b15..5ed954898 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -171,15 +171,17 @@ fn real_packs_read() {
             };
             let inputs = horizon_shaders::GameInputs {
                 terrain: Some(terrain.clone()),
-                sky: Some(terrain),
+                sky: Some(terrain.clone()),
+                celestial: Some(terrain),
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?} {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
                 post.terrain.as_ref().map(|t| &t.name),
                 post.water.as_ref().map(|t| &t.name),
                 post.sky.as_ref().map(|t| &t.name),
+                post.sky_textured.as_ref().map(|t| &t.name),
                 post.notes.len() + post.config.notes.len(),
                 start.elapsed().as_secs_f64() * 1000.0
             );

From 36f68ab8388a615ade371796231fa2ddc9573afc Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 03:08:07 +0100
Subject: [PATCH 025/270] Server dialogs: text and boolean inputs

A dialog's text inputs are edit boxes (labelled above, CommonLayouts.
labeledElement; width, max length and initial value from the dialog) and
its boolean inputs are checkboxes with their label. A click focuses a box
or toggles a box, Tab and Shift+Tab move between the text inputs, the
keys, shortcuts and typed text go to the focused one. What they hold
fills the command templates and custom actions' payloads.

With this, AuthMe's register and login dialogs work: players type their
password and join instead of being kicked after 30 s.

horizon-ctl's `type` types into the focused input of an open dialog (the
first one when none is), in configuration too. server_e2e's dialog check
now types a number and ticks a box, and checks the command the template
makes of them and the payload of a custom action.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/dialog_screen.rs |  82 +++++++++-
 crates/horizon-client/src/game.rs          |   3 +-
 crates/horizon-client/src/game/control.rs  |   8 +-
 crates/horizon-client/src/game/dialogs.rs  | 177 ++++++++++++++++++++-
 tools/server_e2e.py                        |  21 ++-
 5 files changed, 273 insertions(+), 18 deletions(-)

diff --git a/crates/horizon-client/src/dialog_screen.rs b/crates/horizon-client/src/dialog_screen.rs
index c9434cfc2..ad4f47a17 100644
--- a/crates/horizon-client/src/dialog_screen.rs
+++ b/crates/horizon-client/src/dialog_screen.rs
@@ -1,15 +1,17 @@
 //! `DialogScreen` and its kinds (`SimpleDialogScreen`, `MultiButtonDialogScreen`):
-//! where a server dialog's title, body and buttons go in a
+//! where a server dialog's title, body, inputs and buttons go in a
 //! `HeaderAndFooterLayout` (a 33 high header, the body in a `ScrollableLayout`,
 //! the footer), and the `WaitingForResponseScreen` an answer can leave open.
 use crate::{
-    dialog::{Body, Dialog, Kind},
+    dialog::{Body, Control, Dialog, Kind},
     font::Font,
     text::Text,
 };
 
 /// `HeaderAndFooterLayout.DEFAULT_HEADER_AND_FOOTER_HEIGHT`.
 const BAR: f32 = 33.0;
+/// `Checkbox.getBoxSize`.
+pub const BOX: f32 = 17.0;
 /// `DialogScreen.WARNING_BUTTON_SPRITES`: normal, disabled, highlighted.
 pub const WARNING_SPRITES: [&str; 3] = [
     "gui/sprites/dialog/warning_button",
@@ -23,6 +25,10 @@ pub const WARNING_SPRITES: [&str; 3] = [
 pub enum Part {
     /// A line of text and where it starts.
     Line(Text, f32, f32),
+    /// A text input's box.
+    Field { input: usize, rect: [f32; 4] },
+    /// A boolean input: the box, its label right of it.
+    Check { input: usize, rect: [f32; 4] },
     /// A button of `Dialog::buttons`.
     Button { index: usize, rect: [f32; 4] },
 }
@@ -51,6 +57,14 @@ impl Element {
     fn at(self, x: f32, y: f32) -> impl Iterator<Item = Part> {
         self.parts.into_iter().map(move |p| match p {
             Part::Line(t, px, py) => Part::Line(t, px + x, py + y),
+            Part::Field { input, rect } => Part::Field {
+                input,
+                rect: shift(rect, x, y),
+            },
+            Part::Check { input, rect } => Part::Check {
+                input,
+                rect: shift(rect, x, y),
+            },
             Part::Button { index, rect } => Part::Button {
                 index,
                 rect: shift(rect, x, y),
@@ -86,6 +100,55 @@ fn message(font: &Font, contents: &Text, width: f32) -> Element {
     }
 }
 
+/// `InputControlHandlers`: the control for input `i`, if Horizon has it.
+fn input(font: &Font, i: usize, control: &Control) -> Option<Element> {
+    Some(match control {
+        Control::Text {
+            width,
+            label,
+            label_visible,
+            ..
+        } => {
+            let w = *width as f32;
+            if !label_visible {
+                return Some(Element {
+                    w,
+                    h: 20.0,
+                    parts: vec![Part::Field {
+                        input: i,
+                        rect: [0.0, 0.0, w, 20.0],
+                    }],
+                });
+            }
+            // CommonLayouts.labeledElement: the label, 4 below it the box,
+            // both on the left.
+            Element {
+                w: w.max(font.width_text(label)),
+                h: 9.0 + 4.0 + 20.0,
+                parts: vec![
+                    Part::Line(label.clone(), 0.0, 0.0),
+                    Part::Field {
+                        input: i,
+                        rect: [0.0, 13.0, w, 20.0],
+                    },
+                ],
+            }
+        }
+        Control::Boolean { label, .. } => {
+            let w = BOX + 4.0 + font.width_text(label);
+            Element {
+                w,
+                h: BOX,
+                parts: vec![Part::Check {
+                    input: i,
+                    rect: [0.0, 0.0, w, BOX],
+                }],
+            }
+        }
+        Control::SingleOption { .. } | Control::NumberRange { .. } => return None,
+    })
+}
+
 /// `DialogScreen.packControlsIntoColumns`: full rows in a grid 2 apart, what
 /// is left in a centred row under them.
 fn columns(widths: &[f32], columns: usize, first: usize) -> Element {
@@ -152,6 +215,13 @@ impl Layout {
                 Body::Item { .. } => None,
             })
             .collect();
+        elements.extend(
+            dialog
+                .inputs
+                .iter()
+                .enumerate()
+                .filter_map(|(i, input_)| input(font, i, &input_.control)),
+        );
         let buttons = dialog.buttons();
         let (listed, footer_buttons, footer_h) = match &dialog.kind {
             Kind::MultiAction {
@@ -236,6 +306,14 @@ impl Layout {
         let body = self.body.iter().map(move |p| {
             let p = match p.clone() {
                 Part::Line(t, x, y) => Part::Line(t, x, y + dy),
+                Part::Field { input, rect } => Part::Field {
+                    input,
+                    rect: shift(rect, 0.0, dy),
+                },
+                Part::Check { input, rect } => Part::Check {
+                    input,
+                    rect: shift(rect, 0.0, dy),
+                },
                 Part::Button { index, rect } => Part::Button {
                     index,
                     rect: shift(rect, 0.0, dy),
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 283bd2cad..583b95313 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -11224,10 +11224,11 @@ impl ApplicationHandler for Game<'_> {
                     }
                 }
                 WindowEvent::KeyboardInput { event, .. } if self.dialog_open() => {
+                    let shortcut = self.edit_shortcut(&event);
                     if event.state == ElementState::Pressed
                         && let PhysicalKey::Code(key) = event.physical_key
                     {
-                        self.dialog_key(key)?
+                        self.dialog_key(key, shortcut, event.text.as_deref())?
                     }
                 }
                 WindowEvent::KeyboardInput { event, .. }
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index adba0bc05..598009e6a 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -234,7 +234,7 @@ impl Game<'_> {
                 // A server's dialog takes the keys, in configuration too.
                 if self.dialog_open() {
                     if arg(2)? != "up" {
-                        self.dialog_key(key)?;
+                        self.dialog_key(key, None, None)?;
                     }
                     return ok();
                 }
@@ -527,13 +527,17 @@ impl Game<'_> {
                 ))
             }
             "type" => {
-                self.require_world()?;
                 let text = line
                     .trim_start()
                     .strip_prefix("type")
                     .unwrap_or("")
                     .strip_prefix(' ')
                     .unwrap_or("");
+                // A server's dialog, in configuration too.
+                if self.dialog_type(text) {
+                    return ok();
+                }
+                self.require_world()?;
                 if self.book.is_some() {
                     self.book_type(text);
                     return ok();
diff --git a/crates/horizon-client/src/game/dialogs.rs b/crates/horizon-client/src/game/dialogs.rs
index 28a7a7609..4928b0aa8 100644
--- a/crates/horizon-client/src/game/dialogs.rs
+++ b/crates/horizon-client/src/game/dialogs.rs
@@ -6,9 +6,10 @@
 use super::Game;
 use horizon_client::{
     Result,
+    clipboard::EditShortcut,
     confirm_screen::Confirm,
-    dialog::{AfterAction, Click, Dialog, InputValue},
-    dialog_screen::{Layout, Part, WARNING_SPRITES, waiting_button},
+    dialog::{AfterAction, Click, Control, Dialog, InputValue},
+    dialog_screen::{BOX, Layout, Part, WARNING_SPRITES, waiting_button},
     hud::{HudBatch, rgba},
     text::Text,
     ui,
@@ -21,6 +22,9 @@ use winit::keyboard::KeyCode;
 struct Open {
     dialog: Dialog,
     values: Vec<InputValue>,
+    /// The box of each text input.
+    fields: Vec<Option<ui::EditBox>>,
+    focus: Option<usize>,
     scroll: ui::Scroll,
 }
 
@@ -58,9 +62,30 @@ impl Game<'_> {
             return;
         };
         let values = dialog.inputs.iter().map(|i| i.control.initial()).collect();
+        let fields = dialog
+            .inputs
+            .iter()
+            .map(|i| match &i.control {
+                Control::Text {
+                    width,
+                    initial,
+                    max_length,
+                    ..
+                } => {
+                    let mut edit = ui::EditBox::new(0.0, 0.0, *width as f32, 20.0);
+                    edit.max_length = (*max_length).max(1) as usize;
+                    edit.set_value(initial);
+                    edit.focused = false;
+                    Some(edit)
+                }
+                _ => None,
+            })
+            .collect();
         self.dialogs.open = Some(Open {
             dialog,
             values,
+            fields,
+            focus: None,
             scroll: ui::Scroll::default(),
         });
         self.dialogs.waiting = None;
@@ -86,6 +111,15 @@ impl Game<'_> {
         }
     }
 
+    /// The input values as the controls hold them now.
+    fn dialog_values(open: &mut Open) {
+        for (value, field) in open.values.iter_mut().zip(&open.fields) {
+            if let Some(f) = field {
+                *value = InputValue::Text(f.value.clone());
+            }
+        }
+    }
+
     /// `DialogScreen.runAction`: the click event, then the screen the dialog's
     /// `after_action` leaves.
     fn run_dialog_action(&mut self, click: Option<Click>, after: AfterAction) -> Result<()> {
@@ -268,6 +302,37 @@ impl Game<'_> {
                 Part::Line(text, x, y) => {
                     batch.text_styled(atlas, &text, x, y, u32::MAX, true);
                 }
+                Part::Field { input, rect } => {
+                    if let Some(Some(edit)) = open.fields.get_mut(input) {
+                        [edit.x, edit.y, edit.width, edit.height] = rect;
+                        edit.focused = open.focus == Some(input);
+                        edit.draw(batch, atlas, None);
+                    }
+                }
+                Part::Check { input, rect } => {
+                    let [x, y, cw, ch] = rect;
+                    let hover = in_area(cursor.1) && ui::hovered(cursor, x, y, cw, ch);
+                    let on = open.values.get(input) == Some(&InputValue::Bool(true));
+                    let sprite = match (on, hover) {
+                        (true, true) => "gui/sprites/widget/checkbox_selected_highlighted",
+                        (true, false) => "gui/sprites/widget/checkbox_selected",
+                        (false, true) => "gui/sprites/widget/checkbox_highlighted",
+                        (false, false) => "gui/sprites/widget/checkbox",
+                    };
+                    let Control::Boolean { label, .. } = &open.dialog.inputs[input].control else {
+                        continue;
+                    };
+                    horizon_client::widgets::record(&label.plain(), rect, true);
+                    batch.sprite_scaled(atlas, sprite, x, y, BOX, BOX, u32::MAX);
+                    batch.text_styled(
+                        atlas,
+                        label,
+                        x + BOX + 4.0,
+                        y + 4.0,
+                        rgba(224, 224, 224, 255),
+                        true,
+                    );
+                }
                 Part::Button { index, rect } => {
                     let [x, y, bw, bh] = rect;
                     let hover =
@@ -360,24 +425,51 @@ impl Game<'_> {
         };
         let [_, ay, _, ah] = layout.area;
         let mut action = None;
+        open.focus = None;
         for (part, clipped) in layout.placed(open.scroll.amount) {
             if clipped && !(cursor.1 >= ay && cursor.1 < ay + ah) {
                 continue;
             }
             match part {
+                Part::Field {
+                    input,
+                    rect: [x, y, w, h],
+                } if ui::hovered(cursor, x, y, w, h) => {
+                    open.focus = Some(input);
+                    if let Some(Some(edit)) = open.fields.get_mut(input) {
+                        edit.focused = true;
+                        edit.click(&self.gui.atlas, cursor.0, false, false);
+                    }
+                }
+                Part::Check {
+                    input,
+                    rect: [x, y, w, h],
+                } if ui::hovered(cursor, x, y, w, h) => {
+                    if let Some(InputValue::Bool(b)) = open.values.get_mut(input) {
+                        *b = !*b;
+                    }
+                    action = Some(None);
+                }
                 Part::Button {
                     index,
                     rect: [x, y, w, h],
                 } if ui::hovered(cursor, x, y, w, h) => {
-                    action = Some(index);
+                    action = Some(Some(index));
                 }
                 _ => {}
             }
         }
-        let Some(index) = action else {
+        let Some(action) = action else {
             return Ok(());
         };
         self.audio.play_button_click();
+        let Some(index) = action else {
+            return Ok(());
+        };
+        let Some(open) = self.dialogs.open.as_mut() else {
+            return Ok(());
+        };
+        Self::dialog_values(open);
         let d = &open.dialog;
         let click = d.buttons()[index]
             .action
@@ -398,8 +490,15 @@ impl Game<'_> {
         }
     }
 
-    /// A key pressed on a dialog screen: Escape closes what allows it.
-    pub(super) fn dialog_key(&mut self, key: KeyCode) -> Result<()> {
+    /// A key pressed on a dialog screen: Escape closes what allows it, Tab
+    /// moves between the text inputs, the rest goes to the focused one
+    /// (`shortcut`: the press as an edit shortcut; `text`: what it types).
+    pub(super) fn dialog_key(
+        &mut self,
+        key: KeyCode,
+        shortcut: Option<EditShortcut>,
+        text: Option<&str>,
+    ) -> Result<()> {
         let escape = key == KeyCode::Escape;
         if self.dialogs.warning {
             if escape {
@@ -418,7 +517,9 @@ impl Game<'_> {
             }
             return Ok(());
         }
-        let Some(open) = self.dialogs.open.as_ref() else {
+        let ctrl = self.modifiers.control_key() || self.modifiers.super_key();
+        let shift = self.modifiers.shift_key();
+        let Some(open) = self.dialogs.open.as_mut() else {
             return Ok(());
         };
         if escape {
@@ -426,13 +527,65 @@ impl Game<'_> {
                 return Ok(());
             }
             // onClose: the cancel action, and the screen closes.
+            Self::dialog_values(open);
             let d = &open.dialog;
             let click = d.on_cancel().and_then(|a| a.click(&d.inputs, &open.values));
             return self.run_dialog_action(click, AfterAction::Close);
         }
+        if key == KeyCode::Tab {
+            let texts: Vec<usize> = (0..open.fields.len())
+                .filter(|&i| open.fields[i].is_some())
+                .collect();
+            if !texts.is_empty() {
+                let at = open.focus.and_then(|f| texts.iter().position(|&i| i == f));
+                let next = match at {
+                    None if shift => texts.len() - 1,
+                    None => 0,
+                    Some(p) if shift => (p + texts.len() - 1) % texts.len(),
+                    Some(p) => (p + 1) % texts.len(),
+                };
+                open.focus = Some(texts[next]);
+            }
+            return Ok(());
+        }
+        let Some(Some(edit)) = open.focus.and_then(|f| open.fields.get_mut(f)) else {
+            return Ok(());
+        };
+        if let Some(shortcut) = shortcut {
+            edit.shortcut(shortcut, &mut self.clipboard);
+            return Ok(());
+        }
+        if edit.key(key, ctrl, shift) {
+            return Ok(());
+        }
+        let typed: String = text
+            .unwrap_or_default()
+            .chars()
+            .filter(|c| !c.is_control())
+            .collect();
+        if !typed.is_empty() {
+            edit.insert_text(&typed);
+        }
         Ok(())
     }
 
+    /// `type TEXT` with a dialog open: into the focused text input, or the
+    /// first one.
+    pub(super) fn dialog_type(&mut self, text: &str) -> bool {
+        let Some(open) = self.dialogs.open.as_mut() else {
+            return false;
+        };
+        let focus = open
+            .focus
+            .or_else(|| open.fields.iter().position(Option::is_some));
+        let Some(Some(edit)) = focus.and_then(|f| open.fields.get_mut(f)) else {
+            return false;
+        };
+        open.focus = focus;
+        edit.insert_text(text);
+        true
+    }
+
     /// What `state` reports: the open dialog and its values, or the waiting
     /// and warning screens.
     pub(super) fn dialog_status(&self) -> serde_json::Value {
@@ -444,7 +597,15 @@ impl Game<'_> {
         } else {
             None
         };
-        let open = d.open.as_ref().map(|open| open.dialog.json(&open.values));
+        let open = d.open.as_ref().map(|open| {
+            let mut values = open.values.clone();
+            for (value, field) in values.iter_mut().zip(&open.fields) {
+                if let Some(f) = field {
+                    *value = InputValue::Text(f.value.clone());
+                }
+            }
+            open.dialog.json(&values)
+        });
         serde_json::json!({ "open": open, "screen": screen })
     }
 }
diff --git a/tools/server_e2e.py b/tools/server_e2e.py
index 397e03549..590072249 100644
--- a/tools/server_e2e.py
+++ b/tools/server_e2e.py
@@ -9,8 +9,9 @@ the game shows and what reaches the server (its console and, for custom click ac
     python3 tools/server_e2e.py --bin-dir target/fast --check dialog
 
 Checks:
-- dialog: `/dialog show` with a multi-action dialog (a message, three buttons): the game shows it,
-          a command runs on the server (`trigger`), a custom action reaches it with its
+- dialog: `/dialog show` with a multi-action dialog (a message, a text and a boolean input, three
+          buttons): the game shows it with its inputs and buttons, the text typed and the box ticked
+          go back in a command template (`trigger`, run by the server) and in a custom action's
           payload (the server's "Received custom click action" line), `wait_for_response` leaves the
           waiting screen, and `/dialog clear` closes a dialog (servers used to see nothing: the game
           dropped the packets).
@@ -79,8 +80,13 @@ def check_dialog(server, game, out):
         'type': 'minecraft:multi_action',
         'title': {'text': 'Sign in', 'color': 'gold'},
         'body': {'type': 'minecraft:plain_message', 'contents': 'Pick a number.'},
+        'inputs': [
+            {'type': 'minecraft:text', 'key': 'number', 'label': 'Number'},
+            {'type': 'minecraft:boolean', 'key': 'agree', 'label': 'Agree', 'on_true': '1', 'on_false': '0'},
+        ],
         'actions': [
-            {'label': 'Send', 'action': {'type': 'minecraft:run_command', 'command': 'trigger answer set 41'}},
+            {'label': 'Send', 'action': {'type': 'minecraft:dynamic/run_command',
+                                         'template': 'trigger answer set $(number)$(agree)'}},
             {'label': 'Submit', 'action': {'type': 'minecraft:dynamic/custom', 'id': 'horizon:e2e',
                                            'additions': {'tag': 'x'}}},
             {'label': 'Wait', 'action': {'type': 'minecraft:dynamic/custom', 'id': 'horizon:wait'}},
@@ -94,19 +100,24 @@ def check_dialog(server, game, out):
     state = game('state')
     shown['shown'] = state['dialog']['open']
     assert shown['shown']['title'] == 'Sign in', shown
+    assert [i['key'] for i in shown['shown']['inputs']] == ['number', 'agree'], shown
     assert shown['shown']['buttons'] == ['Send', 'Submit', 'Wait'], shown
     game.shot(out, 'dialog')
+    # The text, the box, then the command the template makes of them.
+    game.raw('type', '4')
+    game.raw('click', 'agree')
     game.raw('click', 'send')
     time.sleep(1)
     server.console(f'scoreboard players get {PLAYER} answer')
     server.wait_for(rf'{PLAYER} has 41 \[answer\]', timeout=30)
     shown['trigger'] = 41
-    # A custom action and its additions.
+    # A custom action: its additions and every input's tag.
     game.raw('click', 'submit')
     server.wait_for(r'Received custom click action horizon:e2e with payload', timeout=30)
     line = next(l for l in server.lines if 'horizon:e2e' in l)
     shown['custom'] = line.split('payload ', 1)[1]
-    assert shown['custom'] == '{tag:"x"}', shown
+    for part in ('agree:1b', 'number:"4"', 'tag:"x"'):
+        assert part in shown['custom'], shown
     # after_action none: still open. Then clear it.
     assert game('state')['dialog']['open'], 'the dialog closed after an action with after_action none'
     server.console(f'dialog clear {PLAYER}')

From b940754555666ba25fa8541e537b7b9a83aa0449 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 04:23:38 +0100
Subject: [PATCH 026/270] Terrain vertex arena readable as storage where flat
 draws run

The terrain vertex arena's pages also get STORAGE usage on devices that
run flat draws (vertex storage and compute), so a shader pack's terrain
program can read the other corners of a vertex's quad to give packs a
face normal and tangent. Horizon's own pipelines are unchanged; the A/B
in the PR shows no frame-time change without a pack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs       |  5 ++++-
 crates/horizon-client/src/gfx/arena.rs | 15 +++++++++++----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index bdd8250b8..1883e6077 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2140,13 +2140,16 @@ impl Renderer {
             usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
             mapped_at_creation: false,
         });
+        let flat_wanted = flat::wanted(&adapter, &device);
+        // Readable as storage where flat draws run: a shader pack's terrain program reads them.
         let arena = arena::Arena::new(
             &device,
             std::mem::size_of::<TerrainVertex>() as u64,
             1 << 20,
+            flat_wanted,
         );
         // Sections as one index list per frame where multi-draw is emulated.
-        let flat = flat::wanted(&adapter, &device).then(|| {
+        let flat = flat_wanted.then(|| {
             let buffers = [Some(wgpu::VertexBufferLayout {
                 array_stride: std::mem::size_of::<TerrainVertex>() as u64,
                 step_mode: wgpu::VertexStepMode::Vertex,
diff --git a/crates/horizon-client/src/gfx/arena.rs b/crates/horizon-client/src/gfx/arena.rs
index 8da835aa2..dbbf70140 100644
--- a/crates/horizon-client/src/gfx/arena.rs
+++ b/crates/horizon-client/src/gfx/arena.rs
@@ -65,8 +65,15 @@ pub struct Arena {
 }
 
 impl Arena {
-    pub fn new(device: &wgpu::Device, stride: u64, capacity: u64) -> Self {
-        Self::with_usage(device, stride, capacity, wgpu::BufferUsages::VERTEX)
+    /// Vertices; `storage` also lets shaders read them as a storage buffer (a shader pack's
+    /// terrain program reads the other corners of a vertex's quad for its normal).
+    pub fn new(device: &wgpu::Device, stride: u64, capacity: u64, storage: bool) -> Self {
+        let usage = if storage {
+            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::STORAGE
+        } else {
+            wgpu::BufferUsages::VERTEX
+        };
+        Self::with_usage(device, stride, capacity, usage)
     }
     /// Sorted translucent indices; `storage` when compute passes read them.
     pub fn indices(device: &wgpu::Device, capacity: u64, storage: bool) -> Self {
@@ -352,7 +359,7 @@ mod tests {
             eprintln!("no GPU adapter: skipped");
             return;
         };
-        let mut arena = Arena::new(&device, 4, GRAIN);
+        let mut arena = Arena::new(&device, 4, GRAIN, false);
         arena.page_limit = 2 * GRAIN;
         assert_eq!(arena.bytes(), 0);
         let (first, a) = alloc(&mut arena, &device, &queue, GRAIN).unwrap();
@@ -395,7 +402,7 @@ mod tests {
             return;
         };
         for mut arena in [
-            Arena::new(&device, 28, GRAIN),
+            Arena::new(&device, 28, GRAIN, false),
             Arena::indices(&device, GRAIN, false),
         ] {
             alloc(&mut arena, &device, &queue, GRAIN).unwrap();

From 441f749c25507bfceedc1d618f72e72522e4cf4d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 04:59:39 +0100
Subject: [PATCH 027/270] Shader packs, clean room 24: mc_Entity from
 block.properties

block.properties (spec 4.1) is read: `block.<id>=` names with optional
namespaces and state filters; the most specific matching entry wins.
Terrain vertices carry their sprite layer, not their block, so the game
builds a table of the block sprite layers: each takes the id of the block
named like its sprite, else the id most blocks drawing it share; y is 1
on the water and lava sprites. Flat terrain reads it from a storage
buffer at set 3; other draws and packs without the file read (-1, -1).
Building the table takes 14 ms for BSL, 39 ms for Complementary.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
4.1, 5.1, 5.3; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/shader_packs.rs   | 101 ++++++++++++++-
 crates/horizon-client/src/gfx.rs              |   6 +-
 crates/horizon-client/src/gfx/pack_atlas.rs   |  11 +-
 crates/horizon-client/src/gfx/pack_post.rs    |  71 ++++++++++-
 crates/horizon-shaders/src/block_ids.rs       | 120 ++++++++++++++++++
 crates/horizon-shaders/src/lib.rs             |   2 +
 .../tests/packs/terrain-test/README.md        |   2 +-
 .../terrain-test/shaders/block.properties     |   3 +
 .../terrain-test/shaders/gbuffers_terrain.fsh |   3 +
 .../terrain-test/shaders/gbuffers_terrain.vsh |   3 +
 10 files changed, 314 insertions(+), 8 deletions(-)
 create mode 100644 crates/horizon-shaders/src/block_ids.rs
 create mode 100644 crates/horizon-shaders/tests/packs/terrain-test/shaders/block.properties

diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index 360262640..7fa2ea3f6 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -4,7 +4,7 @@
 
 use horizon_client::camera::CameraFluid;
 use horizon_client::gfx::pack_uniforms::PackInputs;
-use horizon_shaders::{Macros, Pack, Properties, dimension_folder, load_post};
+use horizon_shaders::{BlockIds, Macros, Pack, Properties, dimension_folder, load_post};
 
 use super::{Dim, Game};
 
@@ -44,7 +44,21 @@ impl Game<'_> {
                     let folder = dimension_folder(&pack, dimension);
                     let inputs = renderer.pack_inputs();
                     let post = load_post(&pack, &folder, &properties, &macros, &inputs);
-                    if let Some((programs, notes)) = renderer.set_shader_pack(dimension, Some(post))
+                    let text = pack.read_text("block.properties").unwrap_or_default();
+                    let ids = BlockIds::parse(&Properties::parse(&text, &macros));
+                    for note in &ids.notes {
+                        log::warn!("shader pack {name}: block.properties: {note}");
+                    }
+                    let started_ids = std::time::Instant::now();
+                    let table = block_id_table(&self.pack, &ids);
+                    log::info!(
+                        "shader pack {name}: mc_Entity for {} of {} block sprites in {} ms",
+                        table.chunks(2).filter(|p| p[0] != -1).count(),
+                        table.len() / 2,
+                        started_ids.elapsed().as_millis()
+                    );
+                    if let Some((programs, notes)) =
+                        renderer.set_shader_pack(dimension, Some(post), &table)
                     {
                         for note in notes {
                             log::warn!("shader pack {name}: {note}");
@@ -59,7 +73,7 @@ impl Game<'_> {
                 }
                 Err(e) => {
                     log::warn!("shader pack {name}: {e}");
-                    renderer.set_shader_pack(dimension, None);
+                    renderer.set_shader_pack(dimension, None, &[]);
                 }
             }
         }
@@ -83,3 +97,84 @@ impl Game<'_> {
         }
     }
 }
+
+/// `mc_Entity` (x, y) of each block sprite layer, as (id, fluid) pairs: terrain vertices carry
+/// their sprite layer, not their block. A layer takes the id of the block named like its sprite
+/// (`block/oak_leaves` for `oak_leaves`), else the id most blocks drawing it share (ties: the
+/// lowest); -1 when no block drawing it has one. y is 1 for the fluid sprites, -1 otherwise.
+fn block_id_table(pack: &super::PackResources, ids: &BlockIds) -> Vec<i32> {
+    use std::collections::{BTreeMap, BTreeSet};
+    let layers = pack
+        .render
+        .sprite_layers
+        .values()
+        .max()
+        .map_or(0, |l| l + 1) as usize;
+    let mut table = vec![-1; layers * 2];
+    if ids.is_empty() {
+        return table;
+    }
+    let registry = pack.assets.registry;
+    let catalog = &pack.render.model_catalog;
+    let sprite = |name: &str| pack.render.sprite_layers.get(name).copied();
+    // (layer, id) -> (a block named like the sprite, the blocks).
+    let mut votes: BTreeMap<(u32, i32), (bool, BTreeSet<&str>)> = BTreeMap::new();
+    for i in 0..registry.len() {
+        let state_id = horizon_world::registry::BlockStateId(i as u32);
+        let Some(state) = registry.state(state_id) else {
+            continue;
+        };
+        let Some(id) = ids.id(&state.name, |k| state.properties.get(k).map(String::as_str)) else {
+            continue;
+        };
+        let block = state.name.strip_prefix("minecraft:").unwrap_or(&state.name);
+        let mut vote = |layer: u32| {
+            let named = pack
+                .layer_names
+                .get(&layer)
+                .and_then(|n| n.strip_prefix("block/"))
+                == Some(block);
+            let v = votes.entry((layer, id)).or_default();
+            v.0 |= named;
+            v.1.insert(&state.name);
+        };
+        // Fluids draw from their own sprites.
+        let fluid = match block {
+            "water" => ["water_still", "water_flow"],
+            "lava" => ["lava_still", "lava_flow"],
+            _ => ["", ""],
+        };
+        for f in fluid.iter().filter(|f| !f.is_empty()) {
+            if let Some(l) = sprite(&format!("minecraft:block/{f}")) {
+                vote(l);
+            }
+        }
+        let origin = horizon_core::position::BlockPos::new(0, 0, 0);
+        for (_, model) in catalog.collect(state_id, origin).unwrap_or_default() {
+            for face in &model.faces {
+                vote(face.layer);
+            }
+        }
+    }
+    let mut best: BTreeMap<u32, (bool, usize, i32)> = BTreeMap::new();
+    for ((layer, id), (named, blocks)) in votes {
+        let candidate = (named, blocks.len(), -id);
+        let b = best.entry(layer).or_insert(candidate);
+        if candidate > *b {
+            *b = candidate;
+        }
+    }
+    for (layer, (_, _, id)) in best {
+        if let Some(slot) = table.get_mut(layer as usize * 2) {
+            *slot = -id;
+        }
+    }
+    for f in ["water_still", "water_flow", "lava_still", "lava_flow"] {
+        if let Some(l) = sprite(&format!("minecraft:block/{f}"))
+            && let Some(slot) = table.get_mut(l as usize * 2 + 1)
+        {
+            *slot = 1;
+        }
+    }
+    table
+}
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 1883e6077..9b7fcc303 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2764,12 +2764,14 @@ impl Renderer {
         self.world_post.scale = scale.clamp(0.25, 2.0);
         self.world_post.antialias = antialias;
     }
-    /// Runs `post` over the world from now on (`None`: no pack), for the dimension `dimension`.
+    /// Runs `post` over the world from now on (`None`: no pack), for the dimension `dimension`;
+    /// `block_ids` gives each block sprite layer's `mc_Entity` (id, fluid) pair.
     /// Returns the programs that run and the notes of loading them.
     pub fn set_shader_pack(
         &mut self,
         dimension: i32,
         pack: Option<horizon_shaders::Post>,
+        block_ids: &[i32],
     ) -> Option<(Vec<String>, Vec<String>)> {
         if pack.is_none() {
             self.pack_atlas = None;
@@ -2796,7 +2798,9 @@ impl Renderer {
                     table: self.flat.as_ref().filter(|_| flat).map(|f| &f.draw_layout),
                     depth_write: true,
                     atlas: None,
+                    ids: None,
                 }),
+                block_ids,
                 celestial: self
                     .hud
                     .atlas_texture
diff --git a/crates/horizon-client/src/gfx/pack_atlas.rs b/crates/horizon-client/src/gfx/pack_atlas.rs
index 1a14a8da9..ac56985fd 100644
--- a/crates/horizon-client/src/gfx/pack_atlas.rs
+++ b/crates/horizon-client/src/gfx/pack_atlas.rs
@@ -127,6 +127,10 @@ impl PackAtlas {
                 "layout(set = 1, binding = 0) readonly buffer HzBlockSlots { uint hz_block_slots[]; };\n\
                  layout(set = 1, binding = 1) readonly buffer HzSlotOrigins { vec4 hz_slot_origins[]; };\n",
             );
+            // `mc_Entity` of each sprite layer: id, then 1 for fluids or -1 (the game's table).
+            declarations.push_str(
+                "layout(set = 3, binding = 0) readonly buffer HzBlockIds { int hz_block_ids[]; };\n",
+            );
             "hz_slot_origins[hz_block_slots[uint(gl_VertexIndex) >> 8u]]"
         } else {
             declarations.push_str("layout(location = 5) in vec4 hz_v_origin;\n");
@@ -153,8 +157,13 @@ impl PackAtlas {
             scale[0], scale[1],
         );
         declarations.push_str("vec2 hz_cell; vec2 hz_scale;\n");
+        let entity = if flat {
+            "vec4(float(hz_block_ids[2u * hz_layer]), float(hz_block_ids[2u * hz_layer + 1u]), 0.0, 0.0)"
+        } else {
+            "vec4(-1.0, -1.0, 0.0, 0.0)"
+        };
         let attributes = [
-            ("mc_Entity", "vec4(-1.0, -1.0, 0.0, 0.0)"),
+            ("mc_Entity", entity),
             (
                 "mc_midTexCoord",
                 "vec4((hz_cell + 0.5) * hz_scale, 0.0, 1.0)",
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 9002ad963..ba8fe62e7 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -154,6 +154,8 @@ struct Pass {
     draw: bool,
     /// What `texture` reads instead of the block atlas.
     atlas: Option<wgpu::TextureView>,
+    /// Reads `mc_Entity`'s table (`PackPost::block_ids`).
+    ids: bool,
     groups: HashMap<u16, wgpu::BindGroup>,
 }
 
@@ -184,6 +186,8 @@ pub(super) struct World<'a> {
     pub lightmap: wgpu::TextureView,
     /// Terrain's geometry, when the pack draws it.
     pub terrain: Option<Geometry<'a>>,
+    /// `mc_Entity` of each block sprite layer: (id, 1 for fluids or -1) pairs.
+    pub block_ids: &'a [i32],
     /// The atlas of the sun and moon's sprites.
     pub celestial: Option<wgpu::TextureView>,
 }
@@ -207,6 +211,8 @@ pub struct PackPost {
     down: HashMap<wgpu::TextureFormat, (wgpu::RenderPipeline, wgpu::BindGroupLayout)>,
     /// The per-draw uniforms of gbuffers programs.
     draws: DrawUniforms,
+    /// `mc_Entity`'s table of flat terrain, and its bind group.
+    block_ids: Option<(wgpu::BindGroupLayout, wgpu::BindGroup)>,
     /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
     timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
@@ -492,6 +498,42 @@ fn attach(
     })
 }
 
+/// `mc_Entity`'s table as a storage buffer (vertex stage) at set 3; -1 pairs when empty.
+fn block_ids(device: &wgpu::Device, table: &[i32]) -> (wgpu::BindGroupLayout, wgpu::BindGroup) {
+    let empty = [-1, -1];
+    let table = if table.is_empty() { &empty[..] } else { table };
+    let buffer = wgpu::util::DeviceExt::create_buffer_init(
+        device,
+        &wgpu::util::BufferInitDescriptor {
+            label: Some("Shader pack block ids"),
+            contents: bytemuck::cast_slice(table),
+            usage: wgpu::BufferUsages::STORAGE,
+        },
+    );
+    let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("Shader pack block ids"),
+        entries: &[wgpu::BindGroupLayoutEntry {
+            binding: 0,
+            visibility: wgpu::ShaderStages::VERTEX,
+            ty: wgpu::BindingType::Buffer {
+                ty: wgpu::BufferBindingType::Storage { read_only: true },
+                has_dynamic_offset: false,
+                min_binding_size: None,
+            },
+            count: None,
+        }],
+    });
+    let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+        label: Some("Shader pack block ids"),
+        layout: &layout,
+        entries: &[wgpu::BindGroupEntry {
+            binding: 0,
+            resource: buffer.as_entire_binding(),
+        }],
+    });
+    (layout, group)
+}
+
 /// The game's geometry a gbuffers program draws: its vertex buffers and, for flat draws
 /// (flat.rs), the layout of their bind group 1.
 pub(super) struct Geometry<'a> {
@@ -501,6 +543,8 @@ pub(super) struct Geometry<'a> {
     pub depth_write: bool,
     /// What `texture` reads instead of the block atlas.
     pub atlas: Option<wgpu::TextureView>,
+    /// `mc_Entity`'s table at set 3 (flat terrain).
+    pub ids: Option<&'a wgpu::BindGroupLayout>,
 }
 
 /// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
@@ -663,6 +707,7 @@ fn build_pass(
                 Some(&layout),
                 geometry.and_then(|g| g.table),
                 draw.then_some(draws),
+                geometry.and_then(|g| g.ids),
             ],
             ..Default::default()
         });
@@ -745,6 +790,7 @@ fn build_pass(
         mipmaps: p.mipmaps,
         draw,
         atlas: geometry.and_then(|g| g.atlas.clone()),
+        ids: geometry.is_some_and(|g| g.ids.is_some()),
         groups: HashMap::new(),
     })
 }
@@ -796,13 +842,26 @@ impl PackPost {
             used |= pass.reads | pass.written | pass.flip;
             Some(pass)
         };
+        // Flat terrain reads `mc_Entity` from a table of the sprite layers.
+        let block_ids = world
+            .terrain
+            .as_ref()
+            .filter(|g| g.table.is_some())
+            .map(|_| block_ids(device, world.block_ids));
+        let terrain_geometry = world.terrain.as_ref().map(|g| Geometry {
+            buffers: g.buffers,
+            table: g.table,
+            depth_write: g.depth_write,
+            atlas: g.atlas.clone(),
+            ids: block_ids.as_ref().map(|i| &i.0),
+        });
         let terrain = post
             .terrain
-            .zip(world.terrain.as_ref())
+            .zip(terrain_geometry.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
         let water = post
             .water
-            .zip(world.terrain.as_ref())
+            .zip(terrain_geometry.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
         let sky = (post.sky.is_some() || post.sky_textured.is_some()).then(|| {
             let geometry = PackSky::new(device);
@@ -811,6 +870,7 @@ impl PackPost {
                 table: Some(&geometry.layout),
                 depth_write: false,
                 atlas: None,
+                ids: None,
             };
             let basic = post.sky.and_then(|p| build(p, Some(&basic)));
             let textured = Geometry {
@@ -818,6 +878,7 @@ impl PackPost {
                 table: None,
                 depth_write: false,
                 atlas: world.celestial.clone(),
+                ids: None,
             };
             let textured = post.sky_textured.and_then(|p| build(p, Some(&textured)));
             Sky {
@@ -981,6 +1042,7 @@ impl PackPost {
             mips_valid: 0,
             down,
             draws,
+            block_ids,
             timing: super::pack_timing::PassTiming::new(device, queue),
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
@@ -1216,6 +1278,11 @@ impl PackPost {
             let mut rp = self.begin(encoder, &pass);
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
+            if pass.ids
+                && let Some((_, ids)) = &self.block_ids
+            {
+                rp.set_bind_group(3, ids, &[]);
+            }
             if pass.draw {
                 let stage = if translucent {
                     "TERRAIN_TRANSLUCENT"
diff --git a/crates/horizon-shaders/src/block_ids.rs b/crates/horizon-shaders/src/block_ids.rs
new file mode 100644
index 000000000..623473283
--- /dev/null
+++ b/crates/horizon-shaders/src/block_ids.rs
@@ -0,0 +1,120 @@
+//! `block.properties` (spec 4.1): `block.<id>=<block> <block> ...`, each block
+//! `[namespace:]name` with optional state filters `:<property>=<v1>,<v2>`. Values in one filter
+//! are alternatives; separate filters must all match. Names the game does not know are simply
+//! never asked for. Block tags (`%tag`, tier E) are not read yet.
+
+use crate::Properties;
+
+#[derive(Clone, Debug, PartialEq)]
+struct Rule {
+    id: i32,
+    /// `minecraft:stone`.
+    name: String,
+    filters: Vec<(String, Vec<String>)>,
+}
+
+/// The ids `block.properties` gives block states.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct BlockIds {
+    rules: Vec<Rule>,
+    /// Lines skipped and why.
+    pub notes: Vec<String>,
+}
+
+impl BlockIds {
+    pub fn parse(properties: &Properties) -> Self {
+        let mut out = Self::default();
+        for e in &properties.entries {
+            let Some(id) = e.key.strip_prefix("block.") else {
+                continue;
+            };
+            let Ok(id) = id.parse::<i32>() else {
+                // `layer.*` (4.2) and other keys are not ids.
+                continue;
+            };
+            for word in e.value.split_whitespace() {
+                if word.starts_with('%') {
+                    out.notes.push(format!(
+                        "line {}: block tags are not read yet: {word}",
+                        e.line
+                    ));
+                    continue;
+                }
+                let (names, filters): (Vec<&str>, Vec<&str>) =
+                    word.split(':').partition(|p| !p.contains('='));
+                let name = match names[..] {
+                    [name] => format!("minecraft:{name}"),
+                    [namespace, name] => format!("{namespace}:{name}"),
+                    _ => {
+                        out.notes
+                            .push(format!("line {}: not a block name: {word}", e.line));
+                        continue;
+                    }
+                };
+                let filters = filters
+                    .iter()
+                    .filter_map(|f| f.split_once('='))
+                    .map(|(k, v)| (k.to_owned(), v.split(',').map(str::to_owned).collect()))
+                    .collect();
+                out.rules.push(Rule { id, name, filters });
+            }
+        }
+        out
+    }
+
+    /// The id of block `name` (`minecraft:stone`) in the state with `properties`. The rule with
+    /// the most filters that all match wins, then the first in the file (one name belongs to
+    /// one id; a filtered entry is the more specific one).
+    pub fn id<'a>(&self, name: &str, properties: impl Fn(&str) -> Option<&'a str>) -> Option<i32> {
+        self.rules
+            .iter()
+            .filter(|r| r.name == name)
+            .filter(|r| {
+                r.filters
+                    .iter()
+                    .all(|(k, vs)| properties(k).is_some_and(|v| vs.iter().any(|x| x == v)))
+            })
+            .min_by_key(|r| std::cmp::Reverse(r.filters.len()))
+            .map(|r| r.id)
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.rules.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Macros;
+
+    #[test]
+    fn names_states_and_precedence() {
+        let text = "block.10=stone minecraft:dirt mod:thing \\\n grass_block:snowy=false\n\
+                    block.11=grass_block\nblock.12=oak_leaves:persistent=true:distance=1,2 %leaves\n\
+                    layer.translucent=glass\n";
+        let ids = BlockIds::parse(&Properties::parse(text, &Macros::standard()));
+        let none = |_: &str| None;
+        assert_eq!(ids.id("minecraft:stone", none), Some(10));
+        assert_eq!(ids.id("mod:thing", none), Some(10));
+        assert_eq!(ids.id("minecraft:glass", none), None);
+        let snowy = |s: &'static str| move |k: &str| (k == "snowy").then_some(s);
+        // The filtered entry is the more specific one.
+        assert_eq!(ids.id("minecraft:grass_block", snowy("false")), Some(10));
+        assert_eq!(ids.id("minecraft:grass_block", snowy("true")), Some(11));
+        let leaves = |p: &'static str, d: &'static str| {
+            move |k: &str| match k {
+                "persistent" => Some(p),
+                "distance" => Some(d),
+                _ => None,
+            }
+        };
+        assert_eq!(
+            ids.id("minecraft:oak_leaves", leaves("true", "2")),
+            Some(12)
+        );
+        assert_eq!(ids.id("minecraft:oak_leaves", leaves("true", "3")), None);
+        assert_eq!(ids.id("minecraft:oak_leaves", leaves("false", "1")), None);
+        assert_eq!(ids.notes.len(), 1, "{:?}", ids.notes);
+    }
+}
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index f33dfec57..fbad9bee0 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -12,6 +12,7 @@
 //! - [`load_post`]: a dimension's `prepare`, `deferred`, `composite` and `final` programs, in order (2.1).
 //! - [`Macros`] and [`eval_condition`]: the macros packs test, and the `#if` arithmetic (1.5).
 
+mod block_ids;
 mod condition;
 mod config;
 mod custom;
@@ -25,6 +26,7 @@ mod preprocess;
 mod properties;
 mod translate;
 
+pub use block_ids::BlockIds;
 pub use condition::eval_condition;
 pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffers};
 pub use custom::{Custom, Val};
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/README.md b/crates/horizon-shaders/tests/packs/terrain-test/README.md
index 7d2c168cb..13745ed66 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/README.md
+++ b/crates/horizon-shaders/tests/packs/terrain-test/README.md
@@ -3,7 +3,7 @@
 Horizon's own shader pack for testing gbuffers terrain (written for Horizon, no other pack's code).
 `gbuffers_terrain` draws blocks from the atlas with their vertex colour and lightmap, tinted by
 the lightmap coordinate's sky light (cooler where the sky is hidden); `mc_midTexCoord` marks each
-face's centre with a dot, and any stage but solid terrain (translucent terrain falls back to it)
+face's centre with a dot; leaves (id 1 in `block.properties`) are yellow, and any stage but solid terrain (translucent terrain falls back to it)
 is red. `gbuffers_skybasic` draws the sky in its vertex colour, a little greener, with magenta
 stars and a dark red void; `gbuffers_textured` (the fallback of `gbuffers_skytextured`) the sun,
 and the moon tinted green. `composite` puts the depth buffer's view-space distance into the blue
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/block.properties b/crates/horizon-shaders/tests/packs/terrain-test/shaders/block.properties
new file mode 100644
index 000000000..cd08c6a16
--- /dev/null
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/block.properties
@@ -0,0 +1,3 @@
+# Leaves draw yellow in gbuffers_terrain.
+block.1=oak_leaves spruce_leaves birch_leaves jungle_leaves acacia_leaves dark_oak_leaves \
+ mangrove_leaves cherry_leaves azalea_leaves flowering_azalea_leaves pale_oak_leaves
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
index 8be409929..4f6850575 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.fsh
@@ -9,6 +9,7 @@ varying vec2 texcoord;
 varying vec2 lmcoord;
 varying vec2 mid;
 varying vec4 glcolor;
+varying float blockId;
 
 void main() {
     vec4 color = texture2D(texture, texcoord) * glcolor;
@@ -16,6 +17,8 @@ void main() {
     color.rgb *= texture2D(lightmap, lmcoord).rgb;
     // Less sky light: bluer.
     color.rgb = mix(color.rgb * vec3(0.6, 0.7, 1.2), color.rgb, lmcoord.y);
+    // Leaves (block.properties' id 1) yellow.
+    if (abs(blockId - 1.0) < 0.5) color.rgb = vec3(color.g, color.g, 0.0);
     // A dot at the face's centre, one texel wide.
     if (length((texcoord - mid) * vec2(atlasSize)) < 1.0) color.rgb = vec3(1.0, 0.0, 1.0);
     // Any other stage than solid terrain (translucent terrain falls back here): red.
diff --git a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh
index bc16f4aad..1f26fd658 100644
--- a/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh
+++ b/crates/horizon-shaders/tests/packs/terrain-test/shaders/gbuffers_terrain.vsh
@@ -1,11 +1,13 @@
 #version 120
 
 attribute vec4 mc_midTexCoord;
+attribute vec4 mc_Entity;
 
 varying vec2 texcoord;
 varying vec2 lmcoord;
 varying vec2 mid;
 varying vec4 glcolor;
+varying float blockId;
 
 void main() {
     gl_Position = ftransform();
@@ -13,4 +15,5 @@ void main() {
     lmcoord = (gl_TextureMatrix[1] * gl_MultiTexCoord1).xy;
     mid = mc_midTexCoord.xy;
     glcolor = gl_Color;
+    blockId = mc_Entity.x;
 }

From 732efe69bbe9d05c72f9d9dc9e92de920f37388b Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 05:16:38 +0100
Subject: [PATCH 028/270] Shader packs, clean room 25: terrain normals and
 tangents

Flat terrain's vertex stage reads its quad's first three corners from the
arena page (bound per page at set 3, beside mc_Entity's table) and gives
gl_Normal / vaNormal the face normal and at_tangent the tangent along
the texture's u, with w the handedness of bitangent = cross(tangent,
normal) (spec 5.1). The pack's terrain and water pipelines cull back
faces as the game's own terrain does (clockwise front faces, rows being
flipped to GL's): water's surface no longer shows its downward copy.

Flat draws call a hook per arena page (Flat::draw_with); the arena lists
its page buffers.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
5.1; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs            |  61 ++++++-----
 crates/horizon-client/src/gfx/arena.rs      |   5 +
 crates/horizon-client/src/gfx/flat.rs       |  12 +++
 crates/horizon-client/src/gfx/pack_atlas.rs |  41 +++++++-
 crates/horizon-client/src/gfx/pack_post.rs  | 106 +++++++++++++-------
 5 files changed, 162 insertions(+), 63 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 9b7fcc303..f829b9eb1 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2799,6 +2799,7 @@ impl Renderer {
                     depth_write: true,
                     atlas: None,
                     ids: None,
+                    cull: true,
                 }),
                 block_ids,
                 celestial: self
@@ -4070,31 +4071,42 @@ impl Renderer {
         {
             let size = self.world_post.size().unwrap_or([1, 1]);
             let flat = self.flat.as_ref().filter(|_| flat_frame);
-            let mut terrain = |rp: &mut wgpu::RenderPass<'_>, translucent: bool| {
-                if !pack_draws_terrain {
-                    return;
-                }
-                match flat {
-                    Some(flat) => {
-                        let calls = if translucent {
-                            &flat.calls[flat.solid_calls..]
-                        } else {
-                            &flat.calls[..flat.solid_calls]
-                        };
-                        flat.draw(rp, calls, |p| self.arena.buffer(p));
-                    }
-                    None => {
-                        rp.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
-                        rp.set_vertex_buffer(1, self.instances.slice(..));
-                        let (first, count) = if translucent {
-                            (solid_draws, translucent_draws)
-                        } else {
-                            (0, solid_draws)
-                        };
-                        self.draw_sections(rp, &self.indirect, 0, first, count);
-                    }
-                }
+            let pages: Vec<(u32, wgpu::Buffer)> = match flat {
+                Some(_) if pack_draws_terrain => self
+                    .arena
+                    .page_buffers()
+                    .map(|(p, b)| (p, b.clone()))
+                    .collect(),
+                _ => Vec::new(),
             };
+            let mut terrain =
+                |rp: &mut wgpu::RenderPass<'_>,
+                 translucent: bool,
+                 page: &dyn Fn(&mut wgpu::RenderPass<'_>, u32)| {
+                    if !pack_draws_terrain {
+                        return;
+                    }
+                    match flat {
+                        Some(flat) => {
+                            let calls = if translucent {
+                                &flat.calls[flat.solid_calls..]
+                            } else {
+                                &flat.calls[..flat.solid_calls]
+                            };
+                            flat.draw_with(rp, calls, |p| self.arena.buffer(p), page);
+                        }
+                        None => {
+                            rp.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
+                            rp.set_vertex_buffer(1, self.instances.slice(..));
+                            let (first, count) = if translucent {
+                                (solid_draws, translucent_draws)
+                            } else {
+                                (0, solid_draws)
+                            };
+                            self.draw_sections(rp, &self.indirect, 0, first, count);
+                        }
+                    }
+                };
             post.run(
                 &self.device,
                 &self.queue,
@@ -4106,6 +4118,7 @@ impl Renderer {
                 &frame.pack,
                 size,
                 [self.config.width, self.config.height],
+                &pages,
                 &mut terrain,
             );
             self.pack_post = Some((dimension, Some(post)));
diff --git a/crates/horizon-client/src/gfx/arena.rs b/crates/horizon-client/src/gfx/arena.rs
index dbbf70140..34b4d332d 100644
--- a/crates/horizon-client/src/gfx/arena.rs
+++ b/crates/horizon-client/src/gfx/arena.rs
@@ -155,6 +155,11 @@ impl Arena {
     pub fn has_page(&self, page: u32) -> bool {
         self.pages.get(page as usize).is_some_and(Option::is_some)
     }
+    /// Each live page's buffer, by page.
+    pub fn page_buffers(&self) -> impl Iterator<Item = (u32, &wgpu::Buffer)> {
+        let pages = self.pages.iter().enumerate();
+        pages.filter_map(|(i, p)| Some((i as u32, &p.as_ref()?.buffer)))
+    }
     pub fn buffer(&self, page: u32) -> &wgpu::Buffer {
         &self.pages[page as usize]
             .as_ref()
diff --git a/crates/horizon-client/src/gfx/flat.rs b/crates/horizon-client/src/gfx/flat.rs
index 4c337025a..d167e3f3c 100644
--- a/crates/horizon-client/src/gfx/flat.rs
+++ b/crates/horizon-client/src/gfx/flat.rs
@@ -649,10 +649,22 @@ impl Flat {
         pass: &mut wgpu::RenderPass<'_>,
         calls: &[Call],
         vertices: impl Fn(u32) -> &'a wgpu::Buffer,
+    ) {
+        self.draw_with(pass, calls, vertices, |_, _| {});
+    }
+    /// `draw`, calling `page` before each run of calls from one arena page (a shader pack binds
+    /// that page's vertices for reading).
+    pub fn draw_with<'a>(
+        &self,
+        pass: &mut wgpu::RenderPass<'_>,
+        calls: &[Call],
+        vertices: impl Fn(u32) -> &'a wgpu::Buffer,
+        page: impl Fn(&mut wgpu::RenderPass<'_>, u32),
     ) {
         pass.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
         for call in calls {
             self.bind_page(pass, call.page, &vertices);
+            page(pass, call.page);
             pass.draw_indexed(call.first..call.first + call.count, 0, 0..1);
         }
     }
diff --git a/crates/horizon-client/src/gfx/pack_atlas.rs b/crates/horizon-client/src/gfx/pack_atlas.rs
index ac56985fd..e1727f1fe 100644
--- a/crates/horizon-client/src/gfx/pack_atlas.rs
+++ b/crates/horizon-client/src/gfx/pack_atlas.rs
@@ -113,6 +113,30 @@ impl PackAtlas {
     }
 }
 
+/// GLSL: the face normal and tangent of a flat-drawn vertex, from its quad's first three corners
+/// (quads are four consecutive vertices of the page; position words 0-2, UV word 3).
+const FACE: &str = "    uint hz_q = (uint(gl_VertexIndex) & ~3u) * 6u;\n    \
+    vec3 hz_p0 = uintBitsToFloat(uvec3(hz_vertices[hz_q], hz_vertices[hz_q + 1u], hz_vertices[hz_q + 2u]));\n    \
+    vec3 hz_p1 = uintBitsToFloat(uvec3(hz_vertices[hz_q + 6u], hz_vertices[hz_q + 7u], hz_vertices[hz_q + 8u]));\n    \
+    vec3 hz_p2 = uintBitsToFloat(uvec3(hz_vertices[hz_q + 12u], hz_vertices[hz_q + 13u], hz_vertices[hz_q + 14u]));\n    \
+    uvec3 hz_w = uvec3(hz_vertices[hz_q + 3u], hz_vertices[hz_q + 9u], hz_vertices[hz_q + 15u]);\n    \
+    vec2 hz_t0 = vec2(hz_w.x & 65535u, hz_w.x >> 16u);\n    \
+    vec2 hz_d1 = vec2(hz_w.y & 65535u, hz_w.y >> 16u) - hz_t0;\n    \
+    vec2 hz_d2 = vec2(hz_w.z & 65535u, hz_w.z >> 16u) - hz_t0;\n    \
+    vec3 hz_e1 = hz_p1 - hz_p0;\n    \
+    vec3 hz_e2 = hz_p2 - hz_p0;\n    \
+    vec3 hz_n = cross(hz_e1, hz_e2);\n    \
+    if (dot(hz_n, hz_n) > 1e-12) {\n        \
+        hz_Normal = normalize(hz_n);\n        \
+        float hz_r = hz_d1.x * hz_d2.y - hz_d2.x * hz_d1.y;\n        \
+        vec3 hz_t = (hz_e1 * hz_d2.y - hz_e2 * hz_d1.y) * sign(hz_r);\n        \
+        vec3 hz_b = (hz_e2 * hz_d1.x - hz_e1 * hz_d2.x) * sign(hz_r);\n        \
+        if (dot(hz_t, hz_t) > 1e-12) {\n            \
+            hz_t = normalize(hz_t - hz_Normal * dot(hz_Normal, hz_t));\n            \
+            hz_tangent = vec4(hz_t, dot(cross(hz_t, hz_Normal), hz_b) < 0.0 ? -1.0 : 1.0);\n        \
+        }\n    \
+    }\n";
+
 impl PackAtlas {
     /// The vertex inputs of a gbuffers program drawing terrain (`TerrainVertex`, terrain.wgsl's
     /// `vs_terrain` or, for `flat` draws, `vs_terrain_flat`), in atlas coordinates.
@@ -127,9 +151,11 @@ impl PackAtlas {
                 "layout(set = 1, binding = 0) readonly buffer HzBlockSlots { uint hz_block_slots[]; };\n\
                  layout(set = 1, binding = 1) readonly buffer HzSlotOrigins { vec4 hz_slot_origins[]; };\n",
             );
-            // `mc_Entity` of each sprite layer: id, then 1 for fluids or -1 (the game's table).
+            // `mc_Entity` of each sprite layer: id, then 1 for fluids or -1 (the game's table),
+            // and the arena page's vertices (`TerrainVertex`, six words each).
             declarations.push_str(
-                "layout(set = 3, binding = 0) readonly buffer HzBlockIds { int hz_block_ids[]; };\n",
+                "layout(set = 3, binding = 0) readonly buffer HzBlockIds { int hz_block_ids[]; };\n\
+                 layout(set = 3, binding = 1) readonly buffer HzVertices { uint hz_vertices[]; };\n",
             );
             "hz_slot_origins[hz_block_slots[uint(gl_VertexIndex) >> 8u]]"
         } else {
@@ -153,10 +179,15 @@ impl PackAtlas {
              hz_MultiTexCoord1 = vec4(float(hz_v_light.y), float(hz_v_light.x), 0.0, 1.0);\n    \
              hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
              hz_Color = hz_v_color;\n    \
-             hz_Normal = vec3(0.0, 1.0, 0.0);\n",
+             hz_Normal = vec3(0.0, 1.0, 0.0);\n    \
+             hz_tangent = vec4(1.0, 0.0, 0.0, 1.0);\n",
             scale[0], scale[1],
         );
-        declarations.push_str("vec2 hz_cell; vec2 hz_scale;\n");
+        let mut body = body;
+        if flat {
+            body.push_str(FACE);
+        }
+        declarations.push_str("vec2 hz_cell; vec2 hz_scale; vec4 hz_tangent;\n");
         let entity = if flat {
             "vec4(float(hz_block_ids[2u * hz_layer]), float(hz_block_ids[2u * hz_layer + 1u]), 0.0, 0.0)"
         } else {
@@ -168,7 +199,7 @@ impl PackAtlas {
                 "mc_midTexCoord",
                 "vec4((hz_cell + 0.5) * hz_scale, 0.0, 1.0)",
             ),
-            ("at_tangent", "vec4(1.0, 0.0, 0.0, 1.0)"),
+            ("at_tangent", "hz_tangent"),
             ("vaPosition", "hz_Vertex.xyz"),
             ("vaUV0", "hz_MultiTexCoord0.xy"),
             ("vaUV2", "hz_MultiTexCoord1.xy"),
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index ba8fe62e7..972ac82f3 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -211,8 +211,10 @@ pub struct PackPost {
     down: HashMap<wgpu::TextureFormat, (wgpu::RenderPipeline, wgpu::BindGroupLayout)>,
     /// The per-draw uniforms of gbuffers programs.
     draws: DrawUniforms,
-    /// `mc_Entity`'s table of flat terrain, and its bind group.
-    block_ids: Option<(wgpu::BindGroupLayout, wgpu::BindGroup)>,
+    /// Set 3 of flat terrain (`mc_Entity`'s table) and its bind group for each arena page,
+    /// with the page buffer it was made for.
+    block_ids: Option<(wgpu::BindGroupLayout, wgpu::Buffer)>,
+    page_groups: HashMap<u32, (wgpu::Buffer, wgpu::BindGroup)>,
     /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
     timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
@@ -498,8 +500,14 @@ fn attach(
     })
 }
 
-/// `mc_Entity`'s table as a storage buffer (vertex stage) at set 3; -1 pairs when empty.
-fn block_ids(device: &wgpu::Device, table: &[i32]) -> (wgpu::BindGroupLayout, wgpu::BindGroup) {
+/// Draws the game's terrain (`true`: translucent) into a pass; calls its third argument with
+/// each arena page before drawing from it.
+pub(super) type TerrainDraw<'a> =
+    dyn FnMut(&mut wgpu::RenderPass<'_>, bool, &dyn Fn(&mut wgpu::RenderPass<'_>, u32)) + 'a;
+
+/// Set 3 of flat terrain, read by the vertex stage: `mc_Entity`'s table (-1 pairs when empty)
+/// and, per arena page, the page's vertices (a vertex reads its quad's corners for its normal).
+fn block_ids(device: &wgpu::Device, table: &[i32]) -> (wgpu::BindGroupLayout, wgpu::Buffer) {
     let empty = [-1, -1];
     let table = if table.is_empty() { &empty[..] } else { table };
     let buffer = wgpu::util::DeviceExt::create_buffer_init(
@@ -510,28 +518,21 @@ fn block_ids(device: &wgpu::Device, table: &[i32]) -> (wgpu::BindGroupLayout, wg
             usage: wgpu::BufferUsages::STORAGE,
         },
     );
+    let storage = |binding| wgpu::BindGroupLayoutEntry {
+        binding,
+        visibility: wgpu::ShaderStages::VERTEX,
+        ty: wgpu::BindingType::Buffer {
+            ty: wgpu::BufferBindingType::Storage { read_only: true },
+            has_dynamic_offset: false,
+            min_binding_size: None,
+        },
+        count: None,
+    };
     let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
-        label: Some("Shader pack block ids"),
-        entries: &[wgpu::BindGroupLayoutEntry {
-            binding: 0,
-            visibility: wgpu::ShaderStages::VERTEX,
-            ty: wgpu::BindingType::Buffer {
-                ty: wgpu::BufferBindingType::Storage { read_only: true },
-                has_dynamic_offset: false,
-                min_binding_size: None,
-            },
-            count: None,
-        }],
+        label: Some("Shader pack terrain"),
+        entries: &[storage(0), storage(1)],
     });
-    let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
-        label: Some("Shader pack block ids"),
-        layout: &layout,
-        entries: &[wgpu::BindGroupEntry {
-            binding: 0,
-            resource: buffer.as_entire_binding(),
-        }],
-    });
-    (layout, group)
+    (layout, buffer)
 }
 
 /// The game's geometry a gbuffers program draws: its vertex buffers and, for flat draws
@@ -545,6 +546,8 @@ pub(super) struct Geometry<'a> {
     pub atlas: Option<wgpu::TextureView>,
     /// `mc_Entity`'s table at set 3 (flat terrain).
     pub ids: Option<&'a wgpu::BindGroupLayout>,
+    /// Back faces are culled, as for the game's own terrain.
+    pub cull: bool,
 }
 
 /// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
@@ -728,7 +731,12 @@ fn build_pass(
                 compilation_options: Default::default(),
                 buffers: geometry.map_or(&[], |g| g.buffers),
             },
-            primitive: Default::default(),
+            // Rows flipped to GL's turn front faces clockwise.
+            primitive: wgpu::PrimitiveState {
+                front_face: wgpu::FrontFace::Cw,
+                cull_mode: geometry.filter(|g| g.cull).map(|_| wgpu::Face::Back),
+                ..Default::default()
+            },
             depth_stencil: geometry.map(|g| wgpu::DepthStencilState {
                 format: wgpu::TextureFormat::Depth32Float,
                 depth_write_enabled: Some(g.depth_write),
@@ -854,6 +862,7 @@ impl PackPost {
             depth_write: g.depth_write,
             atlas: g.atlas.clone(),
             ids: block_ids.as_ref().map(|i| &i.0),
+            cull: g.cull,
         });
         let terrain = post
             .terrain
@@ -871,6 +880,7 @@ impl PackPost {
                 depth_write: false,
                 atlas: None,
                 ids: None,
+                cull: false,
             };
             let basic = post.sky.and_then(|p| build(p, Some(&basic)));
             let textured = Geometry {
@@ -879,6 +889,7 @@ impl PackPost {
                 depth_write: false,
                 atlas: world.celestial.clone(),
                 ids: None,
+                cull: false,
             };
             let textured = post.sky_textured.and_then(|p| build(p, Some(&textured)));
             Sky {
@@ -1043,6 +1054,7 @@ impl PackPost {
             down,
             draws,
             block_ids,
+            page_groups: HashMap::new(),
             timing: super::pack_timing::PassTiming::new(device, queue),
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
@@ -1253,7 +1265,7 @@ impl PackPost {
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
         translucent: bool,
-        draw: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
+        draw: &mut TerrainDraw<'_>,
     ) {
         let slot = if translucent {
             &mut self.water
@@ -1278,11 +1290,6 @@ impl PackPost {
             let mut rp = self.begin(encoder, &pass);
             rp.set_pipeline(&pass.pipeline);
             rp.set_bind_group(0, &group, &[]);
-            if pass.ids
-                && let Some((_, ids)) = &self.block_ids
-            {
-                rp.set_bind_group(3, ids, &[]);
-            }
             if pass.draw {
                 let stage = if translucent {
                     "TERRAIN_TRANSLUCENT"
@@ -1291,7 +1298,13 @@ impl PackPost {
                 };
                 self.draws.bind(&mut rp, stage);
             }
-            draw(&mut rp, translucent);
+            let (groups, ids) = (&self.page_groups, pass.ids);
+            let page = |rp: &mut wgpu::RenderPass<'_>, page: u32| {
+                if let Some((_, group)) = groups.get(&page).filter(|_| ids) {
+                    rp.set_bind_group(3, group, &[]);
+                }
+            };
+            draw(&mut rp, translucent, &page);
         }
         self.mips_valid &= !pass.written;
         if translucent {
@@ -1362,7 +1375,7 @@ impl PackPost {
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
         frame: &super::Frame,
-        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
+        terrain: &mut TerrainDraw<'_>,
     ) {
         if super::sky_visible(frame) {
             self.draw_sky(device, queue, encoder, size, frame);
@@ -1533,9 +1546,34 @@ impl PackPost {
         inputs: &PackInputs,
         size: [u32; 2],
         window: [u32; 2],
-        terrain: &mut dyn FnMut(&mut wgpu::RenderPass<'_>, bool),
+        pages: &[(u32, wgpu::Buffer)],
+        terrain: &mut TerrainDraw<'_>,
     ) {
         self.resize(device, size);
+        if let Some((layout, ids)) = &self.block_ids {
+            // A page that grew has a new buffer.
+            self.page_groups
+                .retain(|p, (b, _)| pages.iter().any(|(q, c)| q == p && c == b));
+            for (page, buffer) in pages {
+                self.page_groups.entry(*page).or_insert_with(|| {
+                    let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+                        label: Some("Shader pack terrain"),
+                        layout,
+                        entries: &[
+                            wgpu::BindGroupEntry {
+                                binding: 0,
+                                resource: ids.as_entire_binding(),
+                            },
+                            wgpu::BindGroupEntry {
+                                binding: 1,
+                                resource: buffer.as_entire_binding(),
+                            },
+                        ],
+                    });
+                    (buffer.clone(), group)
+                });
+            }
+        }
         if let Some(t) = &mut self.timing {
             t.begin(device, queue);
         }

From bf59c0c4f7c532af62056a413db921adfc44885e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:11:52 +0100
Subject: [PATCH 029/270] Shader packs, clean room 26: biome uniforms and
 constants

Custom uniform expressions and programs now see the biome at the camera:
`biome`, `biome_category`, `biome_precipitation`, `temperature` and
`rainfall`, and the `BIOME_*`, `CAT_*` and `PPT_*` constants (spec 3.4).
Before, `biome` and every `BIOME_*` read 0, so a test such as
`biome == BIOME_PALE_GARDEN` held everywhere: Complementary drew the pale
garden's fog over every world, and BSL treated every biome as cold, dry,
swampy and so on at once.

OQ-11: `biome` is the index in the game's biome registry (vanilla's
biomes sorted by identifier); names from before the 1.18 renames map to
their successors; a `BIOME_` name that matches no biome reads -1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/shader_packs.rs   |  18 +-
 .../horizon-client/src/gfx/pack_uniforms.rs   |  16 ++
 crates/horizon-shaders/src/biomes.rs          | 159 ++++++++++++++++++
 crates/horizon-shaders/src/custom.rs          |  55 +++++-
 crates/horizon-shaders/src/lib.rs             |   2 +
 5 files changed, 242 insertions(+), 8 deletions(-)
 create mode 100644 crates/horizon-shaders/src/biomes.rs

diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index 7fa2ea3f6..f5f7a5fba 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -43,7 +43,10 @@ impl Game<'_> {
                     }
                     let folder = dimension_folder(&pack, dimension);
                     let inputs = renderer.pack_inputs();
-                    let post = load_post(&pack, &folder, &properties, &macros, &inputs);
+                    let mut post = load_post(&pack, &folder, &properties, &macros, &inputs);
+                    let biomes = self.res.biomes();
+                    let names: Vec<&str> = biomes.list.iter().map(|b| b.name.as_str()).collect();
+                    post.custom.set_biomes(&names);
                     let text = pack.read_text("block.properties").unwrap_or_default();
                     let ids = BlockIds::parse(&Properties::parse(&text, &macros));
                     for note in &ids.notes {
@@ -80,6 +83,12 @@ impl Game<'_> {
         let lerp = |(old, new): (f32, f32)| old + (new - old) * partial;
         let at = camera.floor().as_ivec3();
         let light = self.world.light(at.x, at.y, at.z);
+        let biome = self
+            .world
+            .chunks
+            .get(&(at.x >> 4, at.z >> 4))
+            .map(|c| c.biome(at.x, at.y, at.z));
+        let info = biome.map(|b| self.res.biomes().get(b));
         PackInputs {
             day_time: self.world.day_time,
             rain: lerp(self.world.weather.rain_level),
@@ -94,6 +103,13 @@ impl Game<'_> {
             eye_light: [i32::from(light & 15), i32::from(light >> 4)],
             hide_gui: self.ui.hide_gui,
             brightness: self.settings.gamma,
+            biome: biome.map_or(-1, i32::from),
+            biome_category: info.map_or(0, |b| horizon_shaders::biome_category(&b.name)),
+            biome_precipitation: info.map_or(0, |b| {
+                horizon_shaders::biome_precipitation(b.precipitation, b.temperature)
+            }),
+            temperature: info.map_or(0.0, |b| b.temperature),
+            rainfall: info.map_or(0.0, |b| b.downfall),
         }
     }
 }
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index c7c4cfd8b..ad53b509a 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -23,6 +23,12 @@ pub struct PackInputs {
     pub hide_gui: bool,
     /// The brightness option, 0..1.
     pub brightness: f32,
+    /// The biome at the camera (3.4): registry id, `CAT_*`, `PPT_*`, temperature, downfall.
+    pub biome: i32,
+    pub biome_category: i32,
+    pub biome_precipitation: i32,
+    pub temperature: f32,
+    pub rainfall: f32,
 }
 
 /// One uniform's value: up to 16 floats or 3 integers.
@@ -134,6 +140,11 @@ pub const NAMES: &[&str] = &[
     "heldBlockLightValue",
     "heldBlockLightValue2",
     "renderStage",
+    "biome",
+    "biome_category",
+    "biome_precipitation",
+    "temperature",
+    "rainfall",
     "gbufferModelView",
     "gbufferModelViewInverse",
     "gbufferProjection",
@@ -290,6 +301,11 @@ impl FrameUniforms {
                 "screenBrightness" => Value::f(&[inputs.brightness]),
                 "hideGUI" => Value::i(&[inputs.hide_gui as i32]),
                 "eyeBrightness" => Value::i(&eye.map(|v| v as i32)),
+                "biome" => Value::i(&[inputs.biome]),
+                "biome_category" => Value::i(&[inputs.biome_category]),
+                "biome_precipitation" => Value::i(&[inputs.biome_precipitation]),
+                "temperature" => Value::f(&[inputs.temperature]),
+                "rainfall" => Value::f(&[inputs.rainfall]),
                 "eyeBrightnessSmooth" => Value::i(&self.eye_smooth.map(|v| v.round() as i32)),
                 "gbufferModelView" => m4(view),
                 "gbufferModelViewInverse" => m4(view.inverse()),
diff --git a/crates/horizon-shaders/src/biomes.rs b/crates/horizon-shaders/src/biomes.rs
new file mode 100644
index 000000000..c9ede57e0
--- /dev/null
+++ b/crates/horizon-shaders/src/biomes.rs
@@ -0,0 +1,159 @@
+//! The biome parameters and constants of custom uniform expressions (spec 3.4): `BIOME_<NAME>`,
+//! `CAT_<NAME>` and `PPT_<NAME>`.
+//!
+//! Decisions (impl-plan.md, OQ-11):
+//! - `biome` is the biome's index in the game's biome registry, which lists vanilla's biomes
+//!   sorted by identifier; `BIOME_<NAME>` is the index of `minecraft:<name>`. Names from before
+//!   the 1.18 renames map to the biome that replaced them. A `BIOME_` name that matches no biome
+//!   reads -1, so it never equals the player's biome.
+//! - `biome_category` comes from the biome's name (categories left the game in 1.19).
+
+use std::collections::HashMap;
+
+/// `CAT_*`, in the order of their values.
+pub const CATEGORIES: [&str; 17] = [
+    "NONE",
+    "TAIGA",
+    "EXTREME_HILLS",
+    "JUNGLE",
+    "MESA",
+    "PLAINS",
+    "SAVANNA",
+    "ICY",
+    "THE_END",
+    "BEACH",
+    "FOREST",
+    "OCEAN",
+    "DESERT",
+    "RIVER",
+    "SWAMP",
+    "MUSHROOM",
+    "NETHER",
+];
+
+/// Old biome names and the biomes that replaced them.
+const LEGACY: &[(&str, &str)] = &[
+    ("EXTREME_HILLS", "windswept_hills"),
+    ("MOUNTAINS", "windswept_hills"),
+    ("GRAVELLY_MOUNTAINS", "windswept_gravelly_hills"),
+    ("WOODED_MOUNTAINS", "windswept_forest"),
+    ("SHATTERED_SAVANNA", "windswept_savanna"),
+    ("GIANT_TREE_TAIGA", "old_growth_pine_taiga"),
+    ("GIANT_SPRUCE_TAIGA", "old_growth_spruce_taiga"),
+    ("TALL_BIRCH_FOREST", "old_growth_birch_forest"),
+    ("SNOWY_TUNDRA", "snowy_plains"),
+    ("JUNGLE_EDGE", "sparse_jungle"),
+    ("WOODED_BADLANDS_PLATEAU", "wooded_badlands"),
+    ("STONE_SHORE", "stony_shore"),
+    ("NETHER", "nether_wastes"),
+];
+
+/// The constants every pack sees: `CAT_*` and `PPT_*`, plus `BIOME_*` for `biomes` (the
+/// registry's identifiers, in id order).
+pub fn constants(biomes: &[&str]) -> HashMap<String, f64> {
+    let mut out: HashMap<String, f64> = CATEGORIES
+        .iter()
+        .enumerate()
+        .map(|(i, c)| (format!("CAT_{c}"), i as f64))
+        .collect();
+    for (i, p) in ["NONE", "RAIN", "SNOW"].iter().enumerate() {
+        out.insert(format!("PPT_{p}"), i as f64);
+    }
+    let index = |name: &str| {
+        biomes
+            .iter()
+            .position(|b| b.strip_prefix("minecraft:") == Some(name))
+    };
+    for (i, b) in biomes.iter().enumerate() {
+        if let Some(name) = b.strip_prefix("minecraft:") {
+            out.insert(format!("BIOME_{}", name.to_ascii_uppercase()), i as f64);
+        }
+    }
+    for (old, new) in LEGACY {
+        if let Some(i) = index(new) {
+            out.entry(format!("BIOME_{old}")).or_insert(i as f64);
+        }
+    }
+    out
+}
+
+/// `biome_category` of the biome `minecraft:<name>`.
+pub fn category(name: &str) -> i32 {
+    let name = name.strip_prefix("minecraft:").unwrap_or(name);
+    let has = |words: &[&str]| words.iter().any(|w| name.contains(w));
+    let cat = if name == "the_void" {
+        "NONE"
+    } else if name == "the_end" || name.starts_with("end_") || name == "small_end_islands" {
+        "THE_END"
+    } else if has(&["nether", "crimson", "warped", "basalt", "soul_sand"]) {
+        "NETHER"
+    } else if has(&["ocean"]) {
+        "OCEAN"
+    } else if has(&["river"]) {
+        "RIVER"
+    } else if has(&["beach", "shore"]) {
+        "BEACH"
+    } else if has(&["swamp"]) {
+        "SWAMP"
+    } else if has(&["mushroom"]) {
+        "MUSHROOM"
+    } else if has(&["desert"]) {
+        "DESERT"
+    } else if has(&["badlands"]) {
+        "MESA"
+    } else if has(&["savanna"]) {
+        "SAVANNA"
+    } else if has(&["jungle"]) {
+        "JUNGLE"
+    } else if has(&["taiga"]) {
+        "TAIGA"
+    } else if has(&["windswept", "peaks", "slopes", "meadow", "grove"]) && name != "cherry_grove" {
+        "EXTREME_HILLS"
+    } else if has(&["frozen", "snowy", "ice"]) {
+        "ICY"
+    } else if has(&["forest", "garden", "cherry"]) {
+        "FOREST"
+    } else if has(&["plains"]) {
+        "PLAINS"
+    } else {
+        "NONE"
+    };
+    CATEGORIES.iter().position(|c| *c == cat).unwrap_or(0) as i32
+}
+
+/// `biome_precipitation`: none where the biome has none, else rain from temperature 0.15 up,
+/// snow below it (spec 3.4).
+pub fn precipitation(has_precipitation: bool, temperature: f32) -> i32 {
+    match (has_precipitation, temperature >= 0.15) {
+        (false, _) => 0,
+        (true, true) => 1,
+        (true, false) => 2,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn constants_categories_and_precipitation() {
+        let c = constants(&[
+            "minecraft:badlands",
+            "minecraft:pale_garden",
+            "minecraft:windswept_hills",
+        ]);
+        assert_eq!(c["BIOME_PALE_GARDEN"], 1.0);
+        assert_eq!(c["BIOME_EXTREME_HILLS"], 2.0);
+        assert_eq!(c["CAT_NETHER"], 16.0);
+        assert_eq!(c["PPT_SNOW"], 2.0);
+        assert!(!c.contains_key("BIOME_SULFUR_CAVES"));
+        assert_eq!(category("minecraft:pale_garden"), 10);
+        assert_eq!(category("minecraft:deep_frozen_ocean"), 11);
+        assert_eq!(category("minecraft:snowy_taiga"), 1);
+        assert_eq!(category("minecraft:crimson_forest"), 16);
+        assert_eq!(category("minecraft:cherry_grove"), 10);
+        assert_eq!(precipitation(true, 0.0), 2);
+        assert_eq!(precipitation(true, 0.8), 1);
+        assert_eq!(precipitation(false, 2.0), 0);
+    }
+}
diff --git a/crates/horizon-shaders/src/custom.rs b/crates/horizon-shaders/src/custom.rs
index 34510247e..e27472816 100644
--- a/crates/horizon-shaders/src/custom.rs
+++ b/crates/horizon-shaders/src/custom.rs
@@ -87,6 +87,8 @@ pub struct Custom {
     smooth: HashMap<usize, f64>,
     seed: u64,
     unknown: HashSet<String>,
+    /// `BIOME_*`, `CAT_*` and `PPT_*` (crate::biomes).
+    constants: HashMap<String, f64>,
     /// Expressions that did not parse, and unknown names, as `key: message`.
     pub notes: Vec<String>,
     calls: usize,
@@ -97,6 +99,7 @@ impl Custom {
     pub fn parse(properties: &Properties) -> Self {
         let mut out = Custom {
             seed: 0x9e37_79b9_7f4a_7c15,
+            constants: crate::biomes::constants(&[]),
             ..Default::default()
         };
         for e in &properties.entries {
@@ -126,6 +129,11 @@ impl Custom {
         out
     }
 
+    /// Names the game's biomes (registry identifiers, in id order) for `BIOME_*`.
+    pub fn set_biomes(&mut self, biomes: &[&str]) {
+        self.constants = crate::biomes::constants(biomes);
+    }
+
     /// The uniforms' names and declared types, in file order.
     pub fn uniforms(&self) -> impl Iterator<Item = (&str, &str)> {
         self.items
@@ -189,8 +197,19 @@ impl Custom {
                     "pi" => Some(Val::scalar(std::f64::consts::PI)),
                     "true" => Some(Val::scalar(1.0)),
                     "false" => Some(Val::scalar(0.0)),
-                    n => vars.get(n).copied().or_else(|| builtin(n)),
+                    n => vars
+                        .get(n)
+                        .copied()
+                        .or_else(|| builtin(n))
+                        .or_else(|| self.constants.get(n).map(|&x| Val::scalar(x))),
                 };
+                if v.is_none() && name.starts_with("BIOME_") {
+                    if self.unknown.insert(name.clone()) {
+                        self.notes
+                            .push(format!("`{name}` names no biome; it reads -1"));
+                    }
+                    return Val::scalar(-1.0);
+                }
                 let Some(v) = v else {
                     if self.unknown.insert(name.clone()) {
                         self.notes.push(format!("`{name}` is unknown; it reads 0"));
@@ -523,16 +542,18 @@ mod tests {
              uniform.vec3.e = vec3(a, cameraPosition.y, 2) * 2\n\
              uniform.float.f = if(a < 0, 1, a < 7, 2, 3) + clamp(fmod(-1, 4), 0, 2.5) + min(4, 2, 3)\n\
              uniform.float.g = gbufferModelView.1.0 + frac(sunAngle - 0.25) + pi * 0\n\
-             uniform.float.h = unknownThing + in(biome, 3, BIOME_DESERT)\n",
+             uniform.float.h = unknownThing + in(biome, 3, BIOME_DESERT)\n\
+             uniform.int.i = biome == BIOME_PALE_GARDEN || biome == BIOME_OLD\n\
+             uniform.int.j = CAT_OCEAN + PPT_RAIN\n",
         );
+        c.set_biomes(&["minecraft:beach", "minecraft:desert"]);
         assert!(c.notes.is_empty(), "{:?}", c.notes);
         let names: Vec<_> = c.uniforms().map(|u| u.0).collect();
-        assert_eq!(names, ["b", "c", "d", "e", "f", "g", "h"]);
+        assert_eq!(names, ["b", "c", "d", "e", "f", "g", "h", "i", "j"]);
         let builtin = |n: &str| match n {
             "cameraPosition" => Some(Val::vector(&[1.0, 64.0, 2.0])),
             "sunAngle" => Some(Val::scalar(0.125)),
-            "biome" => Some(Val::scalar(5.0)),
-            "BIOME_DESERT" => Some(Val::scalar(5.0)),
+            "biome" => Some(Val::scalar(1.0)),
             "gbufferModelView" => {
                 let mut m = Val::scalar(0.0);
                 m.v[1] = 9.0; // column 0, row 1
@@ -543,9 +564,29 @@ mod tests {
         };
         let v = c.eval(0.016, &builtin);
         let x: Vec<f64> = v.iter().map(|v| v.v[0]).collect();
-        assert_eq!(x, [3.0, 1.0, -3.0, 12.0, 2.0 + 2.5 + 2.0, 9.0 + 0.875, 1.0]);
+        assert_eq!(
+            x,
+            [
+                3.0,
+                1.0,
+                -3.0,
+                12.0,
+                2.0 + 2.5 + 2.0,
+                9.0 + 0.875,
+                1.0,
+                0.0,
+                12.0
+            ]
+        );
         assert_eq!(&v[3].v[..3], &[12.0, 128.0, 4.0]);
-        assert_eq!(c.notes, ["`unknownThing` is unknown; it reads 0"]);
+        assert_eq!(
+            c.notes,
+            [
+                "`unknownThing` is unknown; it reads 0",
+                "`BIOME_PALE_GARDEN` names no biome; it reads -1",
+                "`BIOME_OLD` names no biome; it reads -1"
+            ]
+        );
     }
 
     #[test]
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index fbad9bee0..8684be867 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -12,6 +12,7 @@
 //! - [`load_post`]: a dimension's `prepare`, `deferred`, `composite` and `final` programs, in order (2.1).
 //! - [`Macros`] and [`eval_condition`]: the macros packs test, and the `#if` arithmetic (1.5).
 
+mod biomes;
 mod block_ids;
 mod condition;
 mod config;
@@ -26,6 +27,7 @@ mod preprocess;
 mod properties;
 mod translate;
 
+pub use biomes::{category as biome_category, precipitation as biome_precipitation};
 pub use block_ids::BlockIds;
 pub use condition::eval_condition;
 pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffers};

From 9a8453c61217599122f7569da3d60217c2996619 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:11:52 +0100
Subject: [PATCH 030/270] Shader packs, clean room 27: sample mip chains only
 while current

A program sampled every level of a buffer that has mipmaps, even after a
later program had rewritten the buffer: the levels below the first were
stale. Complementary's FXAA, which samples its colour buffer with implicit
derivatives inside branches, picked those levels at edges and drew black
dots along every edge. A buffer now binds its whole chain only while the
chain matches its content, and its first level otherwise (6.1.7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_post.rs | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 972ac82f3..c3a67f22e 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -156,7 +156,9 @@ struct Pass {
     atlas: Option<wgpu::TextureView>,
     /// Reads `mc_Entity`'s table (`PackPost::block_ids`).
     ids: bool,
-    groups: HashMap<u16, wgpu::BindGroup>,
+    /// Bind groups by the sides read (low 16 bits) and the buffers whose mip chain is current
+    /// (high 16 bits).
+    groups: HashMap<u32, wgpu::BindGroup>,
 }
 
 /// One side of a buffer with mipmaps.
@@ -1152,7 +1154,10 @@ impl PackPost {
             queue.write_buffer(&pass.ubo, 0, &pass.block);
         }
         let targets = self.targets.as_ref().expect("resized");
-        let key = self.main & pass.reads;
+        // A chain is sampled only while it is current: a buffer written since its last chain
+        // reads its first level, never stale levels (6.1.7).
+        let current = self.mips_valid & self.mipped & pass.reads;
+        let key = u32::from(self.main & pass.reads) | u32::from(current) << 16;
         let group = pass.groups.entry(key).or_insert_with(|| {
             let mut entries = vec![wgpu::BindGroupEntry {
                 binding: 0,
@@ -1163,9 +1168,9 @@ impl PackPost {
                     Source::Color(i) => {
                         let side = usize::from(key & 1 << i != 0);
                         match (&targets.mips[i], &targets.color[i]) {
-                            (Some(m), _) => &m[side].all,
-                            (None, Some(t)) => &t[side],
-                            (None, None) => &self.dummy,
+                            (Some(m), _) if current & 1 << i != 0 => &m[side].all,
+                            (_, Some(t)) => &t[side],
+                            (_, None) => &self.dummy,
                         }
                     }
                     Source::Depth => &targets.depth,

From 379692f35545e149cc323f48966697b00a24fffa Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:19:43 +0100
Subject: [PATCH 031/270] Port YUNG's worldgen as written; delete the old YUNG
 conversion and assembler
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clean-room (spec-yungsapi.md §2, §3, §5; no mod source read; the legacy
files were deleted unread). horizon-port-pack's new `yung` module carries
`yungsapi:yung_jigsaw` structures and `yungsapi:yung_single_element` pool
elements as the mods write them, so players' packs reach the YUNG draws of
the jigsaw assembler. Fields whose behaviour the specification leaves open
(adapt_noise, max_y/min_y, enhanced terrain, element conditions, modifiers,
priorities, depths, ignore_bounds) are counted as lost by name. YUNG's
other structure, placement and processor types go to the general code
(unsupported or dropped) until the specification covers them.

Deleted: legacy_structure_mods/yung.rs, horizon-world's structure/yung.rs,
the `horizon:yungsapi` keys and `horizon:disables`, which nothing writes
now. Two test initializers of the removed field (enhanced_terrain.rs,
piece_limited.rs) were removed by line from the compiler's error positions.

The layout harness now carries the mods through `horizon-port-pack carry`:
82 of 84 Better Dungeons starts match the oracle piece for piece, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-port-pack/src/carry.rs         |    1 -
 .../src/legacy_structure_mods/mod.rs          |    1 -
 .../src/legacy_structure_mods/yung.rs         | 1055 ----------------
 crates/horizon-port-pack/src/lib.rs           |    1 +
 crates/horizon-port-pack/src/processors.rs    |   19 +-
 crates/horizon-port-pack/src/worldgen.rs      |    7 +-
 crates/horizon-port-pack/src/yung.rs          |  107 ++
 .../horizon-world/src/worldgen/structure.rs   |    1 -
 .../worldgen/structure/enhanced_terrain.rs    |    1 -
 .../src/worldgen/structure/jigsaw.rs          |   21 +-
 .../src/worldgen/structure/piece_limited.rs   |    1 -
 .../src/worldgen/structure/start.rs           |   71 +-
 .../src/worldgen/structure/yung.rs            | 1122 -----------------
 docs/mods.md                                  |    6 +-
 tools/test_structure_layout_parity.py         |  109 +-
 15 files changed, 190 insertions(+), 2333 deletions(-)
 delete mode 100644 crates/horizon-port-pack/src/legacy_structure_mods/yung.rs
 create mode 100644 crates/horizon-port-pack/src/yung.rs
 delete mode 100644 crates/horizon-world/src/worldgen/structure/yung.rs

diff --git a/crates/horizon-port-pack/src/carry.rs b/crates/horizon-port-pack/src/carry.rs
index 42c0483b4..82dbf11af 100644
--- a/crates/horizon-port-pack/src/carry.rs
+++ b/crates/horizon-port-pack/src/carry.rs
@@ -814,7 +814,6 @@ pub fn carry(
                     if kind == "structure" {
                         let path = rel.trim_start_matches("worldgen/structure/");
                         let structure = format!("{ns}:{}", path.trim_end_matches(".json"));
-                        changed |= crate::legacy_structure_mods::yung::disables(&structure, &mut v);
                         changed |=
                             crate::worldgen::add_piece_counts(&structure, &mut v, &piece_counts);
                     }
diff --git a/crates/horizon-port-pack/src/legacy_structure_mods/mod.rs b/crates/horizon-port-pack/src/legacy_structure_mods/mod.rs
index 49db376bc..1faa1b39f 100644
--- a/crates/horizon-port-pack/src/legacy_structure_mods/mod.rs
+++ b/crates/horizon-port-pack/src/legacy_structure_mods/mod.rs
@@ -15,7 +15,6 @@
 //! conversion.
 pub(crate) mod ctov;
 pub(crate) mod lithostitched;
-pub(crate) mod yung;
 
 #[cfg(test)]
 fn data() -> crate::processors::ProcessorData {
diff --git a/crates/horizon-port-pack/src/legacy_structure_mods/yung.rs b/crates/horizon-port-pack/src/legacy_structure_mods/yung.rs
deleted file mode 100644
index 26dd25923..000000000
--- a/crates/horizon-port-pack/src/legacy_structure_mods/yung.rs
+++ /dev/null
@@ -1,1055 +0,0 @@
-//! YUNG's API and the mods built on it: structures, placements, pool
-//! elements and processors.
-use crate::worldgen::{ENHANCED_TERRAIN, HORIZON_ENHANCED_TERRAIN, moogs_terrain, placement_rules};
-use serde_json::{Value, json};
-use std::collections::BTreeMap;
-
-/// YUNG's placements: vanilla's random spread with an enhanced exclusion
-/// zone (several sets), plus, for the temples, no start near an ocean or a
-/// river, and for strongholds, starts only in odd rings around the origin.
-const YUNG_SPREADS: [&str; 4] = [
-    "yungsapi:enhanced_random_spread",
-    "betterdeserttemples:desert_temple",
-    "betterjungletemples:jungle_temple",
-    "betterstrongholds:stronghold",
-];
-/// YUNG's structures and the vanilla structure type each one's mod turns
-/// off (its DisableVanilla*Mixin, on by default in each mod's config).
-const YUNG_REPLACES: [(&str, &str); 7] = [
-    (
-        "betterdeserttemples:desert_temple",
-        "minecraft:desert_pyramid",
-    ),
-    (
-        "betterjungletemples:jungle_temple",
-        "minecraft:jungle_temple",
-    ),
-    ("betterwitchhuts:witch_hut", "minecraft:swamp_hut"),
-    (
-        "betteroceanmonuments:ocean_monument",
-        "minecraft:ocean_monument",
-    ),
-    ("betterstrongholds:stronghold", "minecraft:stronghold"),
-    ("betterfortresses:fortress", "minecraft:fortress"),
-    ("bettermineshafts:mineshaft_", "minecraft:mineshaft"),
-];
-
-/// A `structure` or `structure_set` file of YUNG's types as vanilla's: its
-/// jigsaw, and its placements. `None` for any other file.
-pub(crate) fn upgrade(
-    kind: &str,
-    v: &mut Value,
-    set_tags: &BTreeMap<String, Vec<String>>,
-    lost: &mut BTreeMap<String, usize>,
-) -> Option<bool> {
-    match kind {
-        "structure" => match v["type"].as_str() {
-            // Better Dungeons' small Nether dungeon is YUNG's jigsaw behind a
-            // config switch that ships on.
-            Some("yungsapi:yung_jigsaw" | "betterdungeons:small_nether_dungeon") => {
-                yung_structure(v, lost);
-                Some(true)
-            }
-            _ => None,
-        },
-        "structure_set" => match v["placement"]["type"].as_str() {
-            Some(t) if YUNG_SPREADS.contains(&t) => {
-                let t = t.to_owned();
-                yung_placement(&t, &mut v["placement"], set_tags, lost);
-                Some(true)
-            }
-            _ => None,
-        },
-        _ => None,
-    }
-}
-
-/// A pool element of YUNG's type as vanilla's; whether it was one.
-pub(crate) fn upgrade_pool_element(
-    element: &mut Value,
-    lost: &mut BTreeMap<String, usize>,
-) -> bool {
-    if element["element_type"] != "yungsapi:yung_single_element" {
-        return false;
-    }
-    yung_element(element, lost);
-    true
-}
-
-/// YUNG's API's jigsaw as vanilla's, laid out by its own assembler in the
-/// game (`horizon:yungsapi`, `horizon_world::worldgen::structure::yung`):
-/// the heights pieces stay within move under the key, its terrain
-/// adaptation under `horizon:enhanced_terrain_adaptation`. A start offset in
-/// the chunk is lost.
-fn yung_structure(v: &mut Value, lost: &mut BTreeMap<String, usize>) {
-    let Some(o) = v.as_object_mut() else {
-        return;
-    };
-    o.insert("type".into(), "minecraft:jigsaw".into());
-    let mut rules = serde_json::Map::new();
-    for key in ["min_y", "max_y"] {
-        if let Some(y) = o.remove(key) {
-            rules.insert(key.into(), y);
-        }
-    }
-    // YungJigsawStructure's adaptation (NONE by default): every piece's
-    // junctions, and the start's box grown by its radius.
-    let own = o.remove(ENHANCED_TERRAIN);
-    let mut kernel = yung_terrain(own.as_ref().unwrap_or(&Value::Null), lost);
-    kernel["rigid_junctions"] = true.into();
-    kernel["inflate"] = true.into();
-    o.insert(HORIZON_ENHANCED_TERRAIN.into(), kernel);
-    for key in ["x_offset_in_chunk", "z_offset_in_chunk"] {
-        if o.remove(key).is_some_and(|n| n != 0) {
-            *lost.entry(key.into()).or_default() += 1;
-        }
-    }
-    o.insert("horizon:yungsapi".into(), rules.into());
-}
-
-/// YUNG's single pool element as vanilla's, its rules under
-/// `horizon:yungsapi`: name and `max_count`, depth range, priority,
-/// `ignore_bounds`, its condition, dead-end pool and modifiers; its terrain
-/// adaptation under `horizon:enhanced_terrain_adaptation`.
-fn yung_element(element: &mut Value, lost: &mut BTreeMap<String, usize>) {
-    let Some(o) = element.as_object_mut() else {
-        return;
-    };
-    o.insert(
-        "element_type".into(),
-        "minecraft:single_pool_element".into(),
-    );
-    let mut rules = serde_json::Map::new();
-    for (from, to) in [
-        ("name", "name"),
-        ("max_count", "max_count"),
-        ("min_required_depth", "min_depth"),
-        ("max_possible_depth", "max_depth"),
-        ("is_priority", "priority"),
-        ("ignore_bounds", "ignore_bounds"),
-    ] {
-        if let Some(x) = o.remove(from) {
-            rules.insert(to.into(), x);
-        }
-    }
-    if let Some(c) = o.remove("condition") {
-        rules.insert("condition".into(), yung_condition(&c, lost));
-    }
-    // A piece's own adaptation, NONE included, replaces its structure's.
-    if let Some(a) = o.remove(ENHANCED_TERRAIN) {
-        o.insert(HORIZON_ENHANCED_TERRAIN.into(), yung_terrain(&a, lost));
-    }
-    if let Some(pool) = o.remove("deadend_pool").filter(Value::is_string) {
-        rules.insert("deadend_pool".into(), pool);
-    }
-    let modifiers: Vec<Value> = o
-        .remove("modifiers")
-        .and_then(|m| m.as_array().cloned())
-        .unwrap_or_default()
-        .iter()
-        .filter_map(|m| yung_modifier(m, lost))
-        .collect();
-    if !modifiers.is_empty() {
-        rules.insert("modifiers".into(), modifiers.into());
-    }
-    o.insert("horizon:yungsapi".into(), rules.into());
-}
-
-/// One of YUNG's structure modifiers in the game's terms: its condition and
-/// its transform and delay_generation actions, on the piece itself (`self`,
-/// the API's only target). Another target loses the modifier, another action
-/// just that action.
-fn yung_modifier(m: &Value, lost: &mut BTreeMap<String, usize>) -> Option<Value> {
-    let target = m["target_selector"]["type"].as_str().unwrap_or_default();
-    if target != "yungsapi:self" {
-        *lost
-            .entry(format!("yungsapi modifier target {target}"))
-            .or_default() += 1;
-        return None;
-    }
-    let mut actions = Vec::new();
-    for a in m["actions"].as_array().into_iter().flatten() {
-        let int = |k: &str| a[k].as_i64().unwrap_or(0);
-        match a["type"].as_str().unwrap_or_default() {
-            "yungsapi:transform" => actions.push(serde_json::json!({"type": "transform",
-                "output": a["output"].clone(),
-                "offset": [int("x_offset"), int("y_offset"), int("z_offset")]})),
-            "yungsapi:delay_generation" => {
-                actions.push(serde_json::json!({"type": "delay_generation"}))
-            }
-            other => {
-                *lost
-                    .entry(format!("yungsapi modifier action {other}"))
-                    .or_default() += 1
-            }
-        }
-    }
-    let condition = match m.get("condition") {
-        Some(c) => yung_condition(c, lost),
-        None => serde_json::json!({"type": "true"}),
-    };
-    Some(serde_json::json!({"condition": condition, "actions": actions}))
-}
-
-/// YUNG's API's terrain adaptation as the game's kernel: its two presets
-/// spelled out, NONE (also the default) as size 0. An aquifer override
-/// (none of ATM10's) is lost.
-fn yung_terrain(a: &Value, lost: &mut BTreeMap<String, usize>) -> Value {
-    let kernel = |size: i32, distance: i32, top: &str, bottom: &str| {
-        serde_json::json!({"kernel_size": size, "kernel_distance": distance,
-            "top": top, "bottom": bottom})
-    };
-    match a["type"].as_str() {
-        Some("yungsapi:carved_top_no_beard_large") => kernel(24, 16, "carve", "none"),
-        Some("yungsapi:carved_top_no_beard_small") => kernel(12, 6, "carve", "none"),
-        Some("yungsapi:custom") => {
-            let mut out = serde_json::Map::new();
-            for key in [
-                "kernel_size",
-                "kernel_distance",
-                "top",
-                "bottom",
-                "bottom_offset",
-                "padding",
-            ] {
-                if let Some(x) = a.get(key) {
-                    out.insert(key.into(), x.clone());
-                }
-            }
-            if a.get("aquifer_override")
-                .is_some_and(|x| x["type"] != "yungsapi:none")
-            {
-                *lost.entry("yungsapi aquifer_override".into()).or_default() += 1;
-            }
-            moogs_terrain(&out.into(), lost).unwrap_or_else(|| kernel(0, 0, "none", "none"))
-        }
-        None | Some("yungsapi:none") => kernel(0, 0, "none", "none"),
-        Some(other) => {
-            *lost
-                .entry(format!("yungsapi terrain adaptation {other}"))
-                .or_default() += 1;
-            kernel(0, 0, "none", "none")
-        }
-    }
-}
-
-/// One of YUNG's structure conditions in the game's terms. `mod_loaded`
-/// holds for Minecraft alone: a mod that needs code is not ported, and the
-/// pieces it guards would place its blocks. A condition the game does not
-/// have does not hold, and is counted.
-fn yung_condition(c: &Value, lost: &mut BTreeMap<String, usize>) -> Value {
-    let t = c["type"].as_str().unwrap_or_default();
-    let list = |lost: &mut BTreeMap<String, usize>| -> Value {
-        let all = c["conditions"].as_array().into_iter().flatten();
-        all.map(|x| yung_condition(x, lost))
-            .collect::<Vec<_>>()
-            .into()
-    };
-    let opt = |k: &str| c.get(k).cloned().unwrap_or(Value::Null);
-    match t.trim_start_matches("yungsapi:") {
-        "always_true" => serde_json::json!({"type": "true"}),
-        "not" => {
-            serde_json::json!({"type": "not", "condition": yung_condition(&c["condition"], lost)})
-        }
-        "all_of" => serde_json::json!({"type": "all_of", "conditions": list(lost)}),
-        "any_of" => serde_json::json!({"type": "any_of", "conditions": list(lost)}),
-        "depth" => serde_json::json!({"type": "depth",
-            "min_depth": opt("min_required_depth"), "max_depth": opt("max_possible_depth")}),
-        "altitude" => serde_json::json!({"type": "altitude",
-            "bottom": opt("bottom_cutoff_y"), "top": opt("top_cutoff_y")}),
-        "random_chance" => serde_json::json!({"type": "random_chance", "chance": opt("chance")}),
-        "rotation" => serde_json::json!({"type": "rotation", "rotations": opt("rotations")}),
-        "piece_in_horizontal_direction" => {
-            // "yungsapi:all" (or no list) matches any piece.
-            let pieces: Vec<Value> = c["pieces"].as_array().cloned().unwrap_or_default();
-            let any = pieces.is_empty() || pieces.iter().any(|p| p == "yungsapi:all");
-            serde_json::json!({"type": "piece_in_horizontal_direction",
-                "pieces": if any { Vec::new() } else { pieces },
-                "range": opt("range"), "rotation": opt("rotation")})
-        }
-        // The game reads "yungsapi:all" (or no list) as any piece.
-        "piece_in_range" => serde_json::json!({"type": "piece_in_range",
-            "pieces": c.get("pieces").cloned().unwrap_or_else(|| Vec::<Value>::new().into()),
-            "horizontal_range": opt("horizontal_range"), "above_range": opt("above_range"),
-            "below_range": opt("below_range")}),
-        "mod_loaded" if c["modid"] == "minecraft" => serde_json::json!({"type": "true"}),
-        "mod_loaded" => serde_json::json!({"type": "false"}),
-        _ => {
-            *lost.entry(format!("yungsapi condition {t}")).or_default() += 1;
-            serde_json::json!({"type": "false"})
-        }
-    }
-}
-
-/// One of YUNG's placements as vanilla's random spread with `horizon:` keys:
-/// the enhanced exclusion zone as `horizon:exclusion_zone`; the temples'
-/// ocean and river search (findBiomeHorizontal around the chunk's middle
-/// block at y 120, 48 blocks, every 2 quarts) as `horizon:avoid_biomes`; the
-/// strongholds' rings as `horizon:ring_sections`.
-fn yung_placement(
-    t: &str,
-    p: &mut Value,
-    set_tags: &BTreeMap<String, Vec<String>>,
-    lost: &mut BTreeMap<String, usize>,
-) {
-    placement_rules(p, set_tags, lost);
-    p["type"] = "minecraft:random_spread".into();
-    let Some(o) = p.as_object_mut() else {
-        return;
-    };
-    match t {
-        "betterdeserttemples:desert_temple" | "betterjungletemples:jungle_temple" => {
-            o.insert(
-                "horizon:avoid_biomes".into(),
-                serde_json::json!({"biomes": ["#minecraft:is_river", "#minecraft:is_ocean"],
-                    "radius": 48, "step": 2, "y": 120}),
-            );
-        }
-        "betterstrongholds:stronghold" => {
-            let mut rings = serde_json::Map::new();
-            for (from, to) in [
-                ("chunk_distance_to_first_ring", "distance_to_first_ring"),
-                ("ring_chunk_thickness", "thickness"),
-                ("max_ring_section", "max_section"),
-            ] {
-                if let Some(n) = o.remove(from) {
-                    rings.insert(to.into(), n);
-                }
-            }
-            o.insert("horizon:ring_sections".into(), rings.into());
-        }
-        _ => {}
-    }
-}
-
-/// Marks a YUNG's structure that the game can start (its type is vanilla's
-/// after the upgrade) with the vanilla type its mod turns off, under
-/// `horizon:disables`. One the game cannot start leaves the vanilla
-/// structure in place, so the world keeps one of the two.
-pub(crate) fn disables(id: &str, v: &mut Value) -> bool {
-    let Some((_, vanilla)) = YUNG_REPLACES.iter().find(|(s, _)| id.starts_with(s)) else {
-        return false;
-    };
-    if !v["type"]
-        .as_str()
-        .is_some_and(|t| t.starts_with("minecraft:"))
-    {
-        return false;
-    }
-    v["horizon:disables"] = serde_json::json!([vanilla]);
-    true
-}
-
-/// The game's type for the YUNG's processors that place blocks past their
-/// template, which keep their fields (`horizon-world`'s `pillars.rs`).
-pub(crate) fn pillar_type(kind: &str) -> Option<&'static str> {
-    Some(match kind {
-        "betterfortresses:pillar_processor" | "betterjungletemples:pillar_processor" => {
-            "horizon:yung_pillar"
-        }
-        _ => return None,
-    })
-}
-
-/// The data form of one of YUNG's processors: the processors to put in its
-/// place, or `None` when it has none (or is not YUNG's).
-pub(crate) fn processor(kind: &str, p: &Value) -> Option<Vec<Value>> {
-    let (ns, _) = kind.split_once(':')?;
-    Some(match kind {
-        // Better Fortresses' stair supports get the blocks its Java code
-        // names.
-        "betterfortresses:stair_pillar_processor" => {
-            vec![json!({"processor_type": "horizon:stair_pillar",
-            "blocks": {"minecraft:stone_brick_stairs": "minecraft:red_nether_brick_stairs",
-                "minecraft:purpur_stairs": "minecraft:red_nether_bricks"},
-            "front": "minecraft:red_nether_brick_stairs",
-            "pillar": "minecraft:red_nether_bricks"})]
-        }
-        _ if ns == "betterdeserttemples"
-            && let Some(processor) = desert_temple(kind) =>
-        {
-            vec![processor]
-        }
-        "betterdungeons:small_dungeon_chest_processor" => {
-            // Its config's defaults: one chest at least, two at most, a
-            // fifth of the others kept until then; ChestBlock covers both.
-            vec![json!({"processor_type": "horizon:count_cap",
-                "blocks": ["minecraft:chest", "minecraft:trapped_chest"],
-                "min": 1, "max": 2, "chance": 0.2f32 as f64,
-                "replacement": block("minecraft:cave_air")})]
-        }
-        "betterwitchhuts:leg_processor" => vec![yung_leg(
-            "minecraft:brown_stained_glass",
-            json!({"id": "minecraft:oak_log", "properties": {"axis": "y"}}),
-            false,
-        )],
-        "betterwitchhuts:fence_leg_processor" => vec![yung_leg(
-            "minecraft:crimson_fence",
-            block("minecraft:oak_fence"),
-            true,
-        )],
-        _ if ns == "betteroceanmonuments" => ocean_monument(kind)?,
-        _ if ns == "betterdungeons" || ns == "betterdeserttemples" => vec![yung_spawner(kind, p)?],
-        _ => return None,
-    })
-}
-
-/// YUNG's leg processors (Better Ocean Monuments, Better Witch Huts): a
-/// placeholder block becomes `state` and a column of it runs down through
-/// air and fluids: the game's `horizon:yung_pillar` with fixed states, and
-/// the placeholder's properties kept for the fence legs.
-fn yung_leg(target: &str, state: Value, keep_properties: bool) -> Value {
-    let fixed = json!({"entries": [], "defaultBlockState": state});
-    json!({"processor_type": "horizon:yung_pillar", "target_block": block(target),
-        "target_block_output": fixed, "pillar_states": fixed,
-        "keep_properties": keep_properties})
-}
-
-/// Better Ocean Monuments' processors (no fields; what they do is in their
-/// Java code): placeholder blocks as vanilla's `rule` or the game's
-/// `horizon:pick` (a new `nextFloat` for each chance, as the mod draws),
-/// and its sea-level ones as the game's `horizon:flood_air`,
-/// `horizon:waterlog` and `horizon:keep_world_block`.
-fn ocean_monument(kind: &str) -> Option<Vec<Value>> {
-    let rule = |rules: &[(&str, Value)]| {
-        let rules: Vec<Value> = rules
-            .iter()
-            .map(|(from, to)| {
-                json!({"input_predicate": {"predicate_type": "minecraft:block_match", "block": from},
-                "location_predicate": {"predicate_type": "minecraft:always_true"},
-                "output_state": to})
-            })
-            .collect();
-        json!({"processor_type": "minecraft:rule", "rules": rules})
-    };
-    let state = |id: &str, props: Value| json!({"id": id, "properties": props});
-    let pick = |from: &str, picks: Vec<(f32, Value)>, default: Value, keep: bool| {
-        let picks: Vec<Value> = picks
-            .into_iter()
-            .map(|(below, state)| json!({"below": below as f64, "state": state}))
-            .collect();
-        json!({"processor_type": "horizon:pick", "block": from, "picks": picks,
-            "default": {"state": default}, "redraw": true, "keep_properties": keep})
-    };
-    let slabs = |from: &str, slab: &str, otherwise: &str| {
-        let wet = |t: &str| state(slab, json!({"type": t, "waterlogged": "true"}));
-        pick(
-            from,
-            vec![(0.4, wet("top")), (0.8, wet("bottom"))],
-            block(otherwise),
-            false,
-        )
-    };
-    // Exposed below 0.1, else weathered below a new 0.3, else oxidized,
-    // with the placeholder's properties for the stairs and slabs.
-    let copper = |kind: &str| {
-        let id = |age: &str| block(&format!("minecraft:{age}{kind}"));
-        pick(
-            &format!("minecraft:oxidized_{kind}"),
-            vec![(0.1, id("exposed_")), (0.3, id("weathered_"))],
-            id("oxidized_"),
-            true,
-        )
-    };
-    Some(match kind.strip_prefix("betteroceanmonuments:")? {
-        "random_prismarine_slab_decoration_processor" => vec![slabs(
-            "minecraft:lime_concrete",
-            "minecraft:prismarine_slab",
-            "minecraft:air",
-        )],
-        "random_dark_prismarine_slab_decoration_processor" => vec![slabs(
-            "minecraft:blue_concrete",
-            "minecraft:dark_prismarine_slab",
-            "minecraft:water",
-        )],
-        "sand_gravel_processor" => {
-            vec![rule(&[(
-                "minecraft:yellow_stained_glass",
-                block("minecraft:gravel"),
-            )])]
-        }
-        "random_oxidization_processor" => [
-            "copper",
-            "cut_copper",
-            "cut_copper_stairs",
-            "cut_copper_slab",
-        ]
-        .into_iter()
-        .map(copper)
-        .collect(),
-        "structure_void_processor" => vec![json!({"processor_type": "horizon:keep_world_block",
-            "blocks": ["minecraft:purpur_slab", "minecraft:brown_wool"]})],
-        "air_processor" => vec![json!({"processor_type": "horizon:flood_air"})],
-        "waterlog_processor" => vec![json!({"processor_type": "horizon:waterlog"})],
-        "seagrass_processor" => vec![rule(&[
-            (
-                "minecraft:red_sandstone_slab",
-                state("minecraft:tall_seagrass", json!({"half": "lower"})),
-            ),
-            (
-                "minecraft:end_stone_brick_slab",
-                state("minecraft:tall_seagrass", json!({"half": "upper"})),
-            ),
-            ("minecraft:brick_slab", block("minecraft:seagrass")),
-        ])],
-        "random_sponge_processor" => vec![pick(
-            "minecraft:orange_stained_glass",
-            vec![(0.75, block("minecraft:wet_sponge"))],
-            block("minecraft:water"),
-            false,
-        )],
-        "leg_processor" => vec![yung_leg(
-            "minecraft:blue_stained_glass",
-            block("minecraft:prismarine_bricks"),
-            false,
-        )],
-        _ => return None,
-    })
-}
-
-/// A block state as 26.3 writes it.
-fn block(id: &str) -> Value {
-    json!({"id": id})
-}
-
-/// Better Desert Temples' placeholder blocks (glass, concrete and wool in
-/// the templates) as the mod's processors turn them: the fixed ones as
-/// vanilla's `rule`, the random ones as the game's `horizon:pick`, with the
-/// mod's bounds on one `nextFloat` (YUNG's BlockStateRandomizer adds its
-/// chances up in floats). The ones that read or change the world around
-/// (pillars, Diorite's waterlogging) stay dropped.
-fn desert_temple(kind: &str) -> Option<Value> {
-    let swap = |from: &str, to: &str| {
-        json!({"processor_type": "minecraft:rule", "rules": [{
-            "input_predicate": {"predicate_type": "minecraft:block_match", "block": from},
-            "location_predicate": {"predicate_type": "minecraft:always_true"},
-            "output_state": block(to)}]})
-    };
-    let pick = |from: &str, picks: Vec<Value>, default: Value| json!({"processor_type": "horizon:pick", "block": from, "picks": picks, "default": default});
-    // YUNG's BlockStateRandomizer: an entry wins below the sum of the
-    // chances so far, summed as floats.
-    let randomizer = |entries: &[(f32, &str)]| {
-        let mut bottom = 0f32;
-        entries
-            .iter()
-            .map(|(chance, id)| {
-                bottom += chance;
-                json!({"below": bottom as f64, "state": block(id)})
-            })
-            .collect::<Vec<_>>()
-    };
-    let at = |below: f32, id: &str| json!({"below": below as f64, "state": block(id)});
-    // Sandstone stairs, upside down, facing Plane.HORIZONTAL.getRandomDirection.
-    let stairs = || {
-        let states: Vec<Value> = ["north", "east", "south", "west"]
-            .iter()
-            .map(|facing| {
-                json!({"id": "minecraft:sandstone_stairs", "properties": {
-                    "facing": facing, "half": "top", "shape": "straight", "waterlogged": "false"}})
-            })
-            .collect();
-        json!({"states": states})
-    };
-    Some(match kind.strip_prefix("betterdeserttemples:")? {
-        "blue_concrete_processor" => swap("minecraft:blue_concrete", "minecraft:blue_terracotta"),
-        "yellow_concrete_processor" => {
-            swap("minecraft:yellow_concrete", "minecraft:yellow_terracotta")
-        }
-        "red_wool_processor" => swap("minecraft:red_wool", "minecraft:tnt"),
-        "white_stained_glass_processor" => pick(
-            "minecraft:white_stained_glass",
-            randomizer(&[(0.4, "minecraft:cobweb")]),
-            json!({"state": block("minecraft:air")}),
-        ),
-        "polished_diorite_processor" => pick(
-            "minecraft:polished_diorite",
-            randomizer(&[(0.6, "minecraft:cut_sandstone")]),
-            json!({"state": block("minecraft:sandstone")}),
-        ),
-        "orange_stained_glass_processor" => {
-            let mut sus = at(0.01, "minecraft:suspicious_sand");
-            sus["nbt"] = json!({"LootTable": "minecraft:archaeology/desert_pyramid"});
-            let mut stairs = stairs();
-            stairs["below"] = (0.45f32 as f64).into();
-            pick(
-                "minecraft:orange_stained_glass",
-                vec![
-                    sus,
-                    at(0.1, "minecraft:sand"),
-                    at(0.2, "minecraft:sandstone"),
-                    stairs,
-                ],
-                json!({"state": block("minecraft:cut_sandstone")}),
-            )
-        }
-        "red_stained_glass_processor" => pick(
-            "minecraft:red_stained_glass",
-            vec![at(0.3, "minecraft:sand"), at(0.75, "minecraft:sandstone")],
-            stairs(),
-        ),
-        "pot_processor" => {
-            // Four sherds, one float each; the pot back to its default state.
-            let values: Vec<Value> = [
-                (0.05f32, "archer"),
-                (0.1, "miner"),
-                (0.15, "prize"),
-                (0.2, "skull"),
-            ]
-            .iter()
-            .map(|(below, sherd)| {
-                json!({"below": *below as f64, "value": format!("minecraft:{sherd}_pottery_sherd")})
-            })
-            .collect();
-            pick(
-                "minecraft:decorated_pot",
-                Vec::new(),
-                json!({"state": block("minecraft:decorated_pot"), "lists": [{
-                    "key": "sherds", "count": 4, "values": values, "default": "minecraft:brick"}]}),
-            )
-        }
-        _ => return None,
-    })
-}
-
-/// An item as 26.3 saves it.
-fn item(id: &str) -> Value {
-    json!({"id": format!("minecraft:{id}"), "count": 1})
-}
-
-/// YUNG's processors that make a spawner of a fixed mob (YUNG's API's
-/// `MobSpawnerData`), as vanilla's `rule`: every `input` block becomes a
-/// spawner with that NBT.
-fn yung_spawner(kind: &str, p: &Value) -> Option<Value> {
-    const SPAWNER: &str = "minecraft:spawner";
-    // (input block, mob, fields other than the defaults, whether the mob is
-    // also the only potential, its equipment)
-    let (input, mob, fields, potential, equipment): (_, _, &[(&str, i64)], _, _) = match kind {
-        "betterdungeons:mob_spawner_processor" => {
-            (SPAWNER, p["spawner_mob"].as_str()?, &[], true, None)
-        }
-        "betterdungeons:zombie_mob_spawner_processor" => (
-            SPAWNER,
-            "minecraft:zombie",
-            &[("MaxNearbyEntities", 8)],
-            true,
-            None,
-        ),
-        "betterdungeons:skeleton_mob_spawner_processor" => (
-            SPAWNER,
-            "minecraft:skeleton",
-            &[
-                ("RequiredPlayerRange", 18),
-                ("MaxNearbyEntities", 8),
-                ("MaxSpawnDelay", 650),
-            ],
-            true,
-            None,
-        ),
-        "betterdungeons:small_nether_dungeon_mob_spawner_processor" => {
-            let mob = p["spawner_mob"].as_str()?;
-            // Wither skeletons get netherite armor that never drops and a
-            // stone sword (with the mod's default config, they and blazes
-            // keep their loot).
-            let armor = (mob == "minecraft:wither_skeleton").then(|| {
-                json!({
-                    "equipment": {
-                        "feet": item("netherite_boots"),
-                        "legs": item("netherite_leggings"),
-                        "chest": item("netherite_chestplate"),
-                        "head": item("netherite_helmet"),
-                        "mainhand": item("stone_sword"),
-                    },
-                    "drop_chances": {"feet": 0.0, "legs": 0.0, "chest": 0.0, "head": 0.0},
-                })
-            });
-            (SPAWNER, mob, &[], true, armor)
-        }
-        "betterdungeons:zombie_tombstone_spawner_processor" => (
-            "minecraft:black_stained_glass",
-            "minecraft:skeleton",
-            &[],
-            false,
-            Some(json!({"equipment": {"mainhand": item("iron_sword")}})),
-        ),
-        "betterdeserttemples:gravel_processor" => (
-            "minecraft:gravel",
-            "minecraft:husk",
-            &[("MaxNearbyEntities", 8), ("RequiredPlayerRange", 24)],
-            false,
-            None,
-        ),
-        // An empty hand list in 1.21.1: the skeletons spawn without a bow,
-        // since a spawn entry with more than its id is not finalized.
-        "betterdeserttemples:bone_block_processor" => (
-            "minecraft:bone_block",
-            "minecraft:skeleton",
-            &[("RequiredPlayerRange", 32)],
-            false,
-            Some(json!({"equipment": {}})),
-        ),
-        "betterdeserttemples:infested_cracked_stone_bricks_processor" => (
-            "minecraft:infested_cracked_stone_bricks",
-            "minecraft:silverfish",
-            &[("RequiredPlayerRange", 24)],
-            false,
-            None,
-        ),
-        // 1.21.1 ignores the items' old `Count` and `tag` (the shield's
-        // pattern, the boots' dye): plain items.
-        "betterdeserttemples:yellow_wool_processor" => (
-            "minecraft:yellow_wool",
-            "minecraft:husk",
-            &[("MaxNearbyEntities", 8), ("RequiredPlayerRange", 24)],
-            false,
-            Some(json!({"equipment": {
-                "mainhand": item("golden_sword"),
-                "offhand": item("shield"),
-                "feet": item("leather_boots"),
-                "legs": item("leather_leggings"),
-                "chest": item("golden_chestplate"),
-                "head": item("chainmail_helmet"),
-            }})),
-        ),
-        _ => return None,
-    };
-    let mut entity = json!({"id": mob});
-    if let Some(Value::Object(extra)) = equipment {
-        entity.as_object_mut()?.extend(extra);
-    }
-    let potentials = match potential {
-        true => json!([{"data": {"entity": entity.clone()}, "weight": 1}]),
-        false => json!([]),
-    };
-    let mut nbt = json!({
-        "Delay": 20, "MinSpawnDelay": 200, "MaxSpawnDelay": 800, "SpawnCount": 4,
-        "MaxNearbyEntities": 6, "RequiredPlayerRange": 16, "SpawnRange": 4,
-        "SpawnData": {"entity": entity},
-        "SpawnPotentials": potentials,
-    });
-    for (key, value) in fields {
-        nbt[*key] = (*value).into();
-    }
-    Some(json!({
-        "processor_type": "minecraft:rule",
-        "rules": [{
-            "input_predicate": {"predicate_type": "minecraft:block_match", "block": input},
-            "location_predicate": {"predicate_type": "minecraft:always_true"},
-            "output_state": {"Name": SPAWNER},
-            "block_entity_modifier": {"type": "minecraft:append_static", "data": nbt},
-        }],
-    }))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::legacy_structure_mods::data;
-    use crate::processors::{ProcessorData, carry};
-    use crate::worldgen::{Upgrade, upgrade};
-
-    const NO_TAGS: BTreeMap<String, Vec<String>> = BTreeMap::new();
-
-    #[test]
-    fn yungs_jigsaws_keep_their_rules() {
-        let mut report = Upgrade::default();
-        let mut s = json!({"type": "yungsapi:yung_jigsaw", "start_pool": "y:start", "size": 20,
-            "max_y": 60, "x_offset_in_chunk": 0, "max_distance_from_center": 80,
-            "enhanced_terrain_adaptation": {"type": "yungsapi:custom", "kernel_size": 24,
-                "kernel_distance": 24, "top": "carve", "bottom": "none"}});
-        assert!(upgrade("structure", &mut s, &mut report, &NO_TAGS));
-        assert_eq!(s["type"], "minecraft:jigsaw");
-        assert_eq!(s["horizon:yungsapi"], json!({"max_y": 60}));
-        assert_eq!(
-            s["horizon:enhanced_terrain_adaptation"],
-            json!({"kernel_size": 24, "kernel_distance": 24, "top": "carve", "bottom": "none",
-                "rigid_junctions": true, "inflate": true})
-        );
-        for gone in ["max_y", "x_offset_in_chunk", "enhanced_terrain_adaptation"] {
-            assert!(s.get(gone).is_none(), "{gone}");
-        }
-        // Better Dungeons' small Nether dungeon is the same jigsaw.
-        let mut nether = json!({"type": "betterdungeons:small_nether_dungeon",
-            "start_pool": "betterdungeons:small_nether_dungeon", "size": 10,
-            "start_jigsaw_name": "betterdungeons:small_nether_dungeon_anchor",
-            "max_distance_from_center": 80, "liquid_settings": "ignore_waterlogging"});
-        assert!(upgrade("structure", &mut nether, &mut report, &NO_TAGS));
-        assert_eq!(nether["type"], "minecraft:jigsaw");
-        assert_eq!(nether["horizon:yungsapi"], json!({}));
-        assert_eq!(
-            nether["horizon:enhanced_terrain_adaptation"],
-            json!({"kernel_size": 0, "kernel_distance": 0, "top": "none", "bottom": "none",
-                "rigid_junctions": true, "inflate": true})
-        );
-        assert_eq!(
-            nether["start_jigsaw_name"],
-            "betterdungeons:small_nether_dungeon_anchor"
-        );
-        assert!(report.unsupported.is_empty());
-        let mut pool = json!({"elements": [{"weight": 3, "element": {
-            "element_type": "yungsapi:yung_single_element", "location": "y:room",
-            "processors": "minecraft:empty", "projection": "rigid",
-            "name": "room", "max_count": 2, "min_required_depth": 1, "is_priority": true,
-            "ignore_bounds": false, "deadend_pool": "y:end",
-            "modifiers": [
-                {"condition": {"type": "yungsapi:piece_in_range", "pieces": ["y:pillar"],
-                    "above_range": 40},
-                 "target_selector": {"type": "yungsapi:self"},
-                 "actions": [{"type": "yungsapi:transform", "output": ["y:covered"], "x_offset": -1},
-                    {"type": "yungsapi:delay_generation"}, {"type": "yungsapi:spin"}]},
-                {"condition": {"type": "yungsapi:always_true"},
-                 "target_selector": {"type": "yungsapi:all"}, "actions": []}],
-            "enhanced_terrain_adaptation": {"type": "yungsapi:carved_top_no_beard_small"},
-            "condition": {"type": "yungsapi:all_of", "conditions": [
-                {"type": "yungsapi:piece_in_horizontal_direction", "pieces": ["yungsapi:all"],
-                    "range": 5, "rotation": "none"},
-                {"type": "yungsapi:not", "condition": {"type": "yungsapi:mod_loaded", "modid": "create"}},
-                {"type": "yungsapi:biome", "biomes": []}]}}}]});
-        assert!(upgrade("template_pool", &mut pool, &mut report, &NO_TAGS));
-        let e = &pool["elements"][0]["element"];
-        assert_eq!(e["element_type"], "minecraft:single_pool_element");
-        assert_eq!(e["location"], "y:room");
-        assert_eq!(
-            e["horizon:yungsapi"],
-            json!({"name": "room", "max_count": 2, "min_depth": 1, "priority": true,
-                "ignore_bounds": false, "condition": {"type": "all_of", "conditions": [
-                    {"type": "piece_in_horizontal_direction", "pieces": [], "range": 5, "rotation": "none"},
-                    {"type": "not", "condition": {"type": "false"}},
-                    {"type": "false"}]},
-                "deadend_pool": "y:end",
-                "modifiers": [{"condition": {"type": "piece_in_range", "pieces": ["y:pillar"],
-                        "horizontal_range": null, "above_range": 40, "below_range": null},
-                    "actions": [{"type": "transform", "output": ["y:covered"], "offset": [-1, 0, 0]},
-                        {"type": "delay_generation"}]}]})
-        );
-        assert!(e.get("deadend_pool").is_none() && e.get("modifiers").is_none());
-        assert_eq!(
-            e["horizon:enhanced_terrain_adaptation"],
-            json!({"kernel_size": 12, "kernel_distance": 6, "top": "carve", "bottom": "none"})
-        );
-        assert_eq!(
-            report.rules_lost,
-            BTreeMap::from([
-                ("yungsapi condition yungsapi:biome".into(), 1),
-                ("yungsapi modifier action yungsapi:spin".into(), 1),
-                ("yungsapi modifier target yungsapi:all".into(), 1),
-            ])
-        );
-        assert!(report.unsupported.is_empty());
-    }
-
-    #[test]
-    fn yungs_placements_keep_their_rules() {
-        let tags = BTreeMap::from([(
-            "bf:avoid".to_owned(),
-            vec!["minecraft:nether_complexes".to_owned()],
-        )]);
-        let mut report = Upgrade::default();
-        let mut fortress = json!({"placement": {"type": "yungsapi:enhanced_random_spread",
-            "salt": 1, "spacing": 30, "separation": 20,
-            "enhanced_exclusion_zone": {"other_set": "#bf:avoid", "chunk_count": 10}}});
-        assert!(upgrade("structure_set", &mut fortress, &mut report, &tags));
-        assert_eq!(
-            fortress["placement"],
-            json!({"type": "minecraft:random_spread", "salt": 1, "spacing": 30, "separation": 20,
-                "horizon:exclusion_zone": {"other_sets": ["minecraft:nether_complexes"], "chunk_count": 10}})
-        );
-        let mut temple = json!({"placement": {"type": "betterdeserttemples:desert_temple",
-            "salt": 2, "spacing": 30, "separation": 20,
-            "exclusion_zone": {"other_set": "minecraft:villages", "chunk_count": 6}}});
-        assert!(upgrade("structure_set", &mut temple, &mut report, &tags));
-        assert_eq!(temple["placement"]["type"], "minecraft:random_spread");
-        assert_eq!(temple["placement"]["exclusion_zone"]["chunk_count"], 6);
-        assert_eq!(
-            temple["placement"]["horizon:avoid_biomes"],
-            json!({"biomes": ["#minecraft:is_river", "#minecraft:is_ocean"],
-                "radius": 48, "step": 2, "y": 120})
-        );
-        let mut stronghold = json!({"placement": {"type": "betterstrongholds:stronghold",
-            "salt": 3, "spacing": 85, "separation": 50,
-            "chunk_distance_to_first_ring": 80, "ring_chunk_thickness": 96}});
-        assert!(upgrade(
-            "structure_set",
-            &mut stronghold,
-            &mut report,
-            &tags
-        ));
-        assert_eq!(
-            stronghold["placement"],
-            json!({"type": "minecraft:random_spread", "salt": 3, "spacing": 85, "separation": 50,
-                "horizon:ring_sections": {"distance_to_first_ring": 80, "thickness": 96}})
-        );
-        assert_eq!(report.mapped, 3);
-        assert!(report.unsupported.is_empty());
-        // The vanilla counterpart is turned off only for a structure the game starts.
-        let mut ported = json!({"type": "minecraft:jigsaw"});
-        assert!(disables("betterstrongholds:stronghold", &mut ported));
-        assert_eq!(ported["horizon:disables"], json!(["minecraft:stronghold"]));
-        let mut java = json!({"type": "bettermineshafts:mineshaft"});
-        assert!(!disables("bettermineshafts:mineshaft_oak", &mut java));
-        let mut circle = json!({"type": "minecraft:jigsaw"});
-        assert!(!disables("betterwitchhuts:witch_circle", &mut circle));
-    }
-
-    #[test]
-    fn yungs_spawners_become_rules() {
-        let mut pool = json!({"elements": [{"element": {"processors": {"processors": [
-            {"processor_type": "betterdungeons:skeleton_mob_spawner_processor"},
-            {"processor_type": "betterdeserttemples:bone_block_processor"},
-            {"processor_type": "betterdungeons:small_nether_dungeon_mob_spawner_processor",
-             "spawner_mob": "minecraft:wither_skeleton"},
-            {"processor_type": "betterdungeons:candle_processor"}]}}}]});
-        let mut carried = BTreeMap::new();
-        assert!(carry("template_pool", &mut pool, &data(), &mut carried));
-        let p = &pool["elements"][0]["element"]["processors"]["processors"];
-        let rule = |i: usize| &p[i]["rules"][0];
-        assert_eq!(rule(0)["input_predicate"]["block"], "minecraft:spawner");
-        assert_eq!(
-            rule(0)["output_state"],
-            json!({"Name": "minecraft:spawner"})
-        );
-        let nbt = &rule(0)["block_entity_modifier"]["data"];
-        assert_eq!(
-            (
-                nbt["RequiredPlayerRange"].clone(),
-                nbt["MaxNearbyEntities"].clone()
-            ),
-            (json!(18), json!(8))
-        );
-        assert_eq!(nbt["MaxSpawnDelay"], 650);
-        assert_eq!(
-            nbt["SpawnPotentials"],
-            json!([{"data": {"entity": {"id": "minecraft:skeleton"}}, "weight": 1}])
-        );
-        // Bone blocks become bowless skeleton spawners with no potentials.
-        let bone = &rule(1)["block_entity_modifier"]["data"];
-        assert_eq!(rule(1)["input_predicate"]["block"], "minecraft:bone_block");
-        assert_eq!(
-            bone["SpawnData"],
-            json!({"entity": {"id": "minecraft:skeleton", "equipment": {}}})
-        );
-        assert_eq!(bone["SpawnPotentials"], json!([]));
-        let wither = &rule(2)["block_entity_modifier"]["data"]["SpawnData"]["entity"];
-        assert_eq!(
-            wither["equipment"]["head"]["id"],
-            "minecraft:netherite_helmet"
-        );
-        assert_eq!(wither["drop_chances"]["feet"], 0.0);
-        assert_eq!(p[3]["processor_type"], "betterdungeons:candle_processor");
-        assert_eq!(carried.values().sum::<usize>(), 3);
-    }
-
-    #[test]
-    fn desert_temple_placeholders_become_rules_and_picks() {
-        let mut list = json!({"processors": [
-            {"processor_type": "betterdeserttemples:red_wool_processor"},
-            {"processor_type": "betterdeserttemples:white_stained_glass_processor"},
-            {"processor_type": "betterdeserttemples:orange_stained_glass_processor"},
-            {"processor_type": "betterdeserttemples:pot_processor"},
-            {"processor_type": "betterdeserttemples:quartz_pillar_processor"}]});
-        let mut carried = BTreeMap::new();
-        assert!(carry("processor_list", &mut list, &data(), &mut carried));
-        let p = list["processors"].as_array().unwrap();
-        assert_eq!(
-            p[0]["rules"][0]["output_state"],
-            json!({"id": "minecraft:tnt"})
-        );
-        assert_eq!(p[1]["processor_type"], "horizon:pick");
-        assert_eq!(p[1]["picks"][0]["below"], 0.4f32 as f64);
-        assert_eq!(p[1]["default"]["state"]["id"], "minecraft:air");
-        let glass = &p[2]["picks"];
-        assert_eq!(glass[0]["state"]["id"], "minecraft:suspicious_sand");
-        assert_eq!(
-            glass[0]["nbt"]["LootTable"],
-            "minecraft:archaeology/desert_pyramid"
-        );
-        assert_eq!(glass[3]["states"].as_array().unwrap().len(), 4);
-        assert_eq!(glass[3]["below"], 0.45f32 as f64);
-        assert_eq!(p[3]["default"]["lists"][0]["count"], 4);
-        // The pillar reads the world below: still Java, still dropped later.
-        assert_eq!(
-            p[4]["processor_type"],
-            "betterdeserttemples:quartz_pillar_processor"
-        );
-        assert_eq!(carried.values().sum::<usize>(), 4);
-    }
-
-    #[test]
-    fn small_dungeon_chests_are_capped() {
-        let mut list = json!({"processors": [
-            {"processor_type": "betterdungeons:small_dungeon_chest_processor"}]});
-        let mut carried = BTreeMap::new();
-        assert!(carry("processor_list", &mut list, &data(), &mut carried));
-        let cap = &list["processors"][0];
-        assert_eq!(cap["processor_type"], "horizon:count_cap");
-        assert_eq!(
-            (cap["min"].as_u64(), cap["max"].as_u64()),
-            (Some(1), Some(2))
-        );
-        assert_eq!(cap["replacement"], json!({"id": "minecraft:cave_air"}));
-    }
-
-    #[test]
-    fn ocean_monuments_become_the_games() {
-        let names = [
-            "random_prismarine_slab_decoration_processor",
-            "random_dark_prismarine_slab_decoration_processor",
-            "sand_gravel_processor",
-            "random_oxidization_processor",
-            "structure_void_processor",
-            "air_processor",
-            "waterlog_processor",
-            "seagrass_processor",
-            "random_sponge_processor",
-            "leg_processor",
-        ];
-        let processors: Vec<Value> = names
-            .iter()
-            .map(|n| json!({"processor_type": format!("betteroceanmonuments:{n}")}))
-            .chain([json!({"processor_type": "betterwitchhuts:fence_leg_processor"})])
-            .collect();
-        let mut list = json!({"processors": processors});
-        let mut carried = BTreeMap::new();
-        assert!(carry(
-            "processor_list",
-            &mut list,
-            &ProcessorData::default(),
-            &mut carried
-        ));
-        let p = list["processors"].as_array().unwrap();
-        let types: Vec<&str> = p
-            .iter()
-            .map(|p| p["processor_type"].as_str().unwrap())
-            .collect();
-        let mut want = vec!["horizon:pick", "horizon:pick", "minecraft:rule"];
-        want.extend(["horizon:pick"; 4]);
-        want.extend([
-            "horizon:keep_world_block",
-            "horizon:flood_air",
-            "horizon:waterlog",
-            "minecraft:rule",
-            "horizon:pick",
-            "horizon:yung_pillar",
-            "horizon:yung_pillar",
-        ]);
-        assert_eq!(types, want);
-        assert_eq!(carried.values().sum::<usize>(), 11);
-        // Copper stairs keep their properties, each chance on a new float.
-        let stairs = &p[5];
-        assert_eq!(stairs["block"], "minecraft:oxidized_cut_copper_stairs");
-        assert_eq!(
-            stairs["picks"][1]["state"]["id"],
-            "minecraft:weathered_cut_copper_stairs"
-        );
-        assert_eq!(
-            (stairs["redraw"].clone(), stairs["keep_properties"].clone()),
-            (json!(true), json!(true))
-        );
-        assert_eq!(p[0]["picks"][0]["state"]["properties"]["type"], "top");
-        assert_eq!(p[1]["default"]["state"]["id"], "minecraft:water");
-        assert_eq!(
-            p[12]["target_block_output"]["defaultBlockState"]["id"],
-            "minecraft:prismarine_bricks"
-        );
-        assert_eq!(p[13]["keep_properties"], true);
-    }
-}
diff --git a/crates/horizon-port-pack/src/lib.rs b/crates/horizon-port-pack/src/lib.rs
index 950413341..3b17f1c9c 100644
--- a/crates/horizon-port-pack/src/lib.rs
+++ b/crates/horizon-port-pack/src/lib.rs
@@ -20,3 +20,4 @@ pub mod pipeline;
 pub mod processors;
 pub mod report;
 pub mod worldgen;
+mod yung;
diff --git a/crates/horizon-port-pack/src/processors.rs b/crates/horizon-port-pack/src/processors.rs
index f182bee7b..af1595f92 100644
--- a/crates/horizon-port-pack/src/processors.rs
+++ b/crates/horizon-port-pack/src/processors.rs
@@ -16,7 +16,7 @@
 //! What is not here is taken out of its list later and counted
 //! (`worldgen::upgrade`). The entity NBT is written in 26.3's shape (an
 //! `equipment` map, not 1.21.1's `HandItems` and `ArmorItems`).
-use crate::legacy_structure_mods::{ctov, lithostitched, yung};
+use crate::legacy_structure_mods::{ctov, lithostitched};
 use serde_json::{Value, json};
 use std::{
     collections::{BTreeMap, BTreeSet},
@@ -177,12 +177,12 @@ fn carry_at(
     let mut out = Vec::with_capacity(expanded.len());
     for p in expanded {
         let kind = p["processor_type"].as_str().unwrap_or_default().to_owned();
-        // Lithostitched's and YUNG's processors are carried apart from this
-        // code (`legacy_structure_mods`).
+        // Lithostitched's processors are carried apart from this code
+        // (`legacy_structure_mods`).
         let replacement = lithostitched::processor(&kind, &p, data, carried).or_else(|| {
-            match pillar_type(&kind).or_else(|| yung::pillar_type(&kind)) {
+            match pillar_type(&kind) {
                 Some(to) => Some(vec![pillar(&p, to, data, carried, depth)]),
-                None => as_data(&kind, &p, data).or_else(|| yung::processor(&kind, &p)),
+                None => as_data(&kind, &p, data),
             }
         });
         match replacement {
@@ -860,8 +860,10 @@ mod tests {
                 "horizon:bottom_pillar",
                 "horizon:close_off_fluid_sources",
                 "horizon:close_off_air_sources",
-                "horizon:yung_pillar",
-                "horizon:stair_pillar"
+                // YUNG's processors stay Java (dropped later) until the
+                // specification covers them.
+                "betterfortresses:pillar_processor",
+                "betterfortresses:stair_pillar_processor"
             ]
         );
         // The named list is written in once; its own pillar loses its list.
@@ -878,8 +880,7 @@ mod tests {
             p[4]["weighted_list_of_replacement_blocks"],
             json!([{"block": "minecraft:prismarine", "weight": 1}])
         );
-        assert_eq!(p[6]["pillar"], "minecraft:red_nether_bricks");
         assert_eq!(carried["repurposed_structures:pillar_processor"], 2);
-        assert_eq!(carried["betterfortresses:stair_pillar_processor"], 1);
+        assert!(!carried.contains_key("betterfortresses:stair_pillar_processor"));
     }
 }
diff --git a/crates/horizon-port-pack/src/worldgen.rs b/crates/horizon-port-pack/src/worldgen.rs
index 1070b2aad..298179acf 100644
--- a/crates/horizon-port-pack/src/worldgen.rs
+++ b/crates/horizon-port-pack/src/worldgen.rs
@@ -14,10 +14,11 @@
 //! as it is is listed, so the coverage report can say what generates and how
 //! closely.
 //!
-//! YUNG's, Lithostitched's and CTOV's worldgen files are converted by
+//! YUNG's API's files are carried as written ([`crate::yung`]).
+//! Lithostitched's and CTOV's worldgen files are converted by
 //! `legacy_structure_mods`, called from [`upgrade`], [`crate::carry`] and the
 //! processors.
-use crate::legacy_structure_mods::{lithostitched, yung};
+use crate::{legacy_structure_mods::lithostitched, yung};
 use serde_json::Value;
 use std::{
     collections::{BTreeMap, BTreeSet},
@@ -262,7 +263,7 @@ fn upgrade_types(
     let lost = &mut report.rules_lost;
     // YUNG's and Lithostitched's types are converted apart from this code.
     if let Some(changed) =
-        yung::upgrade(kind, v, set_tags, lost).or_else(|| lithostitched::upgrade(kind, v, lost))
+        yung::upgrade(kind, v, lost).or_else(|| lithostitched::upgrade(kind, v, lost))
     {
         report.mapped += usize::from(changed);
         return changed;
diff --git a/crates/horizon-port-pack/src/yung.rs b/crates/horizon-port-pack/src/yung.rs
new file mode 100644
index 000000000..1cb970846
--- /dev/null
+++ b/crates/horizon-port-pack/src/yung.rs
@@ -0,0 +1,107 @@
+//! YUNG's API's worldgen, carried as the mods write it (clean room:
+//! `cleanroom/structures/spec-yungsapi.md`).
+//!
+//! The game reads `yungsapi:yung_jigsaw` structures and
+//! `yungsapi:yung_single_element` pool elements as they ship
+//! (`horizon_world::worldgen::structure::jigsaw::Draws::Yung`), so their files
+//! pass through unchanged. What the game does not run yet is counted by name
+//! in the carry report: the fields whose behaviour the specification leaves
+//! open. YUNG's other structure, placement and processor types are left to the
+//! general code, which lists them as unsupported or drops them.
+use serde_json::Value;
+use std::collections::BTreeMap;
+
+const JIGSAW: &str = "yungsapi:yung_jigsaw";
+const ELEMENT: &str = "yungsapi:yung_single_element";
+/// A terrain adaptation that adapts nothing.
+const NO_ADAPTATION: &str = "yungsapi:none";
+
+fn count(lost: &mut BTreeMap<String, usize>, rule: String) {
+    *lost.entry(rule).or_default() += 1;
+}
+
+/// Whether a field changes generation in a way the game does not run yet:
+/// present, and not the value that changes nothing.
+fn active(v: &Value, field: &str) -> bool {
+    match &v[field] {
+        Value::Null | Value::Bool(false) => false,
+        Value::Object(o) => o.get("type").and_then(Value::as_str) != Some(NO_ADAPTATION),
+        _ => true,
+    }
+}
+
+/// A `yung_jigsaw` structure: `Some(false)` (carried as it is), else `None`.
+pub(crate) fn upgrade(kind: &str, v: &Value, lost: &mut BTreeMap<String, usize>) -> Option<bool> {
+    if kind != "structure" || v["type"] != JIGSAW {
+        return None;
+    }
+    // spec-yungsapi §2: OPEN-Y1, OPEN-Y2 and §5.
+    for field in [
+        "adapt_noise",
+        "max_y",
+        "min_y",
+        "enhanced_terrain_adaptation",
+    ] {
+        if active(v, field) {
+            count(lost, format!("{JIGSAW} {field}"));
+        }
+    }
+    Some(false)
+}
+
+/// A `yung_single_element` pool element, carried as it is; whether it was one.
+pub(crate) fn upgrade_pool_element(element: &Value, lost: &mut BTreeMap<String, usize>) -> bool {
+    if element["element_type"] != ELEMENT {
+        return false;
+    }
+    // spec-yungsapi §3: OPEN-Y5 to OPEN-Y9 and §5.
+    for field in [
+        "is_priority",
+        "min_required_depth",
+        "ignore_bounds",
+        "condition",
+        "enhanced_terrain_adaptation",
+        "modifiers",
+    ] {
+        if active(element, field) {
+            count(lost, format!("{ELEMENT} {field}"));
+        }
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn jigsaws_and_elements_are_carried_as_written() {
+        let mut lost = BTreeMap::new();
+        let dungeon =
+            json!({"type": JIGSAW, "start_pool": "a:b", "size": 10, "adapt_noise": false});
+        assert_eq!(upgrade("structure", &dungeon, &mut lost), Some(false));
+        assert!(lost.is_empty());
+        let stronghold = json!({"type": JIGSAW, "max_y": 0,
+            "enhanced_terrain_adaptation": {"type": "yungsapi:carved"}});
+        assert_eq!(upgrade("structure", &stronghold, &mut lost), Some(false));
+        assert_eq!(lost[&format!("{JIGSAW} max_y")], 1);
+        assert_eq!(lost[&format!("{JIGSAW} enhanced_terrain_adaptation")], 1);
+        assert_eq!(
+            upgrade("structure", &json!({"type": "minecraft:jigsaw"}), &mut lost),
+            None
+        );
+        assert_eq!(upgrade("structure_set", &dungeon, &mut lost), None);
+
+        let mut lost = BTreeMap::new();
+        let pile = json!({"element_type": ELEMENT, "name": "loot_pile_0", "max_count": 1,
+            "enhanced_terrain_adaptation": {"type": NO_ADAPTATION}, "is_priority": false});
+        assert!(upgrade_pool_element(&pile, &mut lost));
+        assert!(lost.is_empty());
+        let gated = json!({"element_type": ELEMENT, "condition": {"type": "yungsapi:not"}});
+        assert!(upgrade_pool_element(&gated, &mut lost));
+        assert_eq!(lost[&format!("{ELEMENT} condition")], 1);
+        let single = json!({"element_type": "minecraft:single_pool_element"});
+        assert!(!upgrade_pool_element(&single, &mut lost));
+    }
+}
diff --git a/crates/horizon-world/src/worldgen/structure.rs b/crates/horizon-world/src/worldgen/structure.rs
index d9b037808..e0ac4d9e8 100644
--- a/crates/horizon-world/src/worldgen/structure.rs
+++ b/crates/horizon-world/src/worldgen/structure.rs
@@ -21,7 +21,6 @@ pub mod start_checks;
 pub mod stronghold;
 pub mod template;
 pub mod temple;
-pub mod yung;
 
 use crate::{
     nbt::{self, Limits},
diff --git a/crates/horizon-world/src/worldgen/structure/enhanced_terrain.rs b/crates/horizon-world/src/worldgen/structure/enhanced_terrain.rs
index ac4d01e98..24c3b9a82 100644
--- a/crates/horizon-world/src/worldgen/structure/enhanced_terrain.rs
+++ b/crates/horizon-world/src/worldgen/structure/enhanced_terrain.rs
@@ -306,7 +306,6 @@ mod tests {
             legacy: false,
             projection,
             waterlogging: None,
-            yung: None,
             enhanced_terrain: own.map(Arc::new),
             ground_level: 1,
         })
diff --git a/crates/horizon-world/src/worldgen/structure/jigsaw.rs b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
index 87a551c05..6e1da3a4c 100644
--- a/crates/horizon-world/src/worldgen/structure/jigsaw.rs
+++ b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
@@ -39,9 +39,6 @@ pub enum PoolElement {
         legacy: bool,
         projection: Projection,
         waterlogging: Option<bool>,
-        /// YUNG's API's rules on the piece (`"horizon:yungsapi"`), read only
-        /// by its assembler ([`super::yung`]).
-        yung: Option<Box<super::yung::Rules>>,
         /// The piece's own terrain kernel in a structure that has one
         /// (`"horizon:enhanced_terrain_adaptation"`).
         enhanced_terrain: Option<Arc<super::enhanced_terrain::Adaptation>>,
@@ -149,10 +146,6 @@ impl PoolElement {
                         Some("ignore_waterlogging") => Some(false),
                         _ => None,
                     },
-                    yung: value
-                        .get("horizon:yungsapi")
-                        .map(|rules| super::yung::Rules::decode(rules, resources).map(Box::new))
-                        .transpose()?,
                     enhanced_terrain: value
                         .get("horizon:enhanced_terrain_adaptation")
                         .map(|a| super::enhanced_terrain::Adaptation::decode(a).map(Arc::new))
@@ -248,13 +241,10 @@ impl PoolElement {
                 .first()
                 .map(|e| e.shuffled_jigsaws(resources, position, rotation, random))
                 .unwrap_or_default(),
-            Self::Single { template, yung, .. } => {
+            Self::Single { template, .. } => {
                 let mut jigsaws = template_jigsaws(resources, template, position, rotation);
                 shuffle(&mut jigsaws, random);
-                // YUNG's elements keep the shuffled order.
-                if yung.is_none() {
-                    jigsaws.sort_by_key(|j| std::cmp::Reverse(j.selection_priority));
-                }
+                jigsaws.sort_by_key(|j| std::cmp::Reverse(j.selection_priority));
                 jigsaws
             }
         }
@@ -265,13 +255,6 @@ impl PoolElement {
             _ => 1,
         }
     }
-    /// YUNG's API's rules, on a piece of one of its structures.
-    pub fn yung(&self) -> Option<&super::yung::Rules> {
-        match self {
-            Self::Single { yung, .. } => yung.as_deref(),
-            _ => None,
-        }
-    }
     /// The piece's own terrain kernel, in place of its structure's.
     pub fn enhanced_terrain(&self) -> Option<&super::enhanced_terrain::Adaptation> {
         match self {
diff --git a/crates/horizon-world/src/worldgen/structure/piece_limited.rs b/crates/horizon-world/src/worldgen/structure/piece_limited.rs
index 12a6e3f17..6977ebc88 100644
--- a/crates/horizon-world/src/worldgen/structure/piece_limited.rs
+++ b/crates/horizon-world/src/worldgen/structure/piece_limited.rs
@@ -1025,7 +1025,6 @@ mod tests {
             legacy: false,
             projection: Projection::Rigid,
             waterlogging: None,
-            yung: None,
             enhanced_terrain: None,
             ground_level: 1,
         });
diff --git a/crates/horizon-world/src/worldgen/structure/start.rs b/crates/horizon-world/src/worldgen/structure/start.rs
index 44f4b70f4..a98a9f88f 100644
--- a/crates/horizon-world/src/worldgen/structure/start.rs
+++ b/crates/horizon-world/src/worldgen/structure/start.rs
@@ -59,8 +59,6 @@ pub struct JigsawDef {
     waterlogging: bool,
     /// A carried mod's start rules (`"horizon:start_checks"`).
     checks: super::start_checks::StartChecks,
-    /// Laid out by YUNG's API's assembler (`"horizon:yungsapi"`).
-    yung: Option<super::yung::Config>,
     /// Vanilla's draws, or YUNG's API's for `yungsapi:yung_jigsaw`.
     draws: super::jigsaw::Draws,
     /// Laid out by Repurposed Structures' and Moog's piece-limited
@@ -111,9 +109,6 @@ pub struct StructureDef {
     /// A structure library's terrain kernel
     /// (`"horizon:enhanced_terrain_adaptation"`).
     pub enhanced_terrain: Option<super::enhanced_terrain::StructureAdaptation>,
-    /// Another loaded structure turns this one's type off
-    /// (`"horizon:disables"`): it never starts.
-    pub disabled: bool,
 }
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 enum Reduction {
@@ -311,19 +306,8 @@ impl StructureRegistry {
         biome_set: &dyn Fn(&Value) -> Result<BTreeSet<BiomeId>, DecodeError>,
     ) -> Result<Self, DecodeError> {
         let mut defs = Vec::new();
-        let (mut types, mut disables) = (Vec::new(), BTreeSet::new());
         for (name, json) in structures {
             let v: Value = serde_json::from_str(json)?;
-            types.push(v["type"].as_str().unwrap_or_default().to_owned());
-            // YUNG's mods turn their vanilla counterparts off (the
-            // DisableVanilla*Mixin on ChunkGenerator.tryGenerateStructure).
-            disables.extend(
-                v["horizon:disables"]
-                    .as_array()
-                    .into_iter()
-                    .flatten()
-                    .filter_map(|t| Some(t.as_str()?.to_owned())),
-            );
             let draws = match v["type"].as_str() {
                 Some("yungsapi:yung_jigsaw") => super::jigsaw::Draws::Yung,
                 _ => super::jigsaw::Draws::Vanilla,
@@ -347,7 +331,6 @@ impl StructureRegistry {
                     padding: pair(v.get("dimension_padding"), "bottom", "top", 0),
                     waterlogging: v["liquid_settings"].as_str() != Some("ignore_waterlogging"),
                     checks: super::start_checks::StartChecks::decode(v.get("horizon:start_checks")),
-                    yung: v.get("horizon:yungsapi").map(super::yung::Config::decode),
                     piece_limited: v
                         .get("horizon:piece_limited")
                         .map(super::piece_limited::Config::decode),
@@ -408,12 +391,8 @@ impl StructureRegistry {
                     .get("horizon:enhanced_terrain_adaptation")
                     .map(super::enhanced_terrain::StructureAdaptation::decode)
                     .transpose()?,
-                disabled: false,
             });
         }
-        for (def, kind) in defs.iter_mut().zip(&types) {
-            def.disabled = disables.contains(kind);
-        }
         let index = |name: &str| defs.iter().position(|d| d.name == name);
         let mut out = Vec::new();
         for (name, json) in sets {
@@ -879,9 +858,6 @@ fn try_generate(
     chunk: ChunkPos,
 ) -> Option<StructureStart> {
     let def = &registry.structures[structure];
-    if def.disabled {
-        return None;
-    }
     context.set_valid_biomes(&def.biomes);
     let seed = context.seed();
     let mut random = WorldgenRandom::new(LegacyRandom::new(0));
@@ -911,8 +887,8 @@ fn try_generate(
                 padding: jigsaw.padding,
                 waterlogging: jigsaw.waterlogging,
             };
-            let (position, mut pieces) = match (&jigsaw.yung, &jigsaw.piece_limited) {
-                (_, Some(limits)) => super::piece_limited::assemble(
+            let (position, mut pieces) = match &jigsaw.piece_limited {
+                Some(limits) => super::piece_limited::assemble(
                     &config,
                     limits,
                     context,
@@ -922,17 +898,7 @@ fn try_generate(
                     chunk,
                     start,
                 )?,
-                (Some(yung), None) => super::yung::assemble(
-                    &config,
-                    yung,
-                    context,
-                    &registry.pools,
-                    resources,
-                    bindings,
-                    &mut random,
-                    start,
-                )?,
-                (None, None) => assemble_drawing(
+                None => assemble_drawing(
                     jigsaw.draws,
                     &config,
                     context,
@@ -1437,37 +1403,6 @@ mod tests {
         .unwrap()
     }
 
-    #[test]
-    fn a_structure_turns_its_vanilla_counterpart_off() {
-        let r = registry(
-            &[
-                (
-                    "minecraft:pyramid",
-                    json!({"type": "minecraft:desert_pyramid"}),
-                ),
-                ("minecraft:igloo", json!({"type": "minecraft:igloo"})),
-                (
-                    "yung:temple",
-                    json!({"type": "minecraft:swamp_hut", "horizon:disables": ["minecraft:desert_pyramid"]}),
-                ),
-            ],
-            &[],
-        );
-        let disabled: Vec<_> = r
-            .structures
-            .iter()
-            .map(|d| (d.name.as_str(), d.disabled))
-            .collect();
-        assert_eq!(
-            disabled,
-            [
-                ("minecraft:igloo", false),
-                ("minecraft:pyramid", true),
-                ("yung:temple", false)
-            ]
-        );
-    }
-
     #[test]
     fn exclusion_zones_may_skip_the_other_sets_own() {
         let set = |avoid: Value| {
diff --git a/crates/horizon-world/src/worldgen/structure/yung.rs b/crates/horizon-world/src/worldgen/structure/yung.rs
deleted file mode 100644
index efd66fdc3..000000000
--- a/crates/horizon-world/src/worldgen/structure/yung.rs
+++ /dev/null
@@ -1,1122 +0,0 @@
-//! YUNG's API's jigsaw assembler, for the structures of the "YUNG's Better"
-//! mods carried over from a modpack (docs/modpacks.md). Carry maps
-//! `yungsapi:yung_jigsaw` to `minecraft:jigsaw` with a `"horizon:yungsapi"`
-//! key, and its pool elements to vanilla's single element with the piece's
-//! rules under the same key; vanilla data never has it.
-//!
-//! The assembler differs from vanilla's JigsawPlacement: it picks the start
-//! piece and every child by weight from the pool's weighted entries (a
-//! priority piece first), lays pieces out breadth first, caps pieces by name
-//! (`max_count`), limits them by depth, lets some ignore the bounds, checks
-//! each piece's condition, and keeps every piece between `min_y` and
-//! `max_y`. Pieces fit the same free space as vanilla's. A piece that ends
-//! up with no child can be swapped for one of a dead-end pool, and once the
-//! layout is done each piece's modifiers can turn it into another template
-//! or place it last.
-use super::{
-    BoundingBox, Rotation, StructureResources, StructureTemplate,
-    jigsaw::{
-        Free, JigsawConfig, JigsawContext, Junction, PoolElement, PoolPiece, Pools, Projection,
-        can_attach, shuffle, step,
-    },
-};
-use crate::{
-    heightmap::HeightmapType,
-    worldgen::{DecodeError, block_feature::FeatureBlockBindings},
-};
-use horizon_core::random::{LegacyRandom, RandomSource, WorldgenRandom};
-use serde_json::Value;
-use std::{
-    cell::RefCell,
-    collections::{HashMap, VecDeque},
-    rc::Rc,
-    sync::Arc,
-};
-
-/// A YUNG structure's own settings (`"horizon:yungsapi"` on the structure):
-/// the heights every piece must stay within.
-#[derive(Debug, Default)]
-pub struct Config {
-    pub min_y: Option<i32>,
-    pub max_y: Option<i32>,
-}
-impl Config {
-    pub fn decode(v: &Value) -> Self {
-        let y = |k: &str| v[k].as_i64().map(|n| n as i32);
-        Self {
-            min_y: y("min_y"),
-            max_y: y("max_y"),
-        }
-    }
-}
-
-/// A piece's rules (`"horizon:yungsapi"` on a pool element).
-#[derive(Clone, Debug, Default)]
-pub struct Rules {
-    /// Pieces sharing a name share the cap `max_count`.
-    name: Option<String>,
-    max_count: Option<i32>,
-    min_depth: Option<i32>,
-    max_depth: Option<i32>,
-    /// Chosen before any other piece of its pool.
-    priority: bool,
-    /// Placed even where it overlaps other pieces or leaves the bounds.
-    ignore_bounds: bool,
-    condition: Condition,
-    /// The pool a piece that got no child is swapped for.
-    deadend_pool: Option<String>,
-    /// Applied to the piece once the layout is done.
-    modifiers: Vec<Modifier>,
-}
-impl Rules {
-    pub fn decode(v: &Value, resources: &StructureResources) -> Result<Self, DecodeError> {
-        let int = |k: &str| v[k].as_i64().map(|n| n as i32);
-        Ok(Self {
-            name: v["name"].as_str().map(str::to_owned),
-            max_count: int("max_count"),
-            min_depth: int("min_depth"),
-            max_depth: int("max_depth"),
-            priority: v["priority"].as_bool().unwrap_or(false),
-            ignore_bounds: v["ignore_bounds"].as_bool().unwrap_or(false),
-            condition: match v.get("condition") {
-                Some(c) => Condition::decode(c, resources)?,
-                None => Condition::True,
-            },
-            deadend_pool: v["deadend_pool"].as_str().map(str::to_owned),
-            modifiers: v["modifiers"]
-                .as_array()
-                .into_iter()
-                .flatten()
-                .map(|m| Modifier::decode(m, resources))
-                .collect::<Result<_, _>>()?,
-        })
-    }
-    /// YungJigsawPoolElement.isAtValidDepth.
-    fn at_valid_depth(&self, depth: i32) -> bool {
-        self.min_depth.is_none_or(|d| d <= depth) && self.max_depth.is_none_or(|d| d >= depth)
-    }
-    /// The name a capped piece counts under: `max_count` without a name is
-    /// ignored, as YUNG's does.
-    fn capped(&self) -> Option<(&str, i32)> {
-        Some((self.name.as_deref()?, self.max_count?))
-    }
-}
-
-/// A StructureModifier: when its condition holds for the piece, its actions
-/// apply to the piece (the `self` target, the only one YUNG's API has).
-#[derive(Clone, Debug)]
-struct Modifier {
-    condition: Condition,
-    actions: Vec<Action>,
-}
-impl Modifier {
-    fn decode(v: &Value, resources: &StructureResources) -> Result<Self, DecodeError> {
-        Ok(Self {
-            condition: match v.get("condition") {
-                Some(c) => Condition::decode(c, resources)?,
-                None => Condition::True,
-            },
-            actions: v["actions"]
-                .as_array()
-                .ok_or(DecodeError::Field("modifier actions"))?
-                .iter()
-                .map(|a| Action::decode(a, resources))
-                .collect::<Result<_, _>>()?,
-        })
-    }
-}
-
-#[derive(Clone, Debug)]
-enum Action {
-    /// TransformAction: the piece becomes one of these templates, moved by
-    /// `offset` turned with the piece.
-    Transform {
-        output: Vec<Arc<StructureTemplate>>,
-        offset: [i32; 3],
-    },
-    /// DelayGenerationAction: the piece is placed after every other.
-    DelayGeneration,
-}
-impl Action {
-    fn decode(v: &Value, resources: &StructureResources) -> Result<Self, DecodeError> {
-        Ok(match v["type"].as_str().unwrap_or_default() {
-            "transform" => {
-                let output = v["output"]
-                    .as_array()
-                    .into_iter()
-                    .flatten()
-                    .map(|t| {
-                        let id = t.as_str().ok_or(DecodeError::Field("transform output"))?;
-                        resources
-                            .template(id)
-                            .ok_or_else(|| DecodeError::Registry(format!("missing template {id}")))
-                    })
-                    .collect::<Result<Vec<_>, _>>()?;
-                if output.is_empty() {
-                    return Err(DecodeError::Field("transform output"));
-                }
-                let offset = v["offset"].as_array();
-                let at = |i: usize| {
-                    offset
-                        .and_then(|o| o.get(i))
-                        .and_then(Value::as_i64)
-                        .unwrap_or(0) as i32
-                };
-                Self::Transform {
-                    output,
-                    offset: [at(0), at(1), at(2)],
-                }
-            }
-            "delay_generation" => Self::DelayGeneration,
-            _ => return Err(DecodeError::Field("YUNG modifier action type")),
-        })
-    }
-}
-
-/// YUNG's structure conditions, as carry writes them.
-#[derive(Clone, Debug, Default)]
-enum Condition {
-    #[default]
-    True,
-    False,
-    Not(Box<Condition>),
-    AllOf(Vec<Condition>),
-    AnyOf(Vec<Condition>),
-    Depth {
-        min: Option<i32>,
-        max: Option<i32>,
-    },
-    Altitude {
-        bottom: Option<f64>,
-        top: Option<f64>,
-    },
-    RandomChance(f32),
-    Rotation(Vec<Rotation>),
-    /// Another piece (of these templates, or any) within `range` blocks in
-    /// the direction `rotation` turns the piece's own north.
-    PieceInDirection {
-        templates: Vec<Arc<StructureTemplate>>,
-        range: i32,
-        rotation: Rotation,
-    },
-    /// Another piece (of these templates, or any when None) within the
-    /// piece's box grown by these ranges, not overlapping the piece.
-    PieceInRange {
-        templates: Option<Vec<Arc<StructureTemplate>>>,
-        horizontal: i32,
-        above: i32,
-        below: i32,
-    },
-}
-impl Condition {
-    fn decode(v: &Value, resources: &StructureResources) -> Result<Self, DecodeError> {
-        let list = |k: &'static str| -> Result<Vec<Condition>, DecodeError> {
-            v[k].as_array()
-                .ok_or(DecodeError::Field(k))?
-                .iter()
-                .map(|c| Self::decode(c, resources))
-                .collect()
-        };
-        let int = |k: &str| v[k].as_i64().map(|n| n as i32);
-        let rotation = |r: &Value| {
-            r.as_str()
-                .and_then(Rotation::from_name)
-                .ok_or(DecodeError::Field("condition rotation"))
-        };
-        Ok(match v["type"].as_str().unwrap_or_default() {
-            "true" => Self::True,
-            "false" => Self::False,
-            "not" => Self::Not(Box::new(Self::decode(&v["condition"], resources)?)),
-            "all_of" => Self::AllOf(list("conditions")?),
-            "any_of" => Self::AnyOf(list("conditions")?),
-            "depth" => Self::Depth {
-                min: int("min_depth"),
-                max: int("max_depth"),
-            },
-            "altitude" => Self::Altitude {
-                bottom: v["bottom"].as_f64(),
-                top: v["top"].as_f64(),
-            },
-            "random_chance" => Self::RandomChance(v["chance"].as_f64().unwrap_or(0.) as f32),
-            "rotation" => Self::Rotation(
-                v["rotations"]
-                    .as_array()
-                    .into_iter()
-                    .flatten()
-                    .map(rotation)
-                    .collect::<Result<_, _>>()?,
-            ),
-            "piece_in_horizontal_direction" => Self::PieceInDirection {
-                templates: v["pieces"]
-                    .as_array()
-                    .into_iter()
-                    .flatten()
-                    .filter_map(|p| resources.template(p.as_str()?))
-                    .collect(),
-                range: int("range").unwrap_or(0),
-                rotation: rotation(&v["rotation"])?,
-            },
-            "piece_in_range" => {
-                let pieces = v["pieces"]
-                    .as_array()
-                    .map(Vec::as_slice)
-                    .unwrap_or_default();
-                let any = pieces.is_empty() || pieces.iter().any(|p| p == "yungsapi:all");
-                Self::PieceInRange {
-                    // An unknown template matches nothing, as YUNG's API's
-                    // empty stand-in does.
-                    templates: (!any).then(|| {
-                        pieces
-                            .iter()
-                            .filter_map(|p| resources.template(p.as_str()?))
-                            .collect()
-                    }),
-                    horizontal: int("horizontal_range").unwrap_or(0),
-                    above: int("above_range").unwrap_or(0),
-                    below: int("below_range").unwrap_or(0),
-                }
-            }
-            _ => return Err(DecodeError::Field("YUNG condition type")),
-        })
-    }
-    /// StructureCondition.passes. `at` is the piece being placed: its box,
-    /// rotation and depth; the start piece has no box yet.
-    fn passes(&self, at: &At<'_>, random: &mut impl RandomSource) -> bool {
-        match self {
-            Self::True => true,
-            Self::False => false,
-            Self::Not(c) => !c.passes(at, random),
-            Self::AllOf(all) => all.iter().all(|c| c.passes(at, random)),
-            Self::AnyOf(any) => any.iter().any(|c| c.passes(at, random)),
-            Self::Depth { min, max } => {
-                min.is_none_or(|d| d <= at.depth) && max.is_none_or(|d| d >= at.depth)
-            }
-            Self::Altitude { bottom, top } => {
-                let [low, high] = at.span;
-                bottom.is_none_or(|y| f64::from(low) >= y)
-                    && top.is_none_or(|y| f64::from(high) <= y)
-            }
-            Self::RandomChance(chance) => random.next_float() < *chance,
-            Self::Rotation(valid) => valid.contains(&at.rotation),
-            Self::PieceInDirection {
-                templates,
-                range,
-                rotation,
-            } => {
-                let Some(piece) = at.piece else {
-                    return false;
-                };
-                let mut search = piece;
-                match at.rotation.get_rotated(*rotation) {
-                    Rotation::None => search.min[2] -= range,
-                    Rotation::Clockwise90 => search.max[0] += range,
-                    Rotation::Clockwise180 => search.max[2] += range,
-                    Rotation::Counterclockwise90 => search.min[0] -= range,
-                }
-                at.near(piece, &search, |template| {
-                    templates.is_empty() || templates.iter().any(|t| Arc::ptr_eq(t, template))
-                })
-            }
-            Self::PieceInRange {
-                templates,
-                horizontal,
-                above,
-                below,
-            } => {
-                let Some(piece) = at.piece else {
-                    return false;
-                };
-                let search = BoundingBox::new(
-                    [
-                        piece.min[0] - horizontal,
-                        piece.min[1] - below,
-                        piece.min[2] - horizontal,
-                    ],
-                    [
-                        piece.max[0] + horizontal,
-                        piece.max[1] + above,
-                        piece.max[2] + horizontal,
-                    ],
-                );
-                at.near(piece, &search, |template| {
-                    templates
-                        .as_ref()
-                        .is_none_or(|ts| ts.iter().any(|t| Arc::ptr_eq(t, template)))
-                })
-            }
-        }
-    }
-}
-
-/// The surface height query, object-safe for the per-call cache.
-trait JigsawContextDyn {
-    fn surface(&mut self, x: i32, z: i32) -> i32;
-}
-impl<C: JigsawContext> JigsawContextDyn for C {
-    fn surface(&mut self, x: i32, z: i32) -> i32 {
-        self.base_height(x, z, HeightmapType::WorldSurfaceWg)
-    }
-}
-
-/// What a condition sees of the piece being placed (or modified).
-struct At<'a> {
-    depth: i32,
-    rotation: Rotation,
-    piece: Option<BoundingBox>,
-    /// The piece's lowest and highest Y when the condition was set up.
-    span: [i32; 2],
-    pieces: &'a [PoolPiece],
-    /// Pieces taken out by a dead end, by index; the rest are kept.
-    gone: &'a [bool],
-}
-impl At<'_> {
-    /// Whether another single piece whose template matches lies in `search`
-    /// without overlapping `piece` (nor being exactly it).
-    fn near(
-        &self,
-        piece: BoundingBox,
-        search: &BoundingBox,
-        matches: impl Fn(&Arc<StructureTemplate>) -> bool,
-    ) -> bool {
-        self.pieces.iter().enumerate().any(|(i, other)| {
-            let PoolElement::Single { template, .. } = other.element.as_ref() else {
-                return false;
-            };
-            let b = other.bounding_box;
-            !self.gone.get(i).copied().unwrap_or(false)
-                && b != piece
-                && matches(template)
-                && b.intersects(search)
-                && !b.intersects(&piece)
-        })
-    }
-}
-
-/// The index of the entry to try: the first priority piece, else one drawn
-/// by weight (`nextInt(total) + 1`, counted down).
-fn pick(
-    candidates: &[(Arc<PoolElement>, i32)],
-    total: i32,
-    random: &mut impl RandomSource,
-) -> usize {
-    if let Some(i) = candidates
-        .iter()
-        .position(|(e, _)| e.yung().is_some_and(|r| r.priority))
-    {
-        return i;
-    }
-    let mut chosen = random.next_int_bound(total).unwrap_or(0) + 1;
-    for (i, (_, weight)) in candidates.iter().enumerate() {
-        chosen -= weight;
-        if chosen <= 0 {
-            return i;
-        }
-    }
-    candidates.len() - 1
-}
-
-/// JigsawManager.assembleJigsawStructure: the start position and the
-/// pieces, or None when no start piece fits.
-#[allow(clippy::too_many_arguments)]
-pub fn assemble(
-    config: &JigsawConfig<'_>,
-    yung: &Config,
-    context: &mut impl JigsawContext,
-    pools: &Pools,
-    resources: &StructureResources,
-    bindings: &FeatureBlockBindings<'_>,
-    random: &mut impl RandomSource,
-    position: [i32; 3],
-) -> Option<([i32; 3], Vec<PoolPiece>)> {
-    let pool = pools.get(config.start_pool, resources, bindings)?;
-    let mut candidates = pool.raw.clone();
-    shuffle(&mut candidates, random);
-    let rotation = Rotation::random(random);
-    let mut total: i32 = candidates.iter().map(|c| c.1).sum();
-    let (element, adjusted, local) = loop {
-        if candidates.is_empty() || total <= 0 {
-            return None;
-        }
-        let index = pick(&candidates, total, random);
-        let (element, weight) = candidates[index].clone();
-        if matches!(element.as_ref(), PoolElement::Empty) {
-            return None;
-        }
-        let anchored = match config.start_jigsaw {
-            Some(name) => {
-                element
-                    .shuffled_jigsaws(resources, position, rotation, random)
-                    .into_iter()
-                    .find(|j| j.name.as_deref() == Some(name))?
-                    .pos
-            }
-            None => position,
-        };
-        let local: [i32; 3] = std::array::from_fn(|i| anchored[i] - position[i]);
-        let adjusted: [i32; 3] = std::array::from_fn(|i| position[i] - local[i]);
-        let at = At {
-            depth: 0,
-            rotation,
-            piece: None,
-            span: [0, 0],
-            pieces: &[],
-            gone: &[],
-        };
-        if element
-            .yung()
-            .is_some_and(|r| !r.condition.passes(&at, random))
-        {
-            total -= weight;
-            candidates.remove(index);
-            continue;
-        }
-        break (element, adjusted, local);
-    };
-    let mut start = PoolPiece {
-        bounding_box: element.bounding_box(adjusted, rotation),
-        ground_level_delta: element.ground_level_delta(),
-        element,
-        position: adjusted,
-        rotation,
-        junctions: Vec::new(),
-        waterlogging: config.waterlogging,
-    };
-    let b = start.bounding_box;
-    let (cx, cz) = ((b.max[0] + b.min[0]) / 2, (b.max[2] + b.min[2]) / 2);
-    let bottom = match config.project_to {
-        Some(kind) => position[1] + context.base_height(cx, cz, kind),
-        None => adjusted[1],
-    };
-    start.moved(bottom - (b.min[1] + start.ground_level_delta));
-    let cy = bottom + local[1];
-    let d = config.max_distance[0];
-    let free = Rc::new(RefCell::new(Free {
-        container: BoundingBox::new([cx - d, cy - d, cz - d], [cx + d, cy + d, cz + d]),
-        removed: vec![start.bounding_box],
-    }));
-    let mut assembler = Assembler {
-        config,
-        yung,
-        pools,
-        resources,
-        bindings,
-        pieces: vec![start],
-        states: vec![(free, 0)],
-        origins: vec![None],
-        gone: vec![false],
-        counts: HashMap::new(),
-    };
-    if config.max_depth > 0 {
-        let mut queue = VecDeque::from([0]);
-        while let Some(piece) = queue.pop_front() {
-            assembler.children(piece, &mut queue, context, random);
-        }
-    }
-    Some(([cx, cy, cz], assembler.modified(random)))
-}
-
-/// JigsawStructureAssembler.
-struct Assembler<'a> {
-    config: &'a JigsawConfig<'a>,
-    yung: &'a Config,
-    pools: &'a Pools,
-    resources: &'a StructureResources,
-    bindings: &'a FeatureBlockBindings<'a>,
-    pieces: Vec<PoolPiece>,
-    /// Per piece: the free space it was placed in, and its depth.
-    states: Vec<(Rc<RefCell<Free>>, i32)>,
-    /// Per piece: where it was placed and the junction it left on its
-    /// parent (none for the start piece), for a dead end to undo.
-    origins: Vec<Option<(Slot, Junction)>>,
-    /// Per piece: taken out by a dead end.
-    gone: Vec<bool>,
-    /// Pieces placed per capped name.
-    counts: HashMap<String, i32>,
-}
-
-/// Where a child goes: the parent's jigsaw and what it needs.
-#[derive(Clone)]
-struct Slot {
-    source: usize,
-    jigsaw: super::jigsaw::Jigsaw,
-    target_pos: [i32; 3],
-    free: Rc<RefCell<Free>>,
-    depth: i32,
-}
-
-impl Assembler<'_> {
-    fn pool(&self, name: &str) -> Option<Arc<super::jigsaw::Pool>> {
-        let name = self.config.aliases.get(name).map_or(name, String::as_str);
-        self.pools.get(name, self.resources, self.bindings)
-    }
-    /// JigsawStructureAssembler.Settings.isInBounds.
-    fn in_bounds(&self, y: i32, context: &impl JigsawContext) -> bool {
-        self.yung.max_y.is_none_or(|m| y <= m)
-            && self.yung.min_y.is_none_or(|m| y >= m)
-            && y >= context.min_y() + self.config.padding[0]
-            && y <= context.max_y() + 1 - self.config.padding[1]
-    }
-    /// addChildrenForPiece: one child per jigsaw where one fits, from the
-    /// target pool unless the piece is at the last depth, else its fallback.
-    fn children(
-        &mut self,
-        source: usize,
-        queue: &mut VecDeque<usize>,
-        context: &mut impl JigsawContext,
-        random: &mut impl RandomSource,
-    ) {
-        let (element, position, rotation, source_box) = {
-            let s = &self.pieces[source];
-            (s.element.clone(), s.position, s.rotation, s.bounding_box)
-        };
-        let (context_free, depth) = self.states[source].clone();
-        let mut source_free: Option<Rc<RefCell<Free>>> = None;
-        let jigsaws = element.shuffled_jigsaws(self.resources, position, rotation, random);
-        let count = jigsaws.len();
-        let mut any = false;
-        for jigsaw in jigsaws {
-            let Some(target) = self.pool(&jigsaw.pool) else {
-                continue;
-            };
-            if target.templates.is_empty() && jigsaw.pool != "minecraft:empty" {
-                continue;
-            }
-            let Some(fallback) = self.pool(&target.fallback) else {
-                continue;
-            };
-            if fallback.templates.is_empty() && target.fallback != "minecraft:empty" {
-                continue;
-            }
-            let s = step(jigsaw.front);
-            let target_pos: [i32; 3] = std::array::from_fn(|i| jigsaw.pos[i] + s[i]);
-            let free = if source_box.is_inside(target_pos) {
-                source_free
-                    .get_or_insert_with(|| {
-                        Rc::new(RefCell::new(Free {
-                            container: source_box,
-                            removed: Vec::new(),
-                        }))
-                    })
-                    .clone()
-            } else {
-                context_free.clone()
-            };
-            let slot = Slot {
-                source,
-                jigsaw,
-                target_pos,
-                free,
-                depth,
-            };
-            let placed = depth != self.config.max_depth
-                && self.choose(&slot, target.raw.clone(), queue, context, random);
-            any |= placed || self.choose(&slot, fallback.raw.clone(), queue, context, random);
-        }
-        if let Some(pool) = element.yung().and_then(|r| r.deadend_pool.as_deref())
-            && !any
-            && count > 1
-        {
-            self.dead_end(source, pool, queue, context, random);
-        }
-    }
-    /// A piece with a dead-end pool that got no child though it has other
-    /// jigsaws is taken out, its parent's junction and its room freed and its
-    /// count given back, and a piece of that pool is chosen in its place for
-    /// the same parent jigsaw. The start piece stays.
-    fn dead_end(
-        &mut self,
-        piece: usize,
-        pool: &str,
-        queue: &mut VecDeque<usize>,
-        context: &mut impl JigsawContext,
-        random: &mut impl RandomSource,
-    ) {
-        let Some(pool) = self.pool(pool) else {
-            return;
-        };
-        let Some((slot, junction)) = self.origins[piece].clone() else {
-            return;
-        };
-        let parent = &mut self.pieces[slot.source].junctions;
-        if let Some(i) = parent.iter().position(|j| *j == junction) {
-            parent.remove(i);
-        }
-        let bounds = self.pieces[piece].bounding_box;
-        {
-            let mut free = slot.free.borrow_mut();
-            if let Some(i) = free.removed.iter().position(|b| *b == bounds) {
-                free.removed.remove(i);
-            }
-        }
-        self.gone[piece] = true;
-        let element = self.pieces[piece].element.clone();
-        if let Some((name, _)) = element.yung().and_then(Rules::capped)
-            && let Some(count) = self.counts.get_mut(name)
-        {
-            *count -= 1;
-        }
-        self.choose(&slot, pool.raw.clone(), queue, context, random);
-    }
-    /// applyModifications: each piece's modifiers, in piece order, then the
-    /// delayed pieces moved last. Returns the pieces kept.
-    fn modified(mut self, random: &mut impl RandomSource) -> Vec<PoolPiece> {
-        let mut delayed = vec![false; self.pieces.len()];
-        for (i, delay) in delayed.iter_mut().enumerate() {
-            let element = self.pieces[i].element.clone();
-            let Some(rules) = element
-                .yung()
-                .filter(|r| !self.gone[i] && !r.modifiers.is_empty())
-            else {
-                continue;
-            };
-            let b = self.pieces[i].bounding_box;
-            let (depth, rotation, span) = (
-                self.states[i].1,
-                self.pieces[i].rotation,
-                [b.min[1], b.max[1]],
-            );
-            for modifier in &rules.modifiers {
-                let at = At {
-                    depth,
-                    rotation,
-                    piece: Some(self.pieces[i].bounding_box),
-                    span,
-                    pieces: &self.pieces,
-                    gone: &self.gone,
-                };
-                if !modifier.condition.passes(&at, random) {
-                    continue;
-                }
-                for action in &modifier.actions {
-                    match action {
-                        Action::Transform { output, offset } => {
-                            transform(&mut self.pieces[i], output, *offset);
-                        }
-                        Action::DelayGeneration => *delay = true,
-                    }
-                }
-            }
-        }
-        let (mut kept, mut last) = (Vec::new(), Vec::new());
-        for ((piece, gone), delay) in self.pieces.into_iter().zip(self.gone).zip(delayed) {
-            if !gone {
-                if delay { &mut last } else { &mut kept }.push(piece);
-            }
-        }
-        kept.extend(last);
-        kept
-    }
-    /// chooseCandidateFromPool: whether a piece was placed.
-    fn choose(
-        &mut self,
-        slot: &Slot,
-        mut candidates: Vec<(Arc<PoolElement>, i32)>,
-        queue: &mut VecDeque<usize>,
-        context: &mut impl JigsawContext,
-        random: &mut impl RandomSource,
-    ) -> bool {
-        let jigsaw = &slot.jigsaw;
-        let (source_rigid, source_y, source_ground) = {
-            let s = &self.pieces[slot.source];
-            (
-                s.element.projection() == Projection::Rigid,
-                s.bounding_box.min[1],
-                s.ground_level_delta,
-            )
-        };
-        let local_y = jigsaw.pos[1] - source_y;
-        // The surface at the jigsaw, read once per call.
-        let mut surface = None;
-        let (x, z) = (jigsaw.pos[0], jigsaw.pos[2]);
-        let mut base = |context: &mut dyn JigsawContextDyn| {
-            *surface.get_or_insert_with(|| context.surface(x, z))
-        };
-        shuffle(&mut candidates, random);
-        let mut total: i32 = candidates.iter().map(|c| c.1).sum();
-        while !candidates.is_empty() && total > 0 {
-            let index = pick(&candidates, total, random);
-            let (target, weight) = candidates[index].clone();
-            if matches!(target.as_ref(), PoolElement::Empty) {
-                return false;
-            }
-            let rules = target.yung();
-            let capped = rules.and_then(Rules::capped);
-            let full = capped
-                .is_some_and(|(name, max)| self.counts.get(name).copied().unwrap_or(0) >= max);
-            if full || rules.is_some_and(|r| !r.at_valid_depth(slot.depth)) {
-                total -= weight;
-                candidates.remove(index);
-                continue;
-            }
-            let mut rotations = Rotation::ALL;
-            shuffle(&mut rotations, random);
-            for rotation in rotations {
-                let target_jigsaws =
-                    target.shuffled_jigsaws(self.resources, [0; 3], rotation, random);
-                let hack_box = target.bounding_box([0; 3], rotation);
-                let expand_to = if self.config.use_expansion_hack && hack_box.span()[1] <= 16 {
-                    target_jigsaws
-                        .iter()
-                        .map(|tj| {
-                            let st = step(tj.front);
-                            if !hack_box.is_inside(std::array::from_fn(|i| tj.pos[i] + st[i])) {
-                                return 0;
-                            }
-                            let child = self.pool(&tj.pool);
-                            let child_size = child.as_ref().map_or(0, |p| p.max_size());
-                            let fallback_size = child
-                                .and_then(|p| self.pool(&p.fallback))
-                                .map_or(0, |p| p.max_size());
-                            child_size.max(fallback_size)
-                        })
-                        .max()
-                        .unwrap_or(0)
-                } else {
-                    0
-                };
-                for target_jigsaw in &target_jigsaws {
-                    if !can_attach(jigsaw, target_jigsaw) {
-                        continue;
-                    }
-                    let target_local = target_jigsaw.pos;
-                    let raw_position: [i32; 3] =
-                        std::array::from_fn(|i| slot.target_pos[i] - target_local[i]);
-                    let raw_box = target.bounding_box(raw_position, rotation);
-                    let target_rigid = target.projection() == Projection::Rigid;
-                    let delta_y = local_y - target_local[1] + step(jigsaw.front)[1];
-                    let target_y = if source_rigid && target_rigid {
-                        source_y + delta_y
-                    } else {
-                        base(context) - target_local[1]
-                    };
-                    let offset = target_y - raw_box.min[1];
-                    let mut target_box = raw_box.moved([0, offset, 0]);
-                    let target_position =
-                        [raw_position[0], raw_position[1] + offset, raw_position[2]];
-                    if expand_to > 0 {
-                        let size = (expand_to + 1).max(target_box.max[1] - target_box.min[1]);
-                        target_box.max[1] = target_box.min[1] + size;
-                    }
-                    if !self.in_bounds(target_box.max[1], context)
-                        || !self.in_bounds(target_box.min[1], context)
-                    {
-                        continue;
-                    }
-                    if !rules.is_some_and(|r| r.ignore_bounds)
-                        && !slot.free.borrow().fits(&target_box)
-                    {
-                        continue;
-                    }
-                    let target_ground = if target_rigid {
-                        source_ground - delta_y
-                    } else {
-                        target.ground_level_delta()
-                    };
-                    let junction_y = if source_rigid {
-                        source_y + local_y
-                    } else if target_rigid {
-                        target_y + target_local[1]
-                    } else {
-                        base(context) + delta_y / 2
-                    };
-                    let at = At {
-                        depth: slot.depth + 1,
-                        rotation,
-                        piece: Some(target_box),
-                        span: [target_box.min[1], target_box.max[1]],
-                        pieces: &self.pieces,
-                        gone: &self.gone,
-                    };
-                    if rules.is_some_and(|r| !r.condition.passes(&at, random)) {
-                        continue;
-                    }
-                    let on_parent = Junction {
-                        source_x: slot.target_pos[0],
-                        source_ground_y: junction_y - local_y + source_ground,
-                        source_z: slot.target_pos[2],
-                    };
-                    self.pieces[slot.source].junctions.push(on_parent);
-                    slot.free.borrow_mut().removed.push(target_box);
-                    self.pieces.push(PoolPiece {
-                        element: target.clone(),
-                        position: target_position,
-                        ground_level_delta: target_ground,
-                        rotation,
-                        bounding_box: target_box,
-                        junctions: vec![Junction {
-                            source_x: jigsaw.pos[0],
-                            source_ground_y: junction_y - target_local[1] + target_ground,
-                            source_z: jigsaw.pos[2],
-                        }],
-                        waterlogging: self.config.waterlogging,
-                    });
-                    self.states.push((slot.free.clone(), slot.depth + 1));
-                    self.origins.push(Some((slot.clone(), on_parent)));
-                    self.gone.push(false);
-                    if slot.depth < self.config.max_depth {
-                        queue.push_back(self.pieces.len() - 1);
-                    }
-                    if let Some((name, _)) = capped {
-                        *self.counts.entry(name.to_owned()).or_default() += 1;
-                    }
-                    return true;
-                }
-            }
-            total -= weight;
-            candidates.remove(index);
-        }
-        false
-    }
-}
-
-/// TransformAction: the piece takes one of `output`'s templates, picked by a
-/// random seeded with setFeatureSeed(x, y, x) of its position, and moves by
-/// `offset` turned with it. Like YUNG's API's new piece, it loses its
-/// junctions and takes its own liquid setting (else waterlogging).
-fn transform(piece: &mut PoolPiece, output: &[Arc<StructureTemplate>], offset: [i32; 3]) {
-    let [x, y, _] = piece.position;
-    let mut random = WorldgenRandom::new(LegacyRandom::new(0));
-    random.set_feature_seed(i64::from(x), y, x);
-    let chosen = random.next_int_bound(output.len() as i32).unwrap_or(0) as usize;
-    let mut element = (*piece.element).clone();
-    let PoolElement::Single {
-        template,
-        waterlogging,
-        ..
-    } = &mut element
-    else {
-        return;
-    };
-    *template = output[chosen].clone();
-    piece.waterlogging = waterlogging.unwrap_or(true);
-    let [dx, dy, dz] = offset;
-    let [dx, dz] = match piece.rotation {
-        Rotation::None => [dx, dz],
-        Rotation::Clockwise90 => [-dz, dx],
-        Rotation::Clockwise180 => [-dx, -dz],
-        Rotation::Counterclockwise90 => [dz, -dx],
-    };
-    piece.position = [x + dx, y + dy, piece.position[2] + dz];
-    piece.bounding_box = element.bounding_box(piece.position, piece.rotation);
-    piece.element = Arc::new(element);
-    piece.junctions.clear();
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use horizon_core::random::LegacyRandom;
-
-    fn single(template: &Arc<StructureTemplate>, rules: Option<Rules>) -> Arc<PoolElement> {
-        Arc::new(PoolElement::Single {
-            template: template.clone(),
-            processors: Default::default(),
-            legacy: false,
-            projection: Projection::Rigid,
-            waterlogging: None,
-            yung: rules.map(Box::new),
-            enhanced_terrain: None,
-            ground_level: 1,
-        })
-    }
-
-    #[test]
-    fn picks_priority_pieces_then_by_weight() {
-        let t = Arc::new(StructureTemplate::empty());
-        let plain = single(&t, None);
-        let first = single(
-            &t,
-            Some(Rules {
-                priority: true,
-                ..Rules::default()
-            }),
-        );
-        let mut random = LegacyRandom::new(7);
-        let list = vec![(plain.clone(), 3), (first, 1)];
-        assert_eq!(pick(&list, 4, &mut random), 1);
-        // By weight: nextInt(total) + 1, counted down; the first entry
-        // takes draws 1..=3 of 4.
-        let list = vec![(plain.clone(), 3), (plain, 1)];
-        let mut ours = LegacyRandom::new(42);
-        let mut theirs = LegacyRandom::new(42);
-        for _ in 0..32 {
-            let draw = theirs.next_int_bound(4).unwrap() + 1;
-            assert_eq!(pick(&list, 4, &mut ours), usize::from(draw > 3));
-        }
-    }
-
-    #[test]
-    fn rules_cap_by_name_and_depth() {
-        let rules = Rules {
-            name: Some("room".into()),
-            max_count: Some(2),
-            min_depth: Some(1),
-            max_depth: Some(3),
-            ..Rules::default()
-        };
-        assert_eq!(rules.capped(), Some(("room", 2)));
-        assert!(!rules.at_valid_depth(0) && rules.at_valid_depth(1) && !rules.at_valid_depth(4));
-        // max_count without a name is ignored, as YUNG's does.
-        let unnamed = Rules {
-            max_count: Some(1),
-            ..Rules::default()
-        };
-        assert_eq!(unnamed.capped(), None);
-    }
-
-    #[test]
-    fn conditions() {
-        let t = Arc::new(StructureTemplate::empty());
-        let other = Arc::new(StructureTemplate::empty());
-        let neighbour = PoolPiece {
-            element: single(&t, None),
-            position: [0; 3],
-            ground_level_delta: 1,
-            rotation: Rotation::None,
-            bounding_box: BoundingBox::new([0, 0, -6], [4, 4, -1]),
-            junctions: Vec::new(),
-            waterlogging: true,
-        };
-        let pieces = [neighbour];
-        let at = |rotation, depth| At {
-            depth,
-            rotation,
-            piece: Some(BoundingBox::new([0, 10, 0], [4, 14, 4])),
-            span: [10, 14],
-            pieces: &pieces,
-            gone: &[],
-        };
-        let mut random = LegacyRandom::new(1);
-        let depth = Condition::Depth {
-            min: Some(2),
-            max: None,
-        };
-        assert!(!depth.passes(&at(Rotation::None, 1), &mut random));
-        assert!(depth.passes(&at(Rotation::None, 2), &mut random));
-        let altitude = |bottom, top| Condition::Altitude { bottom, top };
-        assert!(altitude(Some(10.), Some(14.)).passes(&at(Rotation::None, 0), &mut random));
-        assert!(!altitude(Some(10.5), None).passes(&at(Rotation::None, 0), &mut random));
-        assert!(!altitude(None, Some(13.9)).passes(&at(Rotation::None, 0), &mut random));
-        // North (-Z) of an unrotated piece, within 5 blocks; the neighbour
-        // stays below it in Y, but only X and Z are searched, and it must
-        // not overlap the piece itself.
-        let north = |templates, rotation| Condition::PieceInDirection {
-            templates,
-            range: 5,
-            rotation,
-        };
-        assert!(!north(Vec::new(), Rotation::None).passes(&at(Rotation::None, 1), &mut random));
-        let low = At {
-            piece: Some(BoundingBox::new([0, 0, 0], [4, 4, 4])),
-            span: [0, 4],
-            ..at(Rotation::None, 1)
-        };
-        assert!(north(Vec::new(), Rotation::None).passes(&low, &mut random));
-        assert!(north(vec![t.clone()], Rotation::None).passes(&low, &mut random));
-        assert!(!north(vec![other], Rotation::None).passes(&low, &mut random));
-        // The piece turned 180°: its north is south.
-        let turned = At {
-            rotation: Rotation::Clockwise180,
-            ..low
-        };
-        assert!(!north(Vec::new(), Rotation::None).passes(&turned, &mut random));
-        assert!(north(Vec::new(), Rotation::Clockwise180).passes(&turned, &mut random));
-        let all = Condition::AllOf(vec![
-            Condition::True,
-            Condition::Not(Box::new(Condition::False)),
-            Condition::Rotation(vec![Rotation::Clockwise180]),
-        ]);
-        assert!(all.passes(&turned, &mut random));
-        assert!(!Condition::AnyOf(vec![Condition::False]).passes(&turned, &mut random));
-    }
-
-    #[test]
-    fn piece_in_range_searches_a_grown_box() {
-        let t = Arc::new(StructureTemplate::empty());
-        let other = Arc::new(StructureTemplate::empty());
-        let piece = BoundingBox::new([0, 0, 0], [4, 4, 4]);
-        let above = |gone: &'static [bool]| {
-            let pieces = vec![PoolPiece {
-                element: single(&t, None),
-                position: [0, 30, 0],
-                ground_level_delta: 1,
-                rotation: Rotation::None,
-                bounding_box: BoundingBox::new([0, 30, 0], [4, 34, 4]),
-                junctions: Vec::new(),
-                waterlogging: true,
-            }];
-            (pieces, gone)
-        };
-        let range = |templates, above| Condition::PieceInRange {
-            templates,
-            horizontal: 0,
-            above,
-            below: 0,
-        };
-        let mut random = LegacyRandom::new(1);
-        let (pieces, gone) = above(&[]);
-        let at = At {
-            depth: 1,
-            rotation: Rotation::None,
-            piece: Some(piece),
-            span: [0, 4],
-            pieces: &pieces,
-            gone,
-        };
-        // 26 blocks above the piece's top: in a 40-block search, not 20.
-        assert!(range(None, 40).passes(&at, &mut random));
-        assert!(!range(None, 20).passes(&at, &mut random));
-        assert!(range(Some(vec![t.clone()]), 40).passes(&at, &mut random));
-        assert!(!range(Some(vec![other]), 40).passes(&at, &mut random));
-        // An unknown template matches nothing; a piece taken out by a dead
-        // end is not seen.
-        assert!(!range(Some(Vec::new()), 40).passes(&at, &mut random));
-        let (pieces, gone) = above(&[true]);
-        let at = At {
-            pieces: &pieces,
-            gone,
-            ..at
-        };
-        assert!(!range(None, 40).passes(&at, &mut random));
-    }
-
-    #[test]
-    fn transform_picks_by_position_and_turns_its_offset() {
-        let (a, b) = (
-            Arc::new(StructureTemplate::empty()),
-            Arc::new(StructureTemplate::empty()),
-        );
-        let rules = Rules {
-            name: Some("pillar".into()),
-            ..Rules::default()
-        };
-        let mut piece = PoolPiece {
-            element: single(&a, Some(rules)),
-            position: [100, 40, -7],
-            ground_level_delta: 1,
-            rotation: Rotation::Clockwise90,
-            bounding_box: BoundingBox::new([100, 40, -7], [104, 44, -3]),
-            junctions: vec![Junction {
-                source_x: 0,
-                source_ground_y: 0,
-                source_z: 0,
-            }],
-            waterlogging: false,
-        };
-        transform(&mut piece, &[a.clone(), b.clone()], [-1, 2, 0]);
-        // setFeatureSeed(x, y, x): seed x + y + 10000 * x, then nextInt(2).
-        let mut java = LegacyRandom::new(100 + 40 + 10000 * 100);
-        let chosen = [&a, &b][java.next_int_bound(2).unwrap() as usize];
-        let PoolElement::Single { template, yung, .. } = piece.element.as_ref() else {
-            panic!("not a single element");
-        };
-        assert!(Arc::ptr_eq(template, chosen));
-        assert_eq!(
-            yung.as_ref().and_then(|r| r.name.as_deref()),
-            Some("pillar")
-        );
-        // (-1, 2, 0) turned 90° clockwise is (0, 2, -1).
-        assert_eq!(piece.position, [100, 42, -8]);
-        assert!(piece.junctions.is_empty() && piece.waterlogging);
-    }
-}
diff --git a/docs/mods.md b/docs/mods.md
index 6f3216d38..d17b15d65 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -350,14 +350,14 @@ A pool addition holds `"elements"` as a pool does. This is what lithostitched's
 NeoForge and Fabric, and `horizon-port-pack carry` writes them from those.
 
 A structure (and any of its pool elements, in place of the structure's) may
-hold `horizon:enhanced_terrain_adaptation`: YUNG's API's and
-MoogsStructureLib's terrain kernel, which carves or buries terrain around the
+hold `horizon:enhanced_terrain_adaptation`: MoogsStructureLib's terrain
+kernel, which carves or buries terrain around the
 pieces on top of vanilla's `terrain_adaptation`. `kernel_size` and
 `kernel_distance` shape the kernel; `top` and `bottom` (`carve`, `bury` or
 `none`) act above and below a piece's floor; `bottom_offset`, `padding`
 (`x`, `top`, `bottom`, `z`) and MoogsStructureLib's `band` (`bottom`, `top`,
 `piece_heights`) move the box it measures from. On a structure,
-`rigid_junctions` (YUNG's API) adds rigid pieces' junctions as well and
+`rigid_junctions` adds rigid pieces' junctions as well and
 `inflate` grows the start's box by the kernel radius. `kernel_size` 0 is
 none.
 
diff --git a/tools/test_structure_layout_parity.py b/tools/test_structure_layout_parity.py
index 185dde578..d16002424 100644
--- a/tools/test_structure_layout_parity.py
+++ b/tools/test_structure_layout_parity.py
@@ -17,12 +17,11 @@ The oracle's game is 1.21.1 and Horizon's 26.3. KNOWN lists the starts where 26.
 1.21.1, each checked against 26.3 vanilla (VanillaChunkGenerationOracle's `scan`, HORIZON_PIECES=1), whose
 pieces equal Horizon's there; they are reported, not failed.
 
-Mod profiles compare the mod world's `pieces` instead. Horizon then reads the mod's own data from its jar
-(`.local/structure-oracle/jars/`, or HORIZON_STRUCTURE_JARS): an overlay of the 26.3 resources adds the
-jar's structures, sets, pools, processor lists, biome tags and templates, as they are written. The mod's
-own processors are left out of the overlay's lists: they change blocks, never which pieces are placed.
-Block states are upgraded to 26.3's JSON shape, as the port does.
-The jars are the player's; nothing of them enters the repository.
+Mod profiles compare the mod world's `pieces` instead, through the path players' packs take: the mod jars
+(`.local/structure-oracle/jars/`, or HORIZON_STRUCTURE_JARS) are carried by `horizon-port-pack carry` into
+a fresh work folder, and an overlay of the 26.3 resources adds the carried structures, sets, pools,
+processor lists, biome tags and templates. The jars are the player's; nothing of them enters the
+repository.
 
 usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons] [--filter REGEX] [--verbose]
 """
@@ -34,7 +33,6 @@ import re
 import shutil
 import subprocess
 import sys
-import zipfile
 from pathlib import Path
 
 try:
@@ -44,12 +42,13 @@ except ImportError:
 
 ORACLE = Path(os.environ.get('HORIZON_STRUCTURE_ORACLE', lab.LOCAL / 'structure-oracle'))
 JARS = Path(os.environ.get('HORIZON_STRUCTURE_JARS', ORACLE / 'jars'))
-# Per profile: which saved pieces are expected, the mod jars whose data Horizon reads, and the structures
-# compared (a regex; None: every start that has the pieces).
+# Per profile: which saved pieces are expected, the mods in the pack (id: jar), those carried, and the
+# structures compared (a regex; None: every start that has the pieces).
 PROFILES = {
-    'lithostitched': {'side': 'base_pieces', 'jars': [], 'structures': None},
-    'betterdungeons': {'side': 'pieces', 'jars': ['YungsApi-1.21.1-NeoForge-5.1.9.jar', 'YungsBetterDungeons-1.21.1-NeoForge-5.1.4.jar'],
-                       'structures': r'^betterdungeons:(small|skeleton|zombie)_dungeon$'},
+    'lithostitched': {'side': 'base_pieces', 'mods': {}, 'carry': [], 'structures': None},
+    'betterdungeons': {'side': 'pieces', 'mods': {'yungsapi': 'YungsApi-1.21.1-NeoForge-5.1.9.jar',
+                                                  'betterdungeons': 'YungsBetterDungeons-1.21.1-NeoForge-5.1.4.jar'},
+                       'carry': ['betterdungeons'], 'structures': r'^betterdungeons:(small|skeleton|zombie)_dungeon$'},
 }
 BUNDLES = {'structure': 'structures', 'structure_set': 'structure_sets', 'template_pool': 'template_pools',
            'processor_list': 'processor_lists'}
@@ -61,7 +60,7 @@ KNOWN = {
     ('lithostitched', 1234, 'minecraft:village_plains', -24, 47): 'no start in 26.3 vanilla (nor in Horizon)',
     ('lithostitched', 1234, 'minecraft:ruined_portal', -16, 51): RUINED_PORTAL,
     ('lithostitched', 42, 'minecraft:ruined_portal', -19, -38): RUINED_PORTAL,
-        ('betterdungeons', 1234, 'betterdungeons:small_dungeon', 162, 10): SULFUR_CAVES,
+    ('betterdungeons', 1234, 'betterdungeons:small_dungeon', 162, 10): SULFUR_CAVES,
     ('betterdungeons', 42, 'betterdungeons:small_dungeon', -29, -28): SULFUR_CAVES,
     **{('lithostitched', seed, 'minecraft:trial_chambers', x, z): TRIAL_CHAMBERS
        for seed, x, z in [(1234, 13, 21), (2, -28, 13), (2, 11, 16), (2, 146, 44), (42, 17, 7), (42, 38, -25)]},
@@ -91,20 +90,34 @@ def expected_piece(saved):
     return piece
 
 
-def upgrade_states(value):
-    """1.21.1's block states (`{"Name", "Properties"}`) in 26.3's shape (`{"id", "properties"}`)."""
-    if isinstance(value, list):
-        return [upgrade_states(v) for v in value]
-    if not isinstance(value, dict):
-        return value
-    if 'Name' in value and set(value) <= {'Name', 'Properties'}:
-        return {'id': value['Name'], **({'properties': value['Properties']} if 'Properties' in value else {})}
-    return {k: upgrade_states(v) for k, v in value.items()}
+# horizon-port-pack's jar census (inventory.json); the carry does not read it.
+CENSUS = ['blockstates', 'item_models', 'recipes', 'loot_tables', 'tags', 'worldgen', 'structures', 'languages',
+          'textures', 'sounds', 'classes', 'mixin_configs']
 
 
-def overlay(profile, jars):
-    """The 26.3 resources plus the jars' structure data, in a folder the probe reads as its resources."""
-    root = lab.LOCAL / 'structure-layout' / profile
+def carry(profile, mods, carried):
+    """`horizon-port-pack carry` of the profile's mods; the carried mods' data folders."""
+    work = lab.LOCAL / 'structure-layout' / profile / 'work'
+    shutil.rmtree(work, ignore_errors=True)
+    work.mkdir(parents=True)
+    records = [{'key': key, 'name': key, 'version': '', 'path': jar, 'tier': 'data', 'confidence': 'known',
+                'class': 'content' if key in carried else 'library', 'source': 'file', 'license': '',
+                'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': str(JARS / jar),
+                'info': {'mod_id': key, 'name': key, 'version': '', 'license': '', 'depends': [],
+                         'census': dict.fromkeys(CENSUS, 0)}}
+               for key, jar in mods.items()]
+    (work / 'inventory.json').write_text(json.dumps(records))
+    subprocess.run(['cargo', 'run', '--release', '-q', '-p', 'horizon-port-pack', '--', 'carry', str(work),
+                    '--resources', str(lab.RESOURCES), *carried], check=True, cwd=lab.ROOT, stdout=subprocess.DEVNULL)
+    data = [work / 'mods' / key / 'carry' / 'data' for key in carried]
+    if not all(d.is_dir() for d in data):
+        raise SystemExit(f'horizon-port-pack carried nothing into {work / "mods"}')
+    return data
+
+
+def overlay(profile, data_dirs):
+    """The 26.3 resources plus the carried structure data, in a folder the probe reads as its resources."""
+    root = lab.LOCAL / 'structure-layout' / profile / 'resources'
     shutil.rmtree(root, ignore_errors=True)
     worldgen = root / 'worldgen'
     (worldgen / 'structure').mkdir(parents=True)
@@ -116,28 +129,24 @@ def overlay(profile, jars):
             (worldgen / entry.name).symlink_to(entry)
     for namespace in (source / 'structure').iterdir():
         (worldgen / 'structure' / namespace.name).symlink_to(namespace)
-    for jar in jars:
-        with zipfile.ZipFile(JARS / jar) as archive:
-            for name in archive.namelist():
-                parts = name.split('/')
-                if parts[0] != 'data' or len(parts) < 4 or name.endswith('/'):
-                    continue
-                namespace, kind = parts[1], parts[2]
-                if kind == 'structure' and name.endswith('.nbt'):
-                    target = worldgen / 'structure' / namespace / '/'.join(parts[3:])
-                    target.parent.mkdir(parents=True, exist_ok=True)
-                    target.write_bytes(archive.read(name))
-                elif name.endswith('.json') and kind == 'worldgen' and parts[3] in BUNDLES:
-                    value = upgrade_states(json.loads(archive.read(name)))
-                    if parts[3] == 'processor_list':
-                        value['processors'] = [p for p in value['processors'] if p['processor_type'].startswith('minecraft:')]
-                    merged[BUNDLES[parts[3]]][f'{namespace}:' + '/'.join(parts[4:])[:-5]] = json.dumps(value)
-                elif name.endswith('.json') and parts[2:5] == ['tags', 'worldgen', 'biome']:
-                    tag = f'{namespace}:' + '/'.join(parts[5:])[:-5]
-                    value = json.loads(archive.read(name))
-                    if tag in merged['biome_tags'] and not value.get('replace'):
-                        value['values'] = json.loads(merged['biome_tags'][tag])['values'] + value['values']
-                    merged['biome_tags'][tag] = json.dumps(value)
+    for data in data_dirs:
+        for path in sorted(p for p in data.rglob('*') if p.is_file()):
+            parts = path.relative_to(data).parts
+            if len(parts) < 3:
+                continue
+            namespace, kind = parts[0], parts[1]
+            if kind == 'structure' and path.suffix == '.nbt':
+                target = worldgen / 'structure' / namespace / Path(*parts[2:])
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.symlink_to(path)
+            elif path.suffix == '.json' and kind == 'worldgen' and parts[2] in BUNDLES:
+                merged[BUNDLES[parts[2]]][f'{namespace}:' + '/'.join(parts[3:])[:-5]] = path.read_text()
+            elif path.suffix == '.json' and parts[1:4] == ('tags', 'worldgen', 'biome'):
+                tag = f'{namespace}:' + '/'.join(parts[4:])[:-5]
+                value = json.loads(path.read_text())
+                if tag in merged['biome_tags'] and not value.get('replace'):
+                    value['values'] = json.loads(merged['biome_tags'][tag])['values'] + value['values']
+                merged['biome_tags'][tag] = json.dumps(value)
     for name, bundle in merged.items():
         (worldgen / f'{name}.json').write_text(json.dumps(bundle))
     return root
@@ -190,11 +199,13 @@ def main():
         print(f'SKIP: no oracle results in {ORACLE / args.profile} (see this file\'s docstring)')
         return 0
     profile = PROFILES[args.profile]
-    missing = [jar for jar in profile['jars'] if not (JARS / jar).exists()]
+    missing = [jar for jar in profile['mods'].values() if not (JARS / jar).exists()]
     if missing:
         print(f'SKIP: mod jars not in {JARS}: {", ".join(missing)}')
         return 0
-    resources = overlay(args.profile, profile['jars']) if profile['jars'] else lab.RESOURCES
+    resources = lab.RESOURCES
+    if profile['carry']:
+        resources = overlay(args.profile, carry(args.profile, profile['mods'], profile['carry']))
     binary = probe_binary()
     matched, known, failed = 0, 0, []
     for path in results:

From 7b35ca27998f246649869056389e57fb429f19aa Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:35:43 +0100
Subject: [PATCH 032/270] Shader packs, clean room 28: Sildurs Vibrant renders

Three things kept Sildurs Vibrant black or wrong:

- Matrix and array varyings (`varying mat3 tbnMatrix;`): wgpu's stage
  interfaces take only scalars and vectors, so the translator now carries
  each column or element as its own varying and copies them out of and
  into a private global around the pack's `main`.
- Switch options defined in an included file whose name is not a shader
  extension (`#include "shaders.settings"`) were not read, so every
  `program.<name>.enabled` that tested them was false and the composites
  were skipped (OQ-13).
- `fogStart`/`fogEnd` mixed the start of one of vanilla's two fogs with
  the end of the other, so on clear days fog began at the camera and
  Sildurs' water turned white. They now come as the pair of the fog that
  is complete nearer (OQ-36).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/gfx/pack_uniforms.rs   |  16 ++-
 crates/horizon-shaders/src/options.rs         |  45 +++++--
 crates/horizon-shaders/src/translate/mod.rs   | 116 +++++++++++++++++-
 3 files changed, 155 insertions(+), 22 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index ad53b509a..21cfc2b14 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -233,12 +233,18 @@ impl FrameUniforms {
         for (smoothed, target) in self.eye_smooth.iter_mut().zip(eye) {
             *smoothed = smooth(*smoothed, target, 10.0 / 20.0, dt);
         }
+        // Vanilla fades by the stronger of two linear fogs; a pack gets one: the pair (start
+        // and end together) of the one that is complete nearer (OQ-36). Mixing the nearer start
+        // of one with the nearer end of the other made fog begin at the camera on clear days.
         let (fog_color, fog_start, fog_end) = match &frame.fog {
-            Some(f) => (
-                [f.color[0], f.color[1], f.color[2]],
-                f.environmental_start.min(f.render_distance_start),
-                f.environmental_end.min(f.render_distance_end),
-            ),
+            Some(f) => {
+                let (start, end) = if f.environmental_end < f.render_distance_end {
+                    (f.environmental_start, f.environmental_end)
+                } else {
+                    (f.render_distance_start, f.render_distance_end)
+                };
+                ([f.color[0], f.color[1], f.color[2]], start, end)
+            }
             None => (frame.sky.fog_color, frame.distance * 0.9, frame.distance),
         };
         // The shadow camera (OQ-6, impl-plan.md): orthographic, `shadowDistance` (160) blocks
diff --git a/crates/horizon-shaders/src/options.rs b/crates/horizon-shaders/src/options.rs
index 687fd40e0..752dc12a0 100644
--- a/crates/horizon-shaders/src/options.rs
+++ b/crates/horizon-shaders/src/options.rs
@@ -1,8 +1,9 @@
 //! Switch options (spec 8.1), as far as program-enable expressions (3.3) need them: which are on
 //! by default. A switch is `#define NAME` (on) or `//#define NAME` (off) with nothing after the
 //! name but a comment, in any stage or included file of the pack. Packs keep their options in
-//! included `.glsl` files and test them elsewhere (OQ-13), so the test the spec asks for
-//! (`#ifdef NAME` / `#ifndef NAME`) may be in any file of the pack.
+//! included `.glsl` files (or files of any name a source includes) and test them elsewhere
+//! (OQ-13), so the test the spec asks for (`#ifdef NAME` / `#ifndef NAME`) may be in any file
+//! of the pack.
 
 use std::collections::BTreeSet;
 
@@ -13,14 +14,27 @@ const SOURCES: [&str; 8] = ["vsh", "fsh", "gsh", "csh", "tcs", "tes", "glsl", "i
 /// The switch options that are on by default.
 pub fn switches_on(pack: &Pack) -> BTreeSet<String> {
     let (mut on, mut off, mut tested) = (BTreeSet::new(), BTreeSet::new(), BTreeSet::new());
-    for path in pack.all_files() {
-        let ext = path.rsplit_once('.').map_or("", |(_, e)| e);
-        if !SOURCES.contains(&ext) {
-            continue;
-        }
-        let Some(text) = pack.read_text(&path) else {
-            continue;
-        };
+    let files = pack.all_files();
+    let source = |path: &str| SOURCES.contains(&path.rsplit_once('.').map_or("", |(_, e)| e));
+    let texts: Vec<(&String, String)> = files
+        .iter()
+        .filter(|p| source(p))
+        .filter_map(|p| Some((p, pack.read_text(p)?)))
+        .collect();
+    // Files of other names count when a source includes them (`#include "shaders.settings"`).
+    let included: BTreeSet<&str> = texts
+        .iter()
+        .flat_map(|(_, t)| t.lines())
+        .filter_map(|l| l.trim().strip_prefix("#include"))
+        .map(|r| r.trim().trim_matches(|c| c == '"' || c == '<' || c == '>'))
+        .map(|r| r.rsplit('/').next().unwrap_or(r))
+        .collect();
+    let extra: Vec<(&String, String)> = files
+        .iter()
+        .filter(|p| !source(p) && included.contains(p.rsplit('/').next().unwrap_or(p)))
+        .filter_map(|p| Some((p, pack.read_text(p)?)))
+        .collect();
+    for (_, text) in texts.iter().chain(&extra) {
         for line in text.lines() {
             let line = line.trim();
             let (commented, rest) = match line.strip_prefix("//") {
@@ -71,10 +85,19 @@ mod tests {
                     "#ifdef AO\n#endif\n#ifndef BLOOM\n#endif\n#ifdef SPLIT\n#endif\n#ifdef LEVEL\n#endif\n",
                 ),
                 ("shaders/world-1/deferred.fsh", "//#define SPLIT\n"),
+                (
+                    "shaders/final.fsh",
+                    "#include \"shaders.settings\"\n#ifdef GODRAYS\n#endif\n",
+                ),
+                ("shaders/shaders.settings", "    #define GODRAYS //Toggle\n"),
+                ("shaders/notes.settings", "#define NOT_INCLUDED\n#ifdef NOT_INCLUDED\n"),
                 ("shaders/shaders.properties", "#define NOT_SOURCE\n#ifdef NOT_SOURCE\n"),
             ]),
         )
         .unwrap();
-        assert_eq!(switches_on(&pack), BTreeSet::from(["AO".to_owned()]));
+        assert_eq!(
+            switches_on(&pack),
+            BTreeSet::from(["AO".to_owned(), "GODRAYS".to_owned()])
+        );
     }
 }
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 35475ddab..96872da1d 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -204,13 +204,30 @@ fn translate(
         })
         .collect();
 
-    // Varyings by name: the vertex outputs, then fragment inputs the vertex stage lacks.
+    // Varyings by name: the vertex outputs, then fragment inputs the vertex stage lacks. A
+    // matrix or array travels as one varying per column or element (`varying_parts`).
     let mut locations: BTreeMap<String, (u32, String)> = BTreeMap::new();
+    let mut split: BTreeMap<String, (String, Vec<(String, String)>)> = BTreeMap::new();
     for var in v.outs.iter().chain(&f.ins) {
-        let next = locations.len() as u32;
-        locations
-            .entry(var.name.clone())
-            .or_insert((next, var.decl.clone()));
+        if locations.contains_key(&var.name) || split.contains_key(&var.name) {
+            continue;
+        }
+        match varying_parts(&var.decl) {
+            Some((global, parts)) => {
+                let mut copies = Vec::new();
+                for (k, (decl, access)) in parts.into_iter().enumerate() {
+                    let part = format!("hz_v_{}_{k}", var.name);
+                    let next = locations.len() as u32;
+                    locations.insert(part.clone(), (next, decl));
+                    copies.push((part, access));
+                }
+                split.insert(var.name.clone(), (global, copies));
+            }
+            None => {
+                let next = locations.len() as u32;
+                locations.insert(var.name.clone(), (next, var.decl.clone()));
+            }
+        }
     }
 
     let header = |stage: &Stage| {
@@ -255,6 +272,9 @@ fn translate(
             )
             .unwrap();
         }
+        for (name, (global, _)) in &split {
+            writeln!(h, "{}", global.replace("@", name)).unwrap();
+        }
         if let (Some(inputs), ShaderStage::Vertex) = (gbuffers, stage.kind) {
             h.push_str(&inputs.declarations);
             h.push('\n');
@@ -292,9 +312,15 @@ fn translate(
     for name in &v.inits {
         writeln!(vertex_main, "    {name} = hz_init_{name}();").unwrap();
     }
+    vertex_main.push_str("    hz_main();\n");
+    for (name, (_, copies)) in &split {
+        for (part, access) in copies {
+            writeln!(vertex_main, "    {part} = {name}{access};").unwrap();
+        }
+    }
     write!(
         vertex_main,
-        "    hz_main();\n    gl_Position = vec4(gl_Position.x, {flip}gl_Position.y, (gl_Position.z + gl_Position.w) * 0.5, gl_Position.w);\n{}}}\n",
+        "    gl_Position = vec4(gl_Position.x, {flip}gl_Position.y, (gl_Position.z + gl_Position.w) * 0.5, gl_Position.w);\n{}}}\n",
         gbuffers.map_or("", |g| &g.after)
     )
     .unwrap();
@@ -309,6 +335,11 @@ fn translate(
             Target::Buffers => "    hz_FragCoord = gl_FragCoord;\n",
         });
     }
+    for (name, (_, copies)) in &split {
+        for (part, access) in copies {
+            writeln!(fragment_main, "    {name}{access} = {part};").unwrap();
+        }
+    }
     for name in &f.inits {
         writeln!(fragment_main, "    {name} = hz_init_{name}();").unwrap();
     }
@@ -363,6 +394,52 @@ fn translate(
     })
 }
 
+/// A matrix or array varying (`flat mat3 @[2];`): wgpu's stage interfaces take only scalars
+/// and vectors (WGSL), so it becomes a private global (`mat3 @[2];`) and one varying per
+/// column or element, each with the qualifiers and how to reach it (`[1][2]`). `None` for
+/// scalars and vectors, and for sizes that are not plain numbers.
+fn varying_parts(decl: &str) -> Option<(String, Vec<(String, String)>)> {
+    let (before, after) = decl.split_once('@')?;
+    let mut words: Vec<&str> = before.split_whitespace().collect();
+    let ty = words.pop()?;
+    let qualifiers: String = words.iter().map(|w| format!("{w} ")).collect();
+    let array = after.trim().trim_end_matches(';').trim();
+    let mut sizes = Vec::new();
+    let mut rest = array;
+    while let Some(r) = rest.strip_prefix('[') {
+        let (n, r) = r.split_once(']')?;
+        sizes.push(n.trim().parse::<usize>().ok()?);
+        rest = r.trim_start();
+    }
+    if !rest.is_empty() {
+        return None;
+    }
+    // matC or matCxR: C columns of R rows.
+    let column = ty.strip_prefix("mat").and_then(|d| {
+        let (c, r) = d.split_once('x').unwrap_or((d, d));
+        Some((c.parse::<usize>().ok()?, r.parse::<usize>().ok()?))
+    });
+    if sizes.is_empty() && column.is_none() {
+        return None;
+    }
+    let part_ty = column.map_or(ty.to_owned(), |(_, r)| format!("vec{r}"));
+    if let Some((c, _)) = column {
+        sizes.push(c);
+    }
+    let count: usize = sizes.iter().product();
+    let parts = (0..count)
+        .map(|mut k| {
+            let mut access = String::new();
+            for &size in sizes.iter().rev() {
+                access.insert_str(0, &format!("[{}]", k % size));
+                k /= size;
+            }
+            (format!("{qualifiers}{part_ty} @;"), access)
+        })
+        .collect();
+    Some((format!("{ty} @{array};"), parts))
+}
+
 /// `sampler2DShadow` → (`texture2D`, `samplerShadow`); `isampler3D` → (`itexture3D`, `sampler`).
 pub(super) fn split_sampler(ty: &str) -> (String, &'static str) {
     let shadow = ty.ends_with("Shadow");
@@ -643,6 +720,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn matrix_and_array_varyings_travel_in_parts() {
+        let vsh = "#version 120\nvarying mat3 tbn;\nflat varying ivec2 ids[2];\nvarying mat2x3 m[2];\n\
+                   void main() {\n    gl_Position = ftransform();\n    tbn = mat3(2.0);\n    \
+                   ids[1] = ivec2(3);\n    m[1][0] = vec3(4.0);\n}\n";
+        let fsh = "#version 120\nvarying mat3 tbn;\nflat varying ivec2 ids[2];\nvarying mat2x3 m[2];\n\
+                   void main() { gl_FragColor = vec4(tbn[2] + m[1][0], float(ids[1].x)); }\n";
+        let p = program(
+            &[("composite.vsh", vsh), ("composite.fsh", fsh)],
+            Target::Buffers,
+        )
+        .unwrap_or_else(|e| panic!("{e:?}"));
+        let inputs = p.fragment.entry_points[0].function.arguments.len();
+        // 3 columns + 2 elements + 2 x 2 columns, and the fragment position.
+        assert!(inputs >= 9, "{inputs} inputs");
+        assert_eq!(
+            varying_parts("flat ivec2 @[2];").unwrap().1,
+            [
+                ("flat ivec2 @;".to_owned(), "[0]".to_owned()),
+                ("flat ivec2 @;".to_owned(), "[1]".to_owned())
+            ]
+        );
+        assert_eq!(varying_parts("mat2x3 @[2];").unwrap().1[3].1, "[1][1]");
+        assert!(varying_parts("vec4 @;").is_none());
+        assert!(varying_parts("vec4 @[N];").is_none());
+    }
+
     #[test]
     fn locals_may_hide_a_sampler() {
         let fsh = "#version 120\nuniform sampler2D specular;\nstruct M { float specular; };\n\

From f80f4e01e762a32a06eca5b5f6b8592b8c478cac Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:39:52 +0100
Subject: [PATCH 033/270] Structure blocks harness: the blocks Horizon's
 structure mods place against the structure oracle's

The clean-room structure oracle saved, for each start of a mod world, the
blocks of its box and every position around it that differs from the no-mod
world of the same seed. tools/test_structure_blocks_parity.py generates the
same chunks in full with Horizon twice (26.3 alone, and with the mods carried
by horizon-port-pack as players' packs are) and compares: a position counts
only where Horizon's no-mod world equals the oracle's (1.21.1 and 26.3 differ
elsewhere), and a mismatch is reported by its no-mod, expected and Horizon
blocks, so a missing processor rule reads as one line.

Better Dungeons (3 seeds, 96 complete starts): every structure is listed as
known, with the reason: the placeholder processors, the biome modifier and the
mod's own structure types are not implemented yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/test_structure_blocks_parity.py | 180 ++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 tools/test_structure_blocks_parity.py

diff --git a/tools/test_structure_blocks_parity.py b/tools/test_structure_blocks_parity.py
new file mode 100644
index 000000000..006046a31
--- /dev/null
+++ b/tools/test_structure_blocks_parity.py
@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Compare the blocks Horizon's structure mods place with the blocks a real server saved.
+
+Expected side: the clean-room structure oracle (see test_structure_layout_parity.py), which kept, for every
+start of a mod world, its blocks (`blocks`, the start's box) and every position of the box grown by
+`diff_margin` where the mod world differs from the no-mod world of the same seed (`changed_vs_vanilla`).
+
+Horizon side: the chunk_dump probe generates the chunks around each start in full (terrain, structures,
+features) twice: from the 26.3 resources (the no-mod world) and from those resources with the mods carried
+by `horizon-port-pack carry` (the mod world), as test_structure_layout_parity.py builds them.
+
+The oracle's game is 1.21.1 and Horizon's 26.3, so the worlds also differ where the versions do. A position
+is compared only where the two no-mod worlds agree (the oracle's no-mod block is known inside the start's
+box and at the changed positions); elsewhere in the grown box, where the oracle saw no change, Horizon's mod
+world must equal its no-mod world. Overlapping structures need no special case: both worlds have them.
+
+A mismatch is counted by the oracle's no-mod block, the expected block and Horizon's, so a processor's
+missing rule reads as one line. KNOWN names the mismatch classes the implementation does not cover yet, with
+the reason; they are reported, not failed.
+
+usage: test_structure_blocks_parity.py [--profile betterdungeons] [--filter REGEX] [--limit N]
+"""
+import argparse
+import gzip
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter, defaultdict
+
+try:
+    from . import lab, test_structure_layout_parity as layout
+except ImportError:
+    import lab
+    import test_structure_layout_parity as layout
+
+# profile -> {structure id regex: what the implementation does not cover yet}
+KNOWN = {
+    'betterdungeons': {
+        r'^betterdungeons:(small|skeleton|zombie)_dungeon$':
+            "Better Dungeons' placeholder processors and its biome modifier that removes vanilla's "
+            'monster rooms (spec-betterdungeons §1.2, §3.2) are not implemented yet',
+        r'^betterdungeons:(spider|small_nether)_dungeon$':
+            "Better Dungeons' own structure types (spec-betterdungeons §5, §6; OPEN-B14, B15) are not "
+            'implemented yet',
+    },
+}
+
+
+def state(text):
+    """`name[k=v,...]` with sorted properties, the same for both games' spellings."""
+    name, _, rest = text.partition('[')
+    return name + ('[' + ','.join(sorted(rest.rstrip(']').split(','))) + ']' if rest else '')
+
+
+def state_names(resources):
+    facts = json.loads((resources / 'facts.json').read_text())
+    return [state(s[3].removeprefix('Block{').replace('}', '', 1)) for s in facts['states']]
+
+
+def chunk_rect(box):
+    x0, _, z0, x1, _, z1 = box
+    return f'{x0 >> 4},{z0 >> 4},{x1 >> 4},{z1 >> 4}'
+
+
+def generate(binary, resources, seed, dimension, boxes, names):
+    """Block states by position inside `boxes`, from chunk_dump's full generation of their chunks."""
+    result = subprocess.run([str(binary), 'chunk_dump', str(resources), str(seed), dimension,
+                             *(chunk_rect(b) for b in boxes)], capture_output=True, text=True, cwd=lab.ROOT)
+    if result.returncode:
+        raise SystemExit('chunk_dump failed: ' + result.stderr[-2000:])
+    rows = {}  # chunk -> the heights the boxes over it need
+    for x0, y0, z0, x1, y1, z1 in boxes:
+        for cx in range(x0 >> 4, (x1 >> 4) + 1):
+            for cz in range(z0 >> 4, (z1 >> 4) + 1):
+                low, high = rows.get((cx, cz), (y0, y1))
+                rows[(cx, cz)] = (min(low, y0), max(high, y1))
+    blocks, chunk, low, high = {}, None, 0, -1
+    for line in result.stdout.splitlines():
+        if line.startswith('chunk '):
+            _, x, z = line.split()
+            low, high = rows.get((int(x), int(z)), (0, -1))
+            chunk = (int(x) * 16, int(z) * 16)
+        elif line.startswith('y '):
+            _, y, row = line.split(' ', 2)
+            y = int(y)
+            if low <= y <= high:
+                for i, state_id in enumerate(row.split(' ')):
+                    blocks[(chunk[0] + i % 16, y, chunk[1] + i // 16)] = names[int(state_id)]
+    return blocks
+
+
+def oracle_blocks(start):
+    """(mod world, no-mod world) block by position: the box in full, the changed positions around it."""
+    x0, y0, z0, x1, y1, z1 = start['bounding_box']
+    palette = [state(p) for p in start['blocks']['palette']]
+    runs = iter(index for index, count in start['blocks']['rle'] for _ in range(count))
+    mod = {(x, y, z): palette[next(runs)] for y in range(y0, y1 + 1) for z in range(z0, z1 + 1)
+           for x in range(x0, x1 + 1)}
+    base = dict(mod)
+    for x, y, z, mod_state, base_state in start['changed_vs_vanilla']:
+        mod[(x, y, z)], base[(x, y, z)] = state(mod_state), state(base_state)
+    return mod, base
+
+
+def inside(box, p):
+    return all(box[i] <= p[i] <= box[i + 3] for i in range(3))
+
+
+def compare(start, vanilla, modded):
+    """Compared positions and the mismatches, as (no-mod, expected, Horizon) -> count."""
+    mod, base = oracle_blocks(start)
+    compared, mismatches = 0, Counter()
+    x0, y0, z0, x1, y1, z1 = start['diff_box']
+    for y in range(y0, y1 + 1):
+        for z in range(z0, z1 + 1):
+            for x in range(x0, x1 + 1):
+                p = (x, y, z)
+                if p not in vanilla or p not in modded:
+                    continue
+                if p in base:
+                    if vanilla[p] != base[p]:
+                        continue  # the versions differ here
+                    expected = mod[p]
+                else:
+                    expected = vanilla[p]  # the oracle saw no change
+                compared += 1
+                if modded[p] != expected:
+                    mismatches[(base.get(p, vanilla[p]), expected, modded[p])] += 1
+    return compared, mismatches
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument('--profile', default='betterdungeons', choices=[p for p, v in layout.PROFILES.items() if v['carry']])
+    parser.add_argument('--filter', default='', help='only structure ids matching this regex')
+    parser.add_argument('--limit', type=int, default=8, help='mismatch classes shown per structure')
+    args = parser.parse_args()
+    profile = layout.PROFILES[args.profile]
+    results = sorted((layout.ORACLE / args.profile).glob('seed-*.json.gz'))
+    missing = [jar for jar in profile['mods'].values() if not (layout.JARS / jar).exists()]
+    if not results or missing:
+        print(f'SKIP: oracle results or mod jars missing under {layout.ORACLE} (see test_structure_layout_parity.py)')
+        return 0
+    resources = layout.overlay(args.profile, layout.carry(args.profile, profile['mods'], profile['carry']))
+    binary = layout.probe_binary()
+    names = state_names(lab.RESOURCES)
+    totals = defaultdict(lambda: [0, 0, Counter()])  # structure -> [starts, compared, mismatches]
+    for path in results:
+        oracle = json.load(gzip.open(path))
+        seed = oracle['seed']
+        starts = [s for s in oracle['structures'] if s['complete'] and re.search(args.filter, s['id'])]
+        for dimension in sorted({s['dimension'] for s in starts}):
+            here = [s for s in starts if s['dimension'] == dimension]
+            boxes = [s['diff_box'] for s in here]
+            dim = dimension.removeprefix('minecraft:')
+            vanilla = generate(binary, lab.RESOURCES, seed, dim, boxes, names)
+            modded = generate(binary, resources, seed, dim, boxes, names)
+            for start in here:
+                compared, mismatches = compare(start, vanilla, modded)
+                total = totals[start['id']]
+                total[0] += 1
+                total[1] += compared
+                total[2].update(mismatches)
+    failed = False
+    for structure, (starts, compared, mismatches) in sorted(totals.items()):
+        wrong = sum(mismatches.values())
+        reason = next((r for pattern, r in KNOWN.get(args.profile, {}).items() if re.search(pattern, structure)), None)
+        verdict = 'ok   ' if not wrong else 'known' if reason else 'FAIL '
+        failed |= verdict == 'FAIL '
+        print(f'{verdict} {structure}: {starts} starts, {compared - wrong} of {compared} positions match'
+              + (f' ({reason})' if wrong and reason else ''))
+        for (base, expected, got), n in mismatches.most_common(args.limit):
+            print(f'        {n:6}  no-mod {base}  expected {expected}  Horizon {got}')
+    return 1 if failed else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

From da150409ea6b63f8a70450d5d7a62ac00a8c2ed1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kaic=20Salom=C3=A3o?= <imkaicsm@gmail.com>
Date: Sun, 25 Oct 2026 02:49:22 -0300
Subject: [PATCH 034/270] Complete and color mod commands in the chat on the
 server thread

---
 crates/horizon-client/src/game/chat.rs   |  2 +-
 crates/horizon-client/src/game/mods.rs   | 25 ++++++++++++++++++++++++
 crates/horizon-client/src/game/remote.rs |  1 +
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/game/chat.rs b/crates/horizon-client/src/game/chat.rs
index 1bc30513b..e879698c7 100644
--- a/crates/horizon-client/src/game/chat.rs
+++ b/crates/horizon-client/src/game/chat.rs
@@ -18,7 +18,7 @@ fn chat_tree<'a>(
     mods: &'a super::mods::ModsState,
 ) -> &'a horizon_client::command::Dispatcher {
     match remote.as_ref().and_then(|r| r.commands.as_ref()) {
-        Some(tree) => tree,
+        Some(tree) => mods.remote_dispatcher().unwrap_or(tree),
         None => mods.dispatcher(),
     }
 }
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 572f9fe2b..982c7f097 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -39,6 +39,9 @@ pub(super) struct ModsState {
     /// The chat's command tree while a running mod owns commands.
     #[cfg(feature = "mods")]
     tree: Option<Dispatcher>,
+    /// The server's command tree with the running mods' commands added.
+    #[cfg(feature = "mods")]
+    remote_tree: Option<Dispatcher>,
 }
 impl ModsState {
     /// The chat's command tree: vanilla's, plus the running mods' commands.
@@ -49,6 +52,14 @@ impl ModsState {
         }
         vanilla::game_dispatcher()
     }
+    /// The server's tree plus the mods' commands, when a mod owns any.
+    pub(super) fn remote_dispatcher(&self) -> Option<&Dispatcher> {
+        #[cfg(feature = "mods")]
+        if let Some(tree) = &self.remote_tree {
+            return Some(tree);
+        }
+        None
+    }
     /// Whether a mod runs: the chat keeps its lines for them.
     pub(super) fn running(&self) -> bool {
         #[cfg(feature = "mods")]
@@ -158,6 +169,7 @@ impl Game<'_> {
             );
         }
     }
+    pub(super) fn merge_remote_tree(&mut self) {}
     pub(super) fn sync_mods(&mut self) {}
     pub(super) fn tick_mods(&mut self) {}
     pub(super) fn mods_frame(&mut self, _elapsed: Duration) {}
@@ -238,7 +250,20 @@ impl Game<'_> {
             .peek()
             .is_some()
             .then(|| vanilla::game_dispatcher().with_mod_commands(names));
+        self.merge_remote_tree();
     }
+
+    /// The server's command tree with the mods' commands, for the chat.
+    pub(super) fn merge_remote_tree(&mut self) {
+        let names: Vec<String> = self.mods.mods.commands().map(str::to_owned).collect();
+        self.mods.remote_tree = self
+            .remote
+            .as_ref()
+            .and_then(|r| r.commands.as_ref())
+            .filter(|_| !names.is_empty())
+            .map(|t| t.with_mod_commands(names.iter().map(String::as_str)));
+    }
+
     /// After the options changed: restart the mods if the list of the ones
     /// turned on did.
     pub(super) fn sync_mods(&mut self) {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 23c6677c2..9da81e551 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -2423,6 +2423,7 @@ impl Game<'_> {
                 if let Some(r) = self.remote.as_mut() {
                     r.commands = Some(tree);
                 }
+                self.merge_remote_tree();
             }
             C::SystemChat(p) => {
                 // The component as sent, translated in the client's own

From aac2f3a903524bb56685a218a8992b99614a34a5 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 07:44:21 +0100
Subject: [PATCH 035/270] Shader packs, clean room 29: entity spans

While a shader pack is loaded, building the entity geometry records where
each entity's vertices begin, with its render stage (entities, block
entities, particles, breaking cracks) and its `entityId` or
`blockEntityId` from the pack's `entity.properties` and
`block.properties` (65535 for a name the file lacks, 0 without the
file). The spans reach the renderer in `Frame::entity_spans`, for the
pack's per-entity draws that follow; Horizon's own entity draw stays one
call and without a pack nothing is recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             | 45 ++++++++++-
 crates/horizon-client/src/game/creatures.rs   |  1 +
 .../horizon-client/src/game/shader_packs.rs   | 80 +++++++++++++++++++
 crates/horizon-client/src/gfx.rs              |  4 +-
 crates/horizon-client/src/gfx/pack_draw.rs    | 14 ++++
 crates/horizon-shaders/src/block_ids.rs       | 33 +++++++-
 6 files changed, 172 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 352e1e30e..f43593360 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1228,6 +1228,11 @@ struct Game<'a> {
     luminance: Option<horizon_client::dynamic_light::Luminance>,
     /// Name tags drawn over everything (`RenderPipelines.TEXT_SEE_THROUGH`).
     see_through_vertices: Vec<Vertex>,
+    /// Runs of `entity_vertices` by entity, for a shader pack's per-entity draws; recorded only
+    /// while `pack_ids` is set (game/shader_packs.rs).
+    entity_spans: std::cell::RefCell<Vec<horizon_client::gfx::pack_draw::EntitySpan>>,
+    /// The shader pack's entity and block entity ids, while one draws entities.
+    pack_ids: Option<shader_packs::PackIds>,
     started: Instant,
     previous: Instant,
     /// FramerateLimitTracker.latestInputTime.
@@ -6668,8 +6673,10 @@ impl Game<'_> {
         alpha: f64,
         mut out: Vec<Vertex>,
     ) -> Vec<Vertex> {
+        self.entity_spans.borrow_mut().clear();
         self.prepare_entity_culling(camera);
         self.prepare_trims();
+        self.mark_entity(out.len(), "minecraft:entity_flame");
         let fire_yaw = if self.camera_type == perspective::CameraType::ThirdPersonFront {
             self.yaw + 180.0
         } else {
@@ -6761,20 +6768,27 @@ impl Game<'_> {
             }
         }
         // `ItemEntityRenderer`.
+        self.mark_entity(out.len(), "minecraft:item");
         self.dropped_item_geometry(camera, alpha, &mut out);
         // `VaultRenderer`.
+        self.mark_entity(out.len(), "");
         self.vault_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:ominous_item_spawner");
         self.ominous_item_spawner_geometry(camera, alpha, &mut out);
-        // Mobs and their projectiles.
+        // Mobs and their projectiles (a span each).
         self.mob_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:player");
         self.player_model_geometry(camera, self.clock.camera_fraction(), &mut out);
         self.guest_model_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:evoker_fangs");
         self.fangs_geometry(camera, alpha, &mut out);
         let mut see_through = std::mem::take(&mut self.see_through_vertices);
         see_through.clear();
+        self.mark_entity(out.len(), "minecraft:name_tag");
         self.name_tag_geometry(camera, alpha, &mut out, &mut see_through);
         self.see_through_vertices = see_through;
         // Entity shadows (EntityRenderer.extractShadow).
+        self.mark_entity(out.len(), "minecraft:entity_shadow");
         if let Some(sprite) = self.gui.atlas.sprites.get("misc/shadow").copied() {
             let ambient = if self.dim == Dim::Nether { 0.1 } else { 0.0 };
             let darken = self.sky_darken();
@@ -6868,13 +6882,14 @@ impl Game<'_> {
                         v.intersects(o - glam::Vec3::ONE, o + glam::Vec3::splat(2.0))
                     })
             });
-            if self.entity_culler.is_some() {
+            if self.entity_culler.is_some() || self.pack_ids.is_some() {
                 for block in visible {
                     let start = out.len();
+                    self.mark_block_entity(start, block.1);
                     self.res
                         .block_entity_render()
                         .render(&scene, std::iter::once(block), &mut out);
-                    if !off_screen(block.1) {
+                    if !off_screen(block.1) && self.entity_culler.is_some() {
                         self.cull_entity_vertices(&mut out, start);
                     }
                 }
@@ -6883,6 +6898,7 @@ impl Game<'_> {
                     .block_entity_render()
                     .render(&scene, visible, &mut out);
             }
+            self.mark_stage(out.len(), "DESTROY");
             for (pos, stage) in self.cracks(camera) {
                 let state = self.world.block(pos[0], pos[1], pos[2]);
                 self.res
@@ -6891,6 +6907,7 @@ impl Game<'_> {
             }
         }
         // Experience orbs (ExperienceOrbRenderer): pulsing billboards from a 4x4 icon sheet.
+        self.mark_entity(out.len(), "minecraft:experience_orb");
         if let Some(r) = self
             .gui
             .atlas
@@ -6954,6 +6971,7 @@ impl Game<'_> {
             }
         }
         // Falling blocks use their baked model, including non-cubic shapes.
+        self.mark_entity(out.len(), "minecraft:falling_block");
         for f in &self.falling {
             let Some((_, tint)) = self.block_face_sprite(f.state) else {
                 continue;
@@ -6984,20 +7002,34 @@ impl Game<'_> {
                 vertex.color = horizon_client::hud_layout::multiply(vertex.color, tint);
             }
         }
+        self.mark_entity(out.len(), "");
         self.moving_piston_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:tnt");
         self.tnt_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:painting");
         self.painting_geometry(camera, &mut out);
+        self.mark_entity(out.len(), "minecraft:item_frame");
         self.frame_geometry(camera, &mut out);
+        self.mark_entity(out.len(), "minecraft:armor_stand");
         self.armor_stand_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:oak_boat");
         self.boat_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:minecart");
         self.cart_geometry(camera, alpha, &mut out);
+        self.mark_stage(out.len(), "BLOCK_ENTITIES");
         self.beacon_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:fishing_bobber");
         self.fishing_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:leash_knot");
         self.leash_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:trident");
         self.trident_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:firework_rocket");
         self.rocket_geometry(camera, alpha, &mut out);
+        self.mark_entity(out.len(), "minecraft:splash_potion");
         self.thrown_potion_geometry(camera, alpha, &mut out);
         // Particles (ParticleEngine.extract): camera-facing quads.
+        self.mark_stage(out.len(), "PARTICLES");
         let world = &self.world;
         self.particles.render(
             camera,
@@ -7008,6 +7040,7 @@ impl Game<'_> {
             &mut out,
         );
         // Breaking progress overlays (destroy_stage_0..9): ours and the other players'.
+        self.mark_stage(out.len(), "DESTROY");
         for (pos, stage) in self.cracks(camera) {
             let o = (glam::DVec3::new(f64::from(pos[0]), f64::from(pos[1]), f64::from(pos[2]))
                 - camera)
@@ -10070,6 +10103,7 @@ impl Game<'_> {
         } else {
             self.shader_pack_inputs(camera, alpha as f32)
         };
+        let entity_spans = std::mem::take(self.entity_spans.get_mut());
         let frame = Frame {
             weather: &weather,
             weather_time: horizon_client::weather::Time::new(self.world.game_time, alpha as f32),
@@ -10134,6 +10168,7 @@ impl Game<'_> {
                 color: sky.cloud_color,
             }),
             entities: &entities,
+            entity_spans: &entity_spans,
             dynamic_lights: &self.dynamic_lights,
             lightning: horizon_client::gfx::lightning::Input {
                 bolts: &bolts,
@@ -10182,6 +10217,7 @@ impl Game<'_> {
         };
         // Restore storage even when rendering fails (for example, a lost surface).
         self.entity_vertices = entities;
+        *self.entity_spans.get_mut() = entity_spans;
         self.see_through_vertices = see_through;
         result
     }
@@ -11762,6 +11798,8 @@ impl<'a> Game<'a> {
             dynamic_lights: Vec::new(),
             luminance: None,
             see_through_vertices: Vec::new(),
+            entity_spans: Default::default(),
+            pack_ids: None,
             health_hud: hud_layout::HealthHud::default(),
             started: now,
             previous: now,
@@ -12686,6 +12724,7 @@ fn loading_frame(hud: &HudBatch) -> Frame<'_> {
         hud,
         nether_lighting: false,
         entities: &[],
+        entity_spans: &[],
         dynamic_lights: &[],
         clouds: None,
         lightning: Default::default(),
diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index ec9848919..31a1500d7 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -2996,6 +2996,7 @@ impl Game<'_> {
                     continue;
                 }
             }
+            self.mark_entity(entity_start, &mob.kind.id);
             let light = self.world.light(
                 mob.position.x.floor() as i32,
                 (mob.position.y + mob.eye_height()).floor() as i32,
diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index f5f7a5fba..6699a753d 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -7,6 +7,21 @@ use horizon_client::gfx::pack_uniforms::PackInputs;
 use horizon_shaders::{BlockIds, Macros, Pack, Properties, dimension_folder, load_post};
 
 use super::{Dim, Game};
+use horizon_client::gfx::pack_draw::EntitySpan;
+use std::cell::RefCell;
+use std::collections::HashMap;
+
+/// The ids a pack gives entities and block entities (4.1, 5.3), for the spans of the entity
+/// geometry.
+pub(super) struct PackIds {
+    entities: HashMap<String, i32>,
+    blocks: BlockIds,
+    /// `blockEntityId` by block state, filled as states are drawn.
+    block_states: RefCell<HashMap<u32, i32>>,
+    /// The id of a name the file lacks: 65535, or 0 without the file.
+    missing_entity: i32,
+    missing_block: i32,
+}
 
 impl Game<'_> {
     /// Loads the pack for the current dimension when it changed, and returns this frame's
@@ -52,6 +67,18 @@ impl Game<'_> {
                     for note in &ids.notes {
                         log::warn!("shader pack {name}: block.properties: {note}");
                     }
+                    let text = pack.read_text("entity.properties");
+                    let entities = BlockIds::parse_kind(
+                        &Properties::parse(text.as_deref().unwrap_or_default(), &macros),
+                        "entity",
+                    );
+                    self.pack_ids = Some(PackIds {
+                        entities: entities.plain(),
+                        missing_entity: if text.is_some() { 65535 } else { 0 },
+                        missing_block: if ids.is_empty() { 0 } else { 65535 },
+                        blocks: ids.clone(),
+                        block_states: RefCell::default(),
+                    });
                     let started_ids = std::time::Instant::now();
                     let table = block_id_table(&self.pack, &ids);
                     log::info!(
@@ -75,6 +102,7 @@ impl Game<'_> {
                     }
                 }
                 Err(e) => {
+                    self.pack_ids = None;
                     log::warn!("shader pack {name}: {e}");
                     renderer.set_shader_pack(dimension, None, &[]);
                 }
@@ -114,6 +142,58 @@ impl Game<'_> {
     }
 }
 
+impl Game<'_> {
+    /// Starts a span of the entity geometry at vertex `start` for entity type `name`
+    /// (`minecraft:zombie`; "" for one the pack cannot name). Nothing without a pack.
+    pub(super) fn mark_entity(&self, start: usize, name: &str) {
+        if let Some(ids) = &self.pack_ids {
+            let id = ids.entities.get(name).copied();
+            self.push_span(start, "ENTITIES", id.unwrap_or(ids.missing_entity));
+        }
+    }
+
+    /// Starts a span for the block entity of block state `state`.
+    pub(super) fn mark_block_entity(&self, start: usize, state: u32) {
+        let Some(ids) = &self.pack_ids else { return };
+        let id = *ids
+            .block_states
+            .borrow_mut()
+            .entry(state)
+            .or_insert_with(|| {
+                let registry = self.pack.assets.registry;
+                registry
+                    .state(horizon_world::registry::BlockStateId(state))
+                    .and_then(|s| {
+                        ids.blocks
+                            .id(&s.name, |k| s.properties.get(k).map(String::as_str))
+                    })
+                    .unwrap_or(ids.missing_block)
+            });
+        self.push_span(start, "BLOCK_ENTITIES", id);
+    }
+
+    /// Starts a span of geometry that is not an entity (`PARTICLES`, `DESTROY`...).
+    pub(super) fn mark_stage(&self, start: usize, stage: &str) {
+        if self.pack_ids.is_some() {
+            self.push_span(start, stage, 0);
+        }
+    }
+
+    fn push_span(&self, start: usize, stage: &str, id: i32) {
+        let mut spans = self.entity_spans.borrow_mut();
+        let span = EntitySpan {
+            start: start as u32,
+            stage: horizon_shaders::render_stage(stage),
+            id,
+        };
+        // A span that drew nothing gives way to the next.
+        match spans.last_mut() {
+            Some(last) if last.start == span.start => *last = span,
+            _ => spans.push(span),
+        }
+    }
+}
+
 /// `mc_Entity` (x, y) of each block sprite layer, as (id, fluid) pairs: terrain vertices carry
 /// their sprite layer, not their block. A layer takes the id of the block named like its sprite
 /// (`block/oak_leaves` for `oak_leaves`), else the id most blocks drawing it share (ties: the
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index f829b9eb1..4351fd85d 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -69,7 +69,7 @@ pub mod lightning;
 mod lod;
 mod occlusion;
 mod pack_atlas;
-mod pack_draw;
+pub mod pack_draw;
 mod pack_post;
 mod pack_sky;
 mod pack_timing;
@@ -248,6 +248,8 @@ pub struct Frame<'a> {
     pub nether_lighting: bool,
     /// Camera-relative entity geometry textured from the shared atlas.
     pub entities: &'a [Vertex],
+    /// Runs of `entities` by entity, while a shader pack draws them (`pack_draw::EntitySpan`).
+    pub entity_spans: &'a [pack_draw::EntitySpan],
     pub weather: &'a [crate::weather::Vertex],
     pub weather_time: crate::weather::Time,
     /// Horizon Extras' dynamic lights, nearest first (`dynamic_light::select`); empty when off.
diff --git a/crates/horizon-client/src/gfx/pack_draw.rs b/crates/horizon-client/src/gfx/pack_draw.rs
index 91c77a6bf..f365c484f 100644
--- a/crates/horizon-client/src/gfx/pack_draw.rs
+++ b/crates/horizon-client/src/gfx/pack_draw.rs
@@ -4,6 +4,20 @@
 
 use horizon_shaders::{RENDER_STAGES, render_stage};
 
+/// Where a run of `Frame::entities` begins, and what it is (slice 7): the run lasts until the
+/// next span. Recorded only while a shader pack draws entities, so Horizon's own frames carry
+/// none; Horizon itself still draws the whole list at once.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct EntitySpan {
+    /// The first vertex.
+    pub start: u32,
+    /// The render stage (5.4: `ENTITIES`, `BLOCK_ENTITIES`, `PARTICLES`, `DESTROY`), which picks
+    /// the program.
+    pub stage: u32,
+    /// `entityId` for entities, `blockEntityId` for block entities (5.3), else 0.
+    pub id: i32,
+}
+
 /// `HzDraw`'s size: `renderStage`, `entityId`, `blockEntityId`, a pad, `entityColor`.
 const SIZE: u32 = 32;
 
diff --git a/crates/horizon-shaders/src/block_ids.rs b/crates/horizon-shaders/src/block_ids.rs
index 623473283..6ebcf6d99 100644
--- a/crates/horizon-shaders/src/block_ids.rs
+++ b/crates/horizon-shaders/src/block_ids.rs
@@ -23,9 +23,16 @@ pub struct BlockIds {
 
 impl BlockIds {
     pub fn parse(properties: &Properties) -> Self {
+        Self::parse_kind(properties, "block")
+    }
+
+    /// The same for `<kind>.<id>=` lines: `entity` in `entity.properties`, `item` in
+    /// `item.properties` (4.1); names there carry no state filters.
+    pub fn parse_kind(properties: &Properties, kind: &str) -> Self {
         let mut out = Self::default();
+        let prefix = format!("{kind}.");
         for e in &properties.entries {
-            let Some(id) = e.key.strip_prefix("block.") else {
+            let Some(id) = e.key.strip_prefix(prefix.as_str()) else {
                 continue;
             };
             let Ok(id) = id.parse::<i32>() else {
@@ -78,6 +85,16 @@ impl BlockIds {
             .map(|r| r.id)
     }
 
+    /// Every name without state filters and its id (the first line naming it wins): what
+    /// `entity.properties` and `item.properties` hold.
+    pub fn plain(&self) -> std::collections::HashMap<String, i32> {
+        let mut out = std::collections::HashMap::new();
+        for r in self.rules.iter().filter(|r| r.filters.is_empty()) {
+            out.entry(r.name.clone()).or_insert(r.id);
+        }
+        out
+    }
+
     pub fn is_empty(&self) -> bool {
         self.rules.is_empty()
     }
@@ -117,4 +134,18 @@ mod tests {
         assert_eq!(ids.id("minecraft:oak_leaves", leaves("false", "1")), None);
         assert_eq!(ids.notes.len(), 1, "{:?}", ids.notes);
     }
+
+    #[test]
+    fn entity_lines_by_name() {
+        let text = "entity.10=zombie minecraft:husk\nentity.11=zombie mod:thing\nblock.5=stone\n";
+        let ids = BlockIds::parse_kind(&Properties::parse(text, &Macros::standard()), "entity");
+        let plain = ids.plain();
+        assert_eq!(
+            plain["minecraft:zombie"], 10,
+            "the first line naming it wins"
+        );
+        assert_eq!(plain["minecraft:husk"], 10);
+        assert_eq!(plain["mod:thing"], 11);
+        assert!(!plain.contains_key("minecraft:stone"));
+    }
 }

From 58e184f5d591f866f164be084173f22633416ebd Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 07:19:22 +0100
Subject: [PATCH 036/270] Structure blocks harness: place the oracle's own
 pieces, split piece boxes from their surroundings

The mod world now takes each saved start whose pieces are all jigsaw pieces
as the oracle saved it (chunk_dump's HORIZON_SAVED_STARTS, through a new
GeneratorWorker::use_saved_start and PoolPiece::from_saved), so the blocks
are checked whatever the layout: Lithostitched lays jigsaws out its own way
(spec-lithostitched OPEN-L5) and the layout harness checks layouts apart.
Lithostitched's wrapper elements place their delegate; 1.21.1 block states
are read in 26.3's shape.

Counts are split between positions inside a piece's box and around them
(terrain adaptation, decoration), and every mismatch class is written to
.local/structure-layout/<profile>/blocks-report.json.

A CTOV profile carries Lithostitched and ChoiceTheorem's Overhauled Village
from a pack's jar folder (.local/structure-oracle/pack-jars).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../examples/probe/chunk_dump.rs              |  16 +++
 .../horizon-world/src/worldgen/generator.rs   |  33 ++++++
 .../src/worldgen/generator_structures.rs      |  46 +++++++-
 .../src/worldgen/structure/jigsaw.rs          |  57 ++++++++++
 .../src/worldgen/structure/start.rs           |  41 ++++---
 tools/test_structure_blocks_parity.py         | 105 ++++++++++++++----
 tools/test_structure_layout_parity.py         |  27 ++++-
 7 files changed, 280 insertions(+), 45 deletions(-)

diff --git a/crates/horizon-world/examples/probe/chunk_dump.rs b/crates/horizon-world/examples/probe/chunk_dump.rs
index d36944989..1e89d03df 100644
--- a/crates/horizon-world/examples/probe/chunk_dump.rs
+++ b/crates/horizon-world/examples/probe/chunk_dump.rs
@@ -2,6 +2,9 @@
 //!
 //! chunk_dump <client resource dir> <seed> <dimension> <x0,z0,x1,z1>...
 //! With HORIZON_SCAN set, one rectangle lists the structure starts in it.
+//! HORIZON_SAVED_STARTS names a JSON file of saved starts (`[{"id", "chunk":
+//! [x, z], "pieces": [...]}]`, jigsaw pieces as a save lists them) that take
+//! the place of the starts generation builds in their chunks.
 //!
 //! Chunks are generated through biomes, terrain and carvers, then decorated in
 //! row-major order over the target rectangle grown by one chunk (or in the
@@ -166,10 +169,23 @@ pub fn main() -> Result<(), Error> {
         }
         return Ok(());
     }
+    let saved: Vec<Value> = match std::env::var_os("HORIZON_SAVED_STARTS") {
+        Some(path) => serde_json::from_str(&fs::read_to_string(path)?)?,
+        None => Vec::new(),
+    };
     for [x0, z0, x1, z1] in rects {
         // Each rectangle starts from scratch, like the oracle's fresh chunks:
         // structure pieces keep placement state (a shipwreck's adjusted height).
         worker.forget_structure_starts();
+        for start in &saved {
+            let chunk = ChunkPos::new(
+                start["chunk"][0].as_i64().ok_or("saved start chunk")? as i32,
+                start["chunk"][1].as_i64().ok_or("saved start chunk")? as i32,
+            );
+            let pieces = start["pieces"].as_array().ok_or("saved start pieces")?;
+            let id = start["id"].as_str().ok_or("saved start id")?;
+            worker.use_saved_start(chunk, id, pieces)?;
+        }
         let mut chunks: HashMap<(i32, i32), ProtoChunk> = HashMap::new();
         for z in z0 - 2..=z1 + 2 {
             for x in x0 - 2..=x1 + 2 {
diff --git a/crates/horizon-world/src/worldgen/generator.rs b/crates/horizon-world/src/worldgen/generator.rs
index 2595173ad..1ba9f86a3 100644
--- a/crates/horizon-world/src/worldgen/generator.rs
+++ b/crates/horizon-world/src/worldgen/generator.rs
@@ -1651,6 +1651,13 @@ trait SeededPipeline: Send + Sync {
         pos: ChunkPos,
     ) -> Vec<Arc<super::structure::start::StructureStart>>;
     fn unsupported_features(&self) -> Vec<(String, String)>;
+    fn use_saved_start(
+        &self,
+        worker: &mut WorkerState,
+        chunk: ChunkPos,
+        structure: &str,
+        pieces: &[serde_json::Value],
+    ) -> Result<(), String>;
     fn forget_structure_starts(&self);
     fn ring_positions(&self, set: &str) -> Option<Vec<ChunkPos>>;
     fn spawn_position(&self) -> Result<[i32; 2], GeneratorError>;
@@ -1747,6 +1754,21 @@ where
             .map(super::generator_decoration::Decoration::unsupported)
             .unwrap_or_default()
     }
+    fn use_saved_start(
+        &self,
+        worker: &mut WorkerState,
+        chunk: ChunkPos,
+        structure: &str,
+        pieces: &[serde_json::Value],
+    ) -> Result<(), String> {
+        let structures = (self.structures.as_ref()).ok_or("structures were not loaded")?;
+        let mut queries = StructureQueries {
+            pipeline: self,
+            worker,
+            valid: BTreeSet::new(),
+        };
+        structures.use_saved_start(&mut queries, chunk, structure, pieces)
+    }
     fn forget_structure_starts(&self) {
         if let Some(structures) = &self.structures {
             structures.forget_starts();
@@ -2494,6 +2516,17 @@ impl GeneratorWorker {
     ) -> Vec<Arc<super::structure::start::StructureStart>> {
         self.pipeline.structure_starts(&mut self.state, pos)
     }
+    /// Puts a saved start of `structure` (its pieces as a save lists them, in
+    /// JSON) in `chunk`, in place of the one generation builds there, until
+    /// the starts are forgotten. Harnesses place another game's layout.
+    pub fn use_saved_start(
+        &mut self,
+        chunk: ChunkPos,
+        structure: &str,
+        pieces: &[serde_json::Value],
+    ) -> Result<(), String> {
+        (self.pipeline).use_saved_start(&mut self.state, chunk, structure, pieces)
+    }
     /// Forget the cached structure starts: chunks generated afterwards get
     /// fresh starts, as in a new level that has not loaded the old chunks.
     pub fn forget_structure_starts(&mut self) {
diff --git a/crates/horizon-world/src/worldgen/generator_structures.rs b/crates/horizon-world/src/worldgen/generator_structures.rs
index 1e4913c95..7e242cf65 100644
--- a/crates/horizon-world/src/worldgen/generator_structures.rs
+++ b/crates/horizon-world/src/worldgen/generator_structures.rs
@@ -5,8 +5,10 @@ use super::{
     generator::{ChunkWork, GeneratorData, GeneratorError},
     structure::{
         StructureResources,
+        jigsaw::PoolPiece,
         start::{
-            Rings, StartContext, StructureRegistry, StructureStart, beardifier, create_starts,
+            Piece, Rings, StartContext, StructureRegistry, StructureStart, beardifier,
+            create_starts,
         },
         stronghold::RingSearch,
     },
@@ -142,6 +144,9 @@ impl StartCache {
         }
         shard.entry(key).or_insert(starts).clone()
     }
+    fn replace(&self, key: (i32, i32), starts: Starts) {
+        self.shard(key).write().unwrap().insert(key, starts);
+    }
     fn clear(&self) {
         for shard in &self.shards {
             shard.write().unwrap().clear();
@@ -285,6 +290,45 @@ impl StructureState {
         );
         self.starts.insert_first((chunk.x, chunk.z), starts)
     }
+    /// Puts a saved start of `structure` in `chunk`, in place of the one
+    /// this generator builds there from the same structure sets (a set
+    /// starts one structure per chunk): `pieces` as a save lists them (see
+    /// `PoolPiece::from_saved`). Until the starts are forgotten.
+    pub(super) fn use_saved_start(
+        &self,
+        context: &mut impl super::structure::start::StartContext,
+        chunk: ChunkPos,
+        structure: &str,
+        pieces: &[Value],
+    ) -> Result<(), String> {
+        let index = (self.registry.structures.iter())
+            .position(|s| s.name == structure)
+            .ok_or_else(|| format!("unknown structure {structure}"))?;
+        let pieces = (pieces.iter())
+            .map(|p| PoolPiece::from_saved(p, &self.resources, &self.bindings).map(Piece::Pool))
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(|e| format!("{structure} at {chunk:?}: {e}"))?;
+        if pieces.is_empty() {
+            return Err(format!("{structure} at {chunk:?}: no pieces"));
+        }
+        let def = &self.registry.structures[index];
+        let sets: Vec<_> = (self.registry.sets.iter())
+            .filter(|set| set.structures.iter().any(|(s, _)| *s == index))
+            .collect();
+        let same_set = |s: usize| {
+            s == index
+                || sets
+                    .iter()
+                    .any(|set| set.structures.iter().any(|(t, _)| *t == s))
+        };
+        let mut starts: Vec<_> = (self.starts_at(context, chunk).iter())
+            .filter(|s| !same_set(s.structure))
+            .cloned()
+            .collect();
+        starts.push(Arc::new(StructureStart::new(index, def, chunk, pieces)));
+        self.starts.replace((chunk.x, chunk.z), Arc::new(starts));
+        Ok(())
+    }
     /// ChunkGenerator.findNearestMapStructure: the nearest start of one of
     /// `names` from block `from` (rings: every ring chunk; random spreads:
     /// sectors in growing squares up to `radius`). Returns the structure and
diff --git a/crates/horizon-world/src/worldgen/structure/jigsaw.rs b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
index 6e1da3a4c..f53f712f3 100644
--- a/crates/horizon-world/src/worldgen/structure/jigsaw.rs
+++ b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
@@ -458,6 +458,63 @@ pub struct PoolPiece {
     pub waterlogging: bool,
 }
 impl PoolPiece {
+    /// A piece as a saved start lists it (PoolElementStructurePiece's tag:
+    /// `pool_element`, `PosX`/`PosY`/`PosZ`, `rotation`, `ground_level_delta`,
+    /// `BB`, `junctions`, `liquid_settings`), in JSON. Harnesses place another
+    /// game's layout with it.
+    pub fn from_saved(
+        v: &Value,
+        resources: &StructureResources,
+        bindings: &FeatureBlockBindings<'_>,
+    ) -> Result<Self, DecodeError> {
+        let int = |v: &Value, key: &'static str| {
+            v[key]
+                .as_i64()
+                .and_then(|i| i32::try_from(i).ok())
+                .ok_or(DecodeError::Field(key))
+        };
+        let corners: Vec<i32> = v["BB"]
+            .as_array()
+            .into_iter()
+            .flatten()
+            .filter_map(|i| i32::try_from(i.as_i64()?).ok())
+            .collect();
+        let [x0, y0, z0, x1, y1, z1]: [i32; 6] =
+            corners.try_into().map_err(|_| DecodeError::Field("BB"))?;
+        let rotation = match v["rotation"].as_str() {
+            Some("NONE") => Rotation::None,
+            Some("CLOCKWISE_90") => Rotation::Clockwise90,
+            Some("CLOCKWISE_180") => Rotation::Clockwise180,
+            Some("COUNTERCLOCKWISE_90") => Rotation::Counterclockwise90,
+            _ => return Err(DecodeError::Field("rotation")),
+        };
+        let junctions = v["junctions"]
+            .as_array()
+            .into_iter()
+            .flatten()
+            .map(|j| {
+                Ok(Junction {
+                    source_x: int(j, "source_x")?,
+                    source_ground_y: int(j, "source_ground_y")?,
+                    source_z: int(j, "source_z")?,
+                })
+            })
+            .collect::<Result<_, DecodeError>>()?;
+        Ok(Self {
+            element: Arc::new(PoolElement::decode(
+                &v["pool_element"],
+                resources,
+                bindings,
+                None,
+            )?),
+            position: [int(v, "PosX")?, int(v, "PosY")?, int(v, "PosZ")?],
+            ground_level_delta: int(v, "ground_level_delta")?,
+            rotation,
+            bounding_box: BoundingBox::new([x0, y0, z0], [x1, y1, z1]),
+            junctions,
+            waterlogging: v["liquid_settings"].as_str() != Some("ignore_waterlogging"),
+        })
+    }
     pub(super) fn moved(&mut self, dy: i32) {
         self.position[1] += dy;
         self.bounding_box = self.bounding_box.moved([0, dy, 0]);
diff --git a/crates/horizon-world/src/worldgen/structure/start.rs b/crates/horizon-world/src/worldgen/structure/start.rs
index a98a9f88f..a157d1528 100644
--- a/crates/horizon-world/src/worldgen/structure/start.rs
+++ b/crates/horizon-world/src/worldgen/structure/start.rs
@@ -1166,24 +1166,31 @@ fn try_generate(
     if !def.biomes.contains(&context.noise_biome(quart)) || pieces.is_empty() {
         return None;
     }
-    let mut bounding_box = pieces[0].bounding_box();
-    for piece in &pieces[1..] {
-        bounding_box.encapsulate(&piece.bounding_box());
+    Some(StructureStart::new(structure, def, chunk, pieces))
+}
+impl StructureStart {
+    /// A start of `def` (registry index `structure`) from its pieces, at
+    /// least one: their box, grown where the structure adapts the terrain.
+    pub fn new(structure: usize, def: &StructureDef, chunk: ChunkPos, pieces: Vec<Piece>) -> Self {
+        let mut bounding_box = pieces[0].bounding_box();
+        for piece in &pieces[1..] {
+            bounding_box.encapsulate(&piece.bounding_box());
+        }
+        if def.terrain != TerrainAdjustment::None {
+            bounding_box = bounding_box.inflated(12, 12);
+        }
+        if let Some(enhanced) = def.enhanced_terrain.as_ref().filter(|e| e.inflate) {
+            let r = enhanced.radius();
+            bounding_box = bounding_box.inflated(r, r);
+        }
+        Self {
+            structure,
+            name: def.name.clone(),
+            chunk,
+            pieces,
+            bounding_box,
+        }
     }
-    if def.terrain != TerrainAdjustment::None {
-        bounding_box = bounding_box.inflated(12, 12);
-    }
-    if let Some(enhanced) = def.enhanced_terrain.as_ref().filter(|e| e.inflate) {
-        let r = enhanced.radius();
-        bounding_box = bounding_box.inflated(r, r);
-    }
-    Some(StructureStart {
-        structure,
-        name: def.name.clone(),
-        chunk,
-        pieces,
-        bounding_box,
-    })
 }
 /// PoolAliasLookup.create.
 fn resolve_aliases(bindings: &[Value], position: [i32; 3], seed: i64) -> BTreeMap<String, String> {
diff --git a/tools/test_structure_blocks_parity.py b/tools/test_structure_blocks_parity.py
index 006046a31..39ccb4e49 100644
--- a/tools/test_structure_blocks_parity.py
+++ b/tools/test_structure_blocks_parity.py
@@ -7,7 +7,10 @@ start of a mod world, its blocks (`blocks`, the start's box) and every position
 
 Horizon side: the chunk_dump probe generates the chunks around each start in full (terrain, structures,
 features) twice: from the 26.3 resources (the no-mod world) and from those resources with the mods carried
-by `horizon-port-pack carry` (the mod world), as test_structure_layout_parity.py builds them.
+by `horizon-port-pack carry` (the mod world), as test_structure_layout_parity.py builds them. In the mod
+world each start whose pieces are all jigsaw pieces is the oracle's own (HORIZON_SAVED_STARTS): the blocks
+are checked whatever the layout (Lithostitched lays out jigsaws its own way, spec-lithostitched OPEN-L5), and
+test_structure_layout_parity.py checks layouts apart.
 
 The oracle's game is 1.21.1 and Horizon's 26.3, so the worlds also differ where the versions do. A position
 is compared only where the two no-mod worlds agree (the oracle's no-mod block is known inside the start's
@@ -18,7 +21,7 @@ A mismatch is counted by the oracle's no-mod block, the expected block and Horiz
 missing rule reads as one line. KNOWN names the mismatch classes the implementation does not cover yet, with
 the reason; they are reported, not failed.
 
-usage: test_structure_blocks_parity.py [--profile betterdungeons] [--filter REGEX] [--limit N]
+usage: test_structure_blocks_parity.py [--profile betterdungeons|ctov] [--filter REGEX] [--limit N]
 """
 import argparse
 import gzip
@@ -35,6 +38,13 @@ except ImportError:
     import lab
     import test_structure_layout_parity as layout
 
+# The mod profiles: the layout harness's, and CTOV (its jar and Lithostitched's come from a pack's jar
+# folder, `.local/structure-oracle/pack-jars/`).
+PROFILES = {
+    **{name: p for name, p in layout.PROFILES.items() if p['carry']},
+    'ctov': {'mods': {'lithostitched': 'lithostitched-1.8.1-neoforge-21.1.jar', 'ctov': '[Neoforge]ctov-3.6.3.jar'},
+             'carry': ['lithostitched', 'ctov']},
+}
 # profile -> {structure id regex: what the implementation does not cover yet}
 KNOWN = {
     'betterdungeons': {
@@ -64,10 +74,37 @@ def chunk_rect(box):
     return f'{x0 >> 4},{z0 >> 4},{x1 >> 4},{z1 >> 4}'
 
 
-def generate(binary, resources, seed, dimension, boxes, names):
-    """Block states by position inside `boxes`, from chunk_dump's full generation of their chunks."""
+def saved_element(element):
+    """A saved pool element as the game reads it: Lithostitched's wrappers place their `delegate`
+    (spec-lithostitched §3), and 1.21.1's `{"Name", "Properties"}` states are 26.3's `{"id", "properties"}`."""
+    if isinstance(element, dict):
+        if 'delegate' in element and str(element.get('element_type', '')).startswith('lithostitched:'):
+            return saved_element(element['delegate'])
+        if 'Name' in element and set(element) <= {'Name', 'Properties'}:
+            return {'id': element['Name'], **({'properties': element['Properties']} if 'Properties' in element else {})}
+        return {k: saved_element(v) for k, v in element.items()}
+    if isinstance(element, list):
+        return [saved_element(v) for v in element]
+    return element
+
+
+def saved_starts(starts):
+    """The starts chunk_dump can place as saved (every piece a jigsaw piece), in HORIZON_SAVED_STARTS's form."""
+    return [{'id': s['id'], 'chunk': s['start_chunk'],
+             'pieces': [{**p, 'pool_element': saved_element(p['pool_element'])} for p in s['pieces']]}
+            for s in starts if s['pieces'] and all(p['id'] == 'minecraft:jigsaw' for p in s['pieces'])]
+
+
+def generate(binary, resources, seed, dimension, boxes, names, saved=()):
+    """Block states by position inside `boxes`, from chunk_dump's full generation of their chunks, with the
+    `saved` starts in place of the ones generation builds."""
+    env = dict(os.environ)
+    if saved:
+        path = lab.LOCAL / 'structure-layout' / 'saved-starts.json'
+        path.write_text(json.dumps(list(saved)))
+        env['HORIZON_SAVED_STARTS'] = str(path)
     result = subprocess.run([str(binary), 'chunk_dump', str(resources), str(seed), dimension,
-                             *(chunk_rect(b) for b in boxes)], capture_output=True, text=True, cwd=lab.ROOT)
+                             *(chunk_rect(b) for b in boxes)], capture_output=True, text=True, cwd=lab.ROOT, env=env)
     if result.returncode:
         raise SystemExit('chunk_dump failed: ' + result.stderr[-2000:])
     rows = {}  # chunk -> the heights the boxes over it need
@@ -104,15 +141,24 @@ def oracle_blocks(start):
     return mod, base
 
 
-def inside(box, p):
-    return all(box[i] <= p[i] <= box[i + 3] for i in range(3))
+REGIONS = ('pieces', 'around')
 
 
 def compare(start, vanilla, modded):
-    """Compared positions and the mismatches, as (no-mod, expected, Horizon) -> count."""
+    """Per region (inside a piece's box, or around them: terrain adaptation and decoration), the compared
+    positions and the mismatches, as (no-mod, expected, Horizon) -> count."""
     mod, base = oracle_blocks(start)
-    compared, mismatches = 0, Counter()
     x0, y0, z0, x1, y1, z1 = start['diff_box']
+    width, depth = x1 - x0 + 1, z1 - z0 + 1
+    in_piece = bytearray(width * depth * (y1 - y0 + 1))  # (y, z, x) over the diff box
+    for bx0, by0, bz0, bx1, by1, bz1 in (p['BB'] for p in start['pieces']):
+        for y in range(max(by0, y0), min(by1, y1) + 1):
+            for z in range(max(bz0, z0), min(bz1, z1) + 1):
+                row = ((y - y0) * depth + z - z0) * width - x0
+                lo, hi = max(bx0, x0), min(bx1, x1)
+                if lo <= hi:
+                    in_piece[row + lo:row + hi + 1] = b'\x01' * (hi - lo + 1)
+    compared, mismatches = Counter(), {region: Counter() for region in REGIONS}
     for y in range(y0, y1 + 1):
         for z in range(z0, z1 + 1):
             for x in range(x0, x1 + 1):
@@ -125,28 +171,30 @@ def compare(start, vanilla, modded):
                     expected = mod[p]
                 else:
                     expected = vanilla[p]  # the oracle saw no change
-                compared += 1
+                region = REGIONS[0] if in_piece[((y - y0) * depth + z - z0) * width + x - x0] else REGIONS[1]
+                compared[region] += 1
                 if modded[p] != expected:
-                    mismatches[(base.get(p, vanilla[p]), expected, modded[p])] += 1
+                    mismatches[region][(base.get(p, vanilla[p]), expected, modded[p])] += 1
     return compared, mismatches
 
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument('--profile', default='betterdungeons', choices=[p for p, v in layout.PROFILES.items() if v['carry']])
+    parser.add_argument('--profile', default='betterdungeons', choices=sorted(PROFILES))
     parser.add_argument('--filter', default='', help='only structure ids matching this regex')
     parser.add_argument('--limit', type=int, default=8, help='mismatch classes shown per structure')
     args = parser.parse_args()
-    profile = layout.PROFILES[args.profile]
+    profile = PROFILES[args.profile]
     results = sorted((layout.ORACLE / args.profile).glob('seed-*.json.gz'))
-    missing = [jar for jar in profile['mods'].values() if not (layout.JARS / jar).exists()]
+    missing = [jar for jar in profile['mods'].values() if not layout.jar_path(jar).exists()]
     if not results or missing:
         print(f'SKIP: oracle results or mod jars missing under {layout.ORACLE} (see test_structure_layout_parity.py)')
         return 0
     resources = layout.overlay(args.profile, layout.carry(args.profile, profile['mods'], profile['carry']))
     binary = layout.probe_binary()
     names = state_names(lab.RESOURCES)
-    totals = defaultdict(lambda: [0, 0, Counter()])  # structure -> [starts, compared, mismatches]
+    # structure -> [starts, compared by region, mismatches by region]
+    totals = defaultdict(lambda: [0, Counter(), {region: Counter() for region in REGIONS}])
     for path in results:
         oracle = json.load(gzip.open(path))
         seed = oracle['seed']
@@ -156,23 +204,32 @@ def main():
             boxes = [s['diff_box'] for s in here]
             dim = dimension.removeprefix('minecraft:')
             vanilla = generate(binary, lab.RESOURCES, seed, dim, boxes, names)
-            modded = generate(binary, resources, seed, dim, boxes, names)
+            modded = generate(binary, resources, seed, dim, boxes, names, saved_starts(here))
             for start in here:
                 compared, mismatches = compare(start, vanilla, modded)
                 total = totals[start['id']]
                 total[0] += 1
-                total[1] += compared
-                total[2].update(mismatches)
+                total[1].update(compared)
+                for region in REGIONS:
+                    total[2][region].update(mismatches[region])
     failed = False
+    report = {}
     for structure, (starts, compared, mismatches) in sorted(totals.items()):
-        wrong = sum(mismatches.values())
+        wrong = {region: sum(mismatches[region].values()) for region in REGIONS}
         reason = next((r for pattern, r in KNOWN.get(args.profile, {}).items() if re.search(pattern, structure)), None)
-        verdict = 'ok   ' if not wrong else 'known' if reason else 'FAIL '
+        verdict = 'ok   ' if not any(wrong.values()) else 'known' if reason else 'FAIL '
         failed |= verdict == 'FAIL '
-        print(f'{verdict} {structure}: {starts} starts, {compared - wrong} of {compared} positions match'
-              + (f' ({reason})' if wrong and reason else ''))
-        for (base, expected, got), n in mismatches.most_common(args.limit):
-            print(f'        {n:6}  no-mod {base}  expected {expected}  Horizon {got}')
+        counts = ', '.join(f'{compared[r] - wrong[r]} of {compared[r]} {r}' for r in REGIONS)
+        print(f'{verdict} {structure}: {starts} starts, positions matching: {counts}'
+              + (f' ({reason})' if any(wrong.values()) and reason else ''))
+        for region in REGIONS:
+            for (base, expected, got), n in mismatches[region].most_common(args.limit):
+                print(f'        {region:6} {n:6}  no-mod {base}  expected {expected}  Horizon {got}')
+        report[structure] = {'starts': starts, 'compared': compared,
+                             'mismatches': {r: [[*k, n] for k, n in mismatches[r].most_common()] for r in REGIONS}}
+    # Every mismatch class, for a closer look than the summary.
+    out = lab.LOCAL / 'structure-layout' / args.profile / 'blocks-report.json'
+    out.write_text(json.dumps(report, indent=1))
     return 1 if failed else 0
 
 
diff --git a/tools/test_structure_layout_parity.py b/tools/test_structure_layout_parity.py
index d16002424..7af8026fb 100644
--- a/tools/test_structure_layout_parity.py
+++ b/tools/test_structure_layout_parity.py
@@ -42,6 +42,12 @@ except ImportError:
 
 ORACLE = Path(os.environ.get('HORIZON_STRUCTURE_ORACLE', lab.LOCAL / 'structure-oracle'))
 JARS = Path(os.environ.get('HORIZON_STRUCTURE_JARS', ORACLE / 'jars'))
+# Jars of a modpack's mods the oracle cache does not hold (Lithostitched, CTOV): a pack's jar folder.
+PACK_JARS = Path(os.environ.get('HORIZON_STRUCTURE_PACK_JARS', ORACLE / 'pack-jars'))
+
+
+def jar_path(jar):
+    return JARS / jar if (JARS / jar).exists() else PACK_JARS / jar
 # Per profile: which saved pieces are expected, the mods in the pack (id: jar), those carried, and the
 # structures compared (a regex; None: every start that has the pieces).
 PROFILES = {
@@ -102,7 +108,7 @@ def carry(profile, mods, carried):
     work.mkdir(parents=True)
     records = [{'key': key, 'name': key, 'version': '', 'path': jar, 'tier': 'data', 'confidence': 'known',
                 'class': 'content' if key in carried else 'library', 'source': 'file', 'license': '',
-                'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': str(JARS / jar),
+                'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': str(jar_path(jar)),
                 'info': {'mod_id': key, 'name': key, 'version': '', 'license': '', 'depends': [],
                          'census': dict.fromkeys(CENSUS, 0)}}
                for key, jar in mods.items()]
@@ -124,6 +130,7 @@ def overlay(profile, data_dirs):
     (root / 'facts.json').symlink_to(lab.RESOURCES / 'facts.json')
     source = lab.RESOURCES / 'worldgen'
     merged = {name: json.loads((source / f'{name}.json').read_text()) for name in [*BUNDLES.values(), 'biome_tags']}
+    additions = []
     for entry in source.iterdir():
         if entry.name != 'structure' and entry.stem not in merged:
             (worldgen / entry.name).symlink_to(entry)
@@ -140,13 +147,27 @@ def overlay(profile, data_dirs):
                 target.parent.mkdir(parents=True, exist_ok=True)
                 target.symlink_to(path)
             elif path.suffix == '.json' and kind == 'worldgen' and parts[2] in BUNDLES:
-                merged[BUNDLES[parts[2]]][f'{namespace}:' + '/'.join(parts[3:])[:-5]] = path.read_text()
+                text = path.read_text()
+                if 'horizon:add_to' in text:
+                    additions.append((BUNDLES[parts[2]], json.loads(text)))
+                else:
+                    merged[BUNDLES[parts[2]]][f'{namespace}:' + '/'.join(parts[3:])[:-5]] = text
             elif path.suffix == '.json' and parts[1:4] == ('tags', 'worldgen', 'biome'):
                 tag = f'{namespace}:' + '/'.join(parts[4:])[:-5]
                 value = json.loads(path.read_text())
                 if tag in merged['biome_tags'] and not value.get('replace'):
                     value['values'] = json.loads(merged['biome_tags'][tag])['values'] + value['values']
                 merged['biome_tags'][tag] = json.dumps(value)
+    # A carried file with `horizon:add_to` adds its entries to other sets or pools, as the game's
+    # mod_content.rs merges them.
+    for bundle, addition in additions:
+        targets = addition['horizon:add_to']
+        key = 'structures' if bundle == 'structure_sets' else 'elements'
+        for target in [targets] if isinstance(targets, str) else targets:
+            if target in merged[bundle]:
+                value = json.loads(merged[bundle][target])
+                value[key] = value.get(key, []) + addition.get(key, [])
+                merged[bundle][target] = json.dumps(value)
     for name, bundle in merged.items():
         (worldgen / f'{name}.json').write_text(json.dumps(bundle))
     return root
@@ -199,7 +220,7 @@ def main():
         print(f'SKIP: no oracle results in {ORACLE / args.profile} (see this file\'s docstring)')
         return 0
     profile = PROFILES[args.profile]
-    missing = [jar for jar in profile['mods'].values() if not (JARS / jar).exists()]
+    missing = [jar for jar in profile['mods'].values() if not jar_path(jar).exists()]
     if missing:
         print(f'SKIP: mod jars not in {JARS}: {", ".join(missing)}')
         return 0

From b5a791170d1e1bec47f2508419d2918c72f891f1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 09:51:55 +0100
Subject: [PATCH 037/270] Shader packs, clean room 30: the loader's alpha test

Gbuffers programs get the loader's alpha test on output 0 when they
write `gl_FragData`/`gl_FragColor` (spec 3.2 `alphaTest.<program>`;
with `out` variables the pack tests alpha itself). `GbuffersInputs`
carries the geometry's default, none for terrain, water and the sky so
far; `alphaTest.<program>` replaces it for that program (`off`, or a GL
comparison and a reference).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_atlas.rs |  1 +
 crates/horizon-client/src/gfx/pack_sky.rs   |  2 +
 crates/horizon-shaders/src/lib.rs           |  2 +-
 crates/horizon-shaders/src/post.rs          |  9 +-
 crates/horizon-shaders/src/translate/mod.rs | 97 ++++++++++++++++++++-
 5 files changed, 108 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_atlas.rs b/crates/horizon-client/src/gfx/pack_atlas.rs
index e1727f1fe..42a2abee1 100644
--- a/crates/horizon-client/src/gfx/pack_atlas.rs
+++ b/crates/horizon-client/src/gfx/pack_atlas.rs
@@ -214,6 +214,7 @@ impl PackAtlas {
                 .map(|&(n, v)| (n.to_owned(), v.to_owned()))
                 .collect(),
             after: String::new(),
+            alpha_test: None,
         }
     }
 }
diff --git a/crates/horizon-client/src/gfx/pack_sky.rs b/crates/horizon-client/src/gfx/pack_sky.rs
index 007fdc034..694f3096f 100644
--- a/crates/horizon-client/src/gfx/pack_sky.rs
+++ b/crates/horizon-client/src/gfx/pack_sky.rs
@@ -96,6 +96,7 @@ pub fn inputs() -> horizon_shaders::GbuffersInputs {
         ],
         // At the far plane: the sky shows only where nothing else drew, and it writes no depth.
         after: "    gl_Position.z = gl_Position.w;\n".into(),
+        alpha_test: None,
     }
 }
 
@@ -120,6 +121,7 @@ pub fn celestial_inputs() -> horizon_shaders::GbuffersInputs {
             ("vaNormal".into(), "hz_Normal".into()),
         ],
         after: "    gl_Position.z = gl_Position.w;\n".into(),
+        alpha_test: None,
     }
 }
 
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index 8684be867..426ee5b35 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -44,6 +44,6 @@ pub use post::{
 pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
 pub use translate::{
-    DRAW_UNIFORMS, Error, GbuffersInputs, Interface, Program, Sampler, Target, Uniform,
+    AlphaTest, DRAW_UNIFORMS, Error, GbuffersInputs, Interface, Program, Sampler, Target, Uniform,
     translate_composite, translate_gbuffers,
 };
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 944cf10b8..7b83b98b5 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -226,8 +226,15 @@ pub fn load_post(
     }
     let mut gbuffers = |names: &[&str], group, inputs: &GbuffersInputs| {
         names.iter().find_map(|name| {
+            // `alphaTest.<program>` replaces the geometry's default test (OQ-23).
+            let key = properties.get(&format!("alphaTest.{name}"));
+            let test = key.and_then(|v| crate::AlphaTest::parse(v.trim()));
+            let mut inputs = inputs.clone();
+            if let Some(test) = test {
+                inputs.alpha_test = test;
+            }
             loader.load(name.to_string(), group, |v, f| {
-                translate_gbuffers(v, f, Target::Buffers, inputs)
+                translate_gbuffers(v, f, Target::Buffers, &inputs)
             })
         })
     };
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 96872da1d..5d0bfee3b 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -111,6 +111,41 @@ pub struct GbuffersInputs {
     pub attributes: Vec<(String, String)>,
     /// GLSL statements run last in `main`, with `gl_Position` in wgpu's clip space.
     pub after: String,
+    /// The alpha test applied to output 0 (`gl_FragData[0]`, `gl_FragColor`), the loader's
+    /// (3.2 `alphaTest.<program>`): `None` keeps every fragment.
+    pub alpha_test: Option<AlphaTest>,
+}
+
+/// A fragment stays when its output 0's alpha compares to `reference` as `op` says (a GLSL
+/// comparison operator, `true` for GL's `ALWAYS`, `false` for `NEVER`).
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct AlphaTest {
+    pub op: &'static str,
+    pub reference: f32,
+}
+
+impl AlphaTest {
+    /// `alphaTest.<program>`'s value: `off`, or a GL comparison and a reference.
+    pub fn parse(value: &str) -> Option<Option<Self>> {
+        let mut words = value.split_whitespace();
+        let func = words.next()?;
+        if func == "off" {
+            return Some(None);
+        }
+        let op = match func.trim_start_matches("GL_") {
+            "NEVER" => "false",
+            "LESS" => "<",
+            "EQUAL" => "==",
+            "LEQUAL" => "<=",
+            "GREATER" => ">",
+            "NOTEQUAL" => "!=",
+            "GEQUAL" => ">=",
+            "ALWAYS" => return Some(None),
+            _ => return None,
+        };
+        let reference = words.next()?.parse().ok()?;
+        Some(Some(Self { op, reference }))
+    }
 }
 
 /// Translates a composite-style program (`composite`, `deferred`, `final`...).
@@ -343,7 +378,23 @@ fn translate(
     for name in &f.inits {
         writeln!(fragment_main, "    {name} = hz_init_{name}();").unwrap();
     }
-    fragment_main.push_str("    hz_main();\n}\n");
+    fragment_main.push_str("    hz_main();\n");
+    // With `out` variables the pack tests alpha itself.
+    if let Some(t) = gbuffers.and_then(|g| g.alpha_test)
+        && f.outputs.contains(&0)
+        && !f.frag_outs.iter().any(|(n, _)| *n == 0)
+    {
+        match t.op {
+            "false" => fragment_main.push_str("    discard;\n"),
+            op => writeln!(
+                fragment_main,
+                "    if (!(hz_out0.a {op} {:?})) {{ discard; }}",
+                t.reference
+            )
+            .unwrap(),
+        }
+    }
+    fragment_main.push_str("}\n");
 
     let v_text = format!(
         "{}{}{vertex_main}",
@@ -651,6 +702,50 @@ mod tests {
         }
     }
 
+    #[test]
+    fn the_alpha_test_discards_below_its_reference() {
+        assert_eq!(
+            AlphaTest::parse("GREATER 0.1"),
+            Some(Some(AlphaTest {
+                op: ">",
+                reference: 0.1
+            }))
+        );
+        assert_eq!(AlphaTest::parse("off"), Some(None));
+        assert_eq!(AlphaTest::parse("GL_ALWAYS 0"), Some(None));
+        assert_eq!(AlphaTest::parse("SOMETIMES 0.5"), None);
+        let vsh = "#version 120\nvoid main() { gl_Position = ftransform(); }\n";
+        let legacy = "#version 120\nvoid main() { gl_FragData[0] = vec4(0.5); }\n";
+        let outs =
+            "#version 330\nlayout(location = 0) out vec4 c;\nvoid main() { c = vec4(0.5); }\n";
+        for (fsh, kills) in [(legacy, true), (outs, false)] {
+            let files = [
+                ("shaders/gbuffers_entities.vsh", vsh),
+                ("shaders/gbuffers_entities.fsh", fsh),
+            ];
+            let pack = Pack::from_zip_bytes("P.zip", zip(&files)).unwrap();
+            let m = Macros::standard();
+            let inputs = GbuffersInputs {
+                body: "    hz_Vertex = vec4(0.0, 0.0, 0.0, 1.0);\n".into(),
+                alpha_test: AlphaTest::parse("GREATER 0.1").unwrap(),
+                ..Default::default()
+            };
+            let p = translate_gbuffers(
+                &preprocess(&pack, "gbuffers_entities.vsh", &m),
+                &preprocess(&pack, "gbuffers_entities.fsh", &m),
+                Target::Buffers,
+                &inputs,
+            )
+            .unwrap_or_else(|e| panic!("{e:?}"));
+            let functions = p.fragment.functions.iter().map(|(_, f)| f);
+            let kill = functions
+                .chain([&p.fragment.entry_points[0].function])
+                .any(|f| format!("{:?}", f.body).contains("Kill"));
+            // With `out` variables the pack tests alpha itself.
+            assert_eq!(kill, kills, "{fsh}");
+        }
+    }
+
     #[test]
     fn gbuffers_programs_read_the_games_vertices() {
         let vsh = "#version 120\nattribute vec4 mc_Entity;\nattribute vec2 mc_midTexCoord;\nvarying vec2 uv;\nvarying vec2 light;\n\

From ab289a2cf3f84fac470eb146e140c2fa7dc55f67 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 09:51:55 +0100
Subject: [PATCH 038/270] Shader packs, clean room 31: entities and block
 entities

A shader pack now draws entities with `gbuffers_entities` and block
entities with `gbuffers_block` (or their fallbacks, spec 2.3), after
terrain. Each run of the entity spans is one draw with its own
`entityId` or `blockEntityId` and `entityColor` (the hurt red, the
white flashes) in a per-draw slot. Horizon still draws everything else
(particles, cracks, beams, name tags, shadows, End portals, clouds) in
its own single entity draw, without the runs the pack drew.

The entity vertices are read again at set 1, so the pack gets the face
normal where a vertex has none (block entities), `at_tangent` along the
texture's u and `mc_midTexCoord`, as for terrain.

Entities and block entities draw without blending, with the loader's
alpha test at GREATER 0.1, as cutout (OQ-23); name tags and shadows,
which blend, stay Horizon's for now.

`HORIZON_SHADER_PACK_TIMING` no longer panics when a pass skips a whole
report window (no entities in view).

Without a shader pack nothing changes: the split only runs while a pack
draws entities.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |   8 +-
 crates/horizon-client/src/gfx.rs              |  30 +-
 .../horizon-client/src/gfx/pack_entities.rs   | 400 ++++++++++++++++++
 crates/horizon-client/src/gfx/pack_post.rs    | 129 +++++-
 crates/horizon-client/src/gfx/pack_timing.rs  |   3 +-
 crates/horizon-shaders/src/post.rs            |  60 ++-
 crates/horizon-shaders/tests/real_packs.rs    |   7 +-
 7 files changed, 620 insertions(+), 17 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_entities.rs

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f43593360..180d38ab0 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -6784,11 +6784,12 @@ impl Game<'_> {
         self.fangs_geometry(camera, alpha, &mut out);
         let mut see_through = std::mem::take(&mut self.see_through_vertices);
         see_through.clear();
-        self.mark_entity(out.len(), "minecraft:name_tag");
+        // Name tags and shadows blend: Horizon keeps drawing them until the pack's entity
+        // programs draw translucent parts (`minecraft:name_tag`, `minecraft:entity_shadow`).
+        self.mark_stage(out.len(), "NONE");
         self.name_tag_geometry(camera, alpha, &mut out, &mut see_through);
         self.see_through_vertices = see_through;
         // Entity shadows (EntityRenderer.extractShadow).
-        self.mark_entity(out.len(), "minecraft:entity_shadow");
         if let Some(sprite) = self.gui.atlas.sprites.get("misc/shadow").copied() {
             let ambient = if self.dim == Dim::Nether { 0.1 } else { 0.0 };
             let darken = self.sky_darken();
@@ -7016,7 +7017,8 @@ impl Game<'_> {
         self.boat_geometry(camera, alpha, &mut out);
         self.mark_entity(out.len(), "minecraft:minecart");
         self.cart_geometry(camera, alpha, &mut out);
-        self.mark_stage(out.len(), "BLOCK_ENTITIES");
+        // Beams: `gbuffers_beaconbeam`, not a block entity's program (5.4 has no stage for them).
+        self.mark_stage(out.len(), "NONE");
         self.beacon_geometry(camera, alpha, &mut out);
         self.mark_entity(out.len(), "minecraft:fishing_bobber");
         self.fishing_geometry(camera, alpha, &mut out);
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 4351fd85d..d354b9bba 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -70,6 +70,7 @@ mod lod;
 mod occlusion;
 mod pack_atlas;
 pub mod pack_draw;
+mod pack_entities;
 mod pack_post;
 mod pack_sky;
 mod pack_timing;
@@ -487,6 +488,8 @@ pub struct Renderer {
     world_post: world_post::Post,
     /// The shader pack's post-processing, and the dimension (legacy id) it was loaded for.
     pack_post: Option<(i32, Option<pack_post::PackPost>)>,
+    /// The entity vertices Horizon draws itself while a shader pack draws the others.
+    pack_entity_rest: Vec<Vertex>,
     /// The block sprites as one atlas, while a shader pack is loaded.
     pack_atlas: Option<pack_atlas::PackAtlas>,
     /// The pack's terrain program reads flat draws' vertices (`pack_terrain_inputs`).
@@ -2346,6 +2349,7 @@ impl Renderer {
             occlusion: occlusion::Occlusion::new(crate::chunk::MIN_Y, crate::chunk::HEIGHT / 16),
             world_post,
             pack_post: None,
+            pack_entity_rest: Vec::new(),
             pack_atlas: None,
             pack_terrain_flat: false,
             hud,
@@ -2832,6 +2836,7 @@ impl Renderer {
             terrain: self.pack_terrain_inputs(),
             sky: Some(pack_sky::inputs()),
             celestial: Some(pack_sky::celestial_inputs()),
+            entities: Some(pack_entities::inputs()),
         }
     }
 
@@ -3509,18 +3514,31 @@ impl Renderer {
             self.uploads
                 .buffer(&mut encoder, &self.outline, 0, bytemuck::cast_slice(&lines));
         }
+        // While a shader pack draws entities, the runs of `entity_spans` its programs draw are
+        // left out of Horizon's own entity draw.
+        let mut entities = frame.entities;
+        if !frame.title
+            && let Some((_, Some(post))) = &mut self.pack_post
+            && post.has_entities()
+        {
+            post.prepare_entities(
+                &self.device,
+                &self.queue,
+                frame.entities,
+                frame.entity_spans,
+                &mut self.pack_entity_rest,
+            );
+            entities = &self.pack_entity_rest;
+        }
         let [
             entity_quads,
             crumbling_quads,
             translucent_crumbling_quads,
             water_mask_quads,
             shadow_quads,
-        ] = self.entity_batch.update(
-            frame.entities,
-            frame.additive,
-            frame.hand,
-            frame.see_through,
-        );
+        ] = self
+            .entity_batch
+            .update(entities, frame.additive, frame.hand, frame.see_through);
         let weather_quads = frame.weather.len() as u32 / 4;
         let world_quads = entity_quads
             + crumbling_quads
diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
new file mode 100644
index 000000000..b30aa4fdb
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -0,0 +1,400 @@
+//! Entities and block entities drawn by a shader pack's `gbuffers_entities` and `gbuffers_block`
+//! (spec 2.3, 5.3, 5.4): the runs of `Frame::entities` the game marked (`EntitySpan`), each its
+//! own draw with its `entityId` or `blockEntityId` and `entityColor` in a per-draw slot of
+//! `HzDraw` (set 2). Horizon draws whatever the pack does not.
+
+use std::ops::Range;
+
+use horizon_shaders::render_stage;
+
+use super::Vertex;
+use super::pack_draw::EntitySpan;
+
+/// `HzDraw`'s size (pack_draw.rs).
+const SLOT: u64 = 32;
+
+const ATTRIBUTES: [wgpu::VertexAttribute; 6] = wgpu::vertex_attr_array![
+    0 => Float32x3, 1 => Float32x2, 2 => Uint32, 3 => Unorm8x4, 4 => Uint8x4, 5 => Snorm8x4
+];
+
+/// The entity vertex: Horizon's own (`Vertex`).
+pub fn buffers() -> [Option<wgpu::VertexBufferLayout<'static>>; 1] {
+    [Some(wgpu::VertexBufferLayout {
+        array_stride: std::mem::size_of::<Vertex>() as u64,
+        step_mode: wgpu::VertexStepMode::Vertex,
+        attributes: &ATTRIBUTES,
+    })]
+}
+
+/// What `gbuffers_entities` and `gbuffers_block` read from an entity vertex: camera-relative
+/// position, the shared atlas's UV, colour, light (block, sky in 16ths) and the world-oriented
+/// normal. The quad's corners, read from the same vertices at set 1, give the face normal where
+/// the vertex has none (block entities) and `at_tangent` along the texture's u, as for terrain.
+pub fn inputs() -> horizon_shaders::GbuffersInputs {
+    let declarations = "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in vec2 hz_v_uv;\n\
+         layout(location = 2) in uint hz_v_overlay;\nlayout(location = 3) in vec4 hz_v_color;\n\
+         layout(location = 4) in uvec4 hz_v_light;\nlayout(location = 5) in vec4 hz_v_normal;\n\
+         layout(set = 1, binding = 0) readonly buffer HzEntityVertices { uint hz_entity_vertices[]; };\n\
+         vec4 hz_tangent; vec2 hz_mid;\n"
+        .to_owned();
+    let words = std::mem::size_of::<Vertex>() / 4;
+    let corner = |k: usize, field: &str| {
+        let at = |o: usize| format!("hz_entity_vertices[hz_q + {}u]", k * words + o);
+        match field {
+            "pos" => format!("uintBitsToFloat(uvec3({}, {}, {}))", at(0), at(1), at(2)),
+            _ => format!("uintBitsToFloat(uvec2({}, {}))", at(3), at(4)),
+        }
+    };
+    let body = format!(
+        "    uint hz_q = (uint(gl_VertexIndex) & ~3u) * {words}u;\n    \
+         vec3 hz_e1 = {p1} - {p0};\n    \
+         vec3 hz_e2 = {p2} - {p0};\n    \
+         vec2 hz_t0 = {t0};\n    \
+         vec2 hz_d1 = {t1} - hz_t0;\n    \
+         vec2 hz_d2 = {t2} - hz_t0;\n    \
+         hz_mid = (hz_t0 + {t2}) * 0.5;\n    \
+         vec3 hz_n = cross(hz_e1, hz_e2);\n    \
+         hz_Normal = dot(hz_v_normal.xyz, hz_v_normal.xyz) > 0.01 ? normalize(hz_v_normal.xyz)\n        \
+             : dot(hz_n, hz_n) > 1e-12 ? normalize(hz_n) : vec3(0.0, 1.0, 0.0);\n    \
+         hz_tangent = vec4(1.0, 0.0, 0.0, 1.0);\n    \
+         float hz_r = hz_d1.x * hz_d2.y - hz_d2.x * hz_d1.y;\n    \
+         vec3 hz_t = (hz_e1 * hz_d2.y - hz_e2 * hz_d1.y) * sign(hz_r);\n    \
+         vec3 hz_b = (hz_e2 * hz_d1.x - hz_e1 * hz_d2.x) * sign(hz_r);\n    \
+         hz_t -= hz_Normal * dot(hz_Normal, hz_t);\n    \
+         if (dot(hz_t, hz_t) > 1e-12) {{\n        \
+             hz_t = normalize(hz_t);\n        \
+             hz_tangent = vec4(hz_t, dot(cross(hz_t, hz_Normal), hz_b) < 0.0 ? -1.0 : 1.0);\n    \
+         }}\n    \
+         hz_Vertex = vec4(hz_v_pos, 1.0);\n    \
+         hz_MultiTexCoord0 = vec4(hz_v_uv, 0.0, 1.0);\n    \
+         hz_MultiTexCoord1 = vec4(float(hz_v_light.y), float(hz_v_light.x), 0.0, 1.0);\n    \
+         hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+         hz_Color = hz_v_color;\n",
+        p0 = corner(0, "pos"),
+        p1 = corner(1, "pos"),
+        p2 = corner(2, "pos"),
+        t0 = corner(0, "uv"),
+        t1 = corner(1, "uv"),
+        t2 = corner(2, "uv"),
+    );
+    let attributes = [
+        ("at_tangent", "hz_tangent"),
+        ("mc_midTexCoord", "vec4(hz_mid, 0.0, 1.0)"),
+        ("vaPosition", "hz_Vertex.xyz"),
+        ("vaUV0", "hz_v_uv"),
+        ("vaUV1", "ivec2(0, 10)"),
+        ("vaUV2", "ivec2(hz_MultiTexCoord1.xy)"),
+        ("vaColor", "hz_Color"),
+        ("vaNormal", "hz_Normal"),
+    ];
+    horizon_shaders::GbuffersInputs {
+        declarations,
+        body,
+        attributes: attributes
+            .iter()
+            .map(|&(n, v)| (n.to_owned(), v.to_owned()))
+            .collect(),
+        after: String::new(),
+        // Cutout, as vanilla's entity types mostly are (OQ-23): the loader's test at 0.1.
+        alpha_test: Some(horizon_shaders::AlphaTest {
+            op: ">",
+            reference: 0.1,
+        }),
+    }
+}
+
+/// `entityColor` for a run whose first quad carries overlay code `overlay`: the hurt red or a
+/// white flash, its alpha how much of that colour shows over the entity (vanilla mixes the
+/// overlay texel's colour in by one minus the texel's alpha).
+pub fn entity_color(overlay: u32) -> [f32; 4] {
+    let [r, g, b, a] = crate::overlay::HURT_TEXEL.map(|v| f32::from(v) / 255.0);
+    let white = |u: u32| {
+        let a = f32::from(crate::overlay::white_alpha(u)) / 255.0;
+        [1.0, 1.0, 1.0, 1.0 - a]
+    };
+    match overlay {
+        1 | 8 => [r, g, b, 1.0 - a],
+        5 => white(15),
+        16..32 => white(overlay - crate::overlay::WHITE),
+        _ => [0.0; 4],
+    }
+}
+
+/// One draw: its quads in `PackEntities`' buffer, its program and its slot of `HzDraw`.
+pub(super) struct Draw {
+    /// The first vertex.
+    pub base: u32,
+    pub quads: u32,
+    /// `gbuffers_block` (or its fallback) draws it, not `gbuffers_entities`.
+    pub block: bool,
+    pub slot: u32,
+}
+
+/// The vertices and per-draw uniforms of the runs a pack draws, rebuilt each frame.
+pub(super) struct PackEntities {
+    vertices: wgpu::Buffer,
+    /// Set 1: the vertices again, for the quads' corners.
+    pub table: wgpu::BindGroupLayout,
+    pub table_group: wgpu::BindGroup,
+    slots: wgpu::Buffer,
+    pub group: wgpu::BindGroup,
+    stride: u64,
+    /// Two triangles per quad, for `quads` quads.
+    pub indices: wgpu::Buffer,
+    quads: u32,
+    scratch: Vec<Vertex>,
+    uniforms: Vec<u8>,
+    pub draws: Vec<Draw>,
+}
+
+impl PackEntities {
+    pub fn new(device: &wgpu::Device, layout: &wgpu::BindGroupLayout) -> Self {
+        let stride = SLOT.max(u64::from(
+            device.limits().min_uniform_buffer_offset_alignment,
+        ));
+        let table = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("Shader pack entity vertices"),
+            entries: &[wgpu::BindGroupLayoutEntry {
+                binding: 0,
+                visibility: wgpu::ShaderStages::VERTEX,
+                ty: wgpu::BindingType::Buffer {
+                    ty: wgpu::BufferBindingType::Storage { read_only: true },
+                    has_dynamic_offset: false,
+                    min_binding_size: None,
+                },
+                count: None,
+            }],
+        });
+        let (vertices, table_group) = Self::vertex_buffer(device, &table, 4096);
+        let (slots, group) = Self::slot_buffer(device, layout, 64, stride);
+        Self {
+            vertices,
+            table,
+            table_group,
+            slots,
+            group,
+            stride,
+            indices: quad_indices(device, 1024),
+            quads: 1024,
+            scratch: Vec::new(),
+            uniforms: Vec::new(),
+            draws: Vec::new(),
+        }
+    }
+
+    fn vertex_buffer(
+        device: &wgpu::Device,
+        table: &wgpu::BindGroupLayout,
+        vertices: u64,
+    ) -> (wgpu::Buffer, wgpu::BindGroup) {
+        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack entity vertices"),
+            size: vertices * std::mem::size_of::<Vertex>() as u64,
+            usage: wgpu::BufferUsages::VERTEX
+                | wgpu::BufferUsages::STORAGE
+                | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+            label: Some("Shader pack entity vertices"),
+            layout: table,
+            entries: &[wgpu::BindGroupEntry {
+                binding: 0,
+                resource: buffer.as_entire_binding(),
+            }],
+        });
+        (buffer, group)
+    }
+
+    fn slot_buffer(
+        device: &wgpu::Device,
+        layout: &wgpu::BindGroupLayout,
+        slots: u64,
+        stride: u64,
+    ) -> (wgpu::Buffer, wgpu::BindGroup) {
+        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack entity draws"),
+            size: slots * stride,
+            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+            label: Some("Shader pack entity draws"),
+            layout,
+            entries: &[wgpu::BindGroupEntry {
+                binding: 0,
+                resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
+                    buffer: &buffer,
+                    offset: 0,
+                    size: wgpu::BufferSize::new(SLOT),
+                }),
+            }],
+        });
+        (buffer, group)
+    }
+
+    pub fn vertices(&self) -> wgpu::BufferSlice<'_> {
+        self.vertices.slice(..)
+    }
+
+    /// The dynamic offset of draw slot `slot`.
+    pub fn offset(&self, slot: u32) -> u32 {
+        (u64::from(slot) * self.stride) as u32
+    }
+
+    /// Splits `entities` between the pack, which draws the runs of `spans` its programs cover
+    /// (`drawn`: whether it has `gbuffers_entities`, `gbuffers_block` or their fallbacks), and
+    /// Horizon, which draws the rest (`rest`). Uploads the pack's part.
+    #[allow(clippy::too_many_arguments)]
+    pub fn prepare(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        layout: &wgpu::BindGroupLayout,
+        entities: &[Vertex],
+        spans: &[EntitySpan],
+        drawn: [bool; 2],
+        rest: &mut Vec<Vertex>,
+    ) {
+        self.draws.clear();
+        self.scratch.clear();
+        self.uniforms.clear();
+        rest.clear();
+        let first = spans.first().map_or(entities.len(), |s| s.start as usize);
+        rest.extend_from_slice(&entities[..first.min(entities.len())]);
+        for (span, range) in runs(entities.len(), spans) {
+            let run = &entities[range];
+            let Some(block) = drawn_by_pack(span.stage, drawn).filter(|_| plain(run)) else {
+                rest.extend_from_slice(run);
+                continue;
+            };
+            if run.is_empty() {
+                continue;
+            }
+            let start = self.scratch.len() as u32;
+            self.scratch.extend_from_slice(run);
+            let (entity_id, block_id) = if block { (0, span.id) } else { (span.id, 0) };
+            let mut bytes = [0u8; SLOT as usize];
+            bytes[0..4].copy_from_slice(&(span.stage as i32).to_le_bytes());
+            bytes[4..8].copy_from_slice(&entity_id.to_le_bytes());
+            bytes[8..12].copy_from_slice(&block_id.to_le_bytes());
+            for (i, c) in entity_color(run[0].layer).iter().enumerate() {
+                bytes[16 + 4 * i..20 + 4 * i].copy_from_slice(&c.to_le_bytes());
+            }
+            self.uniforms.extend_from_slice(&bytes);
+            self.uniforms
+                .resize(self.uniforms.len() + (self.stride - SLOT) as usize, 0);
+            self.draws.push(Draw {
+                base: start,
+                quads: run.len() as u32 / 4,
+                block,
+                slot: self.draws.len() as u32,
+            });
+        }
+        if self.draws.is_empty() {
+            return;
+        }
+        let vertex_size = std::mem::size_of::<Vertex>() as u64;
+        let (need_vertices, need_slots) = (self.scratch.len() as u64, self.draws.len() as u64);
+        let have_vertices = self.vertices.size() / vertex_size;
+        let have_slots = self.slots.size() / self.stride;
+        if need_vertices > have_vertices {
+            (self.vertices, self.table_group) =
+                Self::vertex_buffer(device, &self.table, need_vertices.next_power_of_two());
+        }
+        if need_slots > have_slots {
+            (self.slots, self.group) =
+                Self::slot_buffer(device, layout, need_slots.next_power_of_two(), self.stride);
+        }
+        let quads = self.draws.iter().map(|d| d.quads).max().unwrap_or(0);
+        if quads > self.quads {
+            self.quads = quads.next_power_of_two();
+            self.indices = quad_indices(device, self.quads);
+        }
+        queue.write_buffer(&self.vertices, 0, bytemuck::cast_slice(&self.scratch));
+        queue.write_buffer(&self.slots, 0, &self.uniforms);
+    }
+}
+
+/// Two triangles for each of `quads` quads, from vertex 0.
+fn quad_indices(device: &wgpu::Device, quads: u32) -> wgpu::Buffer {
+    let indices: Vec<u32> = (0..quads)
+        .flat_map(|q| [0, 1, 2, 0, 2, 3].map(|i| q * 4 + i))
+        .collect();
+    wgpu::util::DeviceExt::create_buffer_init(
+        device,
+        &wgpu::util::BufferInitDescriptor {
+            label: Some("Shader pack entity indices"),
+            contents: bytemuck::cast_slice(&indices),
+            usage: wgpu::BufferUsages::INDEX,
+        },
+    )
+}
+
+/// Whether a run holds only geometry a gbuffers program can draw from the shared atlas: no
+/// celestial body, cloud, beam, End portal or crack (overlay codes Horizon's entity shader
+/// draws in its own way; entity.wgsl).
+fn plain(run: &[Vertex]) -> bool {
+    run.iter()
+        .step_by(4)
+        .all(|v| !matches!(v.layer, 2 | 4 | 6 | 9 | 10 | 11 | 12))
+}
+
+/// Whether the pack draws a run of render stage `stage` (`Some(true)` with `gbuffers_block`),
+/// given which of `gbuffers_entities` and `gbuffers_block` (or their fallbacks) it has.
+pub fn drawn_by_pack(stage: u32, drawn: [bool; 2]) -> Option<bool> {
+    if stage == render_stage("ENTITIES") && drawn[0] {
+        Some(false)
+    } else if stage == render_stage("BLOCK_ENTITIES") && drawn[1] {
+        Some(true)
+    } else {
+        None
+    }
+}
+
+/// Each span with its vertex range: from its start to the next span's (or the end).
+pub fn runs(
+    len: usize,
+    spans: &[EntitySpan],
+) -> impl Iterator<Item = (EntitySpan, Range<usize>)> + '_ {
+    spans.iter().enumerate().map(move |(i, s)| {
+        let end = spans.get(i + 1).map_or(len, |n| n.start as usize);
+        let start = (s.start as usize).min(len);
+        (*s, start..end.clamp(start, len))
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn runs_split_the_list_between_pack_and_horizon() {
+        let v = |layer| Vertex {
+            layer,
+            ..bytemuck::Zeroable::zeroed()
+        };
+        let span = |start, stage: &str, id| EntitySpan {
+            start,
+            stage: render_stage(stage),
+            id,
+        };
+        let spans = [
+            span(2, "ENTITIES", 7),
+            span(5, "PARTICLES", 0),
+            span(6, "BLOCK_ENTITIES", 9),
+        ];
+        let ranges: Vec<_> = runs(10, &spans).map(|(_, r)| r).collect();
+        assert_eq!(ranges, [2..5, 5..6, 6..10]);
+        assert_eq!(drawn_by_pack(spans[0].stage, [true, false]), Some(false));
+        assert_eq!(drawn_by_pack(spans[1].stage, [true, true]), None);
+        assert_eq!(drawn_by_pack(spans[2].stage, [true, false]), None);
+        assert_eq!(drawn_by_pack(spans[2].stage, [false, true]), Some(true));
+        // A beacon beam's quads stay Horizon's.
+        assert!(plain(&[v(0), v(0), v(0), v(0), v(1)]));
+        assert!(!plain(&[v(0), v(0), v(0), v(0), v(6)]));
+        assert_eq!(entity_color(1)[0], 1.0);
+        assert!((entity_color(1)[3] - (1.0 - 178.0 / 255.0)).abs() < 1e-6);
+        assert_eq!(entity_color(0), [0.0; 4]);
+    }
+}
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index c3a67f22e..8d6d12d94 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -16,6 +16,7 @@ use std::collections::HashMap;
 use horizon_shaders::{Format, Group, Kind, Post, Val};
 
 use super::pack_draw::DrawUniforms;
+use super::pack_entities::PackEntities;
 use super::pack_sky::PackSky;
 use super::pack_uniforms::{self, FrameUniforms, PackInputs};
 
@@ -130,6 +131,14 @@ struct Sky {
     textured: Option<Pass>,
 }
 
+/// Entities and block entities a pack draws (`gbuffers_entities`, `gbuffers_block` or their
+/// fallbacks), after terrain; Horizon draws the others.
+struct Entities {
+    geometry: PackEntities,
+    entity: Option<Pass>,
+    block: Option<Pass>,
+}
+
 struct Pass {
     name: String,
     group: Group,
@@ -203,6 +212,8 @@ pub struct PackPost {
     water: Option<Pass>,
     /// What draws the sky (`gbuffers_skybasic` or its fallback), before terrain, and its vertices.
     sky: Option<Sky>,
+    /// What draws entities and block entities, after terrain, and their vertices.
+    entities: Option<Entities>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -901,6 +912,28 @@ impl PackPost {
             }
         });
         let sky = sky.filter(|s| s.basic.is_some() || s.textured.is_some());
+        let entity_vertices = (post.entities.is_some() || post.block.is_some())
+            .then(|| PackEntities::new(device, &draws.layout));
+        let entity_buffers = super::pack_entities::buffers();
+        let entity_geometry = entity_vertices.as_ref().map(|e| Geometry {
+            buffers: &entity_buffers,
+            table: Some(&e.table),
+            depth_write: true,
+            atlas: world.celestial.clone(),
+            ids: None,
+            cull: false,
+        });
+        let entity = post.entities.zip(entity_geometry.as_ref());
+        let entity = entity.and_then(|(p, g)| build(p, Some(g)));
+        let block = post.block.zip(entity_geometry.as_ref());
+        let block = block.and_then(|(p, g)| build(p, Some(g)));
+        let entities = entity_vertices
+            .filter(|_| entity.is_some() || block.is_some())
+            .map(|geometry| Entities {
+                geometry,
+                entity,
+                block,
+            });
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
@@ -923,6 +956,14 @@ impl PackPost {
                 notes.push(format!("the {part} draw with {}", p.name));
             }
         }
+        for (part, pass) in entities
+            .iter()
+            .flat_map(|e| [("entities", &e.entity), ("block entities", &e.block)])
+        {
+            if let Some(p) = pass {
+                notes.push(format!("{part} draw with {}", p.name));
+            }
+        }
         let depth1 = water.is_some()
             && passes
                 .iter()
@@ -940,6 +981,11 @@ impl PackPost {
                 .iter()
                 .flat_map(|s| s.basic.iter().chain(&s.textured))
                 .chain(&terrain)
+                .chain(
+                    entities
+                        .iter()
+                        .flat_map(|e| e.entity.iter().chain(&e.block)),
+                )
                 .chain(&water)
                 .find(touched)
                 .map(|_| true)
@@ -955,6 +1001,7 @@ impl PackPost {
         let blit_depth = terrain.is_some()
             || water.is_some()
             || sky.is_some()
+            || entities.is_some()
             || passes.iter().any(|p| {
                 p.samplers
                     .iter()
@@ -1050,6 +1097,7 @@ impl PackPost {
             terrain,
             water,
             sky,
+            entities,
             depth1,
             mipped,
             mips_valid: 0,
@@ -1372,7 +1420,82 @@ impl PackPost {
         self.sky = Some(sky);
     }
 
-    /// The sky, when it shows, then terrain.
+    /// Entities and block entities with the pack's programs: each run `prepare_entities` kept
+    /// is one draw with its own `entityId` or `blockEntityId` and `entityColor`.
+    fn draw_entities(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+    ) {
+        let Some(mut entities) = self.entities.take() else {
+            return;
+        };
+        let geometry = &entities.geometry;
+        for (block, pass) in [(false, &mut entities.entity), (true, &mut entities.block)] {
+            let Some(pass) = pass else { continue };
+            let mut draws = geometry
+                .draws
+                .iter()
+                .filter(|d| d.block == block)
+                .peekable();
+            if draws.peek().is_none() {
+                continue;
+            }
+            let group = self.bind(device, queue, pass, size);
+            {
+                let mut rp = self.begin(encoder, pass);
+                rp.set_pipeline(&pass.pipeline);
+                rp.set_bind_group(0, &group, &[]);
+                rp.set_bind_group(1, &geometry.table_group, &[]);
+                rp.set_vertex_buffer(0, geometry.vertices());
+                rp.set_index_buffer(geometry.indices.slice(..), wgpu::IndexFormat::Uint32);
+                for d in draws {
+                    if pass.draw {
+                        rp.set_bind_group(2, &geometry.group, &[geometry.offset(d.slot)]);
+                    }
+                    rp.draw_indexed(0..d.quads * 6, d.base as i32, 0..1);
+                }
+            }
+            self.mips_valid &= !pass.written;
+        }
+        self.entities = Some(entities);
+    }
+
+    /// Splits `entities` (`Frame::entities`) between the pack and Horizon by its runs
+    /// (`spans`): the pack's part is uploaded for this frame's draw, Horizon's goes to `rest`.
+    pub fn prepare_entities(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        entities: &[super::Vertex],
+        spans: &[super::pack_draw::EntitySpan],
+        rest: &mut Vec<super::Vertex>,
+    ) {
+        let Some(e) = &mut self.entities else {
+            rest.clear();
+            rest.extend_from_slice(entities);
+            return;
+        };
+        let drawn = [e.entity.is_some(), e.block.is_some()];
+        e.geometry.prepare(
+            device,
+            queue,
+            &self.draws.layout,
+            entities,
+            spans,
+            drawn,
+            rest,
+        );
+    }
+
+    /// Whether the pack draws entities or block entities itself.
+    pub fn has_entities(&self) -> bool {
+        self.entities.is_some()
+    }
+
+    /// The sky, when it shows, then terrain, entities and block entities.
     fn draw_opaque(
         &mut self,
         device: &wgpu::Device,
@@ -1386,6 +1509,7 @@ impl PackPost {
             self.draw_sky(device, queue, encoder, size, frame);
         }
         self.draw_terrain(device, queue, encoder, size, false, terrain);
+        self.draw_entities(device, queue, encoder, size);
     }
 
     /// Regenerates the mip chain of buffer `b`'s side that programs read.
@@ -1692,7 +1816,8 @@ impl PackPost {
         let mut passes = std::mem::take(&mut self.passes);
         let mut seen = (false, false);
         let mut shown = false;
-        let mut terrain_drawn = self.terrain.is_none() && self.sky.is_none();
+        let mut terrain_drawn =
+            self.terrain.is_none() && self.sky.is_none() && self.entities.is_none();
         let mut water_drawn = self.water.is_none();
         for pass in &mut passes {
             if !terrain_drawn && pass.group != Group::Prepare {
diff --git a/crates/horizon-client/src/gfx/pack_timing.rs b/crates/horizon-client/src/gfx/pack_timing.rs
index 61ab721e5..acfdb698f 100644
--- a/crates/horizon-client/src/gfx/pack_timing.rs
+++ b/crates/horizon-client/src/gfx/pack_timing.rs
@@ -132,7 +132,8 @@ impl PassTiming {
     fn report(&mut self) {
         let mut total = 0.0;
         let mut parts = Vec::new();
-        for (name, v) in &mut self.samples {
+        // A pass that did not run in this window (no entities, the sky out of sight) is left out.
+        for (name, v) in self.samples.iter_mut().filter(|s| !s.1.is_empty()) {
             v.sort_by(f32::total_cmp);
             let median = v[v.len() / 2];
             total += median;
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 7b83b98b5..71c055c2b 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -103,6 +103,23 @@ const SKY_TEXTURED: [&str; 3] = [
     "gbuffers_basic",
 ];
 
+/// `gbuffers_entities` and its fallbacks (2.3).
+const ENTITIES: [&str; 4] = [
+    "gbuffers_entities",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
+/// `gbuffers_block` and its fallbacks (2.3).
+const BLOCK: [&str; 5] = [
+    "gbuffers_block",
+    "gbuffers_terrain",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
 /// The sun and moon's default blend: added to the sky, as vanilla draws them.
 pub const CELESTIAL_BLEND: Blend = [
     Factor::SrcAlpha,
@@ -149,6 +166,10 @@ pub struct Post {
     pub sky: Option<PostProgram>,
     /// What draws the sun and moon, between the sunset and the stars.
     pub sky_textured: Option<PostProgram>,
+    /// What draws entities, after terrain.
+    pub entities: Option<PostProgram>,
+    /// What draws block entities, after terrain.
+    pub block: Option<PostProgram>,
     /// The custom uniforms of `shaders.properties` (3.4).
     pub custom: Custom,
     pub config: Config,
@@ -174,6 +195,8 @@ pub struct GameInputs {
     pub terrain: Option<GbuffersInputs>,
     pub sky: Option<GbuffersInputs>,
     pub celestial: Option<GbuffersInputs>,
+    /// Entities and block entities (one vertex format).
+    pub entities: Option<GbuffersInputs>,
 }
 
 /// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
@@ -194,6 +217,8 @@ pub fn load_post(
         water: None,
         sky: None,
         sky_textured: None,
+        entities: None,
+        block: None,
         custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
@@ -253,6 +278,21 @@ pub fn load_post(
         p.blend = blend(properties, &p.name).unwrap_or(Some(CELESTIAL_BLEND));
         p
     });
+    // Entities and block entities draw without blending, as terrain does and as vanilla's
+    // cutout entity types do, unless `blend.*` says otherwise (OQ-23).
+    let entity_blend = |p: Option<PostProgram>| {
+        p.map(|mut p| {
+            p.blend = blend(properties, &p.name).flatten();
+            p
+        })
+    };
+    let (entities, block) = match &inputs.entities {
+        Some(i) => (
+            entity_blend(gbuffers(&ENTITIES, Group::Gbuffers, i)),
+            entity_blend(gbuffers(&BLOCK, Group::Gbuffers, i)),
+        ),
+        None => (None, None),
+    };
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -268,6 +308,8 @@ pub fn load_post(
     }
     loader.post.sky = sky;
     loader.post.sky_textured = sky_textured;
+    loader.post.entities = entities;
+    loader.post.block = block;
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
@@ -530,8 +572,8 @@ mod tests {
         assert!(post.programs.iter().any(|p| p.name == "composite3"));
     }
 
-    /// Water falls back to the terrain chain and blends by default, as the sky does; `blend.*`
-    /// overrides.
+    /// Water falls back to the terrain chain and blends by default, as the sky does; entities
+    /// and block entities fall back along theirs; `blend.*` overrides.
     #[test]
     fn water_falls_back_to_terrain_and_blends() {
         let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/packs/terrain-test");
@@ -545,7 +587,8 @@ mod tests {
         let inputs = GameInputs {
             terrain: Some(inputs.clone()),
             sky: Some(inputs.clone()),
-            celestial: Some(inputs),
+            celestial: Some(inputs.clone()),
+            entities: Some(inputs),
         };
         let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
@@ -570,6 +613,17 @@ mod tests {
             (water.group, water.blend),
             (Group::Translucent, Some(TRANSLUCENT_BLEND))
         );
+        // Entities fall back to gbuffers_textured, block entities to gbuffers_terrain; both
+        // draw without blending.
+        let (entities, block) = (post.entities.unwrap(), post.block.unwrap());
+        assert_eq!(
+            (entities.name.as_str(), entities.blend),
+            ("gbuffers_textured", None)
+        );
+        assert_eq!(
+            (block.name.as_str(), block.blend),
+            ("gbuffers_terrain", None)
+        );
         let properties = Properties::parse(
             "blend.gbuffers_terrain = ONE ONE ZERO ONE\nblend.gbuffers_water = off\n",
             &macros,
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 5ed954898..b77b3b158 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -172,16 +172,19 @@ fn real_packs_read() {
             let inputs = horizon_shaders::GameInputs {
                 terrain: Some(terrain.clone()),
                 sky: Some(terrain.clone()),
-                celestial: Some(terrain),
+                celestial: Some(terrain.clone()),
+                entities: Some(terrain),
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?} {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?} {:?}, entities {:?} {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
                 post.terrain.as_ref().map(|t| &t.name),
                 post.water.as_ref().map(|t| &t.name),
                 post.sky.as_ref().map(|t| &t.name),
                 post.sky_textured.as_ref().map(|t| &t.name),
+                post.entities.as_ref().map(|t| &t.name),
+                post.block.as_ref().map(|t| &t.name),
                 post.notes.len() + post.config.notes.len(),
                 start.elapsed().as_secs_f64() * 1000.0
             );

From 3a7d00a74c3202242356b31ef94a53e8b4478fba Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:11:09 +0100
Subject: [PATCH 039/270] Shader packs, clean room 32: translucent entity parts
 and particles

A shader pack now draws particles with `gbuffers_particles` (falling
back to `gbuffers_textured_lit`, `gbuffers_textured`, `gbuffers_basic`)
and the entity parts that blend, a sneaking player's faded name tag and
entity shadows, with `gbuffers_entities_translucent` (falling back to
`gbuffers_entities`). Both blend with the translucent default unless
`blend.*` says otherwise; particles keep vanilla's alpha cut at 0.1.
Name tag text draws with `gbuffers_entities`, as cutout (2.3).

Particles draw after deferred, with translucent terrain, unless
`particles.ordering=before` or `particles.before.deferred=true`;
translucent entities draw before deferred unless
`separateEntityDraws=true` (3.2).

Without a shader pack nothing changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  4 +-
 crates/horizon-client/src/game/names.rs       |  4 +
 .../horizon-client/src/game/shader_packs.rs   | 13 +++
 crates/horizon-client/src/gfx/pack_draw.rs    |  2 +
 .../horizon-client/src/gfx/pack_entities.rs   | 69 +++++++++-----
 crates/horizon-client/src/gfx/pack_post.rs    | 94 +++++++++++++------
 crates/horizon-shaders/src/post.rs            | 78 +++++++++++++++
 7 files changed, 209 insertions(+), 55 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 180d38ab0..bddf59490 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -6784,12 +6784,10 @@ impl Game<'_> {
         self.fangs_geometry(camera, alpha, &mut out);
         let mut see_through = std::mem::take(&mut self.see_through_vertices);
         see_through.clear();
-        // Name tags and shadows blend: Horizon keeps drawing them until the pack's entity
-        // programs draw translucent parts (`minecraft:name_tag`, `minecraft:entity_shadow`).
-        self.mark_stage(out.len(), "NONE");
         self.name_tag_geometry(camera, alpha, &mut out, &mut see_through);
         self.see_through_vertices = see_through;
         // Entity shadows (EntityRenderer.extractShadow).
+        self.mark_translucent_entity(out.len(), "minecraft:entity_shadow");
         if let Some(sprite) = self.gui.atlas.sprites.get("misc/shadow").copied() {
             let ambient = if self.dim == Dim::Nether { 0.1 } else { 0.0 };
             let darken = self.sky_darken();
diff --git a/crates/horizon-client/src/game/names.rs b/crates/horizon-client/src/game/names.rs
index be829f1bb..3c97a9368 100644
--- a/crates/horizon-client/src/game/names.rs
+++ b/crates/horizon-client/src/game/names.rs
@@ -253,12 +253,16 @@ impl Game<'_> {
         const FADED: u32 = 0x7F;
         for tag in self.name_tags(camera, alpha) {
             let o = tag.at - camera;
+            // `gbuffers_entities` draws name tag text (2.3); a sneaking player's faded tag, on its
+            // background, blends.
             if tag.discrete {
+                self.mark_translucent_entity(out.len(), "minecraft:name_tag");
                 self.name_tag_quads(o, &tag.lines, FADED, true, 0, vertex_light(tag.light), out);
                 continue;
             }
             // LightCoordsUtil.lightCoordsWithEmission(lightCoords, 2).
             let lit = (tag.light >> 4).max(2) << 4 | (tag.light & 15).max(2);
+            self.mark_entity(out.len(), "minecraft:name_tag");
             self.name_tag_quads(o, &tag.lines, 0xFF, false, 0, vertex_light(lit), out);
             // RenderPipelines.TEXT_SEE_THROUGH: no depth test, no lightmap.
             self.name_tag_quads(o, &tag.lines, FADED, true, 2, 0, see_through);
diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index 6699a753d..88a73c108 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -146,9 +146,21 @@ impl Game<'_> {
     /// Starts a span of the entity geometry at vertex `start` for entity type `name`
     /// (`minecraft:zombie`; "" for one the pack cannot name). Nothing without a pack.
     pub(super) fn mark_entity(&self, start: usize, name: &str) {
+        self.mark_entity_part(start, name, false);
+    }
+
+    /// Starts a span for entity geometry that blends (name tags, shadows).
+    pub(super) fn mark_translucent_entity(&self, start: usize, name: &str) {
+        self.mark_entity_part(start, name, true);
+    }
+
+    fn mark_entity_part(&self, start: usize, name: &str, translucent: bool) {
         if let Some(ids) = &self.pack_ids {
             let id = ids.entities.get(name).copied();
             self.push_span(start, "ENTITIES", id.unwrap_or(ids.missing_entity));
+            if let Some(last) = self.entity_spans.borrow_mut().last_mut() {
+                last.translucent = translucent;
+            }
         }
     }
 
@@ -185,6 +197,7 @@ impl Game<'_> {
             start: start as u32,
             stage: horizon_shaders::render_stage(stage),
             id,
+            translucent: false,
         };
         // A span that drew nothing gives way to the next.
         match spans.last_mut() {
diff --git a/crates/horizon-client/src/gfx/pack_draw.rs b/crates/horizon-client/src/gfx/pack_draw.rs
index f365c484f..d19c3b4db 100644
--- a/crates/horizon-client/src/gfx/pack_draw.rs
+++ b/crates/horizon-client/src/gfx/pack_draw.rs
@@ -16,6 +16,8 @@ pub struct EntitySpan {
     pub stage: u32,
     /// `entityId` for entities, `blockEntityId` for block entities (5.3), else 0.
     pub id: i32,
+    /// An entity part that blends (a name tag, a shadow): `gbuffers_entities_translucent`.
+    pub translucent: bool,
 }
 
 /// `HzDraw`'s size: `renderStage`, `entityId`, `blockEntityId`, a pad, `entityColor`.
diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
index b30aa4fdb..6f7de5fe1 100644
--- a/crates/horizon-client/src/gfx/pack_entities.rs
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -1,5 +1,6 @@
-//! Entities and block entities drawn by a shader pack's `gbuffers_entities` and `gbuffers_block`
-//! (spec 2.3, 5.3, 5.4): the runs of `Frame::entities` the game marked (`EntitySpan`), each its
+//! Entities, block entities, translucent entity parts and particles drawn by a shader pack's
+//! `gbuffers_entities`, `gbuffers_block`, `gbuffers_entities_translucent` and
+//! `gbuffers_particles` (spec 2.3, 5.3, 5.4): the runs of `Frame::entities` the game marked (`EntitySpan`), each its
 //! own draw with its `entityId` or `blockEntityId` and `entityColor` in a per-draw slot of
 //! `HzDraw` (set 2). Horizon draws whatever the pack does not.
 
@@ -125,8 +126,8 @@ pub(super) struct Draw {
     /// The first vertex.
     pub base: u32,
     pub quads: u32,
-    /// `gbuffers_block` (or its fallback) draws it, not `gbuffers_entities`.
-    pub block: bool,
+    /// The program that draws it (`ENTITY`, `BLOCK`, `TRANSLUCENT`, `PARTICLE`).
+    pub program: usize,
     pub slot: u32,
 }
 
@@ -253,7 +254,7 @@ impl PackEntities {
         layout: &wgpu::BindGroupLayout,
         entities: &[Vertex],
         spans: &[EntitySpan],
-        drawn: [bool; 2],
+        drawn: [bool; PROGRAMS],
         rest: &mut Vec<Vertex>,
     ) {
         self.draws.clear();
@@ -264,7 +265,7 @@ impl PackEntities {
         rest.extend_from_slice(&entities[..first.min(entities.len())]);
         for (span, range) in runs(entities.len(), spans) {
             let run = &entities[range];
-            let Some(block) = drawn_by_pack(span.stage, drawn).filter(|_| plain(run)) else {
+            let Some(program) = drawn_by_pack(&span, drawn).filter(|_| plain(run)) else {
                 rest.extend_from_slice(run);
                 continue;
             };
@@ -273,7 +274,10 @@ impl PackEntities {
             }
             let start = self.scratch.len() as u32;
             self.scratch.extend_from_slice(run);
-            let (entity_id, block_id) = if block { (0, span.id) } else { (span.id, 0) };
+            let (entity_id, block_id) = match program {
+                BLOCK => (0, span.id),
+                _ => (span.id, 0),
+            };
             let mut bytes = [0u8; SLOT as usize];
             bytes[0..4].copy_from_slice(&(span.stage as i32).to_le_bytes());
             bytes[4..8].copy_from_slice(&entity_id.to_le_bytes());
@@ -287,7 +291,7 @@ impl PackEntities {
             self.draws.push(Draw {
                 base: start,
                 quads: run.len() as u32 / 4,
-                block,
+                program,
                 slot: self.draws.len() as u32,
             });
         }
@@ -340,16 +344,30 @@ fn plain(run: &[Vertex]) -> bool {
         .all(|v| !matches!(v.layer, 2 | 4 | 6 | 9 | 10 | 11 | 12))
 }
 
-/// Whether the pack draws a run of render stage `stage` (`Some(true)` with `gbuffers_block`),
-/// given which of `gbuffers_entities` and `gbuffers_block` (or their fallbacks) it has.
-pub fn drawn_by_pack(stage: u32, drawn: [bool; 2]) -> Option<bool> {
-    if stage == render_stage("ENTITIES") && drawn[0] {
-        Some(false)
-    } else if stage == render_stage("BLOCK_ENTITIES") && drawn[1] {
-        Some(true)
+/// The programs of entity runs, in the order they draw.
+pub const ENTITY: usize = 0;
+pub const BLOCK: usize = 1;
+pub const TRANSLUCENT: usize = 2;
+pub const PARTICLE: usize = 3;
+pub const PROGRAMS: usize = 4;
+
+/// Which program draws `span`'s run, given which of them (or their fallbacks) the pack has;
+/// `None`: Horizon draws it.
+pub fn drawn_by_pack(span: &EntitySpan, drawn: [bool; PROGRAMS]) -> Option<usize> {
+    let program = if span.stage == render_stage("ENTITIES") {
+        if span.translucent {
+            TRANSLUCENT
+        } else {
+            ENTITY
+        }
+    } else if span.stage == render_stage("BLOCK_ENTITIES") {
+        BLOCK
+    } else if span.stage == render_stage("PARTICLES") {
+        PARTICLE
     } else {
-        None
-    }
+        return None;
+    };
+    drawn[program].then_some(program)
 }
 
 /// Each span with its vertex range: from its start to the next span's (or the end).
@@ -378,6 +396,7 @@ mod tests {
             start,
             stage: render_stage(stage),
             id,
+            translucent: false,
         };
         let spans = [
             span(2, "ENTITIES", 7),
@@ -386,10 +405,18 @@ mod tests {
         ];
         let ranges: Vec<_> = runs(10, &spans).map(|(_, r)| r).collect();
         assert_eq!(ranges, [2..5, 5..6, 6..10]);
-        assert_eq!(drawn_by_pack(spans[0].stage, [true, false]), Some(false));
-        assert_eq!(drawn_by_pack(spans[1].stage, [true, true]), None);
-        assert_eq!(drawn_by_pack(spans[2].stage, [true, false]), None);
-        assert_eq!(drawn_by_pack(spans[2].stage, [false, true]), Some(true));
+        let all = [true; PROGRAMS];
+        assert_eq!(drawn_by_pack(&spans[0], all), Some(ENTITY));
+        assert_eq!(drawn_by_pack(&spans[1], all), Some(PARTICLE));
+        assert_eq!(drawn_by_pack(&spans[1], [true, true, true, false]), None);
+        assert_eq!(drawn_by_pack(&spans[2], [true, false, true, true]), None);
+        assert_eq!(drawn_by_pack(&spans[2], all), Some(BLOCK));
+        let shadow = EntitySpan {
+            translucent: true,
+            ..spans[0]
+        };
+        assert_eq!(drawn_by_pack(&shadow, all), Some(TRANSLUCENT));
+        assert_eq!(drawn_by_pack(&span(0, "DESTROY", 0), all), None);
         // A beacon beam's quads stay Horizon's.
         assert!(plain(&[v(0), v(0), v(0), v(0), v(1)]));
         assert!(!plain(&[v(0), v(0), v(0), v(0), v(6)]));
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 8d6d12d94..fc372ab95 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -16,7 +16,7 @@ use std::collections::HashMap;
 use horizon_shaders::{Format, Group, Kind, Post, Val};
 
 use super::pack_draw::DrawUniforms;
-use super::pack_entities::PackEntities;
+use super::pack_entities::{PROGRAMS, PackEntities};
 use super::pack_sky::PackSky;
 use super::pack_uniforms::{self, FrameUniforms, PackInputs};
 
@@ -131,12 +131,13 @@ struct Sky {
     textured: Option<Pass>,
 }
 
-/// Entities and block entities a pack draws (`gbuffers_entities`, `gbuffers_block` or their
-/// fallbacks), after terrain; Horizon draws the others.
+/// Entities, block entities, translucent entity parts and particles a pack draws
+/// (`pack_entities::ENTITY`... order), after terrain or, `late`, after deferred; Horizon draws
+/// the others.
 struct Entities {
     geometry: PackEntities,
-    entity: Option<Pass>,
-    block: Option<Pass>,
+    passes: [Option<Pass>; PROGRAMS],
+    late: [bool; PROGRAMS],
 }
 
 struct Pass {
@@ -912,7 +913,16 @@ impl PackPost {
             }
         });
         let sky = sky.filter(|s| s.basic.is_some() || s.textured.is_some());
-        let entity_vertices = (post.entities.is_some() || post.block.is_some())
+        let programs = [
+            post.entities,
+            post.block,
+            post.entities_translucent,
+            post.particles,
+        ];
+        let late = [false, false, post.translucent_late, post.particles_late];
+        let entity_vertices = programs
+            .iter()
+            .any(Option::is_some)
             .then(|| PackEntities::new(device, &draws.layout));
         let entity_buffers = super::pack_entities::buffers();
         let entity_geometry = entity_vertices.as_ref().map(|e| Geometry {
@@ -923,16 +933,16 @@ impl PackPost {
             ids: None,
             cull: false,
         });
-        let entity = post.entities.zip(entity_geometry.as_ref());
-        let entity = entity.and_then(|(p, g)| build(p, Some(g)));
-        let block = post.block.zip(entity_geometry.as_ref());
-        let block = block.and_then(|(p, g)| build(p, Some(g)));
+        let entity_passes = programs.map(|p| {
+            p.zip(entity_geometry.as_ref())
+                .and_then(|(p, g)| build(p, Some(g)))
+        });
         let entities = entity_vertices
-            .filter(|_| entity.is_some() || block.is_some())
+            .filter(|_| entity_passes.iter().any(Option::is_some))
             .map(|geometry| Entities {
                 geometry,
-                entity,
-                block,
+                passes: entity_passes,
+                late,
             });
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
@@ -956,10 +966,13 @@ impl PackPost {
                 notes.push(format!("the {part} draw with {}", p.name));
             }
         }
-        for (part, pass) in entities
-            .iter()
-            .flat_map(|e| [("entities", &e.entity), ("block entities", &e.block)])
-        {
+        let parts = [
+            "entities",
+            "block entities",
+            "translucent entities",
+            "particles",
+        ];
+        for (part, pass) in entities.iter().flat_map(|e| parts.iter().zip(&e.passes)) {
             if let Some(p) = pass {
                 notes.push(format!("{part} draw with {}", p.name));
             }
@@ -981,11 +994,7 @@ impl PackPost {
                 .iter()
                 .flat_map(|s| s.basic.iter().chain(&s.textured))
                 .chain(&terrain)
-                .chain(
-                    entities
-                        .iter()
-                        .flat_map(|e| e.entity.iter().chain(&e.block)),
-                )
+                .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
                 .chain(&water)
                 .find(touched)
                 .map(|_| true)
@@ -1420,7 +1429,8 @@ impl PackPost {
         self.sky = Some(sky);
     }
 
-    /// Entities and block entities with the pack's programs: each run `prepare_entities` kept
+    /// Entities, block entities, translucent entity parts and particles with the pack's
+    /// programs, those drawn before deferred or (`late`) after: each run `prepare_entities` kept
     /// is one draw with its own `entityId` or `blockEntityId` and `entityColor`.
     fn draw_entities(
         &mut self,
@@ -1428,17 +1438,20 @@ impl PackPost {
         queue: &wgpu::Queue,
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
+        late: bool,
     ) {
         let Some(mut entities) = self.entities.take() else {
             return;
         };
         let geometry = &entities.geometry;
-        for (block, pass) in [(false, &mut entities.entity), (true, &mut entities.block)] {
-            let Some(pass) = pass else { continue };
+        for (program, pass) in entities.passes.iter_mut().enumerate() {
+            let Some(pass) = pass.as_mut().filter(|_| entities.late[program] == late) else {
+                continue;
+            };
             let mut draws = geometry
                 .draws
                 .iter()
-                .filter(|d| d.block == block)
+                .filter(|d| d.program == program)
                 .peekable();
             if draws.peek().is_none() {
                 continue;
@@ -1478,7 +1491,7 @@ impl PackPost {
             rest.extend_from_slice(entities);
             return;
         };
-        let drawn = [e.entity.is_some(), e.block.is_some()];
+        let drawn = e.passes.each_ref().map(Option::is_some);
         e.geometry.prepare(
             device,
             queue,
@@ -1509,7 +1522,20 @@ impl PackPost {
             self.draw_sky(device, queue, encoder, size, frame);
         }
         self.draw_terrain(device, queue, encoder, size, false, terrain);
-        self.draw_entities(device, queue, encoder, size);
+        self.draw_entities(device, queue, encoder, size, false);
+    }
+
+    /// Translucent terrain, then the entity parts drawn after deferred.
+    fn draw_translucent(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        terrain: &mut TerrainDraw<'_>,
+    ) {
+        self.draw_terrain(device, queue, encoder, size, true, terrain);
+        self.draw_entities(device, queue, encoder, size, true);
     }
 
     /// Regenerates the mip chain of buffer `b`'s side that programs read.
@@ -1818,7 +1844,13 @@ impl PackPost {
         let mut shown = false;
         let mut terrain_drawn =
             self.terrain.is_none() && self.sky.is_none() && self.entities.is_none();
-        let mut water_drawn = self.water.is_none();
+        let late_entities = self.entities.as_ref().is_some_and(|e| {
+            e.passes
+                .iter()
+                .zip(e.late)
+                .any(|(p, late)| p.is_some() && late)
+        });
+        let mut water_drawn = self.water.is_none() && !late_entities;
         for pass in &mut passes {
             if !terrain_drawn && pass.group != Group::Prepare {
                 terrain_drawn = true;
@@ -1826,7 +1858,7 @@ impl PackPost {
             }
             if !water_drawn && matches!(pass.group, Group::Composite | Group::Final) {
                 water_drawn = true;
-                self.draw_terrain(device, queue, encoder, size, true, terrain);
+                self.draw_translucent(device, queue, encoder, size, terrain);
             }
             if pass.group == Group::Deferred && !seen.0 {
                 seen.0 = true;
@@ -1881,7 +1913,7 @@ impl PackPost {
             self.draw_opaque(device, queue, encoder, size, frame, terrain);
         }
         if !water_drawn {
-            self.draw_terrain(device, queue, encoder, size, true, terrain);
+            self.draw_translucent(device, queue, encoder, size, terrain);
         }
         let targets = self.targets.as_ref().expect("resized");
         let view = |m: u16, i: usize, alt: bool| {
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 71c055c2b..a31cf5ce7 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -120,6 +120,23 @@ const BLOCK: [&str; 5] = [
     "gbuffers_basic",
 ];
 
+/// `gbuffers_entities_translucent` and its fallbacks (2.3).
+const ENTITIES_TRANSLUCENT: [&str; 5] = [
+    "gbuffers_entities_translucent",
+    "gbuffers_entities",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
+/// `gbuffers_particles` and its fallbacks (2.3).
+const PARTICLES: [&str; 4] = [
+    "gbuffers_particles",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
 /// The sun and moon's default blend: added to the sky, as vanilla draws them.
 pub const CELESTIAL_BLEND: Blend = [
     Factor::SrcAlpha,
@@ -170,6 +187,14 @@ pub struct Post {
     pub entities: Option<PostProgram>,
     /// What draws block entities, after terrain.
     pub block: Option<PostProgram>,
+    /// What draws translucent entities (name tags, shadows), after the others.
+    pub entities_translucent: Option<PostProgram>,
+    /// What draws particles.
+    pub particles: Option<PostProgram>,
+    /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
+    pub translucent_late: bool,
+    /// Particles draw after deferred (`particles.ordering`, `particles.before.deferred`, 3.2).
+    pub particles_late: bool,
     /// The custom uniforms of `shaders.properties` (3.4).
     pub custom: Custom,
     pub config: Config,
@@ -219,6 +244,10 @@ pub fn load_post(
         sky_textured: None,
         entities: None,
         block: None,
+        entities_translucent: None,
+        particles: None,
+        translucent_late: false,
+        particles_late: false,
         custom: Custom::parse(properties),
         config: Config::default(),
         notes: Vec::new(),
@@ -293,6 +322,26 @@ pub fn load_post(
         ),
         None => (None, None),
     };
+    // Translucent entities and particles blend (OQ-23). Particles keep vanilla's alpha cut at
+    // 0.1; translucent entities lose only fully transparent texels (a shadow fades out).
+    let translucent =
+        |names: &[&str],
+         cut: f32,
+         gbuffers: &mut dyn FnMut(&[&str], &GbuffersInputs) -> Option<PostProgram>| {
+            let i = inputs.entities.as_ref()?;
+            let mut i = i.clone();
+            i.alpha_test = Some(crate::AlphaTest {
+                op: ">",
+                reference: cut,
+            });
+            gbuffers(names, &i).map(|mut p| {
+                p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
+                p
+            })
+        };
+    let mut gbuffers_dyn = |names: &[&str], i: &GbuffersInputs| gbuffers(names, Group::Gbuffers, i);
+    let entities_translucent = translucent(&ENTITIES_TRANSLUCENT, 0.0, &mut gbuffers_dyn);
+    let particles = translucent(&PARTICLES, 0.1, &mut gbuffers_dyn);
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -310,6 +359,17 @@ pub fn load_post(
     loader.post.sky_textured = sky_textured;
     loader.post.entities = entities;
     loader.post.block = block;
+    loader.post.entities_translucent = entities_translucent;
+    loader.post.particles = particles;
+    let flag = |key: &str| properties.get(key).map(|v| v.trim() == "true");
+    loader.post.translucent_late = flag("separateEntityDraws").unwrap_or(false);
+    // `after` when the pack has a deferred program, else `mixed`; ours are all translucent, so
+    // `mixed` draws them after deferred too.
+    loader.post.particles_late = match properties.get("particles.ordering").map(str::trim) {
+        Some("before") => false,
+        Some(_) => true,
+        None => !flag("particles.before.deferred").unwrap_or(false),
+    };
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
@@ -624,6 +684,24 @@ mod tests {
             (block.name.as_str(), block.blend),
             ("gbuffers_terrain", None)
         );
+        // Translucent entity parts and particles blend; particles draw after deferred unless
+        // the pack says otherwise, translucent entities before unless `separateEntityDraws`.
+        let (translucent, particles) = (
+            post.entities_translucent.as_ref().unwrap(),
+            post.particles.as_ref().unwrap(),
+        );
+        assert_eq!(
+            (translucent.name.as_str(), translucent.blend),
+            ("gbuffers_textured", Some(TRANSLUCENT_BLEND))
+        );
+        assert_eq!(particles.blend, Some(TRANSLUCENT_BLEND));
+        assert!(post.particles_late && !post.translucent_late);
+        let ordering = Properties::parse(
+            "particles.ordering = before\nseparateEntityDraws = true\n",
+            &macros,
+        );
+        let post = load_post(&pack, "", &ordering, &macros, &inputs);
+        assert!(!post.particles_late && post.translucent_late);
         let properties = Properties::parse(
             "blend.gbuffers_terrain = ONE ONE ZERO ONE\nblend.gbuffers_water = off\n",
             &macros,

From 3bc38cebb4aa90bb791f7e3244cf1c0767b625f8 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:17:21 +0100
Subject: [PATCH 040/270] YUNG jigsaws: the start is not counted, priority,
 depth and bounds rules run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From spec-yungsapi rev 3 §3, §3.1 and §3.2 (impl-questions IQ-2, IQ-3):
- the start piece does not count toward max_count;
- is_priority entries are tried first, in the pool's shuffled order, without
  a weighted draw; min_required_depth skips a pick (no draw) while the parent
  piece is shallower; ignore_bounds places without the free-space test (its
  box is still taken, IQ-12);
- the fallback was already shuffled only when reached.

The port no longer counts these three fields as lost. The layout harness gets
yung-probe and yung-probe2: the spec team's probe pack (built from the oracle
profile) carried as a mod, compared start by start with the oracle's census:
384 of 384 and 32 of 32 starts match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-port-pack/src/yung.rs          |  15 +-
 .../src/worldgen/structure/jigsaw.rs          | 155 ++++++++++++------
 tools/test_structure_layout_parity.py         |  55 ++++++-
 3 files changed, 161 insertions(+), 64 deletions(-)

diff --git a/crates/horizon-port-pack/src/yung.rs b/crates/horizon-port-pack/src/yung.rs
index 1cb970846..3734a1a95 100644
--- a/crates/horizon-port-pack/src/yung.rs
+++ b/crates/horizon-port-pack/src/yung.rs
@@ -54,15 +54,9 @@ pub(crate) fn upgrade_pool_element(element: &Value, lost: &mut BTreeMap<String,
     if element["element_type"] != ELEMENT {
         return false;
     }
-    // spec-yungsapi §3: OPEN-Y5 to OPEN-Y9 and §5.
-    for field in [
-        "is_priority",
-        "min_required_depth",
-        "ignore_bounds",
-        "condition",
-        "enhanced_terrain_adaptation",
-        "modifiers",
-    ] {
+    // spec-yungsapi §4 and §5. `name`, `max_count`, `is_priority`,
+    // `min_required_depth` and `ignore_bounds` are run (§3, §3.2).
+    for field in ["condition", "enhanced_terrain_adaptation", "modifiers"] {
         if active(element, field) {
             count(lost, format!("{ELEMENT} {field}"));
         }
@@ -95,7 +89,8 @@ mod tests {
 
         let mut lost = BTreeMap::new();
         let pile = json!({"element_type": ELEMENT, "name": "loot_pile_0", "max_count": 1,
-            "enhanced_terrain_adaptation": {"type": NO_ADAPTATION}, "is_priority": false});
+            "enhanced_terrain_adaptation": {"type": NO_ADAPTATION}, "is_priority": true,
+            "min_required_depth": 2, "ignore_bounds": true});
         assert!(upgrade_pool_element(&pile, &mut lost));
         assert!(lost.is_empty());
         let gated = json!({"element_type": ELEMENT, "condition": {"type": "yungsapi:not"}});
diff --git a/crates/horizon-world/src/worldgen/structure/jigsaw.rs b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
index 6e1da3a4c..85f202498 100644
--- a/crates/horizon-world/src/worldgen/structure/jigsaw.rs
+++ b/crates/horizon-world/src/worldgen/structure/jigsaw.rs
@@ -120,7 +120,7 @@ impl PoolElement {
         Ok(match kind {
             "minecraft:empty_pool_element" => Self::Empty,
             // YUNG's API's element places what a single element places; its
-            // `name` and `max_count` are the pool entry's (`Pool::limits`).
+            // own fields are the pool entry's rules (`Pool::rules`).
             "minecraft:single_pool_element"
             | "minecraft:legacy_single_pool_element"
             | "yungsapi:yung_single_element" => {
@@ -323,9 +323,8 @@ pub struct Pool {
     pub(super) templates: Vec<Arc<PoolElement>>,
     /// The elements with their weights, in file order (`rawTemplates`).
     pub(super) raw: Vec<(Arc<PoolElement>, i32)>,
-    /// Per entry of `raw`: a YUNG element's `name` and `max_count`, the most
-    /// pieces of that name in one start.
-    limits: Vec<Option<(Arc<str>, i32)>>,
+    /// Per entry of `raw`: a YUNG element's rules.
+    rules: Vec<Rules>,
     pub(super) fallback: String,
     max_size: OnceLock<i32>,
 }
@@ -365,6 +364,37 @@ impl Pool {
         })
     }
 }
+/// A `yungsapi:yung_single_element`'s own fields (spec-yungsapi §3, §3.2).
+#[derive(Clone, Debug, Default)]
+struct Rules {
+    /// `name` and `max_count`: the most pieces of that name in one start,
+    /// the start not counted.
+    limit: Option<(Arc<str>, i32)>,
+    /// `is_priority`: tried before the pool's other entries, in the
+    /// shuffled order and without a weighted draw.
+    priority: bool,
+    /// `min_required_depth`: the least depth of the parent piece (the start
+    /// is depth 0).
+    min_depth: i32,
+    /// `ignore_bounds`: placed without the free-space test.
+    ignore_bounds: bool,
+}
+impl Rules {
+    fn of(element: &Value) -> Self {
+        if element["element_type"] != "yungsapi:yung_single_element" {
+            return Self::default();
+        }
+        Self {
+            limit: element["name"]
+                .as_str()
+                .zip(element["max_count"].as_i64())
+                .map(|(name, max)| (name.into(), max as i32)),
+            priority: element["is_priority"].as_bool().unwrap_or(false),
+            min_depth: element["min_required_depth"].as_i64().unwrap_or(0) as i32,
+            ignore_bounds: element["ignore_bounds"].as_bool().unwrap_or(false),
+        }
+    }
+}
 /// Lazily decoded template pools.
 pub struct Pools {
     raw: BTreeMap<String, String>,
@@ -393,7 +423,7 @@ impl Pools {
         }
         let pool = self.raw.get(name).and_then(|json| {
             let value: Value = serde_json::from_str(json).ok()?;
-            let (mut templates, mut raw, mut limits) = (Vec::new(), Vec::new(), Vec::new());
+            let (mut templates, mut raw, mut rules) = (Vec::new(), Vec::new(), Vec::new());
             for entry in value["elements"].as_array()? {
                 let element =
                     match PoolElement::decode(&entry["element"], resources, bindings, None) {
@@ -410,22 +440,12 @@ impl Pools {
                     templates.push(element.clone());
                 }
                 raw.push((element, weight as i32));
-                let fields = &entry["element"];
-                limits.push(
-                    match (fields["name"].as_str(), fields["max_count"].as_i64()) {
-                        (Some(name), Some(max))
-                            if fields["element_type"] == "yungsapi:yung_single_element" =>
-                        {
-                            Some((name.into(), max as i32))
-                        }
-                        _ => None,
-                    },
-                );
+                rules.push(Rules::of(&entry["element"]));
             }
             Some(Arc::new(Pool {
                 templates,
                 raw,
-                limits,
+                rules,
                 fallback: value["fallback"]
                     .as_str()
                     .unwrap_or("minecraft:empty")
@@ -604,9 +624,10 @@ pub trait JigsawContext {
 pub enum Draws {
     /// JigsawPlacement's.
     Vanilla,
-    /// YUNG's API's `yungsapi:yung_jigsaw` (spec-yungsapi §2.1, §3.1): pools
-    /// are drawn by weight from their file entries, without replacement, and
-    /// an element at its `max_count` is skipped.
+    /// YUNG's API's `yungsapi:yung_jigsaw` (spec-yungsapi §2.1, §3.1, §3.2):
+    /// pools are drawn by weight from their file entries, without
+    /// replacement, priority entries first, and an element at its
+    /// `max_count` or too shallow is skipped.
     Yung,
 }
 
@@ -615,14 +636,28 @@ enum Candidates {
     /// Vanilla: the target pool's weight-expanded elements, then the
     /// fallback's, each shuffled up front.
     Listed(std::vec::IntoIter<Arc<PoolElement>>),
-    /// YUNG's: weighted picks from each pool in turn (the fallback's only
-    /// once the target's are spent), each pool's entries shuffled when it
-    /// is reached.
+    /// YUNG's: picks from each pool in turn (the fallback's only once the
+    /// target's are spent), each pool's entries shuffled when it is
+    /// reached: its priority entries in that order, then weighted picks
+    /// from the others.
     Weighted {
         pools: Vec<Arc<Pool>>,
-        current: Option<(Arc<Pool>, Vec<usize>)>,
+        current: Option<Drawing>,
     },
 }
+/// A YUNG pool being drawn: entries (indices into `raw`) not tried yet.
+struct Drawing {
+    pool: Arc<Pool>,
+    priority: VecDeque<usize>,
+    others: Vec<usize>,
+}
+/// An element to try.
+struct Pick {
+    element: Arc<PoolElement>,
+    /// Its YUNG name, counted toward `max_count` when it is placed.
+    name: Option<Arc<str>>,
+    ignore_bounds: bool,
+}
 impl Candidates {
     fn new(
         draws: Draws,
@@ -650,37 +685,62 @@ impl Candidates {
             },
         }
     }
-    /// The next element to try, with its YUNG name and limit.
+    /// The next element to try for a jigsaw of a piece at `depth`.
     fn next(
         &mut self,
         counts: &HashMap<Arc<str>, i32>,
+        depth: i32,
         random: &mut impl RandomSource,
-    ) -> Option<(Arc<PoolElement>, Option<Arc<str>>)> {
+    ) -> Option<Pick> {
         match self {
-            Self::Listed(elements) => elements.next().map(|e| (e, None)),
+            Self::Listed(elements) => elements.next().map(|element| Pick {
+                element,
+                name: None,
+                ignore_bounds: false,
+            }),
             Self::Weighted { pools, current } => loop {
-                let (pool, order) = match current {
-                    Some((pool, order)) if !order.is_empty() => (pool, order),
+                let drawing = match current {
+                    Some(d) if !d.priority.is_empty() || !d.others.is_empty() => d,
                     _ => {
                         let pool = pools.pop()?;
                         let mut order: Vec<usize> = (0..pool.raw.len()).collect();
                         shuffle(&mut order, random);
-                        *current = Some((pool, order));
+                        let (priority, others): (Vec<usize>, _) =
+                            order.into_iter().partition(|&i| pool.rules[i].priority);
+                        *current = Some(Drawing {
+                            pool,
+                            priority: priority.into(),
+                            others,
+                        });
                         continue;
                     }
                 };
-                let Some(at) = pool.weighted(order, random) else {
-                    order.clear();
-                    continue;
+                let entry = match drawing.priority.pop_front() {
+                    Some(entry) => entry,
+                    None => {
+                        let Some(at) = drawing.pool.weighted(&drawing.others, random) else {
+                            drawing.others.clear();
+                            continue;
+                        };
+                        drawing.others.remove(at)
+                    }
                 };
-                let entry = order.remove(at);
-                let limit = pool.limits[entry].clone();
-                if let Some((name, max)) = &limit
+                // spec-yungsapi §3.1 item 8: an empty element ends the
+                // jigsaw (the caller's), then `max_count`, then the depth.
+                let rules = &drawing.pool.rules[entry];
+                if let Some((name, max)) = &rules.limit
                     && counts.get(name).copied().unwrap_or(0) >= *max
                 {
                     continue;
                 }
-                return Some((pool.raw[entry].0.clone(), limit.map(|(name, _)| name)));
+                if depth < rules.min_depth {
+                    continue;
+                }
+                return Some(Pick {
+                    element: drawing.pool.raw[entry].0.clone(),
+                    name: rules.limit.as_ref().map(|(name, _)| name.clone()),
+                    ignore_bounds: rules.ignore_bounds,
+                });
             },
         }
     }
@@ -760,10 +820,10 @@ pub fn assemble_drawing(
             .unwrap_or_else(|| name.to_owned())
     };
     let center_pool = pools.get(&alias(config.start_pool), resources, bindings)?;
-    let (rotation, element, limit) = match draws {
+    let (rotation, element) = match draws {
         Draws::Vanilla => {
             let rotation = Rotation::random(random);
-            (rotation, center_pool.random_template(random), None)
+            (rotation, center_pool.random_template(random))
         }
         // The entries shuffled, then the rotation, then a weighted pick in
         // the shuffled order.
@@ -772,9 +832,7 @@ pub fn assemble_drawing(
             shuffle(&mut order, random);
             let rotation = Rotation::random(random);
             let entry = order[center_pool.weighted(&order, random)?];
-            let (element, _) = &center_pool.raw[entry];
-            let limit = center_pool.limits[entry].clone().map(|(name, _)| name);
-            (rotation, element.clone(), limit)
+            (rotation, center_pool.raw[entry].0.clone())
         }
     };
     if matches!(element.as_ref(), PoolElement::Empty) {
@@ -829,10 +887,10 @@ pub fn assemble_drawing(
         let low_y = (cy - v).max(context.min_y() + config.padding[0]);
         let high_y = (cy + v + 1).min(context.max_y() + 1 - config.padding[1]);
         let container = BoundingBox::new([cx - h, low_y, cz - h], [cx + h, high_y - 1, cz + h]);
-        let counts = limit.into_iter().map(|name| (name, 1)).collect();
+        // The start does not count toward `max_count` (spec-yungsapi §3).
         add_children_drawing(
             draws,
-            counts,
+            HashMap::new(),
             config,
             context,
             pools,
@@ -995,7 +1053,12 @@ impl Placer<'_, '_> {
                 depth != self.config.max_depth,
                 random,
             );
-            while let Some((target, name)) = candidates.next(&self.counts, random) {
+            while let Some(Pick {
+                element: target,
+                name,
+                ignore_bounds,
+            }) = candidates.next(&self.counts, depth, random)
+            {
                 if matches!(target.as_ref(), PoolElement::Empty) {
                     break;
                 }
@@ -1057,7 +1120,7 @@ impl Placer<'_, '_> {
                             let size = (expand_to + 1).max(target_box.max[1] - target_box.min[1]);
                             target_box.max[1] = target_box.max[1].max(target_box.min[1] + size);
                         }
-                        if !children_free.borrow().fits(&target_box) {
+                        if !ignore_bounds && !children_free.borrow().fits(&target_box) {
                             continue;
                         }
                         children_free.borrow_mut().removed.push(target_box);
diff --git a/tools/test_structure_layout_parity.py b/tools/test_structure_layout_parity.py
index d16002424..e091d12df 100644
--- a/tools/test_structure_layout_parity.py
+++ b/tools/test_structure_layout_parity.py
@@ -23,8 +23,16 @@ a fresh work folder, and an overlay of the 26.3 resources adds the carried struc
 processor lists, biome tags and templates. The jars are the player's; nothing of them enters the
 repository.
 
-usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons] [--filter REGEX] [--verbose]
+The `yung-probe` profiles check YUNG's API's draws with a data pack of the spec team's own (spec-yungsapi
+§3, probe experiments e1-e9: fallback, max_count, empty elements, min_required_depth, ignore_bounds,
+max_y, is_priority). The pack is carried as one more mod, built at run time from the oracle's profile file
+(`.local/structure-oracle/profiles/<profile>.json`), and its starts are read from the oracle's census of
+every start (`all_starts`).
+
+usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons|yung-probe|yung-probe2]
+                                       [--filter REGEX] [--verbose]
 """
+import base64
 import argparse
 import gzip
 import json
@@ -33,6 +41,7 @@ import re
 import shutil
 import subprocess
 import sys
+import zipfile
 from pathlib import Path
 
 try:
@@ -49,6 +58,9 @@ PROFILES = {
     'betterdungeons': {'side': 'pieces', 'mods': {'yungsapi': 'YungsApi-1.21.1-NeoForge-5.1.9.jar',
                                                   'betterdungeons': 'YungsBetterDungeons-1.21.1-NeoForge-5.1.4.jar'},
                        'carry': ['betterdungeons'], 'structures': r'^betterdungeons:(small|skeleton|zombie)_dungeon$'},
+    **{name: {'side': 'all_starts', 'mods': {'yungsapi': 'YungsApi-1.21.1-NeoForge-5.1.9.jar'},
+              'packs': {'probe': name}, 'carry': ['probe'], 'structures': r'^probe:'}
+       for name in ['yung-probe', 'yung-probe2']},
 }
 BUNDLES = {'structure': 'structures', 'structure_set': 'structure_sets', 'template_pool': 'template_pools',
            'processor_list': 'processor_lists'}
@@ -95,14 +107,29 @@ CENSUS = ['blockstates', 'item_models', 'recipes', 'loot_tables', 'tags', 'world
           'textures', 'sounds', 'classes', 'mixin_configs']
 
 
-def carry(profile, mods, carried):
-    """`horizon-port-pack carry` of the profile's mods; the carried mods' data folders."""
+def pack_jar(work, mod, profile):
+    """The data pack an oracle profile added to its world, as a jar of mod `mod`."""
+    spec = json.loads((ORACLE / 'profiles' / f'{profile}.json').read_text())
+    files = {**spec['config_files'], **{path: base64.b64decode(data) for path, data in spec.get('binary_files', {}).items()}}
+    jar = work / f'{mod}.jar'
+    with zipfile.ZipFile(jar, 'w') as z:
+        for path, content in files.items():
+            parts = Path(path).parts
+            if parts[:2] == ('world', 'datapacks') and len(parts) > 3:
+                z.writestr(str(Path(*parts[3:])), content)
+    return jar
+
+
+def carry(profile, mods, carried, packs=None):
+    """`horizon-port-pack carry` of the profile's mods and packs; the carried mods' data folders."""
     work = lab.LOCAL / 'structure-layout' / profile / 'work'
     shutil.rmtree(work, ignore_errors=True)
     work.mkdir(parents=True)
+    mods = {key: str(JARS / jar) for key, jar in mods.items()}
+    mods.update({key: str(pack_jar(work, key, name)) for key, name in (packs or {}).items()})
     records = [{'key': key, 'name': key, 'version': '', 'path': jar, 'tier': 'data', 'confidence': 'known',
                 'class': 'content' if key in carried else 'library', 'source': 'file', 'license': '',
-                'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': str(JARS / jar),
+                'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': jar,
                 'info': {'mod_id': key, 'name': key, 'version': '', 'license': '', 'depends': [],
                          'census': dict.fromkeys(CENSUS, 0)}}
                for key, jar in mods.items()]
@@ -188,6 +215,15 @@ def compare(expected, actual):
     return None
 
 
+def census_starts(oracle):
+    """The oracle's census of every start (`all_starts`), as `structures` entries with their `all_starts`."""
+    for chunk in oracle['all_starts']:
+        for start in chunk['starts']:
+            if 'children' in start:
+                yield {'id': start['id'], 'dimension': chunk['dimension'], 'start_chunk': chunk['chunk'],
+                       'all_starts': start['children']}
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('--profile', default='lithostitched', choices=sorted(PROFILES))
@@ -199,20 +235,23 @@ def main():
         print(f'SKIP: no oracle results in {ORACLE / args.profile} (see this file\'s docstring)')
         return 0
     profile = PROFILES[args.profile]
-    missing = [jar for jar in profile['mods'].values() if not (JARS / jar).exists()]
+    missing = [str(JARS / jar) for jar in profile['mods'].values() if not (JARS / jar).exists()]
+    missing += [str(ORACLE / 'profiles' / f'{name}.json') for name in profile.get('packs', {}).values()
+                if not (ORACLE / 'profiles' / f'{name}.json').exists()]
     if missing:
-        print(f'SKIP: mod jars not in {JARS}: {", ".join(missing)}')
+        print(f'SKIP: not found: {", ".join(missing)}')
         return 0
     resources = lab.RESOURCES
     if profile['carry']:
-        resources = overlay(args.profile, carry(args.profile, profile['mods'], profile['carry']))
+        data = carry(args.profile, profile['mods'], profile['carry'], profile.get('packs'))
+        resources = overlay(args.profile, data)
     binary = probe_binary()
     matched, known, failed = 0, 0, []
     for path in results:
         oracle = json.load(gzip.open(path))
         seed = oracle['seed']
         by_dimension = {}
-        for start in oracle['structures']:
+        for start in oracle['structures'] if profile['side'] != 'all_starts' else census_starts(oracle):
             if start.get(profile['side']) is None or not re.search(args.filter, start['id']) \
                     or not re.search(profile['structures'] or '', start['id']):
                 continue

From 90ae953747a746cc32b20bc1cf4cf73cd21ce8c0 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:21:48 +0100
Subject: [PATCH 041/270] Rockets: collapse the boost's nested if
 (clippy::collapsible_if)

Verify failed on it with warnings denied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/game/remote_projectiles.rs            | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/crates/horizon-client/src/game/remote_projectiles.rs b/crates/horizon-client/src/game/remote_projectiles.rs
index dbf7f3ccf..056efa7c3 100644
--- a/crates/horizon-client/src/game/remote_projectiles.rs
+++ b/crates/horizon-client/src/game/remote_projectiles.rs
@@ -239,20 +239,20 @@ impl Game<'_> {
         for r in &mut self.rockets {
             let id = r.id;
             r.remote_step(|at| step(id, at));
-            if me.is_some() && r.attached_to == me {
-                if let Some(p) = self.player.as_mut()
-                    && p.fall_flying
-                {
-                    let look = view_vector(self.yaw, self.pitch);
-                    let m = p.velocity;
-                    p.velocity = Vec3::new(
-                        m.x + look[0] * 0.1 + (look[0] * 1.5 - m.x) * 0.5,
-                        m.y + look[1] * 0.1 + (look[1] * 1.5 - m.y) * 0.5,
-                        m.z + look[2] * 0.1 + (look[2] * 1.5 - m.z) * 0.5,
-                    );
-                    r.position = p.position;
-                    r.velocity = p.velocity;
-                }
+            if me.is_some()
+                && r.attached_to == me
+                && let Some(p) = self.player.as_mut()
+                && p.fall_flying
+            {
+                let look = view_vector(self.yaw, self.pitch);
+                let m = p.velocity;
+                p.velocity = Vec3::new(
+                    m.x + look[0] * 0.1 + (look[0] * 1.5 - m.x) * 0.5,
+                    m.y + look[1] * 0.1 + (look[1] * 1.5 - m.y) * 0.5,
+                    m.z + look[2] * 0.1 + (look[2] * 1.5 - m.z) * 0.5,
+                );
+                r.position = p.position;
+                r.velocity = p.velocity;
             }
         }
         for c in &mut self.crystals {

From abe7047d1947e12225a8baa120b8f4b86ace0a70 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:32:10 +0100
Subject: [PATCH 042/270] Shader packs, clean room 33: clouds

A pack with gbuffers_clouds draws Horizon's cloud geometry itself (spec
2.3, OQ-3: no fallback), blended, after the opaque world. Horizon's own
cloud draw is skipped then, also when the pack's program writes nothing
(BSL and Complementary hide vanilla clouds that way). Without a pack the
cloud draw is unchanged.

The translator now rewrites a bare `discard;` or `return;` to
`if (true) discard;` / `if (true) return;`, so code a pack leaves after
it stays reachable for naga ("Expression not visited"). This also fixes
Complementary Unbound's gbuffers_skytextured.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1;
no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              | 19 ++++-
 .../horizon-client/src/gfx/pack_entities.rs   | 35 ++++++++
 crates/horizon-client/src/gfx/pack_post.rs    | 83 ++++++++++++++++++-
 crates/horizon-shaders/src/post.rs            | 23 ++++-
 crates/horizon-shaders/src/translate/mod.rs   | 29 +++++++
 .../horizon-shaders/src/translate/rewrite.rs  |  7 ++
 crates/horizon-shaders/tests/real_packs.rs    |  3 +-
 7 files changed, 194 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index d354b9bba..87dc797ba 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -490,6 +490,8 @@ pub struct Renderer {
     pack_post: Option<(i32, Option<pack_post::PackPost>)>,
     /// The entity vertices Horizon draws itself while a shader pack draws the others.
     pack_entity_rest: Vec<Vertex>,
+    /// Set 1 of the cloud pipeline, for a shader pack's `gbuffers_clouds`.
+    cloud_bindings: wgpu::BindGroupLayout,
     /// The block sprites as one atlas, while a shader pack is loaded.
     pack_atlas: Option<pack_atlas::PackAtlas>,
     /// The pack's terrain program reads flat draws' vertices (`pack_terrain_inputs`).
@@ -2350,6 +2352,7 @@ impl Renderer {
             world_post,
             pack_post: None,
             pack_entity_rest: Vec::new(),
+            cloud_bindings,
             pack_atlas: None,
             pack_terrain_flat: false,
             hud,
@@ -2813,6 +2816,7 @@ impl Renderer {
                     .atlas_texture
                     .as_ref()
                     .map(|t| t.create_view(&Default::default())),
+                clouds: Some(&self.cloud_bindings),
             };
             pack_post::PackPost::new(
                 &self.device,
@@ -2837,6 +2841,7 @@ impl Renderer {
             sky: Some(pack_sky::inputs()),
             celestial: Some(pack_sky::celestial_inputs()),
             entities: Some(pack_entities::inputs()),
+            clouds: Some(pack_entities::cloud_inputs()),
         }
     }
 
@@ -3786,6 +3791,12 @@ impl Renderer {
                 .as_ref()
                 .and_then(|p| p.1.as_ref())
                 .is_some_and(|p| p.has_water());
+        let pack_draws_clouds = pack_post
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_clouds());
         let scaled = self.world_post.prepare(
             &self.device,
             [self.config.width, self.config.height],
@@ -4066,7 +4077,7 @@ impl Renderer {
                     0..1,
                 );
             }
-            if cloud_quads > 0 {
+            if cloud_quads > 0 && !pack_draws_clouds {
                 pass.set_pipeline(&self.cloud_pipeline);
                 pass.set_bind_group(0, &self.entity_group, &[]);
                 pass.set_bind_group(1, &self.cloud_group, &[]);
@@ -4127,6 +4138,12 @@ impl Renderer {
                         }
                     }
                 };
+            post.set_clouds(pack_draws_clouds.then(|| pack_post::Clouds {
+                vertices: self.cloud_buffer.clone(),
+                group: self.cloud_group.clone(),
+                indices: self.indices.clone(),
+                quads: cloud_quads,
+            }));
             post.run(
                 &self.device,
                 &self.queue,
diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
index 6f7de5fe1..b06c45af6 100644
--- a/crates/horizon-client/src/gfx/pack_entities.rs
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -104,6 +104,41 @@ pub fn inputs() -> horizon_shaders::GbuffersInputs {
     }
 }
 
+/// What `gbuffers_clouds` reads from the clouds' mesh (entity vertices, `vs_cloud`): the
+/// position moved by the clouds' offset, the colour of the face's shade from their palette,
+/// full sky light. Set 1 holds the clouds' uniform (`clouds::Uniform`).
+pub fn cloud_inputs() -> horizon_shaders::GbuffersInputs {
+    let declarations = "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in vec2 hz_v_uv;\n\
+         layout(location = 2) in uint hz_v_overlay;\nlayout(location = 3) in vec4 hz_v_color;\n\
+         layout(location = 4) in uvec4 hz_v_light;\nlayout(location = 5) in vec4 hz_v_normal;\n\
+         layout(set = 1, binding = 0) uniform HzCloud { vec4 hz_cloud_offset; vec4 hz_cloud_colors[4]; };\n"
+        .to_owned();
+    let body = "    hz_Vertex = vec4(hz_v_pos + hz_cloud_offset.xyz, 1.0);\n    \
+         hz_MultiTexCoord0 = vec4(hz_v_uv, 0.0, 1.0);\n    \
+         hz_MultiTexCoord1 = vec4(0.0, 240.0, 0.0, 1.0);\n    \
+         hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+         hz_Color = hz_cloud_colors[min(hz_v_light.x, 3u)];\n    \
+         hz_Normal = dot(hz_v_normal.xyz, hz_v_normal.xyz) > 0.01 ? normalize(hz_v_normal.xyz) : vec3(0.0, 1.0, 0.0);\n"
+        .to_owned();
+    let attributes = [
+        ("vaPosition", "hz_Vertex.xyz"),
+        ("vaUV0", "hz_v_uv"),
+        ("vaUV2", "ivec2(0, 240)"),
+        ("vaColor", "hz_Color"),
+        ("vaNormal", "hz_Normal"),
+    ];
+    horizon_shaders::GbuffersInputs {
+        declarations,
+        body,
+        attributes: attributes
+            .iter()
+            .map(|&(n, v)| (n.to_owned(), v.to_owned()))
+            .collect(),
+        after: String::new(),
+        alpha_test: None,
+    }
+}
+
 /// `entityColor` for a run whose first quad carries overlay code `overlay`: the hurt red or a
 /// white flash, its alpha how much of that colour shows over the entity (vanilla mixes the
 /// overlay texel's colour in by one minus the texel's alpha).
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index fc372ab95..19ede8302 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -202,6 +202,17 @@ pub(super) struct World<'a> {
     pub block_ids: &'a [i32],
     /// The atlas of the sun and moon's sprites.
     pub celestial: Option<wgpu::TextureView>,
+    /// Set 1 of the clouds' draw: their offset and palette.
+    pub clouds: Option<&'a wgpu::BindGroupLayout>,
+}
+
+/// This frame's clouds, when the pack draws them: their vertices, uniform, quad indices and
+/// quad count.
+pub(super) struct Clouds {
+    pub vertices: wgpu::Buffer,
+    pub group: wgpu::BindGroup,
+    pub indices: wgpu::Buffer,
+    pub quads: u32,
 }
 
 pub struct PackPost {
@@ -215,6 +226,12 @@ pub struct PackPost {
     sky: Option<Sky>,
     /// What draws entities and block entities, after terrain, and their vertices.
     entities: Option<Entities>,
+    /// What draws the clouds, after entities, and this frame's clouds.
+    clouds: Option<Pass>,
+    cloud_draw: Option<Clouds>,
+    /// The pack has `gbuffers_clouds`, even one that writes nothing (a pack drawing its own
+    /// clouds discards vanilla's): the game's clouds are not drawn.
+    hides_clouds: bool,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -944,6 +961,19 @@ impl PackPost {
                 passes: entity_passes,
                 late,
             });
+        let cloud_geometry = world.clouds.map(|layout| Geometry {
+            buffers: &entity_buffers,
+            table: Some(layout),
+            depth_write: true,
+            atlas: world.celestial.clone(),
+            ids: None,
+            cull: false,
+        });
+        let hides_clouds = post.clouds.is_some() && cloud_geometry.is_some();
+        let clouds = post
+            .clouds
+            .zip(cloud_geometry.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)));
         // Developers' aid: `HORIZON_SHADER_PACK_SKIP=composite,final` leaves programs out.
         let skip = std::env::var("HORIZON_SHADER_PACK_SKIP").unwrap_or_default();
         let passes: Vec<Pass> = post
@@ -972,6 +1002,9 @@ impl PackPost {
             "translucent entities",
             "particles",
         ];
+        if let Some(c) = &clouds {
+            notes.push(format!("clouds draw with {}", c.name));
+        }
         for (part, pass) in entities.iter().flat_map(|e| parts.iter().zip(&e.passes)) {
             if let Some(p) = pass {
                 notes.push(format!("{part} draw with {}", p.name));
@@ -995,6 +1028,7 @@ impl PackPost {
                 .flat_map(|s| s.basic.iter().chain(&s.textured))
                 .chain(&terrain)
                 .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
+                .chain(&clouds)
                 .chain(&water)
                 .find(touched)
                 .map(|_| true)
@@ -1011,6 +1045,7 @@ impl PackPost {
             || water.is_some()
             || sky.is_some()
             || entities.is_some()
+            || clouds.is_some()
             || passes.iter().any(|p| {
                 p.samplers
                     .iter()
@@ -1107,6 +1142,9 @@ impl PackPost {
             water,
             sky,
             entities,
+            clouds,
+            cloud_draw: None,
+            hides_clouds,
             depth1,
             mipped,
             mips_valid: 0,
@@ -1523,6 +1561,45 @@ impl PackPost {
         }
         self.draw_terrain(device, queue, encoder, size, false, terrain);
         self.draw_entities(device, queue, encoder, size, false);
+        self.draw_clouds(device, queue, encoder, size);
+    }
+
+    /// The clouds `set_clouds` gave for this frame, with `gbuffers_clouds`.
+    fn draw_clouds(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+    ) {
+        let (Some(mut pass), Some(clouds)) = (self.clouds.take(), self.cloud_draw.take()) else {
+            return;
+        };
+        let group = self.bind(device, queue, &mut pass, size);
+        {
+            let mut rp = self.begin(encoder, &pass);
+            rp.set_pipeline(&pass.pipeline);
+            rp.set_bind_group(0, &group, &[]);
+            rp.set_bind_group(1, &clouds.group, &[]);
+            if pass.draw {
+                self.draws.bind(&mut rp, "CLOUDS");
+            }
+            rp.set_vertex_buffer(0, clouds.vertices.slice(..));
+            rp.set_index_buffer(clouds.indices.slice(..), wgpu::IndexFormat::Uint32);
+            rp.draw_indexed(0..clouds.quads * 6, 0, 0..1);
+        }
+        self.mips_valid &= !pass.written;
+        self.clouds = Some(pass);
+    }
+
+    /// Whether the pack draws the clouds itself (or hides them).
+    pub fn has_clouds(&self) -> bool {
+        self.hides_clouds
+    }
+
+    /// The clouds to draw this frame (`None`: none).
+    pub fn set_clouds(&mut self, clouds: Option<Clouds>) {
+        self.cloud_draw = clouds.filter(|c| c.quads > 0);
     }
 
     /// Translucent terrain, then the entity parts drawn after deferred.
@@ -1842,8 +1919,10 @@ impl PackPost {
         let mut passes = std::mem::take(&mut self.passes);
         let mut seen = (false, false);
         let mut shown = false;
-        let mut terrain_drawn =
-            self.terrain.is_none() && self.sky.is_none() && self.entities.is_none();
+        let mut terrain_drawn = self.terrain.is_none()
+            && self.sky.is_none()
+            && self.entities.is_none()
+            && self.clouds.is_none();
         let late_entities = self.entities.as_ref().is_some_and(|e| {
             e.passes
                 .iter()
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index a31cf5ce7..2e163560f 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -120,6 +120,9 @@ const BLOCK: [&str; 5] = [
     "gbuffers_basic",
 ];
 
+/// `gbuffers_clouds`: no fallback, the game draws its clouds otherwise (OQ-3).
+const CLOUDS: [&str; 1] = ["gbuffers_clouds"];
+
 /// `gbuffers_entities_translucent` and its fallbacks (2.3).
 const ENTITIES_TRANSLUCENT: [&str; 5] = [
     "gbuffers_entities_translucent",
@@ -191,6 +194,8 @@ pub struct Post {
     pub entities_translucent: Option<PostProgram>,
     /// What draws particles.
     pub particles: Option<PostProgram>,
+    /// What draws the game's clouds.
+    pub clouds: Option<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
     pub translucent_late: bool,
     /// Particles draw after deferred (`particles.ordering`, `particles.before.deferred`, 3.2).
@@ -222,6 +227,8 @@ pub struct GameInputs {
     pub celestial: Option<GbuffersInputs>,
     /// Entities and block entities (one vertex format).
     pub entities: Option<GbuffersInputs>,
+    /// The clouds' mesh.
+    pub clouds: Option<GbuffersInputs>,
 }
 
 /// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
@@ -246,6 +253,7 @@ pub fn load_post(
         block: None,
         entities_translucent: None,
         particles: None,
+        clouds: None,
         translucent_late: false,
         particles_late: false,
         custom: Custom::parse(properties),
@@ -342,6 +350,15 @@ pub fn load_post(
     let mut gbuffers_dyn = |names: &[&str], i: &GbuffersInputs| gbuffers(names, Group::Gbuffers, i);
     let entities_translucent = translucent(&ENTITIES_TRANSLUCENT, 0.0, &mut gbuffers_dyn);
     let particles = translucent(&PARTICLES, 0.1, &mut gbuffers_dyn);
+    // Clouds blend, as vanilla's do (OQ-23).
+    let clouds = inputs
+        .clouds
+        .as_ref()
+        .and_then(|i| gbuffers_dyn(&CLOUDS, i));
+    let clouds = clouds.map(|mut p| {
+        p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
+        p
+    });
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -361,6 +378,7 @@ pub fn load_post(
     loader.post.block = block;
     loader.post.entities_translucent = entities_translucent;
     loader.post.particles = particles;
+    loader.post.clouds = clouds;
     let flag = |key: &str| properties.get(key).map(|v| v.trim() == "true");
     loader.post.translucent_late = flag("separateEntityDraws").unwrap_or(false);
     // `after` when the pack has a deferred program, else `mixed`; ours are all translucent, so
@@ -648,7 +666,8 @@ mod tests {
             terrain: Some(inputs.clone()),
             sky: Some(inputs.clone()),
             celestial: Some(inputs.clone()),
-            entities: Some(inputs),
+            entities: Some(inputs.clone()),
+            clouds: Some(inputs),
         };
         let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
@@ -696,6 +715,8 @@ mod tests {
         );
         assert_eq!(particles.blend, Some(TRANSLUCENT_BLEND));
         assert!(post.particles_late && !post.translucent_late);
+        // gbuffers_clouds has no fallback (OQ-3): without it the game draws its clouds.
+        assert!(post.clouds.is_none());
         let ordering = Properties::parse(
             "particles.ordering = before\nseparateEntityDraws = true\n",
             &macros,
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 5d0bfee3b..2f0163f94 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -702,6 +702,35 @@ mod tests {
         }
     }
 
+    /// Code after an unconditional `discard` (BSL's `gbuffers_clouds` with its own clouds on)
+    /// or `return;` still makes a valid module.
+    #[test]
+    fn code_after_discard_or_return_translates() {
+        let vsh = "#version 120\nvoid main() { gl_Position = ftransform(); }\n";
+        for fsh in [
+            "#version 120\nuniform sampler2D texture;\nvoid main() {\n    discard;\n    vec4 c = texture2D(texture, vec2(0.5));\n    gl_FragData[0] = c;\n}\n",
+            "#version 120\nvoid main() {\n    gl_FragData[0] = vec4(1.0);\n    return;\n    gl_FragData[0] = vec4(0.5);\n}\n",
+        ] {
+            let files = [
+                ("shaders/gbuffers_clouds.vsh", vsh),
+                ("shaders/gbuffers_clouds.fsh", fsh),
+            ];
+            let pack = Pack::from_zip_bytes("P.zip", zip(&files)).unwrap();
+            let m = Macros::standard();
+            let inputs = GbuffersInputs {
+                body: "    hz_Vertex = vec4(0.0, 0.0, 0.0, 1.0);\n".into(),
+                ..Default::default()
+            };
+            translate_gbuffers(
+                &preprocess(&pack, "gbuffers_clouds.vsh", &m),
+                &preprocess(&pack, "gbuffers_clouds.fsh", &m),
+                Target::Buffers,
+                &inputs,
+            )
+            .unwrap_or_else(|e| panic!("{fsh}: {e:?}"));
+        }
+    }
+
     #[test]
     fn the_alpha_test_discards_below_its_reference() {
         assert_eq!(
diff --git a/crates/horizon-shaders/src/translate/rewrite.rs b/crates/horizon-shaders/src/translate/rewrite.rs
index 85cb0fcd9..4101b1642 100644
--- a/crates/horizon-shaders/src/translate/rewrite.rs
+++ b/crates/horizon-shaders/src/translate/rewrite.rs
@@ -190,6 +190,13 @@ impl Stage<'_> {
             }
             let replaced: Option<String> = match t {
                 "main" if depth == 0 && called => Some("hz_main".into()),
+                // naga's frontend leaves the code after an unconditional `discard` or `return;`
+                // unreachable but half-built (a module that fails validation): behind an `if`
+                // it stays reachable as far as naga knows.
+                "discard" => Some("if (true) discard".into()),
+                "return" if next(i).is_some_and(|j| self.tokens[j] == ";") => {
+                    Some("if (true) return".into())
+                }
                 // GLSL's `modf`, which naga's frontend lacks.
                 "modf" if called => Some("hz_modf".into()),
                 "texture2D" | "texture1D" | "texture3D" | "textureCube" if called => {
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index b77b3b158..2f6aff111 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -173,7 +173,8 @@ fn real_packs_read() {
                 terrain: Some(terrain.clone()),
                 sky: Some(terrain.clone()),
                 celestial: Some(terrain.clone()),
-                entities: Some(terrain),
+                entities: Some(terrain.clone()),
+                clouds: Some(terrain),
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(

From e7f85e5bfd55783f91348a7f9c6701d201e1cda3 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:44:31 +0100
Subject: [PATCH 043/270] Zip: test the streamed shapes Java 25's ZipFile opens

ZipFile refuses a 0xFFFFFFFF size without its Zip64 extra field ("invalid
zip64 extra len size"), so the test builds both shapes it accepts: real
sizes, and the sentinel with the extra (the zip crate reads the real size
from it). With every accepted shape carrying a real size, the inflate
limit needs no special case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/zip.rs | 105 ++++++++++++++++---------------
 1 file changed, 56 insertions(+), 49 deletions(-)

diff --git a/crates/horizon-client/src/zip.rs b/crates/horizon-client/src/zip.rs
index 17442858e..7f8c2a614 100644
--- a/crates/horizon-client/src/zip.rs
+++ b/crates/horizon-client/src/zip.rs
@@ -52,14 +52,7 @@ impl Zip {
         match method {
             CompressionMethod::Stored => Ok(raw),
             CompressionMethod::Deflated => {
-                // Streamed archives write 0xFFFFFFFF for the uncompressed
-                // size; bound the output instead of trusting it.
-                let limit = if size == u32::MAX as usize {
-                    1 << 30
-                } else {
-                    size.max(1) * 2 + 1024
-                };
-                miniz_oxide::inflate::decompress_to_vec_with_limit(&raw, limit)
+                miniz_oxide::inflate::decompress_to_vec_with_limit(&raw, size.max(1) * 2 + 1024)
                     .map_err(|_| invalid("corrupt deflate stream"))
             }
             _ => Err(invalid("unsupported zip compression")),
@@ -74,10 +67,10 @@ const END_HEADER: usize = 22;
 /// reading the central directory from `cenpos` to `cenpos + cenlen` whatever
 /// they say; the `zip` crate insists the record agrees with the directory.
 /// Packs written while streaming (Nexo serves them for gommehd.net, for one)
-/// leave every file's local header a stub, the uncompressed sizes at
-/// 0xFFFFFFFF and the END counts and disk number at 0 and 0xFFFF — archives
-/// Java opens but the crate refuses. Count the real directory entries and
-/// normalize the record so it does not look multi-disk or empty.
+/// leave every file's local header a stub and the END counts and disk number
+/// at 0 and 0xFFFF: archives Java opens but the crate refuses. Count the real
+/// directory entries and normalize the record so it does not look multi-disk
+/// or empty.
 fn normalize_end(data: &mut [u8]) {
     if data.len() < END_HEADER {
         return;
@@ -270,45 +263,59 @@ mod tests {
     }
 
     /// A pack as a streaming writer serves it (Nexo/gommehd.net): every
-    /// local header is a stub, the uncompressed sizes are 0xFFFFFFFF and the
-    /// END record's counts and disk numbers are wrong. Java's ZipFile opens
-    /// it anyway; so do we.
+    /// local header is a 30-byte stub and the END record's disk number and
+    /// counts are wrong. Java 25's `ZipFile` opens it, with each size either
+    /// in the directory or as 0xFFFFFFFF plus its Zip64 extra field (without
+    /// that field it refuses the archive: "invalid zip64 extra len size").
     #[test]
     fn reads_a_streamed_archive() {
-        let files: [(&str, &[u8], bool); 2] = [
-            ("pack.mcmeta", b"{\"pack\":{}}", true),
-            ("a/b.txt", b"streamed entry", true),
-        ];
-        let mut out = Vec::new();
-        let mut central = Vec::new();
-        for (name, body, _) in files {
-            let data = miniz_oxide::deflate::compress_to_vec(body, 6);
-            let offset = out.len() as u32;
-            out.extend(0x0403_4b50u32.to_le_bytes());
-            out.extend([0; 26]);
-            out.extend(&data);
-            central.extend(0x0201_4b50u32.to_le_bytes());
-            central.extend([20, 0, 20, 0, 0, 0]);
-            central.extend(8u16.to_le_bytes());
-            central.extend([0; 8]);
-            central.extend((data.len() as u32).to_le_bytes());
-            central.extend(u32::MAX.to_le_bytes());
-            central.extend((name.len() as u16).to_le_bytes());
-            central.extend([0; 12]);
-            central.extend(offset.to_le_bytes());
-            central.extend(name.as_bytes());
+        for zip64 in [false, true] {
+            let files: [(&str, &[u8]); 2] = [
+                ("pack.mcmeta", b"{\"pack\":{}}"),
+                ("a/b.txt", b"streamed entry"),
+            ];
+            let mut out = Vec::new();
+            let mut central = Vec::new();
+            for (name, body) in files {
+                let data = miniz_oxide::deflate::compress_to_vec(body, 6);
+                let offset = out.len() as u32;
+                out.extend(0x0403_4b50u32.to_le_bytes());
+                out.extend([0; 26]);
+                out.extend(&data);
+                let extra: Vec<u8> = if zip64 {
+                    [1u16, 8]
+                        .iter()
+                        .flat_map(|v| v.to_le_bytes())
+                        .chain((body.len() as u64).to_le_bytes())
+                        .collect()
+                } else {
+                    Vec::new()
+                };
+                central.extend(0x0201_4b50u32.to_le_bytes());
+                central.extend([20, 0, 20, 0, 0, 0]);
+                central.extend(8u16.to_le_bytes());
+                central.extend([0; 8]);
+                central.extend((data.len() as u32).to_le_bytes());
+                central.extend(if zip64 { u32::MAX } else { body.len() as u32 }.to_le_bytes());
+                central.extend((name.len() as u16).to_le_bytes());
+                central.extend((extra.len() as u16).to_le_bytes());
+                central.extend([0; 10]);
+                central.extend(offset.to_le_bytes());
+                central.extend(name.as_bytes());
+                central.extend(extra);
+            }
+            let start = out.len() as u32;
+            out.extend(&central);
+            out.extend(0x0605_4b50u32.to_le_bytes());
+            out.extend(u16::MAX.to_le_bytes());
+            out.extend([0; 6]);
+            out.extend((central.len() as u32).to_le_bytes());
+            out.extend(start.to_le_bytes());
+            out.extend([0; 2]);
+            let zip = Zip::from_bytes(out).unwrap();
+            assert_eq!(zip.names().collect::<Vec<_>>(), ["a/b.txt", "pack.mcmeta"]);
+            assert_eq!(zip.read("pack.mcmeta").unwrap(), b"{\"pack\":{}}");
+            assert_eq!(zip.read("a/b.txt").unwrap(), b"streamed entry");
         }
-        let start = out.len() as u32;
-        out.extend(&central);
-        out.extend(0x0605_4b50u32.to_le_bytes());
-        out.extend(u16::MAX.to_le_bytes());
-        out.extend([0; 6]);
-        out.extend((central.len() as u32).to_le_bytes());
-        out.extend(start.to_le_bytes());
-        out.extend([0; 2]);
-        let zip = Zip::from_bytes(out).unwrap();
-        assert_eq!(zip.names().collect::<Vec<_>>(), ["a/b.txt", "pack.mcmeta"]);
-        assert_eq!(zip.read("pack.mcmeta").unwrap(), b"{\"pack\":{}}");
-        assert_eq!(zip.read("a/b.txt").unwrap(), b"streamed entry");
     }
 }

From c2c8df4542b857911ec396e0430da5b46fdffdb1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:47:54 +0100
Subject: [PATCH 044/270] Mods: run a mod's commands on the next tick

Run while the mod's output was shown, a command's chat line reached the
mods again inside that call: a mod that answers a line with a command
that prints one recursed without end, and when a control-socket command
set the hook off, the mod's commands ran with the console's level. Queue
them for the next tick instead, where the player's own level applies (the
server already checks it on a server).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/mods.rs | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index c203d0ca2..8364a4d58 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -39,6 +39,11 @@ pub(super) struct ModsState {
     /// The chat's command tree while a running mod owns commands.
     #[cfg(feature = "mods")]
     tree: Option<Dispatcher>,
+    /// `command.run` lines for this window's own world, run on the next tick:
+    /// run at once, their chat lines would reach the mods while their output
+    /// is still being shown, and a mod answering its own lines would recurse.
+    #[cfg(feature = "mods")]
+    commands: Vec<String>,
 }
 impl ModsState {
     /// The chat's command tree: vanilla's, plus the running mods' commands.
@@ -283,6 +288,11 @@ impl Game<'_> {
     }
     /// A game tick.
     pub(super) fn tick_mods(&mut self) {
+        // Here, at the player's level: shown inside a console call (a control
+        // socket command set the hook off), they would run as the console.
+        for line in std::mem::take(&mut self.mods.commands) {
+            self.run_command(&line);
+        }
         if !self.mods.mods.is_running() {
             return;
         }
@@ -345,13 +355,13 @@ impl Game<'_> {
                 // Vanilla's commands only: a mod running a mod command could loop.
                 Output::Command { line } => {
                     let name = line.split(' ').next().unwrap_or_default();
-                    // As handle_chat_input, without the chat history.
                     if !vanilla_command(name) {
-                        // dropped
+                        // Dropped.
                     } else if self.remote.is_some() {
+                        // The server checks the player's permissions.
                         self.send_chat(&format!("/{line}"));
                     } else {
-                        self.run_command(&line);
+                        self.mods.commands.push(line);
                     }
                     continue;
                 }

From 5262effa7e4b13cd4737563dabeda3dc03e2f8af Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:48:35 +0100
Subject: [PATCH 045/270] cargo horizon-mod check: list the commands a mod runs

Main's check reports every output; the command capability adds one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/cargo-horizon-mod/src/check.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index 0294bec98..a1cb44c9e 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -214,6 +214,7 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
             Output::Feedback { text, error } => {
                 format!("{}: {text}", if error { "error" } else { "feedback" })
             }
+            Output::Command { line } => format!("command: /{line}"),
             Output::Stopped { reason, .. } => return Err(format!("it stopped: {reason}")),
         });
     }

From 173463acdf4fa73f15089567bf2152a235ed328e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:51:53 +0100
Subject: [PATCH 046/270] Shader packs, clean room 34: rain and snow

A pack with gbuffers_weather (or its fallbacks textured_lit, textured,
basic; spec 2.3) draws the game's rain and snow after translucent
terrain, blended, with vanilla's 0.1 alpha cut. The weather quads become
entity vertices with their UV animation applied on the CPU (the same
phase Horizon's weather shader computes; a test checks it against the
weather columns bit for bit), and rain and snow each read a copy of
their sprite, so the pack's `texture` repeats down the column as a
standalone texture would. The shared atlas gains COPY_SRC for that copy.

Without a pack nothing changes: Horizon's weather draw is skipped only
when the pack draws it.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1;
no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              |  37 ++-
 crates/horizon-client/src/gfx/pack_post.rs    |  98 ++++++-
 crates/horizon-client/src/gfx/pack_weather.rs | 264 ++++++++++++++++++
 crates/horizon-shaders/src/post.rs            |  36 ++-
 crates/horizon-shaders/tests/real_packs.rs    |   3 +-
 5 files changed, 433 insertions(+), 5 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_weather.rs

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 87dc797ba..e2e71e036 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -75,6 +75,7 @@ mod pack_post;
 mod pack_sky;
 mod pack_timing;
 pub mod pack_uniforms;
+mod pack_weather;
 mod page_runs;
 pub mod panorama;
 mod resident;
@@ -492,6 +493,8 @@ pub struct Renderer {
     pack_entity_rest: Vec<Vertex>,
     /// Set 1 of the cloud pipeline, for a shader pack's `gbuffers_clouds`.
     cloud_bindings: wgpu::BindGroupLayout,
+    /// Rain and snow handed to a shader pack's `gbuffers_weather`, once a pack draws them.
+    pack_weather: Option<pack_weather::PackWeather>,
     /// The block sprites as one atlas, while a shader pack is loaded.
     pack_atlas: Option<pack_atlas::PackAtlas>,
     /// The pack's terrain program reads flat draws' vertices (`pack_terrain_inputs`).
@@ -1481,7 +1484,10 @@ impl Renderer {
                 sample_count: 1,
                 dimension: wgpu::TextureDimension::D2,
                 format: wgpu::TextureFormat::Rgba8Unorm,
-                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
+                // COPY_SRC: a shader pack's weather copies the rain and snow sprites out.
+                usage: wgpu::TextureUsages::TEXTURE_BINDING
+                    | wgpu::TextureUsages::COPY_DST
+                    | wgpu::TextureUsages::COPY_SRC,
                 view_formats: &[],
             },
             wgpu::util::TextureDataOrder::LayerMajor,
@@ -2353,6 +2359,7 @@ impl Renderer {
             pack_post: None,
             pack_entity_rest: Vec::new(),
             cloud_bindings,
+            pack_weather: None,
             pack_atlas: None,
             pack_terrain_flat: false,
             hud,
@@ -2817,6 +2824,7 @@ impl Renderer {
                     .as_ref()
                     .map(|t| t.create_view(&Default::default())),
                 clouds: Some(&self.cloud_bindings),
+                weather: true,
             };
             pack_post::PackPost::new(
                 &self.device,
@@ -2842,6 +2850,7 @@ impl Renderer {
             celestial: Some(pack_sky::celestial_inputs()),
             entities: Some(pack_entities::inputs()),
             clouds: Some(pack_entities::cloud_inputs()),
+            weather: Some(pack_weather::inputs()),
         }
     }
 
@@ -3797,6 +3806,12 @@ impl Renderer {
                 .as_ref()
                 .and_then(|p| p.1.as_ref())
                 .is_some_and(|p| p.has_clouds());
+        let pack_draws_weather = pack_post
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_weather());
         let scaled = self.world_post.prepare(
             &self.device,
             [self.config.width, self.config.height],
@@ -3962,7 +3977,9 @@ impl Renderer {
                 pass.draw_indexed(0..entity_quads * 6, 0, 0..1);
                 pass.set_bind_group(0, &self.group, &[]);
             }
-            self.weather.draw(&mut pass, &self.entity_group);
+            if !pack_draws_weather {
+                self.weather.draw(&mut pass, &self.entity_group);
+            }
             pass.set_bind_group(0, &self.group, &[]);
             if crumbling_quads > 0 {
                 pass.set_pipeline(&self.crumbling_pipeline);
@@ -4101,6 +4118,22 @@ impl Renderer {
             && let Some((dimension, Some(mut post))) = self.pack_post.take()
         {
             let size = self.world_post.size().unwrap_or([1, 1]);
+            let weather = match &self.hud.atlas_texture {
+                Some(atlas) if pack_draws_weather => self
+                    .pack_weather
+                    .get_or_insert_with(|| pack_weather::PackWeather::new(&self.device))
+                    .prepare(
+                        &self.device,
+                        &mut encoder,
+                        &mut self.uploads,
+                        atlas,
+                        frame.weather,
+                        frame.weather_time,
+                        &self.indices,
+                    ),
+                _ => None,
+            };
+            post.set_weather(weather);
             let flat = self.flat.as_ref().filter(|_| flat_frame);
             let pages: Vec<(u32, wgpu::Buffer)> = match flat {
                 Some(_) if pack_draws_terrain => self
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 19ede8302..f6f87cbb8 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -39,6 +39,7 @@ enum Source {
     Lightmap,
 }
 
+#[derive(Clone)]
 struct Binding {
     source: Source,
     binding: u32,
@@ -140,6 +141,7 @@ struct Entities {
     late: [bool; PROGRAMS],
 }
 
+#[derive(Clone)]
 struct Pass {
     name: String,
     group: Group,
@@ -204,6 +206,8 @@ pub(super) struct World<'a> {
     pub celestial: Option<wgpu::TextureView>,
     /// Set 1 of the clouds' draw: their offset and palette.
     pub clouds: Option<&'a wgpu::BindGroupLayout>,
+    /// The game can hand its rain and snow to the pack.
+    pub weather: bool,
 }
 
 /// This frame's clouds, when the pack draws them: their vertices, uniform, quad indices and
@@ -215,6 +219,16 @@ pub(super) struct Clouds {
     pub quads: u32,
 }
 
+/// This frame's rain and snow, when the pack draws them: their vertices, the quad indices, the
+/// quads of each kind (rain, snow), each kind's sprite, and a number that changes with them.
+pub(super) struct Weather {
+    pub vertices: wgpu::Buffer,
+    pub indices: wgpu::Buffer,
+    pub quads: [std::ops::Range<u32>; 2],
+    pub sprites: [Option<wgpu::TextureView>; 2],
+    pub generation: u64,
+}
+
 pub struct PackPost {
     pub notes: Vec<String>,
     passes: Vec<Pass>,
@@ -232,6 +246,11 @@ pub struct PackPost {
     /// The pack has `gbuffers_clouds`, even one that writes nothing (a pack drawing its own
     /// clouds discards vanilla's): the game's clouds are not drawn.
     hides_clouds: bool,
+    /// What draws rain and snow (the same program, each with its kind's sprite as `texture`),
+    /// after translucent terrain, this frame's weather and the sprites' generation bound.
+    weather: Option<[Pass; 2]>,
+    weather_draw: Option<Weather>,
+    weather_generation: u64,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -970,6 +989,23 @@ impl PackPost {
             cull: false,
         });
         let hides_clouds = post.clouds.is_some() && cloud_geometry.is_some();
+        let weather_geometry = world.weather.then(|| Geometry {
+            buffers: &entity_buffers,
+            table: None,
+            depth_write: true,
+            atlas: None,
+            ids: None,
+            cull: false,
+        });
+        let weather = post
+            .weather
+            .zip(weather_geometry.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)))
+            .map(|rain| {
+                let mut snow = rain.clone();
+                snow.name = format!("{} (snow)", rain.name);
+                [rain, snow]
+            });
         let clouds = post
             .clouds
             .zip(cloud_geometry.as_ref())
@@ -1005,6 +1041,9 @@ impl PackPost {
         if let Some(c) = &clouds {
             notes.push(format!("clouds draw with {}", c.name));
         }
+        if let Some([w, _]) = &weather {
+            notes.push(format!("rain and snow draw with {}", w.name));
+        }
         for (part, pass) in entities.iter().flat_map(|e| parts.iter().zip(&e.passes)) {
             if let Some(p) = pass {
                 notes.push(format!("{part} draw with {}", p.name));
@@ -1015,6 +1054,7 @@ impl PackPost {
                 .iter()
                 .filter(|p| matches!(p.group, Group::Composite | Group::Final))
                 .chain(&water)
+                .chain(weather.iter().take(1).flatten())
                 .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth1));
         // A clear only matters when a program reads the buffer before one writes all of it
         // (composite passes cover their whole target, terrain does not); the others are skipped.
@@ -1030,6 +1070,7 @@ impl PackPost {
                 .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
                 .chain(&clouds)
                 .chain(&water)
+                .chain(weather.iter().take(1).flatten())
                 .find(touched)
                 .map(|_| true)
                 .or_else(|| {
@@ -1046,6 +1087,7 @@ impl PackPost {
             || sky.is_some()
             || entities.is_some()
             || clouds.is_some()
+            || weather.is_some()
             || passes.iter().any(|p| {
                 p.samplers
                     .iter()
@@ -1145,6 +1187,9 @@ impl PackPost {
             clouds,
             cloud_draw: None,
             hides_clouds,
+            weather,
+            weather_draw: None,
+            weather_generation: 0,
             depth1,
             mipped,
             mips_valid: 0,
@@ -1613,6 +1658,57 @@ impl PackPost {
     ) {
         self.draw_terrain(device, queue, encoder, size, true, terrain);
         self.draw_entities(device, queue, encoder, size, true);
+        self.draw_weather(device, queue, encoder, size);
+    }
+
+    /// The rain, then the snow, `set_weather` gave for this frame, with `gbuffers_weather`.
+    fn draw_weather(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+    ) {
+        let (Some(mut passes), Some(weather)) = (self.weather.take(), self.weather_draw.take())
+        else {
+            return;
+        };
+        if weather.generation != self.weather_generation {
+            self.weather_generation = weather.generation;
+            for (pass, sprite) in passes.iter_mut().zip(&weather.sprites) {
+                pass.atlas = sprite.clone();
+                pass.groups.clear();
+            }
+        }
+        for (pass, quads) in passes.iter_mut().zip(weather.quads.clone()) {
+            if quads.is_empty() {
+                continue;
+            }
+            let group = self.bind(device, queue, pass, size);
+            {
+                let mut rp = self.begin(encoder, pass);
+                rp.set_pipeline(&pass.pipeline);
+                rp.set_bind_group(0, &group, &[]);
+                if pass.draw {
+                    self.draws.bind(&mut rp, "RAIN_SNOW");
+                }
+                rp.set_vertex_buffer(0, weather.vertices.slice(..));
+                rp.set_index_buffer(weather.indices.slice(..), wgpu::IndexFormat::Uint32);
+                rp.draw_indexed(quads.start * 6..quads.end * 6, 0, 0..1);
+            }
+            self.mips_valid &= !pass.written;
+        }
+        self.weather = Some(passes);
+    }
+
+    /// Whether the pack draws rain and snow itself.
+    pub fn has_weather(&self) -> bool {
+        self.weather.is_some()
+    }
+
+    /// The rain and snow to draw this frame (`None`: none).
+    pub fn set_weather(&mut self, weather: Option<Weather>) {
+        self.weather_draw = weather;
     }
 
     /// Regenerates the mip chain of buffer `b`'s side that programs read.
@@ -1929,7 +2025,7 @@ impl PackPost {
                 .zip(e.late)
                 .any(|(p, late)| p.is_some() && late)
         });
-        let mut water_drawn = self.water.is_none() && !late_entities;
+        let mut water_drawn = self.water.is_none() && self.weather.is_none() && !late_entities;
         for pass in &mut passes {
             if !terrain_drawn && pass.group != Group::Prepare {
                 terrain_drawn = true;
diff --git a/crates/horizon-client/src/gfx/pack_weather.rs b/crates/horizon-client/src/gfx/pack_weather.rs
new file mode 100644
index 000000000..3479450af
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_weather.rs
@@ -0,0 +1,264 @@
+//! Rain and snow drawn by a shader pack's `gbuffers_weather` (spec 2.3): the game's weather
+//! quads as entity vertices, their UV animation applied here rather than in Horizon's weather
+//! shader, each kind textured from its own copy of its sprite so that the pack's `texture`
+//! repeats it across the column as a standalone rain or snow texture would.
+
+use crate::weather::{Time, Vertex as WeatherVertex};
+
+use super::Vertex;
+use super::pack_post::Weather;
+
+/// What `gbuffers_weather` reads from a weather vertex: camera-relative position, the UV in
+/// repeats of the sprite, colour (with vanilla's fade) and light. Weather has no normal; the
+/// pack sees straight up.
+pub fn inputs() -> horizon_shaders::GbuffersInputs {
+    let declarations =
+        "layout(location = 0) in vec3 hz_v_pos;\nlayout(location = 1) in vec2 hz_v_uv;\n\
+         layout(location = 2) in uint hz_v_overlay;\nlayout(location = 3) in vec4 hz_v_color;\n\
+         layout(location = 4) in uvec4 hz_v_light;\nlayout(location = 5) in vec4 hz_v_normal;\n"
+            .to_owned();
+    let body = "    hz_Vertex = vec4(hz_v_pos, 1.0);\n    \
+         hz_MultiTexCoord0 = vec4(hz_v_uv, 0.0, 1.0);\n    \
+         hz_MultiTexCoord1 = vec4(float(hz_v_light.y), float(hz_v_light.x), 0.0, 1.0);\n    \
+         hz_MultiTexCoord2 = hz_MultiTexCoord1;\n    \
+         hz_Color = hz_v_color;\n    \
+         hz_Normal = vec3(0.0, 1.0, 0.0);\n"
+        .to_owned();
+    let attributes = [
+        ("vaPosition", "hz_Vertex.xyz"),
+        ("vaUV0", "hz_v_uv"),
+        ("vaUV2", "ivec2(hz_MultiTexCoord1.xy)"),
+        ("vaColor", "hz_Color"),
+        ("vaNormal", "hz_Normal"),
+    ];
+    horizon_shaders::GbuffersInputs {
+        declarations,
+        body,
+        attributes: attributes
+            .iter()
+            .map(|&(n, v)| (n.to_owned(), v.to_owned()))
+            .collect(),
+        after: String::new(),
+        // Vanilla's weather drops texels below 0.1, as Horizon's own weather shader does.
+        alpha_test: Some(horizon_shaders::AlphaTest {
+            op: ">",
+            reference: 0.1,
+        }),
+    }
+}
+
+/// The UV phase of `v` at `time`: `weather_phase` of entity.wgsl, on the CPU.
+pub fn phase(v: &WeatherVertex, time: Time) -> [f32; 2] {
+    let [ticks, fall_ticks, partial, _] = time.values;
+    let a = v.animation;
+    if v.snow == 0 {
+        let t = ticks + a[1] + partial;
+        return [0.0, (-t / 32.0 * a[0]) % 32.0];
+    }
+    let t = ticks + partial;
+    let du = t * 0.01 * a[2];
+    let dv = t * a[3] * 0.001;
+    let base = |lo: u32, hi: u32| f64::from_bits(u64::from(lo) | u64::from(hi) << 32);
+    let u = (base(v.bases[0], v.bases[1]) + f64::from(du)) as f32;
+    let v_base = (base(v.bases[2], v.bases[3]) + f64::from(dv)) as f32;
+    [u, -(fall_ticks + partial) / 512.0 + v_base]
+}
+
+/// One kind's sprite copied out of the shared atlas: the sprite's rectangle (bits) and its view.
+type Sprite = Option<([u32; 4], wgpu::TextureView)>;
+
+/// The pack's weather vertices and the rain and snow sprites, kept across frames.
+pub struct PackWeather {
+    vertices: wgpu::Buffer,
+    capacity: usize,
+    scratch: Vec<Vertex>,
+    sprites: [Sprite; 2],
+    /// Bumped when a sprite is copied again.
+    generation: u64,
+}
+
+impl PackWeather {
+    pub fn new(device: &wgpu::Device) -> Self {
+        Self {
+            vertices: Self::buffer(device, 64),
+            capacity: 64,
+            scratch: Vec::new(),
+            sprites: [None, None],
+            generation: 0,
+        }
+    }
+
+    fn buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
+        device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack weather"),
+            size: (capacity * std::mem::size_of::<Vertex>()) as u64,
+            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        })
+    }
+
+    /// This frame's rain then snow (the game emits them in that order) as entity vertices, and
+    /// the sprites they read. `None` when there is none.
+    pub fn prepare(
+        &mut self,
+        device: &wgpu::Device,
+        encoder: &mut wgpu::CommandEncoder,
+        uploads: &mut super::upload::Uploads,
+        atlas: &wgpu::Texture,
+        weather: &[WeatherVertex],
+        time: Time,
+        indices: &wgpu::Buffer,
+    ) -> Option<Weather> {
+        if weather.is_empty() {
+            return None;
+        }
+        let rain = weather.iter().take_while(|v| v.snow == 0).count() as u32 / 4;
+        let snow = weather.len() as u32 / 4 - rain;
+        for (kind, first) in [(0, weather.first()), (1, weather.get(rain as usize * 4))] {
+            let Some(first) = first.filter(|v| v.snow as usize == kind) else {
+                continue;
+            };
+            let key = first.rect.map(f32::to_bits);
+            if self.sprites[kind].as_ref().is_none_or(|s| s.0 != key) {
+                let view = copy_sprite(device, encoder, atlas, first.rect);
+                self.sprites[kind] = Some((key, view));
+                self.generation += 1;
+            }
+        }
+        self.scratch.clear();
+        self.scratch.extend(weather.iter().map(|v| {
+            let [du, dv] = phase(v, time);
+            Vertex {
+                pos: v.pos,
+                uv: [v.uv[0] + du, v.uv[1] + dv],
+                layer: 0,
+                color: v.color,
+                light: v.light,
+                normal: [0; 4],
+            }
+        }));
+        if self.scratch.len() > self.capacity {
+            self.capacity = self.scratch.len().next_power_of_two();
+            self.vertices = Self::buffer(device, self.capacity);
+        }
+        uploads.buffer(
+            encoder,
+            &self.vertices,
+            0,
+            bytemuck::cast_slice(&self.scratch),
+        );
+        let view = |k: usize| self.sprites[k].as_ref().map(|s| s.1.clone());
+        Some(Weather {
+            vertices: self.vertices.clone(),
+            indices: indices.clone(),
+            quads: [0..rain, rain..rain + snow],
+            sprites: [view(0), view(1)],
+            generation: self.generation,
+        })
+    }
+}
+
+/// A texture holding the atlas's texels under `rect` (normalised x, y, width, height), as
+/// Horizon's weather shader reads them (`weather_texel`).
+fn copy_sprite(
+    device: &wgpu::Device,
+    encoder: &mut wgpu::CommandEncoder,
+    atlas: &wgpu::Texture,
+    rect: [f32; 4],
+) -> wgpu::TextureView {
+    let size = [atlas.width() as f32, atlas.height() as f32];
+    let origin = [0, 1].map(|i| (rect[i] * size[i]).round() as u32);
+    let extent = [0, 1].map(|i| ((rect[i + 2] * size[i]).round() as u32).max(1));
+    let extent = [0, 1].map(|i| {
+        extent[i].min(
+            [atlas.width(), atlas.height()][i]
+                .saturating_sub(origin[i])
+                .max(1),
+        )
+    });
+    let size = wgpu::Extent3d {
+        width: extent[0],
+        height: extent[1],
+        depth_or_array_layers: 1,
+    };
+    let texture = device.create_texture(&wgpu::TextureDescriptor {
+        label: Some("Shader pack weather sprite"),
+        size,
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: wgpu::TextureDimension::D2,
+        format: atlas.format(),
+        usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
+        view_formats: &[],
+    });
+    encoder.copy_texture_to_texture(
+        wgpu::TexelCopyTextureInfo {
+            texture: atlas,
+            mip_level: 0,
+            origin: wgpu::Origin3d {
+                x: origin[0],
+                y: origin[1],
+                z: 0,
+            },
+            aspect: wgpu::TextureAspect::All,
+        },
+        wgpu::TexelCopyTextureInfo {
+            texture: &texture,
+            mip_level: 0,
+            origin: wgpu::Origin3d::ZERO,
+            aspect: wgpu::TextureAspect::All,
+        },
+        size,
+    );
+    texture.create_view(&Default::default())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::weather::Parameters;
+
+    /// The CPU phase matches the game's own weather columns (`Parameters::column`), which
+    /// Horizon's weather shader is tested against.
+    #[test]
+    fn phase_matches_the_weather_columns() {
+        for i in 0..512i32 {
+            let x = i.wrapping_mul(45_238_971);
+            let z = i.wrapping_mul(-418_711).wrapping_add(i32::MIN);
+            let p = Parameters::new(x, z);
+            let bases = p.snow_base.map(f64::to_bits);
+            for ticks in [0, 511, 512, 131_071, 131_072, 1_000_003] {
+                let partial = [0.0, 0.5, 0.999][i as usize % 3];
+                for snow in [false, true] {
+                    let column = p.column(snow, ticks, x, -64, 320, z, 0, partial);
+                    let v = WeatherVertex {
+                        pos: [0.0; 3],
+                        uv: [0.0; 2],
+                        rect: [0.0; 4],
+                        animation: [
+                            p.rain_speed,
+                            p.rain_tick_offset,
+                            p.snow_drift[0],
+                            p.snow_drift[1],
+                        ],
+                        bases: [
+                            bases[0] as u32,
+                            (bases[0] >> 32) as u32,
+                            bases[1] as u32,
+                            (bases[1] >> 32) as u32,
+                        ],
+                        color: 0,
+                        light: 0,
+                        snow: u32::from(snow),
+                    };
+                    let [u, v] = phase(&v, Time::new(ticks, partial));
+                    assert_eq!(
+                        [u.to_bits(), v.to_bits()],
+                        [column.u_offset.to_bits(), column.v_offset.to_bits()],
+                        "x {x} z {z} ticks {ticks} snow {snow}"
+                    );
+                }
+            }
+        }
+    }
+}
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 2e163560f..5a7ea1472 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -123,6 +123,14 @@ const BLOCK: [&str; 5] = [
 /// `gbuffers_clouds`: no fallback, the game draws its clouds otherwise (OQ-3).
 const CLOUDS: [&str; 1] = ["gbuffers_clouds"];
 
+/// `gbuffers_weather` and its fallbacks (2.3).
+const WEATHER: [&str; 4] = [
+    "gbuffers_weather",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
 /// `gbuffers_entities_translucent` and its fallbacks (2.3).
 const ENTITIES_TRANSLUCENT: [&str; 5] = [
     "gbuffers_entities_translucent",
@@ -196,6 +204,8 @@ pub struct Post {
     pub particles: Option<PostProgram>,
     /// What draws the game's clouds.
     pub clouds: Option<PostProgram>,
+    /// What draws rain and snow, after deferred.
+    pub weather: Option<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
     pub translucent_late: bool,
     /// Particles draw after deferred (`particles.ordering`, `particles.before.deferred`, 3.2).
@@ -229,6 +239,8 @@ pub struct GameInputs {
     pub entities: Option<GbuffersInputs>,
     /// The clouds' mesh.
     pub clouds: Option<GbuffersInputs>,
+    /// Rain and snow.
+    pub weather: Option<GbuffersInputs>,
 }
 
 /// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
@@ -254,6 +266,7 @@ pub fn load_post(
         entities_translucent: None,
         particles: None,
         clouds: None,
+        weather: None,
         translucent_late: false,
         particles_late: false,
         custom: Custom::parse(properties),
@@ -359,6 +372,15 @@ pub fn load_post(
         p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
         p
     });
+    // Rain and snow draw after deferred and blend, as vanilla's do (OQ-23).
+    let weather = inputs
+        .weather
+        .as_ref()
+        .and_then(|i| gbuffers(&WEATHER, Group::Translucent, i));
+    let weather = weather.map(|mut p| {
+        p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
+        p
+    });
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -379,6 +401,7 @@ pub fn load_post(
     loader.post.entities_translucent = entities_translucent;
     loader.post.particles = particles;
     loader.post.clouds = clouds;
+    loader.post.weather = weather;
     let flag = |key: &str| properties.get(key).map(|v| v.trim() == "true");
     loader.post.translucent_late = flag("separateEntityDraws").unwrap_or(false);
     // `after` when the pack has a deferred program, else `mixed`; ours are all translucent, so
@@ -667,7 +690,8 @@ mod tests {
             sky: Some(inputs.clone()),
             celestial: Some(inputs.clone()),
             entities: Some(inputs.clone()),
-            clouds: Some(inputs),
+            clouds: Some(inputs.clone()),
+            weather: Some(inputs),
         };
         let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
@@ -717,6 +741,16 @@ mod tests {
         assert!(post.particles_late && !post.translucent_late);
         // gbuffers_clouds has no fallback (OQ-3): without it the game draws its clouds.
         assert!(post.clouds.is_none());
+        // Weather falls back to gbuffers_textured, after deferred, blended.
+        let weather = post.weather.as_ref().unwrap();
+        assert_eq!(
+            (weather.name.as_str(), weather.group, weather.blend),
+            (
+                "gbuffers_textured",
+                Group::Translucent,
+                Some(TRANSLUCENT_BLEND)
+            )
+        );
         let ordering = Properties::parse(
             "particles.ordering = before\nseparateEntityDraws = true\n",
             &macros,
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 2f6aff111..41323d440 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -174,7 +174,8 @@ fn real_packs_read() {
                 sky: Some(terrain.clone()),
                 celestial: Some(terrain.clone()),
                 entities: Some(terrain.clone()),
-                clouds: Some(terrain),
+                clouds: Some(terrain.clone()),
+                weather: Some(terrain),
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(

From 11035336a0115e7fbf4444934500c06ae93c66a4 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 11:24:29 +0100
Subject: [PATCH 047/270] Server: a gliding player's rocket boosts them

FireworkRocketItem.use attaches a rocket only to a player who is fall
flying. The server tracks a guest's glide (START_FALL_FLYING) but the
body it swaps in for their item use left fall_flying unset, so on the
server thread, LAN and dedicated servers the rocket did nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan_actions.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index d0f16a0d6..e140f31eb 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -264,6 +264,8 @@ impl Game<'_> {
         motion.sprinting = g.sprinting;
         motion.may_fly = g.creative() || g.game_mode == SPECTATOR;
         motion.flying = g.flying;
+        // FireworkRocketItem.use boosts only a gliding player.
+        motion.fall_flying = g.fall_flying;
         motion.invulnerable = motion.may_fly;
         let _ = motion.set_health(g.health, false);
         motion.health.food.food = g.food;

From e7ca664e01471d6c8e3581c411138d336c1ffff1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 11:32:23 +0100
Subject: [PATCH 048/270] Server: a guest's boost rocket is theirs

The server attached every boosting rocket to its own player: it followed
the host, and DATA_ATTACHED_TO_TARGET named the host (or nothing on the
server thread, which has none), so the guest's client never saw a rocket
attached to them and did not boost. The rocket now keeps the guest it was
fired by, follows them and names their entity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/fireworks.rs   | 23 ++++++++++++++++---
 .../horizon-client/src/game/lan_entities.rs   | 12 ++++++++--
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/game/fireworks.rs b/crates/horizon-client/src/game/fireworks.rs
index a0aa276b7..623e0e147 100644
--- a/crates/horizon-client/src/game/fireworks.rs
+++ b/crates/horizon-client/src/game/fireworks.rs
@@ -28,6 +28,9 @@ pub(super) struct Rocket {
     pub(super) explosions: Vec<FireworkExplosion>,
     /// Boosting the player (attachedToEntity).
     pub(super) attached: bool,
+    /// On a server, the player it boosts when not this game's own: a guest's
+    /// connection.
+    pub(super) guest: Option<u32>,
     /// `DATA_ATTACHED_TO_TARGET`: the server entity the rocket follows;
     /// boosting happens when it is the local player.
     pub(super) attached_to: Option<u32>,
@@ -51,6 +54,7 @@ impl Rocket {
             lifetime: i32::MAX,
             explosions,
             attached: false,
+            guest: None,
             attached_to: None,
             angled: false,
             item,
@@ -93,6 +97,7 @@ impl Game<'_> {
             lifetime,
             explosions,
             attached,
+            guest: None,
             attached_to: None,
             angled: false,
             item: stack.clone(),
@@ -132,7 +137,8 @@ impl Game<'_> {
             return false;
         }
         let at = self.player.as_ref().map_or(Vec3::ZERO, |p| p.position);
-        let rocket = self.new_rocket(at, stack, true);
+        let mut rocket = self.new_rocket(at, stack, true);
+        rocket.guest = self.lan_acting;
         self.rockets.push(rocket);
         if !self.creative {
             self.consume_held();
@@ -145,7 +151,18 @@ impl Game<'_> {
         while i < self.rockets.len() {
             let mut r = self.rockets.remove(i);
             r.previous = r.position;
-            if r.attached {
+            if r.attached
+                && let Some(conn) = r.guest
+            {
+                // A guest's rocket follows them; their own client boosts them.
+                let guest = self
+                    .lan
+                    .as_ref()
+                    .and_then(|host| host.hub.guests.iter().find(|g| g.conn == conn));
+                if let Some(g) = guest {
+                    r.position = Vec3::new(g.position[0], g.position[1], g.position[2]);
+                }
+            } else if r.attached {
                 if let Some(p) = self.player.as_mut() {
                     if p.fall_flying {
                         let look = view_vector(self.yaw, self.pitch);
@@ -234,7 +251,7 @@ impl Game<'_> {
         let at = [r.position.x, r.position.y, r.position.z];
         if !r.explosions.is_empty() {
             let damage = 5.0 + r.explosions.len() as f32 * 2.0;
-            if r.attached {
+            if r.attached && r.guest.is_none() {
                 self.hurt_player_by("minecraft:fireworks", damage);
             }
             let from = r.position;
diff --git a/crates/horizon-client/src/game/lan_entities.rs b/crates/horizon-client/src/game/lan_entities.rs
index db0c3e8b2..c525c902e 100644
--- a/crates/horizon-client/src/game/lan_entities.rs
+++ b/crates/horizon-client/src/game/lan_entities.rs
@@ -417,11 +417,19 @@ impl Game<'_> {
                     Value::Item(hub.stack(&Some(r.item.clone()))),
                 ));
             }
+            let boosted = match r.guest {
+                Some(conn) => hub
+                    .guests
+                    .iter()
+                    .find(|g| g.conn == conn)
+                    .map(|g| g.entity_id),
+                None => host_entity,
+            };
             if r.attached
-                && let Some(host) = host_entity
+                && let Some(player) = boosted
             {
                 e.meta
-                    .push((9, serializer::OPTIONAL_UNSIGNED_INT, Value::Id(host + 1)));
+                    .push((9, serializer::OPTIONAL_UNSIGNED_INT, Value::Id(player + 1)));
             }
             if r.angled {
                 e.meta.push((10, serializer::BOOLEAN, Value::Bool(true)));

From 39904c8051546efdb808f0fa9a8ccb68043f7dd2 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 11:33:08 +0100
Subject: [PATCH 049/270] docs/mods.md: the contract lists the command
 interface

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/mods.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/mods.md b/docs/mods.md
index 2f7105398..a021d420b 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -12,7 +12,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 
 | Part | Where | State |
 |---|---|---|
-| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks |
+| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage, command; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |

From 1437537cbfd16e349ee39eef7ec544fb6cb3fe01 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 08:39:29 +0100
Subject: [PATCH 050/270] Worker threads: leave one core, as vanilla does, not
 two

Graphics::worker_threads sizes the worker pools (the server thread's, which
generates and lights, and the window's, which meshes). Its automatic count
left two cores to the render and server threads; vanilla's executor leaves
one (Util.maxAllowedExecutorThreads). The workers run behind those threads
(niced on Linux; above four cores, raised server and render threads on
macOS and Windows), so the second core mostly idled: on a 4-thread laptop
only 2 cores generated while a world loaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/graphics.rs | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/graphics.rs b/crates/horizon-client/src/graphics.rs
index 3cf1402d2..291bf8a80 100644
--- a/crates/horizon-client/src/graphics.rs
+++ b/crates/horizon-client/src/graphics.rs
@@ -376,14 +376,18 @@ impl Graphics {
         if self.workers > 0 {
             return self.workers as usize;
         }
-        // The pool never takes every core. The render thread and the
-        // integrated server thread (single player runs on its own server
-        // thread by default) each need one, and a pool that fills every core
-        // starves them: the frame rate collapses to single digits while the
-        // workers saturate the CPU and its memory bandwidth.
+        // Vanilla's count (Util.maxAllowedExecutorThreads: every core but
+        // one). The pool never takes every core: a pool that fills them all
+        // starves the render and server threads, and the frame rate collapses
+        // while the workers saturate the CPU and its memory bandwidth. One
+        // core left is enough with the workers behind those two threads
+        // (horizon_threads: niced on Linux; on macOS and Windows the server
+        // and render threads are raised above four cores, where vanilla
+        // raises its server thread). Leaving two idled a core of a 4-thread
+        // laptop while a world loaded: a teleport there took ~15% longer.
         let auto = std::thread::available_parallelism()
             .map_or(2, |n| n.get())
-            .saturating_sub(2)
+            .saturating_sub(1)
             .max(1);
         if self.battery { auto.div_ceil(2) } else { auto }
     }
@@ -546,11 +550,11 @@ mod tests {
     }
 
     #[test]
-    fn automatic_workers_leave_cores_for_the_render_and_server_threads() {
+    fn automatic_workers_leave_a_core_as_vanilla_does() {
         let g = Graphics::default();
         assert_eq!(g.workers, 0);
         let cores = std::thread::available_parallelism().map_or(2, |n| n.get());
-        assert_eq!(g.worker_threads(), cores.saturating_sub(2).max(1));
+        assert_eq!(g.worker_threads(), cores.saturating_sub(1).max(1));
         // A manual count is the player's own choice, kept as asked.
         let manual = Graphics { workers: 3, ..g };
         assert_eq!(manual.worker_threads(), 3);

From 57ee0810381b2d1d271fcfa6678bb8de456c7151 Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:56:53 +0500
Subject: [PATCH 051/270] Keep sprint state independent of held sprint keys

Let PlayerCommand control the server sprint flag, matching vanilla, so releasing Ctrl cannot leave the client's speed modifier and FOV stuck. Cover the packet sequence and FOV recovery in regression tests.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
---
 crates/horizon-client/src/game/agent.rs |  3 +-
 crates/horizon-client/src/lan/hub.rs    |  4 +-
 crates/horizon-client/tests/lan_bot.rs  | 59 +++++++++++++++++++++++++
 tools/lan_e2e.py                        | 46 +++++++++++++++++++
 4 files changed, 110 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/agent.rs b/crates/horizon-client/src/game/agent.rs
index f6b68aa74..57c12da97 100644
--- a/crates/horizon-client/src/game/agent.rs
+++ b/crates/horizon-client/src/game/agent.rs
@@ -469,7 +469,8 @@ impl Game<'_> {
                 "flying": p.flying,
                 "fall_flying": p.fall_flying,
                 "sneaking": self.keys.contains(&KeyCode::ShiftLeft),
-                "sprinting": self.keys.contains(&KeyCode::ControlLeft),
+                "sprinting": p.sprinting,
+                "fov_modifier": self.view.fov_modifier,
                 "health": p.health.health(),
                 "absorption": p.health.absorption(),
                 // The hurt animation's ticks left (the camera's hurt tilt).
diff --git a/crates/horizon-client/src/lan/hub.rs b/crates/horizon-client/src/lan/hub.rs
index c2a395899..dd0a32f22 100644
--- a/crates/horizon-client/src/lan/hub.rs
+++ b/crates/horizon-client/src/lan/hub.rs
@@ -1984,7 +1984,9 @@ impl Hub {
                 S::PlayerInput(p) => {
                     self.guests[i].input = p.flags;
                     self.guests[i].sneaking = p.flags & 32 != 0;
-                    self.guests[i].sprinting = p.flags & 64 != 0 && p.flags & 1 != 0;
+                    // handlePlayerInput only records keys and updates crouching.
+                    // Sprinting persists after the sprint key is released (or
+                    // starts with a double tap); PlayerCommand changes it.
                 }
                 // OPEN_INVENTORY (the ridden mount's inventory) and
                 // START_FALL_FLYING (checked against the guest's chest slot
diff --git a/crates/horizon-client/tests/lan_bot.rs b/crates/horizon-client/tests/lan_bot.rs
index 6dd1b8258..34e8265a1 100644
--- a/crates/horizon-client/tests/lan_bot.rs
+++ b/crates/horizon-client/tests/lan_bot.rs
@@ -278,6 +278,65 @@ fn run<T: Send + 'static>(
     handle.join().unwrap().unwrap()
 }
 
+#[test]
+fn sprint_commands_survive_keyboard_input_changes() {
+    let Some(resources) = resources() else {
+        return;
+    };
+    let mut s = server(&resources);
+    let port = s.hub.lan.port;
+    let _bot = run(&mut s, move || connect(port, "Sprinter", true));
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while s.hub.guests.is_empty() {
+        s.tick(&[]);
+        assert!(Instant::now() < deadline, "guest did not join");
+        thread::yield_now();
+    }
+    let id = s.hub.guests[0].entity_id;
+    s.hub.guests[0].loaded = true;
+    s.hub.guests[0]
+        .inbox
+        .push_back(S::PlayerCommand(play::PlayerCommand {
+            id,
+            action: 1,
+            data: 0,
+        }));
+    s.tick(&[]);
+    assert!(s.hub.guests[0].sprinting);
+    // LocalPlayer keeps sprinting after Ctrl is released while W remains
+    // down. Double-tap sprint also sends forward without the sprint key.
+    for flags in [65, 1, 0, 33] {
+        s.hub.guests[0]
+            .inbox
+            .push_back(S::PlayerInput(play::PlayerInput { flags }));
+        s.tick(&[]);
+        let g = &s.hub.guests[0];
+        assert!(
+            g.sprinting,
+            "keyboard input {flags} cleared the sprint flag"
+        );
+        assert_eq!(g.input, flags);
+        assert_eq!(g.sneaking, flags & 32 != 0);
+    }
+    s.hub.guests[0]
+        .inbox
+        .push_back(S::PlayerCommand(play::PlayerCommand {
+            id,
+            action: 2,
+            data: 0,
+        }));
+    s.tick(&[]);
+    assert!(!s.hub.guests[0].sprinting);
+    s.hub.guests[0]
+        .inbox
+        .push_back(S::PlayerInput(play::PlayerInput { flags: 65 }));
+    s.tick(&[]);
+    assert!(
+        !s.hub.guests[0].sprinting,
+        "keyboard input started a sprint"
+    );
+}
+
 #[test]
 fn status_and_join() {
     let Some(resources) = resources() else {
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 0c8979f0a..892e393f0 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -6162,5 +6162,51 @@ CHECKS += ['falling']
 CHECK_FNS.update(falling=check_falling)
 
 
+def check_sprint_fov(host, guest, out):
+    """Releasing Ctrl must preserve a sprint until W is released, then reset FOV.
+
+    PlayerInput reports keys; PlayerCommand starts/stops the sprint. Confusing
+    them clears the client's sprint flag while leaving its speed modifier on.
+    """
+    seen = {}
+    for game in (host, guest):
+        game('command', command='gamemode creative')
+        game('command', command='effect clear @s')
+        game.raw('options-set', 'fovEffectScale', '1.0')
+        x, y, z = map(math.floor, pos_of(game))
+        game('command', command=f'fill {x - 2} {y} {z - 2} {x + 2} {y + 3} {z + 20} minecraft:air')
+        game('command', command=f'fill {x - 2} {y - 1} {z - 2} {x + 2} {y - 1} {z + 20} minecraft:stone')
+        game('command', command=f'tp @s {x + 0.5} {y} {z + 0.5} 0 0')
+        game.wait(20)
+        try:
+            game.raw('key', 'w', 'down')
+            game.raw('key', 'ctrl', 'down')
+            game.wait(10)
+            started = game('state')['player']
+            game.raw('key', 'ctrl', 'up')
+            game.wait(10)
+            released_ctrl = game('state')['player']
+            game.raw('key', 'w', 'up')
+            game.wait(20)
+            stopped = game('state')['player']
+        finally:
+            game.raw('key', 'ctrl', 'up')
+            game.raw('key', 'w', 'up')
+        seen[game.name] = states = {
+            label: {k: p[k] for k in ('sprinting', 'fov_modifier')}
+            for label, p in [('started', started), ('released_ctrl', released_ctrl), ('stopped', stopped)]
+        }
+        for label in ('started', 'released_ctrl'):
+            assert states[label]['sprinting'], f'{game.name} {label}: {states}'
+            assert abs(states[label]['fov_modifier'] - 1.15) < 0.002, f'{game.name} {label}: {states}'
+        assert not stopped['sprinting'], f'{game.name}: {states}'
+        assert abs(stopped['fov_modifier'] - 1.0) < 0.002, f'{game.name}: {states}'
+    return seen
+
+
+CHECKS += ['sprint-fov']
+CHECK_FNS['sprint-fov'] = check_sprint_fov
+
+
 if __name__ == '__main__':
     main()

From 1ec6d6d734ff97716ed5f6e1796a13db366006bd Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:15:35 +0500
Subject: [PATCH 052/270] Detach entity passengers when their vehicle is
 removed

Clear remote passenger mount and pose flags when a vehicle disappears, matching Entity.setRemoved. Add a two-passenger boat destruction check for both single-player paths and LAN observers.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
---
 crates/horizon-client/src/game/creatures.rs |  6 ++-
 crates/horizon-client/src/game/remote.rs    |  8 ++--
 tools/lan_e2e.py                            | 50 +++++++++++++++++++++
 3 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 0bb7bbe85..5cfcefdb8 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -321,7 +321,7 @@ impl Game<'_> {
             .iter()
             .filter(|m| m.distance_sqr(center) <= radius * radius)
             .map(|m| {
-                serde_json::json!({
+                let mut state = serde_json::json!({
                     "id": m.id,
                     "kind": m.kind.id,
                     "pos": [m.position.x, m.position.y, m.position.z],
@@ -370,7 +370,9 @@ impl Game<'_> {
                         "patrol_target": s.patrol_target,
                         "vehicle": m.extra.mount,
                     })),
-                })
+                });
+                state["passenger"] = serde_json::json!(m.extra.passenger);
+                state
             })
             .collect();
         serde_json::json!({ "count": self.mobs.len(), "near": list, "projectiles": self.creatures.projectiles.len() })
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a71b13a8..efaf02b95 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1515,10 +1515,10 @@ impl Game<'_> {
         self.turn_remote_projectile(id, rotation);
     }
     fn remove_entity(&mut self, id: i32) {
-        // The vehicle the player rode is gone (Entity.removeVehicle).
-        if self.riding == Some(id as u32) {
-            self.riding = None;
-        }
+        // Entity.setRemoved detaches every passenger, even when no empty
+        // SetPassengers packet preceded the vehicle's removal. Otherwise
+        // mobs and other players keep their passenger pose after it is gone.
+        self.remote_set_passengers(id, &[]);
         self.mobs.retain(|m| m.id != id as u32);
         self.orbs.retain(|o| o.id != id as u32);
         self.dropped.retain(|d| d.id != id as u32);
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 0c8979f0a..e146364b2 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -6162,5 +6162,55 @@ CHECKS += ['falling']
 CHECK_FNS.update(falling=check_falling)
 
 
+def check_boat_dismount_pose(host, guest, out):
+    """Removing a boat detaches its mobs on the server and every observing client."""
+    x, y, z = map(math.floor, pos_of(host))
+    bx, bz = x + 3.5, z + 3.5
+    tag = 'boat_dismount_pose'
+    host('command', command='gamemode creative')
+    host('command', command=f'fill {x - 2} {y - 1} {z - 2} {x + 8} {y - 1} {z + 8} minecraft:stone')
+    host('command', command=f'fill {x - 2} {y} {z - 2} {x + 8} {y + 4} {z + 8} minecraft:air')
+    host('command', command=f'summon minecraft:oak_boat {bx} {y} {bz} {{Tags:["{tag}"]}}')
+    for _ in range(2):
+        host('command', command=f'summon minecraft:husk {bx} {y} {bz} {{NoAI:1b,Tags:["{tag}"]}}')
+        host.wait(5)
+    try:
+        host.wait(20)
+        boat = next(o for o in host('status')['objects']
+                    if o['kind'].endswith('oak_boat') and math.dist(o['position'], [bx, y, bz]) < 2)
+        riders = [m['id'] for m in host.raw('mobs', 64)['near']
+                  if m['kind'] == 'minecraft:husk' and m['mount'] == boat['id']]
+        assert len(riders) == 2, f'the boat did not collect both husks: {riders}'
+        for game in (host, guest):
+            game.wait(10)
+            for rider in riders:
+                m = mob_seen(game, rider)
+                assert m and m['mount'] == boat['id'] and m['passenger'], f'{game.name} did not see seated husk {rider}: {m}'
+            game.raw('look-at', bx, y + 1, bz)
+            game.shot(out, 'boat-passengers-seated')
+        host('command', command=f'tp @s {bx - 3} {y} {bz} 0 0')
+        host.wait(5)
+        # Aim at the near rim, below the riders, so their boxes cannot
+        # intercept the creative player's one hit that destroys the boat.
+        host.raw('look-at', bx - 0.55, y + 0.1, bz)
+        host.raw('mouse', 'left', 'click')
+        seen = {}
+        for game in (host, guest):
+            game.wait(20)
+            assert all(o['id'] != boat['id'] for o in game('status')['objects']), f'{game.name} still sees the boat'
+            seen[game.name] = [mob_seen(game, rider) for rider in riders]
+            game.raw('look-at', bx, y + 1, bz)
+            game.shot(out, 'boat-passengers-dismounted')
+            for m in seen[game.name]:
+                assert m and m['mount'] is None and not m['passenger'], f'{game.name} still draws a removed boat\'s passenger: {m}'
+        return {name: [{k: m[k] for k in ('id', 'mount', 'passenger')} for m in mobs] for name, mobs in seen.items()}
+    finally:
+        host('command', command=f'kill @e[tag={tag}]')
+
+
+CHECKS += ['boat-dismount-pose']
+CHECK_FNS['boat-dismount-pose'] = check_boat_dismount_pose
+
+
 if __name__ == '__main__':
     main()

From 4032e162ce1cb2c3552edda9a744d910383db287 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 02:06:53 +0200
Subject: [PATCH 053/270] Draw translucent particles after translucent terrain
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Quad particles all went into the entity batch, drawn before translucent
terrain with depth writes on: a stained-glass crumb wrote its depth and
the sorted translucent pass then culled the glass behind it, so breaking
glass in front of glass cut holes through the wall.

Vanilla 26.3 submits quad particles to two phases: opaque layers draw
with the solids and translucent layers draw in an "afterTerrain" phase
right after the translucent section pass (the translucent particle
pipeline still writes depth, so ordering is what matters). Mirror that:
HudAtlas records which sprites have a 0 < alpha < 255 texel
(`SpriteContents.transparency().hasTranslucent`), particles classify
their layer the way `SingleQuadParticle.getLayer` does — the type's
hardcoded layer, or `Layer.bySprite` for terrain, item and block marker
sprites — and the entity batch routes those quads to a sixth bucket the
renderer draws immediately after translucent terrain.

Fixes #1679.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../examples/probe/marker_particles_probe.rs  |  2 +-
 .../probe/particle_providers_probe.rs         |  2 +-
 crates/horizon-client/src/game.rs             |  6 +-
 crates/horizon-client/src/gfx.rs              | 43 +++++++++++---
 crates/horizon-client/src/gfx/entity_batch.rs | 15 +++--
 crates/horizon-client/src/hud.rs              | 15 ++++-
 crates/horizon-client/src/particles.rs        | 58 +++++++++++++++++--
 7 files changed, 118 insertions(+), 23 deletions(-)

diff --git a/crates/horizon-client/examples/probe/marker_particles_probe.rs b/crates/horizon-client/examples/probe/marker_particles_probe.rs
index 190751d79..6b05af356 100644
--- a/crates/horizon-client/examples/probe/marker_particles_probe.rs
+++ b/crates/horizon-client/examples/probe/marker_particles_probe.rs
@@ -49,7 +49,7 @@ pub fn main() -> Result<()> {
             }
         }
     }
-    let mut engine = ParticleEngine::new(root, &HashMap::new());
+    let mut engine = ParticleEngine::new(root, &HashMap::new(), Default::default());
     let mut out = BufWriter::new(File::create(&args[2])?);
     for line in BufReader::new(File::open(&args[1])?).lines() {
         let case: Value = serde_json::from_str(&line?)?;
diff --git a/crates/horizon-client/examples/probe/particle_providers_probe.rs b/crates/horizon-client/examples/probe/particle_providers_probe.rs
index c8cd9d88d..067648e95 100644
--- a/crates/horizon-client/examples/probe/particle_providers_probe.rs
+++ b/crates/horizon-client/examples/probe/particle_providers_probe.rs
@@ -152,7 +152,7 @@ pub fn main() -> Result<()> {
         world(&assets, &facts, false, true)?,
         world(&assets, &facts, true, true)?,
     ];
-    let mut engine = ParticleEngine::new(root, &HashMap::new());
+    let mut engine = ParticleEngine::new(root, &HashMap::new(), Default::default());
     for (ty, item) in [
         (ParticleType::ItemSlime, "item_slime_ball"),
         (ParticleType::ItemSnowball, "item_snowball"),
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 653a1d038..cfb3ad433 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -11690,7 +11690,11 @@ impl<'a> Game<'a> {
         let inventory = vec![None; 36];
         let now = Instant::now();
         let look = options.look;
-        let particles = horizon_client::particles::ParticleEngine::new(&root, &gui.atlas.sprites);
+        let particles = horizon_client::particles::ParticleEngine::new(
+            &root,
+            &gui.atlas.sprites,
+            gui.atlas.translucent.clone(),
+        );
         Ok(Game {
             res: res.clone(),
             rest_loader: None,
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index a848d36a5..6af750b62 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -35,7 +35,7 @@ fn entity_shader() -> String {
 mod entity_batch;
 mod weather;
 use entity_batch::EntityBatch;
-pub use entity_batch::{SHADOW_OVERLAY, WATER_MASK_OVERLAY};
+pub use entity_batch::{SHADOW_OVERLAY, TRANSLUCENT_PARTICLE_OVERLAY, WATER_MASK_OVERLAY};
 
 /// Window.getAppropriateLineWidth, in framebuffer pixels.
 pub fn outline_width(width: u32) -> f32 {
@@ -3362,6 +3362,7 @@ impl Renderer {
             translucent_crumbling_quads,
             water_mask_quads,
             shadow_quads,
+            translucent_particle_quads,
         ] = self.entity_batch.update(
             frame.entities,
             frame.additive,
@@ -3373,7 +3374,8 @@ impl Renderer {
             + crumbling_quads
             + translucent_crumbling_quads
             + water_mask_quads
-            + shadow_quads;
+            + shadow_quads
+            + translucent_particle_quads;
         let cloud_quads = if let Some(input) = &frame.clouds {
             let (rebuilt, uniform) =
                 crate::spans::time("clouds", || self.cloud_mesh.prepare(input));
@@ -3827,6 +3829,22 @@ impl Renderer {
                     );
                 }
             }
+            // LevelRenderer.executeTranslucentAfterTerrain: vanilla's
+            // translucent particle layer draws after translucent terrain —
+            // the quads write depth, so before it they would hide the glass
+            // or water behind them.
+            if translucent_particle_quads > 0 {
+                pass.set_pipeline(&self.entity_pipeline);
+                pass.set_bind_group(0, &self.entity_group, &[]);
+                pass.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
+                pass.set_vertex_buffer(0, self.entity_buffer.slice(..));
+                pass.draw_indexed(
+                    0..translucent_particle_quads * 6,
+                    ((world_quads - translucent_particle_quads) * 4) as i32,
+                    0..1,
+                );
+                pass.set_bind_group(0, &self.group, &[]);
+            }
             // LevelRenderer.executeClassicTransparency: translucent targets'
             // outlines follow terrain, so its blending cannot wash them out.
             if outline_edges > 0 && frame.outline_after_terrain {
@@ -4316,14 +4334,23 @@ mod tests {
                 normal: [0; 4],
             }; 4]
         };
-        let entities: Vec<_> = [(0, 0), (14, 9), (4, 1), (11, 2), (7, 3), (4, 4), (12, 7)]
-            .into_iter()
-            .flat_map(|(layer, id)| quad(layer, id))
-            .collect();
+        let entities: Vec<_> = [
+            (0, 0),
+            (14, 9),
+            (4, 1),
+            (11, 2),
+            (15, 10),
+            (7, 3),
+            (4, 4),
+            (12, 7),
+        ]
+        .into_iter()
+        .flat_map(|(layer, id)| quad(layer, id))
+        .collect();
         let mut batch = super::EntityBatch::default();
         let counts = batch.update(&entities, &quad(3, 5), &quad(0, 6), &quad(0, 8));
         let vertices = &batch.combined;
-        assert_eq!(counts, [4, 1, 1, 0, 1]);
+        assert_eq!(counts, [4, 1, 1, 0, 1, 1]);
         assert_eq!(
             vertices
                 .as_chunks::<4>()
@@ -4331,7 +4358,7 @@ mod tests {
                 .iter()
                 .map(|q| q[0].light)
                 .collect::<Vec<_>>(),
-            [0, 1, 3, 4, 2, 7, 9, 5, 6, 8]
+            [0, 1, 3, 4, 2, 7, 9, 10, 5, 6, 8]
         );
     }
     #[test]
diff --git a/crates/horizon-client/src/gfx/entity_batch.rs b/crates/horizon-client/src/gfx/entity_batch.rs
index 56ffb04b9..8153699fc 100644
--- a/crates/horizon-client/src/gfx/entity_batch.rs
+++ b/crates/horizon-client/src/gfx/entity_batch.rs
@@ -3,13 +3,16 @@ use super::Vertex;
 
 /// Entity materials by a quad's overlay (`Vertex::layer`), in draw order:
 /// ordinary entities, breaking cracks (11), translucent breaking cracks (12),
-/// the boat water mask (13, `RenderPipelines.WATER_MASK`) and entity shadows
-/// (14, `RenderPipelines.ENTITY_SHADOW`).
-const MATERIALS: usize = 5;
+/// the boat water mask (13, `RenderPipelines.WATER_MASK`), entity shadows
+/// (14, `RenderPipelines.ENTITY_SHADOW`) and translucent-layer particles (15,
+/// drawn after translucent terrain: `SubmitNodeCollection.submitQuadParticleGroup`).
+const MATERIALS: usize = 6;
 /// The overlay of depth-only quads that hide water (`RenderTypes.waterMask`).
 pub const WATER_MASK_OVERLAY: u32 = 13;
 /// The overlay of entity shadow quads (`RenderTypes.entityShadow`).
 pub const SHADOW_OVERLAY: u32 = 14;
+/// The overlay of translucent-layer particles (`SingleQuadParticle.Layer.translucent`).
+pub const TRANSLUCENT_PARTICLE_OVERLAY: u32 = 15;
 
 #[derive(Default)]
 pub(super) struct EntityBatch {
@@ -41,6 +44,7 @@ impl EntityBatch {
                 12 => 2,
                 WATER_MASK_OVERLAY => 3,
                 SHADOW_OVERLAY => 4,
+                TRANSLUCENT_PARTICLE_OVERLAY => 5,
                 _ => 0,
             };
             self.buckets[material][counts[material]] = index;
@@ -92,13 +96,14 @@ mod tests {
     ) -> (Vec<Vertex>, [u32; MATERIALS]) {
         let mut combined = Vec::with_capacity(entities.len() + additive.len() + hand.len());
         let mut counts = [0; MATERIALS];
-        for (i, layer) in [0, 11, 12, 13, 14].into_iter().enumerate() {
+        for (i, layer) in [0, 11, 12, 13, 14, 15].into_iter().enumerate() {
             for quad in entities.as_chunks::<4>().0 {
                 let material = match quad[0].layer {
                     11 => 11,
                     12 => 12,
                     13 => 13,
                     14 => 14,
+                    15 => 15,
                     _ => 0,
                 };
                 if material == layer {
@@ -118,7 +123,7 @@ mod tests {
                 pos: [index as f32, 2.0, 3.0],
                 uv: [index as f32, 5.0],
                 layer: if mixed {
-                    [7, 11, 14, 12, 4, 13, 0][index / 4 % 7]
+                    [7, 11, 14, 12, 4, 13, 15, 0][index / 4 % 8]
                 } else {
                     0
                 },
diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs
index 89d1b1c3c..5626359c8 100644
--- a/crates/horizon-client/src/hud.rs
+++ b/crates/horizon-client/src/hud.rs
@@ -3,7 +3,7 @@
 //! GUI scale is applied when drawing).
 use crate::Result;
 use std::{
-    collections::HashMap,
+    collections::{HashMap, HashSet},
     fs,
     path::{Path, PathBuf},
 };
@@ -58,6 +58,9 @@ pub struct HudAtlas {
     pub width: u32,
     pub height: u32,
     pub sprites: HashMap<String, Rect>,
+    /// Sprites with a 0 < alpha < 255 texel (`SpriteContents.transparency().hasTranslucent`),
+    /// which puts their particles on vanilla's translucent layer.
+    pub translucent: HashSet<String>,
     /// Sprites whose `.png.mcmeta` sets `blur` or `clamp`; the others
     /// sample as vanilla's defaults (nearest, repeat).
     pub flags: HashMap<String, TextureFlags>,
@@ -459,7 +462,16 @@ impl HudAtlas {
         let height = (glyph_region + GLYPH_ROWS).next_multiple_of(1024);
         let mut pixels = vec![0u8; (width * height * 4) as usize];
         let mut sprites = HashMap::new();
+        let mut translucent = HashSet::new();
         for ((name, w, h, data), (px, py)) in images.iter().zip(placements) {
+            if data
+                .as_chunks::<4>()
+                .0
+                .iter()
+                .any(|p| p[3] != 0 && p[3] != 255)
+            {
+                translucent.insert(name.clone());
+            }
             for row in 0..*h {
                 let src = &data[(row * w * 4) as usize..((row + 1) * w * 4) as usize];
                 let dst = (((py + row) * width + px) * 4) as usize;
@@ -524,6 +536,7 @@ impl HudAtlas {
             width,
             height,
             sprites,
+            translucent,
             flags,
             fire_animations,
             font,
diff --git a/crates/horizon-client/src/particles.rs b/crates/horizon-client/src/particles.rs
index 0d4f4d623..62127808a 100644
--- a/crates/horizon-client/src/particles.rs
+++ b/crates/horizon-client/src/particles.rs
@@ -18,7 +18,10 @@ use horizon_core::{
     random::{LegacyRandom, RandomSource},
 };
 use horizon_world::block_collision::BlockCollisionRegistry;
-use std::{collections::HashMap, path::Path};
+use std::{
+    collections::{HashMap, HashSet},
+    path::Path,
+};
 
 macro_rules! particle_types {
     ($($variant:ident = $name:literal),* $(,)?) => {
@@ -196,6 +199,33 @@ impl ParticleType {
                 | Self::OminousSpawning
         )
     }
+    /// `SingleQuadParticle.Layer.translucent`: types whose vanilla particle class
+    /// hardcodes the translucent layer, drawn after translucent terrain.
+    /// `TerrainParticle`, `BreakingItemParticle` and `BlockMarker` resolve their
+    /// layer from the sprite instead (`Layer.bySprite`); see the `translucent`
+    /// sprite set on the engine.
+    pub fn translucent_layer(self) -> bool {
+        match self {
+            // CampfireSmokeParticle.
+            Self::CampfireCosySmoke | Self::CampfireSignalSmoke
+            // PlayerCloudParticle.
+            | Self::Cloud | Self::Sneeze
+            // SpellParticle.
+            | Self::Effect | Self::InstantEffect | Self::EntityEffect
+            | Self::Witch | Self::Infested | Self::TrialOmen | Self::RaidOmen
+            // EmissiveRisingParticle.
+            | Self::Soul | Self::SculkSoul
+            // SculkChargeParticle, SculkChargePopParticle, ShriekParticle,
+            // VibrationSignalParticle, FireflyParticle, OverlayParticle.
+            | Self::SculkCharge | Self::SculkChargePop | Self::Shriek
+            | Self::Vibration | Self::Firefly | Self::Flash
+            // SimpleAnimatedParticle and its subclasses: EndRodParticle,
+            // SparkParticle (firework), SquidInkParticle, TotemParticle.
+            | Self::EndRod | Self::Firework | Self::SquidInk | Self::GlowSquidInk
+            | Self::TotemOfUndying => true,
+            _ => false,
+        }
+    }
 }
 
 /// `ParticleOptions` with the parameters of the option classes used here.
@@ -1148,6 +1178,9 @@ pub struct ParticleEngine {
     names: Vec<String>,
     rects: Vec<Option<Rect>>,
     atlas: HashMap<String, Rect>,
+    /// `SingleQuadParticle.Layer.bySprite`: named sprites whose texels include
+    /// 0 < alpha < 255 render on vanilla's translucent particle layer.
+    translucent: HashSet<String>,
     sets: HashMap<ParticleType, u32>,
     set_sprites: Vec<Vec<u32>>,
     /// `TrackingEmitter`s: particle type, entity feet position, width, height, ticks left.
@@ -1167,7 +1200,7 @@ pub struct ParticleEngine {
 /// `ParticleGroup.MAX_PARTICLES` (per render group; one group here).
 const MAX_PARTICLES: usize = 16384;
 impl ParticleEngine {
-    pub fn new(root: &Path, atlas: &HashMap<String, Rect>) -> Self {
+    pub fn new(root: &Path, atlas: &HashMap<String, Rect>, translucent: HashSet<String>) -> Self {
         let mut engine = Self {
             particles: Vec::new(),
             pending: Vec::new(),
@@ -1179,6 +1212,7 @@ impl ParticleEngine {
             names: Vec::new(),
             rects: Vec::new(),
             atlas: atlas.clone(),
+            translucent,
             sets: HashMap::new(),
             set_sprites: Vec::new(),
             emitters: Vec::new(),
@@ -3765,6 +3799,13 @@ impl ParticleEngine {
                 Sprite::Named(name) => self.atlas.get(name).copied(),
             };
             let Some(r) = rect else { continue };
+            // `SubmitNodeCollection.submitQuadParticleGroup`: the translucent
+            // layer draws after translucent terrain, so a crumb of stained
+            // glass cannot hide the glass behind it (`getLayer`).
+            let layer = match &p.sprite {
+                Sprite::Index(_) => p.ty.translucent_layer(),
+                Sprite::Named(name) => self.translucent.contains(name),
+            };
             let a = f64::from(partial);
             let pos = DVec3::new(
                 p.previous[0] + (p.position[0] - p.previous[0]) * a,
@@ -3867,7 +3908,11 @@ impl ParticleEngine {
                         normal: [0; 4],
                         pos: v.to_array(),
                         uv,
-                        layer: 0,
+                        layer: if layer {
+                            crate::gfx::TRANSLUCENT_PARTICLE_OVERLAY
+                        } else {
+                            0
+                        },
                         color,
                         light,
                     });
@@ -3891,7 +3936,7 @@ mod tests {
 
     #[test]
     fn egg_teleport_unpacks_offsets_and_preserves_seeded_draw_order() {
-        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new());
+        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
         engine.seed_randoms(0, 0, 0);
         // Destination offset (-15, 7, 15); the unused top byte is ignored.
         engine.block_teleportation([4, 12, -5], 0xff01_0f1fu32 as i32, [16, 8, 16], 0);
@@ -3916,7 +3961,7 @@ mod tests {
 
     #[test]
     fn consume_teleport_unpacks_offsets_within_127() {
-        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new());
+        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
         engine.seed_randoms(0, 0, 0);
         // TeleportRandomlyConsumeEffect: BlockUtil.clampedPackDifferenceInPosition
         // of the move (-7, -3, 9) with radii 127, from (4, 12, -5) to (-3, 9, 4).
@@ -3941,7 +3986,8 @@ mod tests {
             (2, 0, 99_413_408_083_437),
         ] {
             for distant in [false, true] {
-                let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new());
+                let mut engine =
+                    ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
                 engine.seed_randoms(0, 0, 0);
                 if distant {
                     engine.camera = [1000.0; 3];

From be378bb77361b611b9451f76033daf97e0c8d75e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:44:32 +0100
Subject: [PATCH 054/270] Particles: vault connections are translucent, shadows
 keep their range

- FlyTowardsPositionParticle puts vault_connection on the translucent
  layer: its LifetimeAlpha(0, 0.6, 0.25, 1) is not opaque.
- The shadow draw started at world_quads - shadow_quads; with the new
  bucket after it, that drew translucent particles with the shadow
  pipeline and dropped as many shadows.
- One atlas lookup per named-sprite particle and frame: the engine keeps
  each sprite's layer beside its rect instead of hashing the name twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../examples/probe/marker_particles_probe.rs  |  2 +-
 .../probe/particle_providers_probe.rs         |  2 +-
 crates/horizon-client/src/game.rs             |  2 +-
 crates/horizon-client/src/gfx.rs              |  2 +-
 crates/horizon-client/src/particles.rs        | 45 ++++++++++---------
 5 files changed, 29 insertions(+), 24 deletions(-)

diff --git a/crates/horizon-client/examples/probe/marker_particles_probe.rs b/crates/horizon-client/examples/probe/marker_particles_probe.rs
index 6b05af356..72ebaff22 100644
--- a/crates/horizon-client/examples/probe/marker_particles_probe.rs
+++ b/crates/horizon-client/examples/probe/marker_particles_probe.rs
@@ -49,7 +49,7 @@ pub fn main() -> Result<()> {
             }
         }
     }
-    let mut engine = ParticleEngine::new(root, &HashMap::new(), Default::default());
+    let mut engine = ParticleEngine::new(root, &HashMap::new(), &Default::default());
     let mut out = BufWriter::new(File::create(&args[2])?);
     for line in BufReader::new(File::open(&args[1])?).lines() {
         let case: Value = serde_json::from_str(&line?)?;
diff --git a/crates/horizon-client/examples/probe/particle_providers_probe.rs b/crates/horizon-client/examples/probe/particle_providers_probe.rs
index 067648e95..68f23f3af 100644
--- a/crates/horizon-client/examples/probe/particle_providers_probe.rs
+++ b/crates/horizon-client/examples/probe/particle_providers_probe.rs
@@ -152,7 +152,7 @@ pub fn main() -> Result<()> {
         world(&assets, &facts, false, true)?,
         world(&assets, &facts, true, true)?,
     ];
-    let mut engine = ParticleEngine::new(root, &HashMap::new(), Default::default());
+    let mut engine = ParticleEngine::new(root, &HashMap::new(), &Default::default());
     for (ty, item) in [
         (ParticleType::ItemSlime, "item_slime_ball"),
         (ParticleType::ItemSnowball, "item_snowball"),
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index cfb3ad433..f6b1bf828 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -11693,7 +11693,7 @@ impl<'a> Game<'a> {
         let particles = horizon_client::particles::ParticleEngine::new(
             &root,
             &gui.atlas.sprites,
-            gui.atlas.translucent.clone(),
+            &gui.atlas.translucent,
         );
         Ok(Game {
             res: res.clone(),
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 6af750b62..f8cd8acd8 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -3761,7 +3761,7 @@ impl Renderer {
                 pass.set_vertex_buffer(0, self.entity_buffer.slice(..));
                 pass.draw_indexed(
                     0..shadow_quads * 6,
-                    ((world_quads - shadow_quads) * 4) as i32,
+                    ((world_quads - translucent_particle_quads - shadow_quads) * 4) as i32,
                     0..1,
                 );
                 pass.set_bind_group(0, &self.group, &[]);
diff --git a/crates/horizon-client/src/particles.rs b/crates/horizon-client/src/particles.rs
index 62127808a..be7f32551 100644
--- a/crates/horizon-client/src/particles.rs
+++ b/crates/horizon-client/src/particles.rs
@@ -222,7 +222,9 @@ impl ParticleType {
             // SimpleAnimatedParticle and its subclasses: EndRodParticle,
             // SparkParticle (firework), SquidInkParticle, TotemParticle.
             | Self::EndRod | Self::Firework | Self::SquidInk | Self::GlowSquidInk
-            | Self::TotemOfUndying => true,
+            | Self::TotemOfUndying
+            // FlyTowardsPositionParticle: its LifetimeAlpha(0, 0.6, 0.25, 1) is not opaque.
+            | Self::VaultConnection => true,
             _ => false,
         }
     }
@@ -1177,10 +1179,9 @@ pub struct ParticleEngine {
     pub requested: Option<Vec<(ParticleOptions, [f64; 3], [f64; 3])>>,
     names: Vec<String>,
     rects: Vec<Option<Rect>>,
-    atlas: HashMap<String, Rect>,
-    /// `SingleQuadParticle.Layer.bySprite`: named sprites whose texels include
-    /// 0 < alpha < 255 render on vanilla's translucent particle layer.
-    translucent: HashSet<String>,
+    /// Each named sprite, and whether `SingleQuadParticle.Layer.bySprite` puts
+    /// it on the translucent layer (a texel with 0 < alpha < 255).
+    atlas: HashMap<String, (Rect, bool)>,
     sets: HashMap<ParticleType, u32>,
     set_sprites: Vec<Vec<u32>>,
     /// `TrackingEmitter`s: particle type, entity feet position, width, height, ticks left.
@@ -1200,7 +1201,7 @@ pub struct ParticleEngine {
 /// `ParticleGroup.MAX_PARTICLES` (per render group; one group here).
 const MAX_PARTICLES: usize = 16384;
 impl ParticleEngine {
-    pub fn new(root: &Path, atlas: &HashMap<String, Rect>, translucent: HashSet<String>) -> Self {
+    pub fn new(root: &Path, atlas: &HashMap<String, Rect>, translucent: &HashSet<String>) -> Self {
         let mut engine = Self {
             particles: Vec::new(),
             pending: Vec::new(),
@@ -1211,8 +1212,10 @@ impl ParticleEngine {
             requested: None,
             names: Vec::new(),
             rects: Vec::new(),
-            atlas: atlas.clone(),
-            translucent,
+            atlas: atlas
+                .iter()
+                .map(|(name, &rect)| (name.clone(), (rect, translucent.contains(name))))
+                .collect(),
             sets: HashMap::new(),
             set_sprites: Vec::new(),
             emitters: Vec::new(),
@@ -1254,7 +1257,7 @@ impl ParticleEngine {
             return i as u32;
         }
         self.names.push(name.to_owned());
-        self.rects.push(self.atlas.get(name).copied());
+        self.rects.push(self.atlas.get(name).map(|&(rect, _)| rect));
         (self.names.len() - 1) as u32
     }
     pub fn len(&self) -> usize {
@@ -3794,18 +3797,20 @@ impl ParticleEngine {
             {
                 continue;
             }
-            let rect = match &p.sprite {
-                Sprite::Index(i) => self.rects.get(*i as usize).copied().flatten(),
-                Sprite::Named(name) => self.atlas.get(name).copied(),
-            };
-            let Some(r) = rect else { continue };
             // `SubmitNodeCollection.submitQuadParticleGroup`: the translucent
             // layer draws after translucent terrain, so a crumb of stained
             // glass cannot hide the glass behind it (`getLayer`).
-            let layer = match &p.sprite {
-                Sprite::Index(_) => p.ty.translucent_layer(),
-                Sprite::Named(name) => self.translucent.contains(name),
+            let (rect, layer) = match &p.sprite {
+                Sprite::Index(i) => (
+                    self.rects.get(*i as usize).copied().flatten(),
+                    p.ty.translucent_layer(),
+                ),
+                Sprite::Named(name) => match self.atlas.get(name) {
+                    Some(&(rect, translucent)) => (Some(rect), translucent),
+                    None => (None, false),
+                },
             };
+            let Some(r) = rect else { continue };
             let a = f64::from(partial);
             let pos = DVec3::new(
                 p.previous[0] + (p.position[0] - p.previous[0]) * a,
@@ -3936,7 +3941,7 @@ mod tests {
 
     #[test]
     fn egg_teleport_unpacks_offsets_and_preserves_seeded_draw_order() {
-        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
+        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), &HashSet::new());
         engine.seed_randoms(0, 0, 0);
         // Destination offset (-15, 7, 15); the unused top byte is ignored.
         engine.block_teleportation([4, 12, -5], 0xff01_0f1fu32 as i32, [16, 8, 16], 0);
@@ -3961,7 +3966,7 @@ mod tests {
 
     #[test]
     fn consume_teleport_unpacks_offsets_within_127() {
-        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
+        let mut engine = ParticleEngine::new(Path::new(""), &HashMap::new(), &HashSet::new());
         engine.seed_randoms(0, 0, 0);
         // TeleportRandomlyConsumeEffect: BlockUtil.clampedPackDifferenceInPosition
         // of the move (-7, -3, 9) with radii 127, from (4, 12, -5) to (-3, 9, 4).
@@ -3987,7 +3992,7 @@ mod tests {
         ] {
             for distant in [false, true] {
                 let mut engine =
-                    ParticleEngine::new(Path::new(""), &HashMap::new(), HashSet::new());
+                    ParticleEngine::new(Path::new(""), &HashMap::new(), &HashSet::new());
                 engine.seed_randoms(0, 0, 0);
                 if distant {
                     engine.camera = [1000.0; 3];

From 0bc85843ce0d9672c6990345af6ffd4e4b180993 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 00:19:47 +0200
Subject: [PATCH 055/270] Client: remote players keep their skins instead of
 falling back
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

skins::unpack discarded a profile's whole textures payload when any one
entry lacked "url" or pointed outside the texture services' domains, so
a player with e.g. an unusual cape lost their skin too; it now drops only
the offending texture. The 32 skin atlas slots evicted past players back
to defaults on busy servers — now 128. A dimension reset (join game or
respawn onto another world) now also clears the entity-id→profile map so
a re-used entity id can't pin the wrong skin or name to a player, and the
nametag join falls back to the player-list entry's name.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/remote.rs | 12 +++++++++++-
 crates/horizon-client/src/hud.rs         |  4 +++-
 crates/horizon-client/src/skins.rs       | 21 +++++++++++----------
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a71b13a8..36122d42a 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1006,6 +1006,9 @@ impl Game<'_> {
                 r.stepped.clear();
                 r.head_lerps.clear();
                 r.pending_items.clear();
+                // The entity ids are the old world's; the new dimension's
+                // player entities re-map to their profiles on AddEntity.
+                r.level_players.clear();
                 // A new ClientLevel: a new chunk storage, centred on 0, 0.
                 r.chunk_center = (0, 0);
             }
@@ -5065,7 +5068,14 @@ impl Game<'_> {
         r.level_players
             .iter()
             .filter(|(_, uuid)| **uuid != r.profile)
-            .filter_map(|(id, uuid)| Some((*id as u32, r.players.get(uuid)?.clone())))
+            .filter_map(|(id, uuid)| {
+                let name = r
+                    .players
+                    .get(uuid)
+                    .cloned()
+                    .or_else(|| r.tab_players.get(uuid).map(|t| t.name.clone()))?;
+                Some((*id as u32, name))
+            })
             .collect()
     }
     /// `ClientClockManager.tick`: the clock moves on by the game time that
diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs
index 89d1b1c3c..90a8b346c 100644
--- a/crates/horizon-client/src/hud.rs
+++ b/crates/horizon-client/src/hud.rs
@@ -78,7 +78,9 @@ pub const MAP_SLOTS: usize = 256;
 /// The atlas slot the minimap extra draws into.
 pub const MINIMAP_SPRITE: &str = "horizon/minimap";
 /// Atlas slots for downloaded player skins (`skins/<sha1>`), 64x64 each.
-pub const SKIN_SLOTS: usize = 32;
+/// Vanilla registers a texture per skin; too few slots evict a busy
+/// server's players back to their default skins.
+pub const SKIN_SLOTS: usize = 128;
 /// Reused by the visible rows of the classic world selector.
 pub const WORLD_ICON_SLOTS: usize = 32;
 /// Atlas slots for the pack icons on the pack screen, one per icon drawn
diff --git a/crates/horizon-client/src/skins.rs b/crates/horizon-client/src/skins.rs
index 9014032c4..0cf9cc8a2 100644
--- a/crates/horizon-client/src/skins.rs
+++ b/crates/horizon-client/src/skins.rs
@@ -92,22 +92,23 @@ pub fn unpack(value: &str, signature: Signature, valid_uris: &[&str]) -> Texture
         ..empty.clone()
     };
     for (kind, texture) in textures {
-        let Some(url) = texture.get("url").and_then(|u| u.as_str()) else {
-            return empty;
-        };
-        let allowed = valid_uris
-            .iter()
-            .any(|u| url.starts_with(&u.replace("{textureId}", "")));
-        if !allowed {
-            return empty;
-        }
         let slot = match kind.as_str() {
             "SKIN" => &mut out.skin,
             "CAPE" => &mut out.cape,
             "ELYTRA" => &mut out.elytra,
             _ => continue,
         };
-        *slot = Some(url.to_owned());
+        // One bad entry (no `url`, or a URL outside the texture services'
+        // domains) drops only that texture, not the whole payload.
+        let Some(url) = texture.get("url").and_then(|u| u.as_str()) else {
+            continue;
+        };
+        let allowed = valid_uris
+            .iter()
+            .any(|u| url.starts_with(&u.replace("{textureId}", "")));
+        if allowed {
+            *slot = Some(url.to_owned());
+        }
     }
     out
 }

From 18cac82d448888c5901b9b29679fd3a5dfae6230 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:35:44 +0100
Subject: [PATCH 056/270] Shader packs, clean room 35: held item ids and light

`item.properties` (spec 4.1) gives `heldItemId` and `heldItemId2` the
id of the main and off hand's item: -1 for an item the file lacks or an
empty hand, 0 without the file (5.3). `heldBlockLightValue(2)` are the
light levels of the held items' blocks, as Horizon's dynamic lights
already compute them. With `oldHandLight` (on unless the pack turns it
off, OQ-21) the first id and light are those of the brighter hand.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1;
no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/shader_packs.rs   | 50 +++++++++++++++++++
 .../horizon-client/src/gfx/pack_uniforms.rs   | 10 +++-
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index 88a73c108..f0087c4b0 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -21,6 +21,12 @@ pub(super) struct PackIds {
     /// The id of a name the file lacks: 65535, or 0 without the file.
     missing_entity: i32,
     missing_block: i32,
+    /// `item.properties` (4.1) and the id of a held item the file lacks, or of an empty hand:
+    /// −1, or 0 without the file (5.3).
+    items: HashMap<String, i32>,
+    missing_item: i32,
+    /// `oldHandLight` (3.2): the first held item and light are those of the brighter hand.
+    old_hand_light: bool,
 }
 
 impl Game<'_> {
@@ -72,7 +78,18 @@ impl Game<'_> {
                         &Properties::parse(text.as_deref().unwrap_or_default(), &macros),
                         "entity",
                     );
+                    let text = pack.read_text("item.properties");
+                    let items = BlockIds::parse_kind(
+                        &Properties::parse(text.as_deref().unwrap_or_default(), &macros),
+                        "item",
+                    );
                     self.pack_ids = Some(PackIds {
+                        items: items.plain(),
+                        missing_item: if text.is_some() { -1 } else { 0 },
+                        // OQ-21: on unless the pack turns it off.
+                        old_hand_light: properties
+                            .get("oldHandLight")
+                            .is_none_or(|v| v.trim() != "false"),
                         entities: entities.plain(),
                         missing_entity: if text.is_some() { 65535 } else { 0 },
                         missing_block: if ids.is_empty() { 0 } else { 65535 },
@@ -116,6 +133,7 @@ impl Game<'_> {
             .chunks
             .get(&(at.x >> 4, at.z >> 4))
             .map(|c| c.biome(at.x, at.y, at.z));
+        let (held_items, held_light) = self.held_for_pack();
         let info = biome.map(|b| self.res.biomes().get(b));
         PackInputs {
             day_time: self.world.day_time,
@@ -138,8 +156,40 @@ impl Game<'_> {
             }),
             temperature: info.map_or(0.0, |b| b.temperature),
             rainfall: info.map_or(0.0, |b| b.downfall),
+            held_items,
+            held_light,
         }
     }
+
+    /// `heldItemId(2)` and `heldBlockLightValue(2)`: main hand, then off hand (5.2, 5.3).
+    fn held_for_pack(&mut self) -> ([i32; 2], [i32; 2]) {
+        if self.pack_ids.is_none() {
+            return ([0; 2], [0; 2]);
+        }
+        if self.luminance.is_none() {
+            self.luminance = Some(horizon_client::dynamic_light::Luminance::new(
+                self.res.facts(),
+                self.pack.assets.registry,
+            ));
+        }
+        let (Some(ids), Some(lum)) = (&self.pack_ids, &self.luminance) else {
+            return ([0; 2], [0; 2]);
+        };
+        let hands = [self.selected, super::shield::OFFHAND_SLOT].map(|slot| {
+            let item = self.stack_in(slot).map(|s| &*s.item);
+            let id = item.and_then(|i| ids.items.get(i).copied());
+            (
+                id.unwrap_or(ids.missing_item),
+                item.map_or(0, |i| i32::from(lum.of(i))),
+            )
+        });
+        let first = if ids.old_hand_light && hands[1].1 > hands[0].1 {
+            hands[1]
+        } else {
+            hands[0]
+        };
+        ([first.0, hands[1].0], [first.1, hands[1].1])
+    }
 }
 
 impl Game<'_> {
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index 21cfc2b14..efa8d2e2c 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -29,6 +29,9 @@ pub struct PackInputs {
     pub biome_precipitation: i32,
     pub temperature: f32,
     pub rainfall: f32,
+    /// `heldItemId`, `heldItemId2` (item.properties, 5.3) and `heldBlockLightValue(2)`.
+    pub held_items: [i32; 2],
+    pub held_light: [i32; 2],
 }
 
 /// One uniform's value: up to 16 floats or 3 integers.
@@ -319,8 +322,11 @@ impl FrameUniforms {
                 "gbufferProjectionInverse" => m4(projection.inverse()),
                 "gbufferPreviousModelView" => m4(previous_view),
                 "gbufferPreviousProjection" => m4(previous_projection),
-                // Held items wait for `item.properties` (5.3: 0 without the file); renderStage
-                // is NONE outside gbuffers draws.
+                "heldItemId" => Value::i(&[inputs.held_items[0]]),
+                "heldItemId2" => Value::i(&[inputs.held_items[1]]),
+                "heldBlockLightValue" => Value::i(&[inputs.held_light[0]]),
+                "heldBlockLightValue2" => Value::i(&[inputs.held_light[1]]),
+                // renderStage is NONE outside gbuffers draws.
                 _ => Value::i(&[0]),
             }
         };

From 3740de5116dbf9322e39d18c3ce0777d087d0401 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 13:40:07 +0100
Subject: [PATCH 057/270] Launcher: pin the macOS title bar to the chosen
 appearance

The launcher's Appearance setting darkened the page but not the window's native chrome: NSWindow keeps the system appearance, so a launcher set to Dark still drew a light title bar on a light desktop. apply_appearance (titlebar.rs) pins the NSWindow's appearance to the choice at startup and when the setting changes; System clears the pin so the chrome follows the computer again.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 launcher/Cargo.lock      |  2 ++
 launcher/Cargo.toml      |  4 ++++
 launcher/src/main.rs     |  4 ++++
 launcher/src/titlebar.rs | 49 +++++++++++++++++++++++++++++++++++++++-
 4 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/launcher/Cargo.lock b/launcher/Cargo.lock
index 5155420e0..922a92f2f 100644
--- a/launcher/Cargo.lock
+++ b/launcher/Cargo.lock
@@ -2680,8 +2680,10 @@ dependencies = [
  "horizon-theme",
  "image",
  "keyring",
+ "objc2-app-kit",
  "oo7",
  "pulldown-cmark",
+ "raw-window-handle",
  "self-replace",
  "serde",
  "serde_json",
diff --git a/launcher/Cargo.toml b/launcher/Cargo.toml
index a402d0e28..570e2bd75 100644
--- a/launcher/Cargo.toml
+++ b/launcher/Cargo.toml
@@ -48,6 +48,10 @@ oo7 = { version = "0.5", default-features = false, features = ["async-std", "nat
 futures-lite = "2"
 [target.'cfg(target_os = "macos")'.dependencies]
 keyring = { version = "3", features = ["apple-native"] }
+# Painting the window's title bar dark or light (titlebar::apply_appearance): crates already in
+# the lockfile through gpui and wgpu.
+objc2-app-kit = { version = "0.3", default-features = false, features = ["NSAppearance", "NSView", "NSWindow"] }
+raw-window-handle = "0.6"
 [target.'cfg(target_os = "windows")'.dependencies]
 keyring = { version = "3", features = ["windows-native"] }
 
diff --git a/launcher/src/main.rs b/launcher/src/main.rs
index 0bcbc4011..ebde171e5 100644
--- a/launcher/src/main.rs
+++ b/launcher/src/main.rs
@@ -265,6 +265,9 @@ impl Launcher {
         {
             settings.selected = installed.first().cloned();
         }
+        // Pin the window's chrome (macOS title bar) to the choice before the theme reads
+        // `window.appearance()`, so both draw the same look.
+        titlebar::apply_appearance(window, settings.appearance);
         let mut this = Self {
             theme: Theme::for_appearance(settings.appearance, window.appearance()),
             page: Page::from_env(),
@@ -2482,6 +2485,7 @@ impl Launcher {
                     let _ = this.update(cx, |this, cx| {
                         this.settings.appearance = choice;
                         this.settings.save();
+                        titlebar::apply_appearance(window, choice);
                         this.theme = Theme::for_appearance(choice, window.appearance());
                         cx.notify();
                     });
diff --git a/launcher/src/titlebar.rs b/launcher/src/titlebar.rs
index 3c2a78ea4..2e6445091 100644
--- a/launcher/src/titlebar.rs
+++ b/launcher/src/titlebar.rs
@@ -1,6 +1,8 @@
-//! Custom Windows chrome. Other platforms keep their native window decorations.
+//! Custom Windows chrome. Other platforms keep their native window decorations; on macOS,
+//! `apply_appearance` repaints that chrome (the title bar) to match the chosen look.
 use crate::theme::Theme;
 use gpui::{Div, TitlebarOptions, Window};
+use horizon_launcher::backend::Appearance;
 
 /// Whether the launcher draws its own title bar (`render`) rather than the system.
 pub const DRAWN: bool = cfg!(target_os = "windows");
@@ -18,6 +20,51 @@ pub fn render(_theme: &Theme, _window: &Window) -> Option<Div> {
     None
 }
 
+/// macOS keeps the window's appearance on the system setting, so a launcher set to Dark still
+/// draws a light title bar on a light desktop. Pin the NSWindow's appearance to the choice
+/// instead (`System` clears the pin, handing the chrome back to the system), honouring the same
+/// `HORIZON_LAUNCHER_APPEARANCE` override the theme does. Other platforms' chrome already
+/// follows the setting (ours is drawn, Windows and Linux follow the system either way).
+#[cfg(target_os = "macos")]
+pub fn apply_appearance(window: &Window, choice: Appearance) {
+    use objc2_app_kit::{
+        NSAppearance, NSAppearanceCustomization, NSAppearanceName, NSAppearanceNameAqua,
+        NSAppearanceNameDarkAqua, NSView,
+    };
+    use raw_window_handle::{HasWindowHandle, RawWindowHandle};
+
+    // Reading AppKit's name constants is unsafe to rustc only (`use of extern static`).
+    let name: Option<&'static NSAppearanceName> = unsafe {
+        match std::env::var("HORIZON_LAUNCHER_APPEARANCE").as_deref() {
+            Ok("light") => Some(NSAppearanceNameAqua),
+            Ok("dark") => Some(NSAppearanceNameDarkAqua),
+            _ => match choice {
+                Appearance::Dark => Some(NSAppearanceNameDarkAqua),
+                Appearance::Light => Some(NSAppearanceNameAqua),
+                Appearance::System => None,
+            },
+        }
+    };
+    // The trait, not `Window::window_handle` (which is gpui's own `AnyWindowHandle`).
+    let Ok(handle) = HasWindowHandle::window_handle(window) else {
+        return;
+    };
+    let RawWindowHandle::AppKit(appkit) = handle.as_raw() else {
+        return;
+    };
+    // The handle is the window's content view; its `window` is the NSWindow itself. Both outlive
+    // this call.
+    let view = unsafe { appkit.ns_view.cast::<NSView>().as_ref() };
+    let Some(native) = view.window() else {
+        return;
+    };
+    let appearance = name.and_then(NSAppearance::appearanceNamed);
+    native.setAppearance(appearance.as_deref());
+}
+
+#[cfg(not(target_os = "macos"))]
+pub fn apply_appearance(_: &Window, _: Appearance) {}
+
 #[cfg(target_os = "windows")]
 mod windows {
     use super::*;

From 9e21868dfa012b3a46d3242d03e56845fb6fb5c5 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:46:45 +0100
Subject: [PATCH 058/270] Potions keep their potion across the connection

A server's client (single player on the server thread, LAN guests, a
dedicated server's players) saw every potion as an "Uncraftable Potion"
in the water colour: the server never wrote `minecraft:potion_contents`
and the client read past it. A potion taken from the creative menu also
reached the server without its potion, so it splashed as water.

PotionContents now goes as vanilla's stream codec writes it: the potion
by its `minecraft:potion` id and the custom colour, with the custom
effects and name kept as their bytes. The server writes it for every
stack it sends, the client reads it into the item's components, and a
creative pick and the server's read of it keep the potion too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan_actions.rs |  7 ++
 crates/horizon-client/src/game/remote.rs      | 24 +++++
 crates/horizon-client/src/lan/guest.rs        | 34 +++++++
 crates/horizon-protocol/src/item.rs           | 90 +++++++++++++++++++
 crates/horizon-protocol/src/item/skip.rs      |  8 +-
 5 files changed, 158 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..4964bc687 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1231,6 +1231,13 @@ impl Game<'_> {
                 }
             }
         }
+        if let Some(Component::Potion {
+            potion: Some(id), ..
+        }) = s.component(component::POTION_CONTENTS)
+            && let Some(potion) = host.hub.registry_name("minecraft:potion", *id)
+        {
+            out = out.with_potion(potion);
+        }
         Some(out)
     }
 
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a71b13a8..c723400a8 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -672,6 +672,16 @@ impl Game<'_> {
                     ("mob_factor", Tag::Float(v[5].to_bits())),
                 ]),
                 Component::Profile(p) => profile_tag(p),
+                // PotionContents' NBT: the potion by name and the custom colour.
+                Component::Potion { potion, color, .. } => {
+                    let potion = potion.and_then(|id| r.builtin.get("minecraft:potion")?.name(id));
+                    Tag::compound(
+                        potion
+                            .map(|name| ("potion", Tag::String(name.into())))
+                            .into_iter()
+                            .chain(color.map(|c| ("custom_color", Tag::Int(c)))),
+                    )
+                }
                 // ItemStackTemplate.CODEC: id, count and components.
                 Component::Stacks(stacks) => Tag::List(
                     stacks
@@ -733,6 +743,20 @@ impl Game<'_> {
     fn to_network(&self, s: &Option<ItemStack>) -> Option<Stack> {
         let s = s.as_ref()?;
         let mut stack = Stack::new(self.item_id(&s.item), s.count as i32);
+        // A creative pick keeps its potion (PotionContents by its builtin id).
+        if let Some(id) = s.potion().and_then(|p| {
+            let potions = self.remote.as_ref()?.builtin.get("minecraft:potion")?;
+            potions.id(&horizon_world::datafix::dynamic::namespaced(p))
+        }) {
+            stack.added.push((
+                horizon_protocol::item::component::POTION_CONTENTS,
+                horizon_protocol::item::Component::Potion {
+                    potion: Some(id),
+                    color: None,
+                    rest: Vec::new(),
+                },
+            ));
+        }
         if s.damage > 0 {
             stack.added.push((
                 horizon_protocol::item::component::DAMAGE,
diff --git a/crates/horizon-client/src/lan/guest.rs b/crates/horizon-client/src/lan/guest.rs
index 440b58284..bbab454d7 100644
--- a/crates/horizon-client/src/lan/guest.rs
+++ b/crates/horizon-client/src/lan/guest.rs
@@ -521,6 +521,22 @@ fn network_stack(
                 horizon_protocol::item::Component::Int(i32::from(mode)),
             ));
         }
+        // PotionContents: the potion by its `minecraft:potion` id.
+        if let Some(id) = (d.potion.as_deref()).and_then(|potion| {
+            synced_id(
+                "minecraft:potion",
+                &horizon_world::datafix::dynamic::namespaced(potion),
+            )
+        }) {
+            stack.added.push((
+                horizon_protocol::item::component::POTION_CONTENTS,
+                horizon_protocol::item::Component::Potion {
+                    potion: Some(id),
+                    color: None,
+                    rest: Vec::new(),
+                },
+            ));
+        }
         // A loaded crossbow's ammunition.
         if !d.charged.is_empty() {
             let charged = d
@@ -573,6 +589,24 @@ mod tests {
     use super::*;
     use horizon_protocol::item::{Component, component};
 
+    #[test]
+    fn potions_go_as_potion_registry_ids() {
+        let synced_id = |registry: &str, name: &str| match (registry, name) {
+            ("minecraft:potion", "minecraft:swiftness") => Some(14),
+            _ => None,
+        };
+        let potion = ItemStack::new("minecraft:splash_potion", 1).with_potion("swiftness");
+        let stack = stack_to_network(|_| 7, synced_id, &Some(potion)).unwrap();
+        assert_eq!(
+            stack.component(component::POTION_CONTENTS),
+            Some(&Component::Potion {
+                potion: Some(14),
+                color: None,
+                rest: Vec::new(),
+            })
+        );
+    }
+
     #[test]
     fn trims_go_as_synced_registry_references() {
         let mut chestplate = ItemStack::new("minecraft:diamond_chestplate", 1);
diff --git a/crates/horizon-protocol/src/item.rs b/crates/horizon-protocol/src/item.rs
index 6b6b845f8..2c04b5c61 100644
--- a/crates/horizon-protocol/src/item.rs
+++ b/crates/horizon-protocol/src/item.rs
@@ -35,6 +35,7 @@ pub mod component {
     pub const MAP_ID: i32 = 48;
     pub const MAP_POST_PROCESSING: i32 = 50;
     pub const CHARGED_PROJECTILES: i32 = 51;
+    pub const POTION_CONTENTS: i32 = 53;
     pub const WRITABLE_BOOK_CONTENT: i32 = 56;
     pub const WRITTEN_BOOK_CONTENT: i32 = 57;
     pub const TRIM: i32 = 58;
@@ -65,6 +66,13 @@ pub enum Component {
     Lore(Vec<Tag>),
     Enchantments(Vec<(i32, i32)>),
     AttackRange([f32; 6]),
+    /// `PotionContents`: the potion's `minecraft:potion` id and the custom
+    /// colour; the custom effects and name stay their encoded bytes.
+    Potion {
+        potion: Option<i32>,
+        color: Option<i32>,
+        rest: Vec<u8>,
+    },
     Profile(Profile),
     CustomModelData {
         floats: Vec<f32>,
@@ -162,6 +170,22 @@ impl Component {
                         .collect::<Result<_>>()?,
                 )
             }
+            POTION_CONTENTS => {
+                let potion = if r.bool()? { Some(r.varint()?) } else { None };
+                let color = if r.bool()? { Some(r.i32()?) } else { None };
+                let start = r.position();
+                skip::potion_effects_and_name(r)?;
+                // No custom effects and no name: an empty tail.
+                let rest = match r.since(start) {
+                    [0, 0] => Vec::new(),
+                    bytes => bytes.to_vec(),
+                };
+                Self::Potion {
+                    potion,
+                    color,
+                    rest,
+                }
+            }
             ATTACK_RANGE => {
                 let mut values = [0.0f32; 6];
                 for v in &mut values {
@@ -283,6 +307,27 @@ impl Component {
                 }
             }
             Self::AttackRange(values) => values.iter().for_each(|v| w.f32(*v)),
+            Self::Potion {
+                potion,
+                color,
+                rest,
+            } => {
+                w.bool(potion.is_some());
+                if let Some(id) = potion {
+                    w.varint(*id);
+                }
+                w.bool(color.is_some());
+                if let Some(color) = color {
+                    w.i32(*color);
+                }
+                // An empty tail is no custom effects and no name.
+                if rest.is_empty() {
+                    w.varint(0);
+                    w.bool(false);
+                } else {
+                    w.bytes(rest);
+                }
+            }
             Self::Profile(p) => {
                 w.u8(0);
                 w.bool(p.name.is_some());
@@ -532,6 +577,51 @@ mod tests {
         assert_eq!(r.remaining(), 0);
     }
 
+    #[test]
+    fn potion_contents_round_trip() {
+        let mut arrow = Stack::new(7, 3);
+        arrow.added.push((
+            component::POTION_CONTENTS,
+            Component::Potion {
+                potion: Some(31),
+                color: None,
+                rest: Vec::new(),
+            },
+        ));
+        round::<Option<Stack>, Slot>(Some(arrow));
+        // A custom colour, one custom effect (speed II for 600 ticks, shown,
+        // no hidden effect) and a custom name survive as they came.
+        let mut w = Writer::new();
+        w.bool(false);
+        w.bool(true);
+        w.i32(0x00FF_8800);
+        w.varint(1);
+        for v in [1, 1, 600] {
+            w.varint(v);
+        }
+        for b in [false, true, true, false] {
+            w.bool(b);
+        }
+        w.bool(true);
+        w.string("Tea");
+        let mut r = Reader::new(&w.data);
+        let read = Component::read(component::POTION_CONTENTS, &mut r).unwrap();
+        assert_eq!(r.remaining(), 0);
+        let Component::Potion {
+            potion,
+            color,
+            rest,
+        } = &read
+        else {
+            panic!("{read:?}");
+        };
+        assert_eq!((*potion, *color), (None, Some(0x00FF_8800)));
+        assert!(!rest.is_empty());
+        let mut again = Writer::new();
+        read.write(component::POTION_CONTENTS, &mut again);
+        assert_eq!(again.data, w.data);
+    }
+
     #[test]
     fn stacks_round_trip() {
         round::<Option<Stack>, Slot>(None);
diff --git a/crates/horizon-protocol/src/item/skip.rs b/crates/horizon-protocol/src/item/skip.rs
index 152d0f0f1..aa436cc31 100644
--- a/crates/horizon-protocol/src/item/skip.rs
+++ b/crates/horizon-protocol/src/item/skip.rs
@@ -87,7 +87,6 @@ pub(super) fn component(kind: i32, r: &mut Reader) -> Result<()> {
         }
         // BundleContents: templates.
         52 => list(r, template),
-        53 => potion_contents(r),
         // SuspiciousStewEffects: effect, duration.
         55 => list(r, |r| {
             varint(r)?;
@@ -410,10 +409,9 @@ fn kinetic_weapon(r: &mut Reader) -> Result<()> {
     optional(r, sound)?;
     optional(r, sound)
 }
-/// PotionContents: potion, customColor, customEffects, customName.
-fn potion_contents(r: &mut Reader) -> Result<()> {
-    optional(r, varint)?;
-    optional(r, i32)?;
+/// PotionContents' customEffects and customName (`Component::read` reads
+/// the potion and colour before them).
+pub(super) fn potion_effects_and_name(r: &mut Reader) -> Result<()> {
     list(r, mob_effect)?;
     optional(r, string)
 }

From 224b83c6a6ab13fb3d5876630c93f9346c3db22f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:48:03 +0100
Subject: [PATCH 059/270] Shader packs, clean room 36: the hand

A pack with gbuffers_hand (or textured_lit, textured, basic; spec 2.3)
draws the first-person hand and held items after the opaque world, into
its own buffers and the world's depth, without blending and with the
entities' 0.1 alpha cut. The vertices are Horizon's hand geometry, read
as entities are; `gl_ProjectionMatrix` is the hand's own projection (the
hand's field of view and bob) with depth scaled by MC_HAND_DEPTH, while
`gbufferProjection` stays the world's (5.2). Horizon's own hand draw is
skipped only when the pack draws it.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1;
no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              |  11 +-
 .../horizon-client/src/gfx/pack_entities.rs   |   2 +-
 crates/horizon-client/src/gfx/pack_hand.rs    | 169 ++++++++++++++++++
 crates/horizon-client/src/gfx/pack_post.rs    |  70 +++++++-
 crates/horizon-shaders/src/post.rs            |  32 +++-
 crates/horizon-shaders/tests/real_packs.rs    |   3 +-
 6 files changed, 282 insertions(+), 5 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_hand.rs

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index e2e71e036..9f048f19e 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -71,6 +71,7 @@ mod occlusion;
 mod pack_atlas;
 pub mod pack_draw;
 mod pack_entities;
+mod pack_hand;
 mod pack_post;
 mod pack_sky;
 mod pack_timing;
@@ -2825,6 +2826,7 @@ impl Renderer {
                     .map(|t| t.create_view(&Default::default())),
                 clouds: Some(&self.cloud_bindings),
                 weather: true,
+                hand: true,
             };
             pack_post::PackPost::new(
                 &self.device,
@@ -2851,6 +2853,7 @@ impl Renderer {
             entities: Some(pack_entities::inputs()),
             clouds: Some(pack_entities::cloud_inputs()),
             weather: Some(pack_weather::inputs()),
+            hand: Some(pack_hand::inputs()),
         }
     }
 
@@ -3806,6 +3809,12 @@ impl Renderer {
                 .as_ref()
                 .and_then(|p| p.1.as_ref())
                 .is_some_and(|p| p.has_clouds());
+        let pack_draws_hand = pack_post
+            && self
+                .pack_post
+                .as_ref()
+                .and_then(|p| p.1.as_ref())
+                .is_some_and(|p| p.has_hand());
         let pack_draws_weather = pack_post
             && self
                 .pack_post
@@ -4195,7 +4204,7 @@ impl Renderer {
         } else if scaled.is_some() {
             self.world_post.finish(&mut encoder, &view_target);
         }
-        if hand_quads > 0 {
+        if hand_quads > 0 && !pack_draws_hand {
             let attachments = [Some(wgpu::RenderPassColorAttachment {
                 view: &view_target,
                 resolve_target: None,
diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
index b06c45af6..ffc55149f 100644
--- a/crates/horizon-client/src/gfx/pack_entities.rs
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -356,7 +356,7 @@ impl PackEntities {
 }
 
 /// Two triangles for each of `quads` quads, from vertex 0.
-fn quad_indices(device: &wgpu::Device, quads: u32) -> wgpu::Buffer {
+pub(super) fn quad_indices(device: &wgpu::Device, quads: u32) -> wgpu::Buffer {
     let indices: Vec<u32> = (0..quads)
         .flat_map(|q| [0, 1, 2, 0, 2, 3].map(|i| q * 4 + i))
         .collect();
diff --git a/crates/horizon-client/src/gfx/pack_hand.rs b/crates/horizon-client/src/gfx/pack_hand.rs
new file mode 100644
index 000000000..096cc5bcf
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_hand.rs
@@ -0,0 +1,169 @@
+//! The first-person hand and held items drawn by a shader pack's `gbuffers_hand` (spec 2.3):
+//! `Frame::hand`'s entity vertices, read as entities are (`pack_entities::inputs`), with the
+//! hand's own projection as `gl_ProjectionMatrix` (5.2: `gbufferProjection` stays the world's).
+
+use glam::Mat4;
+
+use super::Vertex;
+
+/// `MC_HAND_DEPTH`'s value (1.5): the hand's depth is scaled by it through its projection, so
+/// that it sits in front of the world in the shared depth buffer.
+const HAND_DEPTH: f32 = 0.125;
+
+/// `HzHand`: the hand's projection and its inverse.
+const UNIFORM: u64 = 2 * 64;
+
+/// What `gbuffers_hand` reads: the entity inputs, and the hand's projection from set 1.
+pub fn inputs() -> horizon_shaders::GbuffersInputs {
+    let mut inputs = super::pack_entities::inputs();
+    inputs.declarations.push_str(
+        "layout(set = 1, binding = 1) uniform HzHand { mat4 hz_hand_projection; mat4 hz_hand_projection_inverse; };\n",
+    );
+    inputs.body.push_str(
+        "    hz_ProjectionMatrix = hz_hand_projection;\n    \
+         hz_ProjectionMatrixInverse = hz_hand_projection_inverse;\n    \
+         hz_ModelViewProjectionMatrix = hz_hand_projection * hz_ModelViewMatrix;\n",
+    );
+    inputs
+}
+
+/// The hand's projection in GL's conventions: `hud_fov` degrees, the view bob, depth scaled by
+/// `MC_HAND_DEPTH`.
+pub fn projection(hud_fov: f32, aspect: f32, far: f32, bob: Mat4) -> Mat4 {
+    Mat4::from_scale(glam::Vec3::new(1.0, 1.0, HAND_DEPTH))
+        * Mat4::perspective_rh_gl(hud_fov.to_radians(), aspect, 0.05, far)
+        * bob
+}
+
+/// The hand's vertices (also read at set 1 for normals and tangents), its uniform and quad
+/// indices.
+pub struct PackHand {
+    pub layout: wgpu::BindGroupLayout,
+    vertices: wgpu::Buffer,
+    uniform: wgpu::Buffer,
+    pub group: wgpu::BindGroup,
+    pub indices: wgpu::Buffer,
+    capacity: u32,
+    /// Quads uploaded this frame.
+    pub quads: u32,
+}
+
+impl PackHand {
+    pub fn new(device: &wgpu::Device) -> Self {
+        let entry = |binding, ty| wgpu::BindGroupLayoutEntry {
+            binding,
+            visibility: wgpu::ShaderStages::VERTEX,
+            ty: wgpu::BindingType::Buffer {
+                ty,
+                has_dynamic_offset: false,
+                min_binding_size: None,
+            },
+            count: None,
+        };
+        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("Shader pack hand"),
+            entries: &[
+                entry(0, wgpu::BufferBindingType::Storage { read_only: true }),
+                entry(1, wgpu::BufferBindingType::Uniform),
+            ],
+        });
+        let uniform = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack hand"),
+            size: UNIFORM,
+            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let capacity = 256;
+        let (vertices, group) = Self::vertex_buffer(device, &layout, &uniform, capacity);
+        Self {
+            indices: super::pack_entities::quad_indices(device, capacity),
+            layout,
+            vertices,
+            uniform,
+            group,
+            capacity,
+            quads: 0,
+        }
+    }
+
+    fn vertex_buffer(
+        device: &wgpu::Device,
+        layout: &wgpu::BindGroupLayout,
+        uniform: &wgpu::Buffer,
+        quads: u32,
+    ) -> (wgpu::Buffer, wgpu::BindGroup) {
+        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Shader pack hand vertices"),
+            size: u64::from(quads) * 4 * std::mem::size_of::<Vertex>() as u64,
+            usage: wgpu::BufferUsages::VERTEX
+                | wgpu::BufferUsages::STORAGE
+                | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+            label: Some("Shader pack hand"),
+            layout,
+            entries: &[
+                wgpu::BindGroupEntry {
+                    binding: 0,
+                    resource: buffer.as_entire_binding(),
+                },
+                wgpu::BindGroupEntry {
+                    binding: 1,
+                    resource: uniform.as_entire_binding(),
+                },
+            ],
+        });
+        (buffer, group)
+    }
+
+    /// Uploads this frame's hand and its projection.
+    pub fn prepare(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        hand: &[Vertex],
+        projection: Mat4,
+    ) {
+        self.quads = (hand.len() / 4) as u32;
+        if self.quads == 0 {
+            return;
+        }
+        if self.quads > self.capacity {
+            self.capacity = self.quads.next_power_of_two();
+            (self.vertices, self.group) =
+                Self::vertex_buffer(device, &self.layout, &self.uniform, self.capacity);
+            self.indices = super::pack_entities::quad_indices(device, self.capacity);
+        }
+        queue.write_buffer(&self.vertices, 0, bytemuck::cast_slice(hand));
+        let matrices = [projection, projection.inverse()].map(|m| m.to_cols_array());
+        queue.write_buffer(&self.uniform, 0, bytemuck::cast_slice(&matrices));
+    }
+
+    pub fn vertices(&self) -> wgpu::BufferSlice<'_> {
+        self.vertices.slice(..)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The hand's window depth lies within `MC_HAND_DEPTH` of the middle (packs tell the hand
+    /// apart by it), and x, y match the plain projection.
+    #[test]
+    fn hand_depth_is_scaled_around_the_middle() {
+        let p = projection(70.0, 16.0 / 9.0, 512.0, Mat4::IDENTITY);
+        let plain = Mat4::perspective_rh_gl(70f32.to_radians(), 16.0 / 9.0, 0.05, 512.0);
+        for z in [-0.06f32, -0.5, -3.0, -400.0] {
+            let v = glam::Vec4::new(0.1, -0.2, z, 1.0);
+            let (a, b) = (p * v, plain * v);
+            let window = (a.z / a.w) * 0.5 + 0.5;
+            assert!(
+                (window - 0.5).abs() <= HAND_DEPTH * 0.5 + 1e-6,
+                "{z}: {window}"
+            );
+            assert!((a.x / a.w - b.x / b.w).abs() < 1e-6);
+        }
+    }
+}
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index f6f87cbb8..57c24b1ed 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -208,6 +208,8 @@ pub(super) struct World<'a> {
     pub clouds: Option<&'a wgpu::BindGroupLayout>,
     /// The game can hand its rain and snow to the pack.
     pub weather: bool,
+    /// The game can hand its first-person hand to the pack.
+    pub hand: bool,
 }
 
 /// This frame's clouds, when the pack draws them: their vertices, uniform, quad indices and
@@ -251,6 +253,9 @@ pub struct PackPost {
     weather: Option<[Pass; 2]>,
     weather_draw: Option<Weather>,
     weather_generation: u64,
+    /// What draws the first-person hand (`gbuffers_hand` or its fallback), after the opaque
+    /// world, and its vertices.
+    hand: Option<(Pass, super::pack_hand::PackHand)>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
     /// Buffers with mipmaps (filterable ones a program asks them for).
@@ -997,6 +1002,18 @@ impl PackPost {
             ids: None,
             cull: false,
         });
+        let hand_geometry = world.hand.then(|| super::pack_hand::PackHand::new(device));
+        let hand = post.hand.zip(hand_geometry).and_then(|(p, geometry)| {
+            let g = Geometry {
+                buffers: &entity_buffers,
+                table: Some(&geometry.layout),
+                depth_write: true,
+                atlas: world.celestial.clone(),
+                ids: None,
+                cull: false,
+            };
+            build(p, Some(&g)).map(|pass| (pass, geometry))
+        });
         let weather = post
             .weather
             .zip(weather_geometry.as_ref())
@@ -1041,6 +1058,9 @@ impl PackPost {
         if let Some(c) = &clouds {
             notes.push(format!("clouds draw with {}", c.name));
         }
+        if let Some((h, _)) = &hand {
+            notes.push(format!("the hand draws with {}", h.name));
+        }
         if let Some([w, _]) = &weather {
             notes.push(format!("rain and snow draw with {}", w.name));
         }
@@ -1071,6 +1091,7 @@ impl PackPost {
                 .chain(&clouds)
                 .chain(&water)
                 .chain(weather.iter().take(1).flatten())
+                .chain(hand.iter().map(|h| &h.0))
                 .find(touched)
                 .map(|_| true)
                 .or_else(|| {
@@ -1088,6 +1109,7 @@ impl PackPost {
             || entities.is_some()
             || clouds.is_some()
             || weather.is_some()
+            || hand.is_some()
             || passes.iter().any(|p| {
                 p.samplers
                     .iter()
@@ -1190,6 +1212,7 @@ impl PackPost {
             weather,
             weather_draw: None,
             weather_generation: 0,
+            hand,
             depth1,
             mipped,
             mips_valid: 0,
@@ -1607,6 +1630,50 @@ impl PackPost {
         self.draw_terrain(device, queue, encoder, size, false, terrain);
         self.draw_entities(device, queue, encoder, size, false);
         self.draw_clouds(device, queue, encoder, size);
+        self.draw_hand(device, queue, encoder, size, frame);
+    }
+
+    /// The first-person hand and held items, with `gbuffers_hand` at the hand's projection.
+    fn draw_hand(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+        frame: &super::Frame,
+    ) {
+        let Some((mut pass, mut geometry)) = self.hand.take() else {
+            return;
+        };
+        let projection = super::pack_hand::projection(
+            frame.hand_fov_degrees,
+            size[0] as f32 / size[1].max(1) as f32,
+            frame.depth_far,
+            frame.bob,
+        );
+        geometry.prepare(device, queue, frame.hand, projection);
+        if geometry.quads > 0 {
+            let group = self.bind(device, queue, &mut pass, size);
+            {
+                let mut rp = self.begin(encoder, &pass);
+                rp.set_pipeline(&pass.pipeline);
+                rp.set_bind_group(0, &group, &[]);
+                rp.set_bind_group(1, &geometry.group, &[]);
+                if pass.draw {
+                    self.draws.bind(&mut rp, "HAND_SOLID");
+                }
+                rp.set_vertex_buffer(0, geometry.vertices());
+                rp.set_index_buffer(geometry.indices.slice(..), wgpu::IndexFormat::Uint32);
+                rp.draw_indexed(0..geometry.quads * 6, 0, 0..1);
+            }
+            self.mips_valid &= !pass.written;
+        }
+        self.hand = Some((pass, geometry));
+    }
+
+    /// Whether the pack draws the first-person hand itself.
+    pub fn has_hand(&self) -> bool {
+        self.hand.is_some()
     }
 
     /// The clouds `set_clouds` gave for this frame, with `gbuffers_clouds`.
@@ -2018,7 +2085,8 @@ impl PackPost {
         let mut terrain_drawn = self.terrain.is_none()
             && self.sky.is_none()
             && self.entities.is_none()
-            && self.clouds.is_none();
+            && self.clouds.is_none()
+            && self.hand.is_none();
         let late_entities = self.entities.as_ref().is_some_and(|e| {
             e.passes
                 .iter()
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 5a7ea1472..9beb7f06a 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -123,6 +123,14 @@ const BLOCK: [&str; 5] = [
 /// `gbuffers_clouds`: no fallback, the game draws its clouds otherwise (OQ-3).
 const CLOUDS: [&str; 1] = ["gbuffers_clouds"];
 
+/// `gbuffers_hand` and its fallbacks (2.3).
+const HAND: [&str; 4] = [
+    "gbuffers_hand",
+    "gbuffers_textured_lit",
+    "gbuffers_textured",
+    "gbuffers_basic",
+];
+
 /// `gbuffers_weather` and its fallbacks (2.3).
 const WEATHER: [&str; 4] = [
     "gbuffers_weather",
@@ -206,6 +214,8 @@ pub struct Post {
     pub clouds: Option<PostProgram>,
     /// What draws rain and snow, after deferred.
     pub weather: Option<PostProgram>,
+    /// What draws the first-person hand and held items.
+    pub hand: Option<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
     pub translucent_late: bool,
     /// Particles draw after deferred (`particles.ordering`, `particles.before.deferred`, 3.2).
@@ -241,6 +251,8 @@ pub struct GameInputs {
     pub clouds: Option<GbuffersInputs>,
     /// Rain and snow.
     pub weather: Option<GbuffersInputs>,
+    /// The first-person hand and held items.
+    pub hand: Option<GbuffersInputs>,
 }
 
 /// Loads the post-processing programs of `folder` and, for the geometry `inputs` describes, the
@@ -267,6 +279,7 @@ pub fn load_post(
         particles: None,
         clouds: None,
         weather: None,
+        hand: None,
         translucent_late: false,
         particles_late: false,
         custom: Custom::parse(properties),
@@ -381,6 +394,15 @@ pub fn load_post(
         p.blend = blend(properties, &p.name).unwrap_or(Some(TRANSLUCENT_BLEND));
         p
     });
+    // The hand draws as entities do: no blending unless `blend.*` says otherwise (OQ-23).
+    let hand = inputs
+        .hand
+        .as_ref()
+        .and_then(|i| gbuffers(&HAND, Group::Gbuffers, i))
+        .map(|mut p| {
+            p.blend = blend(properties, &p.name).flatten();
+            p
+        });
     if let Some(inputs) = &inputs.terrain {
         let terrain = gbuffers(&TERRAIN, Group::Gbuffers, inputs);
         // gbuffers_water falls back to gbuffers_terrain's chain (2.3).
@@ -402,6 +424,7 @@ pub fn load_post(
     loader.post.particles = particles;
     loader.post.clouds = clouds;
     loader.post.weather = weather;
+    loader.post.hand = hand;
     let flag = |key: &str| properties.get(key).map(|v| v.trim() == "true");
     loader.post.translucent_late = flag("separateEntityDraws").unwrap_or(false);
     // `after` when the pack has a deferred program, else `mixed`; ours are all translucent, so
@@ -691,7 +714,8 @@ mod tests {
             celestial: Some(inputs.clone()),
             entities: Some(inputs.clone()),
             clouds: Some(inputs.clone()),
-            weather: Some(inputs),
+            weather: Some(inputs.clone()),
+            hand: Some(inputs),
         };
         let post = load_post(&pack, "", &Properties::default(), &macros, &inputs);
         let (terrain, water) = (post.terrain.unwrap(), post.water.unwrap());
@@ -741,6 +765,12 @@ mod tests {
         assert!(post.particles_late && !post.translucent_late);
         // gbuffers_clouds has no fallback (OQ-3): without it the game draws its clouds.
         assert!(post.clouds.is_none());
+        // The hand falls back to gbuffers_textured and does not blend.
+        let hand = post.hand.as_ref().unwrap();
+        assert_eq!(
+            (hand.name.as_str(), hand.group, hand.blend),
+            ("gbuffers_textured", Group::Gbuffers, None)
+        );
         // Weather falls back to gbuffers_textured, after deferred, blended.
         let weather = post.weather.as_ref().unwrap();
         assert_eq!(
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 41323d440..747b732d7 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -175,7 +175,8 @@ fn real_packs_read() {
                 celestial: Some(terrain.clone()),
                 entities: Some(terrain.clone()),
                 clouds: Some(terrain.clone()),
-                weather: Some(terrain),
+                weather: Some(terrain.clone()),
+                hand: Some(terrain),
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(

From 40c77c02f0332188ae7622dd7b2ae842df5becb7 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:15:19 +0100
Subject: [PATCH 060/270] PalettedContainer: look up a word's filled bits, not
 divide for them

`locate` found an entry's word by multiplication (the MAGIC table) but
still divided `64 / bits` at run time for the shift, on every block read
and write of a section stored in 5, 6 or 7 bits. A division by a value the
compiler does not know costs tens of cycles on x86: `perf annotate` of a
10-bot server on the ThinkPad put 12% of `PalettedContainer::get`, the
server thread's top function, on that `div`. The table now also holds the
bits a word's entries fill, so the shift is `i * bits - word * filled`.
A test checks `locate` against the division for every width and entry.

ThinkPad (i5-7200U), 4M random reads, 5-7 bit palettes: 28.5-36.9 ->
24.6-32.4 ns over 2,000 sections, 6.7-7.1 -> 5.4-5.8 ns within one;
4 and 8 bits (shifts, unchanged) the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-core/src/paletted.rs | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-core/src/paletted.rs b/crates/horizon-core/src/paletted.rs
index 802eac225..9aa4aec6a 100644
--- a/crates/horizon-core/src/paletted.rs
+++ b/crates/horizon-core/src/paletted.rs
@@ -106,14 +106,16 @@ enum Palette {
     List(Vec<u32>),
     Global,
 }
-/// `n / per_word` for `n < 4096` by multiplication: `MAGIC[bits] = ceil(2^20 /
-/// (64 / bits))` is exact while `n * (64 / bits) < 2^20`.
-const MAGIC: [u32; 33] = {
-    let mut table = [0; 33];
+/// `n / per_word` for `n < 4096` by multiplication: `MAGIC[bits].0 = ceil(2^20 /
+/// (64 / bits))` is exact while `n * (64 / bits) < 2^20`. `.1` is the bits a
+/// word's entries fill (`64 / bits * bits`): looked up, not divided for, as a
+/// division by a run-time value costs tens of cycles on x86.
+const MAGIC: [(u32, u32); 33] = {
+    let mut table = [(0, 0); 33];
     let mut bits = 1;
     while bits <= 32 {
         let per = 64 / bits as u32;
-        table[bits] = (1u32 << 20).div_ceil(per);
+        table[bits] = ((1u32 << 20).div_ceil(per), per * bits as u32);
         bits += 1;
     }
     table
@@ -134,9 +136,9 @@ fn locate(bits: u8, i: usize) -> (usize, u32) {
         let word = i >> (6 - log);
         (word, ((i & ((64 >> log) - 1)) as u32) << log)
     } else {
-        let per = 64 / u32::from(bits);
-        let word = (i as u32 * MAGIC[usize::from(bits)]) >> 20;
-        (word as usize, (i as u32 - word * per) * u32::from(bits))
+        let (magic, filled) = MAGIC[usize::from(bits)];
+        let word = (i as u32 * magic) >> 20;
+        (word as usize, i as u32 * u32::from(bits) - word * filled)
     }
 }
 #[inline]
@@ -720,6 +722,17 @@ mod tests {
     use super::*;
     const BLOCKS: Strategy = Strategy::blocks(16);
     const BIOMES: Strategy = Strategy::biomes(7);
+
+    #[test]
+    fn locate_matches_division_for_every_width() {
+        for bits in 1..=32u8 {
+            let per = 64 / usize::from(bits);
+            for i in 0..4096 {
+                let expected = (i / per, ((i % per) * usize::from(bits)) as u32);
+                assert_eq!(locate(bits, i), expected, "{bits} bits, entry {i}");
+            }
+        }
+    }
     fn rng(state: &mut u64) -> u64 {
         *state ^= *state << 13;
         *state ^= *state >> 7;

From 87b3c9aa38e5568733a2678d0332ad33e0e792e3 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 13:51:12 +0100
Subject: [PATCH 061/270] Drop the stale craft grid when a remote menu closes

The server's AbstractContainerMenu.removed gives the grid and the
carried stack back to the inventory and syncs those slots, but the
client kept its copies: a crafting table closed with items inside left
ghost stacks in the inventory's 2x2 grid that could not be picked up.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/remote.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a71b13a8..d8148f77f 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -4783,6 +4783,11 @@ impl Game<'_> {
         self.mount_menu_reset();
         // The client's menu has no level access: what it holds is the server's.
         self.station = None;
+        // AbstractContainerMenu.removed: the server gives the grid and the
+        // carried stack back to the inventory and syncs it; the copies here
+        // are stale the moment the window closes.
+        self.craft_grid.fill(None);
+        self.carried = None;
         self.craft_size = 2;
         if let Some(key) = self.container.take() {
             // Server containers stay renderable but lose their copied slots.

From df626cf2f381ff11ff72a2e7d3793e7078291cca Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:15:28 +0100
Subject: [PATCH 062/270] A tool that changes a block ends the click on a
 server's client

On a server's client (single player on the server thread, LAN guests), a
shovel making a path, an axe stripping, a hoe tilling or honeycomb waxing
did not end the right click: the client went on to the other hand, so an
off-hand torch was predicted as placed and its hand swung instead of the
tool's (#1289).

Vanilla's client runs `Item.useOn` itself: its SUCCESS swings that hand
and `Minecraft.startUseItem` returns before the off hand. The client now
does the same when its prediction of the tool's use succeeds.

Fixes #1289

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/remote.rs | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index c1ef53122..8edfd77a2 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -4000,8 +4000,14 @@ impl Game<'_> {
             }
             if reacts {
                 self.predict_use(&changes, seq);
-            } else if let Some(stack) = held.as_ref() {
-                self.predict_item_on_block(stack, &hit);
+            } else if let Some(stack) = held.as_ref()
+                && self.predict_item_on_block(stack, &hit)
+            {
+                // Item.useOn succeeded here (InteractionResult.SUCCESS):
+                // this hand swings and the click ends, so the other hand
+                // (a shield, a torch) is never tried.
+                self.with_hand(hand, Game::swing_arm);
+                return true;
             }
             if held_block {
                 let placed = if reacts {
@@ -4031,7 +4037,8 @@ impl Game<'_> {
     /// `playSound(player, ...)`: the server sends them to the others only):
     /// honeycomb waxing copper, and an axe, hoe or shovel transforming a
     /// block (stripping, scraping, removing wax, tilling, making a path).
-    fn predict_item_on_block(&mut self, stack: &ItemStack, hit: &super::Hit) {
+    /// Whether the item's use succeeded, which ends the click.
+    fn predict_item_on_block(&mut self, stack: &ItemStack, hit: &super::Hit) -> bool {
         let at = [
             f64::from(hit.pos[0]) + 0.5,
             f64::from(hit.pos[1]) + 0.5,
@@ -4050,11 +4057,15 @@ impl Game<'_> {
                 self.audio
                     .play("minecraft:item.honeycomb.wax_on", Some(at), 1.0, 1.0);
             }
+            waxes
         } else if let Some((_, sound, _, _, particle)) =
             self.block_transform(stack, hit.pos, hit.face)
         {
             self.transform_particle(&particle, hit.pos);
             self.audio.play(&sound, Some(at), 1.0, 1.0);
+            true
+        } else {
+            false
         }
     }
 

From 41b799042acb262601e6a3e2695a5a3e68b4e618 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 14:26:55 +0100
Subject: [PATCH 063/270] Sync mobs' aggressive and item-use flags so clients
 pose them right

Mob.DATA_MOB_FLAGS_ID's aggressive bit and LivingEntity's
DATA_LIVING_ENTITY_FLAGS never reached a client for mobs: on the
server thread and for LAN guests a skeleton kept its arms down while
its arrows flew, and a drawn bow never pulled. Send both entries (with
their defaults so a flag going back to 0 is sent too), decode them for
every mob, and let a remote mob's item-use ticks count up as
LivingEntity.updatingUsingItem does. The same entries drive the zombie
arms, the vindicator's axe, the drowned's trident and the spellcasters'
poses, so the pillager's charging and evoker's/illusioner's casting
entries go with them. A left-handed mob now mirrors the pose and the
held item (Mob.getMainArm), and a bow in the off hand counts for
LivingEntity.isHolding.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/lan.rs         | 28 +++++++-
 crates/horizon-client/src/game/mob_blocks.rs  |  4 +-
 crates/horizon-client/src/game/remote.rs      | 67 +++++++------------
 .../src/game/remote_mob_data.rs               | 63 +++++++++++++++++
 crates/horizon-client/src/mobs.rs             |  5 ++
 crates/horizon-client/src/mobs/anim.rs        |  4 +-
 crates/horizon-client/src/mobs/undead.rs      |  5 ++
 7 files changed, 127 insertions(+), 49 deletions(-)

diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs
index 8460f54e6..522c6f1d3 100644
--- a/crates/horizon-client/src/game/lan.rs
+++ b/crates/horizon-client/src/game/lan.rs
@@ -162,17 +162,26 @@ fn mob_meta(
             meta.push((3, serializer::BOOLEAN, Value::Bool(true)));
         }
     }
+    // LivingEntity.DATA_LIVING_ENTITY_FLAGS: using an item 1, in the off
+    // hand 2 (a skeleton draws its bow, a witch raises her potion).
+    let using = i8::from(m.extra.using_item > 0) | i8::from(m.extra.using_off_hand) << 1;
+    if using != 0 {
+        meta.push((8, serializer::BYTE, Value::Byte(using)));
+    }
+    defaults.push((8, serializer::BYTE, Value::Byte(0)));
     // LivingEntity.DATA_HEALTH_ID: defined as 1, then set to the max health.
     let health = m.health.max(0.0);
     if health != 1.0 {
         meta.push((9, serializer::FLOAT, Value::Float(health)));
     }
     defaults.push((9, serializer::FLOAT, Value::Float(1.0)));
-    // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2.
-    let flags = i8::from(m.no_ai) | i8::from(m.extra.left_handed) << 1;
+    // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2, aggressive 4.
+    let flags =
+        i8::from(m.no_ai) | i8::from(m.extra.left_handed) << 1 | i8::from(m.ai.aggressive) << 2;
     if flags != 0 {
         meta.push((15, serializer::BYTE, Value::Byte(flags)));
     }
+    defaults.push((15, serializer::BYTE, Value::Byte(0)));
     // AgeableMob.DATA_BABY_ID (and Zombie's, Piglin's).
     if let Some(index) = baby_index(kind) {
         if m.is_baby() {
@@ -289,6 +298,21 @@ fn mob_meta(
                 meta.push((18, serializer::BOOLEAN, Value::Bool(true)));
             }
         }
+        // Pillager.IS_CHARGING_CROSSBOW: the charge pose and the held
+        // item's loading animation.
+        "minecraft:pillager" => {
+            if e.flag {
+                meta.push((17, serializer::BOOLEAN, Value::Bool(true)));
+            }
+            defaults.push((17, serializer::BOOLEAN, Value::Bool(false)));
+        }
+        // SpellcasterIllager.DATA_SPELL_CASTING_ID: the casting pose.
+        "minecraft:evoker" | "minecraft:illusioner" => {
+            if e.variant2 != 0 {
+                meta.push((17, serializer::BYTE, Value::Byte(e.variant2 as i8)));
+            }
+            defaults.push((17, serializer::BYTE, Value::Byte(0)));
+        }
         // Enderman.DATA_CARRY_STATE.
         "minecraft:enderman" => {
             if let Some(state) = e.carried {
diff --git a/crates/horizon-client/src/game/mob_blocks.rs b/crates/horizon-client/src/game/mob_blocks.rs
index a9e854bfb..083c96a66 100644
--- a/crates/horizon-client/src/game/mob_blocks.rs
+++ b/crates/horizon-client/src/game/mob_blocks.rs
@@ -259,7 +259,7 @@ impl Game<'_> {
         // ItemInHandLayer submits with OverlayTexture.NO_OVERLAY: no hurt tint.
         for (item, off_hand) in [(&mob.extra.main_hand, false), (&mob.extra.off_hand, true)] {
             let Some(item) = item else { continue };
-            let left = off_hand != mob.extra.main_hand_left;
+            let left = off_hand != mob.main_arm_left();
             let Some(t) =
                 render::held_item_transform(mob, alpha as f32, camera, self.res.mob_data(), left)
             else {
@@ -305,7 +305,7 @@ impl Game<'_> {
                     .player_model
                     .as_ref()
                     .is_some_and(|p| std::ptr::eq(p, mob));
-            owner.main_arm_left = mob.extra.main_hand_left;
+            owner.main_arm_left = mob.main_arm_left();
             if off_hand == mob.extra.using_off_hand && mob.extra.using_item > 0 {
                 owner.using_this_item = true;
                 owner.use_duration = 72_000;
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index dc3ce5de9..ae5d25a44 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1994,15 +1994,6 @@ impl Game<'_> {
                         }
                     }
                 }
-                if let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32)
-                    && m.species() == horizon_client::mobs::Species::Rabbit
-                {
-                    for (index, _, value) in &p.values {
-                        if let (15, Value::Byte(flags)) = (index, value) {
-                            m.no_ai = flags & 1 != 0;
-                        }
-                    }
-                }
                 self.remote_mob_data(p.id, &p.values);
                 if let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32)
                     && m.species() == horizon_client::mobs::Species::Creeper
@@ -2017,25 +2008,12 @@ impl Game<'_> {
                         }
                     }
                 }
-                // LivingEntity.onSyncedDataUpdated(DATA_LIVING_ENTITY_FLAGS):
-                // another player starts using the item in a hand (eating, a
-                // bow drawn, a shield up), or stops.
+                // LivingEntity.DATA_LIVING_ENTITY_FLAGS: for another player
+                // too, remote_mob_data's apply reads index 8 above.
                 let other = self
                     .remote
                     .as_ref()
                     .is_some_and(|r| r.level_players.contains_key(&p.id) && r.entity_id != p.id);
-                if other && let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32) {
-                    for (index, _, value) in &p.values {
-                        if let (8, Value::Byte(flags)) = (index, value) {
-                            m.extra.using_off_hand = flags & 2 != 0;
-                            if flags & 1 == 0 {
-                                m.extra.using_item = 0;
-                            } else if m.extra.using_item == 0 {
-                                m.extra.using_item = 1;
-                            }
-                        }
-                    }
-                }
                 // LivingEntity.onSyncedDataUpdated(SLEEPING_POS_ID): another
                 // player lies down in their bed (drawn lying in it), or gets up.
                 if other {
@@ -3520,25 +3498,28 @@ impl Game<'_> {
                 m.head_yaw += wrap_degrees(*yaw - m.head_yaw) / *steps as f32;
                 *steps -= 1;
             }
-            // LivingEntity.updatingUsingItem for another player: the ticks the
-            // item has been used before this one.
-            if player && m.extra.using_item > 0 {
-                let item = if m.extra.using_off_hand {
-                    m.extra.off_hand.clone()
-                } else {
-                    m.extra.main_hand.clone()
-                };
-                if let Some(item) = item {
-                    let eye = if m.extra.crouching { 1.27 } else { 1.62 };
-                    let at = [m.position.x, m.position.y, m.position.z];
-                    using.push((
-                        item,
-                        m.extra.using_item as u32 - 1,
-                        at,
-                        eye,
-                        m.head_pitch,
-                        m.yaw,
-                    ));
+            // LivingEntity.updatingUsingItem: the ticks the item has been
+            // used before this one. Another player's use particles; a mob's
+            // drawn bow only needs the count (its pull follows it).
+            if m.extra.using_item > 0 {
+                if player {
+                    let item = if m.extra.using_off_hand {
+                        m.extra.off_hand.clone()
+                    } else {
+                        m.extra.main_hand.clone()
+                    };
+                    if let Some(item) = item {
+                        let eye = if m.extra.crouching { 1.27 } else { 1.62 };
+                        let at = [m.position.x, m.position.y, m.position.z];
+                        using.push((
+                            item,
+                            m.extra.using_item as u32 - 1,
+                            at,
+                            eye,
+                            m.head_pitch,
+                            m.yaw,
+                        ));
+                    }
                 }
                 m.extra.using_item += 1;
             }
diff --git a/crates/horizon-client/src/game/remote_mob_data.rs b/crates/horizon-client/src/game/remote_mob_data.rs
index 5573d0f87..5d024cd84 100644
--- a/crates/horizon-client/src/game/remote_mob_data.rs
+++ b/crates/horizon-client/src/game/remote_mob_data.rs
@@ -20,9 +20,27 @@ fn apply(m: &mut Mob, values: &[(u8, i32, Value)], builtin: &Builtin) {
             // client, which draws the flames. A client doesn't count the
             // fire down: the flag goes off when the server's fire is out.
             (0, Value::Byte(flags)) => m.fire_ticks = i32::from(flags & 1),
+            // LivingEntity.DATA_LIVING_ENTITY_FLAGS: using an item 1, in the
+            // off hand 2. The flag starts and stops the use; the client ticks
+            // the count itself (a bow's pull follows it).
+            (8, Value::Byte(flags)) => {
+                m.extra.using_off_hand = flags & 2 != 0;
+                if flags & 1 == 0 {
+                    m.extra.using_item = 0;
+                } else if m.extra.using_item == 0 {
+                    m.extra.using_item = 1;
+                }
+            }
             // LivingEntity.DATA_HEALTH_ID: the boss bars and the death
             // animation follow it.
             (9, Value::Float(health)) => m.health = *health,
+            // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2, aggressive 4.
+            // A skeleton raises its bow and a zombie its arms on the last bit.
+            (15, Value::Byte(flags)) => {
+                m.no_ai = flags & 1 != 0;
+                m.extra.left_handed = flags & 2 != 0;
+                m.ai.aggressive = flags & 4 != 0;
+            }
             (i, Value::Bool(b)) if Some(i) == baby => m.extra.age = if *b { -1 } else { 0 },
             _ => {}
         }
@@ -45,6 +63,13 @@ fn apply(m: &mut Mob, values: &[(u8, i32, Value)], builtin: &Builtin) {
             (Species::Slime | Species::MagmaCube, 18, Value::Int(size)) => {
                 m.extra.size = (*size).clamp(1, 127);
             }
+            // Pillager.IS_CHARGING_CROSSBOW: the charge pose (Raider's
+            // IS_CELEBRATING takes 16).
+            (Species::Pillager, 17, Value::Bool(charging)) => m.extra.flag = *charging,
+            // SpellcasterIllager.DATA_SPELL_CASTING_ID: the casting pose.
+            (Species::Evoker | Species::Illusioner, 17, Value::Byte(spell)) => {
+                m.extra.variant2 = (*spell).max(0) as u8;
+            }
             // Villager.DATA_VILLAGER_DATA and ZombieVillager's (after
             // Zombie's three): what VillagerProfessionLayer draws.
             (Species::Villager, 19, Value::Ids(data))
@@ -218,4 +243,42 @@ mod tests {
         );
         assert_eq!(name(&z), ("desert", "farmer", 3));
     }
+
+    #[test]
+    fn the_mob_flags_drive_the_aggressive_poses() {
+        let Some(mut m) = mob("minecraft:skeleton") else {
+            return;
+        };
+        apply(&mut m, &[(15, s::BYTE, Value::Byte(2 | 4))]);
+        assert!(m.ai.aggressive && m.extra.left_handed && !m.no_ai);
+        apply(&mut m, &[(15, s::BYTE, Value::Byte(0))]);
+        assert!(!m.ai.aggressive && !m.extra.left_handed);
+    }
+
+    #[test]
+    fn the_living_flags_start_and_stop_a_mob_using_an_item() {
+        let Some(mut m) = mob("minecraft:skeleton") else {
+            return;
+        };
+        apply(&mut m, &[(8, s::BYTE, Value::Byte(1))]);
+        assert_eq!(m.extra.using_item, 1);
+        assert!(!m.extra.using_off_hand);
+        // Using in the off hand.
+        apply(&mut m, &[(8, s::BYTE, Value::Byte(3))]);
+        assert!(m.extra.using_off_hand);
+        apply(&mut m, &[(8, s::BYTE, Value::Byte(0))]);
+        assert_eq!(m.extra.using_item, 0);
+    }
+
+    #[test]
+    fn a_pillager_charges_and_a_spellcaster_casts() {
+        let Some(mut p) = mob("minecraft:pillager") else {
+            return;
+        };
+        apply(&mut p, &[(17, s::BOOLEAN, Value::Bool(true))]);
+        assert!(p.extra.flag);
+        let mut e = mob("minecraft:evoker").unwrap();
+        apply(&mut e, &[(17, s::BYTE, Value::Byte(2))]);
+        assert_eq!(e.extra.variant2, 2);
+    }
 }
diff --git a/crates/horizon-client/src/mobs.rs b/crates/horizon-client/src/mobs.rs
index 4e3879fe5..1a124b6de 100644
--- a/crates/horizon-client/src/mobs.rs
+++ b/crates/horizon-client/src/mobs.rs
@@ -1646,6 +1646,11 @@ impl Mob {
     pub fn species(&self) -> Species {
         self.kind.species
     }
+    /// `Mob.getMainArm`: the left arm when the mob is left-handed, a player's
+    /// `mainHand` option for a player mob.
+    pub fn main_arm_left(&self) -> bool {
+        self.extra.main_hand_left || self.extra.left_handed
+    }
     /// The player hit this mob (melee): LivingEntity.hurt with knockback.
     pub fn hurt(
         &mut self,
diff --git a/crates/horizon-client/src/mobs/anim.rs b/crates/horizon-client/src/mobs/anim.rs
index aa0d8fb2a..b2158132b 100644
--- a/crates/horizon-client/src/mobs/anim.rs
+++ b/crates/horizon-client/src/mobs/anim.rs
@@ -642,7 +642,7 @@ pub fn setup(
             } else {
                 ArmPose::Empty
             };
-            let mut h = if m.extra.main_hand_left {
+            let mut h = if m.main_arm_left() {
                 Hum::new(ArmPose::Empty, main)
             } else {
                 Hum::new(main, ArmPose::Empty)
@@ -693,7 +693,7 @@ pub fn setup(
             } else {
                 ArmPose::Empty
             };
-            let mut h = if m.extra.main_hand_left {
+            let mut h = if m.main_arm_left() {
                 Hum::new(off, pose)
             } else {
                 Hum::new(pose, off)
diff --git a/crates/horizon-client/src/mobs/undead.rs b/crates/horizon-client/src/mobs/undead.rs
index 197321dea..e77a37641 100644
--- a/crates/horizon-client/src/mobs/undead.rs
+++ b/crates/horizon-client/src/mobs/undead.rs
@@ -621,8 +621,10 @@ impl BowAttack {
         }
     }
 }
+/// `LivingEntity.isHolding(Items.BOW)`: the bow can sit in either hand.
 fn holding_bow(m: &Mob) -> bool {
     m.extra.main_hand.as_deref() == Some("minecraft:bow")
+        || m.extra.off_hand.as_deref() == Some("minecraft:bow")
 }
 impl Goal for BowAttack {
     goal_clone!();
@@ -715,7 +717,10 @@ impl Goal for BowAttack {
         } else {
             self.attack_time -= 1;
             if self.attack_time <= 0 && self.see_time >= -60 {
+                // mob.startUsingItem(ProjectileUtil.getWeaponHoldingHand):
+                // the off hand when the main one doesn't hold the bow.
                 m.extra.using_item = 1;
+                m.extra.using_off_hand = m.extra.main_hand.as_deref() != Some("minecraft:bow");
             }
         }
     }

From fb1142cd71dba47247f5f897c8ff487362431413 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:31:41 +0100
Subject: [PATCH 064/270] Skins: keep vanilla's whole-payload rejection, drop
 the dead name fallback

authlib 10.0.77 MinecraftServicesSessionService.unpackTextures returns
MinecraftProfileTextures.EMPTY when any texture has no URL or a URL outside
the allowed domains, so skins::unpack goes back to main's behaviour.

remote_player_names: r.players and r.tab_players are filled from the same
ADD_PLAYER entries and emptied by the same PlayerInfoRemove, so the
tab-list fallback could never apply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/remote.rs |  9 +--------
 crates/horizon-client/src/hud.rs         |  5 +++--
 crates/horizon-client/src/skins.rs       | 21 ++++++++++-----------
 3 files changed, 14 insertions(+), 21 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 36122d42a..74850110b 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -5068,14 +5068,7 @@ impl Game<'_> {
         r.level_players
             .iter()
             .filter(|(_, uuid)| **uuid != r.profile)
-            .filter_map(|(id, uuid)| {
-                let name = r
-                    .players
-                    .get(uuid)
-                    .cloned()
-                    .or_else(|| r.tab_players.get(uuid).map(|t| t.name.clone()))?;
-                Some((*id as u32, name))
-            })
+            .filter_map(|(id, uuid)| Some((*id as u32, r.players.get(uuid)?.clone())))
             .collect()
     }
     /// `ClientClockManager.tick`: the clock moves on by the game time that
diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs
index 90a8b346c..617126c2e 100644
--- a/crates/horizon-client/src/hud.rs
+++ b/crates/horizon-client/src/hud.rs
@@ -78,8 +78,9 @@ pub const MAP_SLOTS: usize = 256;
 /// The atlas slot the minimap extra draws into.
 pub const MINIMAP_SPRITE: &str = "horizon/minimap";
 /// Atlas slots for downloaded player skins (`skins/<sha1>`), 64x64 each.
-/// Vanilla registers a texture per skin; too few slots evict a busy
-/// server's players back to their default skins.
+/// Vanilla registers a texture per skin. Here a skin evicted from its slot
+/// is not stored again, and its player falls back to the default skin, so
+/// the slots must cover a busy server's player list.
 pub const SKIN_SLOTS: usize = 128;
 /// Reused by the visible rows of the classic world selector.
 pub const WORLD_ICON_SLOTS: usize = 32;
diff --git a/crates/horizon-client/src/skins.rs b/crates/horizon-client/src/skins.rs
index 0cf9cc8a2..9014032c4 100644
--- a/crates/horizon-client/src/skins.rs
+++ b/crates/horizon-client/src/skins.rs
@@ -92,23 +92,22 @@ pub fn unpack(value: &str, signature: Signature, valid_uris: &[&str]) -> Texture
         ..empty.clone()
     };
     for (kind, texture) in textures {
+        let Some(url) = texture.get("url").and_then(|u| u.as_str()) else {
+            return empty;
+        };
+        let allowed = valid_uris
+            .iter()
+            .any(|u| url.starts_with(&u.replace("{textureId}", "")));
+        if !allowed {
+            return empty;
+        }
         let slot = match kind.as_str() {
             "SKIN" => &mut out.skin,
             "CAPE" => &mut out.cape,
             "ELYTRA" => &mut out.elytra,
             _ => continue,
         };
-        // One bad entry (no `url`, or a URL outside the texture services'
-        // domains) drops only that texture, not the whole payload.
-        let Some(url) = texture.get("url").and_then(|u| u.as_str()) else {
-            continue;
-        };
-        let allowed = valid_uris
-            .iter()
-            .any(|u| url.starts_with(&u.replace("{textureId}", "")));
-        if allowed {
-            *slot = Some(url.to_owned());
-        }
+        *slot = Some(url.to_owned());
     }
     out
 }

From c756a372a3cc5a2a58719187dedfedaef0f39884 Mon Sep 17 00:00:00 2001
From: cristibctr <cristian.bucataru@gmail.com>
Date: Sun, 25 Oct 2026 15:32:57 +0200
Subject: [PATCH 065/270] Fix stale Windows resource pack overlays

Invalidate version 3 overlays that can omit untouched vanilla resources. Cover folder and ZIP pack cache recovery, and use a writable timestamp handle in the Windows cache test.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 crates/horizon-client/src/packs/cache.rs | 75 +++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/packs/cache.rs b/crates/horizon-client/src/packs/cache.rs
index efcf01e4a..51b7a9f1d 100644
--- a/crates/horizon-client/src/packs/cache.rs
+++ b/crates/horizon-client/src/packs/cache.rs
@@ -8,7 +8,8 @@ use std::io::Read;
 use std::{collections::BTreeSet, fs, io, path::Path, path::PathBuf};
 
 // Bump when overlay/merge semantics change. Markers are disposable cache data.
-const VERSION: u32 = 3;
+// Version 3 could omit untouched vanilla directories on Windows (#1649, #1688).
+const VERSION: u32 = 4;
 
 #[derive(Default, Serialize, Deserialize)]
 pub(super) struct Dependencies {
@@ -421,6 +422,73 @@ mod tests {
         out
     }
 
+    #[test]
+    #[cfg(not(unix))]
+    fn texture_only_packs_rebuild_incomplete_windows_v3_overlays() {
+        let f = Fixture::new();
+        let blockstate = "assets/minecraft/blockstates/oak_stairs.json";
+        let model = "assets/minecraft/models/block/oak_stairs.json";
+        let texture = "assets/minecraft/textures/block/stone.png";
+        let font = "assets/minecraft/textures/font/ascii.png";
+        f.write(&format!("vanilla/{blockstate}"), br#"{"variants":{}}"#);
+        f.write(&format!("vanilla/{model}"), br#"{"elements":[]}"#);
+        f.write(&format!("vanilla/{texture}"), b"vanilla texture");
+        f.write(&format!("vanilla/{font}"), b"vanilla font");
+        let folder = f.dir_pack("textures");
+        f.write(&format!("textures/{texture}"), b"pack texture");
+        f.write(
+            "textures.zip",
+            &archive(
+                &[
+                    (
+                        "pack.mcmeta",
+                        br#"{"pack":{"description":"test","pack_format":97}}"#.to_vec(),
+                    ),
+                    (texture, b"pack texture".to_vec()),
+                ],
+                true,
+            ),
+        );
+        let zip = packs::pack(
+            "zip".into(),
+            Text::empty(),
+            Source::Zip(f.0.join("textures.zip")),
+        )
+        .unwrap();
+        let vanilla = f.0.join("vanilla");
+        for pack in [folder, zip] {
+            let out = f.0.join(format!("cached-{}", pack.id));
+            let selected = std::slice::from_ref(&pack);
+            packs::build_overlay(&vanilla, selected, &out).unwrap();
+            let check = || {
+                for name in [blockstate, model, font] {
+                    assert_eq!(
+                        fs::read(out.join(name)).unwrap(),
+                        fs::read(vanilla.join(name)).unwrap()
+                    );
+                }
+                assert_eq!(fs::read(out.join(texture)).unwrap(), b"pack texture");
+            };
+            check();
+            // Before #1688, Windows silently omitted untouched directories.
+            // A v3 marker still validates because it checks only source files.
+            let marker_path = marker_path(&out);
+            let mut marker: Marker =
+                serde_json::from_slice(&fs::read(&marker_path).unwrap()).unwrap();
+            marker.version = 3;
+            for dir in ["blockstates", "models", "textures/font"] {
+                fs::remove_dir_all(out.join("assets/minecraft").join(dir)).unwrap();
+            }
+            fs::write(&marker_path, serde_json::to_vec(&marker).unwrap()).unwrap();
+            assert!(marker.dependencies.valid());
+            packs::build_overlay(&vanilla, selected, &out).unwrap();
+            check();
+            // The repaired overlay also remains complete on a cache hit.
+            packs::build_overlay(&vanilla, selected, &out).unwrap();
+            check();
+        }
+    }
+
     #[test]
     fn directory_inputs_config_and_owned_output_recovery() {
         let f = Fixture::new();
@@ -456,7 +524,10 @@ mod tests {
         let path = f.0.join(format!("high/{resource}"));
         let original_time = fs::metadata(&path).unwrap().modified().unwrap();
         fs::write(&path, br#"{"p":"c"}"#).unwrap();
-        fs::File::open(path)
+        // Windows requires a writable handle to restore the timestamp.
+        fs::OpenOptions::new()
+            .write(true)
+            .open(path)
             .unwrap()
             .set_times(fs::FileTimes::new().set_modified(original_time))
             .unwrap();

From 2f1f0150eb112062fb696676bc578ba174fa3472 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:37:26 +0100
Subject: [PATCH 066/270] mobs diagnostics: say why passenger is set outside
 the json! macro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/creatures.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 5cfcefdb8..c4779dbf7 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -371,7 +371,9 @@ impl Game<'_> {
                         "vehicle": m.extra.mount,
                     })),
                 });
-                state["passenger"] = serde_json::json!(m.extra.passenger);
+                // Drawn seated (Entity.isPassenger); set apart because the
+                // json! above is at the macro recursion limit.
+                state["passenger"] = m.extra.passenger.into();
                 state
             })
             .collect();

From 68deac8533c0a7072785712940b643f11c34c039 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:38:44 +0100
Subject: [PATCH 067/270] Server clients see mobs' aggression and arm swings

Mob.DATA_MOB_FLAGS_ID now carries the aggressive bit (with its default
0, so it goes back off) and every client mob reads no AI, left-handed
and aggressive from it: a vindicator draws its axe, skeletons their bow,
piglins and illagers their attack poses on the server thread, LAN guests
and dedicated servers. Mobs' swings (LivingEntity.swing) go out as
ClientboundSwingAnimationPacket.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan.rs         | 24 +++++++++++++++----
 crates/horizon-client/src/game/remote.rs      |  9 -------
 .../src/game/remote_mob_data.rs               | 21 ++++++++++++++++
 3 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs
index 8460f54e6..97b4d2ba7 100644
--- a/crates/horizon-client/src/game/lan.rs
+++ b/crates/horizon-client/src/game/lan.rs
@@ -55,8 +55,8 @@ pub(super) struct LanHost {
     pub play: HashMap<u32, super::lan_actions::GuestPlay>,
     /// Blocks broken this tick (their sound is a level event for the guests).
     pub broken: Vec<[f64; 3]>,
-    /// Hurt and death state of the mobs guests see.
-    mob_state: HashMap<super::Dim, HashMap<u32, (i32, bool)>>,
+    /// Hurt time, death and swing time (while swinging) of the mobs guests see.
+    mob_state: HashMap<super::Dim, HashMap<u32, (i32, bool, Option<i32>)>>,
     /// The guest each mob sees as its player, when not the host (game/lan_mobs.rs).
     pub mob_players: HashMap<u32, u32>,
     /// An integrated server's owner (game/integrated.rs).
@@ -168,11 +168,15 @@ fn mob_meta(
         meta.push((9, serializer::FLOAT, Value::Float(health)));
     }
     defaults.push((9, serializer::FLOAT, Value::Float(1.0)));
-    // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2.
-    let flags = i8::from(m.no_ai) | i8::from(m.extra.left_handed) << 1;
+    // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2, aggressive 4 (what
+    // draws a vindicator's axe, a skeleton's drawn bow, a piglin's raised
+    // weapon).
+    let flags =
+        i8::from(m.no_ai) | i8::from(m.extra.left_handed) << 1 | i8::from(m.ai.aggressive) << 2;
     if flags != 0 {
         meta.push((15, serializer::BYTE, Value::Byte(flags)));
     }
+    defaults.push((15, serializer::BYTE, Value::Byte(0)));
     // AgeableMob.DATA_BABY_ID (and Zombie's, Piglin's).
     if let Some(index) = baby_index(kind) {
         if m.is_baby() {
@@ -1193,7 +1197,17 @@ impl Game<'_> {
             if dead && !old.is_some_and(|o| o.1) {
                 host.hub.entity_event(m.id as i32, 3, at);
             }
-            seen.insert(m.id, (m.hurt_time, dead));
+            // LivingEntity.swing on a server (a melee hit, a thrown potion):
+            // ClientboundSwingAnimationPacket for the players around. A swing
+            // started since the last flush, or restarted (its time went back).
+            let swing = m.ai.swinging.then_some(m.ai.swing_time);
+            if let Some(time) = swing
+                && !dead
+                && old.and_then(|o| o.2).is_none_or(|before| time < before)
+            {
+                host.hub.swing(m.id as i32, 0, at, None);
+            }
+            seen.insert(m.id, (m.hurt_time, dead, swing));
         }
         host.mob_state.insert(self.dim, seen);
     }
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..11d2b367c 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1994,15 +1994,6 @@ impl Game<'_> {
                         }
                     }
                 }
-                if let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32)
-                    && m.species() == horizon_client::mobs::Species::Rabbit
-                {
-                    for (index, _, value) in &p.values {
-                        if let (15, Value::Byte(flags)) = (index, value) {
-                            m.no_ai = flags & 1 != 0;
-                        }
-                    }
-                }
                 self.remote_mob_data(p.id, &p.values);
                 if let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32)
                     && m.species() == horizon_client::mobs::Species::Creeper
diff --git a/crates/horizon-client/src/game/remote_mob_data.rs b/crates/horizon-client/src/game/remote_mob_data.rs
index 5573d0f87..64c092142 100644
--- a/crates/horizon-client/src/game/remote_mob_data.rs
+++ b/crates/horizon-client/src/game/remote_mob_data.rs
@@ -23,6 +23,14 @@ fn apply(m: &mut Mob, values: &[(u8, i32, Value)], builtin: &Builtin) {
             // LivingEntity.DATA_HEALTH_ID: the boss bars and the death
             // animation follow it.
             (9, Value::Float(health)) => m.health = *health,
+            // Mob.DATA_MOB_FLAGS_ID: no AI 1, left-handed 2, aggressive 4.
+            // Mob.isAggressive draws the illagers' and skeletons' attack
+            // poses and the vindicator's axe.
+            (15, Value::Byte(flags)) => {
+                m.no_ai = flags & 1 != 0;
+                m.extra.left_handed = flags & 2 != 0;
+                m.ai.aggressive = flags & 4 != 0;
+            }
             (i, Value::Bool(b)) if Some(i) == baby => m.extra.age = if *b { -1 } else { 0 },
             _ => {}
         }
@@ -178,6 +186,19 @@ mod tests {
         assert_eq!(m.fire_ticks, 0);
     }
 
+    #[test]
+    fn mob_flags_turn_aggression_on_and_off() {
+        let Some(mut m) = mob("minecraft:vindicator") else {
+            return;
+        };
+        apply(&mut m, &[(15, s::BYTE, Value::Byte(4 | 2))]);
+        assert!(m.ai.aggressive && m.extra.left_handed && !m.no_ai);
+        assert!(horizon_client::mobs::illager::shows_item(&m));
+        apply(&mut m, &[(15, s::BYTE, Value::Byte(0))]);
+        assert!(!m.ai.aggressive && !m.extra.left_handed);
+        assert!(!horizon_client::mobs::illager::shows_item(&m));
+    }
+
     #[test]
     fn a_villager_takes_its_type_profession_and_level() {
         let Some(mut m) = mob("minecraft:villager") else {

From 1506c1808a2e5bd9bee4307090c09d111ad9e446 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 13:16:16 +0100
Subject: [PATCH 068/270] Add /pregen: generate, light and save an area ahead
 of the players

A Chunky-like command for single player and servers: /pregen start
<radius> [square|circle] [<x> <z>], status, pause, continue and cancel,
with progress (chunks, chunks/s, time left) in the log and to the player
who started it.

The area is swept strip by strip by a band of rows that streaming treats
like a player's area (Streaming::set_band). A row is done once its chunks
are lit and post-processed; the rows behind the band then unload and are
saved, so memory holds only the rows in flight. The band's chunks are
ranked for decoration row by row as they come within reach, so a task
decorates in the same order however its jobs are timed. Between ticks
the server waits on the workers' results and schedules the next jobs at
once instead of once a tick.
---
 crates/horizon-client/src/command/vanilla.rs  |  46 +++-
 crates/horizon-client/src/game.rs             |   1 +
 crates/horizon-client/src/game/commands.rs    |   2 +
 .../horizon-client/src/game/commands/extra.rs |   2 +
 .../src/game/commands/pregen.rs               | 252 ++++++++++++++++++
 .../src/game/commands/terrain_cmds.rs         |   2 +-
 crates/horizon-client/src/game/levels.rs      |  13 +-
 crates/horizon-client/src/lib.rs              |   1 +
 crates/horizon-client/src/pregen.rs           | 111 ++++++++
 crates/horizon-client/src/streaming.rs        | 131 ++++++++-
 docs/README.md                                |   1 +
 docs/hosting.md                               |   2 +
 docs/pregeneration.md                         |  41 +++
 13 files changed, 594 insertions(+), 11 deletions(-)
 create mode 100644 crates/horizon-client/src/game/commands/pregen.rs
 create mode 100644 crates/horizon-client/src/pregen.rs
 create mode 100644 docs/pregeneration.md

diff --git a/crates/horizon-client/src/command/vanilla.rs b/crates/horizon-client/src/command/vanilla.rs
index cdd4848d7..cba5a5d5b 100644
--- a/crates/horizon-client/src/command/vanilla.rs
+++ b/crates/horizon-client/src/command/vanilla.rs
@@ -538,12 +538,50 @@ fn apply_vanilla_order(d: &mut Dispatcher) {
 }
 /// The tree the game runs: a release integrated server's, or with
 /// `HORIZON_DEV_COMMANDS` set the development one
-/// (SharedConstants.DEBUG_DEV_COMMANDS).
+/// (SharedConstants.DEBUG_DEV_COMMANDS), plus Horizon's own commands.
 pub fn game_dispatcher() -> &'static Dispatcher {
-    if std::env::var_os("HORIZON_DEV_COMMANDS").is_some() {
-        dispatcher()
+    static DEV: std::sync::OnceLock<Dispatcher> = std::sync::OnceLock::new();
+    static RELEASE: std::sync::OnceLock<Dispatcher> = std::sync::OnceLock::new();
+    let (tree, dev) = if std::env::var_os("HORIZON_DEV_COMMANDS").is_some() {
+        (&DEV, true)
     } else {
-        release_dispatcher()
+        (&RELEASE, false)
+    };
+    tree.get_or_init(|| {
+        let mut d = build_with(dev);
+        horizon_commands(&mut d, 0);
+        d
+    })
+}
+/// Commands vanilla doesn't have, after its own: `/pregen`
+/// (docs/pregeneration.md).
+fn horizon_commands(d: &mut Dispatcher, root: usize) {
+    let pregen = d.literal(root, "pregen");
+    d.requires(pregen, GAMEMASTERS);
+    let start = d.literal(pregen, "start");
+    let radius = d.argument(
+        start,
+        "radius",
+        ArgType::Integer {
+            min: 0,
+            max: 30_000_000,
+        },
+    );
+    d.executes(radius, "pregen.start");
+    for shape in ["square", "circle"] {
+        let shape = d.literal(radius, shape);
+        d.executes(shape, "pregen.start");
+        let center = d.argument(shape, "center", ArgType::ColumnPos);
+        d.executes(center, "pregen.start");
+    }
+    for (word, id) in [
+        ("pause", "pregen.pause"),
+        ("continue", "pregen.continue"),
+        ("cancel", "pregen.cancel"),
+        ("status", "pregen.status"),
+    ] {
+        let w = d.literal(pregen, word);
+        d.executes(w, id);
     }
 }
 pub fn dispatcher() -> &'static Dispatcher {
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..fa00e3804 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -10590,6 +10590,7 @@ impl Game<'_> {
         // The loading screen's chunk map fills ring by ring, as vanilla's.
         self.streaming.loading =
             self.options.execution_role.is_client() && self.loading_reason().is_some();
+        self.tick_pregen();
         let (uploads, unloaded) =
             horizon_client::spans::time("streaming", || self.streaming.update(&mut self.world));
         if let Some(lod) = &mut self.lod {
diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index 19a16e261..d5f9e6542 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -10,6 +10,7 @@ mod items;
 mod misc;
 mod place;
 mod players;
+pub(super) mod pregen;
 mod raid;
 mod terrain_cmds;
 mod text_commands;
@@ -758,6 +759,7 @@ impl Game<'_> {
             "ride.mount" | "ride.dismount" => self.cmd_ride(id, ctx),
             "spreadplayers" => self.cmd_spreadplayers(ctx),
             id if id.starts_with("forceload.") => self.cmd_forceload(id, ctx),
+            id if id.starts_with("pregen.") => self.cmd_pregen(id, ctx),
             "fillbiome" => self.cmd_fillbiome(ctx),
             id if id.starts_with("worldborder.") => self.cmd_worldborder(id, ctx),
             id if id.starts_with("loot.") => self.cmd_loot(id, ctx),
diff --git a/crates/horizon-client/src/game/commands/extra.rs b/crates/horizon-client/src/game/commands/extra.rs
index ef69be6d9..ca431b8e7 100644
--- a/crates/horizon-client/src/game/commands/extra.rs
+++ b/crates/horizon-client/src/game/commands/extra.rs
@@ -57,6 +57,8 @@ pub(in crate::game) struct CommandExtras {
     /// The `CommandResultCallback` results of the outermost source, when a
     /// harness records them.
     pub results: Option<Vec<(bool, i32)>>,
+    /// The running `/pregen` task.
+    pub pregen: Option<super::pregen::PregenTask>,
 }
 
 use horizon_core::version::{BUILD_TIME, DATA_VERSION, STABLE, VANILLA_VERSION, VERSION_ID};
diff --git a/crates/horizon-client/src/game/commands/pregen.rs b/crates/horizon-client/src/game/commands/pregen.rs
new file mode 100644
index 000000000..d61ba63ac
--- /dev/null
+++ b/crates/horizon-client/src/game/commands/pregen.rs
@@ -0,0 +1,252 @@
+//! `/pregen`, Horizon's own command: generate, light and save every chunk of a
+//! square or a circle ahead of the players (docs/pregeneration.md). The task
+//! lives on the server and hands its band to the level's streaming, whose
+//! workers do the work; chunks behind the band unload and are saved as any
+//! chunk the players leave.
+use super::{CommandError, Context, Dim, Game, R};
+use horizon_client::{
+    lan::data::component_nbt,
+    pregen::{Pregen, Shape},
+    text::{self, Text},
+};
+use horizon_protocol::packets::play::{self, Clientbound as C};
+use std::time::{Duration, Instant};
+
+/// How often the progress is reported.
+const REPORT_EVERY: Duration = Duration::from_secs(5);
+
+pub(in crate::game) struct PregenTask {
+    pregen: Pregen,
+    dim: Dim,
+    paused: bool,
+    /// Time spent running, up to the last pause, and when it last resumed.
+    ran: Duration,
+    resumed: Instant,
+    reported: Instant,
+    /// The player who started it, told the progress too (a guest's connection).
+    owner: Option<u32>,
+}
+
+impl PregenTask {
+    fn running_for(&self) -> Duration {
+        if self.paused {
+            self.ran
+        } else {
+            self.ran + self.resumed.elapsed()
+        }
+    }
+    fn progress(&self) -> Text {
+        let p = &self.pregen;
+        let seconds = self.running_for().as_secs_f64();
+        let rate = p.done as f64 / seconds.max(1e-3);
+        let left = p.total - p.done;
+        let eta = if rate > 0.0 {
+            duration(left as f64 / rate)
+        } else {
+            "unknown".into()
+        };
+        Text::literal(format!(
+            "Pregenerating {}: {} of {} chunks ({:.1}%), {rate:.1} chunks/s, {} left",
+            self.dim.id(),
+            p.done,
+            p.total,
+            100.0 * p.done as f64 / p.total.max(1) as f64,
+            if p.done == p.total {
+                "nothing".into()
+            } else {
+                eta
+            },
+        ))
+    }
+}
+
+fn failure(message: &str) -> CommandError {
+    CommandError::new(Text::literal(message))
+}
+
+/// `1h 02m 03s`.
+fn duration(seconds: f64) -> String {
+    let s = seconds.round() as u64;
+    match (s / 3600, s / 60 % 60, s % 60) {
+        (0, 0, s) => format!("{s}s"),
+        (0, m, s) => format!("{m}m {s:02}s"),
+        (h, m, s) => format!("{h}h {m:02}m {s:02}s"),
+    }
+}
+
+impl Game<'_> {
+    pub(super) fn cmd_pregen(&mut self, id: &str, ctx: &Context) -> R<i32> {
+        match id {
+            "pregen.start" => {
+                if self.cmds.pregen.is_some() {
+                    return Err(failure(
+                        "Pregeneration is already running: /pregen cancel stops it",
+                    ));
+                }
+                let radius = Self::int(ctx, "radius").unwrap_or(0);
+                let shape = if ctx.literals.iter().any(|l| l == "circle") {
+                    Shape::Circle
+                } else {
+                    Shape::Square
+                };
+                let [x, z] = if ctx.get("center").is_some() {
+                    self.column_arg(ctx, "center")?
+                } else {
+                    let p = self.source_position();
+                    [p[0].floor() as i32, p[2].floor() as i32]
+                };
+                let pregen = Pregen::new((x >> 4, z >> 4), radius >> 4, shape);
+                let now = Instant::now();
+                let total = pregen.total;
+                self.feedback(Text::literal(format!(
+                    "Pregenerating {total} chunks of {}: a {} of radius {radius} around {x} {z}",
+                    self.dim.id(),
+                    match shape {
+                        Shape::Square => "square",
+                        Shape::Circle => "circle",
+                    },
+                )));
+                self.cmds.pregen = Some(PregenTask {
+                    pregen,
+                    dim: self.dim,
+                    paused: false,
+                    ran: Duration::ZERO,
+                    resumed: now,
+                    reported: now,
+                    owner: self.lan_acting,
+                });
+                Ok(total as i32)
+            }
+            "pregen.pause" | "pregen.continue" => {
+                let pause = id == "pregen.pause";
+                let task = self
+                    .cmds
+                    .pregen
+                    .as_mut()
+                    .ok_or_else(|| failure("No pregeneration is running"))?;
+                if task.paused != pause {
+                    task.paused = pause;
+                    if pause {
+                        task.ran += task.resumed.elapsed();
+                    } else {
+                        task.resumed = Instant::now();
+                    }
+                }
+                let (progress, dim) = (task.progress(), task.dim);
+                if pause && self.dim == dim {
+                    self.streaming.set_band(None);
+                }
+                self.feedback(
+                    Text::literal(if pause { "Paused. " } else { "Continuing. " }).append(progress),
+                );
+                Ok(1)
+            }
+            "pregen.cancel" => {
+                let task = self
+                    .cmds
+                    .pregen
+                    .take()
+                    .ok_or_else(|| failure("No pregeneration is running"))?;
+                if self.dim == task.dim {
+                    self.streaming.set_band(None);
+                }
+                self.feedback(Text::literal("Cancelled. ").append(task.progress()));
+                Ok(task.pregen.done as i32)
+            }
+            _ => {
+                let task = self
+                    .cmds
+                    .pregen
+                    .as_ref()
+                    .ok_or_else(|| failure("No pregeneration is running"))?;
+                let progress = task.progress();
+                let done = task.pregen.done as i32;
+                self.feedback(progress);
+                Ok(done)
+            }
+        }
+    }
+
+    /// Move the task's band past the rows that are lit and hand it to the
+    /// level's streaming, and report the progress now and then. Runs before
+    /// each streaming update of the level in place.
+    pub(in crate::game) fn tick_pregen(&mut self) {
+        let Some(task) = self.cmds.pregen.as_mut() else {
+            return;
+        };
+        if task.dim != self.dim || task.paused {
+            return;
+        }
+        // A row is done once its chunks are lit and post-processed
+        // (`postprocess_chunks`, on the tick), as vanilla's are by the time
+        // they are FULL: then they may unload and be saved.
+        let (streaming, chunks) = (&mut self.streaming, &self.world.chunks);
+        task.pregen.advance(|x, z| {
+            streaming.is_lit(x, z)
+                && chunks
+                    .get(&(x, z))
+                    .is_some_and(|c| c.postprocess.is_empty())
+        });
+        streaming.set_band(task.pregen.band());
+        let finished = task.pregen.finished();
+        if finished || task.reported.elapsed() >= REPORT_EVERY {
+            task.reported = Instant::now();
+            let (owner, mut message) = (task.owner, task.progress());
+            if finished {
+                message = Text::literal("Done. ")
+                    .append(message)
+                    .with_color(text::GREEN);
+                self.cmds.pregen = None;
+            }
+            self.pregen_report(owner, message);
+        }
+    }
+
+    /// Whether the level in place has a running task, which the server pumps
+    /// between its ticks (`pump_pregen`).
+    pub(in crate::game) fn pregen_runs_here(&self) -> bool {
+        self.cmds
+            .pregen
+            .as_ref()
+            .is_some_and(|t| t.dim == self.dim && !t.paused)
+    }
+
+    /// The level a running task needs ticked, whoever is in it.
+    pub(in crate::game) fn pregen_level(&self) -> Option<Dim> {
+        self.cmds.pregen.as_ref().map(|t| t.dim)
+    }
+
+    /// Keep the workers fed until `until`: collect what they finished and
+    /// hand them the next jobs as soon as each one is done, rather than once
+    /// a tick.
+    pub(in crate::game) fn pump_pregen(&mut self, until: Instant) {
+        while self.pregen_runs_here() {
+            let now = Instant::now();
+            if now >= until {
+                break;
+            }
+            self.streaming
+                .wait((until - now).min(Duration::from_millis(5)));
+            self.update_world();
+        }
+    }
+
+    /// The console and the player who started the task get the progress.
+    fn pregen_report(&mut self, owner: Option<u32>, message: Text) {
+        if self.options.dedicated.is_some() {
+            super::super::dedicated::log("INFO", &message.plain());
+        } else {
+            log::info!("{}", message.plain());
+        }
+        if let Some(host) = &self.lan {
+            if let Some(g) = owner.and_then(|c| host.hub.guest(c)) {
+                g.send(&C::SystemChat(play::SystemChat {
+                    content: component_nbt(&message.component()),
+                    overlay: false,
+                }));
+            }
+        } else if self.options.dedicated.is_none() {
+            self.system_message(message);
+        }
+    }
+}
diff --git a/crates/horizon-client/src/game/commands/terrain_cmds.rs b/crates/horizon-client/src/game/commands/terrain_cmds.rs
index df52f2251..d4b1c125c 100644
--- a/crates/horizon-client/src/game/commands/terrain_cmds.rs
+++ b/crates/horizon-client/src/game/commands/terrain_cmds.rs
@@ -30,7 +30,7 @@ fn ticks_to_seconds(ticks: i64) -> String {
 impl Game<'_> {
     // ---- /forceload ----------------------------------------------------------
 
-    fn column_arg(&self, ctx: &Context, name: &str) -> R<[i32; 2]> {
+    pub(super) fn column_arg(&self, ctx: &Context, name: &str) -> R<[i32; 2]> {
         let c = self
             .coords(ctx, name)
             .ok_or_else(|| err("argument.pos2d.incomplete", &[]))?;
diff --git a/crates/horizon-client/src/game/levels.rs b/crates/horizon-client/src/game/levels.rs
index f685200f2..588f425a4 100644
--- a/crates/horizon-client/src/game/levels.rs
+++ b/crates/horizon-client/src/game/levels.rs
@@ -365,7 +365,12 @@ impl Game<'_> {
         }
         *next += self.clock.tick_duration();
         if *next > now {
-            std::thread::sleep(*next - now);
+            // A `/pregen` task keeps the workers fed until the next tick.
+            self.pump_pregen(*next);
+            let now = Instant::now();
+            if *next > now {
+                std::thread::sleep(*next - now);
+            }
         } else if now - *next > Duration::from_secs(2) {
             *next = now;
         }
@@ -373,7 +378,7 @@ impl Game<'_> {
 
     /// The levels this server tick runs, in `MinecraftServer.levels` order
     /// (the Overworld, the Nether, the End): every level with a player in
-    /// it, or the Overworld while nobody is online.
+    /// it or a `/pregen` task, or the Overworld while nobody is online.
     pub(super) fn levels_to_tick(&self) -> Vec<Dim> {
         let guests = self
             .lan
@@ -381,7 +386,9 @@ impl Game<'_> {
             .map_or(&[][..], |h| h.hub.guests.as_slice());
         let mut dims: Vec<Dim> = [Dim::Overworld, Dim::Nether, Dim::End]
             .into_iter()
-            .filter(|d| guests.iter().any(|g| g.dimension == d.id()))
+            .filter(|d| {
+                guests.iter().any(|g| g.dimension == d.id()) || self.pregen_level() == Some(*d)
+            })
             .collect();
         if dims.is_empty() {
             dims.push(Dim::Overworld);
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index ae95e1bdb..5125608d4 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -145,6 +145,7 @@ pub mod player_sync;
 pub mod poi_sections;
 pub mod portal_sections;
 pub mod pose;
+pub mod pregen;
 pub mod projectiles;
 pub mod raid;
 pub mod random_sequences;
diff --git a/crates/horizon-client/src/pregen.rs b/crates/horizon-client/src/pregen.rs
new file mode 100644
index 000000000..f31a6d712
--- /dev/null
+++ b/crates/horizon-client/src/pregen.rs
@@ -0,0 +1,111 @@
+//! Pregeneration (`/pregen`): every chunk of a square or a circle generated,
+//! lit and saved ahead of the players. The area is cut into strips of columns
+//! and each strip is swept north to south by a [`Band`] a few rows deep:
+//! streaming generates the band's chunks and keeps them until they are lit,
+//! then the band moves on and the rows behind it unload and are saved, so
+//! memory stays bounded whatever the radius.
+use crate::streaming::Band;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Shape {
+    Square,
+    Circle,
+}
+
+/// The widest strip, in chunks. Strips are swept one after another; the few
+/// columns along the edge between two are generated with both.
+const STRIP_WIDTH: i32 = 256;
+/// How many chunks a band holds at least: enough to keep every worker busy
+/// while the rows before it finish.
+const BAND_CHUNKS: i32 = 1024;
+
+pub struct Pregen {
+    /// The centre chunk and the radius in chunks.
+    pub center: (i32, i32),
+    pub radius: i32,
+    pub shape: Shape,
+    /// The strips' columns, west to east.
+    strips: Vec<(i32, i32)>,
+    strip: usize,
+    /// The band's first row: every row of the strip before it is done.
+    row: i32,
+    /// Chunks of the area lit so far, and in all.
+    pub done: u64,
+    pub total: u64,
+}
+
+impl Pregen {
+    pub fn new(center: (i32, i32), radius: i32, shape: Shape) -> Self {
+        let radius = radius.max(0);
+        let (x0, width) = (center.0 - radius, 2 * radius + 1);
+        let count = (width + STRIP_WIDTH - 1) / STRIP_WIDTH;
+        let strips = (0..count)
+            .map(|i| (x0 + width * i / count, x0 + width * (i + 1) / count - 1))
+            .collect();
+        let mut pregen = Self {
+            center,
+            radius,
+            shape,
+            strips,
+            strip: 0,
+            row: center.1 - radius,
+            done: 0,
+            total: 0,
+        };
+        pregen.total = (center.1 - radius..=center.1 + radius)
+            .map(|z| pregen.row_chunks(x0, x0 + width - 1, z))
+            .sum();
+        pregen
+    }
+
+    fn contains(&self, x: i32, z: i32) -> bool {
+        match self.shape {
+            Shape::Square => true,
+            Shape::Circle => {
+                let (dx, dz) = (i64::from(x - self.center.0), i64::from(z - self.center.1));
+                dx * dx + dz * dz <= i64::from(self.radius) * i64::from(self.radius)
+            }
+        }
+    }
+
+    fn row_chunks(&self, x0: i32, x1: i32, z: i32) -> u64 {
+        (x0..=x1).filter(|&x| self.contains(x, z)).count() as u64
+    }
+
+    /// The band streaming should hold now; none once every strip is done.
+    pub fn band(&self) -> Option<Band> {
+        let &(x0, x1) = self.strips.get(self.strip)?;
+        let rows = (BAND_CHUNKS + (x1 - x0)) / (x1 - x0 + 1);
+        Some(Band {
+            x0,
+            x1,
+            z0: self.row,
+            z1: (self.row + rows - 1).min(self.center.1 + self.radius),
+            circle: (self.shape == Shape::Circle).then_some((self.center, self.radius)),
+        })
+    }
+
+    /// Move past the band's first rows once all their chunks are `lit`.
+    /// Returns whether the band moved.
+    pub fn advance(&mut self, lit: impl Fn(i32, i32) -> bool) -> bool {
+        let mut moved = false;
+        while let Some(&(x0, x1)) = self.strips.get(self.strip) {
+            let z = self.row;
+            if !(x0..=x1).all(|x| !self.contains(x, z) || lit(x, z)) {
+                break;
+            }
+            self.done += self.row_chunks(x0, x1, z);
+            self.row += 1;
+            if self.row > self.center.1 + self.radius {
+                self.strip += 1;
+                self.row = self.center.1 - self.radius;
+            }
+            moved = true;
+        }
+        moved
+    }
+
+    pub fn finished(&self) -> bool {
+        self.strip >= self.strips.len()
+    }
+}
diff --git a/crates/horizon-client/src/streaming.rs b/crates/horizon-client/src/streaming.rs
index 55a2f0086..51c4eaea4 100644
--- a/crates/horizon-client/src/streaming.rs
+++ b/crates/horizon-client/src/streaming.rs
@@ -278,6 +278,11 @@ pub struct Streaming {
     cover: Option<ExtraCover>,
     /// Mesh the sections for drawing (false on a server thread).
     pub mesh: bool,
+    /// The pregeneration band (`set_band`).
+    band: Option<Band>,
+    /// The columns and the next row the band's decoration ranks were given
+    /// for (`set_band`).
+    band_ranked: Option<(i32, i32, i32)>,
 }
 /// Snapshot only after a scan found no missing candidates. Public range fields
 /// and `World::chunks` can change without going through Streaming, so compare
@@ -289,6 +294,7 @@ struct GenerationScan {
     radius: i32,
     extra: Vec<((i32, i32), i32)>,
     forced: HashSet<(i32, i32)>,
+    band: Option<Band>,
     chunk_revision: u64,
 }
 impl GenerationScan {
@@ -298,6 +304,7 @@ impl GenerationScan {
             && self.radius == ranges.radius
             && self.extra == ranges.extra
             && self.forced == *ranges.forced
+            && self.band.as_ref() == ranges.band
             && self.chunk_revision == world.chunks.membership_revision()
     }
     fn remember(&mut self, ranges: Ranges<'_>, world: &World) {
@@ -307,6 +314,7 @@ impl GenerationScan {
         self.extra.clear();
         self.extra.extend_from_slice(ranges.extra);
         self.forced.clone_from(ranges.forced);
+        self.band = ranges.band.copied();
         self.chunk_revision = world.chunks.membership_revision();
     }
 }
@@ -348,6 +356,10 @@ impl GenerationScan {
                 let r = radius + margin.max(reach + 1);
                 runs.extend((center.1 - r..=center.1 + r).map(|z| (z, center.0 - r, center.0 + r)));
             }
+            if let Some(band) = input.ranges.band {
+                let r = margin.max(reach + 1);
+                runs.extend((band.z0 - r..=band.z1 + r).map(|z| (z, band.x0 - r, band.x1 + r)));
+            }
             runs.sort_unstable();
             let mut runs = runs.into_iter().peekable();
             while let Some((z, x0, mut x1)) = runs.next() {
@@ -392,6 +404,7 @@ impl GenerationScan {
                     extra: input.ranges.extra,
                     forced: input.ranges.forced,
                     cover: input.ranges.cover,
+                    band: input.ranges.band,
                 };
                 self.remember(ranges, input.world);
             } else {
@@ -564,6 +577,8 @@ impl Streaming {
             extra: Vec::new(),
             cover: None,
             mesh: true,
+            band: None,
+            band_ranked: None,
         }
     }
     /// Shares generation resources, but gives distant work its own worker state.
@@ -916,6 +931,7 @@ impl Streaming {
                 p.is_some()
                     && i64::from(x - center.0).pow(2) + i64::from(z - center.1).pow(2) > r4 * r4
                     && !ranges.in_extra(x, z, 4)
+                    && !ranges.in_band(x, z, 4)
                     && !ranges
                         .forced
                         .iter()
@@ -985,6 +1001,7 @@ impl Streaming {
                 extra: &self.extra,
                 forced: &self.forced,
                 cover: ExtraCover::matching(&self.cover, &self.extra),
+                band: self.band.as_ref(),
             };
             let (protos, generating) = (&self.protos, &self.generating);
             self.decoration_order.retain(|x, z| {
@@ -1113,6 +1130,7 @@ impl Streaming {
                 extra: &self.extra,
                 forced: &self.forced,
                 cover: ExtraCover::matching(&self.cover, &self.extra),
+                band: self.band.as_ref(),
             };
             self.waiting.retain(|&(x, sy, z)| {
                 let back = ranges.in_view(x, z);
@@ -1189,6 +1207,7 @@ impl Streaming {
                 extra: &self.extra,
                 forced: &self.forced,
                 cover: ExtraCover::matching(&self.cover, &self.extra),
+                band: self.band.as_ref(),
             },
             world,
             generating: &self.generating,
@@ -1285,6 +1304,7 @@ impl Streaming {
             extra: &self.extra,
             forced: &self.forced,
             cover: ExtraCover::matching(&self.cover, &self.extra),
+            band: self.band.as_ref(),
         }
     }
     fn near_finished(&self, x: i32, z: i32, reach: i32) -> bool {
@@ -1354,6 +1374,45 @@ impl Streaming {
     fn in_range(&self, x: i32, z: i32, margin: i32) -> bool {
         self.ranges().in_range(x, z, margin)
     }
+    pub fn band(&self) -> Option<Band> {
+        self.band
+    }
+    /// Generate, light and keep the chunks of `band` (none: stop), and let
+    /// go of what earlier bands held as it falls out of range. The chunks a
+    /// band reaches are ranked for decoration row by row, as they first come
+    /// within reach, so that a task decorates in the same order however its
+    /// work is timed and shared among the workers.
+    pub fn set_band(&mut self, band: Option<Band>) {
+        if self.band == band {
+            return;
+        }
+        self.band = band;
+        self.generation_scan.exhausted = false;
+        let Some(band) = band else {
+            return;
+        };
+        // Decoration reaches two chunks past the band and generation three.
+        const REACH: i32 = 4;
+        let (x0, x1) = (band.x0 - REACH, band.x1 + REACH);
+        let first = match self.band_ranked {
+            Some((rx0, rx1, next)) if (rx0, rx1) == (x0, x1) => next,
+            _ => band.z0 - REACH,
+        };
+        let end = band.z1 + REACH;
+        for z in first..=end {
+            for x in x0..=x1 {
+                self.decoration_order.rank_or_append(x, z);
+            }
+        }
+        self.band_ranked = Some((x0, x1, end.max(first - 1) + 1));
+    }
+    /// Wait up to `timeout` for a worker to finish a job; the next `update`
+    /// takes it. A server pumps generation with this between its ticks.
+    pub fn wait(&mut self, timeout: std::time::Duration) {
+        if let Ok(done) = self.results.recv_timeout(timeout) {
+            self.deferred.push(done);
+        }
+    }
 }
 /// `ChunkTrackingView.isInViewDistance`: whether the column (x, z) is drawn
 /// at this render distance around `center`, the camera's column
@@ -1373,6 +1432,53 @@ struct Ranges<'a> {
     /// `extra` as a grid, when one was made for it: `in_extra` without a
     /// scan of every area.
     cover: Option<&'a ExtraCover>,
+    band: Option<&'a Band>,
+}
+/// The chunks a pregeneration task (`/pregen`) wants lit now: rows `z0..=z1`
+/// of the columns `x0..=x1`, those within `circle` (a centre and a radius in
+/// chunks) when there is one. Like an extra area, it finishes its chunks and
+/// the ring around them, so that its own chunks can be lit, and generation
+/// reaches past that. A task moves it down a strip of columns a row at a
+/// time, so each chunk is generated once and only the rows in flight stay
+/// loaded.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Band {
+    pub x0: i32,
+    pub x1: i32,
+    pub z0: i32,
+    pub z1: i32,
+    pub circle: Option<((i32, i32), i32)>,
+}
+impl Band {
+    /// Whether (x, z) lies within `margin` (Chebyshev) of one of the band's
+    /// chunks: the square of side `2 * margin + 1` around it meets the
+    /// rectangle at a point inside the circle.
+    pub fn within(&self, x: i32, z: i32, margin: i32) -> bool {
+        let (x0, x1) = (
+            x.saturating_sub(margin).max(self.x0),
+            x.saturating_add(margin).min(self.x1),
+        );
+        let (z0, z1) = (
+            z.saturating_sub(margin).max(self.z0),
+            z.saturating_add(margin).min(self.z1),
+        );
+        if x0 > x1 || z0 > z1 {
+            return false;
+        }
+        self.circle.is_none_or(|((cx, cz), r)| {
+            let dx = i64::from(cx.clamp(x0, x1)) - i64::from(cx);
+            let dz = i64::from(cz.clamp(z0, z1)) - i64::from(cz);
+            dx * dx + dz * dz <= i64::from(r) * i64::from(r)
+        })
+    }
+    /// The band's chunks go after the players' (lower runs first), row by
+    /// row, as the task wants them lit.
+    fn priority(&self, x: i32, z: i32) -> i64 {
+        const AFTER_PLAYERS: i64 = 1 << 40;
+        AFTER_PLAYERS
+            + (i64::from(z - self.z0 + 8).max(0) << 20)
+            + i64::from(x - self.x0 + 8).max(0)
+    }
 }
 /// For every column near the extra areas, how far it lies outside the
 /// nearest one's square (Chebyshev distance less its radius; 0 inside). A server has an area per player, and streaming asks of every
@@ -1468,10 +1574,14 @@ impl ExtraCover {
 impl Ranges<'_> {
     /// `distance`, or `rings` while the level loading screen is up.
     fn priority(&self, x: i32, z: i32, loading: bool) -> i64 {
-        if loading {
+        let own = if loading {
             self.rings(x, z)
         } else {
             self.distance(x, z)
+        };
+        match self.band {
+            Some(band) if band.within(x, z, 4) => own.min(band.priority(x, z)),
+            _ => own,
         }
     }
     /// Ring by ring: the Chebyshev distance to the nearest centre first, then
@@ -1532,10 +1642,18 @@ impl Ranges<'_> {
         let (dx, dz) = (gap(x - self.center.0), gap(z - self.center.1));
         let r = i64::from(self.radius + 1);
         // The extra areas are squares: their finished square grown by `reach`.
-        dx * dx + dz * dz <= r * r || self.in_extra(x, z, 1 + reach)
+        dx * dx + dz * dz <= r * r
+            || self.in_extra(x, z, 1 + reach)
+            || self.in_band(x, z, 1 + reach)
     }
     fn in_range(&self, x: i32, z: i32, margin: i32) -> bool {
-        self.in_main_range(x, z, margin) || self.in_extra(x, z, margin)
+        self.in_main_range(x, z, margin)
+            || self.in_extra(x, z, margin)
+            || self.in_band(x, z, margin)
+    }
+    /// Within `margin` of the pregeneration band.
+    fn in_band(&self, x: i32, z: i32, margin: i32) -> bool {
+        self.band.is_some_and(|b| b.within(x, z, margin))
     }
     /// Within `margin` of an extra area's square (Chebyshev distance, as
     /// vanilla's ticket levels spread).
@@ -1659,6 +1777,7 @@ mod tests {
                     extra: &self.extra,
                     forced: &self.forced,
                     cover: None,
+                    band: None,
                 },
                 world: &self.world,
                 generating: &self.generating,
@@ -1972,6 +2091,7 @@ mod tests {
                     extra: &[],
                     forced: &forced,
                     cover: None,
+                    band: None,
                 };
                 let square = |x: i32, z: i32, n: i32| {
                     (-n..=n).flat_map(move |dz| (-n..=n).map(move |dx| (x + dx, z + dz)))
@@ -2027,6 +2147,7 @@ mod tests {
             extra: &[],
             forced: &forced,
             cover: None,
+            band: None,
         };
         let at = |dx: i32, dz: i32| (2 + dx, -1 + dz);
         let key = |(x, z): (i32, i32), loading| r.priority(x, z, loading);
@@ -2053,6 +2174,7 @@ mod tests {
                     extra: &[((radius * 2 + 9, 3), 4)],
                     forced: &forced,
                     cover: None,
+                    band: None,
                 };
                 let span = radius * 3 + 20;
                 for x in -span..=span {
@@ -2093,6 +2215,7 @@ mod tests {
                 extra: &extra,
                 forced: &forced,
                 cover: None,
+                band: None,
             };
             let level = |x: i32, z: i32| 31 + ((x - 40).abs().max((z + 9).abs()) - view).max(0);
             for x in 40 - view - 8..=40 + view + 8 {
@@ -2161,6 +2284,7 @@ mod cover_tests {
                 extra: &extra,
                 forced: &forced,
                 cover,
+                band: None,
             };
             let (scan, grid) = (ranges(None), ranges(Some(&cover)));
             let span = [4, 30, 120][case % 3] + 40;
@@ -2218,6 +2342,7 @@ mod cover_tests {
                 extra: &extra,
                 forced: &forced,
                 cover,
+                band: None,
             };
             // The columns streaming asks about: everything kept, and the
             // generation scan's ring past it.
diff --git a/docs/README.md b/docs/README.md
index 1450ba388..48ddfd7b5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,6 +34,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
 ## Architecture: world generation
 
 - [World generation](world-generation.md): the pipeline from noise to features.
+- [Pregeneration](pregeneration.md): `/pregen`, generating, lighting and saving an area ahead of the players.
 - [Noise generation](noise-generation.md), [compiled density functions](density-functions.md), [structure density](structure-density.md), [terrain filling](terrain-filling.md).
 - Biomes: [lookup](biome-lookup.md), [temperatures](biome-temperatures.md).
 - Surfaces: [material surfaces](material-surfaces.md), [material conditions](material-conditions.md), [rule libraries](material-rule-libraries.md), [vertical anchors](vertical-anchors.md), [value providers](value-providers.md).
diff --git a/docs/hosting.md b/docs/hosting.md
index bf431cada..4c4c954bc 100644
--- a/docs/hosting.md
+++ b/docs/hosting.md
@@ -218,6 +218,8 @@ horizon-server rollback                  back to the release before
 While the server runs, `op`, `whitelist` and `cmd` go to the game's console, so they act exactly as vanilla's
 console commands do. While it's stopped, they edit vanilla's files directly. Any console command works through
 `cmd`: `horizon-server cmd ban Griefer`, `horizon-server cmd say Restarting in 5 minutes`.
+To generate the world around spawn ahead of the players, Horizon has its own `pregen` command:
+`horizon-server cmd pregen start 2500` ([pregeneration](pregeneration.md)).
 
 `config set` changes `server.toml` without opening it: `horizon-server config set world.difficulty=hard
 server.max_players=10`. Each key is a section and a name from the file (`properties.spawn-protection=0` for any
diff --git a/docs/pregeneration.md b/docs/pregeneration.md
new file mode 100644
index 000000000..a8ca228b3
--- /dev/null
+++ b/docs/pregeneration.md
@@ -0,0 +1,41 @@
+# Pregeneration: `/pregen`
+
+`/pregen` generates every chunk of a square or a circle ahead of the players, lights it and saves it, as
+Chunky does on a Java server. It is Horizon's own command (vanilla has none), available in single player
+with cheats on and to operators (level 2) on a server, from the chat or the server console
+(`horizon-server cmd pregen start 2500`).
+
+```text
+/pregen start <radius> [square|circle] [<x> <z>]   radius in blocks; the centre defaults to where you
+                                                   stand (the world spawn from the console)
+/pregen status                                     chunks done, chunks per second, time left
+/pregen pause | continue                           stop scheduling new chunks, and go on
+/pregen cancel                                     stop; what is done stays saved
+```
+
+The area is the chunks within `radius / 16` chunks of the centre chunk: a square of side
+`2 * (radius / 16) + 1` (radius 2500 is 313 x 313 = 97,969 chunks), or the chunks whose distance from the
+centre chunk is at most `radius / 16`. It runs in the dimension the command was run in; that level keeps
+ticking while the task runs, whoever is in it. The progress goes to the server log every five seconds
+and to the player who started it, and once more when it is done. A task is not kept across a restart:
+start it again and the chunks already saved load instead of generating.
+
+## How it works
+
+- `horizon_client::pregen::Pregen` cuts the area into strips at most 256 chunks wide and sweeps each
+  north to south with a band of rows (`streaming::Band`) holding about a thousand chunks.
+- Streaming treats the band like a player's area: it generates its chunks and the rings around them that
+  decoration and light need, and lights its own chunks. Once every chunk of the band's first row is lit
+  and post-processed (`LevelChunk.postProcessGeneration`, which vanilla runs before a chunk is FULL), the
+  band moves down a row; the rows that fall out of its reach unload and are saved like any chunk the
+  players leave, so memory holds only the rows in flight.
+- The chunks a band reaches are ranked for decoration row by row as they come within its reach
+  (`Streaming::set_band`). Decoration is order dependent where neighbours' writes overlap
+  (`DecorationOrder`), and this makes a task decorate in the same order however its jobs are timed and
+  shared among the workers: the same seed gives the same chunks.
+- Between server ticks the server waits for the workers' results and hands out the next jobs at once
+  (`Streaming::wait`, `pump_pregen`), instead of once a tick: a chunk passes through five jobs
+  (generate, decorate, finish, light, save), each needing its neighbours' earlier ones.
+
+The chunks of the band's outer ring are finished (FULL) but not lit, as at the edge of what a player has
+loaded; they light when their neighbours load later.

From 35254c4f0230580e5293146a5203022a3c54d027 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 14:04:28 +0100
Subject: [PATCH 069/270] Pregen: keep an empty dedicated server from pausing
 while it runs

pause-when-empty-seconds paused a server with nobody online after a
minute, and a paused server skips its tick: post-processing stopped, so
the band waited forever on a row of lit chunks. A running /pregen now
counts as activity; the countdown starts once it is done.
---
 crates/horizon-client/src/game/dedicated.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/game/dedicated.rs b/crates/horizon-client/src/game/dedicated.rs
index 9cc892fe0..edea0e800 100644
--- a/crates/horizon-client/src/game/dedicated.rs
+++ b/crates/horizon-client/src/game/dedicated.rs
@@ -667,7 +667,9 @@ impl Game<'_> {
             self.poll_server_control(&mut state);
             let players = self.lan.as_ref().map_or(0, |h| h.hub.guests.len());
             if pause_after > 0 {
-                if players == 0 {
+                // A `/pregen` task keeps the server busy as a player would:
+                // paused, nothing would post-process its chunks.
+                if players == 0 && self.pregen_level().is_none() {
                     state.empty_ticks += 1;
                 } else {
                     state.empty_ticks = 0;

From f56785c2f512eef6eff83687455cbee97ecbcd11 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 13:16:16 +0100
Subject: [PATCH 070/270] Keep a chunk's scheduled ticks when it unloads before
 the next tick

attach_save_data took a chunk's ticks only from the tick scheduler, which
registers new chunks once a tick. A chunk loaded and unloaded again in
between was saved with its block and fluid ticks cleared, though its own
saved list still held them.
---
 crates/horizon-client/src/game/persist.rs | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/crates/horizon-client/src/game/persist.rs b/crates/horizon-client/src/game/persist.rs
index d3afbf6ce..45ef8801f 100644
--- a/crates/horizon-client/src/game/persist.rs
+++ b/crates/horizon-client/src/game/persist.rs
@@ -76,15 +76,14 @@ impl Game<'_> {
         let pos = ChunkPos::new(chunk.x, chunk.z);
         let time = self.world.game_time;
         let mut extras: ChunkExtras = chunk.saved.as_deref().cloned().unwrap_or_default();
+        // A chunk the scheduler hasn't registered yet (one loaded and
+        // unloaded again before the next tick) still holds its saved ticks:
+        // `register_chunk_ticks` empties that list once it takes them.
         if let Some(t) = self.block_ticks.blocks.chunk(pos) {
             extras.block_ticks = t.pack(time);
-        } else {
-            extras.block_ticks.clear();
         }
         if let Some(t) = self.block_ticks.fluids.chunk(pos) {
             extras.fluid_ticks = t.pack(time);
-        } else {
-            extras.fluid_ticks.clear();
         }
         extras.last_update = time;
         // TheEndGatewayBlockEntity saves its Age (the server copy's).

From 4cd1504513ab7c5f9c4bd326fa1e4913adb3147d Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 14:04:28 +0100
Subject: [PATCH 071/270] Pregen: report what a stalled band waits for, and
 requeue lost light

When the band hasn't moved for 30 seconds the task logs how many chunks
of its first row are not loaded, being lit, unlit with no light job or
not post-processed, with the streaming stage counts, and queues light
again for unlit chunks whose neighbours are all loaded.
---
 .../src/game/commands/pregen.rs               | 28 +++++++++++++++++--
 crates/horizon-client/src/pregen.rs           | 11 ++++++++
 crates/horizon-client/src/streaming.rs        | 21 ++++++++++++++
 3 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/commands/pregen.rs b/crates/horizon-client/src/game/commands/pregen.rs
index d61ba63ac..d497e2734 100644
--- a/crates/horizon-client/src/game/commands/pregen.rs
+++ b/crates/horizon-client/src/game/commands/pregen.rs
@@ -14,6 +14,8 @@ use std::time::{Duration, Instant};
 
 /// How often the progress is reported.
 const REPORT_EVERY: Duration = Duration::from_secs(5);
+/// How long the band may stay put before the task looks for what holds it.
+const STALL: Duration = Duration::from_secs(30);
 
 pub(in crate::game) struct PregenTask {
     pregen: Pregen,
@@ -23,6 +25,8 @@ pub(in crate::game) struct PregenTask {
     ran: Duration,
     resumed: Instant,
     reported: Instant,
+    /// When the band last moved, to notice a task that stopped advancing.
+    moved: Instant,
     /// The player who started it, told the progress too (a guest's connection).
     owner: Option<u32>,
 }
@@ -113,6 +117,7 @@ impl Game<'_> {
                     ran: Duration::ZERO,
                     resumed: now,
                     reported: now,
+                    moved: now,
                     owner: self.lan_acting,
                 });
                 Ok(total as i32)
@@ -181,13 +186,32 @@ impl Game<'_> {
         // (`postprocess_chunks`, on the tick), as vanilla's are by the time
         // they are FULL: then they may unload and be saved.
         let (streaming, chunks) = (&mut self.streaming, &self.world.chunks);
-        task.pregen.advance(|x, z| {
+        if task.pregen.advance(|x, z| {
             streaming.is_lit(x, z)
                 && chunks
                     .get(&(x, z))
                     .is_some_and(|c| c.postprocess.is_empty())
-        });
+        }) {
+            task.moved = Instant::now();
+        }
         streaming.set_band(task.pregen.band());
+        if task.moved.elapsed() >= STALL {
+            // Nothing advanced for a while: say what the first row waits
+            // for, and queue light again for chunks that lost their job.
+            task.moved = Instant::now();
+            let row = task.pregen.first_row();
+            let waiting = row
+                .iter()
+                .filter(|k| chunks.get(k).is_some_and(|c| !c.postprocess.is_empty()))
+                .count();
+            let [missing, lighting, unlit] = streaming.unstick_light(&mut self.world, &row);
+            log::warn!(
+                "Horizon: pregeneration waits on row {:?}: {missing} not loaded, {lighting} being lit, \
+                 {unlit} unlit with no light job (queued again), {waiting} not post-processed; {:?}",
+                row.first(),
+                streaming.stages()
+            );
+        }
         let finished = task.pregen.finished();
         if finished || task.reported.elapsed() >= REPORT_EVERY {
             task.reported = Instant::now();
diff --git a/crates/horizon-client/src/pregen.rs b/crates/horizon-client/src/pregen.rs
index f31a6d712..e714bcda2 100644
--- a/crates/horizon-client/src/pregen.rs
+++ b/crates/horizon-client/src/pregen.rs
@@ -105,6 +105,17 @@ impl Pregen {
         moved
     }
 
+    /// The chunks of the band's first row, which it waits for.
+    pub fn first_row(&self) -> Vec<(i32, i32)> {
+        let Some(&(x0, x1)) = self.strips.get(self.strip) else {
+            return Vec::new();
+        };
+        (x0..=x1)
+            .filter(|&x| self.contains(x, self.row))
+            .map(|x| (x, self.row))
+            .collect()
+    }
+
     pub fn finished(&self) -> bool {
         self.strip >= self.strips.len()
     }
diff --git a/crates/horizon-client/src/streaming.rs b/crates/horizon-client/src/streaming.rs
index 51c4eaea4..c9e858aea 100644
--- a/crates/horizon-client/src/streaming.rs
+++ b/crates/horizon-client/src/streaming.rs
@@ -1406,6 +1406,27 @@ impl Streaming {
         }
         self.band_ranked = Some((x0, x1, end.max(first - 1) + 1));
     }
+    /// What holds up the columns `keys`, for a task that stopped advancing:
+    /// how many are not loaded, loaded but unlit with a light job in flight,
+    /// and unlit with none (those whose neighbours are all loaded are queued
+    /// for light again).
+    pub fn unstick_light(&mut self, world: &mut World, keys: &[(i32, i32)]) -> [usize; 3] {
+        let mut counts = [0; 3];
+        for &key in keys {
+            if !world.chunks.contains_key(&key) {
+                counts[0] += 1;
+            } else if self.lit.contains(&key) {
+            } else if self.lighting.contains_key(&key) {
+                counts[1] += 1;
+            } else {
+                counts[2] += 1;
+                if Self::region(world, key.0, key.1).is_some() {
+                    world.dirty_light.insert(key);
+                }
+            }
+        }
+        counts
+    }
     /// Wait up to `timeout` for a worker to finish a job; the next `update`
     /// takes it. A server pumps generation with this between its ticks.
     pub fn wait(&mut self, timeout: std::time::Duration) {

From e181b17e17a88f6c39fbb16dd4b81440d8e738e1 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 13:16:16 +0100
Subject: [PATCH 072/270] Register new chunks' ticks before post-processing
 them

postprocess_chunks ran before tick_blocks registered the chunks that
arrived since the last tick, so the fluid and block ticks their marks
schedule went to chunks the scheduler did not know and were dropped.
Vanilla registers a chunk's tick containers before postProcessGeneration.
---
 crates/horizon-client/src/game/postprocess.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/horizon-client/src/game/postprocess.rs b/crates/horizon-client/src/game/postprocess.rs
index e896a77ab..77cba6832 100644
--- a/crates/horizon-client/src/game/postprocess.rs
+++ b/crates/horizon-client/src/game/postprocess.rs
@@ -27,6 +27,11 @@ impl Game<'_> {
         if ready.is_empty() {
             return Ok(());
         }
+        // The ticks the marks schedule go to the chunks' containers, which a
+        // chunk that arrived since the last tick doesn't have yet
+        // (`LevelChunk.registerTickContainerInLevel` comes before
+        // `postProcessGeneration`).
+        self.sync_tick_chunks();
         for key in ready {
             let Some(chunk) = self.world.chunks.get_mut(&key) else {
                 continue;

From dbafda06ed699a4e6e2653abd2aaa620fcfb1859 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 13:38:10 +0100
Subject: [PATCH 073/270] Surface: specialise the material rule per gradient
 band and surface side

Each chunk's compiled rule is specialised once for every band of y that
its vertical gradients bound, and for blocks below and at or above the
preliminary surface when the rule asks for it. Conditions those facts
decide are folded away, so a deep stone block evaluates only the rules
that can apply there (ore veins, the underground rules) instead of
walking the whole surface tree. Conditions only read the position and
the world, so the blocks are the same.

Surface stage, one thread, seed 1234: 2.45 -> 2.08 ms per chunk.
---
 .../src/worldgen/material_condition.rs        |  75 +++++++++
 .../src/worldgen/material_condition/rule.rs   | 159 +++++++++++++++++-
 .../src/worldgen/material_stage.rs            |  13 +-
 3 files changed, 244 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-world/src/worldgen/material_condition.rs b/crates/horizon-world/src/worldgen/material_condition.rs
index 6433b09a4..d0b6c4290 100644
--- a/crates/horizon-world/src/worldgen/material_condition.rs
+++ b/crates/horizon-world/src/worldgen/material_condition.rs
@@ -23,6 +23,7 @@ use horizon_core::{
 pub use library::MaterialRuleLibrary;
 pub use noise::MaterialNoiseSources;
 use rule::CompiledRule;
+pub use rule::SurfaceVariants;
 pub use rule::{MaterialRule, MaterialRuleError};
 use std::{
     collections::{BTreeMap, BTreeSet},
@@ -299,7 +300,81 @@ enum Kind<R: RandomSource> {
     },
     Not(Box<Compiled<R>>),
 }
+/// What a specialised rule may assume about every position it is applied to
+/// (`CompiledRule::specialize`): its y lies in `low..=high`, and whether it is
+/// at or above the column's preliminary surface level, when known.
+#[derive(Clone, Copy, Debug)]
+pub struct Facts {
+    pub low: i32,
+    pub high: i32,
+    pub above_surface: Option<bool>,
+}
+impl<R: RandomSource> Clone for Kind<R>
+where
+    R::Positional: Clone,
+{
+    fn clone(&self) -> Self {
+        match self {
+            Self::Simple(condition) => Self::Simple(condition.clone()),
+            Self::Biome(names) => Self::Biome(names.clone()),
+            Self::Constant(value) => Self::Constant(*value),
+            Self::Noise { sampler, min, max } => Self::Noise {
+                sampler: *sampler,
+                min: *min,
+                max: *max,
+            },
+            Self::Gradient { low, high, random } => Self::Gradient {
+                low: *low,
+                high: *high,
+                random: random.clone(),
+            },
+            Self::Not(child) => Self::Not(child.clone()),
+        }
+    }
+}
+impl<R: RandomSource> Clone for Compiled<R>
+where
+    R::Positional: Clone,
+{
+    fn clone(&self) -> Self {
+        Self {
+            kind: self.kind.clone(),
+            revision: self.revision,
+            result: self.result,
+        }
+    }
+}
 impl<R: RandomSource> Compiled<R> {
+    /// The value `facts` decide for this condition at every position they
+    /// cover. Conditions read the position and the world, never change them,
+    /// so one decided in advance gives what testing it would.
+    fn decided(&self, facts: Facts) -> Option<bool> {
+        match &self.kind {
+            Kind::Constant(value) => Some(*value),
+            Kind::Simple(MaterialCondition::AbovePreliminarySurface) => facts.above_surface,
+            Kind::Gradient { low, high, .. } => {
+                if facts.high <= *low {
+                    Some(true)
+                } else if facts.low >= *high {
+                    Some(false)
+                } else {
+                    None
+                }
+            }
+            Kind::Not(child) => child.decided(facts).map(|value| !value),
+            _ => None,
+        }
+    }
+    /// The vertical gradients' bounds, and whether the preliminary surface
+    /// is asked for.
+    fn inputs(&self, gradients: &mut Vec<(i32, i32)>, surface: &mut bool) {
+        match &self.kind {
+            Kind::Gradient { low, high, .. } => gradients.push((*low, *high)),
+            Kind::Simple(MaterialCondition::AbovePreliminarySurface) => *surface = true,
+            Kind::Not(child) => child.inputs(gradients, surface),
+            _ => {}
+        }
+    }
     fn constant_result(&self) -> Option<bool> {
         match &self.kind {
             Kind::Constant(value) => Some(*value),
diff --git a/crates/horizon-world/src/worldgen/material_condition/rule.rs b/crates/horizon-world/src/worldgen/material_condition/rule.rs
index cf4fc8547..f3c2ae60d 100644
--- a/crates/horizon-world/src/worldgen/material_condition/rule.rs
+++ b/crates/horizon-world/src/worldgen/material_condition/rule.rs
@@ -1,5 +1,7 @@
 //! Compiled material rule composition, sharing the condition worker's context.
-use super::{Compiled, Context, MaterialCondition, MaterialConditions, MaterialSurfaceQueries};
+use super::{
+    Compiled, Context, Facts, MaterialCondition, MaterialConditions, MaterialSurfaceQueries,
+};
 use crate::{registry::BlockStateId, worldgen::DecodeError};
 use horizon_core::{
     density::DensitySampler,
@@ -209,6 +211,161 @@ impl<R: RandomSource> CompiledRule<R> {
         }
     }
 }
+impl<R: RandomSource> CompiledRule<R>
+where
+    R::Positional: Clone,
+{
+    /// This rule where `facts` hold: conditions they decide are folded away,
+    /// with what can no longer produce a block, and a sequence stops at its
+    /// first child that always produces one. For every position the facts
+    /// cover it gives the block the whole rule gives.
+    fn specialize(&self, facts: Facts) -> Self {
+        match self {
+            Self::Empty => Self::Empty,
+            Self::Block(block) => Self::Block(*block),
+            Self::Bandlands => Self::Bandlands,
+            Self::OreVein {
+                blocks,
+                raw_ore_chance,
+                densities,
+                random,
+            } => Self::OreVein {
+                blocks: *blocks,
+                raw_ore_chance: *raw_ore_chance,
+                densities: *densities,
+                random: random.clone(),
+            },
+            Self::Condition { condition, rule } => match condition.decided(facts) {
+                Some(false) => Self::Empty,
+                Some(true) => rule.specialize(facts),
+                None => match rule.specialize(facts) {
+                    Self::Empty => Self::Empty,
+                    rule => Self::Condition {
+                        condition: condition.clone(),
+                        rule: Box::new(rule),
+                    },
+                },
+            },
+            Self::Sequence(children) => {
+                let mut result = Vec::new();
+                for child in children {
+                    let child = child.specialize(facts);
+                    if matches!(child, Self::Empty) {
+                        continue;
+                    }
+                    let last = child.always_produces();
+                    result.push(child);
+                    if last {
+                        break;
+                    }
+                }
+                match result.len() {
+                    0 => Self::Empty,
+                    1 => result.pop().unwrap(),
+                    _ => Self::Sequence(result),
+                }
+            }
+        }
+    }
+    /// Whether applying this rule never gives `None` (only an error).
+    fn always_produces(&self) -> bool {
+        match self {
+            Self::Block(_) | Self::Bandlands => true,
+            Self::Sequence(children) => children.iter().any(Self::always_produces),
+            Self::Empty | Self::OreVein { .. } | Self::Condition { .. } => false,
+        }
+    }
+    fn inputs(&self, gradients: &mut Vec<(i32, i32)>, surface: &mut bool) {
+        match self {
+            Self::Condition { condition, rule } => {
+                condition.inputs(gradients, surface);
+                rule.inputs(gradients, surface);
+            }
+            Self::Sequence(children) => {
+                for child in children {
+                    child.inputs(gradients, surface);
+                }
+            }
+            _ => {}
+        }
+    }
+}
+/// A rule specialised (`CompiledRule::specialize`) for each band of y between
+/// its vertical gradients' bounds, and below and at or above the preliminary
+/// surface when the rule asks for it: most blocks of a column, deep stone,
+/// then evaluate only the few rules that can apply there.
+pub struct SurfaceVariants {
+    /// The first y of each band after the first, ascending.
+    starts: Vec<i32>,
+    /// The rule index per band (two per band, below then above the surface,
+    /// when `surface`).
+    rules: Vec<usize>,
+    pub surface: bool,
+}
+impl SurfaceVariants {
+    /// The rule for a block at `y`, `above` the preliminary surface (ignored
+    /// unless `surface`).
+    #[inline]
+    pub fn rule(&self, y: i32, above: bool) -> usize {
+        let band = self.starts.partition_point(|&start| start <= y);
+        if self.surface {
+            self.rules[band * 2 + usize::from(above)]
+        } else {
+            self.rules[band]
+        }
+    }
+}
+impl<R: RandomSource, S: MaterialSurfaceQueries> MaterialConditions<R, S>
+where
+    R::Positional: Clone,
+{
+    /// Add the specialised variants of rule `index` (`SurfaceVariants`).
+    pub fn surface_variants(&mut self, index: usize) -> Result<SurfaceVariants, MaterialRuleError> {
+        let rule = self
+            .rules
+            .get(index)
+            .ok_or(MaterialRuleError::UnknownRule)?;
+        let (mut gradients, mut surface) = (Vec::new(), false);
+        rule.inputs(&mut gradients, &mut surface);
+        // A gradient is true at and below `low`, random between, false at
+        // and above `high`: it is decided within each band these bound.
+        let mut starts: Vec<i32> = gradients
+            .iter()
+            .flat_map(|&(low, high)| [low.saturating_add(1), high])
+            .collect();
+        starts.sort_unstable();
+        starts.dedup();
+        let mut variants = Vec::new();
+        for band in 0..=starts.len() {
+            let low = if band == 0 {
+                i32::MIN
+            } else {
+                starts[band - 1]
+            };
+            let high = starts.get(band).map_or(i32::MAX, |&next| next - 1);
+            let sides: &[Option<bool>] = if surface {
+                &[Some(false), Some(true)]
+            } else {
+                &[None]
+            };
+            for &above_surface in sides {
+                let facts = Facts {
+                    low,
+                    high,
+                    above_surface,
+                };
+                variants.push(self.rules[index].specialize(facts));
+            }
+        }
+        let first = self.rules.len();
+        self.rules.extend(variants);
+        Ok(SurfaceVariants {
+            starts,
+            rules: (first..self.rules.len()).collect(),
+            surface,
+        })
+    }
+}
 impl<R: RandomSource, S: MaterialSurfaceQueries> MaterialConditions<R, S> {
     /// Compile all children in order, even after an unconditional block rule.
     /// Failed compilation never adds a partial rule to this worker.
diff --git a/crates/horizon-world/src/worldgen/material_stage.rs b/crates/horizon-world/src/worldgen/material_stage.rs
index 0763c4e63..fd51d3716 100644
--- a/crates/horizon-world/src/worldgen/material_stage.rs
+++ b/crates/horizon-world/src/worldgen/material_stage.rs
@@ -196,7 +196,10 @@ pub fn build_surface<R: RandomSource, S: MaterialSurfaceQueries, B: TerrainBlock
     rule: MaterialRule,
     inputs: SurfaceInputs<'_, R, S>,
     extensions: &MaterialExtensions<R::Positional>,
-) -> Result<(), SurfaceError> {
+) -> Result<(), SurfaceError>
+where
+    R::Positional: Clone,
+{
     let min = chunk.min_y();
     let max = min + chunk.height() - 1;
     if inputs.write_min_y < min
@@ -240,9 +243,13 @@ fn build_columns<R: RandomSource, S: MaterialSurfaceQueries, B: TerrainBlockStat
     extensions: &MaterialExtensions<R::Positional>,
     write_min_y: i32,
     write_max_y: i32,
-) -> Result<(), SurfaceError> {
+) -> Result<(), SurfaceError>
+where
+    R::Positional: Clone,
+{
     let min = chunk.min_y();
     let rule = worker.add_rule(rule)?;
+    let variants = worker.surface_variants(rule)?;
     let cx = chunk.position().x.wrapping_shl(4);
     let cz = chunk.position().z.wrapping_shl(4);
     for lx in 0..16 {
@@ -321,6 +328,8 @@ fn build_columns<R: RandomSource, S: MaterialSurfaceQueries, B: TerrainBlockStat
                     above = above.wrapping_add(1);
                     worker.update_y(above, y.wrapping_sub(bottom).wrapping_add(1), water, y);
                     if y >= write_min_y && y <= write_max_y {
+                        let above = variants.surface && y >= worker.minimum_surface_level()?;
+                        let rule = variants.rule(y, above);
                         if let Some(state) = worker.try_apply(rule, BlockPos::new(x, y, z))? {
                             column.set_block(y, state)?;
                         }

From b457f6382a76b2bfa64077fee92a5bbaa9feca61 Mon Sep 17 00:00:00 2001
From: JasonGu <1456970218@qq.com>
Date: Sun, 25 Oct 2026 21:41:56 +0800
Subject: [PATCH 074/270] Localization: names, container titles, death text and
 search follow the language

- item and block names in tooltips, held labels, command feedback and the
  creative tabs read the selected language; the pinned English map stays
  for logic and search
- Game::translate resolves through lang::get_or, so station titles follow
  the language screen
- container titles and Inventory labels for chests, hoppers, furnaces,
  smokers, blast furnaces, crafters, shulkers and mounts are translated
- server-resolved components (menu titles, death messages, command
  suggestion tooltips) load the selected language over en_us, and follow
  a language change while a world is open
- death messages always reach the death screen translated; the chat
  broadcast still obeys showDeathMessages
- creative search matches the localized display name
- sign editors use sign.edit and hanging_sign.edit

Co-Authored-By: OpenCode DeepSeek V4.1 Flash <noreply@opencode.ai>
---
 crates/horizon-client/src/creative.rs         | 86 ++++++++++++++++++-
 crates/horizon-client/src/game.rs             | 57 ++++++++----
 crates/horizon-client/src/game/commands.rs    |  2 +-
 crates/horizon-client/src/game/lan_actions.rs | 50 +++++------
 crates/horizon-client/src/game/machines.rs    | 50 +++++++----
 .../src/game/machines/crafter.rs              |  3 +-
 crates/horizon-client/src/game/mount_menu.rs  |  3 +-
 crates/horizon-client/src/game/options.rs     |  1 +
 crates/horizon-client/src/game/packs.rs       |  1 +
 crates/horizon-client/src/game/potions.rs     |  2 +-
 crates/horizon-client/src/game/recipe_book.rs |  2 +-
 crates/horizon-client/src/game/remote.rs      |  9 ++
 crates/horizon-client/src/game/sign_edit.rs   | 11 +--
 crates/horizon-client/src/game/stations.rs    | 33 ++++---
 crates/horizon-client/src/game/storage.rs     |  6 +-
 crates/horizon-client/src/game/titles.rs      |  2 +-
 crates/horizon-client/src/game/tweaks.rs      |  2 +-
 crates/horizon-client/src/lang.rs             |  5 ++
 crates/horizon-client/src/menu.rs             |  2 +-
 crates/horizon-client/src/net.rs              | 12 +--
 20 files changed, 236 insertions(+), 103 deletions(-)

diff --git a/crates/horizon-client/src/creative.rs b/crates/horizon-client/src/creative.rs
index e1d1c262e..593aad61d 100644
--- a/crates/horizon-client/src/creative.rs
+++ b/crates/horizon-client/src/creative.rs
@@ -71,10 +71,52 @@ impl Names {
             .cloned()
             .unwrap_or_else(|| path.replace('_', " "))
     }
+    /// An item's display name in the selected language: `item.*` then
+    /// `block.*`, then the pinned English map (`Names::item`).
+    pub fn display_item(&self, id: &str) -> String {
+        let (namespace, path) = id.split_once(':').unwrap_or(("minecraft", id));
+        if let Some(lang) = crate::lang::current() {
+            for prefix in ["item", "block"] {
+                if let Some(name) = lang.get(&format!("{prefix}.{namespace}.{path}")) {
+                    return name.to_owned();
+                }
+            }
+        }
+        self.item(id)
+    }
+    /// A translation key's text in the selected language, else the pinned
+    /// English map (`HoverName` and tooltip keys such as potion names).
+    pub fn display_get(&self, key: &str) -> Option<String> {
+        crate::lang::current()
+            .and_then(|lang| lang.get(key).map(str::to_owned))
+            .or_else(|| self.get(key).map(str::to_owned))
+    }
     pub fn get(&self, key: &str) -> Option<&str> {
         self.map.get(key).map(String::as_str)
     }
 }
+
+/// `CreativeModeTabs`' key for an exported tab id (`itemGroup.*`); the
+/// export's `title` is the English fallback.
+pub fn item_group_key(id: &str) -> Option<&'static str> {
+    Some(match id.trim_start_matches("minecraft:") {
+        "building_blocks" => "itemGroup.buildingBlocks",
+        "colored_blocks" => "itemGroup.coloredBlocks",
+        "natural_blocks" => "itemGroup.natural",
+        "functional_blocks" => "itemGroup.functional",
+        "redstone_blocks" => "itemGroup.redstone",
+        "hotbar" => "itemGroup.hotbar",
+        "search" => "itemGroup.search",
+        "tools_and_utilities" => "itemGroup.tools",
+        "combat" => "itemGroup.combat",
+        "food_and_drinks" => "itemGroup.foodAndDrink",
+        "ingredients" => "itemGroup.ingredients",
+        "spawn_eggs" => "itemGroup.spawnEggs",
+        "op_blocks" => "itemGroup.op",
+        "inventory" => "itemGroup.inventory",
+        _ => return None,
+    })
+}
 impl Creative {
     pub const WIDTH: f32 = 195.0;
     pub const HEIGHT: f32 = 136.0;
@@ -303,7 +345,11 @@ impl Creative {
                 .collect();
         }
         // FullTextSearchTree: tooltip lines, and the item id after a colon.
+        // The export's lines are English (they come from the vanilla jars);
+        // the display name in the selected language is matched too, so a
+        // localized search finds the item.
         let text = java_lower(term);
+        let localized = |i: usize| java_lower(&names.display_item(&self.search_items[i].item));
         all.filter(|&i| {
             let e = &self.search_index[i];
             let fallback;
@@ -314,11 +360,15 @@ impl Creative {
                 &e.lines
             };
             match text.split_once(':') {
-                None => any(lines.iter().map(String::as_str), &text),
+                None => {
+                    any(lines.iter().map(String::as_str), &text) || localized(i).contains(&text)
+                }
                 Some((ns, path)) => {
                     let (ns, path) = (java_trim(ns), java_trim(path));
                     e.namespace.contains(ns)
-                        && (e.path.contains(path) || any(lines.iter().map(String::as_str), path))
+                        && (e.path.contains(path)
+                            || any(lines.iter().map(String::as_str), path)
+                            || localized(i).contains(path))
                 }
             }
         })
@@ -759,6 +809,24 @@ mod tests {
         assert_eq!(q("#craft"), Vec::<usize>::new());
     }
 
+    #[test]
+    fn search_matches_the_display_name_in_the_selected_language() {
+        let c = creative(0);
+        let names = Names {
+            map: HashMap::from([
+                ("item.minecraft.anvil".to_owned(), "铁砧".to_owned()),
+                ("item.minecraft.wooden_hoe".to_owned(), "木锄".to_owned()),
+            ]),
+        };
+        let q = |s: &str| c.search_results(s, &names);
+        assert_eq!(q("铁砧"), [0]);
+        assert_eq!(q("木锄"), [2]);
+        // The English tooltip lines the export indexed still match.
+        assert_eq!(q("anvil"), [0]);
+        // A colon's path searches the display name too.
+        assert_eq!(q("minecraft:铁砧"), [0]);
+    }
+
     #[test]
     fn scrollbar_drag_follows_the_mouse_while_held() {
         let mut c = creative(90);
@@ -794,6 +862,20 @@ mod tests {
         assert!(!c.scrolling);
     }
 
+    #[test]
+    fn creative_tab_titles_have_vanilla_keys() {
+        assert_eq!(
+            item_group_key("minecraft:building_blocks"),
+            Some("itemGroup.buildingBlocks")
+        );
+        assert_eq!(
+            item_group_key("minecraft:food_and_drinks"),
+            Some("itemGroup.foodAndDrink")
+        );
+        assert_eq!(item_group_key("minecraft:hotbar"), Some("itemGroup.hotbar"));
+        assert_eq!(item_group_key("minecraft:nonsense"), None);
+    }
+
     #[test]
     fn wheel_moves_one_row_per_notch() {
         let mut c = creative(90);
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 653a1d038..6bd8f88cb 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -5296,22 +5296,32 @@ impl Game<'_> {
                 Some(BlockEntity::Chest(_)) if self.draw_machine_screen(batch, ox, oy) => {}
                 Some(BlockEntity::Chest(_)) => self.draw_chest_screen(batch, ox, oy),
                 Some(BlockEntity::Furnace(f)) => {
-                    let (tex, title) = match f.kind {
+                    let (tex, key, fallback) = match f.kind {
                         horizon_client::containers::FurnaceKind::Furnace => {
-                            ("gui/container/furnace", "Furnace")
-                        }
-                        horizon_client::containers::FurnaceKind::BlastFurnace => {
-                            ("gui/container/blast_furnace", "Blast Furnace")
+                            ("gui/container/furnace", "container.furnace", "Furnace")
                         }
+                        horizon_client::containers::FurnaceKind::BlastFurnace => (
+                            "gui/container/blast_furnace",
+                            "container.blast_furnace",
+                            "Blast Furnace",
+                        ),
                         horizon_client::containers::FurnaceKind::Smoker => {
-                            ("gui/container/smoker", "Smoker")
+                            ("gui/container/smoker", "container.smoker", "Smoker")
                         }
                     };
                     part(batch, tex, 0.0, 0.0, 176.0, 166.0, ox, oy);
-                    let title = &self.container_title(title.to_owned());
-                    let tw = HudBatch::text_width(atlas, title);
-                    batch.text(atlas, title, ox + (176.0 - tw) / 2.0, oy + 6.0, grey, false);
-                    batch.text(atlas, "Inventory", ox + 8.0, oy + 72.0, grey, false);
+                    let title = self.container_title(self.translate(key, fallback));
+                    let tw = HudBatch::text_width(atlas, &title);
+                    batch.text(
+                        atlas,
+                        &title,
+                        ox + (176.0 - tw) / 2.0,
+                        oy + 6.0,
+                        grey,
+                        false,
+                    );
+                    let inventory = self.translate("container.inventory", "Inventory");
+                    batch.text(atlas, &inventory, ox + 8.0, oy + 72.0, grey, false);
                     if f.lit_remaining > 0 {
                         // AbstractFurnaceScreen: flame height ceil(lit * 13) + 1.
                         let total = if f.lit_total == 0 { 200 } else { f.lit_total };
@@ -5365,14 +5375,12 @@ impl Game<'_> {
                         "gui/container/inventory"
                     };
                     part(batch, texture, 0.0, 0.0, 176.0, 166.0, ox, oy);
-                    let (title, tx) = if self.craft_size == 3 {
-                        ("Crafting", 29.0)
-                    } else {
-                        ("Crafting", 97.0)
-                    };
-                    batch.text(atlas, title, ox + tx, oy + 6.0, grey, false);
+                    let title = self.translate("container.crafting", "Crafting");
+                    let tx = if self.craft_size == 3 { 29.0 } else { 97.0 };
+                    batch.text(atlas, &title, ox + tx, oy + 6.0, grey, false);
                     if self.craft_size == 3 {
-                        batch.text(atlas, "Inventory", ox + 8.0, oy + 72.0, grey, false);
+                        let inventory = self.translate("container.inventory", "Inventory");
+                        batch.text(atlas, &inventory, ox + 8.0, oy + 72.0, grey, false);
                     }
                 }
             }
@@ -9402,6 +9410,11 @@ impl Game<'_> {
     fn creative_origin(batch: &HudBatch) -> (f32, f32) {
         batch.centered_origin(Creative::WIDTH, Creative::HEIGHT)
     }
+    /// A creative tab's title: `itemGroup.*`, else the export's English title.
+    fn creative_tab_title(&self, tab: &horizon_client::creative::Tab) -> String {
+        horizon_client::creative::item_group_key(&tab.id)
+            .map_or_else(|| tab.title.clone(), |key| self.translate(key, &tab.title))
+    }
     /// Vanilla tooltip: dark box with a purple gradient border.
     fn tooltip(&self, batch: &mut HudBatch, text: &str, x: f32, y: f32) {
         let atlas = &self.gui.atlas;
@@ -9471,9 +9484,10 @@ impl Game<'_> {
         }
         let atlas = &self.gui.atlas;
         if !tab.inventory {
+            let title = self.creative_tab_title(&tab);
             batch.text(
                 atlas,
-                &tab.title,
+                &title,
                 ox + 8.0,
                 oy + 6.0,
                 rgba(64, 64, 64, 255),
@@ -9584,7 +9598,12 @@ impl Game<'_> {
                 && self.cursor.1 >= oy + ty
                 && self.cursor.1 < oy + ty + 32.0
             {
-                self.tooltip(batch, &t.title, self.cursor.0, self.cursor.1);
+                self.tooltip(
+                    batch,
+                    &self.creative_tab_title(t),
+                    self.cursor.0,
+                    self.cursor.1,
+                );
             }
         }
         self.draw_carried(batch);
diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index 2e551f440..1bb468a7f 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -439,7 +439,7 @@ impl Game<'_> {
                     .find(|i| i.id == id)
                     .map(|i| i.stack.item.to_string())
                     .unwrap_or_default();
-                Text::literal(self.pack.names.item(&item))
+                Text::literal(self.pack.names.display_item(&item))
             }
             Target::Mob(id)
                 if self
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..03bb15b65 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1791,33 +1791,33 @@ impl Game<'_> {
                 // ServerPlayer.die: dropAllDeathLoot unless a spectator, from the eyes less 0.3.
                 let drops = (g.game_mode != SPECTATOR)
                     .then(|| [at[0], at[1] + g.eye_height() - 0.3, at[2]]);
+                // ServerPlayer.die: the death screen always shows the message;
+                // chat only when the rule allows and the team does not hide it.
                 let cause = host.play.get_mut(&conn).and_then(|p| p.death_cause.take());
-                let message = match cause {
-                    // ServerPlayer.die: the death message, to everyone unless
-                    // the player's team hides it.
-                    Some(key) if self.ui.rules.bool("show_death_messages") => {
-                        let text = horizon_client::text::Text::translate(
-                            &key,
-                            &[self.player_text(&name, uuid)],
-                        );
-                        let message = horizon_client::lan::data::component_nbt(&text.component());
-                        let team = self.score.board.players_team(&name);
-                        if horizon_client::scoreboard::own_death_message_shown(team) {
-                            host.hub.system_message(message.clone());
-                            if self.options.dedicated.is_some() {
-                                super::dedicated::log(
-                                    "INFO",
-                                    &format!("System chat: {}", text.plain()),
-                                );
-                            } else if self.player.is_some() {
-                                self.system_message(text);
-                            }
-                        }
-                        message
+                let key = cause.unwrap_or_else(|| {
+                    if at[1] < f64::from(horizon_client::chunk::MIN_Y - 64) {
+                        "death.attack.outOfWorld".into()
+                    } else {
+                        "death.attack.generic".into()
                     }
-                    Some(_) => literal(""),
-                    None => literal(&format!("{name} died")),
-                };
+                });
+                let text =
+                    horizon_client::text::Text::translate(&key, &[self.player_text(&name, uuid)]);
+                let message = horizon_client::lan::data::component_nbt(&text.component());
+                if self.ui.rules.bool("show_death_messages") {
+                    let team = self.score.board.players_team(&name);
+                    if horizon_client::scoreboard::own_death_message_shown(team) {
+                        host.hub.system_message(message.clone());
+                        if self.options.dedicated.is_some() {
+                            super::dedicated::log(
+                                "INFO",
+                                &format!("System chat: {}", text.plain()),
+                            );
+                        } else if self.player.is_some() {
+                            self.system_message(text);
+                        }
+                    }
+                }
                 host.hub.send_to(
                     conn,
                     &C::PlayerCombatKill(play::PlayerCombatKill { id, message }),
diff --git a/crates/horizon-client/src/game/machines.rs b/crates/horizon-client/src/game/machines.rs
index 8ce1940c9..6866552c1 100644
--- a/crates/horizon-client/src/game/machines.rs
+++ b/crates/horizon-client/src/game/machines.rs
@@ -889,13 +889,31 @@ impl Game<'_> {
         let key_is_cart = self
             .container
             .is_some_and(|k| k.1 == super::minecarts::CART_KEY_Y);
-        let (texture, height, title) = match screen {
-            Screen::Hopper if key_is_cart => {
-                ("gui/container/hopper", 133.0, "Minecart with Hopper")
-            }
-            Screen::Hopper => ("gui/container/hopper", 133.0, "Item Hopper"),
-            Screen::Dispenser => ("gui/container/dispenser", 166.0, "Dispenser"),
-            Screen::Dropper => ("gui/container/dispenser", 166.0, "Dropper"),
+        let (texture, height, key, fallback) = match screen {
+            Screen::Hopper if key_is_cart => (
+                "gui/container/hopper",
+                133.0,
+                "entity.minecraft.hopper_minecart",
+                "Minecart with Hopper",
+            ),
+            Screen::Hopper => (
+                "gui/container/hopper",
+                133.0,
+                "container.hopper",
+                "Item Hopper",
+            ),
+            Screen::Dispenser => (
+                "gui/container/dispenser",
+                166.0,
+                "container.dispenser",
+                "Dispenser",
+            ),
+            Screen::Dropper => (
+                "gui/container/dispenser",
+                166.0,
+                "container.dropper",
+                "Dropper",
+            ),
         };
         if let Some(mut r) = atlas.sprites.get(texture).copied() {
             let dv = (r.v1 - r.v0) / r.h as f32;
@@ -905,23 +923,17 @@ impl Game<'_> {
             batch.rect_uv(ox, oy, 176.0, height, r, u32::MAX);
         }
         let grey = horizon_client::hud::rgba(64, 64, 64, 255);
-        let title = &self
+        let title = self
             .remote_menu_title()
-            .unwrap_or_else(|| self.container_title(title.to_owned()));
+            .unwrap_or_else(|| self.container_title(self.translate(key, fallback)));
         let title_x = if screen == Screen::Hopper {
             8.0
         } else {
-            (176.0 - horizon_client::hud::HudBatch::text_width(atlas, title)) / 2.0
+            (176.0 - horizon_client::hud::HudBatch::text_width(atlas, &title)) / 2.0
         };
-        batch.text(atlas, title, ox + title_x, oy + 6.0, grey, false);
-        batch.text(
-            atlas,
-            "Inventory",
-            ox + 8.0,
-            oy + height - 94.0,
-            grey,
-            false,
-        );
+        batch.text(atlas, &title, ox + title_x, oy + 6.0, grey, false);
+        let inventory = self.translate("container.inventory", "Inventory");
+        batch.text(atlas, &inventory, ox + 8.0, oy + height - 94.0, grey, false);
         true
     }
 }
diff --git a/crates/horizon-client/src/game/machines/crafter.rs b/crates/horizon-client/src/game/machines/crafter.rs
index 0fe66f7c8..b76bafd64 100644
--- a/crates/horizon-client/src/game/machines/crafter.rs
+++ b/crates/horizon-client/src/game/machines/crafter.rs
@@ -256,7 +256,8 @@ impl Game<'_> {
             grey,
             false,
         );
-        batch.text(atlas, "Inventory", ox + 8.0, oy + 72.0, grey, false);
+        let inventory = self.translate("container.inventory", "Inventory");
+        batch.text(atlas, &inventory, ox + 8.0, oy + 72.0, grey, false);
         self.paint_screen(batch, ox, oy, rest, true);
     }
     /// `gui.togglable_slot` over an empty, enabled grid slot.
diff --git a/crates/horizon-client/src/game/mount_menu.rs b/crates/horizon-client/src/game/mount_menu.rs
index e9e1e380b..c80c900f9 100644
--- a/crates/horizon-client/src/game/mount_menu.rs
+++ b/crates/horizon-client/src/game/mount_menu.rs
@@ -470,7 +470,8 @@ impl Game<'_> {
             None => String::new(),
         };
         batch.text(atlas, &title, ox + 8.0, oy + 6.0, grey, false);
-        batch.text(atlas, "Inventory", ox + 8.0, oy + 72.0, grey, false);
+        let inventory = self.translate("container.inventory", "Inventory");
+        batch.text(atlas, &inventory, ox + 8.0, oy + 72.0, grey, false);
         if let Some(m) = self.mobs.iter().find(|m| m.id == open.mob) {
             self.draw_mob_preview(
                 batch,
diff --git a/crates/horizon-client/src/game/options.rs b/crates/horizon-client/src/game/options.rs
index d947f91d0..bb78b8bf8 100644
--- a/crates/horizon-client/src/game/options.rs
+++ b/crates/horizon-client/src/game/options.rs
@@ -246,6 +246,7 @@ impl Game<'_> {
     pub(super) fn load_language(&mut self, code: &str) {
         let root = self.options.resources.clone();
         lang::set(lang::Language::load(&[&root], code));
+        self.refresh_remote_language();
         self.ui.chat.rescale(&self.gui.atlas);
     }
     /// Settings that Horizon applies beyond render distance, volume and GUI scale.
diff --git a/crates/horizon-client/src/game/packs.rs b/crates/horizon-client/src/game/packs.rs
index 7629a5d25..733b19649 100644
--- a/crates/horizon-client/src/game/packs.rs
+++ b/crates/horizon-client/src/game/packs.rs
@@ -203,6 +203,7 @@ impl Game<'_> {
             horizon_client::mobs::villager_hats::VillagerHats::load(root);
         horizon_client::ui::load_metadata(root);
         lang::set(lang::Language::load(&[&root.to_path_buf()], &lang::code()));
+        self.refresh_remote_language();
         self.audio.reload(root);
         self.clear_lod();
         self.streaming.reload_resources(&mut self.world, context);
diff --git a/crates/horizon-client/src/game/potions.rs b/crates/horizon-client/src/game/potions.rs
index b17316e08..49e171ce1 100644
--- a/crates/horizon-client/src/game/potions.rs
+++ b/crates/horizon-client/src/game/potions.rs
@@ -755,7 +755,7 @@ impl Game<'_> {
             image_width,
             &self.potions.effects.list,
             self.clock.rate(),
-            &|key| self.pack.names.get(key).map(str::to_owned),
+            &|key| Some(horizon_client::lang::get(key)),
             &|text| self.gui.atlas.font.width(text).ceil() as i32,
         );
         if let Some(lines) = inventory_effects::paint(
diff --git a/crates/horizon-client/src/game/recipe_book.rs b/crates/horizon-client/src/game/recipe_book.rs
index d3c14ffc7..f68460b7d 100644
--- a/crates/horizon-client/src/game/recipe_book.rs
+++ b/crates/horizon-client/src/game/recipe_book.rs
@@ -502,7 +502,7 @@ impl Game<'_> {
                     horizon_client::item_tooltip::lines(
                         stack,
                         self.res.items().get(&stack.item),
-                        &|k| self.pack.names.get(k).map(str::to_owned),
+                        &|k| Some(horizon_client::lang::get(k)),
                     )
                 })
             {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a71b13a8..e7be063e6 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -4990,6 +4990,15 @@ impl Game<'_> {
     pub(super) fn remote_menu_title(&self) -> Option<String> {
         self.remote.as_ref()?.menu_title.clone()
     }
+    /// A language change reaches the server-sent components too: their titles
+    /// are resolved when the packet arrives, with the session's language.
+    pub(super) fn refresh_remote_language(&mut self) {
+        if let Some(lang) = horizon_client::lang::current()
+            && let Some(r) = self.remote.as_mut()
+        {
+            r.lang = Arc::new(lang.map().clone());
+        }
+    }
     /// A server's chest-like menu (`MenuType.GENERIC_9xN`): its rows and title.
     pub(super) fn remote_chest_menu(&self) -> Option<(usize, String)> {
         let r = self.remote.as_ref()?;
diff --git a/crates/horizon-client/src/game/sign_edit.rs b/crates/horizon-client/src/game/sign_edit.rs
index 5a26e3e69..e8ee0a94d 100644
--- a/crates/horizon-client/src/game/sign_edit.rs
+++ b/crates/horizon-client/src/game/sign_edit.rs
@@ -248,13 +248,14 @@ impl Game<'_> {
         let atlas = &self.gui.atlas;
         let (w, h) = (batch.width, batch.height);
         batch.fill(atlas, 0.0, 0.0, w, h, rgba(16, 16, 16, 160));
-        let title = if sign.hanging {
-            "Edit Hanging Sign Message"
+        let (key, fallback) = if sign.hanging {
+            ("hanging_sign.edit", "Edit Hanging Sign Message")
         } else {
-            "Edit Sign Message"
+            ("sign.edit", "Edit Sign Message")
         };
-        let tw = HudBatch::text_width(atlas, title);
-        batch.text(atlas, title, (w - tw) / 2.0, 40.0, u32::MAX, true);
+        let title = self.translate(key, fallback);
+        let tw = HudBatch::text_width(atlas, &title);
+        batch.text(atlas, &title, (w - tw) / 2.0, 40.0, u32::MAX, true);
         let name = self
             .res
             .facts()
diff --git a/crates/horizon-client/src/game/stations.rs b/crates/horizon-client/src/game/stations.rs
index ffe56d699..2501e892d 100644
--- a/crates/horizon-client/src/game/stations.rs
+++ b/crates/horizon-client/src/game/stations.rs
@@ -277,15 +277,10 @@ fn argb(c: i32) -> u32 {
 }
 
 impl Game<'_> {
-    fn data(&self) -> &stations::StationData {
-        self.res.stations()
-    }
+    /// `Component.translatable`: the selected language (which `lang` layers
+    /// over `en_us`), the caller's English text last.
     pub(super) fn translate(&self, key: &str, fallback: &str) -> String {
-        self.data()
-            .enchantments
-            .translate(key)
-            .unwrap_or(fallback)
-            .to_owned()
+        horizon_client::lang::get_or(key, fallback)
     }
     fn brewing_open(&self) -> bool {
         matches!(self.container_kind(), Some(BlockEntity::Brewing(_)))
@@ -421,7 +416,8 @@ impl Game<'_> {
     pub(super) fn anvil_item_name(&self, s: &Station) -> String {
         match &s.inputs[0] {
             Some(input)
-                if input.custom_name().is_none() && s.name == self.pack.names.item(&input.item) =>
+                if input.custom_name().is_none()
+                    && s.name == self.pack.names.display_item(&input.item) =>
             {
                 String::new()
             }
@@ -462,7 +458,7 @@ impl Game<'_> {
                 let name = self.anvil_item_name(&s);
                 let hover = s.inputs[0]
                     .as_ref()
-                    .map(|i| stations::hover_name(&|id| self.pack.names.item(id), i))
+                    .map(|i| stations::hover_name(&|id| self.pack.names.display_item(id), i))
                     .unwrap_or_default();
                 s.anvil = stations::anvil_result(
                     &data.enchantments,
@@ -895,7 +891,7 @@ impl Game<'_> {
             s.anvil_last = s.inputs[0].clone();
             s.name = s.inputs[0]
                 .as_ref()
-                .map(|i| stations::hover_name(&|id| self.pack.names.item(id), i))
+                .map(|i| stations::hover_name(&|id| self.pack.names.display_item(id), i))
                 .unwrap_or_default();
         }
         self.station_changed();
@@ -1648,28 +1644,29 @@ impl Game<'_> {
         let name = if let Some(n) = stack.custom_name() {
             n.to_owned()
         } else if stack.data().is_some_and(|d| d.ominous_banner) {
-            e.translate("block.minecraft.ominous_banner")
-                .map_or_else(|| "Ominous Banner".to_owned(), str::to_owned)
+            self.translate("block.minecraft.ominous_banner", "Ominous Banner")
         } else if stack.data().and_then(|d| d.potion.as_ref()).is_some()
             || stack.item.ends_with("potion")
             || &*stack.item == "minecraft:tipped_arrow"
         {
             let key = brewing::potion_name_key(&stack.item, stack.potion());
-            e.translate(&key)
-                .map_or_else(|| self.pack.names.item(&stack.item), str::to_owned)
+            self.pack
+                .names
+                .display_get(&key)
+                .unwrap_or_else(|| self.pack.names.display_item(&stack.item))
         } else {
-            self.pack.names.item(&stack.item)
+            self.pack.names.display_item(&stack.item)
         };
         let display = horizon_client::item_tooltip::TooltipDisplay::for_stack(stack);
         let mut lines = Vec::new();
         if display.name_visible(self.screen == Screen::Creative) {
             lines.push((name, color));
         }
-        let translate = |k: &str| e.translate(k).map(str::to_owned);
+        let translate = |k: &str| self.pack.names.display_get(k);
         // ItemContainerContents.addToTooltip.
         let hover_name = |s: &ItemStack| {
             s.custom_name()
-                .map_or_else(|| self.pack.names.item(&s.item), str::to_owned)
+                .map_or_else(|| self.pack.names.display_item(&s.item), str::to_owned)
         };
         if display.shows("minecraft:container") {
             for line in
diff --git a/crates/horizon-client/src/game/storage.rs b/crates/horizon-client/src/game/storage.rs
index 9b28ce26b..bc05b546f 100644
--- a/crates/horizon-client/src/game/storage.rs
+++ b/crates/horizon-client/src/game/storage.rs
@@ -227,7 +227,8 @@ impl Game<'_> {
             );
             let title = self.translate("container.shulkerBox", "Shulker Box");
             batch.text(atlas, &title, ox + 8.0, oy + 6.0, grey, false);
-            batch.text(atlas, "Inventory", ox + 8.0, oy + 73.0, grey, false);
+            let inventory = self.translate("container.inventory", "Inventory");
+            batch.text(atlas, &inventory, ox + 8.0, oy + 73.0, grey, false);
             return;
         }
         let rows = self.chest_rows().unwrap_or(3);
@@ -255,9 +256,10 @@ impl Game<'_> {
             grey,
             false,
         );
+        let inventory = self.translate("container.inventory", "Inventory");
         batch.text(
             atlas,
-            "Inventory",
+            &inventory,
             ox + 8.0,
             oy + 114.0 + rows as f32 * 18.0 - 94.0,
             grey,
diff --git a/crates/horizon-client/src/game/titles.rs b/crates/horizon-client/src/game/titles.rs
index 70ade5595..cbae1f6b4 100644
--- a/crates/horizon-client/src/game/titles.rs
+++ b/crates/horizon-client/src/game/titles.rs
@@ -30,7 +30,7 @@ impl Game<'_> {
         Some(HeldName {
             item: stack.item.to_string(),
             hover_name: Text::literal(item_tooltip::name_line(stack, &|key| {
-                self.pack.names.get(key).map(str::to_owned)
+                self.pack.names.display_get(key)
             })),
             rarity_color: match rarity {
                 "uncommon" => text::YELLOW,
diff --git a/crates/horizon-client/src/game/tweaks.rs b/crates/horizon-client/src/game/tweaks.rs
index 681368cab..cec83e248 100644
--- a/crates/horizon-client/src/game/tweaks.rs
+++ b/crates/horizon-client/src/game/tweaks.rs
@@ -399,7 +399,7 @@ impl Game<'_> {
         }
         let views: Vec<Option<ItemStack>> = slots.iter().map(|&s| self.slot_view(s)).collect();
         let clicks = {
-            let names = |id: &str| self.pack.names.item(id);
+            let names = |id: &str| self.pack.names.display_item(id);
             let rank = |s: &ItemStack| {
                 let order = self.creative_screen.order_of(s).unwrap_or(usize::MAX);
                 (order, hover_name(&names, s))
diff --git a/crates/horizon-client/src/lang.rs b/crates/horizon-client/src/lang.rs
index 15f47285a..79a06229d 100644
--- a/crates/horizon-client/src/lang.rs
+++ b/crates/horizon-client/src/lang.rs
@@ -117,6 +117,11 @@ impl Language {
     pub fn get(&self, key: &str) -> Option<&str> {
         self.map.get(key).map(String::as_str)
     }
+    /// The resolved map, for `horizon_protocol::text::plain`: a server's
+    /// components carry keys, and the network layer resolves them with this.
+    pub fn map(&self) -> &HashMap<String, String> {
+        &self.map
+    }
     pub fn len(&self) -> usize {
         self.map.len()
     }
diff --git a/crates/horizon-client/src/menu.rs b/crates/horizon-client/src/menu.rs
index 07e4ba2b9..912d4498c 100644
--- a/crates/horizon-client/src/menu.rs
+++ b/crates/horizon-client/src/menu.rs
@@ -995,7 +995,7 @@ impl Menu {
     fn anvil_result(&mut self, env: &Env) {
         let hover = self.containers[MAIN][0]
             .as_ref()
-            .map(|i| crate::stations::hover_name(&|id| env.names.item(id), i))
+            .map(|i| crate::stations::hover_name(&|id| env.names.display_item(id), i))
             .unwrap_or_default();
         let out = crate::stations::anvil_result(
             env.enchantments,
diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs
index 9cce9e1c6..2b314f2a8 100644
--- a/crates/horizon-client/src/net.rs
+++ b/crates/horizon-client/src/net.rs
@@ -597,12 +597,14 @@ pub fn json_text(v: &serde_json::Value, lang: &Language) -> String {
     }
 }
 
-/// en_us.json from the prepared resources.
+/// The language a session resolves server-sent components with: the client's
+/// selected language, layered over `en_us` (`ClientLanguage.loadFrom`), so a
+/// menu title the server sends as a key follows the language screen.
 pub fn load_language(resources: &std::path::Path) -> Language {
-    std::fs::read(resources.join("assets/minecraft/lang/en_us.json"))
-        .ok()
-        .and_then(|b| serde_json::from_slice(&b).ok())
-        .unwrap_or_default()
+    let root = resources.to_path_buf();
+    crate::lang::Language::load(&[&root], &crate::lang::code())
+        .map()
+        .clone()
 }
 
 /// Ask a server for its status (ServerStatusPinger): MOTD, players and the

From 56560b467a8fad3ffe02457691bd8486a1a77cb6 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 00:19:47 +0200
Subject: [PATCH 075/270] Multiplayer: answer cookie requests, store cookies,
 follow transfer packets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ClientboundCookieRequestPacket in play state decoded as Unknown and was
dropped; StoreCookie and Transfer likewise, and the configuration-phase
CookieRequest was always answered empty. Proxies (BungeeCord, Velocity)
store and read cookies around a server switch and send Transfer to move
a player to another address — both ended in a kick.

Play-state cookie_request/store_cookie/transfer now have packet types,
cookie requests answer from the stored cookies in both configuration and
play (ClientCommonPacketListenerImpl.handleRequestCookie), stored cookies
land in the session's map (handleStoreCookie), and a transfer reconnects
the game to the target address carrying them (handleTransfer →
ConnectScreen.startConnecting with TransferState).

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game.rs             | 10 +-
 crates/horizon-client/src/game/remote.rs      | 51 +++++++++-
 .../horizon-client/src/game/startup_menu.rs   |  4 +-
 crates/horizon-client/src/net.rs              | 94 +++++++++++++++++--
 crates/horizon-protocol/src/packets/play.rs   |  9 +-
 5 files changed, 153 insertions(+), 15 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..7fcb3be89 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -12098,6 +12098,8 @@ enum PendingWorldEntry {
     Server {
         address: String,
         name: String,
+        /// A transfer's carried-over server cookies (`TransferState`).
+        cookies: Option<horizon_client::net::Cookies>,
     },
 }
 
@@ -12172,8 +12174,12 @@ impl Game<'_> {
             }) => {
                 self.open_world(&folder, name.as_deref(), seed, creative, create.as_deref())?;
             }
-            Some(PendingWorldEntry::Server { address, name }) => {
-                self.connect_server(&address, &name)?;
+            Some(PendingWorldEntry::Server {
+                address,
+                name,
+                cookies,
+            }) => {
+                self.connect_server_with_cookies(&address, &name, cookies)?;
             }
             None => {}
         }
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..c10b64c54 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -193,6 +193,9 @@ pub(super) struct Remote {
     /// the oldest of them first waited (`poll_remote`).
     backlog: VecDeque<Event>,
     backlog_since: Option<Instant>,
+    /// `ClientboundTransferPacket`'s target: when the connection ends the
+    /// game connects here, the stored cookies carried over (`TransferState`).
+    transfer: Option<String>,
 }
 
 /// The time a frame spends on chunk packets before it leaves the rest of
@@ -257,14 +260,25 @@ fn number_format(f: &play::NumberFormat) -> horizon_client::scoreboard::NumberFo
 impl Game<'_> {
     /// Leave the title for a server (ConnectScreen): an empty world fed by the connection.
     pub(super) fn connect_server(&mut self, address: &str, name: &str) -> Result<()> {
+        self.connect_server_with_cookies(address, name, None)
+    }
+    /// `connect_server` carrying a transfer's stored server cookies
+    /// (`TransferState`); None on an ordinary join.
+    pub(super) fn connect_server_with_cookies(
+        &mut self,
+        address: &str,
+        name: &str,
+        cookies: Option<horizon_client::net::Cookies>,
+    ) -> Result<()> {
         if self.defer_world_entry(super::PendingWorldEntry::Server {
             address: address.to_owned(),
             name: name.to_owned(),
+            cookies: cookies.clone(),
         })? {
             return Ok(());
         }
         self.join_world_rest()?;
-        if let Err(error) = self.join_server(address, name, None) {
+        if let Err(error) = self.join_server(address, name, None, cookies) {
             log::warn!("Horizon: could not join server: {error}");
             if self.title.is_none() {
                 self.title = Some(horizon_client::title::Title::new(
@@ -285,13 +299,14 @@ impl Game<'_> {
         pipe: horizon_protocol::connection::Pipe,
         name: &str,
     ) -> Result<()> {
-        self.join_server("local", name, Some(pipe))
+        self.join_server("local", name, Some(pipe), None)
     }
     fn join_server(
         &mut self,
         address: &str,
         name: &str,
         local: Option<horizon_protocol::connection::Pipe>,
+        cookies: Option<horizon_client::net::Cookies>,
     ) -> Result<()> {
         self.perf.world_opening();
         let root = self.options.resources.clone();
@@ -323,7 +338,17 @@ impl Game<'_> {
             Some(pipe) => Session::connect_local(pipe, name, view, lang.clone()),
             None => {
                 self.extras_connecting(address, name);
-                Session::connect(address, name, auth.clone(), view, lang.clone())
+                match cookies {
+                    Some(cookies) => Session::connect_transferred(
+                        address,
+                        name,
+                        auth.clone(),
+                        view,
+                        lang.clone(),
+                        cookies,
+                    ),
+                    None => Session::connect(address, name, auth.clone(), view, lang.clone()),
+                }
             }
         };
         let player_type = super::perspective::player_type(&root);
@@ -446,6 +471,7 @@ impl Game<'_> {
             chunk_center: (0, 0),
             backlog: VecDeque::new(),
             backlog_since: None,
+            transfer: None,
         });
         // The level's TickRateManager follows the server's ticking packets.
         self.clock = horizon_client::clock::FixedStep::client();
@@ -867,6 +893,11 @@ impl Game<'_> {
                     }
                 }
                 Event::Reconfigured(registries) => self.set_registries(registries),
+                Event::Transfer { host, port } => {
+                    if let Some(r) = self.remote.as_mut() {
+                        r.transfer = Some(format!("{host}:{port}"));
+                    }
+                }
                 Event::PackPush(p) => self.handle_pack_push(p),
                 Event::PackPop(id) => self.handle_pack_pop(id),
                 Event::DecodeError(e) => {
@@ -882,6 +913,20 @@ impl Game<'_> {
                     from_server,
                 } => {
                     log::info!("Horizon: disconnected: {reason}");
+                    // ClientboundTransferPacket left a target: connect there
+                    // instead of showing the disconnect, the stored cookies
+                    // carried over (ClientCommonPacketListenerImpl.
+                    // handleTransfer → ConnectScreen.startConnecting).
+                    let transfer = self.remote.as_mut().and_then(|r| {
+                        r.transfer.take().map(|address| {
+                            (address, r.session.name.clone(), r.session.cookies.clone())
+                        })
+                    });
+                    if let Some((address, name, cookies)) = transfer {
+                        self.leave_server(None)?;
+                        self.connect_server_with_cookies(&address, &name, Some(cookies))?;
+                        return Ok(());
+                    }
                     let retry = self.reconnect_after(&reason, from_server);
                     self.leave_server(Some(reason))?;
                     self.offer_reconnect(retry);
diff --git a/crates/horizon-client/src/game/startup_menu.rs b/crates/horizon-client/src/game/startup_menu.rs
index 96af99bbc..fe568fe71 100644
--- a/crates/horizon-client/src/game/startup_menu.rs
+++ b/crates/horizon-client/src/game/startup_menu.rs
@@ -33,6 +33,7 @@ impl StartupMenu {
             Some(PendingWorldEntry::Server {
                 address: address.clone(),
                 name: options.player_name(),
+                cookies: None,
             })
         } else {
             options
@@ -125,6 +126,7 @@ impl StartupMenu {
             Action::Connect { address } => PendingWorldEntry::Server {
                 address,
                 name: player_name,
+                cookies: None,
             },
             _ => return,
         };
@@ -762,7 +764,7 @@ mod tests {
             "Guest".into(),
         );
         assert!(
-            matches!(menu.pending.take(), Some(PendingWorldEntry::Server { address, name })
+            matches!(menu.pending.take(), Some(PendingWorldEntry::Server { address, name, .. })
             if address == "localhost:25565" && name == "Guest")
         );
         assert!(menu.pending.take().is_none(), "an entry is consumed once");
diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs
index 9cce9e1c6..c4e53cef4 100644
--- a/crates/horizon-client/src/net.rs
+++ b/crates/horizon-client/src/net.rs
@@ -18,6 +18,7 @@ use horizon_protocol::{
     text::{Language, plain, translatable},
 };
 use std::{
+    collections::HashMap,
     sync::{
         Arc, Mutex,
         atomic::{AtomicBool, Ordering},
@@ -27,6 +28,12 @@ use std::{
     time::Duration,
 };
 
+/// `CommonListenerCookie.serverCookies`: cookies the server asked the client
+/// to store (`ClientboundStoreCookiePacket`), answered to
+/// `ClientboundCookieRequestPacket`. A `transfer` carries them to the next
+/// connection (`TransferState`), so a proxy's backend switch keeps them.
+pub type Cookies = Arc<Mutex<HashMap<String, Vec<u8>>>>;
+
 /// What the network thread reports to the game.
 pub enum Event {
     /// Progress text for the connecting screen.
@@ -48,6 +55,13 @@ pub enum Event {
     PackPush(cfg::ResourcePackPush),
     /// ClientboundResourcePackPopPacket: one pack, or every pack.
     PackPop(Option<u128>),
+    /// `ClientboundTransferPacket`: the server sent us to another address.
+    /// The connection ends right after; the game reconnects there with the
+    /// stored cookies.
+    Transfer {
+        host: String,
+        port: i32,
+    },
     /// The connection ended. `from_server`: the server gave the reason (or
     /// the connection was refused for good), rather than the connection
     /// failing (auto-reconnect retries only failures and shutdowns).
@@ -67,6 +81,8 @@ pub struct Session {
     pub address: String,
     pub name: String,
     pub counters: Arc<Mutex<Option<Arc<Counters>>>>,
+    /// The cookies this server stored on us (`ClientboundStoreCookiePacket`).
+    pub cookies: Cookies,
     /// HORIZON_NET_DEBUG=1 logs every packet sent from the game thread.
     debug: bool,
 }
@@ -79,7 +95,27 @@ impl Session {
         view_distance: i8,
         lang: Arc<Language>,
     ) -> Self {
-        Self::start(address, name, auth, view_distance, lang, None)
+        Self::start(address, name, auth, view_distance, lang, None, None)
+    }
+    /// `ConnectScreen.startConnecting` for a `transfer`: the cookies the
+    /// server stored carry to the new connection (`TransferState`).
+    pub fn connect_transferred(
+        address: &str,
+        name: &str,
+        auth: Option<Arc<AuthSession>>,
+        view_distance: i8,
+        lang: Arc<Language>,
+        cookies: Cookies,
+    ) -> Self {
+        Self::start(
+            address,
+            name,
+            auth,
+            view_distance,
+            lang,
+            None,
+            Some(cookies),
+        )
     }
     /// Join an integrated server through memory (`Connection.connectToLocalServer`).
     pub fn connect_local(
@@ -88,7 +124,7 @@ impl Session {
         view_distance: i8,
         lang: Arc<Language>,
     ) -> Self {
-        Self::start("local", name, None, view_distance, lang, Some(pipe))
+        Self::start("local", name, None, view_distance, lang, Some(pipe), None)
     }
     fn start(
         address: &str,
@@ -97,12 +133,15 @@ impl Session {
         view_distance: i8,
         lang: Arc<Language>,
         local: Option<horizon_protocol::connection::Pipe>,
+        cookies: Option<Cookies>,
     ) -> Self {
         let (send, events) = channel();
         let writer = Arc::new(Mutex::new(None));
         let configuring = Arc::new(AtomicBool::new(true));
         let counters = Arc::new(Mutex::new(None));
-        let (thread_writer, thread_counters) = (writer.clone(), counters.clone());
+        let cookies = cookies.unwrap_or_default();
+        let (thread_writer, thread_counters, thread_cookies) =
+            (writer.clone(), counters.clone(), cookies.clone());
         let thread_configuring = configuring.clone();
         let (address_owned, name_owned) = (address.to_owned(), name.to_owned());
         let thread = std::thread::Builder::new()
@@ -119,6 +158,7 @@ impl Session {
                     &thread_writer,
                     &thread_configuring,
                     &thread_counters,
+                    &thread_cookies,
                 );
                 let from_server = result.is_ok();
                 let reason = result.unwrap_or_else(|e| e);
@@ -140,6 +180,7 @@ impl Session {
             address: address.to_owned(),
             name: name.to_owned(),
             counters,
+            cookies,
             debug,
         }
     }
@@ -291,6 +332,7 @@ fn run(
     shared_writer: &Mutex<Option<ConnWriter>>,
     configuring: &AtomicBool,
     shared_counters: &Mutex<Option<Arc<Counters>>>,
+    cookies: &Cookies,
 ) -> Result<String, String> {
     let (host, port, mut c) = if let Some(pipe) = local {
         (address.to_owned(), 0, Connection::local(pipe))
@@ -419,13 +461,13 @@ fn run(
     .map_err(e)?;
     let (mut reader, writer) = c.split();
     *shared_writer.lock().unwrap() = Some(writer);
-    let registries = configure(&mut reader, shared_writer, configuring, lang, send)?;
+    let registries = configure(&mut reader, shared_writer, configuring, lang, send, cookies)?;
     let _ = send.send(Event::Joined {
         registries: Arc::new(registries),
         uuid: profile.uuid,
         name: profile.name,
     });
-    receive_play(&mut reader, shared_writer, configuring, lang, send)
+    receive_play(&mut reader, shared_writer, configuring, lang, send, cookies)
 }
 
 fn receive_play(
@@ -434,6 +476,7 @@ fn receive_play(
     configuring: &AtomicBool,
     lang: &Language,
     send: &Sender<Event>,
+    cookies: &Cookies,
 ) -> Result<String, String> {
     loop {
         let (id, payload) = reader.recv().map_err(|e| e.to_string())?;
@@ -469,9 +512,31 @@ fn receive_play(
                     let _ = w.send(&play::Serverbound::ConfigurationAcknowledged(Empty).encode());
                     configuring.store(true, Ordering::Relaxed);
                 }
-                let registries = configure(reader, shared_writer, configuring, lang, send)?;
+                let registries =
+                    configure(reader, shared_writer, configuring, lang, send, cookies)?;
                 let _ = send.send(Event::Reconfigured(Arc::new(registries)));
             }
+            // ClientCommonPacketListenerImpl.handleRequestCookie: the stored
+            // cookie (or none) goes straight back.
+            play::Clientbound::CookieRequest(q) => {
+                let payload = cookies.lock().unwrap().get(&q.key).cloned();
+                reply(play::Serverbound::CookieResponse(cfg::CookieResponse {
+                    key: q.key,
+                    payload,
+                }));
+            }
+            play::Clientbound::StoreCookie(p) => {
+                cookies.lock().unwrap().insert(p.key, p.payload);
+            }
+            // ClientCommonPacketListenerImpl.handleTransfer: the connection
+            // ends and the game connects to the other address.
+            play::Clientbound::Transfer(p) => {
+                let _ = send.send(Event::Transfer {
+                    host: p.host,
+                    port: p.port,
+                });
+                return Ok(tr(lang, "disconnect.transfer"));
+            }
             play::Clientbound::Disconnect(d) => return Ok(plain(&d.reason, lang)),
             play::Clientbound::CustomPayload(p) if p.channel == "minecraft:brand" => {
                 receive_brand(&p, send);
@@ -493,6 +558,7 @@ fn configure(
     configuring: &AtomicBool,
     lang: &Language,
     send: &Sender<Event>,
+    cookies: &Cookies,
 ) -> Result<Dynamic, String> {
     let mut registries = Dynamic::default();
     let reply = |p: cfg::Serverbound| -> Result<(), String> {
@@ -525,11 +591,22 @@ fn configure(
                 let _ = send.send(Event::PackPop(p.id));
             }
             cfg::Clientbound::CookieRequest(q) => {
+                let payload = cookies.lock().unwrap().get(&q.key).cloned();
                 reply(cfg::Serverbound::CookieResponse(cfg::CookieResponse {
                     key: q.key,
-                    payload: None,
+                    payload,
                 }))?
             }
+            cfg::Clientbound::StoreCookie(p) => {
+                cookies.lock().unwrap().insert(p.key, p.payload);
+            }
+            cfg::Clientbound::Transfer(p) => {
+                let _ = send.send(Event::Transfer {
+                    host: p.host,
+                    port: p.port,
+                });
+                return Err(tr(lang, "disconnect.transfer"));
+            }
             cfg::Clientbound::Disconnect(d) => return Err(plain(&d.reason, lang)),
             cfg::Clientbound::FinishConfiguration(_) => {
                 let mut w = writer.lock().unwrap();
@@ -659,6 +736,7 @@ mod tests {
                 &AtomicBool::new(false),
                 &Language::new(),
                 &send,
+                &Cookies::default(),
             )
         });
         let mut server = Connection::local(server);
@@ -708,6 +786,7 @@ mod tests {
             address: "local".into(),
             name: "Player".into(),
             counters: Arc::new(Mutex::new(None)),
+            cookies: Cookies::default(),
             debug: false,
         };
         let (thread_writer, thread_configuring) =
@@ -719,6 +798,7 @@ mod tests {
                 &thread_configuring,
                 &Language::new(),
                 &send,
+                &Cookies::default(),
             )
         });
         let mut server = Connection::local(server);
diff --git a/crates/horizon-protocol/src/packets/play.rs b/crates/horizon-protocol/src/packets/play.rs
index 26bb96316..67373cf4b 100644
--- a/crates/horizon-protocol/src/packets/play.rs
+++ b/crates/horizon-protocol/src/packets/play.rs
@@ -13,8 +13,9 @@ use crate::{
     packets::{
         Empty,
         configuration::{
-            ClientInformation, CustomPayload, Disconnect, KeepAlive, Ping, ResourcePackPop,
-            ResourcePackPush, ResourcePackResponse, UpdateTags,
+            ClientInformation, CookieRequest, CookieResponse, CustomPayload, Disconnect, KeepAlive,
+            Ping, ResourcePackPop, ResourcePackPush, ResourcePackResponse, StoreCookie, Transfer,
+            UpdateTags,
         },
         login::Property,
     },
@@ -1759,6 +1760,7 @@ packet_enum!(Clientbound, crate::ids::play::clientbound {
     ContainerSetContent(ContainerSetContent) = CONTAINER_SET_CONTENT,
     ContainerSetData(ContainerSetData) = CONTAINER_SET_DATA,
     ContainerSetSlot(ContainerSetSlot) = CONTAINER_SET_SLOT,
+    CookieRequest(CookieRequest) = COOKIE_REQUEST,
     CustomPayload(CustomPayload) = CUSTOM_PAYLOAD,
     Disconnect(Disconnect) = DISCONNECT,
     DisguisedChat(DisguisedChat) = DISGUISED_CHAT,
@@ -1836,6 +1838,7 @@ packet_enum!(Clientbound, crate::ids::play::clientbound {
     SoundEntity(SoundEntity) = SOUND_ENTITY,
     StopSound(StopSound) = STOP_SOUND,
     StartConfiguration(Empty) = START_CONFIGURATION,
+    StoreCookie(StoreCookie) = STORE_COOKIE,
     SwingAnimation(SwingAnimation) = SWING_ANIMATION,
     SystemChat(SystemChat) = SYSTEM_CHAT,
     TabList(TabList) = TAB_LIST,
@@ -1843,6 +1846,7 @@ packet_enum!(Clientbound, crate::ids::play::clientbound {
     TeleportEntity(TeleportEntity) = TELEPORT_ENTITY,
     TickingState(TickingState) = TICKING_STATE,
     TickingStep(TickingStep) = TICKING_STEP,
+    Transfer(Transfer) = TRANSFER,
     UpdateAdvancements(UpdateAdvancements) = UPDATE_ADVANCEMENTS,
     UpdateAttributes(UpdateAttributes) = UPDATE_ATTRIBUTES,
     LevelParticles(LevelParticles) = LEVEL_PARTICLES,
@@ -2223,6 +2227,7 @@ packet_enum!(Serverbound, crate::ids::play::serverbound {
     ContainerButtonClick(ContainerButtonClick) = CONTAINER_BUTTON_CLICK,
     ContainerClick(ContainerClick) = CONTAINER_CLICK,
     ContainerClose(ContainerClose) = CONTAINER_CLOSE,
+    CookieResponse(CookieResponse) = COOKIE_RESPONSE,
     CustomPayload(CustomPayload) = CUSTOM_PAYLOAD,
     EditBook(EditBook) = EDIT_BOOK,
     Interact(Interact) = INTERACT,

From a2fccf0205c133ef871bb9a781dddac1cce52a6c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:52:17 +0100
Subject: [PATCH 076/270] Flint and steel lights nether portals only in the
 Overworld and the Nether

BaseFireBlock.inPortalDimension: a frame lit in the End stays a fire.
The world code's fire placement already checked it; the flint-and-steel
path (Game::try_light_portal) didn't, so a portal could be lit and used
in the End in every mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..36926afde 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -7879,8 +7879,12 @@ impl Game<'_> {
             (0..width).all(|i| frame([left[0] + d[0] * i, left[1] + height, left[2] + d[2] * i]));
         ((3..=21).contains(&height) && top_ok).then_some((left, width, height))
     }
-    /// BaseFireBlock.onPlace: lighting fire inside a frame creates a portal.
+    /// BaseFireBlock.onPlace: lighting fire inside a frame creates a portal,
+    /// only in the Overworld and the Nether (`inPortalDimension`).
     fn try_light_portal(&mut self, at: [i32; 3]) -> Result<bool> {
+        if !matches!(self.dim, Dim::Overworld | Dim::Nether) {
+            return Ok(false);
+        }
         for x_axis in [true, false] {
             if let Some((origin, width, height)) = self.portal_shape(at, x_axis) {
                 let d = if x_axis { [1, 0, 0] } else { [0, 0, 1] };

From 319c7fcaee27a70ac847e55c7f04147df648b476 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:58:51 +0100
Subject: [PATCH 077/270] A server's client shows the nether portal effect

NetherPortalBlock.entityInside runs on the client's own level too: its
setAsInsidePortal drives LocalPlayer.handlePortalTransitionEffect (the
purple overlay, block.portal.trigger). The remote motion loop dropped
MotionEvent::InsidePortal, so single player on the server thread, LAN
guests and dedicated servers' players went through portals without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/nether_portal.rs | 12 ++++++++++++
 crates/horizon-client/src/game/remote.rs        |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/crates/horizon-client/src/game/nether_portal.rs b/crates/horizon-client/src/game/nether_portal.rs
index a30cf822a..353ad216c 100644
--- a/crates/horizon-client/src/game/nether_portal.rs
+++ b/crates/horizon-client/src/game/nether_portal.rs
@@ -270,6 +270,18 @@ impl Game<'_> {
         self.portals.player.set_inside(pos, PLAYER_DELAY);
         self.portals.client_inside = true;
     }
+    /// The same on a server's client: `Entity.canUsePortal` (alive, not a
+    /// passenger), then only the client's `setAsInsidePortal`, which drives
+    /// the confusion effect (`client_portal_effect`).
+    pub(super) fn client_inside_nether_portal(&mut self) {
+        let alive = self
+            .player
+            .as_ref()
+            .is_some_and(|p| !p.health.dead_or_dying());
+        if alive && self.riding.is_none() {
+            self.portals.client_inside = true;
+        }
+    }
     /// `ServerPlayer.handlePortal` (not while changing dimension: there is no
     /// player then). Players wait `players_nether_portal_default_delay`
     /// ticks, or the creative delay with invulnerable abilities.
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..c3fc23535 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -3318,6 +3318,12 @@ impl Game<'_> {
                     self.audio
                         .play("minecraft:entity.player.swim", Some(feet), volume, pitch);
                 }
+                // NetherPortalBlock.entityInside on the client's own level:
+                // the portal overlay and its trigger sound (the server moves
+                // the player).
+                horizon_client::motion::MotionEvent::InsidePortal { .. } => {
+                    self.client_inside_nether_portal();
+                }
                 _ => {}
             }
         }

From 93d05591c26a9706bdecd8ab63918b8776aded21 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:04:04 +0100
Subject: [PATCH 078/270] horizon-mod-registry: a submission's pull request
 says it came through the form
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The form opens pull requests with the registry's token, which is Ludovic's
account, so the body now starts "🤖 Submitted through playhorizon.dev by
@login" and says neither Ludovic nor a reviewer wrote it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-mod-registry/src/lib.rs      | 7 ++++++-
 crates/horizon-mod-registry/tests/submit.rs | 6 +++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-mod-registry/src/lib.rs b/crates/horizon-mod-registry/src/lib.rs
index 9799bace8..72970017a 100644
--- a/crates/horizon-mod-registry/src/lib.rs
+++ b/crates/horizon-mod-registry/src/lib.rs
@@ -625,11 +625,16 @@ pub fn publish(
         .map(|r| format!("- needs {} {}", r.id, r.version))
         .collect();
     let body = format!(
-        "<!-- submitted-by: {login} -->\nSubmitted by @{login} through [the form]({public}/mods/submit).\n\n\
+        "<!-- submitted-by: {login} -->\n🤖 Submitted through [{site}]({public}/mods/submit) by @{login}. The form opens the pull request with \
+         the registry's token: neither Ludovic nor a reviewer wrote it.\n\n\
          | | |\n|---|---|\n| Project | `{id}` ({kind}, {new}) |\n| Version | {version} for {game} |\n| File | `{file}`, {size} bytes, SHA-256 `{sha256}` |\n| Signed | {signed} |\n| Source | {source} |\n\n{lists}\n\n\
          The checks below run the file's own checks again and, for a mod, a trial run in the sandbox. \
          Reviewers: read the source and the checks' report before you approve.",
         public = config.public_url,
+        site = config
+            .public_url
+            .split_once("://")
+            .map_or(config.public_url.as_str(), |(_, host)| host),
         id = form.id,
         kind = kind.name(),
         new = if is_new { "new" } else { "update" },
diff --git a/crates/horizon-mod-registry/tests/submit.rs b/crates/horizon-mod-registry/tests/submit.rs
index 77487089d..f586effac 100644
--- a/crates/horizon-mod-registry/tests/submit.rs
+++ b/crates/horizon-mod-registry/tests/submit.rs
@@ -303,7 +303,11 @@ async fn a_submission_becomes_a_pull_request() {
         assert!(message.contains("Co-authored-by: alice <7+alice@users.noreply.github.com>"));
         assert_eq!(replaced, &None);
         let body = m.pulls[0]["body"].as_str().unwrap();
-        assert!(body.starts_with("<!-- submitted-by: alice -->"), "{body}");
+        assert!(
+            body.starts_with("<!-- submitted-by: alice -->\n🤖 Submitted through "),
+            "{body}"
+        );
+        assert!(body.contains("/mods/submit) by @alice."), "{body}");
         assert!(body.contains("may draw text on your screen"), "{body}");
     }
     // The same version again: its branch is there.

From e9d2c1041774e9e291c2b8e360bf5c7e2485ffb7 Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 10:32:36 -0300
Subject: [PATCH 079/270] Peaceful zombie horses spawn without their zombie
 rider

ZombieHorse.finalizeSpawn gets its rider from EntityType.create, which
returns null for a notInPeaceful type (the zombie) in peaceful, so vanilla
spawns the zombie horse alone there. spawn_jockeys created the rider
regardless. mobs/finalize.rs already skips it through level.create.

Fixes #1761.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/passengers.rs | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/passengers.rs b/crates/horizon-client/src/game/passengers.rs
index b20c1560b..8f205c484 100644
--- a/crates/horizon-client/src/game/passengers.rs
+++ b/crates/horizon-client/src/game/passengers.rs
@@ -147,8 +147,16 @@ impl Game<'_> {
                 }
             }
             Species::Strider if !baby => self.spawn_strider_jockey(id, at),
-            // ZombieHorse.finalizeSpawn: a zombie with an iron spear.
-            Species::ZombieHorse if natural => {
+            // ZombieHorse.finalizeSpawn: a zombie with an iron spear. The rider
+            // comes from EntityType.create, which makes no zombie in peaceful
+            // (canSpawn), so a peaceful zombie horse spawns without one.
+            Species::ZombieHorse
+                if natural
+                    && (self.ui.difficulty != 0
+                        || horizon_client::mobs::spawn_rules::allowed_in_peaceful(
+                            Species::Zombie,
+                        )) =>
+            {
                 if let Some(zombie) = self.spawn_mob("minecraft:zombie", at, false) {
                     if let Some(z) = self.mobs.iter_mut().find(|m| m.id == zombie) {
                         z.extra.main_hand = Some("minecraft:iron_spear".into());

From ceff5a2110bfcaf460898909f08e532f19f767e2 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:06:34 +0100
Subject: [PATCH 080/270] Launcher: installing a taken-down registry mod says
 it was taken down, and why

It said the mod had no version for 26.3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/browser/horizon.rs       | 17 +++++++++++++----
 launcher/src/browser/horizon/tests.rs |  2 +-
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index 5333e481d..501295c6b 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -374,10 +374,19 @@ fn install_from(
 
 /// A project's newest version for this game that wasn't taken down.
 fn newest<'a>(index: &Index, p: &'a index::Project) -> Result<&'a index::Version, String> {
-    p.versions
-        .iter()
-        .find(|v| v.game == GAME && index.revoked(&p.id, &v.file.sha256).is_none())
-        .ok_or_else(|| format!("{} has no version for {GAME} to install.", p.name))
+    let mut taken_down = None;
+    for v in p.versions.iter().filter(|v| v.game == GAME) {
+        match index.revoked(&p.id, &v.file.sha256) {
+            None => return Ok(v),
+            Some(r) => {
+                taken_down.get_or_insert(r);
+            }
+        }
+    }
+    Err(match taken_down {
+        Some(r) => format!("{} was taken down: {}", p.name, r.reason),
+        None => format!("{} has no version for {GAME} to install.", p.name),
+    })
 }
 
 /// Installs version `v` of the registry's mod or resource pack `p` into the game folder `home`.
diff --git a/launcher/src/browser/horizon/tests.rs b/launcher/src/browser/horizon/tests.rs
index caff9cd99..bf98719d7 100644
--- a/launcher/src/browser/horizon/tests.rs
+++ b/launcher/src/browser/horizon/tests.rs
@@ -123,7 +123,7 @@ fn refuses_a_changed_file_a_taken_id_and_local_files_from_the_real_registry() {
         date: String::new(),
     });
     let e = install_from(&taken_down, true, &p, &home, &|_, _| {}).unwrap_err();
-    assert!(e.contains("no version"), "{e}");
+    assert_eq!(e, "Coordinates HUD was taken down: Test.");
     fs::remove_dir_all(&home).unwrap();
 }
 

From 0f2a497f0241248adcbe88d564004b0c9bec122f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:09:16 +0100
Subject: [PATCH 081/270] Trapped chests give their signal, barrels show
 they're open

TrappedChestBlock.getSignal is the chest's opener count (at most 15);
TrappedChestBlockEntity.signalOpenCount updates the blocks around it and
below it when the count changes. GameLevel answered 0 for every trapped
chest. BarrelBlockEntity's openers set open=true for the first one and
open=false when the last one leaves; nothing set it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  7 +++
 .../src/game/block_entity_anims.rs            | 60 ++++++++++++++++---
 .../src/game/machines/crafter.rs              |  2 +-
 3 files changed, 61 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..64f37ec31 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -548,6 +548,8 @@ struct GameLevel<'w> {
     /// Where the chunk tickets let blocks tick.
     tickets: horizon_client::ticket_levels::Levels,
     random_tick_sections: &'w mut horizon_client::random_tick_sections::RandomTickSections,
+    /// Players with each chest open (a trapped chest's signal).
+    lid_openers: &'w HashMap<(i32, i32, i32), i32>,
 }
 struct PlayerCollision {
     y: f64,
@@ -683,6 +685,10 @@ impl LevelAccess for GameLevel<'_> {
         _state: BlockStateId,
         _direction: Direction,
     ) -> i32 {
+        // TrappedChestBlock.getSignal: the players with it open, at most 15.
+        if let Some(count) = self.lid_openers.get(&(pos.x, pos.y, pos.z)) {
+            return (*count).clamp(0, 15);
+        }
         jukebox::jukebox_signals(self.world, self.items, pos).map_or(0, |(signal, _)| signal)
     }
     fn biome_name(&self, pos: BlockPos) -> Option<&str> {
@@ -2428,6 +2434,7 @@ impl Game<'_> {
             spill: &mut self.spill,
             tickets: self.tickets.levels(),
             random_tick_sections: &mut self.random_tick_sections,
+            lid_openers: &self.lid_openers,
         };
         let result = f(self.res.behaviours(), &mut level, &mut self.block_ticks);
         self.flush_spill();
diff --git a/crates/horizon-client/src/game/block_entity_anims.rs b/crates/horizon-client/src/game/block_entity_anims.rs
index 619fcd009..4fbec9c7a 100644
--- a/crates/horizon-client/src/game/block_entity_anims.rs
+++ b/crates/horizon-client/src/game/block_entity_anims.rs
@@ -11,7 +11,10 @@ use horizon_client::{
     particles::{ParticleOptions, ParticleType},
     save::number,
 };
-use horizon_core::geometry::{Aabb, Vec3};
+use horizon_core::{
+    geometry::{Aabb, Vec3},
+    position::BlockPos,
+};
 use horizon_world::nbt::Tag;
 
 /// The handle of the local player among a bell's gathered entities.
@@ -84,6 +87,16 @@ impl Game<'_> {
                     self.lid_openers_changed(other, open);
                 }
             }
+            _ if self
+                .res
+                .facts()
+                .get(self.world.block(pos[0], pos[1], pos[2]))
+                .name
+                .as_ref()
+                == "minecraft:barrel" =>
+            {
+                self.barrel_openers_changed(key, open);
+            }
             Some(Ticker::Shulker { .. }) => {
                 let shulker = self.be_anims.shulkers.entry(pos).or_default();
                 let (count, _) = if open {
@@ -102,15 +115,48 @@ impl Game<'_> {
     /// `ChestBlockEntity.signalOpenCount`: block event 1 with the count, here
     /// and for the guests.
     fn lid_openers_changed(&mut self, key: (i32, i32, i32), open: bool) {
-        let count = self.lid_openers.entry(key).or_default();
-        *count = (*count + if open { 1 } else { -1 }).max(0);
-        let count = *count;
-        if count == 0 {
-            self.lid_openers.remove(&key);
-        }
+        let (before, count) = self.count_opener(key, open);
         let pos = [key.0, key.1, key.2];
         self.block_entity_event(pos, 1, count);
         self.lan_block_event(pos, 1, count);
+        // TrappedChestBlockEntity.signalOpenCount: its signal is the count
+        // (`TrappedChestBlock.getSignal`), so the blocks around it and
+        // below it hear of a change.
+        let state = self.world.block(pos[0], pos[1], pos[2]);
+        if before != count && self.res.facts().get(state).name.as_ref() == "minecraft:trapped_chest"
+        {
+            let p = BlockPos::new(pos[0], pos[1], pos[2]);
+            self.with_level(|b, level, ticks| {
+                let block = b.block(state);
+                b.update_neighbors_at(level, ticks, p, block);
+                b.update_neighbors_at(level, ticks, p.offset(0, -1, 0), block);
+            });
+        }
+    }
+    /// `BarrelBlockEntity.openersCounter`: the first opener opens the barrel
+    /// (`open=true`), the last one to leave closes it (`updateBlockState`).
+    fn barrel_openers_changed(&mut self, key: (i32, i32, i32), open: bool) {
+        let (before, count) = self.count_opener(key, open);
+        if (before == 0) != (count == 0) {
+            self.set_bool_prop(
+                key,
+                "open",
+                count > 0,
+                horizon_world::level::flags::UPDATE_ALL,
+            );
+        }
+    }
+    /// One opener more (`open`) or less at `key`: the count before and after
+    /// (`ContainerOpenersCounter.incrementOpeners` / `decrementOpeners`).
+    fn count_opener(&mut self, key: (i32, i32, i32), open: bool) -> (i32, i32) {
+        let count = self.lid_openers.entry(key).or_default();
+        let before = *count;
+        *count = (before + if open { 1 } else { -1 }).max(0);
+        let after = *count;
+        if after == 0 {
+            self.lid_openers.remove(&key);
+        }
+        (before, after)
     }
     /// `BellBlockEntity.updateEntities`: the living entities whose bounding
     /// box meets the bell's block box inflated by 48.
diff --git a/crates/horizon-client/src/game/machines/crafter.rs b/crates/horizon-client/src/game/machines/crafter.rs
index 0fe66f7c8..dd6d5cedc 100644
--- a/crates/horizon-client/src/game/machines/crafter.rs
+++ b/crates/horizon-client/src/game/machines/crafter.rs
@@ -33,7 +33,7 @@ fn recipe_matches(condition: &Value, id: &str) -> bool {
 
 impl Game<'_> {
     /// `Level.setBlock` of one boolean property of the block at `pos`.
-    fn set_bool_prop(&mut self, pos: Pos, key: &str, value: bool, flags: i32) {
+    pub(crate) fn set_bool_prop(&mut self, pos: Pos, key: &str, value: bool, flags: i32) {
         let registry = self.pack.assets.registry;
         let old = self.world.block(pos.0, pos.1, pos.2);
         let Some(mut state) = registry.state(old).cloned() else {

From 22c3f2bd0f63d88f27e4badd82f8e613c36e9804 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:13:51 +0100
Subject: [PATCH 082/270] Roadmap: roadmap/roadmap.toml, ROADMAP.md generated
 from it, and its checks

One source of truth for what is being done, what comes next and where to help: roadmap/roadmap.toml,
each item said twice (plain words for players, the technical picture for contributors), Now / Next /
Later / Help wanted / Shipped, no dates. tools/roadmap.py builds ROADMAP.md from it, checks its rules
offline (CI, through tests/test_roadmap.py) and against GitHub (links resolve, no stale Now item),
ships items whose pull requests all went out in a release (sync), and keeps a roadmap:<id> label per
item (labels). README links it; roadmap/README.md is the maintenance guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md             |   5 +
 ROADMAP.md            | 341 ++++++++++++++++++++++++++
 roadmap/README.md     |  56 +++++
 roadmap/roadmap.toml  | 477 ++++++++++++++++++++++++++++++++++++
 tests/test_roadmap.py | 207 ++++++++++++++++
 tools/pr_ready.py     |   6 +-
 tools/roadmap.py      | 551 ++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 1641 insertions(+), 2 deletions(-)
 create mode 100644 ROADMAP.md
 create mode 100644 roadmap/README.md
 create mode 100644 roadmap/roadmap.toml
 create mode 100644 tests/test_roadmap.py
 create mode 100644 tools/roadmap.py

diff --git a/README.md b/README.md
index 6dd192d5d..ceee29249 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@
   <a href="#download"><b>Download</b></a> ·
   <a href="https://playhorizon.dev/docs/"><b>Documentation</b></a> ·
   <a href="https://github.com/ludovic111/horizon/releases"><b>Release notes</b></a> ·
+  <a href="ROADMAP.md"><b>Roadmap</b></a> ·
   <a href="#project-status"><b>Project status</b></a> ·
   <a href="#contributing"><b>Contributing</b></a>
 </p>
@@ -109,6 +110,10 @@ Everything prepared lands in the gitignored `.local/`. It is derived from the ga
 
 The client starts on the title screen. Command-line options (`--world`, `--seed`, `--creative`, `--render-distance`, `--dedicated`), controls, scripting through `horizon-ctl` and the architecture are described in [the native client guide](docs/native-client.md). The rest of the developer documentation is indexed in [docs/README.md](docs/README.md), including [the parity workflow](docs/parity-workflow.md).
 
+## Roadmap
+
+What is being done now, what comes next and where you can help, in plain words and in technical detail: [ROADMAP.md](ROADMAP.md). [playhorizon.dev/hub](https://playhorizon.dev/hub) shows it with the work board, the journal of what shipped and how to help.
+
 ## Contributing
 
 Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) for how we work (vanilla first, small pull requests, labels), or [the contributing guide](https://playhorizon.dev/docs/contributing) on the site. Questions and ideas: [Discord](https://discord.gg/HcTeMZxe5E). Before opening a pull request, run the self-check and paste the block it prints:
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 000000000..b433fad3a
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,341 @@
+# Horizon roadmap
+
+<!-- Generated by tools/roadmap.py from roadmap/roadmap.toml: edit that file, then run `python3 tools/roadmap.py build`. -->
+
+What is being done on Horizon, what comes next and where you can help. There are no dates: things are Now, Next or Later. Each item is said in plain words, with the technical picture folded under it. The same roadmap, with a Simple / Technical switch, the board, the journal and how to help, is on [playhorizon.dev/hub](https://playhorizon.dev/hub). Pull requests carry the `roadmap:<id>` label of their item.
+
+## At a glance
+
+Horizon is Minecraft: Java Edition 26.3 rewritten from scratch in Rust, so it runs faster on the same computer. Single player, LAN, servers, resource packs and Horizon's own mods work today, on your own copy of the game.
+
+**Being done now**
+
+- **Steady frames at long render distances**: Making Horizon faster than vanilla on every computer, with smooth camera movement even at 32 chunks, by spreading the work better over the processor's cores.
+- **Modpacks' world generation, natively**: Making the world-generation mods of popular modpacks (new structures, YUNG's dungeons and mineshafts, packs built on Lithostitched) generate their worlds in Horizon, natively and fast.
+- **Playing on servers: everything shows as it should**: When you play on a server, other players, mobs, items and menus look and behave as in vanilla: skins, poses, item names, inventories and server networks.
+- **Single player as a server: the last differences**: Single player now runs a small server in the background, as vanilla does. We are fixing what still behaves differently there; every fix also works for LAN and server players.
+- **Horizon's mod registry**: One place for mods, modpacks and resource packs made for Horizon: browse them on the website and install them from the launcher in one click.
+
+**Next**: Microsoft sign-in (coming soon); CurseForge in the mod browser (coming soon); Fresh benchmarks against vanilla; Pistons push players and mobs; Horizon on Intel Macs.
+
+**How to help**: Play it and tell us what differs from vanilla (Discord or GitHub), run the benchmark on your computer, vote for what you want next, or pick one of the Help wanted items.
+
+**Developers**: Read CONTRIBUTING.md, pick a Help wanted item or a To do card, check vanilla's code for the behaviour, and paste the block `python3 tools/pr_ready.py` prints in your pull request.
+
+## Now
+
+### Performance
+
+#### Steady frames at long render distances
+
+Making Horizon faster than vanilla on every computer, with smooth camera movement even at 32 chunks, by spreading the work better over the processor's cores.
+
+<details><summary>Technical</summary>
+
+Frame pacing at render distance 32 ([#678](https://github.com/ludovic111/horizon/issues/678)): long frames come from work competing with the render thread. In review: world generation workers build free structure starts instead of queueing them ([#1760](https://github.com/ludovic111/horizon/issues/1760)), the worker pool leaves one core as vanilla does ([#1778](https://github.com/ludovic111/horizon/issues/1778)), and the terrain vertex arena is read as storage where flat draws run ([#1742](https://github.com/ludovic111/horizon/issues/1742)). Still open: far terrain at 48 to 64 chunks ([#718](https://github.com/ludovic111/horizon/issues/718)) and CPU-bound fields of block entities ([#717](https://github.com/ludovic111/horizon/issues/717)). Every change shows before and after numbers from `tools/perf_bench.py` against vanilla 26.3 ([docs/benchmark.md](docs/benchmark.md)).
+
+</details>
+
+#### Faster block lookups
+
+Speeding up the code that reads and writes the blocks of the world, which almost everything in the game goes through: generation, lighting, meshing and ticking.
+
+<details><summary>Technical</summary>
+
+`PalettedContainer` and `PackedStorage` find an entry's word by multiply and shift instead of an integer division ([#1790](https://github.com/ludovic111/horizon/issues/1790), [#1794](https://github.com/ludovic111/horizon/issues/1794)); meshing looks up baked models by index, not by name ([#1747](https://github.com/ludovic111/horizon/issues/1747)). Each change keeps the paletted storage harnesses identical and shows its microbenchmark ([docs/performance/paletted-container-access-results.md](docs/performance/paletted-container-access-results.md)).
+
+</details>
+
+### Modpacks
+
+#### Modpacks' world generation, natively
+
+Making the world-generation mods of popular modpacks (new structures, YUNG's dungeons and mineshafts, packs built on Lithostitched) generate their worlds in Horizon, natively and fast.
+
+<details><summary>Technical</summary>
+
+`horizon-port-pack` carries a pack's data-driven content over; structure mods that need code get a native port: YUNG's worldgen as written ([#1746](https://github.com/ludovic111/horizon/issues/1746)), Lithostitched's limited and guaranteed elements with pool and processor modifiers ([#1777](https://github.com/ludovic111/horizon/issues/1777)), its processors as the game's own types ([#1765](https://github.com/ludovic111/horizon/issues/1765)). Proved by the structure blocks and layout harnesses ([#1753](https://github.com/ludovic111/horizon/issues/1753), [#1757](https://github.com/ludovic111/horizon/issues/1757)). Mods whose Java code does more than world generation don't run ([docs/modpacks.md](docs/modpacks.md)).
+
+</details>
+
+### Servers and multiplayer
+
+#### Playing on servers: everything shows as it should
+
+When you play on a server, other players, mobs, items and menus look and behave as in vanilla: skins, poses, item names, inventories and server networks.
+
+<details><summary>Technical</summary>
+
+Client-of-a-server fixes in `game/remote*.rs` and `horizon-protocol`: mobs' aggressive and item-use flags ([#1802](https://github.com/ludovic111/horizon/issues/1802), [#1798](https://github.com/ludovic111/horizon/issues/1798)), ghost items after a remote menu ([#1795](https://github.com/ludovic111/horizon/issues/1795)), skins ([#1652](https://github.com/ludovic111/horizon/issues/1652)), cookies and transfer packets for proxy networks ([#1650](https://github.com/ludovic111/horizon/issues/1650)), firework boosts ([#1671](https://github.com/ludovic111/horizon/issues/1671)), living-entity attributes and simulation distance ([#1731](https://github.com/ludovic111/horizon/issues/1731)), styled item names ([#1702](https://github.com/ludovic111/horizon/issues/1702)), primed TNT between updates ([#1710](https://github.com/ludovic111/horizon/issues/1710)).
+
+</details>
+
+#### Server dialogs and login screens
+
+Servers that show dialogs, such as the register and login screens of AuthMe, will work in Horizon.
+
+<details><summary>Technical</summary>
+
+26.3's dialog packets and model ([#1720](https://github.com/ludovic111/horizon/issues/1720)), the dialog screen with its buttons and actions ([#1734](https://github.com/ludovic111/horizon/issues/1734)), then text and boolean inputs ([#1735](https://github.com/ludovic111/horizon/issues/1735)).
+
+</details>
+
+### Mods and API
+
+#### Horizon's mod registry
+
+One place for mods, modpacks and resource packs made for Horizon: browse them on the website and install them from the launcher in one click.
+
+<details><summary>Technical</summary>
+
+Merged: the registry index (schema 1, `.hpack`, checks before install, [#1634](https://github.com/ludovic111/horizon/issues/1634)), `cargo horizon-mod check` ([#1642](https://github.com/ludovic111/horizon/issues/1642)) and the submission service (`crates/horizon-mod-registry`, [#1659](https://github.com/ludovic111/horizon/issues/1659)). In review: the website's /mods ([#1596](https://github.com/ludovic111/horizon/issues/1596)) and /mods/submit ([#1635](https://github.com/ludovic111/horizon/issues/1635)), and in the launcher the registry as a source ([#1636](https://github.com/ludovic111/horizon/issues/1636)), install, enable and takedowns ([#1637](https://github.com/ludovic111/horizon/issues/1637)), the Mods page ([#1638](https://github.com/ludovic111/horizon/issues/1638)) and modpacks as their own profiles ([#1640](https://github.com/ludovic111/horizon/issues/1640)).
+
+More: [docs/mods.md](docs/mods.md)
+
+</details>
+
+### Gameplay parity
+
+#### Single player as a server: the last differences
+
+Single player now runs a small server in the background, as vanilla does. We are fixing what still behaves differently there; every fix also works for LAN and server players.
+
+<details><summary>Technical</summary>
+
+Since [#1514](https://github.com/ludovic111/horizon/issues/1514) single player runs on the server thread (`game/integrated.rs`) and the window joins it as a client; `--in-frame` keeps the old path. The open `[server-thread]` issues list the gaps. In review: a tool that changes a block ends the click ([#1797](https://github.com/ludovic111/horizon/issues/1797)), potions keep their potion over the connection ([#1796](https://github.com/ludovic111/horizon/issues/1796)), mobs' aggression and arm swings ([#1802](https://github.com/ludovic111/horizon/issues/1802)). [docs/server-levels.md](docs/server-levels.md).
+
+</details>
+
+#### Play in your language
+
+Item names, container titles and server messages follow the language you pick, as in vanilla. Today parts of the game stay in English.
+
+<details><summary>Technical</summary>
+
+Translatable components resolved through the selected language for items, containers and server text ([#1806](https://github.com/ludovic111/horizon/issues/1806)), on top of the bundled languages the prepared resources carry ([#1594](https://github.com/ludovic111/horizon/issues/1594)). Left: the client's own screens ([#1672](https://github.com/ludovic111/horizon/issues/1672)) and the main menu with zh_cn ([#1774](https://github.com/ludovic111/horizon/issues/1774)).
+
+</details>
+
+### Rendering
+
+#### Shader packs, written again from scratch
+
+Shader packs were removed and are being rebuilt from scratch. They come back, off by default, once the best-known packs draw properly.
+
+<details><summary>Technical</summary>
+
+A clean-room rewrite in `horizon-shaderpack`, from the packs' public format documentation only: reading packs, the preprocessor and `.properties` files are merged ([#1584](https://github.com/ludovic111/horizon/issues/1584), [#1585](https://github.com/ludovic111/horizon/issues/1585), [#1586](https://github.com/ludovic111/horizon/issues/1586)); translating programs to WGSL through naga, buffers, uniforms and the terrain, entity, sky, weather and hand stages are in review ([#1698](https://github.com/ludovic111/horizon/issues/1698) to [#1801](https://github.com/ludovic111/horizon/issues/1801)).
+
+More: [#1561](https://github.com/ludovic111/horizon/issues/1561) · [#1771](https://github.com/ludovic111/horizon/issues/1771) · [#1786](https://github.com/ludovic111/horizon/issues/1786)
+
+</details>
+
+### Horizon extras
+
+#### Discord Rich Presence
+
+Your Discord profile can show that you are playing Horizon, with a switch to turn it off.
+
+<details><summary>Technical</summary>
+
+A Discord IPC client on its own thread ([#1787](https://github.com/ludovic111/horizon/issues/1787)) and the presence with its setting ([#1788](https://github.com/ludovic111/horizon/issues/1788)). Merged: it ships with the next release.
+
+</details>
+
+### Code and tools
+
+#### A leaner codebase that builds faster
+
+Cleaning up Horizon's code: removing what nothing uses and making it quicker to build, so fixes and new features land faster.
+
+<details><summary>Technical</summary>
+
+A review of the whole tree: dead code and stubs removed ([#1432](https://github.com/ludovic111/horizon/issues/1432), [#1658](https://github.com/ludovic111/horizon/issues/1658)), one probe binary per crate ([#1453](https://github.com/ludovic111/horizon/issues/1453), [#1454](https://github.com/ludovic111/horizon/issues/1454)), shared harness helpers ([#1448](https://github.com/ludovic111/horizon/issues/1448)), clippy clean on the whole tree ([#1707](https://github.com/ludovic111/horizon/issues/1707)). [docs/architecture.md](docs/architecture.md) maps each feature to its files and harnesses.
+
+</details>
+
+## Next
+
+### Performance
+
+#### Fresh benchmarks against vanilla
+
+New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, on the website's Benchmarks page.
+
+<details><summary>Technical</summary>
+
+Redo the comparison after the current performance work ([#1073](https://github.com/ludovic111/horizon/issues/1073)); reliability, coverage and presentation ([#1346](https://github.com/ludovic111/horizon/issues/1346)); a scene must count as loaded only once its first chunk arrives ([#1749](https://github.com/ludovic111/horizon/issues/1749)). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` ([docs/benchmark.md](docs/benchmark.md)).
+
+</details>
+
+### Modpacks
+
+#### CurseForge in the mod browser (coming soon)
+
+Coming soon: search and download CurseForge mods and modpacks from the launcher, as you can with Modrinth today.
+
+<details><summary>Technical</summary>
+
+The mod browser lists CurseForge as coming soon ([docs/mod-browser.md](docs/mod-browser.md)): it needs CurseForge API access. Meanwhile packs import from a CurseForge zip or instance folder, and jars only CurseForge hosts come from the player's own instance ([docs/modpacks.md](docs/modpacks.md)).
+
+</details>
+
+### Gameplay parity
+
+#### Pistons push players and mobs
+
+Pistons and slime blocks will push players, mobs and items as in vanilla. Today moving blocks pass through them.
+
+<details><summary>Technical</summary>
+
+Port `PistonMovingBlockEntity.moveCollidedEntities` and `moveStuckEntities` (honey), the slime bounce and `Entity.limitPistonMovement` for `MoverType.PISTON`, in single player and for a server's players. Issues [#1496](https://github.com/ludovic111/horizon/issues/1496), [#1609](https://github.com/ludovic111/horizon/issues/1609), [#1608](https://github.com/ludovic111/horizon/issues/1608), [#1704](https://github.com/ludovic111/horizon/issues/1704), [#1758](https://github.com/ludovic111/horizon/issues/1758).
+
+</details>
+
+### Launcher
+
+#### Microsoft sign-in (coming soon)
+
+Coming soon: sign in with your Microsoft account to play on online-mode servers. The code is ready; it waits for Microsoft's approval.
+
+<details><summary>Technical</summary>
+
+Device-code sign-in in the launcher and online-mode login in the client ([docs/microsoft-account.md](docs/microsoft-account.md)). It is turned on by setting the app's client id once Minecraft API access is approved; until then the launcher shows "Coming soon".
+
+More: [#1270](https://github.com/ludovic111/horizon/issues/1270)
+
+</details>
+
+#### Horizon on Intel Macs
+
+Builds of the game and the launcher for Macs with an Intel processor.
+
+<details><summary>Technical</summary>
+
+x86_64 game and launcher builds, picked per processor ([#1171](https://github.com/ludovic111/horizon/issues/1171)). Before it ships it needs a run on a real Intel Mac: Rosetta on Apple Silicon only proves the CPU code. Requests: [#1161](https://github.com/ludovic111/horizon/issues/1161), [#1792](https://github.com/ludovic111/horizon/issues/1792).
+
+</details>
+
+## Later
+
+### Gameplay parity
+
+#### Following new Minecraft versions
+
+When Mojang releases a new version of the game, Horizon follows it, and every system is checked against the new version again.
+
+<details><summary>Technical</summary>
+
+The port pipeline detects a release, diffs its classes against 26.3 and writes a port report ([docs/version-ports.md](docs/version-ports.md)); the harnesses then run against the new version.
+
+</details>
+
+### Horizon extras
+
+#### An optional AI teammate
+
+An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the No AI switch hides it completely.
+
+<details><summary>Technical</summary>
+
+Draft pull requests: the companion ([#1068](https://github.com/ludovic111/horizon/issues/1068)), its safety modes and their evaluation ([#1069](https://github.com/ludovic111/horizon/issues/1069)), and a route that finishes the game ([#1070](https://github.com/ludovic111/horizon/issues/1070)). Local models first; it ships only once the safety evaluation passes.
+
+</details>
+
+## Help wanted
+
+### Performance
+
+#### Benchmark your computer
+
+Run Horizon's built-in benchmark and share the report: every new computer makes the performance work more accurate. No coding needed.
+
+<details><summary>Technical</summary>
+
+`horizon-launcher play --arg=--benchmark --arg=standard` writes a JSON report; `horizon-launcher data benchmark <report>` shows what would be sent and uploads it ([website/docs/performance.md](website/docs/performance.md)). Results from three installs with the same hardware appear on the Benchmarks page. Example: [#1711](https://github.com/ludovic111/horizon/issues/1711).
+
+</details>
+
+### Gameplay parity
+
+#### End city banners keep their pattern
+
+Banners in End cities show as plain magenta instead of with their pattern.
+
+<details><summary>Technical</summary>
+
+Compare the banner block entities the End city templates place with vanilla's (`EndCityPieces`, the templates' block entity NBT, `BannerBlockEntity`'s patterns), in `crates/horizon-world/src/worldgen/structure/`. Issue [#1438](https://github.com/ludovic111/horizon/issues/1438); possibly related: [#526](https://github.com/ludovic111/horizon/issues/526).
+
+</details>
+
+#### Enchanted loot in End cities
+
+Armour and tools in End city chests should come enchanted, as in vanilla.
+
+<details><summary>Technical</summary>
+
+`loot.rs` implements `enchant_with_levels`: find why the End city chest table's rolls come out bare, and compare them with vanilla's for a few seeds. Issues [#1437](https://github.com/ludovic111/horizon/issues/1437), [#1660](https://github.com/ludovic111/horizon/issues/1660).
+
+</details>
+
+#### Cooldowns drawn on items
+
+After you throw an ender pearl, its slot should show the cooldown sweeping away, as in vanilla.
+
+<details><summary>Technical</summary>
+
+Vanilla draws `ItemCooldowns`' percent as a white overlay over the slot (`GuiGraphicsExtractor.itemDecorations` and `itemCooldown`) in the hotbar and in inventories. Issue [#1763](https://github.com/ludovic111/horizon/issues/1763).
+
+</details>
+
+#### Chat settings and team prefixes
+
+The Hidden and Commands Only chat settings should hide chat, and team prefixes should appear before names in chat.
+
+<details><summary>Technical</summary>
+
+Vanilla checks `ChatVisiblity` before it delivers chat and system messages ([#1376](https://github.com/ludovic111/horizon/issues/1376)), and chat uses the team-formatted display name ([#1378](https://github.com/ludovic111/horizon/issues/1378)). Both issues have exact steps to reproduce.
+
+</details>
+
+#### A pointing hand over buttons
+
+The mouse pointer should turn into a pointing hand over menu buttons, as in vanilla 26.3.
+
+<details><summary>Technical</summary>
+
+26.3's `AbstractWidget` asks for a cursor from `CursorTypes` when it is hovered; winit's `CursorIcon::Pointer` gives the same shape. Issue [#1347](https://github.com/ludovic111/horizon/issues/1347).
+
+</details>
+
+#### Ctrl+Backspace and scroll bars in menus
+
+Ctrl+Backspace should delete a whole word in the creative search, and every list's scroll bar should be draggable.
+
+<details><summary>Technical</summary>
+
+`EditBox` deletes by word with Ctrl ([#1764](https://github.com/ludovic111/horizon/issues/1764)); the Game Rules and Statistics lists' scroll bars can't be dragged ([#1782](https://github.com/ludovic111/horizon/issues/1782), after [#978](https://github.com/ludovic111/horizon/issues/978)).
+
+</details>
+
+#### Chickens flap while they fall
+
+Chickens should flap their wings while they fall, not stand still in the air.
+
+<details><summary>Technical</summary>
+
+Vanilla's `Chicken.aiStep` updates `flap` and `flapSpeed` when the chicken isn't on the ground, and the model's wings follow them. Issue [#1706](https://github.com/ludovic111/horizon/issues/1706).
+
+</details>
+
+## Recently shipped
+
+- **Server resource packs** (v0.2.48): Servers can send you their resource pack: Horizon asks, downloads it and applies it, like vanilla. [#1562](https://github.com/ludovic111/horizon/issues/1562) · [#1569](https://github.com/ludovic111/horizon/issues/1569) · [#1570](https://github.com/ludovic111/horizon/issues/1570)
+- **Single player on its own server thread** (v0.2.39): Single player runs on a server thread, as vanilla does, so the world keeps ticking smoothly while the window draws. [#1514](https://github.com/ludovic111/horizon/issues/1514) · [docs/server-levels.md](docs/server-levels.md)
+- **GPU occlusion culling on Macs** (v0.2.17): On Macs the GPU now skips terrain hidden behind hills and caves: 8 to 48% more frames per second at 32 chunks on an M4 Pro. [#1434](https://github.com/ludovic111/horizon/issues/1434)
+- **Animated textures on the GPU** (v0.2.5): Water, lava and other animated blocks are now animated by the graphics card: 1.7 to 2.4 times better 1% lows on Intel graphics. [#1239](https://github.com/ludovic111/horizon/issues/1239)
+- **Far Detail for integrated graphics** (v0.2.5): An optional Reduced setting for far terrain, suggested on integrated graphics, that saves 2 to 4 ms of GPU time per frame. [#1199](https://github.com/ludovic111/horizon/issues/1199) · [#1029](https://github.com/ludovic111/horizon/issues/1029)
+- **The launcher's mod browser** (launcher@0.2.0): Search Modrinth for mods, modpacks and resource packs from the launcher; it says before installing what works in Horizon. [#1154](https://github.com/ludovic111/horizon/issues/1154) · [#1242](https://github.com/ludovic111/horizon/issues/1242) · [#1243](https://github.com/ludovic111/horizon/issues/1243) · [#1246](https://github.com/ludovic111/horizon/issues/1246) · [docs/mod-browser.md](docs/mod-browser.md)
+- **A blocky, Minecraft-like launcher** (launcher@0.2.0): The launcher got a new blocky look in Horizon's purple, in dark and light. [#1269](https://github.com/ludovic111/horizon/issues/1269) · [docs/design-system.md](docs/design-system.md)
+- **Dynamic lights** (v2026.10.22): An optional extra: torches you hold, drop or set on fire light up what is around them. [#1162](https://github.com/ludovic111/horizon/issues/1162)
+- **Host a server from the launcher** (launcher-v0.15.0): The launcher's Servers page creates, starts, backs up and updates a Horizon server with buttons, and invites friends. [#1026](https://github.com/ludovic111/horizon/issues/1026) · [docs/hosting.md](docs/hosting.md)
diff --git a/roadmap/README.md b/roadmap/README.md
new file mode 100644
index 000000000..df44575a5
--- /dev/null
+++ b/roadmap/README.md
@@ -0,0 +1,56 @@
+# The roadmap
+
+`roadmap.toml` is the one source of the roadmap. `tools/roadmap.py build` turns it into
+[ROADMAP.md](../ROADMAP.md); the website's hub (playhorizon.dev/hub) and Kira read the same items. The work
+board stays the task-level view (every issue and pull request); the roadmap is the overview, and each pull
+request carries the `roadmap:<id>` label of the item it moves.
+
+## An item
+
+```toml
+[[item]]
+id = "server-dialogs"            # lowercase words joined by dashes; never renamed (votes and links use it)
+title = "Server dialogs and login screens"
+status = "now"                   # now | next | later | help-wanted | shipped
+area = "servers"                 # one of the [[area]] ids, listed in the order of priority
+focus = true                     # optional: one of the 3 to 5 Now items in the overview
+ongoing = true                   # optional: a workstream that goes on after its pull requests merge
+plain = """Servers that show dialogs ... will work in Horizon."""   # players' words, at most 240 characters
+dev = """26.3's dialog packets and model (#1720), ..."""             # crates, approach, what is left
+links = ["#1720", "#1734", "docs/hosting.md"]                       # #N, a repository path, or https://
+shipped_in = "v0.2.58"           # shipped items only: a game tag, launcher@x.y.z, or "website"
+post = "..."                     # optional: the announcement when it ships, if `plain` doesn't read as one
+```
+
+- **No dates, ever**: Now, Next, Later. The check rejects month names, years, quarters and "next week".
+  "Coming soon" is the only phrase for something waiting on someone else (Microsoft sign-in, CurseForge).
+- **Only what is decided.** Ideas stay in issues and in the suggestion queue until they are.
+- **Only what is true in a release** for shipped items: a merged pull request isn't shipped until a release has it.
+- `plain` is for players: what they will be able to do, not how. `dev` is for contributors: the code, the
+  vanilla classes, the pull requests, what is left. Both stay public: no machines, accounts or private notes.
+- Help wanted items are good first contributions: a clear vanilla behaviour, an issue with steps, a place to
+  start in `dev`.
+
+## Keeping it current
+
+Whoever moves the work (the orchestrator on each heartbeat, or anyone in their pull request):
+
+1. `python3 tools/roadmap.py sync`: every item whose linked pull requests all went out in a release, whose
+   linked issues are all closed and that isn't `ongoing` becomes `shipped`, with that release in
+   `shipped_in`, on top of the shipped items. It rewrites `roadmap.toml` and ROADMAP.md; open a pull request
+   with the change (`skip-release`).
+2. `python3 tools/roadmap.py check`: the file's rules, then GitHub's state of every link. It fails when a
+   link is not an issue or pull request, when a Now item has no open pull request and none merged in the last
+   14 days (link the new work, or move it to Next or Later), and when every link of a Help wanted item is
+   closed. It also says which items `sync` will ship once a release has them.
+3. When work starts, opens a pull request or is decided: add or move the item, add its links, then
+   `python3 tools/roadmap.py build`. Keep the overview's focus to the 3 to 5 biggest Now items.
+4. `python3 tools/roadmap.py labels` (after the change merges): creates a `roadmap:<id>` label for each new
+   item, updates their colour (by status) and description, and adds the label to the open pull requests an item
+   links. Label a new pull request for an item by hand or by linking it and running `labels` again. Labels of
+   removed items are listed, never deleted.
+5. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
+   item in a normal pull request; none is published automatically.
+
+CI runs `tests/test_roadmap.py` (in the Python tests), which fails when ROADMAP.md is not what `build` writes
+or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs the same rules without GitHub.
diff --git a/roadmap/roadmap.toml b/roadmap/roadmap.toml
new file mode 100644
index 000000000..bb664d3d5
--- /dev/null
+++ b/roadmap/roadmap.toml
@@ -0,0 +1,477 @@
+# Horizon's roadmap: the one source of truth for ROADMAP.md, playhorizon.dev/roadmap and Kira's answers.
+# Edit this file, then run `python3 tools/roadmap.py build`. How to keep it current: roadmap/README.md.
+#
+# No dates, ever: an item is Now, Next or Later. Each item says the same thing twice: `plain` for players
+# (one or two sentences, at most 240 characters, so it fits a post when it ships) and `dev` for contributors
+# (crates, approach, what is left). Links are "#123" (an issue or a pull request), a path in the repository,
+# or an https URL. Only what is decided goes here; ideas wait in GitHub issues and the suggestion queue.
+# `focus = true` puts a Now item in the overview (3 to 5 of them). `ongoing = true` marks a workstream that goes on
+# after its linked pull requests merge: `sync` never ships it, so link its new pull requests as they open.
+
+[overview]
+today_plain = """Horizon is Minecraft: Java Edition 26.3 rewritten from scratch in Rust, so it runs faster on the \
+same computer. Single player, LAN, servers, resource packs and Horizon's own mods work today, on your own copy of \
+the game."""
+today_dev = """A native Rust and wgpu reimplementation of Java 26.3: the same saves, rules and terrain, checked \
+against the real game by more than 300 differential harnesses (a Java oracle and a Rust probe on the same inputs). \
+Single player runs on its own server thread, like vanilla's integrated server."""
+help_plain = """Play it and tell us what differs from vanilla (Discord or GitHub), run the benchmark on your \
+computer, vote for what you want next, or pick one of the Help wanted items."""
+help_dev = """Read CONTRIBUTING.md, pick a Help wanted item or a To do card, check vanilla's code for the \
+behaviour, and paste the block `python3 tools/pr_ready.py` prints in your pull request."""
+
+# Areas, in the project's order of priority: performance first, then modpacks and servers.
+[[area]]
+id = "performance"
+name = "Performance"
+
+[[area]]
+id = "modpacks"
+name = "Modpacks"
+
+[[area]]
+id = "servers"
+name = "Servers and multiplayer"
+
+[[area]]
+id = "mods"
+name = "Mods and API"
+
+[[area]]
+id = "gameplay"
+name = "Gameplay parity"
+
+[[area]]
+id = "rendering"
+name = "Rendering"
+
+[[area]]
+id = "launcher"
+name = "Launcher"
+
+[[area]]
+id = "extras"
+name = "Horizon extras"
+
+[[area]]
+id = "project"
+name = "Code and tools"
+
+# ---------------------------------------------------------------------------------------------------- Now
+
+[[item]]
+id = "smooth-frames"
+title = "Steady frames at long render distances"
+status = "now"
+area = "performance"
+focus = true
+plain = """Making Horizon faster than vanilla on every computer, with smooth camera movement even at 32 chunks, \
+by spreading the work better over the processor's cores."""
+dev = """Frame pacing at render distance 32 (#678): long frames come from work competing with the render thread. \
+In review: world generation workers build free structure starts instead of queueing them (#1760), the worker pool \
+leaves one core as vanilla does (#1778), and the terrain vertex arena is read as storage where flat draws run \
+(#1742). Still open: far terrain at 48 to 64 chunks (#718) and CPU-bound fields of block entities (#717). Every \
+change shows before and after numbers from `tools/perf_bench.py` against vanilla 26.3 (docs/benchmark.md)."""
+links = ["#678", "#1760", "#1778", "#1742", "#718", "#717", "docs/benchmark.md"]
+
+[[item]]
+id = "block-storage"
+title = "Faster block lookups"
+status = "now"
+area = "performance"
+plain = """Speeding up the code that reads and writes the blocks of the world, which almost everything in the game \
+goes through: generation, lighting, meshing and ticking."""
+dev = """`PalettedContainer` and `PackedStorage` find an entry's word by multiply and shift instead of an integer \
+division (#1790, #1794); meshing looks up baked models by index, not by name (#1747). Each change keeps the paletted \
+storage harnesses identical and shows its microbenchmark (docs/performance/paletted-container-access-results.md)."""
+links = ["#1790", "#1794", "#1747", "docs/performance/paletted-container-access-results.md"]
+
+[[item]]
+id = "modpack-worldgen"
+title = "Modpacks' world generation, natively"
+status = "now"
+area = "modpacks"
+focus = true
+plain = """Making the world-generation mods of popular modpacks (new structures, YUNG's dungeons and mineshafts, \
+packs built on Lithostitched) generate their worlds in Horizon, natively and fast."""
+dev = """`horizon-port-pack` carries a pack's data-driven content over; structure mods that need code get a native \
+port: YUNG's worldgen as written (#1746), Lithostitched's limited and guaranteed elements with pool and processor \
+modifiers (#1777), its processors as the game's own types (#1765). Proved by the structure blocks and layout \
+harnesses (#1753, #1757). Mods whose Java code does more than world generation don't run (docs/modpacks.md)."""
+links = ["#1746", "#1777", "#1765", "#1753", "#1757", "docs/modpacks.md"]
+
+[[item]]
+id = "server-clients"
+title = "Playing on servers: everything shows as it should"
+status = "now"
+ongoing = true
+area = "servers"
+focus = true
+plain = """When you play on a server, other players, mobs, items and menus look and behave as in vanilla: skins, \
+poses, item names, inventories and server networks."""
+dev = """Client-of-a-server fixes in `game/remote*.rs` and `horizon-protocol`: mobs' aggressive and item-use flags \
+(#1802, #1798), ghost items after a remote menu (#1795), skins (#1652), cookies and transfer packets for proxy \
+networks (#1650), firework boosts (#1671), living-entity attributes and simulation distance (#1731), styled item \
+names (#1702), primed TNT between updates (#1710)."""
+links = ["#1802", "#1798", "#1795", "#1652", "#1650", "#1671", "#1731", "#1702", "#1710"]
+
+[[item]]
+id = "server-thread"
+title = "Single player as a server: the last differences"
+status = "now"
+ongoing = true
+area = "gameplay"
+focus = true
+plain = """Single player now runs a small server in the background, as vanilla does. We are fixing what still \
+behaves differently there; every fix also works for LAN and server players."""
+dev = """Since #1514 single player runs on the server thread (`game/integrated.rs`) and the window joins it as a \
+client; `--in-frame` keeps the old path. The open `[server-thread]` issues list the gaps. In review: a tool that \
+changes a block ends the click (#1797), potions keep their potion over the connection (#1796), mobs' aggression \
+and arm swings (#1802). docs/server-levels.md."""
+links = ["#1514", "#1797", "#1796", "#1802", "docs/server-levels.md"]
+
+[[item]]
+id = "mod-registry"
+title = "Horizon's mod registry"
+status = "now"
+area = "mods"
+focus = true
+plain = """One place for mods, modpacks and resource packs made for Horizon: browse them on the website and \
+install them from the launcher in one click."""
+dev = """Merged: the registry index (schema 1, `.hpack`, checks before install, #1634), `cargo horizon-mod check` \
+(#1642) and the submission service (`crates/horizon-mod-registry`, #1659). In review: the website's /mods (#1596) \
+and /mods/submit (#1635), and in the launcher the registry as a source (#1636), install, enable and takedowns \
+(#1637), the Mods page (#1638) and modpacks as their own profiles (#1640)."""
+links = ["#1634", "#1642", "#1659", "#1596", "#1635", "#1636", "#1637", "#1638", "#1640", "docs/mods.md"]
+
+[[item]]
+id = "server-dialogs"
+title = "Server dialogs and login screens"
+status = "now"
+area = "servers"
+plain = """Servers that show dialogs, such as the register and login screens of AuthMe, will work in Horizon."""
+dev = """26.3's dialog packets and model (#1720), the dialog screen with its buttons and actions (#1734), then text \
+and boolean inputs (#1735)."""
+links = ["#1720", "#1734", "#1735"]
+
+[[item]]
+id = "languages"
+title = "Play in your language"
+status = "now"
+area = "gameplay"
+plain = """Item names, container titles and server messages follow the language you pick, as in vanilla. Today \
+parts of the game stay in English."""
+dev = """Translatable components resolved through the selected language for items, containers and server text \
+(#1806), on top of the bundled languages the prepared resources carry (#1594). Left: the client's own screens \
+(#1672) and the main menu with zh_cn (#1774)."""
+links = ["#1806", "#1594", "#1672", "#1774"]
+
+[[item]]
+id = "shader-packs"
+title = "Shader packs, written again from scratch"
+status = "now"
+ongoing = true
+area = "rendering"
+plain = """Shader packs were removed and are being rebuilt from scratch. They come back, off by default, once the \
+best-known packs draw properly."""
+dev = """A clean-room rewrite in `horizon-shaderpack`, from the packs' public format documentation only: reading \
+packs, the preprocessor and `.properties` files are merged (#1584, #1585, #1586); translating programs to WGSL \
+through naga, buffers, uniforms and the terrain, entity, sky, weather and hand stages are in review (#1698 to \
+#1801)."""
+links = ["#1561", "#1584", "#1586", "#1698", "#1771", "#1786", "#1801"]
+
+[[item]]
+id = "discord-presence"
+title = "Discord Rich Presence"
+status = "now"
+area = "extras"
+plain = """Your Discord profile can show that you are playing Horizon, with a switch to turn it off."""
+dev = """A Discord IPC client on its own thread (#1787) and the presence with its setting (#1788). Merged: it ships \
+with the next release."""
+links = ["#1787", "#1788"]
+
+[[item]]
+id = "lean-code"
+title = "A leaner codebase that builds faster"
+status = "now"
+ongoing = true
+area = "project"
+plain = """Cleaning up Horizon's code: removing what nothing uses and making it quicker to build, so fixes and new \
+features land faster."""
+dev = """A review of the whole tree: dead code and stubs removed (#1432, #1658), one probe binary per crate (#1453, \
+#1454), shared harness helpers (#1448), clippy clean on the whole tree (#1707). docs/architecture.md maps each \
+feature to its files and harnesses."""
+links = ["#1432", "#1658", "#1453", "#1454", "#1448", "#1707", "docs/architecture.md"]
+
+# ---------------------------------------------------------------------------------------------------- Next
+
+[[item]]
+id = "microsoft-sign-in"
+title = "Microsoft sign-in (coming soon)"
+status = "next"
+area = "launcher"
+plain = """Coming soon: sign in with your Microsoft account to play on online-mode servers. The code is ready; it \
+waits for Microsoft's approval."""
+dev = """Device-code sign-in in the launcher and online-mode login in the client (docs/microsoft-account.md). It is \
+turned on by setting the app's client id once Minecraft API access is approved; until then the launcher shows \
+"Coming soon"."""
+links = ["docs/microsoft-account.md", "#1270"]
+
+[[item]]
+id = "curseforge"
+title = "CurseForge in the mod browser (coming soon)"
+status = "next"
+area = "modpacks"
+plain = """Coming soon: search and download CurseForge mods and modpacks from the launcher, as you can with \
+Modrinth today."""
+dev = """The mod browser lists CurseForge as coming soon (docs/mod-browser.md): it needs CurseForge API access. \
+Meanwhile packs import from a CurseForge zip or instance folder, and jars only CurseForge hosts come from the \
+player's own instance (docs/modpacks.md)."""
+links = ["docs/mod-browser.md", "docs/modpacks.md"]
+
+[[item]]
+id = "benchmarks"
+title = "Fresh benchmarks against vanilla"
+status = "next"
+area = "performance"
+plain = """New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way \
+every time, on the website's Benchmarks page."""
+dev = """Redo the comparison after the current performance work (#1073); reliability, coverage and presentation \
+(#1346); a scene must count as loaded only once its first chunk arrives (#1749). Players' reports come in through \
+`--benchmark` and `horizon-launcher data benchmark` (docs/benchmark.md)."""
+links = ["#1073", "#1346", "#1749", "docs/benchmark.md"]
+
+[[item]]
+id = "pistons-push"
+title = "Pistons push players and mobs"
+status = "next"
+area = "gameplay"
+plain = """Pistons and slime blocks will push players, mobs and items as in vanilla. Today moving blocks pass \
+through them."""
+dev = """Port `PistonMovingBlockEntity.moveCollidedEntities` and `moveStuckEntities` (honey), the slime bounce and \
+`Entity.limitPistonMovement` for `MoverType.PISTON`, in single player and for a server's players. Issues #1496, \
+#1609, #1608, #1704, #1758."""
+links = ["#1496", "#1609", "#1608", "#1704", "#1758"]
+
+[[item]]
+id = "intel-mac"
+title = "Horizon on Intel Macs"
+status = "next"
+area = "launcher"
+plain = """Builds of the game and the launcher for Macs with an Intel processor."""
+dev = """x86_64 game and launcher builds, picked per processor (#1171). Before it ships it needs a run on a real \
+Intel Mac: Rosetta on Apple Silicon only proves the CPU code. Requests: #1161, #1792."""
+links = ["#1171", "#1161", "#1792"]
+
+# ---------------------------------------------------------------------------------------------------- Later
+
+[[item]]
+id = "ai-companion"
+title = "An optional AI teammate"
+status = "later"
+area = "extras"
+plain = """An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the \
+No AI switch hides it completely."""
+dev = """Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069), and a route \
+that finishes the game (#1070). Local models first; it ships only once the safety evaluation passes."""
+links = ["#1068", "#1069", "#1070"]
+
+[[item]]
+id = "new-versions"
+title = "Following new Minecraft versions"
+status = "later"
+area = "gameplay"
+plain = """When Mojang releases a new version of the game, Horizon follows it, and every system is checked against \
+the new version again."""
+dev = """The port pipeline detects a release, diffs its classes against 26.3 and writes a port report \
+(docs/version-ports.md); the harnesses then run against the new version."""
+links = ["docs/version-ports.md"]
+
+# ---------------------------------------------------------------------------------------------------- Help wanted
+
+[[item]]
+id = "benchmark-your-pc"
+title = "Benchmark your computer"
+status = "help-wanted"
+area = "performance"
+plain = """Run Horizon's built-in benchmark and share the report: every new computer makes the performance work \
+more accurate. No coding needed."""
+dev = """`horizon-launcher play --arg=--benchmark --arg=standard` writes a JSON report; `horizon-launcher data \
+benchmark <report>` shows what would be sent and uploads it (website/docs/performance.md). Results from three \
+installs with the same hardware appear on the Benchmarks page. Example: #1711."""
+links = ["website/docs/performance.md", "#1711"]
+
+[[item]]
+id = "end-city-banners"
+title = "End city banners keep their pattern"
+status = "help-wanted"
+area = "gameplay"
+plain = """Banners in End cities show as plain magenta instead of with their pattern."""
+dev = """Compare the banner block entities the End city templates place with vanilla's (`EndCityPieces`, the \
+templates' block entity NBT, `BannerBlockEntity`'s patterns), in `crates/horizon-world/src/worldgen/structure/`. \
+Issue #1438; possibly related: #526."""
+links = ["#1438", "#526"]
+
+[[item]]
+id = "end-city-loot"
+title = "Enchanted loot in End cities"
+status = "help-wanted"
+area = "gameplay"
+plain = """Armour and tools in End city chests should come enchanted, as in vanilla."""
+dev = """`loot.rs` implements `enchant_with_levels`: find why the End city chest table's rolls come out bare, and \
+compare them with vanilla's for a few seeds. Issues #1437, #1660."""
+links = ["#1437", "#1660"]
+
+[[item]]
+id = "item-cooldowns"
+title = "Cooldowns drawn on items"
+status = "help-wanted"
+area = "gameplay"
+plain = """After you throw an ender pearl, its slot should show the cooldown sweeping away, as in vanilla."""
+dev = """Vanilla draws `ItemCooldowns`' percent as a white overlay over the slot \
+(`GuiGraphicsExtractor.itemDecorations` and `itemCooldown`) in the hotbar and in inventories. Issue #1763."""
+links = ["#1763"]
+
+[[item]]
+id = "chat-settings"
+title = "Chat settings and team prefixes"
+status = "help-wanted"
+area = "gameplay"
+plain = """The Hidden and Commands Only chat settings should hide chat, and team prefixes should appear before \
+names in chat."""
+dev = """Vanilla checks `ChatVisiblity` before it delivers chat and system messages (#1376), and chat uses the \
+team-formatted display name (#1378). Both issues have exact steps to reproduce."""
+links = ["#1376", "#1378"]
+
+[[item]]
+id = "pointer-hand"
+title = "A pointing hand over buttons"
+status = "help-wanted"
+area = "gameplay"
+plain = """The mouse pointer should turn into a pointing hand over menu buttons, as in vanilla 26.3."""
+dev = """26.3's `AbstractWidget` asks for a cursor from `CursorTypes` when it is hovered; winit's \
+`CursorIcon::Pointer` gives the same shape. Issue #1347."""
+links = ["#1347"]
+
+[[item]]
+id = "text-field-keys"
+title = "Ctrl+Backspace and scroll bars in menus"
+status = "help-wanted"
+area = "gameplay"
+plain = """Ctrl+Backspace should delete a whole word in the creative search, and every list's scroll bar should be \
+draggable."""
+dev = """`EditBox` deletes by word with Ctrl (#1764); the Game Rules and Statistics lists' scroll bars can't be \
+dragged (#1782, after #978)."""
+links = ["#1764", "#1782"]
+
+[[item]]
+id = "chicken-flap"
+title = "Chickens flap while they fall"
+status = "help-wanted"
+area = "gameplay"
+plain = """Chickens should flap their wings while they fall, not stand still in the air."""
+dev = """Vanilla's `Chicken.aiStep` updates `flap` and `flapSpeed` when the chicken isn't on the ground, and the \
+model's wings follow them. Issue #1706."""
+links = ["#1706"]
+
+# ---------------------------------------------------------------------------------------------------- Shipped
+# Newest first: `tools/roadmap.py sync` adds each newly shipped item on top.
+
+[[item]]
+id = "server-resource-packs"
+title = "Server resource packs"
+status = "shipped"
+shipped_in = "v0.2.48"
+area = "servers"
+plain = """Servers can send you their resource pack: Horizon asks, downloads it and applies it, like vanilla."""
+dev = """The dedicated server offers server.properties' pack (#1562); the client's pack manager, downloads, prompt \
+and Server Resource Packs setting (#1569, #1570)."""
+links = ["#1562", "#1569", "#1570"]
+
+[[item]]
+id = "server-thread-default"
+title = "Single player on its own server thread"
+status = "shipped"
+shipped_in = "v0.2.39"
+area = "gameplay"
+plain = """Single player runs on a server thread, as vanilla does, so the world keeps ticking smoothly while the \
+window draws."""
+dev = """`game/integrated.rs` runs a second `Game` with one level per dimension; the window joins it through \
+memory like a LAN guest (#1514)."""
+links = ["#1514", "docs/server-levels.md"]
+
+[[item]]
+id = "metal-occlusion"
+title = "GPU occlusion culling on Macs"
+status = "shipped"
+shipped_in = "v0.2.17"
+area = "performance"
+plain = """On Macs the GPU now skips terrain hidden behind hills and caves: 8 to 48% more frames per second at 32 \
+chunks on an M4 Pro."""
+dev = """GPU occlusion culling on Metal (#1434)."""
+links = ["#1434"]
+
+[[item]]
+id = "gpu-animated-textures"
+title = "Animated textures on the GPU"
+status = "shipped"
+shipped_in = "v0.2.5"
+area = "performance"
+plain = """Water, lava and other animated blocks are now animated by the graphics card: 1.7 to 2.4 times better 1% \
+lows on Intel graphics."""
+dev = """Frames uploaded once, no per-tick CPU blend or copy (#1239)."""
+links = ["#1239"]
+
+[[item]]
+id = "far-detail"
+title = "Far Detail for integrated graphics"
+status = "shipped"
+shipped_in = "v0.2.5"
+area = "performance"
+plain = """An optional Reduced setting for far terrain, suggested on integrated graphics, that saves 2 to 4 ms of GPU \
+time per frame."""
+dev = """Opt-in reduced far terrain (#1199), on far-terrain chunk summaries built on the workers (#1029)."""
+links = ["#1199", "#1029"]
+
+[[item]]
+id = "mod-browser"
+title = "The launcher's mod browser"
+status = "shipped"
+shipped_in = "launcher@0.2.0"
+area = "modpacks"
+plain = """Search Modrinth for mods, modpacks and resource packs from the launcher; it says before installing what \
+works in Horizon."""
+dev = """The Mods page (#1154), Java mods checked before install (#1242), project pages, filters and galleries \
+(#1243), modpacks ported in the same step (#1246). docs/mod-browser.md."""
+links = ["#1154", "#1242", "#1243", "#1246", "docs/mod-browser.md"]
+
+[[item]]
+id = "launcher-look"
+title = "A blocky, Minecraft-like launcher"
+status = "shipped"
+shipped_in = "launcher@0.2.0"
+area = "launcher"
+plain = """The launcher got a new blocky look in Horizon's purple, in dark and light."""
+dev = """The Blocks look (#1269), from `horizon-theme` (docs/design-system.md)."""
+links = ["#1269", "docs/design-system.md"]
+
+[[item]]
+id = "dynamic-lights"
+title = "Dynamic lights"
+status = "shipped"
+shipped_in = "v2026.10.22"
+area = "extras"
+plain = """An optional extra: torches you hold, drop or set on fire light up what is around them."""
+dev = """Held, dropped and burning light sources (#1162), in Horizon Extras, off by default."""
+links = ["#1162"]
+
+[[item]]
+id = "servers-page"
+title = "Host a server from the launcher"
+status = "shipped"
+shipped_in = "launcher-v0.15.0"
+area = "servers"
+plain = """The launcher's Servers page creates, starts, backs up and updates a Horizon server with buttons, and \
+invites friends."""
+dev = """The launcher's Servers page (#1026) over `horizon-server` (docs/hosting.md)."""
+links = ["#1026", "docs/hosting.md"]
diff --git a/tests/test_roadmap.py b/tests/test_roadmap.py
new file mode 100644
index 000000000..fb4f4e419
--- /dev/null
+++ b/tests/test_roadmap.py
@@ -0,0 +1,207 @@
+import copy
+import datetime
+import tomllib
+import unittest
+from unittest import mock
+
+from tools import roadmap
+
+SAMPLE = '''[overview]
+today_plain = "a"
+today_dev = "b"
+help_plain = "c"
+help_dev = "d"
+
+[[area]]
+id = "performance"
+name = "Performance"
+
+# ---- Now
+
+[[item]]
+id = "fast"
+title = "Fast"
+status = "now"
+area = "performance"
+focus = true
+plain = "Faster."
+dev = """Multiply, \\
+not divide (#10)."""
+links = ["#10"]
+
+[[item]]
+id = "faster"
+title = "Faster"
+status = "now"
+area = "performance"
+focus = true
+plain = "Even faster."
+dev = "More (#11)."
+links = ["#11", "#12"]
+
+[[item]]
+id = "fastest"
+title = "Fastest"
+status = "now"
+area = "performance"
+focus = true
+ongoing = true
+plain = "The fastest."
+dev = "Most (#13)."
+links = ["#13"]
+
+# ---- Shipped
+
+[[item]]
+id = "old"
+title = "Old"
+status = "shipped"
+shipped_in = "v0.2.1"
+area = "performance"
+plain = "Done."
+dev = "Done (#1)."
+links = ["#1"]
+'''
+
+
+def pull(state, merged_at=None, paths=("crates/horizon-client/src/game.rs",)):
+    return {"kind": "PullRequest", "state": state, "merged_at": merged_at, "merge_commit": "abc" if merged_at else None,
+            "paths": list(paths)}
+
+
+def issue(state):
+    return {"kind": "Issue", "state": state, "merged_at": None, "merge_commit": None, "paths": []}
+
+
+class RepositoryRoadmap(unittest.TestCase):
+    def test_the_roadmap_keeps_its_rules(self):
+        self.assertEqual(roadmap.validate(roadmap.load()), [])
+
+    def test_roadmap_md_is_generated_from_the_toml(self):
+        self.assertEqual(roadmap.OUTPUT.read_text(), roadmap.render(roadmap.load()),
+                         "ROADMAP.md is out of date: run `python3 tools/roadmap.py build`")
+
+
+class Rules(unittest.TestCase):
+    def setUp(self):
+        self.data = tomllib.loads(SAMPLE)
+
+    def problems(self, **changes):
+        data = copy.deepcopy(self.data)
+        data["item"][0].update(changes)
+        return roadmap.validate(data)
+
+    def test_the_sample_is_valid(self):
+        self.assertEqual(roadmap.validate(self.data), [])
+
+    def test_unknown_status_area_and_key(self):
+        self.assertTrue(any("status" in p for p in self.problems(status="soon")))
+        self.assertTrue(any("area" in p for p in self.problems(area="nowhere")))
+        self.assertTrue(any("unknown key" in p for p in self.problems(eta="soon")))
+
+    def test_plain_fits_a_post(self):
+        self.assertTrue(any("at most 240" in p for p in self.problems(plain="x" * 241)))
+        self.assertTrue(any("post" in p for p in self.problems(post="x" * 241)))
+
+    def test_shipped_needs_its_release(self):
+        self.assertTrue(any("shipped_in" in p for p in self.problems(status="shipped", focus=False)))
+        self.assertTrue(any("only shipped" in p for p in self.problems(shipped_in="v0.2.3")))
+        self.assertTrue(any("not a release" in p for p in self.problems(status="shipped", focus=False,
+                                                                           shipped_in="soon")))
+
+    def test_links_are_issues_urls_or_repository_paths(self):
+        self.assertEqual(self.problems(links=["#4", "https://playhorizon.dev", "docs/benchmark.md"]), [])
+        self.assertTrue(any("link" in p for p in self.problems(links=["docs/nothing-here.md"])))
+        self.assertTrue(any("link" in p for p in self.problems(links=["http://example.com"])))
+
+    def test_three_to_five_items_in_focus(self):
+        self.assertTrue(any("focus" in p for p in self.problems(focus=False)))
+
+    def test_no_dates(self):
+        for text in ("Ready in March.", "Before 2027.", "In Q3.", "Next week.", "In 3 weeks.", "By the end of it."):
+            self.assertTrue(roadmap.dated(text), text)
+        for text in ("Coming soon.", "Pull request #2026.", "Java 26.3.", "Mobs march on.", "It may land."):
+            self.assertIsNone(roadmap.dated(text), text)
+        self.assertTrue(any("date" in p for p in self.problems(plain="Done in October.")))
+
+
+class Render(unittest.TestCase):
+    def test_sections_links_and_the_overview(self):
+        text = roadmap.render(tomllib.loads(SAMPLE))
+        self.assertIn("## Now", text)
+        self.assertIn("## Recently shipped", text)
+        self.assertNotIn("## Later", text)
+        self.assertIn("- **Fast**: Faster.", text)
+        self.assertIn("Multiply, not divide ([#10](https://github.com/ludovic111/horizon/issues/10)).", text)
+        # A link the technical text already gives isn't repeated; the others are listed after it.
+        self.assertIn("More: [#12](https://github.com/ludovic111/horizon/issues/12)", text)
+        self.assertIn("- **Old** (v0.2.1): Done.", text)
+
+
+class GitHubState(unittest.TestCase):
+    now = datetime.datetime(2030, 1, 20, tzinfo=datetime.timezone.utc)
+
+    def test_a_now_item_without_live_pull_requests_is_stale(self):
+        data = tomllib.loads(SAMPLE)
+        states = {1: pull("MERGED", "2029-12-01T00:00:00Z"), 10: pull("OPEN"),
+                  11: pull("MERGED", "2029-11-01T00:00:00Z"), 12: issue("OPEN"),
+                  13: pull("MERGED", "2030-01-19T00:00:00Z")}
+        problems, notes = roadmap.online_problems(data, states, self.now)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("faster: stale", problems[0])
+        self.assertTrue(any("fastest: ongoing" in note for note in notes))
+
+    def test_missing_numbers_are_reported(self):
+        problems, _ = roadmap.online_problems(tomllib.loads(SAMPLE), {}, self.now)
+        self.assertTrue(any("#10 is neither" in p for p in problems))
+
+
+class Labels(unittest.TestCase):
+    def test_creates_updates_and_adds_labels(self):
+        data = tomllib.loads(SAMPLE)
+        existing = {"roadmap:fast": {"color": "5B3FD6", "description": "Roadmap, now: Fast"},
+                    "roadmap:faster": {"color": "000000", "description": "old"},
+                    "roadmap:gone": {"color": "000000", "description": ""}}
+        states = {10: dict(pull("OPEN"), labels=["roadmap:fast"]), 11: dict(pull("OPEN"), labels=[]),
+                  13: dict(pull("MERGED", "2030-01-01T00:00:00Z"), labels=[])}
+        changes, stale = roadmap.label_changes(data, existing, states)
+        self.assertEqual([(action, target) for action, target, _ in changes],
+                         [("update", "roadmap:faster"), ("add", 11), ("create", "roadmap:fastest"),
+                          ("create", "roadmap:old")])
+        self.assertEqual(changes[0][2]["color"], "5b3fd6")
+        self.assertEqual(stale, ["roadmap:gone"])
+
+
+class Sync(unittest.TestCase):
+    def test_family_of_a_change(self):
+        self.assertEqual(roadmap.family(["launcher/src/main.rs"]), "launcher")
+        self.assertEqual(roadmap.family(["website/src/main.js"]), "website")
+        self.assertEqual(roadmap.family(["launcher/src/main.rs", "crates/x/src/lib.rs"]), "game")
+
+    def test_merged_and_released_items_move_to_the_top_of_shipped(self):
+        data = tomllib.loads(SAMPLE)
+        states = {10: pull("MERGED", "2030-01-02T00:00:00Z"), 11: pull("MERGED", "2030-01-03T00:00:00Z"),
+                  12: issue("OPEN"), 13: pull("MERGED", "2030-01-03T00:00:00Z")}
+        with mock.patch.object(roadmap, "first_release", return_value="v0.2.9") as release:
+            text, log = roadmap.sync(data, SAMPLE, states)
+        release.assert_called_once_with("abc", "game")
+        # "faster" keeps an open issue and "fastest" is ongoing: only "fast" ships.
+        self.assertEqual(log, ["fast: shipped in v0.2.9"])
+        new = tomllib.loads(text)
+        self.assertEqual([item["id"] for item in new["item"]], ["faster", "fastest", "fast", "old"])
+        fast = new["item"][2]
+        self.assertEqual((fast["status"], fast["shipped_in"]), ("shipped", "v0.2.9"))
+        self.assertNotIn("focus", fast)
+        self.assertEqual(fast["dev"], "Multiply, not divide (#10).")
+        self.assertIn("# ---- Shipped\n\n[[item]]\nid = \"fast\"", text)
+
+    def test_merged_but_unreleased_items_wait(self):
+        states = {10: pull("MERGED", "2030-01-02T00:00:00Z")}
+        with mock.patch.object(roadmap, "first_release", return_value=None):
+            text, log = roadmap.sync(tomllib.loads(SAMPLE), SAMPLE, states)
+        self.assertEqual(text, SAMPLE)
+        self.assertEqual(log, ["fast: merged, waiting for a release"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/pr_ready.py b/tools/pr_ready.py
index a944e2116..505de28c1 100755
--- a/tools/pr_ready.py
+++ b/tools/pr_ready.py
@@ -108,7 +108,7 @@ def touched_crates(paths, packages):
 
 def area(path):
     """The part of the project a path belongs to; None for what goes with any change (docs, tests, harnesses)."""
-    if is_doc(path) or path.startswith(("tests/", "mods/", "docs/")) or path == "research-lock.json" or \
+    if is_doc(path) or path.startswith(("tests/", "mods/", "docs/", "roadmap/")) or path == "research-lock.json" or \
             (path.startswith("tools/") and not path.startswith("tools/ci/")):
         return None
     if path.startswith(("launcher/", "crates/horizon-prepare/")):
@@ -288,7 +288,9 @@ def plan(args, base, changed, crates_of, libraries, dependencies):
     """The checks for these changed files, in the order they run."""
     rust = any(workspace_rust(path) for path in changed)
     launcher = any(launcher_rust(path) for path in changed)
-    python = any(path.endswith(".py") or path.startswith(("tests/", "tools/")) for path in changed)
+    # The Python tests also hold ROADMAP.md to roadmap/roadmap.toml (tests/test_roadmap.py).
+    python = any(path.endswith(".py") or path.startswith(("tests/", "tools/", "roadmap/")) or path == "ROADMAP.md"
+                 for path in changed)
     crates = touched_crates(changed, crates_of) if rust or TOKENS in changed else []
     # An unrecognised Rust path must not silently skip validation.
     if rust and crates == []:
diff --git a/tools/roadmap.py b/tools/roadmap.py
new file mode 100644
index 000000000..b1bb13c6d
--- /dev/null
+++ b/tools/roadmap.py
@@ -0,0 +1,551 @@
+#!/usr/bin/env python3
+"""Horizon's roadmap: roadmap/roadmap.toml is the source, ROADMAP.md is generated from it.
+
+    python3 tools/roadmap.py build              write ROADMAP.md
+    python3 tools/roadmap.py build --check      fail when ROADMAP.md is out of date (CI)
+    python3 tools/roadmap.py check --offline    the file's own rules (CI)
+    python3 tools/roadmap.py check              the same, then GitHub: links resolve, no stale Now item
+    python3 tools/roadmap.py sync [--dry-run]   items whose pull requests all merged become shipped,
+                                                with the release they went out in
+    python3 tools/roadmap.py labels [--dry-run] a `roadmap:<id>` label per item on GitHub, and on the open
+                                                pull requests the item links
+
+The online commands read GitHub with GITHUB_TOKEN, GH_TOKEN or `gh auth token`. Maintenance: roadmap/README.md.
+"""
+
+import argparse
+import datetime
+import json
+import os
+import re
+import subprocess
+import sys
+import tomllib
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SOURCE = ROOT / "roadmap" / "roadmap.toml"
+OUTPUT = ROOT / "ROADMAP.md"
+REPO = "ludovic111/horizon"
+SITE = "https://playhorizon.dev/hub"
+
+STATUSES = {
+    "now": "Now",
+    "next": "Next",
+    "later": "Later",
+    "help-wanted": "Help wanted",
+    "shipped": "Recently shipped",
+}
+PLAIN_MAX = 240  # one post's worth, so a shipped item can be announced as written
+TITLE_MAX = 70
+FOCUS_RANGE = (3, 5)
+STALE_DAYS = 14  # a Now item needs an open pull request, or one merged this recently
+LABEL_PREFIX = "roadmap:"
+# GitHub label colours by status, from the design system's palette.
+LABEL_COLOURS = {"now": "5b3fd6", "next": "9a86ff", "later": "c5c7d1", "help-wanted": "1d7a48", "shipped": "646875"}
+ITEM_KEYS = {"id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post"}
+
+ISSUE = re.compile(r"#(\d+)$")
+ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$")
+RELEASE = re.compile(r"(v\d[\w.]*|launcher@\d[\w.]*|launcher-v\d[\w.]*|website)$")
+MONTHS = ("January|February|March|April|June|July|August|September|October|November|December")
+# Kira's rule: no dates and no promises of when. "Coming soon" is the one allowed phrase.
+DATE = re.compile(
+    rf"\b(?:{MONTHS})\b|\bMay \d|(?<![#\w.])20\d\d(?!\w|\.\d)|\bQ[1-4]\b|\btomorrow\b|\btonight\b"
+    r"|\b(?:next|this) (?:week|month|year)\b|\bin \d+ (?:days?|weeks?|months?)\b|\bby the end of\b",
+    re.IGNORECASE)
+MONTH_CASE = re.compile(rf"\b(?:{MONTHS})\b")
+
+
+def load(path=SOURCE):
+    with open(path, "rb") as source:
+        return tomllib.load(source)
+
+
+def link_url(link):
+    """Where a link points: "#12" is an issue or a pull request (GitHub redirects one to the other)."""
+    match = ISSUE.match(link)
+    if match:
+        return f"https://github.com/{REPO}/issues/{match[1]}"
+    return link
+
+
+def dated(text):
+    """The first date or deadline in the text, or None. A month counts only capitalised ("march" is a verb)."""
+    for match in DATE.finditer(text):
+        if match[0].lower() not in MONTHS.lower().split("|") or MONTH_CASE.fullmatch(match[0]):
+            return match[0]
+    return None
+
+
+def validate(data, root=ROOT):
+    """The file's own rules, without the network. Returns a list of problems."""
+    problems = []
+    overview = data.get("overview", {})
+    for key in ("today_plain", "today_dev", "help_plain", "help_dev"):
+        if not str(overview.get(key, "")).strip():
+            problems.append(f"overview: {key} is missing")
+    areas = [area.get("id") for area in data.get("area", [])]
+    if len(set(areas)) != len(areas):
+        problems.append("areas: an id appears twice")
+    seen = set()
+    items = data.get("item", [])
+    for index, item in enumerate(items):
+        where = f"item {item.get('id') or index + 1}"
+        for key in sorted(set(item) - ITEM_KEYS):
+            problems.append(f"{where}: unknown key {key!r}")
+        for key in ("id", "title", "status", "area", "plain", "dev"):
+            if not str(item.get(key, "")).strip():
+                problems.append(f"{where}: {key} is missing")
+        ident = item.get("id", "")
+        if ident and not ID.match(ident):
+            problems.append(f"{where}: ids are lowercase words joined by dashes")
+        if ident in seen:
+            problems.append(f"{where}: the id appears twice")
+        seen.add(ident)
+        status = item.get("status")
+        if status not in STATUSES:
+            problems.append(f"{where}: status {status!r} is not one of {', '.join(STATUSES)}")
+        if item.get("area") not in areas:
+            problems.append(f"{where}: area {item.get('area')!r} is not declared in an [[area]]")
+        if len(item.get("title", "")) > TITLE_MAX:
+            problems.append(f"{where}: the title is longer than {TITLE_MAX} characters")
+        for key in ("plain", "post"):
+            if len(item.get(key, "")) > PLAIN_MAX:
+                problems.append(f"{where}: {key} is {len(item[key])} characters, at most {PLAIN_MAX}")
+        for key in ("title", "plain", "dev", "post"):
+            found = dated(item.get(key, ""))
+            if found:
+                problems.append(f"{where}: {key} names a date or a deadline ({found!r}); the roadmap has none")
+        shipped_in = item.get("shipped_in")
+        if status == "shipped":
+            if not shipped_in:
+                problems.append(f"{where}: a shipped item needs shipped_in (a release tag, or \"website\")")
+            elif not RELEASE.match(shipped_in):
+                problems.append(f"{where}: shipped_in {shipped_in!r} is not a release tag or \"website\"")
+        elif shipped_in:
+            problems.append(f"{where}: only shipped items have shipped_in")
+        if item.get("ongoing") and status not in ("now", "next", "later"):
+            problems.append(f"{where}: only Now, Next and Later items are ongoing")
+        if item.get("focus") and status != "now":
+            problems.append(f"{where}: only Now items can be in focus")
+        links = item.get("links", [])
+        if not isinstance(links, list):
+            problems.append(f"{where}: links is a list")
+            links = []
+        if not links and status != "later":
+            problems.append(f"{where}: needs at least one link (an issue, a pull request or a doc)")
+        for link in links:
+            if ISSUE.match(link) or link.startswith("https://"):
+                continue
+            if link.startswith(("/", "http:")) or ".." in link or not (root / link).exists():
+                problems.append(f"{where}: link {link!r} is neither #N, https:// nor a path in the repository")
+    focus = sum(1 for item in items if item.get("focus"))
+    low, high = FOCUS_RANGE
+    if not low <= focus <= high:
+        problems.append(f"focus: {focus} items are in focus, the overview wants {low} to {high}")
+    return problems
+
+
+def areas_in_order(data):
+    return [(area["id"], area["name"]) for area in data.get("area", [])]
+
+
+def by_area(data, status):
+    """The items of a status, grouped by area in the areas' order, each group in the file's order."""
+    items = [item for item in data.get("item", []) if item.get("status") == status]
+    return [(name, [item for item in items if item["area"] == key])
+            for key, name in areas_in_order(data) if any(item["area"] == key for item in items)]
+
+
+def linkify(text, links=()):
+    """Markdown links for the text's #N, and for the item's own paths and URLs where the text names them."""
+    text = re.sub(r"(?<![\w\[/])#(\d+)\b", lambda m: f"[#{m[1]}]({link_url('#' + m[1])})", text)
+    for link in links:
+        if not ISSUE.match(link):
+            text = re.sub(rf"(?<![\w/\[])(?<!\]\(){re.escape(link)}(?![\w/])", f"[{link}]({link})", text, count=1)
+    return text
+
+
+def link_list(links):
+    return " · ".join(f"[{link}]({link_url(link)})" for link in links)
+
+
+def render(data):
+    """ROADMAP.md, from the parsed TOML."""
+    overview = data["overview"]
+    items = data.get("item", [])
+    out = [
+        "# Horizon roadmap",
+        "",
+        "<!-- Generated by tools/roadmap.py from roadmap/roadmap.toml: edit that file, then run"
+        " `python3 tools/roadmap.py build`. -->",
+        "",
+        "What is being done on Horizon, what comes next and where you can help. There are no dates: things are"
+        " Now, Next or Later. Each item is said in plain words, with the technical picture folded under it."
+        f" The same roadmap, with a Simple / Technical switch, the board, the journal and how to help, is on"
+        f" [playhorizon.dev/hub]({SITE}). Pull requests carry the `roadmap:<id>` label of their item.",
+        "",
+        "## At a glance",
+        "",
+        overview["today_plain"].strip(),
+        "",
+        "**Being done now**",
+        "",
+    ]
+    out += [f"- **{item['title']}**: {item['plain'].strip()}" for item in items if item.get("focus")]
+    nexts = [item["title"] for item in items if item.get("status") == "next"]
+    if nexts:
+        out += ["", "**Next**: " + "; ".join(nexts) + "."]
+    out += ["", f"**How to help**: {overview['help_plain'].strip()}", "",
+            f"**Developers**: {overview['help_dev'].strip()}"]
+    for status, heading in STATUSES.items():
+        groups = by_area(data, status)
+        if not groups:
+            continue
+        out += ["", f"## {heading}"]
+        if status == "shipped":
+            # Newest first: the file's order, where `sync` puts each newly shipped item on top.
+            out += [""] + [f"- **{item['title']}** ({item['shipped_in']}): {item['plain'].strip()} "
+                           f"{link_list(item['links'])}" for item in items if item.get("status") == status]
+            continue
+        for area, group in groups:
+            out += ["", f"### {area}"]
+            for item in group:
+                out += ["", f"#### {item['title']}", "", item["plain"].strip(), "",
+                        "<details><summary>Technical</summary>", "", linkify(item["dev"].strip(), item.get("links", []))]
+                more = [link for link in item.get("links", []) if not re.search(rf"{re.escape(link)}\b", item["dev"])]
+                if more:
+                    out += ["", "More: " + link_list(more)]
+                out += ["", "</details>"]
+    return "\n".join(out) + "\n"
+
+
+# --- GitHub ---------------------------------------------------------------------------------------------------
+
+def token():
+    for name in ("GITHUB_TOKEN", "GH_TOKEN"):
+        if os.environ.get(name):
+            return os.environ[name]
+    try:
+        return subprocess.run(["gh", "auth", "token"], capture_output=True, text=True, check=True).stdout.strip()
+    except (OSError, subprocess.CalledProcessError):
+        sys.exit("roadmap: reading GitHub needs GITHUB_TOKEN, GH_TOKEN or `gh auth login` (or use --offline)")
+
+
+def numbers_in(data):
+    return sorted({int(ISSUE.match(link)[1]) for item in data.get("item", [])
+                   for link in item.get("links", []) if ISSUE.match(link)})
+
+
+def github_states(numbers, auth):
+    """{number: {"kind": "Issue" | "PullRequest", "state", "merged_at", "merge_commit", "paths"}} for those
+    that exist, in one GraphQL request per hundred numbers."""
+    owner, name = REPO.split("/")
+    states = {}
+    for start in range(0, len(numbers), 100):
+        fields = "\n".join(
+            f"n{n}: issueOrPullRequest(number: {n}) {{ __typename "
+            "... on Issue { state } "
+            "... on PullRequest { state mergedAt mergeCommit { oid } files(first: 100) { nodes { path } } "
+            "labels(first: 50) { nodes { name } } } }"
+            for n in numbers[start:start + 100])
+        query = f'query {{ repository(owner: "{owner}", name: "{name}") {{ {fields} }} }}'
+        request = urllib.request.Request(
+            "https://api.github.com/graphql", data=json.dumps({"query": query}).encode(),
+            headers={"Authorization": f"bearer {auth}", "User-Agent": "horizon-roadmap"})
+        with urllib.request.urlopen(request, timeout=30) as response:
+            answer = json.load(response)
+        for key, node in (answer.get("data", {}).get("repository") or {}).items():
+            if node:
+                states[int(key[1:])] = {
+                    "kind": node["__typename"],
+                    "state": node["state"],
+                    "merged_at": node.get("mergedAt"),
+                    "merge_commit": (node.get("mergeCommit") or {}).get("oid"),
+                    "paths": [file["path"] for file in ((node.get("files") or {}).get("nodes") or [])],
+                    "labels": [label["name"] for label in ((node.get("labels") or {}).get("nodes") or [])],
+                }
+    return states
+
+
+def pull_requests(item, states):
+    return [states[n] for n in (int(ISSUE.match(link)[1]) for link in item.get("links", []) if ISSUE.match(link))
+            if n in states and states[n]["kind"] == "PullRequest"]
+
+
+def open_issues(item, states):
+    return [n for n in (int(ISSUE.match(link)[1]) for link in item.get("links", []) if ISSUE.match(link))
+            if n in states and states[n]["kind"] == "Issue" and states[n]["state"] == "OPEN"]
+
+
+def online_problems(data, states, now):
+    """What only GitHub can tell: links that don't exist, Now items nobody works on, Help wanted items already
+    done, items `sync` would ship."""
+    problems, notes = [], []
+    recent = now - datetime.timedelta(days=STALE_DAYS)
+    for item in data.get("item", []):
+        where = f"item {item['id']}"
+        for link in item.get("links", []):
+            match = ISSUE.match(link)
+            if match and int(match[1]) not in states:
+                problems.append(f"{where}: {link} is neither an issue nor a pull request of {REPO}")
+        pulls = pull_requests(item, states)
+        status = item.get("status")
+        if status == "now":
+            alive = [p for p in pulls if p["state"] == "OPEN" or
+                     (p["merged_at"] and datetime.datetime.fromisoformat(p["merged_at"]) >= recent)]
+            if not alive:
+                problems.append(f"{where}: stale: Now, but no open pull request and none merged in the last "
+                                f"{STALE_DAYS} days (link the work, or move it to Next or Later)")
+        if status == "help-wanted":
+            issues = [states[int(ISSUE.match(link)[1])] for link in item.get("links", [])
+                      if ISSUE.match(link) and int(ISSUE.match(link)[1]) in states]
+            if issues and all(i["state"] != "OPEN" for i in issues):
+                problems.append(f"{where}: every linked issue and pull request is closed: ship or drop it")
+        if status != "shipped" and pulls and all(p["state"] == "MERGED" for p in pulls):
+            if item.get("ongoing"):
+                notes.append(f"{where}: ongoing, and all its pull requests merged: link the new ones")
+            elif not open_issues(item, states):
+                notes.append(f"{where}: all its pull requests merged: `python3 tools/roadmap.py sync` ships it "
+                             "once a release has them")
+    return problems, notes
+
+
+# --- sync -----------------------------------------------------------------------------------------------------
+
+def family(paths):
+    """Which releases carry a change: the launcher's, the website (deployed from main) or the game's."""
+    if paths and all(path.startswith("launcher/") for path in paths):
+        return "launcher"
+    if paths and all(path.startswith("website/") for path in paths):
+        return "website"
+    return "game"
+
+
+def first_release(commit, kind):
+    """The oldest release tag of this kind that contains the commit, or None while none does."""
+    if kind == "website":
+        return "website"
+    tags = subprocess.run(["git", "tag", "--contains", commit, "--sort=creatordate"], cwd=ROOT,
+                          capture_output=True, text=True).stdout.split()
+    wanted = (lambda tag: tag.startswith(("launcher@", "launcher-v"))) if kind == "launcher" else \
+        (lambda tag: re.match(r"v\d", tag))
+    return next((tag for tag in tags if wanted(tag)), None)
+
+
+def release_of(pulls):
+    """The release that shipped the last of these merged pull requests, or None."""
+    kinds = {family(p["paths"]) for p in pulls}
+    kind = "game" if "game" in kinds or len(kinds) > 1 else kinds.pop()
+    latest = max(pulls, key=lambda p: p["merged_at"])
+    return first_release(latest["merge_commit"], kind) if latest["merge_commit"] else None
+
+
+def item_span(lines, ident):
+    """[start, end) of the item's lines: its [[item]] header to its last key, without the comments that follow."""
+    starts = [i for i, line in enumerate(lines) if line.strip() == "[[item]]"]
+    for position, start in enumerate(starts):
+        end = starts[position + 1] if position + 1 < len(starts) else len(lines)
+        if not any(re.match(rf'id\s*=\s*"{re.escape(ident)}"\s*$', line) for line in lines[start:end]):
+            continue
+        while end > start and (not lines[end - 1].strip() or re.match(r"#(\s|-|$)", lines[end - 1])):
+            end -= 1
+        return start, end
+    raise KeyError(ident)
+
+
+def mark_shipped(text, ident, release):
+    """The TOML with this item shipped in `release`, moved to the top of the shipped items (newest first)."""
+    lines = text.split("\n")
+    start, end = item_span(lines, ident)
+    block = [line for line in lines[start:end] if not line.startswith("shipped_in")]
+    block = [f'status = "shipped"\nshipped_in = "{release}"' if re.match(r"status\s*=", line) else line
+             for line in block]
+    block = [line for line in block if not re.match(r"focus\s*=", line)]
+    rest = lines[:start] + lines[end:]
+    # Drop the blank line the block leaves behind.
+    if start < len(rest) and start > 0 and not rest[start - 1].strip() and not rest[start].strip():
+        del rest[start]
+    shipped = [i for i, line in enumerate(rest) if re.match(r'status\s*=\s*"shipped"', line)]
+    if shipped:
+        header = max(i for i in range(shipped[0] + 1) if rest[i].strip() == "[[item]]")
+        rest[header:header] = block + [""]
+    else:
+        rest += [""] + block
+    return "\n".join(rest)
+
+
+def sync(data, text, states):
+    """Ship every item whose linked pull requests all went out in a release and whose linked issues are all
+    closed, unless it is ongoing. Returns the new text and what happened."""
+    log = []
+    for item in data.get("item", []):
+        if item.get("status") == "shipped":
+            continue
+        pulls = pull_requests(item, states)
+        # An ongoing item, or one with an open issue, still has work left whatever its pull requests say.
+        if item.get("ongoing") or open_issues(item, states):
+            continue
+        if not pulls or any(p["state"] != "MERGED" for p in pulls):
+            continue
+        release = release_of(pulls)
+        if release is None:
+            log.append(f"{item['id']}: merged, waiting for a release")
+            continue
+        text = mark_shipped(text, item["id"], release)
+        log.append(f"{item['id']}: shipped in {release}")
+    return text, log
+
+
+# --- labels ---------------------------------------------------------------------------------------------------
+
+def label_of(item):
+    """The GitHub label of an item: its name, colour and description (GitHub allows 100 characters)."""
+    description = f"Roadmap, {STATUSES[item['status']].lower()}: {item['title']}"
+    return {"name": LABEL_PREFIX + item["id"], "color": LABEL_COLOURS[item["status"]], "description": description[:100]}
+
+
+def label_changes(data, existing, states):
+    """What `labels` does: [(action, label or number, payload)] for labels to create or update, and open pull
+    requests linked from an item that lack its label. existing: {name: {"color", "description"}}; states as
+    github_states, plus each pull request's "labels"."""
+    changes = []
+    for item in data.get("item", []):
+        label = label_of(item)
+        have = existing.get(label["name"])
+        if have is None:
+            changes.append(("create", label["name"], label))
+        elif (have.get("color", "").lower(), have.get("description") or "") != (label["color"], label["description"]):
+            changes.append(("update", label["name"], label))
+        for link in item.get("links", []):
+            match = ISSUE.match(link)
+            state = states.get(int(match[1])) if match else None
+            if state and state["kind"] == "PullRequest" and state["state"] == "OPEN" and \
+                    label["name"] not in state.get("labels", []):
+                changes.append(("add", int(match[1]), label["name"]))
+    stale = sorted(set(existing) - {LABEL_PREFIX + item["id"] for item in data.get("item", [])})
+    return changes, [name for name in stale if name.startswith(LABEL_PREFIX)]
+
+
+def github_rest(method, path, auth, body=None):
+    request = urllib.request.Request(
+        f"https://api.github.com{path}", method=method, data=None if body is None else json.dumps(body).encode(),
+        headers={"Authorization": f"bearer {auth}", "Accept": "application/vnd.github+json",
+                 "User-Agent": "horizon-roadmap"})
+    with urllib.request.urlopen(request, timeout=30) as response:
+        return json.load(response) if response.status != 204 else None
+
+
+def existing_labels(auth):
+    labels, page = {}, 1
+    while True:
+        batch = github_rest("GET", f"/repos/{REPO}/labels?per_page=100&page={page}", auth)
+        labels.update({label["name"]: label for label in batch})
+        if len(batch) < 100:
+            return labels
+        page += 1
+
+
+# --- commands -------------------------------------------------------------------------------------------------
+
+def report(problems):
+    for problem in problems:
+        print(f"roadmap: {problem}", file=sys.stderr)
+    return 1 if problems else 0
+
+
+def command_build(args):
+    data = load()
+    problems = validate(data)
+    if problems:
+        return report(problems)
+    markdown = render(data)
+    if args.check:
+        if not OUTPUT.exists() or OUTPUT.read_text() != markdown:
+            return report(["ROADMAP.md is out of date: run `python3 tools/roadmap.py build`"])
+        return 0
+    OUTPUT.write_text(markdown)
+    print(f"roadmap: wrote {OUTPUT.relative_to(ROOT)}")
+    return 0
+
+
+def command_check(args):
+    data = load()
+    problems = validate(data)
+    if not problems and not args.offline:
+        states = github_states(numbers_in(data), token())
+        online, notes = online_problems(data, states, datetime.datetime.now(datetime.timezone.utc))
+        problems += online
+        for note in notes:
+            print(f"roadmap: {note}")
+    if not problems:
+        print(f"roadmap: {len(data.get('item', []))} items, all good")
+    return report(problems)
+
+
+def command_sync(args):
+    data = load()
+    problems = validate(data)
+    if problems:
+        return report(problems)
+    subprocess.run(["git", "fetch", "--quiet", "--tags", "origin"], cwd=ROOT, check=False)
+    text, log = sync(data, SOURCE.read_text(), github_states(numbers_in(data), token()))
+    for line in log:
+        print(f"roadmap: {line}")
+    if args.dry_run or text == SOURCE.read_text():
+        return 0
+    new = tomllib.loads(text)
+    if len(new.get("item", [])) != len(data.get("item", [])) or validate(new):
+        return report(["sync produced an invalid file; nothing written"] + validate(new))
+    SOURCE.write_text(text)
+    OUTPUT.write_text(render(new))
+    print("roadmap: wrote roadmap/roadmap.toml and ROADMAP.md")
+    return 0
+
+
+def command_labels(args):
+    data = load()
+    problems = validate(data)
+    if problems:
+        return report(problems)
+    auth = token()
+    changes, stale = label_changes(data, existing_labels(auth), github_states(numbers_in(data), auth))
+    for action, target, payload in changes:
+        print(f"roadmap: {action} {target}" + (f" ({payload})" if action == "add" else ""))
+        if args.dry_run:
+            continue
+        if action == "create":
+            github_rest("POST", f"/repos/{REPO}/labels", auth, payload)
+        elif action == "update":
+            github_rest("PATCH", f"/repos/{REPO}/labels/{urllib.parse.quote(target, safe='')}", auth,
+                        {"color": payload["color"], "description": payload["description"]})
+        else:
+            github_rest("POST", f"/repos/{REPO}/issues/{target}/labels", auth, {"labels": [payload]})
+    for name in stale:
+        print(f"roadmap: {name} names no item any more: rename or delete it by hand (it stays on its pull requests)")
+    if not changes:
+        print("roadmap: labels up to date")
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    commands = parser.add_subparsers(dest="command", required=True)
+    build = commands.add_parser("build", help="write ROADMAP.md")
+    build.add_argument("--check", action="store_true", help="fail when ROADMAP.md is out of date")
+    check = commands.add_parser("check", help="the roadmap's rules, and GitHub's state of its links")
+    check.add_argument("--offline", action="store_true", help="skip GitHub")
+    sync_command = commands.add_parser("sync", help="ship the items whose pull requests all merged")
+    sync_command.add_argument("--dry-run", action="store_true", help="say what would change, write nothing")
+    labels = commands.add_parser("labels", help="a roadmap:<id> label per item, on its linked open pull requests")
+    labels.add_argument("--dry-run", action="store_true", help="say what would change, change nothing")
+    args = parser.parse_args(argv)
+    return {"build": command_build, "check": command_check, "sync": command_sync,
+            "labels": command_labels}[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 98bebd26bdc33efaa4483ac5d5cbb07250fc1345 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:14:48 +0100
Subject: [PATCH 083/270] Launcher: one place reads the pinned appearance
 (theme::pinned_dark)

The title bar and the theme both resolved HORIZON_LAUNCHER_APPEARANCE and the
Settings choice; titlebar::apply_appearance now uses the theme's helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/theme.rs    | 39 +++++++++++++++++++++++++--------------
 launcher/src/titlebar.rs | 21 +++++++--------------
 2 files changed, 32 insertions(+), 28 deletions(-)

diff --git a/launcher/src/theme.rs b/launcher/src/theme.rs
index 60b796709..9d495a598 100644
--- a/launcher/src/theme.rs
+++ b/launcher/src/theme.rs
@@ -74,22 +74,33 @@ fn c(hex: u32) -> Hsla {
     rgb(hex).into()
 }
 
+/// Whether the launcher is pinned dark (`Some(true)`) or light, or follows the system (`None`):
+/// `HORIZON_LAUNCHER_APPEARANCE=light` or `dark` (for screenshots and tests), else the player's
+/// choice in Settings.
+pub fn pinned_dark(choice: Appearance) -> Option<bool> {
+    match std::env::var("HORIZON_LAUNCHER_APPEARANCE").as_deref() {
+        Ok("light") => Some(false),
+        Ok("dark") => Some(true),
+        _ => match choice {
+            Appearance::Dark => Some(true),
+            Appearance::Light => Some(false),
+            Appearance::System => None,
+        },
+    }
+}
+
 impl Theme {
-    /// The player's choice in Settings (dark unless they picked another), the system's when they
-    /// asked to follow it. `HORIZON_LAUNCHER_APPEARANCE=light` or `dark` overrides both (for
-    /// screenshots and tests).
+    /// The pinned look (`pinned_dark`: dark unless the player picked another), the system's when
+    /// they asked to follow it.
     pub fn for_appearance(choice: Appearance, system: WindowAppearance) -> Self {
-        match std::env::var("HORIZON_LAUNCHER_APPEARANCE").as_deref() {
-            Ok("light") => return Self::light(),
-            Ok("dark") => return Self::dark(),
-            _ => {}
-        }
-        match (choice, system) {
-            (Appearance::Light, _) => Self::light(),
-            (Appearance::System, WindowAppearance::Light | WindowAppearance::VibrantLight) => {
-                Self::light()
-            }
-            _ => Self::dark(),
+        let system_dark = !matches!(
+            system,
+            WindowAppearance::Light | WindowAppearance::VibrantLight
+        );
+        if pinned_dark(choice).unwrap_or(system_dark) {
+            Self::dark()
+        } else {
+            Self::light()
         }
     }
 
diff --git a/launcher/src/titlebar.rs b/launcher/src/titlebar.rs
index 2e6445091..a023f7d7d 100644
--- a/launcher/src/titlebar.rs
+++ b/launcher/src/titlebar.rs
@@ -22,9 +22,8 @@ pub fn render(_theme: &Theme, _window: &Window) -> Option<Div> {
 
 /// macOS keeps the window's appearance on the system setting, so a launcher set to Dark still
 /// draws a light title bar on a light desktop. Pin the NSWindow's appearance to the choice
-/// instead (`System` clears the pin, handing the chrome back to the system), honouring the same
-/// `HORIZON_LAUNCHER_APPEARANCE` override the theme does. Other platforms' chrome already
-/// follows the setting (ours is drawn, Windows and Linux follow the system either way).
+/// instead (`theme::pinned_dark`: `System` clears the pin, handing the chrome back to the
+/// system). Elsewhere the chrome is ours (Windows) or the system's (Linux).
 #[cfg(target_os = "macos")]
 pub fn apply_appearance(window: &Window, choice: Appearance) {
     use objc2_app_kit::{
@@ -33,17 +32,11 @@ pub fn apply_appearance(window: &Window, choice: Appearance) {
     };
     use raw_window_handle::{HasWindowHandle, RawWindowHandle};
 
-    // Reading AppKit's name constants is unsafe to rustc only (`use of extern static`).
-    let name: Option<&'static NSAppearanceName> = unsafe {
-        match std::env::var("HORIZON_LAUNCHER_APPEARANCE").as_deref() {
-            Ok("light") => Some(NSAppearanceNameAqua),
-            Ok("dark") => Some(NSAppearanceNameDarkAqua),
-            _ => match choice {
-                Appearance::Dark => Some(NSAppearanceNameDarkAqua),
-                Appearance::Light => Some(NSAppearanceNameAqua),
-                Appearance::System => None,
-            },
-        }
+    // AppKit's name constants are extern statics: reading them is `unsafe` to rustc only.
+    let name: Option<&'static NSAppearanceName> = match crate::theme::pinned_dark(choice) {
+        Some(true) => Some(unsafe { NSAppearanceNameDarkAqua }),
+        Some(false) => Some(unsafe { NSAppearanceNameAqua }),
+        None => None,
     };
     // The trait, not `Window::window_handle` (which is gpui's own `AnyWindowHandle`).
     let Ok(handle) = HasWindowHandle::window_handle(window) else {

From 6d418fdb3ef91907ee71f055991b88294d479efa Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:17:19 +0100
Subject: [PATCH 084/270] Docs: publish a mod through the registry, and how
 horizon-mods runs

docs/mods.md gets "Publish your mod" (the form, the review, updates) and
its Distribution section points at the registry instead of the plan for
it. docs/api/mod-index.md says how horizon-mods runs: its checks, merging,
Pages, the weekly cleanup, and that removing an entry needs an admin merge
(takedowns go in revoked.toml). The service's README says where it runs on
Railway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-mod-registry/README.md |  7 ++++--
 docs/api/mod-index.md                 | 17 +++++++++++++-
 docs/mods.md                          | 33 ++++++++++++++++++++++-----
 3 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/crates/horizon-mod-registry/README.md b/crates/horizon-mod-registry/README.md
index 936fe5acf..f7cdc68c5 100644
--- a/crates/horizon-mod-registry/README.md
+++ b/crates/horizon-mod-registry/README.md
@@ -40,5 +40,8 @@ REGISTRY_PUBLIC_URL=http://localhost:4173 REGISTRY_SESSION_KEY=... GITHUB_CLIENT
 | `REGISTRY_REPO` | Default `ludovic111/horizon-mods` |
 | `PORT` | Default 8080 |
 
-On Railway it is its own service (`railway.json`, built with the `Dockerfile` from the repository root); the website's
-Caddy sends `/api/mods/*` to it over Railway's private network.
+On Railway it is the service `horizon-mod-registry` of the project `horizon-site`, next to the website: built from
+`main` with this `Dockerfile` from the repository root, health check `/healthz`, no public domain and no volume. The
+website's Caddy sends `/api/mods/*` to it over Railway's private network (`REGISTRY_UPSTREAM` on the website service:
+`http://horizon-mod-registry.railway.internal:8080`). `railway.json` lists the same settings; Railway reads them from
+the service, not from the file.
diff --git a/docs/api/mod-index.md b/docs/api/mod-index.md
index beb6ec2c8..6b807d950 100644
--- a/docs/api/mod-index.md
+++ b/docs/api/mod-index.md
@@ -138,9 +138,24 @@ Unknown keys are refused. Its CI runs `cargo-horizon-mod` (`crates/cargo-horizon
 | `cargo horizon-mod check <file> [--json]` | A submission's checks: its kind's (above), its signature with `--key` and `--signature`, and for a mod a trial run in the sandbox (40 ticks, 120 frames, a chat line, each command). |
 | `cargo horizon-mod registry check <base> <head> --files <dir>` | `check` on each file `head` lists and `base` doesn't: a pull request's new files. |
 | `cargo horizon-mod registry list <checkout>` | `<sha256> <id> <version> <file>` per version: the files to download. |
-| `cargo horizon-mod registry build <checkout> --files <dir> --out index.json` | Reads every entry and its file (`<dir>/<sha256>`), lists every problem, and writes the index with URLs `<release>/<id>-<version>/<file>`. |
+| `cargo horizon-mod registry build <checkout> --files <dir> --out index.json` | Reads every entry and its file (`<dir>/<sha256>`), lists every problem, and writes the index with URLs `<release><id>-<version>/<file>` (`--release`, ending in `/`, defaults to the repository's releases). |
 | `cargo horizon-mod registry review <base> <head> --author <login>` | A pull request's changes: a published file never changes and is never removed (take it down in `revoked.toml`), a kind never changes; changes by a non-owner and to owners or keys are pointed out for the reviewers. |
 
+How the repository runs (its workflows are in `.github/workflows/`):
+
+- **A pull request** (`check.yml`) runs `registry review`, downloads each new file from the `staging` prerelease, runs
+  `registry check` on it and builds the index it would publish; the report is the run's summary. The tool is
+  `cargo-horizon-mod` from Horizon at the commit in the repository variable `HORIZON_REV`. The form's pull requests
+  are opened with the token of the account in the variable `REGISTRY_BOT`; for those, the author is the login in the
+  body's `<!-- submitted-by: … -->` line.
+- **Merging** needs the `check` run and a CODEOWNER's review. `publish.yml` then makes each new version a release
+  `<id>-<version>` and deploys `index.json` and `icons/` to GitHub Pages:
+  `https://ludovic111.github.io/horizon-mods/index.json`, served with `Access-Control-Allow-Origin: *`.
+- **Weekly**, `cleanup.yml` deletes staged copies of published files after 7 days and of files no open pull request
+  lists after 30.
+- **Taking a file down** is a pull request adding it to `revoked.toml`. Removing an entry outright (a test, a project
+  nobody installed) fails `registry review` on purpose and needs an administrator's merge.
+
 Kinds open to submissions: `mod`, `modpack`, `resourcepack`. `shader` is in the schema and stays closed until
 Horizon's own shader pack format exists (Iris and OptiFine packs are for the Modrinth browser); its check will compile
 the pack in a headless Horizon. A new kind gets its own check before it opens.
diff --git a/docs/mods.md b/docs/mods.md
index 5fa6a290d..bac207f60 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -378,6 +378,29 @@ none.
     "top": "carve", "bottom": "none", "rigid_junctions": true, "inflate": true } }
 ```
 
+## Publish your mod
+
+Horizon's registry lists mods, modpacks (`.hpack`) and resource packs made for Horizon, each reviewed before it is
+published. Players find them at [playhorizon.dev/mods](https://playhorizon.dev/mods) and in the launcher (Mods, then
+**Horizon** beside Modrinth), which checks every file before it installs it.
+
+1. Run `cargo horizon-mod check` on the file (above): the registry runs the same checks.
+2. Put the source somewhere public, under a licence that lets players run it: reviewers read it, and the file must be
+   built from it.
+3. Open [playhorizon.dev/mods/submit](https://playhorizon.dev/mods/submit), sign in with GitHub (it reads only your
+   public profile) and fill in the page: the file, its name and summary, licence, source address, and optionally a
+   minisign public key with the file's `.minisig`.
+4. The form checks the file again and opens a pull request in
+   [ludovic111/horizon-mods](https://github.com/ludovic111/horizon-mods) that adds `mods/<id>.toml`, with you as its
+   owner. That repository's checks run the file in the sandbox and post their report on the pull request; answer the
+   reviewers there.
+5. A reviewer merges it: within minutes the file is a release of horizon-mods, and the project is on the site and in
+   the launcher.
+
+An update is the same form with a new version; only the project's `owners` can publish one, signed with its key if it
+has one. A published file never changes. Without the form, open the pull request by hand (the repository's README
+says how). The formats: [api/mod-index.md](api/mod-index.md).
+
 ## Versions and compatibility
 
 - The API is the WIT package `horizon:mods@0.1.0`. New functions and
@@ -420,12 +443,10 @@ none.
   format: a `.hmod.minisig` beside it); the index pins each project's public
   key, so an update signed by another key is refused. Unsigned local files
   stay allowed, with an "unsigned" mark on the Mods page.
-- **Where mods come from.** Modrinth is where players already look and it
-  stores files with hashes, but its loader list is Modrinth's to extend: we ask
-  Modrinth to add a `horizon` loader. Until then (and as a fallback), the
-  launcher reads a small index of approved mods: a JSON file in a public Git
-  repository (id, versions, file URLs as GitHub release assets, SHA-256,
-  signing key). No server of our own is needed.
+- **Where mods come from.** Horizon's registry ([Publish your mod](#publish-your-mod)): reviewed pull requests in
+  [ludovic111/horizon-mods](https://github.com/ludovic111/horizon-mods), files as its release assets, and an
+  `index.json` on GitHub Pages that the launcher and the website read. A file the registry takes down
+  (`revoked.toml`) is refused by the launcher and turned off where installed.
 - **The launcher.** A Mods tab per installation: browse and search the index,
   install, update, turn on and off (it writes the same `horizon-mods.txt`),
   see capabilities before installing. The launcher's CLI and MCP tools gain

From 98c8db50a35a0eb7e0409a5865e35e40edfce906 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:18:03 +0100
Subject: [PATCH 085/270] Horizon shader packs: horizon-shaders.toml (schema 1)
 and the .hshader package

A new crate, horizon-shader-api, reads and checks Horizon's own WGSL shader
packs (docs/api/shaders.md), so the game, the launcher and the registry judge
a pack the same way. This first part is the format: the manifest (id, name,
version, the api line, shared files, the sky, material and post stages,
options typed for WGSL override constants, a GPU time budget) and the package
(a folder or a .hshader zip, built reproducibly so its SHA-256 depends only on
its files). The stages' WGSL is checked in the next parts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |   1 +
 Cargo.lock                                    |   9 +
 Cargo.toml                                    |   2 +-
 crates/horizon-shader-api/Cargo.toml          |  15 +
 crates/horizon-shader-api/src/lib.rs          |  10 +
 crates/horizon-shader-api/src/manifest.rs     | 365 ++++++++++++++++++
 crates/horizon-shader-api/src/package.rs      | 175 +++++++++
 .../tests/samples/schema-1/README.md          |   1 +
 .../tests/samples/schema-1/common.wgsl        |   3 +
 .../samples/schema-1/horizon-shaders.toml     |  59 +++
 .../tests/samples/schema-1/material.wgsl      |   3 +
 .../tests/samples/schema-1/post/grade.wgsl    |   8 +
 .../tests/samples/schema-1/post/vignette.wgsl |   8 +
 .../tests/samples/schema-1/sky.wgsl           |   3 +
 crates/horizon-shader-api/tests/schema.rs     | 238 ++++++++++++
 docs/api/shaders.md                           |  46 ++-
 16 files changed, 944 insertions(+), 2 deletions(-)
 create mode 100644 crates/horizon-shader-api/Cargo.toml
 create mode 100644 crates/horizon-shader-api/src/lib.rs
 create mode 100644 crates/horizon-shader-api/src/manifest.rs
 create mode 100644 crates/horizon-shader-api/src/package.rs
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/README.md
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/common.wgsl
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl
 create mode 100644 crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl
 create mode 100644 crates/horizon-shader-api/tests/schema.rs

diff --git a/AGENTS.md b/AGENTS.md
index 0656e40fc..a72c6723a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,6 +45,7 @@ Game workspace (root `Cargo.toml`); `launcher/` and `crates/horizon-telemetry-se
 | `horizon-friends`, `horizon-relay` | Play with Friends: invite codes, encrypted tunnel, the relay ([docs/play-with-friends.md](docs/play-with-friends.md)) |
 | `horizon-mods`, `horizon-mod-sdk`, `cargo-horizon-mod` | Sandboxed WebAssembly mods: runtime, SDK + WIT, `cargo horizon-mod` ([docs/mods.md](docs/mods.md)) |
 | `horizon-port-pack` | Porting Java modpacks ([docs/modpacks.md](docs/modpacks.md)) |
+| `horizon-shader-api` | Horizon's own WGSL shader packs ([docs/api/shaders.md](docs/api/shaders.md)): `horizon-shaders.toml`, the `.hshader` package; shared by the game, the launcher and the registry |
 | `horizon-shaders` | Shader packs (the `shaders/` folder format), rebuilt clean-room from a written spec of the format; no wgpu |
 | `horizon-theme` | Design tokens and fonts for the launcher, the game's own menus and the website |
 | `horizon-telemetry`, `horizon-telemetry-server`, `horizon-bench` | Opt-in data collection, its ingest server, the benchmark report format |
diff --git a/Cargo.lock b/Cargo.lock
index 2d09d2d0e..25b278069 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1437,6 +1437,15 @@ dependencies = [
  "ureq",
 ]
 
+[[package]]
+name = "horizon-shader-api"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "toml",
+ "zip",
+]
+
 [[package]]
 name = "horizon-shaders"
 version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index c6f2bc581..294e93aa9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml
new file mode 100644
index 000000000..5d9098055
--- /dev/null
+++ b/crates/horizon-shader-api/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "horizon-shader-api"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+rust-version = "1.85"
+description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-shaders.toml, the .hshader package"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+toml = "1.1.6"
+zip = { version = "2", default-features = false, features = ["deflate"] }
+
+[lints]
+workspace = true
diff --git a/crates/horizon-shader-api/src/lib.rs b/crates/horizon-shader-api/src/lib.rs
new file mode 100644
index 000000000..418563089
--- /dev/null
+++ b/crates/horizon-shader-api/src/lib.rs
@@ -0,0 +1,10 @@
+//! Horizon's own shader packs (docs/api/shaders.md): WGSL written against
+//! the renderer's stages, described by `horizon-shaders.toml` and shipped as
+//! a folder or a `.hshader`. This crate reads and checks packs; the game, the
+//! launcher and the registry all use it, so a pack is judged the same way
+//! everywhere.
+pub mod manifest;
+pub mod package;
+
+pub use manifest::{API, MANIFEST, Manifest, OptionKind, PackOption, SCHEMA, Stage};
+pub use package::{EXTENSION, Pack};
diff --git a/crates/horizon-shader-api/src/manifest.rs b/crates/horizon-shader-api/src/manifest.rs
new file mode 100644
index 000000000..d03a4f213
--- /dev/null
+++ b/crates/horizon-shader-api/src/manifest.rs
@@ -0,0 +1,365 @@
+//! `horizon-shaders.toml`, a shader pack's manifest (schema 1, docs/shaders.md).
+use serde::Deserialize;
+
+/// The manifest's file name at the root of a pack.
+pub const MANIFEST: &str = "horizon-shaders.toml";
+/// The manifest schema this build reads.
+pub const SCHEMA: u32 = 1;
+/// The shader API line this build serves: the stages, their signatures and
+/// the inputs a pack's WGSL may read.
+pub const API: &str = "0.1";
+/// Full-screen passes a pack may chain.
+pub const MAX_POST_PASSES: usize = 8;
+/// Options a pack may declare.
+pub const MAX_OPTIONS: usize = 64;
+/// The most GPU time a pack may declare for itself, in milliseconds.
+pub const MAX_GPU_MS: f32 = 16.0;
+
+/// A checked manifest.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Manifest {
+    /// `[a-z0-9_]{1,64}`: the pack's settings key and registry id.
+    pub id: String,
+    pub name: String,
+    pub version: String,
+    /// The API line the pack is written for.
+    pub api: String,
+    pub description: String,
+    pub authors: Vec<String>,
+    pub license: Option<String>,
+    /// WGSL files put before every stage's own file, in order.
+    pub shared: Vec<String>,
+    pub sky: Option<Stage>,
+    pub material: Option<Stage>,
+    /// Full-screen passes, in the order they run.
+    pub post: Vec<Stage>,
+    pub options: Vec<PackOption>,
+    pub budget: Budget,
+}
+
+/// One stage: the WGSL file that defines its function.
+#[derive(Clone, Debug, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Stage {
+    pub file: String,
+    /// Shown in the GPU time overlay; the file name when absent.
+    #[serde(default)]
+    pub name: Option<String>,
+}
+
+/// An option the player can change: a WGSL `override` constant of the
+/// same name, set when the pipelines are built.
+#[derive(Clone, Debug, PartialEq)]
+pub struct PackOption {
+    /// The `override`'s name in the pack's WGSL.
+    pub id: String,
+    pub name: String,
+    pub description: String,
+    pub kind: OptionKind,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum OptionKind {
+    /// `override <id>: bool`.
+    Bool { default: bool },
+    /// `override <id>: f32`; the slider moves by `step`.
+    Float {
+        default: f32,
+        min: f32,
+        max: f32,
+        step: f32,
+    },
+    /// `override <id>: i32`.
+    Int { default: i32, min: i32, max: i32 },
+    /// `override <id>: u32`, the index of the chosen value.
+    Choice { values: Vec<String>, default: u32 },
+}
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Budget {
+    /// The GPU time the pack aims to add to a frame, in milliseconds; the
+    /// overlay shows the pack over budget past it.
+    pub gpu_ms: Option<f32>,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Raw {
+    schema: u32,
+    id: String,
+    name: String,
+    version: String,
+    api: String,
+    #[serde(default)]
+    description: String,
+    #[serde(default)]
+    authors: Vec<String>,
+    license: Option<String>,
+    #[serde(default)]
+    shared: Vec<String>,
+    sky: Option<Stage>,
+    material: Option<Stage>,
+    #[serde(default)]
+    post: Vec<Stage>,
+    #[serde(default)]
+    options: Vec<RawOption>,
+    #[serde(default)]
+    budget: RawBudget,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawOption {
+    id: String,
+    name: String,
+    #[serde(default)]
+    description: String,
+    #[serde(rename = "type")]
+    kind: String,
+    default: toml::Value,
+    min: Option<toml::Value>,
+    max: Option<toml::Value>,
+    step: Option<f64>,
+    values: Option<Vec<String>>,
+}
+
+#[derive(Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawBudget {
+    gpu_ms: Option<f64>,
+}
+
+impl Manifest {
+    pub fn parse(text: &str) -> Result<Manifest, String> {
+        let raw: Raw = toml::from_str(text).map_err(|e| format!("{MANIFEST}: {e}"))?;
+        let err = |e: String| format!("{MANIFEST}: {e}");
+        if raw.schema != SCHEMA {
+            return Err(err(format!(
+                "schema {}; this Horizon reads {SCHEMA}",
+                raw.schema
+            )));
+        }
+        if raw.api != API {
+            return Err(err(format!(
+                "written for shader API {}; this Horizon serves {API}",
+                raw.api
+            )));
+        }
+        let id_ok = (1..=64).contains(&raw.id.len())
+            && raw
+                .id
+                .bytes()
+                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_');
+        if !id_ok {
+            return Err(err(format!("id {:?} is not [a-z0-9_]{{1,64}}", raw.id)));
+        }
+        if raw.name.trim().is_empty() || raw.version.trim().is_empty() {
+            return Err(err("name and version can't be empty".into()));
+        }
+        if raw.sky.is_none() && raw.material.is_none() && raw.post.is_empty() {
+            return Err(err(
+                "no stage: give it a [sky], a [material] or a [[post]]".into()
+            ));
+        }
+        if raw.post.len() > MAX_POST_PASSES {
+            return Err(err(format!(
+                "{} post passes; a pack may chain {MAX_POST_PASSES}",
+                raw.post.len()
+            )));
+        }
+        let stages = raw.sky.iter().chain(&raw.material).chain(&raw.post);
+        for file in raw.shared.iter().chain(stages.map(|s| &s.file)) {
+            if !crate::package::plain_path(file) || !file.ends_with(".wgsl") {
+                return Err(err(format!("{file:?} is not a plain path to a .wgsl file")));
+            }
+        }
+        if raw.options.len() > MAX_OPTIONS {
+            return Err(err(format!(
+                "{} options; a pack may declare {MAX_OPTIONS}",
+                raw.options.len()
+            )));
+        }
+        let mut options = Vec::with_capacity(raw.options.len());
+        for (i, o) in raw.options.into_iter().enumerate() {
+            let id = o.id.clone();
+            let option = o.check().map_err(|e| err(format!("option {id:?}: {e}")))?;
+            if options[..i].iter().any(|p: &PackOption| p.id == option.id) {
+                return Err(err(format!("option {id:?} is declared twice")));
+            }
+            options.push(option);
+        }
+        let gpu_ms = match raw.budget.gpu_ms {
+            Some(ms) if !(ms > 0.0 && ms <= f64::from(MAX_GPU_MS)) => {
+                return Err(err(format!(
+                    "budget.gpu_ms {ms} is not in (0, {MAX_GPU_MS}]"
+                )));
+            }
+            ms => ms.map(|ms| ms as f32),
+        };
+        Ok(Manifest {
+            id: raw.id,
+            name: raw.name,
+            version: raw.version,
+            api: raw.api,
+            description: raw.description,
+            authors: raw.authors,
+            license: raw.license,
+            shared: raw.shared,
+            sky: raw.sky,
+            material: raw.material,
+            post: raw.post,
+            options,
+            budget: Budget { gpu_ms },
+        })
+    }
+
+    /// Every WGSL file the manifest names, shared files first, each once.
+    pub fn files(&self) -> Vec<&str> {
+        let mut files: Vec<&str> = Vec::new();
+        let stages = self.sky.iter().chain(&self.material).chain(&self.post);
+        for file in self.shared.iter().chain(stages.map(|s| &s.file)) {
+            if !files.contains(&file.as_str()) {
+                files.push(file);
+            }
+        }
+        files
+    }
+}
+
+/// A WGSL identifier the renderer leaves to packs: ASCII, not starting
+/// with a digit, `_` or the renderer's own `horizon_` prefix.
+pub fn pack_identifier(name: &str) -> bool {
+    let mut bytes = name.bytes();
+    bytes.next().is_some_and(|b| b.is_ascii_alphabetic())
+        && bytes.all(|b| b.is_ascii_alphanumeric() || b == b'_')
+        && name.len() <= 64
+        && !name.starts_with("horizon_")
+}
+
+impl RawOption {
+    fn check(self) -> Result<PackOption, String> {
+        if !pack_identifier(&self.id) {
+            return Err(
+                "the id must be a WGSL identifier: a letter, then letters, digits or _, up to 64, not starting with horizon_".into(),
+            );
+        }
+        let int = |v: &toml::Value| {
+            v.as_integer()
+                .and_then(|i| i32::try_from(i).ok())
+                .ok_or_else(|| format!("{v} is not a 32-bit integer"))
+        };
+        let float = |v: &toml::Value| {
+            v.as_float()
+                .or_else(|| v.as_integer().map(|i| i as f64))
+                .filter(|f| f.is_finite())
+                .map(|f| f as f32)
+                .ok_or_else(|| format!("{v} is not a number"))
+        };
+        let need = |v: Option<toml::Value>, key: &str| v.ok_or_else(|| format!("needs {key}"));
+        let unused = |present: bool, key: &str| {
+            if present {
+                Err(format!("{key} doesn't apply to type = {:?}", self.kind))
+            } else {
+                Ok(())
+            }
+        };
+        let kind = match self.kind.as_str() {
+            "bool" => {
+                unused(self.min.is_some() || self.max.is_some(), "min/max")?;
+                unused(self.step.is_some(), "step")?;
+                unused(self.values.is_some(), "values")?;
+                let default = self
+                    .default
+                    .as_bool()
+                    .ok_or("default must be true or false")?;
+                OptionKind::Bool { default }
+            }
+            "float" => {
+                unused(self.values.is_some(), "values")?;
+                let (min, max) = (
+                    float(&need(self.min, "min")?)?,
+                    float(&need(self.max, "max")?)?,
+                );
+                let default = float(&self.default)?;
+                let step = self.step.map_or((max - min) / 100.0, |s| s as f32);
+                if !(min < max && (min..=max).contains(&default)) {
+                    return Err(format!("needs min < max and default in [{min}, {max}]"));
+                }
+                if !(step > 0.0 && step <= max - min) {
+                    return Err(format!("step {step} is not in (0, max - min]"));
+                }
+                OptionKind::Float {
+                    default,
+                    min,
+                    max,
+                    step,
+                }
+            }
+            "int" => {
+                unused(self.step.is_some(), "step")?;
+                unused(self.values.is_some(), "values")?;
+                let (min, max) = (int(&need(self.min, "min")?)?, int(&need(self.max, "max")?)?);
+                let default = int(&self.default)?;
+                if !(min < max && (min..=max).contains(&default)) {
+                    return Err(format!("needs min < max and default in [{min}, {max}]"));
+                }
+                OptionKind::Int { default, min, max }
+            }
+            "choice" => {
+                unused(self.min.is_some() || self.max.is_some(), "min/max")?;
+                unused(self.step.is_some(), "step")?;
+                let values = self.values.ok_or("needs values")?;
+                if !(2..=32).contains(&values.len()) {
+                    return Err("needs 2 to 32 values".into());
+                }
+                if values
+                    .iter()
+                    .enumerate()
+                    .any(|(i, v)| v.trim().is_empty() || values[..i].contains(v))
+                {
+                    return Err("values must be distinct and not empty".into());
+                }
+                let default = self
+                    .default
+                    .as_str()
+                    .and_then(|d| values.iter().position(|v| v == d))
+                    .ok_or("default must be one of the values")?;
+                OptionKind::Choice {
+                    values,
+                    default: default as u32,
+                }
+            }
+            other => {
+                return Err(format!("type {other:?} is not bool, float, int or choice"));
+            }
+        };
+        Ok(PackOption {
+            id: self.id,
+            name: self.name,
+            description: self.description,
+            kind,
+        })
+    }
+}
+
+impl OptionKind {
+    /// The WGSL type of the option's `override`.
+    pub fn wgsl_type(&self) -> &'static str {
+        match self {
+            OptionKind::Bool { .. } => "bool",
+            OptionKind::Float { .. } => "f32",
+            OptionKind::Int { .. } => "i32",
+            OptionKind::Choice { .. } => "u32",
+        }
+    }
+
+    /// The default as the pipeline constant wgpu takes.
+    pub fn default_constant(&self) -> f64 {
+        match *self {
+            OptionKind::Bool { default } => f64::from(u8::from(default)),
+            OptionKind::Float { default, .. } => f64::from(default),
+            OptionKind::Int { default, .. } => f64::from(default),
+            OptionKind::Choice { default, .. } => f64::from(default),
+        }
+    }
+}
diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs
new file mode 100644
index 000000000..af72afc4c
--- /dev/null
+++ b/crates/horizon-shader-api/src/package.rs
@@ -0,0 +1,175 @@
+//! A shader pack on disk: a folder holding `horizon-shaders.toml`, or the
+//! same files zipped as a `.hshader` (what the registry and the launcher
+//! carry). Both read into one [`Pack`].
+use crate::manifest::{MANIFEST, Manifest};
+use std::{
+    collections::BTreeMap,
+    io::{Read, Write},
+    path::Path,
+};
+
+/// A packaged pack's extension.
+pub const EXTENSION: &str = "hshader";
+/// Bytes per WGSL file, per other file, and in all.
+const MAX_WGSL: u64 = 256 << 10;
+const MAX_OTHER: u64 = 1 << 20;
+const MAX_TOTAL: u64 = 8 << 20;
+/// Files in a `.hshader`.
+const MAX_ENTRIES: usize = 512;
+/// Files a pack may hold beside its manifest and WGSL.
+const EXTRAS: [&str; 5] = [
+    "README.md",
+    "LICENSE",
+    "LICENSE.md",
+    "LICENSE.txt",
+    "icon.png",
+];
+
+/// A pack read from a folder or a `.hshader`: its manifest and every file,
+/// by path from the pack's root (`/`-separated).
+#[derive(Debug)]
+pub struct Pack {
+    pub manifest: Manifest,
+    pub files: BTreeMap<String, Vec<u8>>,
+}
+
+/// A relative path made of plain parts: no root, `..`, `\`, empty or
+/// hidden parts.
+pub fn plain_path(path: &str) -> bool {
+    !path.is_empty()
+        && path.split('/').all(|part| {
+            !part.is_empty()
+                && !part.starts_with('.')
+                && part
+                    .bytes()
+                    .all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b))
+        })
+}
+
+impl Pack {
+    /// Reads `path`: a `.hshader` file, or a folder (its hidden files and
+    /// folders, such as `.git`, are skipped).
+    pub fn read(path: &Path) -> Result<Pack, String> {
+        let mut files = BTreeMap::new();
+        if path.is_dir() {
+            read_dir(path, "", &mut files)?;
+        } else {
+            let file = std::fs::File::open(path).map_err(|e| format!("{}: {e}", path.display()))?;
+            let mut zip = zip::ZipArchive::new(file)
+                .map_err(|e| format!("{}: not a .{EXTENSION} (zip): {e}", path.display()))?;
+            if zip.len() > MAX_ENTRIES {
+                return Err(format!("over {MAX_ENTRIES} files in the package"));
+            }
+            for i in 0..zip.len() {
+                let mut entry = zip.by_index(i).map_err(|e| e.to_string())?;
+                if entry.is_dir() {
+                    continue;
+                }
+                let name = entry.name().to_owned();
+                let mut bytes = Vec::new();
+                (&mut entry)
+                    .take(MAX_OTHER.max(MAX_WGSL) + 1)
+                    .read_to_end(&mut bytes)
+                    .map_err(|e| format!("{name}: {e}"))?;
+                if files.insert(name.clone(), bytes).is_some() {
+                    return Err(format!("{name} is in the package twice"));
+                }
+            }
+        }
+        Pack::from_files(files)
+    }
+
+    /// Checks a pack's files: a manifest, the WGSL it names (as UTF-8),
+    /// nothing it doesn't use, and sizes within bounds.
+    pub fn from_files(files: BTreeMap<String, Vec<u8>>) -> Result<Pack, String> {
+        let text = files
+            .get(MANIFEST)
+            .ok_or_else(|| format!("{MANIFEST}: missing at the pack's root"))?;
+        let manifest = Manifest::parse(
+            std::str::from_utf8(text).map_err(|_| format!("{MANIFEST}: not UTF-8"))?,
+        )?;
+        let used = manifest.files();
+        let mut total = 0;
+        for (name, bytes) in &files {
+            if !plain_path(name) {
+                return Err(format!("{name:?} is not a plain path"));
+            }
+            let size = bytes.len() as u64;
+            total += size;
+            let max = if name.ends_with(".wgsl") {
+                if !used.contains(&name.as_str()) {
+                    return Err(format!("{name} is not used by any stage or in shared"));
+                }
+                if std::str::from_utf8(bytes).is_err() {
+                    return Err(format!("{name}: not UTF-8"));
+                }
+                MAX_WGSL
+            } else if name == MANIFEST || EXTRAS.contains(&name.as_str()) {
+                MAX_OTHER
+            } else {
+                return Err(format!(
+                    "{name}: a pack holds only {MANIFEST}, .wgsl files and {}",
+                    EXTRAS.join(", ")
+                ));
+            };
+            if size > max {
+                return Err(format!("{name} is over {} KiB", max >> 10));
+            }
+        }
+        if total > MAX_TOTAL {
+            return Err(format!("the pack is over {} MiB", MAX_TOTAL >> 20));
+        }
+        if let Some(missing) = used.iter().find(|f| !files.contains_key(**f)) {
+            return Err(format!("{missing}: named in {MANIFEST} but missing"));
+        }
+        Ok(Pack { manifest, files })
+    }
+
+    /// A WGSL file's text (every file the manifest names is checked UTF-8).
+    pub fn source(&self, file: &str) -> Option<&str> {
+        self.files
+            .get(file)
+            .and_then(|b| std::str::from_utf8(b).ok())
+    }
+
+    /// The `.hshader` bytes: the files in path order, with fixed times and
+    /// permissions, so the same pack always gives the same bytes (and the
+    /// same SHA-256).
+    pub fn package(&self) -> Result<Vec<u8>, String> {
+        let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
+        let options = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Deflated)
+            .last_modified_time(zip::DateTime::default())
+            .unix_permissions(0o644);
+        let err = |e: zip::result::ZipError| e.to_string();
+        for (name, bytes) in &self.files {
+            zip.start_file(name.as_str(), options).map_err(err)?;
+            zip.write_all(bytes).map_err(|e| e.to_string())?;
+        }
+        Ok(zip.finish().map_err(err)?.into_inner())
+    }
+}
+
+fn read_dir(dir: &Path, prefix: &str, files: &mut BTreeMap<String, Vec<u8>>) -> Result<(), String> {
+    let entries = std::fs::read_dir(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
+    for entry in entries {
+        let entry = entry.map_err(|e| format!("{}: {e}", dir.display()))?;
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if name.starts_with('.') {
+            continue;
+        }
+        let path = entry.path();
+        let rel = format!("{prefix}{name}");
+        if path.is_dir() {
+            read_dir(&path, &format!("{rel}/"), files)?;
+        } else {
+            let size = entry.metadata().map_err(|e| format!("{rel}: {e}"))?.len();
+            if size > MAX_TOTAL {
+                return Err(format!("{rel} is over {} MiB", MAX_TOTAL >> 20));
+            }
+            let bytes = std::fs::read(&path).map_err(|e| format!("{rel}: {e}"))?;
+            files.insert(rel, bytes);
+        }
+    }
+    Ok(())
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/README.md b/crates/horizon-shader-api/tests/samples/schema-1/README.md
new file mode 100644
index 000000000..6762a7892
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/README.md
@@ -0,0 +1 @@
+The schema 1 sample read by `tests/schema.rs`. Its WGSL is checked once the stages exist.
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl
new file mode 100644
index 000000000..8fef8baf9
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl
@@ -0,0 +1,3 @@
+fn luminance(c: vec3<f32>) -> f32 {
+    return dot(c, vec3<f32>(0.2126, 0.7152, 0.0722));
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml b/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml
new file mode 100644
index 000000000..6e8a545a7
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml
@@ -0,0 +1,59 @@
+# Schema 1 of horizon-shaders.toml with every key. Readers of later schemas
+# keep reading this file (docs/api/stability.md, "Data formats").
+schema = 1
+id = "sample_pack"
+name = "Sample Pack"
+version = "1.0.0"
+api = "0.1"
+description = "Every key of schema 1."
+authors = ["Horizon"]
+license = "MIT"
+shared = ["common.wgsl"]
+
+[sky]
+file = "sky.wgsl"
+
+[material]
+file = "material.wgsl"
+name = "Terrain"
+
+[[post]]
+file = "post/grade.wgsl"
+name = "Colour grade"
+
+[[post]]
+file = "post/vignette.wgsl"
+
+[[options]]
+id = "saturation"
+name = "Saturation"
+description = "How colourful the picture is."
+type = "float"
+default = 1.1
+min = 0.0
+max = 2.0
+step = 0.05
+
+[[options]]
+id = "vignette"
+name = "Vignette"
+type = "bool"
+default = true
+
+[[options]]
+id = "samples"
+name = "Samples"
+type = "int"
+default = 4
+min = 1
+max = 16
+
+[[options]]
+id = "tonemap"
+name = "Tone mapping"
+type = "choice"
+values = ["None", "Soft", "Filmic"]
+default = "Soft"
+
+[budget]
+gpu_ms = 1.5
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
new file mode 100644
index 000000000..0ad42c6d9
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
@@ -0,0 +1,3 @@
+fn material(input: MaterialInput) -> Surface {
+    return input.surface;
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl
new file mode 100644
index 000000000..8daa1eab0
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl
@@ -0,0 +1,8 @@
+override saturation: f32 = 1.1;
+override tonemap: u32 = 1u;
+
+fn post(input: PostInput) -> vec4<f32> {
+    let c = input.color.rgb;
+    let graded = mix(vec3<f32>(luminance(c)), c, saturation);
+    return vec4<f32>(select(graded, graded / (graded + 0.5) * 1.5, tonemap > 0u), input.color.a);
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl
new file mode 100644
index 000000000..84f7261cb
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl
@@ -0,0 +1,8 @@
+override vignette: bool = true;
+override samples: i32 = 4;
+
+fn post(input: PostInput) -> vec4<f32> {
+    let d = distance(input.uv, vec2<f32>(0.5));
+    let dark = select(1.0, 1.0 - smoothstep(0.4, 0.9, d) * 0.5, vignette);
+    return vec4<f32>(input.color.rgb * dark, input.color.a);
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl
new file mode 100644
index 000000000..55ca0ac1d
--- /dev/null
+++ b/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl
@@ -0,0 +1,3 @@
+fn sky(input: SkyInput) -> vec4<f32> {
+    return input.color;
+}
diff --git a/crates/horizon-shader-api/tests/schema.rs b/crates/horizon-shader-api/tests/schema.rs
new file mode 100644
index 000000000..2176805ee
--- /dev/null
+++ b/crates/horizon-shader-api/tests/schema.rs
@@ -0,0 +1,238 @@
+//! Schema 1 of `horizon-shaders.toml` and the `.hshader` package.
+use horizon_shader_api::{MANIFEST, Manifest, OptionKind, Pack};
+use std::{collections::BTreeMap, path::Path};
+
+fn sample_dir() -> &'static Path {
+    Path::new(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/tests/samples/schema-1"
+    ))
+}
+
+fn sample_text() -> String {
+    std::fs::read_to_string(sample_dir().join(MANIFEST)).unwrap()
+}
+
+fn refused(text: &str) -> String {
+    Manifest::parse(text).expect_err("should be refused")
+}
+
+#[test]
+fn reads_every_key_of_schema_1() {
+    let m = Manifest::parse(&sample_text()).unwrap();
+    assert_eq!(
+        (
+            m.id.as_str(),
+            m.name.as_str(),
+            m.version.as_str(),
+            m.api.as_str()
+        ),
+        ("sample_pack", "Sample Pack", "1.0.0", "0.1")
+    );
+    assert_eq!(m.authors, ["Horizon"]);
+    assert_eq!(m.license.as_deref(), Some("MIT"));
+    assert_eq!(m.sky.as_ref().unwrap().file, "sky.wgsl");
+    assert_eq!(
+        m.material.as_ref().unwrap().name.as_deref(),
+        Some("Terrain")
+    );
+    let post: Vec<_> = m.post.iter().map(|s| s.file.as_str()).collect();
+    assert_eq!(post, ["post/grade.wgsl", "post/vignette.wgsl"]);
+    assert_eq!(
+        m.files(),
+        [
+            "common.wgsl",
+            "sky.wgsl",
+            "material.wgsl",
+            "post/grade.wgsl",
+            "post/vignette.wgsl"
+        ]
+    );
+    let kinds: Vec<_> = m.options.iter().map(|o| (o.id.as_str(), &o.kind)).collect();
+    assert_eq!(
+        kinds,
+        [
+            (
+                "saturation",
+                &OptionKind::Float {
+                    default: 1.1,
+                    min: 0.0,
+                    max: 2.0,
+                    step: 0.05
+                }
+            ),
+            ("vignette", &OptionKind::Bool { default: true }),
+            (
+                "samples",
+                &OptionKind::Int {
+                    default: 4,
+                    min: 1,
+                    max: 16
+                }
+            ),
+            (
+                "tonemap",
+                &OptionKind::Choice {
+                    values: vec!["None".into(), "Soft".into(), "Filmic".into()],
+                    default: 1
+                }
+            ),
+        ]
+    );
+    let types: Vec<_> = m.options.iter().map(|o| o.kind.wgsl_type()).collect();
+    assert_eq!(types, ["f32", "bool", "i32", "u32"]);
+    let constants: Vec<_> = m
+        .options
+        .iter()
+        .map(|o| o.kind.default_constant())
+        .collect();
+    assert_eq!(constants, [f64::from(1.1f32), 1.0, 4.0, 1.0]);
+    assert_eq!(m.budget.gpu_ms, Some(1.5));
+}
+
+#[test]
+fn the_smallest_manifest() {
+    let m = Manifest::parse(
+        "schema = 1\nid = \"p\"\nname = \"P\"\nversion = \"1\"\napi = \"0.1\"\n[[post]]\nfile = \"a.wgsl\"\n",
+    )
+    .unwrap();
+    assert!(m.sky.is_none() && m.options.is_empty() && m.budget.gpu_ms.is_none());
+}
+
+#[test]
+fn refuses_what_this_build_does_not_read() {
+    let text = sample_text();
+    let cases = [
+        (text.replace("schema = 1", "schema = 2"), "schema 2"),
+        (
+            text.replace("api = \"0.1\"", "api = \"0.2\""),
+            "shader API 0.2",
+        ),
+        (
+            text.replace("\"sample_pack\"", "\"Sample\""),
+            "is not [a-z0-9_]",
+        ),
+        (
+            text.replace("license = \"MIT\"", "licence = \"MIT\""),
+            "unknown field",
+        ),
+        (
+            text.replace("gpu_ms = 1.5", "gpu_ms = 40.0"),
+            "budget.gpu_ms",
+        ),
+        (
+            text.replace("\"common.wgsl\"", "\"../common.wgsl\""),
+            "not a plain path",
+        ),
+        (
+            text.replace("\"sky.wgsl\"", "\"sky.glsl\""),
+            "not a plain path to a .wgsl",
+        ),
+        (
+            text.replace("id = \"samples\"", "id = \"vignette\""),
+            "declared twice",
+        ),
+        (
+            text.replace("id = \"samples\"", "id = \"horizon_samples\""),
+            "WGSL identifier",
+        ),
+        (
+            text.replace("default = \"Soft\"", "default = \"Hard\""),
+            "one of the values",
+        ),
+        (
+            text.replace("default = 1.1", "default = 3.0"),
+            "default in [0, 2]",
+        ),
+        (
+            text.replace("default = 4", "default = 4.5"),
+            "not a 32-bit integer",
+        ),
+        (
+            text.replace("type = \"bool\"", "type = \"color\""),
+            "is not bool",
+        ),
+        (
+            text.replace("default = true", "default = true\nmin = 0"),
+            "doesn't apply",
+        ),
+    ];
+    for (text, needle) in cases {
+        let e = refused(&text);
+        assert!(e.contains(needle), "{needle:?} not in {e:?}");
+        assert!(e.starts_with(MANIFEST), "{e}");
+    }
+    let no_stage = "schema = 1\nid = \"p\"\nname = \"P\"\nversion = \"1\"\napi = \"0.1\"\n";
+    assert!(refused(no_stage).contains("no stage"));
+    let many = (0..9).map(|i| format!("[[post]]\nfile = \"p{i}.wgsl\"\n"));
+    assert!(refused(&format!("{no_stage}{}", many.collect::<String>())).contains("9 post passes"));
+}
+
+#[test]
+fn reads_the_sample_folder_and_its_package_alike() {
+    let folder = Pack::read(sample_dir()).unwrap();
+    assert_eq!(folder.files.len(), 7);
+    assert!(
+        folder
+            .source("post/grade.wgsl")
+            .unwrap()
+            .contains("fn post")
+    );
+    let bytes = folder.package().unwrap();
+    assert_eq!(
+        bytes,
+        folder.package().unwrap(),
+        "packaging is reproducible"
+    );
+    let dir = std::env::temp_dir().join(format!("horizon-shader-api-{}", std::process::id()));
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("sample_pack.hshader");
+    std::fs::write(&path, &bytes).unwrap();
+    let packaged = Pack::read(&path).unwrap();
+    std::fs::remove_dir_all(&dir).unwrap();
+    assert_eq!(packaged.files, folder.files);
+    assert_eq!(packaged.manifest, folder.manifest);
+}
+
+#[test]
+fn refuses_files_a_pack_does_not_use() {
+    let base = || -> BTreeMap<String, Vec<u8>> { Pack::read(sample_dir()).unwrap().files };
+    let mut files = base();
+    files.insert("old.wgsl".into(), b"fn f() {}".to_vec());
+    assert!(
+        Pack::from_files(files)
+            .unwrap_err()
+            .contains("old.wgsl is not used")
+    );
+    let mut files = base();
+    files.insert("run.sh".into(), Vec::new());
+    assert!(
+        Pack::from_files(files)
+            .unwrap_err()
+            .contains("run.sh: a pack holds only")
+    );
+    let mut files = base();
+    files.remove("sky.wgsl");
+    assert!(
+        Pack::from_files(files)
+            .unwrap_err()
+            .contains("sky.wgsl: named in")
+    );
+    let mut files = base();
+    files.insert("sky.wgsl".into(), vec![0xff, 0xfe]);
+    assert!(Pack::from_files(files).unwrap_err().contains("not UTF-8"));
+    let mut files = base();
+    files.insert("post/grade.wgsl".into(), vec![b' '; 300 << 10]);
+    assert!(
+        Pack::from_files(files)
+            .unwrap_err()
+            .contains("over 256 KiB")
+    );
+    let mut files = base();
+    files.remove(MANIFEST);
+    assert!(
+        Pack::from_files(files)
+            .unwrap_err()
+            .contains("missing at the pack's root")
+    );
+}
diff --git a/docs/api/shaders.md b/docs/api/shaders.md
index 10d1ae3de..82b9acced 100644
--- a/docs/api/shaders.md
+++ b/docs/api/shaders.md
@@ -34,6 +34,49 @@ how the world is fed to the GPU.
   benchmark ([benchmark-report.md](../benchmark-report.md)) records the pack and its cost, so "fast" stays measured.
 - **Off by default.** Without a pack the renderer is vanilla's look, and no pack code runs.
 
+## The pack format (schema 1)
+
+A pack is a folder, or the same files zipped as a `.hshader`, with `horizon-shaders.toml` at its root
+(crate `horizon-shader-api`; the sample with every key is
+`crates/horizon-shader-api/tests/samples/schema-1/`):
+
+```toml
+schema = 1                 # the manifest's format; a reader refuses schemas newer than it knows
+id = "soft_light"          # [a-z0-9_]{1,64}: the settings key and the registry id
+name = "Soft Light"
+version = "1.0.0"
+api = "0.1"                # the shader API line the WGSL is written for
+description = "..."        # optional, like authors and license
+shared = ["common.wgsl"]   # optional: WGSL put before every stage's file, in order
+
+[sky]                      # each stage is optional, but a pack has at least one
+file = "sky.wgsl"
+
+[material]
+file = "material.wgsl"
+
+[[post]]                   # full-screen passes, in the order they run (8 at most)
+file = "post/grade.wgsl"
+name = "Colour grade"      # optional: the GPU time overlay's label
+
+[[options]]                # 64 at most; `id` is the WGSL `override` it sets
+id = "saturation"
+name = "Saturation"
+type = "float"             # bool, float (min, max, step), int (min, max), choice (values)
+default = 1.1
+min = 0.0
+max = 2.0
+step = 0.05
+
+[budget]
+gpu_ms = 1.5               # optional: the GPU time the pack aims to add (0 to 16 ms)
+```
+
+An option's `override` has the type of its kind: `bool`, `f32`, `i32`, or `u32` for a choice (the index of the
+value). The pack holds only the manifest, the `.wgsl` files it names (each used, UTF-8, 256 KiB at most),
+`README.md`, `LICENSE` (`.md`, `.txt`) and `icon.png`, under plain paths, 8 MiB in all. A `.hshader` is built
+the same way every time (files in path order, fixed dates), so a pack's SHA-256 depends only on its files.
+
 ## Guide, reference and examples
 
 None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack
@@ -46,9 +89,10 @@ pack exist ([stability.md](stability.md)).
 
 ## Not there yet
 
-Everything on this page. The order: the renderer hooks shared with the format loader, then the material and post
+The stages and everything that runs a pack (the format above is read and checked). The order: the renderer hooks shared with the format loader, then the material and post
 stages with options and hot reload, then the overlay, lighting, sky and shadow stages.
 
 ## Changelog
 
+- 2026-10-25: the pack format, schema 1: `horizon-shaders.toml` and the `.hshader` package.
 - 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.

From 608d1a70a74f80abd392fe458ab36d7ae42b0d67 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:27:43 +0100
Subject: [PATCH 086/270] Horizon shader packs: the stages of API 0.1 and their
 generated reference

Three stages, each a WGSL function with a fixed signature that Horizon calls
inside its own pass: sky (fn sky(input: SkyInput) -> vec4<f32>), material
(fn material(input: MaterialInput) -> Surface) and post (fn post(input:
PostInput) -> vec4<f32>). A stage's WGSL is a generated prelude (the frame
uniform, the stage's structs, its resources in bind group 3, the post
helpers), the pack's shared files, its own file, then the entry points; each
part is located so errors point at the pack's file and line.

The frame is the Rust struct the renderer will upload; its WGSL, its offsets
and docs/api/shaders-reference.md are generated from it, and tests check that
the preludes compile, that naga's layout of the WGSL is the Rust layout, that
the sample pack's stages compile, and that the reference is up to date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                                    |   2 +
 crates/horizon-shader-api/Cargo.toml          |   4 +
 crates/horizon-shader-api/src/inputs.rs       | 218 ++++++++++++++
 crates/horizon-shader-api/src/lib.rs          |   5 +
 crates/horizon-shader-api/src/package.rs      |   4 +-
 crates/horizon-shader-api/src/reference.rs    |  88 ++++++
 crates/horizon-shader-api/src/stages.rs       | 265 ++++++++++++++++++
 crates/horizon-shader-api/tests/reference.rs  | 119 ++++++++
 .../tests/samples/schema-1/README.md          |   2 +-
 .../tests/samples/schema-1/material.wgsl      |   3 +-
 docs/api/shaders-reference.md                 | 152 ++++++++++
 docs/api/shaders.md                           |   6 +-
 12 files changed, 862 insertions(+), 6 deletions(-)
 create mode 100644 crates/horizon-shader-api/src/inputs.rs
 create mode 100644 crates/horizon-shader-api/src/reference.rs
 create mode 100644 crates/horizon-shader-api/src/stages.rs
 create mode 100644 crates/horizon-shader-api/tests/reference.rs
 create mode 100644 docs/api/shaders-reference.md

diff --git a/Cargo.lock b/Cargo.lock
index 25b278069..7586c5d11 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1441,6 +1441,8 @@ dependencies = [
 name = "horizon-shader-api"
 version = "0.1.0"
 dependencies = [
+ "bytemuck",
+ "naga",
  "serde",
  "toml",
  "zip",
diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml
index 5d9098055..249019042 100644
--- a/crates/horizon-shader-api/Cargo.toml
+++ b/crates/horizon-shader-api/Cargo.toml
@@ -7,9 +7,13 @@ rust-version = "1.85"
 description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-shaders.toml, the .hshader package"
 
 [dependencies]
+bytemuck = { version = "1.24", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 toml = "1.1.6"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 
+[dev-dependencies]
+naga = { version = "30.0.1", features = ["wgsl-in"] }
+
 [lints]
 workspace = true
diff --git a/crates/horizon-shader-api/src/inputs.rs b/crates/horizon-shader-api/src/inputs.rs
new file mode 100644
index 000000000..5bc82fd82
--- /dev/null
+++ b/crates/horizon-shader-api/src/inputs.rs
@@ -0,0 +1,218 @@
+//! What a pack's WGSL reads: the frame uniform every stage sees, which the
+//! renderer fills and uploads as the Rust struct below, and the stage input
+//! and output structs. The WGSL of each is generated from these definitions
+//! (`Struct::wgsl`), and so is the reference (docs/api/shaders-reference.md).
+
+/// One field of a WGSL struct, for the prelude and the reference.
+#[derive(Debug)]
+pub struct Field {
+    pub name: &'static str,
+    pub ty: &'static str,
+    /// Its meaning, unit and range.
+    pub doc: &'static str,
+}
+
+/// A struct a pack's WGSL can name.
+#[derive(Debug)]
+pub struct Struct {
+    pub name: &'static str,
+    pub doc: &'static str,
+    pub fields: &'static [Field],
+}
+
+impl Struct {
+    pub fn wgsl(&self) -> String {
+        let mut out = format!("struct {} {{\n", self.name);
+        for f in self.fields {
+            out += &format!("    {}: {},\n", f.name, f.ty);
+        }
+        out + "}\n"
+    }
+}
+
+/// The WGSL type of a Rust field the renderer uploads.
+pub trait Wgsl {
+    const TYPE: &'static str;
+}
+
+macro_rules! wgsl_types {
+    ($($rust:ty => $wgsl:literal),* $(,)?) => {
+        $(impl Wgsl for $rust {
+            const TYPE: &'static str = $wgsl;
+        })*
+    };
+}
+
+wgsl_types! {
+    f32 => "f32",
+    u32 => "u32",
+    i32 => "i32",
+    [f32; 2] => "vec2<f32>",
+    [f32; 3] => "vec3<f32>",
+    [f32; 4] => "vec4<f32>",
+    [[f32; 4]; 4] => "mat4x4<f32>",
+}
+
+/// A uniform struct: the Rust type the renderer uploads, and its WGSL.
+macro_rules! uniform {
+    ($(#[doc = $doc:literal])* $name:ident {
+        $($(#[doc = $fdoc:literal])* $field:ident: $ty:ty,)*
+    }) => {
+        $(#[doc = $doc])*
+        #[repr(C)]
+        #[derive(Clone, Copy, Debug, Default, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
+        pub struct $name {
+            $($(#[doc = $fdoc])* pub $field: $ty,)*
+        }
+
+        impl $name {
+            pub const WGSL: Struct = Struct {
+                name: stringify!($name),
+                doc: concat!($($doc, "\n"),*),
+                fields: &[$(Field {
+                    name: stringify!($field),
+                    ty: <$ty as Wgsl>::TYPE,
+                    doc: concat!($($fdoc),*),
+                }),*],
+            };
+            /// Each field's byte offset, in `WGSL.fields`' order.
+            pub const OFFSETS: &'static [usize] = &[$(std::mem::offset_of!($name, $field)),*];
+        }
+    };
+}
+
+uniform! {
+    /// The frame, as `frame` in every stage. Positions and directions are
+    /// in world axes relative to the camera (x east, y up, z south), so they
+    /// stay precise far from the world's origin; depth is reversed (1 near,
+    /// 0 at the far plane and in the sky).
+    Frame {
+        /// Camera-relative world to view space: the camera's rotation.
+        view: [[f32; 4]; 4],
+        /// View to clip space (reversed depth, wgpu's clip space: z 0..1).
+        projection: [[f32; 4]; 4],
+        /// View to camera-relative world space.
+        view_inverse: [[f32; 4]; 4],
+        /// Clip to view space.
+        projection_inverse: [[f32; 4]; 4],
+        /// The camera's world position, in blocks (about a millimetre of precision 10 000 blocks out).
+        camera_position: [f32; 3],
+        /// Seconds since the pack was loaded, wrapping to 0 every hour.
+        time: f32,
+        /// Unit vector toward the sun (below the horizon at night).
+        sun_direction: [f32; 3],
+        /// The time of day, 0..1: 0 sunrise, 0.25 noon, 0.5 sunset, 0.75 midnight.
+        day_time: f32,
+        /// Unit vector toward the moon.
+        moon_direction: [f32; 3],
+        /// Vanilla's GameTime: (game time % 24000 + partial tick) / 24000, 0..1.
+        game_time: f32,
+        /// Vanilla's sky colour this frame, 0..1.
+        sky_color: [f32; 3],
+        /// Rain strength, 0..1.
+        rain: f32,
+        /// Vanilla's fog colour this frame (also the clear colour), 0..1.
+        fog_color: [f32; 3],
+        /// Thunder strength, 0..1.
+        thunder: f32,
+        /// The size of the world's picture, in pixels (the resolution scale applied).
+        resolution: [f32; 2],
+        /// Block and sky light at the camera, 0..1 (level / 15).
+        eye_light: [f32; 2],
+        /// Where vanilla's fog starts, in blocks from the camera.
+        fog_start: f32,
+        /// Where vanilla's fog is full, in blocks.
+        fog_end: f32,
+        /// The render distance, in blocks.
+        render_distance: f32,
+        /// The far plane, in blocks.
+        far: f32,
+        /// Night vision strength, 0..1.
+        night_vision: f32,
+        /// Blindness strength, 0..1.
+        blindness: f32,
+        /// The darkness effect's strength, 0..1.
+        darkness: f32,
+        /// The Brightness option, 0..1 (Moody to Bright).
+        brightness: f32,
+        /// What the camera is in: 0 air, 1 water, 2 lava, 3 powder snow.
+        eye_in: u32,
+        /// 0 the Overworld, -1 the Nether, 1 the End, 2 any other dimension.
+        dimension: i32,
+        /// Frames drawn since the pack was loaded (wraps).
+        frame_index: u32,
+        /// 1 while F1 hides the HUD, else 0.
+        hide_gui: u32,
+    }
+}
+
+macro_rules! fields {
+    ($($name:ident: $ty:literal = $doc:literal,)*) => {
+        &[$(Field { name: stringify!($name), ty: $ty, doc: $doc }),*]
+    };
+}
+
+/// The post stage's input: one pixel of the picture.
+pub const POST_INPUT: Struct = Struct {
+    name: "PostInput",
+    doc: "One pixel of the picture, for `fn post(input: PostInput) -> vec4<f32>`.",
+    fields: fields! {
+        uv: "vec2<f32>" = "Where the pixel is, 0..1 from the top left.",
+        pixel: "vec2<f32>" = "The pixel's centre, in pixels from the top left.",
+        color: "vec4<f32>" = "The previous pass's colour here (the world's picture for the first pass).",
+        depth: "f32" = "The world's depth here, reversed: 0 is the sky.",
+    },
+};
+
+/// The material stage's input: one point of a block's surface.
+pub const MATERIAL_INPUT: Struct = Struct {
+    name: "MaterialInput",
+    doc: "One point of a block's surface, for `fn material(input: MaterialInput) -> Surface`.",
+    fields: fields! {
+        albedo: "vec4<f32>" = "The block texture's colour here (alpha 0..1).",
+        tint: "vec4<f32>" = "The vertex colour: biome tint, face shade and ambient occlusion.",
+        light: "vec2<f32>" = "Block and sky light, 0..1, smoothed over the face.",
+        lightmap: "vec3<f32>" = "Vanilla's light colour for that light this frame.",
+        position: "vec3<f32>" = "The point, camera-relative, in blocks.",
+        uv: "vec2<f32>" = "The texture coordinate inside the block atlas.",
+        translucent: "bool" = "Drawn in the translucent pass (water, stained glass, ice).",
+    },
+};
+
+/// What the material stage returns.
+pub const SURFACE: Struct = Struct {
+    name: "Surface",
+    doc: "What `material` returns. Vanilla's own is `albedo * tint * vec4(lightmap, 1.0)`; \
+          Horizon then applies the alpha test (cutout and translucent) and fog.",
+    fields: fields! {
+        color: "vec4<f32>" = "The lit colour, 0..1, with its alpha.",
+    },
+};
+
+/// The sky stage's input: one direction of the sky.
+pub const SKY_INPUT: Struct = Struct {
+    name: "SkyInput",
+    doc: "One direction of the sky, for `fn sky(input: SkyInput) -> vec4<f32>`. The sun, moon, \
+          stars and clouds are drawn over the result.",
+    fields: fields! {
+        direction: "vec3<f32>" = "Unit view ray, camera-relative world axes.",
+        color: "vec4<f32>" = "Vanilla's sky colour along the ray (sky, fog and sunrise).",
+    },
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn frame_fields_carry_their_docs() {
+        let wgsl = Frame::WGSL;
+        assert_eq!(wgsl.fields.len(), 28);
+        assert!(wgsl.fields.iter().all(|f| !f.doc.trim().is_empty()));
+        assert_eq!(std::mem::size_of::<Frame>(), 4 * 64 + 9 * 16);
+        assert!(
+            wgsl.wgsl()
+                .contains("    camera_position: vec3<f32>,\n    time: f32,\n")
+        );
+    }
+}
diff --git a/crates/horizon-shader-api/src/lib.rs b/crates/horizon-shader-api/src/lib.rs
index 418563089..1d85e7a5e 100644
--- a/crates/horizon-shader-api/src/lib.rs
+++ b/crates/horizon-shader-api/src/lib.rs
@@ -3,8 +3,13 @@
 //! a folder or a `.hshader`. This crate reads and checks packs; the game, the
 //! launcher and the registry all use it, so a pack is judged the same way
 //! everywhere.
+pub mod inputs;
 pub mod manifest;
 pub mod package;
+pub mod reference;
+pub mod stages;
 
+pub use inputs::Frame;
 pub use manifest::{API, MANIFEST, Manifest, OptionKind, PackOption, SCHEMA, Stage};
 pub use package::{EXTENSION, Pack};
+pub use stages::{Composed, StageKind, compose};
diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs
index af72afc4c..d95e8d321 100644
--- a/crates/horizon-shader-api/src/package.rs
+++ b/crates/horizon-shader-api/src/package.rs
@@ -11,9 +11,9 @@ use std::{
 /// A packaged pack's extension.
 pub const EXTENSION: &str = "hshader";
 /// Bytes per WGSL file, per other file, and in all.
-const MAX_WGSL: u64 = 256 << 10;
+pub const MAX_WGSL: u64 = 256 << 10;
 const MAX_OTHER: u64 = 1 << 20;
-const MAX_TOTAL: u64 = 8 << 20;
+pub const MAX_TOTAL: u64 = 8 << 20;
 /// Files in a `.hshader`.
 const MAX_ENTRIES: usize = 512;
 /// Files a pack may hold beside its manifest and WGSL.
diff --git a/crates/horizon-shader-api/src/reference.rs b/crates/horizon-shader-api/src/reference.rs
new file mode 100644
index 000000000..9847ccf90
--- /dev/null
+++ b/crates/horizon-shader-api/src/reference.rs
@@ -0,0 +1,88 @@
+//! docs/api/shaders-reference.md, generated from the stages and inputs this
+//! crate defines (`tests/reference.rs` fails when the file drifts).
+use crate::inputs::{Frame, SURFACE, Struct};
+use crate::manifest::{API, MAX_GPU_MS, MAX_OPTIONS, MAX_POST_PASSES};
+use crate::package::{MAX_TOTAL, MAX_WGSL};
+use crate::stages::{GROUP, StageKind};
+
+fn table(s: &Struct, offsets: Option<&[usize]>) -> String {
+    let mut out = format!("### `{}`\n\n{}\n\n", s.name, one_line(s.doc));
+    out += if offsets.is_some() {
+        "| Field | Type | Offset | Meaning |\n| --- | --- | --- | --- |\n"
+    } else {
+        "| Field | Type | Meaning |\n| --- | --- | --- |\n"
+    };
+    for (i, f) in s.fields.iter().enumerate() {
+        let offset = offsets.map_or(String::new(), |o| format!(" {} |", o[i]));
+        out += &format!(
+            "| `{}` | `{}` |{offset} {} |\n",
+            f.name,
+            f.ty,
+            one_line(f.doc)
+        );
+    }
+    out + "\n"
+}
+
+fn one_line(doc: &str) -> String {
+    doc.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+pub fn markdown() -> String {
+    let mut out = format!(
+        "# Shader API reference ({API})\n\n\
+         Generated from `crates/horizon-shader-api` (`HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`\n\
+         rewrites it; the test fails when it drifts). The API's design and pack format: [shaders.md](shaders.md).\n\n\
+         A stage is a function your WGSL defines, with the signature below; Horizon puts the prelude (these structs, the\n\
+         resources and helpers) before your files and calls the function from its own pass. Your files declare no\n\
+         bindings and no entry points, and no names starting with `horizon_`.\n\n\
+         ## Stages\n\n\
+         | Stage | In `horizon-shaders.toml` | Your function |\n| --- | --- | --- |\n"
+    );
+    for kind in StageKind::ALL {
+        let key = match kind {
+            StageKind::Post => "[[post]]",
+            StageKind::Sky => "[sky]",
+            StageKind::Material => "[material]",
+        };
+        out += &format!("| {} | `{key}` | `{}` |\n", kind.name(), kind.signature());
+    }
+    out += "\n";
+    for kind in StageKind::ALL {
+        out += &format!("## {}\n\n`{}`\n\n", kind.name(), kind.signature());
+        out += &table(kind.input(), None);
+        if kind == StageKind::Material {
+            out += &table(&SURFACE, None);
+        }
+        out += &format!(
+            "Resources (bind group {GROUP}):\n\n| Binding | Declaration | Meaning |\n| --- | --- | --- |\n"
+        );
+        for r in kind.resources() {
+            out += &format!("| {} | `{}` | {} |\n", r.binding, r.ty, r.doc);
+        }
+        out += "\n";
+        if kind == StageKind::Post {
+            out += "Helpers:\n\n\
+                    - `fn depth_at(uv: vec2<f32>) -> f32`: the world's depth at `uv`.\n\
+                    - `fn view_position(uv: vec2<f32>, depth: f32) -> vec3<f32>`: the camera-relative position, in blocks, of\n  \
+                    the point at `uv` and `depth`.\n\n";
+        }
+    }
+    out += "## The frame\n\n";
+    out += &table(&Frame::WGSL, Some(Frame::OFFSETS));
+    out += &format!(
+        "## Options\n\n\
+         Each `[[options]]` entry sets the WGSL `override` of the same name when the pipelines are built:\n\n\
+         | `type` | Keys | The `override` |\n| --- | --- | --- |\n\
+         | `bool` | `default` | `override <id>: bool` |\n\
+         | `float` | `default`, `min`, `max`, `step` | `override <id>: f32` |\n\
+         | `int` | `default`, `min`, `max` | `override <id>: i32` |\n\
+         | `choice` | `values`, `default` (one of them) | `override <id>: u32`, the value's index |\n\n\
+         ## Limits\n\n\
+         - {MAX_POST_PASSES} post passes, {MAX_OPTIONS} options, `budget.gpu_ms` up to {MAX_GPU_MS}.\n\
+         - {} KiB per WGSL file, {} MiB per pack.\n",
+        MAX_WGSL >> 10,
+        MAX_TOTAL >> 20
+    );
+    out
+}
diff --git a/crates/horizon-shader-api/src/stages.rs b/crates/horizon-shader-api/src/stages.rs
new file mode 100644
index 000000000..12bd3e038
--- /dev/null
+++ b/crates/horizon-shader-api/src/stages.rs
@@ -0,0 +1,265 @@
+//! The stages a pack can fill, each a WGSL function with a fixed signature
+//! that Horizon calls inside its own passes, and the WGSL put around a
+//! pack's files to build a stage: the prelude before (the inputs and the
+//! resources), the entry points after.
+use crate::inputs::{Frame, MATERIAL_INPUT, POST_INPUT, SKY_INPUT, SURFACE, Struct};
+use crate::package::Pack;
+
+/// The bind group of a pack's resources; groups 0 to 2 are the renderer's.
+pub const GROUP: u32 = 3;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StageKind {
+    /// The sky's colour along each view ray, before the sun, moon and stars.
+    Sky,
+    /// The colour of block surfaces (terrain), before the alpha test and fog.
+    Material,
+    /// A full-screen pass over the world's picture, under the hand and HUD.
+    Post,
+}
+
+/// A resource a stage reads, declared by its prelude.
+#[derive(Debug)]
+pub struct Resource {
+    pub binding: u32,
+    pub name: &'static str,
+    pub ty: &'static str,
+    pub doc: &'static str,
+}
+
+const FRAME: Resource = Resource {
+    binding: 0,
+    name: "frame",
+    ty: "var<uniform> frame: Frame",
+    doc: "The frame (`Frame`).",
+};
+
+const POST_RESOURCES: [Resource; 6] = [
+    FRAME,
+    Resource {
+        binding: 1,
+        name: "scene_color",
+        ty: "var scene_color: texture_2d<f32>",
+        doc: "The world's picture before any pass.",
+    },
+    Resource {
+        binding: 2,
+        name: "scene_depth",
+        ty: "var scene_depth: texture_depth_2d",
+        doc: "The world's depth, reversed (1 near, 0 far and sky).",
+    },
+    Resource {
+        binding: 3,
+        name: "previous",
+        ty: "var previous: texture_2d<f32>",
+        doc: "The previous pass's output (`scene_color` for the first pass).",
+    },
+    Resource {
+        binding: 4,
+        name: "linear_sampler",
+        ty: "var linear_sampler: sampler",
+        doc: "Bilinear filtering, clamped to the edges.",
+    },
+    Resource {
+        binding: 5,
+        name: "nearest_sampler",
+        ty: "var nearest_sampler: sampler",
+        doc: "Nearest texel, clamped to the edges.",
+    },
+];
+
+/// Functions the post prelude gives packs.
+const POST_HELPERS: &str = "\
+// The world's depth at `uv` (reversed: 0 is the sky).
+fn depth_at(uv: vec2<f32>) -> f32 {
+    let size = vec2<f32>(textureDimensions(scene_depth));
+    let texel = vec2<i32>(clamp(uv * size, vec2<f32>(0.0), size - 1.0));
+    return textureLoad(scene_depth, texel, 0);
+}
+// The camera-relative world position, in blocks, of the point at `uv` and `depth`.
+fn view_position(uv: vec2<f32>, depth: f32) -> vec3<f32> {
+    let clip = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth, 1.0);
+    let view = frame.projection_inverse * clip;
+    return (frame.view_inverse * vec4<f32>(view.xyz / view.w, 0.0)).xyz;
+}
+";
+
+/// The post stage's entry points, as the renderer builds them: a full-screen
+/// triangle, and a fragment that calls the pack's `post` for each pixel.
+const POST_ENTRIES: &str = "\
+struct HorizonPostOut {
+    @builtin(position) position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+}
+@vertex fn horizon_vs_post(@builtin(vertex_index) i: u32) -> HorizonPostOut {
+    let p = vec2<f32>(f32((i << 1u) & 2u), f32(i & 2u));
+    var out: HorizonPostOut;
+    out.position = vec4<f32>(p * 2.0 - 1.0, 0.0, 1.0);
+    out.uv = vec2<f32>(p.x, 1.0 - p.y);
+    return out;
+}
+@fragment fn horizon_fs_post(in: HorizonPostOut) -> @location(0) vec4<f32> {
+    let color = textureSampleLevel(previous, linear_sampler, in.uv, 0.0);
+    return post(PostInput(in.uv, in.position.xy, color, depth_at(in.uv)));
+}
+";
+
+/// Entry points with the material stage's inputs: the renderer calls
+/// `material` from its own terrain shader in the same way.
+const MATERIAL_ENTRIES: &str = "\
+struct HorizonMaterialIn {
+    @builtin(position) position: vec4<f32>,
+    @location(0) albedo: vec4<f32>,
+    @location(1) tint: vec4<f32>,
+    @location(2) light: vec2<f32>,
+    @location(3) lightmap: vec3<f32>,
+    @location(4) world: vec3<f32>,
+    @location(5) uv: vec2<f32>,
+    @location(6) @interpolate(flat) translucent: u32,
+}
+@fragment fn horizon_fs_material(in: HorizonMaterialIn) -> @location(0) vec4<f32> {
+    let input = MaterialInput(in.albedo, in.tint, in.light, in.lightmap, in.world, in.uv, in.translucent != 0u);
+    return material(input).color;
+}
+";
+
+/// Entry points with the sky stage's inputs: the renderer calls `sky` from
+/// its own sky shader in the same way.
+const SKY_ENTRIES: &str = "\
+struct HorizonSkyIn {
+    @builtin(position) position: vec4<f32>,
+    @location(0) direction: vec3<f32>,
+    @location(1) color: vec4<f32>,
+}
+@fragment fn horizon_fs_sky(in: HorizonSkyIn) -> @location(0) vec4<f32> {
+    return sky(SkyInput(normalize(in.direction), in.color));
+}
+";
+
+impl StageKind {
+    pub const ALL: [StageKind; 3] = [StageKind::Sky, StageKind::Material, StageKind::Post];
+
+    /// The manifest's name for the stage (`[sky]`, `[material]`, `[[post]]`).
+    pub fn name(self) -> &'static str {
+        match self {
+            StageKind::Sky => "sky",
+            StageKind::Material => "material",
+            StageKind::Post => "post",
+        }
+    }
+
+    /// The function a pack defines: it has the stage's name.
+    pub fn function(self) -> &'static str {
+        self.name()
+    }
+
+    pub fn input(self) -> &'static Struct {
+        match self {
+            StageKind::Sky => &SKY_INPUT,
+            StageKind::Material => &MATERIAL_INPUT,
+            StageKind::Post => &POST_INPUT,
+        }
+    }
+
+    /// The type the function returns.
+    pub fn output(self) -> &'static str {
+        match self {
+            StageKind::Material => SURFACE.name,
+            StageKind::Sky | StageKind::Post => "vec4<f32>",
+        }
+    }
+
+    /// `fn <name>(input: <Input>) -> <Output>`.
+    pub fn signature(self) -> String {
+        format!(
+            "fn {}(input: {}) -> {}",
+            self.function(),
+            self.input().name,
+            self.output()
+        )
+    }
+
+    pub fn resources(self) -> &'static [Resource] {
+        match self {
+            StageKind::Post => &POST_RESOURCES,
+            StageKind::Sky | StageKind::Material => std::slice::from_ref(&FRAME),
+        }
+    }
+
+    /// Everything the pack's files may use, declared before them.
+    pub fn prelude(self) -> String {
+        let mut out =
+            String::from("// Horizon shader API prelude (docs/api/shaders-reference.md)\n");
+        out += &Frame::WGSL.wgsl();
+        out += &self.input().wgsl();
+        if self == StageKind::Material {
+            out += &SURFACE.wgsl();
+        }
+        for r in self.resources() {
+            out += &format!("@group({GROUP}) @binding({}) {};\n", r.binding, r.ty);
+        }
+        if self == StageKind::Post {
+            out += POST_HELPERS;
+        }
+        out
+    }
+
+    /// The entry points put after the pack's files.
+    pub fn entries(self) -> &'static str {
+        match self {
+            StageKind::Sky => SKY_ENTRIES,
+            StageKind::Material => MATERIAL_ENTRIES,
+            StageKind::Post => POST_ENTRIES,
+        }
+    }
+}
+
+/// A stage's WGSL, and where each part of it came from.
+#[derive(Debug)]
+pub struct Composed {
+    pub text: String,
+    /// (the file, or `<prelude>` / `<entries>`, its byte range in `text`).
+    pub parts: Vec<(String, std::ops::Range<usize>)>,
+}
+
+impl Composed {
+    /// The file, line and column (1-based) of a byte offset in `text`.
+    pub fn locate(&self, offset: usize) -> (&str, usize, usize) {
+        let (file, range) = self
+            .parts
+            .iter()
+            .find(|(_, r)| r.contains(&offset))
+            .or(self.parts.last())
+            .expect("a composed stage has parts");
+        let before = &self.text[range.start..offset.clamp(range.start, range.end)];
+        let line = before.matches('\n').count() + 1;
+        let column = before.len() - before.rfind('\n').map_or(0, |i| i + 1) + 1;
+        (file, line, column)
+    }
+}
+
+/// The WGSL of the stage `kind` whose own file is `file`: the prelude, the
+/// pack's shared files in order, the file, then the entry points.
+pub fn compose(pack: &Pack, kind: StageKind, file: &str) -> Composed {
+    let mut composed = Composed {
+        text: String::new(),
+        parts: Vec::new(),
+    };
+    let mut push = |name: &str, text: &str| {
+        let start = composed.text.len();
+        composed.text += text;
+        if !text.ends_with('\n') {
+            composed.text.push('\n');
+        }
+        composed
+            .parts
+            .push((name.to_owned(), start..composed.text.len()));
+    };
+    push("<prelude>", &kind.prelude());
+    for shared in pack.manifest.shared.iter().filter(|s| *s != file) {
+        push(shared, pack.source(shared).unwrap_or_default());
+    }
+    push(file, pack.source(file).unwrap_or_default());
+    push("<entries>", kind.entries());
+    composed
+}
diff --git a/crates/horizon-shader-api/tests/reference.rs b/crates/horizon-shader-api/tests/reference.rs
new file mode 100644
index 000000000..fc548590b
--- /dev/null
+++ b/crates/horizon-shader-api/tests/reference.rs
@@ -0,0 +1,119 @@
+//! The stages' WGSL against the Rust definitions: the preludes compile, the
+//! frame's WGSL layout is the uploaded struct's, and
+//! docs/api/shaders-reference.md is up to date. Rewrite the reference with
+//! `HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`.
+use horizon_shader_api::{Frame, Pack, StageKind, compose, reference};
+use std::path::Path;
+
+const DOC: &str = "docs/api/shaders-reference.md";
+
+fn root() -> &'static Path {
+    Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../.."))
+}
+
+fn validate(text: &str) -> naga::Module {
+    let module = naga::front::wgsl::parse_str(text)
+        .unwrap_or_else(|e| panic!("{}\n{text}", e.emit_to_string(text)));
+    naga::valid::Validator::new(
+        naga::valid::ValidationFlags::all(),
+        naga::valid::Capabilities::default(),
+    )
+    .validate(&module)
+    .unwrap_or_else(|e| panic!("{}\n{text}", e.emit_to_string(text)));
+    module
+}
+
+/// Vanilla's look, written as each stage.
+fn vanilla(kind: StageKind) -> &'static str {
+    match kind {
+        StageKind::Sky => "fn sky(input: SkyInput) -> vec4<f32> { return input.color; }\n",
+        StageKind::Material => {
+            "fn material(input: MaterialInput) -> Surface {\n    \
+             return Surface(input.albedo * input.tint * vec4<f32>(input.lightmap, 1.0));\n}\n"
+        }
+        StageKind::Post => "fn post(input: PostInput) -> vec4<f32> { return input.color; }\n",
+    }
+}
+
+#[test]
+fn every_stage_compiles_with_vanilla_s_function() {
+    for kind in StageKind::ALL {
+        let text = format!("{}{}{}", kind.prelude(), vanilla(kind), kind.entries());
+        let module = validate(&text);
+        assert!(
+            module
+                .entry_points
+                .iter()
+                .all(|e| e.name.starts_with("horizon_")),
+            "{kind:?}"
+        );
+    }
+}
+
+#[test]
+fn the_frame_s_wgsl_layout_is_the_uploaded_struct_s() {
+    let text = format!("{}{}", StageKind::Sky.prelude(), vanilla(StageKind::Sky));
+    let module = validate(&text);
+    let (_, ty) = module
+        .types
+        .iter()
+        .find(|(_, t)| t.name.as_deref() == Some("Frame"))
+        .expect("Frame in the prelude");
+    let naga::TypeInner::Struct { members, span } = &ty.inner else {
+        panic!("Frame is a struct")
+    };
+    assert_eq!(*span as usize, std::mem::size_of::<Frame>());
+    let wgsl: Vec<_> = members
+        .iter()
+        .map(|m| (m.name.clone().unwrap(), m.offset as usize))
+        .collect();
+    let rust: Vec<_> = Frame::WGSL
+        .fields
+        .iter()
+        .zip(Frame::OFFSETS)
+        .map(|(f, &o)| (f.name.to_owned(), o))
+        .collect();
+    assert_eq!(wgsl, rust);
+}
+
+#[test]
+fn the_sample_pack_s_stages_compile() {
+    let dir = root().join("crates/horizon-shader-api/tests/samples/schema-1");
+    let pack = Pack::read(&dir).unwrap();
+    let m = &pack.manifest;
+    let stages = [
+        (StageKind::Sky, m.sky.iter().collect::<Vec<_>>()),
+        (StageKind::Material, m.material.iter().collect()),
+        (StageKind::Post, m.post.iter().collect()),
+    ];
+    for (kind, list) in stages {
+        for stage in list {
+            let composed = compose(&pack, kind, &stage.file);
+            validate(&composed.text);
+            // Errors point into the pack's own file.
+            let part = composed.parts.iter().find(|(f, _)| *f == stage.file);
+            let part = part.unwrap().1.clone();
+            let needle = format!("fn {}(", kind.function());
+            let at = part.start + composed.text[part].find(&needle).unwrap();
+            let source = pack.source(&stage.file).unwrap();
+            let line = source.lines().position(|l| l.starts_with(&needle)).unwrap() + 1;
+            assert_eq!(composed.locate(at), (stage.file.as_str(), line, 1));
+        }
+    }
+}
+
+#[test]
+fn the_reference_is_up_to_date() {
+    let path = root().join(DOC);
+    let want = reference::markdown();
+    if std::env::var_os("HORIZON_WRITE_DOCS").is_some() {
+        std::fs::write(&path, &want).unwrap();
+    }
+    let have = std::fs::read_to_string(&path)
+        .unwrap_or_default()
+        .replace("\r\n", "\n");
+    assert!(
+        have == want,
+        "{DOC} is out of date: HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference"
+    );
+}
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/README.md b/crates/horizon-shader-api/tests/samples/schema-1/README.md
index 6762a7892..a8ad4583b 100644
--- a/crates/horizon-shader-api/tests/samples/schema-1/README.md
+++ b/crates/horizon-shader-api/tests/samples/schema-1/README.md
@@ -1 +1 @@
-The schema 1 sample read by `tests/schema.rs`. Its WGSL is checked once the stages exist.
+The schema 1 sample read by `tests/schema.rs`; `tests/reference.rs` compiles its stages.
diff --git a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
index 0ad42c6d9..830470a6b 100644
--- a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
+++ b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl
@@ -1,3 +1,4 @@
 fn material(input: MaterialInput) -> Surface {
-    return input.surface;
+    let lit = input.albedo * input.tint * vec4<f32>(input.lightmap, 1.0);
+    return Surface(vec4<f32>(lit.rgb * (0.9 + 0.1 * luminance(lit.rgb)), lit.a));
 }
diff --git a/docs/api/shaders-reference.md b/docs/api/shaders-reference.md
new file mode 100644
index 000000000..ed574978d
--- /dev/null
+++ b/docs/api/shaders-reference.md
@@ -0,0 +1,152 @@
+# Shader API reference (0.1)
+
+Generated from `crates/horizon-shader-api` (`HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`
+rewrites it; the test fails when it drifts). The API's design and pack format: [shaders.md](shaders.md).
+
+A stage is a function your WGSL defines, with the signature below; Horizon puts the prelude (these structs, the
+resources and helpers) before your files and calls the function from its own pass. Your files declare no
+bindings and no entry points, and no names starting with `horizon_`.
+
+## Stages
+
+| Stage | In `horizon-shaders.toml` | Your function |
+| --- | --- | --- |
+| sky | `[sky]` | `fn sky(input: SkyInput) -> vec4<f32>` |
+| material | `[material]` | `fn material(input: MaterialInput) -> Surface` |
+| post | `[[post]]` | `fn post(input: PostInput) -> vec4<f32>` |
+
+## sky
+
+`fn sky(input: SkyInput) -> vec4<f32>`
+
+### `SkyInput`
+
+One direction of the sky, for `fn sky(input: SkyInput) -> vec4<f32>`. The sun, moon, stars and clouds are drawn over the result.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `direction` | `vec3<f32>` | Unit view ray, camera-relative world axes. |
+| `color` | `vec4<f32>` | Vanilla's sky colour along the ray (sky, fog and sunrise). |
+
+Resources (bind group 3):
+
+| Binding | Declaration | Meaning |
+| --- | --- | --- |
+| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
+
+## material
+
+`fn material(input: MaterialInput) -> Surface`
+
+### `MaterialInput`
+
+One point of a block's surface, for `fn material(input: MaterialInput) -> Surface`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `albedo` | `vec4<f32>` | The block texture's colour here (alpha 0..1). |
+| `tint` | `vec4<f32>` | The vertex colour: biome tint, face shade and ambient occlusion. |
+| `light` | `vec2<f32>` | Block and sky light, 0..1, smoothed over the face. |
+| `lightmap` | `vec3<f32>` | Vanilla's light colour for that light this frame. |
+| `position` | `vec3<f32>` | The point, camera-relative, in blocks. |
+| `uv` | `vec2<f32>` | The texture coordinate inside the block atlas. |
+| `translucent` | `bool` | Drawn in the translucent pass (water, stained glass, ice). |
+
+### `Surface`
+
+What `material` returns. Vanilla's own is `albedo * tint * vec4(lightmap, 1.0)`; Horizon then applies the alpha test (cutout and translucent) and fog.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `color` | `vec4<f32>` | The lit colour, 0..1, with its alpha. |
+
+Resources (bind group 3):
+
+| Binding | Declaration | Meaning |
+| --- | --- | --- |
+| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
+
+## post
+
+`fn post(input: PostInput) -> vec4<f32>`
+
+### `PostInput`
+
+One pixel of the picture, for `fn post(input: PostInput) -> vec4<f32>`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `uv` | `vec2<f32>` | Where the pixel is, 0..1 from the top left. |
+| `pixel` | `vec2<f32>` | The pixel's centre, in pixels from the top left. |
+| `color` | `vec4<f32>` | The previous pass's colour here (the world's picture for the first pass). |
+| `depth` | `f32` | The world's depth here, reversed: 0 is the sky. |
+
+Resources (bind group 3):
+
+| Binding | Declaration | Meaning |
+| --- | --- | --- |
+| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
+| 1 | `var scene_color: texture_2d<f32>` | The world's picture before any pass. |
+| 2 | `var scene_depth: texture_depth_2d` | The world's depth, reversed (1 near, 0 far and sky). |
+| 3 | `var previous: texture_2d<f32>` | The previous pass's output (`scene_color` for the first pass). |
+| 4 | `var linear_sampler: sampler` | Bilinear filtering, clamped to the edges. |
+| 5 | `var nearest_sampler: sampler` | Nearest texel, clamped to the edges. |
+
+Helpers:
+
+- `fn depth_at(uv: vec2<f32>) -> f32`: the world's depth at `uv`.
+- `fn view_position(uv: vec2<f32>, depth: f32) -> vec3<f32>`: the camera-relative position, in blocks, of
+  the point at `uv` and `depth`.
+
+## The frame
+
+### `Frame`
+
+The frame, as `frame` in every stage. Positions and directions are in world axes relative to the camera (x east, y up, z south), so they stay precise far from the world's origin; depth is reversed (1 near, 0 at the far plane and in the sky).
+
+| Field | Type | Offset | Meaning |
+| --- | --- | --- | --- |
+| `view` | `mat4x4<f32>` | 0 | Camera-relative world to view space: the camera's rotation. |
+| `projection` | `mat4x4<f32>` | 64 | View to clip space (reversed depth, wgpu's clip space: z 0..1). |
+| `view_inverse` | `mat4x4<f32>` | 128 | View to camera-relative world space. |
+| `projection_inverse` | `mat4x4<f32>` | 192 | Clip to view space. |
+| `camera_position` | `vec3<f32>` | 256 | The camera's world position, in blocks (about a millimetre of precision 10 000 blocks out). |
+| `time` | `f32` | 268 | Seconds since the pack was loaded, wrapping to 0 every hour. |
+| `sun_direction` | `vec3<f32>` | 272 | Unit vector toward the sun (below the horizon at night). |
+| `day_time` | `f32` | 284 | The time of day, 0..1: 0 sunrise, 0.25 noon, 0.5 sunset, 0.75 midnight. |
+| `moon_direction` | `vec3<f32>` | 288 | Unit vector toward the moon. |
+| `game_time` | `f32` | 300 | Vanilla's GameTime: (game time % 24000 + partial tick) / 24000, 0..1. |
+| `sky_color` | `vec3<f32>` | 304 | Vanilla's sky colour this frame, 0..1. |
+| `rain` | `f32` | 316 | Rain strength, 0..1. |
+| `fog_color` | `vec3<f32>` | 320 | Vanilla's fog colour this frame (also the clear colour), 0..1. |
+| `thunder` | `f32` | 332 | Thunder strength, 0..1. |
+| `resolution` | `vec2<f32>` | 336 | The size of the world's picture, in pixels (the resolution scale applied). |
+| `eye_light` | `vec2<f32>` | 344 | Block and sky light at the camera, 0..1 (level / 15). |
+| `fog_start` | `f32` | 352 | Where vanilla's fog starts, in blocks from the camera. |
+| `fog_end` | `f32` | 356 | Where vanilla's fog is full, in blocks. |
+| `render_distance` | `f32` | 360 | The render distance, in blocks. |
+| `far` | `f32` | 364 | The far plane, in blocks. |
+| `night_vision` | `f32` | 368 | Night vision strength, 0..1. |
+| `blindness` | `f32` | 372 | Blindness strength, 0..1. |
+| `darkness` | `f32` | 376 | The darkness effect's strength, 0..1. |
+| `brightness` | `f32` | 380 | The Brightness option, 0..1 (Moody to Bright). |
+| `eye_in` | `u32` | 384 | What the camera is in: 0 air, 1 water, 2 lava, 3 powder snow. |
+| `dimension` | `i32` | 388 | 0 the Overworld, -1 the Nether, 1 the End, 2 any other dimension. |
+| `frame_index` | `u32` | 392 | Frames drawn since the pack was loaded (wraps). |
+| `hide_gui` | `u32` | 396 | 1 while F1 hides the HUD, else 0. |
+
+## Options
+
+Each `[[options]]` entry sets the WGSL `override` of the same name when the pipelines are built:
+
+| `type` | Keys | The `override` |
+| --- | --- | --- |
+| `bool` | `default` | `override <id>: bool` |
+| `float` | `default`, `min`, `max`, `step` | `override <id>: f32` |
+| `int` | `default`, `min`, `max` | `override <id>: i32` |
+| `choice` | `values`, `default` (one of them) | `override <id>: u32`, the value's index |
+
+## Limits
+
+- 8 post passes, 64 options, `budget.gpu_ms` up to 16.
+- 256 KiB per WGSL file, 8 MiB per pack.
diff --git a/docs/api/shaders.md b/docs/api/shaders.md
index 82b9acced..a5ba0986d 100644
--- a/docs/api/shaders.md
+++ b/docs/api/shaders.md
@@ -79,8 +79,9 @@ the same way every time (files in path order, fixed dates), so a pack's SHA-256
 
 ## Guide, reference and examples
 
-None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack
-in the repository that the renderer's tests load.
+- [shaders-reference.md](shaders-reference.md): every stage's signature, input and output structs, resources and
+  helpers, the frame's fields with their units, option types and limits, generated from `crates/horizon-shader-api`.
+- The guide and an example pack come with `horizon-shader check`.
 
 ## Stability
 
@@ -94,5 +95,6 @@ stages with options and hot reload, then the overlay, lighting, sky and shadow s
 
 ## Changelog
 
+- 2026-10-25: the stages of API 0.1 (sky, material, post), their inputs and the generated reference.
 - 2026-10-25: the pack format, schema 1: `horizon-shaders.toml` and the `.hshader` package.
 - 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.

From 4b5fa2ea6b86a7766c9503f01524681602732656 Mon Sep 17 00:00:00 2001
From: Fo <26b95bff27431f3eaab8@wajo.ai>
Date: Sun, 25 Oct 2026 14:28:55 +0000
Subject: [PATCH 087/270] build: make horizon-dualsense compile on iOS

hidapi 2.6.7 has no iOS backend, so the crate failed to build for
aarch64-apple-ios (hidapi's build script looked for hid.h). Gate the
hidapi and cpal dependencies plus all HID device/haptics code behind
cfg(not(target_os = "ios")) and provide an inert stub on iOS
(Link::start() is a no-op), mirroring how horizon-gamecontroller
already compiles empty on iOS.

Verified with cargo check -p horizon-dualsense --target
aarch64-apple-ios: clean, no warnings. Host clippy/tests are left to
CI (this sandbox has no C toolchain for the host target).

Co-Authored-By: Fo <26b95bff27431f3eaab8@wajo.ai>
---
 crates/horizon-dualsense/Cargo.toml          |  8 +++-
 crates/horizon-dualsense/src/device.rs       | 47 ++++++++++++++++----
 crates/horizon-dualsense/src/haptics_stub.rs | 21 +++++++++
 crates/horizon-dualsense/src/lib.rs          |  6 +++
 4 files changed, 73 insertions(+), 9 deletions(-)
 create mode 100644 crates/horizon-dualsense/src/haptics_stub.rs

diff --git a/crates/horizon-dualsense/Cargo.toml b/crates/horizon-dualsense/Cargo.toml
index fe05b4f59..1a41e5703 100644
--- a/crates/horizon-dualsense/Cargo.toml
+++ b/crates/horizon-dualsense/Cargo.toml
@@ -7,10 +7,16 @@ rust-version = "1.85"
 description = "The DualSense's output over HID: rumble, adaptive triggers, lightbar and player LEDs"
 
 [dependencies]
+log = "0.4"
+
+# hidapi has no iOS backend and its build script stops there, so the output's two
+# dependencies go only to the targets that have one. On iOS the crate builds empty: pads
+# are read through GameController (horizon-gamecontroller), which only reads, and the
+# DualSense's own output waits for a desktop.
+[target.'cfg(not(target_os = "ios"))'.dependencies]
 # MIT; bundles the C hidapi under its BSD licence option. hidraw on Linux (libudev, as gilrs),
 # IOKit on macOS (opened shared, so gilrs keeps reading the pad), the HID API on Windows.
 hidapi = { version = "2.6.7", default-features = false, features = ["linux-static-hidraw", "macos-shared-device"] }
-log = "0.4"
 # HD haptics through the pad's own audio device (USB).
 cpal = "0.16"
 
diff --git a/crates/horizon-dualsense/src/device.rs b/crates/horizon-dualsense/src/device.rs
index 97c6ec72b..0b11ac415 100644
--- a/crates/horizon-dualsense/src/device.rs
+++ b/crates/horizon-dualsense/src/device.rs
@@ -1,14 +1,21 @@
 //! The pad over hidapi, and the thread that writes to it: writes block (a Bluetooth report can
 //! take milliseconds), so the game only hands over what the pad should do.
-use crate::{
-    DEFAULT_LIGHTBAR, Output, PLAYER_1, TRIGGER_OFF, TriggerEffect, Vibration, is_dualsense,
-};
+#[cfg(not(target_os = "ios"))]
+use crate::{DEFAULT_LIGHTBAR, Output, PLAYER_1, Vibration, is_dualsense};
+use crate::{TRIGGER_OFF, TriggerEffect};
+#[cfg(not(target_os = "ios"))]
 use hidapi::{BusType, HidApi, HidDevice, HidResult};
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
-use std::sync::mpsc::{self, RecvTimeoutError, Sender};
+#[cfg(not(target_os = "ios"))]
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::{AtomicU8, Ordering};
+use std::sync::mpsc::Sender;
+#[cfg(not(target_os = "ios"))]
+use std::sync::mpsc::{self, RecvTimeoutError};
 use std::thread::JoinHandle;
-use std::time::{Duration, Instant};
+use std::time::Duration;
+#[cfg(not(target_os = "ios"))]
+use std::time::Instant;
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Transport {
@@ -17,6 +24,7 @@ pub enum Transport {
 }
 
 /// An open DualSense.
+#[cfg(not(target_os = "ios"))]
 pub struct DualSense {
     device: HidDevice,
     transport: Transport,
@@ -34,6 +42,7 @@ pub fn bluetooth_allowed() -> bool {
     cfg!(target_os = "linux") || std::env::var_os("HORIZON_DUALSENSE_BT").is_some_and(|v| v == "1")
 }
 
+#[cfg(not(target_os = "ios"))]
 impl DualSense {
     /// The first DualSense hidapi lists, USB before Bluetooth (as SDL); `None` when there is
     /// none, an error when it can't be opened (Linux without access to its hidraw node).
@@ -119,13 +128,17 @@ impl Default for State {
 /// A vibration: the motors' levels (left, right), each for a while, in order.
 pub type Rumble = Vec<([u8; 2], Duration)>;
 
+// On iOS no thread reads the queue (the Link never opens); the variants stay so the
+// Link's API is the same everywhere.
+#[cfg_attr(target_os = "ios", allow(dead_code))]
 enum Message {
     State(State),
     Rumble(Rumble),
     Scan,
 }
 
-/// The writer thread. Dropping it frees the triggers and stops the motors before it ends.
+/// The output thread. Dropping it frees the triggers and stops the motors before it ends; on
+/// iOS there is none (no hidapi backend) and the Link stays closed.
 pub struct Link {
     tx: Option<Sender<Message>>,
     /// 0: no pad open, else 1 + the transport.
@@ -135,6 +148,7 @@ pub struct Link {
 
 impl Link {
     /// Start the thread and look for a DualSense.
+    #[cfg(not(target_os = "ios"))]
     pub fn start() -> Link {
         let (tx, rx) = mpsc::channel();
         let open = Arc::new(AtomicU8::new(0));
@@ -151,6 +165,17 @@ impl Link {
         }
     }
 
+    /// No output on iOS: hidapi has no backend there, and iOS reads pads through
+    /// GameController (horizon-gamecontroller), which only reads. The Link never opens.
+    #[cfg(target_os = "ios")]
+    pub fn start() -> Link {
+        Link {
+            tx: None,
+            open: Arc::new(AtomicU8::new(0)),
+            thread: None,
+        }
+    }
+
     /// The pad's transport while one is open and taking reports.
     pub fn open(&self) -> Option<Transport> {
         match self.open.load(Ordering::Relaxed) {
@@ -194,8 +219,10 @@ impl Drop for Link {
 
 /// Looks for the pad this many more times, a second apart, after a scan finds nothing (its
 /// hidraw node may appear after the controller does).
+#[cfg(not(target_os = "ios"))]
 const SCAN_TRIES: u32 = 5;
 
+#[cfg(not(target_os = "ios"))]
 struct Writer {
     api: Option<HidApi>,
     pad: Option<DualSense>,
@@ -213,6 +240,7 @@ struct Writer {
     next_scan: Instant,
 }
 
+#[cfg(not(target_os = "ios"))]
 #[derive(Clone, Copy, Debug, PartialEq)]
 enum Lights {
     /// Over Bluetooth, until the pad's clock says its animation is over (or this long after
@@ -225,11 +253,13 @@ enum Lights {
 
 /// The pad's sensor clock once its Bluetooth connection animation is over (SDL_hidapi_ps5.c's
 /// `HIDAPI_DriverPS5_CheckPendingLEDReset`).
+#[cfg(not(target_os = "ios"))]
 const ANIMATION_OVER: u32 = 10_200_000;
 
 /// The sensor clock of a Bluetooth input report 0x31: its state block starts at byte 2 and
 /// holds the clock at 27..31, little-endian (SDL's `PS5StatePacketCommon_t`, the kernel's
 /// `dualsense_input_report`).
+#[cfg(not(target_os = "ios"))]
 fn bluetooth_clock(report: &[u8]) -> Option<u32> {
     match report {
         [0x31, _, state @ ..] if state.len() >= 31 => {
@@ -239,6 +269,7 @@ fn bluetooth_clock(report: &[u8]) -> Option<u32> {
     }
 }
 
+#[cfg(not(target_os = "ios"))]
 impl Writer {
     fn new(open: Arc<AtomicU8>) -> Self {
         Writer {
@@ -451,7 +482,7 @@ impl Writer {
     }
 }
 
-#[cfg(test)]
+#[cfg(all(test, not(target_os = "ios")))]
 mod tests {
     use super::*;
 
diff --git a/crates/horizon-dualsense/src/haptics_stub.rs b/crates/horizon-dualsense/src/haptics_stub.rs
new file mode 100644
index 000000000..7afc944ca
--- /dev/null
+++ b/crates/horizon-dualsense/src/haptics_stub.rs
@@ -0,0 +1,21 @@
+//! No HD haptics on iOS: the trick plays vibrations through the pad's own four-channel audio
+//! device over USB, and a phone has neither that device nor the audio stack the real module
+//! needs. The motors' rumble through [`crate::Link`] covers vibration instead.
+
+/// The pad's audio output, playing the queued samples (left, right actuator).
+pub struct Haptics;
+
+impl Haptics {
+    /// The DualSense's audio device, if one is there with its four channels (USB). A phone
+    /// has none.
+    pub fn open() -> Option<Haptics> {
+        None
+    }
+
+    /// Play a vibration (heavy and light levels, 0..1, each for a while), replacing the one
+    /// playing. Nothing plays on iOS.
+    pub fn play(&self, _steps: &[(f32, f32, std::time::Duration)]) {}
+
+    /// Stop at once. Nothing plays on iOS.
+    pub fn stop(&self) {}
+}
diff --git a/crates/horizon-dualsense/src/lib.rs b/crates/horizon-dualsense/src/lib.rs
index 438d8f6fe..80831ee00 100644
--- a/crates/horizon-dualsense/src/lib.rs
+++ b/crates/horizon-dualsense/src/lib.rs
@@ -1,12 +1,18 @@
 //! The DualSense's output report, built by hand (docs/controllers.md "DualSense output"): the
 //! compatible-vibration motors, the adaptive triggers, the lightbar and the player LEDs. Gilrs
 //! keeps reading the pad; this crate only writes to it, over hidapi ([`device`]).
+//! On iOS the crate builds without hidapi, which has no backend there: [`Link`] never opens,
+//! and the pad is read through GameController, which only reads.
 //!
 //! The byte layout is the one documented by the Linux kernel's `hid-playstation.c` and SDL's
 //! `SDL_hidapi_ps5.c`: a 47-byte block shared by both transports, sent as report 0x02 over USB
 //! and as report 0x31 over Bluetooth, where a sequence tag leads it and a CRC-32 (seeded with
 //! the byte 0xA2) closes it.
 pub mod device;
+#[cfg(not(target_os = "ios"))]
+pub mod haptics;
+#[cfg(target_os = "ios")]
+#[path = "haptics_stub.rs"]
 pub mod haptics;
 pub mod trigger;
 

From 6b97107dc7ed8cc1ce6f5d76fcf932febf8b796d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:37:02 +0100
Subject: [PATCH 088/270] Transfers: handshake with the TRANSFER intent, answer
 login cookie requests

Vanilla 26.3 reconnects after ClientboundTransferPacket with a TransferState,
so Connection.initiateServerboundPlayConnection sends ClientIntent.TRANSFER (3):
a target with accepts-transfers=false refuses the player, and the target can
ask for the carried cookies during login
(ClientHandshakePacketListenerImpl.handleRequestCookie). Both now match.

A transfer from single player closes the world instead of connecting
elsewhere (handleTransfer: "Cannot transfer to server from singleplayer").

Adds a unit test for the play-state store/request round trip and the
Transfer event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/remote.rs |  6 +-
 crates/horizon-client/src/net.rs         | 78 +++++++++++++++++++++++-
 2 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index c10b64c54..d70c0a4ae 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -893,8 +893,12 @@ impl Game<'_> {
                     }
                 }
                 Event::Reconfigured(registries) => self.set_registries(registries),
+                // handleTransfer: "Cannot transfer to server from
+                // singleplayer" (no ServerData), so the world just closes.
                 Event::Transfer { host, port } => {
-                    if let Some(r) = self.remote.as_mut() {
+                    if let Some(r) = self.remote.as_mut()
+                        && r.session.address != "local"
+                    {
                         r.transfer = Some(format!("{host}:{port}"));
                     }
                 }
diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs
index c4e53cef4..18aec0bea 100644
--- a/crates/horizon-client/src/net.rs
+++ b/crates/horizon-client/src/net.rs
@@ -139,6 +139,9 @@ impl Session {
         let writer = Arc::new(Mutex::new(None));
         let configuring = Arc::new(AtomicBool::new(true));
         let counters = Arc::new(Mutex::new(None));
+        // Connection.initiateServerboundPlayConnection: a transfer's
+        // handshake says so (ClientIntent.TRANSFER).
+        let transferred = cookies.is_some();
         let cookies = cookies.unwrap_or_default();
         let (thread_writer, thread_counters, thread_cookies) =
             (writer.clone(), counters.clone(), cookies.clone());
@@ -159,6 +162,7 @@ impl Session {
                     &thread_configuring,
                     &thread_counters,
                     &thread_cookies,
+                    transferred,
                 );
                 let from_server = result.is_ok();
                 let reason = result.unwrap_or_else(|e| e);
@@ -333,6 +337,7 @@ fn run(
     configuring: &AtomicBool,
     shared_counters: &Mutex<Option<Arc<Counters>>>,
     cookies: &Cookies,
+    transferred: bool,
 ) -> Result<String, String> {
     let (host, port, mut c) = if let Some(pipe) = local {
         (address.to_owned(), 0, Connection::local(pipe))
@@ -363,7 +368,11 @@ fn run(
             protocol: PROTOCOL_VERSION,
             host: host.clone(),
             port,
-            intent: handshake::LOGIN,
+            intent: if transferred {
+                handshake::TRANSFER
+            } else {
+                handshake::LOGIN
+            },
         })
         .encode(),
     )
@@ -433,11 +442,14 @@ fn run(
                 )
                 .map_err(e)?;
             }
+            // ClientHandshakePacketListenerImpl.handleRequestCookie: the
+            // cookies a transfer carried over (none on a plain join).
             login::Clientbound::CookieRequest(q) => {
+                let payload = cookies.lock().unwrap().get(&q.key).cloned();
                 c.send(
                     &login::Serverbound::CookieResponse(login::CookieResponse {
                         key: q.key,
-                        payload: None,
+                        payload,
                     })
                     .encode(),
                 )
@@ -829,6 +841,68 @@ mod tests {
         assert!(thread.join().unwrap().is_err());
     }
 
+    #[test]
+    fn play_answers_cookie_requests_from_stored_cookies_and_follows_transfers() {
+        let (client, server) = horizon_protocol::connection::Pipe::pair();
+        let (mut reader, writer) = Connection::local(client).split();
+        let writer = Arc::new(Mutex::new(Some(writer)));
+        let (send, events) = channel();
+        let cookies = Cookies::default();
+        let (thread_writer, thread_cookies) = (writer.clone(), cookies.clone());
+        let thread = std::thread::spawn(move || {
+            receive_play(
+                &mut reader,
+                &thread_writer,
+                &AtomicBool::new(false),
+                &Language::new(),
+                &send,
+                &thread_cookies,
+            )
+        });
+        let mut server = Connection::local(server);
+        let ask = |server: &mut Connection, key: &str| {
+            let request = play::Clientbound::CookieRequest(cfg::CookieRequest { key: key.into() });
+            server.send(&request.encode()).unwrap();
+            let (id, body) = server.recv().unwrap();
+            play::Serverbound::decode(id, &body).unwrap()
+        };
+        // handleRequestCookie answers an unknown key with no payload.
+        assert_eq!(
+            ask(&mut server, "proxy:session"),
+            play::Serverbound::CookieResponse(cfg::CookieResponse {
+                key: "proxy:session".into(),
+                payload: None,
+            })
+        );
+        let store = play::Clientbound::StoreCookie(cfg::StoreCookie {
+            key: "proxy:session".into(),
+            payload: vec![1, 2, 3],
+        });
+        server.send(&store.encode()).unwrap();
+        assert_eq!(
+            ask(&mut server, "proxy:session"),
+            play::Serverbound::CookieResponse(cfg::CookieResponse {
+                key: "proxy:session".into(),
+                payload: Some(vec![1, 2, 3]),
+            })
+        );
+        let transfer = play::Clientbound::Transfer(cfg::Transfer {
+            host: "example.net".into(),
+            port: 25566,
+        });
+        server.send(&transfer.encode()).unwrap();
+        assert!(thread.join().unwrap().is_ok());
+        assert!(matches!(
+            events.try_iter().last(),
+            Some(Event::Transfer { host, port: 25566 }) if host == "example.net"
+        ));
+        // The stored cookie stays for the next connection (TransferState).
+        assert_eq!(
+            cookies.lock().unwrap().get("proxy:session"),
+            Some(&vec![1, 2, 3])
+        );
+    }
+
     #[test]
     fn server_brand_payload_is_decoded_and_invalid_or_unrelated_payloads_are_ignored() {
         let (send, events) = channel();

From 749a2dc9bd5d0c0367701c59b814141e24b65b19 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:30:43 +0100
Subject: [PATCH 089/270] Global level events reach a server's players;
 explosions play their packet's sound

ServerLevel.globalLevelEvent (an end portal opening, 1038; the dragon's
death roar, 1028) went to the Game's own audio without a position, which
is never forwarded: on the server thread, LAN and dedicated servers
nobody heard them. They now go to every guest as a global LevelEvent,
which a client plays two blocks from its camera towards the event
(LevelEventHandler.globalLevelEvent).

ClientPacketListener.handleExplosion plays the packet's explosionSound;
the client always played entity.generic.explode (a vanilla server's wind
charge sounded like TNT).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  3 ++
 crates/horizon-client/src/game/dragon.rs      |  7 ++--
 crates/horizon-client/src/game/end.rs         |  7 ++--
 crates/horizon-client/src/game/lan.rs         |  3 ++
 .../horizon-client/src/game/lan_particles.rs  | 12 +++----
 .../src/game/level_particles.rs               | 33 +++++++++++++++++++
 crates/horizon-client/src/game/remote.rs      | 30 +++++++++++------
 crates/horizon-client/src/lan/containers.rs   | 11 +++++++
 8 files changed, 84 insertions(+), 22 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..afd8181cc 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1544,6 +1544,8 @@ struct Game<'a> {
     /// position) for the guests.
     lan_block_events: Vec<([i32; 3], i32, i32, u32)>,
     lan_entity_events: Vec<(i32, i8, [f64; 3])>,
+    /// Global level events for every guest (`ServerLevel.globalLevelEvent`).
+    lan_global_events: Vec<(i32, [i32; 3], i32)>,
     /// `ContainerOpenersCounter`: how many players (the host and the guests)
     /// have each chest open.
     lid_openers: HashMap<(i32, i32, i32), i32>,
@@ -11990,6 +11992,7 @@ impl<'a> Game<'a> {
             lan_events: Vec::new(),
             lan_block_events: Vec::new(),
             lan_entity_events: Vec::new(),
+            lan_global_events: Vec::new(),
             lid_openers: HashMap::new(),
             lan_acting: None,
             guest_packets: Vec::new(),
diff --git a/crates/horizon-client/src/game/dragon.rs b/crates/horizon-client/src/game/dragon.rs
index 54b260c67..fb555c2d8 100644
--- a/crates/horizon-client/src/game/dragon.rs
+++ b/crates/horizon-client/src/game/dragon.rs
@@ -1963,9 +1963,10 @@ impl Game<'_> {
             self.spawn_orbs([p.x, p.y, p.z], (xp as f32 * 0.08) as u32);
         }
         if t == 1 {
-            // Level event 1028: the death roar, heard everywhere.
-            self.audio
-                .play("minecraft:entity.ender_dragon.death", None, 5.0, 1.0);
+            // EnderDragon.tickDeath: global level event 1028, the death
+            // roar, heard everywhere.
+            let at = [p.x, p.y, p.z].map(|v| v.floor() as i32);
+            self.global_level_event(1028, at, 0);
         }
         if let Some(d) = self.dragon.as_mut() {
             d.position.y += 0.1;
diff --git a/crates/horizon-client/src/game/end.rs b/crates/horizon-client/src/game/end.rs
index 599158e3e..d3fb79172 100644
--- a/crates/horizon-client/src/game/end.rs
+++ b/crates/horizon-client/src/game/end.rs
@@ -311,9 +311,10 @@ impl Game<'_> {
                     )?;
                 }
             }
-            // Global LevelEvent 1038: END_PORTAL_SPAWN.
-            self.audio
-                .play("minecraft:block.end_portal.spawn", None, 1.0, 1.0);
+            // EnderEyeItem.useOn: global level event 1038 (END_PORTAL_SPAWN),
+            // heard by every player (vanilla places it at the frame's corner
+            // + (1, 0, 1); only its direction matters).
+            self.global_level_event(1038, c, 0);
         }
         Ok(true)
     }
diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs
index 8460f54e6..442c38a66 100644
--- a/crates/horizon-client/src/game/lan.rs
+++ b/crates/horizon-client/src/game/lan.rs
@@ -1150,6 +1150,9 @@ impl Game<'_> {
         for (id, event, at) in std::mem::take(&mut self.lan_entity_events) {
             host.hub.entity_event(id, event, at);
         }
+        for (kind, pos, data) in std::mem::take(&mut self.lan_global_events) {
+            host.hub.global_level_event(kind, pos, data);
+        }
         self.lan_broadcast_effects(host);
         if host.hub.guests.is_empty() {
             host.mob_state.clear();
diff --git a/crates/horizon-client/src/game/lan_particles.rs b/crates/horizon-client/src/game/lan_particles.rs
index 1efb4ac58..0e35392bf 100644
--- a/crates/horizon-client/src/game/lan_particles.rs
+++ b/crates/horizon-client/src/game/lan_particles.rs
@@ -161,12 +161,12 @@ impl Game<'_> {
                 + (self.particles.random().next_float() - self.particles.random().next_float())
                     * 0.2)
                 * 0.7;
-            self.audio.play(
-                "minecraft:entity.generic.explode",
-                Some(p.center),
-                4.0,
-                pitch,
-            );
+            // The packet's explosionSound: a wind charge's burst, a bed's
+            // or anchor's blast, a modded sound.
+            let sound = self
+                .remote_sound_name(&p.sound)
+                .unwrap_or_else(|| "minecraft:entity.generic.explode".to_owned());
+            self.audio.play(&sound, Some(p.center), 4.0, pitch);
         }
         if let Some(options) = self.received_particle(&p.particle, p.center) {
             self.particles.add(&options, p.center, [1.0, 0.0, 0.0]);
diff --git a/crates/horizon-client/src/game/level_particles.rs b/crates/horizon-client/src/game/level_particles.rs
index d239c69d0..f12aedc5b 100644
--- a/crates/horizon-client/src/game/level_particles.rs
+++ b/crates/horizon-client/src/game/level_particles.rs
@@ -101,6 +101,39 @@ impl Game<'_> {
             }
         }
     }
+    /// `ServerLevel.globalLevelEvent`: heard by every player on the server
+    /// (an end portal opening, the dragon's death roar): here, and sent to
+    /// every guest whatever their dimension.
+    pub(super) fn global_level_event(&mut self, id: i32, pos: [i32; 3], data: i32) {
+        self.global_level_event_sound(id, pos);
+        if self.audio.capture.is_some() {
+            self.lan_global_events.push((id, pos, data));
+        }
+    }
+    /// `LevelEventHandler.globalLevelEvent`: the sound two blocks from the
+    /// camera towards the event, so it is heard from anywhere.
+    pub(super) fn global_level_event_sound(&mut self, id: i32, pos: [i32; 3]) {
+        let (sound, volume) = match id {
+            1023 => ("minecraft:entity.wither.spawn", 1.0),
+            1028 => ("minecraft:entity.ender_dragon.death", 5.0),
+            1038 => ("minecraft:block.end_portal.spawn", 1.0),
+            _ => return,
+        };
+        let at = self.eye_position().map(|eye| {
+            let d = [
+                f64::from(pos[0]) + 0.5 - eye[0],
+                f64::from(pos[1]) + 0.5 - eye[1],
+                f64::from(pos[2]) + 0.5 - eye[2],
+            ];
+            let length = (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt();
+            if length < 1.0e-4 {
+                return eye;
+            }
+            [0, 1, 2].map(|k| eye[k] + d[k] / length * 2.0)
+        });
+        // Each guest plays it from the global packet.
+        self.audio.play_unshared(sound, at, volume, 1.0);
+    }
     /// Queue and play level event `id` at `pos` (`Level.levelEvent`).
     pub(super) fn level_event_at(&mut self, id: i32, pos: [i32; 3], data: i32) {
         self.level_events.push(LevelEvent::LevelEvent {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..a80f0087a 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -255,6 +255,22 @@ fn number_format(f: &play::NumberFormat) -> horizon_client::scoreboard::NumberFo
 }
 
 impl Game<'_> {
+    /// A `Holder<SoundEvent>` off the wire: an inline event's location, or
+    /// the name of a registered one.
+    pub(super) fn remote_sound_name(
+        &self,
+        sound: &(i32, Option<(String, Option<f32>)>),
+    ) -> Option<String> {
+        match &sound.1 {
+            Some((location, _)) => Some(location.clone()),
+            None => self.remote.as_ref().and_then(|r| {
+                r.builtin
+                    .get("minecraft:sound_event")?
+                    .name(sound.0)
+                    .map(str::to_owned)
+            }),
+        }
+    }
     /// Leave the title for a server (ConnectScreen): an empty world fed by the connection.
     pub(super) fn connect_server(&mut self, address: &str, name: &str) -> Result<()> {
         if self.defer_world_entry(super::PendingWorldEntry::Server {
@@ -1814,20 +1830,14 @@ impl Game<'_> {
             // ClientLevel.levelEvent: LevelEventHandler, as this client's own
             // level plays them (particles and sounds: a spawner's burst, bone
             // meal, waxing, a block broken by someone else).
+            // ClientPacketListener.handleLevelEvent: a global one is heard
+            // from anywhere (ClientLevel.globalLevelEvent).
+            C::LevelEvent(p) if p.global => self.global_level_event_sound(p.kind, p.pos),
             C::LevelEvent(p) => self.level_event_at(p.kind, p.pos, p.data),
             C::LevelParticles(p) => self.remote_level_particles(&p),
             C::Explode(p) => self.remote_explode(&p),
             C::Sound(p) => {
-                let name = match &p.sound.1 {
-                    Some((location, _)) => Some(location.clone()),
-                    None => self.remote.as_ref().and_then(|r| {
-                        r.builtin
-                            .get("minecraft:sound_event")?
-                            .name(p.sound.0)
-                            .map(str::to_owned)
-                    }),
-                };
-                if let Some(name) = name {
+                if let Some(name) = self.remote_sound_name(&p.sound) {
                     let at = [
                         f64::from(p.x) / 8.0,
                         f64::from(p.y) / 8.0,
diff --git a/crates/horizon-client/src/lan/containers.rs b/crates/horizon-client/src/lan/containers.rs
index d43cb5c27..f34d5ff58 100644
--- a/crates/horizon-client/src/lan/containers.rs
+++ b/crates/horizon-client/src/lan/containers.rs
@@ -78,6 +78,17 @@ impl Hub {
         );
     }
 
+    /// `ServerLevel.globalLevelEvent`: the packet with its global flag, for
+    /// every player on the server (`PlayerList.broadcastAll`).
+    pub fn global_level_event(&self, kind: i32, pos: [i32; 3], data: i32) {
+        self.broadcast(&C::LevelEvent(play::LevelEvent {
+            kind,
+            pos,
+            data,
+            global: true,
+        }));
+    }
+
     /// ClientboundBlockEventPacket (`PlayerList.broadcast` within 64 blocks).
     pub fn block_event(&self, pos: [i32; 3], b0: i32, b1: i32, state: u32) {
         let block = self

From 5fb0cad6e7a520365e78b2635884af970493e11d Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 11:31:02 -0300
Subject: [PATCH 090/270] Wither roses give the player Wither

WitherRoseBlock.entityInside adds getBeeInteractionEffect (Wither, 40
ticks) to a living entity inside it on a server level that isn't
peaceful, unless it is invulnerable to wither damage. The player's
inside-block dispatch had no wither rose case, so neither singleplayer
mode applied it. The sweep now asks for it, the game adds it to its own
player, and the server-thread path adds it to a server's player.

Fixes #1319.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  1 +
 crates/horizon-client/src/game/creatures.rs   | 10 +++
 crates/horizon-client/src/game/lan_actions.rs |  6 ++
 crates/horizon-client/src/motion.rs           | 79 ++++++++++++++++++-
 4 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..d6a587e53 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -4289,6 +4289,7 @@ impl Game<'_> {
                 MotionEvent::Snowflake { position, velocity } => self.snowflake(position, velocity),
                 MotionEvent::EnterBlock { state } => self.trigger_enter_block(state),
                 MotionEvent::InsidePortal { pos } => self.player_inside_nether_portal(pos),
+                MotionEvent::InsideWitherRose => self.wither_rose_contact(),
                 MotionEvent::SmashLanding {
                     state,
                     position,
diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 0bb7bbe85..a0419f23b 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -1558,6 +1558,16 @@ impl Game<'_> {
                 id, ticks, amplifier,
             ));
     }
+    /// `WitherRoseBlock.entityInside` for the player: on a server level that
+    /// isn't peaceful, `getBeeInteractionEffect` (Wither, 40 ticks) unless the
+    /// player is invulnerable to wither damage (creative, spectator). A
+    /// server's player gets it from the server.
+    pub(super) fn wither_rose_contact(&mut self) {
+        if self.remote.is_some() || self.ui.difficulty == 0 {
+            return;
+        }
+        self.give_player_effect("minecraft:wither", 40, 0);
+    }
     /// Burning applied to the player by mobs.
     fn tick_player_effects(&mut self) {
         self.creatures.wind_cooldown = self.creatures.wind_cooldown.saturating_sub(1);
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..882a66244 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -2010,6 +2010,12 @@ impl Game<'_> {
             let _ = w.apply_fire_contact();
             let _ = w.server_hazards_tick(in_wall);
             let mut events = std::mem::take(&mut w.player.events);
+            // WitherRoseBlock.entityInside along those moves.
+            for event in &events {
+                if matches!(event, MotionEvent::InsideWitherRose) {
+                    game.wither_rose_contact();
+                }
+            }
             // ServerGamePacketListenerImpl.handleMovePlayer:
             // Player.checkMovementStatistics for each move.
             for d in travelled {
diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs
index 560cadc80..ecf7b76d1 100644
--- a/crates/horizon-client/src/motion.rs
+++ b/crates/horizon-client/src/motion.rs
@@ -167,6 +167,9 @@ pub enum MotionEvent {
     InsidePortal {
         pos: BlockPos,
     },
+    /// `WitherRoseBlock.entityInside`: the player's box swept through a
+    /// wither rose; the server adds its Wither unless peaceful.
+    InsideWitherRose,
     /// `ServerPlayer.checkFallDamage` after a mace smash: block particles
     /// from the landing block, more the further the fall.
     SmashLanding {
@@ -1294,9 +1297,13 @@ impl MotionWorld<'_, '_, '_> {
                 }
             };
             if inside && visited.insert(p.pack()) {
-                // CactusBlock and CampfireBlock.entityInside (`entity.hurt`).
+                // CactusBlock and CampfireBlock.entityInside (`entity.hurt`),
+                // and WitherRoseBlock's server-side effect.
                 match name {
                     "minecraft:cactus" => self.environment_hurt("minecraft:cactus", 1.0)?,
+                    "minecraft:wither_rose" => {
+                        self.player.events.push(MotionEvent::InsideWitherRose);
+                    }
                     "minecraft:campfire" | "minecraft:soul_campfire" => {
                         let lit = self
                             .assets
@@ -2368,6 +2375,76 @@ mod tests {
         assert_eq!(player.position.y, 4.0);
     }
 
+    #[test]
+    fn standing_in_a_wither_rose_asks_for_its_effect() {
+        let root = std::env::var_os("HORIZON_TEST_RESOURCES")
+            .map(std::path::PathBuf::from)
+            .unwrap_or_else(|| {
+                Path::new(env!("CARGO_MANIFEST_DIR"))
+                    .join("../../.local/horizon-client")
+                    .join(horizon_core::VANILLA_VERSION)
+            });
+        if !root.join("movement-properties.nbt").exists() {
+            return;
+        }
+        let assets = Assets::load(&root).unwrap();
+        let render = assets.reload(&root).unwrap();
+        let binding = crate::collisions::load(&root, assets.registry).unwrap();
+        let resources = MotionResources::load(&root, &assets).unwrap();
+        let mut scene = World::test_scene(&assets, &render, 1).unwrap();
+        let rose = assets
+            .registry
+            .default_state("minecraft:wither_rose")
+            .unwrap();
+        scene.set(20, 4, 20, rose).unwrap();
+        let roses = |player: &PlayerMotion| {
+            player
+                .events
+                .iter()
+                .filter(|e| matches!(e, MotionEvent::InsideWitherRose))
+                .count()
+        };
+        let mut player = PlayerMotion::new(&resources, Vec3::new(20.5, 4.0, 20.5)).unwrap();
+        MotionWorld {
+            entities: &[],
+            player: &mut player,
+            scene: &mut scene,
+            assets: &assets,
+            collision_binding: &binding,
+            resources: &resources,
+        }
+        .controlled_simulation_tick(Default::default())
+        .unwrap();
+        assert_eq!(roses(&player), 1);
+        // A server's player: its client moved it, the server applies the effect.
+        player.events.clear();
+        let from = player.position;
+        MotionWorld {
+            entities: &[],
+            player: &mut player,
+            scene: &mut scene,
+            assets: &assets,
+            collision_binding: &binding,
+            resources: &resources,
+        }
+        .server_block_damage(from)
+        .unwrap();
+        assert_eq!(roses(&player), 1);
+        // Two blocks away, nothing.
+        let mut away = PlayerMotion::new(&resources, Vec3::new(22.5, 4.0, 20.5)).unwrap();
+        MotionWorld {
+            entities: &[],
+            player: &mut away,
+            scene: &mut scene,
+            assets: &assets,
+            collision_binding: &binding,
+            resources: &resources,
+        }
+        .controlled_simulation_tick(Default::default())
+        .unwrap();
+        assert_eq!(roses(&away), 0);
+    }
+
     #[test]
     fn server_travel_moves_only_the_velocity() {
         let root = Path::new(env!("CARGO_MANIFEST_DIR"))

From 923fdee42e1cfa9596dff25e449050bc20ae34d4 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:34:07 +0100
Subject: [PATCH 091/270] Horizon shader packs: the check every pack passes
 before it runs

horizon_shader_api::check builds each stage as the renderer does and judges
it the same way wherever it runs (the game, the launcher, the registry's CI,
the coming horizon-shader tool): naga parses and validates it; the stage
function must have its signature; the pack's files declare no bindings, no
entry points and no horizon_ names; each override is an option of its type or
has a default, and each option is used; a stage stays within 20 000
expressions and 64 texture reads; and every entry point translates to SPIR-V,
Metal and HLSL with the options at their defaults, minimums and maximums.
Problems carry the pack's own file, line and column. Pack::sha256 gives the
reproducible package's hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                                 |   1 +
 crates/horizon-shader-api/Cargo.toml       |   6 +-
 crates/horizon-shader-api/src/check.rs     | 495 +++++++++++++++++++++
 crates/horizon-shader-api/src/lib.rs       |   2 +
 crates/horizon-shader-api/src/package.rs   |  15 +
 crates/horizon-shader-api/src/reference.rs |  11 +-
 crates/horizon-shader-api/tests/check.rs   | 146 ++++++
 docs/api/shaders-reference.md              |  10 +
 8 files changed, 682 insertions(+), 4 deletions(-)
 create mode 100644 crates/horizon-shader-api/src/check.rs
 create mode 100644 crates/horizon-shader-api/tests/check.rs

diff --git a/Cargo.lock b/Cargo.lock
index 7586c5d11..ee2312561 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1444,6 +1444,7 @@ dependencies = [
  "bytemuck",
  "naga",
  "serde",
+ "sha2",
  "toml",
  "zip",
 ]
diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml
index 249019042..caab5c736 100644
--- a/crates/horizon-shader-api/Cargo.toml
+++ b/crates/horizon-shader-api/Cargo.toml
@@ -8,12 +8,12 @@ description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-s
 
 [dependencies]
 bytemuck = { version = "1.24", features = ["derive"] }
+# Parses and validates a pack's WGSL, and translates it as wgpu does for Vulkan, Metal and DirectX 12.
+naga = { version = "30.0.1", features = ["wgsl-in", "spv-out", "msl-out", "hlsl-out"] }
 serde = { version = "1", features = ["derive"] }
+sha2 = "0.10"
 toml = "1.1.6"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 
-[dev-dependencies]
-naga = { version = "30.0.1", features = ["wgsl-in"] }
-
 [lints]
 workspace = true
diff --git a/crates/horizon-shader-api/src/check.rs b/crates/horizon-shader-api/src/check.rs
new file mode 100644
index 000000000..935dccc13
--- /dev/null
+++ b/crates/horizon-shader-api/src/check.rs
@@ -0,0 +1,495 @@
+//! The check a pack passes before it runs: in the game when it loads (a pack
+//! that fails keeps the last good one drawing), in the launcher before it
+//! installs, in the registry's CI, and in `horizon-shader check`.
+//!
+//! Each stage is built as the renderer builds it, parsed and validated by
+//! naga, checked against its signature and the API's rules (no bindings, no
+//! entry points, no `horizon_` names), then translated to SPIR-V, Metal and
+//! HLSL with its options at their defaults, minimums and maximums.
+use crate::manifest::{OptionKind, PackOption};
+use crate::package::Pack;
+use crate::stages::{Composed, StageKind, compose};
+use naga::valid::{Capabilities, ModuleInfo, ValidationFlags, Validator};
+use std::collections::HashSet;
+use std::fmt;
+
+/// naga expressions a stage may hold, over all its functions.
+pub const MAX_EXPRESSIONS: usize = 20_000;
+/// Texture reads (samples, gathers and loads) a stage may write.
+pub const MAX_TEXTURE_READS: usize = 64;
+
+/// What is wrong, and where: a file of the pack, with the line and column
+/// when known (0 when not).
+#[derive(Clone, Debug, PartialEq)]
+pub struct Problem {
+    pub file: String,
+    pub line: usize,
+    pub column: usize,
+    pub message: String,
+}
+
+impl fmt::Display for Problem {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        if self.line == 0 {
+            write!(f, "{}: {}", self.file, self.message)
+        } else {
+            write!(
+                f,
+                "{}:{}:{}: {}",
+                self.file, self.line, self.column, self.message
+            )
+        }
+    }
+}
+
+fn problem(file: &str, message: impl Into<String>) -> Problem {
+    Problem {
+        file: file.to_owned(),
+        line: 0,
+        column: 0,
+        message: message.into(),
+    }
+}
+
+/// One stage that passed, ready for the renderer.
+#[derive(Debug)]
+pub struct CheckedStage {
+    pub kind: StageKind,
+    pub file: String,
+    /// The manifest's name for it, else its file.
+    pub label: String,
+    pub module: naga::Module,
+    pub info: ModuleInfo,
+    pub expressions: usize,
+    pub texture_reads: usize,
+}
+
+#[derive(Debug)]
+pub struct Report {
+    pub stages: Vec<CheckedStage>,
+}
+
+/// Checks every stage of `pack`, and that each option is an `override` of
+/// its type in some stage. Returns every problem found, not just the first.
+pub fn check(pack: &Pack) -> Result<Report, Vec<Problem>> {
+    let m = &pack.manifest;
+    let stages = m
+        .sky
+        .iter()
+        .map(|s| (StageKind::Sky, s))
+        .chain(m.material.iter().map(|s| (StageKind::Material, s)))
+        .chain(m.post.iter().map(|s| (StageKind::Post, s)));
+    let (mut checked, mut problems) = (Vec::new(), Vec::new());
+    for (kind, stage) in stages {
+        match check_stage(pack, kind, &stage.file) {
+            Ok(mut c) => {
+                c.label = stage.name.clone().unwrap_or_else(|| stage.file.clone());
+                checked.push(c);
+            }
+            Err(p) => problems.extend(p),
+        }
+    }
+    if problems.is_empty() {
+        for option in &m.options {
+            let used = checked.iter().any(|c| {
+                c.module
+                    .overrides
+                    .iter()
+                    .any(|(_, o)| o.name.as_deref() == Some(&option.id))
+            });
+            if !used {
+                problems.push(problem(
+                    crate::MANIFEST,
+                    format!(
+                        "option {:?}: no stage declares `override {}: {}`",
+                        option.id,
+                        option.id,
+                        option.kind.wgsl_type()
+                    ),
+                ));
+            }
+        }
+    }
+    if problems.is_empty() {
+        Ok(Report { stages: checked })
+    } else {
+        Err(problems)
+    }
+}
+
+/// Builds and checks one stage of `pack` from its file.
+pub fn check_stage(pack: &Pack, kind: StageKind, file: &str) -> Result<CheckedStage, Vec<Problem>> {
+    // First without the entry points, so a missing or mistyped stage function
+    // is reported as such rather than as a call that doesn't resolve.
+    let mut own = compose(pack, kind, file);
+    let entries = own.parts.pop().expect("entries are the last part");
+    own.text.truncate(entries.1.start);
+    let module = parse(&own)?;
+    let mut problems = signature(&module, kind, file);
+    problems.extend(api_rules(&module, kind, &own));
+    problems.extend(options(&module, &pack.manifest.options, file));
+    if !problems.is_empty() {
+        return Err(problems);
+    }
+    let composed = compose(pack, kind, file);
+    let module = parse(&composed)?;
+    let info = Validator::new(ValidationFlags::all(), Capabilities::default())
+        .validate(&module)
+        .map_err(|e| {
+            let at = e.spans().next().and_then(|(span, _)| span.to_range());
+            let mut message = e.as_inner().to_string();
+            let mut source = std::error::Error::source(e.as_inner());
+            while let Some(s) = source {
+                message += &format!(": {s}");
+                source = s.source();
+            }
+            vec![located(&composed, at.map(|r| r.start), message)]
+        })?;
+    let (expressions, texture_reads) = cost(&module);
+    let mut problems = Vec::new();
+    if expressions > MAX_EXPRESSIONS {
+        problems.push(problem(
+            file,
+            format!("{expressions} expressions; a stage may hold {MAX_EXPRESSIONS}"),
+        ));
+    }
+    if texture_reads > MAX_TEXTURE_READS {
+        problems.push(problem(
+            file,
+            format!("{texture_reads} texture reads; a stage may write {MAX_TEXTURE_READS}"),
+        ));
+    }
+    problems.extend(translate(&module, &info, &pack.manifest.options, file));
+    if !problems.is_empty() {
+        return Err(problems);
+    }
+    Ok(CheckedStage {
+        kind,
+        file: file.to_owned(),
+        label: file.to_owned(),
+        module,
+        info,
+        expressions,
+        texture_reads,
+    })
+}
+
+fn located(composed: &Composed, offset: Option<usize>, message: String) -> Problem {
+    match offset {
+        Some(at) => {
+            let (file, line, column) = composed.locate(at);
+            Problem {
+                file: file.to_owned(),
+                line,
+                column,
+                message,
+            }
+        }
+        None => problem(&composed.parts[composed.parts.len() - 2].0, message),
+    }
+}
+
+fn parse(composed: &Composed) -> Result<naga::Module, Vec<Problem>> {
+    naga::front::wgsl::parse_str(&composed.text).map_err(|e| {
+        let label = e.labels().next();
+        let mut message = e.message().to_owned();
+        if let Some((_, text)) = label.filter(|(_, t)| !t.is_empty()) {
+            message += &format!(" ({text})");
+        }
+        let at = label.and_then(|(span, _)| span.to_range()).map(|r| r.start);
+        vec![located(composed, at, message)]
+    })
+}
+
+fn type_name(module: &naga::Module, ty: naga::Handle<naga::Type>) -> String {
+    let t = &module.types[ty];
+    if let Some(name) = &t.name {
+        return name.clone();
+    }
+    match t.inner {
+        naga::TypeInner::Scalar(s) => scalar_name(s).to_owned(),
+        naga::TypeInner::Vector { size, scalar } => {
+            format!("vec{}<{}>", size as u8, scalar_name(scalar))
+        }
+        _ => format!("{:?}", t.inner),
+    }
+}
+
+fn scalar_name(s: naga::Scalar) -> &'static str {
+    match (s.kind, s.width) {
+        (naga::ScalarKind::Bool, _) => "bool",
+        (naga::ScalarKind::Float, 4) => "f32",
+        (naga::ScalarKind::Sint, 4) => "i32",
+        (naga::ScalarKind::Uint, 4) => "u32",
+        _ => "another scalar",
+    }
+}
+
+fn signature(module: &naga::Module, kind: StageKind, file: &str) -> Vec<Problem> {
+    let found = module
+        .functions
+        .iter()
+        .find(|(_, f)| f.name.as_deref() == Some(kind.function()));
+    let Some((_, f)) = found else {
+        return vec![problem(file, format!("defines no `{}`", kind.signature()))];
+    };
+    let args: Vec<String> = f
+        .arguments
+        .iter()
+        .map(|a| type_name(module, a.ty))
+        .collect();
+    let result = f.result.as_ref().map(|r| type_name(module, r.ty));
+    if args == [kind.input().name] && result.as_deref() == Some(kind.output()) {
+        return Vec::new();
+    }
+    vec![problem(
+        file,
+        format!(
+            "`fn {}({}) -> {}` should be `{}`",
+            kind.function(),
+            args.join(", "),
+            result.as_deref().unwrap_or("()"),
+            kind.signature()
+        ),
+    )]
+}
+
+/// The names of everything a module defines at its top level.
+fn names(module: &naga::Module) -> HashSet<String> {
+    let types = module.types.iter().filter_map(|(_, t)| t.name.clone());
+    let functions = module.functions.iter().filter_map(|(_, f)| f.name.clone());
+    let globals = module
+        .global_variables
+        .iter()
+        .filter_map(|(_, g)| g.name.clone());
+    let constants = module.constants.iter().filter_map(|(_, c)| c.name.clone());
+    let overrides = module.overrides.iter().filter_map(|(_, o)| o.name.clone());
+    types
+        .chain(functions)
+        .chain(globals)
+        .chain(constants)
+        .chain(overrides)
+        .collect()
+}
+
+/// A pack's files declare no bindings, no entry points and no `horizon_`
+/// names: what the prelude doesn't define is the pack's.
+fn api_rules(module: &naga::Module, kind: StageKind, own: &Composed) -> Vec<Problem> {
+    let prelude = naga::front::wgsl::parse_str(&kind.prelude()).expect("the prelude parses");
+    let ours = names(&prelude);
+    let file = &own.parts[own.parts.len() - 1].0;
+    let mut problems = Vec::new();
+    for e in &module.entry_points {
+        problems.push(problem(
+            file,
+            format!(
+                "declares the entry point `{}`: a stage is a function, Horizon adds the entry points",
+                e.name
+            ),
+        ));
+    }
+    for (_, g) in module.global_variables.iter() {
+        let name = g.name.clone().unwrap_or_default();
+        if g.binding.is_some() && !ours.contains(&name) {
+            problems.push(problem(
+                file,
+                format!(
+                    "declares the binding `{name}`: a stage reads only the resources of its prelude"
+                ),
+            ));
+        }
+    }
+    let mut theirs: Vec<String> = names(module)
+        .into_iter()
+        .filter(|n| !ours.contains(n) && n.starts_with("horizon_"))
+        .collect();
+    theirs.sort();
+    for name in theirs {
+        problems.push(problem(
+            file,
+            format!("`{name}`: names starting with horizon_ are Horizon's"),
+        ));
+    }
+    problems
+}
+
+/// Each `override` is an option of its type, or has a default of its own.
+fn options(module: &naga::Module, options: &[PackOption], file: &str) -> Vec<Problem> {
+    let mut problems = Vec::new();
+    for (_, o) in module.overrides.iter() {
+        let name = o.name.as_deref().unwrap_or("?");
+        let ty = type_name(module, o.ty);
+        match options.iter().find(|opt| opt.id == name) {
+            Some(opt) if ty != opt.kind.wgsl_type() => problems.push(problem(
+                file,
+                format!(
+                    "`override {name}: {ty}`: option {name:?} is a {}, so its override is `{}`",
+                    kind_name(&opt.kind),
+                    opt.kind.wgsl_type()
+                ),
+            )),
+            None if o.init.is_none() => problems.push(problem(
+                file,
+                format!("`override {name}` has no default and no [[options]] entry"),
+            )),
+            _ => {}
+        }
+    }
+    problems
+}
+
+fn kind_name(kind: &OptionKind) -> &'static str {
+    match kind {
+        OptionKind::Bool { .. } => "bool",
+        OptionKind::Float { .. } => "float",
+        OptionKind::Int { .. } => "int",
+        OptionKind::Choice { .. } => "choice",
+    }
+}
+
+fn cost(module: &naga::Module) -> (usize, usize) {
+    let functions = module
+        .functions
+        .iter()
+        .map(|(_, f)| f)
+        .chain(module.entry_points.iter().map(|e| &e.function));
+    let (mut expressions, mut reads) = (0, 0);
+    for f in functions {
+        expressions += f.expressions.len();
+        reads += f
+            .expressions
+            .iter()
+            .filter(|(_, e)| {
+                matches!(
+                    e,
+                    naga::Expression::ImageSample { .. } | naga::Expression::ImageLoad { .. }
+                )
+            })
+            .count();
+    }
+    (expressions, reads)
+}
+
+/// The option values a pack is translated with: its defaults, then every
+/// option at its minimum, then at its maximum.
+fn option_sets(options: &[PackOption]) -> [(&'static str, Vec<(String, f64)>); 3] {
+    let at = |pick: fn(&OptionKind) -> f64| {
+        options
+            .iter()
+            .map(|o| (o.id.clone(), pick(&o.kind)))
+            .collect()
+    };
+    [
+        ("defaults", at(OptionKind::default_constant)),
+        (
+            "minimums",
+            at(|k| match *k {
+                OptionKind::Bool { .. } | OptionKind::Choice { .. } => 0.0,
+                OptionKind::Float { min, .. } => f64::from(min),
+                OptionKind::Int { min, .. } => f64::from(min),
+            }),
+        ),
+        (
+            "maximums",
+            at(|k| match k {
+                OptionKind::Bool { .. } => 1.0,
+                OptionKind::Choice { values, .. } => (values.len() - 1) as f64,
+                OptionKind::Float { max, .. } => f64::from(*max),
+                OptionKind::Int { max, .. } => f64::from(*max),
+            }),
+        ),
+    ]
+}
+
+/// Translates every entry point for Vulkan (SPIR-V), Metal and DirectX 12
+/// (HLSL) with each option set, as wgpu does when it builds the pipelines.
+fn translate(
+    module: &naga::Module,
+    info: &ModuleInfo,
+    options: &[PackOption],
+    file: &str,
+) -> Vec<Problem> {
+    let present: HashSet<&str> = module
+        .overrides
+        .iter()
+        .filter_map(|(_, o)| o.name.as_deref())
+        .collect();
+    let mut problems = Vec::new();
+    for (set, values) in option_sets(options) {
+        let mut constants = naga::back::PipelineConstants::default();
+        for (id, value) in values
+            .into_iter()
+            .filter(|(id, _)| present.contains(id.as_str()))
+        {
+            constants.insert(id, value);
+        }
+        for e in &module.entry_points {
+            let fail = |backend: &str, err: String| {
+                problem(
+                    file,
+                    format!("with the options at their {set}, {backend} refuses it: {err}"),
+                )
+            };
+            let processed = naga::back::pipeline_constants::process_overrides(
+                module,
+                info,
+                Some((e.stage, &e.name)),
+                &constants,
+            );
+            let (m, i) = match processed {
+                Ok(p) => p,
+                Err(err) => {
+                    problems.push(fail("the override step", err.to_string()));
+                    return problems;
+                }
+            };
+            let spv = naga::back::spv::write_vec(
+                &m,
+                &i,
+                &naga::back::spv::Options::default(),
+                Some(&naga::back::spv::PipelineOptions {
+                    shader_stage: e.stage,
+                    entry_point: e.name.clone(),
+                }),
+            );
+            let msl = naga::back::msl::write_string(
+                &m,
+                &i,
+                &naga::back::msl::Options {
+                    lang_version: (2, 2),
+                    ..Default::default()
+                },
+                &naga::back::msl::PipelineOptions {
+                    entry_point: Some((e.stage, e.name.clone())),
+                    ..Default::default()
+                },
+            );
+            let mut hlsl = String::new();
+            let hlsl_result = naga::back::hlsl::Writer::new(
+                &mut hlsl,
+                &naga::back::hlsl::Options::default(),
+                &naga::back::hlsl::PipelineOptions {
+                    entry_point: Some((e.stage, e.name.clone())),
+                },
+            )
+            .write(&m, &i, None);
+            let errors = [
+                ("Vulkan (SPIR-V)", spv.err().map(|e| e.to_string())),
+                ("Metal", msl.err().map(|e| e.to_string())),
+                (
+                    "DirectX 12 (HLSL)",
+                    hlsl_result.err().map(|e| e.to_string()),
+                ),
+            ];
+            for (backend, err) in errors {
+                if let Some(err) = err {
+                    problems.push(fail(backend, err));
+                }
+            }
+            if !problems.is_empty() {
+                return problems;
+            }
+        }
+    }
+    problems
+}
diff --git a/crates/horizon-shader-api/src/lib.rs b/crates/horizon-shader-api/src/lib.rs
index 1d85e7a5e..ff676f64f 100644
--- a/crates/horizon-shader-api/src/lib.rs
+++ b/crates/horizon-shader-api/src/lib.rs
@@ -3,12 +3,14 @@
 //! a folder or a `.hshader`. This crate reads and checks packs; the game, the
 //! launcher and the registry all use it, so a pack is judged the same way
 //! everywhere.
+pub mod check;
 pub mod inputs;
 pub mod manifest;
 pub mod package;
 pub mod reference;
 pub mod stages;
 
+pub use check::{Problem, Report, check};
 pub use inputs::Frame;
 pub use manifest::{API, MANIFEST, Manifest, OptionKind, PackOption, SCHEMA, Stage};
 pub use package::{EXTENSION, Pack};
diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs
index d95e8d321..e2e644a04 100644
--- a/crates/horizon-shader-api/src/package.rs
+++ b/crates/horizon-shader-api/src/package.rs
@@ -148,6 +148,21 @@ impl Pack {
         }
         Ok(zip.finish().map_err(err)?.into_inner())
     }
+
+    /// The SHA-256 of [`Pack::package`], in lowercase hex: the pack's
+    /// identity in the registry.
+    pub fn sha256(&self) -> Result<String, String> {
+        Ok(sha256_hex(&self.package()?))
+    }
+}
+
+/// SHA-256 in lowercase hex.
+pub fn sha256_hex(bytes: &[u8]) -> String {
+    use sha2::Digest;
+    sha2::Sha256::digest(bytes)
+        .iter()
+        .map(|b| format!("{b:02x}"))
+        .collect()
 }
 
 fn read_dir(dir: &Path, prefix: &str, files: &mut BTreeMap<String, Vec<u8>>) -> Result<(), String> {
diff --git a/crates/horizon-shader-api/src/reference.rs b/crates/horizon-shader-api/src/reference.rs
index 9847ccf90..df74b7633 100644
--- a/crates/horizon-shader-api/src/reference.rs
+++ b/crates/horizon-shader-api/src/reference.rs
@@ -1,5 +1,6 @@
 //! docs/api/shaders-reference.md, generated from the stages and inputs this
 //! crate defines (`tests/reference.rs` fails when the file drifts).
+use crate::check::{MAX_EXPRESSIONS, MAX_TEXTURE_READS};
 use crate::inputs::{Frame, SURFACE, Struct};
 use crate::manifest::{API, MAX_GPU_MS, MAX_OPTIONS, MAX_POST_PASSES};
 use crate::package::{MAX_TOTAL, MAX_WGSL};
@@ -80,7 +81,15 @@ pub fn markdown() -> String {
          | `choice` | `values`, `default` (one of them) | `override <id>: u32`, the value's index |\n\n\
          ## Limits\n\n\
          - {MAX_POST_PASSES} post passes, {MAX_OPTIONS} options, `budget.gpu_ms` up to {MAX_GPU_MS}.\n\
-         - {} KiB per WGSL file, {} MiB per pack.\n",
+         - {} KiB per WGSL file, {} MiB per pack.\n\
+         - Per stage: {MAX_EXPRESSIONS} naga expressions over all its functions, {MAX_TEXTURE_READS} texture reads (samples,\n  \
+         gathers and loads, the prelude's included).\n\n\
+         ## The check\n\n\
+         A pack runs only after it passes `horizon_shader_api::check` (the game when it loads a pack, the launcher before it\n\
+         installs one, the registry's CI): each stage is parsed and validated by naga, checked against its signature and\n\
+         the rules above, and translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL) with its options at their\n\
+         defaults, minimums and maximums. Every option must be an `override` of its type in some stage; an `override`\n\
+         that is no option needs a default.\n",
         MAX_WGSL >> 10,
         MAX_TOTAL >> 20
     );
diff --git a/crates/horizon-shader-api/tests/check.rs b/crates/horizon-shader-api/tests/check.rs
new file mode 100644
index 000000000..4c6168a43
--- /dev/null
+++ b/crates/horizon-shader-api/tests/check.rs
@@ -0,0 +1,146 @@
+//! `check`: the sample pack passes, and each kind of mistake is reported
+//! with the pack's own file and line.
+use horizon_shader_api::{MANIFEST, Pack, Problem, check};
+use std::path::Path;
+
+fn sample() -> Pack {
+    Pack::read(Path::new(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/tests/samples/schema-1"
+    )))
+    .unwrap()
+}
+
+/// The sample with `file` replaced by `text`, checked.
+fn problems(file: &str, text: &str) -> Vec<Problem> {
+    let mut files = sample().files;
+    files.insert(file.into(), text.as_bytes().to_vec());
+    check(&Pack::from_files(files).unwrap()).expect_err("should fail")
+}
+
+fn one(file: &str, text: &str, needle: &str) -> Problem {
+    let p = problems(file, text);
+    assert!(
+        p.iter().any(|p| p.message.contains(needle)),
+        "{needle:?} not in {p:#?}"
+    );
+    p.into_iter().find(|p| p.message.contains(needle)).unwrap()
+}
+
+const GRADE: &str = "post/grade.wgsl";
+
+#[test]
+fn the_sample_passes() {
+    let pack = sample();
+    let report = check(&pack).unwrap();
+    let labels: Vec<_> = report.stages.iter().map(|s| s.label.as_str()).collect();
+    assert_eq!(
+        labels,
+        ["sky.wgsl", "Terrain", "Colour grade", "post/vignette.wgsl"]
+    );
+    assert!(report.stages.iter().all(|s| s.expressions > 0));
+    let post = &report.stages[2];
+    assert!(post.texture_reads >= 2, "the entry point samples and loads");
+    let sha = pack.sha256().unwrap();
+    assert_eq!(sha.len(), 64);
+    assert_eq!(sha, sample().sha256().unwrap());
+}
+
+#[test]
+fn a_syntax_error_points_at_its_line() {
+    let p = one(
+        GRADE,
+        "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\nfn post(input: PostInput) -> vec4<f32> {\n    return input.color +;\n}\n",
+        "expected",
+    );
+    assert_eq!((p.file.as_str(), p.line), (GRADE, 4), "{p}");
+    assert!(p.to_string().starts_with("post/grade.wgsl:4:"), "{p}");
+}
+
+#[test]
+fn the_stage_function_must_have_its_signature() {
+    let header = "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\n";
+    one(
+        GRADE,
+        &format!("{header}fn post(input: PostInput) -> vec3<f32> {{ return input.color.rgb; }}\n"),
+        "`fn post(PostInput) -> vec3<f32>` should be `fn post(input: PostInput) -> vec4<f32>`",
+    );
+    one(
+        GRADE,
+        &format!("{header}fn grade(input: PostInput) -> vec4<f32> {{ return input.color; }}\n"),
+        "defines no `fn post(input: PostInput) -> vec4<f32>`",
+    );
+}
+
+#[test]
+fn a_pack_declares_no_bindings_entry_points_or_horizon_names() {
+    let body = "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\nfn post(input: PostInput) -> vec4<f32> { return input.color; }\n";
+    one(
+        GRADE,
+        &format!("@group(3) @binding(9) var extra: texture_2d<f32>;\n{body}"),
+        "declares the binding `extra`",
+    );
+    one(
+        GRADE,
+        &format!(
+            "{body}@fragment fn main() -> @location(0) vec4<f32> {{ return vec4<f32>(1.0); }}\n"
+        ),
+        "declares the entry point `main`",
+    );
+    one(
+        GRADE,
+        &format!("{body}fn horizon_mine() {{}}\n"),
+        "`horizon_mine`: names starting with horizon_",
+    );
+}
+
+#[test]
+fn overrides_match_the_options() {
+    let post = "fn post(input: PostInput) -> vec4<f32> { return input.color; }\n";
+    one(
+        GRADE,
+        &format!("override saturation: i32 = 1;\noverride tonemap: u32 = 1u;\n{post}"),
+        "option \"saturation\" is a float, so its override is `f32`",
+    );
+    one(
+        GRADE,
+        &format!(
+            "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\noverride extra: f32;\n{post}"
+        ),
+        "`override extra` has no default and no [[options]] entry",
+    );
+    let p = one(
+        GRADE,
+        &format!("override saturation: f32 = 1.1;\n{post}"),
+        "option \"tonemap\": no stage declares `override tonemap: u32`",
+    );
+    assert_eq!(p.file, MANIFEST);
+}
+
+#[test]
+fn validation_errors_point_into_the_pack() {
+    // A compute-only barrier in a fragment stage passes the parser, not the validator.
+    let p = one(
+        GRADE,
+        "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\n\
+         fn post(input: PostInput) -> vec4<f32> {\n    \
+         workgroupBarrier();\n    \
+         return input.color;\n}\n",
+        "forbidden at this stage",
+    );
+    assert_eq!(p.file, GRADE, "{p}");
+}
+
+#[test]
+fn texture_reads_have_a_budget() {
+    let reads: String = (0..70)
+        .map(|i| format!("    c += textureLoad(previous, vec2<i32>({i}, 0), 0);\n"))
+        .collect();
+    one(
+        GRADE,
+        &format!(
+            "override saturation: f32 = 1.1;\noverride tonemap: u32 = 1u;\nfn post(input: PostInput) -> vec4<f32> {{\n    var c = input.color;\n{reads}    return c;\n}}\n"
+        ),
+        "texture reads; a stage may write 64",
+    );
+}
diff --git a/docs/api/shaders-reference.md b/docs/api/shaders-reference.md
index ed574978d..f9682a1a4 100644
--- a/docs/api/shaders-reference.md
+++ b/docs/api/shaders-reference.md
@@ -150,3 +150,13 @@ Each `[[options]]` entry sets the WGSL `override` of the same name when the pipe
 
 - 8 post passes, 64 options, `budget.gpu_ms` up to 16.
 - 256 KiB per WGSL file, 8 MiB per pack.
+- Per stage: 20000 naga expressions over all its functions, 64 texture reads (samples,
+  gathers and loads, the prelude's included).
+
+## The check
+
+A pack runs only after it passes `horizon_shader_api::check` (the game when it loads a pack, the launcher before it
+installs one, the registry's CI): each stage is parsed and validated by naga, checked against its signature and
+the rules above, and translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL) with its options at their
+defaults, minimums and maximums. Every option must be an `override` of its type in some stage; an `override`
+that is no option needs a default.

From 49f62d02cb01596462023f46c803e4cc1053b2f0 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:38:23 +0100
Subject: [PATCH 092/270] Horizon shader packs: horizon-shader new/check/pack,
 templates, an example pack and the guide

The SDK's tool, in horizon-shader-api: `horizon-shader new <dir> --template
post|sky|material` makes a pack that passes the check, `check <pack>...
[--json]` runs the check the game, the launcher and the registry run and
prints each stage's cost and the pack's SHA-256 or every problem at its
file:line:column, and `pack <dir>` checks then writes the reproducible
.hshader. Golden Hour, the example pack, warms the sky around a low sun and
adds a soft glow and a colour grade, with five options. docs/shaders.md is the
authors' guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                                    |   1 +
 crates/horizon-shader-api/Cargo.toml          |   3 +-
 .../packs/golden_hour/README.md               |   4 +
 .../packs/golden_hour/common.wgsl             |  13 +
 .../packs/golden_hour/horizon-shaders.toml    |  69 ++++
 .../packs/golden_hour/post/glow.wgsl          |  22 ++
 .../packs/golden_hour/post/grade.wgsl         |  19 ++
 .../packs/golden_hour/sky.wgsl                |  14 +
 .../src/bin/horizon-shader.rs                 | 307 ++++++++++++++++++
 crates/horizon-shader-api/src/check.rs        |   2 +-
 .../templates/material/horizon-shaders.toml   |  18 +
 .../templates/material/material.wgsl          |   9 +
 .../templates/post/horizon-shaders.toml       |  22 ++
 .../templates/post/post.wgsl                  |   9 +
 .../templates/sky/horizon-shaders.toml        |  18 +
 .../horizon-shader-api/templates/sky/sky.wgsl |   9 +
 crates/horizon-shader-api/tests/sdk.rs        |  92 ++++++
 docs/README.md                                |   1 +
 docs/api/shaders.md                           |   5 +-
 docs/shaders.md                               | 127 ++++++++
 20 files changed, 761 insertions(+), 3 deletions(-)
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/README.md
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/common.wgsl
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/horizon-shaders.toml
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/post/grade.wgsl
 create mode 100644 crates/horizon-shader-api/packs/golden_hour/sky.wgsl
 create mode 100644 crates/horizon-shader-api/src/bin/horizon-shader.rs
 create mode 100644 crates/horizon-shader-api/templates/material/horizon-shaders.toml
 create mode 100644 crates/horizon-shader-api/templates/material/material.wgsl
 create mode 100644 crates/horizon-shader-api/templates/post/horizon-shaders.toml
 create mode 100644 crates/horizon-shader-api/templates/post/post.wgsl
 create mode 100644 crates/horizon-shader-api/templates/sky/horizon-shaders.toml
 create mode 100644 crates/horizon-shader-api/templates/sky/sky.wgsl
 create mode 100644 crates/horizon-shader-api/tests/sdk.rs
 create mode 100644 docs/shaders.md

diff --git a/Cargo.lock b/Cargo.lock
index ee2312561..70c3c831c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1444,6 +1444,7 @@ dependencies = [
  "bytemuck",
  "naga",
  "serde",
+ "serde_json",
  "sha2",
  "toml",
  "zip",
diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml
index caab5c736..3d365cd83 100644
--- a/crates/horizon-shader-api/Cargo.toml
+++ b/crates/horizon-shader-api/Cargo.toml
@@ -4,13 +4,14 @@ version = "0.1.0"
 edition.workspace = true
 license.workspace = true
 rust-version = "1.85"
-description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-shaders.toml, the .hshader package"
+description = "Horizon's own shader packs (WGSL, docs/shaders.md): the format, the stages, the check, and the horizon-shader tool"
 
 [dependencies]
 bytemuck = { version = "1.24", features = ["derive"] }
 # Parses and validates a pack's WGSL, and translates it as wgpu does for Vulkan, Metal and DirectX 12.
 naga = { version = "30.0.1", features = ["wgsl-in", "spv-out", "msl-out", "hlsl-out"] }
 serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 sha2 = "0.10"
 toml = "1.1.6"
 zip = { version = "2", default-features = false, features = ["deflate"] }
diff --git a/crates/horizon-shader-api/packs/golden_hour/README.md b/crates/horizon-shader-api/packs/golden_hour/README.md
new file mode 100644
index 000000000..943bce85a
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/README.md
@@ -0,0 +1,4 @@
+# Golden Hour
+
+Horizon's example shader pack (docs/shaders.md): a sky stage and two post passes, with five options. Check it with
+`horizon-shader check crates/horizon-shader-api/packs/golden_hour`.
diff --git a/crates/horizon-shader-api/packs/golden_hour/common.wgsl b/crates/horizon-shader-api/packs/golden_hour/common.wgsl
new file mode 100644
index 000000000..687e76f4b
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/common.wgsl
@@ -0,0 +1,13 @@
+fn luminance(c: vec3<f32>) -> f32 {
+    return dot(c, vec3<f32>(0.2126, 0.7152, 0.0722));
+}
+
+// 1 while the sun is up in the Overworld, fading out around the horizon.
+fn daylight() -> f32 {
+    return select(0.0, smoothstep(-0.1, 0.1, frame.sun_direction.y), frame.dimension == 0);
+}
+
+// 1 when the sun is on the horizon, 0 from a quarter of the way up.
+fn sun_low() -> f32 {
+    return 1.0 - smoothstep(0.0, 0.35, abs(frame.sun_direction.y));
+}
diff --git a/crates/horizon-shader-api/packs/golden_hour/horizon-shaders.toml b/crates/horizon-shader-api/packs/golden_hour/horizon-shaders.toml
new file mode 100644
index 000000000..8b67cff3b
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/horizon-shaders.toml
@@ -0,0 +1,69 @@
+schema = 1
+id = "golden_hour"
+name = "Golden Hour"
+version = "1.0.0"
+api = "0.1"
+description = "Warm light at sunrise and sunset, a soft glow around bright things and a gentle colour grade."
+authors = ["Horizon"]
+license = "MIT"
+shared = ["common.wgsl"]
+
+[sky]
+file = "sky.wgsl"
+name = "Warm horizon"
+
+[[post]]
+file = "post/glow.wgsl"
+name = "Glow"
+
+[[post]]
+file = "post/grade.wgsl"
+name = "Colour grade"
+
+[[options]]
+id = "sun_glow"
+name = "Sunset glow"
+description = "How warm the sky is around a low sun."
+type = "float"
+default = 0.6
+min = 0.0
+max = 1.0
+step = 0.05
+
+[[options]]
+id = "glow"
+name = "Glow"
+description = "The soft halo around bright things: the sun, lava, torches."
+type = "float"
+default = 0.35
+min = 0.0
+max = 1.0
+step = 0.05
+
+[[options]]
+id = "warmth"
+name = "Warmth"
+description = "How golden the light turns when the sun is low."
+type = "float"
+default = 0.4
+min = 0.0
+max = 1.0
+step = 0.05
+
+[[options]]
+id = "saturation"
+name = "Saturation"
+type = "float"
+default = 1.1
+min = 0.0
+max = 2.0
+step = 0.05
+
+[[options]]
+id = "vignette"
+name = "Vignette"
+type = "bool"
+default = true
+
+[budget]
+gpu_ms = 1.0
diff --git a/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl b/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
new file mode 100644
index 000000000..4d523c9ef
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
@@ -0,0 +1,22 @@
+// A soft halo around bright pixels: twelve taps on two rings, scaled with
+// the picture's height so it looks the same at any resolution.
+override glow: f32 = 0.35;
+
+fn bright(c: vec3<f32>) -> vec3<f32> {
+    return c * smoothstep(0.7, 1.0, luminance(c));
+}
+
+fn post(input: PostInput) -> vec4<f32> {
+    if glow <= 0.0 {
+        return input.color;
+    }
+    let step = frame.resolution.y / 720.0 / frame.resolution;
+    var sum = vec3<f32>(0.0);
+    for (var i = 0; i < 12; i++) {
+        let angle = f32(i) * 0.5235988;
+        let radius = select(3.0, 7.0, (i & 1) == 1);
+        let offset = vec2<f32>(cos(angle), sin(angle)) * radius * step;
+        sum += bright(textureSampleLevel(previous, linear_sampler, input.uv + offset, 0.0).rgb);
+    }
+    return vec4<f32>(input.color.rgb + sum * (glow / 6.0), input.color.a);
+}
diff --git a/crates/horizon-shader-api/packs/golden_hour/post/grade.wgsl b/crates/horizon-shader-api/packs/golden_hour/post/grade.wgsl
new file mode 100644
index 000000000..809b0877e
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/post/grade.wgsl
@@ -0,0 +1,19 @@
+// Golden light when the sun is low, a soft shoulder for the brightest
+// colours (white stays white), saturation and a light vignette.
+override warmth: f32 = 0.4;
+override saturation: f32 = 1.1;
+override vignette: bool = true;
+
+fn post(input: PostInput) -> vec4<f32> {
+    var c = input.color.rgb;
+    let golden = warmth * mix(0.3, 1.0, sun_low()) * daylight() * (1.0 - frame.rain * 0.7);
+    c *= mix(vec3<f32>(1.0), vec3<f32>(1.08, 1.0, 0.86), golden);
+    c = c / (1.0 + 0.25 * c) * 1.25;
+    c = mix(vec3<f32>(luminance(c)), c, saturation);
+    if vignette {
+        let aspect = frame.resolution.x / frame.resolution.y;
+        let d = length((input.uv - 0.5) * vec2<f32>(aspect, 1.0)) / length(vec2<f32>(aspect, 1.0) * 0.5);
+        c *= 1.0 - smoothstep(0.55, 1.1, d) * 0.3;
+    }
+    return vec4<f32>(clamp(c, vec3<f32>(0.0), vec3<f32>(1.0)), input.color.a);
+}
diff --git a/crates/horizon-shader-api/packs/golden_hour/sky.wgsl b/crates/horizon-shader-api/packs/golden_hour/sky.wgsl
new file mode 100644
index 000000000..dbf1e0ab5
--- /dev/null
+++ b/crates/horizon-shader-api/packs/golden_hour/sky.wgsl
@@ -0,0 +1,14 @@
+// Warms the sky around a low sun, and deepens the blue overhead by day.
+override sun_glow: f32 = 0.6;
+
+fn sky(input: SkyInput) -> vec4<f32> {
+    let d = input.direction;
+    let toward = max(dot(d, frame.sun_direction), 0.0);
+    let near_horizon = 1.0 - smoothstep(0.0, 0.4, abs(d.y));
+    let day = daylight() * (1.0 - frame.rain);
+    let halo = pow(toward, 6.0) * 0.6 + near_horizon * toward * toward * 0.4;
+    let warm = vec3<f32>(1.0, 0.55, 0.25) * halo * sun_low() * day * sun_glow;
+    let zenith = smoothstep(0.1, 1.0, d.y) * day * 0.12;
+    let base = input.color.rgb * (1.0 - zenith * vec3<f32>(0.5, 0.25, 0.0));
+    return vec4<f32>(base + warm, input.color.a);
+}
diff --git a/crates/horizon-shader-api/src/bin/horizon-shader.rs b/crates/horizon-shader-api/src/bin/horizon-shader.rs
new file mode 100644
index 000000000..b6130282d
--- /dev/null
+++ b/crates/horizon-shader-api/src/bin/horizon-shader.rs
@@ -0,0 +1,307 @@
+//! `horizon-shader`: make Horizon shader packs (docs/shaders.md).
+//!
+//! - `new <dir> [--template post|sky|material] [--name "Name"]`: a pack from a template.
+//! - `check <pack>... [--json]`: the check the game, the launcher and the registry run.
+//! - `pack <dir> [--out <file.hshader>]`: check, then write the reproducible `.hshader`.
+use horizon_shader_api::{EXTENSION, MANIFEST, Pack, Problem, check, package::sha256_hex};
+use serde::Serialize;
+use std::{path::Path, process::ExitCode};
+
+const USAGE: &str = "usage: horizon-shader new <dir> [--template post|sky|material] [--name \"Name\"] | check <pack>... [--json] | pack <dir> [--out <file.hshader>]";
+
+/// (template, its files as (name, text)).
+const TEMPLATES: [(&str, [(&str, &str); 2]); 3] = [
+    (
+        "post",
+        [
+            (
+                MANIFEST,
+                include_str!("../../templates/post/horizon-shaders.toml"),
+            ),
+            ("post.wgsl", include_str!("../../templates/post/post.wgsl")),
+        ],
+    ),
+    (
+        "sky",
+        [
+            (
+                MANIFEST,
+                include_str!("../../templates/sky/horizon-shaders.toml"),
+            ),
+            ("sky.wgsl", include_str!("../../templates/sky/sky.wgsl")),
+        ],
+    ),
+    (
+        "material",
+        [
+            (
+                MANIFEST,
+                include_str!("../../templates/material/horizon-shaders.toml"),
+            ),
+            (
+                "material.wgsl",
+                include_str!("../../templates/material/material.wgsl"),
+            ),
+        ],
+    ),
+];
+
+fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let result = match args.first().map(String::as_str) {
+        Some("new") => new(&args[1..]),
+        Some("check") => check_command(&args[1..]),
+        Some("pack") => pack(&args[1..]),
+        _ => Err(USAGE.into()),
+    };
+    match result {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(e) => {
+            eprintln!("error: {e}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+/// The value after `flag` in `args`.
+fn flag<'a>(args: &'a [String], flag: &str) -> Option<&'a str> {
+    let i = args.iter().position(|a| a == flag)?;
+    args.get(i + 1).map(String::as_str)
+}
+
+/// The arguments that are neither flags nor their values.
+fn positional(args: &[String], flags: &[&str]) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut it = args.iter();
+    while let Some(a) = it.next() {
+        if flags.contains(&a.as_str()) {
+            it.next();
+        } else if !a.starts_with("--") {
+            out.push(a.clone());
+        }
+    }
+    out
+}
+
+fn new(args: &[String]) -> Result<(), String> {
+    let [dir] = positional(args, &["--template", "--name"])
+        .try_into()
+        .map_err(|_| USAGE.to_string())?;
+    let dir = Path::new(&dir);
+    if dir.exists() {
+        return Err(format!("{} already exists", dir.display()));
+    }
+    let template = flag(args, "--template").unwrap_or("post");
+    let (_, files) = TEMPLATES
+        .iter()
+        .find(|(name, _)| *name == template)
+        .ok_or_else(|| format!("no template {template:?}: post, sky or material"))?;
+    let base = dir
+        .file_name()
+        .and_then(|n| n.to_str())
+        .ok_or("the path needs a folder name")?;
+    let mut id: String = base
+        .chars()
+        .map(|c| match c {
+            'a'..='z' | '0'..='9' => c,
+            'A'..='Z' => c.to_ascii_lowercase(),
+            _ => '_',
+        })
+        .collect();
+    id.truncate(64);
+    let name = flag(args, "--name").map_or_else(|| base.replace(['-', '_'], " "), str::to_owned);
+    std::fs::create_dir_all(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
+    for (file, text) in files {
+        let text = text
+            .replace("{{id}}", &id)
+            .replace("{{name}}", &name.replace('"', "'"));
+        let path = dir.join(file);
+        std::fs::write(&path, text).map_err(|e| format!("{}: {e}", path.display()))?;
+    }
+    println!(
+        "Made {} from the {template} template. Edit it, then: horizon-shader check {}",
+        dir.display(),
+        dir.display()
+    );
+    Ok(())
+}
+
+#[derive(Serialize)]
+struct StageJson {
+    stage: &'static str,
+    file: String,
+    label: String,
+    expressions: usize,
+    texture_reads: usize,
+}
+
+#[derive(Serialize)]
+struct ProblemJson {
+    file: String,
+    line: usize,
+    column: usize,
+    message: String,
+}
+
+#[derive(Serialize)]
+struct CheckJson {
+    path: String,
+    ok: bool,
+    id: Option<String>,
+    version: Option<String>,
+    api: Option<String>,
+    /// The file's own SHA-256 (a `.hshader`), else the reproducible package's.
+    sha256: Option<String>,
+    stages: Vec<StageJson>,
+    problems: Vec<ProblemJson>,
+}
+
+/// Reads and checks the pack at `path`.
+fn check_one(path: &Path) -> CheckJson {
+    let mut out = CheckJson {
+        path: path.display().to_string(),
+        ok: false,
+        id: None,
+        version: None,
+        api: None,
+        sha256: None,
+        stages: Vec::new(),
+        problems: Vec::new(),
+    };
+    let problem = |message: String| ProblemJson {
+        file: path.display().to_string(),
+        line: 0,
+        column: 0,
+        message,
+    };
+    let pack = match Pack::read(path) {
+        Ok(p) => p,
+        Err(e) => {
+            out.problems.push(problem(e));
+            return out;
+        }
+    };
+    out.id = Some(pack.manifest.id.clone());
+    out.version = Some(pack.manifest.version.clone());
+    out.api = Some(pack.manifest.api.clone());
+    out.sha256 = if path.is_dir() {
+        pack.sha256().ok()
+    } else {
+        std::fs::read(path).ok().map(|b| sha256_hex(&b))
+    };
+    match check(&pack) {
+        Ok(report) => {
+            out.ok = true;
+            out.stages = report
+                .stages
+                .into_iter()
+                .map(|s| StageJson {
+                    stage: s.kind.name(),
+                    file: s.file,
+                    label: s.label,
+                    expressions: s.expressions,
+                    texture_reads: s.texture_reads,
+                })
+                .collect();
+        }
+        Err(problems) => {
+            out.problems = problems
+                .into_iter()
+                .map(
+                    |Problem {
+                         file,
+                         line,
+                         column,
+                         message,
+                     }| ProblemJson {
+                        file,
+                        line,
+                        column,
+                        message,
+                    },
+                )
+                .collect();
+        }
+    }
+    out
+}
+
+fn check_command(args: &[String]) -> Result<(), String> {
+    let paths = positional(args, &[]);
+    if paths.is_empty() {
+        return Err(USAGE.into());
+    }
+    let results: Vec<CheckJson> = paths.iter().map(|p| check_one(Path::new(p))).collect();
+    let failed = results.iter().filter(|r| !r.ok).count();
+    if args.iter().any(|a| a == "--json") {
+        let json = serde_json::to_string_pretty(&results).map_err(|e| e.to_string())?;
+        println!("{json}");
+    } else {
+        for r in &results {
+            print_result(r);
+        }
+    }
+    match failed {
+        0 => Ok(()),
+        n => Err(format!("{n} of {} packs failed the check", results.len())),
+    }
+}
+
+fn print_result(r: &CheckJson) {
+    let what = match (&r.id, &r.version, &r.api) {
+        (Some(id), Some(v), Some(api)) => format!("{id} {v} (shader API {api})"),
+        _ => r.path.clone(),
+    };
+    if !r.ok {
+        println!("{what}: FAILED");
+        for p in &r.problems {
+            if p.line == 0 {
+                println!("  {}: {}", p.file, p.message);
+            } else {
+                println!("  {}:{}:{}: {}", p.file, p.line, p.column, p.message);
+            }
+        }
+        return;
+    }
+    println!("{what}: ok");
+    for s in &r.stages {
+        println!(
+            "  {:<9} {:<28} {:>6} expressions, {} texture reads",
+            s.stage, s.label, s.expressions, s.texture_reads
+        );
+    }
+    if let Some(sha) = &r.sha256 {
+        println!("  sha256 {sha}");
+    }
+}
+
+fn pack(args: &[String]) -> Result<(), String> {
+    let [dir] = positional(args, &["--out"])
+        .try_into()
+        .map_err(|_| USAGE.to_string())?;
+    let dir = Path::new(&dir)
+        .canonicalize()
+        .map_err(|e| format!("{dir}: {e}"))?;
+    if !dir.is_dir() {
+        return Err(format!("{} is not a pack folder", dir.display()));
+    }
+    let dir = dir.as_path();
+    let pack = Pack::read(dir)?;
+    if let Err(problems) = check(&pack) {
+        for p in &problems {
+            eprintln!("{p}");
+        }
+        return Err(format!("{} failed the check", dir.display()));
+    }
+    let bytes = pack.package()?;
+    let out = flag(args, "--out").map_or_else(
+        || {
+            let m = &pack.manifest;
+            dir.with_file_name(format!("{}-{}.{EXTENSION}", m.id, m.version))
+        },
+        Into::into,
+    );
+    std::fs::write(&out, &bytes).map_err(|e| format!("{}: {e}", out.display()))?;
+    println!("Wrote {} (sha256 {})", out.display(), sha256_hex(&bytes));
+    Ok(())
+}
diff --git a/crates/horizon-shader-api/src/check.rs b/crates/horizon-shader-api/src/check.rs
index 935dccc13..6c43718f7 100644
--- a/crates/horizon-shader-api/src/check.rs
+++ b/crates/horizon-shader-api/src/check.rs
@@ -193,7 +193,7 @@ fn parse(composed: &Composed) -> Result<naga::Module, Vec<Problem>> {
     naga::front::wgsl::parse_str(&composed.text).map_err(|e| {
         let label = e.labels().next();
         let mut message = e.message().to_owned();
-        if let Some((_, text)) = label.filter(|(_, t)| !t.is_empty()) {
+        if let Some((_, text)) = label.filter(|(_, t)| !t.is_empty() && !message.contains(*t)) {
             message += &format!(" ({text})");
         }
         let at = label.and_then(|(span, _)| span.to_range()).map(|r| r.start);
diff --git a/crates/horizon-shader-api/templates/material/horizon-shaders.toml b/crates/horizon-shader-api/templates/material/horizon-shaders.toml
new file mode 100644
index 000000000..8cb7737e6
--- /dev/null
+++ b/crates/horizon-shader-api/templates/material/horizon-shaders.toml
@@ -0,0 +1,18 @@
+schema = 1
+id = "{{id}}"
+name = "{{name}}"
+version = "0.1.0"
+api = "0.1"
+description = "How block surfaces are lit."
+
+[material]
+file = "material.wgsl"
+
+[[options]]
+id = "contrast"
+name = "Light contrast"
+type = "float"
+default = 1.2
+min = 0.5
+max = 2.0
+step = 0.05
diff --git a/crates/horizon-shader-api/templates/material/material.wgsl b/crates/horizon-shader-api/templates/material/material.wgsl
new file mode 100644
index 000000000..ef9d89a2b
--- /dev/null
+++ b/crates/horizon-shader-api/templates/material/material.wgsl
@@ -0,0 +1,9 @@
+// The colour of each point of a block's surface, before the alpha test and
+// fog. Vanilla's own: albedo * tint * vec4(lightmap, 1.0).
+// Reference: docs/api/shaders-reference.md.
+override contrast: f32 = 1.2;
+
+fn material(input: MaterialInput) -> Surface {
+    let light = pow(input.lightmap, vec3<f32>(contrast));
+    return Surface(input.albedo * input.tint * vec4<f32>(light, 1.0));
+}
diff --git a/crates/horizon-shader-api/templates/post/horizon-shaders.toml b/crates/horizon-shader-api/templates/post/horizon-shaders.toml
new file mode 100644
index 000000000..e135ee838
--- /dev/null
+++ b/crates/horizon-shader-api/templates/post/horizon-shaders.toml
@@ -0,0 +1,22 @@
+schema = 1
+id = "{{id}}"
+name = "{{name}}"
+version = "0.1.0"
+api = "0.1"
+description = "A post-processing pass over the world."
+
+[[post]]
+file = "post.wgsl"
+name = "Colour"
+
+[[options]]
+id = "saturation"
+name = "Saturation"
+type = "float"
+default = 1.15
+min = 0.0
+max = 2.0
+step = 0.05
+
+[budget]
+gpu_ms = 0.5
diff --git a/crates/horizon-shader-api/templates/post/post.wgsl b/crates/horizon-shader-api/templates/post/post.wgsl
new file mode 100644
index 000000000..d4d179379
--- /dev/null
+++ b/crates/horizon-shader-api/templates/post/post.wgsl
@@ -0,0 +1,9 @@
+// Runs once per pixel of the world's picture, under the hand and the HUD.
+// Reference: docs/api/shaders-reference.md (the inputs, `frame` and the helpers).
+override saturation: f32 = 1.15;
+
+fn post(input: PostInput) -> vec4<f32> {
+    let grey = dot(input.color.rgb, vec3<f32>(0.2126, 0.7152, 0.0722));
+    let color = mix(vec3<f32>(grey), input.color.rgb, saturation);
+    return vec4<f32>(color, input.color.a);
+}
diff --git a/crates/horizon-shader-api/templates/sky/horizon-shaders.toml b/crates/horizon-shader-api/templates/sky/horizon-shaders.toml
new file mode 100644
index 000000000..5939f25fd
--- /dev/null
+++ b/crates/horizon-shader-api/templates/sky/horizon-shaders.toml
@@ -0,0 +1,18 @@
+schema = 1
+id = "{{id}}"
+name = "{{name}}"
+version = "0.1.0"
+api = "0.1"
+description = "A sky of its own."
+
+[sky]
+file = "sky.wgsl"
+
+[[options]]
+id = "glow"
+name = "Sun glow"
+type = "float"
+default = 0.5
+min = 0.0
+max = 1.0
+step = 0.05
diff --git a/crates/horizon-shader-api/templates/sky/sky.wgsl b/crates/horizon-shader-api/templates/sky/sky.wgsl
new file mode 100644
index 000000000..b5aaaa7ad
--- /dev/null
+++ b/crates/horizon-shader-api/templates/sky/sky.wgsl
@@ -0,0 +1,9 @@
+// The sky's colour along each view ray; the sun, moon, stars and clouds are
+// drawn over it. Reference: docs/api/shaders-reference.md.
+override glow: f32 = 0.5;
+
+fn sky(input: SkyInput) -> vec4<f32> {
+    let toward_sun = max(dot(input.direction, frame.sun_direction), 0.0);
+    let warm = vec3<f32>(1.0, 0.6, 0.3) * pow(toward_sun, 8.0) * glow;
+    return vec4<f32>(input.color.rgb + warm, input.color.a);
+}
diff --git a/crates/horizon-shader-api/tests/sdk.rs b/crates/horizon-shader-api/tests/sdk.rs
new file mode 100644
index 000000000..ef69a88a0
--- /dev/null
+++ b/crates/horizon-shader-api/tests/sdk.rs
@@ -0,0 +1,92 @@
+//! The SDK: every template and the example pack pass the check, and the
+//! `horizon-shader` tool makes, checks and packages a pack.
+use horizon_shader_api::{Pack, check};
+use std::{path::Path, process::Command};
+
+const TOOL: &str = env!("CARGO_BIN_EXE_horizon-shader");
+
+fn scratch(name: &str) -> std::path::PathBuf {
+    let dir = std::env::temp_dir().join(format!("horizon-shader-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    dir
+}
+
+fn run(args: &[&str]) -> (bool, String) {
+    let out = Command::new(TOOL).args(args).output().unwrap();
+    let text =
+        String::from_utf8_lossy(&out.stdout).into_owned() + &String::from_utf8_lossy(&out.stderr);
+    (out.status.success(), text)
+}
+
+#[test]
+fn the_example_pack_passes() {
+    let dir = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/packs/golden_hour"));
+    let report = check(&Pack::read(dir).unwrap()).unwrap();
+    let labels: Vec<_> = report.stages.iter().map(|s| s.label.as_str()).collect();
+    assert_eq!(labels, ["Warm horizon", "Glow", "Colour grade"]);
+}
+
+#[test]
+fn every_template_makes_a_pack_that_passes() {
+    let root = scratch("templates");
+    for template in ["post", "sky", "material"] {
+        let dir = root.join(format!("My-{template}"));
+        let dir_s = dir.to_str().unwrap();
+        let (ok, text) = run(&["new", dir_s, "--template", template]);
+        assert!(ok, "{text}");
+        let pack = Pack::read(&dir).unwrap();
+        assert_eq!(pack.manifest.id, format!("my_{template}"));
+        assert_eq!(pack.manifest.name, format!("My {template}"));
+        let (ok, text) = run(&["check", dir_s]);
+        assert!(ok && text.contains(": ok"), "{text}");
+    }
+    let (ok, text) = run(&[
+        "new",
+        root.join("x").to_str().unwrap(),
+        "--template",
+        "water",
+    ]);
+    assert!(!ok && text.contains("no template \"water\""), "{text}");
+    std::fs::remove_dir_all(root).unwrap();
+}
+
+#[test]
+fn packs_and_checks_the_package() {
+    let root = scratch("pack");
+    let dir = root.join("glow");
+    let dir_s = dir.to_str().unwrap();
+    assert!(run(&["new", dir_s, "--name", "Glow"]).0);
+    let out = root.join("glow.hshader");
+    let (ok, text) = run(&["pack", dir_s, "--out", out.to_str().unwrap()]);
+    assert!(ok, "{text}");
+    let sha = text
+        .split("sha256 ")
+        .nth(1)
+        .unwrap()
+        .trim_end_matches([')', '\n'])
+        .to_owned();
+    let (ok, json) = run(&["check", out.to_str().unwrap(), "--json"]);
+    assert!(ok, "{json}");
+    let report: serde_json::Value = serde_json::from_str(&json).unwrap();
+    assert_eq!(report[0]["ok"], true);
+    assert_eq!(report[0]["id"], "glow");
+    assert_eq!(report[0]["sha256"], sha.as_str());
+    assert_eq!(report[0]["stages"][0]["stage"], "post");
+
+    std::fs::write(
+        dir.join("post.wgsl"),
+        "fn post(input: PostInput) -> vec4<f32> { return input.color }\n",
+    )
+    .unwrap();
+    let (ok, json) = run(&["check", dir_s, "--json"]);
+    assert!(!ok);
+    let report: serde_json::Value =
+        serde_json::from_str(json.split("\nerror:").next().unwrap()).unwrap();
+    assert_eq!(report[0]["ok"], false);
+    assert_eq!(report[0]["problems"][0]["file"], "post.wgsl");
+    assert_eq!(report[0]["problems"][0]["line"], 1);
+    let (ok, text) = run(&["pack", dir_s]);
+    assert!(!ok && text.contains("failed the check"), "{text}");
+    std::fs::remove_dir_all(root).unwrap();
+}
diff --git a/docs/README.md b/docs/README.md
index 1450ba388..609580d91 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,6 +13,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
 - [Graphics](graphics.md): the Simple and Advanced graphics settings, the graphics benchmark and what it measured.
 - [Benchmark](benchmark.md): Horizon against vanilla 26.3 and vanilla with performance mods, on the same machine, world, path and settings: what is measured, how it is kept fair, how to reproduce it.
 - [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default.
+- [Shader packs](shaders.md): Horizon's own WGSL shader packs, how to make and check one (`horizon-shader`).
 - [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods.
 - [Modpacks](modpacks.md): porting whole packs (ATM10 and smaller): import, inventory, carry-over, an agent per mod with a harness against the Java original, coverage, and how "10x" is measured.
 - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it.
diff --git a/docs/api/shaders.md b/docs/api/shaders.md
index a5ba0986d..8e9e6919c 100644
--- a/docs/api/shaders.md
+++ b/docs/api/shaders.md
@@ -81,7 +81,8 @@ the same way every time (files in path order, fixed dates), so a pack's SHA-256
 
 - [shaders-reference.md](shaders-reference.md): every stage's signature, input and output structs, resources and
   helpers, the frame's fields with their units, option types and limits, generated from `crates/horizon-shader-api`.
-- The guide and an example pack come with `horizon-shader check`.
+- [The guide](../shaders.md): making a pack with `horizon-shader new`, `check` and `pack`; the templates and the
+  example pack (`crates/horizon-shader-api/packs/golden_hour`).
 
 ## Stability
 
@@ -95,6 +96,8 @@ stages with options and hot reload, then the overlay, lighting, sky and shadow s
 
 ## Changelog
 
+- 2026-10-25: `horizon-shader` (`new`, `check`, `pack`), three templates, the example pack and the guide.
+- 2026-10-25: the check (naga validation, signatures, options, budgets, SPIR-V/Metal/HLSL translation).
 - 2026-10-25: the stages of API 0.1 (sky, material, post), their inputs and the generated reference.
 - 2026-10-25: the pack format, schema 1: `horizon-shaders.toml` and the `.hshader` package.
 - 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.
diff --git a/docs/shaders.md b/docs/shaders.md
new file mode 100644
index 000000000..99a08fa9a
--- /dev/null
+++ b/docs/shaders.md
@@ -0,0 +1,127 @@
+# Horizon shader packs
+
+Horizon has its own shader packs: WGSL written against stages of Horizon's renderer, checked before they run. This page
+is the guide for pack authors. The design and the pack format are in [api/shaders.md](api/shaders.md); every stage's
+signature, input, resource and limit is in the generated [api/shaders-reference.md](api/shaders-reference.md).
+
+Shader packs in the Iris/OptiFine format are a separate feature with its own loader; this page is only about
+Horizon's own format.
+
+| Part | Where | State |
+|---|---|---|
+| Format, stages, check | `crates/horizon-shader-api` | API 0.1, experimental |
+| Authoring tool | `horizon-shader` (same crate) | `new`, `check`, `pack` |
+| Templates | `crates/horizon-shader-api/templates/` | post, sky, material |
+| Example pack | `crates/horizon-shader-api/packs/golden_hour` | a warm sky and two post passes |
+| In the game, the launcher, the registry | | not yet: the renderer hooks come next |
+
+## Quick start
+
+```sh
+cargo install --path crates/horizon-shader-api      # or: cargo run -p horizon-shader-api --bin horizon-shader -- <command>
+horizon-shader new my_pack --template post          # also: --template sky, --template material; --name "My Pack"
+horizon-shader check my_pack                        # what the game, the launcher and the registry will check
+horizon-shader pack my_pack                         # check, then write my_pack-0.1.0.hshader beside the folder
+```
+
+`check` prints each stage with its cost, and the pack's SHA-256:
+
+```
+golden_hour 1.0.0 (shader API 0.1): ok
+  sky       Warm horizon                     99 expressions, 0 texture reads
+  post      Glow                            185 expressions, 3 texture reads
+  post      Colour grade                    201 expressions, 2 texture reads
+  sha256 fd92a294...
+```
+
+or every problem, at its file, line and column:
+
+```
+my_pack 0.1.0 (shader API 0.1): FAILED
+  post.wgsl:9:1: expected `;`, found "}"
+```
+
+`--json` prints the same for tools (`ok`, `id`, `version`, `api`, `sha256`, `stages`, `problems`).
+
+## A pack
+
+A folder (or the same files zipped as a `.hshader`) with `horizon-shaders.toml` and WGSL files:
+
+```toml
+schema = 1
+id = "my_pack"
+name = "My Pack"
+version = "0.1.0"
+api = "0.1"
+
+[[post]]
+file = "post.wgsl"
+
+[[options]]
+id = "saturation"
+name = "Saturation"
+type = "float"
+default = 1.15
+min = 0.0
+max = 2.0
+```
+
+Every key is in [api/shaders.md](api/shaders.md#the-pack-format-schema-1).
+
+## Stages
+
+A stage is one function your file defines. Horizon puts its prelude (the structs, `frame`, the stage's resources and
+helpers) before your file and calls the function from its own pass, so the world is still culled, batched and meshed
+by Horizon: a pack changes how things look, not how they are drawn.
+
+| Stage | Your function | What it does |
+| --- | --- | --- |
+| `[sky]` | `fn sky(input: SkyInput) -> vec4<f32>` | the sky's colour along each view ray; the sun, moon, stars and clouds are drawn over it |
+| `[material]` | `fn material(input: MaterialInput) -> Surface` | the lit colour of each point of a block's surface, before the alpha test and fog |
+| `[[post]]` | `fn post(input: PostInput) -> vec4<f32>` | a full-screen pass over the world's picture (up to 8, in order), under the hand and HUD |
+
+A pack has at least one stage; a stage it leaves out keeps vanilla's look. Each input says what vanilla would draw
+(`input.color` in the sky and post stages; `albedo * tint * vec4(lightmap, 1.0)` for a material), so a pack can start
+from vanilla and change only what it means to.
+
+Every stage can read `frame`: the camera's matrices and position, the sun and moon directions, the time of day,
+vanilla's sky and fog colours, rain and thunder, fog distances, the light at the camera, effects and the dimension.
+Post passes also read `scene_color`, `scene_depth`, `previous` (the last pass's output), two samplers and the helpers
+`depth_at(uv)` and `view_position(uv, depth)`.
+
+Rules the check enforces: your files declare no bindings (`@group`/`@binding`), no entry points and no names starting
+with `horizon_`. Code shared by several stages goes in files listed in `shared`, put before every stage.
+
+## Options
+
+Each `[[options]]` entry is a WGSL `override` of the same name, set when the game builds the pipeline: no text
+substitution, no recompiling a different program per value.
+
+```wgsl
+override saturation: f32 = 1.15;   // type = "float"; bool → bool, int → i32, choice → u32 (the value's index)
+```
+
+The game shows the options on the pack's settings screen. Branches on an option are on a constant, so the GPU
+skips the side that isn't taken.
+
+## What the check does
+
+The game runs the same check when it loads a pack (a pack that fails is refused with the message, and the last good
+one keeps drawing), the launcher before it installs one, and the registry's CI before a pack is listed:
+
+1. The manifest and the package: known keys, valid ids, every file used, sizes.
+2. Each stage built as the renderer builds it and validated by naga.
+3. The stage function's signature, and the rules above.
+4. Each `override` matches its option's type (or has a default); each option is used.
+5. Budgets: 20 000 expressions and 64 texture reads per stage.
+6. Every entry point translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL), with the options at their
+   defaults, minimums and maximums.
+
+`[budget] gpu_ms` is the GPU time your pack aims to add to a frame; the game's overlay will show each pass's time
+against it.
+
+## Next
+
+The renderer hooks (shared with the Iris/OptiFine loader), then the post stage in the game with hot reload and the
+GPU time per pass, Options > Shader packs listing these packs, then the material and sky stages, and the registry's
+`shader` kind with installs from the launcher.

From ed7d88b2135e81b19238c3ffb39ede17b838aee6 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:13:12 +0100
Subject: [PATCH 093/270] Close container menus when the player moves out of
 reach

Container.stillValidBlockEntity also checks the player's block interaction
range plus a 4-block buffer. Guest menus now close in the tick once out of
reach and ignore clicks while invalid, and the in-frame single player menu
closes the same way.
---
 .../src/game/block_entity_ticks.rs            |  1 +
 crates/horizon-client/src/game/lan_actions.rs | 26 ++++++++++++++
 .../horizon-client/src/game/lan_stations.rs   | 10 +-----
 crates/horizon-client/src/game/storage.rs     | 36 +++++++++++++++++++
 crates/horizon-client/src/lan/containers.rs   |  6 ++++
 crates/horizon-client/src/lan/guest.rs        | 17 +++++++++
 crates/horizon-client/src/lan/menu.rs         | 13 +++++++
 7 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/crates/horizon-client/src/game/block_entity_ticks.rs b/crates/horizon-client/src/game/block_entity_ticks.rs
index 094aed6ef..389807d9b 100644
--- a/crates/horizon-client/src/game/block_entity_ticks.rs
+++ b/crates/horizon-client/src/game/block_entity_ticks.rs
@@ -15,6 +15,7 @@ use horizon_world::registry::BlockStateId;
 impl Game<'_> {
     pub(super) fn tick_block_entities(&mut self) -> Result<()> {
         self.tick_mount_menu();
+        self.tick_container_reach();
         self.load_entity_types();
         if !self.world.block_entities.has_states() {
             let states = self.ticking_states();
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..c6d1b5302 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -812,6 +812,31 @@ impl Game<'_> {
         }
     }
 
+    /// `ServerPlayer.tick`'s `stillValid`: a guest's block container closes
+    /// once the guest is out of reach of its block (a removed block closes it
+    /// in the hub's `sync_containers`).
+    fn lan_containers_tick(&mut self, host: &mut LanHost) {
+        let far: Vec<u32> = host
+            .hub
+            .guests
+            .iter()
+            .filter(|g| host.hub.here(g))
+            .filter(|g| {
+                g.menu.as_ref().is_some_and(|m| {
+                    m.slots.valid(&self.world) && !m.slots.still_valid(&self.world, g, m.pos)
+                })
+            })
+            .map(|g| g.conn)
+            .collect();
+        for conn in far {
+            self.guest_container_closed(host, conn);
+            host.hub.close_container(conn);
+            if let Some(gi) = host.hub.guests.iter().position(|g| g.conn == conn) {
+                self.guest_carried_back(host, gi);
+            }
+        }
+    }
+
     /// A packet from a guest that the hub does not handle itself.
     pub(super) fn lan_guest_packet(&mut self, host: &mut LanHost, conn: u32, packet: S) {
         let Some(gi) = host.hub.guests.iter().position(|g| g.conn == conn) else {
@@ -1680,6 +1705,7 @@ impl Game<'_> {
     pub(super) fn tick_guests(&mut self, host: &mut LanHost) {
         self.lan_merchant_tick(host);
         self.lan_stations_tick(host);
+        self.lan_containers_tick(host);
         self.tick_lan_mount_menus(host);
         self.announce_guest_advancements(host);
         let conns: Vec<u32> = host
diff --git a/crates/horizon-client/src/game/lan_stations.rs b/crates/horizon-client/src/game/lan_stations.rs
index 2efcfc705..49a90b7b9 100644
--- a/crates/horizon-client/src/game/lan_stations.rs
+++ b/crates/horizon-client/src/game/lan_stations.rs
@@ -665,13 +665,5 @@ pub(super) fn station_inputs(gs: &GuestStation) -> Vec<ItemStack> {
 /// its block interaction range (4.5, creative 5) and a 4-block buffer of the
 /// block's box.
 pub(super) fn within_reach(g: &horizon_client::lan::guest::Guest, pos: [i32; 3]) -> bool {
-    let eye = [g.position[0], g.position[1] + g.eye_height(), g.position[2]];
-    let reach = if g.creative() { 5.0 } else { 4.5 } + 4.0;
-    (0..3)
-        .map(|k| {
-            let lo = f64::from(pos[k]);
-            (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
-        })
-        .sum::<f64>()
-        < reach * reach
+    g.within_block_range(pos, 4.0)
 }
diff --git a/crates/horizon-client/src/game/storage.rs b/crates/horizon-client/src/game/storage.rs
index 9b28ce26b..9132c02a8 100644
--- a/crates/horizon-client/src/game/storage.rs
+++ b/crates/horizon-client/src/game/storage.rs
@@ -127,6 +127,42 @@ impl Game<'_> {
             None => vec![own],
         }
     }
+    /// `Container.stillValidBlockEntity`: the open block container closes once
+    /// the player's eyes are out of reach of any of its blocks (a 4-block buffer).
+    pub(super) fn tick_container_reach(&mut self) {
+        // A server's menu ends when the server closes it.
+        if self.remote.is_some() {
+            return;
+        }
+        let Some(eye) = self.eye_position() else {
+            return;
+        };
+        if self
+            .container
+            .is_none_or(|k| k.1 == super::minecarts::CART_KEY_Y)
+        {
+            return;
+        }
+        let range = self.reach() + 4.0;
+        let near = self.container_parts().iter().all(|((x, y, z), _)| {
+            let d = [*x, *y, *z]
+                .iter()
+                .zip(eye)
+                .map(|(&lo, e)| {
+                    (f64::from(lo) - e)
+                        .max(e - f64::from(lo) - 1.0)
+                        .max(0.0)
+                        .powi(2)
+                })
+                .sum::<f64>();
+            d < range * range
+        });
+        if !near {
+            self.close_container();
+            self.screen = super::Screen::Playing;
+            self.capture(true);
+        }
+    }
     /// The number of slots of the open container.
     pub(super) fn container_size(&self) -> usize {
         self.container_parts().iter().map(|p| p.1).sum()
diff --git a/crates/horizon-client/src/lan/containers.rs b/crates/horizon-client/src/lan/containers.rs
index d43cb5c27..d30d3a494 100644
--- a/crates/horizon-client/src/lan/containers.rs
+++ b/crates/horizon-client/src/lan/containers.rs
@@ -343,6 +343,12 @@ impl Hub {
         if !window_ok || self.guests[i].spectator() {
             return Vec::new();
         }
+        // A menu that is no longer valid takes no clicks.
+        if let Some(m) = self.guests[i].menu.as_ref().filter(|_| in_menu)
+            && !m.slots.still_valid(world, &self.guests[i], m.pos)
+        {
+            return Vec::new();
+        }
         let source = self.guests[i].menu.as_ref().map(|m| m.slots);
         let mut drag = if in_menu {
             self.guests[i].menu.as_mut().and_then(|m| m.drag.take())
diff --git a/crates/horizon-client/src/lan/guest.rs b/crates/horizon-client/src/lan/guest.rs
index 440b58284..dc10096e3 100644
--- a/crates/horizon-client/src/lan/guest.rs
+++ b/crates/horizon-client/src/lan/guest.rs
@@ -404,6 +404,23 @@ impl Guest {
     pub fn eye_height(&self) -> f64 {
         if self.sneaking { 1.27 } else { 1.62 }
     }
+    /// `Player.isWithinBlockInteractionRange(pos, buffer)`: the eyes within the
+    /// block interaction range (4.5, creative 5) plus `buffer` of the block's box.
+    pub fn within_block_range(&self, pos: [i32; 3], buffer: f64) -> bool {
+        let eye = [
+            self.position[0],
+            self.position[1] + self.eye_height(),
+            self.position[2],
+        ];
+        let reach = if self.creative() { 5.0 } else { 4.5 } + buffer;
+        (0..3)
+            .map(|k| {
+                let lo = f64::from(pos[k]);
+                (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
+            })
+            .sum::<f64>()
+            < reach * reach
+    }
     /// The inventory menu's 46 slots (ServerPlayer.inventoryMenu): 0 crafting
     /// result, 1..=4 crafting grid, 5..=8 armor, 9..=35 main, 36..=44 hotbar,
     /// 45 off hand.
diff --git a/crates/horizon-client/src/lan/menu.rs b/crates/horizon-client/src/lan/menu.rs
index de9fb9608..b3f72da7e 100644
--- a/crates/horizon-client/src/lan/menu.rs
+++ b/crates/horizon-client/src/lan/menu.rs
@@ -64,6 +64,19 @@ impl Slots {
             .iter()
             .all(|k| world.block_entities.contains_key(k))
     }
+    /// `Container.stillValid` for the guest: the block entities are there
+    /// and the guest is within reach of each (`stillValidBlockEntity`). The
+    /// ender chest's block is `at` (`PlayerEnderChestContainer.activeChest`).
+    pub fn still_valid(self, world: &World, guest: &Guest, at: Option<(i32, i32, i32)>) -> bool {
+        let blocks = match self {
+            Slots::Ender => at.into_iter().collect(),
+            _ => self.halves(),
+        };
+        self.valid(world)
+            && blocks
+                .iter()
+                .all(|k| guest.within_block_range([k.0, k.1, k.2], 4.0))
+    }
     /// Container slot `n`.
     pub fn get(self, world: &World, guest: &Guest, mut n: usize) -> Option<ItemStack> {
         if self == Slots::Ender {

From 18ec4145c46400864f921987ed4d601fd1979f04 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:19:31 +0100
Subject: [PATCH 094/270] Close crafting tables that are removed or out of
 reach

CraftingMenu.stillValid needs the block to still be a crafting table and the
player within reach of it. The table's position is now kept with the open
grid, so the menu closes in the tick (giving its grid back) and a stale
click no longer crafts, in single player and for LAN guests.
---
 crates/horizon-client/src/game.rs             | 34 +++++++++
 .../src/game/block_entity_ticks.rs            |  1 +
 crates/horizon-client/src/game/lan_actions.rs | 16 +++--
 .../horizon-client/src/game/lan_crafting.rs   | 69 +++++++++++++++----
 4 files changed, 102 insertions(+), 18 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..7a208ecfe 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1168,6 +1168,8 @@ struct Game<'a> {
     carried: Option<ItemStack>,
     craft_grid: Vec<Option<ItemStack>>,
     craft_size: usize,
+    /// The crafting table the 3x3 grid belongs to (`CraftingMenu.access`).
+    craft_table: Option<[i32; 3]>,
     /// A quick craft drag over inventory slots: (button, game slots so far).
     inv_drag: Option<(i32, Vec<usize>)>,
     /// `AbstractContainerScreen`'s quick craft and skip-release state.
@@ -2897,6 +2899,35 @@ impl Game<'_> {
         }
         Ok(())
     }
+    /// `CraftingMenu.stillValid`: the open crafting table closes once its
+    /// block is gone or the player's eyes are out of reach (a 4-block buffer).
+    pub(super) fn tick_craft_table(&mut self) {
+        // A server's menu ends when the server closes it.
+        if self.remote.is_some() || self.craft_size != 3 {
+            return;
+        }
+        let (Some(pos), Some(eye)) = (self.craft_table, self.eye_position()) else {
+            return;
+        };
+        let table = &*self
+            .res
+            .facts()
+            .get(self.world.block(pos[0], pos[1], pos[2]))
+            .name
+            == "minecraft:crafting_table";
+        let range = self.reach() + 4.0;
+        let d = (0..3)
+            .map(|k| {
+                let lo = f64::from(pos[k]);
+                (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
+            })
+            .sum::<f64>();
+        if !table || d >= range * range {
+            self.close_container();
+            self.screen = Screen::Playing;
+            self.capture(true);
+        }
+    }
     /// Menus opened by PlayerEffect::OpenMenu.
     fn open_menu(&mut self, pos: [i32; 3]) {
         let name = self
@@ -2916,6 +2947,7 @@ impl Game<'_> {
         }
         if &*name == "minecraft:crafting_table" {
             self.craft_size = 3;
+            self.craft_table = Some(pos);
         } else if &*name == "minecraft:ender_chest" {
             self.open_ender_chest(key);
             self.container_opener_event(key, true);
@@ -5425,6 +5457,7 @@ impl Game<'_> {
             }
         }
         self.craft_size = 2;
+        self.craft_table = None;
         if let Some(key) = self.container.take() {
             self.container_opener_event(key, false);
             self.post_block_game_event(
@@ -11746,6 +11779,7 @@ impl<'a> Game<'a> {
             carried: None,
             craft_grid: vec![None; 9],
             craft_size: 2,
+            craft_table: None,
             inv_drag: None,
             tweaks: Default::default(),
             inv_clicks: Default::default(),
diff --git a/crates/horizon-client/src/game/block_entity_ticks.rs b/crates/horizon-client/src/game/block_entity_ticks.rs
index 094aed6ef..dd3a95250 100644
--- a/crates/horizon-client/src/game/block_entity_ticks.rs
+++ b/crates/horizon-client/src/game/block_entity_ticks.rs
@@ -15,6 +15,7 @@ use horizon_world::registry::BlockStateId;
 impl Game<'_> {
     pub(super) fn tick_block_entities(&mut self) -> Result<()> {
         self.tick_mount_menu();
+        self.tick_craft_table();
         self.load_entity_types();
         if !self.world.block_entities.has_states() {
             let states = self.ticking_states();
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..d0d7bd7df 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -117,6 +117,7 @@ pub(super) struct GuestSwap {
     host_command_block: Option<super::command_blocks::CommandBlockScreen>,
     host_mount_menu: super::mount_menu::MountMenu,
     craft_size: usize,
+    craft_table: Option<[i32; 3]>,
     craft_grid: Vec<Option<ItemStack>>,
     container: Option<(i32, i32, i32)>,
     mining: Option<Mining>,
@@ -307,6 +308,7 @@ impl Game<'_> {
         // The host's crafting grid stays theirs; a crafting table the guest
         // opens shows as the 3x3 size.
         let craft_size = std::mem::replace(&mut self.craft_size, 2);
+        let craft_table = self.craft_table.take();
         let craft_grid = std::mem::replace(&mut self.craft_grid, vec![None; 9]);
         let container = self.container.take();
         let mining = std::mem::replace(&mut self.mining, play.mining.take());
@@ -390,6 +392,7 @@ impl Game<'_> {
             host_command_block,
             host_mount_menu,
             craft_size,
+            craft_table,
             craft_grid,
             container,
             mining,
@@ -445,6 +448,7 @@ impl Game<'_> {
             host_command_block,
             host_mount_menu,
             craft_size,
+            craft_table,
             craft_grid,
             container,
             mining,
@@ -495,7 +499,10 @@ impl Game<'_> {
 
         // What the action opened: handed to the guest instead of the host.
         let opened = self.container.take();
-        let opened_table = std::mem::replace(&mut self.craft_size, craft_size) == 3;
+        let guest_table = std::mem::replace(&mut self.craft_table, craft_table);
+        let opened_table = (std::mem::replace(&mut self.craft_size, craft_size) == 3)
+            .then_some(guest_table)
+            .flatten();
         self.craft_grid = craft_grid;
         let opened_station = std::mem::replace(&mut self.station, host_station);
         let bed = std::mem::replace(&mut self.sleeping, sleeping);
@@ -671,8 +678,8 @@ impl Game<'_> {
         if let Some(key) = guest_lectern {
             self.lan_open_lectern(host, conn, key);
         }
-        if opened_table {
-            self.lan_open_crafting(host, conn);
+        if let Some(pos) = opened_table {
+            self.lan_open_crafting(host, conn, pos);
         }
         if let Some(mob) = guest_mount {
             self.lan_open_mount(host, conn, mob);
@@ -1238,7 +1245,7 @@ impl Game<'_> {
     /// cursor goes back into their inventory (`placeItemBackInInventory`,
     /// dropped only if it doesn't fit), and their client's cursor empties
     /// with the inventory it is sent.
-    fn guest_carried_back(&mut self, host: &mut LanHost, gi: usize) {
+    pub(super) fn guest_carried_back(&mut self, host: &mut LanHost, gi: usize) {
         if let Some(c) = host.hub.guests[gi].carried.take() {
             self.lan_place_back(host, gi, vec![c]);
             host.hub.send_inventory(gi);
@@ -1680,6 +1687,7 @@ impl Game<'_> {
     pub(super) fn tick_guests(&mut self, host: &mut LanHost) {
         self.lan_merchant_tick(host);
         self.lan_stations_tick(host);
+        self.lan_tables_tick(host);
         self.tick_lan_mount_menus(host);
         self.announce_guest_advancements(host);
         let conns: Vec<u32> = host
diff --git a/crates/horizon-client/src/game/lan_crafting.rs b/crates/horizon-client/src/game/lan_crafting.rs
index cb3b0a2c9..dd51b2843 100644
--- a/crates/horizon-client/src/game/lan_crafting.rs
+++ b/crates/horizon-client/src/game/lan_crafting.rs
@@ -19,8 +19,8 @@ use horizon_protocol::packets::play::{self, Clientbound as C};
 pub(super) struct GuestCrafting {
     /// The inventory menu; its grid lives in the hub's guest.
     inventory: Option<Box<Menu>>,
-    /// The open crafting table: its window, state id and menu.
-    table: Option<(i32, i32, Box<Menu>)>,
+    /// The open crafting table: its window, state id, menu and block.
+    table: Option<(i32, i32, Box<Menu>, [i32; 3])>,
     /// The open furnace's or brewing stand's window and menu (`AbstractFurnaceMenu`,
     /// `BrewingStandMenu`); its slots live in the block entity and the hub's
     /// container menu keeps the client in sync.
@@ -383,17 +383,17 @@ impl Game<'_> {
             host.hub.send_inventory(gi);
             placed
         } else {
-            let Some((window, state, mut menu)) = host
+            let Some((window, state, mut menu, pos)) = host
                 .play
                 .get_mut(&conn)
-                .and_then(|play| play.crafting.table.take_if(|(w, _, _)| *w == p.container))
+                .and_then(|play| play.crafting.table.take_if(|(w, ..)| *w == p.container))
             else {
                 return;
             };
             let placed = self.guest_menu_op(host, gi, &mut menu, |menu, env| {
                 menu.place_recipe(env, &id, p.use_max, creative, None)
             });
-            host.play.entry(conn).or_default().crafting.table = Some((window, state, menu));
+            host.play.entry(conn).or_default().crafting.table = Some((window, state, menu, pos));
             self.lan_send_table_content(host, conn);
             placed
         };
@@ -403,7 +403,7 @@ impl Game<'_> {
     }
 
     /// The guest opened a crafting table (`CraftingTableBlock.getMenuProvider`).
-    pub(super) fn lan_open_crafting(&mut self, host: &mut LanHost, conn: u32) {
+    pub(super) fn lan_open_crafting(&mut self, host: &mut LanHost, conn: u32, pos: [i32; 3]) {
         self.lan_crafting_closed(host, conn, None);
         self.lan_station_closed(host, conn, None);
         // The container it replaces loses its opener.
@@ -413,7 +413,7 @@ impl Game<'_> {
             return;
         };
         let menu = Box::new(Menu::new(Kind::Crafting));
-        host.play.entry(conn).or_default().crafting.table = Some((window, 0, menu));
+        host.play.entry(conn).or_default().crafting.table = Some((window, 0, menu, pos));
         self.lan_send_table_content(host, conn);
     }
 
@@ -427,31 +427,72 @@ impl Game<'_> {
         let Some(play) = host.play.get_mut(&conn) else {
             return false;
         };
-        let Some((window, state, mut menu)) = play
+        let Some((window, state, mut menu, pos)) = play
             .crafting
             .table
-            .take_if(|(window, _, _)| *window == p.container)
+            .take_if(|(window, ..)| *window == p.container)
         else {
             return false;
         };
+        // A table that is no longer valid takes no clicks (handleContainerClick).
         if let Some(gi) = host.hub.guests.iter().position(|g| g.conn == conn)
             && !host.hub.guests[gi].spectator()
+            && self.lan_table_valid(&host.hub.guests[gi], pos)
         {
             self.guest_menu_op(host, gi, &mut menu, |menu, env| {
                 let _ = menu.click(env, i32::from(p.slot), i32::from(p.button), input(p.input));
             });
         }
-        host.play.entry(conn).or_default().crafting.table = Some((window, state, menu));
+        host.play.entry(conn).or_default().crafting.table = Some((window, state, menu, pos));
         self.lan_send_table_content(host, conn);
         true
     }
 
+    /// `CraftingMenu.stillValid`: the block is still a crafting table and the
+    /// guest is within reach of it.
+    fn lan_table_valid(&self, g: &Guest, pos: [i32; 3]) -> bool {
+        let name = &self
+            .res
+            .facts()
+            .get(self.world.block(pos[0], pos[1], pos[2]))
+            .name;
+        &**name == "minecraft:crafting_table" && super::lan_stations::within_reach(g, pos)
+    }
+
+    /// `ServerPlayer.tick`'s `stillValid`: a guest's crafting table closes
+    /// once it is gone or out of reach, giving its grid back.
+    pub(super) fn lan_tables_tick(&mut self, host: &mut LanHost) {
+        let invalid: Vec<(u32, i32)> = host
+            .play
+            .iter()
+            .filter_map(|(c, p)| p.crafting.table.as_ref().map(|t| (*c, t.0, t.3)))
+            .filter(|&(c, _, pos)| {
+                host.hub
+                    .guests
+                    .iter()
+                    .find(|g| g.conn == c)
+                    .is_some_and(|g| host.hub.here(g) && !self.lan_table_valid(g, pos))
+            })
+            .map(|(c, window, _)| (c, window))
+            .collect();
+        for (conn, window) in invalid {
+            self.lan_crafting_closed(host, conn, Some(window));
+            host.hub.send_to(
+                conn,
+                &C::ContainerClose(play::ContainerClose { container: window }),
+            );
+            if let Some(gi) = host.hub.guests.iter().position(|g| g.conn == conn) {
+                self.guest_carried_back(host, gi);
+            }
+        }
+    }
+
     /// The whole crafting table menu for the client (`sendAllDataToRemote`).
     fn lan_send_table_content(&mut self, host: &mut LanHost, conn: u32) {
         let Some(gi) = host.hub.guests.iter().position(|g| g.conn == conn) else {
             return;
         };
-        let Some((window, state, menu)) = host
+        let Some((window, state, menu, _)) = host
             .play
             .get_mut(&conn)
             .and_then(|p| p.crafting.table.as_mut())
@@ -499,9 +540,9 @@ impl Game<'_> {
         } else {
             match crafting
                 .table
-                .take_if(|(w, _, _)| window.is_none_or(|window| *w == window))
+                .take_if(|(w, ..)| window.is_none_or(|window| *w == window))
             {
-                Some((_, _, menu)) => (1..10).filter_map(|s| menu.slot(s).cloned()).collect(),
+                Some((_, _, menu, _)) => (1..10).filter_map(|s| menu.slot(s).cloned()).collect(),
                 None => return false,
             }
         };
@@ -527,7 +568,7 @@ impl Game<'_> {
         let mut grid: Vec<ItemStack> = g.craft_grid.iter_mut().filter_map(Option::take).collect();
         g.craft_result = None;
         if let Some(play) = play {
-            if let Some((_, _, menu)) = play.crafting.table {
+            if let Some((_, _, menu, _)) = play.crafting.table {
                 grid.extend((1..10).filter_map(|s| menu.slot(s).cloned()));
             }
             // A workstation's inputs too.

From 4bfa496173109366e9e37bf1d4194f7844fb389c Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 11:47:21 -0300
Subject: [PATCH 095/270] Lava cauldrons burn the player inside them

The player's inside-block sweep skipped lava cauldrons, so standing in
one did nothing. It now tests the player against LavaCauldronBlock's
entity-inside shape (the cauldron's shape or its lava, Block.column(12,
4, 15)) the way Entity.checkInsideBlocks does, and applies
LavaCauldronBlock.entityInside: CLEAR_FREEZE, LAVA_IGNITE (15 seconds)
and Entity.lavaHurt (lava, 4), for the game's own player and a server's.

Fixes #1320.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/motion.rs | 94 ++++++++++++++++++++++++-----
 1 file changed, 80 insertions(+), 14 deletions(-)

diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs
index 560cadc80..8637ead1f 100644
--- a/crates/horizon-client/src/motion.rs
+++ b/crates/horizon-client/src/motion.rs
@@ -1259,21 +1259,22 @@ impl MotionWorld<'_, '_, '_> {
                 continue;
             }
             let powder_snow = name == "minecraft:powder_snow";
+            let lava_cauldron = name == "minecraft:lava_cauldron";
             // getEntityInsideCollisionShape is the whole block but for powder
             // snow (its collision shape, the whole block when it is empty),
             // filled cauldrons, end portals and tripwires; Horizon doesn't
-            // follow the player into those last three.
+            // follow the player into the water and powder snow cauldrons, end
+            // portals or tripwires yet.
             if matches!(
                 name,
                 "minecraft:water_cauldron"
-                    | "minecraft:lava_cauldron"
                     | "minecraft:powder_snow_cauldron"
                     | "minecraft:end_portal"
                     | "minecraft:tripwire"
             ) {
                 continue;
             }
-            let inside = !powder_snow || {
+            let inside = !(powder_snow || lava_cauldron) || {
                 let context = self.context();
                 let binding = self.collision_binding;
                 let shape = binding.collision_shape_with_context(
@@ -1282,21 +1283,30 @@ impl MotionWorld<'_, '_, '_> {
                     p,
                     &context,
                 )?;
-                shape.is_empty() || shape.boxes() == VoxelShape::block().boxes() || {
-                    let boxes: Vec<_> = shape
-                        .moved(Vec3::new(f64::from(p.x), f64::from(p.y), f64::from(p.z)))
-                        .boxes()
-                        .to_vec();
-                    self.player
-                        .dimensions
-                        .bounds(from)
-                        .collided_along_vector(to.subtract(from), &boxes)
-                }
+                powder_snow && (shape.is_empty() || shape.boxes() == VoxelShape::block().boxes())
+                    || {
+                        let offset = Vec3::new(f64::from(p.x), f64::from(p.y), f64::from(p.z));
+                        let mut boxes: Vec<_> = shape.moved(offset).boxes().to_vec();
+                        if lava_cauldron {
+                            // LavaCauldronBlock.FILLED_SHAPE: the cauldron's
+                            // shape or its lava, Block.column(12, 4, 15).
+                            boxes.push(Aabb::new(
+                                Vec3::new(2.0 / 16.0, 4.0 / 16.0, 2.0 / 16.0).add_vector(offset),
+                                Vec3::new(14.0 / 16.0, 15.0 / 16.0, 14.0 / 16.0).add_vector(offset),
+                            ));
+                        }
+                        self.player
+                            .dimensions
+                            .bounds(from)
+                            .collided_along_vector(to.subtract(from), &boxes)
+                    }
             };
             if inside && visited.insert(p.pack()) {
-                // CactusBlock and CampfireBlock.entityInside (`entity.hurt`).
+                // CactusBlock, CampfireBlock and LavaCauldronBlock.entityInside
+                // (`entity.hurt`).
                 match name {
                     "minecraft:cactus" => self.environment_hurt("minecraft:cactus", 1.0)?,
+                    "minecraft:lava_cauldron" => self.lava_cauldron_inside()?,
                     "minecraft:campfire" | "minecraft:soul_campfire" => {
                         let lit = self
                             .assets
@@ -1354,6 +1364,14 @@ impl MotionWorld<'_, '_, '_> {
         }
         self.player.impulse.try_reset();
     }
+    /// `LavaCauldronBlock.entityInside`: CLEAR_FREEZE, LAVA_IGNITE
+    /// (`Entity.lavaIgnite`, 15 seconds) and then `Entity.lavaHurt` (lava,
+    /// 4), as ordinary lava does to the player.
+    fn lava_cauldron_inside(&mut self) -> Result<()> {
+        self.player.ticks_frozen = 0;
+        self.player.ignite_for_ticks(300)?;
+        self.environment_hurt("minecraft:lava", 4.0)
+    }
     /// `WebBlock.entityInside`: stuck at a quarter of the speed, half with
     /// the Weaving effect.
     fn web_inside(&mut self) {
@@ -2368,6 +2386,54 @@ mod tests {
         assert_eq!(player.position.y, 4.0);
     }
 
+    #[test]
+    fn a_lava_cauldron_burns_the_player_inside_it() {
+        let root = std::env::var_os("HORIZON_TEST_RESOURCES")
+            .map(std::path::PathBuf::from)
+            .unwrap_or_else(|| {
+                Path::new(env!("CARGO_MANIFEST_DIR"))
+                    .join("../../.local/horizon-client")
+                    .join(horizon_core::VANILLA_VERSION)
+            });
+        if !root.join("movement-properties.nbt").exists() {
+            return;
+        }
+        let assets = Assets::load(&root).unwrap();
+        let render = assets.reload(&root).unwrap();
+        let binding = crate::collisions::load(&root, assets.registry).unwrap();
+        let resources = MotionResources::load(&root, &assets).unwrap();
+        let mut scene = World::test_scene(&assets, &render, 1).unwrap();
+        let cauldron = assets
+            .registry
+            .default_state("minecraft:lava_cauldron")
+            .unwrap();
+        scene.set(20, 4, 20, cauldron).unwrap();
+        let mut tick = |player: &mut PlayerMotion| {
+            MotionWorld {
+                entities: &[],
+                player,
+                scene: &mut scene,
+                assets: &assets,
+                collision_binding: &binding,
+                resources: &resources,
+            }
+            .controlled_simulation_tick(Default::default())
+            .unwrap();
+        };
+        // Standing on the cauldron's floor, in its lava.
+        let mut player = PlayerMotion::new(&resources, Vec3::new(20.5, 4.25, 20.5)).unwrap();
+        player.ticks_frozen = 40;
+        tick(&mut player);
+        assert!(player.health.health() < 20.0, "the lava must hurt");
+        assert!(player.fire_ticks > 0, "the lava must ignite");
+        assert_eq!(player.ticks_frozen, 0);
+        // Beside it, nothing.
+        let mut away = PlayerMotion::new(&resources, Vec3::new(22.5, 4.0, 20.5)).unwrap();
+        tick(&mut away);
+        assert_eq!(away.health.health(), 20.0);
+        assert!(away.fire_ticks <= 0);
+    }
+
     #[test]
     fn server_travel_moves_only_the_velocity() {
         let root = Path::new(env!("CARGO_MANIFEST_DIR"))

From 467277ef6d70de648f45ce6c66409b28644d796e Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:21:53 +0100
Subject: [PATCH 096/270] Update comparators when a guest changes a chest
 through its menu

A container click from a server-thread or LAN player wrote the slots but
never called BlockEntity.setChanged, so comparators kept the old output.
Notify the block entity when the click changed the container's slots.
---
 crates/horizon-client/src/game/lan_actions.rs | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..8da418271 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1075,7 +1075,20 @@ impl Game<'_> {
             }
             S::ContainerClick(p) => {
                 let rules = ItemRules(self.res.items());
+                let slots = host.hub.guests[gi]
+                    .menu
+                    .as_ref()
+                    .filter(|m| m.window == p.container)
+                    .map(|m| m.slots);
+                let before = slots.and_then(|s| s.read(&self.world, &host.hub.guests[gi]));
                 let drops = host.hub.container_click(conn, &p, &mut self.world, &rules);
+                // A click that changed the container's slots: BlockEntity.setChanged,
+                // so comparators read it again (a double chest's other half follows).
+                if let Some(Slots::Block(key) | Slots::Double(key, _)) = slots
+                    && slots.and_then(|s| s.read(&self.world, &host.hub.guests[gi])) != before
+                {
+                    self.container_changed(key);
+                }
                 self.drop_guest_items(host, gi, drops);
             }
             S::ContainerClose(p) => {

From 3843a9a4aae425fa4ec4f759dc9e4e37a5c44abc Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:27:51 +0100
Subject: [PATCH 097/270] Use the team-formatted player name in chat

Chat, /say, /me and /tell now name the sender the way
Player.getDisplayName does: the team prefix, the name and the suffix
in the team colour. On a server the hub gets the scoreboard's teams
each tick; in-frame the existing player_display_name is used.
---
 crates/horizon-client/src/game/chat.rs       |  2 +-
 crates/horizon-client/src/game/commands.rs   |  8 +++----
 crates/horizon-client/src/game/scoreboard.rs |  1 +
 crates/horizon-client/src/lan/hub.rs         | 22 ++++++++++++++++++++
 crates/horizon-client/src/lan/hub/chat.rs    | 12 +++++------
 5 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/crates/horizon-client/src/game/chat.rs b/crates/horizon-client/src/game/chat.rs
index ec85732ae..9fd3157c4 100644
--- a/crates/horizon-client/src/game/chat.rs
+++ b/crates/horizon-client/src/game/chat.rs
@@ -586,7 +586,7 @@ impl Game<'_> {
         } else {
             let line = Text::translate(
                 "chat.type.text",
-                &[Text::literal(PLAYER_NAME), Text::literal(message)],
+                &[self.player_display_name(), Text::literal(message)],
             );
             let focused = self.screen == Screen::Chat;
             let heard = self.mods.running().then(|| line.plain());
diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index 19a16e261..b84f13e4a 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -214,7 +214,7 @@ impl Game<'_> {
     }
     /// Player.getDisplayName: the name (team-formatted), suggesting a
     /// `/tell`, showing the player on hover, inserting the name.
-    fn player_display_name(&self) -> Text {
+    pub(super) fn player_display_name(&self) -> Text {
         let name = self.acting_player_name().to_owned();
         let Some(uuid) = self.lan_acting_uuid else {
             return self.target_name(Target::Player);
@@ -2809,7 +2809,7 @@ impl Game<'_> {
         let name = match self.command_source.map(|s| s.entity) {
             Some(Some(t)) => self.target_name(t),
             Some(None) => Text::literal("Server"),
-            None => Text::literal(self.acting_player_name()),
+            None => self.player_display_name(),
         };
         let line = match id {
             "say" => Text::translate("chat.type.announcement", &[name, message]),
@@ -2819,14 +2819,14 @@ impl Game<'_> {
                 // Whispering to yourself: the incoming and outgoing lines.
                 let out = Text::translate(
                     "commands.message.display.outgoing",
-                    &[Text::literal(self.acting_player_name()), message.clone()],
+                    &[self.player_display_name(), message.clone()],
                 )
                 .with_color(text::GRAY)
                 .italic();
                 self.system_message(out);
                 Text::translate(
                     "commands.message.display.incoming",
-                    &[Text::literal(self.acting_player_name()), message],
+                    &[self.player_display_name(), message],
                 )
                 .with_color(text::GRAY)
                 .italic()
diff --git a/crates/horizon-client/src/game/scoreboard.rs b/crates/horizon-client/src/game/scoreboard.rs
index 227a09a6c..81c03e288 100644
--- a/crates/horizon-client/src/game/scoreboard.rs
+++ b/crates/horizon-client/src/game/scoreboard.rs
@@ -332,6 +332,7 @@ impl Game<'_> {
             return;
         }
         self.load_scoreboard();
+        host.hub.teams.clone_from(&self.score.board.teams);
         let view = horizon_client::lan::scoreboard::View::of(&self.score.board);
         for g in host.hub.guests.iter_mut().filter(|g| g.placed) {
             if g.scoreboard != view {
diff --git a/crates/horizon-client/src/lan/hub.rs b/crates/horizon-client/src/lan/hub.rs
index c2a395899..fd2381596 100644
--- a/crates/horizon-client/src/lan/hub.rs
+++ b/crates/horizon-client/src/lan/hub.rs
@@ -149,6 +149,9 @@ pub struct Hub {
     pub singleplayer_owner: Option<u128>,
     /// Who rides what, set by the game before each tick.
     pub riding: super::entity::Riding,
+    /// The scoreboard's teams, set by the game each tick, for players'
+    /// display names.
+    pub teams: Vec<crate::scoreboard::Team>,
     last_clock: i64,
     last_rate: f32,
     ticking: (f32, bool),
@@ -206,6 +209,24 @@ pub fn display_name(uuid: u128, name: &str) -> Tag {
     ])
 }
 
+impl Hub {
+    /// Player.getDisplayName: the name formatted for the player's team
+    /// (PlayerTeam.formatNameForTeam), suggesting `/tell NAME `, showing the
+    /// player on hover and inserting the name.
+    pub fn player_display_name(&self, uuid: u128, name: &str) -> Tag {
+        let Some(team) = self.teams.iter().find(|t| t.players.contains(name)) else {
+            return display_name(uuid, name);
+        };
+        let mut c = team.formatted_name_comp(&crate::scoreboard::literal(name));
+        c["click_event"] =
+            serde_json::json!({"action": "suggest_command", "command": format!("/tell {name} ")});
+        c["hover_event"] = serde_json::json!({"action": "show_entity", "id": "minecraft:player",
+            "uuid": horizon_protocol::crypto::uuid_string(uuid), "name": name});
+        c["insertion"] = name.into();
+        crate::scoreboard::component_tag(&c)
+    }
+}
+
 /// A yellow translation of player names (`multiplayer.player.joined`).
 fn yellow_names(key: &str, names: Vec<Tag>) -> Tag {
     Tag::compound([
@@ -315,6 +336,7 @@ impl Hub {
             entity_types: Default::default(),
             entities: Default::default(),
             entity_out: Vec::new(),
+            teams: Vec::new(),
         }
     }
 
diff --git a/crates/horizon-client/src/lan/hub/chat.rs b/crates/horizon-client/src/lan/hub/chat.rs
index 7e75c84c5..bdc7c3fb2 100644
--- a/crates/horizon-client/src/lan/hub/chat.rs
+++ b/crates/horizon-client/src/lan/hub/chat.rs
@@ -2,7 +2,7 @@
 //! handle it: chat sessions validated against the services' keys, signed
 //! messages checked link by link, the acknowledged window, and messages
 //! relayed with each connection's numbering and signature cache.
-use super::{HostEvent, Hub, display_name};
+use super::{HostEvent, Hub};
 use horizon_protocol::{
     packets::play::{self, Clientbound as C},
     secure_chat::{self, Body, Chain, ChatSession, DecodeError, ProfileKey, Signature, Unpacked},
@@ -214,7 +214,7 @@ impl Hub {
         }
         let bound = play::ChatTypeBound {
             chat_type: self.chat_type,
-            name: display_name(uuid, &name),
+            name: self.player_display_name(uuid, &name),
             target: None,
         };
         let line = format!("<{name}> {}", message.content);
@@ -427,7 +427,7 @@ impl Hub {
         let (uuid, name) = (self.guests[i].uuid, self.guests[i].name.clone());
         let bound = play::ChatTypeBound {
             chat_type: self.chat_type_id(chat_type),
-            name: display_name(uuid, &name),
+            name: self.player_display_name(uuid, &name),
             target: None,
         };
         let line = match chat_type {
@@ -467,15 +467,15 @@ impl Hub {
             self.chat_type_id("msg_command_incoming"),
         );
         for &t in targets {
-            let target = display_name(self.guests[t].uuid, &self.guests[t].name);
+            let target = self.player_display_name(self.guests[t].uuid, &self.guests[t].name);
             let out = play::ChatTypeBound {
                 chat_type: outgoing,
-                name: display_name(uuid, &name),
+                name: self.player_display_name(uuid, &name),
                 target: Some(target),
             };
             let inc = play::ChatTypeBound {
                 chat_type: incoming,
-                name: display_name(uuid, &name),
+                name: self.player_display_name(uuid, &name),
                 target: None,
             };
             match &message {

From 13e83e4e63e13752978d552980b997573013fea4 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:36:01 +0100
Subject: [PATCH 098/270] Read saved attribute bases for every mob

LivingEntity.readAdditionalSaveData applies the attributes list for any
living entity, then sets the health (the max health when none is saved).
Only horses read max_health and movement_speed, so a summoned cow kept its
type defaults. Read max_health, movement_speed and attack_damage for all
mobs before the health; horses still read jump_strength.
---
 crates/horizon-client/src/entity_nbt.rs | 26 +++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/entity_nbt.rs b/crates/horizon-client/src/entity_nbt.rs
index bf0764a6b..00576ea02 100644
--- a/crates/horizon-client/src/entity_nbt.rs
+++ b/crates/horizon-client/src/entity_nbt.rs
@@ -617,9 +617,23 @@ pub fn mob_from_nbt(tag: &Tag, types: &HashMap<String, Arc<MobType>>, id: u32) -
     m.head_pitch = pitch;
     m.on_ground = flag(tag, "OnGround");
     m.fall_distance = float(tag.get("fall_distance")).unwrap_or(0.0);
-    if let Some(h) = float(tag.get("Health")) {
-        m.health = h as f32;
+    // LivingEntity.readAdditionalSaveData: the saved attribute bases, then
+    // the health, the max health when there is none.
+    if let Some(Tag::List(attrs)) = tag.get("attributes") {
+        for a in attrs {
+            let (Some(id), Some(Tag::Double(bits))) = (text(a.get("id")), a.get("base")) else {
+                continue;
+            };
+            let v = f64::from_bits(*bits);
+            match id.as_str() {
+                "minecraft:max_health" => m.attrs.max_health = v as f32,
+                "minecraft:movement_speed" => m.attrs.speed = v,
+                "minecraft:attack_damage" => m.attrs.attack_damage = v as f32,
+                _ => {}
+            }
+        }
     }
+    m.health = float(tag.get("Health")).map_or(m.attrs.max_health, |h| h as f32);
     m.hurt_time = number(tag.get("HurtTime")).unwrap_or(0) as i32;
     // What it holds (equipment.mainhand / offhand), when saved.
     if let Some(eq) = tag.get("equipment") {
@@ -735,12 +749,8 @@ pub fn mob_from_nbt(tag: &Tag, types: &HashMap<String, Arc<MobType>>, id: u32) -
                 let (Some(id), Some(Tag::Double(bits))) = (text(a.get("id")), a.get("base")) else {
                     continue;
                 };
-                let v = f64::from_bits(*bits);
-                match id.as_str() {
-                    "minecraft:max_health" => m.attrs.max_health = v as f32,
-                    "minecraft:movement_speed" => m.attrs.speed = v,
-                    "minecraft:jump_strength" => m.extra.vector[0] = v,
-                    _ => {}
+                if id == "minecraft:jump_strength" {
+                    m.extra.vector[0] = f64::from_bits(*bits);
                 }
             }
         }

From 5d40d6a33ea36d07440d4eecf03ab63028eff3f6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:54:39 +0100
Subject: [PATCH 099/270] Telemetry server: the hub's votes (POST /hub/vote,
 GET /hub/votes)

A thumbs-up on a roadmap item at playhorizon.dev/hub: one per browser (a random
id the page keeps), taken back with "up": false, counts cached a minute. Item ids
are checked for shape and capped at 1000 distinct items. Rate limits key their
buckets by a keyed hash of the address (key drawn at start, in memory); no address
is stored. CORS preflight for the website's JSON posts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-telemetry-server/README.md    |   7 +-
 crates/horizon-telemetry-server/src/hub.rs   | 239 +++++++++++++++++++
 crates/horizon-telemetry-server/src/lib.rs   |  29 ++-
 crates/horizon-telemetry-server/src/store.rs |   3 +-
 crates/horizon-telemetry-server/tests/hub.rs | 116 +++++++++
 5 files changed, 388 insertions(+), 6 deletions(-)
 create mode 100644 crates/horizon-telemetry-server/src/hub.rs
 create mode 100644 crates/horizon-telemetry-server/tests/hub.rs

diff --git a/crates/horizon-telemetry-server/README.md b/crates/horizon-telemetry-server/README.md
index ed54024a1..2b86bf99d 100644
--- a/crates/horizon-telemetry-server/README.md
+++ b/crates/horizon-telemetry-server/README.md
@@ -1,6 +1,6 @@
 # horizon-telemetry-server
 
-This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only. It is one small Rust process, about 7 MB of memory when idle.
+This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only, and the 👍 players give roadmap items on the hub (playhorizon.dev/hub). It is one small Rust process, about 7 MB of memory when idle.
 
     cargo run --release                     # in this folder: its own workspace, like the launcher's
     PORT=8080 HORIZON_TELEMETRY_DB=/data/telemetry.sqlite3 horizon-telemetry-server
@@ -17,6 +17,8 @@ It runs at **https://telemetry.playhorizon.dev** (`DEFAULT_ENDPOINT` in `crates/
 | `GET /v1/benchmarks/summary` | Players' benchmark uploads grouped by GPU, CPU, render distance and game, for the website's Benchmarks page (below). Cached 10 minutes, same `Access-Control-Allow-Origin`. |
 | `POST /v1/live` | A game's "I'm playing" ping (JSON, at most 512 bytes). Returns 204. Returns 400 for a bad ping, 413 for one too large, 429 over the address's limit, 503 when it holds `LIVE_MAX_SESSIONS` already. |
 | `GET /v1/live` | How many play now, rounded: `playing`, `lan`, `versions`, `platforms`. Made again at most every 15 seconds, with the same `Access-Control-Allow-Origin`. |
+| `POST /hub/vote` | `{"item": "<roadmap id>", "voter": "<the browser's random id>", "up": true}`: a 👍 on a roadmap item, one per voter; `"up": false` takes it back. Returns `{"item", "votes"}`. 400 for a bad id, 429 over the address's limit. `OPTIONS` answers the website's preflight. |
+| `GET /hub/votes` | `{"votes": {"<item>": n}}`. Made again at most every minute. |
 | `GET /healthz` | `ok` |
 
 The totals are grouped per version, OS, GPU vendor and render distance. Each group has its sessions, install-days, hours played, the 14 frame-time buckets summed, and the mean p50 and p99 frame times. Groups with fewer than 5 install-days are left out. The totals also list crash counts per version. Benchmark uploads are published only through the summary below, never one by one.
@@ -56,6 +58,8 @@ The live count is a table in memory: a session ID, when it last pinged, its vers
 
 The day stored is the day the server received an item. The sender's IP address is never written down. The per-address rate limit keeps addresses in memory for an hour at most.
 
+A hub vote is stored as an item ID and the browser's random ID. The hub's rate limits key their buckets by a hash of the address with a key drawn at each start, in memory.
+
 Raw rows are deleted after `HORIZON_TELEMETRY_RETENTION_DAYS` (180). The daily totals stay; they hold no install ID.
 
 ## Settings
@@ -73,6 +77,7 @@ All are environment variables:
 - `HORIZON_TELEMETRY_LIVE_PER_HOUR` per address, pings and reads (600, bursts of 60: ten players behind one address)
 - `HORIZON_TELEMETRY_LIVE_WINDOW_SECONDS` (120)
 - `HORIZON_TELEMETRY_LIVE_MAX_SESSIONS` (200 000)
+- `HORIZON_TELEMETRY_HUB_PER_HOUR` votes and vote reads per address (120, bursts of 12)
 
 ## Hosting
 
diff --git a/crates/horizon-telemetry-server/src/hub.rs b/crates/horizon-telemetry-server/src/hub.rs
new file mode 100644
index 000000000..ebf22610d
--- /dev/null
+++ b/crates/horizon-telemetry-server/src/hub.rs
@@ -0,0 +1,239 @@
+//! The hub's votes: a 👍 on a roadmap item at playhorizon.dev/hub. roadmap/README.md documents them for Kira and the website.
+//!
+//! - `POST /hub/vote`: a 👍 on a roadmap item, one per browser (`voter`, a random id the page makes and
+//!   keeps); `"up": false` takes it back. Answers the item's count.
+//! - `GET /hub/votes`: every item's count, cached a minute.
+//!
+//! Stored: an item id and the browser's random id per vote. Never an IP address: the rate limits key their
+//! buckets by a hash of it with a key drawn at start, in memory.
+use std::collections::HashMap;
+use std::hash::BuildHasher;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use axum::extract::{Request, State};
+use axum::http::{HeaderValue, StatusCode, header};
+use axum::response::Response;
+use rusqlite::params;
+use serde_json::{Map, Value, json};
+
+use crate::store::Store;
+use crate::{App, json_response, peer, take};
+
+pub const SCHEMA: &str = "
+CREATE TABLE IF NOT EXISTS hub_votes (item TEXT NOT NULL, voter TEXT NOT NULL, PRIMARY KEY (item, voter)) WITHOUT ROWID;
+";
+
+/// Items with votes, at most: a vote for a new id past this is refused (ids are only checked for shape).
+const MAX_ITEMS: i64 = 1000;
+/// The largest body accepted: a report's fields at their limits, as JSON, fit.
+const MAX_BODY: usize = 24 * 1024;
+const VOTES_FOR: Duration = Duration::from_secs(60);
+
+/// The hub's buckets: keyed by a keyed hash of the address, never the address itself.
+pub type HashedBuckets = HashMap<u64, (f64, Instant)>;
+
+/// A roadmap item id's shape: lowercase words joined by dashes (tools/roadmap.py), at most 48 characters.
+pub fn item_id(id: &str) -> bool {
+    (1..=48).contains(&id.len())
+        && !id.starts_with('-')
+        && !id.ends_with('-')
+        && !id.contains("--")
+        && id
+            .bytes()
+            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+}
+
+/// A voter id's shape: what `crypto.randomUUID()` and similar make.
+fn voter_id(id: &str) -> bool {
+    (16..=64).contains(&id.len())
+        && id
+            .bytes()
+            .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
+}
+
+impl Store {
+    /// Adds or takes back a vote; the item's count after it. None when the item would be one too many.
+    pub fn vote(&mut self, item: &str, voter: &str, up: bool) -> rusqlite::Result<Option<i64>> {
+        let tx = self.db.transaction()?;
+        if up {
+            let known = tx
+                .prepare("SELECT 1 FROM hub_votes WHERE item = ?1 LIMIT 1")?
+                .exists([item])?;
+            let items: i64 =
+                tx.query_row("SELECT count(DISTINCT item) FROM hub_votes", [], |r| {
+                    r.get(0)
+                })?;
+            if !known && items >= MAX_ITEMS {
+                return Ok(None);
+            }
+            tx.execute(
+                "INSERT OR IGNORE INTO hub_votes (item, voter) VALUES (?1, ?2)",
+                params![item, voter],
+            )?;
+        } else {
+            tx.execute(
+                "DELETE FROM hub_votes WHERE item = ?1 AND voter = ?2",
+                params![item, voter],
+            )?;
+        }
+        let count = tx.query_row(
+            "SELECT count(*) FROM hub_votes WHERE item = ?1",
+            [item],
+            |r| r.get(0),
+        )?;
+        tx.commit()?;
+        Ok(Some(count))
+    }
+
+    /// Every item's count.
+    pub fn votes(&self) -> rusqlite::Result<Map<String, Value>> {
+        let mut statement = self
+            .db
+            .prepare("SELECT item, count(*) FROM hub_votes GROUP BY item ORDER BY item")?;
+        let rows =
+            statement.query_map([], |r| Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)?)))?;
+        rows.map(|row| row.map(|(item, n)| (item, Value::from(n))))
+            .collect()
+    }
+}
+
+impl App {
+    pub(crate) fn hashed(&self, req: &Request) -> u64 {
+        self.hub_key.hash_one(self.client(req.headers(), peer(req)))
+    }
+
+    /// Takes a token from the address's hub bucket (votes and reads of the counts).
+    fn allow_hub(&self, req: &Request) -> bool {
+        take(
+            &self.hub_buckets,
+            self.config.hub_per_hour,
+            self.hashed(req),
+        )
+    }
+
+    /// The hub's share of `maintain`: idle buckets are forgotten.
+    pub(crate) fn forget_hub_buckets(&self) {
+        self.hub_buckets
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .retain(|_, (_, at)| at.elapsed() < Duration::from_secs(3600));
+    }
+}
+
+/// A JSON answer to the website: its origin may read it, nothing caches it.
+pub(crate) fn answer(app: &App, code: StatusCode, body: Value) -> Response {
+    let mut response = json_response(app, body.to_string(), 0);
+    *response.status_mut() = code;
+    response
+        .headers_mut()
+        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    response
+}
+
+pub(crate) fn refuse(app: &App, code: StatusCode, message: &str) -> Response {
+    answer(app, code, json!({ "error": message }))
+}
+
+/// A browser's preflight for the JSON posts: the website may post them.
+pub async fn preflight(State(app): State<Arc<App>>) -> Response {
+    let mut response = answer(&app, StatusCode::NO_CONTENT, Value::Null);
+    *response.body_mut() = axum::body::Body::empty();
+    let headers = response.headers_mut();
+    headers.remove(header::CONTENT_TYPE);
+    headers.insert(
+        header::ACCESS_CONTROL_ALLOW_METHODS,
+        HeaderValue::from_static("POST"),
+    );
+    headers.insert(
+        header::ACCESS_CONTROL_ALLOW_HEADERS,
+        HeaderValue::from_static("content-type"),
+    );
+    headers.insert(
+        header::ACCESS_CONTROL_MAX_AGE,
+        HeaderValue::from_static("86400"),
+    );
+    response
+}
+
+pub(crate) async fn json_body(req: Request) -> Result<Value, &'static str> {
+    let bytes = axum::body::to_bytes(req.into_body(), MAX_BODY)
+        .await
+        .map_err(|_| "too large")?;
+    serde_json::from_slice(&bytes).map_err(|_| "send JSON")
+}
+
+/// `POST /hub/vote` `{"item", "voter", "up"}`: 200 `{"item", "votes"}`.
+pub async fn vote(State(app): State<Arc<App>>, req: Request) -> Response {
+    if !app.allow_hub(&req) {
+        return refuse(&app, StatusCode::TOO_MANY_REQUESTS, "too many requests");
+    }
+    let body = match json_body(req).await {
+        Ok(body) => body,
+        Err(e) => return refuse(&app, StatusCode::BAD_REQUEST, e),
+    };
+    let item = body["item"].as_str().unwrap_or("");
+    let voter = body["voter"].as_str().unwrap_or("");
+    if !item_id(item) || !voter_id(voter) {
+        return refuse(&app, StatusCode::BAD_REQUEST, "an item id and a voter id");
+    }
+    let up = body["up"].as_bool().unwrap_or(true);
+    let counted = app.store().vote(item, voter, up);
+    match counted {
+        Ok(Some(votes)) => {
+            *app.votes_cache.lock().unwrap_or_else(|e| e.into_inner()) = None;
+            answer(
+                &app,
+                StatusCode::OK,
+                json!({ "item": item, "votes": votes }),
+            )
+        }
+        Ok(None) => refuse(&app, StatusCode::BAD_REQUEST, "no such item"),
+        Err(e) => {
+            eprintln!("horizon-telemetry-server: could not store a vote: {e}");
+            refuse(&app, StatusCode::SERVICE_UNAVAILABLE, "try again later")
+        }
+    }
+}
+
+/// `GET /hub/votes`: `{"votes": {"<item>": n}}`, made again at most every minute.
+pub async fn votes(State(app): State<Arc<App>>, req: Request) -> Response {
+    if !app.allow_hub(&req) {
+        return refuse(&app, StatusCode::TOO_MANY_REQUESTS, "too many requests");
+    }
+    let json = {
+        let mut cache = app.votes_cache.lock().unwrap_or_else(|e| e.into_inner());
+        match &*cache {
+            Some((at, json)) if at.elapsed() < VOTES_FOR => json.clone(),
+            _ => {
+                let counts = app.store().votes();
+                match counts {
+                    Ok(counts) => {
+                        let json = json!({ "votes": counts }).to_string();
+                        *cache = Some((Instant::now(), json.clone()));
+                        json
+                    }
+                    Err(e) => {
+                        eprintln!("horizon-telemetry-server: could not read the votes: {e}");
+                        return refuse(&app, StatusCode::SERVICE_UNAVAILABLE, "try again later");
+                    }
+                }
+            }
+        }
+    };
+    json_response(&app, json, VOTES_FOR.as_secs())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ids_are_checked_for_shape() {
+        assert!(item_id("smooth-frames") && item_id("v2"));
+        for bad in ["", "-a", "a-", "a--b", "Smooth", "a b", &"a".repeat(49)] {
+            assert!(!item_id(bad), "{bad}");
+        }
+        assert!(voter_id("0b7c3c9e-3f0a-4d8e-9a39-4c1f5a6b7d21") && !voter_id("short"));
+    }
+}
diff --git a/crates/horizon-telemetry-server/src/lib.rs b/crates/horizon-telemetry-server/src/lib.rs
index 1a8e750e6..19ba3e1dc 100644
--- a/crates/horizon-telemetry-server/src/lib.rs
+++ b/crates/horizon-telemetry-server/src/lib.rs
@@ -7,6 +7,7 @@
 //!   least 3 installs only (`summary`), cached; the website's Benchmarks page reads it.
 //! - `POST /v1/live`: a game's anonymous "I'm playing" ping (`live`, in memory only).
 //! - `GET /v1/live`: how many play now, rounded, cached briefly.
+//! - `POST /hub/vote`, `GET /hub/votes`: the hub's 👍 on roadmap items (`hub`).
 //! - `GET /healthz`.
 //!
 //! Abuse limits: a token bucket per IP address (kept in memory for an hour, never stored), a
@@ -15,6 +16,7 @@
 //! rows expire after `retention_days`; the daily totals stay. One small process and one SQLite
 //! file: see `README.md` for running it.
 use std::collections::HashMap;
+use std::hash::{Hash, RandomState};
 use std::net::{IpAddr, SocketAddr};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
@@ -27,6 +29,7 @@ use axum::routing::{delete, get, post};
 use horizon_telemetry::batch;
 
 pub mod classes;
+pub mod hub;
 pub mod live;
 pub mod store;
 pub mod summary;
@@ -56,6 +59,8 @@ pub struct Config {
     pub live_window: Duration,
     /// Sessions the live count holds at most; a new one past that is refused.
     pub live_max_sessions: usize,
+    /// The hub's votes and reads of their counts an IP address may make an hour.
+    pub hub_per_hour: f64,
 }
 
 impl Default for Config {
@@ -70,6 +75,7 @@ impl Default for Config {
             live_per_hour: 600.0,
             live_window: horizon_telemetry::live::WINDOW,
             live_max_sessions: 200_000,
+            hub_per_hour: 120.0,
         }
     }
 }
@@ -77,7 +83,7 @@ impl Default for Config {
 impl Config {
     /// The defaults, with `HORIZON_TELEMETRY_RETENTION_DAYS`, `…_MIN_INSTALL_DAYS`,
     /// `…_REQUESTS_PER_HOUR`, `…_ITEMS_PER_DAY`, `…_TRUST_PROXY` (1), `…_ALLOW_ORIGIN`,
-    /// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS` and `…_LIVE_MAX_SESSIONS`.
+    /// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS`, `…_LIVE_MAX_SESSIONS` and `…_HUB_PER_HOUR`.
     pub fn from_env() -> Self {
         let var = |k: &str| std::env::var(format!("HORIZON_TELEMETRY_{k}")).ok();
         let d = Self::default();
@@ -105,6 +111,9 @@ impl Config {
             live_max_sessions: var("LIVE_MAX_SESSIONS")
                 .and_then(|v| v.parse().ok())
                 .unwrap_or(d.live_max_sessions),
+            hub_per_hour: var("HUB_PER_HOUR")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(d.hub_per_hour),
         }
     }
 }
@@ -126,6 +135,12 @@ pub struct App {
     summary_cache: Mutex<Option<(Instant, String)>>,
     /// Today, in days since 1970 (a test moves it).
     today: Box<dyn Fn() -> u32 + Send + Sync>,
+    /// The key the hub's buckets hash addresses with, drawn at start and never stored.
+    hub_key: RandomState,
+    /// The hub's votes and vote counts, per hashed address.
+    hub_buckets: Mutex<hub::HashedBuckets>,
+    /// `GET /hub/votes`'s answer and when it was made.
+    votes_cache: Mutex<Option<(Instant, String)>>,
 }
 
 type Buckets = HashMap<IpAddr, (f64, Instant)>;
@@ -157,6 +172,9 @@ impl App {
             cache: Mutex::default(),
             summary_cache: Mutex::default(),
             today,
+            hub_key: RandomState::new(),
+            hub_buckets: Mutex::default(),
+            votes_cache: Mutex::default(),
         })
     }
 
@@ -221,6 +239,7 @@ impl App {
     pub fn maintain(&self) -> rusqlite::Result<usize> {
         let oldest = (self.today)().saturating_sub(self.config.retention_days);
         let removed = self.store().expire(oldest)?;
+        self.forget_hub_buckets();
         for buckets in [&self.buckets, &self.live_buckets] {
             buckets
                 .lock()
@@ -235,14 +254,14 @@ impl App {
     }
 }
 
-/// Takes a token for `ip` from its bucket in `buckets` (`per_hour`, bursts of a tenth of it);
+/// Takes a token for `key` from its bucket in `buckets` (`per_hour`, bursts of a tenth of it);
 /// false when it has none left.
-fn take(buckets: &Mutex<Buckets>, per_hour: f64, ip: IpAddr) -> bool {
+fn take<K: Hash + Eq>(buckets: &Mutex<HashMap<K, (f64, Instant)>>, per_hour: f64, key: K) -> bool {
     let rate = per_hour / 3600.0;
     let burst = (per_hour / 10.0).max(1.0);
     let mut buckets = buckets.lock().unwrap_or_else(|e| e.into_inner());
     let now = Instant::now();
-    let (tokens, at) = buckets.entry(ip).or_insert((burst, now));
+    let (tokens, at) = buckets.entry(key).or_insert((burst, now));
     *tokens = (*tokens + now.duration_since(*at).as_secs_f64() * rate).min(burst);
     *at = now;
     if *tokens < 1.0 {
@@ -482,6 +501,8 @@ pub fn router(app: Arc<App>) -> Router {
         .route("/v1/installs/{id}", delete(forget))
         .route("/v1/aggregate", get(aggregate))
         .route("/v1/benchmarks/summary", get(benchmarks))
+        .route("/hub/vote", post(hub::vote).options(hub::preflight))
+        .route("/hub/votes", get(hub::votes))
         .route("/healthz", get(|| async { "ok" }))
         .with_state(app)
 }
diff --git a/crates/horizon-telemetry-server/src/store.rs b/crates/horizon-telemetry-server/src/store.rs
index 02c8803ae..d1137d197 100644
--- a/crates/horizon-telemetry-server/src/store.rs
+++ b/crates/horizon-telemetry-server/src/store.rs
@@ -123,13 +123,14 @@ pub fn gpu_vendor(gpu: &str) -> &'static str {
 }
 
 pub struct Store {
-    db: Connection,
+    pub(crate) db: Connection,
 }
 
 impl Store {
     pub fn open(path: &str) -> rusqlite::Result<Self> {
         let mut db = Connection::open(path)?;
         db.execute_batch(SCHEMA)?;
+        db.execute_batch(crate::hub::SCHEMA)?;
         migrate(&mut db)?;
         Ok(Self { db })
     }
diff --git a/crates/horizon-telemetry-server/tests/hub.rs b/crates/horizon-telemetry-server/tests/hub.rs
new file mode 100644
index 000000000..10ddc12c4
--- /dev/null
+++ b/crates/horizon-telemetry-server/tests/hub.rs
@@ -0,0 +1,116 @@
+//! The hub's votes through the HTTP interface.
+use std::sync::Arc;
+
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use horizon_telemetry_server::store::Store;
+use horizon_telemetry_server::{App, Config, router};
+use http_body_util::BodyExt;
+use serde_json::{Value, json};
+use tower::ServiceExt;
+
+const DAY: u32 = 20_741;
+const VOTER: &str = "0b7c3c9e-3f0a-4d8e-9a39-4c1f5a6b7d21";
+
+struct Hub {
+    app: Arc<App>,
+}
+
+fn hub(config: Config) -> Hub {
+    let app = App::with_clock(Store::open(":memory:").unwrap(), config, Box::new(|| DAY));
+    Hub { app }
+}
+
+fn config() -> Config {
+    Config::default()
+}
+
+impl Hub {
+    async fn send(&self, req: Request<Body>) -> (StatusCode, Value) {
+        let res = router(self.app.clone()).oneshot(req).await.unwrap();
+        let code = res.status();
+        let body = res.into_body().collect().await.unwrap().to_bytes();
+        (code, serde_json::from_slice(&body).unwrap_or(Value::Null))
+    }
+
+    async fn post(&self, path: &str, body: Value) -> (StatusCode, Value) {
+        self.send(
+            Request::post(path)
+                .header("content-type", "application/json")
+                .body(Body::from(body.to_string()))
+                .unwrap(),
+        )
+        .await
+    }
+
+    async fn get(&self, path: &str) -> (StatusCode, Value) {
+        self.send(Request::get(path).body(Body::empty()).unwrap())
+            .await
+    }
+}
+
+#[tokio::test]
+async fn votes_count_once_per_browser_and_can_be_taken_back() {
+    let hub = hub(config());
+    let vote = |up: bool, voter: &str| json!({ "item": "smooth-frames", "voter": voter, "up": up });
+    assert_eq!(
+        hub.post("/hub/vote", vote(true, VOTER)).await,
+        (
+            StatusCode::OK,
+            json!({ "item": "smooth-frames", "votes": 1 })
+        )
+    );
+    assert_eq!(
+        hub.post("/hub/vote", vote(true, VOTER)).await.1["votes"],
+        1,
+        "a second vote changes nothing"
+    );
+    let other = "f".repeat(32);
+    assert_eq!(
+        hub.post("/hub/vote", vote(true, &other)).await.1["votes"],
+        2
+    );
+    assert_eq!(
+        hub.get("/hub/votes").await,
+        (StatusCode::OK, json!({ "votes": { "smooth-frames": 2 } }))
+    );
+    assert_eq!(
+        hub.post("/hub/vote", vote(false, VOTER)).await.1["votes"],
+        1
+    );
+    assert_eq!(
+        hub.get("/hub/votes").await.1["votes"]["smooth-frames"],
+        1,
+        "a vote drops the cached counts"
+    );
+    for bad in [
+        json!({ "item": "Not An Id", "voter": VOTER }),
+        json!({ "item": "a", "voter": "short" }),
+        json!([]),
+    ] {
+        assert_eq!(hub.post("/hub/vote", bad).await.0, StatusCode::BAD_REQUEST);
+    }
+}
+
+#[tokio::test]
+async fn the_website_may_post_from_the_browser() {
+    let hub = hub(config());
+    let res = router(hub.app.clone())
+        .oneshot(
+            Request::options("/hub/vote")
+                .header("origin", "https://playhorizon.dev")
+                .header("access-control-request-method", "POST")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), StatusCode::NO_CONTENT);
+    let header = |name: &str| res.headers()[name].to_str().unwrap().to_owned();
+    assert_eq!(
+        header("access-control-allow-origin"),
+        "https://playhorizon.dev"
+    );
+    assert_eq!(header("access-control-allow-methods"), "POST");
+    assert_eq!(header("access-control-allow-headers"), "content-type");
+}

From a95be8a7f3de4b7bddf525ba71115ada203e68bb Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:57:34 +0100
Subject: [PATCH 100/270] Roadmap: `announce = true` marks items Kira also
 posts on X when they ship

Kira's X poster (kira #12) posts shipped items flagged announce in journal.json.
Set on the five whose release is news: modpack world generation, the mod
registry, Discord Rich Presence, Microsoft sign-in and CurseForge. Flags must be
booleans.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 roadmap/README.md     | 1 +
 roadmap/roadmap.toml  | 5 +++++
 tests/test_roadmap.py | 4 ++++
 tools/roadmap.py      | 6 +++++-
 4 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/roadmap/README.md b/roadmap/README.md
index df44575a5..656303464 100644
--- a/roadmap/README.md
+++ b/roadmap/README.md
@@ -20,6 +20,7 @@ dev = """26.3's dialog packets and model (#1720), ..."""             # crates, a
 links = ["#1720", "#1734", "docs/hosting.md"]                       # #N, a repository path, or https://
 shipped_in = "v0.2.58"           # shipped items only: a game tag, launcher@x.y.z, or "website"
 post = "..."                     # optional: the announcement when it ships, if `plain` doesn't read as one
+announce = true                  # optional: when it ships, Kira also posts it on X (`post`, else `plain`)
 ```
 
 - **No dates, ever**: Now, Next, Later. The check rejects month names, years, quarters and "next week".
diff --git a/roadmap/roadmap.toml b/roadmap/roadmap.toml
index bb664d3d5..5ad4d8846 100644
--- a/roadmap/roadmap.toml
+++ b/roadmap/roadmap.toml
@@ -91,6 +91,7 @@ id = "modpack-worldgen"
 title = "Modpacks' world generation, natively"
 status = "now"
 area = "modpacks"
+announce = true
 focus = true
 plain = """Making the world-generation mods of popular modpacks (new structures, YUNG's dungeons and mineshafts, \
 packs built on Lithostitched) generate their worlds in Horizon, natively and fast."""
@@ -135,6 +136,7 @@ id = "mod-registry"
 title = "Horizon's mod registry"
 status = "now"
 area = "mods"
+announce = true
 focus = true
 plain = """One place for mods, modpacks and resource packs made for Horizon: browse them on the website and \
 install them from the launcher in one click."""
@@ -185,6 +187,7 @@ id = "discord-presence"
 title = "Discord Rich Presence"
 status = "now"
 area = "extras"
+announce = true
 plain = """Your Discord profile can show that you are playing Horizon, with a switch to turn it off."""
 dev = """A Discord IPC client on its own thread (#1787) and the presence with its setting (#1788). Merged: it ships \
 with the next release."""
@@ -210,6 +213,7 @@ id = "microsoft-sign-in"
 title = "Microsoft sign-in (coming soon)"
 status = "next"
 area = "launcher"
+announce = true
 plain = """Coming soon: sign in with your Microsoft account to play on online-mode servers. The code is ready; it \
 waits for Microsoft's approval."""
 dev = """Device-code sign-in in the launcher and online-mode login in the client (docs/microsoft-account.md). It is \
@@ -222,6 +226,7 @@ id = "curseforge"
 title = "CurseForge in the mod browser (coming soon)"
 status = "next"
 area = "modpacks"
+announce = true
 plain = """Coming soon: search and download CurseForge mods and modpacks from the launcher, as you can with \
 Modrinth today."""
 dev = """The mod browser lists CurseForge as coming soon (docs/mod-browser.md): it needs CurseForge API access. \
diff --git a/tests/test_roadmap.py b/tests/test_roadmap.py
index fb4f4e419..3b8e15b45 100644
--- a/tests/test_roadmap.py
+++ b/tests/test_roadmap.py
@@ -114,6 +114,10 @@ class Rules(unittest.TestCase):
         self.assertTrue(any("link" in p for p in self.problems(links=["docs/nothing-here.md"])))
         self.assertTrue(any("link" in p for p in self.problems(links=["http://example.com"])))
 
+    def test_flags_are_true_or_false(self):
+        self.assertEqual(self.problems(announce=True), [])
+        self.assertTrue(any("announce is true or false" in p for p in self.problems(announce="yes")))
+
     def test_three_to_five_items_in_focus(self):
         self.assertTrue(any("focus" in p for p in self.problems(focus=False)))
 
diff --git a/tools/roadmap.py b/tools/roadmap.py
index b1bb13c6d..d80c9692c 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -45,7 +45,8 @@ STALE_DAYS = 14  # a Now item needs an open pull request, or one merged this rec
 LABEL_PREFIX = "roadmap:"
 # GitHub label colours by status, from the design system's palette.
 LABEL_COLOURS = {"now": "5b3fd6", "next": "9a86ff", "later": "c5c7d1", "help-wanted": "1d7a48", "shipped": "646875"}
-ITEM_KEYS = {"id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post"}
+ITEM_KEYS = {"id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post",
+             "announce"}
 
 ISSUE = re.compile(r"#(\d+)$")
 ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$")
@@ -127,6 +128,9 @@ def validate(data, root=ROOT):
                 problems.append(f"{where}: shipped_in {shipped_in!r} is not a release tag or \"website\"")
         elif shipped_in:
             problems.append(f"{where}: only shipped items have shipped_in")
+        for key in ("focus", "ongoing", "announce"):
+            if key in item and not isinstance(item[key], bool):
+                problems.append(f"{where}: {key} is true or false")
         if item.get("ongoing") and status not in ("now", "next", "later"):
             problems.append(f"{where}: only Now, Next and Later items are ongoing")
         if item.get("focus") and status != "now":

From e936e412ba04f67d907d4b5abdeb412a8f3e6462 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:29:37 +0100
Subject: [PATCH 101/270] Website: the hub (/hub) with the roadmap, a Simple /
 Technical switch and live states

playhorizon.dev/hub is the public entry point to what is happening on Horizon. Overview: where
Horizon is, the 3 to 5 things in focus, what is next, what shipped last, how to help. Roadmap: Now /
Next / Later / Help wanted / Shipped, filtered by area, every item with its issues and pull requests
in their GitHub state (baked at build, refreshed in the browser). Contribute: good first tasks,
claiming, connecting an agent to Kira, the rules. A Simple / Technical switch swaps every item's
plain and dev text and is remembered. /roadmap redirects to the Roadmap tab.

tools/roadmap.py build now also writes website/data/roadmap.json, which the site reads and serves at
/hub/roadmap.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_roadmap.py     |  13 +-
 tools/roadmap.py          |  46 +++-
 website/Caddyfile         |   5 +-
 website/README.md         |   4 +
 website/build.mjs         |  64 ++++-
 website/data/roadmap.json | 557 ++++++++++++++++++++++++++++++++++++++
 website/serve.mjs         |   5 +
 website/src/hub-page.js   | 119 ++++++++
 website/src/hub.html      | 110 ++++++++
 website/src/hub.js        | 175 ++++++++++++
 website/src/hub.test.mjs  |  48 ++++
 website/src/style.css     |  63 ++++-
 12 files changed, 1187 insertions(+), 22 deletions(-)
 create mode 100644 website/data/roadmap.json
 create mode 100644 website/src/hub-page.js
 create mode 100644 website/src/hub.html
 create mode 100644 website/src/hub.js
 create mode 100644 website/src/hub.test.mjs

diff --git a/tests/test_roadmap.py b/tests/test_roadmap.py
index 3b8e15b45..641d4e11b 100644
--- a/tests/test_roadmap.py
+++ b/tests/test_roadmap.py
@@ -1,5 +1,6 @@
 import copy
 import datetime
+import json
 import tomllib
 import unittest
 from unittest import mock
@@ -77,9 +78,15 @@ class RepositoryRoadmap(unittest.TestCase):
     def test_the_roadmap_keeps_its_rules(self):
         self.assertEqual(roadmap.validate(roadmap.load()), [])
 
-    def test_roadmap_md_is_generated_from_the_toml(self):
-        self.assertEqual(roadmap.OUTPUT.read_text(), roadmap.render(roadmap.load()),
-                         "ROADMAP.md is out of date: run `python3 tools/roadmap.py build`")
+    def test_generated_files_match_the_toml(self):
+        for path, text in roadmap.outputs(roadmap.load()).items():
+            self.assertEqual(path.read_text(), text, f"{path.name} is out of date: run `python3 tools/roadmap.py build`")
+
+    def test_site_data_has_every_item_in_one_line_text(self):
+        data = json.loads(roadmap.site_data(tomllib.loads(SAMPLE)))
+        self.assertEqual([item["id"] for item in data["items"]], ["fast", "faster", "fastest", "old"])
+        self.assertEqual(data["items"][0]["dev"], "Multiply, not divide (#10).")
+        self.assertEqual(data["areas"], [{"id": "performance", "name": "Performance"}])
 
 
 class Rules(unittest.TestCase):
diff --git a/tools/roadmap.py b/tools/roadmap.py
index d80c9692c..1a4f58136 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """Horizon's roadmap: roadmap/roadmap.toml is the source, ROADMAP.md is generated from it.
 
-    python3 tools/roadmap.py build              write ROADMAP.md
-    python3 tools/roadmap.py build --check      fail when ROADMAP.md is out of date (CI)
+    python3 tools/roadmap.py build              write ROADMAP.md and website/data/roadmap.json
+    python3 tools/roadmap.py build --check      fail when either is out of date (CI)
     python3 tools/roadmap.py check --offline    the file's own rules (CI)
     python3 tools/roadmap.py check              the same, then GitHub: links resolve, no stale Now item
     python3 tools/roadmap.py sync [--dry-run]   items whose pull requests all merged become shipped,
@@ -28,6 +28,8 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 SOURCE = ROOT / "roadmap" / "roadmap.toml"
 OUTPUT = ROOT / "ROADMAP.md"
+# What the website's hub reads (website/build.mjs), and serves at /hub/roadmap.json for Kira and others.
+SITE_DATA = ROOT / "website" / "data" / "roadmap.json"
 REPO = "ludovic111/horizon"
 SITE = "https://playhorizon.dev/hub"
 
@@ -227,6 +229,27 @@ def render(data):
     return "\n".join(out) + "\n"
 
 
+def site_data(data):
+    """website/data/roadmap.json: the items as the hub and Kira read them, in the file's order."""
+    keys = ("id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post")
+    out = {
+        "format": "horizon-roadmap",
+        "version": 1,
+        "source": "roadmap/roadmap.toml",
+        "overview": {key: " ".join(value.split()) for key, value in data["overview"].items()},
+        "statuses": [{"id": key, "name": name} for key, name in STATUSES.items()],
+        "areas": [{"id": key, "name": name} for key, name in areas_in_order(data)],
+        "items": [{key: (" ".join(item[key].split()) if isinstance(item[key], str) else item[key])
+                   for key in keys if key in item} for item in data.get("item", [])],
+    }
+    return json.dumps(out, indent=1, ensure_ascii=False) + "\n"
+
+
+def outputs(data):
+    """Every generated file and its content."""
+    return {OUTPUT: render(data), SITE_DATA: site_data(data)}
+
+
 # --- GitHub ---------------------------------------------------------------------------------------------------
 
 def token():
@@ -466,13 +489,15 @@ def command_build(args):
     problems = validate(data)
     if problems:
         return report(problems)
-    markdown = render(data)
+    files = outputs(data)
     if args.check:
-        if not OUTPUT.exists() or OUTPUT.read_text() != markdown:
-            return report(["ROADMAP.md is out of date: run `python3 tools/roadmap.py build`"])
-        return 0
-    OUTPUT.write_text(markdown)
-    print(f"roadmap: wrote {OUTPUT.relative_to(ROOT)}")
+        stale = [path for path, text in files.items() if not path.exists() or path.read_text() != text]
+        return report([f"{path.relative_to(ROOT)} is out of date: run `python3 tools/roadmap.py build`"
+                       for path in stale])
+    for path, text in files.items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+        print(f"roadmap: wrote {path.relative_to(ROOT)}")
     return 0
 
 
@@ -505,8 +530,9 @@ def command_sync(args):
     if len(new.get("item", [])) != len(data.get("item", [])) or validate(new):
         return report(["sync produced an invalid file; nothing written"] + validate(new))
     SOURCE.write_text(text)
-    OUTPUT.write_text(render(new))
-    print("roadmap: wrote roadmap/roadmap.toml and ROADMAP.md")
+    for path, content in outputs(new).items():
+        path.write_text(content)
+    print("roadmap: wrote roadmap/roadmap.toml, ROADMAP.md and website/data/roadmap.json")
     return 0
 
 
diff --git a/website/Caddyfile b/website/Caddyfile
index 1571566ad..50ba44381 100644
--- a/website/Caddyfile
+++ b/website/Caddyfile
@@ -33,9 +33,12 @@
 	rewrite /privacy /privacy.html
 	rewrite /releases /releases.html
 	rewrite /benchmarks /benchmarks.html
+	rewrite /hub /hub.html
+	# The roadmap is the hub's Roadmap tab.
+	redir /roadmap /hub#roadmap permanent
 	@doc path_regexp doc ^/docs/([a-z-]+)$
 	rewrite @doc /docs/{re.doc.1}.html
-	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /docs /docs/* /sitemap.xml
+	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /hub /hub.html /hub/* /docs /docs/* /sitemap.xml
 	header @pages Cache-Control "no-cache"
 	@legal path /LEGAL.md /fonts/*.txt
 	header @legal Content-Type "text/plain; charset=utf-8"
diff --git a/website/README.md b/website/README.md
index 9d1f8dc8d..c73683c73 100644
--- a/website/README.md
+++ b/website/README.md
@@ -25,6 +25,7 @@ src/404.html       the not-found page
 src/privacy.html   what the launcher can send when players allow it, retention, deletion (/privacy)
 src/releases.html  every release, newest first, with what it adds and fixes, its notes and downloads (/releases)
 src/benchmarks.html Horizon against vanilla 26.3 on our machines, the hardware picker, players' results (/benchmarks)
+src/hub.html       the hub (/hub, /roadmap redirects to its Roadmap tab): Overview, Roadmap, Contribute, a Simple / Technical switch
 src/docs.html      the template of every documentation page (/docs/...), with its left navigation
 src/tokens.css     the design tokens, generated from crates/horizon-theme (do not edit)
 src/style.css      every style, on top of the tokens
@@ -39,6 +40,9 @@ src/estimate.js    estimates for unmeasured hardware from the nearest measured m
 src/markdown.js    a small Markdown renderer (escapes everything), shared by build and page
 src/releases.js    the home page's "Recently added" and the Releases page's markup, shared by build and page
 src/contributors.js the contributors' filtering and markup, shared by build and page
+src/hub.js         the hub's markup from data/roadmap.json and GitHub's issue states, shared by build and page
+src/hub-page.js    the hub page: tabs by #hash, the Simple / Technical switch (localStorage), the area filter, live states
+data/roadmap.json  the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /hub/roadmap.json
 public/            fonts, screenshots, icons, og.png, robots.txt, benchmarks.json: copied as is (sitemap.xml is written by the build)
 data/benchmarks/   our raw benchmark reports (tools/perf_bench.py) and fleet.json, the list scripts/benchmarks.mjs reads
 scripts/benchmarks.mjs  benchmark reports -> public/benchmarks.json (ours, and players' groups of 3+ installs)
diff --git a/website/build.mjs b/website/build.mjs
index 8b0954054..b36e0e103 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -16,6 +16,7 @@ import { machinesHtml, playersHtml } from "./src/bench.js";
 import { CPUS, GPUS, singleThread } from "./src/hardware.js";
 import { isGame, isLauncher, launcherVersion, newestFirst } from "./src/versions.js";
 import { contributorsFrom, contributorsHtml } from "./src/contributors.js";
+import { areaFilterHtml, helpWantedHtml, overviewHtml, roadmapHtml, slimIssue } from "./src/hub.js";
 
 const site = dirname(fileURLToPath(import.meta.url));
 const dist = join(site, "dist");
@@ -77,6 +78,45 @@ try {
   console.warn(`contributors: ${e.message}; the page will load them itself`);
 }
 
+// The hub's roadmap (data/roadmap.json, generated from roadmap/roadmap.toml by tools/roadmap.py) and the live state
+// of the issues and pull requests its items link: the open ones and those closed lately, then (with a token) the
+// older ones in one GraphQL request. Without GitHub the hub shows the links without their state.
+const roadmap = JSON.parse(await readFile(join(site, "data", "roadmap.json"), "utf8"));
+const linked = new Set(roadmap.items.flatMap((i) => (i.links || []).map((l) => Number((l.match(/^#(\d+)$/) || [])[1])).filter(Boolean)));
+let hubLive = [];
+try {
+  const urls = [1, 2, 3].map((p) => `https://api.github.com/repos/${REPO}/issues?state=open&per_page=100&page=${p}`);
+  urls.push(`https://api.github.com/repos/${REPO}/issues?state=closed&sort=updated&direction=desc&per_page=100`);
+  for (const url of urls) {
+    const res = await fetch(url, { headers: githubHeaders, signal: AbortSignal.timeout(15000) });
+    if (!res.ok) throw new Error(`${res.status} from GitHub`);
+    hubLive.push(...(await res.json()).map(slimIssue));
+  }
+  const missing = [...linked].filter((n) => !hubLive.some((i) => i.n === n));
+  if (missing.length && process.env.GITHUB_TOKEN) {
+    const fields = missing.map((n) => `n${n}: issueOrPullRequest(number: ${n}) { ... on Issue { number title state stateReason url } ... on PullRequest { number title state isDraft mergedAt url } }`).join(" ");
+    const res = await fetch("https://api.github.com/graphql", {
+      method: "POST",
+      headers: githubHeaders,
+      body: JSON.stringify({ query: `query { repository(owner: "ludovic111", name: "horizon") { ${fields} } }` }),
+      signal: AbortSignal.timeout(15000),
+    });
+    const nodes = Object.values((await res.json()).data?.repository || {}).filter(Boolean);
+    hubLive.push(
+      ...nodes.map((x) =>
+        slimIssue({
+          number: x.number, title: x.title, html_url: x.url, draft: x.isDraft,
+          state: x.state === "OPEN" ? "open" : "closed", state_reason: x.stateReason === "NOT_PLANNED" ? "not_planned" : null,
+          pull_request: "isDraft" in x ? { merged_at: x.mergedAt } : undefined,
+        }),
+      ),
+    );
+  }
+} catch (e) {
+  console.warn(`hub: ${e.message}; the page will load the states itself`);
+}
+const hubLinked = new Map(hubLive.filter((i) => linked.has(i.n)).map((i) => [i.n, i]));
+
 // --- The parity table ------------------------------------------------------------------
 
 const status = section(readme, "Project status") ?? "";
@@ -170,7 +210,7 @@ await writeFile(join(dist, "favicon.ico"), Buffer.concat([ico, png32]));
 const names = {};
 const rewrite = (code) => code.replace(/"\.\/(\w+\.js)"/g, (all, file) => (names[file] ? `"./${names[file]}"` : all));
 // Dependencies before what imports them.
-const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "main.js", "releases-page.js", "benchmarks-page.js", "docs-page.js"];
+const modules = ["markdown.js", "versions.js", "chrome.js", "hardware.js", "estimate.js", "releases.js", "contributors.js", "bench.js", "hub.js", "main.js", "releases-page.js", "benchmarks-page.js", "docs-page.js", "hub-page.js"];
 for (const file of modules) {
   const code = rewrite(await readFile(join(site, "src", file), "utf8"));
   names[file] = `${file.replace(".js", "")}.${fingerprint(code)}.js`;
@@ -203,7 +243,7 @@ const unavailable = `<p class="lede">The release notes could not be loaded here.
 
 // One top bar and phone menu for Home, Releases, Benchmarks and every Docs page.
 const navSections = [["/#about", "About"], ["/#screenshots", "In game"], ["/#parity", "Parity"], ["/#launcher", "Launcher"], ["/#recent", "New", "Recently added"], ["/#community", "Community"]];
-const navPages = [["/releases", "Releases"], ["/benchmarks", "Benchmarks"], ["/docs/", "Docs", "Documentation"]];
+const navPages = [["/hub", "Hub"], ["/releases", "Releases"], ["/benchmarks", "Benchmarks"], ["/docs/", "Docs", "Documentation"]];
 const navLink = ([href, label, menuLabel], current, menu = false) =>
   `<a href="${href}"${href === current ? ' aria-current="page"' : ""}${href === "/#contributors" ? ` data-contributors${contributors.length ? "" : " hidden"}` : ""}>${menu && menuLabel ? menuLabel : label}</a>`;
 const siteNav = (current) => `    <header class="nav" id="top">
@@ -233,7 +273,7 @@ const siteFooter = `    <footer class="footer">
       <div class="container">
         <div class="footer-bar">
           <span class="footer-mark">Made in the open, in Rust.</span>
-          <nav class="footer-links" aria-label="Elsewhere"><a href="/">Home</a><a href="/releases">Releases</a><a href="/benchmarks">Benchmarks</a><a href="/docs/">Docs</a><a href="/docs/how-horizon-is-built">How it's built</a><a href="https://github.com/${REPO}">GitHub</a><a href="/privacy">Privacy</a><a href="/LEGAL.md">Assets</a></nav>
+          <nav class="footer-links" aria-label="Elsewhere"><a href="/">Home</a><a href="/hub">Hub</a><a href="/releases">Releases</a><a href="/benchmarks">Benchmarks</a><a href="/docs/">Docs</a><a href="/docs/how-horizon-is-built">How it's built</a><a href="https://github.com/${REPO}">GitHub</a><a href="/privacy">Privacy</a><a href="/LEGAL.md">Assets</a></nav>
         </div>
       </div>
       <p class="footer-word" aria-hidden="true">horizon</p>
@@ -282,6 +322,12 @@ const values = {
   CONTRIBUTORS: contributorsHtml(contributors),
   CONTRIBUTORS_HIDDEN: contributors.length ? "" : " hidden",
   BAKED: JSON.stringify(baked).replace(/</g, "\\u003c"),
+  HUB_JS: `/assets/${names["hub-page.js"]}`,
+  HUB_OVERVIEW: overviewHtml(roadmap, hubLinked),
+  HUB_ROADMAP: roadmapHtml(roadmap, hubLinked),
+  HUB_AREAS: areaFilterHtml(roadmap),
+  HUB_HELP_WANTED: helpWantedHtml(roadmap),
+  HUB_DATA: JSON.stringify({ roadmap, live: [...hubLinked.values()] }).replace(/</g, "\\u003c"),
   YEAR: String(new Date().getUTCFullYear()),
 };
 
@@ -358,8 +404,8 @@ const docPages = renderedDocs.map((d, i) => {
   };
 });
 
-const pages = ["index.html", "404.html", "privacy.html", "releases.html", "benchmarks.html"];
-const currentPath = { "releases.html": "/releases", "benchmarks.html": "/benchmarks" };
+const pages = ["index.html", "404.html", "privacy.html", "releases.html", "benchmarks.html", "hub.html"];
+const currentPath = { "releases.html": "/releases", "benchmarks.html": "/benchmarks", "hub.html": "/hub" };
 for (const page of pages) {
   let html = await readFile(join(site, "src", page), "utf8");
   const own = { ...values, SITE_NAV: siteNav(currentPath[page]) };
@@ -382,6 +428,10 @@ for (const { file, values: own } of docPages) {
   docPageFiles.push(file);
 }
 
+// The roadmap for other readers (Kira, scripts): /hub/roadmap.json, as tools/roadmap.py wrote it.
+await mkdir(join(dist, "hub"), { recursive: true });
+await cp(join(site, "data", "roadmap.json"), join(dist, "hub", "roadmap.json"));
+
 // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS
 // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash.
 const allHtml = (await Promise.all([...pages, ...docPageFiles].map((page) => readFile(join(dist, page), "utf8")))).join("\n");
@@ -389,7 +439,7 @@ const hashes = (re) => [...new Set([...allHtml.matchAll(re)].map((m) => `'sha256
 await writeFile(join(dist, ".csp-script"), hashes(/<script>([\s\S]*?)<\/script>/g));
 await writeFile(join(dist, ".csp-style"), hashes(/<style>([\s\S]*?)<\/style>/g));
 
-const urls = ["/", "/releases", "/benchmarks", ...docs.map((d) => d.path), "/privacy"];
+const urls = ["/", "/hub", "/releases", "/benchmarks", ...docs.map((d) => d.path), "/privacy"];
 await writeFile(
   join(dist, "sitemap.xml"),
   `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.map((u) => `  <url><loc>https://playhorizon.dev${u}</loc></url>`).join("\n")}\n</urlset>\n`,
@@ -397,5 +447,5 @@ await writeFile(
 
 console.log(
   `built dist/ from ${readmeFrom}: ${body.length} subsystems, ${percent}, ${harnesses} harnesses, ` +
-    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages`,
+    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages, ${roadmap.items.length} roadmap items (${hubLinked.size}/${linked.size} links live)`,
 );
diff --git a/website/data/roadmap.json b/website/data/roadmap.json
new file mode 100644
index 000000000..142b27011
--- /dev/null
+++ b/website/data/roadmap.json
@@ -0,0 +1,557 @@
+{
+ "format": "horizon-roadmap",
+ "version": 1,
+ "source": "roadmap/roadmap.toml",
+ "overview": {
+  "today_plain": "Horizon is Minecraft: Java Edition 26.3 rewritten from scratch in Rust, so it runs faster on the same computer. Single player, LAN, servers, resource packs and Horizon's own mods work today, on your own copy of the game.",
+  "today_dev": "A native Rust and wgpu reimplementation of Java 26.3: the same saves, rules and terrain, checked against the real game by more than 300 differential harnesses (a Java oracle and a Rust probe on the same inputs). Single player runs on its own server thread, like vanilla's integrated server.",
+  "help_plain": "Play it and tell us what differs from vanilla (Discord or GitHub), run the benchmark on your computer, vote for what you want next, or pick one of the Help wanted items.",
+  "help_dev": "Read CONTRIBUTING.md, pick a Help wanted item or a To do card, check vanilla's code for the behaviour, and paste the block `python3 tools/pr_ready.py` prints in your pull request."
+ },
+ "statuses": [
+  {
+   "id": "now",
+   "name": "Now"
+  },
+  {
+   "id": "next",
+   "name": "Next"
+  },
+  {
+   "id": "later",
+   "name": "Later"
+  },
+  {
+   "id": "help-wanted",
+   "name": "Help wanted"
+  },
+  {
+   "id": "shipped",
+   "name": "Recently shipped"
+  }
+ ],
+ "areas": [
+  {
+   "id": "performance",
+   "name": "Performance"
+  },
+  {
+   "id": "modpacks",
+   "name": "Modpacks"
+  },
+  {
+   "id": "servers",
+   "name": "Servers and multiplayer"
+  },
+  {
+   "id": "mods",
+   "name": "Mods and API"
+  },
+  {
+   "id": "gameplay",
+   "name": "Gameplay parity"
+  },
+  {
+   "id": "rendering",
+   "name": "Rendering"
+  },
+  {
+   "id": "launcher",
+   "name": "Launcher"
+  },
+  {
+   "id": "extras",
+   "name": "Horizon extras"
+  },
+  {
+   "id": "project",
+   "name": "Code and tools"
+  }
+ ],
+ "items": [
+  {
+   "id": "smooth-frames",
+   "title": "Steady frames at long render distances",
+   "status": "now",
+   "area": "performance",
+   "plain": "Making Horizon faster than vanilla on every computer, with smooth camera movement even at 32 chunks, by spreading the work better over the processor's cores.",
+   "dev": "Frame pacing at render distance 32 (#678): long frames come from work competing with the render thread. In review: world generation workers build free structure starts instead of queueing them (#1760), the worker pool leaves one core as vanilla does (#1778), and the terrain vertex arena is read as storage where flat draws run (#1742). Still open: far terrain at 48 to 64 chunks (#718) and CPU-bound fields of block entities (#717). Every change shows before and after numbers from `tools/perf_bench.py` against vanilla 26.3 (docs/benchmark.md).",
+   "links": [
+    "#678",
+    "#1760",
+    "#1778",
+    "#1742",
+    "#718",
+    "#717",
+    "docs/benchmark.md"
+   ],
+   "focus": true
+  },
+  {
+   "id": "block-storage",
+   "title": "Faster block lookups",
+   "status": "now",
+   "area": "performance",
+   "plain": "Speeding up the code that reads and writes the blocks of the world, which almost everything in the game goes through: generation, lighting, meshing and ticking.",
+   "dev": "`PalettedContainer` and `PackedStorage` find an entry's word by multiply and shift instead of an integer division (#1790, #1794); meshing looks up baked models by index, not by name (#1747). Each change keeps the paletted storage harnesses identical and shows its microbenchmark (docs/performance/paletted-container-access-results.md).",
+   "links": [
+    "#1790",
+    "#1794",
+    "#1747",
+    "docs/performance/paletted-container-access-results.md"
+   ]
+  },
+  {
+   "id": "modpack-worldgen",
+   "title": "Modpacks' world generation, natively",
+   "status": "now",
+   "area": "modpacks",
+   "plain": "Making the world-generation mods of popular modpacks (new structures, YUNG's dungeons and mineshafts, packs built on Lithostitched) generate their worlds in Horizon, natively and fast.",
+   "dev": "`horizon-port-pack` carries a pack's data-driven content over; structure mods that need code get a native port: YUNG's worldgen as written (#1746), Lithostitched's limited and guaranteed elements with pool and processor modifiers (#1777), its processors as the game's own types (#1765). Proved by the structure blocks and layout harnesses (#1753, #1757). Mods whose Java code does more than world generation don't run (docs/modpacks.md).",
+   "links": [
+    "#1746",
+    "#1777",
+    "#1765",
+    "#1753",
+    "#1757",
+    "docs/modpacks.md"
+   ],
+   "focus": true
+  },
+  {
+   "id": "server-clients",
+   "title": "Playing on servers: everything shows as it should",
+   "status": "now",
+   "area": "servers",
+   "plain": "When you play on a server, other players, mobs, items and menus look and behave as in vanilla: skins, poses, item names, inventories and server networks.",
+   "dev": "Client-of-a-server fixes in `game/remote*.rs` and `horizon-protocol`: mobs' aggressive and item-use flags (#1802, #1798), ghost items after a remote menu (#1795), skins (#1652), cookies and transfer packets for proxy networks (#1650), firework boosts (#1671), living-entity attributes and simulation distance (#1731), styled item names (#1702), primed TNT between updates (#1710).",
+   "links": [
+    "#1802",
+    "#1798",
+    "#1795",
+    "#1652",
+    "#1650",
+    "#1671",
+    "#1731",
+    "#1702",
+    "#1710"
+   ],
+   "focus": true,
+   "ongoing": true
+  },
+  {
+   "id": "server-thread",
+   "title": "Single player as a server: the last differences",
+   "status": "now",
+   "area": "gameplay",
+   "plain": "Single player now runs a small server in the background, as vanilla does. We are fixing what still behaves differently there; every fix also works for LAN and server players.",
+   "dev": "Since #1514 single player runs on the server thread (`game/integrated.rs`) and the window joins it as a client; `--in-frame` keeps the old path. The open `[server-thread]` issues list the gaps. In review: a tool that changes a block ends the click (#1797), potions keep their potion over the connection (#1796), mobs' aggression and arm swings (#1802). docs/server-levels.md.",
+   "links": [
+    "#1514",
+    "#1797",
+    "#1796",
+    "#1802",
+    "docs/server-levels.md"
+   ],
+   "focus": true,
+   "ongoing": true
+  },
+  {
+   "id": "mod-registry",
+   "title": "Horizon's mod registry",
+   "status": "now",
+   "area": "mods",
+   "plain": "One place for mods, modpacks and resource packs made for Horizon: browse them on the website and install them from the launcher in one click.",
+   "dev": "Merged: the registry index (schema 1, `.hpack`, checks before install, #1634), `cargo horizon-mod check` (#1642) and the submission service (`crates/horizon-mod-registry`, #1659). In review: the website's /mods (#1596) and /mods/submit (#1635), and in the launcher the registry as a source (#1636), install, enable and takedowns (#1637), the Mods page (#1638) and modpacks as their own profiles (#1640).",
+   "links": [
+    "#1634",
+    "#1642",
+    "#1659",
+    "#1596",
+    "#1635",
+    "#1636",
+    "#1637",
+    "#1638",
+    "#1640",
+    "docs/mods.md"
+   ],
+   "focus": true
+  },
+  {
+   "id": "server-dialogs",
+   "title": "Server dialogs and login screens",
+   "status": "now",
+   "area": "servers",
+   "plain": "Servers that show dialogs, such as the register and login screens of AuthMe, will work in Horizon.",
+   "dev": "26.3's dialog packets and model (#1720), the dialog screen with its buttons and actions (#1734), then text and boolean inputs (#1735).",
+   "links": [
+    "#1720",
+    "#1734",
+    "#1735"
+   ]
+  },
+  {
+   "id": "languages",
+   "title": "Play in your language",
+   "status": "now",
+   "area": "gameplay",
+   "plain": "Item names, container titles and server messages follow the language you pick, as in vanilla. Today parts of the game stay in English.",
+   "dev": "Translatable components resolved through the selected language for items, containers and server text (#1806), on top of the bundled languages the prepared resources carry (#1594). Left: the client's own screens (#1672) and the main menu with zh_cn (#1774).",
+   "links": [
+    "#1806",
+    "#1594",
+    "#1672",
+    "#1774"
+   ]
+  },
+  {
+   "id": "shader-packs",
+   "title": "Shader packs, written again from scratch",
+   "status": "now",
+   "area": "rendering",
+   "plain": "Shader packs were removed and are being rebuilt from scratch. They come back, off by default, once the best-known packs draw properly.",
+   "dev": "A clean-room rewrite in `horizon-shaderpack`, from the packs' public format documentation only: reading packs, the preprocessor and `.properties` files are merged (#1584, #1585, #1586); translating programs to WGSL through naga, buffers, uniforms and the terrain, entity, sky, weather and hand stages are in review (#1698 to #1801).",
+   "links": [
+    "#1561",
+    "#1584",
+    "#1586",
+    "#1698",
+    "#1771",
+    "#1786",
+    "#1801"
+   ],
+   "ongoing": true
+  },
+  {
+   "id": "discord-presence",
+   "title": "Discord Rich Presence",
+   "status": "now",
+   "area": "extras",
+   "plain": "Your Discord profile can show that you are playing Horizon, with a switch to turn it off.",
+   "dev": "A Discord IPC client on its own thread (#1787) and the presence with its setting (#1788). Merged: it ships with the next release.",
+   "links": [
+    "#1787",
+    "#1788"
+   ]
+  },
+  {
+   "id": "lean-code",
+   "title": "A leaner codebase that builds faster",
+   "status": "now",
+   "area": "project",
+   "plain": "Cleaning up Horizon's code: removing what nothing uses and making it quicker to build, so fixes and new features land faster.",
+   "dev": "A review of the whole tree: dead code and stubs removed (#1432, #1658), one probe binary per crate (#1453, #1454), shared harness helpers (#1448), clippy clean on the whole tree (#1707). docs/architecture.md maps each feature to its files and harnesses.",
+   "links": [
+    "#1432",
+    "#1658",
+    "#1453",
+    "#1454",
+    "#1448",
+    "#1707",
+    "docs/architecture.md"
+   ],
+   "ongoing": true
+  },
+  {
+   "id": "microsoft-sign-in",
+   "title": "Microsoft sign-in (coming soon)",
+   "status": "next",
+   "area": "launcher",
+   "plain": "Coming soon: sign in with your Microsoft account to play on online-mode servers. The code is ready; it waits for Microsoft's approval.",
+   "dev": "Device-code sign-in in the launcher and online-mode login in the client (docs/microsoft-account.md). It is turned on by setting the app's client id once Minecraft API access is approved; until then the launcher shows \"Coming soon\".",
+   "links": [
+    "docs/microsoft-account.md",
+    "#1270"
+   ]
+  },
+  {
+   "id": "curseforge",
+   "title": "CurseForge in the mod browser (coming soon)",
+   "status": "next",
+   "area": "modpacks",
+   "plain": "Coming soon: search and download CurseForge mods and modpacks from the launcher, as you can with Modrinth today.",
+   "dev": "The mod browser lists CurseForge as coming soon (docs/mod-browser.md): it needs CurseForge API access. Meanwhile packs import from a CurseForge zip or instance folder, and jars only CurseForge hosts come from the player's own instance (docs/modpacks.md).",
+   "links": [
+    "docs/mod-browser.md",
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "benchmarks",
+   "title": "Fresh benchmarks against vanilla",
+   "status": "next",
+   "area": "performance",
+   "plain": "New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, on the website's Benchmarks page.",
+   "dev": "Redo the comparison after the current performance work (#1073); reliability, coverage and presentation (#1346); a scene must count as loaded only once its first chunk arrives (#1749). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` (docs/benchmark.md).",
+   "links": [
+    "#1073",
+    "#1346",
+    "#1749",
+    "docs/benchmark.md"
+   ]
+  },
+  {
+   "id": "pistons-push",
+   "title": "Pistons push players and mobs",
+   "status": "next",
+   "area": "gameplay",
+   "plain": "Pistons and slime blocks will push players, mobs and items as in vanilla. Today moving blocks pass through them.",
+   "dev": "Port `PistonMovingBlockEntity.moveCollidedEntities` and `moveStuckEntities` (honey), the slime bounce and `Entity.limitPistonMovement` for `MoverType.PISTON`, in single player and for a server's players. Issues #1496, #1609, #1608, #1704, #1758.",
+   "links": [
+    "#1496",
+    "#1609",
+    "#1608",
+    "#1704",
+    "#1758"
+   ]
+  },
+  {
+   "id": "intel-mac",
+   "title": "Horizon on Intel Macs",
+   "status": "next",
+   "area": "launcher",
+   "plain": "Builds of the game and the launcher for Macs with an Intel processor.",
+   "dev": "x86_64 game and launcher builds, picked per processor (#1171). Before it ships it needs a run on a real Intel Mac: Rosetta on Apple Silicon only proves the CPU code. Requests: #1161, #1792.",
+   "links": [
+    "#1171",
+    "#1161",
+    "#1792"
+   ]
+  },
+  {
+   "id": "ai-companion",
+   "title": "An optional AI teammate",
+   "status": "later",
+   "area": "extras",
+   "plain": "An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the No AI switch hides it completely.",
+   "dev": "Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069), and a route that finishes the game (#1070). Local models first; it ships only once the safety evaluation passes.",
+   "links": [
+    "#1068",
+    "#1069",
+    "#1070"
+   ]
+  },
+  {
+   "id": "new-versions",
+   "title": "Following new Minecraft versions",
+   "status": "later",
+   "area": "gameplay",
+   "plain": "When Mojang releases a new version of the game, Horizon follows it, and every system is checked against the new version again.",
+   "dev": "The port pipeline detects a release, diffs its classes against 26.3 and writes a port report (docs/version-ports.md); the harnesses then run against the new version.",
+   "links": [
+    "docs/version-ports.md"
+   ]
+  },
+  {
+   "id": "benchmark-your-pc",
+   "title": "Benchmark your computer",
+   "status": "help-wanted",
+   "area": "performance",
+   "plain": "Run Horizon's built-in benchmark and share the report: every new computer makes the performance work more accurate. No coding needed.",
+   "dev": "`horizon-launcher play --arg=--benchmark --arg=standard` writes a JSON report; `horizon-launcher data benchmark <report>` shows what would be sent and uploads it (website/docs/performance.md). Results from three installs with the same hardware appear on the Benchmarks page. Example: #1711.",
+   "links": [
+    "website/docs/performance.md",
+    "#1711"
+   ]
+  },
+  {
+   "id": "end-city-banners",
+   "title": "End city banners keep their pattern",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "Banners in End cities show as plain magenta instead of with their pattern.",
+   "dev": "Compare the banner block entities the End city templates place with vanilla's (`EndCityPieces`, the templates' block entity NBT, `BannerBlockEntity`'s patterns), in `crates/horizon-world/src/worldgen/structure/`. Issue #1438; possibly related: #526.",
+   "links": [
+    "#1438",
+    "#526"
+   ]
+  },
+  {
+   "id": "end-city-loot",
+   "title": "Enchanted loot in End cities",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "Armour and tools in End city chests should come enchanted, as in vanilla.",
+   "dev": "`loot.rs` implements `enchant_with_levels`: find why the End city chest table's rolls come out bare, and compare them with vanilla's for a few seeds. Issues #1437, #1660.",
+   "links": [
+    "#1437",
+    "#1660"
+   ]
+  },
+  {
+   "id": "item-cooldowns",
+   "title": "Cooldowns drawn on items",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "After you throw an ender pearl, its slot should show the cooldown sweeping away, as in vanilla.",
+   "dev": "Vanilla draws `ItemCooldowns`' percent as a white overlay over the slot (`GuiGraphicsExtractor.itemDecorations` and `itemCooldown`) in the hotbar and in inventories. Issue #1763.",
+   "links": [
+    "#1763"
+   ]
+  },
+  {
+   "id": "chat-settings",
+   "title": "Chat settings and team prefixes",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "The Hidden and Commands Only chat settings should hide chat, and team prefixes should appear before names in chat.",
+   "dev": "Vanilla checks `ChatVisiblity` before it delivers chat and system messages (#1376), and chat uses the team-formatted display name (#1378). Both issues have exact steps to reproduce.",
+   "links": [
+    "#1376",
+    "#1378"
+   ]
+  },
+  {
+   "id": "pointer-hand",
+   "title": "A pointing hand over buttons",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "The mouse pointer should turn into a pointing hand over menu buttons, as in vanilla 26.3.",
+   "dev": "26.3's `AbstractWidget` asks for a cursor from `CursorTypes` when it is hovered; winit's `CursorIcon::Pointer` gives the same shape. Issue #1347.",
+   "links": [
+    "#1347"
+   ]
+  },
+  {
+   "id": "text-field-keys",
+   "title": "Ctrl+Backspace and scroll bars in menus",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "Ctrl+Backspace should delete a whole word in the creative search, and every list's scroll bar should be draggable.",
+   "dev": "`EditBox` deletes by word with Ctrl (#1764); the Game Rules and Statistics lists' scroll bars can't be dragged (#1782, after #978).",
+   "links": [
+    "#1764",
+    "#1782"
+   ]
+  },
+  {
+   "id": "chicken-flap",
+   "title": "Chickens flap while they fall",
+   "status": "help-wanted",
+   "area": "gameplay",
+   "plain": "Chickens should flap their wings while they fall, not stand still in the air.",
+   "dev": "Vanilla's `Chicken.aiStep` updates `flap` and `flapSpeed` when the chicken isn't on the ground, and the model's wings follow them. Issue #1706.",
+   "links": [
+    "#1706"
+   ]
+  },
+  {
+   "id": "server-resource-packs",
+   "title": "Server resource packs",
+   "status": "shipped",
+   "area": "servers",
+   "plain": "Servers can send you their resource pack: Horizon asks, downloads it and applies it, like vanilla.",
+   "dev": "The dedicated server offers server.properties' pack (#1562); the client's pack manager, downloads, prompt and Server Resource Packs setting (#1569, #1570).",
+   "links": [
+    "#1562",
+    "#1569",
+    "#1570"
+   ],
+   "shipped_in": "v0.2.48"
+  },
+  {
+   "id": "server-thread-default",
+   "title": "Single player on its own server thread",
+   "status": "shipped",
+   "area": "gameplay",
+   "plain": "Single player runs on a server thread, as vanilla does, so the world keeps ticking smoothly while the window draws.",
+   "dev": "`game/integrated.rs` runs a second `Game` with one level per dimension; the window joins it through memory like a LAN guest (#1514).",
+   "links": [
+    "#1514",
+    "docs/server-levels.md"
+   ],
+   "shipped_in": "v0.2.39"
+  },
+  {
+   "id": "metal-occlusion",
+   "title": "GPU occlusion culling on Macs",
+   "status": "shipped",
+   "area": "performance",
+   "plain": "On Macs the GPU now skips terrain hidden behind hills and caves: 8 to 48% more frames per second at 32 chunks on an M4 Pro.",
+   "dev": "GPU occlusion culling on Metal (#1434).",
+   "links": [
+    "#1434"
+   ],
+   "shipped_in": "v0.2.17"
+  },
+  {
+   "id": "gpu-animated-textures",
+   "title": "Animated textures on the GPU",
+   "status": "shipped",
+   "area": "performance",
+   "plain": "Water, lava and other animated blocks are now animated by the graphics card: 1.7 to 2.4 times better 1% lows on Intel graphics.",
+   "dev": "Frames uploaded once, no per-tick CPU blend or copy (#1239).",
+   "links": [
+    "#1239"
+   ],
+   "shipped_in": "v0.2.5"
+  },
+  {
+   "id": "far-detail",
+   "title": "Far Detail for integrated graphics",
+   "status": "shipped",
+   "area": "performance",
+   "plain": "An optional Reduced setting for far terrain, suggested on integrated graphics, that saves 2 to 4 ms of GPU time per frame.",
+   "dev": "Opt-in reduced far terrain (#1199), on far-terrain chunk summaries built on the workers (#1029).",
+   "links": [
+    "#1199",
+    "#1029"
+   ],
+   "shipped_in": "v0.2.5"
+  },
+  {
+   "id": "mod-browser",
+   "title": "The launcher's mod browser",
+   "status": "shipped",
+   "area": "modpacks",
+   "plain": "Search Modrinth for mods, modpacks and resource packs from the launcher; it says before installing what works in Horizon.",
+   "dev": "The Mods page (#1154), Java mods checked before install (#1242), project pages, filters and galleries (#1243), modpacks ported in the same step (#1246). docs/mod-browser.md.",
+   "links": [
+    "#1154",
+    "#1242",
+    "#1243",
+    "#1246",
+    "docs/mod-browser.md"
+   ],
+   "shipped_in": "launcher@0.2.0"
+  },
+  {
+   "id": "launcher-look",
+   "title": "A blocky, Minecraft-like launcher",
+   "status": "shipped",
+   "area": "launcher",
+   "plain": "The launcher got a new blocky look in Horizon's purple, in dark and light.",
+   "dev": "The Blocks look (#1269), from `horizon-theme` (docs/design-system.md).",
+   "links": [
+    "#1269",
+    "docs/design-system.md"
+   ],
+   "shipped_in": "launcher@0.2.0"
+  },
+  {
+   "id": "dynamic-lights",
+   "title": "Dynamic lights",
+   "status": "shipped",
+   "area": "extras",
+   "plain": "An optional extra: torches you hold, drop or set on fire light up what is around them.",
+   "dev": "Held, dropped and burning light sources (#1162), in Horizon Extras, off by default.",
+   "links": [
+    "#1162"
+   ],
+   "shipped_in": "v2026.10.22"
+  },
+  {
+   "id": "servers-page",
+   "title": "Host a server from the launcher",
+   "status": "shipped",
+   "area": "servers",
+   "plain": "The launcher's Servers page creates, starts, backs up and updates a Horizon server with buttons, and invites friends.",
+   "dev": "The launcher's Servers page (#1026) over `horizon-server` (docs/hosting.md).",
+   "links": [
+    "#1026",
+    "docs/hosting.md"
+   ],
+   "shipped_in": "launcher-v0.15.0"
+  }
+ ]
+}
diff --git a/website/serve.mjs b/website/serve.mjs
index 761eef48a..0f862714e 100644
--- a/website/serve.mjs
+++ b/website/serve.mjs
@@ -17,6 +17,11 @@ createServer(async (req, res) => {
     res.writeHead(301, { Location: "/docs/hosting" });
     return res.end();
   }
+  // The roadmap page became the hub's Roadmap tab.
+  if (path === "/roadmap") {
+    res.writeHead(301, { Location: "/hub#roadmap" });
+    return res.end();
+  }
   if (path === "/docs") path = "/docs/index.html";
   // /privacy and /docs/<page> are .html files, as the Caddyfile rewrites them.
   if (!extname(path)) path += ".html";
diff --git a/website/src/hub-page.js b/website/src/hub-page.js
new file mode 100644
index 000000000..039e98826
--- /dev/null
+++ b/website/src/hub-page.js
@@ -0,0 +1,119 @@
+// The hub page (/hub): its tabs (one per #hash, so /hub#roadmap and /hub#item-<id> can be linked), the
+// Simple / Technical switch (remembered in localStorage), the area filter, and the live state of every
+// linked issue and pull request, refreshed from GitHub's public API. Without JavaScript, every tab reads
+// one after the other with what was baked at build time.
+import { cached, get, setUpMenu, setUpTheme } from "./chrome.js";
+import { REPO, overviewHtml, roadmapHtml, slimIssue } from "./hub.js";
+
+const root = document.documentElement;
+const data = JSON.parse(document.getElementById("hub-data").textContent);
+const tabs = [...document.querySelectorAll('.hub-tabs [role="tab"]')];
+const pill = document.querySelector(".hub-tabs .tab-pill");
+let area = "all";
+
+// --- Tabs ------------------------------------------------------------------------------------------------------
+
+const panelOf = (tab) => document.getElementById(tab.getAttribute("aria-controls"));
+const place = (tab) => {
+  pill.style.width = `${tab.offsetWidth}px`;
+  pill.style.height = `${tab.offsetHeight}px`;
+  pill.style.transform = `translate(${tab.offsetLeft}px, ${tab.offsetTop}px)`;
+};
+function choose(tab, { focus = false, push = false } = {}) {
+  for (const t of tabs) {
+    const on = t === tab;
+    t.setAttribute("aria-selected", String(on));
+    t.tabIndex = on ? 0 : -1;
+    panelOf(t).classList.toggle("is-active", on);
+  }
+  place(tab);
+  if (focus) tab.focus();
+  if (push && location.hash !== `#${panelOf(tab).id}`) history.replaceState(null, "", `#${panelOf(tab).id}`);
+}
+// "#roadmap" opens its tab; "#item-x" or "#help-wanted" opens the tab holding it and scrolls there.
+function follow() {
+  const target = location.hash && document.getElementById(decodeURIComponent(location.hash.slice(1)));
+  const tab = tabs.find((t) => target && (panelOf(t) === target || panelOf(t).contains(target))) || tabs[0];
+  choose(tab);
+  if (target && target !== panelOf(tab)) {
+    if (target.dataset.area && area !== "all" && target.dataset.area !== area) filter("all");
+    requestAnimationFrame(() => target.scrollIntoView({ block: "start" }));
+  }
+}
+tabs.forEach((tab, i) => {
+  tab.addEventListener("click", () => choose(tab, { push: true }));
+  tab.addEventListener("keydown", (e) => {
+    const step = { ArrowRight: 1, ArrowLeft: -1 }[e.key];
+    if (step) choose(tabs[(i + step + tabs.length) % tabs.length], { focus: true, push: true });
+  });
+});
+// Links inside the page ("Help wanted", an item of the overview) switch tabs through the hash.
+addEventListener("hashchange", follow);
+addEventListener("resize", () => place(tabs.find((t) => t.getAttribute("aria-selected") === "true")));
+document.fonts?.ready.then(() => place(tabs.find((t) => t.getAttribute("aria-selected") === "true")));
+
+// --- Simple / Technical ----------------------------------------------------------------------------------------
+
+const detailButtons = [...document.querySelectorAll("[data-detail]")];
+function detail(mode) {
+  if (mode === "dev") root.dataset.detail = "dev";
+  else delete root.dataset.detail;
+  detailButtons.forEach((b) => b.setAttribute("aria-pressed", String(b.dataset.detail === mode)));
+}
+detailButtons.forEach((b) =>
+  b.addEventListener("click", () => {
+    detail(b.dataset.detail);
+    try {
+      localStorage.setItem("hub:detail", b.dataset.detail);
+    } catch {}
+  }),
+);
+detail(root.dataset.detail === "dev" ? "dev" : "plain");
+
+// --- Area filter -----------------------------------------------------------------------------------------------
+
+const areaButtons = [...document.querySelectorAll("[data-area-filter]")];
+function filter(to) {
+  area = to;
+  areaButtons.forEach((b) => b.setAttribute("aria-pressed", String(b.dataset.areaFilter === area)));
+  for (const section of document.querySelectorAll("[data-roadmap] .hub-section")) {
+    let shown = 0;
+    for (const item of section.querySelectorAll(".hub-item")) {
+      item.hidden = area !== "all" && item.dataset.area !== area;
+      if (!item.hidden) shown++;
+    }
+    section.hidden = shown === 0;
+  }
+}
+areaButtons.forEach((b) => b.addEventListener("click", () => filter(b.dataset.areaFilter)));
+
+// --- Live state from GitHub ------------------------------------------------------------------------------------
+
+// The open issues and pull requests, and those closed or merged lately: four requests at most, kept ten minutes.
+async function loadLive() {
+  const list = [];
+  for (let page = 1; page <= 3; page++) {
+    const batch = await get(`https://api.github.com/repos/${REPO}/issues?state=open&per_page=100&page=${page}`);
+    list.push(...batch.map(slimIssue));
+    if (batch.length < 100) break;
+  }
+  const closed = await get(`https://api.github.com/repos/${REPO}/issues?state=closed&sort=updated&direction=desc&per_page=100`);
+  return list.concat(closed.map(slimIssue));
+}
+
+async function refresh() {
+  const fresh = await cached("horizon:hub-live", loadLive).catch(() => null);
+  if (!fresh) return;
+  // What the build knew about older links stays; GitHub's answer wins for the rest.
+  const live = new Map([...data.live, ...fresh].map((i) => [i.n, i]));
+  document.querySelector("[data-overview]").innerHTML = overviewHtml(data.roadmap, live);
+  document.querySelector("[data-roadmap]").innerHTML = roadmapHtml(data.roadmap, live);
+  filter(area);
+  const note = document.querySelector("[data-live-note]");
+  if (note) note.textContent = "Pull request and issue states are live from GitHub.";
+}
+
+setUpTheme();
+setUpMenu();
+follow();
+refresh().then(() => location.hash.startsWith("#item-") && follow());
diff --git a/website/src/hub.html b/website/src/hub.html
new file mode 100644
index 000000000..5aff05639
--- /dev/null
+++ b/website/src/hub.html
@@ -0,0 +1,110 @@
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+    <title>Hub · Horizon</title>
+    <meta name="description" content="Where Horizon is: what is being done now, what comes next, what shipped, and how to help, in plain words or in technical detail.">
+    <meta name="theme-color" content="#ece7f7" media="(prefers-color-scheme: light)">
+    <meta name="theme-color" content="#0f0d17" media="(prefers-color-scheme: dark)">
+    <meta name="color-scheme" content="light dark">
+    <link rel="canonical" href="https://playhorizon.dev/hub">
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="icon" href="/favicon-32.png" sizes="32x32" type="image/png">
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="Horizon">
+    <meta property="og:title" content="Hub · Horizon">
+    <meta property="og:description" content="What is being done on Horizon now, what comes next, what shipped, and how to help.">
+    <meta property="og:url" content="https://playhorizon.dev/hub">
+    <meta property="og:image" content="https://playhorizon.dev/og.png">
+    <link rel="preconnect" href="https://api.github.com" crossorigin>
+    <style>{{STYLE}}</style>
+    <script>document.documentElement.classList.replace("no-js", "js"); try { const t = localStorage.getItem("theme"); if (t === "light" || t === "dark") document.documentElement.dataset.theme = t; if (localStorage.getItem("hub:detail") === "dev") document.documentElement.dataset.detail = "dev" } catch {}</script>
+    <script type="module" src="{{HUB_JS}}"></script>
+  </head>
+  <body class="subpage">
+    <a class="skip" href="#main">Skip to the content</a>
+{{SITE_NAV}}
+    <main id="main" class="section page-main hub">
+      <div class="container">
+        <p class="kicker"><span>Hub</span>Now, next and how to help</p>
+        <h1 class="display page-title">Where Horizon is going</h1>
+        <p class="lede">What is being done, what comes next, what shipped and where you can help. No dates: things are Now, Next or Later. Read it in plain words, or switch to the technical picture.</p>
+        <div class="hub-bar">
+          <div class="tabs hub-tabs" role="tablist" aria-label="Hub">
+            <span class="tab-pill" aria-hidden="true"></span>
+            <button type="button" role="tab" id="tab-overview" aria-controls="overview" aria-selected="true">Overview</button>
+            <button type="button" role="tab" id="tab-roadmap" aria-controls="roadmap" aria-selected="false" tabindex="-1">Roadmap</button>
+            <button type="button" role="tab" id="tab-contribute" aria-controls="contribute" aria-selected="false" tabindex="-1">Contribute</button>
+          </div>
+          <div class="hub-detail" role="group" aria-label="Detail">
+            <button type="button" class="button secondary small" data-detail="plain" aria-pressed="true">Simple</button>
+            <button type="button" class="button secondary small" data-detail="dev" aria-pressed="false">Technical</button>
+          </div>
+        </div>
+
+        <div class="hub-panel is-active" role="tabpanel" id="overview" aria-labelledby="tab-overview" data-overview>
+{{HUB_OVERVIEW}}
+        </div>
+
+        <div class="hub-panel" role="tabpanel" id="roadmap" aria-labelledby="tab-roadmap">
+          <div class="release-filter hub-areas" role="group" aria-label="Area">
+{{HUB_AREAS}}
+          </div>
+          <div data-roadmap>
+{{HUB_ROADMAP}}
+          </div>
+          <p class="meta hub-source">The roadmap lives in the repository: <a href="https://github.com/ludovic111/horizon/blob/main/ROADMAP.md">ROADMAP.md</a>, generated from <a href="https://github.com/ludovic111/horizon/blob/main/roadmap/roadmap.toml">roadmap/roadmap.toml</a>. Pull requests carry the <code>roadmap:&lt;id&gt;</code> label of their item. <span data-live-note></span></p>
+        </div>
+
+        <div class="hub-panel" role="tabpanel" id="contribute" aria-labelledby="tab-contribute">
+          <section class="hub-block" aria-labelledby="h-first">
+            <h2 class="title" id="h-first">Good first tasks</h2>
+            <p class="hub-plain hub-intro">Each one is a small difference from vanilla, with an issue that says how to see it.</p>
+            <p class="hub-dev hub-intro">Each links its issue; the technical text says where in the code and in vanilla to start.</p>
+            <ol class="index hub-rows">{{HUB_HELP_WANTED}}</ol>
+          </section>
+          <section class="hub-block" aria-labelledby="h-ways">
+            <h2 class="title" id="h-ways">Ways to help</h2>
+            <div class="hub-cards">
+              <article class="highlight">
+                <h3>Tell us what differs</h3>
+                <p>Something that doesn't play like vanilla is a bug. Say what you did, what happened and what vanilla does, with your Horizon version and system.</p>
+                <p class="hub-actions"><a class="button secondary small" href="{{DISCORD}}">Discord</a><a class="button secondary small" href="https://github.com/ludovic111/horizon/issues/new">GitHub issue</a></p>
+              </article>
+              <article class="highlight">
+                <h3>Take a task</h3>
+                <p>Pick a good first task or an open issue. On Discord, <code>/claim 1234</code> tells everyone you are on issue 1234, so nobody starts the same work; <code>/unclaim</code> frees it.</p>
+                <p class="hub-actions"><a class="button secondary small" href="https://github.com/ludovic111/horizon/issues">Open issues</a></p>
+              </article>
+              <article class="highlight">
+                <h3>Bring your AI agent</h3>
+                <p>On Discord, <code>/agent connect</code> gives your coding agent a personal token for Kira's MCP server: it reads the work board, claims tasks and posts its progress in your name.</p>
+                <p class="hub-actions"><a class="button secondary small" href="{{DISCORD}}">Join the Discord</a></p>
+              </article>
+              <article class="highlight">
+                <h3>Benchmark your computer</h3>
+                <p>Run the built-in benchmark and share the report: every new machine makes the performance work more accurate. No coding needed.</p>
+                <p class="hub-actions"><a class="button secondary small" href="/docs/performance">How to</a></p>
+              </article>
+            </div>
+          </section>
+          <section class="hub-block" aria-labelledby="h-rules">
+            <h2 class="title" id="h-rules">The rules</h2>
+            <ol class="hub-rules">
+              <li><strong>Vanilla is the specification.</strong> Wherever Minecraft 26.3 has the feature, Horizon does exactly what it does: read vanilla's code, then match it.</li>
+              <li><strong>Small pull requests, proven.</strong> One change each, under about 500 lines, with the block <code>python3 tools/pr_ready.py</code> prints: formatting, Clippy, tests and the harnesses your change can affect.</li>
+              <li><strong>Say who wrote it.</strong> If an AI agent wrote or posts it, the pull request says so, and commits keep its co-author line.</li>
+              <li><strong>Never commit Mojang's files.</strong> No game jars, assets, decompiled code or prepared resources, and nothing taken from other mods' code.</li>
+            </ol>
+            <p class="hub-actions"><a class="button primary" href="/docs/contributing">The contributing guide</a><a class="button secondary" href="https://github.com/ludovic111/horizon/blob/main/CONTRIBUTING.md">CONTRIBUTING.md</a></p>
+          </section>
+        </div>
+        <p class="disclaimer">Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.</p>
+      </div>
+    </main>
+{{SITE_FOOTER}}
+    <script type="application/json" id="hub-data">{{HUB_DATA}}</script>
+  </body>
+</html>
diff --git a/website/src/hub.js b/website/src/hub.js
new file mode 100644
index 000000000..37e26738c
--- /dev/null
+++ b/website/src/hub.js
@@ -0,0 +1,175 @@
+// The hub (/hub): the roadmap from website/data/roadmap.json (generated from roadmap/roadmap.toml by
+// tools/roadmap.py), with each item's issues and pull requests in their live GitHub state. Shared by build.mjs
+// (baked into the page) and hub-page.js (refreshed from GitHub in the browser). Every item says the same thing
+// twice: `plain` (.hub-plain) for players and `dev` (.hub-dev) for contributors; the page's Simple / Technical
+// switch shows one of them.
+import { escape, inline } from "./markdown.js";
+
+export const REPO = "ludovic111/horizon";
+const issueUrl = (n) => `https://github.com/${REPO}/issues/${n}`;
+const fileUrl = (path) => `https://github.com/${REPO}/blob/main/${path}`;
+
+// The issues a pull request closes when merged: "Fixes #12", "closes #3, resolves #4" (as Kira's board reads them).
+export function fixesIn(text) {
+  const out = new Set();
+  for (const m of String(text ?? "").matchAll(/\b(?:fix(?:e[sd])?|close[sd]?|resolve[sd]?)\s*:?\s+((?:#\d+(?:\s*(?:,|and)\s*)?)+)/gi)) {
+    for (const n of m[1].matchAll(/#(\d+)/g)) out.add(Number(n[1]));
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+// A GitHub issue or pull request (from /issues, which lists both) reduced to what the hub shows.
+export function slimIssue(raw) {
+  const pr = Boolean(raw.pull_request);
+  const merged = pr && raw.pull_request.merged_at;
+  return {
+    n: raw.number,
+    title: String(raw.title || ""),
+    kind: pr ? "pr" : "issue",
+    state: merged ? "merged" : raw.state === "open" ? "open" : raw.state_reason === "not_planned" ? "dropped" : "closed",
+    draft: Boolean(raw.draft),
+    user: raw.user?.login || "",
+    labels: (raw.labels || []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean),
+    assigned: (raw.assignees || []).length > 0,
+    fixes: pr ? fixesIn(raw.body) : [],
+    at: merged || raw.closed_at || raw.updated_at || "",
+    url: raw.html_url || issueUrl(raw.number),
+  };
+}
+
+const number = (link) => Number((String(link).match(/^#(\d+)$/) || [])[1]) || null;
+
+// "#12 in review", "#13 merged": a link's state, when GitHub told us.
+function linkState(issue) {
+  if (!issue) return null;
+  if (issue.kind === "pr") return issue.state === "open" ? (issue.draft ? "in progress" : "in review") : issue.state;
+  return issue.state === "open" ? "open" : "closed";
+}
+
+function linkHtml(link, live) {
+  const n = number(link);
+  if (!n) {
+    const url = link.startsWith("https://") ? link : fileUrl(link);
+    return `<a class="hub-link" href="${escape(url)}">${escape(link.replace(/^https:\/\//, ""))}</a>`;
+  }
+  const issue = live.get(n);
+  const state = linkState(issue);
+  const label = issue ? `${issue.kind === "pr" ? "Pull request" : "Issue"} #${n}: ${issue.title}` : `#${n}`;
+  return `<a class="hub-link${state ? ` is-${state.replace(" ", "-")}` : ""}" href="${issueUrl(n)}" title="${escape(label)}">#${n}${state ? ` <span>${state}</span>` : ""}</a>`;
+}
+
+// The technical text with its #N and the item's own paths as links.
+function devHtml(item) {
+  let text = item.dev.replace(/(^|[^\w[/`])#(\d+)\b/g, (_, before, n) => `${before}[#${n}](${issueUrl(n)})`);
+  for (const link of item.links || []) {
+    if (!number(link) && !link.startsWith("https://")) text = text.replace(link, `[${link}](${fileUrl(link)})`);
+  }
+  return inline(text);
+}
+
+// "2 pull requests in review · 3 merged · 1 issue open", from the item's links.
+export function progress(item, live) {
+  const known = (item.links || []).map(number).filter(Boolean).map((n) => live.get(n)).filter(Boolean);
+  const pulls = known.filter((i) => i.kind === "pr");
+  const count = (list, word) => (list.length ? `${list.length} ${word}` : "");
+  const parts = [
+    count(pulls.filter((p) => p.state === "open" && !p.draft), pulls.filter((p) => p.state === "open" && !p.draft).length === 1 ? "pull request in review" : "pull requests in review"),
+    count(pulls.filter((p) => p.state === "open" && p.draft), "in progress"),
+    count(pulls.filter((p) => p.state === "merged"), "merged"),
+    count(known.filter((i) => i.kind === "issue" && i.state === "open"), known.filter((i) => i.kind === "issue" && i.state === "open").length === 1 ? "issue open" : "issues open"),
+  ].filter(Boolean);
+  return parts.join(" · ");
+}
+
+const areaName = (roadmap, id) => roadmap.areas.find((a) => a.id === id)?.name || id;
+
+export function itemHtml(item, roadmap, live) {
+  const done = item.status === "shipped";
+  const state = done ? "" : progress(item, live);
+  return `<article class="hub-item" id="item-${escape(item.id)}" data-area="${escape(item.area)}" data-item="${escape(item.id)}">
+  <p class="hub-item-meta"><span class="badge">${escape(areaName(roadmap, item.area))}</span>${done ? `<span class="badge badge-game">${escape(item.shipped_in)}</span>` : ""}${item.ongoing ? `<span class="hub-ongoing">Ongoing</span>` : ""}</p>
+  <h3 class="hub-item-title">${escape(item.title)}</h3>
+  <p class="hub-plain">${inline(item.plain)}</p>
+  <p class="hub-dev">${devHtml(item)}</p>
+  ${state ? `<p class="hub-progress" data-progress>${escape(state)}</p>` : ""}
+  <p class="hub-links">${(item.links || []).map((l) => linkHtml(l, live)).join("")}</p>
+</article>`;
+}
+
+const SECTION_LEDE = {
+  now: "Being worked on, with pull requests open or just merged.",
+  next: "Decided, and up after what is being done now.",
+  later: "Decided, further out.",
+  "help-wanted": "Good first contributions: a clear vanilla behaviour, an issue with the steps, a place to start.",
+  shipped: "Out in a release. The journal has every change.",
+};
+
+// The Roadmap tab: one section per status, the items in the file's order (areas by priority).
+export function roadmapHtml(roadmap, live = new Map()) {
+  const order = new Map(roadmap.areas.map((a, i) => [a.id, i]));
+  return roadmap.statuses
+    .map(({ id, name }) => {
+      const items = roadmap.items.filter((i) => i.status === id);
+      if (!items.length) return "";
+      // Shipped stays newest first; the others go by the areas' priority.
+      if (id !== "shipped") items.sort((a, b) => order.get(a.area) - order.get(b.area));
+      return `<section class="hub-section" id="${id}" data-status="${id}" aria-labelledby="h-${id}">
+  <div class="hub-section-head"><h2 class="title" id="h-${id}">${escape(name)}</h2><p class="meta">${escape(SECTION_LEDE[id] || "")}</p></div>
+  <div class="hub-items">
+${items.map((item) => itemHtml(item, roadmap, live)).join("\n")}
+  </div>
+</section>`;
+    })
+    .join("\n");
+}
+
+// The area filter's buttons: every area that has an item.
+export function areaFilterHtml(roadmap) {
+  const used = roadmap.areas.filter((a) => roadmap.items.some((i) => i.area === a.id));
+  return [`<button type="button" class="button secondary small" data-area-filter="all" aria-pressed="true">All</button>`]
+    .concat(used.map((a) => `<button type="button" class="button secondary small" data-area-filter="${escape(a.id)}" aria-pressed="false">${escape(a.name)}</button>`))
+    .join("\n");
+}
+
+// The Overview tab: where Horizon is, the 3 to 5 things in focus, what is next, what shipped last, how to help.
+export function overviewHtml(roadmap, live = new Map()) {
+  const o = roadmap.overview;
+  const focus = roadmap.items.filter((i) => i.focus);
+  const next = roadmap.items.filter((i) => i.status === "next");
+  const shipped = roadmap.items.filter((i) => i.status === "shipped").slice(0, 3);
+  const row = (item, i, meta) => `<li class="row"><a href="#item-${escape(item.id)}" data-goto="roadmap"><span class="row-index">${String(i + 1).padStart(2, "0")}</span><span class="hub-row-body"><span class="hub-row-title">${escape(item.title)}</span><span class="hub-plain">${inline(item.plain)}</span><span class="hub-dev">${inline(item.dev)}</span></span><span class="row-meta">${escape(meta(item))}</span></a></li>`;
+  return `<div class="hub-today">
+  <p class="hub-plain hub-lead">${inline(o.today_plain)}</p>
+  <p class="hub-dev hub-lead">${inline(o.today_dev)}</p>
+</div>
+<section class="hub-block" aria-labelledby="h-focus">
+  <h2 class="title" id="h-focus">Being done now</h2>
+  <ol class="index hub-rows">${focus.map((item, i) => row(item, i, (x) => progress(x, live))).join("")}</ol>
+</section>
+<section class="hub-block" aria-labelledby="h-next">
+  <h2 class="title" id="h-next">Next</h2>
+  <ol class="index hub-rows">${next.map((item, i) => row(item, i, (x) => areaName(roadmap, x.area))).join("")}</ol>
+</section>
+<section class="hub-block" aria-labelledby="h-shipped">
+  <h2 class="title" id="h-shipped">Recently shipped</h2>
+  <ol class="index hub-rows">${shipped.map((item, i) => row(item, i, (x) => `In ${x.shipped_in}`)).join("")}</ol>
+</section>
+<section class="hub-block hub-help" aria-labelledby="h-help">
+  <h2 class="title" id="h-help">How to help</h2>
+  <p class="hub-plain">${inline(o.help_plain)}</p>
+  <p class="hub-dev">${inline(o.help_dev)}</p>
+  <p class="hub-actions"><a class="button primary" href="#contribute" data-goto="contribute">Contribute</a><a class="button secondary" href="#help-wanted" data-goto="roadmap">Help wanted</a></p>
+</section>`;
+}
+
+// The Contribute tab's list of good first tasks.
+export function helpWantedHtml(roadmap) {
+  return roadmap.items
+    .filter((i) => i.status === "help-wanted")
+    .map((item, i) => {
+      const first = (item.links || []).map(number).find(Boolean);
+      const href = first ? issueUrl(first) : `#item-${item.id}`;
+      return `<li class="row"><a href="${escape(href)}"><span class="row-index">${String(i + 1).padStart(2, "0")}</span><span class="hub-row-body"><span class="hub-row-title">${escape(item.title)}</span><span class="hub-plain">${inline(item.plain)}</span><span class="hub-dev">${inline(item.dev)}</span></span><span class="row-meta">${first ? `#${first}` : ""}</span></a></li>`;
+    })
+    .join("");
+}
diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs
new file mode 100644
index 000000000..e73c9a8af
--- /dev/null
+++ b/website/src/hub.test.mjs
@@ -0,0 +1,48 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fixesIn, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
+
+const roadmap = JSON.parse(readFileSync(new URL("../data/roadmap.json", import.meta.url), "utf8"));
+
+const pr = (number, extra = {}) => ({ number, title: `PR ${number}`, state: "open", pull_request: { merged_at: null }, user: { login: "a" }, labels: [], assignees: [], body: "", ...extra });
+const issue = (number, extra = {}) => ({ number, title: `Issue ${number}`, state: "open", user: { login: "b" }, labels: [{ name: "bug" }], assignees: [], ...extra });
+
+test("pull requests and issues reduce to their hub state", () => {
+  assert.deepEqual(fixesIn("Fixes #12, #13 and closes #4. Mentions #9."), [4, 12, 13]);
+  const merged = slimIssue(pr(5, { state: "closed", pull_request: { merged_at: "2030-01-01T00:00:00Z" }, body: "Fixes #3" }));
+  assert.equal(merged.kind, "pr");
+  assert.equal(merged.state, "merged");
+  assert.deepEqual(merged.fixes, [3]);
+  assert.equal(slimIssue(issue(6, { state: "closed", state_reason: "not_planned" })).state, "dropped");
+  assert.deepEqual(slimIssue(issue(7)).labels, ["bug"]);
+});
+
+test("an item's progress counts its pull requests and issues", () => {
+  const live = new Map([
+    [1, slimIssue(pr(1))],
+    [2, slimIssue(pr(2, { draft: true }))],
+    [3, slimIssue(pr(3, { state: "closed", pull_request: { merged_at: "2030-01-01T00:00:00Z" } }))],
+    [4, slimIssue(issue(4))],
+  ]);
+  const item = { links: ["#1", "#2", "#3", "#4", "#99", "docs/x.md"] };
+  assert.equal(progress(item, live), "1 pull request in review · 1 in progress · 1 merged · 1 issue open");
+  assert.equal(progress(item, new Map()), "");
+});
+
+test("the roadmap renders every item once, with both texts, in its status's section", () => {
+  const html = roadmapHtml(roadmap);
+  for (const item of roadmap.items) {
+    assert.equal(html.split(`id="item-${item.id}"`).length, 2, item.id);
+  }
+  assert.ok(html.indexOf('id="now"') < html.indexOf('id="next"'));
+  assert.ok(html.includes('class="hub-plain"') && html.includes('class="hub-dev"'));
+  // Shipped items say which release had them.
+  assert.ok(html.includes(`>${roadmap.items.find((i) => i.status === "shipped").shipped_in}<`));
+});
+
+test("the overview lists the focus items and never nests links", () => {
+  const html = overviewHtml(roadmap);
+  for (const item of roadmap.items.filter((i) => i.focus)) assert.ok(html.includes(`href="#item-${item.id}"`), item.id);
+  for (const row of html.match(/<li class="row">[\s\S]*?<\/li>/g)) assert.equal(row.split("<a ").length, 2, row);
+});
diff --git a/website/src/style.css b/website/src/style.css
index 6cf764237..4ec688812 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -645,7 +645,7 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 
 /* Releases: a filter, then every release as a panel that opens. */
 .release-filter { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 32px; }
-.release-filter .button[aria-pressed="true"] { background: var(--face); color: var(--on-face); box-shadow: inset 0 var(--block-bevel) 0 var(--face-bevel), inset 0 calc(-1 * var(--block-lip)) 0 var(--face-lip); }
+.release-filter .button[aria-pressed="true"], .hub-detail .button[aria-pressed="true"] { background: var(--face); color: var(--on-face); box-shadow: inset 0 var(--block-bevel) 0 var(--face-bevel), inset 0 calc(-1 * var(--block-lip)) 0 var(--face-lip); }
 .release-count { margin: 16px 0 12px; }
 .release-list { display: grid; gap: 8px; }
 .release-list .release + .release { margin-top: 0; }
@@ -726,3 +726,64 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
   .release-detail { padding-left: 0; margin-left: 0; }
   .machine { padding: 16px; }
 }
+
+/* --- The hub (/hub): tabs, the Simple / Technical switch, roadmap items as panels ------------------- */
+
+.hub-bar { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 16px; margin-top: 32px; }
+.hub-tabs { margin-bottom: 0; }
+.hub-detail { display: flex; gap: 8px; }
+/* A link to a tab (/hub#roadmap) lands with the tabs in view under the top bar. */
+.hub-panel { margin-top: 40px; scroll-margin-top: calc(var(--nav) + 120px); }
+.js .hub-panel:not(.is-active) { display: none; }
+/* Simple shows `plain`, Technical shows `dev`; without the switch (no JavaScript) Simple reads. */
+.hub .hub-dev { display: none; }
+:root[data-detail="dev"] .hub .hub-dev { display: block; }
+:root[data-detail="dev"] .hub .hub-plain { display: none; }
+.hub-lead { max-width: 60ch; font-size: var(--text-heading); line-height: var(--text-heading-line); color: var(--ink); }
+.hub-block { margin-top: 56px; }
+.hub-block > .title { margin-bottom: 16px; }
+.hub-intro { margin-bottom: 16px; color: var(--ink-soft); max-width: var(--measure); }
+.hub-rows .row > a { grid-template-columns: var(--index) minmax(0, 1fr) auto; align-items: baseline; }
+.hub-row-body { display: grid; gap: 4px; min-width: 0; }
+.hub-row-title { font-size: clamp(18px, 1.8vw, 22px); font-weight: 500; color: var(--ink); }
+.hub-row-body .hub-plain, .hub-row-body .hub-dev { color: var(--ink-soft); font-size: var(--text-ui); max-width: 80ch; }
+.hub-rows .row-meta { max-width: 16rem; }
+.hub-section { margin-top: 48px; }
+.hub-section-head { display: flex; flex-wrap: wrap; align-items: baseline; gap: 8px 20px; }
+.hub-items { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 340px), 1fr)); gap: 8px; margin-top: 16px; }
+.hub-item {
+  display: flex; flex-direction: column; gap: 10px; padding: 18px 20px; scroll-margin-top: calc(var(--nav) + 24px);
+  background: var(--panel); border: var(--block-outline) solid var(--outline); box-shadow: var(--panel-edges);
+}
+.hub-item:target { box-shadow: var(--panel-edges), 0 0 0 3px var(--accent); }
+.hub-item-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+.hub-item-meta .badge { margin-right: 0; }
+.hub-ongoing { font: var(--text-micro) / 1 var(--mono); letter-spacing: var(--text-micro-tracking); color: var(--muted); }
+.hub-item-title { font-size: var(--text-heading); line-height: var(--text-heading-line); }
+.hub-item .hub-plain, .hub-item .hub-dev { font-size: var(--text-ui); color: var(--ink-soft); }
+.hub-progress { font: var(--text-micro) / 1.4 var(--mono); letter-spacing: var(--text-micro-tracking); color: var(--ink); }
+.hub-links { display: flex; flex-wrap: wrap; gap: 6px; margin-top: auto; padding-top: 4px; }
+.hub-link {
+  display: inline-flex; gap: 6px; align-items: baseline; padding: 3px 7px; font: var(--text-micro) / 1.3 var(--mono);
+  color: var(--ink-soft); background: var(--well); box-shadow: 0 0 0 var(--block-outline) var(--outline);
+}
+.hub-link span { color: var(--muted); }
+.hub-link:hover { color: var(--accent); }
+.hub-link.is-merged { background: color-mix(in srgb, var(--success) 18%, var(--well)); }
+.hub-link.is-in-review { background: color-mix(in srgb, var(--accent) 18%, var(--well)); }
+.hub-link.is-in-progress { background: color-mix(in srgb, var(--warn) 22%, var(--well)); }
+.hub-link.is-merged span, .hub-link.is-in-review span, .hub-link.is-in-progress span { color: var(--ink); }
+.hub-cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 260px), 1fr)); gap: 8px; }
+.hub-cards .highlight { justify-content: flex-start; }
+.hub-cards h3 { font-size: var(--text-heading); line-height: var(--text-heading-line); }
+.hub-cards p { color: var(--ink-soft); font-size: var(--text-ui); }
+.hub-actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 16px; }
+.hub-cards .hub-actions { margin-top: auto; }
+.hub-rules { list-style: decimal; padding-left: 20px; max-width: var(--measure); }
+.hub-rules li + li { margin-top: 10px; }
+.hub-rules li::marker { color: var(--muted); font-family: var(--mono); }
+.hub-source { margin-top: 40px; max-width: var(--measure); }
+@media (max-width: 720px) {
+  .hub-rows .row > a { grid-template-columns: var(--index) minmax(0, 1fr); }
+  .hub-rows .row-meta { grid-column: 2; text-align: left; }
+}

From 8ffd595575358067bf29cf02a7166bffef56af9b Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 14:58:42 +0000
Subject: [PATCH 102/270] fix: suppress secondary explosions from destroyed End
 crystals

Pass the crystal damage cause through destruction so explosion damage removes crystals without another blast, including during dragon respawn. Keep fight callbacks and direct-hit blasts.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 crates/horizon-client/src/game/dragon.rs | 40 +++++++++++++------
 tools/lan_e2e.py                         | 50 ++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 12 deletions(-)

diff --git a/crates/horizon-client/src/game/dragon.rs b/crates/horizon-client/src/game/dragon.rs
index 54b260c67..701c09e64 100644
--- a/crates/horizon-client/src/game/dragon.rs
+++ b/crates/horizon-client/src/game/dragon.rs
@@ -336,6 +336,12 @@ enum StrafeRequest {
     /// Anything else: the player nearest the crystal.
     Nearest(Vec3),
 }
+/// Whether `EndCrystal.hurtServer` creates a blast before notifying the fight.
+#[derive(Clone, Copy, PartialEq)]
+enum CrystalDamage {
+    Direct,
+    Explosion,
+}
 /// What `EnderDragon.hurt` made of a hit.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(super) enum Hurt {
@@ -867,8 +873,9 @@ impl Game<'_> {
             }
         }
     }
-    /// A crystal took damage: `EndCrystal.hurtServer` blows it up (power 6).
-    fn destroy_crystal(&mut self, index: usize, by: Option<FightWho>) {
+    /// `EndCrystal.hurtServer`: remove it, blast only for non-explosion damage,
+    /// then notify the dragon fight even when no blast was created.
+    fn destroy_crystal(&mut self, index: usize, by: Option<FightWho>, damage: CrystalDamage) {
         if index >= self.crystals.len() || self.crystals[index].invulnerable {
             return;
         }
@@ -880,14 +887,23 @@ impl Game<'_> {
                 .iter()
                 .any(|p| p.distance_squared(c.position) < 0.01)
         {
-            let at = [c.position.x, c.position.y, c.position.z];
-            let _ =
-                self.server_explode(at, 6.0, super::explosion::BlockInteraction::Destroy, false);
+            if damage == CrystalDamage::Direct {
+                let at = [c.position.x, c.position.y, c.position.z];
+                let _ = self.server_explode(
+                    at,
+                    6.0,
+                    super::explosion::BlockInteraction::Destroy,
+                    false,
+                );
+            }
             self.abort_respawn();
             return;
         }
-        let at = [c.position.x, c.position.y, c.position.z];
-        let _ = self.server_explode(at, 6.0, super::explosion::BlockInteraction::Destroy, false);
+        if damage == CrystalDamage::Direct {
+            let at = [c.position.x, c.position.y, c.position.z];
+            let _ =
+                self.server_explode(at, 6.0, super::explosion::BlockInteraction::Destroy, false);
+        }
         // EnderDragonFight.onCrystalDestroyed.
         self.count_crystals();
         if let Some(d) = self.dragon.as_mut() {
@@ -962,7 +978,7 @@ impl Game<'_> {
                 return Hurt::Refused;
             }
             let by = by_player.then(|| self.acting_player());
-            self.destroy_crystal(index, by);
+            self.destroy_crystal(index, by, CrystalDamage::Direct);
             Hurt::Landed { full: true }
         } else if id >= SPECIAL {
             self.hurt_dragon((id - SPECIAL) as usize, amount, by_player, arrow)
@@ -2634,8 +2650,8 @@ impl Crystal {
     }
 }
 impl Game<'_> {
-    /// `ServerExplosion.hurtEntities` on the end crystals (each in reach
-    /// blows up in turn) and the dragon (explosions always hurt dragons).
+    /// `ServerExplosion.hurtEntities`: crystals in reach are removed without
+    /// another blast; explosions always hurt dragons.
     pub(super) fn explosion_hits_special(&mut self, center: [f64; 3], radius: f32) {
         let diameter = f64::from(radius * 2.0);
         let in_reach = |p: Vec3| {
@@ -2651,9 +2667,9 @@ impl Game<'_> {
             .map(|c| c.position)
             .collect();
         for at in crystals {
-            // One blowing up may already have taken the next.
+            // Look up the current index after each removal.
             if let Some(i) = self.crystals.iter().position(|c| c.position == at) {
-                self.destroy_crystal(i, None);
+                self.destroy_crystal(i, None, CrystalDamage::Explosion);
             }
         }
         let Some(d) = self.dragon.as_ref() else {
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 320a9c56a..9aa1e1278 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -6252,5 +6252,55 @@ CHECKS += ['crystals']
 CHECK_FNS.update(crystals=check_crystals)
 
 
+def check_crystal_blast(host, guest, out):
+    """#1533: TNT removes a crystal without a blast; a punched crystal blasts once.
+    Both clients must see the surviving distant and invulnerable crystals."""
+    spots = apart(host, guest)
+    seen = {}
+    for label, player, other in (('host', host, guest), ('guest', guest, host)):
+        x, y, z = spots[label]
+        y += 32
+        player('command', command='gamemode creative')
+        for offset, cause in enumerate(('tnt', 'melee')):
+            # Leave survivors in separate arenas; the scratch world is discarded.
+            z = spots[label][2] + (0 if label == 'host' else 80) + offset * 40
+            case = f'{label}-{cause}'
+            host('command', command=f'fill {x - 3} {y - 1} {z - 3} {x + 25} {y - 1} {z + 5} minecraft:bedrock')
+            host('command', command=f'fill {x - 3} {y} {z - 3} {x + 25} {y + 4} {z + 5} minecraft:air')
+            positions = [[x + dx, y, z + dz] for dx, dz in ((2.5, 0.5), (12.5, 0.5), (22.5, 0.5), (4.5, 3.5))]
+
+            def remaining(game):
+                crystals = [p for p in game('status')['projectiles'] if p['kind'] == 'minecraft:end_crystal']
+                return [i for i, at in enumerate(positions)
+                        if any(math.dist(p['position'], at) < 0.01 for p in crystals)]
+
+            for i, at in enumerate(positions):
+                host('command', command=f'summon minecraft:end_crystal {at[0]} {at[1]} {at[2]} {{Invulnerable:{1 if i == 3 else 0}b}}')
+            player('command', command=f'tp @s {x + 0.5} {y} {z + 0.5}')
+            other('command', command='gamemode creative')
+            other('command', command=f'tp @s {x + 0.5} {y} {z + 4.5}')
+            player('command', command='clear @s')
+            player.wait(20)
+            for game in (host, guest):
+                assert remaining(game) == [0, 1, 2, 3], f'{case}: crystals not tracked on {game.name}'
+            if cause == 'tnt':
+                player('command', command=f'summon minecraft:tnt {x + 0.5} {y} {z + 0.5} {{fuse:10s}}')
+            else:
+                player.raw('look-at', positions[0][0], y + 1, positions[0][2])
+                player.raw('mouse', 'left', 'click')
+            player.wait(80)
+            result = {game.name: remaining(game) for game in (host, guest)}
+            seen[case] = result
+            # TNT reaches the first crystal only. A direct crystal blast reaches
+            # the second too, but that crystal must not detonate the third.
+            expected = [1, 2, 3] if cause == 'tnt' else [2, 3]
+            assert all(ids == expected for ids in result.values()), f'{case}: expected {expected}, got {result}'
+    return seen
+
+
+CHECKS += ['crystal_blast']
+CHECK_FNS.update(crystal_blast=check_crystal_blast)
+
+
 if __name__ == '__main__':
     main()

From 68234ac4075d4e55b2b5ee5f3acc5d5e9136b08e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:59:31 +0100
Subject: [PATCH 103/270] Hub: the roadmap at /data/roadmap.json and items at
 hub#<id>, as Kira reads them

Kira (kira #10-#14) fetches https://playhorizon.dev/data/roadmap.json and links
items as <hub>#<id>: the JSON moves there (readable from any origin) with the
announce flag, and each item's anchor is its id. Ids the page uses itself (tabs,
sections, headings) are refused by the check; a test keeps every id of the page
unique, which caught the overview's headings sharing ids with the roadmap's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_roadmap.py     |  4 ++++
 tools/roadmap.py          | 10 ++++++++--
 website/Caddyfile         |  5 ++++-
 website/README.md         |  2 +-
 website/build.mjs         |  6 +++---
 website/data/roadmap.json | 15 ++++++++++-----
 website/src/hub-page.js   |  6 +++---
 website/src/hub.js        | 22 +++++++++++-----------
 website/src/hub.test.mjs  | 11 +++++++++--
 9 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/tests/test_roadmap.py b/tests/test_roadmap.py
index 641d4e11b..605843f25 100644
--- a/tests/test_roadmap.py
+++ b/tests/test_roadmap.py
@@ -121,6 +121,10 @@ class Rules(unittest.TestCase):
         self.assertTrue(any("link" in p for p in self.problems(links=["docs/nothing-here.md"])))
         self.assertTrue(any("link" in p for p in self.problems(links=["http://example.com"])))
 
+    def test_ids_are_free_anchors_of_the_hub(self):
+        for taken in ("roadmap", "now", "h-next", "tab-board"):
+            self.assertTrue(any("taken by the hub page" in p for p in self.problems(id=taken)), taken)
+
     def test_flags_are_true_or_false(self):
         self.assertEqual(self.problems(announce=True), [])
         self.assertTrue(any("announce is true or false" in p for p in self.problems(announce="yes")))
diff --git a/tools/roadmap.py b/tools/roadmap.py
index 1a4f58136..f09224147 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -28,7 +28,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 SOURCE = ROOT / "roadmap" / "roadmap.toml"
 OUTPUT = ROOT / "ROADMAP.md"
-# What the website's hub reads (website/build.mjs), and serves at /hub/roadmap.json for Kira and others.
+# What the website's hub reads (website/build.mjs), and serves at /data/roadmap.json for Kira and others.
 SITE_DATA = ROOT / "website" / "data" / "roadmap.json"
 REPO = "ludovic111/horizon"
 SITE = "https://playhorizon.dev/hub"
@@ -52,6 +52,9 @@ ITEM_KEYS = {"id", "title", "status", "area", "plain", "dev", "links", "focus",
 
 ISSUE = re.compile(r"#(\d+)$")
 ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$")
+# An item is the anchor playhorizon.dev/hub#<id>: it can't take the name of a tab, a section or a heading.
+RESERVED = {"main", "overview", "roadmap", "board", "journal", "contribute", "hub-data", *STATUSES}
+RESERVED_PREFIXES = ("h-", "tab-", "week-")
 RELEASE = re.compile(r"(v\d[\w.]*|launcher@\d[\w.]*|launcher-v\d[\w.]*|website)$")
 MONTHS = ("January|February|March|April|June|July|August|September|October|November|December")
 # Kira's rule: no dates and no promises of when. "Coming soon" is the one allowed phrase.
@@ -105,6 +108,8 @@ def validate(data, root=ROOT):
         ident = item.get("id", "")
         if ident and not ID.match(ident):
             problems.append(f"{where}: ids are lowercase words joined by dashes")
+        if ident in RESERVED or ident.startswith(RESERVED_PREFIXES):
+            problems.append(f"{where}: the id is taken by the hub page (hub#{ident} is a tab, a section or a heading)")
         if ident in seen:
             problems.append(f"{where}: the id appears twice")
         seen.add(ident)
@@ -231,7 +236,8 @@ def render(data):
 
 def site_data(data):
     """website/data/roadmap.json: the items as the hub and Kira read them, in the file's order."""
-    keys = ("id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post")
+    keys = ("id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post",
+            "announce")
     out = {
         "format": "horizon-roadmap",
         "version": 1,
diff --git a/website/Caddyfile b/website/Caddyfile
index 50ba44381..a160f2259 100644
--- a/website/Caddyfile
+++ b/website/Caddyfile
@@ -38,8 +38,11 @@
 	redir /roadmap /hub#roadmap permanent
 	@doc path_regexp doc ^/docs/([a-z-]+)$
 	rewrite @doc /docs/{re.doc.1}.html
-	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /hub /hub.html /hub/* /docs /docs/* /sitemap.xml
+	@pages path / /index.html /404.html /privacy.html /releases /releases.html /benchmarks /benchmarks.html /benchmarks.json /hub /hub.html /data/* /docs /docs/* /sitemap.xml
 	header @pages Cache-Control "no-cache"
+	# The hub's data for Kira and anyone else: readable from any origin.
+	@data path /data/*
+	header @data Access-Control-Allow-Origin "*"
 	@legal path /LEGAL.md /fonts/*.txt
 	header @legal Content-Type "text/plain; charset=utf-8"
 
diff --git a/website/README.md b/website/README.md
index c73683c73..8f35fbcf4 100644
--- a/website/README.md
+++ b/website/README.md
@@ -42,7 +42,7 @@ src/releases.js    the home page's "Recently added" and the Releases page's mark
 src/contributors.js the contributors' filtering and markup, shared by build and page
 src/hub.js         the hub's markup from data/roadmap.json and GitHub's issue states, shared by build and page
 src/hub-page.js    the hub page: tabs by #hash, the Simple / Technical switch (localStorage), the area filter, live states
-data/roadmap.json  the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /hub/roadmap.json
+data/roadmap.json  the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /data/roadmap.json
 public/            fonts, screenshots, icons, og.png, robots.txt, benchmarks.json: copied as is (sitemap.xml is written by the build)
 data/benchmarks/   our raw benchmark reports (tools/perf_bench.py) and fleet.json, the list scripts/benchmarks.mjs reads
 scripts/benchmarks.mjs  benchmark reports -> public/benchmarks.json (ours, and players' groups of 3+ installs)
diff --git a/website/build.mjs b/website/build.mjs
index b36e0e103..563bc6fa4 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -428,9 +428,9 @@ for (const { file, values: own } of docPages) {
   docPageFiles.push(file);
 }
 
-// The roadmap for other readers (Kira, scripts): /hub/roadmap.json, as tools/roadmap.py wrote it.
-await mkdir(join(dist, "hub"), { recursive: true });
-await cp(join(site, "data", "roadmap.json"), join(dist, "hub", "roadmap.json"));
+// The roadmap for other readers (Kira, scripts): /data/roadmap.json, as tools/roadmap.py wrote it.
+await mkdir(join(dist, "data"), { recursive: true });
+await cp(join(site, "data", "roadmap.json"), join(dist, "data", "roadmap.json"));
 
 // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS
 // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash.
diff --git a/website/data/roadmap.json b/website/data/roadmap.json
index 142b27011..d4124e534 100644
--- a/website/data/roadmap.json
+++ b/website/data/roadmap.json
@@ -116,7 +116,8 @@
     "#1757",
     "docs/modpacks.md"
    ],
-   "focus": true
+   "focus": true,
+   "announce": true
   },
   {
    "id": "server-clients",
@@ -175,7 +176,8 @@
     "#1640",
     "docs/mods.md"
    ],
-   "focus": true
+   "focus": true,
+   "announce": true
   },
   {
    "id": "server-dialogs",
@@ -232,7 +234,8 @@
    "links": [
     "#1787",
     "#1788"
-   ]
+   ],
+   "announce": true
   },
   {
    "id": "lean-code",
@@ -262,7 +265,8 @@
    "links": [
     "docs/microsoft-account.md",
     "#1270"
-   ]
+   ],
+   "announce": true
   },
   {
    "id": "curseforge",
@@ -274,7 +278,8 @@
    "links": [
     "docs/mod-browser.md",
     "docs/modpacks.md"
-   ]
+   ],
+   "announce": true
   },
   {
    "id": "benchmarks",
diff --git a/website/src/hub-page.js b/website/src/hub-page.js
index 039e98826..97d6f3d60 100644
--- a/website/src/hub-page.js
+++ b/website/src/hub-page.js
@@ -1,4 +1,4 @@
-// The hub page (/hub): its tabs (one per #hash, so /hub#roadmap and /hub#item-<id> can be linked), the
+// The hub page (/hub): its tabs (one per #hash, so /hub#roadmap and /hub#<item id> can be linked), the
 // Simple / Technical switch (remembered in localStorage), the area filter, and the live state of every
 // linked issue and pull request, refreshed from GitHub's public API. Without JavaScript, every tab reads
 // one after the other with what was baked at build time.
@@ -30,7 +30,7 @@ function choose(tab, { focus = false, push = false } = {}) {
   if (focus) tab.focus();
   if (push && location.hash !== `#${panelOf(tab).id}`) history.replaceState(null, "", `#${panelOf(tab).id}`);
 }
-// "#roadmap" opens its tab; "#item-x" or "#help-wanted" opens the tab holding it and scrolls there.
+// "#roadmap" opens its tab; "#<item id>" or "#help-wanted" opens the tab holding it and scrolls there.
 function follow() {
   const target = location.hash && document.getElementById(decodeURIComponent(location.hash.slice(1)));
   const tab = tabs.find((t) => target && (panelOf(t) === target || panelOf(t).contains(target))) || tabs[0];
@@ -116,4 +116,4 @@ async function refresh() {
 setUpTheme();
 setUpMenu();
 follow();
-refresh().then(() => location.hash.startsWith("#item-") && follow());
+refresh().then(() => data.roadmap.items.some((i) => `#${i.id}` === location.hash) && follow());
diff --git a/website/src/hub.js b/website/src/hub.js
index 37e26738c..ecfb4da80 100644
--- a/website/src/hub.js
+++ b/website/src/hub.js
@@ -86,7 +86,7 @@ const areaName = (roadmap, id) => roadmap.areas.find((a) => a.id === id)?.name |
 export function itemHtml(item, roadmap, live) {
   const done = item.status === "shipped";
   const state = done ? "" : progress(item, live);
-  return `<article class="hub-item" id="item-${escape(item.id)}" data-area="${escape(item.area)}" data-item="${escape(item.id)}">
+  return `<article class="hub-item" id="${escape(item.id)}" data-area="${escape(item.area)}" data-item="${escape(item.id)}">
   <p class="hub-item-meta"><span class="badge">${escape(areaName(roadmap, item.area))}</span>${done ? `<span class="badge badge-game">${escape(item.shipped_in)}</span>` : ""}${item.ongoing ? `<span class="hub-ongoing">Ongoing</span>` : ""}</p>
   <h3 class="hub-item-title">${escape(item.title)}</h3>
   <p class="hub-plain">${inline(item.plain)}</p>
@@ -137,25 +137,25 @@ export function overviewHtml(roadmap, live = new Map()) {
   const focus = roadmap.items.filter((i) => i.focus);
   const next = roadmap.items.filter((i) => i.status === "next");
   const shipped = roadmap.items.filter((i) => i.status === "shipped").slice(0, 3);
-  const row = (item, i, meta) => `<li class="row"><a href="#item-${escape(item.id)}" data-goto="roadmap"><span class="row-index">${String(i + 1).padStart(2, "0")}</span><span class="hub-row-body"><span class="hub-row-title">${escape(item.title)}</span><span class="hub-plain">${inline(item.plain)}</span><span class="hub-dev">${inline(item.dev)}</span></span><span class="row-meta">${escape(meta(item))}</span></a></li>`;
+  const row = (item, i, meta) => `<li class="row"><a href="#${escape(item.id)}" data-goto="roadmap"><span class="row-index">${String(i + 1).padStart(2, "0")}</span><span class="hub-row-body"><span class="hub-row-title">${escape(item.title)}</span><span class="hub-plain">${inline(item.plain)}</span><span class="hub-dev">${inline(item.dev)}</span></span><span class="row-meta">${escape(meta(item))}</span></a></li>`;
   return `<div class="hub-today">
   <p class="hub-plain hub-lead">${inline(o.today_plain)}</p>
   <p class="hub-dev hub-lead">${inline(o.today_dev)}</p>
 </div>
-<section class="hub-block" aria-labelledby="h-focus">
-  <h2 class="title" id="h-focus">Being done now</h2>
+<section class="hub-block" aria-labelledby="h-ov-focus">
+  <h2 class="title" id="h-ov-focus">Being done now</h2>
   <ol class="index hub-rows">${focus.map((item, i) => row(item, i, (x) => progress(x, live))).join("")}</ol>
 </section>
-<section class="hub-block" aria-labelledby="h-next">
-  <h2 class="title" id="h-next">Next</h2>
+<section class="hub-block" aria-labelledby="h-ov-next">
+  <h2 class="title" id="h-ov-next">Next</h2>
   <ol class="index hub-rows">${next.map((item, i) => row(item, i, (x) => areaName(roadmap, x.area))).join("")}</ol>
 </section>
-<section class="hub-block" aria-labelledby="h-shipped">
-  <h2 class="title" id="h-shipped">Recently shipped</h2>
+<section class="hub-block" aria-labelledby="h-ov-shipped">
+  <h2 class="title" id="h-ov-shipped">Recently shipped</h2>
   <ol class="index hub-rows">${shipped.map((item, i) => row(item, i, (x) => `In ${x.shipped_in}`)).join("")}</ol>
 </section>
-<section class="hub-block hub-help" aria-labelledby="h-help">
-  <h2 class="title" id="h-help">How to help</h2>
+<section class="hub-block hub-help" aria-labelledby="h-ov-help">
+  <h2 class="title" id="h-ov-help">How to help</h2>
   <p class="hub-plain">${inline(o.help_plain)}</p>
   <p class="hub-dev">${inline(o.help_dev)}</p>
   <p class="hub-actions"><a class="button primary" href="#contribute" data-goto="contribute">Contribute</a><a class="button secondary" href="#help-wanted" data-goto="roadmap">Help wanted</a></p>
@@ -168,7 +168,7 @@ export function helpWantedHtml(roadmap) {
     .filter((i) => i.status === "help-wanted")
     .map((item, i) => {
       const first = (item.links || []).map(number).find(Boolean);
-      const href = first ? issueUrl(first) : `#item-${item.id}`;
+      const href = first ? issueUrl(first) : `#${item.id}`;
       return `<li class="row"><a href="${escape(href)}"><span class="row-index">${String(i + 1).padStart(2, "0")}</span><span class="hub-row-body"><span class="hub-row-title">${escape(item.title)}</span><span class="hub-plain">${inline(item.plain)}</span><span class="hub-dev">${inline(item.dev)}</span></span><span class="row-meta">${first ? `#${first}` : ""}</span></a></li>`;
     })
     .join("");
diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs
index e73c9a8af..eb9b8a087 100644
--- a/website/src/hub.test.mjs
+++ b/website/src/hub.test.mjs
@@ -33,7 +33,7 @@ test("an item's progress counts its pull requests and issues", () => {
 test("the roadmap renders every item once, with both texts, in its status's section", () => {
   const html = roadmapHtml(roadmap);
   for (const item of roadmap.items) {
-    assert.equal(html.split(`id="item-${item.id}"`).length, 2, item.id);
+    assert.equal(html.split(`id="${item.id}"`).length, 2, item.id);
   }
   assert.ok(html.indexOf('id="now"') < html.indexOf('id="next"'));
   assert.ok(html.includes('class="hub-plain"') && html.includes('class="hub-dev"'));
@@ -41,8 +41,15 @@ test("the roadmap renders every item once, with both texts, in its status's sect
   assert.ok(html.includes(`>${roadmap.items.find((i) => i.status === "shipped").shipped_in}<`));
 });
 
+test("an item is its own anchor (hub#<id>, as Kira links it) and takes no other id of the page", () => {
+  const page = readFileSync(new URL("./hub.html", import.meta.url), "utf8") + roadmapHtml(roadmap) + overviewHtml(roadmap);
+  const ids = [...page.matchAll(/ id="([^"]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(ids.filter((id, i) => ids.indexOf(id) !== i), []);
+  for (const item of roadmap.items) assert.ok(ids.includes(item.id), item.id);
+});
+
 test("the overview lists the focus items and never nests links", () => {
   const html = overviewHtml(roadmap);
-  for (const item of roadmap.items.filter((i) => i.focus)) assert.ok(html.includes(`href="#item-${item.id}"`), item.id);
+  for (const item of roadmap.items.filter((i) => i.focus)) assert.ok(html.includes(`href="#${item.id}"`), item.id);
   for (const row of html.match(/<li class="row">[\s\S]*?<\/li>/g)) assert.equal(row.split("<a ").length, 2, row);
 });

From c5a640dd56c0ac7607fc056934ef7471a6eb60a6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:59:56 +0100
Subject: [PATCH 104/270] Endermen, endermites, blazes, eyes of ender, dried
 ghasts and end portals make their ambient effects

The client-side branches vanilla runs on its own level: Enderman and
Endermite aiStep (two portal particles a tick), Blaze aiStep (two large
smoke particles, the burn sound one tick in 24), EyeOfEnder.tick (a
portal particle behind it, four bubbles in water), and the
DriedGhastBlock and EndPortalBlock animateTick. They run on the window's
game in-frame and as a server's client, never on a server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/animate_tick.rs     | 50 +++++++++++++++++
 crates/horizon-client/src/game.rs             |  2 +
 .../horizon-client/src/game/client_ambient.rs | 37 +++++++++++++
 crates/horizon-client/src/game/end.rs         | 36 +++++++++++-
 crates/horizon-client/src/game/remote.rs      |  1 +
 crates/horizon-client/src/mobs.rs             |  1 +
 crates/horizon-client/src/mobs/ambient.rs     | 55 +++++++++++++++++++
 7 files changed, 181 insertions(+), 1 deletion(-)
 create mode 100644 crates/horizon-client/src/game/client_ambient.rs
 create mode 100644 crates/horizon-client/src/mobs/ambient.rs

diff --git a/crates/horizon-client/src/animate_tick.rs b/crates/horizon-client/src/animate_tick.rs
index ce34df510..48e8f16f4 100644
--- a/crates/horizon-client/src/animate_tick.rs
+++ b/crates/horizon-client/src/animate_tick.rs
@@ -63,6 +63,10 @@ enum Animate {
     SculkSensor,
     /// Potent sulfur that is not dry.
     PotentSulfur,
+    DriedGhast {
+        waterlogged: bool,
+    },
+    EndPortal,
 }
 fn step(facing: &str) -> [i32; 3] {
     match facing {
@@ -137,6 +141,10 @@ fn classify(name: &str, prop: &dyn Fn(&str) -> Option<String>) -> Animate {
             drag: prop("drag").as_deref() == Some("true"),
         },
         "fire" | "soul_fire" => Animate::Fire,
+        "dried_ghast" => Animate::DriedGhast {
+            waterlogged: prop("waterlogged").as_deref() == Some("true"),
+        },
+        "end_portal" => Animate::EndPortal,
         "sculk_sensor" | "calibrated_sculk_sensor"
             if prop("sculk_sensor_phase").as_deref() == Some("active") =>
         {
@@ -180,6 +188,8 @@ pub struct AnimateTables {
     impermeable: Vec<bool>,
     power_provider: Vec<bool>,
     power_transmitter: Vec<bool>,
+    /// `#triggers_ambient_dried_ghast_block_sounds` (soul sand, soul soil).
+    dried_ghast_sounds: Vec<bool>,
     /// Biome id -> ambient particles and probabilities (`minecraft:visual/ambient_particles`).
     ambient: Vec<Vec<(T, f32)>>,
 }
@@ -237,6 +247,7 @@ impl AnimateTables {
             impermeable: by_state("minecraft:impermeable"),
             power_provider: by_state("minecraft:enchantment_power_provider"),
             power_transmitter: by_state("minecraft:enchantment_power_transmitter"),
+            dried_ghast_sounds: by_state("minecraft:triggers_ambient_dried_ghast_block_sounds"),
             ambient,
         })
     }
@@ -869,6 +880,45 @@ fn block_animate_tick(
             ];
             add(engine, T::Smoke, p, [0.0; 3]);
         }
+        Animate::DriedGhast { waterlogged } => {
+            // DriedGhastBlock.animateTick.
+            let c = [fx + 0.5, fy + 0.5, fz + 0.5];
+            if waterlogged {
+                if next_int(engine.random(), 40) == 0 {
+                    let name = "minecraft:block.dried_ghast.ambient_water";
+                    sound(engine, name, c, 1.0, 1.0);
+                }
+                let r = engine.random();
+                if next_int(r, 6) == 0 {
+                    let x = c[0] + f64::from((r.next_float() * 2.0 - 1.0) / 3.0);
+                    let y = c[1] + 0.4;
+                    let z = c[2] + f64::from((r.next_float() * 2.0 - 1.0) / 3.0);
+                    let v = [0.0, f64::from(r.next_float()), 0.0];
+                    add(engine, T::HappyVillager, [x, y, z], v);
+                }
+            } else {
+                let below = ctx.state([pos[0], pos[1] - 1, pos[2]]);
+                let triggers = || {
+                    tables
+                        .dried_ghast_sounds
+                        .get(below.0 as usize)
+                        .copied()
+                        .unwrap_or(false)
+                };
+                if next_int(engine.random(), 40) == 0 && triggers() {
+                    sound(engine, "minecraft:block.dried_ghast.ambient", c, 1.0, 1.0);
+                }
+                if next_int(engine.random(), 6) == 0 {
+                    add(engine, T::WhiteSmoke, c, [0.0, 0.02, 0.0]);
+                }
+            }
+        }
+        Animate::EndPortal => {
+            // EndPortalBlock.animateTick: one smoke particle above the surface.
+            let r = engine.random();
+            let p = [fx + r.next_double(), fy + 0.8, fz + r.next_double()];
+            add(engine, T::Smoke, p, [0.0; 3]);
+        }
         Animate::EnderChest => {
             for _ in 0..3 {
                 let r = engine.random();
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..46621082e 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -20,6 +20,7 @@ mod bossbars;
 mod breezes;
 mod cartography;
 mod chat;
+mod client_ambient;
 mod clipboard;
 mod combat;
 mod command_blocks;
@@ -4447,6 +4448,7 @@ impl Game<'_> {
                 self.tick_block_entity_anims()
             });
             horizon_client::spans::time("tick_particles", || self.tick_particles());
+            self.tick_client_ambient();
         }
         // ServerBossEvent broadcasts, after this level's entities have ticked.
         self.publish_boss_bars();
diff --git a/crates/horizon-client/src/game/client_ambient.rs b/crates/horizon-client/src/game/client_ambient.rs
new file mode 100644
index 000000000..a10c6da49
--- /dev/null
+++ b/crates/horizon-client/src/game/client_ambient.rs
@@ -0,0 +1,37 @@
+//! The window's own ambient effects of entities, which a client makes for
+//! itself (`level().isClientSide()` branches): endermen's and endermites'
+//! portal particles, blazes' smoke and burn, eyes of ender's trail. They run
+//! on the game that has the window, in-frame or following a server, never on
+//! a server: nothing of them goes over the network.
+use super::Game;
+use horizon_client::mobs::{MobEvent, ambient};
+use horizon_client::particles::{ParticleOptions, ParticleType};
+
+impl Game<'_> {
+    pub(super) fn tick_client_ambient(&mut self) {
+        if self.serving.is_some() || self.options.dedicated.is_some() {
+            return;
+        }
+        let mut events = Vec::new();
+        for m in self.mobs.iter_mut().filter(|m| !m.removed) {
+            ambient::client_ai_step(m, &mut events);
+        }
+        for event in events {
+            match event {
+                MobEvent::ParticleAt { kind, at, velocity } => {
+                    if let Some(ty) = ParticleType::from_name(kind) {
+                        self.particles
+                            .add(&ParticleOptions::simple(ty), at, velocity);
+                    }
+                }
+                // Each guest of a LAN host makes its own.
+                MobEvent::LocalSound(name, at, volume, pitch) => {
+                    self.audio
+                        .play_unshared(&format!("minecraft:{name}"), Some(at), volume, pitch)
+                }
+                _ => {}
+            }
+        }
+        self.eye_particles();
+    }
+}
diff --git a/crates/horizon-client/src/game/end.rs b/crates/horizon-client/src/game/end.rs
index 599158e3e..655971a5c 100644
--- a/crates/horizon-client/src/game/end.rs
+++ b/crates/horizon-client/src/game/end.rs
@@ -4,7 +4,12 @@
 //! inactive until the dragon dies.
 use super::{Dim, Game};
 use horizon_client::{
-    Result, environment::Environment, items::ItemStack, mesher::Vertex, motion::PlayerMotion,
+    Result,
+    environment::Environment,
+    items::ItemStack,
+    mesher::Vertex,
+    motion::PlayerMotion,
+    particles::{ParticleOptions, ParticleType},
     vanillagen::VanillaTerrain,
 };
 use horizon_core::{
@@ -1122,6 +1127,35 @@ impl Game<'_> {
         self.end.eyes = eyes;
     }
 
+    /// `EyeOfEnder.tick` on a client: behind each eye (a quarter of its last
+    /// move back), four bubbles in water, else a portal particle.
+    pub(super) fn eye_particles(&mut self) {
+        for i in 0..self.end.eyes.len() {
+            let e = &self.end.eyes[i];
+            let movement = (e.position - e.previous).to_array();
+            let origin = (e.position - (e.position - e.previous) * 0.25).to_array();
+            let block = origin.map(|v| v.floor() as i32);
+            let water = self
+                .res
+                .facts()
+                .get(self.world.block(block[0], block[1], block[2]))
+                .fluid
+                == horizon_client::blocks::Fluid::Water;
+            if water {
+                let bubble = ParticleOptions::simple(ParticleType::Bubble);
+                for _ in 0..4 {
+                    self.particles.add(&bubble, origin, movement);
+                }
+            } else {
+                let r = self.particles.random();
+                let x = origin[0] + r.next_double() * 0.6 - 0.3;
+                let z = origin[2] + r.next_double() * 0.6 - 0.3;
+                let portal = ParticleOptions::simple(ParticleType::Portal);
+                self.particles
+                    .add(&portal, [x, origin[1] - 0.5, z], movement);
+            }
+        }
+    }
     /// ThrownItemRenderer: the ender eye item facing the camera.
     fn eye_geometry(&self, camera: glam::DVec3, out: &mut Vec<Vertex>) {
         let Some(r) = self.gui.atlas.sprites.get("item/ender_eye").copied() else {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..711753869 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -3187,6 +3187,7 @@ impl Game<'_> {
         self.tick_block_entity_anims();
         self.tick_hand();
         self.tick_particles();
+        self.tick_client_ambient();
         self.tick_client_effects();
         // Player.tick's sleep counter (the darkening and the wake-up fade).
         self.sleep_timer = super::tick_sleep_timer(self.sleep_timer, self.sleeping.is_some());
diff --git a/crates/horizon-client/src/mobs.rs b/crates/horizon-client/src/mobs.rs
index 4e3879fe5..6dee6a829 100644
--- a/crates/horizon-client/src/mobs.rs
+++ b/crates/horizon-client/src/mobs.rs
@@ -7,6 +7,7 @@
 //! behaviour, models, animations and sounds.
 pub mod ai;
 pub mod allay;
+pub mod ambient;
 pub mod anim;
 pub mod animal_brain;
 pub mod aquatic;
diff --git a/crates/horizon-client/src/mobs/ambient.rs b/crates/horizon-client/src/mobs/ambient.rs
new file mode 100644
index 000000000..cb4146e08
--- /dev/null
+++ b/crates/horizon-client/src/mobs/ambient.rs
@@ -0,0 +1,55 @@
+//! What a client's copy of a mob makes on its own, in the
+//! `level().isClientSide()` branches of `aiStep`: nothing of it reaches the
+//! server or goes over the network, so the window's game runs it, whether it
+//! simulates the world (in-frame) or follows a server.
+use super::{Mob, MobEvent, Species};
+use horizon_core::random::RandomSource;
+
+/// `Enderman.aiStep`, `Endermite.aiStep` and `Blaze.aiStep` on a client:
+/// two portal particles a tick around endermen and endermites; two large
+/// smoke particles a tick around blazes and, one tick in 24, their burn.
+pub fn client_ai_step(m: &mut Mob, out: &mut Vec<MobEvent>) {
+    let species = m.species();
+    if !matches!(
+        species,
+        Species::Enderman | Species::Endermite | Species::Blaze
+    ) {
+        return;
+    }
+    let (w, h) = (f64::from(m.width()), f64::from(m.height()));
+    let p = m.position;
+    if species == Species::Blaze && m.random.next_int_bound(24).unwrap_or(1) == 0 && !m.silent {
+        let volume = 1.0 + m.random.next_float();
+        let pitch = m.random.next_float() * 0.7 + 0.3;
+        out.push(MobEvent::LocalSound(
+            "entity.blaze.burn",
+            [p.x + 0.5, p.y + 0.5, p.z + 0.5],
+            volume,
+            pitch,
+        ));
+    }
+    for _ in 0..2 {
+        // Entity.getRandomX(0.5), getRandomY(), getRandomZ(0.5).
+        let r = &mut m.random;
+        let x = p.x + w * (2.0 * r.next_double() - 1.0) * 0.5;
+        let y = p.y + h * r.next_double();
+        let z = p.z + w * (2.0 * r.next_double() - 1.0) * 0.5;
+        let (kind, at, velocity) = if species == Species::Blaze {
+            ("large_smoke", [x, y, z], [0.0; 3])
+        } else {
+            // The enderman's are a quarter block lower.
+            let y = if species == Species::Enderman {
+                y - 0.25
+            } else {
+                y
+            };
+            let velocity = [
+                (r.next_double() - 0.5) * 2.0,
+                -r.next_double(),
+                (r.next_double() - 0.5) * 2.0,
+            ];
+            ("portal", [x, y, z], velocity)
+        };
+        out.push(MobEvent::ParticleAt { kind, at, velocity });
+    }
+}

From c04b7afdb9b515b57cde9459f2e01386e4e327bd Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:35:27 +0100
Subject: [PATCH 105/270] Hub: the Kanban and the Journal tabs, and
 /hub/journal.json

Kanban: every open issue and pull request and what closed in the last seven days, placed in To do,
In progress, In review and Done by the rules of Kira's work board, each card with its roadmap item
(its roadmap:<id> label or the item linking it) and a filter by item. Journal: every release with its
changes grouped by roadmap item, the merges no release has yet, and a weekly summary from
roadmap/journal/<year>-<week>.md. The same journal is /hub/journal.json, for Kira's #updates and posts
elsewhere: each entry names the roadmap items it moved and shipped, with their 240-character text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 roadmap/README.md          |  24 ++++-
 roadmap/journal/2026-43.md |  17 ++++
 tests/test_roadmap.py      |  17 ++++
 tools/roadmap.py           |  24 +++++
 website/README.md          |   4 +-
 website/build.mjs          |  11 ++-
 website/data/roadmap.json  |   9 ++
 website/src/hub-page.js    |  33 ++++++-
 website/src/hub.html       |  19 ++++
 website/src/hub.js         | 198 +++++++++++++++++++++++++++++++++++++
 website/src/hub.test.mjs   |  47 ++++++++-
 website/src/style.css      |  39 ++++++++
 12 files changed, 435 insertions(+), 7 deletions(-)
 create mode 100644 roadmap/journal/2026-43.md

diff --git a/roadmap/README.md b/roadmap/README.md
index 656303464..f16e83f8c 100644
--- a/roadmap/README.md
+++ b/roadmap/README.md
@@ -50,8 +50,30 @@ Whoever moves the work (the orchestrator on each heartbeat, or anyone in their p
    item, updates their colour (by status) and description, and adds the label to the open pull requests an item
    links. Label a new pull request for an item by hand or by linking it and running `labels` again. Labels of
    removed items are listed, never deleted.
-5. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
+5. Once a week, write the week's summary in `roadmap/journal/<year>-<ISO week>.md` (for example
+   `2026-43.md`): `# Title`, a paragraph or two for players, then `## Technical` and the same week for
+   contributors, with its pull requests. `build` puts it into website/data/roadmap.json; the hub's Journal tab
+   shows it among the releases, and `/hub/journal.json` carries it to Kira's #updates and to posts elsewhere.
+6. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
    item in a normal pull request; none is published automatically.
 
 CI runs `tests/test_roadmap.py` (in the Python tests), which fails when ROADMAP.md is not what `build` writes
 or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs the same rules without GitHub.
+
+## The journal
+
+The hub's Journal tab and `https://playhorizon.dev/hub/journal.json` are built with each deploy of the website
+(`website/src/hub.js`, `journalFrom`): every game and launcher release with its notes' changes, each placed under
+the roadmap item it moves (the pull request's `roadmap:<id>` label, else the item that links it); the merged pull
+requests no release has yet; and the weekly summaries above. Its JSON, newest first:
+
+```json
+{ "format": "horizon-journal", "version": 1, "generated": "…", "url": "https://playhorizon.dev/hub#journal",
+  "entries": [ { "id": "v0.2.57", "kind": "release | launcher | merged | week", "date": "…", "title": "…",
+                 "plain": "one line for players", "url": "…", "dev": "weeks only",
+                 "changes": [ { "section": "new | fixed | merged", "text": "…", "prs": [1787], "item": "discord-presence" } ],
+                 "items": [ { "id", "title", "plain", "post" } ],      // roadmap items the entry moved
+                 "shipped": [ { "id", "title", "plain", "post" } ] } ] } // items that shipped in this release
+```
+
+`post` is at most 240 characters, ready to announce as is. Readers should remember the ids they have posted.
diff --git a/roadmap/journal/2026-43.md b/roadmap/journal/2026-43.md
new file mode 100644
index 000000000..388f5d544
--- /dev/null
+++ b/roadmap/journal/2026-43.md
@@ -0,0 +1,17 @@
+# Single player becomes a server, servers send their packs
+
+Single player now runs on its own server thread, as vanilla does, and a run of fixes made shields, tridents,
+elytra, maps, fishing, signs and books work there and for every server player. Servers can send you their
+resource packs, the launcher got its blocky new look, and the first pieces of Horizon's mod registry landed.
+Shader packs were taken out, to come back written from scratch.
+
+## Technical
+
+The server thread became the default (#1514), after guests and server-thread players reached parity: totems
+(#1463), death drops (#1464), signs and books (#1465, #1466), shields, tridents, crossbows and spyglasses
+(#1476), elytra (#1475), maps (#1510), fishing (#1509), wind charges (#1508), strikes and mob effects (#1512),
+the cursor stack on close (#1513). Server resource packs: the dedicated server offers them (#1562) and the
+client downloads, asks and applies them (#1569, #1570). Mod registry: index schema 1 and `.hpack` (#1634),
+`cargo horizon-mod check` (#1642), the submission service (#1659). Shader packs were removed (#1561) and the
+clean-room rewrite started from the format's documentation (#1584 onward). Releases now ship in batches of five
+pull requests, or six hours after the oldest (#1554).
diff --git a/tests/test_roadmap.py b/tests/test_roadmap.py
index 605843f25..6c7b14e31 100644
--- a/tests/test_roadmap.py
+++ b/tests/test_roadmap.py
@@ -171,6 +171,23 @@ class GitHubState(unittest.TestCase):
         self.assertTrue(any("#10 is neither" in p for p in problems))
 
 
+class Journal(unittest.TestCase):
+    def test_weekly_summaries_newest_first_with_their_monday(self):
+        import tempfile
+        from pathlib import Path
+        with tempfile.TemporaryDirectory() as folder:
+            folder = Path(folder)
+            (folder / "2026-43.md").write_text("# A week\n\nPlain\nwords.\n\n## Technical\n\nDev (#1).\n")
+            (folder / "2026-42.md").write_text("# Older\n\nPlain.\n\n## Technical\n\nDev.\n")
+            (folder / "week-44.md").write_text("# Bad name\n")
+            (folder / "2026-45.md").write_text("# No technical part\n\nPlain.\n")
+            entries, problems = roadmap.weeks(folder)
+        self.assertEqual([e["week"] for e in entries], ["2026-43", "2026-42"])
+        self.assertEqual(entries[0], {"week": "2026-43", "date": "2026-10-19", "title": "A week",
+                                      "plain": "Plain words.", "dev": "Dev (#1)."})
+        self.assertEqual(len(problems), 2)
+
+
 class Labels(unittest.TestCase):
     def test_creates_updates_and_adds_labels(self):
         data = tomllib.loads(SAMPLE)
diff --git a/tools/roadmap.py b/tools/roadmap.py
index f09224147..ab0147e70 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -30,6 +30,9 @@ SOURCE = ROOT / "roadmap" / "roadmap.toml"
 OUTPUT = ROOT / "ROADMAP.md"
 # What the website's hub reads (website/build.mjs), and serves at /data/roadmap.json for Kira and others.
 SITE_DATA = ROOT / "website" / "data" / "roadmap.json"
+# The journal's weekly summaries, one file per ISO week: roadmap/journal/2026-43.md (roadmap/README.md).
+JOURNAL = ROOT / "roadmap" / "journal"
+WEEK = re.compile(r"(\d{4})-(\d{2})\.md$")
 REPO = "ludovic111/horizon"
 SITE = "https://playhorizon.dev/hub"
 
@@ -153,6 +156,7 @@ def validate(data, root=ROOT):
                 continue
             if link.startswith(("/", "http:")) or ".." in link or not (root / link).exists():
                 problems.append(f"{where}: link {link!r} is neither #N, https:// nor a path in the repository")
+    problems += weeks()[1] if root == ROOT else []
     focus = sum(1 for item in items if item.get("focus"))
     low, high = FOCUS_RANGE
     if not low <= focus <= high:
@@ -234,6 +238,25 @@ def render(data):
     return "\n".join(out) + "\n"
 
 
+def weeks(directory=JOURNAL):
+    """The weekly summaries, newest first: {"week", "date" (its Monday), "title", "plain", "dev"}, and problems."""
+    entries, problems = [], []
+    for path in sorted(directory.glob("*.md"), reverse=True) if directory.exists() else []:
+        name = WEEK.match(path.name)
+        text = path.read_text()
+        parts = re.match(r"# (.+)\n\n(.+?)\n\n## Technical\n\n(.+)", text.strip() + "\n", re.S)
+        if not name or not 1 <= int(name[2]) <= 53:
+            problems.append(f"journal/{path.name}: name it by its ISO week, like 2026-43.md")
+            continue
+        if not parts:
+            problems.append(f"journal/{path.name}: needs '# Title', the plain text, then '## Technical' and its text")
+            continue
+        monday = datetime.date.fromisocalendar(int(name[1]), int(name[2]), 1)
+        entries.append({"week": path.stem, "date": monday.isoformat(), "title": parts[1].strip(),
+                        "plain": " ".join(parts[2].split()), "dev": " ".join(parts[3].split())})
+    return entries, problems
+
+
 def site_data(data):
     """website/data/roadmap.json: the items as the hub and Kira read them, in the file's order."""
     keys = ("id", "title", "status", "area", "plain", "dev", "links", "focus", "ongoing", "shipped_in", "post",
@@ -247,6 +270,7 @@ def site_data(data):
         "areas": [{"id": key, "name": name} for key, name in areas_in_order(data)],
         "items": [{key: (" ".join(item[key].split()) if isinstance(item[key], str) else item[key])
                    for key in keys if key in item} for item in data.get("item", [])],
+        "journal": weeks()[0],
     }
     return json.dumps(out, indent=1, ensure_ascii=False) + "\n"
 
diff --git a/website/README.md b/website/README.md
index 8f35fbcf4..56fa515b9 100644
--- a/website/README.md
+++ b/website/README.md
@@ -25,7 +25,7 @@ src/404.html       the not-found page
 src/privacy.html   what the launcher can send when players allow it, retention, deletion (/privacy)
 src/releases.html  every release, newest first, with what it adds and fixes, its notes and downloads (/releases)
 src/benchmarks.html Horizon against vanilla 26.3 on our machines, the hardware picker, players' results (/benchmarks)
-src/hub.html       the hub (/hub, /roadmap redirects to its Roadmap tab): Overview, Roadmap, Contribute, a Simple / Technical switch
+src/hub.html       the hub (/hub, /roadmap redirects to its Roadmap tab): Overview, Roadmap, Kanban, Journal, Contribute, a Simple / Technical switch
 src/docs.html      the template of every documentation page (/docs/...), with its left navigation
 src/tokens.css     the design tokens, generated from crates/horizon-theme (do not edit)
 src/style.css      every style, on top of the tokens
@@ -40,7 +40,7 @@ src/estimate.js    estimates for unmeasured hardware from the nearest measured m
 src/markdown.js    a small Markdown renderer (escapes everything), shared by build and page
 src/releases.js    the home page's "Recently added" and the Releases page's markup, shared by build and page
 src/contributors.js the contributors' filtering and markup, shared by build and page
-src/hub.js         the hub's markup from data/roadmap.json and GitHub's issue states, shared by build and page
+src/hub.js         the hub's roadmap, board and journal from data/roadmap.json, GitHub's issues and the releases, shared by build and page; /hub/journal.json
 src/hub-page.js    the hub page: tabs by #hash, the Simple / Technical switch (localStorage), the area filter, live states
 data/roadmap.json  the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /data/roadmap.json
 public/            fonts, screenshots, icons, og.png, robots.txt, benchmarks.json: copied as is (sitemap.xml is written by the build)
diff --git a/website/build.mjs b/website/build.mjs
index 563bc6fa4..17768e5fc 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -16,7 +16,7 @@ import { machinesHtml, playersHtml } from "./src/bench.js";
 import { CPUS, GPUS, singleThread } from "./src/hardware.js";
 import { isGame, isLauncher, launcherVersion, newestFirst } from "./src/versions.js";
 import { contributorsFrom, contributorsHtml } from "./src/contributors.js";
-import { areaFilterHtml, helpWantedHtml, overviewHtml, roadmapHtml, slimIssue } from "./src/hub.js";
+import { areaFilterHtml, boardFilterHtml, boardFrom, boardHtml, helpWantedHtml, journalFrom, journalHtml, journalJson, overviewHtml, roadmapHtml, slimIssue } from "./src/hub.js";
 
 const site = dirname(fileURLToPath(import.meta.url));
 const dist = join(site, "dist");
@@ -116,6 +116,8 @@ try {
   console.warn(`hub: ${e.message}; the page will load the states itself`);
 }
 const hubLinked = new Map(hubLive.filter((i) => linked.has(i.n)).map((i) => [i.n, i]));
+const board = boardFrom(hubLive, roadmap);
+const journal = journalFrom(releases, hubLive, roadmap);
 
 // --- The parity table ------------------------------------------------------------------
 
@@ -327,6 +329,9 @@ const values = {
   HUB_ROADMAP: roadmapHtml(roadmap, hubLinked),
   HUB_AREAS: areaFilterHtml(roadmap),
   HUB_HELP_WANTED: helpWantedHtml(roadmap),
+  HUB_BOARD: hubLive.length ? boardHtml(board, roadmap) : `<p class="lede">The board could not be loaded here.</p>`,
+  HUB_BOARD_FILTER: boardFilterHtml(board, roadmap),
+  HUB_JOURNAL: journalHtml(journal, roadmap) || unavailable,
   HUB_DATA: JSON.stringify({ roadmap, live: [...hubLinked.values()] }).replace(/</g, "\\u003c"),
   YEAR: String(new Date().getUTCFullYear()),
 };
@@ -431,6 +436,8 @@ for (const { file, values: own } of docPages) {
 // The roadmap for other readers (Kira, scripts): /data/roadmap.json, as tools/roadmap.py wrote it.
 await mkdir(join(dist, "data"), { recursive: true });
 await cp(join(site, "data", "roadmap.json"), join(dist, "data", "roadmap.json"));
+// The journal for Kira's #updates and its X posts: /data/journal.json, rebuilt with every deploy.
+await writeFile(join(dist, "data", "journal.json"), JSON.stringify(journalJson(journal, roadmap), null, 1) + "\n");
 
 // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS
 // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash.
@@ -447,5 +454,5 @@ await writeFile(
 
 console.log(
   `built dist/ from ${readmeFrom}: ${body.length} subsystems, ${percent}, ${harnesses} harnesses, ` +
-    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages, ${roadmap.items.length} roadmap items (${hubLinked.size}/${linked.size} links live)`,
+    `${ours.length} releases (${game.length} game)${launcher ? `, launcher ${launcher.tag_name}` : ""}, ${benchSummary.groups.length} benchmark rows, ${contributors.length} contributors, ${docs.length} docs pages, ${roadmap.items.length} roadmap items (${hubLinked.size}/${linked.size} links live), ${Object.values(board).flat().length} board cards, ${journal.length} journal entries`,
 );
diff --git a/website/data/roadmap.json b/website/data/roadmap.json
index d4124e534..1fcbdd773 100644
--- a/website/data/roadmap.json
+++ b/website/data/roadmap.json
@@ -558,5 +558,14 @@
    ],
    "shipped_in": "launcher-v0.15.0"
   }
+ ],
+ "journal": [
+  {
+   "week": "2026-43",
+   "date": "2026-10-19",
+   "title": "Single player becomes a server, servers send their packs",
+   "plain": "Single player now runs on its own server thread, as vanilla does, and a run of fixes made shields, tridents, elytra, maps, fishing, signs and books work there and for every server player. Servers can send you their resource packs, the launcher got its blocky new look, and the first pieces of Horizon's mod registry landed. Shader packs were taken out, to come back written from scratch.",
+   "dev": "The server thread became the default (#1514), after guests and server-thread players reached parity: totems (#1463), death drops (#1464), signs and books (#1465, #1466), shields, tridents, crossbows and spyglasses (#1476), elytra (#1475), maps (#1510), fishing (#1509), wind charges (#1508), strikes and mob effects (#1512), the cursor stack on close (#1513). Server resource packs: the dedicated server offers them (#1562) and the client downloads, asks and applies them (#1569, #1570). Mod registry: index schema 1 and `.hpack` (#1634), `cargo horizon-mod check` (#1642), the submission service (#1659). Shader packs were removed (#1561) and the clean-room rewrite started from the format's documentation (#1584 onward). Releases now ship in batches of five pull requests, or six hours after the oldest (#1554)."
+  }
  ]
 }
diff --git a/website/src/hub-page.js b/website/src/hub-page.js
index 97d6f3d60..748ddbab4 100644
--- a/website/src/hub-page.js
+++ b/website/src/hub-page.js
@@ -3,7 +3,7 @@
 // linked issue and pull request, refreshed from GitHub's public API. Without JavaScript, every tab reads
 // one after the other with what was baked at build time.
 import { cached, get, setUpMenu, setUpTheme } from "./chrome.js";
-import { REPO, overviewHtml, roadmapHtml, slimIssue } from "./hub.js";
+import { REPO, boardFilterHtml, boardFrom, boardHtml, journalFrom, journalHtml, overviewHtml, roadmapHtml, slimIssue } from "./hub.js";
 
 const root = document.documentElement;
 const data = JSON.parse(document.getElementById("hub-data").textContent);
@@ -87,6 +87,28 @@ function filter(to) {
 }
 areaButtons.forEach((b) => b.addEventListener("click", () => filter(b.dataset.areaFilter)));
 
+// --- The board: a roadmap item's cards, and the long columns' "Show more" ----------------------------------------
+
+const boardSelect = document.querySelector("[data-board-item]");
+function showItem() {
+  const want = boardSelect.value;
+  for (const card of document.querySelectorAll("[data-board] .hub-card")) {
+    card.hidden = want === "-" ? !card.dataset.item : want ? card.dataset.item !== want : false;
+  }
+  for (const column of document.querySelectorAll("[data-board] .hub-column")) {
+    column.querySelector("[data-count]").textContent = column.querySelectorAll(".hub-card:not([hidden])").length;
+    // A filtered column shows all its cards.
+    column.classList.toggle("is-open", Boolean(want) || column.classList.contains("was-opened"));
+  }
+}
+boardSelect?.addEventListener("change", showItem);
+document.querySelector("[data-board]")?.addEventListener("click", (e) => {
+  const button = e.target.closest("[data-more-button]");
+  if (!button) return;
+  button.closest(".hub-column").classList.add("is-open", "was-opened");
+  button.remove();
+});
+
 // --- Live state from GitHub ------------------------------------------------------------------------------------
 
 // The open issues and pull requests, and those closed or merged lately: four requests at most, kept ten minutes.
@@ -100,6 +122,7 @@ async function loadLive() {
   const closed = await get(`https://api.github.com/repos/${REPO}/issues?state=closed&sort=updated&direction=desc&per_page=100`);
   return list.concat(closed.map(slimIssue));
 }
+const loadReleases = () => get(`https://api.github.com/repos/${REPO}/releases?per_page=40`);
 
 async function refresh() {
   const fresh = await cached("horizon:hub-live", loadLive).catch(() => null);
@@ -109,6 +132,14 @@ async function refresh() {
   document.querySelector("[data-overview]").innerHTML = overviewHtml(data.roadmap, live);
   document.querySelector("[data-roadmap]").innerHTML = roadmapHtml(data.roadmap, live);
   filter(area);
+  const board = boardFrom(fresh, data.roadmap);
+  const chosen = boardSelect.value;
+  boardSelect.innerHTML = boardFilterHtml(board, data.roadmap);
+  boardSelect.value = [...boardSelect.options].some((o) => o.value === chosen) ? chosen : "";
+  document.querySelector("[data-board]").innerHTML = boardHtml(board, data.roadmap);
+  showItem();
+  const releases = await cached("horizon:hub-releases", loadReleases).catch(() => null);
+  if (releases) document.querySelector("[data-journal]").innerHTML = journalHtml(journalFrom(releases, fresh, data.roadmap), data.roadmap);
   const note = document.querySelector("[data-live-note]");
   if (note) note.textContent = "Pull request and issue states are live from GitHub.";
 }
diff --git a/website/src/hub.html b/website/src/hub.html
index 5aff05639..a6e146080 100644
--- a/website/src/hub.html
+++ b/website/src/hub.html
@@ -36,6 +36,8 @@
             <span class="tab-pill" aria-hidden="true"></span>
             <button type="button" role="tab" id="tab-overview" aria-controls="overview" aria-selected="true">Overview</button>
             <button type="button" role="tab" id="tab-roadmap" aria-controls="roadmap" aria-selected="false" tabindex="-1">Roadmap</button>
+            <button type="button" role="tab" id="tab-board" aria-controls="board" aria-selected="false" tabindex="-1">Kanban</button>
+            <button type="button" role="tab" id="tab-journal" aria-controls="journal" aria-selected="false" tabindex="-1">Journal</button>
             <button type="button" role="tab" id="tab-contribute" aria-controls="contribute" aria-selected="false" tabindex="-1">Contribute</button>
           </div>
           <div class="hub-detail" role="group" aria-label="Detail">
@@ -58,6 +60,23 @@
           <p class="meta hub-source">The roadmap lives in the repository: <a href="https://github.com/ludovic111/horizon/blob/main/ROADMAP.md">ROADMAP.md</a>, generated from <a href="https://github.com/ludovic111/horizon/blob/main/roadmap/roadmap.toml">roadmap/roadmap.toml</a>. Pull requests carry the <code>roadmap:&lt;id&gt;</code> label of their item. <span data-live-note></span></p>
         </div>
 
+        <div class="hub-panel" role="tabpanel" id="board" aria-labelledby="tab-board">
+          <div class="hub-board-head">
+            <p class="hub-intro">Every open issue and pull request, placed by its state on GitHub, as on Kira's work board in Discord.</p>
+            <label class="hub-select"><span class="meta">Show</span><select data-board-item>{{HUB_BOARD_FILTER}}</select></label>
+          </div>
+          <div class="hub-board" data-board>
+{{HUB_BOARD}}
+          </div>
+        </div>
+
+        <div class="hub-panel" role="tabpanel" id="journal" aria-labelledby="tab-journal">
+          <p class="hub-intro">Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as <a href="/hub/journal.json">journal.json</a>.</p>
+          <div class="hub-journal" data-journal>
+{{HUB_JOURNAL}}
+          </div>
+        </div>
+
         <div class="hub-panel" role="tabpanel" id="contribute" aria-labelledby="tab-contribute">
           <section class="hub-block" aria-labelledby="h-first">
             <h2 class="title" id="h-first">Good first tasks</h2>
diff --git a/website/src/hub.js b/website/src/hub.js
index ecfb4da80..cda3b4e5b 100644
--- a/website/src/hub.js
+++ b/website/src/hub.js
@@ -4,6 +4,8 @@
 // twice: `plain` (.hub-plain) for players and `dev` (.hub-dev) for contributors; the page's Simple / Technical
 // switch shows one of them.
 import { escape, inline } from "./markdown.js";
+import { parts, plainItem, sections } from "./releases.js";
+import { isGame, isLauncher } from "./versions.js";
 
 export const REPO = "ludovic111/horizon";
 const issueUrl = (n) => `https://github.com/${REPO}/issues/${n}`;
@@ -173,3 +175,199 @@ export function helpWantedHtml(roadmap) {
     })
     .join("");
 }
+
+// --- The work board --------------------------------------------------------------------------------------------
+
+export const COLUMNS = [
+  { id: "todo", name: "To do", about: "Open and free: pick one, and say so with /claim on Discord." },
+  { id: "progress", name: "In progress", about: "Claimed, assigned, or a draft pull request." },
+  { id: "review", name: "In review", about: "A pull request is ready for review." },
+  { id: "done", name: "Done", about: "Closed or merged in the last seven days." },
+];
+const DONE_DAYS = 7;
+
+// The roadmap item an issue or pull request moves: its roadmap:<id> label, else the item linking it, else (for a
+// pull request) the item linking an issue it fixes.
+export function itemOf(issue, roadmap) {
+  const label = issue.labels.find((l) => l.startsWith("roadmap:"));
+  const ids = new Set(roadmap.items.map((i) => i.id));
+  if (label && ids.has(label.slice(8))) return label.slice(8);
+  const linking = (n) => roadmap.items.find((i) => (i.links || []).includes(`#${n}`))?.id;
+  return linking(issue.n) || issue.fixes.map(linking).find(Boolean) || null;
+}
+
+// The board from GitHub's open issues and pull requests and those closed lately, placed as Kira's work board places
+// them: an issue goes to review when an open, ready pull request fixes it, to progress when a draft one does or it is
+// claimed or assigned; a pull request that fixes no open issue is a card of its own.
+export function boardFrom(list, roadmap, now = Date.now()) {
+  const columns = Object.fromEntries(COLUMNS.map((c) => [c.id, []]));
+  const open = list.filter((i) => i.state === "open");
+  const openIssues = new Set(open.filter((i) => i.kind === "issue").map((i) => i.n));
+  const fixing = (n) => open.filter((p) => p.kind === "pr" && p.fixes.includes(n));
+  const card = (i, prs = []) => ({ n: i.n, kind: i.kind, title: i.title, user: i.user, url: i.url, item: itemOf(i, roadmap) || prs.map((p) => itemOf(p, roadmap)).find(Boolean) || null, prs: prs.map((p) => p.n) });
+  for (const i of open) {
+    if (i.kind === "issue") {
+      const prs = fixing(i.n);
+      const claimed = i.assigned || i.labels.some((l) => /^(in progress|claimed)$/i.test(l));
+      const column = prs.some((p) => !p.draft) ? "review" : prs.length || claimed ? "progress" : "todo";
+      columns[column].push(card(i, prs));
+    } else if (!i.fixes.some((n) => openIssues.has(n))) {
+      columns[i.draft ? "progress" : "review"].push(card(i));
+    }
+  }
+  const since = now - DONE_DAYS * 864e5;
+  const seen = new Set();
+  for (const i of list) {
+    if (seen.has(i.n) || !["merged", "closed"].includes(i.state) || !(Date.parse(i.at) >= since)) continue;
+    seen.add(i.n);
+    columns.done.push(card(i));
+  }
+  columns.done.sort((a, b) => b.n - a.n);
+  return columns;
+}
+
+const SHOWN = 20; // cards per column before "Show more"
+
+function cardHtml(c, roadmap, more) {
+  const item = c.item && roadmap.items.find((i) => i.id === c.item);
+  return `<li class="hub-card" data-item="${escape(c.item || "")}"${more ? " data-more" : ""}><a href="${escape(c.url)}"><span class="hub-card-ref">${c.kind === "pr" ? "PR" : "Issue"} #${c.n}${c.prs.length ? ` · ${c.prs.map((n) => `PR #${n}`).join(", ")}` : ""}</span><span class="hub-card-title">${escape(c.title)}</span><span class="hub-card-meta">${item ? `<span class="hub-card-item">${escape(item.title)}</span>` : ""}${c.user ? `<span>${escape(c.user)}</span>` : ""}</span></a></li>`;
+}
+
+export function boardHtml(columns, roadmap) {
+  return COLUMNS.map(({ id, name, about }) => {
+    const cards = columns[id];
+    return `<section class="hub-column" data-column="${id}" aria-labelledby="col-${id}">
+  <h3 id="col-${id}"><span>${escape(name)}</span><span class="hub-count" data-count>${cards.length}</span></h3>
+  <p class="meta">${escape(about)}</p>
+  <ol class="hub-cards-list">${cards.map((c, i) => cardHtml(c, roadmap, i >= SHOWN)).join("")}</ol>
+  ${cards.length > SHOWN ? `<button type="button" class="button secondary small hub-more" data-more-button>Show ${cards.length - SHOWN} more</button>` : ""}
+</section>`;
+  }).join("\n");
+}
+
+// The board's roadmap filter: every item that has a card.
+export function boardFilterHtml(columns, roadmap) {
+  const used = new Set(Object.values(columns).flat().map((c) => c.item).filter(Boolean));
+  return [`<option value="">Every card</option>`, `<option value="-">Cards of a roadmap item</option>`]
+    .concat(roadmap.items.filter((i) => used.has(i.id)).map((i) => `<option value="${escape(i.id)}">${escape(i.title)}</option>`))
+    .join("");
+}
+
+// --- The journal -----------------------------------------------------------------------------------------------
+
+export const JOURNAL_URL = "https://playhorizon.dev/hub#journal";
+const ENTRIES = 40;
+
+// The journal, newest first: each release with its changes grouped by roadmap item, the weekly summaries
+// (roadmap/journal/), and what merged since the newest game release. releases: GitHub's release objects; list: the
+// hub's issues and pull requests (their roadmap:<id> labels place changes the roadmap doesn't link).
+export function journalFrom(releases, list, roadmap) {
+  const prs = new Map(list.filter((i) => i.kind === "pr").map((i) => [i.n, i]));
+  const placed = (numbers) => {
+    for (const n of numbers) {
+      const known = prs.get(n);
+      const id = known ? itemOf(known, roadmap) : roadmap.items.find((i) => (i.links || []).includes(`#${n}`))?.id;
+      if (id) return id;
+    }
+    return null;
+  };
+  const ours = releases.filter((r) => !r.draft && (isGame(r.tag_name) || isLauncher(r.tag_name)));
+  const entries = ours.map((r) => {
+    const changes = sections(r.body)
+      .filter((x) => /^(new|what's new|fixed)/i.test(x.title))
+      .flatMap((x) => x.items.map((text) => ({ section: /^fixed/i.test(x.title) ? "fixed" : "new", text })))
+      .map((c) => {
+        const numbers = [...c.text.matchAll(/#(\d+)/g)].map((m) => Number(m[1]));
+        return { ...c, text: plainItem(c.text), prs: numbers, item: placed(numbers) };
+      });
+    return {
+      id: r.tag_name,
+      kind: isLauncher(r.tag_name) ? "launcher" : "release",
+      date: r.published_at || "",
+      title: r.name || r.tag_name,
+      plain: parts(r).line,
+      url: r.html_url,
+      changes,
+      shipped: roadmap.items.filter((i) => i.status === "shipped" && i.shipped_in === r.tag_name).map((i) => i.id),
+    };
+  });
+  // Merged but in no release's notes yet: a release is cut from main a while after its last merge, so the newest
+  // releases' notes, not their dates, say what they hold. Pull requests players don't see (skip-release) never are.
+  const games = ours.filter((r) => isGame(r.tag_name)).map((r) => r.published_at).sort().reverse();
+  const since = games[Math.min(4, games.length - 1)] || "";
+  const noted = new Set(entries.flatMap((e) => e.changes.flatMap((c) => c.prs)));
+  const pending = list
+    .filter((i) => i.kind === "pr" && i.state === "merged" && i.at > since && !noted.has(i.n) && !i.labels.includes("skip-release"))
+    .sort((a, b) => b.at.localeCompare(a.at));
+  if (pending.length) {
+    entries.push({
+      id: "next-release",
+      kind: "merged",
+      date: pending[0].at,
+      title: "Merged, in the next release",
+      plain: `${pending.length} change${pending.length === 1 ? "" : "s"} merged since the last release.`,
+      url: `https://github.com/${REPO}/pulls?q=is%3Apr+is%3Amerged`,
+      changes: pending.map((p) => ({ section: "merged", text: p.title, prs: [p.n], item: itemOf(p, roadmap) })),
+      shipped: [],
+    });
+  }
+  for (const w of roadmap.journal || []) {
+    // A week's summary sits after its last day's releases.
+    const end = new Date(Date.parse(w.date) + 7 * 864e5 - 1).toISOString();
+    entries.push({ id: `week-${w.week}`, kind: "week", date: end, title: w.title, plain: w.plain, dev: w.dev, url: `${JOURNAL_URL.replace("#journal", "")}#week-${w.week}`, changes: [], shipped: [] });
+  }
+  return entries.sort((a, b) => b.date.localeCompare(a.date)).slice(0, ENTRIES);
+}
+
+// /hub/journal.json: the journal for Kira's #updates and posts elsewhere, with each shipped item's short text.
+export function journalJson(entries, roadmap, generated = new Date().toISOString()) {
+  const item = (id) => {
+    const i = roadmap.items.find((x) => x.id === id);
+    return i && { id: i.id, title: i.title, plain: i.plain, post: i.post || i.plain };
+  };
+  return {
+    format: "horizon-journal",
+    version: 1,
+    generated,
+    url: JOURNAL_URL,
+    entries: entries.map((e) => ({ ...e, items: [...new Set(e.changes.map((c) => c.item).filter(Boolean))].map(item).filter(Boolean), shipped: e.shipped.map(item).filter(Boolean) })),
+  };
+}
+
+const KIND = { release: "Game", launcher: "Launcher", merged: "Merged", week: "This week" };
+
+function changesHtml(entry, roadmap) {
+  if (!entry.changes.length) return "";
+  const line = (c) => `<li>${inline(c.text)}${c.prs.length ? ` ${c.prs.map((n) => `<a class="hub-ref" href="${issueUrl(n)}">#${n}</a>`).join(" ")}` : ""}</li>`;
+  // Simple: what is new, then how many fixes. Technical: every change, under the roadmap item it moves.
+  const added = entry.changes.filter((c) => c.section !== "fixed");
+  const fixes = entry.changes.length - added.length;
+  const simple = `<div class="hub-plain">${added.length ? `<ul class="hub-changes">${added.map((c) => `<li>${inline(c.text)}</li>`).join("")}</ul>` : ""}${fixes ? `<p class="meta">${added.length ? "And " : ""}${fixes} fix${fixes === 1 ? "" : "es"}.</p>` : ""}</div>`;
+  const groups = new Map();
+  for (const c of entry.changes) groups.set(c.item || "", [...(groups.get(c.item || "") || []), c]);
+  const order = [...groups.keys()].sort((a, b) => (a === "") - (b === ""));
+  const dev = `<div class="hub-dev">${order
+    .map((id) => {
+      const item = roadmap.items.find((i) => i.id === id);
+      return `<p class="hub-group">${item ? `<a href="#item-${escape(id)}">${escape(item.title)}</a>` : "Other changes"}</p><ul class="hub-changes">${groups.get(id).map(line).join("")}</ul>`;
+    })
+    .join("")}</div>`;
+  return simple + dev;
+}
+
+export function journalHtml(entries, roadmap) {
+  return entries
+    .map((e) => {
+      const shipped = e.shipped.map((id) => roadmap.items.find((i) => i.id === id)).filter(Boolean);
+      const items = [...new Set(e.changes.map((c) => c.item).filter(Boolean))].map((id) => roadmap.items.find((i) => i.id === id)).filter(Boolean);
+      return `<article class="hub-entry hub-entry-${e.kind}" id="${e.kind === "week" ? escape(e.id) : `journal-${escape(e.id.replace(/[^\w.-]/g, "-"))}`}">
+  <p class="hub-entry-meta"><span class="badge${e.kind === "release" ? " badge-game" : e.kind === "launcher" ? " badge-launcher" : ""}">${KIND[e.kind]}</span><time datetime="${escape(e.date)}">${escape(e.date.slice(0, 10))}</time></p>
+  <h3 class="hub-entry-title">${e.url ? `<a href="${escape(e.url)}">${escape(e.title)}</a>` : escape(e.title)}</h3>
+  ${e.kind === "week" ? `<p class="hub-plain">${inline(e.plain)}</p><p class="hub-dev">${inline(e.dev.replace(/(^|[^\w[/`])#(\d+)\b/g, (_, b, n) => `${b}[#${n}](${issueUrl(n)})`))}</p>` : ""}
+  ${shipped.length ? `<p class="hub-shipped">Shipped: ${shipped.map((i) => `<a href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join(", ")}</p>` : ""}
+  ${items.length ? `<p class="hub-entry-items hub-plain">${items.map((i) => `<a class="hub-link" href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join("")}</p>` : ""}
+  ${changesHtml(e, roadmap)}
+</article>`;
+    })
+    .join("\n");
+}
diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs
index eb9b8a087..a6337399b 100644
--- a/website/src/hub.test.mjs
+++ b/website/src/hub.test.mjs
@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
-import { fixesIn, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
+import { boardFrom, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
 
 const roadmap = JSON.parse(readFileSync(new URL("../data/roadmap.json", import.meta.url), "utf8"));
 
@@ -53,3 +53,48 @@ test("the overview lists the focus items and never nests links", () => {
   for (const item of roadmap.items.filter((i) => i.focus)) assert.ok(html.includes(`href="#${item.id}"`), item.id);
   for (const row of html.match(/<li class="row">[\s\S]*?<\/li>/g)) assert.equal(row.split("<a ").length, 2, row);
 });
+
+test("the board places issues and pull requests as Kira's board does", () => {
+  const now = Date.parse("2030-01-10T00:00:00Z");
+  const list = [
+    issue(1),
+    issue(2),
+    issue(3, { assignees: [{ login: "x" }] }),
+    pr(10, { body: "Fixes #1" }),
+    pr(11, { body: "Fixes #2", draft: true }),
+    pr(12, { labels: [{ name: `roadmap:${roadmap.items[0].id}` }] }),
+    pr(13, { draft: true }),
+    pr(14, { state: "closed", pull_request: { merged_at: "2030-01-09T00:00:00Z" } }),
+    pr(15, { state: "closed", pull_request: { merged_at: "2029-12-01T00:00:00Z" } }),
+  ].map(slimIssue);
+  const board = boardFrom(list, roadmap, now);
+  const ids = (column) => board[column].map((c) => c.n);
+  assert.deepEqual(ids("todo"), []);
+  assert.deepEqual(ids("progress"), [2, 3, 13]);
+  assert.deepEqual(ids("review"), [1, 12]);
+  assert.deepEqual(ids("done"), [14]);
+  assert.deepEqual(board.review[0].prs, [10]);
+  assert.equal(board.review[1].item, roadmap.items[0].id);
+  assert.equal(itemOf(slimIssue(pr(16, { body: "Fixes #1438" })), roadmap), "end-city-banners");
+});
+
+test("the journal groups a release's changes by roadmap item and lists what awaits a release", () => {
+  const releases = [
+    { tag_name: "v0.2.2", name: "Horizon 0.2.2: Rich presence", published_at: "2030-01-02T00:00:00Z", html_url: "u2", body: "### New\n- Discord Rich Presence (#1787)\n\n### Fixed\n- A fix (#5, fixes #4)\n" },
+    { tag_name: "launcher@0.2.1", name: "Horizon launcher 0.2.1", published_at: "2030-01-01T00:00:00Z", html_url: "u1", body: "### Fixed\n- Window (#6)\n" },
+  ];
+  const list = [
+    pr(1788, { state: "closed", pull_request: { merged_at: "2030-01-03T00:00:00Z" } }),
+    pr(7, { state: "closed", pull_request: { merged_at: "2030-01-03T00:00:00Z" }, labels: [{ name: "skip-release" }] }),
+  ].map(slimIssue);
+  const entries = journalFrom(releases, list, { ...roadmap, journal: [] });
+  assert.deepEqual(entries.map((e) => e.id), ["next-release", "v0.2.2", "launcher@0.2.1"]);
+  assert.deepEqual(entries[0].changes.map((c) => [c.prs, c.item]), [[[1788], "discord-presence"]]);
+  assert.deepEqual(entries[1].changes.map((c) => [c.section, c.text, c.item]), [["new", "Discord Rich Presence", "discord-presence"], ["fixed", "A fix", null]]);
+  const json = journalJson(entries, roadmap, "now");
+  assert.equal(json.format, "horizon-journal");
+  assert.equal(json.entries[1].items[0].post.length <= 240, true);
+  const html = journalHtml(entries, roadmap);
+  assert.ok(html.includes('href="#item-discord-presence"'));
+  assert.ok(html.includes("And 1 fix."));
+});
diff --git a/website/src/style.css b/website/src/style.css
index 4ec688812..f32e24a30 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -783,7 +783,46 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 .hub-rules li + li { margin-top: 10px; }
 .hub-rules li::marker { color: var(--muted); font-family: var(--mono); }
 .hub-source { margin-top: 40px; max-width: var(--measure); }
+.hub-board-head { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 12px 24px; }
+.hub-board-head .hub-intro { margin-bottom: 0; }
+.hub-select { display: inline-flex; align-items: center; gap: 10px; }
+.hub-select select {
+  height: 32px; max-width: 22rem; padding: 0 10px; font: var(--text-label) / 1 var(--font); color: var(--ink);
+  background: var(--well); border: 0; box-shadow: 0 0 0 var(--block-outline) var(--outline);
+}
+.hub-board { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px; margin-top: 24px; align-items: start; }
+.hub-column { padding: 14px; background: var(--panel); border: var(--block-outline) solid var(--outline); box-shadow: var(--panel-edges); }
+.hub-column h3 { display: flex; justify-content: space-between; align-items: baseline; font-size: var(--text-heading); }
+.hub-count { font: var(--text-micro) / 1 var(--mono); color: var(--muted); }
+.hub-column > .meta { margin: 6px 0 12px; }
+.hub-cards-list { display: grid; gap: 6px; }
+.js .hub-column:not(.is-open) .hub-card[data-more] { display: none; }
+.hub-card a { display: grid; gap: 4px; padding: 10px 12px; background: var(--well); box-shadow: 0 0 0 var(--block-outline) var(--outline); color: var(--ink); }
+.hub-card a:hover { box-shadow: 0 0 0 var(--block-outline) var(--accent); }
+.hub-card-ref, .hub-card-meta { font: var(--text-micro) / 1.4 var(--mono); letter-spacing: var(--text-micro-tracking); color: var(--muted); }
+.hub-card-title { font-size: var(--text-label); line-height: 1.4; overflow-wrap: anywhere; }
+.hub-card-meta { display: flex; flex-wrap: wrap; gap: 4px 10px; }
+.hub-card-item { color: var(--accent); }
+.hub-more { margin-top: 10px; width: 100%; justify-content: center; }
+.hub-journal { display: grid; gap: 8px; margin-top: 24px; max-width: 56rem; }
+.hub-entry { display: grid; gap: 10px; padding: 18px 20px; background: var(--panel); border: var(--block-outline) solid var(--outline); box-shadow: var(--panel-edges); scroll-margin-top: calc(var(--nav) + 24px); }
+.hub-entry-week { background: color-mix(in srgb, var(--accent) 8%, var(--panel)); }
+.hub-entry-meta { display: flex; align-items: center; gap: 10px; font: var(--text-micro) / 1 var(--mono); color: var(--muted); }
+.hub-entry-meta .badge { margin-right: 0; }
+.hub-entry-title { font-size: var(--text-heading); line-height: var(--text-heading-line); }
+.hub-entry-title a { color: var(--ink); }
+.hub-entry-title a:hover { color: var(--accent); }
+.hub-entry .hub-plain, .hub-entry .hub-dev { font-size: var(--text-ui); color: var(--ink-soft); }
+.hub-entry-items { display: flex; flex-wrap: wrap; gap: 6px; }
+.hub-shipped { font-size: var(--text-ui); color: var(--ink); }
+.hub-changes { list-style: square; padding-left: 18px; font-size: var(--text-ui); color: var(--ink-soft); }
+.hub-changes li + li { margin-top: 4px; }
+.hub-ref { font: var(--text-micro) / 1 var(--mono); }
+.hub-group { margin-top: 8px; font: 500 var(--text-label) / 1.4 var(--font); }
+.hub-group:first-child { margin-top: 0; }
+@media (max-width: 1100px) { .hub-board { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
 @media (max-width: 720px) {
+  .hub-board { grid-template-columns: minmax(0, 1fr); }
   .hub-rows .row > a { grid-template-columns: var(--index) minmax(0, 1fr); }
   .hub-rows .row-meta { grid-column: 2; text-align: left; }
 }

From 0481dbdb81e49134f42dccafb58474504466a440 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:10:56 +0100
Subject: [PATCH 106/270] Make hardcore players spectators when they respawn

A hardcore death offered another survival life. Vanilla's death screen
says Spectate in hardcore, and the server makes the respawned player a
spectator (ServerGamePacketListenerImpl.handleClientCommand). Do the
same on the server and in the in-frame world, and add a harness that
compares a hardcore respawn on a dedicated server with vanilla's.
---
 crates/horizon-client/src/game/agent.rs       |   8 +-
 crates/horizon-client/src/game/lan_actions.rs |   5 +
 crates/horizon-client/src/game/screens.rs     |  27 +++-
 .../horizonlab/parity/LocatorBarClient.java   |   6 +-
 tools/test_hardcore_respawn_parity.py         | 139 ++++++++++++++++++
 5 files changed, 177 insertions(+), 8 deletions(-)
 create mode 100644 tools/test_hardcore_respawn_parity.py

diff --git a/crates/horizon-client/src/game/agent.rs b/crates/horizon-client/src/game/agent.rs
index f6b68aa74..b85710146 100644
--- a/crates/horizon-client/src/game/agent.rs
+++ b/crates/horizon-client/src/game/agent.rs
@@ -1598,8 +1598,12 @@ impl Game<'_> {
                 if self.screen != Screen::Dead {
                     return Err("respawn needs the death screen".into());
                 }
-                let label =
-                    horizon_client::text::Text::translate("deathScreen.respawn", &[]).plain();
+                let key = if self.level.hardcore {
+                    "deathScreen.spectate"
+                } else {
+                    "deathScreen.respawn"
+                };
+                let label = horizon_client::text::Text::translate(key, &[]).plain();
                 let w = widgets::find(&widgets::last(), &label)?;
                 if !w.enabled {
                     // DeathScreen enables its buttons after 20 ticks.
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..2942bea7d 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1649,6 +1649,11 @@ impl Game<'_> {
             border: &self.border,
         };
         host.hub.respawn(i, spawn, &ctx);
+        // ServerGamePacketListenerImpl.handleClientCommand: a hardcore world's
+        // respawned player only watches.
+        if self.level.hardcore {
+            host.hub.set_game_mode(conn, SPECTATOR);
+        }
         if let Some(config) = elsewhere {
             self.respawn_trip(conn, config);
         }
diff --git a/crates/horizon-client/src/game/screens.rs b/crates/horizon-client/src/game/screens.rs
index cf1f3269f..5fa040665 100644
--- a/crates/horizon-client/src/game/screens.rs
+++ b/crates/horizon-client/src/game/screens.rs
@@ -2,6 +2,7 @@
 use super::{Game, Screen};
 use horizon_client::{
     Result,
+    command::args::GameMode,
     hud::{HudBatch, rgba},
     text::{self, Text},
     ui,
@@ -81,9 +82,15 @@ fn pause_icons(w: f32, h: f32) -> [(f32, f32, &'static str); 4] {
         (x0 + 72.0, y, "gui/sprites/pause_menu/player_reporting"),
     ]
 }
-fn death_buttons(w: f32, h: f32) -> [(f32, f32, &'static str, u8); 2] {
+/// DeathScreen.init: a hardcore player can only spectate.
+fn death_buttons(w: f32, h: f32, hardcore: bool) -> [(f32, f32, &'static str, u8); 2] {
+    let respawn = if hardcore {
+        "deathScreen.spectate"
+    } else {
+        "deathScreen.respawn"
+    };
     [
-        (w / 2.0 - 100.0, h / 4.0 + 72.0, "deathScreen.respawn", 0),
+        (w / 2.0 - 100.0, h / 4.0 + 72.0, respawn, 0),
         (
             w / 2.0 - 100.0,
             h / 4.0 + 96.0,
@@ -223,7 +230,12 @@ impl Game<'_> {
                 ),
             );
         }
-        let title = Text::translate("deathScreen.title", &[]);
+        let title = if self.level.hardcore {
+            "deathScreen.title.hardcore"
+        } else {
+            "deathScreen.title"
+        };
+        let title = Text::translate(title, &[]);
         let tw = atlas.font.width_text(&title);
         ui::text_scaled(
             batch,
@@ -258,7 +270,7 @@ impl Game<'_> {
             .ui
             .died_at
             .is_none_or(|t| t.elapsed().as_millis() >= 1000);
-        for (x, y, key, _) in death_buttons(w, h) {
+        for (x, y, key, _) in death_buttons(w, h, self.level.hardcore) {
             let hover = active && ui::hovered(self.cursor, x, y, 200.0, 20.0);
             ui::button(
                 batch,
@@ -286,7 +298,7 @@ impl Game<'_> {
             .as_ref()
             .map_or([1, 1], |r| [r.config.width, r.config.height]);
         let b = HudBatch::new(size);
-        let hit = death_buttons(b.width, b.height)
+        let hit = death_buttons(b.width, b.height, self.level.hardcore)
             .into_iter()
             .find(|d| ui::hovered(self.cursor, d.0, d.1, 200.0, 20.0))
             .map(|d| d.3);
@@ -330,6 +342,11 @@ impl Game<'_> {
             Some(1) => self.close_world()?,
             _ => {}
         }
+        // ServerGamePacketListenerImpl.handleClientCommand: a hardcore world's
+        // respawned player only watches.
+        if hit == Some(0) && self.remote.is_none() && self.level.hardcore {
+            self.set_mode(GameMode::Spectator);
+        }
         if hit.is_some() {
             self.audio.play_button_click();
         }
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
index 76a951894..3bed808f6 100644
--- a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
@@ -84,7 +84,9 @@ import net.minecraft.world.phys.Vec3;
  * still), {@code sync NAME} (runs {@code time query gametime}, whose reply is
  * not recorded, and prints {@code synced NAME} once it is back: the server has
  * handled everything this player sent before, and everything the server sent
- * this player before the reply has been recorded), {@code quit NAME}, {@code
+ * this player before the reply has been recorded), {@code respawn NAME} (the
+ * death screen's button, ServerboundClientCommandPacket PERFORM_RESPAWN),
+ * {@code quit NAME}, {@code
  * players on|off} (whether each player also records the other players added
  * to and removed from its level, and its own respawns into a dimension),
  * {@code chat on|off} (whether the system chat each player receives is
@@ -130,6 +132,8 @@ public final class LocatorBarClient {
                         players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundPlayerAbilitiesPacket(abilities));
                     }
                     case "still" -> players.get(w[1]).still();
+                    case "respawn" -> players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundClientCommandPacket(
+                        net.minecraft.network.protocol.game.ServerboundClientCommandPacket.Action.PERFORM_RESPAWN));
                     case "sync" -> {
                         try {
                             players.get(w[1]).sync();
diff --git a/tools/test_hardcore_respawn_parity.py b/tools/test_hardcore_respawn_parity.py
new file mode 100644
index 000000000..6e0669534
--- /dev/null
+++ b/tools/test_hardcore_respawn_parity.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Respawning in a hardcore world on a dedicated server, against vanilla's, seen by a vanilla client.
+
+A vanilla dedicated server and Horizon's (`horizon-client --dedicated --nogui`) each serve a copy of one hardcore
+flat world vanilla generated first, with Alice an operator in survival. LocatorBarClient (a player made of
+vanilla's protocol code) joins, runs /kill on itself and presses the death screen's button
+(ServerboundClientCommandPacket PERFORM_RESPAWN). Vanilla's ServerGamePacketListenerImpl.handleClientCommand
+respawns the player, then makes it a spectator because the server is hardcore. The game mode changes and respawns
+Alice is sent in the death and respawn steps are compared exactly.
+"""
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+import time
+
+try:
+    from . import lab, test_rust_parity as base, test_locator_bar_parity as locator
+    from .test_dedicated_server_parity import Server
+except ImportError:
+    import lab
+    import test_rust_parity as base
+    import test_locator_bar_parity as locator
+    from test_dedicated_server_parity import Server
+
+NAME = 'hardcore-respawn-parity'
+# server_dir and generate_world write these server.properties.
+locator.PROPERTIES = dict(locator.PROPERTIES, hardcore='true', gamemode='survival')
+SCRIPT = [
+    ('death', ['cmd Alice kill @s']),
+    ('respawn', ['respawn Alice']),
+]
+STEP_SECONDS = 4.0
+SHOWN = ('gamemode', 'respawn')
+
+
+def run_side(label, server_command, client_command, build, world):
+    directory = build / label
+    port = locator.server_dir(directory, world)
+    out = build / f'{label}.txt'
+    out.unlink(missing_ok=True)
+    server = Server(server_command, directory, label)
+    try:
+        server.wait_for(r'Done \(')
+        with (build / f'{label}-client.log').open('w') as log:
+            client = subprocess.Popen([*map(str, client_command), '127.0.0.1', str(port), str(out)],
+                                      cwd=lab.ROOT, stdin=subprocess.PIPE, stdout=log, stderr=subprocess.STDOUT,
+                                      text=True)
+
+            def tell(line):
+                client.stdin.write(line + '\n')
+                client.stdin.flush()
+            try:
+                tell('players on')
+                tell('state on')
+                tell('step joins')
+                tell('join Alice')
+                server.wait_for(r'Alice joined the game', timeout=120)
+                time.sleep(STEP_SECONDS)
+                for step, actions in SCRIPT:
+                    tell(f'step {step}')
+                    for action in actions:
+                        tell(action)
+                    time.sleep(STEP_SECONDS)
+                tell('end')
+                client.wait(timeout=60)
+            finally:
+                if client.poll() is None:
+                    client.kill()
+    finally:
+        server.stop()
+    if not out.exists():
+        raise AssertionError(f'{label}: the client wrote no transcript (see {build}/{label}-client.log)')
+    return out.read_text(encoding='utf-8').splitlines()
+
+
+def shown(lines):
+    """Alice's game mode changes and respawns in the death and respawn steps."""
+    keep = []
+    for line in lines:
+        parts = line.split(' ', 3)
+        if len(parts) >= 3 and parts[1] in ('step=death', 'step=respawn') and parts[2] in SHOWN:
+            keep.append(line)
+    return keep
+
+
+def main():
+    lock, jars, libraries = base.verify_artifacts()
+    build = lab.LOCAL / NAME
+    build.mkdir(parents=True, exist_ok=True)
+    report = build / 'report.json'
+    report.unlink(missing_ok=True)
+    oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java'
+    classes = build / 'classes'
+    shutil.rmtree(classes, ignore_errors=True)
+    classes.mkdir()
+    dependencies = os.pathsep.join(map(str, [jars['server'], *libraries]))
+    subprocess.run(['javac', '--release', str(lock['minecraft']['java_major']), '-proc:none', '-nowarn', '-sourcepath',
+                    lab.ROOT / 'mods/horizon/src/test/java', '-cp', dependencies, '-d', classes, oracle],
+                   cwd=lab.ROOT, check=True, capture_output=True)
+    subprocess.run(['cargo', 'build', '--release', '-p', 'horizon-client', '--bin', 'horizon-client'], cwd=lab.ROOT,
+                   check=True, capture_output=True)
+    metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--no-deps', '--format-version', '1'],
+                                                  cwd=lab.ROOT, text=True))
+    binary = Path(metadata['target_directory']) / 'release' / ('horizon-client.exe' if os.name == 'nt' else 'horizon-client')
+    vanilla_server = ['java', '-Xmx2g', '-Duser.timezone=UTC', '-cp', dependencies, 'net.minecraft.server.Main', 'nogui']
+    horizon_server = [binary, '--resources', lab.LOCAL / 'horizon-client/26.3', '--dedicated', '--nogui']
+    client = ['java', '-Xmx1g', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.LocatorBarClient']
+
+    world = locator.generate_world(vanilla_server, build)
+    vanilla_all = run_side('vanilla', vanilla_server, client, build, world)
+    horizon_all = run_side('horizon', horizon_server, client, build, world)
+    errors = [l for l in vanilla_all + horizon_all if ' error ' in f' {l} ' or 'disconnected' in l]
+    vanilla, horizon = shown(vanilla_all), shown(horizon_all)
+    if errors or vanilla != horizon:
+        import difflib
+        diff = '\n'.join(difflib.unified_diff(vanilla, horizon, 'vanilla', 'horizon', n=1, lineterm=''))
+        raise AssertionError(f'{len(errors)} errors, transcripts differ (see {build}/vanilla.txt and horizon.txt):\n'
+                             + '\n'.join(errors[:10]) + '\n' + diff[:6000])
+    if 'Alice step=respawn gamemode 3' not in vanilla:
+        raise AssertionError(f'vanilla did not make the respawned player a spectator: the script did not run '
+                             f'(see {build})')
+    lab.write_json(report, dict(
+        schema=1, minecraft=lock['minecraft']['version'], platform=platform.platform(),
+        java=subprocess.check_output(['java', '--version'], text=True).splitlines()[0],
+        lines=len(vanilla), output_sha256=lab.digest(build / 'horizon.txt', 'sha256'),
+        scope='A player dying and respawning in a hardcore world on a dedicated server: the respawn and the game '
+              'mode it is sent (spectator).'))
+    print(f'hardcore respawn: {len(vanilla)} lines identical')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except AssertionError as error:
+        sys.exit(f'{NAME}: {error}')

From f48cfb79661b9181ed62435e5009f1cd2bfc0543 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:48:47 +0100
Subject: [PATCH 107/270] Let /ride mount and dismount mob riders

/ride now looks up a mob's vehicle as well as the player's, so mobs
can mount mobs, get the already-riding and loop errors, and dismount
to the vehicle's dismount spot. execute on vehicle uses the same
lookup. The command_exec corpus gets a mob riding group.
---
 .../src/game/commands/execute.rs              |  5 +-
 .../src/game/commands/world_cmds.rs           | 88 +++++++++++++++----
 tools/command_exec_corpus.py                  | 26 ++++++
 3 files changed, 100 insertions(+), 19 deletions(-)

diff --git a/crates/horizon-client/src/game/commands/execute.rs b/crates/horizon-client/src/game/commands/execute.rs
index 463cd542e..3f7e4c2a0 100644
--- a/crates/horizon-client/src/game/commands/execute.rs
+++ b/crates/horizon-client/src/game/commands/execute.rs
@@ -606,10 +606,7 @@ impl Game<'_> {
                     .collect(),
                 _ => Vec::new(),
             },
-            Some("vehicle") => match entity {
-                Target::Player => self.riding.map(Target::Mob).into_iter().collect(),
-                _ => Vec::new(),
-            },
+            Some("vehicle") => self.ride_vehicle(entity).into_iter().collect(),
             Some("controller") | Some("passengers") => match entity {
                 Target::Mob(id) if self.mobs.iter().any(|m| m.id == id && m.rider.is_some()) => {
                     vec![Target::Player]
diff --git a/crates/horizon-client/src/game/commands/world_cmds.rs b/crates/horizon-client/src/game/commands/world_cmds.rs
index 2f3792a57..c8bd220be 100644
--- a/crates/horizon-client/src/game/commands/world_cmds.rs
+++ b/crates/horizon-client/src/game/commands/world_cmds.rs
@@ -1074,15 +1074,15 @@ impl Game<'_> {
         };
         let name = self.target_name(target);
         if id == "ride.dismount" {
-            let vehicle = match target {
-                Target::Player => self.riding.map(Target::Mob),
-                _ => None,
-            };
-            let Some(v) = vehicle else {
+            let Some(v) = self.ride_vehicle(target) else {
                 return Err(err("commands.ride.not_riding", &[&name.plain()]));
             };
             let vehicle_name = self.target_name(v);
-            self.dismount_mount();
+            match target {
+                Target::Player => self.dismount_mount(),
+                Target::Mob(rider) => self.dismount_mob(rider),
+                _ => {}
+            }
             self.feedback(Text::translate(
                 "commands.ride.dismount.success",
                 &[name, vehicle_name],
@@ -1094,11 +1094,8 @@ impl Game<'_> {
             return Ok(0);
         };
         let vehicle_name = self.target_name(vehicle);
-        if target == Target::Player && self.riding.is_some() {
-            let current = self
-                .riding
-                .map(Target::Mob)
-                .map_or_else(Text::empty, |v| self.target_name(v));
+        if let Some(current) = self.ride_vehicle(target) {
+            let current = self.target_name(current);
             return Err(err(
                 "commands.ride.already_riding",
                 &[&name.plain(), &current.plain()],
@@ -1107,22 +1104,42 @@ impl Game<'_> {
         if vehicle == Target::Player {
             return Err(err("commands.ride.mount.failure.cant_ride_players", &[]));
         }
-        if target == vehicle {
-            return Err(err("commands.ride.mount.failure.loop", &[]));
+        // getSelfAndPassengers: the vehicle is the target or rides it.
+        let mut up = Some(vehicle);
+        while let Some(v) = up {
+            if v == target {
+                return Err(err("commands.ride.mount.failure.loop", &[]));
+            }
+            up = self.ride_vehicle(v);
         }
-        // The player can ride mobs that carry a rider.
+        // Players and mobs can ride mobs.
         let Target::Mob(mob_id) = vehicle else {
             return Err(err(
                 "commands.ride.mount.failure.generic",
                 &[&name.plain(), &vehicle_name.plain()],
             ));
         };
-        if target != Target::Player || !self.mobs.iter().any(|m| m.id == mob_id && m.alive()) {
+        let rider = match target {
+            Target::Mob(id) => Some(id),
+            _ => None,
+        };
+        if !(target == Target::Player || rider.is_some())
+            || !self.mobs.iter().any(|m| m.id == mob_id && m.alive())
+        {
             return Err(err(
                 "commands.ride.mount.failure.generic",
                 &[&name.plain(), &vehicle_name.plain()],
             ));
         }
+        if let Some(rider) = rider {
+            // Entity.startRiding.
+            self.mount_mob(rider, mob_id);
+            self.feedback(Text::translate(
+                "commands.ride.mount.success",
+                &[name, vehicle_name],
+            ));
+            return Ok(1);
+        }
         if let Some(m) = self.mobs.iter_mut().find(|m| m.id == mob_id) {
             m.extra.flag = false;
             m.extra.counter = 0;
@@ -1138,6 +1155,47 @@ impl Game<'_> {
         Ok(1)
     }
 
+    /// Entity.getVehicle: the player's mount, or a mob's.
+    pub(super) fn ride_vehicle(&self, t: Target) -> Option<Target> {
+        let id = match t {
+            Target::Player => return self.riding.map(Target::Mob),
+            Target::Mob(id) => self.mobs.iter().find(|m| m.id == id)?.extra.mount?,
+            _ => return None,
+        };
+        Some(if self.boats.iter().any(|b| b.id == id) {
+            Target::Boat(id)
+        } else {
+            Target::Mob(id)
+        })
+    }
+    /// LivingEntity.stopRiding for a mob: off its vehicle
+    /// (Entity.removePassenger), then to where the vehicle lets it out
+    /// (LivingEntity.dismountVehicle).
+    fn dismount_mob(&mut self, rider: u32) {
+        let Some(i) = self.mobs.iter().position(|m| m.id == rider) else {
+            return;
+        };
+        let Some(v) = self.mobs[i].extra.mount.take() else {
+            return;
+        };
+        let (width, yaw) = (f64::from(self.mobs[i].width()), self.mobs[i].yaw);
+        let at = if let Some(b) = self.boats.iter().position(|b| b.id == v) {
+            self.boat_dismount_target(b, width, yaw)
+        } else if let Some(m) = self.mobs.iter_mut().find(|m| m.id == v) {
+            m.extra.rider = None;
+            // Entity.getDismountLocationForPassenger: on top of the vehicle.
+            let p = m.position;
+            horizon_core::geometry::Vec3::new(p.x, p.y + f64::from(m.height()), p.z)
+        } else {
+            self.mobs[i].position
+        };
+        let m = &mut self.mobs[i];
+        m.extra.passenger = false;
+        m.extra.boarding_cooldown = 60;
+        m.position = at;
+        m.previous = at;
+    }
+
     // ---- /spreadplayers -----------------------------------------------------------------------
 
     pub(super) fn cmd_spreadplayers(&mut self, ctx: &Context) -> R<i32> {
diff --git a/tools/command_exec_corpus.py b/tools/command_exec_corpus.py
index 0e376e260..ba03fc817 100644
--- a/tools/command_exec_corpus.py
+++ b/tools/command_exec_corpus.py
@@ -327,6 +327,31 @@ def riding_teleport():
                               '/tp @s 8.5 230 8.5 0 0')
 
 
+def mob_riding():
+    """Mobs mount and dismount mobs with /ride, NBT passengers included (#1520)."""
+    rider, vehicle = '@e[tag=ride_r,limit=1]', '@e[tag=ride_v,limit=1]'
+    return [
+        *setup('/summon minecraft:cow 4.5 220 12.5 {NoAI:1b,NoGravity:1b,Tags:["ride_v"]}',
+               '/summon minecraft:pig 6.5 220 12.5 {NoAI:1b,NoGravity:1b,Tags:["ride_r"]}'),
+        cmd(f'/ride {rider} dismount'),
+        cmd(f'/ride {rider} mount @s'),
+        cmd(f'/ride {rider} mount {rider}'),
+        cmd(f'/ride {rider} mount {vehicle}'),
+        cmd(f'/ride {rider} mount {vehicle}'),
+        cmd(f'/ride {vehicle} mount {rider}'),
+        cmd('/execute as @e[tag=ride_r] on vehicle run say carrying'),
+        cmd(f'/ride {rider} dismount'),
+        cmd(f'/data get entity {rider} Pos'),
+        cmd('/execute as @e[tag=ride_r] on vehicle run say still carrying'),
+        *setup('/kill @e[tag=ride_r]', '/kill @e[tag=ride_v]'),
+        *setup('/summon minecraft:cow 4.5 220 12.5 {NoAI:1b,NoGravity:1b,Tags:["ride_v"],'
+               'Passengers:[{id:"minecraft:pig",NoAI:1b,NoGravity:1b,Tags:["ride_r"]}]}'),
+        cmd(f'/ride {rider} dismount'),
+        cmd(f'/data get entity {rider} Pos'),
+        *setup('/kill @e[tag=ride_r]', '/kill @e[tag=ride_v]'),
+    ]
+
+
 def scores():
     return [
         cmd('/scoreboard objectives add harness dummy'),
@@ -1017,6 +1042,7 @@ def groups():
         ('blocks and border', world_blocks()),
         ('entities', entities()),
         ('riding teleport', riding_teleport()),
+        ('mob riding', mob_riding()),
         ('scores, teams and bossbars', scores()),
         ('execute', execute()),
         ('levels', levels()),

From 436c2fefb47d16e33b0e13ad2218dc731ec43afe Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:40:05 +0100
Subject: [PATCH 108/270] Freeze server-thread players in powder snow

With the server thread, the host's copy of a player never set isInPowderSnow from the blocks along its moves and never ran LivingEntity.aiStep's freezing, so a frozen player took no freezing damage and the client's own damage was overwritten. Record powder snow's FREEZE on the server path and run the freezing countdown and its damage every 40 ticks there. The guest's freeze-immune armor now comes from its worn armor, as for the local player.
---
 crates/horizon-client/src/game.rs             | 24 ++++++++++--------
 crates/horizon-client/src/game/lan_actions.rs |  2 ++
 crates/horizon-client/src/motion.rs           | 25 ++++++++++++++++---
 3 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..4e4865c7a 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1844,6 +1844,19 @@ impl Game<'_> {
     /// (decreaseAirSupply), the wings, leather boots on powder snow
     /// (PowderSnowBlock.canEntityWalkOnPowderSnow), freeze-immune wear
     /// (LivingEntity.canFreeze) and the dimension's FAST_LAVA.
+    /// `LivingEntity.canFreeze`'s armor half: any worn piece in
+    /// `freeze_immune_wearables`.
+    pub(crate) fn wears_freeze_immune(&self) -> bool {
+        let immune = self
+            .res
+            .items()
+            .item_tags
+            .get("minecraft:freeze_immune_wearables");
+        self.armor
+            .iter()
+            .flatten()
+            .any(|s| immune.is_some_and(|t| t.contains(&*s.item)))
+    }
     pub(crate) fn sync_player_body(&mut self) {
         let glider = self.glider_worn();
         let item_use_speed = self
@@ -1863,16 +1876,7 @@ impl Game<'_> {
         let leather_boots = self.armor[3]
             .as_ref()
             .is_some_and(|s| &*s.item == "minecraft:leather_boots");
-        let immune = self
-            .res
-            .items()
-            .item_tags
-            .get("minecraft:freeze_immune_wearables");
-        let freeze_immune = self
-            .armor
-            .iter()
-            .flatten()
-            .any(|s| immune.is_some_and(|t| t.contains(&*s.item)));
+        let freeze_immune = self.wears_freeze_immune();
         let Some(player) = self.player.as_mut() else {
             return;
         };
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..10307dca3 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1942,6 +1942,7 @@ impl Game<'_> {
         let events = self.as_guest(host, conn, |game| {
             let (rules, motion) = (game.world.health_rules, game.motion);
             let health = &motion.health;
+            let freeze_immune = game.wears_freeze_immune();
             let Some(player) = game.player.as_mut() else {
                 return (Vec::new(), None);
             };
@@ -2005,6 +2006,7 @@ impl Game<'_> {
             // Entity.applyEffectsFromBlocks along those moves: magma, cactus,
             // lit campfires and grown sweet berry bushes hurt (#1305).
             w.player.shift_key_down = sneaking;
+            w.player.freeze_immune = freeze_immune;
             let _ = w.server_block_damage(start);
             let _ = w.tick_environment_damage();
             let _ = w.apply_fire_contact();
diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs
index 560cadc80..e7809055d 100644
--- a/crates/horizon-client/src/motion.rs
+++ b/crates/horizon-client/src/motion.rs
@@ -1083,11 +1083,26 @@ impl MotionWorld<'_, '_, '_> {
     }
     /// What `applyEffectsFromBlocks` does to a server's player along the
     /// moves its client sent since `from` (in its history): the damage of
-    /// magma, cactus, lit campfires and grown sweet berry bushes. Its client
-    /// moves it, so the slowing and the rest are the client's.
+    /// magma, cactus, lit campfires and grown sweet berry bushes, and powder
+    /// snow's FREEZE, then `LivingEntity.aiStep`'s freezing and its damage.
+    /// Its client moves it, so the slowing and the rest are the client's.
     pub fn server_block_damage(&mut self, from: Vec3) -> Result<()> {
         self.player.old_position = from;
-        self.effects_from_blocks(true)
+        // Entity.baseTick
+        self.player.was_in_powder_snow = self.player.in_powder_snow;
+        self.player.in_powder_snow = false;
+        self.effects_from_blocks(true)?;
+        // LivingEntity.aiStep "freezing" (server).
+        if !self.player.in_powder_snow || !self.player.can_freeze() {
+            self.player.ticks_frozen = (self.player.ticks_frozen - 2).max(0);
+        }
+        if self.player.health.tick_count % 40 == 0
+            && self.player.is_fully_frozen()
+            && self.player.can_freeze()
+        {
+            self.freeze_damage()?;
+        }
+        Ok(())
     }
     fn effects_from_blocks(&mut self, damage_only: bool) -> Result<()> {
         use horizon_world::entity_move::MovementRecord;
@@ -1191,7 +1206,7 @@ impl MotionWorld<'_, '_, '_> {
                 groups += 1;
                 last_step = step;
             }
-            if groups == 1 {
+            if groups == 1 && !damage_only {
                 // A later group finds the fire already out.
                 self.player.powder_snow_entered.push(p);
             }
@@ -1316,6 +1331,8 @@ impl MotionWorld<'_, '_, '_> {
                     "minecraft:sweet_berry_bush" if damage_only => {
                         self.sweet_berry_bush_damage(state)?;
                     }
+                    // PowderSnowBlock.entityInside's FREEZE.
+                    "minecraft:powder_snow" if damage_only => entered.push((step, p)),
                     _ => {}
                 }
                 if damage_only {

From e458e3724924360dfad1252358368ff090cc4dae Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:02:36 +0100
Subject: [PATCH 109/270] Hub: journal.json in the flat format Kira reads, at
 /data/journal.json

One entry per merged pull request (with its roadmap item), game or launcher
release, shipped roadmap item (post and announce) and weekly summary, newest
first, ids stable forever: the feed kira's src/journal.js posts to #updates and
X. The journal's item links are hub#<id>; the board's and the journal's ids are
reserved too, and the page-wide unique-id test covers every tab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 roadmap/README.md        | 36 ++++++++++++------
 tools/roadmap.py         |  2 +-
 website/README.md        |  2 +-
 website/build.mjs        |  2 +-
 website/src/hub.html     |  2 +-
 website/src/hub.js       | 79 ++++++++++++++++++++++++++++++++--------
 website/src/hub.test.mjs | 51 +++++++++++++++++++++++---
 7 files changed, 136 insertions(+), 38 deletions(-)

diff --git a/roadmap/README.md b/roadmap/README.md
index f16e83f8c..55cf9d09f 100644
--- a/roadmap/README.md
+++ b/roadmap/README.md
@@ -53,7 +53,7 @@ Whoever moves the work (the orchestrator on each heartbeat, or anyone in their p
 5. Once a week, write the week's summary in `roadmap/journal/<year>-<ISO week>.md` (for example
    `2026-43.md`): `# Title`, a paragraph or two for players, then `## Technical` and the same week for
    contributors, with its pull requests. `build` puts it into website/data/roadmap.json; the hub's Journal tab
-   shows it among the releases, and `/hub/journal.json` carries it to Kira's #updates and to posts elsewhere.
+   shows it among the releases, and `/data/journal.json` carries it to Kira's #updates and to X.
 6. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
    item in a normal pull request; none is published automatically.
 
@@ -62,18 +62,30 @@ or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs
 
 ## The journal
 
-The hub's Journal tab and `https://playhorizon.dev/hub/journal.json` are built with each deploy of the website
-(`website/src/hub.js`, `journalFrom`): every game and launcher release with its notes' changes, each placed under
-the roadmap item it moves (the pull request's `roadmap:<id>` label, else the item that links it); the merged pull
-requests no release has yet; and the weekly summaries above. Its JSON, newest first:
+The hub's Journal tab and `https://playhorizon.dev/data/journal.json` are built with each deploy of the website
+(`website/src/hub.js`). The tab shows every game and launcher release with its notes' changes, each placed under
+the roadmap item it moves (the pull request's `roadmap:<id>` label, else the item that links it), the merged pull
+requests no release has yet, and the weekly summaries above.
+
+`journal.json` is what Kira reads for `#updates` and its X posts (kira's `src/journal.js`): one flat entry per
+merged pull request, release, shipped item and weekly summary, newest first, the latest 300.
 
 ```json
-{ "format": "horizon-journal", "version": 1, "generated": "…", "url": "https://playhorizon.dev/hub#journal",
-  "entries": [ { "id": "v0.2.57", "kind": "release | launcher | merged | week", "date": "…", "title": "…",
-                 "plain": "one line for players", "url": "…", "dev": "weeks only",
-                 "changes": [ { "section": "new | fixed | merged", "text": "…", "prs": [1787], "item": "discord-presence" } ],
-                 "items": [ { "id", "title", "plain", "post" } ],      // roadmap items the entry moved
-                 "shipped": [ { "id", "title", "plain", "post" } ] } ] } // items that shipped in this release
+{ "format": "horizon-journal", "version": 2, "generated": "…", "url": "https://playhorizon.dev/hub#journal",
+  "entries": [
+    { "id": "pr-1788", "kind": "merge", "date": "…", "title": "the pull request's title", "url": "…",
+      "number": 1788, "item": "discord-presence", "item_title": "Discord Rich Presence" },
+    { "id": "release-v0.2.57", "kind": "release", "date": "…", "title": "…", "plain": "one line", "url": "…",
+      "tag": "v0.2.57" },
+    { "id": "shipped-server-resource-packs", "kind": "shipped", "date": "the release's", "title": "…",
+      "plain": "…", "url": "https://playhorizon.dev/hub#server-resource-packs", "item": "…", "item_title": "…",
+      "shipped_in": "v0.2.48", "post": "at most 240 characters", "announce": false },
+    { "id": "weekly-2026-43", "kind": "weekly", "date": "the week's last second", "title": "…", "plain": "…",
+      "dev": "…", "url": "https://playhorizon.dev/hub#week-2026-43" } ] }
 ```
 
-`post` is at most 240 characters, ready to announce as is. Readers should remember the ids they have posted.
+- An `id` never changes: readers post each one once. `merge` entries are the pull requests players see (no
+  `skip-release` label), plus any that moves a roadmap item; `item` is absent when none does.
+- `announce: true` (the item's `announce` key) asks Kira to post the shipped item on X too, with `post`.
+- `https://playhorizon.dev/data/roadmap.json` is `roadmap.toml` as JSON (`areas`, `items` with every key above,
+  `overview`, the weekly summaries); an item's page is `https://playhorizon.dev/hub#<id>`.
diff --git a/tools/roadmap.py b/tools/roadmap.py
index ab0147e70..fe97285ff 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -57,7 +57,7 @@ ISSUE = re.compile(r"#(\d+)$")
 ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$")
 # An item is the anchor playhorizon.dev/hub#<id>: it can't take the name of a tab, a section or a heading.
 RESERVED = {"main", "overview", "roadmap", "board", "journal", "contribute", "hub-data", *STATUSES}
-RESERVED_PREFIXES = ("h-", "tab-", "week-")
+RESERVED_PREFIXES = ("h-", "tab-", "col-", "week-", "journal-")
 RELEASE = re.compile(r"(v\d[\w.]*|launcher@\d[\w.]*|launcher-v\d[\w.]*|website)$")
 MONTHS = ("January|February|March|April|June|July|August|September|October|November|December")
 # Kira's rule: no dates and no promises of when. "Coming soon" is the one allowed phrase.
diff --git a/website/README.md b/website/README.md
index 56fa515b9..d17bd0cd1 100644
--- a/website/README.md
+++ b/website/README.md
@@ -40,7 +40,7 @@ src/estimate.js    estimates for unmeasured hardware from the nearest measured m
 src/markdown.js    a small Markdown renderer (escapes everything), shared by build and page
 src/releases.js    the home page's "Recently added" and the Releases page's markup, shared by build and page
 src/contributors.js the contributors' filtering and markup, shared by build and page
-src/hub.js         the hub's roadmap, board and journal from data/roadmap.json, GitHub's issues and the releases, shared by build and page; /hub/journal.json
+src/hub.js         the hub's roadmap, board and journal from data/roadmap.json, GitHub's issues and the releases, shared by build and page; /data/journal.json
 src/hub-page.js    the hub page: tabs by #hash, the Simple / Technical switch (localStorage), the area filter, live states
 data/roadmap.json  the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /data/roadmap.json
 public/            fonts, screenshots, icons, og.png, robots.txt, benchmarks.json: copied as is (sitemap.xml is written by the build)
diff --git a/website/build.mjs b/website/build.mjs
index 17768e5fc..c3203891e 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -437,7 +437,7 @@ for (const { file, values: own } of docPages) {
 await mkdir(join(dist, "data"), { recursive: true });
 await cp(join(site, "data", "roadmap.json"), join(dist, "data", "roadmap.json"));
 // The journal for Kira's #updates and its X posts: /data/journal.json, rebuilt with every deploy.
-await writeFile(join(dist, "data", "journal.json"), JSON.stringify(journalJson(journal, roadmap), null, 1) + "\n");
+await writeFile(join(dist, "data", "journal.json"), JSON.stringify(journalJson(releases, hubLive, roadmap), null, 1) + "\n");
 
 // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS
 // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash.
diff --git a/website/src/hub.html b/website/src/hub.html
index a6e146080..d4ba4600c 100644
--- a/website/src/hub.html
+++ b/website/src/hub.html
@@ -71,7 +71,7 @@
         </div>
 
         <div class="hub-panel" role="tabpanel" id="journal" aria-labelledby="tab-journal">
-          <p class="hub-intro">Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as <a href="/hub/journal.json">journal.json</a>.</p>
+          <p class="hub-intro">Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as <a href="/data/journal.json">journal.json</a>.</p>
           <div class="hub-journal" data-journal>
 {{HUB_JOURNAL}}
           </div>
diff --git a/website/src/hub.js b/website/src/hub.js
index cda3b4e5b..d293b7250 100644
--- a/website/src/hub.js
+++ b/website/src/hub.js
@@ -319,19 +319,66 @@ export function journalFrom(releases, list, roadmap) {
   return entries.sort((a, b) => b.date.localeCompare(a.date)).slice(0, ENTRIES);
 }
 
-// /hub/journal.json: the journal for Kira's #updates and posts elsewhere, with each shipped item's short text.
-export function journalJson(entries, roadmap, generated = new Date().toISOString()) {
-  const item = (id) => {
-    const i = roadmap.items.find((x) => x.id === id);
-    return i && { id: i.id, title: i.title, plain: i.plain, post: i.post || i.plain };
-  };
-  return {
-    format: "horizon-journal",
-    version: 1,
-    generated,
-    url: JOURNAL_URL,
-    entries: entries.map((e) => ({ ...e, items: [...new Set(e.changes.map((c) => c.item).filter(Boolean))].map(item).filter(Boolean), shipped: e.shipped.map(item).filter(Boolean) })),
-  };
+const HUB = "https://playhorizon.dev/hub";
+const FEED = 300;
+
+// /data/journal.json, which Kira reads for #updates and X (kira's src/journal.js): one flat entry per merged pull
+// request, release, shipped roadmap item and weekly summary, newest first. An entry's id never changes: Kira posts
+// each id once. Shipped items carry `post` (at most 240 characters, tools/roadmap.py checks) and `announce`.
+export function journalJson(releases, list, roadmap, generated = new Date().toISOString()) {
+  const items = new Map(roadmap.items.map((i) => [i.id, i]));
+  const ours = releases.filter((r) => !r.draft && (isGame(r.tag_name) || isLauncher(r.tag_name)));
+  const published = new Map(ours.map((r) => [r.tag_name, r.published_at || ""]));
+  const merges = list
+    .filter((i) => i.kind === "pr" && i.state === "merged")
+    .map((pr) => ({ pr, item: itemOf(pr, roadmap) }))
+    // What players see, and anything that moves a roadmap item.
+    .filter(({ pr, item }) => item || !pr.labels.includes("skip-release"))
+    .map(({ pr, item }) => ({
+      id: `pr-${pr.n}`,
+      kind: "merge",
+      date: pr.at,
+      title: pr.title,
+      url: pr.url,
+      number: pr.n,
+      ...(item ? { item, item_title: items.get(item)?.title } : {}),
+    }));
+  const released = ours.map((r) => ({
+    id: `release-${r.tag_name}`,
+    kind: "release",
+    date: r.published_at || "",
+    title: r.name || r.tag_name,
+    plain: parts(r).line,
+    url: r.html_url,
+    tag: r.tag_name,
+  }));
+  const shipped = roadmap.items
+    .filter((i) => i.status === "shipped")
+    .map((i) => ({
+      id: `shipped-${i.id}`,
+      kind: "shipped",
+      date: published.get(i.shipped_in) || generated,
+      title: i.title,
+      plain: i.plain,
+      url: `${HUB}#${i.id}`,
+      item: i.id,
+      item_title: i.title,
+      shipped_in: i.shipped_in,
+      post: i.post || i.plain,
+      announce: Boolean(i.announce),
+    }));
+  // A week's summary is dated at the end of its week, after that week's releases.
+  const weekly = (roadmap.journal || []).map((w) => ({
+    id: `weekly-${w.week}`,
+    kind: "weekly",
+    date: new Date(Date.parse(w.date) + 7 * 864e5 - 1000).toISOString(),
+    title: w.title,
+    plain: w.plain,
+    dev: w.dev,
+    url: `${HUB}#week-${w.week}`,
+  }));
+  const entries = [...merges, ...released, ...shipped, ...weekly].sort((a, b) => b.date.localeCompare(a.date) || a.id.localeCompare(b.id));
+  return { format: "horizon-journal", version: 2, generated, url: `${HUB}#journal`, entries: entries.slice(0, FEED) };
 }
 
 const KIND = { release: "Game", launcher: "Launcher", merged: "Merged", week: "This week" };
@@ -349,7 +396,7 @@ function changesHtml(entry, roadmap) {
   const dev = `<div class="hub-dev">${order
     .map((id) => {
       const item = roadmap.items.find((i) => i.id === id);
-      return `<p class="hub-group">${item ? `<a href="#item-${escape(id)}">${escape(item.title)}</a>` : "Other changes"}</p><ul class="hub-changes">${groups.get(id).map(line).join("")}</ul>`;
+      return `<p class="hub-group">${item ? `<a href="#${escape(id)}">${escape(item.title)}</a>` : "Other changes"}</p><ul class="hub-changes">${groups.get(id).map(line).join("")}</ul>`;
     })
     .join("")}</div>`;
   return simple + dev;
@@ -364,8 +411,8 @@ export function journalHtml(entries, roadmap) {
   <p class="hub-entry-meta"><span class="badge${e.kind === "release" ? " badge-game" : e.kind === "launcher" ? " badge-launcher" : ""}">${KIND[e.kind]}</span><time datetime="${escape(e.date)}">${escape(e.date.slice(0, 10))}</time></p>
   <h3 class="hub-entry-title">${e.url ? `<a href="${escape(e.url)}">${escape(e.title)}</a>` : escape(e.title)}</h3>
   ${e.kind === "week" ? `<p class="hub-plain">${inline(e.plain)}</p><p class="hub-dev">${inline(e.dev.replace(/(^|[^\w[/`])#(\d+)\b/g, (_, b, n) => `${b}[#${n}](${issueUrl(n)})`))}</p>` : ""}
-  ${shipped.length ? `<p class="hub-shipped">Shipped: ${shipped.map((i) => `<a href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join(", ")}</p>` : ""}
-  ${items.length ? `<p class="hub-entry-items hub-plain">${items.map((i) => `<a class="hub-link" href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join("")}</p>` : ""}
+  ${shipped.length ? `<p class="hub-shipped">Shipped: ${shipped.map((i) => `<a href="#${escape(i.id)}">${escape(i.title)}</a>`).join(", ")}</p>` : ""}
+  ${items.length ? `<p class="hub-entry-items hub-plain">${items.map((i) => `<a class="hub-link" href="#${escape(i.id)}">${escape(i.title)}</a>`).join("")}</p>` : ""}
   ${changesHtml(e, roadmap)}
 </article>`;
     })
diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs
index a6337399b..d688489e9 100644
--- a/website/src/hub.test.mjs
+++ b/website/src/hub.test.mjs
@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
-import { boardFrom, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
+import { boardFrom, boardHtml, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
 
 const roadmap = JSON.parse(readFileSync(new URL("../data/roadmap.json", import.meta.url), "utf8"));
 
@@ -42,7 +42,11 @@ test("the roadmap renders every item once, with both texts, in its status's sect
 });
 
 test("an item is its own anchor (hub#<id>, as Kira links it) and takes no other id of the page", () => {
-  const page = readFileSync(new URL("./hub.html", import.meta.url), "utf8") + roadmapHtml(roadmap) + overviewHtml(roadmap);
+  const week = { week: "2030-01", date: "2029-12-31", title: "A week", plain: "p", dev: "d" };
+  const release = { tag_name: "v0.2.2", name: "0.2.2", published_at: "2030-01-02T00:00:00Z", html_url: "u", body: "" };
+  const journal = journalHtml(journalFrom([release], [], { ...roadmap, journal: [week] }), roadmap);
+  const board = boardHtml(boardFrom([], roadmap), roadmap);
+  const page = readFileSync(new URL("./hub.html", import.meta.url), "utf8") + roadmapHtml(roadmap) + overviewHtml(roadmap) + board + journal;
   const ids = [...page.matchAll(/ id="([^"]+)"/g)].map((m) => m[1]);
   assert.deepEqual(ids.filter((id, i) => ids.indexOf(id) !== i), []);
   for (const item of roadmap.items) assert.ok(ids.includes(item.id), item.id);
@@ -91,10 +95,45 @@ test("the journal groups a release's changes by roadmap item and lists what awai
   assert.deepEqual(entries.map((e) => e.id), ["next-release", "v0.2.2", "launcher@0.2.1"]);
   assert.deepEqual(entries[0].changes.map((c) => [c.prs, c.item]), [[[1788], "discord-presence"]]);
   assert.deepEqual(entries[1].changes.map((c) => [c.section, c.text, c.item]), [["new", "Discord Rich Presence", "discord-presence"], ["fixed", "A fix", null]]);
-  const json = journalJson(entries, roadmap, "now");
-  assert.equal(json.format, "horizon-journal");
-  assert.equal(json.entries[1].items[0].post.length <= 240, true);
   const html = journalHtml(entries, roadmap);
-  assert.ok(html.includes('href="#item-discord-presence"'));
+  assert.ok(html.includes('href="#discord-presence"'));
   assert.ok(html.includes("And 1 fix."));
 });
+
+test("journal.json is the flat feed Kira reads: merges, releases, shipped items, weeks, ids that never change", () => {
+  const releases = [
+    { tag_name: "v0.2.48", name: "Horizon 0.2.48", published_at: "2030-01-02T00:00:00Z", html_url: "https://github.com/ludovic111/horizon/releases/tag/v0.2.48", body: "### New\n- Packs (#1)\n" },
+    { tag_name: "nightly-1", name: "Nightly", published_at: "2030-01-03T00:00:00Z", html_url: "u", body: "" },
+  ];
+  const list = [
+    pr(1788, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, html_url: "https://github.com/ludovic111/horizon/pull/1788" }),
+    pr(7, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, labels: [{ name: "skip-release" }] }),
+    pr(8, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, labels: [{ name: "skip-release" }, { name: "roadmap:lean-code" }] }),
+    pr(9),
+  ].map(slimIssue);
+  const week = { week: "2030-01", date: "2029-12-31", title: "A week", plain: "p", dev: "d" };
+  const feed = journalJson(releases, list, { ...roadmap, journal: [week] }, "2030-01-05T00:00:00Z");
+  const byId = new Map(feed.entries.map((e) => [e.id, e]));
+  // A merged pull request, with its roadmap item; skip-release ones only when they move an item; open ones never.
+  assert.deepEqual(byId.get("pr-1788"), { id: "pr-1788", kind: "merge", date: "2030-01-04T00:00:00Z", title: "PR 1788", url: "https://github.com/ludovic111/horizon/pull/1788", number: 1788, item: "discord-presence", item_title: "Discord Rich Presence" });
+  assert.ok(!byId.has("pr-7") && byId.get("pr-8").item === "lean-code" && !byId.has("pr-9"));
+  // Game and launcher releases only.
+  assert.equal(byId.get("release-v0.2.48").tag, "v0.2.48");
+  assert.ok(!byId.has("release-nightly-1"));
+  // Every shipped item, dated by its release when the feed has it, with its post and the announce flag.
+  const shipped = roadmap.items.filter((i) => i.status === "shipped");
+  for (const item of shipped) {
+    const e = byId.get(`shipped-${item.id}`);
+    assert.equal(e.kind, "shipped");
+    assert.equal(e.url, `https://playhorizon.dev/hub#${item.id}`);
+    assert.ok(e.post.length <= 240 && typeof e.announce === "boolean", item.id);
+  }
+  assert.equal(byId.get("shipped-server-resource-packs").date, "2030-01-02T00:00:00Z");
+  assert.equal(byId.get("weekly-2030-01").date, "2030-01-06T23:59:59.000Z");
+  // Newest first; every entry has what Kira needs, and links only where Kira shows them.
+  assert.deepEqual(feed.entries.map((e) => e.date), feed.entries.map((e) => e.date).sort().reverse());
+  for (const e of feed.entries) {
+    assert.ok(e.id && ["merge", "release", "weekly", "shipped"].includes(e.kind) && e.date && e.title, e.id);
+    assert.match(e.url, /^https:\/\/(github\.com|playhorizon\.dev)\//, e.id);
+  }
+});

From 10efca9e6cd922ff7b9a4a3cc3f5a467e97f52f2 Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:40:29 +0100
Subject: [PATCH 110/270] Discard a dead player's ender pearl when the rule
 says so

With ender_pearls_vanish_on_death on, a pearl thrown just before death
kept flying and pulled the respawned player back to it. Vanilla's
ThrownEnderpearl.tick discards the pearl instead of ticking it while
its owner is dead. Add a harness that throws a pearl, dies and respawns
on a dedicated server and compares the teleports with vanilla's.
---
 crates/horizon-client/src/game/creatures.rs   |  19 +++
 .../horizonlab/parity/LocatorBarClient.java   |  15 +-
 tools/test_pearl_death_parity.py              | 142 ++++++++++++++++++
 3 files changed, 175 insertions(+), 1 deletion(-)
 create mode 100644 tools/test_pearl_death_parity.py

diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 0bb7bbe85..ff07e9011 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -1694,7 +1694,26 @@ impl Game<'_> {
                 targets: targets_guests,
             };
             let guest_entities = self.lan_guest_entities();
+            // ThrownEnderpearl.tick: a dead player's pearl is discarded in
+            // place of its tick while ender_pearls_vanish_on_death is on.
+            let vanish = self.ui.rules.bool("ender_pearls_vanish_on_death");
+            let host_dead = self.player_view().is_some_and(|p| !p.alive);
+            let dead_guests: Vec<u32> = self.lan.as_ref().map_or_else(Vec::new, |h| {
+                h.hub
+                    .guests
+                    .iter()
+                    .filter(|g| g.dead)
+                    .map(|g| g.conn)
+                    .collect()
+            });
             projectiles.retain_mut(|p| {
+                if vanish
+                    && matches!(p.kind, ProjectileKind::EnderPearl)
+                    && p.owner == Some(Who::Player)
+                    && p.guest.map_or(host_dead, |c| dead_guests.contains(&c))
+                {
+                    return false;
+                }
                 let mob_shot = !matches!(p.owner, Some(Who::Player));
                 // A player's arrows, snowballs and eggs meet every player; a
                 // guest's flies from that guest (Projectile.getOwner), not
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
index 76a951894..818746336 100644
--- a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
@@ -84,7 +84,10 @@ import net.minecraft.world.phys.Vec3;
  * still), {@code sync NAME} (runs {@code time query gametime}, whose reply is
  * not recorded, and prints {@code synced NAME} once it is back: the server has
  * handled everything this player sent before, and everything the server sent
- * this player before the reply has been recorded), {@code quit NAME}, {@code
+ * this player before the reply has been recorded), {@code respawn NAME} (the
+ * death screen's button, ServerboundClientCommandPacket PERFORM_RESPAWN),
+ * {@code use NAME PITCH} (the main hand's item used looking that way,
+ * ServerboundUseItemPacket), {@code quit NAME}, {@code
  * players on|off} (whether each player also records the other players added
  * to and removed from its level, and its own respawns into a dimension),
  * {@code chat on|off} (whether the system chat each player receives is
@@ -130,6 +133,9 @@ public final class LocatorBarClient {
                         players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundPlayerAbilitiesPacket(abilities));
                     }
                     case "still" -> players.get(w[1]).still();
+                    case "respawn" -> players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundClientCommandPacket(
+                        net.minecraft.network.protocol.game.ServerboundClientCommandPacket.Action.PERFORM_RESPAWN));
+                    case "use" -> players.get(w[1]).use(Float.parseFloat(w[2]));
                     case "sync" -> {
                         try {
                             players.get(w[1]).sync();
@@ -250,6 +256,13 @@ public final class LocatorBarClient {
             }
         }
 
+        private int sequence;
+
+        void use(float pitch) throws Exception {
+            send(new net.minecraft.network.protocol.game.ServerboundUseItemPacket(
+                net.minecraft.world.InteractionHand.MAIN_HAND, ++sequence, position.yRot(), pitch));
+        }
+
         void still() throws Exception {
             PositionMoveRotation at = position;
             // A tick of its own: the server takes one position per client tick (receivedPositionThisTick).
diff --git a/tools/test_pearl_death_parity.py b/tools/test_pearl_death_parity.py
new file mode 100644
index 000000000..a6795c749
--- /dev/null
+++ b/tools/test_pearl_death_parity.py
@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""An ender pearl in flight when its thrower dies, on a dedicated server, against vanilla's, seen by a vanilla client.
+
+A vanilla dedicated server and Horizon's (`horizon-client --dedicated --nogui`) each serve a copy of one flat world
+vanilla generated first, with Alice an operator in survival. LocatorBarClient (a player made of vanilla's protocol
+code) throws an ender pearl straight up (ServerboundUseItemPacket), runs /kill on itself while the pearl flies,
+presses the death screen's button (PERFORM_RESPAWN) and waits for the pearl to come down, with the rule
+ender_pearls_vanish_on_death true: ThrownEnderpearl.tick discards a dead owner's pearl, so the respawned player is
+never teleported. The teleports, game mode changes and respawns Alice is sent from the throw on are compared
+exactly.
+"""
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+import time
+
+try:
+    from . import lab, test_rust_parity as base, test_locator_bar_parity as locator
+    from .test_dedicated_server_parity import Server
+except ImportError:
+    import lab
+    import test_rust_parity as base
+    import test_locator_bar_parity as locator
+    from test_dedicated_server_parity import Server
+
+NAME = 'pearl-death-parity'
+# server_dir and generate_world write these server.properties.
+locator.PROPERTIES = dict(locator.PROPERTIES, gamemode='survival')
+STEP_SECONDS = 4.0
+SHOWN = ('teleport', 'gamemode', 'respawn')
+
+
+SCRIPT = [
+    ('setup', ['cmd Alice gamerule ender_pearls_vanish_on_death true', 'cmd Alice give @s minecraft:ender_pearl']),
+    # Straight up: it comes down about four seconds later, near where it was thrown.
+    ('throw', ['use Alice -90', 'cmd Alice kill @s']),
+    ('respawn', ['respawn Alice']),
+    ('landed', []),
+]
+
+
+def run_side(label, server_command, client_command, build, world):
+    directory = build / label
+    port = locator.server_dir(directory, world)
+    out = build / f'{label}.txt'
+    out.unlink(missing_ok=True)
+    server = Server(server_command, directory, label)
+    try:
+        server.wait_for(r'Done \(')
+        with (build / f'{label}-client.log').open('w') as log:
+            client = subprocess.Popen([*map(str, client_command), '127.0.0.1', str(port), str(out)],
+                                      cwd=lab.ROOT, stdin=subprocess.PIPE, stdout=log, stderr=subprocess.STDOUT,
+                                      text=True)
+
+            def tell(line):
+                client.stdin.write(line + '\n')
+                client.stdin.flush()
+            try:
+                tell('players on')
+                tell('state on')
+                tell('step joins')
+                tell('join Alice')
+                server.wait_for(r'Alice joined the game', timeout=120)
+                time.sleep(STEP_SECONDS)
+                for step, actions in SCRIPT:
+                    tell(f'step {step}')
+                    for action in actions:
+                        tell(action)
+                    time.sleep(STEP_SECONDS)
+                tell('end')
+                client.wait(timeout=60)
+            finally:
+                if client.poll() is None:
+                    client.kill()
+    finally:
+        server.stop()
+    if not out.exists():
+        raise AssertionError(f'{label}: the client wrote no transcript (see {build}/{label}-client.log)')
+    return out.read_text(encoding='utf-8').splitlines()
+
+
+def shown(lines):
+    """Alice's teleports, game mode changes and respawns from the throws on."""
+    steps = {f'step={step}' for step, _ in SCRIPT if step != 'setup'}
+    return [line for line in lines if len(parts := line.split(' ', 3)) >= 3 and parts[1] in steps
+            and parts[2] in SHOWN]
+
+
+def main():
+    lock, jars, libraries = base.verify_artifacts()
+    build = lab.LOCAL / NAME
+    build.mkdir(parents=True, exist_ok=True)
+    report = build / 'report.json'
+    report.unlink(missing_ok=True)
+    oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java'
+    classes = build / 'classes'
+    shutil.rmtree(classes, ignore_errors=True)
+    classes.mkdir()
+    dependencies = os.pathsep.join(map(str, [jars['server'], *libraries]))
+    subprocess.run(['javac', '--release', str(lock['minecraft']['java_major']), '-proc:none', '-nowarn', '-sourcepath',
+                    lab.ROOT / 'mods/horizon/src/test/java', '-cp', dependencies, '-d', classes, oracle],
+                   cwd=lab.ROOT, check=True, capture_output=True)
+    subprocess.run(['cargo', 'build', '--release', '-p', 'horizon-client', '--bin', 'horizon-client'], cwd=lab.ROOT,
+                   check=True, capture_output=True)
+    metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--no-deps', '--format-version', '1'],
+                                                  cwd=lab.ROOT, text=True))
+    binary = Path(metadata['target_directory']) / 'release' / ('horizon-client.exe' if os.name == 'nt' else 'horizon-client')
+    vanilla_server = ['java', '-Xmx2g', '-Duser.timezone=UTC', '-cp', dependencies, 'net.minecraft.server.Main', 'nogui']
+    horizon_server = [binary, '--resources', lab.LOCAL / 'horizon-client/26.3', '--dedicated', '--nogui']
+    client = ['java', '-Xmx1g', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.LocatorBarClient']
+
+    world = locator.generate_world(vanilla_server, build)
+    vanilla_all = run_side('vanilla', vanilla_server, client, build, world)
+    horizon_all = run_side('horizon', horizon_server, client, build, world)
+    errors = [l for l in vanilla_all + horizon_all if ' error ' in f' {l} ' or 'disconnected' in l]
+    vanilla, horizon = shown(vanilla_all), shown(horizon_all)
+    if errors or vanilla != horizon:
+        import difflib
+        diff = '\n'.join(difflib.unified_diff(vanilla, horizon, 'vanilla', 'horizon', n=1, lineterm=''))
+        raise AssertionError(f'{len(errors)} errors, transcripts differ (see {build}/vanilla.txt and horizon.txt):\n'
+                             + '\n'.join(errors[:10]) + '\n' + diff[:6000])
+    killed = any(l.startswith('Alice step=throw killed') for l in vanilla_all)
+    if not killed or 'Alice step=respawn respawn minecraft:overworld' not in vanilla:
+        raise AssertionError(f'vanilla did not kill and respawn Alice: the script did not run (see {build})')
+    lab.write_json(report, dict(
+        schema=1, minecraft=lock['minecraft']['version'], platform=platform.platform(),
+        java=subprocess.check_output(['java', '--version'], text=True).splitlines()[0],
+        lines=len(vanilla), output_sha256=lab.digest(build / 'horizon.txt', 'sha256'),
+        scope='An ender pearl in flight when its thrower dies and respawns on a dedicated server, with '
+              'ender_pearls_vanish_on_death true: the pearl vanishes and never teleports the player.'))
+    print(f'pearl death: {len(vanilla)} lines identical')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except AssertionError as error:
+        sys.exit(f'{NAME}: {error}')

From 0c017678eb50c5819f0e2948f3f8432093e027ac Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:44:16 +0100
Subject: [PATCH 111/270] Keep shulker boxes out of shulker boxes on the server

ShulkerBoxSlot.mayPlace refuses items that cannot fit inside container items, which BlockItem says of every shulker box. The server's menus for guests treated a shulker box's slots like a chest's, so with the server thread a shulker box could be clicked, shift-clicked or swapped into another. Apply the slot rule when the open menu is a shulker box.
---
 crates/horizon-client/src/lan/containers.rs |  9 +++++++++
 crates/horizon-client/src/lan/menu.rs       | 11 +++++++++++
 2 files changed, 20 insertions(+)

diff --git a/crates/horizon-client/src/lan/containers.rs b/crates/horizon-client/src/lan/containers.rs
index d43cb5c27..3dc085a6d 100644
--- a/crates/horizon-client/src/lan/containers.rs
+++ b/crates/horizon-client/src/lan/containers.rs
@@ -344,6 +344,14 @@ impl Hub {
             return Vec::new();
         }
         let source = self.guests[i].menu.as_ref().map(|m| m.slots);
+        let shulker_box = self
+            .sync
+            .builtin
+            .get("minecraft:menu")
+            .and_then(|m| m.id("minecraft:shulker_box"));
+        let shulker = in_menu
+            && shulker_box.is_some()
+            && self.guests[i].menu.as_ref().map(|m| m.kind) == shulker_box;
         let mut drag = if in_menu {
             self.guests[i].menu.as_mut().and_then(|m| m.drag.take())
         } else {
@@ -357,6 +365,7 @@ impl Hub {
         let mut view = View {
             guest,
             container: items.as_deref_mut(),
+            shulker,
         };
         let (drops, changed) = menu::click(
             &mut view,
diff --git a/crates/horizon-client/src/lan/menu.rs b/crates/horizon-client/src/lan/menu.rs
index de9fb9608..fefcb1933 100644
--- a/crates/horizon-client/src/lan/menu.rs
+++ b/crates/horizon-client/src/lan/menu.rs
@@ -111,6 +111,8 @@ pub struct View<'a> {
     pub guest: &'a mut Guest,
     /// The container's slots, or None for the inventory menu.
     pub container: Option<&'a mut [Option<ItemStack>]>,
+    /// The container is a shulker box (`ShulkerBoxSlot`).
+    pub shulker: bool,
 }
 
 impl View<'_> {
@@ -153,6 +155,14 @@ impl View<'_> {
         if self.container.is_none() && (5..=8).contains(&i) {
             return rules.armor_index(&stack.item) == Some(i - 5);
         }
+        // ShulkerBoxSlot.mayPlace: Item.canFitInsideContainerItems, false
+        // for shulker boxes.
+        if self.shulker
+            && self.container.as_ref().is_some_and(|c| i < c.len())
+            && stack.item.ends_with("shulker_box")
+        {
+            return false;
+        }
         self.enabled(i)
     }
     fn slot_max(&self, i: usize, stack: &ItemStack, rules: &dyn Rules) -> u32 {
@@ -704,6 +714,7 @@ mod tests {
         let mut view = View {
             guest: &mut g,
             container: Some(&mut chest),
+            shulker: false,
         };
         view.guest.carried = Some(ItemStack::new("minecraft:bundle", 1));
         // Left click with the bundle: the stone goes in.

From 0eb475152e0040c2623bfa76ec10053fa31059ac Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:07:46 +0100
Subject: [PATCH 112/270] Registry: show who publishes a project, linked to
 their GitHub profile

The index already carries each project's owners (the GitHub accounts the
registry checked at submission), but neither the website nor the launcher
showed them. The project page now says "Published by @login" with the
avatar and a link to the profile; the launcher adds an @login link per
owner. Only strings that are valid GitHub logins become links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/browser/horizon.rs       | 24 ++++++++++++++++++++++--
 launcher/src/browser/horizon/tests.rs | 19 +++++++++++++++++++
 website/src/mods.js                   | 15 ++++++++++++++-
 website/src/mods.test.mjs             |  8 ++++++++
 website/src/style.css                 |  3 +++
 5 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index 501295c6b..e56f31e09 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -190,6 +190,18 @@ fn version_of(index: &Index, p: &index::Project, v: &index::Version) -> Version
     }
 }
 
+/// A GitHub login as GitHub allows it (letters, digits, single dashes, at most 39), so an index
+/// entry can't turn a link into something else.
+fn github_login(login: &str) -> bool {
+    (1..=39).contains(&login.len())
+        && login
+            .bytes()
+            .all(|b| b.is_ascii_alphanumeric() || b == b'-')
+        && !login.starts_with('-')
+        && !login.ends_with('-')
+        && !login.contains("--")
+}
+
 /// The words of a query found in a project's id, name, summary or authors.
 fn matches(p: &index::Project, text: &str) -> bool {
     let hay = format!("{} {} {} {}", p.id, p.name, p.summary, p.authors.join(" ")).to_lowercase();
@@ -277,9 +289,14 @@ impl Source for Registry {
                 body.push_str(&format!("- {} {}{may}\n", m.name, w.version));
             }
         }
+        // Who publishes it: the GitHub accounts the registry checked at submission.
+        let owners = p.owners.iter().filter(|o| github_login(o)).map(|o| Link {
+            label: format!("@{o}"),
+            url: format!("https://github.com/{o}"),
+        });
         Ok(Details {
             body,
-            links: vec![
+            links: [
                 Link {
                     label: "Source".into(),
                     url: p.source.clone(),
@@ -292,7 +309,10 @@ impl Source for Registry {
                     label: "Report".into(),
                     url: format!("{REPORT}&title={}", p.id),
                 },
-            ],
+            ]
+            .into_iter()
+            .chain(owners)
+            .collect(),
             authors: p.authors.clone(),
             published: p
                 .versions
diff --git a/launcher/src/browser/horizon/tests.rs b/launcher/src/browser/horizon/tests.rs
index bf98719d7..fb99462e1 100644
--- a/launcher/src/browser/horizon/tests.rs
+++ b/launcher/src/browser/horizon/tests.rs
@@ -143,3 +143,22 @@ fn registry_versions_run_when_made_for_this_game() {
         .collect();
     assert_eq!(pick(Kind::Mod, &versions, false).unwrap().number, "0.1.0");
 }
+
+#[test]
+fn owner_links_only_take_github_logins() {
+    for ok in ["Stink-O", "ludovic111", "a"] {
+        assert!(github_login(ok), "{ok}");
+    }
+    for bad in [
+        "",
+        "-x",
+        "x-",
+        "a--b",
+        "bad login",
+        "a/b",
+        "x?y=1",
+        &"a".repeat(40),
+    ] {
+        assert!(!github_login(bad), "{bad}");
+    }
+}
diff --git a/website/src/mods.js b/website/src/mods.js
index 4819af374..acaee41f0 100644
--- a/website/src/mods.js
+++ b/website/src/mods.js
@@ -79,6 +79,19 @@ function installHtml(p, v) {
 </ol>`;
 }
 
+// GitHub's rule for a login: letters, digits and single dashes, at most 39.
+const LOGIN = /^(?!-)(?!.*--)[A-Za-z0-9-]{1,39}(?<!-)$/;
+
+// Who publishes it: the GitHub accounts the registry checked when the project was submitted.
+export function ownersHtml(p) {
+  const owners = (p.owners || []).filter((o) => LOGIN.test(o));
+  if (!owners.length) return "";
+  const links = owners
+    .map((o) => `<a class="mod-owner" href="https://github.com/${o}"><img src="https://avatars.githubusercontent.com/${o}?s=48" alt="" width="24" height="24" loading="lazy">@${o}</a>`)
+    .join(" ");
+  return `<p class="meta mod-owners">Published by ${links}</p>`;
+}
+
 // One project's page.
 export function projectHtml(p) {
   const v = p.versions[0];
@@ -93,7 +106,7 @@ export function projectHtml(p) {
     .map((x) => `<li><strong>${escape(x.version)}</strong> <span class="mod-version">${escape(x.published || "")} · for ${escape(x.game)}${x.api ? ` · API ${escape(x.api)}` : ""}</span>${x.changelog ? `<div class="prose">${markdown(x.changelog)}</div>` : ""}</li>`)
     .join("");
   return `<article class="mod-page" data-id="${escape(p.id)}">
-  <header class="mod-head">${icon(p)}<div><p class="kicker"><span>${escape(KIND_NAMES[p.kind] || p.kind)}</span>${escape((p.authors || []).join(", "))}</p>
+  <header class="mod-head">${icon(p)}<div><p class="kicker"><span>${escape(KIND_NAMES[p.kind] || p.kind)}</span>${escape((p.authors || []).join(", "))}</p>${ownersHtml(p)}
   <h1 class="display page-title">${escape(p.name)}</h1><p class="lede">${escape(p.summary || "")}</p>
   <p class="mod-badges">${trust(p)} <span class="badge">${escape(p.license)}</span> <span class="badge">${escape(v.version)}</span>${v.side ? ` <span class="badge">${escape(v.side)}</span>` : ""}</p></div></header>
   ${p.description ? `<div class="prose">${markdown(p.description)}</div>` : ""}
diff --git a/website/src/mods.test.mjs b/website/src/mods.test.mjs
index 75e3ca4c5..c5ff2e783 100644
--- a/website/src/mods.test.mjs
+++ b/website/src/mods.test.mjs
@@ -53,3 +53,11 @@ test("the submit form sends what the service reads", () => {
   assert.equal(entry.icon, undefined);
   assert.equal(JSON.parse(JSON.stringify(entry)).key, undefined, "an empty key isn't sent");
 });
+
+test("a project's page links its owners' GitHub profiles, and only valid logins", () => {
+  const html = projectHtml(project({ owners: ["Stink-O", "bad login", "-x", "a--b", "ok\"><script>"] }));
+  assert.ok(html.includes('href="https://github.com/Stink-O"'));
+  assert.ok(html.includes("@Stink-O"));
+  for (const bad of ["bad login", "github.com/-x", "a--b", "<script>"]) assert.ok(!html.includes(bad), bad);
+  assert.ok(!projectHtml(project()).includes("Published by"));
+});
diff --git a/website/src/style.css b/website/src/style.css
index 4ce91791d..a698c5967 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -759,6 +759,9 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 .mod-page { display: grid; gap: 16px; max-width: calc(var(--measure) + 240px); }
 .mod-page .heading { margin-top: 24px; }
 .mod-head { display: grid; grid-template-columns: 96px minmax(0, 1fr); gap: 24px; align-items: start; }
+.mod-owners { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin: 4px 0 0; }
+.mod-owner { display: inline-flex; align-items: center; gap: 6px; }
+.mod-owner img { border-radius: 50%; }
 .mod-head .mod-icon { width: 96px; height: 96px; font-size: 44px; }
 .mod-head .page-title { margin-top: 0; }
 .mod-badges { margin-top: 16px; }

From 5bfc649edd18aaf9738dc428bc24ae9e991cf87d Mon Sep 17 00:00:00 2001
From: Kacpherek <papiezkacper10@gmail.com>
Date: Sun, 25 Oct 2026 15:52:29 +0100
Subject: [PATCH 113/270] Drop the cursor stack of a dead player

A stack held on the inventory cursor at death stayed there through the
respawn, even with keep_inventory off. In vanilla the dead player is
removed 20 ticks after dying (or when it respawns sooner), and
Player.remove's inventoryMenu.removed drops what the cursor held where
the player died. Do the same for server players and the in-frame
player, and add a harness that dies with a cursor stack on a dedicated
server and compares with vanilla.
---
 crates/horizon-client/src/game.rs             |  20 ++-
 crates/horizon-client/src/game/chat.rs        |   2 +
 crates/horizon-client/src/game/lan_actions.rs |  27 +++-
 crates/horizon-client/src/lan/guest.rs        |   3 +
 .../horizonlab/parity/LocatorBarClient.java   |  10 +-
 tools/test_cursor_death_parity.py             | 143 ++++++++++++++++++
 6 files changed, 202 insertions(+), 3 deletions(-)
 create mode 100644 tools/test_cursor_death_parity.py

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..667eff52a 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -2173,6 +2173,11 @@ impl Game<'_> {
         // Player.drop: the drop statistics.
         self.stats.add("dropped", &thrown.item, thrown.count as i32);
         self.stats.custom("drop", 1);
+        self.throw_from_eyes(thrown, eye);
+    }
+    /// `Player.createItemStackToDrop`: an item entity thrown from the eyes
+    /// along the view direction.
+    fn throw_from_eyes(&mut self, thrown: ItemStack, eye: [f64; 3]) {
         let (yaw, pitch) = (
             f64::from(self.yaw).to_radians(),
             f64::from(self.pitch).to_radians(),
@@ -4335,7 +4340,8 @@ impl Game<'_> {
             // Out of the world.
             let _ = player.set_health(0.0, false);
         }
-        if player.health.dead_or_dying() && self.screen != Screen::Dead {
+        let dead = player.health.dead_or_dying();
+        if dead && self.screen != Screen::Dead {
             // Inventory.dropAll: every stack thrown in a random direction.
             let feet = [player.position.x, player.position.y, player.position.z];
             let at = [feet[0], feet[1] + 1.32, feet[2]];
@@ -4369,6 +4375,18 @@ impl Game<'_> {
             }
             self.screen = Screen::Dead;
             self.capture(false);
+            self.ui.death_time = 0;
+        } else if dead {
+            // LivingEntity.tickDeath: 20 ticks after dying the player is
+            // removed, and Player.remove's inventoryMenu.removed drops what
+            // the cursor held.
+            self.ui.death_time += 1;
+            if self.ui.death_time >= 20
+                && let Some(stack) = self.carried.take()
+                && let Some(eye) = self.eye_position()
+            {
+                self.throw_from_eyes(stack, eye);
+            }
         }
         self.tick_world(running)
     }
diff --git a/crates/horizon-client/src/game/chat.rs b/crates/horizon-client/src/game/chat.rs
index ec85732ae..15e34bbb6 100644
--- a/crates/horizon-client/src/game/chat.rs
+++ b/crates/horizon-client/src/game/chat.rs
@@ -99,6 +99,8 @@ pub struct UiState {
     /// Death screen cause and when the player died (buttons wait 20 ticks).
     pub death_text: Option<Text>,
     pub died_at: Option<std::time::Instant>,
+    /// `LivingEntity.deathTime` of the window's player: ticks since it died.
+    pub death_time: u32,
 }
 
 impl Game<'_> {
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..de6ae51dc 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1234,6 +1234,24 @@ impl Game<'_> {
         Some(out)
     }
 
+    /// `LivingEntity.tickDeath`: 20 ticks after dying the player is removed,
+    /// and `Player.remove`'s `inventoryMenu.removed` drops what the cursor
+    /// held (`dropOrPlaceInInventory` for a removed player). Respawning
+    /// sooner removes it too.
+    fn guest_tick_death(&mut self, host: &mut LanHost, gi: usize) {
+        let g = &mut host.hub.guests[gi];
+        g.death_time += 1;
+        if g.death_time >= 20 {
+            self.guest_drop_carried(host, gi);
+        }
+    }
+
+    fn guest_drop_carried(&mut self, host: &mut LanHost, gi: usize) {
+        if let Some(c) = host.hub.guests[gi].carried.take() {
+            self.drop_guest_items(host, gi, vec![c]);
+        }
+    }
+
     /// `AbstractContainerMenu.removed`: what a closing player held on the
     /// cursor goes back into their inventory (`placeItemBackInInventory`,
     /// dropped only if it doesn't fit), and their client's cursor empties
@@ -1573,6 +1591,8 @@ impl Game<'_> {
         if !host.hub.guests[i].dead {
             return;
         }
+        // PlayerList.respawn removes the dead player (Player.remove).
+        self.guest_drop_carried(host, i);
         // PlayerList.respawn: a server's player comes back in its respawn
         // point's level: the Overworld, where the world spawn and beds are,
         // or another one's anchor or forced point, which its block resolves
@@ -1613,6 +1633,7 @@ impl Game<'_> {
         }
         let g = &mut host.hub.guests[i];
         g.dead = false;
+        g.death_time = 0;
         g.health = 20.0;
         g.food = 20;
         g.saturation = 5.0;
@@ -1694,7 +1715,11 @@ impl Game<'_> {
                 continue;
             };
             self.guest_sleep_tick(host, gi);
-            if host.hub.guests[gi].dead || self.on_server_trip(conn) {
+            if host.hub.guests[gi].dead {
+                self.guest_tick_death(host, gi);
+                continue;
+            }
+            if self.on_server_trip(conn) {
                 continue;
             }
             let play = host.play.entry(conn).or_default();
diff --git a/crates/horizon-client/src/lan/guest.rs b/crates/horizon-client/src/lan/guest.rs
index 440b58284..70510a5b4 100644
--- a/crates/horizon-client/src/lan/guest.rs
+++ b/crates/horizon-client/src/lan/guest.rs
@@ -223,6 +223,8 @@ pub struct Guest {
     /// Whether the guest was on the ground before the first of `moves`.
     pub moves_from_ground: bool,
     pub dead: bool,
+    /// `LivingEntity.deathTime`: ticks since the guest died.
+    pub death_time: u32,
     /// The join packets were sent (PlayerList.placeNewPlayer ran).
     pub placed: bool,
     /// The level the player is in (`ServerPlayer.level().dimension()`): the
@@ -349,6 +351,7 @@ impl Guest {
             moves: Vec::new(),
             moves_from_ground: false,
             dead: false,
+            death_time: 0,
             placed: false,
             dimension: "minecraft:overworld".into(),
             menu: None,
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
index 76a951894..e4aeef25e 100644
--- a/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java
@@ -84,7 +84,10 @@ import net.minecraft.world.phys.Vec3;
  * still), {@code sync NAME} (runs {@code time query gametime}, whose reply is
  * not recorded, and prints {@code synced NAME} once it is back: the server has
  * handled everything this player sent before, and everything the server sent
- * this player before the reply has been recorded), {@code quit NAME}, {@code
+ * this player before the reply has been recorded), {@code respawn NAME} (the
+ * death screen's button, ServerboundClientCommandPacket PERFORM_RESPAWN),
+ * {@code pickup NAME SLOT} (a left click on that slot of the player's
+ * inventory menu, claiming nothing), {@code quit NAME}, {@code
  * players on|off} (whether each player also records the other players added
  * to and removed from its level, and its own respawns into a dimension),
  * {@code chat on|off} (whether the system chat each player receives is
@@ -130,6 +133,11 @@ public final class LocatorBarClient {
                         players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundPlayerAbilitiesPacket(abilities));
                     }
                     case "still" -> players.get(w[1]).still();
+                    case "respawn" -> players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundClientCommandPacket(
+                        net.minecraft.network.protocol.game.ServerboundClientCommandPacket.Action.PERFORM_RESPAWN));
+                    case "pickup" -> players.get(w[1]).send(new net.minecraft.network.protocol.game.ServerboundContainerClickPacket(
+                        0, 0, Short.parseShort(w[2]), (byte) 0, net.minecraft.world.inventory.ContainerInput.PICKUP,
+                        new it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap<>(), net.minecraft.network.HashedStack.EMPTY));
                     case "sync" -> {
                         try {
                             players.get(w[1]).sync();
diff --git a/tools/test_cursor_death_parity.py b/tools/test_cursor_death_parity.py
new file mode 100644
index 000000000..8da944350
--- /dev/null
+++ b/tools/test_cursor_death_parity.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""What a player holds on the cursor when they die, on a dedicated server, against vanilla's, seen by a vanilla client.
+
+A vanilla dedicated server and Horizon's (`horizon-client --dedicated --nogui`) each serve a copy of one flat world
+vanilla generated first, with Alice an operator in survival and keep_inventory off. LocatorBarClient (a player made
+of vanilla's protocol code) is given seven diamonds, picks them up onto its inventory menu's cursor (a PICKUP click)
+ten blocks from the spawn, runs /kill on itself, waits on the death screen and respawns (PERFORM_RESPAWN). Twenty
+ticks after dying vanilla removes the dead player (LivingEntity.tickDeath), and Player.remove's
+inventoryMenu.removed drops the cursor's stack where it died. Alice then asks whether an item lies around the death
+site; the reply, and the inventory slots, respawns and teleports she is sent from the death on, are compared
+exactly.
+"""
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+import time
+
+try:
+    from . import lab, test_rust_parity as base, test_locator_bar_parity as locator
+    from .test_dedicated_server_parity import Server
+except ImportError:
+    import lab
+    import test_rust_parity as base
+    import test_locator_bar_parity as locator
+    from test_dedicated_server_parity import Server
+
+NAME = 'cursor-death-parity'
+# server_dir and generate_world write these server.properties.
+locator.PROPERTIES = dict(locator.PROPERTIES, gamemode='survival')
+SCRIPT = [
+    ('setup', ['cmd Alice gamerule keep_inventory false', 'cmd Alice clear @s',
+               'cmd Alice give @s minecraft:diamond 7', 'cmd Alice tp @s 10.5 -60 0.5']),
+    # Hotbar slot 0 is the inventory menu's slot 36.
+    ('pickup', ['pickup Alice 36']),
+    ('death', ['cmd Alice kill @s']),
+    ('respawn', ['respawn Alice']),
+    ('check', ['chat Alice on',
+               'cmd Alice execute if entity @e[type=minecraft:item,x=10.5,y=-60,z=0.5,distance=..4]']),
+]
+STEP_SECONDS = 4.0
+SHOWN = ('slot', 'inventory', 'respawn', 'teleport', 'chat')
+
+
+def run_side(label, server_command, client_command, build, world):
+    directory = build / label
+    port = locator.server_dir(directory, world)
+    out = build / f'{label}.txt'
+    out.unlink(missing_ok=True)
+    server = Server(server_command, directory, label)
+    try:
+        server.wait_for(r'Done \(')
+        with (build / f'{label}-client.log').open('w') as log:
+            client = subprocess.Popen([*map(str, client_command), '127.0.0.1', str(port), str(out)],
+                                      cwd=lab.ROOT, stdin=subprocess.PIPE, stdout=log, stderr=subprocess.STDOUT,
+                                      text=True)
+
+            def tell(line):
+                client.stdin.write(line + '\n')
+                client.stdin.flush()
+            try:
+                tell('players on')
+                tell('state on')
+                tell('step joins')
+                tell('join Alice')
+                server.wait_for(r'Alice joined the game', timeout=120)
+                time.sleep(STEP_SECONDS)
+                for step, actions in SCRIPT:
+                    tell(f'step {step}')
+                    for action in actions:
+                        tell(action.replace('chat Alice', 'chat'))
+                    time.sleep(STEP_SECONDS)
+                tell('end')
+                client.wait(timeout=60)
+            finally:
+                if client.poll() is None:
+                    client.kill()
+    finally:
+        server.stop()
+    if not out.exists():
+        raise AssertionError(f'{label}: the client wrote no transcript (see {build}/{label}-client.log)')
+    return out.read_text(encoding='utf-8').splitlines()
+
+
+def shown(lines):
+    """Alice's slots, respawns, teleports and chat from the death on."""
+    steps = {'step=death', 'step=respawn', 'step=check'}
+    return [line for line in lines if len(parts := line.split(' ', 3)) >= 3 and parts[1] in steps
+            and parts[2] in SHOWN]
+
+
+def main():
+    lock, jars, libraries = base.verify_artifacts()
+    build = lab.LOCAL / NAME
+    build.mkdir(parents=True, exist_ok=True)
+    report = build / 'report.json'
+    report.unlink(missing_ok=True)
+    oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java'
+    classes = build / 'classes'
+    shutil.rmtree(classes, ignore_errors=True)
+    classes.mkdir()
+    dependencies = os.pathsep.join(map(str, [jars['server'], *libraries]))
+    subprocess.run(['javac', '--release', str(lock['minecraft']['java_major']), '-proc:none', '-nowarn', '-sourcepath',
+                    lab.ROOT / 'mods/horizon/src/test/java', '-cp', dependencies, '-d', classes, oracle],
+                   cwd=lab.ROOT, check=True, capture_output=True)
+    subprocess.run(['cargo', 'build', '--release', '-p', 'horizon-client', '--bin', 'horizon-client'], cwd=lab.ROOT,
+                   check=True, capture_output=True)
+    metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--no-deps', '--format-version', '1'],
+                                                  cwd=lab.ROOT, text=True))
+    binary = Path(metadata['target_directory']) / 'release' / ('horizon-client.exe' if os.name == 'nt' else 'horizon-client')
+    vanilla_server = ['java', '-Xmx2g', '-Duser.timezone=UTC', '-cp', dependencies, 'net.minecraft.server.Main', 'nogui']
+    horizon_server = [binary, '--resources', lab.LOCAL / 'horizon-client/26.3', '--dedicated', '--nogui']
+    client = ['java', '-Xmx1g', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.LocatorBarClient']
+
+    world = locator.generate_world(vanilla_server, build)
+    vanilla_all = run_side('vanilla', vanilla_server, client, build, world)
+    horizon_all = run_side('horizon', horizon_server, client, build, world)
+    errors = [l for l in vanilla_all + horizon_all if ' error ' in f' {l} ' or 'disconnected' in l]
+    vanilla, horizon = shown(vanilla_all), shown(horizon_all)
+    if errors or vanilla != horizon:
+        import difflib
+        diff = '\n'.join(difflib.unified_diff(vanilla, horizon, 'vanilla', 'horizon', n=1, lineterm=''))
+        raise AssertionError(f'{len(errors)} errors, transcripts differ (see {build}/vanilla.txt and horizon.txt):\n'
+                             + '\n'.join(errors[:10]) + '\n' + diff[:6000])
+    if not any(l.startswith('Alice step=check chat') for l in vanilla):
+        raise AssertionError(f'vanilla answered no check command: the script did not run (see {build})')
+    lab.write_json(report, dict(
+        schema=1, minecraft=lock['minecraft']['version'], platform=platform.platform(),
+        java=subprocess.check_output(['java', '--version'], text=True).splitlines()[0],
+        lines=len(vanilla), output_sha256=lab.digest(build / 'horizon.txt', 'sha256'),
+        scope='A player dying with a stack on the inventory menu cursor (keep_inventory off) and respawning on a '
+              'dedicated server: the stack is dropped where it died, not kept.'))
+    print(f'cursor death: {len(vanilla)} lines identical')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except AssertionError as error:
+        sys.exit(f'{NAME}: {error}')

From 91148cdf74b18741253bfcc20313c0f239a4c3b6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:09:48 +0100
Subject: [PATCH 114/270] Telemetry server: hub votes allow 600 an hour per
 address (bursts of 60)

A visitor voting down the roadmap, or a school behind one address, ran out of
the 12-request burst. Votes are cheap; the item cap and the voter id still bound them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-telemetry-server/README.md  | 2 +-
 crates/horizon-telemetry-server/src/lib.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-telemetry-server/README.md b/crates/horizon-telemetry-server/README.md
index 2b86bf99d..69095be73 100644
--- a/crates/horizon-telemetry-server/README.md
+++ b/crates/horizon-telemetry-server/README.md
@@ -77,7 +77,7 @@ All are environment variables:
 - `HORIZON_TELEMETRY_LIVE_PER_HOUR` per address, pings and reads (600, bursts of 60: ten players behind one address)
 - `HORIZON_TELEMETRY_LIVE_WINDOW_SECONDS` (120)
 - `HORIZON_TELEMETRY_LIVE_MAX_SESSIONS` (200 000)
-- `HORIZON_TELEMETRY_HUB_PER_HOUR` votes and vote reads per address (120, bursts of 12)
+- `HORIZON_TELEMETRY_HUB_PER_HOUR` votes and vote reads per address (600, bursts of 60: a page load is one read, and several players can share an address)
 
 ## Hosting
 
diff --git a/crates/horizon-telemetry-server/src/lib.rs b/crates/horizon-telemetry-server/src/lib.rs
index 19ba3e1dc..9c273727c 100644
--- a/crates/horizon-telemetry-server/src/lib.rs
+++ b/crates/horizon-telemetry-server/src/lib.rs
@@ -75,7 +75,7 @@ impl Default for Config {
             live_per_hour: 600.0,
             live_window: horizon_telemetry::live::WINDOW,
             live_max_sessions: 200_000,
-            hub_per_hour: 120.0,
+            hub_per_hour: 600.0,
         }
     }
 }

From bac51e3fba6922c0a10eb4105cfc68886d6ae573 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:55:50 +0100
Subject: [PATCH 115/270] Telemetry server: the hub's bug reports and
 suggestions

POST /hub/report opens a GitHub issue at once (labels bug and from-website, the
every template field required, people's text made inert (no mentions, issue
references, HTML or closing keywords) and the same report twice answered with the
first issue. If GitHub fails it answers 202 and the upkeep tries again for a week.
Off (503) without HORIZON_TELEMETRY_GITHUB_TOKEN.

POST /hub/suggest queues a suggestion; GET /hub/suggestions?after=<id> hands the
queue to Kira with the HORIZON_TELEMETRY_HUB_TOKEN bearer (404 when unset, 401 for
a wrong token). Nothing is published.

Per-address limits (20 an hour, bursts of 2) on keyed hashes of the address, daily
caps from everyone (30 reports, 200 suggestions), a honeypot field, entries kept
90 days.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-telemetry-server/Cargo.lock    |  52 +++
 crates/horizon-telemetry-server/Cargo.toml    |   2 +
 crates/horizon-telemetry-server/README.md     |  18 +-
 crates/horizon-telemetry-server/src/github.rs | 128 ++++++
 crates/horizon-telemetry-server/src/hub.rs    |  13 +-
 crates/horizon-telemetry-server/src/intake.rs | 370 ++++++++++++++++++
 crates/horizon-telemetry-server/src/lib.rs    |  80 +++-
 crates/horizon-telemetry-server/src/main.rs   |   3 +
 crates/horizon-telemetry-server/src/store.rs  |   1 +
 .../horizon-telemetry-server/tests/github.rs  |  41 ++
 crates/horizon-telemetry-server/tests/hub.rs  | 304 +++++++++++++-
 11 files changed, 990 insertions(+), 22 deletions(-)
 create mode 100644 crates/horizon-telemetry-server/src/github.rs
 create mode 100644 crates/horizon-telemetry-server/src/intake.rs
 create mode 100644 crates/horizon-telemetry-server/tests/github.rs

diff --git a/crates/horizon-telemetry-server/Cargo.lock b/crates/horizon-telemetry-server/Cargo.lock
index e4e7d060e..9b5fc960d 100644
--- a/crates/horizon-telemetry-server/Cargo.lock
+++ b/crates/horizon-telemetry-server/Cargo.lock
@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -92,6 +98,15 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 
+[[package]]
+name = "crc32fast"
+version = "1.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ba106e844045ddc02c20768ac4b0b7cb45f2cc2ecbd833ac9f5dacb183c2055"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "displaydoc"
 version = "0.2.7"
@@ -131,6 +146,17 @@ version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
 
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+ "zlib-rs",
+]
+
 [[package]]
 name = "foldhash"
 version = "0.1.5"
@@ -235,6 +261,7 @@ dependencies = [
  "serde_json",
  "tokio",
  "tower",
+ "ureq",
 ]
 
 [[package]]
@@ -473,6 +500,16 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
 [[package]]
 name = "mio"
 version = "1.2.4"
@@ -701,6 +738,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -851,10 +894,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
 dependencies = [
  "base64",
+ "flate2",
  "log",
  "once_cell",
  "rustls",
  "rustls-pki-types",
+ "serde",
+ "serde_json",
  "url",
  "webpki-roots 0.26.11",
 ]
@@ -1099,6 +1145,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "zlib-rs"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
+
 [[package]]
 name = "zmij"
 version = "1.0.23"
diff --git a/crates/horizon-telemetry-server/Cargo.toml b/crates/horizon-telemetry-server/Cargo.toml
index 8dbb0b7fd..486648b5f 100644
--- a/crates/horizon-telemetry-server/Cargo.toml
+++ b/crates/horizon-telemetry-server/Cargo.toml
@@ -19,6 +19,8 @@ rusqlite = { version = "0.37", features = ["bundled"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 ruzstd = "0.9"
+# Opens the hub's bug reports as GitHub issues (blocking, run off the async workers; rustls).
+ureq = { version = "2.12", features = ["json"] }
 
 [dev-dependencies]
 # The uploader the launcher uses, against this server, end to end.
diff --git a/crates/horizon-telemetry-server/README.md b/crates/horizon-telemetry-server/README.md
index 69095be73..a401a72b0 100644
--- a/crates/horizon-telemetry-server/README.md
+++ b/crates/horizon-telemetry-server/README.md
@@ -1,6 +1,6 @@
 # horizon-telemetry-server
 
-This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only, and the 👍 players give roadmap items on the hub (playhorizon.dev/hub). It is one small Rust process, about 7 MB of memory when idle.
+This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only, and takes what players send from the hub (playhorizon.dev/hub): votes, bug reports and suggestions. It is one small Rust process, about 7 MB of memory when idle.
 
     cargo run --release                     # in this folder: its own workspace, like the launcher's
     PORT=8080 HORIZON_TELEMETRY_DB=/data/telemetry.sqlite3 horizon-telemetry-server
@@ -17,10 +17,15 @@ It runs at **https://telemetry.playhorizon.dev** (`DEFAULT_ENDPOINT` in `crates/
 | `GET /v1/benchmarks/summary` | Players' benchmark uploads grouped by GPU, CPU, render distance and game, for the website's Benchmarks page (below). Cached 10 minutes, same `Access-Control-Allow-Origin`. |
 | `POST /v1/live` | A game's "I'm playing" ping (JSON, at most 512 bytes). Returns 204. Returns 400 for a bad ping, 413 for one too large, 429 over the address's limit, 503 when it holds `LIVE_MAX_SESSIONS` already. |
 | `GET /v1/live` | How many play now, rounded: `playing`, `lan`, `versions`, `platforms`. Made again at most every 15 seconds, with the same `Access-Control-Allow-Origin`. |
-| `POST /hub/vote` | `{"item": "<roadmap id>", "voter": "<the browser's random id>", "up": true}`: a 👍 on a roadmap item, one per voter; `"up": false` takes it back. Returns `{"item", "votes"}`. 400 for a bad id, 429 over the address's limit. `OPTIONS` answers the website's preflight. |
+| `POST /hub/vote` | `{"item": "<roadmap id>", "voter": "<the browser's random id>", "up": true}`: a 👍 on a roadmap item, one per voter; `"up": false` takes it back. Returns `{"item", "votes"}`. 400 for a bad id, 429 over the address's limit. |
 | `GET /hub/votes` | `{"votes": {"<item>": n}}`. Made again at most every minute. |
+| `POST /hub/report` | A bug report from the hub's form: `{"title", "did", "happened", "expected", "version"?, "system", "name"?}`. Opens a GitHub issue at once (labels `bug` and `from-website`, the `#horizon-bugs` template, "Reported on playhorizon.dev") and returns 201 `{"id", "issue": "<url>"}`. If GitHub fails: 202 `{"id", "issue": null}`, and the upkeep tries again for a week. The same report twice in a day returns the first one's issue. 400 for an empty or too long field, 429 over the address's limit, 503 past the day's cap or without `GITHUB_TOKEN`. |
+| `POST /hub/suggest` | `{"text", "item"?, "name"?}` into the suggestion queue. Returns 202 `{"id"}`. Never published: Kira relays it to the maintainers' private channel. |
+| `GET /hub/suggestions?after=<id>&limit=100` | The queue, oldest first, for Kira: `{"suggestions": [{"id", "text", "item"?, "name"?, "created_at"}]}`. Needs `Authorization: Bearer <HORIZON_TELEMETRY_HUB_TOKEN>`: 401 without it, 404 when the server has none. |
 | `GET /healthz` | `ok` |
 
+The hub's posts take JSON from the website (`OPTIONS` preflights answer with its origin). A form's hidden `website` field filled in (a bot) gets 202 and is dropped.
+
 The totals are grouped per version, OS, GPU vendor and render distance. Each group has its sessions, install-days, hours played, the 14 frame-time buckets summed, and the mean p50 and p99 frame times. Groups with fewer than 5 install-days are left out. The totals also list crash counts per version. Benchmark uploads are published only through the summary below, never one by one.
 
 ## Benchmarks summary
@@ -58,7 +63,7 @@ The live count is a table in memory: a session ID, when it last pinged, its vers
 
 The day stored is the day the server received an item. The sender's IP address is never written down. The per-address rate limit keeps addresses in memory for an hour at most.
 
-A hub vote is stored as an item ID and the browser's random ID. The hub's rate limits key their buckets by a hash of the address with a key drawn at each start, in memory.
+The hub keeps votes as an item ID and the browser's random ID, and reports and suggestions as their text, for `HORIZON_TELEMETRY_HUB_KEEP_DAYS` (90). Its rate limits key their buckets by a hash of the address with a key drawn at each start, in memory.
 
 Raw rows are deleted after `HORIZON_TELEMETRY_RETENTION_DAYS` (180). The daily totals stay; they hold no install ID.
 
@@ -78,6 +83,13 @@ All are environment variables:
 - `HORIZON_TELEMETRY_LIVE_WINDOW_SECONDS` (120)
 - `HORIZON_TELEMETRY_LIVE_MAX_SESSIONS` (200 000)
 - `HORIZON_TELEMETRY_HUB_PER_HOUR` votes and vote reads per address (600, bursts of 60: a page load is one read, and several players can share an address)
+- `HORIZON_TELEMETRY_HUB_POSTS_PER_HOUR` reports and suggestions per address (20, bursts of 2)
+- `HORIZON_TELEMETRY_HUB_REPORTS_PER_DAY` from everyone (30): each opens an issue
+- `HORIZON_TELEMETRY_HUB_SUGGESTIONS_PER_DAY` from everyone (200)
+- `HORIZON_TELEMETRY_HUB_KEEP_DAYS` (90)
+- `HORIZON_TELEMETRY_HUB_TOKEN`: the token Kira reads the suggestions with (unset: `GET /hub/suggestions` is off)
+- `HORIZON_TELEMETRY_GITHUB_TOKEN`: a fine-grained token with Issues read and write on the repository only (unset: `POST /hub/report` answers 503 and the form points to GitHub and Discord)
+- `HORIZON_TELEMETRY_GITHUB_REPO` (`ludovic111/horizon`)
 
 ## Hosting
 
diff --git a/crates/horizon-telemetry-server/src/github.rs b/crates/horizon-telemetry-server/src/github.rs
new file mode 100644
index 000000000..a800442e7
--- /dev/null
+++ b/crates/horizon-telemetry-server/src/github.rs
@@ -0,0 +1,128 @@
+//! A website bug report as a GitHub issue: the text made inert (no mentions, no cross-references, no HTML),
+//! written as the template Kira's `/report` and `#horizon-bugs` use, and the call that opens it.
+use std::time::Duration;
+
+use serde_json::{Map, Value, json};
+
+/// Opens an issue; its URL, or why not. The server's is [`Filer::github`]; tests give their own.
+pub type Filer = dyn Fn(&Issue) -> Result<String, String> + Send + Sync;
+
+pub struct Issue {
+    pub title: String,
+    pub body: String,
+    pub labels: Vec<String>,
+}
+
+/// Labels every website report gets.
+pub const LABELS: [&str; 2] = ["bug", "from-website"];
+
+/// Text people wrote, safe in an issue: no HTML, no `@` mentions, no `#12` or issue-URL cross-references,
+/// no closing keywords, no code spans to break out of. The same rules as Kira's `neutralise`.
+pub fn neutralise(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let chars: Vec<char> = text.chars().collect();
+    let mut i = 0;
+    while i < chars.len() {
+        let c = chars[i];
+        let next = chars.get(i + 1).copied();
+        let word_start = i == 0 || !chars[i - 1].is_alphanumeric();
+        match c {
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '`' => out.push('\''),
+            // A zero-width space after `@` or `#` keeps the text and drops the mention or the link.
+            '@' | '#' if next.is_some_and(|n| n.is_alphanumeric()) => {
+                out.push(c);
+                out.push('\u{200b}');
+            }
+            _ if word_start && closing_keyword(&chars[i..]) => {
+                out.push(c);
+                out.push('\u{200b}');
+            }
+            _ => out.push(c),
+        }
+        i += 1;
+    }
+    // github.com/owner/repo/issues/12 links cross-reference the issue: shown, not linked.
+    out.replace("github.com/", "github.com\u{200b}/")
+}
+
+fn closing_keyword(rest: &[char]) -> bool {
+    let word: String = rest
+        .iter()
+        .take_while(|c| c.is_alphabetic())
+        .flat_map(|c| c.to_lowercase())
+        .collect();
+    [
+        "close", "closes", "closed", "fix", "fixes", "fixed", "resolve", "resolves", "resolved",
+    ]
+    .contains(&word.as_str())
+}
+
+/// Text as a markdown quote, every line prefixed.
+fn quote(text: &str) -> String {
+    text.lines()
+        .map(|l| format!("> {l}").trim_end().to_owned())
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+/// The issue for a report's fields (`hub::REPORT`'s names, already checked).
+pub fn issue(fields: &Map<String, Value>) -> Issue {
+    let field = |name: &str| {
+        fields
+            .get(name)
+            .and_then(Value::as_str)
+            .map(neutralise)
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "not given".into())
+    };
+    let title = neutralise(&field("title").replace(['\n', '\r'], " "));
+    let text = [
+        format!("**What I did:**\n{}", field("did")),
+        format!("**What happened:**\n{}", field("happened")),
+        format!("**What I expected:**\n{}", field("expected")),
+        format!("**Horizon version:** {}", field("version")),
+        format!("**OS, CPU, GPU:** {}", field("system")),
+    ]
+    .join("\n");
+    let by = fields
+        .get("name")
+        .and_then(Value::as_str)
+        .map(|n| neutralise(n).replace(['*', '_', '~', '|', '[', ']'], ""))
+        .filter(|n| !n.is_empty())
+        .map(|n| format!(" by **{n}**"))
+        .unwrap_or_default();
+    let body = format!(
+        "{}\n\nReported on playhorizon.dev{by}\n\n<sub>Opened by the bug form on playhorizon.dev/hub. The reporter has this issue's link; they don't get GitHub notifications.</sub>",
+        quote(&text)
+    );
+    Issue {
+        title,
+        body,
+        labels: LABELS.iter().map(|l| (*l).to_owned()).collect(),
+    }
+}
+
+/// Opens issues in `repo` (`owner/name`) with `token` (a fine-grained token with Issues: write on that repo
+/// only). Errors never carry the token or GitHub's answer body.
+pub fn github(repo: String, token: String) -> Box<Filer> {
+    Box::new(move |issue: &Issue| {
+        let response = ureq::post(&format!("https://api.github.com/repos/{repo}/issues"))
+            .set("Authorization", &format!("Bearer {token}"))
+            .set("Accept", "application/vnd.github+json")
+            .set("X-GitHub-Api-Version", "2022-11-28")
+            .set("User-Agent", "horizon-telemetry-server")
+            .timeout(Duration::from_secs(20))
+            .send_json(json!({ "title": issue.title, "body": issue.body, "labels": issue.labels }));
+        match response {
+            Ok(response) => response
+                .into_json::<Value>()
+                .ok()
+                .and_then(|v| v["html_url"].as_str().map(str::to_owned))
+                .ok_or_else(|| "GitHub's answer had no issue URL".into()),
+            Err(ureq::Error::Status(code, _)) => Err(format!("GitHub answered {code}")),
+            Err(ureq::Error::Transport(e)) => Err(format!("could not reach GitHub: {}", e.kind())),
+        }
+    })
+}
diff --git a/crates/horizon-telemetry-server/src/hub.rs b/crates/horizon-telemetry-server/src/hub.rs
index ebf22610d..eb92cd692 100644
--- a/crates/horizon-telemetry-server/src/hub.rs
+++ b/crates/horizon-telemetry-server/src/hub.rs
@@ -1,4 +1,5 @@
-//! The hub's votes: a 👍 on a roadmap item at playhorizon.dev/hub. roadmap/README.md documents them for Kira and the website.
+//! The hub's votes: a 👍 on a roadmap item at playhorizon.dev/hub, and the helpers the hub's other
+//! endpoints (`intake`) share. roadmap/README.md documents them for Kira and the website.
 //!
 //! - `POST /hub/vote`: a 👍 on a roadmap item, one per browser (`voter`, a random id the page makes and
 //!   keeps); `"up": false` takes it back. Answers the item's count.
@@ -114,10 +115,12 @@ impl App {
 
     /// The hub's share of `maintain`: idle buckets are forgotten.
     pub(crate) fn forget_hub_buckets(&self) {
-        self.hub_buckets
-            .lock()
-            .unwrap_or_else(|e| e.into_inner())
-            .retain(|_, (_, at)| at.elapsed() < Duration::from_secs(3600));
+        for buckets in [&self.hub_buckets, &self.hub_post_buckets] {
+            buckets
+                .lock()
+                .unwrap_or_else(|e| e.into_inner())
+                .retain(|_, (_, at)| at.elapsed() < Duration::from_secs(3600));
+        }
     }
 }
 
diff --git a/crates/horizon-telemetry-server/src/intake.rs b/crates/horizon-telemetry-server/src/intake.rs
new file mode 100644
index 000000000..59ce57141
--- /dev/null
+++ b/crates/horizon-telemetry-server/src/intake.rs
@@ -0,0 +1,370 @@
+//! What players send from the hub (playhorizon.dev/hub) for the maintainers: bug reports and suggestions.
+//! roadmap/README.md documents it for Kira and the website.
+//!
+//! - `POST /hub/report`: a bug report, opened at once as a GitHub issue (labels `bug`, `from-website`) in
+//!   the template Kira's `/report` uses (`github`). Kept and tried again by the upkeep if GitHub fails.
+//! - `POST /hub/suggest`: a suggestion, into the queue. Never published: Kira relays it to the
+//!   maintainers' private channel.
+//! - `GET /hub/suggestions?after=<id>`: the queue for Kira, with the `HORIZON_TELEMETRY_HUB_TOKEN` bearer.
+//!
+//! Stored: reports and suggestions as their text, for `hub_keep_days`. Never an IP address.
+use std::sync::Arc;
+
+use axum::extract::{Query, Request, State};
+use axum::http::{HeaderMap, HeaderValue, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use rusqlite::params;
+use serde::Deserialize;
+use serde_json::{Map, Value, json};
+
+use crate::hub::{answer, item_id, json_body, refuse};
+use crate::store::Store;
+use crate::{App, github, take, utc_now};
+
+pub const SCHEMA: &str = "
+CREATE TABLE IF NOT EXISTS hub_queue (
+    id INTEGER PRIMARY KEY, kind TEXT NOT NULL, day INTEGER NOT NULL, created TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'new', issue TEXT NOT NULL DEFAULT '', body TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS hub_queue_kind ON hub_queue (kind, state, id);
+";
+
+/// Days the upkeep keeps trying to open a report's issue.
+const RETRY_DAYS: u32 = 7;
+
+/// A field's rules: its name, whether it is needed, its length in characters, whether it may hold lines.
+struct Field(&'static str, bool, std::ops::RangeInclusive<usize>, bool);
+
+/// A bug report: the `#horizon-bugs` template's fields.
+const REPORT: &[Field] = &[
+    Field("title", true, 5..=120, false),
+    Field("did", true, 3..=2000, true),
+    Field("happened", true, 3..=2000, true),
+    Field("expected", true, 3..=2000, true),
+    Field("version", false, 0..=60, false),
+    Field("system", true, 3..=200, false),
+    Field("name", false, 0..=64, false),
+];
+const SUGGESTION: &[Field] = &[
+    Field("text", true, 10..=1000, true),
+    Field("item", false, 0..=48, false),
+    Field("name", false, 0..=64, false),
+];
+
+/// Text as stored: no control characters but line breaks (where allowed), trimmed.
+fn clean(text: &str, lines: bool) -> String {
+    let text = text.replace("\r\n", "\n");
+    let kept: String = text
+        .chars()
+        .map(|c| if !lines && c == '\n' { ' ' } else { c })
+        .filter(|c| !c.is_control() || (lines && *c == '\n'))
+        .collect();
+    kept.trim().to_owned()
+}
+
+/// The request's fields checked against `rules`: the cleaned object, or what is wrong.
+fn fields(body: &Value, rules: &[Field]) -> Result<Map<String, Value>, String> {
+    let object = body.as_object().ok_or("send a JSON object")?;
+    let mut out = Map::new();
+    for Field(name, needed, length, lines) in rules {
+        let text = match object.get(*name) {
+            None | Some(Value::Null) => String::new(),
+            Some(Value::String(s)) => clean(s, *lines),
+            Some(_) => return Err(format!("{name} is text")),
+        };
+        if text.is_empty() && !needed {
+            continue;
+        }
+        if !length.contains(&text.chars().count()) {
+            return Err(format!(
+                "{name}: {} to {} characters",
+                length.start(),
+                length.end()
+            ));
+        }
+        out.insert((*name).to_owned(), Value::String(text));
+    }
+    Ok(out)
+}
+
+impl Store {
+    /// How many entries of `kind` came in on `day`.
+    pub fn queued_on(&self, kind: &str, day: u32) -> rusqlite::Result<u32> {
+        self.db.query_row(
+            "SELECT count(*) FROM hub_queue WHERE kind = ?1 AND day = ?2",
+            params![kind, day],
+            |r| r.get(0),
+        )
+    }
+
+    /// Queues an entry: its id, and its issue when the same text already came in since `since` and was
+    /// opened (a double click, a form sent twice).
+    pub fn enqueue(
+        &mut self,
+        kind: &str,
+        day: u32,
+        since: u32,
+        body: &Map<String, Value>,
+    ) -> rusqlite::Result<(i64, Option<String>)> {
+        let body = Value::Object(body.clone()).to_string();
+        let same = self
+            .db
+            .prepare(
+                "SELECT id, issue FROM hub_queue WHERE kind = ?1 AND body = ?2 AND day >= ?3 LIMIT 1",
+            )?
+            .query_row(params![kind, body, since], |r| {
+                Ok((r.get::<_, i64>(0)?, r.get::<_, String>(1)?))
+            });
+        match same {
+            Ok((id, issue)) => return Ok((id, Some(issue).filter(|i| !i.is_empty()))),
+            Err(rusqlite::Error::QueryReturnedNoRows) => {}
+            Err(e) => return Err(e),
+        }
+        self.db.execute(
+            "INSERT INTO hub_queue (kind, day, created, body) VALUES (?1, ?2, ?3, ?4)",
+            params![kind, day, utc_now(), body],
+        )?;
+        Ok((self.db.last_insert_rowid(), None))
+    }
+
+    /// Suggestions after `after`, oldest first: `{id, text, item?, name?, created_at}`.
+    pub fn suggestions(&self, after: i64, limit: u32) -> rusqlite::Result<Vec<Value>> {
+        let mut statement = self.db.prepare(
+            "SELECT id, created, body FROM hub_queue WHERE kind = 'suggestion' AND id > ?1 ORDER BY id LIMIT ?2",
+        )?;
+        let rows = statement.query_map(params![after, limit], |r| {
+            let mut entry: Map<String, Value> =
+                serde_json::from_str(&r.get::<_, String>(2)?).unwrap_or_default();
+            entry.insert("id".into(), r.get::<_, i64>(0)?.into());
+            entry.insert("created_at".into(), r.get::<_, String>(1)?.into());
+            Ok(Value::Object(entry))
+        })?;
+        rows.collect()
+    }
+
+    /// Reports whose issue isn't open yet, from `since` on: id and fields.
+    pub fn unfiled(&self, since: u32) -> rusqlite::Result<Vec<(i64, Map<String, Value>)>> {
+        let mut statement = self.db.prepare(
+            "SELECT id, body FROM hub_queue WHERE kind = 'report' AND state = 'new' AND day >= ?1 ORDER BY id",
+        )?;
+        let rows = statement.query_map([since], |r| {
+            Ok((
+                r.get::<_, i64>(0)?,
+                serde_json::from_str(&r.get::<_, String>(1)?).unwrap_or_default(),
+            ))
+        })?;
+        rows.collect()
+    }
+
+    /// Marks a report as opened: `issue` is its URL.
+    pub fn filed(&mut self, id: i64, issue: &str) -> rusqlite::Result<()> {
+        self.db.execute(
+            "UPDATE hub_queue SET state = 'filed', issue = ?2 WHERE id = ?1",
+            params![id, issue],
+        )?;
+        Ok(())
+    }
+
+    /// Reports from before `retry_from` that never got an issue are given up; entries before `oldest_day`
+    /// go.
+    pub fn expire_queue(&mut self, oldest_day: u32, retry_from: u32) -> rusqlite::Result<usize> {
+        self.db.execute(
+            "UPDATE hub_queue SET state = 'failed' WHERE kind = 'report' AND state = 'new' AND day < ?1",
+            [retry_from],
+        )?;
+        self.db
+            .execute("DELETE FROM hub_queue WHERE day < ?1", [oldest_day])
+    }
+}
+
+impl App {
+    /// The same for reports and suggestions, a much smaller bucket.
+    fn allow_post(&self, req: &Request) -> bool {
+        take(
+            &self.hub_post_buckets,
+            self.config.hub_posts_per_hour,
+            self.hashed(req),
+        )
+    }
+
+    /// Opens the reports whose issue isn't open yet (the upkeep calls it off the async workers; it blocks).
+    /// Stops at the first failure: GitHub is down or the token is wrong, the next round tries again.
+    pub fn file_pending(&self) {
+        let Some(filer) = &self.filer else { return };
+        let since = (self.today)().saturating_sub(RETRY_DAYS);
+        let pending = self.store().unfiled(since).unwrap_or_default();
+        for (id, fields) in pending {
+            match filer(&github::issue(&fields)) {
+                Ok(url) => self.mark_filed(id, &url),
+                Err(e) => {
+                    eprintln!("horizon-telemetry-server: report {id} still not opened: {e}");
+                    return;
+                }
+            }
+        }
+    }
+
+    fn mark_filed(&self, id: i64, url: &str) {
+        let marked = self.store().filed(id, url);
+        if let Err(e) = marked {
+            eprintln!("horizon-telemetry-server: report {id} opened as {url}, not marked: {e}");
+        }
+    }
+
+    /// The intake's share of `maintain`: entries past `hub_keep_days` go, reports never opened after
+    /// [`RETRY_DAYS`] are given up.
+    pub(crate) fn expire_intake(&self) -> rusqlite::Result<usize> {
+        let today = (self.today)();
+        self.store().expire_queue(
+            today.saturating_sub(self.config.hub_keep_days),
+            today.saturating_sub(RETRY_DAYS),
+        )
+    }
+}
+
+/// What `receive` keeps: the entry's id, its issue if already opened, its fields.
+type Received = (i64, Option<String>, Map<String, Value>);
+
+/// Checks a report or a suggestion and queues it.
+async fn receive(
+    app: &App,
+    req: Request,
+    kind: &str,
+    rules: &[Field],
+    per_day: u32,
+) -> Result<Received, Box<Response>> {
+    let no = |code: StatusCode, message: &str| Box::new(refuse(app, code, message));
+    if !app.allow_post(&req) {
+        return Err(no(StatusCode::TOO_MANY_REQUESTS, "too many requests"));
+    }
+    let body = json_body(req)
+        .await
+        .map_err(|e| no(StatusCode::BAD_REQUEST, e))?;
+    // The form's hidden field, which people leave empty and form-filling bots don't: thanked, dropped.
+    if body["website"].as_str().is_some_and(|s| !s.is_empty()) {
+        let thanks = answer(app, StatusCode::ACCEPTED, json!({ "id": 0 }));
+        return Err(Box::new(thanks));
+    }
+    let entry = fields(&body, rules).map_err(|e| no(StatusCode::BAD_REQUEST, &e))?;
+    if let Some(item) = entry.get("item").and_then(Value::as_str)
+        && !item_id(item)
+    {
+        return Err(no(StatusCode::BAD_REQUEST, "item: a roadmap item id"));
+    }
+    let today = (app.today)();
+    let mut store = app.store();
+    if store.queued_on(kind, today).unwrap_or(u32::MAX) >= per_day {
+        let full = "too many today: please try again tomorrow";
+        return Err(no(StatusCode::SERVICE_UNAVAILABLE, full));
+    }
+    match store.enqueue(kind, today, today.saturating_sub(1), &entry) {
+        Ok((id, issue)) => Ok((id, issue, entry)),
+        Err(e) => {
+            eprintln!("horizon-telemetry-server: could not queue a {kind}: {e}");
+            Err(no(StatusCode::SERVICE_UNAVAILABLE, "try again later"))
+        }
+    }
+}
+
+/// `POST /hub/report` `{"title", "did", "happened", "expected", "version"?, "system", "name"?}`: 201
+/// `{"id", "issue"}` once the issue is open, 202 `{"id", "issue": null}` when GitHub failed and the upkeep
+/// will try again; 503 when reports are off (no GitHub token).
+pub async fn report(State(app): State<Arc<App>>, req: Request) -> Response {
+    let Some(filer) = app.filer.clone() else {
+        return refuse(
+            &app,
+            StatusCode::SERVICE_UNAVAILABLE,
+            "reports are closed here: use GitHub or Discord",
+        );
+    };
+    let per_day = app.config.hub_reports_per_day;
+    let (id, issue, fields) = match receive(&app, req, "report", REPORT, per_day).await {
+        Ok(received) => received,
+        Err(response) => return *response,
+    };
+    if let Some(issue) = issue {
+        return answer(
+            &app,
+            StatusCode::CREATED,
+            json!({ "id": id, "issue": issue }),
+        );
+    }
+    let opened = tokio::task::spawn_blocking(move || filer(&github::issue(&fields)))
+        .await
+        .map_err(|e| e.to_string())
+        .and_then(|opened| opened);
+    match opened {
+        Ok(url) => {
+            app.mark_filed(id, &url);
+            answer(&app, StatusCode::CREATED, json!({ "id": id, "issue": url }))
+        }
+        Err(e) => {
+            eprintln!("horizon-telemetry-server: report {id} not opened yet: {e}");
+            answer(
+                &app,
+                StatusCode::ACCEPTED,
+                json!({ "id": id, "issue": null }),
+            )
+        }
+    }
+}
+
+/// `POST /hub/suggest` `{"text", "item"?, "name"?}`: 202 `{"id"}`.
+pub async fn suggest(State(app): State<Arc<App>>, req: Request) -> Response {
+    let per_day = app.config.hub_suggestions_per_day;
+    match receive(&app, req, "suggestion", SUGGESTION, per_day).await {
+        Ok((id, ..)) => answer(&app, StatusCode::ACCEPTED, json!({ "id": id })),
+        Err(response) => *response,
+    }
+}
+
+#[derive(Deserialize)]
+pub struct After {
+    after: Option<i64>,
+    limit: Option<u32>,
+}
+
+/// `GET /hub/suggestions?after=<id>&limit=100` with `Authorization: Bearer <HORIZON_TELEMETRY_HUB_TOKEN>`:
+/// `{"suggestions": [{"id", "text", "item"?, "name"?, "created_at"}]}`, oldest first. 404 when no token is
+/// set, 401 for a wrong one.
+pub async fn suggestions(
+    State(app): State<Arc<App>>,
+    headers: HeaderMap,
+    Query(after): Query<After>,
+) -> Response {
+    let Some(token) = app.config.hub_token.as_deref() else {
+        return StatusCode::NOT_FOUND.into_response();
+    };
+    let sent = headers
+        .get(header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "))
+        .unwrap_or("");
+    if !same(sent.as_bytes(), token.as_bytes()) {
+        return StatusCode::UNAUTHORIZED.into_response();
+    }
+    let limit = after.limit.unwrap_or(100).clamp(1, 500);
+    let listed = app.store().suggestions(after.after.unwrap_or(0), limit);
+    match listed {
+        Ok(list) => (
+            [
+                (
+                    header::CONTENT_TYPE,
+                    HeaderValue::from_static("application/json"),
+                ),
+                (header::CACHE_CONTROL, HeaderValue::from_static("no-store")),
+            ],
+            json!({ "suggestions": list }).to_string(),
+        )
+            .into_response(),
+        Err(e) => {
+            eprintln!("horizon-telemetry-server: could not read the suggestions: {e}");
+            StatusCode::SERVICE_UNAVAILABLE.into_response()
+        }
+    }
+}
+
+/// Equal, in a time that doesn't depend on where they differ.
+fn same(a: &[u8], b: &[u8]) -> bool {
+    a.len() == b.len() && a.iter().zip(b).fold(0, |diff, (x, y)| diff | (x ^ y)) == 0
+}
diff --git a/crates/horizon-telemetry-server/src/lib.rs b/crates/horizon-telemetry-server/src/lib.rs
index 9c273727c..3ab923969 100644
--- a/crates/horizon-telemetry-server/src/lib.rs
+++ b/crates/horizon-telemetry-server/src/lib.rs
@@ -7,7 +7,7 @@
 //!   least 3 installs only (`summary`), cached; the website's Benchmarks page reads it.
 //! - `POST /v1/live`: a game's anonymous "I'm playing" ping (`live`, in memory only).
 //! - `GET /v1/live`: how many play now, rounded, cached briefly.
-//! - `POST /hub/vote`, `GET /hub/votes`: the hub's 👍 on roadmap items (`hub`).
+//! - `/hub/…`: the hub's votes (`hub`), bug reports and suggestions (`intake`).
 //! - `GET /healthz`.
 //!
 //! Abuse limits: a token bucket per IP address (kept in memory for an hour, never stored), a
@@ -29,11 +29,14 @@ use axum::routing::{delete, get, post};
 use horizon_telemetry::batch;
 
 pub mod classes;
+pub mod github;
 pub mod hub;
+pub mod intake;
 pub mod live;
 pub mod store;
 pub mod summary;
 
+use github::Filer;
 use horizon_telemetry::live::{MAX_PING_BYTES, Ping};
 use live::Live;
 use store::Store;
@@ -61,6 +64,20 @@ pub struct Config {
     pub live_max_sessions: usize,
     /// The hub's votes and reads of their counts an IP address may make an hour.
     pub hub_per_hour: f64,
+    /// Bug reports and suggestions together an IP address may send an hour.
+    pub hub_posts_per_hour: f64,
+    /// Bug reports taken a day, from everyone: each one opens a GitHub issue.
+    pub hub_reports_per_day: u32,
+    /// Suggestions taken a day, from everyone.
+    pub hub_suggestions_per_day: u32,
+    /// Days reports and suggestions are kept (Kira has relayed them long before).
+    pub hub_keep_days: u32,
+    /// The bearer token `GET /hub/suggestions` wants (Kira's); unset, it answers 404.
+    pub hub_token: Option<String>,
+    /// Opens the website's bug reports as issues; unset, `POST /hub/report` answers 503.
+    pub github_token: Option<String>,
+    /// Where those issues go, `owner/name`.
+    pub github_repo: String,
 }
 
 impl Default for Config {
@@ -76,6 +93,13 @@ impl Default for Config {
             live_window: horizon_telemetry::live::WINDOW,
             live_max_sessions: 200_000,
             hub_per_hour: 600.0,
+            hub_posts_per_hour: 20.0,
+            hub_reports_per_day: 30,
+            hub_suggestions_per_day: 200,
+            hub_keep_days: 90,
+            hub_token: None,
+            github_token: None,
+            github_repo: "ludovic111/horizon".into(),
         }
     }
 }
@@ -83,9 +107,16 @@ impl Default for Config {
 impl Config {
     /// The defaults, with `HORIZON_TELEMETRY_RETENTION_DAYS`, `…_MIN_INSTALL_DAYS`,
     /// `…_REQUESTS_PER_HOUR`, `…_ITEMS_PER_DAY`, `…_TRUST_PROXY` (1), `…_ALLOW_ORIGIN`,
-    /// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS`, `…_LIVE_MAX_SESSIONS` and `…_HUB_PER_HOUR`.
+    /// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS`, `…_LIVE_MAX_SESSIONS`, `…_HUB_PER_HOUR`,
+    /// `…_HUB_POSTS_PER_HOUR`, `…_HUB_REPORTS_PER_DAY`, `…_HUB_SUGGESTIONS_PER_DAY`, `…_HUB_KEEP_DAYS`,
+    /// `…_HUB_TOKEN`, `…_GITHUB_TOKEN` and `…_GITHUB_REPO`. Empty tokens count as unset.
     pub fn from_env() -> Self {
         let var = |k: &str| std::env::var(format!("HORIZON_TELEMETRY_{k}")).ok();
+        let secret = |k: &str| {
+            var(k)
+                .map(|v| v.trim().to_owned())
+                .filter(|v| !v.is_empty())
+        };
         let d = Self::default();
         Self {
             retention_days: var("RETENTION_DAYS")
@@ -114,6 +145,21 @@ impl Config {
             hub_per_hour: var("HUB_PER_HOUR")
                 .and_then(|v| v.parse().ok())
                 .unwrap_or(d.hub_per_hour),
+            hub_posts_per_hour: var("HUB_POSTS_PER_HOUR")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(d.hub_posts_per_hour),
+            hub_reports_per_day: var("HUB_REPORTS_PER_DAY")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(d.hub_reports_per_day),
+            hub_suggestions_per_day: var("HUB_SUGGESTIONS_PER_DAY")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(d.hub_suggestions_per_day),
+            hub_keep_days: var("HUB_KEEP_DAYS")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(d.hub_keep_days),
+            hub_token: secret("HUB_TOKEN"),
+            github_token: secret("GITHUB_TOKEN"),
+            github_repo: var("GITHUB_REPO").unwrap_or(d.github_repo),
         }
     }
 }
@@ -139,8 +185,12 @@ pub struct App {
     hub_key: RandomState,
     /// The hub's votes and vote counts, per hashed address.
     hub_buckets: Mutex<hub::HashedBuckets>,
+    /// The hub's reports and suggestions, per hashed address.
+    hub_post_buckets: Mutex<hub::HashedBuckets>,
     /// `GET /hub/votes`'s answer and when it was made.
     votes_cache: Mutex<Option<(Instant, String)>>,
+    /// Opens bug reports as GitHub issues; None without a token.
+    filer: Option<Arc<Filer>>,
 }
 
 type Buckets = HashMap<IpAddr, (f64, Instant)>;
@@ -160,6 +210,20 @@ impl App {
         store: Store,
         config: Config,
         today: Box<dyn Fn() -> u32 + Send + Sync>,
+    ) -> Arc<Self> {
+        let filer = config
+            .github_token
+            .clone()
+            .map(|token| Arc::from(github::github(config.github_repo.clone(), token)));
+        Self::with_filer(store, config, today, filer)
+    }
+
+    /// [`Self::with_clock`] with the hub's bug reports opened by `filer` (tests give their own).
+    pub fn with_filer(
+        store: Store,
+        config: Config,
+        today: Box<dyn Fn() -> u32 + Send + Sync>,
+        filer: Option<Arc<Filer>>,
     ) -> Arc<Self> {
         let live = Live::new(config.live_window, config.live_max_sessions);
         Arc::new(Self {
@@ -174,7 +238,9 @@ impl App {
             today,
             hub_key: RandomState::new(),
             hub_buckets: Mutex::default(),
+            hub_post_buckets: Mutex::default(),
             votes_cache: Mutex::default(),
+            filer,
         })
     }
 
@@ -235,10 +301,12 @@ impl App {
     }
 
     /// Daily upkeep: totals rebuilt, expired rows removed, idle rate-limit entries and live
-    /// sessions forgotten.
+    /// sessions forgotten, the hub's old reports and suggestions removed. Reports still waiting for
+    /// their issue are [`Self::file_pending`]'s.
     pub fn maintain(&self) -> rusqlite::Result<usize> {
         let oldest = (self.today)().saturating_sub(self.config.retention_days);
         let removed = self.store().expire(oldest)?;
+        self.expire_intake()?;
         self.forget_hub_buckets();
         for buckets in [&self.buckets, &self.live_buckets] {
             buckets
@@ -503,6 +571,12 @@ pub fn router(app: Arc<App>) -> Router {
         .route("/v1/benchmarks/summary", get(benchmarks))
         .route("/hub/vote", post(hub::vote).options(hub::preflight))
         .route("/hub/votes", get(hub::votes))
+        .route("/hub/report", post(intake::report).options(hub::preflight))
+        .route(
+            "/hub/suggest",
+            post(intake::suggest).options(hub::preflight),
+        )
+        .route("/hub/suggestions", get(intake::suggestions))
         .route("/healthz", get(|| async { "ok" }))
         .with_state(app)
 }
diff --git a/crates/horizon-telemetry-server/src/main.rs b/crates/horizon-telemetry-server/src/main.rs
index 9b9c702c3..728846a0f 100644
--- a/crates/horizon-telemetry-server/src/main.rs
+++ b/crates/horizon-telemetry-server/src/main.rs
@@ -22,6 +22,9 @@ async fn main() {
             if let Err(e) = upkeep.maintain() {
                 eprintln!("horizon-telemetry-server: upkeep failed: {e}");
             }
+            // The hub's reports GitHub refused before: their issues, off the async workers.
+            let filing = upkeep.clone();
+            let _ = tokio::task::spawn_blocking(move || filing.file_pending()).await;
         }
     });
     let listener = tokio::net::TcpListener::bind(SocketAddr::from(([0, 0, 0, 0], port)))
diff --git a/crates/horizon-telemetry-server/src/store.rs b/crates/horizon-telemetry-server/src/store.rs
index d1137d197..9286dd36a 100644
--- a/crates/horizon-telemetry-server/src/store.rs
+++ b/crates/horizon-telemetry-server/src/store.rs
@@ -131,6 +131,7 @@ impl Store {
         let mut db = Connection::open(path)?;
         db.execute_batch(SCHEMA)?;
         db.execute_batch(crate::hub::SCHEMA)?;
+        db.execute_batch(crate::intake::SCHEMA)?;
         migrate(&mut db)?;
         Ok(Self { db })
     }
diff --git a/crates/horizon-telemetry-server/tests/github.rs b/crates/horizon-telemetry-server/tests/github.rs
new file mode 100644
index 000000000..81f480b58
--- /dev/null
+++ b/crates/horizon-telemetry-server/tests/github.rs
@@ -0,0 +1,41 @@
+//! A website bug report as the issue GitHub gets: the template, and people's text made inert.
+use horizon_telemetry_server::github::{issue, neutralise};
+use serde_json::{Map, Value, json};
+
+#[test]
+fn people_text_mentions_and_references_nothing() {
+    let text =
+        neutralise("@octocat see #12 and https://github.com/a/b/issues/3 <img src=x> `x` Fixes it");
+    assert!(!text.contains("@o") && !text.contains("#1") && !text.contains("github.com/"));
+    assert!(!text.contains('<') && !text.contains('`'));
+    assert!(text.contains("F\u{200b}ixes"));
+    // Words that only start like a keyword stay as they are.
+    assert_eq!(neutralise("closet fixture"), "closet fixture");
+}
+
+#[test]
+fn a_report_reads_as_the_template() {
+    let fields: Map<String, Value> = serde_json::from_value(json!({
+        "title": "Water is black\non AMD", "did": "Opened a world", "happened": "Black water",
+        "expected": "Blue water", "system": "Windows 11, RX 6600", "name": "steve_"
+    }))
+    .unwrap();
+    let issue = issue(&fields);
+    assert_eq!(issue.title, "Water is black on AMD");
+    assert!(
+        issue
+            .body
+            .starts_with("> **What I did:**\n> Opened a world\n> **What happened:**")
+    );
+    assert!(
+        issue
+            .body
+            .contains("> **Horizon version:** not given\n> **OS, CPU, GPU:** Windows 11, RX 6600")
+    );
+    assert!(
+        issue
+            .body
+            .contains("Reported on playhorizon.dev by **steve**")
+    );
+    assert_eq!(issue.labels, ["bug", "from-website"]);
+}
diff --git a/crates/horizon-telemetry-server/tests/hub.rs b/crates/horizon-telemetry-server/tests/hub.rs
index 10ddc12c4..056978212 100644
--- a/crates/horizon-telemetry-server/tests/hub.rs
+++ b/crates/horizon-telemetry-server/tests/hub.rs
@@ -1,8 +1,11 @@
-//! The hub's votes through the HTTP interface.
-use std::sync::Arc;
+//! The hub's intake through its HTTP interface: votes, bug reports (opened as issues by a fake GitHub),
+//! suggestions and the queue Kira reads.
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::{Arc, Mutex};
 
 use axum::body::Body;
 use axum::http::{Request, StatusCode};
+use horizon_telemetry_server::github::{Filer, Issue};
 use horizon_telemetry_server::store::Store;
 use horizon_telemetry_server::{App, Config, router};
 use http_body_util::BodyExt;
@@ -12,17 +15,54 @@ use tower::ServiceExt;
 const DAY: u32 = 20_741;
 const VOTER: &str = "0b7c3c9e-3f0a-4d8e-9a39-4c1f5a6b7d21";
 
+/// The issues the fake GitHub opened, and whether it is up.
+#[derive(Default)]
+struct GitHub {
+    opened: Mutex<Vec<Issue>>,
+    down: Mutex<bool>,
+}
+
 struct Hub {
     app: Arc<App>,
+    github: Arc<GitHub>,
+    day: Arc<AtomicU32>,
 }
 
 fn hub(config: Config) -> Hub {
-    let app = App::with_clock(Store::open(":memory:").unwrap(), config, Box::new(|| DAY));
-    Hub { app }
+    let github = Arc::new(GitHub::default());
+    let fake = github.clone();
+    let filer: Arc<Filer> = Arc::new(move |issue: &Issue| {
+        if *fake.down.lock().unwrap() {
+            return Err("GitHub answered 502".into());
+        }
+        let mut opened = fake.opened.lock().unwrap();
+        opened.push(Issue {
+            title: issue.title.clone(),
+            body: issue.body.clone(),
+            labels: issue.labels.clone(),
+        });
+        Ok(format!(
+            "https://github.com/ludovic111/horizon/issues/{}",
+            1000 + opened.len()
+        ))
+    });
+    let day = Arc::new(AtomicU32::new(DAY));
+    let clock = day.clone();
+    let app = App::with_filer(
+        Store::open(":memory:").unwrap(),
+        config,
+        Box::new(move || clock.load(Ordering::SeqCst)),
+        Some(filer),
+    );
+    Hub { app, github, day }
 }
 
 fn config() -> Config {
-    Config::default()
+    Config {
+        hub_token: Some("kira-secret".into()),
+        hub_posts_per_hour: 1000.0,
+        ..Config::default()
+    }
 }
 
 impl Hub {
@@ -43,12 +83,27 @@ impl Hub {
         .await
     }
 
-    async fn get(&self, path: &str) -> (StatusCode, Value) {
-        self.send(Request::get(path).body(Body::empty()).unwrap())
-            .await
+    async fn get(&self, path: &str, token: Option<&str>) -> (StatusCode, Value) {
+        let mut req = Request::get(path);
+        if let Some(token) = token {
+            req = req.header("authorization", format!("Bearer {token}"));
+        }
+        self.send(req.body(Body::empty()).unwrap()).await
     }
 }
 
+fn report(title: &str) -> Value {
+    json!({
+        "title": title,
+        "did": "Opened a new world\nWalked to the sea",
+        "happened": "The water is black",
+        "expected": "Blue water, as in vanilla",
+        "version": "v0.2.57",
+        "system": "Windows 11, Ryzen 5 5600, RX 6600",
+        "website": "",
+    })
+}
+
 #[tokio::test]
 async fn votes_count_once_per_browser_and_can_be_taken_back() {
     let hub = hub(config());
@@ -71,7 +126,7 @@ async fn votes_count_once_per_browser_and_can_be_taken_back() {
         2
     );
     assert_eq!(
-        hub.get("/hub/votes").await,
+        hub.get("/hub/votes", None).await,
         (StatusCode::OK, json!({ "votes": { "smooth-frames": 2 } }))
     );
     assert_eq!(
@@ -79,7 +134,7 @@ async fn votes_count_once_per_browser_and_can_be_taken_back() {
         1
     );
     assert_eq!(
-        hub.get("/hub/votes").await.1["votes"]["smooth-frames"],
+        hub.get("/hub/votes", None).await.1["votes"]["smooth-frames"],
         1,
         "a vote drops the cached counts"
     );
@@ -92,12 +147,239 @@ async fn votes_count_once_per_browser_and_can_be_taken_back() {
     }
 }
 
+#[tokio::test]
+async fn a_report_becomes_an_issue_in_the_bug_template() {
+    let hub = hub(config());
+    let (code, body) = hub
+        .post("/hub/report", report("Water is black on AMD"))
+        .await;
+    assert_eq!(code, StatusCode::CREATED);
+    assert_eq!(
+        body["issue"],
+        "https://github.com/ludovic111/horizon/issues/1001"
+    );
+    let issue = hub.github.opened.lock().unwrap().remove(0);
+    assert_eq!(issue.title, "Water is black on AMD");
+    assert_eq!(issue.labels, ["bug", "from-website"]);
+    for line in [
+        "> **What I did:**\n> Opened a new world\n> Walked to the sea",
+        "> **What happened:**\n> The water is black",
+        "> **What I expected:**\n> Blue water, as in vanilla",
+        "> **Horizon version:** v0.2.57",
+        "> **OS, CPU, GPU:** Windows 11, Ryzen 5 5600, RX 6600",
+        "Reported on playhorizon.dev",
+    ] {
+        assert!(issue.body.contains(line), "{line}\n---\n{}", issue.body);
+    }
+    // The same report again (a double click) answers the same issue and opens nothing.
+    let (code, again) = hub
+        .post("/hub/report", report("Water is black on AMD"))
+        .await;
+    assert_eq!(
+        (code, &again["issue"]),
+        (StatusCode::CREATED, &body["issue"])
+    );
+    assert!(hub.github.opened.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn reports_need_every_template_field_and_skip_bots() {
+    let hub = hub(config());
+    for empty in ["title", "did", "happened", "expected", "system"] {
+        let mut body = report("Water is black on AMD");
+        body[empty] = json!("   ");
+        let (code, answer) = hub.post("/hub/report", body).await;
+        assert_eq!(code, StatusCode::BAD_REQUEST, "{empty}");
+        assert!(answer["error"].as_str().unwrap().starts_with(empty));
+    }
+    let mut bot = report("Cheap watches");
+    bot["website"] = json!("https://spam.example");
+    assert_eq!(
+        hub.post("/hub/report", bot).await,
+        (StatusCode::ACCEPTED, json!({ "id": 0 }))
+    );
+    assert!(hub.github.opened.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn a_report_github_refused_is_opened_by_the_upkeep() {
+    let hub = hub(config());
+    *hub.github.down.lock().unwrap() = true;
+    let (code, body) = hub
+        .post("/hub/report", report("Crash when opening a chest"))
+        .await;
+    assert_eq!((code, &body["issue"]), (StatusCode::ACCEPTED, &Value::Null));
+    hub.app.file_pending();
+    assert_eq!(hub.github.opened.lock().unwrap().len(), 0);
+    *hub.github.down.lock().unwrap() = false;
+    hub.app.file_pending();
+    assert_eq!(hub.github.opened.lock().unwrap().len(), 1);
+    hub.app.file_pending();
+    assert_eq!(hub.github.opened.lock().unwrap().len(), 1, "opened once");
+}
+
+#[tokio::test]
+async fn reports_are_closed_without_a_github_token() {
+    let app = App::with_clock(
+        Store::open(":memory:").unwrap(),
+        Config::default(),
+        Box::new(|| DAY),
+    );
+    let res = router(app)
+        .oneshot(
+            Request::post("/hub/report")
+                .header("content-type", "application/json")
+                .body(Body::from(report("Water is black").to_string()))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), StatusCode::SERVICE_UNAVAILABLE);
+}
+
+#[tokio::test]
+async fn suggestions_wait_in_the_queue_for_kira() {
+    let hub = hub(config());
+    let first = json!({ "text": "  Add a waypoint mod\r\nto the\u{7} browser ", "item": "mod-registry", "name": "alex", "extra": 1 });
+    let (code, body) = hub.post("/hub/suggest", first).await;
+    assert_eq!(code, StatusCode::ACCEPTED);
+    let first_id = body["id"].as_i64().unwrap();
+    hub.post(
+        "/hub/suggest",
+        json!({ "text": "Bigger render distance on the Steam Deck" }),
+    )
+    .await;
+    assert_eq!(
+        hub.post("/hub/suggest", json!({ "text": "too short" }))
+            .await
+            .0,
+        StatusCode::BAD_REQUEST
+    );
+    assert_eq!(
+        hub.post(
+            "/hub/suggest",
+            json!({ "text": "A long enough idea", "item": "Bad Id" })
+        )
+        .await
+        .0,
+        StatusCode::BAD_REQUEST
+    );
+
+    assert_eq!(
+        hub.get("/hub/suggestions", None).await.0,
+        StatusCode::UNAUTHORIZED
+    );
+    assert_eq!(
+        hub.get("/hub/suggestions", Some("wrong-secret")).await.0,
+        StatusCode::UNAUTHORIZED
+    );
+    let (code, all) = hub.get("/hub/suggestions", Some("kira-secret")).await;
+    assert_eq!(code, StatusCode::OK);
+    let list = all["suggestions"].as_array().unwrap();
+    assert_eq!(list.len(), 2);
+    assert_eq!(
+        list[0]["text"], "Add a waypoint mod\nto the browser",
+        "trimmed, no control characters"
+    );
+    assert!(list[0].get("extra").is_none());
+    assert_eq!(list[0]["item"], "mod-registry");
+    assert_eq!(list[0]["name"], "alex");
+    assert!(list[0]["created_at"].as_str().unwrap().ends_with('Z'));
+    assert!(list[1].get("name").is_none());
+    let (_, after) = hub
+        .get(
+            &format!("/hub/suggestions?after={first_id}"),
+            Some("kira-secret"),
+        )
+        .await;
+    assert_eq!(after["suggestions"].as_array().unwrap().len(), 1);
+
+    let closed = hub_without_token();
+    assert_eq!(
+        closed.get("/hub/suggestions", Some("anything")).await.0,
+        StatusCode::NOT_FOUND
+    );
+}
+
+fn hub_without_token() -> Hub {
+    hub(Config::default())
+}
+
+#[tokio::test]
+async fn posts_are_rate_limited_per_address_and_capped_per_day() {
+    let hub = hub(Config {
+        hub_posts_per_hour: 20.0,
+        hub_suggestions_per_day: 3,
+        ..config()
+    });
+    // A burst of a tenth of the hourly rate: two, then refused.
+    let idea = |n: u32| json!({ "text": format!("Idea number {n}, long enough") });
+    assert_eq!(
+        hub.post("/hub/suggest", idea(1)).await.0,
+        StatusCode::ACCEPTED
+    );
+    assert_eq!(
+        hub.post("/hub/suggest", idea(2)).await.0,
+        StatusCode::ACCEPTED
+    );
+    assert_eq!(
+        hub.post("/hub/suggest", idea(3)).await.0,
+        StatusCode::TOO_MANY_REQUESTS
+    );
+
+    let busy = self::hub(Config {
+        hub_posts_per_hour: 1000.0,
+        hub_suggestions_per_day: 3,
+        ..config()
+    });
+    for n in 0..3 {
+        assert_eq!(
+            busy.post("/hub/suggest", idea(n)).await.0,
+            StatusCode::ACCEPTED
+        );
+    }
+    assert_eq!(
+        busy.post("/hub/suggest", idea(9)).await.0,
+        StatusCode::SERVICE_UNAVAILABLE
+    );
+    busy.day.store(DAY + 1, Ordering::SeqCst);
+    assert_eq!(
+        busy.post("/hub/suggest", idea(9)).await.0,
+        StatusCode::ACCEPTED,
+        "a new day"
+    );
+}
+
+#[tokio::test]
+async fn old_entries_go_and_reports_never_opened_are_given_up() {
+    let hub = hub(config());
+    *hub.github.down.lock().unwrap() = true;
+    let (_, body) = hub
+        .post("/hub/report", report("Crash when opening a chest"))
+        .await;
+    assert!(body["id"].as_i64().unwrap() > 0);
+    hub.post("/hub/suggest", json!({ "text": "An idea from long ago" }))
+        .await;
+    hub.day.store(DAY + 8, Ordering::SeqCst);
+    hub.app.maintain().unwrap();
+    *hub.github.down.lock().unwrap() = false;
+    hub.app.file_pending();
+    assert!(
+        hub.github.opened.lock().unwrap().is_empty(),
+        "past a week a report is given up"
+    );
+    hub.day.store(DAY + 91, Ordering::SeqCst);
+    hub.app.maintain().unwrap();
+    let (_, left) = hub.get("/hub/suggestions", Some("kira-secret")).await;
+    assert!(left["suggestions"].as_array().unwrap().is_empty());
+}
+
 #[tokio::test]
 async fn the_website_may_post_from_the_browser() {
     let hub = hub(config());
     let res = router(hub.app.clone())
         .oneshot(
-            Request::options("/hub/vote")
+            Request::options("/hub/report")
                 .header("origin", "https://playhorizon.dev")
                 .header("access-control-request-method", "POST")
                 .body(Body::empty())

From 4a9ca2988732944ea794e23852132e02c2aec567 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:07:49 +0100
Subject: [PATCH 116/270] Website: the API portal at /docs/api, with Markdown
 tables

The repository's docs/api/ (the portal, its surface pages and the generated mod and
server references) is built into the docs section: /docs/api is its README and
/docs/api/<page> each page, in two nav groups, "Build on Horizon" and "API reference".
The pages are read from the checkout or from main on GitHub, like the README, so the
site never holds a copy. Links between portal pages become the site's (and the build's
link check covers them); other relative links go to the file on GitHub.

The renderer gains tables: the "Ways in" table, the references and the other tables
on the site (apis, performance) showed as raw pipes. A link whose label is a code span
no longer throws.

Caddy and the dev server route /docs/api/<page> and redirect /docs/api/ to /docs/api;
Railway rebuilds when docs/api/ changes. /docs/mods links the Mod API, its reference
and its ways in; the summary page is now "APIs at a glance".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api/README.md            |  3 ++-
 website/Caddyfile             |  4 ++++
 website/README.md             |  9 ++++++--
 website/build.mjs             | 34 +++++++++++++++++++++++-------
 website/docs/apis.md          |  4 ++--
 website/docs/mods.md          |  2 +-
 website/docs/nav.json         |  3 ++-
 website/railway.json          |  2 +-
 website/serve.mjs             |  6 +++++-
 website/src/docs.html         |  2 +-
 website/src/markdown.js       | 39 ++++++++++++++++++++++++++++++++---
 website/src/markdown.test.mjs | 25 ++++++++++++++++++++++
 website/src/style.css         |  4 ++++
 13 files changed, 117 insertions(+), 20 deletions(-)
 create mode 100644 website/src/markdown.test.mjs

diff --git a/docs/api/README.md b/docs/api/README.md
index ad49ff609..ef3649105 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -51,5 +51,6 @@ Every page has the same parts: **Overview** (what you can build), **Guide** (whe
 **Examples**, **Stability** (the level of each part, per [stability.md](stability.md)), **Changelog** and
 **Not there yet** (what is planned, so nobody builds on a guess).
 
-The website's summary for players and authors is [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis)
+The website shows these pages at [playhorizon.dev/docs/api](https://playhorizon.dev/docs/api), built from this
+folder, and a summary for players and authors at [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis)
 (`website/docs/apis.md`).
diff --git a/website/Caddyfile b/website/Caddyfile
index fb96e836d..4ef85d2fc 100644
--- a/website/Caddyfile
+++ b/website/Caddyfile
@@ -35,6 +35,10 @@
 	rewrite /benchmarks /benchmarks.html
 	@doc path_regexp doc ^/docs/([a-z-]+)$
 	rewrite @doc /docs/{re.doc.1}.html
+	# The API portal: /docs/api is its index, /docs/api/<page> its pages.
+	redir /docs/api/ /docs/api permanent
+	@apidoc path_regexp apidoc ^/docs/api/([a-z-]+)$
+	rewrite @apidoc /docs/api/{re.apidoc.1}.html
 	# The registry's submission service (crates/horizon-mod-registry), over Railway's private network. Unset, the
 	# form says it isn't open.
 	handle /api/mods/* {
diff --git a/website/README.md b/website/README.md
index 8ced5a0aa..7339cf966 100644
--- a/website/README.md
+++ b/website/README.md
@@ -77,8 +77,13 @@ mark merged-but-unreleased things "next release". `{{HARNESSES}}` and `{{PERCENT
 the README. A line holding only `![caption](/media/...)` becomes a figure (the file must be in
 `public/media/`); links to other pages are `/docs/<slug>#heading`. The build checks every link
 between pages and every image, and fails with the list when one is broken. `/server`
-redirects to `/docs/hosting`. The developer docs in the repository's `docs/` stay as they are and are linked from
-the Contributing page.
+redirects to `/docs/hosting`.
+
+The API portal is the repository's `docs/api/`, not a copy: `nav.json` lists its README as `api` (`/docs/api`) and
+its pages as `api/<page>` (`/docs/api/<page>`), read from the checkout or from `main` on GitHub like the README.
+Links between its pages become the site's, every other relative link goes to the file on GitHub, and the same link
+check applies. Markdown tables render as tables. The other developer docs in `docs/` stay on GitHub and are linked
+from the Contributing page.
 
 ## Run it locally
 
diff --git a/website/build.mjs b/website/build.mjs
index 12bba71cb..4045297fb 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -3,12 +3,13 @@
 // docs/nav.json), plus public/ and fingerprinted CSS and JS. No dependencies.
 //
 // Railway builds only website/, so the README and links.json come from the repo when they
-// are next to it (a local checkout) and from main on GitHub otherwise. The documentation lives in website/. The latest releases and
+// are next to it (a local checkout) and from main on GitHub otherwise. The documentation lives in website/, except the
+// API portal (docs/api/), read the same way as the README. The latest releases and
 // the contributors are baked in when GitHub answers, so the page reads well before (or without) JavaScript.
 import { readFile, writeFile, mkdir, rm, cp } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { join, dirname } from "node:path";
+import { join, dirname, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { markdown, inline, section, escape } from "./src/markdown.js";
 import { recentHtml, releasesPageHtml } from "./src/releases.js";
@@ -303,16 +304,35 @@ const values = {
 
 // --- The documentation ---------------------------------------------------------------------
 // website/docs/<slug>.md: "# Title", a one-paragraph lede, then the body. docs/nav.json orders them in groups.
+// The API portal is the repository's docs/api/ (the pages and their generated references): nav.json lists it as
+// `api` (its README, /docs/api) and `api/<page>` (/docs/api/<page>). Its links are written for GitHub, so links
+// between its pages become the site's and every other relative link goes to the file on GitHub.
 
 const docsNav = JSON.parse(await readFile(join(site, "docs", "nav.json"), "utf8"));
+const docSlugs = new Set(docsNav.flatMap((g) => g.pages));
+const apiSource = (slug) => `docs/api/${slug === "api" ? "README" : slug.slice(4)}.md`;
+function apiLinks(text, from) {
+  return text.replace(/\]\(([^)\s]+)\)/g, (all, url) => {
+    if (url.startsWith("https://playhorizon.dev/")) return `](${url.slice(23)})`;
+    if (/^([a-z]+:|#|\/)/i.test(url)) return all;
+    const [file, id] = url.split("#");
+    const path = posix.normalize(posix.join(posix.dirname(from), file));
+    const page = path.match(/^docs\/api\/([\w-]+)\.md$/)?.[1];
+    const slug = page === "README" ? "api" : page && `api/${page}`;
+    const to = docSlugs.has(slug) ? `/docs/${slug}` : `https://github.com/${REPO}/blob/main/${path}`;
+    return `](${to}${id ? `#${id}` : ""})`;
+  });
+}
 const docs = [];
 for (const { group, pages: slugs } of docsNav) {
   for (const slug of slugs) {
-    const file = `${slug}.md`;
-    const text = (await readFile(join(site, "docs", file), "utf8")).replace(/\r\n?/g, "\n");
+    const api = slug === "api" || slug.startsWith("api/");
+    const file = api ? apiSource(slug) : `website/docs/${slug}.md`;
+    let text = (api ? (await repoFile(file))[0] : await readFile(join(site, "docs", `${slug}.md`), "utf8")).replace(/\r\n?/g, "\n");
+    if (api) text = apiLinks(text.replace(/^<!--[\s\S]*?-->\n/, ""), file);
     const m = text.match(/^# (.+)\n\n((?:[^\n]+\n)+)\n/);
-    if (!m) throw new Error(`docs/${file}: needs "# Title", a blank line, a lede paragraph and a blank line`);
-    docs.push({ slug, file, group, title: m[1].trim(), lede: m[2].trim().replace(/\n/g, " "), body: text.slice(m[0].length), path: slug === "index" ? "/docs/" : `/docs/${slug}` });
+    if (!m) throw new Error(`${file}: needs "# Title", a blank line, a lede paragraph and a blank line`);
+    docs.push({ slug, file, group, title: m[1].replace(/`/g, "").trim(), lede: m[2].trim().replace(/\n/g, " "), body: text.slice(m[0].length), path: slug === "index" ? "/docs/" : `/docs/${slug}` });
   }
 }
 const plain = (md) => md.replace(/`/g, "").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/\*\*/g, "");
@@ -352,7 +372,7 @@ const docNav = (current) =>
     .join("\n");
 const pagerLink = (d, rel) => (d ? `<a class="docs-pager-${rel}" href="${d.path}"><span>${rel === "next" ? "Next" : "Previous"}</span>${escape(d.title)}</a>` : "");
 
-await mkdir(join(dist, "docs"), { recursive: true });
+await mkdir(join(dist, "docs", "api"), { recursive: true });
 const docPageFiles = [];
 const docPages = renderedDocs.map((d, i) => {
   const toc = d.headings.filter((h) => h.level === 2);
diff --git a/website/docs/apis.md b/website/docs/apis.md
index f948b1d54..fbed5fe53 100644
--- a/website/docs/apis.md
+++ b/website/docs/apis.md
@@ -1,4 +1,4 @@
-# Horizon's APIs
+# APIs at a glance
 
 Horizon is built to be built on. Mods, shaders, agents, server panels, launchers' scripts and tools all get a documented API with a version, a stability level and a reference generated from the code, so it never says something the game doesn't do.
 
@@ -13,7 +13,7 @@ Horizon is built to be built on. Mods, shaders, agents, server panels, launchers
 | **Launcher** | your agent, pack makers | `horizon-launcher`'s 46 commands and its MCP server | preview |
 | **Data formats** | tools that read Horizon's files | benchmark reports, telemetry, settings, release checksums; worlds are vanilla's format | per format |
 
-The full pages, one per surface, are in the repository: [docs/api](https://github.com/ludovic111/horizon/tree/main/docs/api). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting).
+The full pages, one per surface, with their references: [the API portal](/docs/api), starting with [the Mod API](/docs/api/mods). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting).
 
 ## What the levels mean
 
diff --git a/website/docs/mods.md b/website/docs/mods.md
index 0c125cf73..77a1734fd 100644
--- a/website/docs/mods.md
+++ b/website/docs/mods.md
@@ -30,7 +30,7 @@ cd my-mod
 cargo horizon-mod run
 ```
 
-`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The full guide, with the API, the manifest and the roadmap, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)).
+`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The [Mod API](/docs/api/mods) lists what a mod can do today, its [reference](/docs/api/mods-reference), the [ways in](/docs/api/mods#ways-in) (Rust today, Lua scripts planned) and what comes next; the full guide, with the manifest and the runtime, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)).
 
 ## Finding resource packs and modpacks
 
diff --git a/website/docs/nav.json b/website/docs/nav.json
index 3bc2ec8d2..18eab69fd 100644
--- a/website/docs/nav.json
+++ b/website/docs/nav.json
@@ -3,6 +3,7 @@
   { "group": "Playing", "pages": ["settings", "multiplayer", "troubleshooting"] },
   { "group": "Hosting", "pages": ["hosting"] },
   { "group": "Going further", "pages": ["modpacks", "mods", "performance", "agents"] },
-  { "group": "Build on Horizon", "pages": ["apis"] },
+  { "group": "Build on Horizon", "pages": ["apis", "api", "api/stability"] },
+  { "group": "API reference", "pages": ["api/mods", "api/mods-reference", "api/mod-index", "api/server", "api/server-reference", "api/agent-control", "api/launcher", "api/data-formats", "api/shaders"] },
   { "group": "Project", "pages": ["contributing", "faq"] }
 ]
diff --git a/website/railway.json b/website/railway.json
index 0f84cf952..3bbe9dfb3 100644
--- a/website/railway.json
+++ b/website/railway.json
@@ -3,7 +3,7 @@
   "build": {
     "builder": "DOCKERFILE",
     "dockerfilePath": "Dockerfile",
-    "watchPatterns": ["/website/**", "/README.md", "/launcher/links.json"]
+    "watchPatterns": ["/website/**", "/README.md", "/launcher/links.json", "/docs/api/**"]
   },
   "deploy": {
     "healthcheckPath": "/",
diff --git a/website/serve.mjs b/website/serve.mjs
index 761eef48a..6159474a0 100644
--- a/website/serve.mjs
+++ b/website/serve.mjs
@@ -11,6 +11,10 @@ const port = Number(process.env.PORT) || 4173;
 
 createServer(async (req, res) => {
   let path = normalize(decodeURIComponent(new URL(req.url, "http://x").pathname)).replace(/^(\.\.[/\\])+/, "");
+  if (path === "/docs/api/") {
+    res.writeHead(301, { Location: "/docs/api" });
+    return res.end();
+  }
   if (path.endsWith("/")) path += "index.html";
   // The server guide is part of the docs now, as the Caddyfile redirects it.
   if (path === "/server" || path === "/server.html") {
@@ -18,7 +22,7 @@ createServer(async (req, res) => {
     return res.end();
   }
   if (path === "/docs") path = "/docs/index.html";
-  // /privacy and /docs/<page> are .html files, as the Caddyfile rewrites them.
+  // /privacy, /docs/<page> and /docs/api/<page> are .html files, as the Caddyfile rewrites them.
   if (!extname(path)) path += ".html";
   let file = join(root, path);
   let status = 200;
diff --git a/website/src/docs.html b/website/src/docs.html
index 1277803b5..56ba89c09 100644
--- a/website/src/docs.html
+++ b/website/src/docs.html
@@ -46,7 +46,7 @@
         <nav class="docs-pager" aria-label="Next and previous pages">
 {{DOC_PAGER}}
         </nav>
-        <p class="docs-edit"><a href="https://github.com/ludovic111/horizon/blob/main/website/docs/{{DOC_FILE}}">Edit this page on GitHub</a> · Spotted something wrong? <a href="https://github.com/ludovic111/horizon/issues">Open an issue</a> or ask on <a href="{{DISCORD}}">Discord</a>.</p>
+        <p class="docs-edit"><a href="https://github.com/ludovic111/horizon/blob/main/{{DOC_FILE}}">Edit this page on GitHub</a> · Spotted something wrong? <a href="https://github.com/ludovic111/horizon/issues">Open an issue</a> or ask on <a href="{{DISCORD}}">Discord</a>.</p>
         <p class="disclaimer">Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.</p>
       </main>
     </div>
diff --git a/website/src/markdown.js b/website/src/markdown.js
index 252e554ec..1735f7304 100644
--- a/website/src/markdown.js
+++ b/website/src/markdown.js
@@ -1,5 +1,5 @@
-// A small Markdown renderer for release notes and the README: headings, paragraphs,
-// lists (nested by indentation), fenced code, quotes, rules, and inline code, bold,
+// A small Markdown renderer for release notes, the README and the docs: headings, paragraphs,
+// lists (nested by indentation), fenced code, quotes, rules, tables, and inline code, bold,
 // italic and links. Everything is escaped first, so its output never carries raw HTML.
 // Shared by build.mjs (Node) and main.js (browser).
 
@@ -38,12 +38,41 @@ export function inline(text, site = false) {
   out = out.replace(/\u0001(\d+)\u0001/g, (_, i) => {
     const [label, url] = links[i];
     const target = href(url, site);
-    const body = inline(label, site);
+    // The label's code spans are already placeholders: put them back for its own pass.
+    const body = inline(label.replace(/\u0000(\d+)\u0000/g, (_, c) => `\`${codes[c]}\``), site);
     return target ? `<a href="${escape(target)}">${body}</a>` : body;
   });
   return out.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${escape(codes[i])}</code>`);
 }
 
+// A table: a row of cells, a rule row (`| --- | :-: |`), then body rows, until a line that isn't a row.
+const ROW = /^\s*\|.*\|\s*$/;
+const RULE = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/;
+
+/** A row's cells: split on `|` outside code spans; `\|` is a literal bar. */
+function cells(row) {
+  const s = row.trim().slice(1, -1);
+  const out = [""];
+  let code = false;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\" && s[i + 1] === "|") out[out.length - 1] += s[++i];
+    else if (s[i] === "|" && !code) out.push("");
+    else {
+      if (s[i] === "`") code = !code;
+      out[out.length - 1] += s[i];
+    }
+  }
+  return out.map((c) => c.trim());
+}
+
+function table(lines, start, site) {
+  const row = (line, tag) => `<tr>${cells(line).map((c) => `<${tag}>${inline(c, site)}</${tag}>`).join("")}</tr>`;
+  let i = start + 2;
+  const body = [];
+  while (i < lines.length && ROW.test(lines[i])) body.push(row(lines[i++], "td"));
+  return [`<div class="table-wrap"><table class="md-table"><thead>${row(lines[start], "th")}</thead><tbody>${body.join("")}</tbody></table></div>`, i];
+}
+
 const indentOf = (line) => line.match(/^ */)[0].length;
 const ITEM = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
 
@@ -131,6 +160,10 @@ export function markdown(source, { shift = 0, site = false, headings = null } =
     } else if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
       out.push("<hr>");
       i++;
+    } else if (ROW.test(line) && RULE.test(lines[i + 1] || "")) {
+      const [html, end] = table(lines, i, site);
+      out.push(html);
+      i = end;
     } else if (ITEM.test(line)) {
       const [html, end] = list(lines, i, site);
       out.push(html);
diff --git a/website/src/markdown.test.mjs b/website/src/markdown.test.mjs
new file mode 100644
index 000000000..171348e45
--- /dev/null
+++ b/website/src/markdown.test.mjs
@@ -0,0 +1,25 @@
+// node --test src/: the Markdown the docs pages and release notes are rendered from.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { markdown } from "./markdown.js";
+
+test("a table renders with its header, cells and inline Markdown", () => {
+  const html = markdown("| Way in | Status |\n| --- | :-: |\n| Rust | `cargo horizon-mod` |\n| Lua | planned \\| soon |\n\nAfter.");
+  assert.equal(
+    html,
+    '<div class="table-wrap"><table class="md-table"><thead><tr><th>Way in</th><th>Status</th></tr></thead>' +
+      "<tbody><tr><td>Rust</td><td><code>cargo horizon-mod</code></td></tr><tr><td>Lua</td><td>planned | soon</td></tr></tbody></table></div>\n<p>After.</p>",
+  );
+});
+
+test("a bar inside a code span stays in its cell", () => {
+  assert.match(markdown("| a | b |\n|---|---|\n| `x | y` | z |"), /<td><code>x \| y<\/code><\/td><td>z<\/td>/);
+});
+
+test("rows without a rule line are a paragraph", () => {
+  assert.equal(markdown("| a | b |\n| c | d |"), "<p>| a | b | | c | d |</p>");
+});
+
+test("a link whose label is code keeps it", () => {
+  assert.equal(markdown("See [`AGENTS.md`](/docs/agents).", { site: true }), '<p>See <a href="/docs/agents"><code>AGENTS.md</code></a>.</p>');
+});
diff --git a/website/src/style.css b/website/src/style.css
index 4ce91791d..0279c38aa 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -687,6 +687,10 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 .bench-table td.num { font-variant-numeric: tabular-nums; white-space: nowrap; }
 .bench-table td.wins { color: var(--ink); font-weight: 600; }
 .bench-table td.vs { font-size: var(--text-caption); white-space: nowrap; }
+.md-table { width: 100%; border-collapse: collapse; font-size: var(--text-ui); }
+.md-table th, .md-table td { padding: 8px 12px 8px 0; text-align: left; border-bottom: 1px solid var(--rule); vertical-align: baseline; }
+.md-table th { font-weight: 500; color: var(--ink); }
+.md-table td code, .md-table th code { overflow-wrap: anywhere; }
 .vs-horizon { color: var(--success); }
 .vs-java { color: var(--danger); }
 .vs-tie, .vs-none { color: var(--muted); }

From c1ffa17c87bcef7d2d564644123c3142c169b0d3 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:14:12 +0100
Subject: [PATCH 117/270] Hub: vote for roadmap items, report a bug and suggest
 something from the page

Each item still to come gets a "Want it" button with its count; the Contribute
tab gets a bug report form (the #horizon-bugs template, which the telemetry
server opens as a GitHub issue and links back) and a suggestion form (to the
private queue Kira relays), and a Contributors list that shows the Discord name
of those who agreed on Kira (/contributors.json). The forms and buttons appear
once the hub's server answers; until then the page points to GitHub and Discord.
roadmap/README.md documents the intake API that Kira shares.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 roadmap/README.md           |  29 ++++++++-
 tools/roadmap.py            |   3 +-
 website/build.mjs           |  19 +++++-
 website/src/contributors.js |   2 +-
 website/src/hub-page.js     | 120 ++++++++++++++++++++++++++++++++++++
 website/src/hub.html        |  43 ++++++++++++-
 website/src/hub.js          |  41 +++++++++++-
 website/src/hub.test.mjs    |  22 ++++++-
 website/src/style.css       |  25 +++++++-
 9 files changed, 293 insertions(+), 11 deletions(-)

diff --git a/roadmap/README.md b/roadmap/README.md
index 55cf9d09f..22cde1a7d 100644
--- a/roadmap/README.md
+++ b/roadmap/README.md
@@ -54,8 +54,8 @@ Whoever moves the work (the orchestrator on each heartbeat, or anyone in their p
    `2026-43.md`): `# Title`, a paragraph or two for players, then `## Technical` and the same week for
    contributors, with its pull requests. `build` puts it into website/data/roadmap.json; the hub's Journal tab
    shows it among the releases, and `/data/journal.json` carries it to Kira's #updates and to X.
-6. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an
-   item in a normal pull request; none is published automatically.
+6. Suggestions from the website and Discord reach the maintainers' private channel through Kira (below). A good
+   one becomes an item in a normal pull request; none is published automatically.
 
 CI runs `tests/test_roadmap.py` (in the Python tests), which fails when ROADMAP.md is not what `build` writes
 or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs the same rules without GitHub.
@@ -89,3 +89,28 @@ merged pull request, release, shipped item and weekly summary, newest first, the
 - `announce: true` (the item's `announce` key) asks Kira to post the shipped item on X too, with `post`.
 - `https://playhorizon.dev/data/roadmap.json` is `roadmap.toml` as JSON (`areas`, `items` with every key above,
   `overview`, the weekly summaries); an item's page is `https://playhorizon.dev/hub#<id>`.
+
+## The intake: votes, bug reports, suggestions
+
+The hub's forms and vote buttons talk to the telemetry server (`https://telemetry.playhorizon.dev`,
+`crates/horizon-telemetry-server`, `src/hub.rs` and `src/intake.rs`; its README lists the limits and settings).
+Kira uses the same endpoints, so a bug or an idea goes the same way from the site and from Discord.
+
+| Endpoint | Body | Answer |
+| --- | --- | --- |
+| `POST /hub/vote` | `{"item": "<roadmap id>", "voter": "<random id, 16 to 64 characters>", "up": true}` | `{"item", "votes"}`; `"up": false` takes the vote back |
+| `GET /hub/votes` | | `{"votes": {"<item>": n}}`, a minute old at most |
+| `POST /hub/report` | `{"title", "did", "happened", "expected", "version"?, "system", "name"?}` | 201 `{"id", "issue": "<GitHub URL>"}`; 202 `{"id", "issue": null}` when GitHub was down (opened later) |
+| `POST /hub/suggest` | `{"text", "item"?, "name"?}` | 202 `{"id"}` |
+| `GET /hub/suggestions?after=<id>` | `Authorization: Bearer <HORIZON_TELEMETRY_HUB_TOKEN>` | `{"suggestions": [{"id", "text", "item"?, "name"?, "created_at"}]}`, oldest first |
+
+- A report becomes an issue at once, labels `bug` and `from-website`, in the `#horizon-bugs` template (What I did,
+  What happened, What I expected, Horizon version, OS, CPU, GPU) with "Reported on playhorizon.dev". Every field
+  but the version and the name is required; mentions, `#123` references and HTML in people's text are made inert.
+- Suggestions are never published. Kira polls `/hub/suggestions` with the last id it relayed and posts each one
+  to `#roadmap-suggestions`.
+- Errors are `{"error": "…"}`: 400 names the field (`"did: 3 to 2000 characters"`), 429 means too many from that
+  address, 503 a full day or reports turned off (no GitHub token on the server).
+- The page shows the forms and the buttons only once `GET /hub/votes` answers. Until then it points to GitHub and
+  Discord. It keeps a random voter id and the items it voted for in `localStorage` (`hub:voter`, `hub:voted`).
+
diff --git a/tools/roadmap.py b/tools/roadmap.py
index fe97285ff..4bc439e4d 100644
--- a/tools/roadmap.py
+++ b/tools/roadmap.py
@@ -56,7 +56,8 @@ ITEM_KEYS = {"id", "title", "status", "area", "plain", "dev", "links", "focus",
 ISSUE = re.compile(r"#(\d+)$")
 ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$")
 # An item is the anchor playhorizon.dev/hub#<id>: it can't take the name of a tab, a section or a heading.
-RESERVED = {"main", "overview", "roadmap", "board", "journal", "contribute", "hub-data", *STATUSES}
+RESERVED = {"main", "overview", "roadmap", "board", "journal", "contribute", "report", "suggest", "contributors",
+            "hub-data", *STATUSES}
 RESERVED_PREFIXES = ("h-", "tab-", "col-", "week-", "journal-")
 RELEASE = re.compile(r"(v\d[\w.]*|launcher@\d[\w.]*|launcher-v\d[\w.]*|website)$")
 MONTHS = ("January|February|March|April|June|July|August|September|October|November|December")
diff --git a/website/build.mjs b/website/build.mjs
index c3203891e..b766b3d79 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -16,7 +16,7 @@ import { machinesHtml, playersHtml } from "./src/bench.js";
 import { CPUS, GPUS, singleThread } from "./src/hardware.js";
 import { isGame, isLauncher, launcherVersion, newestFirst } from "./src/versions.js";
 import { contributorsFrom, contributorsHtml } from "./src/contributors.js";
-import { areaFilterHtml, boardFilterHtml, boardFrom, boardHtml, helpWantedHtml, journalFrom, journalHtml, journalJson, overviewHtml, roadmapHtml, slimIssue } from "./src/hub.js";
+import { areaFilterHtml, boardFilterHtml, boardFrom, boardHtml, creditFrom, creditHtml, helpWantedHtml, journalFrom, journalHtml, journalJson, overviewHtml, roadmapHtml, slimIssue, suggestItemsHtml } from "./src/hub.js";
 
 const site = dirname(fileURLToPath(import.meta.url));
 const dist = join(site, "dist");
@@ -119,6 +119,18 @@ const hubLinked = new Map(hubLive.filter((i) => linked.has(i.n)).map((i) => [i.n
 const board = boardFrom(hubLive, roadmap);
 const journal = journalFrom(releases, hubLive, roadmap);
 
+// The hub's server (crates/horizon-telemetry-server: votes, bug reports, suggestions), and Kira's list of the
+// contributors who linked their Discord account and agreed to be credited (kira's /contributors.json).
+const hubApi = process.env.HUB_API_URL || "https://telemetry.playhorizon.dev";
+let kiraCredit = {};
+try {
+  const res = await fetch(process.env.KIRA_CONTRIBUTORS_URL || "https://kira-production-500e.up.railway.app/contributors.json", { signal: AbortSignal.timeout(10000) });
+  if (!res.ok) throw new Error(`${res.status} from Kira`);
+  kiraCredit = await res.json();
+} catch (e) {
+  console.warn(`hub: contributors' Discord names: ${e.message}`);
+}
+
 // --- The parity table ------------------------------------------------------------------
 
 const status = section(readme, "Project status") ?? "";
@@ -332,7 +344,10 @@ const values = {
   HUB_BOARD: hubLive.length ? boardHtml(board, roadmap) : `<p class="lede">The board could not be loaded here.</p>`,
   HUB_BOARD_FILTER: boardFilterHtml(board, roadmap),
   HUB_JOURNAL: journalHtml(journal, roadmap) || unavailable,
-  HUB_DATA: JSON.stringify({ roadmap, live: [...hubLinked.values()] }).replace(/</g, "\\u003c"),
+  HUB_DATA: JSON.stringify({ roadmap, live: [...hubLinked.values()], api: hubApi }).replace(/</g, "\\u003c"),
+  HUB_SUGGEST_ITEMS: suggestItemsHtml(roadmap),
+  HUB_VERSION: escape(game[0]?.tag_name || ""),
+  HUB_CREDIT: creditHtml(creditFrom(contributors, kiraCredit)),
   YEAR: String(new Date().getUTCFullYear()),
 };
 
diff --git a/website/src/contributors.js b/website/src/contributors.js
index 5d2030f5e..12bce9457 100644
--- a/website/src/contributors.js
+++ b/website/src/contributors.js
@@ -21,7 +21,7 @@ export function contributorsFrom(list) {
 }
 
 // GitHub serves avatars at any size: 96 px is twice what the page draws, for sharp screens.
-function avatar(url) {
+export function avatar(url) {
   if (!url.startsWith(AVATARS)) return "";
   const u = new URL(url);
   u.searchParams.set("s", "96");
diff --git a/website/src/hub-page.js b/website/src/hub-page.js
index 748ddbab4..9115c5ca4 100644
--- a/website/src/hub-page.js
+++ b/website/src/hub-page.js
@@ -132,6 +132,7 @@ async function refresh() {
   document.querySelector("[data-overview]").innerHTML = overviewHtml(data.roadmap, live);
   document.querySelector("[data-roadmap]").innerHTML = roadmapHtml(data.roadmap, live);
   filter(area);
+  showVotes();
   const board = boardFrom(fresh, data.roadmap);
   const chosen = boardSelect.value;
   boardSelect.innerHTML = boardFilterHtml(board, data.roadmap);
@@ -144,7 +145,126 @@ async function refresh() {
   if (note) note.textContent = "Pull request and issue states are live from GitHub.";
 }
 
+// --- Votes, bug reports and suggestions: the hub's server (crates/horizon-telemetry-server) --------------------
+
+const saved = (key, fallback) => {
+  try {
+    return JSON.parse(localStorage.getItem(key)) ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+const save = (key, value) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {}
+};
+const post = (path, body) => fetch(`${data.api}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+
+// This browser's random id (one vote per item per browser) and the items it voted for. Nothing else identifies it.
+function voter() {
+  let id = saved("hub:voter", "");
+  if (typeof id !== "string" || id.length < 16) {
+    id = crypto.randomUUID ? crypto.randomUUID() : [...crypto.getRandomValues(new Uint8Array(16))].map((b) => b.toString(16).padStart(2, "0")).join("");
+    save("hub:voter", id);
+  }
+  return id;
+}
+const mine = new Set(saved("hub:voted", []));
+let counts = null; // { item: votes } once the server answered; until then the buttons stay hidden
+
+function showVotes() {
+  if (!counts) return;
+  for (const button of document.querySelectorAll("[data-vote]")) {
+    const id = button.dataset.vote;
+    button.hidden = false;
+    button.setAttribute("aria-pressed", String(mine.has(id)));
+    button.querySelector(".hub-vote-label").textContent = mine.has(id) ? "Wanted" : "Want it";
+    button.querySelector("[data-votes]").textContent = counts[id] ? String(counts[id]) : "";
+  }
+}
+
+async function vote(id) {
+  const up = !mine.has(id);
+  const apply = (on, step) => {
+    if (on) mine.add(id);
+    else mine.delete(id);
+    counts[id] = Math.max(0, (counts[id] || 0) + step);
+    save("hub:voted", [...mine]);
+    showVotes();
+  };
+  apply(up, up ? 1 : -1);
+  try {
+    const res = await post("/hub/vote", { item: id, voter: voter(), up });
+    if (!res.ok) throw new Error(res.status);
+    counts[id] = (await res.json()).votes;
+    showVotes();
+  } catch {
+    apply(!up, up ? -1 : 1);
+  }
+}
+document.addEventListener("click", (e) => {
+  const button = e.target.closest("[data-vote]");
+  if (button && counts) vote(button.dataset.vote);
+});
+
+const LABELS = { title: "the title", did: "what you did", happened: "what happened", expected: "what you expected", version: "the version", system: "OS, CPU, GPU", text: "your idea", name: "your name" };
+// The server's answer in words: "did: 3 to 2000 characters" becomes "Check what you did: 3 to 2000 characters."
+function trouble(code, answer) {
+  if (code === 429) return "Too many sent from your connection: try again in a few minutes.";
+  const said = typeof answer.error === "string" ? answer.error : "";
+  const field = said.match(/^(\w+): (.+)$/);
+  if (code === 400 && field) return `Check ${LABELS[field[1]] || field[1]}: ${field[2]}.`;
+  return said ? `${said[0].toUpperCase()}${said.slice(1)}.` : "That didn't go through: try again in a moment.";
+}
+
+function setUpForm(form, path, thanks) {
+  const status = form.querySelector("[data-status]");
+  form.hidden = false;
+  form.parentElement.querySelector("[data-closed]").hidden = true;
+  form.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    if (!form.reportValidity()) return;
+    const button = form.querySelector('[type="submit"]');
+    button.disabled = true;
+    status.textContent = "Sending…";
+    try {
+      const res = await post(path, Object.fromEntries(new FormData(form)));
+      const answer = await res.json().catch(() => ({}));
+      if (res.ok) {
+        thanks(status, answer);
+        // A new report starts with the version filled in again; the name stays for the next one.
+        for (const field of form.querySelectorAll("textarea, input:not([name='version']):not([name='name'])")) field.value = "";
+      } else status.textContent = trouble(res.status, answer);
+    } catch {
+      status.textContent = "Couldn't reach the server: try again, or use GitHub or Discord.";
+    }
+    button.disabled = false;
+  });
+}
+
+// The forms and the votes show once the server answers; without it the page points to GitHub and Discord.
+async function connect() {
+  try {
+    // Revalidated: the server keeps the counts a minute, a browser's copy would miss this browser's own vote.
+    const res = await fetch(`${data.api}/hub/votes`, { cache: "no-cache" });
+    if (!res.ok) return;
+    counts = (await res.json()).votes || {};
+  } catch {
+    return;
+  }
+  showVotes();
+  setUpForm(document.querySelector('[data-form="report"]'), "/hub/report", (status, answer) => {
+    const issue = typeof answer.issue === "string" && answer.issue.match(/^https:\/\/github\.com\/ludovic111\/horizon\/issues\/(\d+)$/);
+    status.innerHTML = issue ? `Thanks! It's <a href="${issue[0]}">issue #${issue[1]}</a> on GitHub: follow it there.` : "Thanks! It will be on GitHub in a few minutes.";
+  });
+  setUpForm(document.querySelector('[data-form="suggest"]'), "/hub/suggest", (status) => {
+    status.textContent = "Thanks! The maintainers read every suggestion.";
+  });
+}
+
 setUpTheme();
 setUpMenu();
+connect();
 follow();
 refresh().then(() => data.roadmap.items.some((i) => `#${i.id}` === location.hash) && follow());
diff --git a/website/src/hub.html b/website/src/hub.html
index d4ba4600c..167ffc15e 100644
--- a/website/src/hub.html
+++ b/website/src/hub.html
@@ -90,7 +90,7 @@
               <article class="highlight">
                 <h3>Tell us what differs</h3>
                 <p>Something that doesn't play like vanilla is a bug. Say what you did, what happened and what vanilla does, with your Horizon version and system.</p>
-                <p class="hub-actions"><a class="button secondary small" href="{{DISCORD}}">Discord</a><a class="button secondary small" href="https://github.com/ludovic111/horizon/issues/new">GitHub issue</a></p>
+                <p class="hub-actions"><a class="button secondary small" href="#report">Report a bug</a><a class="button secondary small" href="#suggest">Suggest something</a></p>
               </article>
               <article class="highlight">
                 <h3>Take a task</h3>
@@ -109,6 +109,41 @@
               </article>
             </div>
           </section>
+          <section class="hub-block" id="report" aria-labelledby="h-report">
+            <h2 class="title" id="h-report">Report a bug</h2>
+            <p class="hub-intro">One bug per report: something that breaks, or doesn't play like vanilla. It becomes an issue on GitHub, public, and you get its link to follow it. Search the <a href="https://github.com/ludovic111/horizon/issues?q=is%3Aissue+label%3Abug">open bugs</a> first.</p>
+            <form class="hub-form" data-form="report" hidden>
+              <label class="hub-field"><span>Title: what is broken, in a few words</span><input name="title" required minlength="5" maxlength="120" autocomplete="off" placeholder="Water looks black on AMD graphics"></label>
+              <label class="hub-field"><span>What did you do? The steps, one per line</span><textarea name="did" required minlength="3" maxlength="2000" rows="4"></textarea></label>
+              <div class="hub-form-pair">
+                <label class="hub-field"><span>What happened?</span><textarea name="happened" required minlength="3" maxlength="2000" rows="3"></textarea></label>
+                <label class="hub-field"><span>What did you expect? What vanilla does</span><textarea name="expected" required minlength="3" maxlength="2000" rows="3"></textarea></label>
+              </div>
+              <div class="hub-form-pair">
+                <label class="hub-field"><span>Horizon version</span><input name="version" maxlength="60" value="{{HUB_VERSION}}" autocomplete="off"></label>
+                <label class="hub-field"><span>OS, CPU, GPU</span><input name="system" required minlength="3" maxlength="200" placeholder="Windows 11, Ryzen 5 5600, RX 6600"></label>
+              </div>
+              <label class="hub-field"><span>Your name, shown on the issue (optional)</span><input name="name" maxlength="64" autocomplete="nickname"></label>
+              <label class="hub-trap" aria-hidden="true">Leave this empty <input name="website" tabindex="-1" autocomplete="off"></label>
+              <p class="hub-form-foot"><button type="submit" class="button primary">Send the report</button><span class="meta" data-status role="status"></span></p>
+              <p class="meta">What you write is public on GitHub: no passwords or personal details. A screenshot or the log file helps: add it to the issue once it's open.</p>
+            </form>
+            <p class="hub-form-closed" data-closed>Report it on <a href="https://github.com/ludovic111/horizon/issues/new">GitHub</a> or in <a href="{{DISCORD}}">#horizon-bugs on Discord</a>, where Kira turns your post into an issue.</p>
+          </section>
+          <section class="hub-block" id="suggest" aria-labelledby="h-suggest">
+            <h2 class="title" id="h-suggest">Suggest something</h2>
+            <p class="hub-intro">An idea for Horizon, or about something on the roadmap. The maintainers read every one, and the good ones become roadmap items. Nothing you send here is published.</p>
+            <form class="hub-form" data-form="suggest" hidden>
+              <label class="hub-field"><span>Your idea</span><textarea name="text" required minlength="10" maxlength="1000" rows="4"></textarea></label>
+              <div class="hub-form-pair">
+                <label class="hub-field"><span>About</span><select name="item">{{HUB_SUGGEST_ITEMS}}</select></label>
+                <label class="hub-field"><span>Your name (optional)</span><input name="name" maxlength="64" autocomplete="nickname"></label>
+              </div>
+              <label class="hub-trap" aria-hidden="true">Leave this empty <input name="website" tabindex="-1" autocomplete="off"></label>
+              <p class="hub-form-foot"><button type="submit" class="button primary">Send the idea</button><span class="meta" data-status role="status"></span></p>
+            </form>
+            <p class="hub-form-closed" data-closed>Post it in <a href="{{DISCORD}}">#horizon-ideas on Discord</a>, or send it to Kira with <code>/suggest</code>.</p>
+          </section>
           <section class="hub-block" aria-labelledby="h-rules">
             <h2 class="title" id="h-rules">The rules</h2>
             <ol class="hub-rules">
@@ -119,6 +154,12 @@
             </ol>
             <p class="hub-actions"><a class="button primary" href="/docs/contributing">The contributing guide</a><a class="button secondary" href="https://github.com/ludovic111/horizon/blob/main/CONTRIBUTING.md">CONTRIBUTING.md</a></p>
           </section>
+          <section class="hub-block" id="contributors" aria-labelledby="h-contributors">
+            <h2 class="title" id="h-contributors">Contributors</h2>
+            <p class="hub-intro">Everyone with commits in Horizon. On Discord, <code>/link-github &lt;your login&gt; credit:True</code> adds your Discord name next to yours.</p>
+            <ul class="contributors-list hub-people">{{HUB_CREDIT}}</ul>
+            <p class="meta"><a href="https://github.com/ludovic111/horizon/graphs/contributors">All contributors on GitHub</a></p>
+          </section>
         </div>
         <p class="disclaimer">Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.</p>
       </div>
diff --git a/website/src/hub.js b/website/src/hub.js
index d293b7250..f11668d8c 100644
--- a/website/src/hub.js
+++ b/website/src/hub.js
@@ -6,6 +6,7 @@
 import { escape, inline } from "./markdown.js";
 import { parts, plainItem, sections } from "./releases.js";
 import { isGame, isLauncher } from "./versions.js";
+import { avatar } from "./contributors.js";
 
 export const REPO = "ludovic111/horizon";
 const issueUrl = (n) => `https://github.com/${REPO}/issues/${n}`;
@@ -85,11 +86,16 @@ export function progress(item, live) {
 
 const areaName = (roadmap, id) => roadmap.areas.find((a) => a.id === id)?.name || id;
 
+// An item's vote button: hidden until the page has the counts from the hub's server (hub-page.js).
+export function voteHtml(item) {
+  return `<button type="button" class="button secondary small hub-vote" data-vote="${escape(item.id)}" aria-pressed="false" hidden><span class="hub-vote-label">Want it</span><span class="hub-vote-count" data-votes></span></button>`;
+}
+
 export function itemHtml(item, roadmap, live) {
   const done = item.status === "shipped";
   const state = done ? "" : progress(item, live);
   return `<article class="hub-item" id="${escape(item.id)}" data-area="${escape(item.area)}" data-item="${escape(item.id)}">
-  <p class="hub-item-meta"><span class="badge">${escape(areaName(roadmap, item.area))}</span>${done ? `<span class="badge badge-game">${escape(item.shipped_in)}</span>` : ""}${item.ongoing ? `<span class="hub-ongoing">Ongoing</span>` : ""}</p>
+  <p class="hub-item-meta"><span class="badge">${escape(areaName(roadmap, item.area))}</span>${done ? `<span class="badge badge-game">${escape(item.shipped_in)}</span>` : ""}${item.ongoing ? `<span class="hub-ongoing">Ongoing</span>` : ""}${done ? "" : voteHtml(item)}</p>
   <h3 class="hub-item-title">${escape(item.title)}</h3>
   <p class="hub-plain">${inline(item.plain)}</p>
   <p class="hub-dev">${devHtml(item)}</p>
@@ -160,7 +166,7 @@ export function overviewHtml(roadmap, live = new Map()) {
   <h2 class="title" id="h-ov-help">How to help</h2>
   <p class="hub-plain">${inline(o.help_plain)}</p>
   <p class="hub-dev">${inline(o.help_dev)}</p>
-  <p class="hub-actions"><a class="button primary" href="#contribute" data-goto="contribute">Contribute</a><a class="button secondary" href="#help-wanted" data-goto="roadmap">Help wanted</a></p>
+  <p class="hub-actions"><a class="button primary" href="#contribute" data-goto="contribute">Contribute</a><a class="button secondary" href="#help-wanted" data-goto="roadmap">Help wanted</a><a class="button secondary" href="#report">Report a bug</a><a class="button secondary" href="#suggest">Suggest something</a></p>
 </section>`;
 }
 
@@ -418,3 +424,34 @@ export function journalHtml(entries, roadmap) {
     })
     .join("\n");
 }
+
+// --- Contribute: the suggestion form's items and the contributors ------------------------------------------------
+
+// The suggestion form's "About" choices: the items still to come.
+export function suggestItemsHtml(roadmap) {
+  const open = roadmap.items.filter((i) => i.status !== "shipped");
+  return [`<option value="">Something new</option>`]
+    .concat(open.map((i) => `<option value="${escape(i.id)}">${escape(i.title)}</option>`))
+    .join("");
+}
+
+// The contributors, from GitHub (contributors.js's list), with the Discord name of those who linked their accounts
+// on Kira and agreed to be credited (Kira's /contributors.json: { contributors: [{ github, discord }] }).
+export function creditFrom(github, kira) {
+  const discord = new Map(
+    (Array.isArray(kira?.contributors) ? kira.contributors : [])
+      .filter((c) => c && typeof c.github === "string" && typeof c.discord === "string")
+      .map((c) => [c.github.toLowerCase(), c.discord]),
+  );
+  return github.map((c) => ({ ...c, discord: discord.get(c.login.toLowerCase()) || "" }));
+}
+
+export function creditHtml(list) {
+  return list
+    .map((c) => {
+      const src = avatar(c.avatar_url);
+      const count = `${c.contributions.toLocaleString("en-US")} ${c.contributions === 1 ? "commit" : "commits"}`;
+      return `<li><a class="contributor" href="${escape(c.html_url)}">${src ? `<img class="contributor-avatar" loading="lazy" decoding="async" src="${escape(src)}" width="48" height="48" alt="">` : `<span class="contributor-avatar" aria-hidden="true"></span>`}<span class="contributor-name">${escape(c.login)}</span><span class="contributor-count">${count}${c.discord ? ` · ${escape(c.discord)} on Discord` : ""}</span></a></li>`;
+    })
+    .join("");
+}
diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs
index d688489e9..4213d8a87 100644
--- a/website/src/hub.test.mjs
+++ b/website/src/hub.test.mjs
@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
-import { boardFrom, boardHtml, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js";
+import { boardFrom, boardHtml, creditFrom, creditHtml, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue, suggestItemsHtml } from "./hub.js";
 
 const roadmap = JSON.parse(readFileSync(new URL("../data/roadmap.json", import.meta.url), "utf8"));
 
@@ -137,3 +137,23 @@ test("journal.json is the flat feed Kira reads: merges, releases, shipped items,
     assert.match(e.url, /^https:\/\/(github\.com|playhorizon\.dev)\//, e.id);
   }
 });
+
+test("items still to come take votes and suggestions; shipped ones don't", () => {
+  const html = roadmapHtml(roadmap);
+  for (const item of roadmap.items) {
+    assert.equal(html.includes(`data-vote="${item.id}"`), item.status !== "shipped", item.id);
+    assert.equal(suggestItemsHtml(roadmap).includes(`value="${item.id}"`), item.status !== "shipped", item.id);
+  }
+  // Hidden until the hub's server answers.
+  assert.ok(html.includes('aria-pressed="false" hidden>'));
+});
+
+test("the contributors carry the Discord name of those who agreed on Kira", () => {
+  const github = [{ login: "Alex", html_url: "https://github.com/Alex", avatar_url: "", contributions: 3 }, { login: "sam", html_url: "https://github.com/sam", avatar_url: "", contributions: 1 }];
+  const kira = { contributors: [{ github: "alex", discord: "Alex <b>" }, { github: 5 }, null] };
+  const credit = creditFrom(github, kira);
+  assert.deepEqual(credit.map((c) => c.discord), ["Alex <b>", ""]);
+  const html = creditHtml(credit);
+  assert.ok(html.includes("3 commits · Alex &lt;b&gt; on Discord") && html.includes("1 commit</span>"));
+  assert.deepEqual(creditFrom(github, "not json").map((c) => c.discord), ["", ""]);
+});
diff --git a/website/src/style.css b/website/src/style.css
index f32e24a30..1a23e79c8 100644
--- a/website/src/style.css
+++ b/website/src/style.css
@@ -645,7 +645,7 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
 
 /* Releases: a filter, then every release as a panel that opens. */
 .release-filter { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 32px; }
-.release-filter .button[aria-pressed="true"], .hub-detail .button[aria-pressed="true"] { background: var(--face); color: var(--on-face); box-shadow: inset 0 var(--block-bevel) 0 var(--face-bevel), inset 0 calc(-1 * var(--block-lip)) 0 var(--face-lip); }
+.release-filter .button[aria-pressed="true"], .hub-detail .button[aria-pressed="true"], .button.hub-vote[aria-pressed="true"] { background: var(--face); color: var(--on-face); box-shadow: inset 0 var(--block-bevel) 0 var(--face-bevel), inset 0 calc(-1 * var(--block-lip)) 0 var(--face-lip); }
 .release-count { margin: 16px 0 12px; }
 .release-list { display: grid; gap: 8px; }
 .release-list .release + .release { margin-top: 0; }
@@ -826,3 +826,26 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou
   .hub-rows .row > a { grid-template-columns: var(--index) minmax(0, 1fr); }
   .hub-rows .row-meta { grid-column: 2; text-align: left; }
 }
+
+/* --- Hub: votes, the report and suggestion forms, the contributors ---------------------- */
+.hub-vote { margin-left: auto; }
+.hub-vote-count { margin-left: -2px; }
+.hub-vote-count:empty { display: none; }
+.hub-form { display: grid; gap: 16px; max-width: 46rem; margin-top: 8px; }
+.hub-form-pair { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; }
+.hub-field { display: grid; gap: 6px; font-size: var(--text-label); color: var(--ink-soft); }
+.hub-field input, .hub-field textarea, .hub-field select {
+  width: 100%; min-height: 36px; padding: 8px 10px; font: var(--text-ui) / 1.4 var(--font); color: var(--ink);
+  background: var(--well); border: 0; box-shadow: 0 0 0 var(--block-outline) var(--outline);
+}
+.hub-field textarea { resize: vertical; }
+.hub-field input:focus-visible, .hub-field textarea:focus-visible, .hub-field select:focus-visible { outline: 1px solid var(--accent); outline-offset: 2px; }
+.hub-field input::placeholder, .hub-field textarea::placeholder { color: var(--muted); }
+.hub-trap { position: absolute; left: -10000px; width: 1px; height: 1px; overflow: hidden; }
+.hub-form-foot { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 16px; }
+.hub-form-foot [data-status] { color: var(--ink); }
+.hub-form-foot .button:disabled { opacity: 0.4; cursor: default; }
+.hub-form-closed { color: var(--ink-soft); }
+@media (max-width: 720px) {
+  .hub-form-pair { grid-template-columns: minmax(0, 1fr); }
+}

From 818b9638ed1a737d8ef09c16a3108215fc1d588e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:15:16 +0100
Subject: [PATCH 118/270] CONTRIBUTING.md and docs/README.md point to the hub

Where to start is playhorizon.dev/hub: the roadmap, the work board, good first
tasks and the forms; roadmap PRs carry their roadmap:<id> label, ideas go to the
suggestion queue and issues are for bugs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CONTRIBUTING.md | 5 +++++
 docs/README.md  | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e6e959186..21951c083 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,6 +7,11 @@ welcome on [Discord](https://discord.gg/HcTeMZxe5E).
 This repository holds the game, the launcher and the website, plus the tools, tests and docs that build, check and
 release them. Anything else (videos, Discord and other community material) lives elsewhere.
 
+**Where to start: [playhorizon.dev/hub](https://playhorizon.dev/hub).** It shows what is being done now and next
+([ROADMAP.md](ROADMAP.md) in the repository), the work board, good first tasks, and the forms to report a bug or
+suggest something. A pull request for a roadmap item carries its `roadmap:<id>` label; ideas go to the suggestion
+queue (the hub, or `/suggest` on Discord) rather than to issues, which are for bugs.
+
 ## Build it
 
 You need Rust (stable), Python 3.10+, JDK 25, and on Linux the ALSA and udev headers (`libasound2-dev libudev-dev`).
diff --git a/docs/README.md b/docs/README.md
index 1450ba388..f946ee10b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,6 @@
 # Horizon documentation
 
-To play, use [the launcher](../launcher/README.md); the project site is [playhorizon.dev](https://playhorizon.dev). These pages are for developers.
+To play, use [the launcher](../launcher/README.md); the project site is [playhorizon.dev](https://playhorizon.dev). These pages are for developers. What is being done now and next, the work board and how to help: [the hub](https://playhorizon.dev/hub) ([ROADMAP.md](../ROADMAP.md), [roadmap/README.md](../roadmap/README.md) for keeping it current).
 
 ## Build and run
 

From a6f951e126f2dc210aa278531790334ff655e10c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:22:19 +0100
Subject: [PATCH 119/270] Website: Make a mod, the full guide from the first
 line to the registry

Six pages under a "Make a mod" group of the docs: set up and see a mod in
the game (the launcher's Game arguments or cargo horizon-mod run), the
manifest and every capability, the hooks and calls with a worked example
(Playtime, built and checked), content mods, testing and check, and
publishing (minisign signing, the submit form, review, updates). /mods,
the submit page, the docs index, Mods and data packs and the Mod API link
to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api/mods.md              |   3 +
 website/build.mjs             |   2 +-
 website/docs/content-mods.md  | 114 ++++++++++++++++++++
 website/docs/index.md         |   1 +
 website/docs/make-a-mod.md    |  88 ++++++++++++++++
 website/docs/mod-code.md      | 190 ++++++++++++++++++++++++++++++++++
 website/docs/mod-manifest.md  |  60 +++++++++++
 website/docs/mods.md          |   8 +-
 website/docs/nav.json         |   1 +
 website/docs/publish-a-mod.md |  57 ++++++++++
 website/docs/test-a-mod.md    |  59 +++++++++++
 website/src/mods.js           |   1 +
 12 files changed, 580 insertions(+), 4 deletions(-)
 create mode 100644 website/docs/content-mods.md
 create mode 100644 website/docs/make-a-mod.md
 create mode 100644 website/docs/mod-code.md
 create mode 100644 website/docs/mod-manifest.md
 create mode 100644 website/docs/publish-a-mod.md
 create mode 100644 website/docs/test-a-mod.md

diff --git a/docs/api/mods.md b/docs/api/mods.md
index bec03e84e..3e6108c70 100644
--- a/docs/api/mods.md
+++ b/docs/api/mods.md
@@ -24,6 +24,9 @@ the player before the mod is turned on, and checked against the component's real
 
 ## Guide
 
+The step-by-step guide, from installing the tools to publishing on the registry, is
+[Make a mod](https://playhorizon.dev/docs/make-a-mod) on the website. In short:
+
 1. `rustup target add wasm32-unknown-unknown`, `cargo install --git https://github.com/ludovic111/horizon
    cargo-horizon-mod`, then `cargo horizon-mod new my-mod` ([Making a mod](../mods.md#making-a-mod)).
 2. Implement `Mod` for your type, list the capabilities you import in `horizon-mod.toml`
diff --git a/website/build.mjs b/website/build.mjs
index 4045297fb..d92f452ed 100644
--- a/website/build.mjs
+++ b/website/build.mjs
@@ -411,7 +411,7 @@ const modsTemplate = await readFile(join(site, "src", "mods.html"), "utf8");
 const modsList = `        <p class="kicker"><span>Mods</span>Made for Horizon, reviewed</p>
         <h1 class="display page-title">Horizon mods</h1>
         <p class="lede">Mods, modpacks and resource packs made for Horizon. Each one was reviewed before it was listed, and the launcher checks every file before it installs it. Mods run in a sandbox and can only do what their page says.</p>
-        <p class="mod-actions"><a class="button primary" href="${SUBMIT}">Submit yours</a> <a class="button secondary" href="/docs/mods">Make a mod</a></p>
+        <p class="mod-actions"><a class="button primary" href="${SUBMIT}">Submit yours</a> <a class="button secondary" href="/docs/make-a-mod">Make a mod</a></p>
         <div class="mod-tools">
           <input class="mod-search" id="mod-search" type="search" placeholder="Search" aria-label="Search the registry" autocomplete="off">
           <div class="release-filter" role="group" aria-label="Show">
diff --git a/website/docs/content-mods.md b/website/docs/content-mods.md
new file mode 100644
index 000000000..1ad8cd5fb
--- /dev/null
+++ b/website/docs/content-mods.md
@@ -0,0 +1,114 @@
+# Content mods
+
+A content mod adds blocks and items to the game with data files only: no Rust, no compiler. Each new block or item copies a vanilla one (its template) and changes what differs, and comes with its recipes, loot table, tags, model, textures and name, in the same formats as vanilla's data packs and resource packs.
+
+## What a content mod is
+
+A folder (while you work on it) or a `.hmod` zip (to share it) holding a manifest, `assets/` and `data/`. This is the SDK's [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) example, a ruby gem and a block of ruby:
+
+```
+ruby/
+├── horizon-mod.toml
+├── data/ruby/horizon/block/ruby_block.json        the block: a template and what differs
+├── data/ruby/horizon/item/ruby.json               the item
+├── data/ruby/recipe/ruby_block.json               recipes, as in a data pack
+├── data/ruby/recipe/ruby_from_ruby_block.json
+├── data/ruby/loot_table/blocks/ruby_block.json    what the block drops
+├── data/minecraft/tags/block/mineable/pickaxe.json   added to vanilla's tags
+├── data/minecraft/tags/block/needs_iron_tool.json
+├── assets/ruby/blockstates/ruby_block.json        models and textures, as in a resource pack
+├── assets/ruby/models/block/ruby_block.json
+├── assets/ruby/models/item/ruby.json
+├── assets/ruby/items/ruby.json
+├── assets/ruby/items/ruby_block.json
+├── assets/ruby/textures/block/ruby_block.png
+├── assets/ruby/textures/item/ruby.png
+└── assets/ruby/lang/en_us.json                    the names players see
+```
+
+Its manifest asks for API `0.2` and the `registries` capability. It has no code, so it needs no `Cargo.toml` and no `mod.wasm`:
+
+```toml
+id = "ruby"
+name = "Ruby"
+version = "0.1.0"
+description = "A ruby gem and a block of ruby"
+authors = ["You"]
+api = "0.2"
+side = "both"
+capabilities = ["registries"]
+```
+
+## Blocks
+
+A block is a file `data/<id>/horizon/block/<name>.json`. It becomes the block `<id>:<name>`, with the template's behaviour, states and shapes:
+
+```json
+{
+  "template": "minecraft:iron_block",
+  "properties": { "hardness": 4.0, "light": 3, "sounds": "minecraft:amethyst_block", "map_color": 28 }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `template` | The vanilla block it copies, such as `minecraft:iron_block`, `minecraft:oak_door` or `minecraft:diamond_ore`. A door copies a door's states and shape, an ore an ore's. |
+| `properties.hardness` | How long it takes to mine (vanilla's destroy time; `-1` cannot be broken). |
+| `properties.explosion_resistance` | How well it stands up to explosions. |
+| `properties.light` | The light it gives, 0 to 15. |
+| `properties.requires_tool` | `true`: it drops nothing unless mined with the right tool (the tags say which). |
+| `properties.friction` | How slippery it is (ice is `0.98`). |
+| `properties.map_color` | Its colour on maps, a vanilla map colour id from 0 to 61. |
+| `properties.sounds` | A vanilla block whose sounds it uses. |
+| `item` | `false` for a block with no item. By default the block gets an item of the same id. |
+
+Every property you leave out is the template's.
+
+## Items
+
+An item is a file `data/<id>/horizon/item/<name>.json`, copying a vanilla item:
+
+```json
+{ "template": "minecraft:diamond", "rarity": "uncommon" }
+```
+
+It may change `max_stack_size` (1 to 99) and `rarity` (`common`, `uncommon`, `rare` or `epic`, the colour of its name).
+
+## Recipes, loot, tags, models and names
+
+Everything else uses vanilla 26.3's own formats, so the [Minecraft Wiki's](https://minecraft.wiki/w/Data_pack) pages on data packs and resource packs apply:
+
+- **Recipes** in `data/<id>/recipe/`, **loot tables** in `data/<id>/loot_table/`.
+- **Tags**: your own in `data/<id>/tags/`. To add to vanilla's (which pickaxe mines the block, for example), put a tag file in `data/minecraft/tags/`; to add to the convention tags NeoForge and Fabric mods share, in `data/c/tags/`. They add to the tag as a data pack does; `"replace": true` drops what came before it, and the log says so.
+- **Block states, models, item models and textures** in `assets/<id>/`, as in a resource pack. Models can use vanilla's parents, such as `minecraft:block/cube_all`.
+- **Names** in `assets/<id>/lang/en_us.json`: `"block.ruby.ruby_block": "Block of Ruby"`, `"item.ruby.ruby": "Ruby"`.
+
+**Structures.** A content mod can also carry structures, template pools and structure sets in its namespace, and add its own pieces to vanilla's villages or to another mod's pools. The [mod design page](https://github.com/ludovic111/horizon/blob/main/docs/mods.md#content-mods-api-02) has the details.
+
+## Namespaces
+
+Your files go under your mod's id (`assets/ruby/`, `data/ruby/`), plus vanilla's and the convention tags (`data/minecraft/tags/`, `data/c/tags/`). Tags are the only files a mod may put under `minecraft`.
+
+A mod made from a Java mod whose files use other names lists them in its manifest: `namespaces = ["kaisyn", "towns_and_towers"]`. A listed namespace is the mod's own, as its id is, but blocks and items are still declared under `data/<id>/horizon/`. `minecraft`, `c` and `horizon` can't be listed, and two mods that are on can't own the same namespace: the game keeps the first and logs the clash.
+
+## Limits
+
+- A mod's files use vanilla's resource-name characters: at most 65,536 files, 16 MiB each and 512 MiB in all.
+- A file the game can't read (a block model that doesn't parse, a recipe with a typo) is logged and skipped, as vanilla does: the rest of the mod still loads. Read the log while you work.
+- Unknown keys in a block or item file are refused, and the mod stays off with the reason on its row.
+- Content mods work in single player today. Playing them together on a server is planned.
+
+## Try it and share it
+
+While you work, give the game the folder as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)): `--dev-mod "/path/to/ruby"`. The first start with a new set of mods takes a little longer while the game adds their content to its tables; after a change to the files, start the game again.
+
+To share it, zip the folder's contents, with `horizon-mod.toml` at the top of the zip, and name the file `<id>.hmod`:
+
+```sh
+cd ruby
+zip -r ../ruby.hmod horizon-mod.toml assets data
+```
+
+Players put that file in their `horizon-mods` folder and turn it on in **Options, Mods...**. The registry doesn't take content-only mods yet: its checks (`cargo horizon-mod check`) expect code in the file. That is coming next.
+
+Next: [test it](/docs/test-a-mod).
diff --git a/website/docs/index.md b/website/docs/index.md
index 2b16c4db9..24f969840 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -30,4 +30,5 @@ There is no build for Intel Macs, 32-bit systems, or ARM Linux and Windows. The
 - **Playing:** [install and first launch](/docs/install), [settings worth knowing](/docs/settings), [multiplayer](/docs/multiplayer) and [what to do when something breaks](/docs/troubleshooting).
 - **Hosting:** [host a server](/docs/hosting), from the launcher or the command line.
 - **Going further:** [modpacks](/docs/modpacks), [mods and data packs](/docs/mods) and [performance](/docs/performance).
+- **Making mods:** [make a mod](/docs/make-a-mod), from the first line of code to the registry, and the [Mod API](/docs/api/mods).
 - **Helping out:** [contribute](/docs/contributing) and the [FAQ](/docs/faq).
diff --git a/website/docs/make-a-mod.md b/website/docs/make-a-mod.md
new file mode 100644
index 000000000..94c3deca2
--- /dev/null
+++ b/website/docs/make-a-mod.md
@@ -0,0 +1,88 @@
+# Make a mod
+
+This guide takes you from nothing to a mod that other players can install from [playhorizon.dev/mods](/mods). You write the mod in Rust. It is compiled to WebAssembly and runs in a sandbox, so a player can see what it may do before turning it on. You need no Minecraft modding experience.
+
+## The path
+
+1. **Set up** (this page): install Rust and `cargo horizon-mod`, make your first mod and see it in the game.
+2. **[The manifest and capabilities](/docs/mod-manifest)**: the file that names your mod and lists what it may do.
+3. **[Write the code](/docs/mod-code)**: the hooks the game calls, what your code can call, and a worked example.
+4. **[Content mods](/docs/content-mods)**: blocks, items, recipes and textures from data files, with no code at all.
+5. **[Test it](/docs/test-a-mod)**: unit tests, the game's dev mode and the registry's own checks.
+6. **[Publish it](/docs/publish-a-mod)**: package, sign and submit it to the registry.
+
+The [Mod API](/docs/api/mods) lists everything a mod can do today, and its [reference](/docs/api/mods-reference) has every function and type.
+
+## What a mod can do today
+
+- **Client mods** run in the player's game. They read what the F3 screen shows (position, facing, health, food, dimension, the time), draw a text panel on the screen, show chat lines only that player sees, add chat commands, and keep small files of their own. They work in single player and on any server, and a server cannot see them.
+- **Content mods** add blocks and items copied from vanilla templates, with their recipes, loot tables, tags, models, textures and names. They need no code.
+- **Server mods** (rules, world events, server commands) are being built. The [Mod API](/docs/api/mods#not-there-yet) says what comes next.
+
+A Horizon mod is not a Java mod. Fabric, NeoForge and Forge jars don't run in Horizon, and Horizon mods don't run in Java Minecraft.
+
+## Install the tools
+
+You need [Rust](https://rustup.rs) (the stable toolchain), its WebAssembly target and `cargo horizon-mod`, the tool that makes, builds and checks mods. On Windows, macOS or Linux:
+
+```sh
+rustup target add wasm32-unknown-unknown
+cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod
+```
+
+The second command builds the tool from source, which takes a few minutes the first time. Run it again later to update the tool.
+
+You also need Horizon itself, installed with the launcher ([Install](/docs/install)), and prepared at least once so the game has its files.
+
+## Make your first mod
+
+```sh
+cargo horizon-mod new my-mod
+cd my-mod
+```
+
+`new` makes a folder with a working mod in it: a `/hello` command that answers in chat. `--name "My Mod"` sets the name players see. The folder holds:
+
+```
+my-mod/
+├── Cargo.toml          the Rust crate (a cdylib depending on horizon-mod-sdk)
+├── horizon-mod.toml    the manifest: id, name, version, what the mod may do
+├── .gitignore
+└── src/lib.rs          the code
+```
+
+Build it:
+
+```sh
+cargo horizon-mod build
+```
+
+This compiles the crate, checks that the code uses nothing its manifest doesn't declare, and writes `target/horizon-mod/my_mod.hmod`. A `.hmod` is a zip file holding the manifest and the compiled code (`mod.wasm`). It is the one file you give players: the same file runs on Windows, macOS and Linux.
+
+## See it in the game
+
+A **dev mod** is a mod the game loads from a path you give it. It is always on, and the game looks at its file once a second: build again and the game reloads it, saying "Mods reloaded" in chat. Its memory starts over; what it saved to its storage stays.
+
+**From the launcher.** Open the launcher's **Settings** and put this in **Game arguments**, with the full path to your file:
+
+```
+--dev-mod "/path/to/my-mod/target/horizon-mod/my_mod.hmod"
+```
+
+Then press **Play**, open a world and type `/hello world` in chat. Leave the setting there while you work on the mod, and clear it when you are done. The launcher's command line does the same: `horizon-launcher play --arg --dev-mod --arg /path/to/my_mod.hmod`.
+
+**With `cargo horizon-mod run`.** If you have a `horizon-client` you built from source, `cargo horizon-mod run` builds the mod and starts that game with it. It looks for `horizon-client` on your `PATH`, or takes `--game <path>` or the `HORIZON_CLIENT` variable; anything after `--` goes to the game:
+
+```sh
+cargo horizon-mod run --game ../horizon/target/fast/horizon-client -- --resources ../horizon/.local/horizon-client/26.3
+```
+
+Either way, edit `src/lib.rs`, run `cargo horizon-mod build`, and the game picks up the new file.
+
+## Where things go
+
+- **Your mod's messages** go to the game log as `[mod my_mod] …` (the `logs/latest.log` file in the game folder), and the game prints them in its terminal too.
+- **Mods players install** go in the `horizon-mods` folder of the game folder (Linux `~/.local/share/horizon`, macOS `~/Library/Application Support/horizon`, Windows `%APPDATA%\horizon`). **Options, Mods...** in the game lists them, each with what it may do and a switch. They start off.
+- **A mod that fails** to load, or that breaks while running, is switched off with the reason in red on its row of the Mods screen. It never takes the game down with it.
+
+Next: [the manifest and capabilities](/docs/mod-manifest).
diff --git a/website/docs/mod-code.md b/website/docs/mod-code.md
new file mode 100644
index 000000000..42cc6f04b
--- /dev/null
+++ b/website/docs/mod-code.md
@@ -0,0 +1,190 @@
+# Write the code
+
+A mod is a Rust type that implements the `Mod` trait from `horizon-mod-sdk`. The game calls its methods, the hooks, at fixed points, and the mod calls back into the game through the parts of the API its capabilities allow. This page explains both, then builds a complete mod step by step.
+
+## The shape of a mod
+
+```rust
+use horizon_mod_sdk::{Mod, Registration, chat};
+
+struct Hello {
+    greeted: u32,
+}
+
+impl Mod for Hello {
+    fn init() -> Result<(Self, Registration), String> {
+        Ok((Hello { greeted: 0 }, Registration::new().command("hello")))
+    }
+
+    fn command(&mut self, _name: &str, args: &str) -> Result<Option<String>, String> {
+        self.greeted += 1;
+        chat::show(&format!("Hello {args}! ({} so far)", self.greeted));
+        Ok(None)
+    }
+}
+
+horizon_mod_sdk::export_mod!(Hello);
+```
+
+- **The state lives in your type.** `init` creates it, and every hook gets `&mut self`.
+- **`export_mod!`** connects the type to the game. A mod has exactly one.
+- **The game calls only the hooks you ask for.** `init` returns a `Registration` that lists them. The other methods keep their default, empty bodies, and a hook you didn't ask for costs nothing.
+
+## Hooks
+
+| Hook | Ask for it with | When the game calls it |
+| --- | --- | --- |
+| `init() -> Result<(Self, Registration), String>` | always called | Once, when the mod loads. An `Err` keeps the mod off and shows the message on its row. |
+| `tick(&mut self, tick: u64)` | `.on_tick()` | Every game tick while the player is in a world: 20 times a second. |
+| `frame(&mut self, seconds: f32)` | `.on_frame()` | Every frame the game draws, with the time since the last one. |
+| `command(&mut self, name: &str, args: &str)` | `.command("name")` | When the player types `/name …` in chat. `args` is everything after the name. |
+| `chat(&mut self, text: &str)` | `.on_chat()` | For each chat line the player receives, as plain text. |
+
+**Commands.** Ask for as many as you like with `.command("…")`, without the slash. The chat box colours them and completes them with Tab, like vanilla's commands. Vanilla's names win: a mod can't take `/give`, and when two mods ask for the same name, the first one loaded keeps it. The game logs both cases. The return value says what happens next:
+
+- `Ok(None)`: nothing more. Use it when the mod already answered with `chat::show`.
+- `Ok(Some(text))`: the game shows `text` to the player.
+- `Err(text)`: the game shows `text` in red, as a failed command.
+
+**Prefer ticks to frames.** A tick happens 20 times a second whatever the frame rate. The HUD panel is kept by the game and drawn every frame for you, so most mods never need `frame`.
+
+## What your code can call
+
+Each module of the SDK is one part of the API, and each needs its capability in the manifest ([the list](/docs/mod-manifest#capabilities)):
+
+| Module | Capability | Calls |
+| --- | --- | --- |
+| `game` | `game-read` | `get_player() -> Option<Player>` (`x`, `y`, `z`, `yaw`, `pitch`, `health`, `food`, `dimension`), `get_clock() -> Option<Clock>` (`game_time`, `day_time`). `None` outside a world. |
+| `chat` | `chat` | `show(text)` |
+| `hud` | `hud` | `set_panel(Corner, &[Line])` (`Line { text, color }`, colour as `0xRRGGBB`; corners `TopLeft`, `TopRight`, `BottomLeft`, `BottomRight`), `clear()` |
+| `storage` | `storage` | `get(key) -> Option<Vec<u8>>`, `set(key, &[u8]) -> Result<(), String>`, `delete(key)` |
+| `log` | none | `horizon_mod_sdk::info(text)` and `warn(text)`: lines in the game log |
+
+What the game reads for you (`game`) is a snapshot taken once a tick, and again before a command runs. It never changes in the middle of a call. Everything else is plain Rust: your own types, maths and text, and the crates you add to `Cargo.toml`, as long as they build for `wasm32-unknown-unknown` without the operating system (no files, threads, network or clock).
+
+## A worked example: Playtime
+
+This mod counts how long you play, shows it in the top-right corner, and keeps the count when you quit. `/playtime` says it in chat; `/playtime hide`, `show` and `reset` do what they say. It uses three capabilities (`hud`, `chat`, `storage`) and two hooks (`tick`, `command`).
+
+**1. Make the mod.**
+
+```sh
+cargo horizon-mod new playtime --name "Playtime"
+cd playtime
+```
+
+**2. Declare what it may do.** In `horizon-mod.toml`, set the description and the capabilities:
+
+```toml
+description = "How long you have played, in a corner of the screen"
+capabilities = ["hud", "chat", "storage"]
+```
+
+**3. The state and a helper.** Replace `src/lib.rs` with the code below, in parts. First the imports, the state and a function that turns ticks into hours and minutes. It touches no API, so an ordinary unit test can check it (step 7).
+
+```rust
+use horizon_mod_sdk::{
+    Mod, Registration, chat,
+    hud::{self, Corner, Line},
+    storage,
+};
+
+/// Ticks played, kept across sessions in the mod's storage.
+struct Playtime {
+    ticks: u64,
+    shown: bool,
+}
+
+/// `1h 05m` from a number of ticks (20 a second).
+fn format(ticks: u64) -> String {
+    let minutes = ticks / 20 / 60;
+    format!("{}h {:02}m", minutes / 60, minutes % 60)
+}
+```
+
+**4. Saving and drawing.** `storage::set` writes bytes under a key of your choice; it can fail when the mod is over its quota, so the error goes to the log. The panel is set once and the game draws it until it changes, so redraw only when there is something new to show.
+
+```rust
+impl Playtime {
+    fn save(&self) {
+        if let Err(e) = storage::set("ticks", &self.ticks.to_le_bytes()) {
+            horizon_mod_sdk::warn(&format!("could not save: {e}"));
+        }
+    }
+
+    fn draw(&self) {
+        if self.shown {
+            let line = Line { text: format!("Played {}", format(self.ticks)), color: 0xFFFF55 };
+            hud::set_panel(Corner::TopRight, &[line]);
+        } else {
+            hud::clear();
+        }
+    }
+}
+```
+
+**5. The hooks.** `init` reads what an earlier session saved, draws the panel and asks for one command and the tick hook. `tick` counts, and once a minute redraws and saves. `command` reads its arguments.
+
+```rust
+impl Mod for Playtime {
+    fn init() -> Result<(Self, Registration), String> {
+        // What an earlier session saved, or 0 the first time.
+        let ticks = storage::get("ticks")
+            .and_then(|bytes| bytes.try_into().ok())
+            .map_or(0, u64::from_le_bytes);
+        let state = Playtime { ticks, shown: true };
+        state.draw();
+        Ok((state, Registration::new().command("playtime").on_tick()))
+    }
+
+    fn tick(&mut self, _tick: u64) {
+        self.ticks += 1;
+        // Once a minute: redraw the panel and save.
+        if self.ticks % (20 * 60) == 0 {
+            self.draw();
+            self.save();
+        }
+    }
+
+    fn command(&mut self, _name: &str, args: &str) -> Result<Option<String>, String> {
+        match args.trim() {
+            "" => chat::show(&format!("You have played {}", format(self.ticks))),
+            "hide" | "show" => {
+                self.shown = args.trim() == "show";
+                self.draw();
+            }
+            "reset" => {
+                self.ticks = 0;
+                self.save();
+                self.draw();
+                return Ok(Some("Playtime reset".into()));
+            }
+            other => return Err(format!("Unknown option {other}: use hide, show or reset")),
+        }
+        Ok(None)
+    }
+}
+
+horizon_mod_sdk::export_mod!(Playtime);
+```
+
+**6. Try it.** `cargo horizon-mod build`, then start the game with it as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)). Open a world: "Played 0h 00m" sits in the top-right corner and goes up each minute. Type `/playtime`, then `/playtime hide`. `/playtime foo` answers in red. Quit and come back: the count goes on from where it was.
+
+**7. Test the helper.** At the end of `src/lib.rs`:
+
+```rust
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn formats_hours_and_minutes() {
+        assert_eq!(super::format(0), "0h 00m");
+        assert_eq!(super::format(20 * 60 * 65), "1h 05m");
+    }
+}
+```
+
+`cargo test` runs it on your computer, with no game. [Test it](/docs/test-a-mod) covers the rest.
+
+**Where to go from here.** The SDK's examples are complete mods to read: [`coords-hud`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/coords-hud) (coordinates, facing and the time on the HUD, `/where` and `/coords`) and [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) (a content mod). The [reference](/docs/api/mods-reference) lists every type and function, with its limits.
+
+Next: [content mods](/docs/content-mods), or straight to [testing](/docs/test-a-mod) if your mod has no blocks or items.
diff --git a/website/docs/mod-manifest.md b/website/docs/mod-manifest.md
new file mode 100644
index 000000000..c0e0e4b51
--- /dev/null
+++ b/website/docs/mod-manifest.md
@@ -0,0 +1,60 @@
+# The manifest and capabilities
+
+Every mod has a `horizon-mod.toml` at its root. It names the mod, says which version of the mod API it was made for, and lists its capabilities: what it may do. Players read that list before they turn the mod on, and the game holds the mod to it.
+
+## The manifest
+
+```toml
+id = "playtime"
+name = "Playtime"
+version = "0.1.0"
+description = "How long you have played, in a corner of the screen"
+authors = ["You"]
+api = "0.1"
+side = "client"
+capabilities = ["hud", "chat", "storage"]
+```
+
+| Key | What it is |
+| --- | --- |
+| `id` | The mod's id: 1 to 64 characters of `a-z`, `0-9` and `_`. It names the mod's setting, its log lines, its storage folder and, for content, its namespace. Keep it once you have published the mod. |
+| `name` | The name players see. |
+| `version` | Your mod's version, such as `0.1.0`. Each version you publish needs a new one. |
+| `description` | One or two sentences for the Mods screen. |
+| `authors` | A list of names. |
+| `api` | The mod API line the mod was made for: `"0.1"` for code, `"0.2"` for content. The game refuses a line it doesn't serve, with a message that says so. |
+| `side` | `"client"` for a mod that runs in the player's game. Content mods use `"both"`. |
+| `capabilities` | What the mod may do: the list below. |
+| `namespaces` | Content mods only: extra namespaces the mod's files use (see [Content mods](/docs/content-mods#namespaces)). |
+
+Unknown keys are refused, so a typo is an error, not a permission that silently does nothing.
+
+## Capabilities
+
+A capability is a part of the API the mod may use. Each one shows on the Mods screen as a sentence that starts with "May". Writing to the game log needs no capability.
+
+| Capability | The player reads | What the code can do |
+| --- | --- | --- |
+| `game-read` | May see your position, health and the time | `game::get_player()`: position, facing (yaw and pitch), health, food and dimension. `game::get_clock()`: the game time and the time of day. |
+| `chat` | May show you chat messages | `chat::show(text)`: a chat line only this player sees, after the mod's name. At most 8 per call into the mod. |
+| `hud` | May draw text on your screen | `hud::set_panel(corner, lines)` and `hud::clear()`: a panel of up to 16 coloured lines of 256 characters in one corner. The game keeps drawing it until you change it. |
+| `storage` | May save its own settings to disk | `storage::get`, `set` and `delete`: small files in a folder of the mod's own. Up to 64 files and 4 MiB in all, and at most 1 MiB written per call. Keys are 1 to 64 characters of `a-z`, `0-9`, `_`, `.` and `-`. |
+| `registries` | May add blocks and items to your worlds | Content mods: blocks and items from the mod's data files. No code. |
+
+Ask only for what the mod uses: players are more likely to turn on a mod that asks for little.
+
+**The game checks.** When you build, and again when a game loads the mod, the compiled code's imports are compared with the manifest. A mod whose code calls `chat::show` without `chat` in its capabilities is refused (`uses capability chat, missing from horizon-mod.toml`). The list players read is what the code can do, not a promise.
+
+## What no mod can do
+
+A mod runs in a WebAssembly sandbox. Whatever its capabilities:
+
+- It cannot open files (apart from its own storage), the network, other programs or the clock.
+- It sees the game only through the snapshot the game gives it once a tick, and changes it only through the calls above. It cannot patch the game's code.
+- It has 64 MiB of memory and a time budget for each call. A mod that runs past its budget, runs out of memory or crashes is switched off, with the reason on its row of the Mods screen. The game goes on.
+
+## API versions
+
+The mod API is versioned apart from the game. A mod made for API `0.1` keeps loading on every game that serves `0.1`, and new functions arrive as additions. A change that would break mods comes as a new line, served beside the old one for at least one release cycle. The [stability page](/docs/api/stability) has the whole policy, and the [Mod API's changelog](/docs/api/mods#changelog) what each line added.
+
+Next: [write the code](/docs/mod-code).
diff --git a/website/docs/mods.md b/website/docs/mods.md
index 77a1734fd..405c62976 100644
--- a/website/docs/mods.md
+++ b/website/docs/mods.md
@@ -6,7 +6,7 @@ Horizon has its own mod system, written for Horizon and not compatible with Java
 
 Horizon mods are written in Rust, compiled to WebAssembly and run in a sandbox. A mod can only do what it asks for and you allow, and a mod that crashes is switched off without taking the game down.
 
-> **Early.** The mod system is new. There is no store for Horizon mods yet: they are files to put in a folder. The launcher's **Mods** page (see below) finds resource packs and modpacks, not `.hmod` mods.
+> **Early.** The mod system is new. Reviewed mods are listed at [playhorizon.dev/mods](/mods), and any `.hmod` file can be put in the folder by hand.
 
 **Playing with mods**
 
@@ -22,15 +22,17 @@ Horizon mods are written in Rust, compiled to WebAssembly and run in a sandbox.
 
 **Making a mod**
 
+[Make a mod](/docs/make-a-mod) is the full guide: the tools, your first mod in the game, the manifest and capabilities, the code with a worked example, content mods, testing, and publishing on [the registry](/mods). In short:
+
 ```sh
 rustup target add wasm32-unknown-unknown
 cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod
 cargo horizon-mod new my-mod
 cd my-mod
-cargo horizon-mod run
+cargo horizon-mod build
 ```
 
-`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The [Mod API](/docs/api/mods) lists what a mod can do today, its [reference](/docs/api/mods-reference), the [ways in](/docs/api/mods#ways-in) (Rust today, Lua scripts planned) and what comes next; the full guide, with the manifest and the runtime, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)).
+The [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](/docs/modpacks)).
 
 ## Finding resource packs and modpacks
 
diff --git a/website/docs/nav.json b/website/docs/nav.json
index 18eab69fd..76c06dc47 100644
--- a/website/docs/nav.json
+++ b/website/docs/nav.json
@@ -3,6 +3,7 @@
   { "group": "Playing", "pages": ["settings", "multiplayer", "troubleshooting"] },
   { "group": "Hosting", "pages": ["hosting"] },
   { "group": "Going further", "pages": ["modpacks", "mods", "performance", "agents"] },
+  { "group": "Make a mod", "pages": ["make-a-mod", "mod-manifest", "mod-code", "content-mods", "test-a-mod", "publish-a-mod"] },
   { "group": "Build on Horizon", "pages": ["apis", "api", "api/stability"] },
   { "group": "API reference", "pages": ["api/mods", "api/mods-reference", "api/mod-index", "api/server", "api/server-reference", "api/agent-control", "api/launcher", "api/data-formats", "api/shaders"] },
   { "group": "Project", "pages": ["contributing", "faq"] }
diff --git a/website/docs/publish-a-mod.md b/website/docs/publish-a-mod.md
new file mode 100644
index 000000000..c24a77a2f
--- /dev/null
+++ b/website/docs/publish-a-mod.md
@@ -0,0 +1,57 @@
+# Publish a mod
+
+Horizon's registry lists mods, modpacks and resource packs made for Horizon. Players find them at [playhorizon.dev/mods](/mods) and on the launcher's Mods page, which checks every file before it installs it. Each project is reviewed by a person before it is published. This page takes your mod from a file on your computer to the registry.
+
+## Before you submit
+
+1. **Choose a version.** Set `version` in `horizon-mod.toml` (such as `1.0.0`). Every version you publish needs a new one, and a published file never changes.
+2. **Build it for release.** `cargo horizon-mod build` (release is the default; `--debug` is for quick local builds) writes `target/horizon-mod/<id>.hmod`. That file is what you submit.
+3. **Check it.** `cargo horizon-mod check target/horizon-mod/<id>.hmod` must pass ([Test a mod](/docs/test-a-mod#check-it-as-the-registry-does)).
+4. **Publish the source.** Put the mod's source in a public repository, under a licence that lets players use it (MIT, Apache-2.0, GPL and so on, as an [SPDX](https://spdx.org/licenses/) name). Reviewers read it, and the file must be built from it.
+
+## Sign it
+
+Signing is optional and recommended. When your project has a public key, every later version must be signed with the matching secret key, so nobody else can publish an update in your name, even with access to your GitHub account.
+
+Horizon uses [minisign](https://jedisct1.github.io/minisign/) signatures. Install minisign (`brew install minisign`, `scoop install minisign`, or your Linux distribution's package), then make a key pair once:
+
+```sh
+minisign -G -p horizon-mods.pub -s horizon-mods.key
+```
+
+Keep `horizon-mods.key` and its password private and backed up: losing it means changing the project's key by hand, through the registry's maintainers. The public key is the last line of `horizon-mods.pub` (it starts with `RW`).
+
+Sign each file you publish, and check the signature as the registry will:
+
+```sh
+minisign -S -s horizon-mods.key -m target/horizon-mod/playtime.hmod
+cargo horizon-mod check target/horizon-mod/playtime.hmod --key "RW…your public key…" --signature target/horizon-mod/playtime.hmod.minisig
+```
+
+The report then says "signature verified".
+
+## Submit it
+
+Open [playhorizon.dev/mods/submit](/mods/submit) and sign in with GitHub. The page reads only your public profile. Then fill in:
+
+- **The file**: the kind (mod), the `.hmod`, its id (the manifest's `id`), its version, the Minecraft version (26.3) and what changed.
+- **Its page**: the name, a one-line summary for the list, a description (Markdown), the authors, the licence, the source address and, optionally, a square PNG icon (at most 256 KiB).
+- **Signature**: your public key (for a new project) and the file's `.minisig`.
+
+**Submit for review** checks the file again and opens a pull request in [ludovic111/horizon-mods](https://github.com/ludovic111/horizon-mods). It adds `mods/<id>.toml`, with you as the project's owner. The repository's checks run the file in the sandbox and post their report on the pull request.
+
+## Review and publication
+
+A reviewer reads the pull request, your source and the checks' report. Questions and requests for changes come as comments on the pull request: answer them there, and submit a new version from the form when the file must change.
+
+When the reviewer merges it, the file becomes a release of horizon-mods within minutes, and the project gets its page at `playhorizon.dev/mods/<id>` and shows in the launcher. The page lists what the mod may do, as the game's Mods screen does, with your source, licence and the file's SHA-256.
+
+## Updates
+
+An update is the same form with a new version: it adds the version to your project's entry. The project's owners publish updates without a reviewer's extra look, and if the project has a key, the new file must be signed with it.
+
+Without the form, you can open the pull request by hand: the [horizon-mods README](https://github.com/ludovic111/horizon-mods) says how. The registry's file formats are in [the mod index reference](/docs/api/mod-index).
+
+## Reports and takedowns
+
+Anyone can report a project from its page (**Report it**). A project that does harm is taken down: the launcher then refuses its files and turns installed copies off, telling players why.
diff --git a/website/docs/test-a-mod.md b/website/docs/test-a-mod.md
new file mode 100644
index 000000000..650810963
--- /dev/null
+++ b/website/docs/test-a-mod.md
@@ -0,0 +1,59 @@
+# Test a mod
+
+Three kinds of checks catch most mistakes before players see them: unit tests for your own logic, the game's dev mode for how the mod looks and feels, and `cargo horizon-mod check`, which runs the same checks as the registry.
+
+## Unit tests for your logic
+
+Code that doesn't call the game (formatting, maths, parsing a command's arguments) is ordinary Rust. Put it in plain functions and test it with `#[test]`, as the [Playtime example](/docs/mod-code#a-worked-example-playtime) does with its `format` function:
+
+```sh
+cargo test
+```
+
+The tests run on your computer, with no game and no WebAssembly. Keeping the hooks thin and the logic in functions makes most of a mod testable this way.
+
+## In the game, as a dev mod
+
+Start the game with your mod as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)) and keep it running. After each edit:
+
+```sh
+cargo horizon-mod build
+```
+
+The game sees the new file within a second, says "Mods reloaded" in chat and starts the mod over. What it saved with `storage` stays. Things to try each time:
+
+- Every command, with no arguments, with good ones and with wrong ones. An `Err` should say what to type instead.
+- Leaving the world and opening another: `game::get_player()` is `None` on the title screen.
+- Quitting and starting again, for a mod that saves.
+- **Options, Mods...**: the mod's row lists what it may do. If it says the mod stopped, the reason is there.
+
+The game log (`logs/latest.log` in the game folder) has your mod's `info` and `warn` lines as `[mod <id>]`, and the reason when the game refused or stopped the mod.
+
+**Why a mod stops.** A mod that panics, runs past its time budget for one call (an endless loop, for example) or uses more than 64 MiB of memory is switched off. The rest of the game carries on. Fix the cause and build again: a dev mod starts over with the new file.
+
+## Check it as the registry does
+
+Before you publish, run what the registry runs on every submission:
+
+```sh
+cargo horizon-mod check target/horizon-mod/playtime.hmod
+```
+
+```
+playtime 0.1.0 (mod, API 0.1, client)
+  12424 bytes, SHA-256 6561…ac13, unsigned
+  may draw text on your screen
+  may show you chat messages
+  may save its own settings to disk
+  trial run: started, 40 ticks, 120 frames, a chat line, /playtime: ok
+```
+
+It reads the manifest, refuses code that uses a capability the manifest doesn't list, then plays the mod in the sandbox, as the game does: 40 ticks with a moving player, 120 frames, a chat line and each of its commands once with no arguments. The mod must start and must never crash or overrun its budget. It fails with the reason when one of those goes wrong.
+
+- `--json` prints the report as JSON, for scripts.
+- `--key <public key> --signature <file>.minisig` also checks your signature ([Publish](/docs/publish-a-mod#sign-it)).
+- It checks modpacks (`.hpack`) and resource packs (`.zip`) too; `--kind mod|modpack|resourcepack` when the file's extension doesn't say which.
+
+A mod that passes `check` passes the registry's automatic checks. A person still reviews it (see [Publish](/docs/publish-a-mod)).
+
+Next: [publish it](/docs/publish-a-mod).
diff --git a/website/src/mods.js b/website/src/mods.js
index 4819af374..a597e2847 100644
--- a/website/src/mods.js
+++ b/website/src/mods.js
@@ -121,6 +121,7 @@ export function submitHtml() {
   return `<p class="kicker"><span>Mods</span>Submit</p>
         <h1 class="display page-title">Submit to the registry</h1>
         <p class="lede">A mod, a modpack of registry mods, or a resource pack made for Horizon. The form checks the file and opens a pull request; a reviewer reads it, its source and the checks' report, and merging publishes it to this site and the launcher.</p>
+        <p class="meta">First time? <a href="/docs/publish-a-mod">Publish a mod</a> walks through building, checking and signing the file, and <a href="/docs/make-a-mod">Make a mod</a> starts from the beginning.</p>
         <div class="mod-auth" id="submit-auth" aria-live="polite">
           <p class="meta no-script">The form needs JavaScript. You can also <a href="${REGISTRY}">open a pull request by hand</a>.</p>
         </div>

From 5dcbe222c94261c7291659a15a06549f46134014 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:00:44 +0100
Subject: [PATCH 120/270] Shader packs, clean room 37: shadow settings and the
 shadow camera

The stage files' shadow constants (shadowMapResolution, shadowDistance,
shadowDistanceRenderMul, shadowIntervalSize, sunPathRotation, shadowMapFov,
shadowNearPlane, shadowFarPlane, shadowHardwareFiltering[0|1] and the
shadowcolor0/1 Format, Clear and ClearColor) are read into Config::shadow
(spec 6.3, 7.1).

The shadow matrices are no longer a placeholder (OQ-6): the camera looks
from the shadow light, sits 128 blocks toward it from a point that moves in
steps of shadowIntervalSize along the shadow view's own axes, and projects
orthographically over shadowDistance each side (or in perspective with
shadowMapFov), between shadowNearPlane and shadowFarPlane.

sunPathRotation turns the sun and moon's path about the world's X axis:
sunPosition, moonPosition, shadowLightPosition and the shadow camera follow
it, and so do the sun, moon and stars a pack's gbuffers_skytextured and
gbuffers_skybasic draw.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
sections 6.3 and 7.1; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_post.rs    |   6 +-
 crates/horizon-client/src/gfx/pack_sky.rs     |  10 +-
 .../horizon-client/src/gfx/pack_uniforms.rs   | 121 +++++++++++++---
 crates/horizon-shaders/src/config.rs          | 136 ++++++++++++++++++
 crates/horizon-shaders/src/lib.rs             |   2 +-
 5 files changed, 252 insertions(+), 23 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 57c24b1ed..2be557c17 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -879,6 +879,7 @@ impl PackPost {
         });
         let mut notes = post.notes;
         notes.extend(post.config.notes);
+        let shadow_config = post.config.shadow.clone();
         let mut custom = post.custom;
         let custom_names: Vec<String> = custom.uniforms().map(|u| u.0.to_owned()).collect();
         // A first run finds the names neither the frame nor the pack defines.
@@ -1279,6 +1280,7 @@ impl PackPost {
             uniforms: {
                 let mut u = FrameUniforms::default();
                 u.atlas = world.atlas.map_or([0; 2], |a| a.1);
+                u.shadow = shadow_config;
                 u
             },
         }
@@ -1495,7 +1497,9 @@ impl PackPost {
         let Some(mut sky) = self.sky.take() else {
             return;
         };
-        let parts = sky.geometry.prepare(queue, frame);
+        let parts = sky
+            .geometry
+            .prepare(queue, frame, self.uniforms.shadow.sun_path_rotation);
         let mut groups = [None, None];
         for (i, pass) in [&mut sky.basic, &mut sky.textured].into_iter().enumerate() {
             if let Some(pass) = pass {
diff --git a/crates/horizon-client/src/gfx/pack_sky.rs b/crates/horizon-client/src/gfx/pack_sky.rs
index 694f3096f..4823da4a4 100644
--- a/crates/horizon-client/src/gfx/pack_sky.rs
+++ b/crates/horizon-client/src/gfx/pack_sky.rs
@@ -255,8 +255,10 @@ impl PackSky {
 
     /// Writes the frame's sky and returns its draws in vanilla's order: the disc, the sunset
     /// fan while the sun is near the horizon, the sun and the moon, the stars and, with the
-    /// camera low, the void.
-    pub fn prepare(&self, queue: &wgpu::Queue, frame: &super::Frame) -> Vec<Part> {
+    /// camera low, the void. `tilt` is the pack's `sunPathRotation` (degrees): the sun, moon
+    /// and stars turn with it (7.1).
+    pub fn prepare(&self, queue: &wgpu::Queue, frame: &super::Frame, tilt: f32) -> Vec<Part> {
+        let turn = super::pack_uniforms::tilt_matrix(tilt);
         let sun_angle = frame.sky.sun_angle.to_radians();
         // The fan turns to the other horizon in the afternoon (terrain.wgsl's sunrise_weight).
         let flip = if sun_angle.sin() < 0.0 { 180f32 } else { 0.0 };
@@ -264,7 +266,7 @@ impl PackSky {
         let (rotation, brightness) = frame.stars.unwrap_or_default();
         let [r, g, b] = frame.sky.sky_color;
         let uniform = Uniform {
-            stars: rotation.to_cols_array_2d(),
+            stars: (turn * rotation).to_cols_array_2d(),
             color: [r, g, b, 1.0],
             sunrise: frame.sky.sunrise_color,
             sun: [theta.cos(), theta.sin(), brightness.clamp(0.0, 1.0), 0.0],
@@ -281,7 +283,7 @@ impl PackSky {
             .clone()
             .flat_map(|q| [0, 1, 2, 0, 2, 3].map(|i| q[i]))
             .map(|v| Celestial {
-                pos: v.pos,
+                pos: turn.transform_vector3(v.pos.into()).into(),
                 uv: v.uv,
                 color: v.color,
             })
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index efa8d2e2c..d1a85a1ba 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -3,7 +3,8 @@
 //! Matrices follow GL's conventions (5.5): `gbufferProjection` maps view depth to clip z in
 //! [-w, w], and the depth buffers packs read hold GL window depth.
 
-use glam::{Mat4, Vec3, Vec4};
+use glam::{DMat4, DVec3, Mat4, Vec3, Vec4};
+use horizon_shaders::Shadow;
 
 use super::Frame;
 
@@ -172,6 +173,8 @@ pub struct FrameUniforms {
     previous: Option<(Vec3, Mat4, Mat4)>,
     wetness: f32,
     eye_smooth: [f32; 2],
+    /// The pack's shadow settings (7.1).
+    pub shadow: Shadow,
 }
 
 impl Default for FrameUniforms {
@@ -185,14 +188,72 @@ impl Default for FrameUniforms {
             previous: None,
             wetness: 0.0,
             eye_smooth: [0.0; 2],
+            shadow: Shadow::default(),
         }
     }
 }
 
-/// `(0, 100, 0)` on the frame the sky draws a body on: Y -90°, then X by its angle in degrees.
-fn body(angle: f32) -> Vec3 {
-    (Mat4::from_rotation_y((-90.0f32).to_radians()) * Mat4::from_rotation_x(angle.to_radians()))
-        .transform_vector3(Vec3::new(0.0, 100.0, 0.0))
+/// `(0, 100, 0)` on the frame the sky draws a body on: Y -90°, then X by its angle in degrees;
+/// `sunPathRotation` (`tilt`, degrees) then turns the path about the world's X axis (7.1, OQ-6).
+fn body(angle: f32, tilt: f32) -> Vec3 {
+    (tilt_matrix(tilt)
+        * Mat4::from_rotation_y((-90.0f32).to_radians())
+        * Mat4::from_rotation_x(angle.to_radians()))
+    .transform_vector3(Vec3::new(0.0, 100.0, 0.0))
+}
+
+/// `sunPathRotation`'s turn of the sky's bodies: `tilt` degrees about the world's X axis, so a
+/// positive angle moves the noon sun toward +Z (south).
+pub fn tilt_matrix(tilt: f32) -> Mat4 {
+    Mat4::from_rotation_x(tilt.to_radians())
+}
+
+/// The world direction of the shadow light (7.1): the sun by day, the moon by night.
+fn shadow_light(frame: &Frame, shadow: &Shadow) -> Vec3 {
+    let sun_angle = (frame.sky.sun_angle / 360.0 + 0.25).rem_euclid(1.0);
+    let angle = if sun_angle < 0.5 {
+        frame.sky.sun_angle
+    } else {
+        frame.sky.moon_angle
+    };
+    body(angle, shadow.sun_path_rotation).normalize()
+}
+
+/// Distance from the snapped point to the shadow camera, toward the light: the middle of the
+/// default near and far planes (OQ-6).
+const SHADOW_EYE: f64 = 128.0;
+
+/// The shadow camera (7.1; OQ-6, impl-plan.md): its view (player space to shadow view space)
+/// and GL projection. The camera looks from the light, world +Z up (+Y when the light is near
+/// Z); the point it centres moves in steps of `shadowIntervalSize` along the shadow view's
+/// own axes, and it sits `SHADOW_EYE` blocks toward the light from it. Orthographic over
+/// `shadowDistance` each side, or perspective with `shadowMapFov`.
+pub fn shadow_camera(light: Vec3, camera: DVec3, shadow: &Shadow) -> (Mat4, Mat4) {
+    let light = light.as_dvec3();
+    let up = if light.z.abs() > 0.99 {
+        DVec3::Y
+    } else {
+        DVec3::Z
+    };
+    let rotation = DMat4::look_to_rh(DVec3::ZERO, -light, up);
+    let at = rotation.transform_vector3(camera);
+    let step = f64::from(shadow.interval);
+    let snapped = if step > 0.0 {
+        (at / step).floor() * step
+    } else {
+        at
+    };
+    let offset = at - snapped - DVec3::new(0.0, 0.0, SHADOW_EYE);
+    let view = (DMat4::from_translation(offset) * rotation).as_mat4();
+    let (near, far) = (shadow.near, shadow.far);
+    let projection = match shadow.fov {
+        Some(fov) => Mat4::perspective_rh_gl(fov.to_radians(), 1.0, near, far),
+        None => {
+            let d = shadow.distance;
+            Mat4::orthographic_rh_gl(-d, d, -d, d, near, far)
+        }
+    };
+    (view, projection)
 }
 
 /// `value` moved toward `target` with a half-life of `half_life` seconds over `dt` (5.6).
@@ -223,8 +284,9 @@ impl FrameUniforms {
         let to_view = |v: Vec3| view.transform_vector3(v);
         let sun_angle = (frame.sky.sun_angle / 360.0 + 0.25).rem_euclid(1.0);
         let day = sun_angle < 0.5;
-        let sun = to_view(body(frame.sky.sun_angle));
-        let moon = to_view(body(frame.sky.moon_angle));
+        let tilt = self.shadow.sun_path_rotation;
+        let sun = to_view(body(frame.sky.sun_angle, tilt));
+        let moon = to_view(body(frame.sky.moon_angle, tilt));
         // Half-lives are given in ticks (7.2); smoothing runs per frame in seconds (OQ-26).
         let half_life = if inputs.rain > self.wetness {
             600.0
@@ -250,14 +312,8 @@ impl FrameUniforms {
             }
             None => (frame.sky.fog_color, frame.distance * 0.9, frame.distance),
         };
-        // The shadow camera (OQ-6, impl-plan.md): orthographic, `shadowDistance` (160) blocks
-        // each side, 100 blocks from the player toward the shadow light, world +z up.
-        let light = view
-            .inverse()
-            .transform_vector3(if day { sun } else { moon })
-            .normalize();
-        let shadow_view = Mat4::look_at_rh(light * 100.0, Vec3::ZERO, Vec3::Z);
-        let shadow_projection = Mat4::orthographic_rh_gl(-160.0, 160.0, -160.0, 160.0, 0.05, 256.0);
+        let light = shadow_light(frame, &self.shadow);
+        let (shadow_view, shadow_projection) = shadow_camera(light, frame.camera, &self.shadow);
         let day_time = inputs.day_time.rem_euclid(24000) as i32;
         let world_day = inputs.day_time.div_euclid(24000);
         let seconds = (now - self.start).as_secs_f32() % 3600.0;
@@ -413,7 +469,38 @@ mod tests {
 
     #[test]
     fn noon_is_straight_up_and_the_sun_sets_in_the_west() {
-        assert!(body(0.0).abs_diff_eq(Vec3::new(0.0, 100.0, 0.0), 1e-3));
-        assert!(body(90.0).abs_diff_eq(Vec3::new(-100.0, 0.0, 0.0), 1e-3));
+        assert!(body(0.0, 0.0).abs_diff_eq(Vec3::new(0.0, 100.0, 0.0), 1e-3));
+        assert!(body(90.0, 0.0).abs_diff_eq(Vec3::new(-100.0, 0.0, 0.0), 1e-3));
+        // sunPathRotation tilts noon toward +Z and leaves sunset on the horizon.
+        assert!(body(0.0, 30.0).abs_diff_eq(Vec3::new(0.0, 86.60254, 50.0), 1e-3));
+        assert!(body(90.0, 30.0).abs_diff_eq(Vec3::new(-100.0, 0.0, 0.0), 1e-3));
+    }
+
+    #[test]
+    fn the_shadow_camera_looks_down_from_the_light_in_steps() {
+        let shadow = Shadow::default();
+        let mut camera = DVec3::new(1000.3, 70.0, -20.7);
+        // Noon: the light is straight up.
+        let (view, projection) = shadow_camera(Vec3::Y, camera, &shadow);
+        let at = |p: Vec3| view.transform_point3(p);
+        // Straight down: a block below the player is farther from the light.
+        assert!(at(Vec3::new(0.0, -1.0, 0.0)).z < at(Vec3::ZERO).z);
+        // The player is less than a step from the centre, 128 blocks from the light.
+        let centre = at(Vec3::ZERO);
+        assert!(centre.x.abs() <= 2.0 && centre.y.abs() <= 2.0, "{centre}");
+        assert!((centre.z + 128.0).abs() < 1e-3, "{centre}");
+        // Moving within a step keeps the world where it was in the map.
+        camera.x = 1000.6;
+        let (moved, _) = shadow_camera(Vec3::Y, camera, &shadow);
+        let world = Vec3::new(5.0, -3.0, 9.0);
+        let shift = Vec3::new(0.3, 0.0, 0.0);
+        assert!(
+            moved
+                .transform_point3(world - shift)
+                .abs_diff_eq(at(world), 1e-3)
+        );
+        // shadowDistance blocks reach the map's edge.
+        let edge = projection.project_point3(Vec3::new(160.0, 0.0, -128.0));
+        assert!((edge.x.abs() - 1.0).abs() < 1e-4, "{edge}");
     }
 }
diff --git a/crates/horizon-shaders/src/config.rs b/crates/horizon-shaders/src/config.rs
index 0f21e4900..042840354 100644
--- a/crates/horizon-shaders/src/config.rs
+++ b/crates/horizon-shaders/src/config.rs
@@ -118,9 +118,55 @@ impl Default for Buffer {
     }
 }
 
+/// The shadow map's settings (6.3, 7.1), from `const` lines of the stage files.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Shadow {
+    /// `shadowMapResolution`: the map's side in pixels.
+    pub resolution: u32,
+    /// `shadowDistance`: half the side of the area the map covers, in blocks.
+    pub distance: f32,
+    /// `shadowDistanceRenderMul`: when > 0, geometry beyond `distance × mul` is not drawn.
+    pub render_mul: f32,
+    /// `shadowIntervalSize`: the shadow camera moves in steps of this many blocks (0: none).
+    pub interval: f32,
+    /// `sunPathRotation`, degrees.
+    pub sun_path_rotation: f32,
+    /// `shadowMapFov`: a perspective projection of this many degrees instead of orthographic.
+    pub fov: Option<f32>,
+    /// `shadowNearPlane`, `shadowFarPlane`.
+    pub near: f32,
+    pub far: f32,
+    /// `shadowHardwareFiltering(0|1)`: shadowtex0/1 sampled with depth comparison.
+    pub hardware_filtering: [bool; 2],
+    /// `shadowcolor0/1`: format, cleared every frame, clear colour (default white).
+    pub colors: [Buffer; 2],
+}
+
+impl Default for Shadow {
+    fn default() -> Self {
+        let white = Buffer {
+            clear_color: Some([1.0; 4]),
+            ..Buffer::default()
+        };
+        Self {
+            resolution: 1024,
+            distance: 160.0,
+            render_mul: -1.0,
+            interval: 2.0,
+            sun_path_rotation: 0.0,
+            fov: None,
+            near: 0.05,
+            far: 256.0,
+            hardware_filtering: [false; 2],
+            colors: [white.clone(), white],
+        }
+    }
+}
+
 #[derive(Clone, Debug, PartialEq)]
 pub struct Config {
     pub buffers: [Buffer; BUFFERS],
+    pub shadow: Shadow,
     /// Conflicting or unreadable settings, as `file:line: message`.
     pub notes: Vec<String>,
     format_set: [bool; BUFFERS],
@@ -133,6 +179,7 @@ impl Default for Config {
     fn default() -> Self {
         Self {
             buffers: std::array::from_fn(|_| Buffer::default()),
+            shadow: Shadow::default(),
             notes: Vec::new(),
             format_set: [false; BUFFERS],
             seen: Vec::new(),
@@ -197,6 +244,9 @@ impl Config {
     }
 
     fn constant(&mut self, place: &str, ty: &str, name: &str, value: &str) {
+        if self.shadow_constant(ty, name, value) {
+            return;
+        }
         let settings = [
             ("Format", "int"),
             ("ClearColor", "vec4"),
@@ -243,6 +293,70 @@ impl Config {
     }
 }
 
+impl Config {
+    /// A shadow setting of 6.3 or 7.1; true when `name` is one (read or not).
+    fn shadow_constant(&mut self, ty: &str, name: &str, value: &str) -> bool {
+        let s = &mut self.shadow;
+        let float = |v: &mut f32| {
+            if let Some(n) = number(value) {
+                *v = n;
+            }
+        };
+        match name {
+            "shadowMapResolution" => {
+                if let Some(n) = number(value).filter(|n| *n >= 1.0) {
+                    s.resolution = (n as u32).min(16384);
+                }
+            }
+            "shadowDistance" => float(&mut s.distance),
+            "shadowDistanceRenderMul" => float(&mut s.render_mul),
+            "shadowIntervalSize" => float(&mut s.interval),
+            "sunPathRotation" => float(&mut s.sun_path_rotation),
+            "shadowNearPlane" => float(&mut s.near),
+            "shadowFarPlane" => float(&mut s.far),
+            "shadowMapFov" => s.fov = number(value).filter(|f| *f > 0.0),
+            "shadowHardwareFiltering" => {
+                if let Some(b) = boolean(value) {
+                    s.hardware_filtering = [b; 2];
+                }
+            }
+            "shadowHardwareFiltering0" | "shadowHardwareFiltering1" => {
+                if let Some(b) = boolean(value) {
+                    s.hardware_filtering[usize::from(name.ends_with('1'))] = b;
+                }
+            }
+            _ => {
+                let color = ["shadowcolor0", "shadowcolor1", "shadowcolor"]
+                    .iter()
+                    .find_map(|b| Some((b, name.strip_prefix(b)?)));
+                let Some((buffer, setting)) = color else {
+                    return false;
+                };
+                let b = &mut s.colors[usize::from(buffer.ends_with('1'))];
+                match (setting, ty) {
+                    ("Format", "int") => {
+                        if let Some(f) = Format::parse(value) {
+                            b.format = f;
+                        }
+                    }
+                    ("Clear", "bool") => {
+                        if let Some(v) = boolean(value) {
+                            b.clear = v;
+                        }
+                    }
+                    ("ClearColor", "vec4") => {
+                        if let Some(c) = vec4(value) {
+                            b.clear_color = Some(c);
+                        }
+                    }
+                    _ => return false,
+                }
+            }
+        }
+        true
+    }
+}
+
 /// The buffers a fragment shader writes, from the last `DRAWBUFFERS` or `RENDERTARGETS` comment
 /// of its live code, or `None` without one (then it writes buffers 0 to 7). 6.1.4.
 pub fn draw_buffers(pp: &Preprocessed) -> Option<Vec<u32>> {
@@ -402,6 +516,28 @@ mod tests {
         assert!(config.notes.is_empty(), "{:?}", config.notes);
     }
 
+    #[test]
+    fn shadow_settings() {
+        let mut c = Config::default();
+        c.read(&stage(
+            "const int shadowMapResolution = 2048;\nconst float shadowDistance = 128.0f;\n\
+             const float sunPathRotation = -40.0;\nconst bool shadowHardwareFiltering = true;\n\
+             /* const int shadowcolor1Format = RGBA16F; */\nconst bool shadowcolor0Clear = false;\n",
+        ));
+        let s = c.finish().shadow;
+        assert_eq!(
+            (s.resolution, s.distance, s.sun_path_rotation),
+            (2048, 128.0, -40.0)
+        );
+        assert_eq!(
+            (s.interval, s.fov, s.hardware_filtering),
+            (2.0, None, [true; 2])
+        );
+        assert!(!s.colors[0].clear && s.colors[1].clear);
+        assert_eq!(s.colors[1].format, Format::parse("RGBA16F").unwrap());
+        assert_eq!(s.colors[1].clear_color, Some([1.0; 4]));
+    }
+
     #[test]
     fn no_directive_and_conflicts() {
         let pp = stage("void main() {}\n");
diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index 426ee5b35..9411f506c 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -30,7 +30,7 @@ mod translate;
 pub use biomes::{category as biome_category, precipitation as biome_precipitation};
 pub use block_ids::BlockIds;
 pub use condition::eval_condition;
-pub use config::{BUFFERS, Buffer, Config, Format, Kind, buffer_index, draw_buffers};
+pub use config::{BUFFERS, Buffer, Config, Format, Kind, Shadow, buffer_index, draw_buffers};
 pub use custom::{Custom, Val};
 pub use discover::{Found, discover};
 pub use lang::Lang;

From 86d8d9e3a19a0c6614b6b4fec537007d33759254 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:06:22 +0100
Subject: [PATCH 121/270] Shader packs, clean room 38: load the shadow programs

The shadow pass runs when some program reads a shadow buffer (shadow,
watershadow, shadowtex0/1, their HW forms, shadowcolor, shadowcolor0/1) or
shadow.enabled=true; shadow.enabled=false keeps it off (spec 2.5). Then
`shadow` (solid and cutout terrain), `shadow_water` falling back to
`shadow` (translucent terrain) and shadowcomp..shadowcomp99 load, in the
new Shadow and ShadowComp groups (2.1, 2.4). shadow_solid and shadow_cutout
are not used: the game's solid and cutout terrain is one draw.

Their output n writes shadowcolor n (6.3): draw buffer lists stop at the
first index past 1. translate_shadow gives a shadow program the shadow
camera's matrices as its model-view and projection (5.2). The game does not
draw any of them yet.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
sections 2.1, 2.4, 2.5, 5.2 and 6.3; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-shaders/src/lib.rs           |   4 +-
 crates/horizon-shaders/src/post.rs          | 180 +++++++++++++++++++-
 crates/horizon-shaders/src/translate/mod.rs |  45 ++++-
 crates/horizon-shaders/tests/real_packs.rs  |   6 +-
 4 files changed, 223 insertions(+), 12 deletions(-)

diff --git a/crates/horizon-shaders/src/lib.rs b/crates/horizon-shaders/src/lib.rs
index 9411f506c..4aa481e81 100644
--- a/crates/horizon-shaders/src/lib.rs
+++ b/crates/horizon-shaders/src/lib.rs
@@ -7,7 +7,7 @@
 //! - [`Properties`]: `shaders.properties` and the id files, with their conditional directives (3.1, 1.5).
 //! - [`Lang`]: the pack's translated names (8.4).
 //! - [`preprocess`]: a stage file through `#include` and the GLSL preprocessor, lines mapped back (1.4, 1.5).
-//! - [`translate_composite`], [`translate_gbuffers`]: a program into naga modules and its interface (1.6, 2.2).
+//! - [`translate_composite`], [`translate_gbuffers`], [`translate_shadow`]: a program into naga modules and its interface (1.6, 2.2).
 //! - [`Config`] and [`draw_buffers`]: the buffer settings and output lists stage files carry (1.7, 6.1).
 //! - [`load_post`]: a dimension's `prepare`, `deferred`, `composite` and `final` programs, in order (2.1).
 //! - [`Macros`] and [`eval_condition`]: the macros packs test, and the `#if` arithmetic (1.5).
@@ -45,5 +45,5 @@ pub use preprocess::{Diagnostic, Origin, Preprocessed, preprocess};
 pub use properties::{Entry, Note, Properties};
 pub use translate::{
     AlphaTest, DRAW_UNIFORMS, Error, GbuffersInputs, Interface, Program, Sampler, Target, Uniform,
-    translate_composite, translate_gbuffers,
+    translate_composite, translate_gbuffers, translate_shadow,
 };
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 9beb7f06a..95b8c3663 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -15,7 +15,9 @@ use std::collections::BTreeSet;
 use crate::config::{self, Config};
 use crate::custom::Custom;
 use crate::{GbuffersInputs, Macros, Pack, Preprocessed, Program, Properties, Target};
-use crate::{eval_condition, preprocess, translate_composite, translate_gbuffers};
+use crate::{
+    eval_condition, preprocess, translate_composite, translate_gbuffers, translate_shadow,
+};
 
 /// Which group of 2.1 a program belongs to.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -28,8 +30,32 @@ pub enum Group {
     Gbuffers,
     /// A gbuffers program drawing translucent geometry, after deferred (2.1).
     Translucent,
+    /// A shadow program: the game's geometry from the shadow light, into the shadow buffers.
+    Shadow,
+    /// `shadowcomp`..`shadowcomp99`: composite-style programs over the shadow buffers.
+    ShadowComp,
 }
 
+impl Group {
+    /// Whether the group writes the shadow buffers, where buffer n is shadowcolor n.
+    pub fn shadow(self) -> bool {
+        matches!(self, Group::Shadow | Group::ShadowComp)
+    }
+}
+
+/// The samplers whose use turns the shadow pass on (2.5, 6.3).
+const SHADOW_SAMPLERS: [&str; 9] = [
+    "shadow",
+    "watershadow",
+    "shadowtex0",
+    "shadowtex1",
+    "shadowtex0HW",
+    "shadowtex1HW",
+    "shadowcolor",
+    "shadowcolor0",
+    "shadowcolor1",
+];
+
 /// A blend factor of `blend.<program>` (3.2), as GL names it.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Factor {
@@ -216,6 +242,14 @@ pub struct Post {
     pub weather: Option<PostProgram>,
     /// What draws the first-person hand and held items.
     pub hand: Option<PostProgram>,
+    /// Some program reads a shadow buffer, or `shadow.enabled=true`: the shadow pass runs (2.5).
+    pub shadow_pass: bool,
+    /// When it runs: what draws solid and cutout terrain from the light (`shadow`), and
+    /// translucent terrain (`shadow_water` or `shadow`), into the shadow buffers (2.4).
+    pub shadow: Option<PostProgram>,
+    pub shadow_water: Option<PostProgram>,
+    /// `shadowcomp`..`shadowcomp99`, after the shadow pass (2.1).
+    pub shadow_comp: Vec<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
     pub translucent_late: bool,
     /// Particles draw after deferred (`particles.ordering`, `particles.before.deferred`, 3.2).
@@ -280,6 +314,10 @@ pub fn load_post(
         clouds: None,
         weather: None,
         hand: None,
+        shadow_pass: false,
+        shadow: None,
+        shadow_water: None,
+        shadow_comp: Vec::new(),
         translucent_late: false,
         particles_late: false,
         custom: Custom::parse(properties),
@@ -434,10 +472,77 @@ pub fn load_post(
         Some(_) => true,
         None => !flag("particles.before.deferred").unwrap_or(false),
     };
+    load_shadow(&mut loader, inputs.terrain.as_ref());
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
 
+/// Whether the shadow pass runs (2.5) and, when it does, its programs: `shadow_solid` and
+/// `shadow_cutout` are not used (2.4, Legacy); the game's solid and cutout terrain is one draw.
+fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
+    let post = &*loader.post;
+    let gbuffers = [
+        &post.terrain,
+        &post.water,
+        &post.sky,
+        &post.sky_textured,
+        &post.entities,
+        &post.block,
+        &post.entities_translucent,
+        &post.particles,
+        &post.clouds,
+        &post.weather,
+        &post.hand,
+    ];
+    let reads = (post.programs.iter())
+        .chain(gbuffers.into_iter().flatten())
+        .flat_map(|p| &p.program.interface.samplers)
+        .any(|s| SHADOW_SAMPLERS.contains(&s.name.as_str()));
+    let forced = match loader.properties.get("shadow.enabled").map(str::trim) {
+        Some("true") => Some(true),
+        Some("false") => Some(false),
+        _ => None,
+    };
+    let on = forced.unwrap_or(reads);
+    loader.post.shadow_pass = on;
+    if !on {
+        return;
+    }
+    let names =
+        std::iter::once("shadowcomp".to_owned()).chain((1..=99).map(|n| format!("shadowcomp{n}")));
+    for name in names {
+        let program = loader.load(name, Group::ShadowComp, |v, f| {
+            translate_composite(v, f, Target::Buffers)
+        });
+        loader.post.shadow_comp.extend(program);
+    }
+    let Some(inputs) = terrain else {
+        return;
+    };
+    let properties = loader.properties;
+    let mut load = |names: &[&str]| {
+        names.iter().find_map(|name| {
+            let p = loader.load(name.to_string(), Group::Shadow, |v, f| {
+                translate_shadow(v, f, inputs)
+            });
+            p.map(|mut p| {
+                p.blend = blend(properties, &p.name).flatten();
+                p
+            })
+        })
+    };
+    let shadow = load(&["shadow"]);
+    let water = load(&["shadow_water", "shadow"]);
+    if shadow.is_none() {
+        loader
+            .post
+            .notes
+            .push("shadow: no program; the shadow map stays clear".to_owned());
+    }
+    loader.post.shadow = shadow;
+    loader.post.shadow_water = water;
+}
+
 struct Loader<'a> {
     pack: &'a Pack,
     folder: &'a str,
@@ -505,9 +610,17 @@ impl Loader<'_> {
         };
         self.post.config.read(&vertex);
         self.post.config.read(&fragment);
-        let buffers = config::draw_buffers(&fragment).unwrap_or_else(|| (0..8).collect());
+        let mut buffers = config::draw_buffers(&fragment).unwrap_or_else(|| (0..8).collect());
+        if group.shadow() {
+            // Output n writes shadowcolor n (6.3); there are two.
+            let kept = buffers
+                .iter()
+                .position(|&b| b >= 2)
+                .unwrap_or(buffers.len());
+            buffers.truncate(kept);
+        }
         let mipmaps = match group {
-            Group::Gbuffers | Group::Translucent => 0,
+            Group::Gbuffers | Group::Translucent | Group::Shadow | Group::ShadowComp => 0,
             _ => {
                 let mut own = Config::default();
                 own.read(&fragment);
@@ -696,6 +809,67 @@ mod tests {
         assert!(post.programs.iter().any(|p| p.name == "composite3"));
     }
 
+    /// The shadow pass runs when a program reads a shadow buffer or `shadow.enabled` says so;
+    /// then `shadow`, `shadow_water` and the `shadowcomp` series load, writing shadowcolor0/1.
+    #[test]
+    fn shadow_programs_load_when_a_shadow_buffer_is_read() {
+        let reads = "#version 120\nuniform sampler2D shadowtex0;\nvarying vec2 uv;\n\
+                     void main() { gl_FragColor = texture2D(shadowtex0, uv); }\n";
+        let shadow = "#version 120\nvarying vec2 uv;\nvoid main() {\n/* RENDERTARGETS: 1,0,4 */\n\
+                      gl_FragData[0] = vec4(1.0); gl_FragData[1] = vec4(0.5); gl_FragData[2] = vec4(0.0);\n}\n";
+        let files = [
+            ("shaders/composite.vsh", VSH),
+            ("shaders/composite.fsh", reads),
+            ("shaders/shadow.vsh", VSH),
+            ("shaders/shadow.fsh", shadow),
+            ("shaders/shadowcomp1.vsh", VSH),
+            ("shaders/shadowcomp1.fsh", FSH),
+        ];
+        let pack = Pack::from_zip_bytes("t", zip(&files)).unwrap();
+        let inputs = GameInputs {
+            terrain: Some(crate::GbuffersInputs {
+                declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
+                body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n".into(),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+        let load = |properties: &str| {
+            let properties = Properties::parse(properties, &Macros::default());
+            load_post(&pack, "", &properties, &Macros::standard(), &inputs)
+        };
+        let post = load("");
+        assert!(post.shadow_pass);
+        let shadow = post.shadow.as_ref().expect("shadow");
+        assert_eq!(
+            (shadow.group, &shadow.buffers[..]),
+            (Group::Shadow, &[1, 0][..])
+        );
+        // shadow_water falls back to shadow.
+        assert_eq!(
+            post.shadow_water.as_ref().map(|p| p.name.as_str()),
+            Some("shadow")
+        );
+        let comp: Vec<_> = post
+            .shadow_comp
+            .iter()
+            .map(|p| (p.name.as_str(), p.group))
+            .collect();
+        assert_eq!(comp, [("shadowcomp1", Group::ShadowComp)]);
+        // DRAWBUFFERS:3 names no shadowcolor buffer.
+        assert!(post.shadow_comp[0].buffers.is_empty());
+        let post = load("shadow.enabled = false");
+        assert!(!post.shadow_pass && post.shadow.is_none() && post.shadow_comp.is_empty());
+        // Nothing reads a shadow buffer.
+        let pack = Pack::from_zip_bytes("t", zip(&files[2..])).unwrap();
+        let none = |properties: &str| {
+            let properties = Properties::parse(properties, &Macros::default());
+            load_post(&pack, "", &properties, &Macros::standard(), &inputs)
+        };
+        assert!(!none("").shadow_pass);
+        assert!(none("shadow.enabled=true").shadow.is_some());
+    }
+
     /// Water falls back to the terrain chain and blends by default, as the sky does; entities
     /// and block entities fall back along theirs; `blend.*` overrides.
     #[test]
diff --git a/crates/horizon-shaders/src/translate/mod.rs b/crates/horizon-shaders/src/translate/mod.rs
index 2f0163f94..6d2ae46c6 100644
--- a/crates/horizon-shaders/src/translate/mod.rs
+++ b/crates/horizon-shaders/src/translate/mod.rs
@@ -154,7 +154,7 @@ pub fn translate_composite(
     fragment: &Preprocessed,
     target: Target,
 ) -> Result<Program, Vec<Error>> {
-    translate(vertex, fragment, target, None)
+    translate(vertex, fragment, target, None, false)
 }
 
 /// Translates a gbuffers-style program (`gbuffers_terrain`...) drawing the game's geometry
@@ -165,7 +165,18 @@ pub fn translate_gbuffers(
     target: Target,
     inputs: &GbuffersInputs,
 ) -> Result<Program, Vec<Error>> {
-    translate(vertex, fragment, target, Some(inputs))
+    translate(vertex, fragment, target, Some(inputs), false)
+}
+
+/// Translates a shadow program (`shadow`, `shadow_water`...) drawing the game's geometry
+/// described by `inputs` from the shadow light: its model-view and projection matrices are the
+/// shadow camera's (5.2).
+pub fn translate_shadow(
+    vertex: &Preprocessed,
+    fragment: &Preprocessed,
+    inputs: &GbuffersInputs,
+) -> Result<Program, Vec<Error>> {
+    translate(vertex, fragment, Target::Buffers, Some(inputs), true)
 }
 
 /// The matrices of the compatibility profile in a gbuffers-style program, from the frame's.
@@ -183,7 +194,13 @@ fn translate(
     fragment: &Preprocessed,
     target: Target,
     gbuffers: Option<&GbuffersInputs>,
+    shadow: bool,
 ) -> Result<Program, Vec<Error>> {
+    let matrices = if shadow {
+        GBUFFERS_MATRICES.replace("gbuffer", "shadow")
+    } else {
+        GBUFFERS_MATRICES.to_owned()
+    };
     let mut v = Stage::scan(vertex, ShaderStage::Vertex);
     let mut f = Stage::scan(fragment, ShaderStage::Fragment);
     v.gbuffers = gbuffers.is_some();
@@ -200,6 +217,9 @@ fn translate(
             "gbufferProjectionInverse",
         ] {
             uniforms.insert(name.to_owned(), "mat4".to_owned());
+            if shadow {
+                uniforms.insert(name.replace("gbuffer", "shadow"), "mat4".to_owned());
+            }
         }
     }
     let mut samplers: BTreeMap<String, String> = BTreeMap::new();
@@ -327,7 +347,7 @@ fn translate(
              hz_MultiTexCoord0 = hz_Vertex;\n    hz_Color = vec4(1.0);\n    hz_Normal = vec3(0.0, 0.0, 1.0);\n",
         ),
         Some(inputs) => {
-            vertex_main.push_str(GBUFFERS_MATRICES);
+            vertex_main.push_str(&matrices);
             vertex_main.push_str(&inputs.body);
         }
     }
@@ -361,7 +381,7 @@ fn translate(
     .unwrap();
     let mut fragment_main = String::from("\nvoid main() {\n");
     if gbuffers.is_some() {
-        fragment_main.push_str(GBUFFERS_MATRICES);
+        fragment_main.push_str(&matrices);
     }
     fragment_main.push_str(fog);
     if f.frag_coord {
@@ -795,7 +815,7 @@ mod tests {
         let files: Vec<(&str, &str)> = files.iter().map(|(p, t)| (p.as_str(), *t)).collect();
         let pack = Pack::from_zip_bytes("P.zip", zip(&files)).unwrap();
         let m = Macros::standard();
-        let inputs = GbuffersInputs {
+        let game = GbuffersInputs {
             declarations: "layout(location = 0) in vec3 game_pos;\nlayout(location = 1) in uvec2 game_uv;".into(),
             body: "    hz_Vertex = vec4(game_pos, 1.0);\n    hz_MultiTexCoord0 = vec4(vec2(game_uv) / 32768.0, 0.0, 1.0);\n    \
                    hz_MultiTexCoord1 = vec4(240.0, 240.0, 0.0, 1.0);\n    hz_Color = vec4(1.0);\n    hz_Normal = vec3(0.0, 1.0, 0.0);\n"
@@ -807,7 +827,7 @@ mod tests {
             &preprocess(&pack, "gbuffers_terrain.vsh", &m),
             &preprocess(&pack, "gbuffers_terrain.fsh", &m),
             Target::Buffers,
-            &inputs,
+            &game,
         )
         .unwrap_or_else(|e| panic!("{e:?}"));
         let names: Vec<&str> = p
@@ -842,6 +862,19 @@ mod tests {
             inputs.contains(&"game_pos") && inputs.contains(&"game_uv"),
             "{inputs:?}"
         );
+        // From the light, the compatibility matrices are the shadow camera's.
+        let shadow = translate_shadow(
+            &preprocess(&pack, "gbuffers_terrain.vsh", &m),
+            &preprocess(&pack, "gbuffers_terrain.fsh", &m),
+            &game,
+        )
+        .unwrap_or_else(|e| panic!("{e:?}"));
+        let names: Vec<&str> = (shadow.interface.uniforms.iter())
+            .map(|u| u.name.as_str())
+            .collect();
+        for name in ["shadowModelView", "shadowProjection", "gbufferModelView"] {
+            assert!(names.contains(&name), "{name} missing from {names:?}");
+        }
     }
 
     #[test]
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 747b732d7..70fcaa55f 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -180,8 +180,12 @@ fn real_packs_read() {
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, terrain {:?}, water {:?}, sky {:?} {:?}, entities {:?} {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, shadow pass {} ({:?}, {:?}, {} shadowcomp), terrain {:?}, water {:?}, sky {:?} {:?}, entities {:?} {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
+                post.shadow_pass,
+                post.shadow.as_ref().map(|t| &t.name),
+                post.shadow_water.as_ref().map(|t| &t.name),
+                post.shadow_comp.len(),
                 post.terrain.as_ref().map(|t| &t.name),
                 post.water.as_ref().map(|t| &t.name),
                 post.sky.as_ref().map(|t| &t.name),

From 632071849134f15723faba98d8fb76d155faa1ce Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:25:47 +0100
Subject: [PATCH 122/270] Shader packs, clean room 39: shadow buffers, their
 samplers and shadowcomp

When the shadow pass runs, the pack gets real shadow buffers (spec 6.3):
shadowtex0 (cleared to 1.0 every frame), shadowtex1 (a copy, made only when
a program reads it) and shadowcolor0/1 (each with two sides, made only when
used, cleared to their ShadowClear colour, white by default), square at
shadowMapResolution within the device's limit.

Samplers: shadowtex0/watershadow, shadowtex1, `shadow` (shadowtex1 beside
watershadow) and the HW forms read the shadow map, through a linear depth
comparison when declared sampler2DShadow; shadowcolor/shadowcolor0/1 read
the colour buffers. In the shadow programs, buffer n is shadowcolor n and
colortex reads a stand-in. Without the shadow pass nothing changes: the
names read the stand-ins as before.

shadowcomp..shadowcomp99 run after the shadow pass and before prepare, each
drawing into the alt side of the shadowcolor buffers it writes and flipping
them after, as composite programs do with colortex (6.1.6). The shadow pass
itself draws nothing yet, so the map stays clear.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1,
sections 2.1, 5.2 (samplers), 6.1.6 and 6.3; no other loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs             |   1 +
 crates/horizon-client/src/gfx/pack_post.rs   | 276 +++++++++++++++++--
 crates/horizon-client/src/gfx/pack_shadow.rs | 150 ++++++++++
 3 files changed, 397 insertions(+), 30 deletions(-)
 create mode 100644 crates/horizon-client/src/gfx/pack_shadow.rs

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index df6bc33a5..bba07c647 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -73,6 +73,7 @@ pub mod pack_draw;
 mod pack_entities;
 mod pack_hand;
 mod pack_post;
+mod pack_shadow;
 mod pack_sky;
 mod pack_timing;
 pub mod pack_uniforms;
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 2be557c17..f17765a0f 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -37,6 +37,10 @@ enum Source {
     /// The block atlas (pack_atlas.rs), in gbuffers programs.
     Atlas,
     Lightmap,
+    /// `shadowtex0`/`shadowtex1` (6.3), with depth comparison (`sampler2DShadow`) or not.
+    ShadowDepth(usize, bool),
+    /// `shadowcolor0/1` read outside the shadow programs (in them they are `Color`).
+    ShadowColor(usize),
 }
 
 #[derive(Clone)]
@@ -63,13 +67,17 @@ enum SamplerKind {
 impl SamplerKind {
     fn of(source: Source, filtering: bool) -> Self {
         match source {
-            Source::Color(_) | Source::Dummy if !filtering => Self::Nearest,
-            Source::Depth | Source::Depth1 => Self::Nearest,
+            Source::Color(_) | Source::ShadowColor(_) | Source::Dummy if !filtering => {
+                Self::Nearest
+            }
+            Source::Depth | Source::Depth1 | Source::ShadowDepth(_, false) => Self::Nearest,
             Source::Noise => Self::Repeat,
-            Source::Shadow => Self::Comparison,
+            Source::Shadow | Source::ShadowDepth(_, true) => Self::Comparison,
             // Blocks look as the game draws them: nearest texels.
             Source::Atlas => Self::NearestRepeat,
-            Source::Color(_) | Source::Dummy | Source::Lightmap => Self::Linear,
+            Source::Color(_) | Source::ShadowColor(_) | Source::Dummy | Source::Lightmap => {
+                Self::Linear
+            }
         }
     }
 
@@ -158,6 +166,8 @@ struct Pass {
     flip: u16,
     /// Buffers sampled, for the bind group cache key.
     reads: u16,
+    /// shadowcolor buffers sampled by a program of the other buffers.
+    shadow_reads: u16,
     /// Buffers written.
     written: u16,
     /// Buffers whose mip chain is regenerated right before it (6.1.7).
@@ -168,9 +178,9 @@ struct Pass {
     atlas: Option<wgpu::TextureView>,
     /// Reads `mc_Entity`'s table (`PackPost::block_ids`).
     ids: bool,
-    /// Bind groups by the sides read (low 16 bits) and the buffers whose mip chain is current
-    /// (high 16 bits).
-    groups: HashMap<u32, wgpu::BindGroup>,
+    /// Bind groups by the sides read (bits 0–15), the buffers whose mip chain is current (bits
+    /// 16–31) and the shadowcolor sides read (bits 32–33).
+    groups: HashMap<u64, wgpu::BindGroup>,
 }
 
 /// One side of a buffer with mipmaps.
@@ -258,6 +268,9 @@ pub struct PackPost {
     hand: Option<(Pass, super::pack_hand::PackHand)>,
     /// A program after translucent terrain reads `depthtex1`: it is copied before water.
     depth1: bool,
+    /// The shadow buffers, when the shadow pass runs (2.5), and the `shadowcomp` programs.
+    shadow_targets: Option<super::pack_shadow::ShadowTargets>,
+    shadow_comp: Vec<Pass>,
     /// Buffers with mipmaps (filterable ones a program asks them for).
     mipped: u16,
     /// Buffers whose mip chain matches their first level, this frame.
@@ -342,7 +355,37 @@ fn texture_format(f: Format, features: wgpu::Features) -> wgpu::TextureFormat {
     }
 }
 
-fn source(name: &str) -> Source {
+/// The texture behind sampler `name` in a program of the shadow buffers (`shadow_space`: buffer
+/// n is shadowcolor n) or of the others, when the shadow pass runs (`shadow_pass`). `shadow` is
+/// `shadowtex1` when the program also declares `watershadow` (6.3).
+fn source(name: &str, shadow_space: bool, shadow_pass: bool, watershadow: bool) -> Source {
+    let shadow_color = match name {
+        "shadowcolor" | "shadowcolor0" => Some(0),
+        "shadowcolor1" => Some(1),
+        _ => None,
+    };
+    let shadow_depth = match name {
+        "shadowtex0" | "watershadow" | "shadowtex0HW" => Some(0),
+        "shadowtex1" | "shadowtex1HW" => Some(1),
+        "shadow" => Some(usize::from(watershadow)),
+        _ => None,
+    };
+    if shadow_pass {
+        if let Some(n) = shadow_depth {
+            return Source::ShadowDepth(n, name.ends_with("HW"));
+        }
+        if let Some(n) = shadow_color {
+            return if shadow_space {
+                Source::Color(n)
+            } else {
+                Source::ShadowColor(n)
+            };
+        }
+    }
+    if shadow_space && horizon_shaders::buffer_index(name).is_some() {
+        // colortex buffers are not this pass's.
+        return Source::Dummy;
+    }
     match name {
         "depthtex0" | "gdepthtex" => Source::Depth,
         // The hand is drawn after the pack, so `depthtex2` (without it) is `depthtex1`.
@@ -606,11 +649,15 @@ pub(super) struct Geometry<'a> {
 }
 
 /// The pass of program `p`: a quad, or `geometry` drawn by the game. `None` (with a note) when
-/// wgpu refuses it or it writes nothing.
+/// wgpu refuses it or it writes nothing. `formats` are its buffers' (for a program of the shadow
+/// buffers, buffer n is shadowcolor n); `shadow` the shadowcolor formats when the shadow pass
+/// runs.
+#[allow(clippy::too_many_arguments)]
 fn build_pass(
     device: &wgpu::Device,
     p: horizon_shaders::PostProgram,
     formats: &[wgpu::TextureFormat; BUFFERS],
+    shadow: Option<&[wgpu::TextureFormat; 2]>,
     screen: wgpu::TextureFormat,
     notes: &mut Vec<String>,
     geometry: Option<&Geometry<'_>>,
@@ -639,6 +686,8 @@ fn build_pass(
     let mut samplers = Vec::new();
     let (mut kinds, mut slots) = (HashMap::new(), HashMap::new());
     let mut reads = 0u16;
+    let mut shadow_reads = 0u16;
+    let watershadow = interface.samplers.iter().any(|s| s.name == "watershadow");
     // A gbuffers pass draws into its buffers and the depth buffer: reading them as well would
     // be a feedback loop (undefined in GL, refused by wgpu), so those read a blank texture.
     let in_place = match geometry {
@@ -646,8 +695,10 @@ fn build_pass(
         None => 0,
     };
     for s in &interface.samplers {
-        let mut src = source(&s.name);
+        let mut src = source(&s.name, p.group.shadow(), shadow.is_some(), watershadow);
         let blank = match src {
+            // The shadow pass writes the shadow map.
+            Source::ShadowDepth(..) => p.group == Group::Shadow,
             Source::Atlas => geometry.is_none(),
             Source::Depth => geometry.is_some(),
             // Translucent terrain reads the copy; opaque terrain would read itself.
@@ -660,14 +711,23 @@ fn build_pass(
             Source::Color(n) => formats[n]
                 .sample_type(None, Some(features))
                 .unwrap_or(float),
-            Source::Depth | Source::Depth1 => wgpu::TextureSampleType::Float { filterable: false },
+            Source::ShadowColor(n) => shadow
+                .and_then(|f| f[n].sample_type(None, Some(features)))
+                .unwrap_or(float),
+            Source::Depth | Source::Depth1 | Source::ShadowDepth(..) => {
+                wgpu::TextureSampleType::Float { filterable: false }
+            }
             // Unfilterable on WebGPU-level devices; the lightmap is sampled at texel centres.
             Source::Lightmap => float,
             _ => float,
         };
         let int = !matches!(sample_type, wgpu::TextureSampleType::Float { .. });
         if s.ty == "sampler2DShadow" {
-            (src, sample_type) = (Source::Shadow, wgpu::TextureSampleType::Depth);
+            src = match src {
+                Source::ShadowDepth(n, _) => Source::ShadowDepth(n, true),
+                _ => Source::Shadow,
+            };
+            sample_type = wgpu::TextureSampleType::Depth;
         }
         let wanted = match s.ty.as_str() {
             "sampler2DShadow" => true,
@@ -683,7 +743,9 @@ fn build_pass(
             ));
             (src, sample_type) = (Source::Dummy, float);
         }
-        if blank {
+        if blank && sample_type == wgpu::TextureSampleType::Depth {
+            src = Source::Shadow;
+        } else if blank {
             // The blank texture is float: an integer sampler then fails the pipeline (a note).
             src = Source::Dummy;
             if int {
@@ -691,8 +753,10 @@ fn build_pass(
             }
         }
         let filtering = sample_type == float;
-        if let Source::Color(n) = src {
-            reads |= 1 << n;
+        match src {
+            Source::Color(n) => reads |= 1 << n,
+            Source::ShadowColor(n) => shadow_reads |= 1 << n,
+            _ => {}
         }
         entries.push(texture_entry(s.binding, sample_type));
         let kind = SamplerKind::of(src, filtering);
@@ -849,6 +913,7 @@ fn build_pass(
         writes,
         flip,
         reads,
+        shadow_reads,
         written,
         mipmaps: p.mipmaps,
         draw,
@@ -892,18 +957,32 @@ impl PackPost {
             |flips: &[(u32, bool)]| flips.iter().filter(|f| f.1).fold(0u16, |m, f| m | 1 << f.0);
         let mut used = 1u16;
         let draws = DrawUniforms::new(device);
+        // The shadow buffers' formats when the shadow pass runs; their programs see them as
+        // buffers 0 and 1.
+        let shadow_formats: Option<[wgpu::TextureFormat; 2]> = post.shadow_pass.then(|| {
+            std::array::from_fn(|n| texture_format(shadow_config.colors[n].format, features))
+        });
+        let shadow_space: [wgpu::TextureFormat; BUFFERS] = std::array::from_fn(|i| {
+            shadow_formats
+                .filter(|_| i < 2)
+                .map_or(formats[i], |f| f[i])
+        });
         let mut build = |p: horizon_shaders::PostProgram, geometry: Option<&Geometry<'_>>| {
+            let in_shadow = p.group.shadow();
             let pass = build_pass(
                 device,
                 p,
-                &formats,
+                if in_shadow { &shadow_space } else { &formats },
+                shadow_formats.as_ref(),
                 screen,
                 &mut notes,
                 geometry,
                 &custom_names,
                 &draws.layout,
             )?;
-            used |= pass.reads | pass.written | pass.flip;
+            if !in_shadow {
+                used |= pass.reads | pass.written | pass.flip;
+            }
             Some(pass)
         };
         // Flat terrain reads `mc_Entity` from a table of the sprite layers.
@@ -1036,6 +1115,12 @@ impl PackPost {
             .filter(|p| !skip.split(',').any(|s| s == p.name))
             .filter_map(|p| build(p, None))
             .collect();
+        let shadow_comp: Vec<Pass> = post
+            .shadow_comp
+            .into_iter()
+            .filter(|p| !skip.split(',').any(|s| s == p.name))
+            .filter_map(|p| build(p, None))
+            .collect();
         if let Some(t) = &terrain {
             notes.push(format!("terrain draws with {}", t.name));
         }
@@ -1077,6 +1162,39 @@ impl PackPost {
                 .chain(&water)
                 .chain(weather.iter().take(1).flatten())
                 .any(|p| p.samplers.iter().any(|s| s.source == Source::Depth1));
+        let every_pass = || {
+            (passes
+                .iter()
+                .chain(&shadow_comp)
+                .chain(&terrain)
+                .chain(&water))
+            .chain(sky.iter().flat_map(|s| s.basic.iter().chain(&s.textured)))
+            .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
+            .chain(&clouds)
+            .chain(weather.iter().flatten())
+            .chain(hand.iter().map(|h| &h.0))
+        };
+        let shadow_targets = shadow_formats.map(|f| {
+            let colors = every_pass().fold(0u16, |m, p| {
+                let own = if p.group.shadow() {
+                    p.reads | p.written | p.flip
+                } else {
+                    0
+                };
+                m | own | p.shadow_reads
+            });
+            let depth1 = every_pass()
+                .flat_map(|p| &p.samplers)
+                .any(|s| matches!(s.source, Source::ShadowDepth(1, _)));
+            let t =
+                super::pack_shadow::ShadowTargets::new(device, &shadow_config, f, colors, depth1);
+            notes.push(format!(
+                "shadow map {0}x{0}, shadowcolor buffers {colors:#b}{1}",
+                t.size,
+                if depth1 { ", shadowtex1" } else { "" }
+            ));
+            t
+        });
         // A clear only matters when a program reads the buffer before one writes all of it
         // (composite passes cover their whole target, terrain does not); the others are skipped.
         let mut cleared = Vec::new();
@@ -1215,6 +1333,8 @@ impl PackPost {
             weather_generation: 0,
             hand,
             depth1,
+            shadow_targets,
+            shadow_comp,
             mipped,
             mips_valid: 0,
             down,
@@ -1319,17 +1439,43 @@ impl PackPost {
             queue.write_buffer(&pass.ubo, 0, &pass.block);
         }
         let targets = self.targets.as_ref().expect("resized");
+        let shadow = self.shadow_targets.as_ref();
+        let shadow_main = shadow.map_or(0, |s| s.main);
+        let shadow_space = pass.group.shadow();
         // A chain is sampled only while it is current: a buffer written since its last chain
-        // reads its first level, never stale levels (6.1.7).
-        let current = self.mips_valid & self.mipped & pass.reads;
-        let key = u32::from(self.main & pass.reads) | u32::from(current) << 16;
+        // reads its first level, never stale levels (6.1.7). The shadow buffers have none.
+        let (main, current) = if shadow_space {
+            (shadow_main, 0)
+        } else {
+            (self.main, self.mips_valid & self.mipped & pass.reads)
+        };
+        let key = u64::from(main & pass.reads)
+            | u64::from(current) << 16
+            | u64::from(shadow_main & pass.shadow_reads) << 32;
         let group = pass.groups.entry(key).or_insert_with(|| {
             let mut entries = vec![wgpu::BindGroupEntry {
                 binding: 0,
                 resource: pass.ubo.as_entire_binding(),
             }];
             for s in &pass.samplers {
+                let shadow_color = |i: usize, side: usize| {
+                    shadow.and_then(|t| t.color[i].as_ref()).map(|c| &c[side])
+                };
                 let texture = match s.source {
+                    Source::Color(i) if shadow_space => {
+                        shadow_color(i, usize::from(key & 1 << i != 0)).unwrap_or(&self.dummy)
+                    }
+                    Source::ShadowColor(i) => {
+                        shadow_color(i, usize::from(key & 1 << (32 + i) != 0))
+                            .unwrap_or(&self.dummy)
+                    }
+                    Source::ShadowDepth(i, _) => match shadow {
+                        Some(t) => match (i, &t.depth1) {
+                            (1, Some(d)) => &d.1,
+                            _ => &t.depth.1,
+                        },
+                        None => &self.shadow.0,
+                    },
                     Source::Color(i) => {
                         let side = usize::from(key & 1 << i != 0);
                         match (&targets.mips[i], &targets.color[i]) {
@@ -1366,7 +1512,7 @@ impl PackPost {
                     SamplerKind::Nearest => &self.nearest,
                     SamplerKind::Repeat => &self.repeat,
                     SamplerKind::NearestRepeat => &self.nearest_repeat,
-                    SamplerKind::Comparison => &self.shadow.1,
+                    SamplerKind::Comparison => shadow.map_or(&self.shadow.1, |t| &t.comparison),
                 };
                 entries.push(wgpu::BindGroupEntry {
                     binding: s.binding,
@@ -1399,15 +1545,20 @@ impl PackPost {
             load: wgpu::LoadOp::Load,
             store: wgpu::StoreOp::Store,
         };
+        // The shadow pass draws into the shadow buffers and the shadow map.
+        let shadow = self.shadow_targets.as_ref().filter(|_| pass.group.shadow());
         let mut attachments: Vec<Option<wgpu::RenderPassColorAttachment>> = Vec::new();
         for &(location, buffer) in &pass.writes {
             let l = location as usize;
             if attachments.len() <= l {
                 attachments.resize(l + 1, None);
             }
-            attachments[l] = targets.color[buffer]
-                .as_ref()
-                .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load));
+            attachments[l] = match shadow {
+                Some(s) => s.color(buffer, false).and_then(|v| attach(v, load)),
+                None => targets.color[buffer]
+                    .as_ref()
+                    .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load)),
+            };
         }
         let timestamp_writes = self.timing.as_mut().and_then(|t| t.writes(&pass.name));
         encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
@@ -1415,7 +1566,7 @@ impl PackPost {
             color_attachments: &attachments,
             timestamp_writes,
             depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
-                view: &targets.depth,
+                view: shadow.map_or(&targets.depth, |s| &s.depth.1),
                 depth_ops: Some(wgpu::Operations {
                     load: wgpu::LoadOp::Load,
                     store: wgpu::StoreOp::Store,
@@ -1933,6 +2084,55 @@ impl PackPost {
     /// Runs the pack over the world drawn into `world` (colour) and `world_depth`, then draws
     /// the result onto `screen`.
     #[allow(clippy::too_many_arguments)]
+    /// The shadow pass (2.1, passes 2 and 3): the shadow buffers cleared, then the `shadowcomp`
+    /// programs, each drawing into the "alt" side of what it writes and flipping it after.
+    fn run_shadow(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+    ) {
+        let Some(t) = &self.shadow_targets else {
+            return;
+        };
+        t.clear(encoder);
+        t.copy_depth1(encoder);
+        let size = [t.size; 2];
+        let mut comp = std::mem::take(&mut self.shadow_comp);
+        for pass in &mut comp {
+            let group = self.bind(device, queue, pass, size);
+            let t = self.shadow_targets.as_ref().expect("shadow pass");
+            let mut attachments: Vec<Option<wgpu::RenderPassColorAttachment>> = Vec::new();
+            for &(location, buffer) in &pass.writes {
+                let l = location as usize;
+                if attachments.len() <= l {
+                    attachments.resize(l + 1, None);
+                }
+                // Overwritten whole.
+                let ops = wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
+                    store: wgpu::StoreOp::Store,
+                };
+                attachments[l] = t.color(buffer, true).and_then(|v| attach(v, ops));
+            }
+            {
+                let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                    label: Some(&pass.name),
+                    color_attachments: &attachments,
+                    timestamp_writes: self.timing.as_mut().and_then(|t| t.writes(&pass.name)),
+                    ..Default::default()
+                });
+                rp.set_pipeline(&pass.pipeline);
+                rp.set_bind_group(0, &group, &[]);
+                rp.draw(0..6, 0..1);
+            }
+            if let Some(t) = &mut self.shadow_targets {
+                t.main ^= pass.flip;
+            }
+        }
+        self.shadow_comp = comp;
+    }
+
     pub fn run(
         &mut self,
         device: &wgpu::Device,
@@ -1978,6 +2178,10 @@ impl PackPost {
         }
         self.uniforms.update(frame, inputs, size);
         self.uniforms.eval_custom(&mut self.custom);
+        if self.targets.is_none() {
+            return;
+        }
+        self.run_shadow(device, queue, encoder);
         let Some(targets) = &self.targets else { return };
         let main = |m: u16, i: usize| usize::from(m & 1 << i != 0);
         let view = |m: u16, i: usize, alt: bool| {
@@ -2249,10 +2453,22 @@ mod tests {
 
     #[test]
     fn sampler_names() {
-        assert!(source("gaux1") == Source::Color(4));
-        assert!(source("gdepthtex") == Source::Depth);
-        assert!(source("depthtex2") == Source::Depth1);
-        assert!(source("noisetex") == Source::Noise);
-        assert!(source("shadowcolor0") == Source::Dummy);
+        let main = |n| source(n, false, false, false);
+        assert!(main("gaux1") == Source::Color(4));
+        assert!(main("gdepthtex") == Source::Depth);
+        assert!(main("depthtex2") == Source::Depth1);
+        assert!(main("noisetex") == Source::Noise);
+        // Without the shadow pass, the shadow buffers are stand-ins.
+        assert!(main("shadowcolor0") == Source::Dummy);
+        assert!(main("shadowtex0") == Source::Dummy);
+        // With it: shadowcolor n is buffer n of the shadow programs, `shadow` is shadowtex1
+        // beside `watershadow` (6.3), and colortex is not theirs.
+        assert!(source("shadowcolor", false, true, false) == Source::ShadowColor(0));
+        assert!(source("shadowcolor1", true, true, false) == Source::Color(1));
+        assert!(source("colortex1", true, true, false) == Source::Dummy);
+        assert!(source("shadow", false, true, false) == Source::ShadowDepth(0, false));
+        assert!(source("shadow", false, true, true) == Source::ShadowDepth(1, false));
+        assert!(source("watershadow", false, true, true) == Source::ShadowDepth(0, false));
+        assert!(source("shadowtex1HW", false, true, false) == Source::ShadowDepth(1, true));
     }
 }
diff --git a/crates/horizon-client/src/gfx/pack_shadow.rs b/crates/horizon-client/src/gfx/pack_shadow.rs
new file mode 100644
index 000000000..7688d1250
--- /dev/null
+++ b/crates/horizon-client/src/gfx/pack_shadow.rs
@@ -0,0 +1,150 @@
+//! A shader pack's shadow buffers (spec 6.3): the shadow map's depth (`shadowtex0`, and
+//! `shadowtex1` without translucent geometry), and the colour buffers `shadowcolor0/1`, each
+//! with two sides that `shadowcomp` programs flip as composite programs flip colortex (6.1.6).
+//! Square, `shadowMapResolution` pixels.
+
+/// What the shadow pass writes and the programs read.
+pub(super) struct ShadowTargets {
+    pub size: u32,
+    /// `shadowtex0`, written by the shadow pass.
+    pub depth: (wgpu::Texture, wgpu::TextureView),
+    /// `shadowtex1`: a copy of `shadowtex0` taken before translucent terrain, when read.
+    pub depth1: Option<(wgpu::Texture, wgpu::TextureView)>,
+    /// Both sides of each shadowcolor buffer used.
+    pub color: [Option<[wgpu::TextureView; 2]>; 2],
+    /// The clear colour of each buffer cleared every frame.
+    pub clears: [Option<[f32; 4]>; 2],
+    /// Bit n set: B is shadowcolor n's "main".
+    pub main: u16,
+    /// Depth comparison for `sampler2DShadow` (hardware filtering): linear, as GL filters it.
+    pub comparison: wgpu::Sampler,
+}
+
+fn target(
+    device: &wgpu::Device,
+    label: &str,
+    size: u32,
+    format: wgpu::TextureFormat,
+    copy: wgpu::TextureUsages,
+) -> (wgpu::Texture, wgpu::TextureView) {
+    let texture = device.create_texture(&wgpu::TextureDescriptor {
+        label: Some(label),
+        size: wgpu::Extent3d {
+            width: size,
+            height: size,
+            depth_or_array_layers: 1,
+        },
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: wgpu::TextureDimension::D2,
+        format,
+        usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::RENDER_ATTACHMENT | copy,
+        view_formats: &[],
+    });
+    let view = texture.create_view(&Default::default());
+    (texture, view)
+}
+
+impl ShadowTargets {
+    /// The buffers of `shadow` the pack uses: `colors` (bit n: shadowcolor n), `depth1` when
+    /// some program reads `shadowtex1`. The resolution is kept within the device's limit.
+    pub fn new(
+        device: &wgpu::Device,
+        shadow: &horizon_shaders::Shadow,
+        formats: [wgpu::TextureFormat; 2],
+        colors: u16,
+        depth1: bool,
+    ) -> Self {
+        let size = shadow
+            .resolution
+            .clamp(1, device.limits().max_texture_dimension_2d);
+        let copy = wgpu::TextureUsages::COPY_SRC | wgpu::TextureUsages::COPY_DST;
+        let depth = wgpu::TextureFormat::Depth32Float;
+        let color = std::array::from_fn(|n| {
+            (colors & 1 << n != 0).then(|| {
+                [0, 1].map(|side| {
+                    let label = format!("Shader pack shadowcolor{n} {}", ["A", "B"][side]);
+                    target(
+                        device,
+                        &label,
+                        size,
+                        formats[n],
+                        wgpu::TextureUsages::empty(),
+                    )
+                    .1
+                })
+            })
+        });
+        Self {
+            size,
+            depth: target(device, "Shader pack shadowtex0", size, depth, copy),
+            depth1: depth1.then(|| target(device, "Shader pack shadowtex1", size, depth, copy)),
+            color,
+            clears: std::array::from_fn(|n| {
+                let b = &shadow.colors[n];
+                b.clear.then(|| b.clear_color.unwrap_or([1.0; 4]))
+            }),
+            main: 0,
+            comparison: device.create_sampler(&wgpu::SamplerDescriptor {
+                label: Some("Shader pack shadow comparison"),
+                compare: Some(wgpu::CompareFunction::LessEqual),
+                mag_filter: wgpu::FilterMode::Linear,
+                min_filter: wgpu::FilterMode::Linear,
+                ..Default::default()
+            }),
+        }
+    }
+
+    /// Side `alt` (of "main" and "alt") of shadowcolor `n`.
+    pub fn color(&self, n: usize, alt: bool) -> Option<&wgpu::TextureView> {
+        let side = usize::from(self.main & 1 << n != 0) ^ usize::from(alt);
+        self.color.get(n)?.as_ref().map(|c| &c[side])
+    }
+
+    /// Clears the shadow map and the shadowcolor buffers cleared every frame (6.3).
+    pub fn clear(&self, encoder: &mut wgpu::CommandEncoder) {
+        let attachments: Vec<_> = (0..2)
+            .filter_map(|n| {
+                let c = self.clears[n]?;
+                Some(Some(wgpu::RenderPassColorAttachment {
+                    view: self.color(n, false)?,
+                    depth_slice: None,
+                    resolve_target: None,
+                    ops: wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color {
+                            r: c[0].into(),
+                            g: c[1].into(),
+                            b: c[2].into(),
+                            a: c[3].into(),
+                        }),
+                        store: wgpu::StoreOp::Store,
+                    },
+                }))
+            })
+            .collect();
+        encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: Some("Shader pack shadow clear"),
+            color_attachments: &attachments,
+            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
+                view: &self.depth.1,
+                depth_ops: Some(wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(1.0),
+                    store: wgpu::StoreOp::Store,
+                }),
+                stencil_ops: None,
+            }),
+            ..Default::default()
+        });
+    }
+
+    /// `shadowtex1`: the shadow map as it is now (before translucent geometry).
+    pub fn copy_depth1(&self, encoder: &mut wgpu::CommandEncoder) {
+        if let Some((copy, _)) = &self.depth1 {
+            encoder.copy_texture_to_texture(
+                self.depth.0.as_image_copy(),
+                copy.as_image_copy(),
+                self.depth.0.size(),
+            );
+        }
+    }
+}

From bf81ae6358638575fb14192f2a5f82495a0ce13f Mon Sep 17 00:00:00 2001
From: Alexander Krylov <sashakryllov58@gmail.com>
Date: Sun, 25 Oct 2026 18:28:48 +0300
Subject: [PATCH 123/270] Furnace: pay the experience a smelt earned

RecipesUsed was written as an empty compound and never read, so a furnace
paid nothing when its output was taken and nothing when it was broken.

- Furnace keeps the per-recipe counter, saves and loads it, and floors each
  recipe on its own as AbstractFurnaceBlockEntity.createExperience does.
- FurnaceResultSlot.checkTakeAchievements pays on a take: the counter is
  read and cleared when the output slot loses an item.
- AbstractFurnaceBlockEntity.playerDestroy pays the same counter as orbs at
  the block when it is broken, whatever the tool.

Fixes #1732

Co-Authored-By: Hermes Agent (Nous Research) <noreply@nousresearch.com>
---
 .../examples/probe/menu_fixture.rs            |  1 +
 crates/horizon-client/src/containers.rs       | 47 +++++++++++++++++
 crates/horizon-client/src/crafting.rs         |  8 +++
 crates/horizon-client/src/game.rs             | 51 +++++++++++++++++++
 crates/horizon-client/src/game/remote.rs      |  1 +
 crates/horizon-client/src/save.rs             | 35 ++++++++++++-
 6 files changed, 142 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/examples/probe/menu_fixture.rs b/crates/horizon-client/examples/probe/menu_fixture.rs
index 3c83b20bc..9ec558de3 100644
--- a/crates/horizon-client/examples/probe/menu_fixture.rs
+++ b/crates/horizon-client/examples/probe/menu_fixture.rs
@@ -169,6 +169,7 @@ pub fn main() -> horizon_client::Result<()> {
             cooking_timer: menu.data[2],
             cooking_total: menu.data[3],
             speed: 1.0,
+            recipes_used: Default::default(),
         });
         menu.drops.clear();
         menu.equipped.clear();
diff --git a/crates/horizon-client/src/containers.rs b/crates/horizon-client/src/containers.rs
index de2e1b2e9..3701fefaf 100644
--- a/crates/horizon-client/src/containers.rs
+++ b/crates/horizon-client/src/containers.rs
@@ -44,6 +44,10 @@ pub struct Furnace {
     pub cooking_timer: i32,
     pub cooking_total: i32,
     pub speed: f32,
+    /// `AbstractFurnaceBlockEntity.recipesUsed`: how many of each recipe this furnace has
+    /// made since a player last took from its output. The experience is owed per recipe
+    /// rather than per item, and a save keeps it as the `RecipesUsed` compound.
+    pub recipes_used: HashMap<String, u32>,
 }
 /// A hopper's slots: the only plain container with five.
 pub const HOPPER_SLOTS: usize = 5;
@@ -190,6 +194,7 @@ impl BlockEntity {
                 cooking_timer: 0,
                 cooking_total: 0,
                 speed: 1.0,
+                recipes_used: HashMap::new(),
             }));
         }
         if name == "minecraft:creaking_heart" {
@@ -483,6 +488,26 @@ impl Furnace {
             self.cooking_timer = 0;
         }
     }
+    /// `AbstractFurnaceBlockEntity.createExperience`: each recipe's own share is floored,
+    /// then the floors are added. Flooring the sum instead pays one point for two recipes
+    /// worth 0.6 each, which vanilla does not.
+    fn owed(used: &HashMap<String, u32>, experience: impl Fn(&str) -> f32) -> u32 {
+        used.iter()
+            .map(|(id, count)| (experience(id) * *count as f32).floor().max(0.0) as u32)
+            .sum()
+    }
+    /// What this furnace owes right now, without forgetting it: breaking the block reads
+    /// the same counter, and only a payout clears it.
+    pub fn experience_owed(&self, recipes: &Recipes) -> u32 {
+        Self::owed(&self.recipes_used, |id| recipes.cooking_experience(id))
+    }
+    /// `AbstractFurnaceBlockEntity.awardUsedRecipesAndPopExperience`: the experience this
+    /// furnace owes, forgotten as it is paid.
+    pub fn take_experience(&mut self, recipes: &Recipes) -> u32 {
+        let owed = self.experience_owed(recipes);
+        self.recipes_used.clear();
+        owed
+    }
     /// A menu click wrote its slots into `items`, and `before` was the input
     /// slot until then: the menu called `setItem` on it only if it changed
     /// (`Slot.setByPlayer`; partial takes and merges keep the stack).
@@ -564,6 +589,7 @@ impl Furnace {
                                     Some(out) => out.count += recipe.result.count,
                                     None => self.items[2] = Some(recipe.result.clone()),
                                 }
+                                *self.recipes_used.entry(recipe.id.clone()).or_insert(0) += 1;
                                 if let Some(i) = self.items[0].as_mut() {
                                     i.count -= 1;
                                     if i.count == 0 {
@@ -594,3 +620,24 @@ fn total_time(time: u32, speed: f32) -> i32 {
         time as i32
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `createExperience` floors each recipe on its own. Two recipes worth 0.6 each pay
+    /// nothing, where flooring their sum would pay one point.
+    #[test]
+    fn experience_is_floored_per_recipe_and_not_on_the_sum() {
+        let mut used = HashMap::new();
+        used.insert("a".to_owned(), 1);
+        used.insert("b".to_owned(), 1);
+        assert_eq!(Furnace::owed(&used, |_| 0.6), 0);
+
+        used.insert("c".to_owned(), 10);
+        assert_eq!(
+            Furnace::owed(&used, |id| if id == "c" { 0.1 } else { 0.0 }),
+            1
+        );
+    }
+}
diff --git a/crates/horizon-client/src/crafting.rs b/crates/horizon-client/src/crafting.rs
index d0b8906ee..690383963 100644
--- a/crates/horizon-client/src/crafting.rs
+++ b/crates/horizon-client/src/crafting.rs
@@ -1610,6 +1610,14 @@ impl Recipes {
         }
         out
     }
+    /// The `experience` of the cooking recipe with this file name, and 0 for one this data
+    /// pack does not have (a save from another pack can name it).
+    pub fn cooking_experience(&self, id: &str) -> f32 {
+        self.cooking
+            .iter()
+            .find(|c| c.id == id)
+            .map_or(0.0, |c| c.experience)
+    }
     pub fn cook(&self, kind: &str, input: &ItemStack) -> Option<&Cooking> {
         let index = self.cook_index.get_or_init(|| {
             let mut index = CookIndex::new();
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..7c0bbc917 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -3246,6 +3246,12 @@ impl Game<'_> {
         }
         // The block entity as it was, for what the drops copy from it.
         let key = (pos[0], pos[1], pos[2]);
+        // AbstractFurnaceBlockEntity.playerDestroy: the experience its recipes earned drops
+        // with the block. Read now, paid only if the block is really removed.
+        let furnace_xp = match self.world.block_entities.get(&key) {
+            Some(BlockEntity::Furnace(f)) => f.experience_owed(self.res.recipes()),
+            _ => 0,
+        };
         if let Some(entity) = self.world.block_entities.get(&key).cloned() {
             let name = self.world.block_names.get(&key).cloned();
             self.pending.record(pos, &entity, &facts.name, name);
@@ -3315,6 +3321,18 @@ impl Game<'_> {
                     );
                 }
             }
+            // Stored recipe experience is not a loot drop: it leaves with the block
+            // whatever the tool, as `AbstractFurnaceBlockEntity` does.
+            if furnace_xp > 0 {
+                self.spawn_orbs(
+                    [
+                        f64::from(pos[0]) + 0.5,
+                        f64::from(pos[1]) + 0.5,
+                        f64::from(pos[2]) + 0.5,
+                    ],
+                    furnace_xp,
+                );
+            }
         }
         self.pending.clear(pos);
         self.process_level_events()?;
@@ -5936,6 +5954,12 @@ impl Game<'_> {
             // Attached after the slots were set: setting them is not a click.
             menu.merchant = session.map(|(s, _)| s);
         }
+        // `FurnaceResultSlot.checkTakeAchievements` pays out on what left the output slot.
+        let furnace_before = if matches!(kind, Kind::Furnace(_)) {
+            menu.slot(2).cloned().map_or(0, |s| s.count)
+        } else {
+            0
+        };
         let outcome = run(&mut menu, &env, &to_menu);
         let made = maps.made.take();
         match outcome {
@@ -5953,6 +5977,12 @@ impl Game<'_> {
             self.merchant_sync_out(s);
         }
         let after: Vec<Option<ItemStack>> = (0..total).map(|i| menu.slot(i).cloned()).collect();
+        // Only a furnace has a result slot to compare: an enchanting table has two slots.
+        let furnace_after = if matches!(kind, Kind::Furnace(_)) {
+            after[2].as_ref().map_or(0, |s| s.count)
+        } else {
+            0
+        };
         let carried = menu.carried.take();
         let dropped = std::mem::take(&mut menu.dropped);
         let sounds = std::mem::take(&mut menu.sounds);
@@ -5977,6 +6007,15 @@ impl Game<'_> {
                 self.player_drop(stack);
             }
             self.award_crafted(&crafted);
+            // shortcut: paid straight to the player instead of through `ExperienceOrb.award`
+            // (no orb flies at them), which a furnace's orbs reach within a tick anyway;
+            // upgrade if the visual matters or another block pays out far from the player.
+            if furnace_before > furnace_after {
+                let owed = self.take_furnace_experience();
+                if owed > 0 {
+                    self.give_orb_points(owed);
+                }
+            }
         }
         if kind == Kind::Loom {
             if let Some(s) = self.station.as_mut() {
@@ -8768,6 +8807,18 @@ impl Game<'_> {
             self.give_orb_points(gained);
         }
     }
+    /// `AbstractFurnaceBlockEntity.awardUsedRecipesAndPopExperience`: what the open furnace
+    /// owes for everything it made since the last payout, cleared as it is read.
+    fn take_furnace_experience(&mut self) -> u32 {
+        let Some(pos) = self.container else {
+            return 0;
+        };
+        let recipes = self.res.recipes();
+        let Some(BlockEntity::Furnace(f)) = self.world.block_entities.get_mut(&pos) else {
+            return 0;
+        };
+        f.take_experience(recipes)
+    }
     /// `Player.giveExperiencePoints`, and `giveExperienceLevels`' level-up
     /// sound every fifth level (at most every 100 ticks).
     pub(super) fn give_orb_points(&mut self, gained: u32) {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..12e012a06 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -4919,6 +4919,7 @@ impl Game<'_> {
                     cooking_timer: 0,
                     cooking_total: 0,
                     speed: 1.0,
+                    recipes_used: std::collections::HashMap::new(),
                 }))
             }
             // HopperMenu, and DispenserMenu (MenuType.GENERIC_3x3: dispensers
diff --git a/crates/horizon-client/src/save.rs b/crates/horizon-client/src/save.rs
index da5735c17..937519da9 100644
--- a/crates/horizon-client/src/save.rs
+++ b/crates/horizon-client/src/save.rs
@@ -488,7 +488,12 @@ pub fn encode_block_entity(
             entries.push(("cooking_time_spent", Tag::Int(f.cooking_timer)));
             entries.push(("cooking_total_time", Tag::Int(f.cooking_total)));
             entries.push(("speed_multiplier", Tag::Float(f.speed.to_bits())));
-            entries.push(("RecipesUsed", Tag::Compound(Compound::new())));
+            let used: Compound = f
+                .recipes_used
+                .iter()
+                .map(|(id, count)| (id.as_str().into(), Tag::Int(*count as i32)))
+                .collect();
+            entries.push(("RecipesUsed", Tag::Compound(used)));
         }
         BlockEntity::Brewing(b) => {
             entries.push(("Items", encode_items(&b.items)));
@@ -640,6 +645,17 @@ pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::contain
             if let Some(speed) = float(tag.get("speed_multiplier")) {
                 f.speed = speed as f32;
             }
+            // A save without it owes nothing: the field is newer than some worlds.
+            if let Some(Tag::Compound(used)) = tag.get("RecipesUsed") {
+                for (id, count) in used {
+                    let count = match count {
+                        Tag::Int(n) => *n,
+                        _ => continue,
+                    };
+                    f.recipes_used
+                        .insert(id.to_string_lossy(), count.max(0) as u32);
+                }
+            }
         }
         BlockEntity::Brewing(b) => {
             let items = decode_items(tag.get("Items"), 5);
@@ -4276,4 +4292,21 @@ mod tests {
             .unwrap_or(0);
         assert_eq!(flying_survival, 0);
     }
+
+    /// `RecipesUsed` is what a furnace owes in experience, so a save that drops it pays the
+    /// player nothing after a reload.
+    #[test]
+    fn a_furnaces_recipes_used_survive_a_save() {
+        use crate::containers::BlockEntity;
+        let Some(BlockEntity::Furnace(mut f)) = BlockEntity::for_block("minecraft:furnace") else {
+            panic!("a furnace");
+        };
+        f.recipes_used
+            .insert("minecraft:cooked_porkchop".to_owned(), 3);
+        let tag = encode_block_entity((1, 64, 2), &BlockEntity::Furnace(f), "minecraft:furnace");
+        let Some((_, BlockEntity::Furnace(back))) = decode_block_entity(&tag) else {
+            panic!("a furnace back");
+        };
+        assert_eq!(back.recipes_used.get("minecraft:cooked_porkchop"), Some(&3));
+    }
 }

From feec1b67e8446f5d81a4418f956b8b6b0f394e1e Mon Sep 17 00:00:00 2001
From: JasonGu <1456970218@qq.com>
Date: Sun, 25 Oct 2026 23:29:23 +0800
Subject: [PATCH 124/270] Server deaths: build the message from the player's
 own combat record

A guest's death only had `death_cause`, which `/kill` alone sets, so a
server-thread, LAN or dedicated death fell back to "X died" or a generic
cause. Give each guest its own CombatTracker, fed by the motion events
the server already records, and take the message from
CombatTracker.getDeathMessage with the dying player's own name. The
wither's skull names the wither that launched it (projectile owner).

The death screen now resolves the server's component in the client's
current language instead of the session's en_us table, so it matches the
chat line.

Co-Authored-By: OpenCode DeepSeek V4.1 Flash <noreply@opencode.ai>
---
 crates/horizon-client/src/game.rs             |  3 +
 crates/horizon-client/src/game/combat.rs      |  6 +-
 crates/horizon-client/src/game/lan_actions.rs | 83 +++++++++++++------
 crates/horizon-client/src/game/remote.rs      | 10 +--
 crates/horizon-client/src/game/wither.rs      |  2 +
 5 files changed, 72 insertions(+), 32 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..848061ff5 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1568,6 +1568,8 @@ struct Game<'a> {
     cmds: commands::extra::CommandExtras,
     ui: chat::UiState,
     combat: combat::CombatTracker,
+    /// Each guest's own `CombatTracker`, out of `combat` between turns.
+    guest_combat: std::collections::HashMap<u32, combat::CombatTracker>,
     mount: mounts::MountState,
     stats: stats::Stats,
     score: scoreboard::ScoreState,
@@ -12001,6 +12003,7 @@ impl<'a> Game<'a> {
             cmds: Default::default(),
             ui: Default::default(),
             combat: Default::default(),
+            guest_combat: Default::default(),
             mount: Default::default(),
             stats: Default::default(),
             score: Default::default(),
diff --git a/crates/horizon-client/src/game/combat.rs b/crates/horizon-client/src/game/combat.rs
index 70ae082aa..227aa0332 100644
--- a/crates/horizon-client/src/game/combat.rs
+++ b/crates/horizon-client/src/game/combat.rs
@@ -191,8 +191,12 @@ impl Game<'_> {
     }
     /// `CombatTracker.getDeathMessage`.
     pub(super) fn combat_death_message(&mut self) -> Text {
+        self.combat_death_message_for(Text::literal(PLAYER_NAME))
+    }
+    /// `CombatTracker.getDeathMessage` for a player whose display name is
+    /// `me`: a server's guest is not `PLAYER_NAME`.
+    pub(super) fn combat_death_message_for(&mut self, me: Text) -> Text {
         self.recheck_combat();
-        let me = Text::literal(PLAYER_NAME);
         let entries = std::mem::take(&mut self.combat.entries);
         self.combat.in_combat = false;
         let Some(killing) = entries.last() else {
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..f5d419357 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -143,6 +143,8 @@ pub(super) struct GuestSwap {
     adv_loaded: bool,
     last_inventory: u64,
     death_cause: Option<String>,
+    /// The guest's own damage record, in place while they act.
+    combat: super::combat::CombatTracker,
     /// The guest whose turn this one nests in, if any.
     acting: (Option<u32>, Option<String>, Option<u128>),
     /// The packets queued for that guest.
@@ -256,6 +258,14 @@ impl Game<'_> {
             host.play.insert(conn, play);
             return None;
         };
+        // The guest's own CombatTracker: damage to them is not the host's.
+        // A new body starts with no record of the last one.
+        let guest_combat = if fresh {
+            Default::default()
+        } else {
+            self.guest_combat.remove(&conn).unwrap_or_default()
+        };
+        let host_combat = std::mem::replace(&mut self.combat, guest_combat);
         self.potions.swap_player(&mut g.effects, &mut play.potions);
         motion.position = Vec3::new(g.position[0], g.position[1], g.position[2]);
         motion.ground.on_ground = g.on_ground;
@@ -418,6 +428,7 @@ impl Game<'_> {
             swings,
             projectiles,
             modifiers,
+            combat: host_combat,
         })
     }
 
@@ -468,12 +479,16 @@ impl Game<'_> {
             adv_loaded,
             last_inventory,
             death_cause,
+            combat,
             acting,
             packets,
             swings,
             projectiles,
             modifiers,
         } = swap;
+        // The guest's damage record back into their slot, the host's in place.
+        let guest_combat = std::mem::replace(&mut self.combat, combat);
+        self.guest_combat.insert(conn, guest_combat);
         play.modifiers = std::mem::replace(&mut self.applied_modifiers, modifiers);
         // What the guest shot is theirs (Projectile.setOwner).
         for p in self.creatures.projectiles.iter_mut().skip(projectiles) {
@@ -1792,32 +1807,31 @@ impl Game<'_> {
                 let drops = (g.game_mode != SPECTATOR)
                     .then(|| [at[0], at[1] + g.eye_height() - 0.3, at[2]]);
                 let cause = host.play.get_mut(&conn).and_then(|p| p.death_cause.take());
-                let message = match cause {
-                    // ServerPlayer.die: the death message, to everyone unless
-                    // the player's team hides it.
-                    Some(key) if self.ui.rules.bool("show_death_messages") => {
-                        let text = horizon_client::text::Text::translate(
-                            &key,
-                            &[self.player_text(&name, uuid)],
-                        );
-                        let message = horizon_client::lan::data::component_nbt(&text.component());
-                        let team = self.score.board.players_team(&name);
-                        if horizon_client::scoreboard::own_death_message_shown(team) {
-                            host.hub.system_message(message.clone());
-                            if self.options.dedicated.is_some() {
-                                super::dedicated::log(
-                                    "INFO",
-                                    &format!("System chat: {}", text.plain()),
-                                );
-                            } else if self.player.is_some() {
-                                self.system_message(text);
-                            }
-                        }
-                        message
+                let me = self.player_text(&name, uuid);
+                let text = match cause {
+                    Some(key) => horizon_client::text::Text::translate(&key, &[me]),
+                    None if at[1] < f64::from(horizon_client::chunk::MIN_Y - 64) => {
+                        horizon_client::text::Text::translate("death.attack.outOfWorld", &[me])
                     }
-                    Some(_) => literal(""),
-                    None => literal(&format!("{name} died")),
+                    None => self.guest_death_message(conn, me),
                 };
+                let message = horizon_client::lan::data::component_nbt(&text.component());
+                // ServerPlayer.die: the message goes to everyone unless the
+                // player's team hides it, and always to the dying player.
+                if self.ui.rules.bool("show_death_messages") {
+                    let team = self.score.board.players_team(&name);
+                    if horizon_client::scoreboard::own_death_message_shown(team) {
+                        host.hub.system_message(message.clone());
+                        if self.options.dedicated.is_some() {
+                            super::dedicated::log(
+                                "INFO",
+                                &format!("System chat: {}", text.plain()),
+                            );
+                        } else if self.player.is_some() {
+                            self.system_message(text);
+                        }
+                    }
+                }
                 host.hub.send_to(
                     conn,
                     &C::PlayerCombatKill(play::PlayerCombatKill { id, message }),
@@ -1832,6 +1846,21 @@ impl Game<'_> {
         }
     }
 
+    /// `ServerPlayer.die`'s message from a guest's own `CombatTracker`, which
+    /// sits in `guest_combat` between turns.
+    fn guest_death_message(
+        &mut self,
+        conn: u32,
+        me: horizon_client::text::Text,
+    ) -> horizon_client::text::Text {
+        let mut tracker = self.guest_combat.remove(&conn).unwrap_or_default();
+        std::mem::swap(&mut self.combat, &mut tracker);
+        let text = self.combat_death_message_for(me);
+        std::mem::swap(&mut self.combat, &mut tracker);
+        self.guest_combat.insert(conn, tracker);
+        text
+    }
+
     /// `Player.tick`'s sleep counter, and `LivingEntity.tick`'s wake-up of a
     /// sleeper who died or whose bed is gone.
     fn guest_sleep_tick(&mut self, host: &mut LanHost, gi: usize) {
@@ -2033,10 +2062,14 @@ impl Game<'_> {
                 resources: game.motion,
             }
             .server_travel();
+            // Landing damage from this travel reaches the tracker too.
+            events.append(&mut player.events);
             // A hurt since the last tick marked the velocity (Entity.markHurt):
             // ServerEntity.sendChanges sends it as it is after this travel.
             let marked = std::mem::take(&mut player.health.sync_velocity);
-            (events, marked.then_some(player.velocity))
+            let velocity = marked.then_some(player.velocity);
+            game.record_combat(&events);
+            (events, velocity)
         });
         let Some((events, marked)) = events else {
             return;
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 044e43835..53f7ea186 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -2285,12 +2285,10 @@ impl Game<'_> {
                 }
             }
             C::PlayerCombatKill(p) => {
-                let lang = self
-                    .remote
-                    .as_ref()
-                    .map(|r| r.lang.clone())
-                    .unwrap_or_default();
-                let message = plain(&p.message, &lang);
+                // The component resolves in the client's current language, as
+                // the chat line does, not in the language the session joined
+                // with (`Remote.lang` is the vanilla server-language table).
+                let message = remote_text(&p.message).plain();
                 let me = self.remote.as_ref().is_some_and(|r| r.entity_id == p.id);
                 if let Some(r) = self.remote.as_mut() {
                     r.death_message = Some(message);
diff --git a/crates/horizon-client/src/game/wither.rs b/crates/horizon-client/src/game/wither.rs
index 91fe91b00..8084425ca 100644
--- a/crates/horizon-client/src/game/wither.rs
+++ b/crates/horizon-client/src/game/wither.rs
@@ -92,6 +92,8 @@ impl Game<'_> {
         match who {
             Some(Who::Player) => {
                 if !self.creative {
+                    // WitherSkull.onHitEntity's source: the wither launched it.
+                    self.combat.projectile_owner = owner;
                     self.mob_hits_player_kind(
                         amount,
                         [p.previous.x, p.previous.y, p.previous.z],

From d9360338f655668351008f323e6181baf44ab7d0 Mon Sep 17 00:00:00 2001
From: Joansitoh <joan.programas@gmail.com>
Date: Sun, 25 Oct 2026 16:33:35 +0100
Subject: [PATCH 125/270] Show item lore in tooltips with vanilla purple italic
 styles.

Stack tooltips skipped minecraft:lore entirely; draw the component lines as Text so colours and explicit non-italic spans survive.
---
 crates/horizon-client/src/game/beacon.rs      |   7 +-
 crates/horizon-client/src/game/loom.rs        |   9 +-
 crates/horizon-client/src/game/recipe_book.rs |  21 ++-
 crates/horizon-client/src/game/stations.rs    | 134 ++++++++++++------
 crates/horizon-client/src/item_tooltip.rs     |  56 +++++++-
 5 files changed, 167 insertions(+), 60 deletions(-)

diff --git a/crates/horizon-client/src/game/beacon.rs b/crates/horizon-client/src/game/beacon.rs
index c8a0bcba6..24ead3a3d 100644
--- a/crates/horizon-client/src/game/beacon.rs
+++ b/crates/horizon-client/src/game/beacon.rs
@@ -519,7 +519,12 @@ impl Game<'_> {
             self.draw_tooltip_lines(batch, &lines, self.cursor.0, self.cursor.1);
         } else if let Some(key) = tooltip {
             let text = self.translate(&key, &key);
-            self.draw_tooltip_lines(batch, &[(text, u32::MAX)], self.cursor.0, self.cursor.1);
+            self.draw_tooltip_lines(
+                batch,
+                &[(horizon_client::text::Text::literal(text), u32::MAX)],
+                self.cursor.0,
+                self.cursor.1,
+            );
         }
     }
     /// `BeaconRenderer`: each section's rotating solid beam and its glow.
diff --git a/crates/horizon-client/src/game/loom.rs b/crates/horizon-client/src/game/loom.rs
index ef49c8cf1..3d69aaca6 100644
--- a/crates/horizon-client/src/game/loom.rs
+++ b/crates/horizon-client/src/game/loom.rs
@@ -218,7 +218,7 @@ impl Game<'_> {
         oy: f32,
         draws: &[ScreenDraw],
         background: bool,
-    ) -> Option<Vec<(String, u32)>> {
+    ) -> Option<Vec<(horizon_client::text::Text, u32)>> {
         let atlas = &self.gui.atlas;
         let mut tooltip = None;
         let mut sheet: Option<String> = None;
@@ -261,7 +261,10 @@ impl Game<'_> {
                     ..
                 } => self.draw_banner_result(batch, ox + *x0 as f32, oy + *y0 as f32, base, layers),
                 ScreenDraw::Tooltip { key } => {
-                    tooltip = Some(vec![(self.translate(key, key), u32::MAX)]);
+                    tooltip = Some(vec![(
+                        horizon_client::text::Text::literal(self.translate(key, key)),
+                        u32::MAX,
+                    )]);
                 }
                 ScreenDraw::SpriteOf { id } => sheet = Some(id.clone()),
                 ScreenDraw::Fill {
@@ -314,7 +317,7 @@ impl Game<'_> {
         ox: f32,
         oy: f32,
         local: (f32, f32),
-    ) -> Option<Vec<(String, u32)>> {
+    ) -> Option<Vec<(horizon_client::text::Text, u32)>> {
         let s = self.station.as_ref()?;
         let l = &s.loom;
         let dye = s.inputs[1]
diff --git a/crates/horizon-client/src/game/recipe_book.rs b/crates/horizon-client/src/game/recipe_book.rs
index d3c14ffc7..2536c3e03 100644
--- a/crates/horizon-client/src/game/recipe_book.rs
+++ b/crates/horizon-client/src/game/recipe_book.rs
@@ -1163,8 +1163,12 @@ impl Game<'_> {
     }
     /// Paints recipe book calls; returns the first tooltip set (vanilla keeps
     /// the first one a frame asks for).
-    fn paint_book(&mut self, batch: &mut HudBatch, calls: &[Drawn]) -> Option<Vec<(String, u32)>> {
-        let mut tooltip: Option<Vec<(String, u32)>> = None;
+    fn paint_book(
+        &mut self,
+        batch: &mut HudBatch,
+        calls: &[Drawn],
+    ) -> Option<Vec<(horizon_client::text::Text, u32)>> {
+        let mut tooltip: Option<Vec<(horizon_client::text::Text, u32)>> = None;
         for d in calls {
             let start = batch.vertices.len();
             let atlas = &self.gui.atlas;
@@ -1259,7 +1263,14 @@ impl Game<'_> {
                         tooltip = Some(
                             lines
                                 .iter()
-                                .map(|l| (l.iter().map(|r| r.text.as_str()).collect(), u32::MAX))
+                                .map(|l| {
+                                    (
+                                        horizon_client::text::Text::literal(
+                                            l.iter().map(|r| r.text.as_str()).collect::<String>(),
+                                        ),
+                                        u32::MAX,
+                                    )
+                                })
                                 .collect(),
                         );
                     }
@@ -1269,10 +1280,10 @@ impl Game<'_> {
                         let mut lines = self.stack_tooltip(stack);
                         if *more {
                             lines.push((
-                                self.translate(
+                                horizon_client::text::Text::literal(self.translate(
                                     "gui.recipebook.moreRecipes",
                                     "Right Click for More",
-                                ),
+                                )),
                                 u32::MAX,
                             ));
                         }
diff --git a/crates/horizon-client/src/game/stations.rs b/crates/horizon-client/src/game/stations.rs
index ffe56d699..fd7bd2642 100644
--- a/crates/horizon-client/src/game/stations.rs
+++ b/crates/horizon-client/src/game/stations.rs
@@ -1096,7 +1096,7 @@ impl Game<'_> {
         }
         let (ox, oy) = self.inventory_origin(batch);
         let local = (self.cursor.0 - ox, self.cursor.1 - oy);
-        let mut tooltip: Option<Vec<(String, u32)>> = None;
+        let mut tooltip: Option<Vec<(horizon_client::text::Text, u32)>> = None;
         {
             let atlas = &self.gui.atlas;
             batch.fill(
@@ -1345,16 +1345,19 @@ impl Game<'_> {
                             let clue = self
                                 .translate("container.enchant.clue", "%s . . . ?")
                                 .replace("%s", &name);
-                            let mut lines = vec![(clue, u32::MAX)];
+                            let mut lines =
+                                vec![(horizon_client::text::Text::literal(clue), u32::MAX)];
                             if !self.creative {
-                                lines.push((String::new(), u32::MAX));
+                                lines.push((horizon_client::text::Text::literal(""), u32::MAX));
                                 if level < cost {
                                     lines.push((
-                                        self.translate(
-                                            "container.enchant.level.requirement",
-                                            "Level Requirement: %s",
-                                        )
-                                        .replace("%s", &cost.to_string()),
+                                        horizon_client::text::Text::literal(
+                                            self.translate(
+                                                "container.enchant.level.requirement",
+                                                "Level Requirement: %s",
+                                            )
+                                            .replace("%s", &cost.to_string()),
+                                        ),
                                         rgba(255, 85, 85, 255),
                                     ));
                                 } else {
@@ -1372,7 +1375,7 @@ impl Game<'_> {
                                         .replace("%s", &n.to_string())
                                     };
                                     lines.push((
-                                        lapis,
+                                        horizon_client::text::Text::literal(lapis),
                                         if gold >= n as i32 {
                                             rgba(170, 170, 170, 255)
                                         } else {
@@ -1391,7 +1394,10 @@ impl Game<'_> {
                                         )
                                         .replace("%s", &n.to_string())
                                     };
-                                    lines.push((levels, rgba(170, 170, 170, 255)));
+                                    lines.push((
+                                        horizon_client::text::Text::literal(levels),
+                                        rgba(170, 170, 170, 255),
+                                    ));
                                 }
                             }
                             tooltip = Some(lines);
@@ -1500,10 +1506,10 @@ impl Game<'_> {
                         );
                         if inside(local, 65.0, 46.0, 28.0, 21.0) {
                             tooltip = Some(vec![(
-                                self.translate(
+                                horizon_client::text::Text::literal(self.translate(
                                     "container.upgrade.error_tooltip",
                                     "Item can't be upgraded this way",
-                                ),
+                                )),
                                 u32::MAX,
                             )]);
                         }
@@ -1630,9 +1636,12 @@ impl Game<'_> {
 
     // ---------------------------------------------------------------- tooltips
 
-    /// `ItemStack.getTooltipLines` subset: name in rarity colour, potion
-    /// effects, enchantments (gray, curses red), stored enchantments, trims.
-    pub(super) fn stack_tooltip(&self, stack: &ItemStack) -> Vec<(String, u32)> {
+    /// `ItemStack.getTooltipLines` subset: name in rarity colour, lore,
+    /// potion effects, enchantments (gray, curses red), stored enchantments, trims.
+    pub(super) fn stack_tooltip(
+        &self,
+        stack: &ItemStack,
+    ) -> Vec<(horizon_client::text::Text, u32)> {
         let e: &Enchantments = &self.res.stations().enchantments;
         let props = e.props(&stack.item);
         let rarity = horizon_client::item_tooltip::rarity(
@@ -1663,24 +1672,33 @@ impl Game<'_> {
         let display = horizon_client::item_tooltip::TooltipDisplay::for_stack(stack);
         let mut lines = Vec::new();
         if display.name_visible(self.screen == Screen::Creative) {
-            lines.push((name, color));
+            lines.push((horizon_client::text::Text::legacy(&name), color));
+        }
+        // ItemLore.addToTooltip: after the name, before other component lines.
+        if display.shows("minecraft:lore") {
+            for text in horizon_client::item_tooltip::lore_texts(stack) {
+                lines.push((text, u32::MAX));
+            }
         }
         let translate = |k: &str| e.translate(k).map(str::to_owned);
+        let push = |lines: &mut Vec<(horizon_client::text::Text, u32)>, s: String, c: u32| {
+            lines.push((horizon_client::text::Text::legacy(&s), c));
+        };
         // ItemContainerContents.addToTooltip.
         let hover_name = |s: &ItemStack| {
             s.custom_name()
                 .map_or_else(|| self.pack.names.item(&s.item), str::to_owned)
         };
         if display.shows("minecraft:container") {
-            for line in
+            for text in
                 horizon_client::item_tooltip::container_lines(stack, &hover_name, &translate)
             {
-                lines.push((line, u32::MAX));
+                push(&mut lines, text, u32::MAX);
             }
         }
         // Fireworks / FireworkExplosion.addToTooltip.
-        for line in horizon_client::item_tooltip::firework_lines(stack, &translate) {
-            lines.push((line, rgba(170, 170, 170, 255)));
+        for text in horizon_client::item_tooltip::firework_lines(stack, &translate) {
+            push(&mut lines, text, rgba(170, 170, 170, 255));
         }
         if display.shows("minecraft:potion_contents")
             && (stack.item.ends_with("potion") || &*stack.item == "minecraft:tipped_arrow")
@@ -1690,7 +1708,7 @@ impl Game<'_> {
                 "minecraft:tipped_arrow" => 0.125,
                 _ => 1.0,
             };
-            for (line, cat) in brewing::tooltip(stack.potion(), scale, &|k| {
+            for (text, cat) in brewing::tooltip(stack.potion(), scale, &|k| {
                 e.translate(k).map(str::to_owned)
             }) {
                 let c = match cat {
@@ -1698,18 +1716,19 @@ impl Game<'_> {
                     brewing::Category::Harmful => rgba(255, 85, 85, 255),
                     brewing::Category::Neutral => rgba(170, 170, 170, 255),
                 };
-                lines.push((line, c));
+                push(&mut lines, text, c);
             }
         }
         if display.shows("minecraft:trim")
             && let Some((material, pattern)) = stack.data().and_then(|d| d.trim.clone())
         {
-            lines.push((
+            push(
+                &mut lines,
                 e.translate("item.minecraft.smithing_template.upgrade")
                     .unwrap_or("Upgrade:")
                     .to_owned(),
                 rgba(170, 170, 170, 255),
-            ));
+            );
             let short = |s: &str| s.trim_start_matches("minecraft:").to_owned();
             let p = e
                 .translate(&format!("trim_pattern.minecraft.{}", short(&pattern)))
@@ -1717,38 +1736,44 @@ impl Game<'_> {
             let m = e
                 .translate(&format!("trim_material.minecraft.{}", short(&material)))
                 .map_or_else(|| short(&material), str::to_owned);
-            lines.push((format!(" {p}"), rgba(170, 170, 170, 255)));
-            lines.push((format!(" {m}"), rgba(170, 170, 170, 255)));
+            push(&mut lines, format!(" {p}"), rgba(170, 170, 170, 255));
+            push(&mut lines, format!(" {m}"), rgba(170, 170, 170, 255));
         }
         if display.shows("minecraft:stored_enchantments") {
             for (text, curse) in e.tooltip(stack.stored_enchantments()) {
-                lines.push((
+                push(
+                    &mut lines,
                     text,
                     if curse {
                         rgba(255, 85, 85, 255)
                     } else {
                         rgba(170, 170, 170, 255)
                     },
-                ));
+                );
             }
         }
         if display.shows("minecraft:enchantments") {
             for (text, curse) in e.tooltip(stack.enchantments()) {
-                lines.push((
+                push(
+                    &mut lines,
                     text,
                     if curse {
                         rgba(255, 85, 85, 255)
                     } else {
                         rgba(170, 170, 170, 255)
                     },
-                ));
+                );
             }
         }
         // BannerPatternLayers.addToTooltip: up to six layer names.
         if display.shows("minecraft:banner_patterns") {
             for layer in horizon_client::banner::tooltip_layers(stack).iter().take(6) {
                 let key = self.res.stations().banners.layer_key(layer);
-                lines.push((self.translate(&key, &key), rgba(170, 170, 170, 255)));
+                push(
+                    &mut lines,
+                    self.translate(&key, &key),
+                    rgba(170, 170, 170, 255),
+                );
             }
         }
         // Spawner.appendHoverText: what a spawner or trial spawner item spawns.
@@ -1762,15 +1787,15 @@ impl Game<'_> {
             match block_entity_item::spawner_entity(stack) {
                 Some(id) => {
                     let key = format!("entity.{}", id.replacen(':', ".", 1));
-                    lines.push((self.translate(&key, &id), gray));
+                    push(&mut lines, self.translate(&key, &id), gray);
                 }
                 None => {
-                    lines.push((String::new(), u32::MAX));
+                    push(&mut lines, String::new(), u32::MAX);
                     let desc1 =
                         self.translate("block.minecraft.spawner.desc1", "Interact with Spawn Egg:");
-                    lines.push((desc1, gray));
+                    push(&mut lines, desc1, gray);
                     let desc2 = self.translate("block.minecraft.spawner.desc2", "Sets Mob Type");
-                    lines.push((format!(" {desc2}"), rgba(85, 85, 255, 255)));
+                    push(&mut lines, format!(" {desc2}"), rgba(85, 85, 255, 255));
                 }
             }
         }
@@ -1798,11 +1823,13 @@ impl Game<'_> {
                     horizon_client::attack_strength::BASE_ATTACK_SPEED,
                 ),
             ];
-            lines.extend(horizon_client::item_tooltip::attribute_lines(
+            for (text, c) in horizon_client::item_tooltip::attribute_lines(
                 &info.modifiers,
                 Some(player_base),
                 &translate,
-            ));
+            ) {
+                push(&mut lines, text, c);
+            }
         }
         if display.shows("minecraft:damage")
             && let Some(info) = self.res.items().get(&stack.item)
@@ -1810,14 +1837,15 @@ impl Game<'_> {
             && stack.damage > 0
             && self.options_advanced_tooltips()
         {
-            lines.push((
+            push(
+                &mut lines,
                 format!(
                     "Durability: {} / {}",
                     info.max_damage - stack.damage,
                     info.max_damage
                 ),
                 u32::MAX,
-            ));
+            );
         }
         // ItemStack.OP_NBT_WARNING, for a player with game master permission.
         if self.ui.registries.permission >= 2 && block_entity_item::op_warning(stack) {
@@ -1832,7 +1860,11 @@ impl Game<'_> {
                     "Do not use unless you know the exact contents!",
                 ),
             ] {
-                lines.push((self.translate(key, fallback), rgba(255, 85, 85, 255)));
+                push(
+                    &mut lines,
+                    self.translate(key, fallback),
+                    rgba(255, 85, 85, 255),
+                );
             }
         }
         lines
@@ -1863,20 +1895,27 @@ impl Game<'_> {
         self.settings.file.bool("advancedItemTooltips")
     }
     /// `TooltipRenderUtil`: dark box with the purple border, first line spaced.
-    pub(super) fn draw_tooltip_lines(
+    pub(super) fn draw_tooltip_lines<T: Clone + Into<horizon_client::text::Text>>(
         &self,
         batch: &mut HudBatch,
-        lines: &[(String, u32)],
+        lines: &[(T, u32)],
         x: f32,
         y: f32,
     ) {
         if lines.is_empty() {
             return;
         }
+        let lines: Vec<_> = lines
+            .iter()
+            .map(|(text, color)| {
+                let text: horizon_client::text::Text = text.clone().into();
+                (text.resolve_legacy(), *color)
+            })
+            .collect();
         let atlas = &self.gui.atlas;
         let w = lines
             .iter()
-            .map(|(t, _)| HudBatch::text_width(atlas, t))
+            .map(|(t, _)| atlas.font.width_text(t))
             .fold(0.0, f32::max);
         let h = if lines.len() == 1 {
             8.0
@@ -1929,7 +1968,7 @@ impl Game<'_> {
         );
         let mut ty = y;
         for (i, (text, color)) in lines.iter().enumerate() {
-            batch.text(atlas, text, x, ty, *color, true);
+            batch.text_styled(atlas, text, x, ty, *color, true);
             ty += if i == 0 { 12.0 } else { 10.0 };
         }
     }
@@ -1946,7 +1985,12 @@ impl Game<'_> {
             let lines = self.stack_tooltip(&stack);
             self.draw_tooltip_lines(batch, &lines, self.cursor.0, self.cursor.1);
         } else if let Some(text) = self.crafter_tooltip(slot) {
-            self.draw_tooltip_lines(batch, &[(text, u32::MAX)], self.cursor.0, self.cursor.1);
+            self.draw_tooltip_lines(
+                batch,
+                &[(horizon_client::text::Text::literal(text), u32::MAX)],
+                self.cursor.0,
+                self.cursor.1,
+            );
         }
     }
 
diff --git a/crates/horizon-client/src/item_tooltip.rs b/crates/horizon-client/src/item_tooltip.rs
index ca6ff481b..6e51de391 100644
--- a/crates/horizon-client/src/item_tooltip.rs
+++ b/crates/horizon-client/src/item_tooltip.rs
@@ -487,23 +487,31 @@ pub fn lines(
 ) -> Vec<String> {
     let mut lines = vec![name_line(stack, translate)];
     if TooltipDisplay::for_stack(stack).shows("minecraft:lore") {
-        lines.extend(lore_lines(stack));
+        lines.extend(lore_texts(stack).into_iter().map(|t| t.plain()));
     }
     lines.extend(detail_lines(stack, info, translate));
     lines
 }
 
-/// `LoreComponent.addToTooltip`: the saved component lines, as plain text.
-fn lore_lines(stack: &ItemStack) -> Vec<String> {
+/// `ItemLore.addToTooltip`: each lore component under dark purple italic, with
+/// the component's own styles (including explicit `false`) winning on children.
+pub fn lore_texts(stack: &ItemStack) -> Vec<crate::text::Text> {
     let Some(Tag::List(entries)) = stack.data().and_then(|d| d.other("minecraft:lore")) else {
         return Vec::new();
     };
+    let base = crate::text::Style {
+        color: Some(crate::text::DARK_PURPLE),
+        italic: Some(true),
+        ..Default::default()
+    };
     entries
         .iter()
         .map(|entry| {
-            let json = crate::scoreboard::tag_to_json(entry);
-            let text = crate::component::to_text(&json, &mut |s| crate::text::Text::literal(s));
-            text.plain()
+            let mut text = crate::entity_nbt::name_text(entry).resolve_legacy();
+            for span in &mut text.spans {
+                span.style.inherit(&base);
+            }
+            text
         })
         .collect()
 }
@@ -512,6 +520,42 @@ fn lore_lines(stack: &ItemStack) -> Vec<String> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn lore_keeps_component_colours_under_dark_purple_italic() {
+        let mut stack = ItemStack::new("minecraft:stick", 1);
+        stack.data_mut().set_other(
+            "minecraft:lore",
+            Some(Tag::List(vec![
+                Tag::compound([
+                    ("text", Tag::String("Gold line".into())),
+                    ("color", Tag::String("gold".into())),
+                    ("italic", Tag::Byte(0)),
+                ]),
+                Tag::String("Plain lore".into()),
+            ])),
+        );
+        let lines = lore_texts(&stack);
+        assert_eq!(lines.len(), 2);
+        assert_eq!(lines[0].plain(), "Gold line");
+        assert_eq!(lines[0].spans[0].style.color, Some(crate::text::GOLD));
+        assert!(!lines[0].spans[0].style.is_italic());
+        assert_eq!(lines[1].plain(), "Plain lore");
+        assert_eq!(
+            lines[1].spans[0].style.color,
+            Some(crate::text::DARK_PURPLE)
+        );
+        assert!(lines[1].spans[0].style.is_italic());
+        assert!(TooltipDisplay::for_stack(&stack).shows("minecraft:lore"));
+        stack.data_mut().set_other(
+            "minecraft:tooltip_display",
+            Some(Tag::compound([(
+                "hidden_components",
+                Tag::List(vec![Tag::String("minecraft:lore".into())]),
+            )])),
+        );
+        assert!(!TooltipDisplay::for_stack(&stack).shows("minecraft:lore"));
+    }
+
     #[test]
     fn tooltip_display_controls_name_and_component_visibility() {
         let mut stack = ItemStack::new("minecraft:diamond_sword", 1);

From ba4cf45aacb5564ae04bce109e466c48dea9f2eb Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:35:01 +0100
Subject: [PATCH 126/270] cargo horizon-mod: content mods (new --template
 content, build packs assets and data, check takes no code)

- `new --template content`: a content mod with one block (Glowing Amethyst,
  copying vanilla's amethyst block) and its block state, model, item model,
  name, loot, recipe and pickaxe tag; `--template code` is the default.
- `build` packs the mod's `assets/` and `data/` (read and checked as the
  game reads them) beside the component; a folder without `Cargo.toml` is a
  content mod and needs no compiler.
- `check` takes a `.hmod` with no `mod.wasm`: "no code: content only,
  nothing to run" instead of the trial run, which refused it, so the
  registry can publish content mods.
- The guide (content mods, make a mod) and docs/mods.md, docs/api/mods.md
  say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/cargo-horizon-mod/src/check.rs         |  16 +-
 crates/cargo-horizon-mod/src/main.rs          | 168 +++++++++++++++---
 .../template/content/block.json               |   4 +
 .../template/content/blockstate.json          |   5 +
 .../template/content/horizon-mod.toml         |  10 ++
 .../template/content/item.json                |   3 +
 .../template/content/lang.json                |   3 +
 .../template/content/loot.json                |  11 ++
 .../template/content/model.json               |   4 +
 .../template/content/pickaxe.json             |   3 +
 .../template/content/recipe.json              |   6 +
 docs/api/mods.md                              |   3 +-
 docs/mods.md                                  |   8 +-
 website/docs/content-mods.md                  |  20 ++-
 website/docs/make-a-mod.md                    |   2 +-
 15 files changed, 233 insertions(+), 33 deletions(-)
 create mode 100644 crates/cargo-horizon-mod/template/content/block.json
 create mode 100644 crates/cargo-horizon-mod/template/content/blockstate.json
 create mode 100644 crates/cargo-horizon-mod/template/content/horizon-mod.toml
 create mode 100644 crates/cargo-horizon-mod/template/content/item.json
 create mode 100644 crates/cargo-horizon-mod/template/content/lang.json
 create mode 100644 crates/cargo-horizon-mod/template/content/loot.json
 create mode 100644 crates/cargo-horizon-mod/template/content/model.json
 create mode 100644 crates/cargo-horizon-mod/template/content/pickaxe.json
 create mode 100644 crates/cargo-horizon-mod/template/content/recipe.json

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index 0294bec98..8a25d1a24 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -21,6 +21,8 @@ pub struct Report {
     pub sha256: String,
     pub size: u64,
     pub signed: bool,
+    /// A mod has code to run (a content mod may have none).
+    pub code: bool,
     /// A mod's component imports.
     pub imports: Vec<String>,
     /// A mod's commands, each run once.
@@ -49,6 +51,7 @@ impl Report {
             "sha256": self.sha256,
             "size": self.size,
             "signed": self.signed,
+            "code": self.code,
             "imports": self.imports,
             "commands": self.commands,
             "output": self.output,
@@ -87,7 +90,9 @@ impl Report {
         for r in &f.requires {
             out += &format!("  needs {} {} ({})\n", r.id, r.version, &r.sha256[..12]);
         }
-        if self.kind == Kind::Mod {
+        if self.kind == Kind::Mod && !self.code {
+            out += "  no code: content only, nothing to run\n";
+        } else if self.kind == Kind::Mod {
             let commands = if self.commands.is_empty() {
                 String::new()
             } else {
@@ -142,6 +147,7 @@ pub fn check(
         sha256: index::sha256_file(path)?,
         size,
         signed,
+        code: false,
         imports: Vec::new(),
         commands: Vec::new(),
         output: Vec::new(),
@@ -153,10 +159,14 @@ pub fn check(
 }
 
 /// Runs a mod in the sandbox, as the game does, from a scratch copy so its
-/// storage lands in a folder removed afterwards.
+/// storage lands in a folder removed afterwards. A content mod has no code to
+/// run: `inspect` already read its content as the game does.
 fn trial_run(path: &Path, report: &mut Report) -> Result<(), String> {
     let package = Package::read(path)?;
-    let wasm = package.wasm.as_deref().ok_or("the .hmod has no mod.wasm")?;
+    let Some(wasm) = package.wasm.as_deref() else {
+        return Ok(());
+    };
+    report.code = true;
     report.imports = component_imports(wasm)?;
     package
         .manifest
diff --git a/crates/cargo-horizon-mod/src/main.rs b/crates/cargo-horizon-mod/src/main.rs
index 925633930..a4585f680 100644
--- a/crates/cargo-horizon-mod/src/main.rs
+++ b/crates/cargo-horizon-mod/src/main.rs
@@ -1,14 +1,16 @@
 //! `cargo horizon-mod`: make Horizon mods in Rust (`docs/mods.md`).
 //!
-//! - `new <path> [--name "Name"] [--sdk-path <dir>]`: a mod crate from the template.
-//! - `build [--debug]`: the `.hmod` in `target/horizon-mod/`.
+//! - `new <path> [--template code|content] [--name "Name"] [--sdk-path <dir>]`:
+//!   a mod from a template: a Rust crate, or a content mod (no code).
+//! - `build [--debug]`: the `.hmod` in `target/horizon-mod/`, with the mod's
+//!   `assets/` and `data/`; a folder without `Cargo.toml` is content only.
 //! - `run [--game <horizon-client>] [-- <game args>]`: build, then play with
 //!   the mod; run `build` again and the game reloads it.
 //! - `check <file> [--json]`: what the registry checks of a submission
 //!   (`.hmod`, `.hpack`, resource pack `.zip`), with a trial run for a mod.
 //! - `registry build|review|check|list`: the registry repository's CI.
 use horizon_mods::{
-    Manifest, Package,
+    Capability, Content, Manifest, Package,
     manifest::{MANIFEST, component_imports, componentize},
 };
 mod check;
@@ -36,7 +38,7 @@ fn main() -> ExitCode {
         Some("run") => run(&args[1..]),
         Some("check") => check(&args[1..]),
         Some("registry") => registry::main(&args[1..]),
-        _ => Err("usage: cargo horizon-mod new <path> | build [--debug] | run [--game <horizon-client>] [-- <game args>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--json] | registry build|review|check|list".into()),
+        _ => Err("usage: cargo horizon-mod new <path> [--template code|content] | build [--debug] | run [--game <horizon-client>] [-- <game args>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--json] | registry build|review|check|list".into()),
     };
     match result {
         Ok(()) => ExitCode::SUCCESS,
@@ -90,19 +92,68 @@ fn new(args: &[String]) -> Result<(), String> {
             .replace("{name}", &name)
             .replace("{sdk}", &sdk)
     };
-    let files = [
+    let code = [
         ("Cargo.toml", include_str!("../template/Cargo.toml.in")),
         (MANIFEST, include_str!("../template/horizon-mod.toml")),
         ("src/lib.rs", include_str!("../template/src/lib.rs")),
         (".gitignore", include_str!("../template/gitignore")),
     ];
-    for (file, text) in files {
+    // A block copying a vanilla one, with its model, name, loot, recipe and tag.
+    let content = [
+        (
+            MANIFEST,
+            include_str!("../template/content/horizon-mod.toml"),
+        ),
+        (
+            "data/{id}/horizon/block/glowing_amethyst.json",
+            include_str!("../template/content/block.json"),
+        ),
+        (
+            "assets/{id}/blockstates/glowing_amethyst.json",
+            include_str!("../template/content/blockstate.json"),
+        ),
+        (
+            "assets/{id}/models/block/glowing_amethyst.json",
+            include_str!("../template/content/model.json"),
+        ),
+        (
+            "assets/{id}/items/glowing_amethyst.json",
+            include_str!("../template/content/item.json"),
+        ),
+        (
+            "assets/{id}/lang/en_us.json",
+            include_str!("../template/content/lang.json"),
+        ),
+        (
+            "data/{id}/loot_table/blocks/glowing_amethyst.json",
+            include_str!("../template/content/loot.json"),
+        ),
+        (
+            "data/{id}/recipe/glowing_amethyst.json",
+            include_str!("../template/content/recipe.json"),
+        ),
+        (
+            "data/minecraft/tags/block/mineable/pickaxe.json",
+            include_str!("../template/content/pickaxe.json"),
+        ),
+        (".gitignore", include_str!("../template/gitignore")),
+    ];
+    let files: &[(&str, &str)] = match flag(args, "--template").unwrap_or("code") {
+        "code" => &code,
+        "content" => &content,
+        other => return Err(format!("no template {other}: code or content")),
+    };
+    for &(file, text) in files {
+        let file = fill(file);
+        let file = file.as_str();
         let to = dir.join(file);
         std::fs::create_dir_all(to.parent().expect("a file in the mod"))
             .map_err(|e| e.to_string())?;
         std::fs::write(&to, fill(text)).map_err(|e| format!("{}: {e}", to.display()))?;
     }
-    Manifest::parse(&std::fs::read_to_string(dir.join(MANIFEST)).map_err(|e| e.to_string())?)?;
+    let manifest =
+        Manifest::parse(&std::fs::read_to_string(dir.join(MANIFEST)).map_err(|e| e.to_string())?)?;
+    Content::read(dir, &manifest)?;
     println!(
         "Created {} (mod id {id}). Next: cd {path} && cargo horizon-mod run",
         dir.display()
@@ -110,14 +161,53 @@ fn new(args: &[String]) -> Result<(), String> {
     Ok(())
 }
 
-/// Builds the crate in the current folder and packs `target/horizon-mod/<id>.hmod`.
+/// Builds the mod in the current folder and packs `target/horizon-mod/<id>.hmod`:
+/// the manifest, the crate's component (none without a `Cargo.toml`: a
+/// content mod) and the files in `assets/` and `data/`.
 fn build(release: bool) -> Result<PathBuf, String> {
-    let manifest_text = std::fs::read_to_string(MANIFEST)
+    build_in(Path::new("."), release)
+}
+
+fn build_in(root: &Path, release: bool) -> Result<PathBuf, String> {
+    let manifest_text = std::fs::read_to_string(root.join(MANIFEST))
         .map_err(|e| format!("{MANIFEST}: {e} (run this in a mod's folder)"))?;
     let manifest = Manifest::parse(&manifest_text)?;
+    let (wasm, target_dir) = if root.join("Cargo.toml").exists() {
+        let (wasm, target) = compile(root, release)?;
+        // The game refuses a component importing capabilities the manifest lacks.
+        manifest.check_imports(component_imports(&wasm)?.iter().map(String::as_str))?;
+        (Some(wasm), target)
+    } else if manifest.capabilities.contains(&Capability::Registries) {
+        (None, root.join("target"))
+    } else {
+        return Err(format!(
+            "no Cargo.toml: only a content mod (capability registries in {MANIFEST}) has no code"
+        ));
+    };
+    // The same checks as the game's, and the files in the order it lists them.
+    let content = Content::read(root, &manifest)?;
+    let mut reader = content.reader()?;
+    let mut files = Vec::with_capacity(content.files.len());
+    for name in &content.files {
+        files.push((name.as_str(), reader.read(name)?));
+    }
+    let files: Vec<(&str, &[u8])> = files.iter().map(|(n, b)| (*n, b.as_slice())).collect();
+    let dir = target_dir.join("horizon-mod");
+    std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    let path = dir.join(format!("{}.hmod", manifest.id));
+    // Write then rename, so a running game never reads half a file.
+    let partial = path.with_extension("hmod.partial");
+    let bytes = Package::write_files(&manifest_text, wasm.as_deref(), &files)?;
+    std::fs::write(&partial, bytes).map_err(|e| e.to_string())?;
+    std::fs::rename(&partial, &path).map_err(|e| e.to_string())?;
+    Ok(path)
+}
+
+/// Builds the crate for WebAssembly: its component, and Cargo's target folder.
+fn compile(root: &Path, release: bool) -> Result<(Vec<u8>, PathBuf), String> {
     let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into());
     let mut cmd = Command::new(cargo);
-    cmd.args([
+    cmd.current_dir(root).args([
         "build",
         "--lib",
         "--target",
@@ -145,17 +235,8 @@ fn build(release: bool) -> Result<PathBuf, String> {
         .rfind(|f| f.extension().is_some_and(|e| e == "wasm"))
         .ok_or("the build made no .wasm: is the crate a cdylib?")?;
     let wasm = componentize(&std::fs::read(&core).map_err(|e| e.to_string())?)?;
-    // The game refuses a component importing capabilities the manifest lacks.
-    manifest.check_imports(component_imports(&wasm)?.iter().map(String::as_str))?;
-    let target_dir = core.ancestors().nth(3).ok_or("unexpected target folder")?;
-    let dir = target_dir.join("horizon-mod");
-    std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    let path = dir.join(format!("{}.hmod", manifest.id));
-    // Write then rename, so a running game never reads half a file.
-    let partial = path.with_extension("hmod.partial");
-    std::fs::write(&partial, Package::write(&manifest_text, &wasm)?).map_err(|e| e.to_string())?;
-    std::fs::rename(&partial, &path).map_err(|e| e.to_string())?;
-    Ok(path)
+    let target = core.ancestors().nth(3).ok_or("unexpected target folder")?;
+    Ok((wasm, target.to_path_buf()))
 }
 
 /// `check <file>`: the registry's checks of a submission, printed; fails
@@ -237,4 +318,49 @@ mod tests {
         );
         std::fs::remove_dir_all(&dir).unwrap();
     }
+
+    #[test]
+    fn the_content_template_builds_and_checks_with_no_code() {
+        let dir = std::env::temp_dir().join(format!("horizon-mod-content-{}", std::process::id()));
+        let path = dir.join("gems");
+        let new_args = [
+            path.display().to_string(),
+            "--template".into(),
+            "content".into(),
+        ];
+        new(&new_args).unwrap();
+        assert!(!path.join("Cargo.toml").exists());
+        let hmod = build_in(&path, true).unwrap();
+        assert_eq!(hmod, path.join("target/horizon-mod/gems.hmod"));
+        let package = Package::read(&hmod).unwrap();
+        assert!(package.wasm.is_none());
+        let content = Content::read(&hmod, &package.manifest).unwrap();
+        assert!(
+            content
+                .files
+                .contains(&"data/gems/horizon/block/glowing_amethyst.json".into())
+        );
+        assert_eq!(content.files.len(), 8, "{:?}", content.files);
+        let report = check::check(&hmod, check::kind_of(&hmod).unwrap(), None, None).unwrap();
+        assert!(!report.code);
+        assert!(
+            report.text().contains("no code: content only"),
+            "{}",
+            report.text()
+        );
+        // Without registries, a mod needs code.
+        let manifest = std::fs::read_to_string(path.join(MANIFEST)).unwrap();
+        let manifest = manifest.replace("[\"registries\"]", "[]");
+        std::fs::write(path.join(MANIFEST), manifest).unwrap();
+        assert!(build_in(&path, true).unwrap_err().contains("no Cargo.toml"));
+        assert!(
+            new(&[
+                dir.join("x").display().to_string(),
+                "--template".into(),
+                "lua".into()
+            ])
+            .is_err()
+        );
+        std::fs::remove_dir_all(&dir).unwrap();
+    }
 }
diff --git a/crates/cargo-horizon-mod/template/content/block.json b/crates/cargo-horizon-mod/template/content/block.json
new file mode 100644
index 000000000..ea68a1a27
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/block.json
@@ -0,0 +1,4 @@
+{
+  "template": "minecraft:amethyst_block",
+  "properties": { "hardness": 2.0, "light": 7 }
+}
diff --git a/crates/cargo-horizon-mod/template/content/blockstate.json b/crates/cargo-horizon-mod/template/content/blockstate.json
new file mode 100644
index 000000000..ea472666e
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/blockstate.json
@@ -0,0 +1,5 @@
+{
+  "variants": {
+    "": { "model": "{id}:block/glowing_amethyst" }
+  }
+}
diff --git a/crates/cargo-horizon-mod/template/content/horizon-mod.toml b/crates/cargo-horizon-mod/template/content/horizon-mod.toml
new file mode 100644
index 000000000..4f133a905
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/horizon-mod.toml
@@ -0,0 +1,10 @@
+id = "{id}"
+name = "{name}"
+version = "0.1.0"
+description = ""
+authors = []
+# A content mod: blocks and items from data/ and assets/, no code (API 0.2).
+api = "0.2"
+side = "both"
+# registries: "May add blocks and items to your worlds".
+capabilities = ["registries"]
diff --git a/crates/cargo-horizon-mod/template/content/item.json b/crates/cargo-horizon-mod/template/content/item.json
new file mode 100644
index 000000000..411bc4499
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/item.json
@@ -0,0 +1,3 @@
+{
+  "model": { "type": "minecraft:model", "model": "{id}:block/glowing_amethyst" }
+}
diff --git a/crates/cargo-horizon-mod/template/content/lang.json b/crates/cargo-horizon-mod/template/content/lang.json
new file mode 100644
index 000000000..74baddab8
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/lang.json
@@ -0,0 +1,3 @@
+{
+  "block.{id}.glowing_amethyst": "Glowing Amethyst"
+}
diff --git a/crates/cargo-horizon-mod/template/content/loot.json b/crates/cargo-horizon-mod/template/content/loot.json
new file mode 100644
index 000000000..898111f1b
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/loot.json
@@ -0,0 +1,11 @@
+{
+  "type": "minecraft:block",
+  "pools": [
+    {
+      "condition": { "type": "minecraft:survives_explosion" },
+      "entries": [{ "type": "minecraft:item", "name": "{id}:glowing_amethyst" }],
+      "rolls": 1
+    }
+  ],
+  "random_sequence": "{id}:blocks/glowing_amethyst"
+}
diff --git a/crates/cargo-horizon-mod/template/content/model.json b/crates/cargo-horizon-mod/template/content/model.json
new file mode 100644
index 000000000..5710fecb1
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/model.json
@@ -0,0 +1,4 @@
+{
+  "parent": "minecraft:block/cube_all",
+  "textures": { "all": "minecraft:block/amethyst_block" }
+}
diff --git a/crates/cargo-horizon-mod/template/content/pickaxe.json b/crates/cargo-horizon-mod/template/content/pickaxe.json
new file mode 100644
index 000000000..8725edebd
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/pickaxe.json
@@ -0,0 +1,3 @@
+{
+  "values": ["{id}:glowing_amethyst"]
+}
diff --git a/crates/cargo-horizon-mod/template/content/recipe.json b/crates/cargo-horizon-mod/template/content/recipe.json
new file mode 100644
index 000000000..5edb03d94
--- /dev/null
+++ b/crates/cargo-horizon-mod/template/content/recipe.json
@@ -0,0 +1,6 @@
+{
+  "type": "minecraft:crafting_shapeless",
+  "category": "building",
+  "ingredients": ["minecraft:amethyst_block", "minecraft:glowstone_dust"],
+  "result": { "id": "{id}:glowing_amethyst" }
+}
diff --git a/docs/api/mods.md b/docs/api/mods.md
index 3e6108c70..5c323a0e1 100644
--- a/docs/api/mods.md
+++ b/docs/api/mods.md
@@ -19,7 +19,7 @@ the player before the mod is turned on, and checked against the component's real
 | Capabilities | 5: `game-read`, `chat`, `hud`, `storage`, `registries` |
 | Manifest `api` lines served | 2: `0.1` (code), `0.2` (content) |
 | SDK | the `Mod` trait (5 methods), `Registration` (4 builders), `export_mod!`, log helpers |
-| `cargo horizon-mod` | `new`, `build`, `run` |
+| `cargo horizon-mod` | `new` (templates `code` and `content`), `build`, `run`, `check` |
 | Example mods | `coords-hud` (code), `ruby-content` (content) |
 
 ## Guide
@@ -58,6 +58,7 @@ scripting runtime in the game.
 | Way in | For | Status | Template and example |
 | --- | --- | --- | --- |
 | Rust | most mods; the fastest | first-class: the SDK, `cargo horizon-mod` | `cargo horizon-mod new`, `coords-hud` |
+| Data only | blocks and items with no code | first-class: content mods (API 0.2) | `cargo horizon-mod new --template content`, `ruby-content` |
 | Lua scripts | people who don't want a compiler | planned: a script mod whose code is a `.lua` file, run by Horizon's own interpreter mod | planned, with the same example as Rust |
 | C, C++, Zig | authors of those languages | to evaluate: bindings generated from the WIT, built without WASI | one each if it passes |
 | Go (TinyGo), AssemblyScript, JavaScript / TypeScript | authors of those languages | to evaluate: each needs its toolchain to emit a component without WASI imports, or an interpreter mod as for Lua | one each if it passes |
diff --git a/docs/mods.md b/docs/mods.md
index bac207f60..3a4473032 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -16,7 +16,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
-| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run / check`, and the registry's CI (`registry build / review / list`) |
+| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / check`, and the registry's CI (`registry build / review / list`) |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
 | Launcher mod browser (Modrinth, CurseForge with a key) | [mod-browser.md](mod-browser.md) | resource packs, modpacks |
 | Registry index (`index.json`, `.hpack`), signatures | `horizon_mods::index`, [api/mod-index.md](api/mod-index.md) | schema 1; launcher and website next |
@@ -215,6 +215,7 @@ Benchmarks (`--benchmark`) never load mods.
 rustup target add wasm32-unknown-unknown
 cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod
 cargo horizon-mod new my-mod        # Cargo.toml, horizon-mod.toml, src/lib.rs
+                                    # (--template content: a content mod, no code)
 cd my-mod
 cargo horizon-mod run               # build, then start the game with it
 cargo horizon-mod build             # again after an edit: the running game reloads it
@@ -292,7 +293,10 @@ permission.
 ### Content mods (API 0.2)
 
 A mod with `api = "0.2"` and capability `registries` may carry `assets/` and
-`data/` in the `.hmod`, and needs no `mod.wasm` if it has no code. It adds
+`data/` in the `.hmod`, and needs no `mod.wasm` if it has no code
+(`cargo horizon-mod new --template content` starts one; `build` in a folder
+with no `Cargo.toml` packs the manifest, `assets/` and `data/`, and `check`
+reads it without a trial run). It adds
 blocks and items by declaring them in `data/<id>/horizon/block/*.json` and
 `data/<id>/horizon/item/*.json`, each copying a vanilla template
 ([modpacks.md](modpacks.md#registries-02-data-driven-blocks-and-items)):
diff --git a/website/docs/content-mods.md b/website/docs/content-mods.md
index 1ad8cd5fb..9504bceb6 100644
--- a/website/docs/content-mods.md
+++ b/website/docs/content-mods.md
@@ -4,7 +4,7 @@ A content mod adds blocks and items to the game with data files only: no Rust, n
 
 ## What a content mod is
 
-A folder (while you work on it) or a `.hmod` zip (to share it) holding a manifest, `assets/` and `data/`. This is the SDK's [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) example, a ruby gem and a block of ruby:
+A folder (while you work on it) or a `.hmod` file (to share it) holding a manifest, `assets/` and `data/`. This is the SDK's [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) example, a ruby gem and a block of ruby:
 
 ```
 ruby/
@@ -98,17 +98,27 @@ A mod made from a Java mod whose files use other names lists them in its manifes
 - Unknown keys in a block or item file are refused, and the mod stays off with the reason on its row.
 - Content mods work in single player today. Playing them together on a server is planned.
 
+## Start one
+
+```sh
+cargo horizon-mod new my-blocks --template content
+```
+
+makes a content mod with one block, Glowing Amethyst: an amethyst block that gives light, with its block state, model (using vanilla's amethyst texture), item model, name, loot table, a recipe (an amethyst block and glowstone dust) and the pickaxe tag. Rename and copy its files to add your own.
+
 ## Try it and share it
 
 While you work, give the game the folder as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)): `--dev-mod "/path/to/ruby"`. The first start with a new set of mods takes a little longer while the game adds their content to its tables; after a change to the files, start the game again.
 
-To share it, zip the folder's contents, with `horizon-mod.toml` at the top of the zip, and name the file `<id>.hmod`:
+To share it, build the `.hmod` in the mod's folder:
 
 ```sh
-cd ruby
-zip -r ../ruby.hmod horizon-mod.toml assets data
+cargo horizon-mod build
+cargo horizon-mod check target/horizon-mod/ruby.hmod
 ```
 
-Players put that file in their `horizon-mods` folder and turn it on in **Options, Mods...**. The registry doesn't take content-only mods yet: its checks (`cargo horizon-mod check`) expect code in the file. That is coming next.
+A folder without a `Cargo.toml` is a content mod: `build` checks its files as the game will and packs the manifest, `assets/` and `data/` into `target/horizon-mod/<id>.hmod`, with no compiler involved. `check` reads it as the registry does and says "no code: content only, nothing to run". Players put that file in their `horizon-mods` folder and turn it on in **Options, Mods...**, and you can [publish it](/docs/publish-a-mod) like any mod.
+
+A mod can have both: a `Cargo.toml` with code, and `assets/` and `data/` with content. `build` packs both.
 
 Next: [test it](/docs/test-a-mod).
diff --git a/website/docs/make-a-mod.md b/website/docs/make-a-mod.md
index 94c3deca2..89f2d8bcd 100644
--- a/website/docs/make-a-mod.md
+++ b/website/docs/make-a-mod.md
@@ -41,7 +41,7 @@ cargo horizon-mod new my-mod
 cd my-mod
 ```
 
-`new` makes a folder with a working mod in it: a `/hello` command that answers in chat. `--name "My Mod"` sets the name players see. The folder holds:
+`new` makes a folder with a working mod in it: a `/hello` command that answers in chat. `--name "My Mod"` sets the name players see, and `--template content` makes a [content mod](/docs/content-mods) instead, with no code. The folder holds:
 
 ```
 my-mod/

From c6405610008b0c779ffe281a6cdab34c67f9199a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:56:26 +0100
Subject: [PATCH 127/270] Launcher: the registry pack tests build file URLs
 with forward slashes, so they pass on Windows

A Windows temp path's backslashes went into the test index's JSON as escapes, so the
index failed to parse and the Windows launcher release stopped at its tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/browser/horizon/pack.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/launcher/src/browser/horizon/pack.rs b/launcher/src/browser/horizon/pack.rs
index 73dcd0cc1..a2cc4d079 100644
--- a/launcher/src/browser/horizon/pack.rs
+++ b/launcher/src/browser/horizon/pack.rs
@@ -208,6 +208,8 @@ mod tests {
         zip.write_all(b"renderDistance:8\n").unwrap();
         zip.finish().unwrap();
         let size = |p: &Path| fs::metadata(p).unwrap().len();
+        // Forward slashes: a Windows path's backslashes would be escapes in the JSON.
+        let url = |p: &Path| p.display().to_string().replace('\\', "/");
         let text = format!(
             r#"{{"schema": 1, "projects": [
               {{"id": "coords_hud", "kind": "mod", "name": "Coordinates HUD", "summary": "", "license": "MIT",
@@ -219,9 +221,9 @@ mod tests {
                 "requires": [{{"id": "coords_hud", "version": "0.1.0", "sha256": "{hmod_sha}"}}],
                 "file": {{"name": "cozy-1.0.0.hpack", "url": "file://{}", "size": {}, "sha256": "{}"}}}}]}}
             ]{extra}}}"#,
-            hmod.display(),
+            url(&hmod),
             size(&hmod),
-            hpack.display(),
+            url(&hpack),
             size(&hpack),
             idx::sha256_file(&hpack).unwrap()
         );

From af7a685b5c5871764b9c7b16d948b04dd2cdb867 Mon Sep 17 00:00:00 2001
From: socksprox <socksprox@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:09:25 +0100
Subject: [PATCH 128/270] =?UTF-8?q?Mod=20API:=20capability=20`ui`=20?=
 =?UTF-8?q?=E2=80=94=20mod-owned=20screens=20and=20settings=20pages?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New WIT interface `ui` (text, item and list widgets; open-screen,
close-screen, set-settings) plus a `ui-events` export (select, closed,
settings-opened), in a second world `horizon-ui-mod` so mods built before
it keep loading. The game lays out and draws the widgets with its own
menus' code: a screen the mod owns (Esc/Done to leave) and a Settings
button on the mod's Options > Mods row that opens its page.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 AGENTS.md                                     |   2 +-
 Cargo.lock                                    |   7 +
 Cargo.toml                                    |   2 +-
 crates/horizon-client/src/game.rs             |  11 +
 crates/horizon-client/src/game/agent.rs       |   1 +
 crates/horizon-client/src/game/control.rs     |   1 +
 crates/horizon-client/src/game/mods.rs        | 336 +++++++++++++++++-
 crates/horizon-client/src/game/options.rs     |   1 +
 crates/horizon-client/src/game/screens.rs     |   3 +-
 .../horizon-client/src/game/startup_menu.rs   |   2 +
 crates/horizon-client/src/mod_list.rs         |   4 +
 crates/horizon-client/src/options_ui.rs       |  40 ++-
 crates/horizon-mod-sdk/src/lib.rs             |  36 +-
 crates/horizon-mod-sdk/wit/horizon.wit        |  92 +++++
 crates/horizon-mods/src/manifest.rs           |   9 +-
 crates/horizon-mods/src/runtime.rs            | 200 ++++++++++-
 crates/horizon-mods/tests/sandbox.rs          |  49 +++
 crates/horizon-mods/tests/ui_guest/Cargo.toml |  16 +
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  66 ++++
 docs/api/mods-reference.md                    |  88 +++++
 docs/mods.md                                  |   4 +-
 21 files changed, 936 insertions(+), 34 deletions(-)
 create mode 100644 crates/horizon-mods/tests/ui_guest/Cargo.toml
 create mode 100644 crates/horizon-mods/tests/ui_guest/src/lib.rs

diff --git a/AGENTS.md b/AGENTS.md
index a72c6723a..2d883b33b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,7 +82,7 @@ python3 tools/agent_control_e2e.py         # horizon-ctl / MCP end to end
   ~25, a file of the client lib ~103, of `horizon-world` ~103–109, of `horizon-core` ~119. Plan for it.
 - Rust integration tests: `crates/horizon-client/tests/` (`lan_bot.rs`, `generation_saves.rs`, `streaming_meshes.rs`).
 - **macOS:** `cargo build/test --workspace` may fail to link the two wasm guest cdylibs (undefined
-  `horizon:mods/events` symbols) until #1446 lands: add `--exclude coords-hud --exclude horizon-mods-test-guest`.
+  `horizon:mods/events` symbols) until #1446 lands: add `--exclude coords-hud --exclude horizon-mods-test-guest --exclude horizon-mods-test-ui-guest`.
   Their real check is `cargo test -p horizon-mods` (builds them for `wasm32-unknown-unknown`).
 - Linux needs `libasound2-dev libudev-dev`; `--no-default-features` drops audio and controllers (the server build).
 - Run and drive the game (starts the `horizon-client` beside `horizon-ctl`; other arguments go to the game):
diff --git a/Cargo.lock b/Cargo.lock
index 70c3c831c..6945e09cf 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1352,6 +1352,13 @@ dependencies = [
  "horizon-mod-sdk",
 ]
 
+[[package]]
+name = "horizon-mods-test-ui-guest"
+version = "0.1.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "horizon-port-pack"
 version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 294e93aa9..4076b9079 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..eabbc22b8 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -482,6 +482,9 @@ enum Screen {
     CommandBlock,
     /// WinScreen: the end poem and the credits (game/win.rs).
     Win,
+    /// A `ui` mod's own screen, or its settings page from Options > Mods
+    /// (game/mods.rs).
+    Mod,
 }
 struct Mining {
     pos: [i32; 3],
@@ -5047,6 +5050,7 @@ impl Game<'_> {
                 self.draw_creative(&mut batch);
             }
             Screen::Chat => self.draw_chat_screen(&mut batch),
+            Screen::Mod => self.draw_mod_screen(&mut batch),
             Screen::Playing | Screen::Options | Screen::Win => {}
         }
         self.draw_toasts(&mut batch);
@@ -10363,6 +10367,7 @@ impl Game<'_> {
                 Screen::CommandBlock => self.close_command_block(),
                 Screen::Chat => self.close_chat(),
                 Screen::Win => self.close_win_screen()?,
+                Screen::Mod => self.close_mod_screen(true),
             },
             KeyCode::Digit1
             | KeyCode::Digit2
@@ -11009,6 +11014,9 @@ impl ApplicationHandler for Game<'_> {
                     if self.screen == Screen::Options && d != 0.0 {
                         self.options_scroll(d);
                     }
+                    if self.screen == Screen::Mod && d != 0.0 {
+                        self.mod_screen_scroll(d);
+                    }
                     if self.screen == Screen::Creative && d != 0.0 {
                         self.creative_screen.wheel(f64::from(d), &self.pack.names);
                     }
@@ -11231,6 +11239,9 @@ impl ApplicationHandler for Game<'_> {
                                 .map_or([1, 1], |r| [r.config.width, r.config.height]);
                             self.stats_click(size);
                         }
+                        Screen::Mod if pressed && button == MouseButton::Left => {
+                            self.mod_screen_click()
+                        }
                         _ => {}
                     }
                 }
diff --git a/crates/horizon-client/src/game/agent.rs b/crates/horizon-client/src/game/agent.rs
index f6b68aa74..bed331c32 100644
--- a/crates/horizon-client/src/game/agent.rs
+++ b/crates/horizon-client/src/game/agent.rs
@@ -416,6 +416,7 @@ impl Game<'_> {
             Screen::Friends => "friends",
             Screen::CommandBlock => "command-block",
             Screen::Win => "win",
+            Screen::Mod => "mod",
         }
     }
     pub(super) fn inventory_counts(&self) -> BTreeMap<String, i64> {
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index a0d8987d8..ffe05b518 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -799,6 +799,7 @@ impl Game<'_> {
             Screen::Friends => "friends",
             Screen::CommandBlock => "command-block",
             Screen::Win => "win",
+            Screen::Mod => "mod",
         }
     }
 
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 572f9fe2b..688e29da1 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -20,10 +20,13 @@ use {
     horizon_client::{
         extras::Corner,
         extras_hud,
+        items::ItemStack,
         mod_list::Installed,
+        options_ui::Page,
         text::{self, Text},
+        ui,
     },
-    horizon_mods::{Clock, Mods, Output, Player, Snapshot, Status},
+    horizon_mods::{Clock, Mods, Output, Player, Snapshot, Status, UiScreen, UiWidget},
     std::time::Instant,
 };
 
@@ -39,6 +42,23 @@ pub(super) struct ModsState {
     /// The chat's command tree while a running mod owns commands.
     #[cfg(feature = "mods")]
     tree: Option<Dispatcher>,
+    /// A `ui` mod's screen or settings page while it is up.
+    #[cfg(feature = "mods")]
+    screen: Option<ModScreen>,
+}
+
+/// A `ui` mod's own screen, or its settings page from Options > Mods: the
+/// widgets the mod pushed, laid out and drawn with the menus' own widgets.
+#[cfg(feature = "mods")]
+struct ModScreen {
+    /// The running mod's index in `mods.mods.entries()`.
+    owner: usize,
+    /// Opened from Options > Mods: Done and Esc return there.
+    settings: bool,
+    /// What the mod's screen replaced (Playing, Chat, ...), to restore.
+    under: Screen,
+    /// One scroll per `list` widget, in widget order.
+    scrolls: Vec<ui::Scroll>,
 }
 impl ModsState {
     /// The chat's command tree: vanilla's, plus the running mods' commands.
@@ -166,6 +186,11 @@ impl Game<'_> {
     }
     pub(super) fn mods_chat(&mut self, _line: &str) {}
     pub(super) fn draw_mod_panels(&self, _batch: &mut HudBatch, _corners: &mut Corners) {}
+    pub(super) fn open_mod_screen(&mut self, _owner: usize, _settings: bool) {}
+    pub(super) fn close_mod_screen(&mut self, _tell: bool) {}
+    pub(super) fn draw_mod_screen(&mut self, _batch: &mut HudBatch) {}
+    pub(super) fn mod_screen_click(&mut self) {}
+    pub(super) fn mod_screen_scroll(&mut self, _delta: f32) {}
 }
 
 #[cfg(feature = "mods")]
@@ -187,6 +212,8 @@ impl Game<'_> {
         let on = |id: &str| enabled.contains(id) || dev_ids.iter().any(|d| d == id);
         let mods = Mods::load(&paths, on, vanilla_command);
         self.mods.mods = mods;
+        // Entries were replaced wholesale: a screen's owner index is stale.
+        self.mods.screen = None;
         self.list_mods();
         self.sync_mod_commands();
         self.show_mod_output();
@@ -212,6 +239,7 @@ impl Game<'_> {
                         description: String::new(),
                         problem,
                         dev: false,
+                        has_settings: false,
                     };
                 };
                 // What it may do first: the row cuts long descriptions.
@@ -227,6 +255,7 @@ impl Game<'_> {
                     description: format!("{may} {}", m.description).trim().to_owned(),
                     problem,
                     dev: dev.contains(&e.path),
+                    has_settings: e.has_ui_settings(),
                 }
             })
             .collect();
@@ -343,10 +372,22 @@ impl Game<'_> {
                 Output::Feedback { text, error: false } => Text::literal(text),
                 Output::Feedback { text, error: true } => Text::literal(text).with_color(text::RED),
                 Output::Stopped { name, reason } => {
+                    // Its screen goes with it: the entry's run is gone, so
+                    // `mod_ui_view` finds no widgets and the screen closes.
                     self.list_mods();
                     self.sync_mod_commands();
                     Text::literal(format!("Mod {name} stopped: {reason}")).with_color(text::RED)
                 }
+                Output::OpenScreen { owner } => {
+                    self.open_mod_screen(owner, false);
+                    continue;
+                }
+                Output::CloseScreen { owner } => {
+                    if self.mods.screen.as_ref().is_some_and(|s| s.owner == owner) {
+                        self.close_mod_screen(false);
+                    }
+                    continue;
+                }
             };
             // Not through system_message: a mod must not hear its own lines.
             let focused = self.screen == Screen::Chat;
@@ -376,4 +417,297 @@ impl Game<'_> {
             extras_hud::draw_lines(batch, &self.gui.atlas, corners, corner, &lines);
         }
     }
+
+    /// A `ui` screen's title and widgets as the mod last pushed them; None
+    /// when the surface is gone (the mod stopped or closed it).
+    fn mod_ui_view(&self) -> Option<(String, Vec<UiWidget>)> {
+        let ms = self.mods.screen.as_ref()?;
+        if ms.settings {
+            let widgets = self.mods.mods.settings_widgets(ms.owner);
+            if widgets.is_empty() {
+                return None;
+            }
+            let name = self
+                .mods
+                .mods
+                .entries()
+                .get(ms.owner)
+                .and_then(|e| e.manifest.as_ref())
+                .map_or("Mod", |m| m.name.as_str());
+            Some((name.to_string(), widgets.to_vec()))
+        } else {
+            let s: &UiScreen = self.mods.mods.screen(ms.owner)?;
+            Some((s.title.clone(), s.widgets.clone()))
+        }
+    }
+    /// The layout the mod screen's widgets get at `h`: (widget, top,
+    /// height), the column being `COLUMN` wide down the middle.
+    fn mod_ui_layout(&self, h: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
+        let mut out = Vec::with_capacity(widgets.len());
+        let mut y = MOD_UI_TOP;
+        for w in widgets {
+            let wh = match w {
+                UiWidget::Text(_) => 12.0,
+                UiWidget::Item(_) => 20.0,
+                UiWidget::List(l) => (l.rows.len().min(6) as f32 * 12.0) + 8.0,
+            };
+            // Nothing may cover Done; a crowded mod loses what won't fit.
+            if y + wh > h - 34.0 {
+                break;
+            }
+            out.push((y, wh));
+            y += wh + 6.0;
+        }
+        out
+    }
+    /// A mod pushes its screen (`ui.open-screen`), or Options > Mods opens
+    /// its settings page (`settings`, the mod's `installed` index).
+    pub(super) fn open_mod_screen(&mut self, owner: usize, settings: bool) {
+        if self.title.is_some() {
+            return;
+        }
+        if settings {
+            self.mods.mods.ui_settings_opened(owner);
+            if self.mods.mods.settings_widgets(owner).is_empty() {
+                self.show_mod_output();
+                return;
+            }
+        }
+        self.mods.screen = Some(ModScreen {
+            owner,
+            settings,
+            under: self.screen,
+            scrolls: Vec::new(),
+        });
+        self.screen = Screen::Mod;
+        if self.player.is_some() {
+            self.capture(false);
+        }
+        self.show_mod_output();
+    }
+    /// Leaves the mod screen: back to Options for a settings page, to what
+    /// it covered for a mod's own. `tell` is Esc/Done, heard as `closed`.
+    pub(super) fn close_mod_screen(&mut self, tell: bool) {
+        let Some(ms) = self.mods.screen.take() else {
+            return;
+        };
+        if ms.settings {
+            self.open_options_at(self.options_from_title, Page::Mods);
+        } else {
+            self.screen = ms.under;
+            if self.screen == Screen::Playing && self.player.is_some() {
+                self.capture(true);
+            }
+        }
+        if tell {
+            self.mods.mods.ui_closed(ms.owner);
+            self.show_mod_output();
+        }
+    }
+    /// The mod's screen or settings page: its title over widgets stacked
+    /// down the middle, a Done button, Esc to leave (vanilla's menus).
+    pub(super) fn draw_mod_screen(&mut self, batch: &mut HudBatch) {
+        if self.mods.screen.is_none() {
+            self.screen = Screen::Playing;
+            return;
+        }
+        let Some((title, widgets)) = self.mod_ui_view() else {
+            self.mods.screen = None;
+            self.screen = Screen::Playing;
+            return;
+        };
+        // Item icons draw in a second pass: `draw_item` needs `&mut self`,
+        // so `atlas` may not stay borrowed across it.
+        let mut items: Vec<(String, f32, f32)> = Vec::new();
+        let atlas = &self.gui.atlas;
+        let in_world = self.player.is_some();
+        ui::menu_background(batch, &atlas, 0.0, 0.0, batch.width, batch.height, in_world);
+        ui::centered_text(
+            batch,
+            &atlas,
+            &Text::literal(title),
+            0.0,
+            15.0,
+            batch.width,
+            u32::MAX,
+        );
+        let cx = (batch.width / 2.0).floor();
+        let x = cx - MOD_UI_COLUMN / 2.0;
+        let layout = self.mod_ui_layout(batch.height, &widgets);
+        let mut list_i = 0usize;
+        for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
+            match w {
+                UiWidget::Text(t) => {
+                    let color = if t.color == 0 {
+                        u32::MAX
+                    } else {
+                        t.color | 0xFF00_0000
+                    };
+                    ui::centered_text(
+                        batch,
+                        &atlas,
+                        &Text::literal(t.text.clone()),
+                        x,
+                        wy + 1.0,
+                        MOD_UI_COLUMN,
+                        color,
+                    );
+                }
+                UiWidget::Item(i) => {
+                    if self.res.items().get(&i.item).is_some() {
+                        items.push((i.item.clone(), x + 2.0, wy + 2.0));
+                    } else {
+                        batch.text(&atlas, "?", x + 6.0, wy + 6.0, u32::MAX, true);
+                    }
+                    let name = if i.name.is_empty() {
+                        i.item.rsplit(':').next().unwrap_or(&i.item).to_string()
+                    } else {
+                        i.name.clone()
+                    };
+                    batch.text_styled(
+                        &atlas,
+                        &Text::literal(name),
+                        x + 22.0,
+                        wy + 6.0,
+                        u32::MAX,
+                        true,
+                    );
+                }
+                UiWidget::List(l) => {
+                    let scroll = {
+                        let ms = self.mods.screen.as_mut().expect("checked");
+                        ms.scrolls.resize_with(list_i + 1, ui::Scroll::default);
+                        ms.scrolls[list_i]
+                    };
+                    list_i += 1;
+                    let rows_top = wy + 4.0;
+                    let rows_bottom = wy + wh - 4.0;
+                    batch.fill(&atlas, x, wy, MOD_UI_COLUMN, wh, 0x8000_0000);
+                    for (b, yy) in [(x, wy), (x, wy + wh - 1.0)] {
+                        batch.fill(&atlas, b, yy, MOD_UI_COLUMN, 1.0, 0xFF50_5050);
+                    }
+                    for (xx, yy) in [(x, wy), (x + MOD_UI_COLUMN - 1.0, wy)] {
+                        batch.fill(&atlas, xx, yy, 1.0, wh, 0xFF50_5050);
+                    }
+                    let content = l.rows.len() as f32 * 12.0;
+                    let first = (scroll.amount / 12.0) as usize;
+                    let last = (first + ((rows_bottom - rows_top) / 12.0).ceil() as usize + 1)
+                        .min(l.rows.len());
+                    for (vi, ri) in (first..last).enumerate() {
+                        let ry = rows_top + vi as f32 * 12.0 - (scroll.amount % 12.0);
+                        if ui::hovered(self.cursor, x, ry, MOD_UI_COLUMN - 6.0, 12.0) {
+                            batch.fill(&atlas, x + 1.0, ry, MOD_UI_COLUMN - 8.0, 12.0, 0x20FF_FFFF);
+                        }
+                        if l.selected == Some(ri as u32) {
+                            batch.fill(&atlas, x + 1.0, ry, 3.0, 12.0, 0xFFFF_FFFF);
+                        }
+                        batch.text_styled(
+                            &atlas,
+                            &Text::literal(l.rows[ri].clone()),
+                            x + 6.0,
+                            ry + 2.0,
+                            u32::MAX,
+                            true,
+                        );
+                    }
+                    ui::scrollbar(
+                        batch,
+                        &atlas,
+                        x + MOD_UI_COLUMN - 5.0,
+                        rows_top,
+                        rows_bottom,
+                        content,
+                        scroll.amount,
+                    );
+                }
+            }
+        }
+        let hover = ui::hovered(self.cursor, cx - 100.0, batch.height - 27.0, 200.0, 20.0);
+        ui::button(
+            batch,
+            &atlas,
+            cx - 100.0,
+            batch.height - 27.0,
+            200.0,
+            20.0,
+            &Text::literal("Done"),
+            true,
+            hover,
+        );
+        for (id, ix, iy) in items {
+            let stack = ItemStack::new(id.as_str(), 1);
+            self.draw_item(batch, &stack, ix, iy);
+        }
+    }
+    /// A click on the mod screen: Done leaves it, a `list` row is the mod's
+    /// `ui-events::select`.
+    pub(super) fn mod_screen_click(&mut self) {
+        let (w, h) = self.gui_size();
+        let cursor = self.cursor;
+        if ui::hovered(cursor, (w / 2.0).floor() - 100.0, h - 27.0, 200.0, 20.0) {
+            self.audio.play_button_click();
+            self.close_mod_screen(true);
+            return;
+        }
+        let Some((_, widgets)) = self.mod_ui_view() else {
+            return;
+        };
+        let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
+        let layout = self.mod_ui_layout(h, &widgets);
+        let mut list_i = 0usize;
+        for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
+            let UiWidget::List(l) = w else { continue };
+            let scroll = self
+                .mods
+                .screen
+                .as_ref()
+                .and_then(|ms| ms.scrolls.get(list_i).copied())
+                .unwrap_or_default();
+            list_i += 1;
+            let row = ((cursor.1 - (wy + 4.0) + scroll.amount) / 12.0) as i64;
+            if ui::hovered(cursor, x + 1.0, wy + 1.0, MOD_UI_COLUMN - 7.0, wh - 2.0)
+                && row >= 0
+                && (row as usize) < l.rows.len()
+            {
+                self.audio.play_button_click();
+                self.mods.mods.ui_select(
+                    self.mods.screen.as_ref().map_or(0, |ms| ms.owner),
+                    l.id,
+                    row as u32,
+                );
+                self.show_mod_output();
+                return;
+            }
+        }
+    }
+    /// The wheel over a `list` scrolls it.
+    pub(super) fn mod_screen_scroll(&mut self, delta: f32) {
+        let (w, h) = self.gui_size();
+        let cursor = self.cursor;
+        let Some((_, widgets)) = self.mod_ui_view() else {
+            return;
+        };
+        let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
+        let layout = self.mod_ui_layout(h, &widgets);
+        let mut list_i = 0usize;
+        for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
+            let UiWidget::List(l) = w else { continue };
+            let over = ui::hovered(cursor, x, wy, MOD_UI_COLUMN, wh);
+            let Some(ms) = self.mods.screen.as_mut() else {
+                return;
+            };
+            ms.scrolls.resize_with(list_i + 1, ui::Scroll::default);
+            if over {
+                let content = l.rows.len() as f32 * 12.0;
+                ms.scrolls[list_i].wheel(delta, 12.0, wy + 4.0, wy + wh - 4.0, content);
+                return;
+            }
+            list_i += 1;
+        }
+    }
 }
+
+#[cfg(feature = "mods")]
+const MOD_UI_TOP: f32 = 40.0;
+#[cfg(feature = "mods")]
+const MOD_UI_COLUMN: f32 = 200.0;
diff --git a/crates/horizon-client/src/game/options.rs b/crates/horizon-client/src/game/options.rs
index d947f91d0..812c9ce07 100644
--- a/crates/horizon-client/src/game/options.rs
+++ b/crates/horizon-client/src/game/options.rs
@@ -237,6 +237,7 @@ impl Game<'_> {
                     let _ = std::fs::create_dir_all(&dir);
                     super::packs::open_folder(&dir);
                 }
+                Event::ModSettings(i) => self.open_mod_screen(i, true),
                 Event::Credits => self.open_win_screen(false, super::win::Finish::Options),
             }
         }
diff --git a/crates/horizon-client/src/game/screens.rs b/crates/horizon-client/src/game/screens.rs
index cf1f3269f..44f3fbd51 100644
--- a/crates/horizon-client/src/game/screens.rs
+++ b/crates/horizon-client/src/game/screens.rs
@@ -17,7 +17,8 @@ impl Screen {
             | Self::Stats
             | Self::Advancements
             | Self::WorldOptions
-            | Self::Friends => true,
+            | Self::Friends
+            | Self::Mod => true,
             Self::Playing
             | Self::GameModeSwitcher
             | Self::Chat
diff --git a/crates/horizon-client/src/game/startup_menu.rs b/crates/horizon-client/src/game/startup_menu.rs
index 96af99bbc..94771f9ac 100644
--- a/crates/horizon-client/src/game/startup_menu.rs
+++ b/crates/horizon-client/src/game/startup_menu.rs
@@ -381,6 +381,8 @@ impl Loading {
                         self.menu.win = Some((screen, Instant::now()));
                     }
                 }
+                // Mods' settings pages open only in a running game.
+                Event::ModSettings(_) => {}
                 // The startup menu runs before the game opens a control socket.
                 Event::ButtonClick | Event::CopyAgentDetails => {}
             }
diff --git a/crates/horizon-client/src/mod_list.rs b/crates/horizon-client/src/mod_list.rs
index ba3d93cda..db2ea9194 100644
--- a/crates/horizon-client/src/mod_list.rs
+++ b/crates/horizon-client/src/mod_list.rs
@@ -26,6 +26,9 @@ pub struct Installed {
     pub problem: Option<String>,
     /// Loaded with `--dev-mod`: always on, reloaded when rebuilt.
     pub dev: bool,
+    /// The running mod set a page of widgets (capability `ui`): its row
+    /// gains a Settings button.
+    pub has_settings: bool,
 }
 
 impl ModList {
@@ -96,6 +99,7 @@ mod tests {
             description: String::new(),
             problem: None,
             dev,
+            has_settings: false,
         };
         let mut list = ModList {
             installed: vec![installed("a", false), installed("b", true)],
diff --git a/crates/horizon-client/src/options_ui.rs b/crates/horizon-client/src/options_ui.rs
index 0bc1e933d..1d1f099eb 100644
--- a/crates/horizon-client/src/options_ui.rs
+++ b/crates/horizon-client/src/options_ui.rs
@@ -893,6 +893,9 @@ enum Act {
     ResetPadKey(&'static str),
     ResetPadKeys,
     ToggleMod(usize),
+    /// The installed mod's own settings page (capability `ui`), shown as a
+    /// screen: `Event::ModSettings` has the game open it.
+    ModSettings(usize),
     OpenModFolder,
     /// Credits & Attribution's Credits button (WinScreen without the poem).
     Credits,
@@ -944,6 +947,9 @@ pub enum Event {
     Packs(Vec<String>),
     OpenPackFolder,
     OpenModFolder,
+    /// Open the mod's own settings page (capability `ui`): the installed
+    /// mod's index in `mods.installed`.
+    ModSettings(usize),
     /// Roll the credits (`CreditsAndAttributionScreen.openCreditsScreen`).
     Credits,
     /// Copy how an agent connects (the AI Agent page).
@@ -1503,15 +1509,26 @@ impl OptionsUi {
                         } else if installed.dev {
                             label = label.append(" (Dev)");
                         }
-                        let widget = button(0.0, 0.0, 310.0, label, Act::ToggleMod(i));
-                        Row::Buttons(
-                            if installed.dev || installed.id.is_empty() {
-                                inactive(widget)
-                            } else {
-                                widget
-                            },
-                            None,
-                        )
+                        let dead = installed.dev || installed.id.is_empty();
+                        // A running mod with a settings page (capability
+                        // `ui`) gets its own button beside the toggle.
+                        if installed.has_settings {
+                            let toggle = button(0.0, 0.0, 150.0, label, Act::ToggleMod(i));
+                            let settings = button(
+                                0.0,
+                                0.0,
+                                150.0,
+                                Text::literal("Settings"),
+                                Act::ModSettings(i),
+                            );
+                            Row::Buttons(
+                                if dead { inactive(toggle) } else { toggle },
+                                Some(settings),
+                            )
+                        } else {
+                            let widget = button(0.0, 0.0, 310.0, label, Act::ToggleMod(i));
+                            Row::Buttons(if dead { inactive(widget) } else { widget }, None)
+                        }
                     })
                     .collect()
             }
@@ -2498,6 +2515,10 @@ impl OptionsUi {
                             s.mods.toggle(i);
                             events.push(Event::Changed);
                         }
+                        Act::ModSettings(i) => {
+                            events.push(Event::ButtonClick);
+                            events.push(Event::ModSettings(i));
+                        }
                         Act::OpenModFolder => events.push(Event::OpenModFolder),
                         Act::Credits => events.push(Event::Credits),
                         Act::CopyAgentDetails => events.push(Event::CopyAgentDetails),
@@ -2988,6 +3009,7 @@ mod tests {
                 description: "May show HUD panels.".into(),
                 problem: id.is_empty().then(|| "Invalid package".into()),
                 dev,
+                has_settings: false,
             });
         }
         let (widgets, ..) = ui.layout(&s, size.0, size.1);
diff --git a/crates/horizon-mod-sdk/src/lib.rs b/crates/horizon-mod-sdk/src/lib.rs
index 71c36cf80..aea52339f 100644
--- a/crates/horizon-mod-sdk/src/lib.rs
+++ b/crates/horizon-mod-sdk/src/lib.rs
@@ -21,18 +21,24 @@
 //! ```
 //!
 //! Every interface but `log` is a capability: list the ones the mod uses in
-//! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`).
+//! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`, `ui`).
+//!
+//! Widgets (capability `ui`): a mod shows a screen it owns with
+//! [`ui::open_screen`] and a page in Options > Mods with
+//! [`ui::set_settings`]; what the player does with them comes back as
+//! [`Mod::ui_select`], [`Mod::ui_closed`] and [`Mod::ui_settings_opened`].
 
 wit_bindgen::generate!({
     path: "wit",
-    world: "horizon-mod",
+    world: "horizon-ui-mod",
     pub_export_macro: true,
     export_macro_name: "__export_horizon_mod",
     default_bindings_module: "horizon_mod_sdk",
 });
 
 pub use exports::horizon::mods::events::{Guest as __Guest, Registration};
-pub use horizon::mods::{chat, game, hud, log, storage};
+pub use exports::horizon::mods::ui_events::Guest as __UiEventsGuest;
+pub use horizon::mods::{chat, game, hud, log, storage, ui};
 
 /// The game's calls into a mod. Only the hooks [`Registration`] asks for
 /// are called; the others may stay as their defaults.
@@ -51,6 +57,14 @@ pub trait Mod: Sized + 'static {
     }
     /// A chat line the player received, when [`Registration::chat`] is set.
     fn chat(&mut self, _text: &str) {}
+    /// A row of one of the mod's `list` widgets was picked (capability
+    /// `ui`): the widget's `id` and the row.
+    fn ui_select(&mut self, _id: u32, _row: u32) {}
+    /// The player left the mod's screen (Esc or Done; capability `ui`).
+    fn ui_closed(&mut self) {}
+    /// The player opened the mod's settings page (capability `ui`): call
+    /// [`ui::set_settings`] for fresh widgets.
+    fn ui_settings_opened(&mut self) {}
 }
 
 impl Registration {
@@ -135,13 +149,27 @@ macro_rules! export_mod {
                     with(|m| $crate::Mod::chat(m, &text))
                 }
             }
+            impl $crate::__UiEventsGuest for Export {
+                fn select(id: u32, row: u32) {
+                    with(|m| $crate::Mod::ui_select(m, id, row))
+                }
+                fn closed() {
+                    with(|m| $crate::Mod::ui_closed(m))
+                }
+                fn settings_opened() {
+                    with(|m| $crate::Mod::ui_settings_opened(m))
+                }
+            }
             // Only WebAssembly has the component's exports: a host build (cargo test or
             // clippy on the workspace) checks the mod without them, which macOS
             // couldn't link (its exported-symbols list cuts names at the `#`).
             #[cfg(target_arch = "wasm32")]
             $crate::__export_horizon_mod!(Export);
             #[cfg(not(target_arch = "wasm32"))]
-            let _ = <Export as $crate::__Guest>::init;
+            let _ = (
+                <Export as $crate::__Guest>::init,
+                <Export as $crate::__UiEventsGuest>::select,
+            );
         };
     };
 }
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 9f00a12b1..1e49919c3 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -86,6 +86,83 @@ interface storage {
     delete: func(key: string);
 }
 
+/// Capability `ui`: widgets the game draws with its own menus' widgets, for
+/// a screen the mod owns and a settings page in Options > Mods. Layout and
+/// drawing are the game's: a mod says what its widgets hold, never where
+/// they sit or how they look, and the game clips everything it is handed.
+interface ui {
+    /// A line of text.
+    record text-widget {
+        /// The mod's own name for the widget; `ui-events` calls echo it.
+        id: u32,
+        /// Up to 256 characters.
+        text: string,
+        /// 0xRRGGBB; 0 is the menus' white.
+        color: u32,
+    }
+    /// An item's icon and a name beside it, as recipe viewers show them.
+    record item-widget {
+        /// The mod's own name for the widget.
+        id: u32,
+        /// `minecraft:diamond`, `<mod>:<path>`; an unknown id draws a "?".
+        item: string,
+        /// The name shown beside the icon (empty: the item's own).
+        name: string,
+    }
+    /// Rows the player picks one of, as an options page lists choices: a
+    /// pick is `ui-events::select`, `selected` is the row to mark now.
+    record list-widget {
+        /// The mod's own name for the widget; `ui-events::select` echoes it.
+        id: u32,
+        /// The rows' texts, at most 512, each up to 256 characters.
+        rows: list<string>,
+        /// The row to mark as the current choice, if any.
+        selected: option<u32>,
+    }
+    /// A thing on a mod's screen or settings page.
+    variant widget {
+        /// Text the player reads.
+        text(text-widget),
+        /// An item's icon and name.
+        item(item-widget),
+        /// Rows the player picks from.
+        %list(list-widget),
+    }
+    /// A screen the mod owns: a title over widgets stacked down the middle,
+    /// the Done button the game adds, and Esc to leave it.
+    record screen {
+        /// Its title, up to 256 characters.
+        title: string,
+        /// Its widgets, in order, at most 64.
+        widgets: list<widget>,
+    }
+    /// Show `screen` over the game; a second call while it is open replaces
+    /// it. Only the last call of one hook counts.
+    open-screen: func(screen: screen);
+    /// Close the mod's screen when it is open (the mod hears no `closed`
+    /// for this: it was its own doing).
+    close-screen: func();
+    /// The mod's page in Options > Mods, reached from a settings button on
+    /// its row: the widgets it shows, an empty list for no page. The player
+    /// opening the page is `ui-events::settings-opened`: push fresh widgets
+    /// then; later calls update the page while it shows.
+    set-settings: func(widgets: list<widget>);
+}
+
+/// What the game calls on a mod that shows widgets (capability `ui`):
+/// what the player did with them.
+interface ui-events {
+    /// A row of one of the mod's `list` widgets was picked: the widget's
+    /// `id` and the row, on the screen or the settings page that showed it.
+    select: func(id: u32, row: u32);
+    /// The player left the mod's screen (Esc or Done); not for a screen the
+    /// mod closed itself or one that went away with the mod.
+    closed: func();
+    /// The player opened the mod's settings page in Options > Mods: call
+    /// `ui::set-settings` now to fill it with fresh widgets.
+    settings-opened: func();
+}
+
 /// What the game calls. Only the hooks `init` asks for are ever called.
 interface events {
     record registration {
@@ -119,3 +196,18 @@ world horizon-mod {
     import storage;
     export events;
 }
+
+/// A mod with widgets (capability `ui`): the SDK builds every mod against
+/// this world. Mods built for `horizon-mod` alone (no `ui-events` export)
+/// still load and simply hear nothing of their widgets.
+world horizon-ui-mod {
+    include horizon-mod;
+    import ui;
+    export ui-events;
+}
+
+/// The game's side of `horizon-ui-mod` beyond `horizon-mod`.
+world ui-host {
+    import ui;
+    export ui-events;
+}
diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index 3a93b2512..f1ac123b1 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -75,14 +75,18 @@ pub enum Capability {
     /// New blocks and items from the mod's `data/` (API 0.2): no WIT
     /// interface, the game reads them before the world loads.
     Registries,
+    /// A screen the mod owns and a settings page in Options > Mods, drawn
+    /// with the menus' own widgets (interface `ui`, calls `ui-events`).
+    Ui,
 }
 impl Capability {
-    pub const ALL: [Capability; 5] = [
+    pub const ALL: [Capability; 6] = [
         Capability::GameRead,
         Capability::Chat,
         Capability::Hud,
         Capability::Storage,
         Capability::Registries,
+        Capability::Ui,
     ];
     /// The WIT interface it grants, in `horizon:mods`.
     pub fn interface(self) -> &'static str {
@@ -92,6 +96,7 @@ impl Capability {
             Capability::Hud => "hud",
             Capability::Storage => "storage",
             Capability::Registries => "registries",
+            Capability::Ui => "ui",
         }
     }
     /// What the player reads before turning the mod on: "May <this>".
@@ -102,6 +107,7 @@ impl Capability {
             Capability::Hud => "draw text on your screen",
             Capability::Storage => "save its own settings to disk",
             Capability::Registries => "add blocks and items to your worlds",
+            Capability::Ui => "show its own screens and a settings page",
         }
     }
     /// The capability a component import needs, `Ok(None)` for one every
@@ -132,6 +138,7 @@ impl fmt::Display for Capability {
             Capability::Hud => "hud",
             Capability::Storage => "storage",
             Capability::Registries => "registries",
+            Capability::Ui => "ui",
         };
         f.write_str(name)
     }
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 52da641b4..1b1795037 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -16,6 +16,15 @@ mod bindings {
         world: "horizon-mod",
     });
 }
+/// Capability `ui`'s world beyond `horizon-mod` (docs/mods.md): a second
+/// world, so mods built before it (no `ui-events` export) still instantiate
+/// as `horizon-mod` and simply hear nothing of their widgets.
+mod ui_bindings {
+    wasmtime::component::bindgen!({
+        path: "../horizon-mod-sdk/wit",
+        world: "ui-host",
+    });
+}
 pub use bindings::horizon::mods::{
     game::{Clock, Player},
     hud::{Corner, Line},
@@ -25,6 +34,12 @@ use bindings::{
     exports::horizon::mods::events::Registration,
     horizon::mods::{chat, game, hud, log as mod_log, storage},
 };
+/// The widget model a `ui` screen or settings page shows (WIT `interface
+/// ui`), for the game to draw with its menus' own widgets.
+pub use ui_bindings::horizon::mods::ui::{
+    ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
+};
+use ui_bindings::{UiHost, horizon::mods::ui};
 
 /// A mod's linear memory cap.
 const MEMORY: usize = 64 << 20;
@@ -66,6 +81,11 @@ pub enum Output {
     Feedback { text: String, error: bool },
     /// The mod was turned off: it trapped, overran or failed to start.
     Stopped { name: String, reason: String },
+    /// `ui.open-screen`: the mod's entry in `entries()`; what it shows is
+    /// [`Mods::screen`].
+    OpenScreen { owner: usize },
+    /// `ui.close-screen`: the mod closed its own screen (no `closed` back).
+    CloseScreen { owner: usize },
 }
 
 /// A mod's text panel, drawn every frame until it changes.
@@ -95,19 +115,44 @@ pub struct Entry {
     run: Option<Running>,
     modified: Option<SystemTime>,
 }
+impl Entry {
+    /// The running mod has a settings page (capability `ui` set widgets
+    /// with `ui.set-settings`): its row in Options > Mods gains a button.
+    pub fn has_ui_settings(&self) -> bool {
+        self.run
+            .as_ref()
+            .is_some_and(|r| !r.store.data().ui.settings.is_empty())
+    }
+}
 
 struct Running {
     store: Store<State>,
     exports: HorizonMod,
+    /// The mod's `ui-events` export; none for a mod built before `ui`.
+    ui: Option<UiHost>,
     hooks: Registration,
 }
 
+/// What capability `ui` pushed since the hooks last ran.
+#[derive(Default)]
+struct UiState {
+    /// The screen `ui.open-screen` last pushed, until `ui.close-screen`.
+    screen: Option<UiScreen>,
+    /// The widgets `ui.set-settings` last pushed (the mod's page in
+    /// Options > Mods).
+    settings: Vec<UiWidget>,
+    /// The calls since the last hook ended, for [`Output`].
+    open: bool,
+    close: bool,
+}
+
 struct State {
     name: String,
     id: String,
     snapshot: Arc<Snapshot>,
     out: Vec<Output>,
     panel: Option<Panel>,
+    ui: UiState,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
     /// Bytes `storage::set` may still write before this hook call ends
@@ -184,6 +229,8 @@ impl Mods {
             let mut linker = Linker::new(&engine);
             HorizonMod::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
                 .map_err(|e| e.to_string())?;
+            UiHost::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
+                .map_err(|e| e.to_string())?;
             self.engine = Some((engine, linker));
         }
         Ok(self.engine.as_ref().expect("made above"))
@@ -242,6 +289,7 @@ impl Mods {
             snapshot,
             out: Vec::new(),
             panel: None,
+            ui: UiState::default(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
             limits: StoreLimitsBuilder::new()
@@ -252,8 +300,13 @@ impl Mods {
         let mut store = Store::new(engine, state);
         store.limiter(|s| &mut s.limits);
         store.set_fuel(FUEL_INIT).map_err(|e| e.to_string())?;
-        let exports =
-            HorizonMod::instantiate(&mut store, &component, linker).map_err(|e| reason(&e))?;
+        let instance = linker
+            .instantiate(&mut store, &component)
+            .map_err(|e| reason(&e))?;
+        let exports = HorizonMod::new(&mut store, &instance).map_err(|e| reason(&e))?;
+        // `ui-events` is a mod built since `ui`'s; older mods have no export
+        // and stay callable through `events` alone.
+        let ui = UiHost::new(&mut store, &instance).ok();
         let mut hooks = exports
             .horizon_mods_events()
             .call_init(&mut store)
@@ -269,6 +322,7 @@ impl Mods {
         Ok(Some(Running {
             store,
             exports,
+            ui,
             hooks,
         }))
     }
@@ -290,7 +344,7 @@ impl Mods {
         &mut self,
         fuel: u64,
         wants: impl Fn(&Registration) -> bool,
-        mut f: impl FnMut(&HorizonMod, &mut Store<State>) -> wasmtime::Result<()>,
+        mut f: impl FnMut(&mut Running) -> wasmtime::Result<()>,
     ) {
         for i in 0..self.entries.len() {
             if self.entries[i]
@@ -308,20 +362,28 @@ impl Mods {
         &mut self,
         i: usize,
         fuel: u64,
-        f: impl FnOnce(&HorizonMod, &mut Store<State>) -> wasmtime::Result<R>,
+        f: impl FnOnce(&mut Running) -> wasmtime::Result<R>,
     ) -> Option<R> {
         let entry = &mut self.entries[i];
         let run = entry.run.as_mut()?;
         run.store.data_mut().snapshot = self.snapshot.clone();
         run.store.data_mut().storage_budget = STORAGE_WRITE_BUDGET;
         let started = Instant::now();
-        let result = run
-            .store
-            .set_fuel(fuel)
-            .and_then(|()| f(&run.exports, &mut run.store));
+        let result = run.store.set_fuel(fuel).and_then(|()| f(run));
         // An average over about the last 64 calls.
         entry.cost = (entry.cost * 63 + started.elapsed()) / 64;
-        self.out.append(&mut run.store.data_mut().out);
+        let data = run.store.data_mut();
+        let (open, close) = (
+            std::mem::take(&mut data.ui.open),
+            std::mem::take(&mut data.ui.close),
+        );
+        self.out.append(&mut data.out);
+        if open {
+            self.out.push(Output::OpenScreen { owner: i });
+        }
+        if close {
+            self.out.push(Output::CloseScreen { owner: i });
+        }
         match result {
             Ok(r) => Some(r),
             Err(e) => {
@@ -344,7 +406,11 @@ impl Mods {
         self.each(
             FUEL_TICK,
             |h| h.tick,
-            |m, s| m.horizon_mods_events().call_tick(s, tick),
+            |run| {
+                run.exports
+                    .horizon_mods_events()
+                    .call_tick(&mut run.store, tick)
+            },
         );
     }
     /// A rendered frame, `seconds` after the last.
@@ -352,7 +418,11 @@ impl Mods {
         self.each(
             FUEL_FRAME,
             |h| h.frame,
-            |m, s| m.horizon_mods_events().call_frame(s, seconds),
+            |run| {
+                run.exports
+                    .horizon_mods_events()
+                    .call_frame(&mut run.store, seconds)
+            },
         );
     }
     /// A chat line the player received, as plain text.
@@ -360,7 +430,11 @@ impl Mods {
         self.each(
             FUEL_EVENT,
             |h| h.chat,
-            |m, s| m.horizon_mods_events().call_chat(s, text),
+            |run| {
+                run.exports
+                    .horizon_mods_events()
+                    .call_chat(&mut run.store, text)
+            },
         );
     }
     /// Whether a running mod owns `/name`.
@@ -381,8 +455,10 @@ impl Mods {
         let Some(i) = self.command_owner(name) else {
             return false;
         };
-        let result = self.call(i, FUEL_EVENT, |m, s| {
-            m.horizon_mods_events().call_command(s, name, args)
+        let result = self.call(i, FUEL_EVENT, |run| {
+            run.exports
+                .horizon_mods_events()
+                .call_command(&mut run.store, name, args)
         });
         match result {
             Some(Ok(Some(text))) => self.out.push(Output::Feedback { text, error: false }),
@@ -405,6 +481,60 @@ impl Mods {
             .iter()
             .filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
     }
+    /// The screen mod `i` last pushed with `ui.open-screen`, while it is up.
+    pub fn screen(&self, i: usize) -> Option<&UiScreen> {
+        self.entries
+            .get(i)?
+            .run
+            .as_ref()?
+            .store
+            .data()
+            .ui
+            .screen
+            .as_ref()
+    }
+    /// The widgets `ui.set-settings` pushed: mod `i`'s page in
+    /// Options > Mods. Empty while it has none.
+    pub fn settings_widgets(&self, i: usize) -> &[UiWidget] {
+        self.entries
+            .get(i)
+            .and_then(|e| e.run.as_ref())
+            .map_or(&[], |r| &r.store.data().ui.settings)
+    }
+    /// A `list` widget's row was picked on a surface of mod `i`.
+    pub fn ui_select(&mut self, i: usize, id: u32, row: u32) {
+        self.ui_event(i, |ui, s| {
+            ui.horizon_mods_ui_events().call_select(s, id, row)
+        });
+    }
+    /// The player left mod `i`'s screen (Esc or Done).
+    pub fn ui_closed(&mut self, i: usize) {
+        self.ui_event(i, |ui, s| ui.horizon_mods_ui_events().call_closed(s));
+    }
+    /// The player opened mod `i`'s settings page.
+    pub fn ui_settings_opened(&mut self, i: usize) {
+        self.ui_event(i, |ui, s| {
+            ui.horizon_mods_ui_events().call_settings_opened(s)
+        });
+    }
+    /// A `ui-events` call on mod `i`; no export, no call (mods built
+    /// before `ui` have none).
+    fn ui_event(
+        &mut self,
+        i: usize,
+        f: impl FnOnce(&UiHost, &mut Store<State>) -> wasmtime::Result<()>,
+    ) {
+        let has_ui = self
+            .entries
+            .get(i)
+            .and_then(|e| e.run.as_ref())
+            .is_some_and(|r| r.ui.is_some());
+        if has_ui {
+            self.call(i, FUEL_EVENT, |run| {
+                f(run.ui.as_ref().expect("checked above"), &mut run.store)
+            });
+        }
+    }
     /// What mods asked to show since the last call.
     pub fn drain(&mut self) -> Vec<Output> {
         std::mem::take(&mut self.out)
@@ -476,6 +606,33 @@ fn clip(text: String) -> String {
     }
 }
 
+/// Widgets on a `ui` screen or settings page, and rows on one `list`.
+const WIDGETS: usize = 64;
+const LIST_ROWS: usize = 512;
+
+fn clip_widgets(widgets: Vec<UiWidget>) -> Vec<UiWidget> {
+    widgets
+        .into_iter()
+        .take(WIDGETS)
+        .map(|w| match w {
+            UiWidget::Text(mut t) => {
+                t.text = clip(t.text);
+                UiWidget::Text(t)
+            }
+            UiWidget::Item(mut i) => {
+                i.item = clip(i.item);
+                i.name = clip(i.name);
+                UiWidget::Item(i)
+            }
+            UiWidget::List(mut l) => {
+                l.rows = l.rows.into_iter().take(LIST_ROWS).map(clip).collect();
+                l.selected = l.selected.filter(|&s| (s as usize) < l.rows.len());
+                UiWidget::List(l)
+            }
+        })
+        .collect()
+}
+
 impl mod_log::Host for State {
     fn write(&mut self, level: mod_log::Level, message: String) {
         let level = match level {
@@ -527,6 +684,21 @@ impl hud::Host for State {
         self.panel = None;
     }
 }
+impl ui::Host for State {
+    fn open_screen(&mut self, mut screen: ui::Screen) {
+        screen.title = clip(screen.title);
+        screen.widgets = clip_widgets(screen.widgets);
+        self.ui.screen = Some(screen);
+        self.ui.open = true;
+    }
+    fn close_screen(&mut self) {
+        self.ui.screen = None;
+        self.ui.close = true;
+    }
+    fn set_settings(&mut self, widgets: Vec<ui::Widget>) {
+        self.ui.settings = clip_widgets(widgets);
+    }
+}
 impl storage::Host for State {
     fn get(&mut self, key: String) -> Option<Vec<u8>> {
         storage_key_ok(&key)
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index a246c07b0..a229f748e 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -17,6 +17,13 @@ version = "0.1.0"
 api = "0.1"
 capabilities = ["chat", "storage"]
 "#;
+const UI_MANIFEST: &str = r#"
+id = "test_ui_guest"
+name = "Test UI Guest"
+version = "0.1.0"
+api = "0.1"
+capabilities = ["chat", "ui"]
+"#;
 
 /// Builds both mods once and writes their `.hmod` files; returns the folder.
 fn mods_dir() -> &'static Path {
@@ -32,6 +39,8 @@ fn mods_dir() -> &'static Path {
                 "coords-hud",
                 "-p",
                 "horizon-mods-test-guest",
+                "-p",
+                "horizon-mods-test-ui-guest",
                 "--target-dir",
             ])
             .arg(&target)
@@ -48,6 +57,7 @@ fn mods_dir() -> &'static Path {
         let mods = [
             ("coords_hud", std::fs::read_to_string(example).unwrap()),
             ("horizon_mods_test_guest", GUEST_MANIFEST.to_string()),
+            ("horizon_mods_test_ui_guest", UI_MANIFEST.to_string()),
         ];
         for (name, manifest) in mods {
             let core = std::fs::read(built.join(format!("{name}.wasm"))).unwrap();
@@ -366,6 +376,45 @@ fn hook_overhead() {
     );
 }
 
+#[test]
+fn ui_screens_settings_and_events() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    assert_eq!(mods.entries()[0].status, Status::Running);
+    assert!(!mods.entries()[0].has_ui_settings());
+    // `/ui_screen` pushes the screen; the host clips nothing of this one.
+    assert!(mods.command("ui_screen"));
+    assert_eq!(mods.drain(), [Output::OpenScreen { owner: 0 }]);
+    let screen = mods.screen(0).expect("a pushed screen");
+    assert_eq!(screen.title, "Guest's screen");
+    assert_eq!(screen.widgets.len(), 3);
+    // What the player did comes back through `ui-events`.
+    mods.ui_select(0, 7, 2);
+    mods.ui_closed(0);
+    assert_eq!(
+        mods.drain(),
+        [
+            Output::Chat {
+                name: "Test UI Guest".into(),
+                text: "selected 7:2".into(),
+            },
+            Output::Chat {
+                name: "Test UI Guest".into(),
+                text: "closed".into(),
+            },
+        ]
+    );
+    // The settings page: empty until the mod fills it, refreshed on open.
+    assert!(mods.command("ui_settings"));
+    assert_eq!(mods.settings_widgets(0).len(), 3);
+    assert!(mods.entries()[0].has_ui_settings());
+    mods.ui_settings_opened(0);
+    assert_eq!(mods.settings_widgets(0).len(), 1);
+    // `/ui_close` closes the mod's own screen.
+    assert!(mods.command("ui_close"));
+    assert!(mods.drain().contains(&Output::CloseScreen { owner: 0 }));
+    assert!(mods.screen(0).is_none());
+}
+
 #[test]
 fn content_only_mods_load_without_an_engine() {
     let manifest = r#"
diff --git a/crates/horizon-mods/tests/ui_guest/Cargo.toml b/crates/horizon-mods/tests/ui_guest/Cargo.toml
new file mode 100644
index 000000000..ae6e0950e
--- /dev/null
+++ b/crates/horizon-mods/tests/ui_guest/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "horizon-mods-test-ui-guest"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "A mod that shows widgets, for horizon-mods' sandbox tests"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../../../horizon-mod-sdk" }
+
+[lints]
+workspace = true
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
new file mode 100644
index 000000000..1af3985a1
--- /dev/null
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -0,0 +1,66 @@
+//! A mod for the runtime's `ui` tests: `/ui_screen` opens a screen with one
+//! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes
+//! the screen; the `ui-events` calls answer in chat so the host sees them.
+use horizon_mod_sdk::{
+    Mod, Registration, chat,
+    ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
+};
+
+struct Guest;
+
+fn widgets() -> Vec<Widget> {
+    vec![
+        Widget::Text(TextWidget {
+            id: 1,
+            text: "Pick a row".into(),
+            color: 0,
+        }),
+        Widget::Item(ItemWidget {
+            id: 2,
+            item: "minecraft:diamond".into(),
+            name: String::new(),
+        }),
+        Widget::List(ListWidget {
+            id: 7,
+            rows: vec!["first".into(), "second".into(), "third".into()],
+            selected: Some(1),
+        }),
+    ]
+}
+
+impl Mod for Guest {
+    fn init() -> Result<(Self, Registration), String> {
+        let hooks = ["ui_screen", "ui_settings", "ui_close"]
+            .into_iter()
+            .fold(Registration::new(), Registration::command);
+        Ok((Guest, hooks))
+    }
+    fn command(&mut self, name: &str, _args: &str) -> Result<Option<String>, String> {
+        match name {
+            "ui_screen" => ui::open_screen(&Screen {
+                title: "Guest's screen".into(),
+                widgets: widgets(),
+            }),
+            "ui_settings" => ui::set_settings(&widgets()),
+            "ui_close" => ui::close_screen(),
+            _ => {}
+        }
+        Ok(None)
+    }
+    fn ui_select(&mut self, id: u32, row: u32) {
+        chat::show(&format!("selected {id}:{row}"));
+    }
+    fn ui_closed(&mut self) {
+        chat::show("closed");
+    }
+    fn ui_settings_opened(&mut self) {
+        ui::set_settings(&[Widget::Text(TextWidget {
+            id: 1,
+            text: "fresh".into(),
+            color: 0x33CC33,
+        })]);
+        chat::show("settings opened");
+    }
+}
+
+horizon_mod_sdk::export_mod!(Guest);
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index ca2fe9d7a..0812cde54 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -12,12 +12,27 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `hud` | [`hud`](#hud) | draw text on your screen |
 | `storage` | [`storage`](#storage) | save its own settings to disk |
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
+| `ui` | [`ui`](#ui) | show its own screens and a settings page |
 
 ## World `horizon-mod`
 
 - Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`
 - Exports (what the mod provides): `events`
 
+## World `horizon-ui-mod`
+
+A mod with widgets (capability `ui`): the SDK builds every mod against this world. Mods built for `horizon-mod` alone (no `ui-events` export) still load and simply hear nothing of their widgets.
+
+- Imports (what the game offers): `ui`, `log`, `game`, `chat`, `hud`, `storage`
+- Exports (what the mod provides): `ui-events`, `events`
+
+## World `ui-host`
+
+The game's side of `horizon-ui-mod` beyond `horizon-mod`.
+
+- Imports (what the game offers): `ui`
+- Exports (what the mod provides): `ui-events`
+
 ## `log`
 
 Access: always granted.
@@ -117,6 +132,79 @@ Capability `storage`: a per-mod folder of small key/value files, quota'd (docs/m
 | `set` | `func(key: string, value: list<u8>) -> result<_, string>` | Errs on a malformed key or over quota (bytes for the whole mod). |
 | `delete` | `func(key: string)` | No error if `key` was already absent. |
 
+## `ui`
+
+Access: capability `ui`.
+
+Capability `ui`: widgets the game draws with its own menus' widgets, for a screen the mod owns and a settings page in Options > Mods. Layout and drawing are the game's: a mod says what its widgets hold, never where they sit or how they look, and the game clips everything it is handed.
+
+### record `text-widget`
+
+A line of text.
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `u32` | The mod's own name for the widget; `ui-events` calls echo it. |
+| `text` | `string` | Up to 256 characters. |
+| `color` | `u32` | 0xRRGGBB; 0 is the menus' white. |
+
+### record `item-widget`
+
+An item's icon and a name beside it, as recipe viewers show them.
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `u32` | The mod's own name for the widget. |
+| `item` | `string` | `minecraft:diamond`, `<mod>:<path>`; an unknown id draws a "?". |
+| `name` | `string` | The name shown beside the icon (empty: the item's own). |
+
+### record `list-widget`
+
+Rows the player picks one of, as an options page lists choices: a pick is `ui-events::select`, `selected` is the row to mark now.
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `u32` | The mod's own name for the widget; `ui-events::select` echoes it. |
+| `rows` | `list<string>` | The rows' texts, at most 512, each up to 256 characters. |
+| `selected` | `option<u32>` | The row to mark as the current choice, if any. |
+
+### variant `widget`
+
+A thing on a mod's screen or settings page.
+
+| Case | Payload | |
+| --- | --- | --- |
+| `text` | `text-widget` | Text the player reads. |
+| `item` | `item-widget` | An item's icon and name. |
+| `list` | `list-widget` | Rows the player picks from. |
+
+### record `screen`
+
+A screen the mod owns: a title over widgets stacked down the middle, the Done button the game adds, and Esc to leave it.
+
+| Field | Type | |
+| --- | --- | --- |
+| `title` | `string` | Its title, up to 256 characters. |
+| `widgets` | `list<widget>` | Its widgets, in order, at most 64. |
+
+| Function | Signature | What it does |
+| --- | --- | --- |
+| `open-screen` | `func(screen: screen)` | Show `screen` over the game; a second call while it is open replaces it. Only the last call of one hook counts. |
+| `close-screen` | `func()` | Close the mod's screen when it is open (the mod hears no `closed` for this: it was its own doing). |
+| `set-settings` | `func(widgets: list<widget>)` | The mod's page in Options > Mods, reached from a settings button on its row: the widgets it shows, an empty list for no page. The player opening the page is `ui-events::settings-opened`: push fresh widgets then; later calls update the page while it shows. |
+
+## `ui-events`
+
+Access: exported by the mod: the game calls it.
+
+What the game calls on a mod that shows widgets (capability `ui`): what the player did with them.
+
+| Function | Signature | What it does |
+| --- | --- | --- |
+| `select` | `func(id: u32, row: u32)` | A row of one of the mod's `list` widgets was picked: the widget's `id` and the row, on the screen or the settings page that showed it. |
+| `closed` | `func()` | The player left the mod's screen (Esc or Done); not for a screen the mod closed itself or one that went away with the mod. |
+| `settings-opened` | `func()` | The player opened the mod's settings page in Options > Mods: call `ui::set-settings` now to fill it with fresh widgets. |
+
 ## `events`
 
 Access: exported by the mod: the game calls it.
diff --git a/docs/mods.md b/docs/mods.md
index bac207f60..45e5ae02e 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -12,7 +12,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 
 | Part | Where | State |
 |---|---|---|
-| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks |
+| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage, ui; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
@@ -86,6 +86,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) |
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
+| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code |
 
 | Hook (export) | When |
 |---|---|
@@ -112,7 +113,6 @@ loading. Ordered by what the first native ports need:
 | `target` | the crosshair's block or entity, with its state and NBT summary | Jade/WTHIT-style tooltips |
 | `inventory-read` | the player's inventory, held item, open container | AppleSkin, recipe viewers |
 | `recipes` | the recipe registry and lookups | JEI/EMI-style viewers |
-| `ui` | widgets: text, item icons, lists, a screen the mod owns, a settings page in Options > Mods | built from vanilla's widgets (`ui`) so it matches the menus |
 | `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics |
 | `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints |
 | `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) |

From fd154dcbba30d8b4ad8320f6f93231013965391d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:13:06 +0100
Subject: [PATCH 129/270] Website image: copy data/ so the build finds the
 roadmap

build.mjs reads website/data/roadmap.json since the hub (#1819), but the Dockerfile never
copied data/, so every site deploy since then failed and playhorizon.dev kept the old build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 website/Dockerfile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/Dockerfile b/website/Dockerfile
index ea9cc9afc..b075f9b58 100644
--- a/website/Dockerfile
+++ b/website/Dockerfile
@@ -5,6 +5,7 @@ WORKDIR /site
 COPY build.mjs ./
 COPY src ./src
 COPY docs ./docs
+COPY data ./data
 COPY public ./public
 COPY LEGAL.md ./
 ARG GITHUB_TOKEN

From d41a3075aa86491e6ac23821480ff2a86b494289 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:13:26 +0100
Subject: [PATCH 130/270] Launcher: a local registry's file:/// URLs open on
 Windows

file:///C:/x left /C:/x after the scheme, which Windows can't open; the pack tests now
write real file:/// URLs (the index only accepts those), with forward slashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/browser/horizon.rs      |  9 +++++++++
 launcher/src/browser/horizon/pack.rs | 12 ++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/launcher/src/browser/horizon.rs b/launcher/src/browser/horizon.rs
index e56f31e09..66553ab50 100644
--- a/launcher/src/browser/horizon.rs
+++ b/launcher/src/browser/horizon.rs
@@ -343,6 +343,7 @@ fn fetch(
 ) -> Result<PathBuf, String> {
     match file.url.strip_prefix("file://").filter(|_| local) {
         Some(path) => {
+            let path = local_path(path);
             let reader = fs::File::open(path).map_err(|e| format!("{path}: {e}"))?;
             download::save_from_anywhere(file, reader, folder, progress)
         }
@@ -350,6 +351,14 @@ fn fetch(
     }
 }
 
+/// The path of a `file:///` URL: on Windows `/C:/x` is `C:/x`.
+fn local_path(path: &str) -> &str {
+    match path.strip_prefix('/') {
+        Some(rest) if cfg!(windows) && rest.get(1..2) == Some(":") => rest,
+        _ => path,
+    }
+}
+
 /// What the registry adds to an installed entry.
 fn trust_label(trust: Trust) -> &'static str {
     match trust {
diff --git a/launcher/src/browser/horizon/pack.rs b/launcher/src/browser/horizon/pack.rs
index a2cc4d079..3cb6d7c9b 100644
--- a/launcher/src/browser/horizon/pack.rs
+++ b/launcher/src/browser/horizon/pack.rs
@@ -208,8 +208,16 @@ mod tests {
         zip.write_all(b"renderDistance:8\n").unwrap();
         zip.finish().unwrap();
         let size = |p: &Path| fs::metadata(p).unwrap().len();
-        // Forward slashes: a Windows path's backslashes would be escapes in the JSON.
-        let url = |p: &Path| p.display().to_string().replace('\\', "/");
+        // A `file:///` URL: forward slashes (a Windows path's backslashes would be escapes in
+        // the JSON) and a leading slash before a Windows drive.
+        let url = |p: &Path| {
+            let path = p.display().to_string().replace('\\', "/");
+            if path.starts_with('/') {
+                path
+            } else {
+                format!("/{path}")
+            }
+        };
         let text = format!(
             r#"{{"schema": 1, "projects": [
               {{"id": "coords_hud", "kind": "mod", "name": "Coordinates HUD", "summary": "", "license": "MIT",

From 204859a2cb893f71b14605ea689f91424ace0671 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:20:41 +0100
Subject: [PATCH 131/270] Launcher: a preparation reusing imported game files
 still finds the assets

When an update's preparation reused the game files an earlier version imported,
`preparer` handed the chosen folder as it was to the sound copy and the panorama,
fonts, packs and languages step. A Prism Launcher instance or Modrinth App profile
holds no asset store, so the game was silent with a grey title screen, and
Prepare again did the same. It now resolves the folder (linking another
launcher's files into the official layout) either way; with reused imports a
missing one is a log line, not an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/backend.rs | 97 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 88 insertions(+), 9 deletions(-)

diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 9d1eeb111..5f631f8f8 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -1103,6 +1103,34 @@ fn with_java(cmd: &mut Command, home: &Path) {
     }
 }
 
+/// The Minecraft folder a preparation whose game files are imported already reads: the sounds,
+/// the title panorama, the fonts and the languages come from its asset store. It is the one
+/// `resolve` found, linked into the official layout for another launcher's files; without one, the
+/// chosen folder, and the preparation goes without them, saying so. Before, such a preparation
+/// read the chosen folder as it was, which a Prism Launcher or Modrinth App install does not
+/// keep its assets in: the game was silent and its title screen grey.
+fn assets_folder(
+    resolved: Result<sources::Resolved, String>,
+    chosen: &Path,
+    version: &str,
+    log: &dyn Fn(String),
+) -> PathBuf {
+    match resolved {
+        Ok(sources::Resolved::Folder(dir)) => dir,
+        Ok(sources::Resolved::NotFound(_)) => {
+            log(format!(
+                "Minecraft {version}'s assets were not found in any launcher folder: the game \
+                 will be silent and the title screen plain"
+            ));
+            chosen.to_path_buf()
+        }
+        Err(e) => {
+            log(format!("Minecraft {version}'s assets: {e}"));
+            chosen.to_path_buf()
+        }
+    }
+}
+
 /// Checks what the preparation needs and picks how to run it. PLAY.txt describes the same
 /// steps: the player's own launcher install, the server jar from that version's own json, and
 /// Java (and Python, for versions before horizon-prepare). Also returns the Minecraft folder
@@ -1117,9 +1145,8 @@ pub fn preparer(
     let dir = version_dir(tag);
     let reused = horizon_prepare::artifacts::reuse_imported(&dir, &|line| log(line.to_string()))?;
     let chosen = minecraft.to_path_buf();
-    let minecraft = if reused {
-        minecraft.to_path_buf()
-    } else {
+    // Resolved even when the game files are reused: the assets still come from the install.
+    let minecraft = {
         let pins = read_json(&dir.join("research-lock.json"))
             .and_then(|lock| sources::Pins::read(&lock))
             .ok_or("The version's research-lock.json doesn't pin the Minecraft files")?;
@@ -1139,12 +1166,17 @@ pub fn preparer(
             Ok(body)
         };
         let linked = data_dir().join("linked-minecraft");
-        match sources::resolve(minecraft, &pins, &known, &linked, &fetch, log)? {
-            sources::Resolved::Folder(dir) => dir,
-            sources::Resolved::NotFound(checked) => {
-                let not_found = sources::not_found(&version, &checked, minecraft);
-                download_for_owner(&pins, &own, &fetch, log).map_err(|e| not_found + &e)?;
-                own
+        let resolved = sources::resolve(minecraft, &pins, &known, &linked, &fetch, log);
+        if reused {
+            assets_folder(resolved, &chosen, &version, log)
+        } else {
+            match resolved? {
+                sources::Resolved::Folder(dir) => dir,
+                sources::Resolved::NotFound(checked) => {
+                    let not_found = sources::not_found(&version, &checked, minecraft);
+                    download_for_owner(&pins, &own, &fetch, log).map_err(|e| not_found + &e)?;
+                    own
+                }
             }
         }
     };
@@ -2353,6 +2385,53 @@ mod tests {
     use super::*;
     use std::cmp::Ordering::*;
 
+    /// A preparation that reuses the imported game files still reads the assets from the
+    /// launcher that has them: a Prism Launcher instance's are in the launcher root, linked into
+    /// the official layout (jan.sonki on Discord: silent, grey title screen since 0.2.48).
+    #[test]
+    fn reused_imports_take_the_assets_from_the_launcher_that_has_them() {
+        let dir =
+            std::env::temp_dir().join(format!("horizon-reused-assets-{}", std::process::id()));
+        let _ = fs::remove_dir_all(&dir);
+        let client = b"fake client jar";
+        let manifest = br#"{"id": "26.3"}"#;
+        let write = |path: &str, data: &[u8]| {
+            let path = dir.join(path);
+            fs::create_dir_all(path.parent().unwrap()).unwrap();
+            fs::write(path, data).unwrap();
+        };
+        let prism = "PrismLauncher";
+        write(
+            &format!("{prism}/libraries/com/mojang/minecraft/26.3/minecraft-26.3-client.jar"),
+            client,
+        );
+        write(&format!("{prism}/assets/indexes/34.json"), b"{}");
+        let instance = dir.join(prism).join("instances/26.3/minecraft");
+        fs::create_dir_all(&instance).unwrap();
+        let pins = sources::Pins::read(&serde_json::json!({ "minecraft": {
+            "version": "26.3",
+            "client_sha1": sources::sha1_hex(client),
+            "manifest_sha1": sources::sha1_hex(manifest),
+        }}))
+        .unwrap();
+        let linked = dir.join("linked");
+        let fetch = |_: &str| Ok(manifest.to_vec());
+        let lines = std::cell::RefCell::new(Vec::new());
+        let log = |line: String| lines.borrow_mut().push(line);
+        let resolved = sources::resolve(&instance, &pins, &[], &linked, &fetch, &log);
+        let folder = assets_folder(resolved, &instance, "26.3", &log);
+        assert_eq!(folder, linked);
+        assert!(folder.join("assets/indexes/34.json").is_file());
+
+        // Nothing found: the chosen folder, and a line saying what the game will lack.
+        let empty = dir.join("empty");
+        fs::create_dir_all(&empty).unwrap();
+        let resolved = sources::resolve(&empty, &pins, &[], &linked, &fetch, &log);
+        assert_eq!(assets_folder(resolved, &empty, "26.3", &log), empty);
+        assert!(lines.borrow().last().unwrap().contains("will be silent"));
+        fs::remove_dir_all(&dir).unwrap();
+    }
+
     #[test]
     fn resources_without_sounds_are_reported() {
         let dir = std::env::temp_dir().join(format!("horizon-no-sounds-{}", std::process::id()));

From 6d3cd330d1f9b24b560c19c1701f39b1ed9b87cd Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:25:02 +0100
Subject: [PATCH 132/270] One isWithinBlockInteractionRange for guests, the
 in-frame player, stations, lecterns and signs

The reach test was written out four times (stations, lecterns, the
in-frame container check and the guest's); they now share
lan::guest::within_block_range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/lan_stations.rs   | 20 ++------------
 crates/horizon-client/src/game/sign_edit.rs   |  2 +-
 crates/horizon-client/src/game/storage.rs     | 14 ++--------
 crates/horizon-client/src/lan/guest.rs        | 26 ++++++++++++-------
 4 files changed, 21 insertions(+), 41 deletions(-)

diff --git a/crates/horizon-client/src/game/lan_stations.rs b/crates/horizon-client/src/game/lan_stations.rs
index 49a90b7b9..418ed9c2a 100644
--- a/crates/horizon-client/src/game/lan_stations.rs
+++ b/crates/horizon-client/src/game/lan_stations.rs
@@ -588,7 +588,7 @@ impl Game<'_> {
             let [x, y, z] = gs.pos;
             let name = &self.res.facts().get(self.world.block(x, y, z)).name;
             let block = StationKind::from_block(name) == Some(gs.kind);
-            if !(block && within_reach(g, gs.pos)) {
+            if !(block && g.within_block_range(gs.pos, 4.0)) {
                 let window = gs.window;
                 self.lan_station_closed(host, conn, Some(window));
                 host.hub.send_to(
@@ -631,16 +631,7 @@ impl Game<'_> {
                 Some(BlockEntity::Lectern(l)) if l.book.is_some()
             );
             // Container.stillValidBlockEntity: the interaction range and its buffer.
-            let eye = [g.position[0], g.position[1] + g.eye_height(), g.position[2]];
-            let reach = if g.creative() { 5.0 } else { 4.5 } + 4.0;
-            let pos = [key.0, key.1, key.2];
-            let near = (0..3)
-                .map(|k| {
-                    let lo = f64::from(pos[k]);
-                    (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
-                })
-                .sum::<f64>()
-                < reach * reach;
+            let near = g.within_block_range([key.0, key.1, key.2], 4.0);
             if has_book && near {
                 self.lan_send_lectern(host, conn, false);
             } else {
@@ -660,10 +651,3 @@ pub(super) fn station_inputs(gs: &GuestStation) -> Vec<ItemStack> {
         .map(|(_, _, inputs)| inputs.filter_map(|s| gs.menu.slot(s).cloned()).collect())
         .unwrap_or_default()
 }
-
-/// `Player.isWithinBlockInteractionRange(pos, 4)`: the guest's eyes within
-/// its block interaction range (4.5, creative 5) and a 4-block buffer of the
-/// block's box.
-pub(super) fn within_reach(g: &horizon_client::lan::guest::Guest, pos: [i32; 3]) -> bool {
-    g.within_block_range(pos, 4.0)
-}
diff --git a/crates/horizon-client/src/game/sign_edit.rs b/crates/horizon-client/src/game/sign_edit.rs
index 5a26e3e69..5efc3dd0b 100644
--- a/crates/horizon-client/src/game/sign_edit.rs
+++ b/crates/horizon-client/src/game/sign_edit.rs
@@ -78,7 +78,7 @@ impl Game<'_> {
         let Some(g) = host.hub.guest(conn) else {
             return;
         };
-        let near = super::lan_stations::within_reach(g, p.pos);
+        let near = g.within_block_range(p.pos, 4.0);
         let Some(play) = host.play.get_mut(&conn) else {
             return;
         };
diff --git a/crates/horizon-client/src/game/storage.rs b/crates/horizon-client/src/game/storage.rs
index 9132c02a8..de7dfd6e7 100644
--- a/crates/horizon-client/src/game/storage.rs
+++ b/crates/horizon-client/src/game/storage.rs
@@ -144,18 +144,8 @@ impl Game<'_> {
             return;
         }
         let range = self.reach() + 4.0;
-        let near = self.container_parts().iter().all(|((x, y, z), _)| {
-            let d = [*x, *y, *z]
-                .iter()
-                .zip(eye)
-                .map(|(&lo, e)| {
-                    (f64::from(lo) - e)
-                        .max(e - f64::from(lo) - 1.0)
-                        .max(0.0)
-                        .powi(2)
-                })
-                .sum::<f64>();
-            d < range * range
+        let near = self.container_parts().iter().all(|&((x, y, z), _)| {
+            horizon_client::lan::guest::within_block_range(eye, range, [x, y, z])
         });
         if !near {
             self.close_container();
diff --git a/crates/horizon-client/src/lan/guest.rs b/crates/horizon-client/src/lan/guest.rs
index dc10096e3..57fa7c636 100644
--- a/crates/horizon-client/src/lan/guest.rs
+++ b/crates/horizon-client/src/lan/guest.rs
@@ -404,22 +404,16 @@ impl Guest {
     pub fn eye_height(&self) -> f64 {
         if self.sneaking { 1.27 } else { 1.62 }
     }
-    /// `Player.isWithinBlockInteractionRange(pos, buffer)`: the eyes within the
-    /// block interaction range (4.5, creative 5) plus `buffer` of the block's box.
+    /// `Player.isWithinBlockInteractionRange(pos, buffer)` for the guest:
+    /// its block interaction range is 4.5, 5 in creative.
     pub fn within_block_range(&self, pos: [i32; 3], buffer: f64) -> bool {
         let eye = [
             self.position[0],
             self.position[1] + self.eye_height(),
             self.position[2],
         ];
-        let reach = if self.creative() { 5.0 } else { 4.5 } + buffer;
-        (0..3)
-            .map(|k| {
-                let lo = f64::from(pos[k]);
-                (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
-            })
-            .sum::<f64>()
-            < reach * reach
+        let range = if self.creative() { 5.0 } else { 4.5 };
+        within_block_range(eye, range + buffer, pos)
     }
     /// The inventory menu's 46 slots (ServerPlayer.inventoryMenu): 0 crafting
     /// result, 1..=4 crafting grid, 5..=8 armor, 9..=35 main, 36..=44 hotbar,
@@ -585,6 +579,18 @@ fn network_stack(
     Some(stack)
 }
 
+/// `Player.isWithinBlockInteractionRange`: `eye` closer than `range` to the
+/// box of the block at `pos` (`AABB.distanceToSqr`).
+pub fn within_block_range(eye: [f64; 3], range: f64, pos: [i32; 3]) -> bool {
+    (0..3)
+        .map(|k| {
+            let lo = f64::from(pos[k]);
+            (lo - eye[k]).max(eye[k] - lo - 1.0).max(0.0).powi(2)
+        })
+        .sum::<f64>()
+        < range * range
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

From 65d3edfc3a1fc391f99dd091e41d031857a61583 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:26:03 +0100
Subject: [PATCH 133/270] Launcher: find the client jar of a Modrinth App mod
 loader profile (#1783)

The Modrinth App keeps a Fabric or Quilt profile's vanilla client jar as
`versions/<v>-<loader>/<v>-<loader>.jar`; a player who only played such a
profile has no `versions/<v>/`, and Prepare said Minecraft was not found.
Those jars are now candidates too, checked against the pinned sha1 like the rest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/sources.rs       | 18 ++++++++++++++++++
 launcher/src/sources_tests.rs | 23 +++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/launcher/src/sources.rs b/launcher/src/sources.rs
index b27b8417b..50953067e 100644
--- a/launcher/src/sources.rs
+++ b/launcher/src/sources.rs
@@ -191,6 +191,24 @@ fn client_jars(base: &Path, version: &str) -> Vec<String> {
             jars.push(jar);
         }
     }
+    jars.extend(loader_jars(base, version));
+    jars
+}
+
+/// The client jars the Modrinth App keeps for a mod loader's profile: `versions/<v>-<loader>/`,
+/// the vanilla jar under the loader's name, when only a Fabric or Quilt profile of the version
+/// was ever played (#1783). The jar is checked against the pin like the others.
+fn loader_jars(base: &Path, version: &str) -> Vec<String> {
+    let prefix = format!("{version}-");
+    let mut jars: Vec<String> = fs::read_dir(base.join("versions"))
+        .into_iter()
+        .flatten()
+        .flatten()
+        .filter_map(|entry| entry.file_name().into_string().ok())
+        .filter(|name| name.starts_with(&prefix))
+        .map(|name| format!("versions/{name}/{name}.jar"))
+        .collect();
+    jars.sort();
     jars
 }
 
diff --git a/launcher/src/sources_tests.rs b/launcher/src/sources_tests.rs
index 6d882f032..396f50881 100644
--- a/launcher/src/sources_tests.rs
+++ b/launcher/src/sources_tests.rs
@@ -289,6 +289,29 @@ fn the_modrinth_app_atlauncher_and_gdlauncher_are_found() {
     }
 }
 
+/// A Modrinth App that only ever played a Fabric profile of 26.3 keeps the vanilla client jar
+/// under the loader's name (#1783); a profile of another version beside it is not taken.
+#[test]
+fn a_modrinth_loader_profile_has_the_client_jar() {
+    let s = Scratch::new("modrinth-fabric");
+    s.write(
+        "ModrinthApp/meta/versions/26.3.1-0.18.1/26.3.1-0.18.1.jar",
+        b"other",
+    );
+    let jar = "versions/26.3-0.18.1/26.3-0.18.1.jar";
+    let dir = s.launcher("ModrinthApp", "meta", jar);
+    s.write(
+        "ModrinthApp/meta/versions/26.3-0.18.1/26.3-0.18.1.json",
+        br#"{"id":"26.3-0.18.1","inheritsFrom":"26.3"}"#,
+    );
+    let profile = dir.join("profiles/Fabric 26.3");
+    fs::create_dir_all(&profile).unwrap();
+    let linked = s.0.join("linked");
+    let got = resolve_with(&profile, &[], &linked, &Mojang::new(MANIFEST)).unwrap();
+    assert_eq!(got, linked);
+    assert_linked(&linked, &dir.join("meta"), jar);
+}
+
 #[test]
 fn an_instance_folder_may_be_chosen() {
     let s = Scratch::new("instance");

From 50727eb5c3d389628549c9237bbcca76029c3b79 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:26:43 +0100
Subject: [PATCH 134/270] Harnesses: one scaffold for one-player dedicated
 server scripts

test_hardcore_respawn_parity.py copied test_locator_bar_parity.py's
build and run code; both now share locator.sides, and one-player
scripts run through locator.one_player.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/test_hardcore_respawn_parity.py | 114 +++-----------------------
 tools/test_locator_bar_parity.py      |  76 ++++++++++++++++-
 2 files changed, 84 insertions(+), 106 deletions(-)

diff --git a/tools/test_hardcore_respawn_parity.py b/tools/test_hardcore_respawn_parity.py
index 6e0669534..8c7a5394d 100644
--- a/tools/test_hardcore_respawn_parity.py
+++ b/tools/test_hardcore_respawn_parity.py
@@ -8,23 +8,12 @@ vanilla's protocol code) joins, runs /kill on itself and presses the death scree
 respawns the player, then makes it a spectator because the server is hardcore. The game mode changes and respawns
 Alice is sent in the death and respawn steps are compared exactly.
 """
-import json
-import os
-from pathlib import Path
-import platform
-import shutil
-import subprocess
 import sys
-import time
 
 try:
-    from . import lab, test_rust_parity as base, test_locator_bar_parity as locator
-    from .test_dedicated_server_parity import Server
+    from . import test_locator_bar_parity as locator
 except ImportError:
-    import lab
-    import test_rust_parity as base
     import test_locator_bar_parity as locator
-    from test_dedicated_server_parity import Server
 
 NAME = 'hardcore-respawn-parity'
 # server_dir and generate_world write these server.properties.
@@ -33,103 +22,24 @@ SCRIPT = [
     ('death', ['cmd Alice kill @s']),
     ('respawn', ['respawn Alice']),
 ]
-STEP_SECONDS = 4.0
-SHOWN = ('gamemode', 'respawn')
-
-
-def run_side(label, server_command, client_command, build, world):
-    directory = build / label
-    port = locator.server_dir(directory, world)
-    out = build / f'{label}.txt'
-    out.unlink(missing_ok=True)
-    server = Server(server_command, directory, label)
-    try:
-        server.wait_for(r'Done \(')
-        with (build / f'{label}-client.log').open('w') as log:
-            client = subprocess.Popen([*map(str, client_command), '127.0.0.1', str(port), str(out)],
-                                      cwd=lab.ROOT, stdin=subprocess.PIPE, stdout=log, stderr=subprocess.STDOUT,
-                                      text=True)
-
-            def tell(line):
-                client.stdin.write(line + '\n')
-                client.stdin.flush()
-            try:
-                tell('players on')
-                tell('state on')
-                tell('step joins')
-                tell('join Alice')
-                server.wait_for(r'Alice joined the game', timeout=120)
-                time.sleep(STEP_SECONDS)
-                for step, actions in SCRIPT:
-                    tell(f'step {step}')
-                    for action in actions:
-                        tell(action)
-                    time.sleep(STEP_SECONDS)
-                tell('end')
-                client.wait(timeout=60)
-            finally:
-                if client.poll() is None:
-                    client.kill()
-    finally:
-        server.stop()
-    if not out.exists():
-        raise AssertionError(f'{label}: the client wrote no transcript (see {build}/{label}-client.log)')
-    return out.read_text(encoding='utf-8').splitlines()
 
 
 def shown(lines):
     """Alice's game mode changes and respawns in the death and respawn steps."""
-    keep = []
-    for line in lines:
-        parts = line.split(' ', 3)
-        if len(parts) >= 3 and parts[1] in ('step=death', 'step=respawn') and parts[2] in SHOWN:
-            keep.append(line)
-    return keep
+    return [line for line in lines if len(parts := line.split(' ', 3)) >= 3
+            and parts[1] in ('step=death', 'step=respawn') and parts[2] in ('gamemode', 'respawn')]
+
+
+def check(vanilla, _):
+    if 'Alice step=respawn gamemode 3' not in vanilla:
+        return 'vanilla did not make the respawned player a spectator'
+    return None
 
 
 def main():
-    lock, jars, libraries = base.verify_artifacts()
-    build = lab.LOCAL / NAME
-    build.mkdir(parents=True, exist_ok=True)
-    report = build / 'report.json'
-    report.unlink(missing_ok=True)
-    oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java'
-    classes = build / 'classes'
-    shutil.rmtree(classes, ignore_errors=True)
-    classes.mkdir()
-    dependencies = os.pathsep.join(map(str, [jars['server'], *libraries]))
-    subprocess.run(['javac', '--release', str(lock['minecraft']['java_major']), '-proc:none', '-nowarn', '-sourcepath',
-                    lab.ROOT / 'mods/horizon/src/test/java', '-cp', dependencies, '-d', classes, oracle],
-                   cwd=lab.ROOT, check=True, capture_output=True)
-    subprocess.run(['cargo', 'build', '--release', '-p', 'horizon-client', '--bin', 'horizon-client'], cwd=lab.ROOT,
-                   check=True, capture_output=True)
-    metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--no-deps', '--format-version', '1'],
-                                                  cwd=lab.ROOT, text=True))
-    binary = Path(metadata['target_directory']) / 'release' / ('horizon-client.exe' if os.name == 'nt' else 'horizon-client')
-    vanilla_server = ['java', '-Xmx2g', '-Duser.timezone=UTC', '-cp', dependencies, 'net.minecraft.server.Main', 'nogui']
-    horizon_server = [binary, '--resources', lab.LOCAL / 'horizon-client/26.3', '--dedicated', '--nogui']
-    client = ['java', '-Xmx1g', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.LocatorBarClient']
-
-    world = locator.generate_world(vanilla_server, build)
-    vanilla_all = run_side('vanilla', vanilla_server, client, build, world)
-    horizon_all = run_side('horizon', horizon_server, client, build, world)
-    errors = [l for l in vanilla_all + horizon_all if ' error ' in f' {l} ' or 'disconnected' in l]
-    vanilla, horizon = shown(vanilla_all), shown(horizon_all)
-    if errors or vanilla != horizon:
-        import difflib
-        diff = '\n'.join(difflib.unified_diff(vanilla, horizon, 'vanilla', 'horizon', n=1, lineterm=''))
-        raise AssertionError(f'{len(errors)} errors, transcripts differ (see {build}/vanilla.txt and horizon.txt):\n'
-                             + '\n'.join(errors[:10]) + '\n' + diff[:6000])
-    if 'Alice step=respawn gamemode 3' not in vanilla:
-        raise AssertionError(f'vanilla did not make the respawned player a spectator: the script did not run '
-                             f'(see {build})')
-    lab.write_json(report, dict(
-        schema=1, minecraft=lock['minecraft']['version'], platform=platform.platform(),
-        java=subprocess.check_output(['java', '--version'], text=True).splitlines()[0],
-        lines=len(vanilla), output_sha256=lab.digest(build / 'horizon.txt', 'sha256'),
-        scope='A player dying and respawning in a hardcore world on a dedicated server: the respawn and the game '
-              'mode it is sent (spectator).'))
-    print(f'hardcore respawn: {len(vanilla)} lines identical')
+    lines = locator.one_player(NAME, SCRIPT, shown, check, 'A player dying and respawning in a hardcore world on a '
+                               'dedicated server: the respawn and the game mode it is sent (spectator).')
+    print(f'hardcore respawn: {len(lines)} lines identical')
 
 
 if __name__ == '__main__':
diff --git a/tools/test_locator_bar_parity.py b/tools/test_locator_bar_parity.py
index bc7d21750..985b87a35 100644
--- a/tools/test_locator_bar_parity.py
+++ b/tools/test_locator_bar_parity.py
@@ -205,12 +205,13 @@ def run_side(label, server_command, client_command, build, world):
     return out.read_text(encoding='utf-8').splitlines()
 
 
-def main():
+def sides(name):
+    """The vanilla and Horizon dedicated servers and the LocatorBarClient that joins them, built for harness
+    `name`: (lock, build directory, vanilla server, Horizon server, client) commands."""
     lock, jars, libraries = base.verify_artifacts()
-    build = lab.LOCAL / NAME
+    build = lab.LOCAL / name
     build.mkdir(parents=True, exist_ok=True)
-    report = build / 'report.json'
-    report.unlink(missing_ok=True)
+    (build / 'report.json').unlink(missing_ok=True)
     oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/LocatorBarClient.java'
     classes = build / 'classes'
     shutil.rmtree(classes, ignore_errors=True)
@@ -228,7 +229,74 @@ def main():
     vanilla_server = ['java', '-Xmx2g', '-Duser.timezone=UTC', '-cp', dependencies, 'net.minecraft.server.Main', 'nogui']
     horizon_server = [binary, '--resources', lab.LOCAL / 'horizon-client/26.3', '--dedicated', '--nogui']
     client = ['java', '-Xmx1g', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.LocatorBarClient']
+    return lock, build, vanilla_server, horizon_server, client
 
+
+def one_player(name, script, shown, check, scope, step_seconds=4.0):
+    """A harness of one player, Alice: on each server she joins, then runs `script`, a list of (step, client
+    actions) `step_seconds` apart. The lines `shown(transcript)` keeps must match vanilla's exactly, and
+    `check(vanilla's shown lines, vanilla's transcript)` returns why vanilla's run is no proof (the script did
+    not run), or None."""
+    lock, build, vanilla_server, horizon_server, client = sides(name)
+
+    def run(label, server_command, world):
+        directory = build / label
+        port = server_dir(directory, world)
+        out = build / f'{label}.txt'
+        out.unlink(missing_ok=True)
+        server = Server(server_command, directory, label)
+        try:
+            server.wait_for(r'Done \(')
+            with (build / f'{label}-client.log').open('w') as log:
+                process = subprocess.Popen([*map(str, client), '127.0.0.1', str(port), str(out)], cwd=lab.ROOT,
+                                           stdin=subprocess.PIPE, stdout=log, stderr=subprocess.STDOUT, text=True)
+
+                def tell(line):
+                    process.stdin.write(line + '\n')
+                    process.stdin.flush()
+                try:
+                    for line in ['players on', 'state on', 'step joins', 'join Alice']:
+                        tell(line)
+                    server.wait_for(r'Alice joined the game', timeout=120)
+                    time.sleep(step_seconds)
+                    for step, actions in script:
+                        tell(f'step {step}')
+                        for action in actions:
+                            tell(action)
+                        time.sleep(step_seconds)
+                    tell('end')
+                    process.wait(timeout=60)
+                finally:
+                    if process.poll() is None:
+                        process.kill()
+        finally:
+            server.stop()
+        if not out.exists():
+            raise AssertionError(f'{label}: the client wrote no transcript (see {build}/{label}-client.log)')
+        return out.read_text(encoding='utf-8').splitlines()
+
+    world = generate_world(vanilla_server, build)
+    vanilla_all = run('vanilla', vanilla_server, world)
+    horizon_all = run('horizon', horizon_server, world)
+    errors = [l for l in vanilla_all + horizon_all if ' error ' in f' {l} ' or 'disconnected' in l]
+    vanilla, horizon = shown(vanilla_all), shown(horizon_all)
+    if errors or vanilla != horizon:
+        import difflib
+        diff = '\n'.join(difflib.unified_diff(vanilla, horizon, 'vanilla', 'horizon', n=1, lineterm=''))
+        raise AssertionError(f'{len(errors)} errors, transcripts differ (see {build}/vanilla.txt and horizon.txt):\n'
+                             + '\n'.join(errors[:10]) + '\n' + diff[:6000])
+    if (why := check(vanilla, vanilla_all)) is not None:
+        raise AssertionError(f'{why}: the script did not run (see {build})')
+    lab.write_json(build / 'report.json', dict(
+        schema=1, minecraft=lock['minecraft']['version'], platform=platform.platform(),
+        java=subprocess.check_output(['java', '--version'], text=True).splitlines()[0],
+        lines=len(vanilla), output_sha256=lab.digest(build / 'horizon.txt', 'sha256'), scope=scope))
+    return vanilla
+
+
+def main():
+    lock, build, vanilla_server, horizon_server, client = sides(NAME)
+    report = build / 'report.json'
     world = generate_world(vanilla_server, build)
     vanilla = run_side('vanilla', vanilla_server, client, build, world)
     horizon = run_side('horizon', horizon_server, client, build, world)

From df23e1bfed0c2fde5d9c319ccae18fed3c6b036b Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:27:41 +0100
Subject: [PATCH 135/270] Keep vanilla's death screen message; resolve with the
 loaded language

- Leave ServerPlayer.die's message as it was: with showDeathMessages off
  vanilla sends CommonComponents.EMPTY to the death screen, and #1858
  reworks the death message from the combat record.
- The effects panel and recipe book tooltips use Names::display_get, so a
  key missing from the language still falls back instead of showing the key.
- net::load_language reuses the language lang already loaded (packs
  included) instead of reading it from disk again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan_actions.rs | 48 +++++++++----------
 crates/horizon-client/src/game/potions.rs     |  2 +-
 crates/horizon-client/src/game/recipe_book.rs |  2 +-
 crates/horizon-client/src/net.rs              | 18 ++++---
 4 files changed, 37 insertions(+), 33 deletions(-)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 03bb15b65..2c7019c73 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1791,33 +1791,33 @@ impl Game<'_> {
                 // ServerPlayer.die: dropAllDeathLoot unless a spectator, from the eyes less 0.3.
                 let drops = (g.game_mode != SPECTATOR)
                     .then(|| [at[0], at[1] + g.eye_height() - 0.3, at[2]]);
-                // ServerPlayer.die: the death screen always shows the message;
-                // chat only when the rule allows and the team does not hide it.
                 let cause = host.play.get_mut(&conn).and_then(|p| p.death_cause.take());
-                let key = cause.unwrap_or_else(|| {
-                    if at[1] < f64::from(horizon_client::chunk::MIN_Y - 64) {
-                        "death.attack.outOfWorld".into()
-                    } else {
-                        "death.attack.generic".into()
-                    }
-                });
-                let text =
-                    horizon_client::text::Text::translate(&key, &[self.player_text(&name, uuid)]);
-                let message = horizon_client::lan::data::component_nbt(&text.component());
-                if self.ui.rules.bool("show_death_messages") {
-                    let team = self.score.board.players_team(&name);
-                    if horizon_client::scoreboard::own_death_message_shown(team) {
-                        host.hub.system_message(message.clone());
-                        if self.options.dedicated.is_some() {
-                            super::dedicated::log(
-                                "INFO",
-                                &format!("System chat: {}", text.plain()),
-                            );
-                        } else if self.player.is_some() {
-                            self.system_message(text);
+                let message = match cause {
+                    // ServerPlayer.die: the death message, to everyone unless
+                    // the player's team hides it.
+                    Some(key) if self.ui.rules.bool("show_death_messages") => {
+                        let text = horizon_client::text::Text::translate(
+                            &key,
+                            &[self.player_text(&name, uuid)],
+                        );
+                        let message = horizon_client::lan::data::component_nbt(&text.component());
+                        let team = self.score.board.players_team(&name);
+                        if horizon_client::scoreboard::own_death_message_shown(team) {
+                            host.hub.system_message(message.clone());
+                            if self.options.dedicated.is_some() {
+                                super::dedicated::log(
+                                    "INFO",
+                                    &format!("System chat: {}", text.plain()),
+                                );
+                            } else if self.player.is_some() {
+                                self.system_message(text);
+                            }
                         }
+                        message
                     }
-                }
+                    Some(_) => literal(""),
+                    None => literal(&format!("{name} died")),
+                };
                 host.hub.send_to(
                     conn,
                     &C::PlayerCombatKill(play::PlayerCombatKill { id, message }),
diff --git a/crates/horizon-client/src/game/potions.rs b/crates/horizon-client/src/game/potions.rs
index 49e171ce1..b28c2fb4d 100644
--- a/crates/horizon-client/src/game/potions.rs
+++ b/crates/horizon-client/src/game/potions.rs
@@ -755,7 +755,7 @@ impl Game<'_> {
             image_width,
             &self.potions.effects.list,
             self.clock.rate(),
-            &|key| Some(horizon_client::lang::get(key)),
+            &|key| self.pack.names.display_get(key),
             &|text| self.gui.atlas.font.width(text).ceil() as i32,
         );
         if let Some(lines) = inventory_effects::paint(
diff --git a/crates/horizon-client/src/game/recipe_book.rs b/crates/horizon-client/src/game/recipe_book.rs
index f68460b7d..fd44041e5 100644
--- a/crates/horizon-client/src/game/recipe_book.rs
+++ b/crates/horizon-client/src/game/recipe_book.rs
@@ -502,7 +502,7 @@ impl Game<'_> {
                     horizon_client::item_tooltip::lines(
                         stack,
                         self.res.items().get(&stack.item),
-                        &|k| Some(horizon_client::lang::get(k)),
+                        &|k| self.pack.names.display_get(k),
                     )
                 })
             {
diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs
index 2b314f2a8..8acfa7ec9 100644
--- a/crates/horizon-client/src/net.rs
+++ b/crates/horizon-client/src/net.rs
@@ -597,14 +597,18 @@ pub fn json_text(v: &serde_json::Value, lang: &Language) -> String {
     }
 }
 
-/// The language a session resolves server-sent components with: the client's
-/// selected language, layered over `en_us` (`ClientLanguage.loadFrom`), so a
-/// menu title the server sends as a key follows the language screen.
+/// The language a session resolves server-sent components with: the selected
+/// one as `lang` loaded it (`en_us` under it, packs included), so a menu title
+/// the server sends as a key follows the language screen. A process with no
+/// language set (a dedicated server's log) reads en_us.json.
 pub fn load_language(resources: &std::path::Path) -> Language {
-    let root = resources.to_path_buf();
-    crate::lang::Language::load(&[&root], &crate::lang::code())
-        .map()
-        .clone()
+    if let Some(lang) = crate::lang::current() {
+        return lang.map().clone();
+    }
+    std::fs::read(resources.join("assets/minecraft/lang/en_us.json"))
+        .ok()
+        .and_then(|b| serde_json::from_slice(&b).ok())
+        .unwrap_or_default()
 }
 
 /// Ask a server for its status (ServerStatusPinger): MOTD, players and the

From 70aff6e90b1689bd2f365825fa34308aa46e65fa Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:30:01 +0100
Subject: [PATCH 136/270] Death screen: empty message with showDeathMessages
 off; forget a guest's record when they leave

- ServerPlayer.die sends CommonComponents.EMPTY to the death screen when
  showDeathMessages is off, as the local player's death_message already
  does; the combat record is only read when the rule is on.
- A guest's CombatTracker leaves guest_combat with them, so a long-running
  server doesn't keep one per connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan.rs         |  1 +
 crates/horizon-client/src/game/lan_actions.rs | 30 +++++++++++--------
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs
index 8460f54e6..4315cc56d 100644
--- a/crates/horizon-client/src/game/lan.rs
+++ b/crates/horizon-client/src/game/lan.rs
@@ -979,6 +979,7 @@ impl Game<'_> {
                         self.save_guest(&host, &guest);
                         host.models.remove(&guest.conn);
                         host.play.remove(&guest.conn);
+                        self.guest_combat.remove(&guest.conn);
                         if self.options.dedicated.is_some() && guest.placed {
                             super::dedicated::log(
                                 "INFO",
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index f5d419357..fec2f7251 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1807,18 +1807,19 @@ impl Game<'_> {
                 let drops = (g.game_mode != SPECTATOR)
                     .then(|| [at[0], at[1] + g.eye_height() - 0.3, at[2]]);
                 let cause = host.play.get_mut(&conn).and_then(|p| p.death_cause.take());
-                let me = self.player_text(&name, uuid);
-                let text = match cause {
-                    Some(key) => horizon_client::text::Text::translate(&key, &[me]),
-                    None if at[1] < f64::from(horizon_client::chunk::MIN_Y - 64) => {
-                        horizon_client::text::Text::translate("death.attack.outOfWorld", &[me])
-                    }
-                    None => self.guest_death_message(conn, me),
-                };
-                let message = horizon_client::lan::data::component_nbt(&text.component());
-                // ServerPlayer.die: the message goes to everyone unless the
-                // player's team hides it, and always to the dying player.
-                if self.ui.rules.bool("show_death_messages") {
+                // ServerPlayer.die: with showDeathMessages, the message goes to
+                // the dying player's death screen and to everyone the team lets
+                // see it; without it, the death screen gets an empty one.
+                let message = if self.ui.rules.bool("show_death_messages") {
+                    let me = self.player_text(&name, uuid);
+                    let text = match cause {
+                        Some(key) => horizon_client::text::Text::translate(&key, &[me]),
+                        None if at[1] < f64::from(horizon_client::chunk::MIN_Y - 64) => {
+                            horizon_client::text::Text::translate("death.attack.outOfWorld", &[me])
+                        }
+                        None => self.guest_death_message(conn, me),
+                    };
+                    let message = horizon_client::lan::data::component_nbt(&text.component());
                     let team = self.score.board.players_team(&name);
                     if horizon_client::scoreboard::own_death_message_shown(team) {
                         host.hub.system_message(message.clone());
@@ -1831,7 +1832,10 @@ impl Game<'_> {
                             self.system_message(text);
                         }
                     }
-                }
+                    message
+                } else {
+                    literal("")
+                };
                 host.hub.send_to(
                     conn,
                     &C::PlayerCombatKill(play::PlayerCombatKill { id, message }),

From 0609fb2bebdc082c335361c3da65a188a8f77ef0 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:30:37 +0100
Subject: [PATCH 137/270] Tooltip: lore after the enchantments, as
 ItemStack.addDetailsToTooltip

Vanilla adds LORE after CONTAINER, BANNER_PATTERNS, FIREWORKS,
POTION_CONTENTS, TRIM and the enchantments, and before the attribute
modifiers, not right under the name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/stations.rs | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/crates/horizon-client/src/game/stations.rs b/crates/horizon-client/src/game/stations.rs
index fd7bd2642..5d8a2c3fe 100644
--- a/crates/horizon-client/src/game/stations.rs
+++ b/crates/horizon-client/src/game/stations.rs
@@ -1674,12 +1674,6 @@ impl Game<'_> {
         if display.name_visible(self.screen == Screen::Creative) {
             lines.push((horizon_client::text::Text::legacy(&name), color));
         }
-        // ItemLore.addToTooltip: after the name, before other component lines.
-        if display.shows("minecraft:lore") {
-            for text in horizon_client::item_tooltip::lore_texts(stack) {
-                lines.push((text, u32::MAX));
-            }
-        }
         let translate = |k: &str| e.translate(k).map(str::to_owned);
         let push = |lines: &mut Vec<(horizon_client::text::Text, u32)>, s: String, c: u32| {
             lines.push((horizon_client::text::Text::legacy(&s), c));
@@ -1776,6 +1770,13 @@ impl Game<'_> {
                 );
             }
         }
+        // ItemLore.addToTooltip: after the enchantments, before the attributes
+        // (ItemStack.addDetailsToTooltip).
+        if display.shows("minecraft:lore") {
+            for text in horizon_client::item_tooltip::lore_texts(stack) {
+                lines.push((text, u32::MAX));
+            }
+        }
         // Spawner.appendHoverText: what a spawner or trial spawner item spawns.
         if display.shows("minecraft:block_entity_data")
             && matches!(

From 0298d109886f0679f3a3ae11d001f0b81224026c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:31:37 +0100
Subject: [PATCH 138/270] Shulker boxes: one canFitInsideContainerItems for
 both menus, and a unit test

The client's menu and the server's guest menus now share
menu::fits_inside_container_items, and a resource-backed test checks
that a guest's shulker box menu refuses shulker boxes by pickup,
shift-click and number key while other containers take them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/lan/menu.rs | 70 +++++++++++++++++++++------
 crates/horizon-client/src/menu.rs     | 13 ++---
 2 files changed, 61 insertions(+), 22 deletions(-)

diff --git a/crates/horizon-client/src/lan/menu.rs b/crates/horizon-client/src/lan/menu.rs
index fefcb1933..8e8772055 100644
--- a/crates/horizon-client/src/lan/menu.rs
+++ b/crates/horizon-client/src/lan/menu.rs
@@ -155,11 +155,9 @@ impl View<'_> {
         if self.container.is_none() && (5..=8).contains(&i) {
             return rules.armor_index(&stack.item) == Some(i - 5);
         }
-        // ShulkerBoxSlot.mayPlace: Item.canFitInsideContainerItems, false
-        // for shulker boxes.
         if self.shulker
             && self.container.as_ref().is_some_and(|c| i < c.len())
-            && stack.item.ends_with("shulker_box")
+            && !crate::menu::fits_inside_container_items(stack)
         {
             return false;
         }
@@ -675,6 +673,24 @@ mod tests {
         )
     }
 
+    /// The prepared resources' items, or None (the test is skipped) without them.
+    fn rules() -> Option<ItemRules> {
+        let root = std::env::var_os("HORIZON_RESOURCES")
+            .map(std::path::PathBuf::from)
+            .unwrap_or_else(|| {
+                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+                    .join("../../.local/horizon-client")
+                    .join(horizon_core::VANILLA_VERSION)
+            });
+        if !root.join("items.json").exists() {
+            eprintln!("skipping resource-backed menu check: {}", root.display());
+            return None;
+        }
+        let registry = horizon_world::level::data::load_registry(&root).unwrap();
+        let facts = crate::blocks::BlockFacts::load(&root, &registry).unwrap();
+        Some(ItemRules(Items::load(&root, &registry, &facts).unwrap()))
+    }
+
     fn contents(stack: &Option<ItemStack>) -> Vec<(String, u32)> {
         let inside = stack.as_ref().and_then(|s| s.data());
         inside.map_or(Vec::new(), |d| {
@@ -690,20 +706,9 @@ mod tests {
     /// slot; a stack clicked onto a bundle goes in, as far as it fits.
     #[test]
     fn guest_chest_clicks_fill_and_empty_bundles() {
-        let root = std::env::var_os("HORIZON_RESOURCES")
-            .map(std::path::PathBuf::from)
-            .unwrap_or_else(|| {
-                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-                    .join("../../.local/horizon-client")
-                    .join(horizon_core::VANILLA_VERSION)
-            });
-        if !root.join("items.json").exists() {
-            eprintln!("skipping resource-backed bundle check: {}", root.display());
+        let Some(rules) = rules() else {
             return;
-        }
-        let registry = horizon_world::level::data::load_registry(&root).unwrap();
-        let facts = crate::blocks::BlockFacts::load(&root, &registry).unwrap();
-        let rules = ItemRules(Items::load(&root, &registry, &facts).unwrap());
+        };
         let mut g = guest();
         let mut chest = vec![
             Some(ItemStack::new("minecraft:stone", 48)),
@@ -747,4 +752,37 @@ mod tests {
         );
         assert_eq!(contents(&view.get(2)), []);
     }
+
+    #[test]
+    fn guest_shulker_box_menu_refuses_shulker_boxes() {
+        let Some(rules) = rules() else {
+            return;
+        };
+        for shulker in [true, false] {
+            let mut g = guest();
+            let mut container = vec![None; 27];
+            let mut drag = None;
+            let mut view = View {
+                guest: &mut g,
+                container: Some(&mut container),
+                shulker,
+            };
+            // Carried onto an empty slot, shift-clicked from the hotbar
+            // (menu slot 27 + 27) and swapped in with the number key 1.
+            view.guest.carried = Some(ItemStack::new("minecraft:red_shulker_box", 1));
+            click(&mut view, &mut drag, 0, 0, input::PICKUP, &rules);
+            assert_eq!(view.get(0).is_none(), shulker);
+            view.guest.carried = None;
+            view.guest.inventory[0] = Some(ItemStack::new("minecraft:shulker_box", 1));
+            click(&mut view, &mut drag, 54, 0, input::QUICK_MOVE, &rules);
+            assert_eq!(view.guest.inventory[0].is_some(), shulker);
+            view.guest.inventory[0] = Some(ItemStack::new("minecraft:blue_shulker_box", 1));
+            click(&mut view, &mut drag, 5, 0, input::SWAP, &rules);
+            assert_eq!(view.get(5).is_none(), shulker);
+            // Anything else goes in.
+            view.guest.carried = Some(ItemStack::new("minecraft:diamond", 1));
+            click(&mut view, &mut drag, 9, 0, input::PICKUP, &rules);
+            assert!(view.get(9).is_some());
+        }
+    }
 }
diff --git a/crates/horizon-client/src/menu.rs b/crates/horizon-client/src/menu.rs
index 07e4ba2b9..764abe0d9 100644
--- a/crates/horizon-client/src/menu.rs
+++ b/crates/horizon-client/src/menu.rs
@@ -247,6 +247,12 @@ pub fn beacon_required_levels(effect: Option<&str>) -> i32 {
         .map_or(i32::MAX, |i| i as i32 + 1)
 }
 
+/// `Item.canFitInsideContainerItems` (`ShulkerBoxSlot.mayPlace`): shulker
+/// boxes cannot nest.
+pub fn fits_inside_container_items(stack: &ItemStack) -> bool {
+    !stack.item.ends_with("shulker_box")
+}
+
 /// The containers a menu spans.
 const PLAYER: usize = 0;
 const MAIN: usize = 1;
@@ -1210,11 +1216,6 @@ impl Menu {
         env.items.get(&stack.item).is_some_and(|i| i.fuel.is_some())
     }
 
-    /// `Item.canFitInsideContainerItems`: shulker boxes cannot nest.
-    fn fits_inside(stack: &ItemStack) -> bool {
-        !(stack.item.ends_with("shulker_box"))
-    }
-
     // ---- Slot ----
 
     fn may_place(&self, env: &Env, s: usize, stack: &ItemStack) -> bool {
@@ -1247,7 +1248,7 @@ impl Menu {
                         .as_deref()
                         .is_some_and(|m| i.equip_allowed.as_ref().is_none_or(|a| a.contains(m)))
             }),
-            Role::Shulker => Self::fits_inside(stack),
+            Role::Shulker => fits_inside_container_items(stack),
             Role::Fuel => Self::is_fuel(env, stack) || Self::is_bucket(stack),
             Role::Output | Role::CraftResult | Role::Inert => false,
             Role::CrafterIn => self.data.get(self.slots[s].index) != Some(&1),

From 71f0ffde4bf15a0d7b06a25a9bc4890ae0af344b Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:31:44 +0100
Subject: [PATCH 139/270] Prepare: a launcher's rewritten version file falls
 back to Mojang's (#1772)

Launchers like HMCL rewrite versions/<v>/<v>.json in the official layout
(same jars and libraries, their own fields), and horizon-prepare refused it
as a version Mojang may have republished. Mojang's copy saved as the imported
manifest.json is now used instead, and without one the error says the
launcher may have rewritten it and how to get Mojang's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-prepare/src/artifacts.rs | 67 ++++++++++++++++++++++---
 1 file changed, 60 insertions(+), 7 deletions(-)

diff --git a/crates/horizon-prepare/src/artifacts.rs b/crates/horizon-prepare/src/artifacts.rs
index 805dd80d4..bd22df079 100644
--- a/crates/horizon-prepare/src/artifacts.rs
+++ b/crates/horizon-prepare/src/artifacts.rs
@@ -199,13 +199,22 @@ pub(crate) fn import_manifest(lock: &Lock, minecraft: &Path) -> Result<Value, St
         }
         let checksum = digest(&source, "sha1")?;
         if !lock.manifest_accepted(&checksum) {
-            return Err(format!(
-                "{} is a {version} version file Horizon does not know yet (sha1 {checksum}); \
-                 Mojang may have republished it. Update Horizon, or report it if this is the latest release.",
-                source.display()
-            ));
-        }
-        if !(destination.exists() && digest(&destination, "sha1")? == checksum) {
+            // Another launcher's rewrite of Mojang's file (HMCL and PCL add their own fields to
+            // the same jars, #1772), or one Mojang republished: Mojang's own copy saved as the
+            // imported one is used instead.
+            let pinned = lock.pin("manifest_sha1")?;
+            if !(destination.exists() && lock.manifest_accepted(&digest(&destination, "sha1")?)) {
+                return Err(format!(
+                    "{} is not a {version} version file Horizon knows (sha1 {checksum}): your \
+                     launcher may have rewritten it, or Mojang republished it. Prepare from the \
+                     Horizon launcher, which downloads Mojang's own, or save \
+                     https://piston-meta.mojang.com/v1/packages/{pinned}/{version}.json as {} \
+                     and prepare again.",
+                    source.display(),
+                    destination.display()
+                ));
+            }
+        } else if !(destination.exists() && digest(&destination, "sha1")? == checksum) {
             fs::create_dir_all(&lock.directory).map_err(|e| e.to_string())?;
             fs::copy(&source, &destination).map_err(|e| e.to_string())?;
         }
@@ -1097,6 +1106,50 @@ mod tests {
         }
     }
 
+    /// A launcher that rewrites Mojang's version file in the official layout (HMCL, PCL: the same
+    /// id and jars, its own fields, #1772) is refused with what to do, and Mojang's own copy saved
+    /// as the imported one is then used.
+    #[test]
+    fn a_rewritten_version_file_falls_back_to_mojangs() {
+        let root = std::env::temp_dir().join(format!("horizon-rewritten-{}", std::process::id()));
+        let _ = fs::remove_dir_all(&root);
+        let mojang = r#"{"id":"9.9","javaVersion":{"majorVersion":25},"downloads":{"client":{"sha1":"c"},"server":{"sha1":"s"}}}"#;
+        let rewritten = r#"{"id":"9.9","javaVersion":{"majorVersion":25},"downloads":{"client":{"sha1":"c"},"server":{"sha1":"s"}},"patches":[],"root":true}"#;
+        let minecraft = root.join("minecraft");
+        fs::create_dir_all(minecraft.join("versions/9.9")).unwrap();
+        fs::write(minecraft.join("versions/9.9/9.9.json"), rewritten).unwrap();
+        fs::write(root.join("mojang.json"), mojang).unwrap();
+        let pinned = digest(&root.join("mojang.json"), "sha1").unwrap();
+        fs::write(
+            root.join("research-lock.json"),
+            format!(
+                r#"{{"minecraft":{{"version":"9.9","java_major":25,"manifest_sha1":"{pinned}","client_sha1":"c","server_sha1":"s"}}}}"#
+            ),
+        )
+        .unwrap();
+        let lock = Lock::read(&root).unwrap();
+        let destination = lock.directory.join("manifest.json");
+
+        let error = import_manifest(&lock, &minecraft).unwrap_err();
+        assert!(error.contains("may have rewritten it"), "{error}");
+        assert!(
+            error.contains(&format!("packages/{pinned}/9.9.json")),
+            "{error}"
+        );
+        assert!(
+            error.contains(&destination.display().to_string()),
+            "{error}"
+        );
+        assert!(!destination.exists());
+
+        fs::create_dir_all(&lock.directory).unwrap();
+        fs::copy(root.join("mojang.json"), &destination).unwrap();
+        let manifest = import_manifest(&lock, &minecraft).unwrap();
+        assert!(manifest.get("patches").is_none());
+        assert_eq!(digest(&destination, "sha1").unwrap(), pinned);
+        fs::remove_dir_all(&root).unwrap();
+    }
+
     /// scanfee's Prism Launcher 26.3 install on a Mac (#1487): Prism keeps natives under its own
     /// names and never downloads Netty's native transport, which the game runs without. Preparing
     /// still checks every other library, and the transport whenever the launcher has it.

From 1a39af6b623f3f12fc15ba609a016c2f4e4ea464 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:36:22 +0100
Subject: [PATCH 140/270] /pregen: plan any radius at once, and skip a strip's
 rows outside the circle

Pregen::new counted the area chunk by chunk and split the strips with
an i32 product: /pregen start 30000000 overflowed, then hung the server
thread for hours. Rows are now counted from the circle's half-width,
the strip edges in i64, and each strip starts and ends at the rows the
circle reaches, so a band never walks empty corner rows. Unit tests
check that every chunk of squares and circles is swept once and that
the largest radius plans at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/pregen.rs | 99 ++++++++++++++++++++++++-----
 1 file changed, 84 insertions(+), 15 deletions(-)

diff --git a/crates/horizon-client/src/pregen.rs b/crates/horizon-client/src/pregen.rs
index e714bcda2..01215928a 100644
--- a/crates/horizon-client/src/pregen.rs
+++ b/crates/horizon-client/src/pregen.rs
@@ -39,48 +39,69 @@ impl Pregen {
         let radius = radius.max(0);
         let (x0, width) = (center.0 - radius, 2 * radius + 1);
         let count = (width + STRIP_WIDTH - 1) / STRIP_WIDTH;
-        let strips = (0..count)
-            .map(|i| (x0 + width * i / count, x0 + width * (i + 1) / count - 1))
-            .collect();
+        // The columns `i * width / count` on, in i64: the product overflows
+        // for a radius of a few hundred thousand chunks.
+        let edge = |i: i32| x0 + (i64::from(width) * i64::from(i) / i64::from(count)) as i32;
+        let strips = (0..count).map(|i| (edge(i), edge(i + 1) - 1)).collect();
         let mut pregen = Self {
             center,
             radius,
             shape,
             strips,
             strip: 0,
-            row: center.1 - radius,
+            row: 0,
             done: 0,
             total: 0,
         };
         pregen.total = (center.1 - radius..=center.1 + radius)
             .map(|z| pregen.row_chunks(x0, x0 + width - 1, z))
             .sum();
+        pregen.row = pregen.rows().map_or(0, |r| r.0);
         pregen
     }
 
-    fn contains(&self, x: i32, z: i32) -> bool {
+    /// How far from the centre column the area reaches at `d` chunks from
+    /// the centre row (or, the same, from the centre column), if it does.
+    fn half_width(&self, d: i32) -> Option<i32> {
+        let (r, d) = (i64::from(self.radius), i64::from(d));
         match self.shape {
-            Shape::Square => true,
-            Shape::Circle => {
-                let (dx, dz) = (i64::from(x - self.center.0), i64::from(z - self.center.1));
-                dx * dx + dz * dz <= i64::from(self.radius) * i64::from(self.radius)
-            }
+            Shape::Square => (d.abs() <= r).then_some(self.radius),
+            Shape::Circle => (d * d <= r * r).then(|| (r * r - d * d).isqrt() as i32),
         }
     }
 
+    fn contains(&self, x: i32, z: i32) -> bool {
+        self.half_width(z - self.center.1)
+            .is_some_and(|h| (x - self.center.0).abs() <= h)
+    }
+
+    /// The area's chunks in columns `x0..=x1` of row `z`.
     fn row_chunks(&self, x0: i32, x1: i32, z: i32) -> u64 {
-        (x0..=x1).filter(|&x| self.contains(x, z)).count() as u64
+        self.half_width(z - self.center.1).map_or(0, |h| {
+            let (lo, hi) = (x0.max(self.center.0 - h), x1.min(self.center.0 + h));
+            (i64::from(hi) - i64::from(lo) + 1).max(0) as u64
+        })
+    }
+
+    /// The first and last rows of the current strip that hold chunks of the
+    /// area.
+    fn rows(&self) -> Option<(i32, i32)> {
+        let &(x0, x1) = self.strips.get(self.strip)?;
+        let nearest = (x0 - self.center.0).max(self.center.0 - x1).max(0);
+        let h = self.half_width(nearest)?;
+        Some((self.center.1 - h, self.center.1 + h))
     }
 
     /// The band streaming should hold now; none once every strip is done.
     pub fn band(&self) -> Option<Band> {
         let &(x0, x1) = self.strips.get(self.strip)?;
+        let (_, last) = self.rows()?;
         let rows = (BAND_CHUNKS + (x1 - x0)) / (x1 - x0 + 1);
         Some(Band {
             x0,
             x1,
             z0: self.row,
-            z1: (self.row + rows - 1).min(self.center.1 + self.radius),
+            z1: (self.row + rows - 1).min(last),
             circle: (self.shape == Shape::Circle).then_some((self.center, self.radius)),
         })
     }
@@ -89,16 +110,16 @@ impl Pregen {
     /// Returns whether the band moved.
     pub fn advance(&mut self, lit: impl Fn(i32, i32) -> bool) -> bool {
         let mut moved = false;
-        while let Some(&(x0, x1)) = self.strips.get(self.strip) {
+        while let (Some(&(x0, x1)), Some((_, last))) = (self.strips.get(self.strip), self.rows()) {
             let z = self.row;
             if !(x0..=x1).all(|x| !self.contains(x, z) || lit(x, z)) {
                 break;
             }
             self.done += self.row_chunks(x0, x1, z);
             self.row += 1;
-            if self.row > self.center.1 + self.radius {
+            if self.row > last {
                 self.strip += 1;
-                self.row = self.center.1 - self.radius;
+                self.row = self.rows().map_or(self.row, |r| r.0);
             }
             moved = true;
         }
@@ -120,3 +141,51 @@ impl Pregen {
         self.strip >= self.strips.len()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sweeps_every_chunk_of_the_area_once() {
+        for shape in [Shape::Square, Shape::Circle] {
+            for (center, radius) in [((0, 0), 0), ((3, -7), 5), ((-40, 12), 130), ((0, 0), 300)] {
+                let mut p = Pregen::new(center, radius, shape);
+                let r = i64::from(radius);
+                let area = (-radius..=radius)
+                    .flat_map(|dz| (-radius..=radius).map(move |dx| (dx, dz)))
+                    .filter(|&(dx, dz)| {
+                        shape == Shape::Square
+                            || i64::from(dx).pow(2) + i64::from(dz).pow(2) <= r * r
+                    })
+                    .count() as u64;
+                assert_eq!(p.total, area, "{shape:?} {radius}");
+                let mut seen = std::collections::HashSet::new();
+                while !p.finished() {
+                    let band = p.band().unwrap();
+                    assert!(band.z0 <= band.z1);
+                    let row = p.first_row();
+                    for &(x, z) in &row {
+                        assert!(seen.insert((x, z)), "{x} {z} twice");
+                    }
+                    assert!(
+                        p.advance(|x, z| z == band.z0 && row.contains(&(x, z))) || row.is_empty()
+                    );
+                }
+                assert_eq!(
+                    (p.done, seen.len() as u64),
+                    (area, area),
+                    "{shape:?} {radius}"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn a_huge_area_is_planned_at_once() {
+        let started = std::time::Instant::now();
+        let p = Pregen::new((0, 0), 30_000_000 >> 4, Shape::Circle);
+        assert!(p.total > 11_000_000_000_000);
+        assert!(started.elapsed() < std::time::Duration::from_secs(5));
+    }
+}

From b729cfc83361456ffcb3ff926dbb97ad617cf600 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:37:22 +0100
Subject: [PATCH 141/270] Furnace experience: createExperience's chance, orbs,
 every removal, guests

- createExperience floors count * experience and adds one with the chance of
  the fraction (a level random nextFloat); flooring alone paid nothing for a
  single iron ore (0.7).
- The payout pops ExperienceOrb.award's orbs at the player, recipe by recipe,
  instead of adding points directly.
- A server's player (the default single-player path, LAN and dedicated)
  gets it too: lan_machine_click pays when the guest takes from the output.
- AbstractFurnaceBlockEntity.preRemoveSideEffects pays at the block's centre
  on any removal (explosions, /setblock, creative breaking), after the
  contents spill, so it moves from break_block to the removal side effects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/containers.rs       | 69 ++++++++++---------
 crates/horizon-client/src/game.rs             | 64 ++++++++---------
 .../horizon-client/src/game/lan_crafting.rs   |  7 ++
 crates/horizon-client/src/game/spill.rs       | 19 ++++-
 4 files changed, 90 insertions(+), 69 deletions(-)

diff --git a/crates/horizon-client/src/containers.rs b/crates/horizon-client/src/containers.rs
index 3701fefaf..26ca193a2 100644
--- a/crates/horizon-client/src/containers.rs
+++ b/crates/horizon-client/src/containers.rs
@@ -488,25 +488,13 @@ impl Furnace {
             self.cooking_timer = 0;
         }
     }
-    /// `AbstractFurnaceBlockEntity.createExperience`: each recipe's own share is floored,
-    /// then the floors are added. Flooring the sum instead pays one point for two recipes
-    /// worth 0.6 each, which vanilla does not.
-    fn owed(used: &HashMap<String, u32>, experience: impl Fn(&str) -> f32) -> u32 {
-        used.iter()
-            .map(|(id, count)| (experience(id) * *count as f32).floor().max(0.0) as u32)
-            .sum()
-    }
-    /// What this furnace owes right now, without forgetting it: breaking the block reads
-    /// the same counter, and only a payout clears it.
-    pub fn experience_owed(&self, recipes: &Recipes) -> u32 {
-        Self::owed(&self.recipes_used, |id| recipes.cooking_experience(id))
-    }
-    /// `AbstractFurnaceBlockEntity.awardUsedRecipesAndPopExperience`: the experience this
-    /// furnace owes, forgotten as it is paid.
-    pub fn take_experience(&mut self, recipes: &Recipes) -> u32 {
-        let owed = self.experience_owed(recipes);
-        self.recipes_used.clear();
-        owed
+    /// `recipesUsed`, each recipe with its `experience` (0 for one this data pack does
+    /// not have), in the order `getRecipesToAwardAndPopExperience` pays them.
+    pub fn recipe_experience(&self, recipes: &Recipes) -> Vec<(u32, f32)> {
+        self.recipes_used
+            .iter()
+            .map(|(id, count)| (*count, recipes.cooking_experience(id)))
+            .collect()
     }
     /// A menu click wrote its slots into `items`, and `before` was the input
     /// slot until then: the menu called `setItem` on it only if it changed
@@ -621,23 +609,40 @@ fn total_time(time: u32, speed: f32) -> i32 {
     }
 }
 
+/// `AbstractFurnaceBlockEntity.createExperience`: `count * experience`, floored, and one
+/// more with the chance of what is left over (a level random draw only when there is some).
+pub fn create_experience(
+    count: u32,
+    experience: f32,
+    random: &mut impl horizon_core::random::RandomSource,
+) -> u32 {
+    let total = count as f32 * experience;
+    let whole = total.floor();
+    let fraction = total - whole;
+    let mut xp = whole.max(0.0) as u32;
+    if fraction != 0.0 && random.next_float() < fraction {
+        xp += 1;
+    }
+    xp
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use horizon_core::random::{LegacyRandom, RandomSource};
 
-    /// `createExperience` floors each recipe on its own. Two recipes worth 0.6 each pay
-    /// nothing, where flooring their sum would pay one point.
+    /// A whole amount pays itself without a draw; a fraction is a chance of one more.
     #[test]
-    fn experience_is_floored_per_recipe_and_not_on_the_sum() {
-        let mut used = HashMap::new();
-        used.insert("a".to_owned(), 1);
-        used.insert("b".to_owned(), 1);
-        assert_eq!(Furnace::owed(&used, |_| 0.6), 0);
-
-        used.insert("c".to_owned(), 10);
-        assert_eq!(
-            Furnace::owed(&used, |id| if id == "c" { 0.1 } else { 0.0 }),
-            1
-        );
+    fn create_experience_rounds_the_fraction_by_chance() {
+        let mut random = LegacyRandom::new(7);
+        let mut untouched = LegacyRandom::new(7);
+        assert_eq!(create_experience(4, 0.5, &mut random), 2);
+        assert_eq!(create_experience(3, 0.0, &mut random), 0);
+        assert_eq!(random.next_long(), untouched.next_long());
+        let paid: u32 = (0..1000)
+            .map(|_| create_experience(1, 0.35, &mut random))
+            .sum();
+        assert!((250..450).contains(&paid), "{paid}");
+        assert!((0..100).all(|_| (1..=2).contains(&create_experience(1, 1.7, &mut random))));
     }
 }
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 7c0bbc917..808ca087f 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -537,6 +537,8 @@ struct GameLevel<'w> {
     seed: i64,
     behaviours: &'w Behaviours,
     items: &'w Items,
+    /// Cooking recipes' experience, which a removed furnace pays out.
+    recipes: &'w horizon_client::crafting::Recipes,
     /// Container loot tables (`unpackLootTable`).
     loot: Option<std::sync::Arc<horizon_world::loot::LootData>>,
     registry: &'static horizon_world::registry::BlockRegistry,
@@ -2420,6 +2422,7 @@ impl Game<'_> {
             seed: self.level.seed,
             behaviours: self.res.behaviours(),
             items: self.res.items(),
+            recipes: self.res.recipes(),
             loot: horizon_client::structure_blocks::loot_data(&self.options.resources),
             registry: self.pack.assets.registry,
             rules,
@@ -3246,12 +3249,6 @@ impl Game<'_> {
         }
         // The block entity as it was, for what the drops copy from it.
         let key = (pos[0], pos[1], pos[2]);
-        // AbstractFurnaceBlockEntity.playerDestroy: the experience its recipes earned drops
-        // with the block. Read now, paid only if the block is really removed.
-        let furnace_xp = match self.world.block_entities.get(&key) {
-            Some(BlockEntity::Furnace(f)) => f.experience_owed(self.res.recipes()),
-            _ => 0,
-        };
         if let Some(entity) = self.world.block_entities.get(&key).cloned() {
             let name = self.world.block_names.get(&key).cloned();
             self.pending.record(pos, &entity, &facts.name, name);
@@ -3321,18 +3318,6 @@ impl Game<'_> {
                     );
                 }
             }
-            // Stored recipe experience is not a loot drop: it leaves with the block
-            // whatever the tool, as `AbstractFurnaceBlockEntity` does.
-            if furnace_xp > 0 {
-                self.spawn_orbs(
-                    [
-                        f64::from(pos[0]) + 0.5,
-                        f64::from(pos[1]) + 0.5,
-                        f64::from(pos[2]) + 0.5,
-                    ],
-                    furnace_xp,
-                );
-            }
         }
         self.pending.clear(pos);
         self.process_level_events()?;
@@ -6007,14 +5992,12 @@ impl Game<'_> {
                 self.player_drop(stack);
             }
             self.award_crafted(&crafted);
-            // shortcut: paid straight to the player instead of through `ExperienceOrb.award`
-            // (no orb flies at them), which a furnace's orbs reach within a tick anyway;
-            // upgrade if the visual matters or another block pays out far from the player.
-            if furnace_before > furnace_after {
-                let owed = self.take_furnace_experience();
-                if owed > 0 {
-                    self.give_orb_points(owed);
-                }
+            if furnace_before > furnace_after
+                && self.remote.is_none()
+                && let (Some(pos), Some(p)) = (self.container, self.player.as_ref())
+            {
+                let at = [p.position.x, p.position.y, p.position.z];
+                self.award_furnace_recipes(pos, at);
             }
         }
         if kind == Kind::Loom {
@@ -8807,17 +8790,26 @@ impl Game<'_> {
             self.give_orb_points(gained);
         }
     }
-    /// `AbstractFurnaceBlockEntity.awardUsedRecipesAndPopExperience`: what the open furnace
-    /// owes for everything it made since the last payout, cleared as it is read.
-    fn take_furnace_experience(&mut self) -> u32 {
-        let Some(pos) = self.container else {
-            return 0;
+    /// `FurnaceResultSlot.checkTakeAchievements`: the player took from the output of the
+    /// furnace at `pos`, which pops the experience of what it made at them
+    /// (`awardUsedRecipesAndPopExperience`) and forgets it.
+    pub(super) fn award_furnace_recipes(&mut self, pos: (i32, i32, i32), at: [f64; 3]) {
+        let used = match self.world.block_entities.get_mut(&pos) {
+            Some(BlockEntity::Furnace(f)) => {
+                let used = f.recipe_experience(self.res.recipes());
+                f.recipes_used.clear();
+                used
+            }
+            _ => return,
         };
-        let recipes = self.res.recipes();
-        let Some(BlockEntity::Furnace(f)) = self.world.block_entities.get_mut(&pos) else {
-            return 0;
-        };
-        f.take_experience(recipes)
+        for (count, experience) in used {
+            let xp = horizon_client::containers::create_experience(
+                count,
+                experience,
+                &mut self.world.random,
+            );
+            self.spawn_orbs(at, xp);
+        }
     }
     /// `Player.giveExperiencePoints`, and `giveExperienceLevels`' level-up
     /// sound every fifth level (at most every 100 ticks).
diff --git a/crates/horizon-client/src/game/lan_crafting.rs b/crates/horizon-client/src/game/lan_crafting.rs
index cb3b0a2c9..3199894dd 100644
--- a/crates/horizon-client/src/game/lan_crafting.rs
+++ b/crates/horizon-client/src/game/lan_crafting.rs
@@ -225,6 +225,7 @@ impl Game<'_> {
             Some(BlockEntity::Crafter(c)) => (Kind::CrafterBlock, c.items.to_vec()),
             _ => return false,
         };
+        let furnace = matches!(kind, Kind::Furnace(_));
         // CrafterBlockEntity.containerData: the disabled slots, then triggered.
         let crafter_data = match self.world.block_entities.get(&pos) {
             Some(BlockEntity::Crafter(c)) => Some((c.disabled, c.triggered)),
@@ -284,6 +285,12 @@ impl Game<'_> {
             }
             _ => {}
         }
+        // FurnaceResultSlot.checkTakeAchievements: the guest took from the output.
+        let count = |s: Option<&ItemStack>| s.map_or(0, |s| s.count);
+        if furnace && count(menu.slot(2)) < count(items[2].as_ref()) {
+            let at = host.hub.guests[gi].position;
+            self.award_furnace_recipes(pos, at);
+        }
         host.play.entry(conn).or_default().crafting.machine = Some((p.container, menu));
         host.hub.inventory_clicked(conn, p, &self.world, &changed);
         true
diff --git a/crates/horizon-client/src/game/spill.rs b/crates/horizon-client/src/game/spill.rs
index 20dcdf0de..b7283c57b 100644
--- a/crates/horizon-client/src/game/spill.rs
+++ b/crates/horizon-client/src/game/spill.rs
@@ -373,12 +373,29 @@ impl GameLevel<'_> {
         let mut neighbour_updates = 0;
         if side_effects {
             match kind {
-                PreRemove::Contents { slots, .. } => {
+                PreRemove::Contents { slots, furnace } => {
                     let items = entity.as_ref().map_or(&[][..], BlockEntity::slots);
                     for slot in 0..slots {
                         let stack = items.get(slot).cloned().flatten();
                         self.drop_item_stack(pos, stack);
                     }
+                    // AbstractFurnaceBlockEntity.preRemoveSideEffects: then the
+                    // experience of what it made, at the block's centre.
+                    if furnace && let Some(BlockEntity::Furnace(f)) = &entity {
+                        let at = [
+                            f64::from(pos.x) + 0.5,
+                            f64::from(pos.y) + 0.5,
+                            f64::from(pos.z) + 0.5,
+                        ];
+                        for (count, experience) in f.recipe_experience(self.recipes) {
+                            let xp = horizon_client::containers::create_experience(
+                                count,
+                                experience,
+                                &mut self.world.random,
+                            );
+                            self.award_orbs(at, xp);
+                        }
+                    }
                 }
                 PreRemove::Campfire => {
                     for _ in 0..4 {

From a495fcf7a7af9ee0cc475bbccb810ae1c23d9755 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:37:51 +0100
Subject: [PATCH 142/270] End crystal: one blast call for both paths

The respawn check is read before the blast, so the two copies of the
explosion collapse into one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/dragon.rs | 22 +++++++---------------
 1 file changed, 7 insertions(+), 15 deletions(-)

diff --git a/crates/horizon-client/src/game/dragon.rs b/crates/horizon-client/src/game/dragon.rs
index 701c09e64..ddd5a716b 100644
--- a/crates/horizon-client/src/game/dragon.rs
+++ b/crates/horizon-client/src/game/dragon.rs
@@ -880,30 +880,22 @@ impl Game<'_> {
             return;
         }
         let c = self.crystals.remove(index);
-        if self.fight.respawn.is_some()
+        // Read before the blast, which can take other respawn crystals.
+        let respawn_crystal = self.fight.respawn.is_some()
             && self
                 .fight
                 .respawn_crystals
                 .iter()
-                .any(|p| p.distance_squared(c.position) < 0.01)
-        {
-            if damage == CrystalDamage::Direct {
-                let at = [c.position.x, c.position.y, c.position.z];
-                let _ = self.server_explode(
-                    at,
-                    6.0,
-                    super::explosion::BlockInteraction::Destroy,
-                    false,
-                );
-            }
-            self.abort_respawn();
-            return;
-        }
+                .any(|p| p.distance_squared(c.position) < 0.01);
         if damage == CrystalDamage::Direct {
             let at = [c.position.x, c.position.y, c.position.z];
             let _ =
                 self.server_explode(at, 6.0, super::explosion::BlockInteraction::Destroy, false);
         }
+        if respawn_crystal {
+            self.abort_respawn();
+            return;
+        }
         // EnderDragonFight.onCrystalDestroyed.
         self.count_crystals();
         if let Some(d) = self.dragon.as_mut() {

From 0dfc6d8700554d0d0b8bfb93cc00cd14062daa49 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:38:28 +0100
Subject: [PATCH 143/270] command_exec harness: summoned mobs' saved attribute
 bases and health (#1483)

A cow summoned with max_health and movement_speed bases, and a zombie
with an attack_damage base and a saved Health, against vanilla.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/command_exec_corpus.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tools/command_exec_corpus.py b/tools/command_exec_corpus.py
index 0e376e260..be4e16a8a 100644
--- a/tools/command_exec_corpus.py
+++ b/tools/command_exec_corpus.py
@@ -291,6 +291,19 @@ def entities():
         cmd('/data get entity @e[tag=root,limit=1] Passengers[0].Health'),
         cmd('/data get entity @e[tag=root,limit=1] Passengers[0].id'),
         cmd('/kill @e[tag=root]'),
+        # Saved attribute bases are read for every mob, then Health or the max
+        # health when there is none (LivingEntity.readAdditionalSaveData, #1483).
+        cmd('/summon minecraft:cow 4.5 210 8.5 {Tags:["attr"],NoAI:1b,NoGravity:1b,'
+            'attributes:[{id:"minecraft:max_health",base:40.0d},{id:"minecraft:movement_speed",base:0.5d}]}'),
+        cmd('/data get entity @e[tag=attr,limit=1] Health'),
+        cmd('/attribute @e[tag=attr,limit=1] minecraft:max_health base get'),
+        cmd('/attribute @e[tag=attr,limit=1] minecraft:movement_speed base get'),
+        cmd('/kill @e[tag=attr]'),
+        cmd('/summon minecraft:zombie 4.5 210 8.5 {Tags:["attr"],NoAI:1b,NoGravity:1b,Health:7.0f,'
+            'attributes:[{id:"minecraft:attack_damage",base:9.0d}]}'),
+        cmd('/data get entity @e[tag=attr,limit=1] Health'),
+        cmd('/attribute @e[tag=attr,limit=1] minecraft:attack_damage base get'),
+        cmd('/kill @e[tag=attr]'),
         *setup('/kill @e[type=minecraft:armor_stand]'),
         {'op': 'tick', 'n': 25},
         cmd('/execute if entity @e[tag=h]'),

From 8c54e1858741b47dcca050cd5dc35b6d32f2d23c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:40:41 +0100
Subject: [PATCH 144/270] /ride dismount: the boats' BOARDING_COOLDOWN, not a
 second 60

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/boat_passengers.rs     | 2 +-
 crates/horizon-client/src/game/commands/world_cmds.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/boat_passengers.rs b/crates/horizon-client/src/game/boat_passengers.rs
index 96686f69b..7055cccfd 100644
--- a/crates/horizon-client/src/game/boat_passengers.rs
+++ b/crates/horizon-client/src/game/boat_passengers.rs
@@ -13,7 +13,7 @@ use horizon_client::{
 use horizon_core::geometry::{Aabb, Vec3};
 
 /// `Entity.boardingCooldown` once a mob leaves its boat.
-const BOARDING_COOLDOWN: i32 = 60;
+pub(super) const BOARDING_COOLDOWN: i32 = 60;
 /// `Player.DEFAULT_VEHICLE_ATTACHMENT`: how far below the seat a player's
 /// feet are.
 const PLAYER_RIDING_OFFSET: f64 = 0.6;
diff --git a/crates/horizon-client/src/game/commands/world_cmds.rs b/crates/horizon-client/src/game/commands/world_cmds.rs
index c8bd220be..30f019997 100644
--- a/crates/horizon-client/src/game/commands/world_cmds.rs
+++ b/crates/horizon-client/src/game/commands/world_cmds.rs
@@ -1191,7 +1191,7 @@ impl Game<'_> {
         };
         let m = &mut self.mobs[i];
         m.extra.passenger = false;
-        m.extra.boarding_cooldown = 60;
+        m.extra.boarding_cooldown = super::super::boat_passengers::BOARDING_COOLDOWN;
         m.position = at;
         m.previous = at;
     }

From b873f30c29b66a551b6f3744be5efa7468795c9c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:41:04 +0100
Subject: [PATCH 145/270] wears_freeze_immune above sync_player_body's doc
 comment, which it had taken over

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 4e4865c7a..6dd5f4678 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1837,13 +1837,6 @@ impl Game<'_> {
                 .is_some_and(|i| i.glider && (i.max_damage == 0 || s.damage + 1 < i.max_damage))
         })
     }
-    /// What the window decides for its player's body every tick, in frame and
-    /// on a server alike: the look (Player.travel steers sprint-swimming by
-    /// the pitch), Auto Jump (LocalPlayer.sendPosition), the slowdown of an
-    /// item in use (LocalPlayer.modifyInput), the helmet's Respiration
-    /// (decreaseAirSupply), the wings, leather boots on powder snow
-    /// (PowderSnowBlock.canEntityWalkOnPowderSnow), freeze-immune wear
-    /// (LivingEntity.canFreeze) and the dimension's FAST_LAVA.
     /// `LivingEntity.canFreeze`'s armor half: any worn piece in
     /// `freeze_immune_wearables`.
     pub(crate) fn wears_freeze_immune(&self) -> bool {
@@ -1857,6 +1850,13 @@ impl Game<'_> {
             .flatten()
             .any(|s| immune.is_some_and(|t| t.contains(&*s.item)))
     }
+    /// What the window decides for its player's body every tick, in frame and
+    /// on a server alike: the look (Player.travel steers sprint-swimming by
+    /// the pitch), Auto Jump (LocalPlayer.sendPosition), the slowdown of an
+    /// item in use (LocalPlayer.modifyInput), the helmet's Respiration
+    /// (decreaseAirSupply), the wings, leather boots on powder snow
+    /// (PowderSnowBlock.canEntityWalkOnPowderSnow), freeze-immune wear
+    /// (LivingEntity.canFreeze) and the dimension's FAST_LAVA.
     pub(crate) fn sync_player_body(&mut self) {
         let glider = self.glider_worn();
         let item_use_speed = self

From 644384763338a5912405063d25ef52e60995d322 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:42:00 +0100
Subject: [PATCH 146/270] Launcher: add the panorama, Unifont, languages and
 sounds prepared resources lack

Versions prepared while the asset store could not be read (Prism Launcher
installs since 0.2.48) are silent with a grey title screen. Like the built-in
packs (#1539), the launcher now copies each of these from the player's own
asset store into prepared resources that lack it, at start, after an install
and before Play, without preparing again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/backend.rs | 241 +++++++++++++++++++++++++++++-----------
 launcher/src/main.rs    |   7 +-
 2 files changed, 178 insertions(+), 70 deletions(-)

diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 9d1eeb111..a7485468a 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -552,7 +552,7 @@ pub fn install(release: &Release, progress: impl Fn(f32)) -> Result<(), String>
     fs::write(target.join(COMPLETE), "").map_err(|e| e.to_string())?;
     let _ = fs::remove_dir_all(&partial);
     reuse_prepared(&root, tag);
-    complete_packs(tag);
+    complete_assets(tag);
     progress(1.0);
     Ok(())
 }
@@ -774,13 +774,13 @@ fn reuse_prepared(versions: &Path, tag: &str) -> Option<String> {
 /// `reuse_prepared` for every installed version that is not prepared, oldest first, so a
 /// version prepared this way can serve the next. Launchers before 0.1.4 installed new versions
 /// without it; this catches those up. Returns each (version, where its resources came from).
-/// Prepared versions also get the run-time reports (`complete_reports`) and built-in packs
-/// (`complete_packs`) they lack.
+/// Prepared versions also get the run-time reports (`complete_reports`) and the built-in packs,
+/// panorama and sounds (`complete_assets`) they lack.
 pub fn reuse_prepared_everywhere() -> Vec<(String, String)> {
     let versions = versions_dir();
     let reused = reuse_prepared_in(&versions);
     for tag in installed_in(&versions) {
-        complete_packs(&tag);
+        complete_assets(&tag);
     }
     reused
 }
@@ -856,19 +856,77 @@ fn complete_reports(versions: &Path, tag: &str) -> bool {
     complete
 }
 
-/// Adds vanilla's built-in Programmer Art and High Contrast packs to a prepared version that
-/// lacks them, as `horizon-prepare packs` does: preparers before #1538 left them out, and a new
-/// version reuses the resources of the one before (`reuse_prepared`). They come from the player's
-/// own Minecraft asset store; without them there, one line in the log, once per launcher run, and
-/// the version plays as before. Nothing is prepared again.
-pub fn complete_packs(tag: &str) {
-    complete_packs_in(&versions_dir(), tag, minecraft_folders, &|line| {
+/// What a prepared version may lack that the launcher adds without preparing again, each copied
+/// from the player's own Minecraft asset store as `horizon-prepare <kind>` does: what the
+/// player misses without it, whether the resources lack it, and the copy.
+type Completion = (
+    &'static str,
+    fn(&Path) -> bool,
+    fn(&Path, Option<&Path>, horizon_prepare::Log) -> Result<PathBuf, String>,
+);
+
+const COMPLETIONS: [Completion; 5] = [
+    // Preparers before #1538 left the built-in packs out.
+    (
+        "Programmer Art and High Contrast",
+        lacks_packs,
+        horizon_prepare::packs,
+    ),
+    // A preparation that could not read the asset store keeps the client jar's 1x1 grey
+    // placeholders, its English alone, and no sounds (#1867: Prism Launcher installs prepared
+    // since 0.2.48).
+    (
+        "The title panorama",
+        lacks_panorama,
+        horizon_prepare::panorama,
+    ),
+    ("The Unifont glyphs", lacks_unifont, horizon_prepare::fonts),
+    ("The languages", lacks_languages, horizon_prepare::languages),
+    (
+        "The sounds",
+        |resources| !sounds_in(resources),
+        horizon_prepare::sounds,
+    ),
+];
+
+fn lacks_unifont(resources: &Path) -> bool {
+    !resources
+        .join("assets/minecraft/font/unifont.zip")
+        .is_file()
+}
+
+/// Whether `en_us`, the one language the client jar has, is the only one.
+fn lacks_languages(resources: &Path) -> bool {
+    fs::read_dir(resources.join("assets/minecraft/lang")).map_or(true, |dir| dir.count() <= 1)
+}
+
+fn lacks_packs(resources: &Path) -> bool {
+    horizon_prepare::BUILT_IN_PACKS
+        .iter()
+        .any(|pack| !resources.join("assets").join(pack).is_file())
+}
+
+/// Whether the first panorama face is missing or the client jar's 1x1 placeholder (a PNG's
+/// width is the big-endian word at byte 16, in the IHDR chunk).
+fn lacks_panorama(resources: &Path) -> bool {
+    let face = resources.join("assets/minecraft/textures/gui/title/background/panorama_0.png");
+    fs::read(face).map_or(true, |png| {
+        png.get(16..20).is_none_or(|width| width == [0, 0, 0, 1])
+    })
+}
+
+/// Adds what a prepared version lacks of `COMPLETIONS`: a new version reuses the resources of the
+/// one before (`reuse_prepared`), which may come from a preparer that left them out. Without them
+/// in any Minecraft folder, one line each in the log, once per launcher run, and the version plays
+/// as before. Nothing is prepared again.
+pub fn complete_assets(tag: &str) {
+    complete_assets_in(&versions_dir(), tag, minecraft_folders, &|line| {
         eprintln!("{line}")
     });
 }
 
-/// `folders`: where to look, asked only when the version lacks a pack.
-fn complete_packs_in(
+/// `folders`: where to look, asked only when the version lacks something.
+fn complete_assets_in(
     versions: &Path,
     tag: &str,
     folders: impl Fn() -> Vec<PathBuf>,
@@ -879,37 +937,41 @@ fn complete_packs_in(
     static TRIED: Mutex<Vec<PathBuf>> = Mutex::new(Vec::new());
     let root = versions.join(tag);
     let resources = resources_at(&root);
-    let lacking = || {
-        resources.join(RESOURCES_MANIFEST).exists()
-            && horizon_prepare::BUILT_IN_PACKS
-                .iter()
-                .any(|pack| !resources.join("assets").join(pack).is_file())
+    let lacking = || -> Vec<&Completion> {
+        if !resources.join(RESOURCES_MANIFEST).exists() {
+            return Vec::new();
+        }
+        COMPLETIONS
+            .iter()
+            .filter(|(_, lacks, _)| lacks(&resources))
+            .collect()
     };
-    if !lacking() {
+    if lacking().is_empty() {
         return;
     }
     let mut tried = TRIED.lock().unwrap_or_else(|e| e.into_inner());
-    if tried.contains(&root) || !lacking() {
+    let lacking = lacking();
+    if tried.contains(&root) || lacking.is_empty() {
         return;
     }
     tried.push(root.clone());
-    let mut first_error = None;
-    for folder in folders() {
-        let copied = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            horizon_prepare::packs(&root, Some(&folder), &|line| log(line.to_string()))
-        }))
-        .unwrap_or_else(|_| Err("the copy stopped unexpectedly".into()));
-        match copied {
-            Ok(_) => return,
-            Err(e) => {
-                first_error.get_or_insert(e);
-            }
+    let folders = folders();
+    for (what, _, copy) in lacking {
+        let mut first_error = None;
+        let added = folders.iter().any(|folder| {
+            let copied = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                copy(&root, Some(folder), &|line| log(line.to_string()))
+            }))
+            .unwrap_or_else(|_| Err("the copy stopped unexpectedly".into()));
+            copied.map_err(|e| first_error.get_or_insert(e)).is_ok()
+        });
+        if !added {
+            log(format!(
+                "{tag}: {what} not added: {}",
+                first_error.unwrap_or_else(|| "no Minecraft folder found".into())
+            ));
         }
     }
-    log(format!(
-        "{tag}: Programmer Art and High Contrast not added: {}",
-        first_error.unwrap_or_else(|| "no Minecraft folder found".into())
-    ));
 }
 
 /// The Minecraft folders whose asset store can hold what a prepared version lacks: the one
@@ -1635,7 +1697,7 @@ pub fn need_prepared(tag: &str) -> Result<(), String> {
 /// The client's command, once its resources are prepared.
 pub fn client(tag: &str) -> Result<Command, String> {
     need_prepared(tag)?;
-    complete_packs(tag);
+    complete_assets(tag);
     crate::browser::horizon::before_play(&game_home());
     let mut cmd = client_command(tag);
     // A sign-in that can't be renewed (no network, expired) still lets the game start, offline.
@@ -3069,7 +3131,7 @@ mod tests {
     }
 
     #[test]
-    fn prepared_versions_get_the_built_in_packs_without_preparing_again() {
+    fn prepared_versions_get_what_the_asset_store_adds_without_preparing_again() {
         let dir = std::env::temp_dir().join(format!(
             "horizon-launcher-packs-test-{}",
             std::process::id()
@@ -3080,17 +3142,42 @@ mod tests {
             fs::create_dir_all(path.parent().unwrap()).unwrap();
             fs::write(path, data).unwrap();
         };
-        // An official launcher folder whose asset store holds the two packs.
-        let packs = horizon_prepare::BUILT_IN_PACKS.map(|name| (name, name.as_bytes()));
+        // An official launcher folder whose asset store holds the two packs, a panorama (fake
+        // 2x2 PNG headers), Unifont, a language and the sound list.
+        let background = "minecraft/textures/gui/title/background";
+        let png = |n: u8| {
+            let mut data = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR\0\0\0\x02\0\0\0\x02".to_vec();
+            data.push(n);
+            data
+        };
+        let mut assets: Vec<(String, Vec<u8>)> = horizon_prepare::BUILT_IN_PACKS
+            .iter()
+            .map(|name| (name.to_string(), name.as_bytes().to_vec()))
+            .collect();
+        for face in ["0", "1", "2", "3", "4", "5", "overlay"] {
+            assets.push((
+                format!("{background}/panorama_{face}.png"),
+                png(face.as_bytes()[0]),
+            ));
+        }
+        for name in [
+            "minecraft/font/include/unifont.json",
+            "minecraft/font/unifont.zip",
+            "pack.mcmeta",
+            "minecraft/lang/fr_fr.json",
+            "minecraft/sounds.json",
+        ] {
+            assets.push((name.into(), format!("{{\"{name}\": 1}}").into_bytes()));
+        }
         let mut index = serde_json::Map::new();
-        for (name, data) in packs {
+        for (name, data) in &assets {
             let hash = sources::sha1_hex(data);
             write(
                 store.join("assets/objects").join(&hash[..2]).join(&hash),
                 data,
             );
             index.insert(
-                name.into(),
+                name.clone(),
                 serde_json::json!({"hash": hash, "size": data.len()}),
             );
         }
@@ -3105,6 +3192,8 @@ mod tests {
         .to_string();
         write(store.join("versions/9.9/9.9.json"), manifest.as_bytes());
         fs::create_dir_all(&empty).unwrap();
+        // The client jar's 1x1 placeholder.
+        let placeholder = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR\0\0\0\x01\0\0\0\x01";
         let release = |tag: &str, prepared: bool| {
             let root = versions.join(tag);
             write(root.join(COMPLETE), b"");
@@ -3112,27 +3201,27 @@ mod tests {
                 "client_sha1": "c", "server_sha1": "s", "manifest_sha1": sources::sha1_hex(manifest.as_bytes())}});
             write(root.join("research-lock.json"), lock.to_string().as_bytes());
             if prepared {
-                write(resources_at(&root).join(RESOURCES_MANIFEST), b"{}");
+                let resources = resources_at(&root);
+                write(resources.join(RESOURCES_MANIFEST), b"{}");
+                write(resources.join("assets/minecraft/lang/en_us.json"), b"{}");
                 write(
-                    resources_at(&root).join("assets/minecraft/lang/en_us.json"),
-                    b"{}",
+                    resources
+                        .join("assets")
+                        .join(background)
+                        .join("panorama_0.png"),
+                    placeholder,
                 );
             }
         };
         let lines = std::cell::RefCell::new(Vec::new());
         let log = |line: String| lines.borrow_mut().push(line);
-        let pack = |tag: &str, i: usize| {
-            fs::read(
-                resources_at(&versions.join(tag))
-                    .join("assets")
-                    .join(packs[i].0),
-            )
-            .ok()
+        let asset = |tag: &str, name: &str| {
+            fs::read(resources_at(&versions.join(tag)).join("assets").join(name)).ok()
         };
 
-        // Resources prepared before the packs were: a folder without an asset store is skipped.
+        // Resources prepared without any of them: a folder without an asset store is skipped.
         release("v0.2.1", true);
-        complete_packs_in(
+        complete_assets_in(
             &versions,
             "v0.2.1",
             || vec![empty.clone(), store.clone()],
@@ -3140,37 +3229,55 @@ mod tests {
         );
         assert_eq!(
             *lines.borrow(),
-            ["Built-in pack assets ready: 2 files, 0.0 MB"]
+            [
+                "Built-in pack assets ready: 2 files, 0.0 MB",
+                "Panorama assets ready: 7 files, 0.0 MB",
+                "Font assets ready: 2 files, 0.0 MB",
+                "Language assets ready: 2 files, 0.0 MB",
+                "Sound assets ready: 1 files, 0.0 MB",
+            ]
         );
-        for (i, (_, data)) in packs.iter().enumerate() {
-            assert_eq!(pack("v0.2.1", i).as_deref(), Some(*data));
+        for (name, data) in &assets {
+            assert_eq!(asset("v0.2.1", name).as_ref(), Some(data), "{name}");
         }
         // Nothing else is prepared again.
         let resources = resources_at(&versions.join("v0.2.1"));
         assert_eq!(fs::read(resources.join(RESOURCES_MANIFEST)).unwrap(), b"{}");
-        assert!(!resources.join("assets/minecraft/sounds.json").exists());
 
-        // No asset store anywhere: one line, the version stays prepared, and no second try.
+        // No asset store anywhere: one line each, the version stays prepared, and no second try.
         lines.borrow_mut().clear();
         release("v0.2.2", true);
-        complete_packs_in(&versions, "v0.2.2", || vec![empty.clone()], &log);
-        complete_packs_in(&versions, "v0.2.2", || vec![empty.clone()], &log);
-        assert_eq!(lines.borrow().len(), 1);
-        assert!(
-            lines.borrow()[0].starts_with("v0.2.2: Programmer Art and High Contrast not added: "),
-            "{lines:?}"
+        complete_assets_in(&versions, "v0.2.2", || vec![empty.clone()], &log);
+        complete_assets_in(&versions, "v0.2.2", || vec![empty.clone()], &log);
+        let what = lines
+            .borrow()
+            .iter()
+            .map(|line| line.split(" not added: ").next().unwrap().to_string())
+            .collect::<Vec<_>>();
+        assert_eq!(
+            what,
+            [
+                "v0.2.2: Programmer Art and High Contrast",
+                "v0.2.2: The title panorama",
+                "v0.2.2: The Unifont glyphs",
+                "v0.2.2: The languages",
+                "v0.2.2: The sounds",
+            ]
         );
         assert!(resources_at(&versions.join("v0.2.2"))
             .join(RESOURCES_MANIFEST)
             .exists());
-        assert_eq!(pack("v0.2.2", 0), None);
+        assert_eq!(
+            asset("v0.2.2", &format!("{background}/panorama_0.png")).as_deref(),
+            Some(&placeholder[..])
+        );
 
         // Not prepared, or complete: nothing to do, without even looking for a Minecraft folder.
         lines.borrow_mut().clear();
         release("v0.2.3", false);
         let unasked = || -> Vec<PathBuf> { unreachable!("no folder is needed") };
-        complete_packs_in(&versions, "v0.2.3", unasked, &log);
-        complete_packs_in(&versions, "v0.2.1", unasked, &log);
+        complete_assets_in(&versions, "v0.2.3", unasked, &log);
+        complete_assets_in(&versions, "v0.2.1", unasked, &log);
         assert!(lines.borrow().is_empty());
         assert!(!resources_at(&versions.join("v0.2.3")).exists());
         let _ = fs::remove_dir_all(&dir);
diff --git a/launcher/src/main.rs b/launcher/src/main.rs
index afc8dde45..9105f71a2 100644
--- a/launcher/src/main.rs
+++ b/launcher/src/main.rs
@@ -831,13 +831,14 @@ impl Launcher {
         // A little earlier than the spawn: file times can be coarse.
         self.client_started =
             Some(std::time::SystemTime::now() - std::time::Duration::from_secs(2));
-        // The built-in packs the resources lack and the session (a network round trip when the
-        // token needs renewing) come first; `drain` starts the game when the session arrives.
+        // What the resources lack (built-in packs, panorama, sounds) and the session (a network
+        // round trip when the token needs renewing) come first; `drain` starts the game when the
+        // session arrives.
         self.starting_client = Some(tag.clone());
         self.play_pressed = Some(Instant::now());
         let tx = self.tx.clone();
         std::thread::spawn(move || {
-            backend::complete_packs(&tag);
+            backend::complete_assets(&tag);
             let session = (|| {
                 let mut accounts = Accounts::load();
                 let Some((a, secrets)) = account::session_for_launch(

From 9fe77c7a56042ceb82ee634f0abc1610ede4f767 Mon Sep 17 00:00:00 2001
From: Alexander Krylov <sashakryllov58@gmail.com>
Date: Sun, 25 Oct 2026 19:49:02 +0300
Subject: [PATCH 147/270] Creative: a stack keeps its components when it
 crosses the wire

`Game::to_network` wrote damage alone into SetCreativeModeSlot, and
`item_from_network` read back damage and enchantments, so anything else a
creative stack carried was gone once the server echoed the inventory: a
named sword lost its name, trimmed armour its trim, an enchanted book its
stored enchantments and its repair cost.

`item_sync` is the pair for the components Horizon models: `encode` writes
them with the synced registries' ids (an unknown name is left out rather
than sent as id 0, which is a different entry) and `apply` reads them back
into the same `StackData` fields `item_data::decode_components` fills.

Potions are not carried yet: `minecraft:potion_contents` has no id or codec
in horizon-protocol, so a creative potion still arrives as an uncraftable
one (#1832). Nor are containers, charged projectiles, written books and a
map id, which the packet models but this patch does not write.

Refs #1832

Co-Authored-By: Hermes Agent (Nous Research) <noreply@nousresearch.com>
---
 crates/horizon-client/src/game/lan_actions.rs |  19 +-
 crates/horizon-client/src/game/remote.rs      |  12 +-
 crates/horizon-client/src/item_data.rs        |   2 +-
 crates/horizon-client/src/item_sync.rs        | 170 ++++++++++++++++++
 crates/horizon-client/src/lan/hub.rs          |   8 +
 crates/horizon-client/src/lib.rs              |   1 +
 crates/horizon-protocol/src/registry.rs       |   6 +
 7 files changed, 204 insertions(+), 14 deletions(-)
 create mode 100644 crates/horizon-client/src/item_sync.rs

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..1b4989055 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1216,21 +1216,22 @@ impl Game<'_> {
         host: &LanHost,
         stack: &Option<horizon_protocol::item::Stack>,
     ) -> Option<ItemStack> {
-        use horizon_protocol::item::{Component, component};
         let s = stack.as_ref()?;
         let name = host
             .hub
             .item_name(s.item)
             .unwrap_or_else(|| "minecraft:air".into());
         let mut out = ItemStack::new(&name, s.count.max(1) as u32);
-        out.damage = s.damage().max(0) as u32;
-        if let Some(Component::Enchantments(list)) = s.component(component::ENCHANTMENTS) {
-            for (id, level) in list {
-                if let Some(e) = host.hub.enchantment_name(*id) {
-                    out.enchant(&e, *level as u32);
-                }
-            }
-        }
+        // The same components the encoder wrote, so a creative slot keeps what
+        // the client held instead of just damage and enchantments.
+        horizon_client::item_sync::apply(
+            s,
+            &mut out,
+            |id| host.hub.enchantment_name(id).map(|n| n.into()),
+            |id| host.hub.trim_name("minecraft:trim_material", id),
+            |id| host.hub.trim_name("minecraft:trim_pattern", id),
+        );
+        out.tidy();
         Some(out)
     }
 
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index a3ab8d281..bbd688eef 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -761,10 +761,14 @@ impl Game<'_> {
     fn to_network(&self, s: &Option<ItemStack>) -> Option<Stack> {
         let s = s.as_ref()?;
         let mut stack = Stack::new(self.item_id(&s.item), s.count as i32);
-        if s.damage > 0 {
-            stack.added.push((
-                horizon_protocol::item::component::DAMAGE,
-                horizon_protocol::item::Component::Int(s.damage as i32),
+        // The components the client models, with the synced registries' ids:
+        // without them the server's echo hands back a bare item.
+        if let Some(r) = self.remote.as_ref() {
+            stack.added.extend(horizon_client::item_sync::encode(
+                s,
+                |name| r.registries.id("minecraft:enchantment", name),
+                |name| r.registries.id("minecraft:trim_material", name),
+                |name| r.registries.id("minecraft:trim_pattern", name),
             ));
         }
         Some(stack)
diff --git a/crates/horizon-client/src/item_data.rs b/crates/horizon-client/src/item_data.rs
index c07e2f352..00fd0f074 100644
--- a/crates/horizon-client/src/item_data.rs
+++ b/crates/horizon-client/src/item_data.rs
@@ -291,7 +291,7 @@ fn filterable_text(t: &Tag) -> Option<String> {
         None => read_text(t),
     }
 }
-fn read_text(t: &Tag) -> Option<String> {
+pub(crate) fn read_text(t: &Tag) -> Option<String> {
     match t {
         Tag::String(s) => Some(s.to_string_lossy()),
         // A component's root `text` may be empty with the visible words in
diff --git a/crates/horizon-client/src/item_sync.rs b/crates/horizon-client/src/item_sync.rs
new file mode 100644
index 000000000..4e48498ac
--- /dev/null
+++ b/crates/horizon-client/src/item_sync.rs
@@ -0,0 +1,170 @@
+//! The data components a stack keeps when it crosses the wire, and how the
+//! other side reads them back. A creative slot's packet carries a component
+//! patch, and before this the encoder wrote damage alone, so everything else
+//! (enchantments, a custom name, trim, repair cost) was gone once the server
+//! echoed the inventory back.
+use crate::item_data::{Levels, StackData};
+use crate::items::ItemStack;
+use horizon_protocol::item::{Component, Stack, component};
+use horizon_world::nbt::Tag;
+use std::sync::Arc;
+
+/// `Slot.STREAM_CODEC`'s patch for the components Horizon models, with the
+/// registries' ids for enchantments and trim. A name the registry does not
+/// know is left out: id 0 is a different entry, not a missing one.
+pub fn encode(
+    stack: &ItemStack,
+    enchantment: impl Fn(&str) -> Option<i32>,
+    trim_material: impl Fn(&str) -> Option<i32>,
+    trim_pattern: impl Fn(&str) -> Option<i32>,
+) -> Vec<(i32, Component)> {
+    let mut out = Vec::new();
+    if stack.damage > 0 {
+        out.push((component::DAMAGE, Component::Int(stack.damage as i32)));
+    }
+    let Some(d) = stack.data() else {
+        return out;
+    };
+    let levels = |levels: &Levels| -> Option<Component> {
+        let list: Vec<(i32, i32)> = levels
+            .iter()
+            .filter_map(|(name, level)| Some((enchantment(name)?, *level as i32)))
+            .collect();
+        (!list.is_empty()).then_some(Component::Enchantments(list))
+    };
+    if let Some(c) = levels(&d.enchantments) {
+        out.push((component::ENCHANTMENTS, c));
+    }
+    if let Some(c) = levels(&d.stored_enchantments) {
+        out.push((component::STORED_ENCHANTMENTS, c));
+    }
+    if d.repair_cost > 0 {
+        out.push((component::REPAIR_COST, Component::Int(d.repair_cost as i32)));
+    }
+    if let Some(name) = &d.custom_name {
+        // A plain string is a valid text component, and `decode_components`
+        // reads it back as one.
+        out.push((
+            component::CUSTOM_NAME,
+            Component::Text(Tag::String(name.as_str().into())),
+        ));
+    }
+    if let Some((material, pattern)) = &d.trim
+        && let (Some(material), Some(pattern)) = (trim_material(material), trim_pattern(pattern))
+    {
+        out.push((component::TRIM, Component::Trim { material, pattern }));
+    }
+    out
+}
+
+/// The same patch read back into `out`, the fields `item_data::decode_components`
+/// fills from the equivalent `components` compound.
+pub fn apply(
+    stack: &Stack,
+    out: &mut ItemStack,
+    enchantment: impl Fn(i32) -> Option<Arc<str>>,
+    trim_material: impl Fn(i32) -> Option<Arc<str>>,
+    trim_pattern: impl Fn(i32) -> Option<Arc<str>>,
+) {
+    out.damage = stack.damage().max(0) as u32;
+    let read_levels = |kind: i32, into: &mut Levels| {
+        if let Some(Component::Enchantments(list)) = stack.component(kind) {
+            for (id, level) in list {
+                if let Some(name) = enchantment(*id) {
+                    into.push((name, (*level).max(0) as u32));
+                }
+            }
+        }
+    };
+    let data: &mut StackData = out.data_mut();
+    read_levels(component::ENCHANTMENTS, &mut data.enchantments);
+    read_levels(
+        component::STORED_ENCHANTMENTS,
+        &mut data.stored_enchantments,
+    );
+    if let Some(Component::Int(v)) = stack.component(component::REPAIR_COST) {
+        data.repair_cost = (*v).max(0) as u32;
+    }
+    if let Some(Component::Text(t)) = stack.component(component::CUSTOM_NAME) {
+        data.custom_name = crate::item_data::read_text(t);
+    }
+    if let Some(Component::Trim { material, pattern }) = stack.component(component::TRIM)
+        && let (Some(material), Some(pattern)) = (trim_material(*material), trim_pattern(*pattern))
+    {
+        data.trim = Some((material, pattern));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn named(name: &str) -> Option<i32> {
+        Some(match name {
+            "minecraft:sharpness" => 3,
+            "minecraft:gold" => 7,
+            "minecraft:sentry" => 2,
+            _ => return None,
+        })
+    }
+    fn name_of(id: i32) -> Option<Arc<str>> {
+        Some(Arc::from(match id {
+            3 => "minecraft:sharpness",
+            7 => "minecraft:gold",
+            2 => "minecraft:sentry",
+            _ => return None,
+        }))
+    }
+
+    fn stack_with_data() -> ItemStack {
+        let mut stack = ItemStack::new("minecraft:diamond_sword", 1);
+        stack.damage = 5;
+        let d = stack.data_mut();
+        d.enchantments.push((Arc::from("minecraft:sharpness"), 4));
+        d.stored_enchantments
+            .push((Arc::from("minecraft:sharpness"), 2));
+        d.repair_cost = 9;
+        d.custom_name = Some("Keeper".to_owned());
+        d.trim = Some((Arc::from("minecraft:gold"), Arc::from("minecraft:sentry")));
+        stack
+    }
+
+    /// Every modelled component survives the packet, so the server's echo does
+    /// not hand back a bare item.
+    #[test]
+    fn a_stack_keeps_its_components_across_the_wire() {
+        let stack = stack_with_data();
+        let mut packet = Stack::new(1, 1);
+        packet.added = encode(&stack, named, named, named);
+
+        let mut back = ItemStack::new("minecraft:diamond_sword", 1);
+        apply(&packet, &mut back, name_of, name_of, name_of);
+        back.tidy();
+
+        assert_eq!(back.damage, 5);
+        let d = back.data().expect("components");
+        assert_eq!(d.enchantments, vec![(Arc::from("minecraft:sharpness"), 4)]);
+        assert_eq!(
+            d.stored_enchantments,
+            vec![(Arc::from("minecraft:sharpness"), 2)]
+        );
+        assert_eq!(d.repair_cost, 9);
+        assert_eq!(d.custom_name.as_deref(), Some("Keeper"));
+        assert_eq!(
+            d.trim,
+            Some((Arc::from("minecraft:gold"), Arc::from("minecraft:sentry")))
+        );
+    }
+
+    /// A name the registry does not know is a missing id, not id 0, which would
+    /// name the registry's first entry instead.
+    #[test]
+    fn an_unknown_enchantment_is_left_out_rather_than_sent_as_zero() {
+        let mut stack = ItemStack::new("minecraft:book", 1);
+        stack
+            .data_mut()
+            .enchantments
+            .push((Arc::from("mod:unknown"), 1));
+        assert!(encode(&stack, named, named, named).is_empty());
+    }
+}
diff --git a/crates/horizon-client/src/lan/hub.rs b/crates/horizon-client/src/lan/hub.rs
index dd0a32f22..2667b1fed 100644
--- a/crates/horizon-client/src/lan/hub.rs
+++ b/crates/horizon-client/src/lan/hub.rs
@@ -2293,6 +2293,14 @@ impl Hub {
             .name("minecraft:enchantment", id)
             .map(str::to_owned)
     }
+    /// An entry of a synced registry by id, for the components a packet
+    /// carries by id (`minecraft:trim_material`, `minecraft:trim_pattern`).
+    pub fn trim_name(&self, registry: &str, id: i32) -> Option<std::sync::Arc<str>> {
+        self.sync
+            .dynamic
+            .name(registry, id)
+            .map(std::sync::Arc::from)
+    }
 
     /// ServerLevel.removePlayerImmediately, then addRespawnedPlayer: the other players
     /// lose the dead player's entity (ServerEntity.removePairing) and are sent the
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index ae95e1bdb..ad05153eb 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -96,6 +96,7 @@ pub mod inv_sort;
 pub mod inventory_effects;
 pub mod item_data;
 pub mod item_render;
+pub mod item_sync;
 pub mod item_tooltip;
 pub mod items;
 pub mod java_text;
diff --git a/crates/horizon-protocol/src/registry.rs b/crates/horizon-protocol/src/registry.rs
index f97401670..400c21a37 100644
--- a/crates/horizon-protocol/src/registry.rs
+++ b/crates/horizon-protocol/src/registry.rs
@@ -102,6 +102,12 @@ impl Dynamic {
             .get(i)
             .map(|(n, _)| n.as_str())
     }
+    /// The id of an entry by name, the reverse of `name`. A registry has one
+    /// entry per id, so the first match is the only one.
+    pub fn id(&self, registry: &str, name: &str) -> Option<i32> {
+        let list = self.registries.get(registry)?;
+        list.iter().position(|(n, _)| n == name).map(|i| i as i32)
+    }
     pub fn data(&self, registry: &str, id: i32) -> Option<&Tag> {
         let i = usize::try_from(id).ok()?;
         self.registries.get(registry)?.get(i)?.1.as_ref()

From 5ee1130719904c4101a0b13748fc53b1adaab1ee Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:53:13 +0100
Subject: [PATCH 148/270] horizon-dualsense: iOS comments name only what exists

The repo has no horizon-gamecontroller crate, and on iOS the Link never
opens, so no rumble covers vibration there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-dualsense/Cargo.toml          | 5 ++---
 crates/horizon-dualsense/src/device.rs       | 3 +--
 crates/horizon-dualsense/src/haptics_stub.rs | 5 ++---
 crates/horizon-dualsense/src/lib.rs          | 3 +--
 4 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/crates/horizon-dualsense/Cargo.toml b/crates/horizon-dualsense/Cargo.toml
index 1a41e5703..feb25026b 100644
--- a/crates/horizon-dualsense/Cargo.toml
+++ b/crates/horizon-dualsense/Cargo.toml
@@ -10,9 +10,8 @@ description = "The DualSense's output over HID: rumble, adaptive triggers, light
 log = "0.4"
 
 # hidapi has no iOS backend and its build script stops there, so the output's two
-# dependencies go only to the targets that have one. On iOS the crate builds empty: pads
-# are read through GameController (horizon-gamecontroller), which only reads, and the
-# DualSense's own output waits for a desktop.
+# dependencies go only to the targets that have one. On iOS the crate builds without
+# output: the Link never opens.
 [target.'cfg(not(target_os = "ios"))'.dependencies]
 # MIT; bundles the C hidapi under its BSD licence option. hidraw on Linux (libudev, as gilrs),
 # IOKit on macOS (opened shared, so gilrs keeps reading the pad), the HID API on Windows.
diff --git a/crates/horizon-dualsense/src/device.rs b/crates/horizon-dualsense/src/device.rs
index 0b11ac415..f8e544ea6 100644
--- a/crates/horizon-dualsense/src/device.rs
+++ b/crates/horizon-dualsense/src/device.rs
@@ -165,8 +165,7 @@ impl Link {
         }
     }
 
-    /// No output on iOS: hidapi has no backend there, and iOS reads pads through
-    /// GameController (horizon-gamecontroller), which only reads. The Link never opens.
+    /// No output on iOS: hidapi has no backend there. The Link never opens.
     #[cfg(target_os = "ios")]
     pub fn start() -> Link {
         Link {
diff --git a/crates/horizon-dualsense/src/haptics_stub.rs b/crates/horizon-dualsense/src/haptics_stub.rs
index 7afc944ca..dc4e61667 100644
--- a/crates/horizon-dualsense/src/haptics_stub.rs
+++ b/crates/horizon-dualsense/src/haptics_stub.rs
@@ -1,6 +1,5 @@
-//! No HD haptics on iOS: the trick plays vibrations through the pad's own four-channel audio
-//! device over USB, and a phone has neither that device nor the audio stack the real module
-//! needs. The motors' rumble through [`crate::Link`] covers vibration instead.
+//! No HD haptics on iOS: they play through the pad's own four-channel audio device over USB,
+//! which needs cpal, and cpal is left out there with hidapi (see Cargo.toml).
 
 /// The pad's audio output, playing the queued samples (left, right actuator).
 pub struct Haptics;
diff --git a/crates/horizon-dualsense/src/lib.rs b/crates/horizon-dualsense/src/lib.rs
index 80831ee00..4ae55de9a 100644
--- a/crates/horizon-dualsense/src/lib.rs
+++ b/crates/horizon-dualsense/src/lib.rs
@@ -1,8 +1,7 @@
 //! The DualSense's output report, built by hand (docs/controllers.md "DualSense output"): the
 //! compatible-vibration motors, the adaptive triggers, the lightbar and the player LEDs. Gilrs
 //! keeps reading the pad; this crate only writes to it, over hidapi ([`device`]).
-//! On iOS the crate builds without hidapi, which has no backend there: [`Link`] never opens,
-//! and the pad is read through GameController, which only reads.
+//! On iOS the crate builds without hidapi, which has no backend there: [`Link`] never opens.
 //!
 //! The byte layout is the one documented by the Linux kernel's `hid-playstation.c` and SDL's
 //! `SDL_hidapi_ps5.c`: a 47-byte block shared by both transports, sent as report 0x02 over USB

From f2832f83ef4e811e744312ac01117114a098f746 Mon Sep 17 00:00:00 2001
From: socksprox <socksprox@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:53:13 +0100
Subject: [PATCH 149/270] check: cover the ui open/close-screen outputs

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/cargo-horizon-mod/src/check.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index 0294bec98..5d4150ab9 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -215,6 +215,8 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
                 format!("{}: {text}", if error { "error" } else { "feedback" })
             }
             Output::Stopped { reason, .. } => return Err(format!("it stopped: {reason}")),
+            Output::OpenScreen { .. } => "opened a screen".to_string(),
+            Output::CloseScreen { .. } => "closed its screen".to_string(),
         });
     }
     match failed(&mods) {

From a276f81abacc7d7503a3098c986b1c370f294912 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:55:23 +0100
Subject: [PATCH 150/270] Shader packs, clean room 39: the run doc comment back
 on run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/pack_post.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index f17765a0f..fdc4563ef 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -2081,9 +2081,6 @@ impl PackPost {
         }
     }
 
-    /// Runs the pack over the world drawn into `world` (colour) and `world_depth`, then draws
-    /// the result onto `screen`.
-    #[allow(clippy::too_many_arguments)]
     /// The shadow pass (2.1, passes 2 and 3): the shadow buffers cleared, then the `shadowcomp`
     /// programs, each drawing into the "alt" side of what it writes and flipping it after.
     fn run_shadow(
@@ -2133,6 +2130,9 @@ impl PackPost {
         self.shadow_comp = comp;
     }
 
+    /// Runs the pack over the world drawn into `world` (colour) and `world_depth`, then draws
+    /// the result onto `screen`.
+    #[allow(clippy::too_many_arguments)]
     pub fn run(
         &mut self,
         device: &wgpu::Device,

From 2ec2964962790c292180cd228890329285bf5ea9 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:09:13 +0100
Subject: [PATCH 151/270] Roadmap: the items Ludovic decided on (55 added, 4
 updated, 3 areas)

Adds the ideas he said yes to, as roadmap items with plain and dev text,
and extends ai-companion, new-versions, benchmarks and intel-mac. New
areas: platforms, ai, community.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 ROADMAP.md                | 632 +++++++++++++++++++++++++++++++-
 roadmap/roadmap.toml      | 739 +++++++++++++++++++++++++++++++++++++-
 website/data/roadmap.json | 663 +++++++++++++++++++++++++++++++++-
 3 files changed, 1996 insertions(+), 38 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index b433fad3a..7e4cc9937 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -16,7 +16,7 @@ Horizon is Minecraft: Java Edition 26.3 rewritten from scratch in Rust, so it ru
 - **Single player as a server: the last differences**: Single player now runs a small server in the background, as vanilla does. We are fixing what still behaves differently there; every fix also works for LAN and server players.
 - **Horizon's mod registry**: One place for mods, modpacks and resource packs made for Horizon: browse them on the website and install them from the launcher in one click.
 
-**Next**: Microsoft sign-in (coming soon); CurseForge in the mod browser (coming soon); Fresh benchmarks against vanilla; Pistons push players and mobs; Horizon on Intel Macs.
+**Next**: Microsoft sign-in (coming soon); CurseForge in the mod browser (coming soon); Fresh benchmarks against vanilla; Pistons push players and mobs; Horizon on Intel Macs; Faster world creation and entry on small CPUs; Servers that hold 20 TPS with 50 to 100 players; Low-end computers: Steam Deck, old Macs, 8 GB; Native upscaling; A batch of targeted optimisations; A Convert to Rust button for what isn't rewritten yet; Mods with code: machines, magic, mobs; Data packs in the mod browser; Prepare a version without Java; Server console, bans and a full admin API; Hosting polish: Windows service, safe updates; Guided hosting with Tailscale and an invite button; An official Docker image for servers; One single-player path: remove the in-frame world; Villages and combat, exactly as in vanilla; Choose the audio output device; Mods that read and change the world; Machines and blocks with inventories (API 0.4); Lua and other languages for mods; Well-known shader looks, rewritten for Horizon; A visible beta label; Wayland and Hyprland polish; A versioned agent-control protocol; Port mods with your own AI agent; Horizon on X (coming soon); Pipeline protection and a GitHub App for agents; Signed updates everywhere, installers included.
 
 **How to help**: Play it and tell us what differs from vanilla (Discord or GitHub), run the benchmark on your computer, vote for what you want next, or pick one of the Help wanted items.
 
@@ -80,6 +80,16 @@ Servers that show dialogs, such as the register and login screens of AuthMe, wil
 
 </details>
 
+#### Pre-generate an area with /pregen
+
+A /pregen command that builds an area of the world ahead of time, so players don't wait for new terrain when they explore.
+
+<details><summary>Technical</summary>
+
+Generates, lights and saves an area before anyone walks there ([#1805](https://github.com/ludovic111/horizon/issues/1805), a contributor's pull request, in review). Useful on servers, and it moves the generation cost away from the first visit; the generation speed-ups are under 'Steady frames at long render distances'.
+
+</details>
+
 ### Mods and API
 
 #### Horizon's mod registry
@@ -94,6 +104,40 @@ More: [docs/mods.md](docs/mods.md)
 
 </details>
 
+#### Mods that run on the server
+
+Mods that run on the server side of a world, so a dedicated server or a LAN world can have mods that react to players joining, chat and blocks being broken or placed, and that add commands.
+
+<details><summary>Technical</summary>
+
+API 0.3, experimental first ([#1833](https://github.com/ludovic111/horizon/issues/1833), in review): the same sandboxed component runs on the server thread and the dedicated server, with world events (block broken or placed, entity spawned or killed, player joined or left), game rules and server commands with typed arguments. The world, item and entity interfaces come after (see 'Mods that read and change the world'). [docs/api/mods.md](docs/api/mods.md), [docs/mods.md](docs/mods.md).
+
+</details>
+
+#### Screens, input and drawing for mods
+
+Mods will be able to open their own screens and settings pages and react to keys and item use, so bigger mods, such as the Orbital Laser, can run on the normal game.
+
+<details><summary>Technical</summary>
+
+Capability `ui` is in review ([#1864](https://github.com/ludovic111/horizon/issues/1864)): mod-owned screens and a settings page under Options > Mods, built from vanilla's widgets. Still to design: `input` (an item's use, key binds, the crosshair target), `render` (a budgeted draw list on the native shader API) and `world` (changing blocks). Orbital Laser is the acceptance test: it needs all four today through its author's fork (see 'Orbital Laser on the normal game').
+
+More: [docs/mods.md](docs/mods.md)
+
+</details>
+
+#### Tools for people who make mods
+
+Better tools for mod makers: a test runner that needs no game window, templates for each kind of mod, and clear promises about what keeps working from one version to the next.
+
+<details><summary>Technical</summary>
+
+`cargo horizon-mod test` runs a mod's test scripts against a fake game snapshot ([#1816](https://github.com/ludovic111/horizon/issues/1816)) and, for server mods, scripted server events ([#1837](https://github.com/ludovic111/horizon/issues/1837)); the content template and the guides are merged ([#1859](https://github.com/ludovic111/horizon/issues/1859), [#1810](https://github.com/ludovic111/horizon/issues/1810), [docs/api/stability.md](docs/api/stability.md)). Left: templates for hud, server and machine mods, typed wrappers in the SDK, a frozen 0.1 compatibility mod that every runtime must load, a CI check that fails when a stable reference entry is removed without a new major version, and the SDK on crates.io once the API is stable.
+
+More: [website/docs/test-a-mod.md](website/docs/test-a-mod.md)
+
+</details>
+
 ### Gameplay parity
 
 #### Single player as a server: the last differences
@@ -130,6 +174,16 @@ More: [#1561](https://github.com/ludovic111/horizon/issues/1561) · [#1771](http
 
 </details>
 
+#### Horizon's own shader format and kit
+
+Horizon's own way to make shader packs, with tools to write and test them. Every pack is checked before it runs, and the registry will list them.
+
+<details><summary>Technical</summary>
+
+`horizon-shader-api` (API 0.1, experimental): WGSL stages with typed inputs inside the renderer's passes, options as WGSL override constants, and the `horizon-shader new|check|pack` tool with templates and the example pack Golden Hour. Merged: the check every pack passes ([#1820](https://github.com/ludovic111/horizon/issues/1820)) and the tool, templates and guide ([#1822](https://github.com/ludovic111/horizon/issues/1822)). In review: the post stage running in the game with hot reload ([#1861](https://github.com/ludovic111/horizon/issues/1861)), the sky stage ([#1863](https://github.com/ludovic111/horizon/issues/1863)) and registry checks that use the game's own check ([#1855](https://github.com/ludovic111/horizon/issues/1855)). Left: the material, lighting and shadow stages, a last-good fallback on reload, a GPU-time overlay per stage and budgets ([docs/shaders.md](docs/shaders.md), [docs/api/shaders.md](docs/api/shaders.md)). The Iris/OptiFine loader is a separate item, 'Shader packs, written again from scratch'.
+
+</details>
+
 ### Horizon extras
 
 #### Discord Rich Presence
@@ -160,11 +214,65 @@ A review of the whole tree: dead code and stubs removed ([#1432](https://github.
 
 #### Fresh benchmarks against vanilla
 
-New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, on the website's Benchmarks page.
+New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, with a history that shows what each release changed.
 
 <details><summary>Technical</summary>
 
-Redo the comparison after the current performance work ([#1073](https://github.com/ludovic111/horizon/issues/1073)); reliability, coverage and presentation ([#1346](https://github.com/ludovic111/horizon/issues/1346)); a scene must count as loaded only once its first chunk arrives ([#1749](https://github.com/ludovic111/horizon/issues/1749)). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` ([docs/benchmark.md](docs/benchmark.md)).
+Redo the comparison after the current performance work ([#1073](https://github.com/ludovic111/horizon/issues/1073)); reliability, coverage and presentation ([#1346](https://github.com/ludovic111/horizon/issues/1346)); a scene must count as loaded only once its first chunk arrives ([#1749](https://github.com/ludovic111/horizon/issues/1749)). Next: a performance history across releases (an automatic comparison of each release with the last, on a timeline), more report fields (server TPS and MSPT, power, battery drain, temperature, throttling) and more hardware (a MacBook on battery, low-end laptops, community reports). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` ([docs/benchmark.md](docs/benchmark.md)).
+
+</details>
+
+#### Faster world creation and entry on small CPUs
+
+Creating a world and joining it should be quick even on a four-thread laptop, where a fresh world at 32 chunks can make you wait minutes for the first terrain.
+
+<details><summary>Technical</summary>
+
+Cut the per-column generation cost (noise sampling, surface rules, aquifers) and the lock convoy on structure starts, and leave one core free for the rest of the game as vanilla does ([#1760](https://github.com/ludovic111/horizon/issues/1760) and [#1778](https://github.com/ludovic111/horizon/issues/1778), in review, are listed under 'Steady frames at long render distances'). Still to profile on small CPUs: the first seconds of a fresh world deliver no chunk, and fluids remesh for about a minute after loading. Measured with `tools/perf_bench.py` ([docs/benchmark.md](docs/benchmark.md), [docs/profiling.md](docs/profiling.md)).
+
+</details>
+
+#### Servers that hold 20 TPS with 50 to 100 players
+
+Servers that keep 20 ticks per second with 50 to 100 players. Today Horizon holds it up to 50 bots and drops to about 10 at 100.
+
+<details><summary>Technical</summary>
+
+Measured against vanilla on equal work ([docs/server.md](docs/server.md), Scale): Horizon is ahead with few players and when exploring, but vanilla's tick is shorter with 25 to 50 players near spawn. Ideas on the list: send entity changes instead of rebuilding every entity each tick (about 15 percent), fewer memory reads in random ticks and collision scans, cheaper item collision checks, mob AI and natural spawning. The bot benchmark (`horizon-bots`) is the proof.
+
+</details>
+
+#### Low-end computers: Steam Deck, old Macs, 8 GB
+
+Horizon should run well on small machines: integrated graphics, the Steam Deck, older Macs and 8 GB of memory, with a battery mode that saves power on laptops.
+
+<details><summary>Technical</summary>
+
+Partly done: an opt-in 60 FPS cap with fewer workers on battery, Far Detail Reduced for integrated GPUs and animated textures on the GPU (both shipped). Left: measured targets and fixes per class of machine (memory use, worker counts, startup) on a Steam Deck, old Intel and Apple Silicon Macs and 8 GB computers, reported on the Benchmarks page.
+
+More: [docs/benchmark.md](docs/benchmark.md) · [website/docs/performance.md](website/docs/performance.md)
+
+</details>
+
+#### Native upscaling
+
+Draw the game at a lower resolution and sharpen it to your screen's size, in the way of FSR or DLSS, to gain frames on weaker graphics cards. An optional graphics setting.
+
+<details><summary>Technical</summary>
+
+A render-scale setting below the window size with an upscaler of our own that runs on every wgpu backend. Proof: frame time against native resolution on integrated GPUs, and screenshots for image quality. Issue [#1403](https://github.com/ludovic111/horizon/issues/1403).
+
+</details>
+
+#### A batch of targeted optimisations
+
+Several smaller speed-ups, each measured: idle block entities that sleep, cheaper particles, faster structure placement, high-rate mice and very large texture packs.
+
+<details><summary>Technical</summary>
+
+Block entities and hoppers that skip work when idle (the hopper item scan is already skipped when no item is near); a particle frustum test first (also a parity gap), then particle quads built on the GPU; jigsaw shortcuts that skip blocked connectors and pool elements known not to fit, with layouts unchanged (trial chambers and ancient cities first); batched raw mouse input on Windows for 8000 Hz mice; a better atlas packer for huge resource packs (a 64x pack builds a 704 MiB atlas for 452 MiB of textures); sign-heavy scenes ([#1461](https://github.com/ludovic111/horizon/issues/1461)). Profile first, keep what pays, show before and after numbers.
+
+More: [docs/profiling.md](docs/profiling.md)
 
 </details>
 
@@ -180,6 +288,126 @@ The mod browser lists CurseForge as coming soon ([docs/mod-browser.md](docs/mod-
 
 </details>
 
+#### A Convert to Rust button for what isn't rewritten yet
+
+When a mod, shader pack or modpack hasn't been rewritten for Horizon, one button converts what can be converted, so you don't have to wait for the rewrite.
+
+<details><summary>Technical</summary>
+
+Generalise the mod browser's Port step (`horizon-port-pack`: the data, assets, worldgen and block and item definitions of Java mods, .mrpack and CurseForge zips) to every kind of content: code mods where the API allows it (see 'Mods with code') and shader packs, converting an Iris/OptiFine pack into Horizon's format. The browser says what works before the install. Java code itself does not run ([docs/modpacks.md](docs/modpacks.md), [docs/mod-browser.md](docs/mod-browser.md)).
+
+</details>
+
+#### Mods with code: machines, magic, mobs
+
+Making mods that add machines, magic and mobs work in Horizon, in steps, starting with machines. They are most of what a big modpack is made of.
+
+<details><summary>Technical</summary>
+
+333 of the 496 mods in a big pack (ATM10) contain code. Issue [#1854](https://github.com/ludovic111/horizon/issues/1854) ranks the API gaps (ticking block entities, networking, rendering, menus, inventories) that unlock them in tiers, with machines first as the recommended path and a furnace ported tick for tick as proof. The first API step is a draft ([#1189](https://github.com/ludovic111/horizon/issues/1189), see 'Machines and blocks with inventories'). The path isn't started yet ([docs/modpacks.md](docs/modpacks.md)).
+
+</details>
+
+#### Data packs in the mod browser
+
+Search and install data packs from the launcher's mod browser, for the world you choose, as you do mods and resource packs.
+
+<details><summary>Technical</summary>
+
+A Datapacks tab beside Mods and Resource packs: install into a chosen world's datapacks folder, with the same checks and 'works in Horizon' notes as the other kinds ([docs/mod-browser.md](docs/mod-browser.md)).
+
+</details>
+
+### Servers and multiplayer
+
+#### Prepare a version without Java
+
+Set up Horizon, a server first, without Java on your computer: published tables are combined with your own copy of the game.
+
+<details><summary>Technical</summary>
+
+Today `horizon-prepare` runs Mojang's exporters with Java. Issue [#1750](https://github.com/ludovic111/horizon/issues/1750) proposes publishing the computed version tables once from CI and assembling the rest locally from the player's own jar and assets, provided the tables hold no Mojang content; a contributor offered a pull request, and it would help phones too. A server-only prepare from `server.jar` alone is the first step ([docs/server.md](docs/server.md)).
+
+</details>
+
+#### Server console, bans and a full admin API
+
+Manage a server from a console, ban and pardon players, and drive it from other tools through a full admin API and an MCP server for AI agents.
+
+<details><summary>Technical</summary>
+
+`horizon-server console` (a text interface), `ban`, `pardon`, `ban-ip` and `mcp` over stdio. Admin API additions: the player list, kick, ban, op and whitelist, an SSE stream of logs and events, a text metrics endpoint, config GET and PATCH, backup delete and download. The panel's later features (bans, worlds, server.properties import, logs and crash reports, modpacks) and vanilla's management protocol (the JSON-RPC over WebSocket that the `management-server-*` keys configure), so vanilla's tools can manage a Horizon server. [docs/server.md](docs/server.md), [docs/api/server.md](docs/api/server.md).
+
+</details>
+
+#### Hosting polish: Windows service, safe updates
+
+Smoother hosting: a real Windows service, a backup before every update, backups that keep the world and each player's state, and a changed view distance or message without a restart.
+
+<details><summary>Technical</summary>
+
+A Windows service wrapper instead of the logon scheduled task; `backups.before_update`; hot reload of config for view distance and the message of the day (needs engine support); backups that keep world and player state ([#1808](https://github.com/ludovic111/horizon/issues/1808), a contributor's draft, in review). [docs/hosting.md](docs/hosting.md), docs/server.md.
+
+</details>
+
+#### Guided hosting with Tailscale and an invite button
+
+In the launcher, a guide and a button to host a server and invite friends over Tailscale, so nobody has to open ports on a router.
+
+<details><summary>Technical</summary>
+
+On the Servers page (create, start, back up, update and invite are shipped) add a Tailscale setup that explains and checks each step, and an invite button that hands friends what they need to join over the tailnet. Buttons first, no docs needed, with the details in an Advanced section. Remote access over Tailscale is already described in [docs/server.md](docs/server.md).
+
+More: [docs/hosting.md](docs/hosting.md)
+
+</details>
+
+#### An official Docker image for servers
+
+An official image to run a Horizon dedicated server in Docker with one command, your own copy of the game files mounted in.
+
+<details><summary>Technical</summary>
+
+The repository has the Dockerfile (`packaging/server/Dockerfile`: a multi-stage build on Debian bookworm-slim, user `horizon`, volume `/data`, port 25565, game files mounted read-only, `HORIZON_EULA` and friends answering the first-start questions), and anyone can build it ([docs/hosting.md](docs/hosting.md), section 9). Left: publish the image to a public registry from the release workflow, tagged per release, so it follows the same checks, and update the docs and the launcher. The image never holds Mojang's files.
+
+More: [docs/server.md](docs/server.md)
+
+</details>
+
+### Mods and API
+
+#### Mods that read and change the world
+
+Mods that can see and change blocks, read inventories and items, and find and affect entities, all through the server so every player sees the same thing.
+
+<details><summary>Technical</summary>
+
+After server mods: read blocks, states and biomes in loaded chunks and change them through the server's block log, so clients and the parity harnesses see vanilla's updates; the player's inventory, held item, open container and item stacks with components; entity queries near a position, a safe subset of entity data and data-driven mod entity types. Snapshots and batched calls per tick, never per-block host calls in hot paths. [docs/api/mods.md](docs/api/mods.md) ('Not there yet').
+
+More: [docs/modpacks.md](docs/modpacks.md)
+
+</details>
+
+#### Machines and blocks with inventories (API 0.4)
+
+Mods that add machines: blocks that tick, hold items and have their own menus. This unlocks the technology mods of big modpacks.
+
+<details><summary>Technical</summary>
+
+Block entities and menus: ticking machines with slots, server menu logic and the menu protocol to clients, energy, item and fluid transfer, data attachments, accessory slots and custom recipe types, with a typed client and server channel and typed config beside them. A draft ([#1189](https://github.com/ludovic111/horizon/issues/1189)) proves a furnace ported tick for tick and holds the ATM10 code-mods plan; the design is redone through the API policy before it merges ([docs/modpacks.md](docs/modpacks.md), docs/api/stability.md).
+
+</details>
+
+#### Lua and other languages for mods
+
+Write mods as Lua scripts, in the style of KubeJS, with no compiler, and later in other languages that pass the tests. Every language runs in the same sandbox.
+
+<details><summary>Technical</summary>
+
+Lua first: Horizon ships a Lua interpreter that is itself a WebAssembly mod, and a script mod's manifest names it and the capabilities it uses, so a script can do exactly what a compiled mod with the same manifest can, with hot reload of `main.lua`. Then C, C++, Zig, Go (TinyGo), AssemblyScript and JavaScript or TypeScript are measured against Rust on the same tick-heavy example, and each is supported only with a template, an example and a CI test. [docs/api/mods.md](docs/api/mods.md) ('Ways in').
+
+</details>
+
 ### Gameplay parity
 
 #### Pistons push players and mobs
@@ -192,6 +420,50 @@ Port `PistonMovingBlockEntity.moveCollidedEntities` and `moveStuckEntities` (hon
 
 </details>
 
+#### One single-player path: remove the in-frame world
+
+Single player will have one way to run, the server thread, so every fix works everywhere and there are fewer bugs. The older in-frame mode goes once everything passes without it.
+
+<details><summary>Technical</summary>
+
+`--in-frame` (also `--no-server-thread` and `HORIZON_SERVER_THREAD=0`) still ticks the world inside the window's `Game`, and most harnesses test that path. Delete it once `lan_e2e --server-thread` and the parity harnesses pass on the server thread, which also halves the bug surface. See also 'Single player as a server' and [docs/server-levels.md](docs/server-levels.md).
+
+</details>
+
+#### Villages and combat, exactly as in vanilla
+
+Villages and fights behaving as in vanilla: iron golems defending villages, villagers remembering their homes, mace smashes and knockback.
+
+<details><summary>Technical</summary>
+
+Villages: iron golem village goals, villager memories across saves, villager age, job-site claiming on dedicated servers, flower offers ([#1639](https://github.com/ludovic111/horizon/issues/1639) is one report). Combat: the mobs' `attack_knockback` attribute, mace smash logic, the hit knockback source on the host, the fire burnout biome tag. Each is checked against vanilla by a harness ([docs/rust-parity.md](docs/rust-parity.md)).
+
+</details>
+
+#### Choose the audio output device
+
+Pick the speakers or headphones Horizon plays through, in Music & Sounds.
+
+<details><summary>Technical</summary>
+
+An output device list in Music & Sounds, falling back to the system default. [#1035](https://github.com/ludovic111/horizon/issues/1035) started it: a player on an older Windows computer had no sound at all, and a device choice is how such cases are found and fixed.
+
+</details>
+
+### Rendering
+
+#### Well-known shader looks, rewritten for Horizon
+
+Popular shader packs rewritten in Horizon's format, so good packs exist from the start. Only packs whose licence is open source and compatible with ours are rewritten, never anything else.
+
+<details><summary>Technical</summary>
+
+The first candidates are Photon, Chocapic13 and MakeUp Ultra Fast, each only after its licence is read and recorded: a pack is rewritten only if it is open source and compatible with Horizon's licence, and the rewrite is written from the shader format's documentation and the look on screen, not from anyone's code. Today only the Golden Hour example exists (`[crates/horizon-shader-api/packs/golden_hour](crates/horizon-shader-api/packs/golden_hour)`).
+
+More: [docs/shaders.md](docs/shaders.md)
+
+</details>
+
 ### Launcher
 
 #### Microsoft sign-in (coming soon)
@@ -206,6 +478,18 @@ More: [#1270](https://github.com/ludovic111/horizon/issues/1270)
 
 </details>
 
+#### A visible beta label
+
+A clear 'beta' label in the launcher and the game, so nobody is surprised that Horizon is still being built.
+
+<details><summary>Technical</summary>
+
+Show Beta in the launcher's header and about page, on the game's title screen and on the website, beside the version number ([docs/versioning.md](docs/versioning.md)).
+
+</details>
+
+### Platforms
+
 #### Horizon on Intel Macs
 
 Builds of the game and the launcher for Macs with an Intel processor.
@@ -216,29 +500,351 @@ x86_64 game and launcher builds, picked per processor ([#1171](https://github.co
 
 </details>
 
-## Later
+#### Wayland and Hyprland polish
 
-### Gameplay parity
-
-#### Following new Minecraft versions
-
-When Mojang releases a new version of the game, Horizon follows it, and every system is checked against the new version again.
+Fixes for Linux desktops that use Wayland and Hyprland: fullscreen, the clipboard, the GUI scale after a restart and the like.
 
 <details><summary>Technical</summary>
 
-The port pipeline detects a release, diffs its classes against 26.3 and writes a port report ([docs/version-ports.md](docs/version-ports.md)); the harnesses then run against the new version.
+Open: the GUI Scale is clamped to 2 after a restart under Hyprland, while XWayland keeps it ([#1866](https://github.com/ludovic111/horizon/issues/1866)). Earlier reports covered fullscreen dropping on menu clicks, the clipboard and a white overlay ([#1007](https://github.com/ludovic111/horizon/issues/1007), closed). Checked on a real Wayland session.
+
+</details>
+
+### AI and agents
+
+#### A versioned agent-control protocol
+
+A stable, documented way for AI agents and scripts to drive the game and the launcher, with versions and an event stream so tools keep working as Horizon changes.
+
+<details><summary>Technical</summary>
+
+`hello` answers with the API version, the release and the features; `horizon-ctl --api`; MCP serverInfo; reply schemas generated into the reference; a `test.` namespace for hooks; transcript compatibility tests; `subscribe` as a stream of events on one connection; Horizon option files by key and saved-server commands. Agent control itself (`horizon-ctl`, both MCP servers, the No AI switch) is done: [docs/agent-control.md](docs/agent-control.md), [docs/api/agent-control.md](docs/api/agent-control.md).
+
+More: [docs/api/stability.md](docs/api/stability.md)
+
+</details>
+
+#### Port mods with your own AI agent
+
+You can port a mod to Horizon with your own AI agent on your own computer. Horizon documents how and gives you the tools, but provides no hosted agents.
+
+<details><summary>Technical</summary>
+
+A player runs their own agent locally with `horizon-ctl` and the MCP servers ([docs/agent-control.md](docs/agent-control.md)), `cargo horizon-mod`, `horizon-port-pack` and the parity harnesses as the check. Horizon writes the guide ([website/docs/agents.md](website/docs/agents.md), [docs/modpacks.md](docs/modpacks.md)) and runs no agents, accounts or keys for players. The No AI switch turns all of it off.
+
+</details>
+
+### Community
+
+#### Horizon on X (coming soon)
+
+Coming soon: an official Horizon account on X, used to announce releases and the weekly summary.
+
+<details><summary>Technical</summary>
+
+Kira already posts the roadmap items marked `announce = true` when they ship, and the weekly summary, as soon as the account's credentials exist ([roadmap/README.md](roadmap/README.md), 'The journal'). Waiting for the account itself.
+
+</details>
+
+### Code and tools
+
+#### Pipeline protection and a GitHub App for agents
+
+Safer releases: changes to the release machinery need the owner's review, and AI agents use a smaller identity of their own instead of a personal account.
+
+<details><summary>Technical</summary>
+
+`.github/CODEOWNERS` lists the workflows, the release and signing tools, the update-checking code and the installers ([#1015](https://github.com/ludovic111/horizon/issues/1015)); the branch protection that makes it count waits for the `horizon-agent` GitHub App, which reads and writes code, pull requests and issues but can't change settings, workflows, secrets or members, and whose tokens last an hour. It needs the owner to create the App and switch the protection on ([docs/security.md](docs/security.md)).
+
+</details>
+
+#### Signed updates everywhere, installers included
+
+Every download Horizon makes is checked against the project's signature, including the first install with install.sh and install.ps1.
+
+<details><summary>Technical</summary>
+
+Releases carry signed checksums, and the launcher and `horizon-server update` refuse anything unsigned ([#1011](https://github.com/ludovic111/horizon/issues/1011), [#1014](https://github.com/ludovic111/horizon/issues/1014)). Left: the first install through `install.sh` and `install.ps1` still trusts only the checksum GitHub publishes, because verifying Ed25519 signatures needs OpenSSL 3, which macOS doesn't ship ([docs/security.md](docs/security.md)).
+
+</details>
+
+## Later
+
+### Performance
+
+#### Exact far terrain from real chunks
+
+Far terrain drawn from the world you really built and explored, caves and builds included, not only a preview from the seed.
+
+<details><summary>Technical</summary>
+
+Keep a 3D mip store on disk built from real chunks, drawn by the GPU beside the seed preview for areas nobody has visited. Written from scratch and measured before it is kept. Builds on Far Detail and the far-terrain levels of detail already shipped; the open work on them is [#718](https://github.com/ludovic111/horizon/issues/718).
+
+</details>
+
+### Modpacks
+
+#### Older Fabric and Forge mods
+
+Recognise mods built for versions before 26.1 in the mod browser, so they can be checked and carried over like newer ones.
+
+<details><summary>Technical</summary>
+
+A mapping table from intermediary and SRG names so pre-26.1 jars can be classified, and a rename for mod ids with dashes (`fabric-api`); the port step then treats them like newer jars ([docs/mod-browser.md](docs/mod-browser.md)).
+
+</details>
+
+#### A modpack's own resource and shader packs
+
+Importing a modpack also brings the resource packs and shader packs it ships with, where Horizon can use them.
+
+<details><summary>Technical</summary>
+
+Porting a pack carries data, assets and worldgen today; the resource packs and shader packs bundled with it are left out. Resource packs can be carried as they are; shader packs go through the converter ([docs/modpacks.md](docs/modpacks.md)).
+
+</details>
+
+#### Whole modpacks, such as ATM10, rewritten
+
+Rewriting a complete big modpack for Horizon so it runs far better than the original. Not a priority now: the work above comes first.
+
+<details><summary>Technical</summary>
+
+The project's first goal for modpacks: support them ten times better than vanilla and port any of them. It was set aside in favour of compatibility through the browser. What exists: ATM10's world generates and 42 of its 496 mods are carried at least in part ([docs/modpacks.md](docs/modpacks.md)). It depends on 'Mods with code' and the native mod API.
+
+</details>
+
+#### Running Java mods that aren't rewritten
+
+Run Java mods that nobody has rewritten for Horizon yet, through a bridge or a converter. Hard and not started: the Convert button and native rewrites come first.
+
+<details><summary>Technical</summary>
+
+Earlier research ([#527](https://github.com/ludovic111/horizon/issues/527), closed) found that Java mods can't simply run, because they call Minecraft's own classes. Options to look at again: a jar-to-WebAssembly backend, or a bridge for simple Fabric mods. Whatever is chosen has to run inside the same sandbox and capability checks as native mods.
+
+</details>
+
+### Servers and multiplayer
+
+#### Ely.by and other sign-in providers
+
+Sign in with other account providers, such as Ely.by or any Yggdrasil-compatible one, beside Microsoft.
+
+<details><summary>Technical</summary>
+
+Issue [#1270](https://github.com/ludovic111/horizon/issues/1270) asks for Ely.by and Yggdrasil-compatible servers with an account selector in the launcher. It builds on the Microsoft sign-in ([docs/microsoft-account.md](docs/microsoft-account.md)).
+
+</details>
+
+#### Online-mode checks for Play with Friends
+
+Friends who join through an invite code could prove who they are with their Microsoft account, as on online-mode servers.
+
+<details><summary>Technical</summary>
+
+Play with Friends joins over an encrypted tunnel with an invite code ([docs/play-with-friends.md](docs/play-with-friends.md), 'Identity'). Online-mode checks against Mojang's session servers can be added on top of the same tunnel; they need Microsoft sign-in first, which is coming soon. Play with Friends stays self-hosted between players, with no relay run by the project.
+
+</details>
+
+### Mods and API
+
+#### Orbital Laser on the normal game
+
+The community mod Orbital Laser, made for a fork of Horizon, running on the normal game and listed in the registry as the showcase of the mod API.
+
+<details><summary>Technical</summary>
+
+A pull request on [https://github.com/Stink-O/orbital-laser](https://github.com/Stink-O/orbital-laser) (MIT) once the input, ui, render and world capabilities exist (see 'Screens, input and drawing for mods'): today the mod needs them through its author's fork. Tested in the game, and listed in the registry.
+
+</details>
+
+#### Native versions of popular client mods
+
+Built-in versions of the client mods players ask for: block info on hover, a recipe viewer like JEI, a world map and schematic overlays.
+
+<details><summary>Technical</summary>
+
+Done as extras: a mod list and menu, a minimap and a zoom ([docs/extras.md](docs/extras.md)). Left: block info tooltips, a recipe viewer (a contributor offered to port JEI if it becomes a native feature), a world map and a schematic overlay. They need the read-only interfaces `inventory-read`, `recipes`, `world-read` and `render` in the mod API, or they go into the game directly.
+
+More: [docs/mods.md](docs/mods.md)
+
+</details>
+
+#### Create-style physics as a native mod
+
+Contraptions and physics like the Create and Aeronautics mods, as a mod for Horizon rather than part of the base game.
+
+<details><summary>Technical</summary>
+
+Issue [#805](https://github.com/ludovic111/horizon/issues/805) (porting QOL mods) closed with this answer: it would come as a native Horizon mod on the mod API. It needs server mods, entities and rendering first.
+
+</details>
+
+#### Proximity voice chat as a native mod
+
+Hear nearby players talk, as with the voice chat mods of other Minecraft versions, as a Horizon mod.
+
+<details><summary>Technical</summary>
+
+Needs server mods, mod networking and an audio interface in the mod API before anything can be built ([docs/api/mods.md](docs/api/mods.md)).
+
+</details>
+
+### Gameplay parity
+
+#### Every Minecraft version, prepared automatically
+
+Every past and future Minecraft version prepared for Horizon automatically. When Mojang releases one, Horizon follows it, and every system is checked against it again.
+
+<details><summary>Technical</summary>
+
+The port pipeline ([docs/version-ports.md](docs/version-ports.md), `tools/version_port.py`) detects a release, prepares it, diffs its classes against the pinned 26.3, regenerates the data-driven tables, runs every parity harness on it and writes a port report that becomes issues. The goal is as little human work as possible for any version, past or future. Detection and the first slices are merged; the scheduled agent that runs it every day isn't installed yet. Two versions in one build are out of scope.
+
+</details>
+
+#### Controllers: tested on real pads, and in the launcher
+
+Make controller support solid: tested with real PlayStation and Xbox pads and a Steam Deck, and usable in the launcher too.
+
+<details><summary>Technical</summary>
+
+The game side is merged ([docs/controllers.md](docs/controllers.md)): pads read with gilrs, menus, rumble, glyphs, remapping and DualSense adaptive triggers, lightbar and haptics, but not yet confirmed on real pads or a Steam Deck (DualSense haptics stay behind a switch until then). Left: a test pass on real hardware, and the same focus navigation in the GPUI launcher.
+
+</details>
+
+#### The full debug screen
+
+Vanilla's complete F3 screen: debug options, a profiler chart, ten-second captures and an atlas dump.
+
+<details><summary>Technical</summary>
+
+Today F3 shows position, chunk, light, biome and FPS ([docs/native-client.md](docs/native-client.md)). Vanilla also has F3+F6 debug options with profiles, F3+1 the profiler pie, F3+L a ten-second capture and F3+S the atlas dump ([#562](https://github.com/ludovic111/horizon/issues/562) asked for the F3 editor).
+
+</details>
+
+### Rendering
+
+#### A light default shader pack
+
+A small built-in look (tone mapping, colour grade, a cheap vignette) that costs almost nothing, for players who want a nicer picture without a heavy pack.
+
+<details><summary>Technical</summary>
+
+An opt-in, composite-only pack on the native shader API, under about 0.3 ms at 1080p, shown on the Shader Packs page. Pack option sliders and profiles, and a Failed row with the full error, belong with it.
+
+More: [docs/shaders.md](docs/shaders.md)
+
+</details>
+
+#### Optional ray tracing
+
+An optional ray-tracing mode for graphics cards that support it (RTX and recent AMD): shadows, water reflections and global lighting on top of the vanilla look.
+
+<details><summary>Technical</summary>
+
+A spike with ray-traced sun shadows, off by default, is a draft ([#1180](https://github.com/ludovic111/horizon/issues/1180)). Reflections, global illumination, Apple M3 and newer if it is cheap, and a performance report per card come after.
+
+</details>
+
+#### HDR monitors
+
+Output for HDR monitors: brighter highlights and richer colour where your screen supports it.
+
+<details><summary>Technical</summary>
+
+Issue [#1441](https://github.com/ludovic111/horizon/issues/1441). Needs a surface format and a tone-mapping path per backend, and tests on real HDR screens on Windows, macOS and Linux.
+
+</details>
+
+#### MSAA, anisotropic filtering, exclusive fullscreen
+
+More graphics options: multisample anti-aliasing, anisotropic filtering and an exclusive fullscreen mode. Today Horizon has FXAA and borderless fullscreen.
+
+<details><summary>Technical</summary>
+
+Not implemented ([docs/graphics.md](docs/graphics.md)). Anisotropic filtering needs linear magnification in wgpu, which blurs close blocks, so close-up sharpness has to be kept first; MSAA would sit beside FXAA; exclusive fullscreen where the backend supports it.
+
+</details>
+
+### Launcher
+
+#### Lean installs that use less disk
+
+Smaller installs: Horizon keeps one shared copy of the prepared game files and removes what only the preparation needed.
+
+<details><summary>Technical</summary>
+
+A shared resource store keyed by the preparer's digest, no prepare intermediates left behind, the current and the previous version kept, and an automatic clean-up. Not started.
+
+</details>
+
+### Platforms
+
+#### Horizon on Linux ARM64
+
+Game and launcher builds for 64-bit ARM Linux computers.
+
+<details><summary>Technical</summary>
+
+Issue [#1709](https://github.com/ludovic111/horizon/issues/1709): aarch64 builds of the game and the launcher in the release workflow, tested on a real ARM machine with its Vulkan driver. The server build already drops audio and controllers (`--no-default-features`).
+
+</details>
+
+#### OpenGL for old computers
+
+A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL.
+
+<details><summary>Technical</summary>
+
+Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like the DirectX 12 fallback that already ships.
+
+More: [docs/graphics.md](docs/graphics.md)
+
+</details>
+
+#### Android, iOS and the browser
+
+Versions of Horizon for Android, iOS and web browsers. Nothing official yet; contributors have started the first pieces.
+
+<details><summary>Technical</summary>
+
+No official build. Android was first closed as not planned, with touch controls, a mobile interface, packaging and loading the player's own assets all missing; the roadmap now includes it, iOS and a WebAssembly build for the browser as long-term goals. First pieces from contributors: `horizon-dualsense` compiling on iOS ([#1813](https://github.com/ludovic111/horizon/issues/1813)) and helper-thread limits on Android ([#1751](https://github.com/ludovic111/horizon/issues/1751)). Preparing without Java ([#1750](https://github.com/ludovic111/horizon/issues/1750)) matters here too. Horizon ships none of Mojang's files on any platform.
 
 </details>
 
 ### Horizon extras
 
-#### An optional AI teammate
+#### A complete video studio inside the game
 
-An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the No AI switch hides it completely.
+Record, replay and edit videos without leaving the game: record in a keypress, replay a session, cut and finish the video. One of Horizon's original goals.
 
 <details><summary>Technical</summary>
 
-Draft pull requests: the companion ([#1068](https://github.com/ludovic111/horizon/issues/1068)), its safety modes and their evaluation ([#1069](https://github.com/ludovic111/horizon/issues/1069)), and a route that finishes the game ([#1070](https://github.com/ludovic111/horizon/issues/1070)). Local models first; it ships only once the safety evaluation passes.
+Three stages. Recording: capture gameplay in a keypress with an encoder thread and little frame-time cost. Replay: a replay mode for recorded sessions. Editing: cuts, camera paths, titles and export. None of it exists yet; the agent-control socket ([docs/agent-control.md](docs/agent-control.md)) already lets tools drive the game for scripted shots.
+
+</details>
+
+### AI and agents
+
+#### An optional AI teammate
+
+An optional AI teammate you can talk to by voice. It plays beside you, helps or finishes the game with you, runs on your computer first, and exists only if you turn it on. The No AI switch hides it.
+
+<details><summary>Technical</summary>
+
+Draft pull requests: the companion ([#1068](https://github.com/ludovic111/horizon/issues/1068)), its safety modes and their evaluation ([#1069](https://github.com/ludovic111/horizon/issues/1069)) and a route that finishes the game ([#1070](https://github.com/ludovic111/horizon/issues/1070)). In the drafts: a companion that follows, fights, mines, crafts, sleeps and respawns; chat and push-to-talk voice, with speech recognition and a choice of voices; presets (very strong, helper, beat the game); a guard model with Clean, Kid and Salty modes; perception levels from Fair to All-knowing; hardware detection with a simple mode and an Advanced tab; local models first, cloud keys optional. The No AI switch is already in the game. Left: the speedrun route doesn't finish the game reliably yet, voices for more languages, and the safety evaluation, which must pass before it ships.
+
+</details>
+
+### Community
+
+#### A video series about Horizon
+
+A series of videos about how Horizon is made and what is new, with each upload announced on Discord.
+
+<details><summary>Technical</summary>
+
+Kira already shows new uploads in a read-only Discord channel (done). The series follows each stage of the project: a script, edits, titles and a thumbnail per video.
 
 </details>
 
diff --git a/roadmap/roadmap.toml b/roadmap/roadmap.toml
index 5ad4d8846..34ae8a955 100644
--- a/roadmap/roadmap.toml
+++ b/roadmap/roadmap.toml
@@ -49,10 +49,22 @@ name = "Rendering"
 id = "launcher"
 name = "Launcher"
 
+[[area]]
+id = "platforms"
+name = "Platforms"
+
 [[area]]
 id = "extras"
 name = "Horizon extras"
 
+[[area]]
+id = "ai"
+name = "AI and agents"
+
+[[area]]
+id = "community"
+name = "Community"
+
 [[area]]
 id = "project"
 name = "Code and tools"
@@ -206,6 +218,75 @@ dev = """A review of the whole tree: dead code and stubs removed (#1432, #1658),
 feature to its files and harnesses."""
 links = ["#1432", "#1658", "#1453", "#1454", "#1448", "#1707", "docs/architecture.md"]
 
+[[item]]
+id = "native-shaders"
+title = "Horizon's own shader format and kit"
+status = "now"
+area = "rendering"
+plain = """Horizon's own way to make shader packs, with tools to write and test them. Every pack is checked before it \
+runs, and the registry will list them."""
+dev = """`horizon-shader-api` (API 0.1, experimental): WGSL stages with typed inputs inside the renderer's passes, \
+options as WGSL override constants, and the `horizon-shader new|check|pack` tool with templates and the \
+example pack Golden Hour. Merged: the check every pack passes (#1820) and the tool, templates and guide \
+(#1822). In review: the post stage running in the game with hot reload (#1861), the sky stage (#1863) and \
+registry checks that use the game's own check (#1855). Left: the material, lighting and shadow stages, a \
+last-good fallback on reload, a GPU-time overlay per stage and budgets (docs/shaders.md, \
+docs/api/shaders.md). The Iris/OptiFine loader is a separate item, 'Shader packs, written again from \
+scratch'."""
+links = ["#1820", "#1822", "#1861", "#1863", "#1855", "docs/shaders.md", "docs/api/shaders.md"]
+
+[[item]]
+id = "server-mods"
+title = "Mods that run on the server"
+status = "now"
+area = "mods"
+plain = """Mods that run on the server side of a world, so a dedicated server or a LAN world can have mods that react \
+to players joining, chat and blocks being broken or placed, and that add commands."""
+dev = """API 0.3, experimental first (#1833, in review): the same sandboxed component runs on the server thread and \
+the dedicated server, with world events (block broken or placed, entity spawned or killed, player joined or \
+left), game rules and server commands with typed arguments. The world, item and entity interfaces come after \
+(see 'Mods that read and change the world'). docs/api/mods.md, docs/mods.md."""
+links = ["#1833", "docs/api/mods.md", "docs/mods.md"]
+
+[[item]]
+id = "mod-screens"
+title = "Screens, input and drawing for mods"
+status = "now"
+area = "mods"
+plain = """Mods will be able to open their own screens and settings pages and react to keys and item use, so bigger \
+mods, such as the Orbital Laser, can run on the normal game."""
+dev = """Capability `ui` is in review (#1864): mod-owned screens and a settings page under Options > Mods, built from \
+vanilla's widgets. Still to design: `input` (an item's use, key binds, the crosshair target), `render` (a \
+budgeted draw list on the native shader API) and `world` (changing blocks). Orbital Laser is the acceptance \
+test: it needs all four today through its author's fork (see 'Orbital Laser on the normal game')."""
+links = ["#1864", "docs/mods.md"]
+
+[[item]]
+id = "modder-tools"
+title = "Tools for people who make mods"
+status = "now"
+area = "mods"
+plain = """Better tools for mod makers: a test runner that needs no game window, templates for each kind of mod, and \
+clear promises about what keeps working from one version to the next."""
+dev = """`cargo horizon-mod test` runs a mod's test scripts against a fake game snapshot (#1816) and, for server \
+mods, scripted server events (#1837); the content template and the guides are merged (#1859, #1810, \
+docs/api/stability.md). Left: templates for hud, server and machine mods, typed wrappers in the SDK, a \
+frozen 0.1 compatibility mod that every runtime must load, a CI check that fails when a stable reference \
+entry is removed without a new major version, and the SDK on crates.io once the API is stable."""
+links = ["#1816", "#1837", "docs/api/stability.md", "website/docs/test-a-mod.md"]
+
+[[item]]
+id = "pregen"
+title = "Pre-generate an area with /pregen"
+status = "now"
+area = "servers"
+plain = """A /pregen command that builds an area of the world ahead of time, so players don't wait for new terrain when \
+they explore."""
+dev = """Generates, lights and saves an area before anyone walks there (#1805, a contributor's pull request, in \
+review). Useful on servers, and it moves the generation cost away from the first visit; the generation \
+speed-ups are under 'Steady frames at long render distances'."""
+links = ["#1805"]
+
 # ---------------------------------------------------------------------------------------------------- Next
 
 [[item]]
@@ -239,11 +320,14 @@ id = "benchmarks"
 title = "Fresh benchmarks against vanilla"
 status = "next"
 area = "performance"
-plain = """New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way \
-every time, on the website's Benchmarks page."""
+plain = """New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every \
+time, with a history that shows what each release changed."""
 dev = """Redo the comparison after the current performance work (#1073); reliability, coverage and presentation \
-(#1346); a scene must count as loaded only once its first chunk arrives (#1749). Players' reports come in through \
-`--benchmark` and `horizon-launcher data benchmark` (docs/benchmark.md)."""
+(#1346); a scene must count as loaded only once its first chunk arrives (#1749). Next: a performance history \
+across releases (an automatic comparison of each release with the last, on a timeline), more report fields \
+(server TPS and MSPT, power, battery drain, temperature, throttling) and more hardware (a MacBook on \
+battery, low-end laptops, community reports). Players' reports come in through `--benchmark` and \
+`horizon-launcher data benchmark` (docs/benchmark.md)."""
 links = ["#1073", "#1346", "#1749", "docs/benchmark.md"]
 
 [[item]]
@@ -262,36 +346,659 @@ links = ["#1496", "#1609", "#1608", "#1704", "#1758"]
 id = "intel-mac"
 title = "Horizon on Intel Macs"
 status = "next"
-area = "launcher"
-plain = """Builds of the game and the launcher for Macs with an Intel processor."""
+area = "platforms"
+plain = "Builds of the game and the launcher for Macs with an Intel processor."
 dev = """x86_64 game and launcher builds, picked per processor (#1171). Before it ships it needs a run on a real \
 Intel Mac: Rosetta on Apple Silicon only proves the CPU code. Requests: #1161, #1792."""
 links = ["#1171", "#1161", "#1792"]
 
+[[item]]
+id = "world-entry"
+title = "Faster world creation and entry on small CPUs"
+status = "next"
+area = "performance"
+plain = """Creating a world and joining it should be quick even on a four-thread laptop, where a fresh world at 32 \
+chunks can make you wait minutes for the first terrain."""
+dev = """Cut the per-column generation cost (noise sampling, surface rules, aquifers) and the lock convoy on \
+structure starts, and leave one core free for the rest of the game as vanilla does (#1760 and #1778, in \
+review, are listed under 'Steady frames at long render distances'). Still to profile on small CPUs: the \
+first seconds of a fresh world deliver no chunk, and fluids remesh for about a minute after loading. \
+Measured with `tools/perf_bench.py` (docs/benchmark.md, docs/profiling.md)."""
+links = ["docs/benchmark.md", "docs/profiling.md"]
+
+[[item]]
+id = "server-tick"
+title = "Servers that hold 20 TPS with 50 to 100 players"
+status = "next"
+area = "performance"
+plain = """Servers that keep 20 ticks per second with 50 to 100 players. Today Horizon holds it up to 50 bots and drops \
+to about 10 at 100."""
+dev = """Measured against vanilla on equal work (docs/server.md, Scale): Horizon is ahead with few players and when \
+exploring, but vanilla's tick is shorter with 25 to 50 players near spawn. Ideas on the list: send entity \
+changes instead of rebuilding every entity each tick (about 15 percent), fewer memory reads in random ticks \
+and collision scans, cheaper item collision checks, mob AI and natural spawning. The bot benchmark \
+(`horizon-bots`) is the proof."""
+links = ["docs/server.md"]
+
+[[item]]
+id = "low-end-mode"
+title = "Low-end computers: Steam Deck, old Macs, 8 GB"
+status = "next"
+area = "performance"
+plain = """Horizon should run well on small machines: integrated graphics, the Steam Deck, older Macs and 8 GB of \
+memory, with a battery mode that saves power on laptops."""
+dev = """Partly done: an opt-in 60 FPS cap with fewer workers on battery, Far Detail Reduced for integrated GPUs and \
+animated textures on the GPU (both shipped). Left: measured targets and fixes per class of machine (memory \
+use, worker counts, startup) on a Steam Deck, old Intel and Apple Silicon Macs and 8 GB computers, reported \
+on the Benchmarks page."""
+links = ["docs/benchmark.md", "website/docs/performance.md"]
+
+[[item]]
+id = "upscaling"
+title = "Native upscaling"
+status = "next"
+area = "performance"
+plain = """Draw the game at a lower resolution and sharpen it to your screen's size, in the way of FSR or DLSS, to gain \
+frames on weaker graphics cards. An optional graphics setting."""
+dev = """A render-scale setting below the window size with an upscaler of our own that runs on every wgpu backend. \
+Proof: frame time against native resolution on integrated GPUs, and screenshots for image quality. Issue \
+#1403."""
+links = ["#1403"]
+
+[[item]]
+id = "targeted-optimisations"
+title = "A batch of targeted optimisations"
+status = "next"
+area = "performance"
+plain = """Several smaller speed-ups, each measured: idle block entities that sleep, cheaper particles, faster \
+structure placement, high-rate mice and very large texture packs."""
+dev = """Block entities and hoppers that skip work when idle (the hopper item scan is already skipped when no item is \
+near); a particle frustum test first (also a parity gap), then particle quads built on the GPU; jigsaw \
+shortcuts that skip blocked connectors and pool elements known not to fit, with layouts unchanged (trial \
+chambers and ancient cities first); batched raw mouse input on Windows for 8000 Hz mice; a better atlas \
+packer for huge resource packs (a 64x pack builds a 704 MiB atlas for 452 MiB of textures); sign-heavy \
+scenes (#1461). Profile first, keep what pays, show before and after numbers."""
+links = ["#1461", "docs/profiling.md"]
+
+[[item]]
+id = "convert-to-rust"
+title = "A Convert to Rust button for what isn't rewritten yet"
+status = "next"
+area = "modpacks"
+plain = """When a mod, shader pack or modpack hasn't been rewritten for Horizon, one button converts what can be \
+converted, so you don't have to wait for the rewrite."""
+dev = """Generalise the mod browser's Port step (`horizon-port-pack`: the data, assets, worldgen and block and item \
+definitions of Java mods, .mrpack and CurseForge zips) to every kind of content: code mods where the API \
+allows it (see 'Mods with code') and shader packs, converting an Iris/OptiFine pack into Horizon's format. \
+The browser says what works before the install. Java code itself does not run (docs/modpacks.md, \
+docs/mod-browser.md)."""
+links = ["docs/modpacks.md", "docs/mod-browser.md"]
+
+[[item]]
+id = "code-mods"
+title = "Mods with code: machines, magic, mobs"
+status = "next"
+area = "modpacks"
+plain = """Making mods that add machines, magic and mobs work in Horizon, in steps, starting with machines. They are \
+most of what a big modpack is made of."""
+dev = """333 of the 496 mods in a big pack (ATM10) contain code. Issue #1854 ranks the API gaps (ticking block \
+entities, networking, rendering, menus, inventories) that unlock them in tiers, with machines first as the \
+recommended path and a furnace ported tick for tick as proof. The first API step is a draft (#1189, see \
+'Machines and blocks with inventories'). The path isn't started yet (docs/modpacks.md)."""
+links = ["#1854", "docs/modpacks.md"]
+
+[[item]]
+id = "datapack-browser"
+title = "Data packs in the mod browser"
+status = "next"
+area = "modpacks"
+plain = """Search and install data packs from the launcher's mod browser, for the world you choose, as you do mods and \
+resource packs."""
+dev = """A Datapacks tab beside Mods and Resource packs: install into a chosen world's datapacks folder, with the \
+same checks and 'works in Horizon' notes as the other kinds (docs/mod-browser.md)."""
+links = ["docs/mod-browser.md"]
+
+[[item]]
+id = "prepare-without-java"
+title = "Prepare a version without Java"
+status = "next"
+area = "servers"
+plain = """Set up Horizon, a server first, without Java on your computer: published tables are combined with your own \
+copy of the game."""
+dev = """Today `horizon-prepare` runs Mojang's exporters with Java. Issue #1750 proposes publishing the computed \
+version tables once from CI and assembling the rest locally from the player's own jar and assets, provided \
+the tables hold no Mojang content; a contributor offered a pull request, and it would help phones too. A \
+server-only prepare from `server.jar` alone is the first step (docs/server.md)."""
+links = ["#1750", "docs/server.md"]
+
+[[item]]
+id = "server-admin"
+title = "Server console, bans and a full admin API"
+status = "next"
+area = "servers"
+plain = """Manage a server from a console, ban and pardon players, and drive it from other tools through a full admin \
+API and an MCP server for AI agents."""
+dev = """`horizon-server console` (a text interface), `ban`, `pardon`, `ban-ip` and `mcp` over stdio. Admin API \
+additions: the player list, kick, ban, op and whitelist, an SSE stream of logs and events, a text metrics \
+endpoint, config GET and PATCH, backup delete and download. The panel's later features (bans, worlds, \
+server.properties import, logs and crash reports, modpacks) and vanilla's management protocol (the JSON-RPC \
+over WebSocket that the `management-server-*` keys configure), so vanilla's tools can manage a Horizon \
+server. docs/server.md, docs/api/server.md."""
+links = ["docs/server.md", "docs/api/server.md"]
+
+[[item]]
+id = "hosting-polish"
+title = "Hosting polish: Windows service, safe updates"
+status = "next"
+area = "servers"
+plain = """Smoother hosting: a real Windows service, a backup before every update, backups that keep the world and each \
+player's state, and a changed view distance or message without a restart."""
+dev = """A Windows service wrapper instead of the logon scheduled task; `backups.before_update`; hot reload of config \
+for view distance and the message of the day (needs engine support); backups that keep world and player \
+state (#1808, a contributor's draft, in review). docs/hosting.md, docs/server.md."""
+links = ["#1808", "docs/hosting.md"]
+
+[[item]]
+id = "tailscale-hosting"
+title = "Guided hosting with Tailscale and an invite button"
+status = "next"
+area = "servers"
+plain = """In the launcher, a guide and a button to host a server and invite friends over Tailscale, so nobody has to \
+open ports on a router."""
+dev = """On the Servers page (create, start, back up, update and invite are shipped) add a Tailscale setup that \
+explains and checks each step, and an invite button that hands friends what they need to join over the \
+tailnet. Buttons first, no docs needed, with the details in an Advanced section. Remote access over \
+Tailscale is already described in docs/server.md."""
+links = ["docs/hosting.md", "docs/server.md"]
+
+[[item]]
+id = "docker-image"
+title = "An official Docker image for servers"
+status = "next"
+area = "servers"
+plain = """An official image to run a Horizon dedicated server in Docker with one command, your own copy of the game \
+files mounted in."""
+dev = """The repository has the Dockerfile (`packaging/server/Dockerfile`: a multi-stage build on Debian \
+bookworm-slim, user `horizon`, volume `/data`, port 25565, game files mounted read-only, `HORIZON_EULA` and \
+friends answering the first-start questions), and anyone can build it (docs/hosting.md, section 9). Left: \
+publish the image to a public registry from the release workflow, tagged per release, so it follows the same \
+checks, and update the docs and the launcher. The image never holds Mojang's files."""
+links = ["docs/hosting.md", "docs/server.md"]
+
+[[item]]
+id = "one-single-player-path"
+title = "One single-player path: remove the in-frame world"
+status = "next"
+area = "gameplay"
+plain = """Single player will have one way to run, the server thread, so every fix works everywhere and there are fewer \
+bugs. The older in-frame mode goes once everything passes without it."""
+dev = """`--in-frame` (also `--no-server-thread` and `HORIZON_SERVER_THREAD=0`) still ticks the world inside the \
+window's `Game`, and most harnesses test that path. Delete it once `lan_e2e --server-thread` and the parity \
+harnesses pass on the server thread, which also halves the bug surface. See also 'Single player as a server' \
+and docs/server-levels.md."""
+links = ["docs/server-levels.md"]
+
+[[item]]
+id = "villages-combat-parity"
+title = "Villages and combat, exactly as in vanilla"
+status = "next"
+area = "gameplay"
+plain = """Villages and fights behaving as in vanilla: iron golems defending villages, villagers remembering their \
+homes, mace smashes and knockback."""
+dev = """Villages: iron golem village goals, villager memories across saves, villager age, job-site claiming on \
+dedicated servers, flower offers (#1639 is one report). Combat: the mobs' `attack_knockback` attribute, mace \
+smash logic, the hit knockback source on the host, the fire burnout biome tag. Each is checked against \
+vanilla by a harness (docs/rust-parity.md)."""
+links = ["#1639", "docs/rust-parity.md"]
+
+[[item]]
+id = "audio-device"
+title = "Choose the audio output device"
+status = "next"
+area = "gameplay"
+plain = "Pick the speakers or headphones Horizon plays through, in Music & Sounds."
+dev = """An output device list in Music & Sounds, falling back to the system default. #1035 started it: a player on \
+an older Windows computer had no sound at all, and a device choice is how such cases are found and fixed."""
+links = ["#1035"]
+
+[[item]]
+id = "mod-world-items"
+title = "Mods that read and change the world"
+status = "next"
+area = "mods"
+plain = """Mods that can see and change blocks, read inventories and items, and find and affect entities, all through \
+the server so every player sees the same thing."""
+dev = """After server mods: read blocks, states and biomes in loaded chunks and change them through the server's \
+block log, so clients and the parity harnesses see vanilla's updates; the player's inventory, held item, \
+open container and item stacks with components; entity queries near a position, a safe subset of entity data \
+and data-driven mod entity types. Snapshots and batched calls per tick, never per-block host calls in hot \
+paths. docs/api/mods.md ('Not there yet')."""
+links = ["docs/api/mods.md", "docs/modpacks.md"]
+
+[[item]]
+id = "machines-api"
+title = "Machines and blocks with inventories (API 0.4)"
+status = "next"
+area = "mods"
+plain = """Mods that add machines: blocks that tick, hold items and have their own menus. This unlocks the technology \
+mods of big modpacks."""
+dev = """Block entities and menus: ticking machines with slots, server menu logic and the menu protocol to clients, \
+energy, item and fluid transfer, data attachments, accessory slots and custom recipe types, with a typed \
+client and server channel and typed config beside them. A draft (#1189) proves a furnace ported tick for \
+tick and holds the ATM10 code-mods plan; the design is redone through the API policy before it merges \
+(docs/modpacks.md, docs/api/stability.md)."""
+links = ["#1189", "docs/modpacks.md"]
+
+[[item]]
+id = "mod-languages"
+title = "Lua and other languages for mods"
+status = "next"
+area = "mods"
+plain = """Write mods as Lua scripts, in the style of KubeJS, with no compiler, and later in other languages that pass \
+the tests. Every language runs in the same sandbox."""
+dev = """Lua first: Horizon ships a Lua interpreter that is itself a WebAssembly mod, and a script mod's manifest \
+names it and the capabilities it uses, so a script can do exactly what a compiled mod with the same manifest \
+can, with hot reload of `main.lua`. Then C, C++, Zig, Go (TinyGo), AssemblyScript and JavaScript or \
+TypeScript are measured against Rust on the same tick-heavy example, and each is supported only with a \
+template, an example and a CI test. docs/api/mods.md ('Ways in')."""
+links = ["docs/api/mods.md"]
+
+[[item]]
+id = "shader-pack-examples"
+title = "Well-known shader looks, rewritten for Horizon"
+status = "next"
+area = "rendering"
+plain = """Popular shader packs rewritten in Horizon's format, so good packs exist from the start. Only packs whose \
+licence is open source and compatible with ours are rewritten, never anything else."""
+dev = """The first candidates are Photon, Chocapic13 and MakeUp Ultra Fast, each only after its licence is read and \
+recorded: a pack is rewritten only if it is open source and compatible with Horizon's licence, and the \
+rewrite is written from the shader format's documentation and the look on screen, not from anyone's code. \
+Today only the Golden Hour example exists (`crates/horizon-shader-api/packs/golden_hour`)."""
+links = ["docs/shaders.md", "crates/horizon-shader-api/packs/golden_hour"]
+
+[[item]]
+id = "beta-label"
+title = "A visible beta label"
+status = "next"
+area = "launcher"
+plain = """A clear 'beta' label in the launcher and the game, so nobody is surprised that Horizon is still being built."""
+dev = """Show Beta in the launcher's header and about page, on the game's title screen and on the website, beside the \
+version number (docs/versioning.md)."""
+links = ["docs/versioning.md"]
+
+[[item]]
+id = "wayland-polish"
+title = "Wayland and Hyprland polish"
+status = "next"
+area = "platforms"
+plain = """Fixes for Linux desktops that use Wayland and Hyprland: fullscreen, the clipboard, the GUI scale after a \
+restart and the like."""
+dev = """Open: the GUI Scale is clamped to 2 after a restart under Hyprland, while XWayland keeps it (#1866). Earlier \
+reports covered fullscreen dropping on menu clicks, the clipboard and a white overlay (#1007, closed). \
+Checked on a real Wayland session."""
+links = ["#1866"]
+
+[[item]]
+id = "agent-control-protocol"
+title = "A versioned agent-control protocol"
+status = "next"
+area = "ai"
+plain = """A stable, documented way for AI agents and scripts to drive the game and the launcher, with versions and an \
+event stream so tools keep working as Horizon changes."""
+dev = """`hello` answers with the API version, the release and the features; `horizon-ctl --api`; MCP serverInfo; \
+reply schemas generated into the reference; a `test.` namespace for hooks; transcript compatibility tests; \
+`subscribe` as a stream of events on one connection; Horizon option files by key and saved-server commands. \
+Agent control itself (`horizon-ctl`, both MCP servers, the No AI switch) is done: docs/agent-control.md, \
+docs/api/agent-control.md."""
+links = ["docs/agent-control.md", "docs/api/agent-control.md", "docs/api/stability.md"]
+
+[[item]]
+id = "own-agents-porting"
+title = "Port mods with your own AI agent"
+status = "next"
+area = "ai"
+plain = """You can port a mod to Horizon with your own AI agent on your own computer. Horizon documents how and gives \
+you the tools, but provides no hosted agents."""
+dev = """A player runs their own agent locally with `horizon-ctl` and the MCP servers (docs/agent-control.md), `cargo \
+horizon-mod`, `horizon-port-pack` and the parity harnesses as the check. Horizon writes the guide \
+(website/docs/agents.md, docs/modpacks.md) and runs no agents, accounts or keys for players. The No AI \
+switch turns all of it off."""
+links = ["website/docs/agents.md", "docs/modpacks.md", "docs/agent-control.md"]
+
+[[item]]
+id = "x-account"
+title = "Horizon on X (coming soon)"
+status = "next"
+area = "community"
+plain = "Coming soon: an official Horizon account on X, used to announce releases and the weekly summary."
+dev = """Kira already posts the roadmap items marked `announce = true` when they ship, and the weekly summary, as \
+soon as the account's credentials exist (roadmap/README.md, 'The journal'). Waiting for the account itself."""
+links = ["roadmap/README.md"]
+
+[[item]]
+id = "agents-app"
+title = "Pipeline protection and a GitHub App for agents"
+status = "next"
+area = "project"
+plain = """Safer releases: changes to the release machinery need the owner's review, and AI agents use a smaller \
+identity of their own instead of a personal account."""
+dev = """`.github/CODEOWNERS` lists the workflows, the release and signing tools, the update-checking code and the \
+installers (#1015); the branch protection that makes it count waits for the `horizon-agent` GitHub App, \
+which reads and writes code, pull requests and issues but can't change settings, workflows, secrets or \
+members, and whose tokens last an hour. It needs the owner to create the App and switch the protection on \
+(docs/security.md)."""
+links = ["docs/security.md"]
+
+[[item]]
+id = "signed-installers"
+title = "Signed updates everywhere, installers included"
+status = "next"
+area = "project"
+plain = """Every download Horizon makes is checked against the project's signature, including the first install with \
+install.sh and install.ps1."""
+dev = """Releases carry signed checksums, and the launcher and `horizon-server update` refuse anything unsigned \
+(#1011, #1014). Left: the first install through `install.sh` and `install.ps1` still trusts only the \
+checksum GitHub publishes, because verifying Ed25519 signatures needs OpenSSL 3, which macOS doesn't ship \
+(docs/security.md)."""
+links = ["docs/security.md"]
+
 # ---------------------------------------------------------------------------------------------------- Later
 
 [[item]]
 id = "ai-companion"
 title = "An optional AI teammate"
 status = "later"
-area = "extras"
-plain = """An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the \
-No AI switch hides it completely."""
-dev = """Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069), and a route \
-that finishes the game (#1070). Local models first; it ships only once the safety evaluation passes."""
+area = "ai"
+plain = """An optional AI teammate you can talk to by voice. It plays beside you, helps or finishes the game with you, \
+runs on your computer first, and exists only if you turn it on. The No AI switch hides it."""
+dev = """Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069) and a route that \
+finishes the game (#1070). In the drafts: a companion that follows, fights, mines, crafts, sleeps and \
+respawns; chat and push-to-talk voice, with speech recognition and a choice of voices; presets (very strong, \
+helper, beat the game); a guard model with Clean, Kid and Salty modes; perception levels from Fair to \
+All-knowing; hardware detection with a simple mode and an Advanced tab; local models first, cloud keys \
+optional. The No AI switch is already in the game. Left: the speedrun route doesn't finish the game reliably \
+yet, voices for more languages, and the safety evaluation, which must pass before it ships."""
 links = ["#1068", "#1069", "#1070"]
 
 [[item]]
 id = "new-versions"
-title = "Following new Minecraft versions"
+title = "Every Minecraft version, prepared automatically"
 status = "later"
 area = "gameplay"
-plain = """When Mojang releases a new version of the game, Horizon follows it, and every system is checked against \
-the new version again."""
-dev = """The port pipeline detects a release, diffs its classes against 26.3 and writes a port report \
-(docs/version-ports.md); the harnesses then run against the new version."""
+plain = """Every past and future Minecraft version prepared for Horizon automatically. When Mojang releases one, \
+Horizon follows it, and every system is checked against it again."""
+dev = """The port pipeline (docs/version-ports.md, `tools/version_port.py`) detects a release, prepares it, diffs its \
+classes against the pinned 26.3, regenerates the data-driven tables, runs every parity harness on it and \
+writes a port report that becomes issues. The goal is as little human work as possible for any version, past \
+or future. Detection and the first slices are merged; the scheduled agent that runs it every day isn't \
+installed yet. Two versions in one build are out of scope."""
 links = ["docs/version-ports.md"]
 
+[[item]]
+id = "exact-far-terrain"
+title = "Exact far terrain from real chunks"
+status = "later"
+area = "performance"
+plain = """Far terrain drawn from the world you really built and explored, caves and builds included, not only a \
+preview from the seed."""
+dev = """Keep a 3D mip store on disk built from real chunks, drawn by the GPU beside the seed preview for areas \
+nobody has visited. Written from scratch and measured before it is kept. Builds on Far Detail and the \
+far-terrain levels of detail already shipped; the open work on them is #718."""
+links = ["#718"]
+
+[[item]]
+id = "older-jars"
+title = "Older Fabric and Forge mods"
+status = "later"
+area = "modpacks"
+plain = """Recognise mods built for versions before 26.1 in the mod browser, so they can be checked and carried over \
+like newer ones."""
+dev = """A mapping table from intermediary and SRG names so pre-26.1 jars can be classified, and a rename for mod ids \
+with dashes (`fabric-api`); the port step then treats them like newer jars (docs/mod-browser.md)."""
+links = ["docs/mod-browser.md"]
+
+[[item]]
+id = "modpack-own-packs"
+title = "A modpack's own resource and shader packs"
+status = "later"
+area = "modpacks"
+plain = """Importing a modpack also brings the resource packs and shader packs it ships with, where Horizon can use \
+them."""
+dev = """Porting a pack carries data, assets and worldgen today; the resource packs and shader packs bundled with it \
+are left out. Resource packs can be carried as they are; shader packs go through the converter \
+(docs/modpacks.md)."""
+links = ["docs/modpacks.md"]
+
+[[item]]
+id = "whole-modpacks"
+title = "Whole modpacks, such as ATM10, rewritten"
+status = "later"
+area = "modpacks"
+plain = """Rewriting a complete big modpack for Horizon so it runs far better than the original. Not a priority now: \
+the work above comes first."""
+dev = """The project's first goal for modpacks: support them ten times better than vanilla and port any of them. It \
+was set aside in favour of compatibility through the browser. What exists: ATM10's world generates and 42 of \
+its 496 mods are carried at least in part (docs/modpacks.md). It depends on 'Mods with code' and the native \
+mod API."""
+links = ["docs/modpacks.md"]
+
+[[item]]
+id = "java-mod-bridge"
+title = "Running Java mods that aren't rewritten"
+status = "later"
+area = "modpacks"
+plain = """Run Java mods that nobody has rewritten for Horizon yet, through a bridge or a converter. Hard and not \
+started: the Convert button and native rewrites come first."""
+dev = """Earlier research (#527, closed) found that Java mods can't simply run, because they call Minecraft's own \
+classes. Options to look at again: a jar-to-WebAssembly backend, or a bridge for simple Fabric mods. \
+Whatever is chosen has to run inside the same sandbox and capability checks as native mods."""
+links = ["#527"]
+
+[[item]]
+id = "alt-accounts"
+title = "Ely.by and other sign-in providers"
+status = "later"
+area = "servers"
+plain = """Sign in with other account providers, such as Ely.by or any Yggdrasil-compatible one, beside Microsoft."""
+dev = """Issue #1270 asks for Ely.by and Yggdrasil-compatible servers with an account selector in the launcher. It \
+builds on the Microsoft sign-in (docs/microsoft-account.md)."""
+links = ["#1270", "docs/microsoft-account.md"]
+
+[[item]]
+id = "friends-online-mode"
+title = "Online-mode checks for Play with Friends"
+status = "later"
+area = "servers"
+plain = """Friends who join through an invite code could prove who they are with their Microsoft account, as on \
+online-mode servers."""
+dev = """Play with Friends joins over an encrypted tunnel with an invite code (docs/play-with-friends.md, \
+'Identity'). Online-mode checks against Mojang's session servers can be added on top of the same tunnel; \
+they need Microsoft sign-in first, which is coming soon. Play with Friends stays self-hosted between \
+players, with no relay run by the project."""
+links = ["docs/play-with-friends.md"]
+
+[[item]]
+id = "orbital-laser"
+title = "Orbital Laser on the normal game"
+status = "later"
+area = "mods"
+plain = """The community mod Orbital Laser, made for a fork of Horizon, running on the normal game and listed in the \
+registry as the showcase of the mod API."""
+dev = """A pull request on https://github.com/Stink-O/orbital-laser (MIT) once the input, ui, render and world \
+capabilities exist (see 'Screens, input and drawing for mods'): today the mod needs them through its \
+author's fork. Tested in the game, and listed in the registry."""
+links = ["https://github.com/Stink-O/orbital-laser"]
+
+[[item]]
+id = "client-mod-natives"
+title = "Native versions of popular client mods"
+status = "later"
+area = "mods"
+plain = """Built-in versions of the client mods players ask for: block info on hover, a recipe viewer like JEI, a world \
+map and schematic overlays."""
+dev = """Done as extras: a mod list and menu, a minimap and a zoom (docs/extras.md). Left: block info tooltips, a \
+recipe viewer (a contributor offered to port JEI if it becomes a native feature), a world map and a \
+schematic overlay. They need the read-only interfaces `inventory-read`, `recipes`, `world-read` and `render` \
+in the mod API, or they go into the game directly."""
+links = ["docs/extras.md", "docs/mods.md"]
+
+[[item]]
+id = "create-physics"
+title = "Create-style physics as a native mod"
+status = "later"
+area = "mods"
+plain = """Contraptions and physics like the Create and Aeronautics mods, as a mod for Horizon rather than part of the \
+base game."""
+dev = """Issue #805 (porting QOL mods) closed with this answer: it would come as a native Horizon mod on the mod API. \
+It needs server mods, entities and rendering first."""
+links = ["#805"]
+
+[[item]]
+id = "proximity-voice"
+title = "Proximity voice chat as a native mod"
+status = "later"
+area = "mods"
+plain = """Hear nearby players talk, as with the voice chat mods of other Minecraft versions, as a Horizon mod."""
+dev = """Needs server mods, mod networking and an audio interface in the mod API before anything can be built \
+(docs/api/mods.md)."""
+links = ["docs/api/mods.md"]
+
+[[item]]
+id = "light-default-pack"
+title = "A light default shader pack"
+status = "later"
+area = "rendering"
+plain = """A small built-in look (tone mapping, colour grade, a cheap vignette) that costs almost nothing, for players \
+who want a nicer picture without a heavy pack."""
+dev = """An opt-in, composite-only pack on the native shader API, under about 0.3 ms at 1080p, shown on the Shader \
+Packs page. Pack option sliders and profiles, and a Failed row with the full error, belong with it."""
+links = ["docs/shaders.md"]
+
+[[item]]
+id = "ray-tracing"
+title = "Optional ray tracing"
+status = "later"
+area = "rendering"
+plain = """An optional ray-tracing mode for graphics cards that support it (RTX and recent AMD): shadows, water \
+reflections and global lighting on top of the vanilla look."""
+dev = """A spike with ray-traced sun shadows, off by default, is a draft (#1180). Reflections, global illumination, \
+Apple M3 and newer if it is cheap, and a performance report per card come after."""
+links = ["#1180"]
+
+[[item]]
+id = "hdr"
+title = "HDR monitors"
+status = "later"
+area = "rendering"
+plain = "Output for HDR monitors: brighter highlights and richer colour where your screen supports it."
+dev = """Issue #1441. Needs a surface format and a tone-mapping path per backend, and tests on real HDR screens on \
+Windows, macOS and Linux."""
+links = ["#1441"]
+
+[[item]]
+id = "msaa-fullscreen"
+title = "MSAA, anisotropic filtering, exclusive fullscreen"
+status = "later"
+area = "rendering"
+plain = """More graphics options: multisample anti-aliasing, anisotropic filtering and an exclusive fullscreen mode. \
+Today Horizon has FXAA and borderless fullscreen."""
+dev = """Not implemented (docs/graphics.md). Anisotropic filtering needs linear magnification in wgpu, which blurs \
+close blocks, so close-up sharpness has to be kept first; MSAA would sit beside FXAA; exclusive fullscreen \
+where the backend supports it."""
+links = ["docs/graphics.md"]
+
+[[item]]
+id = "video-studio"
+title = "A complete video studio inside the game"
+status = "later"
+area = "extras"
+plain = """Record, replay and edit videos without leaving the game: record in a keypress, replay a session, cut and \
+finish the video. One of Horizon's original goals."""
+dev = """Three stages. Recording: capture gameplay in a keypress with an encoder thread and little frame-time cost. \
+Replay: a replay mode for recorded sessions. Editing: cuts, camera paths, titles and export. None of it \
+exists yet; the agent-control socket (docs/agent-control.md) already lets tools drive the game for scripted \
+shots."""
+links = ["docs/agent-control.md"]
+
+[[item]]
+id = "controllers"
+title = "Controllers: tested on real pads, and in the launcher"
+status = "later"
+area = "gameplay"
+plain = """Make controller support solid: tested with real PlayStation and Xbox pads and a Steam Deck, and usable in \
+the launcher too."""
+dev = """The game side is merged (docs/controllers.md): pads read with gilrs, menus, rumble, glyphs, remapping and \
+DualSense adaptive triggers, lightbar and haptics, but not yet confirmed on real pads or a Steam Deck \
+(DualSense haptics stay behind a switch until then). Left: a test pass on real hardware, and the same focus \
+navigation in the GPUI launcher."""
+links = ["docs/controllers.md"]
+
+[[item]]
+id = "debug-screen"
+title = "The full debug screen"
+status = "later"
+area = "gameplay"
+plain = """Vanilla's complete F3 screen: debug options, a profiler chart, ten-second captures and an atlas dump."""
+dev = """Today F3 shows position, chunk, light, biome and FPS (docs/native-client.md). Vanilla also has F3+F6 debug \
+options with profiles, F3+1 the profiler pie, F3+L a ten-second capture and F3+S the atlas dump (#562 asked \
+for the F3 editor)."""
+links = ["#562", "docs/native-client.md"]
+
+[[item]]
+id = "lean-installs"
+title = "Lean installs that use less disk"
+status = "later"
+area = "launcher"
+plain = """Smaller installs: Horizon keeps one shared copy of the prepared game files and removes what only the \
+preparation needed."""
+dev = """A shared resource store keyed by the preparer's digest, no prepare intermediates left behind, the current \
+and the previous version kept, and an automatic clean-up. Not started."""
+
+[[item]]
+id = "linux-arm64"
+title = "Horizon on Linux ARM64"
+status = "later"
+area = "platforms"
+plain = "Game and launcher builds for 64-bit ARM Linux computers."
+dev = """Issue #1709: aarch64 builds of the game and the launcher in the release workflow, tested on a real ARM \
+machine with its Vulkan driver. The server build already drops audio and controllers \
+(`--no-default-features`)."""
+links = ["#1709"]
+
+[[item]]
+id = "opengl-fallback"
+title = "OpenGL for old computers"
+status = "later"
+area = "platforms"
+plain = "A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL."
+dev = """Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL \
+backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like \
+the DirectX 12 fallback that already ships."""
+links = ["docs/graphics.md"]
+
+[[item]]
+id = "phones-and-browser"
+title = "Android, iOS and the browser"
+status = "later"
+area = "platforms"
+plain = """Versions of Horizon for Android, iOS and web browsers. Nothing official yet; contributors have started the \
+first pieces."""
+dev = """No official build. Android was first closed as not planned, with touch controls, a mobile interface, \
+packaging and loading the player's own assets all missing; the roadmap now includes it, iOS and a \
+WebAssembly build for the browser as long-term goals. First pieces from contributors: `horizon-dualsense` \
+compiling on iOS (#1813) and helper-thread limits on Android (#1751). Preparing without Java (#1750) matters \
+here too. Horizon ships none of Mojang's files on any platform."""
+links = ["#1813", "#1751"]
+
+[[item]]
+id = "video-series"
+title = "A video series about Horizon"
+status = "later"
+area = "community"
+plain = """A series of videos about how Horizon is made and what is new, with each upload announced on Discord."""
+dev = """Kira already shows new uploads in a read-only Discord channel (done). The series follows each stage of the \
+project: a script, edits, titles and a thumbnail per video."""
+
 # ---------------------------------------------------------------------------------------------------- Help wanted
 
 [[item]]
diff --git a/website/data/roadmap.json b/website/data/roadmap.json
index 1fcbdd773..4af2a460f 100644
--- a/website/data/roadmap.json
+++ b/website/data/roadmap.json
@@ -59,10 +59,22 @@
    "id": "launcher",
    "name": "Launcher"
   },
+  {
+   "id": "platforms",
+   "name": "Platforms"
+  },
   {
    "id": "extras",
    "name": "Horizon extras"
   },
+  {
+   "id": "ai",
+   "name": "AI and agents"
+  },
+  {
+   "id": "community",
+   "name": "Community"
+  },
   {
    "id": "project",
    "name": "Code and tools"
@@ -255,6 +267,73 @@
    ],
    "ongoing": true
   },
+  {
+   "id": "native-shaders",
+   "title": "Horizon's own shader format and kit",
+   "status": "now",
+   "area": "rendering",
+   "plain": "Horizon's own way to make shader packs, with tools to write and test them. Every pack is checked before it runs, and the registry will list them.",
+   "dev": "`horizon-shader-api` (API 0.1, experimental): WGSL stages with typed inputs inside the renderer's passes, options as WGSL override constants, and the `horizon-shader new|check|pack` tool with templates and the example pack Golden Hour. Merged: the check every pack passes (#1820) and the tool, templates and guide (#1822). In review: the post stage running in the game with hot reload (#1861), the sky stage (#1863) and registry checks that use the game's own check (#1855). Left: the material, lighting and shadow stages, a last-good fallback on reload, a GPU-time overlay per stage and budgets (docs/shaders.md, docs/api/shaders.md). The Iris/OptiFine loader is a separate item, 'Shader packs, written again from scratch'.",
+   "links": [
+    "#1820",
+    "#1822",
+    "#1861",
+    "#1863",
+    "#1855",
+    "docs/shaders.md",
+    "docs/api/shaders.md"
+   ]
+  },
+  {
+   "id": "server-mods",
+   "title": "Mods that run on the server",
+   "status": "now",
+   "area": "mods",
+   "plain": "Mods that run on the server side of a world, so a dedicated server or a LAN world can have mods that react to players joining, chat and blocks being broken or placed, and that add commands.",
+   "dev": "API 0.3, experimental first (#1833, in review): the same sandboxed component runs on the server thread and the dedicated server, with world events (block broken or placed, entity spawned or killed, player joined or left), game rules and server commands with typed arguments. The world, item and entity interfaces come after (see 'Mods that read and change the world'). docs/api/mods.md, docs/mods.md.",
+   "links": [
+    "#1833",
+    "docs/api/mods.md",
+    "docs/mods.md"
+   ]
+  },
+  {
+   "id": "mod-screens",
+   "title": "Screens, input and drawing for mods",
+   "status": "now",
+   "area": "mods",
+   "plain": "Mods will be able to open their own screens and settings pages and react to keys and item use, so bigger mods, such as the Orbital Laser, can run on the normal game.",
+   "dev": "Capability `ui` is in review (#1864): mod-owned screens and a settings page under Options > Mods, built from vanilla's widgets. Still to design: `input` (an item's use, key binds, the crosshair target), `render` (a budgeted draw list on the native shader API) and `world` (changing blocks). Orbital Laser is the acceptance test: it needs all four today through its author's fork (see 'Orbital Laser on the normal game').",
+   "links": [
+    "#1864",
+    "docs/mods.md"
+   ]
+  },
+  {
+   "id": "modder-tools",
+   "title": "Tools for people who make mods",
+   "status": "now",
+   "area": "mods",
+   "plain": "Better tools for mod makers: a test runner that needs no game window, templates for each kind of mod, and clear promises about what keeps working from one version to the next.",
+   "dev": "`cargo horizon-mod test` runs a mod's test scripts against a fake game snapshot (#1816) and, for server mods, scripted server events (#1837); the content template and the guides are merged (#1859, #1810, docs/api/stability.md). Left: templates for hud, server and machine mods, typed wrappers in the SDK, a frozen 0.1 compatibility mod that every runtime must load, a CI check that fails when a stable reference entry is removed without a new major version, and the SDK on crates.io once the API is stable.",
+   "links": [
+    "#1816",
+    "#1837",
+    "docs/api/stability.md",
+    "website/docs/test-a-mod.md"
+   ]
+  },
+  {
+   "id": "pregen",
+   "title": "Pre-generate an area with /pregen",
+   "status": "now",
+   "area": "servers",
+   "plain": "A /pregen command that builds an area of the world ahead of time, so players don't wait for new terrain when they explore.",
+   "dev": "Generates, lights and saves an area before anyone walks there (#1805, a contributor's pull request, in review). Useful on servers, and it moves the generation cost away from the first visit; the generation speed-ups are under 'Steady frames at long render distances'.",
+   "links": [
+    "#1805"
+   ]
+  },
   {
    "id": "microsoft-sign-in",
    "title": "Microsoft sign-in (coming soon)",
@@ -286,8 +365,8 @@
    "title": "Fresh benchmarks against vanilla",
    "status": "next",
    "area": "performance",
-   "plain": "New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, on the website's Benchmarks page.",
-   "dev": "Redo the comparison after the current performance work (#1073); reliability, coverage and presentation (#1346); a scene must count as loaded only once its first chunk arrives (#1749). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` (docs/benchmark.md).",
+   "plain": "New public numbers comparing Horizon with vanilla on many kinds of computers, measured the same way every time, with a history that shows what each release changed.",
+   "dev": "Redo the comparison after the current performance work (#1073); reliability, coverage and presentation (#1346); a scene must count as loaded only once its first chunk arrives (#1749). Next: a performance history across releases (an automatic comparison of each release with the last, on a timeline), more report fields (server TPS and MSPT, power, battery drain, temperature, throttling) and more hardware (a MacBook on battery, low-end laptops, community reports). Players' reports come in through `--benchmark` and `horizon-launcher data benchmark` (docs/benchmark.md).",
    "links": [
     "#1073",
     "#1346",
@@ -314,7 +393,7 @@
    "id": "intel-mac",
    "title": "Horizon on Intel Macs",
    "status": "next",
-   "area": "launcher",
+   "area": "platforms",
    "plain": "Builds of the game and the launcher for Macs with an Intel processor.",
    "dev": "x86_64 game and launcher builds, picked per processor (#1171). Before it ships it needs a run on a real Intel Mac: Rosetta on Apple Silicon only proves the CPU code. Requests: #1161, #1792.",
    "links": [
@@ -323,13 +402,328 @@
     "#1792"
    ]
   },
+  {
+   "id": "world-entry",
+   "title": "Faster world creation and entry on small CPUs",
+   "status": "next",
+   "area": "performance",
+   "plain": "Creating a world and joining it should be quick even on a four-thread laptop, where a fresh world at 32 chunks can make you wait minutes for the first terrain.",
+   "dev": "Cut the per-column generation cost (noise sampling, surface rules, aquifers) and the lock convoy on structure starts, and leave one core free for the rest of the game as vanilla does (#1760 and #1778, in review, are listed under 'Steady frames at long render distances'). Still to profile on small CPUs: the first seconds of a fresh world deliver no chunk, and fluids remesh for about a minute after loading. Measured with `tools/perf_bench.py` (docs/benchmark.md, docs/profiling.md).",
+   "links": [
+    "docs/benchmark.md",
+    "docs/profiling.md"
+   ]
+  },
+  {
+   "id": "server-tick",
+   "title": "Servers that hold 20 TPS with 50 to 100 players",
+   "status": "next",
+   "area": "performance",
+   "plain": "Servers that keep 20 ticks per second with 50 to 100 players. Today Horizon holds it up to 50 bots and drops to about 10 at 100.",
+   "dev": "Measured against vanilla on equal work (docs/server.md, Scale): Horizon is ahead with few players and when exploring, but vanilla's tick is shorter with 25 to 50 players near spawn. Ideas on the list: send entity changes instead of rebuilding every entity each tick (about 15 percent), fewer memory reads in random ticks and collision scans, cheaper item collision checks, mob AI and natural spawning. The bot benchmark (`horizon-bots`) is the proof.",
+   "links": [
+    "docs/server.md"
+   ]
+  },
+  {
+   "id": "low-end-mode",
+   "title": "Low-end computers: Steam Deck, old Macs, 8 GB",
+   "status": "next",
+   "area": "performance",
+   "plain": "Horizon should run well on small machines: integrated graphics, the Steam Deck, older Macs and 8 GB of memory, with a battery mode that saves power on laptops.",
+   "dev": "Partly done: an opt-in 60 FPS cap with fewer workers on battery, Far Detail Reduced for integrated GPUs and animated textures on the GPU (both shipped). Left: measured targets and fixes per class of machine (memory use, worker counts, startup) on a Steam Deck, old Intel and Apple Silicon Macs and 8 GB computers, reported on the Benchmarks page.",
+   "links": [
+    "docs/benchmark.md",
+    "website/docs/performance.md"
+   ]
+  },
+  {
+   "id": "upscaling",
+   "title": "Native upscaling",
+   "status": "next",
+   "area": "performance",
+   "plain": "Draw the game at a lower resolution and sharpen it to your screen's size, in the way of FSR or DLSS, to gain frames on weaker graphics cards. An optional graphics setting.",
+   "dev": "A render-scale setting below the window size with an upscaler of our own that runs on every wgpu backend. Proof: frame time against native resolution on integrated GPUs, and screenshots for image quality. Issue #1403.",
+   "links": [
+    "#1403"
+   ]
+  },
+  {
+   "id": "targeted-optimisations",
+   "title": "A batch of targeted optimisations",
+   "status": "next",
+   "area": "performance",
+   "plain": "Several smaller speed-ups, each measured: idle block entities that sleep, cheaper particles, faster structure placement, high-rate mice and very large texture packs.",
+   "dev": "Block entities and hoppers that skip work when idle (the hopper item scan is already skipped when no item is near); a particle frustum test first (also a parity gap), then particle quads built on the GPU; jigsaw shortcuts that skip blocked connectors and pool elements known not to fit, with layouts unchanged (trial chambers and ancient cities first); batched raw mouse input on Windows for 8000 Hz mice; a better atlas packer for huge resource packs (a 64x pack builds a 704 MiB atlas for 452 MiB of textures); sign-heavy scenes (#1461). Profile first, keep what pays, show before and after numbers.",
+   "links": [
+    "#1461",
+    "docs/profiling.md"
+   ]
+  },
+  {
+   "id": "convert-to-rust",
+   "title": "A Convert to Rust button for what isn't rewritten yet",
+   "status": "next",
+   "area": "modpacks",
+   "plain": "When a mod, shader pack or modpack hasn't been rewritten for Horizon, one button converts what can be converted, so you don't have to wait for the rewrite.",
+   "dev": "Generalise the mod browser's Port step (`horizon-port-pack`: the data, assets, worldgen and block and item definitions of Java mods, .mrpack and CurseForge zips) to every kind of content: code mods where the API allows it (see 'Mods with code') and shader packs, converting an Iris/OptiFine pack into Horizon's format. The browser says what works before the install. Java code itself does not run (docs/modpacks.md, docs/mod-browser.md).",
+   "links": [
+    "docs/modpacks.md",
+    "docs/mod-browser.md"
+   ]
+  },
+  {
+   "id": "code-mods",
+   "title": "Mods with code: machines, magic, mobs",
+   "status": "next",
+   "area": "modpacks",
+   "plain": "Making mods that add machines, magic and mobs work in Horizon, in steps, starting with machines. They are most of what a big modpack is made of.",
+   "dev": "333 of the 496 mods in a big pack (ATM10) contain code. Issue #1854 ranks the API gaps (ticking block entities, networking, rendering, menus, inventories) that unlock them in tiers, with machines first as the recommended path and a furnace ported tick for tick as proof. The first API step is a draft (#1189, see 'Machines and blocks with inventories'). The path isn't started yet (docs/modpacks.md).",
+   "links": [
+    "#1854",
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "datapack-browser",
+   "title": "Data packs in the mod browser",
+   "status": "next",
+   "area": "modpacks",
+   "plain": "Search and install data packs from the launcher's mod browser, for the world you choose, as you do mods and resource packs.",
+   "dev": "A Datapacks tab beside Mods and Resource packs: install into a chosen world's datapacks folder, with the same checks and 'works in Horizon' notes as the other kinds (docs/mod-browser.md).",
+   "links": [
+    "docs/mod-browser.md"
+   ]
+  },
+  {
+   "id": "prepare-without-java",
+   "title": "Prepare a version without Java",
+   "status": "next",
+   "area": "servers",
+   "plain": "Set up Horizon, a server first, without Java on your computer: published tables are combined with your own copy of the game.",
+   "dev": "Today `horizon-prepare` runs Mojang's exporters with Java. Issue #1750 proposes publishing the computed version tables once from CI and assembling the rest locally from the player's own jar and assets, provided the tables hold no Mojang content; a contributor offered a pull request, and it would help phones too. A server-only prepare from `server.jar` alone is the first step (docs/server.md).",
+   "links": [
+    "#1750",
+    "docs/server.md"
+   ]
+  },
+  {
+   "id": "server-admin",
+   "title": "Server console, bans and a full admin API",
+   "status": "next",
+   "area": "servers",
+   "plain": "Manage a server from a console, ban and pardon players, and drive it from other tools through a full admin API and an MCP server for AI agents.",
+   "dev": "`horizon-server console` (a text interface), `ban`, `pardon`, `ban-ip` and `mcp` over stdio. Admin API additions: the player list, kick, ban, op and whitelist, an SSE stream of logs and events, a text metrics endpoint, config GET and PATCH, backup delete and download. The panel's later features (bans, worlds, server.properties import, logs and crash reports, modpacks) and vanilla's management protocol (the JSON-RPC over WebSocket that the `management-server-*` keys configure), so vanilla's tools can manage a Horizon server. docs/server.md, docs/api/server.md.",
+   "links": [
+    "docs/server.md",
+    "docs/api/server.md"
+   ]
+  },
+  {
+   "id": "hosting-polish",
+   "title": "Hosting polish: Windows service, safe updates",
+   "status": "next",
+   "area": "servers",
+   "plain": "Smoother hosting: a real Windows service, a backup before every update, backups that keep the world and each player's state, and a changed view distance or message without a restart.",
+   "dev": "A Windows service wrapper instead of the logon scheduled task; `backups.before_update`; hot reload of config for view distance and the message of the day (needs engine support); backups that keep world and player state (#1808, a contributor's draft, in review). docs/hosting.md, docs/server.md.",
+   "links": [
+    "#1808",
+    "docs/hosting.md"
+   ]
+  },
+  {
+   "id": "tailscale-hosting",
+   "title": "Guided hosting with Tailscale and an invite button",
+   "status": "next",
+   "area": "servers",
+   "plain": "In the launcher, a guide and a button to host a server and invite friends over Tailscale, so nobody has to open ports on a router.",
+   "dev": "On the Servers page (create, start, back up, update and invite are shipped) add a Tailscale setup that explains and checks each step, and an invite button that hands friends what they need to join over the tailnet. Buttons first, no docs needed, with the details in an Advanced section. Remote access over Tailscale is already described in docs/server.md.",
+   "links": [
+    "docs/hosting.md",
+    "docs/server.md"
+   ]
+  },
+  {
+   "id": "docker-image",
+   "title": "An official Docker image for servers",
+   "status": "next",
+   "area": "servers",
+   "plain": "An official image to run a Horizon dedicated server in Docker with one command, your own copy of the game files mounted in.",
+   "dev": "The repository has the Dockerfile (`packaging/server/Dockerfile`: a multi-stage build on Debian bookworm-slim, user `horizon`, volume `/data`, port 25565, game files mounted read-only, `HORIZON_EULA` and friends answering the first-start questions), and anyone can build it (docs/hosting.md, section 9). Left: publish the image to a public registry from the release workflow, tagged per release, so it follows the same checks, and update the docs and the launcher. The image never holds Mojang's files.",
+   "links": [
+    "docs/hosting.md",
+    "docs/server.md"
+   ]
+  },
+  {
+   "id": "one-single-player-path",
+   "title": "One single-player path: remove the in-frame world",
+   "status": "next",
+   "area": "gameplay",
+   "plain": "Single player will have one way to run, the server thread, so every fix works everywhere and there are fewer bugs. The older in-frame mode goes once everything passes without it.",
+   "dev": "`--in-frame` (also `--no-server-thread` and `HORIZON_SERVER_THREAD=0`) still ticks the world inside the window's `Game`, and most harnesses test that path. Delete it once `lan_e2e --server-thread` and the parity harnesses pass on the server thread, which also halves the bug surface. See also 'Single player as a server' and docs/server-levels.md.",
+   "links": [
+    "docs/server-levels.md"
+   ]
+  },
+  {
+   "id": "villages-combat-parity",
+   "title": "Villages and combat, exactly as in vanilla",
+   "status": "next",
+   "area": "gameplay",
+   "plain": "Villages and fights behaving as in vanilla: iron golems defending villages, villagers remembering their homes, mace smashes and knockback.",
+   "dev": "Villages: iron golem village goals, villager memories across saves, villager age, job-site claiming on dedicated servers, flower offers (#1639 is one report). Combat: the mobs' `attack_knockback` attribute, mace smash logic, the hit knockback source on the host, the fire burnout biome tag. Each is checked against vanilla by a harness (docs/rust-parity.md).",
+   "links": [
+    "#1639",
+    "docs/rust-parity.md"
+   ]
+  },
+  {
+   "id": "audio-device",
+   "title": "Choose the audio output device",
+   "status": "next",
+   "area": "gameplay",
+   "plain": "Pick the speakers or headphones Horizon plays through, in Music & Sounds.",
+   "dev": "An output device list in Music & Sounds, falling back to the system default. #1035 started it: a player on an older Windows computer had no sound at all, and a device choice is how such cases are found and fixed.",
+   "links": [
+    "#1035"
+   ]
+  },
+  {
+   "id": "mod-world-items",
+   "title": "Mods that read and change the world",
+   "status": "next",
+   "area": "mods",
+   "plain": "Mods that can see and change blocks, read inventories and items, and find and affect entities, all through the server so every player sees the same thing.",
+   "dev": "After server mods: read blocks, states and biomes in loaded chunks and change them through the server's block log, so clients and the parity harnesses see vanilla's updates; the player's inventory, held item, open container and item stacks with components; entity queries near a position, a safe subset of entity data and data-driven mod entity types. Snapshots and batched calls per tick, never per-block host calls in hot paths. docs/api/mods.md ('Not there yet').",
+   "links": [
+    "docs/api/mods.md",
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "machines-api",
+   "title": "Machines and blocks with inventories (API 0.4)",
+   "status": "next",
+   "area": "mods",
+   "plain": "Mods that add machines: blocks that tick, hold items and have their own menus. This unlocks the technology mods of big modpacks.",
+   "dev": "Block entities and menus: ticking machines with slots, server menu logic and the menu protocol to clients, energy, item and fluid transfer, data attachments, accessory slots and custom recipe types, with a typed client and server channel and typed config beside them. A draft (#1189) proves a furnace ported tick for tick and holds the ATM10 code-mods plan; the design is redone through the API policy before it merges (docs/modpacks.md, docs/api/stability.md).",
+   "links": [
+    "#1189",
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "mod-languages",
+   "title": "Lua and other languages for mods",
+   "status": "next",
+   "area": "mods",
+   "plain": "Write mods as Lua scripts, in the style of KubeJS, with no compiler, and later in other languages that pass the tests. Every language runs in the same sandbox.",
+   "dev": "Lua first: Horizon ships a Lua interpreter that is itself a WebAssembly mod, and a script mod's manifest names it and the capabilities it uses, so a script can do exactly what a compiled mod with the same manifest can, with hot reload of `main.lua`. Then C, C++, Zig, Go (TinyGo), AssemblyScript and JavaScript or TypeScript are measured against Rust on the same tick-heavy example, and each is supported only with a template, an example and a CI test. docs/api/mods.md ('Ways in').",
+   "links": [
+    "docs/api/mods.md"
+   ]
+  },
+  {
+   "id": "shader-pack-examples",
+   "title": "Well-known shader looks, rewritten for Horizon",
+   "status": "next",
+   "area": "rendering",
+   "plain": "Popular shader packs rewritten in Horizon's format, so good packs exist from the start. Only packs whose licence is open source and compatible with ours are rewritten, never anything else.",
+   "dev": "The first candidates are Photon, Chocapic13 and MakeUp Ultra Fast, each only after its licence is read and recorded: a pack is rewritten only if it is open source and compatible with Horizon's licence, and the rewrite is written from the shader format's documentation and the look on screen, not from anyone's code. Today only the Golden Hour example exists (`crates/horizon-shader-api/packs/golden_hour`).",
+   "links": [
+    "docs/shaders.md",
+    "crates/horizon-shader-api/packs/golden_hour"
+   ]
+  },
+  {
+   "id": "beta-label",
+   "title": "A visible beta label",
+   "status": "next",
+   "area": "launcher",
+   "plain": "A clear 'beta' label in the launcher and the game, so nobody is surprised that Horizon is still being built.",
+   "dev": "Show Beta in the launcher's header and about page, on the game's title screen and on the website, beside the version number (docs/versioning.md).",
+   "links": [
+    "docs/versioning.md"
+   ]
+  },
+  {
+   "id": "wayland-polish",
+   "title": "Wayland and Hyprland polish",
+   "status": "next",
+   "area": "platforms",
+   "plain": "Fixes for Linux desktops that use Wayland and Hyprland: fullscreen, the clipboard, the GUI scale after a restart and the like.",
+   "dev": "Open: the GUI Scale is clamped to 2 after a restart under Hyprland, while XWayland keeps it (#1866). Earlier reports covered fullscreen dropping on menu clicks, the clipboard and a white overlay (#1007, closed). Checked on a real Wayland session.",
+   "links": [
+    "#1866"
+   ]
+  },
+  {
+   "id": "agent-control-protocol",
+   "title": "A versioned agent-control protocol",
+   "status": "next",
+   "area": "ai",
+   "plain": "A stable, documented way for AI agents and scripts to drive the game and the launcher, with versions and an event stream so tools keep working as Horizon changes.",
+   "dev": "`hello` answers with the API version, the release and the features; `horizon-ctl --api`; MCP serverInfo; reply schemas generated into the reference; a `test.` namespace for hooks; transcript compatibility tests; `subscribe` as a stream of events on one connection; Horizon option files by key and saved-server commands. Agent control itself (`horizon-ctl`, both MCP servers, the No AI switch) is done: docs/agent-control.md, docs/api/agent-control.md.",
+   "links": [
+    "docs/agent-control.md",
+    "docs/api/agent-control.md",
+    "docs/api/stability.md"
+   ]
+  },
+  {
+   "id": "own-agents-porting",
+   "title": "Port mods with your own AI agent",
+   "status": "next",
+   "area": "ai",
+   "plain": "You can port a mod to Horizon with your own AI agent on your own computer. Horizon documents how and gives you the tools, but provides no hosted agents.",
+   "dev": "A player runs their own agent locally with `horizon-ctl` and the MCP servers (docs/agent-control.md), `cargo horizon-mod`, `horizon-port-pack` and the parity harnesses as the check. Horizon writes the guide (website/docs/agents.md, docs/modpacks.md) and runs no agents, accounts or keys for players. The No AI switch turns all of it off.",
+   "links": [
+    "website/docs/agents.md",
+    "docs/modpacks.md",
+    "docs/agent-control.md"
+   ]
+  },
+  {
+   "id": "x-account",
+   "title": "Horizon on X (coming soon)",
+   "status": "next",
+   "area": "community",
+   "plain": "Coming soon: an official Horizon account on X, used to announce releases and the weekly summary.",
+   "dev": "Kira already posts the roadmap items marked `announce = true` when they ship, and the weekly summary, as soon as the account's credentials exist (roadmap/README.md, 'The journal'). Waiting for the account itself.",
+   "links": [
+    "roadmap/README.md"
+   ]
+  },
+  {
+   "id": "agents-app",
+   "title": "Pipeline protection and a GitHub App for agents",
+   "status": "next",
+   "area": "project",
+   "plain": "Safer releases: changes to the release machinery need the owner's review, and AI agents use a smaller identity of their own instead of a personal account.",
+   "dev": "`.github/CODEOWNERS` lists the workflows, the release and signing tools, the update-checking code and the installers (#1015); the branch protection that makes it count waits for the `horizon-agent` GitHub App, which reads and writes code, pull requests and issues but can't change settings, workflows, secrets or members, and whose tokens last an hour. It needs the owner to create the App and switch the protection on (docs/security.md).",
+   "links": [
+    "docs/security.md"
+   ]
+  },
+  {
+   "id": "signed-installers",
+   "title": "Signed updates everywhere, installers included",
+   "status": "next",
+   "area": "project",
+   "plain": "Every download Horizon makes is checked against the project's signature, including the first install with install.sh and install.ps1.",
+   "dev": "Releases carry signed checksums, and the launcher and `horizon-server update` refuse anything unsigned (#1011, #1014). Left: the first install through `install.sh` and `install.ps1` still trusts only the checksum GitHub publishes, because verifying Ed25519 signatures needs OpenSSL 3, which macOS doesn't ship (docs/security.md).",
+   "links": [
+    "docs/security.md"
+   ]
+  },
   {
    "id": "ai-companion",
    "title": "An optional AI teammate",
    "status": "later",
-   "area": "extras",
-   "plain": "An AI teammate that plays beside you and that you can talk to. It is off unless you turn it on, and the No AI switch hides it completely.",
-   "dev": "Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069), and a route that finishes the game (#1070). Local models first; it ships only once the safety evaluation passes.",
+   "area": "ai",
+   "plain": "An optional AI teammate you can talk to by voice. It plays beside you, helps or finishes the game with you, runs on your computer first, and exists only if you turn it on. The No AI switch hides it.",
+   "dev": "Draft pull requests: the companion (#1068), its safety modes and their evaluation (#1069) and a route that finishes the game (#1070). In the drafts: a companion that follows, fights, mines, crafts, sleeps and respawns; chat and push-to-talk voice, with speech recognition and a choice of voices; presets (very strong, helper, beat the game); a guard model with Clean, Kid and Salty modes; perception levels from Fair to All-knowing; hardware detection with a simple mode and an Advanced tab; local models first, cloud keys optional. The No AI switch is already in the game. Left: the speedrun route doesn't finish the game reliably yet, voices for more languages, and the safety evaluation, which must pass before it ships.",
    "links": [
     "#1068",
     "#1069",
@@ -338,15 +732,266 @@
   },
   {
    "id": "new-versions",
-   "title": "Following new Minecraft versions",
+   "title": "Every Minecraft version, prepared automatically",
    "status": "later",
    "area": "gameplay",
-   "plain": "When Mojang releases a new version of the game, Horizon follows it, and every system is checked against the new version again.",
-   "dev": "The port pipeline detects a release, diffs its classes against 26.3 and writes a port report (docs/version-ports.md); the harnesses then run against the new version.",
+   "plain": "Every past and future Minecraft version prepared for Horizon automatically. When Mojang releases one, Horizon follows it, and every system is checked against it again.",
+   "dev": "The port pipeline (docs/version-ports.md, `tools/version_port.py`) detects a release, prepares it, diffs its classes against the pinned 26.3, regenerates the data-driven tables, runs every parity harness on it and writes a port report that becomes issues. The goal is as little human work as possible for any version, past or future. Detection and the first slices are merged; the scheduled agent that runs it every day isn't installed yet. Two versions in one build are out of scope.",
    "links": [
     "docs/version-ports.md"
    ]
   },
+  {
+   "id": "exact-far-terrain",
+   "title": "Exact far terrain from real chunks",
+   "status": "later",
+   "area": "performance",
+   "plain": "Far terrain drawn from the world you really built and explored, caves and builds included, not only a preview from the seed.",
+   "dev": "Keep a 3D mip store on disk built from real chunks, drawn by the GPU beside the seed preview for areas nobody has visited. Written from scratch and measured before it is kept. Builds on Far Detail and the far-terrain levels of detail already shipped; the open work on them is #718.",
+   "links": [
+    "#718"
+   ]
+  },
+  {
+   "id": "older-jars",
+   "title": "Older Fabric and Forge mods",
+   "status": "later",
+   "area": "modpacks",
+   "plain": "Recognise mods built for versions before 26.1 in the mod browser, so they can be checked and carried over like newer ones.",
+   "dev": "A mapping table from intermediary and SRG names so pre-26.1 jars can be classified, and a rename for mod ids with dashes (`fabric-api`); the port step then treats them like newer jars (docs/mod-browser.md).",
+   "links": [
+    "docs/mod-browser.md"
+   ]
+  },
+  {
+   "id": "modpack-own-packs",
+   "title": "A modpack's own resource and shader packs",
+   "status": "later",
+   "area": "modpacks",
+   "plain": "Importing a modpack also brings the resource packs and shader packs it ships with, where Horizon can use them.",
+   "dev": "Porting a pack carries data, assets and worldgen today; the resource packs and shader packs bundled with it are left out. Resource packs can be carried as they are; shader packs go through the converter (docs/modpacks.md).",
+   "links": [
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "whole-modpacks",
+   "title": "Whole modpacks, such as ATM10, rewritten",
+   "status": "later",
+   "area": "modpacks",
+   "plain": "Rewriting a complete big modpack for Horizon so it runs far better than the original. Not a priority now: the work above comes first.",
+   "dev": "The project's first goal for modpacks: support them ten times better than vanilla and port any of them. It was set aside in favour of compatibility through the browser. What exists: ATM10's world generates and 42 of its 496 mods are carried at least in part (docs/modpacks.md). It depends on 'Mods with code' and the native mod API.",
+   "links": [
+    "docs/modpacks.md"
+   ]
+  },
+  {
+   "id": "java-mod-bridge",
+   "title": "Running Java mods that aren't rewritten",
+   "status": "later",
+   "area": "modpacks",
+   "plain": "Run Java mods that nobody has rewritten for Horizon yet, through a bridge or a converter. Hard and not started: the Convert button and native rewrites come first.",
+   "dev": "Earlier research (#527, closed) found that Java mods can't simply run, because they call Minecraft's own classes. Options to look at again: a jar-to-WebAssembly backend, or a bridge for simple Fabric mods. Whatever is chosen has to run inside the same sandbox and capability checks as native mods.",
+   "links": [
+    "#527"
+   ]
+  },
+  {
+   "id": "alt-accounts",
+   "title": "Ely.by and other sign-in providers",
+   "status": "later",
+   "area": "servers",
+   "plain": "Sign in with other account providers, such as Ely.by or any Yggdrasil-compatible one, beside Microsoft.",
+   "dev": "Issue #1270 asks for Ely.by and Yggdrasil-compatible servers with an account selector in the launcher. It builds on the Microsoft sign-in (docs/microsoft-account.md).",
+   "links": [
+    "#1270",
+    "docs/microsoft-account.md"
+   ]
+  },
+  {
+   "id": "friends-online-mode",
+   "title": "Online-mode checks for Play with Friends",
+   "status": "later",
+   "area": "servers",
+   "plain": "Friends who join through an invite code could prove who they are with their Microsoft account, as on online-mode servers.",
+   "dev": "Play with Friends joins over an encrypted tunnel with an invite code (docs/play-with-friends.md, 'Identity'). Online-mode checks against Mojang's session servers can be added on top of the same tunnel; they need Microsoft sign-in first, which is coming soon. Play with Friends stays self-hosted between players, with no relay run by the project.",
+   "links": [
+    "docs/play-with-friends.md"
+   ]
+  },
+  {
+   "id": "orbital-laser",
+   "title": "Orbital Laser on the normal game",
+   "status": "later",
+   "area": "mods",
+   "plain": "The community mod Orbital Laser, made for a fork of Horizon, running on the normal game and listed in the registry as the showcase of the mod API.",
+   "dev": "A pull request on https://github.com/Stink-O/orbital-laser (MIT) once the input, ui, render and world capabilities exist (see 'Screens, input and drawing for mods'): today the mod needs them through its author's fork. Tested in the game, and listed in the registry.",
+   "links": [
+    "https://github.com/Stink-O/orbital-laser"
+   ]
+  },
+  {
+   "id": "client-mod-natives",
+   "title": "Native versions of popular client mods",
+   "status": "later",
+   "area": "mods",
+   "plain": "Built-in versions of the client mods players ask for: block info on hover, a recipe viewer like JEI, a world map and schematic overlays.",
+   "dev": "Done as extras: a mod list and menu, a minimap and a zoom (docs/extras.md). Left: block info tooltips, a recipe viewer (a contributor offered to port JEI if it becomes a native feature), a world map and a schematic overlay. They need the read-only interfaces `inventory-read`, `recipes`, `world-read` and `render` in the mod API, or they go into the game directly.",
+   "links": [
+    "docs/extras.md",
+    "docs/mods.md"
+   ]
+  },
+  {
+   "id": "create-physics",
+   "title": "Create-style physics as a native mod",
+   "status": "later",
+   "area": "mods",
+   "plain": "Contraptions and physics like the Create and Aeronautics mods, as a mod for Horizon rather than part of the base game.",
+   "dev": "Issue #805 (porting QOL mods) closed with this answer: it would come as a native Horizon mod on the mod API. It needs server mods, entities and rendering first.",
+   "links": [
+    "#805"
+   ]
+  },
+  {
+   "id": "proximity-voice",
+   "title": "Proximity voice chat as a native mod",
+   "status": "later",
+   "area": "mods",
+   "plain": "Hear nearby players talk, as with the voice chat mods of other Minecraft versions, as a Horizon mod.",
+   "dev": "Needs server mods, mod networking and an audio interface in the mod API before anything can be built (docs/api/mods.md).",
+   "links": [
+    "docs/api/mods.md"
+   ]
+  },
+  {
+   "id": "light-default-pack",
+   "title": "A light default shader pack",
+   "status": "later",
+   "area": "rendering",
+   "plain": "A small built-in look (tone mapping, colour grade, a cheap vignette) that costs almost nothing, for players who want a nicer picture without a heavy pack.",
+   "dev": "An opt-in, composite-only pack on the native shader API, under about 0.3 ms at 1080p, shown on the Shader Packs page. Pack option sliders and profiles, and a Failed row with the full error, belong with it.",
+   "links": [
+    "docs/shaders.md"
+   ]
+  },
+  {
+   "id": "ray-tracing",
+   "title": "Optional ray tracing",
+   "status": "later",
+   "area": "rendering",
+   "plain": "An optional ray-tracing mode for graphics cards that support it (RTX and recent AMD): shadows, water reflections and global lighting on top of the vanilla look.",
+   "dev": "A spike with ray-traced sun shadows, off by default, is a draft (#1180). Reflections, global illumination, Apple M3 and newer if it is cheap, and a performance report per card come after.",
+   "links": [
+    "#1180"
+   ]
+  },
+  {
+   "id": "hdr",
+   "title": "HDR monitors",
+   "status": "later",
+   "area": "rendering",
+   "plain": "Output for HDR monitors: brighter highlights and richer colour where your screen supports it.",
+   "dev": "Issue #1441. Needs a surface format and a tone-mapping path per backend, and tests on real HDR screens on Windows, macOS and Linux.",
+   "links": [
+    "#1441"
+   ]
+  },
+  {
+   "id": "msaa-fullscreen",
+   "title": "MSAA, anisotropic filtering, exclusive fullscreen",
+   "status": "later",
+   "area": "rendering",
+   "plain": "More graphics options: multisample anti-aliasing, anisotropic filtering and an exclusive fullscreen mode. Today Horizon has FXAA and borderless fullscreen.",
+   "dev": "Not implemented (docs/graphics.md). Anisotropic filtering needs linear magnification in wgpu, which blurs close blocks, so close-up sharpness has to be kept first; MSAA would sit beside FXAA; exclusive fullscreen where the backend supports it.",
+   "links": [
+    "docs/graphics.md"
+   ]
+  },
+  {
+   "id": "video-studio",
+   "title": "A complete video studio inside the game",
+   "status": "later",
+   "area": "extras",
+   "plain": "Record, replay and edit videos without leaving the game: record in a keypress, replay a session, cut and finish the video. One of Horizon's original goals.",
+   "dev": "Three stages. Recording: capture gameplay in a keypress with an encoder thread and little frame-time cost. Replay: a replay mode for recorded sessions. Editing: cuts, camera paths, titles and export. None of it exists yet; the agent-control socket (docs/agent-control.md) already lets tools drive the game for scripted shots.",
+   "links": [
+    "docs/agent-control.md"
+   ]
+  },
+  {
+   "id": "controllers",
+   "title": "Controllers: tested on real pads, and in the launcher",
+   "status": "later",
+   "area": "gameplay",
+   "plain": "Make controller support solid: tested with real PlayStation and Xbox pads and a Steam Deck, and usable in the launcher too.",
+   "dev": "The game side is merged (docs/controllers.md): pads read with gilrs, menus, rumble, glyphs, remapping and DualSense adaptive triggers, lightbar and haptics, but not yet confirmed on real pads or a Steam Deck (DualSense haptics stay behind a switch until then). Left: a test pass on real hardware, and the same focus navigation in the GPUI launcher.",
+   "links": [
+    "docs/controllers.md"
+   ]
+  },
+  {
+   "id": "debug-screen",
+   "title": "The full debug screen",
+   "status": "later",
+   "area": "gameplay",
+   "plain": "Vanilla's complete F3 screen: debug options, a profiler chart, ten-second captures and an atlas dump.",
+   "dev": "Today F3 shows position, chunk, light, biome and FPS (docs/native-client.md). Vanilla also has F3+F6 debug options with profiles, F3+1 the profiler pie, F3+L a ten-second capture and F3+S the atlas dump (#562 asked for the F3 editor).",
+   "links": [
+    "#562",
+    "docs/native-client.md"
+   ]
+  },
+  {
+   "id": "lean-installs",
+   "title": "Lean installs that use less disk",
+   "status": "later",
+   "area": "launcher",
+   "plain": "Smaller installs: Horizon keeps one shared copy of the prepared game files and removes what only the preparation needed.",
+   "dev": "A shared resource store keyed by the preparer's digest, no prepare intermediates left behind, the current and the previous version kept, and an automatic clean-up. Not started."
+  },
+  {
+   "id": "linux-arm64",
+   "title": "Horizon on Linux ARM64",
+   "status": "later",
+   "area": "platforms",
+   "plain": "Game and launcher builds for 64-bit ARM Linux computers.",
+   "dev": "Issue #1709: aarch64 builds of the game and the launcher in the release workflow, tested on a real ARM machine with its Vulkan driver. The server build already drops audio and controllers (`--no-default-features`).",
+   "links": [
+    "#1709"
+   ]
+  },
+  {
+   "id": "opengl-fallback",
+   "title": "OpenGL for old computers",
+   "status": "later",
+   "area": "platforms",
+   "plain": "A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL.",
+   "dev": "Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like the DirectX 12 fallback that already ships.",
+   "links": [
+    "docs/graphics.md"
+   ]
+  },
+  {
+   "id": "phones-and-browser",
+   "title": "Android, iOS and the browser",
+   "status": "later",
+   "area": "platforms",
+   "plain": "Versions of Horizon for Android, iOS and web browsers. Nothing official yet; contributors have started the first pieces.",
+   "dev": "No official build. Android was first closed as not planned, with touch controls, a mobile interface, packaging and loading the player's own assets all missing; the roadmap now includes it, iOS and a WebAssembly build for the browser as long-term goals. First pieces from contributors: `horizon-dualsense` compiling on iOS (#1813) and helper-thread limits on Android (#1751). Preparing without Java (#1750) matters here too. Horizon ships none of Mojang's files on any platform.",
+   "links": [
+    "#1813",
+    "#1751"
+   ]
+  },
+  {
+   "id": "video-series",
+   "title": "A video series about Horizon",
+   "status": "later",
+   "area": "community",
+   "plain": "A series of videos about how Horizon is made and what is new, with each upload announced on Discord.",
+   "dev": "Kira already shows new uploads in a read-only Discord channel (done). The series follows each stage of the project: a script, edits, titles and a thumbnail per video."
+  },
   {
    "id": "benchmark-your-pc",
    "title": "Benchmark your computer",

From 72b9daabf01ee530be04b6dba5f3f58fe9ef2410 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 18:24:46 +0100
Subject: [PATCH 152/270] =?UTF-8?q?Resolve=20legacy=20=C2=A7=20codes=20whe?=
 =?UTF-8?q?re=20the=20font=20draws=20text?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Name tags and styled HUD text drew a span's § codes as glyphs instead of
restyling what follows, as StringDecomposer.iterateFormatted does. A team
prefix like "§c" showed literally over players' heads, and a resource
pack's styled menu.disconnect kept its codes on the leave-server button.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/font.rs       |  5 ++++-
 crates/horizon-client/src/game/names.rs | 12 ++++++++----
 crates/horizon-client/src/hud.rs        |  3 +++
 crates/horizon-client/src/text.rs       | 25 +++++++++++++++++++++++++
 crates/horizon-client/src/ui.rs         | 12 ++++++++++--
 5 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/crates/horizon-client/src/font.rs b/crates/horizon-client/src/font.rs
index 801a892d5..1903cab7e 100644
--- a/crates/horizon-client/src/font.rs
+++ b/crates/horizon-client/src/font.rs
@@ -891,8 +891,11 @@ impl Font {
         }
         s.chars().map(|c| self.glyph(c).advance).sum::<f32>().ceil()
     }
+    /// Font.width of a component: `§` codes in the spans are formatting,
+    /// not glyphs.
     pub fn width_text(&self, t: &Text) -> f32 {
-        t.chars()
+        t.resolved()
+            .chars()
             .map(|(c, s)| self.advance(c, s))
             .sum::<f32>()
             .ceil()
diff --git a/crates/horizon-client/src/game/names.rs b/crates/horizon-client/src/game/names.rs
index be829f1bb..7655fb489 100644
--- a/crates/horizon-client/src/game/names.rs
+++ b/crates/horizon-client/src/game/names.rs
@@ -151,10 +151,13 @@ impl Game<'_> {
                     .clone()
                     .unwrap_or_else(|| Text::literal(&name))
             };
+            // StringDecomposer.iterateFormatted: `§` codes a server leaves
+            // inside the team prefix or the name itself apply at draw time.
             let shown = match team {
                 Some(t) => t.formatted_name(member),
                 None => member,
-            };
+            }
+            .resolve_legacy();
             let mut lines = Vec::new();
             // EntityRenderer.extractNameTags: the score shows within the
             // below-name distance (10), under the name.
@@ -162,7 +165,7 @@ impl Game<'_> {
             if distance_sqr < 10.0 * 10.0
                 && let Some(score) = holder.and_then(|h| self.below_name_text(&h))
             {
-                lines.push((score, 0.0));
+                lines.push((score.resolve_legacy(), 0.0));
                 lift = f64::from(9.0f32 * 1.15 * 0.025);
             }
             lines.push((shown, lift));
@@ -213,14 +216,15 @@ impl Game<'_> {
             let shown = match team {
                 Some(t) => t.formatted_name(name.clone()),
                 None => name.clone(),
-            };
+            }
+            .resolve_legacy();
             let mut lines = Vec::new();
             let mut lift = 0.0;
             let holder = self.persist.uuids.get(&a.id).map(|u| uuid_text(*u));
             if distance_sqr < 10.0 * 10.0
                 && let Some(score) = holder.and_then(|h| self.below_name_text(&h))
             {
-                lines.push((score, 0.0));
+                lines.push((score.resolve_legacy(), 0.0));
                 lift = f64::from(9.0f32 * 1.15 * 0.025);
             }
             lines.push((shown, lift));
diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs
index 617126c2e..4e3290f15 100644
--- a/crates/horizon-client/src/hud.rs
+++ b/crates/horizon-client/src/hud.rs
@@ -890,6 +890,9 @@ impl HudBatch {
         color: u32,
         shadow: bool,
     ) -> f32 {
+        // StringDecomposer.iterateFormatted inside Font.drawInternal:
+        // `§` codes inside a span restyle what follows and are not drawn.
+        let text = text.resolved();
         let font = &atlas.font;
         let alpha = (color >> 24) as u8;
         let mut glyphs = Vec::new();
diff --git a/crates/horizon-client/src/text.rs b/crates/horizon-client/src/text.rs
index 1254d32f6..4c04c9da5 100644
--- a/crates/horizon-client/src/text.rs
+++ b/crates/horizon-client/src/text.rs
@@ -428,6 +428,15 @@ impl Text {
         }
         out
     }
+    /// `resolve_legacy` borrowing `self` when no span holds a `§` code (the
+    /// common case).
+    pub fn resolved(&self) -> std::borrow::Cow<'_, Text> {
+        if self.spans.iter().any(|s| s.text.contains('§')) {
+            std::borrow::Cow::Owned(self.resolve_legacy())
+        } else {
+            std::borrow::Cow::Borrowed(self)
+        }
+    }
     /// The text without its legacy `§` codes (ChatFormatting.stripFormatting:
     /// a `§` and a code character, `0`-`9`, `a`-`f`, `k`-`o` or `r`).
     pub fn strip_legacy(&self) -> Text {
@@ -695,4 +704,20 @@ mod tests {
         assert_eq!(t.spans[1].style.color, Some(GOLD));
         assert_eq!(t.slice(1, 2).plain(), "y");
     }
+    #[test]
+    fn resolved_borrows_clean_text_and_restyles_codes() {
+        let clean = Text::colored("Steve", GOLD);
+        assert!(matches!(clean.resolved(), std::borrow::Cow::Borrowed(_)));
+        // A colour code inside a span clears its decorations (a bold
+        // "§cSteve" draws "Steve" red, not bold).
+        let styled = Style {
+            bold: Some(true),
+            ..Style::default()
+        };
+        let styled = Text::styled("§cSteve", styled);
+        let resolved = styled.resolved();
+        assert_eq!(resolved.plain(), "Steve");
+        assert_eq!(resolved.spans[0].style.color, Some(RED));
+        assert_eq!(resolved.spans[0].style.bold, Some(false));
+    }
 }
diff --git a/crates/horizon-client/src/ui.rs b/crates/horizon-client/src/ui.rs
index 1c6e93067..3cf7af9cb 100644
--- a/crates/horizon-client/src/ui.rs
+++ b/crates/horizon-client/src/ui.rs
@@ -279,9 +279,17 @@ pub fn centered_text(
     w: f32,
     color: u32,
 ) {
-    let width = atlas.font.width_text(text);
+    let text = text.resolved();
+    let width = atlas.font.width_text(&text);
     if width <= w {
-        batch.text_styled(atlas, text, x + ((w - width) / 2.0).floor(), y, color, true);
+        batch.text_styled(
+            atlas,
+            &text,
+            x + ((w - width) / 2.0).floor(),
+            y,
+            color,
+            true,
+        );
     } else {
         // Clip by characters (vanilla scrolls; we show the part that fits).
         let mut shown = Text::empty();

From c965aad8d3ad6a837149d6ae5a6e7100c168232d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:13:55 +0100
Subject: [PATCH 153/270] Shader packs, clean room 40: terrain in the shadow
 map, culled from the light

The shadow program now draws the world's terrain from the light's view.
The shadow pass culls its own section list against the shadow camera's
frustum (render distance, capped by shadowDistanceRenderMul), nearest
the light first, and draws only the faces toward the light. Its draws go
by arena page within 64-block bands from the light, as the camera's solid
draws do, so the flat path draws them in about ten calls per list instead
of one per page change (over a thousand with BSL). Its draws
follow the camera's translucent draws in the same instance and indirect
buffers, so the flat path gives them calls of their own. Sections never
sorted for the camera are sorted once so their translucent indices are
valid.

The frame's first shadow pass clears the shadow map and shadowcolor
buffers as it begins, instead of a separate pass that loads and stores
them all; the translucent shadow pass is timed under its own label.

Without a pack nothing changes: the shadow lists are empty and the
terrain stays one draw call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs              | 174 ++++++++++++++++--
 crates/horizon-client/src/gfx/flat.rs         |  70 ++++++-
 crates/horizon-client/src/gfx/pack_post.rs    | 161 +++++++++++++---
 crates/horizon-client/src/gfx/pack_shadow.rs  |  84 +++++++--
 .../horizon-client/src/gfx/pack_uniforms.rs   |  15 +-
 crates/horizon-shaders/src/post.rs            |  10 +-
 6 files changed, 447 insertions(+), 67 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index bba07c647..b21c846a5 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -471,6 +471,8 @@ pub struct Renderer {
     /// Per-frame scratch, kept to avoid allocating every frame.
     visible: Vec<resident::Visible>,
     visible_lods: Vec<lod::Visible>,
+    /// The sections a shader pack's shadow camera sees (`pack_post::ShadowView`).
+    shadow_visible: Vec<resident::Visible>,
     translucent_draws: Vec<(u64, usize, [u32; 5], (u32, Option<u32>))>,
     origins: Vec<[f32; 4]>,
     /// `DrawIndexedIndirectArgs` words: index count, instance count, first
@@ -485,6 +487,8 @@ pub struct Renderer {
     /// Each section's solid draws, to group them by arena page.
     solid_runs: page_runs::PageRuns,
     phase2_runs: page_runs::PageRuns,
+    /// The shadow camera's draws by page, in bands of distance from the light.
+    shadow_runs: page_runs::PageRuns,
     /// Block-entity blocks per meshed section (world position, state id).
     block_entities: HashMap<SectionKey, Vec<([i32; 3], u32)>>,
     /// Changes whenever `block_entities` does (unique across renderers).
@@ -2351,6 +2355,7 @@ impl Renderer {
             multi_draw,
             visible: Vec::new(),
             visible_lods: Vec::new(),
+            shadow_visible: Vec::new(),
             translucent_draws: Vec::new(),
             origins: Vec::new(),
             draws: Vec::new(),
@@ -2359,6 +2364,7 @@ impl Renderer {
             phase2_pages: Vec::new(),
             solid_runs: page_runs::PageRuns::default(),
             phase2_runs: page_runs::PageRuns::default(),
+            shadow_runs: page_runs::PageRuns::default(),
             block_entities: HashMap::new(),
             block_entity_revision: next_block_entity_revision(),
             occlusion: occlusion::Occlusion::new(crate::chunk::MIN_Y, crate::chunk::HEIGHT / 16),
@@ -3275,8 +3281,43 @@ impl Renderer {
             );
             visible_lods.sort_unstable_by_key(|v| (v.distance, v.key));
         }
+        // A shader pack's shadow pass draws the sections in its camera's box, all of them (the
+        // occlusion graph follows the eye, not the light), within shadowDistanceRenderMul.
+        let shadow_view = self
+            .pack_post
+            .as_ref()
+            .and_then(|p| p.1.as_ref())
+            .filter(|_| !frame.title)
+            .and_then(|p| p.shadow_view(frame));
+        let mut shadow_visible = std::mem::take(&mut self.shadow_visible);
+        shadow_visible.clear();
+        if let Some(v) = &shadow_view {
+            let radius = (frame.detail_distance / 16.0) as i32;
+            let radius = v
+                .distance
+                .map_or(radius, |d| radius.min((d / 16.0).ceil() as i32));
+            let light = Frustum {
+                planes: frustum(v.cull),
+            };
+            crate::spans::time("shadow visibility", || {
+                self.sections.visible(
+                    camera,
+                    radius,
+                    &light,
+                    |_| true,
+                    |_, _| false,
+                    &mut shadow_visible,
+                )
+            });
+            // Nearest the light first, so the depth test rejects what lies under it.
+            let light = v.light;
+            shadow_visible.sort_unstable_by(|a, b| {
+                let height = |s: &resident::Visible| glam::Vec3::from(s.origin).dot(light);
+                height(b).total_cmp(&height(a))
+            });
+        }
         self.drawn_sections = visible.len() + visible_lods.len();
-        let instances = self.drawn_sections;
+        let instances = self.drawn_sections + shadow_visible.len();
         if instances as u64 > self.instance_capacity {
             self.instance_capacity = (instances as u64).next_power_of_two();
             self.instances = self.device.create_buffer(&wgpu::BufferDescriptor {
@@ -3293,7 +3334,8 @@ impl Renderer {
             visible
                 .iter()
                 .map(|v| section_instance(v.origin))
-                .chain(visible_lods.iter().map(|v| lod::instance(v.origin))),
+                .chain(visible_lods.iter().map(|v| lod::instance(v.origin)))
+                .chain(shadow_visible.iter().map(|v| section_instance(v.origin))),
         );
         if !self.origins.is_empty() {
             self.uploads.buffer(
@@ -3497,9 +3539,87 @@ impl Renderer {
         self.translucency_cursor += budget;
         let translucent_draws = self.draws.len() as u32 - solid_draws;
         self.section_draws = self.draws.len();
+        // The shadow camera's sections after the camera's: quads that can face the light, then
+        // translucent ones (in their last sorted order; depth decides there).
+        let shadow_first = self.draws.len() as u32;
+        let mut shadow_translucent = Vec::new();
+        self.shadow_runs.clear();
+        if let Some(view) = &shadow_view {
+            let base = self.drawn_sections;
+            let toward = view.light * 1.0e5;
+            // How far below the nearest section to the light (squared, as bits, as `PageRuns`
+            // takes distances): each band's draws go by page, a call per page and band.
+            let height = |v: &resident::Visible| glam::Vec3::from(v.origin).dot(view.light);
+            let top = shadow_visible.first().map_or(0.0, height);
+            for (k, v) in shadow_visible.iter().enumerate() {
+                let s = self.sections.get_mut(v.slot);
+                let instance = (base + k) as u32;
+                let depth = f64::from(top - height(v)).max(0.0);
+                let distance = (depth * depth).to_bits();
+                // A section the camera never saw has no sorted indices yet: sorted once now.
+                if let Some((index_page, index_start)) = s.sorted_indices
+                    && !s.sort.is_sorted()
+                {
+                    let origin = [
+                        v.key.0 * 16,
+                        crate::chunk::MIN_Y + v.key.1 * 16,
+                        v.key.2 * 16,
+                    ];
+                    if let Some(indices) =
+                        s.sort
+                            .update(camera.to_array(), origin, &mut self.translucent_sorter)
+                    {
+                        self.uploads.buffer(
+                            &mut encoder,
+                            self.sorted_indices.buffer(index_page),
+                            index_start * 4,
+                            bytemuck::cast_slice(indices),
+                        );
+                    }
+                }
+                let before = self.draws.len();
+                facing_runs(&s.sides, Some(toward), v.origin, |first, quads| {
+                    let start = s.start as u32 + first * 4;
+                    self.draws.push([quads * 6, 1, 0, start, instance]);
+                    self.draw_pages.push((s.page, None));
+                });
+                let len = self.draws.len() - before;
+                self.shadow_runs.push(distance, s.page, before, len, [0; 3]);
+                if let Some((index_page, index_start)) = s.sorted_indices {
+                    let start = s.start + u64::from(s.solid) * 4;
+                    shadow_translucent.push((
+                        distance,
+                        [
+                            s.translucent * 6,
+                            1,
+                            index_start as u32,
+                            start as u32,
+                            instance,
+                        ],
+                        (s.page, Some(index_page)),
+                    ));
+                }
+            }
+        }
+        let shadow_solid = self.draws.len() as u32 - shadow_first;
+        self.shadow_runs
+            .regroup(&mut self.draws, &mut self.draw_pages, shadow_first as usize);
+        self.shadow_runs.clear();
+        for (distance, draw, pages) in shadow_translucent {
+            self.shadow_runs
+                .push(distance, pages.0, self.draws.len(), 1, [0; 3]);
+            self.draws.push(draw);
+            self.draw_pages.push(pages);
+        }
+        self.shadow_runs.regroup(
+            &mut self.draws,
+            &mut self.draw_pages,
+            (shadow_first + shadow_solid) as usize,
+        );
+        let shadow_translucent = self.draws.len() as u32 - shadow_first - shadow_solid;
         // Metal replays a multi-draw as one draw call per entry.
         self.section_draw_calls = if self.multi_draw && self.info.backend != wgpu::Backend::Metal {
-            (0..self.draws.len())
+            (0..self.section_draws)
                 .filter(|&i| {
                     i == 0
                         || i == phase1_draws as usize
@@ -3508,7 +3628,7 @@ impl Renderer {
                 })
                 .count()
         } else {
-            self.draws.len()
+            self.section_draws
         };
         let debug_depth = frame.debug_lines.len() as u32;
         let debug_top = frame.debug_lines_on_top.len() as u32;
@@ -3743,7 +3863,9 @@ impl Renderer {
             Some(flat)
                 if self.flat_on
                     && !self.draws.is_empty()
-                    && (self.drawn_sections >= flat.min_sections || pack_terrain) =>
+                    && (self.drawn_sections >= flat.min_sections
+                        || pack_terrain
+                        || shadow_view.is_some()) =>
             {
                 let sections = &self.sections;
                 let lods = &self.lods;
@@ -3758,9 +3880,11 @@ impl Renderer {
                         &self.draw_pages,
                         phase1_draws as usize,
                         solid_draws as usize,
+                        [shadow_first, shadow_first + shadow_solid].map(|d| d as usize),
                         phase2,
                         visible
                             .iter()
+                            .chain(&shadow_visible)
                             .filter_map(|v| {
                                 let id = sections.get(v.slot).flat_id?;
                                 Some((id, section_instance(v.origin)))
@@ -3776,7 +3900,7 @@ impl Renderer {
             _ => false,
         };
         if flat_frame {
-            self.section_draw_calls = self.flat.as_ref().map_or(0, |f| f.calls.len());
+            self.section_draw_calls = self.flat.as_ref().map_or(0, |f| f.shadow_calls[0]);
         } else if self.multi_draw && !self.draws.is_empty() {
             if self.draws.len() as u64 > self.indirect_capacity {
                 self.indirect_capacity = (self.draws.len() as u64).next_power_of_two();
@@ -3805,6 +3929,8 @@ impl Renderer {
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
         // The pack's program reads the vertices this frame's draws bind.
         let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
+        // The shadow camera's lists, drawn by the pack's shadow programs.
+        let pack_draws_shadow = shadow_view.is_some() && flat_frame == self.pack_terrain_flat;
         let pack_draws_sky = pack_post
             && self
                 .pack_post
@@ -4074,7 +4200,7 @@ impl Renderer {
                 _ if pack_draws_water => {}
                 Some(flat) => {
                     pass.set_pipeline(&flat.translucent);
-                    flat.draw(&mut pass, &flat.calls[flat.solid_calls..], |p| {
+                    flat.draw(&mut pass, flat.translucent_calls(), |p| {
                         self.arena.buffer(p)
                     });
                     pass.set_bind_group(0, &self.group, &[]);
@@ -4165,7 +4291,7 @@ impl Renderer {
             post.set_weather(weather);
             let flat = self.flat.as_ref().filter(|_| flat_frame);
             let pages: Vec<(u32, wgpu::Buffer)> = match flat {
-                Some(_) if pack_draws_terrain => self
+                Some(_) if pack_draws_terrain || pack_draws_shadow => self
                     .arena
                     .page_buffers()
                     .map(|(p, b)| (p, b.clone()))
@@ -4174,27 +4300,38 @@ impl Renderer {
             };
             let mut terrain =
                 |rp: &mut wgpu::RenderPass<'_>,
-                 translucent: bool,
+                 list: pack_post::TerrainList,
                  page: &dyn Fn(&mut wgpu::RenderPass<'_>, u32)| {
-                    if !pack_draws_terrain {
+                    use pack_post::TerrainList as L;
+                    let shadow = matches!(list, L::ShadowSolid | L::ShadowTranslucent);
+                    if !(if shadow {
+                        pack_draws_shadow
+                    } else {
+                        pack_draws_terrain
+                    }) {
                         return;
                     }
                     match flat {
                         Some(flat) => {
-                            let calls = if translucent {
-                                &flat.calls[flat.solid_calls..]
-                            } else {
-                                &flat.calls[..flat.solid_calls]
+                            let [shadow, shadow_translucent] = flat.shadow_calls;
+                            let calls = match list {
+                                L::Solid => &flat.calls[..flat.solid_calls],
+                                L::Translucent => flat.translucent_calls(),
+                                L::ShadowSolid => &flat.calls[shadow..shadow_translucent],
+                                L::ShadowTranslucent => &flat.calls[shadow_translucent..],
                             };
                             flat.draw_with(rp, calls, |p| self.arena.buffer(p), page);
                         }
                         None => {
                             rp.set_index_buffer(self.indices.slice(..), wgpu::IndexFormat::Uint32);
                             rp.set_vertex_buffer(1, self.instances.slice(..));
-                            let (first, count) = if translucent {
-                                (solid_draws, translucent_draws)
-                            } else {
-                                (0, solid_draws)
+                            let (first, count) = match list {
+                                L::Solid => (0, solid_draws),
+                                L::Translucent => (solid_draws, translucent_draws),
+                                L::ShadowSolid => (shadow_first, shadow_solid),
+                                L::ShadowTranslucent => {
+                                    (shadow_first + shadow_solid, shadow_translucent)
+                                }
                             };
                             self.draw_sections(rp, &self.indirect, 0, first, count);
                         }
@@ -4429,6 +4566,7 @@ impl Renderer {
         let _ = self.started;
         self.visible = visible;
         self.visible_lods = visible_lods;
+        self.shadow_visible = shadow_visible;
         Ok(true)
     }
 }
diff --git a/crates/horizon-client/src/gfx/flat.rs b/crates/horizon-client/src/gfx/flat.rs
index 6b71a16f7..5d86888da 100644
--- a/crates/horizon-client/src/gfx/flat.rs
+++ b/crates/horizon-client/src/gfx/flat.rs
@@ -40,6 +40,8 @@ enum Source {
 struct Plan {
     phase1_calls: usize,
     solid_calls: usize,
+    /// Where the shadow camera's solid and translucent calls begin.
+    shadow_calls: [usize; 2],
     total: u64,
 }
 const QUADS: u32 = u32::MAX;
@@ -97,6 +99,10 @@ pub struct Flat {
     pub calls: Vec<Call>,
     pub phase1_calls: usize,
     pub solid_calls: usize,
+    /// Where a shader pack's shadow camera's solid and translucent calls
+    /// begin (`calls.len()` without them): the camera's translucent calls
+    /// end at the first.
+    pub shadow_calls: [usize; 2],
     /// Frames with fewer sections in view keep the per-section draws.
     pub min_sections: usize,
     range_align: u64,
@@ -164,12 +170,16 @@ fn buffer(
 /// draw calls, one per run of draws in the same vertex page, phase 1's solid
 /// ones, phase 2's (draws `phase1_draws..solid_draws`) and translucent ones
 /// apart. A phase 2 range names its draw in phase 2 and its call in phase 2
-/// instead of a destination: the call's room holds all of its draws.
+/// instead of a destination: the call's room holds all of its draws. Draws
+/// from `shadow[0]` (solid) and `shadow[1]` (translucent) on are a shader
+/// pack's shadow camera's, with calls of their own.
+#[allow(clippy::too_many_arguments)]
 fn plan(
     draws: &[[u32; 5]],
     pages: &[(u32, Option<u32>)],
     phase1_draws: usize,
     solid_draws: usize,
+    shadow: [usize; 2],
     align: u64,
     calls: &mut Vec<Call>,
     ranges: &mut Vec<Range>,
@@ -179,6 +189,7 @@ fn plan(
     ranges.clear();
     segments.clear();
     let (mut phase1_calls, mut solid_calls) = (None, None);
+    let mut shadow_calls = [None; 2];
     let mut total = 0u64;
     let mut by_source: Vec<(Source, Vec<Range>)> = Vec::new();
     for (i, (d, &(page, sorted))) in draws.iter().zip(pages).enumerate() {
@@ -188,10 +199,14 @@ fn plan(
         if i == solid_draws {
             solid_calls = Some(calls.len());
         }
-        match calls.last_mut() {
-            Some(last) if last.page == page && i != phase1_draws && i != solid_draws => {
-                last.count += d[0]
+        for (k, &from) in shadow.iter().enumerate() {
+            if i == from {
+                shadow_calls[k].get_or_insert(calls.len());
             }
+        }
+        let starts = i == phase1_draws || i == solid_draws || shadow.contains(&i);
+        match calls.last_mut() {
+            Some(last) if last.page == page && !starts => last.count += d[0],
             _ => calls.push(Call {
                 page,
                 first: total as u32,
@@ -227,6 +242,7 @@ fn plan(
     Plan {
         phase1_calls: phase1_calls.unwrap_or(calls.len()).min(solid_calls),
         solid_calls,
+        shadow_calls: shadow_calls.map(|c| c.unwrap_or(calls.len())),
         total,
     }
 }
@@ -340,6 +356,7 @@ impl Flat {
             calls: Vec::new(),
             phase1_calls: 0,
             solid_calls: 0,
+            shadow_calls: [0; 2],
             min_sections: if std::env::var("HORIZON_FLAT_DRAWS").as_deref() == Ok("1") {
                 0
             } else {
@@ -412,6 +429,7 @@ impl Flat {
     ///
     /// When culling, the solid draws from `phase1_draws` are phase 2's, which
     /// `phase2` holds as the test leaves them: `flatten_phase2` copies them.
+    /// Draws from `shadow` on are a shader pack's shadow camera's (`plan`).
     #[allow(clippy::too_many_arguments)]
     pub fn prepare(
         &mut self,
@@ -422,6 +440,7 @@ impl Flat {
         pages: &[(u32, Option<u32>)],
         phase1_draws: usize,
         solid_draws: usize,
+        shadow: [usize; 2],
         phase2: Option<&wgpu::Buffer>,
         origins: impl Iterator<Item = (u32, [f32; 4])>,
         sorted_page: impl Fn(u32) -> wgpu::Buffer,
@@ -464,12 +483,14 @@ impl Flat {
         let Plan {
             phase1_calls,
             solid_calls,
+            shadow_calls,
             total,
         } = plan(
             draws,
             pages,
             phase1_draws,
             solid_draws,
+            shadow,
             self.range_align,
             &mut self.calls,
             &mut self.range_data,
@@ -477,10 +498,12 @@ impl Flat {
         );
         self.phase1_calls = phase1_calls;
         self.solid_calls = solid_calls;
+        self.shadow_calls = shadow_calls;
         if total == 0 || total * 4 > device.limits().max_storage_buffer_binding_size {
             self.calls.clear();
             self.phase1_calls = 0;
             self.solid_calls = 0;
+            self.shadow_calls = [0; 2];
             return false;
         }
         if self.range_data.len() as u64 > self.range_capacity {
@@ -644,6 +667,11 @@ impl Flat {
         pass.dispatch_workgroups((*count).min(GROUP_LIMIT), count.div_ceil(GROUP_LIMIT), 1);
     }
 
+    /// The camera's translucent calls.
+    pub fn translucent_calls(&self) -> &[Call] {
+        &self.calls[self.solid_calls..self.shadow_calls[0]]
+    }
+
     /// Draws `calls` with a flat pipeline set and `vertices` giving each
     /// page's vertex buffer.
     pub fn draw<'a>(
@@ -735,11 +763,13 @@ mod tests {
             phase1_calls,
             solid_calls,
             total,
+            ..
         } = plan(
             &draws,
             &pages,
             solid,
             solid,
+            [draws.len(); 2],
             4,
             &mut calls,
             &mut ranges,
@@ -774,6 +804,35 @@ mod tests {
         assert_eq!(ranges.len(), 12);
     }
 
+    /// A shader pack's shadow draws follow the camera's, in calls of their
+    /// own even from the same page: solid ones, then translucent ones.
+    #[test]
+    fn plan_gives_the_shadow_lists_calls_of_their_own() {
+        let (mut draws, mut pages, solid) = sample();
+        let camera = draws.len();
+        draws.extend([[6, 1, 0, 40, 6], [6 * 2, 1, 0, 64, 7], [6, 1, 6, 80, 7]]);
+        pages.extend([(0, None), (0, None), (0, Some(0))]);
+        let (mut calls, mut ranges, mut segments) = (Vec::new(), Vec::new(), Vec::new());
+        let plan = plan(
+            &draws,
+            &pages,
+            solid,
+            solid,
+            [camera, camera + 2],
+            4,
+            &mut calls,
+            &mut ranges,
+            &mut segments,
+        );
+        assert_eq!((plan.solid_calls, plan.shadow_calls), (3, [4, 5]));
+        let call = |page, first, count| Call { page, first, count };
+        assert_eq!(
+            &calls[3..],
+            [call(0, 60, 18), call(0, 78, 18), call(0, 96, 6)]
+        );
+        assert_eq!(plan.total, 6 * 17);
+    }
+
     /// Phase 2's draws (here the third and fourth) get calls of their own,
     /// each with room for all of its draws, and ranges naming their draw
     /// and call in phase 2.
@@ -786,6 +845,7 @@ mod tests {
             &pages,
             2,
             solid,
+            [draws.len(); 2],
             4,
             &mut calls,
             &mut ranges,
@@ -796,6 +856,7 @@ mod tests {
             Plan {
                 phase1_calls: 1,
                 solid_calls: 3,
+                shadow_calls: [4, 4],
                 total: 6 * 13
             }
         );
@@ -899,6 +960,7 @@ mod tests {
                 &pages,
                 phase1,
                 solid,
+                [draws.len(); 2],
                 align,
                 &mut calls,
                 &mut ranges,
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index fdc4563ef..57ce0b147 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -270,6 +270,9 @@ pub struct PackPost {
     depth1: bool,
     /// The shadow buffers, when the shadow pass runs (2.5), and the `shadowcomp` programs.
     shadow_targets: Option<super::pack_shadow::ShadowTargets>,
+    /// What draws terrain from the light (`shadow`), and translucent terrain (`shadow_water`).
+    shadow_terrain: Option<Pass>,
+    shadow_water: Option<Pass>,
     shadow_comp: Vec<Pass>,
     /// Buffers with mipmaps (filterable ones a program asks them for).
     mipped: u16,
@@ -598,10 +601,35 @@ fn attach(
     })
 }
 
-/// Draws the game's terrain (`true`: translucent) into a pass; calls its third argument with
-/// each arena page before drawing from it.
+/// Which of the frame's terrain draws: the camera's solid or translucent ones, or the shadow
+/// camera's.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum TerrainList {
+    Solid,
+    Translucent,
+    ShadowSolid,
+    ShadowTranslucent,
+}
+
+impl TerrainList {
+    fn translucent(self) -> bool {
+        matches!(self, Self::Translucent | Self::ShadowTranslucent)
+    }
+}
+
+/// Draws the game's terrain of one list into a pass; calls its third argument with each arena
+/// page before drawing from it.
 pub(super) type TerrainDraw<'a> =
-    dyn FnMut(&mut wgpu::RenderPass<'_>, bool, &dyn Fn(&mut wgpu::RenderPass<'_>, u32)) + 'a;
+    dyn FnMut(&mut wgpu::RenderPass<'_>, TerrainList, &dyn Fn(&mut wgpu::RenderPass<'_>, u32)) + 'a;
+
+/// What the shadow camera sees of the terrain, for the game's draw lists: its view and
+/// projection in wgpu's clip space, the direction toward the light, and how far from the camera
+/// terrain is drawn (`shadowDistanceRenderMul`).
+pub(super) struct ShadowView {
+    pub cull: glam::Mat4,
+    pub light: glam::Vec3,
+    pub distance: Option<f32>,
+}
 
 /// Set 3 of flat terrain, read by the vertex stage: `mc_Entity`'s table (-1 pairs when empty)
 /// and, per arena page, the page's vertices (a vertex reads its quad's corners for its normal).
@@ -1007,6 +1035,14 @@ impl PackPost {
             .water
             .zip(terrain_geometry.as_ref())
             .and_then(|(p, g)| build(p, Some(g)));
+        let shadow_terrain = post
+            .shadow
+            .zip(terrain_geometry.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)));
+        let shadow_water = post
+            .shadow_water
+            .zip(terrain_geometry.as_ref())
+            .and_then(|(p, g)| build(p, Some(g)));
         let sky = (post.sky.is_some() || post.sky_textured.is_some()).then(|| {
             let geometry = PackSky::new(device);
             let basic = Geometry {
@@ -1124,9 +1160,22 @@ impl PackPost {
         if let Some(t) = &terrain {
             notes.push(format!("terrain draws with {}", t.name));
         }
+        for (part, pass) in [
+            ("terrain", &shadow_terrain),
+            ("translucent terrain", &shadow_water),
+        ] {
+            if let Some(p) = pass {
+                notes.push(format!("{part} casts shadows with {}", p.name));
+            }
+        }
         if let Some(w) = &water {
             notes.push(format!("translucent terrain draws with {}", w.name));
         }
+        // Timed (and labelled) apart from the solid shadow pass that runs the same program.
+        let mut shadow_water = shadow_water;
+        if let Some(p) = &mut shadow_water {
+            p.name.push_str(" (translucent)");
+        }
         for (part, pass) in sky
             .iter()
             .flat_map(|s| [("sky", &s.basic), ("sun and moon", &s.textured)])
@@ -1168,6 +1217,7 @@ impl PackPost {
                 .chain(&shadow_comp)
                 .chain(&terrain)
                 .chain(&water))
+            .chain(shadow_terrain.iter().chain(&shadow_water))
             .chain(sky.iter().flat_map(|s| s.basic.iter().chain(&s.textured)))
             .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
             .chain(&clouds)
@@ -1189,9 +1239,11 @@ impl PackPost {
             let t =
                 super::pack_shadow::ShadowTargets::new(device, &shadow_config, f, colors, depth1);
             notes.push(format!(
-                "shadow map {0}x{0}, shadowcolor buffers {colors:#b}{1}",
+                "shadow map {0}x{0} over {2} blocks, sunPathRotation {3}, shadowcolor buffers {colors:#b}{1}",
                 t.size,
-                if depth1 { ", shadowtex1" } else { "" }
+                if depth1 { ", shadowtex1" } else { "" },
+                shadow_config.distance,
+                shadow_config.sun_path_rotation,
             ));
             t
         });
@@ -1334,6 +1386,8 @@ impl PackPost {
             hand,
             depth1,
             shadow_targets,
+            shadow_terrain,
+            shadow_water,
             shadow_comp,
             mipped,
             mips_valid: 0,
@@ -1545,7 +1599,12 @@ impl PackPost {
             load: wgpu::LoadOp::Load,
             store: wgpu::StoreOp::Store,
         };
-        // The shadow pass draws into the shadow buffers and the shadow map.
+        // The shadow pass draws into the shadow buffers and the shadow map, the frame's first
+        // one clearing them.
+        let (depth_ops, shadow_ops) = match &mut self.shadow_targets {
+            Some(s) if pass.group.shadow() => s.clear_ops(pass.writes.iter().map(|w| w.1)),
+            _ => (super::pack_shadow::load(), [load; 2]),
+        };
         let shadow = self.shadow_targets.as_ref().filter(|_| pass.group.shadow());
         let mut attachments: Vec<Option<wgpu::RenderPassColorAttachment>> = Vec::new();
         for &(location, buffer) in &pass.writes {
@@ -1554,7 +1613,9 @@ impl PackPost {
                 attachments.resize(l + 1, None);
             }
             attachments[l] = match shadow {
-                Some(s) => s.color(buffer, false).and_then(|v| attach(v, load)),
+                Some(s) => s
+                    .color(buffer, false)
+                    .and_then(|v| attach(v, shadow_ops.get(buffer).copied().unwrap_or(load))),
                 None => targets.color[buffer]
                     .as_ref()
                     .and_then(|t| attach(&t[usize::from(self.main & 1 << buffer != 0)], load)),
@@ -1567,10 +1628,7 @@ impl PackPost {
             timestamp_writes,
             depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                 view: shadow.map_or(&targets.depth, |s| &s.depth.1),
-                depth_ops: Some(wgpu::Operations {
-                    load: wgpu::LoadOp::Load,
-                    store: wgpu::StoreOp::Store,
-                }),
+                depth_ops: Some(depth_ops),
                 stencil_ops: None,
             }),
             ..Default::default()
@@ -1585,18 +1643,20 @@ impl PackPost {
         queue: &wgpu::Queue,
         encoder: &mut wgpu::CommandEncoder,
         size: [u32; 2],
-        translucent: bool,
+        list: TerrainList,
         draw: &mut TerrainDraw<'_>,
     ) {
-        let slot = if translucent {
-            &mut self.water
-        } else {
-            &mut self.terrain
+        let slot = match list {
+            TerrainList::Solid => &mut self.terrain,
+            TerrainList::Translucent => &mut self.water,
+            TerrainList::ShadowSolid => &mut self.shadow_terrain,
+            TerrainList::ShadowTranslucent => &mut self.shadow_water,
         };
         let Some(mut pass) = slot.take() else {
             return;
         };
-        if translucent
+        let translucent = list.translucent();
+        if list == TerrainList::Translucent
             && let Some(t) = &self.targets
             && let Some((copy, _)) = &t.depth1
         {
@@ -1625,14 +1685,17 @@ impl PackPost {
                     rp.set_bind_group(3, group, &[]);
                 }
             };
-            draw(&mut rp, translucent, &page);
+            draw(&mut rp, list, &page);
         }
-        self.mips_valid &= !pass.written;
-        if translucent {
-            self.water = Some(pass);
-        } else {
-            self.terrain = Some(pass);
+        if !pass.group.shadow() {
+            self.mips_valid &= !pass.written;
         }
+        *match list {
+            TerrainList::Solid => &mut self.terrain,
+            TerrainList::Translucent => &mut self.water,
+            TerrainList::ShadowSolid => &mut self.shadow_terrain,
+            TerrainList::ShadowTranslucent => &mut self.shadow_water,
+        } = Some(pass);
     }
 
     /// The sky's parts in vanilla's order, each with the program that draws it; one render pass
@@ -1782,7 +1845,7 @@ impl PackPost {
         if super::sky_visible(frame) {
             self.draw_sky(device, queue, encoder, size, frame);
         }
-        self.draw_terrain(device, queue, encoder, size, false, terrain);
+        self.draw_terrain(device, queue, encoder, size, TerrainList::Solid, terrain);
         self.draw_entities(device, queue, encoder, size, false);
         self.draw_clouds(device, queue, encoder, size);
         self.draw_hand(device, queue, encoder, size, frame);
@@ -1878,7 +1941,14 @@ impl PackPost {
         size: [u32; 2],
         terrain: &mut TerrainDraw<'_>,
     ) {
-        self.draw_terrain(device, queue, encoder, size, true, terrain);
+        self.draw_terrain(
+            device,
+            queue,
+            encoder,
+            size,
+            TerrainList::Translucent,
+            terrain,
+        );
         self.draw_entities(device, queue, encoder, size, true);
         self.draw_weather(device, queue, encoder, size);
     }
@@ -1960,6 +2030,20 @@ impl PackPost {
     }
 
     /// Whether the pack draws terrain itself.
+    /// What the shadow camera draws of the terrain this frame, when the pack draws it.
+    pub fn shadow_view(&self, frame: &super::Frame) -> Option<ShadowView> {
+        self.shadow_targets.as_ref()?;
+        if self.shadow_terrain.is_none() && self.shadow_water.is_none() {
+            return None;
+        }
+        let shadow = &self.uniforms.shadow;
+        Some(ShadowView {
+            cull: pack_uniforms::shadow_culling(frame, shadow),
+            light: pack_uniforms::shadow_light(frame, shadow),
+            distance: (shadow.render_mul > 0.0).then_some(shadow.distance * shadow.render_mul),
+        })
+    }
+
     pub fn has_terrain(&self) -> bool {
         self.terrain.is_some()
     }
@@ -2088,13 +2172,32 @@ impl PackPost {
         device: &wgpu::Device,
         queue: &wgpu::Queue,
         encoder: &mut wgpu::CommandEncoder,
+        terrain: &mut TerrainDraw<'_>,
     ) {
-        let Some(t) = &self.shadow_targets else {
+        let Some(t) = &mut self.shadow_targets else {
             return;
         };
-        t.clear(encoder);
-        t.copy_depth1(encoder);
+        t.begin_frame();
         let size = [t.size; 2];
+        self.draw_terrain(
+            device,
+            queue,
+            encoder,
+            size,
+            TerrainList::ShadowSolid,
+            terrain,
+        );
+        let t = self.shadow_targets.as_mut().expect("shadow pass");
+        t.clear_rest(encoder);
+        t.copy_depth1(encoder);
+        self.draw_terrain(
+            device,
+            queue,
+            encoder,
+            size,
+            TerrainList::ShadowTranslucent,
+            terrain,
+        );
         let mut comp = std::mem::take(&mut self.shadow_comp);
         for pass in &mut comp {
             let group = self.bind(device, queue, pass, size);
@@ -2181,7 +2284,7 @@ impl PackPost {
         if self.targets.is_none() {
             return;
         }
-        self.run_shadow(device, queue, encoder);
+        self.run_shadow(device, queue, encoder, terrain);
         let Some(targets) = &self.targets else { return };
         let main = |m: u16, i: usize| usize::from(m & 1 << i != 0);
         let view = |m: u16, i: usize, alt: bool| {
diff --git a/crates/horizon-client/src/gfx/pack_shadow.rs b/crates/horizon-client/src/gfx/pack_shadow.rs
index 7688d1250..92f0aeda0 100644
--- a/crates/horizon-client/src/gfx/pack_shadow.rs
+++ b/crates/horizon-client/src/gfx/pack_shadow.rs
@@ -3,6 +3,29 @@
 //! with two sides that `shadowcomp` programs flip as composite programs flip colortex (6.1.6).
 //! Square, `shadowMapResolution` pixels.
 
+type Ops<T> = wgpu::Operations<T>;
+type Color = wgpu::Color;
+
+/// Loaded and stored.
+pub(super) fn load<T>() -> Ops<T> {
+    wgpu::Operations {
+        load: wgpu::LoadOp::Load,
+        store: wgpu::StoreOp::Store,
+    }
+}
+
+fn clear(c: [f32; 4]) -> Ops<Color> {
+    wgpu::Operations {
+        load: wgpu::LoadOp::Clear(wgpu::Color {
+            r: c[0].into(),
+            g: c[1].into(),
+            b: c[2].into(),
+            a: c[3].into(),
+        }),
+        store: wgpu::StoreOp::Store,
+    }
+}
+
 /// What the shadow pass writes and the programs read.
 pub(super) struct ShadowTargets {
     pub size: u32,
@@ -16,6 +39,11 @@ pub(super) struct ShadowTargets {
     pub clears: [Option<[f32; 4]>; 2],
     /// Bit n set: B is shadowcolor n's "main".
     pub main: u16,
+    /// Nothing cleared yet this frame: the first pass into the shadow buffers clears them as it
+    /// begins (`clear_ops`), which saves a pass that loads and stores them all on tiled GPUs.
+    fresh: bool,
+    /// Bit n set: shadowcolor n was cleared that way.
+    cleared: u8,
     /// Depth comparison for `sampler2DShadow` (hardware filtering): linear, as GL filters it.
     pub comparison: wgpu::Sampler,
 }
@@ -85,6 +113,8 @@ impl ShadowTargets {
                 b.clear.then(|| b.clear_color.unwrap_or([1.0; 4]))
             }),
             main: 0,
+            fresh: false,
+            cleared: 0,
             comparison: device.create_sampler(&wgpu::SamplerDescriptor {
                 label: Some("Shader pack shadow comparison"),
                 compare: Some(wgpu::CompareFunction::LessEqual),
@@ -101,31 +131,59 @@ impl ShadowTargets {
         self.color.get(n)?.as_ref().map(|c| &c[side])
     }
 
-    /// Clears the shadow map and the shadowcolor buffers cleared every frame (6.3).
-    pub fn clear(&self, encoder: &mut wgpu::CommandEncoder) {
+    /// A new frame: the shadow map and the shadowcolor buffers cleared every frame (6.3) are
+    /// cleared by the first pass that begins (`clear_ops`), or else by `clear_rest`.
+    pub fn begin_frame(&mut self) {
+        self.fresh = true;
+        self.cleared = 0;
+    }
+
+    /// The load operations of a pass into the shadow map and shadowcolor buffers `writes`:
+    /// clears in the frame's first one, loads after.
+    pub fn clear_ops(
+        &mut self,
+        writes: impl Iterator<Item = usize>,
+    ) -> (Ops<f32>, [Ops<Color>; 2]) {
+        if !std::mem::take(&mut self.fresh) {
+            return (load(), [load(); 2]);
+        }
+        let mut colors = [load(); 2];
+        for n in writes.filter(|&n| n < 2) {
+            if let Some(c) = self.clears[n] {
+                colors[n] = clear(c);
+                self.cleared |= 1 << n;
+            }
+        }
+        let depth = wgpu::Operations {
+            load: wgpu::LoadOp::Clear(1.0),
+            store: wgpu::StoreOp::Store,
+        };
+        (depth, colors)
+    }
+
+    /// Clears what no pass has cleared this frame: all of it when no shadow program drew, the
+    /// cleared shadowcolor buffers the first one did not write.
+    pub fn clear_rest(&mut self, encoder: &mut wgpu::CommandEncoder) {
+        let depth = std::mem::take(&mut self.fresh);
+        let cleared = std::mem::replace(&mut self.cleared, 0b11);
         let attachments: Vec<_> = (0..2)
+            .filter(|n| cleared & 1 << n == 0)
             .filter_map(|n| {
-                let c = self.clears[n]?;
                 Some(Some(wgpu::RenderPassColorAttachment {
                     view: self.color(n, false)?,
                     depth_slice: None,
                     resolve_target: None,
-                    ops: wgpu::Operations {
-                        load: wgpu::LoadOp::Clear(wgpu::Color {
-                            r: c[0].into(),
-                            g: c[1].into(),
-                            b: c[2].into(),
-                            a: c[3].into(),
-                        }),
-                        store: wgpu::StoreOp::Store,
-                    },
+                    ops: clear(self.clears[n]?),
                 }))
             })
             .collect();
+        if !depth && attachments.is_empty() {
+            return;
+        }
         encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
             label: Some("Shader pack shadow clear"),
             color_attachments: &attachments,
-            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
+            depth_stencil_attachment: depth.then_some(wgpu::RenderPassDepthStencilAttachment {
                 view: &self.depth.1,
                 depth_ops: Some(wgpu::Operations {
                     load: wgpu::LoadOp::Clear(1.0),
diff --git a/crates/horizon-client/src/gfx/pack_uniforms.rs b/crates/horizon-client/src/gfx/pack_uniforms.rs
index d1a85a1ba..c4df4377b 100644
--- a/crates/horizon-client/src/gfx/pack_uniforms.rs
+++ b/crates/horizon-client/src/gfx/pack_uniforms.rs
@@ -209,7 +209,7 @@ pub fn tilt_matrix(tilt: f32) -> Mat4 {
 }
 
 /// The world direction of the shadow light (7.1): the sun by day, the moon by night.
-fn shadow_light(frame: &Frame, shadow: &Shadow) -> Vec3 {
+pub fn shadow_light(frame: &Frame, shadow: &Shadow) -> Vec3 {
     let sun_angle = (frame.sky.sun_angle / 360.0 + 0.25).rem_euclid(1.0);
     let angle = if sun_angle < 0.5 {
         frame.sky.sun_angle
@@ -219,6 +219,19 @@ fn shadow_light(frame: &Frame, shadow: &Shadow) -> Vec3 {
     body(angle, shadow.sun_path_rotation).normalize()
 }
 
+/// `shadow_camera`'s view and projection in wgpu's clip space (depth 0..1), for culling.
+pub fn shadow_culling(frame: &Frame, shadow: &Shadow) -> Mat4 {
+    let (view, gl) = shadow_camera(shadow_light(frame, shadow), frame.camera, shadow);
+    // GL's depth -w..w to wgpu's 0..w.
+    let depth = Mat4::from_cols(
+        Vec4::X,
+        Vec4::Y,
+        Vec4::new(0.0, 0.0, 0.5, 0.0),
+        Vec4::new(0.0, 0.0, 0.5, 1.0),
+    );
+    depth * gl * view
+}
+
 /// Distance from the snapped point to the shadow camera, toward the light: the middle of the
 /// default near and far planes (OQ-6).
 const SHADOW_EYE: f64 = 128.0;
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 95b8c3663..dd062b508 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -531,8 +531,12 @@ fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
             })
         })
     };
-    let shadow = load(&["shadow"]);
-    let water = load(&["shadow_water", "shadow"]);
+    // `shadowTerrain` and `shadowTranslucent` (3.2) leave terrain out of the shadow pass.
+    let keep = |key: &str| properties.get(key).is_none_or(|v| v.trim() != "false");
+    let shadow = keep("shadowTerrain").then(|| load(&["shadow"])).flatten();
+    let water = keep("shadowTranslucent")
+        .then(|| load(&["shadow_water", "shadow"]))
+        .flatten();
     if shadow.is_none() {
         loader
             .post
@@ -868,6 +872,8 @@ mod tests {
         };
         assert!(!none("").shadow_pass);
         assert!(none("shadow.enabled=true").shadow.is_some());
+        let post = none("shadow.enabled=true\nshadowTranslucent=false");
+        assert!(post.shadow.is_some() && post.shadow_water.is_none());
     }
 
     /// Water falls back to the terrain chain and blends by default, as the sky does; entities

From 13508cbd9c6ee7122694dc3f1482a10683f408ca Mon Sep 17 00:00:00 2001
From: Jan Pres <janpres2011@gmail.com>
Date: Sun, 25 Oct 2026 17:41:07 +0000
Subject: [PATCH 154/270] Creative: Ctrl+Backspace deletes a word in the search

The creative inventory's search box is an append-only EditBox of 50
characters, but its editing was a plain String pop, so Ctrl+Backspace
removed one character instead of the word before the caret, unlike every
other text field and vanilla's EditBox.keyPressed.

Move EditBox.getWordPosition and deleteWords into one shared helper in
ui.rs (the UI and chat text fields had two copies of it), and route a
Ctrl+Backspace in the creative search through it. A Select All selection
is still what backspace deletes first, as in vanilla.

Fixes #1764.

Co-Authored-By: OpenCode (DeepSeek V4.1 Flash Free) <noreply@opencode.ai>
---
 crates/horizon-client/src/game.rs           |  5 +-
 crates/horizon-client/src/game/clipboard.rs | 22 ++++--
 crates/horizon-client/src/game/control.rs   |  2 +-
 crates/horizon-client/src/game/pad_menu.rs  |  6 +-
 crates/horizon-client/src/screen_draw.rs    | 21 +----
 crates/horizon-client/src/ui.rs             | 86 ++++++++++++++++-----
 6 files changed, 92 insertions(+), 50 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 7fcb3be89..6df6e531c 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -11272,9 +11272,10 @@ impl ApplicationHandler for Game<'_> {
                         // The hovered slot took the key (`ignoreTextInput`).
                     } else if let Some(shortcut) = self.edit_shortcut(&event) {
                         self.creative_search_shortcut(shortcut);
+                    } else if event.physical_key == PhysicalKey::Code(KeyCode::Backspace) {
+                        self.creative_search_backspace(self.has_control_down());
                     } else {
-                        let backspace = event.physical_key == PhysicalKey::Code(KeyCode::Backspace);
-                        self.creative_search_edit(event.text.as_deref(), backspace);
+                        self.creative_search_edit(event.text.as_deref());
                     }
                 }
                 WindowEvent::KeyboardInput { event, .. }
diff --git a/crates/horizon-client/src/game/clipboard.rs b/crates/horizon-client/src/game/clipboard.rs
index b9558ddfd..c87aa3681 100644
--- a/crates/horizon-client/src/game/clipboard.rs
+++ b/crates/horizon-client/src/game/clipboard.rs
@@ -97,15 +97,25 @@ impl Game<'_> {
             self.creative_screen.scroll = 0.0;
         }
     }
-    /// Typing or a backspace in the creative search box.
-    pub(super) fn creative_search_edit(&mut self, typed: Option<&str>, backspace: bool) {
+    /// A backspace in the creative search box: with Ctrl, the whole word
+    /// before the caret (`EditBox.deleteWords(-1)`), otherwise one character.
+    /// A Select All selection is what it deletes, as in `EditBox.keyPressed`.
+    pub(super) fn creative_search_backspace(&mut self, ctrl: bool) {
         let search = &mut self.creative_screen.search;
-        let cleared = self.text_selection.take(CREATIVE_SEARCH, search);
-        if backspace {
-            if !cleared {
+        if !self.text_selection.take(CREATIVE_SEARCH, search) {
+            if ctrl {
+                horizon_client::ui::delete_words(search, -1);
+            } else {
                 search.pop();
             }
-        } else if let Some(text) = typed {
+        }
+        self.creative_screen.scroll = 0.0;
+    }
+    /// Typing in the creative search box.
+    pub(super) fn creative_search_edit(&mut self, typed: Option<&str>) {
+        let search = &mut self.creative_screen.search;
+        self.text_selection.take(CREATIVE_SEARCH, search);
+        if let Some(text) = typed {
             clipboard::append_limited(search, text, CREATIVE_SEARCH_CHARS);
         }
         self.creative_screen.scroll = 0.0;
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index a0d8987d8..987937066 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -569,7 +569,7 @@ impl Game<'_> {
                     }
                     Screen::Creative if self.creative_screen.tab().search => {
                         // As typed: replaces a selected query, keeps the length limit.
-                        self.creative_search_edit(Some(text), false)
+                        self.creative_search_edit(Some(text))
                     }
                     _ => {
                         return Err(
diff --git a/crates/horizon-client/src/game/pad_menu.rs b/crates/horizon-client/src/game/pad_menu.rs
index 32acdd256..30f2e7337 100644
--- a/crates/horizon-client/src/game/pad_menu.rs
+++ b/crates/horizon-client/src/game/pad_menu.rs
@@ -921,8 +921,10 @@ impl Game<'_> {
         } else if self.book.is_some() {
             self.book_input(key, text);
         } else if self.screen == Screen::Creative && self.creative_screen.tab().search {
-            if key != Some(KeyCode::Enter) {
-                self.creative_search_edit(text, backspace);
+            if backspace {
+                self.creative_search_backspace(false);
+            } else if key != Some(KeyCode::Enter) {
+                self.creative_search_edit(text);
             }
         } else if self.recipe_search_focused() {
             if key != Some(KeyCode::Enter) {
diff --git a/crates/horizon-client/src/screen_draw.rs b/crates/horizon-client/src/screen_draw.rs
index 572ee202f..03f979a68 100644
--- a/crates/horizon-client/src/screen_draw.rs
+++ b/crates/horizon-client/src/screen_draw.rs
@@ -619,26 +619,7 @@ impl TextField {
     /// `getWordPosition(dir, from)`: past the next space run, or back to the
     /// start of the word.
     pub fn word_position(&self, dir: isize, from: usize) -> usize {
-        let v: Vec<char> = self.value.chars().collect();
-        let mut at = from;
-        if dir > 0 {
-            at = v
-                .iter()
-                .skip(at)
-                .position(|c| *c == ' ')
-                .map_or(v.len(), |p| p + at);
-            while at < v.len() && v[at] == ' ' {
-                at += 1;
-            }
-        } else {
-            while at > 0 && v[at - 1] == ' ' {
-                at -= 1;
-            }
-            while at > 0 && v[at - 1] != ' ' {
-                at -= 1;
-            }
-        }
-        at
+        crate::ui::word_position(&self.value, dir, from)
     }
     /// `keyPressed` of a focused, editable box: `Some(changed)` when handled.
     pub fn key(
diff --git a/crates/horizon-client/src/ui.rs b/crates/horizon-client/src/ui.rs
index 1c6e93067..5f8f7b9f9 100644
--- a/crates/horizon-client/src/ui.rs
+++ b/crates/horizon-client/src/ui.rs
@@ -821,6 +821,40 @@ fn byte_index(s: &str, chars: usize) -> usize {
 pub fn char_len(s: &str) -> usize {
     s.chars().count()
 }
+/// `EditBox.getWordPosition(dir, from)`: the character index `dir` words away
+/// from `from`. Forward, past the rest of the word and its spaces; backward,
+/// over any spaces to the start of the word.
+pub fn word_position(value: &str, dir: isize, from: usize) -> usize {
+    let chars: Vec<char> = value.chars().collect();
+    let mut pos = from.min(chars.len());
+    if dir < 0 {
+        while pos > 0 && chars[pos - 1] == ' ' {
+            pos -= 1;
+        }
+        while pos > 0 && chars[pos - 1] != ' ' {
+            pos -= 1;
+        }
+    } else {
+        while pos < chars.len() && chars[pos] != ' ' {
+            pos += 1;
+        }
+        while pos < chars.len() && chars[pos] == ' ' {
+            pos += 1;
+        }
+    }
+    pos
+}
+/// `EditBox.deleteWords(dir)` for an append-only field, whose caret is at the
+/// end: removes the word in that direction. True when the value changed.
+pub fn delete_words(value: &mut String, dir: isize) -> bool {
+    let len = char_len(value);
+    let to = word_position(value, dir, len);
+    if to == len {
+        return false;
+    }
+    value.truncate(byte_index(value, to));
+    true
+}
 impl crate::clipboard::Editable for EditBox {
     fn select_all(&mut self) {
         self.move_cursor_to_end(false);
@@ -919,25 +953,7 @@ impl EditBox {
     }
     /// EditBox.getWordPosition(dir, from).
     fn word_position_from(&self, dir: isize, from: usize) -> usize {
-        let chars: Vec<char> = self.value.chars().collect();
-        let mut pos = from.min(chars.len());
-        if dir < 0 {
-            while pos > 0 && chars[pos - 1] == ' ' {
-                pos -= 1;
-            }
-            while pos > 0 && chars[pos - 1] != ' ' {
-                pos -= 1;
-            }
-        } else {
-            let len = chars.len();
-            while pos < len && chars[pos] != ' ' {
-                pos += 1;
-            }
-            while pos < len && chars[pos] == ' ' {
-                pos += 1;
-            }
-        }
-        pos
+        word_position(&self.value, dir, from)
     }
     pub fn set_cursor(&mut self, pos: usize, select: bool) {
         self.cursor = pos.min(char_len(&self.value));
@@ -1451,4 +1467,36 @@ mod tests {
         assert_eq!(e.value, "éx worl");
         assert_eq!(e.cursor, 2);
     }
+    #[test]
+    fn word_position_steps_over_a_word_and_its_spaces() {
+        assert_eq!(word_position("hello world", -1, 11), 6);
+        assert_eq!(word_position("hello world", -1, 6), 0);
+        assert_eq!(word_position("hello   world", -1, 13), 8);
+        assert_eq!(word_position("hello   world", 1, 5), 8);
+        // From inside a word: back to its start, forward past it and its spaces.
+        assert_eq!(word_position("hello world", -1, 8), 6);
+        assert_eq!(word_position("hello world", 1, 2), 6);
+        // The ends, and a position past the end.
+        assert_eq!(word_position("hello", -1, 0), 0);
+        assert_eq!(word_position("hello", 1, 5), 5);
+        assert_eq!(word_position("hi", -1, 99), 0);
+        assert_eq!(word_position("hi", 1, 99), 2);
+    }
+    #[test]
+    fn delete_words_removes_the_word_before_the_end() {
+        let mut v = "stone bricks".to_string();
+        assert!(delete_words(&mut v, -1));
+        assert_eq!(v, "stone ");
+        assert!(delete_words(&mut v, -1));
+        assert_eq!(v, "");
+        assert!(!delete_words(&mut v, -1));
+        // Characters, not bytes.
+        let mut v = "a é§x".to_string();
+        assert!(delete_words(&mut v, -1));
+        assert_eq!(v, "a ");
+        // Nothing after the end to delete.
+        let mut v = "stone".to_string();
+        assert!(!delete_words(&mut v, 1));
+        assert_eq!(v, "stone");
+    }
 }

From aa2f60b7bd78179f1e7723c866212fd4e1ec548e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:43:03 +0100
Subject: [PATCH 155/270] Copper golem statues turn to their next pose when
 right-clicked

CopperGolemStatueBlock.useItemOn: anything but an axe, an empty hand too,
cycles copper_golem_pose with its sound and block_change game event; honeycomb
on a weathering statue passes on to waxing. Axe scraping, unwaxing and
stripping and honeycomb waxing now count the item as used, and waxing sends
its block_change game event, as vanilla's useOn does. The use_item_on harness
gains statue cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs          | 10 ++++++
 crates/horizon-world/src/level/interact.rs | 31 ++++++++++++++++++
 tools/test_use_item_on_parity.py           | 37 ++++++++++++++++++++--
 3 files changed, 76 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 7fcb3be89..ee6df4c38 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -8332,6 +8332,8 @@ impl Game<'_> {
             1.0,
             1.0,
         );
+        // ItemStack.useOn: a use that acted counts as one of the item.
+        self.stats.add("used", &stack.item, 1);
         self.damage_held(damage);
         self.post_block_game_event("minecraft:block_change", pos, self.sculk_actor(), Some(new));
         Ok(true)
@@ -8536,6 +8538,14 @@ impl Game<'_> {
                     1.0,
                     1.0,
                 );
+                // HoneycombItem.useOn's game event, and ItemStack.useOn's used statistic.
+                self.post_block_game_event(
+                    "minecraft:block_change",
+                    hit.pos,
+                    self.sculk_actor(),
+                    Some(state),
+                );
+                self.stats.add("used", &stack.item, 1);
                 if !self.creative {
                     self.consume_held();
                 }
diff --git a/crates/horizon-world/src/level/interact.rs b/crates/horizon-world/src/level/interact.rs
index b8251ba46..7b2195c34 100644
--- a/crates/horizon-world/src/level/interact.rs
+++ b/crates/horizon-world/src/level/interact.rs
@@ -592,6 +592,37 @@ impl Behaviours {
         {
             return InteractionResult::Pass;
         }
+        if self.data(state).chain.contains(&Class::CopperGolemStatue) {
+            return self.turn_statue(level, ticks, pos, state, item);
+        }
         self.use_without_item(level, ticks, pos, face, hit, player)
     }
+
+    /// `CopperGolemStatueBlock.useItemOn` (and its weathering subclass's): anything but an axe
+    /// (`#minecraft:axes`, every one named `*_axe`), even an empty hand, turns the statue to its
+    /// next pose; honeycomb waxes a statue that still weathers instead.
+    fn turn_statue<L: LevelAccess + ?Sized>(
+        &self,
+        level: &mut L,
+        ticks: &mut Ticks,
+        pos: BlockPos,
+        state: BlockStateId,
+        item: Option<&str>,
+    ) -> InteractionResult {
+        let item = item.unwrap_or("minecraft:air");
+        let waxed = self.table.name(state).starts_with("minecraft:waxed_");
+        if item.ends_with("_axe") || (item == "minecraft:honeycomb" && !waxed) {
+            return InteractionResult::Pass;
+        }
+        let mut sim = self.sim(level, ticks);
+        sim.sound(
+            pos,
+            &"minecraft:entity.copper_golem_become_statue".into(),
+            1.0,
+            1.0,
+        );
+        sim.set_block_and_update(pos, self.table.cycle(state, self.props.copper_golem_pose));
+        sim.game_event(pos, "minecraft:block_change");
+        InteractionResult::Success
+    }
 }
diff --git a/tools/test_use_item_on_parity.py b/tools/test_use_item_on_parity.py
index 89b463116..eabdd04eb 100644
--- a/tools/test_use_item_on_parity.py
+++ b/tools/test_use_item_on_parity.py
@@ -2,8 +2,9 @@
 """Compare a player's right click on a block with vanilla's, for items that are
 both food and blocks (sweet and glow berries, carrots, potatoes), for sweet
 berry bushes, for spawn eggs used on a monster spawner, for shears carving
-pumpkins, for blocks placed where mobs and armor stands stand, for respawn
-anchors and for beds in the Nether and the End.
+pumpkins, for copper golem statues turned to their next pose, for blocks
+placed where mobs and armor stands stand, for respawn anchors and for beds in
+the Nether and the End.
 
 Every case has a block at the origin, something above it, and a player three
 blocks south, survival or creative, hungry or full, sneaking or not, who
@@ -228,6 +229,32 @@ def pumpkin_case(rng, states, case):
     case['cells'] = cells
 
 
+STATUES = [f'{wax}{age}copper_golem_statue' for wax in ('', 'waxed_')
+           for age in ('', 'exposed_', 'weathered_', 'oxidized_')]
+
+
+def statue_case(rng, states, case):
+    """A copper golem statue right-clicked (`CopperGolemStatueBlock.useItemOn`, the weathering
+    one's): anything but an axe, an empty hand too, turns it to its next pose; honeycomb waxes a
+    statue that still weathers instead (`HoneycombItem.useOn`), and an axe scrapes or unwaxes it."""
+    statue = rng.choice(STATUES)
+    case['cells'] = [[0, 0, 0, states.any(rng, statue)]]
+    items = ['-', '-', 'stick', 'honeycomb', 'honeycomb', 'stone', 'copper_ingot', 'diamond_pickaxe',
+             'copper_golem_statue']
+    if statue != 'copper_golem_statue':
+        # An axe scrapes or unwaxes the others; on the unaffected one it brings the golem back
+        # (`CopperGolemStatueBlockEntity.removeStatue`), which Horizon does not do yet.
+        items.append('iron_axe')
+    item = rng.choice(items)
+    use = {'item': '-' if item == '-' else d_plain(item, rng.choice([1, 16])), 'creative': rng.random() < 0.2,
+           'sneaking': rng.random() < 0.15, 'food': 20,
+           'face': rng.choice(['up', 'up', 'north', 'south', 'west', 'east'])}
+    if rng.random() < 0.2:
+        # The item in the off hand, nothing in the main hand.
+        use.update(offhand=use['item'], item='-')
+    case['use_item'] = use
+
+
 # Entities a block may be placed into (`Entity.blocksBuilding`), and blocks to place.
 BLOCKERS = ['skeleton', 'zombie', 'pig', 'chicken', 'cow', 'armor_stand', 'slime', 'bat']
 PLACED = ['obsidian', 'stone', 'oak_slab', 'oak_fence', 'white_carpet', 'torch', 'glass', 'oak_trapdoor', 'snow']
@@ -290,6 +317,12 @@ def cases(facts, count, seed):
             case['mode'] = 'dispense'
             yield case
             continue
+        if rng.random() < 0.08:
+            statue_case(rng, states, case)
+            case['items'] = []
+            case['mode'] = 'dispense'
+            yield case
+            continue
         if rng.random() < 0.12:
             pumpkin_case(rng, states, case)
             case['items'] = []

From bdbc816486ea2bc8aa3362a8547be73af897a9a1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:53:20 +0100
Subject: [PATCH 156/270] Creative search: match the localized hover name, not
 the item's base name

The base name (Tipped Arrow, Potion, White Banner) matched where vanilla's
first tooltip line (Arrow of Poison, Water Bottle, Ominous Banner) doesn't:
the creative harness found extra results for 'e', 'potion', 'tipped' and
'white'. name_line builds the full hover name through display_get.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/creative.rs | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/creative.rs b/crates/horizon-client/src/creative.rs
index 593aad61d..249e40b11 100644
--- a/crates/horizon-client/src/creative.rs
+++ b/crates/horizon-client/src/creative.rs
@@ -346,10 +346,16 @@ impl Creative {
         }
         // FullTextSearchTree: tooltip lines, and the item id after a colon.
         // The export's lines are English (they come from the vanilla jars);
-        // the display name in the selected language is matched too, so a
-        // localized search finds the item.
+        // the hover name in the selected language is matched too, so a
+        // localized search finds the item. It is the whole name (a tipped
+        // arrow's potion, the ominous banner), as the first line is.
         let text = java_lower(term);
-        let localized = |i: usize| java_lower(&names.display_item(&self.search_items[i].item));
+        let localized = |i: usize| {
+            java_lower(&crate::item_tooltip::name_line(
+                &self.search_items[i],
+                &|k| names.display_get(k),
+            ))
+        };
         all.filter(|&i| {
             let e = &self.search_index[i];
             let fallback;

From 90eda915d5dec7d02c929ec867262bfe867d396f Mon Sep 17 00:00:00 2001
From: Joansitoh <joan.programas@gmail.com>
Date: Sun, 25 Oct 2026 18:58:52 +0100
Subject: [PATCH 157/270] Add a lore tooltip harness against
 ItemLore.addToTooltip.

The styled lines have to keep matching vanilla, including an explicit non-italic span and a lore component hidden by tooltip_display.
---
 .../examples/probe/lore_tooltip_fixture.rs    | 53 +++++++++++++++++
 crates/horizon-client/examples/probe/main.rs  |  2 +
 .../parity/VanillaLoreTooltipOracle.java      | 58 +++++++++++++++++++
 tools/test_lore_tooltip_parity.py             | 41 +++++++++++++
 4 files changed, 154 insertions(+)
 create mode 100644 crates/horizon-client/examples/probe/lore_tooltip_fixture.rs
 create mode 100644 mods/horizon/src/test/java/dev/horizonlab/parity/VanillaLoreTooltipOracle.java
 create mode 100644 tools/test_lore_tooltip_parity.py

diff --git a/crates/horizon-client/examples/probe/lore_tooltip_fixture.rs b/crates/horizon-client/examples/probe/lore_tooltip_fixture.rs
new file mode 100644
index 000000000..350d9be81
--- /dev/null
+++ b/crates/horizon-client/examples/probe/lore_tooltip_fixture.rs
@@ -0,0 +1,53 @@
+//! Lore tooltip companion for tools/test_lore_tooltip_parity.py: the spans
+//! `item_tooltip::lore_texts` gives each stack (SNBT, one per line).
+use horizon_client::{
+    item_data::parse_stack,
+    item_tooltip::{TooltipDisplay, lore_texts},
+};
+use std::{error::Error, fmt::Write};
+
+pub fn main() -> Result<(), Box<dyn Error>> {
+    let args: Vec<String> = crate::args().collect();
+    let input = std::fs::read_to_string(&args[1])?;
+    let mut output = String::new();
+    for line in input
+        .lines()
+        .filter(|l| !l.is_empty() && !l.starts_with('#'))
+    {
+        let stack = parse_stack(line)?.ok_or("empty stack")?;
+        let display = TooltipDisplay::for_stack(&stack);
+        if !display.shows("minecraft:lore") {
+            writeln!(output, "-")?;
+            continue;
+        }
+        let lines = lore_texts(&stack);
+        if lines.is_empty() {
+            writeln!(output, "-")?;
+            continue;
+        }
+        let mut rendered = Vec::new();
+        for text in lines {
+            let mut spans = Vec::new();
+            for span in &text.spans {
+                if span.text.is_empty() {
+                    continue;
+                }
+                let style = &span.style;
+                spans.push(format!(
+                    "{}\t{}\t{}\t{}\t{}\t{}\t{}",
+                    span.text,
+                    style.color.map(|c| c as i32).unwrap_or(-1),
+                    style.bold == Some(true),
+                    style.italic == Some(true),
+                    style.underlined == Some(true),
+                    style.strikethrough == Some(true),
+                    style.obfuscated == Some(true),
+                ));
+            }
+            rendered.push(spans.join(" | "));
+        }
+        writeln!(output, "{}", rendered.join(" || "))?;
+    }
+    std::fs::write(&args[2], output)?;
+    Ok(())
+}
diff --git a/crates/horizon-client/examples/probe/main.rs b/crates/horizon-client/examples/probe/main.rs
index f05c2a662..e80088fd0 100644
--- a/crates/horizon-client/examples/probe/main.rs
+++ b/crates/horizon-client/examples/probe/main.rs
@@ -49,6 +49,7 @@ mod input_probe;
 mod interaction_input_fixture;
 mod lan_probe;
 mod light_parity;
+mod lore_tooltip_fixture;
 mod marker_particles_probe;
 mod menu_fixture;
 mod mipmap_probe;
@@ -133,6 +134,7 @@ probes! {
     interaction_input_fixture,
     lan_probe,
     light_parity,
+    lore_tooltip_fixture,
     marker_particles_probe,
     menu_fixture,
     mipmap_probe,
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaLoreTooltipOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaLoreTooltipOracle.java
new file mode 100644
index 000000000..462a8016a
--- /dev/null
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaLoreTooltipOracle.java
@@ -0,0 +1,58 @@
+package dev.horizonlab.parity;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Optional;
+import net.minecraft.core.component.DataComponents;
+import net.minecraft.network.chat.Component;
+import net.minecraft.network.chat.Style;
+import net.minecraft.world.item.Item;
+import net.minecraft.world.item.TooltipFlag;
+import net.minecraft.world.item.component.ItemLore;
+import net.minecraft.world.item.component.TooltipDisplay;
+
+/**
+ * The styled lines {@code ItemLore.addToTooltip} adds, one stack (SNBT) per input
+ * line. Each line is its visited spans ({@code text, colour, bold, italic,
+ * underlined, strikethrough, obfuscated}); lines are separated by {@code ||}.
+ */
+public final class VanillaLoreTooltipOracle {
+    public static void main(String[] args) throws Exception {
+        ParityData.init();
+        var context = Item.TooltipContext.of(ParityData.lookup);
+        var output = new ArrayList<String>();
+        for (String line : Files.readAllLines(Path.of(args[0]))) {
+            if (line.isBlank() || line.startsWith("#")) continue;
+            var stack = ParityData.stack(line);
+            var display = stack.getOrDefault(DataComponents.TOOLTIP_DISPLAY, TooltipDisplay.DEFAULT);
+            ItemLore lore = stack.get(DataComponents.LORE);
+            if (lore == null || !display.shows(DataComponents.LORE)) {
+                output.add("-");
+                continue;
+            }
+            var lines = new ArrayList<String>();
+            lore.addToTooltip(context, component -> lines.add(spans(component)), TooltipFlag.NORMAL, stack);
+            output.add(lines.isEmpty() ? "-" : String.join(" || ", lines));
+        }
+        Files.write(Path.of(args[1]), output);
+    }
+
+    /** {@code Component.visit} from {@code Style.EMPTY}: the style a tooltip draws. */
+    static String spans(Component component) {
+        var out = new StringBuilder();
+        component.visit((style, text) -> {
+            if (text.isEmpty()) return Optional.empty();
+            if (out.length() > 0) out.append(" | ");
+            int color = style.getColor() == null ? -1 : style.getColor().getValue();
+            out.append(text).append('\t').append(color).append('\t')
+                .append(style.isBold()).append('\t')
+                .append(style.isItalic()).append('\t')
+                .append(style.isUnderlined()).append('\t')
+                .append(style.isStrikethrough()).append('\t')
+                .append(style.isObfuscated());
+            return Optional.empty();
+        }, Style.EMPTY);
+        return out.toString();
+    }
+}
diff --git a/tools/test_lore_tooltip_parity.py b/tools/test_lore_tooltip_parity.py
new file mode 100644
index 000000000..d262a3542
--- /dev/null
+++ b/tools/test_lore_tooltip_parity.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Compare item lore tooltip styles with the pinned vanilla client.
+
+Vanilla prints what ``ItemLore.addToTooltip`` adds after ``ComponentUtils.mergeStyles``
+with dark purple italic (VanillaLoreTooltipOracle). Horizon prints what
+``item_tooltip::lore_texts`` gives (examples/probe/lore_tooltip_fixture).
+"""
+try:
+    from . import lab, oracle_harness as harness
+except ImportError:
+    import lab, oracle_harness as harness
+
+# SNBT stacks. A lore line is a text component; italic:0b is an explicit false.
+CASES = [
+    '{id:"minecraft:stick",count:1}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'"Plain"\']}}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'{"text":"Gold","color":"gold","italic":0b}\']}}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'{"text":"A","extra":[{"text":"B","color":"aqua","italic":0b}]}\']}}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'"One"\',\'{"text":"Two","bold":1b}\']}}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'"Hidden"\'],"minecraft:tooltip_display":{hidden_components:["minecraft:lore"]}}}',
+    '{id:"minecraft:stick",count:1,components:{"minecraft:lore":[\'{"text":"Line","underlined":1b,"strikethrough":1b}\']}}',
+]
+
+
+def cases(build):
+    path = build / 'cases.txt'
+    path.write_text(''.join(line + '\n' for line in CASES))
+    return path, len(CASES)
+
+
+if __name__ == '__main__':
+    harness.differential(
+        'lore-tooltip-parity', 'VanillaLoreTooltipOracle', 'lore_tooltip_fixture', cases,
+        'Item lore tooltip lines: dark purple italic, child colours, explicit non-italic, and tooltip_display',
+        sources=[
+            lab.ROOT / 'crates/horizon-client/src/item_tooltip.rs',
+            lab.ROOT / 'crates/horizon-client/src/item_data.rs',
+            lab.ROOT / 'crates/horizon-client/src/text.rs',
+            lab.ROOT / 'crates/horizon-client/src/component.rs',
+        ],
+        expected_lines=len(CASES))

From b3840adccdaf48f9c04f9e67f5b4decf74fd2545 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:08:03 +0000
Subject: [PATCH 158/270] Fix renderer backend fallback after surface creation
 failure

Keep surface creation errors in the backend failure list so Windows Auto can try DirectX 12 after Vulkan fails.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 crates/horizon-client/src/gfx.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 31853ad92..2c54a0e53 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -685,7 +685,7 @@ fn instance_descriptor(backends: wgpu::Backends) -> wgpu::InstanceDescriptor {
 /// device. `api` is the player's choice (`GraphicsApi::with_env` applied);
 /// `wgpu_backend`: whether `WGPU_BACKEND` is set, which picks the backends
 /// itself. Only Windows has two: Auto tries Vulkan, then DirectX 12 when
-/// Vulkan has no adapter (no Vulkan driver) or no device. A native crash in
+/// Vulkan has no surface, adapter (no Vulkan driver) or device. A native crash in
 /// the driver can't be caught in the game; the launcher switches the setting
 /// to DirectX 12 after one at the renderer's start (#746).
 fn backend_order(api: GraphicsApi, windows: bool, wgpu_backend: bool) -> Vec<wgpu::Backends> {
@@ -793,7 +793,13 @@ async fn open_device(
         let surface = if offscreen {
             None
         } else {
-            Some(instance.create_surface(window.clone())?)
+            match instance.create_surface(window.clone()) {
+                Ok(surface) => Some(surface),
+                Err(e) => {
+                    failures.push(format!("{name} surface: {e}"));
+                    continue;
+                }
+            }
         };
         let adapter = match instance
             .request_adapter(&wgpu::RequestAdapterOptions {

From 2c8930c48da0ba6c17db31dcaf09dea9a1465b4f Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:16:32 -0300
Subject: [PATCH 159/270] Chickens flap while they fall on a client of a server

Chicken.aiStep updates flap and flapSpeed on the client too, for the
chickens it only displays. tick_remote_entities never did, so with
single player on its server thread (and on servers) a falling chicken
kept its wings folded. The wing part of chicken_ai_step is now
chicken_flap, and the remote tick runs it from the server's on-ground
flag; the falling slowdown and egg laying stay the server's.

Fixes #1706.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/remote.rs |   4 +
 crates/horizon-client/src/mobs/farm.rs   | 111 +++++++++++++++++++++--
 2 files changed, 106 insertions(+), 9 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 620d145bf..b3a2b73ce 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -3572,6 +3572,10 @@ impl Game<'_> {
                 m.head_yaw += wrap_degrees(*yaw - m.head_yaw) / *steps as f32;
                 *steps -= 1;
             }
+            // Chicken.aiStep: the wings follow the server's on-ground flag.
+            if m.species() == horizon_client::mobs::Species::Chicken {
+                horizon_client::mobs::farm::chicken_flap(m);
+            }
             // LivingEntity.updatingUsingItem for another player: the ticks the
             // item has been used before this one.
             if player && m.extra.using_item > 0 {
diff --git a/crates/horizon-client/src/mobs/farm.rs b/crates/horizon-client/src/mobs/farm.rs
index bf886cb5a..aa02c901d 100644
--- a/crates/horizon-client/src/mobs/farm.rs
+++ b/crates/horizon-client/src/mobs/farm.rs
@@ -69,18 +69,10 @@ pub fn register(m: &mut Mob) {
 }
 /// Chicken.aiStep: wing flapping, slowed falling and laying eggs.
 pub fn chicken_ai_step(m: &mut Mob, _w: &MobWorld, events: &mut Vec<MobEvent>) {
-    let a = &mut m.anim;
-    a.flap_o = a.flap;
-    a.flap_speed_o = a.flap_speed;
-    a.flap_speed = (a.flap_speed + if m.on_ground { -1.0 } else { 4.0 } * 0.3).clamp(0.0, 1.0);
-    if !m.on_ground && a.flapping < 1.0 {
-        a.flapping = 1.0;
-    }
-    a.flapping *= 0.9;
+    chicken_flap(m);
     if !m.on_ground && m.velocity.y < 0.0 {
         m.velocity.y *= 0.6;
     }
-    a.flap += a.flapping * 2.0;
     if m.alive() && !m.is_baby() && !m.extra.jockey {
         m.extra.egg_time -= 1;
         if m.extra.egg_time <= 0 {
@@ -95,6 +87,21 @@ pub fn chicken_ai_step(m: &mut Mob, _w: &MobWorld, events: &mut Vec<MobEvent>) {
         }
     }
 }
+/// Chicken.aiStep's wings: `flapSpeed` rises in the air and falls on the
+/// ground, `flapping` restarts at 1 in the air and decays, and `flap` turns
+/// by it. It runs on a client too, for the chickens it only displays (the
+/// falling slowdown and the eggs are the server's).
+pub fn chicken_flap(m: &mut Mob) {
+    let a = &mut m.anim;
+    a.flap_o = a.flap;
+    a.flap_speed_o = a.flap_speed;
+    a.flap_speed = (a.flap_speed + if m.on_ground { -1.0 } else { 4.0 } * 0.3).clamp(0.0, 1.0);
+    if !m.on_ground && a.flapping < 1.0 {
+        a.flapping = 1.0;
+    }
+    a.flapping *= 0.9;
+    a.flap += a.flapping * 2.0;
+}
 /// Farm animal climate from the biome tags (`spawns_warm/cold_variant_farm_animals`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub enum Climate {
@@ -125,3 +132,89 @@ pub fn sheep_color(climate: Climate, random: &mut impl RandomSource) -> u8 {
         6
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mobs::{Anim, Brain, Flags, MobType, Part, Species};
+    use horizon_core::geometry::Vec3;
+    use serde_json::json;
+    use std::collections::HashMap;
+
+    fn chicken() -> Mob {
+        let model = Arc::new(Part::parse(
+            "root",
+            &json!({"children": {"right_wing": {}, "left_wing": {}}}),
+        ));
+        let kind = Arc::new(MobType {
+            id: "minecraft:chicken".into(),
+            species: Species::Chicken,
+            width: 0.4,
+            height: 0.7,
+            eye_height: 0.644,
+            category: "creature".into(),
+            max_health: 4.0,
+            speed: 0.25,
+            flying_speed: 0.4,
+            attack_damage: 0.0,
+            attack_knockback: 0.0,
+            follow_range: 16.0,
+            step_height: 0.6,
+            armor: 0.0,
+            armor_toughness: 0.0,
+            knockback_resistance: 0.0,
+            jump_strength: 0.42,
+            attributes: Arc::default(),
+            gravity: 0.08,
+            safe_fall_distance: 3.0,
+            fall_damage_multiplier: 1.0,
+            water_efficiency: 0.0,
+            water_slowdown: 0.8,
+            air_speed: 0.02,
+            baby_scale: 0.5,
+            head_rot_speed: 10.0,
+            max_head_x_rot: 40.0,
+            max_head_y_rot: 75.0,
+            ambient_interval: 120,
+            flags: Flags {
+                animal: true,
+                ..Default::default()
+            },
+            model,
+            layers: HashMap::new(),
+            texture: String::new(),
+            brain: Brain::Passive,
+            anim: Anim::Chicken,
+            sounds: [""; 3],
+            step_sound: None,
+            food: Arc::default(),
+            tempt: Arc::default(),
+        });
+        Mob::new(1, kind, Vec3::ZERO, 0.0)
+    }
+
+    #[test]
+    fn a_falling_chicken_flaps_and_a_landed_one_folds_its_wings() {
+        let mut m = chicken();
+        m.on_ground = true;
+        chicken_flap(&mut m);
+        assert_eq!(m.anim.flap_speed, 0.0);
+        assert_eq!(m.anim.flap, 0.0);
+        // In the air flapSpeed rises by 1.2 (clamped to 1), flapping restarts
+        // at 1 and decays by 0.9, and flap turns by twice flapping.
+        m.on_ground = false;
+        chicken_flap(&mut m);
+        assert_eq!(m.anim.flap_speed, 1.0);
+        assert_eq!(m.anim.flapping, 0.9);
+        assert_eq!(m.anim.flap, 1.8);
+        chicken_flap(&mut m);
+        assert_eq!(m.anim.flap_o, 1.8);
+        assert_eq!(m.anim.flap_speed_o, 1.0);
+        assert_eq!(m.anim.flap, 3.6);
+        // Landed, flapSpeed falls by 0.3 a tick and flapping decays.
+        m.on_ground = true;
+        chicken_flap(&mut m);
+        assert!((m.anim.flap_speed - 0.7).abs() < 1.0e-6);
+        assert!((m.anim.flapping - 0.81).abs() < 1.0e-6);
+    }
+}

From 96199c23e7ba28ec666bff1309ce6a075a058c17 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:20:17 +0100
Subject: [PATCH 160/270] Shader packs, clean room 41: entities and block
 entities in the shadow pass

shadow_entities and shadow_block (each falling back to shadow) load with
the entities' vertex inputs unless shadowEntities or shadowBlockEntities is
false (spec 2.4, 3.2; both on by default, OQ-19). They draw the same entity
and block-entity runs the gbuffers programs would, with the same per-draw
uniforms, into the shadow map after the solid terrain and before the
shadowtex1 copy. A run is uploaded when a gbuffers program or a shadow
program draws it; Horizon still draws the runs no gbuffers program covers.

Without a pack nothing changes: only the pack's entity code is touched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/gfx/pack_entities.rs   | 35 +++++---
 crates/horizon-client/src/gfx/pack_post.rs    | 85 +++++++++++++++++--
 crates/horizon-shaders/src/post.rs            | 70 +++++++++++----
 crates/horizon-shaders/tests/real_packs.rs    |  4 +-
 4 files changed, 160 insertions(+), 34 deletions(-)

diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
index ffc55149f..30fa70880 100644
--- a/crates/horizon-client/src/gfx/pack_entities.rs
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -161,8 +161,12 @@ pub(super) struct Draw {
     /// The first vertex.
     pub base: u32,
     pub quads: u32,
-    /// The program that draws it (`ENTITY`, `BLOCK`, `TRANSLUCENT`, `PARTICLE`).
+    /// The kind of program that draws it (`ENTITY`, `BLOCK`, `TRANSLUCENT`, `PARTICLE`).
     pub program: usize,
+    /// The pack's gbuffers program draws it (else Horizon does).
+    pub pack: bool,
+    /// The pack's shadow program draws it into the shadow map too.
+    pub shadow: bool,
     pub slot: u32,
 }
 
@@ -280,7 +284,8 @@ impl PackEntities {
 
     /// Splits `entities` between the pack, which draws the runs of `spans` its programs cover
     /// (`drawn`: whether it has `gbuffers_entities`, `gbuffers_block` or their fallbacks), and
-    /// Horizon, which draws the rest (`rest`). Uploads the pack's part.
+    /// Horizon, which draws the rest (`rest`). Uploads the pack's part, and the runs its shadow
+    /// programs draw (`shadow`: entities, block entities).
     #[allow(clippy::too_many_arguments)]
     pub fn prepare(
         &mut self,
@@ -290,6 +295,7 @@ impl PackEntities {
         entities: &[Vertex],
         spans: &[EntitySpan],
         drawn: [bool; PROGRAMS],
+        shadow: [bool; 2],
         rest: &mut Vec<Vertex>,
     ) {
         self.draws.clear();
@@ -300,13 +306,15 @@ impl PackEntities {
         rest.extend_from_slice(&entities[..first.min(entities.len())]);
         for (span, range) in runs(entities.len(), spans) {
             let run = &entities[range];
-            let Some(program) = drawn_by_pack(&span, drawn).filter(|_| plain(run)) else {
+            let program = program_of(&span).filter(|_| plain(run));
+            let pack = program.is_some_and(|p| drawn[p]);
+            let casts = program.is_some_and(|p| shadow.get(p).copied().unwrap_or(false));
+            if !pack {
                 rest.extend_from_slice(run);
+            }
+            let Some(program) = program.filter(|_| (pack || casts) && !run.is_empty()) else {
                 continue;
             };
-            if run.is_empty() {
-                continue;
-            }
             let start = self.scratch.len() as u32;
             self.scratch.extend_from_slice(run);
             let (entity_id, block_id) = match program {
@@ -327,6 +335,8 @@ impl PackEntities {
                 base: start,
                 quads: run.len() as u32 / 4,
                 program,
+                pack,
+                shadow: casts,
                 slot: self.draws.len() as u32,
             });
         }
@@ -388,8 +398,14 @@ pub const PROGRAMS: usize = 4;
 
 /// Which program draws `span`'s run, given which of them (or their fallbacks) the pack has;
 /// `None`: Horizon draws it.
-pub fn drawn_by_pack(span: &EntitySpan, drawn: [bool; PROGRAMS]) -> Option<usize> {
-    let program = if span.stage == render_stage("ENTITIES") {
+#[cfg(test)]
+fn drawn_by_pack(span: &EntitySpan, drawn: [bool; PROGRAMS]) -> Option<usize> {
+    program_of(span).filter(|&p| drawn[p])
+}
+
+/// The kind of program that draws `span`'s run, when a pack may.
+pub fn program_of(span: &EntitySpan) -> Option<usize> {
+    Some(if span.stage == render_stage("ENTITIES") {
         if span.translucent {
             TRANSLUCENT
         } else {
@@ -401,8 +417,7 @@ pub fn drawn_by_pack(span: &EntitySpan, drawn: [bool; PROGRAMS]) -> Option<usize
         PARTICLE
     } else {
         return None;
-    };
-    drawn[program].then_some(program)
+    })
 }
 
 /// Each span with its vertex range: from its start to the next span's (or the end).
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 57ce0b147..da174b022 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -147,6 +147,15 @@ struct Entities {
     geometry: PackEntities,
     passes: [Option<Pass>; PROGRAMS],
     late: [bool; PROGRAMS],
+    /// What draws entities and block entities into the shadow map (2.4).
+    shadow: [Option<Pass>; 2],
+}
+
+impl Entities {
+    /// Whether a gbuffers program draws some of them (else only the shadow pass does).
+    fn drawn(&self) -> bool {
+        self.passes.iter().any(Option::is_some)
+    }
 }
 
 #[derive(Clone)]
@@ -1077,8 +1086,8 @@ impl PackPost {
             post.particles,
         ];
         let late = [false, false, post.translucent_late, post.particles_late];
-        let entity_vertices = programs
-            .iter()
+        let shadow_programs = [post.shadow_entities, post.shadow_block];
+        let entity_vertices = (programs.iter().chain(&shadow_programs))
             .any(Option::is_some)
             .then(|| PackEntities::new(device, &draws.layout));
         let entity_buffers = super::pack_entities::buffers();
@@ -1094,12 +1103,17 @@ impl PackPost {
             p.zip(entity_geometry.as_ref())
                 .and_then(|(p, g)| build(p, Some(g)))
         });
+        let shadow_entities = shadow_programs.map(|p| {
+            p.zip(entity_geometry.as_ref())
+                .and_then(|(p, g)| build(p, Some(g)))
+        });
         let entities = entity_vertices
-            .filter(|_| entity_passes.iter().any(Option::is_some))
+            .filter(|_| (entity_passes.iter().chain(&shadow_entities)).any(Option::is_some))
             .map(|geometry| Entities {
                 geometry,
                 passes: entity_passes,
                 late,
+                shadow: shadow_entities,
             });
         let cloud_geometry = world.clouds.map(|layout| Geometry {
             buffers: &entity_buffers,
@@ -1204,6 +1218,15 @@ impl PackPost {
                 notes.push(format!("{part} draw with {}", p.name));
             }
         }
+        // Timed (and labelled) apart from the terrain's shadow pass, which may run the same
+        // program.
+        let mut entities = entities;
+        for (part, pass) in (entities.iter_mut()).flat_map(|e| parts.iter().zip(&mut e.shadow)) {
+            if let Some(p) = pass {
+                notes.push(format!("{part} cast shadows with {}", p.name));
+                p.name.push_str(&format!(" ({part})"));
+            }
+        }
         let depth1 = water.is_some()
             && passes
                 .iter()
@@ -1220,6 +1243,7 @@ impl PackPost {
             .chain(shadow_terrain.iter().chain(&shadow_water))
             .chain(sky.iter().flat_map(|s| s.basic.iter().chain(&s.textured)))
             .chain(entities.iter().flat_map(|e| e.passes.iter().flatten()))
+            .chain(entities.iter().flat_map(|e| e.shadow.iter().flatten()))
             .chain(&clouds)
             .chain(weather.iter().flatten())
             .chain(hand.iter().map(|h| &h.0))
@@ -1277,7 +1301,7 @@ impl PackPost {
         let blit_depth = terrain.is_some()
             || water.is_some()
             || sky.is_some()
-            || entities.is_some()
+            || entities.as_ref().is_some_and(Entities::drawn)
             || clouds.is_some()
             || weather.is_some()
             || hand.is_some()
@@ -1775,7 +1799,7 @@ impl PackPost {
             let mut draws = geometry
                 .draws
                 .iter()
-                .filter(|d| d.program == program)
+                .filter(|d| d.pack && d.program == program)
                 .peekable();
             if draws.peek().is_none() {
                 continue;
@@ -1800,6 +1824,46 @@ impl PackPost {
         self.entities = Some(entities);
     }
 
+    /// Entities and block entities into the shadow map, each run with the per-draw uniforms
+    /// of its gbuffers draw (2.4): opaque, so before the `shadowtex1` copy.
+    fn draw_shadow_entities(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        size: [u32; 2],
+    ) {
+        let Some(mut entities) = self.entities.take() else {
+            return;
+        };
+        let geometry = &entities.geometry;
+        for (program, pass) in entities.shadow.iter_mut().enumerate() {
+            let Some(pass) = pass else {
+                continue;
+            };
+            let mut draws = (geometry.draws.iter())
+                .filter(|d| d.shadow && d.program == program)
+                .peekable();
+            if draws.peek().is_none() {
+                continue;
+            }
+            let group = self.bind(device, queue, pass, size);
+            let mut rp = self.begin(encoder, pass);
+            rp.set_pipeline(&pass.pipeline);
+            rp.set_bind_group(0, &group, &[]);
+            rp.set_bind_group(1, &geometry.table_group, &[]);
+            rp.set_vertex_buffer(0, geometry.vertices());
+            rp.set_index_buffer(geometry.indices.slice(..), wgpu::IndexFormat::Uint32);
+            for d in draws {
+                if pass.draw {
+                    rp.set_bind_group(2, &geometry.group, &[geometry.offset(d.slot)]);
+                }
+                rp.draw_indexed(0..d.quads * 6, d.base as i32, 0..1);
+            }
+        }
+        self.entities = Some(entities);
+    }
+
     /// Splits `entities` (`Frame::entities`) between the pack and Horizon by its runs
     /// (`spans`): the pack's part is uploaded for this frame's draw, Horizon's goes to `rest`.
     pub fn prepare_entities(
@@ -1816,6 +1880,11 @@ impl PackPost {
             return;
         };
         let drawn = e.passes.each_ref().map(Option::is_some);
+        // Only while the shadow pass draws this frame.
+        let shadow = e
+            .shadow
+            .each_ref()
+            .map(|p| p.is_some() && self.shadow_targets.is_some());
         e.geometry.prepare(
             device,
             queue,
@@ -1823,6 +1892,7 @@ impl PackPost {
             entities,
             spans,
             drawn,
+            shadow,
             rest,
         );
     }
@@ -2029,7 +2099,6 @@ impl PackPost {
         }
     }
 
-    /// Whether the pack draws terrain itself.
     /// What the shadow camera draws of the terrain this frame, when the pack draws it.
     pub fn shadow_view(&self, frame: &super::Frame) -> Option<ShadowView> {
         self.shadow_targets.as_ref()?;
@@ -2044,6 +2113,7 @@ impl PackPost {
         })
     }
 
+    /// Whether the pack draws terrain itself.
     pub fn has_terrain(&self) -> bool {
         self.terrain.is_some()
     }
@@ -2187,6 +2257,7 @@ impl PackPost {
             TerrainList::ShadowSolid,
             terrain,
         );
+        self.draw_shadow_entities(device, queue, encoder, size);
         let t = self.shadow_targets.as_mut().expect("shadow pass");
         t.clear_rest(encoder);
         t.copy_depth1(encoder);
@@ -2395,7 +2466,7 @@ impl PackPost {
         let mut shown = false;
         let mut terrain_drawn = self.terrain.is_none()
             && self.sky.is_none()
-            && self.entities.is_none()
+            && !self.entities.as_ref().is_some_and(Entities::drawn)
             && self.clouds.is_none()
             && self.hand.is_none();
         let late_entities = self.entities.as_ref().is_some_and(|e| {
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index dd062b508..715dca257 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -248,6 +248,10 @@ pub struct Post {
     /// translucent terrain (`shadow_water` or `shadow`), into the shadow buffers (2.4).
     pub shadow: Option<PostProgram>,
     pub shadow_water: Option<PostProgram>,
+    /// What draws entities (`shadow_entities` or `shadow`) and block entities (`shadow_block` or
+    /// `shadow`) from the light, unless `shadowEntities`/`shadowBlockEntities` is false.
+    pub shadow_entities: Option<PostProgram>,
+    pub shadow_block: Option<PostProgram>,
     /// `shadowcomp`..`shadowcomp99`, after the shadow pass (2.1).
     pub shadow_comp: Vec<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
@@ -317,6 +321,8 @@ pub fn load_post(
         shadow_pass: false,
         shadow: None,
         shadow_water: None,
+        shadow_entities: None,
+        shadow_block: None,
         shadow_comp: Vec::new(),
         translucent_late: false,
         particles_late: false,
@@ -472,14 +478,23 @@ pub fn load_post(
         Some(_) => true,
         None => !flag("particles.before.deferred").unwrap_or(false),
     };
-    load_shadow(&mut loader, inputs.terrain.as_ref());
+    load_shadow(
+        &mut loader,
+        inputs.terrain.as_ref(),
+        inputs.entities.as_ref(),
+    );
     post.config = std::mem::take(&mut post.config).finish();
     post
 }
 
 /// Whether the shadow pass runs (2.5) and, when it does, its programs: `shadow_solid` and
 /// `shadow_cutout` are not used (2.4, Legacy); the game's solid and cutout terrain is one draw.
-fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
+/// `shadow_entities` and `shadow_block` read the entities' vertices (`entities`).
+fn load_shadow(
+    loader: &mut Loader<'_>,
+    terrain: Option<&GbuffersInputs>,
+    entities: Option<&GbuffersInputs>,
+) {
     let post = &*loader.post;
     let gbuffers = [
         &post.terrain,
@@ -516,11 +531,9 @@ fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
         });
         loader.post.shadow_comp.extend(program);
     }
-    let Some(inputs) = terrain else {
-        return;
-    };
     let properties = loader.properties;
-    let mut load = |names: &[&str]| {
+    let mut load = |names: &[&str], inputs: Option<&GbuffersInputs>| {
+        let inputs = inputs?;
         names.iter().find_map(|name| {
             let p = loader.load(name.to_string(), Group::Shadow, |v, f| {
                 translate_shadow(v, f, inputs)
@@ -531,13 +544,22 @@ fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
             })
         })
     };
-    // `shadowTerrain` and `shadowTranslucent` (3.2) leave terrain out of the shadow pass.
+    // `shadowTerrain`, `shadowTranslucent`, `shadowEntities` and `shadowBlockEntities` (3.2)
+    // leave their part out of the shadow pass; all are on by default (OQ-19).
     let keep = |key: &str| properties.get(key).is_none_or(|v| v.trim() != "false");
-    let shadow = keep("shadowTerrain").then(|| load(&["shadow"])).flatten();
-    let water = keep("shadowTranslucent")
-        .then(|| load(&["shadow_water", "shadow"]))
+    let shadow = keep("shadowTerrain")
+        .then(|| load(&["shadow"], terrain))
         .flatten();
-    if shadow.is_none() {
+    let water = keep("shadowTranslucent")
+        .then(|| load(&["shadow_water", "shadow"], terrain))
+        .flatten();
+    let shadow_entities = keep("shadowEntities")
+        .then(|| load(&["shadow_entities", "shadow"], entities))
+        .flatten();
+    let shadow_block = keep("shadowBlockEntities")
+        .then(|| load(&["shadow_block", "shadow"], entities))
+        .flatten();
+    if shadow.is_none() && terrain.is_some() {
         loader
             .post
             .notes
@@ -545,6 +567,8 @@ fn load_shadow(loader: &mut Loader<'_>, terrain: Option<&GbuffersInputs>) {
     }
     loader.post.shadow = shadow;
     loader.post.shadow_water = water;
+    loader.post.shadow_entities = shadow_entities;
+    loader.post.shadow_block = shadow_block;
 }
 
 struct Loader<'a> {
@@ -828,14 +852,18 @@ mod tests {
             ("shaders/shadow.fsh", shadow),
             ("shaders/shadowcomp1.vsh", VSH),
             ("shaders/shadowcomp1.fsh", FSH),
+            ("shaders/shadow_block.vsh", VSH),
+            ("shaders/shadow_block.fsh", FSH),
         ];
         let pack = Pack::from_zip_bytes("t", zip(&files)).unwrap();
+        let game = crate::GbuffersInputs {
+            declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
+            body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n".into(),
+            ..Default::default()
+        };
         let inputs = GameInputs {
-            terrain: Some(crate::GbuffersInputs {
-                declarations: "layout(location = 0) in vec3 hz_v_pos;".into(),
-                body: "    hz_Vertex = vec4(hz_v_pos, 1.0);\n".into(),
-                ..Default::default()
-            }),
+            terrain: Some(game.clone()),
+            entities: Some(game),
             ..Default::default()
         };
         let load = |properties: &str| {
@@ -854,6 +882,16 @@ mod tests {
             post.shadow_water.as_ref().map(|p| p.name.as_str()),
             Some("shadow")
         );
+        // Entities fall back to shadow; block entities have their own program.
+        let name = |p: &Option<PostProgram>| p.as_ref().map(|p| p.name.clone());
+        assert_eq!(
+            (name(&post.shadow_entities), name(&post.shadow_block)),
+            (Some("shadow".into()), Some("shadow_block".into()))
+        );
+        let off = load("shadowEntities=false\nshadowBlockEntities = false");
+        assert!(
+            off.shadow.is_some() && off.shadow_entities.is_none() && off.shadow_block.is_none()
+        );
         let comp: Vec<_> = post
             .shadow_comp
             .iter()
diff --git a/crates/horizon-shaders/tests/real_packs.rs b/crates/horizon-shaders/tests/real_packs.rs
index 70fcaa55f..52d31fd0e 100644
--- a/crates/horizon-shaders/tests/real_packs.rs
+++ b/crates/horizon-shaders/tests/real_packs.rs
@@ -180,11 +180,13 @@ fn real_packs_read() {
             };
             let post = load_post(&pack, &folder, &shaders, &Macros::standard(), &inputs);
             println!(
-                "  dimension {id} (folder `{folder}`): {} post programs, shadow pass {} ({:?}, {:?}, {} shadowcomp), terrain {:?}, water {:?}, sky {:?} {:?}, entities {:?} {:?}, {} notes, {:.0} ms",
+                "  dimension {id} (folder `{folder}`): {} post programs, shadow pass {} ({:?}, {:?}, {:?}, {:?}, {} shadowcomp), terrain {:?}, water {:?}, sky {:?} {:?}, entities {:?} {:?}, {} notes, {:.0} ms",
                 post.programs.len(),
                 post.shadow_pass,
                 post.shadow.as_ref().map(|t| &t.name),
                 post.shadow_water.as_ref().map(|t| &t.name),
+                post.shadow_entities.as_ref().map(|t| &t.name),
+                post.shadow_block.as_ref().map(|t| &t.name),
                 post.shadow_comp.len(),
                 post.terrain.as_ref().map(|t| &t.name),
                 post.water.as_ref().map(|t| &t.name),

From f969415c7a91ab19c83c6b3d98d1d6c9950eca6c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:36:52 +0100
Subject: [PATCH 161/270] Creative stacks: reuse the wire codec both sides
 already had

Horizon already encoded stacks for the wire (lan::guest::stack_to_network,
what a Horizon server sends its clients: damage, enchantments, stored
enchantments, repair cost, custom name, dyed colour, trim, maps, charged
projectiles, books) and decoded them on the client (remote.rs's
protocol_components + item_data::decode_components, every component it has
a codec for). The new encode/apply pair covered six components and
duplicated both.

- The client's SetCreativeModeSlot stack goes through stack_to_network.
- The decoder moves into item_sync::from_network, used by the client for
  what its server sends and by the server (Hub::stack_from_network) for a
  creative client's slot, so the server now keeps every component the
  client's decoder reads, not six.
- One round-trip test covers encode then decode with registries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/lan_actions.rs |  17 +-
 crates/horizon-client/src/game/remote.rs      | 198 +--------
 crates/horizon-client/src/item_data.rs        |   2 +-
 crates/horizon-client/src/item_sync.rs        | 378 ++++++++++++------
 crates/horizon-client/src/lan/hub.rs          |  11 +-
 5 files changed, 270 insertions(+), 336 deletions(-)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 1b4989055..84633836c 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1217,21 +1217,8 @@ impl Game<'_> {
         stack: &Option<horizon_protocol::item::Stack>,
     ) -> Option<ItemStack> {
         let s = stack.as_ref()?;
-        let name = host
-            .hub
-            .item_name(s.item)
-            .unwrap_or_else(|| "minecraft:air".into());
-        let mut out = ItemStack::new(&name, s.count.max(1) as u32);
-        // The same components the encoder wrote, so a creative slot keeps what
-        // the client held instead of just damage and enchantments.
-        horizon_client::item_sync::apply(
-            s,
-            &mut out,
-            |id| host.hub.enchantment_name(id).map(|n| n.into()),
-            |id| host.hub.trim_name("minecraft:trim_material", id),
-            |id| host.hub.trim_name("minecraft:trim_pattern", id),
-        );
-        out.tidy();
+        let mut out = host.hub.stack_from_network(s);
+        out.count = out.count.max(1);
         Some(out)
     }
 
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 55d259c1a..2c6ab4a26 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -223,30 +223,6 @@ fn face_direction(face: [i32; 3]) -> u8 {
     }
 }
 
-/// A `minecraft:profile` component as the item data JSON the model reads.
-fn profile_tag(p: &horizon_protocol::item::Profile) -> Tag {
-    let properties = p
-        .properties
-        .iter()
-        .map(|(name, value, signature)| {
-            let mut entries: Vec<(&'static str, Tag)> = vec![
-                ("name", Tag::String(name.as_str().into())),
-                ("value", Tag::String(value.as_str().into())),
-            ];
-            if let Some(signature) = signature {
-                entries.push(("signature", Tag::String(signature.as_str().into())));
-            }
-            Tag::compound(entries)
-        })
-        .collect::<Vec<_>>();
-    let mut entries: Vec<(&'static str, Tag)> = Vec::new();
-    if let Some(name) = &p.name {
-        entries.push(("name", Tag::String(name.as_str().into())));
-    }
-    entries.push(("properties", Tag::List(properties)));
-    Tag::compound(entries)
-}
-
 /// A protocol number format as the scoreboard's.
 fn number_format(f: &play::NumberFormat) -> horizon_client::scoreboard::NumberFormat {
     use horizon_client::scoreboard::{NumberFormat, tag_to_json};
@@ -610,168 +586,26 @@ impl Game<'_> {
             .and_then(|i| i.id(name))
             .unwrap_or(0)
     }
+    /// A stack from the server, decoded as the saved and command item NBT
+    /// are, so tooltips and models see every field.
     pub(super) fn to_stack(&self, s: &Option<Stack>) -> Option<ItemStack> {
-        let s = s.as_ref()?;
-        let mut out = ItemStack {
-            item: self.item_name(s.item),
-            count: s.count.max(0) as u32,
-            damage: 0,
-            extra: None,
-        };
-        // A vanilla `components` compound, then the same decoder the saved
-        // and command item NBT use, so tooltips and models see every field.
-        let components = self.protocol_components(s);
-        let (damage, data) = horizon_client::item_data::decode_components(components.as_ref());
-        out.damage = damage;
-        if let Some(data) = data {
-            *out.data_mut() = *data;
-        }
-        out.tidy();
-        Some(out)
-    }
-    /// The item's patched components as vanilla's `components` compound.
-    fn protocol_components(&self, s: &Stack) -> Option<Tag> {
-        use horizon_protocol::item::{Component, component};
         let r = self.remote.as_ref()?;
-        let name = |id: i32| r.builtin.get("minecraft:data_component_type")?.name(id);
-        let mut entries: Vec<(&str, Tag)> = Vec::new();
-        for (kind, c) in &s.added {
-            let Some(key) = name(*kind) else {
-                continue;
-            };
-            let value = match c {
-                // Read past, not decoded: the item keeps its prototype's value.
-                Component::Raw(_) => continue,
-                // Trim materials and patterns are synced registries, as enchantments are.
-                Component::Trim { material, pattern } => {
-                    let (Some(material), Some(pattern)) = (
-                        r.registries.name("minecraft:trim_material", *material),
-                        r.registries.name("minecraft:trim_pattern", *pattern),
-                    ) else {
-                        continue;
-                    };
-                    Tag::compound([
-                        ("material", Tag::String(material.into())),
-                        ("pattern", Tag::String(pattern.into())),
-                    ])
-                }
-                Component::Int(v) if *kind == component::RARITY => {
-                    let rarity = ["common", "uncommon", "rare", "epic"];
-                    Tag::String(rarity.get(*v as usize).copied().unwrap_or("common").into())
-                }
-                Component::Int(v) => Tag::Int(*v),
-                Component::Unit => Tag::Compound(Default::default()),
-                Component::Bool(v) => Tag::Byte(i8::from(*v)),
-                Component::Text(t) | Component::Nbt(t) => t.clone(),
-                Component::Ident(v) => Tag::String(v.as_str().into()),
-                Component::Lore(lines) => Tag::List(lines.clone()),
-                Component::WritableBook(pages) => Tag::compound([(
-                    "pages",
-                    Tag::List(
-                        pages
-                            .iter()
-                            .map(|p| Tag::String(p.as_str().into()))
-                            .collect(),
-                    ),
-                )]),
-                Component::WrittenBook(b) => Tag::compound([
-                    ("title", Tag::String(b.title.as_str().into())),
-                    ("author", Tag::String(b.author.as_str().into())),
-                    ("generation", Tag::Int(b.generation)),
-                    ("pages", Tag::List(b.pages.clone())),
-                    ("resolved", Tag::Byte(i8::from(b.resolved))),
-                ]),
-                Component::Enchantments(list) => {
-                    // Enchantments are a synced (data-driven) registry: the
-                    // ids index the server's RegistryData, not the builtin
-                    // report, so a datapack enchantment names correctly.
-                    let levels = list.iter().filter_map(|(id, level)| {
-                        let name = r.registries.name("minecraft:enchantment", *id)?;
-                        Some((name, Tag::Int(*level)))
-                    });
-                    Tag::compound(levels)
-                }
-                Component::AttackRange(v) => Tag::compound([
-                    ("min_reach", Tag::Float(v[0].to_bits())),
-                    ("max_reach", Tag::Float(v[1].to_bits())),
-                    ("min_attack_momentum", Tag::Float(v[2].to_bits())),
-                    ("max_attack_momentum", Tag::Float(v[3].to_bits())),
-                    ("hitbox_margin", Tag::Float(v[4].to_bits())),
-                    ("mob_factor", Tag::Float(v[5].to_bits())),
-                ]),
-                Component::Profile(p) => profile_tag(p),
-                // ItemStackTemplate.CODEC: id, count and components.
-                Component::Stacks(stacks) => Tag::List(
-                    stacks
-                        .iter()
-                        .map(|t| {
-                            let mut entries = vec![
-                                ("id", Tag::String(self.item_name(t.item).as_ref().into())),
-                                ("count", Tag::Int(t.count)),
-                            ];
-                            if let Some(c) = self.protocol_components(t) {
-                                entries.push(("components", c));
-                            }
-                            Tag::compound(entries)
-                        })
-                        .collect(),
-                ),
-                Component::CustomModelData {
-                    floats,
-                    flags,
-                    strings,
-                    colors,
-                } => Tag::compound([
-                    (
-                        "floats",
-                        Tag::List(floats.iter().map(|f| Tag::Float(f.to_bits())).collect()),
-                    ),
-                    (
-                        "flags",
-                        Tag::List(flags.iter().map(|b| Tag::Byte(i8::from(*b))).collect()),
-                    ),
-                    (
-                        "strings",
-                        Tag::List(
-                            strings
-                                .iter()
-                                .map(|s| Tag::String(s.as_str().into()))
-                                .collect(),
-                        ),
-                    ),
-                    (
-                        "colors",
-                        Tag::List(colors.iter().map(|c| Tag::Int(*c)).collect()),
-                    ),
-                ]),
-                Component::TooltipDisplay { hide, hidden } => {
-                    let hidden = hidden
-                        .iter()
-                        .filter_map(|id| Some(Tag::String(name(*id)?.into())));
-                    Tag::compound([
-                        ("hide_tooltip", Tag::Byte(i8::from(*hide))),
-                        ("hidden_components", Tag::List(hidden.collect())),
-                    ])
-                }
-            };
-            entries.push((key, value));
-        }
-        Some(Tag::compound(entries))
+        Some(horizon_client::item_sync::from_network(
+            s.as_ref()?,
+            &r.builtin,
+            &r.registries,
+        ))
     }
+    /// A stack to the server (`SetCreativeModeSlot`): the same component
+    /// patch a Horizon server sends its clients, with the synced registries'
+    /// ids, so the server's echo doesn't hand back a bare item.
     fn to_network(&self, s: &Option<ItemStack>) -> Option<Stack> {
-        let s = s.as_ref()?;
-        let mut stack = Stack::new(self.item_id(&s.item), s.count as i32);
-        // The components the client models, with the synced registries' ids:
-        // without them the server's echo hands back a bare item.
-        if let Some(r) = self.remote.as_ref() {
-            stack.added.extend(horizon_client::item_sync::encode(
-                s,
-                |name| r.registries.id("minecraft:enchantment", name),
-                |name| r.registries.id("minecraft:trim_material", name),
-                |name| r.registries.id("minecraft:trim_pattern", name),
-            ));
-        }
-        Some(stack)
+        let r = self.remote.as_ref()?;
+        horizon_client::lan::guest::stack_to_network(
+            |name| self.item_id(name),
+            |registry, name| r.registries.id(registry, name),
+            s,
+        )
     }
     /// A line in the connection's chat, with its styles, click and hover
     /// events (ChatComponent.addMessage).
diff --git a/crates/horizon-client/src/item_data.rs b/crates/horizon-client/src/item_data.rs
index 00fd0f074..c07e2f352 100644
--- a/crates/horizon-client/src/item_data.rs
+++ b/crates/horizon-client/src/item_data.rs
@@ -291,7 +291,7 @@ fn filterable_text(t: &Tag) -> Option<String> {
         None => read_text(t),
     }
 }
-pub(crate) fn read_text(t: &Tag) -> Option<String> {
+fn read_text(t: &Tag) -> Option<String> {
     match t {
         Tag::String(s) => Some(s.to_string_lossy()),
         // A component's root `text` may be empty with the visible words in
diff --git a/crates/horizon-client/src/item_sync.rs b/crates/horizon-client/src/item_sync.rs
index 4e48498ac..6ac2e894e 100644
--- a/crates/horizon-client/src/item_sync.rs
+++ b/crates/horizon-client/src/item_sync.rs
@@ -1,149 +1,277 @@
-//! The data components a stack keeps when it crosses the wire, and how the
-//! other side reads them back. A creative slot's packet carries a component
-//! patch, and before this the encoder wrote damage alone, so everything else
-//! (enchantments, a custom name, trim, repair cost) was gone once the server
-//! echoed the inventory back.
-use crate::item_data::{Levels, StackData};
+//! Item stacks on the wire (`ItemStack.OPTIONAL_STREAM_CODEC`): the component
+//! patch read back as vanilla's `components` compound, so the decoder the saved
+//! and command item NBT use fills every field. Both sides use it: a client for
+//! what its server sends, a server for a creative client's
+//! `SetCreativeModeSlot`. The other direction is `lan::guest::stack_to_network`.
 use crate::items::ItemStack;
-use horizon_protocol::item::{Component, Stack, component};
+use horizon_protocol::item::{Component, Profile, Stack, component};
+use horizon_protocol::registry::{Builtin, Dynamic};
 use horizon_world::nbt::Tag;
 use std::sync::Arc;
 
-/// `Slot.STREAM_CODEC`'s patch for the components Horizon models, with the
-/// registries' ids for enchantments and trim. A name the registry does not
-/// know is left out: id 0 is a different entry, not a missing one.
-pub fn encode(
-    stack: &ItemStack,
-    enchantment: impl Fn(&str) -> Option<i32>,
-    trim_material: impl Fn(&str) -> Option<i32>,
-    trim_pattern: impl Fn(&str) -> Option<i32>,
-) -> Vec<(i32, Component)> {
-    let mut out = Vec::new();
-    if stack.damage > 0 {
-        out.push((component::DAMAGE, Component::Int(stack.damage as i32)));
-    }
-    let Some(d) = stack.data() else {
-        return out;
+/// A stack from the wire: its item by the built-in registry's id, its
+/// components by the synced registries' (enchantments, trims).
+pub fn from_network(s: &Stack, builtin: &Builtin, synced: &Dynamic) -> ItemStack {
+    let mut out = ItemStack {
+        item: item_name(builtin, s.item),
+        count: s.count.max(0) as u32,
+        damage: 0,
+        extra: None,
     };
-    let levels = |levels: &Levels| -> Option<Component> {
-        let list: Vec<(i32, i32)> = levels
-            .iter()
-            .filter_map(|(name, level)| Some((enchantment(name)?, *level as i32)))
-            .collect();
-        (!list.is_empty()).then_some(Component::Enchantments(list))
-    };
-    if let Some(c) = levels(&d.enchantments) {
-        out.push((component::ENCHANTMENTS, c));
-    }
-    if let Some(c) = levels(&d.stored_enchantments) {
-        out.push((component::STORED_ENCHANTMENTS, c));
-    }
-    if d.repair_cost > 0 {
-        out.push((component::REPAIR_COST, Component::Int(d.repair_cost as i32)));
-    }
-    if let Some(name) = &d.custom_name {
-        // A plain string is a valid text component, and `decode_components`
-        // reads it back as one.
-        out.push((
-            component::CUSTOM_NAME,
-            Component::Text(Tag::String(name.as_str().into())),
-        ));
-    }
-    if let Some((material, pattern)) = &d.trim
-        && let (Some(material), Some(pattern)) = (trim_material(material), trim_pattern(pattern))
-    {
-        out.push((component::TRIM, Component::Trim { material, pattern }));
+    let components = components_tag(s, builtin, synced);
+    let (damage, data) = crate::item_data::decode_components(components.as_ref());
+    out.damage = damage;
+    if let Some(data) = data {
+        *out.data_mut() = *data;
     }
+    out.tidy();
     out
 }
 
-/// The same patch read back into `out`, the fields `item_data::decode_components`
-/// fills from the equivalent `components` compound.
-pub fn apply(
-    stack: &Stack,
-    out: &mut ItemStack,
-    enchantment: impl Fn(i32) -> Option<Arc<str>>,
-    trim_material: impl Fn(i32) -> Option<Arc<str>>,
-    trim_pattern: impl Fn(i32) -> Option<Arc<str>>,
-) {
-    out.damage = stack.damage().max(0) as u32;
-    let read_levels = |kind: i32, into: &mut Levels| {
-        if let Some(Component::Enchantments(list)) = stack.component(kind) {
-            for (id, level) in list {
-                if let Some(name) = enchantment(*id) {
-                    into.push((name, (*level).max(0) as u32));
-                }
+fn item_name(builtin: &Builtin, id: i32) -> Arc<str> {
+    Arc::from(
+        builtin
+            .get("minecraft:item")
+            .and_then(|i| i.name(id))
+            .unwrap_or("minecraft:air"),
+    )
+}
+
+/// The item's patched components as vanilla's `components` compound.
+fn components_tag(s: &Stack, builtin: &Builtin, synced: &Dynamic) -> Option<Tag> {
+    let name = |id: i32| builtin.get("minecraft:data_component_type")?.name(id);
+    let mut entries: Vec<(&str, Tag)> = Vec::new();
+    for (kind, c) in &s.added {
+        let Some(key) = name(*kind) else {
+            continue;
+        };
+        let value = match c {
+            // Read past, not decoded: the item keeps its prototype's value.
+            Component::Raw(_) => continue,
+            // Trim materials and patterns are synced registries, as enchantments are.
+            Component::Trim { material, pattern } => {
+                let (Some(material), Some(pattern)) = (
+                    synced.name("minecraft:trim_material", *material),
+                    synced.name("minecraft:trim_pattern", *pattern),
+                ) else {
+                    continue;
+                };
+                Tag::compound([
+                    ("material", Tag::String(material.into())),
+                    ("pattern", Tag::String(pattern.into())),
+                ])
             }
-        }
-    };
-    let data: &mut StackData = out.data_mut();
-    read_levels(component::ENCHANTMENTS, &mut data.enchantments);
-    read_levels(
-        component::STORED_ENCHANTMENTS,
-        &mut data.stored_enchantments,
-    );
-    if let Some(Component::Int(v)) = stack.component(component::REPAIR_COST) {
-        data.repair_cost = (*v).max(0) as u32;
+            Component::Int(v) if *kind == component::RARITY => {
+                let rarity = ["common", "uncommon", "rare", "epic"];
+                Tag::String(rarity.get(*v as usize).copied().unwrap_or("common").into())
+            }
+            Component::Int(v) => Tag::Int(*v),
+            Component::Unit => Tag::Compound(Default::default()),
+            Component::Bool(v) => Tag::Byte(i8::from(*v)),
+            Component::Text(t) | Component::Nbt(t) => t.clone(),
+            Component::Ident(v) => Tag::String(v.as_str().into()),
+            Component::Lore(lines) => Tag::List(lines.clone()),
+            Component::WritableBook(pages) => Tag::compound([(
+                "pages",
+                Tag::List(
+                    pages
+                        .iter()
+                        .map(|p| Tag::String(p.as_str().into()))
+                        .collect(),
+                ),
+            )]),
+            Component::WrittenBook(b) => Tag::compound([
+                ("title", Tag::String(b.title.as_str().into())),
+                ("author", Tag::String(b.author.as_str().into())),
+                ("generation", Tag::Int(b.generation)),
+                ("pages", Tag::List(b.pages.clone())),
+                ("resolved", Tag::Byte(i8::from(b.resolved))),
+            ]),
+            Component::Enchantments(list) => {
+                // Enchantments are a synced (data-driven) registry: the
+                // ids index the server's RegistryData, not the builtin
+                // report, so a datapack enchantment names correctly.
+                let levels = list.iter().filter_map(|(id, level)| {
+                    let name = synced.name("minecraft:enchantment", *id)?;
+                    Some((name, Tag::Int(*level)))
+                });
+                Tag::compound(levels)
+            }
+            Component::AttackRange(v) => Tag::compound([
+                ("min_reach", Tag::Float(v[0].to_bits())),
+                ("max_reach", Tag::Float(v[1].to_bits())),
+                ("min_attack_momentum", Tag::Float(v[2].to_bits())),
+                ("max_attack_momentum", Tag::Float(v[3].to_bits())),
+                ("hitbox_margin", Tag::Float(v[4].to_bits())),
+                ("mob_factor", Tag::Float(v[5].to_bits())),
+            ]),
+            Component::Profile(p) => profile_tag(p),
+            // ItemStackTemplate.CODEC: id, count and components.
+            Component::Stacks(stacks) => Tag::List(
+                stacks
+                    .iter()
+                    .map(|t| {
+                        let mut entries = vec![
+                            (
+                                "id",
+                                Tag::String(item_name(builtin, t.item).as_ref().into()),
+                            ),
+                            ("count", Tag::Int(t.count)),
+                        ];
+                        if let Some(c) = components_tag(t, builtin, synced) {
+                            entries.push(("components", c));
+                        }
+                        Tag::compound(entries)
+                    })
+                    .collect(),
+            ),
+            Component::CustomModelData {
+                floats,
+                flags,
+                strings,
+                colors,
+            } => Tag::compound([
+                (
+                    "floats",
+                    Tag::List(floats.iter().map(|f| Tag::Float(f.to_bits())).collect()),
+                ),
+                (
+                    "flags",
+                    Tag::List(flags.iter().map(|b| Tag::Byte(i8::from(*b))).collect()),
+                ),
+                (
+                    "strings",
+                    Tag::List(
+                        strings
+                            .iter()
+                            .map(|s| Tag::String(s.as_str().into()))
+                            .collect(),
+                    ),
+                ),
+                (
+                    "colors",
+                    Tag::List(colors.iter().map(|c| Tag::Int(*c)).collect()),
+                ),
+            ]),
+            Component::TooltipDisplay { hide, hidden } => {
+                let hidden = hidden
+                    .iter()
+                    .filter_map(|id| Some(Tag::String(name(*id)?.into())));
+                Tag::compound([
+                    ("hide_tooltip", Tag::Byte(i8::from(*hide))),
+                    ("hidden_components", Tag::List(hidden.collect())),
+                ])
+            }
+        };
+        entries.push((key, value));
     }
-    if let Some(Component::Text(t)) = stack.component(component::CUSTOM_NAME) {
-        data.custom_name = crate::item_data::read_text(t);
-    }
-    if let Some(Component::Trim { material, pattern }) = stack.component(component::TRIM)
-        && let (Some(material), Some(pattern)) = (trim_material(*material), trim_pattern(*pattern))
-    {
-        data.trim = Some((material, pattern));
+    Some(Tag::compound(entries))
+}
+
+/// A `minecraft:profile` component as the item data JSON the model reads.
+fn profile_tag(p: &Profile) -> Tag {
+    let properties = p
+        .properties
+        .iter()
+        .map(|(name, value, signature)| {
+            let mut entries: Vec<(&'static str, Tag)> = vec![
+                ("name", Tag::String(name.as_str().into())),
+                ("value", Tag::String(value.as_str().into())),
+            ];
+            if let Some(signature) = signature {
+                entries.push(("signature", Tag::String(signature.as_str().into())));
+            }
+            Tag::compound(entries)
+        })
+        .collect::<Vec<_>>();
+    let mut entries: Vec<(&'static str, Tag)> = Vec::new();
+    if let Some(name) = &p.name {
+        entries.push(("name", Tag::String(name.as_str().into())));
     }
+    entries.push(("properties", Tag::List(properties)));
+    Tag::compound(entries)
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use horizon_protocol::registry::Ids;
 
-    fn named(name: &str) -> Option<i32> {
-        Some(match name {
-            "minecraft:sharpness" => 3,
-            "minecraft:gold" => 7,
-            "minecraft:sentry" => 2,
-            _ => return None,
-        })
-    }
-    fn name_of(id: i32) -> Option<Arc<str>> {
-        Some(Arc::from(match id {
-            3 => "minecraft:sharpness",
-            7 => "minecraft:gold",
-            2 => "minecraft:sentry",
-            _ => return None,
-        }))
-    }
-
-    fn stack_with_data() -> ItemStack {
-        let mut stack = ItemStack::new("minecraft:diamond_sword", 1);
+    /// What a creative client sends (`stack_to_network`) comes back whole on
+    /// the server: damage, both enchantment lists, repair cost, name, trim.
+    #[test]
+    fn a_creative_stack_keeps_its_components_across_the_wire() {
+        let mut components = vec![String::new(); 60];
+        for (id, name) in [
+            (component::DAMAGE, "minecraft:damage"),
+            (component::CUSTOM_NAME, "minecraft:custom_name"),
+            (component::ENCHANTMENTS, "minecraft:enchantments"),
+            (component::REPAIR_COST, "minecraft:repair_cost"),
+            (
+                component::STORED_ENCHANTMENTS,
+                "minecraft:stored_enchantments",
+            ),
+            (component::TRIM, "minecraft:trim"),
+        ] {
+            components[id as usize] = name.to_owned();
+        }
+        let names = |n: &[&str]| n.iter().map(|s| s.to_string()).collect::<Vec<_>>();
+        let builtin = Builtin {
+            registries: [
+                (
+                    "minecraft:item".to_owned(),
+                    Ids::from_names(names(&["minecraft:air", "minecraft:diamond_chestplate"])),
+                ),
+                (
+                    "minecraft:data_component_type".to_owned(),
+                    Ids::from_names(components),
+                ),
+            ]
+            .into(),
+        };
+        let synced = |n: &[&str]| n.iter().map(|s| (s.to_string(), None)).collect::<Vec<_>>();
+        let dynamic = Dynamic {
+            registries: [
+                (
+                    "minecraft:enchantment".to_owned(),
+                    synced(&["minecraft:protection", "minecraft:sharpness"]),
+                ),
+                (
+                    "minecraft:trim_material".to_owned(),
+                    synced(&["minecraft:gold"]),
+                ),
+                (
+                    "minecraft:trim_pattern".to_owned(),
+                    synced(&["minecraft:sentry"]),
+                ),
+            ]
+            .into(),
+        };
+        let mut stack = ItemStack::new("minecraft:diamond_chestplate", 1);
         stack.damage = 5;
+        stack.enchant("minecraft:protection", 4);
         let d = stack.data_mut();
-        d.enchantments.push((Arc::from("minecraft:sharpness"), 4));
         d.stored_enchantments
             .push((Arc::from("minecraft:sharpness"), 2));
         d.repair_cost = 9;
         d.custom_name = Some("Keeper".to_owned());
         d.trim = Some((Arc::from("minecraft:gold"), Arc::from("minecraft:sentry")));
-        stack
-    }
-
-    /// Every modelled component survives the packet, so the server's echo does
-    /// not hand back a bare item.
-    #[test]
-    fn a_stack_keeps_its_components_across_the_wire() {
-        let stack = stack_with_data();
-        let mut packet = Stack::new(1, 1);
-        packet.added = encode(&stack, named, named, named);
-
-        let mut back = ItemStack::new("minecraft:diamond_sword", 1);
-        apply(&packet, &mut back, name_of, name_of, name_of);
-        back.tidy();
-
+        let wire = crate::lan::guest::stack_to_network(
+            |name| {
+                builtin
+                    .get("minecraft:item")
+                    .and_then(|i| i.id(name))
+                    .unwrap_or(0)
+            },
+            |registry, name| dynamic.id(registry, name),
+            &Some(stack.clone()),
+        )
+        .unwrap();
+        let back = from_network(&wire, &builtin, &dynamic);
+        assert_eq!(back.item, stack.item);
         assert_eq!(back.damage, 5);
         let d = back.data().expect("components");
-        assert_eq!(d.enchantments, vec![(Arc::from("minecraft:sharpness"), 4)]);
+        assert_eq!(d.enchantments, vec![(Arc::from("minecraft:protection"), 4)]);
         assert_eq!(
             d.stored_enchantments,
             vec![(Arc::from("minecraft:sharpness"), 2)]
@@ -155,16 +283,4 @@ mod tests {
             Some((Arc::from("minecraft:gold"), Arc::from("minecraft:sentry")))
         );
     }
-
-    /// A name the registry does not know is a missing id, not id 0, which would
-    /// name the registry's first entry instead.
-    #[test]
-    fn an_unknown_enchantment_is_left_out_rather_than_sent_as_zero() {
-        let mut stack = ItemStack::new("minecraft:book", 1);
-        stack
-            .data_mut()
-            .enchantments
-            .push((Arc::from("mod:unknown"), 1));
-        assert!(encode(&stack, named, named, named).is_empty());
-    }
 }
diff --git a/crates/horizon-client/src/lan/hub.rs b/crates/horizon-client/src/lan/hub.rs
index 2667b1fed..dddecf0ca 100644
--- a/crates/horizon-client/src/lan/hub.rs
+++ b/crates/horizon-client/src/lan/hub.rs
@@ -2293,13 +2293,10 @@ impl Hub {
             .name("minecraft:enchantment", id)
             .map(str::to_owned)
     }
-    /// An entry of a synced registry by id, for the components a packet
-    /// carries by id (`minecraft:trim_material`, `minecraft:trim_pattern`).
-    pub fn trim_name(&self, registry: &str, id: i32) -> Option<std::sync::Arc<str>> {
-        self.sync
-            .dynamic
-            .name(registry, id)
-            .map(std::sync::Arc::from)
+    /// A stack a client sent (`SetCreativeModeSlot`), read with this
+    /// server's registries.
+    pub fn stack_from_network(&self, s: &horizon_protocol::item::Stack) -> crate::items::ItemStack {
+        crate::item_sync::from_network(s, &self.sync.builtin, &self.sync.dynamic)
     }
 
     /// ServerLevel.removePlayerImmediately, then addRespawnedPlayer: the other players

From e4a151c2e9dd78b09d5f76962df1ee6992061bf1 Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 15:49:15 -0300
Subject: [PATCH 162/270] Menu buttons show the pointing hand under the mouse

26.3's AbstractWidget.handleCursor asks for CursorTypes.POINTING_HAND
when a widget is hovered, or NOT_ALLOWED when it is inactive, and the
frame applies the last request to the window (GuiGraphicsExtractor
requestCursor and applyCursor, Window.selectCursor). Horizon never
changed the cursor, so it stayed an arrow over buttons.

widgets.rs keeps the frame's request, ui::button and the resource pack
screen's buttons make it from the mouse hover (not keyboard focus), and
the game sets winit's Pointer, NotAllowed or Default cursor after each
frame when it changes.

Fixes #1347.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs        | 22 ++++++++
 crates/horizon-client/src/pack_screen.rs |  3 ++
 crates/horizon-client/src/ui.rs          |  1 +
 crates/horizon-client/src/widgets.rs     | 66 +++++++++++++++++++++++-
 4 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 0502753db..1a862193d 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1203,6 +1203,8 @@ struct Game<'a> {
     left: bool,
     right: bool,
     cursor: (f32, f32),
+    /// The cursor icon the window shows (`widgets::take_cursor` each frame).
+    cursor_icon: horizon_client::widgets::Cursor,
     captured: bool,
     focused: bool,
     /// The keyboard's modifier state (`KeyEvent.modifiers`).
@@ -4659,6 +4661,24 @@ impl Game<'_> {
         }
         window.set_cursor_visible(!self.captured);
     }
+    /// `GuiGraphicsExtractor.applyCursor` -> `Window.selectCursor` at the end
+    /// of a frame: the cursor the frame's widgets asked for, set on the window
+    /// only when it changes.
+    fn apply_cursor_icon(&mut self) {
+        use horizon_client::widgets::Cursor;
+        let wanted = horizon_client::widgets::take_cursor();
+        if wanted == self.cursor_icon {
+            return;
+        }
+        if let Some(window) = &self.window {
+            window.set_cursor(match wanted {
+                Cursor::Arrow => winit::window::CursorIcon::Default,
+                Cursor::PointingHand => winit::window::CursorIcon::Pointer,
+                Cursor::NotAllowed => winit::window::CursorIcon::NotAllowed,
+            });
+        }
+        self.cursor_icon = wanted;
+    }
     /// LevelLoadingScreen.onClose -> Gui.setScreen(null) -> grabMouse.
     fn capture_loaded_world(&mut self) {
         // Loading may finish after focus was lost or another screen opened.
@@ -11472,6 +11492,7 @@ impl ApplicationHandler for Game<'_> {
                     self.advance_flight();
                     let ticked = Instant::now();
                     let rendered = self.render()?;
+                    self.apply_cursor_icon();
                     if let Some(threshold) = self.options.spikes
                         && let Some(r) = self.renderer.as_ref()
                     {
@@ -11779,6 +11800,7 @@ impl<'a> Game<'a> {
             left: false,
             right: false,
             cursor: (0.0, 0.0),
+            cursor_icon: horizon_client::widgets::Cursor::Arrow,
             captured: false,
             focused: true,
             modifiers: winit::keyboard::ModifiersState::empty(),
diff --git a/crates/horizon-client/src/pack_screen.rs b/crates/horizon-client/src/pack_screen.rs
index 2929fd663..03906030a 100644
--- a/crates/horizon-client/src/pack_screen.rs
+++ b/crates/horizon-client/src/pack_screen.rs
@@ -831,6 +831,7 @@ impl PackScreen {
             d::label(&mut out, &lines, mx, my, self.width - 50, true);
             for ((bx, by), key) in buttons.into_iter().zip(["gui.yes", "gui.no"]) {
                 let hover = d::inside(mouse, bx, by, 150, 20);
+                crate::widgets::widget_cursor(hover, true);
                 d::button(&mut out, m, &tr(key), bx, by, 150, 20, true, hover);
             }
             return out;
@@ -856,6 +857,8 @@ impl PackScreen {
             } else {
                 "gui.done"
             });
+            // The cursor follows the mouse; the highlight also keyboard focus.
+            crate::widgets::widget_cursor(hover, true);
             d::button(
                 &mut out,
                 m,
diff --git a/crates/horizon-client/src/ui.rs b/crates/horizon-client/src/ui.rs
index 1c6e93067..df72ba45b 100644
--- a/crates/horizon-client/src/ui.rs
+++ b/crates/horizon-client/src/ui.rs
@@ -309,6 +309,7 @@ pub fn button(
     hover: bool,
 ) {
     crate::widgets::record(&label.plain(), [x, y, w, h], active);
+    crate::widgets::widget_cursor(hover, active);
     let sprite = if !active {
         "gui/sprites/widget/button_disabled"
     } else if hover {
diff --git a/crates/horizon-client/src/widgets.rs b/crates/horizon-client/src/widgets.rs
index 8bd80d3d1..c7c7eb2db 100644
--- a/crates/horizon-client/src/widgets.rs
+++ b/crates/horizon-client/src/widgets.rs
@@ -1,8 +1,47 @@
 //! The labelled widgets and focus targets drawn in the last frame, for the
 //! control socket: a script clicks a button by its label (`horizon-ctl
 //! click-button Respawn`) or any widget by its id in [`tree`] (`horizon-ctl
-//! click done`), whatever screen drew it.
-use std::cell::RefCell;
+//! click done`), whatever screen drew it. Also the mouse cursor the widget
+//! under the mouse asks for.
+use std::cell::{Cell, RefCell};
+
+/// The mouse cursor a frame's widgets asked for (`CursorTypes`; the others
+/// aren't asked for yet).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum Cursor {
+    #[default]
+    Arrow,
+    PointingHand,
+    NotAllowed,
+}
+
+thread_local! {
+    /// `GuiGraphicsExtractor.requestCursor`: the last request since [`take_cursor`].
+    static CURSOR: Cell<Cursor> = const { Cell::new(Cursor::Arrow) };
+}
+
+/// `GuiGraphicsExtractor.requestCursor`: the last request of a frame wins.
+pub fn request_cursor(cursor: Cursor) {
+    CURSOR.set(cursor);
+}
+
+/// `AbstractWidget.handleCursor`: a hovered widget asks for the pointing
+/// hand, or for not-allowed when it is inactive.
+pub fn widget_cursor(hovered: bool, active: bool) {
+    if hovered {
+        request_cursor(if active {
+            Cursor::PointingHand
+        } else {
+            Cursor::NotAllowed
+        });
+    }
+}
+
+/// The cursor the frame asked for, and back to the arrow for the next one
+/// (the window shows the arrow unless a widget asks).
+pub fn take_cursor() -> Cursor {
+    CURSOR.replace(Cursor::Arrow)
+}
 
 /// A labelled widget in GUI pixels (the coordinates screens take input in).
 #[derive(Clone, Debug)]
@@ -133,6 +172,29 @@ pub fn record_as(label: &str, [x, y, w, h]: [f32; 4], enabled: bool, kind: Kind)
     });
 }
 
+#[cfg(test)]
+mod cursor_tests {
+    use super::*;
+
+    #[test]
+    fn hovered_widgets_ask_for_the_hand_or_not_allowed() {
+        let _ = take_cursor();
+        widget_cursor(false, true);
+        assert_eq!(take_cursor(), Cursor::Arrow);
+        widget_cursor(true, true);
+        assert_eq!(take_cursor(), Cursor::PointingHand);
+        // Taken: the next frame starts from the arrow.
+        assert_eq!(take_cursor(), Cursor::Arrow);
+        widget_cursor(true, false);
+        assert_eq!(take_cursor(), Cursor::NotAllowed);
+        // The last request of a frame wins.
+        widget_cursor(true, false);
+        widget_cursor(false, true);
+        widget_cursor(true, true);
+        assert_eq!(take_cursor(), Cursor::PointingHand);
+    }
+}
+
 /// Once per event loop turn with the count of rendered frames: when a new
 /// frame was drawn since the last call, its buttons become the last frame's.
 pub fn end_frame(frames: u64) {

From 9ec5f1ddbc31908eaa27735a01ecd8ba9cf44182 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:51:09 +0100
Subject: [PATCH 163/270] Rockets: a guest's boost rocket hurts them; fireworks
 sent to a server's clients

FireworkRocketEntity.dealExplosionDamage hurts attachedToEntity with the
full 5 + 2 per explosion: a guest's boost rocket now hurts that guest
instead of nobody. The host's encoder (network_stack) now sends
minecraft:fireworks and minecraft:firework_explosion too, so a rocket's
flight duration and a star's explosion reach the server thread's window,
LAN guests and a dedicated server's players; the creative slot encoder
shares it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/fireworks.rs | 15 ++++++--
 crates/horizon-client/src/game/remote.rs    | 21 +++---------
 crates/horizon-client/src/lan/guest.rs      | 38 +++++++++++++++++++++
 3 files changed, 55 insertions(+), 19 deletions(-)

diff --git a/crates/horizon-client/src/game/fireworks.rs b/crates/horizon-client/src/game/fireworks.rs
index 623e0e147..7838c9590 100644
--- a/crates/horizon-client/src/game/fireworks.rs
+++ b/crates/horizon-client/src/game/fireworks.rs
@@ -251,8 +251,19 @@ impl Game<'_> {
         let at = [r.position.x, r.position.y, r.position.z];
         if !r.explosions.is_empty() {
             let damage = 5.0 + r.explosions.len() as f32 * 2.0;
-            if r.attached && r.guest.is_none() {
-                self.hurt_player_by("minecraft:fireworks", damage);
+            // The player it boosts takes the full damage, a guest as well.
+            if r.attached {
+                match r.guest {
+                    None => self.hurt_player_by("minecraft:fireworks", damage),
+                    Some(conn) => {
+                        if let Some(mut host) = self.lan.take() {
+                            self.as_guest(&mut host, conn, |g| {
+                                g.hurt_player_by("minecraft:fireworks", damage);
+                            });
+                            self.lan = Some(host);
+                        }
+                    }
+                }
             }
             let from = r.position;
             let hits: Vec<(u32, f32)> = {
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 5a8582ac9..d8b370af4 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -769,23 +769,10 @@ impl Game<'_> {
                 horizon_protocol::item::Component::Int(s.damage as i32),
             ));
         }
-        if let Some((flight, explosions)) = s.data().and_then(|d| d.fireworks.clone()) {
-            stack.added.push((
-                horizon_protocol::item::component::FIREWORKS,
-                horizon_protocol::item::Component::Fireworks {
-                    flight: i32::from(flight),
-                    explosions: explosions
-                        .iter()
-                        .map(|e| horizon_protocol::item::FireworkExplosion {
-                            shape: e.shape as i32,
-                            colors: e.colors.iter().map(|c| *c as i32).collect(),
-                            fade: e.fade.iter().map(|c| *c as i32).collect(),
-                            trail: e.trail,
-                            twinkle: e.twinkle,
-                        })
-                        .collect(),
-                },
-            ));
+        if let Some(d) = s.data() {
+            stack
+                .added
+                .extend(horizon_client::lan::guest::firework_components(d));
         }
         Some(stack)
     }
diff --git a/crates/horizon-client/src/lan/guest.rs b/crates/horizon-client/src/lan/guest.rs
index 440b58284..4bafe7866 100644
--- a/crates/horizon-client/src/lan/guest.rs
+++ b/crates/horizon-client/src/lan/guest.rs
@@ -431,6 +431,43 @@ impl Guest {
     }
 }
 
+/// `FireworkExplosion.STREAM_CODEC`'s fields (`Shape` by its BY_ID order).
+fn network_explosion(
+    e: &crate::particles::FireworkExplosion,
+) -> horizon_protocol::item::FireworkExplosion {
+    horizon_protocol::item::FireworkExplosion {
+        shape: e.shape as i32,
+        colors: e.colors.iter().map(|c| *c as i32).collect(),
+        fade: e.fade.iter().map(|c| *c as i32).collect(),
+        trail: e.trail,
+        twinkle: e.twinkle,
+    }
+}
+
+/// A rocket's `minecraft:fireworks` and a star's `minecraft:firework_explosion`.
+pub fn firework_components(
+    d: &crate::item_data::StackData,
+) -> Vec<(i32, horizon_protocol::item::Component)> {
+    use horizon_protocol::item::{Component, component};
+    let mut out = Vec::new();
+    if let Some((flight, explosions)) = &d.fireworks {
+        out.push((
+            component::FIREWORKS,
+            Component::Fireworks {
+                flight: i32::from(*flight),
+                explosions: explosions.iter().map(network_explosion).collect(),
+            },
+        ));
+    }
+    if let Some(e) = &d.firework_explosion {
+        out.push((
+            component::FIREWORK_EXPLOSION,
+            Component::FireworkExplosion(network_explosion(e)),
+        ));
+    }
+    out
+}
+
 /// The off hand slot is conventionally 40 in saves and 45 in the menu.
 /// `synced_id` names an entry of a synced registry (enchantments, trim
 /// materials and patterns) by its id on this connection.
@@ -521,6 +558,7 @@ fn network_stack(
                 horizon_protocol::item::Component::Int(i32::from(mode)),
             ));
         }
+        stack.added.extend(firework_components(d));
         // A loaded crossbow's ammunition.
         if !d.charged.is_empty() {
             let charged = d

From dab13669f513ec00b24b591188bf3382d2bad96b Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:53:09 +0100
Subject: [PATCH 164/270] Creative screen drops reach the server:
 SetCreativeModeSlot(-1)

A stack picked from a creative tab exists only on the client. Thrown out of
the creative screen as a server's client, it went out as a ContainerClick to
slot -999, which the server had no carried stack for, so nothing dropped. The
client now sends handleCreativeModeItemDrop's SetCreativeModeSlot(-1, stack),
and the server drops it from the player's hand, with vanilla's drop spam
throttle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  8 +++--
 crates/horizon-client/src/game/lan_actions.rs | 33 +++++++++++++++++++
 crates/horizon-client/src/game/remote.rs      | 28 ++++++++++++++++
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 7fcb3be89..88972eebe 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -2163,7 +2163,7 @@ impl Game<'_> {
         self.player_drop(thrown);
     }
     /// `Player.drop`: the statistics and a thrown item entity in front of the player.
-    fn player_drop(&mut self, thrown: ItemStack) {
+    pub(super) fn player_drop(&mut self, thrown: ItemStack) {
         let Some(eye) = self.eye_position() else {
             return;
         };
@@ -6326,7 +6326,11 @@ impl Game<'_> {
         use horizon_client::menu::Input;
         let button = i32::from(right);
         if self.remote.is_some() {
-            self.remote_throw(right, input);
+            if self.screen == Screen::Creative {
+                self.remote_creative_drop(right);
+            } else {
+                self.remote_throw(right, input);
+            }
             return;
         }
         let before = self.carried.clone();
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..2e5890b5b 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -38,6 +38,9 @@ pub(super) struct GuestPlay {
     use_delay: u32,
     /// The shield's ItemCooldowns entry: an axe disabled it for this many ticks.
     pub(super) shield_cooldown: u32,
+    /// `ServerGamePacketListenerImpl.dropSpamThrottler` (`TickThrottler(20, 1480)`): 20 for each
+    /// item a creative player drops from the creative screen, one less each tick.
+    creative_drops: u32,
     attack_ticks: u32,
     /// The main hand's item at the guest's last tick (`Game::attack_item`).
     attack_item: Option<std::sync::Arc<str>>,
@@ -1015,6 +1018,35 @@ impl Game<'_> {
             }
             S::MoveVehicle(p) => self.guest_move_vehicle(host, conn, &p),
             S::PaddleBoat(p) => self.guest_paddle_boat(host, conn, [p.left, p.right]),
+            // handleSetCreativeModeSlot's drop: a slot below 0 is a stack thrown out of the
+            // creative screen (`handleCreativeModeItemDrop`), dropped from the player's hand.
+            S::SetCreativeModeSlot(p) if p.slot < 0 => {
+                if !host.hub.guests[gi].creative() {
+                    return;
+                }
+                let Some(stack) = self.item_from_network(host, &p.item) else {
+                    return;
+                };
+                if stack.count
+                    > self
+                        .res
+                        .items()
+                        .get(&stack.item)
+                        .map_or(64, |i| i.max_stack)
+                {
+                    return;
+                }
+                let play = host.play.entry(conn).or_default();
+                if play.creative_drops >= 1480 {
+                    eprintln!(
+                        "Player {} was dropping items too fast in creative mode, ignoring.",
+                        host.hub.guests[gi].name
+                    );
+                    return;
+                }
+                play.creative_drops += 20;
+                self.as_guest(host, conn, |g| g.player_drop(stack));
+            }
             S::SetCreativeModeSlot(p) => {
                 let g = &mut host.hub.guests[gi];
                 if !g.creative() || !(0..46).contains(&p.slot) {
@@ -1701,6 +1733,7 @@ impl Game<'_> {
             // Player.tick's ItemCooldowns.tick, once a tick for each player
             // (the shield an axe disabled).
             play.shield_cooldown = play.shield_cooldown.saturating_sub(1);
+            play.creative_drops = play.creative_drops.saturating_sub(1);
             let digging = play.digging;
             let using = play.using.is_some();
             let delayed = play.destroy_delay > 0 || play.use_delay > 0 || play.attack_ticks < 100;
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 620d145bf..53abd4b1f 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -4831,6 +4831,34 @@ impl Game<'_> {
             carried,
         }));
     }
+    /// `CreativeModeInventoryScreen.slotClicked` outside the window: the server knows nothing of
+    /// a stack picked from the creative screen, so the carried stack (an item tab's right click:
+    /// one of it) is dropped through `handleCreativeModeItemDrop`, a SetCreativeModeSlot to slot
+    /// -1, and the hand swings as `Player.drop` predicts.
+    pub(super) fn remote_creative_drop(&mut self, right: bool) {
+        let one = right && !self.creative_inventory_open();
+        let Some(carried) = self.carried.as_mut() else {
+            return;
+        };
+        let thrown = if one && carried.count > 1 {
+            carried.count -= 1;
+            ItemStack {
+                count: 1,
+                ..carried.clone()
+            }
+        } else {
+            self.carried.take().expect("carried")
+        };
+        if !self.creative {
+            return;
+        }
+        self.swing_arm();
+        let item = self.to_network(&Some(thrown));
+        self.send(S::SetCreativeModeSlot(play::SetCreativeModeSlot {
+            slot: -1,
+            item,
+        }));
+    }
     pub(super) fn remote_close_container(&mut self) {
         let id = self
             .remote

From 4513af89954872409e1f02909633789c6293a5a9 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:13:36 +0100
Subject: [PATCH 165/270] horizon-server: the lock test waits for a fork-held
 descriptor to close

Tests in the same binary spawn processes (tar, the engine); between fork and exec the child holds a copy
of every open descriptor, the lock's too, so relocking right after drop could see WouldBlock. Seen twice
on CI (#1833, #1895).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-server/src/supervisor.rs | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-server/src/supervisor.rs b/crates/horizon-server/src/supervisor.rs
index 4de011362..f2e811700 100644
--- a/crates/horizon-server/src/supervisor.rs
+++ b/crates/horizon-server/src/supervisor.rs
@@ -849,7 +849,17 @@ mod tests {
         let first = lock(&dir).unwrap();
         assert!(lock(&dir).unwrap_err().contains("already running"));
         drop(first);
-        lock(&dir).unwrap();
+        // A process another test spawns holds a copy of the lock's descriptor between its fork and exec:
+        // the lock comes back once that child has exec'd.
+        let mut again = lock(&dir);
+        for _ in 0..50 {
+            if again.is_ok() {
+                break;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(20));
+            again = lock(&dir);
+        }
+        again.unwrap();
         std::fs::remove_dir_all(&dir).unwrap();
     }
 }

From 481e75bc33bea120cad48a40294fdaf3df2b19aa Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:16:36 +0000
Subject: [PATCH 166/270] Clear off-hand items in vanilla inventory slot order

Co-Authored-By: OpenAI Codex GPT-6.1 <noreply@openai.com>
---
 crates/horizon-client/src/game/commands.rs |  9 ++++++---
 tools/command_exec_corpus.py               | 17 +++++++++++++++++
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index 19a16e261..1f24c8a4f 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -2499,12 +2499,14 @@ impl Game<'_> {
         };
         let max = Self::int(ctx, "maxCount").unwrap_or(-1);
         let counting = max == 0;
-        // Inventory.clearOrCountMatchingItems: main, armor, crafting grid, carried.
+        // Inventory slots 0..40: main, armor feet to head, off hand;
+        // then clearOrCountMatchingItems visits the crafting grid and carried stack.
         let mut removed = 0i32;
         let mut budget = if max < 0 { i32::MAX } else { max };
         let all = |g: &Self| -> Vec<Option<ItemStack>> {
             let mut v: Vec<Option<ItemStack>> = g.inventory.clone();
-            v.extend(g.armor.iter().cloned());
+            v.extend(g.armor.iter().rev().cloned());
+            v.push(g.offhand.clone());
             v.extend(g.craft_grid.iter().cloned());
             v.push(g.carried.clone());
             v
@@ -2518,7 +2520,8 @@ impl Game<'_> {
             .collect();
         let mut slots: Vec<&mut Option<ItemStack>> = Vec::new();
         slots.extend(self.inventory.iter_mut());
-        slots.extend(self.armor.iter_mut());
+        slots.extend(self.armor.iter_mut().rev());
+        slots.push(&mut self.offhand);
         slots.extend(self.craft_grid.iter_mut());
         slots.push(&mut self.carried);
         for (slot, matches) in slots.into_iter().zip(matching) {
diff --git a/tools/command_exec_corpus.py b/tools/command_exec_corpus.py
index 0e376e260..4b24ca80f 100644
--- a/tools/command_exec_corpus.py
+++ b/tools/command_exec_corpus.py
@@ -182,6 +182,23 @@ def player_state():
         cmd('/item modify entity @s weapon.mainhand {type:"minecraft:set_count",count:1}'),
         cmd('/clear @s'),
         cmd('/clear @s'),
+        # Inventory.clearOrCountMatchingItems visits the off hand as well as
+        # the main inventory, and consumes limited clears in inventory-slot order.
+        cmd('/item replace entity @s weapon.offhand with minecraft:shield'),
+        cmd('/clear @s minecraft:shield 0'),
+        cmd('/clear @s minecraft:shield 1'),
+        cmd('/clear @s minecraft:shield 0'),
+        cmd('/item replace entity @s weapon.offhand with minecraft:stone 5'),
+        cmd('/clear @s minecraft:stone 2'),
+        cmd('/clear @s minecraft:stone 0'),
+        cmd('/clear @s'),
+        cmd('/clear @s minecraft:stone 0'),
+        cmd('/item replace entity @s armor.head with minecraft:iron_helmet'),
+        cmd('/item replace entity @s armor.feet with minecraft:iron_boots'),
+        cmd('/clear @s * 1'),
+        cmd('/clear @s minecraft:iron_boots 0'),
+        cmd('/clear @s minecraft:iron_helmet 0'),
+        cmd('/clear @s'),
         cmd('/attribute @s minecraft:max_health get'),
         cmd('/attribute @s minecraft:max_health base get'),
         cmd('/attribute @s minecraft:max_health base set 30'),

From 9c7909f77006d76fda223ecb8396039f2a108188 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:23:55 +0000
Subject: [PATCH 167/270] Advance remote fireballs between server tracker
 updates

Co-Authored-By: OpenAI Codex GPT-6.1 <noreply@openai.com>
---
 crates/horizon-client/src/game/remote.rs      | 23 +++++++
 .../src/game/remote_projectiles.rs            | 20 +++++-
 crates/horizon-client/src/projectiles.rs      | 46 ++++++++++----
 tools/test_remote_fireball_parity.py          | 62 +++++++++++++++++++
 4 files changed, 137 insertions(+), 14 deletions(-)
 create mode 100644 tools/test_remote_fireball_parity.py

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index ba069522c..662a29d18 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1566,6 +1566,22 @@ impl Game<'_> {
                 m.on_ground = on_ground;
                 return;
             }
+            if let Some(p) = self.creatures.projectiles.iter_mut().find(|p| {
+                p.id == id as u32
+                    && matches!(
+                        p.kind,
+                        horizon_client::projectiles::ProjectileKind::LargeFireball { .. }
+                    )
+            }) {
+                if path.is_some() {
+                    p.position = Vec3::new(position[0], position[1], position[2]);
+                }
+                if let Some((yaw, pitch)) = rotation {
+                    p.yaw = yaw;
+                    p.pitch = pitch;
+                }
+                return;
+            }
             if let Some(p) = r.pending_items.get_mut(&id) {
                 p.0 = position;
             }
@@ -3104,6 +3120,13 @@ impl Game<'_> {
             d.velocity = v;
         } else if let Some(f) = self.falling.iter_mut().find(|f| f.id == id as u32) {
             f.velocity = v;
+        } else if let Some(p) = self
+            .creatures
+            .projectiles
+            .iter_mut()
+            .find(|p| p.id == id as u32)
+        {
+            p.velocity = v;
         } else if let Some(p) = self
             .remote
             .as_mut()
diff --git a/crates/horizon-client/src/game/remote_projectiles.rs b/crates/horizon-client/src/game/remote_projectiles.rs
index bc6d0b13e..c7f80ae8e 100644
--- a/crates/horizon-client/src/game/remote_projectiles.rs
+++ b/crates/horizon-client/src/game/remote_projectiles.rs
@@ -207,7 +207,25 @@ impl Game<'_> {
         for p in &mut self.creatures.projectiles {
             p.previous = p.position;
             p.age += 1;
-            p.position = step(p.id, p.position);
+            if matches!(p.kind, ProjectileKind::LargeFireball { .. }) {
+                // AbstractHurtingProjectile.tick advances on the client between
+                // the tracker updates (ten ticks apart for a ghast's fireball).
+                let at = p.position;
+                let water = self
+                    .res
+                    .facts()
+                    .get(self.world.block(
+                        at.x.floor() as i32,
+                        at.y.floor() as i32,
+                        at.z.floor() as i32,
+                    ))
+                    .fluid
+                    == horizon_client::blocks::Fluid::Water;
+                p.apply_hurting_inertia(water);
+                p.position = p.position.add_vector(p.velocity);
+            } else {
+                p.position = step(p.id, p.position);
+            }
         }
         for t in &mut self.tridents {
             let id = t.id;
diff --git a/crates/horizon-client/src/projectiles.rs b/crates/horizon-client/src/projectiles.rs
index 8244da4d9..219d59b6b 100644
--- a/crates/horizon-client/src/projectiles.rs
+++ b/crates/horizon-client/src/projectiles.rs
@@ -572,6 +572,23 @@ impl Projectile {
         }
         (self.position.y > -128.0, Hit::None)
     }
+    /// AbstractHurtingProjectile.applyInertia, on both server and client.
+    pub fn apply_hurting_inertia(&mut self, water: bool) {
+        // WitherSkull.getInertia: 0.73 for dangerous skulls.
+        let inertia = match self.kind {
+            ProjectileKind::WitherSkull { dangerous: true } => 0.73,
+            _ if water => 0.8,
+            _ => 0.95,
+        };
+        let v = self.velocity;
+        let len = (v.x * v.x + v.y * v.y + v.z * v.z).sqrt().max(1.0e-9);
+        self.velocity = Vec3::new(
+            (v.x + v.x / len * self.acceleration) * inertia,
+            (v.y + v.y / len * self.acceleration) * inertia,
+            (v.z + v.z / len * self.acceleration) * inertia,
+        );
+    }
+
     /// One tick: returns whether to keep the projectile and what it hit.
     pub fn tick(&mut self, w: &impl ProjectileWorld) -> (bool, Hit) {
         self.previous = self.position;
@@ -584,19 +601,7 @@ impl Projectile {
             ProjectileKind::SmallFireball
             | ProjectileKind::LargeFireball { .. }
             | ProjectileKind::WitherSkull { .. } => {
-                // WitherSkull.getInertia: 0.73 for dangerous skulls.
-                let inertia = match self.kind {
-                    ProjectileKind::WitherSkull { dangerous: true } => 0.73,
-                    _ if water => 0.8,
-                    _ => 0.95,
-                };
-                let v = self.velocity;
-                let len = (v.x * v.x + v.y * v.y + v.z * v.z).sqrt().max(1.0e-9);
-                self.velocity = Vec3::new(
-                    (v.x + v.x / len * self.acceleration) * inertia,
-                    (v.y + v.y / len * self.acceleration) * inertia,
-                    (v.z + v.z / len * self.acceleration) * inertia,
-                );
+                self.apply_hurting_inertia(water);
             }
             // Arrows tick with `arrows::tick`.
             ProjectileKind::Arrow { .. } => {}
@@ -819,6 +824,21 @@ mod tests {
         // (0.1 + 0.1) * 0.95
         assert!((p.velocity.x - 0.19).abs() < 1e-9);
     }
+
+    #[test]
+    fn fireball_inertia_preserves_custom_acceleration() {
+        let mut p = Projectile::fireball(
+            ProjectileKind::SmallFireball,
+            Vec3::new(0.0, 100.0, 0.0),
+            None,
+            [1.0, 0.0, 0.0],
+        );
+        // A redirected projectile can carry a different acceleration power.
+        p.acceleration = 0.2;
+        p.tick(&Empty(vec![]));
+        assert!((p.velocity.x - 0.285).abs() < 1e-9);
+        assert!((p.position.x - 0.285).abs() < 1e-9);
+    }
 }
 
 #[cfg(test)]
diff --git a/tools/test_remote_fireball_parity.py b/tools/test_remote_fireball_parity.py
new file mode 100644
index 000000000..7e60ff30a
--- /dev/null
+++ b/tools/test_remote_fireball_parity.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""A connected client advances ghast fireballs between tracker packets.
+
+AbstractHurtingProjectile.tick/applyInertia run on clients as well as servers.
+Like lan_e2e's falling-entity check, sample motion more often than the tracker
+interval; an interpolation-only client stalls for most of that interval.
+"""
+import json
+import math
+import subprocess
+
+import lab
+import lan_e2e as lan
+
+
+def check_motion(host, guest, out):
+    x, y, z = (math.floor(v) for v in lan.pos_of(guest))
+    for game in (host, guest):
+        game('command', command='gamemode creative')
+    tag = 'remote_fireball_parity'
+    host('command', command=f'fill {x + 2} {y + 18} {z - 1} {x + 48} {y + 23} {z + 1} minecraft:air')
+    host('command', command=f'summon minecraft:fireball {x + 3.5} {y + 20} {z + 0.5} '
+                            f'{{Tags:["{tag}"],Motion:[0.1d,0.0d,0.0d]}}')
+    samples = []
+    try:
+        for _ in range(8):
+            balls = [p for p in guest('status')['projectiles'] if p['kind'] == 'LargeFireball']
+            samples.append(balls[0]['position'][0] if balls else None)
+            guest.wait(2)
+    finally:
+        host('command', command=f'kill @e[tag={tag}]')
+    seen = [p for p in samples if p is not None]
+    assert len(seen) >= 6, f'fireball visible in only {len(seen)} samples: {samples}'
+    moves = sum(b != a for a, b in zip(seen, seen[1:]))
+    assert moves >= len(seen) - 2, f'fireball stalled between tracker updates: {samples}'
+    return {'positions': samples}
+
+
+def main():
+    subprocess.run(['cargo', 'build', '--locked', '--profile', 'fast', '-p', 'horizon-client',
+                    '--bin', 'horizon-client', '--bin', 'horizon-ctl'], cwd=lab.ROOT, check=True)
+    metadata = json.loads(subprocess.check_output(
+        ['cargo', 'metadata', '--format-version', '1', '--no-deps'], cwd=lab.ROOT, text=True))
+    ctl = lab.ROOT / metadata['target_directory'] / 'fast' / 'horizon-ctl'
+    lan.CHECK_FNS['remote-fireball'] = check_motion
+    # Use the runner's current display (xvfb on Linux), with fresh isolated homes.
+    lan.game_env = lambda _screen, home: lab.game_env(
+        HORIZON_HOME=home, HORIZON_TELEMETRY_URL='off')
+    reports = {}
+    for threaded in (True, False):
+        lan.SERVER_THREAD = threaded
+        mode = 'server-thread' if threaded else 'in-frame'
+        out = lab.LOCAL / 'remote-fireball-parity' / mode
+        out.mkdir(parents=True, exist_ok=True)
+        # lan.Game launches each client with lab.game_env and private scratch homes.
+        reports[mode] = lan.run(ctl, out, lab.RESOURCES.resolve(), ['remote-fireball'])
+    lab.write_json(lab.LOCAL / 'remote-fireball-parity' / 'report.json', reports)
+    assert all(r['pass'] for mode in reports.values() for r in mode.values()), reports
+
+
+if __name__ == '__main__':
+    main()

From 84a3f1ee1832967b8d1eed3b55dfae767efaeee9 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:30:34 +0000
Subject: [PATCH 168/270] Emit sculk movement events for each server player

Co-Authored-By: OpenAI Codex GPT-6.1 <noreply@openai.com>
---
 crates/horizon-client/src/game/lan_actions.rs |  5 ++
 crates/horizon-client/src/game/sculk.rs       | 25 +++++-
 tools/test_server_player_sculk_parity.py      | 87 +++++++++++++++++++
 3 files changed, 116 insertions(+), 1 deletion(-)
 create mode 100644 tools/test_server_player_sculk_parity.py

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 18f529184..b8c161428 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -84,6 +84,7 @@ pub(super) struct GuestPlay {
     equipped: Option<Vec<Option<ItemStack>>>,
     /// The guest's cast fishing hook (`Player.fishing`).
     pub(super) hook: Option<super::fishing::Hook>,
+    sculk: super::sculk::PlayerEvents,
 }
 
 /// A guest's command waiting for the hub (`LanHost::commands`).
@@ -250,6 +251,7 @@ impl Game<'_> {
         if fresh {
             // A new body (joined, respawned, changed level): nothing on it yet.
             play.equipped = None;
+            play.sculk = Default::default();
         }
         let g = &mut host.hub.guests[i];
         // The guest's body.
@@ -257,6 +259,7 @@ impl Game<'_> {
             host.play.insert(conn, play);
             return None;
         };
+        self.sculk.swap_player(&mut play.sculk);
         self.potions.swap_player(&mut g.effects, &mut play.potions);
         motion.position = Vec3::new(g.position[0], g.position[1], g.position[2]);
         motion.ground.on_ground = g.on_ground;
@@ -478,6 +481,7 @@ impl Game<'_> {
             projectiles,
             modifiers,
         } = swap;
+        self.sculk.swap_player(&mut play.sculk);
         play.modifiers = std::mem::replace(&mut self.applied_modifiers, modifiers);
         // What the guest shot is theirs (Projectile.setOwner).
         for p in self.creatures.projectiles.iter_mut().skip(projectiles) {
@@ -2095,6 +2099,7 @@ impl Game<'_> {
         let Some((events, marked)) = events else {
             return;
         };
+        self.as_guest(host, conn, |game| game.tick_player_sculk_events());
         for event in events {
             match event {
                 MotionEvent::HurtSound(sound) => self.player_hurt_sound(sound, at),
diff --git a/crates/horizon-client/src/game/sculk.rs b/crates/horizon-client/src/game/sculk.rs
index a11a643c1..84e3d5cb2 100644
--- a/crates/horizon-client/src/game/sculk.rs
+++ b/crates/horizon-client/src/game/sculk.rs
@@ -63,6 +63,12 @@ struct Steps {
     on_ground: bool,
     in_water: bool,
 }
+#[derive(Default)]
+pub(super) struct PlayerEvents {
+    steps: Option<Steps>,
+    last_health: Option<f32>,
+}
+
 #[derive(Default)]
 pub(super) struct SculkState {
     /// The player's warning level toward a warden.
@@ -86,6 +92,15 @@ pub(super) struct SculkState {
 }
 
 impl SculkState {
+    pub(super) fn swap_player(&mut self, other: &mut PlayerEvents) {
+        let steps = self.steps.remove(&Who::Player);
+        if let Some(guest) = other.steps.take() {
+            self.steps.insert(Who::Player, guest);
+        }
+        other.steps = steps;
+        std::mem::swap(&mut self.last_health, &mut other.last_health);
+    }
+
     /// Exchange the level-held parts (its sculk block entities and the
     /// chunks scanned for them) with another level's (game/levels.rs).
     pub(super) fn swap_level(&mut self, other: &mut Self) {
@@ -1491,6 +1506,12 @@ impl Game<'_> {
     /// Events from entities moving, getting hurt and dying, derived from what
     /// changed this tick.
     fn tick_entity_events(&mut self) {
+        self.tick_player_sculk_events();
+        self.tick_mob_sculk_events();
+    }
+
+    /// Entity.move emits on the authoritative server too, for each ServerPlayer.
+    pub(super) fn tick_player_sculk_events(&mut self) {
         // The player.
         let player = self.player.as_ref().map(|p| {
             (
@@ -1518,7 +1539,9 @@ impl Game<'_> {
             }
             self.sculk.last_health = Some(health);
         }
-        // Mobs.
+    }
+
+    fn tick_mob_sculk_events(&mut self) {
         let snapshot: Vec<(u32, [f64; 3], bool, bool, Species, Option<i64>)> = self
             .mobs
             .iter()
diff --git a/tools/test_server_player_sculk_parity.py b/tools/test_server_player_sculk_parity.py
new file mode 100644
index 000000000..33489ad5a
--- /dev/null
+++ b/tools/test_server_player_sculk_parity.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Both players' ordinary walking activates a sculk sensor on the server.
+
+Exercise Entity.move movement emission through real client input, alongside
+sculk's deterministic vanilla oracle. Check the integrated-server and in-frame
+hosts: the guest always uses the server-player path.
+"""
+import json
+import math
+import subprocess
+
+import lab
+import lan_e2e as lan
+
+
+def until(game, observe, predicate, ticks=100):
+    value = observe()
+    for _ in range(ticks):
+        if predicate(value):
+            return value
+        game.wait(1)
+        value = observe()
+    assert predicate(value), value
+    return value
+
+
+def check_walk(host, guest, out, role):
+    player = host if role == 'host' else guest
+    hx, y, hz = (math.floor(v) for v in lan.pos_of(host))
+    x, z = hx + 6, hz + (-8 if role == 'host' else 8)
+    sensor = (x + 3, y, z + 1)
+    player('command', command='gamemode survival')
+    host('command', command=f'fill {x - 2} {y - 1} {z - 2} {x + 5} {y - 1} {z + 5} minecraft:stone')
+    host('command', command=f'fill {x - 2} {y} {z - 2} {x + 5} {y + 3} {z + 5} minecraft:air')
+    start = (x + 0.5, y, z + 0.5)
+    player('command', command=f'tp @s {start[0]} {start[1]} {start[2]} 0 0')
+    until(player, lambda: lan.pos_of(player), lambda p: math.dist(p, start) < 0.1)
+    player.raw('look', 0, 0)
+    player.wait(2)
+    host('command', command=f'setblock {sensor[0]} {sensor[1]} {sensor[2]} minecraft:sculk_sensor')
+    phase = lambda game: game.raw('getblock', *sensor)['block']
+    try:
+        until(host, lambda: phase(host), lambda s: 'sculk_sensor_phase=inactive' in s)
+        player.wait(10)
+        assert 'sculk_sensor_phase=inactive' in phase(host), 'setup activated the sensor'
+        player.raw('key', 'w', 'down')
+        try:
+            player.wait(15)
+        finally:
+            player.raw('key', 'w', 'up')
+        moved = {'client': math.dist(lan.pos_of(player), start),
+                 'server': math.dist(lan.server_player(host, player)['position'], start)}
+        assert all(d > 1 for d in moved.values()), moved
+        for viewer in (host, guest):
+            until(viewer, lambda: phase(viewer), lambda s: 'sculk_sensor_phase=active' in s, ticks=85)
+        return {'moved': moved, 'phase': phase(host)}
+    finally:
+        player.raw('key', 'w', 'up')
+        host('command', command=f'fill {x - 2} {y} {z - 2} {x + 5} {y + 3} {z + 5} minecraft:air')
+
+
+def main():
+    subprocess.run(['cargo', 'build', '--locked', '--profile', 'fast', '-p', 'horizon-client',
+                    '--bin', 'horizon-client', '--bin', 'horizon-ctl'], cwd=lab.ROOT, check=True)
+    metadata = json.loads(subprocess.check_output(
+        ['cargo', 'metadata', '--format-version', '1', '--no-deps'], cwd=lab.ROOT, text=True))
+    ctl = lab.ROOT / metadata['target_directory'] / 'fast' / 'horizon-ctl'
+    checks = ['sculk-walk-host', 'sculk-walk-guest']
+    for role, name in zip(('host', 'guest'), checks):
+        lan.CHECK_FNS[name] = lambda h, g, o, role=role: check_walk(h, g, o, role)
+    # Use the runner's current display (xvfb on Linux), with fresh isolated homes.
+    lan.game_env = lambda _screen, home: lab.game_env(
+        HORIZON_HOME=home, HORIZON_TELEMETRY_URL='off')
+    reports = {}
+    for threaded in (True, False):
+        lan.SERVER_THREAD = threaded
+        mode = 'server-thread' if threaded else 'in-frame'
+        out = lab.LOCAL / 'server-player-sculk-parity' / mode
+        out.mkdir(parents=True, exist_ok=True)
+        # lan.Game launches each client with lab.game_env and private scratch homes.
+        reports[mode] = lan.run(ctl, out, lab.RESOURCES.resolve(), checks)
+    lab.write_json(lab.LOCAL / 'server-player-sculk-parity' / 'report.json', reports)
+    assert all(r['pass'] for mode in reports.values() for r in mode.values()), reports
+
+
+if __name__ == '__main__':
+    main()

From 89d6e1c2a50112cb6d65de4cbfbe8af094ea5952 Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:34:39 -0300
Subject: [PATCH 169/270] Structure chests keep the enchantments their loot
 rolled

The loot rolls carry enchantments and potions (horizon_world::loot runs
enchant_with_levels, enchant_randomly and set_potion), but chests filled
when a structure is placed, and mineshaft chest minecarts, turned each
LootStack into an item with loot_item, which keeps only the item, count,
damage and exploration map. End city gear came out bare. Both now use
loot_item_with_components, as vaults, trial spawners and decorated pots
already do.

Fixes #1437.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/structure_blocks.rs | 53 +++++++++++++++----
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/crates/horizon-client/src/structure_blocks.rs b/crates/horizon-client/src/structure_blocks.rs
index 1e1906f6d..427323c23 100644
--- a/crates/horizon-client/src/structure_blocks.rs
+++ b/crates/horizon-client/src/structure_blocks.rs
@@ -165,14 +165,10 @@ pub fn block_entities(
                 .iter_mut()
                 .zip(loot.fill(&table, seed, 27, Some(biome)))
             {
-                *slot = stack.map(|s| {
-                    let mut item = loot_item(&s);
-                    // An ominous bottle's level (the default, 0, is no component).
-                    if let Some(level) = s.ominous_amplifier.filter(|l| *l > 0) {
-                        item.data_mut().ominous_amplifier = Some(level.clamp(0, 4) as u8);
-                    }
-                    item
-                });
+                // With what the rolls put on them: enchantments
+                // (enchant_with_levels in End city chests), potions and an
+                // ominous bottle's level.
+                *slot = stack.map(|s| loot_item_with_components(&s));
             }
         }
         out.push(((x, y, z), entity));
@@ -211,7 +207,7 @@ pub fn unpack_entity_loot(
     let slots: Vec<Option<ItemStack>> = loot
         .fill(&table, seed, 27, Some(biome))
         .into_iter()
-        .map(|s| s.map(|s| loot_item(&s)))
+        .map(|s| s.map(|s| loot_item_with_components(&s)))
         .collect();
     nbt.remove(&JavaString::from("LootTable"));
     nbt.remove(&JavaString::from("LootTableSeed"));
@@ -224,6 +220,45 @@ mod tests {
     use super::*;
     use horizon_world::loot::{ExplorationMap, LootStack};
 
+    #[test]
+    fn placed_chest_loot_keeps_its_enchantments_and_potions() {
+        let stack =
+            |item: &str, enchantments: Vec<(String, i32)>, potion: Option<&str>| LootStack {
+                item: item.into(),
+                count: 1,
+                damage: 0,
+                enchantments,
+                potion: potion.map(str::to_owned),
+                map: false,
+                exploration: None,
+                ominous_amplifier: None,
+            };
+        // An End city chest's enchant_with_levels roll.
+        let boots = loot_item_with_components(&stack(
+            "minecraft:diamond_boots",
+            vec![
+                ("minecraft:protection".into(), 3),
+                ("minecraft:unbreaking".into(), 2),
+            ],
+            None,
+        ));
+        assert_eq!(boots.enchantments().len(), 2);
+        // A book's go into stored_enchantments.
+        let book = loot_item_with_components(&stack(
+            "minecraft:enchanted_book",
+            vec![("minecraft:mending".into(), 1)],
+            None,
+        ));
+        assert!(book.enchantments().is_empty());
+        assert_eq!(book.stored_enchantments().len(), 1);
+        let arrow = loot_item_with_components(&stack(
+            "minecraft:tipped_arrow",
+            Vec::new(),
+            Some("minecraft:slowness"),
+        ));
+        assert_eq!(arrow.potion(), Some("minecraft:slowness"));
+    }
+
     #[test]
     fn exploration_maps_wait_in_custom_data_until_searched() {
         let mut stack = LootStack {

From 4459f132fe481be02ed0c2a2e2e41b7666ba3dbe Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:44:09 +0100
Subject: [PATCH 170/270] Collision scans: skip the outer cells of sections no
 block reaches out of

BlockCollisions keeps a block on the cells around the box (Cursor3D types 1
and 2) only if it has a large collision shape or is a moving piston. Most
sections hold neither in their palette, so the scan now asks the provider
once per section and passes those cells without reading them: a mob's box
reads about a fifth of the cells it did. Same hits, same order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/collisions.rs       |  18 +++
 crates/horizon-world/src/block_collision.rs   |   7 ++
 .../horizon-world/src/block_collision_scan.rs |  31 +++++
 .../tests/block_collision_scan.rs             | 107 +++++++++++++-----
 4 files changed, 136 insertions(+), 27 deletions(-)

diff --git a/crates/horizon-client/src/collisions.rs b/crates/horizon-client/src/collisions.rs
index 3ff2cfdd6..7c32bd829 100644
--- a/crates/horizon-client/src/collisions.rs
+++ b/crates/horizon-client/src/collisions.rs
@@ -92,6 +92,13 @@ impl<W: BlockCollisionWorld> BlockCollisionWorld for EntityCollisions<'_, W> {
     ) -> std::result::Result<bool, Self::Error> {
         self.blocks.is_suffocating(chunk, block, p)
     }
+    fn may_reach_out(
+        &mut self,
+        chunk: Self::Chunk,
+        section_y: i32,
+    ) -> std::result::Result<bool, Self::Error> {
+        self.blocks.may_reach_out(chunk, section_y)
+    }
     fn context_shape(
         &mut self,
         block: CollisionBlock,
@@ -262,6 +269,17 @@ impl<'w> BlockCollisionWorld for SceneCollisions<'w, '_> {
     fn collision_block(&mut self, chunk: Self::Chunk, p: BlockPos) -> io::Result<CollisionBlock> {
         self.binding.collision_block(chunk.block(p.x, p.y, p.z))
     }
+    /// From the section's palette, without reading its blocks; a palette
+    /// of the whole registry reads every cell.
+    fn may_reach_out(&mut self, chunk: Self::Chunk, section_y: i32) -> io::Result<bool> {
+        let blocks = usize::try_from(section_y - (crate::chunk::MIN_Y >> 4))
+            .ok()
+            .and_then(|s| chunk.sections.get(s))
+            .map(|section| &section.blocks);
+        Ok(blocks.is_none_or(|blocks| {
+            blocks.is_global() || blocks.maybe_has(|v| self.binding.reaches_out(BlockStateId(v)))
+        }))
+    }
     fn is_suffocating(
         &mut self,
         _: Self::Chunk,
diff --git a/crates/horizon-world/src/block_collision.rs b/crates/horizon-world/src/block_collision.rs
index 3770a1a0f..9e2d81b78 100644
--- a/crates/horizon-world/src/block_collision.rs
+++ b/crates/horizon-world/src/block_collision.rs
@@ -158,6 +158,13 @@ impl<'r> BlockCollisionRegistry<'r> {
             empty_shape: flags & 4 != 0,
         })
     }
+    /// Whether a scan keeps `state` in the cells around its box: a large
+    /// collision shape or a moving piston. States outside the registry count.
+    pub fn reaches_out(&self, state: BlockStateId) -> bool {
+        self.scan_flags
+            .get(state.0 as usize)
+            .is_none_or(|flags| flags & 3 != 0)
+    }
     pub fn collision_shape<W: DynamicCollisionWorld>(
         &self,
         world: &mut W,
diff --git a/crates/horizon-world/src/block_collision_scan.rs b/crates/horizon-world/src/block_collision_scan.rs
index 6c26c6631..391c3e96e 100644
--- a/crates/horizon-world/src/block_collision_scan.rs
+++ b/crates/horizon-world/src/block_collision_scan.rs
@@ -41,6 +41,13 @@ pub trait BlockCollisionWorld {
         position: BlockPos,
         context: &CollisionContext<'_>,
     ) -> Result<VoxelShape, Self::Error>;
+    /// Whether a block of the chunk's section `section_y` (block y >> 4) may
+    /// have a large collision shape or be a moving piston: the only blocks
+    /// the scan keeps outside the box's own cells. False lets the scan pass
+    /// that section's outer cells without reading them; true reads them all.
+    fn may_reach_out(&mut self, _chunk: Self::Chunk, _section_y: i32) -> Result<bool, Self::Error> {
+        Ok(true)
+    }
 }
 
 #[derive(Debug)]
@@ -88,6 +95,8 @@ pub struct BlockCollisionScan<'w, 'c, W: BlockCollisionWorld> {
     count: usize,
     budget: usize,
     chunk: Option<(ChunkPos, W::Chunk)>,
+    /// `may_reach_out` of the last section an outer cell was in.
+    reach: Option<(ChunkPos, i32, bool)>,
     failed: bool,
 }
 impl<'w, 'c, W: BlockCollisionWorld> BlockCollisionScan<'w, 'c, W> {
@@ -137,6 +146,7 @@ impl<'w, 'c, W: BlockCollisionWorld> BlockCollisionScan<'w, 'c, W> {
             count,
             budget: candidate_budget,
             chunk: None,
+            reach: None,
             failed: false,
         })
     }
@@ -184,6 +194,27 @@ impl<'w, 'c, W: BlockCollisionWorld> BlockCollisionScan<'w, 'c, W> {
             let Some(chunk) = chunk else {
                 continue;
             };
+            // An outer cell only counts for a block reaching out of its own
+            // cell: most sections hold none, so their outer cells go unread
+            // (the result is the same, with a fifth of the block reads for a
+            // mob's box).
+            if kind != 0 {
+                let section_y = p.y >> 4;
+                let reaches = match self.reach {
+                    Some((at, y, reaches)) if at == chunk_position && y == section_y => reaches,
+                    _ => {
+                        let reaches = self
+                            .world
+                            .may_reach_out(chunk, section_y)
+                            .map_err(CollisionScanError::World)?;
+                        self.reach = Some((chunk_position, section_y, reaches));
+                        reaches
+                    }
+                };
+                if !reaches {
+                    continue;
+                }
+            }
             let block = self
                 .world
                 .collision_block(chunk, p)
diff --git a/crates/horizon-world/tests/block_collision_scan.rs b/crates/horizon-world/tests/block_collision_scan.rs
index 32735f826..adf530069 100644
--- a/crates/horizon-world/tests/block_collision_scan.rs
+++ b/crates/horizon-world/tests/block_collision_scan.rs
@@ -112,6 +112,8 @@ fn invalid_or_excessive_domains_fail_before_world_queries() {
 /// and has an empty shape.
 struct Recording {
     cells: Vec<BlockPos>,
+    /// Sections (block y >> 4) whose blocks never reach out of their cell.
+    contained: Vec<i32>,
 }
 impl BlockCollisionWorld for Recording {
     type Error = io::Error;
@@ -139,6 +141,40 @@ impl BlockCollisionWorld for Recording {
     ) -> io::Result<VoxelShape> {
         unreachable!()
     }
+    fn may_reach_out(&mut self, _: (), section_y: i32) -> io::Result<bool> {
+        Ok(!self.contained.contains(&section_y))
+    }
+}
+
+/// The cells the scan reads for `bounds` (Cursor3D order: x fastest, then
+/// y, then z, without the 8 corners), less the outer cells of `contained`.
+fn expected_cells(bounds: Aabb, contained: &[i32]) -> Vec<BlockPos> {
+    let (min, max) = (bounds.min_position(), bounds.max_position());
+    let start = BlockPos::containing(Vec3::new(min.x - 1.0e-7, min.y - 1.0e-7, min.z - 1.0e-7))
+        .offset(-1, -1, -1);
+    let end = BlockPos::containing(Vec3::new(max.x + 1.0e-7, max.y + 1.0e-7, max.z + 1.0e-7))
+        .offset(1, 1, 1);
+    let sizes = [
+        end.x - start.x + 1,
+        end.y - start.y + 1,
+        end.z - start.z + 1,
+    ];
+    let mut expected = Vec::new();
+    for i in 0..sizes[0] * sizes[1] * sizes[2] {
+        let r = [
+            i % sizes[0],
+            i / sizes[0] % sizes[1],
+            i / sizes[0] / sizes[1],
+        ];
+        let edges = (0..3)
+            .filter(|&a| r[a] == 0 || r[a] == sizes[a] - 1)
+            .count();
+        let p = start.offset(r[0], r[1], r[2]);
+        if edges < 3 && (edges == 0 || !contained.contains(&(p.y >> 4))) {
+            expected.push(p);
+        }
+    }
+    expected
 }
 
 #[test]
@@ -150,7 +186,10 @@ fn cells_follow_the_cursor_order_without_corners() {
         Aabb::new(Vec3::new(-0.3, 0.0, -0.3), Vec3::new(0.3, 0.9, 0.3)),
     ];
     for bounds in boxes {
-        let mut world = Recording { cells: Vec::new() };
+        let mut world = Recording {
+            cells: Vec::new(),
+            contained: Vec::new(),
+        };
         let hits = BlockCollisionScan::new(
             &mut world,
             CollisionContext::empty(false),
@@ -161,31 +200,45 @@ fn cells_follow_the_cursor_order_without_corners() {
         .unwrap()
         .count();
         assert_eq!(hits, 0);
-        // Cursor3D: x fastest, then y, then z, skipping the 8 corners.
-        let (min, max) = (bounds.min_position(), bounds.max_position());
-        let start = BlockPos::containing(Vec3::new(min.x - 1.0e-7, min.y - 1.0e-7, min.z - 1.0e-7))
-            .offset(-1, -1, -1);
-        let end = BlockPos::containing(Vec3::new(max.x + 1.0e-7, max.y + 1.0e-7, max.z + 1.0e-7))
-            .offset(1, 1, 1);
-        let sizes = [
-            end.x - start.x + 1,
-            end.y - start.y + 1,
-            end.z - start.z + 1,
-        ];
-        let mut expected = Vec::new();
-        for i in 0..sizes[0] * sizes[1] * sizes[2] {
-            let r = [
-                i % sizes[0],
-                i / sizes[0] % sizes[1],
-                i / sizes[0] / sizes[1],
-            ];
-            let edges = (0..3)
-                .filter(|&a| r[a] == 0 || r[a] == sizes[a] - 1)
-                .count();
-            if edges < 3 {
-                expected.push(start.offset(r[0], r[1], r[2]));
-            }
-        }
-        assert_eq!(world.cells, expected);
+        assert_eq!(world.cells, expected_cells(bounds, &[]));
+    }
+}
+
+/// Outer cells are read only in sections that may hold a block reaching
+/// out of its cell; the box's own cells always are.
+#[test]
+fn outer_cells_of_contained_sections_are_not_read() {
+    // A mob crossing from section 3 into section 4, and an item in section 0.
+    let boxes = [
+        (
+            Aabb::new(Vec3::new(0.2, 63.5, 0.3), Vec3::new(0.8, 65.3, 0.9)),
+            vec![3],
+        ),
+        (
+            Aabb::new(Vec3::new(0.2, 63.5, 0.3), Vec3::new(0.8, 65.3, 0.9)),
+            vec![3, 4],
+        ),
+        (
+            Aabb::new(Vec3::new(4.4, 2.0, -7.6), Vec3::new(4.65, 2.25, -7.35)),
+            vec![0],
+        ),
+    ];
+    for (bounds, contained) in boxes {
+        let mut world = Recording {
+            cells: Vec::new(),
+            contained: contained.clone(),
+        };
+        let hits = BlockCollisionScan::new(
+            &mut world,
+            CollisionContext::empty(false),
+            bounds,
+            false,
+            1_000_000,
+        )
+        .unwrap()
+        .count();
+        assert_eq!(hits, 0);
+        assert_eq!(world.cells, expected_cells(bounds, &contained));
+        assert!(world.cells.len() < expected_cells(bounds, &[]).len());
     }
 }

From bb9c474c643f45ba551899bfe24ea360daeb2e6e Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:48:58 +0500
Subject: [PATCH 171/270] End city banners keep their template patterns

A structure template saves a banner's layers in its block entity NBT, and
StructureTemplate.placeInWorld hands that NBT to the level, where
BannerBlockEntity.loadAdditional reads `patterns`. Horizon built the client
block entity from the block alone (BlockEntity::for_block), so the End
cities' magenta banners came out bare.

Fixes #1438.

Co-Authored-By: [CC] <deepseek-v4.1-flash> <noreply@deepseek.com>
---
 crates/horizon-client/src/structure_blocks.rs | 89 ++++++++++++++++---
 1 file changed, 78 insertions(+), 11 deletions(-)

diff --git a/crates/horizon-client/src/structure_blocks.rs b/crates/horizon-client/src/structure_blocks.rs
index 1e1906f6d..da5b75258 100644
--- a/crates/horizon-client/src/structure_blocks.rs
+++ b/crates/horizon-client/src/structure_blocks.rs
@@ -128,6 +128,44 @@ fn text(nbt: &Compound, key: &str) -> Option<String> {
     }
 }
 
+/// `BannerBlockEntity.loadAdditional`: the `patterns` layers and the custom
+/// name a structure template saves with its banner (the End cities' tower
+/// tops place black triangles this way).
+fn banner_from_nbt(nbt: &Compound) -> crate::containers::Banner {
+    crate::containers::Banner {
+        layers: crate::banner::layers_from_nbt(nbt.get(&JavaString::from("patterns"))),
+        name: text(nbt, "CustomName"),
+        components: match nbt.get(&JavaString::from("components")) {
+            Some(Tag::Compound(c)) => c.clone(),
+            _ => Compound::new(),
+        },
+    }
+}
+
+/// The client block entity for one of a chunk's generated block entities,
+/// before a container's loot is unpacked.
+fn generated_block_entity(block: &str, nbt: &Compound) -> Option<BlockEntity> {
+    let mut entity = BlockEntity::for_block(block)?;
+    let tag = Tag::Compound(nbt.clone());
+    // MonsterRoomFeature and the structures' setEntityId.
+    if let BlockEntity::Spawner(s) = &mut entity {
+        **s = crate::mobs::spawner::Spawner::load(&tag);
+    }
+    if let BlockEntity::TrialSpawner(s) = &mut entity {
+        **s = crate::mobs::trial_spawner::TrialSpawner::load(&tag);
+    }
+    if let BlockEntity::Vault(v) = &mut entity {
+        **v = crate::vault::Vault::load(&tag);
+    }
+    // StructureTemplate.placeInWorld hands the template's block entity NBT to
+    // the level, so `BannerBlockEntity.loadAdditional` keeps the banner's
+    // patterns (the End cities' black triangles) and its name.
+    if let BlockEntity::Banner(b) = &mut entity {
+        *b = banner_from_nbt(nbt);
+    }
+    Some(entity)
+}
+
 /// Client block entities for the generated block entities of a chunk.
 pub fn block_entities(
     chunk: &ProtoChunk,
@@ -137,19 +175,9 @@ pub fn block_entities(
     for (pos, nbt) in &chunk.block_entities {
         let [x, y, z] = *pos;
         let block = chunk.block_name(x, y, z);
-        let Some(mut entity) = BlockEntity::for_block(block) else {
+        let Some(mut entity) = generated_block_entity(block, nbt) else {
             continue;
         };
-        // MonsterRoomFeature and the structures' setEntityId.
-        if let BlockEntity::Spawner(s) = &mut entity {
-            **s = crate::mobs::spawner::Spawner::load(&Tag::Compound(nbt.clone()));
-        }
-        if let BlockEntity::TrialSpawner(s) = &mut entity {
-            **s = crate::mobs::trial_spawner::TrialSpawner::load(&Tag::Compound(nbt.clone()));
-        }
-        if let BlockEntity::Vault(v) = &mut entity {
-            **v = crate::vault::Vault::load(&Tag::Compound(nbt.clone()));
-        }
         if let (BlockEntity::Chest(slots), Some(table), Some(loot)) =
             (&mut entity, text(nbt, "LootTable"), loot)
         {
@@ -278,4 +306,43 @@ mod tests {
         stack.exploration = None;
         assert!(!has_pending_map(&loot_item(&stack)));
     }
+
+    /// The End cities' tower tops save their banners' patterns in the
+    /// template; the placed banner must keep them (`EndCityPieces`).
+    #[test]
+    fn a_generated_banner_keeps_its_template_patterns() {
+        let patterns = Tag::List(vec![
+            Tag::compound([
+                ("color", Tag::String("black".into())),
+                ("pattern", Tag::String("minecraft:triangle_top".into())),
+            ]),
+            Tag::compound([
+                ("color", Tag::String("black".into())),
+                ("pattern", Tag::String("minecraft:triangle_bottom".into())),
+            ]),
+        ]);
+        let nbt = Tag::compound([
+            ("id", Tag::String("minecraft:banner".into())),
+            ("patterns", patterns),
+        ]);
+        let Tag::Compound(nbt) = nbt else {
+            unreachable!()
+        };
+        let Some(BlockEntity::Banner(banner)) =
+            generated_block_entity("minecraft:magenta_banner", &nbt)
+        else {
+            panic!("a banner block makes a banner block entity");
+        };
+        assert_eq!(banner.layers.len(), 2);
+        assert_eq!(&*banner.layers[0].pattern, "minecraft:triangle_top");
+        assert_eq!(&*banner.layers[1].pattern, "minecraft:triangle_bottom");
+        assert_eq!(&*banner.layers[0].color, "black");
+        // A banner the template saved without patterns stays bare.
+        let Some(BlockEntity::Banner(bare)) =
+            generated_block_entity("minecraft:white_banner", &Compound::new())
+        else {
+            panic!("a banner block makes a banner block entity");
+        };
+        assert!(bare.layers.is_empty());
+    }
 }

From 200b756b4ae2cbd0cce186d1b4db8041805c9ac1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:53:31 +0100
Subject: [PATCH 172/270] Sculk: pass over idle sensors and catalysts in the
 block entity tick

A sculk sensor, shrieker or catalyst with no vibration chosen, travelling or
waiting, and no charge cursors, ticks without changing anything (vanilla's
VibrationSystem.Ticker.tick and SculkSpreader.updateCursors return at once).
The tick now leaves those out before asking whether the chunks around them
tick (nine lookups each) and before looking them up a second time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/sculk.rs | 17 ++++++++++++-----
 crates/horizon-client/src/sculk.rs      |  7 +++++++
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/game/sculk.rs b/crates/horizon-client/src/game/sculk.rs
index a11a643c1..63909c592 100644
--- a/crates/horizon-client/src/game/sculk.rs
+++ b/crates/horizon-client/src/game/sculk.rs
@@ -718,17 +718,24 @@ impl Game<'_> {
             })
         };
         // The ticking ones in the index's order, with whether the chunks
-        // around them tick too.
+        // around them tick too. Most sensors and catalysts wait for a
+        // vibration or a death: their tick would change nothing, so they
+        // are passed over here (a vibration scheduled during these ticks is
+        // chosen on the next tick at the earliest, as in vanilla).
+        let entities = &self.world.block_entities;
         let due: Vec<((i32, i32, i32), bool)> = self
             .sculk
             .index
             .iter()
             .filter_map(|&key| {
                 let (cx, cz) = (key.0 >> 4, key.2 >> 4);
-                ticks(cx, cz).then(|| {
-                    let adjacent = (-1..=1).all(|dx| (-1..=1).all(|dz| ticks(cx + dx, cz + dz)));
-                    (key, adjacent)
-                })
+                if !ticks(cx, cz)
+                    || matches!(entities.get(&key), Some(BlockEntity::Sculk(e)) if e.idle())
+                {
+                    return None;
+                }
+                let adjacent = (-1..=1).all(|dx| (-1..=1).all(|dz| ticks(cx + dx, cz + dz)));
+                Some((key, adjacent))
             })
             .collect();
         for (key, adjacent) in due {
diff --git a/crates/horizon-client/src/sculk.rs b/crates/horizon-client/src/sculk.rs
index 3affbda77..eefedaa98 100644
--- a/crates/horizon-client/src/sculk.rs
+++ b/crates/horizon-client/src/sculk.rs
@@ -413,6 +413,13 @@ impl SculkEntity {
             spreader: SculkSpreader::default(),
         }
     }
+    /// Whether its block entity tick does nothing: no vibration chosen
+    /// or on its way, none waiting to be chosen, and no charge to spread.
+    pub fn idle(&self) -> bool {
+        self.vibration.current.is_none()
+            && self.vibration.selector.current().is_none()
+            && self.spreader.cursors.is_empty()
+    }
     pub fn for_block(name: &str) -> Option<Self> {
         Some(Self::new(match name {
             "minecraft:sculk_sensor" => SculkKind::Sensor,

From 05396b4edfd63209708ecbf767e0b93eea272272 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:57:10 +0100
Subject: [PATCH 173/270] ui: experimental, opted into with experimental =
 ["ui"] in the manifest

docs/api/stability.md: a new API starts experimental, usable only by
opting in with a manifest field naming it. Capability ui now needs
experimental = ["ui"] beside capabilities; without it the manifest is
refused with that line to add. A capability promoted later stays
accepted in the list, so such manifests keep loading.

The ui test guest opts in; stability.md gets ui's row; docs/mods.md
shows the key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-mods/src/manifest.rs  | 38 ++++++++++++++++++++++++++++
 crates/horizon-mods/tests/sandbox.rs |  1 +
 docs/api/stability.md                |  1 +
 docs/mods.md                         |  7 +++--
 4 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index f1ac123b1..6070f99bd 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -49,6 +49,12 @@ pub struct Manifest {
     /// that are on may share one (`content::clash`).
     #[serde(default)]
     pub namespaces: Vec<String>,
+    /// The experimental capabilities the mod opts into (`["ui"]`): each one
+    /// it lists in `capabilities` must be named here too, since it may change
+    /// in any release (docs/api/stability.md). One no longer experimental is
+    /// accepted here, so the manifest keeps loading once it is promoted.
+    #[serde(default)]
+    pub experimental: Vec<Capability>,
 }
 
 #[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq)]
@@ -99,6 +105,11 @@ impl Capability {
             Capability::Ui => "ui",
         }
     }
+    /// May change in any release: a mod uses it only with
+    /// `experimental = ["<name>"]` in its manifest.
+    pub fn is_experimental(self) -> bool {
+        matches!(self, Capability::Ui)
+    }
     /// What the player reads before turning the mod on: "May <this>".
     pub fn describe(self) -> &'static str {
         match self {
@@ -169,6 +180,16 @@ impl Manifest {
                 "{MANIFEST}: capability registries needs api = \"0.2\""
             ));
         }
+        if let Some(c) = m
+            .capabilities
+            .iter()
+            .find(|c| c.is_experimental() && !m.experimental.contains(c))
+        {
+            return Err(format!(
+                "{MANIFEST}: capability {c} is experimental and may change in any release: \
+                 add experimental = [\"{c}\"] to use it"
+            ));
+        }
         if !m.namespaces.is_empty() && !m.capabilities.contains(&Capability::Registries) {
             return Err(format!(
                 "{MANIFEST}: namespaces are for content, which needs capability registries"
@@ -421,4 +442,21 @@ capabilities = ["game-read", "hud"]
         assert_eq!(p.wasm.as_deref(), Some(&b"\0asm"[..]));
         std::fs::remove_dir_all(&dir).unwrap();
     }
+
+    #[test]
+    fn experimental_capabilities_need_the_opt_in() {
+        let base = "id = \"m\"\nname = \"M\"\nversion = \"1\"\napi = \"0.1\"\n";
+        let err = Manifest::parse(&format!("{base}capabilities = [\"ui\"]\n")).unwrap_err();
+        assert!(err.contains("experimental = [\"ui\"]"), "{err}");
+        let m = Manifest::parse(&format!(
+            "{base}capabilities = [\"ui\"]\nexperimental = [\"ui\"]\n"
+        ))
+        .unwrap();
+        assert_eq!(m.experimental, [Capability::Ui]);
+        // A capability that is (or became) stable is fine in the list.
+        Manifest::parse(&format!(
+            "{base}capabilities = [\"hud\"]\nexperimental = [\"hud\"]\n"
+        ))
+        .unwrap();
+    }
 }
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index a229f748e..77f0975f3 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -23,6 +23,7 @@ name = "Test UI Guest"
 version = "0.1.0"
 api = "0.1"
 capabilities = ["chat", "ui"]
+experimental = ["ui"]
 "#;
 
 /// Builds both mods once and writes their `.hmod` files; returns the folder.
diff --git a/docs/api/stability.md b/docs/api/stability.md
index 2d4476fc7..ffa9d9b11 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -87,6 +87,7 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
 | Part | Level | Version |
 | --- | --- | --- |
 | Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
+| Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` |
 | Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
 | Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first |
 | Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
diff --git a/docs/mods.md b/docs/mods.md
index 45e5ae02e..9b3b8aa94 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -86,7 +86,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) |
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
-| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code |
+| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
 
 | Hook (export) | When |
 |---|---|
@@ -284,10 +284,13 @@ authors = ["..."]
 api = "0.1"                  # the API the SDK targets
 side = "client"              # client | server | both
 capabilities = ["game-read", "hud", "chat"]
+experimental = []            # experimental capabilities it uses, e.g. ["ui"]
 ```
 
 Unknown keys are refused, so a typo is an error, not a silently ignored
-permission.
+permission. An experimental capability (today `ui`) may change in any release
+([stability](api/stability.md)): a mod uses it only by naming it in
+`experimental` as well, so nobody depends on it by accident.
 
 ### Content mods (API 0.2)
 

From befec1995f0cb89d11b4fd07354116805f6796a5 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:57:10 +0100
Subject: [PATCH 174/270] ui: a Settings button appears when the mod sets its
 page later

has_settings was read once, when the mods loaded, so a mod that called
set-settings from a command or a tick never got its Settings button
until a reload. The Mods page's rows now follow each mod call's output.
Also clippy with --features mods: needless borrows of the atlas in
draw_mod_screen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/mods.rs | 32 +++++++++++++++-----------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 688e29da1..47a3ce07b 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -395,6 +395,12 @@ impl Game<'_> {
                 .chat
                 .add(&self.gui.atlas, line, None, self.ticks, focused);
         }
+        // A mod may set or clear its settings page in any call, not only
+        // while loading: its row's Settings button follows.
+        let rows = self.settings.mods.installed.iter_mut();
+        for (row, e) in rows.zip(self.mods.mods.entries()) {
+            row.has_settings = e.has_ui_settings();
+        }
     }
     /// The mods' HUD panels, stacked with the extras in their corners.
     pub(super) fn draw_mod_panels(&self, batch: &mut HudBatch, corners: &mut Corners) {
@@ -521,10 +527,10 @@ impl Game<'_> {
         let mut items: Vec<(String, f32, f32)> = Vec::new();
         let atlas = &self.gui.atlas;
         let in_world = self.player.is_some();
-        ui::menu_background(batch, &atlas, 0.0, 0.0, batch.width, batch.height, in_world);
+        ui::menu_background(batch, atlas, 0.0, 0.0, batch.width, batch.height, in_world);
         ui::centered_text(
             batch,
-            &atlas,
+            atlas,
             &Text::literal(title),
             0.0,
             15.0,
@@ -545,7 +551,7 @@ impl Game<'_> {
                     };
                     ui::centered_text(
                         batch,
-                        &atlas,
+                        atlas,
                         &Text::literal(t.text.clone()),
                         x,
                         wy + 1.0,
@@ -557,7 +563,7 @@ impl Game<'_> {
                     if self.res.items().get(&i.item).is_some() {
                         items.push((i.item.clone(), x + 2.0, wy + 2.0));
                     } else {
-                        batch.text(&atlas, "?", x + 6.0, wy + 6.0, u32::MAX, true);
+                        batch.text(atlas, "?", x + 6.0, wy + 6.0, u32::MAX, true);
                     }
                     let name = if i.name.is_empty() {
                         i.item.rsplit(':').next().unwrap_or(&i.item).to_string()
@@ -565,7 +571,7 @@ impl Game<'_> {
                         i.name.clone()
                     };
                     batch.text_styled(
-                        &atlas,
+                        atlas,
                         &Text::literal(name),
                         x + 22.0,
                         wy + 6.0,
@@ -582,12 +588,12 @@ impl Game<'_> {
                     list_i += 1;
                     let rows_top = wy + 4.0;
                     let rows_bottom = wy + wh - 4.0;
-                    batch.fill(&atlas, x, wy, MOD_UI_COLUMN, wh, 0x8000_0000);
+                    batch.fill(atlas, x, wy, MOD_UI_COLUMN, wh, 0x8000_0000);
                     for (b, yy) in [(x, wy), (x, wy + wh - 1.0)] {
-                        batch.fill(&atlas, b, yy, MOD_UI_COLUMN, 1.0, 0xFF50_5050);
+                        batch.fill(atlas, b, yy, MOD_UI_COLUMN, 1.0, 0xFF50_5050);
                     }
                     for (xx, yy) in [(x, wy), (x + MOD_UI_COLUMN - 1.0, wy)] {
-                        batch.fill(&atlas, xx, yy, 1.0, wh, 0xFF50_5050);
+                        batch.fill(atlas, xx, yy, 1.0, wh, 0xFF50_5050);
                     }
                     let content = l.rows.len() as f32 * 12.0;
                     let first = (scroll.amount / 12.0) as usize;
@@ -596,13 +602,13 @@ impl Game<'_> {
                     for (vi, ri) in (first..last).enumerate() {
                         let ry = rows_top + vi as f32 * 12.0 - (scroll.amount % 12.0);
                         if ui::hovered(self.cursor, x, ry, MOD_UI_COLUMN - 6.0, 12.0) {
-                            batch.fill(&atlas, x + 1.0, ry, MOD_UI_COLUMN - 8.0, 12.0, 0x20FF_FFFF);
+                            batch.fill(atlas, x + 1.0, ry, MOD_UI_COLUMN - 8.0, 12.0, 0x20FF_FFFF);
                         }
                         if l.selected == Some(ri as u32) {
-                            batch.fill(&atlas, x + 1.0, ry, 3.0, 12.0, 0xFFFF_FFFF);
+                            batch.fill(atlas, x + 1.0, ry, 3.0, 12.0, 0xFFFF_FFFF);
                         }
                         batch.text_styled(
-                            &atlas,
+                            atlas,
                             &Text::literal(l.rows[ri].clone()),
                             x + 6.0,
                             ry + 2.0,
@@ -612,7 +618,7 @@ impl Game<'_> {
                     }
                     ui::scrollbar(
                         batch,
-                        &atlas,
+                        atlas,
                         x + MOD_UI_COLUMN - 5.0,
                         rows_top,
                         rows_bottom,
@@ -625,7 +631,7 @@ impl Game<'_> {
         let hover = ui::hovered(self.cursor, cx - 100.0, batch.height - 27.0, 200.0, 20.0);
         ui::button(
             batch,
-            &atlas,
+            atlas,
             cx - 100.0,
             batch.height - 27.0,
             200.0,

From de0f76476f1ee603c7d86d167b669d9680acfdb7 Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:10:26 -0300
Subject: [PATCH 175/270] Big dripleaves tilt under a player standing on them

The leaf's tilt ticks, its reset and its redstone reset were already in
horizon-world (big_dripleaf_tick, big_dripleaf_reset_tilt), but nothing
started them: BigDripleafBlock.entityInside was missing. An entity on
the ground whose feet are above the leaf's y + 0.6875 (canEntityTilt)
tilts a flat, unpowered leaf UNSTABLE and schedules its tick in 10.

The block tick's inside scan now also passes the host's and the LAN
guests' feet and on-ground flag to Behaviours::entity_on_big_dripleaf.

Fixes #1683.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs          | 31 ++++++++++++++++
 crates/horizon-client/src/game/lan_mobs.rs | 13 +++++++
 crates/horizon-world/src/level/hooks.rs    | 23 ++++++++++++
 crates/horizon-world/src/level/mod.rs      | 13 +++++++
 crates/horizon-world/src/level/tests.rs    | 41 ++++++++++++++++++++++
 5 files changed, 121 insertions(+)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f05ee41e4..9edb3c17d 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -2575,10 +2575,41 @@ impl Game<'_> {
                 }
             }
         }
+        // BigDripleafBlock.entityInside also asks whether the player stands on
+        // the ground and how high its feet are: the leaves its box's feet
+        // layer is inside (the host and the LAN guests).
+        let mut standing = Vec::new();
+        let feet = self
+            .player
+            .iter()
+            .filter(|_| !self.spectator())
+            .map(|p| {
+                (
+                    [p.position.x, p.position.y, p.position.z],
+                    p.ground.on_ground,
+                    f64::from(p.dimensions.width) / 2.0,
+                )
+            })
+            .chain(
+                self.lan_guest_feet()
+                    .into_iter()
+                    .map(|(at, on_ground)| (at, on_ground, 0.3)),
+            );
+        for (at, on_ground, w) in feet {
+            let y = (at[1] + 1e-7).floor() as i32;
+            for x in (at[0] - w + 1e-7).floor() as i32..=(at[0] + w - 1e-7).floor() as i32 {
+                for z in (at[2] - w + 1e-7).floor() as i32..=(at[2] + w - 1e-7).floor() as i32 {
+                    standing.push((BlockPos::new(x, y, z), on_ground, at[1]));
+                }
+            }
+        }
         self.with_level(|b, level, ticks| {
             for pos in inside {
                 b.entity_inside(level, ticks, pos);
             }
+            for (pos, on_ground, feet_y) in standing {
+                b.entity_on_big_dripleaf(level, ticks, pos, on_ground, feet_y);
+            }
         });
         self.process_level_events()?;
         self.tick_scheduled()?;
diff --git a/crates/horizon-client/src/game/lan_mobs.rs b/crates/horizon-client/src/game/lan_mobs.rs
index be277b6e0..dc4d1eb42 100644
--- a/crates/horizon-client/src/game/lan_mobs.rs
+++ b/crates/horizon-client/src/game/lan_mobs.rs
@@ -171,6 +171,19 @@ impl Game<'_> {
             })
             .collect()
     }
+    /// The same guests' feet and whether they stand on the ground, for the
+    /// blocks that also ask that (`BigDripleafBlock.canEntityTilt`).
+    pub(super) fn lan_guest_feet(&self) -> Vec<([f64; 3], bool)> {
+        let Some(host) = self.lan.as_ref() else {
+            return Vec::new();
+        };
+        host.hub
+            .guests
+            .iter()
+            .filter(|g| host.hub.here(g) && g.loaded && !g.dead && !g.spectator())
+            .map(|g| (g.position, g.on_ground))
+            .collect()
+    }
 
     /// The guests a projectile can hit, under their entity ids.
     pub(super) fn lan_projectile_targets(&self) -> Vec<(Who, Aabb)> {
diff --git a/crates/horizon-world/src/level/hooks.rs b/crates/horizon-world/src/level/hooks.rs
index 0695a92b3..7f9e8d19a 100644
--- a/crates/horizon-world/src/level/hooks.rs
+++ b/crates/horizon-world/src/level/hooks.rs
@@ -573,6 +573,29 @@ impl<L: LevelAccess + ?Sized> Sim<'_, L> {
             self.game_event_state(pos, "minecraft:block_destroy", state);
         }
     }
+    /// `BigDripleafBlock.entityInside` on a server level: an entity standing on
+    /// a flat leaf (`canEntityTilt`: on the ground, its feet above the leaf's
+    /// lowest top, 11/16, less 4/16: 0.6875) tilts it UNSTABLE unless the leaf
+    /// is powered; `setTiltAndScheduleTick` with no sound (UNSTABLE causes no
+    /// vibration) and the next state in 10 ticks.
+    pub(crate) fn big_dripleaf_entity_inside(
+        &mut self,
+        pos: BlockPos,
+        on_ground: bool,
+        feet_y: f64,
+    ) {
+        let b = self.b;
+        let state = self.state(pos);
+        if !b.data(state).is(Class::BigDripleaf)
+            || b.table.text(state, b.props.tilt) != "none"
+            || !(on_ground && feet_y > f64::from(pos.y) + f64::from(0.6875_f32))
+            || self.has_neighbor_signal(pos)
+        {
+            return;
+        }
+        self.set_block(pos, b.table.set_text(state, b.props.tilt, "unstable"), 2);
+        self.schedule_tick(pos, b.block(state), 10);
+    }
     /// `BigDripleafBlock.resetTilt`.
     pub(crate) fn big_dripleaf_reset_tilt(&mut self, pos: BlockPos, state: BlockStateId) {
         let b = self.b;
diff --git a/crates/horizon-world/src/level/mod.rs b/crates/horizon-world/src/level/mod.rs
index 696777386..3831efbd6 100644
--- a/crates/horizon-world/src/level/mod.rs
+++ b/crates/horizon-world/src/level/mod.rs
@@ -749,6 +749,19 @@ impl Behaviours {
     ) {
         self.sim(level, ticks).entity_inside(pos);
     }
+    /// `BigDripleafBlock.entityInside` for an entity whose box is inside
+    /// `pos`: whether it is on the ground and its feet's y (`canEntityTilt`).
+    pub fn entity_on_big_dripleaf<L: LevelAccess + ?Sized>(
+        &self,
+        level: &mut L,
+        ticks: &mut Ticks,
+        pos: BlockPos,
+        on_ground: bool,
+        feet_y: f64,
+    ) {
+        self.sim(level, ticks)
+            .big_dripleaf_entity_inside(pos, on_ground, feet_y);
+    }
     /// Redstone signal queries (`SignalGetter`).
     pub fn has_neighbor_signal<L: LevelAccess + ?Sized>(
         &self,
diff --git a/crates/horizon-world/src/level/tests.rs b/crates/horizon-world/src/level/tests.rs
index 1a1b9ebae..8a4b6c34f 100644
--- a/crates/horizon-world/src/level/tests.rs
+++ b/crates/horizon-world/src/level/tests.rs
@@ -1283,3 +1283,44 @@ fn player_breaks_fire_with_extinguish_not_generic_break_event() {
         assert_eq!(w.get(pos), w.b().air());
     }
 }
+
+#[test]
+fn big_dripleaf_tilts_under_an_entity_standing_on_it() {
+    let mut w = world!();
+    w.floor(0, 2, "clay");
+    let pos = BlockPos::new(0, 1, 0);
+    let leaf = w.id("big_dripleaf", &[("facing", "north")]);
+    w.put(pos, leaf);
+    let stand = |w: &mut World, on_ground: bool, feet: f64| {
+        w.f.behaviours
+            .entity_on_big_dripleaf(&mut w.level, &mut w.ticks, pos, on_ground, feet);
+    };
+    // canEntityTilt: in the air, or with its feet at or under 0.6875, nothing.
+    stand(&mut w, false, 1.9375);
+    stand(&mut w, true, 1.6875);
+    assert_eq!(w.prop(pos, "tilt"), "none");
+    // Standing on the leaf's top (15/16): UNSTABLE, then PARTIAL and FULL
+    // 10 ticks apart, and back to NONE 100 ticks later.
+    stand(&mut w, true, 1.9375);
+    assert_eq!(w.prop(pos, "tilt"), "unstable");
+    for _ in 0..10 {
+        w.tick();
+    }
+    assert_eq!(w.prop(pos, "tilt"), "partial");
+    for _ in 0..10 {
+        w.tick();
+    }
+    assert_eq!(w.prop(pos, "tilt"), "full");
+    // A tilted leaf doesn't restart under the entity.
+    stand(&mut w, true, 1.9375);
+    assert_eq!(w.prop(pos, "tilt"), "full");
+    for _ in 0..100 {
+        w.tick();
+    }
+    assert_eq!(w.prop(pos, "tilt"), "none");
+    // A powered leaf doesn't tilt.
+    let power = w.id("redstone_block", &[]);
+    w.put(BlockPos::new(1, 1, 0), power);
+    stand(&mut w, true, 1.9375);
+    assert_eq!(w.prop(pos, "tilt"), "none");
+}

From 74e3b0adf6937575dd5c5a3d2ea99ed0cb490eec Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 21:10:52 +0100
Subject: [PATCH 176/270] ui: recapture the mouse when a mod's screen vanishes,
 borrow its widgets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review on #1864: when a mod stops while its screen or settings page is
up, draw_mod_screen dropped the player back to Playing without
capture(true), leaving the mouse free until the next click into the
world. The dead surface now leaves through close_mod_screen, which puts
back the screen it covered and holds the mouse on a return to Playing;
the same goes for a screen dropped while it was up.

mod_ui_view also cloned the title and every widget (up to 64, lists to
512 rows) on each frame, click and scroll. It now borrows the mod's
stored widgets — the screen's scrolls live in a disjoint field — and the
click finds the picked row first so the &mut ui_select runs after.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/mods.rs | 87 +++++++++++++-------------
 1 file changed, 44 insertions(+), 43 deletions(-)

diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 47a3ce07b..d2e9627e6 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -425,30 +425,28 @@ impl Game<'_> {
     }
 
     /// A `ui` screen's title and widgets as the mod last pushed them; None
-    /// when the surface is gone (the mod stopped or closed it).
-    fn mod_ui_view(&self) -> Option<(String, Vec<UiWidget>)> {
-        let ms = self.mods.screen.as_ref()?;
+    /// when the surface is gone (the mod stopped or closed it). Borrows
+    /// `mods` only, so `self.mods.screen` may stay borrowed for the scrolls.
+    fn mod_ui_view<'a>(mods: &'a Mods, ms: &ModScreen) -> Option<(&'a str, &'a [UiWidget])> {
         if ms.settings {
-            let widgets = self.mods.mods.settings_widgets(ms.owner);
+            let widgets = mods.settings_widgets(ms.owner);
             if widgets.is_empty() {
                 return None;
             }
-            let name = self
-                .mods
-                .mods
+            let name = mods
                 .entries()
                 .get(ms.owner)
                 .and_then(|e| e.manifest.as_ref())
                 .map_or("Mod", |m| m.name.as_str());
-            Some((name.to_string(), widgets.to_vec()))
+            Some((name, widgets))
         } else {
-            let s: &UiScreen = self.mods.mods.screen(ms.owner)?;
-            Some((s.title.clone(), s.widgets.clone()))
+            let s: &UiScreen = mods.screen(ms.owner)?;
+            Some((s.title.as_str(), s.widgets.as_slice()))
         }
     }
     /// The layout the mod screen's widgets get at `h`: (widget, top,
     /// height), the column being `COLUMN` wide down the middle.
-    fn mod_ui_layout(&self, h: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
+    fn mod_ui_layout(h: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
         let mut out = Vec::with_capacity(widgets.len());
         let mut y = MOD_UI_TOP;
         for w in widgets {
@@ -513,13 +511,19 @@ impl Game<'_> {
     /// The mod's screen or settings page: its title over widgets stacked
     /// down the middle, a Done button, Esc to leave (vanilla's menus).
     pub(super) fn draw_mod_screen(&mut self, batch: &mut HudBatch) {
-        if self.mods.screen.is_none() {
+        let Some(ms) = self.mods.screen.as_mut() else {
+            // The screen was dropped while it was up: back to the world,
+            // mouse held again like any return to Playing.
             self.screen = Screen::Playing;
+            if self.player.is_some() {
+                self.capture(true);
+            }
             return;
-        }
-        let Some((title, widgets)) = self.mod_ui_view() else {
-            self.mods.screen = None;
-            self.screen = Screen::Playing;
+        };
+        let Some((title, widgets)) = Self::mod_ui_view(&self.mods.mods, ms) else {
+            // The mod's surface is gone (it stopped or cleared it): leave
+            // the screen like Done did, without `closed` — the mod ended it.
+            self.close_mod_screen(false);
             return;
         };
         // Item icons draw in a second pass: `draw_item` needs `&mut self`,
@@ -539,7 +543,7 @@ impl Game<'_> {
         );
         let cx = (batch.width / 2.0).floor();
         let x = cx - MOD_UI_COLUMN / 2.0;
-        let layout = self.mod_ui_layout(batch.height, &widgets);
+        let layout = Self::mod_ui_layout(batch.height, widgets);
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             match w {
@@ -580,11 +584,8 @@ impl Game<'_> {
                     );
                 }
                 UiWidget::List(l) => {
-                    let scroll = {
-                        let ms = self.mods.screen.as_mut().expect("checked");
-                        ms.scrolls.resize_with(list_i + 1, ui::Scroll::default);
-                        ms.scrolls[list_i]
-                    };
+                    ms.scrolls.resize_with(list_i + 1, ui::Scroll::default);
+                    let scroll = ms.scrolls[list_i];
                     list_i += 1;
                     let rows_top = wy + 4.0;
                     let rows_bottom = wy + wh - 4.0;
@@ -655,53 +656,53 @@ impl Game<'_> {
             self.close_mod_screen(true);
             return;
         }
-        let Some((_, widgets)) = self.mod_ui_view() else {
+        let Some(ms) = self.mods.screen.as_ref() else {
             return;
         };
+        let Some((_, widgets)) = Self::mod_ui_view(&self.mods.mods, ms) else {
+            return;
+        };
+        let owner = ms.owner;
         let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
-        let layout = self.mod_ui_layout(h, &widgets);
+        let layout = Self::mod_ui_layout(h, widgets);
         let mut list_i = 0usize;
+        // The `ui_select` call needs `&mut`: find the pick first.
+        let mut hit = None;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             let UiWidget::List(l) = w else { continue };
-            let scroll = self
-                .mods
-                .screen
-                .as_ref()
-                .and_then(|ms| ms.scrolls.get(list_i).copied())
-                .unwrap_or_default();
+            let scroll = ms.scrolls.get(list_i).copied().unwrap_or_default();
             list_i += 1;
             let row = ((cursor.1 - (wy + 4.0) + scroll.amount) / 12.0) as i64;
             if ui::hovered(cursor, x + 1.0, wy + 1.0, MOD_UI_COLUMN - 7.0, wh - 2.0)
                 && row >= 0
                 && (row as usize) < l.rows.len()
             {
-                self.audio.play_button_click();
-                self.mods.mods.ui_select(
-                    self.mods.screen.as_ref().map_or(0, |ms| ms.owner),
-                    l.id,
-                    row as u32,
-                );
-                self.show_mod_output();
-                return;
+                hit = Some((l.id, row as u32));
+                break;
             }
         }
+        if let Some((id, row)) = hit {
+            self.audio.play_button_click();
+            self.mods.mods.ui_select(owner, id, row);
+            self.show_mod_output();
+        }
     }
     /// The wheel over a `list` scrolls it.
     pub(super) fn mod_screen_scroll(&mut self, delta: f32) {
         let (w, h) = self.gui_size();
         let cursor = self.cursor;
-        let Some((_, widgets)) = self.mod_ui_view() else {
+        let Some(ms) = self.mods.screen.as_mut() else {
+            return;
+        };
+        let Some((_, widgets)) = Self::mod_ui_view(&self.mods.mods, ms) else {
             return;
         };
         let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
-        let layout = self.mod_ui_layout(h, &widgets);
+        let layout = Self::mod_ui_layout(h, widgets);
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             let UiWidget::List(l) = w else { continue };
             let over = ui::hovered(cursor, x, wy, MOD_UI_COLUMN, wh);
-            let Some(ms) = self.mods.screen.as_mut() else {
-                return;
-            };
             ms.scrolls.resize_with(list_i + 1, ui::Scroll::default);
             if over {
                 let content = l.rows.len() as f32 * 12.0;

From 03a5cbdcd800bb6d41c3f6ffb88e875ce25e9f07 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:11:47 +0100
Subject: [PATCH 177/270] Renderer: OpenGL as the last fallback, for GPUs with
 no Vulkan or DirectX 12 driver

wgpu's GL backend (WGL on Windows, EGL on Linux). Auto tries Vulkan, then DirectX 12 on Windows,
then OpenGL; graphicsApi:opengl (or HORIZON_GRAPHICS_API=opengl) picks it. A Radeon HD 7400M
(TeraScale 2: DirectX 11, OpenGL 4.x) could not start Horizon at all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/Cargo.toml      |  5 +++
 crates/horizon-client/src/gfx.rs      | 64 +++++++++++++++------------
 crates/horizon-client/src/graphics.rs | 15 +++++--
 3 files changed, 53 insertions(+), 31 deletions(-)

diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml
index ea5859c23..4877c18f2 100644
--- a/crates/horizon-client/Cargo.toml
+++ b/crates/horizon-client/Cargo.toml
@@ -68,6 +68,11 @@ rustix = { version = "1", default-features = false, features = ["std", "time"] }
 # on the PATH.
 wgpu = { version = "30.0.1", default-features = false, features = ["dx12"] }
 
+[target.'cfg(not(target_os = "macos"))'.dependencies]
+# OpenGL (WGL on Windows, EGL on Linux), the last fallback, for GPUs with no Vulkan or
+# DirectX 12 driver (`graphicsApi`, graphics.rs).
+wgpu = { version = "30.0.1", default-features = false, features = ["gles"] }
+
 [target.'cfg(windows)'.build-dependencies]
 # The icon resource in the .exe (build.rs).
 winresource = "0.1"
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index b43202074..f2fdfb6b3 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -683,25 +683,31 @@ fn instance_descriptor(backends: wgpu::Backends) -> wgpu::InstanceDescriptor {
 }
 /// The backends to open a device on, each tried in turn until one gives a
 /// device. `api` is the player's choice (`GraphicsApi::with_env` applied);
-/// `wgpu_backend`: whether `WGPU_BACKEND` is set, which picks the backends
-/// itself. Only Windows has two: Auto tries Vulkan, then DirectX 12 when
-/// Vulkan has no surface, adapter (no Vulkan driver) or device. A native crash in
-/// the driver can't be caught in the game; the launcher switches the setting
-/// to DirectX 12 after one at the renderer's start (#746).
-fn backend_order(api: GraphicsApi, windows: bool, wgpu_backend: bool) -> Vec<wgpu::Backends> {
-    if !windows || wgpu_backend {
-        return vec![wgpu::Backends::default()];
+/// `os` is `std::env::consts::OS`; `wgpu_backend`: whether `WGPU_BACKEND` is set,
+/// which picks the backends itself. Auto tries Vulkan, then DirectX 12 on Windows,
+/// then OpenGL (Windows and Linux) for GPUs with neither driver, each when the one
+/// before has no surface, adapter or device. A native crash in the driver can't be
+/// caught in the game; the launcher switches the setting to DirectX 12 after one at
+/// the renderer's start (#746). macOS has Metal only.
+fn backend_order(api: GraphicsApi, os: &str, wgpu_backend: bool) -> Vec<wgpu::Backends> {
+    use wgpu::Backends;
+    if os == "macos" || wgpu_backend {
+        return vec![Backends::default()];
     }
+    let windows = os == "windows";
     match api {
-        GraphicsApi::Auto => vec![wgpu::Backends::VULKAN, wgpu::Backends::DX12],
-        GraphicsApi::Vulkan => vec![wgpu::Backends::VULKAN],
-        GraphicsApi::Dx12 => vec![wgpu::Backends::DX12],
+        GraphicsApi::Auto if windows => vec![Backends::VULKAN, Backends::DX12, Backends::GL],
+        GraphicsApi::Auto => vec![Backends::VULKAN, Backends::GL],
+        GraphicsApi::Dx12 if windows => vec![Backends::DX12],
+        GraphicsApi::Vulkan | GraphicsApi::Dx12 => vec![Backends::VULKAN],
+        GraphicsApi::OpenGl => vec![Backends::GL],
     }
 }
 fn backends_name(backends: wgpu::Backends) -> &'static str {
     match backends {
         wgpu::Backends::VULKAN => "Vulkan",
         wgpu::Backends::DX12 => "DirectX 12",
+        wgpu::Backends::GL => "OpenGL",
         _ => "graphics",
     }
 }
@@ -780,7 +786,7 @@ async fn open_device(
 ) -> Result<Opened> {
     let order = backend_order(
         api.with_env(),
-        cfg!(windows),
+        std::env::consts::OS,
         std::env::var_os("WGPU_BACKEND").is_some(),
     );
     let mut failures = Vec::new();
@@ -869,14 +875,14 @@ async fn open_device(
 /// Vulkan is loaded at run time (the game links no graphics library), so a
 /// missing driver shows here rather than as a missing-DLL dialog.
 #[cfg(target_os = "windows")]
-const NO_GPU_DRIVER: &str = "No graphics driver with Vulkan or DirectX 12 found: Horizon needs a GPU \
-     driver with one of them. Install the latest driver for your NVIDIA, AMD or Intel GPU and \
+const NO_GPU_DRIVER: &str = "No graphics driver with Vulkan, DirectX 12 or OpenGL found: Horizon needs \
+     a GPU driver with one of them. Install the latest driver for your NVIDIA, AMD or Intel GPU and \
      start the game again";
 #[cfg(target_os = "macos")]
 const NO_GPU_DRIVER: &str = "No Metal graphics device found";
 #[cfg(not(any(target_os = "windows", target_os = "macos")))]
-const NO_GPU_DRIVER: &str = "No Vulkan graphics driver found: Horizon needs the Vulkan loader \
-     (libvulkan.so.1) and a Vulkan driver for your GPU (Mesa's, or NVIDIA's)";
+const NO_GPU_DRIVER: &str = "No Vulkan or OpenGL graphics driver found: Horizon needs the Vulkan loader \
+     (libvulkan.so.1) and a Vulkan driver for your GPU (Mesa's, or NVIDIA's), or OpenGL through EGL";
 /// Logs a step of the renderer's start, for a native crash in the graphics
 /// driver: it leaves no panic or crash report, so the log's last line is the
 /// only sign of where the game stopped. The log file is written unbuffered;
@@ -4475,25 +4481,27 @@ mod tests {
         );
     }
     #[test]
-    fn windows_tries_vulkan_then_directx_12() {
+    fn auto_tries_vulkan_then_directx_12_then_opengl() {
         use super::{GraphicsApi, backend_order};
         use wgpu::Backends;
+        let order = |api, os| backend_order(api, os, false);
         assert_eq!(
-            backend_order(GraphicsApi::Auto, true, false),
-            [Backends::VULKAN, Backends::DX12]
+            order(GraphicsApi::Auto, "windows"),
+            [Backends::VULKAN, Backends::DX12, Backends::GL]
         );
+        assert_eq!(order(GraphicsApi::Vulkan, "windows"), [Backends::VULKAN]);
+        assert_eq!(order(GraphicsApi::Dx12, "windows"), [Backends::DX12]);
+        assert_eq!(order(GraphicsApi::OpenGl, "windows"), [Backends::GL]);
         assert_eq!(
-            backend_order(GraphicsApi::Vulkan, true, false),
-            [Backends::VULKAN]
+            order(GraphicsApi::Auto, "linux"),
+            [Backends::VULKAN, Backends::GL]
         );
-        assert_eq!(
-            backend_order(GraphicsApi::Dx12, true, false),
-            [Backends::DX12]
-        );
-        // WGPU_BACKEND picks the backends itself; other systems have one.
+        assert_eq!(order(GraphicsApi::Dx12, "linux"), [Backends::VULKAN]);
+        assert_eq!(order(GraphicsApi::OpenGl, "linux"), [Backends::GL]);
+        // WGPU_BACKEND picks the backends itself; macOS has Metal only.
         for api in GraphicsApi::ALL {
-            assert_eq!(backend_order(api, true, true), [Backends::default()]);
-            assert_eq!(backend_order(api, false, false), [Backends::default()]);
+            assert_eq!(backend_order(api, "windows", true), [Backends::default()]);
+            assert_eq!(order(api, "macos"), [Backends::default()]);
         }
     }
     /// Every WGSL shader file translates to HLSL as wgpu's DirectX 12 backend
diff --git a/crates/horizon-client/src/graphics.rs b/crates/horizon-client/src/graphics.rs
index 3cf1402d2..21d38539e 100644
--- a/crates/horizon-client/src/graphics.rs
+++ b/crates/horizon-client/src/graphics.rs
@@ -98,19 +98,27 @@ impl PresentMode {
 /// macOS). Applies at the next start.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub enum GraphicsApi {
-    /// Vulkan, and DirectX 12 when Vulkan has no adapter or device.
+    /// Vulkan, then DirectX 12 (Windows), then OpenGL when neither has a surface, adapter or device.
     #[default]
     Auto,
     Vulkan,
     Dx12,
+    /// OpenGL, for GPUs with no Vulkan or DirectX 12 driver (Windows and Linux).
+    OpenGl,
 }
 impl GraphicsApi {
-    pub const ALL: [GraphicsApi; 3] = [GraphicsApi::Auto, GraphicsApi::Vulkan, GraphicsApi::Dx12];
+    pub const ALL: [GraphicsApi; 4] = [
+        GraphicsApi::Auto,
+        GraphicsApi::Vulkan,
+        GraphicsApi::Dx12,
+        GraphicsApi::OpenGl,
+    ];
     pub fn name(self) -> &'static str {
         match self {
             GraphicsApi::Auto => "auto",
             GraphicsApi::Vulkan => "vulkan",
             GraphicsApi::Dx12 => "dx12",
+            GraphicsApi::OpenGl => "opengl",
         }
     }
     pub fn label(self) -> &'static str {
@@ -118,6 +126,7 @@ impl GraphicsApi {
             GraphicsApi::Auto => "Auto",
             GraphicsApi::Vulkan => "Vulkan",
             GraphicsApi::Dx12 => "DirectX 12",
+            GraphicsApi::OpenGl => "OpenGL",
         }
     }
     /// The API a name stands for, ignoring case; `None` for anything else.
@@ -126,7 +135,7 @@ impl GraphicsApi {
             .into_iter()
             .find(|api| api.name().eq_ignore_ascii_case(s.trim()))
     }
-    /// `HORIZON_GRAPHICS_API` (auto, vulkan or dx12) if set, else the setting.
+    /// `HORIZON_GRAPHICS_API` (auto, vulkan, dx12 or opengl) if set, else the setting.
     pub fn with_env(self) -> Self {
         std::env::var("HORIZON_GRAPHICS_API")
             .ok()

From a013e35a61f3d888f141364ab5e04f13fbb1a842 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:17:59 +0100
Subject: [PATCH 178/270] Collision scans: pass the rest of an outer row in a
 contained section at once

On the rows along a box's bottom, top and sides every cell is outer, so in a
section no block reaches out of, the rest of the row up to the chunk's edge
is passed in one step instead of cell by cell. The candidate budget still
ends the scan where it did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-world/src/block_collision_scan.rs | 35 ++++++++++++++++++-
 .../tests/block_collision_scan.rs             | 31 ++++++++++++++++
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-world/src/block_collision_scan.rs b/crates/horizon-world/src/block_collision_scan.rs
index 391c3e96e..172e6a79c 100644
--- a/crates/horizon-world/src/block_collision_scan.rs
+++ b/crates/horizon-world/src/block_collision_scan.rs
@@ -151,12 +151,31 @@ impl<'w, 'c, W: BlockCollisionWorld> BlockCollisionScan<'w, 'c, W> {
         })
     }
 
+    /// Move the cursor `n` cells further along its row; `n` must not pass
+    /// the row's end.
+    fn skip(&mut self, n: usize) {
+        if n == 0 {
+            return;
+        }
+        let [width, height, _] = self.sizes;
+        self.index += n;
+        self.cursor[0] += n;
+        if self.cursor[0] == width {
+            self.cursor[0] = 0;
+            self.cursor[1] += 1;
+            if self.cursor[1] == height {
+                self.cursor[1] = 0;
+                self.cursor[2] += 1;
+            }
+        }
+    }
+
     fn find_next(&mut self) -> Result<Option<BlockCollisionHit>, CollisionScanError<W::Error>> {
         while self.index < self.count {
             if self.index >= self.budget {
                 return Err(CollisionScanError::VisitBudget);
             }
-            let [width, height, _] = self.sizes;
+            let [width, height, depth] = self.sizes;
             let relative = self.cursor;
             self.index += 1;
             self.cursor[0] += 1;
@@ -212,6 +231,20 @@ impl<'w, 'c, W: BlockCollisionWorld> BlockCollisionScan<'w, 'c, W> {
                     }
                 };
                 if !reaches {
+                    // On a row along the box's bottom, top or sides every
+                    // cell is outer: the rest of it in this chunk is passed
+                    // at once (never beyond the budget, which still ends the
+                    // scan where it would have).
+                    if relative[1] == 0
+                        || relative[1] == height - 1
+                        || relative[2] == 0
+                        || relative[2] == depth - 1
+                    {
+                        let rest = (width - 1 - relative[0])
+                            .min(15 - (p.x & 15) as usize)
+                            .min(self.budget.saturating_sub(self.index));
+                        self.skip(rest);
+                    }
                     continue;
                 }
             }
diff --git a/crates/horizon-world/tests/block_collision_scan.rs b/crates/horizon-world/tests/block_collision_scan.rs
index adf530069..e3f61e1ae 100644
--- a/crates/horizon-world/tests/block_collision_scan.rs
+++ b/crates/horizon-world/tests/block_collision_scan.rs
@@ -222,6 +222,11 @@ fn outer_cells_of_contained_sections_are_not_read() {
             Aabb::new(Vec3::new(4.4, 2.0, -7.6), Vec3::new(4.65, 2.25, -7.35)),
             vec![0],
         ),
+        // Across a chunk's edge: the rest of a row is passed only up to it.
+        (
+            Aabb::new(Vec3::new(14.2, 70.5, -0.4), Vec3::new(17.8, 71.5, 0.4)),
+            vec![4],
+        ),
     ];
     for (bounds, contained) in boxes {
         let mut world = Recording {
@@ -242,3 +247,29 @@ fn outer_cells_of_contained_sections_are_not_read() {
         assert!(world.cells.len() < expected_cells(bounds, &[]).len());
     }
 }
+
+/// Passing outer cells at once still stops at the candidate budget, as
+/// visiting them one by one does.
+#[test]
+fn passed_cells_count_toward_the_budget() {
+    let bounds = Aabb::new(Vec3::new(0.2, 63.5, 0.3), Vec3::new(0.8, 65.3, 0.9));
+    for budget in 0..80 {
+        let scan = |contained: Vec<i32>| {
+            let mut world = Recording {
+                cells: Vec::new(),
+                contained,
+            };
+            BlockCollisionScan::new(
+                &mut world,
+                CollisionContext::empty(false),
+                bounds,
+                false,
+                budget,
+            )
+            .unwrap()
+            .map(|hit| hit.map(|_| ()).map_err(|e| e.to_string()))
+            .collect::<Vec<_>>()
+        };
+        assert_eq!(scan(vec![3, 4]), scan(Vec::new()), "budget {budget}");
+    }
+}

From 54bb3e4fbe869bfc223d0daa2ccf2fa329c721e8 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:19:47 +0100
Subject: [PATCH 179/270] Screen effects: one sampler per entry point, so the
 shader compiles for OpenGL

GLSL combines a texture with its sampler, and naga refuses an entry point that reads one texture
through two (ImageMultipleSamplers): the BLUR override left both branches in fs_screen and
fs_vignette, so creating the screen effect pipelines failed on wgpu's GL backend at startup. Blurred
sprites now have their own entry points (fs_screen_blur, fs_vignette_blur); each pipeline still
samples once per pixel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs      | 17 +++++++-------
 crates/horizon-client/src/screen.wgsl | 34 +++++++++++++++++----------
 2 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index f2fdfb6b3..b55022510 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2069,16 +2069,15 @@ impl Renderer {
         // One per blend and `.png.mcmeta` sampling (screen_effects::SAMPLE_*):
         // the shader is specialised, so a pixel pays for none of the others.
         let screen_pipelines: [wgpu::RenderPipeline; 8] = std::array::from_fn(|i| {
-            let (entry, blend) = if i & 4 == 0 {
-                ("fs_screen", alpha_blend)
-            } else {
-                ("fs_vignette", vignette_blend)
+            let blur = i as u32 & crate::screen_effects::SAMPLE_BLUR != 0;
+            let (entry, blend) = match (i & 4 == 0, blur) {
+                (true, false) => ("fs_screen", alpha_blend),
+                (true, true) => ("fs_screen_blur", alpha_blend),
+                (false, false) => ("fs_vignette", vignette_blend),
+                (false, true) => ("fs_vignette_blur", vignette_blend),
             };
-            let on = |bit: u32| f64::from(u8::from(i as u32 & bit != 0));
-            let constants = [
-                ("BLUR", on(crate::screen_effects::SAMPLE_BLUR)),
-                ("CLAMP", on(crate::screen_effects::SAMPLE_CLAMP)),
-            ];
+            let clamp = i as u32 & crate::screen_effects::SAMPLE_CLAMP != 0;
+            let constants = [("CLAMP", f64::from(u8::from(clamp)))];
             let compilation_options = wgpu::PipelineCompilationOptions {
                 constants: &constants,
                 ..Default::default()
diff --git a/crates/horizon-client/src/screen.wgsl b/crates/horizon-client/src/screen.wgsl
index e70aeb896..1497b36fa 100644
--- a/crates/horizon-client/src/screen.wgsl
+++ b/crates/horizon-client/src/screen.wgsl
@@ -8,10 +8,12 @@
 // atlas, wrapped as repeat reads it (hud.rs), so the hardware's bilinear
 // sample is GL_LINEAR with repeat; clamp-to-edge keeps the sample point half
 // a texel inside. Each sampling has its own pipeline (gfx.rs), so a pixel
-// costs what it did with nearest and repeat only: one sample.
+// costs what it did with nearest and repeat only: one sample. Each entry
+// point reads `atlas` through one sampler only: GLSL (wgpu's OpenGL backend)
+// combines a texture with its sampler, and an override would not remove the
+// other sampler's branch.
 @group(0) @binding(2) var nearest_sampler: sampler;
 @group(0) @binding(4) var linear_sampler: sampler;
-override BLUR: bool = false;
 override CLAMP: bool = false;
 struct Out {
     @builtin(position) clip: vec4<f32>,
@@ -32,28 +34,36 @@ struct Out {
     out.edges = vec4(rect.xy + half, rect.zw - half);
     return out;
 }
-fn sample(in: Out) -> vec4<f32> {
+// The sprite's atlas coordinates of this pixel.
+fn atlas_uv(in: Out) -> vec2<f32> {
     var f = in.uv;
     if !CLAMP {
         // Repeat: one period of the sprite.
         f = fract(f);
     }
-    var uv = in.rect.xy + f * (in.rect.zw - in.rect.xy);
+    let uv = in.rect.xy + f * (in.rect.zw - in.rect.xy);
     if CLAMP {
-        uv = clamp(uv, in.edges.xy, in.edges.zw);
+        return clamp(uv, in.edges.xy, in.edges.zw);
     }
-    if BLUR {
-        return textureSampleLevel(atlas, linear_sampler, uv, 0.0) * in.color;
-    }
-    return textureSampleLevel(atlas, nearest_sampler, uv, 0.0) * in.color;
+    return uv;
 }
-@fragment fn fs_screen(in: Out) -> @location(0) vec4<f32> {
-    let c = sample(in);
+fn screen(c: vec4<f32>) -> vec4<f32> {
     if c.a <= 0.0 { discard; }
     return c;
 }
+@fragment fn fs_screen(in: Out) -> @location(0) vec4<f32> {
+    return screen(textureSampleLevel(atlas, nearest_sampler, atlas_uv(in), 0.0) * in.color);
+}
+@fragment fn fs_screen_blur(in: Out) -> @location(0) vec4<f32> {
+    return screen(textureSampleLevel(atlas, linear_sampler, atlas_uv(in), 0.0) * in.color);
+}
 // RenderPipelines.VIGNETTE blends ZERO, ONE_MINUS_SRC_COLOR: output the
 // texture colour; the blend state darkens the frame by it.
 @fragment fn fs_vignette(in: Out) -> @location(0) vec4<f32> {
-    return vec4(sample(in).rgb, 1.0);
+    let c = textureSampleLevel(atlas, nearest_sampler, atlas_uv(in), 0.0) * in.color;
+    return vec4(c.rgb, 1.0);
+}
+@fragment fn fs_vignette_blur(in: Out) -> @location(0) vec4<f32> {
+    let c = textureSampleLevel(atlas, linear_sampler, atlas_uv(in), 0.0) * in.color;
+    return vec4(c.rgb, 1.0);
 }

From 903da4f1ab8f6735a8d60734a63bcecdd4edbe9e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:20:02 +0100
Subject: [PATCH 180/270] Cargo.lock: wgpu's GL backend dependencies (glow,
 khronos-egl, glutin_wgl_sys)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/Cargo.lock b/Cargo.lock
index 6945e09cf..4d749add6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1116,12 +1116,44 @@ dependencies = [
  "stable_deref_trait",
 ]
 
+[[package]]
+name = "gl_generator"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a95dfc23a2b4a9a2f5ab41d194f8bfda3cabec42af4e39f08c339eb2a0c124d"
+dependencies = [
+ "khronos_api",
+ "log",
+ "xml-rs",
+]
+
 [[package]]
 name = "glam"
 version = "0.30.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "19fc433e8437a212d1b6f1e68c7824af3aed907da60afa994e7f542d18d12aa9"
 
+[[package]]
+name = "glow"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29038e1c483364cc6bb3cf78feee1816002e127c331a1eec55a4d202b9e1adb5"
+dependencies = [
+ "js-sys",
+ "slotmap",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "glutin_wgl_sys"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c4ee00b289aba7a9e5306d57c2d05499b2e5dc427f84ac708bd2c090212cf3e"
+dependencies = [
+ "gl_generator",
+]
+
 [[package]]
 name = "gpu-allocator"
 version = "0.28.0"
@@ -1812,6 +1844,23 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "khronos-egl"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6aae1df220ece3c0ada96b8153459b67eebe9ae9212258bb0134ae60416fdf76"
+dependencies = [
+ "libc",
+ "libloading",
+ "pkg-config",
+]
+
+[[package]]
+name = "khronos_api"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
+
 [[package]]
 name = "lazy_static"
 version = "1.5.1"
@@ -3149,6 +3198,15 @@ version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
+[[package]]
+name = "slotmap"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038"
+dependencies = [
+ "version_check",
+]
+
 [[package]]
 name = "smallvec"
 version = "1.16.2"
@@ -4274,6 +4332,7 @@ dependencies = [
  "smallvec",
  "thiserror 2.0.21",
  "wgpu-core-deps-apple",
+ "wgpu-core-deps-emscripten",
  "wgpu-core-deps-windows-linux-android",
  "wgpu-hal",
  "wgpu-naga-bridge",
@@ -4289,6 +4348,15 @@ dependencies = [
  "wgpu-hal",
 ]
 
+[[package]]
+name = "wgpu-core-deps-emscripten"
+version = "30.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98b86cf4abf524a902dd35f18ca6a3f08fc2ae9847c8f10b48e30491b1f0b86"
+dependencies = [
+ "wgpu-hal",
+]
+
 [[package]]
 name = "wgpu-core-deps-windows-linux-android"
 version = "30.0.1"
@@ -4311,13 +4379,18 @@ dependencies = [
  "bytemuck",
  "cfg-if",
  "cfg_aliases",
+ "glow",
+ "glutin_wgl_sys",
  "gpu-allocator",
  "hashbrown 0.17.1",
+ "js-sys",
+ "khronos-egl",
  "libc",
  "libloading",
  "log",
  "naga",
  "naga-types",
+ "ndk-sys",
  "objc2 0.6.5",
  "objc2-core-foundation",
  "objc2-core-graphics",
@@ -4337,10 +4410,14 @@ dependencies = [
  "smallvec",
  "static_assertions",
  "thiserror 2.0.21",
+ "wasm-bindgen",
+ "wayland-sys",
+ "web-sys",
  "wgpu-naga-bridge",
  "wgpu-types",
  "windows 0.62.2",
  "windows-core 0.62.2",
+ "windows-result 0.4.1",
 ]
 
 [[package]]
@@ -5081,6 +5158,12 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56"
 
+[[package]]
+name = "xml-rs"
+version = "0.8.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7"
+
 [[package]]
 name = "xtask"
 version = "0.1.0"

From ac47b988c9add9ceb575a23a24751084ec43abc6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:21:05 +0100
Subject: [PATCH 181/270] Shader packs, clean room 42: culled entities, the
 first-person player, shadowPlayer and shadowLightBlockEntities in the shadow
 pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Entities Horizon's entity culling hides from the camera keep their vertices in a hidden span that
only the pack's shadow pass draws; the local player's model is built in first person, hidden from
the camera, while the pack casts entity shadows. shadowPlayer draws the player alone when
shadowEntities is off, shadowLightBlockEntities the light-emitting block entities when
shadowBlockEntities is off. Without a shader pack nothing changes.

Clean-room: implemented from cleanroom/shader-packs-spec.md revision 1, §2.4, §3.2; no other
loader's code read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/entity_culling.rs   | 20 ++++--
 crates/horizon-client/src/game.rs             |  8 ++-
 .../horizon-client/src/game/entity_culling.rs | 46 +++++++-----
 crates/horizon-client/src/game/perspective.rs |  3 +-
 .../horizon-client/src/game/shader_packs.rs   | 28 +++++++-
 crates/horizon-client/src/gfx.rs              | 12 ++++
 crates/horizon-client/src/gfx/pack_draw.rs    | 71 ++++++++++++++++++-
 .../horizon-client/src/gfx/pack_entities.rs   | 59 +++++++++++++--
 crates/horizon-client/src/gfx/pack_post.rs    | 42 ++++++++---
 crates/horizon-shaders/src/post.rs            | 27 ++++++-
 10 files changed, 271 insertions(+), 45 deletions(-)

diff --git a/crates/horizon-client/src/entity_culling.rs b/crates/horizon-client/src/entity_culling.rs
index 611eff1af..16de17465 100644
--- a/crates/horizon-client/src/entity_culling.rs
+++ b/crates/horizon-client/src/entity_culling.rs
@@ -25,6 +25,20 @@ impl Culler {
         vertices: &mut Vec<crate::mesher::Vertex>,
         start: usize,
         opaque: impl FnMut([i32; 3]) -> bool,
+    ) -> bool {
+        let hidden = self.hidden(vertices, start, opaque);
+        if hidden {
+            vertices.truncate(start);
+        }
+        hidden
+    }
+
+    /// Whether this entity's completed camera-relative mesh (`vertices[start..]`) is hidden.
+    pub fn hidden(
+        &self,
+        vertices: &[crate::mesher::Vertex],
+        start: usize,
+        opaque: impl FnMut([i32; 3]) -> bool,
     ) -> bool {
         if start >= vertices.len() || self.remaining.get() == 0 {
             return false;
@@ -42,11 +56,7 @@ impl Culler {
             }
         }
         // Cover floating-point and rasterization edges as well as the vertices.
-        if self.occluded(min.map(|v| v - 0.05), max.map(|v| v + 0.05), opaque) {
-            vertices.truncate(start);
-            return true;
-        }
-        false
+        self.occluded(min.map(|v| v - 0.05), max.map(|v| v + 0.05), opaque)
     }
 
     /// Returns true only when a complete opaque block plane covers the bounds.
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 97dff6bbc..49d2a75c0 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1495,6 +1495,9 @@ struct Game<'a> {
     /// This frame's view frustum, for culling entities and block entities.
     view_frustum: Option<horizon_client::gfx::Frustum>,
     entity_culler: Option<horizon_client::entity_culling::Culler>,
+    /// `Renderer::pack_shadow_casters` for this frame's entities: (keep what the culler hides,
+    /// build the player's model in first person); (false, false) without a shader pack.
+    pack_shadow_casters: (bool, bool),
     /// A scripted flight from the control socket (`fly`).
     flight: Option<control::Flight>,
     /// The running agent action from the control socket (game/agent.rs).
@@ -6792,8 +6795,10 @@ impl Game<'_> {
         self.ominous_item_spawner_geometry(camera, alpha, &mut out);
         // Mobs and their projectiles (a span each).
         self.mob_geometry(camera, alpha, &mut out);
-        self.mark_entity(out.len(), "minecraft:player");
+        // In first person only a shader pack's shadow pass draws the player.
+        self.mark_player(out.len(), self.camera_type.first_person());
         self.player_model_geometry(camera, self.clock.camera_fraction(), &mut out);
+        self.mark_entity(out.len(), "minecraft:player");
         self.guest_model_geometry(camera, alpha, &mut out);
         self.mark_entity(out.len(), "minecraft:evoker_fangs");
         self.fangs_geometry(camera, alpha, &mut out);
@@ -11998,6 +12003,7 @@ impl<'a> Game<'a> {
             agent: agent::Agent::default(),
             view_frustum: None,
             entity_culler: None,
+            pack_shadow_casters: (false, false),
             pending_uploads: Vec::new(),
             frame_graph: Default::default(),
             extras: Default::default(),
diff --git a/crates/horizon-client/src/game/entity_culling.rs b/crates/horizon-client/src/game/entity_culling.rs
index 3abf92835..66fbaa3e4 100644
--- a/crates/horizon-client/src/game/entity_culling.rs
+++ b/crates/horizon-client/src/game/entity_culling.rs
@@ -15,6 +15,11 @@ fn opaque(facts: &StateFacts) -> bool {
 
 impl Game<'_> {
     pub(super) fn prepare_entity_culling(&mut self, camera: glam::DVec3) {
+        // Spans tell the pack's passes which entities are hidden; without them, nothing changes.
+        self.pack_shadow_casters = match (&self.renderer, &self.pack_ids) {
+            (Some(r), Some(_)) => r.pack_shadow_casters(),
+            _ => (false, false),
+        };
         let at = camera.to_array().map(|v| v.floor() as i32);
         self.entity_culler = (self.settings.horizon.entity_culling
             // Packs can replace an opaque block's model or texture.
@@ -28,24 +33,29 @@ impl Game<'_> {
     /// Use complete generated geometry so equipment, animation and custom
     /// models cannot stick out of an assumed collision-sized culling box.
     pub(super) fn cull_entity_vertices(&self, vertices: &mut Vec<Vertex>, start: usize) {
-        if let Some(culler) = &self.entity_culler {
-            culler.cull_vertices(vertices, start, |pos| {
-                let state = self.world.block(pos[0], pos[1], pos[2]);
-                if !opaque(self.res.facts().get(state)) {
-                    return false;
-                }
-                let Some(y) = pos[1].checked_sub(MIN_Y) else {
-                    return false;
-                };
-                let section = (pos[0] >> 4, y.div_euclid(16), pos[2] >> 4);
-                // Newly edited or not-yet-uploaded terrain is not an occluder.
-                self.renderer
-                    .as_ref()
-                    .is_some_and(|r| r.has_section(section))
-                    && !self.world.dirty_sections.contains(&section)
-                    && !self.streaming.is_meshing(section)
-                    && !self.pending_uploads.iter().any(|(key, _)| *key == section)
-            });
+        let Some(culler) = &self.entity_culler else {
+            return;
+        };
+        let hidden = culler.hidden(vertices, start, |pos| {
+            let state = self.world.block(pos[0], pos[1], pos[2]);
+            if !opaque(self.res.facts().get(state)) {
+                return false;
+            }
+            let Some(y) = pos[1].checked_sub(MIN_Y) else {
+                return false;
+            };
+            let section = (pos[0] >> 4, y.div_euclid(16), pos[2] >> 4);
+            // Newly edited or not-yet-uploaded terrain is not an occluder.
+            self.renderer
+                .as_ref()
+                .is_some_and(|r| r.has_section(section))
+                && !self.world.dirty_sections.contains(&section)
+                && !self.streaming.is_meshing(section)
+                && !self.pending_uploads.iter().any(|(key, _)| *key == section)
+        });
+        // A shader pack's shadow pass still draws what the camera cannot see.
+        if hidden && !(self.pack_shadow_casters.0 && self.hide_spans_from(start, vertices.len())) {
+            vertices.truncate(start);
         }
     }
 }
diff --git a/crates/horizon-client/src/game/perspective.rs b/crates/horizon-client/src/game/perspective.rs
index bd2721648..caf49883b 100644
--- a/crates/horizon-client/src/game/perspective.rs
+++ b/crates/horizon-client/src/game/perspective.rs
@@ -412,7 +412,8 @@ impl Game<'_> {
     }
     /// Whether the player's own model shows in the world view.
     fn player_model_shown(&self) -> bool {
-        !self.camera_type.first_person()
+        // A shader pack's shadow pass draws the player in first person too (shadowPlayer).
+        (!self.camera_type.first_person() || self.pack_shadow_casters.1)
             && self.sleeping.is_none()
             && !self.spectator()
             && self.potions.effects.get("minecraft:invisibility").is_none()
diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index f0087c4b0..f534e8391 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -232,6 +232,32 @@ impl Game<'_> {
                     .unwrap_or(ids.missing_block)
             });
         self.push_span(start, "BLOCK_ENTITIES", id);
+        let emission = self
+            .res
+            .facts()
+            .get(horizon_world::registry::BlockStateId(state))
+            .emission;
+        if let Some(last) = self.entity_spans.borrow_mut().last_mut() {
+            last.emissive = emission > 0;
+        }
+    }
+
+    /// Starts the span of the local player's model; `hidden` in first person, where only a
+    /// pack's shadow pass draws it.
+    pub(super) fn mark_player(&self, start: usize, hidden: bool) {
+        self.mark_entity(start, "minecraft:player");
+        if self.pack_ids.is_some()
+            && let Some(last) = self.entity_spans.borrow_mut().last_mut()
+        {
+            last.player = true;
+            last.hidden = hidden;
+        }
+    }
+
+    /// Marks vertices `start..end` (one entity) as hidden from the camera, for an entity
+    /// Horizon's culling would drop but a pack's shadow pass still draws (`EntitySpan::hide`).
+    pub(super) fn hide_spans_from(&self, start: usize, end: usize) -> bool {
+        EntitySpan::hide(&mut self.entity_spans.borrow_mut(), start, end)
     }
 
     /// Starts a span of geometry that is not an entity (`PARTICLES`, `DESTROY`...).
@@ -247,7 +273,7 @@ impl Game<'_> {
             start: start as u32,
             stage: horizon_shaders::render_stage(stage),
             id,
-            translucent: false,
+            ..Default::default()
         };
         // A span that drew nothing gives way to the next.
         match spans.last_mut() {
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index b21c846a5..523a2801b 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2560,6 +2560,18 @@ impl Renderer {
     pub fn section_count(&self) -> usize {
         self.sections.len()
     }
+    /// What a shader pack's shadow pass draws of the entities this frame: (entities or block
+    /// entities other than the player, so those Horizon's culling hides from the camera are
+    /// kept for it; the local player, so its model is built in first person too). (false,
+    /// false) without a pack or its shadow pass.
+    pub fn pack_shadow_casters(&self) -> (bool, bool) {
+        let Some((_, Some(post))) = &self.pack_post else {
+            return (false, false);
+        };
+        let c = post.shadow_casters();
+        ((c.entities && !c.only_player) || c.blocks, c.entities)
+    }
+
     pub fn has_section(&self, key: SectionKey) -> bool {
         self.sections.contains(key)
     }
diff --git a/crates/horizon-client/src/gfx/pack_draw.rs b/crates/horizon-client/src/gfx/pack_draw.rs
index d19c3b4db..a558084f4 100644
--- a/crates/horizon-client/src/gfx/pack_draw.rs
+++ b/crates/horizon-client/src/gfx/pack_draw.rs
@@ -7,7 +7,7 @@ use horizon_shaders::{RENDER_STAGES, render_stage};
 /// Where a run of `Frame::entities` begins, and what it is (slice 7): the run lasts until the
 /// next span. Recorded only while a shader pack draws entities, so Horizon's own frames carry
 /// none; Horizon itself still draws the whole list at once.
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct EntitySpan {
     /// The first vertex.
     pub start: u32,
@@ -18,6 +18,44 @@ pub struct EntitySpan {
     pub id: i32,
     /// An entity part that blends (a name tag, a shadow): `gbuffers_entities_translucent`.
     pub translucent: bool,
+    /// Hidden from the camera (Horizon's entity culling, the player in first person): only the
+    /// shadow pass draws it.
+    pub hidden: bool,
+    /// The local player (`shadowPlayer`).
+    pub player: bool,
+    /// A block entity whose block emits light (`shadowLightBlockEntities`).
+    pub emissive: bool,
+}
+
+impl EntitySpan {
+    /// Marks vertices `start..end` of `spans`' list (one entity) as hidden: the span covering
+    /// `start` is split there, the spans inside are hidden, and the geometry after `end` goes
+    /// on in the last span's kind. False when no span covers `start`.
+    pub fn hide(spans: &mut Vec<EntitySpan>, start: usize, end: usize) -> bool {
+        let Some(i) = spans.iter().rposition(|s| s.start as usize <= start) else {
+            return false;
+        };
+        let after = spans[spans.len() - 1];
+        if spans[i].start as usize != start {
+            let split = EntitySpan {
+                start: start as u32,
+                ..spans[i]
+            };
+            spans.insert(i + 1, split);
+        }
+        for s in spans.iter_mut().skip(i) {
+            if s.start as usize >= start {
+                s.hidden = true;
+            }
+        }
+        if end > start {
+            spans.push(EntitySpan {
+                start: end as u32,
+                ..after
+            });
+        }
+        true
+    }
 }
 
 /// `HzDraw`'s size: `renderStage`, `entityId`, `blockEntityId`, a pad, `entityColor`.
@@ -81,3 +119,34 @@ impl DrawUniforms {
         pass.set_bind_group(2, &self.group, &[self.stride * render_stage(stage)]);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::EntitySpan;
+
+    fn span(start: u32, id: i32) -> EntitySpan {
+        EntitySpan {
+            start,
+            id,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn hide_splits_the_span_around_one_entity() {
+        // Two cows in one span: the second (vertices 8..16) is hidden.
+        let mut spans = vec![span(0, 7)];
+        assert!(EntitySpan::hide(&mut spans, 8, 16));
+        let hidden = EntitySpan {
+            hidden: true,
+            ..span(8, 7)
+        };
+        assert_eq!(spans, [span(0, 7), hidden, span(16, 7)]);
+        // An entity with its own span and a part after it (armour) is hidden whole.
+        let mut spans = vec![span(0, 1), span(4, 2), span(6, 3)];
+        assert!(EntitySpan::hide(&mut spans, 4, 10));
+        assert!(!spans[0].hidden && spans[1].hidden && spans[2].hidden);
+        assert_eq!(spans[3], span(10, 3));
+        assert!(!EntitySpan::hide(&mut Vec::new(), 0, 4));
+    }
+}
diff --git a/crates/horizon-client/src/gfx/pack_entities.rs b/crates/horizon-client/src/gfx/pack_entities.rs
index 30fa70880..ab3c66c69 100644
--- a/crates/horizon-client/src/gfx/pack_entities.rs
+++ b/crates/horizon-client/src/gfx/pack_entities.rs
@@ -170,6 +170,30 @@ pub(super) struct Draw {
     pub slot: u32,
 }
 
+/// Which entity runs a pack's shadow pass draws (2.4, 3.2).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct Casters {
+    /// `shadow_entities` (or `shadow`) draws entities...
+    pub entities: bool,
+    /// ...only the local player (`shadowPlayer` without `shadowEntities`).
+    pub only_player: bool,
+    /// `shadow_block` (or `shadow`) draws block entities...
+    pub blocks: bool,
+    /// ...only those whose block emits light (`shadowLightBlockEntities`).
+    pub only_lit: bool,
+}
+
+impl Casters {
+    /// Whether the shadow pass draws `span`'s run, of kind `program`.
+    pub fn cast(&self, span: &EntitySpan, program: usize) -> bool {
+        match program {
+            ENTITY => self.entities && (!self.only_player || span.player),
+            BLOCK => self.blocks && (!self.only_lit || span.emissive),
+            _ => false,
+        }
+    }
+}
+
 /// The vertices and per-draw uniforms of the runs a pack draws, rebuilt each frame.
 pub(super) struct PackEntities {
     vertices: wgpu::Buffer,
@@ -285,7 +309,7 @@ impl PackEntities {
     /// Splits `entities` between the pack, which draws the runs of `spans` its programs cover
     /// (`drawn`: whether it has `gbuffers_entities`, `gbuffers_block` or their fallbacks), and
     /// Horizon, which draws the rest (`rest`). Uploads the pack's part, and the runs its shadow
-    /// programs draw (`shadow`: entities, block entities).
+    /// programs draw (`shadow`). Runs hidden from the camera only ever cast shadows.
     #[allow(clippy::too_many_arguments)]
     pub fn prepare(
         &mut self,
@@ -295,7 +319,7 @@ impl PackEntities {
         entities: &[Vertex],
         spans: &[EntitySpan],
         drawn: [bool; PROGRAMS],
-        shadow: [bool; 2],
+        shadow: Casters,
         rest: &mut Vec<Vertex>,
     ) {
         self.draws.clear();
@@ -307,9 +331,9 @@ impl PackEntities {
         for (span, range) in runs(entities.len(), spans) {
             let run = &entities[range];
             let program = program_of(&span).filter(|_| plain(run));
-            let pack = program.is_some_and(|p| drawn[p]);
-            let casts = program.is_some_and(|p| shadow.get(p).copied().unwrap_or(false));
-            if !pack {
+            let pack = program.is_some_and(|p| drawn[p]) && !span.hidden;
+            let casts = program.is_some_and(|p| shadow.cast(&span, p));
+            if !pack && !span.hidden {
                 rest.extend_from_slice(run);
             }
             let Some(program) = program.filter(|_| (pack || casts) && !run.is_empty()) else {
@@ -446,7 +470,7 @@ mod tests {
             start,
             stage: render_stage(stage),
             id,
-            translucent: false,
+            ..Default::default()
         };
         let spans = [
             span(2, "ENTITIES", 7),
@@ -473,5 +497,28 @@ mod tests {
         assert_eq!(entity_color(1)[0], 1.0);
         assert!((entity_color(1)[3] - (1.0 - 178.0 / 255.0)).abs() < 1e-6);
         assert_eq!(entity_color(0), [0.0; 4]);
+        // The shadow pass: entities, the player alone, block entities, those that emit light.
+        let all = Casters {
+            entities: true,
+            blocks: true,
+            ..Default::default()
+        };
+        let player = EntitySpan {
+            player: true,
+            ..spans[0]
+        };
+        let lit = EntitySpan {
+            emissive: true,
+            ..spans[2]
+        };
+        assert!(all.cast(&spans[0], ENTITY) && all.cast(&spans[2], BLOCK));
+        assert!(!all.cast(&spans[1], PARTICLE));
+        let some = Casters {
+            only_player: true,
+            only_lit: true,
+            ..all
+        };
+        assert!(!some.cast(&spans[0], ENTITY) && some.cast(&player, ENTITY));
+        assert!(!some.cast(&spans[2], BLOCK) && some.cast(&lit, BLOCK));
     }
 }
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index da174b022..19f0d7349 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -149,6 +149,8 @@ struct Entities {
     late: [bool; PROGRAMS],
     /// What draws entities and block entities into the shadow map (2.4).
     shadow: [Option<Pass>; 2],
+    /// Only the player, only block entities that emit light (3.2).
+    only: (bool, bool),
 }
 
 impl Entities {
@@ -1086,6 +1088,7 @@ impl PackPost {
             post.particles,
         ];
         let late = [false, false, post.translucent_late, post.particles_late];
+        let shadow_only = (post.shadow_only_player, post.shadow_only_lit_blocks);
         let shadow_programs = [post.shadow_entities, post.shadow_block];
         let entity_vertices = (programs.iter().chain(&shadow_programs))
             .any(Option::is_some)
@@ -1114,6 +1117,7 @@ impl PackPost {
                 passes: entity_passes,
                 late,
                 shadow: shadow_entities,
+                only: shadow_only,
             });
         let cloud_geometry = world.clouds.map(|layout| Geometry {
             buffers: &entity_buffers,
@@ -1221,10 +1225,17 @@ impl PackPost {
         // Timed (and labelled) apart from the terrain's shadow pass, which may run the same
         // program.
         let mut entities = entities;
-        for (part, pass) in (entities.iter_mut()).flat_map(|e| parts.iter().zip(&mut e.shadow)) {
-            if let Some(p) = pass {
-                notes.push(format!("{part} cast shadows with {}", p.name));
-                p.name.push_str(&format!(" ({part})"));
+        for e in entities.iter_mut() {
+            let only = [
+                (e.only.0, " (only the player)"),
+                (e.only.1, " (only those that emit light)"),
+            ];
+            for ((part, pass), (only, which)) in parts.iter().zip(&mut e.shadow).zip(only) {
+                if let Some(p) = pass {
+                    let which = if only { which } else { "" };
+                    notes.push(format!("{part}{which} cast shadows with {}", p.name));
+                    p.name.push_str(&format!(" ({part})"));
+                }
             }
         }
         let depth1 = water.is_some()
@@ -1874,17 +1885,13 @@ impl PackPost {
         spans: &[super::pack_draw::EntitySpan],
         rest: &mut Vec<super::Vertex>,
     ) {
+        let shadow = self.shadow_casters();
         let Some(e) = &mut self.entities else {
             rest.clear();
             rest.extend_from_slice(entities);
             return;
         };
         let drawn = e.passes.each_ref().map(Option::is_some);
-        // Only while the shadow pass draws this frame.
-        let shadow = e
-            .shadow
-            .each_ref()
-            .map(|p| p.is_some() && self.shadow_targets.is_some());
         e.geometry.prepare(
             device,
             queue,
@@ -1897,6 +1904,23 @@ impl PackPost {
         );
     }
 
+    /// Which entity runs the shadow pass draws: none without it.
+    pub fn shadow_casters(&self) -> super::pack_entities::Casters {
+        let Some(e) = self
+            .entities
+            .as_ref()
+            .filter(|_| self.shadow_targets.is_some())
+        else {
+            return Default::default();
+        };
+        super::pack_entities::Casters {
+            entities: e.shadow[0].is_some(),
+            only_player: e.only.0,
+            blocks: e.shadow[1].is_some(),
+            only_lit: e.only.1,
+        }
+    }
+
     /// Whether the pack draws entities or block entities itself.
     pub fn has_entities(&self) -> bool {
         self.entities.is_some()
diff --git a/crates/horizon-shaders/src/post.rs b/crates/horizon-shaders/src/post.rs
index 715dca257..fe5b1c63f 100644
--- a/crates/horizon-shaders/src/post.rs
+++ b/crates/horizon-shaders/src/post.rs
@@ -252,6 +252,11 @@ pub struct Post {
     /// `shadow`) from the light, unless `shadowEntities`/`shadowBlockEntities` is false.
     pub shadow_entities: Option<PostProgram>,
     pub shadow_block: Option<PostProgram>,
+    /// `shadowEntities=false` with `shadowPlayer=true`: of the entities, only the player casts.
+    pub shadow_only_player: bool,
+    /// `shadowBlockEntities=false` with `shadowLightBlockEntities=true`: only block entities
+    /// whose block emits light cast.
+    pub shadow_only_lit_blocks: bool,
     /// `shadowcomp`..`shadowcomp99`, after the shadow pass (2.1).
     pub shadow_comp: Vec<PostProgram>,
     /// Translucent entities draw after deferred (`separateEntityDraws`, 3.2).
@@ -323,6 +328,8 @@ pub fn load_post(
         shadow_water: None,
         shadow_entities: None,
         shadow_block: None,
+        shadow_only_player: false,
+        shadow_only_lit_blocks: false,
         shadow_comp: Vec::new(),
         translucent_late: false,
         particles_late: false,
@@ -545,18 +552,23 @@ fn load_shadow(
         })
     };
     // `shadowTerrain`, `shadowTranslucent`, `shadowEntities` and `shadowBlockEntities` (3.2)
-    // leave their part out of the shadow pass; all are on by default (OQ-19).
+    // leave their part out of the shadow pass; all are on by default (OQ-19). `shadowPlayer`
+    // and `shadowLightBlockEntities` (E, off by default) keep the player, and block entities
+    // that emit light, when the first two are off.
     let keep = |key: &str| properties.get(key).is_none_or(|v| v.trim() != "false");
+    let set = |key: &str| properties.get(key).is_some_and(|v| v.trim() == "true");
+    let only_player = !keep("shadowEntities") && set("shadowPlayer");
+    let only_lit = !keep("shadowBlockEntities") && set("shadowLightBlockEntities");
     let shadow = keep("shadowTerrain")
         .then(|| load(&["shadow"], terrain))
         .flatten();
     let water = keep("shadowTranslucent")
         .then(|| load(&["shadow_water", "shadow"], terrain))
         .flatten();
-    let shadow_entities = keep("shadowEntities")
+    let shadow_entities = (keep("shadowEntities") || only_player)
         .then(|| load(&["shadow_entities", "shadow"], entities))
         .flatten();
-    let shadow_block = keep("shadowBlockEntities")
+    let shadow_block = (keep("shadowBlockEntities") || only_lit)
         .then(|| load(&["shadow_block", "shadow"], entities))
         .flatten();
     if shadow.is_none() && terrain.is_some() {
@@ -569,6 +581,8 @@ fn load_shadow(
     loader.post.shadow_water = water;
     loader.post.shadow_entities = shadow_entities;
     loader.post.shadow_block = shadow_block;
+    loader.post.shadow_only_player = only_player;
+    loader.post.shadow_only_lit_blocks = only_lit;
 }
 
 struct Loader<'a> {
@@ -892,6 +906,13 @@ mod tests {
         assert!(
             off.shadow.is_some() && off.shadow_entities.is_none() && off.shadow_block.is_none()
         );
+        // shadowPlayer and shadowLightBlockEntities keep a part of each.
+        let some = load(
+            "shadowEntities=false\nshadowPlayer=true\nshadowBlockEntities=false\nshadowLightBlockEntities=true",
+        );
+        assert!(some.shadow_entities.is_some() && some.shadow_only_player);
+        assert!(some.shadow_block.is_some() && some.shadow_only_lit_blocks);
+        assert!(!post.shadow_only_player && !post.shadow_only_lit_blocks);
         let comp: Vec<_> = post
             .shadow_comp
             .iter()

From b3e400a52673862fa237ef4341ba21d4440d3c52 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:25:37 +0100
Subject: [PATCH 182/270] Renderer: sprite arrays OpenGL can view as arrays

wgpu's GL backend picks a texture's target from its layer count when it creates it: one layer makes
a 2D texture and a multiple of six on a square texture a cube map, and neither can be bound as
terrain.wgsl's texture_2d_array. On GL, the 1-layer stand-in for unused sprite arrays gets two
layers and a sprite array of 1 or 6n layers one empty layer more. Other backends are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index b55022510..a02e6eb7f 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -516,6 +516,18 @@ fn sprite_split() -> u32 {
 }
 /// Sprite arrays terrain.wgsl binds (`sprites`, `sprites_1`...).
 const SPRITE_ARRAYS: u32 = 8;
+/// The layers to give a square texture of `count` layers viewed as a 2D
+/// array. wgpu's OpenGL backend picks a texture's target from its layer
+/// count when it is created: one layer makes a 2D texture and a multiple of
+/// six a cube map, neither of which can be viewed as an array.
+fn array_layers(count: u32, gl: bool) -> u32 {
+    match count {
+        _ if !gl => count,
+        0 | 1 => 2,
+        n if n % 6 == 0 => n + 1,
+        n => n,
+    }
+}
 /// The views of terrain.wgsl's sprite arrays, the unused ones a 1-layer
 /// stand-in.
 fn sprite_views(
@@ -1312,13 +1324,17 @@ impl Renderer {
             PreparedTextures::new(sprite_pixels, sprite_size, layers, sprite_mips, forcefield)
         });
         let mut mip_levels = 1;
+        let gl = adapter.get_info().backend == wgpu::Backend::Gl;
         let sprite_textures: Vec<wgpu::Texture> = prepared
             .sprites
             .into_iter()
             .enumerate()
-            .map(|(array, (mips, levels))| {
+            .map(|(array, (mut mips, levels))| {
                 let first = array as u32 * split;
-                let count = layers.saturating_sub(first).clamp(1, split);
+                let used = layers.saturating_sub(first).clamp(1, split);
+                let count = array_layers(used, gl);
+                // The extra layers are empty.
+                mips.resize(mips.len() / used as usize * count as usize, 0);
                 mip_levels = levels;
                 device.create_texture_with_data(
                     &queue,
@@ -1359,7 +1375,7 @@ impl Renderer {
                 size: wgpu::Extent3d {
                     width: 1,
                     height: 1,
-                    depth_or_array_layers: 1,
+                    depth_or_array_layers: array_layers(1, gl),
                 },
                 mip_level_count: 1,
                 sample_count: 1,
@@ -4560,6 +4576,13 @@ mod tests {
         }
     }
     #[test]
+    fn gl_sprite_arrays_are_neither_2d_textures_nor_cube_maps() {
+        for (count, gl) in [(1, 2), (2, 2), (5, 5), (6, 7), (12, 13), (2048, 2048)] {
+            assert_eq!(super::array_layers(count, true), gl);
+            assert_eq!(super::array_layers(count, false), count);
+        }
+    }
+    #[test]
     fn entity_shader_validates_with_its_overlay_constants() {
         let module = naga::front::wgsl::parse_str(&super::entity_shader()).unwrap();
         naga::valid::Validator::new(

From 1a16e35aaa45800285fca7d5be2a07e48f0421c0 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:25:37 +0100
Subject: [PATCH 183/270] Animated sprites without compute shaders (OpenGL
 before 4.3)

SpriteAnimator wrote every changed sprite with a compute pass, which OpenGL 3.3 to 4.2 has no
equivalent for in wgpu: creating the pipeline failed. Without compute shaders and storage, the same
jobs now run on the CPU with animate.wgsl's integer mix, and each level is copied into its layer
through the upload belt. The GPU test runs both paths against the same CPU reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs         |   1 +
 crates/horizon-client/src/gfx/animate.rs | 162 +++++++++++++++++++++--
 2 files changed, 150 insertions(+), 13 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index a02e6eb7f..baa8c5099 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -1368,6 +1368,7 @@ impl Renderer {
             sprite_mips,
             &sprite_textures,
             split,
+            animate::SpriteAnimator::compute(&adapter, &device),
         );
         let sprite_unused = device
             .create_texture(&wgpu::TextureDescriptor {
diff --git a/crates/horizon-client/src/gfx/animate.rs b/crates/horizon-client/src/gfx/animate.rs
index b7c44429b..c94d8034e 100644
--- a/crates/horizon-client/src/gfx/animate.rs
+++ b/crates/horizon-client/src/gfx/animate.rs
@@ -10,6 +10,10 @@
 //! frames. Blending on the CPU at the array's size and copying every changed
 //! sprite level by level (a copy command each, a blit each in Mesa) was about
 //! a fifth of the render thread on an integrated GPU.
+//!
+//! Without compute shaders (OpenGL before 4.3, the last fallback) the same
+//! jobs run on the CPU, the same integer mix as `animate.wgsl`, and each
+//! changed level is copied into its layer.
 use super::upload::Uploads;
 use crate::mipmap::Settings;
 use crate::sprites::{FrameBlend, SpriteAnimation};
@@ -38,17 +42,32 @@ struct Sprite {
 struct Group {
     /// Where its jobs start in `SpriteAnimator::jobs`, in bytes.
     offset: u64,
-    /// One bind group per mip level of the array.
+    /// One bind group per mip level of the array (none on the CPU).
     levels: Vec<wgpu::BindGroup>,
     /// This tick's jobs.
     jobs: Vec<u8>,
+    /// Its sprite array and its frames, for the CPU.
+    array: usize,
+    buffer: usize,
+}
+
+/// Where the jobs run.
+enum Writer {
+    Gpu {
+        jobs: wgpu::Buffer,
+        pipeline: wgpu::ComputePipeline,
+    },
+    /// Every frames buffer's words, and the sprite arrays to copy into.
+    Cpu {
+        frames: Vec<Vec<u8>>,
+        textures: Vec<wgpu::Texture>,
+    },
 }
 
 pub(super) struct SpriteAnimator {
     sprites: Vec<Sprite>,
     groups: Vec<Group>,
-    jobs: wgpu::Buffer,
-    pipeline: wgpu::ComputePipeline,
+    writer: Writer,
     /// Edge of the arrays' layers.
     size: u32,
     /// The layers the last `animate` rewrote, counted over all arrays.
@@ -57,7 +76,8 @@ pub(super) struct SpriteAnimator {
 
 impl SpriteAnimator {
     /// `textures` are the sprite arrays, `split` layers each, `size` pixels
-    /// wide; `animations` hold their frames at that size.
+    /// wide; `animations` hold their frames at that size. `compute`: whether
+    /// the device runs compute shaders writing storage textures.
     pub fn new(
         device: &wgpu::Device,
         animations: &[SpriteAnimation],
@@ -65,11 +85,17 @@ impl SpriteAnimator {
         settings: &[Settings],
         textures: &[wgpu::Texture],
         split: u32,
+        compute: bool,
     ) -> Self {
         let limits = device.limits();
-        let limit = limits
-            .max_storage_buffer_binding_size
-            .min(limits.max_buffer_size);
+        let limit = if compute {
+            limits
+                .max_storage_buffer_binding_size
+                .min(limits.max_buffer_size)
+        } else {
+            // Word offsets.
+            u64::from(u32::MAX) * 4
+        };
         let mut frames: Vec<Vec<u8>> = Vec::new();
         // Each group's sprite array and frames buffer.
         let mut keys: Vec<(u32, usize)> = Vec::new();
@@ -119,6 +145,29 @@ impl SpriteAnimator {
                 group,
             });
         }
+        if !compute {
+            let groups = keys
+                .iter()
+                .zip(&counts)
+                .map(|(&(array, buffer), &count)| Group {
+                    offset: 0,
+                    levels: Vec::new(),
+                    jobs: Vec::with_capacity(count * JOB_BYTES),
+                    array: array as usize,
+                    buffer,
+                })
+                .collect();
+            return Self {
+                sprites,
+                groups,
+                writer: Writer::Cpu {
+                    frames,
+                    textures: textures.to_vec(),
+                },
+                size,
+                changed: Vec::new(),
+            };
+        }
         let frames: Vec<_> = frames
             .iter()
             .map(|data| {
@@ -198,19 +247,33 @@ impl SpriteAnimator {
                     offset,
                     levels,
                     jobs: Vec::with_capacity(count * JOB_BYTES),
+                    array: array as usize,
+                    buffer,
                 }
             })
             .collect();
         Self {
             sprites,
             groups,
-            jobs,
-            pipeline,
+            writer: Writer::Gpu { jobs, pipeline },
             size,
             changed: Vec::new(),
         }
     }
 
+    /// Whether the jobs can run on the GPU: compute shaders writing a
+    /// storage texture and reading two storage buffers (not OpenGL before
+    /// 4.3).
+    pub fn compute(adapter: &wgpu::Adapter, device: &wgpu::Device) -> bool {
+        let limits = device.limits();
+        adapter
+            .get_downlevel_capabilities()
+            .flags
+            .contains(wgpu::DownlevelFlags::COMPUTE_SHADERS)
+            && limits.max_storage_textures_per_shader_stage >= 1
+            && limits.max_storage_buffers_per_shader_stage >= 2
+    }
+
     /// The layers the last `animate` rewrote (for the shader pack atlas).
     pub fn changed(&self) -> &[u32] {
         &self.changed
@@ -227,14 +290,47 @@ impl SpriteAnimator {
         if self.collect(tick) == 0 {
             return;
         }
+        let (jobs, pipeline) = match &self.writer {
+            Writer::Gpu { jobs, pipeline } => (jobs, pipeline),
+            Writer::Cpu { frames, textures } => {
+                for group in &mut self.groups {
+                    let (frames, texture) = (&frames[group.buffer], &textures[group.array]);
+                    for job in group.jobs.as_chunks::<JOB_BYTES>().0 {
+                        let (words, _) = job.as_chunks::<4>();
+                        let job: [u32; 5] = std::array::from_fn(|i| u32::from_le_bytes(words[i]));
+                        for level in 0..texture.mip_level_count() {
+                            let width = self.size >> level;
+                            uploads.texture(
+                                encoder,
+                                wgpu::TexelCopyTextureInfo {
+                                    texture,
+                                    mip_level: level,
+                                    origin: wgpu::Origin3d {
+                                        x: 0,
+                                        y: 0,
+                                        z: job[0],
+                                    },
+                                    aspect: wgpu::TextureAspect::All,
+                                },
+                                width,
+                                width,
+                                &mix_level(frames, job, width),
+                            );
+                        }
+                    }
+                    group.jobs.clear();
+                }
+                return;
+            }
+        };
         for group in &self.groups {
-            uploads.buffer(encoder, &self.jobs, group.offset, &group.jobs);
+            uploads.buffer(encoder, jobs, group.offset, &group.jobs);
         }
         let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
             label: Some("Animated sprites"),
             timestamp_writes: None,
         });
-        pass.set_pipeline(&self.pipeline);
+        pass.set_pipeline(pipeline);
         for group in &mut self.groups {
             let count = (group.jobs.len() / JOB_BYTES) as u32;
             if count == 0 {
@@ -278,6 +374,33 @@ impl SpriteAnimator {
     }
 }
 
+/// `animate.wgsl` on the CPU: one `width` wide level of a job
+/// (`[layer, current, next, millis, edge]`) from `frames`' chains.
+fn mix_level(frames: &[u8], [_, current, next, millis, edge]: [u32; 5], width: u32) -> Vec<u8> {
+    let mut out = Vec::with_capacity((width * width * 4) as usize);
+    for y in 0..width {
+        for x in 0..width {
+            let texel = if width >= edge {
+                let scale = width / edge;
+                y / scale * edge + x / scale
+            } else {
+                4 * (edge * edge - width * width) / 3 + y * width + x
+            };
+            let at = |chain: u32| ((chain + texel) * 4) as usize;
+            let a = &frames[at(current)..at(current) + 4];
+            if millis == 0 {
+                out.extend_from_slice(a);
+                continue;
+            }
+            let b = &frames[at(next)..at(next) + 4];
+            out.extend(a.iter().zip(b).map(|(&a, &b)| {
+                ((u32::from(a) * (1000 - millis) + u32::from(b) * millis + 500) / 1000) as u8
+            }));
+        }
+    }
+    out
+}
+
 /// The mip chain a frame's layer is made of, and its first level's edge.
 /// `mipmap::generate` makes a sprite scaled up by whole pixels to the
 /// array's size from its own size's chain, its first level repeated into the
@@ -512,6 +635,16 @@ mod tests {
 
     #[test]
     fn gpu_layers_match_the_cpu_chains_every_tick() {
+        layers_match_the_cpu_chains_every_tick(true);
+    }
+
+    /// Without compute shaders (OpenGL before 4.3): the same layers.
+    #[test]
+    fn copied_layers_match_the_cpu_chains_every_tick() {
+        layers_match_the_cpu_chains_every_tick(false);
+    }
+
+    fn layers_match_the_cpu_chains_every_tick(compute: bool) {
         let Some((device, queue)) = device() else {
             return;
         };
@@ -552,12 +685,15 @@ mod tests {
                     sample_count: 1,
                     dimension: wgpu::TextureDimension::D2,
                     format: wgpu::TextureFormat::Rgba8Unorm,
-                    usage: wgpu::TextureUsages::STORAGE_BINDING | wgpu::TextureUsages::COPY_SRC,
+                    usage: wgpu::TextureUsages::STORAGE_BINDING
+                        | wgpu::TextureUsages::COPY_SRC
+                        | wgpu::TextureUsages::COPY_DST,
                     view_formats: &[],
                 })
             })
             .collect();
-        let mut animator = SpriteAnimator::new(&device, &animations, size, &mips, &textures, split);
+        let mut animator =
+            SpriteAnimator::new(&device, &animations, size, &mips, &textures, split, compute);
         let mut uploads = Uploads::new(&device);
         let mut writes = Vec::new();
         for tick in [0, 0, 1, 2, 3, 4, 7, 7, 12, 30] {

From 72de6e0b70aece450db738b421222b4ec9b6bd78 Mon Sep 17 00:00:00 2001
From: vlesmentie <129341611+vlesmentie@users.noreply.github.com>
Date: Sun, 25 Oct 2026 17:25:48 -0300
Subject: [PATCH 184/270] Water cauldrons put out a burning player and lose a
 level

On top of the lava cauldron's inside test: water and powder snow
cauldrons are no longer skipped. Their entity-inside shape is the
cauldron's or their content, Block.column(12, 4, 6 + 3 per level), and
LayeredCauldronBlock.entityInside applies: on a server, a burning
player first asks for handleEntityOnFireInside (runBefore EXTINGUISH),
which lowers the fill level (lowerFillLevel, a powder snow cauldron
turning to water of its level first, block_change with no source); then
EXTINGUISH (Entity.clearFire) puts the fire out.

Fixes #1330.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/cauldron.rs         |  34 +++++
 crates/horizon-client/src/game.rs             |  30 +++++
 crates/horizon-client/src/game/lan_actions.rs |   6 +
 crates/horizon-client/src/motion.rs           | 120 +++++++++++++++---
 4 files changed, 173 insertions(+), 17 deletions(-)

diff --git a/crates/horizon-client/src/cauldron.rs b/crates/horizon-client/src/cauldron.rs
index 9fbe1179f..03fb0676d 100644
--- a/crates/horizon-client/src/cauldron.rs
+++ b/crates/horizon-client/src/cauldron.rs
@@ -87,6 +87,19 @@ fn filled(player: &mut dyn Player, new: ItemStack, limit_creative: bool) {
     }
 }
 
+/// `LayeredCauldronBlock.handleEntityOnFireInside`: a burning entity in a
+/// water cauldron lowers it a level; a powder snow cauldron becomes a water
+/// cauldron of its level first, then lowers.
+pub fn extinguished(cauldron: &BlockState) -> BlockState {
+    if cauldron.name == "minecraft:powder_snow_cauldron" {
+        let mut water = cauldron.clone();
+        water.name = "minecraft:water_cauldron".into();
+        lowered(&water)
+    } else {
+        lowered(cauldron)
+    }
+}
+
 /// `LayeredCauldronBlock.lowerFillLevel`.
 fn lowered(cauldron: &BlockState) -> BlockState {
     let level: u8 = cauldron
@@ -296,3 +309,24 @@ pub fn interact(
         _ => pass(),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_burning_entity_lowers_water_and_melts_powder_snow() {
+        let water = |l| state("minecraft:water_cauldron", Some(l));
+        assert_eq!(extinguished(&water(3)), water(2));
+        assert_eq!(extinguished(&water(1)), state("minecraft:cauldron", None));
+        // Powder snow turns to water of its level, then lowers.
+        assert_eq!(
+            extinguished(&state("minecraft:powder_snow_cauldron", Some(3))),
+            water(2)
+        );
+        assert_eq!(
+            extinguished(&state("minecraft:powder_snow_cauldron", Some(1))),
+            state("minecraft:cauldron", None)
+        );
+    }
+}
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 699468651..f75064d76 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -4289,6 +4289,7 @@ impl Game<'_> {
                 MotionEvent::Snowflake { position, velocity } => self.snowflake(position, velocity),
                 MotionEvent::EnterBlock { state } => self.trigger_enter_block(state),
                 MotionEvent::InsidePortal { pos } => self.player_inside_nether_portal(pos),
+                MotionEvent::CauldronExtinguish { pos } => self.cauldron_extinguish(pos),
                 MotionEvent::SmashLanding {
                     state,
                     position,
@@ -8354,6 +8355,35 @@ impl Game<'_> {
         self.level_set(pos, id)?;
         Ok(true)
     }
+    /// `LayeredCauldronBlock.handleEntityOnFireInside` for a burning player
+    /// in the cauldron at `pos` (`mayInteract`: not a spectator): the fill
+    /// level drops (`lowerFillLevel`, a `block_change` with no source). A
+    /// server's cauldron is the server's.
+    pub(super) fn cauldron_extinguish(&mut self, pos: BlockPos) {
+        if self.remote.is_some() {
+            return;
+        }
+        let at = [pos.x, pos.y, pos.z];
+        let registry = self.pack.assets.registry;
+        let Some(old) = registry
+            .state(self.world.block(at[0], at[1], at[2]))
+            .filter(|s| {
+                matches!(
+                    s.name.as_str(),
+                    "minecraft:water_cauldron" | "minecraft:powder_snow_cauldron"
+                )
+            })
+            .cloned()
+        else {
+            return;
+        };
+        let Ok(new) = registry.resolve(&horizon_client::cauldron::extinguished(&old)) else {
+            return;
+        };
+        if self.level_set(at, new).is_ok() {
+            self.post_block_game_event("minecraft:block_change", at, None, Some(new));
+        }
+    }
     fn damage_held(&mut self, amount: u32) {
         if self.creative {
             return;
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 2c7019c73..6090fb896 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -2010,6 +2010,12 @@ impl Game<'_> {
             let _ = w.apply_fire_contact();
             let _ = w.server_hazards_tick(in_wall);
             let mut events = std::mem::take(&mut w.player.events);
+            // LayeredCauldronBlock.handleEntityOnFireInside along those moves.
+            for event in &events {
+                if let MotionEvent::CauldronExtinguish { pos } = event {
+                    game.cauldron_extinguish(*pos);
+                }
+            }
             // ServerGamePacketListenerImpl.handleMovePlayer:
             // Player.checkMovementStatistics for each move.
             for d in travelled {
diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs
index 8637ead1f..5835c4629 100644
--- a/crates/horizon-client/src/motion.rs
+++ b/crates/horizon-client/src/motion.rs
@@ -167,6 +167,11 @@ pub enum MotionEvent {
     InsidePortal {
         pos: BlockPos,
     },
+    /// `LayeredCauldronBlock.handleEntityOnFireInside`: a burning player in
+    /// a water or powder snow cauldron; the server lowers its fill level.
+    CauldronExtinguish {
+        pos: BlockPos,
+    },
     /// `ServerPlayer.checkFallDamage` after a mace smash: block particles
     /// from the landing block, more the further the fall.
     SmashLanding {
@@ -1259,22 +1264,31 @@ impl MotionWorld<'_, '_, '_> {
                 continue;
             }
             let powder_snow = name == "minecraft:powder_snow";
-            let lava_cauldron = name == "minecraft:lava_cauldron";
+            // A filled cauldron's content top in blocks: the lava's 15/16
+            // (LavaCauldronBlock.FILLED_SHAPE), or a layered cauldron's
+            // getPixelContentHeight, 6 + 3 per level (FILLED_SHAPES).
+            let content_top = match name {
+                "minecraft:lava_cauldron" => Some(15.0 / 16.0),
+                "minecraft:water_cauldron" | "minecraft:powder_snow_cauldron" => {
+                    let level = self
+                        .assets
+                        .registry
+                        .state(state)
+                        .and_then(|s| s.properties.get("level"))
+                        .and_then(|l| l.parse::<u8>().ok())
+                        .unwrap_or(1);
+                    Some((6.0 + 3.0 * f64::from(level)) / 16.0)
+                }
+                _ => None,
+            };
             // getEntityInsideCollisionShape is the whole block but for powder
             // snow (its collision shape, the whole block when it is empty),
             // filled cauldrons, end portals and tripwires; Horizon doesn't
-            // follow the player into the water and powder snow cauldrons, end
-            // portals or tripwires yet.
-            if matches!(
-                name,
-                "minecraft:water_cauldron"
-                    | "minecraft:powder_snow_cauldron"
-                    | "minecraft:end_portal"
-                    | "minecraft:tripwire"
-            ) {
+            // follow the player into those last two.
+            if matches!(name, "minecraft:end_portal" | "minecraft:tripwire") {
                 continue;
             }
-            let inside = !(powder_snow || lava_cauldron) || {
+            let inside = !(powder_snow || content_top.is_some()) || {
                 let context = self.context();
                 let binding = self.collision_binding;
                 let shape = binding.collision_shape_with_context(
@@ -1287,12 +1301,12 @@ impl MotionWorld<'_, '_, '_> {
                     || {
                         let offset = Vec3::new(f64::from(p.x), f64::from(p.y), f64::from(p.z));
                         let mut boxes: Vec<_> = shape.moved(offset).boxes().to_vec();
-                        if lava_cauldron {
-                            // LavaCauldronBlock.FILLED_SHAPE: the cauldron's
-                            // shape or its lava, Block.column(12, 4, 15).
+                        if let Some(top) = content_top {
+                            // The cauldron's shape or its content,
+                            // Block.column(12, 4, top).
                             boxes.push(Aabb::new(
                                 Vec3::new(2.0 / 16.0, 4.0 / 16.0, 2.0 / 16.0).add_vector(offset),
-                                Vec3::new(14.0 / 16.0, 15.0 / 16.0, 14.0 / 16.0).add_vector(offset),
+                                Vec3::new(14.0 / 16.0, top, 14.0 / 16.0).add_vector(offset),
                             ));
                         }
                         self.player
@@ -1302,11 +1316,14 @@ impl MotionWorld<'_, '_, '_> {
                     }
             };
             if inside && visited.insert(p.pack()) {
-                // CactusBlock, CampfireBlock and LavaCauldronBlock.entityInside
-                // (`entity.hurt`).
+                // CactusBlock, CampfireBlock and the cauldrons' entityInside
+                // (`entity.hurt`, the fire and the fill level).
                 match name {
                     "minecraft:cactus" => self.environment_hurt("minecraft:cactus", 1.0)?,
                     "minecraft:lava_cauldron" => self.lava_cauldron_inside()?,
+                    "minecraft:water_cauldron" | "minecraft:powder_snow_cauldron" => {
+                        self.layered_cauldron_inside(p);
+                    }
                     "minecraft:campfire" | "minecraft:soul_campfire" => {
                         let lit = self
                             .assets
@@ -1372,6 +1389,18 @@ impl MotionWorld<'_, '_, '_> {
         self.player.ignite_for_ticks(300)?;
         self.environment_hurt("minecraft:lava", 4.0)
     }
+    /// `LayeredCauldronBlock.entityInside`: on a server, a burning player
+    /// asks for the cauldron's `handleEntityOnFireInside` (runBefore
+    /// EXTINGUISH, so while still burning), then EXTINGUISH
+    /// (`Entity.clearFire`) puts the fire out.
+    fn layered_cauldron_inside(&mut self, pos: BlockPos) {
+        if self.player.fire_ticks > 0 && !self.player.spectator {
+            self.player
+                .events
+                .push(MotionEvent::CauldronExtinguish { pos });
+        }
+        self.player.fire_ticks = self.player.fire_ticks.min(0);
+    }
     /// `WebBlock.entityInside`: stuck at a quarter of the speed, half with
     /// the Weaving effect.
     fn web_inside(&mut self) {
@@ -2434,6 +2463,63 @@ mod tests {
         assert!(away.fire_ticks <= 0);
     }
 
+    #[test]
+    fn a_water_cauldron_puts_out_a_burning_player() {
+        let root = std::env::var_os("HORIZON_TEST_RESOURCES")
+            .map(std::path::PathBuf::from)
+            .unwrap_or_else(|| {
+                Path::new(env!("CARGO_MANIFEST_DIR"))
+                    .join("../../.local/horizon-client")
+                    .join(horizon_core::VANILLA_VERSION)
+            });
+        if !root.join("movement-properties.nbt").exists() {
+            return;
+        }
+        let assets = Assets::load(&root).unwrap();
+        let render = assets.reload(&root).unwrap();
+        let binding = crate::collisions::load(&root, assets.registry).unwrap();
+        let resources = MotionResources::load(&root, &assets).unwrap();
+        let mut scene = World::test_scene(&assets, &render, 1).unwrap();
+        let water = assets
+            .registry
+            .resolve(&horizon_world::chunk::BlockState {
+                name: "minecraft:water_cauldron".into(),
+                properties: [("level".to_owned(), "3".to_owned())].into(),
+            })
+            .unwrap();
+        scene.set(20, 4, 20, water).unwrap();
+        let mut tick = |player: &mut PlayerMotion| {
+            MotionWorld {
+                entities: &[],
+                player,
+                scene: &mut scene,
+                assets: &assets,
+                collision_binding: &binding,
+                resources: &resources,
+            }
+            .controlled_simulation_tick(Default::default())
+            .unwrap();
+        };
+        let asks = |player: &PlayerMotion| {
+            player
+                .events
+                .iter()
+                .filter(|e| matches!(e, MotionEvent::CauldronExtinguish { .. }))
+                .count()
+        };
+        // Burning, on the cauldron's floor in its water: put out, and the
+        // server is asked to lower the water.
+        let mut burning = PlayerMotion::new(&resources, Vec3::new(20.5, 4.25, 20.5)).unwrap();
+        burning.fire_ticks = 100;
+        tick(&mut burning);
+        assert!(burning.fire_ticks <= 0, "the water must put the fire out");
+        assert_eq!(asks(&burning), 1);
+        // Not burning: nothing to lower.
+        let mut dry = PlayerMotion::new(&resources, Vec3::new(20.5, 4.25, 20.5)).unwrap();
+        tick(&mut dry);
+        assert_eq!(asks(&dry), 0);
+    }
+
     #[test]
     fn server_travel_moves_only_the_velocity() {
         let root = Path::new(env!("CARGO_MANIFEST_DIR"))

From 386912a76d4046a6026e6caa331b5ee5576e217b Mon Sep 17 00:00:00 2001
From: sl4ppleware <66299946+sl4ppleware@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:32:27 +0300
Subject: [PATCH 185/270] Hearts blink again when the server sets health:
 LocalPlayer.hurtTo's damageCooldownTime

---
 crates/horizon-client/src/health.rs | 10 ++++++++--
 crates/horizon-client/src/motion.rs |  5 +++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/health.rs b/crates/horizon-client/src/health.rs
index da40f41fc..25c719bfb 100644
--- a/crates/horizon-client/src/health.rs
+++ b/crates/horizon-client/src/health.rs
@@ -261,11 +261,17 @@ impl PlayerHealth {
         self.hurt_animation_time = 10;
     }
     /// `LocalPlayer.hurtTo` with `flashOnSetHealth`: a drop below the current
-    /// health starts the hurt animation.
+    /// health starts the hurt animation; `damageCooldownTime` (20 on a drop,
+    /// 10 on a gain) is what lets `Hud.extractPlayerHealth` blink the hearts.
     pub fn flash_health_change(&mut self, health: f32) {
         let damage = self.health() - health;
-        if damage > 0.0 {
+        if damage <= 0.0 {
+            if damage < 0.0 {
+                self.hurt.cooldown = 10;
+            }
+        } else {
             self.hurt.last_hurt = damage;
+            self.hurt.cooldown = 20;
             self.animate_hurt();
         }
     }
diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs
index e7809055d..a5e3813b1 100644
--- a/crates/horizon-client/src/motion.rs
+++ b/crates/horizon-client/src/motion.rs
@@ -2934,8 +2934,13 @@ mod tests {
             if client_side {
                 w.player.health.flash_health_change(20.0);
                 assert_eq!(w.player.health.hurt_animation_time, 0);
+                assert_eq!(w.player.health.hurt.cooldown, 0);
                 w.player.health.flash_health_change(12.0);
                 assert_eq!(w.player.health.hurt_animation_time, 10);
+                // LocalPlayer.hurtTo's damageCooldownTime: the HUD's hearts blink.
+                assert_eq!(w.player.health.hurt.cooldown, 20);
+                w.player.health.flash_health_change(25.0);
+                assert_eq!(w.player.health.hurt.cooldown, 10);
             }
         }
     }

From 21203de7f07aec02ac1bb325462c729d9ae8fc38 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:33:05 +0100
Subject: [PATCH 186/270] Animated sprites: the CPU path also when the driver
 cannot build the compute pipeline

An OpenGL driver can list compute shaders among its extensions while wgpu writes GLSL of its core
version, which has none (seen under MESA_GL_VERSION_OVERRIDE=3.3: the pipeline failed and the game
panicked). The pipeline is now created inside error scopes, and a failure falls back to the CPU path
with one warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx/animate.rs | 50 ++++++++++++++++--------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/crates/horizon-client/src/gfx/animate.rs b/crates/horizon-client/src/gfx/animate.rs
index c94d8034e..5a70f3b0f 100644
--- a/crates/horizon-client/src/gfx/animate.rs
+++ b/crates/horizon-client/src/gfx/animate.rs
@@ -77,7 +77,7 @@ pub(super) struct SpriteAnimator {
 impl SpriteAnimator {
     /// `textures` are the sprite arrays, `split` layers each, `size` pixels
     /// wide; `animations` hold their frames at that size. `compute`: whether
-    /// the device runs compute shaders writing storage textures.
+    /// the device says it runs compute shaders writing storage textures.
     pub fn new(
         device: &wgpu::Device,
         animations: &[SpriteAnimation],
@@ -87,8 +87,9 @@ impl SpriteAnimator {
         split: u32,
         compute: bool,
     ) -> Self {
+        let pipeline = if compute { pipeline(device) } else { None };
         let limits = device.limits();
-        let limit = if compute {
+        let limit = if pipeline.is_some() {
             limits
                 .max_storage_buffer_binding_size
                 .min(limits.max_buffer_size)
@@ -145,7 +146,7 @@ impl SpriteAnimator {
                 group,
             });
         }
-        if !compute {
+        let Some(pipeline) = pipeline else {
             let groups = keys
                 .iter()
                 .zip(&counts)
@@ -167,7 +168,7 @@ impl SpriteAnimator {
                 size,
                 changed: Vec::new(),
             };
-        }
+        };
         let frames: Vec<_> = frames
             .iter()
             .map(|data| {
@@ -191,18 +192,6 @@ impl SpriteAnimator {
             usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
             mapped_at_creation: false,
         });
-        let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
-            label: Some("Animated sprites"),
-            source: wgpu::ShaderSource::Wgsl(include_str!("animate.wgsl").into()),
-        });
-        let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
-            label: Some("Animated sprites"),
-            layout: None,
-            module: &module,
-            entry_point: Some("animate"),
-            compilation_options: Default::default(),
-            cache: None,
-        });
         let layout = pipeline.get_bind_group_layout(0);
         let groups = keys
             .iter()
@@ -374,6 +363,35 @@ impl SpriteAnimator {
     }
 }
 
+/// `animate.wgsl`'s pipeline, unless the device fails to make it: an OpenGL
+/// driver can list compute shaders among its extensions while wgpu writes
+/// the GLSL version of its core version, which has none (Mesa's
+/// `MESA_GL_VERSION_OVERRIDE`, older drivers).
+fn pipeline(device: &wgpu::Device) -> Option<wgpu::ComputePipeline> {
+    let validation = device.push_error_scope(wgpu::ErrorFilter::Validation);
+    let internal = device.push_error_scope(wgpu::ErrorFilter::Internal);
+    let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+        label: Some("Animated sprites"),
+        source: wgpu::ShaderSource::Wgsl(include_str!("animate.wgsl").into()),
+    });
+    let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
+        label: Some("Animated sprites"),
+        layout: None,
+        module: &module,
+        entry_point: Some("animate"),
+        compilation_options: Default::default(),
+        cache: None,
+    });
+    let internal = pollster::block_on(internal.pop());
+    match internal.or(pollster::block_on(validation.pop())) {
+        None => Some(pipeline),
+        Some(e) => {
+            log::warn!("Horizon renderer: animated sprites drawn on the CPU ({e})");
+            None
+        }
+    }
+}
+
 /// `animate.wgsl` on the CPU: one `width` wide level of a job
 /// (`[layer, current, next, millis, edge]`) from `frames`' chains.
 fn mix_level(frames: &[u8], [_, current, next, millis, edge]: [u32; 5], width: u32) -> Vec<u8> {

From 61c44c22efe23f9cbc4ac00ef8c8f20a35b00aa4 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:35:12 +0100
Subject: [PATCH 187/270] Mod API: capability render (experimental): HUD shapes
 and camera shake

Mods draw through the game's own renderer, never their own shaders:

- WIT `render`: set-hud(shapes) with fill, quad (any four corners),
  sprite (the game's GUI sprites), item (scaled) and text shapes, up
  to 1024, kept until replaced; gui-size(); shake(strength, seconds).
- Drawn over the HUD after the extras, under chat and screens, hidden
  with F1 (game/mod_render.rs). Colours are 0xAARRGGBB.
- shake turns the view, not the player: jolts fade out squared, add up
  to 1, at most 3 degrees of yaw and 2 of pitch, scaled by Distortion
  Effects (screenEffectScale; 0 turns it off).
- Experimental: the manifest needs experimental = ["render"].
- No mod drawing, no cost: an empty iterator and an is_empty check.
- cargo horizon-mod check reports shakes and HUD shapes. The ui test
  guest gains /render_hud, /render_clear and /render_shake, with a
  sandbox test; HudBatch gets fill_quad.
- Docs: mods.md, stability.md, the changelog, the regenerated reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/cargo-horizon-mod/src/check.rs         |   9 +
 crates/horizon-client/src/game.rs             |   3 +
 crates/horizon-client/src/game/mod_render.rs  | 176 ++++++++++++++++++
 crates/horizon-client/src/game/mods.rs        |  15 +-
 crates/horizon-client/src/hud.rs              |   6 +
 crates/horizon-mod-sdk/src/lib.rs             |   2 +-
 crates/horizon-mod-sdk/wit/horizon.wit        |  82 ++++++++
 crates/horizon-mods/src/manifest.rs           |  11 +-
 crates/horizon-mods/src/runtime.rs            |  81 ++++++++
 crates/horizon-mods/tests/sandbox.rs          |  38 +++-
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  71 ++++++-
 docs/api/mods-reference.md                    |  94 +++++++++-
 docs/api/mods.md                              |   2 +
 docs/api/stability.md                         |   1 +
 docs/mods.md                                  |   5 +-
 15 files changed, 582 insertions(+), 14 deletions(-)
 create mode 100644 crates/horizon-client/src/game/mod_render.rs

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index 5d4150ab9..dfb9820a2 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -198,6 +198,8 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
                 game_time: t,
                 day_time: 1000 + t,
             }),
+            // The GUI of a 1280 x 720 window at scale 3.
+            gui_size: (427.0, 240.0),
         });
         mods.tick(t);
         for _ in 0..FRAMES_PER_TICK {
@@ -217,8 +219,15 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
             Output::Stopped { reason, .. } => return Err(format!("it stopped: {reason}")),
             Output::OpenScreen { .. } => "opened a screen".to_string(),
             Output::CloseScreen { .. } => "closed its screen".to_string(),
+            Output::Shake { strength, seconds } => {
+                format!("shook the camera: {strength:.2} for {seconds:.1} s")
+            }
         });
     }
+    let shapes = mods.hud_shapes().count();
+    if shapes > 0 {
+        report.output.push(format!("drew {shapes} HUD shape(s)"));
+    }
     match failed(&mods) {
         Some(reason) => Err(format!("it stopped: {reason}")),
         None => Ok(()),
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index eabbc22b8..31bfe74b6 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -96,6 +96,7 @@ mod maps;
 mod minecarts;
 mod mob_blocks;
 mod mob_gear;
+mod mod_render;
 mod mods;
 mod mount_menu;
 mod mounts;
@@ -4894,6 +4895,7 @@ impl Game<'_> {
             // Hud: the action bar and titles draw over the hotbar (nextStratum).
             self.draw_boss_bars(&mut batch);
             self.draw_extras(&mut batch);
+            self.draw_mod_shapes(&mut batch);
         }
         if show_hud {
             // Hud.nextContextualInfoState: the jump bar, the experience bar or
@@ -9865,6 +9867,7 @@ impl Game<'_> {
                 self.pitch,
             ),
         };
+        let (view_yaw, view_pitch) = self.shaken_view(view_yaw, view_pitch);
         self.audio
             .set_listener([camera.x, camera.y, camera.z], view_yaw, view_pitch);
         let block = [
diff --git a/crates/horizon-client/src/game/mod_render.rs b/crates/horizon-client/src/game/mod_render.rs
new file mode 100644
index 000000000..1c3a20621
--- /dev/null
+++ b/crates/horizon-client/src/game/mod_render.rs
@@ -0,0 +1,176 @@
+//! Capability `render` (docs/mods.md): the shapes mods keep on the HUD,
+//! drawn by the game's own HUD renderer, and their camera shakes. Mods
+//! never supply shader code. With no mod drawing, each hook here returns
+//! after one check.
+use super::Game;
+use horizon_client::hud::HudBatch;
+#[cfg(feature = "mods")]
+use {
+    horizon_client::{hud::rgba, items::ItemStack, text::Text},
+    horizon_mods::Shape,
+    std::time::Instant,
+};
+
+/// The camera's jolts from `render.shake`, while any is fading.
+#[cfg(feature = "mods")]
+#[derive(Default)]
+pub(super) struct Shake {
+    jolts: Vec<Jolt>,
+}
+
+#[cfg(feature = "mods")]
+struct Jolt {
+    start: Instant,
+    strength: f32,
+    seconds: f32,
+}
+
+/// The HUD batch's colour (ABGR) from a mod's 0xAARRGGBB.
+#[cfg(feature = "mods")]
+fn argb(color: u32) -> u32 {
+    let [a, r, g, b] = color.to_be_bytes();
+    rgba(r, g, b, a)
+}
+
+/// The view's turn at full strength, in degrees: yaw, then pitch.
+#[cfg(feature = "mods")]
+const SHAKE_DEGREES: (f32, f32) = (3.0, 2.0);
+
+#[cfg(feature = "mods")]
+impl Shake {
+    pub(super) fn add(&mut self, strength: f32, seconds: f32) {
+        self.jolts.push(Jolt {
+            start: Instant::now(),
+            strength,
+            seconds,
+        });
+    }
+    /// How far the view turns now (yaw, pitch degrees), `scale` being the
+    /// player's Distortion Effects; fades jolts out and forgets ended ones.
+    fn offset(&mut self, now: Instant, scale: f32) -> (f32, f32) {
+        self.jolts
+            .retain(|j| now.duration_since(j.start).as_secs_f32() < j.seconds);
+        let mut strength = 0.0;
+        for j in &self.jolts {
+            let left = 1.0 - now.duration_since(j.start).as_secs_f32() / j.seconds;
+            strength += j.strength * left * left;
+        }
+        let strength = strength.min(1.0) * scale.clamp(0.0, 1.0);
+        if strength <= 0.0 {
+            return (0.0, 0.0);
+        }
+        // Smooth noise: sines at unrelated rates, so it never repeats visibly.
+        let t = self
+            .jolts
+            .first()
+            .map_or(0.0, |j| now.duration_since(j.start).as_secs_f32());
+        let wave = |a: f32, b: f32, c: f32| {
+            ((t * a).sin() * 0.5 + (t * b).sin() * 0.3 + (t * c).sin() * 0.2).clamp(-1.0, 1.0)
+        };
+        (
+            strength * SHAKE_DEGREES.0 * wave(23.0, 37.3, 51.7),
+            strength * SHAKE_DEGREES.1 * wave(29.1, 43.9, 61.3),
+        )
+    }
+}
+
+#[cfg(not(feature = "mods"))]
+impl Game<'_> {
+    pub(super) fn draw_mod_shapes(&self, _batch: &mut HudBatch) {}
+    pub(super) fn shaken_view(&mut self, yaw: f32, pitch: f32) -> (f32, f32) {
+        (yaw, pitch)
+    }
+}
+
+#[cfg(feature = "mods")]
+impl Game<'_> {
+    /// The running mods' HUD shapes, in order, over the HUD.
+    pub(super) fn draw_mod_shapes(&self, batch: &mut HudBatch) {
+        let atlas = &self.gui.atlas;
+        for shape in self.mods.mods.hud_shapes() {
+            match shape {
+                Shape::Fill(f) => {
+                    let r = f.rect;
+                    batch.fill(atlas, r.x, r.y, r.w, r.h, argb(f.color));
+                }
+                Shape::Quad(q) => {
+                    let (a, b, c, d) = q.corners;
+                    let corners = [[a.x, a.y], [b.x, b.y], [c.x, c.y], [d.x, d.y]];
+                    batch.fill_quad(atlas, corners, argb(q.color));
+                }
+                Shape::Sprite(s) => {
+                    let r = s.rect;
+                    let name = s.sprite.strip_prefix("minecraft:").unwrap_or(&s.sprite);
+                    let name = format!("gui/sprites/{name}");
+                    batch.sprite_scaled(atlas, &name, r.x, r.y, r.w, r.h, argb(s.color));
+                }
+                Shape::Item(i) => {
+                    if self.res.items().get(&i.item).is_none() {
+                        continue;
+                    }
+                    let start = batch.vertices.len();
+                    let stack = ItemStack::new(i.item.as_str(), 1);
+                    self.draw_item_model(batch, &stack, i.at.x, i.at.y);
+                    batch.scale_since(start, i.at.x, i.at.y, i.scale, i.scale);
+                }
+                Shape::Text(t) => {
+                    let text = Text::literal(t.text.clone());
+                    let x = if t.centered {
+                        t.at.x - (HudBatch::text_width(atlas, &t.text) / 2.0).floor()
+                    } else {
+                        t.at.x
+                    };
+                    batch.text_styled(
+                        atlas,
+                        &text,
+                        x,
+                        t.at.y,
+                        argb(t.color | 0xFF00_0000),
+                        t.shadow,
+                    );
+                }
+            }
+        }
+    }
+    /// The view's yaw and pitch after the mods' camera shakes; unchanged
+    /// while none is fading.
+    pub(super) fn shaken_view(&mut self, yaw: f32, pitch: f32) -> (f32, f32) {
+        if self.mods.shake.jolts.is_empty() {
+            return (yaw, pitch);
+        }
+        let scale = self.settings.file.double("screenEffectScale") as f32;
+        let (dy, dp) = self.mods.shake.offset(Instant::now(), scale);
+        (yaw + dy, (pitch + dp).clamp(-90.0, 90.0))
+    }
+}
+
+#[cfg(all(test, feature = "mods"))]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+
+    #[test]
+    fn a_jolt_fades_out_and_distortion_scales_it() {
+        let mut shake = Shake::default();
+        shake.add(1.0, 2.0);
+        let start = shake.jolts[0].start;
+        let at = |s: f32| start + Duration::from_secs_f32(s);
+        let size = |(y, p): (f32, f32)| y.abs() + p.abs();
+        // Off with Distortion Effects at 0, inside the limits otherwise.
+        assert_eq!(shake.offset(at(0.3), 0.0), (0.0, 0.0));
+        let (y, p) = shake.offset(at(0.3), 1.0);
+        assert!(y.abs() <= SHAKE_DEGREES.0 && p.abs() <= SHAKE_DEGREES.1);
+        // Fading: the largest turn over a window shrinks.
+        let mut peak = |from: f32| {
+            (0..50)
+                .map(|i| size(shake.offset(at(from + i as f32 * 0.002), 1.0)))
+                .fold(0.0, f32::max)
+        };
+        let early = peak(0.1);
+        let late = peak(1.6);
+        assert!(late < early, "{late} !< {early}");
+        // Gone once it ends.
+        assert_eq!(shake.offset(at(2.1), 1.0), (0.0, 0.0));
+        assert!(shake.jolts.is_empty());
+    }
+}
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 47a3ce07b..2a07cb940 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -33,7 +33,10 @@ use {
 #[derive(Default)]
 pub(super) struct ModsState {
     #[cfg(feature = "mods")]
-    mods: Mods,
+    pub(super) mods: Mods,
+    /// Capability `render`'s camera shakes.
+    #[cfg(feature = "mods")]
+    pub(super) shake: super::mod_render::Shake,
     /// `--dev-mod PATH`: always on, reloaded when rebuilt.
     pub(super) dev: Vec<PathBuf>,
     /// When dev mods were last checked for a rebuild.
@@ -308,7 +311,11 @@ impl Game<'_> {
             game_time: self.world.game_time.max(0) as u64,
             day_time: self.world.day_time.max(0) as u64,
         });
-        Snapshot { player, clock }
+        Snapshot {
+            player,
+            clock,
+            gui_size: self.gui_size(),
+        }
     }
     /// A game tick.
     pub(super) fn tick_mods(&mut self) {
@@ -382,6 +389,10 @@ impl Game<'_> {
                     self.open_mod_screen(owner, false);
                     continue;
                 }
+                Output::Shake { strength, seconds } => {
+                    self.mods.shake.add(strength, seconds);
+                    continue;
+                }
                 Output::CloseScreen { owner } => {
                     if self.mods.screen.as_ref().is_some_and(|s| s.owner == owner) {
                         self.close_mod_screen(false);
diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs
index 89d1b1c3c..c3a165792 100644
--- a/crates/horizon-client/src/hud.rs
+++ b/crates/horizon-client/src/hud.rs
@@ -835,6 +835,12 @@ impl HudBatch {
         r.v1 = cv;
         self.rect_uv(x, y, w, h, r, color);
     }
+    /// Any four-cornered shape in one colour, corners in order round it.
+    pub fn fill_quad(&mut self, atlas: &HudAtlas, corners: [[f32; 2]; 4], color: u32) {
+        let w = atlas.white;
+        let uv = [(w.u0 + w.u1) / 2.0, (w.v0 + w.v1) / 2.0];
+        self.quad(corners, [uv; 4], color);
+    }
     /// GuiGraphics.fillGradient: `top` to `bottom`, down the rectangle.
     pub fn fill_gradient(
         &mut self,
diff --git a/crates/horizon-mod-sdk/src/lib.rs b/crates/horizon-mod-sdk/src/lib.rs
index aea52339f..8708fb5be 100644
--- a/crates/horizon-mod-sdk/src/lib.rs
+++ b/crates/horizon-mod-sdk/src/lib.rs
@@ -38,7 +38,7 @@ wit_bindgen::generate!({
 
 pub use exports::horizon::mods::events::{Guest as __Guest, Registration};
 pub use exports::horizon::mods::ui_events::Guest as __UiEventsGuest;
-pub use horizon::mods::{chat, game, hud, log, storage, ui};
+pub use horizon::mods::{chat, game, hud, log, render, storage, ui};
 
 /// The game's calls into a mod. Only the hooks [`Registration`] asks for
 /// are called; the others may stay as their defaults.
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 1e49919c3..64bbac592 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -163,6 +163,82 @@ interface ui-events {
     settings-opened: func();
 }
 
+/// Capability `render` (experimental: the manifest needs
+/// `experimental = ["render"]`): shapes the game draws for the mod with its
+/// own renderer, kept until the mod replaces them (no call per frame). A mod
+/// never supplies shader code.
+interface render {
+    /// A rectangle in GUI pixels: the top left corner and the size.
+    record rect {
+        x: f32,
+        y: f32,
+        w: f32,
+        h: f32,
+    }
+    /// A point in GUI pixels from the screen's top left.
+    record point {
+        x: f32,
+        y: f32,
+    }
+    record fill-shape {
+        rect: rect,
+        /// 0xAARRGGBB.
+        color: u32,
+    }
+    /// Any four-cornered shape (a wheel's segment, an arrow): the corners
+    /// in order round it.
+    record quad-shape {
+        corners: tuple<point, point, point, point>,
+        /// 0xAARRGGBB.
+        color: u32,
+    }
+    record sprite-shape {
+        /// One of the game's GUI sprites, as `gui/sprites/` names them
+        /// (`hud/heart/full`, `widget/button`), the resource packs' versions
+        /// included. An unknown one draws nothing.
+        sprite: string,
+        rect: rect,
+        /// A tint, 0xAARRGGBB: 0xFFFFFFFF draws it as it is.
+        color: u32,
+    }
+    record item-shape {
+        /// `minecraft:diamond`, `<mod>:<path>`; an unknown one draws nothing.
+        item: string,
+        /// The icon's top left.
+        at: point,
+        /// 1.0 is the hotbar's 16 × 16.
+        scale: f32,
+    }
+    record text-shape {
+        /// Up to 256 characters, one line.
+        text: string,
+        at: point,
+        /// 0xRRGGBB, as `hud`'s lines.
+        color: u32,
+        /// Centred on `at.x` instead of starting there.
+        centered: bool,
+        shadow: bool,
+    }
+    variant shape {
+        fill(fill-shape),
+        quad(quad-shape),
+        sprite(sprite-shape),
+        item(item-shape),
+        text(text-shape),
+    }
+    /// Replaces the mod's HUD shapes: up to 1024, drawn every frame in
+    /// order over the HUD (after the hotbar, under chat and screens), hidden
+    /// with the HUD (F1). An empty list removes them.
+    set-hud: func(shapes: list<shape>);
+    /// The screen's size in GUI pixels (width, height), as of this tick.
+    gui-size: func() -> tuple<f32, f32>;
+    /// Shakes the camera: a jolt of `strength` (0 to 1, 1 the hardest) that
+    /// fades out over `seconds` (at most 10). Jolts add up to 1. The view
+    /// turns, the player doesn't, and the player's Distortion Effects option
+    /// scales it (0 turns it off).
+    shake: func(strength: f32, seconds: f32);
+}
+
 /// What the game calls. Only the hooks `init` asks for are ever called.
 interface events {
     record registration {
@@ -203,6 +279,7 @@ world horizon-mod {
 world horizon-ui-mod {
     include horizon-mod;
     import ui;
+    import render;
     export ui-events;
 }
 
@@ -211,3 +288,8 @@ world ui-host {
     import ui;
     export ui-events;
 }
+
+/// The game's side of capability `render` (imports only).
+world render-host {
+    import render;
+}
diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index 6070f99bd..1880b9f3e 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -84,15 +84,19 @@ pub enum Capability {
     /// A screen the mod owns and a settings page in Options > Mods, drawn
     /// with the menus' own widgets (interface `ui`, calls `ui-events`).
     Ui,
+    /// Shapes on the HUD and the camera's shake, drawn by the game's own
+    /// renderer (interface `render`).
+    Render,
 }
 impl Capability {
-    pub const ALL: [Capability; 6] = [
+    pub const ALL: [Capability; 7] = [
         Capability::GameRead,
         Capability::Chat,
         Capability::Hud,
         Capability::Storage,
         Capability::Registries,
         Capability::Ui,
+        Capability::Render,
     ];
     /// The WIT interface it grants, in `horizon:mods`.
     pub fn interface(self) -> &'static str {
@@ -103,12 +107,13 @@ impl Capability {
             Capability::Storage => "storage",
             Capability::Registries => "registries",
             Capability::Ui => "ui",
+            Capability::Render => "render",
         }
     }
     /// May change in any release: a mod uses it only with
     /// `experimental = ["<name>"]` in its manifest.
     pub fn is_experimental(self) -> bool {
-        matches!(self, Capability::Ui)
+        matches!(self, Capability::Ui | Capability::Render)
     }
     /// What the player reads before turning the mod on: "May <this>".
     pub fn describe(self) -> &'static str {
@@ -119,6 +124,7 @@ impl Capability {
             Capability::Storage => "save its own settings to disk",
             Capability::Registries => "add blocks and items to your worlds",
             Capability::Ui => "show its own screens and a settings page",
+            Capability::Render => "draw on your screen and shake the camera",
         }
     }
     /// The capability a component import needs, `Ok(None)` for one every
@@ -150,6 +156,7 @@ impl fmt::Display for Capability {
             Capability::Storage => "storage",
             Capability::Registries => "registries",
             Capability::Ui => "ui",
+            Capability::Render => "render",
         };
         f.write_str(name)
     }
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 1b1795037..e19bfbe3f 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -40,6 +40,19 @@ pub use ui_bindings::horizon::mods::ui::{
     ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
 };
 use ui_bindings::{UiHost, horizon::mods::ui};
+/// Capability `render`'s imports (docs/mods.md): the game draws the shapes.
+mod render_bindings {
+    wasmtime::component::bindgen!({
+        path: "../horizon-mod-sdk/wit",
+        world: "render-host",
+    });
+}
+/// What capability `render` asks the game to draw (WIT `interface render`).
+pub use render_bindings::horizon::mods::render::{
+    FillShape, ItemShape, Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape,
+    TextShape,
+};
+use render_bindings::{RenderHost, horizon::mods::render};
 
 /// A mod's linear memory cap.
 const MEMORY: usize = 64 << 20;
@@ -70,6 +83,8 @@ const STORAGE_WRITE_BUDGET: u64 = 1 << 20;
 pub struct Snapshot {
     pub player: Option<Player>,
     pub clock: Option<Clock>,
+    /// The screen in GUI pixels (capability `render`'s `gui-size`).
+    pub gui_size: (f32, f32),
 }
 
 /// What mods asked the game to show since the last [`Mods::drain`].
@@ -86,6 +101,8 @@ pub enum Output {
     OpenScreen { owner: usize },
     /// `ui.close-screen`: the mod closed its own screen (no `closed` back).
     CloseScreen { owner: usize },
+    /// `render.shake`: strength 0 to 1, fading out over `seconds` (≤ 10).
+    Shake { strength: f32, seconds: f32 },
 }
 
 /// A mod's text panel, drawn every frame until it changes.
@@ -153,6 +170,8 @@ struct State {
     out: Vec<Output>,
     panel: Option<Panel>,
     ui: UiState,
+    /// Capability `render`'s HUD shapes, drawn until replaced.
+    shapes: Vec<Shape>,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
     /// Bytes `storage::set` may still write before this hook call ends
@@ -231,6 +250,8 @@ impl Mods {
                 .map_err(|e| e.to_string())?;
             UiHost::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
                 .map_err(|e| e.to_string())?;
+            RenderHost::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
+                .map_err(|e| e.to_string())?;
             self.engine = Some((engine, linker));
         }
         Ok(self.engine.as_ref().expect("made above"))
@@ -290,6 +311,7 @@ impl Mods {
             out: Vec::new(),
             panel: None,
             ui: UiState::default(),
+            shapes: Vec::new(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
             limits: StoreLimitsBuilder::new()
@@ -481,6 +503,14 @@ impl Mods {
             .iter()
             .filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
     }
+    /// The running mods' HUD shapes (capability `render`), each mod's in
+    /// its own order, mods in load order.
+    pub fn hud_shapes(&self) -> impl Iterator<Item = &Shape> {
+        self.entries
+            .iter()
+            .filter_map(|e| e.run.as_ref())
+            .flat_map(|r| &r.store.data().shapes)
+    }
     /// The screen mod `i` last pushed with `ui.open-screen`, while it is up.
     pub fn screen(&self, i: usize) -> Option<&UiScreen> {
         self.entries
@@ -668,6 +698,57 @@ impl chat::Host for State {
         }
     }
 }
+/// HUD shapes one mod may keep (capability `render`).
+const SHAPES: usize = 1024;
+/// The longest jolt `render.shake` makes, in seconds.
+const SHAKE_SECONDS: f32 = 10.0;
+
+impl render::Host for State {
+    fn set_hud(&mut self, shapes: Vec<Shape>) {
+        self.shapes = shapes
+            .into_iter()
+            .take(SHAPES)
+            .map(|shape| match shape {
+                Shape::Sprite(mut s) => {
+                    s.sprite = clip(s.sprite);
+                    Shape::Sprite(s)
+                }
+                Shape::Item(mut i) => {
+                    i.item = clip(i.item);
+                    i.scale = if i.scale.is_finite() {
+                        i.scale.clamp(0.0, 16.0)
+                    } else {
+                        1.0
+                    };
+                    Shape::Item(i)
+                }
+                Shape::Text(mut t) => {
+                    t.text = clip(t.text);
+                    t.color &= 0xFF_FFFF;
+                    Shape::Text(t)
+                }
+                other => other,
+            })
+            .collect();
+    }
+    fn gui_size(&mut self) -> (f32, f32) {
+        self.snapshot.gui_size
+    }
+    fn shake(&mut self, strength: f32, seconds: f32) {
+        let ok = |v: f32, max: f32| {
+            if v.is_finite() {
+                v.clamp(0.0, max)
+            } else {
+                0.0
+            }
+        };
+        let (strength, seconds) = (ok(strength, 1.0), ok(seconds, SHAKE_SECONDS));
+        if strength > 0.0 && seconds > 0.0 {
+            self.out.push(Output::Shake { strength, seconds });
+        }
+    }
+}
+
 impl hud::Host for State {
     fn set_panel(&mut self, corner: Corner, lines: Vec<Line>) {
         let lines = lines
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index 77f0975f3..dac333fe6 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -1,7 +1,7 @@
 //! Loads real mods built with the SDK: the coords-hud example and a guest
 //! that misbehaves on command. Needs `rustup target add wasm32-unknown-unknown`.
 use horizon_mods::{
-    Clock, Corner, Mods, Output, Package, Player, Snapshot, Status, manifest::componentize,
+    Clock, Corner, Mods, Output, Package, Player, Shape, Snapshot, Status, manifest::componentize,
 };
 use std::{
     path::{Path, PathBuf},
@@ -22,8 +22,8 @@ id = "test_ui_guest"
 name = "Test UI Guest"
 version = "0.1.0"
 api = "0.1"
-capabilities = ["chat", "ui"]
-experimental = ["ui"]
+capabilities = ["chat", "ui", "render"]
+experimental = ["ui", "render"]
 "#;
 
 /// Builds both mods once and writes their `.hmod` files; returns the folder.
@@ -89,6 +89,7 @@ fn player() -> Snapshot {
             game_time: 100,
             day_time: 24000 + 6000,
         }),
+        gui_size: (427.0, 240.0),
     }
 }
 
@@ -416,6 +417,37 @@ fn ui_screens_settings_and_events() {
     assert!(mods.screen(0).is_none());
 }
 
+#[test]
+fn render_shapes_and_shakes() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    mods.set_snapshot(Snapshot {
+        gui_size: (427.0, 240.0),
+        ..Snapshot::default()
+    });
+    assert_eq!(mods.hud_shapes().count(), 0);
+    assert!(mods.command("render_hud"));
+    let shapes: Vec<_> = mods.hud_shapes().cloned().collect();
+    assert_eq!(shapes.len(), 5);
+    // The guest read `gui-size`; text is clipped to 256 characters.
+    let Shape::Text(t) = &shapes[4] else {
+        panic!("{:?}", shapes[4])
+    };
+    assert!(t.text.starts_with("gui 427x240 "), "{}", t.text);
+    assert_eq!(t.text.chars().count(), 256);
+    assert!(mods.command("render_clear"));
+    assert_eq!(mods.hud_shapes().count(), 0);
+    // One jolt, clamped; zero and NaN shake nothing.
+    mods.drain();
+    assert!(mods.command("render_shake"));
+    assert_eq!(
+        mods.drain(),
+        [Output::Shake {
+            strength: 1.0,
+            seconds: 10.0
+        }]
+    );
+}
+
 #[test]
 fn content_only_mods_load_without_an_engine() {
     let manifest = r#"
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index 1af3985a1..146ab6f40 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -1,11 +1,61 @@
 //! A mod for the runtime's `ui` tests: `/ui_screen` opens a screen with one
 //! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes
 //! the screen; the `ui-events` calls answer in chat so the host sees them.
+//! `/render_hud`, `/render_clear` and `/render_shake` test `render`.
 use horizon_mod_sdk::{
     Mod, Registration, chat,
+    render::{self, FillShape, ItemShape, Point, QuadShape, Rect, Shape, SpriteShape, TextShape},
     ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
 };
 
+/// One of each shape, the text too long by 44 characters.
+fn shapes() -> Vec<Shape> {
+    let (w, h) = render::gui_size();
+    let p = |x, y| Point { x, y };
+    vec![
+        Shape::Fill(FillShape {
+            rect: Rect {
+                x: 4.0,
+                y: 4.0,
+                w: 60.0,
+                h: 20.0,
+            },
+            color: 0x80FF0000,
+        }),
+        Shape::Quad(QuadShape {
+            corners: (
+                p(w / 2.0, 10.0),
+                p(w / 2.0 + 20.0, 30.0),
+                p(w / 2.0, 50.0),
+                p(w / 2.0 - 20.0, 30.0),
+            ),
+            color: 0xC000FF00,
+        }),
+        Shape::Sprite(SpriteShape {
+            sprite: "hud/heart/full".into(),
+            rect: Rect {
+                x: 70.0,
+                y: 4.0,
+                w: 18.0,
+                h: 18.0,
+            },
+            color: 0xFFFFFFFF,
+        }),
+        Shape::Item(ItemShape {
+            item: "minecraft:diamond".into(),
+            at: p(92.0, 4.0),
+            scale: 2.0,
+        }),
+        Shape::Text(TextShape {
+            text: format!("gui {w}x{h} {}", "x".repeat(300)),
+            at: p(w / 2.0, h / 2.0 - 30.0),
+            color: 0xFFFF55,
+            centered: true,
+            shadow: true,
+        }),
+    ]
+}
+
 struct Guest;
 
 fn widgets() -> Vec<Widget> {
@@ -30,9 +80,16 @@ fn widgets() -> Vec<Widget> {
 
 impl Mod for Guest {
     fn init() -> Result<(Self, Registration), String> {
-        let hooks = ["ui_screen", "ui_settings", "ui_close"]
-            .into_iter()
-            .fold(Registration::new(), Registration::command);
+        let hooks = [
+            "ui_screen",
+            "ui_settings",
+            "ui_close",
+            "render_hud",
+            "render_clear",
+            "render_shake",
+        ]
+        .into_iter()
+        .fold(Registration::new(), Registration::command);
         Ok((Guest, hooks))
     }
     fn command(&mut self, name: &str, _args: &str) -> Result<Option<String>, String> {
@@ -43,6 +100,14 @@ impl Mod for Guest {
             }),
             "ui_settings" => ui::set_settings(&widgets()),
             "ui_close" => ui::close_screen(),
+            "render_hud" => render::set_hud(&shapes()),
+            "render_clear" => render::set_hud(&[]),
+            // Clamped to (1, 10); the two after it shake nothing.
+            "render_shake" => {
+                render::shake(2.0, 99.0);
+                render::shake(0.0, 1.0);
+                render::shake(f32::NAN, 1.0);
+            }
             _ => {}
         }
         Ok(None)
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index 0812cde54..ef889d599 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -13,6 +13,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `storage` | [`storage`](#storage) | save its own settings to disk |
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
 | `ui` | [`ui`](#ui) | show its own screens and a settings page |
+| `render` | [`render`](#render) | draw on your screen and shake the camera |
 
 ## World `horizon-mod`
 
@@ -23,7 +24,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 
 A mod with widgets (capability `ui`): the SDK builds every mod against this world. Mods built for `horizon-mod` alone (no `ui-events` export) still load and simply hear nothing of their widgets.
 
-- Imports (what the game offers): `ui`, `log`, `game`, `chat`, `hud`, `storage`
+- Imports (what the game offers): `ui`, `render`, `log`, `game`, `chat`, `hud`, `storage`
 - Exports (what the mod provides): `ui-events`, `events`
 
 ## World `ui-host`
@@ -33,6 +34,13 @@ The game's side of `horizon-ui-mod` beyond `horizon-mod`.
 - Imports (what the game offers): `ui`
 - Exports (what the mod provides): `ui-events`
 
+## World `render-host`
+
+The game's side of capability `render` (imports only).
+
+- Imports (what the game offers): `render`
+- Exports (what the mod provides): 
+
 ## `log`
 
 Access: always granted.
@@ -205,6 +213,90 @@ What the game calls on a mod that shows widgets (capability `ui`): what the play
 | `closed` | `func()` | The player left the mod's screen (Esc or Done); not for a screen the mod closed itself or one that went away with the mod. |
 | `settings-opened` | `func()` | The player opened the mod's settings page in Options > Mods: call `ui::set-settings` now to fill it with fresh widgets. |
 
+## `render`
+
+Access: capability `render`.
+
+Capability `render` (experimental: the manifest needs `experimental = ["render"]`): shapes the game draws for the mod with its own renderer, kept until the mod replaces them (no call per frame). A mod never supplies shader code.
+
+### record `rect`
+
+A rectangle in GUI pixels: the top left corner and the size.
+
+| Field | Type | |
+| --- | --- | --- |
+| `x` | `f32` |  |
+| `y` | `f32` |  |
+| `w` | `f32` |  |
+| `h` | `f32` |  |
+
+### record `point`
+
+A point in GUI pixels from the screen's top left.
+
+| Field | Type | |
+| --- | --- | --- |
+| `x` | `f32` |  |
+| `y` | `f32` |  |
+
+### record `fill-shape`
+
+| Field | Type | |
+| --- | --- | --- |
+| `rect` | `rect` |  |
+| `color` | `u32` | 0xAARRGGBB. |
+
+### record `quad-shape`
+
+Any four-cornered shape (a wheel's segment, an arrow): the corners in order round it.
+
+| Field | Type | |
+| --- | --- | --- |
+| `corners` | `tuple<point, point, point, point>` |  |
+| `color` | `u32` | 0xAARRGGBB. |
+
+### record `sprite-shape`
+
+| Field | Type | |
+| --- | --- | --- |
+| `sprite` | `string` | One of the game's GUI sprites, as `gui/sprites/` names them (`hud/heart/full`, `widget/button`), the resource packs' versions included. An unknown one draws nothing. |
+| `rect` | `rect` |  |
+| `color` | `u32` | A tint, 0xAARRGGBB: 0xFFFFFFFF draws it as it is. |
+
+### record `item-shape`
+
+| Field | Type | |
+| --- | --- | --- |
+| `item` | `string` | `minecraft:diamond`, `<mod>:<path>`; an unknown one draws nothing. |
+| `at` | `point` | The icon's top left. |
+| `scale` | `f32` | 1.0 is the hotbar's 16 × 16. |
+
+### record `text-shape`
+
+| Field | Type | |
+| --- | --- | --- |
+| `text` | `string` | Up to 256 characters, one line. |
+| `at` | `point` |  |
+| `color` | `u32` | 0xRRGGBB, as `hud`'s lines. |
+| `centered` | `bool` | Centred on `at.x` instead of starting there. |
+| `shadow` | `bool` |  |
+
+### variant `shape`
+
+| Case | Payload | |
+| --- | --- | --- |
+| `fill` | `fill-shape` |  |
+| `quad` | `quad-shape` |  |
+| `sprite` | `sprite-shape` |  |
+| `item` | `item-shape` |  |
+| `text` | `text-shape` |  |
+
+| Function | Signature | What it does |
+| --- | --- | --- |
+| `set-hud` | `func(shapes: list<shape>)` | Replaces the mod's HUD shapes: up to 1024, drawn every frame in order over the HUD (after the hotbar, under chat and screens), hidden with the HUD (F1). An empty list removes them. |
+| `gui-size` | `func() -> tuple<f32, f32>` | The screen's size in GUI pixels (width, height), as of this tick. |
+| `shake` | `func(strength: f32, seconds: f32)` | Shakes the camera: a jolt of `strength` (0 to 1, 1 the hardest) that fades out over `seconds` (at most 10). Jolts add up to 1. The view turns, the player doesn't, and the player's Distortion Effects option scales it (0 turns it off). |
+
 ## `events`
 
 Access: exported by the mod: the game calls it.
diff --git a/docs/api/mods.md b/docs/api/mods.md
index bec03e84e..cda484c31 100644
--- a/docs/api/mods.md
+++ b/docs/api/mods.md
@@ -95,5 +95,7 @@ What real mods need next, in the order modpacks and servers need it:
 
 ## Changelog
 
+- Experimental `render` (`experimental = ["render"]`): HUD shapes (fill, quad, sprite, item, text), `gui-size`, camera
+  `shake`, drawn by the game's own renderer.
 - API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation.
 - API 0.1.0: `log`, `game`, `chat`, `hud`, `storage`; `init`, `tick`, `frame`, `command`, `chat`.
diff --git a/docs/api/stability.md b/docs/api/stability.md
index ffa9d9b11..76c3c4e51 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -88,6 +88,7 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
 | --- | --- | --- |
 | Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
 | Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` |
+| Mod API: `render` (HUD shapes, camera shake; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` |
 | Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
 | Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first |
 | Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
diff --git a/docs/mods.md b/docs/mods.md
index 9b3b8aa94..672d6c7fd 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -87,6 +87,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
+| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects. The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
 
 | Hook (export) | When |
 |---|---|
@@ -114,7 +115,7 @@ loading. Ordered by what the first native ports need:
 | `inventory-read` | the player's inventory, held item, open container | AppleSkin, recipe viewers |
 | `recipes` | the recipe registry and lookups | JEI/EMI-style viewers |
 | `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics |
-| `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints |
+| `render` (world) | world-space lines, boxes and billboards, beside the HUD shapes `render` has | Litematica-style placement, waypoints |
 | `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) |
 | `server` | world events (block break/place, entity spawn/death, player join), game rules, server commands | runs where the world is simulated |
 | `net` | a mod's own client↔server channel (custom payloads) | only between the two halves of the same mod |
@@ -288,7 +289,7 @@ experimental = []            # experimental capabilities it uses, e.g. ["ui"]
 ```
 
 Unknown keys are refused, so a typo is an error, not a silently ignored
-permission. An experimental capability (today `ui`) may change in any release
+permission. An experimental capability (today `ui` and `render`) may change in any release
 ([stability](api/stability.md)): a mod uses it only by naming it in
 `experimental` as well, so nobody depends on it by accident.
 

From 09ff66bfeee243b10396a77381095eaa31670327 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:39:44 +0000
Subject: [PATCH 188/270] Fix stale server digging after instant survival
 breaks

Clear completed guest digging so replanted flowers and crops are not broken again after attack is released. Add a LAN replanting regression for both single-player paths.

Co-Authored-By: Codex (gpt-6.1-sol) <noreply@openai.com>
---
 crates/horizon-client/src/game/lan_actions.rs | 11 ++-
 tools/lan_e2e.py                              | 68 +++++++++++++++++++
 2 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 02434d793..ab7803ddd 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -1810,14 +1810,13 @@ impl Game<'_> {
                         g.use_delay -= 1;
                     }
                 });
-                // ServerPlayerGameMode.handleBlockBreakAction: a creative
-                // player's START breaks the block once (destroyAndAck) and
-                // leaves nothing being destroyed; its client sends no STOP.
-                // Kept, the dig broke whatever was put there next, every
-                // destroy delay, for as long as the player broke nothing else.
+                // ServerPlayerGameMode.handleBlockBreakAction: creative and
+                // instant survival STARTs finish without a STOP from the client.
+                // tick_mining clears mining on completion; forget the START too,
+                // so a flower or crop planted here later is not broken again.
                 if digging.is_some()
-                    && host.hub.guests[gi].creative()
                     && let Some(play) = host.play.get_mut(&conn)
+                    && (host.hub.guests[gi].creative() || play.mining.is_none())
                 {
                     play.digging = None;
                 }
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index f79e07033..f0333c87b 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -250,6 +250,8 @@ address. The script then checks, from both sides, what a guest's game used to ge
 - falling:   an item and a falling block the host summons high up fall smoothly on the guest, a
              little further every tick between the server's updates (every 20 ticks), as their own
              client tick moves them (they used to hang, then jump down once a second, #1568).
+- replant:   flowers and crops replanted after a short harvest click stay planted for both players;
+             the server forgets the completed instant break (#1880).
 
 Each check is reported on its own (a failing one doesn't stop the others) and the screenshots of
 both sides go to --out (host-*.png, guest-*.png).
@@ -6348,5 +6350,71 @@ CHECKS += ['sprint-fov']
 CHECK_FNS['sprint-fov'] = check_sprint_fov
 
 
+def check_replant(host, guest, out):
+    """Instant breaks leave no server dig that can destroy a replacement (#1880).
+
+    ServerPlayerGameMode.handleBlockBreakAction's insta-mine branch finishes on
+    START; MultiPlayerGameMode sends no STOP or ABORT when attack is released.
+    Exercise actual flower placement and seed planting after a short click.
+    """
+    spots = apart(host, guest)
+    seen = {}
+    host('command', command='gamerule random_tick_speed 0')
+    try:
+        for label, player in (('host', host), ('guest', guest)):
+            x, y, z = spots[label]
+            cell = (x, y, z + 2)
+
+            def observe(block):
+                # The integrated host is itself a client: wait for both views.
+                for _ in range(40):
+                    blocks = [g.raw('block', *cell).get('block') for g in (host, guest)]
+                    if blocks == [f'minecraft:{block}'] * 2:
+                        return blocks
+                    host.wait(2)
+                raise AssertionError(f'{label} expected {block} on both clients: {blocks}')
+
+            for mode, block, item, soil in (
+                ('survival', 'dandelion', 'dandelion', 'dirt'),
+                ('survival', 'wheat', 'wheat_seeds', 'farmland[moisture=7]'),
+                ('survival', 'carrots', 'carrot', 'farmland[moisture=7]'),
+                ('creative', 'dandelion', 'dandelion', 'dirt'),
+            ):
+                player('command', command=f'gamemode {mode}')
+                player('command', command='clear @s')
+                player('command', command=f'item replace entity @s weapon.mainhand with minecraft:{item} 8')
+                player('command', command=f'setblock {x} {y - 1} {z + 2} minecraft:{soil}')
+                player('command', command=f'setblock {x} {y} {z + 2} minecraft:{block}')
+                player.wait(5)
+                observe(block)
+                # Flowers' narrow outlines have a position-dependent offset.
+                for dx in (0.0, -0.2, 0.2):
+                    player.raw('look-at', x + 0.5 + dx, y + (0.3 if block == 'dandelion' else 0.1), z + 2.5)
+                    target = player('looking_at').get('block') or {}
+                    if target.get('pos') == list(cell):
+                        break
+                assert target.get('pos') == list(cell), f'{label} does not aim at {block}: {target}'
+                player.raw('mouse', 'left', 'click')
+                player.wait(5)
+                observe('air')
+                # Keep aiming at the supporting soil and use the held flower/seeds.
+                player.raw('mouse', 'right', 'click')
+                player.wait(3)
+                observe(block)
+                player.wait(20)  # past the stale dig's five-tick destroy delay
+                key = f'{label} {mode} {block}'
+                seen[key] = [g.raw('block', *cell).get('block') for g in (host, guest)]
+                player.shot(out, f'replant-{mode}-{block}')
+                assert seen[key] == [f'minecraft:{block}'] * 2, f'{key}: {seen}'
+                player('command', command=f'setblock {x} {y} {z + 2} minecraft:air')
+    finally:
+        host('command', command='gamerule random_tick_speed 3')
+    return seen
+
+
+CHECKS += ['replant']
+CHECK_FNS['replant'] = check_replant
+
+
 if __name__ == '__main__':
     main()

From b3807d6e505de48df82e5861de400e559cbd2988 Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:45:10 +0500
Subject: [PATCH 189/270] Chat: the Chat option hides what it says it hides

The Chat Settings option was saved and shown but never applied: Hidden and
Commands Only still sent and displayed ordinary chat, and Hidden still
displayed the server's messages.

Minecraft.computeChatAbilities turns the option into ChatRestriction's
permissions, and they are now honoured where vanilla honours them:
ChatScreen refuses to submit input they take (hasAllowedInput) and says why
in a red usage line, ClientPacketListener.sendChat/sendCommand stop it before
the packet, ChatListener drops the player, server and client sources the
option hides, and ClientInformation carries the visibility to a server (at
login, and again when it changes, as Options.broadcastOptions does).

Fixes #1376

Co-Authored-By: [CC] <deepseek-v4.1-flash> <noreply@deepseek.com>
---
 .../examples/probe/chat_screen_fixture.rs     |   3 +-
 crates/horizon-client/src/chat.rs             | 105 +++++++++++++++++-
 crates/horizon-client/src/chat_tests.rs       |  95 +++++++++++++++-
 crates/horizon-client/src/game/chat.rs        |  22 +++-
 crates/horizon-client/src/game/remote.rs      |  63 ++++++++---
 5 files changed, 260 insertions(+), 28 deletions(-)

diff --git a/crates/horizon-client/examples/probe/chat_screen_fixture.rs b/crates/horizon-client/examples/probe/chat_screen_fixture.rs
index 229d8d861..db334797d 100644
--- a/crates/horizon-client/examples/probe/chat_screen_fixture.rs
+++ b/crates/horizon-client/examples/probe/chat_screen_fixture.rs
@@ -7,7 +7,7 @@
 //! usage: chat_screen_fixture RESOURCES REGISTRIES CASES OUTPUT
 use crate::pack_screen_fixture;
 use horizon_client::{
-    chat::{ChatAction, ChatScreen, Commands},
+    chat::{ChatAbilities, ChatAction, ChatScreen, ChatVisibility, Commands},
     command::vanilla,
     hud::HudAtlas,
     lang,
@@ -53,6 +53,7 @@ pub fn main() -> horizon_client::Result<()> {
             history.len(),
             w,
             h,
+            ChatAbilities::new(ChatVisibility::Full),
         );
         screen.auto_suggestions = case["autoSuggest"] == true;
         let mut closed = false;
diff --git a/crates/horizon-client/src/chat.rs b/crates/horizon-client/src/chat.rs
index 273b87153..e14178c8d 100644
--- a/crates/horizon-client/src/chat.rs
+++ b/crates/horizon-client/src/chat.rs
@@ -19,6 +19,78 @@ mod tests;
 /// GuiMessageTag.systemSinglePlayer's indicator colour.
 pub const SYSTEM_INDICATOR: u32 = 0xD0D0D0;
 
+/// `ChatVisiblity`: the Chat option's three values.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ChatVisibility {
+    Full,
+    System,
+    Hidden,
+}
+impl ChatVisibility {
+    /// Options.chatVisibility's saved value (0 full, 1 system, 2 hidden).
+    pub fn from_option(value: u8) -> Self {
+        match value {
+            0 => Self::Full,
+            1 => Self::System,
+            _ => Self::Hidden,
+        }
+    }
+}
+
+/// `ChatAbilities`: what the Chat option allows, as `Minecraft.computeChatAbilities`
+/// derives it from the visibility alone (`ChatRestriction`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ChatAbilities {
+    pub send_messages: bool,
+    pub send_commands: bool,
+    pub receive_player_messages: bool,
+    pub receive_system_messages: bool,
+}
+impl ChatAbilities {
+    /// `ChatRestriction.CHAT_AND_COMMANDS_DISABLED_BY_OPTIONS` (Hidden) takes
+    /// chat, commands, player messages and system messages;
+    /// `CHAT_DISABLED_BY_OPTIONS` (System) takes the chat and player messages.
+    pub fn new(visibility: ChatVisibility) -> Self {
+        match visibility {
+            ChatVisibility::Full => Self {
+                send_messages: true,
+                send_commands: true,
+                receive_player_messages: true,
+                receive_system_messages: true,
+            },
+            ChatVisibility::System => Self {
+                send_messages: false,
+                send_commands: true,
+                receive_player_messages: false,
+                receive_system_messages: true,
+            },
+            ChatVisibility::Hidden => Self {
+                send_messages: false,
+                send_commands: false,
+                receive_player_messages: false,
+                receive_system_messages: false,
+            },
+        }
+    }
+    /// Whether the chat screen may send `input` (`hasAllowedInput`).
+    pub fn allows(&self, input: &str) -> bool {
+        if input.starts_with('/') {
+            self.send_commands
+        } else {
+            self.send_messages
+        }
+    }
+}
+
+/// Where a chat line came from (`GuiMessageSource`): the visibility filters
+/// player messages and the server's, while the client's own always show.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ChatSource {
+    Player,
+    Server,
+    Client,
+}
+
 /// The chat options (doubles, as vanilla keeps them).
 #[derive(Clone, Copy, Debug)]
 pub struct ChatOptions {
@@ -437,6 +509,8 @@ pub struct ChatScreen {
     allow_suggestions: bool,
     keep_suggestions: bool,
     pub auto_suggestions: bool,
+    /// `CommandSuggestions.setRestrictions`: what the Chat option allows.
+    pub abilities: ChatAbilities,
 }
 /// Local completions waiting for the server's reply to request `id`.
 struct Awaiting {
@@ -482,6 +556,7 @@ impl ChatScreen {
         history_len: usize,
         width: i32,
         height: i32,
+        abilities: ChatAbilities,
     ) -> Self {
         let mut input = TextField::new(4, height - 12, width - 4, 12);
         input.max_length = 256;
@@ -505,6 +580,7 @@ impl ChatScreen {
             allow_suggestions: false,
             keep_suggestions: false,
             auto_suggestions: true,
+            abilities,
         };
         s.update_command_info(m, c);
         s
@@ -522,7 +598,8 @@ impl ChatScreen {
         if (width, height) != (self.width, self.height) {
             let value = self.input.value.clone();
             let auto = self.auto_suggestions;
-            *self = Self::new(m, c, &value, self.history_pos, width, height);
+            let abilities = self.abilities;
+            *self = Self::new(m, c, &value, self.history_pos, width, height, abilities);
             self.auto_suggestions = auto;
         }
     }
@@ -604,6 +681,14 @@ impl ChatScreen {
             self.pending = Some((range.0, list));
             self.usage_width = 0;
             self.usage_position = 0;
+            // CommandSuggestions.updateCommandInfo: the Chat option may take
+            // the messages.
+            if !self.abilities.send_messages {
+                let line =
+                    Text::translate("chat_screen.messages_not_allowed", &[]).with_color(text::RED);
+                self.usage_width = m.width(&line);
+                self.usage.push(line);
+            }
         } else {
             self.awaiting = None;
             self.pending = None;
@@ -708,6 +793,15 @@ impl ChatScreen {
             }
             self.usage.extend(entries);
         }
+        // CommandSuggestions.updateUsageInfo: the Chat option may take the
+        // commands, under the usage. (Vanilla also counts a command with a
+        // message argument, `/say hi`, as a message; Horizon's parse keeps no
+        // argument kinds, so only a bare message does.)
+        if !self.abilities.send_commands {
+            self.usage.push(
+                Text::translate("chat_screen.commands_not_allowed", &[]).with_color(text::RED),
+            );
+        }
         self.usage_width = self.usage.iter().map(|u| m.width(u)).max().unwrap_or(0);
         self.usage_position = if self.usage.is_empty() {
             0
@@ -842,7 +936,14 @@ impl ChatScreen {
         }
         match key {
             K::Escape => return ChatAction::Close,
-            K::Enter | K::NumpadEnter => return ChatAction::Submit(self.normalized()),
+            K::Enter | K::NumpadEnter => {
+                // ChatScreen.keyPressed: without `hasAllowedInput` the input
+                // stays, unsent, and the screen stays open.
+                if !self.abilities.allows(&self.input.value) {
+                    return ChatAction::None;
+                }
+                return ChatAction::Submit(self.normalized());
+            }
             K::ArrowUp => self.move_in_history(m, c, history, -1),
             K::ArrowDown => self.move_in_history(m, c, history, 1),
             _ => {
diff --git a/crates/horizon-client/src/chat_tests.rs b/crates/horizon-client/src/chat_tests.rs
index d0ce3f458..cd5860bfb 100644
--- a/crates/horizon-client/src/chat_tests.rs
+++ b/crates/horizon-client/src/chat_tests.rs
@@ -2,6 +2,11 @@ use super::*;
 use crate::{font::Font, hud::Rect};
 use std::{collections::HashMap, path::Path};
 
+/// The Chat option's default: no restriction.
+fn full() -> ChatAbilities {
+    ChatAbilities::new(ChatVisibility::Full)
+}
+
 fn font() -> Font {
     // The missing-glyph metrics let these tests run without game assets.
     Font::load(
@@ -139,7 +144,7 @@ fn locate_coordinates_fill_chat_with_teleport_without_submitting() {
         assert_eq!(link.component()["click_event"]["command"], expected);
         let mut chat = Chat::default();
         add(&mut chat, &font, Text::literal("Found at ").append(link));
-        let mut screen = ChatScreen::new(&m, &commands, "draft", 0, 640, 360);
+        let mut screen = ChatScreen::new(&m, &commands, "draft", 0, 640, 360, full());
         let x = 4.0 + f64::from(font.width("Found at "));
         assert!(!screen.click(&m, &commands, x, 315.0));
         let Some(ClickEvent::SuggestCommand(command)) = chat.click_at(&font, 360, x, 315.0) else {
@@ -176,7 +181,15 @@ fn history_arrows_recall_messages_and_restore_the_draft() {
         registries: &registries,
     };
     let history = vec!["first message".to_owned(), "latest message".to_owned()];
-    let mut screen = ChatScreen::new(&m, &commands, "unfinished draft", history.len(), 640, 360);
+    let mut screen = ChatScreen::new(
+        &m,
+        &commands,
+        "unfinished draft",
+        history.len(),
+        640,
+        360,
+        full(),
+    );
     for (key, expected) in [
         (ArrowUp, "latest message"),
         (ArrowUp, "first message"),
@@ -213,7 +226,7 @@ fn mod_commands_are_coloured_and_complete_like_vanilla_ones() {
             dispatcher,
             registries: &registries,
         };
-        let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360);
+        let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360, full());
         screen.type_text(&m, &c, line);
         screen
     };
@@ -259,7 +272,7 @@ fn ask_server_nodes_wait_for_the_servers_completions() {
     let tab = |screen: &mut ChatScreen| {
         screen.key(&m, &c, &[], winit::keyboard::KeyCode::Tab, false, false);
     };
-    let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360);
+    let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360, full());
     screen.type_text(&m, &c, "/bossbar get pt");
     let (request, sent) = screen.take_request().expect("the server is asked");
     assert_eq!(sent, "/bossbar get pt");
@@ -281,7 +294,7 @@ fn ask_server_nodes_wait_for_the_servers_completions() {
         dispatcher: local,
         registries: &registries,
     };
-    let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360);
+    let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360, full());
     screen.type_text(&m, &c, "/bossbar get pt");
     assert_eq!(screen.take_request(), None);
 }
@@ -327,3 +340,75 @@ fn a_server_component_keeps_its_click_and_hover_events() {
     let past = 4.0 + f64::from(font.width("CLICK")) + 20.0;
     assert!(chat.hover_at(&font, 360, past, 315.0).is_none());
 }
+
+/// `ChatVisiblity`: Commands Only keeps the chat out, Hidden takes the
+/// commands too (`ChatAbilities`), and Enter sends nothing the option hides.
+#[test]
+fn the_chat_option_decides_what_may_be_sent() {
+    let font = font();
+    let m = Measure(&font);
+    let registries = Registries::default();
+    let c = Commands {
+        dispatcher: crate::command::vanilla::game_dispatcher(),
+        registries: &registries,
+    };
+    let enter = |screen: &mut ChatScreen| {
+        screen.key(&m, &c, &[], winit::keyboard::KeyCode::Enter, false, false)
+    };
+    for (visibility, chat, command) in [
+        (ChatVisibility::Full, true, true),
+        (ChatVisibility::System, false, true),
+        (ChatVisibility::Hidden, false, false),
+    ] {
+        let abilities = ChatAbilities::new(visibility);
+        assert_eq!(abilities.allows("hi"), chat, "{visibility:?}");
+        assert_eq!(abilities.allows("/time set day"), command, "{visibility:?}");
+        for (line, allowed) in [("hi", chat), ("/time set day", command)] {
+            let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360, abilities);
+            screen.type_text(&m, &c, line);
+            match enter(&mut screen) {
+                ChatAction::Submit(sent) => {
+                    assert!(allowed, "{visibility:?} sent {sent}");
+                    assert_eq!(sent, line);
+                }
+                ChatAction::None => assert!(!allowed, "{visibility:?} kept {line}"),
+                ChatAction::Close => panic!("Enter does not close the chat"),
+            }
+        }
+    }
+}
+
+/// The restriction the option sets is a usage line: red, under the input, for
+/// a command the Chat option takes and for a message it takes.
+#[test]
+fn restricted_input_says_why_it_will_not_send() {
+    let font = font();
+    let m = Measure(&font);
+    let registries = Registries::default();
+    let c = Commands {
+        dispatcher: crate::command::vanilla::game_dispatcher(),
+        registries: &registries,
+    };
+    let usage = |visibility, line: &str| {
+        let mut screen = ChatScreen::new(&m, &c, "", 0, 640, 360, ChatAbilities::new(visibility));
+        screen.type_text(&m, &c, line);
+        screen.usage.iter().map(|t| t.plain()).collect::<Vec<_>>()
+    };
+    assert_eq!(usage(ChatVisibility::Full, "hi"), Vec::<String>::new());
+    // The font has no language files here, so the line is its key.
+    assert_eq!(
+        usage(ChatVisibility::System, "hi"),
+        ["chat_screen.messages_not_allowed"]
+    );
+    // A command the option allows says nothing about the restriction.
+    assert!(
+        !usage(ChatVisibility::System, "/time set day")
+            .iter()
+            .any(|line| line == "chat_screen.commands_not_allowed")
+    );
+    assert!(
+        usage(ChatVisibility::Hidden, "/time set day")
+            .iter()
+            .any(|line| line == "chat_screen.commands_not_allowed")
+    );
+}
diff --git a/crates/horizon-client/src/game/chat.rs b/crates/horizon-client/src/game/chat.rs
index 23a0f0965..fafe88f26 100644
--- a/crates/horizon-client/src/game/chat.rs
+++ b/crates/horizon-client/src/game/chat.rs
@@ -2,7 +2,10 @@
 //! (game rules, the world clock, difficulty), bound to the game.
 use super::{Game, Screen};
 use horizon_client::{
-    chat::{Chat, ChatAction, ChatScreen, Commands, SYSTEM_INDICATOR},
+    chat::{
+        Chat, ChatAbilities, ChatAction, ChatScreen, ChatSource, ChatVisibility, Commands,
+        SYSTEM_INDICATOR,
+    },
     command::Registries,
     gamerules::GameRules,
     hud::HudBatch,
@@ -425,6 +428,7 @@ impl Game<'_> {
             self.ui.chat.recent.len(),
             b.width as i32,
             b.height as i32,
+            self.chat_abilities(),
         );
         screen.auto_suggestions = self.settings.auto_suggestions;
         self.ui.chat_screen = Some(screen);
@@ -443,6 +447,10 @@ impl Game<'_> {
             self.capture(true);
         }
     }
+    /// `Minecraft.computeChatAbilities` from the Chat option.
+    pub(super) fn chat_abilities(&self) -> ChatAbilities {
+        ChatAbilities::new(ChatVisibility::from_option(self.settings.chat_visibility))
+    }
     /// A chat message from the game (ChatComponent.addServerSystemMessage).
     pub(super) fn system_message(&mut self, text: Text) {
         if let Some(capture) = self.chat_capture.as_mut() {
@@ -452,7 +460,12 @@ impl Game<'_> {
         // Connected to a server (single player's own included), the chat on
         // screen is the connection's: the game's own messages join it.
         if self.remote.is_some() {
-            self.chat_line(text);
+            self.chat_line(text, ChatSource::Server);
+            return;
+        }
+        // ChatListener.handleSystemMessage: the Chat option's Hidden level
+        // takes the server's messages too.
+        if !self.chat_abilities().receive_system_messages {
             return;
         }
         let focused = self.screen == Screen::Chat;
@@ -570,7 +583,12 @@ impl Game<'_> {
         }
     }
     /// ChatScreen.handleChatInput: history, then a command or a chat line.
+    /// The Chat option's restrictions stop the message here too, so a
+    /// control-socket `chat` cannot send what the player's setting hides.
     pub(super) fn handle_chat_input(&mut self, message: &str) {
+        if !self.chat_abilities().allows(message) {
+            return;
+        }
         self.ui.chat.add_recent(message);
         // On a server (single player's own included) the server runs it,
         // unless a client mod owns the command.
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index ba069522c..80adb5ff6 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -123,6 +123,9 @@ pub(super) struct Remote {
     loaded_sent: bool,
     /// The view distance last sent in ClientInformation.
     sent_view: i8,
+    /// The Chat option's visibility last sent in ClientInformation
+    /// (`Options.broadcastOptions` sends it again when it changes).
+    sent_chat_visibility: i32,
     /// BlockStatePredictionHandler: blocks changed ahead of the server (a predicted break),
     /// with the sequence of the last action that changed them and the state the server
     /// last said they have. Until the server acknowledges that sequence its block updates
@@ -430,6 +433,7 @@ impl Game<'_> {
             abilities: None,
             loaded_sent: false,
             sent_view: view,
+            sent_chat_visibility: self.settings.chat_visibility as i32,
             predictions: HashMap::new(),
             menu: None,
             menu_title: None,
@@ -794,8 +798,22 @@ impl Game<'_> {
         Some(stack)
     }
     /// A line in the connection's chat, with its styles, click and hover
-    /// events (ChatComponent.addMessage).
-    pub(super) fn chat_line(&mut self, content: horizon_client::text::Text) {
+    /// events (ChatComponent.addMessage). `ChatListener` drops the lines the
+    /// Chat option hides before they reach the chat.
+    pub(super) fn chat_line(
+        &mut self,
+        content: horizon_client::text::Text,
+        source: horizon_client::chat::ChatSource,
+    ) {
+        let abilities = self.chat_abilities();
+        let allowed = match source {
+            horizon_client::chat::ChatSource::Player => abilities.receive_player_messages,
+            horizon_client::chat::ChatSource::Server => abilities.receive_system_messages,
+            horizon_client::chat::ChatSource::Client => true,
+        };
+        if !allowed {
+            return;
+        }
         let text = content.plain();
         log::info!("[chat] {text}");
         self.ui.chat.add(
@@ -1776,9 +1794,10 @@ impl Game<'_> {
                 if let Some(r) = self.remote.as_mut() {
                     r.sent_view = view;
                 }
-                self.send(S::ClientInformation(
-                    horizon_protocol::packets::configuration::ClientInformation::new(view),
-                ));
+                let mut info =
+                    horizon_protocol::packets::configuration::ClientInformation::new(view);
+                info.chat_visibility = self.settings.chat_visibility as i32;
+                self.send(S::ClientInformation(info));
             }
             C::Respawn(p) => {
                 // A new player, without effects: the server sends them again.
@@ -2568,7 +2587,7 @@ impl Game<'_> {
                 if p.overlay {
                     self.titles.set_overlay(text, false);
                 } else {
-                    self.chat_line(text);
+                    self.chat_line(text, horizon_client::chat::ChatSource::Server);
                 }
             }
             C::PlayerChat(p) => {
@@ -2578,12 +2597,12 @@ impl Game<'_> {
                     .as_ref()
                     .map_or_else(|| serde_json::Value::from(p.content.as_str()), tag_to_json);
                 let line = self.format_chat(&p.chat_type, content);
-                self.chat_line(line);
+                self.chat_line(line, horizon_client::chat::ChatSource::Player);
             }
             C::DisguisedChat(p) => {
                 let content = horizon_client::scoreboard::tag_to_json(&p.message);
                 let line = self.format_chat(&p.chat_type, content);
-                self.chat_line(line);
+                self.chat_line(line, horizon_client::chat::ChatSource::Player);
             }
             C::PlayerInfoUpdate(p) => {
                 if let Some(r) = self.remote.as_mut() {
@@ -3216,16 +3235,19 @@ impl Game<'_> {
     fn tick_remote_level(&mut self) -> Result<()> {
         self.ticks += 1;
         self.track_experience_display();
-        // Options.broadcastOptions: a changed render distance is sent again.
+        // Options.broadcastOptions: a changed render distance or Chat option
+        // is sent again.
         let view = client_view_distance(self.settings.render_distance);
+        let visibility = self.settings.chat_visibility as i32;
         if let Some(r) = self.remote.as_mut()
             && r.joined
-            && r.sent_view != view
+            && (r.sent_view != view || r.sent_chat_visibility != visibility)
         {
             r.sent_view = view;
-            self.send(S::ClientInformation(
-                horizon_protocol::packets::configuration::ClientInformation::new(view),
-            ));
+            r.sent_chat_visibility = visibility;
+            let mut info = horizon_protocol::packets::configuration::ClientInformation::new(view);
+            info.chat_visibility = visibility;
+            self.send(S::ClientInformation(info));
         }
         // Minecraft.tick: TickRateManager.tick; ClientLevel.tickTime advances
         // the time only while the level runs normally.
@@ -4643,10 +4665,12 @@ impl Game<'_> {
             _ => Ok(false),
         }
     }
-    /// ClientPacketListener.sendChat / sendCommand (unsigned).
+    /// ClientPacketListener.sendChat / sendCommand (unsigned). The Chat
+    /// option's Hidden and System levels keep chat out and Hidden keeps the
+    /// commands out (ChatAbilities).
     pub(super) fn send_chat(&mut self, message: &str) {
         let message = message.trim();
-        if message.is_empty() {
+        if message.is_empty() || !self.chat_abilities().allows(message) {
             return;
         }
         if let Some(command) = message.strip_prefix('/') {
@@ -5026,9 +5050,12 @@ impl Game<'_> {
                 self.send(S::ContainerClose(play::ContainerClose {
                     container: p.container,
                 }));
-                self.chat_line(horizon_client::text::Text::literal(format!(
-                    "(Horizon cannot show {menu} screens yet)"
-                )));
+                self.chat_line(
+                    horizon_client::text::Text::literal(format!(
+                        "(Horizon cannot show {menu} screens yet)"
+                    )),
+                    horizon_client::chat::ChatSource::Client,
+                );
                 return;
             }
         };

From 3762ab7cdaa0f67c8cd473a88347098ebc982f92 Mon Sep 17 00:00:00 2001
From: Alexander Krylov <sashakryllov58@gmail.com>
Date: Sun, 25 Oct 2026 23:46:43 +0300
Subject: [PATCH 190/270] Enchantments: the name and the level follow the
 selected language

The registry resolved every `description` from the pinned `en_us` map at load
and `full_name` took `enchantment.level.<n>` from the same table, so a tooltip
showed an English enchantment line whatever language the player picked.

Keep the description's translation key and resolve it, and the level, through
the current language at display time, with the English text as the fallback for
the server thread, the probes and an old resource root.

Refs #1774.

Co-Authored-By: Hermes Agent (Nous Research) <noreply@nousresearch.com>
---
 crates/horizon-client/src/enchant.rs | 55 +++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 5 deletions(-)

diff --git a/crates/horizon-client/src/enchant.rs b/crates/horizon-client/src/enchant.rs
index 2fc9ef2fb..f5ddc84c2 100644
--- a/crates/horizon-client/src/enchant.rs
+++ b/crates/horizon-client/src/enchant.rs
@@ -33,7 +33,11 @@ impl Cost {
 #[derive(Clone, Debug)]
 pub struct Enchantment {
     pub id: Arc<str>,
+    /// The name the pinned English map gave at load: the fallback for a
+    /// language that has no entry for the key below.
     pub description: String,
+    /// `description`'s translation key (`enchantment.minecraft.<name>`).
+    pub description_key: String,
     pub max_level: u32,
     pub weight: u32,
     pub anvil_cost: u32,
@@ -224,6 +228,7 @@ impl Enchantments {
                     .get(key)
                     .cloned()
                     .unwrap_or_else(|| id.trim_start_matches("minecraft:").replace('_', " ")),
+                description_key: key.to_owned(),
                 max_level: v["max_level"].as_u64().unwrap_or(1) as u32,
                 weight: v["weight"].as_u64().unwrap_or(1) as u32,
                 anvil_cost: v["anvil_cost"].as_u64().unwrap_or(0) as u32,
@@ -329,16 +334,26 @@ impl Enchantments {
     }
     /// `Enchantment.getFullname` as plain text and whether it is a curse (red).
     pub fn full_name(&self, id: &str, level: u32) -> (String, bool) {
+        let language = crate::lang::current();
+        self.full_name_in(language.as_deref(), id, level)
+    }
+    /// `full_name` against `language`; `None` keeps the English names loaded
+    /// above, which is what the server thread and the probes see.
+    pub fn full_name_in(
+        &self,
+        language: Option<&crate::lang::Language>,
+        id: &str,
+        level: u32,
+    ) -> (String, bool) {
+        let tr = |key: &str| language.and_then(|l| l.get(key).map(str::to_owned));
         let Some(e) = self.get(id) else {
             return (format!("{id} {}", level_name(level)), false);
         };
-        let mut name = e.description.clone();
+        let mut name = tr(&e.description_key).unwrap_or_else(|| e.description.clone());
         if level != 1 || e.max_level != 1 {
             name.push(' ');
             name.push_str(
-                self.lang
-                    .get(&format!("enchantment.level.{level}"))
-                    .map_or(&level_name(level), |s| s),
+                &tr(&format!("enchantment.level.{level}")).unwrap_or_else(|| level_name(level)),
             );
         }
         (name, self.is_curse(id))
@@ -771,7 +786,7 @@ pub(crate) mod tests {
         let defs = [
             (
                 "minecraft:sharpness",
-                json!({"anvil_cost":1,"exclusive_set":"#minecraft:exclusive_set/damage","max_cost":{"base":21,"per_level_above_first":11},"max_level":5,"min_cost":{"base":1,"per_level_above_first":11},"primary_items":"#minecraft:enchantable/melee_weapon","supported_items":"#minecraft:enchantable/sharp_weapon","weight":10,"slots":["mainhand"],"effects":{"minecraft:damage":[{"effect":{"type":"minecraft:add","value":{"type":"minecraft:linear","base":1.0,"per_level_above_first":0.5}}}]}}),
+                json!({"anvil_cost":1,"description":{"translate":"enchantment.minecraft.sharpness"},"exclusive_set":"#minecraft:exclusive_set/damage","max_cost":{"base":21,"per_level_above_first":11},"max_level":5,"min_cost":{"base":1,"per_level_above_first":11},"primary_items":"#minecraft:enchantable/melee_weapon","supported_items":"#minecraft:enchantable/sharp_weapon","weight":10,"slots":["mainhand"],"effects":{"minecraft:damage":[{"effect":{"type":"minecraft:add","value":{"type":"minecraft:linear","base":1.0,"per_level_above_first":0.5}}}]}}),
             ),
             (
                 "minecraft:smite",
@@ -795,6 +810,7 @@ pub(crate) mod tests {
             .map(|(id, v)| Enchantment {
                 id: Arc::from(*id),
                 description: id.trim_start_matches("minecraft:").into(),
+                description_key: v["description"]["translate"].as_str().unwrap_or("").into(),
                 max_level: v["max_level"].as_u64().unwrap() as u32,
                 weight: v["weight"].as_u64().unwrap() as u32,
                 anvil_cost: v["anvil_cost"].as_u64().unwrap() as u32,
@@ -1088,4 +1104,33 @@ pub(crate) mod tests {
         assert!(!e.compatible("minecraft:sharpness", "minecraft:smite"));
         assert!(e.compatible("minecraft:sharpness", "minecraft:unbreaking"));
     }
+
+    /// The enchantment's name and its level come from the selected language,
+    /// with the English name loaded above as the fallback.
+    #[test]
+    fn names_follow_the_language() {
+        struct Mem(HashMap<String, Vec<u8>>);
+        impl crate::lang::ResourceSource for Mem {
+            fn read(&self, path: &str) -> Option<Vec<u8>> {
+                self.0.get(path).cloned()
+            }
+        }
+        let ru = Mem(HashMap::from([(
+            "assets/minecraft/lang/ru_ru.json".to_owned(),
+            r#"{"enchantment.minecraft.sharpness":"Острота","enchantment.level.5":"V"}"#
+                .as_bytes()
+                .to_vec(),
+        )]));
+        let ru = crate::lang::Language::load(&[&ru], "ru_ru");
+        let e = sample();
+        assert_eq!(
+            e.full_name_in(Some(&ru), "minecraft:sharpness", 5).0,
+            "Острота V"
+        );
+        // mending carries no key in the fixture: the English name stays.
+        assert_eq!(
+            e.full_name_in(Some(&ru), "minecraft:mending", 1).0,
+            "mending"
+        );
+    }
 }

From b71623dfd7a7b402b40bf6424efbcfae8f8e8c64 Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:50:12 +0500
Subject: [PATCH 191/270] Item cooldowns: the sweep on a slot, and no use while
 one runs

Nothing tracked `ItemCooldowns`: `draw_item_decorations` passed a cooldown of
0.0 with a note that there was none to shade, and ender pearls were held back
by an ad-hoc `pearl_cooldown` counter.

`horizon_client::cooldowns` keeps the `use_cooldown` component's entries by
cooldown group the way `Player.getCooldowns` does (start and end ticks, the
percent `getCooldownPercent` returns), `ItemInfo` now carries the item's
`use_cooldown`, and the game uses it where vanilla does:
`ServerPlayerGameMode.useItem`/useItemOn refuse a stack on cooldown,
`ItemStack.applyAfterUseComponentSideEffects` starts the entry when a use
finishes (a thrown pearl, a wind charge, an eaten chorus fruit),
`GuiGraphicsExtractor.itemCooldown` shades the slot, and a server's guests
keep their own and are sent `ClientboundCooldownPacket` (started, and 0 when
it ends), which a client applies.

Fixes #1763

Co-Authored-By: [CC] <deepseek-v4.1-flash> <noreply@deepseek.com>
---
 crates/horizon-client/src/cooldowns.rs        | 174 ++++++++++++++++++
 crates/horizon-client/src/game.rs             |  56 +++++-
 crates/horizon-client/src/game/creatures.rs   |  24 +--
 crates/horizon-client/src/game/lan_actions.rs |  31 +++-
 crates/horizon-client/src/game/remote.rs      |  18 +-
 crates/horizon-client/src/game/wind.rs        |   4 -
 crates/horizon-client/src/items.rs            |   5 +
 crates/horizon-client/src/lib.rs              |   1 +
 crates/horizon-protocol/src/packets/play.rs   |  22 +++
 9 files changed, 306 insertions(+), 29 deletions(-)
 create mode 100644 crates/horizon-client/src/cooldowns.rs

diff --git a/crates/horizon-client/src/cooldowns.rs b/crates/horizon-client/src/cooldowns.rs
new file mode 100644
index 000000000..31e882712
--- /dev/null
+++ b/crates/horizon-client/src/cooldowns.rs
@@ -0,0 +1,174 @@
+//! `Player.getCooldowns()` (`ItemCooldowns`) as the game keeps it: the
+//! `use_cooldown` component's entries by cooldown group, counted down once a
+//! tick, and the percent `GuiGraphicsExtractor.itemCooldown` shades a slot
+//! by. The world crate's `item_cooldowns` models vanilla's hash map and its
+//! observers for the parity harness; this is the same data with the lookup a
+//! slot needs, and no observer (vanilla's own player uses the plain class).
+use crate::items::ItemStack;
+use horizon_world::nbt::Tag;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+/// A stack's `minecraft:use_cooldown` component.
+#[derive(Clone, Debug, PartialEq)]
+pub struct UseCooldown {
+    pub seconds: f32,
+    /// `cooldown_group`: the group the entry is filed under, else the item.
+    pub group: Option<Arc<str>>,
+}
+impl UseCooldown {
+    /// `UseCooldown.ticks`: the seconds in ticks, truncated.
+    pub fn ticks(&self) -> i32 {
+        (self.seconds * 20.0) as i32
+    }
+    /// The component as `items.json` holds it.
+    pub fn from_json(v: &serde_json::Value) -> Option<Self> {
+        let seconds = v.get("seconds")?.as_f64()? as f32;
+        Some(Self {
+            seconds,
+            group: v
+                .get("cooldown_group")
+                .and_then(|g| g.as_str())
+                .map(Arc::from),
+        })
+    }
+    /// The component as a stack's saved `components` holds it.
+    pub fn from_tag(t: &Tag) -> Option<Self> {
+        let Tag::Compound(c) = t else {
+            return None;
+        };
+        let text = |k: &str| match c.get(&horizon_world::nbt::JavaString::from(k)) {
+            Some(Tag::String(s)) => Some(s.to_string_lossy()),
+            _ => None,
+        };
+        let seconds = match c.get(&horizon_world::nbt::JavaString::from("seconds")) {
+            Some(Tag::Float(bits)) => f32::from_bits(*bits),
+            Some(Tag::Double(bits)) => f64::from_bits(*bits) as f32,
+            _ => return None,
+        };
+        Some(Self {
+            seconds,
+            group: text("cooldown_group").map(Arc::from),
+        })
+    }
+}
+
+/// The component a stack carries: its own patch first (`ItemStack.get`), then
+/// the item's default from `items.json` (`ItemInfo::use_cooldown`).
+pub fn component(stack: &ItemStack, default: Option<&UseCooldown>) -> Option<UseCooldown> {
+    stack
+        .data()
+        .and_then(|d| d.other("minecraft:use_cooldown"))
+        .and_then(UseCooldown::from_tag)
+        .or_else(|| default.cloned())
+}
+
+/// `ItemCooldowns.getCooldownGroup`: the component's group, else the item id.
+pub fn group(stack: &ItemStack, default: Option<&UseCooldown>) -> Arc<str> {
+    component(stack, default)
+        .and_then(|c| c.group)
+        .unwrap_or_else(|| Arc::clone(&stack.item))
+}
+
+/// `ItemCooldowns`: start and end ticks by group, and the tick counter.
+#[derive(Clone, Debug, Default)]
+pub struct Cooldowns {
+    tick_count: i32,
+    entries: HashMap<Arc<str>, (i32, i32)>,
+}
+impl Cooldowns {
+    /// `getCooldownPercent`: what is left of the entry, from 1 to 0.
+    pub fn percent(&self, group: &str, partial_tick: f32) -> f32 {
+        let Some((start, end)) = self.entries.get(group) else {
+            return 0.0;
+        };
+        let duration = end.wrapping_sub(*start) as f32;
+        let remaining = *end as f32 - (self.tick_count as f32 + partial_tick);
+        (remaining / duration).clamp(0.0, 1.0)
+    }
+    /// `isOnCooldown`: whether the group still has time to run.
+    pub fn is_on_cooldown(&self, group: &str) -> bool {
+        self.percent(group, 0.0) > 0.0
+    }
+    /// `addCooldown`.
+    pub fn add(&mut self, group: Arc<str>, ticks: i32) {
+        self.entries.insert(
+            group,
+            (self.tick_count, self.tick_count.wrapping_add(ticks)),
+        );
+    }
+    /// `ItemCooldowns.tick`: the counter, then every entry that has run out,
+    /// which it hands back (`onCooldownEnded`).
+    pub fn tick(&mut self) -> Vec<Arc<str>> {
+        self.tick_count = self.tick_count.wrapping_add(1);
+        let done: Vec<Arc<str>> = self
+            .entries
+            .iter()
+            .filter(|(_, (_, end))| *end <= self.tick_count)
+            .map(|(group, _)| Arc::clone(group))
+            .collect();
+        self.entries.retain(|_, (_, end)| *end > self.tick_count);
+        done
+    }
+    /// `removeCooldown`.
+    pub fn remove(&mut self, group: &str) {
+        self.entries.remove(group);
+    }
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn stack(item: &str) -> ItemStack {
+        ItemStack::new(item, 1)
+    }
+
+    #[test]
+    fn the_percent_falls_from_one_to_zero_over_the_entry() {
+        let mut c = Cooldowns::default();
+        c.add(Arc::from("minecraft:ender_pearl"), 20);
+        assert!(c.is_on_cooldown("minecraft:ender_pearl"));
+        assert_eq!(c.percent("minecraft:ender_pearl", 0.0), 1.0);
+        for _ in 0..10 {
+            assert!(c.tick().is_empty());
+        }
+        assert_eq!(c.percent("minecraft:ender_pearl", 0.0), 0.5);
+        // The partial tick moves it within the tick.
+        assert_eq!(c.percent("minecraft:ender_pearl", 0.5), 0.475);
+        for _ in 0..9 {
+            c.tick();
+        }
+        assert!(c.is_on_cooldown("minecraft:ender_pearl"));
+        // ItemCooldowns.tick drops the entry at its end tick, and says so.
+        assert_eq!(c.tick(), [Arc::<str>::from("minecraft:ender_pearl")]);
+        assert!(!c.is_on_cooldown("minecraft:ender_pearl"));
+        assert!(c.is_empty());
+        assert_eq!(c.percent("minecraft:ender_pearl", 0.0), 0.0);
+    }
+
+    #[test]
+    fn the_group_comes_from_the_stack_then_the_item() {
+        let pearl = stack("minecraft:ender_pearl");
+        let default = UseCooldown::from_json(&json!({"seconds": 1.0})).expect("the component");
+        assert_eq!(&*group(&pearl, Some(&default)), "minecraft:ender_pearl");
+        // A stack's own component overrides the item's, group included.
+        let mut grouped = stack("minecraft:ender_pearl");
+        grouped.data_mut().set_other(
+            "minecraft:use_cooldown",
+            Some(Tag::compound([
+                ("seconds", Tag::Float(2.0f32.to_bits())),
+                ("cooldown_group", Tag::String("minecraft:pearls".into())),
+            ])),
+        );
+        let c = component(&grouped, Some(&default)).expect("the stack's component");
+        assert_eq!(c.ticks(), 40);
+        assert_eq!(&*group(&grouped, Some(&default)), "minecraft:pearls");
+        // An item without the component has no cooldown.
+        assert!(component(&stack("minecraft:dirt"), None).is_none());
+    }
+}
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f05ee41e4..d7ec53eea 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1320,6 +1320,10 @@ struct Game<'a> {
     hand: Hand,
     /// The shield's item cooldown after an axe disabled it (ticks).
     shield_cooldown: u32,
+    /// `Player.getCooldowns()`: the `use_cooldown` component's entries, what
+    /// `itemDecorations` shades a slot by. A server's players have their own
+    /// (`GuestPlay::cooldowns`), swapped in for their turn.
+    cooldowns: horizon_client::cooldowns::Cooldowns,
     /// The source of a command run through /execute (the player otherwise).
     command_source: Option<commands::execute::Source>,
     titles: titles::Titles,
@@ -1558,6 +1562,9 @@ struct Game<'a> {
     chat_capture: Option<Vec<horizon_client::text::Text>>,
     /// Packets for the guest acting now, sent once its action returns.
     guest_packets: Vec<horizon_protocol::packets::play::Clientbound>,
+    /// The acting guest's cooldowns, as (item, ticks): their packet needs the
+    /// hub's item registry, which the guest's turn does not hold.
+    guest_cooldowns: Vec<(Arc<str>, i32)>,
     /// `broadcastToAdmins` lines a guest's command queued, sent once it
     /// returns: the line, whether operators get it and whether the console
     /// logs it.
@@ -3394,6 +3401,25 @@ impl Game<'_> {
             || self.interact_mob()?
             || self.interact_knot())
     }
+    /// `ItemStack.applyAfterUseComponentSideEffects`: a used stack with a
+    /// `use_cooldown` component starts its entry (`UseCooldown.apply`). A
+    /// server's guest also gets `ClientboundCooldownPacket`
+    /// (`ServerItemCooldowns.onCooldownStarted`), queued for their turn's end.
+    pub(super) fn apply_use_cooldown(&mut self, stack: &ItemStack) {
+        let default = self
+            .res
+            .items()
+            .get(&stack.item)
+            .and_then(|i| i.use_cooldown.clone());
+        let Some(component) = horizon_client::cooldowns::component(stack, default.as_ref()) else {
+            return;
+        };
+        let group = horizon_client::cooldowns::group(stack, default.as_ref());
+        self.cooldowns.add(Arc::clone(&group), component.ticks());
+        if self.lan_acting.is_some() {
+            self.guest_cooldowns.push((group, component.ticks()));
+        }
+    }
     /// One hand's turn in `startUseItem`: `useItemOn` the block aimed at,
     /// then `useItem`. Whether the click ends here (it acted or failed).
     fn use_hand(&mut self, block_hit: Option<&Hit>) -> Result<bool> {
@@ -3478,6 +3504,17 @@ impl Game<'_> {
         let Some(info) = self.res.items().get(&stack.item).cloned() else {
             return Ok(false);
         };
+        // ServerPlayerGameMode.useItem and useItemOn: an item on cooldown is
+        // not used (PASS, so the other hand may still act).
+        if self
+            .cooldowns
+            .is_on_cooldown(&horizon_client::cooldowns::group(
+                &stack,
+                info.use_cooldown.as_ref(),
+            ))
+        {
+            return Ok(false);
+        }
         if block_hit.is_some() && (self.use_bone_meal(&stack)? || self.ignite_tnt(&stack)?) {
             return Ok(true);
         }
@@ -3804,6 +3841,8 @@ impl Game<'_> {
         }
         if ticks >= duration {
             self.using = None;
+            // ItemStack.finishUsingItem's applyAfterUseComponentSideEffects.
+            self.apply_use_cooldown(&stack);
             self.finish_consuming(&info, consumable, &stack);
         } else {
             self.using = Some((slot, ticks));
@@ -4405,6 +4444,7 @@ impl Game<'_> {
         // Player.tick's ItemCooldowns.tick for the window's player (a
         // server's players count theirs down in `tick_guests`).
         self.shield_cooldown = self.shield_cooldown.saturating_sub(1);
+        self.cooldowns.tick();
         horizon_client::spans::time("tick_using", || self.tick_using());
         horizon_client::spans::time("tick_hud", || self.tick_hud());
         // The player's digging comes in with its packets, before the level
@@ -4786,17 +4826,17 @@ impl Game<'_> {
         count_text: Option<String>,
     ) {
         // GuiGraphicsExtractor.itemDecorations, laid out at the origin and
-        // moved to (x, y). Horizon tracks no item cooldowns to shade yet.
-        let max_damage = self
-            .res
-            .items()
-            .get(&stack.item)
-            .map_or(0, |info| info.max_damage as i32);
+        // moved to (x, y): the damage bar, the cooldown shade and the count.
+        let info = self.res.items().get(&stack.item);
+        let max_damage = info.map_or(0, |info| info.max_damage as i32);
+        let cooldown =
+            horizon_client::cooldowns::group(stack, info.and_then(|i| i.use_cooldown.as_ref()));
+        let partial = self.clock.fraction() as f32;
         let decorations = hud_overlays::ItemDecorations {
             count: stack.count,
             count_text,
             bar: hud_overlays::damage_bar(stack.damage as i32, max_damage),
-            cooldown: 0.0,
+            cooldown: self.cooldowns.percent(&cooldown, partial),
         };
         let mut draws = vec![hud_layout::GuiDraw::Push(vec![
             hud_layout::PoseOp::Translate(x, y),
@@ -11880,6 +11920,7 @@ impl<'a> Game<'a> {
             offhand: None,
             hand: Hand::Main,
             shield_cooldown: 0,
+            cooldowns: Default::default(),
             command_source: None,
             titles: Default::default(),
             tool_highlight: Default::default(),
@@ -12028,6 +12069,7 @@ impl<'a> Game<'a> {
             lid_openers: HashMap::new(),
             lan_acting: None,
             guest_packets: Vec::new(),
+            guest_cooldowns: Vec::new(),
             lan_acting_name: None,
             lan_acting_uuid: None,
             chat_capture: None,
diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 5cc6d7db7..9b2044d62 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -44,9 +44,7 @@ fn arrow_damage(arrow: &mut Projectile, fallback: &mut impl RandomSource) -> f32
 pub(super) struct Creatures {
     pub projectiles: Vec<Projectile>,
     /// Player status effects applied by mobs: (effect, ticks left, amplifier).
-    pub pearl_cooldown: u32,
     /// The wind charge's use cooldown (ticks).
-    pub wind_cooldown: u32,
     /// Wind bursts from a guest's turn, waiting for it to end (game/wind.rs).
     pub wind_bursts: Vec<super::wind::Burst>,
     /// Ticks left of the elder guardian's apparition (MobAppearanceParticle).
@@ -642,7 +640,6 @@ impl Game<'_> {
         self.tick_allays();
         self.tick_breeze_effects();
         self.tick_sniffer_effects();
-        self.tick_player_effects();
         self.piglin_pickups();
         self.sulfur_cube_pickups();
         // Hurt and death sounds of damage dealt outside the mob ticks.
@@ -1563,12 +1560,6 @@ impl Game<'_> {
             ));
     }
     /// Burning applied to the player by mobs.
-    fn tick_player_effects(&mut self) {
-        self.creatures.wind_cooldown = self.creatures.wind_cooldown.saturating_sub(1);
-        if self.creatures.pearl_cooldown > 0 {
-            self.creatures.pearl_cooldown -= 1;
-        }
-    }
     pub(super) fn hurt_player_by(&mut self, damage_type: &str, amount: f32) {
         if self.creative {
             return;
@@ -2869,14 +2860,14 @@ impl Game<'_> {
         let kind = match item {
             "minecraft:snowball" => ProjectileKind::Snowball,
             "minecraft:egg" | "minecraft:blue_egg" | "minecraft:brown_egg" => ProjectileKind::Egg,
-            "minecraft:ender_pearl" => {
-                if self.creatures.pearl_cooldown > 0 {
-                    return Ok(true);
+            "minecraft:ender_pearl" => ProjectileKind::EnderPearl,
+            "minecraft:wind_charge" => {
+                let thrown = self.throw_wind_charge()?;
+                if thrown {
+                    self.apply_use_cooldown(stack);
                 }
-                self.creatures.pearl_cooldown = 20;
-                ProjectileKind::EnderPearl
+                return Ok(thrown);
             }
-            "minecraft:wind_charge" => return self.throw_wind_charge(),
             _ if item.ends_with("_spawn_egg") => return self.use_spawn_egg(stack),
             _ => return Ok(false),
         };
@@ -2901,6 +2892,9 @@ impl Game<'_> {
         );
         self.creatures.projectiles.push(proj);
         self.player_projectile_shot();
+        // ItemStack.use's applyAfterUseComponentSideEffects: the pearl's
+        // second is the `use_cooldown` component, as for any thrown item.
+        self.apply_use_cooldown(stack);
         let sound = match kind {
             ProjectileKind::Snowball => "minecraft:entity.snowball.throw",
             ProjectileKind::Egg => "minecraft:entity.egg.throw",
diff --git a/crates/horizon-client/src/game/lan_actions.rs b/crates/horizon-client/src/game/lan_actions.rs
index 02434d793..2b033ba2d 100644
--- a/crates/horizon-client/src/game/lan_actions.rs
+++ b/crates/horizon-client/src/game/lan_actions.rs
@@ -38,6 +38,8 @@ pub(super) struct GuestPlay {
     use_delay: u32,
     /// The shield's ItemCooldowns entry: an axe disabled it for this many ticks.
     pub(super) shield_cooldown: u32,
+    /// The guest's `Player.getCooldowns()` (`Game::cooldowns` for its turn).
+    pub(super) cooldowns: horizon_client::cooldowns::Cooldowns,
     attack_ticks: u32,
     /// The main hand's item at the guest's last tick (`Game::attack_item`).
     attack_item: Option<std::sync::Arc<str>>,
@@ -125,6 +127,8 @@ pub(super) struct GuestSwap {
     using: Option<(usize, u32)>,
     use_delay: u32,
     pub(super) shield_cooldown: u32,
+    /// The guest's item cooldowns (`Game::cooldowns` for its turn).
+    cooldowns: horizon_client::cooldowns::Cooldowns,
     attack_ticks: u32,
     attack_item: Option<std::sync::Arc<str>>,
     swing: horizon_client::first_person::SwingState,
@@ -316,6 +320,7 @@ impl Game<'_> {
         let using = std::mem::replace(&mut self.using, play.using.take());
         let use_delay = std::mem::replace(&mut self.use_delay, play.use_delay);
         let shield_cooldown = std::mem::replace(&mut self.shield_cooldown, play.shield_cooldown);
+        let cooldowns = std::mem::replace(&mut self.cooldowns, std::mem::take(&mut play.cooldowns));
         let attack_ticks = std::mem::replace(&mut self.attack_ticks, play.attack_ticks);
         let attack_item = std::mem::replace(&mut self.attack_item, play.attack_item.take());
         let swing = std::mem::replace(&mut self.swing, play.swing);
@@ -400,6 +405,7 @@ impl Game<'_> {
             using,
             use_delay,
             shield_cooldown,
+            cooldowns,
             attack_ticks,
             attack_item,
             swing,
@@ -456,6 +462,7 @@ impl Game<'_> {
             using,
             use_delay,
             shield_cooldown,
+            cooldowns,
             attack_ticks,
             attack_item,
             swing,
@@ -491,6 +498,16 @@ impl Game<'_> {
         for packet in std::mem::replace(&mut self.guest_packets, packets) {
             host.hub.send_to(conn, &packet);
         }
+        // ServerItemCooldowns.onCooldownStarted: the guest's own cooldown.
+        for (group, duration) in std::mem::take(&mut self.guest_cooldowns) {
+            host.hub.send_to(
+                conn,
+                &C::Cooldown(play::Cooldown {
+                    group: group.to_string(),
+                    duration,
+                }),
+            );
+        }
         (self.lan_acting, self.lan_acting_name, self.lan_acting_uuid) = acting;
         play.death_cause = std::mem::replace(&mut self.ui.death_cause, death_cause);
         // An ender chest the guest opened: the menu shows their inventory
@@ -520,6 +537,7 @@ impl Game<'_> {
         play.using = std::mem::replace(&mut self.using, using);
         play.use_delay = std::mem::replace(&mut self.use_delay, use_delay);
         play.shield_cooldown = std::mem::replace(&mut self.shield_cooldown, shield_cooldown);
+        play.cooldowns = std::mem::replace(&mut self.cooldowns, cooldowns);
         play.attack_ticks = std::mem::replace(&mut self.attack_ticks, attack_ticks);
         play.attack_item = std::mem::replace(&mut self.attack_item, attack_item);
         play.swing = std::mem::replace(&mut self.swing, swing);
@@ -1783,8 +1801,19 @@ impl Game<'_> {
             }
             let play = host.play.entry(conn).or_default();
             // Player.tick's ItemCooldowns.tick, once a tick for each player
-            // (the shield an axe disabled).
+            // (the shield an axe disabled, a thrown pearl).
             play.shield_cooldown = play.shield_cooldown.saturating_sub(1);
+            // ServerItemCooldowns.onCooldownEnded: a finished entry is told to
+            // the guest (a duration of 0 removes it).
+            for group in play.cooldowns.tick() {
+                host.hub.send_to(
+                    conn,
+                    &C::Cooldown(play::Cooldown {
+                        group: group.to_string(),
+                        duration: 0,
+                    }),
+                );
+            }
             let digging = play.digging;
             let using = play.using.is_some();
             let delayed = play.destroy_delay > 0 || play.use_delay > 0 || play.attack_ticks < 100;
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index ba069522c..0f6bad14a 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -2561,6 +2561,16 @@ impl Game<'_> {
                     r.commands = Some(tree);
                 }
             }
+            C::Cooldown(p) => {
+                // ClientPacketListener.handleItemCooldown: the server starts
+                // (or confirms) a group's cooldown; 0 ends it.
+                let group: Arc<str> = Arc::from(p.group.as_str());
+                if p.duration == 0 {
+                    self.cooldowns.remove(&group);
+                } else {
+                    self.cooldowns.add(group, p.duration);
+                }
+            }
             C::SystemChat(p) => {
                 // The component as sent, translated in the client's own
                 // language. ChatListener.handleOverlay for the action bar.
@@ -4303,8 +4313,12 @@ impl Game<'_> {
         let Some(info) = self.res.items().get(&held.item).cloned() else {
             return false;
         };
-        // MultiPlayerGameMode.useItem runs the use here too: food starts
-        // being eaten (Consumable.startConsuming), a book and quill opens.
+        // MultiPlayerGameMode.useItem runs the use here too (inside
+        // startPrediction): the `use_cooldown` component starts its entry, and
+        // the server's ClientboundCooldownPacket confirms it.
+        self.apply_use_cooldown(&held);
+        // Food starts being eaten (Consumable.startConsuming), a book and
+        // quill opens.
         self.with_hand(hand, |g| g.start_eating(&info));
         if self.with_hand(hand, |g| g.remote_use_book(&held)) {
             return true;
diff --git a/crates/horizon-client/src/game/wind.rs b/crates/horizon-client/src/game/wind.rs
index 0754bca8b..fb24102ba 100644
--- a/crates/horizon-client/src/game/wind.rs
+++ b/crates/horizon-client/src/game/wind.rs
@@ -52,10 +52,6 @@ fn triggers(name: &str) -> bool {
 impl Game<'_> {
     /// `WindChargeItem.use`.
     pub(super) fn throw_wind_charge(&mut self) -> Result<bool> {
-        if self.creatures.wind_cooldown > 0 {
-            return Ok(true);
-        }
-        self.creatures.wind_cooldown = 10;
         let (Some(eye), Some(p)) = (self.eye_position(), self.player.as_ref()) else {
             return Ok(false);
         };
diff --git a/crates/horizon-client/src/items.rs b/crates/horizon-client/src/items.rs
index 95e7e2c42..8ac450bcb 100644
--- a/crates/horizon-client/src/items.rs
+++ b/crates/horizon-client/src/items.rs
@@ -77,6 +77,8 @@ pub struct ItemInfo {
     pub consumable: Option<horizon_world::consumable::Consumable<String, ConsumeEffect>>,
     /// `use_remainder`: what a finished use leaves (`UseRemainder`).
     pub use_remainder: Option<String>,
+    /// `use_cooldown`: the cooldown a use starts (`UseCooldown`).
+    pub use_cooldown: Option<crate::cooldowns::UseCooldown>,
     pub model: String,
     /// Main-hand `attack_damage` / `attack_speed` modifier amounts.
     pub attack_damage: f32,
@@ -568,6 +570,9 @@ impl Items {
                     use_remainder: c["minecraft:use_remainder"]["id"]
                         .as_str()
                         .map(str::to_owned),
+                    use_cooldown: c
+                        .get("minecraft:use_cooldown")
+                        .and_then(crate::cooldowns::UseCooldown::from_json),
                     model: c["minecraft:item_model"]
                         .as_str()
                         .unwrap_or(name)
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index ae95e1bdb..722a4dab0 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -46,6 +46,7 @@ pub mod confirm_screen;
 pub mod container_screen;
 pub mod containers;
 pub mod control;
+pub mod cooldowns;
 pub mod crafting;
 pub mod crash;
 pub mod creative;
diff --git a/crates/horizon-protocol/src/packets/play.rs b/crates/horizon-protocol/src/packets/play.rs
index 67373cf4b..9f7ec4c6a 100644
--- a/crates/horizon-protocol/src/packets/play.rs
+++ b/crates/horizon-protocol/src/packets/play.rs
@@ -176,6 +176,9 @@ packet!(
     }
 );
 packet!(ContainerSetData { container: i32 => VarInt, id: i16 => Short, value: i16 => Short });
+// ClientboundCooldownPacket: the cooldown group (an identifier) and the ticks
+// its entry lasts (0 ends it).
+packet!(Cooldown { group: String => Ident, duration: i32 => VarInt });
 packet!(ContainerSetSlot { container: i32 => VarInt, state: i32 => VarInt, slot: i16 => Short, item: Option<Stack> => Slot });
 /// A holder reference: registry id + 1, or 0 for an inline value (unsupported).
 pub struct HolderId;
@@ -1761,6 +1764,7 @@ packet_enum!(Clientbound, crate::ids::play::clientbound {
     ContainerSetData(ContainerSetData) = CONTAINER_SET_DATA,
     ContainerSetSlot(ContainerSetSlot) = CONTAINER_SET_SLOT,
     CookieRequest(CookieRequest) = COOKIE_REQUEST,
+    Cooldown(Cooldown) = COOLDOWN,
     CustomPayload(CustomPayload) = CUSTOM_PAYLOAD,
     Disconnect(Disconnect) = DISCONNECT,
     DisguisedChat(DisguisedChat) = DISGUISED_CHAT,
@@ -2894,6 +2898,24 @@ mod tests {
         round_trip(beacon, Serverbound::encode, Serverbound::decode);
     }
 
+    #[test]
+    fn a_cooldown_packet_carries_its_group_and_ticks() {
+        let packet = Clientbound::Cooldown(Cooldown {
+            group: "minecraft:ender_pearl".into(),
+            duration: 20,
+        });
+        round_trip(packet, Clientbound::encode, Clientbound::decode);
+        // The group is an identifier, the ticks a VarInt; a duration of 0
+        // removes the entry.
+        let body = Clientbound::encode(&Clientbound::Cooldown(Cooldown {
+            group: "minecraft:ender_pearl".into(),
+            duration: 0,
+        }));
+        assert_eq!(body[0], crate::ids::play::clientbound::COOLDOWN as u8);
+        assert_eq!(&body[1..3], [21, b'm']);
+        assert_eq!(body[body.len() - 1], 0);
+    }
+
     #[test]
     fn change_game_mode_uses_the_game_type_varint() {
         for mode in 0..=3 {

From 2761349d98199a2695e629bf2f911c2d0db7a6c8 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:50:49 +0100
Subject: [PATCH 192/270] Renderer: no indirect buffer usage without indirect
 draws (OpenGL before 4.3)

wgpu refuses to create a buffer with INDIRECT usage on a device without
DownlevelFlags::INDIRECT_EXECUTION (OpenGL before 4.3 without compute shaders), so the game
panicked creating 'Section draws'. Multi-draw now also needs indirect execution, and without it
the buffer has no INDIRECT usage: sections are drawn one direct draw each, as they already were
without INDIRECT_FIRST_INSTANCE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/gfx.rs | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index baa8c5099..cd40ea22e 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2182,15 +2182,26 @@ impl Renderer {
             )
         });
         let sorted_indices = arena::Arena::indices(&device, 1 << 16, flat.is_some());
+        let multi_draw = device
+            .features()
+            .contains(wgpu::Features::INDIRECT_FIRST_INSTANCE)
+            && adapter
+                .get_downlevel_capabilities()
+                .flags
+                .contains(wgpu::DownlevelFlags::INDIRECT_EXECUTION);
+        // Without indirect draws (OpenGL before 4.3 without compute shaders)
+        // even creating an indirect buffer fails; one draw per section reads
+        // `draws` on the CPU instead.
         let indirect = device.create_buffer(&wgpu::BufferDescriptor {
             label: Some("Section draws"),
             size: 1024 * 20,
-            usage: wgpu::BufferUsages::INDIRECT | wgpu::BufferUsages::COPY_DST,
+            usage: if multi_draw {
+                wgpu::BufferUsages::INDIRECT | wgpu::BufferUsages::COPY_DST
+            } else {
+                wgpu::BufferUsages::COPY_DST
+            },
             mapped_at_creation: false,
         });
-        let multi_draw = device
-            .features()
-            .contains(wgpu::Features::INDIRECT_FIRST_INSTANCE);
         // HORIZON_GPU_CULL=0 turns occlusion culling off, `all` culls every
         // frame however few its draws and little it hides, `shader` tests in
         // the shader as on Metal (A/B checks).

From 95c336a3870b003b6da5b7baae01d87e8cddee4b Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 20:50:57 +0000
Subject: [PATCH 193/270] fix(threads): lower helper thread priority on Android

Co-Authored-By: Codex (gpt-6.1-sol) <noreply@openai.com>
---
 crates/horizon-threads/Cargo.toml |  2 +-
 crates/horizon-threads/src/lib.rs | 18 +++++++++---------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/crates/horizon-threads/Cargo.toml b/crates/horizon-threads/Cargo.toml
index 3d7581fe9..d43b3e4fc 100644
--- a/crates/horizon-threads/Cargo.toml
+++ b/crates/horizon-threads/Cargo.toml
@@ -6,7 +6,7 @@ license.workspace = true
 rust-version = "1.85"
 description = "Scheduling hints for the game's threads: the OS calls the crates that forbid unsafe code can't make"
 
-[target.'cfg(any(target_vendor = "apple", target_os = "linux"))'.dependencies]
+[target.'cfg(any(target_vendor = "apple", target_os = "linux", target_os = "android"))'.dependencies]
 libc = "0.2"
 
 [target.'cfg(windows)'.dependencies]
diff --git a/crates/horizon-threads/src/lib.rs b/crates/horizon-threads/src/lib.rs
index ae4cc753f..7e9146ce7 100644
--- a/crates/horizon-threads/src/lib.rs
+++ b/crates/horizon-threads/src/lib.rs
@@ -45,8 +45,8 @@ fn favour() -> bool {
 /// behind the server thread and the render thread (`behind_server`).
 static HELPERS_BEHIND: AtomicBool = AtomicBool::new(false);
 
-/// How many nice levels a helper thread goes below the process on Linux.
-#[cfg(target_os = "linux")]
+/// How many nice levels a helper thread goes below the process on Linux and Android.
+#[cfg(any(target_os = "linux", target_os = "android"))]
 const BEHIND: i32 = 10;
 
 /// From now on, the helper threads that call `behind_server` as they start
@@ -58,7 +58,7 @@ pub fn put_helpers_behind() {
 
 /// Called by a helper thread as it starts (world generation, lighting and
 /// meshing, a connection's packet writer): work no tick or frame waits for.
-/// Once `put_helpers_behind` was called, on Linux, where the server and
+/// Once `put_helpers_behind` was called, on Linux and Android, where the server and
 /// render threads can't be raised (`favour_current`), the helper lowers
 /// itself instead, which an unprivileged thread may: 10 nice levels below
 /// the process, or, where nice runs out (a game started under nice 10 or
@@ -69,10 +69,10 @@ pub fn behind_server() -> bool {
     HELPERS_BEHIND.load(Ordering::Relaxed) && behind()
 }
 
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "android"))]
 fn behind() -> bool {
     // SAFETY: these read and set the calling thread's own nice value or
-    // policy (who 0, pid 0 is the calling thread on Linux); `param` lives
+    // policy (who 0, pid 0 is the calling thread on Linux and Android); `param` lives
     // across the call.
     unsafe {
         let nice = libc::getpriority(libc::PRIO_PROCESS as _, 0);
@@ -85,7 +85,7 @@ fn behind() -> bool {
     }
 }
 
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "android")))]
 fn behind() -> bool {
     false
 }
@@ -117,12 +117,12 @@ mod tests {
     }
 
     /// A helper goes behind only once a dedicated server asks for it, and
-    /// then, on Linux, 10 nice levels below the process or in the idle class.
+    /// then, on Linux and Android, 10 nice levels below the process or in the idle class.
     #[test]
     fn helpers_go_behind_only_when_asked() {
         assert!(!std::thread::spawn(super::behind_server).join().unwrap());
         super::put_helpers_behind();
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android"))]
         std::thread::spawn(|| {
             // SAFETY: reads the calling thread's own nice value.
             let before = unsafe { libc::getpriority(libc::PRIO_PROCESS as _, 0) };
@@ -142,7 +142,7 @@ mod tests {
         })
         .join()
         .unwrap();
-        #[cfg(not(target_os = "linux"))]
+        #[cfg(not(any(target_os = "linux", target_os = "android")))]
         assert!(!std::thread::spawn(super::behind_server).join().unwrap());
     }
 }

From 8dcd00fc623d0c5c0e75843fe24839028ed15f96 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 21:54:47 +0100
Subject: [PATCH 194/270] AGENTS.md: the feature-request loop

When an agent is asked for a feature it runs the whole loop itself: check open
PRs for the area first, work in a new worktree on the latest upstream main,
build and run pr_ready, then push to the fork and open the pull request
against upstream, never the fork.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 AGENTS.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2d883b33b..ed76c08dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,10 @@ Feature → files → harness for the most-changed areas: [docs/architecture.md]
   change), none for a fix. Agents never add `release-now`: the maintainer decides it. Merges ship in batches of 5, or after
   6 hours ([docs/release-flow.md](docs/release-flow.md)).
 - Contributors first: `gh pr list --state open --search <area>` before you start; never duplicate theirs.
+- Asked for a feature? Run the whole loop: check open PRs for the area (above), work in a new worktree,
+  `git fetch` the upstream remote (`ludovic111/horizon`) and start from its latest `main`, build, run
+  `tools/pr_ready.py`, then push to your fork and open the pull request against upstream's `main` —
+  never against the fork itself.
 
 ## Crates
 

From 820cc211d32d6bf0c7fa677a9c99a60f4cfc0aa8 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 21:55:02 +0100
Subject: [PATCH 195/270] Player heads render their owner's skin

Placed player_head blocks kept no profile: skulls had no block entity, so the
renderer fell back to a hardcoded steve for every head. Give skulls a real
BlockEntity carrying vanilla's SkullBlockEntity fields (profile,
note_block_sound, custom_name) so the placement pipeline lands
minecraft:profile in it the way block_entity_item already maps, encode and
decode it through save so regions keep it, send its update tag to remote
clients, and resolve the profile through the skin downloader the head items
and the tab list share: the downloaded skin slot once it lands, the
profile's DefaultPlayerSkin uuid pick while it fetches, SKIN_BY_TYPE steve
without a profile.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../probe/block_entity_render_fixture.rs      |  1 +
 .../horizon-client/src/block_entity_render.rs | 16 +++-
 crates/horizon-client/src/containers.rs       | 24 +++++-
 crates/horizon-client/src/game.rs             |  7 +-
 .../src/game/block_entity_anims.rs            | 32 ++++++++
 crates/horizon-client/src/game/minecarts.rs   |  1 +
 crates/horizon-client/src/lan/chunks.rs       | 14 ++++
 crates/horizon-client/src/save.rs             | 68 +++++++++++++++-
 crates/horizon-client/src/skins.rs            | 77 +++++++++++++++++++
 9 files changed, 233 insertions(+), 7 deletions(-)

diff --git a/crates/horizon-client/examples/probe/block_entity_render_fixture.rs b/crates/horizon-client/examples/probe/block_entity_render_fixture.rs
index a0e3471bc..1db978b77 100644
--- a/crates/horizon-client/examples/probe/block_entity_render_fixture.rs
+++ b/crates/horizon-client/examples/probe/block_entity_render_fixture.rs
@@ -367,6 +367,7 @@ pub fn main() -> Result<()> {
             lid: &|_| open,
             sign: &|_| sign.as_ref(),
             banner: &|_| layers.clone(),
+            skull: &|_| None,
             glyph: &|c| atlas.glyph_cell(c),
         };
         let mut verts = Vec::new();
diff --git a/crates/horizon-client/src/block_entity_render.rs b/crates/horizon-client/src/block_entity_render.rs
index af4168307..a863d6214 100644
--- a/crates/horizon-client/src/block_entity_render.rs
+++ b/crates/horizon-client/src/block_entity_render.rs
@@ -730,6 +730,10 @@ pub struct Scene<'a> {
     pub sign: &'a dyn Fn([i32; 3]) -> Option<&'a crate::signs::SignData>,
     /// Banner layers at a position: pattern texture and RGB tint, bottom first.
     pub banner: &'a dyn Fn([i32; 3]) -> Vec<(String, u32)>,
+    /// The skin sprite a `player_head` shows at a position (`SkullBlockRenderer`
+    /// profile → skin): a downloaded `skins/<sha1>` slot or the profile's
+    /// `DefaultPlayerSkin` fallback; None keeps `SKIN_BY_TYPE` (steve).
+    pub skull: &'a dyn Fn([i32; 3]) -> Option<String>,
     /// Font glyph cell (none for blank glyphs such as the space) and advance.
     pub glyph: &'a dyn Fn(char) -> (Option<Rect>, f32),
 }
@@ -1277,7 +1281,16 @@ impl BlockEntityRenderer {
                     SkullType::Creeper => ("creeper_head", "entity/creeper/creeper"),
                     SkullType::Dragon => ("dragon_skull", "entity/enderdragon/dragon"),
                     SkullType::Piglin => ("piglin_head", "entity/piglin/piglin"),
-                    SkullType::Player => ("player_head", "entity/player/slim/steve"),
+                    SkullType::Player => ("player_head", "entity/player/wide/steve"),
+                };
+                // SkullBlockRenderer.getRenderType: the profile's skin when it
+                // resolves, `SKIN_BY_TYPE` (steve) otherwise.
+                let skin;
+                let texture = if *kind == SkullType::Player {
+                    skin = (scene.skull)(pos);
+                    skin.as_deref().unwrap_or(texture)
+                } else {
+                    texture
                 };
                 let (Some(model), Some(paint)) =
                     (self.models.get(model), paint(texture, 0xFFFFFF, packed))
@@ -1886,6 +1899,7 @@ mod tests {
             lid: &|_| 0.0,
             sign: &|_| None,
             banner: &|_| Vec::new(),
+            skull: &|_| None,
             glyph: &|_| (None, 0.0),
         };
         // Compare the cached world path with the original model renderer,
diff --git a/crates/horizon-client/src/containers.rs b/crates/horizon-client/src/containers.rs
index de2e1b2e9..7c9da6862 100644
--- a/crates/horizon-client/src/containers.rs
+++ b/crates/horizon-client/src/containers.rs
@@ -79,6 +79,17 @@ pub enum BlockEntity {
     Beehive(Box<crate::beehive::Beehive>),
     /// `CommandBlockEntity` of the three command blocks (`crate::command_block`).
     CommandBlock(Box<crate::command_block::CommandBlock>),
+    /// `SkullBlockEntity` of every skull and head block.
+    Skull(Skull),
+}
+/// `SkullBlockEntity`: the player profile the head shows (kept as loaded —
+/// `SkullOwner` is a compound, or a string when it names a player only),
+/// the note block sound and `custom_name`.
+#[derive(Clone, Debug, Default)]
+pub struct Skull {
+    pub profile: Option<horizon_world::nbt::Tag>,
+    pub note_block_sound: Option<String>,
+    pub custom_name: Option<horizon_world::nbt::Tag>,
 }
 /// `CrafterBlockEntity`: nine slots that can be disabled, the powered flag
 /// and the ticks left in the crafting animation.
@@ -233,6 +244,9 @@ impl BlockEntity {
         if name.ends_with("_banner") {
             return Some(Self::Banner(Banner::default()));
         }
+        if name.ends_with("_head") || name.ends_with("_skull") {
+            return Some(Self::Skull(Skull::default()));
+        }
         if name == "minecraft:beacon" {
             return Some(Self::Beacon(Box::new(Beacon {
                 last_check_y: i32::MIN / 2,
@@ -278,6 +292,7 @@ impl BlockEntity {
             Self::Vault(_) => "minecraft:vault",
             Self::Beehive(_) => "minecraft:beehive",
             Self::CommandBlock(_) => "minecraft:command_block",
+            Self::Skull(_) => "minecraft:skull",
         }
     }
     pub fn contents(&self) -> Vec<ItemStack> {
@@ -293,7 +308,8 @@ impl BlockEntity {
             | Self::TrialSpawner(_)
             | Self::Vault(_)
             | Self::Beehive(_)
-            | Self::CommandBlock(_) => Vec::new(),
+            | Self::CommandBlock(_)
+            | Self::Skull(_) => Vec::new(),
             Self::Lectern(l) => l.book.iter().cloned().collect(),
             Self::Sculk(_) => Vec::new(),
             Self::Banner(_) => Vec::new(),
@@ -310,7 +326,8 @@ impl BlockEntity {
             | Self::Beacon(_)
             | Self::Lectern(_)
             | Self::Sculk(_)
-            | Self::Banner(_) => &[],
+            | Self::Banner(_)
+            | Self::Skull(_) => &[],
             Self::Crafter(c) => &c.items,
             Self::CreakingHeart(_)
             | Self::Spawner(_)
@@ -330,7 +347,8 @@ impl BlockEntity {
             | Self::Beacon(_)
             | Self::Lectern(_)
             | Self::Sculk(_)
-            | Self::Banner(_) => &mut [],
+            | Self::Banner(_)
+            | Self::Skull(_) => &mut [],
             Self::Crafter(c) => &mut c.items,
             Self::CreakingHeart(_)
             | Self::Spawner(_)
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 52d7ce8dd..bfdebe44a 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -5133,7 +5133,8 @@ impl Game<'_> {
                 | BlockEntity::TrialSpawner(_)
                 | BlockEntity::Vault(_)
                 | BlockEntity::Beehive(_)
-                | BlockEntity::CommandBlock(_),
+                | BlockEntity::CommandBlock(_)
+                | BlockEntity::Skull(_),
             ) => {}
             None => {
                 v.extend((0..self.craft_size * self.craft_size).map(|i| 100 + i));
@@ -5392,7 +5393,8 @@ impl Game<'_> {
                     | BlockEntity::TrialSpawner(_)
                     | BlockEntity::Vault(_)
                     | BlockEntity::Beehive(_)
-                    | BlockEntity::CommandBlock(_),
+                    | BlockEntity::CommandBlock(_)
+                    | BlockEntity::Skull(_),
                 ) => {}
                 None if self.mount_active() => self.draw_mount_background(batch, ox, oy),
                 None => {
@@ -6884,6 +6886,7 @@ impl Game<'_> {
                     _ => None,
                 },
                 banner: &|p| self.banner_layers_at(p),
+                skull: &|p| self.skull_skin_at(p),
                 glyph: &|c| self.gui.atlas.glyph_cell(c),
             };
             // Block entities outside the view frustum are skipped (with a
diff --git a/crates/horizon-client/src/game/block_entity_anims.rs b/crates/horizon-client/src/game/block_entity_anims.rs
index 619fcd009..136738350 100644
--- a/crates/horizon-client/src/game/block_entity_anims.rs
+++ b/crates/horizon-client/src/game/block_entity_anims.rs
@@ -8,8 +8,10 @@ use horizon_client::{
     block_entity_anim::{BellEntity, EndGateway, Shulker, ShulkerStatus, Ticker},
     block_entity_render::BlockAnim,
     collisions::{SceneCollisions, no_collision_empty},
+    containers::BlockEntity,
     particles::{ParticleOptions, ParticleType},
     save::number,
+    skins,
 };
 use horizon_core::geometry::{Aabb, Vec3};
 use horizon_world::nbt::Tag;
@@ -392,4 +394,34 @@ impl Game<'_> {
     pub(super) fn chest_lid(&self, pos: [i32; 3], partial: f32) -> f32 {
         self.be_anims.lid(pos, partial)
     }
+    /// `SkullBlockRenderer.getPlayerSkin`: the skin sprite of the `profile` of
+    /// the player head at `pos`. The skin download is started here; while it
+    /// is in flight (or when it cannot be got) the profile's uuid picks the
+    /// `DefaultPlayerSkin` for it, and a profile with no id keeps steve. A
+    /// head with no profile answers None so `SKIN_BY_TYPE` applies.
+    pub(super) fn skull_skin_at(&self, pos: [i32; 3]) -> Option<String> {
+        let key = (pos[0], pos[1], pos[2]);
+        let profile = match self.world.block_entities.get(&key) {
+            Some(BlockEntity::Skull(s)) => s.profile.clone(),
+            _ => None,
+        }
+        .or_else(|| self.saved_tag(pos).and_then(|t| t.get("profile").cloned()));
+        let profile = profile?;
+        if let Some(url) = skins::profile_skin_url_nbt(&profile)
+            && let Some(location) =
+                skins::texture_hash(&url).map(|hash| skins::skin_location(&hash))
+        {
+            self.skin_downloads
+                .borrow_mut()
+                .state(skins::Kind::Skin, &url);
+            if self.gui.atlas.sprites.contains_key(&location) {
+                return Some(location);
+            }
+        }
+        Some(
+            skins::profile_uuid_nbt(&profile)
+                .map(|uuid| horizon_client::tab_list::default_skin(uuid).to_owned())
+                .unwrap_or_else(|| "entity/player/wide/steve".to_owned()),
+        )
+    }
 }
diff --git a/crates/horizon-client/src/game/minecarts.rs b/crates/horizon-client/src/game/minecarts.rs
index 6b8b51dde..8d4920b48 100644
--- a/crates/horizon-client/src/game/minecarts.rs
+++ b/crates/horizon-client/src/game/minecarts.rs
@@ -1463,6 +1463,7 @@ impl Game<'_> {
             lid: &lid,
             sign: &|_| None,
             banner: &|_| Vec::new(),
+            skull: &|_| None,
             glyph: &|c| self.gui.atlas.glyph_cell(c),
         };
         self.res
diff --git a/crates/horizon-client/src/lan/chunks.rs b/crates/horizon-client/src/lan/chunks.rs
index 65b092881..d7dcc6cd8 100644
--- a/crates/horizon-client/src/lan/chunks.rs
+++ b/crates/horizon-client/src/lan/chunks.rs
@@ -937,6 +937,20 @@ pub fn entity_tag(entity: &BlockEntity) -> Option<Tag> {
     match entity {
         BlockEntity::Sign(sign) => Some(Tag::compound(sign.encode())),
         BlockEntity::Spawner(s) => Some(s.update_tag()),
+        // SkullBlockEntity: the profile is the whole reason a head differs.
+        BlockEntity::Skull(s) => {
+            let mut entries = Vec::new();
+            if let Some(profile) = &s.profile {
+                entries.push(("profile", profile.clone()));
+            }
+            if let Some(sound) = &s.note_block_sound {
+                entries.push(("note_block_sound", Tag::String(sound.as_str().into())));
+            }
+            if let Some(name) = &s.custom_name {
+                entries.push(("custom_name", name.clone()));
+            }
+            Some(Tag::compound(entries))
+        }
         BlockEntity::Jukebox(_) | BlockEntity::Lectern(_) => None,
         _ => None,
     }
diff --git a/crates/horizon-client/src/save.rs b/crates/horizon-client/src/save.rs
index da5735c17..c59c3c974 100644
--- a/crates/horizon-client/src/save.rs
+++ b/crates/horizon-client/src/save.rs
@@ -548,6 +548,17 @@ pub fn encode_block_entity(
                 entries.push(("creaking", uuid_tag(uuid)));
             }
         }
+        BlockEntity::Skull(s) => {
+            if let Some(profile) = &s.profile {
+                entries.push(("profile", profile.clone()));
+            }
+            if let Some(sound) = &s.note_block_sound {
+                entries.push(("note_block_sound", string(sound)));
+            }
+            if let Some(name) = &s.custom_name {
+                entries.push(("custom_name", name.clone()));
+            }
+        }
         BlockEntity::Spawner(s) => entries.extend(s.save()),
         BlockEntity::TrialSpawner(s) => entries.extend(s.save()),
         BlockEntity::Vault(v) => entries.extend(v.save()),
@@ -622,6 +633,19 @@ pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::contain
         };
         return Some((pos, BlockEntity::Beacon(Box::new(beacon))));
     }
+    // A skull's block entity id is not its block's name (every head block).
+    if id == "minecraft:skull" {
+        return Some((
+            pos,
+            BlockEntity::Skull(crate::containers::Skull {
+                profile: tag.get("profile").cloned(),
+                note_block_sound: text(tag.get("note_block_sound")),
+                custom_name: tag
+                    .get("custom_name")
+                    .and_then(crate::block_entity_nbt::component),
+            }),
+        ));
+    }
     // A spawner's block entity id is not its block's name.
     let block = match id.as_str() {
         "minecraft:mob_spawner" => "minecraft:spawner",
@@ -683,7 +707,8 @@ pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::contain
         | BlockEntity::Beacon(_)
         | BlockEntity::Lectern(_)
         | BlockEntity::Banner(_)
-        | BlockEntity::CreakingHeart(_) => {}
+        | BlockEntity::CreakingHeart(_)
+        | BlockEntity::Skull(_) => {}
         BlockEntity::Spawner(s) => **s = crate::mobs::spawner::Spawner::load(tag),
         BlockEntity::TrialSpawner(s) => **s = crate::mobs::trial_spawner::TrialSpawner::load(tag),
         BlockEntity::Vault(v) => **v = crate::vault::Vault::load(tag),
@@ -3876,6 +3901,47 @@ mod tests {
     }
     use super::*;
 
+    #[test]
+    fn skull_block_entity_keeps_its_profile() {
+        // A placed `player_head` as vanilla saves it: the owning player's
+        // `profile` survives load, encode and `canonical`.
+        let saved = horizon_world::nbt::parse_snbt(
+            r#"{id:"minecraft:skull",x:10,y:64,z:20,profile:{name:"Steve",id:[I;1,2,3,4],properties:[{name:"textures",value:"abc"}]},note_block_sound:"minecraft:entity.player.hurt",custom_name:"Trophy"}"#,
+        )
+        .unwrap()
+        .0;
+        let (pos, back) = decode_block_entity(&saved).expect("skull");
+        assert_eq!(pos, (10, 64, 20));
+        let crate::containers::BlockEntity::Skull(skull) = &back else {
+            panic!("not a skull");
+        };
+        assert_eq!(skull.profile, saved.get("profile").cloned());
+        assert_eq!(
+            skull.note_block_sound.as_deref(),
+            Some("minecraft:entity.player.hurt")
+        );
+        assert_eq!(back.id(), "minecraft:skull");
+        let tag = encode_block_entity(pos, &back, "minecraft:player_head");
+        assert_eq!(
+            crate::block_entity_nbt::id(&tag).as_deref(),
+            Some("minecraft:skull")
+        );
+        assert_eq!(tag.get("profile"), saved.get("profile"));
+        let (_, again) = decode_block_entity(&tag).expect("skull again");
+        let crate::containers::BlockEntity::Skull(again) = again else {
+            panic!("not a skull");
+        };
+        assert_eq!(again.profile, skull.profile);
+        // A profile-less head (skeleton, creeper) round-trips too.
+        let plain = encode_block_entity(
+            pos,
+            &crate::containers::BlockEntity::Skull(crate::containers::Skull::default()),
+            "minecraft:creeper_head",
+        );
+        let (_, decoded) = decode_block_entity(&plain).expect("plain skull");
+        assert!(matches!(decoded, crate::containers::BlockEntity::Skull(_)));
+    }
+
     #[test]
     fn uuid_text_round_trips() {
         let u = [-158327916, 1572358581, -2125825222, -487948715];
diff --git a/crates/horizon-client/src/skins.rs b/crates/horizon-client/src/skins.rs
index 9014032c4..ee6851e00 100644
--- a/crates/horizon-client/src/skins.rs
+++ b/crates/horizon-client/src/skins.rs
@@ -130,6 +130,47 @@ pub fn profile_skin_url(profile: &serde_json::Value) -> Option<String> {
     unpack(value, Signature::Unsigned, &TEXTURE_URIS).skin
 }
 
+/// `profile_skin_url` on a block entity's `profile` NBT (`SkullBlockEntity`):
+/// the same `properties` list, held as a compound. A name-only profile (a
+/// string tag) has no properties and no skin URL.
+pub fn profile_skin_url_nbt(profile: &horizon_world::nbt::Tag) -> Option<String> {
+    let properties = match profile.get("properties")? {
+        horizon_world::nbt::Tag::List(list) => list,
+        _ => return None,
+    };
+    let value = properties.iter().find_map(|p| {
+        let name = nbt_text(p.get("name"))?;
+        (name == "textures")
+            .then(|| nbt_text(p.get("value")))
+            .flatten()
+    })?;
+    unpack(&value, Signature::Unsigned, &TEXTURE_URIS).skin
+}
+
+/// The profile's uuid as u128: `id` as an int array (block entity NBT) or a
+/// uuid string (older and component forms). Used for `DefaultPlayerSkin.get`
+/// when a head's skin is not downloaded yet.
+pub fn profile_uuid_nbt(profile: &horizon_world::nbt::Tag) -> Option<u128> {
+    match profile.get("id")? {
+        horizon_world::nbt::Tag::IntArray(v) if v.len() == 4 => Some(
+            v.iter()
+                .fold(0u128, |a, &w| (a << 32) | u128::from(w as u32)),
+        ),
+        horizon_world::nbt::Tag::String(s) => {
+            let digits: String = s.to_string_lossy().chars().filter(|c| *c != '-').collect();
+            u128::from_str_radix(&digits, 16).ok()
+        }
+        _ => None,
+    }
+}
+
+fn nbt_text(tag: Option<&horizon_world::nbt::Tag>) -> Option<String> {
+    match tag {
+        Some(horizon_world::nbt::Tag::String(s)) => Some(s.to_string_lossy()),
+        _ => None,
+    }
+}
+
 /// `MinecraftProfileTexture.getHash`: the base name of the URL's path.
 pub fn texture_hash(url: &str) -> Option<String> {
     let rest = url.split_once("://")?.1;
@@ -457,6 +498,42 @@ mod tests {
 
     use super::*;
 
+    #[test]
+    fn skull_block_entity_profiles_supply_head_skins() {
+        let value = "eyJ0ZXh0dXJlcyI6IHsiU0tJTiI6IHsidXJsIjogImh0dHBzOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlL2FiYzEyMyJ9fX0=";
+        let profile = horizon_world::nbt::parse_snbt(&format!(
+            r#"{{name:"T",id:[I;-158327916,1572358581,-2125825222,-487948715],properties:[{{name:"textures",value:"{value}"}}]}}"#
+        ))
+        .unwrap()
+        .0;
+        assert_eq!(
+            super::profile_skin_url_nbt(&profile).as_deref(),
+            Some("https://textures.minecraft.net/texture/abc123")
+        );
+        assert_eq!(
+            super::profile_uuid_nbt(&profile),
+            Some(
+                [-158327916, 1572358581, -2125825222, -487948715]
+                    .iter()
+                    .fold(0u128, |a, &w: &i32| (a << 32) | u128::from(w as u32))
+            )
+        );
+        // A name-only profile (a string tag) has no properties: no url, no id.
+        let named = horizon_world::nbt::Tag::String("MHF_Blaze".into());
+        assert_eq!(super::profile_skin_url_nbt(&named), None);
+        assert_eq!(super::profile_uuid_nbt(&named), None);
+        // A uuid in string form decodes too.
+        let text_id = horizon_world::nbt::parse_snbt(
+            r#"{name:"T",id:"e843a1f4-0000-0001-0000-000200000003"}"#,
+        )
+        .unwrap()
+        .0;
+        assert_eq!(
+            super::profile_uuid_nbt(&text_id),
+            Some(u128::from_str_radix("e843a1f4000000010000000200000003", 16).unwrap())
+        );
+    }
+
     #[test]
     fn sha1_and_base64() {
         let hex: String = sha1(b"abc").iter().map(|b| format!("{b:02x}")).collect();

From 4a2b262343581332c58998410c8884c9d82c6558 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:00:07 +0100
Subject: [PATCH 196/270] Structure starts: decide chunks no ring search can
 reach without the rings

The 128 stronghold biome searches (two seconds of CPU on a 4-thread laptop)
ran when the first chunk of a new world looked up its structure starts, so
nothing near spawn was generated until they were done. Each search ends
within 8 chunks of its ring chunk, which is known before searching, and
strongholds lie 1,400 blocks out or more: a chunk with no ring search in
reach (exclusion zones included) is now decided without them, which is what
they would say. They run when a chunk near a ring, /locate or an eye of
ender needs them (ring_positions now searches on demand instead of returning
nothing before a lookup did).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/vanillagen.rs       |  7 +-
 .../horizon-world/src/worldgen/generator.rs   | 59 +++++++++++--
 .../src/worldgen/generator_structures.rs      | 85 ++++++++++++++++---
 .../src/worldgen/structure/start.rs           | 12 +++
 .../src/worldgen/structure/stronghold.rs      | 15 +++-
 5 files changed, 154 insertions(+), 24 deletions(-)

diff --git a/crates/horizon-client/src/vanillagen.rs b/crates/horizon-client/src/vanillagen.rs
index c44e1f542..a17bb22d3 100644
--- a/crates/horizon-client/src/vanillagen.rs
+++ b/crates/horizon-client/src/vanillagen.rs
@@ -272,9 +272,12 @@ impl VanillaTerrain {
     pub fn origin(&self) -> crate::Result<ChunkPos> {
         Ok(self.generator.origin()?)
     }
-    /// Concentric ring positions of a structure set (strongholds), once known.
+    /// Concentric ring positions of a structure set (strongholds), searched
+    /// for now if no chunk needed them yet.
     pub fn ring_positions(&self, set: &str) -> Option<Vec<ChunkPos>> {
-        self.generator.ring_positions(set)
+        let mut worker = self.query.lock().unwrap_or_else(|e| e.into_inner());
+        let worker = worker.get_or_insert_with(|| self.generator.worker());
+        worker.ring_positions(set)
     }
 }
 /// The worldgen bundle at `dir`, loaded once and shared by every generator
diff --git a/crates/horizon-world/src/worldgen/generator.rs b/crates/horizon-world/src/worldgen/generator.rs
index 2595173ad..b2daae61c 100644
--- a/crates/horizon-world/src/worldgen/generator.rs
+++ b/crates/horizon-world/src/worldgen/generator.rs
@@ -1652,7 +1652,7 @@ trait SeededPipeline: Send + Sync {
     ) -> Vec<Arc<super::structure::start::StructureStart>>;
     fn unsupported_features(&self) -> Vec<(String, String)>;
     fn forget_structure_starts(&self);
-    fn ring_positions(&self, set: &str) -> Option<Vec<ChunkPos>>;
+    fn ring_positions(&self, worker: &mut WorkerState, set: &str) -> Option<Vec<ChunkPos>>;
     fn spawn_position(&self) -> Result<[i32; 2], GeneratorError>;
     fn locate(
         &self,
@@ -1752,8 +1752,15 @@ where
             structures.forget_starts();
         }
     }
-    fn ring_positions(&self, set: &str) -> Option<Vec<ChunkPos>> {
-        self.structures.as_ref()?.cached_rings(set)
+    fn ring_positions(&self, worker: &mut WorkerState, set: &str) -> Option<Vec<ChunkPos>> {
+        self.structures.as_ref()?.ring_positions(
+            &mut StructureQueries {
+                pipeline: self,
+                worker,
+                valid: BTreeSet::new(),
+            },
+            set,
+        )
     }
     fn spawn_position(&self) -> Result<[i32; 2], GeneratorError> {
         if let Some(position) = self.spawn_position.get() {
@@ -2375,11 +2382,6 @@ impl OverworldGenerator {
     pub fn unsupported_features(&self) -> Vec<(String, String)> {
         self.pipeline.unsupported_features()
     }
-    /// ConcentricRingsStructurePlacement chunks of a structure set (such as
-    /// `minecraft:strongholds`), available once structure starts were looked up.
-    pub fn ring_positions(&self, set: &str) -> Option<Vec<ChunkPos>> {
-        self.pipeline.ring_positions(set)
-    }
     /// NoiseBasedChunkGenerator.getOrigin: the chunk a new world's spawn
     /// search starts from (NoiseSpawnFinder over the `spawn_target` points).
     pub fn origin(&self) -> Result<ChunkPos, GeneratorError> {
@@ -2487,6 +2489,11 @@ impl GeneratorWorker {
     pub fn jigsaw_pieces(&mut self, query: &JigsawQuery<'_>) -> Option<JigsawPieces> {
         self.pipeline.jigsaw_pieces(&mut self.state, query)
     }
+    /// ConcentricRingsStructurePlacement chunks of a structure set (such as
+    /// `minecraft:strongholds`), searched for now if nothing needed them yet.
+    pub fn ring_positions(&mut self, set: &str) -> Option<Vec<ChunkPos>> {
+        self.pipeline.ring_positions(&mut self.state, set)
+    }
     /// STRUCTURE_STARTS: the structure starts owned by a chunk (cached).
     pub fn structure_starts(
         &mut self,
@@ -2887,8 +2894,8 @@ mod tests {
             return;
         };
         let generator = OverworldGenerator::new(data, 1234).expect("generator");
-        generator.worker().structure_starts(ChunkPos::new(0, 0));
         let rings = generator
+            .worker()
             .ring_positions("minecraft:strongholds")
             .expect("ring positions");
         assert_eq!(rings.len(), 128);
@@ -2902,6 +2909,40 @@ mod tests {
         }
     }
 
+    /// Chunks no ring search can end near are decided without the rings,
+    /// which stay unsearched, and get the starts they get with them.
+    #[test]
+    fn chunks_far_from_the_rings_do_not_search_them() {
+        let Some(data) = prepared_data() else {
+            return;
+        };
+        let generator = OverworldGenerator::new(data.clone(), 4321).expect("generator");
+        let mut worker = generator.worker();
+        let summary = |worker: &mut GeneratorWorker, c: ChunkPos| -> Vec<(String, i32, i32)> {
+            worker
+                .structure_starts(c)
+                .iter()
+                .map(|s| (s.name.clone(), s.chunk.x, s.chunk.z))
+                .collect()
+        };
+        let chunks: Vec<ChunkPos> = (-24..=24)
+            .step_by(3)
+            .flat_map(|x| (-24..=24).step_by(3).map(move |z| ChunkPos::new(x, z)))
+            .collect();
+        let before: Vec<_> = chunks.iter().map(|&c| summary(&mut worker, c)).collect();
+        assert!(before.iter().any(|s| !s.is_empty()), "no starts to compare");
+        let searched = || data.ring_cache.lock().unwrap()[0].1.get().is_some();
+        assert!(!searched());
+        let rings = worker
+            .ring_positions("minecraft:strongholds")
+            .expect("ring positions");
+        assert_eq!(rings.len(), 128);
+        assert!(searched());
+        worker.forget_structure_starts();
+        let after: Vec<_> = chunks.iter().map(|&c| summary(&mut worker, c)).collect();
+        assert_eq!(before, after);
+    }
+
     /// Generators of one seed and dimension share their ring positions;
     /// another seed or generator gets its own, and old entries go.
     #[test]
diff --git a/crates/horizon-world/src/worldgen/generator_structures.rs b/crates/horizon-world/src/worldgen/generator_structures.rs
index 1e4913c95..8f8817f11 100644
--- a/crates/horizon-world/src/worldgen/generator_structures.rs
+++ b/crates/horizon-world/src/worldgen/generator_structures.rs
@@ -37,6 +37,8 @@ pub(super) struct StructureState {
     rings: Arc<OnceLock<Rings>>,
     /// Their biome searches while they are computed.
     ring_work: OnceLock<RingWork>,
+    /// `StructureRegistry::zone_reach`.
+    zone_reach: i32,
 }
 
 /// generateRingPositions' biome searches, shared out. Vanilla runs each as
@@ -209,7 +211,9 @@ impl StructureState {
         {
             bindings = bindings.with_block_properties(&blocks.properties)?;
         }
+        let zone_reach = registry.zone_reach();
         Ok(Some(Self {
+            zone_reach,
             registry,
             resources: resources.clone(),
             bindings,
@@ -221,10 +225,22 @@ impl StructureState {
             ring_work: OnceLock::new(),
         }))
     }
-    /// Concentric ring positions of a structure set, once the first start
-    /// lookup has computed them.
-    pub(super) fn cached_rings(&self, set: &str) -> Option<Vec<ChunkPos>> {
-        self.rings.get().and_then(|rings| rings.get(set).cloned())
+    /// Concentric ring positions of a structure set (vanilla's
+    /// getRingPositionsFor), computed now if no lookup needed them yet.
+    pub(super) fn ring_positions(
+        &self,
+        context: &mut impl StartContext,
+        set: &str,
+    ) -> Option<Vec<ChunkPos>> {
+        self.rings(context).get(set).cloned()
+    }
+    fn ring_work(&self, context: &impl StartContext) -> &RingWork {
+        self.ring_work.get_or_init(|| {
+            RingWork::new(
+                self.registry
+                    .ring_searches(&self.possible_sets, context.seed()),
+            )
+        })
     }
     /// The concentric ring positions, computing them with the threads that
     /// need them first (see `RingWork`).
@@ -232,12 +248,7 @@ impl StructureState {
         if let Some(rings) = self.rings.get() {
             return rings;
         }
-        let work = self.ring_work.get_or_init(|| {
-            RingWork::new(
-                self.registry
-                    .ring_searches(&self.possible_sets, context.seed()),
-            )
-        });
+        let work = self.ring_work(context);
         let registry = &self.registry;
         work.help(|set| registry.ring_biomes(set), &mut |quarts| {
             context.noise_biomes(quarts)
@@ -245,6 +256,24 @@ impl StructureState {
         self.rings
             .get_or_init(|| work.rings(|set| registry.sets[set].name.clone()))
     }
+    /// The rings a chunk's starts are decided with. Before they are known,
+    /// a chunk no ring search can end near (with the exclusion zones' reach)
+    /// is decided without them: no ring chunk is near it, which is what the
+    /// rings would say. Strongholds lie 1,400 blocks out or more, so a new
+    /// world's first chunks don't wait for the 128 biome searches (seconds
+    /// on four threads); they run when a chunk near a ring needs them.
+    fn rings_for(&self, context: &mut impl StartContext, chunk: ChunkPos) -> &Rings {
+        static NONE: Rings = Rings::new();
+        if let Some(rings) = self.rings.get() {
+            return rings;
+        }
+        let near = self
+            .ring_work(context)
+            .searches
+            .iter()
+            .any(|(_, search)| search.may_land_near(chunk.x, chunk.z, self.zone_reach));
+        if near { self.rings(context) } else { &NONE }
+    }
     /// Drop the cached starts, so that later chunks build fresh pieces (the
     /// pieces keep per-start placement state such as a shipwreck's height).
     pub(super) fn forget_starts(&self) {
@@ -263,7 +292,7 @@ impl StructureState {
         }
         // Ring searches enlist other workers and wait for them: never hold a
         // chunk-work lock while helping, even when this chunk has no starts.
-        let rings = self.rings(context);
+        let rings = self.rings_for(context, chunk);
         let work = self.start_work.at((chunk.x, chunk.z));
         let _work = work.lock().unwrap();
         if let Some(found) = self.starts.get((chunk.x, chunk.z)) {
@@ -470,6 +499,40 @@ mod tests {
         assert!(cache.get((3, -4)).is_none());
     }
 
+    /// A ring search ends where `may_land_near` allows: on its ring chunk
+    /// or in the square it samples, never further.
+    #[test]
+    fn ring_searches_end_where_they_may() {
+        let none = BTreeSet::new();
+        for seed in [0, 1234, -77, i64::MAX] {
+            for (b, search) in ring_searches(seed, 32, 3, 128).iter().enumerate() {
+                // Preferred biomes on one quart at a time, in turn at each
+                // corner of the square, else nowhere (the ring chunk).
+                let corner = (b % 5) as i32;
+                let biomes = |quarts: &[[i32; 3]]| -> Vec<BiomeId> {
+                    let (first, last) = (quarts[0], quarts[quarts.len() - 1]);
+                    let pick = match corner {
+                        0 => first,
+                        1 => [last[0], 0, first[2]],
+                        2 => [first[0], 0, last[2]],
+                        3 => last,
+                        _ => [i32::MIN, 0, i32::MIN],
+                    };
+                    quarts
+                        .iter()
+                        .map(|q| BiomeId(u32::from(*q == pick)))
+                        .collect()
+                };
+                let preferred: BTreeSet<BiomeId> = [BiomeId(1)].into();
+                for wanted in [&preferred, &none] {
+                    let found = search.find(wanted, &mut { biomes });
+                    assert!(search.may_land_near(found.x, found.z, 0));
+                    assert!(!search.may_land_near(found.x + 17, found.z, 0));
+                }
+            }
+        }
+    }
+
     /// Searches shared between threads give the positions of one thread
     /// running them in order, set by set.
     #[test]
diff --git a/crates/horizon-world/src/worldgen/structure/start.rs b/crates/horizon-world/src/worldgen/structure/start.rs
index 44f4b70f4..7919751aa 100644
--- a/crates/horizon-world/src/worldgen/structure/start.rs
+++ b/crates/horizon-world/src/worldgen/structure/start.rs
@@ -511,6 +511,18 @@ impl StructureRegistry {
             })
             .collect()
     }
+    /// How far from a chunk, in chunks, deciding its starts can look at
+    /// other sets' start chunks through exclusion zones: every set's zones
+    /// summed, a bound on any chain of them.
+    pub fn zone_reach(&self) -> i32 {
+        self.sets
+            .iter()
+            .map(|s| {
+                s.exclusion.as_ref().map_or(0, |e| e.1.max(0))
+                    + s.avoid.as_ref().map_or(0, |a| a.chunk_count.max(0))
+            })
+            .sum()
+    }
     /// The preferred biomes of a concentric-ring set (empty for others).
     pub fn ring_biomes(&self, set: usize) -> &BTreeSet<BiomeId> {
         static NONE: BTreeSet<BiomeId> = BTreeSet::new();
diff --git a/crates/horizon-world/src/worldgen/structure/stronghold.rs b/crates/horizon-world/src/worldgen/structure/stronghold.rs
index e1a10808f..94042ba6f 100644
--- a/crates/horizon-world/src/worldgen/structure/stronghold.rs
+++ b/crates/horizon-world/src/worldgen/structure/stronghold.rs
@@ -29,6 +29,9 @@ pub fn ring_positions(
         .collect()
 }
 
+/// findBiomeHorizontal's radius, 112 blocks, in quarts.
+const SEARCH_QUARTS: i32 = 28;
+
 /// One ring position before its biome search: the chunk on the ring and the
 /// random its search uses. Vanilla runs each search as its own task.
 #[derive(Clone, Debug)]
@@ -38,6 +41,13 @@ pub struct RingSearch {
     random: LegacyRandom,
 }
 impl RingSearch {
+    /// Whether the search can end within `margin` chunks of chunk (`x`,
+    /// `z`): it ends on its ring chunk or in the square it samples, at most
+    /// 120 blocks from the ring chunk's corner (8 chunks, rounded up).
+    pub fn may_land_near(&self, x: i32, z: i32, margin: i32) -> bool {
+        let reach = (SEARCH_QUARTS * 4 + 8 + 15) / 16 + margin;
+        (self.x - x).abs() <= reach && (self.z - z).abs() <= reach
+    }
     /// BiomeSource.findBiomeHorizontal around the ring chunk's centre: a
     /// random preferred biome within 112 blocks, else the ring chunk itself.
     ///
@@ -53,8 +63,9 @@ impl RingSearch {
     ) -> ChunkPos {
         let mut search = self.random.clone();
         let (cx, cz) = ((self.x * 16 + 8) >> 2, (self.z * 16 + 8) >> 2);
-        let quarts: Vec<[i32; 3]> = (-28..=28)
-            .flat_map(|dz| (-28..=28).map(move |dx| [cx + dx, 0, cz + dz]))
+        let r = SEARCH_QUARTS;
+        let quarts: Vec<[i32; 3]> = (-r..=r)
+            .flat_map(|dz| (-r..=r).map(move |dx| [cx + dx, 0, cz + dz]))
             .collect();
         let mut found = 0;
         let mut result = None;

From 2fb0ac186a65b1171d0893c409e040dd094a95b6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:04:13 +0100
Subject: [PATCH 197/270] Behaviour cache: hash the source files once per
 process

The snapshot's key hashes the 70 MB of source tables it was resolved from.
The client's tables and the world generator's are loaded from the same
folder, so a world opening hashed them a second time: a third of a second
of the server thread's start on a 4-thread laptop, before any chunk. The
hash is now kept for the process, by each file's length and modification
time; a changed file is read again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-world/src/level/data/cache.rs | 96 ++++++++++++++++----
 1 file changed, 78 insertions(+), 18 deletions(-)

diff --git a/crates/horizon-world/src/level/data/cache.rs b/crates/horizon-world/src/level/data/cache.rs
index 59bc1f8d8..54682ab8c 100644
--- a/crates/horizon-world/src/level/data/cache.rs
+++ b/crates/horizon-world/src/level/data/cache.rs
@@ -13,10 +13,10 @@ use std::{
     io::Write,
     path::PathBuf,
     sync::{
-        OnceLock,
+        Mutex, OnceLock,
         atomic::{AtomicU64, Ordering},
     },
-    time::UNIX_EPOCH,
+    time::{SystemTime, UNIX_EPOCH},
 };
 
 const MAGIC: &[u8; 8] = b"HZBEHAV\0";
@@ -149,22 +149,7 @@ fn fingerprint(registry: &BlockRegistry, root: &Path) -> io::Result<[u8; 32]> {
         .duration_since(UNIX_EPOCH)
         .map_err(|e| invalid(e.to_string()))?;
     hasher.update(modified.as_nanos().to_le_bytes());
-    for relative in [
-        "facts.json",
-        "block-behaviours.json",
-        "gameplay-facts.json",
-        "block-tags.json",
-        "cached-collision.nbt",
-    ] {
-        hash_file(&mut hasher, root, &root.join(relative))?;
-    }
-    let mut fluids: Vec<PathBuf> = fs::read_dir(root.join("data/minecraft/tags/fluid"))?
-        .map(|entry| entry.map(|entry| entry.path()))
-        .collect::<io::Result<_>>()?;
-    fluids.sort();
-    for path in fluids {
-        hash_file(&mut hasher, root, &path)?;
-    }
+    hasher.update(sources_digest(root)?);
     // The registry argument may be modified independently of facts.json.
     hasher.update((registry.len() as u64).to_le_bytes());
     let mut seen = std::collections::HashSet::new();
@@ -190,6 +175,55 @@ fn fingerprint(registry: &BlockRegistry, root: &Path) -> io::Result<[u8; 32]> {
     Ok(hasher.finalize().into())
 }
 
+/// The source files the snapshot is resolved from, as their lengths and
+/// modification times, and the hash of their contents.
+type Sources = (Vec<(PathBuf, u64, Option<SystemTime>)>, [u8; 32]);
+/// Source hashes already computed by this process: the client's tables and
+/// the world generator's are loaded from the same folder, and hashing its
+/// 70 MB again took a third of a second on a 4-thread laptop. A file whose
+/// length or modification time changed is read again.
+static SOURCES: Mutex<Vec<Sources>> = Mutex::new(Vec::new());
+
+fn sources_digest(root: &Path) -> io::Result<[u8; 32]> {
+    let mut paths: Vec<PathBuf> = [
+        "facts.json",
+        "block-behaviours.json",
+        "gameplay-facts.json",
+        "block-tags.json",
+        "cached-collision.nbt",
+    ]
+    .iter()
+    .map(|relative| root.join(relative))
+    .collect();
+    let mut fluids: Vec<PathBuf> = fs::read_dir(root.join("data/minecraft/tags/fluid"))?
+        .map(|entry| entry.map(|entry| entry.path()))
+        .collect::<io::Result<_>>()?;
+    fluids.sort();
+    paths.extend(fluids);
+    let stamps = paths
+        .iter()
+        .map(|path| {
+            let meta = fs::metadata(path)?;
+            Ok((path.clone(), meta.len(), meta.modified().ok()))
+        })
+        .collect::<io::Result<Vec<_>>>()?;
+    let known = SOURCES.lock().unwrap_or_else(|e| e.into_inner());
+    if let Some((_, digest)) = known.iter().find(|(s, _)| *s == stamps) {
+        return Ok(*digest);
+    }
+    drop(known);
+    let mut hasher = Sha256::new();
+    for path in &paths {
+        hash_file(&mut hasher, root, path)?;
+    }
+    let digest: [u8; 32] = hasher.finalize().into();
+    SOURCES
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .push((stamps, digest));
+    Ok(digest)
+}
+
 fn hash_str(hasher: &mut Sha256, text: &str) {
     hasher.update((text.len() as u64).to_le_bytes());
     hasher.update(text.as_bytes());
@@ -806,6 +840,32 @@ mod tests {
         );
     }
 
+    /// A folder's sources are hashed once while they stay as they are; a
+    /// file rewritten at the same length is hashed again.
+    #[test]
+    fn sources_are_hashed_once_until_a_file_changes() {
+        let Some(root) = fixture() else {
+            return;
+        };
+        let entries = || {
+            SOURCES
+                .lock()
+                .unwrap()
+                .iter()
+                .filter(|(stamps, _)| stamps[0].0.starts_with(&root.0))
+                .count()
+        };
+        let first = sources_digest(&root.0).unwrap();
+        assert_eq!(sources_digest(&root.0).unwrap(), first);
+        assert_eq!(entries(), 1);
+        let tags = root.0.join("block-tags.json");
+        let mut bytes = fs::read(&tags).unwrap();
+        bytes[0] ^= 1;
+        fs::write(&tags, bytes).unwrap();
+        assert_ne!(sources_digest(&root.0).unwrap(), first);
+        assert_eq!(entries(), 2);
+    }
+
     #[test]
     fn cache_invalidates_sources_and_recovers_from_corruption() {
         let Some(root) = fixture() else {

From 40b3c1e3d68bf0c96d9eeb5b7c75cd207d0cf51d Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:08:55 +0000
Subject: [PATCH 198/270] Preserve requested GUI scale across temporary small
 surfaces

Keep framebuffer limits in rendering and explicit option cycling rather than overwriting the saved choice during startup or settings application.

Co-Authored-By: Codex gpt-6.1-sol <noreply@openai.com>
---
 crates/horizon-client/src/game.rs             | 10 ------
 .../horizon-client/src/game/startup_menu.rs   |  2 --
 crates/horizon-client/src/options_ui.rs       |  3 --
 crates/horizon-client/src/settings.rs         | 33 +++++++++++++++----
 4 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f5803ad08..7b69a2ee3 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -9194,10 +9194,6 @@ impl Game<'_> {
         )
     }
     fn apply_settings(&mut self) {
-        if let Some(r) = &self.renderer {
-            self.settings
-                .clamp_gui_scale([r.config.width as i32, r.config.height as i32]);
-        }
         self.streaming.radius = self.settings.render_distance;
         // Options.biomeBlendRadius, ambientOcclusion and cutoutLeaves:
         // LevelExtractor.allChanged when they change.
@@ -13094,10 +13090,6 @@ impl Loading {
                 return;
             }
         }
-        if let Some(r) = &self.renderer {
-            self.settings
-                .clamp_gui_scale([r.config.width as i32, r.config.height as i32]);
-        }
         horizon_client::hud::GUI_SCALE.store(self.settings.gui_scale, Ordering::Relaxed);
         self.window = Some(window);
     }
@@ -13136,8 +13128,6 @@ impl Loading {
             self.settings.horizon.api,
         ) {
             Ok(r) => {
-                self.settings
-                    .clamp_gui_scale([r.config.width as i32, r.config.height as i32]);
                 horizon_client::hud::GUI_SCALE.store(self.settings.gui_scale, Ordering::Relaxed);
                 self.renderer = Some(r);
             }
diff --git a/crates/horizon-client/src/game/startup_menu.rs b/crates/horizon-client/src/game/startup_menu.rs
index a5d658a4d..f7be6241f 100644
--- a/crates/horizon-client/src/game/startup_menu.rs
+++ b/crates/horizon-client/src/game/startup_menu.rs
@@ -272,8 +272,6 @@ impl Loading {
     }
     pub(super) fn apply_menu_settings(&mut self) {
         if let Some(renderer) = &mut self.renderer {
-            self.settings
-                .clamp_gui_scale([renderer.config.width as i32, renderer.config.height as i32]);
             renderer.gamma = self.settings.gamma;
             renderer.set_present_mode(self.settings.vsync, self.settings.horizon.present_mode);
         }
diff --git a/crates/horizon-client/src/options_ui.rs b/crates/horizon-client/src/options_ui.rs
index 1d1f099eb..9f91254bd 100644
--- a/crates/horizon-client/src/options_ui.rs
+++ b/crates/horizon-client/src/options_ui.rs
@@ -3403,9 +3403,6 @@ mod tests {
                 assert_eq!(s.gui_scale, expected);
             }
             s.gui_scale = u32::MAX;
-            s.clamp_gui_scale(framebuffer);
-            assert_eq!(s.gui_scale, max);
-            s.gui_scale = u32::MAX;
             Opt::GuiScale.cycle(&mut s, false, framebuffer);
             assert_eq!(s.gui_scale, 0);
             s.gui_scale = u32::MAX;
diff --git a/crates/horizon-client/src/settings.rs b/crates/horizon-client/src/settings.rs
index 5fc09e35b..2a53e1702 100644
--- a/crates/horizon-client/src/settings.rs
+++ b/crates/horizon-client/src/settings.rs
@@ -104,7 +104,7 @@ pub struct Settings {
     pub master_volume: f32,
     /// Volumes of every other sound source, indexed like SOUND_SOURCES.
     pub volumes: [f32; 11],
-    /// 0 = auto.
+    /// Requested scale (0 = auto); rendering caps it to the current framebuffer.
     pub gui_scale: u32,
     pub view_bobbing: bool,
     /// Brightness 0..1 (gamma).
@@ -284,12 +284,6 @@ fn put_s(f: &mut OptionsFile, key: &str, v: &str) {
     }
 }
 impl Settings {
-    /// `ClampingLazyMaxIntRange.validateValue`: clamp once the framebuffer is known.
-    pub fn clamp_gui_scale(&mut self, framebuffer: [i32; 2]) {
-        let max = crate::window::calculate_scale(framebuffer, 0, self.force_unicode) as u32;
-        self.gui_scale = self.gui_scale.min(max);
-    }
-
     pub fn load(path: &Path) -> Self {
         let horizon = path
             .parent()
@@ -597,6 +591,31 @@ impl Settings {
 #[cfg(test)]
 mod tests {
     use super::*;
+    #[test]
+    fn gui_scale_survives_temporary_small_framebuffer() {
+        for requested in [0, 1, 2, 6] {
+            let settings = Settings::parse(&format!("guiScale:{requested}\n"));
+            // Hyprland's initial surface can be smaller than the fullscreen one.
+            for (framebuffer, maximum) in [([715, 860], 2), ([3400, 1913], 7)] {
+                let effective = crate::window::calculate_scale(
+                    framebuffer,
+                    settings.gui_scale as i32,
+                    settings.force_unicode,
+                );
+                assert_eq!(
+                    effective,
+                    if requested == 0 {
+                        maximum
+                    } else {
+                        (requested as i32).min(maximum)
+                    }
+                );
+                let saved = Settings::parse(&settings.serialize());
+                assert_eq!(saved.gui_scale, requested);
+            }
+        }
+    }
+
     #[test]
     fn round_trips_vanilla_options_txt() {
         let text = "version:4000\nfov:0.5\nrenderDistance:16\nmaxFps:260\nrenderClouds:\"fast\"\nkey_key.jump:key.keyboard.j\nsoundCategory_music:0.25\nresourcePacks:[\"vanilla\",\"file/x.zip\"]\nlang:fr_fr\nsomeFutureOption:42\n";

From fada660310d4dcc8b407219efef987a040b3805c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:10:44 +0100
Subject: [PATCH 199/270] Mod API: capability input (experimental): claimed
 items' use, mod keys

- WIT `input`: claim-items(ids) makes the use button on those items the
  mod's: use-start, then use-stop with the ticks held (button up, item
  out of the hand, or a screen opening); the game does nothing else
  with the click. register-key(name, label, key) for up to 16 keys
  (key.keyboard.r), heard as key-down / key-up while playing; the
  game's own mapping on the key still runs. held(), poll() (256 kept).
- game/mod_input.rs: play_mouse asks mod_use first (local and remote
  windows), the tick ends a use whose item left the hand, the keyboard
  and horizon-ctl's key send the physical key to mod_key.
- No claim and no key, no cost: one check each.
- Experimental: the manifest needs experimental = ["input"].
- The ui test guest gains /input_claim, /input_poll and /input_held,
  with a sandbox test. Docs: mods.md, stability.md, the changelog, the
  regenerated reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/cargo-horizon-mod/src/check.rs         |   1 +
 crates/horizon-client/src/game.rs             |   6 +
 crates/horizon-client/src/game/control.rs     |   5 +
 crates/horizon-client/src/game/mod_input.rs   |  92 +++++++++++
 crates/horizon-client/src/game/mods.rs        |   5 +
 crates/horizon-mod-sdk/src/lib.rs             |   2 +-
 crates/horizon-mod-sdk/wit/horizon.wit        |  44 +++++
 crates/horizon-mods/src/manifest.rs           |  14 +-
 crates/horizon-mods/src/runtime.rs            | 153 ++++++++++++++++++
 crates/horizon-mods/tests/sandbox.rs          |  67 +++++++-
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  30 +++-
 docs/api/mods-reference.md                    |  44 ++++-
 docs/api/mods.md                              |   2 +
 docs/api/stability.md                         |   1 +
 docs/mods.md                                  |   3 +-
 15 files changed, 459 insertions(+), 10 deletions(-)
 create mode 100644 crates/horizon-client/src/game/mod_input.rs

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index dfb9820a2..87ae3c982 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -200,6 +200,7 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
             }),
             // The GUI of a 1280 x 720 window at scale 3.
             gui_size: (427.0, 240.0),
+            held: None,
         });
         mods.tick(t);
         for _ in 0..FRAMES_PER_TICK {
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 31bfe74b6..5b04d8716 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -96,6 +96,7 @@ mod maps;
 mod minecarts;
 mod mob_blocks;
 mod mob_gear;
+mod mod_input;
 mod mod_render;
 mod mods;
 mod mount_menu;
@@ -10479,6 +10480,10 @@ impl Game<'_> {
     }
     /// A mouse button while playing (window or control socket).
     fn play_mouse(&mut self, button: MouseButton, pressed: bool) -> Result<()> {
+        // A mod's claimed item takes the use button (capability `input`).
+        if self.mod_use(button, pressed) {
+            return Ok(());
+        }
         if self.sleeping.is_some() {
             return Ok(());
         }
@@ -11385,6 +11390,7 @@ impl ApplicationHandler for Game<'_> {
                         return Ok(());
                     };
                     self.extras_key(key, event.state == ElementState::Pressed, event.repeat);
+                    self.mod_key(key, event.state == ElementState::Pressed, event.repeat);
                     // key.smoothCamera toggles the cinematic camera.
                     if self.screen == Screen::Playing
                         && event.state == ElementState::Pressed
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index ffe05b518..89ce7c30e 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -294,6 +294,11 @@ impl Game<'_> {
                 if action == "tap" {
                     self.extras_key(physical, false, false);
                 }
+                // So do mods' keys (capability `input`).
+                self.mod_key(physical, action != "up", action == "repeat");
+                if action == "tap" {
+                    self.mod_key(physical, false, false);
+                }
                 // Text screens consume raw presses; releases follow key binds.
                 let typing = matches!(self.screen, Screen::Chat | Screen::Options);
                 let key = if typing && arg(2)? != "up" {
diff --git a/crates/horizon-client/src/game/mod_input.rs b/crates/horizon-client/src/game/mod_input.rs
new file mode 100644
index 000000000..ac80e8e42
--- /dev/null
+++ b/crates/horizon-client/src/game/mod_input.rs
@@ -0,0 +1,92 @@
+//! Capability `input` (docs/mods.md): the use button on items a mod claims,
+//! and the mod's own keys. With no mod claiming items or keys, each hook
+//! here returns after one check.
+use super::Game;
+use winit::{event::MouseButton, keyboard::KeyCode};
+#[cfg(feature = "mods")]
+use {super::Screen, horizon_mods::HeldItem};
+
+/// A claimed item's use while the button is down.
+#[cfg(feature = "mods")]
+pub(super) struct ModUse {
+    item: HeldItem,
+    /// `Game::ticks` when it started.
+    since: u64,
+}
+
+#[cfg(not(feature = "mods"))]
+impl Game<'_> {
+    pub(super) fn mod_use(&mut self, _button: MouseButton, _pressed: bool) -> bool {
+        false
+    }
+    pub(super) fn mod_key(&mut self, _key: KeyCode, _pressed: bool, _repeat: bool) {}
+}
+
+#[cfg(feature = "mods")]
+impl Game<'_> {
+    /// The main hand's stack as `input` shows it; none when it is empty.
+    pub(super) fn mod_held(&self) -> Option<HeldItem> {
+        let stack = self.inventory.get(self.selected)?.as_ref()?;
+        Some(HeldItem {
+            id: stack.item.to_string(),
+            count: stack.count,
+            slot: self.selected as u32,
+        })
+    }
+    /// The use button while playing: true when a mod claimed the held item,
+    /// so the game does nothing else with it (no placing, eating, swing).
+    pub(super) fn mod_use(&mut self, button: MouseButton, pressed: bool) -> bool {
+        if button != MouseButton::Right || !self.mods.mods.claims_any() {
+            return false;
+        }
+        if !pressed {
+            return self.stop_mod_use();
+        }
+        let Some(item) = self.mod_held().filter(|h| self.mods.mods.claims(&h.id)) else {
+            return false;
+        };
+        self.mods.mods.use_start(&item);
+        self.mods.using = Some(ModUse {
+            item,
+            since: self.ticks,
+        });
+        true
+    }
+    /// Ends a claimed use: the button came up, the player switched slots,
+    /// or a screen opened. False when none was going.
+    pub(super) fn stop_mod_use(&mut self) -> bool {
+        let Some(u) = self.mods.using.take() else {
+            return false;
+        };
+        let ticks = self.ticks.saturating_sub(u.since).min(u64::from(u32::MAX)) as u32;
+        self.mods.mods.use_stop(&u.item, ticks);
+        true
+    }
+    /// Once a tick: a claimed use stops when its item leaves the hand or a
+    /// screen opens, as vanilla's `releaseUsingItem`.
+    pub(super) fn tick_mod_use(&mut self) {
+        let Some(u) = &self.mods.using else {
+            return;
+        };
+        let still = self
+            .mod_held()
+            .is_some_and(|h| h.id == u.item.id && h.slot == u.item.slot);
+        if !still || self.screen != Screen::Playing {
+            self.stop_mod_use();
+        }
+    }
+    /// A key went down or up: a mod's registered key while playing (no
+    /// screen) is its `key-down` / `key-up`. Vanilla's mapping on the same
+    /// key still runs.
+    pub(super) fn mod_key(&mut self, key: KeyCode, pressed: bool, repeat: bool) {
+        if repeat || !self.mods.mods.has_keys() {
+            return;
+        }
+        if pressed && (self.screen != Screen::Playing || self.title.is_some()) {
+            return;
+        }
+        if let Some(name) = horizon_client::keybinds::key_name(key) {
+            self.mods.mods.key(name, pressed);
+        }
+    }
+}
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 2a07cb940..1c62046ea 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -34,6 +34,9 @@ use {
 pub(super) struct ModsState {
     #[cfg(feature = "mods")]
     pub(super) mods: Mods,
+    /// Capability `input`: a claimed item's use while the button is down.
+    #[cfg(feature = "mods")]
+    pub(super) using: Option<super::mod_input::ModUse>,
     /// Capability `render`'s camera shakes.
     #[cfg(feature = "mods")]
     pub(super) shake: super::mod_render::Shake,
@@ -315,6 +318,7 @@ impl Game<'_> {
             player,
             clock,
             gui_size: self.gui_size(),
+            held: self.mod_held(),
         }
     }
     /// A game tick.
@@ -322,6 +326,7 @@ impl Game<'_> {
         if !self.mods.mods.is_running() {
             return;
         }
+        self.tick_mod_use();
         let snapshot = self.mod_snapshot();
         self.mods.mods.set_snapshot(snapshot);
         self.mods.mods.tick(self.ticks);
diff --git a/crates/horizon-mod-sdk/src/lib.rs b/crates/horizon-mod-sdk/src/lib.rs
index 8708fb5be..43a6c4263 100644
--- a/crates/horizon-mod-sdk/src/lib.rs
+++ b/crates/horizon-mod-sdk/src/lib.rs
@@ -38,7 +38,7 @@ wit_bindgen::generate!({
 
 pub use exports::horizon::mods::events::{Guest as __Guest, Registration};
 pub use exports::horizon::mods::ui_events::Guest as __UiEventsGuest;
-pub use horizon::mods::{chat, game, hud, log, render, storage, ui};
+pub use horizon::mods::{chat, game, hud, input, log, render, storage, ui};
 
 /// The game's calls into a mod. Only the hooks [`Registration`] asks for
 /// are called; the others may stay as their defaults.
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 64bbac592..1560ec3a7 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -163,6 +163,48 @@ interface ui-events {
     settings-opened: func();
 }
 
+/// Capability `input` (experimental: the manifest needs
+/// `experimental = ["input"]`): the use button on items the mod claims, and
+/// the mod's own keys. Events wait for `poll`, at most 256.
+interface input {
+    /// The main hand's stack.
+    record held-item {
+        /// `minecraft:spyglass`, `<mod>:<path>`.
+        id: string,
+        count: u32,
+        /// The hotbar slot, 0 to 8.
+        slot: u32,
+    }
+    record item-use {
+        item: held-item,
+        /// Game ticks the button was held (0 on `use-start`).
+        ticks: u32,
+    }
+    variant event {
+        /// The use button went down with a claimed item in the main hand.
+        /// The game does nothing else with the click: no placing, no eating,
+        /// no swing.
+        use-start(item-use),
+        /// It came up again, or the item left the hand, or a screen opened.
+        use-stop(item-use),
+        /// A key `register-key` named went down or up while playing (no
+        /// screen open). The game's own mapping on that key still runs.
+        key-down(string),
+        key-up(string),
+    }
+    /// The items whose use the mod handles instead of the game, by id (at
+    /// most 64). Replaces the previous list.
+    claim-items: func(ids: list<string>);
+    /// A key of the mod's: `name` comes back in `key-down` and `key-up`,
+    /// `label` says what it does, `key` is the key as options.txt writes
+    /// it (`key.keyboard.r`). At most 16; an unknown key is an error.
+    register-key: func(name: string, label: string, key: string) -> result<_, string>;
+    /// The main hand's stack, as of this tick; none when it is empty.
+    held: func() -> option<held-item>;
+    /// The events since the last call, oldest first.
+    poll: func() -> list<event>;
+}
+
 /// Capability `render` (experimental: the manifest needs
 /// `experimental = ["render"]`): shapes the game draws for the mod with its
 /// own renderer, kept until the mod replaces them (no call per frame). A mod
@@ -280,6 +322,7 @@ world horizon-ui-mod {
     include horizon-mod;
     import ui;
     import render;
+    import input;
     export ui-events;
 }
 
@@ -292,4 +335,5 @@ world ui-host {
 /// The game's side of capability `render` (imports only).
 world render-host {
     import render;
+    import input;
 }
diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index 1880b9f3e..e9535bc78 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -87,9 +87,12 @@ pub enum Capability {
     /// Shapes on the HUD and the camera's shake, drawn by the game's own
     /// renderer (interface `render`).
     Render,
+    /// The use button on items the mod claims, and its own keys
+    /// (interface `input`).
+    Input,
 }
 impl Capability {
-    pub const ALL: [Capability; 7] = [
+    pub const ALL: [Capability; 8] = [
         Capability::GameRead,
         Capability::Chat,
         Capability::Hud,
@@ -97,6 +100,7 @@ impl Capability {
         Capability::Registries,
         Capability::Ui,
         Capability::Render,
+        Capability::Input,
     ];
     /// The WIT interface it grants, in `horizon:mods`.
     pub fn interface(self) -> &'static str {
@@ -108,12 +112,16 @@ impl Capability {
             Capability::Registries => "registries",
             Capability::Ui => "ui",
             Capability::Render => "render",
+            Capability::Input => "input",
         }
     }
     /// May change in any release: a mod uses it only with
     /// `experimental = ["<name>"]` in its manifest.
     pub fn is_experimental(self) -> bool {
-        matches!(self, Capability::Ui | Capability::Render)
+        matches!(
+            self,
+            Capability::Ui | Capability::Render | Capability::Input
+        )
     }
     /// What the player reads before turning the mod on: "May <this>".
     pub fn describe(self) -> &'static str {
@@ -125,6 +133,7 @@ impl Capability {
             Capability::Registries => "add blocks and items to your worlds",
             Capability::Ui => "show its own screens and a settings page",
             Capability::Render => "draw on your screen and shake the camera",
+            Capability::Input => "take over the use button on its own items, and add keys",
         }
     }
     /// The capability a component import needs, `Ok(None)` for one every
@@ -157,6 +166,7 @@ impl fmt::Display for Capability {
             Capability::Registries => "registries",
             Capability::Ui => "ui",
             Capability::Render => "render",
+            Capability::Input => "input",
         };
         f.write_str(name)
     }
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index e19bfbe3f..881eaf0ae 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -47,6 +47,9 @@ mod render_bindings {
         world: "render-host",
     });
 }
+use render_bindings::horizon::mods::input;
+/// Capability `input`'s records (WIT `interface input`).
+pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, ItemUse};
 /// What capability `render` asks the game to draw (WIT `interface render`).
 pub use render_bindings::horizon::mods::render::{
     FillShape, ItemShape, Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape,
@@ -85,6 +88,8 @@ pub struct Snapshot {
     pub clock: Option<Clock>,
     /// The screen in GUI pixels (capability `render`'s `gui-size`).
     pub gui_size: (f32, f32),
+    /// The main hand's stack (capability `input`'s `held`).
+    pub held: Option<HeldItem>,
 }
 
 /// What mods asked the game to show since the last [`Mods::drain`].
@@ -172,6 +177,7 @@ struct State {
     ui: UiState,
     /// Capability `render`'s HUD shapes, drawn until replaced.
     shapes: Vec<Shape>,
+    input: InputState,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
     /// Bytes `storage::set` may still write before this hook call ends
@@ -312,6 +318,7 @@ impl Mods {
             panel: None,
             ui: UiState::default(),
             shapes: Vec::new(),
+            input: InputState::default(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
             limits: StoreLimitsBuilder::new()
@@ -503,6 +510,78 @@ impl Mods {
             .iter()
             .filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
     }
+    /// Some running mod claimed items (capability `input`).
+    pub fn claims_any(&self) -> bool {
+        self.inputs().any(|i| !i.claimed.is_empty())
+    }
+    /// Some running mod claimed the item `id`.
+    pub fn claims(&self, id: &str) -> bool {
+        self.inputs().any(|i| i.claimed.iter().any(|c| c == id))
+    }
+    /// Some running mod registered a key.
+    pub fn has_keys(&self) -> bool {
+        self.inputs().any(|i| !i.keys.is_empty())
+    }
+    /// The mods' keys: (mod name, key name, label, key), for Controls.
+    pub fn mod_keys(&self) -> impl Iterator<Item = (&str, &ModKey)> {
+        self.entries
+            .iter()
+            .filter_map(|e| e.run.as_ref())
+            .flat_map(|r| {
+                let d = r.store.data();
+                d.input.keys.iter().map(move |k| (d.name.as_str(), k))
+            })
+    }
+    /// The use button went down with `item`: `use-start` to each mod that
+    /// claimed it.
+    pub fn use_start(&mut self, item: &HeldItem) {
+        let event = InputEvent::UseStart(ItemUse {
+            item: item.clone(),
+            ticks: 0,
+        });
+        self.push_input(|i| i.claimed.contains(&item.id), &event);
+    }
+    /// The claimed use ended after `ticks`.
+    pub fn use_stop(&mut self, item: &HeldItem, ticks: u32) {
+        let event = InputEvent::UseStop(ItemUse {
+            item: item.clone(),
+            ticks,
+        });
+        self.push_input(|i| i.claimed.contains(&item.id), &event);
+    }
+    /// The key `key` (`key.keyboard.r`) went down or up: each mod with a
+    /// key on it hears its own name for it.
+    pub fn key(&mut self, key: &str, down: bool) {
+        for run in self.entries.iter_mut().filter_map(|e| e.run.as_mut()) {
+            let input = &mut run.store.data_mut().input;
+            let names: Vec<String> = input
+                .keys
+                .iter()
+                .filter(|k| k.key == key)
+                .map(|k| k.name.clone())
+                .collect();
+            for name in names {
+                input.push(if down {
+                    InputEvent::KeyDown(name)
+                } else {
+                    InputEvent::KeyUp(name)
+                });
+            }
+        }
+    }
+    fn inputs(&self) -> impl Iterator<Item = &InputState> {
+        self.entries
+            .iter()
+            .filter_map(|e| Some(&e.run.as_ref()?.store.data().input))
+    }
+    fn push_input(&mut self, to: impl Fn(&InputState) -> bool, event: &InputEvent) {
+        for run in self.entries.iter_mut().filter_map(|e| e.run.as_mut()) {
+            let input = &mut run.store.data_mut().input;
+            if to(input) {
+                input.push(event.clone());
+            }
+        }
+    }
     /// The running mods' HUD shapes (capability `render`), each mod's in
     /// its own order, mods in load order.
     pub fn hud_shapes(&self) -> impl Iterator<Item = &Shape> {
@@ -698,6 +777,80 @@ impl chat::Host for State {
         }
     }
 }
+/// A key a mod registered (capability `input`).
+#[derive(Clone, Debug, PartialEq)]
+pub struct ModKey {
+    /// The mod's own name for it, echoed in `key-down`.
+    pub name: String,
+    /// What it does, for Controls.
+    pub label: String,
+    /// `key.keyboard.r`.
+    pub key: String,
+}
+
+/// What capability `input` holds for one mod.
+#[derive(Default)]
+struct InputState {
+    claimed: Vec<String>,
+    keys: Vec<ModKey>,
+    events: std::collections::VecDeque<InputEvent>,
+}
+/// Events kept for `poll`, items claimed and keys, per mod.
+const INPUT_EVENTS: usize = 256;
+const CLAIMS: usize = 64;
+const KEYS: usize = 16;
+
+/// `key.keyboard.<name>` or `key.mouse.<name>`, as options.txt writes keys;
+/// the game knows which names exist and ignores a key it has none for.
+fn key_ok(key: &str) -> bool {
+    let rest = key
+        .strip_prefix("key.keyboard.")
+        .or_else(|| key.strip_prefix("key.mouse."));
+    rest.is_some_and(|r| {
+        (1..=32).contains(&r.len())
+            && r.bytes()
+                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'.')
+    })
+}
+
+impl InputState {
+    fn push(&mut self, event: InputEvent) {
+        if self.events.len() == INPUT_EVENTS {
+            self.events.pop_front();
+        }
+        self.events.push_back(event);
+    }
+}
+
+impl input::Host for State {
+    fn claim_items(&mut self, ids: Vec<String>) {
+        self.input.claimed = ids.into_iter().take(CLAIMS).map(clip).collect();
+    }
+    fn register_key(&mut self, name: String, label: String, key: String) -> Result<(), String> {
+        if !key_ok(&key) {
+            return Err(format!(
+                "{key:?} is not a key as options.txt writes them (key.keyboard.r)"
+            ));
+        }
+        let (name, label) = (clip(name), clip(label));
+        if let Some(k) = self.input.keys.iter_mut().find(|k| k.name == name) {
+            (k.label, k.key) = (label, key);
+            return Ok(());
+        }
+        if self.input.keys.len() == KEYS {
+            return Err(format!("a mod may register {KEYS} keys"));
+        }
+        self.input.keys.push(ModKey { name, label, key });
+        Ok(())
+    }
+    fn held(&mut self) -> Option<HeldItem> {
+        self.snapshot.held.clone()
+    }
+    fn poll(&mut self) -> Vec<InputEvent> {
+        self.input.events.drain(..).collect()
+    }
+}
+
 /// HUD shapes one mod may keep (capability `render`).
 const SHAPES: usize = 1024;
 /// The longest jolt `render.shake` makes, in seconds.
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index dac333fe6..ba1736e5e 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -1,7 +1,8 @@
 //! Loads real mods built with the SDK: the coords-hud example and a guest
 //! that misbehaves on command. Needs `rustup target add wasm32-unknown-unknown`.
 use horizon_mods::{
-    Clock, Corner, Mods, Output, Package, Player, Shape, Snapshot, Status, manifest::componentize,
+    Clock, Corner, HeldItem, Mods, Output, Package, Player, Shape, Snapshot, Status,
+    manifest::componentize,
 };
 use std::{
     path::{Path, PathBuf},
@@ -22,8 +23,8 @@ id = "test_ui_guest"
 name = "Test UI Guest"
 version = "0.1.0"
 api = "0.1"
-capabilities = ["chat", "ui", "render"]
-experimental = ["ui", "render"]
+capabilities = ["chat", "ui", "render", "input"]
+experimental = ["ui", "render", "input"]
 "#;
 
 /// Builds both mods once and writes their `.hmod` files; returns the folder.
@@ -90,6 +91,7 @@ fn player() -> Snapshot {
             day_time: 24000 + 6000,
         }),
         gui_size: (427.0, 240.0),
+        held: None,
     }
 }
 
@@ -422,6 +424,7 @@ fn render_shapes_and_shakes() {
     let mut mods = load("horizon_mods_test_ui_guest.hmod");
     mods.set_snapshot(Snapshot {
         gui_size: (427.0, 240.0),
+        held: None,
         ..Snapshot::default()
     });
     assert_eq!(mods.hud_shapes().count(), 0);
@@ -448,6 +451,64 @@ fn render_shapes_and_shakes() {
     );
 }
 
+#[test]
+fn input_claims_keys_and_events() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    let chat = |mods: &mut Mods| -> Vec<String> {
+        mods.drain()
+            .into_iter()
+            .filter_map(|o| match o {
+                Output::Chat { text, .. } => Some(text),
+                _ => None,
+            })
+            .collect()
+    };
+    assert!(!mods.claims_any() && !mods.has_keys());
+    assert!(mods.command("input_claim"));
+    let said = chat(&mut mods);
+    assert!(
+        said[0].starts_with("claimed; \"R\" is not a key"),
+        "{said:?}"
+    );
+    assert!(mods.claims("minecraft:stick") && !mods.claims("minecraft:stone"));
+    let keys: Vec<_> = mods
+        .mod_keys()
+        .map(|(m, k)| (m.to_owned(), k.key.clone()))
+        .collect();
+    assert_eq!(
+        keys,
+        [("Test UI Guest".to_owned(), "key.keyboard.r".to_owned())]
+    );
+    // The game feeds the events; the mod reads them in order with `poll`.
+    let stick = HeldItem {
+        id: "minecraft:stick".into(),
+        count: 3,
+        slot: 2,
+    };
+    mods.use_start(&stick);
+    mods.key("key.keyboard.r", true);
+    mods.key("key.keyboard.t", true);
+    mods.key("key.keyboard.r", false);
+    mods.use_stop(&stick, 12);
+    assert!(mods.command("input_poll"));
+    assert_eq!(
+        chat(&mut mods),
+        [
+            "use-start minecraft:stick 0",
+            "key-down wheel",
+            "key-up wheel",
+            "use-stop minecraft:stick 12"
+        ]
+    );
+    // `held` reads the snapshot.
+    mods.set_snapshot(Snapshot {
+        held: Some(stick),
+        ..Snapshot::default()
+    });
+    assert!(mods.command("input_held"));
+    assert_eq!(chat(&mut mods), ["holding minecraft:stick x3 in 2"]);
+}
+
 #[test]
 fn content_only_mods_load_without_an_engine() {
     let manifest = r#"
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index 146ab6f40..be2b8fcc4 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -1,9 +1,11 @@
 //! A mod for the runtime's `ui` tests: `/ui_screen` opens a screen with one
 //! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes
 //! the screen; the `ui-events` calls answer in chat so the host sees them.
-//! `/render_hud`, `/render_clear` and `/render_shake` test `render`.
+//! `/render_hud`, `/render_clear` and `/render_shake` test `render`;
+//! `/input_claim`, `/input_poll` and `/input_held` test `input`.
 use horizon_mod_sdk::{
     Mod, Registration, chat,
+    input::{self, Event},
     render::{self, FillShape, ItemShape, Point, QuadShape, Rect, Shape, SpriteShape, TextShape},
     ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
 };
@@ -87,6 +89,9 @@ impl Mod for Guest {
             "render_hud",
             "render_clear",
             "render_shake",
+            "input_claim",
+            "input_poll",
+            "input_held",
         ]
         .into_iter()
         .fold(Registration::new(), Registration::command);
@@ -102,6 +107,29 @@ impl Mod for Guest {
             "ui_close" => ui::close_screen(),
             "render_hud" => render::set_hud(&shapes()),
             "render_clear" => render::set_hud(&[]),
+            "input_claim" => {
+                input::claim_items(&["minecraft:stick".into()]);
+                input::register_key("wheel", "Open the wheel", "key.keyboard.r")?;
+                // Not a key: refused.
+                let bad = input::register_key("bad", "Bad", "R").unwrap_err();
+                chat::show(&format!("claimed; {bad}"));
+            }
+            "input_poll" => {
+                for event in input::poll() {
+                    chat::show(&match event {
+                        Event::UseStart(u) => format!("use-start {} {}", u.item.id, u.ticks),
+                        Event::UseStop(u) => format!("use-stop {} {}", u.item.id, u.ticks),
+                        Event::KeyDown(k) => format!("key-down {k}"),
+                        Event::KeyUp(k) => format!("key-up {k}"),
+                    });
+                }
+            }
+            "input_held" => {
+                let held = input::held().map_or("nothing".into(), |h| {
+                    format!("{} x{} in {}", h.id, h.count, h.slot)
+                });
+                chat::show(&format!("holding {held}"));
+            }
             // Clamped to (1, 10); the two after it shake nothing.
             "render_shake" => {
                 render::shake(2.0, 99.0);
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index ef889d599..b1b52164a 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -14,6 +14,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
 | `ui` | [`ui`](#ui) | show its own screens and a settings page |
 | `render` | [`render`](#render) | draw on your screen and shake the camera |
+| `input` | [`input`](#input) | take over the use button on its own items, and add keys |
 
 ## World `horizon-mod`
 
@@ -24,7 +25,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 
 A mod with widgets (capability `ui`): the SDK builds every mod against this world. Mods built for `horizon-mod` alone (no `ui-events` export) still load and simply hear nothing of their widgets.
 
-- Imports (what the game offers): `ui`, `render`, `log`, `game`, `chat`, `hud`, `storage`
+- Imports (what the game offers): `ui`, `render`, `input`, `log`, `game`, `chat`, `hud`, `storage`
 - Exports (what the mod provides): `ui-events`, `events`
 
 ## World `ui-host`
@@ -38,7 +39,7 @@ The game's side of `horizon-ui-mod` beyond `horizon-mod`.
 
 The game's side of capability `render` (imports only).
 
-- Imports (what the game offers): `render`
+- Imports (what the game offers): `render`, `input`
 - Exports (what the mod provides): 
 
 ## `log`
@@ -213,6 +214,45 @@ What the game calls on a mod that shows widgets (capability `ui`): what the play
 | `closed` | `func()` | The player left the mod's screen (Esc or Done); not for a screen the mod closed itself or one that went away with the mod. |
 | `settings-opened` | `func()` | The player opened the mod's settings page in Options > Mods: call `ui::set-settings` now to fill it with fresh widgets. |
 
+## `input`
+
+Access: capability `input`.
+
+Capability `input` (experimental: the manifest needs `experimental = ["input"]`): the use button on items the mod claims, and the mod's own keys. Events wait for `poll`, at most 256.
+
+### record `held-item`
+
+The main hand's stack.
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `string` | `minecraft:spyglass`, `<mod>:<path>`. |
+| `count` | `u32` |  |
+| `slot` | `u32` | The hotbar slot, 0 to 8. |
+
+### record `item-use`
+
+| Field | Type | |
+| --- | --- | --- |
+| `item` | `held-item` |  |
+| `ticks` | `u32` | Game ticks the button was held (0 on `use-start`). |
+
+### variant `event`
+
+| Case | Payload | |
+| --- | --- | --- |
+| `use-start` | `item-use` | The use button went down with a claimed item in the main hand. The game does nothing else with the click: no placing, no eating, no swing. |
+| `use-stop` | `item-use` | It came up again, or the item left the hand, or a screen opened. |
+| `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. |
+| `key-up` | `string` |  |
+
+| Function | Signature | What it does |
+| --- | --- | --- |
+| `claim-items` | `func(ids: list<string>)` | The items whose use the mod handles instead of the game, by id (at most 64). Replaces the previous list. |
+| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`). At most 16; an unknown key is an error. |
+| `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
+| `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
+
 ## `render`
 
 Access: capability `render`.
diff --git a/docs/api/mods.md b/docs/api/mods.md
index cda484c31..29da98122 100644
--- a/docs/api/mods.md
+++ b/docs/api/mods.md
@@ -95,6 +95,8 @@ What real mods need next, in the order modpacks and servers need it:
 
 ## Changelog
 
+- Experimental `input` (`experimental = ["input"]`): `claim-items`, `register-key`, `held`, `poll` (use-start,
+  use-stop, key-down, key-up).
 - Experimental `render` (`experimental = ["render"]`): HUD shapes (fill, quad, sprite, item, text), `gui-size`, camera
   `shake`, drawn by the game's own renderer.
 - API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation.
diff --git a/docs/api/stability.md b/docs/api/stability.md
index 76c3c4e51..b513d5ddf 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -89,6 +89,7 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
 | Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
 | Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` |
 | Mod API: `render` (HUD shapes, camera shake; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` |
+| Mod API: `input` (claimed items' use, the mod's keys) | experimental | manifest `experimental = ["input"]` |
 | Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
 | Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first |
 | Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
diff --git a/docs/mods.md b/docs/mods.md
index 672d6c7fd..01de73fdb 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -88,6 +88,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
 | `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects. The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
+| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs); `held()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 
 | Hook (export) | When |
 |---|---|
@@ -289,7 +290,7 @@ experimental = []            # experimental capabilities it uses, e.g. ["ui"]
 ```
 
 Unknown keys are refused, so a typo is an error, not a silently ignored
-permission. An experimental capability (today `ui` and `render`) may change in any release
+permission. An experimental capability (today `ui`, `render` and `input`) may change in any release
 ([stability](api/stability.md)): a mod uses it only by naming it in
 `experimental` as well, so nobody depends on it by accident.
 

From 61c5f29ab772d04d4cf55c06f59870c27205c16b Mon Sep 17 00:00:00 2001
From: levzzz <86072227+levzzz5154@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:04:47 +0500
Subject: [PATCH 200/270] Game Rules and Statistics: the scroll bars can be
 dragged

Both lists drew a scroll bar but only listened to the mouse wheel: a press
inside the bar column, the drag that follows and the release were dropped.
`ui::Scroll` already models AbstractSelectionList's press/drag/release (the
server list uses it); the two screens now keep their scrolling in it and the
window passes the press, the pointer's moves while it is held and the release
along.

Fixes #1782
---
 crates/horizon-client/src/game.rs             | 10 +++
 .../src/game/game_rules_screen.rs             | 56 +++++++++++----
 crates/horizon-client/src/game/lan_screen.rs  | 21 ++++++
 .../horizon-client/src/game/stats_screen.rs   | 68 ++++++++++++++++---
 4 files changed, 132 insertions(+), 23 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f05ee41e4..f4b2fc192 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -10962,6 +10962,12 @@ impl ApplicationHandler for Game<'_> {
                         if self.screen == Screen::Advancements {
                             self.advancements_drag();
                         }
+                        if self.screen == Screen::Stats {
+                            self.stats_drag();
+                        }
+                        if self.screen == Screen::WorldOptions {
+                            self.world_options_drag();
+                        }
                         if self.screen == Screen::Creative {
                             let (_, oy) = Self::creative_origin(&b);
                             self.creative_screen.drag_scrollbar(self.cursor.1 - oy);
@@ -11238,6 +11244,9 @@ impl ApplicationHandler for Game<'_> {
                         Screen::WorldOptions if pressed && button == MouseButton::Left => {
                             self.world_options_click()
                         }
+                        Screen::WorldOptions if button == MouseButton::Left => {
+                            self.world_options_release()
+                        }
                         Screen::Friends if pressed && button == MouseButton::Left => {
                             self.friends_screen_click()
                         }
@@ -11261,6 +11270,7 @@ impl ApplicationHandler for Game<'_> {
                                 .map_or([1, 1], |r| [r.config.width, r.config.height]);
                             self.stats_click(size);
                         }
+                        Screen::Stats if button == MouseButton::Left => self.stats_release(),
                         _ => {}
                     }
                 }
diff --git a/crates/horizon-client/src/game/game_rules_screen.rs b/crates/horizon-client/src/game/game_rules_screen.rs
index d925c5081..126bc8804 100644
--- a/crates/horizon-client/src/game/game_rules_screen.rs
+++ b/crates/horizon-client/src/game/game_rules_screen.rs
@@ -45,7 +45,8 @@ pub(super) struct RulesScreen {
     initial: GameRules,
     /// IntegerRuleEntry's boxes, by rule.
     numbers: Vec<(&'static str, EditBox)>,
-    scroll: f32,
+    /// RuleList's scrolling: the wheel and the held scrollbar.
+    scroll: ui::Scroll,
     /// ConfirmScreen "Game Rule Changes" in its place.
     confirm: bool,
 }
@@ -120,7 +121,7 @@ impl RulesScreen {
             values: rules.clone(),
             initial: rules.clone(),
             numbers,
-            scroll: 0.0,
+            scroll: ui::Scroll::default(),
             confirm: false,
         }
     }
@@ -156,12 +157,17 @@ impl RulesScreen {
             })
             .collect()
     }
-    fn max_scroll(rows: usize, h: f32) -> f32 {
-        (ROW * rows as f32 + 4.0 - (h - HEADER - FOOTER)).max(0.0)
-    }
     /// Entry `i`'s top: 2 under the list's top, less the scroll.
     fn row_top(&self, i: usize) -> f32 {
-        HEADER + 2.0 - self.scroll.trunc() + ROW * i as f32
+        HEADER + 2.0 - self.scroll.amount.trunc() + ROW * i as f32
+    }
+    /// The list's scrollbar column (AbstractSelectionList: 6 pixels right of
+    /// the entries) and the pixels it scrolls.
+    fn bar(w: f32) -> f32 {
+        row_left(w) + ROW_WIDTH + 6.0 + 2.0
+    }
+    fn content(&self) -> f32 {
+        ROW * self.rows().len() as f32 + 4.0
     }
     /// getEntryAtPosition: the row under the pointer, inside the list.
     fn hovered(&self, rows: usize, (x, y): (f32, f32), (w, h): (f32, f32)) -> Option<usize> {
@@ -212,10 +218,28 @@ impl RulesScreen {
     /// The mouse wheel (AbstractSelectionList: half an entry a step).
     pub(super) fn wheel(&mut self, delta: f32, h: f32) {
         if !self.confirm {
-            let max = Self::max_scroll(self.rows().len(), h);
-            self.scroll = (self.scroll - delta * ROW / 2.0).clamp(0.0, max);
+            let content = self.content();
+            self.scroll
+                .wheel(delta, ROW / 2.0, HEADER, h - FOOTER, content);
         }
     }
+    /// A press on the scrollbar holds it (AbstractSelectionList.updateScrolling).
+    pub(super) fn press_scrollbar(&mut self, cursor: (f32, f32), (w, h): (f32, f32)) -> bool {
+        let content = self.content();
+        self.scroll
+            .press(cursor, Self::bar(w), HEADER, h - FOOTER, content)
+    }
+    /// The pointer moved while the scrollbar is held.
+    pub(super) fn drag(&mut self, y: f32, h: f32) {
+        if self.scroll.held() {
+            let content = self.content();
+            self.scroll.drag(y, HEADER, h - FOOTER, content);
+        }
+    }
+    /// The button came up: the scrollbar lets go.
+    pub(super) fn release(&mut self) {
+        self.scroll.release();
+    }
     fn focused(&mut self) -> Option<(Option<&'static str>, &mut EditBox)> {
         if self.search.focused {
             return Some((None, &mut self.search));
@@ -229,7 +253,7 @@ impl RulesScreen {
     /// number sets its rule when valid (IntegerRuleEntry's responder).
     fn edited(&mut self, rule: Option<&'static str>) {
         let Some(name) = rule else {
-            self.scroll = 0.0;
+            self.scroll.amount = 0.0;
             return;
         };
         let Some(r) = gamerules::rule(name) else {
@@ -286,6 +310,11 @@ impl RulesScreen {
         if on(cx, cy, 150.0, 20.0) {
             return self.close();
         }
+        // A press on the scrollbar holds it and clicks nothing else.
+        if self.press_scrollbar(cursor, size) {
+            self.unfocus();
+            return None;
+        }
         // A click moves the focus to the widget under it.
         let (sx, sy) = search_at(w);
         if on(sx, sy, SEARCH_WIDTH, 15.0) {
@@ -360,7 +389,8 @@ impl RulesScreen {
             return;
         }
         let rows = self.rows();
-        self.scroll = self.scroll.clamp(0.0, Self::max_scroll(rows.len(), h));
+        let content = ROW * rows.len() as f32 + 4.0;
+        self.scroll.clamp(HEADER, h - FOOTER, content);
         // RuleList: the in-world list background, its entries clipped to it,
         // then the separators and scrollbar.
         ui::list_background(batch, atlas, HEADER, h - FOOTER, true);
@@ -421,16 +451,14 @@ impl RulesScreen {
         }
         batch.clip_since(first, 0.0, HEADER, w, h - FOOTER);
         ui::separators(batch, atlas, HEADER, h - FOOTER, true);
-        let content = ROW * rows.len() as f32 + 4.0;
-        let bar_x = left + ROW_WIDTH + 6.0 + 2.0;
         ui::scrollbar(
             batch,
             atlas,
-            bar_x,
+            Self::bar(w),
             HEADER,
             h - FOOTER,
             content,
-            self.scroll.trunc(),
+            self.scroll.amount.trunc(),
         );
         // The header: the title centred over the search box.
         let title = Text::translate("editGamerule.title", &[]);
diff --git a/crates/horizon-client/src/game/lan_screen.rs b/crates/horizon-client/src/game/lan_screen.rs
index 335b5fbae..2d0416d72 100644
--- a/crates/horizon-client/src/game/lan_screen.rs
+++ b/crates/horizon-client/src/game/lan_screen.rs
@@ -802,6 +802,27 @@ impl Game<'_> {
         }
     }
 
+    /// The pointer moved while a list's scrollbar is held: the game rules'
+    /// list follows it (AbstractSelectionList.mouseDragged).
+    pub(super) fn world_options_drag(&mut self) {
+        let h = self.gui_size().1;
+        if let Some(o) = self.world_options.as_mut()
+            && o.view == View::GameRules
+            && let Some(rules) = o.rules.as_mut()
+        {
+            rules.drag(self.cursor.1, h);
+        }
+    }
+
+    /// The button came up: a held scrollbar lets go (onRelease).
+    pub(super) fn world_options_release(&mut self) {
+        if let Some(o) = self.world_options.as_mut()
+            && let Some(rules) = o.rules.as_mut()
+        {
+            rules.release();
+        }
+    }
+
     pub(super) fn world_options_click(&mut self) {
         let Some(mut o) = self.world_options.take() else {
             return;
diff --git a/crates/horizon-client/src/game/stats_screen.rs b/crates/horizon-client/src/game/stats_screen.rs
index 5505d423d..e86b29aeb 100644
--- a/crates/horizon-client/src/game/stats_screen.rs
+++ b/crates/horizon-client/src/game/stats_screen.rs
@@ -158,7 +158,8 @@ const COLUMNS: [(&str, &str); 6] = [
 #[derive(Default)]
 pub(super) struct StatsUi {
     tab: usize,
-    scroll: f32,
+    /// The list's scrolling: the wheel and the held scrollbar.
+    scroll: horizon_client::ui::Scroll,
     sort: Option<(usize, i32)>,
 }
 /// `MenuTabBar` geometry: three tabs over at most 400 pixels.
@@ -182,6 +183,15 @@ impl Game<'_> {
         self.stats_ui = StatsUi::default();
         self.screen = Screen::Stats;
     }
+    /// The list's scrollbar column (right of the 280 pixel list) and the
+    /// pixels it scrolls.
+    fn stats_bar(w: f32) -> f32 {
+        ((w - 280.0) / 2.0).floor() + 280.0 + 6.0
+    }
+    fn stats_content(&self) -> f32 {
+        let (row_h, rows) = self.stats_rows();
+        row_h * rows as f32 + 4.0
+    }
     fn stats_rows(&self) -> (f32, usize) {
         match self.stats_ui.tab {
             0 => (14.0, CUSTOM.len()),
@@ -260,10 +270,9 @@ impl Game<'_> {
         // The list.
         let (row_h, rows) = self.stats_rows();
         let content = row_h * rows as f32 + 4.0;
-        let max_scroll = (content - (bottom - top)).max(0.0);
-        self.stats_ui.scroll = self.stats_ui.scroll.clamp(0.0, max_scroll);
+        self.stats_ui.scroll.clamp(top, bottom, content);
         let left = ((w - 280.0) / 2.0).floor();
-        let scroll = self.stats_ui.scroll;
+        let scroll = self.stats_ui.scroll.amount;
         let row_y = |i: usize| top + 4.0 + i as f32 * row_h - scroll;
         let visible = |y: f32| y >= top && y + row_h <= bottom;
         match self.stats_ui.tab {
@@ -408,11 +417,11 @@ impl Game<'_> {
         ui::scrollbar(
             batch,
             atlas,
-            left + 280.0 + 6.0,
+            Self::stats_bar(w),
             top,
             bottom,
             content,
-            self.stats_ui.scroll,
+            self.stats_ui.scroll.amount,
         );
         self.draw_stats_footer(batch, w, h);
     }
@@ -433,6 +442,10 @@ impl Game<'_> {
         );
     }
     pub(super) fn stats_click(&mut self, size: [u32; 2]) {
+        // A press on the scrollbar holds it and clicks nothing else.
+        if self.stats_press_scrollbar(size) {
+            return;
+        }
         let b = HudBatch::new(size);
         let (w, h) = (b.width, b.height);
         let (x0, tw) = tabs(w);
@@ -441,7 +454,7 @@ impl Game<'_> {
                 && self.stats_ui.tab != i
             {
                 self.stats_ui.tab = i;
-                self.stats_ui.scroll = 0.0;
+                self.stats_ui.scroll.amount = 0.0;
                 self.audio
                     .play("minecraft:ui.button.click", None, 0.25, 1.0);
                 return;
@@ -461,7 +474,7 @@ impl Game<'_> {
         }
         if self.stats_ui.tab == 1 {
             let left = ((w - 280.0) / 2.0).floor();
-            let y = TAB_H + 4.0 - self.stats_ui.scroll;
+            let y = TAB_H + 4.0 - self.stats_ui.scroll.amount;
             for c in 0..COLUMNS.len() {
                 let x = left + 75.0 + 40.0 * c as f32 - 18.0;
                 if ui::hovered(self.cursor, x, y + 1.0, 18.0, 18.0) {
@@ -479,6 +492,43 @@ impl Game<'_> {
     }
     pub(super) fn stats_scroll(&mut self, amount: f32) {
         let (row_h, _) = self.stats_rows();
-        self.stats_ui.scroll -= amount * row_h / 2.0;
+        let size = self
+            .renderer
+            .as_ref()
+            .map_or([1280, 720], |r| [r.config.width, r.config.height]);
+        let h = HudBatch::new(size).height;
+        let content = self.stats_content();
+        self.stats_ui
+            .scroll
+            .wheel(amount, row_h / 2.0, TAB_H, h - FOOTER, content);
+    }
+    /// A press on the statistics list's scrollbar holds it
+    /// (`AbstractSelectionList.updateScrolling`).
+    pub(super) fn stats_press_scrollbar(&mut self, size: [u32; 2]) -> bool {
+        let b = HudBatch::new(size);
+        let (w, h) = (b.width, b.height);
+        let content = self.stats_content();
+        self.stats_ui
+            .scroll
+            .press(self.cursor, Self::stats_bar(w), TAB_H, h - FOOTER, content)
+    }
+    /// The pointer moved while the scrollbar is held.
+    pub(super) fn stats_drag(&mut self) {
+        if !self.stats_ui.scroll.held() {
+            return;
+        }
+        let size = self
+            .renderer
+            .as_ref()
+            .map_or([1280, 720], |r| [r.config.width, r.config.height]);
+        let h = HudBatch::new(size).height;
+        let content = self.stats_content();
+        self.stats_ui
+            .scroll
+            .drag(self.cursor.1, TAB_H, h - FOOTER, content);
+    }
+    /// The button came up: the scrollbar lets go.
+    pub(super) fn stats_release(&mut self) {
+        self.stats_ui.scroll.release();
     }
 }

From a4a709c2d698788c30af6612d1870be9fc5e5763 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:16:18 +0100
Subject: [PATCH 201/270] Roadmap: OpenGL shipped in v0.2.63; three players'
 ideas kept by Ludovic

One-command server install, launcher-style game menus (off by default), AppImage and a Nix flake.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ROADMAP.md                | 45 ++++++++++++++++++++++++-----------
 roadmap/roadmap.toml      | 49 ++++++++++++++++++++++++++++++++++-----
 website/data/roadmap.json | 44 +++++++++++++++++++++++++++++++----
 3 files changed, 114 insertions(+), 24 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 7e4cc9937..a04eca2ce 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -16,7 +16,7 @@ Horizon is Minecraft: Java Edition 26.3 rewritten from scratch in Rust, so it ru
 - **Single player as a server: the last differences**: Single player now runs a small server in the background, as vanilla does. We are fixing what still behaves differently there; every fix also works for LAN and server players.
 - **Horizon's mod registry**: One place for mods, modpacks and resource packs made for Horizon: browse them on the website and install them from the launcher in one click.
 
-**Next**: Microsoft sign-in (coming soon); CurseForge in the mod browser (coming soon); Fresh benchmarks against vanilla; Pistons push players and mobs; Horizon on Intel Macs; Faster world creation and entry on small CPUs; Servers that hold 20 TPS with 50 to 100 players; Low-end computers: Steam Deck, old Macs, 8 GB; Native upscaling; A batch of targeted optimisations; A Convert to Rust button for what isn't rewritten yet; Mods with code: machines, magic, mobs; Data packs in the mod browser; Prepare a version without Java; Server console, bans and a full admin API; Hosting polish: Windows service, safe updates; Guided hosting with Tailscale and an invite button; An official Docker image for servers; One single-player path: remove the in-frame world; Villages and combat, exactly as in vanilla; Choose the audio output device; Mods that read and change the world; Machines and blocks with inventories (API 0.4); Lua and other languages for mods; Well-known shader looks, rewritten for Horizon; A visible beta label; Wayland and Hyprland polish; A versioned agent-control protocol; Port mods with your own AI agent; Horizon on X (coming soon); Pipeline protection and a GitHub App for agents; Signed updates everywhere, installers included.
+**Next**: Microsoft sign-in (coming soon); CurseForge in the mod browser (coming soon); Fresh benchmarks against vanilla; Pistons push players and mobs; Horizon on Intel Macs; Faster world creation and entry on small CPUs; Servers that hold 20 TPS with 50 to 100 players; Low-end computers: Steam Deck, old Macs, 8 GB; Native upscaling; A batch of targeted optimisations; A Convert to Rust button for what isn't rewritten yet; Mods with code: machines, magic, mobs; Data packs in the mod browser; Prepare a version without Java; Server console, bans and a full admin API; Hosting polish: Windows service, safe updates; Guided hosting with Tailscale and an invite button; An official Docker image for servers; One single-player path: remove the in-frame world; Villages and combat, exactly as in vanilla; Choose the audio output device; Mods that read and change the world; Machines and blocks with inventories (API 0.4); Lua and other languages for mods; Well-known shader looks, rewritten for Horizon; A visible beta label; Wayland and Hyprland polish; A versioned agent-control protocol; Port mods with your own AI agent; Horizon on X (coming soon); Pipeline protection and a GitHub App for agents; Signed updates everywhere, installers included; A server you install with one command.
 
 **How to help**: Play it and tell us what differs from vanilla (Discord or GitHub), run the benchmark on your computer, vote for what you want next, or pick one of the Help wanted items.
 
@@ -374,6 +374,16 @@ More: [docs/server.md](docs/server.md)
 
 </details>
 
+#### A server you install with one command
+
+Install and run a Horizon dedicated server from a terminal with a single command, no launcher needed, for VPSes and headless machines.
+
+<details><summary>Technical</summary>
+
+A player's idea (#horizon-ideas). `horizon-server` already runs headless; left: an install script (Linux/macOS shell, Windows PowerShell) that fetches the signed release, checks it, asks for or points at the player's own game files and starts the server, documented in [docs/hosting.md](docs/hosting.md).
+
+</details>
+
 ### Mods and API
 
 #### Mods that read and change the world
@@ -790,18 +800,6 @@ Issue [#1709](https://github.com/ludovic111/horizon/issues/1709): aarch64 builds
 
 </details>
 
-#### OpenGL for old computers
-
-A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL.
-
-<details><summary>Technical</summary>
-
-Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like the DirectX 12 fallback that already ships.
-
-More: [docs/graphics.md](docs/graphics.md)
-
-</details>
-
 #### Android, iOS and the browser
 
 Versions of Horizon for Android, iOS and web browsers. Nothing official yet; contributors have started the first pieces.
@@ -812,6 +810,16 @@ No official build. Android was first closed as not planned, with touch controls,
 
 </details>
 
+#### AppImage and a Nix flake
+
+Install Horizon on any Linux distribution as an AppImage, and on NixOS through a Nix flake.
+
+<details><summary>Technical</summary>
+
+A player's idea (#horizon-ideas). An AppImage of the launcher and game from the release workflow, and a flake.nix packaging the release binaries with their runtime libraries (Vulkan loader, X11/Wayland, ALSA), the way horizon-parity's NixOS setup runs them today.
+
+</details>
+
 ### Horizon extras
 
 #### A complete video studio inside the game
@@ -824,6 +832,16 @@ Three stages. Recording: capture gameplay in a keypress with an encoder thread a
 
 </details>
 
+#### Game menus in the launcher's style
+
+An optional look for the game's own menus and options that matches the Horizon launcher. Off by default: the vanilla menus stay as they are.
+
+<details><summary>Technical</summary>
+
+A player's idea (#horizon-ideas). A built-in resource pack or a Horizon setting that restyles the title, pause and options screens with the launcher's design tokens (crates/horizon-theme), following [docs/design-system.md](docs/design-system.md); off by default because it changes the vanilla look.
+
+</details>
+
 ### AI and agents
 
 #### An optional AI teammate
@@ -936,6 +954,7 @@ Vanilla's `Chicken.aiStep` updates `flap` and `flapSpeed` when the chicken isn't
 
 ## Recently shipped
 
+- **OpenGL for old computers** (v0.2.63): Horizon now starts on old PCs whose graphics card has no Vulkan or DirectX 12 driver: it switches to OpenGL by itself, and Options > Graphics can pick OpenGL by hand. [#1917](https://github.com/ludovic111/horizon/issues/1917) · [#1920](https://github.com/ludovic111/horizon/issues/1920) · [#1936](https://github.com/ludovic111/horizon/issues/1936)
 - **Server resource packs** (v0.2.48): Servers can send you their resource pack: Horizon asks, downloads it and applies it, like vanilla. [#1562](https://github.com/ludovic111/horizon/issues/1562) · [#1569](https://github.com/ludovic111/horizon/issues/1569) · [#1570](https://github.com/ludovic111/horizon/issues/1570)
 - **Single player on its own server thread** (v0.2.39): Single player runs on a server thread, as vanilla does, so the world keeps ticking smoothly while the window draws. [#1514](https://github.com/ludovic111/horizon/issues/1514) · [docs/server-levels.md](docs/server-levels.md)
 - **GPU occlusion culling on Macs** (v0.2.17): On Macs the GPU now skips terrain hidden behind hills and caves: 8 to 48% more frames per second at 32 chunks on an M4 Pro. [#1434](https://github.com/ludovic111/horizon/issues/1434)
diff --git a/roadmap/roadmap.toml b/roadmap/roadmap.toml
index 34ae8a955..669596fba 100644
--- a/roadmap/roadmap.toml
+++ b/roadmap/roadmap.toml
@@ -968,13 +968,15 @@ links = ["#1709"]
 [[item]]
 id = "opengl-fallback"
 title = "OpenGL for old computers"
-status = "later"
+status = "shipped"
+shipped_in = "v0.2.63"
 area = "platforms"
-plain = "A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL."
-dev = """Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL \
-backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like \
-the DirectX 12 fallback that already ships."""
-links = ["docs/graphics.md"]
+plain = """Horizon now starts on old PCs whose graphics card has no Vulkan or DirectX 12 driver: it switches to OpenGL \
+by itself, and Options > Graphics can pick OpenGL by hand."""
+dev = """wgpu's GL backend (WGL on Windows, EGL on Linux) as the last fallback after Vulkan and DirectX 12 (#1917), \
+sprite arrays and CPU sprite animation for drivers without compute (#1920), no indirect draws below GL 4.3 \
+(#1936). Minimum OpenGL 3.3 core. Shader packs don't run on it yet."""
+links = ["#1917", "#1920", "#1936"]
 
 [[item]]
 id = "phones-and-browser"
@@ -1187,3 +1189,38 @@ plain = """The launcher's Servers page creates, starts, backs up and updates a H
 invites friends."""
 dev = """The launcher's Servers page (#1026) over `horizon-server` (docs/hosting.md)."""
 links = ["#1026", "docs/hosting.md"]
+
+[[item]]
+id = "cli-server-install"
+title = "A server you install with one command"
+status = "next"
+area = "servers"
+plain = """Install and run a Horizon dedicated server from a terminal with a single command, no launcher needed, for \
+VPSes and headless machines."""
+dev = """A player's idea (#horizon-ideas). `horizon-server` already runs headless; left: an install script \
+(Linux/macOS shell, Windows PowerShell) that fetches the signed release, checks it, asks for or points at the \
+player's own game files and starts the server, documented in docs/hosting.md."""
+links = ["docs/hosting.md"]
+
+[[item]]
+id = "launcher-look-menus"
+title = "Game menus in the launcher's style"
+status = "later"
+area = "extras"
+plain = """An optional look for the game's own menus and options that matches the Horizon launcher. Off by default: \
+the vanilla menus stay as they are."""
+dev = """A player's idea (#horizon-ideas). A built-in resource pack or a Horizon setting that restyles the title, \
+pause and options screens with the launcher's design tokens (crates/horizon-theme), following \
+docs/design-system.md; off by default because it changes the vanilla look."""
+links = ["docs/design-system.md"]
+
+[[item]]
+id = "linux-packages"
+title = "AppImage and a Nix flake"
+status = "later"
+area = "platforms"
+plain = """Install Horizon on any Linux distribution as an AppImage, and on NixOS through a Nix flake."""
+dev = """A player's idea (#horizon-ideas). An AppImage of the launcher and game from the release workflow, and a \
+flake.nix packaging the release binaries with their runtime libraries (Vulkan loader, X11/Wayland, ALSA), \
+the way horizon-parity's NixOS setup runs them today."""
+links = []
diff --git a/website/data/roadmap.json b/website/data/roadmap.json
index 4af2a460f..58d697257 100644
--- a/website/data/roadmap.json
+++ b/website/data/roadmap.json
@@ -964,13 +964,16 @@
   {
    "id": "opengl-fallback",
    "title": "OpenGL for old computers",
-   "status": "later",
+   "status": "shipped",
    "area": "platforms",
-   "plain": "A way to play on old PCs and Linux machines that have no Vulkan or DirectX 12, through OpenGL.",
-   "dev": "Players on older hardware ask whether Vulkan is the only way. Horizon draws with wgpu, which has an OpenGL backend; what is needed is to see which features hold up on it, how fast it runs, and a launcher switch like the DirectX 12 fallback that already ships.",
+   "plain": "Horizon now starts on old PCs whose graphics card has no Vulkan or DirectX 12 driver: it switches to OpenGL by itself, and Options > Graphics can pick OpenGL by hand.",
+   "dev": "wgpu's GL backend (WGL on Windows, EGL on Linux) as the last fallback after Vulkan and DirectX 12 (#1917), sprite arrays and CPU sprite animation for drivers without compute (#1920), no indirect draws below GL 4.3 (#1936). Minimum OpenGL 3.3 core. Shader packs don't run on it yet.",
    "links": [
-    "docs/graphics.md"
-   ]
+    "#1917",
+    "#1920",
+    "#1936"
+   ],
+   "shipped_in": "v0.2.63"
   },
   {
    "id": "phones-and-browser",
@@ -1202,6 +1205,37 @@
     "docs/hosting.md"
    ],
    "shipped_in": "launcher-v0.15.0"
+  },
+  {
+   "id": "cli-server-install",
+   "title": "A server you install with one command",
+   "status": "next",
+   "area": "servers",
+   "plain": "Install and run a Horizon dedicated server from a terminal with a single command, no launcher needed, for VPSes and headless machines.",
+   "dev": "A player's idea (#horizon-ideas). `horizon-server` already runs headless; left: an install script (Linux/macOS shell, Windows PowerShell) that fetches the signed release, checks it, asks for or points at the player's own game files and starts the server, documented in docs/hosting.md.",
+   "links": [
+    "docs/hosting.md"
+   ]
+  },
+  {
+   "id": "launcher-look-menus",
+   "title": "Game menus in the launcher's style",
+   "status": "later",
+   "area": "extras",
+   "plain": "An optional look for the game's own menus and options that matches the Horizon launcher. Off by default: the vanilla menus stay as they are.",
+   "dev": "A player's idea (#horizon-ideas). A built-in resource pack or a Horizon setting that restyles the title, pause and options screens with the launcher's design tokens (crates/horizon-theme), following docs/design-system.md; off by default because it changes the vanilla look.",
+   "links": [
+    "docs/design-system.md"
+   ]
+  },
+  {
+   "id": "linux-packages",
+   "title": "AppImage and a Nix flake",
+   "status": "later",
+   "area": "platforms",
+   "plain": "Install Horizon on any Linux distribution as an AppImage, and on NixOS through a Nix flake.",
+   "dev": "A player's idea (#horizon-ideas). An AppImage of the launcher and game from the release workflow, and a flake.nix packaging the release binaries with their runtime libraries (Vulkan loader, X11/Wayland, ALSA), the way horizon-parity's NixOS setup runs them today.",
+   "links": []
   }
  ],
  "journal": [

From 2cdb6362cae1e4d88894f4fda3a4dc3b49ada9bb Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Sun, 25 Oct 2026 22:38:40 +0100
Subject: [PATCH 202/270] Particles keep their sprites over a resource reload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The particle engine copied the GUI atlas's sprite rects once at start; a pack or server-pack
change rebuilt the atlas but not the engine, so every named and set sprite then drew a stale
region — break crumbs showed other blocks and campfire smoke showed random items (#1923).
The engine now re-reads the rects and the packs' sprite sets on reload, and a particle whose
sprite-set index outlived the rebuild keeps its sprite instead of indexing past the new list.
The reload also layers content mods over the root again, which startup does but reload forgot,
so the first reload silently dropped their assets and data.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/packs.rs |  6 ++++
 crates/horizon-client/src/particles.rs  | 46 +++++++++++++++++++------
 2 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/crates/horizon-client/src/game/packs.rs b/crates/horizon-client/src/game/packs.rs
index 7629a5d25..b35eff564 100644
--- a/crates/horizon-client/src/game/packs.rs
+++ b/crates/horizon-client/src/game/packs.rs
@@ -142,6 +142,8 @@ impl Game<'_> {
         }
         let server = &self.server_packs.active;
         let root = startup_root(&vanilla, &self.settings.resource_packs, server)?;
+        let root =
+            super::mods::content_root(&root, &self.settings.mods.enabled, &self.options.dev_mods);
         self.reload_resources(&root)
     }
     fn reload_resources(&mut self, root: &Path) -> horizon_client::Result<()> {
@@ -192,6 +194,10 @@ impl Game<'_> {
         let context = pack.context.clone();
         self.pack = pack;
         self.gui = gui;
+        // The atlas's sprites moved: the particle engine re-reads every rect
+        // and the packs' sprite sets, or every particle draws a stale region.
+        self.particles
+            .reload(root, &self.gui.atlas.sprites, &self.gui.atlas.translucent);
         horizon_client::ui_theme::reset_atlas();
         // Villager hats come from the pack's texture metadata (shared data, swapped in place).
         *self
diff --git a/crates/horizon-client/src/particles.rs b/crates/horizon-client/src/particles.rs
index be7f32551..fa9dc9c6e 100644
--- a/crates/horizon-client/src/particles.rs
+++ b/crates/horizon-client/src/particles.rs
@@ -1212,10 +1212,7 @@ impl ParticleEngine {
             requested: None,
             names: Vec::new(),
             rects: Vec::new(),
-            atlas: atlas
-                .iter()
-                .map(|(name, &rect)| (name.clone(), (rect, translucent.contains(name))))
-                .collect(),
+            atlas: HashMap::new(),
             sets: HashMap::new(),
             set_sprites: Vec::new(),
             emitters: Vec::new(),
@@ -1225,6 +1222,34 @@ impl ParticleEngine {
             made: Default::default(),
             item_sprites: HashMap::new(),
         };
+        engine.reload(root, atlas, translucent);
+        engine
+    }
+    /// `onResourceManagerReload`: sprite rects and sets come from the
+    /// reloaded atlas and pack; a live particle keeps drawing its sprite by
+    /// name or index.
+    pub fn reload(
+        &mut self,
+        root: &Path,
+        atlas: &HashMap<String, Rect>,
+        translucent: &HashSet<String>,
+    ) {
+        self.atlas = atlas
+            .iter()
+            .map(|(name, &rect)| (name.clone(), (rect, translucent.contains(name))))
+            .collect();
+        self.rects = self
+            .names
+            .iter()
+            .map(|name| self.atlas.get(name).map(|&(rect, _)| rect))
+            .collect();
+        self.sets.clear();
+        self.set_sprites.clear();
+        self.item_sprites.clear();
+        self.load_sprites(root);
+    }
+    /// The sprite sets of every `particles/*.json` under `root`.
+    fn load_sprites(&mut self, root: &Path) {
         let dir = root.join("assets/minecraft/particles");
         for &ty in ParticleType::ALL {
             let Ok(bytes) = std::fs::read(dir.join(format!("{}.json", ty.name()))) else {
@@ -1239,18 +1264,16 @@ impl ParticleEngine {
                     a.iter()
                         .filter_map(|t| t.as_str())
                         .map(|t| {
-                            engine
-                                .intern(&format!("particle/{}", t.trim_start_matches("minecraft:")))
+                            self.intern(&format!("particle/{}", t.trim_start_matches("minecraft:")))
                         })
                         .collect()
                 })
                 .unwrap_or_default();
             if !sprites.is_empty() {
-                engine.sets.insert(ty, engine.set_sprites.len() as u32);
-                engine.set_sprites.push(sprites);
+                self.sets.insert(ty, self.set_sprites.len() as u32);
+                self.set_sprites.push(sprites);
             }
         }
-        engine
     }
     fn intern(&mut self, name: &str) -> u32 {
         if let Some(i) = self.names.iter().position(|n| n == name) {
@@ -1601,7 +1624,10 @@ impl ParticleEngine {
             return;
         }
         if let Some(set) = p.set {
-            let sprites = &self.set_sprites[set as usize];
+            // A sprite set's index can outlive the reload that rebuilt them.
+            let Some(sprites) = self.set_sprites.get(set as usize) else {
+                return;
+            };
             let lifetime = p.lifetime.max(1);
             let index = (p.age.max(0) as i64 * (sprites.len() as i64 - 1) / i64::from(lifetime))
                 .clamp(0, sprites.len() as i64 - 1);

From b6efebc87908e113cbf555496e61e61f1c685d16 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 21:39:14 +0000
Subject: [PATCH 203/270] Play anvil result sounds once for every player
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deliver anvil level events to the acting player and keep their local sound out of positional sound capture. Extend the anvil LAN check to count sounds for both players using either player’s anvil result.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 crates/horizon-client/src/game.rs     |  8 +++++++-
 crates/horizon-client/src/game/lan.rs |  6 +++---
 tools/lan_e2e.py                      | 20 +++++++++++++++-----
 3 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f5803ad08..08abb2d2b 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -2764,7 +2764,13 @@ impl Game<'_> {
                             }
                             _ => 1.0,
                         };
-                        self.audio.play(name, c, volume, pitch);
+                        if matches!(id, 1029 | 1030) {
+                            // Clients play the anvil sound from its level event;
+                            // capturing it also sends a duplicate sound packet.
+                            self.audio.play_unshared(name, c, volume, pitch);
+                        } else {
+                            self.audio.play(name, c, volume, pitch);
+                        }
                     }
                 }
                 LevelEvent::Sound {
diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs
index ddb959cf3..9b6754661 100644
--- a/crates/horizon-client/src/game/lan.rs
+++ b/crates/horizon-client/src/game/lan.rs
@@ -1114,9 +1114,9 @@ impl Game<'_> {
         for e in events {
             if let horizon_world::level::LevelEvent::LevelEvent { id, pos, data } = e {
                 // The acting guest does not predict the egg's teleport
-                // particles, nor bone meal's growth (BoneMealItem.useOn's
-                // levelEvent names no player).
-                let except = if matches!(*id, 2015 | 1505) {
+                // particles, bone meal's growth, or anvil result sounds
+                // (these levelEvent calls name no excluded player).
+                let except = if matches!(*id, 2015 | 1505 | 1029 | 1030) {
                     None
                 } else {
                     self.lan_acting
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 0ec7218d8..8e7985862 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -52,9 +52,9 @@ address. The script then checks, from both sides, what a guest's game used to ge
 - grindstone: a grindstone opens on the guest's screen; the enchanted sword the guest shift-clicks in
              shows the server's result, and the guest takes it with only its curse left and the
              experience orbs the server awards (#868);
-- anvil:     an anvil opens on the guest's screen; the guest repairs a sword with iron ingots and
-             renames it (ServerboundRenameItemPacket), takes it for the server's level cost, and the
-             server has the repaired, renamed sword (#868);
+- anvil:     each player repairs and renames a sword (ServerboundRenameItemPacket), takes it for
+             the server's level cost, and the server has the repaired, renamed sword (#868);
+             both players hear exactly one anvil sound for each result (#1907);
 - enchanting: an enchanting table opens on the guest's screen with the server's offers for the
              sword the guest puts in; the guest clicks the first offer and the server enchants the
              sword for a level and a lapis, and counts it in the guest's enchant_item stat (#868);
@@ -1620,6 +1620,12 @@ def check_grindstone(host, guest, out):
 
 
 def check_anvil(host, guest, out):
+    # AnvilMenu.onTake emits one level event to everyone, including the user.
+    # Exercise both the in-frame host and a remote user (both remote with --server-thread).
+    return {actor.name: check_anvil_user(actor, (host, guest), out) for actor in (guest, host)}
+
+
+def check_anvil_user(guest, listeners, out):
     guest('command', command='gamemode survival')
     guest('command', command='clear @s')
     guest('command', command='xp set @s 5 levels')
@@ -1638,8 +1644,12 @@ def check_anvil(host, guest, out):
     menu = guest.raw('menu')
     offered = (menu['info']['anvil_cost'], station_slots(guest).get(650))
     guest.shot(out, 'anvil-rename')
+    sounds = ('minecraft:block.anvil.use', 'minecraft:block.anvil.destroy')
+    before = {g.name: sum(heard(g, s) for s in sounds) for g in listeners}
     guest.raw('click-slot', 650, 'shift')
-    guest.wait(10)
+    guest.wait(20)
+    sound_counts = {g.name: sum(heard(g, s) for s in sounds) - before[g.name] for g in listeners}
+    assert sound_counts == {g.name: 1 for g in listeners}, f'anvil sounds: {sound_counts}'
     left = station_slots(guest)
     close_station(guest, at)
     sword = server_reply(guest, 'data get entity @s Inventory[{id:"minecraft:iron_sword"}].components',
@@ -1653,7 +1663,7 @@ def check_anvil(host, guest, out):
     want = {'offered': (4, ('minecraft:iron_sword', 1)), 'left': {}, 'name': True, 'damage': True,
             'levels': 1, 'ingots': 0}
     assert seen == want, f'the anvil on the guest: {seen} ({sword!r})'
-    return seen
+    return {**seen, 'heard': sound_counts}
 
 
 def check_smithing(host, guest, out):

From acb68ed163deb929e1e64b8abf6f39aa9caa99bf Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:44:56 +0100
Subject: [PATCH 204/270] launcher: reuse prepared resources while the
 preparer's OUTPUT_VERSION is the same

A version's resources were reused only when the preparer's sources and the exporters were
byte for byte the same, so any change to crates/horizon-prepare (even one that prepares the
same files) made every player prepare again. The launcher now compares the number the preparer
declares for what it makes (`pub const OUTPUT_VERSION: u32` in crates/horizon-prepare/src/lib.rs,
bumped by hand when the output changes and checked by CI in the follow-up). Preparers from
before the number are known by a fingerprint of their sources and exporters: v0.2.49 to
v0.2.64 prepare version 1's output (measured on the CI runners' preparations). Older versions
are compared as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 launcher/src/backend.rs | 216 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 205 insertions(+), 11 deletions(-)

diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 7e5c4babb..ce9007868 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -628,17 +628,13 @@ pub fn resources_summary(prepared: bool, sounds: bool, version: &str) -> String
     }
 }
 
-/// Whether the resources `from` prepared are the ones preparing `to` would make. The output
-/// depends on the Horizon version, not only on Minecraft's: the manifest records the hashes of
-/// the vanilla exporters it was made with (mods/horizon/src/test/java/.../parity), and the
-/// preparer writes every file and the manifest's `schema`. So both need the same pinned
-/// Minecraft jars (research-lock.json), the same preparer and the same exporter sources. The
-/// preparer is crates/horizon-prepare (its sources ship in the release folder beside the
-/// binary) and tools/prepare_native_client.py (the Python preparer of older versions, a wrapper
-/// of the binary since); a file only one of the two versions has is a different preparer. The
-/// helpers the Python preparer imported (lab.py and the test_*_parity.py modules) change
-/// between releases in how they find and check the player's files, which the output does not
-/// depend on; they are not compared.
+/// Whether the resources `from` prepared are the ones preparing `to` would make: both pin the same
+/// Minecraft jars (research-lock.json) and their preparers make the same output. A preparer
+/// declares what it makes with `OUTPUT_VERSION` (crates/horizon-prepare/src/lib.rs, whose sources
+/// ship in the release folder), bumped by hand when the output changes and checked by CI
+/// (tools/prepare_output.py), so a release that changes the preparer's code but not its output
+/// keeps the resources. Preparers from before the number are known by their sources
+/// (`LEGACY_OUTPUT_VERSIONS`); older ones still are compared file by file (`same_preparer`).
 fn resources_compatible(from: &Path, to: &Path, manifest: &serde_json::Value) -> bool {
     let pins = |dir: &Path| {
         read_json(&dir.join("research-lock.json")).map(|lock| {
@@ -651,6 +647,108 @@ fn resources_compatible(from: &Path, to: &Path, manifest: &serde_json::Value) ->
     if a != b || a.iter().any(|v| !v.is_string()) {
         return false;
     }
+    match (output_version_at(from), output_version_at(to)) {
+        (Some(a), Some(b)) => a == b,
+        (None, None) => same_preparer(from, to, manifest),
+        _ => false,
+    }
+}
+
+/// The `OUTPUT_VERSION` of a version folder's preparer: the constant in its sources, or for a
+/// preparer from before it, the number `LEGACY_OUTPUT_VERSIONS` gives its fingerprint. None for
+/// an unknown older preparer.
+fn output_version_at(dir: &Path) -> Option<u32> {
+    output_version_in(dir, &LEGACY_OUTPUT_VERSIONS)
+}
+
+fn output_version_in(dir: &Path, legacy: &[(&str, u32)]) -> Option<u32> {
+    let crate_dir = dir.join(PREPARER_CRATE);
+    let lib = fs::read_to_string(crate_dir.join("src/lib.rs")).ok()?;
+    let declared = lib.lines().find_map(|line| {
+        line.strip_prefix("pub const OUTPUT_VERSION: u32 = ")?
+            .strip_suffix(';')?
+            .parse()
+            .ok()
+    });
+    if declared.is_some() {
+        return declared;
+    }
+    let fingerprint = legacy_fingerprint(dir)?;
+    legacy
+        .iter()
+        .find(|(known, _)| *known == fingerprint)
+        .map(|&(_, version)| version)
+}
+
+/// Preparers from before `OUTPUT_VERSION`, by `legacy_fingerprint`, whose output
+/// tools/prepare_output.py measured: what they prepare is version 1's.
+const LEGACY_OUTPUT_VERSIONS: [(&str, u32); 2] = [
+    // v0.2.52 to v0.2.64
+    (
+        "54218ade1c058b1f15ea4094bf8c1a7893adb37b1ed5cc803ddae8e950c31704",
+        1,
+    ),
+    // v0.2.49 to v0.2.51
+    (
+        "da9ffe7558129c38b44abf43289e81946fe9f2512e5e07272eeae0cf0b4f1254",
+        1,
+    ),
+];
+
+/// The vanilla exporters those preparers ran (the `*_exporters_sha256` of their manifests), in
+/// mods/horizon/src/test/java/dev/horizonlab/parity.
+const LEGACY_EXPORTERS: [&str; 18] = [
+    "ParityData.java",
+    "VanillaBlockBehaviourExporter.java",
+    "VanillaBlockLandingOracle.java",
+    "VanillaBlockStateBindingOracle.java",
+    "VanillaCollisionOracle.java",
+    "VanillaCommandParseOracle.java",
+    "VanillaCreativeTabsExporter.java",
+    "VanillaCuboidModelOracle.java",
+    "VanillaDamageSourceOracle.java",
+    "VanillaEntityAttributeOracle.java",
+    "VanillaEntityModelExporter.java",
+    "VanillaEntityTypesExporter.java",
+    "VanillaFaceVisibilityOracle.java",
+    "VanillaGameplayFactsExporter.java",
+    "VanillaHeightmapOracle.java",
+    "VanillaMobDataExporter.java",
+    "VanillaMovementRegistryOracle.java",
+    "VanillaPlayerHealthOracle.java",
+];
+
+/// A version folder's preparer as the launchers before `OUTPUT_VERSION` compared it: the digest
+/// of its sources (`horizon_prepare::sources_sha256`) and of the exporters it ran, line endings
+/// as checked out ignored.
+fn legacy_fingerprint(dir: &Path) -> Option<String> {
+    use sha2::Digest;
+    let sources = horizon_prepare::sources_sha256(&dir.join(PREPARER_CRATE))?;
+    let mut hash = sha2::Sha256::new();
+    hash.update(sources.as_bytes());
+    for name in LEGACY_EXPORTERS {
+        let path = format!("mods/horizon/src/test/java/dev/horizonlab/parity/{name}");
+        let data: Vec<u8> = fs::read(dir.join(&path))
+            .ok()?
+            .into_iter()
+            .filter(|b| *b != b'\r')
+            .collect();
+        hash.update(format!("{path}\0{}\0", data.len()));
+        hash.update(&data);
+    }
+    Some(hash.finalize().iter().map(|b| format!("{b:02x}")).collect())
+}
+
+/// How launchers before `OUTPUT_VERSION` compared two preparers, for versions older than the
+/// ones `LEGACY_OUTPUT_VERSIONS` knows. The manifest records the hashes of the vanilla exporters
+/// the resources were made with (mods/horizon/src/test/java/.../parity), and the preparer writes
+/// every file and the manifest's `schema`, so both need the same preparer and the same exporter
+/// sources. The preparer is crates/horizon-prepare and tools/prepare_native_client.py (the
+/// Python preparer of older versions, a wrapper of the binary since); a file only one of the two
+/// versions has is a different preparer. The helpers the Python preparer imported (lab.py and
+/// the test_*_parity.py modules) change between releases in how they find and check the
+/// player's files, which the output does not depend on; they are not compared.
+fn same_preparer(from: &Path, to: &Path, manifest: &serde_json::Value) -> bool {
     let Some(fields) = manifest.as_object() else {
         return false;
     };
@@ -3150,6 +3248,102 @@ mod tests {
         let _ = fs::remove_dir_all(&versions);
     }
 
+    #[test]
+    fn prepared_resources_follow_the_preparers_output_version() {
+        let versions = std::env::temp_dir().join(format!(
+            "horizon-launcher-output-test-{}",
+            std::process::id()
+        ));
+        let _ = fs::remove_dir_all(&versions);
+        let write = |tag: &str, path: &str, text: &str| {
+            let path = versions.join(tag).join(path);
+            fs::create_dir_all(path.parent().unwrap()).unwrap();
+            fs::write(path, text).unwrap();
+        };
+        let lib = "crates/horizon-prepare/src/lib.rs";
+        // A preparer with its sources (as releases ship them) and the exporters it runs.
+        let release = |tag: &str, code: &str| {
+            write(tag, COMPLETE, "");
+            let lock = serde_json::json!({"minecraft": {"version": "26.3", "client_sha1": "c", "server_sha1": "s"}});
+            write(tag, "research-lock.json", &lock.to_string());
+            write(tag, "crates/horizon-prepare/Cargo.toml", "[package]");
+            write(tag, "crates/horizon-prepare/build.rs", "fn main() {}");
+            write(tag, lib, code);
+            for name in LEGACY_EXPORTERS {
+                write(
+                    tag,
+                    &format!("mods/horizon/src/test/java/dev/horizonlab/parity/{name}"),
+                    name,
+                );
+            }
+        };
+        let prepared = |tag: &str| {
+            write(
+                tag,
+                &format!(".local/horizon-client/26.3/{RESOURCES_MANIFEST}"),
+                r#"{"schema": 7}"#,
+            );
+            write(tag, ".local/horizon-client/26.3/facts.json", tag);
+        };
+        let facts = |tag: &str| {
+            fs::read_to_string(resources_at(&versions.join(tag)).join("facts.json")).ok()
+        };
+
+        // The preparer's code changed, not what it makes: the resources are kept.
+        release(
+            "v0.3.0",
+            "pub const OUTPUT_VERSION: u32 = 1;\nfn prepare() {}",
+        );
+        prepared("v0.3.0");
+        release(
+            "v0.3.1",
+            "pub const OUTPUT_VERSION: u32 = 1;\nfn prepare() { faster() }",
+        );
+        assert_eq!(reuse_prepared(&versions, "v0.3.1"), Some("v0.3.0".into()));
+        assert_eq!(facts("v0.3.1").as_deref(), Some("v0.3.0"));
+        // Its output changed, so the number did: prepare again.
+        release(
+            "v0.3.2",
+            "pub const OUTPUT_VERSION: u32 = 2;\nfn prepare() {}",
+        );
+        assert_eq!(reuse_prepared(&versions, "v0.3.2"), None);
+        assert_eq!(facts("v0.3.2"), None);
+        // Another Minecraft jar, same number: prepare again.
+        release(
+            "v0.3.3",
+            "pub const OUTPUT_VERSION: u32 = 1;\nfn prepare() {}",
+        );
+        let lock = serde_json::json!({"minecraft": {"version": "26.3", "client_sha1": "other", "server_sha1": "s"}});
+        write("v0.3.3", "research-lock.json", &lock.to_string());
+        assert_eq!(reuse_prepared(&versions, "v0.3.3"), None);
+
+        // A preparer from before the number is known by its fingerprint.
+        release("v0.2.64", "fn prepare() {}");
+        let fingerprint = legacy_fingerprint(&versions.join("v0.2.64")).unwrap();
+        let legacy = [(fingerprint.as_str(), 1)];
+        let at = |tag: &str| output_version_in(&versions.join(tag), &legacy);
+        assert_eq!(at("v0.2.64"), Some(1));
+        assert_eq!(at("v0.3.2"), Some(2));
+        // Line endings as checked out don't count; an exporter's or the sources' change does.
+        write(
+            "v0.2.64",
+            "mods/horizon/src/test/java/dev/horizonlab/parity/ParityData.java",
+            "ParityData.java\r",
+        );
+        assert_eq!(at("v0.2.64"), Some(1));
+        write(
+            "v0.2.64",
+            "mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java",
+            "changed",
+        );
+        assert_eq!(at("v0.2.64"), None);
+        release("v0.2.65", "fn prepare() { changed() }");
+        assert_eq!(at("v0.2.65"), None);
+        // A folder without the preparer's sources has no number.
+        assert_eq!(output_version_in(&versions.join("missing"), &legacy), None);
+        let _ = fs::remove_dir_all(&versions);
+    }
+
     #[test]
     fn prepared_versions_get_the_run_time_reports_without_preparing_again() {
         let versions = std::env::temp_dir().join(format!(

From 116a7f7dcafc4e36d14b75600f402446ec8056ac Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:48:43 +0100
Subject: [PATCH 205/270] horizon-prepare: OUTPUT_VERSION, the number of what
 it prepares, checked by CI

Launchers copy a player's prepared resources to a new release while its preparer declares the
same OUTPUT_VERSION (the launcher side is its own pull request). The number is bumped by hand;
CI keeps it honest: the parity job already prepares with every change to the preparer, and
tools/prepare_output.py check now fails when that preparation's digest is not the one
crates/horizon-prepare/output-versions.txt gives the current number, or when the file changed
other than by appending a version. The digest canonicalises what differs between two runs of
the same preparer (JSON key order, creative tab tag order, lambda class addresses, logs, the
sounds): 10 preparations by 5 preparer versions on the three Mac runners give one digest, and a Linux preparation by an older preparer gives the Mac runners' digest for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity.yml               |   4 +
 crates/horizon-prepare/output-versions.txt |   3 +
 crates/horizon-prepare/src/lib.rs          |  32 ++++
 docs/release-flow.md                       |   4 +
 tests/test_prepare_output.py               |  64 ++++++++
 tools/prepare_output.py                    | 176 +++++++++++++++++++++
 6 files changed, 283 insertions(+)
 create mode 100644 crates/horizon-prepare/output-versions.txt
 create mode 100644 tests/test_prepare_output.py
 create mode 100755 tools/prepare_output.py

diff --git a/.github/workflows/parity.yml b/.github/workflows/parity.yml
index a18fc5019..0588c12a3 100644
--- a/.github/workflows/parity.yml
+++ b/.github/workflows/parity.yml
@@ -37,6 +37,10 @@ jobs:
         run: bash tools/ci/runner-env.sh
       - name: Vanilla data, and resources prepared by this preparer
         run: bash tools/ci/vanilla-data.sh
+      - name: The prepared output is the one the preparer's OUTPUT_VERSION says
+        env:
+          BASE_SHA: ${{ inputs.base }}
+        run: python3 tools/prepare_output.py check --cache --base "$BASE_SHA"
       - name: The version constants are the pinned jar's
         run: python3 tools/gen_version_consts.py --check
       - name: The harnesses this change can affect
diff --git a/crates/horizon-prepare/output-versions.txt b/crates/horizon-prepare/output-versions.txt
new file mode 100644
index 000000000..71a531fab
--- /dev/null
+++ b/crates/horizon-prepare/output-versions.txt
@@ -0,0 +1,3 @@
+# OUTPUT_VERSION (src/lib.rs) and the digest of what it prepares (python3 tools/prepare_output.py digest),
+# one line per version, never edited: a change to the prepared files appends the next version.
+1 0a608bf4115a8ed2e2c4f5f2b2609dc10c54e63479af8e56fabaa10af1060389
diff --git a/crates/horizon-prepare/src/lib.rs b/crates/horizon-prepare/src/lib.rs
index c7e443c7d..5ea1121df 100644
--- a/crates/horizon-prepare/src/lib.rs
+++ b/crates/horizon-prepare/src/lib.rs
@@ -31,6 +31,15 @@ pub type Log<'a> = &'a dyn Fn(&str);
 /// The manifest's `schema`: the prepared files' layout, which the launcher compares.
 pub const SCHEMA: i64 = 7;
 
+/// What this preparer makes. The launcher copies a prepared version's resources to a newly installed
+/// version whose preparer has the same number (and the same pinned jars), so a release that changes
+/// this crate without changing its output asks nobody to prepare again. Bump it, and append the new
+/// digest to output-versions.txt, when the prepared files change: CI prepares with every change to
+/// the preparer and fails when the output is not the one output-versions.txt gives this number
+/// (`python3 tools/prepare_output.py check`). The launcher reads this line from the version
+/// folder's sources: keep it on one line, as it is.
+pub const OUTPUT_VERSION: u32 = 1;
+
 /// Digest of this crate's sources (build.rs): the launcher prepares a version in-process when
 /// that version ships these same sources, and runs the version's own binary otherwise.
 pub const SOURCES_SHA256: &str = env!("HORIZON_PREPARE_SOURCES_SHA256");
@@ -1209,6 +1218,29 @@ mod tests {
         fs::remove_dir_all(dir).unwrap();
     }
 
+    #[test]
+    fn output_versions_end_at_the_output_version() {
+        let text = include_str!("../output-versions.txt");
+        let versions: Vec<(u32, &str)> = text
+            .lines()
+            .filter(|l| !l.trim().is_empty() && !l.starts_with('#'))
+            .map(|l| {
+                let (n, digest) = l.split_once(' ').unwrap();
+                (n.parse().unwrap(), digest.trim())
+            })
+            .collect();
+        let numbers: Vec<u32> = versions.iter().map(|v| v.0).collect();
+        assert_eq!(numbers, (1..=OUTPUT_VERSION).collect::<Vec<_>>());
+        for (i, (_, digest)) in versions.iter().enumerate() {
+            assert_eq!(digest.len(), 64);
+            assert!(!versions[..i].iter().any(|(_, d)| d == digest));
+        }
+        // The launcher finds the number with this line in a version folder's sources.
+        let lib = include_str!("lib.rs");
+        let line = format!("pub const OUTPUT_VERSION: u32 = {OUTPUT_VERSION};");
+        assert!(lib.lines().any(|l| l == line));
+    }
+
     #[test]
     fn the_source_digest_is_the_one_build_rs_computed() {
         assert_eq!(
diff --git a/docs/release-flow.md b/docs/release-flow.md
index 4fb0209d9..1413cde01 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -39,6 +39,10 @@ copy is: the Mac mini. Its runner runs as the maintainer's account and keeps its
    depend only on the Minecraft version, are kept once in `shared-local/sounds/<version>/` (copied from a folder
    `horizon-prepare sounds` made from the maintainer's own game; the Mac mini has no official launcher of its own)
    and cloned into each preparation (not linked: vanilla's packs refuse symbolic links), for the audio harnesses.
+   `tools/prepare_output.py check` then compares what was prepared with `crates/horizon-prepare/output-versions.txt`:
+   launchers keep a player's prepared resources across releases whose preparer declares the same `OUTPUT_VERSION`
+   (`crates/horizon-prepare/src/lib.rs`), so a change to the prepared files fails here until it bumps the number
+   and appends the new digest (the error gives both lines).
 3. `tools/parity.py --changed <base sha>` picks the harnesses whose traced dependencies (their script, Python
    modules, Java oracles and every Rust source their probes compile) changed since the merge base, plus any
    harness nothing is recorded about yet, and runs those that have no pass for their current inputs. A change to
diff --git a/tests/test_prepare_output.py b/tests/test_prepare_output.py
new file mode 100644
index 000000000..00c489fbb
--- /dev/null
+++ b/tests/test_prepare_output.py
@@ -0,0 +1,64 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from tools import prepare_output
+
+
+class PrepareOutputTests(unittest.TestCase):
+    def preparation(self, root: Path, files: dict[str, bytes]) -> Path:
+        for rel, data in files.items():
+            path = root / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(data)
+        return root
+
+    def test_what_varies_between_runs_does_not_count(self):
+        manifest = {'schema': 7, 'data_version': 5023, 'render_files_sha256': {'a.json': 'x'}}
+        a = {
+            'horizon-resources.json': json.dumps(manifest).encode(),
+            'render-definitions.json': b'{"a": 1, "b": [1, 2]}',
+            'creative-inventory.json': b'{"tags": [["b", "a"]]}',
+            'block-behaviours.json': b'{"c": "Foo$$Lambda/0x0000012a"}',
+            'export.log': b'run 1',
+            'assets/minecraft/sounds/a.ogg': b'one',
+        }
+        manifest['render_files_sha256'] = {'a.json': 'y'}
+        b = {
+            'horizon-resources.json': json.dumps(manifest).encode(),
+            'render-definitions.json': b'{"b": [1, 2], "a": 1}',
+            'creative-inventory.json': b'{"tags": [["a", "b"]]}',
+            'block-behaviours.json': b'{"c": "Foo$$Lambda/0x00000ff0"}',
+            'export.log': b'run 2',
+            'assets/minecraft/sounds/a.ogg': b'two',
+        }
+        with tempfile.TemporaryDirectory() as tmp:
+            first = prepare_output.digest(self.preparation(Path(tmp) / 'a', a))
+            second = prepare_output.digest(self.preparation(Path(tmp) / 'b', b))
+            self.assertEqual(first, second)
+            # The data does, and so do the manifest's schema and the files there are.
+            (Path(tmp) / 'b/render-definitions.json').write_bytes(b'{"b": [2, 1], "a": 1}')
+            self.assertNotEqual(first, prepare_output.digest(Path(tmp) / 'b'))
+            (Path(tmp) / 'b/render-definitions.json').write_bytes(b'{"b": [1, 2], "a": 1}')
+            (Path(tmp) / 'b/horizon-resources.json').write_text(json.dumps({**manifest, 'schema': 8}))
+            self.assertNotEqual(first, prepare_output.digest(Path(tmp) / 'b'))
+            (Path(tmp) / 'b/horizon-resources.json').write_text(json.dumps(manifest))
+            (Path(tmp) / 'b/new.nbt').write_bytes(b'')
+            self.assertNotEqual(first, prepare_output.digest(Path(tmp) / 'b'))
+
+    def test_the_versions_file_ends_at_the_constant(self):
+        versions = prepare_output.parse_versions('# comment\n1 aa\n2 bb\n')
+        self.assertEqual(versions, [(1, 'aa'), (2, 'bb')])
+        self.assertEqual(prepare_output.problems(versions, 2), [])
+        self.assertTrue(prepare_output.problems(versions, 1))
+        self.assertTrue(prepare_output.problems([(1, 'aa'), (3, 'bb')], 3))
+        self.assertTrue(prepare_output.problems([(1, 'aa'), (2, 'aa')], 2))
+        root = Path(prepare_output.__file__).resolve().parent.parent
+        current = prepare_output.parse_versions((root / prepare_output.VERSIONS).read_text())
+        constant = prepare_output.CONSTANT.search((root / prepare_output.LIB).read_text())
+        self.assertEqual(prepare_output.problems(current, int(constant.group(1))), [])
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tools/prepare_output.py b/tools/prepare_output.py
new file mode 100755
index 000000000..81ed156cb
--- /dev/null
+++ b/tools/prepare_output.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""The prepared output's version: what keeps `OUTPUT_VERSION` (crates/horizon-prepare/src/lib.rs) honest.
+
+The launcher copies a prepared version's resources (`.local/horizon-client/<version>`) to a newly installed
+one when both pin the same Minecraft jars and their preparers declare the same `OUTPUT_VERSION`, so a release
+that changes the preparer's code without changing what it makes asks nobody to prepare again. The number is
+bumped by hand; this tool catches a change to the output without a bump.
+
+crates/horizon-prepare/output-versions.txt lists every `OUTPUT_VERSION` with the digest of what it prepares.
+It only grows: the last line is the current version, and a change to the output appends a line.
+
+    python3 tools/prepare_output.py digest [RESOURCES]          the digest of a preparation
+    python3 tools/prepare_output.py check [--base SHA] [--cache] [RESOURCES]
+        fails when RESOURCES (default: this checkout's .local/horizon-client/<version>, as CI prepares it) is
+        not what the last line says, or when the file changed other than by appending since SHA. --cache keeps
+        the digest beside RESOURCES (CI: a preparation never changes once made; it takes ~30 s to compute)
+
+The digest covers every file of the preparation, canonicalised where the preparer is not deterministic between
+runs (verified across the CI runners): JSON is compared as data (key order, the order of each `tags` list of
+creative-inventory.json, and the addresses in `$$Lambda/0x...` class names don't count); logs, compiled classes,
+the sounds (copied from the player's launcher by another step) and the manifest's file hashes (raw bytes) don't
+count. The manifest's own scalar fields (schema, data version, jar hashes, file count) do.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+VERSIONS = 'crates/horizon-prepare/output-versions.txt'
+LIB = 'crates/horizon-prepare/src/lib.rs'
+MANIFEST = 'horizon-resources.json'
+LAMBDA = re.compile(r'\$\$Lambda/0x[0-9a-fA-F]+')
+CONSTANT = re.compile(r'^pub const OUTPUT_VERSION: u32 = (\d+);', re.M)
+
+
+def canonical_json(value, key=''):
+    if isinstance(value, dict):
+        return {k: canonical_json(v, k) for k, v in value.items()}
+    if isinstance(value, list):
+        items = [canonical_json(v, key) for v in value]
+        if key == 'tags' and all(isinstance(x, list) and all(isinstance(t, str) for t in x) for x in items):
+            items = [sorted(x) for x in items]
+        return items
+    if isinstance(value, str):
+        return LAMBDA.sub('$$Lambda', value)
+    return value
+
+
+def canonical(rel: str, data: bytes) -> bytes:
+    if rel == MANIFEST:
+        manifest = json.loads(data)
+        scalars = {k: v for k, v in manifest.items() if not isinstance(v, (dict, list))}
+        return json.dumps(scalars, sort_keys=True).encode()
+    if rel.endswith('.json'):
+        try:
+            value = json.loads(data)
+        except ValueError:
+            return data
+        return json.dumps(canonical_json(value), sort_keys=True).encode()
+    return data
+
+
+def skipped(rel: str) -> bool:
+    parts = rel.split('/')
+    return rel.endswith(('.log', '.class')) or parts[:3] == ['assets', 'minecraft', 'sounds'] \
+        or rel == 'assets/minecraft/sounds.json'
+
+
+def digest(resources: Path) -> tuple[str, int]:
+    """The digest of a preparation, and how many files it covers."""
+    if not (resources / MANIFEST).is_file():
+        raise SystemExit(f'{resources} is not a preparation: no {MANIFEST}')
+    files = []
+    for dirpath, dirs, names in os.walk(resources):
+        dirs.sort()
+        for name in names:
+            path = Path(dirpath) / name
+            rel = path.relative_to(resources).as_posix()
+            if path.is_symlink() or skipped(rel):
+                continue
+            files.append(rel)
+    total = hashlib.sha256()
+    for rel in sorted(files):
+        data = hashlib.sha256(canonical(rel, (resources / rel).read_bytes())).hexdigest()
+        total.update(f'{rel}\0{data}\n'.encode())
+    return total.hexdigest(), len(files)
+
+
+def parse_versions(text: str) -> list[tuple[int, str]]:
+    out = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        number, value = line.split()
+        out.append((int(number), value))
+    return out
+
+
+def problems(versions: list[tuple[int, str]], constant: int | None) -> list[str]:
+    found = []
+    if not versions:
+        return [f'{VERSIONS} lists no version']
+    if [n for n, _ in versions] != list(range(1, len(versions) + 1)):
+        found.append(f'{VERSIONS}: the versions must be 1, 2, 3... in order')
+    if len({d for _, d in versions}) != len(versions):
+        found.append(f'{VERSIONS}: two versions with the same digest')
+    if constant != versions[-1][0]:
+        found.append(f'{LIB} says OUTPUT_VERSION = {constant}, {VERSIONS} ends at {versions[-1][0]}')
+    return found
+
+
+def default_resources() -> Path:
+    lock = json.loads((ROOT / 'research-lock.json').read_text())
+    return ROOT / '.local/horizon-client' / lock['minecraft']['version']
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split('\n\n')[0])
+    parser.add_argument('command', choices=['digest', 'check'])
+    parser.add_argument('resources', nargs='?', type=Path)
+    parser.add_argument('--base', help='the commit the change is based on (check: the file only grew since)')
+    parser.add_argument('--cache', action='store_true', help='keep the digest beside the preparation')
+    args = parser.parse_args()
+    resources = (args.resources or default_resources()).resolve()
+    tool = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()[:16]
+    cache = resources.parent / f'.output-digest-{resources.name}-{tool}'
+    if args.cache and cache.is_file():
+        value, count = cache.read_text().split()
+    else:
+        value, count = digest(resources)
+        if args.cache:
+            cache.write_text(f'{value} {count}\n')
+    if args.command == 'digest':
+        print(value)
+        return 0
+
+    versions = parse_versions((ROOT / VERSIONS).read_text())
+    match = CONSTANT.search((ROOT / LIB).read_text())
+    found = problems(versions, int(match.group(1)) if match else None)
+    if args.base:
+        shown = subprocess.run(['git', 'show', f'{args.base}:{VERSIONS}'], cwd=ROOT, capture_output=True, text=True)
+        if shown.returncode == 0:
+            before = parse_versions(shown.stdout)
+            if versions[:len(before)] != before:
+                found.append(f'{VERSIONS} changed lines it already had (since {args.base[:12]}): '
+                             'a new output gets a new version, appended')
+    current = versions[-1] if versions else (0, '')
+    if value != current[1]:
+        known = [n for n, d in versions if d == value]
+        if known:
+            found.append(f'the preparation is OUTPUT_VERSION {known[0]}\'s output, but OUTPUT_VERSION is {current[0]}')
+        else:
+            found.append(
+                f'the prepared output changed ({count} files, digest {value}) but OUTPUT_VERSION is still '
+                f'{current[0]}. Players would keep resources prepared by the old preparer. Bump it:\n'
+                f'  set `pub const OUTPUT_VERSION: u32 = {current[0] + 1};` in {LIB}\n'
+                f'  append `{current[0] + 1} {value}` to {VERSIONS}\n'
+                '  (if the change is only a nondeterminism this tool should ignore, teach canonical() instead)')
+    for problem in found:
+        print(f'::error::{problem}' if os.environ.get('GITHUB_ACTIONS') else f'error: {problem}', file=sys.stderr)
+    if not found:
+        print(f'prepared output: OUTPUT_VERSION {current[0]} ({count} files, {value[:16]})')
+    return 1 if found else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

From 0b49da246674bef76848ffe3ecb7517db48f0faf Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:07:58 +0000
Subject: [PATCH 206/270] Fix lead drops when leashed mobs die

Follow Leashable.tickLeash for dying mobs and cover trader/player-held llama leads through the death animation.

Co-Authored-By: Codex <noreply@openai.com>
---
 .../examples/probe/mob_ai_probe.rs               | 16 ++++++++++++++++
 crates/horizon-client/src/game/leads.rs          |  2 ++
 crates/horizon-client/src/mobs/leash.rs          |  9 +++++++++
 .../horizonlab/parity/VanillaMobAiOracle.java    |  8 ++++++++
 tools/test_mob_ai_parity.py                      | 15 ++++++++++++++-
 5 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/examples/probe/mob_ai_probe.rs b/crates/horizon-client/examples/probe/mob_ai_probe.rs
index 157baa74c..49f56c250 100644
--- a/crates/horizon-client/examples/probe/mob_ai_probe.rs
+++ b/crates/horizon-client/examples/probe/mob_ai_probe.rs
@@ -598,6 +598,7 @@ fn print(out: &mut String, t: i32, i: usize, m: &Mob, player_down: bool, now: i6
         let _ = writeln!(out, " removed {reason}");
         return;
     }
+    let _ = write!(out, "\tleashed {}", u8::from(m.extra.leash.is_some()));
     let p = m.position;
     let v = m.velocity;
     let _ = write!(
@@ -977,6 +978,7 @@ pub fn main() -> horizon_client::Result<()> {
                     }
                     // Set once the brain exists (below).
                     x if x.starts_with("cooldown=") => {}
+                    "dead" => m.health = 0.0,
                     "leashed" => m.extra.leash = Some(horizon_client::mobs::leash::Holder::Player),
                     x if x.starts_with("leashto=") => {
                         let n: u32 = x[8..].parse().unwrap();
@@ -1097,6 +1099,7 @@ pub fn main() -> horizon_client::Result<()> {
                 }
             };
         }
+        let mut dropped_leads = 0;
         for t in 1..=s.ticks {
             world.game_time += 1;
             if s.daycycle {
@@ -1208,6 +1211,16 @@ pub fn main() -> horizon_client::Result<()> {
                 if !alive {
                     m.removed = true;
                 }
+                // Apply the same detach/drop event as Game::break_leash.
+                for event in &events[from..] {
+                    if let MobEvent::LeashBreak { mob, drop, .. } = event
+                        && let Some(m) = mobs.iter_mut().find(|m| m.id == *mob)
+                        && horizon_client::mobs::leash::remove(m).is_some()
+                        && *drop
+                    {
+                        dropped_leads += 1;
+                    }
+                }
                 horizon_client::mobs::apply_brain_events(&mut mobs, &mut events, from);
                 villager_events(
                     &mut mobs,
@@ -1427,6 +1440,9 @@ pub fn main() -> horizon_client::Result<()> {
                     world.game_time,
                 );
             }
+            if s.name.starts_with("leash_death_") {
+                let _ = writeln!(out, "{t} leads {dropped_leads}");
+            }
             for e in &events {
                 if let MobEvent::Sound(name, _, volume, pitch) = e {
                     let _ = writeln!(
diff --git a/crates/horizon-client/src/game/leads.rs b/crates/horizon-client/src/game/leads.rs
index 3a5112967..8867157ee 100644
--- a/crates/horizon-client/src/game/leads.rs
+++ b/crates/horizon-client/src/game/leads.rs
@@ -79,6 +79,8 @@ impl Game<'_> {
         if horizon_client::mobs::leash::remove(m).is_none() {
             return;
         }
+        // Leashable.tickLeash gates a dying entity's lead drop on entity_drops.
+        let drop = drop && (m.alive() || self.ui.rules.bool("entity_drops"));
         let at = [m.position.x, m.position.y, m.position.z];
         if sound {
             self.lead_sound("break", at);
diff --git a/crates/horizon-client/src/mobs/leash.rs b/crates/horizon-client/src/mobs/leash.rs
index b7c5011ba..3bd0513d7 100644
--- a/crates/horizon-client/src/mobs/leash.rs
+++ b/crates/horizon-client/src/mobs/leash.rs
@@ -198,6 +198,15 @@ pub fn tick(m: &mut Mob, w: &MobWorld, events: &mut Vec<MobEvent>) {
         m.extra.leash_spin = 0.0;
         return;
     };
+    // Leashable.tickLeash: a dying entity cannot interact with the level.
+    if !m.alive() {
+        events.push(MobEvent::LeashBreak {
+            mob: m.id,
+            drop: true,
+            sound: false,
+        });
+        return;
+    }
     let Some(state) = holder_state(w, holder) else {
         // The holder is gone: the lead drops.
         if !matches!(holder, Holder::Player) {
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaMobAiOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaMobAiOracle.java
index 5808fec0d..eb5235adf 100644
--- a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaMobAiOracle.java
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaMobAiOracle.java
@@ -604,6 +604,7 @@ public final class VanillaMobAiOracle {
                         case "tame" -> { if (mob instanceof net.minecraft.world.entity.animal.equine.AbstractHorse horse) horse.setTamed(true); }
                         case "strength" -> method(net.minecraft.world.entity.animal.equine.Llama.class, "setStrength", int.class)
                             .invoke(mob, Integer.parseInt(v));
+                        case "dead" -> mob.setHealth(0.0F);
                         case "leashed", "leashto" -> {
                             // Leashed once every mob exists (below).
                         }
@@ -807,6 +808,12 @@ public final class VanillaMobAiOracle {
                 for (BlockPos h : heartPositions) printHeart(t, level, h);
                 for (String[] b : s.blocks) if (b[0].equals("chest")) printChest(t, s, level, b);
                 for (String[] b : s.blocks) if (isHive(b)) printHive(t, level, b);
+                if (s.name.startsWith("leash_death_")) {
+                    int leads = level.getEntitiesOfClass(ItemEntity.class, ENTS.get(0).getBoundingBox().inflate(32.0),
+                        item -> item.getItem().is(net.minecraft.world.item.Items.LEAD))
+                        .stream().mapToInt(item -> item.getItem().getCount()).sum();
+                    out.println(t + " leads " + leads);
+                }
                 for (String sound : SOUNDS) out.println(t + " sound " + sound);
                 for (var w : watched.entrySet()) {
                     BlockState now = level.getBlockState(w.getKey());
@@ -1008,6 +1015,7 @@ public final class VanillaMobAiOracle {
                 return;
             }
             Mob m = (Mob) e;
+            sb.append("\tleashed ").append(((net.minecraft.world.entity.Leashable) m).isLeashed() ? 1 : 0);
             sb.append("\tp ").append(d(m.getX())).append(',').append(d(m.getY())).append(',').append(d(m.getZ()));
             Vec3 v = m.getDeltaMovement();
             sb.append("\tv ").append(d(v.x)).append(',').append(d(v.y)).append(',').append(d(v.z));
diff --git a/tools/test_mob_ai_parity.py b/tools/test_mob_ai_parity.py
index 3e6ce74df..87a7a1403 100644
--- a/tools/test_mob_ai_parity.py
+++ b/tools/test_mob_ai_parity.py
@@ -191,6 +191,16 @@ def scenarios():
                                'mob minecraft:wandering_trader 0.5 -60 0.5 0 104 persistent',
                                'mob minecraft:trader_llama 3.5 -60 1.5 0 105 persistent leashto=0 strength=2',
                                'mob minecraft:trader_llama 3.5 -60 -1.5 0 106 persistent leashto=0 strength=4'])
+    # Death must detach immediately and drop exactly one lead throughout the corpse animation.
+    add('leash_death_trader_llama', 10, [
+        'player 14.5 -60 0.5',
+        'mob minecraft:wandering_trader 0.5 -60 0.5 0 104 persistent',
+        'mob minecraft:trader_llama 3.5 -60 1.5 0 105 persistent leashto=0 strength=2 dead',
+    ])
+    add('leash_death_player_llama', 10, [
+        'player 0.5 -60 0.5',
+        'mob minecraft:llama 3.5 -60 0.5 0 101 persistent leashed strength=3 dead',
+    ])
     # Copper golems sorting chests (TransportItemsBetweenContainers): from a copper chest to a chest,
     # skipping a chest without the carried item, queueing at a chest another golem has open, a double
     # chest, a blocked copper chest, a part-full chest, and idling with nothing to carry.
@@ -358,6 +368,9 @@ def parse(path):
         if parts[1] == 'hive':
             cur.setdefault('hives', {}).setdefault(t, []).append(parts[2])
             continue
+        if parts[1] == 'leads':
+            cur.setdefault('leads', {}).setdefault(t, []).append(parts[2])
+            continue
         if parts[1] == 'chest':
             cur.setdefault('chests', {}).setdefault(t, []).append(parts[2])
             continue
@@ -455,7 +468,7 @@ def compare(vanilla, rust, fields=None):
                 clean = False
                 break
         # Sounds, watched block changes, chest contents and hives: first differing tick.
-        for kind in ('sounds', 'blocks', 'chests', 'hives'):
+        for kind in ('sounds', 'blocks', 'chests', 'hives', 'leads'):
             va, ra = v.get(kind, {}), r.get(kind, {})
             for t in sorted(set(va) | set(ra)):
                 if va.get(t, []) != ra.get(t, []):

From e3bd6266884838537ed7579f3a9b58c7adbc1127 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:08:15 +0100
Subject: [PATCH 207/270] Mod API: what the extras need as mods: corner panels,
 frame stats, mappings, buttons

The built-in extras become official mods; these are the calls the FPS
counter and keystrokes overlay need to look and behave the same:

- render.set-corner(corner, w, h, shapes): a box the game places with
  its own corner stacking (under the status effects, with the overlays
  and hud panels), clear-corner; text-width(text) in the HUD font
  (advances for U+0000..U+024F, 6 otherwise); frame-stats(): the game's
  FPS counter (fps, min, 1% low).
- input.mapping(name): a movement or click mapping's key label and
  whether it is held; clicks-per-second() for attack and use.
- ui: a button widget (200 x 20, select(id, 0)) for settings pages.
- The game keeps its FPS and click counters running while a mod runs,
  and refreshes the snapshot every frame for mods with a frame hook.
- The ui test guest gains /corner and /readings, with a sandbox test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/cargo-horizon-mod/src/check.rs         |   2 +-
 crates/horizon-client/src/game/extras.rs      |  20 ++-
 crates/horizon-client/src/game/mod_render.rs  |  28 ++--
 crates/horizon-client/src/game/mods.rs        | 102 ++++++++++++-
 crates/horizon-mod-sdk/wit/horizon.wit        |  52 +++++++
 crates/horizon-mods/src/runtime.rs            | 139 ++++++++++++++----
 crates/horizon-mods/tests/sandbox.rs          |  46 +++++-
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  64 +++++++-
 docs/api/mods-reference.md                    |  46 +++++-
 docs/api/mods.md                              |   2 +
 docs/mods.md                                  |   6 +-
 11 files changed, 447 insertions(+), 60 deletions(-)

diff --git a/crates/cargo-horizon-mod/src/check.rs b/crates/cargo-horizon-mod/src/check.rs
index 87ae3c982..b22c0eeaf 100644
--- a/crates/cargo-horizon-mod/src/check.rs
+++ b/crates/cargo-horizon-mod/src/check.rs
@@ -200,7 +200,7 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
             }),
             // The GUI of a 1280 x 720 window at scale 3.
             gui_size: (427.0, 240.0),
-            held: None,
+            ..Snapshot::default()
         });
         mods.tick(t);
         for _ in 0..FRAMES_PER_TICK {
diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index cee173fda..4664f0c6f 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -70,7 +70,8 @@ impl Game<'_> {
             _ => return,
         };
         self.extras.mouse[i] = pressed;
-        if pressed && self.settings.extras.keystrokes {
+        // Mods read the clicks too (`input.clicks-per-second`).
+        if pressed && (self.settings.extras.keystrokes || self.mods.running()) {
             let now = self.extras_now();
             self.extras.cps[i].click(now);
         }
@@ -87,13 +88,28 @@ impl Game<'_> {
             self.extras.mouse = [false; 2];
         }
         self.update_minimap();
-        if self.settings.extras.fps {
+        // Mods read the counter too (`render.frame-stats`).
+        if self.settings.extras.fps || self.mods.running() {
             let now = self.extras_now();
             self.extras.fps.record(now, elapsed.as_secs_f32() * 1000.0);
         } else {
             self.extras.fps.clear();
         }
     }
+    /// The frame counter for mods: fps, min, 1% low.
+    #[cfg(feature = "mods")]
+    pub(super) fn frame_reading(&self) -> (u32, u32, u32) {
+        let r = self.extras.fps.reading();
+        (r.fps, r.min, r.low)
+    }
+    /// Attack and use clicks in the last second, and whether each is held.
+    #[cfg(feature = "mods")]
+    pub(super) fn mouse_reading(&mut self) -> ((u32, u32), [bool; 2]) {
+        let now = self.extras_now();
+        let [l, r] = &mut self.extras.cps;
+        let cps = (l.per_second(now) as u32, r.per_second(now) as u32);
+        (cps, self.extras.mouse)
+    }
     /// Auto-reconnect: a connection to `address` as `name` starts.
     pub(super) fn extras_connecting(&mut self, address: &str, name: &str) {
         self.extras.reconnect.connecting(address, name);
diff --git a/crates/horizon-client/src/game/mod_render.rs b/crates/horizon-client/src/game/mod_render.rs
index 1c3a20621..931aec641 100644
--- a/crates/horizon-client/src/game/mod_render.rs
+++ b/crates/horizon-client/src/game/mod_render.rs
@@ -86,23 +86,29 @@ impl Game<'_> {
 impl Game<'_> {
     /// The running mods' HUD shapes, in order, over the HUD.
     pub(super) fn draw_mod_shapes(&self, batch: &mut HudBatch) {
-        let atlas = &self.gui.atlas;
         for shape in self.mods.mods.hud_shapes() {
+            self.draw_shapes(batch, std::slice::from_ref(shape), (0.0, 0.0));
+        }
+    }
+    /// Shapes with their GUI coordinates moved by `(ox, oy)`.
+    pub(super) fn draw_shapes(&self, batch: &mut HudBatch, shapes: &[Shape], (ox, oy): (f32, f32)) {
+        let atlas = &self.gui.atlas;
+        for shape in shapes {
             match shape {
                 Shape::Fill(f) => {
                     let r = f.rect;
-                    batch.fill(atlas, r.x, r.y, r.w, r.h, argb(f.color));
+                    batch.fill(atlas, ox + r.x, oy + r.y, r.w, r.h, argb(f.color));
                 }
                 Shape::Quad(q) => {
                     let (a, b, c, d) = q.corners;
-                    let corners = [[a.x, a.y], [b.x, b.y], [c.x, c.y], [d.x, d.y]];
+                    let corners = [a, b, c, d].map(|p| [ox + p.x, oy + p.y]);
                     batch.fill_quad(atlas, corners, argb(q.color));
                 }
                 Shape::Sprite(s) => {
                     let r = s.rect;
                     let name = s.sprite.strip_prefix("minecraft:").unwrap_or(&s.sprite);
                     let name = format!("gui/sprites/{name}");
-                    batch.sprite_scaled(atlas, &name, r.x, r.y, r.w, r.h, argb(s.color));
+                    batch.sprite_scaled(atlas, &name, ox + r.x, oy + r.y, r.w, r.h, argb(s.color));
                 }
                 Shape::Item(i) => {
                     if self.res.items().get(&i.item).is_none() {
@@ -110,21 +116,23 @@ impl Game<'_> {
                     }
                     let start = batch.vertices.len();
                     let stack = ItemStack::new(i.item.as_str(), 1);
-                    self.draw_item_model(batch, &stack, i.at.x, i.at.y);
-                    batch.scale_since(start, i.at.x, i.at.y, i.scale, i.scale);
+                    let (x, y) = (ox + i.at.x, oy + i.at.y);
+                    self.draw_item_model(batch, &stack, x, y);
+                    batch.scale_since(start, x, y, i.scale, i.scale);
                 }
                 Shape::Text(t) => {
                     let text = Text::literal(t.text.clone());
-                    let x = if t.centered {
-                        t.at.x - (HudBatch::text_width(atlas, &t.text) / 2.0).floor()
+                    let centre = if t.centered {
+                        (HudBatch::text_width(atlas, &t.text) / 2.0).floor()
                     } else {
-                        t.at.x
+                        0.0
                     };
+                    let x = ox + t.at.x - centre;
                     batch.text_styled(
                         atlas,
                         &text,
                         x,
-                        t.at.y,
+                        oy + t.at.y,
                         argb(t.color | 0xFF00_0000),
                         t.shadow,
                     );
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 1c62046ea..9d6015ad7 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -21,6 +21,7 @@ use {
         extras::Corner,
         extras_hud,
         items::ItemStack,
+        keybinds,
         mod_list::Installed,
         options_ui::Page,
         text::{self, Text},
@@ -51,8 +52,32 @@ pub(super) struct ModsState {
     /// A `ui` mod's screen or settings page while it is up.
     #[cfg(feature = "mods")]
     screen: Option<ModScreen>,
+    /// The HUD font's advances for `render.text-width`, made once.
+    #[cfg(feature = "mods")]
+    font_widths: std::sync::Arc<[f32]>,
 }
 
+/// The mappings `input.mapping` answers for, with the default key their
+/// binding is translated to (none: a mouse button, attack or use).
+#[cfg(feature = "mods")]
+const MAPPINGS: [(&str, Option<winit::keyboard::KeyCode>); 9] = {
+    use winit::keyboard::KeyCode as K;
+    [
+        ("key.forward", Some(K::KeyW)),
+        ("key.left", Some(K::KeyA)),
+        ("key.back", Some(K::KeyS)),
+        ("key.right", Some(K::KeyD)),
+        ("key.jump", Some(K::Space)),
+        ("key.sneak", Some(K::ShiftLeft)),
+        ("key.sprint", Some(K::ControlLeft)),
+        ("key.attack", None),
+        ("key.use", None),
+    ]
+};
+/// Characters `render.text-width` knows exactly: U+0000 to U+024F.
+#[cfg(feature = "mods")]
+const FONT_CHARS: u32 = 0x250;
+
 /// A `ui` mod's own screen, or its settings page from Options > Mods: the
 /// widgets the mod pushed, laid out and drawn with the menus' own widgets.
 #[cfg(feature = "mods")]
@@ -83,10 +108,10 @@ impl ModsState {
         }
         false
     }
-    /// Whether a mod draws a HUD panel.
+    /// Whether a mod draws a HUD panel or a corner panel.
     pub(super) fn has_panels(&self) -> bool {
         #[cfg(feature = "mods")]
-        if self.mods.panels().next().is_some() {
+        if self.mods.panels().next().is_some() || self.mods.corner_panels().next().is_some() {
             return true;
         }
         false
@@ -298,8 +323,8 @@ impl Game<'_> {
             self.start_mods();
         }
     }
-    /// What mods read this tick.
-    fn mod_snapshot(&self) -> Snapshot {
+    /// What mods read this tick (or frame, for mods with a `frame` hook).
+    fn mod_snapshot(&mut self) -> Snapshot {
         let player = self.player.as_ref().map(|p| Player {
             x: p.position.x,
             y: p.position.y,
@@ -314,11 +339,35 @@ impl Game<'_> {
             game_time: self.world.game_time.max(0) as u64,
             day_time: self.world.day_time.max(0) as u64,
         });
+        let (cps, mouse) = self.mouse_reading();
+        // The movement and click mappings, as the keystroke overlay reads them:
+        // keys by the default key their binding is translated to.
+        let mappings = MAPPINGS
+            .iter()
+            .map(|&(name, key)| {
+                let label = keybinds::display_name(self.settings.keys.get(name)).plain();
+                let down = match key {
+                    Some(k) => self.keys.contains(&k),
+                    None => mouse[usize::from(name == "key.use")],
+                };
+                (name, label, down)
+            })
+            .collect();
+        if self.mods.font_widths.is_empty() {
+            let atlas = &self.gui.atlas;
+            self.mods.font_widths = (0..FONT_CHARS)
+                .map(|c| char::from_u32(c).map_or(6.0, |c| atlas.glyph_cell(c).1))
+                .collect();
+        }
         Snapshot {
             player,
             clock,
             gui_size: self.gui_size(),
             held: self.mod_held(),
+            frame: self.frame_reading(),
+            mappings,
+            cps,
+            font_widths: self.mods.font_widths.clone(),
         }
     }
     /// A game tick.
@@ -350,6 +399,10 @@ impl Game<'_> {
         if !self.mods.mods.is_running() {
             return;
         }
+        if self.mods.mods.wants_frames() {
+            let snapshot = self.mod_snapshot();
+            self.mods.mods.set_snapshot(snapshot);
+        }
         self.mods.mods.frame(elapsed.as_secs_f32());
         self.show_mod_output();
     }
@@ -438,6 +491,20 @@ impl Game<'_> {
                 .collect();
             extras_hud::draw_lines(batch, &self.gui.atlas, corners, corner, &lines);
         }
+        // Capability `render`'s corner panels, placed the same way.
+        for panel in self.mods.mods.corner_panels() {
+            let corner = match panel.corner {
+                horizon_mods::RenderCorner::TopLeft => Corner::TopLeft,
+                horizon_mods::RenderCorner::TopRight => Corner::TopRight,
+                horizon_mods::RenderCorner::BottomLeft => Corner::BottomLeft,
+                horizon_mods::RenderCorner::BottomRight => Corner::BottomRight,
+            };
+            if self.debug && corner == Corner::TopLeft {
+                continue;
+            }
+            let at = corners.place(corner, panel.width, panel.height);
+            self.draw_shapes(batch, &panel.shapes, at);
+        }
     }
 
     /// A `ui` screen's title and widgets as the mod last pushed them; None
@@ -470,7 +537,7 @@ impl Game<'_> {
         for w in widgets {
             let wh = match w {
                 UiWidget::Text(_) => 12.0,
-                UiWidget::Item(_) => 20.0,
+                UiWidget::Item(_) | UiWidget::Button(_) => 20.0,
                 UiWidget::List(l) => (l.rows.len().min(6) as f32 * 12.0) + 8.0,
             };
             // Nothing may cover Done; a crowded mod loses what won't fit.
@@ -559,6 +626,21 @@ impl Game<'_> {
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             match w {
+                UiWidget::Button(b) => {
+                    let hover = ui::hovered(self.cursor, x, wy, MOD_UI_COLUMN, 20.0);
+                    let label = Text::literal(b.label.clone());
+                    ui::button(
+                        batch,
+                        atlas,
+                        x,
+                        wy,
+                        MOD_UI_COLUMN,
+                        20.0,
+                        &label,
+                        true,
+                        hover,
+                    );
+                }
                 UiWidget::Text(t) => {
                     let color = if t.color == 0 {
                         u32::MAX
@@ -678,6 +760,16 @@ impl Game<'_> {
         let layout = self.mod_ui_layout(h, &widgets);
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
+            // A button is `select(id, 0)`.
+            if let UiWidget::Button(b) = w
+                && ui::hovered(cursor, x, wy, MOD_UI_COLUMN, 20.0)
+            {
+                self.audio.play_button_click();
+                let owner = self.mods.screen.as_ref().map_or(0, |ms| ms.owner);
+                self.mods.mods.ui_select(owner, b.id, 0);
+                self.show_mod_output();
+                return;
+            }
             let UiWidget::List(l) = w else { continue };
             let scroll = self
                 .mods
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 1560ec3a7..b787ff675 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -120,9 +120,20 @@ interface ui {
         selected: option<u32>,
     }
     /// A thing on a mod's screen or settings page.
+    /// A button as the options pages have them (200 × 20): a click is
+    /// `ui-events::select(id, 0)`. Mods cycle its label for a choice
+    /// ("Corner: Top Left").
+    record button-widget {
+        /// The mod's own name for the widget.
+        id: u32,
+        /// Up to 256 characters.
+        label: string,
+    }
     variant widget {
         /// Text the player reads.
         text(text-widget),
+        /// A button.
+        button(button-widget),
         /// An item's icon and name.
         item(item-widget),
         /// Rows the player picks from.
@@ -203,6 +214,20 @@ interface input {
     held: func() -> option<held-item>;
     /// The events since the last call, oldest first.
     poll: func() -> list<event>;
+    /// A mapping as the player has bound it.
+    record mapping-state {
+        /// The bound key's name as Controls shows it: `W`, `Space`, `LMB`.
+        label: string,
+        /// Held down now (as of this frame for a mod with a `frame` hook,
+        /// else this tick).
+        down: bool,
+    }
+    /// A movement or click mapping as the player has bound it: `key.forward`,
+    /// `key.left`, `key.back`, `key.right`, `key.jump`, `key.sneak`,
+    /// `key.sprint`, `key.attack` or `key.use`. None for another name.
+    mapping: func(name: string) -> option<mapping-state>;
+    /// Clicks of the attack and use buttons in the last second.
+    clicks-per-second: func() -> tuple<u32, u32>;
 }
 
 /// Capability `render` (experimental: the manifest needs
@@ -210,6 +235,13 @@ interface input {
 /// own renderer, kept until the mod replaces them (no call per frame). A mod
 /// never supplies shader code.
 interface render {
+    /// A corner of the screen, as `hud`'s panels use them.
+    enum corner {
+        top-left,
+        top-right,
+        bottom-left,
+        bottom-right,
+    }
     /// A rectangle in GUI pixels: the top left corner and the size.
     record rect {
         x: f32,
@@ -279,6 +311,26 @@ interface render {
     /// turns, the player doesn't, and the player's Distortion Effects option
     /// scales it (0 turns it off).
     shake: func(strength: f32, seconds: f32);
+    /// Replaces the mod's corner panel: shapes in GUI pixels from the top
+    /// left of a `width` × `height` box that the game places in `corner`,
+    /// stacked with the game's overlays and the other mods' panels (under
+    /// the status effects at the top right), as `hud`'s panels are.
+    set-corner: func(corner: corner, width: f32, height: f32, shapes: list<shape>);
+    /// Removes the mod's corner panel.
+    clear-corner: func();
+    /// The width of one line of text in GUI pixels, in the HUD's font: exact
+    /// for Latin letters (U+0000 to U+024F), 6 per other character.
+    text-width: func(text: string) -> f32;
+    record frame-rate {
+        /// Frames drawn in the last second.
+        fps: u32,
+        /// The slowest frame's rate, and the 1% low (the 99th percentile
+        /// frame time's rate), over the last 5 seconds.
+        min: u32,
+        low: u32,
+    }
+    /// The game's frame counter, recomputed twice a second.
+    frame-stats: func() -> frame-rate;
 }
 
 /// What the game calls. Only the hooks `init` asks for are ever called.
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 881eaf0ae..f33839fe7 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -37,7 +37,7 @@ use bindings::{
 /// The widget model a `ui` screen or settings page shows (WIT `interface
 /// ui`), for the game to draw with its menus' own widgets.
 pub use ui_bindings::horizon::mods::ui::{
-    ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
+    ButtonWidget, ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
 };
 use ui_bindings::{UiHost, horizon::mods::ui};
 /// Capability `render`'s imports (docs/mods.md): the game draws the shapes.
@@ -52,8 +52,8 @@ use render_bindings::horizon::mods::input;
 pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, ItemUse};
 /// What capability `render` asks the game to draw (WIT `interface render`).
 pub use render_bindings::horizon::mods::render::{
-    FillShape, ItemShape, Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape,
-    TextShape,
+    Corner as RenderCorner, FillShape, FrameRate, ItemShape, Point as RenderPoint, QuadShape,
+    Rect as RenderRect, Shape, SpriteShape, TextShape,
 };
 use render_bindings::{RenderHost, horizon::mods::render};
 
@@ -90,6 +90,16 @@ pub struct Snapshot {
     pub gui_size: (f32, f32),
     /// The main hand's stack (capability `input`'s `held`).
     pub held: Option<HeldItem>,
+    /// The game's frame counter: fps, min, 1% low (`render.frame-stats`).
+    pub frame: (u32, u32, u32),
+    /// The movement and click mappings `input.mapping` answers for:
+    /// (mapping, the bound key's label, held).
+    pub mappings: Vec<(&'static str, String, bool)>,
+    /// Attack and use clicks in the last second.
+    pub cps: (u32, u32),
+    /// The HUD font's advance per character from U+0000
+    /// (`render.text-width`); empty: 6 each.
+    pub font_widths: Arc<[f32]>,
 }
 
 /// What mods asked the game to show since the last [`Mods::drain`].
@@ -177,6 +187,8 @@ struct State {
     ui: UiState,
     /// Capability `render`'s HUD shapes, drawn until replaced.
     shapes: Vec<Shape>,
+    /// Capability `render`'s corner panel.
+    corner: Option<CornerPanel>,
     input: InputState,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
@@ -318,6 +330,7 @@ impl Mods {
             panel: None,
             ui: UiState::default(),
             shapes: Vec::new(),
+            corner: None,
             input: InputState::default(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
@@ -510,6 +523,19 @@ impl Mods {
             .iter()
             .filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
     }
+    /// The running mods' corner panels (capability `render`), in load order.
+    pub fn corner_panels(&self) -> impl Iterator<Item = &CornerPanel> {
+        self.entries
+            .iter()
+            .filter_map(|e| e.run.as_ref()?.store.data().corner.as_ref())
+    }
+    /// Some running mod has a `frame` hook: the game refreshes the snapshot
+    /// every frame for it.
+    pub fn wants_frames(&self) -> bool {
+        self.entries
+            .iter()
+            .any(|e| e.run.as_ref().is_some_and(|r| r.hooks.frame))
+    }
     /// Some running mod claimed items (capability `input`).
     pub fn claims_any(&self) -> bool {
         self.inputs().any(|i| !i.claimed.is_empty())
@@ -728,6 +754,10 @@ fn clip_widgets(widgets: Vec<UiWidget>) -> Vec<UiWidget> {
                 t.text = clip(t.text);
                 UiWidget::Text(t)
             }
+            UiWidget::Button(mut b) => {
+                b.label = clip(b.label);
+                UiWidget::Button(b)
+            }
             UiWidget::Item(mut i) => {
                 i.item = clip(i.item);
                 i.name = clip(i.name);
@@ -849,6 +879,16 @@ impl input::Host for State {
     fn poll(&mut self) -> Vec<InputEvent> {
         self.input.events.drain(..).collect()
     }
+    fn mapping(&mut self, name: String) -> Option<input::MappingState> {
+        let (_, label, down) = self.snapshot.mappings.iter().find(|m| m.0 == name)?;
+        Some(input::MappingState {
+            label: label.clone(),
+            down: *down,
+        })
+    }
+    fn clicks_per_second(&mut self) -> (u32, u32) {
+        self.snapshot.cps
+    }
 }
 
 /// HUD shapes one mod may keep (capability `render`).
@@ -856,33 +896,76 @@ const SHAPES: usize = 1024;
 /// The longest jolt `render.shake` makes, in seconds.
 const SHAKE_SECONDS: f32 = 10.0;
 
+/// A mod's corner panel: shapes in a `width` × `height` box the game
+/// places in `corner`, stacked with the other overlays.
+#[derive(Clone, Debug)]
+pub struct CornerPanel {
+    pub corner: RenderCorner,
+    pub width: f32,
+    pub height: f32,
+    pub shapes: Vec<Shape>,
+}
+
+fn clip_shapes(shapes: Vec<Shape>) -> Vec<Shape> {
+    shapes
+        .into_iter()
+        .take(SHAPES)
+        .map(|shape| match shape {
+            Shape::Sprite(mut s) => {
+                s.sprite = clip(s.sprite);
+                Shape::Sprite(s)
+            }
+            Shape::Item(mut i) => {
+                i.item = clip(i.item);
+                i.scale = if i.scale.is_finite() {
+                    i.scale.clamp(0.0, 16.0)
+                } else {
+                    1.0
+                };
+                Shape::Item(i)
+            }
+            Shape::Text(mut t) => {
+                t.text = clip(t.text);
+                t.color &= 0xFF_FFFF;
+                Shape::Text(t)
+            }
+            other => other,
+        })
+        .collect()
+}
+
 impl render::Host for State {
     fn set_hud(&mut self, shapes: Vec<Shape>) {
-        self.shapes = shapes
-            .into_iter()
-            .take(SHAPES)
-            .map(|shape| match shape {
-                Shape::Sprite(mut s) => {
-                    s.sprite = clip(s.sprite);
-                    Shape::Sprite(s)
-                }
-                Shape::Item(mut i) => {
-                    i.item = clip(i.item);
-                    i.scale = if i.scale.is_finite() {
-                        i.scale.clamp(0.0, 16.0)
-                    } else {
-                        1.0
-                    };
-                    Shape::Item(i)
-                }
-                Shape::Text(mut t) => {
-                    t.text = clip(t.text);
-                    t.color &= 0xFF_FFFF;
-                    Shape::Text(t)
-                }
-                other => other,
-            })
-            .collect();
+        self.shapes = clip_shapes(shapes);
+    }
+    fn set_corner(&mut self, corner: RenderCorner, width: f32, height: f32, shapes: Vec<Shape>) {
+        let size = |v: f32| {
+            if v.is_finite() {
+                v.clamp(0.0, 1024.0)
+            } else {
+                0.0
+            }
+        };
+        self.corner = Some(CornerPanel {
+            corner,
+            width: size(width),
+            height: size(height),
+            shapes: clip_shapes(shapes),
+        });
+    }
+    fn clear_corner(&mut self) {
+        self.corner = None;
+    }
+    fn text_width(&mut self, text: String) -> f32 {
+        let widths = &self.snapshot.font_widths;
+        text.chars()
+            .map(|c| widths.get(c as usize).copied().unwrap_or(6.0))
+            .sum::<f32>()
+            .ceil()
+    }
+    fn frame_stats(&mut self) -> FrameRate {
+        let (fps, min, low) = self.snapshot.frame;
+        FrameRate { fps, min, low }
     }
     fn gui_size(&mut self) -> (f32, f32) {
         self.snapshot.gui_size
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index ba1736e5e..a9de4f55b 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -91,7 +91,7 @@ fn player() -> Snapshot {
             day_time: 24000 + 6000,
         }),
         gui_size: (427.0, 240.0),
-        held: None,
+        ..Snapshot::default()
     }
 }
 
@@ -412,7 +412,7 @@ fn ui_screens_settings_and_events() {
     assert_eq!(mods.settings_widgets(0).len(), 3);
     assert!(mods.entries()[0].has_ui_settings());
     mods.ui_settings_opened(0);
-    assert_eq!(mods.settings_widgets(0).len(), 1);
+    assert_eq!(mods.settings_widgets(0).len(), 2);
     // `/ui_close` closes the mod's own screen.
     assert!(mods.command("ui_close"));
     assert!(mods.drain().contains(&Output::CloseScreen { owner: 0 }));
@@ -424,7 +424,6 @@ fn render_shapes_and_shakes() {
     let mut mods = load("horizon_mods_test_ui_guest.hmod");
     mods.set_snapshot(Snapshot {
         gui_size: (427.0, 240.0),
-        held: None,
         ..Snapshot::default()
     });
     assert_eq!(mods.hud_shapes().count(), 0);
@@ -509,6 +508,47 @@ fn input_claims_keys_and_events() {
     assert_eq!(chat(&mut mods), ["holding minecraft:stick x3 in 2"]);
 }
 
+#[test]
+fn corner_panels_text_width_and_readings() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    // A font of 5-pixel glyphs, 3-pixel spaces.
+    let mut widths = vec![5.0f32; 0x250];
+    widths[' ' as usize] = 3.0;
+    mods.set_snapshot(Snapshot {
+        frame: (60, 41, 52),
+        mappings: vec![("key.forward", "W".into(), true)],
+        cps: (7, 2),
+        font_widths: widths.into(),
+        ..Snapshot::default()
+    });
+    assert!(mods.command("corner"));
+    let panels: Vec<_> = mods.corner_panels().cloned().collect();
+    assert_eq!(panels.len(), 1);
+    // "60 fps": five glyphs and a space, plus the box's 4.
+    assert_eq!(
+        (panels[0].width, panels[0].height),
+        (5.0 * 5.0 + 3.0 + 4.0, 12.0)
+    );
+    assert_eq!(panels[0].shapes.len(), 2);
+    assert!(matches!(
+        panels[0].corner,
+        horizon_mods::RenderCorner::TopRight
+    ));
+    assert!(matches!(
+        &mods.settings_widgets(0)[0],
+        horizon_mods::UiWidget::Button(b) if b.id == 3 && b.label == "Corner: Top Right"
+    ));
+    mods.drain();
+    assert!(mods.command("readings"));
+    assert_eq!(
+        mods.drain(),
+        [Output::Chat {
+            name: "Test UI Guest".into(),
+            text: "60 41 52; forward W true; cps 7 2; other true".into(),
+        }]
+    );
+}
+
 #[test]
 fn content_only_mods_load_without_an_engine() {
     let manifest = r#"
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index be2b8fcc4..ae6e4dfc4 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -2,7 +2,8 @@
 //! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes
 //! the screen; the `ui-events` calls answer in chat so the host sees them.
 //! `/render_hud`, `/render_clear` and `/render_shake` test `render`;
-//! `/input_claim`, `/input_poll` and `/input_held` test `input`.
+//! `/input_claim`, `/input_poll` and `/input_held` test `input`;
+//! `/corner` and `/readings` the calls the official extras mods use.
 use horizon_mod_sdk::{
     Mod, Registration, chat,
     input::{self, Event},
@@ -92,6 +93,8 @@ impl Mod for Guest {
             "input_claim",
             "input_poll",
             "input_held",
+            "corner",
+            "readings",
         ]
         .into_iter()
         .fold(Registration::new(), Registration::command);
@@ -107,6 +110,49 @@ impl Mod for Guest {
             "ui_close" => ui::close_screen(),
             "render_hud" => render::set_hud(&shapes()),
             "render_clear" => render::set_hud(&[]),
+            // An FPS-counter-like box: as wide as its text plus 4.
+            "corner" => {
+                let text = "60 fps";
+                let w = render::text_width(text) + 4.0;
+                render::set_corner(
+                    render::Corner::TopRight,
+                    w,
+                    12.0,
+                    &[
+                        Shape::Fill(FillShape {
+                            rect: Rect {
+                                x: 0.0,
+                                y: 0.0,
+                                w,
+                                h: 12.0,
+                            },
+                            color: 0x78000000,
+                        }),
+                        Shape::Text(TextShape {
+                            text: text.into(),
+                            at: Point { x: 2.0, y: 2.0 },
+                            color: 0xFFFFFF,
+                            centered: false,
+                            shadow: true,
+                        }),
+                    ],
+                );
+                ui::set_settings(&[Widget::Button(ui::ButtonWidget {
+                    id: 3,
+                    label: "Corner: Top Right".into(),
+                })]);
+            }
+            "readings" => {
+                let f = render::frame_stats();
+                let fwd = input::mapping("key.forward")
+                    .map_or("none".into(), |m| format!("{} {}", m.label, m.down));
+                let (l, r) = input::clicks_per_second();
+                let none = input::mapping("key.inventory").is_none();
+                chat::show(&format!(
+                    "{} {} {}; forward {fwd}; cps {l} {r}; other {none}",
+                    f.fps, f.min, f.low
+                ));
+            }
             "input_claim" => {
                 input::claim_items(&["minecraft:stick".into()]);
                 input::register_key("wheel", "Open the wheel", "key.keyboard.r")?;
@@ -147,11 +193,17 @@ impl Mod for Guest {
         chat::show("closed");
     }
     fn ui_settings_opened(&mut self) {
-        ui::set_settings(&[Widget::Text(TextWidget {
-            id: 1,
-            text: "fresh".into(),
-            color: 0x33CC33,
-        })]);
+        ui::set_settings(&[
+            Widget::Text(TextWidget {
+                id: 1,
+                text: "fresh".into(),
+                color: 0x33CC33,
+            }),
+            Widget::Button(ui::ButtonWidget {
+                id: 3,
+                label: "Corner: Top Right".into(),
+            }),
+        ]);
         chat::show("settings opened");
     }
 }
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index b1b52164a..e371f3975 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -177,13 +177,21 @@ Rows the player picks one of, as an options page lists choices: a pick is `ui-ev
 | `rows` | `list<string>` | The rows' texts, at most 512, each up to 256 characters. |
 | `selected` | `option<u32>` | The row to mark as the current choice, if any. |
 
-### variant `widget`
+### record `button-widget`
 
-A thing on a mod's screen or settings page.
+A thing on a mod's screen or settings page. A button as the options pages have them (200 × 20): a click is `ui-events::select(id, 0)`. Mods cycle its label for a choice ("Corner: Top Left").
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `u32` | The mod's own name for the widget. |
+| `label` | `string` | Up to 256 characters. |
+
+### variant `widget`
 
 | Case | Payload | |
 | --- | --- | --- |
 | `text` | `text-widget` | Text the player reads. |
+| `button` | `button-widget` | A button. |
 | `item` | `item-widget` | An item's icon and name. |
 | `list` | `list-widget` | Rows the player picks from. |
 
@@ -246,12 +254,23 @@ The main hand's stack.
 | `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. |
 | `key-up` | `string` |  |
 
+### record `mapping-state`
+
+A mapping as the player has bound it.
+
+| Field | Type | |
+| --- | --- | --- |
+| `label` | `string` | The bound key's name as Controls shows it: `W`, `Space`, `LMB`. |
+| `down` | `bool` | Held down now (as of this frame for a mod with a `frame` hook, else this tick). |
+
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `claim-items` | `func(ids: list<string>)` | The items whose use the mod handles instead of the game, by id (at most 64). Replaces the previous list. |
 | `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`). At most 16; an unknown key is an error. |
 | `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
 | `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
+| `mapping` | `func(name: string) -> option<mapping-state>` | A movement or click mapping as the player has bound it: `key.forward`, `key.left`, `key.back`, `key.right`, `key.jump`, `key.sneak`, `key.sprint`, `key.attack` or `key.use`. None for another name. |
+| `clicks-per-second` | `func() -> tuple<u32, u32>` | Clicks of the attack and use buttons in the last second. |
 
 ## `render`
 
@@ -259,6 +278,17 @@ Access: capability `render`.
 
 Capability `render` (experimental: the manifest needs `experimental = ["render"]`): shapes the game draws for the mod with its own renderer, kept until the mod replaces them (no call per frame). A mod never supplies shader code.
 
+### enum `corner`
+
+A corner of the screen, as `hud`'s panels use them.
+
+| Case | |
+| --- | --- |
+| `top-left` |  |
+| `top-right` |  |
+| `bottom-left` |  |
+| `bottom-right` |  |
+
 ### record `rect`
 
 A rectangle in GUI pixels: the top left corner and the size.
@@ -331,11 +361,23 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun
 | `item` | `item-shape` |  |
 | `text` | `text-shape` |  |
 
+### record `frame-rate`
+
+| Field | Type | |
+| --- | --- | --- |
+| `fps` | `u32` | Frames drawn in the last second. |
+| `min` | `u32` | The slowest frame's rate, and the 1% low (the 99th percentile frame time's rate), over the last 5 seconds. |
+| `low` | `u32` |  |
+
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `set-hud` | `func(shapes: list<shape>)` | Replaces the mod's HUD shapes: up to 1024, drawn every frame in order over the HUD (after the hotbar, under chat and screens), hidden with the HUD (F1). An empty list removes them. |
 | `gui-size` | `func() -> tuple<f32, f32>` | The screen's size in GUI pixels (width, height), as of this tick. |
 | `shake` | `func(strength: f32, seconds: f32)` | Shakes the camera: a jolt of `strength` (0 to 1, 1 the hardest) that fades out over `seconds` (at most 10). Jolts add up to 1. The view turns, the player doesn't, and the player's Distortion Effects option scales it (0 turns it off). |
+| `set-corner` | `func(corner: corner, width: f32, height: f32, shapes: list<shape>)` | Replaces the mod's corner panel: shapes in GUI pixels from the top left of a `width` × `height` box that the game places in `corner`, stacked with the game's overlays and the other mods' panels (under the status effects at the top right), as `hud`'s panels are. |
+| `clear-corner` | `func()` | Removes the mod's corner panel. |
+| `text-width` | `func(text: string) -> f32` | The width of one line of text in GUI pixels, in the HUD's font: exact for Latin letters (U+0000 to U+024F), 6 per other character. |
+| `frame-stats` | `func() -> frame-rate` | The game's frame counter, recomputed twice a second. |
 
 ## `events`
 
diff --git a/docs/api/mods.md b/docs/api/mods.md
index 29da98122..356ed353c 100644
--- a/docs/api/mods.md
+++ b/docs/api/mods.md
@@ -95,6 +95,8 @@ What real mods need next, in the order modpacks and servers need it:
 
 ## Changelog
 
+- Experimental: `ui` button widget; `render.set-corner`, `text-width`, `frame-stats`; `input.mapping`,
+  `clicks-per-second` (what the official FPS, keystrokes and zoom mods need).
 - Experimental `input` (`experimental = ["input"]`): `claim-items`, `register-key`, `held`, `poll` (use-start,
   use-stop, key-down, key-up).
 - Experimental `render` (`experimental = ["render"]`): HUD shapes (fill, quad, sprite, item, text), `gui-size`, camera
diff --git a/docs/mods.md b/docs/mods.md
index 01de73fdb..d92c88fa6 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -86,9 +86,9 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) |
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
-| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
-| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects. The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
-| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs); `held()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
+| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
+| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects. The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
+| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 
 | Hook (export) | When |
 |---|---|

From 8463325648f90045f83808dd201c07bfad2a264f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:28:03 +0100
Subject: [PATCH 208/270] CI: Linux runners for the parity job (desktop,
 ThinkPad), paused while a game runs

runner-env.sh and vanilla-data.sh find Python 3.13, the pinned JDK and sccache on NixOS;
linux-runner.sh installs a runner as a systemd user service with its own screen; runner-pause.py
stops it from taking jobs while a game runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/ci/linux-runner.sh | 191 +++++++++++++++++++++++++++++++++++++++
 tools/ci/runner-env.sh   |  32 ++++++-
 tools/ci/runner-pause.py | 167 ++++++++++++++++++++++++++++++++++
 tools/ci/vanilla-data.sh |   8 +-
 4 files changed, 392 insertions(+), 6 deletions(-)
 create mode 100755 tools/ci/linux-runner.sh
 create mode 100755 tools/ci/runner-pause.py

diff --git a/tools/ci/linux-runner.sh b/tools/ci/linux-runner.sh
new file mode 100755
index 000000000..0cb677c87
--- /dev/null
+++ b/tools/ci/linux-runner.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# A Horizon CI runner (labels self-hosted, Linux, X64, horizon-game and the host's name) on a Linux machine of the
+# maintainer's (NixOS: ludodesktop, ludothinkpad), as a systemd user service of the account that holds his
+# Minecraft files, like the Mac mini's runners (docs/release-flow.md). Run it on that machine, as that user:
+#
+#   bash tools/ci/linux-runner.sh install    # register (gh login), install, start; again to update the scripts
+#   bash tools/ci/linux-runner.sh status     # the services, the runner's state, the pause watcher's last lines
+#   bash tools/ci/linux-runner.sh uninstall  # stop and unregister
+#
+# Everything lives in ~/.actions-runners/horizon (never in ~/code): the runner, its own rustup and cargo homes,
+# the work folder, and copies of this script and runner-pause.py taken at install time (a pull request's checkout
+# never runs as the service). The service runs nice, in horizon-ci.slice (low CPU and I/O weight, memory capped),
+# on its own virtual screen: vscreen (a headless sway) where it is installed, else Xvfb from nixpkgs with Mesa's
+# Vulkan drivers. runner-pause.py pauses it while a game runs (horizon-runner-pause.service).
+# HORIZON_SHARED_SOURCE: the imported vanilla data (default ~/horizon-local/shared-local, else
+# ~/code/horizon/.local); RUNNER_JOBS: cargo jobs and harnesses at once (default 2/3 of the threads).
+set -euo pipefail
+repo=ludovic111/horizon
+dir=$HOME/.actions-runners/horizon
+units=${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user
+version=2.338.0
+sha=af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32
+here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+
+# Nix packages the jobs need, kept alive by GC roots in $dir/nix.
+nix_out() { nix-build '<nixpkgs>' -A "$1" -o "$dir/nix/$2" > /dev/null && readlink -f "$dir/nix/$2"; }
+
+# The runner is a .NET program: on NixOS its native libraries (libstdc++, ICU, OpenSSL) come from nix-ld.
+export LD_LIBRARY_PATH=/run/current-system/sw/share/nix-ld/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
+# NixOS has no /bin/bash: the runner's scripts (again after each of its self-updates) get a portable one.
+fix_shebangs() { sed -i '1s|^#!/bin/bash|#!/usr/bin/env bash|' "$dir"/*.sh "$dir"/bin/*.sh; }
+
+display_env() {
+  # The jobs' screen. Never the maintainer's: the user manager hands every service his DISPLAY and WAYLAND_DISPLAY.
+  if command -v vscreen > /dev/null; then
+    VSCREEN=ci-horizon vscreen env
+  else
+    echo "unset WAYLAND_DISPLAY; export DISPLAY=:$(cat "$dir/display")"
+  fi
+}
+
+install() {
+  local name=${RUNNER_NAME:-$(hostname)-horizon} jobs=${RUNNER_JOBS:-$(( $(nproc) * 2 / 3 ))}
+  local source=${HORIZON_SHARED_SOURCE:-}
+  if [ -z "$source" ]; then
+    for candidate in "$HOME/horizon-local/shared-local" "$HOME/code/horizon/.local"; do
+      [ -d "$candidate/minecraft" ] && { source=$candidate; break; }
+    done
+  fi
+  [ -n "$source" ] && [ -d "$source/minecraft" ] || { echo "no imported Minecraft (HORIZON_SHARED_SOURCE)"; exit 1; }
+  mkdir -p "$dir/nix" "$units"
+  cp "$here/linux-runner.sh" "$here/runner-pause.py" "$dir/"
+
+  if [ ! -f "$dir/.runner" ]; then
+    local cache=$HOME/.cache/gha-runner/actions-runner-linux-x64-$version.tar.gz
+    if ! echo "$sha  $cache" | sha256sum -c --quiet - > /dev/null 2>&1; then
+      mkdir -p "$(dirname "$cache")"
+      curl -fsSL -o "$cache" "https://github.com/actions/runner/releases/download/v$version/actions-runner-linux-x64-$version.tar.gz"
+      echo "$sha  $cache" | sha256sum -c --quiet -
+    fi
+    tar xzf "$cache" -C "$dir"
+    fix_shebangs
+    gh api -X POST "repos/$repo/actions/runners/registration-token" --jq .token |
+      (cd "$dir" && bash ./config.sh --unattended --replace --url "https://github.com/$repo" --token "$(cat)" \
+        --name "$name" --labels "${RUNNER_LABELS:-horizon-game,$(hostname)}" --work _work > /dev/null)
+  fi
+
+  # Libraries for building (pkg-config) and running (dlopen) the game, the JDK pinned by research-lock.json, sccache.
+  local alsa udev java sccache
+  alsa=$(nix_out alsa-lib.dev alsa-dev)
+  udev=$(nix_out systemd.dev systemd-dev)
+  java=$(nix_out "jdk$(sed -n 's/.*"java_major": *\([0-9]*\).*/\1/p' "$here/../../research-lock.json" | head -1)_headless" jdk)/lib/openjdk
+  sccache=$(nix_out sccache sccache)
+  local libs=/run/opengl-driver/lib:/run/current-system/sw/share/nix-ld/lib
+  if ! command -v vscreen > /dev/null; then
+    local mesa x
+    mesa=$(nix_out mesa mesa)
+    x=$(nix_out xvfb-run xvfb-run)
+    for lib in libx11 libxcursor libxrandr libxi libxext libxinerama libxrender libxxf86vm libxcb libxkbcommon \
+        vulkan-loader libGL; do
+      libs=$libs:$(nix_out "$lib" "$lib")/lib
+    done
+    libs=$mesa/lib:$libs
+    echo "VK_DRIVER_FILES=$mesa/share/vulkan/icd.d/intel_icd.x86_64.json:$mesa/share/vulkan/icd.d/lvp_icd.x86_64.json" \
+      > "$dir/.env.display"
+    echo "$x/bin" > "$dir/.path.display"
+  fi
+  cat > "$dir/.env" <<EOF
+LANG=C.UTF-8
+RUSTUP_HOME=$dir/rustup
+CARGO_HOME=$dir/cargo
+CARGO_BUILD_JOBS=$jobs
+PARITY_MACHINE_JOBS=$jobs
+JAVA_HOME=$java
+HORIZON_SHARED_SOURCE=$source
+HORIZON_NO_AUDIO=1
+HORIZON_NO_HEARTBEAT=1
+HORIZON_TELEMETRY_URL=off
+HORIZON_LAUNCHER_NO_SELF_UPDATE=1
+PKG_CONFIG_PATH=$alsa/lib/pkgconfig:$udev/lib/pkgconfig
+C_INCLUDE_PATH=$udev/include
+LD_LIBRARY_PATH=$libs
+NIX_LD=/run/current-system/sw/share/nix-ld/lib/ld.so
+NIX_LD_LIBRARY_PATH=/run/current-system/sw/share/nix-ld/lib
+EOF
+  if [ -f "$dir/.env.display" ]; then cat "$dir/.env.display" >> "$dir/.env"; else echo "VSCREEN=ci-horizon" >> "$dir/.env"; fi
+  echo "$dir/cargo/bin:$(cat "$dir/.path.display" 2>/dev/null || true)${dir}/nix/sccache/bin:$java/bin:$HOME/.local/bin:/run/wrappers/bin:/etc/profiles/per-user/$USER/bin:/run/current-system/sw/bin" \
+    | sed 's/::/:/g' > "$dir/.path"
+
+  cat > "$units/horizon-ci.slice" <<EOF
+[Unit]
+Description=Horizon CI: the runner's jobs and parity workers sent from other machines
+[Slice]
+CPUWeight=20
+IOWeight=20
+MemoryHigh=$(( $(awk '/MemTotal/ {print int($2 / 1048576)}' /proc/meminfo) / 2 ))G
+MemoryMax=$(( $(awk '/MemTotal/ {print int($2 / 1048576)}' /proc/meminfo) * 2 / 3 ))G
+EOF
+  cat > "$units/horizon-runner.service" <<EOF
+[Unit]
+Description=GitHub Actions runner for $repo (parity), paused while a game runs
+After=network-online.target
+[Service]
+Slice=horizon-ci.slice
+WorkingDirectory=$dir
+ExecStart=/usr/bin/env bash $dir/linux-runner.sh run
+Nice=10
+# runsvc.sh hands SIGTERM to the runner, which stops after cancelling its job; then the rest (Xvfb) goes.
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=5min
+Restart=on-failure
+RestartSec=30
+[Install]
+WantedBy=default.target
+EOF
+  cat > "$units/horizon-runner-pause.service" <<EOF
+[Unit]
+Description=Pauses the Horizon CI runner while a game runs
+[Service]
+ExecStart=$(command -v python3) $dir/runner-pause.py
+Restart=always
+RestartSec=10
+[Install]
+WantedBy=default.target
+EOF
+  # User services run without a login session (after a reboot): lingering, once.
+  if [ "$(loginctl show-user "$USER" -p Linger --value 2>/dev/null)" != yes ]; then
+    sudo -n loginctl enable-linger "$USER" || echo "Run once: sudo loginctl enable-linger $USER"
+  fi
+  systemctl --user daemon-reload
+  systemctl --user enable horizon-runner.service horizon-runner-pause.service > /dev/null
+  systemctl --user restart horizon-runner-pause.service
+  [ -e "$dir/paused" ] || systemctl --user start horizon-runner.service
+  status
+}
+
+run() {
+  cd "$dir"
+  fix_shebangs
+  if command -v vscreen > /dev/null; then
+    eval "$(display_env)"
+  else
+    # Xvfb on the first free display from :90, for this service's lifetime.
+    local n=90
+    while [ -e "/tmp/.X$n-lock" ]; do n=$((n + 1)); done
+    echo "$n" > "$dir/display"
+    Xvfb ":$n" -screen 0 1280x720x24 -nolisten tcp &
+    eval "$(display_env)"
+  fi
+  exec bash ./bin/runsvc.sh
+}
+
+status() {
+  systemctl --user --no-pager list-units 'horizon-runner*' 'vscreen-ci-horizon*'
+  [ -e "$dir/paused" ] && echo "paused: $(cat "$dir/paused")"
+  tail -5 "$dir/pause.log" 2>/dev/null || true
+}
+
+uninstall() {
+  systemctl --user disable --now horizon-runner-pause.service horizon-runner.service 2>/dev/null || true
+  gh api -X POST "repos/$repo/actions/runners/remove-token" --jq .token |
+    (cd "$dir" && bash ./config.sh remove --token "$(cat)")
+  rm -f "$units/horizon-runner.service" "$units/horizon-runner-pause.service" "$units/horizon-ci.slice"
+  systemctl --user daemon-reload
+}
+
+case ${1:-} in
+  install|run|status|uninstall) "$1" ;;
+  *) sed -n '2,10p' "$0"; exit 2 ;;
+esac
diff --git a/tools/ci/runner-env.sh b/tools/ci/runner-env.sh
index 49158ac91..39828b7d7 100755
--- a/tools/ci/runner-env.sh
+++ b/tools/ci/runner-env.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
-# The tools the vanilla harnesses need, on the self-hosted Mac mini runner (label horizon-game): its service
-# starts with a bare PATH. Python 3.13 and the JDK pinned by research-lock.json come from the machine, never
-# from a download. Writes them to $GITHUB_PATH and $GITHUB_ENV for the next steps.
+# The tools the vanilla harnesses need, on a self-hosted runner (label horizon-game): the Mac mini's, whose service
+# starts with a bare PATH, and the Linux ones (tools/ci/linux-runner.sh, NixOS). Python 3.13 and the JDK pinned by
+# research-lock.json come from the machine, never from a download. Writes them to $GITHUB_PATH and $GITHUB_ENV for
+# the next steps.
 set -euo pipefail
 java_major=$(sed -n 's/.*"java_major": *\([0-9]*\).*/\1/p' research-lock.json | head -1)
 bin="$RUNNER_TEMP/horizon-bin"
@@ -17,5 +18,30 @@ if [ "$(uname)" = Darwin ]; then
   if [ -x /opt/homebrew/bin/sccache ]; then
     { echo "RUSTC_WRAPPER=/opt/homebrew/bin/sccache"; echo "CARGO_INCREMENTAL=0"; } >> "$GITHUB_ENV"
   fi
+else
+  python=$(command -v python3.13 || true)
+  [ -n "$python" ] || { echo "::error::no python3.13 on this runner"; exit 1; }
+  ln -sfn "$python" "$bin/python3"
+  ln -sfn "$python" "$bin/python"
+  # The JDK: the runner's JAVA_HOME (linux-runner.sh pins one), else the java on PATH, else nixpkgs' jdk<major>.
+  major_of() { "$1/bin/java" -version 2>&1 | sed -n 's/.*version "\([0-9]*\).*/\1/p' | head -1; }
+  java_home=${JAVA_HOME:-}
+  if [ -z "$java_home" ] || [ "$(major_of "$java_home")" != "$java_major" ]; then
+    java_home=""
+    if command -v java > /dev/null; then
+      candidate=$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")
+      [ "$(major_of "$candidate")" = "$java_major" ] && java_home=$candidate
+    fi
+  fi
+  if [ -z "$java_home" ] && command -v nix-build > /dev/null; then
+    out=$(nix-build '<nixpkgs>' --no-out-link -A "jdk${java_major}_headless" 2>/dev/null || true)
+    [ -n "$out" ] && java_home=$out/lib/openjdk
+  fi
+  [ -n "$java_home" ] || { echo "::error::no JDK $java_major on this runner"; exit 1; }
+  { echo "$bin"; echo "$java_home/bin"; } >> "$GITHUB_PATH"
+  echo "JAVA_HOME=$java_home" >> "$GITHUB_ENV"
+  if sccache=$(command -v sccache); then
+    { echo "RUSTC_WRAPPER=$sccache"; echo "CARGO_INCREMENTAL=0"; } >> "$GITHUB_ENV"
+  fi
 fi
 echo "HORIZON_NO_AUDIO=1" >> "$GITHUB_ENV"
diff --git a/tools/ci/runner-pause.py b/tools/ci/runner-pause.py
new file mode 100755
index 000000000..4a88c6ae4
--- /dev/null
+++ b/tools/ci/runner-pause.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Pauses the Horizon CI runner (tools/ci/linux-runner.sh) while the maintainer plays a game on this machine.
+
+A game is running when any of these holds:
+  - fleet-load says so (~/fleet/load: Steam, gamescope, Wine or Proton processes);
+  - a process of his matches GAME below (the same, plus Minecraft and a Horizon game he started himself);
+  - a process outside horizon-ci.slice keeps the GPU busy (nvidia-smi: SM use >= GPU_BUSY % twice in a row);
+  - ~/.actions-runners/horizon/pause exists (pause by hand: `touch` it; `rm` it to let the watcher decide).
+
+Paused, the runner takes no new job: while it is idle its service is stopped, so GitHub sends the jobs to the
+Mac mini. A job already running is throttled, not stopped: horizon-ci.slice (the job, and the parity workers other machines
+send here) drops to CPU weight 1, I/O weight 1
+and a quota of THROTTLE_CPUS threads, and the service stops once the job ends. Freezing it (SIGSTOP or the cgroup
+freezer) would stop the runner's heartbeat, so GitHub would drop the job as lost, and the harnesses' wall-clock
+timeouts would fail runs that were only waiting. The runner comes back RESUME_AFTER seconds after the last sign
+of a game. Every change is written to ~/.actions-runners/horizon/pause.log.
+"""
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+
+DIR = Path.home() / ".actions-runners" / "horizon"
+SERVICE, SLICE = "horizon-runner.service", "horizon-ci.slice"
+MANUAL, STATE, LOG = DIR / "pause", DIR / "paused", DIR / "pause.log"
+GAME = re.compile(r"(SteamLaunch|gamescope|wine64-preloader|wineserver|wine-preloader|\.exe(\s|$)|proton\b"
+                  r"|net\.minecraft\.client\.main\.Main|minecraft-launcher|prismlauncher)", re.I)
+GPU_BUSY = int(os.environ.get("GPU_BUSY", 30))
+INTERVAL = int(os.environ.get("INTERVAL", 15))
+RESUME_AFTER = int(os.environ.get("RESUME_AFTER", 300))
+THROTTLE_CPUS = int(os.environ.get("THROTTLE_CPUS", 2))
+
+
+def log(text):
+    with LOG.open("a") as handle:
+        handle.write(f"{time.strftime('%Y-%m-%dT%H:%M:%S')} {text}\n")
+
+
+def systemctl(*arguments):
+    return subprocess.run(["systemctl", "--user", *arguments], capture_output=True, text=True)
+
+
+def ci_process(pid):
+    """A process of the runner's slice (its jobs, the parity workers other machines start here)."""
+    try:
+        return SLICE in Path(f"/proc/{pid}/cgroup").read_text()
+    except OSError:
+        return True  # gone
+
+
+def fleet_load_gaming():
+    status = Path(os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{os.getuid()}")) / "fleet-load" / "status.json"
+    try:
+        if time.time() - status.stat().st_mtime > 120:
+            return None
+        return "fleet-load: playing a game" if json.loads(status.read_text())["human"]["gaming"] else None
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def game_process():
+    uid = os.getuid()
+    for entry in Path("/proc").iterdir():
+        if not entry.name.isdigit():
+            continue
+        try:
+            if entry.stat().st_uid != uid:
+                continue
+            command = (entry / "cmdline").read_bytes().replace(b"\0", b" ").decode(errors="replace")
+        except OSError:
+            continue
+        # A Horizon game counts when he started it (its parent is his launcher), not when a harness or agent did.
+        if GAME.search(command) or (" --offscreen" not in command and "/horizon-launcher/" in command
+                                    and "horizon-client" in command.split(" ")[0]):
+            if not ci_process(int(entry.name)):
+                return f"process {entry.name}: {command[:120]}"
+    return None
+
+
+def gpu_users():
+    """Processes outside the CI slice using the GPU's shader cores, as {pid: SM %}."""
+    try:
+        output = subprocess.run(["nvidia-smi", "pmon", "-c", "1", "-s", "u"], capture_output=True, text=True,
+                                timeout=20).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return {}
+    users = {}
+    for line in output.splitlines():
+        fields = line.split()
+        if line.startswith("#") or len(fields) < 4 or not fields[1].isdigit() or not fields[3].isdigit():
+            continue
+        if not ci_process(int(fields[1])):
+            users[int(fields[1])] = int(fields[3])
+    return users
+
+
+def runner_busy():
+    """The runner is in a job: a Runner.Worker runs in its service."""
+    group = systemctl("show", "-p", "ControlGroup", "--value", SERVICE).stdout.strip()
+    try:
+        pids = Path(f"/sys/fs/cgroup{group}/cgroup.procs").read_text().split() if group else []
+    except OSError:
+        return False
+    for pid in pids:
+        try:
+            if Path(f"/proc/{pid}/comm").read_text().strip() == "Runner.Worker":
+                return True
+        except OSError:
+            pass
+    return False
+
+
+def throttle(on):
+    if on:
+        systemctl("set-property", "--runtime", SLICE, "CPUWeight=1", "IOWeight=1", f"CPUQuota={THROTTLE_CPUS * 100}%")
+    else:
+        systemctl("set-property", "--runtime", SLICE, "CPUWeight=20", "IOWeight=20", "CPUQuota=")
+
+
+def main():
+    hot = {}  # GPU users seen busy at the last sample
+    last_game = 0.0
+    paused = STATE.exists()
+    while True:
+        reason = None
+        if MANUAL.exists():
+            reason = "paused by hand (" + str(MANUAL) + ")"
+        reason = reason or fleet_load_gaming() or game_process()
+        if not reason:
+            busy = {pid for pid, sm in gpu_users().items() if sm >= GPU_BUSY}
+            twice = busy & set(hot)
+            hot = dict.fromkeys(busy)
+            if twice:
+                pid = min(twice)
+                try:
+                    name = Path(f"/proc/{pid}/comm").read_text().strip()
+                except OSError:
+                    name = "?"
+                reason = f"GPU busy: process {pid} ({name})"
+        now = time.monotonic()
+        if reason:
+            last_game = now
+        if reason and not paused:
+            paused = True
+            STATE.write_text(reason + "\n")
+            throttle(True)  # also what other machines' parity workers run here meanwhile
+            if runner_busy():
+                log(f"pause: {reason}; a job is running: throttled to {THROTTLE_CPUS} threads, stops after it")
+            else:
+                systemctl("stop", SERVICE)
+                log(f"pause: {reason}; runner stopped")
+        elif paused and reason is None and now - last_game >= RESUME_AFTER:
+            paused = False
+            STATE.unlink(missing_ok=True)
+            throttle(False)
+            systemctl("start", SERVICE)
+            log(f"resume: no game for {RESUME_AFTER} s; runner started")
+        elif paused and systemctl("is-active", "--quiet", SERVICE).returncode == 0 and not runner_busy():
+            systemctl("stop", SERVICE)
+            log("the job ended: runner stopped until the game ends")
+        time.sleep(INTERVAL)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tools/ci/vanilla-data.sh b/tools/ci/vanilla-data.sh
index 5276c54e9..a7bd4a407 100755
--- a/tools/ci/vanilla-data.sh
+++ b/tools/ci/vanilla-data.sh
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # The vanilla data for this checkout on the self-hosted runner. Horizon never downloads the game: the runner
 # holds the maintainer's own copy, imported and decompiled once (HORIZON_SHARED_SOURCE, default
-# ~/code/horizon-parity/shared-local). It is cloned once into the runner's work folder ($RUNNER_WORKSPACE/
-# shared-local; APFS clones, so no second copy of the bytes), and .local/ links to it as in a parity worktree.
+# ~/code/horizon-parity/shared-local; tools/ci/linux-runner.sh sets it on Linux). It is cloned once into the runner's
+# work folder ($RUNNER_WORKSPACE/shared-local; APFS clones, or reflinks where the file system has them, so no second
+# copy of the bytes), and .local/ links to it as in a parity worktree.
 # .local/horizon-client and the exporter outputs beside it, what horizon-prepare makes, are prepared by this
 # checkout's own preparer once per preparer version (its sources, the exporters and research-lock.json), so a
 # change to the preparer is checked with what it prepares; the four newest preparations are kept.
@@ -31,7 +32,8 @@ for entry in "$shared"/*; do
 done
 
 # HORIZON_PREPARE_KEY: the same key, computed where the Git history is (tools/pr_ready.py on another machine).
-key=${HORIZON_PREPARE_KEY:-$(git ls-files -s crates/horizon-prepare mods/horizon/src/test/java research-lock.json | shasum -a 256 | cut -c1-16)}
+sha256() { if command -v shasum > /dev/null; then shasum -a 256; else sha256sum; fi; }
+key=${HORIZON_PREPARE_KEY:-$(git ls-files -s crates/horizon-prepare mods/horizon/src/test/java research-lock.json | sha256 | cut -c1-16)}
 prepared="$shared/prepared/$key"
 # Two runners share the vanilla data (~/.actions-runners/horizon-2/_work/horizon/shared-local links to the first
 # one's): one preparation at a time. A lock older than 30 minutes belongs to a job that died.

From d81aa97e842a753e231ae34b181bc1bd2654c589 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:12:08 +0100
Subject: [PATCH 209/270] CI: the desktop runner works only while nobody is at
 the screen; desktop as a parity host

runner_pause.py pauses on any seat0 session (locked too), games, GPU use or a pause file, and is
the only thing that starts the runner; a job under way is throttled, then the runner stops. The
desktop host in parity_hosts.json refuses work while paused and its workers stop on a pause. The
nightly audit stays on the Mac mini. Docs and a unit test of the watcher.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/nightly.yml                 |   3 +-
 docs/parity-workflow.md                       |   2 +-
 docs/release-flow.md                          |  28 +++-
 tests/test_runner_pause.py                    |  82 ++++++++++++
 tools/ci/linux-runner.sh                      |  52 +++++---
 tools/ci/{runner-pause.py => runner_pause.py} | 125 +++++++++++-------
 tools/parity_hosts.json                       |   9 ++
 7 files changed, 230 insertions(+), 71 deletions(-)
 create mode 100644 tests/test_runner_pause.py
 rename tools/ci/{runner-pause.py => runner_pause.py} (51%)

diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 51f9e89cd..60bbbf057 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -29,7 +29,8 @@ env:
 
 jobs:
   audit:
-    runs-on: [self-hosted, horizon-game]
+    # The Mac mini's runners only: the audit compares with the previous one, so it stays on one platform.
+    runs-on: [self-hosted, horizon-game, macOS]
     timeout-minutes: 150
     steps:
       - name: 03:00 in Paris
diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index f9f222071..80426fa59 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -38,7 +38,7 @@ The game logs into `HORIZON_HOME` and falls back to the player's own game folder
 
 ### Other machines
 
-Harnesses can also run on the Mac mini and the ThinkPad (`tools/parity_hosts.json` describes them; its `default` list is empty, so pass `--hosts macmini,thinkpad` or set `PARITY_HOSTS`, after copying `shared-local/` to `~/code/horizon-parity/shared-local` on each host). The runner mirrors the worktree there with rsync (not `.git`, `.local`, `target` or ignored files) into `~/code/horizon-parity/remote/<host><path>`, whose `.local` links to the vanilla data in `~/code/horizon-parity/shared-local`, and starts `tools/parity.py --worker` over ssh. The worker builds the probes (about 80 s the first time) and runs what it is sent under the same tracer, admitting harnesses against its own free memory. One queue, longest first, feeds every machine, remote ones first: the Mac takes up to 14 harnesses, the desktop 3 and only those under 800 MB. Each pass comes back with the content hash of every file it depended on, so it is keyed on exactly what ran, and logs come back to `.local/parity-runner/logs/`; state, sharing and `gate.py` work as before. If a host can't be reached, or drops out, its harnesses run here.
+Harnesses can also run on the Mac mini, the ThinkPad and the desktop (`tools/parity_hosts.json` describes them; `desktop` uses its CI runner's environment and vanilla data, and refuses work, or stops it, while someone is at it: docs/release-flow.md, "The desktop's runner"; its `default` list is empty, so pass `--hosts macmini,thinkpad` or set `PARITY_HOSTS`, after copying `shared-local/` to `~/code/horizon-parity/shared-local` on each host). The runner mirrors the worktree there with rsync (not `.git`, `.local`, `target` or ignored files) into `~/code/horizon-parity/remote/<host><path>`, whose `.local` links to the vanilla data in `~/code/horizon-parity/shared-local`, and starts `tools/parity.py --worker` over ssh. The worker builds the probes (about 80 s the first time) and runs what it is sent under the same tracer, admitting harnesses against its own free memory. One queue, longest first, feeds every machine, remote ones first: the Mac takes up to 14 harnesses, the desktop 3 and only those under 800 MB. Each pass comes back with the content hash of every file it depended on, so it is keyed on exactly what ran, and logs come back to `.local/parity-runner/logs/`; state, sharing and `gate.py` work as before. If a host can't be reached, or drops out, its harnesses run here.
 
 Harnesses a host can't run are listed in the file: `local_only` (`save_roundtrip` runs the game on a virtual screen) and each host's `exclude`. The Mac excludes nothing: vanilla's `Math.sin`, `pow`, `log` and the like don't round the same on an Apple silicon Mac as on Linux (HotSpot uses fdlibm there, Intel's stubs on x86-64), and Rust's float functions round like neither (they call the platform libm), so code that mirrors a vanilla `Math` call uses `horizon_core::jmath`, which computes what HotSpot computes on the host architecture. The ThinkPad helps too, gently: Linux, 2 harnesses at `nice 19`, since it hosts the Claude account pool; it finds ALSA through `~/code/horizon-parity/alsa-dev` like the desktop.
 
diff --git a/docs/release-flow.md b/docs/release-flow.md
index 4fb0209d9..e72bebc73 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -13,7 +13,7 @@ reopened; labels never start it):
 | Job | Runs on | What | Time |
 | --- | --- | --- | --- |
 | `verify` | GitHub `ubuntu-latest` | Public-tree check, Python tests, rustfmt, clippy with warnings denied, Rust tests. Dependencies and the workspace build come from a cache saved by main's runs | ~4 min cold, less warm |
-| `parity / parity` | The Mac mini's runner (`ludovics-mac-mini`, label `horizon-game`) | The vanilla harnesses the change can affect (`tools/parity.py --changed <base>`) | seconds when nothing is affected; minutes per affected harness |
+| `parity / parity` | A runner with the label `horizon-game`: the Mac mini's two, and the desktop's when no game runs there (below) | The vanilla harnesses the change can affect (`tools/parity.py --changed <base>`) | seconds when nothing is affected; minutes per affected harness |
 
 Pushes to main run `verify` only; the nightly audit covers main's harnesses.
 
@@ -28,10 +28,13 @@ The job is `.github/workflows/parity.yml`, a reusable workflow: `checks` calls i
 repository, `run-parity.yml` for a fork's pull request a maintainer labels `run-parity`.
 
 Horizon never downloads the game, so harnesses that compare with vanilla run only where the maintainer's own
-copy is: the Mac mini. Its runner runs as the maintainer's account and keeps its checkout between runs
-(`clean: false`), so the probes build incrementally into `.local/parity-target` and earlier passes stand.
+copy is: the Mac mini and his Linux desktop. Their runners run as the maintainer's account and keep their checkout
+between runs (`clean: false`), so the probes build incrementally into `.local/parity-target` and earlier passes
+stand.
 
-1. `tools/ci/runner-env.sh` puts the machine's Python 3.13 and the JDK `research-lock.json` pins on the PATH.
+1. `tools/ci/runner-env.sh` puts the machine's Python 3.13 and the JDK `research-lock.json` pins on the PATH
+   (Homebrew and `java_home` on the Mac; on NixOS what `linux-runner.sh` pinned, else nixpkgs), and sccache when
+   the machine has it.
 2. `tools/ci/vanilla-data.sh` links `.local/` to the runner's copy of the vanilla data, cloned once from
    `~/code/horizon-parity/shared-local` into `~/.actions-runners/horizon/_work/horizon/shared-local`, and
    prepares `.local/horizon-client` with the pull request's own `horizon-prepare` once per preparer version
@@ -64,6 +67,23 @@ release's macOS build back. Each keeps its own checkout, `target/` and Rust inst
 `_work/horizon/shared-local` links to the first's, so they share the vanilla data, the preparations (one at a
 time, under a lock) and the parity passes and slots.
 
+**The desktop's runner.** `ludodesktop-horizon` (labels `self-hosted`, `Linux`, `X64`, `ludodesktop`, and
+`horizon-game` once a full trial has passed there) runs on the maintainer's Linux desktop, only while nobody is
+at it. `tools/ci/linux-runner.sh install`, run there as him, registers it and installs two systemd user services:
+`horizon-runner` (the runner, in `~/.actions-runners/horizon`, nice 19, in `horizon-ci.slice` with CPU and I/O
+weight 20 and memory capped at two thirds of the RAM; `CARGO_BUILD_JOBS` and the harness slots at 8, after the
+machine froze under ~7 cold cargo builds on 2026-10-14; its own Rust install; the JDK, sccache and the build
+libraries from nixpkgs; its own `vscreen` so no game it starts reaches his screen) and `horizon-runner-pause`
+(`tools/ci/runner_pause.py`), the only thing that starts the runner. The watcher stops it while a graphical
+session is open on the machine, locked or not (`~/fleet/power status` says "IN USE"), while a game runs (Steam,
+gamescope, Wine, Proton or Minecraft processes, fleet-load's own detection, or a process outside the CI slice
+using the GPU at 50 % or more), or while `~/.actions-runners/horizon/pause` exists, and starts it again 5 minutes
+after the last such sign. A job already under way is throttled to 2 threads at the lowest weight and the runner
+stops after it: freezing the job would make GitHub drop it as lost and the harnesses time out. Old pull requests'
+`runner-env.sh` know only the Mac: the runner's `.env` and `.path` give their jobs Python, the JDK and the
+vanilla data (`HORIZON_SHARED_SOURCE`) all the same. The nightly audit stays on the Mac mini's runners, so its
+comparison with the previous night is always made on one platform.
+
 ## Merging
 
 Pull requests merge with a merge commit. The orchestrator sessions review a pull request, then turn on
diff --git a/tests/test_runner_pause.py b/tests/test_runner_pause.py
new file mode 100644
index 000000000..c6df08b82
--- /dev/null
+++ b/tests/test_runner_pause.py
@@ -0,0 +1,82 @@
+"""tools/ci/runner_pause.py: the Linux CI runner works only while nobody is at the screen or playing."""
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from tools.ci import runner_pause
+
+
+class Machine:
+    """A fake desktop: a clock, who is there, and the runner service. The watcher samples every 15 s."""
+
+    def __init__(self, signs):
+        self.signs = signs  # (from, until, reason): a sign of someone at the screen or playing
+        self.clock = 0.0
+        self.active = False
+        self.job_until = None  # the runner is in a job until then
+        self.throttles = []  # (clock, on)
+        self.calls = []
+
+    def reason(self, hot):
+        return next((reason for start, end, reason in self.signs if start <= self.clock < end), None)
+
+    def systemctl(self, *arguments):
+        self.calls.append((self.clock, arguments))
+        if arguments[1:] == (runner_pause.SERVICE,):
+            self.active = {"start": True, "stop": False}.get(arguments[0], self.active)
+        return mock.Mock(returncode=0 if arguments[:2] != ("is-active", "--quiet") or self.active else 3)
+
+    def busy(self):
+        return self.job_until is not None and self.clock < self.job_until
+
+    def sleep(self, seconds):
+        self.clock += seconds
+        if self.clock > 2000:
+            raise StopIteration
+
+    def run(self):
+        with tempfile.TemporaryDirectory() as directory, \
+                mock.patch.multiple(runner_pause, MANUAL=Path(directory, "pause"), STATE=Path(directory, "paused"),
+                                    LOG=Path(directory, "pause.log"), INTERVAL=15, RESUME_AFTER=300,
+                                    pause_reason=self.reason, systemctl=self.systemctl, runner_busy=self.busy,
+                                    throttle=lambda on: self.throttles.append((self.clock, on))), \
+                mock.patch.object(runner_pause.time, "monotonic", lambda: self.clock), \
+                mock.patch.object(runner_pause.time, "sleep", self.sleep):
+            try:
+                runner_pause.main()
+            except StopIteration:  # the clock ran out
+                pass
+
+    def first(self, verb, after=0):
+        return next(clock for clock, arguments in self.calls
+                    if arguments == (verb, runner_pause.SERVICE) and clock >= after)
+
+
+class RunnerPauseTests(unittest.TestCase):
+    def test_starts_only_after_nobody_was_there_for_resume_after(self):
+        machine = Machine([(0, 600, "session 3 of ludovic at the screen (seat0)")])
+        machine.run()
+        self.assertEqual(machine.first("start"), 585 + 300)  # the last sample that saw him
+
+    def test_a_game_stops_an_idle_runner_at_once(self):
+        machine = Machine([(1000, 1300, "process 42: wine64-preloader game.exe")])
+        machine.run()
+        self.assertEqual(machine.first("start"), 300)
+        self.assertEqual(machine.first("stop", after=300), 1005)
+        self.assertEqual(machine.first("start", after=1005), 1290 + 300)
+
+    def test_a_job_under_way_is_throttled_then_stopped_when_it_ends(self):
+        machine = Machine([(1000, 1300, "GPU busy: process 7 (game)")])
+        machine.job_until = 1200
+        machine.run()
+        self.assertIn((1005, True), machine.throttles)  # the game started: the job slows down at once,
+        self.assertIn((1005, ("stop", "horizon-parity-worker-*.scope")), machine.calls)  # other machines' work goes
+        stop = machine.first("stop", after=300)
+        self.assertGreaterEqual(stop, 1200)  # and the runner stops once it ends, not before
+        self.assertLess(stop, 1215)
+        self.assertEqual(machine.throttles[-1], (1290 + 300, False))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/ci/linux-runner.sh b/tools/ci/linux-runner.sh
index 0cb677c87..adc2b0130 100755
--- a/tools/ci/linux-runner.sh
+++ b/tools/ci/linux-runner.sh
@@ -8,12 +8,14 @@
 #   bash tools/ci/linux-runner.sh uninstall  # stop and unregister
 #
 # Everything lives in ~/.actions-runners/horizon (never in ~/code): the runner, its own rustup and cargo homes,
-# the work folder, and copies of this script and runner-pause.py taken at install time (a pull request's checkout
-# never runs as the service). The service runs nice, in horizon-ci.slice (low CPU and I/O weight, memory capped),
+# the work folder, and copies of this script and runner_pause.py taken at install time (a pull request's checkout
+# never runs as the service). horizon-runner-pause.service (runner_pause.py) starts the runner only while nobody is
+# at the screen or playing, and stops it otherwise. The runner runs nice, in horizon-ci.slice (low CPU and I/O weight, memory capped),
 # on its own virtual screen: vscreen (a headless sway) where it is installed, else Xvfb from nixpkgs with Mesa's
-# Vulkan drivers. runner-pause.py pauses it while a game runs (horizon-runner-pause.service).
+# Vulkan drivers.
 # HORIZON_SHARED_SOURCE: the imported vanilla data (default ~/horizon-local/shared-local, else
-# ~/code/horizon/.local); RUNNER_JOBS: cargo jobs and harnesses at once (default 2/3 of the threads).
+# ~/code/horizon/.local); RUNNER_JOBS: cargo jobs and harnesses at once (default a third of the threads, at most 8:
+# ludodesktop froze under ~7 cold cargo builds on 2026-10-14, and it is the maintainer's own machine).
 set -euo pipefail
 repo=ludovic111/horizon
 dir=$HOME/.actions-runners/horizon
@@ -30,6 +32,18 @@ export LD_LIBRARY_PATH=/run/current-system/sw/share/nix-ld/lib${LD_LIBRARY_PATH:
 # NixOS has no /bin/bash: the runner's scripts (again after each of its self-updates) get a portable one.
 fix_shebangs() { sed -i '1s|^#!/bin/bash|#!/usr/bin/env bash|' "$dir"/*.sh "$dir"/bin/*.sh; }
 
+# Other machines' parity runs can send harnesses here (tools/parity_hosts.json "desktop": parity.py --worker over
+# ssh, in horizon-ci.slice). Their vanilla data is the runner checkout's: parity-host/shared-local links to its
+# .local links, so it follows the preparation of the runner's last job.
+parity_host_links() {
+  local checkout=$dir/_work/horizon/horizon/.local shared=$dir/parity-host/shared-local entry
+  [ -d "$checkout" ] || return 0
+  mkdir -p "$shared"
+  for entry in "$checkout"/*; do
+    [ -L "$entry" ] && ln -sfn "$entry" "$shared/$(basename "$entry")"
+  done
+}
+
 display_env() {
   # The jobs' screen. Never the maintainer's: the user manager hands every service his DISPLAY and WAYLAND_DISPLAY.
   if command -v vscreen > /dev/null; then
@@ -40,7 +54,9 @@ display_env() {
 }
 
 install() {
-  local name=${RUNNER_NAME:-$(hostname)-horizon} jobs=${RUNNER_JOBS:-$(( $(nproc) * 2 / 3 ))}
+  local name=${RUNNER_NAME:-$(hostname)-horizon} threads jobs
+  threads=$(nproc)
+  jobs=${RUNNER_JOBS:-$(( threads / 3 > 8 ? 8 : threads / 3 > 1 ? threads / 3 : 1 ))}
   local source=${HORIZON_SHARED_SOURCE:-}
   if [ -z "$source" ]; then
     for candidate in "$HOME/horizon-local/shared-local" "$HOME/code/horizon/.local"; do
@@ -49,7 +65,7 @@ install() {
   fi
   [ -n "$source" ] && [ -d "$source/minecraft" ] || { echo "no imported Minecraft (HORIZON_SHARED_SOURCE)"; exit 1; }
   mkdir -p "$dir/nix" "$units"
-  cp "$here/linux-runner.sh" "$here/runner-pause.py" "$dir/"
+  cp "$here/linux-runner.sh" "$here/runner_pause.py" "$dir/"
 
   if [ ! -f "$dir/.runner" ]; then
     local cache=$HOME/.cache/gha-runner/actions-runner-linux-x64-$version.tar.gz
@@ -66,11 +82,11 @@ install() {
   fi
 
   # Libraries for building (pkg-config) and running (dlopen) the game, the JDK pinned by research-lock.json, sccache.
-  local alsa udev java sccache
+  local alsa udev java
   alsa=$(nix_out alsa-lib.dev alsa-dev)
   udev=$(nix_out systemd.dev systemd-dev)
   java=$(nix_out "jdk$(sed -n 's/.*"java_major": *\([0-9]*\).*/\1/p' "$here/../../research-lock.json" | head -1)_headless" jdk)/lib/openjdk
-  sccache=$(nix_out sccache sccache)
+  nix_out sccache sccache > /dev/null  # on the PATH below: runner-env.sh hands it to cargo
   local libs=/run/opengl-driver/lib:/run/current-system/sw/share/nix-ld/lib
   if ! command -v vscreen > /dev/null; then
     local mesa x
@@ -91,6 +107,7 @@ RUSTUP_HOME=$dir/rustup
 CARGO_HOME=$dir/cargo
 CARGO_BUILD_JOBS=$jobs
 PARITY_MACHINE_JOBS=$jobs
+PARITY_LOCAL_JOBS=$jobs
 JAVA_HOME=$java
 HORIZON_SHARED_SOURCE=$source
 HORIZON_NO_AUDIO=1
@@ -118,27 +135,25 @@ MemoryMax=$(( $(awk '/MemTotal/ {print int($2 / 1048576)}' /proc/meminfo) * 2 /
 EOF
   cat > "$units/horizon-runner.service" <<EOF
 [Unit]
-Description=GitHub Actions runner for $repo (parity), paused while a game runs
+Description=GitHub Actions runner for $repo (parity), started and stopped by horizon-runner-pause
 After=network-online.target
 [Service]
 Slice=horizon-ci.slice
 WorkingDirectory=$dir
 ExecStart=/usr/bin/env bash $dir/linux-runner.sh run
-Nice=10
+Nice=19
 # runsvc.sh hands SIGTERM to the runner, which stops after cancelling its job; then the rest (Xvfb) goes.
 KillMode=mixed
 KillSignal=SIGTERM
 TimeoutStopSec=5min
 Restart=on-failure
 RestartSec=30
-[Install]
-WantedBy=default.target
 EOF
   cat > "$units/horizon-runner-pause.service" <<EOF
 [Unit]
-Description=Pauses the Horizon CI runner while a game runs
+Description=Runs the Horizon CI runner only while nobody is at the screen or playing
 [Service]
-ExecStart=$(command -v python3) $dir/runner-pause.py
+ExecStart=$(command -v python3) $dir/runner_pause.py
 Restart=always
 RestartSec=10
 [Install]
@@ -149,15 +164,20 @@ EOF
     sudo -n loginctl enable-linger "$USER" || echo "Run once: sudo loginctl enable-linger $USER"
   fi
   systemctl --user daemon-reload
-  systemctl --user enable horizon-runner.service horizon-runner-pause.service > /dev/null
+  # Only the watcher starts the runner (never the boot itself): it decides whether anyone is at the screen.
+  systemctl --user enable horizon-runner-pause.service > /dev/null
+  # The runner reads .env when it starts: stop it, unless it is in a job (that would cancel the job); the watcher
+  # starts it again when it may run.
+  if pgrep -f "$dir/bin/Runner.Worker" > /dev/null; then echo "In a job: stop horizon-runner.service after it"
+  else systemctl --user stop horizon-runner.service; rm -f "$dir/paused"; fi
   systemctl --user restart horizon-runner-pause.service
-  [ -e "$dir/paused" ] || systemctl --user start horizon-runner.service
   status
 }
 
 run() {
   cd "$dir"
   fix_shebangs
+  parity_host_links
   if command -v vscreen > /dev/null; then
     eval "$(display_env)"
   else
diff --git a/tools/ci/runner-pause.py b/tools/ci/runner_pause.py
similarity index 51%
rename from tools/ci/runner-pause.py
rename to tools/ci/runner_pause.py
index 4a88c6ae4..57f304f1f 100755
--- a/tools/ci/runner-pause.py
+++ b/tools/ci/runner_pause.py
@@ -1,19 +1,22 @@
 #!/usr/bin/env python3
-"""Pauses the Horizon CI runner (tools/ci/linux-runner.sh) while the maintainer plays a game on this machine.
+"""Pauses the Horizon CI runner (tools/ci/linux-runner.sh) while the maintainer is at this machine or plays on it.
 
-A game is running when any of these holds:
-  - fleet-load says so (~/fleet/load: Steam, gamescope, Wine or Proton processes);
+The runner works only while nobody is at the screen (rule of 2026-10-25, after ludodesktop was restarted under a
+CI load while he used it). It pauses when any of these holds:
+  - a graphical session is open on seat0, locked or not: what `~/fleet/power status` calls "IN USE";
+  - fleet-load says a game runs (~/fleet/load: Steam, gamescope, Wine or Proton processes);
   - a process of his matches GAME below (the same, plus Minecraft and a Horizon game he started himself);
-  - a process outside horizon-ci.slice keeps the GPU busy (nvidia-smi: SM use >= GPU_BUSY % twice in a row);
+  - a process outside horizon-ci.slice keeps the GPU busy (nvidia-smi: SM use >= GPU_BUSY %, default 50, in two
+    samples in a row; the browser, Discord and the compositor stay under 20 %);
   - ~/.actions-runners/horizon/pause exists (pause by hand: `touch` it; `rm` it to let the watcher decide).
 
 Paused, the runner takes no new job: while it is idle its service is stopped, so GitHub sends the jobs to the
-Mac mini. A job already running is throttled, not stopped: horizon-ci.slice (the job, and the parity workers other machines
-send here) drops to CPU weight 1, I/O weight 1
-and a quota of THROTTLE_CPUS threads, and the service stops once the job ends. Freezing it (SIGSTOP or the cgroup
-freezer) would stop the runner's heartbeat, so GitHub would drop the job as lost, and the harnesses' wall-clock
-timeouts would fail runs that were only waiting. The runner comes back RESUME_AFTER seconds after the last sign
-of a game. Every change is written to ~/.actions-runners/horizon/pause.log.
+Mac mini, and the parity workers other machines started here stop (their harnesses go back to those machines). A
+job already running is throttled, not stopped: horizon-ci.slice drops to CPU weight 1, I/O weight 1 and a quota of
+THROTTLE_CPUS threads, and the service stops once the job ends. Freezing it (SIGSTOP or the cgroup freezer)
+would stop the runner's heartbeat, so GitHub would drop the job as lost, and the harnesses' wall-clock timeouts
+would fail runs that were only waiting. The runner comes back RESUME_AFTER seconds after the last of these signs.
+Every change is written to ~/.actions-runners/horizon/pause.log.
 """
 import json
 import os
@@ -27,7 +30,7 @@ SERVICE, SLICE = "horizon-runner.service", "horizon-ci.slice"
 MANUAL, STATE, LOG = DIR / "pause", DIR / "paused", DIR / "pause.log"
 GAME = re.compile(r"(SteamLaunch|gamescope|wine64-preloader|wineserver|wine-preloader|\.exe(\s|$)|proton\b"
                   r"|net\.minecraft\.client\.main\.Main|minecraft-launcher|prismlauncher)", re.I)
-GPU_BUSY = int(os.environ.get("GPU_BUSY", 30))
+GPU_BUSY = int(os.environ.get("GPU_BUSY", 50))
 INTERVAL = int(os.environ.get("INTERVAL", 15))
 RESUME_AFTER = int(os.environ.get("RESUME_AFTER", 300))
 THROTTLE_CPUS = int(os.environ.get("THROTTLE_CPUS", 2))
@@ -50,6 +53,16 @@ def ci_process(pid):
         return True  # gone
 
 
+def at_the_screen():
+    """A graphical login on seat0, as ~/fleet/power status counts it (a locked screen counts too)."""
+    sessions = subprocess.run(["loginctl", "list-sessions", "--no-legend"], capture_output=True, text=True).stdout
+    for line in sessions.splitlines():
+        fields = line.split()
+        if "seat0" in fields:
+            return f"session {fields[0]} of {fields[2] if len(fields) > 2 else '?'} at the screen (seat0)"
+    return None
+
+
 def fleet_load_gaming():
     status = Path(os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{os.getuid()}")) / "fleet-load" / "status.json"
     try:
@@ -82,7 +95,8 @@ def game_process():
 def gpu_users():
     """Processes outside the CI slice using the GPU's shader cores, as {pid: SM %}."""
     try:
-        output = subprocess.run(["nvidia-smi", "pmon", "-c", "1", "-s", "u"], capture_output=True, text=True,
+        # Two samples: the first one nvidia-smi prints has no utilisation yet.
+        output = subprocess.run(["nvidia-smi", "pmon", "-c", "2", "-s", "u"], capture_output=True, text=True,
                                 timeout=20).stdout
     except (OSError, subprocess.TimeoutExpired):
         return {}
@@ -92,7 +106,7 @@ def gpu_users():
         if line.startswith("#") or len(fields) < 4 or not fields[1].isdigit() or not fields[3].isdigit():
             continue
         if not ci_process(int(fields[1])):
-            users[int(fields[1])] = int(fields[3])
+            users[int(fields[1])] = max(users.get(int(fields[1]), 0), int(fields[3]))
     return users
 
 
@@ -119,47 +133,60 @@ def throttle(on):
         systemctl("set-property", "--runtime", SLICE, "CPUWeight=20", "IOWeight=20", "CPUQuota=")
 
 
+def pause_reason(hot):
+    """Why the runner may not work now, or None. hot: the GPU users seen busy at the last sample (updated)."""
+    if MANUAL.exists():
+        return f"paused by hand ({MANUAL})"
+    reason = at_the_screen() or fleet_load_gaming() or game_process()
+    if reason:
+        return reason
+    busy = {pid for pid, sm in gpu_users().items() if sm >= GPU_BUSY}
+    twice = sorted(busy & set(hot))
+    hot.clear()
+    hot.update(dict.fromkeys(busy))
+    if twice:
+        try:
+            name = Path(f"/proc/{twice[0]}/comm").read_text().strip()
+        except OSError:
+            name = "?"
+        return f"GPU busy: process {twice[0]} ({name})"
+    return None
+
+
 def main():
-    hot = {}  # GPU users seen busy at the last sample
-    last_game = 0.0
-    paused = STATE.exists()
+    hot = {}
+    # A boot (or a restart of this watcher) counts as a sign: the runner starts RESUME_AFTER seconds later at the
+    # earliest, which leaves time to log in after switching the machine on.
+    last_sign = time.monotonic()
+    paused = None
     while True:
-        reason = None
-        if MANUAL.exists():
-            reason = "paused by hand (" + str(MANUAL) + ")"
-        reason = reason or fleet_load_gaming() or game_process()
-        if not reason:
-            busy = {pid for pid, sm in gpu_users().items() if sm >= GPU_BUSY}
-            twice = busy & set(hot)
-            hot = dict.fromkeys(busy)
-            if twice:
-                pid = min(twice)
-                try:
-                    name = Path(f"/proc/{pid}/comm").read_text().strip()
-                except OSError:
-                    name = "?"
-                reason = f"GPU busy: process {pid} ({name})"
+        reason = pause_reason(hot)
         now = time.monotonic()
         if reason:
-            last_game = now
-        if reason and not paused:
-            paused = True
-            STATE.write_text(reason + "\n")
-            throttle(True)  # also what other machines' parity workers run here meanwhile
-            if runner_busy():
-                log(f"pause: {reason}; a job is running: throttled to {THROTTLE_CPUS} threads, stops after it")
-            else:
+            last_sign = now
+        active = systemctl("is-active", "--quiet", SERVICE).returncode == 0
+        if reason or now - last_sign < RESUME_AFTER:
+            if paused is not True:
+                paused = True
+                STATE.write_text((reason or "starting") + "\n")
+                throttle(True)
+                # Parity workers other machines started here (tools/parity_hosts.json): they stop, and those
+                # machines run the harnesses themselves.
+                systemctl("stop", "horizon-parity-worker-*.scope")
+                log(f"pause: {reason or 'waiting ' + str(RESUME_AFTER) + ' s after starting'}"
+                    + (f"; a job is running: throttled to {THROTTLE_CPUS} threads, stops after it" if active else ""))
+            if active and not runner_busy():
                 systemctl("stop", SERVICE)
-                log(f"pause: {reason}; runner stopped")
-        elif paused and reason is None and now - last_game >= RESUME_AFTER:
-            paused = False
-            STATE.unlink(missing_ok=True)
-            throttle(False)
-            systemctl("start", SERVICE)
-            log(f"resume: no game for {RESUME_AFTER} s; runner started")
-        elif paused and systemctl("is-active", "--quiet", SERVICE).returncode == 0 and not runner_busy():
-            systemctl("stop", SERVICE)
-            log("the job ended: runner stopped until the game ends")
+                log("runner stopped")
+        else:
+            if paused is not False:
+                paused = False
+                STATE.unlink(missing_ok=True)
+                throttle(False)
+                log(f"resume: nobody at the screen and no game for {RESUME_AFTER} s")
+            if not active:
+                systemctl("start", SERVICE)
+                log("runner started")
         time.sleep(INTERVAL)
 
 
diff --git a/tools/parity_hosts.json b/tools/parity_hosts.json
index 0aa013a5b..5d561175d 100644
--- a/tools/parity_hosts.json
+++ b/tools/parity_hosts.json
@@ -11,6 +11,15 @@
    "jobs": 14,
    "exclude": {}
   },
+  "desktop": {
+   "ssh": "desktop",
+   "root": ".actions-runners/horizon/parity-host",
+   "shell": "systemd-run --user --scope --quiet --slice=horizon-ci.slice --unit=horizon-parity-worker-$$ bash -c",
+   "setup": "test ! -e ~/.actions-runners/horizon/paused && set -a && . ~/.actions-runners/horizon/.env && set +a && export PATH=$(cat ~/.actions-runners/horizon/.path) && eval \"$(vscreen env)\"",
+   "jobs": 8,
+   "nice": 19,
+   "note": "ludodesktop, the maintainer's own machine: only while nobody is at the screen (tools/ci/runner_pause.py: a paused desktop refuses workers and stops the running ones, whose harnesses then run here); 8 jobs at most, in the CI runner's environment and slice"
+  },
   "thinkpad": {
    "ssh": "thinkpad",
    "root": "code/horizon-parity",

From 28206976d8f301e834f47d85071820214a732bb7 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:04:23 +0000
Subject: [PATCH 210/270] Move parity fixtures onto server execution

Co-Authored-By: OpenAI Codex (GPT-6.1) <noreply@openai.com>
---
 crates/horizon-client/src/game.rs             |  22 ++-
 .../src/game/command_harness.rs               | 141 ++++++++++++++----
 crates/horizon-client/src/game/commands.rs    |   3 +-
 .../horizon-client/src/game/commands/extra.rs |  28 +++-
 .../src/game/dispense_fixture.rs              |   4 +
 crates/horizon-client/src/game/integrated.rs  |  57 ++++++-
 crates/horizon-client/src/game/levels.rs      |  18 ++-
 crates/horizon-client/src/game/remote.rs      |  17 +++
 .../horizon-client/src/game/sculk_fixture.rs  |   4 +
 .../horizon-client/src/game/server_travel.rs  |   2 +-
 docs/parity-workflow.md                       |  28 ++++
 tools/command_exec_corpus.py                  |  23 ++-
 tools/lan_e2e.py                              |  39 +++++
 tools/test_command_exec_parity.py             |   4 +-
 tools/test_dispenser_parity.py                |   2 +-
 tools/test_sculk_parity.py                    |   2 +-
 16 files changed, 338 insertions(+), 56 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f5803ad08..30c1cb5b1 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -348,10 +348,7 @@ impl Options {
             dedicated: None,
             benchmark: None,
             dev_mods: Vec::new(),
-            // The command harness (HORIZON_COMMAND_SCRIPT) drives the world
-            // itself, without the event loop: it stays in the frame.
-            server_thread: std::env::var("HORIZON_SERVER_THREAD").map_or(true, |v| v != "0")
-                && std::env::var_os("HORIZON_COMMAND_SCRIPT").is_none(),
+            server_thread: std::env::var("HORIZON_SERVER_THREAD").map_or(true, |v| v != "0"),
             execution_role: execution_role::ExecutionRole::Client,
         };
         let mut session_file = std::env::var("HORIZON_SESSION_FILE").ok();
@@ -12935,11 +12932,11 @@ fn start_game<'a>(
         );
     }
     if let Ok(spec) = std::env::var("HORIZON_DISPENSE_FIXTURE") {
-        game.dispense_fixture(&spec)?;
+        game.run_component_harness(integrated::ComponentHarness::Dispenser(spec))?;
         return Ok(None);
     }
     if let Ok(spec) = std::env::var("HORIZON_SCULK_FIXTURE") {
-        game.sculk_fixture(&spec)?;
+        game.run_component_harness(integrated::ComponentHarness::Sculk(spec))?;
         return Ok(None);
     }
     if game.options.execution_role == execution_role::ExecutionRole::DedicatedServer {
@@ -12961,8 +12958,8 @@ fn start_game<'a>(
         Some(folder) => {
             let (seed, creative) = (game.options.seed, game.options.creative);
             if std::env::var_os("HORIZON_COMMAND_SCRIPT").is_some() {
-                // The command harness runs before entering the window loop.
-                game.open_world(&folder, None, Some(seed), creative, None)?;
+                // Headless, but with the same server and memory connection as play.
+                game.open_integrated(&folder, None, Some(seed), creative, None)?;
             } else {
                 // Start after the window is handed over, so --world uses the
                 // same responsive initialization path as the title screen.
@@ -12989,11 +12986,10 @@ fn start_game<'a>(
             game.title = Some(title);
         }
     }
-    if let (Some(script), Some(output)) = (
-        std::env::var_os("HORIZON_COMMAND_SCRIPT"),
-        std::env::var_os("HORIZON_COMMAND_OUTPUT"),
-    ) {
-        game.run_command_harness(script.as_ref(), output.as_ref())?;
+    if std::env::var_os("HORIZON_COMMAND_SCRIPT").is_some()
+        && std::env::var_os("HORIZON_COMMAND_OUTPUT").is_some()
+    {
+        game.wait_command_harness()?;
         return Ok(None);
     }
     Ok(Some(game))
diff --git a/crates/horizon-client/src/game/command_harness.rs b/crates/horizon-client/src/game/command_harness.rs
index 096ba1c74..33b99cc14 100644
--- a/crates/horizon-client/src/game/command_harness.rs
+++ b/crates/horizon-client/src/game/command_harness.rs
@@ -1,6 +1,7 @@
 //! Headless command runner for `tools/test_command_exec_parity.py`: with
 //! `HORIZON_COMMAND_SCRIPT` and `HORIZON_COMMAND_OUTPUT` set, the opened world
-//! runs without a window. Each script line is a JSON operation: `cmd` runs a
+//! runs on its server thread with a connected, headless client. Each script
+//! line is a JSON operation: `cmd` runs a
 //! command as the player (Commands.performPrefixedCommand) and records every
 //! system message it produced, as styled spans, with the results reported to
 //! the player's `CommandResultCallback`; `tick` advances the game; `settle`
@@ -41,30 +42,100 @@ pub(super) fn spans(text: &Text) -> Value {
 }
 
 impl Game<'_> {
+    /// Pump the real client's connection, without predicting movement: the
+    /// oracle's player stays where commands put it. Errors cross the server
+    /// boundary through Integrated::stop, including script and save failures.
+    pub(super) fn wait_command_harness(&mut self) -> Result<()> {
+        let server = self.integrated.take().ok_or("command harness: no server")?;
+        while !server.stopped() {
+            self.poll_stationary_client()?;
+            std::thread::sleep(Duration::from_millis(2));
+        }
+        server.stop()
+    }
+
+    /// The owner's authoritative body and level, using the same swaps as a
+    /// server command. Always put them back, also when a script operation fails.
+    fn harness_owner<T>(&mut self, f: impl FnOnce(&mut Self) -> Result<T>) -> Result<T> {
+        let owner = self
+            .serving
+            .as_ref()
+            .ok_or("command harness: not a server")?
+            .owner;
+        let mut host = self.lan.take().ok_or("command harness: no hub")?;
+        let guest = host.hub.guests.iter().find(|g| g.uuid == owner && g.placed);
+        let Some(guest) = guest else {
+            self.lan = Some(host);
+            return Err("command harness: owner is not connected".into());
+        };
+        let (conn, dim, back) = (guest.conn, super::Dim::from_id(&guest.dimension), self.dim);
+        if let Err(error) = self.enter_level(Some(&mut host), dim) {
+            self.lan = Some(host);
+            return Err(error);
+        }
+        let swap = self
+            .enter_guest(&mut host, conn)
+            .expect("the owner is not already acting");
+        self.lan = Some(host);
+        let result = f(self);
+        let mut host = self.lan.take().expect("the operation puts the hub back");
+        self.leave_guest(&mut host, swap);
+        host.hub.sync_all_effects();
+        self.run_level_teleports(&mut host);
+        let restored = self.enter_level(Some(&mut host), back);
+        self.lan = Some(host);
+        restored?;
+        result
+    }
+
     /// The player's portal process finished in the nether portal it stands
     /// in (the oracle's player is not ticked, so neither is the wait).
     fn harness_portal(&mut self) -> Result<()> {
-        let Some(p) = &self.player else {
-            return Err("command harness: portal without a player".into());
-        };
-        let entry = horizon_core::position::BlockPos::containing(p.position);
-        let block = self.world.block(entry.x, entry.y, entry.z);
-        if &*self.res.facts().get(block).name != "minecraft:nether_portal" {
-            return Err("command harness: the player is not in a nether portal".into());
-        }
-        self.player_through_nether_portal(entry)
+        let (conn, plan) = self.harness_owner(|g| {
+            let p = g
+                .player
+                .as_ref()
+                .ok_or("command harness: portal without a player")?;
+            let entry = horizon_core::position::BlockPos::containing(p.position);
+            let block = g.world.block(entry.x, entry.y, entry.z);
+            if &*g.res.facts().get(block).name != "minecraft:nether_portal" {
+                return Err("command harness: the player is not in a nether portal".into());
+            }
+            let plan = g.portal_plan(
+                entry,
+                p.position,
+                p.dimensions.width,
+                p.dimensions.height,
+                true,
+            );
+            Ok((
+                g.lan_acting.ok_or("command harness: no acting owner")?,
+                plan,
+            ))
+        })?;
+        // Start travel after restoring the owner's body: change_level updates
+        // its hub record, which leave_guest would otherwise overwrite.
+        self.in_owner_level(|g| {
+            let mut host = g.lan.take().ok_or("command harness: no hub")?;
+            g.start_server_trip(&mut host, conn, plan.dim, Some(plan));
+            g.lan = Some(host);
+            Ok(())
+        })
     }
     /// Load terrain until the player stands in lit chunks.
     fn harness_settle(&mut self, deadline: Instant) -> Result<()> {
         loop {
             self.update_world();
-            self.spawn_player()?;
             if let Some(p) = &self.player {
                 let (cx, cz) = (
                     (p.position.x.floor() as i32) >> 4,
                     (p.position.z.floor() as i32) >> 4,
                 );
-                if (-1..=1).all(|dz| (-1..=1).all(|dx| self.streaming.is_lit(cx + dx, cz + dz))) {
+                // Finish requested terrain before inspecting it, so worker
+                // timing cannot change which command positions are loaded.
+                if !self.streaming.busy()
+                    && (-1..=1).all(|dz| (-1..=1).all(|dx| self.streaming.is_lit(cx + dx, cz + dz)))
+                {
                     // The oracle's settle also waits for the entities saved
                     // in those chunks (areEntitiesActuallyLoadedAndTicking):
                     // after a dimension change they come back from the save.
@@ -95,7 +166,19 @@ impl Game<'_> {
                     .and_then(|v| v.parse().ok())
                     .unwrap_or(600),
             );
-        self.harness_settle(deadline)?;
+        // Join/configuration uses the normal hub, but never advances the world.
+        while !self
+            .lan
+            .as_ref()
+            .is_some_and(|h| h.hub.guests.iter().any(|g| g.placed && g.loaded))
+        {
+            self.tick_server(true)?;
+            if Instant::now() > deadline {
+                return Err("command harness: owner did not connect".into());
+            }
+            std::thread::sleep(Duration::from_millis(2));
+        }
+        self.harness_owner(|g| g.harness_settle(deadline))?;
         let mut out = String::new();
         for line in std::fs::read_to_string(script)?.lines() {
             if line.trim().is_empty() {
@@ -107,9 +190,12 @@ impl Game<'_> {
                     let command = op["cmd"].as_str().unwrap_or("");
                     self.chat_capture = Some(Vec::new());
                     self.cmds.results = Some(Vec::new());
-                    self.as_console(|g| {
-                        g.run_command(command.strip_prefix('/').unwrap_or(command))
-                    });
+                    self.harness_owner(|g| {
+                        g.as_console(|g| {
+                            g.run_command(command.strip_prefix('/').unwrap_or(command))
+                        });
+                        Ok(())
+                    })?;
                     let messages = self.chat_capture.take().unwrap_or_default();
                     let results = self.cmds.results.take().unwrap_or_default();
                     if op["record"].as_bool() != Some(false) {
@@ -124,17 +210,8 @@ impl Game<'_> {
                 }
                 "tick" => {
                     self.chat_capture = Some(Vec::new());
-                    // The oracle's player has no client moving it: hold the
-                    // player where commands put it while the game ticks.
-                    let held = self.player.as_ref().map(|p| p.position);
                     for _ in 0..op["n"].as_u64().unwrap_or(1) {
-                        self.update_world();
-                        self.tick()?;
-                        if let (Some(p), Some(at)) = (self.player.as_mut(), held) {
-                            p.position = at;
-                            p.velocity = horizon_core::geometry::Vec3::new(0.0, 0.0, 0.0);
-                            p.fall_distance = 0.0;
-                        }
+                        self.tick_server(false)?;
                     }
                     let messages = self.chat_capture.take().unwrap_or_default();
                     if op["record"].as_bool() == Some(true) {
@@ -147,7 +224,17 @@ impl Game<'_> {
                         out.push('\n');
                     }
                 }
-                "settle" => self.harness_settle(deadline)?,
+                "settle" => {
+                    // Finish portal arrivals using connection-only passes too.
+                    while !self.server_trips.is_empty() {
+                        self.tick_server(true)?;
+                        if Instant::now() > deadline {
+                            return Err("command harness: portal did not arrive".into());
+                        }
+                        std::thread::sleep(Duration::from_millis(2));
+                    }
+                    self.harness_owner(|g| g.harness_settle(deadline))?;
+                }
                 "portal" => self.harness_portal()?,
                 other => return Err(format!("command harness: unknown op {other}").into()),
             }
diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index 69c06d97e..c456c9743 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -751,7 +751,8 @@ impl Game<'_> {
                     && !id.ends_with("get")
                     && let Ok(t) = self.entities(ctx, "target", false)
                 {
-                    self.cmds.waypoint_dirty.push(t[0]);
+                    let target = self.waypoint_target(t[0]);
+                    self.cmds.waypoint_dirty.push(target);
                 }
                 result
             }
diff --git a/crates/horizon-client/src/game/commands/extra.rs b/crates/horizon-client/src/game/commands/extra.rs
index ef69be6d9..7536c9503 100644
--- a/crates/horizon-client/src/game/commands/extra.rs
+++ b/crates/horizon-client/src/game/commands/extra.rs
@@ -212,8 +212,22 @@ impl Game<'_> {
 
     // ---- /waypoint ------------------------------------------------------
 
+    /// A guest's body is only `Player` during its turn; retained command state
+    /// must use its connection so the next server tick still finds that body.
+    pub(super) fn waypoint_target(&self, t: Target) -> Target {
+        match t {
+            Target::Player => self.lan_acting.map_or(t, Target::Guest),
+            _ => t,
+        }
+    }
+
     /// A living entity's `waypoint_transmit_range` (`isTransmittingWaypoint`).
     fn transmit_range(&mut self, t: Target) -> f64 {
+        if matches!(t, Target::Guest(_)) {
+            return self
+                .for_player(t, |g| g.transmit_range(Target::Player))
+                .unwrap_or(0.0);
+        }
         if t == Target::Player {
             return self
                 .player
@@ -242,7 +256,7 @@ impl Game<'_> {
     fn waypoint_transmitters(&mut self) -> Vec<Target> {
         if self.cmds.waypoints.is_none() {
             let tracked = if self.transmit_range(Target::Player) > 0.0 {
-                vec![Target::Player]
+                vec![self.waypoint_target(Target::Player)]
             } else {
                 Vec::new()
             };
@@ -255,6 +269,12 @@ impl Game<'_> {
             .collect();
         self.cmds.waypoints = Some(alive.clone());
         alive
+            .into_iter()
+            .map(|t| match t {
+                Target::Guest(conn) if self.lan_acting == Some(conn) => Target::Player,
+                _ => t,
+            })
+            .collect()
     }
     /// The waypoint part of a living entity's tick: dirty transmit ranges
     /// track or untrack it.
@@ -277,7 +297,7 @@ impl Game<'_> {
     fn waypoint_icon(&self, t: Target) -> WaypointIcon {
         self.cmds
             .waypoint_icons
-            .get(&t)
+            .get(&self.waypoint_target(t))
             .cloned()
             .unwrap_or_default()
     }
@@ -387,6 +407,7 @@ impl Game<'_> {
                 &[Text::colored(name, rgb)],
             )
         };
+        let t = self.waypoint_target(t);
         self.cmds.waypoint_icons.insert(t, icon);
         // WaypointCommand.mutateIcon: untrack, change, track again.
         self.waypoint_transmitters();
@@ -606,6 +627,7 @@ impl Game<'_> {
                 .hub
                 .guests
                 .iter()
+                .filter(|g| lan.hub.singleplayer_owner != Some(g.uuid))
                 .filter(|g| match &s.player_name {
                     Some(name) => g.name.eq_ignore_ascii_case(name),
                     None => s.kind == 'a' || s.kind == 'e',
@@ -617,7 +639,7 @@ impl Game<'_> {
         if host.is_empty() && guests.is_empty() {
             return Err(err("argument.entity.notfound.player", &[]));
         }
-        if self.lan.is_none() {
+        if self.lan.is_none() || (self.serving() && self.published_port().is_none()) {
             return Err(err("commands.kick.singleplayer.failed", &[]));
         }
         let reason_raw = match ctx.get("reason") {
diff --git a/crates/horizon-client/src/game/dispense_fixture.rs b/crates/horizon-client/src/game/dispense_fixture.rs
index 752785084..267f323c3 100644
--- a/crates/horizon-client/src/game/dispense_fixture.rs
+++ b/crates/horizon-client/src/game/dispense_fixture.rs
@@ -90,6 +90,10 @@ enum Target {
 impl Game<'_> {
     /// Run every case of `spec` ("CASES,OUTPUT") and write the results.
     pub(super) fn dispense_fixture(&mut self, spec: &str) -> Result<()> {
+        assert!(
+            !self.options.execution_role.is_client(),
+            "fixture requires a server Game"
+        );
         let (input, output) = spec
             .split_once(',')
             .ok_or("HORIZON_DISPENSE_FIXTURE=CASES,OUTPUT")?;
diff --git a/crates/horizon-client/src/game/integrated.rs b/crates/horizon-client/src/game/integrated.rs
index d4726f2f1..abe6df9b3 100644
--- a/crates/horizon-client/src/game/integrated.rs
+++ b/crates/horizon-client/src/game/integrated.rs
@@ -143,7 +143,7 @@ pub(super) struct Serving {
     flags: Arc<Flags>,
     tasks: Receiver<Task>,
     /// The window's profile.
-    owner: u128,
+    pub(super) owner: u128,
     /// Open to LAN or closed from inside a player's command, while the hub
     /// is out of its place: applied after the tick.
     pending: Option<Publish>,
@@ -357,6 +357,16 @@ impl Game<'_> {
         });
         let _ = ready.send(Ok((pipe, self.level.name.clone())));
         self.settle_spawn()?;
+        if let (Some(script), Some(output)) = (
+            std::env::var_os("HORIZON_COMMAND_SCRIPT"),
+            std::env::var_os("HORIZON_COMMAND_OUTPUT"),
+        ) {
+            // The script owns the clock: connection setup and terrain loading
+            // cannot add wall-clock-dependent world ticks to oracle output.
+            let result = self.run_command_harness(script.as_ref(), output.as_ref());
+            let stopped = self.stop_integrated();
+            return result.and(stopped);
+        }
         let mut next = Instant::now();
         while !flags.stop.load(Ordering::Relaxed) {
             self.run_tasks();
@@ -692,6 +702,48 @@ fn serve(
     tasks: Receiver<Task>,
     ready: &Sender<Ready>,
 ) -> Result<()> {
+    let mut server = server_game(res, pack, options, settings)?;
+    server.run_integrated(launch, flags, tasks, ready)
+}
+
+/// Component oracles supply their own synthetic levels and entity phases.
+/// They still execute on a server Game, never the client's world.
+pub(super) enum ComponentHarness {
+    Dispenser(String),
+    Sculk(String),
+}
+
+impl Game<'_> {
+    pub(super) fn run_component_harness(&self, fixture: ComponentHarness) -> Result<()> {
+        let (res, pack, settings) = (self.res.clone(), self.pack.clone(), self.settings.clone());
+        let mut options = self.options.clone();
+        options.execution_role = ExecutionRole::IntegratedServer;
+        options.dedicated = Some(Vec::new());
+        options.server_thread = false;
+        let result = std::thread::Builder::new()
+            .name("Server thread".into())
+            .spawn(move || {
+                let run = || -> Result<()> {
+                    let mut server = server_game(&res, pack, options, settings)?;
+                    match fixture {
+                        ComponentHarness::Dispenser(spec) => server.dispense_fixture(&spec),
+                        ComponentHarness::Sculk(spec) => server.sculk_fixture(&spec),
+                    }
+                };
+                run().map_err(|e| e.to_string())
+            })?
+            .join()
+            .map_err(|_| "the component harness server panicked")?;
+        result.map_err(Into::into)
+    }
+}
+
+fn server_game(
+    res: &Arc<Resources>,
+    pack: PackResources,
+    options: Options,
+    settings: Settings,
+) -> Result<Game<'_>> {
     // It draws nothing: only the font, which books and chat measure with.
     let atlas = HudAtlas::fonts(&options.resources)?;
     let gui = UiResources {
@@ -702,8 +754,7 @@ fn serve(
         }),
     };
     let audio = Audio::silent(&options.resources);
-    let mut server = Game::new(res, pack, gui, options, settings, audio, None)?;
-    server.run_integrated(launch, flags, tasks, ready)
+    Game::new(res, pack, gui, options, settings, audio, None)
 }
 
 #[cfg(test)]
diff --git a/crates/horizon-client/src/game/levels.rs b/crates/horizon-client/src/game/levels.rs
index f685200f2..6f29f9371 100644
--- a/crates/horizon-client/src/game/levels.rs
+++ b/crates/horizon-client/src/game/levels.rs
@@ -21,7 +21,7 @@ use super::{
 use horizon_client::{
     Result, block_entity_anim::BlockEntityAnims, random_tick_sections::RandomTickSections,
     save::SaveDir, streaming::Streaming, tick_chunk_membership::TickChunkMembership,
-    ticket_levels::ChunkTickets, world::World,
+    ticket_levels::ChunkTickets, vanillagen::VanillaTerrain, world::World,
 };
 use horizon_world::level::{LevelEvent, Ticks};
 use std::{
@@ -39,6 +39,7 @@ const IDLE_TICKS: u32 = 300;
 pub(super) struct Parked {
     world: World,
     streaming: Streaming,
+    locator: Option<Arc<VanillaTerrain>>,
     save: Arc<SaveDir>,
     block_ticks: Ticks,
     tick_chunks: TickChunkMembership,
@@ -109,13 +110,21 @@ pub(super) struct Levels {
 impl Game<'_> {
     /// A new level for `dim`, opened from the save (`MinecraftServer.createLevels`).
     fn open_level(&self, dim: Dim) -> Result<Parked> {
-        let (streaming, save) =
-            self.make_streaming(&self.world_root.clone(), dim, self.level.seed)?;
+        let (streaming, save, locator) = super::world_loading::make_streaming(
+            &self.res,
+            &self.pack,
+            &self.options,
+            &self.settings,
+            &self.world_root,
+            dim,
+            self.level.seed,
+        )?;
         let mut world = World::new(self.res.facts().air, self.level.seed);
         world.fast_lava = dim == Dim::Nether;
         Ok(Parked {
             world,
             streaming,
+            locator,
             save,
             block_ticks: Ticks::new(self.level.seed as i32),
             tick_chunks: Default::default(),
@@ -163,6 +172,9 @@ impl Game<'_> {
         use std::mem::swap;
         swap(&mut self.world, &mut p.world);
         swap(&mut self.streaming, &mut p.streaming);
+        let mut locator = self.end.locator();
+        swap(&mut locator, &mut p.locator);
+        self.end.set_locator(locator);
         swap(&mut self.save, &mut p.save);
         swap(&mut self.block_ticks, &mut p.block_ticks);
         swap(&mut self.tick_chunks, &mut p.tick_chunks);
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index c89773a5d..6ee8ed278 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -684,6 +684,23 @@ impl Game<'_> {
     pub(super) fn remote_backlog(&self) -> usize {
         self.remote.as_ref().map_or(0, |r| r.backlog.len())
     }
+    /// A headless command oracle has a real connection but no movement tick.
+    /// Acknowledge loaded terrain without predicting or sending movement.
+    pub(super) fn poll_stationary_client(&mut self) -> Result<()> {
+        self.poll_remote()?;
+        let loaded = self.player.as_ref().is_some_and(|p| {
+            self.streaming.is_lit(
+                (p.position.x.floor() as i32) >> 4,
+                (p.position.z.floor() as i32) >> 4,
+            )
+        });
+        if loaded && self.remote.as_ref().is_some_and(|r| !r.loaded_sent) {
+            self.send(S::PlayerLoaded(Empty));
+            self.remote.as_mut().unwrap().loaded_sent = true;
+        }
+        Ok(())
+    }
+
     /// Process what the network thread received (once per frame, like the
     /// client's packet processor), in order. Chunk packets get
     /// `CHUNK_PACKETS_PER_FRAME`: once a frame has spent it, the events from
diff --git a/crates/horizon-client/src/game/sculk_fixture.rs b/crates/horizon-client/src/game/sculk_fixture.rs
index b02dfe998..58e29066d 100644
--- a/crates/horizon-client/src/game/sculk_fixture.rs
+++ b/crates/horizon-client/src/game/sculk_fixture.rs
@@ -156,6 +156,10 @@ const CLIENT_SOUNDS: &[&str] = &[
 impl Game<'_> {
     /// Run every scenario of `spec` ("SCENARIOS,OUTPUT") and write the results.
     pub(super) fn sculk_fixture(&mut self, spec: &str) -> Result<()> {
+        assert!(
+            !self.options.execution_role.is_client(),
+            "fixture requires a server Game"
+        );
         let (input, output) = spec
             .split_once(',')
             .ok_or("HORIZON_SCULK_FIXTURE=SCENARIOS,OUTPUT")?;
diff --git a/crates/horizon-client/src/game/server_travel.rs b/crates/horizon-client/src/game/server_travel.rs
index 02b94c0f6..158b2301e 100644
--- a/crates/horizon-client/src/game/server_travel.rs
+++ b/crates/horizon-client/src/game/server_travel.rs
@@ -170,7 +170,7 @@ impl Game<'_> {
     /// The player moves to `target`'s level (opened if nobody was there)
     /// and is told it is there, at the approximate exit, while it loads. The
     /// level whose tick is running is put back in place afterwards.
-    fn start_server_trip(
+    pub(super) fn start_server_trip(
         &mut self,
         host: &mut LanHost,
         conn: u32,
diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index f9f222071..52a5a030f 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -74,6 +74,34 @@ An agent working an area merges the integration branch first, uses `tools/parity
 
 On ludodesktop, source `~/code/horizon-parity/env.sh` first: it sets the ALSA build path and the Cargo job cap. Debug builds carry line tables only (`[profile.dev]` in `Cargo.toml`), which keeps backtraces readable while keeping each worktree's build small; a fresh worktree builds `horizon-client` and its tests in under a minute.
 
+## Server execution in game fixtures
+
+`HORIZON_COMMAND_SCRIPT` runs on the integrated server's `Server thread`, with the
+headless client joined through the normal memory connection. Commands use the connected
+owner's body and dimension. The script owns the clock: each `tick` calls `tick_server`,
+while login and portal arrival pump connection-only passes. The client acknowledges
+terrain and teleports without predicting movement, matching the command oracle's stationary
+player. Script and save errors return through server shutdown; output keeps the existing
+styled messages and `CommandResultCallback` schema. `--in-frame` is not needed.
+
+`HORIZON_DISPENSE_FIXTURE` and `HORIZON_SCULK_FIXTURE` are component probes. They construct
+a server `Game` on a server thread and retain the oracles' synthetic levels, seeded random
+streams and explicit entity/block phases. A synthetic sculk player controls warning levels,
+not client input; dispenser probes call one activation without running unrelated world ticks.
+Keep those controls when extending the fixtures. Player interactions belong in connected-client
+coverage alongside the components:
+
+```sh
+python3 tools/test_command_exec_parity.py
+python3 tools/test_dispenser_parity.py
+python3 tools/test_sculk_parity.py
+python3 tools/lan_e2e.py --server-thread --check machines --check fireball --check sculk_container
+```
+
+The LAN checks open and fill machines through the guest's inventory packets, observe a
+powered dispenser's projectile on both clients, and open a chest to activate a sculk sensor
+and shrieker. They supplement the deterministic component comparisons.
+
 ## Reading vanilla
 
 Besides the Vineflower sources in `.local/minecraft/<version>/sources/`, `tools/rea_vanilla.py` queries the shipped bytecode through REA (callers through lambdas, overloads, a second decompiler); see [decompilation status](decompilation-status.md#querying-the-shipped-bytecode-with-rea).
diff --git a/tools/command_exec_corpus.py b/tools/command_exec_corpus.py
index 4bc202f78..230cf9440 100644
--- a/tools/command_exec_corpus.py
+++ b/tools/command_exec_corpus.py
@@ -611,7 +611,9 @@ def world_misc():
         cmd('/fill 0 210 0 2 212 2 minecraft:glass keep'),
         cmd('/fill 0 210 0 2 212 2 minecraft:dirt replace #minecraft:base_stone_overworld'),
         cmd('/fill 0 210 0 2 212 2 minecraft:air strict'),
-        cmd('/fill 0 210 0 100 300 100 minecraft:stone'),
+        # A connected server loads more terrain than the oracle's 5x5 core.
+        # Keep the far corner unambiguously unloaded in both executions.
+        cmd('/fill 0 210 0 1000 300 1000 minecraft:stone'),
         cmd('/setblock 0 211 0 minecraft:oak_sign{front_text:{messages:["a","b","c","d"]}}'),
         cmd('/data get block 0 211 0 front_text.messages'),
         cmd('/clone 0 211 0 0 211 0 1 211 1 replace move'),
@@ -814,6 +816,9 @@ def functions_and_packs():
 
 def ticking():
     return [
+        # Isolate named-stream commands from earlier loot rolls, including
+        # ocean vegetation updated while asynchronous terrain loads settle.
+        *setup('/random reset *'),
         cmd('/tick query'),
         cmd('/tick rate 40'),
         cmd('/tick query'),
@@ -1046,9 +1051,25 @@ def test_command():
     ]
 
 
+def server_clock():
+    """Only explicit tick operations advance the script's authoritative clock."""
+    return [
+        *setup('/scoreboard objectives add harness_clock dummy',
+               '/execute store result score before harness_clock run time query gametime'),
+        {'op': 'tick', 'n': 3},
+        *setup('/execute store result score elapsed harness_clock run time query gametime',
+               '/scoreboard players operation elapsed harness_clock -= before harness_clock'),
+        cmd('/scoreboard players get elapsed harness_clock'),
+        # The connected owner is the only player; @s and @a use the same body.
+        cmd('/execute as @a run say connected owner'),
+        *setup('/scoreboard objectives remove harness_clock'),
+    ]
+
+
 def groups():
     return [
         ('setup', group_setup()),
+        ('server clock', server_clock()),
         ('client commands', client_commands()),
         ('game state', game_state()),
         ('player state', player_state()),
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 0ec7218d8..0259624e0 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -6398,5 +6398,44 @@ CHECKS += ['sprint-fov']
 CHECK_FNS['sprint-fov'] = check_sprint_fov
 
 
+def check_sculk_container(host, guest, out):
+    """A real guest's container interaction emits a server game event. Both
+    clients see the sensor and the non-summoning shrieker activate and reset.
+    The component oracle separately controls warning levels and seeded mobs.
+    """
+    x, y, z = (int(v // 1) for v in pos_of(guest))
+    chest, sensor, shrieker = (x + 2, y, z), (x + 3, y, z), (x + 4, y, z)
+    guest('command', command='gamemode survival')
+    for at, block in ((chest, 'chest'), (shrieker, 'sculk_shrieker'), (sensor, 'sculk_sensor')):
+        guest('command', command=f'setblock {at[0]} {at[1]} {at[2]} minecraft:{block}')
+    guest.wait(60)
+    seen = {}
+    # Keep the sensor's 30-tick active window observable while both clients
+    # acknowledge the container and the control socket inspects them.
+    host('command', command='tick rate 4')
+    try:
+        guest.raw('interact', *chest)
+        guest.raw('wait-for', 'screen', 'container', '--timeout', 10)
+        for game in (host, guest):
+            active = wait_state(game, sensor, 'sculk_sensor_phase', 'active', 40)
+            shrieking = wait_state(game, shrieker, 'shrieking', 'true', 40)
+            seen[game.name] = (active, shrieking)
+        assert all(s == ('active', 'true') for s in seen.values()), seen
+        guest.raw('key', 'esc', 'tap')
+        for game in (host, guest):
+            assert wait_state(game, sensor, 'sculk_sensor_phase', 'inactive', 160) == 'inactive', seen
+            assert wait_state(game, shrieker, 'shrieking', 'false', 160) == 'false', seen
+    finally:
+        host('command', command='tick rate 20')
+        if guest('state').get('screen') == 'container':
+            guest.raw('key', 'esc', 'tap')
+        for at in (sensor, shrieker, chest):
+            guest('command', command=f'setblock {at[0]} {at[1]} {at[2]} minecraft:air')
+    return seen
+
+
+CHECKS += ['sculk_container']
+CHECK_FNS['sculk_container'] = check_sculk_container
+
 if __name__ == '__main__':
     main()
diff --git a/tools/test_command_exec_parity.py b/tools/test_command_exec_parity.py
index 877bd0b38..75f38c351 100644
--- a/tools/test_command_exec_parity.py
+++ b/tools/test_command_exec_parity.py
@@ -4,7 +4,7 @@
 Java (VanillaCommandExecOracle) starts a stand-in integrated server: a real
 MinecraftServer with a generated world, Commands.CommandSelection.INTEGRATED
 and one single-player owner named Player. Rust runs the same script through
-the Horizon client headless (HORIZON_COMMAND_SCRIPT). Both run each command as
+Horizon's integrated server with a connected headless client (HORIZON_COMMAND_SCRIPT). Both run each command as
 the player through Commands.performPrefixedCommand and record every system or
 chat message the player receives (text and resolved style: colour, bold,
 italic, underlined, strikethrough, obfuscated) together with the results the
@@ -82,7 +82,7 @@ def main():
     rust_dir = build / 'rust'
     shutil.rmtree(rust_dir, ignore_errors=True)
     rust_dir.mkdir()
-    env = lab.game_env(HORIZON_COMMAND_SCRIPT=script_path, HORIZON_COMMAND_OUTPUT=build / 'rust.jsonl')
+    env = lab.game_env(HORIZON_SERVER_THREAD=1, HORIZON_PLAYER_NAME="Player", HORIZON_COMMAND_SCRIPT=script_path, HORIZON_COMMAND_OUTPUT=build / 'rust.jsonl')
     run([binary, '--resources', lab.RESOURCES, '--world', 'harness', '--seed', SEED, '--radius', 4], 'rust', cwd=rust_dir, env=env)
 
     vanilla = [json.loads(l) for l in (build / 'vanilla.jsonl').open(encoding='utf-8')]
diff --git a/tools/test_dispenser_parity.py b/tools/test_dispenser_parity.py
index a6d1f429a..7ca48cb7f 100644
--- a/tools/test_dispenser_parity.py
+++ b/tools/test_dispenser_parity.py
@@ -5,7 +5,7 @@ A dispenser or dropper at the origin faces a random direction and holds the
 case's items; the block in front (and below it) comes from a palette of blocks
 the behaviours care about, and some cases put a target entity in front. Vanilla
 `DispenserBlock.dispenseFrom` runs over the headless level of the block update
-oracle (`VanillaDispenserOracle`); Horizon runs its game glue in a headless game
+oracle (`VanillaDispenserOracle`); Horizon runs its game glue as a component probe on a server thread
 (`HORIZON_DISPENSE_FIXTURE`). Both print block changes, container contents,
 spawned entities (type, position, motion), the targets afterwards, level events,
 sounds, game events and the level random. Motion drawn from an entity's own
diff --git a/tools/test_sculk_parity.py b/tools/test_sculk_parity.py
index ae2c1c6aa..bff5ad5ba 100644
--- a/tools/test_sculk_parity.py
+++ b/tools/test_sculk_parity.py
@@ -5,7 +5,7 @@ The Java oracle (VanillaSculkOracle) runs each scenario in a real, headless, fla
 level: it builds the blocks, places the player (with a warning level) and entities, and ticks the
 level in ServerLevel.tick's order while scripted game events and block changes happen at given
 ticks. Horizon runs the same scenarios through its game code (`HORIZON_SCULK_FIXTURE`, the
-same functions the game ticks). Both print, per tick, what changed at the watched blocks (state,
+same server phases, with synthetic player and entity state). Both print, per tick, what changed at the watched blocks (state,
 vibration, selector, last frequency, warning level, charge cursors), sounds, level events, the
 player's warden warning level and darkness, new entities, and the level random. The harness
 reports each scenario's first differing tick.

From 401ac1322ffdd9aa72f2fffd927f135176a0ec98 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:43:03 +0100
Subject: [PATCH 211/270] Banners: one loader for saved and generated banners

The generated banner reuses save.rs's BannerBlockEntity.loadAdditional
(now decode_banner) instead of a copy of it, and the generated block
entity clones its NBT only for the kinds that read it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/save.rs             | 23 +++++-----
 crates/horizon-client/src/structure_blocks.rs | 45 ++++++-------------
 2 files changed, 26 insertions(+), 42 deletions(-)

diff --git a/crates/horizon-client/src/save.rs b/crates/horizon-client/src/save.rs
index da5735c17..69b6a44f5 100644
--- a/crates/horizon-client/src/save.rs
+++ b/crates/horizon-client/src/save.rs
@@ -567,6 +567,17 @@ fn merge_block_entity(original: &Tag, loaded: &Tag, current: &Tag) -> Tag {
     }
     merged
 }
+/// `BannerBlockEntity.loadAdditional` (and the `components` a block entity keeps).
+pub fn decode_banner(tag: &Tag) -> crate::containers::Banner {
+    crate::containers::Banner {
+        layers: crate::banner::layers_from_nbt(tag.get("patterns")),
+        name: text(tag.get("CustomName")),
+        components: match tag.get("components") {
+            Some(Tag::Compound(c)) => c.clone(),
+            _ => Compound::new(),
+        },
+    }
+}
 pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::containers::BlockEntity)> {
     use crate::containers::BlockEntity;
     let int = |k: &str| number(tag.get(k)).map(|v| v as i32);
@@ -600,17 +611,7 @@ pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::contain
         return Some((pos, BlockEntity::Lectern(lectern)));
     }
     if id == "minecraft:banner" {
-        return Some((
-            pos,
-            BlockEntity::Banner(crate::containers::Banner {
-                layers: crate::banner::layers_from_nbt(tag.get("patterns")),
-                name: text(tag.get("CustomName")),
-                components: match tag.get("components") {
-                    Some(Tag::Compound(c)) => c.clone(),
-                    _ => Compound::new(),
-                },
-            }),
-        ));
+        return Some((pos, BlockEntity::Banner(decode_banner(tag))));
     }
     if id == "minecraft:beacon" {
         let beacon = crate::containers::Beacon {
diff --git a/crates/horizon-client/src/structure_blocks.rs b/crates/horizon-client/src/structure_blocks.rs
index da5b75258..ff51116bc 100644
--- a/crates/horizon-client/src/structure_blocks.rs
+++ b/crates/horizon-client/src/structure_blocks.rs
@@ -128,40 +128,23 @@ fn text(nbt: &Compound, key: &str) -> Option<String> {
     }
 }
 
-/// `BannerBlockEntity.loadAdditional`: the `patterns` layers and the custom
-/// name a structure template saves with its banner (the End cities' tower
-/// tops place black triangles this way).
-fn banner_from_nbt(nbt: &Compound) -> crate::containers::Banner {
-    crate::containers::Banner {
-        layers: crate::banner::layers_from_nbt(nbt.get(&JavaString::from("patterns"))),
-        name: text(nbt, "CustomName"),
-        components: match nbt.get(&JavaString::from("components")) {
-            Some(Tag::Compound(c)) => c.clone(),
-            _ => Compound::new(),
-        },
-    }
-}
-
 /// The client block entity for one of a chunk's generated block entities,
-/// before a container's loot is unpacked.
+/// before a container's loot is unpacked: `StructureTemplate.placeInWorld`
+/// hands the template's block entity NBT to the level's block entity.
 fn generated_block_entity(block: &str, nbt: &Compound) -> Option<BlockEntity> {
     let mut entity = BlockEntity::for_block(block)?;
-    let tag = Tag::Compound(nbt.clone());
-    // MonsterRoomFeature and the structures' setEntityId.
-    if let BlockEntity::Spawner(s) = &mut entity {
-        **s = crate::mobs::spawner::Spawner::load(&tag);
-    }
-    if let BlockEntity::TrialSpawner(s) = &mut entity {
-        **s = crate::mobs::trial_spawner::TrialSpawner::load(&tag);
-    }
-    if let BlockEntity::Vault(v) = &mut entity {
-        **v = crate::vault::Vault::load(&tag);
-    }
-    // StructureTemplate.placeInWorld hands the template's block entity NBT to
-    // the level, so `BannerBlockEntity.loadAdditional` keeps the banner's
-    // patterns (the End cities' black triangles) and its name.
-    if let BlockEntity::Banner(b) = &mut entity {
-        *b = banner_from_nbt(nbt);
+    match &mut entity {
+        // MonsterRoomFeature and the structures' setEntityId.
+        BlockEntity::Spawner(s) => {
+            **s = crate::mobs::spawner::Spawner::load(&Tag::Compound(nbt.clone()));
+        }
+        BlockEntity::TrialSpawner(s) => {
+            **s = crate::mobs::trial_spawner::TrialSpawner::load(&Tag::Compound(nbt.clone()));
+        }
+        BlockEntity::Vault(v) => **v = crate::vault::Vault::load(&Tag::Compound(nbt.clone())),
+        // BannerBlockEntity.loadAdditional: the End cities' black triangles.
+        BlockEntity::Banner(b) => *b = crate::save::decode_banner(&Tag::Compound(nbt.clone())),
+        _ => {}
     }
     Some(entity)
 }

From 072f5ce2ee412f735e9b2ec70c29126695dc15b0 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:43:07 +0000
Subject: [PATCH 212/270] Fix custom item names above targeted item frames

Show the framed item's custom name through the existing world name-label renderer, matching vanilla's HUD and crosshair conditions. Extend the LAN frame check for normal and glow frames.

Co-Authored-By: Codex <noreply@openai.com>
---
 crates/horizon-client/src/game/names.rs | 36 +++++++++++++++++++++++++
 tools/lan_e2e.py                        | 17 ++++++++++--
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/names.rs b/crates/horizon-client/src/game/names.rs
index 7655fb489..d5e8446c3 100644
--- a/crates/horizon-client/src/game/names.rs
+++ b/crates/horizon-client/src/game/names.rs
@@ -240,6 +240,42 @@ impl Game<'_> {
                 discrete: false,
             });
         }
+        // ItemFrameRenderer.shouldShowName/getNameTag: only the targeted
+        // frame's custom-named item, with the HUD visible (also glow frames).
+        if !self.ui.hide_gui
+            && let Some((i, distance)) = self.frame_hit()
+            && self.before_block(distance)
+            && self.mob_hit().is_none_or(|(_, d)| d > distance)
+            && let Some(name) = self.item_frames[i]
+                .item
+                .as_ref()
+                .and_then(|item| item.custom_name())
+        {
+            let frame = &self.item_frames[i];
+            let (lo, hi) = frame.bounds();
+            let center = glam::DVec3::from_array(std::array::from_fn(|a| (lo[a] + hi[a]) / 2.0));
+            if center.distance_squared(camera) < 64.0 * 64.0 {
+                // NAME_TAG is at the entity height (0.5), then the name
+                // submitter lifts it 0.5. ItemFrameRenderer offsets rendering
+                // 0.3 toward its facing and -0.25 vertically.
+                let step = frame.step();
+                tags.push(NameTag {
+                    at: center
+                        + glam::DVec3::new(
+                            f64::from(step[0] as f32 * 0.3),
+                            0.75,
+                            f64::from(step[2] as f32 * 0.3),
+                        ),
+                    lines: vec![(Text::literal(name).resolve_legacy(), 0.0)],
+                    light: self.world.light(
+                        center.x.floor() as i32,
+                        center.y.floor() as i32,
+                        center.z.floor() as i32,
+                    ),
+                    discrete: false,
+                });
+            }
+        }
         tags
     }
     /// `SubmitNodeCollection.submitNameTag`: a discrete name is drawn once,
diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index 0ec7218d8..df78489f9 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -3762,17 +3762,21 @@ def check_frames(host, guest, out):
         # Within a survival player's 3 blocks of reach: a frame on a wall, an armor stand beside it.
         player('command', command=f'fill {x - 2} {y} {z + 1} {x + 2} {y + 2} {z + 2} minecraft:air')
         player('command', command=f'fill {x - 2} {y} {z + 3} {x + 2} {y + 2} {z + 3} minecraft:stone')
-        player('command', command=f'summon minecraft:item_frame {x + 0.5} {y + 1.5} {z + 2.97} '
+        frame_kind = 'item_frame' if label == 'host' else 'glow_item_frame'
+        player('command', command=f'summon minecraft:{frame_kind} {x + 0.5} {y + 1.5} {z + 2.97} '
                f'{{block_pos:[I;{x},{y + 1},{z + 2}],Facing:2b}}')
         player('command', command=f'summon minecraft:armor_stand {x - 1.5} {y} {z + 1.5}')
         player('command', command='clear @s')
-        player('command', command='item replace entity @s weapon.mainhand with minecraft:diamond')
+        frame_name = f'{label} framed diamond'
+        player('command', command='item replace entity @s weapon.mainhand with '
+               f"minecraft:diamond[minecraft:custom_name='{frame_name}']")
         player.wait(30)
         try:
             frame = [o for o in player('status')['objects'] if o['kind'].endswith('item_frame')
                      and o['position'] == [x, y + 1, z + 2]]
             assert frame, f'the {label} sees no item frame at {[x, y + 1, z + 2]}'
             player.raw('look-at', f'{x + 0.5:.2f}', f'{y + 1.5:.2f}', f'{z + 2.95:.2f}')
+            assert frame_name not in (player('status').get('name_tags') or []), 'empty frame name visible'
             player.raw('mouse', 'right', 'click')
             player.wait(10)
             player.raw('mouse', 'right', 'click')
@@ -3780,6 +3784,15 @@ def check_frames(host, guest, out):
             frame = [o for o in player('status')['objects'] if o['id'] == frame[0]['id']][0]
             assert frame['item'] == 'minecraft:diamond', f'the {label}\'s frame holds {frame["item"]}'
             assert frame['rotation'] == 1, f'the {label}\'s frame turned to {frame["rotation"]}'
+            assert frame_name in (player('status').get('name_tags') or []), \
+                f"the {label}'s targeted frame has no item name"
+            player.shot(out, f'{label}-framed-item-name')
+            player.raw('key', 'f1', 'tap')
+            player.wait(2)
+            assert frame_name not in (player('status').get('name_tags') or []), 'F1 left the frame name visible'
+            player.raw('key', 'f1', 'tap')
+            player.raw('look-at', f'{x + 2:.2f}', f'{y + 1.5:.2f}', f'{z + 2.95:.2f}')
+            assert frame_name not in (player('status').get('name_tags') or []), 'untargeted frame name visible'
             theirs = [o for o in other('status')['objects'] if o['kind'].endswith('item_frame')
                       and o['position'] == [x, y + 1, z + 2]]
             assert theirs and theirs[0]['item'] == 'minecraft:diamond' and theirs[0]['rotation'] == 1, \

From a41381236362cca38a951ed652adeaef876e0b4a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:46:15 +0100
Subject: [PATCH 213/270] Scroll bars: the screen's GUI size, and a test of the
 drag

stats_scroll and stats_drag take the GUI height from gui_size() instead
of a copy of it. The Game Rules list's press, drag and release get the
test from #1913 (vlesmentie's take on the same fix).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/game/game_rules_screen.rs             | 23 +++++++++++++++++++
 .../horizon-client/src/game/stats_screen.rs   | 12 ++--------
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/crates/horizon-client/src/game/game_rules_screen.rs b/crates/horizon-client/src/game/game_rules_screen.rs
index 126bc8804..0992f7689 100644
--- a/crates/horizon-client/src/game/game_rules_screen.rs
+++ b/crates/horizon-client/src/game/game_rules_screen.rs
@@ -564,6 +564,29 @@ mod tests {
         );
     }
 
+    /// AbstractScrollArea: a press on the bar holds it, a drag moves the
+    /// list (to the ends past them), a release lets go.
+    #[test]
+    fn the_scroll_bar_can_be_held_dragged_and_let_go() {
+        let mut s = RulesScreen::new(&GameRules::default());
+        let (w, h) = (427.0, 240.0);
+        let (top, bottom, content) = (HEADER, h - FOOTER, s.content());
+        assert!(
+            content > bottom - top,
+            "the rules overflow a 240-high screen"
+        );
+        let bar = RulesScreen::bar(w);
+        assert!(!s.press_scrollbar((bar - 4.0, top + 5.0), (w, h)));
+        assert!(s.press_scrollbar((bar + 3.0, top + 5.0), (w, h)));
+        s.drag(top + 40.0, h);
+        assert!(s.scroll.amount > 0.0);
+        s.drag(bottom + 10.0, h);
+        assert_eq!(s.scroll.amount, content - (bottom - top));
+        s.release();
+        s.drag(top, h);
+        assert_eq!(s.scroll.amount, content - (bottom - top));
+    }
+
     #[test]
     fn edits_change_rules_and_bad_numbers_hold_done() {
         let mut s = RulesScreen::new(&GameRules::default());
diff --git a/crates/horizon-client/src/game/stats_screen.rs b/crates/horizon-client/src/game/stats_screen.rs
index e86b29aeb..bd7663e49 100644
--- a/crates/horizon-client/src/game/stats_screen.rs
+++ b/crates/horizon-client/src/game/stats_screen.rs
@@ -492,11 +492,7 @@ impl Game<'_> {
     }
     pub(super) fn stats_scroll(&mut self, amount: f32) {
         let (row_h, _) = self.stats_rows();
-        let size = self
-            .renderer
-            .as_ref()
-            .map_or([1280, 720], |r| [r.config.width, r.config.height]);
-        let h = HudBatch::new(size).height;
+        let h = self.gui_size().1;
         let content = self.stats_content();
         self.stats_ui
             .scroll
@@ -517,11 +513,7 @@ impl Game<'_> {
         if !self.stats_ui.scroll.held() {
             return;
         }
-        let size = self
-            .renderer
-            .as_ref()
-            .map_or([1280, 720], |r| [r.config.width, r.config.height]);
-        let h = HudBatch::new(size).height;
+        let h = self.gui_size().1;
         let content = self.stats_content();
         self.stats_ui
             .scroll

From b7629cf6560ac31557d751638910acdc8bf7e0f8 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:46:36 +0100
Subject: [PATCH 214/270] Enchantments: say which callers have no language

full_name reads the process's language, which the server thread shares
with its window; only a process with no language loaded (a dedicated
server, the probes) keeps the English names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/enchant.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/enchant.rs b/crates/horizon-client/src/enchant.rs
index f5ddc84c2..2f418ae82 100644
--- a/crates/horizon-client/src/enchant.rs
+++ b/crates/horizon-client/src/enchant.rs
@@ -337,8 +337,8 @@ impl Enchantments {
         let language = crate::lang::current();
         self.full_name_in(language.as_deref(), id, level)
     }
-    /// `full_name` against `language`; `None` keeps the English names loaded
-    /// above, which is what the server thread and the probes see.
+    /// `full_name` against `language`; `None` (no language loaded: a
+    /// dedicated server, the probes) keeps the English names loaded above.
     pub fn full_name_in(
         &self,
         language: Option<&crate::lang::Language>,

From 9d5301627bbb81bf46113a9c41dff841d2d4f2e1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:55:43 +0100
Subject: [PATCH 215/270] Chickens: the flap test uses the shared test mob type

chicken_flap reads only the ground flag, so the test builds its mob from
mobs::sensor_scan_tests::kind() instead of a 50-line copy of a MobType.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/mobs/farm.rs | 54 +-------------------------
 1 file changed, 2 insertions(+), 52 deletions(-)

diff --git a/crates/horizon-client/src/mobs/farm.rs b/crates/horizon-client/src/mobs/farm.rs
index aa02c901d..83d5ac1f5 100644
--- a/crates/horizon-client/src/mobs/farm.rs
+++ b/crates/horizon-client/src/mobs/farm.rs
@@ -136,61 +136,11 @@ pub fn sheep_color(climate: Climate, random: &mut impl RandomSource) -> u8 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::mobs::{Anim, Brain, Flags, MobType, Part, Species};
     use horizon_core::geometry::Vec3;
-    use serde_json::json;
-    use std::collections::HashMap;
 
+    /// `chicken_flap` reads only the ground flag: any mob type will do.
     fn chicken() -> Mob {
-        let model = Arc::new(Part::parse(
-            "root",
-            &json!({"children": {"right_wing": {}, "left_wing": {}}}),
-        ));
-        let kind = Arc::new(MobType {
-            id: "minecraft:chicken".into(),
-            species: Species::Chicken,
-            width: 0.4,
-            height: 0.7,
-            eye_height: 0.644,
-            category: "creature".into(),
-            max_health: 4.0,
-            speed: 0.25,
-            flying_speed: 0.4,
-            attack_damage: 0.0,
-            attack_knockback: 0.0,
-            follow_range: 16.0,
-            step_height: 0.6,
-            armor: 0.0,
-            armor_toughness: 0.0,
-            knockback_resistance: 0.0,
-            jump_strength: 0.42,
-            attributes: Arc::default(),
-            gravity: 0.08,
-            safe_fall_distance: 3.0,
-            fall_damage_multiplier: 1.0,
-            water_efficiency: 0.0,
-            water_slowdown: 0.8,
-            air_speed: 0.02,
-            baby_scale: 0.5,
-            head_rot_speed: 10.0,
-            max_head_x_rot: 40.0,
-            max_head_y_rot: 75.0,
-            ambient_interval: 120,
-            flags: Flags {
-                animal: true,
-                ..Default::default()
-            },
-            model,
-            layers: HashMap::new(),
-            texture: String::new(),
-            brain: Brain::Passive,
-            anim: Anim::Chicken,
-            sounds: [""; 3],
-            step_sound: None,
-            food: Arc::default(),
-            tempt: Arc::default(),
-        });
-        Mob::new(1, kind, Vec3::ZERO, 0.0)
+        Mob::new(1, crate::mobs::sensor_scan_tests::kind(), Vec3::ZERO, 0.0)
     }
 
     #[test]

From 4be53ee28a64f126a1ab08b929eae354cba138c4 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 22:58:00 +0000
Subject: [PATCH 216/270] Reduce resource preparation filesystem work

Share the asset index and verification state, stage checked imports while hashing, preserve indexed replacements, and clone independent resource copies where supported.

Co-Authored-By: Codex (GPT-6.1) <noreply@openai.com>
---
 Cargo.lock                              |   2 +
 crates/horizon-prepare/Cargo.toml       |   4 +
 crates/horizon-prepare/src/artifacts.rs |  78 +++--
 crates/horizon-prepare/src/files.rs     | 180 ++++++++++++
 crates/horizon-prepare/src/lib.rs       | 105 +++++--
 crates/horizon-prepare/src/sounds.rs    | 362 +++++++++++++++++++-----
 docs/prepare-performance.md             |  44 +++
 launcher/Cargo.lock                     |   2 +
 launcher/src/backend.rs                 |   2 +-
 9 files changed, 637 insertions(+), 142 deletions(-)
 create mode 100644 crates/horizon-prepare/src/files.rs
 create mode 100644 docs/prepare-performance.md

diff --git a/Cargo.lock b/Cargo.lock
index 4d749add6..bb4e72446 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1408,6 +1408,8 @@ dependencies = [
 name = "horizon-prepare"
 version = "0.1.0"
 dependencies = [
+ "crc32fast",
+ "libc",
  "regex",
  "sha1",
  "sha2",
diff --git a/crates/horizon-prepare/Cargo.toml b/crates/horizon-prepare/Cargo.toml
index 3d62202bd..9bcf5464d 100644
--- a/crates/horizon-prepare/Cargo.toml
+++ b/crates/horizon-prepare/Cargo.toml
@@ -6,11 +6,15 @@ license = "MIT"
 description = "Prepares Horizon's resources from the player's own Minecraft: imports and checks the pinned jars, runs the vanilla exporters, writes the resource folder"
 
 [dependencies]
+crc32fast = "1"
 regex = { version = "1", default-features = false, features = ["std", "unicode-perl"] }
 sha1 = "0.10"
 sha2 = "0.10"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 
+[target.'cfg(any(target_os = "linux", target_os = "macos"))'.dependencies]
+libc = "0.2"
+
 [build-dependencies]
 sha2 = "0.10"
 
diff --git a/crates/horizon-prepare/src/artifacts.rs b/crates/horizon-prepare/src/artifacts.rs
index 805dd80d4..a3bf945d5 100644
--- a/crates/horizon-prepare/src/artifacts.rs
+++ b/crates/horizon-prepare/src/artifacts.rs
@@ -143,31 +143,17 @@ pub(crate) fn import_copy(
     algorithm: &str,
     hint: &str,
 ) -> Result<PathBuf, String> {
-    fs::create_dir_all(destination.parent().unwrap()).map_err(|e| e.to_string())?;
-    if destination.exists() && digest(destination, algorithm)? == checksum {
-        return Ok(destination.to_path_buf());
-    }
-    if !source.is_file() {
-        return Err(format!("Missing {}. {hint}", source.display())
-            .trim()
-            .to_string());
-    }
-    let actual = digest(source, algorithm)?;
-    if actual != checksum {
-        return Err(format!(
-            "{} is not the pinned file: expected {algorithm} {checksum}, got {actual}",
-            source.display()
-        ));
-    }
-    let temporary = destination.with_file_name(format!(
-        ".{}.partial-{}",
-        destination.file_name().unwrap().to_string_lossy(),
-        std::process::id()
-    ));
-    let copied = fs::copy(source, &temporary).and_then(|_| fs::rename(&temporary, destination));
-    let _ = fs::remove_file(&temporary);
-    copied.map_err(|e| format!("{}: {e}", destination.display()))?;
-    Ok(destination.to_path_buf())
+    crate::files::Import::stage(source, destination, checksum, algorithm, false)
+        .map_err(|error| {
+            if !source.is_file() {
+                format!("Missing {}. {hint}", source.display())
+                    .trim()
+                    .to_string()
+            } else {
+                error
+            }
+        })?
+        .commit()
 }
 
 /// The pinned version JSON from the launcher's versions/ directory. The launcher's copy wins
@@ -653,9 +639,17 @@ pub struct Artifacts {
 
 /// Reuses checked imports from this root or another installed version beside it.
 pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
+    Ok(reuse_verified(root, log)?.is_some())
+}
+
+/// Keep this preparation's verified artifacts and client libraries for the exporters.
+pub(crate) fn reuse_verified(
+    root: &Path,
+    log: Log,
+) -> Result<Option<(Artifacts, Vec<PathBuf>)>, String> {
     let root = fs::canonicalize(root).map_err(|e| format!("{}: {e}", root.display()))?;
     let lock = Lock::read(&root)?;
-    let checked = |directory: PathBuf| -> Result<Vec<PathBuf>, String> {
+    let checked = |directory: PathBuf| -> Result<(Artifacts, Vec<PathBuf>), String> {
         let candidate = Lock {
             json: lock.json.clone(),
             version: lock.version.clone(),
@@ -664,17 +658,9 @@ pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
         };
         let found = verify(&candidate)?;
         let client = client_libraries(&candidate, &found.manifest)?;
-        let mut files = vec![
-            candidate.directory.join("manifest.json"),
-            candidate.directory.join("jars/client.jar"),
-            candidate.directory.join("jars/server.jar"),
-            found.jars["server"].clone(),
-        ];
-        files.extend(found.libraries);
-        files.extend(client);
-        Ok(files)
+        Ok((found, client))
     };
-    if checked(lock.directory.clone()).is_ok() {
+    if let Ok((found, client_libraries)) = checked(lock.directory.clone()) {
         if [
             "prepared.json",
             "reports/client-inventory.json",
@@ -683,8 +669,6 @@ pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
         .iter()
         .any(|path| !lock.directory.join(path).is_file())
         {
-            let found = verify(&lock)?;
-            let client_libraries = client_libraries(&lock, &found.manifest)?;
             write_import_metadata(
                 &root,
                 &lock,
@@ -696,10 +680,10 @@ pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
             )?;
         }
         log(&format!("Using imported Minecraft {}", lock.version));
-        return Ok(true);
+        return Ok(Some((found, client_libraries)));
     }
     let Some(versions) = root.parent() else {
-        return Ok(false);
+        return Ok(None);
     };
     // Sibling discovery is intended for the launcher's versions/ folder.
     let mut siblings: Vec<_> = fs::read_dir(versions)
@@ -711,9 +695,17 @@ pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
     siblings.sort();
     for sibling in siblings {
         let source = sibling.join(".local/minecraft").join(&lock.version);
-        let Ok(files) = checked(source.clone()) else {
+        let Ok((found, client)) = checked(source.clone()) else {
             continue;
         };
+        let mut files = vec![
+            source.join("manifest.json"),
+            source.join("jars/client.jar"),
+            source.join("jars/server.jar"),
+            found.jars["server"].clone(),
+        ];
+        files.extend(found.libraries);
+        files.extend(client);
         for file in files {
             let relative = file.strip_prefix(&source).map_err(|e| e.to_string())?;
             import_copy(
@@ -740,9 +732,9 @@ pub fn reuse_imported(root: &Path, log: Log) -> Result<bool, String> {
             lock.version,
             sibling.display()
         ));
-        return Ok(true);
+        return Ok(Some((found, client_libraries)));
     }
-    Ok(false)
+    Ok(None)
 }
 
 pub fn verify(lock: &Lock) -> Result<Artifacts, String> {
diff --git a/crates/horizon-prepare/src/files.rs b/crates/horizon-prepare/src/files.rs
new file mode 100644
index 000000000..484c7bf7b
--- /dev/null
+++ b/crates/horizon-prepare/src/files.rs
@@ -0,0 +1,180 @@
+//! Independent copies, using filesystem cloning when available. Never hard links: exporters
+//! rewrite prepared resources in place. Checked imports publish only after verifying the copy.
+
+use crate::{digest, hex};
+use sha2::Digest;
+use std::fs;
+use std::io::{self, Read, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+fn clone_file(from: &Path, to: &Path) -> io::Result<()> {
+    #[cfg(target_os = "linux")]
+    {
+        use std::os::fd::AsRawFd;
+        let source = fs::File::open(from)?;
+        let target = fs::File::create(to)?;
+        // SAFETY: FICLONE takes a source fd, both descriptors stay open for the call.
+        if unsafe { libc::ioctl(target.as_raw_fd(), libc::FICLONE, source.as_raw_fd()) } == 0 {
+            return Ok(());
+        }
+        Err(io::Error::last_os_error())
+    }
+    #[cfg(target_os = "macos")]
+    {
+        use std::ffi::CString;
+        use std::os::unix::ffi::OsStrExt;
+        let path = |p: &Path| {
+            CString::new(p.as_os_str().as_bytes())
+                .map_err(|e| io::Error::new(io::ErrorKind::InvalidInput, e))
+        };
+        let (source, target) = (path(from)?, path(to)?);
+        // SAFETY: both paths are valid NUL-terminated strings for the duration of the call.
+        if unsafe { libc::clonefile(source.as_ptr(), target.as_ptr(), 0) } == 0 {
+            return Ok(());
+        }
+        Err(io::Error::last_os_error())
+    }
+    #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+    {
+        let _ = (from, to);
+        Err(io::ErrorKind::Unsupported.into())
+    }
+}
+
+/// Copies an independent file, attempting a reflink first. The destination may be replaced.
+pub fn clone_or_copy(from: &Path, to: &Path) -> io::Result<()> {
+    clone_file(from, to).or_else(|_| fs::copy(from, to).map(|_| ()))
+}
+
+fn copy_hash<D: Digest>(from: &Path, to: &Path) -> io::Result<String> {
+    let mut source = fs::File::open(from)?;
+    let mut target = fs::File::create(to)?;
+    let mut hash = D::new();
+    let mut buffer = vec![0; 64 * 1024];
+    loop {
+        let n = source.read(&mut buffer)?;
+        if n == 0 {
+            return Ok(hex(&hash.finalize()));
+        }
+        target.write_all(&buffer[..n])?;
+        hash.update(&buffer[..n]);
+    }
+}
+
+/// A verified replacement staged beside its destination. Dropping an unfinished set cleans
+/// every temporary file, so a corrupt late panorama face cannot replace earlier placeholders.
+pub(crate) struct Import {
+    temporary: Option<PathBuf>,
+    destination: PathBuf,
+}
+
+impl Import {
+    pub(crate) fn stage(
+        source: &Path,
+        destination: &Path,
+        checksum: &str,
+        algorithm: &str,
+        verified: bool,
+    ) -> Result<Self, String> {
+        let mut import = Self {
+            temporary: None,
+            destination: destination.into(),
+        };
+        if verified || (destination.is_file() && digest(destination, algorithm)? == checksum) {
+            return Ok(import);
+        }
+        fs::create_dir_all(destination.parent().unwrap()).map_err(|e| e.to_string())?;
+        static COPIES: AtomicUsize = AtomicUsize::new(0);
+        let temporary = destination.with_file_name(format!(
+            ".{}.partial-{}-{}",
+            destination.file_name().unwrap().to_string_lossy(),
+            std::process::id(),
+            COPIES.fetch_add(1, Ordering::Relaxed)
+        ));
+        import.temporary = Some(temporary.clone());
+        let actual = if clone_file(source, &temporary).is_ok() {
+            digest(&temporary, algorithm)?
+        } else {
+            match algorithm {
+                "sha1" => copy_hash::<sha1::Sha1>(source, &temporary),
+                _ => copy_hash::<sha2::Sha256>(source, &temporary),
+            }
+            .map_err(|e| format!("{}: {e}", source.display()))?
+        };
+        if actual != checksum {
+            return Err(format!(
+                "{} is not the pinned file: expected {algorithm} {checksum}, got {actual}",
+                source.display()
+            ));
+        }
+        Ok(import)
+    }
+
+    pub(crate) fn commit(mut self) -> Result<PathBuf, String> {
+        if let Some(temporary) = &self.temporary {
+            fs::rename(temporary, &self.destination)
+                .map_err(|e| format!("{}: {e}", self.destination.display()))?;
+        }
+        self.temporary = None;
+        Ok(self.destination.clone())
+    }
+}
+
+impl Drop for Import {
+    fn drop(&mut self) {
+        if let Some(temporary) = &self.temporary {
+            let _ = fs::remove_file(temporary);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn copies_are_independent_and_checked_before_publication() {
+        let dir = std::env::temp_dir().join(format!("horizon-file-copy-{}", std::process::id()));
+        fs::create_dir_all(&dir).unwrap();
+        let source = dir.join("source");
+        let target = dir.join("target");
+        let data = vec![42; 200_000]; // More than one streaming buffer.
+        fs::write(&source, &data).unwrap();
+        for algorithm in ["sha1", "sha256"] {
+            let checksum = digest(&source, algorithm).unwrap();
+            Import::stage(&source, &target, &checksum, algorithm, false)
+                .unwrap()
+                .commit()
+                .unwrap();
+            assert_eq!(digest(&target, algorithm).unwrap(), checksum);
+            fs::write(&target, b"old destination").unwrap();
+            assert_eq!(fs::read(&source).unwrap(), data);
+            assert!(Import::stage(&source, &target, "bad hash", algorithm, false).is_err());
+            assert_eq!(fs::read(&target).unwrap(), b"old destination");
+            // Explicitly exercise ordinary streaming copies even on a reflink filesystem.
+            let streamed = if algorithm == "sha1" {
+                copy_hash::<sha1::Sha1>(&source, &target).unwrap()
+            } else {
+                copy_hash::<sha2::Sha256>(&source, &target).unwrap()
+            };
+            assert_eq!(streamed, checksum);
+            assert_eq!(fs::read(&target).unwrap(), data);
+        }
+        clone_or_copy(&source, &target).unwrap();
+        fs::write(&target, b"rewrite").unwrap();
+        assert_eq!(fs::read(&source).unwrap(), data);
+        let staged = Import::stage(
+            &source,
+            &target,
+            &digest(&source, "sha1").unwrap(),
+            "sha1",
+            false,
+        )
+        .unwrap();
+        assert_eq!(fs::read_dir(&dir).unwrap().count(), 3);
+        drop(staged);
+        assert_eq!(fs::read_dir(&dir).unwrap().count(), 2);
+        fs::remove_dir_all(dir).unwrap();
+    }
+}
diff --git a/crates/horizon-prepare/src/lib.rs b/crates/horizon-prepare/src/lib.rs
index c7e443c7d..daee30444 100644
--- a/crates/horizon-prepare/src/lib.rs
+++ b/crates/horizon-prepare/src/lib.rs
@@ -11,12 +11,14 @@
 //! run, keyed by the sha256 of their inputs and outputs recorded in the manifest, as before.
 
 pub mod artifacts;
+mod files;
 mod inventory;
 pub mod java;
 pub mod pyjson;
 mod sounds;
 mod survival;
 
+pub use files::clone_or_copy;
 pub use sounds::{fonts, languages, packs, panorama, sounds, BUILT_IN_PACKS};
 
 use pyjson::Value;
@@ -410,16 +412,28 @@ pub fn prepare(options: &Options, log: Log) -> Result<PathBuf, String> {
         &artifacts::minecraft_dir(options.minecraft_dir.as_deref()).join("runtime"),
     ));
     let jdk = java::find(lock.java_major, &homes)?;
-    if options.import && !artifacts::reuse_imported(root, log)? {
-        artifacts::import(
-            root,
-            &lock,
-            options.minecraft_dir.as_deref(),
-            options.server_jar.as_deref(),
-            log,
-        )?;
-    }
-    let found = artifacts::verify(&lock)?;
+    let reused = if options.import {
+        artifacts::reuse_verified(root, log)?
+    } else {
+        None
+    };
+    let (found, client_libraries) = match reused {
+        Some(checked) => checked,
+        None => {
+            if options.import {
+                artifacts::import(
+                    root,
+                    &lock,
+                    options.minecraft_dir.as_deref(),
+                    options.server_jar.as_deref(),
+                    log,
+                )?;
+            }
+            let found = artifacts::verify(&lock)?;
+            let libraries = artifacts::client_libraries(&lock, &found.manifest)?;
+            (found, libraries)
+        }
+    };
     let local = root.join(".local");
     let resources = local.join("horizon-client").join(&lock.version);
     mkdir(&resources)?;
@@ -445,7 +459,6 @@ pub fn prepare(options: &Options, log: Log) -> Result<PathBuf, String> {
     } else {
         Value::Object(Vec::new())
     };
-    let client_libraries = artifacts::client_libraries(&lock, &found.manifest)?;
     let run = Run {
         root: root.clone(),
         local,
@@ -679,25 +692,9 @@ fn steps(
     // and every data-pack resource (worldgen, recipes, loot tables, tags), and
     // the vanilla pack's icon (`pack.png`) for the pack screen.
     (run.log)("Copying the client's assets and data");
-    let mut count = 0usize;
-    let mut client = open_zip(&run.client)?;
-    let version = pyjson::loads(&zip_text(&mut client, "version.json")?)?;
-    for name in zip_names(&client) {
-        let wanted = name.starts_with("assets/") || name.starts_with("data/") || name == "pack.png";
-        if !wanted || name.ends_with('/') {
-            continue;
-        }
-        let relative = member_path(&name, "Invalid resource path")?;
-        let data = zip_bytes(&mut client, &name)?;
-        write_if_changed(&root.join(relative), &data)?;
-        count += 1;
-    }
-
-    // The JAR holds only gray 1x1 panorama placeholders and an empty Unifont
-    // include, and none of the built-in packs. Import the indexed ones afterwards, including on reruns that just
-    // extracted the JAR again. They are optional when preparing from
-    // already-imported JARs.
-    sounds::optional_assets(repo, minecraft, run.log);
+    let mut indexed = sounds::Assets::load(repo, minecraft, run.log);
+    let (version, count) = extract_client_resources(&run.client, root, indexed.as_mut().ok())?;
+    sounds::optional_imports(indexed.as_mut().map_err(|e| e.as_str()), run.log);
 
     // One file each, exported again when the exporter or the jar it reads changed.
     let single = |what: &str,
@@ -931,6 +928,54 @@ fn steps(
     )
 }
 
+/// Check existing JAR assets by their ZIP size/CRC without inflating every member again.
+/// Indexed panorama/font/language replacements have stronger SHA-1 checks and take precedence.
+fn extract_client_resources(
+    jar: &Path,
+    root: &Path,
+    mut indexed: Option<&mut sounds::Assets>,
+) -> Result<(Value, usize), String> {
+    let mut client = open_zip(jar)?;
+    let version = pyjson::loads(&zip_text(&mut client, "version.json")?)?;
+    let mut count = 0;
+    for name in zip_names(&client) {
+        if !(name.starts_with("assets/") || name.starts_with("data/") || name == "pack.png")
+            || name.ends_with('/')
+        {
+            continue;
+        }
+        let relative = member_path(&name, "Invalid resource path")?;
+        count += 1;
+        if let Some(assets) = &mut indexed {
+            if assets.imported(&name)? {
+                continue;
+            }
+        }
+        let target = root.join(relative);
+        let member = client.by_name(&name).map_err(|e| e.to_string())?;
+        let (size, crc) = (member.size(), member.crc32());
+        drop(member);
+        if target.is_file() && fs::metadata(&target).map_err(|e| e.to_string())?.len() == size {
+            let mut file = fs::File::open(&target).map_err(|e| e.to_string())?;
+            let mut hash = crc32fast::Hasher::new();
+            let mut buffer = [0; 16 * 1024];
+            loop {
+                let n = file.read(&mut buffer).map_err(|e| e.to_string())?;
+                if n == 0 {
+                    break;
+                }
+                hash.update(&buffer[..n]);
+            }
+            if hash.finalize() == crc {
+                continue;
+            }
+        }
+        mkdir(target.parent().unwrap())?;
+        write(&target, &zip_bytes(&mut client, &name)?)?;
+    }
+    Ok((version, count))
+}
+
 fn datagen_reports_missing(root: &Path) -> bool {
     ["items.json", "registries.json", "commands.json"]
         .iter()
diff --git a/crates/horizon-prepare/src/sounds.rs b/crates/horizon-prepare/src/sounds.rs
index 15d4a7a08..fd171ec12 100644
--- a/crates/horizon-prepare/src/sounds.rs
+++ b/crates/horizon-prepare/src/sounds.rs
@@ -5,7 +5,8 @@
 
 use crate::artifacts::{self, Lock};
 use crate::pyjson::Value;
-use crate::{digest, read_json, Log};
+use crate::{digest, Log};
+use std::collections::{HashMap, HashSet};
 use std::fs;
 use std::path::{Path, PathBuf};
 
@@ -18,8 +19,9 @@ fn launcher_assets(
     lock: &Lock,
     manifest: &Value,
     minecraft: &Path,
+    cached_index: &Path,
     log: Log,
-) -> Result<(PathBuf, PathBuf), String> {
+) -> Result<(PathBuf, PathBuf, Vec<u8>), String> {
     let assets = minecraft.join("assets");
     let info = manifest
         .get("assetIndex")
@@ -33,7 +35,10 @@ fn launcher_assets(
     if artifacts::safe_relative(id).is_none_or(|p| p.components().count() != 1) {
         return Err(format!("Unsafe asset index id {id:?}"));
     }
-    let index = assets.join("indexes").join(format!("{id}.json"));
+    let mut index = assets.join("indexes").join(format!("{id}.json"));
+    if !index.is_file() && cached_index.is_file() {
+        index = cached_index.to_path_buf();
+    }
     if !index.is_file() {
         let version = manifest.get("id").and_then(Value::as_str).unwrap_or("");
         return Err(format!(
@@ -42,7 +47,8 @@ fn launcher_assets(
             artifacts::launcher_hint(version)
         ));
     }
-    let checksum = digest(&index, "sha1")?;
+    let bytes = fs::read(&index).map_err(|e| format!("{}: {e}", index.display()))?;
+    let checksum = crate::hex(&<sha1::Sha1 as sha1::Digest>::digest(&bytes));
     if checksum != sha1 && !lock.asset_index_accepted(&checksum) {
         log(&format!(
             "{} is an asset index Horizon does not know yet (sha1 {checksum}); Mojang may have \
@@ -50,7 +56,7 @@ fn launcher_assets(
             index.display()
         ));
     }
-    Ok((assets, index))
+    Ok((assets, index, bytes))
 }
 
 /// Where the launcher's asset store keeps the object with this SHA-1.
@@ -61,24 +67,6 @@ fn object_path(assets: &Path, checksum: &str) -> Result<PathBuf, String> {
     Ok(assets.join("objects").join(&checksum[..2]).join(checksum))
 }
 
-/// One verified object from the launcher's asset store (tools/lab.py `launcher_object`).
-fn launcher_object(assets: &Path, checksum: &str) -> Result<PathBuf, String> {
-    let path = object_path(assets, checksum)?;
-    if !path.is_file() {
-        return Err(format!(
-            "Missing asset object {}. Play the pinned version once in your launcher.",
-            path.display()
-        ));
-    }
-    if digest(&path, "sha1")? != checksum {
-        return Err(format!(
-            "Corrupt asset object {}; let the launcher repair it",
-            path.display()
-        ));
-    }
-    Ok(path)
-}
-
 /// Whether the game plays this asset: sounds.json and everything under sounds/.
 fn is_sound(name: &str) -> bool {
     name == "minecraft/sounds.json" || name.starts_with("minecraft/sounds/")
@@ -127,26 +115,56 @@ fn is_language(name: &str) -> bool {
 }
 
 /// Full preparation can run from cached JARs without an official launcher install.
-pub(crate) fn optional_assets(root: &Path, minecraft: Option<&Path>, log: Log) {
-    if let Err(error) = panorama(root, minecraft, log) {
-        log(&format!(
-            "Title panorama not imported: {error}; run horizon-prepare panorama later"
-        ));
-    }
-    if let Err(error) = fonts(root, minecraft, log) {
-        log(&format!(
-            "Unifont glyphs not imported: {error}; run horizon-prepare fonts later"
-        ));
-    }
-    if let Err(error) = packs(root, minecraft, log) {
-        log(&format!(
-            "Programmer Art and High Contrast not imported: {error}; run horizon-prepare packs later"
-        ));
-    }
-    if let Err(error) = languages(root, minecraft, log) {
-        log(&format!(
-            "Languages not imported: {error}; run horizon-prepare languages later"
-        ));
+#[cfg(test)]
+fn optional_assets(root: &Path, minecraft: Option<&Path>, log: Log) {
+    optional_imports(
+        Assets::load(root, minecraft, log)
+            .as_mut()
+            .map_err(|e| e.as_str()),
+        log,
+    );
+}
+
+pub(crate) fn optional_imports(mut assets: Result<&mut Assets, &str>, log: Log) {
+    for (wanted, label, required, failure, command) in [
+        (
+            is_panorama as fn(&str) -> bool,
+            "Panorama",
+            PANORAMA.as_slice(),
+            "Title panorama",
+            "panorama",
+        ),
+        (
+            is_font,
+            "Font",
+            UNIFONT.as_slice(),
+            "Unifont glyphs",
+            "fonts",
+        ),
+        (
+            is_built_in_pack,
+            "Built-in pack",
+            BUILT_IN_PACKS.as_slice(),
+            "Programmer Art and High Contrast",
+            "packs",
+        ),
+        (
+            is_language,
+            "Language",
+            LANGUAGES.as_slice(),
+            "Languages",
+            "languages",
+        ),
+    ] {
+        let result = match &mut assets {
+            Ok(assets) => assets.copy(wanted, label, required, log).map(|_| ()),
+            Err(error) => Err(error.to_string()),
+        };
+        if let Err(error) = result {
+            log(&format!(
+                "{failure} not imported: {error}; run horizon-prepare {command} later"
+            ));
+        }
     }
 }
 
@@ -207,29 +225,98 @@ fn copy_assets(
     label: &str,
     required: &[&str],
 ) -> Result<PathBuf, String> {
-    let lock = Lock::read(root)?;
-    let minecraft = artifacts::minecraft_dir(minecraft);
-    let manifest = artifacts::import_manifest(&lock, &minecraft)?;
-    let (store, index) = launcher_assets(&lock, &manifest, &minecraft, log)?;
-    let id = manifest
-        .get("id")
-        .and_then(Value::as_str)
-        .ok_or("The version JSON has no id")?;
-    let target = root.join(".local/horizon-client").join(id);
-    fs::create_dir_all(&target).map_err(|e| format!("{}: {e}", target.display()))?;
-    fs::copy(&index, target.join("asset-index.json"))
-        .map_err(|e| format!("{}: {e}", target.join("asset-index.json").display()))?;
-    let objects = read_json(&index)?;
-    let objects = objects
-        .get("objects")
-        .and_then(Value::as_object)
-        .ok_or_else(|| format!("{} has no objects", index.display()))?;
+    Assets::load(root, minecraft, log)?.copy(wanted_asset, label, required, log)
+}
+
+/// A preparation's index and verified destinations. Never persisted: a later invocation
+/// checks the bytes again, including when repairing a corrupt prepared file.
+pub(crate) struct Assets {
+    store: PathBuf,
+    target: PathBuf,
+    objects: Vec<(String, Value)>,
+    verified: HashSet<PathBuf>,
+}
+
+impl Assets {
+    pub(crate) fn load(root: &Path, minecraft: Option<&Path>, log: Log) -> Result<Self, String> {
+        let lock = Lock::read(root)?;
+        let minecraft = artifacts::minecraft_dir(minecraft);
+        let manifest = artifacts::import_manifest(&lock, &minecraft)?;
+        let target = root.join(".local/horizon-client").join(&lock.version);
+        let (store, index, bytes) = launcher_assets(
+            &lock,
+            &manifest,
+            &minecraft,
+            &target.join("asset-index.json"),
+            log,
+        )?;
+        let text = std::str::from_utf8(&bytes).map_err(|e| e.to_string())?;
+        let objects = crate::pyjson::loads(text)?;
+        let objects = objects
+            .get("objects")
+            .and_then(Value::as_object)
+            .ok_or_else(|| format!("{} has no objects", index.display()))?
+            .to_vec();
+        fs::create_dir_all(&target).map_err(|e| e.to_string())?;
+        crate::write_if_changed(&target.join("asset-index.json"), &bytes)?;
+        Ok(Self {
+            store,
+            target,
+            objects,
+            verified: HashSet::new(),
+        })
+    }
+
+    /// Preserve indexed replacements instead of overwriting them with JAR placeholders.
+    pub(crate) fn imported(&mut self, name: &str) -> Result<bool, String> {
+        let Some(name) = name.strip_prefix("assets/") else {
+            return Ok(false);
+        };
+        if !(is_panorama(name) || is_font(name) || is_language(name)) {
+            return Ok(false);
+        }
+        let Some((_, info)) = self.objects.iter().rev().find(|(n, _)| n == name) else {
+            return Ok(false);
+        };
+        let Some(hash) = info.get("hash").and_then(Value::as_str) else {
+            return Ok(false);
+        };
+        let destination = self.target.join("assets").join(name);
+        if destination.is_file() && digest(&destination, "sha1")? == hash {
+            self.verified.insert(destination);
+            return Ok(true);
+        }
+        Ok(false)
+    }
+
+    fn copy(
+        &mut self,
+        wanted_asset: fn(&str) -> bool,
+        label: &str,
+        required: &[&str],
+        log: Log,
+    ) -> Result<PathBuf, String> {
+        copy_indexed(self, wanted_asset, label, required, log)
+    }
+}
+
+fn copy_indexed(
+    assets: &mut Assets,
+    wanted_asset: fn(&str) -> bool,
+    label: &str,
+    required: &[&str],
+    log: Log,
+) -> Result<PathBuf, String> {
+    let objects = &assets.objects;
     // A repeated name keeps its first place and its last value, as a Python dict does.
     let mut wanted: Vec<(&str, &Value)> = Vec::new();
+    let mut positions = HashMap::new();
     for (name, info) in objects.iter().filter(|(name, _)| wanted_asset(name)) {
-        match wanted.iter_mut().find(|(n, _)| n == name) {
-            Some(entry) => entry.1 = info,
-            None => wanted.push((name, info)),
+        if let Some(&position) = positions.get(name.as_str()) {
+            wanted[position] = (name.as_str(), info);
+        } else {
+            positions.insert(name.as_str(), wanted.len());
+            wanted.push((name, info));
         }
     }
     for name in required {
@@ -251,21 +338,45 @@ fn copy_assets(
             .ok_or_else(|| format!("{name} has no size in the asset index"))?;
         let relative = artifacts::safe_relative(name)
             .ok_or_else(|| format!("Unsafe asset name {name:?} in the asset index"))?;
-        let source = launcher_object(&store, hash)?;
-        copies.push((source, target.join("assets").join(relative), hash));
+        let source = object_path(&assets.store, hash)?;
+        let destination = assets.target.join("assets").join(relative);
+        let import = crate::files::Import::stage(
+            &source,
+            &destination,
+            hash,
+            "sha1",
+            assets.verified.contains(&destination),
+        )
+        .map_err(|error| {
+            if !source.is_file() {
+                format!(
+                    "Missing asset object {}. Play the pinned version once in your launcher.",
+                    source.display()
+                )
+            } else if error.contains(" is not the pinned file:") {
+                format!(
+                    "Corrupt asset object {}; let the launcher repair it: {error}",
+                    source.display()
+                )
+            } else {
+                error
+            }
+        })?;
+        copies.push((import, destination));
         total += size;
     }
     // Check the entire set before replacing any placeholders: a missing late face
     // must not leave a mixture of real textures and gray faces in either entry point.
-    for (source, destination, hash) in copies {
-        artifacts::import_copy(&source, &destination, hash, "sha1", "")?;
+    for (import, destination) in copies {
+        import.commit()?;
+        assets.verified.insert(destination);
     }
     log(&format!(
         "{label} assets ready: {} files, {:.1} MB",
         wanted.len(),
         total as f64 / 1e6
     ));
-    Ok(target)
+    Ok(assets.target.clone())
 }
 
 #[cfg(test)]
@@ -680,6 +791,7 @@ mod tests {
             "minecraft/sounds.json is missing from the asset index"
         );
         fs::remove_file(&index).unwrap();
+        fs::remove_file(f.root.join(".local/horizon-client/9.9/asset-index.json")).unwrap();
         let error = f.run().unwrap_err();
         assert!(
             error.starts_with("Missing ") && error.contains("play 9.9 once"),
@@ -687,6 +799,120 @@ mod tests {
         );
     }
 
+    #[test]
+    fn late_corruption_discards_all_staged_replacements() {
+        let f = Fixture::new("late-corruption");
+        let target = f.root.join(".local/horizon-client/9.9/assets");
+        for name in PANORAMA {
+            let path = target.join(name);
+            fs::create_dir_all(path.parent().unwrap()).unwrap();
+            fs::write(path, b"placeholder").unwrap();
+        }
+        fs::write(f.object(FIRST_FACE + 6), b"bad overlay").unwrap();
+        assert!(panorama(&f.root, Some(&f.minecraft), &|_| {}).is_err());
+        for name in PANORAMA {
+            assert_eq!(fs::read(target.join(name)).unwrap(), b"placeholder");
+        }
+        assert_eq!(
+            fs::read_dir(target.join("minecraft/textures/gui/title/background"))
+                .unwrap()
+                .count(),
+            7
+        );
+    }
+
+    #[test]
+    fn one_index_snapshot_serves_every_import_and_reruns_repair_corruption() {
+        let f = Fixture::with_extras("snapshot", &PANORAMA, &[("pack.mcmeta", b"{}")]);
+        let mut assets = Assets::load(&f.root, Some(&f.minecraft), &|_| {}).unwrap();
+        fs::remove_file(f.minecraft.join("assets/indexes/7.json")).unwrap();
+        let lines = std::cell::RefCell::new(Vec::new());
+        optional_imports(Ok(&mut assets), &|line| {
+            lines.borrow_mut().push(line.to_string())
+        });
+        assert_eq!(lines.borrow().len(), 4);
+        assert!(lines
+            .borrow()
+            .iter()
+            .all(|line| line.contains("assets ready")));
+        assets
+            .copy(is_sound, "Sound", &["minecraft/sounds.json"], &|_| {})
+            .unwrap();
+        let sound = assets
+            .target
+            .join("assets/minecraft/sounds/ambient/cave1.ogg");
+        let time = fs::metadata(&sound).unwrap().modified().unwrap();
+        fs::remove_file(f.object(1)).unwrap();
+        f.run().unwrap(); // A verified destination works even without the source object/index.
+        assert_eq!(fs::metadata(&sound).unwrap().modified().unwrap(), time);
+        fs::write(&sound, b"corrupt").unwrap();
+        assert!(f.run().is_err()); // Verification never carries over to another invocation.
+        fs::write(f.object(1), &f.objects[1].1).unwrap();
+        f.run().unwrap();
+        assert_eq!(fs::read(sound).unwrap(), f.objects[1].1);
+    }
+
+    #[test]
+    fn jar_reruns_preserve_indexed_assets_and_repair_missing_or_corrupt_members() {
+        use std::io::Write;
+        let f = Fixture::with_extras(
+            "extract",
+            &PANORAMA,
+            &[
+                ("pack.mcmeta", b"{}"),
+                ("minecraft/lang/en_us.json", b"{\"indexed\":true}"),
+            ],
+        );
+        optional_assets(&f.root, Some(&f.minecraft), &|_| {});
+        let target = f.root.join(".local/horizon-client/9.9");
+        let jar = f.root.join("client.jar");
+        let mut zip = zip::ZipWriter::new(fs::File::create(&jar).unwrap());
+        for (name, data) in [
+            ("version.json", "{\"world_version\": 1}"),
+            (
+                "assets/minecraft/textures/gui/title/background/panorama_0.png",
+                "gray",
+            ),
+            ("assets/minecraft/font/include/unifont.json", "{}"),
+            ("assets/minecraft/lang/en_us.json", "{}"),
+            ("data/minecraft/test.json", "data"),
+            ("pack.png", "icon"),
+        ] {
+            zip.start_file(name, zip::write::SimpleFileOptions::default())
+                .unwrap();
+            zip.write_all(data.as_bytes()).unwrap();
+        }
+        zip.finish().unwrap();
+        let face = target.join("assets").join(PANORAMA[0]);
+        let time = fs::metadata(&face).unwrap().modified().unwrap();
+        // Preparing from cached JARs must also preserve full imports without the launcher.
+        fs::remove_dir_all(f.minecraft.join("assets")).unwrap();
+        for _ in 0..2 {
+            let mut assets = Assets::load(&f.root, Some(&f.minecraft), &|_| {}).unwrap();
+            let (_, count) =
+                crate::extract_client_resources(&jar, &target, Some(&mut assets)).unwrap();
+            assert_eq!(count, 5);
+            optional_imports(Ok(&mut assets), &|_| {});
+            assert_eq!(fs::read(&face).unwrap(), PANORAMA[0].as_bytes());
+            assert_eq!(fs::metadata(&face).unwrap().modified().unwrap(), time);
+            assert_eq!(
+                fs::read(target.join("assets").join(UNIFONT[0])).unwrap(),
+                f.objects[4].1
+            );
+            assert_eq!(
+                fs::read(target.join("assets/minecraft/lang/en_us.json")).unwrap(),
+                b"{\"indexed\":true}"
+            );
+            assert_eq!(
+                fs::read(target.join("data/minecraft/test.json")).unwrap(),
+                b"data"
+            );
+            assert_eq!(fs::read(target.join("pack.png")).unwrap(), b"icon");
+            fs::write(target.join("data/minecraft/test.json"), b"oops").unwrap();
+            fs::remove_file(target.join("pack.png")).unwrap();
+        }
+    }
+
     #[test]
     fn object_paths_come_from_real_hashes() {
         let store = Path::new("assets");
diff --git a/docs/prepare-performance.md b/docs/prepare-performance.md
new file mode 100644
index 000000000..3a3587111
--- /dev/null
+++ b/docs/prepare-performance.md
@@ -0,0 +1,44 @@
+# Resource preparation and filesystem work
+
+The reported preparation timings put sounds at 20–29 seconds with little CPU use, versus
+0.9–1.4 seconds for fresh client asset extraction. Prefer fewer file opens, reads and writes
+over parallelizing decompression.
+
+Preparation now shares one parsed asset index between panorama, font, pack and language imports.
+Its destination verification results live only for that preparation. A subsequent invocation
+checks bytes again, so it can repair corrupt resources. Existing valid destination files do not
+require the original asset objects to remain installed. A saved asset index also lets preparation
+preserve full imports when only cached Minecraft JARs remain.
+
+New imports are staged beside their destination. On Linux, FICLONE is attempted first; other
+filesystems fall back to copying while hashing. Cloned copies are hashed before publication.
+macOS attempts clonefile with the same checked streaming fallback. A whole asset group is staged and
+verified before any replacement is published; corrupt late panorama faces leave placeholders
+alone. Temporary files are cleaned up on errors. This is not a transaction for rename failures
+or process termination during publication: a later run repairs incomplete groups.
+
+Unchanged JAR resources are checked by the ZIP member's size and CRC, avoiding repeated
+decompression. Valid indexed replacements take precedence over JAR placeholders. Reusing checked
+Minecraft imports also passes the verified artifact/library results directly to the exporters.
+
+## An immutable store across releases
+
+The official launcher's SHA-1 object store already provides an immutable source for indexed
+assets. Independent filesystem clones let installed Horizon releases share physical blocks
+where supported, without sharing writable inodes. Ordinary copies remain the fallback.
+
+A separate Horizon store could additionally share complete preparations on filesystems without
+cloning. Its key would need the pinned client/server hashes, the preparer's output version (or
+the legacy source/exporter fingerprint), and the actual asset-index digest: Mojang republishes
+translations without changing the Minecraft release. Two preparations with different optional
+asset availability must not claim the same complete snapshot.
+
+Before adopting that store, separate immutable runtime resources from mutable exporter scratch,
+classes and logs. Publish snapshots through a temporary directory and atomic rename, give each
+release an explicit reference, and define locking, corruption repair, migration and garbage
+collection. Exporters must never receive a shared writable directory or hard-linked files.
+The existing launcher compatibility check should choose reuse; the store should only supply its
+bytes. Keep this separate from the open work on output-version compatibility (#1946/#1947).
+
+For now, retain independent release directories and clone their resource files. This reduces
+copying where the filesystem supports it without introducing a second ownership/cleanup scheme.
diff --git a/launcher/Cargo.lock b/launcher/Cargo.lock
index 1e8a5aee2..ee0cb882a 100644
--- a/launcher/Cargo.lock
+++ b/launcher/Cargo.lock
@@ -2726,6 +2726,8 @@ dependencies = [
 name = "horizon-prepare"
 version = "0.1.0"
 dependencies = [
+ "crc32fast",
+ "libc",
  "regex",
  "sha1",
  "sha2 0.10.9",
diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 7e5c4babb..dadef73d3 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -719,7 +719,7 @@ fn copy_dir(from: &Path, to: &Path) -> std::io::Result<()> {
         if entry.file_type()?.is_dir() {
             copy_dir(&entry.path(), &target)?;
         } else {
-            fs::copy(entry.path(), target)?;
+            horizon_prepare::clone_or_copy(&entry.path(), &target)?;
         }
     }
     Ok(())

From c28bea8e96cdf9ec7db298295664626926cb63f1 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:06:16 +0100
Subject: [PATCH 217/270] Mod API: input's permission line says it sees keys
 and clicks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-mods/src/manifest.rs | 4 +++-
 docs/api/mods-reference.md          | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index e9535bc78..9e998dae1 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -133,7 +133,9 @@ impl Capability {
             Capability::Registries => "add blocks and items to your worlds",
             Capability::Ui => "show its own screens and a settings page",
             Capability::Render => "draw on your screen and shake the camera",
-            Capability::Input => "take over the use button on its own items, and add keys",
+            Capability::Input => {
+                "see the keys you hold and your clicks, take over the use button on its own items, and add keys"
+            }
         }
     }
     /// The capability a component import needs, `Ok(None)` for one every
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index e371f3975..333b65bd0 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -14,7 +14,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
 | `ui` | [`ui`](#ui) | show its own screens and a settings page |
 | `render` | [`render`](#render) | draw on your screen and shake the camera |
-| `input` | [`input`](#input) | take over the use button on its own items, and add keys |
+| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items, and add keys |
 
 ## World `horizon-mod`
 

From 6824224a333df0771dcf085566cb898416463be3 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:06:22 +0100
Subject: [PATCH 218/270] Player heads: read the profile's skin once, and no
 skull on a piston head

- Skull keeps what its profile draws (the skin URL, its skins/<sha1>
  sprite and the default skin), computed when the block entity loads,
  instead of decoding base64 JSON and hashing it for every head every
  frame; skull_skin_at no longer scans the chunk's saved block entities.
- BlockEntity::for_block gave minecraft:piston_head a skull block entity
  (it ends in _head), which would have been saved as minecraft:skull.
- AGENTS.md is left as it is on main: the workflow note is not part of
  this fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |  4 --
 .../horizon-client/src/block_entity_render.rs |  6 +--
 crates/horizon-client/src/containers.rs       | 50 +++++++++++++++++--
 .../src/game/block_entity_anims.rs            | 37 ++++++--------
 crates/horizon-client/src/save.rs             | 18 ++++---
 5 files changed, 74 insertions(+), 41 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ed76c08dd..2d883b33b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,10 +27,6 @@ Feature → files → harness for the most-changed areas: [docs/architecture.md]
   change), none for a fix. Agents never add `release-now`: the maintainer decides it. Merges ship in batches of 5, or after
   6 hours ([docs/release-flow.md](docs/release-flow.md)).
 - Contributors first: `gh pr list --state open --search <area>` before you start; never duplicate theirs.
-- Asked for a feature? Run the whole loop: check open PRs for the area (above), work in a new worktree,
-  `git fetch` the upstream remote (`ludovic111/horizon`) and start from its latest `main`, build, run
-  `tools/pr_ready.py`, then push to your fork and open the pull request against upstream's `main` —
-  never against the fork itself.
 
 ## Crates
 
diff --git a/crates/horizon-client/src/block_entity_render.rs b/crates/horizon-client/src/block_entity_render.rs
index a863d6214..620640188 100644
--- a/crates/horizon-client/src/block_entity_render.rs
+++ b/crates/horizon-client/src/block_entity_render.rs
@@ -733,7 +733,7 @@ pub struct Scene<'a> {
     /// The skin sprite a `player_head` shows at a position (`SkullBlockRenderer`
     /// profile → skin): a downloaded `skins/<sha1>` slot or the profile's
     /// `DefaultPlayerSkin` fallback; None keeps `SKIN_BY_TYPE` (steve).
-    pub skull: &'a dyn Fn([i32; 3]) -> Option<String>,
+    pub skull: &'a dyn Fn([i32; 3]) -> Option<&'a str>,
     /// Font glyph cell (none for blank glyphs such as the space) and advance.
     pub glyph: &'a dyn Fn(char) -> (Option<Rect>, f32),
 }
@@ -1285,10 +1285,8 @@ impl BlockEntityRenderer {
                 };
                 // SkullBlockRenderer.getRenderType: the profile's skin when it
                 // resolves, `SKIN_BY_TYPE` (steve) otherwise.
-                let skin;
                 let texture = if *kind == SkullType::Player {
-                    skin = (scene.skull)(pos);
-                    skin.as_deref().unwrap_or(texture)
+                    (scene.skull)(pos).unwrap_or(texture)
                 } else {
                     texture
                 };
diff --git a/crates/horizon-client/src/containers.rs b/crates/horizon-client/src/containers.rs
index 7c9da6862..1f8fad151 100644
--- a/crates/horizon-client/src/containers.rs
+++ b/crates/horizon-client/src/containers.rs
@@ -82,14 +82,56 @@ pub enum BlockEntity {
     /// `SkullBlockEntity` of every skull and head block.
     Skull(Skull),
 }
-/// `SkullBlockEntity`: the player profile the head shows (kept as loaded —
-/// `SkullOwner` is a compound, or a string when it names a player only),
-/// the note block sound and `custom_name`.
+/// `SkullBlockEntity`: the player profile the head shows (kept as loaded:
+/// a compound, or a string when it names a player only), the note block
+/// sound and `custom_name`.
 #[derive(Clone, Debug, Default)]
 pub struct Skull {
     pub profile: Option<horizon_world::nbt::Tag>,
     pub note_block_sound: Option<String>,
     pub custom_name: Option<horizon_world::nbt::Tag>,
+    /// What `profile` draws, read from it once rather than every frame.
+    pub skin: Option<SkullSkin>,
+}
+impl Skull {
+    pub fn new(
+        profile: Option<horizon_world::nbt::Tag>,
+        note_block_sound: Option<String>,
+        custom_name: Option<horizon_world::nbt::Tag>,
+    ) -> Self {
+        let skin = profile.as_ref().map(SkullSkin::of);
+        Self {
+            profile,
+            note_block_sound,
+            custom_name,
+            skin,
+        }
+    }
+}
+/// `SkullBlockRenderer.getPlayerSkin` of a head's profile: its skin's URL
+/// with the `skins/<sha1>` sprite it downloads to, and the
+/// `DefaultPlayerSkin` drawn until that sprite is there (steve for a
+/// profile with no id).
+#[derive(Clone, Debug)]
+pub struct SkullSkin {
+    pub download: Option<(String, String)>,
+    pub fallback: &'static str,
+}
+impl SkullSkin {
+    pub fn of(profile: &horizon_world::nbt::Tag) -> Self {
+        let download = crate::skins::profile_skin_url_nbt(profile).and_then(|url| {
+            let location = crate::skins::skin_location(&crate::skins::texture_hash(&url)?);
+            Some((url, location))
+        });
+        let fallback = crate::skins::profile_uuid_nbt(profile)
+            .map_or("entity/player/wide/steve", crate::tab_list::default_skin);
+        Self { download, fallback }
+    }
+}
+/// The skull and head blocks (`SkullBlock`, `WallSkullBlock`): every
+/// `*_skull` and `*_head` but the piston's head.
+fn is_skull(name: &str) -> bool {
+    name.ends_with("_skull") || (name.ends_with("_head") && name != "minecraft:piston_head")
 }
 /// `CrafterBlockEntity`: nine slots that can be disabled, the powered flag
 /// and the ticks left in the crafting animation.
@@ -244,7 +286,7 @@ impl BlockEntity {
         if name.ends_with("_banner") {
             return Some(Self::Banner(Banner::default()));
         }
-        if name.ends_with("_head") || name.ends_with("_skull") {
+        if is_skull(name) {
             return Some(Self::Skull(Skull::default()));
         }
         if name == "minecraft:beacon" {
diff --git a/crates/horizon-client/src/game/block_entity_anims.rs b/crates/horizon-client/src/game/block_entity_anims.rs
index 136738350..55f9c42ba 100644
--- a/crates/horizon-client/src/game/block_entity_anims.rs
+++ b/crates/horizon-client/src/game/block_entity_anims.rs
@@ -394,34 +394,25 @@ impl Game<'_> {
     pub(super) fn chest_lid(&self, pos: [i32; 3], partial: f32) -> f32 {
         self.be_anims.lid(pos, partial)
     }
-    /// `SkullBlockRenderer.getPlayerSkin`: the skin sprite of the `profile` of
+    /// `SkullBlockRenderer.getPlayerSkin`: the skin sprite of the profile of
     /// the player head at `pos`. The skin download is started here; while it
-    /// is in flight (or when it cannot be got) the profile's uuid picks the
-    /// `DefaultPlayerSkin` for it, and a profile with no id keeps steve. A
-    /// head with no profile answers None so `SKIN_BY_TYPE` applies.
-    pub(super) fn skull_skin_at(&self, pos: [i32; 3]) -> Option<String> {
-        let key = (pos[0], pos[1], pos[2]);
-        let profile = match self.world.block_entities.get(&key) {
-            Some(BlockEntity::Skull(s)) => s.profile.clone(),
-            _ => None,
-        }
-        .or_else(|| self.saved_tag(pos).and_then(|t| t.get("profile").cloned()));
-        let profile = profile?;
-        if let Some(url) = skins::profile_skin_url_nbt(&profile)
-            && let Some(location) =
-                skins::texture_hash(&url).map(|hash| skins::skin_location(&hash))
-        {
+    /// is in flight (or when it cannot be got) the profile's default skin
+    /// stands in. A head with no profile answers None: `SKIN_BY_TYPE`.
+    pub(super) fn skull_skin_at(&self, pos: [i32; 3]) -> Option<&str> {
+        let Some(BlockEntity::Skull(skull)) =
+            self.world.block_entities.get(&(pos[0], pos[1], pos[2]))
+        else {
+            return None;
+        };
+        let skin = skull.skin.as_ref()?;
+        if let Some((url, location)) = &skin.download {
             self.skin_downloads
                 .borrow_mut()
-                .state(skins::Kind::Skin, &url);
-            if self.gui.atlas.sprites.contains_key(&location) {
+                .state(skins::Kind::Skin, url);
+            if self.gui.atlas.sprites.contains_key(location) {
                 return Some(location);
             }
         }
-        Some(
-            skins::profile_uuid_nbt(&profile)
-                .map(|uuid| horizon_client::tab_list::default_skin(uuid).to_owned())
-                .unwrap_or_else(|| "entity/player/wide/steve".to_owned()),
-        )
+        Some(skin.fallback)
     }
 }
diff --git a/crates/horizon-client/src/save.rs b/crates/horizon-client/src/save.rs
index c59c3c974..964a32cb4 100644
--- a/crates/horizon-client/src/save.rs
+++ b/crates/horizon-client/src/save.rs
@@ -637,13 +637,12 @@ pub fn decode_block_entity(tag: &Tag) -> Option<((i32, i32, i32), crate::contain
     if id == "minecraft:skull" {
         return Some((
             pos,
-            BlockEntity::Skull(crate::containers::Skull {
-                profile: tag.get("profile").cloned(),
-                note_block_sound: text(tag.get("note_block_sound")),
-                custom_name: tag
-                    .get("custom_name")
+            BlockEntity::Skull(crate::containers::Skull::new(
+                tag.get("profile").cloned(),
+                text(tag.get("note_block_sound")),
+                tag.get("custom_name")
                     .and_then(crate::block_entity_nbt::component),
-            }),
+            )),
         ));
     }
     // A spawner's block entity id is not its block's name.
@@ -3940,6 +3939,13 @@ mod tests {
         );
         let (_, decoded) = decode_block_entity(&plain).expect("plain skull");
         assert!(matches!(decoded, crate::containers::BlockEntity::Skull(_)));
+        // The heads and skulls have one; the piston's head is no skull.
+        use crate::containers::BlockEntity;
+        assert!(matches!(
+            BlockEntity::for_block("minecraft:player_wall_head"),
+            Some(BlockEntity::Skull(_))
+        ));
+        assert!(BlockEntity::for_block("minecraft:piston_head").is_none());
     }
 
     #[test]

From fbd6bee3e3adc4f2d64b2e5e3520899fdc0f5239 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:03:38 +0100
Subject: [PATCH 219/270] Official mods: FPS Counter and Keystrokes, the first
 extras as mods

The FPS counter and keystrokes extras rewritten as mods on the public API
(render, input, ui, storage), in mods/official/, with the extras' options
on their settings pages and the extras' look: the same boxes, colours and
text positions, pixel for pixel. They are workspace members, so clippy and
pr_ready cover them; a maintainer publishes them in horizon-mods. The
built-in extras stay until the removal PR, which installs these for the
players who had them on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                                 |  14 ++
 Cargo.toml                                 |   2 +-
 docs/mods.md                               |  16 ++
 mods/official/fps-overlay/Cargo.toml       |  16 ++
 mods/official/fps-overlay/horizon-mod.toml |   9 +
 mods/official/fps-overlay/src/lib.rs       | 131 ++++++++++++++
 mods/official/keystrokes/Cargo.toml        |  16 ++
 mods/official/keystrokes/horizon-mod.toml  |   9 +
 mods/official/keystrokes/src/lib.rs        | 192 +++++++++++++++++++++
 9 files changed, 404 insertions(+), 1 deletion(-)
 create mode 100644 mods/official/fps-overlay/Cargo.toml
 create mode 100644 mods/official/fps-overlay/horizon-mod.toml
 create mode 100644 mods/official/fps-overlay/src/lib.rs
 create mode 100644 mods/official/keystrokes/Cargo.toml
 create mode 100644 mods/official/keystrokes/horizon-mod.toml
 create mode 100644 mods/official/keystrokes/src/lib.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6945e09cf..ecea2e04e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -993,6 +993,13 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fps-overlay"
+version = "1.0.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "futures-core"
 version = "0.3.34"
@@ -1812,6 +1819,13 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "keystrokes"
+version = "1.0.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.1"
diff --git a/Cargo.toml b/Cargo.toml
index 4076b9079..57991c185 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "mods/official/fps-overlay", "mods/official/keystrokes", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/docs/mods.md b/docs/mods.md
index d92c88fa6..44cd24122 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -15,6 +15,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage, ui; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
+| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
 | Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run / check`, and the registry's CI (`registry build / review / list`) |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
@@ -406,6 +407,21 @@ An update is the same form with a new version; only the project's `owners` can p
 has one. A published file never changes. Without the form, open the pull request by hand (the repository's README
 says how). The formats: [api/mod-index.md](api/mod-index.md).
 
+### Horizon's official mods
+
+The Horizon extras that are mods now live in `mods/official/<name>/`, one crate each in the game's workspace, so
+`cargo clippy --workspace` and pr_ready cover them. They use only the public API, like any other mod, with the same
+options on their settings page as the extra had and the same look. Each is published by a maintainer: build it on
+`main` with the toolchain CI uses (`cd mods/official/<name> && cargo horizon-mod build`), then open a pull request in
+horizon-mods with its `mods/<id>.toml` (owners `ludovic111`, `source` pointing at the folder) and the file's
+SHA-256. The reviewer builds it the same way and merges only when the hashes match: the `.wasm` holds no local paths,
+so the same rustc and `Cargo.lock` give the same file.
+
+| Mod | Id | Replaces | Settings (storage key: values) |
+|---|---|---|---|
+| FPS Counter | `fps_overlay` | Extras > FPS counter | `corner`: `top_left` (default), `top_right`, `bottom_left`, `bottom_right`; `lows`: `false` (default), `true` |
+| Keystrokes | `keystrokes` | Extras > Keystrokes | `corner`: as above, default `top_left`; `cps`: `true` (default), `false` |
+
 ## Versions and compatibility
 
 - The API is the WIT package `horizon:mods@0.1.0`. New functions and
diff --git a/mods/official/fps-overlay/Cargo.toml b/mods/official/fps-overlay/Cargo.toml
new file mode 100644
index 000000000..7af17ea0d
--- /dev/null
+++ b/mods/official/fps-overlay/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "fps-overlay"
+version = "1.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "Horizon's official FPS counter: frames per second in a corner, with the minimum and the 1% low."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../../../crates/horizon-mod-sdk" }
+
+[lints]
+workspace = true
diff --git a/mods/official/fps-overlay/horizon-mod.toml b/mods/official/fps-overlay/horizon-mod.toml
new file mode 100644
index 000000000..b18e79f12
--- /dev/null
+++ b/mods/official/fps-overlay/horizon-mod.toml
@@ -0,0 +1,9 @@
+id = "fps_overlay"
+name = "FPS Counter"
+version = "1.0.0"
+description = "Frames per second in a corner of the screen, with the slowest frame and the 1% low if you like. Horizon's own, formerly an extra."
+authors = ["Horizon"]
+api = "0.1"
+side = "client"
+capabilities = ["render", "ui", "storage"]
+experimental = ["render", "ui"]
diff --git a/mods/official/fps-overlay/src/lib.rs b/mods/official/fps-overlay/src/lib.rs
new file mode 100644
index 000000000..897402d02
--- /dev/null
+++ b/mods/official/fps-overlay/src/lib.rs
@@ -0,0 +1,131 @@
+//! Horizon's official FPS counter, formerly the built-in extra: the game's
+//! frame counter (frames in the last second, the slowest frame and the 1%
+//! low of the last 5 seconds) in a box in a corner, drawn as the extra drew
+//! it. Its settings page has the extra's two options; they are kept in the
+//! mod's storage (`corner`, `lows`), where the game writes a player's old
+//! extra settings when it installs the mod for them.
+use horizon_mod_sdk::{
+    Mod, Registration,
+    render::{self, Corner, FillShape, Point, Rect, Shape, TextShape},
+    storage,
+    ui::{self, ButtonWidget, Widget},
+};
+
+/// The extra's box: translucent black, white text with a shadow.
+const BACKGROUND: u32 = 0x7800_0000;
+const CORNERS: [(Corner, &str, &str); 4] = [
+    (Corner::TopLeft, "top_left", "Top left"),
+    (Corner::TopRight, "top_right", "Top right"),
+    (Corner::BottomLeft, "bottom_left", "Bottom left"),
+    (Corner::BottomRight, "bottom_right", "Bottom right"),
+];
+/// Settings page buttons.
+const CORNER_BUTTON: u32 = 1;
+const LOWS_BUTTON: u32 = 2;
+
+struct Fps {
+    /// Index in `CORNERS`.
+    corner: usize,
+    lows: bool,
+    /// What the box shows now, to redraw only on a change.
+    shown: String,
+}
+
+impl Fps {
+    fn text(&self, f: render::FrameRate) -> String {
+        if self.lows {
+            format!("{} fps  min {}  1% {}", f.fps, f.min, f.low)
+        } else {
+            format!("{} fps", f.fps)
+        }
+    }
+    fn draw(&mut self) {
+        let text = self.text(render::frame_stats());
+        if text == self.shown {
+            return;
+        }
+        let w = render::text_width(&text) + 4.0;
+        render::set_corner(
+            CORNERS[self.corner].0,
+            w,
+            12.0,
+            &[
+                Shape::Fill(FillShape {
+                    rect: Rect {
+                        x: 0.0,
+                        y: 0.0,
+                        w,
+                        h: 12.0,
+                    },
+                    color: BACKGROUND,
+                }),
+                Shape::Text(TextShape {
+                    text: text.clone(),
+                    at: Point { x: 2.0, y: 2.0 },
+                    color: 0xFF_FFFF,
+                    centered: false,
+                    shadow: true,
+                }),
+            ],
+        );
+        self.shown = text;
+    }
+    /// The settings page: the screen's title is the mod's name already.
+    fn page(&self) {
+        let on = |b: bool| if b { "ON" } else { "OFF" };
+        ui::set_settings(&[
+            Widget::Button(ButtonWidget {
+                id: CORNER_BUTTON,
+                label: format!("Corner: {}", CORNERS[self.corner].2),
+            }),
+            Widget::Button(ButtonWidget {
+                id: LOWS_BUTTON,
+                label: format!("Minimum and 1% low: {}", on(self.lows)),
+            }),
+        ]);
+    }
+    fn save(&self) {
+        let _ = storage::set("corner", CORNERS[self.corner].1.as_bytes());
+        let _ = storage::set("lows", if self.lows { b"true" } else { b"false" });
+    }
+}
+
+fn stored(key: &str) -> Option<String> {
+    storage::get(key).and_then(|v| String::from_utf8(v).ok())
+}
+
+impl Mod for Fps {
+    fn init() -> Result<(Self, Registration), String> {
+        // The extra's defaults: top left, no lows.
+        let corner = stored("corner")
+            .and_then(|c| CORNERS.iter().position(|k| k.1 == c.trim()))
+            .unwrap_or(0);
+        let lows = stored("lows").is_some_and(|v| v.trim() == "true");
+        let fps = Fps {
+            corner,
+            lows,
+            shown: String::new(),
+        };
+        fps.page();
+        Ok((fps, Registration::new().on_tick()))
+    }
+    fn tick(&mut self, _tick: u64) {
+        self.draw();
+    }
+    fn ui_select(&mut self, id: u32, _row: u32) {
+        match id {
+            CORNER_BUTTON => self.corner = (self.corner + 1) % CORNERS.len(),
+            LOWS_BUTTON => self.lows = !self.lows,
+            _ => return,
+        }
+        self.save();
+        self.page();
+        self.shown.clear();
+        self.draw();
+    }
+    fn ui_settings_opened(&mut self) {
+        self.page();
+    }
+}
+
+horizon_mod_sdk::export_mod!(Fps);
diff --git a/mods/official/keystrokes/Cargo.toml b/mods/official/keystrokes/Cargo.toml
new file mode 100644
index 000000000..36982a12f
--- /dev/null
+++ b/mods/official/keystrokes/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "keystrokes"
+version = "1.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "Horizon's official keystrokes overlay: movement keys, mouse buttons and clicks per second."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../../../crates/horizon-mod-sdk" }
+
+[lints]
+workspace = true
diff --git a/mods/official/keystrokes/horizon-mod.toml b/mods/official/keystrokes/horizon-mod.toml
new file mode 100644
index 000000000..ffda6cd3b
--- /dev/null
+++ b/mods/official/keystrokes/horizon-mod.toml
@@ -0,0 +1,9 @@
+id = "keystrokes"
+name = "Keystrokes"
+version = "1.0.0"
+description = "Your movement keys, mouse buttons and space bar in a corner, lit while held, with clicks per second. Horizon's own, formerly an extra."
+authors = ["Horizon"]
+api = "0.1"
+side = "client"
+capabilities = ["render", "input", "ui", "storage"]
+experimental = ["render", "input", "ui"]
diff --git a/mods/official/keystrokes/src/lib.rs b/mods/official/keystrokes/src/lib.rs
new file mode 100644
index 000000000..29866ffbf
--- /dev/null
+++ b/mods/official/keystrokes/src/lib.rs
@@ -0,0 +1,192 @@
+//! Horizon's official keystrokes overlay, formerly the built-in extra:
+//! forward, left, back and right as the player bound them, the two mouse
+//! buttons (with clicks per second) and the space bar, lit while held,
+//! drawn as the extra drew them. It redraws in the frame hook only when
+//! something changed. Settings (`corner`, `cps`) live in the mod's storage.
+use horizon_mod_sdk::{
+    Mod, Registration, input,
+    render::{self, Corner, FillShape, Rect, Shape, TextShape},
+    storage,
+    ui::{self, ButtonWidget, Widget},
+};
+
+const BACKGROUND: u32 = 0x7800_0000;
+/// A held key: light fill, dark text without a shadow.
+const HELD: u32 = 0xB0FF_FFFF;
+const INK_HELD: u32 = 0x14_1414;
+const INK: u32 = 0xFF_FFFF;
+const KEY: f32 = 22.0;
+const GAP: f32 = 2.0;
+const CORNERS: [(Corner, &str, &str); 4] = [
+    (Corner::TopLeft, "top_left", "Top left"),
+    (Corner::TopRight, "top_right", "Top right"),
+    (Corner::BottomLeft, "bottom_left", "Bottom left"),
+    (Corner::BottomRight, "bottom_right", "Bottom right"),
+];
+const CORNER_BUTTON: u32 = 1;
+const CPS_BUTTON: u32 = 2;
+const MOVES: [&str; 4] = ["key.forward", "key.left", "key.back", "key.right"];
+
+/// What the overlay shows; a change redraws it.
+#[derive(Clone, PartialEq, Default)]
+struct View {
+    moves: [(bool, String); 4],
+    jump: bool,
+    attack: bool,
+    use_: bool,
+    cps: Option<(u32, u32)>,
+}
+
+struct Keystrokes {
+    corner: usize,
+    cps: bool,
+    shown: Option<View>,
+}
+
+fn down(name: &str) -> (bool, String) {
+    input::mapping(name).map_or((false, String::new()), |m| (m.down, m.label))
+}
+
+/// The extra's key box: a fill and its lines centred, 9 pixels apart.
+fn key_box(out: &mut Vec<Shape>, [x, y, w, h]: [f32; 4], held: bool, lines: &[&str]) {
+    let (fill, ink) = if held {
+        (HELD, INK_HELD)
+    } else {
+        (BACKGROUND, INK)
+    };
+    out.push(Shape::Fill(FillShape {
+        rect: Rect { x, y, w, h },
+        color: fill,
+    }));
+    let total = lines.len() as f32 * 9.0 - 1.0;
+    for (i, line) in lines.iter().enumerate() {
+        let tw = render::text_width(line);
+        out.push(Shape::Text(TextShape {
+            text: (*line).into(),
+            at: render::Point {
+                x: (x + (w - tw) / 2.0).round(),
+                y: (y + (h - total) / 2.0).round() + i as f32 * 9.0,
+            },
+            color: ink,
+            centered: false,
+            shadow: !held,
+        }));
+    }
+}
+
+impl Keystrokes {
+    fn view(&self) -> View {
+        let (l, r) = input::clicks_per_second();
+        View {
+            moves: MOVES.map(down),
+            jump: down("key.jump").0,
+            attack: down("key.attack").0,
+            use_: down("key.use").0,
+            cps: self.cps.then_some((l, r)),
+        }
+    }
+    fn draw(&mut self) {
+        let v = self.view();
+        if self.shown.as_ref() == Some(&v) {
+            return;
+        }
+        let (w, h) = (3.0 * KEY + 2.0 * GAP, 3.0 * KEY + 3.0 * GAP + 10.0);
+        let step = KEY + GAP;
+        let mut out = Vec::with_capacity(24);
+        let [forward, left, back, right] = &v.moves;
+        key_box(&mut out, [step, 0.0, KEY, KEY], forward.0, &[&forward.1]);
+        for (i, key) in [left, back, right].into_iter().enumerate() {
+            key_box(
+                &mut out,
+                [i as f32 * step, step, KEY, KEY],
+                key.0,
+                &[&key.1],
+            );
+        }
+        let mw = (w - GAP) / 2.0;
+        let my = 2.0 * step;
+        for (i, (held, label, cps)) in [
+            (v.attack, "LMB", v.cps.map(|c| c.0)),
+            (v.use_, "RMB", v.cps.map(|c| c.1)),
+        ]
+        .into_iter()
+        .enumerate()
+        {
+            let rate = cps.map(|n| format!("{n} CPS"));
+            let lines: Vec<&str> = std::iter::once(label).chain(rate.as_deref()).collect();
+            key_box(&mut out, [i as f32 * (mw + GAP), my, mw, KEY], held, &lines);
+        }
+        // The space bar: a line in a short key.
+        let sy = my + step;
+        key_box(&mut out, [0.0, sy, w, 10.0], v.jump, &[]);
+        out.push(Shape::Fill(FillShape {
+            rect: Rect {
+                x: w / 2.0 - 12.0,
+                y: sy + 4.0,
+                w: 24.0,
+                h: 2.0,
+            },
+            color: 0xFF00_0000 | if v.jump { INK_HELD } else { INK },
+        }));
+        render::set_corner(CORNERS[self.corner].0, w, h, &out);
+        self.shown = Some(v);
+    }
+    /// The settings page: the screen's title is the mod's name already.
+    fn page(&self) {
+        let on = |b: bool| if b { "ON" } else { "OFF" };
+        ui::set_settings(&[
+            Widget::Button(ButtonWidget {
+                id: CORNER_BUTTON,
+                label: format!("Corner: {}", CORNERS[self.corner].2),
+            }),
+            Widget::Button(ButtonWidget {
+                id: CPS_BUTTON,
+                label: format!("Clicks per second: {}", on(self.cps)),
+            }),
+        ]);
+    }
+    fn save(&self) {
+        let _ = storage::set("corner", CORNERS[self.corner].1.as_bytes());
+        let _ = storage::set("cps", if self.cps { b"true" } else { b"false" });
+    }
+}
+
+fn stored(key: &str) -> Option<String> {
+    storage::get(key).and_then(|v| String::from_utf8(v).ok())
+}
+
+impl Mod for Keystrokes {
+    fn init() -> Result<(Self, Registration), String> {
+        // The extra's defaults: top left, with clicks per second.
+        let corner = stored("corner")
+            .and_then(|c| CORNERS.iter().position(|k| k.1 == c.trim()))
+            .unwrap_or(0);
+        let cps = stored("cps").is_none_or(|v| v.trim() != "false");
+        let k = Keystrokes {
+            corner,
+            cps,
+            shown: None,
+        };
+        k.page();
+        Ok((k, Registration::new().on_frame()))
+    }
+    fn frame(&mut self, _seconds: f32) {
+        self.draw();
+    }
+    fn ui_select(&mut self, id: u32, _row: u32) {
+        match id {
+            CORNER_BUTTON => self.corner = (self.corner + 1) % CORNERS.len(),
+            CPS_BUTTON => self.cps = !self.cps,
+            _ => return,
+        }
+        self.save();
+        self.page();
+        self.shown = None;
+        self.draw();
+    }
+    fn ui_settings_opened(&mut self) {
+        self.page();
+    }
+}
+
+horizon_mod_sdk::export_mod!(Keystrokes);

From f45e3f1237edbf3fc665ccec11a178f85757d5d7 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:11:23 +0000
Subject: [PATCH 220/270] Optimize launcher preparation with precompiled,
 batched exporters

Compile and validate original exporter bundles during release builds, cache development compilation, and reuse initialized JVMs and collision data during preparation. Keep legacy preparers compatible while current releases need only a Java runtime.

Co-Authored-By: Codex <noreply@openai.com>
---
 .github/workflows/release.yml                 |  36 ++-
 .gitignore                                    |   3 +
 README.md                                     |   2 +-
 crates/horizon-prepare/src/exporters.rs       | 218 ++++++++++++++++++
 crates/horizon-prepare/src/java.rs            |  45 ++--
 crates/horizon-prepare/src/lib.rs             |  85 ++++---
 crates/horizon-prepare/src/main.rs            |  10 +-
 crates/horizon-prepare/src/worker.rs          |  79 +++++++
 .../horizon-prepare/tests/java_selection.rs   |  16 +-
 docs/hosting.md                               |   2 +-
 docs/launcher-preparation.md                  |  53 +++++
 launcher/src/backend.rs                       |  30 ++-
 launcher/src/backend/java_tests.rs            |   2 +-
 launcher/src/mojang.rs                        |   4 +-
 .../dev/horizonlab/parity/PrepareWorker.java  |  69 ++++++
 .../parity/VanillaCollisionOracle.java        |  24 +-
 packaging/PLAY.txt                            |   2 +-
 tests/test_prepare_exporters.py               |  37 +++
 tools/check_prepare_exporters.py              | 145 ++++++++++++
 xtask/src/main.rs                             |  26 ++-
 20 files changed, 810 insertions(+), 78 deletions(-)
 create mode 100644 crates/horizon-prepare/src/exporters.rs
 create mode 100644 crates/horizon-prepare/src/worker.rs
 create mode 100644 docs/launcher-preparation.md
 create mode 100644 mods/horizon/src/test/java/dev/horizonlab/parity/PrepareWorker.java
 create mode 100644 tests/test_prepare_exporters.py
 create mode 100644 tools/check_prepare_exporters.py

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4cba851fa..4d20941d4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -77,9 +77,39 @@ jobs:
           # A dry run builds whatever the decision, to test the builds.
           if [[ "${{ steps.mode.outputs.dry_run }}" == true ]]; then echo "release=true" >> "$GITHUB_OUTPUT"; fi
 
-  build:
+  exporters:
     needs: decide
     if: needs.decide.outputs.release == 'true'
+    # This runner holds the maintainer's own pinned Minecraft jars. Only our classes leave it.
+    runs-on: ${{ vars.MAC_RUNNER || 'ludovics-mac-mini' }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.head }}
+          persist-credentials: false
+          clean: true
+      - uses: dtolnay/rust-toolchain@stable
+      - run: bash tools/ci/runner-env.sh
+      - run: bash tools/ci/vanilla-data.sh
+      - name: Compile and validate original exporters against the pinned jars
+        shell: bash
+        run: |
+          set -euo pipefail
+          bundle=$(target/release/horizon-prepare compile-exporters --root "$PWD" | tail -1)
+          mkdir -p exporters
+          cp -R "$bundle/server" "$bundle/client" "$bundle/manifest.json" exporters/
+          python3 tools/check_prepare_exporters.py --binary target/release/horizon-prepare
+      - uses: actions/upload-artifact@v4
+        with:
+          name: original-exporters
+          path: exporters/
+          if-no-files-found: error
+          retention-days: 3
+
+  build:
+    needs: [decide, exporters]
+    if: needs.decide.outputs.release == 'true'
     name: build ${{ matrix.name }}
     strategy:
       fail-fast: false
@@ -218,6 +248,10 @@ jobs:
           path: ${{ runner.temp }}/smoke-test.json
           if-no-files-found: error
           retention-days: 3
+      - uses: actions/download-artifact@v4
+        with:
+          name: original-exporters
+          path: exporters
       - name: Package
         run: |
           set -euo pipefail
diff --git a/.gitignore b/.gitignore
index 7fffd6a99..6bdae649a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,6 @@
 /.horizon-cache/
 /crash-reports/
 /debug/
+
+# Release-only compiled original exporter bundle.
+/exporters/
diff --git a/README.md b/README.md
index ceee29249..65078464e 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ Horizon is Minecraft: Java Edition 26.3 rewritten in Rust: a native game that re
 
 Horizon is installed through **the Horizon launcher**. Get it from [playhorizon.dev](https://playhorizon.dev) (the Download button picks your system) or from [the launcher releases](https://github.com/ludovic111/horizon/releases?q=launcher-v&expanded=true), for Linux x86-64, macOS on Apple Silicon or Windows x64. The launcher installs and updates the game, prepares its files from your own copy of Minecraft, and updates itself.
 
-**You need** Minecraft: Java Edition 26.3, played once (the official launcher, Prism, MultiMC and other launchers all work); a Java 25 JDK, for the one-time preparation; and a GPU with Vulkan on Linux and Windows, or any Apple Silicon Mac. Step by step, with macOS's first-open prompt and the first launch: [Install and first launch](https://playhorizon.dev/docs/install).
+**You need** Minecraft: Java Edition 26.3, played once (the official launcher, Prism, MultiMC and other launchers all work); a Java 25 runtime, for the one-time preparation; and a GPU with Vulkan on Linux and Windows, or any Apple Silicon Mac. Step by step, with macOS's first-open prompt and the first launch: [Install and first launch](https://playhorizon.dev/docs/install).
 
 <table>
   <tr>
diff --git a/crates/horizon-prepare/src/exporters.rs b/crates/horizon-prepare/src/exporters.rs
new file mode 100644
index 000000000..35992c8b5
--- /dev/null
+++ b/crates/horizon-prepare/src/exporters.rs
@@ -0,0 +1,218 @@
+//! Only original Horizon classes are packaged. The pinned jars remain player supplied.
+use crate::*;
+
+const SETTINGS: &str = "exporters-v1 --release -proc:none -encoding UTF-8";
+const SERVER: &[&str] = &[
+    "VanillaHeightmapOracle",
+    "VanillaBlockLandingOracle",
+    "VanillaEntityAttributeOracle",
+    "VanillaPlayerHealthOracle",
+    "VanillaDamageSourceOracle",
+    "VanillaCollisionOracle",
+    "VanillaFaceVisibilityOracle",
+    "VanillaGameplayFactsExporter",
+    "VanillaEntityTypesExporter",
+    "VanillaBlockBehaviourExporter",
+    "VanillaCommandParseOracle",
+    "VanillaCreativeTabsExporter",
+    "VanillaSimpleBlockOracle",
+    "VanillaStructureBlockExporter",
+    "PrepareWorker",
+];
+const CLIENT: &[&str] = &[
+    "VanillaBlockStateBindingOracle",
+    "VanillaEntityModelExporter",
+    "VanillaMobDataExporter",
+    "PrepareWorker",
+];
+
+fn files(dir: &Path) -> Result<Vec<PathBuf>, String> {
+    let mut result = Vec::new();
+    for entry in fs::read_dir(dir).map_err(|e| format!("{}: {e}", dir.display()))? {
+        let path = entry.map_err(|e| e.to_string())?.path();
+        if path.is_dir() {
+            result.extend(files(&path)?);
+        } else {
+            result.push(path);
+        }
+    }
+    result.sort();
+    Ok(result)
+}
+
+// research-lock pins both jars and every accepted client manifest (which pins its libraries).
+// artifacts::verify/client_libraries check those dependencies before any bundle is used.
+fn key(root: &Path) -> Result<String, String> {
+    let mut hash = sha2::Sha256::new();
+    hash.update(SETTINGS);
+    // The launcher's bundled preparer may differ from the selected game's. Hash that
+    // version's compiler settings so a newer release still selects a runtime correctly.
+    let compiler = fs::read_to_string(root.join("crates/horizon-prepare/src/exporters.rs"))
+        .unwrap_or_else(|_| include_str!("exporters.rs").into());
+    hash.update(compiler.replace('\r', ""));
+    let mut sources = files(&root.join(PARITY))?;
+    sources.retain(|p| p.extension().is_some_and(|e| e == "java"));
+    sources.push(root.join("research-lock.json"));
+    for path in sources {
+        let data: Vec<_> = read(&path)?.into_iter().filter(|b| *b != b'\r').collect();
+        hash.update(format!(
+            "{}\0{}\0",
+            relative_display(&path, root)?.replace('\\', "/"),
+            data.len()
+        ));
+        hash.update(data);
+    }
+    Ok(hex(&hash.finalize()))
+}
+
+fn outputs(dir: &Path) -> Result<Value, String> {
+    let mut hashes = Value::Object(Vec::new());
+    for path in files(dir)? {
+        if path.extension().is_some_and(|e| e == "class") {
+            let name = relative_display(&path, dir)?.replace('\\', "/");
+            // javac's sourcepath contains our sources only; enforce that at packaging too.
+            if !name.starts_with("server/dev/horizonlab/parity/")
+                && !name.starts_with("client/dev/horizonlab/parity/")
+            {
+                return Err(format!("Non-Horizon class in exporter bundle: {name}"));
+            }
+            hashes.insert(&name, Value::Str(digest(&path, "sha256")?));
+        }
+    }
+    Ok(hashes)
+}
+
+fn valid(dir: &Path, key: &str) -> bool {
+    let Ok(manifest) = read_json(&dir.join("manifest.json")) else {
+        return false;
+    };
+    manifest.get("key").and_then(Value::as_str) == Some(key)
+        && outputs(dir).is_ok_and(|hashes| {
+            !hashes.as_object().unwrap().is_empty() && manifest.get("classes") == Some(&hashes)
+        })
+}
+
+/// Whether the version ships a matching, intact bundle and needs only a Java runtime.
+pub fn available(root: &Path) -> bool {
+    key(root).is_ok_and(|key| valid(&root.join("exporters"), &key))
+}
+
+pub(crate) fn classes(run: &Run) -> Result<PathBuf, String> {
+    let key = key(&run.root)?;
+    let shipped = run.root.join("exporters");
+    if valid(&shipped, &key) {
+        return Ok(shipped);
+    }
+    let cached = run.local.join("exporters").join(&key);
+    if valid(&cached, &key) {
+        return Ok(cached);
+    }
+    // Build privately: an interrupted compiler or another preparer cannot publish partial classes.
+    let destination = cached;
+    let cached = run
+        .local
+        .join("exporters")
+        .join(format!(".{key}-{}", std::process::id()));
+    if cached.exists() {
+        fs::remove_dir_all(&cached).map_err(|e| e.to_string())?;
+    }
+    mkdir(&cached)?;
+    let jdk = java::find(run.java_major, &[run.jdk.home()])?;
+    for (side, mains, cp) in [
+        ("server", SERVER, &run.server_classpath),
+        ("client", CLIENT, &run.client_classpath),
+    ] {
+        (run.log)(&format!("Compiling {side} exporters (shared helpers once)"));
+        let classes = cached.join(side);
+        mkdir(&classes)?;
+        let log = run.log_file(&cached.join(format!("{side}.log")))?;
+        let mut args = vec![
+            "-encoding".into(),
+            "UTF-8".into(),
+            "-cp".into(),
+            cp.clone(),
+            "-sourcepath".into(),
+            arg(&run.root.join("mods/horizon/src/test/java")),
+            "-d".into(),
+            arg(&classes),
+        ];
+        args.extend(mains.iter().map(|n| arg(&run.oracle(&format!("{n}.java")))));
+        jdk.javac(run.java_major, &args, &log)?;
+        let validate = vec![
+            "-Xverify:all".into(),
+            "-cp".into(),
+            format!(
+                "{}{}{}",
+                classes.display(),
+                if cfg!(windows) { ";" } else { ":" },
+                cp
+            ),
+            "dev.horizonlab.parity.PrepareWorker".into(),
+            "validate".into(),
+            arg(&classes),
+        ];
+        // No exporter executes here: resolve every class and its signatures against pinned jars.
+        run.jdk.java(&validate, None, &log)?;
+    }
+    let manifest = Value::Object(vec![
+        ("key".into(), Value::Str(key.clone())),
+        ("classes".into(), outputs(&cached)?),
+    ]);
+    write_json(&cached.join("manifest.json"), &manifest)?;
+    if valid(&destination, &key) {
+        fs::remove_dir_all(&cached).map_err(|e| e.to_string())?;
+    } else {
+        if destination.exists() {
+            fs::remove_dir_all(&destination).map_err(|e| e.to_string())?;
+        }
+        fs::rename(&cached, &destination).map_err(|e| e.to_string())?;
+    }
+    Ok(destination)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bundles_invalidate_sources_pins_and_damaged_classes() {
+        let root = std::env::temp_dir().join(format!("prepare-bundle-{}", std::process::id()));
+        let source = root.join(PARITY).join("VanillaHeightmapOracle.java");
+        mkdir(source.parent().unwrap()).unwrap();
+        write(&source, b"original\n").unwrap();
+        let compiler = root.join("crates/horizon-prepare/src/exporters.rs");
+        mkdir(compiler.parent().unwrap()).unwrap();
+        write(&compiler, b"--release 25 -proc:none").unwrap();
+        write(&root.join("research-lock.json"), b"pins").unwrap();
+        let original = key(&root).unwrap();
+        write(&compiler, b"--release 26 -proc:none").unwrap();
+        assert_ne!(key(&root).unwrap(), original);
+        write(&compiler, b"--release 25 -proc:none").unwrap();
+        write(&source, b"original\r\n").unwrap();
+        assert_eq!(key(&root).unwrap(), original);
+        write(&source, b"changed").unwrap();
+        assert_ne!(key(&root).unwrap(), original);
+        write(&source, b"original\n").unwrap();
+        write(&root.join("research-lock.json"), b"new dependencies").unwrap();
+        assert_ne!(key(&root).unwrap(), original);
+        write(&root.join("research-lock.json"), b"pins").unwrap();
+        let bundle = root.join("exporters");
+        let class = bundle.join("server/dev/horizonlab/parity/Helper.class");
+        mkdir(class.parent().unwrap()).unwrap();
+        write(&class, b"compiled").unwrap();
+        write_json(
+            &bundle.join("manifest.json"),
+            &Value::Object(vec![
+                ("key".into(), Value::Str(original)),
+                ("classes".into(), outputs(&bundle).unwrap()),
+            ]),
+        )
+        .unwrap();
+        assert!(available(&root));
+        write(&class, b"damaged").unwrap();
+        assert!(!available(&root));
+        fs::remove_file(&class).unwrap();
+        assert!(!available(&root));
+        fs::remove_dir_all(root).unwrap();
+    }
+}
diff --git a/crates/horizon-prepare/src/java.rs b/crates/horizon-prepare/src/java.rs
index d46cb9428..6343d8433 100644
--- a/crates/horizon-prepare/src/java.rs
+++ b/crates/horizon-prepare/src/java.rs
@@ -1,4 +1,4 @@
-//! The JDK that compiles and runs the vanilla exporters. They call Mojang's own code, so they
+//! Java discovery and execution for the vanilla exporters. They call Mojang's own code, so they
 //! stay Java; everything around them is here.
 
 use std::ffi::OsStr;
@@ -15,7 +15,7 @@ pub struct Jdk {
 const TIMEOUT: Duration = Duration::from_secs(3600);
 
 /// Exporters and JDK probes write to pipes or log files: on Windows they open no terminal.
-fn command(program: impl AsRef<OsStr>) -> Command {
+pub(crate) fn command(program: impl AsRef<OsStr>) -> Command {
     let command = Command::new(program);
     #[cfg(windows)]
     let command = {
@@ -56,9 +56,9 @@ fn without_verbatim(path: PathBuf) -> PathBuf {
 
 /// Resolve compiler symlinks before picking its sibling runtime. The first `java` on the
 /// PATH may be an older, runtime-only install; it must not be paired with a newer `javac`.
-fn path_jdks(path: &OsStr) -> Vec<PathBuf> {
+fn path_homes(path: &OsStr, tool: &str) -> Vec<PathBuf> {
     std::env::split_paths(path)
-        .map(|dir| executable(&dir, "javac"))
+        .map(|dir| executable(&dir, tool))
         .filter(|javac| javac.is_file())
         .map(real_path)
         .filter_map(|javac| {
@@ -162,7 +162,7 @@ fn jdk_parents() -> Vec<PathBuf> {
 
 /// The JDKs (folders with `bin/javac`) one level below `parents`; a macOS bundle's home is
 /// its `Contents/Home`. Those named for `major` come first, then the others newest name first.
-fn installed_jdks(parents: &[PathBuf], major: i64) -> Vec<PathBuf> {
+fn installed_jdks(parents: &[PathBuf], major: i64, tool: &str) -> Vec<PathBuf> {
     let mut homes: Vec<PathBuf> = parents
         .iter()
         .filter_map(|parent| fs::read_dir(parent).ok())
@@ -176,7 +176,7 @@ fn installed_jdks(parents: &[PathBuf], major: i64) -> Vec<PathBuf> {
                 entry.path()
             }
         })
-        .filter(|home| executable(&home.join("bin"), "javac").is_file())
+        .filter(|home| executable(&home.join("bin"), tool).is_file())
         .collect();
     let named = |home: &Path| {
         home.iter().any(|part| {
@@ -191,8 +191,7 @@ fn installed_jdks(parents: &[PathBuf], major: i64) -> Vec<PathBuf> {
 }
 
 /// The Java runtimes the official launcher downloaded into `runtime` (a game directory's
-/// `runtime` folder: `<component>/<platform>/<component>/`, a macOS one in `jre.bundle`). Mojang's
-/// runtimes are whole JDKs, javac included, so a player who has run Minecraft has one already.
+/// `runtime` folder: `<component>/<platform>/<component>/`, a macOS one in `jre.bundle`).
 pub fn minecraft_runtimes(runtime: &Path) -> Vec<PathBuf> {
     let children = |dir: &Path| -> Vec<PathBuf> {
         let mut paths: Vec<PathBuf> = fs::read_dir(dir)
@@ -206,7 +205,7 @@ pub fn minecraft_runtimes(runtime: &Path) -> Vec<PathBuf> {
         for platform in children(&component) {
             let home = platform.join(component.file_name().unwrap_or_default());
             for home in [home.join("jre.bundle/Contents/Home"), home] {
-                if executable(&home.join("bin"), "javac").is_file() {
+                if executable(&home.join("bin"), "java").is_file() {
                     homes.push(home);
                     break;
                 }
@@ -221,8 +220,18 @@ pub fn minecraft_runtimes(runtime: &Path) -> Vec<PathBuf> {
 /// `/usr/libexec/java_home -v <major>` reports, else the homes in `more` (the launcher's pick,
 /// Minecraft's own runtimes), else the folders installers use (`jdk_parents`).
 pub fn find(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
+    find_tools(major, more, true)
+}
+
+/// Finds a compatible runtime; precompiled exporters do not need javac.
+pub fn find_runtime(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
+    find_tools(major, more, false)
+}
+
+fn find_tools(major: i64, more: &[PathBuf], compiler: bool) -> Result<Jdk, String> {
+    let tool = if compiler { "javac" } else { "java" };
     let need = format!(
-        "Java {major} is needed (a JDK with javac, e.g. Eclipse Temurin {major}). \
+        "Java {major} is needed ({tool}, e.g. Eclipse Temurin {major}). \
          Install it, or set JAVA_HOME to it, and try again."
     );
     let mut candidates = Vec::new();
@@ -235,7 +244,7 @@ pub fn find(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
         ));
     }
     if let Some(path) = std::env::var_os("PATH") {
-        for home in path_jdks(&path) {
+        for home in path_homes(&path, tool) {
             let bin = home.join("bin");
             candidates.push((executable(&bin, "javac"), executable(&bin, "java"), "PATH"));
         }
@@ -265,7 +274,7 @@ pub fn find(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
             "Minecraft's Java",
         ));
     }
-    for home in installed_jdks(&jdk_parents(), major) {
+    for home in installed_jdks(&jdk_parents(), major, tool) {
         let bin = home.join("bin");
         candidates.push((
             executable(&bin, "javac"),
@@ -275,15 +284,16 @@ pub fn find(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
     }
     let mut problems = Vec::new();
     for (javac, java, from) in candidates {
-        if !javac.is_file() || !java.is_file() {
+        if (compiler && !javac.is_file()) || !java.is_file() {
             problems.push(format!(
-                "{from} ({}) has no javac and java",
+                "{from} ({}) has no compatible Java tools",
                 javac.parent().unwrap().display()
             ));
             continue;
         }
         let checked = [(&javac, "javac"), (&java, "java")]
             .into_iter()
+            .filter(|(_, name)| compiler || *name == "java")
             .try_for_each(|(program, name)| {
                 let found = tool_major(program, name)?;
                 if i64::from(found) >= major {
@@ -298,7 +308,7 @@ pub fn find(major: i64, more: &[PathBuf]) -> Result<Jdk, String> {
         }
     }
     if problems.is_empty() {
-        Err(format!("{need} No javac was found."))
+        Err(format!("{need} No {tool} was found."))
     } else {
         Err(format!("{need} Found: {}.", problems.join("; ")))
     }
@@ -317,7 +327,7 @@ pub fn classpath<'a>(paths: impl IntoIterator<Item = &'a Path>) -> String {
 impl Jdk {
     /// The JDK's home, the folder above `bin` (what `JAVA_HOME` names).
     pub fn home(&self) -> PathBuf {
-        self.javac
+        self.java
             .parent()
             .and_then(Path::parent)
             .map(Path::to_path_buf)
@@ -424,6 +434,7 @@ mod tests {
                 dir.join("missing"),
             ],
             25,
+            "javac",
         );
         assert_eq!(
             found,
@@ -445,7 +456,7 @@ mod tests {
         let make = |home: PathBuf, javac: bool| {
             fs::create_dir_all(home.join("bin")).unwrap();
             if javac {
-                fs::write(executable(&home.join("bin"), "javac"), b"").unwrap();
+                fs::write(executable(&home.join("bin"), "java"), b"").unwrap();
             }
             home
         };
diff --git a/crates/horizon-prepare/src/lib.rs b/crates/horizon-prepare/src/lib.rs
index c7e443c7d..09787e476 100644
--- a/crates/horizon-prepare/src/lib.rs
+++ b/crates/horizon-prepare/src/lib.rs
@@ -11,11 +11,13 @@
 //! run, keyed by the sha256 of their inputs and outputs recorded in the manifest, as before.
 
 pub mod artifacts;
+pub mod exporters;
 mod inventory;
 pub mod java;
 pub mod pyjson;
 mod sounds;
 mod survival;
+mod worker;
 
 pub use sounds::{fonts, languages, packs, panorama, sounds, BUILT_IN_PACKS};
 
@@ -65,7 +67,7 @@ pub fn sources_sha256(crate_dir: &Path) -> Option<String> {
 
 pub struct Options {
     /// The version folder (a release folder, or a checkout): research-lock.json, the exporters'
-    /// Java sources, and `.local/` where everything is written.
+    /// Java sources, optional precompiled `exporters/`, and `.local/` where everything is written.
     pub root: PathBuf,
     /// Import the pinned game files from the player's own copy first (`--prepare`).
     pub import: bool,
@@ -74,7 +76,7 @@ pub struct Options {
     pub minecraft_dir: Option<PathBuf>,
     /// The pinned server jar the player downloaded (`--server-jar`, else HORIZON_SERVER_JAR).
     pub server_jar: Option<PathBuf>,
-    /// The JDK to try after JAVA_HOME and the PATH (the launcher's pick, e.g. Minecraft's
+    /// The Java runtime to try after JAVA_HOME and the PATH (the launcher's pick, e.g. Minecraft's
     /// own Java it downloaded from Mojang).
     pub java_home: Option<PathBuf>,
 }
@@ -293,6 +295,8 @@ struct Run<'a> {
     server_classpath: String,
     /// The client jar and its libraries: the classpath of the client-side exporters.
     client_classpath: String,
+    bundles: std::cell::OnceCell<PathBuf>,
+    workers: std::cell::RefCell<[Option<worker::Worker>; 2]>,
     previous: Value,
     origin: Value,
     log: Log<'a>,
@@ -301,6 +305,13 @@ struct Run<'a> {
 const PARITY: &str = "mods/horizon/src/test/java/dev/horizonlab/parity";
 
 impl Run<'_> {
+    fn bundle(&self) -> Result<&Path, String> {
+        if self.bundles.get().is_none() {
+            self.bundles.set(exporters::classes(self)?).unwrap();
+        }
+        Ok(self.bundles.get().unwrap())
+    }
+
     fn oracle(&self, name: &str) -> PathBuf {
         self.root.join(PARITY).join(name)
     }
@@ -333,33 +344,31 @@ impl Run<'_> {
         fs::File::create(path).map_err(|e| format!("{}: {e}", path.display()))
     }
 
-    /// `javac --release <major> -proc:none -cp <classpath> [extra] -d <classes> <sources>`.
-    fn compile(
-        &self,
-        classpath: &str,
-        extra: &[String],
-        classes: &Path,
-        sources: &[&Path],
-        log: &fs::File,
-    ) -> Result<(), String> {
-        let mut args = vec!["-cp".to_string(), classpath.to_string()];
-        args.extend_from_slice(extra);
-        args.push("-d".into());
-        args.push(classes.display().to_string());
-        args.extend(sources.iter().map(|s| s.display().to_string()));
-        self.jdk.javac(self.java_major, &args, log)
-    }
-
     /// `java -Xmx<heap> -cp <classes>:<classpath> dev.horizonlab.parity.<main> <args>`.
     fn run(
         &self,
         heap: &str,
-        classes: &Path,
         classpath: &str,
         main: &str,
         args: &[String],
         log: &fs::File,
+        log_path: &Path,
     ) -> Result<(), String> {
+        let side = usize::from(classpath == self.client_classpath);
+        let classes = self
+            .bundle()?
+            .join(if side == 1 { "client" } else { "server" });
+        if !matches!(
+            main,
+            "VanillaCommandParseOracle" | "VanillaCreativeTabsExporter"
+        ) && std::env::var_os("HORIZON_PREPARE_ISOLATED").is_none()
+        {
+            let mut workers = self.workers.borrow_mut();
+            if workers[side].is_none() {
+                workers[side] = Some(worker::Worker::new(self, &classes, classpath)?);
+            }
+            return workers[side].as_mut().unwrap().run(main, args, log_path);
+        }
         let separator = if cfg!(windows) { ";" } else { ":" };
         let mut all = vec![
             format!("-Xmx{heap}"),
@@ -371,7 +380,7 @@ impl Run<'_> {
         self.jdk.java(&all, None, log)
     }
 
-    /// Compiles `sources` into `classes` and runs each of `mains` with `args`, their output in
+    /// Runs each exporter from the verified shared bundle, with output in
     /// the log at `log`: the shape of every exporter step.
     #[allow(clippy::too_many_arguments)]
     fn export(
@@ -379,7 +388,7 @@ impl Run<'_> {
         what: &str,
         classpath: &str,
         classes: &Path,
-        sources: &[&Path],
+        _sources: &[&Path],
         mains: &[&str],
         heap: &str,
         args: &[String],
@@ -389,10 +398,8 @@ impl Run<'_> {
         mkdir(classes)?;
         let file = self.log_file(log)?;
         let fail = |e: String| format!("{e} while exporting {what}; see {}", log.display());
-        self.compile(classpath, &[], classes, sources, &file)
-            .map_err(fail)?;
         for main in mains {
-            self.run(heap, classes, classpath, main, args, &file)
+            self.run(heap, classpath, main, args, &file, log)
                 .map_err(fail)?;
         }
         Ok(())
@@ -401,6 +408,15 @@ impl Run<'_> {
 
 /// Prepares the resources; returns their folder (`.local/horizon-client/<version>`).
 pub fn prepare(options: &Options, log: Log) -> Result<PathBuf, String> {
+    prepare_impl(options, log, false)
+}
+
+/// Release build tool: compile and link-check only Horizon's original exporter classes.
+pub fn compile_exporters(options: &Options, log: Log) -> Result<PathBuf, String> {
+    prepare_impl(options, log, true)
+}
+
+fn prepare_impl(options: &Options, log: Log, compile_only: bool) -> Result<PathBuf, String> {
     let root = &std::path::absolute(&options.root)
         .map_err(|e| format!("{}: {e}", options.root.display()))?;
     let lock = artifacts::Lock::read(root)?;
@@ -409,7 +425,7 @@ pub fn prepare(options: &Options, log: Log) -> Result<PathBuf, String> {
     homes.extend(java::minecraft_runtimes(
         &artifacts::minecraft_dir(options.minecraft_dir.as_deref()).join("runtime"),
     ));
-    let jdk = java::find(lock.java_major, &homes)?;
+    let jdk = java::find_runtime(lock.java_major, &homes)?;
     if options.import && !artifacts::reuse_imported(root, log)? {
         artifacts::import(
             root,
@@ -456,10 +472,15 @@ pub fn prepare(options: &Options, log: Log) -> Result<PathBuf, String> {
         client: found.jars["client"].clone(),
         server_classpath: classpath_join(&found.jars["server"], &found.libraries),
         client_classpath: classpath_join(&found.jars["client"], &client_libraries),
+        bundles: std::cell::OnceCell::new(),
+        workers: std::cell::RefCell::new([None, None]),
         previous,
         origin,
         log,
     };
+    if compile_only {
+        return Ok(run.bundle()?.to_path_buf());
+    }
     steps(&run, &lock, &oracle, options.minecraft_dir.as_deref())?;
     log(&format!(
         "Prepared Horizon native-client resources: {}",
@@ -1117,7 +1138,6 @@ fn prepare_worldgen(run: &Run) -> Result<(), String> {
 /// whose blocks are checked for survival or support (trees, flowers, grass, kelp, ...).
 fn export_block_behavior(run: &Run, export: &Path) -> Result<(), String> {
     (run.log)("Exporting block behavior (VanillaSimpleBlockOracle)");
-    let tests = run.root.join("mods/horizon/src/test/java");
     let classes = export.join("classes");
     mkdir(&classes)?;
     let log_path = export.join("export.log");
@@ -1128,22 +1148,13 @@ fn export_block_behavior(run: &Run, export: &Path) -> Result<(), String> {
             log_path.display()
         )
     };
-    // The oracle's helper classes are compiled on demand from the source path.
-    run.compile(
-        &run.server_classpath,
-        &["-sourcepath".into(), arg(&tests)],
-        &classes,
-        &[&tests.join("dev/horizonlab/parity/VanillaSimpleBlockOracle.java")],
-        &log,
-    )
-    .map_err(fail)?;
     run.run(
         "1G",
-        &classes,
         &run.server_classpath,
         "VanillaSimpleBlockOracle",
         &["export".into(), arg(export)],
         &log,
+        &log_path,
     )
     .map_err(fail)?;
     let rules = survival::bind_definitions(
diff --git a/crates/horizon-prepare/src/main.rs b/crates/horizon-prepare/src/main.rs
index db64ca19d..10e153a04 100644
--- a/crates/horizon-prepare/src/main.rs
+++ b/crates/horizon-prepare/src/main.rs
@@ -16,6 +16,7 @@ const HELP: &str = "\
 horizon-prepare: prepare Horizon's resources from your own Minecraft Java Edition
 
 Usage: horizon-prepare [--prepare] [--server-jar PATH] [--minecraft-dir PATH] [--root PATH]
+       horizon-prepare compile-exporters [--root PATH]
        horizon-prepare sounds [--minecraft-dir PATH] [--root PATH]
        horizon-prepare panorama [--minecraft-dir PATH] [--root PATH]
        horizon-prepare fonts [--minecraft-dir PATH] [--root PATH]
@@ -30,8 +31,9 @@ Usage: horizon-prepare [--prepare] [--server-jar PATH] [--minecraft-dir PATH] [-
   --root PATH           The Horizon folder to prepare (default: the folder this program is
                         in, else the nearest folder above the current one with research-lock.json)
 
-Needs Minecraft played once from the official launcher, and Java (a JDK) of the version
-research-lock.json pins: JAVA_HOME, else javac and java on the PATH.
+Needs Minecraft played once from the official launcher, and Java of the version
+research-lock.json pins. Releases use a runtime; development or changed exporters need a JDK.
+compile-exporters builds and validates a release bundle from the already imported pinned jars.
 The resources go to <root>/.local/horizon-client/<version>; pass that to horizon-client --resources.
 
 horizon-prepare panorama repairs the classic menu background in existing resources without Java.
@@ -73,7 +75,7 @@ fn main() -> ExitCode {
     let assets = args.next_if(|a| {
         matches!(
             a.to_str(),
-            Some("sounds" | "panorama" | "fonts" | "packs" | "languages")
+            Some("sounds" | "panorama" | "fonts" | "packs" | "languages" | "compile-exporters")
         )
     });
     while let Some(arg) = args.next() {
@@ -132,6 +134,8 @@ fn main() -> ExitCode {
         let _ = out.flush();
     };
     let result = match assets.as_deref().and_then(|a| a.to_str()) {
+        Some("compile-exporters") => horizon_prepare::compile_exporters(&options, &log)
+            .inspect(|dir| log(&dir.display().to_string())),
         Some("sounds") => {
             horizon_prepare::sounds(&options.root, options.minecraft_dir.as_deref(), &log)
         }
diff --git a/crates/horizon-prepare/src/worker.rs b/crates/horizon-prepare/src/worker.rs
new file mode 100644
index 000000000..564b11746
--- /dev/null
+++ b/crates/horizon-prepare/src/worker.rs
@@ -0,0 +1,79 @@
+//! A bounded request/reply channel to one initialized exporter JVM.
+use crate::*;
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Child, ChildStdin, Stdio};
+use std::sync::mpsc::{self, Receiver};
+
+pub(crate) struct Worker {
+    child: Child,
+    input: ChildStdin,
+    replies: Receiver<std::io::Result<String>>,
+}
+
+impl Worker {
+    pub(crate) fn new(run: &Run, classes: &Path, cp: &str) -> Result<Self, String> {
+        let log = run.log_file(&run.local.join(format!(
+            "{}-worker.log",
+            classes.file_name().unwrap().to_string_lossy()
+        )))?;
+        let mut child = java::command(&run.jdk.java)
+            .args([
+                "-Xmx2G",
+                "-cp",
+                &format!(
+                    "{}{}{}",
+                    classes.display(),
+                    if cfg!(windows) { ";" } else { ":" },
+                    cp
+                ),
+                "dev.horizonlab.parity.PrepareWorker",
+            ])
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(log)
+            .spawn()
+            .map_err(|e| e.to_string())?;
+        let input = child.stdin.take().unwrap();
+        let output = child.stdout.take().unwrap();
+        let (send, replies) = mpsc::channel();
+        std::thread::spawn(move || {
+            for line in BufReader::new(output).lines() {
+                if send.send(line).is_err() {
+                    break;
+                }
+            }
+        });
+        Ok(Self {
+            child,
+            input,
+            replies,
+        })
+    }
+
+    pub(crate) fn run(&mut self, main: &str, args: &[String], log: &Path) -> Result<(), String> {
+        let task = Value::Array(vec![
+            Value::Str(arg(log)),
+            Value::Str(main.into()),
+            Value::Array(args.iter().cloned().map(Value::Str).collect()),
+        ]);
+        writeln!(self.input, "{}", pyjson::dumps(&task, &pyjson::COMPACT))
+            .map_err(|e| e.to_string())?;
+        self.input.flush().map_err(|e| e.to_string())?;
+        let reply = self
+            .replies
+            .recv_timeout(std::time::Duration::from_secs(3600))
+            .map_err(|e| format!("Exporter JVM stopped or timed out: {e}"))?
+            .map_err(|e| e.to_string())?;
+        match pyjson::loads(&reply)?.as_str() {
+            Some("") => Ok(()),
+            _ => Err(format!("Exporter {main} failed: {reply}")),
+        }
+    }
+}
+
+impl Drop for Worker {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
diff --git a/crates/horizon-prepare/tests/java_selection.rs b/crates/horizon-prepare/tests/java_selection.rs
index ba15304e6..4e8d60f55 100644
--- a/crates/horizon-prepare/tests/java_selection.rs
+++ b/crates/horizon-prepare/tests/java_selection.rs
@@ -25,13 +25,23 @@ fn selects_a_compatible_compiler_and_runtime() {
             assert!(error.contains(&format!("java {runtime} (")), "{error}");
             return;
         }
-        let jdk = java::find(25, &[]).unwrap();
-        let expected = root.join(if scenario == "target-release" {
+        let jdk = if scenario == "runtime-only" {
+            java::find_runtime(25, &[])
+        } else {
+            java::find(25, &[])
+        }
+        .unwrap();
+        let expected = root.join(if scenario == "runtime-only" {
+            "jre25"
+        } else if scenario == "target-release" {
             "newer"
         } else {
             "jdk25"
         });
         for (actual, name) in [(&jdk.javac, "javac"), (&jdk.java, "java")] {
+            if scenario == "runtime-only" && name == "javac" {
+                continue;
+            }
             assert_eq!(
                 fs::canonicalize(actual).unwrap(),
                 fs::canonicalize(tool(&expected.join("bin"), name)).unwrap()
@@ -64,6 +74,7 @@ fn selects_a_compatible_compiler_and_runtime() {
     );
     for (home, compiler, runtime) in [
         ("jre21", None, "21.0.1"),
+        ("jre25", None, "25.0.1"),
         ("jdk21", Some("21.0.1"), "21.0.1"),
         ("jdk25", Some("25.0.1"), "25.0.1"),
         ("mixed", Some("25.0.1"), "21.0.1"),
@@ -83,6 +94,7 @@ fn selects_a_compatible_compiler_and_runtime() {
     }
     fs::write(root.join("failing/bin/java.exit"), "7").unwrap();
     let scenarios = vec![
+        ("runtime-only", Some("jre25"), vec!["jre21", "jre25"]),
         ("older-runtime", None, vec!["jre21", "jdk25"]),
         ("older-jdk", None, vec!["jdk21", "jdk25"]),
         ("incompatible-home", Some("mixed"), vec!["jdk25"]),
diff --git a/docs/hosting.md b/docs/hosting.md
index bf431cada..778dcbaab 100644
--- a/docs/hosting.md
+++ b/docs/hosting.md
@@ -71,7 +71,7 @@ from there too.
 ## 2. Prepare the game files
 
 Horizon reads Minecraft's data from your own copy of the game. You need Minecraft Java Edition 26.3, played
-once from the official launcher on this computer, Java 25 (a JDK), and the 26.3 `server.jar`: it's the
+once from the official launcher on this computer, a Java 25 runtime, and the 26.3 `server.jar`: it's the
 `downloads.server.url` in your launcher's `versions/26.3/26.3.json`. Then:
 
 ```sh
diff --git a/docs/launcher-preparation.md b/docs/launcher-preparation.md
new file mode 100644
index 000000000..7df5b9131
--- /dev/null
+++ b/docs/launcher-preparation.md
@@ -0,0 +1,53 @@
+# Launcher resource preparation
+
+Release folders include `exporters/server`, `exporters/client` and an integrity manifest.
+These contain only Horizon's original Java exporter classes. Minecraft jars, libraries,
+assets and generated resources remain local and are verified against `research-lock.json`.
+The same platform-independent class bundle is used in game and dedicated-server releases.
+
+The release runner compiles the server and client source sets separately with
+`javac --release <pinned major> -proc:none -encoding UTF-8`, resolving shared helpers once
+per classpath. It checks every class and its signatures with `-Xverify:all` against the
+pinned jars. The release job also compares two fresh isolated preparations with a fresh
+batched preparation using a runtime-only Java home:
+
+```sh
+cargo build --release -p horizon-prepare
+# Requires already imported Minecraft files in .local/minecraft/<version>.
+target/release/horizon-prepare compile-exporters
+# Copy server/, client/ and manifest.json from the printed folder into exporters/.
+python3 tools/check_prepare_exporters.py --binary target/release/horizon-prepare
+```
+
+Development checkouts and changed sources compile on demand, into
+`.local/exporters/<sha256>`. The key covers Java sources (including implicit helpers),
+pinned dependency checksums and compiler settings. Class checksums detect missing or damaged
+outputs. Compilation happens in a private staging folder before publishing a complete cache
+entry. Sources and paths are normalized so one release bundle works on all three platforms.
+
+Compatible exporters run sequentially through one server JVM and one client JVM. Both keep
+Minecraft's initialized built-in registries. Every task restores the original registry tags
+before replying; failures stop preparation. Collision exports share the first generated
+registry and collision files, encoded block states and shape grids within the server worker.
+Ordinary parity oracle processes keep their existing behavior.
+
+Command-registry and creative-tab exporters remain separate processes: they install data
+components as well as tags. The data generator also remains separate. Inspection of pinned
+`net.minecraft.data.Main.main` showed that it calls `Util.shutdownExecutors` after running
+its providers. Calling it inside a worker would shut down shared executors; incorporating
+its providers directly needs a separate comparison of registry and executor lifetimes.
+Fresh release preparation therefore starts five exporter/data-generator JVMs, down from 18,
+and invokes no compiler. `HORIZON_PREPARE_ISOLATED=1` retains separate exporter JVMs for
+output comparisons and diagnosis.
+
+`tools/check_prepare_exporters.py` requires identical resource file sets and identical bytes
+for every file stable across the two isolated runs. For the three known noisy JSON files,
+it also requires semantic equality after normalizing object key order, opaque JVM lambda
+addresses and creative-tab tag set order. Other variation fails the release check.
+
+On Linux with Java 25, two comparisons produced 23,204 matching resource files each.
+The first isolated runs took 178.95 s and 104.25 s, versus 45.05 s batched; the second took
+100.03 s and 176.06 s, versus 120.09 s batched. All used precompiled exporters. These are fresh output directories with a warm OS file cache, on a
+machine with other workloads; the spread between isolated runs prevents treating this as a
+controlled speedup estimate. The compiler saving is separate: release preparation removes
+the previously measured 15 compiler invocations (29–52 s).
diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs
index 7e5c4babb..dfe264300 100644
--- a/launcher/src/backend.rs
+++ b/launcher/src/backend.rs
@@ -1096,17 +1096,23 @@ fn download_for_owner(
     }
 }
 
-/// The home of a JDK whose compiler and runtime support `major`. Forward even an installed
-/// JDK to external preparers: older versions may otherwise rediscover incompatible PATH tools.
+/// The Java home for this version: a runtime for precompiled exporters, a JDK for older
+/// preparers or changed sources. Forward the selection to external preparers too.
 /// Else try the official launcher's Java in `games`, then download the runtime named by
 /// `manifest` into Horizon's game folder (Mojang's runtimes are whole JDKs).
 fn java(
     major: i64,
+    compiler: bool,
     games: &[PathBuf],
     manifest: &Path,
     log: &dyn Fn(String),
 ) -> Result<PathBuf, String> {
-    if let Ok(jdk) = horizon_prepare::java::find(major, &[]) {
+    let find = if compiler {
+        horizon_prepare::java::find
+    } else {
+        horizon_prepare::java::find_runtime
+    };
+    if let Ok(jdk) = find(major, &[]) {
         return Ok(jdk.home());
     }
     let mut runtimes: Vec<PathBuf> = Vec::new();
@@ -1118,7 +1124,7 @@ fn java(
             runtimes.push(home);
         }
     }
-    let missing = match horizon_prepare::java::find(major, &runtimes) {
+    let missing = match find(major, &runtimes) {
         Ok(jdk) => return Ok(jdk.home()),
         Err(e) => e,
     };
@@ -1129,7 +1135,7 @@ fn java(
     // musl distributions) it cannot start, so don't download it.
     if cfg!(all(target_os = "linux", target_arch = "x86_64")) && !Path::new(GLIBC_LOADER).exists() {
         return Err(format!(
-            "{missing}\n  • Minecraft's own Java from Mojang needs glibc ({GLIBC_LOADER} is missing; on NixOS, enable programs.nix-ld), so install a JDK instead."
+            "{missing}\n  • Minecraft's own Java from Mojang needs glibc ({GLIBC_LOADER} is missing; on NixOS, enable programs.nix-ld), so install compatible Java instead."
         ));
     }
     let fetch = |url: &str| -> Result<Vec<u8>, String> {
@@ -1144,13 +1150,13 @@ fn java(
     let home = mojang::java_runtime(&component, &runtime, 8, &fetch, log).map_err(|e| {
         format!("{missing}\n  • Horizon also tried to download Minecraft's own Java from Mojang, but: {e}")
     })?;
-    horizon_prepare::java::find(major, &[home]).map(|jdk| jdk.home())
+    find(major, &[home]).map(|jdk| jdk.home())
 }
 
 /// The dynamic loader glibc programs on x86-64 Linux start through.
 const GLIBC_LOADER: &str = "/lib64/ld-linux-x86-64.so.2";
 
-/// Runs `cmd` with the JDK at `home`: JAVA_HOME names it and its `bin` leads the PATH, as the
+/// Runs `cmd` with Java at `home`: JAVA_HOME names it and its `bin` leads the PATH, as the
 /// versions' own preparers look for Java.
 fn with_java(cmd: &mut Command, home: &Path) {
     let mut path = vec![home.join("bin")];
@@ -1253,7 +1259,7 @@ pub fn preparer(
             "This version prepares with Python: Python 3.10 or newer is needed. Install it, or pick a newer version.",
         )?),
     };
-    // The JDK the version pins, found as horizon-prepare finds it, so a missing one is
+    // The Java the version pins, found as horizon-prepare finds it, so a missing one is
     // reported (or downloaded) before the server jar is downloaded. Versions from before
     // java_major ran Java 25.
     let major = read_json(&dir.join("research-lock.json"))
@@ -1267,7 +1273,13 @@ pub fn preparer(
             .into_iter()
             .map(|(_, dir)| dir),
     );
-    let java_home = java(major, &games, &manifest, log)?;
+    let java_home = java(
+        major,
+        !horizon_prepare::exporters::available(&dir),
+        &games,
+        &manifest,
+        log,
+    )?;
     let jar = data_dir()
         .join("server-jars")
         .join(format!("{version}.jar"));
diff --git a/launcher/src/backend/java_tests.rs b/launcher/src/backend/java_tests.rs
index 75914a1b0..3f46123b8 100644
--- a/launcher/src/backend/java_tests.rs
+++ b/launcher/src/backend/java_tests.rs
@@ -5,7 +5,7 @@ fn selected_jdk_reaches_external_preparers() {
     const CHILD: &str = "HORIZON_LAUNCHER_JAVA_TEST";
     if let Some(root) = std::env::var_os(CHILD) {
         let root = PathBuf::from(root);
-        let home = java(25, &[], &root.join("missing.json"), &|_| {}).unwrap();
+        let home = java(25, true, &[], &root.join("missing.json"), &|_| {}).unwrap();
         assert_eq!(
             fs::canonicalize(&home).unwrap(),
             fs::canonicalize(root.join("jdk25")).unwrap()
diff --git a/launcher/src/mojang.rs b/launcher/src/mojang.rs
index 27f9c3f0b..f242672b9 100644
--- a/launcher/src/mojang.rs
+++ b/launcher/src/mojang.rs
@@ -103,8 +103,8 @@ fn java_platform() -> Option<&'static str> {
 /// Downloads Mojang's Java runtime `component` (the version JSON's `javaVersion.component`, e.g.
 /// `java-runtime-epsilon`) into the game directory's `runtime` folder, as the official launcher
 /// lays it out: `<component>/<platform>/<component>/`. Each file is checked against its sha1;
-/// files already there and whole are kept. Mojang's runtimes are whole JDKs, javac included,
-/// which is what the exporters need.
+/// files already there and whole are kept. These also include javac for older release preparers;
+/// current releases can use an already installed runtime without it.
 pub fn java_runtime(
     component: &str,
     runtime: &Path,
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/PrepareWorker.java b/mods/horizon/src/test/java/dev/horizonlab/parity/PrepareWorker.java
new file mode 100644
index 000000000..26104bbe1
--- /dev/null
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/PrepareWorker.java
@@ -0,0 +1,69 @@
+package dev.horizonlab.parity;
+
+import com.google.gson.*;
+import java.io.*;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.*;
+import java.util.*;
+import net.minecraft.core.*;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.tags.*;
+
+/** Original launcher transport. Each worker owns one server OR client classpath. */
+public final class PrepareWorker {
+    private static <T> Runnable restoreTags(Registry<T> registry) {
+        var tags = new HashMap<TagKey<T>, List<Holder<T>>>();
+        registry.getTags().forEach(tag -> tags.put(tag.key(), tag.stream().toList()));
+        return () -> registry.prepareTagReload(new TagLoader.LoadResult<>(registry.key(), tags)).apply();
+    }
+
+    public static void main(String[] args) throws Exception {
+        if (args.length > 0 && args[0].equals("validate")) {
+            try (var paths = Files.walk(Path.of(args[1]))) {
+                for (var path : paths.filter(p -> p.toString().endsWith(".class")).toList()) {
+                    String name = Path.of(args[1]).relativize(path).toString()
+                        .replace(File.separatorChar, '.').replaceAll("\\.class$", "");
+                    var type = Class.forName(name, false, PrepareWorker.class.getClassLoader());
+                    type.getDeclaredMethods(); type.getDeclaredConstructors(); type.getDeclaredFields();
+                }
+            }
+            return;
+        }
+        // Bootstrap replaces System.out. Keep the protocol on the original descriptor.
+        var replies = new PrintWriter(new OutputStreamWriter(new FileOutputStream(FileDescriptor.out), StandardCharsets.UTF_8), true);
+        System.setOut(System.err);
+        net.minecraft.SharedConstants.tryDetectVersion();
+        net.minecraft.server.Bootstrap.bootStrap();
+        var resets = new ArrayList<Runnable>();
+        for (var registry : BuiltInRegistries.REGISTRY) resets.add(restoreTags(registry));
+        System.setProperty("horizon.prepare.reuse", "true");
+        try (var input = new BufferedReader(new InputStreamReader(System.in, StandardCharsets.UTF_8))) {
+            for (String line; (line = input.readLine()) != null;) {
+                var task = JsonParser.parseString(line).getAsJsonArray();
+                var previousOut = System.out; var previousErr = System.err;
+                String error = "";
+                try (var log = new PrintStream(Files.newOutputStream(Path.of(task.get(0).getAsString()),
+                        StandardOpenOption.CREATE, StandardOpenOption.APPEND), true, StandardCharsets.UTF_8)) {
+                    System.setOut(log); System.setErr(log);
+                    try {
+                        var values = task.get(2).getAsJsonArray();
+                        var argv = new String[values.size()];
+                        for (int i = 0; i < argv.length; i++) argv[i] = values.get(i).getAsString();
+                        Class.forName("dev.horizonlab.parity." + task.get(1).getAsString())
+                            .getMethod("main", String[].class).invoke(null, (Object) argv);
+                    } catch (Throwable failure) {
+                        failure.printStackTrace(log); error = failure.toString();
+                    } finally {
+                        for (var reset : resets) reset.run();
+                    }
+                } finally {
+                    System.setOut(previousOut); System.setErr(previousErr);
+                }
+                replies.println(new Gson().toJson(error));
+                if (!error.isEmpty()) System.exit(1);
+            }
+        }
+        // Vanilla may have started non-daemon executors. All task outputs are closed now.
+        System.exit(0);
+    }
+}
diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java
index 3466606cd..6ac41ff47 100644
--- a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java
+++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java
@@ -19,6 +19,14 @@ import net.minecraft.world.phys.shapes.*;
 /** Exports private runtime data locally and invokes actual vanilla cached-shape queries. */
 public final class VanillaCollisionOracle {
     static { SharedConstants.tryDetectVersion(); Bootstrap.bootStrap(); }
+    private static final boolean REUSE = Boolean.getBoolean("horizon.prepare.reuse");
+    private static Map<String,byte[]> generated;
+    private static final Map<BlockState,Tag> encodedStates = new IdentityHashMap<>();
+    private static final Map<VoxelShape,CompoundTag> encodedGrids = new IdentityHashMap<>();
+    private static Tag encode(BlockState state) {
+        if (!REUSE) return BlockState.FULL_CODEC.encodeStart(NbtOps.INSTANCE,state).getOrThrow();
+        return encodedStates.computeIfAbsent(state, s -> BlockState.FULL_CODEC.encodeStart(NbtOps.INSTANCE,s).getOrThrow()).copy();
+    }
     private static final Field CACHE, COLLISION, DISCRETE;
     private static final Method INDEX;
     static {
@@ -37,6 +45,7 @@ public final class VanillaCollisionOracle {
         return shape;
     }
     private static CompoundTag grid(VoxelShape shape) throws ReflectiveOperationException {
+        if (REUSE && encodedGrids.containsKey(shape)) return encodedGrids.get(shape).copy();
         CompoundTag tag = new CompoundTag();
         tag.putByte("canonical",(byte)(shape==Shapes.empty()?1:shape==Shapes.block()?2:0));
         tag.putByte("cube", (byte)(shape instanceof CubeVoxelShape ? 1 : 0));
@@ -52,13 +61,14 @@ public final class VanillaCollisionOracle {
         byte[] bits = new byte[discrete.getXSize() * discrete.getYSize() * discrete.getZSize()];
         for (int x = 0; x < discrete.getXSize(); x++) for (int y = 0; y < discrete.getYSize(); y++) for (int z = 0; z < discrete.getZSize(); z++) bits[(x * discrete.getYSize() + y) * discrete.getZSize() + z] = (byte)(discrete.isFull(x, y, z) ? 1 : 0);
         tag.putByteArray("occupied", bits);
+        if (REUSE) encodedGrids.put(shape, tag.copy());
         return tag;
     }
     public static CompoundTag occlusionDefinitions() throws Exception {
         var method=BlockBehaviour.class.getDeclaredMethod("getOcclusionShape",BlockState.class);method.setAccessible(true);
         var states=new ListTag();var shapes=new ListTag();var ids=new IdentityHashMap<VoxelShape,Integer>();int[] mapping=new int[Block.BLOCK_STATE_REGISTRY.size()];int index=0;
         for(var state:Block.BLOCK_STATE_REGISTRY) {
-            states.add(BlockState.FULL_CODEC.encodeStart(NbtOps.INSTANCE,state).getOrThrow());
+            states.add(encode(state));
             var shape=(VoxelShape)method.invoke(state.getBlock(),state);Integer id=ids.get(shape);
             if(id==null){id=shapes.size();ids.put(shape,id);shapes.add(grid(shape));}
             mapping[index++]=id;
@@ -70,12 +80,16 @@ public final class VanillaCollisionOracle {
     }
     private static void inputValues(PrintWriter out, double... values) { for (double value : values) out.printf(" %016x", Double.doubleToRawLongBits(value)); }
     private static void generate(Path base) throws Exception {
+        if (REUSE && generated != null) {
+            for (var file : generated.entrySet()) Files.write(base.resolve(file.getKey()), file.getValue());
+            return;
+        }
         ListTag states = new ListTag(), shapes = new ListTag(); CompoundTag defaults = new CompoundTag();
         Map<VoxelShape,Integer> ids = new IdentityHashMap<>();Set<CompoundTag> grids=new HashSet<>(); int[] mapping = new int[Block.BLOCK_STATE_REGISTRY.size()]; int cachedCount = 0;
         for (BlockState state : Block.BLOCK_STATE_REGISTRY) {
             int id = states.size();
             if (Block.BLOCK_STATE_REGISTRY.getId(state) != id) throw new AssertionError("non-dense states");
-            Tag encoded = BlockState.FULL_CODEC.encodeStart(NbtOps.INSTANCE, state).getOrThrow(); states.add(encoded);
+            Tag encoded = encode(state); states.add(encoded);
             if (state == state.getBlock().defaultBlockState()) defaults.putInt(((CompoundTag)encoded).getStringOr("id", ""), id);
             VoxelShape shape = cached(state);
             if (shape == null) mapping[id] = -1;
@@ -109,6 +123,12 @@ public final class VanillaCollisionOracle {
                 }
             }
         }
+        if (REUSE) {
+            // Consumers can overwrite block-registry.nbt; preserve the original bytes.
+            generated = new HashMap<>();
+            for (String file : List.of("block-registry.nbt", "cached-collision.nbt", "inputs.txt"))
+                generated.put(file, Files.readAllBytes(base.resolve(file)));
+        }
         System.out.printf("HORIZON_COLLISION_RESULT {\"registry_states\":%d,\"cached_states\":%d,\"uncached_states\":%d,\"unique_shapes\":%d,\"unique_grids\":%d,\"queries\":%d}%n", mapping.length,cachedCount,mapping.length-cachedCount,shapes.size(),grids.size(),cachedCount*6);
     }
     private static void values(PrintWriter out, String label, double... values) { out.print(label); for (double value : values) out.printf(" %016x",Double.doubleToLongBits(value)); out.println(); }
diff --git a/packaging/PLAY.txt b/packaging/PLAY.txt
index 20ea402fb..6d696b16c 100644
--- a/packaging/PLAY.txt
+++ b/packaging/PLAY.txt
@@ -17,7 +17,7 @@ Downloaded this archive directly?
   More about Horizon: https://playhorizon.dev
 
   To prepare this folder by hand you need Minecraft Java Edition 26.3, played
-  once from the official launcher, and Java 25 (a JDK). Then, in this folder:
+  once from the official launcher, and a Java 25 runtime. Then, in this folder:
     ./horizon-prepare --prepare --server-jar PATH/TO/server.jar
     ./horizon-prepare sounds               (optional, for sound)
   (Windows: horizon-prepare.exe.) The 26.3 server jar is the downloads.server.url
diff --git a/tests/test_prepare_exporters.py b/tests/test_prepare_exporters.py
new file mode 100644
index 000000000..56416100a
--- /dev/null
+++ b/tests/test_prepare_exporters.py
@@ -0,0 +1,37 @@
+"""The release comparison must tolerate only known variation and still catch regressions."""
+import contextlib
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+from tools.check_prepare_exporters import verify
+
+
+class PrepareExportersTests(unittest.TestCase):
+    def test_known_noise_does_not_mask_changed_resources(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            folders = [Path(temporary) / str(i) for i in range(3)]
+            for i, folder in enumerate(folders):
+                folder.mkdir()
+                (folder / 'stable.nbt').write_bytes(b'unchanged')
+                (folder / 'horizon-resources.json').write_text('{"schema":7}')
+                (folder / 'block-behaviours.json').write_text(json.dumps({
+                    'fields': {'shape': f'<Block$$Lambda/0x{i:08x}>', 'solid': True}}))
+                (folder / 'creative-inventory.json').write_text(json.dumps({
+                    'tabs': [{}, {'tags': [['a', 'b'] if i < 2 else ['b', 'a']], 'items': ['stone']}]}))
+            with contextlib.redirect_stdout(io.StringIO()):
+                verify(folders)
+                for name, changed in [
+                    ('stable.nbt', b'changed'),
+                    ('block-behaviours.json', b'{"fields":{"shape":"<Block$$Lambda/0x1234>","solid":false}}'),
+                    ('creative-inventory.json', b'{"tabs":[{},{"tags":[["a","b"]],"items":["dirt"]}]}'),
+                    ('horizon-resources.json', b'{"schema":8}'),
+                ]:
+                    path = folders[2] / name
+                    original = path.read_bytes()
+                    path.write_bytes(changed)
+                    with self.subTest(resource=name), self.assertRaises(SystemExit):
+                        verify(folders)
+                    path.write_bytes(original)
diff --git a/tools/check_prepare_exporters.py b/tools/check_prepare_exporters.py
new file mode 100644
index 000000000..6d37dfe93
--- /dev/null
+++ b/tools/check_prepare_exporters.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Compare two isolated preparations with a batched, runtime-only release preparation.
+
+Uses only locally imported pinned Minecraft files. Run after compile-exporters and copy its
+server/, client/ and manifest.json to exporters/. Byte differences are accepted only where
+both isolated runs also differ and normalize identically (known exporter noise).
+"""
+import argparse
+import hashlib
+import json
+import os
+import re
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def hashes(folder):
+    return {str(p.relative_to(folder)): hashlib.sha256(p.read_bytes()).hexdigest()
+            for p in folder.rglob('*') if p.is_file() and p.suffix != '.log'
+            and not {'classes', 'client-classes'} & set(p.relative_to(folder).parts)
+            and p.name != 'horizon-resources.json'}
+
+
+def normalize(path):
+    value = json.loads(path.read_text())
+    if path.name == 'block-behaviours.json':
+        # JVM-assigned lambda class addresses are printed as opaque field values.
+        def clean(node):
+            if isinstance(node, str):
+                return re.sub(r'\$\$Lambda/0x[0-9a-fA-F]+', '$$Lambda/<address>', node)
+            if isinstance(node, list):
+                return [clean(item) for item in node]
+            if isinstance(node, dict):
+                return {key: clean(item) for key, item in node.items()}
+            return node
+        value = clean(value)
+    elif path.name == 'creative-inventory.json':
+        for tab in value['tabs']:
+            if 'tags' in tab:
+                tab['tags'] = [sorted(tags) for tags in tab['tags']]
+    return value
+
+
+def verify(folders):
+    a, b, batched = [hashes(folder) for folder in folders]
+    if a.keys() != b.keys() or a.keys() != batched.keys():
+        raise SystemExit('Resource file sets differ')
+    known = {'render-definitions.json', 'block-behaviours.json', 'creative-inventory.json'}
+    noise = [name for name in a if a[name] != b[name] or a[name] != batched[name]]
+    differences = []
+    for name in noise:
+        if name not in known:
+            differences.append(name)
+        else:
+            x, y, z = [normalize(folder / name) for folder in folders]
+            if x != y or x != z:
+                differences.append(name)
+    manifests = []
+    for folder, raw in zip(folders, [a, b, batched]):
+        replacements = {raw[name]: f'normalized:{name}' for name in noise}
+        def clean(node):
+            if isinstance(node, str):
+                return replacements.get(node, node)
+            if isinstance(node, list):
+                return [clean(item) for item in node]
+            if isinstance(node, dict):
+                return {key: clean(item) for key, item in node.items()}
+            return node
+        manifests.append(clean(json.loads((folder / 'horizon-resources.json').read_text())))
+    if manifests[0] != manifests[1] or manifests[0] != manifests[2]:
+        differences.append('horizon-resources.json')
+    print(f'Normalized exporter noise: {noise}')
+    if differences:
+        raise SystemExit(f'Resources differ: {differences}')
+    print(f'PASS: all {len(a)} resource files match, with only known noise normalized')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--binary', type=Path, required=True)
+    parser.add_argument('--work', type=Path)
+    args = parser.parse_args()
+    binary = args.binary.resolve()
+    with tempfile.TemporaryDirectory(prefix='prepare-exporters-') as temporary:
+        work = args.work.resolve() if args.work else Path(temporary)
+        work.mkdir(parents=True, exist_ok=True)
+        # Freeze the tested executable even if a developer rebuilds concurrently.
+        frozen = work / binary.name
+        shutil.copy2(binary, frozen)
+        binary = frozen
+        results = []
+        times = []
+        for name in ['isolated-1', 'isolated-2', 'batched']:
+            folder = work / name
+            folder.mkdir()
+            shutil.copyfile(ROOT / 'research-lock.json', folder / 'research-lock.json')
+            shutil.copytree(ROOT / 'mods/horizon/src/test/java', folder / 'mods/horizon/src/test/java')
+            shutil.copytree(ROOT / 'exporters', folder / 'exporters')
+            (folder / '.local').mkdir()
+            (folder / '.local/minecraft').symlink_to((ROOT / '.local/minecraft').resolve(), target_is_directory=True)
+            env = dict(os.environ)
+            env.pop('HORIZON_PREPARE_ISOLATED', None)
+            if name.startswith('isolated'):
+                env['HORIZON_PREPARE_ISOLATED'] = '1'
+            else:
+                # An actual runtime-only home: no javac in bin. Java resolves its own libraries.
+                java = Path(shutil.which('java')).resolve()
+                runtime = folder / 'runtime'
+                (runtime / 'bin').mkdir(parents=True)
+                trace = folder / 'java-invocations.txt'
+                wrapper = runtime / 'bin' / java.name
+                wrapper.write_text('#!/bin/sh\nprintf "%s\\n" "$*" >> '
+                                   + shlex.quote(str(trace)) + '\nexec '
+                                   + shlex.quote(str(java)) + ' "$@"\n')
+                wrapper.chmod(0o755)
+                env['JAVA_HOME'] = str(runtime)
+                env['PATH'] = str(runtime / 'bin')
+            started = time.monotonic()
+            with (work / f'{name}.log').open('w') as log:
+                subprocess.run([str(binary), '--root', str(folder)], cwd=folder, env=env,
+                               stdout=log, stderr=subprocess.STDOUT, check=True, timeout=1200)
+            if name == 'batched':
+                launches = [line for line in trace.read_text().splitlines() if line != '-version']
+                if len(launches) != 5:
+                    raise SystemExit(f'Expected 5 exporter/data-generator JVMs, got {len(launches)}')
+                print(f'Runtime-only preparation: {len(launches)} JVM launches', flush=True)
+            text = (work / f'{name}.log').read_text()
+            if 'Compiling ' in text:
+                raise SystemExit(f'{name} unexpectedly needed a compiler')
+            resources = next((folder / '.local/horizon-client').iterdir())
+            results.append(resources)
+            times.append(round(time.monotonic() - started, 2))
+            print(f'{name}: {times[-1]}s, prepared', flush=True)
+        verify(results)
+        print(f'Isolated {times[:2]}s, batched {times[2]}s')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 28b591626..2682b1f82 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -222,16 +222,40 @@ fn package(binary: &Path, out: &Path) -> Result<(), String> {
     let repo = new_folder(out)?;
     copy_into(binary, out)?;
     copy_beside(binary, &TOOLS, out)?;
+    copy_exporters(&repo.join("exporters"), &out.join("exporters"))?;
     let play = repo.join("packaging/PLAY.txt");
     copy(&play, &out.join("PLAY.txt"))
 }
 
 fn package_server(engine: &Path, out: &Path) -> Result<(), String> {
-    new_folder(out)?;
+    let repo = new_folder(out)?;
+    copy_exporters(&repo.join("exporters"), &out.join("exporters"))?;
     copy(engine, &out.join(program_name(engine, "horizon-engine")))?;
     copy_beside(engine, &SERVER_TOOLS, out)
 }
 
+/// Release builds supply only our compiled classes and their integrity manifest.
+fn copy_exporters(from: &Path, to: &Path) -> Result<(), String> {
+    if !from.join("manifest.json").is_file() {
+        return Err("Missing exporters/manifest.json; run horizon-prepare compile-exporters and copy its bundle to exporters/".into());
+    }
+    copy_exporter_tree(from, to)
+}
+
+fn copy_exporter_tree(from: &Path, to: &Path) -> Result<(), String> {
+    fs::create_dir_all(to).map_err(|e| e.to_string())?;
+    for entry in fs::read_dir(from).map_err(|e| e.to_string())? {
+        let path = entry.map_err(|e| e.to_string())?.path();
+        let target = to.join(path.file_name().unwrap());
+        if path.is_dir() {
+            copy_exporter_tree(&path, &target)?;
+        } else {
+            copy(&path, &target)?;
+        }
+    }
+    Ok(())
+}
+
 /// `OUT`, emptied, with the sources the release folders take (`ARCHIVED`); the repository's path.
 fn new_folder(out: &Path) -> Result<PathBuf, String> {
     let top = git(

From 5e9d45bc9afe0bf91feb22e49a5232cb00f38287 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:11:39 +0100
Subject: [PATCH 221/270] /pregen: off unless the server turns it on

Vanilla has no /pregen, so with it always registered /help and the command
tree differed from vanilla's (the command_exec harness failed on /help).
Horizon's own commands are now added to the game's tree only when the owner
asks: `horizon-pregen=true` in server.properties (`horizon-pregen = true`
under [properties] in server.toml) for a dedicated server, `--pregen` for
the game (single player, LAN). Off, the trees are vanilla's own, unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/command/tests.rs   | 18 ++++++++
 crates/horizon-client/src/command/vanilla.rs | 45 ++++++++++++++------
 crates/horizon-client/src/game.rs            |  4 +-
 crates/horizon-client/src/game/dedicated.rs  |  8 ++++
 docs/hosting.md                              |  5 ++-
 docs/pregeneration.md                        |  6 +++
 6 files changed, 70 insertions(+), 16 deletions(-)

diff --git a/crates/horizon-client/src/command/tests.rs b/crates/horizon-client/src/command/tests.rs
index 2bdea1aba..d61fd8ae1 100644
--- a/crates/horizon-client/src/command/tests.rs
+++ b/crates/horizon-client/src/command/tests.rs
@@ -592,3 +592,21 @@ fn mod_commands_join_the_tree_for_every_player() {
     // The game's own tree is left as it was.
     assert!(vanilla::game_dispatcher().find("where").is_none());
 }
+
+#[test]
+fn horizon_commands_are_off_unless_the_server_turns_them_on() {
+    // By default the game runs vanilla's tree: /help lists no /pregen.
+    assert!(vanilla::game_dispatcher().find("pregen").is_none());
+    for dev in [false, true] {
+        let vanilla_tree = vanilla::game_tree(dev, false);
+        assert!(vanilla_tree.find("pregen").is_none());
+        let d = vanilla::game_tree(dev, true);
+        let parse = d.parse("pregen start 100 circle", &reg());
+        assert_eq!(parse.executable().unwrap().1, "pregen.start");
+        // Vanilla's commands are the same with or without it.
+        assert_eq!(
+            d.nodes[0].children.len(),
+            vanilla_tree.nodes[0].children.len() + 1
+        );
+    }
+}
diff --git a/crates/horizon-client/src/command/vanilla.rs b/crates/horizon-client/src/command/vanilla.rs
index cba5a5d5b..2ce892077 100644
--- a/crates/horizon-client/src/command/vanilla.rs
+++ b/crates/horizon-client/src/command/vanilla.rs
@@ -538,20 +538,39 @@ fn apply_vanilla_order(d: &mut Dispatcher) {
 }
 /// The tree the game runs: a release integrated server's, or with
 /// `HORIZON_DEV_COMMANDS` set the development one
-/// (SharedConstants.DEBUG_DEV_COMMANDS), plus Horizon's own commands.
+/// (SharedConstants.DEBUG_DEV_COMMANDS), plus Horizon's own commands when
+/// the server turned them on (`set_horizon_commands`).
 pub fn game_dispatcher() -> &'static Dispatcher {
-    static DEV: std::sync::OnceLock<Dispatcher> = std::sync::OnceLock::new();
-    static RELEASE: std::sync::OnceLock<Dispatcher> = std::sync::OnceLock::new();
-    let (tree, dev) = if std::env::var_os("HORIZON_DEV_COMMANDS").is_some() {
-        (&DEV, true)
-    } else {
-        (&RELEASE, false)
-    };
-    tree.get_or_init(|| {
-        let mut d = build_with(dev);
-        horizon_commands(&mut d, 0);
-        d
-    })
+    game_tree(
+        std::env::var_os("HORIZON_DEV_COMMANDS").is_some(),
+        HORIZON_COMMANDS.load(std::sync::atomic::Ordering::Relaxed),
+    )
+}
+/// Whether this process's server has Horizon's own commands (`/pregen`). Off
+/// by default, so `/help` and the command tree are vanilla's; a dedicated
+/// server turns them on with `horizon-pregen=true` in server.properties, the
+/// game with `--pregen` (docs/pregeneration.md).
+static HORIZON_COMMANDS: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
+/// Turns Horizon's own commands on or off for the trees `game_dispatcher`
+/// returns from now on.
+pub fn set_horizon_commands(on: bool) {
+    HORIZON_COMMANDS.store(on, std::sync::atomic::Ordering::Relaxed);
+}
+/// The server.properties key that turns `/pregen` on (Horizon's own; vanilla
+/// ignores keys it doesn't know).
+pub const PREGEN_PROPERTY: &str = "horizon-pregen";
+pub(crate) fn game_tree(dev: bool, horizon: bool) -> &'static Dispatcher {
+    static HORIZON: [std::sync::OnceLock<Dispatcher>; 2] =
+        [const { std::sync::OnceLock::new() }; 2];
+    match (dev, horizon) {
+        (true, false) => dispatcher(),
+        (false, false) => release_dispatcher(),
+        (dev, true) => HORIZON[usize::from(dev)].get_or_init(|| {
+            let mut d = build_with(dev);
+            horizon_commands(&mut d, 0);
+            d
+        }),
+    }
 }
 /// Commands vanilla doesn't have, after its own: `/pregen`
 /// (docs/pregeneration.md).
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index fa00e3804..08e1ff68b 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -360,7 +360,7 @@ impl Options {
             match arg.as_str() {
                 "--help" | "-h" => {
                     println!(
-                        "Horizon — Minecraft Java Edition {} in Rust\n\n  --resources PATH        Prepared resources (horizon-prepare)\n  --render-distance N     Chunks, 2..64 (default 12)\n  --world NAME            World folder under saves/ (default \"New World\")\n  --seed N                World seed for new worlds (default 0)\n  --width N, --height N   Window size (default 1280 x 720)\n  --creative              Creative mode (default survival)\n  --test-terrain          Simple test terrain instead of vanilla generation\n  --frames N              Exit after N frames (testing)\n  --world-frames N        Exit after N frames drawn in the world (testing)\n  --smoke-report PATH     Write a JSON report on exit\n  --benchmark SCENARIO    Run a benchmark (standard, village, forest, ocean, mountain), write its report to benchmarks/ and quit\n  --control               Accept horizon-ctl commands on a local socket\n  --control-socket PATH   Control socket path (default $XDG_RUNTIME_DIR/horizon-control.sock)\n  --server HOST[:PORT]    Join a multiplayer server (offline mode) at start\n  --name NAME             Player name for multiplayer (default: generated once, kept in horizon-player.txt)\n  --session-file PATH     Signed-in account from the launcher (read once, then deleted)\n  --dev-mod PATH          A Horizon mod (.hmod or folder) to develop: always on, reloaded when rebuilt\n  --in-frame              Run single player's world in the frame, not on its server thread\n\nControls: mouse look, WASD move, Space jump, Left Shift sneak, Left Ctrl sprint,\nleft click break, right click place/use, 1-9/scroll hotbar, E inventory,\nQ drop, F3 debug, Esc pause.",
+                        "Horizon — Minecraft Java Edition {} in Rust\n\n  --resources PATH        Prepared resources (horizon-prepare)\n  --render-distance N     Chunks, 2..64 (default 12)\n  --world NAME            World folder under saves/ (default \"New World\")\n  --seed N                World seed for new worlds (default 0)\n  --width N, --height N   Window size (default 1280 x 720)\n  --creative              Creative mode (default survival)\n  --test-terrain          Simple test terrain instead of vanilla generation\n  --frames N              Exit after N frames (testing)\n  --world-frames N        Exit after N frames drawn in the world (testing)\n  --smoke-report PATH     Write a JSON report on exit\n  --benchmark SCENARIO    Run a benchmark (standard, village, forest, ocean, mountain), write its report to benchmarks/ and quit\n  --control               Accept horizon-ctl commands on a local socket\n  --control-socket PATH   Control socket path (default $XDG_RUNTIME_DIR/horizon-control.sock)\n  --server HOST[:PORT]    Join a multiplayer server (offline mode) at start\n  --name NAME             Player name for multiplayer (default: generated once, kept in horizon-player.txt)\n  --session-file PATH     Signed-in account from the launcher (read once, then deleted)\n  --dev-mod PATH          A Horizon mod (.hmod or folder) to develop: always on, reloaded when rebuilt\n  --in-frame              Run single player's world in the frame, not on its server thread\n  --pregen                Add Horizon's /pregen command (docs/pregeneration.md)\n\nControls: mouse look, WASD move, Space jump, Left Shift sneak, Left Ctrl sprint,\nleft click break, right click place/use, 1-9/scroll hotbar, E inventory,\nQ drop, F3 debug, Esc pause.",
                         horizon_core::VANILLA_VERSION
                     );
                     return Ok(None);
@@ -377,6 +377,8 @@ impl Options {
                 "--control" => o.control = Some(horizon_client::control::default_path()),
                 "--server-thread" => o.server_thread = true,
                 "--in-frame" | "--no-server-thread" => o.server_thread = false,
+                // Horizon's own commands (/pregen), off by default as on vanilla.
+                "--pregen" => horizon_client::command::vanilla::set_horizon_commands(true),
                 _ => {
                     let value = args
                         .next()
diff --git a/crates/horizon-client/src/game/dedicated.rs b/crates/horizon-client/src/game/dedicated.rs
index edea0e800..fa5365195 100644
--- a/crates/horizon-client/src/game/dedicated.rs
+++ b/crates/horizon-client/src/game/dedicated.rs
@@ -155,6 +155,14 @@ pub(super) fn preflight(options: &mut Options) -> Result<bool> {
     for w in &props.warnings {
         log("WARN", w);
     }
+    // Horizon's own commands are the owner's choice, off as on vanilla.
+    if props
+        .raw
+        .get(horizon_client::command::vanilla::PREGEN_PROPERTY)
+        .is_some_and(|v| v.trim().eq_ignore_ascii_case("true"))
+    {
+        horizon_client::command::vanilla::set_horizon_commands(true);
+    }
     props.store(&settings)?;
     let eula_file = PathBuf::from("eula.txt");
     let agreed = match eula::agreed(&eula_file) {
diff --git a/docs/hosting.md b/docs/hosting.md
index 4c4c954bc..a9624dc2c 100644
--- a/docs/hosting.md
+++ b/docs/hosting.md
@@ -218,8 +218,9 @@ horizon-server rollback                  back to the release before
 While the server runs, `op`, `whitelist` and `cmd` go to the game's console, so they act exactly as vanilla's
 console commands do. While it's stopped, they edit vanilla's files directly. Any console command works through
 `cmd`: `horizon-server cmd ban Griefer`, `horizon-server cmd say Restarting in 5 minutes`.
-To generate the world around spawn ahead of the players, Horizon has its own `pregen` command:
-`horizon-server cmd pregen start 2500` ([pregeneration](pregeneration.md)).
+To generate the world around spawn ahead of the players, Horizon has its own `pregen` command, off until
+`server.toml` has `horizon-pregen = true` under `[properties]`: `horizon-server cmd pregen start 2500`
+([pregeneration](pregeneration.md)).
 
 `config set` changes `server.toml` without opening it: `horizon-server config set world.difficulty=hard
 server.max_players=10`. Each key is a section and a name from the file (`properties.spawn-protection=0` for any
diff --git a/docs/pregeneration.md b/docs/pregeneration.md
index a8ca228b3..706527661 100644
--- a/docs/pregeneration.md
+++ b/docs/pregeneration.md
@@ -5,6 +5,12 @@ Chunky does on a Java server. It is Horizon's own command (vanilla has none), av
 with cheats on and to operators (level 2) on a server, from the chat or the server console
 (`horizon-server cmd pregen start 2500`).
 
+It is off until you turn it on, so `/help` and the command tree stay vanilla's:
+
+- a server: `horizon-pregen = true` under `[properties]` in `server.toml` (or `horizon-pregen=true` in a
+  vanilla folder's `server.properties`), then restart it;
+- single player and LAN: start the game with `--pregen`.
+
 ```text
 /pregen start <radius> [square|circle] [<x> <z>]   radius in blocks; the centre defaults to where you
                                                    stand (the world spawn from the console)

From 03190ec724589fdaa639501640397b75447880ec Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:13:02 +0000
Subject: [PATCH 222/270] Update the runtime download fixture for runtime-only
 discovery

Co-Authored-By: Codex <noreply@openai.com>
---
 launcher/src/mojang_tests.rs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/launcher/src/mojang_tests.rs b/launcher/src/mojang_tests.rs
index 24ed80bca..cd32e4c79 100644
--- a/launcher/src/mojang_tests.rs
+++ b/launcher/src/mojang_tests.rs
@@ -247,9 +247,12 @@ fn links_stay_inside_the_runtime() {
 #[test]
 fn java_runtime_lays_out_mojangs_runtime_with_its_executables_and_links() {
     const JAVAC: &[u8] = b"#!/bin/sh\necho javac 25.0.1\n";
+    const JAVA: &[u8] = b"#!/bin/sh\necho java 25.0.1\n";
     const LICENSE: &[u8] = b"a fake license";
     let manifest = serde_json::json!({"files": {
         "bin": {"type": "directory"},
+        "bin/java": {"type": "file", "executable": true, "downloads": {"raw":
+            {"sha1": sha1_hex(JAVA), "size": JAVA.len(), "url": "https://piston-data.mojang.com/java"}}},
         "bin/javac": {"type": "file", "executable": true, "downloads": {"raw":
             {"sha1": sha1_hex(JAVAC), "size": JAVAC.len(), "url": "https://piston-data.mojang.com/javac"}}},
         "legal/java.base/LICENSE": {"type": "file", "executable": false, "downloads": {"raw":
@@ -269,6 +272,7 @@ fn java_runtime_lays_out_mojangs_runtime_with_its_executables_and_links() {
                 "https://piston-meta.mojang.com/m.json".into(),
                 manifest.into_bytes(),
             ),
+            ("https://piston-data.mojang.com/java".into(), JAVA.to_vec()),
             (
                 "https://piston-data.mojang.com/javac".into(),
                 JAVAC.to_vec(),

From 21d8e530346f3e05c0256e2c085bceb0103f823d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:14:51 +0100
Subject: [PATCH 223/270] parity: pick harnesses by the Rust items their probes
 reach, not whole crates

`--changed` / `--changed-files` now narrow each harness's recorded Rust
sources to those its probes can reach (tools/parity_reach.py): an item-level
reachability walk from the probe modules a harness ran (or the binary it
built) over free items, inherent methods, trait impls and macros, matched by
name so it only over-approximates. Parent modules count through their `mod`
declarations, compared with the merge base. A harness whose probe can't be
placed keeps every source; `--by-crate` turns the narrowing off.

On the last 20 PRs merged on 2026-10-25: 2255 -> 1061 harnesses picked,
2384 -> 1592 harness-minutes. Replaying the week's 61 failed CI parity runs,
every failed harness the old selection picked is still picked; LLVM coverage of
six harnesses' probes executes only kept files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/parity-workflow.md    |   4 +
 tests/test_parity_reach.py | 111 ++++++
 tools/parity.py            |  49 ++-
 tools/parity_reach.py      | 768 +++++++++++++++++++++++++++++++++++++
 4 files changed, 925 insertions(+), 7 deletions(-)
 create mode 100644 tests/test_parity_reach.py
 create mode 100644 tools/parity_reach.py

diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index f9f222071..d794b9c71 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -49,6 +49,10 @@ A harness can declare, at the top level of its script:
 - `PARITY_SHARDS = N`: it runs as `NAME#1` to `NAME#N`, in parallel, each told its share in `PARITY_SHARD=i/N` (`test_datafix_parity.py` upgrades every sixth world). `NAME` on the command line or in `--known-failures` means all of them.
 - `PARITY_RUST_SCOPE = [...]`: the Rust sources its probes can reach, as path prefixes. Cargo's dep-info names every file of every crate a probe links, so without it a probe of `horizon-world` depends on all 350 of its files. The runner keeps only the scope's files if the scope is closed: nothing in it names a module, crate-root re-export or macro outside it (`crate::`, `super::`, other workspace crates; comments and strings ignored), declares a module it doesn't cover, or includes source, and nothing outside it implements anything for a type it defines. Crate roots then count without their declarations of other modules, so adding a module elsewhere doesn't rerun the harness. If the scope isn't closed the runner says why and keeps every file. `datafix` depends on 41 files this way, not 354.
 
+### Which harnesses a change affects
+
+`--changed` and `--changed-files` narrow each harness's Rust sources to those its probes can reach (`tools/parity_reach.py`), so a change to one module of `horizon-client` no longer reruns every harness whose probe links the crate. The narrowing works on items, not files: from the probe modules a harness ran (or the binary it built), a free item (fn, type, const, static) is reached when a reached item names it in its own module, through a path or an import of a module that is named, or through a glob import; an inherent impl's methods count one by one once their type is reached and their name is mentioned; a trait impl counts once its trait and its type are reached (std's traits and types always are); a macro counts once invoked. Names match by spelling, so the result only over-approximates. A reached file's parent modules count through their `mod` declarations of it, compared with the merge base; Rust files a change adds take part, a dependency that was deleted counts as changed, code under `#[cfg(test)]` never counts, and a harness whose probe can't be found keeps every source. Parses are cached by content in `.local/parity-runner/reach-cache.json`. `--by-crate` turns the narrowing off. On the last 20 pull requests merged on 2026-10-25, the harnesses picked went from 2255 to 1061 (2384 to 1592 harness-minutes; game-binary harnesses, which link all of `game/`, set the floor), and every harness a CI parity run failed in the week before was still picked; every source file a sample of probes executed (LLVM `-C instrument-coverage`) is among those kept. Building the graph takes 15 s cold, under a second warm, and up to a minute and a half on a change that reaches many harnesses.
+
 ## The gate
 
 `tools/gate.py` is what a branch must pass before it is integrated: the public-tree check, rustfmt, clippy with warnings denied, the Rust and Python tests, then the harnesses whose inputs changed. It stops at the first failure and writes `.local/gate.json`. `--known-failures a,b` lets harnesses that already fail on the integration branch keep failing. `--quick` checks formatting, lints and Python tests only; `--no-parity` skips the harnesses.
diff --git a/tests/test_parity_reach.py b/tests/test_parity_reach.py
new file mode 100644
index 000000000..9b7464b47
--- /dev/null
+++ b/tests/test_parity_reach.py
@@ -0,0 +1,111 @@
+"""tools/parity_reach.py: which workspace sources a harness's probe can reach."""
+from pathlib import Path
+import tempfile
+import textwrap
+import unittest
+
+from tools import parity, parity_reach
+
+PROBE = [["example", "world_probe", "release", ["-p", "a"], True]]
+
+
+def workspace(root, files):
+    for path, text in files.items():
+        (root / path).parent.mkdir(parents=True, exist_ok=True)
+        (root / path).write_text(textwrap.dedent(text), encoding="utf-8")
+
+
+class ReachTests(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.root = Path(self.directory.name)
+        workspace(self.root, {
+            "crates/a/Cargo.toml": '[package]\nname = "a"\n\n[[example]]\nname = "world_probe"\npath = "examples/probe/main.rs"\n',
+            "crates/a/src/lib.rs": """
+                pub mod used;
+                pub mod unused;
+                mod methods;
+                mod display;
+                mod table;
+                #[cfg(test)]
+                mod tests;
+            """,
+            "crates/a/src/used.rs": """
+                pub struct Thing;
+                pub fn helper() -> u32 { 1 }
+            """,
+            # Same names as used.rs, but nothing names this module.
+            "crates/a/src/unused.rs": "pub struct Thing;\npub fn helper() -> u32 { 2 }\n",
+            "crates/a/src/methods.rs": """
+                use crate::used::Thing;
+                impl Thing {
+                    pub fn method(&self) -> u32 { 3 }
+                    pub fn never_called(&self) -> u32 { 4 }
+                }
+            """,
+            "crates/a/src/display.rs": """
+                impl std::fmt::Display for crate::used::Thing {
+                    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { write!(f, "thing") }
+                }
+            """,
+            "crates/a/src/table.rs": """
+                macro_rules! table { () => { pub struct Table; }; }
+                table!();
+            """,
+            "crates/a/src/tests.rs": "use crate::used::Thing;\nimpl Thing { pub fn method_in_tests(&self) {} }\n",
+            "crates/a/examples/probe/main.rs": "mod dispatch;\nmod p;\n",
+            "crates/a/examples/probe/dispatch.rs": "pub fn args() {}\n",
+            "crates/a/examples/probe/p.rs": """
+                use a::used::{helper, Thing};
+                pub fn main() { println!("{} {} {}", helper(), Thing.method(), Thing); }
+            """,
+        })
+        self.dependencies = sorted(str(path.relative_to(self.root)) for path in self.root.rglob("*") if path.is_file())
+        self.dependencies.remove("crates/a/examples/probe/main.rs")  # parity.only_probes_run leaves it out
+
+    def tearDown(self):
+        self.directory.cleanup()
+
+    def narrowed(self, changed=(), artifacts=PROBE):
+        graph = parity_reach.SourceGraph(self.root, parity.rust_code)
+        return parity_reach.narrow(self.dependencies, artifacts, graph, set(changed))
+
+    def test_keeps_what_the_probe_reaches(self):
+        kept = {path for path, (whole, _) in self.narrowed().items() if whole}
+        self.assertIn("crates/a/src/used.rs", kept)
+        self.assertIn("crates/a/src/methods.rs", kept)  # Thing.method()
+        self.assertIn("crates/a/src/display.rs", kept)  # std's Display for a reached type
+        self.assertIn("crates/a/Cargo.toml", kept)
+        self.assertNotIn("crates/a/src/unused.rs", kept)  # its names match, but nothing names its module
+        self.assertNotIn("crates/a/src/table.rs", kept)
+        self.assertNotIn("crates/a/src/tests.rs", kept)  # compiled into tests only
+
+    def test_module_parents_count_through_their_declarations(self):
+        self.assertEqual(self.narrowed()["crates/a/src/lib.rs"], (False, {"used", "methods", "display"}))
+        text = (self.root / "crates/a/src/lib.rs").read_text()
+        self.assertEqual(parity_reach.declarations(text, {"used"}, False), "pub mod used;")
+        self.assertEqual(parity_reach.declarations(text, {"tests"}, False), "#[cfg(test)]\nmod tests;")
+        # Adding or dropping a module beside the reached ones changes neither view.
+        other = text.replace("mod table;", "mod table2;\nmod more;")
+        self.assertEqual(parity_reach.declarations(other, {"used"}, False), "pub mod used;")
+        self.assertEqual(parity_reach.declarations(other, {"used"}, True), parity_reach.declarations(text, {"used"}, True))
+        self.assertNotEqual(parity_reach.declarations(text + "pub fn f() {}\n", {"used"}, True),
+                            parity_reach.declarations(text, {"used"}, True))
+
+    def test_a_new_file_counts_once_it_is_reached(self):
+        (self.root / "crates/a/src/lib.rs").write_text("pub mod used;\nmod extra;\n")
+        workspace(self.root, {"crates/a/src/extra.rs": "impl crate::used::Thing { pub fn method(&self) -> u32 { 5 } }\n"})
+        self.assertIn("crates/a/src/extra.rs", self.narrowed(changed={"crates/a/src/extra.rs"}))
+
+    def test_a_deleted_dependency_counts(self):
+        (self.root / "crates/a/src/unused.rs").unlink()
+        self.assertIn("crates/a/src/unused.rs", self.narrowed())
+
+    def test_unknown_probes_keep_everything(self):
+        self.assertEqual(set(self.narrowed(artifacts=[])), set(self.dependencies))
+        self.assertEqual(set(self.narrowed(artifacts=[["example", "missing", "release", ["-p", "a"], True]])),
+                         set(self.dependencies))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/parity.py b/tools/parity.py
index 503a5f3bf..dc5fdb1c9 100644
--- a/tools/parity.py
+++ b/tools/parity.py
@@ -45,6 +45,11 @@ import subprocess
 import sys
 import time
 
+try:
+    from . import parity_reach
+except ImportError:
+    import parity_reach
+
 ROOT = Path(__file__).resolve().parents[1]
 LOCAL = ROOT / ".local"
 STATE_DIR = LOCAL / "parity-runner"
@@ -1224,20 +1229,44 @@ def changed_harnesses(found, records, ref):
     return found_changed
 
 
-def affected_harnesses(found, records, changed):
+def affected_harnesses(found, records, changed, reach=True, base=None):
     """Harnesses the changed files can affect: their script or a recorded dependency (here, or in the shared
-    dependency lists) changed, a file every harness depends on changed, or nothing is recorded about them yet."""
+    dependency lists) changed, a file every harness depends on changed, or nothing is recorded about them yet.
+    With reach, a harness's workspace Rust sources count only if its probes can reach them (tools/parity_reach.py);
+    a harness whose probes can't be placed keeps them all. A changed file counts unless, compared with base (a
+    commit), only declarations of modules the harness doesn't reach changed (tools/parity_reach.py)."""
     if changed & SHARED_INPUTS:
         return set(found)
+    graph = None
+    if reach and any(path.startswith("crates/") for path in changed):
+        cache_path = STATE_DIR / "reach-cache.json"
+        try:
+            cache = json.loads(cache_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            cache = {}
+        graph = parity_reach.SourceGraph(ROOT, rust_code, cache)
     affected = set()
     for name, script in found.items():
-        dependencies = records.get(name, {}).get("dependencies")
+        record = records.get(name) or {}
+        dependencies = record.get("dependencies")
         template = SHARED / "dependencies" / f"{name}.json"
         if dependencies is None and template.exists():
-            dependencies = json.loads(template.read_text(encoding="utf-8")).get("dependencies")
-        if dependencies is None or Path(script).relative_to(ROOT).as_posix() in changed or \
-                any(path.split(KEEP)[0] in changed for path in dependencies):
+            record = json.loads(template.read_text(encoding="utf-8"))
+            dependencies = record.get("dependencies")
+        if dependencies is None or Path(script).relative_to(ROOT).as_posix() in changed:
             affected.add(name)
+            continue
+        plain = {path.split(KEEP)[0] for path in dependencies}
+        if graph is not None and plain & changed:
+            narrowed = parity_reach.narrow(dependencies, recorded_artifacts(record), graph, changed)
+            if any(path.split(KEEP)[0] in changed and (children is None or parity_reach.declarations_changed(
+                    ROOT, path.split(KEEP)[0], children, base, whole)) for path, (whole, children) in narrowed.items()):
+                affected.add(name)
+        elif plain & changed:
+            affected.add(name)
+    if graph is not None:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(json.dumps(graph.saved_cache()), encoding="utf-8")
     return affected
 
 
@@ -1280,6 +1309,8 @@ def main():
     parser.add_argument("--flake-rounds", type=int, default=3, help="runs required by --flake-check (default 3)")
     parser.add_argument("--changed", metavar="REF", help="only harnesses the changes since the merge base with REF can "
                         "affect (and that have not passed with their current inputs): the pull-request check")
+    parser.add_argument("--by-crate", action="store_true", help="with --changed: count every Rust source a probe "
+                        "links, not only those it can reach (tools/parity_reach.py)")
     parser.add_argument("--changed-files", metavar="FILE", help="like --changed, for the changed paths listed in FILE, "
                         "one per line: for a copy without Git history (tools/pr_ready.py on another machine)")
     args = parser.parse_args()
@@ -1316,7 +1347,11 @@ def main():
             changed, since = changed_files(args.changed), f" since the merge base with {args.changed}"
         if changed is None:
             parser.error(f"no merge base with {args.changed}")
-        affected = affected_harnesses(found, records, changed)
+        base = None
+        if args.changed:
+            merge_base = subprocess.run(["git", "merge-base", "HEAD", args.changed], cwd=ROOT, capture_output=True, text=True)
+            base = merge_base.stdout.strip() or None
+        affected = affected_harnesses(found, records, changed, reach=not args.by_crate, base=base)
         chosen = [name for name in found if name in affected and stale(name, state, hasher, environment)]
         print(f"{len(changed)} files changed{since}: {len(affected)} harnesses "
               f"depend on them, {len(chosen)} without a pass for their current inputs.", flush=True)
diff --git a/tools/parity_reach.py b/tools/parity_reach.py
new file mode 100644
index 000000000..0c3051b86
--- /dev/null
+++ b/tools/parity_reach.py
@@ -0,0 +1,768 @@
+"""Which of a harness's Rust sources its probes can reach, for `parity.py --changed`.
+
+Cargo's dep-info names every source file of every crate a probe links, so a change anywhere in horizon-client
+selected every harness whose probe links horizon-client. This module narrows a harness's recorded dependencies to
+the files holding an item its entry points (the probe modules it ran, the binaries it built) can reach, over a graph
+of the workspace's current sources whose nodes are items:
+
+- everything in an entry is reached, and so is everything in a Rust file the module tree doesn't place (an
+  `include!`d source);
+- a module is open when it is a crate root, holds reached code, or is named in a path (`name::`, `use ...name`) by
+  reached code while its parent is open;
+- a free item (fn, struct, enum, union, trait, type, const, static, an item-level macro call's items) is reached when
+  reached code in its own module or below it mentions its name, or when its module is open and reached code names
+  it in a path or an import, or when its module is glob-imported (`use m::*`) and its name is mentioned;
+- an inherent impl's methods and constants are reached one by one, by name, once their type is; a trait impl once
+  its trait and its type are (a std or outside name always is, a generic parameter needs nothing); a macro once
+  invoked; a `pub use` like a free item named by everything it imports;
+- "a crate's reached code" covers the crates it names (`horizon_world::`), directly or through one that does, and
+  code under `#[cfg(test)]` or `#[test]` is left out (probes are never test builds).
+
+Names match by spelling, so a file can be kept for a name it never meant: the graph only over-approximates. A
+reached file's parent modules count through their `mod` declarations of it (parity.py compares those with the merge
+base). Everything that isn't a workspace Rust source stays a dependency, except a crate's non-Rust files (shaders,
+assets, fonts) that only unreached sources name; a dependency that no longer exists counts as changed, and Rust files
+a change adds take part.
+"""
+
+import hashlib
+from pathlib import Path, PurePosixPath
+import re
+import subprocess
+
+IDENT = r"[A-Za-z_]\w*"
+WORD = re.compile(rf"\b({IDENT})\b")
+MOD_DECLARATION = re.compile(rf"\bmod\s+({IDENT})\s*;")
+INLINE_MOD = re.compile(rf"\bmod\s+({IDENT})\s*\{{")
+PATH_ATTRIBUTE = re.compile(r'#\[\s*path\s*=\s*"([^"]+)"\s*\]\s*(?:#\[[^\]]*\]\s*)*(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*;$')
+BRACE = re.compile(r"[{}]")
+TEST_ONLY = re.compile(r"#\[\s*(?:cfg\s*\(\s*test\s*\)|test)\s*\]")
+TEST_MODULE = re.compile(r"#\[\s*cfg\s*\(\s*test\s*\)\s*\]\s*(?:#\[[^\]]*\]\s*)*(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*;$")
+SPLIT = re.compile(r"[{}()\[\];]")
+ITEM = re.compile(rf"(?:pub(?:\s*\([^)]*\))?\s+)?(?:(?:unsafe|async|const|extern|default|auto)\s+)*"
+                  rf"(fn|struct|enum|union|trait|type|const|static|impl|mod|use|macro_rules\s*!|extern\s+crate)"
+                  rf"(?!\w)\s*(?:mut\s+)?({IDENT})?")
+PATH_BEFORE = re.compile(rf"\b({IDENT})\s*::")
+PATH_AFTER = re.compile(rf"::\s*({IDENT})")
+MACRO_USE = re.compile(rf"\b({IDENT})\s*!\s*[(\[{{]")
+MACRO_CALL = re.compile(rf"({IDENT}(?:\s*::\s*{IDENT})*)\s*!")
+DEFINED_INSIDE = re.compile(rf"\b(?:fn|struct|enum|union|trait|type|const|static)\s+({IDENT})")
+NESTED_IMPL = re.compile(r"^[ \t]*(?:unsafe\s+)?impl\b([^{;]*)\{", re.MULTILINE)
+QUALIFIED = re.compile(rf"{IDENT}(?:\s*::\s*{IDENT})*")
+GLOB_IMPORT = re.compile(r"\buse\s[^;]*::\s*\*")
+# File names a source may name in a literal (include_str!, include_bytes!, a path it reads). A file of another kind
+# is never "named", so it always counts.
+FILE_NAME = re.compile(r"[\w-]+\.(?:wgsl|glsl|json|png|ttf|otf|svg|txt|toml|ogg|wav|nbt|bin|dat|csv|mcmeta|wit|wasm)\b")
+TYPE_KINDS = {"struct", "enum", "union", "trait", "type", "macro_call"}
+# Names an impl header can take from outside the workspace: std's prelude and primitive types, and the std and serde
+# traits a glob import may bring. A glob-imported name outside this list is taken to be the workspace's.
+STD_NAMES = {"Display", "Error", "Read", "Write", "Seek", "BufRead", "Deref", "DerefMut", "Index", "IndexMut", "Add",
+             "Sub", "Mul", "Div", "Rem", "Neg", "Not", "BitAnd", "BitOr", "BitXor", "Shl", "Shr", "AddAssign",
+             "SubAssign", "MulAssign", "DivAssign", "RemAssign", "BitAndAssign", "BitOrAssign", "BitXorAssign",
+             "Borrow", "BorrowMut", "Future", "Any", "FromStr", "Hasher", "BuildHasher", "Formatter", "Ordering",
+             "Serialize", "Deserialize", "Serializer", "Deserializer", "Visitor", "Termination", "Sum", "Product",
+             "Wake", "Cow", "Rc", "Arc", "Mutex", "RwLock", "Cell", "RefCell", "HashMap", "HashSet", "BTreeMap",
+             "BTreeSet", "VecDeque"}
+PRELUDE = {"Option", "Some", "None", "Result", "Ok", "Err", "Vec", "String", "Box", "ToString", "ToOwned", "Clone",
+           "Copy", "Send", "Sync", "Sized", "Unpin", "Drop", "Fn", "FnMut", "FnOnce", "From", "Into", "TryFrom",
+           "TryInto", "AsRef", "AsMut", "Default", "Eq", "PartialEq", "Ord", "PartialOrd", "Iterator", "Extend",
+           "IntoIterator", "DoubleEndedIterator", "ExactSizeIterator", "FromIterator", "Debug", "Hash",
+           "bool", "char", "str", "u8", "u16", "u32", "u64", "u128", "usize", "i8", "i16", "i32", "i64", "i128",
+           "isize", "f32", "f64"}
+STD_NAMES |= PRELUDE
+KEYWORDS = {"crate", "self", "super", "Self", "pub", "in", "as", "use", "for", "where", "dyn", "mut", "const", "fn",
+            "unsafe", "impl", "std", "core", "alloc", "let", "if", "else", "match", "return", "struct", "enum", "mod",
+            "type", "static", "trait", "true", "false", "loop", "while", "move", "ref", "break", "continue", "async",
+            "await", "extern", "union"}
+
+
+def segments(code, start, end):
+    """The item-level pieces of code[start:end]: each ends at a `;` or a `}` outside any bracket."""
+    found, begin, depth = [], start, 0
+    for match in SPLIT.finditer(code, start, end):
+        character = match.group()
+        if character in "{([":
+            depth += 1
+        elif character in "})]":
+            depth -= 1
+            if character == "}" and depth == 0:
+                found.append((begin, match.end()))
+                begin = match.end()
+        elif depth == 0:
+            found.append((begin, match.end()))
+            begin = match.end()
+    if code[begin:end].strip():
+        found.append((begin, end))
+    return found
+
+
+def skip_attributes(code, index, end):
+    """The offset of the first non-space character after the attributes (`#[...]`, `#![...]`) starting at index."""
+    while True:
+        while index < end and code[index].isspace():
+            index += 1
+        if not code.startswith("#", index) or not re.match(r"#!?\[", code[index:index + 3]):
+            return index
+        depth = 0
+        for position in range(code.index("[", index), end):
+            depth += {"[": 1, "]": -1}.get(code[position], 0)
+            if depth == 0:
+                index = position + 1
+                break
+        else:
+            return end
+
+
+def body_of(code, start, end):
+    """The range inside an item's outermost `{ }` block, or None."""
+    opening = code.find("{", start, end)
+    closing = code.rfind("}", start, end)
+    return (opening + 1, closing) if 0 <= opening < closing else None
+
+
+def words(text):
+    return set(WORD.findall(text)) - KEYWORDS
+
+
+def qualified_words(text):
+    """Names a piece of code reaches through a path (`a::b`: b), the way items of other modules are named."""
+    return set(PATH_AFTER.findall(text)) - KEYWORDS
+
+
+def path_words(text):
+    """Names a piece of code uses as path segments (`a::`, `::b`), where module names appear."""
+    return set(PATH_BEFORE.findall(text)) | set(PATH_AFTER.findall(text))
+
+
+def parse_items(code, start, end, items):
+    """Append the items of code[start:end] (a file or an inline module's body) to items, as dicts."""
+    for begin, finish in segments(code, start, end):
+        head = skip_attributes(code, begin, finish)
+        text = code[head:finish]
+        if not text.strip(" \n\t;") or TEST_ONLY.search(code[begin:head]):
+            continue  # compiled into tests only, never into a probe
+        match = ITEM.match(text)
+        kind = re.sub(r"\s+", "", match.group(1)) if match else None
+        name = match.group(2) if match else None
+        if kind == "mod":
+            body = body_of(code, head, finish)
+            if body:
+                parse_items(code, body[0], body[1], items)
+            continue
+        if kind in ("externcrate", None) and not MACRO_CALL.match(text):
+            if kind is None:
+                items.append({"kind": "glue", "mentions": sorted(words(text)), "paths": sorted(path_words(text)), "qualified": sorted(qualified_words(text)), "invokes": sorted(set(MACRO_USE.findall(text)))})
+            continue
+        if kind is None:  # an item-level macro call: it may define items
+            items.append({"kind": "macro_call", "names": sorted(set(DEFINED_INSIDE.findall(text))),
+                          "macro": MACRO_CALL.match(text).group(1).split("::")[-1].strip(),
+                          "mentions": sorted(words(text)), "paths": sorted(path_words(text)), "qualified": sorted(qualified_words(text)), "invokes": sorted(set(MACRO_USE.findall(text)))})
+        elif kind == "use":
+            head_word = re.match(rf"\s*(?:::\s*)?({IDENT})", text[match.end(1):])
+            items.append({"kind": "use", "public": text.startswith("pub"), "names": sorted(words(text)),
+                          "head": head_word.group(1) if head_word else "", "glob": bool(re.search(r"::\s*\*", text)),
+                          "mentions": sorted(words(text)), "paths": sorted(words(text)), "qualified": sorted(words(text)),
+                          "invokes": []})
+        elif kind == "impl":
+            body = body_of(code, head, finish)
+            subject = code[head + match.end(1) - match.start(): body[0] - 1 if body else finish]
+            inherent = not re.search(r"\bfor\b", impl_subject(subject)[1])
+            if inherent and body:
+                members = []
+                for member_begin, member_end in segments(code, body[0], body[1]):
+                    member = code[skip_attributes(code, member_begin, member_end):member_end]
+                    found = ITEM.match(member)
+                    members.append({"name": found.group(2) if found else None, "mentions": sorted(words(member)),
+                                    "paths": sorted(path_words(member)), "qualified": sorted(qualified_words(member)), "invokes": sorted(set(MACRO_USE.findall(member)))})
+                items.append({"kind": "impl", "subject": subject, "inherent": True, "members": members,
+                              "mentions": sorted(words(subject)), "paths": sorted(path_words(subject)), "qualified": sorted(qualified_words(subject)), "invokes": sorted(set(MACRO_USE.findall(subject)))})
+            else:
+                items.append({"kind": "impl", "subject": subject, "inherent": False, "mentions": sorted(words(text)),
+                              "paths": sorted(path_words(text)), "qualified": sorted(qualified_words(text)), "invokes": sorted(set(MACRO_USE.findall(text)))})
+        else:
+            kind = "macro" if kind.startswith("macro_rules") else kind
+            items.append({"kind": kind, "names": [name] if name else [], "mentions": sorted(words(text)),
+                          "defines": sorted(set(DEFINED_INSIDE.findall(text))) if kind == "macro" else [],
+                          "paths": sorted(path_words(text)), "qualified": sorted(qualified_words(text)), "invokes": sorted(set(MACRO_USE.findall(text)))})
+            if kind in ("fn", "const", "static"):
+                # An impl inside a function body still holds for the whole program.
+                for header in NESTED_IMPL.findall(text):
+                    items.append({"kind": "impl", "subject": header, "inherent": False,
+                                  "mentions": sorted(words(text)), "paths": sorted(path_words(text)), "qualified": sorted(qualified_words(text)), "invokes": sorted(set(MACRO_USE.findall(text)))})
+
+
+def crate_roots(crate_dir):
+    """A crate's root files: its library, binaries and examples."""
+    roots = [crate_dir / "src" / "lib.rs", crate_dir / "src" / "main.rs"]
+    for folder in (crate_dir / "src" / "bin", crate_dir / "examples"):
+        if folder.is_dir():
+            roots += sorted(folder.glob("*.rs")) + sorted(folder.glob("*/main.rs"))
+    return [root for root in roots if root.is_file()]
+
+
+class SourceGraph:
+    """The workspace's Rust sources, parsed once: what each file names, defines and declares."""
+
+    def __init__(self, root, rust_code, cache=None):
+        """cache: a dict of earlier parses by content digest, which the graph reuses and adds to (parity.py keeps it
+        in .local/parity-runner/reach-cache.json)."""
+        self.root = Path(root)
+        self.rust_code = rust_code
+        self.cache = {} if cache is None else cache
+        self.used = set()
+        self.files = {}
+        self.parent = {}  # module file -> the file declaring it
+        self.module_name = {}
+        self.roots = set()
+        self.target_cache = {}
+        self.workspace_heads = None
+        self.test_only = set()  # modules compiled into tests only
+        self.tables = None
+        self.root_of = {}  # source -> the root of its target (lib.rs, a bin's or an example's main file)
+        self.results = {}  # (entries, universe) -> reachable files
+        for manifest in sorted((self.root / "crates").glob("*/Cargo.toml")):
+            for crate_root in crate_roots(manifest.parent):
+                path = self.relative(crate_root)
+                self.roots.add(path)
+                self.root_of[path] = path
+                self.place(path, crate_root.parent, set())
+
+    def entries(self, artifacts, rust):
+        """The root files of the probes and binaries a harness built (its record's artifacts), among its Rust
+        dependencies: for a crate's probe binary, the probe modules it ran (parity.only_probes_run kept only those).
+        None when an artifact can't be placed."""
+        found = set()
+        for kind, name, *rest in artifacts:
+            selection = rest[1] if len(rest) > 1 else []
+            packages = [value for flag, value in zip(selection, selection[1:]) if flag == "-p"] or \
+                [manifest.parent.name for manifest in sorted((self.root / "crates").glob("*/Cargo.toml"))]
+            roots = set()
+            for package in packages:
+                crate = self.root / "crates" / package
+                targets = self.targets(crate)
+                if kind in ("example", "examples"):
+                    candidates = [path for target, (target_kind, path) in targets.items()
+                                  if target_kind == "example" and (not name or target == name)]
+                else:
+                    candidates = [path for target, (target_kind, path) in targets.items()
+                                  if target_kind == "bin" and (not name or target == name)]
+                for path in candidates:
+                    if path.endswith("/examples/probe/main.rs"):
+                        # The probes it ran, and the dispatch and support modules they use (only_probes_run kept
+                        # those); the binary's root, which only declares them, so their own submodules are placed.
+                        folder = path.removesuffix("main.rs")
+                        roots |= {dependency for dependency in rust if dependency.startswith(folder)
+                                  and "/" not in dependency.removeprefix(folder).removeprefix("support/")}
+                        if roots:
+                            roots.add(path)
+                    elif path in rust:
+                        roots.add(path)
+            if not roots:
+                return None
+            found |= roots
+        return found or None
+
+    def targets(self, crate):
+        """A crate's bins and examples: {target name: (kind, root file)}, from its Cargo.toml and Cargo's defaults."""
+        if crate in self.target_cache:
+            return self.target_cache[crate]
+        found = {}
+        manifest = (crate / "Cargo.toml").read_text(encoding="utf-8") if (crate / "Cargo.toml").is_file() else ""
+        package = re.search(r'^\[package\][^\[]*?^name\s*=\s*"([^"]+)"', manifest, re.MULTILINE | re.DOTALL)
+        if (crate / "src" / "main.rs").is_file() and package:
+            found[package.group(1)] = ("bin", self.relative(crate / "src" / "main.rs"))
+        for kind, folder in (("bin", crate / "src" / "bin"), ("example", crate / "examples")):
+            for path in sorted(folder.glob("*.rs")) + sorted(folder.glob("*/main.rs")):
+                found[path.stem if path.name != "main.rs" else path.parent.name] = (kind, self.relative(path))
+        for kind, table in re.findall(r"^\[\[(bin|example)\]\]([^\[]*)", manifest, re.MULTILINE):
+            name = re.search(r'^name\s*=\s*"([^"]+)"', table, re.MULTILINE)
+            path = re.search(r'^path\s*=\s*"([^"]+)"', table, re.MULTILINE)
+            if name and path and (crate / path.group(1)).is_file():
+                found[name.group(1)] = (kind, self.relative(crate / path.group(1)))
+        self.target_cache[crate] = found
+        return found
+
+    def target(self, path):
+        """The Cargo target a source belongs to: the root file of the library, bin or example whose module tree
+        holds it (a file nothing places is its own)."""
+        return self.root_of.get(path, path)
+
+    def is_library(self, path):
+        return self.target(path).endswith("/src/lib.rs")
+
+    def relative(self, path):
+        return Path(path).resolve().relative_to(self.root.resolve()).as_posix()
+
+    def place(self, path, module_dir, seen):
+        """Walk the module tree from a file: record each declared module's file, parent and name."""
+        if path in seen:
+            return
+        seen.add(path)
+        parsed = self.parse(path)
+        if parsed is None:
+            return
+        for name, nesting, attribute, test in parsed["declarations"]:
+            if attribute is not None:
+                if nesting:
+                    continue  # a #[path] inside an inline module: unplaced, so always kept
+                candidates = [(self.root / path).parent / attribute]
+            else:
+                folder = module_dir.joinpath(*nesting)
+                candidates = [folder / f"{name}.rs", folder / name / "mod.rs"]
+            for candidate in candidates:
+                if candidate.is_file():
+                    child = self.relative(candidate)
+                    self.parent.setdefault(child, path)
+                    self.module_name.setdefault(child, name)
+                    self.root_of.setdefault(child, self.root_of[path])
+                    if test or path in self.test_only:
+                        self.test_only.add(child)
+                    child_dir = candidate.parent if candidate.name == "mod.rs" or attribute is not None \
+                        else candidate.parent / candidate.stem
+                    self.place(child, child_dir, seen)
+                    break
+
+    def parse(self, path):
+        if path in self.files:
+            return self.files[path]
+        try:
+            data = (self.root / path).read_bytes()
+        except OSError:
+            self.files[path] = None
+            return None
+        digest = hashlib.sha256(data).hexdigest()
+        self.used.add(digest)
+        if digest in self.cache:
+            self.files[path] = parsed = self.cache[digest]
+            return parsed
+        raw = data.decode("utf-8", errors="replace")
+        code = self.rust_code(raw)  # same length as raw: literals and comments blanked
+        opening = {match.end() - 1: match.group(1) for match in INLINE_MOD.finditer(code)}
+        events = sorted([(match.start(), match) for match in BRACE.finditer(code)]
+                        + [(match.start(), match) for match in MOD_DECLARATION.finditer(code)], key=lambda event: event[0])
+        declarations, stack, depth = [], [], 0
+        for index, match in events:
+            if match.group() == "{":
+                depth += 1
+                if index in opening:
+                    stack.append((opening[index], depth))
+            elif match.group() == "}":
+                if stack and stack[-1][1] == depth:
+                    stack.pop()
+                depth -= 1
+            else:
+                window = " ".join(raw[max(0, index - 300):match.end()].split())
+                attribute = PATH_ATTRIBUTE.search(window)
+                declarations.append([match.group(1), [name for name, _ in stack], attribute.group(1) if attribute else None,
+                                     bool(TEST_MODULE.search(window))])
+        items = []
+        parse_items(code, 0, len(code), items)
+        self.files[path] = parsed = {
+            "declarations": declarations,
+            "items": items,
+            "glob": bool(GLOB_IMPORT.search(code)),
+            "file_names": sorted(set(FILE_NAME.findall(raw))),
+        }
+        self.cache[digest] = parsed
+        return parsed
+
+    def saved_cache(self):
+        """The parses of the files this graph read, to keep for the next run."""
+        return {digest: self.cache[digest] for digest in self.used if digest in self.cache}
+
+    def requirement(self, path, item):
+        """For an impl: for its trait and for its type, [names the file defines, other workspace names], one of
+        which must be a reached type or trait (of this file, of a crate it sees) before the impl can matter; both
+        empty: nothing of the workspace is needed. A name is the workspace's when the path naming it starts in the
+        workspace, or the file defines it, imports it from the workspace or may glob-import it; otherwise (std's,
+        another crate's, the prelude's) it needs nothing."""
+        if "requires" in item:
+            return item["requires"]
+        if self.workspace_heads is None:
+            self.workspace_heads = {"crate", "self", "super"} | set(self.module_name.values()) | {
+                manifest.parent.name.replace("-", "_") for manifest in (self.root / "crates").glob("*/Cargo.toml")}
+        parsed = self.parse(path)
+        defined = {name for other in parsed["items"] for name in other.get("names", ()) if other["kind"] != "use"}
+        workspace_imports = {name for other in parsed["items"] if other["kind"] == "use"
+                             and other["head"] in self.workspace_heads for name in other["names"]}
+        parameters, subject = impl_subject(item["subject"])
+        parts = []
+        for part in re.split(r"\bfor\b", subject, maxsplit=1):
+            names, own = set(), set()
+            for match in QUALIFIED.finditer(part):
+                segments_ = [segment.strip() for segment in match.group().split("::")]
+                name = segments_[-1]
+                if name in parameters or name in KEYWORDS:
+                    continue
+                if len(segments_) > 1:
+                    if segments_[0] in self.workspace_heads:
+                        names.add(name)
+                elif name in defined:
+                    own.add(name)
+                elif name in workspace_imports or (parsed["glob"] and name not in STD_NAMES):
+                    names.add(name)
+            parts.append([sorted(own), sorted(names)])
+        item["requires"] = parts
+        return parts
+
+    def index(self):
+        """Lookup tables over every placed source, built once: which crates each crate sees, the nodes (items, an
+        inherent impl's members) by the names they define and the types they need, the modules by name."""
+        if self.tables is not None:
+            return self.tables
+        idents = {manifest.parent.name.replace("-", "_"): manifest.parent.name
+                  for manifest in (self.root / "crates").glob("*/Cargo.toml")}
+        paths = [path for path in self.files if self.files[path] is not None and path not in self.test_only]
+        sees = {}
+        for path in paths:
+            named = {word for item in self.files[path]["items"] for word in item["mentions"]} & idents.keys()
+            sees.setdefault(crate_of(path), {crate_of(path)}).update(idents[name] for name in named)
+        changed = True
+        while changed:
+            changed = False
+            for crate, seen in sees.items():
+                wider = set().union(*(sees.get(other, {other}) for other in seen))
+                if not wider <= seen:
+                    seen |= wider
+                    changed = True
+        seen_by = {}  # crate -> the crates that see it
+        for crate, seen in sees.items():
+            for other in seen:
+                seen_by.setdefault(other, set()).add(crate)
+        # What a call of a workspace macro defines: what its definition's body defines.
+        expands = {}
+        for path in paths:
+            for item in self.files[path]["items"]:
+                if item["kind"] == "macro":
+                    for name in item["names"]:
+                        expands.setdefault(name, set()).update(item["defines"])
+        names_of, by_name, by_file_name, by_type, by_module, children, seeds = {}, {}, {}, {}, {}, {}, []
+        for path in paths:
+            crate = crate_of(path)
+            if path in self.module_name:
+                by_module.setdefault((crate, self.module_name[path]), []).append(path)
+                children.setdefault(self.parent[path], []).append(path)
+            for index, item in enumerate(self.files[path]["items"]):
+                node = (path, index, None)
+                names = set(item.get("names", ()))
+                if item["kind"] == "macro_call":
+                    names |= expands.get(item["macro"], set())
+                names_of[node] = names
+                if item["kind"] == "glue":
+                    seeds.append(node)
+                elif item["kind"] == "macro_call" and not names:
+                    # A macro call defining nothing by name may still expand to impls: it counts once a type or
+                    # trait it mentions is reached.
+                    for name in item["mentions"]:
+                        by_type.setdefault(name, []).append(node)
+                elif item["kind"] == "impl":
+                    required = {name for own, foreign in self.requirement(path, item) for name in own + foreign}
+                    members = [(path, index, member) for member in range(len(item["members"]))] if item["inherent"] else []
+                    for member_node in members:
+                        name = item["members"][member_node[2]]["name"]
+                        names_of[member_node] = set()
+                        if name:
+                            by_name.setdefault(name, []).append(member_node)
+                    for name in required:
+                        for other in [node] + members:
+                            by_type.setdefault(name, []).append(other)
+                    if not required:
+                        seeds.append(node)
+                        seeds += [member_node for member_node in members if not item["members"][member_node[2]]["name"]]
+                else:
+                    for name in names:
+                        by_name.setdefault(name, []).append(node)
+                        by_file_name.setdefault((path, name), []).append(node)
+        self.tables = dict(idents=idents, sees=sees, seen_by=seen_by, names_of=names_of, by_name=by_name,
+                           by_file_name=by_file_name, by_type=by_type, by_module=by_module, children=children,
+                           seeds=seeds, node_sets={})
+        return self.tables
+
+    def reachable(self, entries, universe, reasons=None):
+        """The files of universe (workspace Rust sources) holding an item reachable from entries (by the rules in
+        this module's doc), and the entries. reasons, a dict, gets why each file was reached (for debugging)."""
+        # Searching every source of the crates involved (not only those Cargo listed) only adds reach, and lets
+        # harnesses with the same entries (the game binary's) share one search.
+        crates = frozenset(crate_of(path) for path in universe)
+        key = (frozenset(entries), crates)
+        if reasons is None and key in self.results:
+            return self.results[key] & set(universe)
+        everything = {path for path in self.files if crate_of(path) in crates} | set(universe)
+        files = self.search(entries, everything, reasons)
+        self.results[key] = files
+        return files & set(universe)
+
+    def search(self, entries, universe, reasons):
+        targets = {self.target(path) for path in entries}
+        universe = {path for path in universe if (self.is_library(path) or self.target(path) in targets)
+                    and path not in self.test_only}
+        tables = self.index()
+        idents, sees, seen_by, names_of = tables["idents"], tables["sees"], tables["seen_by"], tables["names_of"]
+        node_sets = tables["node_sets"]
+        by_name, by_file_name, by_type = tables["by_name"], tables["by_file_name"], tables["by_type"]
+        by_module, children = tables["by_module"], tables["children"]
+        seeds = [node for node in tables["seeds"] if node[0] in universe]
+        for path in universe:
+            if (path in entries or (path not in self.parent and path not in self.roots)) and self.parse(path):
+                seeds += [(path, index, None) for index in range(len(self.parse(path)["items"]))]
+
+        def names(node):
+            return names_of.get(node, set())
+
+        def sets_of(node, item):
+            """A node's mentions, path words, qualified names and macro calls, as sets (parses keep lists)."""
+            if node not in node_sets:
+                source = item["members"][node[2]] if node[2] is not None else item
+                node_sets[node] = {key: set(source.get(key, ())) for key in ("mentions", "paths", "qualified", "invokes")}
+            return node_sets[node]
+
+        def item_of(node):
+            return self.parse(node[0])["items"][node[1]]
+
+        reached, opened, globbed, files, queue = set(), set(), set(), set(), []
+        # name -> the crates whose reached code mentions it plainly, names it in a path or an import, invokes it.
+        mentioned, qualified, invoked = {}, {}, {}
+        done = {"mentions": {}, "qualified": {}, "invokes": {}, "paths": {}}  # crate -> names already handled
+        path_names, types = {}, {}  # by crate
+        local = {}  # file -> plain mentions by reached code in it or below it (child modules may `use super::*`)
+        local_types = {}  # file -> its reached types and traits
+
+        def heard(table, name, crate):
+            """Whether a crate that can see crate's items has name in table."""
+            sources = table.get(name)
+            return bool(sources) and not sources.isdisjoint(seen_by.get(crate, {crate}))
+
+        def ready(node):
+            path, index, member = node
+            item = item_of(node)
+            crate = crate_of(path)
+            if item["kind"] == "impl":
+                visible = visible_types(crate)
+                here = local_types.get(path, set())
+                if not all((not own and not foreign) or here.intersection(own) or visible.intersection(foreign)
+                           for own, foreign in self.requirement(path, item)):
+                    return False
+                name = item["members"][member]["name"] if member is not None else None
+                return name is None or heard(mentioned, name, crate)  # a method: called by its name
+            if item["kind"] == "macro_call" and not names(node):
+                return not visible_types(crate).isdisjoint(item["mentions"])
+            names_ = names(node)
+            if item["kind"] == "macro":
+                return any(heard(invoked, name, crate) for name in names_)
+            if item["kind"] == "use" and item["glob"]:
+                return path in opened
+            nearby = local.get(path, ())
+            if any(name in nearby for name in names_):
+                return True  # named in its own module, or below it
+            if item["kind"] == "use" and not item["public"]:
+                return False
+            if path in opened and any(heard(qualified, name, crate) for name in names_):
+                return True  # named through a path, or imported
+            return path in globbed and any(heard(mentioned, name, crate) for name in names_)
+
+        visible_cache = {}
+
+        def visible_types(crate):
+            """The reached types and traits of the crates a crate sees (cached until a type is reached)."""
+            if crate not in visible_cache:
+                visible_cache[crate] = set().union(*(types.get(other, set()) for other in sees.get(crate, {crate})))
+            return visible_cache[crate]
+
+        def wake(nodes, why):
+            for other in nodes:
+                if other not in reached and other[0] in universe and ready(other):
+                    reach(other, why)
+
+        def open_module(path, why):
+            pending = [path]
+            while pending:
+                current = pending.pop()
+                if current in opened:
+                    continue
+                opened.add(current)
+                crate = crate_of(current)
+                pending += [child for child in children.get(current, ())
+                            if child in universe and self.module_name[child] in path_names.get(crate, ())]
+                parsed = self.parse(current)
+                wake([(current, index, None) for index, item in enumerate(parsed["items"] if parsed else ())
+                      if item["kind"] != "impl"], f"{current} opened ({why})")
+
+        def reach(node, why):
+            if node in reached:
+                return
+            reached.add(node)
+            queue.append(node)
+            path, _, member = node
+            item = item_of(node)
+            if (item["kind"] == "use" and not item["public"]) or (item["kind"] == "impl" and item["inherent"] and member is None):
+                return
+            if path not in files:
+                files.add(path)
+                if reasons is not None:
+                    reasons[path] = why
+
+        for path in universe:
+            if path.endswith("/src/lib.rs") or path in entries or path not in self.parent:
+                open_module(path, "crate root or entry")
+        for node in seeds:
+            reach(node, "entry" if node[0] in entries else "always counted")
+        for path in entries & universe:
+            files.add(path)
+            if reasons is not None:
+                reasons.setdefault(path, "entry")
+        while queue:
+            node = queue.pop()
+            path, index, member = node
+            item = item_of(node)
+            crate = crate_of(path)
+            label = (item.get("names") or [item["kind"]])[0] if member is None else item["members"][member]["name"]
+            source = sets_of(node, item)
+            why = f"{path} ({label})"
+            # Plain mentions reach items of this file and of the modules above it.
+            ancestor, new = path, source["mentions"]
+            while ancestor is not None and new:
+                known = local.setdefault(ancestor, set())
+                new = new - known
+                known |= new
+                for name in new:
+                    wake(by_file_name.get((ancestor, name), ()), f"{why} mentions {name}")
+                ancestor = self.parent.get(ancestor)
+            if item["kind"] == "use" and item["glob"]:
+                for name in item["names"]:
+                    for target in sees.get(crate, {crate}):
+                        for module in list(by_module.get((target, name), ())) + \
+                                ([f"crates/{idents[name]}/src/lib.rs"] if name in idents else []):
+                            if module not in globbed and module in universe:
+                                globbed.add(module)
+                                wake([(module, index, None) for index in range(len(self.parse(module)["items"]))]
+                                     if self.parse(module) else [], f"{why} glob-imports {name}")
+            visible_to = sees.get(crate, {crate})
+            new = source["paths"] - done["paths"].setdefault(crate, set())
+            done["paths"][crate] |= new
+            for name in new:
+                for target in visible_to:
+                    path_names.setdefault(target, set()).add(name)
+                    for module in by_module.get((target, name), ()):
+                        if module in universe and self.parent[module] in opened:
+                            open_module(module, f"{why} names {name}")
+            for key, table, wanted in (("qualified", qualified, lambda other: True),
+                                       ("invokes", invoked, lambda other: item_of(other)["kind"] == "macro"),
+                                       ("mentions", mentioned, lambda other: other[2] is not None or other[0] in globbed)):
+                new = source[key] - done[key].setdefault(crate, set())
+                done[key][crate] |= new
+                for name in new:
+                    table.setdefault(name, set()).add(crate)
+                    wake([other for other in by_name.get(name, ()) if crate_of(other[0]) in visible_to and wanted(other)],
+                         f"{why} {key} {name}")
+            if item["kind"] in TYPE_KINDS and member is None:
+                own = types.setdefault(crate, set())
+                local_types.setdefault(path, set()).update(names(node))
+                if not names(node) <= own:
+                    own |= names(node)
+                    visible_cache.clear()
+                seeing = seen_by.get(crate, {crate})
+                for name in names(node):  # also when the crate has one by that name already: impls of this one
+                    wake([other for other in by_type.get(name, ()) if crate_of(other[0]) in seeing],
+                         f"implements for {name}, defined in {path}")
+        return files
+
+
+def impl_subject(header):
+    """An impl header (the text after `impl`): its generic parameters' names, and the rest without its where clause
+    (the trait and the type it is for)."""
+    header, parameters = header.strip(), set()
+    if header.startswith("<"):
+        depth = 0
+        for index, character in enumerate(header):
+            depth += {"<": 1, ">": -1}.get(character, 0)
+            if depth == 0:
+                generics, header = header[1:index], header[index + 1:]
+                parameters = {match.group(1) for match in re.finditer(rf"(?:^|,)\s*(?:const\s+)?({IDENT})", generics)}
+                break
+    return parameters, re.split(r"\bwhere\b", header)[0]
+
+
+def crate_of(path):
+    return path.split("/", 2)[1]
+
+
+def is_workspace_rust(path):
+    parts = PurePosixPath(path).parts
+    return len(parts) > 2 and parts[0] == "crates" and path.endswith(".rs")
+
+
+DECLARATION_LINE = re.compile(rf"\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+({IDENT})\s*;")
+
+
+def declarations(text, names, keep_rest):
+    """A Rust file's `mod` declarations of names, each with the attribute lines just above it; with keep_rest, the
+    whole text except the declarations of other modules instead."""
+    lines, found, attributes = text.splitlines(), [], []
+    for line in lines:
+        if line.strip().startswith("#[") and not line.strip().startswith("#!["):
+            attributes.append(line.strip())
+            continue
+        match = DECLARATION_LINE.match(line)
+        if match and match.group(1) in names:
+            found += attributes + [line.strip()]
+        elif keep_rest and not match:
+            found += attributes + [line]
+        attributes = []
+    return "\n".join(found + attributes)
+
+
+def declarations_changed(root, path, children, base, whole):
+    """Whether a changed file differs from the commit base in what a harness depends on: for a module parent, its
+    `mod` declarations of the reached children; for a whole file (whole), everything but its declarations of other
+    modules (adding a module beside reached ones changes nothing). True without a base, or if either side is
+    missing."""
+    if base is None:
+        return True
+    try:
+        head = (Path(root) / path).read_text(encoding="utf-8", errors="replace")
+        before = subprocess.run(["git", "show", f"{base}:{path}"], cwd=root, capture_output=True, text=True, check=True).stdout
+    except (OSError, subprocess.CalledProcessError):
+        return True
+    return declarations(head, children, whole) != declarations(before, children, whole)
+
+
+def narrow(dependencies, artifacts, graph, changed=()):
+    """A harness's dependencies narrowed to what its entry points can reach: {dependency: (whole, children)}, where
+    whole says the file counts for its own content (else only through its `mod` declarations of children, as a
+    module ancestor of a reached file) and children are its reached child modules. Without known entry points (a
+    probe or binary the harness built that isn't found here), every dependency is kept whole."""
+    plain = [dependency.split("#keep:")[0] for dependency in dependencies]
+    crates = {PurePosixPath(path).parts[1] for path in plain if path.startswith("crates/")}
+    rust = {path for path in plain if is_workspace_rust(path)}
+    added = {path for path in changed if is_workspace_rust(path) and PurePosixPath(path).parts[1] in crates
+             and path not in rust and (graph.root / path).is_file()}
+    entries = graph.entries(artifacts, rust)
+    if entries is None:
+        return {dependency: (True, None) for dependency in dependencies}
+    missing = {path for path in rust if graph.parse(path) is None}
+    reached = graph.reachable(entries, rust | added | entries) | missing
+    named, named_in_crate = set(), {}
+    for path in rust | added:
+        parsed = graph.parse(path)
+        file_names = set(parsed["file_names"]) if parsed else set()
+        if path in reached:
+            named |= file_names
+        named_in_crate.setdefault(PurePosixPath(path).parts[1], set()).update(file_names)
+    kept = {}
+    for dependency, path in zip(dependencies, plain):
+        if is_workspace_rust(path):
+            if path in reached:
+                kept[dependency] = (True, set())
+        elif not path.startswith("crates/") or path.endswith(("Cargo.toml", "build.rs")) \
+                or PurePosixPath(path).name in named \
+                or PurePosixPath(path).name not in named_in_crate.get(PurePosixPath(path).parts[1], ()):
+            kept[dependency] = (True, None)
+    for path in sorted(added & reached):
+        kept[path] = (True, set())
+    for path in sorted(reached):
+        child = path
+        while child in graph.parent:
+            parent = graph.parent[child]
+            kept.setdefault(parent, (False, set()))[1].add(graph.module_name[child])
+            child = parent
+    return kept

From 1e6f05ed5a192f6ccf483f8cb8877448b6eb6a01 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:15:37 +0100
Subject: [PATCH 224/270] Chat option: filter the chat's lines both ways, as
 setVisibleMessageFilter

The chat keeps where each message came from and the Chat option's
abilities. A message the option hides is still dropped on arrival, but a
change of the option now also hides the lines already in the chat that
it no longer shows, and brings them back when it shows them again
(ChatComponent.setVisibleMessageFilter -> refreshTrimmedMessages), on
apply_settings. Every Chat::add names its source. The Restrictions
screen reads its two flags from ChatAbilities instead of its own copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../examples/probe/hud_fixture/kinds.rs       |  1 +
 crates/horizon-client/src/chat.rs             | 72 ++++++++++++++++---
 crates/horizon-client/src/chat_tests.rs       | 24 +++++++
 crates/horizon-client/src/game.rs             |  3 +
 crates/horizon-client/src/game/chat.rs        | 28 +++++---
 crates/horizon-client/src/game/commands.rs    | 11 ++-
 crates/horizon-client/src/game/lan_screen.rs  |  5 +-
 crates/horizon-client/src/game/remote.rs      | 13 ++--
 8 files changed, 127 insertions(+), 30 deletions(-)

diff --git a/crates/horizon-client/examples/probe/hud_fixture/kinds.rs b/crates/horizon-client/examples/probe/hud_fixture/kinds.rs
index d1450f2e1..9ba66abe1 100644
--- a/crates/horizon-client/examples/probe/hud_fixture/kinds.rs
+++ b/crates/horizon-client/examples/probe/hud_fixture/kinds.rs
@@ -319,6 +319,7 @@ fn chat(c: &Value, h: i32, atlas: &HudAtlas) -> Vec<GuiDraw> {
             atlas,
             comp(&m["text"]),
             indicator,
+            horizon_client::chat::ChatSource::Client,
             m["at"].as_u64().unwrap_or(0),
             false,
         );
diff --git a/crates/horizon-client/src/chat.rs b/crates/horizon-client/src/chat.rs
index e14178c8d..04b9d486c 100644
--- a/crates/horizon-client/src/chat.rs
+++ b/crates/horizon-client/src/chat.rs
@@ -72,6 +72,14 @@ impl ChatAbilities {
             },
         }
     }
+    /// `visibleMessagesFilter`: the client's own lines always show.
+    pub fn shows(&self, source: ChatSource) -> bool {
+        match source {
+            ChatSource::Player => self.receive_player_messages,
+            ChatSource::Server => self.receive_system_messages,
+            ChatSource::Client => true,
+        }
+    }
     /// Whether the chat screen may send `input` (`hasAllowedInput`).
     pub fn allows(&self, input: &str) -> bool {
         if input.starts_with('/') {
@@ -82,6 +90,12 @@ impl ChatAbilities {
     }
 }
 
+impl Default for ChatAbilities {
+    fn default() -> Self {
+        Self::new(ChatVisibility::Full)
+    }
+}
+
 /// Where a chat line came from (`GuiMessageSource`): the visibility filters
 /// player messages and the server's, while the client's own always show.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -143,6 +157,7 @@ struct Message {
     added: u64,
     content: Text,
     indicator: Option<u32>,
+    source: ChatSource,
 }
 /// A wrapped line (`GuiMessage.Line`).
 #[derive(Clone, Debug)]
@@ -177,6 +192,8 @@ pub struct Chat {
     pub log: bool,
     /// Messages added since the start, for the control socket's events.
     pub received: u64,
+    /// The Chat option's `visibleMessageFilter` (`set_abilities`).
+    abilities: ChatAbilities,
 }
 impl Chat {
     pub fn lines_per_page(&self, focused: bool) -> usize {
@@ -186,16 +203,32 @@ impl Chat {
     fn max_width(&self) -> i32 {
         (f64::from(self.options.width_px()) / self.options.scale).floor() as i32
     }
-    /// ChatComponent.addMessage: wrap, prepend and trim to 100 lines.
+    /// ChatComponent.addMessage: wrap, prepend and trim to 100 lines. A
+    /// message the Chat option hides is dropped, unlogged.
     pub fn add(
         &mut self,
         atlas: &HudAtlas,
         content: Text,
         indicator: Option<u32>,
+        source: ChatSource,
         ticks: u64,
         focused: bool,
     ) {
-        // ChatComponent.logChatMessage: every message is in the log.
+        self.add_message(&atlas.font, content, indicator, source, ticks, focused);
+    }
+    fn add_message(
+        &mut self,
+        font: &crate::font::Font,
+        content: Text,
+        indicator: Option<u32>,
+        source: ChatSource,
+        ticks: u64,
+        focused: bool,
+    ) {
+        if !self.abilities.shows(source) {
+            return;
+        }
+        // ChatComponent.logChatMessage: every message shown is in the log.
         crate::logging::write_only(log::Level::Info, &format!("[CHAT] {}", content.plain()));
         if self.log {
             println!("[CHAT] {}", content.plain());
@@ -204,16 +237,17 @@ impl Chat {
             added: ticks,
             content,
             indicator,
+            source,
         };
-        self.add_lines(atlas, &message, focused);
+        self.add_lines(font, &message, focused);
         self.messages.insert(0, message);
         self.messages.truncate(100);
         self.received += 1;
     }
-    fn add_lines(&mut self, atlas: &HudAtlas, message: &Message, focused: bool) {
+    fn add_lines(&mut self, font: &crate::font::Font, message: &Message, focused: bool) {
         let width = self.max_width();
         let content = self.displayed(&message.content);
-        for line in atlas.font.wrap_components(&content, width) {
+        for line in font.wrap_components(&content, width) {
             if focused && self.scroll > 0 {
                 self.new_since_scroll = true;
                 self.scroll_by(1, focused);
@@ -239,16 +273,38 @@ impl Chat {
             content.strip_legacy()
         }
     }
-    /// Re-wrap after a width or scale change (ChatComponent.rescaleChat).
+    /// Re-wrap after a width or scale change (ChatComponent.rescaleChat),
+    /// keeping only the messages the Chat option shows.
     pub fn rescale(&mut self, atlas: &HudAtlas) {
+        self.rewrap(&atlas.font);
+    }
+    fn rewrap(&mut self, font: &crate::font::Font) {
         self.scroll = 0;
         self.new_since_scroll = false;
         self.lines.clear();
-        let messages: Vec<Message> = self.messages.iter().rev().cloned().collect();
+        let messages: Vec<Message> = self
+            .messages
+            .iter()
+            .rev()
+            .filter(|m| self.abilities.shows(m.source))
+            .cloned()
+            .collect();
         for m in &messages {
-            self.add_lines(atlas, m, false);
+            self.add_lines(font, m, false);
         }
     }
+    /// `ChatComponent.setVisibleMessageFilter`: the Chat option changed;
+    /// the messages it now hides leave the chat, those it shows again return.
+    pub fn set_abilities(&mut self, font: &crate::font::Font, abilities: ChatAbilities) {
+        if self.abilities != abilities {
+            self.abilities = abilities;
+            self.rewrap(font);
+        }
+    }
+    /// Whether a message from `source` would show (`visibleMessagesFilter`).
+    pub fn shows(&self, source: ChatSource) -> bool {
+        self.abilities.shows(source)
+    }
     pub fn clear(&mut self) {
         self.messages.clear();
         self.lines.clear();
diff --git a/crates/horizon-client/src/chat_tests.rs b/crates/horizon-client/src/chat_tests.rs
index cd5860bfb..6b058c0fb 100644
--- a/crates/horizon-client/src/chat_tests.rs
+++ b/crates/horizon-client/src/chat_tests.rs
@@ -412,3 +412,27 @@ fn restricted_input_says_why_it_will_not_send() {
             .any(|line| line == "chat_screen.commands_not_allowed")
     );
 }
+
+/// `ChatComponent.setVisibleMessageFilter`: a message the Chat option hides
+/// on arrival is dropped; one already in the chat leaves it while the option
+/// hides its kind and comes back when it shows it again.
+#[test]
+fn the_chat_option_filters_the_lines_both_ways() {
+    let font = font();
+    let mut chat = Chat::default();
+    let says = |chat: &mut Chat, text: &str, source| {
+        chat.add_message(&font, Text::literal(text), None, source, 0, false);
+    };
+    let shown =
+        |chat: &Chat| -> Vec<String> { chat.lines.iter().map(|l| l.content.plain()).collect() };
+    says(&mut chat, "player", ChatSource::Player);
+    says(&mut chat, "server", ChatSource::Server);
+    chat.set_abilities(&font, ChatAbilities::new(ChatVisibility::System));
+    assert_eq!(shown(&chat), ["server"]);
+    says(&mut chat, "dropped", ChatSource::Player);
+    chat.set_abilities(&font, ChatAbilities::new(ChatVisibility::Hidden));
+    says(&mut chat, "client", ChatSource::Client);
+    assert_eq!(shown(&chat), ["client"]);
+    chat.set_abilities(&font, ChatAbilities::new(ChatVisibility::Full));
+    assert_eq!(shown(&chat), ["client", "server", "player"]);
+}
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index f05ee41e4..2f337d16b 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -9136,6 +9136,9 @@ impl Game<'_> {
         )
     }
     fn apply_settings(&mut self) {
+        // LocalPlayer.refreshChatAbilities: the chat shows what the Chat option allows.
+        let abilities = self.chat_abilities();
+        self.ui.chat.set_abilities(&self.gui.atlas.font, abilities);
         if let Some(r) = &self.renderer {
             self.settings
                 .clamp_gui_scale([r.config.width as i32, r.config.height as i32]);
diff --git a/crates/horizon-client/src/game/chat.rs b/crates/horizon-client/src/game/chat.rs
index fafe88f26..1319b1192 100644
--- a/crates/horizon-client/src/game/chat.rs
+++ b/crates/horizon-client/src/game/chat.rs
@@ -463,9 +463,8 @@ impl Game<'_> {
             self.chat_line(text, ChatSource::Server);
             return;
         }
-        // ChatListener.handleSystemMessage: the Chat option's Hidden level
-        // takes the server's messages too.
-        if !self.chat_abilities().receive_system_messages {
+        // The Chat option's Hidden level takes the server's messages too.
+        if !self.ui.chat.shows(ChatSource::Server) {
             return;
         }
         let focused = self.screen == Screen::Chat;
@@ -474,6 +473,7 @@ impl Game<'_> {
             &self.gui.atlas,
             text,
             Some(SYSTEM_INDICATOR),
+            ChatSource::Server,
             self.ticks,
             focused,
         );
@@ -610,9 +610,14 @@ impl Game<'_> {
             );
             let focused = self.screen == Screen::Chat;
             let heard = self.mods.running().then(|| line.plain());
-            self.ui
-                .chat
-                .add(&self.gui.atlas, line, None, self.ticks, focused);
+            self.ui.chat.add(
+                &self.gui.atlas,
+                line,
+                None,
+                ChatSource::Player,
+                self.ticks,
+                focused,
+            );
             if let Some(line) = heard {
                 self.mods_chat(&line);
             }
@@ -916,9 +921,14 @@ impl Game<'_> {
             Err(e) => Text::translate("screenshot.failure", &[Text::literal(e.clone())]),
         };
         let focused = self.screen == Screen::Chat;
-        self.ui
-            .chat
-            .add(&self.gui.atlas, message, None, self.ticks, focused);
+        self.ui.chat.add(
+            &self.gui.atlas,
+            message,
+            None,
+            ChatSource::Client,
+            self.ticks,
+            focused,
+        );
     }
 }
 /// `yyyy-MM-dd_HH.mm.ss[_n].png` (Util.getFilenameFormattedDateTime, local time
diff --git a/crates/horizon-client/src/game/commands.rs b/crates/horizon-client/src/game/commands.rs
index b84f13e4a..41a4b7a15 100644
--- a/crates/horizon-client/src/game/commands.rs
+++ b/crates/horizon-client/src/game/commands.rs
@@ -2836,9 +2836,14 @@ impl Game<'_> {
             capture.push(line.clone());
         }
         let focused = self.screen == Screen::Chat;
-        self.ui
-            .chat
-            .add(&self.gui.atlas, line, None, self.ticks, focused);
+        self.ui.chat.add(
+            &self.gui.atlas,
+            line,
+            None,
+            horizon_client::chat::ChatSource::Player,
+            self.ticks,
+            focused,
+        );
         Ok(1)
     }
     /// MessageArgument: `@p`-style selectors in a message become names.
diff --git a/crates/horizon-client/src/game/lan_screen.rs b/crates/horizon-client/src/game/lan_screen.rs
index 335b5fbae..0f2bec30d 100644
--- a/crates/horizon-client/src/game/lan_screen.rs
+++ b/crates/horizon-client/src/game/lan_screen.rs
@@ -388,7 +388,10 @@ impl Restrictions {
             1 => Some("chat_restriction.chat_disabled_by_options"),
             _ => None,
         };
-        let (chat, commands) = (chat_visibility == 0, chat_visibility < 2);
+        let abilities = horizon_client::chat::ChatAbilities::new(
+            horizon_client::chat::ChatVisibility::from_option(chat_visibility),
+        );
+        let (chat, commands) = (abilities.send_messages, abilities.send_commands);
         // The body's widgets: text blocks (lines, top) and the action's top.
         let mut blocks = Vec::new();
         let mut action = None;
diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 80adb5ff6..a50fdaa61 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -798,20 +798,14 @@ impl Game<'_> {
         Some(stack)
     }
     /// A line in the connection's chat, with its styles, click and hover
-    /// events (ChatComponent.addMessage). `ChatListener` drops the lines the
-    /// Chat option hides before they reach the chat.
+    /// events (ChatComponent.addMessage). The lines the Chat option hides
+    /// are dropped there (its `visibleMessageFilter`).
     pub(super) fn chat_line(
         &mut self,
         content: horizon_client::text::Text,
         source: horizon_client::chat::ChatSource,
     ) {
-        let abilities = self.chat_abilities();
-        let allowed = match source {
-            horizon_client::chat::ChatSource::Player => abilities.receive_player_messages,
-            horizon_client::chat::ChatSource::Server => abilities.receive_system_messages,
-            horizon_client::chat::ChatSource::Client => true,
-        };
-        if !allowed {
+        if !self.ui.chat.shows(source) {
             return;
         }
         let text = content.plain();
@@ -820,6 +814,7 @@ impl Game<'_> {
             &self.gui.atlas,
             content,
             None,
+            source,
             self.ticks,
             self.screen == Screen::Chat,
         );

From 3adff150cf607a90675892ebe5559dee60a55669 Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:15:40 +0000
Subject: [PATCH 225/270] Record preparation validation timings and measurement
 limits

Co-Authored-By: Codex <noreply@openai.com>
---
 docs/launcher-preparation.md | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/launcher-preparation.md b/docs/launcher-preparation.md
index 7df5b9131..5381106a1 100644
--- a/docs/launcher-preparation.md
+++ b/docs/launcher-preparation.md
@@ -45,9 +45,17 @@ for every file stable across the two isolated runs. For the three known noisy JS
 it also requires semantic equality after normalizing object key order, opaque JVM lambda
 addresses and creative-tab tag set order. Other variation fails the release check.
 
-On Linux with Java 25, two comparisons produced 23,204 matching resource files each.
-The first isolated runs took 178.95 s and 104.25 s, versus 45.05 s batched; the second took
-100.03 s and 176.06 s, versus 120.09 s batched. All used precompiled exporters. These are fresh output directories with a warm OS file cache, on a
-machine with other workloads; the spread between isolated runs prevents treating this as a
-controlled speedup estimate. The compiler saving is separate: release preparation removes
-the previously measured 15 compiler invocations (29–52 s).
+On Linux with Java 25, the output comparisons used 23,204 resource files per run.
+All runs used precompiled exporters:
+
+| Comparison | Isolated A | Isolated B | Batched |
+|---|---:|---:|---:|
+| Initial | 178.95 s | 104.25 s | 45.05 s |
+| Repeat | 100.03 s | 176.06 s | 120.09 s |
+| Final, immutable collision cache | 133.80 s | 123.79 s | 56.19 s |
+
+These use fresh output directories with a warm OS file cache, on a machine with other
+workloads. The first two rows include output hashing; the final row measures preparation
+before comparison. The variability prevents treating these as a controlled speedup estimate.
+The compiler saving is separate: release preparation removes the previously measured
+15 compiler invocations (29–52 s).

From ea1c0a4490909d5af7beca6103642034eb463435 Mon Sep 17 00:00:00 2001
From: socksprox <info@shadowfly.net>
Date: Mon, 26 Oct 2026 00:19:29 +0100
Subject: [PATCH 226/270] Render mannequin entities (server NPCs)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Servers on 26.3 spawn NPCs as minecraft:mannequin — the avatar entity
vanilla added for exactly this — instead of fake players (gommehd.net's
"Gommunity" lobby NPCs are invisible today). The client never registered
the type: MobTypes.load only builds species::ALL, so AddEntity produced a
tracked entity but nothing to draw.

- EntityDataSerializers.RESOLVABLE_PROFILE (41) decodes into
  Value::Profile. Before, the entry list ended at it and the mannequin's
  DATA_IMMOVABLE and DATA_DESCRIPTION after it never decoded.
- species::ALL gains mannequin (player#main model, Humanoid anim), and
  the player-only render paths — skin texture, sleep pose,
  AvatarRenderer's 0.9375 scale — take an avatar() check instead of the
  id string.
- SetEntityData's apply stores DATA_PROFILE on the mob, and
  update_remote_skins resolves its textures property through
  PlayerSkinRenderCache's rules (unsigned allowed, SkinManager's
  insecure path) the way a tab player's skin resolves.
- Mannequins get the shared-flags crouch and sleeping-position handling
  other players already had.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 crates/horizon-client/src/game/remote.rs      |  71 +++++++--
 .../src/game/remote_mob_data.rs               |  23 +++
 crates/horizon-client/src/mobs.rs             |   4 +
 crates/horizon-client/src/mobs/render.rs      |  13 +-
 crates/horizon-client/src/mobs/species.rs     |  15 +-
 crates/horizon-protocol/src/entity_data.rs    | 143 ++++++++++++++++++
 6 files changed, 255 insertions(+), 14 deletions(-)

diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs
index 03b48df3d..d64449f55 100644
--- a/crates/horizon-client/src/game/remote.rs
+++ b/crates/horizon-client/src/game/remote.rs
@@ -1906,10 +1906,14 @@ impl Game<'_> {
                 }
                 // LivingEntity.DATA_LIVING_ENTITY_FLAGS: for another player
                 // too, remote_mob_data's apply reads index 8 above.
-                let other = self
-                    .remote
-                    .as_ref()
-                    .is_some_and(|r| r.level_players.contains_key(&p.id) && r.entity_id != p.id);
+                let mannequin = self
+                    .mobs
+                    .iter()
+                    .any(|m| m.id == p.id as u32 && &*m.kind.id == "minecraft:mannequin");
+                let other = mannequin
+                    || self.remote.as_ref().is_some_and(|r| {
+                        r.level_players.contains_key(&p.id) && r.entity_id != p.id
+                    });
                 // LivingEntity.onSyncedDataUpdated(SLEEPING_POS_ID): another
                 // player lies down in their bed (drawn lying in it), or gets up.
                 if other {
@@ -1960,11 +1964,13 @@ impl Game<'_> {
                     }
                 }
                 // Entity.DATA_SHARED_FLAGS_ID's crouching bit: another
-                // player's crouch (their model and Entity.isDiscrete's name tag).
-                if self
-                    .remote
-                    .as_ref()
-                    .is_some_and(|r| r.level_players.contains_key(&p.id))
+                // player's or a mannequin's crouch (their model and
+                // Entity.isDiscrete's name tag).
+                if (mannequin
+                    || self
+                        .remote
+                        .as_ref()
+                        .is_some_and(|r| r.level_players.contains_key(&p.id)))
                     && let Some(m) = self.mobs.iter_mut().find(|m| m.id == p.id as u32)
                 {
                     for (index, _, value) in &p.values {
@@ -2781,6 +2787,53 @@ impl Game<'_> {
         {
             mob.skin = Some(skin);
         }
+        // ClientMannequin.updateSkin (PlayerSkinRenderCache.lookup): a
+        // mannequin's DATA_PROFILE `textures` property resolves like a
+        // player's, never required to be signed.
+        let mannequins: Vec<(u32, horizon_client::skins::Textures)> = self
+            .mobs
+            .iter()
+            .filter(|m| &*m.kind.id == "minecraft:mannequin" && m.profile.is_some())
+            .map(|m| {
+                let t = m
+                    .profile
+                    .as_ref()
+                    .and_then(|p| p.properties.iter().find(|p| p.name == "textures"));
+                let textures = t.map_or_else(Default::default, |t| {
+                    let signature = if t.signature.is_some() {
+                        horizon_client::skins::Signature::Signed
+                    } else {
+                        horizon_client::skins::Signature::Unsigned
+                    };
+                    horizon_client::skins::unpack(
+                        &t.value,
+                        signature,
+                        &horizon_client::skins::TEXTURE_URIS,
+                    )
+                });
+                (m.id, textures)
+            })
+            .collect();
+        let mut resolved: Vec<(u32, Option<String>)> = Vec::new();
+        for (id, textures) in mannequins {
+            let skin = {
+                let mut downloads = self.skin_downloads.borrow_mut();
+                horizon_client::skins::lookup(&textures, false, |kind, url| {
+                    downloads.state(kind, url)
+                })
+            };
+            resolved.push((id, skin));
+        }
+        for (id, skin) in resolved {
+            let skin = skin.filter(|s| !s.starts_with("skins/") || self.show_skin(s));
+            if let Some(mob) = self
+                .mobs
+                .iter_mut()
+                .find(|m| m.id == id && &*m.kind.id == "minecraft:mannequin")
+            {
+                mob.skin = skin;
+            }
+        }
     }
     /// Puts a downloaded skin in an atlas skin slot: a free one, else the
     /// least recently shown.
diff --git a/crates/horizon-client/src/game/remote_mob_data.rs b/crates/horizon-client/src/game/remote_mob_data.rs
index da786c1b9..fbfc5a4fb 100644
--- a/crates/horizon-client/src/game/remote_mob_data.rs
+++ b/crates/horizon-client/src/game/remote_mob_data.rs
@@ -75,6 +75,11 @@ fn apply(m: &mut Mob, values: &[(u8, i32, Value)], builtin: &Builtin) {
             // Zombie's three): what VillagerProfessionLayer draws.
             (Species::Villager, 19, Value::Ids(data))
             | (Species::ZombieVillager, 20, Value::Ids(data)) => villager_data(m, data, builtin),
+            // Mannequin.DATA_PROFILE (after Avatar's two): whose skin it
+            // wears; update_remote_skins resolves it like a tab player's.
+            (Species::Mannequin, 17, Value::Profile(profile)) => {
+                m.profile = Some(profile.clone());
+            }
             _ => {}
         }
     }
@@ -295,4 +300,22 @@ mod tests {
         apply(&mut e, &[(17, s::BYTE, Value::Byte(2))]);
         assert_eq!(e.extra.variant2, 2);
     }
+
+    #[test]
+    fn a_mannequin_exists_and_takes_its_profile() {
+        let Some(mut m) = mob("minecraft:mannequin") else {
+            return;
+        };
+        assert_eq!(&*m.kind.id, "minecraft:mannequin");
+        let profile = horizon_protocol::entity_data::Profile {
+            name: Some("Gommunity".into()),
+            uuid: Some(1),
+            ..Default::default()
+        };
+        apply(
+            &mut m,
+            &[(17, s::RESOLVABLE_PROFILE, Value::Profile(profile.clone()))],
+        );
+        assert_eq!(m.profile, Some(profile));
+    }
 }
diff --git a/crates/horizon-client/src/mobs.rs b/crates/horizon-client/src/mobs.rs
index 46834e9d1..1b5dddbe7 100644
--- a/crates/horizon-client/src/mobs.rs
+++ b/crates/horizon-client/src/mobs.rs
@@ -861,6 +861,9 @@ pub struct Mob {
     /// The skin texture of a player mob (`PlayerInfo.getSkin`), which
     /// replaces the type's default when its download is ready.
     pub skin: Option<String>,
+    /// A mannequin's `DATA_PROFILE` (ResolvableProfile): the profile's
+    /// `textures` property resolves to `skin` like a player's.
+    pub profile: Option<horizon_protocol::entity_data::Profile>,
 }
 /// Events a mob tick asks the game to act on.
 #[derive(Clone, Debug)]
@@ -1586,6 +1589,7 @@ impl Mob {
             rider: None,
             outbox: Vec::new(),
             skin: None,
+            profile: None,
             attrs: Attrs {
                 speed: kind.speed,
                 attack_damage: kind.attack_damage,
diff --git a/crates/horizon-client/src/mobs/render.rs b/crates/horizon-client/src/mobs/render.rs
index cb21cec8c..bbbf26738 100644
--- a/crates/horizon-client/src/mobs/render.rs
+++ b/crates/horizon-client/src/mobs/render.rs
@@ -92,6 +92,11 @@ fn climate(m: &Mob) -> &'static str {
         _ => "temperate",
     }
 }
+/// `AvatarRenderer` entities: a mannequin draws exactly like a player —
+/// the player model, its resolved skin and the same scale.
+fn avatar(m: &Mob) -> bool {
+    matches!(&*m.kind.id, "minecraft:player" | "minecraft:mannequin")
+}
 /// The model layer key and texture for the mob's body.
 pub fn body(m: &Mob) -> (String, String) {
     use Species as S;
@@ -103,7 +108,7 @@ pub fn body(m: &Mob) -> (String, String) {
             s.to_owned()
         }
     };
-    if &*m.kind.id == "minecraft:player" {
+    if avatar(m) {
         return (
             "main".into(),
             m.skin.clone().unwrap_or_else(|| m.kind.texture.clone()),
@@ -334,7 +339,7 @@ pub fn body_color(m: &Mob, alpha: f32) -> u32 {
 pub fn layers(m: &Mob) -> Vec<Layer> {
     use Species as S;
     let mut v = Vec::new();
-    if &*m.kind.id == "minecraft:player" {
+    if avatar(m) {
         return v;
     }
     let white = 0xFFFF_FFFF;
@@ -754,7 +759,7 @@ pub fn base_transform_at(m: &Mob, alpha: f32, origin: glam::Mat4) -> glam::Mat4
         body += (f64::from(ticks * 3.25).cos() * std::f64::consts::PI * 0.4) as f32;
     }
     // A sleeping villager, or another player lying in their bed.
-    let sleep = (m.species() == Species::Villager || m.kind.id == "minecraft:player")
+    let sleep = (m.species() == Species::Villager || avatar(m))
         .then(|| super::villager::sleep_pose(m))
         .flatten();
     let rotation = match sleep {
@@ -873,7 +878,7 @@ fn red_overlay(m: &Mob) -> bool {
     m.hurt_time > 0 || (m.death_time > 0 && !super::creaking::tearing_down(m))
 }
 fn species_scale(m: &Mob, alpha: f32) -> glam::Mat4 {
-    if m.kind.id == "minecraft:player" {
+    if avatar(m) {
         // AvatarRenderer.scale, shared by the inventory and world renderer.
         return glam::Mat4::from_scale(glam::Vec3::splat(0.9375));
     }
diff --git a/crates/horizon-client/src/mobs/species.rs b/crates/horizon-client/src/mobs/species.rs
index 28ea729b3..f48a21fe9 100644
--- a/crates/horizon-client/src/mobs/species.rs
+++ b/crates/horizon-client/src/mobs/species.rs
@@ -94,6 +94,7 @@ pub enum Species {
     Nautilus,
     ZombieNautilus,
     SulfurCube,
+    Mannequin,
 }
 /// Baby bounding boxes (each class's BABY_DIMENSIONS).
 #[derive(Clone, Copy, Debug)]
@@ -1307,6 +1308,18 @@ pub const ALL: &[Def] = &[
         None,
         Baby::None
     ),
+    // Mannequin: the player model; the DATA_PROFILE ResolvableProfile picks
+    // its skin, this texture only while that has none.
+    def!(
+        Mannequin,
+        "mannequin",
+        "player#main",
+        "entity/player/wide/steve",
+        A::Humanoid { zombie_arms: false },
+        ["", "entity.generic.hurt", "entity.generic.death"],
+        None,
+        Baby::None
+    ),
 ];
 pub fn def(s: Species) -> &'static Def {
     ALL.iter().find(|d| d.species == s).unwrap_or(&ALL[0])
@@ -1488,7 +1501,7 @@ impl Def {
             // Nautilus.handleAirSupply: it dries out on land.
             needs_water: aquatic || s == S::Nautilus,
             water_sensitive: matches!(s, S::Enderman | S::Blaze | S::SnowGolem),
-            animal: !matches!(s, S::Bat | S::SulfurCube)
+            animal: !matches!(s, S::Bat | S::SulfurCube | S::Mannequin)
                 && !self.hostile_class()
                 && !aquatic
                 && !matches!(
diff --git a/crates/horizon-protocol/src/entity_data.rs b/crates/horizon-protocol/src/entity_data.rs
index 574afd300..47467de4a 100644
--- a/crates/horizon-protocol/src/entity_data.rs
+++ b/crates/horizon-protocol/src/entity_data.rs
@@ -34,6 +34,98 @@ pub enum Value {
     Particle(Particle),
     /// A particle list (PARTICLES: a VarInt count, then each particle).
     Particles(Vec<Particle>),
+    /// A `ResolvableProfile` (a mannequin's DATA_PROFILE).
+    Profile(Profile),
+}
+/// `ResolvableProfile.STREAM_CODEC`: the GameProfile a mannequin or player
+/// head resolves — either a full profile (id, name and properties on the
+/// wire) or a partial one (a name and/or id to look up) — followed by a
+/// `PlayerSkin.Patch` of texture overrides.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Profile {
+    pub name: Option<String>,
+    pub uuid: Option<u128>,
+    /// `PropertyMap`: its `textures` property carries the skin.
+    pub properties: Vec<crate::packets::login::Property>,
+    /// `PlayerSkin.Patch`: texture asset ids overriding the profile's.
+    pub body: Option<String>,
+    pub cape: Option<String>,
+    pub elytra: Option<String>,
+    /// `PlayerModelType`: true is the slim (4px arms) model.
+    pub slim: Option<bool>,
+}
+/// `ByteBufCodecs.GAME_PROFILE_PROPERTIES`.
+fn read_properties(r: &mut Reader) -> Result<Vec<crate::packets::login::Property>> {
+    use crate::buf::Codec;
+    let n = r.count(16)?;
+    (0..n)
+        .map(|_| crate::packets::login::Property::read(r))
+        .collect()
+}
+fn write_properties(p: &[crate::packets::login::Property], w: &mut Writer) {
+    use crate::buf::Codec;
+    w.varint(p.len() as i32);
+    p.iter()
+        .for_each(|p| crate::packets::login::Property::write(p, w));
+}
+fn read_profile(r: &mut Reader) -> Result<Profile> {
+    let mut p = Profile::default();
+    // ByteBufCodecs.either: true is the full GameProfile, false a Partial.
+    if r.bool()? {
+        p.uuid = Some(r.uuid()?);
+        p.name = Some(r.string(16)?);
+        p.properties = read_properties(r)?;
+    } else {
+        if r.bool()? {
+            p.name = Some(r.string(16)?);
+        }
+        if r.bool()? {
+            p.uuid = Some(r.uuid()?);
+        }
+        p.properties = read_properties(r)?;
+    }
+    // PlayerSkin.Patch: three optional texture ids, then the model type.
+    if r.bool()? {
+        p.body = Some(r.string(32767)?);
+    }
+    if r.bool()? {
+        p.cape = Some(r.string(32767)?);
+    }
+    if r.bool()? {
+        p.elytra = Some(r.string(32767)?);
+    }
+    if r.bool()? {
+        p.slim = Some(r.bool()?);
+    }
+    Ok(p)
+}
+fn write_profile(p: &Profile, w: &mut Writer) {
+    let full = p.uuid.is_some() && p.name.is_some();
+    w.bool(full);
+    if full {
+        w.uuid(p.uuid.unwrap_or(0));
+        w.string(p.name.as_deref().unwrap_or(""));
+    } else {
+        w.bool(p.name.is_some());
+        if let Some(name) = &p.name {
+            w.string(name);
+        }
+        w.bool(p.uuid.is_some());
+        if let Some(uuid) = p.uuid {
+            w.uuid(uuid);
+        }
+    }
+    write_properties(&p.properties, w);
+    for texture in [&p.body, &p.cape, &p.elytra] {
+        w.bool(texture.is_some());
+        if let Some(texture) = texture {
+            w.string(texture);
+        }
+    }
+    w.bool(p.slim.is_some());
+    if let Some(slim) = p.slim {
+        w.bool(slim);
+    }
 }
 /// One `ParticleTypes.STREAM_CODEC` value: the `minecraft:particle_type` id,
 /// then the data its type carries (26.3 registry order).
@@ -258,6 +350,7 @@ fn read_value(kind: i32, r: &mut Reader) -> Result<Option<Value>> {
         | HUMANOID_ARM
         | DYE_COLOR => Value::Id(r.varint()?),
         PARTICLE => Value::Particle(Particle::read(r)?),
+        RESOLVABLE_PROFILE => Value::Profile(read_profile(r)?),
         PARTICLES => {
             let n = r.count(65536)?;
             let mut list = Vec::with_capacity(n.min(64));
@@ -305,6 +398,7 @@ fn write_value(kind: i32, v: &Value, w: &mut Writer) {
             w.varint(list.len() as i32);
             list.iter().for_each(|p| p.write(w));
         }
+        Value::Profile(p) => write_profile(p, w),
     }
     let _ = kind;
 }
@@ -455,4 +549,53 @@ mod tests {
             ]
         );
     }
+
+    /// RESOLVABLE_PROFILE (a mannequin's DATA_PROFILE): both ResolvableProfile
+    /// contents round-trip, and an entry after it still decodes.
+    #[test]
+    fn resolvable_profile_round_trips() {
+        use crate::packets::login::Property;
+        let full = Profile {
+            name: Some("Gommunity".into()),
+            uuid: Some(0x0123_4567_89AB_CDEF_0123_4567_89AB_CDEF),
+            properties: vec![Property {
+                name: "textures".into(),
+                value: "e30=".into(),
+                signature: Some("sig".into()),
+            }],
+            body: Some("minecraft:entity/player/wide/steve".into()),
+            cape: None,
+            elytra: None,
+            slim: Some(false),
+        };
+        let partial = Profile {
+            name: Some("Gommunity".into()),
+            ..Profile::default()
+        };
+        let mut w = Writer::new();
+        EntityData::write(
+            &vec![
+                (
+                    17,
+                    serializer::RESOLVABLE_PROFILE,
+                    Value::Profile(full.clone()),
+                ),
+                (
+                    17,
+                    serializer::RESOLVABLE_PROFILE,
+                    Value::Profile(partial.clone()),
+                ),
+                (18, serializer::BOOLEAN, Value::Bool(true)),
+            ],
+            &mut w,
+        );
+        assert_eq!(
+            EntityData::read(&mut Reader::new(&w.data)).unwrap(),
+            vec![
+                (17, serializer::RESOLVABLE_PROFILE, Value::Profile(full)),
+                (17, serializer::RESOLVABLE_PROFILE, Value::Profile(partial)),
+                (18, serializer::BOOLEAN, Value::Bool(true)),
+            ]
+        );
+    }
 }

From ef5361e4c25c223c6607af9efad9ca0d9348978d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:26:17 +0100
Subject: [PATCH 227/270] Creatures: drop the doc comments the removed cooldown
 fields left behind

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/creatures.rs | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/crates/horizon-client/src/game/creatures.rs b/crates/horizon-client/src/game/creatures.rs
index 9b2044d62..addb24d78 100644
--- a/crates/horizon-client/src/game/creatures.rs
+++ b/crates/horizon-client/src/game/creatures.rs
@@ -43,8 +43,6 @@ fn arrow_damage(arrow: &mut Projectile, fallback: &mut impl RandomSource) -> f32
 #[derive(Default)]
 pub(super) struct Creatures {
     pub projectiles: Vec<Projectile>,
-    /// Player status effects applied by mobs: (effect, ticks left, amplifier).
-    /// The wind charge's use cooldown (ticks).
     /// Wind bursts from a guest's turn, waiting for it to end (game/wind.rs).
     pub wind_bursts: Vec<super::wind::Burst>,
     /// Ticks left of the elder guardian's apparition (MobAppearanceParticle).
@@ -1559,7 +1557,6 @@ impl Game<'_> {
                 id, ticks, amplifier,
             ));
     }
-    /// Burning applied to the player by mobs.
     pub(super) fn hurt_player_by(&mut self, damage_type: &str, amount: f32) {
         if self.creative {
             return;

From 0baf6cbd62e5dc053732354b5ebd356aae3ffd83 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:27:22 +0100
Subject: [PATCH 228/270] CI: the desktop runner works while its screen is
 locked or untouched for 15 min
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ludovic's rule (2026-10-26): runner_pause.py pauses at once on keyboard, mouse or gamepad input
(read from /dev/input, only whether bytes came), on an unlocked session touched in the last
15 min, at 90 °C, on a game or the GPU. Fixes the service start: the link loop's last test
failed the script under set -e.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/parity-workflow.md    |  2 +-
 docs/release-flow.md       | 32 +++++++-------
 tests/test_runner_pause.py | 13 +++++-
 tools/ci/linux-runner.sh   | 12 +++---
 tools/ci/runner_pause.py   | 88 ++++++++++++++++++++++++++++++++------
 tools/parity_hosts.json    |  2 +-
 6 files changed, 113 insertions(+), 36 deletions(-)

diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index 80426fa59..7eecdd8bb 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -38,7 +38,7 @@ The game logs into `HORIZON_HOME` and falls back to the player's own game folder
 
 ### Other machines
 
-Harnesses can also run on the Mac mini, the ThinkPad and the desktop (`tools/parity_hosts.json` describes them; `desktop` uses its CI runner's environment and vanilla data, and refuses work, or stops it, while someone is at it: docs/release-flow.md, "The desktop's runner"; its `default` list is empty, so pass `--hosts macmini,thinkpad` or set `PARITY_HOSTS`, after copying `shared-local/` to `~/code/horizon-parity/shared-local` on each host). The runner mirrors the worktree there with rsync (not `.git`, `.local`, `target` or ignored files) into `~/code/horizon-parity/remote/<host><path>`, whose `.local` links to the vanilla data in `~/code/horizon-parity/shared-local`, and starts `tools/parity.py --worker` over ssh. The worker builds the probes (about 80 s the first time) and runs what it is sent under the same tracer, admitting harnesses against its own free memory. One queue, longest first, feeds every machine, remote ones first: the Mac takes up to 14 harnesses, the desktop 3 and only those under 800 MB. Each pass comes back with the content hash of every file it depended on, so it is keyed on exactly what ran, and logs come back to `.local/parity-runner/logs/`; state, sharing and `gate.py` work as before. If a host can't be reached, or drops out, its harnesses run here.
+Harnesses can also run on the Mac mini, the ThinkPad and the desktop (`tools/parity_hosts.json` describes them; `desktop` uses its CI runner's environment and vanilla data, and refuses work, or stops it, while someone uses it: docs/release-flow.md, "The desktop's runner"; its `default` list is empty, so pass `--hosts macmini,thinkpad` or set `PARITY_HOSTS`, after copying `shared-local/` to `~/code/horizon-parity/shared-local` on each host). The runner mirrors the worktree there with rsync (not `.git`, `.local`, `target` or ignored files) into `~/code/horizon-parity/remote/<host><path>`, whose `.local` links to the vanilla data in `~/code/horizon-parity/shared-local`, and starts `tools/parity.py --worker` over ssh. The worker builds the probes (about 80 s the first time) and runs what it is sent under the same tracer, admitting harnesses against its own free memory. One queue, longest first, feeds every machine, remote ones first: the Mac takes up to 14 harnesses, the desktop 8. Each pass comes back with the content hash of every file it depended on, so it is keyed on exactly what ran, and logs come back to `.local/parity-runner/logs/`; state, sharing and `gate.py` work as before. If a host can't be reached, or drops out, its harnesses run here.
 
 Harnesses a host can't run are listed in the file: `local_only` (`save_roundtrip` runs the game on a virtual screen) and each host's `exclude`. The Mac excludes nothing: vanilla's `Math.sin`, `pow`, `log` and the like don't round the same on an Apple silicon Mac as on Linux (HotSpot uses fdlibm there, Intel's stubs on x86-64), and Rust's float functions round like neither (they call the platform libm), so code that mirrors a vanilla `Math` call uses `horizon_core::jmath`, which computes what HotSpot computes on the host architecture. The ThinkPad helps too, gently: Linux, 2 harnesses at `nice 19`, since it hosts the Claude account pool; it finds ALSA through `~/code/horizon-parity/alsa-dev` like the desktop.
 
diff --git a/docs/release-flow.md b/docs/release-flow.md
index e72bebc73..d9d1801aa 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -68,21 +68,23 @@ release's macOS build back. Each keeps its own checkout, `target/` and Rust inst
 time, under a lock) and the parity passes and slots.
 
 **The desktop's runner.** `ludodesktop-horizon` (labels `self-hosted`, `Linux`, `X64`, `ludodesktop`, and
-`horizon-game` once a full trial has passed there) runs on the maintainer's Linux desktop, only while nobody is
-at it. `tools/ci/linux-runner.sh install`, run there as him, registers it and installs two systemd user services:
-`horizon-runner` (the runner, in `~/.actions-runners/horizon`, nice 19, in `horizon-ci.slice` with CPU and I/O
-weight 20 and memory capped at two thirds of the RAM; `CARGO_BUILD_JOBS` and the harness slots at 8, after the
-machine froze under ~7 cold cargo builds on 2026-10-14; its own Rust install; the JDK, sccache and the build
-libraries from nixpkgs; its own `vscreen` so no game it starts reaches his screen) and `horizon-runner-pause`
-(`tools/ci/runner_pause.py`), the only thing that starts the runner. The watcher stops it while a graphical
-session is open on the machine, locked or not (`~/fleet/power status` says "IN USE"), while a game runs (Steam,
-gamescope, Wine, Proton or Minecraft processes, fleet-load's own detection, or a process outside the CI slice
-using the GPU at 50 % or more), or while `~/.actions-runners/horizon/pause` exists, and starts it again 5 minutes
-after the last such sign. A job already under way is throttled to 2 threads at the lowest weight and the runner
-stops after it: freezing the job would make GitHub drop it as lost and the harnesses time out. Old pull requests'
-`runner-env.sh` know only the Mac: the runner's `.env` and `.path` give their jobs Python, the JDK and the
-vanilla data (`HORIZON_SHARED_SOURCE`) all the same. The nightly audit stays on the Mac mini's runners, so its
-comparison with the previous night is always made on one platform.
+`horizon-game` once a full trial has passed there) runs on the maintainer's Linux desktop while nobody uses it: its
+screen locked, or untouched for 15 minutes (his rule, 2026-10-26). `tools/ci/linux-runner.sh install`, run there as
+him, registers it and installs two systemd user services: `horizon-runner` (the runner, in
+`~/.actions-runners/horizon`, nice 19, in `horizon-ci.slice` with CPU and I/O weight 20 and memory capped at two
+thirds of the RAM; `CARGO_BUILD_JOBS` and the harness slots at 8, after the machine froze under ~7 cold cargo
+builds on 2026-10-14; its own Rust install; the JDK, sccache and the build libraries from nixpkgs; its own
+`vscreen` so no game it starts reaches his screen) and `horizon-runner-pause` (`tools/ci/runner_pause.py`), the
+only thing that starts the runner. The watcher stops it at once on keyboard, mouse or gamepad input (read from
+`/dev/input`: only whether bytes came, never what), while an unlocked session has had input in the last 15 minutes,
+while the CPU package is at 90 °C or more, while a game runs (Steam, gamescope, Wine, Proton or Minecraft
+processes, fleet-load's own detection, or a process outside the CI slice using the GPU at 50 % or more), or while
+`~/.actions-runners/horizon/pause` exists, and starts it again 5 minutes after the last such sign. A job already
+under way is throttled to 2 threads at the lowest weight and the runner stops after it: freezing the job would make
+GitHub drop it as lost and the harnesses time out. Old pull requests' `runner-env.sh` know only the Mac: the
+runner's `.env` and `.path` give their jobs Python, the JDK and the vanilla data (`HORIZON_SHARED_SOURCE`) all the
+same. The nightly audit stays on the Mac mini's runners, so its comparison with the previous night is always made
+on one platform.
 
 ## Merging
 
diff --git a/tests/test_runner_pause.py b/tests/test_runner_pause.py
index c6df08b82..38c4affd8 100644
--- a/tests/test_runner_pause.py
+++ b/tests/test_runner_pause.py
@@ -18,7 +18,7 @@ class Machine:
         self.throttles = []  # (clock, on)
         self.calls = []
 
-    def reason(self, hot):
+    def reason(self, hot, keys):
         return next((reason for start, end, reason in self.signs if start <= self.clock < end), None)
 
     def systemctl(self, *arguments):
@@ -77,6 +77,17 @@ class RunnerPauseTests(unittest.TestCase):
         self.assertLess(stop, 1215)
         self.assertEqual(machine.throttles[-1], (1290 + 300, False))
 
+    def test_the_desktop_is_free_when_locked_or_untouched_for_15_minutes(self):
+        cases = [  # (session, seconds since the last input, someone there)
+            (("3", False), 30, True), (("3", True), 30, True),  # any input pauses at once, even on the lock screen
+            (("3", False), 120, True), (("3", False), 1000, False),  # unlocked: free after 15 min untouched
+            (("3", True), 120, False), (None, 120, False),  # locked, or nobody logged in
+        ]
+        for session, idle, there in cases:
+            with self.subTest(session=session, idle=idle), \
+                    mock.patch.object(runner_pause, "seat_session", lambda: session):
+                self.assertEqual(runner_pause.at_the_screen(idle) is not None, there)
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tools/ci/linux-runner.sh b/tools/ci/linux-runner.sh
index adc2b0130..1bd587e79 100755
--- a/tools/ci/linux-runner.sh
+++ b/tools/ci/linux-runner.sh
@@ -9,10 +9,10 @@
 #
 # Everything lives in ~/.actions-runners/horizon (never in ~/code): the runner, its own rustup and cargo homes,
 # the work folder, and copies of this script and runner_pause.py taken at install time (a pull request's checkout
-# never runs as the service). horizon-runner-pause.service (runner_pause.py) starts the runner only while nobody is
-# at the screen or playing, and stops it otherwise. The runner runs nice, in horizon-ci.slice (low CPU and I/O weight, memory capped),
-# on its own virtual screen: vscreen (a headless sway) where it is installed, else Xvfb from nixpkgs with Mesa's
-# Vulkan drivers.
+# never runs as the service). horizon-runner-pause.service (runner_pause.py) starts the runner only while nobody
+# uses the machine (screen locked or untouched for 15 min, no game), and stops it otherwise. The runner runs nice,
+# in horizon-ci.slice (low CPU and I/O weight, memory capped), on its own virtual screen: vscreen (a headless sway)
+# where it is installed, else Xvfb from nixpkgs with Mesa's Vulkan drivers.
 # HORIZON_SHARED_SOURCE: the imported vanilla data (default ~/horizon-local/shared-local, else
 # ~/code/horizon/.local); RUNNER_JOBS: cargo jobs and harnesses at once (default a third of the threads, at most 8:
 # ludodesktop froze under ~7 cold cargo builds on 2026-10-14, and it is the maintainer's own machine).
@@ -40,7 +40,7 @@ parity_host_links() {
   [ -d "$checkout" ] || return 0
   mkdir -p "$shared"
   for entry in "$checkout"/*; do
-    [ -L "$entry" ] && ln -sfn "$entry" "$shared/$(basename "$entry")"
+    if [ -L "$entry" ]; then ln -sfn "$entry" "$shared/$(basename "$entry")"; fi
   done
 }
 
@@ -151,7 +151,7 @@ RestartSec=30
 EOF
   cat > "$units/horizon-runner-pause.service" <<EOF
 [Unit]
-Description=Runs the Horizon CI runner only while nobody is at the screen or playing
+Description=Runs the Horizon CI runner only while nobody uses the machine or plays on it
 [Service]
 ExecStart=$(command -v python3) $dir/runner_pause.py
 Restart=always
diff --git a/tools/ci/runner_pause.py b/tools/ci/runner_pause.py
index 57f304f1f..35476a0b2 100755
--- a/tools/ci/runner_pause.py
+++ b/tools/ci/runner_pause.py
@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
-"""Pauses the Horizon CI runner (tools/ci/linux-runner.sh) while the maintainer is at this machine or plays on it.
+"""Pauses the Horizon CI runner (tools/ci/linux-runner.sh) while the maintainer uses this machine or plays on it.
 
-The runner works only while nobody is at the screen (rule of 2026-10-25, after ludodesktop was restarted under a
-CI load while he used it). It pauses when any of these holds:
-  - a graphical session is open on seat0, locked or not: what `~/fleet/power status` calls "IN USE";
+The runner works while nobody uses the machine: its screen locked, or untouched for IDLE_AFTER seconds (900).
+It pauses when any of these holds:
+  - keyboard, mouse or gamepad input in the last INPUT_PAUSE seconds (60), or an unlocked session on seat0 with
+    input in the last IDLE_AFTER seconds;
+  - the CPU package at TEMP_LIMIT °C (90) or more;
   - fleet-load says a game runs (~/fleet/load: Steam, gamescope, Wine or Proton processes);
   - a process of his matches GAME below (the same, plus Minecraft and a Horizon game he started himself);
   - a process outside horizon-ci.slice keeps the GPU busy (nvidia-smi: SM use >= GPU_BUSY %, default 50, in two
@@ -34,6 +36,9 @@ GPU_BUSY = int(os.environ.get("GPU_BUSY", 50))
 INTERVAL = int(os.environ.get("INTERVAL", 15))
 RESUME_AFTER = int(os.environ.get("RESUME_AFTER", 300))
 THROTTLE_CPUS = int(os.environ.get("THROTTLE_CPUS", 2))
+INPUT_PAUSE = int(os.environ.get("INPUT_PAUSE", 60))
+IDLE_AFTER = int(os.environ.get("IDLE_AFTER", 900))
+TEMP_LIMIT = int(os.environ.get("TEMP_LIMIT", 90))
 
 
 def log(text):
@@ -53,13 +58,71 @@ def ci_process(pid):
         return True  # gone
 
 
-def at_the_screen():
-    """A graphical login on seat0, as ~/fleet/power status counts it (a locked screen counts too)."""
+class Input:
+    """Keyboard, mouse and gamepad activity, from /dev/input (the input group): only whether bytes came, never what."""
+
+    def __init__(self):
+        self.devices = {}  # path -> file descriptor
+        self.last = time.monotonic()  # a start counts as input: nothing is known yet
+
+    def poll(self):
+        try:
+            text = Path("/proc/bus/input/devices").read_text()
+        except OSError:
+            text = ""
+        wanted = {f"/dev/input/{handler}" for block in text.split("\n\n") for line in block.splitlines()
+                  if line.startswith("H: Handlers=") and re.search(r"\b(kbd|mouse\d*|js\d*)\b", line)
+                  for handler in line.split("=", 1)[1].split() if handler.startswith("event")}
+        for path in set(self.devices) - wanted:
+            os.close(self.devices.pop(path))
+        for path in wanted - set(self.devices):
+            try:
+                self.devices[path] = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+            except OSError:
+                pass
+        for path, descriptor in list(self.devices.items()):
+            try:
+                while os.read(descriptor, 4096):
+                    self.last = time.monotonic()
+            except BlockingIOError:
+                pass
+            except OSError:  # unplugged
+                os.close(self.devices.pop(path))
+        return time.monotonic() - self.last
+
+
+def seat_session():
+    """The graphical session on seat0 and whether its screen is locked, or None."""
     sessions = subprocess.run(["loginctl", "list-sessions", "--no-legend"], capture_output=True, text=True).stdout
     for line in sessions.splitlines():
         fields = line.split()
         if "seat0" in fields:
-            return f"session {fields[0]} of {fields[2] if len(fields) > 2 else '?'} at the screen (seat0)"
+            locked = subprocess.run(["loginctl", "show-session", fields[0], "-p", "LockedHint", "--value"],
+                                    capture_output=True, text=True).stdout.strip() == "yes"
+            return fields[0], locked
+    return None
+
+
+def at_the_screen(input_idle):
+    """Someone is at the machine: input in the last INPUT_PAUSE seconds, or an unlocked session with input in the last
+    IDLE_AFTER seconds. A locked screen, or one nobody touched for IDLE_AFTER, leaves the machine to CI."""
+    if input_idle < INPUT_PAUSE:
+        return f"input {input_idle:.0f} s ago"
+    session = seat_session()
+    if session and not session[1] and input_idle < IDLE_AFTER:
+        return f"session {session[0]} unlocked, input {input_idle:.0f} s ago"
+    return None
+
+
+def too_hot():
+    """The CPU package above TEMP_LIMIT °C (coretemp or k10temp)."""
+    for monitor in Path("/sys/class/hwmon").glob("hwmon*"):
+        try:
+            if (monitor / "name").read_text().strip() in ("coretemp", "k10temp"):
+                celsius = int((monitor / "temp1_input").read_text()) / 1000
+                return f"CPU at {celsius:.0f} °C" if celsius >= TEMP_LIMIT else None
+        except (OSError, ValueError):
+            pass
     return None
 
 
@@ -133,11 +196,12 @@ def throttle(on):
         systemctl("set-property", "--runtime", SLICE, "CPUWeight=20", "IOWeight=20", "CPUQuota=")
 
 
-def pause_reason(hot):
-    """Why the runner may not work now, or None. hot: the GPU users seen busy at the last sample (updated)."""
+def pause_reason(hot, keys):
+    """Why the runner may not work now, or None. hot: the GPU users seen busy at the last sample (updated);
+    keys: the Input watcher."""
     if MANUAL.exists():
         return f"paused by hand ({MANUAL})"
-    reason = at_the_screen() or fleet_load_gaming() or game_process()
+    reason = at_the_screen(keys.poll()) or too_hot() or fleet_load_gaming() or game_process()
     if reason:
         return reason
     busy = {pid for pid, sm in gpu_users().items() if sm >= GPU_BUSY}
@@ -154,13 +218,13 @@ def pause_reason(hot):
 
 
 def main():
-    hot = {}
+    hot, keys = {}, Input()
     # A boot (or a restart of this watcher) counts as a sign: the runner starts RESUME_AFTER seconds later at the
     # earliest, which leaves time to log in after switching the machine on.
     last_sign = time.monotonic()
     paused = None
     while True:
-        reason = pause_reason(hot)
+        reason = pause_reason(hot, keys)
         now = time.monotonic()
         if reason:
             last_sign = now
diff --git a/tools/parity_hosts.json b/tools/parity_hosts.json
index 5d561175d..f2ba65c68 100644
--- a/tools/parity_hosts.json
+++ b/tools/parity_hosts.json
@@ -18,7 +18,7 @@
    "setup": "test ! -e ~/.actions-runners/horizon/paused && set -a && . ~/.actions-runners/horizon/.env && set +a && export PATH=$(cat ~/.actions-runners/horizon/.path) && eval \"$(vscreen env)\"",
    "jobs": 8,
    "nice": 19,
-   "note": "ludodesktop, the maintainer's own machine: only while nobody is at the screen (tools/ci/runner_pause.py: a paused desktop refuses workers and stops the running ones, whose harnesses then run here); 8 jobs at most, in the CI runner's environment and slice"
+   "note": "ludodesktop, the maintainer's own machine: only while nobody uses it (tools/ci/runner_pause.py: screen locked or untouched for 15 min, no game; a paused desktop refuses workers and stops the running ones, whose harnesses then run here); 8 jobs at most, in the CI runner's environment and slice"
   },
   "thinkpad": {
    "ssh": "thinkpad",

From 836c1ee3b999823ab5d0db767ffbb6b71db4ab1e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:27:32 +0100
Subject: [PATCH 229/270] CI parity: pick harnesses with main's selection code,
 run them at the head

The parity job checks out the PR head, so every branch made before #1964
still selected with the old per-crate rule. The step now runs main's
tools/parity.py and tools/parity_reach.py with --changed --list, restores the
head's files, and runs the named harnesses with the head's parity.py. A
branch that edits either file, or a failure of main's selection, falls back
to the head's own `--changed` run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity.yml | 32 +++++++++++++++++++++++++++++++-
 docs/release-flow.md         |  3 +++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/parity.yml b/.github/workflows/parity.yml
index a18fc5019..be87bc965 100644
--- a/.github/workflows/parity.yml
+++ b/.github/workflows/parity.yml
@@ -43,7 +43,37 @@ jobs:
         env:
           PARITY_HOSTS: ''
           BASE_SHA: ${{ inputs.base }}
-        run: python3 tools/parity.py --changed "$BASE_SHA" --timeout 2400  # world_spawn takes ~1480 s on a busy runner
+        run: |
+          # main's selection (tools/parity.py --changed --list with main's parity.py and parity_reach.py), so a
+          # branch made before a better selection landed gets it too; the head's own runner then runs those
+          # harnesses. A branch that changes the selection itself selects with its own code.
+          set -euo pipefail
+          own() { python3 tools/parity.py --changed "$BASE_SHA" --timeout 2400; }  # world_spawn takes ~1480 s on a busy runner
+          fork_point=$(git merge-base "$BASE_SHA" HEAD)
+          if ! git rev-parse --verify -q origin/main >/dev/null || ! git diff --quiet "$fork_point" HEAD -- tools/parity.py tools/parity_reach.py; then
+            own
+            exit
+          fi
+          had_reach=$(git ls-files tools/parity_reach.py)
+          git show origin/main:tools/parity.py > tools/parity.py
+          git show origin/main:tools/parity_reach.py > tools/parity_reach.py
+          status=0
+          python3 tools/parity.py --changed "$BASE_SHA" --list > .local/parity-selection.txt || status=$?
+          git checkout -- tools/parity.py
+          if [ -n "$had_reach" ]; then git checkout -- tools/parity_reach.py; else rm -f tools/parity_reach.py; fi
+          cat .local/parity-selection.txt
+          if [ "$status" != 0 ]; then
+            echo "main's selection failed: the head's own selection runs"
+            own
+            exit
+          fi
+          names=$(sed '$d' .local/parity-selection.txt | grep -E '^[A-Za-z0-9_#]+$' || true)
+          if [ -z "$names" ]; then
+            echo "Nothing to run."
+            exit 0
+          fi
+          # shellcheck disable=SC2086
+          python3 tools/parity.py $names --timeout 2400
       - name: Logs of the failed harnesses
         if: failure()
         uses: actions/upload-artifact@v4
diff --git a/docs/release-flow.md b/docs/release-flow.md
index 4fb0209d9..3024e0f53 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -43,6 +43,9 @@ copy is: the Mac mini. Its runner runs as the maintainer's account and keeps its
    modules, Java oracles and every Rust source their probes compile) changed since the merge base, plus any
    harness nothing is recorded about yet, and runs those that have no pass for their current inputs. A change to
    `Cargo.lock` or `research-lock.json` affects every harness. Each harness has 25 minutes, the job 45.
+   The selection runs with main's `tools/parity.py` and `tools/parity_reach.py` (`--changed <base> --list`), so a
+   branch made before a better selection landed gets it too, and the head's own `parity.py` then runs the named
+   harnesses. A branch that changes either file selects with its own code.
 
 Failed harnesses' logs are uploaded as the `parity-logs` artifact.
 

From 0b970c0c9a0eb259652f5bee756073563e471faf Mon Sep 17 00:00:00 2001
From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com>
Date: Sun, 25 Oct 2026 23:35:22 +0000
Subject: [PATCH 230/270] Cover instant-break sounds alongside replanting

Move the instant_digging regression from redundant PR #1966 into the existing stale-dig fix for #1880 and #1908.

Co-Authored-By: Codex (gpt-6.1-sol) <noreply@openai.com>
---
 tools/lan_e2e.py | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/tools/lan_e2e.py b/tools/lan_e2e.py
index f0333c87b..11354b970 100755
--- a/tools/lan_e2e.py
+++ b/tools/lan_e2e.py
@@ -250,6 +250,7 @@ address. The script then checks, from both sides, what a guest's game used to ge
 - falling:   an item and a falling block the host summons high up fall smoothly on the guest, a
              little further every tick between the server's updates (every 20 ticks), as their own
              client tick moves them (they used to hang, then jump down once a second, #1568).
+- instant_digging: an instant survival break leaves no repeated stone hit sounds or stale server dig (#1908).
 - replant:   flowers and crops replanted after a short harvest click stay planted for both players;
              the server forgets the completed instant break (#1880).
 
@@ -5398,6 +5399,42 @@ CHECKS += ['digging']
 CHECK_FNS.update(digging=check_digging)
 
 
+def check_instant_digging(host, guest, out):
+    """#1908: an instant survival START has no STOP. ServerPlayerGameMode.tick
+    forgets a dig once its block is air; it must neither hit air nor break a replacement.
+    Exercise the in-frame host and network guest (both are clients with --server-thread).
+    """
+    result = {}
+    for label, player in (('host', host), ('guest', guest)):
+        x, y, z = (int(v // 1) for v in pos_of(player))
+        cell = (x, y + 1, z + 2)
+        player('command', command='gamemode survival')
+        player('command', command='clear @s')
+        host('command', command=f'fill {x - 1} {y} {z + 1} {x + 1} {y + 3} {z + 4} minecraft:air')
+        host('command', command=f'setblock {x} {y} {z + 2} minecraft:sand')
+        host('command', command=f'setblock {cell[0]} {cell[1]} {cell[2]} minecraft:dead_bush')
+        player.wait(10)
+        before = heard(player, 'minecraft:block.stone.hit')
+        player.raw('look-at', x + 0.5, y + 1.4, z + 2.5)
+        player.raw('mouse', 'left', 'click')
+        player.wait(20)
+        broken = host.raw('block', *cell).get('block')
+        hits = heard(player, 'minecraft:block.stone.hit') - before
+        host('command', command=f'setblock {cell[0]} {cell[1]} {cell[2]} minecraft:dead_bush')
+        player.wait(20)
+        replacement = host.raw('block', *cell).get('block')
+        result[label] = {'broken': broken, 'stone_hits': hits, 'replacement': replacement}
+        assert broken == 'minecraft:air', f'{label}: the bush did not break: {result}'
+        assert hits == 0, f'{label}: hitting air after an instant break: {result}'
+        assert replacement == 'minecraft:dead_bush', f'{label}: the server kept digging: {result}'
+        host('command', command=f'setblock {cell[0]} {cell[1]} {cell[2]} minecraft:air')
+    return result
+
+
+CHECKS += ['instant_digging']
+CHECK_FNS.update(instant_digging=check_instant_digging)
+
+
 def check_vehicles(host, guest, out):
     """The host and the guest each (#1551):
     - in creative, break a block and have it put back: the server's dig ends with the break

From 73da2f04ddd56cb2ca1f480f54ab0aad31478223 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:35:28 +0100
Subject: [PATCH 231/270] CI: parity on main, a batch of merges at a time;
 releases wait for it

parity-main runs the vanilla harnesses on every push to main, one run at a
time: merges that land during a run wait in one pending run, which checks
every merge since main's last green parity-main (tools/parity_main.py base,
then parity.py --changed). A failure is bisected over the batch's
first-parent merges, running only the failing harnesses, and the breaking
merge's pull request gets a comment.

Game releases ship only a commit both checks and parity-main passed on
(release_train.py; release.yml also starts when parity-main finishes; a
forced release doesn't wait). The per-PR parity job now runs only for a PR
that changes a harness, an oracle, a probe or the runner, or carries
run-parity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml          |  34 +++++++-
 .github/workflows/parity-main.yml |  70 ++++++++++++++++
 .github/workflows/release.yml     |  10 ++-
 docs/parity-workflow.md           |   2 +
 docs/release-flow.md              |  30 ++++++-
 tests/test_parity_main.py         |  43 ++++++++++
 tests/test_release_train.py       |  21 +++++
 tools/parity_main.py              | 129 ++++++++++++++++++++++++++++++
 tools/release_train.py            |  34 ++++++--
 9 files changed, 356 insertions(+), 17 deletions(-)
 create mode 100644 .github/workflows/parity-main.yml
 create mode 100644 tests/test_parity_main.py
 create mode 100644 tools/parity_main.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 98d5b9093..eff82fa99 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,8 @@ name: checks
 # check main requires, so it never has a condition: a skipped job counts as passed, and every run of this workflow
 # must report a real verify (a pull request that changes no Rust finishes it in seconds instead).
 # parity: the vanilla harnesses a pull request's changes can affect, on the Mac mini's runner, which holds the
-# maintainer's own Minecraft files (Horizon never downloads the game); .github/workflows/parity.yml. A fork's pull
+# maintainer's own Minecraft files (Horizon never downloads the game); .github/workflows/parity.yml. Only for a pull
+# request that changes a harness, oracle, probe or the runner: the rest are checked on main by parity-main. A fork's pull
 # request runs it only when a maintainer adds the run-parity label (.github/workflows/run-parity.yml), so labels
 # never start this workflow. See docs/release-flow.md.
 on:
@@ -72,8 +73,37 @@ jobs:
         run: |
           cargo +stable test --workspace --lib --bins --tests --features horizon-client/mods,horizon-mods/pack
           cargo +stable test --workspace --doc --features horizon-client/mods,horizon-mods/pack
-  parity:
+  # Most pull requests leave the harnesses to parity-main, which runs them on main a batch of merges at a time
+  # (.github/workflows/parity-main.yml; releases wait for it). A pull request still runs them itself when it changes
+  # a harness, an oracle, a probe or the runner, or carries the run-parity label (run-parity.yml, when it is added).
+  parity-scope:
     if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ steps.scope.outputs.run }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - id: scope
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          LABELS: ${{ join(github.event.pull_request.labels.*.name, ' ') }}
+        run: |
+          changed=$(git diff --name-only "$(git merge-base "$BASE_SHA" HEAD)" HEAD)
+          harness=$(grep -E '^(tools/test_[a-z0-9_]+_parity\.py|tools/(parity[a-z_]*|lab)\.py|tools/parity_hosts\.json|mods/horizon/src/test/|crates/[^/]+/examples/|crates/horizon-client/src/game/[a-z_]*(fixture|harness)\.rs|\.github/workflows/parity[a-z-]*\.yml)' <<< "$changed" || true)
+          if [ -n "$harness" ] || [[ " $LABELS " == *" run-parity "* ]]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+            echo "The pull request runs its harnesses: ${harness:-label run-parity}"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            echo "No harness, oracle, probe or runner change: parity-main checks this on main"
+          fi
+  parity:
+    needs: parity-scope
+    if: needs.parity-scope.outputs.run == 'true'
     uses: ./.github/workflows/parity.yml
     with:
       base: ${{ github.event.pull_request.base.sha }}
diff --git a/.github/workflows/parity-main.yml b/.github/workflows/parity-main.yml
new file mode 100644
index 000000000..1ddfb24bb
--- /dev/null
+++ b/.github/workflows/parity-main.yml
@@ -0,0 +1,70 @@
+name: parity-main
+# The vanilla harnesses on main, a batch of merges at a time (docs/release-flow.md#parity-on-main), on the Mac mini's
+# runner. One run at a time: merges that land while a run goes on wait in one pending run (GitHub keeps only the
+# newest), which checks every merge since main's last green parity-main (tools/parity_main.py base). On a failure it
+# bisects the failing harnesses over those merges and comments on the pull request that broke them. Releases ship
+# only a commit whose parity-main passed (tools/release_train.py), so nothing a harness catches reaches players.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  # The comment on the merge that broke a harness.
+  pull-requests: write
+  # tools/parity_main.py base reads earlier runs.
+  actions: read
+concurrency:
+  group: parity-main
+  cancel-in-progress: false
+env:
+  # Test runs never reach the telemetry server: no live-count ping, no uploads (docs/telemetry.md).
+  HORIZON_TELEMETRY_URL: "off"
+
+jobs:
+  parity-main:
+    runs-on: [self-hosted, horizon-game]
+    timeout-minutes: 240  # a core-crate batch reruns ~300 harnesses (~60-90 min), a bisect a few rounds of the failures
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+          # Keeps .local/ (parity state, probe builds, oracle results) and target/ between runs.
+          clean: false
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Tools from the runner
+        run: bash tools/ci/runner-env.sh
+      - name: Vanilla data, and resources prepared by this preparer
+        run: bash tools/ci/vanilla-data.sh
+      - name: Main's last green parity-main
+        id: base
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: echo "sha=$(python3 tools/parity_main.py base)" >> "$GITHUB_OUTPUT"
+      - name: The harnesses the merges since then can affect
+        env:
+          PARITY_HOSTS: ''
+          BASE_SHA: ${{ steps.base.outputs.sha }}
+        run: |
+          echo "Merges since ${BASE_SHA}:"
+          git log --first-parent --format='  %h %s' "$BASE_SHA..HEAD"
+          python3 tools/parity.py --changed "$BASE_SHA" --timeout 2400
+      - name: The merge that broke them
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PARITY_HOSTS: ''
+          BASE_SHA: ${{ steps.base.outputs.sha }}
+        run: |
+          rm -rf .local/parity-main-logs && cp -R .local/parity-runner/logs .local/parity-main-logs 2>/dev/null || true
+          python3 tools/parity_main.py bisect "$BASE_SHA" --comment
+      - name: Logs of the failed harnesses
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-main-logs
+          path: .local/parity-main-logs/
+          if-no-files-found: ignore
+          retention-days: 7
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4cba851fa..05f590096 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,6 +1,7 @@
 name: release
 # Automatic game releases (docs/release-flow.md). After every green `checks` run on main, every 10 minutes (so a
-# release waiting for merges to settle goes out without another merge) and by hand, tools/release_train.py decides:
+# release waiting for merges to settle goes out without another merge) and by hand, tools/release_train.py decides,
+# for a commit whose checks and parity-main (the vanilla harnesses on main) both passed:
 # a release when 5 pull requests merged since the last one changed what players run and the newest merged 5 minutes
 # ago, or when the oldest has waited 6 hours, or at once for a pull request labelled release-now.
 # RELEASES_PAUSED=1 (repository variable) stops them; so does an open issue labelled release-blocker, forced runs too.
@@ -18,7 +19,8 @@ name: release
 #   gh workflow run release -f dry_run=false -f force=true       # on main: release now, whatever the rules say
 on:
   workflow_run:
-    workflows: [checks]
+    # A game release ships a commit both passed on (parity-main runs on batches: the newest commit it passed on).
+    workflows: [checks, parity-main]
     types: [completed]
     branches: [main]
   schedule:
@@ -64,8 +66,8 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASES_PAUSED: ${{ vars.RELEASES_PAUSED }}
-          # The commit whose checks just passed; a dry run builds the branch it was started on; otherwise
-          # main's newest commit with green checks.
+          # The commit whose checks or parity-main just passed; a dry run builds the branch it was started on;
+          # otherwise main's newest commit with green checks and parity-main.
           HEAD_SHA: ${{ github.event.workflow_run.head_sha || (steps.mode.outputs.dry_run == 'true' && github.sha) || '' }}
           FORCE: ${{ inputs.force && 'yes' || '' }}
         run: |
diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index d794b9c71..d64ec3087 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -20,6 +20,8 @@ python3 tools/parity.py --changed origin/main      # those a branch's changes ca
 python3 tools/parity.py --changed-files paths.txt  # the same for listed paths, in a copy without Git (tools/pr_ready.py)
 ```
 
+On CI, a pull request runs the parity job only when it changes a harness, an oracle, a probe or the runner; everything else is checked on main by `parity-main`, a batch of merges at a time, which bisects a failure to the merge that caused it (`tools/parity_main.py`; [release-flow.md](release-flow.md#parity-on-main)). Game releases wait for it.
+
 Each harness runs unmodified under a tracer that records the files it depended on: its Python modules, its Java oracle and the oracle sources javac pulled in, other repository files it read, and the Rust sources of the probes it ran (from Cargo's `.d` dep-info files). A pass stands until one of those files, the pinned vanilla artifacts, `Cargo.lock` or the Rust/Java toolchains change. State and logs are in `.local/parity-runner/`; each harness's own outputs stay in its `.local/<name>/` directory.
 
 Vanilla oracle runs are reused as well. `tools/parity_shim.py` stands in for `java` and `javac`: it records each oracle run's outputs and the content of every file under the paths its arguments name, and replays the run while those are unchanged. After a Rust-only change a harness pays only for its Rust side (`block_update`: 53 s to 5 s). Files an oracle writes outside its named paths aren't tracked, so a harness that fails while reusing oracle results is rerun fresh, and stops reusing them if it then passes. `--all` and `--fresh` never reuse them.
diff --git a/docs/release-flow.md b/docs/release-flow.md
index 4fb0209d9..b551bad21 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -13,7 +13,7 @@ reopened; labels never start it):
 | Job | Runs on | What | Time |
 | --- | --- | --- | --- |
 | `verify` | GitHub `ubuntu-latest` | Public-tree check, Python tests, rustfmt, clippy with warnings denied, Rust tests. Dependencies and the workspace build come from a cache saved by main's runs | ~4 min cold, less warm |
-| `parity / parity` | The Mac mini's runner (`ludovics-mac-mini`, label `horizon-game`) | The vanilla harnesses the change can affect (`tools/parity.py --changed <base>`) | seconds when nothing is affected; minutes per affected harness |
+| `parity / parity` | The Mac mini's runner (`ludovics-mac-mini`, label `horizon-game`) | Only for a change to a harness, an oracle, a probe or the runner (or the `run-parity` label): the vanilla harnesses the change can affect (`tools/parity.py --changed <base>`). Other pull requests skip it: [parity-main](#parity-on-main) checks them on main | seconds when nothing is affected; minutes per affected harness |
 
 Pushes to main run `verify` only; the nightly audit covers main's harnesses.
 
@@ -80,10 +80,34 @@ gh api -X POST repos/ludovic111/horizon/branches/main/protection/required_status
 A skipped `parity` (a fork's pull request without the label) counts as passed, so requiring it never blocks a
 fork's pull request; the maintainer decides whether to run it.
 
+## Parity on main
+
+Most pull requests merge on `verify` alone and leave the vanilla harnesses to `.github/workflows/parity-main.yml`,
+which runs them on main a batch of merges at a time, on the Mac mini's runner:
+
+- It starts on every push to main, one run at a time (`concurrency: parity-main`). Merges that land while a run
+  goes on wait in one pending run: GitHub keeps only the newest and cancels the others, so the next run takes them
+  all.
+- `tools/parity_main.py base` gives the newest commit main contains whose parity-main passed (else the last
+  merge's parent), and the run is `tools/parity.py --changed <that commit>`: the union of the harnesses every merge
+  since then can affect, once, with every earlier pass reused.
+- On a failure, `tools/parity_main.py bisect` checks out the batch's first-parent merges by halves and runs only
+  the failing harnesses, names the first merge they fail on in the run's summary and comments on its pull request
+  (`🤖 Agent: parity-main found that this merge breaks ...`). Fix it with a pull request as usual; the next
+  run checks from the last green commit again.
+- Game releases ship only a commit both `checks` and `parity-main` passed on (`tools/release_train.py`, see
+  below), so a broken merge holds releases instead of reaching players. `release.yml` also starts when a
+  parity-main run finishes. A forced release (`force=true`) doesn't wait for parity-main.
+
+A pull request still runs its own parity job when it changes a harness script, an oracle
+(`mods/horizon/src/test/`), a probe (`crates/*/examples/`, `game/*_fixture.rs`, `game/*_harness.rs`), the runner
+(`tools/parity*.py`, `tools/lab.py`, `tools/parity_hosts.json`, `parity*.yml`), or carries the `run-parity` label
+(`run-parity.yml` runs it when the label is added).
+
 ## Game releases
 
-`.github/workflows/release.yml` releases the game by itself. It starts after every green `checks` run of a push
-to main, every 10 minutes (so a release waiting for merges to settle goes out without another merge), and by hand.
+`.github/workflows/release.yml` releases the game by itself. It starts after every green `checks` or `parity-main`
+run of a push to main (it releases a commit only once both passed on it), every 10 minutes (so a release waiting for merges to settle goes out without another merge), and by hand.
 
 ```mermaid
 flowchart LR
diff --git a/tests/test_parity_main.py b/tests/test_parity_main.py
new file mode 100644
index 000000000..7a72ecae5
--- /dev/null
+++ b/tests/test_parity_main.py
@@ -0,0 +1,43 @@
+"""tools/parity_main.py: the base of a parity-main run, and the bisect after a failure."""
+from pathlib import Path
+import tempfile
+import unittest
+from unittest import mock
+
+from tools import parity_main
+
+
+class ParityMainTests(unittest.TestCase):
+    def test_first_bad_finds_the_first_failing_merge(self):
+        commits = list("abcdefgh")  # h failed; the base before a passed
+        for culprit in commits:
+            tried = []
+            fails = lambda commit: tried.append(commit) or commit >= culprit
+            self.assertEqual(parity_main.first_bad(commits, fails), culprit)
+            self.assertLessEqual(len(tried), 3, "log2 of 8 merges")
+        self.assertEqual(parity_main.first_bad(["a"], lambda commit: self.fail("nothing to try")), "a")
+
+    def test_base_is_the_newest_green_run_head_contains(self):
+        with tempfile.TemporaryDirectory() as tmp, mock.patch.object(parity_main, "ROOT", Path(tmp)):
+            git = lambda *arguments: parity_main.git(*arguments).stdout.strip()
+            git("init", "-q")
+            for n in range(3):
+                git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", str(n))
+            head, parent, grandparent = git("rev-parse", "HEAD"), git("rev-parse", "HEAD^1"), git("rev-parse", "HEAD~2")
+            git("checkout", "-q", "-b", "side", grandparent)
+            git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", "side")
+            side = git("rev-parse", "HEAD")
+            git("checkout", "-q", head)
+            self.assertEqual(parity_main.base(runs=[side, grandparent, parent]), grandparent,
+                             "a run on a commit HEAD doesn't contain is skipped")
+            self.assertEqual(parity_main.base(runs=[]), parent, "no green run yet: the last merge")
+            self.assertEqual(parity_main.base(runs=[head]), head)
+
+    def test_a_harness_a_commit_does_not_have_cannot_fail_there(self):
+        with mock.patch.object(parity_main.subprocess, "run") as run:
+            self.assertFalse(parity_main.run_harnesses(["not_a_harness_yet"], 60))
+            run.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_release_train.py b/tests/test_release_train.py
index 56064fa42..ee1fbcae5 100644
--- a/tests/test_release_train.py
+++ b/tests/test_release_train.py
@@ -2,6 +2,7 @@ import datetime as dt
 from pathlib import Path
 import tempfile
 import unittest
+from unittest import mock
 
 from tools import release_train as train
 
@@ -147,6 +148,26 @@ class ReleaseTrainTests(unittest.TestCase):
         self.assertFalse(train.decision("game", [], NOW, new_line="0.3", blockers=[7])[0])
         self.assertTrue(train.decision("game", [pr(1)], NOW, blockers=[])[0])
 
+    def test_game_releases_ship_only_what_parity_main_passed(self):
+        def runs(parity, checks):
+            def gh_json(*arguments):
+                table = parity if "parity-main" in arguments else checks
+                if "--commit" in arguments:
+                    sha = arguments[arguments.index("--commit") + 1]
+                    return [{"status": s, "conclusion": c} for h, s, c in table if h == sha]
+                return [{"headSha": h, "status": s, "conclusion": c} for h, s, c in table]
+            return mock.patch.object(train, "gh_json", gh_json)
+        checks = [("c", "in_progress", ""), ("b", "completed", "success"), ("a", "completed", "success")]
+        with runs([("c", "queued", ""), ("b", "completed", "cancelled"), ("a", "completed", "success")], checks):
+            self.assertEqual(train.green_main_head(), "b", "checks alone: the newest green checks")
+            self.assertEqual(train.green_main_head(parity=True), "a", "a superseded parity-main run counts for nothing")
+            self.assertTrue(train.passed_on("parity-main", "a"))
+            self.assertFalse(train.passed_on("parity-main", "b"))
+        with runs([("b", "completed", "failure"), ("a", "completed", "success")], checks):
+            self.assertIsNone(train.green_main_head(parity=True), "a failed batch holds releases until fixed")
+        with runs([("c", "completed", "success")], checks):
+            self.assertIsNone(train.green_main_head(parity=True), "its checks must pass too")
+
     def test_a_release_is_published_only_after_its_smoke_test_and_with_no_blocker(self):
         drew = {"error": None, "frames": 12710, "chunks": 81, "meshed_sections": 550, "player": [160.5, 71.0, 156.5]}
         self.assertIsNone(train.gate(drew, []))
diff --git a/tools/parity_main.py b/tools/parity_main.py
new file mode 100644
index 000000000..ff319aed0
--- /dev/null
+++ b/tools/parity_main.py
@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""parity-main (.github/workflows/parity-main.yml): the vanilla harnesses run on main, a batch of merges at a time.
+
+    python3 tools/parity_main.py base               # the commit this run checks from: main's last green parity-main
+    python3 tools/parity_main.py bisect BASE        # after a failure: the first merge since BASE that broke a harness
+
+`base` prints the newest commit on main whose parity-main run passed and that HEAD contains, else HEAD's first parent,
+so a run tests every merge since the last green one (`tools/parity.py --changed <base>`), however many landed while
+the previous run went on. `bisect` reads the harnesses that failed (.local/parity-runner/last-run.json), checks out
+the first-parent merges between BASE and HEAD by halves and runs only those harnesses, then names the first merge they
+fail on (written to $GITHUB_STEP_SUMMARY and, with --comment, on its pull request). HEAD is checked out again at the end.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+REPO = os.environ.get("GITHUB_REPOSITORY", "ludovic111/horizon")
+LAST_RUN = ROOT / ".local" / "parity-runner" / "last-run.json"
+
+
+def git(*arguments, check=True):
+    result = subprocess.run(["git", *arguments], cwd=ROOT, capture_output=True, text=True)
+    if check and result.returncode:
+        sys.exit(f"git {' '.join(arguments)}: {result.stderr.strip()}")
+    return result
+
+
+def green_runs():
+    """Head commits of main's passing parity-main runs, newest first."""
+    result = subprocess.run(["gh", "run", "list", "--repo", REPO, "--workflow", "parity-main", "--branch", "main",
+                             "--status", "success", "--limit", "30", "--json", "headSha"], capture_output=True, text=True)
+    if result.returncode:
+        print(f"note: no parity-main history ({result.stderr.strip()})", file=sys.stderr)
+        return []
+    return [run["headSha"] for run in json.loads(result.stdout or "[]")]
+
+
+def base(head="HEAD", runs=None):
+    for sha in green_runs() if runs is None else runs:
+        if git("merge-base", "--is-ancestor", sha, head, check=False).returncode == 0:
+            return git("rev-parse", sha).stdout.strip()
+    return git("rev-parse", f"{head}^1").stdout.strip()
+
+
+def first_bad(commits, fails):
+    """The first of commits (oldest first, the last known to fail; the one before them known to pass) where fails()."""
+    good, bad = -1, len(commits) - 1
+    while bad - good > 1:
+        middle = (good + bad) // 2
+        if fails(commits[middle]):
+            bad = middle
+        else:
+            good = middle
+    return commits[bad]
+
+
+def harness_exists(name):
+    return (ROOT / "tools" / f"test_{name.split('#')[0]}_parity.py").exists()
+
+
+def run_harnesses(names, timeout):
+    """Whether any of the harnesses fails at the checked-out commit (those it doesn't have yet can't)."""
+    present = [name for name in names if harness_exists(name)]
+    if not present:
+        return False
+    return subprocess.run([sys.executable, "tools/parity.py", *present, "--timeout", str(timeout)], cwd=ROOT).returncode != 0
+
+
+def bisect(since, timeout, comment):
+    failed = []
+    if LAST_RUN.exists():
+        failed = json.loads(LAST_RUN.read_text(encoding="utf-8")).get("failed") or []
+    if not failed:
+        print("No failed harness recorded: nothing to bisect.")
+        return 0
+    head = git("rev-parse", "HEAD").stdout.strip()
+    commits = git("rev-list", "--first-parent", "--reverse", f"{since}..{head}").stdout.split()
+    if not commits:
+        print("No merge since the base.")
+        return 0
+
+    def fails(commit):
+        print(f"--- {commit[:9]} {git('log', '-1', '--format=%s', commit).stdout.strip()}", flush=True)
+        git("checkout", "-q", "--detach", commit)
+        return run_harnesses(failed, timeout)
+
+    try:
+        culprit = first_bad(commits, fails) if len(commits) > 1 else commits[0]
+    finally:
+        git("checkout", "-q", "--detach", head)
+    subject = git("log", "-1", "--format=%s", culprit).stdout.strip()
+    number = re.search(r"Merge pull request #(\d+)", subject)
+    line = (f"parity-main: {', '.join(failed)} first fail at {culprit[:9]} ({subject}), "
+            f"of {len(commits)} merges since {since[:9]}.")
+    print(line)
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as summary:
+            summary.write(f"### {line}\n")
+    if comment and number:
+        url = f"{os.environ.get('GITHUB_SERVER_URL', 'https://github.com')}/{REPO}/actions/runs/{os.environ.get('GITHUB_RUN_ID', '')}"
+        body = (f"🤖 Agent: parity-main found that this merge breaks {', '.join(f'`{name}`' for name in failed)} on main "
+                f"(bisected over {len(commits)} merges: {url}). Releases wait until parity-main passes again.")
+        subprocess.run(["gh", "pr", "comment", number.group(1), "--repo", REPO, "--body", body])
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("base")
+    bisecting = commands.add_parser("bisect")
+    bisecting.add_argument("since", help="the last commit known to pass (the run's base)")
+    bisecting.add_argument("--timeout", type=int, default=2400, help="seconds per harness")
+    bisecting.add_argument("--comment", action="store_true", help="comment on the breaking merge's pull request")
+    args = parser.parse_args()
+    if args.command == "base":
+        print(base())
+        return 0
+    return bisect(args.since, args.timeout, args.comment)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tools/release_train.py b/tools/release_train.py
index 48d4d46cf..72d81ce57 100644
--- a/tools/release_train.py
+++ b/tools/release_train.py
@@ -414,13 +414,26 @@ def gather(kind, head, releases=None):
     return last, prs
 
 
-def green_main_head():
-    """The newest commit on main whose checks passed: what an automatic release builds."""
-    runs = gh_json("run", "list", "--repo", REPO, "--workflow", "checks", "--branch", "main", "--event", "push",
+def passed_on(workflow, sha):
+    """Whether the newest finished push run of workflow on main for commit sha passed."""
+    runs = gh_json("run", "list", "--repo", REPO, "--workflow", workflow, "--branch", "main", "--event", "push",
+                   "--commit", sha, "--limit", "5", "--json", "status,conclusion")
+    done = [entry for entry in runs if entry["status"] == "completed" and entry["conclusion"] != "cancelled"]
+    return bool(done) and done[0]["conclusion"] == "success"
+
+
+def green_main_head(parity=False):
+    """The newest commit on main whose checks passed: what an automatic release builds. With parity (game
+    releases), the newest commit parity-main passed on, if its checks passed too: parity-main runs on batches of
+    merges, so the commits a run skipped are covered by the next one, and a superseded run counts for nothing."""
+    workflow = "parity-main" if parity else "checks"
+    runs = gh_json("run", "list", "--repo", REPO, "--workflow", workflow, "--branch", "main", "--event", "push",
                    "--limit", "10", "--json", "headSha,status,conclusion")
     for entry in runs:
-        if entry["status"] == "completed":
-            return entry["headSha"] if entry["conclusion"] == "success" else None
+        if entry["status"] == "completed" and entry["conclusion"] != "cancelled":
+            if entry["conclusion"] != "success":
+                return None
+            return entry["headSha"] if not parity or passed_on("checks", entry["headSha"]) else None
     return None
 
 
@@ -437,7 +450,7 @@ def main():
     parser.add_argument("--kind", choices=["game", "launcher"], required=True)
     parser.add_argument("--head", help="the commit to release (default: the newest commit on main whose checks passed)")
     parser.add_argument("--tag", help="notes: the release's tag")
-    parser.add_argument("--force", action="store_true", help="release even without player-facing changes, before merges settle or while paused")
+    parser.add_argument("--force", action="store_true", help="release even without player-facing changes, before merges settle, while paused or before parity-main passed")
     parser.add_argument("--out", type=Path, help="notes: write title.txt and body.md here")
     parser.add_argument("--now", help="the time to decide at (ISO 8601; default now)")
     parser.add_argument("--smoke", type=Path, help="gate: the release smoke test's report (smoke-test.json)")
@@ -456,9 +469,12 @@ def main():
                 summary.write(f"### {line}\n")
         return 1 if problem else 0
 
-    head = args.head or green_main_head()
+    # Game releases ship only a commit the vanilla harnesses passed on (parity-main, docs/release-flow.md).
+    parity = args.kind == "game" and args.command == "decide" and not args.force
+    head = args.head or green_main_head(parity)
     if not head:
-        result = {"release": False, "reason": "main's latest checks did not pass"}
+        result = {"release": False, "reason": "main's latest checks did not pass" + (
+            " or parity-main did not pass on them" if parity else "")}
         print(json.dumps(result, indent=1))
         write_outputs({"release": "false", "reason": result["reason"]})
         return 0
@@ -482,6 +498,8 @@ def main():
     blockers = open_blockers() if args.kind == "game" else []
     release, reason = decision(args.kind, prs, now, os.environ.get("RELEASES_PAUSED") == "1", args.force, new_line,
                                blockers)
+    if release and args.head and parity and not (passed_on("parity-main", head) and passed_on("checks", head)):
+        release, reason = False, f"waiting for checks and parity-main to pass on {head[:9]}"
     minor = any("feature" in pr["labels"] for pr in prs if pr["paths"])
     tag = next_game_tag(tags, now.date(), line) if args.kind == "game" else next_launcher_tag(tags, minor, line)
     result = {

From 40c08c2d12ebfb8d0a56e9bc2f71b72460cfff0c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:38:47 +0100
Subject: [PATCH 232/270] streaming: check every fourth cell of the cover test
 in debug builds

the_grid_answers_as_the_scan compared the grid with the scan on every cell of
60 cases and took 20 of the ~30 s of `cargo test -p horizon-client` on the
ThinkPad. A debug build now checks every fourth cell of each row, shifted by
row and case, so the cases together still meet every cell position relative
to the areas; a release build checks every cell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/streaming.rs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/crates/horizon-client/src/streaming.rs b/crates/horizon-client/src/streaming.rs
index 55a2f0086..13b19fefc 100644
--- a/crates/horizon-client/src/streaming.rs
+++ b/crates/horizon-client/src/streaming.rs
@@ -2148,8 +2148,13 @@ mod cover_tests {
     }
 
     /// Every question streaming asks gets the same answer with the grid.
+    ///
+    /// A debug build checks every fourth cell of each row, shifted by row and case so the cases still cover every
+    /// cell's position relative to the areas: the full check took 20 of the ~30 s of the crate's tests.
+    /// `cargo test --release -p horizon-client --lib the_grid_answers_as_the_scan` checks every cell.
     #[test]
     fn the_grid_answers_as_the_scan() {
+        let stride = if cfg!(debug_assertions) { 4 } else { 1 };
         let mut seed = 0x9E37_79B9_7F4A_7C15u64;
         let forced: HashSet<(i32, i32)> = [(40, -40)].into();
         for case in 0..60 {
@@ -2165,7 +2170,8 @@ mod cover_tests {
             let (scan, grid) = (ranges(None), ranges(Some(&cover)));
             let span = [4, 30, 120][case % 3] + 40;
             for z in -span..=span {
-                for x in -span..=span {
+                let first = -span + (z + case as i32).rem_euclid(stride);
+                for x in (first..=span).step_by(stride as usize) {
                     for m in 0..=ExtraCover::REACH + 2 {
                         assert_eq!(
                             scan.in_extra(x, z, m),

From 0a8af38ac4ed1094a871eacae8338c4b95c636d5 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:39:18 +0100
Subject: [PATCH 233/270] Rings: search them on a thread behind the server, as
 the world opens

The previous commit decides chunks far from the rings without them. The
128 biome searches now start on a helper thread as an overworld with
structures opens, behind the server and render threads, so an eye of ender
or a chunk near a ring finds them done or shares what is left, instead of
running them all on the thread that asked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../horizon-client/src/game/world_loading.rs  |  3 +++
 crates/horizon-client/src/vanillagen.rs       | 20 +++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/crates/horizon-client/src/game/world_loading.rs b/crates/horizon-client/src/game/world_loading.rs
index 998788960..0cea31fd0 100644
--- a/crates/horizon-client/src/game/world_loading.rs
+++ b/crates/horizon-client/src/game/world_loading.rs
@@ -246,6 +246,9 @@ pub(super) fn make_streaming(
         let inner = Arc::new(VanillaTerrain::for_world(&options.resources.join("worldgen"), pack.assets.registry, res.biomes(), seed, dim.id(), structures).map_err(|e| {
                 format!("{e}\nPrepare the worldgen bundle with the launcher, or: horizon-prepare --prepare")
             })?);
+        if dim == Dim::Overworld && structures {
+            inner.search_rings_behind();
+        }
         locator = Some(inner.clone());
         Streaming::new(
             Arc::new(Persistent {
diff --git a/crates/horizon-client/src/vanillagen.rs b/crates/horizon-client/src/vanillagen.rs
index a17bb22d3..046de6551 100644
--- a/crates/horizon-client/src/vanillagen.rs
+++ b/crates/horizon-client/src/vanillagen.rs
@@ -279,6 +279,26 @@ impl VanillaTerrain {
         let worker = worker.get_or_insert_with(|| self.generator.worker());
         worker.ring_positions(set)
     }
+    /// Searches the concentric rings on a thread of their own, behind the
+    /// server and render threads, as vanilla's background executor does:
+    /// the first chunks don't wait for them, and an eye of ender thrown
+    /// later finds them ready. A chunk or a query that needs them first
+    /// shares the remaining searches with this thread.
+    pub fn search_rings_behind(self: &Arc<Self>) {
+        let terrain = Arc::clone(self);
+        let spawned = std::thread::Builder::new()
+            .name("Ring search".into())
+            .spawn(move || {
+                horizon_threads::behind_server();
+                let _ = terrain
+                    .generator
+                    .worker()
+                    .ring_positions("minecraft:strongholds");
+            });
+        if let Err(e) = spawned {
+            log::warn!("ring search thread: {e}");
+        }
+    }
 }
 /// The worldgen bundle at `dir`, loaded once and shared by every generator
 /// and by live feature placement (sapling growth, bone meal).

From 40f79354d615be286d3ba761b194f22928f57c79 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:40:43 +0100
Subject: [PATCH 234/270] release: build the preparer and compile the exporters
 fresh in the exporters job

The clean checkout removes target/, and vanilla-data.sh builds horizon-prepare only when it
prepares afresh, so compile-exporters had no binary on a cached preparation. The bundle is
also compiled in the job instead of reused from .local/exporters, which vanilla-data.sh links
to preparations that pull requests' parity jobs write, and the job fails if anything but our
classes and the manifest would leave the runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4d20941d4..52eef26da 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -96,9 +96,19 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          # target/ is gone after the clean checkout, and vanilla-data.sh builds the preparer only when it
+          # prepares afresh.
+          cargo build --release --locked -p horizon-prepare
+          # Compiled here, never taken from the runner's shared preparations: pull requests' parity jobs
+          # write those (vanilla-data.sh links .local/exporters to them).
+          rm -rf .local/exporters
           bundle=$(target/release/horizon-prepare compile-exporters --root "$PWD" | tail -1)
           mkdir -p exporters
           cp -R "$bundle/server" "$bundle/client" "$bundle/manifest.json" exporters/
+          # Only our classes and their manifest leave this runner.
+          stray=$(find exporters -type f ! -path exporters/manifest.json \
+            ! \( -name '*.class' \( -path 'exporters/server/dev/horizonlab/parity/*' -o -path 'exporters/client/dev/horizonlab/parity/*' \) \))
+          [ -z "$stray" ] || { echo "::error::not one of our classes: $stray"; exit 1; }
           python3 tools/check_prepare_exporters.py --binary target/release/horizon-prepare
       - uses: actions/upload-artifact@v4
         with:

From 5034e4557dba8c54ebd406a50ef4449b8d7ec2ea Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:44:22 +0100
Subject: [PATCH 235/270] parity: clear rust-<name>-parity outputs after a
 pass, reuse oracles on CI

Disk: clear_large_outputs only looked at .local directories named after the
harness, so the 174 harnesses writing to rust-<name>-parity kept every dump
(86 GB in one runner checkout, 13 GB for state_provider alone). It now
clears those too, keeps vanilla outputs only up to 256 MB (larger ones cost
more disk than rerunning their oracle), and handles shard names.
collision, world and geometry dropped one mkdtemp run directory per run
(11 GB): each run now removes the earlier ones.

Time: harnesses inherited the runner's stdin, a pipe on GitHub's runner, and
parity_shim never reuses an oracle run whose stdin is a pipe, so oracle reuse
never worked on CI. Harnesses now get /dev/null.

CI: parity.yml falls back to the head's own selection when the names main's
`--list` printed don't match its summary count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity.yml   | 11 ++++++++++-
 tests/test_parity_runner.py    | 14 ++++++++++++++
 tools/parity.py                | 20 ++++++++++++++------
 tools/test_collision_parity.py |  3 +++
 tools/test_geometry_parity.py  |  3 +++
 tools/test_world_parity.py     |  3 +++
 6 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/parity.yml b/.github/workflows/parity.yml
index be87bc965..9dcb21775 100644
--- a/.github/workflows/parity.yml
+++ b/.github/workflows/parity.yml
@@ -68,7 +68,16 @@ jobs:
             exit
           fi
           names=$(sed '$d' .local/parity-selection.txt | grep -E '^[A-Za-z0-9_#]+$' || true)
-          if [ -z "$names" ]; then
+          # The summary line says how many would run: a count that doesn't match the names read (a format change)
+          # must not let the job pass untested.
+          expected=$(tail -1 .local/parity-selection.txt | sed -nE 's/^([0-9]+) of [0-9]+ harnesses would run$/\1/p')
+          count=$(printf '%s' "$names" | grep -c . || true)
+          if [ -z "$expected" ] || [ "$expected" != "$count" ]; then
+            echo "main's selection listed $count names, its summary says '${expected:-?}': the head's own selection runs"
+            own
+            exit
+          fi
+          if [ "$count" = 0 ]; then
             echo "Nothing to run."
             exit 0
           fi
diff --git a/tests/test_parity_runner.py b/tests/test_parity_runner.py
index d10fde854..2d16e7179 100644
--- a/tests/test_parity_runner.py
+++ b/tests/test_parity_runner.py
@@ -300,3 +300,17 @@ class LargeOutputTests(unittest.TestCase):
             self.assertFalse((own / "dump.txt").exists())
             # chunk_generation may still be writing there.
             self.assertTrue((shared / "dump.txt").exists())
+
+    def test_rust_named_directories_and_big_oracle_outputs_go_too(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            local, state = Path(tmp) / ".local", Path(tmp) / "state"
+            own = local / "rust-state-provider-parity"
+            own.mkdir(parents=True)
+            for name, size in (("rust.txt", 16), ("server.txt", 16), ("client.txt", 64), ("report.json", 4)):
+                (own / name).write_bytes(b"x" * size)
+            trace = {"commands": [["java", "Oracle", str(own)], ["probe", "fixture", str(own)]]}
+            with mock.patch.multiple(parity, LOCAL=local, STATE_DIR=state, LARGE_OUTPUT=8, KEPT_ORACLE_OUTPUT=32):
+                listing = parity.outputs_listing("state_provider#2", fresh=True)
+                listing.write_text(f"{own / 'server.txt'}\n{own / 'client.txt'}\n")
+                parity.clear_large_outputs("state_provider#2", trace)
+            self.assertEqual(sorted(path.name for path in own.iterdir()), ["report.json", "server.txt"])
diff --git a/tools/parity.py b/tools/parity.py
index dc5fdb1c9..3f18b922d 100644
--- a/tools/parity.py
+++ b/tools/parity.py
@@ -657,6 +657,9 @@ def prebuild(artifacts, jobs):
 
 
 LARGE_OUTPUT = 64 << 20
+# Vanilla outputs above this are deleted after a pass too: rerunning those few oracles (12 harnesses on the Mac
+# mini's runner) costs less than the 26 GB they held in every checkout; smaller ones stay for oracle reuse.
+KEPT_ORACLE_OUTPUT = 256 << 20
 OWN_DIRECTORIES = {"parity-target", "parity-runner", "rea", "logs", "gate"}
 
 
@@ -672,11 +675,12 @@ def clear_large_outputs(name, trace):
     """After a pass, delete the large files a harness regenerates on every run.
 
     Harness outputs reach gigabytes and used to stay in every worktree. Vanilla
-    oracle outputs are kept, since reusing an oracle run needs them in place;
-    everything else large under the harness's .local directories is rebuilt on
-    its next run."""
+    oracle outputs under KEPT_ORACLE_OUTPUT are kept, since reusing an oracle
+    run needs them in place; everything else large under the harness's .local
+    directories (`<name>...` or `rust-<name>-parity`) is rebuilt on its next run."""
     local = LOCAL.resolve()
     keep = {os.path.realpath(line) for line in outputs_listing(name).read_text(encoding="utf-8").splitlines() if line}
+    own = name.split("#")[0].replace("_", "-")
     directories = set()
     for command in trace["commands"]:
         for argument in command[1:]:
@@ -688,12 +692,13 @@ def clear_large_outputs(name, trace):
             # Only the harness's own directory: another harness running beside it may be writing
             # large files in a directory this one merely read (decorated_region compiles its oracle
             # into chunk-generation-parity while chunk_generation writes its dumps there).
-            if top not in OWN_DIRECTORIES and top.startswith(name.replace("_", "-")):
+            if top not in OWN_DIRECTORIES and (top.startswith(own) or top == f"rust-{own}-parity"):
                 directories.add(local / top)
     for directory in directories:
         for file in (directory.rglob("*") if directory.is_dir() else []):
             try:
-                if file.is_file() and not file.is_symlink() and file.stat().st_size >= LARGE_OUTPUT and str(file) not in keep:
+                size = file.stat().st_size if file.is_file() and not file.is_symlink() else 0
+                if size >= LARGE_OUTPUT and (str(file) not in keep or size > KEPT_ORACLE_OUTPUT):
                     file.unlink()
             except OSError:
                 pass
@@ -828,8 +833,11 @@ class LocalExecutor:
         environment.pop("PARITY_SHARD", None)
         if shard:
             environment["PARITY_SHARD"] = shard
+        # stdin from /dev/null: tools/parity_shim.py never reuses an oracle run that reads a pipe, and CI runners
+        # (and --worker's ssh) give the runner one, which kept oracle reuse off on CI.
         process = subprocess.Popen([sys.executable, str(Path(__file__)), "--trace", str(trace), str(script)],
-                                   cwd=ROOT, env=environment, stdout=log, stderr=subprocess.STDOUT, start_new_session=True)
+                                   cwd=ROOT, env=environment, stdin=subprocess.DEVNULL, stdout=log,
+                                   stderr=subprocess.STDOUT, start_new_session=True)
         self.running[name] = {"process": process, "started": time.monotonic(), "log": log, "expected": expected,
                               "slot": slot, "script": script}
         return True
diff --git a/tools/test_collision_parity.py b/tools/test_collision_parity.py
index ad99ab960..26f7f25df 100644
--- a/tools/test_collision_parity.py
+++ b/tools/test_collision_parity.py
@@ -5,6 +5,7 @@ import json
 import os
 from pathlib import Path
 import platform
+import shutil
 import subprocess
 import tempfile
 
@@ -37,6 +38,8 @@ def main():
     if args.prepare:
         lab.prepare()
     lock, jars, libraries = test_rust_parity.verify_artifacts()
+    for earlier in directory.glob("run-*"):  # one run per run used to stay behind: 5 GB here after a few weeks
+        shutil.rmtree(earlier, ignore_errors=True)
     base = Path(tempfile.mkdtemp(prefix="run-", dir=directory))
     oracle = lab.ROOT / "mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCollisionOracle.java"
     sources = [oracle, Path(__file__).resolve(), lab.ROOT / "tools/test_rust_parity.py", lab.ROOT / "Cargo.toml", lab.ROOT / "Cargo.lock", lab.ROOT / "crates/horizon-core/Cargo.toml", lab.ROOT / "crates/horizon-world/Cargo.toml", *sorted((lab.ROOT / "crates/horizon-core/src").rglob("*.rs")), *sorted((lab.ROOT / "crates/horizon-world/src").rglob("*.rs")), lab.ROOT / "crates/horizon-world/examples/probe/collision_fixture.rs"]
diff --git a/tools/test_geometry_parity.py b/tools/test_geometry_parity.py
index 54ebc21ae..fa58bf66f 100644
--- a/tools/test_geometry_parity.py
+++ b/tools/test_geometry_parity.py
@@ -9,6 +9,7 @@ from pathlib import Path
 import platform
 import random
 import struct
+import shutil
 import subprocess
 import tempfile
 
@@ -273,6 +274,8 @@ def main():
     if args.prepare:
         lab.prepare()
     lock, jars, libraries = test_rust_parity.verify_artifacts()
+    for earlier in directory.glob("run-*"):  # one run per run used to stay behind: 5 GB here after a few weeks
+        shutil.rmtree(earlier, ignore_errors=True)
     base = Path(tempfile.mkdtemp(prefix="run-", dir=directory))
     commands = list(corpus())
     inputs = base / "inputs.txt"
diff --git a/tools/test_world_parity.py b/tools/test_world_parity.py
index 0b4a3deb7..9344a47b0 100644
--- a/tools/test_world_parity.py
+++ b/tools/test_world_parity.py
@@ -5,6 +5,7 @@ import json
 import os
 from pathlib import Path
 import platform
+import shutil
 import subprocess
 import tempfile
 
@@ -35,6 +36,8 @@ def main():
     if args.prepare:
         lab.prepare()
     lock, jars, libraries = test_rust_parity.verify_artifacts()
+    for earlier in directory.glob("run-*"):  # one run per run used to stay behind: 5 GB here after a few weeks
+        shutil.rmtree(earlier, ignore_errors=True)
     base = Path(tempfile.mkdtemp(prefix="run-", dir=directory))
     classes = base / "classes"
     classes.mkdir()

From 1dd47581de0fece92a193888e0a9518632edc787 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 00:59:15 +0100
Subject: [PATCH 236/270] Ring search thread: the idle class, not behind the
 server

On a 4-thread laptop the background search at nice +10 took a share of the
cores from the chunk workers: 600 chunks arrived 3-4 s later. The thread now
runs only on cores nothing else wants (Linux SCHED_IDLE, macOS background
QoS, Windows idle priority): horizon_threads::idle_current.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/vanillagen.rs | 12 +++---
 crates/horizon-threads/src/lib.rs       | 54 +++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/crates/horizon-client/src/vanillagen.rs b/crates/horizon-client/src/vanillagen.rs
index 046de6551..7623d720f 100644
--- a/crates/horizon-client/src/vanillagen.rs
+++ b/crates/horizon-client/src/vanillagen.rs
@@ -279,17 +279,17 @@ impl VanillaTerrain {
         let worker = worker.get_or_insert_with(|| self.generator.worker());
         worker.ring_positions(set)
     }
-    /// Searches the concentric rings on a thread of their own, behind the
-    /// server and render threads, as vanilla's background executor does:
-    /// the first chunks don't wait for them, and an eye of ender thrown
-    /// later finds them ready. A chunk or a query that needs them first
-    /// shares the remaining searches with this thread.
+    /// Searches the concentric rings on a thread of their own, as vanilla's
+    /// background executor does, in the idle class: on a few cores it would
+    /// otherwise slow the first chunks, which don't need the rings. An eye
+    /// of ender thrown later finds them ready, and a chunk or a query that
+    /// needs them first shares the remaining searches with this thread.
     pub fn search_rings_behind(self: &Arc<Self>) {
         let terrain = Arc::clone(self);
         let spawned = std::thread::Builder::new()
             .name("Ring search".into())
             .spawn(move || {
-                horizon_threads::behind_server();
+                horizon_threads::idle_current();
                 let _ = terrain
                     .generator
                     .worker()
diff --git a/crates/horizon-threads/src/lib.rs b/crates/horizon-threads/src/lib.rs
index ae4cc753f..27ee32cc4 100644
--- a/crates/horizon-threads/src/lib.rs
+++ b/crates/horizon-threads/src/lib.rs
@@ -90,6 +90,42 @@ fn behind() -> bool {
     false
 }
 
+/// Run the calling thread only on a core nothing else wants: work that may
+/// take seconds and that nothing waits for yet (the stronghold rings while a
+/// world opens). The idle class on Linux, background quality of service on
+/// macOS, idle priority on Windows. Whether the OS took it.
+pub fn idle_current() -> bool {
+    idle()
+}
+
+#[cfg(target_os = "linux")]
+fn idle() -> bool {
+    let param = libc::sched_param { sched_priority: 0 };
+    // SAFETY: sets the calling thread's own policy (pid 0); `param` lives
+    // across the call.
+    unsafe { libc::sched_setscheduler(0, libc::SCHED_IDLE, &param) == 0 }
+}
+
+#[cfg(target_vendor = "apple")]
+fn idle() -> bool {
+    // SAFETY: sets the calling thread's own QoS class; no pointers.
+    unsafe { libc::pthread_set_qos_class_self_np(libc::qos_class_t::QOS_CLASS_BACKGROUND, 0) == 0 }
+}
+
+#[cfg(windows)]
+fn idle() -> bool {
+    use windows_sys::Win32::System::Threading::{
+        GetCurrentThread, SetThreadPriority, THREAD_PRIORITY_IDLE,
+    };
+    // SAFETY: GetCurrentThread's pseudo handle needs no closing.
+    unsafe { SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_IDLE) != 0 }
+}
+
+#[cfg(not(any(target_os = "linux", target_vendor = "apple", windows)))]
+fn idle() -> bool {
+    false
+}
+
 #[cfg(test)]
 mod tests {
     /// The hint holds on the platforms that take it.
@@ -145,4 +181,22 @@ mod tests {
         #[cfg(not(target_os = "linux"))]
         assert!(!std::thread::spawn(super::behind_server).join().unwrap());
     }
+
+    /// The idle hint holds on the three platforms.
+    #[test]
+    fn idling_a_thread_takes() {
+        let took = std::thread::spawn(super::idle_current).join().unwrap();
+        assert_eq!(
+            took,
+            cfg!(any(target_os = "linux", target_vendor = "apple", windows))
+        );
+        #[cfg(target_os = "linux")]
+        std::thread::spawn(|| {
+            assert!(super::idle_current());
+            // SAFETY: reads the calling thread's own policy.
+            assert_eq!(unsafe { libc::sched_getscheduler(0) }, libc::SCHED_IDLE);
+        })
+        .join()
+        .unwrap();
+    }
 }

From 8b26c4cf348e48ccf9d47acdb08984665ed45a84 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:14:39 +0100
Subject: [PATCH 237/270] Ring search thread: start once generation pauses

In the idle class the thread still slowed a fresh world's first 600 chunks
by about 3 s on a 4-thread laptop (it shares a physical core with a worker).
It now waits until no proto chunk was generated for 2 s, or a minute after
the world opened, and gives up if the world closes first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/vanillagen.rs | 47 ++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/vanillagen.rs b/crates/horizon-client/src/vanillagen.rs
index 7623d720f..c890213c5 100644
--- a/crates/horizon-client/src/vanillagen.rs
+++ b/crates/horizon-client/src/vanillagen.rs
@@ -41,6 +41,10 @@ pub struct VanillaTerrain {
     tick_states: Vec<u32>,
     seed: i64,
     dimension: String,
+    /// When the last proto chunk was generated, in milliseconds since
+    /// `created`: the ring search waits for a pause in generation.
+    last_proto: std::sync::atomic::AtomicU64,
+    created: std::time::Instant,
 }
 /// A proto chunk, or the position of one whose generation failed.
 enum VanillaProto {
@@ -139,6 +143,8 @@ impl VanillaTerrain {
             tick_states,
             seed,
             dimension: dimension.to_owned(),
+            last_proto: std::sync::atomic::AtomicU64::new(0),
+            created: std::time::Instant::now(),
         })
     }
     /// A proto chunk's blocks, biomes, scheduled ticks and post-processing
@@ -280,25 +286,46 @@ impl VanillaTerrain {
         worker.ring_positions(set)
     }
     /// Searches the concentric rings on a thread of their own, as vanilla's
-    /// background executor does, in the idle class: on a few cores it would
-    /// otherwise slow the first chunks, which don't need the rings. An eye
-    /// of ender thrown later finds them ready, and a chunk or a query that
+    /// background executor does, once generation pauses for two seconds
+    /// (at the latest a minute after the world opens) and in the idle
+    /// class: on a laptop's few cores, sharing them with the first chunks,
+    /// which don't need the rings, made those 3 s slower. An eye of ender
+    /// thrown later finds the rings ready, and a chunk or a query that
     /// needs them first shares the remaining searches with this thread.
     pub fn search_rings_behind(self: &Arc<Self>) {
-        let terrain = Arc::clone(self);
+        const QUIET: u64 = 2_000;
+        const LATEST: u64 = 60_000;
+        let terrain = Arc::downgrade(self);
         let spawned = std::thread::Builder::new()
             .name("Ring search".into())
             .spawn(move || {
                 horizon_threads::idle_current();
-                let _ = terrain
-                    .generator
-                    .worker()
-                    .ring_positions("minecraft:strongholds");
+                loop {
+                    std::thread::sleep(std::time::Duration::from_millis(500));
+                    // The world closed: nothing to search for.
+                    let Some(terrain) = terrain.upgrade() else {
+                        return;
+                    };
+                    let now = terrain.elapsed_ms();
+                    let last = terrain
+                        .last_proto
+                        .load(std::sync::atomic::Ordering::Relaxed);
+                    if now >= LATEST || (last > 0 && now - last >= QUIET) {
+                        let _ = terrain
+                            .generator
+                            .worker()
+                            .ring_positions("minecraft:strongholds");
+                        return;
+                    }
+                }
             });
         if let Err(e) = spawned {
             log::warn!("ring search thread: {e}");
         }
     }
+    fn elapsed_ms(&self) -> u64 {
+        u64::try_from(self.created.elapsed().as_millis()).unwrap_or(u64::MAX)
+    }
 }
 /// The worldgen bundle at `dir`, loaded once and shared by every generator
 /// and by live feature placement (sapling growth, bone meal).
@@ -346,6 +373,10 @@ impl ChunkGenerator for VanillaTerrain {
         }
     }
     fn proto(&self, worker: &mut GeneratorWorker, x: i32, z: i32) -> Proto {
+        self.last_proto.store(
+            self.elapsed_ms().max(1),
+            std::sync::atomic::Ordering::Relaxed,
+        );
         match worker.generate_proto(ChunkPos::new(x, z)) {
             Ok(chunk) => Box::new(VanillaProto::Ready(Box::new(chunk))),
             Err(e) => {

From 045bda8bfcb53c332af600d359fb662ac87ce0f3 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:21:20 +0100
Subject: [PATCH 238/270] release: give the exporters job an hour, as the Mac
 builds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 52eef26da..5d9801a32 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -82,7 +82,8 @@ jobs:
     if: needs.decide.outputs.release == 'true'
     # This runner holds the maintainer's own pinned Minecraft jars. Only our classes leave it.
     runs-on: ${{ vars.MAC_RUNNER || 'ludovics-mac-mini' }}
-    timeout-minutes: 30
+    # Three full preparations (two isolated, one batched) besides the compile.
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4
         with:

From 9db6a0ee48a6862df8e27fe0e5cb587a61c67e0f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:23:27 +0100
Subject: [PATCH 239/270] CI: parity-main stays on the Mac; heat check on a
 median, boot as the first sign; nix roots fixed

nix-build names a dev output's GC root <name>-dev, so the runner's PKG_CONFIG_PATH pointed at links
that didn't exist and every client build failed on libudev; it now uses the store path nix-build
prints. The package temperature spikes for a second under load, so the heat check takes the median
of 5 readings. Restarting the watcher no longer throttles a running job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity-main.yml |  4 +++-
 docs/release-flow.md              |  5 +++--
 tools/ci/linux-runner.sh          |  5 +++--
 tools/ci/runner_pause.py          | 26 ++++++++++++++++----------
 4 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/parity-main.yml b/.github/workflows/parity-main.yml
index 1ddfb24bb..1debcc694 100644
--- a/.github/workflows/parity-main.yml
+++ b/.github/workflows/parity-main.yml
@@ -23,7 +23,9 @@ env:
 
 jobs:
   parity-main:
-    runs-on: [self-hosted, horizon-game]
+    # The Mac mini's runners only: a desktop job slowed down because the maintainer came back could time out, and a
+    # failure here bisects and comments on merges.
+    runs-on: [self-hosted, horizon-game, macOS]
     timeout-minutes: 240  # a core-crate batch reruns ~300 harnesses (~60-90 min), a bisect a few rounds of the failures
     steps:
       - uses: actions/checkout@v4
diff --git a/docs/release-flow.md b/docs/release-flow.md
index 28d1feef9..dc96498a0 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -90,8 +90,9 @@ processes, fleet-load's own detection, or a process outside the CI slice using t
 under way is throttled to 2 threads at the lowest weight and the runner stops after it: freezing the job would make
 GitHub drop it as lost and the harnesses time out. Old pull requests' `runner-env.sh` know only the Mac: the
 runner's `.env` and `.path` give their jobs Python, the JDK and the vanilla data (`HORIZON_SHARED_SOURCE`) all the
-same. The nightly audit stays on the Mac mini's runners, so its comparison with the previous night is always made
-on one platform.
+same. The nightly audit and parity-main stay on the Mac mini's runners: the audit compares with the previous night,
+so it stays on one platform, and a parity-main job slowed down on the desktop because he came back could time out,
+and its failures bisect and comment on merges.
 
 ## Merging
 
diff --git a/tools/ci/linux-runner.sh b/tools/ci/linux-runner.sh
index 1bd587e79..c7235f5c1 100755
--- a/tools/ci/linux-runner.sh
+++ b/tools/ci/linux-runner.sh
@@ -24,8 +24,9 @@ version=2.338.0
 sha=af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32
 here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 
-# Nix packages the jobs need, kept alive by GC roots in $dir/nix.
-nix_out() { nix-build '<nixpkgs>' -A "$1" -o "$dir/nix/$2" > /dev/null && readlink -f "$dir/nix/$2"; }
+# Nix packages the jobs need, kept alive by GC roots in $dir/nix. nix-build prints the store path; the root's name
+# gets the output's suffix (alsa-dev-dev for alsa-lib.dev), so it is not read back from the link.
+nix_out() { nix-build '<nixpkgs>' -A "$1" -o "$dir/nix/$2" | tail -1; }
 
 # The runner is a .NET program: on NixOS its native libraries (libstdc++, ICU, OpenSSL) come from nix-ld.
 export LD_LIBRARY_PATH=/run/current-system/sw/share/nix-ld/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
diff --git a/tools/ci/runner_pause.py b/tools/ci/runner_pause.py
index 35476a0b2..8fa0a4c5b 100755
--- a/tools/ci/runner_pause.py
+++ b/tools/ci/runner_pause.py
@@ -5,7 +5,7 @@ The runner works while nobody uses the machine: its screen locked, or untouched
 It pauses when any of these holds:
   - keyboard, mouse or gamepad input in the last INPUT_PAUSE seconds (60), or an unlocked session on seat0 with
     input in the last IDLE_AFTER seconds;
-  - the CPU package at TEMP_LIMIT °C (90) or more;
+  - the CPU package at TEMP_LIMIT °C (90) or more (the median of 5 readings);
   - fleet-load says a game runs (~/fleet/load: Steam, gamescope, Wine or Proton processes);
   - a process of his matches GAME below (the same, plus Minecraft and a Horizon game he started himself);
   - a process outside horizon-ci.slice keeps the GPU busy (nvidia-smi: SM use >= GPU_BUSY %, default 50, in two
@@ -63,7 +63,7 @@ class Input:
 
     def __init__(self):
         self.devices = {}  # path -> file descriptor
-        self.last = time.monotonic()  # a start counts as input: nothing is known yet
+        self.last = 0.0  # the boot (the monotonic clock's zero on Linux) counts as input
 
     def poll(self):
         try:
@@ -115,14 +115,20 @@ def at_the_screen(input_idle):
 
 
 def too_hot():
-    """The CPU package above TEMP_LIMIT °C (coretemp or k10temp)."""
+    """The CPU package at TEMP_LIMIT °C or more (coretemp or k10temp), as the median of 5 readings over 2 s: under
+    load it jumps for a second at a time (to 96 °C on ludodesktop at a median of 68 °C), which is no reason to stop."""
     for monitor in Path("/sys/class/hwmon").glob("hwmon*"):
         try:
-            if (monitor / "name").read_text().strip() in ("coretemp", "k10temp"):
-                celsius = int((monitor / "temp1_input").read_text()) / 1000
-                return f"CPU at {celsius:.0f} °C" if celsius >= TEMP_LIMIT else None
+            if (monitor / "name").read_text().strip() not in ("coretemp", "k10temp"):
+                continue
+            readings = []
+            for _ in range(5):
+                readings.append(int((monitor / "temp1_input").read_text()) / 1000)
+                time.sleep(0.5)
         except (OSError, ValueError):
-            pass
+            continue
+        celsius = sorted(readings)[2]
+        return f"CPU at {celsius:.0f} °C" if celsius >= TEMP_LIMIT else None
     return None
 
 
@@ -219,9 +225,9 @@ def pause_reason(hot, keys):
 
 def main():
     hot, keys = {}, Input()
-    # A boot (or a restart of this watcher) counts as a sign: the runner starts RESUME_AFTER seconds later at the
-    # earliest, which leaves time to log in after switching the machine on.
-    last_sign = time.monotonic()
+    # The boot counts as a sign: the runner starts RESUME_AFTER seconds after it at the earliest, which leaves time
+    # to log in after switching the machine on. Restarting this watcher later changes nothing for a running job.
+    last_sign = 0.0
     paused = None
     while True:
         reason = pause_reason(hot, keys)

From bdbf67ef9399a05e741c64c85e46e98fec69964e Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:31:38 +0100
Subject: [PATCH 240/270] pr_ready: work out the affected harnesses once, not
 once per harness

affected_here called parity.affected_harnesses inside the filter, once for
each of the 343 harnesses. Since the selection reads the Rust items each
probe reaches (#1964) one call takes about a minute and a half, so
pr_ready sat for hours before its first step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/pr_ready.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/pr_ready.py b/tools/pr_ready.py
index 505de28c1..4a3da6bae 100755
--- a/tools/pr_ready.py
+++ b/tools/pr_ready.py
@@ -164,7 +164,8 @@ def affected_here(changed):
                 (parity.SHARED / "dependencies" / f"{name}.json").exists() for name in found)
     if not known and not changed & parity.SHARED_INPUTS:
         return None
-    return harness_names(name for name in found if name in parity.affected_harnesses(found, records, changed))
+    affected = parity.affected_harnesses(found, records, changed)
+    return harness_names(name for name in found if name in affected)
 
 
 def short_list(names, limit=12):

From 49bbdf8954bdc8958bc6f8a2e7917bb8035f710c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:38:23 +0100
Subject: [PATCH 241/270] CI: the desktop's CI slice gets half the threads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On all 24, a cargo build held ludodesktop's CPU at 92 °C and the watcher kept pausing; at half,
harnesses run at a median of 80 °C.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/ci/linux-runner.sh | 1 +
 tools/ci/runner_pause.py | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/tools/ci/linux-runner.sh b/tools/ci/linux-runner.sh
index c7235f5c1..699742bf1 100755
--- a/tools/ci/linux-runner.sh
+++ b/tools/ci/linux-runner.sh
@@ -131,6 +131,7 @@ Description=Horizon CI: the runner's jobs and parity workers sent from other mac
 [Slice]
 CPUWeight=20
 IOWeight=20
+CPUQuota=$(( threads * 50 ))%
 MemoryHigh=$(( $(awk '/MemTotal/ {print int($2 / 1048576)}' /proc/meminfo) / 2 ))G
 MemoryMax=$(( $(awk '/MemTotal/ {print int($2 / 1048576)}' /proc/meminfo) * 2 / 3 ))G
 EOF
diff --git a/tools/ci/runner_pause.py b/tools/ci/runner_pause.py
index 8fa0a4c5b..845627243 100755
--- a/tools/ci/runner_pause.py
+++ b/tools/ci/runner_pause.py
@@ -36,6 +36,8 @@ GPU_BUSY = int(os.environ.get("GPU_BUSY", 50))
 INTERVAL = int(os.environ.get("INTERVAL", 15))
 RESUME_AFTER = int(os.environ.get("RESUME_AFTER", 300))
 THROTTLE_CPUS = int(os.environ.get("THROTTLE_CPUS", 2))
+# Working, the slice gets half the threads: on all of them ludodesktop's CPU sits at 92 °C through a cargo build.
+NORMAL_CPUS = int(os.environ.get("NORMAL_CPUS", max(1, (os.cpu_count() or 2) // 2)))
 INPUT_PAUSE = int(os.environ.get("INPUT_PAUSE", 60))
 IDLE_AFTER = int(os.environ.get("IDLE_AFTER", 900))
 TEMP_LIMIT = int(os.environ.get("TEMP_LIMIT", 90))
@@ -199,7 +201,7 @@ def throttle(on):
     if on:
         systemctl("set-property", "--runtime", SLICE, "CPUWeight=1", "IOWeight=1", f"CPUQuota={THROTTLE_CPUS * 100}%")
     else:
-        systemctl("set-property", "--runtime", SLICE, "CPUWeight=20", "IOWeight=20", "CPUQuota=")
+        systemctl("set-property", "--runtime", SLICE, "CPUWeight=20", "IOWeight=20", f"CPUQuota={NORMAL_CPUS * 100}%")
 
 
 def pause_reason(hot, keys):

From 22980fc8ccab18df7e3f9eacb5419d211e30adc6 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:41:18 +0100
Subject: [PATCH 242/270] Extras: the FPS counter and keystrokes move to the
 mod browser

They are official mods now (#1982). The Extras page loses their rows and
the HUD its built-in drawing. A player who had one on gets the mod on the
first start: installed from Horizon's registry, checked as the launcher
checks it (size, SHA-256, signature, manifest), turned on, with the
corner and options carried into the mod's storage. One chat line says so
("FPS counter moved to the mod browser: installed for you"). If it can't
be installed (offline), a line says Horizon tries again at the next
start. horizon-extras.txt keeps the old keys and lists what was done in
movedToMods.

The client's horizon-mods dependency gains the `index` feature for the
check. The frame and click counters now run only for mods.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/Cargo.toml              |   2 +-
 crates/horizon-client/src/extras.rs           |  73 ++----
 crates/horizon-client/src/extras_hud.rs       | 136 +----------
 crates/horizon-client/src/game.rs             |   3 +
 crates/horizon-client/src/game/extras.rs      |  50 +---
 crates/horizon-client/src/game/mods.rs        |   3 +
 .../horizon-client/src/game/moved_extras.rs   | 115 ++++++++++
 crates/horizon-client/src/lib.rs              |   1 +
 crates/horizon-client/src/moved_extras.rs     | 214 ++++++++++++++++++
 docs/extras.md                                |  29 ++-
 10 files changed, 390 insertions(+), 236 deletions(-)
 create mode 100644 crates/horizon-client/src/game/moved_extras.rs
 create mode 100644 crates/horizon-client/src/moved_extras.rs

diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml
index ea5859c23..63acb45e3 100644
--- a/crates/horizon-client/Cargo.toml
+++ b/crates/horizon-client/Cargo.toml
@@ -21,7 +21,7 @@ horizon-shaders = { path = "../horizon-shaders" }
 horizon-friends = { path = "../horizon-friends" }
 # Horizon mods: sandboxed WebAssembly components, off unless installed and turned on (docs/mods.md).
 # Their runtime is the `mods` feature.
-horizon-mods = { path = "../horizon-mods", default-features = false }
+horizon-mods = { path = "../horizon-mods", default-features = false, features = ["index"] }
 wgpu = { version = "30.0.1", default-features = false, features = ["std", "parking_lot", "vulkan", "metal", "wgsl", "naga-ir"] }
 winit = "0.30.13"
 pollster = "0.4"
diff --git a/crates/horizon-client/src/extras.rs b/crates/horizon-client/src/extras.rs
index 40e87214e..c8683bb92 100644
--- a/crates/horizon-client/src/extras.rs
+++ b/crates/horizon-client/src/extras.rs
@@ -81,6 +81,9 @@ pub struct Extras {
     pub zoom_smooth: bool,
     /// Divide mouse turning by the zoom.
     pub zoom_sensitivity: bool,
+    /// The FPS counter and keystrokes extras are official mods now
+    /// (`moved_extras`): their old settings stay here until the game has
+    /// installed the mod for a player who had one on.
     pub fps: bool,
     pub fps_corner: Corner,
     /// Also show the minimum and 1% low.
@@ -89,6 +92,9 @@ pub struct Extras {
     pub keystrokes_corner: Corner,
     /// Clicks per second under the mouse buttons.
     pub keystrokes_cps: bool,
+    /// The official mods installed for the extras they replace, by mod id
+    /// (`movedToMods`): each is done once.
+    pub moved: Vec<String>,
     pub minimap: bool,
     pub minimap_corner: Corner,
     /// Side in GUI pixels (`MINIMAP_SIZES`).
@@ -132,6 +138,7 @@ impl Default for Extras {
             keystrokes: false,
             keystrokes_corner: Corner::TopLeft,
             keystrokes_cps: true,
+            moved: Vec::new(),
             minimap: false,
             minimap_corner: Corner::TopRight,
             minimap_size: 96,
@@ -190,6 +197,14 @@ impl Extras {
                     e.keystrokes_corner = Corner::parse(value, e.keystrokes_corner)
                 }
                 "keystrokesCps" => e.keystrokes_cps = flag(e.keystrokes_cps),
+                "movedToMods" => {
+                    e.moved = value
+                        .split(',')
+                        .map(str::trim)
+                        .filter(|id| !id.is_empty())
+                        .map(str::to_owned)
+                        .collect()
+                }
                 "minimap" => e.minimap = flag(e.minimap),
                 "minimapCorner" => e.minimap_corner = Corner::parse(value, e.minimap_corner),
                 "minimapSize" => {
@@ -219,7 +234,7 @@ impl Extras {
     }
     pub fn serialize(&self) -> String {
         format!(
-            "fullbright:{}\ndynamicLights:{}\nzoom:{}\nzoomKey:{}\nzoomLevel:{}\nzoomSmooth:{}\nzoomSensitivity:{}\nfps:{}\nfpsCorner:{}\nfpsLows:{}\nkeystrokes:{}\nkeystrokesCorner:{}\nkeystrokesCps:{}\nminimap:{}\nminimapCorner:{}\nminimapSize:{}\nminimapShape:{}\nminimapZoom:{}\nminimapRotate:{}\nautoReconnect:{}\nmouseTweaks:{}\nmouseTweaksWheel:{}\nsort:{}\nsortKey:{}\n{}:{}\nagentControl:{}\ndiscordPresence:{}\n",
+            "fullbright:{}\ndynamicLights:{}\nzoom:{}\nzoomKey:{}\nzoomLevel:{}\nzoomSmooth:{}\nzoomSensitivity:{}\nfps:{}\nfpsCorner:{}\nfpsLows:{}\nkeystrokes:{}\nkeystrokesCorner:{}\nkeystrokesCps:{}\nmovedToMods:{}\nminimap:{}\nminimapCorner:{}\nminimapSize:{}\nminimapShape:{}\nminimapZoom:{}\nminimapRotate:{}\nautoReconnect:{}\nmouseTweaks:{}\nmouseTweaksWheel:{}\nsort:{}\nsortKey:{}\n{}:{}\nagentControl:{}\ndiscordPresence:{}\n",
             bool_text(self.fullbright),
             bool_text(self.dynamic_lights),
             bool_text(self.zoom),
@@ -233,6 +248,7 @@ impl Extras {
             bool_text(self.keystrokes),
             self.keystrokes_corner.name(),
             bool_text(self.keystrokes_cps),
+            self.moved.join(","),
             bool_text(self.minimap),
             self.minimap_corner.name(),
             self.minimap_size,
@@ -452,12 +468,6 @@ pub enum Item {
     ZoomLevel,
     ZoomSmooth,
     ZoomSensitivity,
-    Fps,
-    FpsCorner,
-    FpsLows,
-    Keystrokes,
-    KeystrokesCorner,
-    KeystrokesCps,
     Minimap,
     MinimapCorner,
     MinimapSize,
@@ -495,14 +505,6 @@ pub fn rows() -> Vec<Result<Item, &'static str>> {
         Ok(MinimapShape),
         Ok(MinimapZoom),
         Ok(MinimapRotate),
-        Err("FPS counter"),
-        Ok(Fps),
-        Ok(FpsCorner),
-        Ok(FpsLows),
-        Err("Keystrokes"),
-        Ok(Keystrokes),
-        Ok(KeystrokesCorner),
-        Ok(KeystrokesCps),
         Err("Inventory"),
         Ok(MouseTweaks),
         Ok(MouseTweaksWheel),
@@ -537,8 +539,7 @@ impl Item {
             Item::ZoomLevel => "Starting zoom",
             Item::ZoomSmooth => "Smooth zoom",
             Item::ZoomSensitivity => "Slower turning",
-            Item::Fps => "FPS counter",
-            Item::FpsCorner | Item::KeystrokesCorner | Item::MinimapCorner => "Corner",
+            Item::MinimapCorner => "Corner",
             Item::Minimap => "Minimap",
             Item::MinimapSize => "Size",
             Item::MinimapShape => "Shape",
@@ -549,9 +550,6 @@ impl Item {
             Item::MouseTweaksWheel => "Scroll wheel moves items",
             Item::Sort => "Sort buttons",
             Item::SortKey => "Sort key",
-            Item::FpsLows => "Minimum and 1% low",
-            Item::Keystrokes => "Keystrokes",
-            Item::KeystrokesCps => "Clicks per second",
             Item::NoAi => "No AI",
             Item::AgentControl => "Agent Control",
             Item::DiscordPresence => "Discord Rich Presence",
@@ -563,12 +561,10 @@ impl Item {
         Some(match self {
             ZoomKey | ZoomLevel | ZoomSmooth | ZoomSensitivity => Zoom,
             MinimapCorner | MinimapSize | MinimapShape | MinimapZoom | MinimapRotate => Minimap,
-            FpsCorner | FpsLows => Fps,
-            KeystrokesCorner | KeystrokesCps => Keystrokes,
             MouseTweaksWheel => MouseTweaks,
             SortKey => Sort,
-            Fullbright | DynamicLights | Zoom | Minimap | Fps | Keystrokes | MouseTweaks | Sort
-            | AutoReconnect | NoAi | AgentControl | DiscordPresence => {
+            Fullbright | DynamicLights | Zoom | Minimap | MouseTweaks | Sort | AutoReconnect
+            | NoAi | AgentControl | DiscordPresence => {
                 return None;
             }
         })
@@ -585,10 +581,7 @@ impl Item {
             Item::ZoomLevel => "The zoom the key starts at.",
             Item::ZoomSmooth => "Eases in and out like the spyglass.",
             Item::ZoomSensitivity => "Turns slower the more you zoom in.",
-            Item::Fps => "Frames per second in a corner of the screen.",
-            Item::FpsCorner | Item::KeystrokesCorner | Item::MinimapCorner => {
-                "Overlays in one corner stack."
-            }
+            Item::MinimapCorner => "Overlays in one corner stack.",
             Item::Minimap => "A map of the loaded terrain around you, in map colours.",
             Item::MinimapSize => "How big the map is on screen.",
             Item::MinimapShape => "Square or round.",
@@ -597,7 +590,6 @@ impl Item {
             Item::AutoReconnect => {
                 "Rejoins a server after a lost connection or a restart, never after a kick or ban."
             }
-            Item::FpsLows => "The slowest frame and the 1% low of the last 5 seconds.",
             Item::MouseTweaks => {
                 "Right-drag places one per slot, left-drag gathers the held item, Shift + left-drag moves every slot."
             }
@@ -610,8 +602,6 @@ impl Item {
             Item::SortKey => {
                 "Sorts the part under the cursor. Click, then press a key; Escape unbinds it."
             }
-            Item::Keystrokes => "Movement keys, jump and mouse buttons as you press them.",
-            Item::KeystrokesCps => "Clicks in the last second under each mouse button.",
             Item::NoAi => {
                 "Hides and turns off every AI feature: agent control, horizon-ctl and the MCP servers. The launcher's switch too."
             }
@@ -627,7 +617,7 @@ impl Item {
     pub fn cost(self) -> Option<crate::graphics_style::Cost> {
         use crate::graphics_style::Cost;
         match self {
-            Item::Fullbright | Item::Zoom | Item::Fps | Item::Keystrokes => Some(Cost::None),
+            Item::Fullbright | Item::Zoom => Some(Cost::None),
             Item::Minimap | Item::DynamicLights => Some(Cost::Low),
             Item::AutoReconnect | Item::MouseTweaks | Item::Sort => Some(Cost::None),
             _ => None,
@@ -641,10 +631,6 @@ impl Item {
             Item::Zoom => e.zoom,
             Item::ZoomSmooth => e.zoom_smooth,
             Item::ZoomSensitivity => e.zoom_sensitivity,
-            Item::Fps => e.fps,
-            Item::FpsLows => e.fps_lows,
-            Item::Keystrokes => e.keystrokes,
-            Item::KeystrokesCps => e.keystrokes_cps,
             Item::Minimap => e.minimap,
             Item::MinimapRotate => e.minimap_rotate,
             Item::AutoReconnect => e.auto_reconnect,
@@ -663,8 +649,6 @@ impl Item {
             Item::ZoomKey => crate::keybinds::display_name(&e.zoom_key).plain(),
             Item::SortKey => crate::keybinds::display_name(&e.sort_key).plain(),
             Item::ZoomLevel => format!("{}x", e.zoom_level),
-            Item::FpsCorner => e.fps_corner.label().into(),
-            Item::KeystrokesCorner => e.keystrokes_corner.label().into(),
             Item::MinimapCorner => e.minimap_corner.label().into(),
             Item::MinimapSize => MINIMAP_SIZES
                 .iter()
@@ -687,15 +671,7 @@ impl Item {
             Item::Zoom => e.zoom = !e.zoom,
             Item::ZoomSmooth => e.zoom_smooth = !e.zoom_smooth,
             Item::ZoomSensitivity => e.zoom_sensitivity = !e.zoom_sensitivity,
-            Item::Fps => e.fps = !e.fps,
-            Item::FpsLows => e.fps_lows = !e.fps_lows,
-            Item::Keystrokes => e.keystrokes = !e.keystrokes,
-            Item::KeystrokesCps => e.keystrokes_cps = !e.keystrokes_cps,
             Item::ZoomLevel => e.zoom_level = next(&ZOOM_LEVELS, e.zoom_level, back),
-            Item::FpsCorner => e.fps_corner = next(&Corner::ALL, e.fps_corner, back),
-            Item::KeystrokesCorner => {
-                e.keystrokes_corner = next(&Corner::ALL, e.keystrokes_corner, back)
-            }
             Item::Minimap => e.minimap = !e.minimap,
             Item::MinimapRotate => e.minimap_rotate = !e.minimap_rotate,
             Item::AutoReconnect => e.auto_reconnect = !e.auto_reconnect,
@@ -750,6 +726,7 @@ mod tests {
         e.fps_corner = Corner::BottomRight;
         e.keystrokes = true;
         e.keystrokes_cps = false;
+        e.moved = vec!["fps_overlay".into(), "keystrokes".into()];
         e.minimap = true;
         e.minimap_size = 128;
         e.minimap_round = true;
@@ -942,8 +919,8 @@ mod tests {
         Item::ZoomLevel.cycle(&mut e, true);
         Item::ZoomLevel.cycle(&mut e, true);
         assert_eq!(e.zoom_level, 3);
-        Item::FpsCorner.cycle(&mut e, true);
-        assert_eq!(e.fps_corner, Corner::BottomRight);
+        Item::MinimapCorner.cycle(&mut e, true);
+        assert_eq!(e.minimap_corner, Corner::TopLeft);
         Item::Zoom.cycle(&mut e, false);
         assert_eq!(Item::Zoom.switch(&e), Some(true));
         assert_eq!(Item::ZoomKey.value(&e), "Z");
diff --git a/crates/horizon-client/src/extras_hud.rs b/crates/horizon-client/src/extras_hud.rs
index f6fc1ba12..cc26e15d4 100644
--- a/crates/horizon-client/src/extras_hud.rs
+++ b/crates/horizon-client/src/extras_hud.rs
@@ -1,7 +1,7 @@
-//! The extras' HUD overlays (FPS counter, keystrokes): small boxes in the
-//! vanilla font, in GUI pixels, stacked per corner (`docs/extras.md`).
+//! HUD boxes in the corners: the minimap's place and mods' panels, small
+//! boxes in GUI pixels stacked per corner (`docs/extras.md`).
 use crate::{
-    extras::{Corner, FpsReading},
+    extras::Corner,
     hud::{HudAtlas, HudBatch, Rect, rgba},
 };
 
@@ -99,36 +99,6 @@ pub fn draw_minimap(
     }
 }
 
-/// The FPS counter's text.
-pub fn fps_text(r: FpsReading, lows: bool) -> String {
-    if lows {
-        format!("{} fps  min {}  1% {}", r.fps, r.min, r.low)
-    } else {
-        format!("{} fps", r.fps)
-    }
-}
-pub fn draw_fps(
-    batch: &mut HudBatch,
-    atlas: &HudAtlas,
-    corners: &mut Corners,
-    corner: Corner,
-    reading: FpsReading,
-    lows: bool,
-) {
-    let text = fps_text(reading, lows);
-    let w = HudBatch::text_width(atlas, &text) + 4.0;
-    let (x, y) = corners.place(corner, w, 12.0);
-    batch.fill(atlas, x, y, w, 12.0, BACKGROUND);
-    batch.text(
-        atlas,
-        &text,
-        x + 2.0,
-        y + 2.0,
-        rgba(255, 255, 255, 255),
-        true,
-    );
-}
-
 /// A box of text lines (a mod's HUD panel): `(text, 0xRRGGBB)` each.
 pub fn draw_lines(
     batch: &mut HudBatch,
@@ -155,95 +125,6 @@ pub fn draw_lines(
     }
 }
 
-/// What the keystroke overlay shows.
-pub struct Keystrokes {
-    /// Forward, left, back, right: held, and the bound key's name.
-    pub moves: [(bool, String); 4],
-    pub jump: bool,
-    pub attack: bool,
-    pub use_: bool,
-    /// Clicks per second of the left and right buttons, when shown.
-    pub cps: Option<(usize, usize)>,
-}
-const KEY: f32 = 22.0;
-const GAP: f32 = 2.0;
-/// The overlay's size.
-pub fn keystrokes_size() -> (f32, f32) {
-    (3.0 * KEY + 2.0 * GAP, 3.0 * KEY + 3.0 * GAP + 10.0)
-}
-fn key_box(batch: &mut HudBatch, atlas: &HudAtlas, rect: [f32; 4], held: bool, lines: &[&str]) {
-    let [x, y, w, h] = rect;
-    let (fill, ink) = if held {
-        (rgba(255, 255, 255, 176), rgba(20, 20, 20, 255))
-    } else {
-        (BACKGROUND, rgba(255, 255, 255, 255))
-    };
-    batch.fill(atlas, x, y, w, h, fill);
-    let total = lines.len() as f32 * 9.0 - 1.0;
-    for (i, line) in lines.iter().enumerate() {
-        let tw = HudBatch::text_width(atlas, line);
-        let tx = (x + (w - tw) / 2.0).round();
-        let ty = (y + (h - total) / 2.0).round() + i as f32 * 9.0;
-        batch.text(atlas, line, tx, ty, ink, !held);
-    }
-}
-pub fn draw_keystrokes(
-    batch: &mut HudBatch,
-    atlas: &HudAtlas,
-    corners: &mut Corners,
-    corner: Corner,
-    k: &Keystrokes,
-) {
-    let (w, h) = keystrokes_size();
-    let (x, y) = corners.place(corner, w, h);
-    let step = KEY + GAP;
-    let [forward, left, back, right] = &k.moves;
-    key_box(
-        batch,
-        atlas,
-        [x + step, y, KEY, KEY],
-        forward.0,
-        &[&forward.1],
-    );
-    for (i, key) in [left, back, right].into_iter().enumerate() {
-        key_box(
-            batch,
-            atlas,
-            [x + i as f32 * step, y + step, KEY, KEY],
-            key.0,
-            &[&key.1],
-        );
-    }
-    let mw = (w - GAP) / 2.0;
-    let my = y + 2.0 * step;
-    for (i, (held, label, cps)) in [
-        (k.attack, "LMB", k.cps.map(|c| c.0)),
-        (k.use_, "RMB", k.cps.map(|c| c.1)),
-    ]
-    .into_iter()
-    .enumerate()
-    {
-        let rate = cps.map(|n| format!("{n} CPS"));
-        let lines: Vec<&str> = std::iter::once(label).chain(rate.as_deref()).collect();
-        key_box(
-            batch,
-            atlas,
-            [x + i as f32 * (mw + GAP), my, mw, KEY],
-            held,
-            &lines,
-        );
-    }
-    // The space bar: a line in a short key.
-    let sy = my + step;
-    key_box(batch, atlas, [x, sy, w, 10.0], k.jump, &[]);
-    let ink = if k.jump {
-        rgba(20, 20, 20, 255)
-    } else {
-        rgba(255, 255, 255, 255)
-    };
-    batch.fill(atlas, x + w / 2.0 - 12.0, sy + 4.0, 24.0, 2.0, ink);
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -259,15 +140,4 @@ mod tests {
         assert_eq!(c.place(Corner::BottomRight, 50.0, 10.0), (348.0, 274.0));
         assert_eq!(c.place(Corner::BottomLeft, 10.0, 10.0), (2.0, 288.0));
     }
-
-    #[test]
-    fn fps_text_with_and_without_lows() {
-        let r = FpsReading {
-            fps: 144,
-            min: 61,
-            low: 98,
-        };
-        assert_eq!(fps_text(r, false), "144 fps");
-        assert_eq!(fps_text(r, true), "144 fps  min 61  1% 98");
-    }
 }
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 5b04d8716..fb5260fbd 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -101,6 +101,7 @@ mod mod_render;
 mod mods;
 mod mount_menu;
 mod mounts;
+mod moved_extras;
 mod moving_pistons;
 mod music;
 mod names;
@@ -11482,6 +11483,7 @@ impl ApplicationHandler for Game<'_> {
                     }
                     self.extras_frame(elapsed);
                     self.mods_frame(elapsed);
+                    self.poll_moved_extras();
                     self.extras_retry()?;
                     self.apply_mouse_look();
                     self.pad_look(elapsed.as_secs_f32());
@@ -12809,6 +12811,7 @@ fn start_game<'a>(
     // Benchmarks measure the game alone.
     if game.options.benchmark.is_none() {
         game.mods.dev = game.options.dev_mods.clone();
+        game.start_moved_extras();
         game.start_mods();
     }
     game.start_agent_control()?;
diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index 4664f0c6f..0bcc72739 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -1,11 +1,11 @@
 //! Horizon's extras in the game (`docs/extras.md`): the zoom key and wheel,
-//! clicks for the keystroke overlay, frame times for the FPS counter, the
-//! minimap's tiles and image, and their HUD. Each hook does nothing while its
-//! extra is off.
+//! the minimap's tiles and image, and their HUD; clicks and frame times for
+//! mods (`input.clicks-per-second`, `render.frame-stats`). Each hook does
+//! nothing while its extra is off and no mod runs.
 use super::{Dim, Game, Screen};
 use horizon_client::{
     extras::{Corner, Cps, FpsCounter, Zoom, fov_target, turn_scale},
-    extras_hud::{self, Corners, Keystrokes},
+    extras_hud::{self, Corners},
     hud::{HudBatch, MINIMAP_SPRITE},
     keybinds,
     minimap::{self, Layer, Minimap, View},
@@ -70,8 +70,8 @@ impl Game<'_> {
             _ => return,
         };
         self.extras.mouse[i] = pressed;
-        // Mods read the clicks too (`input.clicks-per-second`).
-        if pressed && (self.settings.extras.keystrokes || self.mods.running()) {
+        // For mods (`input.clicks-per-second`).
+        if pressed && self.mods.running() {
             let now = self.extras_now();
             self.extras.cps[i].click(now);
         }
@@ -88,8 +88,8 @@ impl Game<'_> {
             self.extras.mouse = [false; 2];
         }
         self.update_minimap();
-        // Mods read the counter too (`render.frame-stats`).
-        if self.settings.extras.fps || self.mods.running() {
+        // For mods (`render.frame-stats`).
+        if self.mods.running() {
             let now = self.extras_now();
             self.extras.fps.record(now, elapsed.as_secs_f32() * 1000.0);
         } else {
@@ -249,16 +249,14 @@ impl Game<'_> {
     pub(super) fn zoom_turn_scale(&self) -> f64 {
         turn_scale(self.zoom_factor(), self.settings.extras.zoom_sensitivity)
     }
-    /// The FPS counter and keystrokes, in the HUD layer (hidden with F1 by
-    /// the caller). The top left corner gives way to the debug screen.
+    /// The minimap and mods' corner panels, in the HUD layer (hidden with F1
+    /// by the caller). The top left corner gives way to the debug screen.
     pub(super) fn draw_extras(&mut self, batch: &mut HudBatch) {
         let e = &self.settings.extras;
         let mod_panels = self.mods.has_panels();
-        if !e.fps && !e.keystrokes && !e.minimap && !mod_panels {
+        if !e.minimap && !mod_panels {
             return;
         }
-        let (fps_on, fps_corner, lows) = (e.fps, e.fps_corner, e.fps_lows);
-        let (keys_on, keys_corner, cps_on) = (e.keystrokes, e.keystrokes_corner, e.keystrokes_cps);
         let (map_corner, map_size) = (e.minimap_corner, f32::from(e.minimap_size));
         let visible = |corner| !(self.debug && corner == Corner::TopLeft);
         let mut corners = Corners::new(batch.width, batch.height, self.effect_rows_height());
@@ -282,32 +280,6 @@ impl Game<'_> {
             };
             extras_hud::draw_minimap(batch, atlas, &mut corners, &look);
         }
-        if fps_on && visible(fps_corner) {
-            let reading = self.extras.fps.reading();
-            extras_hud::draw_fps(batch, atlas, &mut corners, fps_corner, reading, lows);
-        }
-        if keys_on && visible(keys_corner) {
-            let now = self.extras_now();
-            let cps = cps_on.then(|| {
-                let [l, r] = &mut self.extras.cps;
-                (l.per_second(now), r.per_second(now))
-            });
-            let held = |k| self.keys.contains(&k);
-            let label = |name| keybinds::display_name(self.settings.keys.get(name)).plain();
-            let k = Keystrokes {
-                moves: [
-                    (held(KeyCode::KeyW), label("key.forward")),
-                    (held(KeyCode::KeyA), label("key.left")),
-                    (held(KeyCode::KeyS), label("key.back")),
-                    (held(KeyCode::KeyD), label("key.right")),
-                ],
-                jump: held(KeyCode::Space),
-                attack: self.extras.mouse[0],
-                use_: self.extras.mouse[1],
-                cps,
-            };
-            extras_hud::draw_keystrokes(batch, &self.gui.atlas, &mut corners, keys_corner, &k);
-        }
         if mod_panels {
             self.draw_mod_panels(batch, &mut corners);
         }
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 9d6015ad7..eb35c491f 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -55,6 +55,9 @@ pub(super) struct ModsState {
     /// The HUD font's advances for `render.text-width`, made once.
     #[cfg(feature = "mods")]
     font_widths: std::sync::Arc<[f32]>,
+    /// Extras that are official mods now, being installed.
+    #[cfg(feature = "mods")]
+    pub(super) moved: super::moved_extras::MovedState,
 }
 
 /// The mappings `input.mapping` answers for, with the default key their
diff --git a/crates/horizon-client/src/game/moved_extras.rs b/crates/horizon-client/src/game/moved_extras.rs
new file mode 100644
index 000000000..faeeea541
--- /dev/null
+++ b/crates/horizon-client/src/game/moved_extras.rs
@@ -0,0 +1,115 @@
+//! Extras that are official mods now (`horizon_client::moved_extras`): on
+//! the first start after the update, a player who had one on gets the mod
+//! installed from Horizon's registry, turned on, with their settings, and
+//! one line in the chat saying so. The download runs on its own thread; if
+//! it fails (offline), the game tries again at the next start.
+
+#[cfg(not(feature = "mods"))]
+impl super::Game<'_> {
+    pub(super) fn start_moved_extras(&mut self) {}
+    pub(super) fn poll_moved_extras(&mut self) {}
+}
+
+#[cfg(feature = "mods")]
+mod with_mods {
+    use super::super::Game;
+    use horizon_client::{
+        moved_extras::{self, Moved},
+        text::{self, Text},
+    };
+    use std::sync::mpsc::{Receiver, channel};
+
+    type Done = Vec<(&'static Moved, Result<(), String>)>;
+
+    #[derive(Default)]
+    pub(in crate::game) struct MovedState {
+        /// The installs under way.
+        running: Option<Receiver<Done>>,
+        /// Lines for the player, shown once a world is open.
+        notices: Vec<Text>,
+    }
+
+    impl Game<'_> {
+        /// At start: remembers the moved extras that were off, and installs
+        /// the ones that were on, in the background.
+        pub(in crate::game) fn start_moved_extras(&mut self) {
+            let off = moved_extras::nothing_to_do(&self.settings.extras);
+            let pending = moved_extras::pending(&self.settings.extras);
+            if off.is_empty() && pending.is_empty() {
+                return;
+            }
+            if !off.is_empty() {
+                let e = &mut self.settings.extras;
+                e.moved.extend(off.iter().map(|m| m.id.to_owned()));
+                self.settings.save(&Self::options_path());
+            }
+            if pending.is_empty() {
+                return;
+            }
+            let extras = self.settings.extras.clone();
+            let dir = Self::options_path()
+                .parent()
+                .map(std::path::Path::to_path_buf)
+                .unwrap_or_default();
+            let (tx, rx) = channel();
+            self.mods.moved.running = Some(rx);
+            let spawned = std::thread::Builder::new()
+                .name("Moved extras".into())
+                .spawn(move || {
+                    let done = match moved_extras::fetch_index() {
+                        Ok(index) => pending
+                            .into_iter()
+                            .map(|m| (m, moved_extras::install(&index, m, &extras, &dir)))
+                            .collect(),
+                        Err(e) => pending.into_iter().map(|m| (m, Err(e.clone()))).collect(),
+                    };
+                    let _ = tx.send(done);
+                });
+            if spawned.is_err() {
+                self.mods.moved.running = None;
+            }
+        }
+        /// Once a frame: the installs that finished turn their mods on;
+        /// their lines wait for a world.
+        pub(in crate::game) fn poll_moved_extras(&mut self) {
+            if let Some(rx) = &self.mods.moved.running
+                && let Ok(done) = rx.try_recv()
+            {
+                self.mods.moved.running = None;
+                let mut installed = false;
+                for (m, result) in done {
+                    match result {
+                        Ok(()) => {
+                            self.settings.extras.moved.push(m.id.to_owned());
+                            self.settings.mods.enabled.insert(m.id.to_owned());
+                            self.mods.moved.notices.push(Text::literal(m.notice()));
+                            installed = true;
+                        }
+                        Err(e) => {
+                            log::warn!("Horizon: {} not installed, next start retries: {e}", m.id);
+                            self.mods.moved.notices.push(
+                                Text::literal(format!(
+                                    "{} moved to the mod browser; it couldn't be installed for you yet, Horizon tries again at the next start",
+                                    m.name
+                                ))
+                                .with_color(text::GRAY),
+                            );
+                        }
+                    }
+                }
+                if installed {
+                    self.settings.save(&Self::options_path());
+                    self.start_mods();
+                }
+            }
+            if !self.mods.moved.notices.is_empty() && self.player.is_some() && self.title.is_none()
+            {
+                for line in std::mem::take(&mut self.mods.moved.notices) {
+                    self.system_message(line);
+                }
+            }
+        }
+    }
+}
+#[cfg(feature = "mods")]
+pub(super) use with_mods::MovedState;
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index ae95e1bdb..745052060 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -123,6 +123,7 @@ mod model_library;
 pub mod models;
 pub mod motion;
 pub mod mouse;
+pub mod moved_extras;
 pub mod multiplayer;
 pub mod music;
 pub mod nbt_path;
diff --git a/crates/horizon-client/src/moved_extras.rs b/crates/horizon-client/src/moved_extras.rs
new file mode 100644
index 000000000..659592d80
--- /dev/null
+++ b/crates/horizon-client/src/moved_extras.rs
@@ -0,0 +1,214 @@
+//! Extras that became official mods (docs/mods.md, "Horizon's official
+//! mods"). For a player who had one on, the game installs the mod from
+//! Horizon's registry once, checked as the launcher checks it, turns it on
+//! and carries the extra's settings over into the mod's storage. A player
+//! who had it off gets nothing: the mod is in the mod browser.
+use crate::{extras::Extras, mod_list::ModList};
+use horizon_mods::index::{self, Index};
+use std::{
+    fs,
+    io::Read,
+    path::{Path, PathBuf},
+};
+
+/// Horizon's registry; `HORIZON_MOD_INDEX` points elsewhere (a local file
+/// for trials, whose files may then be `file://`), as for the launcher.
+pub const INDEX_URL: &str = "https://ludovic111.github.io/horizon-mods/index.json";
+const MAX_INDEX: u64 = 16 << 20;
+
+/// An extra that is an official mod now.
+#[derive(Debug, PartialEq)]
+pub struct Moved {
+    /// The mod's id in the registry.
+    pub id: &'static str,
+    /// The extra's name, for the line the player reads.
+    pub name: &'static str,
+}
+
+pub const MOVED: [Moved; 2] = [
+    Moved {
+        id: "fps_overlay",
+        name: "FPS counter",
+    },
+    Moved {
+        id: "keystrokes",
+        name: "Keystrokes",
+    },
+];
+
+impl Moved {
+    fn was_on(&self, e: &Extras) -> bool {
+        match self.id {
+            "fps_overlay" => e.fps,
+            _ => e.keystrokes,
+        }
+    }
+    /// The extra's settings as the mod keeps them (its storage keys).
+    pub fn settings(&self, e: &Extras) -> Vec<(&'static str, String)> {
+        let flag = |b: bool| if b { "true" } else { "false" }.to_owned();
+        match self.id {
+            "fps_overlay" => vec![
+                ("corner", e.fps_corner.name().into()),
+                ("lows", flag(e.fps_lows)),
+            ],
+            _ => vec![
+                ("corner", e.keystrokes_corner.name().into()),
+                ("cps", flag(e.keystrokes_cps)),
+            ],
+        }
+    }
+    /// The line the player reads once it is installed.
+    pub fn notice(&self) -> String {
+        format!("{} moved to the mod browser: installed for you", self.name)
+    }
+}
+
+/// The moved extras still to install: on, and not done yet.
+pub fn pending(e: &Extras) -> Vec<&'static Moved> {
+    MOVED
+        .iter()
+        .filter(|m| m.was_on(e) && !e.moved.iter().any(|d| d == m.id))
+        .collect()
+}
+
+/// The moved extras that were off and not marked yet: nothing to install,
+/// only to remember.
+pub fn nothing_to_do(e: &Extras) -> Vec<&'static Moved> {
+    MOVED
+        .iter()
+        .filter(|m| !m.was_on(e) && !e.moved.iter().any(|d| d == m.id))
+        .collect()
+}
+
+fn location() -> String {
+    std::env::var("HORIZON_MOD_INDEX")
+        .ok()
+        .filter(|v| !v.is_empty())
+        .unwrap_or_else(|| INDEX_URL.to_owned())
+}
+
+/// `url`'s bytes, at most `max`: `https://` from the network; `file://` only
+/// with a local index (a trial registry).
+fn get(url: &str, local: bool, max: u64) -> Result<Vec<u8>, String> {
+    let mut out = Vec::new();
+    if url.starts_with("https://") {
+        let response = ureq::AgentBuilder::new()
+            .timeout(std::time::Duration::from_secs(60))
+            .build()
+            .get(url)
+            .call()
+            .map_err(|e| format!("{url}: {e}"))?;
+        response
+            .into_reader()
+            .take(max + 1)
+            .read_to_end(&mut out)
+            .map_err(|e| e.to_string())?;
+    } else {
+        let path = match url.strip_prefix("file://") {
+            Some(p) if local => p,
+            _ if local && !url.contains("://") => url,
+            _ => return Err(format!("{url}: not an https address")),
+        };
+        out = fs::read(path).map_err(|e| format!("{path}: {e}"))?;
+    }
+    if out.len() as u64 > max {
+        return Err(format!("{url}: over {max} bytes"));
+    }
+    Ok(out)
+}
+
+/// The registry's index, from the network (or `HORIZON_MOD_INDEX`).
+pub fn fetch_index() -> Result<Index, String> {
+    let at = location();
+    let local = !at.starts_with("https://");
+    let text = String::from_utf8(get(&at, local, MAX_INDEX)?).map_err(|e| e.to_string())?;
+    if local {
+        Index::parse_local(&text)
+    } else {
+        Index::parse(&text)
+    }
+}
+
+/// Installs `m` into the game folder `dir` (where `options.txt` is), for a
+/// player whose extras were `e`: its newest version for this game that
+/// wasn't taken down, checked against the index (size, SHA-256, signature,
+/// manifest), as `horizon-mods/<id>.hmod`, turned on, with the extra's
+/// settings in its storage unless the mod has its own already.
+pub fn install(index: &Index, m: &Moved, e: &Extras, dir: &Path) -> Result<(), String> {
+    let project = index
+        .project(m.id)
+        .ok_or_else(|| format!("{} isn't in Horizon's registry yet", m.id))?;
+    let version = project
+        .versions
+        .iter()
+        .find(|v| {
+            v.game == horizon_core::version::VERSION_ID
+                && index.revoked(&project.id, &v.file.sha256).is_none()
+        })
+        .ok_or_else(|| format!("{} has no version for this game", m.id))?;
+    let mods = dir.join(crate::mod_list::DIR);
+    fs::create_dir_all(&mods).map_err(|e| format!("{}: {e}", mods.display()))?;
+    let target = mods.join(format!("{}.hmod", m.id));
+    let current = index::sha256_file(&target).ok();
+    if current.as_deref() != Some(version.file.sha256.as_str()) {
+        let local = !location().starts_with("https://");
+        let bytes = get(&version.file.url, local, index::MAX_FILE)?;
+        let partial: PathBuf = mods.join(format!(".{}.hmod.download", m.id));
+        fs::write(&partial, bytes).map_err(|e| format!("{}: {e}", partial.display()))?;
+        if let Err(e) = index::check_file(index, project, version, &partial) {
+            let _ = fs::remove_file(&partial);
+            return Err(format!("{}: {e}", m.id));
+        }
+        fs::rename(&partial, &target).map_err(|e| format!("{}: {e}", target.display()))?;
+    }
+    let storage = mods.join(horizon_mods::manifest::STORAGE_DIR).join(m.id);
+    fs::create_dir_all(&storage).map_err(|e| format!("{}: {e}", storage.display()))?;
+    for (key, value) in m.settings(e) {
+        let path = storage.join(key);
+        if !path.exists() {
+            fs::write(&path, value).map_err(|e| format!("{}: {e}", path.display()))?;
+        }
+    }
+    let mut list = ModList::load(dir);
+    list.enabled.insert(m.id.to_owned());
+    list.save(dir);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::extras::Corner;
+
+    #[test]
+    fn only_extras_that_were_on_are_installed_and_each_once() {
+        let mut e = Extras::default();
+        assert!(pending(&e).is_empty());
+        assert_eq!(nothing_to_do(&e).len(), 2);
+        e.fps = true;
+        e.fps_corner = Corner::BottomRight;
+        e.fps_lows = true;
+        assert_eq!(pending(&e), [&MOVED[0]]);
+        assert_eq!(
+            MOVED[0].settings(&e),
+            [("corner", "bottom_right".into()), ("lows", "true".into())]
+        );
+        assert_eq!(
+            MOVED[1].settings(&e),
+            [("corner", "top_left".into()), ("cps", "true".into())]
+        );
+        e.moved.push("fps_overlay".into());
+        assert!(pending(&e).is_empty());
+        assert_eq!(nothing_to_do(&e), [&MOVED[1]]);
+        assert_eq!(
+            MOVED[0].notice(),
+            "FPS counter moved to the mod browser: installed for you"
+        );
+    }
+
+    #[test]
+    fn a_file_url_needs_a_local_index() {
+        assert!(get("file:///etc/hosts", false, 1 << 20).is_err());
+        assert!(get("http://example.com/x", true, 1 << 20).is_err());
+    }
+}
diff --git a/docs/extras.md b/docs/extras.md
index 26ddbe161..598b29739 100644
--- a/docs/extras.md
+++ b/docs/extras.md
@@ -1,8 +1,7 @@
 # Horizon extras
 
-Optional conveniences built into the client: fullbright, dynamic lights, zoom, a minimap, an FPS counter, a
-keystroke overlay, auto-reconnect, Mouse Tweaks-style inventory controls and
-inventory sorting. **Every one is off by default**: a fresh
+Optional conveniences built into the client: fullbright, dynamic lights, zoom, a minimap, auto-reconnect,
+Mouse Tweaks-style inventory controls and inventory sorting. **Every one is off by default**: a fresh
 install looks and behaves exactly like vanilla 26.3, and turning an extra off
 again restores vanilla's behaviour completely.
 
@@ -11,9 +10,9 @@ again restores vanilla's behaviour completely.
 | Part | Code |
 |---|---|
 | Settings, parsing and saving | `crates/horizon-client/src/extras.rs` |
-| Zoom curve, FPS and click counters | `extras.rs` (pure logic, unit tested) |
+| Zoom curve; FPS and click counters (for mods) | `extras.rs` (pure logic, unit tested) |
 | Dynamic lights: item glow, nearest sources | `crates/horizon-client/src/dynamic_light.rs` (unit tested), `game/dynamic_lights.rs`, `terrain.wgsl` and `entity.wgsl` (`dynamic_block_light`) |
-| HUD drawing (FPS, keystrokes, minimap frame) | `crates/horizon-client/src/extras_hud.rs` |
+| HUD drawing (minimap frame, corner stacking) | `crates/horizon-client/src/extras_hud.rs` |
 | Minimap colours, tiles and image | `crates/horizon-client/src/minimap.rs` |
 | Reconnect policy and backoff | `crates/horizon-client/src/reconnect.rs` |
 | Game glue (input hooks, per-frame update) | `crates/horizon-client/src/game/extras.rs` |
@@ -83,15 +82,15 @@ Horizon category in Controls, and adding one would put a non-vanilla mapping int
 - With zoom off (or the key up) the FOV target and mouse are vanilla's, bit for
   bit; the FOV harness covers this.
 
-### FPS counter (`fps`, default off)
-- A small "N fps" line in a corner (default top left), optionally followed by
-  the minimum and the 1% low over the last 5 seconds.
-- Separate from the Advanced graphics "Overlay" (the frame-time graph).
+### Moved to the mod browser
 
-### Keystrokes (`keystrokes`, default off)
-- W A S D, Space, LMB and RMB keys that light up while held, with clicks per
-  second under the mouse buttons (clicks in the last second). The letters follow
-  the bound keys.
+The **FPS counter** and **Keystrokes** are official mods now (`mods/official/`, [mods.md](mods.md#horizons-official-mods)),
+with the same look and options. On the first start after the update, a player who had one on gets the mod installed
+from Horizon's registry and turned on, with their corner and options carried over, and reads one line in the chat
+("FPS counter moved to the mod browser: installed for you"). The install is checked like the launcher's (size,
+SHA-256, signature, manifest); if it fails (offline), the next start tries again. `horizon-extras.txt` keeps the old
+keys and lists what was done in `movedToMods`. Code: `crates/horizon-client/src/moved_extras.rs`,
+`game/moved_extras.rs`.
 
 ### Minimap (`minimap`, default off)
 - A corner map (top right by default), square or round, small/medium/large,
@@ -162,11 +161,11 @@ and the container screen tests are unchanged).
   the world, like vanilla's HUD. Extras in the top left corner give way to the
   debug screen (F3), which shows the FPS anyway.
 - Corners stack: extras placed in the same corner stack downward (top corners)
-  or upward (bottom corners) in the order minimap, FPS, keystrokes. The top
+  or upward (bottom corners) in the order minimap, then mods' panels. The top
   right corner starts below the status effect icons.
 
 ## Perf budget
 
 Off: a flag check per frame per extra (no allocations, no world access).
-On: FPS and keystrokes are a few quads; the minimap stays under 0.3 ms of CPU
+On: the minimap stays under 0.3 ms of CPU
 per frame (tile budget) plus a 64 KiB texture upload when its image changes.

From 160c1e8b7a3bebcd7157feff5c4cf17ada0198c2 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:54:02 +0100
Subject: [PATCH 243/270] CI: a failed preparation leaves nothing in .local

When horizon-prepare failed, vanilla-data.sh deleted the preparation folder but kept what it had
already written to .local/ (horizon-client, horizon-client-motion, ...). The next job then saw those
real folders as already there: its preparation listed only horizon-client-structures in .entries,
and the checkout kept using the stale resources outside the per-key cache.

Now a failed preparation removes the .local/ entries it created; a job first removes real folders
named like preparation outputs, and makes again a preparation whose .entries lacks horizon-client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/ci/vanilla-data.sh | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/tools/ci/vanilla-data.sh b/tools/ci/vanilla-data.sh
index 5276c54e9..f548e1f14 100755
--- a/tools/ci/vanilla-data.sh
+++ b/tools/ci/vanilla-data.sh
@@ -42,7 +42,21 @@ until mkdir "$lock" 2>/dev/null; do
 done
 trap 'rmdir "$lock" 2>/dev/null || true' EXIT
 # horizon-prepare writes .local/horizon-client and its exporters' outputs beside it: all of them live in
-# $prepared, listed in $prepared/.entries, and .local/ links to them.
+# $prepared, listed in $prepared/.entries, and .local/ links to them. A real folder of that kind in .local/ is
+# what an older failed preparation left: it would hide the preparations (and a new one would not count it as its
+# own output), so it goes.
+outputs=$({ cat "$shared"/prepared/*/.entries; cd .local && ls -d horizon-client*; } 2>/dev/null || true)
+for name in $(echo "$outputs" | LC_ALL=C sort -u); do
+  if [ -e ".local/$name" ] && [ ! -L ".local/$name" ]; then
+    rm -rf ".local/${name:?}"
+    echo "Removed .local/$name, left by a failed preparation"
+  fi
+done
+# A preparation made while such a folder was there did not list it (horizon-client above all), so it is made again.
+if [ -f "$prepared/.entries" ] && ! grep -qx horizon-client "$prepared/.entries"; then
+  echo "Preparation $key lacks horizon-client: preparing again"
+  rm -rf "$prepared"
+fi
 if [ ! -f "$prepared/.entries" ]; then
   echo "Preparing resources with this checkout's horizon-prepare ($key)"
   rm -rf "$prepared" && mkdir -p "$prepared"
@@ -55,6 +69,9 @@ if [ ! -f "$prepared/.entries" ]; then
   cargo build --release --locked -p horizon-prepare
   if ! target/release/horizon-prepare --root "$PWD" > "$RUNNER_TEMP/prepare.log" 2>&1; then
     tail -40 "$RUNNER_TEMP/prepare.log"
+    # Nothing of a failed preparation stays in .local/: the next job prepares again.
+    LC_ALL=C comm -13 <(echo "$before") <(ls -1A .local | LC_ALL=C sort) |
+      while read -r name; do rm -rf ".local/${name:?}"; done
     rm -rf "$prepared"
     exit 1
   fi

From d782e455a41f21e79675347c4314c9e8e2bdb535 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 01:55:57 +0100
Subject: [PATCH 244/270] docs: the desktop's CI slice gets half the threads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/release-flow.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/release-flow.md b/docs/release-flow.md
index dc96498a0..7bb64d21e 100644
--- a/docs/release-flow.md
+++ b/docs/release-flow.md
@@ -78,8 +78,8 @@ time, under a lock) and the parity passes and slots.
 `horizon-game` once a full trial has passed there) runs on the maintainer's Linux desktop while nobody uses it: its
 screen locked, or untouched for 15 minutes (his rule, 2026-10-26). `tools/ci/linux-runner.sh install`, run there as
 him, registers it and installs two systemd user services: `horizon-runner` (the runner, in
-`~/.actions-runners/horizon`, nice 19, in `horizon-ci.slice` with CPU and I/O weight 20 and memory capped at two
-thirds of the RAM; `CARGO_BUILD_JOBS` and the harness slots at 8, after the machine froze under ~7 cold cargo
+`~/.actions-runners/horizon`, nice 19, in `horizon-ci.slice` with CPU and I/O weight 20, half the threads (on all of
+them the CPU package reached 92–96 °C) and memory capped at two thirds of the RAM; `CARGO_BUILD_JOBS` and the harness slots at 8, after the machine froze under ~7 cold cargo
 builds on 2026-10-14; its own Rust install; the JDK, sccache and the build libraries from nixpkgs; its own
 `vscreen` so no game it starts reaches his screen) and `horizon-runner-pause` (`tools/ci/runner_pause.py`), the
 only thing that starts the runner. The watcher stops it at once on keyboard, mouse or gamepad input (read from

From 7b0192118e8a4e23cfc209d0ae7b2710824a993c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 02:13:09 +0100
Subject: [PATCH 245/270] parity: choose harnesses faster (shared parse cache,
 early stop, time budget)

- The reach parse cache lives in the shared parity folder, keyed by content,
  so a new worktree starts warm (written atomically, other worktrees'
  entries kept within bounds).
- A harness's reach search stops as soon as it reaches a changed file that
  differs in more than its `mod` declarations; partial searches are not
  memoized. Declaration diffs are memoized (one git show per file).
- A harness whose changed dependency is outside crates/ is picked without a
  search (narrowing always keeps those).
- After PARITY_REACH_BUDGET seconds (default 180) the remaining harnesses
  count every source their probes link.
- crate_of is cached; no pathlib in the hot paths.

Same 79 harnesses on the 19-file diff from contrib-gate-16; CPU 19.9 s cold /
16.6 s warm before, 13.1 s cold / 9.9 s warm after (Mac mini under load).

parity.yml: skip the prepare_output check for heads made before #1947 (no
OUTPUT_VERSION, no tool): the job runs main's workflow on the head's files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity.yml |   9 +-
 docs/parity-workflow.md      |   2 +-
 tests/test_parity_reach.py   |  10 ++
 tools/parity.py              |  41 ++++++--
 tools/parity_reach.py        | 184 ++++++++++++++++++++---------------
 5 files changed, 154 insertions(+), 92 deletions(-)

diff --git a/.github/workflows/parity.yml b/.github/workflows/parity.yml
index 577380338..4540f363f 100644
--- a/.github/workflows/parity.yml
+++ b/.github/workflows/parity.yml
@@ -40,7 +40,14 @@ jobs:
       - name: The prepared output is the one the preparer's OUTPUT_VERSION says
         env:
           BASE_SHA: ${{ inputs.base }}
-        run: python3 tools/prepare_output.py check --cache --base "$BASE_SHA"
+        run: |
+          # The job runs main's workflow on the head's files: a head made before OUTPUT_VERSION (#1947) has neither
+          # the tool nor the number, so there is nothing to check.
+          if [ ! -f tools/prepare_output.py ] || ! grep -q OUTPUT_VERSION crates/horizon-prepare/src/lib.rs; then
+            echo "This head's preparer has no OUTPUT_VERSION: nothing to check"
+            exit 0
+          fi
+          python3 tools/prepare_output.py check --cache --base "$BASE_SHA"
       - name: The version constants are the pinned jar's
         run: python3 tools/gen_version_consts.py --check
       - name: The harnesses this change can affect
diff --git a/docs/parity-workflow.md b/docs/parity-workflow.md
index d64ec3087..45ccae3df 100644
--- a/docs/parity-workflow.md
+++ b/docs/parity-workflow.md
@@ -53,7 +53,7 @@ A harness can declare, at the top level of its script:
 
 ### Which harnesses a change affects
 
-`--changed` and `--changed-files` narrow each harness's Rust sources to those its probes can reach (`tools/parity_reach.py`), so a change to one module of `horizon-client` no longer reruns every harness whose probe links the crate. The narrowing works on items, not files: from the probe modules a harness ran (or the binary it built), a free item (fn, type, const, static) is reached when a reached item names it in its own module, through a path or an import of a module that is named, or through a glob import; an inherent impl's methods count one by one once their type is reached and their name is mentioned; a trait impl counts once its trait and its type are reached (std's traits and types always are); a macro counts once invoked. Names match by spelling, so the result only over-approximates. A reached file's parent modules count through their `mod` declarations of it, compared with the merge base; Rust files a change adds take part, a dependency that was deleted counts as changed, code under `#[cfg(test)]` never counts, and a harness whose probe can't be found keeps every source. Parses are cached by content in `.local/parity-runner/reach-cache.json`. `--by-crate` turns the narrowing off. On the last 20 pull requests merged on 2026-10-25, the harnesses picked went from 2255 to 1061 (2384 to 1592 harness-minutes; game-binary harnesses, which link all of `game/`, set the floor), and every harness a CI parity run failed in the week before was still picked; every source file a sample of probes executed (LLVM `-C instrument-coverage`) is among those kept. Building the graph takes 15 s cold, under a second warm, and up to a minute and a half on a change that reaches many harnesses.
+`--changed` and `--changed-files` narrow each harness's Rust sources to those its probes can reach (`tools/parity_reach.py`), so a change to one module of `horizon-client` no longer reruns every harness whose probe links the crate. The narrowing works on items, not files: from the probe modules a harness ran (or the binary it built), a free item (fn, type, const, static) is reached when a reached item names it in its own module, through a path or an import of a module that is named, or through a glob import; an inherent impl's methods count one by one once their type is reached and their name is mentioned; a trait impl counts once its trait and its type are reached (std's traits and types always are); a macro counts once invoked. Names match by spelling, so the result only over-approximates. A reached file's parent modules count through their `mod` declarations of it, compared with the merge base; Rust files a change adds take part, a dependency that was deleted counts as changed, code under `#[cfg(test)]` never counts, and a harness whose probe can't be found keeps every source. Parses are cached by content in `reach-cache.json` of the shared parity folder (beside `passes/`), so a new worktree starts warm; a harness's search stops as soon as it reaches a changed file, and after `PARITY_REACH_BUDGET` seconds (default 180) the remaining harnesses count every source their probes link, so choosing never holds a slow machine for long. `--by-crate` turns the narrowing off. On the last 20 pull requests merged on 2026-10-25, the harnesses picked went from 2255 to 1061 (2384 to 1592 harness-minutes; game-binary harnesses, which link all of `game/`, set the floor), and every harness a CI parity run failed in the week before was still picked; every source file a sample of probes executed (LLVM `-C instrument-coverage`) is among those kept. Building the graph takes 15 s cold, under a second warm, and up to a minute and a half on a change that reaches many harnesses.
 
 ## The gate
 
diff --git a/tests/test_parity_reach.py b/tests/test_parity_reach.py
index 9b7464b47..07e3df9e3 100644
--- a/tests/test_parity_reach.py
+++ b/tests/test_parity_reach.py
@@ -101,6 +101,16 @@ class ReachTests(unittest.TestCase):
         (self.root / "crates/a/src/unused.rs").unlink()
         self.assertIn("crates/a/src/unused.rs", self.narrowed())
 
+    def test_a_search_told_to_stop_still_keeps_the_file_it_stopped_at(self):
+        graph = parity_reach.SourceGraph(self.root, parity.rust_code)
+        kept = parity_reach.narrow(self.dependencies, PROBE, graph, {"crates/a/src/used.rs"}, {"crates/a/src/used.rs"})
+        self.assertEqual(kept["crates/a/src/used.rs"], (True, set()))
+        self.assertFalse(graph.results, "a partial search is not remembered")
+        # A stop file outside the harness's sources doesn't end its search.
+        full = parity_reach.narrow(self.dependencies, PROBE, graph, (), {"crates/b/src/lib.rs"})
+        self.assertIn("crates/a/src/display.rs", full)
+        self.assertTrue(graph.results)
+
     def test_unknown_probes_keep_everything(self):
         self.assertEqual(set(self.narrowed(artifacts=[])), set(self.dependencies))
         self.assertEqual(set(self.narrowed(artifacts=[["example", "missing", "release", ["-p", "a"], True]])),
diff --git a/tools/parity.py b/tools/parity.py
index 3f18b922d..285e7268b 100644
--- a/tools/parity.py
+++ b/tools/parity.py
@@ -1245,14 +1245,20 @@ def affected_harnesses(found, records, changed, reach=True, base=None):
     commit), only declarations of modules the harness doesn't reach changed (tools/parity_reach.py)."""
     if changed & SHARED_INPUTS:
         return set(found)
-    graph = None
+    graph, stop = None, frozenset()
+    # Parses are keyed by content, so every worktree sharing the vanilla data shares them.
+    cache_path = (SHARED if SHARED.is_dir() else STATE_DIR) / "reach-cache.json"
     if reach and any(path.startswith("crates/") for path in changed):
-        cache_path = STATE_DIR / "reach-cache.json"
         try:
             cache = json.loads(cache_path.read_text(encoding="utf-8"))
         except (OSError, ValueError):
             cache = {}
         graph = parity_reach.SourceGraph(ROOT, rust_code, cache)
+        # A changed file that differs in more than its `mod` declarations counts as soon as a harness reaches it,
+        # so the search for that harness can stop there.
+        stop = frozenset(path for path in changed if parity_reach.is_workspace_rust(path)
+                         and parity_reach.declarations_changed(ROOT, path, (), base, True))
+    budget, started, over = float(os.environ.get("PARITY_REACH_BUDGET") or 180), time.monotonic(), False
     affected = set()
     for name, script in found.items():
         record = records.get(name) or {}
@@ -1265,16 +1271,31 @@ def affected_harnesses(found, records, changed, reach=True, base=None):
             affected.add(name)
             continue
         plain = {path.split(KEEP)[0] for path in dependencies}
-        if graph is not None and plain & changed:
-            narrowed = parity_reach.narrow(dependencies, recorded_artifacts(record), graph, changed)
-            if any(path.split(KEEP)[0] in changed and (children is None or parity_reach.declarations_changed(
-                    ROOT, path.split(KEEP)[0], children, base, whole)) for path, (whole, children) in narrowed.items()):
-                affected.add(name)
-        elif plain & changed:
+        hit = plain & changed
+        if not hit:
+            continue
+        if graph is None or any(not path.startswith("crates/") for path in hit):
+            affected.add(name)  # no narrowing, or a file narrowing always keeps (tools/, Java oracles)
+            continue
+        if not over and time.monotonic() - started > budget:
+            over = True
+            print(f"note: choosing harnesses took over {budget:.0f} s (PARITY_REACH_BUDGET): the rest count every "
+                  "source their probes link", flush=True)
+        if over:
+            affected.add(name)
+            continue
+        narrowed = parity_reach.narrow(dependencies, recorded_artifacts(record), graph, changed, stop)
+        if any(path.split(KEEP)[0] in changed and (children is None or parity_reach.declarations_changed(
+                ROOT, path.split(KEEP)[0], children, base, whole)) for path, (whole, children) in narrowed.items()):
             affected.add(name)
     if graph is not None:
-        STATE_DIR.mkdir(parents=True, exist_ok=True)
-        cache_path.write_text(json.dumps(graph.saved_cache()), encoding="utf-8")
+        saved = graph.saved_cache()
+        if len(cache) + len(saved) < 4 * max(len(saved), 1):
+            saved = {**cache, **saved}  # other worktrees' versions of the files too, within bounds
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = cache_path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(saved), encoding="utf-8")
+        temporary.replace(cache_path)
     return affected
 
 
diff --git a/tools/parity_reach.py b/tools/parity_reach.py
index 0c3051b86..dc61f6215 100644
--- a/tools/parity_reach.py
+++ b/tools/parity_reach.py
@@ -25,8 +25,9 @@ assets, fonts) that only unreached sources name; a dependency that no longer exi
 a change adds take part.
 """
 
+import functools
 import hashlib
-from pathlib import Path, PurePosixPath
+from pathlib import Path
 import re
 import subprocess
 
@@ -478,9 +479,10 @@ class SourceGraph:
                            seeds=seeds, node_sets={})
         return self.tables
 
-    def reachable(self, entries, universe, reasons=None):
+    def reachable(self, entries, universe, reasons=None, stop=frozenset()):
         """The files of universe (workspace Rust sources) holding an item reachable from entries (by the rules in
-        this module's doc), and the entries. reasons, a dict, gets why each file was reached (for debugging)."""
+        this module's doc), and the entries. reasons, a dict, gets why each file was reached (for debugging). The
+        search ends early, with only part of the answer, once it reaches a file of stop."""
         # Searching every source of the crates involved (not only those Cargo listed) only adds reach, and lets
         # harnesses with the same entries (the game binary's) share one search.
         crates = frozenset(crate_of(path) for path in universe)
@@ -488,11 +490,12 @@ class SourceGraph:
         if reasons is None and key in self.results:
             return self.results[key] & set(universe)
         everything = {path for path in self.files if crate_of(path) in crates} | set(universe)
-        files = self.search(entries, everything, reasons)
-        self.results[key] = files
+        files, complete = self.search(entries, everything, reasons, stop)
+        if complete:
+            self.results[key] = files
         return files & set(universe)
 
-    def search(self, entries, universe, reasons):
+    def search(self, entries, universe, reasons, stop=frozenset()):
         targets = {self.target(path) for path in entries}
         universe = {path for path in universe if (self.is_library(path) or self.target(path) in targets)
                     and path not in self.test_only}
@@ -600,71 +603,80 @@ class SourceGraph:
                 files.add(path)
                 if reasons is not None:
                     reasons[path] = why
+                if path in stop:
+                    raise Stop
 
-        for path in universe:
-            if path.endswith("/src/lib.rs") or path in entries or path not in self.parent:
-                open_module(path, "crate root or entry")
-        for node in seeds:
-            reach(node, "entry" if node[0] in entries else "always counted")
-        for path in entries & universe:
-            files.add(path)
-            if reasons is not None:
-                reasons.setdefault(path, "entry")
-        while queue:
-            node = queue.pop()
-            path, index, member = node
-            item = item_of(node)
-            crate = crate_of(path)
-            label = (item.get("names") or [item["kind"]])[0] if member is None else item["members"][member]["name"]
-            source = sets_of(node, item)
-            why = f"{path} ({label})"
-            # Plain mentions reach items of this file and of the modules above it.
-            ancestor, new = path, source["mentions"]
-            while ancestor is not None and new:
-                known = local.setdefault(ancestor, set())
-                new = new - known
-                known |= new
+        try:
+            for path in universe:
+                if path.endswith("/src/lib.rs") or path in entries or path not in self.parent:
+                    open_module(path, "crate root or entry")
+            for node in seeds:
+                reach(node, "entry" if node[0] in entries else "always counted")
+            for path in entries & universe:
+                files.add(path)
+                if reasons is not None:
+                    reasons.setdefault(path, "entry")
+            while queue:
+                node = queue.pop()
+                path, index, member = node
+                item = item_of(node)
+                crate = crate_of(path)
+                label = (item.get("names") or [item["kind"]])[0] if member is None else item["members"][member]["name"]
+                source = sets_of(node, item)
+                why = f"{path} ({label})"
+                # Plain mentions reach items of this file and of the modules above it.
+                ancestor, new = path, source["mentions"]
+                while ancestor is not None and new:
+                    known = local.setdefault(ancestor, set())
+                    new = new - known
+                    known |= new
+                    for name in new:
+                        wake(by_file_name.get((ancestor, name), ()), f"{why} mentions {name}")
+                    ancestor = self.parent.get(ancestor)
+                if item["kind"] == "use" and item["glob"]:
+                    for name in item["names"]:
+                        for target in sees.get(crate, {crate}):
+                            for module in list(by_module.get((target, name), ())) + \
+                                    ([f"crates/{idents[name]}/src/lib.rs"] if name in idents else []):
+                                if module not in globbed and module in universe:
+                                    globbed.add(module)
+                                    wake([(module, index, None) for index in range(len(self.parse(module)["items"]))]
+                                         if self.parse(module) else [], f"{why} glob-imports {name}")
+                visible_to = sees.get(crate, {crate})
+                new = source["paths"] - done["paths"].setdefault(crate, set())
+                done["paths"][crate] |= new
                 for name in new:
-                    wake(by_file_name.get((ancestor, name), ()), f"{why} mentions {name}")
-                ancestor = self.parent.get(ancestor)
-            if item["kind"] == "use" and item["glob"]:
-                for name in item["names"]:
-                    for target in sees.get(crate, {crate}):
-                        for module in list(by_module.get((target, name), ())) + \
-                                ([f"crates/{idents[name]}/src/lib.rs"] if name in idents else []):
-                            if module not in globbed and module in universe:
-                                globbed.add(module)
-                                wake([(module, index, None) for index in range(len(self.parse(module)["items"]))]
-                                     if self.parse(module) else [], f"{why} glob-imports {name}")
-            visible_to = sees.get(crate, {crate})
-            new = source["paths"] - done["paths"].setdefault(crate, set())
-            done["paths"][crate] |= new
-            for name in new:
-                for target in visible_to:
-                    path_names.setdefault(target, set()).add(name)
-                    for module in by_module.get((target, name), ()):
-                        if module in universe and self.parent[module] in opened:
-                            open_module(module, f"{why} names {name}")
-            for key, table, wanted in (("qualified", qualified, lambda other: True),
-                                       ("invokes", invoked, lambda other: item_of(other)["kind"] == "macro"),
-                                       ("mentions", mentioned, lambda other: other[2] is not None or other[0] in globbed)):
-                new = source[key] - done[key].setdefault(crate, set())
-                done[key][crate] |= new
-                for name in new:
-                    table.setdefault(name, set()).add(crate)
-                    wake([other for other in by_name.get(name, ()) if crate_of(other[0]) in visible_to and wanted(other)],
-                         f"{why} {key} {name}")
-            if item["kind"] in TYPE_KINDS and member is None:
-                own = types.setdefault(crate, set())
-                local_types.setdefault(path, set()).update(names(node))
-                if not names(node) <= own:
-                    own |= names(node)
-                    visible_cache.clear()
-                seeing = seen_by.get(crate, {crate})
-                for name in names(node):  # also when the crate has one by that name already: impls of this one
-                    wake([other for other in by_type.get(name, ()) if crate_of(other[0]) in seeing],
-                         f"implements for {name}, defined in {path}")
-        return files
+                    for target in visible_to:
+                        path_names.setdefault(target, set()).add(name)
+                        for module in by_module.get((target, name), ()):
+                            if module in universe and self.parent[module] in opened:
+                                open_module(module, f"{why} names {name}")
+                for key, table, wanted in (("qualified", qualified, lambda other: True),
+                                           ("invokes", invoked, lambda other: item_of(other)["kind"] == "macro"),
+                                           ("mentions", mentioned, lambda other: other[2] is not None or other[0] in globbed)):
+                    new = source[key] - done[key].setdefault(crate, set())
+                    done[key][crate] |= new
+                    for name in new:
+                        table.setdefault(name, set()).add(crate)
+                        wake([other for other in by_name.get(name, ()) if crate_of(other[0]) in visible_to and wanted(other)],
+                             f"{why} {key} {name}")
+                if item["kind"] in TYPE_KINDS and member is None:
+                    own = types.setdefault(crate, set())
+                    local_types.setdefault(path, set()).update(names(node))
+                    if not names(node) <= own:
+                        own |= names(node)
+                        visible_cache.clear()
+                    seeing = seen_by.get(crate, {crate})
+                    for name in names(node):  # also when the crate has one by that name already: impls of this one
+                        wake([other for other in by_type.get(name, ()) if crate_of(other[0]) in seeing],
+                             f"implements for {name}, defined in {path}")
+        except Stop:
+            return files, False
+        return files, True
+
+
+class Stop(Exception):
+    """A search reached a file it was told to stop at."""
 
 
 def impl_subject(header):
@@ -682,13 +694,19 @@ def impl_subject(header):
     return parameters, re.split(r"\bwhere\b", header)[0]
 
 
+_CRATES = {}
+
+
 def crate_of(path):
-    return path.split("/", 2)[1]
+    """The crate folder of a crates/<crate>/... path (called millions of times by a search: cached)."""
+    crate = _CRATES.get(path)
+    if crate is None:
+        crate = _CRATES[path] = path.split("/", 2)[1]
+    return crate
 
 
 def is_workspace_rust(path):
-    parts = PurePosixPath(path).parts
-    return len(parts) > 2 and parts[0] == "crates" and path.endswith(".rs")
+    return path.startswith("crates/") and path.endswith(".rs") and path.count("/") >= 2
 
 
 DECLARATION_LINE = re.compile(rf"\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+({IDENT})\s*;")
@@ -718,6 +736,11 @@ def declarations_changed(root, path, children, base, whole):
     missing."""
     if base is None:
         return True
+    return _declarations_changed(str(root), path, frozenset(children), base, whole)
+
+
+@functools.lru_cache(maxsize=None)
+def _declarations_changed(root, path, children, base, whole):
     try:
         head = (Path(root) / path).read_text(encoding="utf-8", errors="replace")
         before = subprocess.run(["git", "show", f"{base}:{path}"], cwd=root, capture_output=True, text=True, check=True).stdout
@@ -726,36 +749,37 @@ def declarations_changed(root, path, children, base, whole):
     return declarations(head, children, whole) != declarations(before, children, whole)
 
 
-def narrow(dependencies, artifacts, graph, changed=()):
+def narrow(dependencies, artifacts, graph, changed=(), stop=frozenset()):
     """A harness's dependencies narrowed to what its entry points can reach: {dependency: (whole, children)}, where
     whole says the file counts for its own content (else only through its `mod` declarations of children, as a
     module ancestor of a reached file) and children are its reached child modules. Without known entry points (a
-    probe or binary the harness built that isn't found here), every dependency is kept whole."""
+    probe or binary the harness built that isn't found here), every dependency is kept whole. The search may end
+    as soon as it reaches a file of stop (changed files that count once reached): then only part is returned."""
     plain = [dependency.split("#keep:")[0] for dependency in dependencies]
-    crates = {PurePosixPath(path).parts[1] for path in plain if path.startswith("crates/")}
+    crates = {crate_of(path) for path in plain if path.startswith("crates/") and path.count("/") >= 2}
     rust = {path for path in plain if is_workspace_rust(path)}
-    added = {path for path in changed if is_workspace_rust(path) and PurePosixPath(path).parts[1] in crates
+    added = {path for path in changed if is_workspace_rust(path) and crate_of(path) in crates
              and path not in rust and (graph.root / path).is_file()}
     entries = graph.entries(artifacts, rust)
     if entries is None:
         return {dependency: (True, None) for dependency in dependencies}
     missing = {path for path in rust if graph.parse(path) is None}
-    reached = graph.reachable(entries, rust | added | entries) | missing
+    reached = graph.reachable(entries, rust | added | entries, stop=frozenset(stop) & (rust | added)) | missing
     named, named_in_crate = set(), {}
     for path in rust | added:
         parsed = graph.parse(path)
         file_names = set(parsed["file_names"]) if parsed else set()
         if path in reached:
             named |= file_names
-        named_in_crate.setdefault(PurePosixPath(path).parts[1], set()).update(file_names)
+        named_in_crate.setdefault(crate_of(path), set()).update(file_names)
     kept = {}
     for dependency, path in zip(dependencies, plain):
         if is_workspace_rust(path):
             if path in reached:
                 kept[dependency] = (True, set())
         elif not path.startswith("crates/") or path.endswith(("Cargo.toml", "build.rs")) \
-                or PurePosixPath(path).name in named \
-                or PurePosixPath(path).name not in named_in_crate.get(PurePosixPath(path).parts[1], ()):
+                or path.rsplit("/", 1)[-1] in named \
+                or path.rsplit("/", 1)[-1] not in named_in_crate.get(crate_of(path), ()):
             kept[dependency] = (True, None)
     for path in sorted(added & reached):
         kept[path] = (True, set())

From 24b26da5d6a2d9fcce961ef8fa289a5dda0bff10 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 02:19:17 +0100
Subject: [PATCH 246/270] server_ops_feedback: wait for the save's reply before
 the next step

On the desktop runner (8 harnesses at a time) vanilla's save-all took 2 s,
the whole step: the transcript ended before "Saved the game" and the
harness failed with Horizon right. The save step now waits for that console
line, on both sides, before its usual 2 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/test_server_ops_feedback_parity.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tools/test_server_ops_feedback_parity.py b/tools/test_server_ops_feedback_parity.py
index 2dd405517..f7b7a0e73 100644
--- a/tools/test_server_ops_feedback_parity.py
+++ b/tools/test_server_ops_feedback_parity.py
@@ -54,6 +54,9 @@ QUIET = [
 ]
 CASES = {'broadcast': ({}, BROADCAST), 'quiet': ({'broadcast-console-to-ops': 'false'}, QUIET)}
 STEP_SECONDS = 2.0
+# Steps whose reply can take longer than a step: the next step waits for this console line first. A loaded machine
+# took 2 s to save vanilla's world, and the transcript ended before "Saved the game".
+WAIT_FOR = {'console-save': r'System chat: Saved the game'}
 
 
 def run_side(label, case, server_command, client_command, build, world):
@@ -88,6 +91,8 @@ def run_side(label, case, server_command, client_command, build, world):
                         server.console(command)
                     for action in actions:
                         tell(action)
+                    if step in WAIT_FOR:
+                        server.wait_for(WAIT_FOR[step], timeout=120)
                     time.sleep(STEP_SECONDS)
                 tell('end')
                 client.wait(timeout=60)

From d3af1e04e01c1122c0647447dbb918dbf53277cf Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 02:27:37 +0100
Subject: [PATCH 247/270] Mannequins run no mob goals and never despawn

A mannequin is an Avatar (a LivingEntity), not a Mob: its serverAiStep has
no goals and LivingEntity has no checkDespawn. With the passive brain a
summoned mannequin wandered off (14 blocks in 400 ticks on the server
thread) and could despawn far from players.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/mobs/ai.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/mobs/ai.rs b/crates/horizon-client/src/mobs/ai.rs
index 97da5ea06..c9bc15fda 100644
--- a/crates/horizon-client/src/mobs/ai.rs
+++ b/crates/horizon-client/src/mobs/ai.rs
@@ -664,8 +664,10 @@ fn ai_step(m: &mut Mob, w: &MobWorld, level_random: &mut LegacyRandom, events: &
     m.ai.xxa *= 0.98;
     m.ai.zza *= 0.98;
     // LivingEntity.isImmobile: no goals or input (a biting, stunned or
-    // roaring ravager).
-    let immobile = m.species() == Species::Ravager && super::ravager::immobile(m);
+    // roaring ravager). A mannequin is an Avatar, not a Mob: LivingEntity's
+    // serverAiStep has no goals, so it only falls and is pushed.
+    let immobile = (m.species() == Species::Ravager && super::ravager::immobile(m))
+        || m.species() == Species::Mannequin;
     if m.alive() && !immobile {
         server_ai_step(m, w, level_random, events);
     } else {
@@ -1018,6 +1020,10 @@ pub fn despawn_check(m: &mut Mob, w: &MobWorld) -> bool {
 /// Mob.checkDespawn, before the tick (players are the only despawn
 /// reference). Returns false when the mob is discarded.
 fn check_despawn(m: &mut Mob, w: &MobWorld) -> bool {
+    // A mannequin is a LivingEntity, which never despawns.
+    if m.species() == Species::Mannequin {
+        return true;
+    }
     let Some(p) = w.nearest_player else {
         return true;
     };

From 48db367d4a32e7ad5ee6bfa51765052c375d25d9 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 03:09:29 +0100
Subject: [PATCH 248/270] Mod API: zoom the camera, take the mouse wheel
 (render, input)

render.set-zoom divides the field of view by up to 10, eased through the
game's FOV easing or at once, with a turning scale (at least 0.05); only
while playing, and the spyglass's own view wins. The strongest of several
mods' zooms counts, and the built-in zoom keeps working beside it.

input.claim-wheel takes the wheel from the hotbar while playing: its steps
are the mod's wheel events. That is the one input a mod consumes; its keys
never do (docs/api/stability.md). A screen opening now lets the mod's held
keys up, and mod keys bound to mouse buttons (key.mouse.4) are heard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |  2 +
 crates/horizon-client/src/game/extras.rs      | 27 +++++---
 crates/horizon-client/src/game/mod_input.rs   | 62 ++++++++++++++++-
 crates/horizon-client/src/game/mods.rs        |  4 ++
 crates/horizon-mod-sdk/wit/horizon.wit        | 25 ++++++-
 crates/horizon-mods/src/manifest.rs           |  4 +-
 crates/horizon-mods/src/runtime.rs            | 68 ++++++++++++++++++-
 crates/horizon-mods/tests/sandbox.rs          | 50 ++++++++++++++
 crates/horizon-mods/tests/ui_guest/src/lib.rs | 21 +++++-
 docs/api/mods-reference.md                    | 17 ++++-
 docs/api/stability.md                         | 13 +++-
 docs/mods.md                                  |  4 +-
 12 files changed, 273 insertions(+), 24 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 5b04d8716..508122bca 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -10995,6 +10995,7 @@ impl ApplicationHandler for Game<'_> {
                     if self.screen == Screen::Playing
                         && self.sleeping.is_none()
                         && self.player.is_some()
+                        && !self.mod_wheel(d)
                         && !self.extras_scroll(d)
                         && let Some((wheel, (_, vertical_steps))) =
                             self.mouse
@@ -11165,6 +11166,7 @@ impl ApplicationHandler for Game<'_> {
                                 return Ok(());
                             }
                             self.extras_mouse(button, pressed);
+                            self.mod_mouse_key(button, pressed);
                             match self.settings.keys.translate_mouse(button) {
                                 Some(Err(b)) => self.play_mouse(b, pressed)?,
                                 Some(Ok(k)) if pressed => {
diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index 4664f0c6f..1978d003f 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -229,25 +229,34 @@ impl Game<'_> {
     fn zoom_factor(&self) -> f32 {
         self.extras.zoom.factor(self.scoping())
     }
+    /// The zoom in effect, the extra's or a mod's (`render.set-zoom`),
+    /// whichever is stronger: (factor, smooth, turning scale).
+    fn zoom_now(&self) -> (f32, bool, f64) {
+        let factor = self.zoom_factor();
+        let e = &self.settings.extras;
+        let own = (factor, e.zoom_smooth, turn_scale(factor, e.zoom_sensitivity));
+        match self.mod_zoom() {
+            Some(z) if z.factor > factor => (z.factor, z.smooth, f64::from(z.turn)),
+            _ => own,
+        }
+    }
     /// The field-of-view modifier target, divided by a smooth zoom.
     pub(super) fn zoomed_fov_target(&self, vanilla: f32) -> f32 {
-        if self.settings.extras.zoom_smooth {
-            fov_target(vanilla, self.zoom_factor())
-        } else {
-            vanilla
+        match self.zoom_now() {
+            (factor, true, _) => fov_target(vanilla, factor),
+            _ => vanilla,
         }
     }
     /// The field of view in degrees, divided by an instant zoom.
     pub(super) fn zoomed_fov_degrees(&self, fov: f32) -> f32 {
-        if self.settings.extras.zoom_smooth {
-            fov
-        } else {
-            fov / self.zoom_factor()
+        match self.zoom_now() {
+            (factor, false, _) => fov / factor,
+            _ => fov,
         }
     }
     /// Mouse turning while zoomed.
     pub(super) fn zoom_turn_scale(&self) -> f64 {
-        turn_scale(self.zoom_factor(), self.settings.extras.zoom_sensitivity)
+        self.zoom_now().2
     }
     /// The FPS counter and keystrokes, in the HUD layer (hidden with F1 by
     /// the caller). The top left corner gives way to the debug screen.
diff --git a/crates/horizon-client/src/game/mod_input.rs b/crates/horizon-client/src/game/mod_input.rs
index ac80e8e42..199669957 100644
--- a/crates/horizon-client/src/game/mod_input.rs
+++ b/crates/horizon-client/src/game/mod_input.rs
@@ -1,6 +1,7 @@
 //! Capability `input` (docs/mods.md): the use button on items a mod claims,
-//! and the mod's own keys. With no mod claiming items or keys, each hook
-//! here returns after one check.
+//! the mod's own keys and the mouse wheel; and `render`'s zoom. With no mod
+//! claiming items, keys or the wheel, each hook here returns after one
+//! check.
 use super::Game;
 use winit::{event::MouseButton, keyboard::KeyCode};
 #[cfg(feature = "mods")]
@@ -20,6 +21,21 @@ impl Game<'_> {
         false
     }
     pub(super) fn mod_key(&mut self, _key: KeyCode, _pressed: bool, _repeat: bool) {}
+    pub(super) fn mod_mouse_key(&mut self, _button: MouseButton, _pressed: bool) {}
+    pub(super) fn mod_wheel(&mut self, _steps: f32) -> bool {
+        false
+    }
+    pub(super) fn mod_zoom(&self) -> Option<ModZoom> {
+        None
+    }
+}
+
+/// A mod's zoom (`render.set-zoom`), clamped by the runtime.
+#[derive(Clone, Copy)]
+pub(super) struct ModZoom {
+    pub(super) factor: f32,
+    pub(super) smooth: bool,
+    pub(super) turn: f32,
 }
 
 #[cfg(feature = "mods")]
@@ -89,4 +105,46 @@ impl Game<'_> {
             self.mods.mods.key(name, pressed);
         }
     }
+    /// A mouse button while playing: a mod's key bound to it
+    /// (`key.mouse.4`...), as `mod_key`.
+    pub(super) fn mod_mouse_key(&mut self, button: MouseButton, pressed: bool) {
+        if self.mods.mods.has_keys() {
+            let name = horizon_client::keybinds::mouse_name(button);
+            self.mods.mods.key(&name, pressed);
+        }
+    }
+    /// Wheel steps while playing: true when a mod holds the wheel, so the
+    /// hotbar doesn't move.
+    pub(super) fn mod_wheel(&mut self, steps: f32) -> bool {
+        self.mods.mods.wheel(steps)
+    }
+    /// Playing, with nothing over the world: mods' keys and zoom apply.
+    fn mod_playing(&self) -> bool {
+        self.screen == Screen::Playing
+            && self.title.is_none()
+            && self.sign_edit.is_none()
+            && self.book.is_none()
+    }
+    /// Once a frame, before the mods run: a screen that opened lets their
+    /// held keys up.
+    pub(super) fn mod_input_frame(&mut self) {
+        let playing = self.mod_playing();
+        if self.mods.playing && !playing {
+            self.mods.mods.release_keys();
+        }
+        self.mods.playing = playing;
+    }
+    /// The strongest zoom a mod asks for, while playing; the spyglass's
+    /// own view wins.
+    pub(super) fn mod_zoom(&self) -> Option<ModZoom> {
+        if !self.mod_playing() || self.scoping() {
+            return None;
+        }
+        let z = self.mods.mods.zoom()?;
+        Some(ModZoom {
+            factor: z.factor,
+            smooth: z.smooth,
+            turn: z.turn,
+        })
+    }
 }
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 9d6015ad7..63e6314fd 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -55,6 +55,9 @@ pub(super) struct ModsState {
     /// The HUD font's advances for `render.text-width`, made once.
     #[cfg(feature = "mods")]
     font_widths: std::sync::Arc<[f32]>,
+    /// Playing at the last frame, for `mod_input_frame`.
+    #[cfg(feature = "mods")]
+    pub(super) playing: bool,
 }
 
 /// The mappings `input.mapping` answers for, with the default key their
@@ -399,6 +402,7 @@ impl Game<'_> {
         if !self.mods.mods.is_running() {
             return;
         }
+        self.mod_input_frame();
         if self.mods.mods.wants_frames() {
             let snapshot = self.mod_snapshot();
             self.mods.mods.set_snapshot(snapshot);
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index b787ff675..5cee9ef51 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -199,9 +199,13 @@ interface input {
         /// It came up again, or the item left the hand, or a screen opened.
         use-stop(item-use),
         /// A key `register-key` named went down or up while playing (no
-        /// screen open). The game's own mapping on that key still runs.
+        /// screen open). The game's own mapping on that key still runs. A
+        /// screen opening lets every held key up.
         key-down(string),
         key-up(string),
+        /// Mouse wheel steps while the mod holds the wheel (`claim-wheel`):
+        /// positive away from the player, as the hotbar reads them.
+        wheel(f32),
     }
     /// The items whose use the mod handles instead of the game, by id (at
     /// most 64). Replaces the previous list.
@@ -214,6 +218,10 @@ interface input {
     held: func() -> option<held-item>;
     /// The events since the last call, oldest first.
     poll: func() -> list<event>;
+    /// Takes the mouse wheel while playing (true) or gives it back: while
+    /// taken, its steps are the mod's `wheel` events and the hotbar doesn't
+    /// move. The game gives it back when the mod stops.
+    claim-wheel: func(on: bool);
     /// A mapping as the player has bound it.
     record mapping-state {
         /// The bound key's name as Controls shows it: `W`, `Space`, `LMB`.
@@ -331,6 +339,21 @@ interface render {
     }
     /// The game's frame counter, recomputed twice a second.
     frame-stats: func() -> frame-rate;
+    record zoom {
+        /// The field of view is divided by it: 1 is none, at most 10.
+        factor: f32,
+        /// Ease in and out through the game's field-of-view easing, as the
+        /// spyglass does, instead of at once.
+        smooth: bool,
+        /// Mouse turning is multiplied by it while zoomed: 1 keeps the
+        /// player's sensitivity, at least 0.05.
+        turn: f32,
+    }
+    /// Zooms the camera until the next call (`factor` 1 ends it), only
+    /// while playing: a screen opening or the spyglass's own view (which
+    /// wins) leave the camera vanilla's. With several mods, the strongest
+    /// zoom counts.
+    set-zoom: func(zoom: zoom);
 }
 
 /// What the game calls. Only the hooks `init` asks for are ever called.
diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs
index 9e998dae1..4dfd9af51 100644
--- a/crates/horizon-mods/src/manifest.rs
+++ b/crates/horizon-mods/src/manifest.rs
@@ -132,9 +132,9 @@ impl Capability {
             Capability::Storage => "save its own settings to disk",
             Capability::Registries => "add blocks and items to your worlds",
             Capability::Ui => "show its own screens and a settings page",
-            Capability::Render => "draw on your screen and shake the camera",
+            Capability::Render => "draw on your screen, shake and zoom the camera",
             Capability::Input => {
-                "see the keys you hold and your clicks, take over the use button on its own items, and add keys"
+                "see the keys you hold and your clicks, take over the use button on its own items and the mouse wheel, and add keys"
             }
         }
     }
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index f33839fe7..538b7edd5 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -53,7 +53,7 @@ pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, I
 /// What capability `render` asks the game to draw (WIT `interface render`).
 pub use render_bindings::horizon::mods::render::{
     Corner as RenderCorner, FillShape, FrameRate, ItemShape, Point as RenderPoint, QuadShape,
-    Rect as RenderRect, Shape, SpriteShape, TextShape,
+    Rect as RenderRect, Shape, SpriteShape, TextShape, Zoom as ModZoom,
 };
 use render_bindings::{RenderHost, horizon::mods::render};
 
@@ -189,6 +189,8 @@ struct State {
     shapes: Vec<Shape>,
     /// Capability `render`'s corner panel.
     corner: Option<CornerPanel>,
+    /// Capability `render`'s zoom, when the mod zooms.
+    zoom: Option<ModZoom>,
     input: InputState,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
@@ -331,6 +333,7 @@ impl Mods {
             ui: UiState::default(),
             shapes: Vec::new(),
             corner: None,
+            zoom: None,
             input: InputState::default(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
@@ -587,6 +590,16 @@ impl Mods {
                 .map(|k| k.name.clone())
                 .collect();
             for name in names {
+                let held = input.down.iter().position(|n| *n == name);
+                match (down, held) {
+                    (true, None) => input.down.push(name.clone()),
+                    (false, Some(i)) => {
+                        input.down.swap_remove(i);
+                    }
+                    // Already let go when a screen opened.
+                    (false, None) => continue,
+                    (true, Some(_)) => {}
+                }
                 input.push(if down {
                     InputEvent::KeyDown(name)
                 } else {
@@ -595,6 +608,35 @@ impl Mods {
             }
         }
     }
+    /// A screen opened, or the game stopped playing: every mod key held
+    /// lets go (`key-up`), so a key needs a new press afterwards.
+    pub fn release_keys(&mut self) {
+        for run in self.entries.iter_mut().filter_map(|e| e.run.as_mut()) {
+            let input = &mut run.store.data_mut().input;
+            for name in std::mem::take(&mut input.down) {
+                input.push(InputEvent::KeyUp(name));
+            }
+        }
+    }
+    /// Some running mod holds the mouse wheel.
+    pub fn wheel_claimed(&self) -> bool {
+        self.inputs().any(|i| i.wheel)
+    }
+    /// Wheel steps while playing: `wheel` to the mods holding it; false
+    /// when none does (the hotbar takes them).
+    pub fn wheel(&mut self, steps: f32) -> bool {
+        let event = InputEvent::Wheel(steps);
+        let claimed = self.wheel_claimed();
+        self.push_input(|i| i.wheel, &event);
+        claimed
+    }
+    /// The strongest zoom a running mod asks for (capability `render`).
+    pub fn zoom(&self) -> Option<ModZoom> {
+        self.entries
+            .iter()
+            .filter_map(|e| e.run.as_ref()?.store.data().zoom)
+            .max_by(|a, b| a.factor.total_cmp(&b.factor))
+    }
     fn inputs(&self) -> impl Iterator<Item = &InputState> {
         self.entries
             .iter()
@@ -824,6 +866,10 @@ struct InputState {
     claimed: Vec<String>,
     keys: Vec<ModKey>,
     events: std::collections::VecDeque<InputEvent>,
+    /// The mod's keys held now, by name.
+    down: Vec<String>,
+    /// It holds the mouse wheel.
+    wheel: bool,
 }
 /// Events kept for `poll`, items claimed and keys, per mod.
 const INPUT_EVENTS: usize = 256;
@@ -889,12 +935,19 @@ impl input::Host for State {
     fn clicks_per_second(&mut self) -> (u32, u32) {
         self.snapshot.cps
     }
+    fn claim_wheel(&mut self, on: bool) {
+        self.input.wheel = on;
+    }
 }
 
 /// HUD shapes one mod may keep (capability `render`).
 const SHAPES: usize = 1024;
 /// The longest jolt `render.shake` makes, in seconds.
 const SHAKE_SECONDS: f32 = 10.0;
+/// `render.set-zoom`'s limits: `Camera.tickFov` keeps the modifier at 0.1
+/// or more, and turning never stops.
+const ZOOM_MAX: f32 = 10.0;
+const TURN_MIN: f32 = 0.05;
 
 /// A mod's corner panel: shapes in a `width` × `height` box the game
 /// places in `corner`, stacked with the other overlays.
@@ -963,6 +1016,19 @@ impl render::Host for State {
             .sum::<f32>()
             .ceil()
     }
+    fn set_zoom(&mut self, zoom: ModZoom) {
+        let finite = |v: f32, lo: f32, hi: f32| if v.is_finite() { v.clamp(lo, hi) } else { lo };
+        let factor = finite(zoom.factor, 1.0, ZOOM_MAX);
+        self.zoom = (factor > 1.0).then(|| ModZoom {
+            factor,
+            smooth: zoom.smooth,
+            turn: if zoom.turn.is_finite() {
+                zoom.turn.clamp(TURN_MIN, 1.0)
+            } else {
+                1.0
+            },
+        });
+    }
     fn frame_stats(&mut self) -> FrameRate {
         let (fps, min, low) = self.snapshot.frame;
         FrameRate { fps, min, low }
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index a9de4f55b..780899289 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -506,6 +506,56 @@ fn input_claims_keys_and_events() {
     });
     assert!(mods.command("input_held"));
     assert_eq!(chat(&mut mods), ["holding minecraft:stick x3 in 2"]);
+    // A screen opening lets held keys up, once; the release that follows
+    // is not sent again.
+    mods.key("key.keyboard.r", true);
+    mods.release_keys();
+    mods.release_keys();
+    mods.key("key.keyboard.r", false);
+    assert!(mods.command("input_poll"));
+    assert_eq!(chat(&mut mods), ["key-down wheel", "key-up wheel"]);
+}
+
+#[test]
+fn input_wheel_is_the_mods_while_claimed() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    let chat = |mods: &mut Mods| -> Vec<String> {
+        mods.drain()
+            .into_iter()
+            .filter_map(|o| match o {
+                Output::Chat { text, .. } => Some(text),
+                _ => None,
+            })
+            .collect()
+    };
+    // Unclaimed, the hotbar keeps the wheel and the mod hears nothing.
+    assert!(!mods.wheel_claimed() && !mods.wheel(1.0));
+    assert!(mods.command("input_wheel"));
+    assert!(mods.wheel_claimed());
+    assert!(mods.wheel(1.0) && mods.wheel(-2.0));
+    assert!(mods.command("input_poll"));
+    assert_eq!(chat(&mut mods), ["wheel 1", "wheel -2"]);
+    assert!(mods.command("input_wheel off"));
+    assert!(!mods.wheel(1.0));
+}
+
+#[test]
+fn render_zoom_is_clamped_and_the_strongest_counts() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    let zoom = |mods: &mut Mods, args: &str| {
+        assert!(mods.command(&format!("zoom {args}")));
+        mods.zoom().map(|z| (z.factor, z.smooth, z.turn))
+    };
+    assert!(mods.zoom().is_none());
+    assert_eq!(zoom(&mut mods, "4 1 0.25"), Some((4.0, true, 0.25)));
+    // Over 10 and a turn under 0.05 are clamped.
+    assert_eq!(zoom(&mut mods, "50 0 0"), Some((10.0, false, 0.05)));
+    // A NaN turn keeps the player's sensitivity.
+    assert_eq!(zoom(&mut mods, "2 0 x"), Some((2.0, false, 1.0)));
+    // 1, under 1 and NaN end the zoom.
+    assert_eq!(zoom(&mut mods, "1 0 1"), None);
+    assert_eq!(zoom(&mut mods, "0.5 0 1"), None);
+    assert_eq!(zoom(&mut mods, "x 0 1"), None);
 }
 
 #[test]
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index ae6e4dfc4..1555b44f0 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -2,7 +2,8 @@
 //! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes
 //! the screen; the `ui-events` calls answer in chat so the host sees them.
 //! `/render_hud`, `/render_clear` and `/render_shake` test `render`;
-//! `/input_claim`, `/input_poll` and `/input_held` test `input`;
+//! `/input_claim`, `/input_poll`, `/input_held` and `/input_wheel` test
+//! `input`; `/zoom FACTOR SMOOTH TURN` tests `render.set-zoom`;
 //! `/corner` and `/readings` the calls the official extras mods use.
 use horizon_mod_sdk::{
     Mod, Registration, chat,
@@ -93,6 +94,8 @@ impl Mod for Guest {
             "input_claim",
             "input_poll",
             "input_held",
+            "input_wheel",
+            "zoom",
             "corner",
             "readings",
         ]
@@ -100,7 +103,7 @@ impl Mod for Guest {
         .fold(Registration::new(), Registration::command);
         Ok((Guest, hooks))
     }
-    fn command(&mut self, name: &str, _args: &str) -> Result<Option<String>, String> {
+    fn command(&mut self, name: &str, args: &str) -> Result<Option<String>, String> {
         match name {
             "ui_screen" => ui::open_screen(&Screen {
                 title: "Guest's screen".into(),
@@ -167,6 +170,7 @@ impl Mod for Guest {
                         Event::UseStop(u) => format!("use-stop {} {}", u.item.id, u.ticks),
                         Event::KeyDown(k) => format!("key-down {k}"),
                         Event::KeyUp(k) => format!("key-up {k}"),
+                        Event::Wheel(steps) => format!("wheel {steps}"),
                     });
                 }
             }
@@ -176,6 +180,19 @@ impl Mod for Guest {
                 });
                 chat::show(&format!("holding {held}"));
             }
+            "input_wheel" => input::claim_wheel(args != "off"),
+            "zoom" => {
+                let mut words = args.split(' ');
+                let mut number = || words.next().and_then(|w| w.parse().ok()).unwrap_or(f32::NAN);
+                let factor = number();
+                let smooth = number() == 1.0;
+                let turn = number();
+                render::set_zoom(render::Zoom {
+                    factor,
+                    smooth,
+                    turn,
+                });
+            }
             // Clamped to (1, 10); the two after it shake nothing.
             "render_shake" => {
                 render::shake(2.0, 99.0);
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index 333b65bd0..209a8298d 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -13,8 +13,8 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
 | `storage` | [`storage`](#storage) | save its own settings to disk |
 | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
 | `ui` | [`ui`](#ui) | show its own screens and a settings page |
-| `render` | [`render`](#render) | draw on your screen and shake the camera |
-| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items, and add keys |
+| `render` | [`render`](#render) | draw on your screen, shake and zoom the camera |
+| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items and the mouse wheel, and add keys |
 
 ## World `horizon-mod`
 
@@ -251,8 +251,9 @@ The main hand's stack.
 | --- | --- | --- |
 | `use-start` | `item-use` | The use button went down with a claimed item in the main hand. The game does nothing else with the click: no placing, no eating, no swing. |
 | `use-stop` | `item-use` | It came up again, or the item left the hand, or a screen opened. |
-| `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. |
+| `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. A screen opening lets every held key up. |
 | `key-up` | `string` |  |
+| `wheel` | `f32` | Mouse wheel steps while the mod holds the wheel (`claim-wheel`): positive away from the player, as the hotbar reads them. |
 
 ### record `mapping-state`
 
@@ -269,6 +270,7 @@ A mapping as the player has bound it.
 | `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`). At most 16; an unknown key is an error. |
 | `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
 | `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
+| `claim-wheel` | `func(on: bool)` | Takes the mouse wheel while playing (true) or gives it back: while taken, its steps are the mod's `wheel` events and the hotbar doesn't move. The game gives it back when the mod stops. |
 | `mapping` | `func(name: string) -> option<mapping-state>` | A movement or click mapping as the player has bound it: `key.forward`, `key.left`, `key.back`, `key.right`, `key.jump`, `key.sneak`, `key.sprint`, `key.attack` or `key.use`. None for another name. |
 | `clicks-per-second` | `func() -> tuple<u32, u32>` | Clicks of the attack and use buttons in the last second. |
 
@@ -369,6 +371,14 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun
 | `min` | `u32` | The slowest frame's rate, and the 1% low (the 99th percentile frame time's rate), over the last 5 seconds. |
 | `low` | `u32` |  |
 
+### record `zoom`
+
+| Field | Type | |
+| --- | --- | --- |
+| `factor` | `f32` | The field of view is divided by it: 1 is none, at most 10. |
+| `smooth` | `bool` | Ease in and out through the game's field-of-view easing, as the spyglass does, instead of at once. |
+| `turn` | `f32` | Mouse turning is multiplied by it while zoomed: 1 keeps the player's sensitivity, at least 0.05. |
+
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `set-hud` | `func(shapes: list<shape>)` | Replaces the mod's HUD shapes: up to 1024, drawn every frame in order over the HUD (after the hotbar, under chat and screens), hidden with the HUD (F1). An empty list removes them. |
@@ -378,6 +388,7 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun
 | `clear-corner` | `func()` | Removes the mod's corner panel. |
 | `text-width` | `func(text: string) -> f32` | The width of one line of text in GUI pixels, in the HUD's font: exact for Latin letters (U+0000 to U+024F), 6 per other character. |
 | `frame-stats` | `func() -> frame-rate` | The game's frame counter, recomputed twice a second. |
+| `set-zoom` | `func(zoom: zoom)` | Zooms the camera until the next call (`factor` 1 ends it), only while playing: a screen opening or the spyglass's own view (which wins) leave the camera vanilla's. With several mods, the strongest zoom counts. |
 
 ## `events`
 
diff --git a/docs/api/stability.md b/docs/api/stability.md
index b513d5ddf..485d805af 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -88,8 +88,8 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
 | --- | --- | --- |
 | Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
 | Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` |
-| Mod API: `render` (HUD shapes, camera shake; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` |
-| Mod API: `input` (claimed items' use, the mod's keys) | experimental | manifest `experimental = ["input"]` |
+| Mod API: `render` (HUD shapes, camera shake and zoom; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` |
+| Mod API: `input` (claimed items' use, the mod's keys, the mouse wheel) | experimental | manifest `experimental = ["input"]` |
 | Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
 | Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first |
 | Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
@@ -104,3 +104,12 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
 | Telemetry batch and consent | stable | `"schema": 1`, consent `2` |
 | `horizon-graphics.txt`, `horizon-extras.txt`, `horizon-mods.txt` | preview | none |
 | `SHA256SUMS` and `SHA256SUMS.sig` | stable | |
+
+### The experimental mod APIs' choices
+
+- **What a mod may take from the game.** `input.claim-wheel` is the one input a mod consumes: while it holds the
+  wheel, the steps are its `wheel` events and the hotbar doesn't move. `claim-items` takes the use button only on the
+  items it names. A mod's keys (`register-key`) never consume: vanilla's mapping on the same key still runs. Whether
+  keys may consume too is decided before `input` becomes preview.
+- **`input`'s `wheel` event** is a new case in a variant the game sends, so it breaks mods built before it (allowed
+  because `input` is experimental): an `input` mod that calls `poll` needs a rebuild against the new WIT.
diff --git a/docs/mods.md b/docs/mods.md
index d92c88fa6..9a75badb6 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -87,8 +87,8 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
-| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects. The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
-| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
+| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
+| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 
 | Hook (export) | When |
 |---|---|

From 2c612fd791c787ca4415439dfa9fc696798395af Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 03:10:55 +0100
Subject: [PATCH 249/270] ci: parity-main on the release runner, not behind PR
 parity jobs

The queued parity-main run waited 2 h behind PR parity jobs on the two
horizon-game runners, each merge replacing the pending one, and releases
need it green. The release runner gets a horizon-parity-main label; a
release only starts after parity-main passed, so the two never compete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity-main.yml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/parity-main.yml b/.github/workflows/parity-main.yml
index 1debcc694..13be3c36d 100644
--- a/.github/workflows/parity-main.yml
+++ b/.github/workflows/parity-main.yml
@@ -23,9 +23,11 @@ env:
 
 jobs:
   parity-main:
-    # The Mac mini's runners only: a desktop job slowed down because the maintainer came back could time out, and a
-    # failure here bisects and comments on merges.
-    runs-on: [self-hosted, horizon-game, macOS]
+    # The Mac mini's release runner (label added 2026-10-26), not the two `horizon-game` runners: behind PR parity jobs
+    # this run waited 2 h while every merge replaced the pending one, and releases wait for it. Releases need it green
+    # first, so the two never compete. Not the desktop: a job slowed down because the maintainer came back could time
+    # out, and a failure here bisects and comments on merges.
+    runs-on: [self-hosted, macOS, horizon-parity-main]
     timeout-minutes: 240  # a core-crate batch reruns ~300 harnesses (~60-90 min), a bisect a few rounds of the failures
     steps:
       - uses: actions/checkout@v4

From 0c84eb30793b461072407eed9bb8c60db480fe19 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 03:18:39 +0100
Subject: [PATCH 250/270] ci: PR parity jobs prepare vanilla data with main's
 script

A PR head older than the fix in vanilla-data.sh left a real
.local/horizon-client without sounds.json on runner ludovics-mac-mini;
every later job there failed subtitle. Like the harness selection, the
job now runs main's script unless the branch changes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity.yml | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/parity.yml b/.github/workflows/parity.yml
index 577380338..b48be1d05 100644
--- a/.github/workflows/parity.yml
+++ b/.github/workflows/parity.yml
@@ -36,7 +36,19 @@ jobs:
       - name: Tools from the runner
         run: bash tools/ci/runner-env.sh
       - name: Vanilla data, and resources prepared by this preparer
-        run: bash tools/ci/vanilla-data.sh
+        env:
+          BASE_SHA: ${{ inputs.base }}
+        run: |
+          # main's script: one written before a fix to it left a real .local/horizon-client without sounds.json on
+          # the runner, and every later job there failed `subtitle`. A branch that changes the script runs its own.
+          set -euo pipefail
+          if git rev-parse --verify -q origin/main >/dev/null \
+            && git diff --quiet "$(git merge-base "$BASE_SHA" HEAD)" HEAD -- tools/ci/vanilla-data.sh; then
+            git show origin/main:tools/ci/vanilla-data.sh > "$RUNNER_TEMP/vanilla-data.sh"
+            bash "$RUNNER_TEMP/vanilla-data.sh"
+          else
+            bash tools/ci/vanilla-data.sh
+          fi
       - name: The prepared output is the one the preparer's OUTPUT_VERSION says
         env:
           BASE_SHA: ${{ inputs.base }}

From 7d4792fb3166b83674b2abf048293908deb7cd9b Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:03:03 +0100
Subject: [PATCH 251/270] Mods API reference test: follow wit-parser 0.254
 (FixedLengthList, Param)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 crates/horizon-mods/tests/api_reference.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-mods/tests/api_reference.rs b/crates/horizon-mods/tests/api_reference.rs
index 5e6a0a069..b3d2363a9 100644
--- a/crates/horizon-mods/tests/api_reference.rs
+++ b/crates/horizon-mods/tests/api_reference.rs
@@ -52,7 +52,7 @@ fn definition(resolve: &Resolve, kind: &TypeDefKind) -> String {
     match kind {
         TypeDefKind::Option(t) => format!("option<{}>", ty(resolve, t)),
         TypeDefKind::List(t) => format!("list<{}>", ty(resolve, t)),
-        TypeDefKind::FixedSizeList(t, n) => format!("list<{}, {n}>", ty(resolve, t)),
+        TypeDefKind::FixedLengthList(t, n) => format!("list<{}, {n}>", ty(resolve, t)),
         TypeDefKind::Result(r) => match (&r.ok, &r.err) {
             (None, None) => "result".into(),
             (ok, None) => format!("result<{}>", of(ok)),
@@ -82,7 +82,7 @@ fn signature(resolve: &Resolve, f: &Function) -> String {
     let params: Vec<_> = f
         .params
         .iter()
-        .map(|(name, t)| format!("{name}: {}", ty(resolve, t)))
+        .map(|p| format!("{}: {}", p.name, ty(resolve, &p.ty)))
         .collect();
     let result = f
         .result

From c89434557b2a60283485d28fea0ed0b6806c6fc3 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:09:25 +0100
Subject: [PATCH 252/270] Player heads without a skin show slim steve, as
 vanilla

SkullBlockRenderer's SKIN_BY_TYPE is DefaultPlayerSkin.getDefaultTexture(),
DEFAULT_SKINS[6] = entity/player/slim/steve; the block_entity_render harness
found Horizon drawing nothing for heads without a profile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/block_entity_render.rs | 4 ++--
 crates/horizon-client/src/containers.rs          | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/block_entity_render.rs b/crates/horizon-client/src/block_entity_render.rs
index 620640188..10c5e2509 100644
--- a/crates/horizon-client/src/block_entity_render.rs
+++ b/crates/horizon-client/src/block_entity_render.rs
@@ -732,7 +732,7 @@ pub struct Scene<'a> {
     pub banner: &'a dyn Fn([i32; 3]) -> Vec<(String, u32)>,
     /// The skin sprite a `player_head` shows at a position (`SkullBlockRenderer`
     /// profile → skin): a downloaded `skins/<sha1>` slot or the profile's
-    /// `DefaultPlayerSkin` fallback; None keeps `SKIN_BY_TYPE` (steve).
+    /// `DefaultPlayerSkin` fallback; None keeps `SKIN_BY_TYPE` (`DefaultPlayerSkin.getDefaultTexture`, slim steve).
     pub skull: &'a dyn Fn([i32; 3]) -> Option<&'a str>,
     /// Font glyph cell (none for blank glyphs such as the space) and advance.
     pub glyph: &'a dyn Fn(char) -> (Option<Rect>, f32),
@@ -1281,7 +1281,7 @@ impl BlockEntityRenderer {
                     SkullType::Creeper => ("creeper_head", "entity/creeper/creeper"),
                     SkullType::Dragon => ("dragon_skull", "entity/enderdragon/dragon"),
                     SkullType::Piglin => ("piglin_head", "entity/piglin/piglin"),
-                    SkullType::Player => ("player_head", "entity/player/wide/steve"),
+                    SkullType::Player => ("player_head", "entity/player/slim/steve"),
                 };
                 // SkullBlockRenderer.getRenderType: the profile's skin when it
                 // resolves, `SKIN_BY_TYPE` (steve) otherwise.
diff --git a/crates/horizon-client/src/containers.rs b/crates/horizon-client/src/containers.rs
index 1f8fad151..a968408db 100644
--- a/crates/horizon-client/src/containers.rs
+++ b/crates/horizon-client/src/containers.rs
@@ -123,8 +123,9 @@ impl SkullSkin {
             let location = crate::skins::skin_location(&crate::skins::texture_hash(&url)?);
             Some((url, location))
         });
+        // DefaultPlayerSkin.get(id), or getDefaultSkin (slim steve) without an id.
         let fallback = crate::skins::profile_uuid_nbt(profile)
-            .map_or("entity/player/wide/steve", crate::tab_list::default_skin);
+            .map_or("entity/player/slim/steve", crate::tab_list::default_skin);
         Self { download, fallback }
     }
 }

From de294e34bbddb7bb2e8dc48c86efe1c662421e53 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:19:07 +0100
Subject: [PATCH 253/270] rustfmt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/extras.rs      | 6 +++++-
 crates/horizon-mods/tests/ui_guest/src/lib.rs | 7 ++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index 1978d003f..a04196b69 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -234,7 +234,11 @@ impl Game<'_> {
     fn zoom_now(&self) -> (f32, bool, f64) {
         let factor = self.zoom_factor();
         let e = &self.settings.extras;
-        let own = (factor, e.zoom_smooth, turn_scale(factor, e.zoom_sensitivity));
+        let own = (
+            factor,
+            e.zoom_smooth,
+            turn_scale(factor, e.zoom_sensitivity),
+        );
         match self.mod_zoom() {
             Some(z) if z.factor > factor => (z.factor, z.smooth, f64::from(z.turn)),
             _ => own,
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index 1555b44f0..9bede11f9 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -183,7 +183,12 @@ impl Mod for Guest {
             "input_wheel" => input::claim_wheel(args != "off"),
             "zoom" => {
                 let mut words = args.split(' ');
-                let mut number = || words.next().and_then(|w| w.parse().ok()).unwrap_or(f32::NAN);
+                let mut number = || {
+                    words
+                        .next()
+                        .and_then(|w| w.parse().ok())
+                        .unwrap_or(f32::NAN)
+                };
                 let factor = number();
                 let smooth = number() == 1.0;
                 let turn = number();

From 2256941af73b77d540de4b3fa74351f45ac0deee Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:23:25 +0100
Subject: [PATCH 254/270] Chat: mod output lines are the client's own

Main's mod output calls Chat::add without the new source; a mod's line is
written by this client, so the Chat option keeps it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/mods.rs | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 667c06335..fbf92237d 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -454,10 +454,16 @@ impl Game<'_> {
                 }
             };
             // Not through system_message: a mod must not hear its own lines.
+            // Written by this client, so the Chat option doesn't hide it.
             let focused = self.screen == Screen::Chat;
-            self.ui
-                .chat
-                .add(&self.gui.atlas, line, None, self.ticks, focused);
+            self.ui.chat.add(
+                &self.gui.atlas,
+                line,
+                None,
+                horizon_client::chat::ChatSource::Client,
+                self.ticks,
+                focused,
+            );
         }
         // A mod may set or clear its settings page in any call, not only
         // while loading: its row's Settings button follows.

From 7e4012c83ec859b5fa18f6f5975e49f97719854a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:41:12 +0100
Subject: [PATCH 255/270] Mod API: a key widget, so players bind a mod's keys
 (ui, input)

A ui page's key widget shows one of the mod's keys as Key Binds does
("Zoom: Z"). A click waits for the next key or mouse button, which
becomes the key; Esc binds none. The game keeps the choice in
horizon-mods.txt (key.<mod>.<name>:key.keyboard.z), applies it when
the mods load and to keys registered later, and lets a held key go when
it is rebound. register-key's key is now the default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game.rs             |   7 +-
 crates/horizon-client/src/game/mods.rs        | 123 +++++++++++++++++-
 crates/horizon-client/src/mod_list.rs         |  52 +++++++-
 crates/horizon-mod-sdk/wit/horizon.wit        |  15 ++-
 crates/horizon-mods/src/runtime.rs            |  67 +++++++++-
 crates/horizon-mods/tests/sandbox.rs          |  41 +++++-
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  11 +-
 docs/api/mods-reference.md                    |  12 +-
 docs/mods.md                                  |   2 +-
 9 files changed, 312 insertions(+), 18 deletions(-)

diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 3f7450501..bb68dc590 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -10451,6 +10451,9 @@ impl Game<'_> {
             }
             return Ok(());
         }
+        if self.screen == Screen::Mod && self.mod_screen_key(key) {
+            return Ok(());
+        }
         if self.sort_key_press(key) {
             return Ok(());
         }
@@ -11363,9 +11366,7 @@ impl ApplicationHandler for Game<'_> {
                                 .map_or([1, 1], |r| [r.config.width, r.config.height]);
                             self.stats_click(size);
                         }
-                        Screen::Mod if pressed && button == MouseButton::Left => {
-                            self.mod_screen_click()
-                        }
+                        Screen::Mod if pressed => self.mod_screen_click(button),
                         _ => {}
                     }
                 }
diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 6211f43b1..66d00b233 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -29,6 +29,7 @@ use {
     },
     horizon_mods::{Clock, Mods, Output, Player, Snapshot, Status, UiScreen, UiWidget},
     std::time::Instant,
+    winit::{event::MouseButton, keyboard::KeyCode},
 };
 
 #[derive(Default)]
@@ -101,6 +102,8 @@ struct ModScreen {
     under: Screen,
     /// One scroll per `list` widget, in widget order.
     scrolls: Vec<ui::Scroll>,
+    /// A key widget waiting for the key to bind: the mod key's name.
+    binding: Option<String>,
 }
 impl ModsState {
     /// The chat's command tree: vanilla's, plus the running mods' commands.
@@ -240,7 +243,10 @@ impl Game<'_> {
     pub(super) fn open_mod_screen(&mut self, _owner: usize, _settings: bool) {}
     pub(super) fn close_mod_screen(&mut self, _tell: bool) {}
     pub(super) fn draw_mod_screen(&mut self, _batch: &mut HudBatch) {}
-    pub(super) fn mod_screen_click(&mut self) {}
+    pub(super) fn mod_screen_click(&mut self, _button: winit::event::MouseButton) {}
+    pub(super) fn mod_screen_key(&mut self, _key: winit::keyboard::KeyCode) -> bool {
+        false
+    }
     pub(super) fn mod_screen_scroll(&mut self, _delta: f32) {}
 }
 
@@ -263,6 +269,8 @@ impl Game<'_> {
         let on = |id: &str| enabled.contains(id) || dev_ids.iter().any(|d| d == id);
         let mods = Mods::load(&paths, on, vanilla_command);
         self.mods.mods = mods;
+        let chosen = &self.settings.mods;
+        self.mods.mods.set_bindings(|id| chosen.keys_of(id));
         // Entries were replaced wholesale: a screen's owner index is stale.
         self.mods.screen = None;
         self.list_mods();
@@ -429,6 +437,8 @@ impl Game<'_> {
         {
             self.mods.checked = Some(Instant::now());
             if self.mods.mods.reload_changed(vanilla_command) {
+                let chosen = &self.settings.mods;
+                self.mods.mods.set_bindings(|id| chosen.keys_of(id));
                 self.list_mods();
                 self.sync_mod_commands();
                 self.system_message(Text::literal("Mods reloaded").with_color(text::GRAY));
@@ -579,6 +589,72 @@ impl Game<'_> {
             Some((s.title.as_str(), s.widgets.as_slice()))
         }
     }
+    /// A key widget's label as Key Binds shows one, "Zoom: Z", marked
+    /// "> Zoom: Z <" in yellow while it waits for the new key.
+    fn mod_key_label(mods: &Mods, owner: usize, name: &str, waiting: bool) -> Text {
+        let (label, key) = mods
+            .keys_of(owner)
+            .iter()
+            .find(|k| k.name == name)
+            .map_or((name, "key.keyboard.unknown"), |k| {
+                (k.label.as_str(), k.key.as_str())
+            });
+        let value = format!("{label}: {}", keybinds::display_name(key).plain());
+        if waiting {
+            Text::literal(format!("> {value} <")).with_color(text::YELLOW)
+        } else {
+            Text::literal(value)
+        }
+    }
+    /// The player bound the key widget that waited to `key`: the mod's key
+    /// follows it now and at the next start (`horizon-mods.txt`).
+    fn bind_mod_key(&mut self, key: String) {
+        let Some(ms) = self.mods.screen.as_mut() else {
+            return;
+        };
+        let Some(name) = ms.binding.take() else {
+            return;
+        };
+        let owner = ms.owner;
+        if !self.mods.mods.rebind(owner, &name, &key) {
+            return;
+        }
+        let Some(id) = self
+            .mods
+            .mods
+            .entries()
+            .get(owner)
+            .and_then(|e| e.manifest.as_ref())
+            .map(|m| m.id.clone())
+        else {
+            return;
+        };
+        self.settings
+            .mods
+            .keys
+            .entry(id)
+            .or_default()
+            .insert(name, key);
+        self.settings.save(&Self::options_path());
+    }
+    /// A key while a mod screen is up: true when a key widget waited for
+    /// it (Key Binds: Escape binds none).
+    pub(super) fn mod_screen_key(&mut self, key: KeyCode) -> bool {
+        if self
+            .mods
+            .screen
+            .as_ref()
+            .is_none_or(|ms| ms.binding.is_none())
+        {
+            return false;
+        }
+        let value = match key {
+            KeyCode::Escape => None,
+            k => keybinds::key_name(k),
+        };
+        self.bind_mod_key(value.unwrap_or("key.keyboard.unknown").to_owned());
+        true
+    }
     /// The layout the mod screen's widgets get at `h`: (widget, top,
     /// height), the column being `COLUMN` wide down the middle.
     fn mod_ui_layout(h: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
@@ -587,7 +663,7 @@ impl Game<'_> {
         for w in widgets {
             let wh = match w {
                 UiWidget::Text(_) => 12.0,
-                UiWidget::Item(_) | UiWidget::Button(_) => 20.0,
+                UiWidget::Item(_) | UiWidget::Button(_) | UiWidget::Key(_) => 20.0,
                 UiWidget::List(l) => (l.rows.len().min(6) as f32 * 12.0) + 8.0,
             };
             // Nothing may cover Done; a crowded mod loses what won't fit.
@@ -617,6 +693,7 @@ impl Game<'_> {
             settings,
             under: self.screen,
             scrolls: Vec::new(),
+            binding: None,
         });
         self.screen = Screen::Mod;
         if self.player.is_some() {
@@ -697,6 +774,22 @@ impl Game<'_> {
                         hover,
                     );
                 }
+                UiWidget::Key(k) => {
+                    let hover = ui::hovered(self.cursor, x, wy, MOD_UI_COLUMN, 20.0);
+                    let waiting = ms.binding.as_deref() == Some(k.key.as_str());
+                    let label = Self::mod_key_label(&self.mods.mods, ms.owner, &k.key, waiting);
+                    ui::button(
+                        batch,
+                        atlas,
+                        x,
+                        wy,
+                        MOD_UI_COLUMN,
+                        20.0,
+                        &label,
+                        true,
+                        hover,
+                    );
+                }
                 UiWidget::Text(t) => {
                     let color = if t.color == 0 {
                         u32::MAX
@@ -798,7 +891,20 @@ impl Game<'_> {
     }
     /// A click on the mod screen: Done leaves it, a `list` row is the mod's
     /// `ui-events::select`.
-    pub(super) fn mod_screen_click(&mut self) {
+    pub(super) fn mod_screen_click(&mut self, button: MouseButton) {
+        // Key Binds: a mouse button pressed while waiting binds it.
+        if self
+            .mods
+            .screen
+            .as_ref()
+            .is_some_and(|ms| ms.binding.is_some())
+        {
+            self.bind_mod_key(keybinds::mouse_name(button));
+            return;
+        }
+        if button != MouseButton::Left {
+            return;
+        }
         let (w, h) = self.gui_size();
         let cursor = self.cursor;
         if ui::hovered(cursor, (w / 2.0).floor() - 100.0, h - 27.0, 200.0, 20.0) {
@@ -829,6 +935,17 @@ impl Game<'_> {
                 self.show_mod_output();
                 return;
             }
+            // A key widget waits for the key to bind.
+            if let UiWidget::Key(k) = w
+                && ui::hovered(cursor, x, wy, MOD_UI_COLUMN, 20.0)
+            {
+                self.audio.play_button_click();
+                let name = k.key.clone();
+                if let Some(ms) = self.mods.screen.as_mut() {
+                    ms.binding = Some(name);
+                }
+                return;
+            }
             let UiWidget::List(l) = w else { continue };
             let scroll = ms.scrolls.get(list_i).copied().unwrap_or_default();
             list_i += 1;
diff --git a/crates/horizon-client/src/mod_list.rs b/crates/horizon-client/src/mod_list.rs
index db2ea9194..325839738 100644
--- a/crates/horizon-client/src/mod_list.rs
+++ b/crates/horizon-client/src/mod_list.rs
@@ -1,7 +1,11 @@
 //! Which of the installed Horizon mods are on (`docs/mods.md`), kept in
 //! `horizon-mods.txt` beside `options.txt` as `mod.<id>:true` lines. Every
 //! mod is off until the player turns it on in Options > Mods.
-use std::{collections::BTreeSet, fs, path::Path};
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs,
+    path::Path,
+};
 
 pub const FILE: &str = "horizon-mods.txt";
 /// The folder holding `.hmod` files, beside `options.txt`.
@@ -11,6 +15,9 @@ pub const DIR: &str = "horizon-mods";
 pub struct ModList {
     /// Ids of the mods the player turned on.
     pub enabled: BTreeSet<String>,
+    /// The keys the player chose for mods' keys, mod id → key name → key
+    /// (`key.<id>.<name>:key.keyboard.x` lines).
+    pub keys: BTreeMap<String, BTreeMap<String, String>>,
     /// What the Mods page shows, filled by the game from the mods it found.
     pub installed: Vec<Installed>,
 }
@@ -45,20 +52,41 @@ impl ModList {
             .filter_map(|(k, _)| k.trim().strip_prefix("mod."))
             .map(str::to_owned)
             .collect();
+        let mut keys: BTreeMap<String, BTreeMap<String, String>> = BTreeMap::new();
+        for (k, v) in text.lines().filter_map(|l| l.split_once(':')) {
+            // Mod ids have no dots; a key's name may.
+            if let Some((id, name)) = k
+                .trim()
+                .strip_prefix("key.")
+                .and_then(|r| r.split_once('.'))
+            {
+                let entry = keys.entry(id.to_owned()).or_default();
+                entry.insert(name.to_owned(), v.trim().to_owned());
+            }
+        }
         Self {
             enabled,
+            keys,
             installed: Vec::new(),
         }
     }
     pub fn serialize(&self) -> String {
-        self.enabled
-            .iter()
-            .map(|id| format!("mod.{id}:true\n"))
-            .collect()
+        let on = self.enabled.iter().map(|id| format!("mod.{id}:true\n"));
+        let keys = self.keys.iter().flat_map(|(id, keys)| {
+            keys.iter()
+                .map(move |(name, key)| format!("key.{id}.{name}:{key}\n"))
+        });
+        on.chain(keys).collect()
+    }
+    /// Mod `id`'s chosen keys, for `Mods::set_bindings`.
+    pub fn keys_of(&self, id: &str) -> Vec<(&str, &str)> {
+        self.keys.get(id).map_or_else(Vec::new, |k| {
+            k.iter().map(|(n, k)| (n.as_str(), k.as_str())).collect()
+        })
     }
     pub fn save(&self, dir: &Path) {
         let path = dir.join(FILE);
-        if self.enabled.is_empty() && !path.exists() {
+        if self.enabled.is_empty() && self.keys.is_empty() && !path.exists() {
             return;
         }
         let _ = fs::write(path, self.serialize());
@@ -91,6 +119,18 @@ mod tests {
         assert_eq!(ModList::default().serialize(), "");
     }
 
+    #[test]
+    fn keeps_the_keys_players_chose() {
+        let text = "mod.zoom:true\nkey.zoom.zoom.in:key.mouse.4\nkey.zoom.out:key.keyboard.x\n";
+        let list = ModList::parse(text);
+        assert_eq!(
+            list.keys_of("zoom"),
+            [("out", "key.keyboard.x"), ("zoom.in", "key.mouse.4")]
+        );
+        assert!(list.keys_of("other").is_empty());
+        assert_eq!(ModList::parse(&list.serialize()), list);
+    }
+
     #[test]
     fn toggles_installed_mods_but_not_dev_ones() {
         let installed = |id: &str, dev| Installed {
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 820a82483..f9c147cfa 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -137,6 +137,16 @@ interface ui {
         /// Up to 256 characters.
         label: string,
     }
+    /// One of the mod's keys (`input.register-key`) as Controls shows a
+    /// binding, "Zoom: Z". A click waits for the next key or mouse button,
+    /// which becomes the key (Esc: none). The game keeps the player's
+    /// choice across starts; the mod's `key-down` and `key-up` follow it.
+    record key-widget {
+        /// The mod's own name for the widget.
+        id: u32,
+        /// The name the mod registered the key under.
+        key: string,
+    }
     variant widget {
         /// Text the player reads.
         text(text-widget),
@@ -146,6 +156,8 @@ interface ui {
         item(item-widget),
         /// Rows the player picks from.
         %list(list-widget),
+        /// A key the player binds.
+        key(key-widget),
     }
     /// A screen the mod owns: a title over widgets stacked down the middle,
     /// the Done button the game adds, and Esc to leave it.
@@ -220,7 +232,8 @@ interface input {
     claim-items: func(ids: list<string>);
     /// A key of the mod's: `name` comes back in `key-down` and `key-up`,
     /// `label` says what it does, `key` is the key as options.txt writes
-    /// it (`key.keyboard.r`). At most 16; an unknown key is an error.
+    /// it (`key.keyboard.r`), the default: a key the player chose for it
+    /// (`ui`'s key widget) wins. At most 16; an unknown key is an error.
     register-key: func(name: string, label: string, key: string) -> result<_, string>;
     /// The main hand's stack, as of this tick; none when it is empty.
     held: func() -> option<held-item>;
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 0e7c079d2..f596db81c 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -37,7 +37,8 @@ use bindings::{
 /// The widget model a `ui` screen or settings page shows (WIT `interface
 /// ui`), for the game to draw with its menus' own widgets.
 pub use ui_bindings::horizon::mods::ui::{
-    ButtonWidget, ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
+    ButtonWidget, ItemWidget, KeyWidget, ListWidget, Screen as UiScreen, TextWidget,
+    Widget as UiWidget,
 };
 use ui_bindings::{UiHost, horizon::mods::ui};
 /// Capability `render`'s imports (docs/mods.md): the game draws the shapes.
@@ -564,6 +565,48 @@ impl Mods {
                 d.input.keys.iter().map(move |k| (d.name.as_str(), k))
             })
     }
+    /// Mod `i`'s keys, as it registered them (with the player's choices).
+    pub fn keys_of(&self, i: usize) -> &[ModKey] {
+        self.entries
+            .get(i)
+            .and_then(|e| e.run.as_ref())
+            .map_or(&[], |r| r.store.data().input.keys.as_slice())
+    }
+    /// The keys the player chose (`ui`'s key widget), by mod id: each
+    /// running mod's `name → key`. They replace the defaults registered
+    /// so far and later ones. Keys that aren't keys are skipped.
+    pub fn set_bindings<'a>(&mut self, chosen: impl Fn(&str) -> Vec<(&'a str, &'a str)>) {
+        for e in &mut self.entries {
+            let (Some(m), Some(run)) = (&e.manifest, e.run.as_mut()) else {
+                continue;
+            };
+            let input = &mut run.store.data_mut().input;
+            input.bindings = chosen(&m.id)
+                .into_iter()
+                .filter(|(_, key)| key_ok(key))
+                .map(|(n, k)| (n.to_owned(), k.to_owned()))
+                .collect();
+            for (name, key) in input.bindings.clone() {
+                input.rebind(&name, key);
+            }
+        }
+    }
+    /// The player binds mod `i`'s key `name` to `key` (`key.keyboard.x`,
+    /// `key.mouse.4`, `key.keyboard.unknown` for none). False when the mod
+    /// has no such key or `key` isn't one.
+    pub fn rebind(&mut self, i: usize, name: &str, key: &str) -> bool {
+        let Some(run) = self.entries.get_mut(i).and_then(|e| e.run.as_mut()) else {
+            return false;
+        };
+        let input = &mut run.store.data_mut().input;
+        if !key_ok(key) || !input.keys.iter().any(|k| k.name == name) {
+            return false;
+        }
+        input.bindings.retain(|(n, _)| n != name);
+        input.bindings.push((name.to_owned(), key.to_owned()));
+        input.rebind(name, key.to_owned());
+        true
+    }
     /// The use button went down with `item`: `use-start` to each mod that
     /// claimed it.
     pub fn use_start(&mut self, item: &HeldItem) {
@@ -813,6 +856,10 @@ fn clip_widgets(widgets: Vec<UiWidget>) -> Vec<UiWidget> {
                 l.selected = l.selected.filter(|&s| (s as usize) < l.rows.len());
                 UiWidget::List(l)
             }
+            UiWidget::Key(mut k) => {
+                k.key = clip(k.key);
+                UiWidget::Key(k)
+            }
         })
         .collect()
 }
@@ -873,6 +920,9 @@ struct InputState {
     down: Vec<String>,
     /// It holds the mouse wheel.
     wheel: bool,
+    /// The keys the player chose, `name → key`: they win over
+    /// `register-key`'s.
+    bindings: Vec<(String, String)>,
 }
 /// Events kept for `poll`, items claimed and keys, per mod.
 const INPUT_EVENTS: usize = 256;
@@ -893,6 +943,17 @@ fn key_ok(key: &str) -> bool {
 }
 
 impl InputState {
+    /// Key `name` is `key` now; held, it lets go first.
+    fn rebind(&mut self, name: &str, key: String) {
+        let Some(k) = self.keys.iter_mut().find(|k| k.name == name) else {
+            return;
+        };
+        k.key = key;
+        if let Some(i) = self.down.iter().position(|n| n == name) {
+            let name = self.down.swap_remove(i);
+            self.push(InputEvent::KeyUp(name));
+        }
+    }
     fn push(&mut self, event: InputEvent) {
         if self.events.len() == INPUT_EVENTS {
             self.events.pop_front();
@@ -912,6 +973,10 @@ impl input::Host for State {
             ));
         }
         let (name, label) = (clip(name), clip(label));
+        let key = match self.input.bindings.iter().find(|(n, _)| *n == name) {
+            Some((_, chosen)) => chosen.clone(),
+            None => key,
+        };
         if let Some(k) = self.input.keys.iter_mut().find(|k| k.name == name) {
             (k.label, k.key) = (label, key);
             return Ok(());
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index 29577a9c6..793d03db6 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -449,7 +449,7 @@ fn ui_screens_settings_and_events() {
     assert_eq!(mods.settings_widgets(0).len(), 3);
     assert!(mods.entries()[0].has_ui_settings());
     mods.ui_settings_opened(0);
-    assert_eq!(mods.settings_widgets(0).len(), 2);
+    assert_eq!(mods.settings_widgets(0).len(), 3);
     // `/ui_close` closes the mod's own screen.
     assert!(mods.command("ui_close"));
     assert!(mods.drain().contains(&Output::CloseScreen { owner: 0 }));
@@ -553,6 +553,45 @@ fn input_claims_keys_and_events() {
     assert_eq!(chat(&mut mods), ["key-down wheel", "key-up wheel"]);
 }
 
+#[test]
+fn the_players_key_choice_wins() {
+    let chat = |mods: &mut Mods| -> Vec<String> {
+        mods.drain()
+            .into_iter()
+            .filter_map(|o| match o {
+                Output::Chat { text, .. } => Some(text),
+                _ => None,
+            })
+            .collect()
+    };
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    assert!(mods.command("input_claim"));
+    assert!(matches!(
+        &mods.settings_widgets(0)[0],
+        horizon_mods::UiWidget::Key(k) if k.id == 9 && k.key == "wheel"
+    ));
+    // Rebinding while held lets the old key go.
+    mods.key("key.keyboard.r", true);
+    assert!(mods.rebind(0, "wheel", "key.mouse.4"));
+    assert_eq!(mods.keys_of(0)[0].key, "key.mouse.4");
+    mods.key("key.keyboard.r", false);
+    mods.key("key.mouse.4", true);
+    assert!(!mods.rebind(0, "wheel", "R") && !mods.rebind(0, "nope", "key.keyboard.g"));
+    chat(&mut mods);
+    assert!(mods.command("input_poll"));
+    assert_eq!(
+        chat(&mut mods),
+        ["key-down wheel", "key-up wheel", "key-down wheel"]
+    );
+    // A choice saved earlier replaces the default, registered before or after.
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    mods.set_bindings(|_| vec![("wheel", "key.keyboard.g"), ("bad", "G")]);
+    assert!(mods.command("input_claim"));
+    assert_eq!(mods.keys_of(0)[0].key, "key.keyboard.g");
+    mods.set_bindings(|_| vec![("wheel", "key.keyboard.h")]);
+    assert_eq!(mods.keys_of(0)[0].key, "key.keyboard.h");
+}
+
 #[test]
 fn input_wheel_is_the_mods_while_claimed() {
     let mut mods = load("horizon_mods_test_ui_guest.hmod");
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index 9bede11f9..f2765e8da 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -9,7 +9,7 @@ use horizon_mod_sdk::{
     Mod, Registration, chat,
     input::{self, Event},
     render::{self, FillShape, ItemShape, Point, QuadShape, Rect, Shape, SpriteShape, TextShape},
-    ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
+    ui::{self, ItemWidget, KeyWidget, ListWidget, Screen, TextWidget, Widget},
 };
 
 /// One of each shape, the text too long by 44 characters.
@@ -162,6 +162,10 @@ impl Mod for Guest {
                 // Not a key: refused.
                 let bad = input::register_key("bad", "Bad", "R").unwrap_err();
                 chat::show(&format!("claimed; {bad}"));
+                ui::set_settings(&[Widget::Key(KeyWidget {
+                    id: 9,
+                    key: "wheel".into(),
+                })]);
             }
             "input_poll" => {
                 for event in input::poll() {
@@ -225,6 +229,11 @@ impl Mod for Guest {
                 id: 3,
                 label: "Corner: Top Right".into(),
             }),
+            // `/input_claim`'s key; drawn as its name until registered.
+            Widget::Key(KeyWidget {
+                id: 9,
+                key: "wheel".into(),
+            }),
         ]);
         chat::show("settings opened");
     }
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index 0deeb0ddd..f525ace89 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -197,6 +197,15 @@ A thing on a mod's screen or settings page. A button as the options pages have t
 | `id` | `u32` | The mod's own name for the widget. |
 | `label` | `string` | Up to 256 characters. |
 
+### record `key-widget`
+
+One of the mod's keys (`input.register-key`) as Controls shows a binding, "Zoom: Z". A click waits for the next key or mouse button, which becomes the key (Esc: none). The game keeps the player's choice across starts; the mod's `key-down` and `key-up` follow it.
+
+| Field | Type | |
+| --- | --- | --- |
+| `id` | `u32` | The mod's own name for the widget. |
+| `key` | `string` | The name the mod registered the key under. |
+
 ### variant `widget`
 
 | Case | Payload | |
@@ -205,6 +214,7 @@ A thing on a mod's screen or settings page. A button as the options pages have t
 | `button` | `button-widget` | A button. |
 | `item` | `item-widget` | An item's icon and name. |
 | `list` | `list-widget` | Rows the player picks from. |
+| `key` | `key-widget` | A key the player binds. |
 
 ### record `screen`
 
@@ -278,7 +288,7 @@ A mapping as the player has bound it.
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `claim-items` | `func(ids: list<string>)` | The items whose use the mod handles instead of the game, by id (at most 64). Replaces the previous list. |
-| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`). At most 16; an unknown key is an error. |
+| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`), the default: a key the player chose for it (`ui`'s key widget) wins. At most 16; an unknown key is an error. |
 | `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
 | `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
 | `claim-wheel` | `func(on: bool)` | Takes the mouse wheel while playing (true) or gives it back: while taken, its steps are the mod's `wheel` events and the hotbar doesn't move. The game gives it back when the mod stops. |
diff --git a/docs/mods.md b/docs/mods.md
index 235574d6c..108e854be 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -87,7 +87,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `command` | `command` | `run(line)`: a vanilla command run as the player, with the player's permissions, after the hook returns (8 per call); mods' own commands are not run |
-| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
+| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item, list and key widgets the game lays out and draws with its own menus' code. A key widget binds one of the mod's keys (`input.register-key`) as Key Binds does: click, then press the key or mouse button (Esc: none); the game keeps the choice in `horizon-mods.txt` (`key.<mod>.<name>:key.keyboard.z`) and the mod's `key-down` follows it. **Experimental:** the manifest needs `experimental = ["ui"]` |
 | `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
 | `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 

From 53289d3565bb70df52876cc8cf23603a54901eb5 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:08:36 +0100
Subject: [PATCH 256/270] Official mod: Zoom, the zoom extra as a mod

mods/official/zoom: hold the key (Z) to zoom in at the starting zoom,
the wheel changes it while held (x1.25 a step, 1.25 to 10), smooth
easing and slower turning as options. Same settings page as the extra,
with the key widget for the key. Built on render.set-zoom,
input.claim-wheel and ui's key widget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                          |   7 ++
 Cargo.toml                          |   2 +-
 docs/mods.md                        |   3 +-
 mods/official/zoom/Cargo.toml       |  16 +++
 mods/official/zoom/horizon-mod.toml |   9 ++
 mods/official/zoom/src/lib.rs       | 145 ++++++++++++++++++++++++++++
 6 files changed, 180 insertions(+), 2 deletions(-)
 create mode 100644 mods/official/zoom/Cargo.toml
 create mode 100644 mods/official/zoom/horizon-mod.toml
 create mode 100644 mods/official/zoom/src/lib.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6e9b41b33..30c0b14d7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5330,6 +5330,13 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
 
+[[package]]
+name = "zoom"
+version = "1.0.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "zopfli"
 version = "0.8.4"
diff --git a/Cargo.toml b/Cargo.toml
index cc88441a4..259734b98 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "crates/horizon-mod-sdk/examples/predator-missile", "mods/official/fps-overlay", "mods/official/keystrokes", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "crates/horizon-mod-sdk/examples/predator-missile", "mods/official/fps-overlay", "mods/official/keystrokes", "mods/official/zoom", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/docs/mods.md b/docs/mods.md
index 13273fa2e..bfa196cb1 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -15,7 +15,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage, command, ui; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands |
-| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes |
+| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes, Zoom |
 | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
 | Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / check`, and the registry's CI (`registry build / review / list`) |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
@@ -426,6 +426,7 @@ so the same rustc and `Cargo.lock` give the same file.
 |---|---|---|---|
 | FPS Counter | `fps_overlay` | Extras > FPS counter | `corner`: `top_left` (default), `top_right`, `bottom_left`, `bottom_right`; `lows`: `false` (default), `true` |
 | Keystrokes | `keystrokes` | Extras > Keystrokes | `corner`: as above, default `top_left`; `cps`: `true` (default), `false` |
+| Zoom | `zoom` | Extras > Zoom | `level`: `2`, `3`, `4` (default), `6`, `8`, `10`; `smooth`: `true` (default), `false`; `sensitivity` (slower turning): `true` (default), `false`. The key is the game's: `key.zoom.zoom` in `horizon-mods.txt`, default `key.keyboard.z` |
 
 ## Versions and compatibility
 
diff --git a/mods/official/zoom/Cargo.toml b/mods/official/zoom/Cargo.toml
new file mode 100644
index 000000000..2225b00e8
--- /dev/null
+++ b/mods/official/zoom/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "zoom"
+version = "1.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "Horizon's official zoom: hold a key to zoom, the wheel changes it while held."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../../../crates/horizon-mod-sdk" }
+
+[lints]
+workspace = true
diff --git a/mods/official/zoom/horizon-mod.toml b/mods/official/zoom/horizon-mod.toml
new file mode 100644
index 000000000..bd699d0b5
--- /dev/null
+++ b/mods/official/zoom/horizon-mod.toml
@@ -0,0 +1,9 @@
+id = "zoom"
+name = "Zoom"
+version = "1.0.0"
+description = "Hold a key to zoom in; the mouse wheel changes the zoom while you hold it. Horizon's own, formerly an extra."
+authors = ["Horizon"]
+api = "0.1"
+side = "client"
+capabilities = ["render", "input", "ui", "storage"]
+experimental = ["render", "input", "ui"]
diff --git a/mods/official/zoom/src/lib.rs b/mods/official/zoom/src/lib.rs
new file mode 100644
index 000000000..f55f10235
--- /dev/null
+++ b/mods/official/zoom/src/lib.rs
@@ -0,0 +1,145 @@
+//! Horizon's official zoom, formerly the built-in extra: hold the key (Z
+//! by default) to zoom in, and turn the mouse wheel while holding it to zoom
+//! further in or out. Its settings page has the extra's four options. The
+//! key is bound on the page and kept by the game (`horizon-mods.txt`); the
+//! rest is kept in the mod's storage (`level`, `smooth`, `sensitivity`),
+//! where the game writes a player's old extra settings when it installs the
+//! mod for them.
+use horizon_mod_sdk::{
+    Mod, Registration,
+    input::{self, Event},
+    render::{self, Zoom as ZoomView},
+    storage,
+    ui::{self, ButtonWidget, KeyWidget, Widget},
+};
+
+/// The key's name for `register-key` and the settings page.
+const KEY: &str = "zoom";
+/// The zooms the starting zoom cycles through, and the wheel's limits.
+const LEVELS: [u8; 6] = [2, 3, 4, 6, 8, 10];
+const MIN: f32 = 1.25;
+const MAX: f32 = 10.0;
+/// Each wheel step multiplies the zoom by this.
+const STEP: f32 = 1.25;
+/// Settings page widgets.
+const KEY_WIDGET: u32 = 1;
+const LEVEL_BUTTON: u32 = 2;
+const SMOOTH_BUTTON: u32 = 3;
+const SENSITIVITY_BUTTON: u32 = 4;
+
+struct Zoom {
+    /// The zoom the key starts at, one of `LEVELS`.
+    level: u8,
+    /// Ease in and out like the spyglass.
+    smooth: bool,
+    /// Turn slower the more you zoom in.
+    sensitivity: bool,
+    /// The zoom while the key is held; None when it is up.
+    held: Option<f32>,
+}
+
+impl Zoom {
+    /// Tells the game the zoom in effect.
+    fn show(&self) {
+        let factor = self.held.unwrap_or(1.0);
+        render::set_zoom(ZoomView {
+            factor,
+            smooth: self.smooth,
+            turn: if self.sensitivity { 1.0 / factor } else { 1.0 },
+        });
+    }
+    fn page(&self) {
+        let on = |b: bool| if b { "ON" } else { "OFF" };
+        ui::set_settings(&[
+            Widget::Key(KeyWidget {
+                id: KEY_WIDGET,
+                key: KEY.into(),
+            }),
+            Widget::Button(ButtonWidget {
+                id: LEVEL_BUTTON,
+                label: format!("Starting zoom: {}x", self.level),
+            }),
+            Widget::Button(ButtonWidget {
+                id: SMOOTH_BUTTON,
+                label: format!("Smooth zoom: {}", on(self.smooth)),
+            }),
+            Widget::Button(ButtonWidget {
+                id: SENSITIVITY_BUTTON,
+                label: format!("Slower turning: {}", on(self.sensitivity)),
+            }),
+        ]);
+    }
+    fn save(&self) {
+        let flag = |b: bool| if b { &b"true"[..] } else { &b"false"[..] };
+        let _ = storage::set("level", self.level.to_string().as_bytes());
+        let _ = storage::set("smooth", flag(self.smooth));
+        let _ = storage::set("sensitivity", flag(self.sensitivity));
+    }
+}
+
+fn stored(key: &str) -> Option<String> {
+    storage::get(key).and_then(|v| String::from_utf8(v).ok())
+}
+
+impl Mod for Zoom {
+    fn init() -> Result<(Self, Registration), String> {
+        input::register_key(KEY, "Zoom", "key.keyboard.z")?;
+        // The extra's defaults: 4x, smooth, slower turning.
+        let level = stored("level")
+            .and_then(|v| v.trim().parse::<u8>().ok())
+            .map_or(4, |v| v.clamp(2, MAX as u8));
+        let flag = |key: &str| stored(key).is_none_or(|v| v.trim() != "false");
+        let zoom = Zoom {
+            level,
+            smooth: flag("smooth"),
+            sensitivity: flag("sensitivity"),
+            held: None,
+        };
+        zoom.page();
+        Ok((zoom, Registration::new().on_frame()))
+    }
+    fn frame(&mut self, _seconds: f32) {
+        let mut changed = false;
+        for event in input::poll() {
+            match event {
+                Event::KeyDown(k) if k == KEY => {
+                    self.held = Some(f32::from(self.level).clamp(MIN, MAX));
+                    // While held, the wheel zooms instead of moving the hotbar.
+                    input::claim_wheel(true);
+                }
+                Event::KeyUp(k) if k == KEY => {
+                    self.held = None;
+                    input::claim_wheel(false);
+                }
+                Event::Wheel(steps) => {
+                    let Some(z) = &mut self.held else { continue };
+                    *z = (*z * STEP.powf(steps)).clamp(MIN, MAX);
+                }
+                _ => continue,
+            }
+            changed = true;
+        }
+        if changed {
+            self.show();
+        }
+    }
+    fn ui_select(&mut self, id: u32, _row: u32) {
+        match id {
+            LEVEL_BUTTON => {
+                // As the extra cycled: an unknown level counts as the first.
+                let i = LEVELS.iter().position(|&l| l == self.level).unwrap_or(0);
+                self.level = LEVELS[(i + 1) % LEVELS.len()];
+            }
+            SMOOTH_BUTTON => self.smooth = !self.smooth,
+            SENSITIVITY_BUTTON => self.sensitivity = !self.sensitivity,
+            _ => return,
+        }
+        self.save();
+        self.page();
+    }
+    fn ui_settings_opened(&mut self) {
+        self.page();
+    }
+}
+
+horizon_mod_sdk::export_mod!(Zoom);

From 5335354658cbbb1970c9bba6d9605f88e1419eda Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:10:19 +0100
Subject: [PATCH 257/270] CI: runners clone what the shared source gained after
 their first copy

The release runner, now parity-main's, cloned the shared source before
the sounds were added to it; vanilla-data.sh only copied on the first
run, so ambient_sound, audio_attributes and music failed there with
"Sound assets missing". Each run now clones any entry the runner's copy
lacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tools/ci/vanilla-data.sh | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/tools/ci/vanilla-data.sh b/tools/ci/vanilla-data.sh
index e8dfb36cc..ebebf3219 100755
--- a/tools/ci/vanilla-data.sh
+++ b/tools/ci/vanilla-data.sh
@@ -13,17 +13,15 @@ source="${HORIZON_SHARED_SOURCE:-$HOME/code/horizon-parity/shared-local}"
 version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' research-lock.json | head -1)
 if [ ! -f "$shared/minecraft/$version/prepared.json" ]; then
   [ -f "$source/minecraft/$version/prepared.json" ] || { echo "::error::no imported Minecraft $version in $source"; exit 1; }
-  mkdir -p "$shared"
-  if [ "$(uname)" = Darwin ]; then
-    for entry in "$source"/*; do
-      [ "$(basename "$entry")" = horizon-client ] || cp -cR "$entry" "$shared/"
-    done
-  else
-    for entry in "$source"/*; do
-      [ "$(basename "$entry")" = horizon-client ] || cp -R --reflink=auto "$entry" "$shared/"
-    done
-  fi
 fi
+# Whatever the source holds and this runner's copy doesn't yet: all of it the first time, and later additions (the
+# sounds came after the release runner's first clone, and its audio harnesses failed for want of them).
+mkdir -p "$shared"
+for entry in "$source"/*; do
+  name=$(basename "$entry")
+  [ "$name" = horizon-client ] || [ -e "$shared/$name" ] && continue
+  if [ "$(uname)" = Darwin ]; then cp -cR "$entry" "$shared/"; else cp -R --reflink=auto "$entry" "$shared/"; fi
+done
 mkdir -p .local "$shared/prepared"
 for entry in "$shared"/*; do
   name=$(basename "$entry")

From 3e3c0cebb51fa5deb0022ff1c0ca8fa4ba9fc42d Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:34:49 +0100
Subject: [PATCH 258/270] Mod keys: rows the game adds to the settings page,
 not a WIT widget

A new case in ui's widget variant stops every ui mod built before it from
loading: the runtime links a component only when each imported
function's types match exactly ("expected variant of 5 cases, found
4"), so the published FPS Counter and Keystrokes would break. Instead,
the game lists a mod's keys first on its page in Options > Mods, as Key
Binds rows, and a mod with keys gets a page even without ui. No WIT
type changes. docs/api/stability.md said a new case the mod sends isn't
breaking; it is, and now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/mods.rs        | 113 ++++++++++--------
 crates/horizon-mod-sdk/wit/horizon.wit        |  17 +--
 crates/horizon-mods/src/runtime.rs            |  17 ++-
 crates/horizon-mods/tests/sandbox.rs          |   8 +-
 crates/horizon-mods/tests/ui_guest/src/lib.rs |  11 +-
 docs/api/mods-reference.md                    |  12 +-
 docs/api/stability.md                         |   9 +-
 docs/mods.md                                  |   4 +-
 8 files changed, 86 insertions(+), 105 deletions(-)

diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs
index 66d00b233..e55a87d46 100644
--- a/crates/horizon-client/src/game/mods.rs
+++ b/crates/horizon-client/src/game/mods.rs
@@ -27,7 +27,7 @@ use {
         text::{self, Text},
         ui,
     },
-    horizon_mods::{Clock, Mods, Output, Player, Snapshot, Status, UiScreen, UiWidget},
+    horizon_mods::{Clock, ModKey, Mods, Output, Player, Snapshot, Status, UiScreen, UiWidget},
     std::time::Instant,
     winit::{event::MouseButton, keyboard::KeyCode},
 };
@@ -102,7 +102,7 @@ struct ModScreen {
     under: Screen,
     /// One scroll per `list` widget, in widget order.
     scrolls: Vec<ui::Scroll>,
-    /// A key widget waiting for the key to bind: the mod key's name.
+    /// A key row waiting for the key to bind: the mod key's name.
     binding: Option<String>,
 }
 impl ModsState {
@@ -575,7 +575,7 @@ impl Game<'_> {
     fn mod_ui_view<'a>(mods: &'a Mods, ms: &ModScreen) -> Option<(&'a str, &'a [UiWidget])> {
         if ms.settings {
             let widgets = mods.settings_widgets(ms.owner);
-            if widgets.is_empty() {
+            if widgets.is_empty() && mods.keys_of(ms.owner).is_empty() {
                 return None;
             }
             let name = mods
@@ -589,24 +589,25 @@ impl Game<'_> {
             Some((s.title.as_str(), s.widgets.as_slice()))
         }
     }
-    /// A key widget's label as Key Binds shows one, "Zoom: Z", marked
+    /// The keys a settings page lists first: the mod's own (`input`).
+    fn mod_page_keys<'a>(mods: &'a Mods, ms: &ModScreen) -> &'a [ModKey] {
+        if ms.settings {
+            mods.keys_of(ms.owner)
+        } else {
+            &[]
+        }
+    }
+    /// A key row's label as Key Binds shows one, "Zoom: Z", marked
     /// "> Zoom: Z <" in yellow while it waits for the new key.
-    fn mod_key_label(mods: &Mods, owner: usize, name: &str, waiting: bool) -> Text {
-        let (label, key) = mods
-            .keys_of(owner)
-            .iter()
-            .find(|k| k.name == name)
-            .map_or((name, "key.keyboard.unknown"), |k| {
-                (k.label.as_str(), k.key.as_str())
-            });
-        let value = format!("{label}: {}", keybinds::display_name(key).plain());
+    fn mod_key_label(k: &ModKey, waiting: bool) -> Text {
+        let value = format!("{}: {}", k.label, keybinds::display_name(&k.key).plain());
         if waiting {
             Text::literal(format!("> {value} <")).with_color(text::YELLOW)
         } else {
             Text::literal(value)
         }
     }
-    /// The player bound the key widget that waited to `key`: the mod's key
+    /// The player bound the key row that waited to `key`: the mod's key
     /// follows it now and at the next start (`horizon-mods.txt`).
     fn bind_mod_key(&mut self, key: String) {
         let Some(ms) = self.mods.screen.as_mut() else {
@@ -637,7 +638,7 @@ impl Game<'_> {
             .insert(name, key);
         self.settings.save(&Self::options_path());
     }
-    /// A key while a mod screen is up: true when a key widget waited for
+    /// A key while a mod screen is up: true when a key row waited for
     /// it (Key Binds: Escape binds none).
     pub(super) fn mod_screen_key(&mut self, key: KeyCode) -> bool {
         if self
@@ -657,13 +658,13 @@ impl Game<'_> {
     }
     /// The layout the mod screen's widgets get at `h`: (widget, top,
     /// height), the column being `COLUMN` wide down the middle.
-    fn mod_ui_layout(h: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
+    fn mod_ui_layout(h: f32, top: f32, widgets: &[UiWidget]) -> Vec<(f32, f32)> {
         let mut out = Vec::with_capacity(widgets.len());
-        let mut y = MOD_UI_TOP;
+        let mut y = top;
         for w in widgets {
             let wh = match w {
                 UiWidget::Text(_) => 12.0,
-                UiWidget::Item(_) | UiWidget::Button(_) | UiWidget::Key(_) => 20.0,
+                UiWidget::Item(_) | UiWidget::Button(_) => 20.0,
                 UiWidget::List(l) => (l.rows.len().min(6) as f32 * 12.0) + 8.0,
             };
             // Nothing may cover Done; a crowded mod loses what won't fit.
@@ -683,7 +684,8 @@ impl Game<'_> {
         }
         if settings {
             self.mods.mods.ui_settings_opened(owner);
-            if self.mods.mods.settings_widgets(owner).is_empty() {
+            let keys = self.mods.mods.keys_of(owner);
+            if self.mods.mods.settings_widgets(owner).is_empty() && keys.is_empty() {
                 self.show_mod_output();
                 return;
             }
@@ -755,7 +757,27 @@ impl Game<'_> {
         );
         let cx = (batch.width / 2.0).floor();
         let x = cx - MOD_UI_COLUMN / 2.0;
-        let layout = Self::mod_ui_layout(batch.height, widgets);
+        // A settings page starts with the mod's keys, as Key Binds rows.
+        let keys = Self::mod_page_keys(&self.mods.mods, ms);
+        for (i, k) in keys.iter().enumerate() {
+            let wy = MOD_UI_TOP + i as f32 * MOD_UI_KEY_ROW;
+            let hover = ui::hovered(self.cursor, x, wy, MOD_UI_COLUMN, 20.0);
+            let waiting = ms.binding.as_deref() == Some(k.name.as_str());
+            let label = Self::mod_key_label(k, waiting);
+            ui::button(
+                batch,
+                atlas,
+                x,
+                wy,
+                MOD_UI_COLUMN,
+                20.0,
+                &label,
+                true,
+                hover,
+            );
+        }
+        let top = MOD_UI_TOP + keys.len() as f32 * MOD_UI_KEY_ROW;
+        let layout = Self::mod_ui_layout(batch.height, top, widgets);
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             match w {
@@ -774,22 +796,6 @@ impl Game<'_> {
                         hover,
                     );
                 }
-                UiWidget::Key(k) => {
-                    let hover = ui::hovered(self.cursor, x, wy, MOD_UI_COLUMN, 20.0);
-                    let waiting = ms.binding.as_deref() == Some(k.key.as_str());
-                    let label = Self::mod_key_label(&self.mods.mods, ms.owner, &k.key, waiting);
-                    ui::button(
-                        batch,
-                        atlas,
-                        x,
-                        wy,
-                        MOD_UI_COLUMN,
-                        20.0,
-                        &label,
-                        true,
-                        hover,
-                    );
-                }
                 UiWidget::Text(t) => {
                     let color = if t.color == 0 {
                         u32::MAX
@@ -920,7 +926,22 @@ impl Game<'_> {
         };
         let owner = ms.owner;
         let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
-        let layout = Self::mod_ui_layout(h, widgets);
+        // A key row waits for the key to bind.
+        let keys = Self::mod_page_keys(&self.mods.mods, ms);
+        let picked = (0..keys.len()).find(|&i| {
+            let wy = MOD_UI_TOP + i as f32 * MOD_UI_KEY_ROW;
+            ui::hovered(cursor, x, wy, MOD_UI_COLUMN, 20.0)
+        });
+        if let Some(i) = picked {
+            let name = keys[i].name.clone();
+            self.audio.play_button_click();
+            if let Some(ms) = self.mods.screen.as_mut() {
+                ms.binding = Some(name);
+            }
+            return;
+        }
+        let top = MOD_UI_TOP + keys.len() as f32 * MOD_UI_KEY_ROW;
+        let layout = Self::mod_ui_layout(h, top, widgets);
         let mut list_i = 0usize;
         // The `ui_select` call needs `&mut`: find the pick first.
         let mut hit = None;
@@ -935,17 +956,6 @@ impl Game<'_> {
                 self.show_mod_output();
                 return;
             }
-            // A key widget waits for the key to bind.
-            if let UiWidget::Key(k) = w
-                && ui::hovered(cursor, x, wy, MOD_UI_COLUMN, 20.0)
-            {
-                self.audio.play_button_click();
-                let name = k.key.clone();
-                if let Some(ms) = self.mods.screen.as_mut() {
-                    ms.binding = Some(name);
-                }
-                return;
-            }
             let UiWidget::List(l) = w else { continue };
             let scroll = ms.scrolls.get(list_i).copied().unwrap_or_default();
             list_i += 1;
@@ -975,7 +985,9 @@ impl Game<'_> {
             return;
         };
         let x = (w / 2.0).floor() - MOD_UI_COLUMN / 2.0;
-        let layout = Self::mod_ui_layout(h, widgets);
+        let top =
+            MOD_UI_TOP + Self::mod_page_keys(&self.mods.mods, ms).len() as f32 * MOD_UI_KEY_ROW;
+        let layout = Self::mod_ui_layout(h, top, widgets);
         let mut list_i = 0usize;
         for (w, &(wy, wh)) in widgets.iter().zip(&layout) {
             let UiWidget::List(l) = w else { continue };
@@ -995,3 +1007,6 @@ impl Game<'_> {
 const MOD_UI_TOP: f32 = 40.0;
 #[cfg(feature = "mods")]
 const MOD_UI_COLUMN: f32 = 200.0;
+/// A key row's height with its gap, as the widgets below it space out.
+#[cfg(feature = "mods")]
+const MOD_UI_KEY_ROW: f32 = 26.0;
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index f9c147cfa..9088c0c39 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -137,16 +137,6 @@ interface ui {
         /// Up to 256 characters.
         label: string,
     }
-    /// One of the mod's keys (`input.register-key`) as Controls shows a
-    /// binding, "Zoom: Z". A click waits for the next key or mouse button,
-    /// which becomes the key (Esc: none). The game keeps the player's
-    /// choice across starts; the mod's `key-down` and `key-up` follow it.
-    record key-widget {
-        /// The mod's own name for the widget.
-        id: u32,
-        /// The name the mod registered the key under.
-        key: string,
-    }
     variant widget {
         /// Text the player reads.
         text(text-widget),
@@ -156,8 +146,6 @@ interface ui {
         item(item-widget),
         /// Rows the player picks from.
         %list(list-widget),
-        /// A key the player binds.
-        key(key-widget),
     }
     /// A screen the mod owns: a title over widgets stacked down the middle,
     /// the Done button the game adds, and Esc to leave it.
@@ -232,8 +220,9 @@ interface input {
     claim-items: func(ids: list<string>);
     /// A key of the mod's: `name` comes back in `key-down` and `key-up`,
     /// `label` says what it does, `key` is the key as options.txt writes
-    /// it (`key.keyboard.r`), the default: a key the player chose for it
-    /// (`ui`'s key widget) wins. At most 16; an unknown key is an error.
+    /// it (`key.keyboard.r`), the default: the player can bind another
+    /// one on the mod's page in Options > Mods, and that one wins. At most
+    /// 16; an unknown key is an error.
     register-key: func(name: string, label: string, key: string) -> result<_, string>;
     /// The main hand's stack, as of this tick; none when it is empty.
     held: func() -> option<held-item>;
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index f596db81c..0011fa99d 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -37,8 +37,7 @@ use bindings::{
 /// The widget model a `ui` screen or settings page shows (WIT `interface
 /// ui`), for the game to draw with its menus' own widgets.
 pub use ui_bindings::horizon::mods::ui::{
-    ButtonWidget, ItemWidget, KeyWidget, ListWidget, Screen as UiScreen, TextWidget,
-    Widget as UiWidget,
+    ButtonWidget, ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
 };
 use ui_bindings::{UiHost, horizon::mods::ui};
 /// Capability `render`'s imports (docs/mods.md): the game draws the shapes.
@@ -153,11 +152,13 @@ pub struct Entry {
 }
 impl Entry {
     /// The running mod has a settings page (capability `ui` set widgets
-    /// with `ui.set-settings`): its row in Options > Mods gains a button.
+    /// with `ui.set-settings`, or `input` registered keys the player may
+    /// bind there): its row in Options > Mods gains a button.
     pub fn has_ui_settings(&self) -> bool {
-        self.run
-            .as_ref()
-            .is_some_and(|r| !r.store.data().ui.settings.is_empty())
+        self.run.as_ref().is_some_and(|r| {
+            let d = r.store.data();
+            !d.ui.settings.is_empty() || !d.input.keys.is_empty()
+        })
     }
 }
 
@@ -856,10 +857,6 @@ fn clip_widgets(widgets: Vec<UiWidget>) -> Vec<UiWidget> {
                 l.selected = l.selected.filter(|&s| (s as usize) < l.rows.len());
                 UiWidget::List(l)
             }
-            UiWidget::Key(mut k) => {
-                k.key = clip(k.key);
-                UiWidget::Key(k)
-            }
         })
         .collect()
 }
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index 793d03db6..3b33ab4b2 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -449,7 +449,7 @@ fn ui_screens_settings_and_events() {
     assert_eq!(mods.settings_widgets(0).len(), 3);
     assert!(mods.entries()[0].has_ui_settings());
     mods.ui_settings_opened(0);
-    assert_eq!(mods.settings_widgets(0).len(), 3);
+    assert_eq!(mods.settings_widgets(0).len(), 2);
     // `/ui_close` closes the mod's own screen.
     assert!(mods.command("ui_close"));
     assert!(mods.drain().contains(&Output::CloseScreen { owner: 0 }));
@@ -566,10 +566,8 @@ fn the_players_key_choice_wins() {
     };
     let mut mods = load("horizon_mods_test_ui_guest.hmod");
     assert!(mods.command("input_claim"));
-    assert!(matches!(
-        &mods.settings_widgets(0)[0],
-        horizon_mods::UiWidget::Key(k) if k.id == 9 && k.key == "wheel"
-    ));
+    // Its keys alone give it a page in Options > Mods, where the game lists them.
+    assert!(mods.settings_widgets(0).is_empty() && mods.entries()[0].has_ui_settings());
     // Rebinding while held lets the old key go.
     mods.key("key.keyboard.r", true);
     assert!(mods.rebind(0, "wheel", "key.mouse.4"));
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index f2765e8da..9bede11f9 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -9,7 +9,7 @@ use horizon_mod_sdk::{
     Mod, Registration, chat,
     input::{self, Event},
     render::{self, FillShape, ItemShape, Point, QuadShape, Rect, Shape, SpriteShape, TextShape},
-    ui::{self, ItemWidget, KeyWidget, ListWidget, Screen, TextWidget, Widget},
+    ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
 };
 
 /// One of each shape, the text too long by 44 characters.
@@ -162,10 +162,6 @@ impl Mod for Guest {
                 // Not a key: refused.
                 let bad = input::register_key("bad", "Bad", "R").unwrap_err();
                 chat::show(&format!("claimed; {bad}"));
-                ui::set_settings(&[Widget::Key(KeyWidget {
-                    id: 9,
-                    key: "wheel".into(),
-                })]);
             }
             "input_poll" => {
                 for event in input::poll() {
@@ -229,11 +225,6 @@ impl Mod for Guest {
                 id: 3,
                 label: "Corner: Top Right".into(),
             }),
-            // `/input_claim`'s key; drawn as its name until registered.
-            Widget::Key(KeyWidget {
-                id: 9,
-                key: "wheel".into(),
-            }),
         ]);
         chat::show("settings opened");
     }
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index f525ace89..a51fb904b 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -197,15 +197,6 @@ A thing on a mod's screen or settings page. A button as the options pages have t
 | `id` | `u32` | The mod's own name for the widget. |
 | `label` | `string` | Up to 256 characters. |
 
-### record `key-widget`
-
-One of the mod's keys (`input.register-key`) as Controls shows a binding, "Zoom: Z". A click waits for the next key or mouse button, which becomes the key (Esc: none). The game keeps the player's choice across starts; the mod's `key-down` and `key-up` follow it.
-
-| Field | Type | |
-| --- | --- | --- |
-| `id` | `u32` | The mod's own name for the widget. |
-| `key` | `string` | The name the mod registered the key under. |
-
 ### variant `widget`
 
 | Case | Payload | |
@@ -214,7 +205,6 @@ One of the mod's keys (`input.register-key`) as Controls shows a binding, "Zoom:
 | `button` | `button-widget` | A button. |
 | `item` | `item-widget` | An item's icon and name. |
 | `list` | `list-widget` | Rows the player picks from. |
-| `key` | `key-widget` | A key the player binds. |
 
 ### record `screen`
 
@@ -288,7 +278,7 @@ A mapping as the player has bound it.
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `claim-items` | `func(ids: list<string>)` | The items whose use the mod handles instead of the game, by id (at most 64). Replaces the previous list. |
-| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`), the default: a key the player chose for it (`ui`'s key widget) wins. At most 16; an unknown key is an error. |
+| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`), the default: the player can bind another one on the mod's page in Options > Mods, and that one wins. At most 16; an unknown key is an error. |
 | `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
 | `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
 | `claim-wheel` | `func(on: bool)` | Takes the mouse wheel while playing (true) or gives it back: while taken, its steps are the mod's `wheel` events and the hotbar doesn't move. The game gives it back when the mod stops. |
diff --git a/docs/api/stability.md b/docs/api/stability.md
index 132c971f9..d5bd0e545 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -26,12 +26,13 @@ promise, how something is deprecated and removed, and the tests that keep old mo
 ## What counts as a breaking change
 
 Breaking: removing or renaming anything; changing a type, a default, a unit or a meaning; making something optional
-required; refusing input that was accepted; a new case in a WIT `enum` or `variant` the game sends to mods (an older
-component cannot decode it); a JSON field that changes type.
+required; refusing input that was accepted; any change to a WIT type a function uses, a new `enum` or `variant` case
+included, in either direction (the runtime links a component only when each imported function's types match exactly:
+a mod built before the change no longer loads); a JSON field that changes type.
 
 Not breaking: a new function, interface, capability, command, endpoint, tool or `server.toml` key; a new optional
-argument or JSON field (readers must ignore fields they don't know); a new WIT case the mod *sends* (the game decodes
-every case it ever served); faster, or fixing behaviour to what the reference already says.
+argument or JSON field (readers must ignore fields they don't know); a new WIT function or type (mods built earlier
+don't import it); faster, or fixing behaviour to what the reference already says.
 
 ## Stability levels
 
diff --git a/docs/mods.md b/docs/mods.md
index 108e854be..a8d8da851 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -87,9 +87,9 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `command` | `command` | `run(line)`: a vanilla command run as the player, with the player's permissions, after the hook returns (8 per call); mods' own commands are not run |
-| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item, list and key widgets the game lays out and draws with its own menus' code. A key widget binds one of the mod's keys (`input.register-key`) as Key Binds does: click, then press the key or mouse button (Esc: none); the game keeps the choice in `horizon-mods.txt` (`key.<mod>.<name>:key.keyboard.z`) and the mod's `key-down` follows it. **Experimental:** the manifest needs `experimental = ["ui"]` |
+| `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
 | `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
-| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
+| `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`. The player rebinds them on the mod's page in Options > Mods, where the game lists them first as Key Binds rows (click, then press a key or mouse button; Esc binds none), even for a mod without `ui`; the choice is kept in `horizon-mods.txt` (`key.<mod>.<name>:key.keyboard.z`) and wins over `register-key`'s default; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 
 | Hook (export) | When |
 |---|---|

From 1aa6f21620833327a6c9aeaa7ab95764682c1041 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:27:14 +0100
Subject: [PATCH 259/270] Horizon shader packs: the post stage runs in the
 game, with hot reload

A native pack named by HORIZON_SHADER_PACK (a folder with horizon-shaders.toml
or a .hshader in shaderpacks/) is checked, then its post passes run over the
world's own target, the one a shaders/ pack reads: no second target and no
extra pass, and without a pack the frame only tests one Option. The pack is
looked at twice a second; a saved file is checked and rebuilt in place, and a
version that fails is refused in the chat while the last good one keeps
drawing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                                    |   1 +
 crates/horizon-client/Cargo.toml              |   2 +
 crates/horizon-client/src/game.rs             |   4 +
 .../horizon-client/src/game/native_shaders.rs | 110 ++++
 .../horizon-client/src/game/shader_packs.rs   |  16 +-
 crates/horizon-client/src/gfx.rs              |  59 +-
 crates/horizon-client/src/gfx/native_post.rs  | 509 ++++++++++++++++++
 .../packs/golden_hour/post/glow.wgsl          |  15 +-
 crates/horizon-shader-api/src/inputs.rs       |   2 +-
 crates/horizon-shader-api/src/package.rs      |   7 +
 docs/api/shaders-reference.md                 |   2 +-
 docs/api/shaders.md                           |   1 +
 docs/shaders.md                               |  16 +-
 13 files changed, 723 insertions(+), 21 deletions(-)
 create mode 100644 crates/horizon-client/src/game/native_shaders.rs
 create mode 100644 crates/horizon-client/src/gfx/native_post.rs

diff --git a/Cargo.lock b/Cargo.lock
index 25c1ae15d..201f7c83c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1364,6 +1364,7 @@ dependencies = [
  "horizon-mods",
  "horizon-protocol",
  "horizon-server-files",
+ "horizon-shader-api",
  "horizon-shaders",
  "horizon-telemetry",
  "horizon-theme",
diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml
index 4877c18f2..a585ce19e 100644
--- a/crates/horizon-client/Cargo.toml
+++ b/crates/horizon-client/Cargo.toml
@@ -18,6 +18,8 @@ horizon-protocol = { path = "../horizon-protocol" }
 horizon-server-files = { path = "../horizon-server-files" }
 # Shader packs: reading them and turning their GLSL into naga modules.
 horizon-shaders = { path = "../horizon-shaders" }
+# Horizon's own shader packs: the format, the stages and the check (docs/shaders.md).
+horizon-shader-api = { path = "../horizon-shader-api" }
 horizon-friends = { path = "../horizon-friends" }
 # Horizon mods: sandboxed WebAssembly components, off unless installed and turned on (docs/mods.md).
 # Their runtime is the `mods` feature.
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 9a3503666..4638a4667 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -106,6 +106,7 @@ mod mounts;
 mod moving_pistons;
 mod music;
 mod names;
+mod native_shaders;
 mod natural_spawning;
 mod nautili;
 mod net_harness;
@@ -1507,6 +1508,8 @@ struct Game<'a> {
     extras: extras::ExtrasState,
     /// Horizon mods (`game/mods.rs`), none running unless turned on.
     mods: mods::ModsState,
+    /// Horizon's own shader pack, while one is picked (`game/native_shaders.rs`).
+    native_shaders: native_shaders::NativeShaders,
     /// Meshed sections waiting for an upload budget (Horizon settings).
     pending_uploads: Vec<((i32, i32, i32), horizon_client::mesher::SectionMesh)>,
     /// This frame's view frustum, for culling entities and block entities.
@@ -12309,6 +12312,7 @@ impl<'a> Game<'a> {
             frame_graph: Default::default(),
             extras: Default::default(),
             mods: Default::default(),
+            native_shaders: Default::default(),
             sky_darken_memo: Default::default(),
             persist: Default::default(),
             remote: None,
diff --git a/crates/horizon-client/src/game/native_shaders.rs b/crates/horizon-client/src/game/native_shaders.rs
new file mode 100644
index 000000000..62aaafc42
--- /dev/null
+++ b/crates/horizon-client/src/game/native_shaders.rs
@@ -0,0 +1,110 @@
+//! Horizon's own shader packs in the game (docs/shaders.md), for development until the Shader
+//! Packs page exists: `HORIZON_SHADER_PACK=<name>` naming one in `shaderpacks/` (a folder with
+//! `horizon-shaders.toml`, or a `.hshader`) runs it once it passes `horizon_shader_api::check`.
+//! The pack is looked at twice a second: a saved file is checked and the pack rebuilt, and a
+//! pack that fails is refused with its problems in the chat while the last good one keeps
+//! drawing.
+
+use std::{
+    hash::{Hash, Hasher},
+    path::Path,
+    time::{Duration, Instant},
+};
+
+use horizon_client::text::Text;
+use horizon_shader_api::{Pack, check};
+
+use super::Game;
+
+const LOOK_EVERY: Duration = Duration::from_millis(500);
+const RED: u32 = 0xFF5555;
+
+#[derive(Default)]
+pub(super) struct NativeShaders {
+    /// The pack's files when it was last read (`fingerprint`).
+    stamp: Option<u64>,
+    looked: Option<Instant>,
+}
+
+impl Game<'_> {
+    /// Builds the pack at `path` when its files changed since it was last read.
+    pub(super) fn tick_native_shader_pack(&mut self, path: &Path) {
+        let now = Instant::now();
+        let state = &mut self.native_shaders;
+        if state.looked.is_some_and(|t| now - t < LOOK_EVERY) {
+            return;
+        }
+        state.looked = Some(now);
+        let stamp = fingerprint(path);
+        if stamp == state.stamp {
+            return;
+        }
+        let reload = state.stamp.is_some();
+        state.stamp = stamp;
+        let Some(renderer) = &mut self.renderer else {
+            return;
+        };
+        let result = Pack::read(path).map_err(|e| vec![e]).and_then(|pack| {
+            let report = check(&pack)
+                .map_err(|p| p.iter().map(ToString::to_string).collect::<Vec<String>>())?;
+            let constants = pack
+                .manifest
+                .options
+                .iter()
+                .map(|o| (o.id.clone(), o.kind.default_constant()))
+                .collect();
+            let labels = renderer
+                .set_native_shader_pack(Some((report, constants)))
+                .map_err(|e| vec![e])?;
+            Ok((pack.manifest, labels))
+        });
+        let name = path.file_name().unwrap_or_default().to_string_lossy();
+        match result {
+            Ok((m, labels)) => {
+                log::info!(
+                    "shader pack {} {}: {} in {} ms",
+                    m.id,
+                    m.version,
+                    labels.join(", "),
+                    now.elapsed().as_millis()
+                );
+                if reload {
+                    self.system_message(Text::literal(format!("Shader pack {} reloaded", m.name)));
+                }
+            }
+            Err(problems) => {
+                log::warn!("shader pack {name} refused: {}", problems.join("; "));
+                self.system_message(Text::colored(format!("Shader pack {name} refused:"), RED));
+                for p in problems {
+                    self.system_message(Text::colored(p, RED));
+                }
+            }
+        }
+    }
+}
+
+/// A hash of the pack's file names, sizes and modification times (`None` when unreadable).
+fn fingerprint(path: &Path) -> Option<u64> {
+    fn walk(path: &Path, hasher: &mut std::hash::DefaultHasher) -> Option<()> {
+        let meta = std::fs::metadata(path).ok()?;
+        path.hash(hasher);
+        if meta.is_dir() {
+            let mut entries: Vec<_> = std::fs::read_dir(path)
+                .ok()?
+                .flatten()
+                .map(|e| e.path())
+                .collect();
+            entries.sort();
+            for entry in entries {
+                walk(&entry, hasher)?;
+            }
+        } else {
+            meta.len().hash(hasher);
+            meta.modified().ok()?.hash(hasher);
+        }
+        Some(())
+    }
+    let mut hasher = std::hash::DefaultHasher::new();
+    walk(path, &mut hasher)?;
+    Some(hasher.finish())
+}
diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index f534e8391..ed8ad61b7 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -1,5 +1,6 @@
 //! Shader packs, for development until the Shader Packs page exists: `HORIZON_SHADER_PACK=<name>`
-//! runs `shaderpacks/<name>` (a folder or a zip beside `options.txt`) over the world. The
+//! runs `shaderpacks/<name>` (a folder or a zip beside `options.txt`) over the world; Horizon's
+//! own packs go to `game/native_shaders.rs`. The
 //! programs of the current dimension's folder are loaded when the dimension changes (spec 1.2).
 
 use horizon_client::camera::CameraFluid;
@@ -41,15 +42,18 @@ impl Game<'_> {
             Dim::Nether => -1,
             Dim::End => 1,
         };
-        if let Some(renderer) = &mut self.renderer
+        let path = std::env::current_dir()
+            .unwrap_or_default()
+            .join("shaderpacks")
+            .join(&name);
+        if horizon_shader_api::package::is_pack(&path) {
+            // One of Horizon's own packs (game/native_shaders.rs).
+            self.tick_native_shader_pack(&path);
+        } else if let Some(renderer) = &mut self.renderer
             && renderer.shader_pack_dimension() != Some(dimension)
         {
             let name = name.to_string_lossy();
             let started = std::time::Instant::now();
-            let path = std::env::current_dir()
-                .unwrap_or_default()
-                .join("shaderpacks")
-                .join(&*name);
             match Pack::open(&path) {
                 Ok(pack) => {
                     let macros = Macros::standard();
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 419f83c4a..5db82b19a 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -67,6 +67,7 @@ mod end_sky;
 mod flat;
 pub mod lightning;
 mod lod;
+mod native_post;
 mod occlusion;
 mod pack_atlas;
 pub mod pack_draw;
@@ -499,6 +500,8 @@ pub struct Renderer {
     world_post: world_post::Post,
     /// The shader pack's post-processing, and the dimension (legacy id) it was loaded for.
     pack_post: Option<(i32, Option<pack_post::PackPost>)>,
+    /// The post passes of one of Horizon's own shader packs; never beside `pack_post`'s.
+    native_post: Option<native_post::NativePost>,
     /// The entity vertices Horizon draws itself while a shader pack draws the others.
     pack_entity_rest: Vec<Vertex>,
     /// Set 1 of the cloud pipeline, for a shader pack's `gbuffers_clouds`.
@@ -2409,6 +2412,7 @@ impl Renderer {
             occlusion: occlusion::Occlusion::new(crate::chunk::MIN_Y, crate::chunk::HEIGHT / 16),
             world_post,
             pack_post: None,
+            native_post: None,
             pack_entity_rest: Vec::new(),
             cloud_bindings,
             pack_weather: None,
@@ -2916,8 +2920,38 @@ impl Renderer {
             (programs, p.notes.clone())
         });
         self.pack_post = Some((dimension, post));
+        if self.pack_post.as_ref().is_some_and(|p| p.1.is_some()) {
+            self.native_post = None;
+        }
         report
     }
+    /// Runs the post passes of one of Horizon's own shader packs over the world from now on
+    /// (`None`: no pack), with its options' values; replaces a `shaders/` pack. Returns the
+    /// passes' labels; on an error the passes that ran keep running.
+    pub fn set_native_shader_pack(
+        &mut self,
+        pack: Option<(horizon_shader_api::Report, Vec<(String, f64)>)>,
+    ) -> std::result::Result<Vec<String>, String> {
+        let stages = pack.map(|(report, constants)| {
+            let post: Vec<_> = report
+                .stages
+                .into_iter()
+                .filter(|s| s.kind == horizon_shader_api::StageKind::Post)
+                .collect();
+            (post, constants)
+        });
+        let Some((post, constants)) = stages.filter(|(post, _)| !post.is_empty()) else {
+            self.native_post = None;
+            return Ok(Vec::new());
+        };
+        let format = self.config.format.remove_srgb_suffix();
+        let post = native_post::NativePost::new(&self.device, post, &constants, format)?;
+        let labels = post.labels().into_iter().map(str::to_owned).collect();
+        self.pack_post = None;
+        self.pack_atlas = None;
+        self.native_post = Some(post);
+        Ok(labels)
+    }
     /// What a shader pack's gbuffers programs read from Horizon's geometry: the sky's, and
     /// terrain's in the pack's block atlas (made here when missing; none when it does not fit).
     pub fn pack_inputs(&mut self) -> horizon_shaders::GameInputs {
@@ -3980,6 +4014,9 @@ impl Renderer {
         }
         // The world's targets: the screen, or the scaled target of `post`.
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
+        // One of Horizon's own packs reads the same world target.
+        let native_post = !frame.title && self.native_post.is_some();
+        let pack_reads_world = pack_post || native_post;
         // The pack's program reads the vertices this frame's draws bind.
         let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
         // The shadow camera's lists, drawn by the pack's shadow programs.
@@ -4023,7 +4060,7 @@ impl Renderer {
         let scaled = self.world_post.prepare(
             &self.device,
             [self.config.width, self.config.height],
-            pack_post,
+            pack_reads_world,
         );
         let (world_view, world_depth) = match &scaled {
             Some((color, depth)) => (color, depth),
@@ -4062,7 +4099,7 @@ impl Renderer {
                     depth_ops: Some(wgpu::Operations {
                         load: wgpu::LoadOp::Clear(0.0),
                         // Phase 2 of occlusion culling draws over it; a shader pack reads it.
-                        store: if cull.is_some() || pack_post {
+                        store: if cull.is_some() || pack_reads_world {
                             wgpu::StoreOp::Store
                         } else {
                             wgpu::StoreOp::Discard
@@ -4128,7 +4165,7 @@ impl Renderer {
                                 &mut encoder,
                                 world_view,
                                 world_depth,
-                                pack_post,
+                                pack_reads_world,
                             );
                             pass.set_bind_group(0, &self.group, &[]);
                             pass.set_pipeline(&flat.solid);
@@ -4157,7 +4194,7 @@ impl Renderer {
                                 &mut encoder,
                                 world_view,
                                 world_depth,
-                                pack_post,
+                                pack_reads_world,
                             );
                             pass.set_bind_group(0, &self.group, &[]);
                             pass.set_pipeline(&self.solid);
@@ -4427,6 +4464,20 @@ impl Renderer {
                 &mut terrain,
             );
             self.pack_post = Some((dimension, Some(post)));
+        } else if let Some((color, depth)) = &scaled
+            && native_post
+            && let Some(post) = &mut self.native_post
+        {
+            let size = self.world_post.size().unwrap_or([1, 1]);
+            post.run(
+                &self.device,
+                &self.queue,
+                &mut encoder,
+                (color, depth),
+                &view_target,
+                frame,
+                size,
+            );
         } else if scaled.is_some() {
             self.world_post.finish(&mut encoder, &view_target);
         }
diff --git a/crates/horizon-client/src/gfx/native_post.rs b/crates/horizon-client/src/gfx/native_post.rs
new file mode 100644
index 000000000..c4af862d7
--- /dev/null
+++ b/crates/horizon-client/src/gfx/native_post.rs
@@ -0,0 +1,509 @@
+//! The post stage of Horizon's own shader packs (docs/shaders.md): each `[[post]]` pass is a
+//! full-screen pipeline built from its checked naga module (`horizon_shader_api::check`), with
+//! the pack's options as pipeline constants. A pass reads bind group 3: the frame, the world's
+//! colour and depth, the previous pass's output and two samplers. Passes before the last write
+//! half-float targets of the world's size, so values over 1 carry to the next; the last draws
+//! onto the screen.
+
+use glam::{Mat4, Vec3};
+use horizon_shader_api::{Frame as FrameInputs, check::CheckedStage, stages::GROUP};
+
+use super::Frame;
+
+const INTERMEDIATE: wgpu::TextureFormat = wgpu::TextureFormat::Rgba16Float;
+
+/// The world's colour and depth views a set of bind groups was made for.
+type WorldViews = (wgpu::TextureView, wgpu::TextureView);
+
+pub struct NativePost {
+    passes: Vec<(String, wgpu::RenderPipeline)>,
+    layout: wgpu::BindGroupLayout,
+    frame: wgpu::Buffer,
+    linear: wgpu::Sampler,
+    nearest: wgpu::Sampler,
+    /// Two targets of the world's size, written in turn (none with a single pass).
+    targets: Option<([u32; 2], [wgpu::TextureView; 2])>,
+    /// One bind group per pass, for these world views.
+    groups: Option<(WorldViews, Vec<wgpu::BindGroup>)>,
+    start: std::time::Instant,
+    frames: u32,
+}
+
+fn texture_entry(binding: u32, sample_type: wgpu::TextureSampleType) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding,
+        visibility: wgpu::ShaderStages::FRAGMENT,
+        ty: wgpu::BindingType::Texture {
+            sample_type,
+            view_dimension: wgpu::TextureViewDimension::D2,
+            multisampled: false,
+        },
+        count: None,
+    }
+}
+
+fn sampler_entry(binding: u32) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding,
+        visibility: wgpu::ShaderStages::FRAGMENT,
+        ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
+        count: None,
+    }
+}
+
+impl NativePost {
+    /// Pipelines for `stages` (the pack's post passes, in order) with the option values
+    /// `constants`, drawing onto a screen of `format`. Errors name the pass wgpu refused.
+    pub fn new(
+        device: &wgpu::Device,
+        stages: Vec<CheckedStage>,
+        constants: &[(String, f64)],
+        format: wgpu::TextureFormat,
+    ) -> Result<Self, String> {
+        let float = wgpu::TextureSampleType::Float { filterable: true };
+        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+            label: Some("Native shader pack post"),
+            entries: &[
+                wgpu::BindGroupLayoutEntry {
+                    binding: 0,
+                    visibility: wgpu::ShaderStages::FRAGMENT,
+                    ty: wgpu::BindingType::Buffer {
+                        ty: wgpu::BufferBindingType::Uniform,
+                        has_dynamic_offset: false,
+                        min_binding_size: wgpu::BufferSize::new(size_of::<FrameInputs>() as u64),
+                    },
+                    count: None,
+                },
+                texture_entry(1, float),
+                texture_entry(2, wgpu::TextureSampleType::Depth),
+                texture_entry(3, float),
+                sampler_entry(4),
+                sampler_entry(5),
+            ],
+        });
+        let mut groups: [Option<&wgpu::BindGroupLayout>; GROUP as usize + 1] = Default::default();
+        groups[GROUP as usize] = Some(&layout);
+        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+            label: Some("Native shader pack post"),
+            bind_group_layouts: &groups,
+            ..Default::default()
+        });
+        let count = stages.len();
+        let mut passes = Vec::with_capacity(count);
+        for (i, stage) in stages.into_iter().enumerate() {
+            let present: Vec<(&str, f64)> = constants
+                .iter()
+                .filter(|(id, _)| {
+                    stage
+                        .module
+                        .overrides
+                        .iter()
+                        .any(|(_, o)| o.name.as_ref() == Some(id))
+                })
+                .map(|(id, v)| (id.as_str(), *v))
+                .collect();
+            let scope = device.push_error_scope(wgpu::ErrorFilter::Validation);
+            let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+                label: Some(&stage.label),
+                source: wgpu::ShaderSource::Naga(std::borrow::Cow::Owned(stage.module)),
+            });
+            let options = wgpu::PipelineCompilationOptions {
+                constants: &present,
+                ..Default::default()
+            };
+            let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
+                label: Some(&stage.label),
+                layout: Some(&pipeline_layout),
+                vertex: wgpu::VertexState {
+                    module: &module,
+                    entry_point: Some("horizon_vs_post"),
+                    compilation_options: options.clone(),
+                    buffers: &[],
+                },
+                primitive: Default::default(),
+                depth_stencil: None,
+                multisample: Default::default(),
+                fragment: Some(wgpu::FragmentState {
+                    module: &module,
+                    entry_point: Some("horizon_fs_post"),
+                    compilation_options: options,
+                    targets: &[Some(wgpu::ColorTargetState {
+                        format: if i + 1 == count { format } else { INTERMEDIATE },
+                        blend: None,
+                        write_mask: wgpu::ColorWrites::ALL,
+                    })],
+                }),
+                multiview_mask: None,
+                cache: None,
+            });
+            if let Some(e) = pollster::block_on(scope.pop()) {
+                return Err(format!("{}: {e}", stage.file));
+            }
+            passes.push((stage.label, pipeline));
+        }
+        let frame = device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("Native shader pack frame"),
+            size: size_of::<FrameInputs>() as u64,
+            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let sampler = |label, filter| {
+            device.create_sampler(&wgpu::SamplerDescriptor {
+                label: Some(label),
+                mag_filter: filter,
+                min_filter: filter,
+                ..Default::default()
+            })
+        };
+        Ok(Self {
+            passes,
+            layout,
+            frame,
+            linear: sampler("Native shader pack linear", wgpu::FilterMode::Linear),
+            nearest: sampler("Native shader pack nearest", wgpu::FilterMode::Nearest),
+            targets: None,
+            groups: None,
+            start: std::time::Instant::now(),
+            frames: 0,
+        })
+    }
+
+    /// The passes' labels, in order.
+    pub fn labels(&self) -> Vec<&str> {
+        self.passes.iter().map(|(l, _)| l.as_str()).collect()
+    }
+
+    fn prepare(
+        &mut self,
+        device: &wgpu::Device,
+        world: (&wgpu::TextureView, &wgpu::TextureView),
+        size: [u32; 2],
+    ) {
+        if self.passes.len() > 1 && self.targets.as_ref().is_none_or(|t| t.0 != size) {
+            let target = |label| {
+                device
+                    .create_texture(&wgpu::TextureDescriptor {
+                        label: Some(label),
+                        size: wgpu::Extent3d {
+                            width: size[0],
+                            height: size[1],
+                            depth_or_array_layers: 1,
+                        },
+                        mip_level_count: 1,
+                        sample_count: 1,
+                        dimension: wgpu::TextureDimension::D2,
+                        format: INTERMEDIATE,
+                        usage: wgpu::TextureUsages::RENDER_ATTACHMENT
+                            | wgpu::TextureUsages::TEXTURE_BINDING,
+                        view_formats: &[],
+                    })
+                    .create_view(&Default::default())
+            };
+            self.targets = Some((
+                size,
+                [
+                    target("Native shader pack A"),
+                    target("Native shader pack B"),
+                ],
+            ));
+            self.groups = None;
+        }
+        if self
+            .groups
+            .as_ref()
+            .is_some_and(|((color, depth), _)| color == world.0 && depth == world.1)
+        {
+            return;
+        }
+        let groups = (0..self.passes.len())
+            .map(|i| {
+                // Pass i reads what pass i - 1 wrote: target (i - 1) % 2, the world for the first.
+                let previous = match (&self.targets, i) {
+                    (Some((_, t)), 1..) => &t[(i - 1) % 2],
+                    _ => world.0,
+                };
+                device.create_bind_group(&wgpu::BindGroupDescriptor {
+                    label: Some("Native shader pack post"),
+                    layout: &self.layout,
+                    entries: &[
+                        wgpu::BindGroupEntry {
+                            binding: 0,
+                            resource: self.frame.as_entire_binding(),
+                        },
+                        wgpu::BindGroupEntry {
+                            binding: 1,
+                            resource: wgpu::BindingResource::TextureView(world.0),
+                        },
+                        wgpu::BindGroupEntry {
+                            binding: 2,
+                            resource: wgpu::BindingResource::TextureView(world.1),
+                        },
+                        wgpu::BindGroupEntry {
+                            binding: 3,
+                            resource: wgpu::BindingResource::TextureView(previous),
+                        },
+                        wgpu::BindGroupEntry {
+                            binding: 4,
+                            resource: wgpu::BindingResource::Sampler(&self.linear),
+                        },
+                        wgpu::BindGroupEntry {
+                            binding: 5,
+                            resource: wgpu::BindingResource::Sampler(&self.nearest),
+                        },
+                    ],
+                })
+            })
+            .collect();
+        self.groups = Some(((world.0.clone(), world.1.clone()), groups));
+    }
+
+    /// Runs the passes over the world target `world` (colour, depth) of `size`, the last onto
+    /// `screen`.
+    pub fn run(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        world: (&wgpu::TextureView, &wgpu::TextureView),
+        screen: &wgpu::TextureView,
+        frame: &Frame,
+        size: [u32; 2],
+    ) {
+        let seconds = self.start.elapsed().as_secs_f32() % 3600.0;
+        let inputs = frame_inputs(frame, size, seconds, self.frames);
+        self.frames = self.frames.wrapping_add(1);
+        self.draw(device, queue, encoder, world, screen, &inputs, size);
+    }
+
+    fn draw(
+        &mut self,
+        device: &wgpu::Device,
+        queue: &wgpu::Queue,
+        encoder: &mut wgpu::CommandEncoder,
+        world: (&wgpu::TextureView, &wgpu::TextureView),
+        screen: &wgpu::TextureView,
+        inputs: &FrameInputs,
+        size: [u32; 2],
+    ) {
+        self.prepare(device, world, size);
+        queue.write_buffer(&self.frame, 0, bytemuck::bytes_of(inputs));
+        let Some((_, groups)) = &self.groups else {
+            return;
+        };
+        for (i, ((label, pipeline), group)) in self.passes.iter().zip(groups).enumerate() {
+            let view = match &self.targets {
+                Some((_, t)) if i + 1 < self.passes.len() => &t[i % 2],
+                _ => screen,
+            };
+            let attachments = [Some(wgpu::RenderPassColorAttachment {
+                view,
+                resolve_target: None,
+                depth_slice: None,
+                ops: wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
+                    store: wgpu::StoreOp::Store,
+                },
+            })];
+            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: Some(label),
+                color_attachments: &attachments,
+                ..Default::default()
+            });
+            pass.set_pipeline(pipeline);
+            pass.set_bind_group(GROUP, group, &[]);
+            pass.draw(0..3, 0..1);
+        }
+    }
+}
+
+/// The frame as packs read it (docs/api/shaders-reference.md), from the renderer's `Frame`.
+pub fn frame_inputs(frame: &Frame, size: [u32; 2], seconds: f32, index: u32) -> FrameInputs {
+    let aspect = size[0] as f32 / size[1].max(1) as f32;
+    let view = crate::camera::view_matrix(frame.yaw, frame.pitch);
+    let projection =
+        super::world_projection(frame.fov_degrees, aspect, frame.depth_far) * frame.bob;
+    // A celestial body's direction at `angle` degrees (SkyRenderer: Y -90°, then X by the
+    // angle, of straight up): overhead at 0, rising in the east (+x).
+    let body = |angle: f32| {
+        let a = angle.to_radians();
+        Vec3::new(-a.sin(), a.cos(), 0.0)
+    };
+    let (fog_color, fog_start, fog_end) = match &frame.fog {
+        Some(f) => (
+            [f.color[0], f.color[1], f.color[2]],
+            f.environmental_start.min(f.render_distance_start),
+            f.environmental_end.min(f.render_distance_end),
+        ),
+        None => (frame.sky.fog_color, frame.distance * 0.9, frame.distance),
+    };
+    let pack = &frame.pack;
+    let level = |l: i32| l as f32 / 15.0;
+    let m = |m: Mat4| m.to_cols_array_2d();
+    FrameInputs {
+        view: m(view),
+        projection: m(projection),
+        view_inverse: m(view.inverse()),
+        projection_inverse: m(projection.inverse()),
+        camera_position: frame.camera.as_vec3().to_array(),
+        time: seconds,
+        sun_direction: body(frame.sky.sun_angle).to_array(),
+        day_time: pack.day_time.rem_euclid(24000) as f32 / 24000.0,
+        moon_direction: body(frame.sky.moon_angle).to_array(),
+        game_time: frame.shader_game_time,
+        sky_color: frame.sky.sky_color,
+        rain: pack.rain,
+        fog_color,
+        thunder: pack.thunder,
+        resolution: [size[0] as f32, size[1] as f32],
+        eye_light: [level(pack.eye_light[0]), level(pack.eye_light[1])],
+        fog_start,
+        fog_end,
+        render_distance: frame.distance,
+        far: frame.depth_far,
+        night_vision: frame.night_vision,
+        blindness: pack.blindness,
+        darkness: frame.darkness.1.clamp(0.0, 1.0),
+        brightness: pack.brightness,
+        eye_in: pack.eye_in as u32,
+        dimension: if frame.end_sky {
+            1
+        } else if frame.nether_lighting {
+            -1
+        } else {
+            0
+        },
+        frame_index: index,
+        hide_gui: u32::from(pack.hide_gui),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use horizon_shader_api::{MANIFEST, Pack, check};
+
+    fn device() -> Option<(wgpu::Device, wgpu::Queue)> {
+        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle());
+        let adapter = pollster::block_on(instance.request_adapter(&Default::default())).ok()?;
+        pollster::block_on(adapter.request_device(&Default::default())).ok()
+    }
+
+    fn texture(
+        device: &wgpu::Device,
+        format: wgpu::TextureFormat,
+        usage: wgpu::TextureUsages,
+    ) -> wgpu::Texture {
+        device.create_texture(&wgpu::TextureDescriptor {
+            label: None,
+            size: wgpu::Extent3d {
+                width: 4,
+                height: 4,
+                depth_or_array_layers: 1,
+            },
+            mip_level_count: 1,
+            sample_count: 1,
+            dimension: wgpu::TextureDimension::D2,
+            format,
+            usage,
+            view_formats: &[],
+        })
+    }
+
+    /// Two passes: the first doubles the world's colour (over 1, so the half-float target
+    /// must keep it) times an option, the second halves it and writes the depth as alpha.
+    #[test]
+    fn passes_chain_through_half_float_targets_with_options_and_depth() {
+        let Some((device, queue)) = device() else {
+            return;
+        };
+        let manifest = "schema = 1\nid = \"t\"\nname = \"T\"\nversion = \"1\"\napi = \"0.1\"\n\
+            [[post]]\nfile = \"a.wgsl\"\n[[post]]\nfile = \"b.wgsl\"\n\
+            [[options]]\nid = \"gain\"\nname = \"Gain\"\ntype = \"float\"\ndefault = 0.0\nmin = 0.0\nmax = 2.0\n";
+        let a = "override gain: f32;\nfn post(input: PostInput) -> vec4<f32> { return vec4<f32>(input.color.rgb * 2.0 * gain, 1.0); }\n";
+        let b = "fn post(input: PostInput) -> vec4<f32> { return vec4<f32>(input.color.rgb * 0.5, input.depth); }\n";
+        let files = [(MANIFEST, manifest), ("a.wgsl", a), ("b.wgsl", b)]
+            .map(|(n, t)| (n.to_owned(), t.as_bytes().to_vec()))
+            .into();
+        let report = check(&Pack::from_files(files).unwrap()).unwrap();
+        let format = wgpu::TextureFormat::Rgba8Unorm;
+        let mut post =
+            NativePost::new(&device, report.stages, &[("gain".into(), 1.0)], format).unwrap();
+        assert_eq!(post.labels(), ["a.wgsl", "b.wgsl"]);
+
+        let usage = wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING;
+        let color = texture(&device, format, usage).create_view(&Default::default());
+        let depth = texture(&device, wgpu::TextureFormat::Depth32Float, usage)
+            .create_view(&Default::default());
+        let screen = texture(
+            &device,
+            format,
+            wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
+        );
+        let mut encoder = device.create_command_encoder(&Default::default());
+        encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: None,
+            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                view: &color,
+                resolve_target: None,
+                depth_slice: None,
+                ops: wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(wgpu::Color {
+                        r: 0.8,
+                        g: 0.4,
+                        b: 0.2,
+                        a: 1.0,
+                    }),
+                    store: wgpu::StoreOp::Store,
+                },
+            })],
+            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
+                view: &depth,
+                depth_ops: Some(wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(0.5),
+                    store: wgpu::StoreOp::Store,
+                }),
+                stencil_ops: None,
+            }),
+            ..Default::default()
+        });
+        let view = screen.create_view(&Default::default());
+        post.draw(
+            &device,
+            &queue,
+            &mut encoder,
+            (&color, &depth),
+            &view,
+            &FrameInputs::default(),
+            [4, 4],
+        );
+        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
+            label: None,
+            size: u64::from(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT * 4),
+            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        encoder.copy_texture_to_buffer(
+            screen.as_image_copy(),
+            wgpu::TexelCopyBufferInfo {
+                buffer: &buffer,
+                layout: wgpu::TexelCopyBufferLayout {
+                    offset: 0,
+                    bytes_per_row: Some(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT),
+                    rows_per_image: Some(4),
+                },
+            },
+            screen.size(),
+        );
+        queue.submit([encoder.finish()]);
+        buffer
+            .slice(..)
+            .map_async(wgpu::MapMode::Read, |r| r.unwrap());
+        device.poll(wgpu::PollType::wait_indefinitely()).unwrap();
+        let pixel = buffer.slice(..).get_mapped_range().unwrap()[..4].to_vec();
+        let near = |got: u8, want: u8| got.abs_diff(want) <= 1;
+        assert!(
+            near(pixel[0], 204) && near(pixel[1], 102) && near(pixel[2], 51) && near(pixel[3], 128),
+            "{pixel:?}"
+        );
+    }
+}
diff --git a/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl b/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
index 4d523c9ef..e27b98244 100644
--- a/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
+++ b/crates/horizon-shader-api/packs/golden_hour/post/glow.wgsl
@@ -1,9 +1,12 @@
-// A soft halo around bright pixels: twelve taps on two rings, scaled with
-// the picture's height so it looks the same at any resolution.
+// A soft halo around the brightest pixels (the sun, lava, torches at night): twelve taps on two
+// rings, scaled with the picture's height so it looks the same at any resolution. The daytime
+// sky is bright too, so it glows only a quarter as much.
 override glow: f32 = 0.35;
 
-fn bright(c: vec3<f32>) -> vec3<f32> {
-    return c * smoothstep(0.7, 1.0, luminance(c));
+fn bright(uv: vec2<f32>) -> vec3<f32> {
+    let c = textureSampleLevel(previous, linear_sampler, uv, 0.0).rgb;
+    let sky = select(1.0, 0.25, depth_at(uv) == 0.0);
+    return c * smoothstep(0.8, 1.0, luminance(c)) * sky;
 }
 
 fn post(input: PostInput) -> vec4<f32> {
@@ -16,7 +19,7 @@ fn post(input: PostInput) -> vec4<f32> {
         let angle = f32(i) * 0.5235988;
         let radius = select(3.0, 7.0, (i & 1) == 1);
         let offset = vec2<f32>(cos(angle), sin(angle)) * radius * step;
-        sum += bright(textureSampleLevel(previous, linear_sampler, input.uv + offset, 0.0).rgb);
+        sum += bright(input.uv + offset);
     }
-    return vec4<f32>(input.color.rgb + sum * (glow / 6.0), input.color.a);
+    return vec4<f32>(input.color.rgb + sum * (glow / 8.0), input.color.a);
 }
diff --git a/crates/horizon-shader-api/src/inputs.rs b/crates/horizon-shader-api/src/inputs.rs
index 5bc82fd82..f25fe2847 100644
--- a/crates/horizon-shader-api/src/inputs.rs
+++ b/crates/horizon-shader-api/src/inputs.rs
@@ -158,7 +158,7 @@ pub const POST_INPUT: Struct = Struct {
     doc: "One pixel of the picture, for `fn post(input: PostInput) -> vec4<f32>`.",
     fields: fields! {
         uv: "vec2<f32>" = "Where the pixel is, 0..1 from the top left.",
-        pixel: "vec2<f32>" = "The pixel's centre, in pixels from the top left.",
+        pixel: "vec2<f32>" = "The pixel's centre, in pixels from the top left of what the pass draws (the world's size; the window's for the last pass).",
         color: "vec4<f32>" = "The previous pass's colour here (the world's picture for the first pass).",
         depth: "f32" = "The world's depth here, reversed: 0 is the sky.",
     },
diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs
index e2e644a04..b148d95c5 100644
--- a/crates/horizon-shader-api/src/package.rs
+++ b/crates/horizon-shader-api/src/package.rs
@@ -46,6 +46,13 @@ pub fn plain_path(path: &str) -> bool {
         })
 }
 
+/// Whether `path` is a pack of this format: a folder holding
+/// `horizon-shaders.toml`, or a `.hshader` file.
+pub fn is_pack(path: &Path) -> bool {
+    path.join(MANIFEST).is_file()
+        || (path.is_file() && path.extension().is_some_and(|e| e == EXTENSION))
+}
+
 impl Pack {
     /// Reads `path`: a `.hshader` file, or a folder (its hidden files and
     /// folders, such as `.git`, are skipped).
diff --git a/docs/api/shaders-reference.md b/docs/api/shaders-reference.md
index f9682a1a4..400d5029b 100644
--- a/docs/api/shaders-reference.md
+++ b/docs/api/shaders-reference.md
@@ -77,7 +77,7 @@ One pixel of the picture, for `fn post(input: PostInput) -> vec4<f32>`.
 | Field | Type | Meaning |
 | --- | --- | --- |
 | `uv` | `vec2<f32>` | Where the pixel is, 0..1 from the top left. |
-| `pixel` | `vec2<f32>` | The pixel's centre, in pixels from the top left. |
+| `pixel` | `vec2<f32>` | The pixel's centre, in pixels from the top left of what the pass draws (the world's size; the window's for the last pass). |
 | `color` | `vec4<f32>` | The previous pass's colour here (the world's picture for the first pass). |
 | `depth` | `f32` | The world's depth here, reversed: 0 is the sky. |
 
diff --git a/docs/api/shaders.md b/docs/api/shaders.md
index 8e9e6919c..675c5e3fc 100644
--- a/docs/api/shaders.md
+++ b/docs/api/shaders.md
@@ -96,6 +96,7 @@ stages with options and hot reload, then the overlay, lighting, sky and shadow s
 
 ## Changelog
 
+- 2026-10-26: the post stage in the game (`HORIZON_SHADER_PACK`, hot reload with the last good pack kept).
 - 2026-10-25: `horizon-shader` (`new`, `check`, `pack`), three templates, the example pack and the guide.
 - 2026-10-25: the check (naga validation, signatures, options, budgets, SPIR-V/Metal/HLSL translation).
 - 2026-10-25: the stages of API 0.1 (sky, material, post), their inputs and the generated reference.
diff --git a/docs/shaders.md b/docs/shaders.md
index 99a08fa9a..ef8521cfe 100644
--- a/docs/shaders.md
+++ b/docs/shaders.md
@@ -13,7 +13,8 @@ Horizon's own format.
 | Authoring tool | `horizon-shader` (same crate) | `new`, `check`, `pack` |
 | Templates | `crates/horizon-shader-api/templates/` | post, sky, material |
 | Example pack | `crates/horizon-shader-api/packs/golden_hour` | a warm sky and two post passes |
-| In the game, the launcher, the registry | | not yet: the renderer hooks come next |
+| In the game: the post stage | `HORIZON_SHADER_PACK=<name>` (for development, until the Shader Packs page) | post passes, hot reload |
+| In the game: sky and material; the launcher and the registry | | not yet |
 
 ## Quick start
 
@@ -29,9 +30,9 @@ horizon-shader pack my_pack                         # check, then write my_pack-
 ```
 golden_hour 1.0.0 (shader API 0.1): ok
   sky       Warm horizon                     99 expressions, 0 texture reads
-  post      Glow                            185 expressions, 3 texture reads
+  post      Glow                            192 expressions, 3 texture reads
   post      Colour grade                    201 expressions, 2 texture reads
-  sha256 fd92a294...
+  sha256 b5e0d98c...
 ```
 
 or every problem, at its file, line and column:
@@ -43,6 +44,15 @@ my_pack 0.1.0 (shader API 0.1): FAILED
 
 `--json` prints the same for tools (`ok`, `id`, `version`, `api`, `sha256`, `stages`, `problems`).
 
+## Trying a pack in the game
+
+Until the Shader Packs page lists them, put the pack folder (or its `.hshader`) in `shaderpacks/` beside `options.txt`
+and start the game with `HORIZON_SHADER_PACK=<its folder or file name>`. The game checks the pack first, and refuses
+one that fails, with its problems in the chat. While it runs, the game looks at the pack twice a second: save a file
+and the pack is checked and rebuilt in place ("Shader pack ... reloaded"); if the new version fails, the chat says
+where and the last good version keeps drawing. The post passes run today; the sky and material stages are checked
+but not drawn yet.
+
 ## A pack
 
 A folder (or the same files zipped as a `.hshader`) with `horizon-shaders.toml` and WGSL files:

From 8fdb27f9493ff31a664f3c6683e5ce8c57dd7084 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:35:16 +0100
Subject: [PATCH 260/270] Zoom: the game lists its key on the settings page, as
 "Zoom key: Z"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 mods/official/zoom/src/lib.rs | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/mods/official/zoom/src/lib.rs b/mods/official/zoom/src/lib.rs
index f55f10235..072a40eb0 100644
--- a/mods/official/zoom/src/lib.rs
+++ b/mods/official/zoom/src/lib.rs
@@ -1,8 +1,9 @@
 //! Horizon's official zoom, formerly the built-in extra: hold the key (Z
 //! by default) to zoom in, and turn the mouse wheel while holding it to zoom
-//! further in or out. Its settings page has the extra's four options. The
-//! key is bound on the page and kept by the game (`horizon-mods.txt`); the
-//! rest is kept in the mod's storage (`level`, `smooth`, `sensitivity`),
+//! further in or out. Its settings page has the extra's four options: the
+//! game lists the key there first and keeps the player's choice
+//! (`horizon-mods.txt`); the rest is kept in the mod's storage (`level`,
+//! `smooth`, `sensitivity`),
 //! where the game writes a player's old extra settings when it installs the
 //! mod for them.
 use horizon_mod_sdk::{
@@ -10,10 +11,10 @@ use horizon_mod_sdk::{
     input::{self, Event},
     render::{self, Zoom as ZoomView},
     storage,
-    ui::{self, ButtonWidget, KeyWidget, Widget},
+    ui::{self, ButtonWidget, Widget},
 };
 
-/// The key's name for `register-key` and the settings page.
+/// The key's name for `register-key`.
 const KEY: &str = "zoom";
 /// The zooms the starting zoom cycles through, and the wheel's limits.
 const LEVELS: [u8; 6] = [2, 3, 4, 6, 8, 10];
@@ -21,8 +22,7 @@ const MIN: f32 = 1.25;
 const MAX: f32 = 10.0;
 /// Each wheel step multiplies the zoom by this.
 const STEP: f32 = 1.25;
-/// Settings page widgets.
-const KEY_WIDGET: u32 = 1;
+/// Settings page buttons, under the key's row.
 const LEVEL_BUTTON: u32 = 2;
 const SMOOTH_BUTTON: u32 = 3;
 const SENSITIVITY_BUTTON: u32 = 4;
@@ -51,10 +51,6 @@ impl Zoom {
     fn page(&self) {
         let on = |b: bool| if b { "ON" } else { "OFF" };
         ui::set_settings(&[
-            Widget::Key(KeyWidget {
-                id: KEY_WIDGET,
-                key: KEY.into(),
-            }),
             Widget::Button(ButtonWidget {
                 id: LEVEL_BUTTON,
                 label: format!("Starting zoom: {}x", self.level),
@@ -83,7 +79,7 @@ fn stored(key: &str) -> Option<String> {
 
 impl Mod for Zoom {
     fn init() -> Result<(Self, Registration), String> {
-        input::register_key(KEY, "Zoom", "key.keyboard.z")?;
+        input::register_key(KEY, "Zoom key", "key.keyboard.z")?;
         // The extra's defaults: 4x, smooth, slower turning.
         let level = stored("level")
             .and_then(|v| v.trim().parse::<u8>().ok())

From 2c5dac354eb0f5b7c3812803e5d4798f54973c34 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 06:11:01 +0100
Subject: [PATCH 261/270] parity-main: name a merge only when HEAD fails again
 and the base passes

The bisect ended on the newest merge when the failed harnesses pass
everywhere now (a flake, or a runner that was missing the sounds), and
on the oldest when they fail everywhere (the runner), and commented on
that pull request either way. It now reruns them at HEAD and at the base
first and names nobody unless HEAD fails and the base passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_parity_main.py | 29 +++++++++++++++++++++++++++++
 tools/parity_main.py      | 17 ++++++++++++++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/tests/test_parity_main.py b/tests/test_parity_main.py
index 7a72ecae5..aa58375a6 100644
--- a/tests/test_parity_main.py
+++ b/tests/test_parity_main.py
@@ -33,6 +33,35 @@ class ParityMainTests(unittest.TestCase):
             self.assertEqual(parity_main.base(runs=[]), parent, "no green run yet: the last merge")
             self.assertEqual(parity_main.base(runs=[head]), head)
 
+    def test_bisect_names_a_merge_only_when_head_fails_and_the_base_passes(self):
+        with tempfile.TemporaryDirectory() as tmp, mock.patch.object(parity_main, "ROOT", Path(tmp)):
+            git = lambda *arguments: parity_main.git(*arguments).stdout.strip()
+            git("init", "-q")
+            for n in range(4):
+                git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty",
+                    "-m", f"Merge pull request #{n} from x/y")
+            commits = git("rev-list", "--reverse", "HEAD").split()
+            last_run = Path(tmp) / ".local/parity-runner/last-run.json"
+            last_run.parent.mkdir(parents=True)
+            last_run.write_text('{"failed": ["music"]}')
+            real_run = parity_main.subprocess.run
+            for broken_from, blamed in ((None, None), (0, None), (2, "2")):
+                comments = []
+                # git runs for real in the scratch repo; a `gh pr comment` is only recorded, never sent.
+                fake_run = lambda command, **kwargs: (comments.append(command) if command[0] == "gh"
+                                                      else real_run(command, **kwargs))
+                with mock.patch.object(parity_main, "LAST_RUN", last_run), \
+                     mock.patch.object(parity_main, "run_harnesses", lambda names, timeout: broken_from is not None
+                                       and commits.index(git("rev-parse", "HEAD")) >= broken_from), \
+                     mock.patch.object(parity_main.subprocess, "run", fake_run), \
+                     mock.patch("builtins.print") as printed:
+                    parity_main.bisect(commits[0], 60, comment=True)
+                if blamed:
+                    self.assertEqual([command[3] for command in comments], [blamed])
+                else:
+                    self.assertEqual(comments, [], printed.call_args_list[-1])
+                self.assertEqual(git("rev-parse", "HEAD"), commits[-1], "HEAD checked out again")
+
     def test_a_harness_a_commit_does_not_have_cannot_fail_there(self):
         with mock.patch.object(parity_main.subprocess, "run") as run:
             self.assertFalse(parity_main.run_harnesses(["not_a_harness_yet"], 60))
diff --git a/tools/parity_main.py b/tools/parity_main.py
index ff319aed0..76fa49070 100644
--- a/tools/parity_main.py
+++ b/tools/parity_main.py
@@ -8,7 +8,7 @@
 so a run tests every merge since the last green one (`tools/parity.py --changed <base>`), however many landed while
 the previous run went on. `bisect` reads the harnesses that failed (.local/parity-runner/last-run.json), checks out
 the first-parent merges between BASE and HEAD by halves and runs only those harnesses, then names the first merge they
-fail on (written to $GITHUB_STEP_SUMMARY and, with --comment, on its pull request). HEAD is checked out again at the end.
+fail on, once they fail again at HEAD and pass at BASE (written to $GITHUB_STEP_SUMMARY and, with --comment, on its pull request). HEAD is checked out again at the end.
 """
 
 import argparse
@@ -90,7 +90,22 @@ def bisect(since, timeout, comment):
         git("checkout", "-q", "--detach", commit)
         return run_harnesses(failed, timeout)
 
+    def blame_nobody(why):
+        line = f"parity-main: {', '.join(failed)} {why}: no merge is named."
+        print(line)
+        if os.environ.get("GITHUB_STEP_SUMMARY"):
+            with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as summary:
+                summary.write(f"### {line}\n")
+        return 0
+
+    # A merge is named only when the harnesses fail again at HEAD and pass at the base: otherwise the search would
+    # end on the newest merge (a flake, or a runner missing files, passes everywhere now) or the oldest one (the
+    # runner fails at every commit) and blame it for nothing.
     try:
+        if not fails(head):
+            return blame_nobody(f"pass when run again at {head[:9]}: a flake or the runner")
+        if fails(since):
+            return blame_nobody(f"fail at the base {since[:9]} too: the runner or a flake")
         culprit = first_bad(commits, fails) if len(commits) > 1 else commits[0]
     finally:
         git("checkout", "-q", "--detach", head)

From a6c8e9070a6557470bab6ba08fd31ca8ec9ad88a Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 06:42:14 +0100
Subject: [PATCH 262/270] Zoom moved to the mod browser: remove the built-in
 zoom

The official Zoom mod (mods/official/zoom) does what the extra did. The
extra's zoom, its key and wheel hooks and its Extras rows go; the camera
keeps a mod's zoom (render.set-zoom). A player who had zoom on gets the
mod installed and turned on at the first start, with the starting zoom,
smooth zoom and slower turning carried into its storage and a changed
key into horizon-mods.txt, and one chat line. horizon-extras.txt keeps
the old keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/extras.rs           | 234 +-----------------
 crates/horizon-client/src/game.rs             |   4 +-
 crates/horizon-client/src/game/control.rs     |  12 +-
 crates/horizon-client/src/game/extras.rs      |  67 +----
 .../horizon-client/src/game/moved_extras.rs   |   7 +
 crates/horizon-client/src/moved_extras.rs     |  50 +++-
 crates/horizon-client/src/options_ui.rs       |  22 +-
 docs/extras.md                                |  39 +--
 website/docs/index.md                         |   2 +-
 website/docs/settings.md                      |   2 +-
 10 files changed, 106 insertions(+), 333 deletions(-)

diff --git a/crates/horizon-client/src/extras.rs b/crates/horizon-client/src/extras.rs
index c8683bb92..b5b4fb165 100644
--- a/crates/horizon-client/src/extras.rs
+++ b/crates/horizon-client/src/extras.rs
@@ -1,4 +1,4 @@
-//! Horizon's optional extras (zoom, FPS counter, keystroke overlay): their
+//! Horizon's optional extras (minimap, lighting, inventory tools): their
 //! settings, kept in `horizon-extras.txt` next to `options.txt` so that file
 //! stays exactly vanilla's, and the logic behind them. Every extra is off by
 //! default; see `docs/extras.md`. Horizon's own switches outside the Extras page
@@ -6,17 +6,8 @@
 use std::{collections::VecDeque, fs, path::Path};
 
 pub const FILE: &str = "horizon-extras.txt";
-/// The name the options screen uses while the zoom key waits for a key.
-pub const ZOOM_KEY: &str = "horizon.zoom";
-/// The same for the sort key.
+/// The name the options screen uses while the sort key waits for a key.
 pub const SORT_KEY: &str = "horizon.sort";
-/// Zoom levels the default cycles through, and the wheel's limits.
-pub const ZOOM_LEVELS: [u8; 6] = [2, 3, 4, 6, 8, 10];
-pub const ZOOM_MIN: f32 = 1.25;
-/// `Camera.tickFov` keeps the field-of-view modifier at 0.1 or more.
-pub const ZOOM_MAX: f32 = 10.0;
-/// Each wheel step multiplies the zoom by this.
-const ZOOM_STEP: f32 = 1.25;
 
 /// The minimap's sizes in GUI pixels, and its zooms in blocks per pixel.
 pub const MINIMAP_SIZES: [(u8, &str); 3] = [(64, "Small"), (96, "Medium"), (128, "Large")];
@@ -184,7 +175,7 @@ impl Extras {
                 "zoomKey" if value.starts_with("key.") => e.zoom_key = value.to_owned(),
                 "zoomLevel" => {
                     if let Ok(v) = value.parse::<u8>() {
-                        e.zoom_level = v.clamp(2, ZOOM_MAX as u8);
+                        e.zoom_level = v.clamp(2, 10);
                     }
                 }
                 "zoomSmooth" => e.zoom_smooth = flag(e.zoom_smooth),
@@ -270,11 +261,10 @@ impl Extras {
             bool_text(self.discord_presence),
         )
     }
-    /// Binds the extra key `name` (`ZOOM_KEY`, `SORT_KEY`); false for
+    /// Binds the extra key `name` (`SORT_KEY`); false for
     /// another name (a vanilla mapping).
     pub fn set_key(&mut self, name: &str, value: String) -> bool {
         match name {
-            ZOOM_KEY => self.zoom_key = value,
             SORT_KEY => self.sort_key = value,
             _ => return false,
         }
@@ -291,87 +281,12 @@ impl Extras {
     }
 }
 
-/// The zoom key's state: held or not, and the zoom the wheel has set.
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct Zoom {
-    held: bool,
-    factor: f32,
-}
-impl Default for Zoom {
-    fn default() -> Self {
-        Self {
-            held: false,
-            factor: 1.0,
-        }
-    }
-}
-impl Zoom {
-    /// The key went down: start at the default level.
-    pub fn press(&mut self, level: u8) {
-        self.held = true;
-        self.factor = f32::from(level).clamp(ZOOM_MIN, ZOOM_MAX);
-    }
-    pub fn release(&mut self) {
-        self.held = false;
-    }
-    /// A press or release of the zoom key. Only a press while `playing` (no
-    /// screen or text field open) zooms; anywhere else the key belongs to
-    /// the screen, and the zoom lets go.
-    pub fn key(&mut self, pressed: bool, repeat: bool, playing: bool, level: u8) {
-        if !pressed || !playing {
-            self.release();
-        } else if !repeat {
-            self.press(level);
-        }
-    }
-    pub fn held(&self) -> bool {
-        self.held
-    }
-    /// Wheel steps while held (positive zooms in); false when not zooming.
-    pub fn scroll(&mut self, steps: f32) -> bool {
-        if !self.held {
-            return false;
-        }
-        self.factor = (self.factor * ZOOM_STEP.powf(steps)).clamp(ZOOM_MIN, ZOOM_MAX);
-        true
-    }
-    /// The zoom in effect: 1 when the key is up or the spyglass is in use
-    /// (scoping keeps vanilla's spyglass view).
-    pub fn factor(&self, scoping: bool) -> f32 {
-        if self.held && !scoping {
-            self.factor
-        } else {
-            1.0
-        }
-    }
-}
-/// Vanilla key mappings bound to the zoom key. The key still reaches them
-/// (a key bound twice triggers both, as vanilla's do), so the Extras page
-/// says so.
-pub fn zoom_key_conflicts(e: &Extras, keys: &crate::keybinds::KeyBinds) -> Vec<&'static str> {
-    if e.zoom_key == "key.keyboard.unknown" {
-        return Vec::new();
-    }
-    crate::keybinds::MAPPINGS
-        .iter()
-        .map(|m| m.0)
-        .filter(|name| keys.get(name) == e.zoom_key)
-        .collect()
-}
 /// The field-of-view modifier target `Camera.tickFov` eases toward: vanilla's
-/// (`getFieldOfViewModifier`) divided by the zoom. A zoom of 1 leaves it as is.
+/// (`getFieldOfViewModifier`) divided by a mod's zoom (`render.set-zoom`). A
+/// zoom of 1 leaves it as is.
 pub fn fov_target(vanilla: f32, zoom: f32) -> f32 {
     if zoom == 1.0 { vanilla } else { vanilla / zoom }
 }
-/// The mouse turning scale while zoomed.
-pub fn turn_scale(zoom: f32, lower_sensitivity: bool) -> f64 {
-    if lower_sensitivity && zoom > 1.0 {
-        1.0 / f64::from(zoom)
-    } else {
-        1.0
-    }
-}
-
 /// Frame times over the last few seconds: frames per second, the minimum
 /// and the 1% low, recomputed twice a second.
 pub struct FpsCounter {
@@ -463,11 +378,6 @@ impl Cps {
 pub enum Item {
     Fullbright,
     DynamicLights,
-    Zoom,
-    ZoomKey,
-    ZoomLevel,
-    ZoomSmooth,
-    ZoomSensitivity,
     Minimap,
     MinimapCorner,
     MinimapSize,
@@ -492,12 +402,6 @@ pub fn rows() -> Vec<Result<Item, &'static str>> {
         Err("Lighting"),
         Ok(Fullbright),
         Ok(DynamicLights),
-        Err("Zoom"),
-        Ok(Zoom),
-        Ok(ZoomKey),
-        Ok(ZoomLevel),
-        Ok(ZoomSmooth),
-        Ok(ZoomSensitivity),
         Err("Minimap"),
         Ok(Minimap),
         Ok(MinimapCorner),
@@ -534,11 +438,6 @@ impl Item {
         match self {
             Item::Fullbright => "Fullbright",
             Item::DynamicLights => "Dynamic lights",
-            Item::Zoom => "Zoom",
-            Item::ZoomKey => "Zoom key",
-            Item::ZoomLevel => "Starting zoom",
-            Item::ZoomSmooth => "Smooth zoom",
-            Item::ZoomSensitivity => "Slower turning",
             Item::MinimapCorner => "Corner",
             Item::Minimap => "Minimap",
             Item::MinimapSize => "Size",
@@ -559,12 +458,11 @@ impl Item {
     pub fn parent(self) -> Option<Item> {
         use Item::*;
         Some(match self {
-            ZoomKey | ZoomLevel | ZoomSmooth | ZoomSensitivity => Zoom,
             MinimapCorner | MinimapSize | MinimapShape | MinimapZoom | MinimapRotate => Minimap,
             MouseTweaksWheel => MouseTweaks,
             SortKey => Sort,
-            Fullbright | DynamicLights | Zoom | Minimap | MouseTweaks | Sort | AutoReconnect
-            | NoAi | AgentControl | DiscordPresence => {
+            Fullbright | DynamicLights | Minimap | MouseTweaks | Sort | AutoReconnect | NoAi
+            | AgentControl | DiscordPresence => {
                 return None;
             }
         })
@@ -576,11 +474,6 @@ impl Item {
             Item::DynamicLights => {
                 "Torches and other light sources held, dropped or on fire light the blocks around them."
             }
-            Item::Zoom => "Hold the zoom key to zoom; the wheel changes it while held.",
-            Item::ZoomKey => "Click, then press a key. Escape unbinds it.",
-            Item::ZoomLevel => "The zoom the key starts at.",
-            Item::ZoomSmooth => "Eases in and out like the spyglass.",
-            Item::ZoomSensitivity => "Turns slower the more you zoom in.",
             Item::MinimapCorner => "Overlays in one corner stack.",
             Item::Minimap => "A map of the loaded terrain around you, in map colours.",
             Item::MinimapSize => "How big the map is on screen.",
@@ -617,7 +510,7 @@ impl Item {
     pub fn cost(self) -> Option<crate::graphics_style::Cost> {
         use crate::graphics_style::Cost;
         match self {
-            Item::Fullbright | Item::Zoom => Some(Cost::None),
+            Item::Fullbright => Some(Cost::None),
             Item::Minimap | Item::DynamicLights => Some(Cost::Low),
             Item::AutoReconnect | Item::MouseTweaks | Item::Sort => Some(Cost::None),
             _ => None,
@@ -628,9 +521,6 @@ impl Item {
         Some(match self {
             Item::Fullbright => e.fullbright,
             Item::DynamicLights => e.dynamic_lights,
-            Item::Zoom => e.zoom,
-            Item::ZoomSmooth => e.zoom_smooth,
-            Item::ZoomSensitivity => e.zoom_sensitivity,
             Item::Minimap => e.minimap,
             Item::MinimapRotate => e.minimap_rotate,
             Item::AutoReconnect => e.auto_reconnect,
@@ -646,9 +536,7 @@ impl Item {
     /// The value of the other items, as their button shows it.
     pub fn value(self, e: &Extras) -> String {
         match self {
-            Item::ZoomKey => crate::keybinds::display_name(&e.zoom_key).plain(),
             Item::SortKey => crate::keybinds::display_name(&e.sort_key).plain(),
-            Item::ZoomLevel => format!("{}x", e.zoom_level),
             Item::MinimapCorner => e.minimap_corner.label().into(),
             Item::MinimapSize => MINIMAP_SIZES
                 .iter()
@@ -663,15 +551,11 @@ impl Item {
             },
         }
     }
-    /// A click (`back` for the right button). The zoom key binds instead.
+    /// A click (`back` for the right button). The sort key binds instead.
     pub fn cycle(self, e: &mut Extras, back: bool) {
         match self {
             Item::Fullbright => e.fullbright = !e.fullbright,
             Item::DynamicLights => e.dynamic_lights = !e.dynamic_lights,
-            Item::Zoom => e.zoom = !e.zoom,
-            Item::ZoomSmooth => e.zoom_smooth = !e.zoom_smooth,
-            Item::ZoomSensitivity => e.zoom_sensitivity = !e.zoom_sensitivity,
-            Item::ZoomLevel => e.zoom_level = next(&ZOOM_LEVELS, e.zoom_level, back),
             Item::Minimap => e.minimap = !e.minimap,
             Item::MinimapRotate => e.minimap_rotate = !e.minimap_rotate,
             Item::AutoReconnect => e.auto_reconnect = !e.auto_reconnect,
@@ -688,13 +572,12 @@ impl Item {
             Item::NoAi => e.no_ai = !e.no_ai,
             Item::AgentControl => e.agent_control = !e.agent_control,
             Item::DiscordPresence => e.discord_presence = !e.discord_presence,
-            Item::ZoomKey | Item::SortKey => {}
+            Item::SortKey => {}
         }
     }
     /// The key name the options screen waits on for a key item.
     pub fn key_name(self) -> Option<&'static str> {
         match self {
-            Item::ZoomKey => Some(ZOOM_KEY),
             Item::SortKey => Some(SORT_KEY),
             _ => None,
         }
@@ -752,43 +635,7 @@ mod tests {
     }
 
     #[test]
-    fn default_zoom_key_is_free_in_vanilla() {
-        let key = Extras::default().zoom_key;
-        assert!(crate::keybinds::key_code(&key).is_some());
-        assert!(
-            crate::keybinds::MAPPINGS.iter().all(|m| m.1 != key),
-            "{key} is a vanilla binding"
-        );
-    }
-
-    #[test]
-    fn zoom_is_vanilla_unless_held_and_not_scoping() {
-        let mut z = Zoom::default();
-        assert_eq!(z.factor(false), 1.0);
-        assert_eq!(fov_target(1.1, z.factor(false)), 1.1);
-        assert!(!z.scroll(1.0), "the wheel is the hotbar's when not zooming");
-        z.press(4);
-        assert_eq!(z.factor(false), 4.0);
-        assert_eq!(z.factor(true), 1.0, "the spyglass wins");
-        assert!((fov_target(1.0, 4.0) - 0.25).abs() < 1e-6);
-        assert!(z.scroll(1.0));
-        assert!((z.factor(false) - 5.0).abs() < 1e-5);
-        for _ in 0..40 {
-            z.scroll(1.0);
-        }
-        assert_eq!(z.factor(false), ZOOM_MAX);
-        for _ in 0..80 {
-            z.scroll(-1.0);
-        }
-        assert_eq!(z.factor(false), ZOOM_MIN);
-        z.release();
-        assert_eq!(z.factor(false), 1.0);
-        z.press(2);
-        assert_eq!(z.factor(false), 2.0, "each press starts at the default");
-    }
-
-    #[test]
-    fn zoom_target_eases_like_the_spyglass() {
+    fn a_mods_zoom_eases_like_the_spyglass() {
         // Camera.tickFov halves the distance to the target each tick.
         let mut camera = crate::camera::Camera::default();
         camera.tick(None, 1.0);
@@ -812,55 +659,6 @@ mod tests {
         assert!((floor - 7.0).abs() < 1e-3, "{floor}");
     }
 
-    #[test]
-    fn the_zoom_key_only_zooms_while_playing() {
-        let mut z = Zoom::default();
-        // In chat, a sign, a text field or any screen: no zoom.
-        z.key(true, false, false, 4);
-        assert!(!z.held());
-        z.key(true, false, true, 4);
-        assert!(z.held());
-        // A screen opening while held lets go (its key presses are the screen's).
-        z.key(true, true, false, 4);
-        assert!(!z.held());
-        // Key repeats do not restart a zoom the wheel changed.
-        z.key(true, false, true, 4);
-        z.scroll(1.0);
-        z.key(true, true, true, 4);
-        assert!((z.factor(false) - 5.0).abs() < 1e-5);
-        z.key(false, false, true, 4);
-        assert!(!z.held());
-    }
-
-    #[test]
-    fn zoom_key_conflicts_name_the_vanilla_mappings() {
-        let mut e = Extras::default();
-        let mut keys = crate::keybinds::KeyBinds::default();
-        assert!(zoom_key_conflicts(&e, &keys).is_empty());
-        e.zoom_key = "key.keyboard.c".into();
-        assert_eq!(
-            zoom_key_conflicts(&e, &keys),
-            [
-                "key.saveToolbarActivator",
-                "key.debug.crash",
-                "key.debug.copyLocation"
-            ]
-        );
-        keys.set("key.drop", "key.keyboard.z");
-        e.zoom_key = "key.keyboard.z".into();
-        assert_eq!(zoom_key_conflicts(&e, &keys), ["key.drop"]);
-        e.zoom_key = "key.keyboard.unknown".into();
-        keys.set("key.smoothCamera", "key.keyboard.unknown");
-        assert!(zoom_key_conflicts(&e, &keys).is_empty());
-    }
-
-    #[test]
-    fn sensitivity_scales_with_zoom() {
-        assert_eq!(turn_scale(1.0, true), 1.0);
-        assert_eq!(turn_scale(4.0, false), 1.0);
-        assert_eq!(turn_scale(4.0, true), 0.25);
-    }
-
     #[test]
     fn fps_counter_reports_rate_minimum_and_low() {
         let mut c = FpsCounter::default();
@@ -914,16 +712,8 @@ mod tests {
     #[test]
     fn items_cycle_through_their_values() {
         let mut e = Extras::default();
-        Item::ZoomLevel.cycle(&mut e, false);
-        assert_eq!(e.zoom_level, 6);
-        Item::ZoomLevel.cycle(&mut e, true);
-        Item::ZoomLevel.cycle(&mut e, true);
-        assert_eq!(e.zoom_level, 3);
         Item::MinimapCorner.cycle(&mut e, true);
         assert_eq!(e.minimap_corner, Corner::TopLeft);
-        Item::Zoom.cycle(&mut e, false);
-        assert_eq!(Item::Zoom.switch(&e), Some(true));
-        assert_eq!(Item::ZoomKey.value(&e), "Z");
         Item::MinimapZoom.cycle(&mut e, true);
         assert_eq!(Item::MinimapZoom.value(&e), "½ block per pixel");
         Item::MinimapSize.cycle(&mut e, false);
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 95984be00..d27d4e471 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -1494,7 +1494,7 @@ struct Game<'a> {
     pending_bench: Option<(Instant, std::sync::mpsc::Sender<String>)>,
     /// Recent frame times for the performance overlay.
     frame_graph: horizon_client::perf_overlay::FrameGraph,
-    /// Horizon's extras (zoom, FPS counter, keystrokes): `game/extras.rs`.
+    /// Horizon's extras (minimap, auto-reconnect; mods' counters): `game/extras.rs`.
     extras: extras::ExtrasState,
     /// Horizon mods (`game/mods.rs`), none running unless turned on.
     mods: mods::ModsState,
@@ -11114,7 +11114,6 @@ impl ApplicationHandler for Game<'_> {
                         && self.sleeping.is_none()
                         && self.player.is_some()
                         && !self.mod_wheel(d)
-                        && !self.extras_scroll(d)
                         && let Some((wheel, (_, vertical_steps))) =
                             self.mouse
                                 .on_scroll(raw_x, raw_y, discrete, wheel_sensitivity)
@@ -11508,7 +11507,6 @@ impl ApplicationHandler for Game<'_> {
                     let PhysicalKey::Code(key) = event.physical_key else {
                         return Ok(());
                     };
-                    self.extras_key(key, event.state == ElementState::Pressed, event.repeat);
                     self.mod_key(key, event.state == ElementState::Pressed, event.repeat);
                     // key.smoothCamera toggles the cinematic camera.
                     if self.screen == Screen::Playing
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index d0a139850..6acb55598 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -288,13 +288,9 @@ impl Game<'_> {
                         self.debug_key(key, KeyAction::Release);
                     }
                 }
-                // The zoom extra sees the key as the keyboard hook does.
+                // Mods' keys (capability `input`) see the key as the keyboard
+                // hook does.
                 let action = arg(2)?;
-                self.extras_key(physical, action != "up", action == "repeat");
-                if action == "tap" {
-                    self.extras_key(physical, false, false);
-                }
-                // So do mods' keys (capability `input`).
                 self.mod_key(physical, action != "up", action == "repeat");
                 if action == "tap" {
                     self.mod_key(physical, false, false);
@@ -372,15 +368,19 @@ impl Game<'_> {
                 match arg(2)? {
                     "down" => {
                         self.extras_mouse(button, true);
+                        self.mod_mouse_key(button, true);
                         self.play_mouse(button, true)?
                     }
                     "up" => {
                         self.extras_mouse(button, false);
+                        self.mod_mouse_key(button, false);
                         self.play_mouse(button, false)?
                     }
                     "click" => {
                         self.extras_mouse(button, true);
+                        self.mod_mouse_key(button, true);
                         self.extras_mouse(button, false);
+                        self.mod_mouse_key(button, false);
                         self.play_mouse(button, true)?;
                         self.play_mouse(button, false)?;
                     }
diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index 30073f186..88d962952 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -1,24 +1,22 @@
-//! Horizon's extras in the game (`docs/extras.md`): the zoom key and wheel,
-//! the minimap's tiles and image, and their HUD; clicks and frame times for
-//! mods (`input.clicks-per-second`, `render.frame-stats`). Each hook does
-//! nothing while its extra is off and no mod runs.
+//! Horizon's extras in the game (`docs/extras.md`): the minimap's tiles and
+//! image, and its HUD; a mod's zoom (`render.set-zoom`) on the camera; clicks
+//! and frame times for mods (`input.clicks-per-second`, `render.frame-stats`).
+//! Each hook does nothing while its extra is off and no mod runs.
 use super::{Dim, Game, Screen};
 use horizon_client::{
-    extras::{Corner, Cps, FpsCounter, Zoom, fov_target, turn_scale},
+    extras::{Corner, Cps, FpsCounter, fov_target},
     extras_hud::{self, Corners},
     hud::{HudBatch, MINIMAP_SPRITE},
-    keybinds,
     minimap::{self, Layer, Minimap, View},
     multiplayer,
     reconnect::{Retry, Tracker},
     title::Mode,
 };
 use std::time::Duration;
-use winit::{event::MouseButton, keyboard::KeyCode};
+use winit::event::MouseButton;
 
 #[derive(Default)]
 pub(super) struct ExtrasState {
-    zoom: Zoom,
     fps: FpsCounter,
     /// Left and right mouse buttons: held, and their clicks.
     mouse: [bool; 2],
@@ -36,34 +34,8 @@ impl Game<'_> {
     fn extras_now(&self) -> f64 {
         self.started.elapsed().as_secs_f64()
     }
-    fn zoom_key(&self) -> Option<KeyCode> {
-        let e = &self.settings.extras;
-        e.zoom.then(|| keybinds::key_code(&e.zoom_key)).flatten()
-    }
-    /// A key press or release. The zoom key zooms only while playing with
-    /// no text open; the key itself always goes on to the screen and the key
-    /// binds, as a vanilla key mapping's would.
-    pub(super) fn extras_key(&mut self, key: KeyCode, pressed: bool, repeat: bool) {
-        if self.zoom_key() != Some(key) {
-            return;
-        }
-        let playing = self.screen == Screen::Playing
-            && self.title.is_none()
-            && self.sign_edit.is_none()
-            && self.book.is_none();
-        let level = self.settings.extras.zoom_level;
-        self.extras.zoom.key(pressed, repeat, playing, level);
-    }
-    /// Wheel steps while playing; true when zooming took them from the hotbar.
-    pub(super) fn extras_scroll(&mut self, steps: f32) -> bool {
-        self.settings.extras.zoom && self.extras.zoom.scroll(steps)
-    }
-    /// Mouse buttons while playing, for zoom and the keystroke overlay.
+    /// Mouse buttons while playing, for mods' clicks.
     pub(super) fn extras_mouse(&mut self, button: MouseButton, pressed: bool) {
-        let e = &self.settings.extras;
-        if e.zoom && e.zoom_key == keybinds::mouse_name(button) {
-            self.extras.zoom.key(pressed, false, true, e.zoom_level);
-        }
         let i = match button {
             MouseButton::Left => 0,
             MouseButton::Right => 1,
@@ -81,9 +53,6 @@ impl Game<'_> {
         // Under agent control the window may lack focus without pausing.
         let focused = self.focused || self.control.is_some();
         let playing = self.screen == Screen::Playing && self.title.is_none() && focused;
-        if !playing || !self.settings.extras.zoom {
-            self.extras.zoom.release();
-        }
         if !playing {
             self.extras.mouse = [false; 2];
         }
@@ -225,24 +194,12 @@ impl Game<'_> {
             rgba: self.extras.minimap.image.clone(),
         });
     }
-    /// The zoom in effect (1 unless the key is held).
-    fn zoom_factor(&self) -> f32 {
-        self.extras.zoom.factor(self.scoping())
-    }
-    /// The zoom in effect, the extra's or a mod's (`render.set-zoom`),
-    /// whichever is stronger: (factor, smooth, turning scale).
+    /// A mod's zoom in effect (`render.set-zoom`): (factor, smooth, turning
+    /// scale); none is 1.
     fn zoom_now(&self) -> (f32, bool, f64) {
-        let factor = self.zoom_factor();
-        let e = &self.settings.extras;
-        let own = (
-            factor,
-            e.zoom_smooth,
-            turn_scale(factor, e.zoom_sensitivity),
-        );
-        match self.mod_zoom() {
-            Some(z) if z.factor > factor => (z.factor, z.smooth, f64::from(z.turn)),
-            _ => own,
-        }
+        self.mod_zoom().map_or((1.0, true, 1.0), |z| {
+            (z.factor, z.smooth, f64::from(z.turn))
+        })
     }
     /// The field-of-view modifier target, divided by a smooth zoom.
     pub(super) fn zoomed_fov_target(&self, vanilla: f32) -> f32 {
diff --git a/crates/horizon-client/src/game/moved_extras.rs b/crates/horizon-client/src/game/moved_extras.rs
index faeeea541..bd277033e 100644
--- a/crates/horizon-client/src/game/moved_extras.rs
+++ b/crates/horizon-client/src/game/moved_extras.rs
@@ -82,6 +82,13 @@ mod with_mods {
                         Ok(()) => {
                             self.settings.extras.moved.push(m.id.to_owned());
                             self.settings.mods.enabled.insert(m.id.to_owned());
+                            // The install wrote the key to horizon-mods.txt;
+                            // the settings save below must keep it.
+                            let keys = self.settings.mods.keys.entry(m.id.to_owned()).or_default();
+                            for (name, key) in m.keys(&self.settings.extras) {
+                                keys.entry(name.to_owned()).or_insert(key);
+                            }
+                            self.settings.mods.keys.retain(|_, k| !k.is_empty());
                             self.mods.moved.notices.push(Text::literal(m.notice()));
                             installed = true;
                         }
diff --git a/crates/horizon-client/src/moved_extras.rs b/crates/horizon-client/src/moved_extras.rs
index 659592d80..3b5db6fbc 100644
--- a/crates/horizon-client/src/moved_extras.rs
+++ b/crates/horizon-client/src/moved_extras.rs
@@ -25,7 +25,7 @@ pub struct Moved {
     pub name: &'static str,
 }
 
-pub const MOVED: [Moved; 2] = [
+pub const MOVED: [Moved; 3] = [
     Moved {
         id: "fps_overlay",
         name: "FPS counter",
@@ -34,13 +34,18 @@ pub const MOVED: [Moved; 2] = [
         id: "keystrokes",
         name: "Keystrokes",
     },
+    Moved {
+        id: "zoom",
+        name: "Zoom",
+    },
 ];
 
 impl Moved {
     fn was_on(&self, e: &Extras) -> bool {
         match self.id {
             "fps_overlay" => e.fps,
-            _ => e.keystrokes,
+            "keystrokes" => e.keystrokes,
+            _ => e.zoom,
         }
     }
     /// The extra's settings as the mod keeps them (its storage keys).
@@ -51,10 +56,23 @@ impl Moved {
                 ("corner", e.fps_corner.name().into()),
                 ("lows", flag(e.fps_lows)),
             ],
-            _ => vec![
+            "keystrokes" => vec![
                 ("corner", e.keystrokes_corner.name().into()),
                 ("cps", flag(e.keystrokes_cps)),
             ],
+            _ => vec![
+                ("level", e.zoom_level.to_string()),
+                ("smooth", flag(e.zoom_smooth)),
+                ("sensitivity", flag(e.zoom_sensitivity)),
+            ],
+        }
+    }
+    /// The extra's key as the mod's key (`horizon-mods.txt`), when the
+    /// player had changed it from the mod's default.
+    pub fn keys(&self, e: &Extras) -> Vec<(&'static str, String)> {
+        match self.id {
+            "zoom" if e.zoom_key != "key.keyboard.z" => vec![("zoom", e.zoom_key.clone())],
+            _ => Vec::new(),
         }
     }
     /// The line the player reads once it is installed.
@@ -171,6 +189,12 @@ pub fn install(index: &Index, m: &Moved, e: &Extras, dir: &Path) -> Result<(), S
     }
     let mut list = ModList::load(dir);
     list.enabled.insert(m.id.to_owned());
+    // A key the player already chose for the mod stays.
+    let keys = list.keys.entry(m.id.to_owned()).or_default();
+    for (name, key) in m.keys(e) {
+        keys.entry(name.to_owned()).or_insert(key);
+    }
+    list.keys.retain(|_, k| !k.is_empty());
     list.save(dir);
     Ok(())
 }
@@ -184,7 +208,7 @@ mod tests {
     fn only_extras_that_were_on_are_installed_and_each_once() {
         let mut e = Extras::default();
         assert!(pending(&e).is_empty());
-        assert_eq!(nothing_to_do(&e).len(), 2);
+        assert_eq!(nothing_to_do(&e).len(), 3);
         e.fps = true;
         e.fps_corner = Corner::BottomRight;
         e.fps_lows = true;
@@ -199,7 +223,23 @@ mod tests {
         );
         e.moved.push("fps_overlay".into());
         assert!(pending(&e).is_empty());
-        assert_eq!(nothing_to_do(&e), [&MOVED[1]]);
+        assert_eq!(nothing_to_do(&e), [&MOVED[1], &MOVED[2]]);
+        // Zoom: its settings, and its key only when the player changed it.
+        e.zoom = true;
+        e.zoom_level = 8;
+        e.zoom_smooth = false;
+        assert_eq!(pending(&e), [&MOVED[2]]);
+        assert_eq!(
+            MOVED[2].settings(&e),
+            [
+                ("level", "8".into()),
+                ("smooth", "false".into()),
+                ("sensitivity", "true".into())
+            ]
+        );
+        assert!(MOVED[2].keys(&e).is_empty());
+        e.zoom_key = "key.mouse.4".into();
+        assert_eq!(MOVED[2].keys(&e), [("zoom", "key.mouse.4".into())]);
         assert_eq!(
             MOVED[0].notice(),
             "FPS counter moved to the mod browser: installed for you"
diff --git a/crates/horizon-client/src/options_ui.rs b/crates/horizon-client/src/options_ui.rs
index 9f91254bd..21436d6cc 100644
--- a/crates/horizon-client/src/options_ui.rs
+++ b/crates/horizon-client/src/options_ui.rs
@@ -3296,26 +3296,29 @@ mod tests {
             crate::extras::rows().iter().filter(|r| r.is_ok()).count()
         );
         assert_eq!(
-            click(&mut ui, &mut s, Act::Extra(crate::extras::Item::Zoom)),
+            click(&mut ui, &mut s, Act::Extra(crate::extras::Item::Sort)),
             vec![Event::ButtonClick, Event::Changed]
         );
-        assert!(s.extras.zoom);
+        assert!(s.extras.sort);
         assert_eq!(
-            click(&mut ui, &mut s, Act::Extra(crate::extras::Item::ZoomKey)),
+            click(&mut ui, &mut s, Act::Extra(crate::extras::Item::SortKey)),
             vec![Event::ButtonClick]
         );
-        assert_eq!(ui.selected_key, Some(crate::extras::ZOOM_KEY));
+        assert_eq!(ui.selected_key, Some(crate::extras::SORT_KEY));
         assert_eq!(
             ui.key(&mut s, &atlas, winit::keyboard::KeyCode::KeyC, None),
             vec![Event::Changed]
         );
-        assert_eq!(s.extras.zoom_key, "key.keyboard.c");
+        assert_eq!(s.extras.sort_key, "key.keyboard.c");
         assert_eq!(
             crate::extras::Extras::parse(&s.extras.serialize()),
             s.extras
         );
-        ui.scroll(&s, size, -1000.0);
-        let (_, top, bottom, content) = ui.layout(&s, size.0, size.1);
+        // In a window too short for the page, the wheel scrolls to its end.
+        let short = (480.0, 300.0);
+        ui.scroll(&s, short, -1000.0);
+        let (_, top, bottom, content) = ui.layout(&s, short.0, short.1);
+        assert!(content > bottom - top);
         assert_eq!(ui.scroll, content - (bottom - top));
         assert_eq!(
             ui.key(&mut s, &atlas, winit::keyboard::KeyCode::Escape, None),
@@ -3867,7 +3870,7 @@ mod tests {
 
     #[test]
     fn extras_and_vanilla_bindings_accept_mouse_buttons() {
-        use crate::extras::{Extras, SORT_KEY, ZOOM_KEY};
+        use crate::extras::{Extras, SORT_KEY};
         use winit::event::MouseButton;
         for button in [
             MouseButton::Left,
@@ -3876,7 +3879,7 @@ mod tests {
             MouseButton::Back,
             MouseButton::Forward,
         ] {
-            for name in [SORT_KEY, ZOOM_KEY, "key.jump"] {
+            for name in [SORT_KEY, "key.jump"] {
                 let mut ui = OptionsUi::default();
                 let mut s = Settings::default();
                 ui.selected_key = Some(name);
@@ -3885,7 +3888,6 @@ mod tests {
                 let value = keybinds::mouse_name(button);
                 match name {
                     SORT_KEY => assert_eq!(s.extras.sort_key, value),
-                    ZOOM_KEY => assert_eq!(s.extras.zoom_key, value),
                     _ => assert_eq!(s.keys.get(name), value),
                 }
                 assert_eq!(Extras::parse(&s.extras.serialize()), s.extras);
diff --git a/docs/extras.md b/docs/extras.md
index 598b29739..aa87c1adf 100644
--- a/docs/extras.md
+++ b/docs/extras.md
@@ -1,6 +1,6 @@
 # Horizon extras
 
-Optional conveniences built into the client: fullbright, dynamic lights, zoom, a minimap, auto-reconnect,
+Optional conveniences built into the client: fullbright, dynamic lights, a minimap, auto-reconnect,
 Mouse Tweaks-style inventory controls and inventory sorting. **Every one is off by default**: a fresh
 install looks and behaves exactly like vanilla 26.3, and turning an extra off
 again restores vanilla's behaviour completely.
@@ -10,7 +10,7 @@ again restores vanilla's behaviour completely.
 | Part | Code |
 |---|---|
 | Settings, parsing and saving | `crates/horizon-client/src/extras.rs` |
-| Zoom curve; FPS and click counters (for mods) | `extras.rs` (pure logic, unit tested) |
+| FPS and click counters (for mods) | `extras.rs` (pure logic, unit tested) |
 | Dynamic lights: item glow, nearest sources | `crates/horizon-client/src/dynamic_light.rs` (unit tested), `game/dynamic_lights.rs`, `terrain.wgsl` and `entity.wgsl` (`dynamic_block_light`) |
 | HUD drawing (minimap frame, corner stacking) | `crates/horizon-client/src/extras_hud.rs` |
 | Minimap colours, tiles and image | `crates/horizon-client/src/minimap.rs` |
@@ -34,10 +34,9 @@ extras stay out of the way of other input and options work.
 `horizon-graphics.txt`. `options.txt` is untouched, so a vanilla client can share
 the folder. Unknown or broken lines fall back to the defaults.
 
-The zoom key is a Horizon setting stored in that file (`zoomKey:key.keyboard.z`)
-and bound on the Extras page, not in vanilla's Key Binds screen: Horizon has no
-Horizon category in Controls, and adding one would put a non-vanilla mapping into
-`options.txt`.
+Extras' keys (the sort key) are Horizon settings stored in that file and bound on
+the Extras page, not in vanilla's Key Binds screen: Horizon has no Horizon category
+in Controls, and adding one would put a non-vanilla mapping into `options.txt`.
 
 ## The extras
 
@@ -61,33 +60,13 @@ Horizon category in Controls, and adding one would put a non-vanilla mapping int
 - Off: nothing is gathered and the shaders' loop runs zero times (the count is 0), so it costs
   nothing measurable (numbers in the pull request, #814).
 
-### Zoom (`zoom`, default off)
-- Hold the zoom key (default **Z**, unused by every vanilla 26.3 key mapping; C
-  is `key.saveToolbarActivator`) to zoom. The key does nothing while zoom is off.
-- It zooms only while playing: in chat, signs, books, text fields and every
-  other screen the key is typed or handled as usual. The key is never taken
-  from vanilla's mappings: one bound to the same key still acts (a key bound
-  twice triggers both, as vanilla's do), and the Extras page marks the zoom key
-  "Also bound" and names the mapping.
-- Starts at the default level (4x, settable 2x to 10x); the scroll wheel changes
-  it while the key is held (and does not move the hotbar then).
-- **Smooth** (default on) goes through vanilla's own FOV easing: the zoom divides
-  the field-of-view modifier target `Camera.tickFov` eases toward, the path the
-  spyglass uses (`AbstractClientPlayer.getFieldOfViewModifier` returns 0.1 while
-  scoping). The modifier keeps vanilla's 0.1 floor, so 10x is the deepest zoom.
-  Off applies the zoom to the final FOV with no easing.
-- While scoping with a spyglass the zoom does nothing: the spyglass view and its
-  overlay stay exactly vanilla's.
-- **Slower turning** (default on) divides mouse turning by the zoom factor.
-- With zoom off (or the key up) the FOV target and mouse are vanilla's, bit for
-  bit; the FOV harness covers this.
-
 ### Moved to the mod browser
 
-The **FPS counter** and **Keystrokes** are official mods now (`mods/official/`, [mods.md](mods.md#horizons-official-mods)),
+The **FPS counter**, **Keystrokes** and **Zoom** are official mods now (`mods/official/`, [mods.md](mods.md#horizons-official-mods)),
 with the same look and options. On the first start after the update, a player who had one on gets the mod installed
-from Horizon's registry and turned on, with their corner and options carried over, and reads one line in the chat
-("FPS counter moved to the mod browser: installed for you"). The install is checked like the launcher's (size,
+from Horizon's registry and turned on, with their corner and options carried over (Zoom's key too, into
+`horizon-mods.txt`, when it wasn't Z), and reads one line in the chat ("Zoom moved to the mod browser: installed for
+you"). The install is checked like the launcher's (size,
 SHA-256, signature, manifest); if it fails (offline), the next start tries again. `horizon-extras.txt` keeps the old
 keys and lists what was done in `movedToMods`. Code: `crates/horizon-client/src/moved_extras.rs`,
 `game/moved_extras.rs`.
diff --git a/website/docs/index.md b/website/docs/index.md
index 24f969840..f22994f9c 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -7,7 +7,7 @@ Horizon is Minecraft: Java Edition 26.3 rewritten in Rust. You install it with a
 - **A new game program, not a mod.** Horizon is written from scratch in Rust. It reads the same worlds, plays by the same rules and generates the same terrain as the Java game.
 - **Checked against vanilla.** {{HARNESSES}} automated tests ("harnesses") feed the same inputs to Horizon and to the real game, then compare the results. Today every subsystem matches in every harness that compares it. That is {{PERCENT}} of what the harnesses compare, which is not proof that nothing else differs. The [status table](/#parity) lists what is covered.
 - **Light and fast.** It starts quickly, uses little memory and draws efficiently. See [Performance](/docs/performance) for what is measured and what is not.
-- **A few things vanilla doesn't have.** Its own settings, added to vanilla's menus the way mods add theirs, graphics presets, distant terrain, controller support, optional extras such as zoom, a minimap and dynamic lights, an invite code to play your world with friends, and a server you can run without Java.
+- **A few things vanilla doesn't have.** Its own settings, added to vanilla's menus the way mods add theirs, graphics presets, distant terrain, controller support, optional extras such as a minimap and dynamic lights, official mods such as zoom, an invite code to play your world with friends, and a server you can run without Java.
 
 ## What Horizon is not
 
diff --git a/website/docs/settings.md b/website/docs/settings.md
index 29eb0a760..e9b228b4c 100644
--- a/website/docs/settings.md
+++ b/website/docs/settings.md
@@ -63,7 +63,7 @@ Horizon plays with PlayStation (DualShock 4 and DualSense), Xbox (360, One and S
 
 ## Extras
 
-**Options, Horizon Settings, Extras** holds small, optional conveniences. Every one is off by default, so a fresh install behaves like vanilla: fullbright, zoom, a minimap, an FPS counter, a keystroke display, auto-reconnect, Mouse Tweaks-style inventory controls and inventory sorting. One more is **dynamic lights**: a torch, lantern or other light source that you hold, that lies dropped as an item, or a burning mob, lights the blocks around it. It is client-side only, so other players do not see it.
+**Options, Horizon Settings, Extras** holds small, optional conveniences. Every one is off by default, so a fresh install behaves like vanilla: fullbright, a minimap, auto-reconnect, Mouse Tweaks-style inventory controls and inventory sorting. The FPS counter, the keystroke display and zoom are official mods now, in **Options, Mods**: if you had one on, the game installed it for you on its first start after the update, with your settings. One more is **dynamic lights**: a torch, lantern or other light source that you hold, that lies dropped as an item, or a burning mob, lights the blocks around it. It is client-side only, so other players do not see it.
 
 ## Where your settings are stored
 

From c3763ff1b3c138c2f944aae844bfdbdc74e60aa2 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 05:59:02 +0100
Subject: [PATCH 263/270] F3 shows the shader pack's GPU time per pass, for
 either kind of pack

While the F3 overlay is open, the running pack's passes are timed on the GPU,
a shaders/ pack's or a native pack's, and the overlay lists the pack's total
and its costliest passes (the median of the last 15 timed frames). The timer
never waits: a timed frame's stamps are resolved once the GPU has finished it
and read back once mapped, then the next frame is timed. A native pack's first
pass counts from a mark that ends with the world's draws, so it does not carry
the time it waited for them. HORIZON_SHADER_PACK_TIMING still logs the medians.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/debug_overlay.rs   |  38 +++
 crates/horizon-client/src/game.rs            |   5 +-
 crates/horizon-client/src/game/debug_keys.rs |   7 +
 crates/horizon-client/src/gfx.rs             |  42 +++
 crates/horizon-client/src/gfx/native_post.rs |  11 +
 crates/horizon-client/src/gfx/pack_post.rs   |   6 +-
 crates/horizon-client/src/gfx/pack_timing.rs | 290 ++++++++++++++-----
 crates/horizon-client/src/gfx/timing.rs      |   4 +-
 docs/shaders.md                              |  10 +-
 9 files changed, 334 insertions(+), 79 deletions(-)

diff --git a/crates/horizon-client/src/debug_overlay.rs b/crates/horizon-client/src/debug_overlay.rs
index 3448ea411..7140905a8 100644
--- a/crates/horizon-client/src/debug_overlay.rs
+++ b/crates/horizon-client/src/debug_overlay.rs
@@ -84,6 +84,33 @@ impl Displayer {
     }
 }
 
+/// Horizon's own lines: the shader pack's GPU time, then its costliest passes (`passes`: each
+/// pass's median milliseconds, in the order they run).
+pub fn shader_pass_lines(passes: &[(String, f32)]) -> Vec<String> {
+    const SHOWN: usize = 8;
+    if passes.is_empty() {
+        return Vec::new();
+    }
+    let total: f32 = passes.iter().map(|p| p.1).sum();
+    let mut lines = vec![format!(
+        "Shader pack GPU: {total:.2} ms in {} passes",
+        passes.len()
+    )];
+    let mut costliest: Vec<&(String, f32)> = passes.iter().collect();
+    costliest.sort_by(|a, b| b.1.total_cmp(&a.1));
+    lines.extend(
+        costliest
+            .iter()
+            .take(SHOWN)
+            .map(|(name, ms)| format!("{name}: {ms:.2} ms")),
+    );
+    if costliest.len() > SHOWN {
+        let rest: f32 = costliest[SHOWN..].iter().map(|p| p.1).sum();
+        lines.push(format!("{} more: {rest:.2} ms", costliest.len() - SHOWN));
+    }
+    lines
+}
+
 /// `Mth.wrapDegrees`.
 fn wrap_degrees(angle: f32) -> f32 {
     let wrapped = angle % 360.0;
@@ -337,4 +364,15 @@ mod tests {
             (1.0, [640, 360])
         );
     }
+
+    #[test]
+    fn shader_pass_lines_list_the_costliest_passes_first() {
+        assert!(shader_pass_lines(&[]).is_empty());
+        let passes: Vec<(String, f32)> = (0..10).map(|i| (format!("p{i}"), i as f32)).collect();
+        let lines = shader_pass_lines(&passes);
+        assert_eq!(lines[0], "Shader pack GPU: 45.00 ms in 10 passes");
+        assert_eq!(lines[1], "p9: 9.00 ms");
+        assert_eq!(lines[8], "p2: 2.00 ms");
+        assert_eq!(lines[9], "2 more: 1.00 ms");
+    }
 }
diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs
index 4638a4667..cc4314937 100644
--- a/crates/horizon-client/src/game.rs
+++ b/crates/horizon-client/src/game.rs
@@ -10495,7 +10495,10 @@ impl Game<'_> {
             menu_blur: self.menu_blur(),
         };
         let result = match self.renderer.as_mut() {
-            Some(renderer) => horizon_client::spans::time("renderer", || renderer.render(&frame)),
+            Some(renderer) => {
+                renderer.set_pass_timing(self.debug);
+                horizon_client::spans::time("renderer", || renderer.render(&frame))
+            }
             None => Err("renderer".into()),
         };
         // Restore storage even when rendering fails (for example, a lost surface).
diff --git a/crates/horizon-client/src/game/debug_keys.rs b/crates/horizon-client/src/game/debug_keys.rs
index 61e2b2f05..16e7fc6e7 100644
--- a/crates/horizon-client/src/game/debug_keys.rs
+++ b/crates/horizon-client/src/game/debug_keys.rs
@@ -415,6 +415,13 @@ impl Game<'_> {
                 ],
             );
         }
+        // Horizon's own: the shader pack's GPU time per pass (an empty group would move others).
+        let pass_lines = self.renderer.as_ref().map_or_else(Vec::new, |r| {
+            debug_overlay::shader_pass_lines(&r.shader_pass_times())
+        });
+        if !pass_lines.is_empty() {
+            d.group("shader pack", pass_lines);
+        }
         // tps: DebugEntryTps for local and remote connections.
         if self.player.is_some() {
             let [tx, rx] = self.debug_charts.packet_rates.map(|n| n.round() as i64);
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 5db82b19a..24e386bc7 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -502,6 +502,8 @@ pub struct Renderer {
     pack_post: Option<(i32, Option<pack_post::PackPost>)>,
     /// The post passes of one of Horizon's own shader packs; never beside `pack_post`'s.
     native_post: Option<native_post::NativePost>,
+    /// Time the shader pack's passes on the GPU (F3, or `HORIZON_SHADER_PACK_TIMING`).
+    pass_timing: bool,
     /// The entity vertices Horizon draws itself while a shader pack draws the others.
     pack_entity_rest: Vec<Vertex>,
     /// Set 1 of the cloud pipeline, for a shader pack's `gbuffers_clouds`.
@@ -2413,6 +2415,7 @@ impl Renderer {
             world_post,
             pack_post: None,
             native_post: None,
+            pass_timing: pack_timing::PassTiming::logging(),
             pack_entity_rest: Vec::new(),
             cloud_bindings,
             pack_weather: None,
@@ -2992,6 +2995,34 @@ impl Renderer {
                 .terrain_inputs(self.pack_terrain_flat),
         )
     }
+    /// Times the shader pack's passes on the GPU while `on` (the F3 overlay is open), or always
+    /// with `HORIZON_SHADER_PACK_TIMING`.
+    pub fn set_pass_timing(&mut self, on: bool) {
+        self.pass_timing = on || pack_timing::PassTiming::logging();
+    }
+    /// The running shader pack's timer, of either kind.
+    fn pass_timer<'a>(
+        pack: &'a mut Option<(i32, Option<pack_post::PackPost>)>,
+        native: &'a mut Option<native_post::NativePost>,
+    ) -> Option<&'a mut Option<pack_timing::PassTiming>> {
+        match (pack, native) {
+            (Some((_, Some(post))), _) => Some(&mut post.timing),
+            (_, Some(post)) => Some(&mut post.timing),
+            _ => None,
+        }
+    }
+    /// Each pass of the running shader pack with its median GPU time in milliseconds, while
+    /// they are timed (`set_pass_timing`).
+    pub fn shader_pass_times(&self) -> Vec<(String, f32)> {
+        let timer = match (&self.pack_post, &self.native_post) {
+            (Some((_, Some(post))), _) => post.timing.as_ref(),
+            (_, Some(post)) => post.timing.as_ref(),
+            _ => None,
+        };
+        timer
+            .map(pack_timing::PassTiming::medians)
+            .unwrap_or_default()
+    }
     /// The dimension the shader pack was last set for.
     pub fn shader_pack_dimension(&self) -> Option<i32> {
         self.pack_post.as_ref().map(|p| p.0)
@@ -4016,6 +4047,14 @@ impl Renderer {
         let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
         // One of Horizon's own packs reads the same world target.
         let native_post = !frame.title && self.native_post.is_some();
+        if let Some(timer) = Self::pass_timer(&mut self.pack_post, &mut self.native_post)
+            && timer.is_some() != self.pass_timing
+        {
+            *timer = self
+                .pass_timing
+                .then(|| pack_timing::PassTiming::new(&self.device, &self.queue))
+                .flatten();
+        }
         let pack_reads_world = pack_post || native_post;
         // The pack's program reads the vertices this frame's draws bind.
         let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
@@ -4649,6 +4688,9 @@ impl Renderer {
             timer.submitted(&self.queue);
             timer.collect(&self.device, &mut self.gpu_times);
         }
+        if let Some(Some(timer)) = Self::pass_timer(&mut self.pack_post, &mut self.native_post) {
+            timer.submitted(&self.queue);
+        }
         if let Some((path, buffer)) = readback {
             self.screenshot_result = Some(
                 self.write_screenshot(&path, &buffer)
diff --git a/crates/horizon-client/src/gfx/native_post.rs b/crates/horizon-client/src/gfx/native_post.rs
index c4af862d7..cf99b1936 100644
--- a/crates/horizon-client/src/gfx/native_post.rs
+++ b/crates/horizon-client/src/gfx/native_post.rs
@@ -27,6 +27,10 @@ pub struct NativePost {
     groups: Option<(WorldViews, Vec<wgpu::BindGroup>)>,
     start: std::time::Instant,
     frames: u32,
+    /// The screen's colour format, the world target's too.
+    format: wgpu::TextureFormat,
+    /// GPU time of each pass, while the renderer asks for it (`pack_timing.rs`).
+    pub timing: Option<super::pack_timing::PassTiming>,
 }
 
 fn texture_entry(binding: u32, sample_type: wgpu::TextureSampleType) -> wgpu::BindGroupLayoutEntry {
@@ -165,6 +169,8 @@ impl NativePost {
             groups: None,
             start: std::time::Instant::now(),
             frames: 0,
+            format,
+            timing: None,
         })
     }
 
@@ -287,6 +293,10 @@ impl NativePost {
     ) {
         self.prepare(device, world, size);
         queue.write_buffer(&self.frame, 0, bytemuck::bytes_of(inputs));
+        if let Some(t) = &mut self.timing {
+            t.begin(device, queue);
+            t.mark(device, encoder, (world.0, self.format));
+        }
         let Some((_, groups)) = &self.groups else {
             return;
         };
@@ -307,6 +317,7 @@ impl NativePost {
             let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some(label),
                 color_attachments: &attachments,
+                timestamp_writes: self.timing.as_mut().and_then(|t| t.writes(label)),
                 ..Default::default()
             });
             pass.set_pipeline(pipeline);
diff --git a/crates/horizon-client/src/gfx/pack_post.rs b/crates/horizon-client/src/gfx/pack_post.rs
index 19f0d7349..b9320277a 100644
--- a/crates/horizon-client/src/gfx/pack_post.rs
+++ b/crates/horizon-client/src/gfx/pack_post.rs
@@ -297,8 +297,8 @@ pub struct PackPost {
     /// with the page buffer it was made for.
     block_ids: Option<(wgpu::BindGroupLayout, wgpu::Buffer)>,
     page_groups: HashMap<u32, (wgpu::Buffer, wgpu::BindGroup)>,
-    /// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
-    timing: Option<super::pack_timing::PassTiming>,
+    /// GPU time of each pass, while the renderer asks for it (`pack_timing.rs`).
+    pub timing: Option<super::pack_timing::PassTiming>,
     /// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
     custom: horizon_shaders::Custom,
     atlas: Option<wgpu::TextureView>,
@@ -1430,7 +1430,7 @@ impl PackPost {
             draws,
             block_ids,
             page_groups: HashMap::new(),
-            timing: super::pack_timing::PassTiming::new(device, queue),
+            timing: None,
             custom,
             atlas: world.atlas.as_ref().map(|a| a.0.clone()),
             lightmap: world.lightmap,
diff --git a/crates/horizon-client/src/gfx/pack_timing.rs b/crates/horizon-client/src/gfx/pack_timing.rs
index acfdb698f..24b97d7af 100644
--- a/crates/horizon-client/src/gfx/pack_timing.rs
+++ b/crates/horizon-client/src/gfx/pack_timing.rs
@@ -1,31 +1,53 @@
-//! Developers' aid: `HORIZON_SHADER_PACK_TIMING=1` times every pass of a shader pack on the
-//! GPU, one frame in `EVERY`, and logs each pass's median every `REPORT` timed frames. The
-//! frame after a timed one waits for the GPU before reading the timestamps (Metal resolves
-//! them without waiting for the passes that write them), so timing slows the game.
+//! GPU time of each pass of a shader pack, of either kind: shown in the F3 overlay while it is
+//! open, and logged every `REPORT` timed frames with `HORIZON_SHADER_PACK_TIMING=1`. One frame
+//! at a time is timed, and the CPU never waits for it: its timestamps are resolved in a later
+//! frame, once the GPU has finished it (Metal resolves them without waiting for the passes that
+//! write them), then read back when mapped. The next frame after that is timed again.
+
+use std::collections::VecDeque;
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
 
-const EVERY: u32 = 30;
 const REPORT: usize = 30;
 /// Passes timed per frame at most (two timestamps each).
 const CAPACITY: u32 = 64;
+/// Timed frames each pass's median is taken over.
+const WINDOW: usize = 15;
 
-pub(super) struct PassTiming {
+enum Stage {
+    /// The next frame is timed.
+    Idle,
+    /// The frame being recorded is timed.
+    Recording,
+    /// Submitted; the flag is set once the GPU has finished it.
+    Running(Arc<AtomicBool>),
+    /// Resolved and copied; the flag is set once the copy is mapped.
+    Reading(Arc<AtomicBool>, u64),
+}
+
+pub struct PassTiming {
     queries: wgpu::QuerySet,
     resolve: wgpu::Buffer,
     read: wgpu::Buffer,
     period_ns: f32,
-    frame: u32,
-    /// The passes timed in the frame being recorded or waiting to be read, in order.
+    stage: Stage,
+    /// The passes of the timed frame, in order.
     names: Vec<String>,
-    timed: bool,
-    samples: Vec<(String, Vec<f32>)>,
+    /// Each pass's last `WINDOW` times, in milliseconds.
+    samples: Vec<(String, VecDeque<f32>)>,
+    /// Log the medians every `REPORT` timed frames.
+    log: bool,
+    /// `mark`'s pipeline, for the target format it was made for.
+    marker: Option<(wgpu::TextureFormat, wgpu::RenderPipeline)>,
     reports: usize,
 }
 
 impl PassTiming {
+    /// `None` when the device can't time passes.
     pub fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Option<Self> {
-        if std::env::var_os("HORIZON_SHADER_PACK_TIMING").is_none()
-            || !device.features().contains(wgpu::Features::TIMESTAMP_QUERY)
-        {
+        if !device.features().contains(wgpu::Features::TIMESTAMP_QUERY) {
             return None;
         }
         let size = u64::from(CAPACITY) * 2 * 8;
@@ -52,51 +74,133 @@ impl PassTiming {
                 wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
             ),
             period_ns: queue.get_timestamp_period(),
-            frame: 0,
+            stage: Stage::Idle,
             names: Vec::new(),
-            timed: false,
             samples: Vec::new(),
+            log: Self::logging(),
+            marker: None,
             reports: 0,
         })
     }
 
-    /// At the start of a frame: reads the last timed frame's passes, and decides whether this
-    /// one is timed.
+    /// Whether `HORIZON_SHADER_PACK_TIMING` asks for timing without the F3 overlay.
+    pub fn logging() -> bool {
+        static LOG: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
+        *LOG.get_or_init(|| std::env::var_os("HORIZON_SHADER_PACK_TIMING").is_some())
+    }
+
+    /// At the start of a frame's passes: moves the last timed frame along, and decides whether
+    /// this one is timed.
     pub fn begin(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
-        if self.timed && !self.names.is_empty() {
-            self.collect(device, queue);
+        match &self.stage {
+            // A timed frame that was never submitted: time this one instead.
+            Stage::Recording => self.stage = Stage::Idle,
+            Stage::Running(done) if done.load(Ordering::Acquire) => {
+                let bytes = self.names.len() as u64 * 16;
+                let mut encoder = device.create_command_encoder(&Default::default());
+                encoder.resolve_query_set(
+                    &self.queries,
+                    0..self.names.len() as u32 * 2,
+                    &self.resolve,
+                    0,
+                );
+                encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.read, 0, bytes);
+                queue.submit([encoder.finish()]);
+                let mapped = Arc::new(AtomicBool::new(false));
+                let flag = mapped.clone();
+                self.read
+                    .slice(..bytes)
+                    .map_async(wgpu::MapMode::Read, move |r| {
+                        flag.store(r.is_ok(), Ordering::Release)
+                    });
+                self.stage = Stage::Reading(mapped, bytes);
+            }
+            Stage::Reading(mapped, bytes) if mapped.load(Ordering::Acquire) => {
+                let bytes = *bytes;
+                self.collect(bytes);
+                self.stage = Stage::Idle;
+            }
+            _ => {}
+        }
+        if matches!(self.stage, Stage::Idle) {
+            self.names.clear();
+            self.stage = Stage::Recording;
         }
-        self.names.clear();
-        self.frame += 1;
-        self.timed = self.frame.is_multiple_of(EVERY);
     }
 
     /// Timestamp writes for the pass `name`, in a timed frame.
     pub fn writes(&mut self, name: &str) -> Option<wgpu::RenderPassTimestampWrites<'_>> {
+        let i = self.push(name)?;
+        Some(stamps(&self.queries, i))
+    }
+
+    /// The index of the timed frame's next pass, `name`.
+    fn push(&mut self, name: &str) -> Option<u32> {
         let i = self.names.len() as u32;
-        if !self.timed || i >= CAPACITY {
+        if !matches!(self.stage, Stage::Recording) || i >= CAPACITY {
             return None;
         }
         self.names.push(name.to_owned());
-        Some(wgpu::RenderPassTimestampWrites {
-            query_set: &self.queries,
-            beginning_of_pass_write_index: Some(2 * i),
-            end_of_pass_write_index: Some(2 * i + 1),
-        })
+        Some(i)
     }
 
-    fn collect(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
-        // The timed frame first, then the resolve, so every timestamp is written.
-        _ = device.poll(wgpu::PollType::wait_indefinitely());
-        let count = self.names.len() as u32 * 2;
-        let bytes = u64::from(count) * 8;
-        let mut encoder = device.create_command_encoder(&Default::default());
-        encoder.resolve_query_set(&self.queries, 0..count, &self.resolve, 0);
-        encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.read, 0, bytes);
-        queue.submit([encoder.finish()]);
+    /// A pass that ends once everything drawn into `target` before it has, in a timed frame:
+    /// the next pass counts from there, not from when the GPU queued it behind them.
+    pub fn mark(
+        &mut self,
+        device: &wgpu::Device,
+        encoder: &mut wgpu::CommandEncoder,
+        (target, format): super::timing::Target,
+    ) {
+        if self.marker.as_ref().is_none_or(|(f, _)| *f != format) {
+            let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+                label: Some("Shader pack timing mark"),
+                source: wgpu::ShaderSource::Wgsl(super::timing::MARKER.into()),
+            });
+            let pipeline = super::timing::end_pipeline(device, &module, format);
+            self.marker = Some((format, pipeline));
+        }
+        // An unnamed pass: its end counts, it is never listed.
+        let Some(i) = self.push("") else {
+            return;
+        };
+        let (_, pipeline) = self.marker.as_ref().expect("made above");
+        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: Some("Shader pack timing mark"),
+            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                view: target,
+                depth_slice: None,
+                resolve_target: None,
+                ops: wgpu::Operations {
+                    load: wgpu::LoadOp::Load,
+                    store: wgpu::StoreOp::Store,
+                },
+            })],
+            timestamp_writes: Some(stamps(&self.queries, i)),
+            ..Default::default()
+        });
+        pass.set_pipeline(pipeline);
+        pass.set_scissor_rect(0, 0, 1, 1);
+        pass.draw(0..3, 0..1);
+    }
+
+    /// After the frame is submitted.
+    pub fn submitted(&mut self, queue: &wgpu::Queue) {
+        if !matches!(self.stage, Stage::Recording) {
+            return;
+        }
+        if self.names.is_empty() {
+            self.stage = Stage::Idle;
+            return;
+        }
+        let done = Arc::new(AtomicBool::new(false));
+        let flag = done.clone();
+        queue.on_submitted_work_done(move || flag.store(true, Ordering::Release));
+        self.stage = Stage::Running(done);
+    }
+
+    fn collect(&mut self, bytes: u64) {
         let slice = self.read.slice(..bytes);
-        slice.map_async(wgpu::MapMode::Read, |_| {});
-        _ = device.poll(wgpu::PollType::wait_indefinitely());
         let Ok(data) = slice.get_mapped_range() else {
             return;
         };
@@ -108,41 +212,91 @@ impl PassTiming {
             .collect();
         drop(data);
         self.read.unmap();
-        // Passes overlap on tiled GPUs (a pass begins before the one before it ends): a pass
-        // costs the time from the later of its beginning and the previous pass's end.
-        let mut previous_end = 0;
-        for (name, pair) in self.names.iter().zip(stamps.as_chunks::<2>().0) {
-            if pair[0] == 0 || pair[1] < pair[0] {
+        let times = pass_times(&stamps, self.period_ns);
+        for (name, ms) in self.names.iter().zip(times) {
+            let Some(ms) = ms.filter(|_| !name.is_empty()) else {
                 continue;
+            };
+            let i = match self.samples.iter().position(|s| s.0 == *name) {
+                Some(i) => i,
+                None => {
+                    self.samples.push((name.clone(), VecDeque::new()));
+                    self.samples.len() - 1
+                }
+            };
+            let window = &mut self.samples[i].1;
+            if window.len() == WINDOW {
+                window.pop_front();
             }
-            let from = pair[0].max(previous_end).min(pair[1]);
-            previous_end = pair[1];
-            let ms = (pair[1] - from) as f32 * self.period_ns / 1e6;
-            match self.samples.iter_mut().find(|s| s.0 == *name) {
-                Some(s) => s.1.push(ms),
-                None => self.samples.push((name.clone(), vec![ms])),
-            }
+            window.push_back(ms);
         }
         self.reports += 1;
-        if self.reports.is_multiple_of(REPORT) {
-            self.report();
+        if self.log && self.reports.is_multiple_of(REPORT) {
+            let medians = self.medians();
+            let total: f32 = medians.iter().map(|m| m.1).sum();
+            let parts: Vec<String> = medians
+                .iter()
+                .map(|(n, ms)| format!("{n} {ms:.3}"))
+                .collect();
+            log::info!(
+                "shader pack GPU time per pass (median ms of the last {WINDOW} timed frames): {} = {total:.3}",
+                parts.join(", ")
+            );
         }
     }
 
-    fn report(&mut self) {
-        let mut total = 0.0;
-        let mut parts = Vec::new();
-        // A pass that did not run in this window (no entities, the sky out of sight) is left out.
-        for (name, v) in self.samples.iter_mut().filter(|s| !s.1.is_empty()) {
-            v.sort_by(f32::total_cmp);
-            let median = v[v.len() / 2];
-            total += median;
-            parts.push(format!("{name} {median:.3}"));
-            v.clear();
-        }
-        log::info!(
-            "shader pack GPU time per pass (median ms of {REPORT} frames): {} = {total:.3}",
-            parts.join(", ")
-        );
+    /// Each pass's median time in milliseconds over its last timed frames, in the order the
+    /// passes first ran.
+    pub fn medians(&self) -> Vec<(String, f32)> {
+        self.samples
+            .iter()
+            .filter(|s| !s.1.is_empty())
+            .map(|(name, v)| {
+                let mut v: Vec<f32> = v.iter().copied().collect();
+                v.sort_by(f32::total_cmp);
+                (name.clone(), v[v.len() / 2])
+            })
+            .collect()
+    }
+}
+
+/// Pass `i`'s beginning and end timestamps.
+fn stamps(queries: &wgpu::QuerySet, i: u32) -> wgpu::RenderPassTimestampWrites<'_> {
+    wgpu::RenderPassTimestampWrites {
+        query_set: queries,
+        beginning_of_pass_write_index: Some(2 * i),
+        end_of_pass_write_index: Some(2 * i + 1),
+    }
+}
+
+/// Each pass's time in milliseconds from its (beginning, end) timestamps, `None` for a pass
+/// the GPU left unstamped. Passes overlap on tiled GPUs (a pass begins before the one before it
+/// ends): a pass costs the time from the later of its beginning and the previous pass's end.
+fn pass_times(stamps: &[u64], period_ns: f32) -> Vec<Option<f32>> {
+    let mut previous_end = 0;
+    stamps
+        .as_chunks::<2>()
+        .0
+        .iter()
+        .map(|&[begin, end]| {
+            if begin == 0 || end < begin {
+                return None;
+            }
+            let from = begin.max(previous_end).min(end);
+            previous_end = end;
+            Some((end - from) as f32 * period_ns / 1e6)
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::pass_times;
+
+    #[test]
+    fn overlapping_passes_cost_from_the_previous_end() {
+        // Pass 2 begins before pass 1 ends; pass 3 was never stamped.
+        let stamps = [1_000_000, 3_000_000, 2_000_000, 5_000_000, 0, 0];
+        assert_eq!(pass_times(&stamps, 1.0), [Some(2.0), Some(2.0), None]);
     }
 }
diff --git a/crates/horizon-client/src/gfx/timing.rs b/crates/horizon-client/src/gfx/timing.rs
index 5fc566fe7..7d2b17b3b 100644
--- a/crates/horizon-client/src/gfx/timing.rs
+++ b/crates/horizon-client/src/gfx/timing.rs
@@ -60,7 +60,7 @@ struct Markers {
 
 /// The start's one thread; the end's triangle over the whole target (the
 /// pass's scissor keeps one pixel), shading nothing it writes.
-const MARKER: &str =
+pub(super) const MARKER: &str =
     "@vertex fn cover(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
     return vec4<f32>(f32(i & 1u) * 4.0 - 1.0, f32(i >> 1u) * 4.0 - 1.0, 0.0, 1.0);
 }
@@ -254,7 +254,7 @@ impl GpuTimer {
 }
 
 /// The end marker's pipeline for a `format` target, every write masked.
-fn end_pipeline(
+pub(super) fn end_pipeline(
     device: &wgpu::Device,
     module: &wgpu::ShaderModule,
     format: wgpu::TextureFormat,
diff --git a/docs/shaders.md b/docs/shaders.md
index ef8521cfe..8ad1f24c8 100644
--- a/docs/shaders.md
+++ b/docs/shaders.md
@@ -127,11 +127,11 @@ one keeps drawing), the launcher before it installs one, and the registry's CI b
 6. Every entry point translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL), with the options at their
    defaults, minimums and maximums.
 
-`[budget] gpu_ms` is the GPU time your pack aims to add to a frame; the game's overlay will show each pass's time
-against it.
+`[budget] gpu_ms` is the GPU time your pack aims to add to a frame. To compare, open F3 in the game: while it is
+open, each pass is timed on the GPU and the overlay shows the pack's total and its costliest passes, by their `name`
+(the median of the last 15 timed frames). Timing waits for nothing, so it does not slow the game.
 
 ## Next
 
-The renderer hooks (shared with the Iris/OptiFine loader), then the post stage in the game with hot reload and the
-GPU time per pass, Options > Shader packs listing these packs, then the material and sky stages, and the registry's
-`shader` kind with installs from the launcher.
+Options > Shader packs listing these packs, then the material and sky stages, and the registry's `shader` kind with
+installs from the launcher.

From 70b832d658c84d586c2e80522044d851e51a7097 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 06:18:24 +0100
Subject: [PATCH 264/270] Options > Horizon Settings > Shader Packs: pick a
 pack of either kind

The page lists the packs in shaderpacks/: Horizon's own, marked (Horizon) and
named by their manifest, then packs in the shaders/ format. One runs at a
time: clicking a pack picks it, clicking the picked one turns it off, and
Open Pack Folder opens the folder. The pick is saved in horizon-graphics.txt
under a new key (pickedShaderPack), so the shaderPack value older versions
saved stays ignored. A new pick drops the running pack and loads the new one
in the next frame; HORIZON_SHADER_PACK still wins, for development.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/bin/horizon-ctl/commands.rs           |   1 +
 crates/horizon-client/src/game/control.rs     |   5 +
 .../horizon-client/src/game/native_shaders.rs |  18 ++-
 crates/horizon-client/src/game/options.rs     |  15 +++
 .../horizon-client/src/game/shader_packs.rs   |  32 +++--
 .../horizon-client/src/game/startup_menu.rs   |  10 ++
 crates/horizon-client/src/gfx.rs              |   6 +
 crates/horizon-client/src/graphics.rs         |  10 +-
 crates/horizon-client/src/lib.rs              |   1 +
 crates/horizon-client/src/options_ui.rs       |  91 ++++++++++++---
 crates/horizon-client/src/settings.rs         |   5 +
 crates/horizon-client/src/shader_pack_list.rs | 109 ++++++++++++++++++
 docs/horizon-ctl-commands.md                  |   2 +-
 docs/shaders.md                               |  13 ++-
 14 files changed, 281 insertions(+), 37 deletions(-)
 create mode 100644 crates/horizon-client/src/shader_pack_list.rs

diff --git a/crates/horizon-client/src/bin/horizon-ctl/commands.rs b/crates/horizon-client/src/bin/horizon-ctl/commands.rs
index cf7be69a6..f722e2f9a 100644
--- a/crates/horizon-client/src/bin/horizon-ctl/commands.rs
+++ b/crates/horizon-client/src/bin/horizon-ctl/commands.rs
@@ -143,6 +143,7 @@ const PAGES: Ty = Ty::Enum(&[
     "font",
     "packs",
     "mods",
+    "shader-packs",
     "graphics",
     "graphics-advanced",
     "extras",
diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs
index f418b0b83..7e6363fb9 100644
--- a/crates/horizon-client/src/game/control.rs
+++ b/crates/horizon-client/src/game/control.rs
@@ -612,6 +612,7 @@ impl Game<'_> {
                     "font" => Page::Font,
                     "packs" => Page::Packs,
                     "mods" => Page::Mods,
+                    "shader-packs" => Page::ShaderPacks,
                     "graphics" => Page::Graphics,
                     "graphics-advanced" => Page::GraphicsAdvanced,
                     "extras" => Page::Extras,
@@ -625,6 +626,10 @@ impl Game<'_> {
                 }
                 self.open_options(self.title.is_some());
                 self.ui.options.show(page);
+                if page == Page::ShaderPacks {
+                    self.settings.shader_packs =
+                        horizon_client::shader_pack_list::scan(&Self::shader_packs_dir());
+                }
                 ok()
             }
             "chat-log" => {
diff --git a/crates/horizon-client/src/game/native_shaders.rs b/crates/horizon-client/src/game/native_shaders.rs
index 62aaafc42..e72892b0e 100644
--- a/crates/horizon-client/src/game/native_shaders.rs
+++ b/crates/horizon-client/src/game/native_shaders.rs
@@ -1,7 +1,6 @@
-//! Horizon's own shader packs in the game (docs/shaders.md), for development until the Shader
-//! Packs page exists: `HORIZON_SHADER_PACK=<name>` naming one in `shaderpacks/` (a folder with
-//! `horizon-shaders.toml`, or a `.hshader`) runs it once it passes `horizon_shader_api::check`.
-//! The pack is looked at twice a second: a saved file is checked and the pack rebuilt, and a
+//! Horizon's own shader packs in the game (docs/shaders.md): the pick in `shaderpacks/` (a
+//! folder with `horizon-shaders.toml`, or a `.hshader`; `game/shader_packs.rs`) runs once it
+//! passes `horizon_shader_api::check`. The pack is looked at twice a second: a saved file is checked and the pack rebuilt, and a
 //! pack that fails is refused with its problems in the chat while the last good one keeps
 //! drawing.
 
@@ -21,11 +20,22 @@ const RED: u32 = 0xFF5555;
 
 #[derive(Default)]
 pub(super) struct NativeShaders {
+    /// The pack's name in `shaderpacks/`, of either kind (`game/shader_packs.rs`); empty: none.
+    pub picked: String,
     /// The pack's files when it was last read (`fingerprint`).
     stamp: Option<u64>,
     looked: Option<Instant>,
 }
 
+impl NativeShaders {
+    pub fn picking(name: &str) -> Self {
+        Self {
+            picked: name.to_owned(),
+            ..Self::default()
+        }
+    }
+}
+
 impl Game<'_> {
     /// Builds the pack at `path` when its files changed since it was last read.
     pub(super) fn tick_native_shader_pack(&mut self, path: &Path) {
diff --git a/crates/horizon-client/src/game/options.rs b/crates/horizon-client/src/game/options.rs
index 0e385e25c..8bfe52f76 100644
--- a/crates/horizon-client/src/game/options.rs
+++ b/crates/horizon-client/src/game/options.rs
@@ -85,6 +85,10 @@ impl Game<'_> {
             .unwrap_or_default()
             .join("options.txt")
     }
+    /// `shaderpacks/` beside `options.txt`.
+    pub(super) fn shader_packs_dir() -> std::path::PathBuf {
+        Self::options_path().with_file_name(horizon_client::shader_pack_list::DIR)
+    }
     pub(super) fn gui_size(&self) -> (f32, f32) {
         let size = self
             .renderer
@@ -237,6 +241,17 @@ impl Game<'_> {
                     let _ = std::fs::create_dir_all(&dir);
                     super::packs::open_folder(&dir);
                 }
+                Event::ListShaderPacks => {
+                    self.settings.shader_packs =
+                        horizon_client::shader_pack_list::scan(&Self::shader_packs_dir());
+                }
+                // Saved; the next frame's `shader_pack_inputs` loads the pick.
+                Event::ShaderPack => self.settings.save(&Self::options_path()),
+                Event::OpenShaderPackFolder => {
+                    let dir = Self::shader_packs_dir();
+                    let _ = std::fs::create_dir_all(&dir);
+                    super::packs::open_folder(&dir);
+                }
                 Event::ModSettings(i) => self.open_mod_screen(i, true),
                 Event::Credits => self.open_win_screen(false, super::win::Finish::Options),
             }
diff --git a/crates/horizon-client/src/game/shader_packs.rs b/crates/horizon-client/src/game/shader_packs.rs
index ed8ad61b7..4146283d3 100644
--- a/crates/horizon-client/src/game/shader_packs.rs
+++ b/crates/horizon-client/src/game/shader_packs.rs
@@ -1,7 +1,8 @@
-//! Shader packs, for development until the Shader Packs page exists: `HORIZON_SHADER_PACK=<name>`
-//! runs `shaderpacks/<name>` (a folder or a zip beside `options.txt`) over the world; Horizon's
-//! own packs go to `game/native_shaders.rs`. The
-//! programs of the current dimension's folder are loaded when the dimension changes (spec 1.2).
+//! Shader packs: the one picked on Options > Horizon Settings > Shader Packs, or
+//! `HORIZON_SHADER_PACK=<name>` (development; it wins over the pick), runs `shaderpacks/<name>`
+//! (a folder or a zip beside `options.txt`) over the world; Horizon's own packs go to
+//! `game/native_shaders.rs`. The programs of the current dimension's folder are loaded when the
+//! dimension changes (spec 1.2).
 
 use horizon_client::camera::CameraFluid;
 use horizon_client::gfx::pack_uniforms::PackInputs;
@@ -34,25 +35,34 @@ impl Game<'_> {
     /// Loads the pack for the current dimension when it changed, and returns this frame's
     /// inputs to the pack's uniforms.
     pub(super) fn shader_pack_inputs(&mut self, camera: glam::DVec3, partial: f32) -> PackInputs {
-        let Some(name) = std::env::var_os("HORIZON_SHADER_PACK") else {
+        static DEV_PACK: std::sync::OnceLock<Option<String>> = std::sync::OnceLock::new();
+        let dev = DEV_PACK.get_or_init(|| std::env::var("HORIZON_SHADER_PACK").ok());
+        let picked = dev.as_deref().unwrap_or(&self.settings.horizon.shader_pack);
+        if self.native_shaders.picked != picked {
+            // Another pack, or none: drop what ran.
+            self.native_shaders = super::native_shaders::NativeShaders::picking(picked);
+            self.pack_ids = None;
+            if let Some(renderer) = &mut self.renderer {
+                renderer.drop_shader_packs();
+            }
+        }
+        if picked.is_empty() {
             return PackInputs::default();
-        };
+        }
+        let name = picked.to_owned();
         let dimension = match self.dim {
             Dim::Overworld => 0,
             Dim::Nether => -1,
             Dim::End => 1,
         };
-        let path = std::env::current_dir()
-            .unwrap_or_default()
-            .join("shaderpacks")
-            .join(&name);
+        let path = Self::shader_packs_dir().join(&name);
         if horizon_shader_api::package::is_pack(&path) {
             // One of Horizon's own packs (game/native_shaders.rs).
             self.tick_native_shader_pack(&path);
         } else if let Some(renderer) = &mut self.renderer
             && renderer.shader_pack_dimension() != Some(dimension)
         {
-            let name = name.to_string_lossy();
+            let name = name.as_str();
             let started = std::time::Instant::now();
             match Pack::open(&path) {
                 Ok(pack) => {
diff --git a/crates/horizon-client/src/game/startup_menu.rs b/crates/horizon-client/src/game/startup_menu.rs
index f7be6241f..ed5971324 100644
--- a/crates/horizon-client/src/game/startup_menu.rs
+++ b/crates/horizon-client/src/game/startup_menu.rs
@@ -366,6 +366,16 @@ impl Loading {
                     let _ = std::fs::create_dir_all(&dir);
                     packs::open_folder(&dir);
                 }
+                Event::ListShaderPacks => {
+                    self.settings.shader_packs =
+                        horizon_client::shader_pack_list::scan(&Game::shader_packs_dir());
+                }
+                Event::ShaderPack => self.save_menu_settings(),
+                Event::OpenShaderPackFolder => {
+                    let dir = Game::shader_packs_dir();
+                    let _ = std::fs::create_dir_all(&dir);
+                    packs::open_folder(&dir);
+                }
                 Event::Credits => {
                     if let Some(gui) = &self.gui {
                         let name = self.options.as_ref().map_or_else(
diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs
index 24e386bc7..80cf1140e 100644
--- a/crates/horizon-client/src/gfx.rs
+++ b/crates/horizon-client/src/gfx.rs
@@ -2928,6 +2928,12 @@ impl Renderer {
         }
         report
     }
+    /// Drops the running shader pack, of either kind.
+    pub fn drop_shader_packs(&mut self) {
+        self.pack_post = None;
+        self.native_post = None;
+        self.pack_atlas = None;
+    }
     /// Runs the post passes of one of Horizon's own shader packs over the world from now on
     /// (`None`: no pack), with its options' values; replaces a `shaders/` pack. Returns the
     /// passes' labels; on an error the passes that ran keep running.
diff --git a/crates/horizon-client/src/graphics.rs b/crates/horizon-client/src/graphics.rs
index d3318aab2..b51a586ab 100644
--- a/crates/horizon-client/src/graphics.rs
+++ b/crates/horizon-client/src/graphics.rs
@@ -261,6 +261,10 @@ pub struct Graphics {
     pub battery: bool,
     /// The graphics API (Windows only; see `GraphicsApi`).
     pub api: GraphicsApi,
+    /// The shader pack picked in `shaderpacks/` (`shader_pack_list`); empty: none. Its key is
+    /// not `shaderPack`, which versions before the clean-room rewrite saved and which stays
+    /// ignored.
+    pub shader_pack: String,
 }
 impl Default for Graphics {
     fn default() -> Self {
@@ -284,6 +288,7 @@ impl Default for Graphics {
             fxaa: false,
             battery: false,
             api: GraphicsApi::Auto,
+            shader_pack: String::new(),
         }
     }
 }
@@ -334,6 +339,7 @@ impl Graphics {
                 "fxaa" => g.fxaa = flag(g.fxaa),
                 "batteryMode" => g.battery = flag(g.battery),
                 "graphicsApi" => g.api = GraphicsApi::from_name(value).unwrap_or_default(),
+                "pickedShaderPack" => g.shader_pack = value.to_owned(),
                 "overlay" => {
                     g.overlay = match value {
                         "fps" => Overlay::Fps,
@@ -348,7 +354,7 @@ impl Graphics {
     }
     pub fn serialize(&self) -> String {
         format!(
-            "preset:{}\nlodDistance:{}\nfarDetail:{}\ncaveCulling:{}\nentityCulling:{}\nchunkUpdates:{}\nuploadBudgetKiB:{}\nsky:{}\nfog:{}\nweather:{}\nanimatedTextures:{}\npresentMode:{}\nframePacing:{}\nworkers:{}\noverlay:{}\nresolutionScale:{}\nfxaa:{}\nbatteryMode:{}\ngraphicsApi:{}\n",
+            "preset:{}\nlodDistance:{}\nfarDetail:{}\ncaveCulling:{}\nentityCulling:{}\nchunkUpdates:{}\nuploadBudgetKiB:{}\nsky:{}\nfog:{}\nweather:{}\nanimatedTextures:{}\npresentMode:{}\nframePacing:{}\nworkers:{}\noverlay:{}\nresolutionScale:{}\nfxaa:{}\nbatteryMode:{}\ngraphicsApi:{}\npickedShaderPack:{}\n",
             self.preset.name(),
             self.lod_distance,
             self.far_detail.name(),
@@ -375,6 +381,7 @@ impl Graphics {
             bool_text(self.fxaa),
             bool_text(self.battery),
             self.api.name(),
+            self.shader_pack,
         )
     }
     pub fn save(&self, dir: &Path) {
@@ -471,6 +478,7 @@ mod tests {
             fxaa: true,
             battery: true,
             api: GraphicsApi::Dx12,
+            shader_pack: "Golden Hour".into(),
         };
         assert_eq!(Graphics::parse(&g.serialize()), g);
         assert_eq!(Graphics::parse(""), Graphics::default());
diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs
index 7ab6d3f61..21b0660f9 100644
--- a/crates/horizon-client/src/lib.rs
+++ b/crates/horizon-client/src/lib.rs
@@ -167,6 +167,7 @@ pub mod sculk;
 pub use horizon_server_files as server;
 pub mod server_packs;
 pub mod settings;
+pub mod shader_pack_list;
 pub mod shadows;
 pub mod signs;
 pub mod skins;
diff --git a/crates/horizon-client/src/options_ui.rs b/crates/horizon-client/src/options_ui.rs
index 9f91254bd..dfa06f47c 100644
--- a/crates/horizon-client/src/options_ui.rs
+++ b/crates/horizon-client/src/options_ui.rs
@@ -863,6 +863,8 @@ pub enum Page {
     Font,
     Packs,
     Mods,
+    /// Horizon's shader packs, either kind (`shader_pack_list`).
+    ShaderPacks,
     /// Horizon's graphics settings (`graphics_ui`).
     Graphics,
     GraphicsAdvanced,
@@ -893,6 +895,9 @@ enum Act {
     ResetPadKey(&'static str),
     ResetPadKeys,
     ToggleMod(usize),
+    /// Pick `s.shader_packs[i]`, or turn it off when it is the pick.
+    PickShaderPack(usize),
+    OpenShaderPackFolder,
     /// The installed mod's own settings page (capability `ui`), shown as a
     /// screen: `Event::ModSettings` has the game open it.
     ModSettings(usize),
@@ -947,6 +952,11 @@ pub enum Event {
     Packs(Vec<String>),
     OpenPackFolder,
     OpenModFolder,
+    /// The Shader Packs page opened: list `shaderpacks/` into `shader_packs`.
+    ListShaderPacks,
+    /// A shader pack was picked or turned off: save and apply it.
+    ShaderPack,
+    OpenShaderPackFolder,
     /// Open the mod's own settings page (capability `ui`): the installed
     /// mod's index in `mods.installed`.
     ModSettings(usize),
@@ -1092,6 +1102,9 @@ fn horizon_page_tooltip(page: Page) -> Option<&'static str> {
             "Optional additions, all off by default: the game stays vanilla until you turn one on."
         }
         Page::Agent => "Let your own AI agent play: horizon-ctl and MCP clients on this computer.",
+        Page::ShaderPacks => {
+            "Shader packs from the shaderpacks folder: Horizon's own and those in the shaders/ format. One runs at a time."
+        }
         Page::Mods => {
             "Mods made for Horizon, from the horizon-mods folder. Each runs in a sandbox and stays off until you turn it on."
         }
@@ -1183,6 +1196,7 @@ impl OptionsUi {
             Page::Font => "options.font.title",
             Page::Packs => "resourcePack.title",
             Page::Mods => "Mods",
+            Page::ShaderPacks => "Shader Packs",
             Page::Graphics | Page::GraphicsAdvanced => "options.videoTitle",
             Page::Controller => "Controller Settings",
             Page::PadBinds => "Controller Binds",
@@ -1299,23 +1313,30 @@ impl OptionsUi {
                         Some(open("Advanced Graphics...", Page::GraphicsAdvanced)),
                     ),
                     Row::Buttons(
-                        open("Controller Settings...", Page::Controller),
-                        Some(self.extra_button(s, crate::extras::Item::DiscordPresence)),
+                        open("Shader Packs...", Page::ShaderPacks),
+                        Some(open("Controller Settings...", Page::Controller)),
                     ),
                     Row::Buttons(
                         open("Extras...", Page::Extras),
                         Some(open("Mods...", Page::Mods)),
                     ),
                     // No AI hides the AI Agent page and everything AI.
-                    if s.extras.no_ai {
-                        Row::Buttons(self.extra_button(s, crate::extras::Item::NoAi), None)
-                    } else {
-                        Row::Buttons(
-                            open("AI Agent...", Page::Agent),
-                            Some(self.extra_button(s, crate::extras::Item::NoAi)),
-                        )
-                    },
+                    Row::Buttons(
+                        self.extra_button(s, crate::extras::Item::DiscordPresence),
+                        Some(if s.extras.no_ai {
+                            self.extra_button(s, crate::extras::Item::NoAi)
+                        } else {
+                            open("AI Agent...", Page::Agent)
+                        }),
+                    ),
                 ]
+                .into_iter()
+                .chain(
+                    (!s.extras.no_ai).then(|| {
+                        Row::Buttons(self.extra_button(s, crate::extras::Item::NoAi), None)
+                    }),
+                )
+                .collect()
             }
             Page::Agent => {
                 let mut rows = vec![Row::Buttons(
@@ -1532,6 +1553,26 @@ impl OptionsUi {
                     })
                     .collect()
             }
+            Page::ShaderPacks => {
+                if s.shader_packs.is_empty() {
+                    return vec![Row::Header(
+                        "No shader packs: put them in the shaderpacks folder",
+                    )];
+                }
+                s.shader_packs
+                    .iter()
+                    .enumerate()
+                    .map(|(i, pack)| {
+                        let kind = match pack.kind {
+                            crate::shader_pack_list::Kind::Horizon => " (Horizon)",
+                            crate::shader_pack_list::Kind::Classic => "",
+                        };
+                        let label = Text::literal(format!("{}{kind}: ", pack.title))
+                            .append(on_off(s.horizon.shader_pack == pack.file));
+                        Row::Buttons(button(0.0, 0.0, 310.0, label, Act::PickShaderPack(i)), None)
+                    })
+                    .collect()
+            }
             _ => {
                 let _ = s;
                 Vec::new()
@@ -2017,13 +2058,18 @@ impl OptionsUi {
                 }
                 content = y + self.scroll - top + 2.0;
                 out[list_start..].iter_mut().for_each(|w| w.list = true);
-                if page == Page::Mods {
+                let folder = match page {
+                    Page::Mods => Some(("Open Mod Folder", Act::OpenModFolder)),
+                    Page::ShaderPacks => Some(("Open Pack Folder", Act::OpenShaderPackFolder)),
+                    _ => None,
+                };
+                if let Some((label, act)) = folder {
                     out.push(button(
                         cx - 154.0,
                         h - 27.0,
                         150.0,
-                        Text::literal("Open Mod Folder"),
-                        Act::OpenModFolder,
+                        Text::literal(label),
+                        act,
                     ));
                     out.push(button(cx + 4.0, h - 27.0, 150.0, tr("gui.done"), Act::Done));
                 } else {
@@ -2475,7 +2521,12 @@ impl OptionsUi {
                 } => {
                     events.push(Event::ButtonClick);
                     match act {
-                        Act::Push(p) => self.push(p),
+                        Act::Push(p) => {
+                            if p == Page::ShaderPacks {
+                                events.push(Event::ListShaderPacks);
+                            }
+                            self.push(p)
+                        }
                         Act::Done => events.extend(self.back(s)),
                         Act::Cycle(opt) => {
                             opt.cycle(s, right, framebuffer);
@@ -2520,6 +2571,17 @@ impl OptionsUi {
                             events.push(Event::ModSettings(i));
                         }
                         Act::OpenModFolder => events.push(Event::OpenModFolder),
+                        Act::PickShaderPack(i) => {
+                            if let Some(pack) = s.shader_packs.get(i) {
+                                s.horizon.shader_pack = if s.horizon.shader_pack == pack.file {
+                                    String::new()
+                                } else {
+                                    pack.file.clone()
+                                };
+                                events.push(Event::ShaderPack);
+                            }
+                        }
+                        Act::OpenShaderPackFolder => events.push(Event::OpenShaderPackFolder),
                         Act::Credits => events.push(Event::Credits),
                         Act::CopyAgentDetails => events.push(Event::CopyAgentDetails),
                         Act::None => {}
@@ -4064,6 +4126,7 @@ mod tests {
             [
                 Page::Graphics,
                 Page::GraphicsAdvanced,
+                Page::ShaderPacks,
                 Page::Controller,
                 Page::Extras,
                 Page::Mods,
diff --git a/crates/horizon-client/src/settings.rs b/crates/horizon-client/src/settings.rs
index 2a53e1702..793a95dce 100644
--- a/crates/horizon-client/src/settings.rs
+++ b/crates/horizon-client/src/settings.rs
@@ -182,6 +182,9 @@ pub struct Settings {
     pub extras: crate::extras::Extras,
     /// The Horizon mods turned on (`horizon-mods.txt`), all off by default.
     pub mods: crate::mod_list::ModList,
+    /// The packs in `shaderpacks/`, listed when the Shader Packs page opens; the pick is
+    /// `horizon.shader_pack`.
+    pub shader_packs: Vec<crate::shader_pack_list::Entry>,
 }
 impl Default for Settings {
     fn default() -> Self {
@@ -255,6 +258,7 @@ impl Default for Settings {
             controller: Default::default(),
             extras: Default::default(),
             mods: Default::default(),
+            shader_packs: Vec::new(),
         }
     }
 }
@@ -415,6 +419,7 @@ impl Settings {
             controller: Default::default(),
             extras: Default::default(),
             mods: Default::default(),
+            shader_packs: Vec::new(),
             auto_jump: f.bool("autoJump"),
             language: f.string("lang"),
             force_unicode: f.bool("forceUnicodeFont"),
diff --git a/crates/horizon-client/src/shader_pack_list.rs b/crates/horizon-client/src/shader_pack_list.rs
new file mode 100644
index 000000000..c9a8f338b
--- /dev/null
+++ b/crates/horizon-client/src/shader_pack_list.rs
@@ -0,0 +1,109 @@
+//! The shader packs in the `shaderpacks` folder beside `options.txt`, as Options > Horizon
+//! Settings > Shader Packs lists them: Horizon's own (docs/shaders.md) and those in the
+//! `shaders/` format, side by side.
+
+use std::path::Path;
+
+pub const DIR: &str = "shaderpacks";
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Kind {
+    /// A folder with `horizon-shaders.toml`, or a `.hshader`.
+    Horizon,
+    /// A folder with a `shaders` folder, or a `.zip`.
+    Classic,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Entry {
+    /// The folder's or file's name in `shaderpacks`: what the pick saves.
+    pub file: String,
+    /// The pack's own name for Horizon's packs, else `file`.
+    pub title: String,
+    pub kind: Kind,
+}
+
+/// The packs in `dir`, Horizon's first, each kind by title. A missing folder has none.
+pub fn scan(dir: &Path) -> Vec<Entry> {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    let mut packs: Vec<Entry> = entries.flatten().filter_map(|e| entry(&e.path())).collect();
+    packs.sort_by(|a, b| {
+        (a.kind == Kind::Classic, a.title.to_lowercase())
+            .cmp(&(b.kind == Kind::Classic, b.title.to_lowercase()))
+    });
+    packs
+}
+
+fn entry(path: &Path) -> Option<Entry> {
+    let file = path.file_name()?.to_str()?.to_owned();
+    if file.starts_with('.') {
+        return None;
+    }
+    if horizon_shader_api::package::is_pack(path) {
+        // Its manifest's name; a pack that can't be read is still listed, under its file
+        // name: picking it says why in the chat.
+        let manifest = if path.is_dir() {
+            std::fs::read_to_string(path.join(horizon_shader_api::MANIFEST))
+                .ok()
+                .and_then(|t| horizon_shader_api::Manifest::parse(&t).ok())
+        } else {
+            horizon_shader_api::Pack::read(path)
+                .ok()
+                .map(|p| p.manifest)
+        };
+        let title = manifest.map_or_else(|| file.clone(), |m| m.name);
+        return Some(Entry {
+            file,
+            title,
+            kind: Kind::Horizon,
+        });
+    }
+    let zip = path.is_file()
+        && path
+            .extension()
+            .is_some_and(|e| e.eq_ignore_ascii_case("zip"));
+    (zip || path.join("shaders").is_dir()).then(|| Entry {
+        title: file.clone(),
+        file,
+        kind: Kind::Classic,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lists_both_kinds_horizon_first_and_skips_the_rest() {
+        let dir = std::env::temp_dir().join(format!("horizon-shader-list-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let d = dir.as_path();
+        let manifest = "schema = 1\nid = \"warm\"\nname = \"Warm Light\"\nversion = \"1\"\n\
+            api = \"0.1\"\n[[post]]\nfile = \"p.wgsl\"\n";
+        std::fs::create_dir(d.join("warm")).unwrap();
+        std::fs::write(d.join("warm").join(horizon_shader_api::MANIFEST), manifest).unwrap();
+        std::fs::create_dir_all(d.join("Classic Folder/shaders")).unwrap();
+        std::fs::write(d.join("archive.zip"), b"").unwrap();
+        std::fs::write(d.join("notes.txt"), b"").unwrap();
+        std::fs::create_dir(d.join("empty")).unwrap();
+        std::fs::create_dir_all(d.join(".hidden/shaders")).unwrap();
+        let packs = scan(d);
+        let listed: Vec<(&str, &str, Kind)> = packs
+            .iter()
+            .map(|e| (e.file.as_str(), e.title.as_str(), e.kind))
+            .collect();
+        assert_eq!(
+            listed,
+            [
+                ("warm", "Warm Light", Kind::Horizon),
+                ("archive.zip", "archive.zip", Kind::Classic),
+                ("Classic Folder", "Classic Folder", Kind::Classic),
+            ]
+        );
+        assert!(scan(&d.join("missing")).is_empty());
+        std::fs::remove_dir_all(d).unwrap();
+    }
+}
diff --git a/docs/horizon-ctl-commands.md b/docs/horizon-ctl-commands.md
index 394aac5bf..9b3d792c7 100644
--- a/docs/horizon-ctl-commands.md
+++ b/docs/horizon-ctl-commands.md
@@ -94,7 +94,7 @@ Every command `horizon-ctl` takes, its MCP tool in `horizon-ctl mcp` (the launch
 | `respawn` | `respawn` | Respawn from the death screen | none |
 | `pause` | `pause` | Open the pause menu | none |
 | `resume` | `resume` | Leave the pause menu | none |
-| `options [PAGE]` | `options` | Open the options screen, or one of its pages (Horizon's too) | `page` (main, video, sound, controls, keybinds, controller, controller-binds, mouse, chat, accessibility, language, font, packs, mods, graphics, graphics-advanced, extras, horizon, agent): the page (default: the main options) |
+| `options [PAGE]` | `options` | Open the options screen, or one of its pages (Horizon's too) | `page` (main, video, sound, controls, keybinds, controller, controller-binds, mouse, chat, accessibility, language, font, packs, mods, shader-packs, graphics, graphics-advanced, extras, horizon, agent): the page (default: the main options) |
 | `book [next\|back\|take\|done]` | `book` | The open book or lectern: its page text, or press one of its buttons | `action` (next, back, take, done): a button to press |
 | `signedit X Y Z [front\|back]` | `signedit` | Open the sign editor of the sign at X Y Z (then type and close) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`side` (front, back): which side |
 | `mount-menu` | `mount_menu` | Open the inventory of the horse, donkey, mule or llama being ridden | none |
diff --git a/docs/shaders.md b/docs/shaders.md
index 8ad1f24c8..92dd74685 100644
--- a/docs/shaders.md
+++ b/docs/shaders.md
@@ -13,7 +13,7 @@ Horizon's own format.
 | Authoring tool | `horizon-shader` (same crate) | `new`, `check`, `pack` |
 | Templates | `crates/horizon-shader-api/templates/` | post, sky, material |
 | Example pack | `crates/horizon-shader-api/packs/golden_hour` | a warm sky and two post passes |
-| In the game: the post stage | `HORIZON_SHADER_PACK=<name>` (for development, until the Shader Packs page) | post passes, hot reload |
+| In the game: the post stage | Options > Horizon Settings > Shader Packs | post passes, hot reload |
 | In the game: sky and material; the launcher and the registry | | not yet |
 
 ## Quick start
@@ -46,9 +46,11 @@ my_pack 0.1.0 (shader API 0.1): FAILED
 
 ## Trying a pack in the game
 
-Until the Shader Packs page lists them, put the pack folder (or its `.hshader`) in `shaderpacks/` beside `options.txt`
-and start the game with `HORIZON_SHADER_PACK=<its folder or file name>`. The game checks the pack first, and refuses
-one that fails, with its problems in the chat. While it runs, the game looks at the pack twice a second: save a file
+Put the pack folder (or its `.hshader`) in `shaderpacks/` beside `options.txt` (Open Pack Folder opens it) and pick
+it on Options > Horizon Settings > Shader Packs, which lists Horizon's packs, marked (Horizon), beside packs in the
+`shaders/` format; one runs at a time, and clicking it again turns it off. `HORIZON_SHADER_PACK=<its folder or file
+name>` runs a pack whatever the page says, for development. The game checks the pack first, and refuses one that
+fails, with its problems in the chat. While it runs, the game looks at the pack twice a second: save a file
 and the pack is checked and rebuilt in place ("Shader pack ... reloaded"); if the new version fails, the chat says
 where and the last good version keeps drawing. The post passes run today; the sky and material stages are checked
 but not drawn yet.
@@ -133,5 +135,4 @@ open, each pass is timed on the GPU and the overlay shows the pack's total and i
 
 ## Next
 
-Options > Shader packs listing these packs, then the material and sky stages, and the registry's `shader` kind with
-installs from the launcher.
+The material and sky stages in the game, and the registry's `shader` kind with installs from the launcher.

From 130f1dc6a5a83917bd89477414b528e640cefc6f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 07:13:21 +0100
Subject: [PATCH 265/270] horizon-ctl options-set keeps the mod list

options-set rebuilt Settings from options.txt and carried over Horizon's
graphics, controller and extras files, but not the mod list: every mod
read as off afterwards, and the next save wrote an empty
horizon-mods.txt. Settings::with_option now does the rebuild and keeps
all four.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/options.rs |  9 +------
 crates/horizon-client/src/settings.rs     | 30 +++++++++++++++++++++++
 2 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/game/options.rs b/crates/horizon-client/src/game/options.rs
index 0e385e25c..3a61b0e7a 100644
--- a/crates/horizon-client/src/game/options.rs
+++ b/crates/horizon-client/src/game/options.rs
@@ -57,14 +57,7 @@ impl Game<'_> {
                     .map(str::trim)
                     .filter(|v| !v.is_empty())
                     .ok_or("options-set KEY VALUE: missing the value")?;
-                let mut file = self.settings.to_file();
-                file.set_text(key, value)?;
-                let mut settings = horizon_client::settings::Settings::from_file(file);
-                // Horizon's own files are not in options.txt.
-                std::mem::swap(&mut settings.horizon, &mut self.settings.horizon);
-                std::mem::swap(&mut settings.controller, &mut self.settings.controller);
-                std::mem::swap(&mut settings.extras, &mut self.settings.extras);
-                self.settings = settings;
+                self.settings = self.settings.with_option(key, value)?;
                 // As the options screen applies a change.
                 self.handle_option_events(vec![Event::Changed])?;
                 match *key {
diff --git a/crates/horizon-client/src/settings.rs b/crates/horizon-client/src/settings.rs
index 2a53e1702..ebffc897f 100644
--- a/crates/horizon-client/src/settings.rs
+++ b/crates/horizon-client/src/settings.rs
@@ -538,6 +538,21 @@ impl Settings {
         }
         f
     }
+    /// These settings with one `options.txt` value changed (`horizon-ctl
+    /// options-set`, as `OptionsFile::set_text` reads it). Horizon's own
+    /// files (graphics, controller, extras, the mod list) aren't in
+    /// `options.txt`, so they stay as they are.
+    pub fn with_option(&self, key: &str, value: &str) -> Result<Self, String> {
+        let mut file = self.to_file();
+        file.set_text(key, value)?;
+        Ok(Self {
+            horizon: self.horizon.clone(),
+            controller: self.controller.clone(),
+            extras: self.extras.clone(),
+            mods: self.mods.clone(),
+            ..Self::from_file(file)
+        })
+    }
     /// The `options.txt` text (Options.save).
     pub fn serialize(&self) -> String {
         self.to_file().serialize()
@@ -592,6 +607,21 @@ impl Settings {
 mod tests {
     use super::*;
     #[test]
+    fn an_option_set_keeps_horizon_files() {
+        let mut s = Settings::parse("fov:70\n");
+        s.mods.enabled.insert("zoom".into());
+        s.extras.minimap = true;
+        s.horizon.fog = !s.horizon.fog;
+        s.controller.vibration = !s.controller.vibration;
+        let set = s.with_option("fov", "90").unwrap();
+        assert_eq!(set.fov, 90.0);
+        assert_eq!(set.mods, s.mods);
+        assert_eq!(set.extras, s.extras);
+        assert_eq!(set.horizon, s.horizon);
+        assert_eq!(set.controller, s.controller);
+        assert!(s.with_option("fov", "200").is_err());
+    }
+    #[test]
     fn gui_scale_survives_temporary_small_framebuffer() {
         for requested in [0, 1, 2, 6] {
             let settings = Settings::parse(&format!("guiScale:{requested}\n"));

From 053291e3392abf47c495bf6c8ea9dc0f1d37d64c Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 06:21:32 +0100
Subject: [PATCH 266/270] Mob scans skip sections that can't hold what they
 look for

A mob's fluid state and its supporting block each read every cell around
its box, every tick. World::may_hold answers from the palettes of the
sections the box reaches: with no fluid listed there the fluid scan stops
before reading a cell, and with no block that reaches out of its cell
(large collision shapes, moving pistons) the supporting block search
reads only the cells meeting its area, as BlockCollisions' cursor does.
Results are the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/mobs/living.rs | 51 ++++++++++++++++---
 crates/horizon-client/src/world.rs       | 63 ++++++++++++++++++++++++
 2 files changed, 106 insertions(+), 8 deletions(-)

diff --git a/crates/horizon-client/src/mobs/living.rs b/crates/horizon-client/src/mobs/living.rs
index f16e0e18d..394821ace 100644
--- a/crates/horizon-client/src/mobs/living.rs
+++ b/crates/horizon-client/src/mobs/living.rs
@@ -64,6 +64,31 @@ impl MobWorld<'_> {
         let b = bounds.deflate(Vec3::new(0.001, 0.001, 0.001));
         let (lo, hi) = (b.min_position(), b.max_position());
         let mut out = Fluids::default();
+        // The eye column below, in the box but for a box thinner than the
+        // deflation.
+        let (ex, ez) = (
+            ((lo.x + hi.x) / 2.0).floor() as i32,
+            ((lo.z + hi.z) / 2.0).floor() as i32,
+        );
+        // Most boxes are in sections without a fluid: no cell to read.
+        let cells = (
+            [
+                (lo.x.floor() as i32).min(ex),
+                lo.y.floor() as i32,
+                (lo.z.floor() as i32).min(ez),
+            ],
+            [
+                (hi.x.ceil() as i32 - 1).max(ex),
+                hi.y.ceil() as i32 - 1,
+                (hi.z.ceil() as i32 - 1).max(ez),
+            ],
+        );
+        if !self
+            .world
+            .may_hold(cells.0, cells.1, |s| self.facts.get(s).fluid != Fluid::None)
+        {
+            return out;
+        }
         for x in lo.x.floor() as i32..=(hi.x.ceil() as i32 - 1) {
             for y in lo.y.floor() as i32..=(hi.y.ceil() as i32 - 1) {
                 for z in lo.z.floor() as i32..=(hi.z.ceil() as i32 - 1) {
@@ -92,10 +117,6 @@ impl MobWorld<'_> {
         // EntityFluidInteraction.update: the eyes are in a fluid block of
         // the box in the entity's column, between its bottom and its height
         // for the camera.
-        let (ex, ez) = (
-            ((lo.x + hi.x) / 2.0).floor() as i32,
-            ((lo.z + hi.z) / 2.0).floor() as i32,
-        );
         for y in lo.y.floor() as i32..=(hi.y.ceil() as i32 - 1) {
             let (fluid, h) = self.fluid_height(ex, y, ez);
             if fluid != Fluid::Water || f64::from(y) + h < lo.y || eye_y < f64::from(y) {
@@ -155,14 +176,28 @@ impl MobWorld<'_> {
             let c = f64::from(c);
             c < area.max(axis) && c + 1.0 > area.min(axis)
         };
+        // Where no section of the cursor holds a block reaching out of its
+        // cell, only the cells meeting `area` can hold the support.
+        let (rx, ry, rz) = (range(Axis::X), range(Axis::Y), range(Axis::Z));
+        let outer = self.world.may_hold(
+            [*rx.start(), *ry.start(), *rz.start()],
+            [*rx.end(), *ry.end(), *rz.end()],
+            |s| self.collision.reaches_out(s),
+        );
         let mut best: Option<(f64, [i32; 3])> = None;
-        for x in range(Axis::X) {
-            for z in range(Axis::Z) {
+        for x in rx {
+            for z in rz.clone() {
+                let column = meets(Axis::X, x) && meets(Axis::Z, z);
+                if !outer && !column {
+                    continue;
+                }
                 let Some(chunk) = self.world.chunks.get(&(x >> 4, z >> 4)) else {
                     continue;
                 };
-                let column = meets(Axis::X, x) && meets(Axis::Z, z);
-                for y in range(Axis::Y) {
+                for y in ry.clone() {
+                    if !outer && !meets(Axis::Y, y) {
+                        continue;
+                    }
                     let state = chunk.block(x & 15, y, z & 15);
                     let Ok(block) = self.collision.collision_block(state) else {
                         continue;
diff --git a/crates/horizon-client/src/world.rs b/crates/horizon-client/src/world.rs
index 3b2920ade..d73956d85 100644
--- a/crates/horizon-client/src/world.rs
+++ b/crates/horizon-client/src/world.rs
@@ -311,6 +311,40 @@ impl World {
             .get(&(x >> 4, z >> 4))
             .map_or(self.air, |chunk| chunk.block(x & 15, y, z & 15))
     }
+    /// Whether a block of the box `lo..=hi` may match, from the palettes of
+    /// the sections it reaches (a palette of the whole registry may hold
+    /// anything): `false` means [`Self::block`] matches in none of its cells,
+    /// so a scan over them can stop before reading one.
+    pub fn may_hold(
+        &self,
+        lo: [i32; 3],
+        hi: [i32; 3],
+        mut matches: impl FnMut(BlockStateId) -> bool,
+    ) -> bool {
+        let top = MIN_Y + SECTIONS as i32 * 16 - 1;
+        // Heights outside the sections read as state 0.
+        if (lo[1] < MIN_Y || hi[1] > top) && matches(BlockStateId(0)) {
+            return true;
+        }
+        let sections = (lo[1].max(MIN_Y) - MIN_Y) >> 4..=(hi[1].min(top) - MIN_Y) >> 4;
+        for cx in lo[0] >> 4..=hi[0] >> 4 {
+            for cz in lo[2] >> 4..=hi[2] >> 4 {
+                let Some(chunk) = self.chunks.get(&(cx, cz)) else {
+                    if matches(self.air) {
+                        return true;
+                    }
+                    continue;
+                };
+                for s in sections.clone() {
+                    let blocks = &chunk.sections[s as usize].blocks;
+                    if blocks.is_global() || blocks.maybe_has(|v| matches(BlockStateId(v))) {
+                        return true;
+                    }
+                }
+            }
+        }
+        false
+    }
     /// The block entities to tick this tick, in order (`BlockEntities::tickers`).
     pub fn block_entity_tickers(&mut self) -> Vec<(crate::block_entities::Pos, u32)> {
         let (chunks, air) = (&self.chunks, self.air);
@@ -333,3 +367,32 @@ impl World {
         self.chunks.contains_key(&(x >> 4, z >> 4))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::World;
+    use crate::chunk::Chunk;
+    use horizon_world::registry::BlockStateId;
+    use std::sync::Arc;
+
+    /// A box misses a state only where no section it reaches lists it, and
+    /// unloaded columns or heights past the world count as their air.
+    #[test]
+    fn may_hold_reads_the_palettes_of_the_reached_sections() {
+        let mut world = World::new(BlockStateId(0), 0);
+        let mut chunk = Chunk::empty(0, 0);
+        chunk.set(3, 70, 3, 9);
+        world.chunks.insert((0, 0), Arc::new(chunk));
+        let nine = |s: BlockStateId| s.0 == 9;
+        // The section of y 64..80 holds 9, the one below does not.
+        assert!(world.may_hold([0, 64, 0], [1, 65, 1], nine));
+        assert!(world.may_hold([10, 79, 10], [12, 80, 12], nine));
+        assert!(!world.may_hold([0, 50, 0], [15, 63, 15], nine));
+        // A box over the unloaded column next door sees only air.
+        assert!(!world.may_hold([16, 70, 0], [17, 71, 1], nine));
+        assert!(world.may_hold([16, 70, 0], [17, 71, 1], |s| s.0 == 0));
+        // Past the top, and the palette of air below it.
+        assert!(!world.may_hold([0, 400, 0], [0, 401, 0], nine));
+        assert!(world.may_hold([0, 400, 0], [0, 401, 0], |s| s.0 == 0));
+    }
+}

From 8e71cb4754c17fbc083ef212fdd21806c7900309 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 07:57:49 +0100
Subject: [PATCH 267/270] Test runner: fill the snapshot's new fields, with the
 trial run's screen size

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-mods/src/testing.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/crates/horizon-mods/src/testing.rs b/crates/horizon-mods/src/testing.rs
index 4a62b3838..d8c8076b4 100644
--- a/crates/horizon-mods/src/testing.rs
+++ b/crates/horizon-mods/src/testing.rs
@@ -87,6 +87,9 @@ impl TestGame {
         self.mods.set_snapshot(Snapshot {
             player: self.player.clone(),
             clock: self.clock,
+            // The GUI of a 1280 x 720 window at scale 3, as the trial run's.
+            gui_size: (427.0, 240.0),
+            ..Snapshot::default()
         });
     }
 

From 6ace65fc1869170334207f0d0bb38d019e163d2f Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:11:46 +0100
Subject: [PATCH 268/270] ci: parity-main's runner comment says where it runs
 now

ludovics-mac-mini-2 holds only the horizon-parity-main label; the release
runner no longer has it, since a release waited behind each new
parity-main run there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/parity-main.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/parity-main.yml b/.github/workflows/parity-main.yml
index 13be3c36d..c47005ab0 100644
--- a/.github/workflows/parity-main.yml
+++ b/.github/workflows/parity-main.yml
@@ -23,10 +23,10 @@ env:
 
 jobs:
   parity-main:
-    # The Mac mini's release runner (label added 2026-10-26), not the two `horizon-game` runners: behind PR parity jobs
-    # this run waited 2 h while every merge replaced the pending one, and releases wait for it. Releases need it green
-    # first, so the two never compete. Not the desktop: a job slowed down because the maintainer came back could time
-    # out, and a failure here bisects and comments on merges.
+    # A Mac mini runner of its own (ludovics-mac-mini-2 holds only this label since 2026-10-26): behind PR parity jobs
+    # this run waited 2 h while every merge replaced the pending one, and on the release runner a release then waited
+    # behind the next run. PR parity jobs have ludovics-mac-mini and the desktop. Not the desktop: a job slowed down
+    # because the maintainer came back could time out, and a failure here bisects and comments on merges.
     runs-on: [self-hosted, macOS, horizon-parity-main]
     timeout-minutes: 240  # a core-crate batch reruns ~300 harnesses (~60-90 min), a bisect a few rounds of the failures
     steps:

From 24ab642e7bc79eea0cd97d99a7abcf1c5049f9ea Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:20:30 +0100
Subject: [PATCH 269/270] Mod API: render.set-minimap, a map the game keeps in
 a corner

What the official Minimap mod needs: a mod picks the corner, side, scale,
shape and turning, and the game draws the map as the minimap extra does,
from the same tiles (vanilla's map colours, the floor under roofs) within
its own frame budget. One map at a time, the first loaded mod's. A new
function and type, so mods built before it keep loading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/horizon-client/src/game/extras.rs      | 48 +++++++++++++------
 crates/horizon-client/src/game/mod_input.rs   | 31 ++++++++++++
 crates/horizon-mod-sdk/wit/horizon.wit        | 21 ++++++++
 crates/horizon-mods/src/runtime.rs            | 25 +++++++++-
 crates/horizon-mods/tests/sandbox.rs          | 26 ++++++++++
 crates/horizon-mods/tests/ui_guest/src/lib.rs | 19 ++++++++
 docs/api/mods-reference.md                    | 11 +++++
 docs/api/stability.md                         |  4 ++
 docs/mods.md                                  |  2 +-
 9 files changed, 169 insertions(+), 18 deletions(-)

diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs
index 30073f186..3abe6f5c7 100644
--- a/crates/horizon-client/src/game/extras.rs
+++ b/crates/horizon-client/src/game/extras.rs
@@ -159,25 +159,44 @@ impl Game<'_> {
         }
         Ok(())
     }
-    /// The minimap's view of the player, if it shows.
-    fn minimap_view(&self) -> Option<View> {
-        let e = &self.settings.extras;
+    /// The minimap that shows, the extra's or else a mod's
+    /// (`render.set-minimap`): its corner, its side in GUI pixels and its
+    /// view of the player.
+    fn minimap_shown(&self) -> Option<(Corner, f32, View)> {
         let p = self.player.as_ref()?;
-        let shown = e.minimap && self.title.is_none() && !self.ui.hide_gui;
-        shown.then_some(View {
+        if self.title.is_some() || self.ui.hide_gui {
+            return None;
+        }
+        let e = &self.settings.extras;
+        let (corner, size, rotate, blocks_per_pixel, round) = if e.minimap {
+            let size = f32::from(e.minimap_size);
+            (
+                e.minimap_corner,
+                size,
+                e.minimap_rotate,
+                e.minimap_zoom,
+                e.minimap_round,
+            )
+        } else {
+            let m = self.mod_minimap()?;
+            (m.corner, m.size, m.rotate, m.blocks_per_pixel, m.round)
+        };
+        let view = View {
             x: p.position.x,
             z: p.position.z,
             yaw: self.yaw,
-            rotate: e.minimap_rotate,
-            blocks_per_pixel: e.minimap_zoom,
-            round: e.minimap_round,
-        })
+            rotate,
+            blocks_per_pixel,
+            round,
+        };
+        Some((corner, size, view))
     }
     /// Refresh the minimap's tiles within the frame budget, recompose its
     /// image when the view or a tile changed, and queue the upload.
     fn update_minimap(&mut self) {
-        let Some(view) = self.minimap_view() else {
-            if !self.settings.extras.minimap || self.player.is_none() {
+        let Some((_, _, view)) = self.minimap_shown() else {
+            let wanted = self.settings.extras.minimap || self.mod_minimap().is_some();
+            if !wanted || self.player.is_none() {
                 self.extras.minimap.clear();
                 self.extras.minimap_dim = None;
             }
@@ -265,16 +284,15 @@ impl Game<'_> {
     /// The minimap and mods' corner panels, in the HUD layer (hidden with F1
     /// by the caller). The top left corner gives way to the debug screen.
     pub(super) fn draw_extras(&mut self, batch: &mut HudBatch) {
-        let e = &self.settings.extras;
         let mod_panels = self.mods.has_panels();
-        if !e.minimap && !mod_panels {
+        let map = self.minimap_shown();
+        if map.is_none() && !mod_panels {
             return;
         }
-        let (map_corner, map_size) = (e.minimap_corner, f32::from(e.minimap_size));
         let visible = |corner| !(self.debug && corner == Corner::TopLeft);
         let mut corners = Corners::new(batch.width, batch.height, self.effect_rows_height());
         let atlas = &self.gui.atlas;
-        if let Some(view) = self.minimap_view()
+        if let Some((map_corner, map_size, view)) = map
             && visible(map_corner)
             && !self.extras.minimap.image.is_empty()
             && let Some(image) = atlas.sprites.get(MINIMAP_SPRITE).copied()
diff --git a/crates/horizon-client/src/game/mod_input.rs b/crates/horizon-client/src/game/mod_input.rs
index 199669957..10faf6a81 100644
--- a/crates/horizon-client/src/game/mod_input.rs
+++ b/crates/horizon-client/src/game/mod_input.rs
@@ -28,6 +28,9 @@ impl Game<'_> {
     pub(super) fn mod_zoom(&self) -> Option<ModZoom> {
         None
     }
+    pub(super) fn mod_minimap(&self) -> Option<ModMinimap> {
+        None
+    }
 }
 
 /// A mod's zoom (`render.set-zoom`), clamped by the runtime.
@@ -38,6 +41,16 @@ pub(super) struct ModZoom {
     pub(super) turn: f32,
 }
 
+/// A mod's minimap (`render.set-minimap`), clamped by the runtime.
+#[derive(Clone, Copy)]
+pub(super) struct ModMinimap {
+    pub(super) corner: horizon_client::extras::Corner,
+    pub(super) size: f32,
+    pub(super) blocks_per_pixel: f32,
+    pub(super) rotate: bool,
+    pub(super) round: bool,
+}
+
 #[cfg(feature = "mods")]
 impl Game<'_> {
     /// The main hand's stack as `input` shows it; none when it is empty.
@@ -147,4 +160,22 @@ impl Game<'_> {
             turn: z.turn,
         })
     }
+    /// The minimap the first mod showing one asks for.
+    pub(super) fn mod_minimap(&self) -> Option<ModMinimap> {
+        use horizon_client::extras::Corner;
+        use horizon_mods::RenderCorner;
+        let m = self.mods.mods.minimap()?;
+        Some(ModMinimap {
+            corner: match m.corner {
+                RenderCorner::TopLeft => Corner::TopLeft,
+                RenderCorner::TopRight => Corner::TopRight,
+                RenderCorner::BottomLeft => Corner::BottomLeft,
+                RenderCorner::BottomRight => Corner::BottomRight,
+            },
+            size: m.size,
+            blocks_per_pixel: m.blocks_per_pixel,
+            rotate: m.rotate,
+            round: m.round,
+        })
+    }
 }
diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit
index 9088c0c39..5fbfafc24 100644
--- a/crates/horizon-mod-sdk/wit/horizon.wit
+++ b/crates/horizon-mod-sdk/wit/horizon.wit
@@ -364,6 +364,27 @@ interface render {
     /// wins) leave the camera vanilla's. With several mods, the strongest
     /// zoom counts.
     set-zoom: func(zoom: zoom);
+    record minimap {
+        corner: corner,
+        /// Its side in GUI pixels, 16 to 256.
+        size: f32,
+        /// World blocks per map pixel, 0.5 to 4; the map is 128 × 128 pixels.
+        blocks-per-pixel: f32,
+        /// The map turns with the player, who faces up, and an N on its rim
+        /// marks north. Otherwise north is up and the player's arrow turns.
+        rotate: bool,
+        /// Round, the corners left clear; otherwise square.
+        round: bool,
+    }
+    /// Shows a map of the world around the player in `corner`, stacked with
+    /// the game's overlays and the mods' panels, until the next call (none
+    /// hides it). It looks like a map item: vanilla's map colours with their
+    /// height shading and water depth, and the player's arrow. Underground,
+    /// under a roof and in the Nether it maps the floor around the player's
+    /// height. The game keeps the map's tiles and refreshes them within its
+    /// own frame budget; hidden, they are dropped. One map shows at a time:
+    /// the first loaded mod's.
+    set-minimap: func(minimap: option<minimap>);
 }
 
 /// What the game calls. Only the hooks `init` asks for are ever called.
diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs
index 0011fa99d..4dc334ea5 100644
--- a/crates/horizon-mods/src/runtime.rs
+++ b/crates/horizon-mods/src/runtime.rs
@@ -52,8 +52,9 @@ use render_bindings::horizon::mods::input;
 pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, ItemUse};
 /// What capability `render` asks the game to draw (WIT `interface render`).
 pub use render_bindings::horizon::mods::render::{
-    Corner as RenderCorner, FillShape, FrameRate, ItemShape, Point as RenderPoint, QuadShape,
-    Rect as RenderRect, Shape, SpriteShape, TextShape, Zoom as ModZoom,
+    Corner as RenderCorner, FillShape, FrameRate, ItemShape, Minimap as ModMinimap,
+    Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape, TextShape,
+    Zoom as ModZoom,
 };
 use render_bindings::{RenderHost, horizon::mods::render};
 
@@ -196,6 +197,8 @@ struct State {
     corner: Option<CornerPanel>,
     /// Capability `render`'s zoom, when the mod zooms.
     zoom: Option<ModZoom>,
+    /// Capability `render`'s minimap, when the mod shows one.
+    minimap: Option<ModMinimap>,
     input: InputState,
     /// Capability `storage`'s folder; made on first `set`.
     data_dir: PathBuf,
@@ -339,6 +342,7 @@ impl Mods {
             shapes: Vec::new(),
             corner: None,
             zoom: None,
+            minimap: None,
             input: InputState::default(),
             data_dir,
             storage_budget: STORAGE_WRITE_BUDGET,
@@ -684,6 +688,12 @@ impl Mods {
             .filter_map(|e| e.run.as_ref()?.store.data().zoom)
             .max_by(|a, b| a.factor.total_cmp(&b.factor))
     }
+    /// The minimap the first running mod shows (capability `render`).
+    pub fn minimap(&self) -> Option<ModMinimap> {
+        self.entries
+            .iter()
+            .find_map(|e| e.run.as_ref()?.store.data().minimap)
+    }
     fn inputs(&self) -> impl Iterator<Item = &InputState> {
         self.entries
             .iter()
@@ -1013,6 +1023,9 @@ const SHAKE_SECONDS: f32 = 10.0;
 /// or more, and turning never stops.
 const ZOOM_MAX: f32 = 10.0;
 const TURN_MIN: f32 = 0.05;
+/// `set-minimap`'s side in GUI pixels and its blocks per map pixel.
+const MINIMAP_SIZE: (f32, f32) = (16.0, 256.0);
+const MINIMAP_SCALE: (f32, f32) = (0.5, 4.0);
 
 /// A mod's corner panel: shapes in a `width` × `height` box the game
 /// places in `corner`, stacked with the other overlays.
@@ -1094,6 +1107,14 @@ impl render::Host for State {
             },
         });
     }
+    fn set_minimap(&mut self, minimap: Option<ModMinimap>) {
+        let finite = |v: f32, lo: f32, hi: f32| if v.is_finite() { v.clamp(lo, hi) } else { lo };
+        self.minimap = minimap.map(|m| ModMinimap {
+            size: finite(m.size, MINIMAP_SIZE.0, MINIMAP_SIZE.1),
+            blocks_per_pixel: finite(m.blocks_per_pixel, MINIMAP_SCALE.0, MINIMAP_SCALE.1),
+            ..m
+        });
+    }
     fn frame_stats(&mut self) -> FrameRate {
         let (fps, min, low) = self.snapshot.frame;
         FrameRate { fps, min, low }
diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs
index 8c6c9d451..0be4fa47d 100644
--- a/crates/horizon-mods/tests/sandbox.rs
+++ b/crates/horizon-mods/tests/sandbox.rs
@@ -633,6 +633,32 @@ fn render_zoom_is_clamped_and_the_strongest_counts() {
     assert_eq!(zoom(&mut mods, "x 0 1"), None);
 }
 
+#[test]
+fn render_minimap_is_clamped_and_hidden() {
+    let mut mods = load("horizon_mods_test_ui_guest.hmod");
+    let map = |mods: &mut Mods, args: &str| {
+        assert!(mods.command(&format!("minimap {args}")));
+        mods.minimap()
+            .map(|m| (m.corner, m.size, m.blocks_per_pixel, m.rotate, m.round))
+    };
+    assert!(mods.minimap().is_none());
+    let corner = horizon_mods::RenderCorner::BottomLeft;
+    assert_eq!(
+        map(&mut mods, "96 2 1 0"),
+        Some((corner, 96.0, 2.0, true, false))
+    );
+    // The side and the scale are clamped; NaN takes the smallest.
+    assert_eq!(
+        map(&mut mods, "999 0.1 0 1"),
+        Some((corner, 256.0, 0.5, false, true))
+    );
+    assert_eq!(
+        map(&mut mods, "x 9 0 0"),
+        Some((corner, 16.0, 4.0, false, false))
+    );
+    assert_eq!(map(&mut mods, "off"), None);
+}
+
 #[test]
 fn corner_panels_text_width_and_readings() {
     let mut mods = load("horizon_mods_test_ui_guest.hmod");
diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs
index 9bede11f9..3d4c66076 100644
--- a/crates/horizon-mods/tests/ui_guest/src/lib.rs
+++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs
@@ -96,6 +96,7 @@ impl Mod for Guest {
             "input_held",
             "input_wheel",
             "zoom",
+            "minimap",
             "corner",
             "readings",
         ]
@@ -198,6 +199,24 @@ impl Mod for Guest {
                     turn,
                 });
             }
+            // `minimap off`, or `minimap SIZE BLOCKS-PER-PIXEL ROTATE ROUND`.
+            "minimap" => {
+                let words: Vec<&str> = args.split(' ').collect();
+                let number = |i: usize| {
+                    words
+                        .get(i)
+                        .and_then(|w| w.parse().ok())
+                        .unwrap_or(f32::NAN)
+                };
+                let map = (args != "off").then(|| render::Minimap {
+                    corner: render::Corner::BottomLeft,
+                    size: number(0),
+                    blocks_per_pixel: number(1),
+                    rotate: words.get(2) == Some(&"1"),
+                    round: words.get(3) == Some(&"1"),
+                });
+                render::set_minimap(map);
+            }
             // Clamped to (1, 10); the two after it shake nothing.
             "render_shake" => {
                 render::shake(2.0, 99.0);
diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md
index a51fb904b..14c815958 100644
--- a/docs/api/mods-reference.md
+++ b/docs/api/mods-reference.md
@@ -390,6 +390,16 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun
 | `smooth` | `bool` | Ease in and out through the game's field-of-view easing, as the spyglass does, instead of at once. |
 | `turn` | `f32` | Mouse turning is multiplied by it while zoomed: 1 keeps the player's sensitivity, at least 0.05. |
 
+### record `minimap`
+
+| Field | Type | |
+| --- | --- | --- |
+| `corner` | `corner` |  |
+| `size` | `f32` | Its side in GUI pixels, 16 to 256. |
+| `blocks-per-pixel` | `f32` | World blocks per map pixel, 0.5 to 4; the map is 128 × 128 pixels. |
+| `rotate` | `bool` | The map turns with the player, who faces up, and an N on its rim marks north. Otherwise north is up and the player's arrow turns. |
+| `round` | `bool` | Round, the corners left clear; otherwise square. |
+
 | Function | Signature | What it does |
 | --- | --- | --- |
 | `set-hud` | `func(shapes: list<shape>)` | Replaces the mod's HUD shapes: up to 1024, drawn every frame in order over the HUD (after the hotbar, under chat and screens), hidden with the HUD (F1). An empty list removes them. |
@@ -400,6 +410,7 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun
 | `text-width` | `func(text: string) -> f32` | The width of one line of text in GUI pixels, in the HUD's font: exact for Latin letters (U+0000 to U+024F), 6 per other character. |
 | `frame-stats` | `func() -> frame-rate` | The game's frame counter, recomputed twice a second. |
 | `set-zoom` | `func(zoom: zoom)` | Zooms the camera until the next call (`factor` 1 ends it), only while playing: a screen opening or the spyglass's own view (which wins) leave the camera vanilla's. With several mods, the strongest zoom counts. |
+| `set-minimap` | `func(minimap: option<minimap>)` | Shows a map of the world around the player in `corner`, stacked with the game's overlays and the mods' panels, until the next call (none hides it). It looks like a map item: vanilla's map colours with their height shading and water depth, and the player's arrow. Underground, under a roof and in the Nether it maps the floor around the player's height. The game keeps the map's tiles and refreshes them within its own frame budget; hidden, they are dropped. One map shows at a time: the first loaded mod's. |
 
 ## `events`
 
diff --git a/docs/api/stability.md b/docs/api/stability.md
index d5bd0e545..5c1b32362 100644
--- a/docs/api/stability.md
+++ b/docs/api/stability.md
@@ -114,3 +114,7 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
   keys may consume too is decided before `input` becomes preview.
 - **`input`'s `wheel` event** is a new case in a variant the game sends, so it breaks mods built before it (allowed
   because `input` is experimental): an `input` mod that calls `poll` needs a rebuild against the new WIT.
+- **`render.set-minimap`** draws a map the game makes, not one a mod composes: reading the blocks around the player
+  for a map image costs too much through hook calls, so the game keeps the tiles (vanilla's map colours) and the mod
+  picks the corner, side, scale and shape. One map shows at a time, the first loaded mod's. It is a new function and a
+  new type, so mods built before it keep loading.
diff --git a/docs/mods.md b/docs/mods.md
index 556a77187..b94aac089 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -89,7 +89,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call |
 | `command` | `command` | `run(line)`: a vanilla command run as the player, with the player's permissions, after the hook returns (8 per call); mods' own commands are not run |
 | `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` |
-| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
+| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts); `set-minimap(minimap)`: a map of the world around the player in a corner, as a map item colours it (the floor underground and under roofs), square or round, turning with the player or north up, with the player's arrow; the game keeps its tiles within its own frame budget (one map at a time, the first loaded mod's). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` |
 | `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`. The player rebinds them on the mod's page in Options > Mods, where the game lists them first as Key Binds rows (click, then press a key or mouse button; Esc binds none), even for a mod without `ui`; the choice is kept in `horizon-mods.txt` (`key.<mod>.<name>:key.keyboard.z`) and wins over `register-key`'s default; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` |
 
 | Hook (export) | When |

From 6c3473c6e0b1eb69f05072c22a93ef33d22962bf Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:40:03 +0100
Subject: [PATCH 270/270] Official mod: Minimap

The minimap extra as a mod (mods/official/minimap): the extra's five
options on its settings page, kept in its storage with the extra's values
(corner, size, shape, zoom, rotate), and the map drawn by the game
through render.set-minimap, so it looks and costs the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                             |   7 ++
 Cargo.toml                             |   2 +-
 docs/mods.md                           |   3 +-
 mods/official/minimap/Cargo.toml       |  16 +++
 mods/official/minimap/horizon-mod.toml |   9 ++
 mods/official/minimap/src/lib.rs       | 135 +++++++++++++++++++++++++
 6 files changed, 170 insertions(+), 2 deletions(-)
 create mode 100644 mods/official/minimap/Cargo.toml
 create mode 100644 mods/official/minimap/horizon-mod.toml
 create mode 100644 mods/official/minimap/src/lib.rs

diff --git a/Cargo.lock b/Cargo.lock
index 1a2aad855..ae1738593 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2082,6 +2082,13 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "minimap"
+version = "1.0.0"
+dependencies = [
+ "horizon-mod-sdk",
+]
+
 [[package]]
 name = "minisign-verify"
 version = "0.3.0"
diff --git a/Cargo.toml b/Cargo.toml
index 259734b98..4d463654b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"]
-members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "crates/horizon-mod-sdk/examples/predator-missile", "mods/official/fps-overlay", "mods/official/keystrokes", "mods/official/zoom", "xtask"]
+members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mods/tests/ui_guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "crates/horizon-mod-sdk/examples/predator-missile", "mods/official/fps-overlay", "mods/official/keystrokes", "mods/official/minimap", "mods/official/zoom", "xtask"]
 resolver = "2"
 
 [workspace.package]
diff --git a/docs/mods.md b/docs/mods.md
index b94aac089..e13e362e5 100644
--- a/docs/mods.md
+++ b/docs/mods.md
@@ -15,7 +15,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
 | The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage, command, ui; tick, frame, chat and command hooks |
 | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
 | Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands |
-| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes, Zoom |
+| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes, Zoom, Minimap |
 | Runtime | `crates/horizon-mods` | wasmtime 48 LTS, component model |
 | Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / test / check`, and the registry's CI (`registry build / review / list`) |
 | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
@@ -490,6 +490,7 @@ so the same rustc and `Cargo.lock` give the same file.
 | FPS Counter | `fps_overlay` | Extras > FPS counter | `corner`: `top_left` (default), `top_right`, `bottom_left`, `bottom_right`; `lows`: `false` (default), `true` |
 | Keystrokes | `keystrokes` | Extras > Keystrokes | `corner`: as above, default `top_left`; `cps`: `true` (default), `false` |
 | Zoom | `zoom` | Extras > Zoom | `level`: `2`, `3`, `4` (default), `6`, `8`, `10`; `smooth`: `true` (default), `false`; `sensitivity` (slower turning): `true` (default), `false`. The key is the game's: `key.zoom.zoom` in `horizon-mods.txt`, default `key.keyboard.z` |
+| Minimap | `minimap` | Extras > Minimap | `corner`: as above, default `top_right`; `size`: `64`, `96` (default), `128`; `shape`: `square` (default), `round`; `zoom` (blocks per pixel): `0.5`, `1` (default), `2`, `4`; `rotate`: `false` (default), `true`. The game draws the map (`render.set-minimap`) |
 
 ## Versions and compatibility
 
diff --git a/mods/official/minimap/Cargo.toml b/mods/official/minimap/Cargo.toml
new file mode 100644
index 000000000..e6aafb7c4
--- /dev/null
+++ b/mods/official/minimap/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "minimap"
+version = "1.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+description = "Horizon's official minimap: a map of the terrain around you in a corner."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+horizon-mod-sdk = { path = "../../../crates/horizon-mod-sdk" }
+
+[lints]
+workspace = true
diff --git a/mods/official/minimap/horizon-mod.toml b/mods/official/minimap/horizon-mod.toml
new file mode 100644
index 000000000..51bd7ef94
--- /dev/null
+++ b/mods/official/minimap/horizon-mod.toml
@@ -0,0 +1,9 @@
+id = "minimap"
+name = "Minimap"
+version = "1.0.0"
+description = "A map of the terrain around you in a corner, in map colours, square or round, north up or turning with you. Horizon's own, formerly an extra."
+authors = ["Horizon"]
+api = "0.1"
+side = "client"
+capabilities = ["render", "ui", "storage"]
+experimental = ["render", "ui"]
diff --git a/mods/official/minimap/src/lib.rs b/mods/official/minimap/src/lib.rs
new file mode 100644
index 000000000..ea8c45b72
--- /dev/null
+++ b/mods/official/minimap/src/lib.rs
@@ -0,0 +1,135 @@
+//! Horizon's official minimap, formerly the built-in extra: a map of the
+//! terrain around the player in a corner (`render.set-minimap`; the game
+//! keeps its tiles). Its settings page has the extra's five options, kept in
+//! the mod's storage (`corner`, `size`, `shape`, `zoom`, `rotate`) with the
+//! extra's values, where the game writes a player's old extra settings when
+//! it installs the mod for them.
+use horizon_mod_sdk::{
+    Mod, Registration,
+    render::{self, Corner, Minimap as MapView},
+    storage,
+    ui::{self, ButtonWidget, Widget},
+};
+
+/// (corner, stored value, label), in the extra's order.
+const CORNERS: [(Corner, &str, &str); 4] = [
+    (Corner::TopLeft, "top_left", "Top left"),
+    (Corner::TopRight, "top_right", "Top right"),
+    (Corner::BottomLeft, "bottom_left", "Bottom left"),
+    (Corner::BottomRight, "bottom_right", "Bottom right"),
+];
+/// (side in GUI pixels, label).
+const SIZES: [(u8, &str); 3] = [(64, "Small"), (96, "Medium"), (128, "Large")];
+/// Blocks per map pixel.
+const ZOOMS: [f32; 4] = [0.5, 1.0, 2.0, 4.0];
+/// Settings page buttons.
+const CORNER_BUTTON: u32 = 1;
+const SIZE_BUTTON: u32 = 2;
+const SHAPE_BUTTON: u32 = 3;
+const ZOOM_BUTTON: u32 = 4;
+const ROTATE_BUTTON: u32 = 5;
+
+/// Indexes into the tables above, and the two switches.
+struct Minimap {
+    corner: usize,
+    size: usize,
+    round: bool,
+    zoom: usize,
+    rotate: bool,
+}
+
+impl Minimap {
+    fn show(&self) {
+        render::set_minimap(Some(MapView {
+            corner: CORNERS[self.corner].0,
+            size: f32::from(SIZES[self.size].0),
+            blocks_per_pixel: ZOOMS[self.zoom],
+            rotate: self.rotate,
+            round: self.round,
+        }));
+    }
+    fn page(&self) {
+        let button = |id, label: String| Widget::Button(ButtonWidget { id, label });
+        let n = ZOOMS[self.zoom];
+        let blocks = if n < 1.0 {
+            "½ block".to_owned()
+        } else if n == 1.0 {
+            "1 block".to_owned()
+        } else {
+            format!("{n} blocks")
+        };
+        ui::set_settings(&[
+            button(CORNER_BUTTON, format!("Corner: {}", CORNERS[self.corner].2)),
+            button(SIZE_BUTTON, format!("Size: {}", SIZES[self.size].1)),
+            button(
+                SHAPE_BUTTON,
+                format!("Shape: {}", if self.round { "Round" } else { "Square" }),
+            ),
+            button(ZOOM_BUTTON, format!("Zoom: {blocks} per pixel")),
+            button(
+                ROTATE_BUTTON,
+                format!(
+                    "Turn with the player: {}",
+                    if self.rotate { "ON" } else { "OFF" }
+                ),
+            ),
+        ]);
+    }
+    fn save(&self) {
+        let _ = storage::set("corner", CORNERS[self.corner].1.as_bytes());
+        let _ = storage::set("size", SIZES[self.size].0.to_string().as_bytes());
+        let _ = storage::set("shape", if self.round { b"round" } else { b"square" });
+        let _ = storage::set("zoom", ZOOMS[self.zoom].to_string().as_bytes());
+        let _ = storage::set("rotate", if self.rotate { b"true" } else { b"false" });
+    }
+}
+
+fn stored(key: &str) -> Option<String> {
+    storage::get(key)
+        .and_then(|v| String::from_utf8(v).ok())
+        .map(|v| v.trim().to_owned())
+}
+
+impl Mod for Minimap {
+    fn init() -> Result<(Self, Registration), String> {
+        // The extra's defaults: top right, medium, square, 1 block per
+        // pixel, north up. An unknown value keeps the default.
+        let find = |key: &str, values: &[String], default: usize| {
+            stored(key)
+                .and_then(|v| values.iter().position(|s| *s == v))
+                .unwrap_or(default)
+        };
+        let corners: Vec<String> = CORNERS.iter().map(|c| c.1.to_owned()).collect();
+        let sizes: Vec<String> = SIZES.iter().map(|s| s.0.to_string()).collect();
+        let zooms: Vec<String> = ZOOMS.iter().map(f32::to_string).collect();
+        let map = Minimap {
+            corner: find("corner", &corners, 1),
+            size: find("size", &sizes, 1),
+            round: stored("shape").as_deref() == Some("round"),
+            zoom: find("zoom", &zooms, 1),
+            rotate: stored("rotate").as_deref() == Some("true"),
+        };
+        map.show();
+        map.page();
+        Ok((map, Registration::new()))
+    }
+    fn ui_select(&mut self, id: u32, _row: u32) {
+        let next = |i: usize, n: usize| (i + 1) % n;
+        match id {
+            CORNER_BUTTON => self.corner = next(self.corner, CORNERS.len()),
+            SIZE_BUTTON => self.size = next(self.size, SIZES.len()),
+            SHAPE_BUTTON => self.round = !self.round,
+            ZOOM_BUTTON => self.zoom = next(self.zoom, ZOOMS.len()),
+            ROTATE_BUTTON => self.rotate = !self.rotate,
+            _ => return,
+        }
+        self.save();
+        self.show();
+        self.page();
+    }
+    fn ui_settings_opened(&mut self) {
+        self.page();
+    }
+}
+
+horizon_mod_sdk::export_mod!(Minimap);