diff --git a/benchmarks/model-state-parse-2026-10-14.md b/benchmarks/model-state-parse-2026-10-14.md new file mode 100644 index 000000000..15a50e8ff --- /dev/null +++ b/benchmarks/model-state-parse-2026-10-14.md @@ -0,0 +1,69 @@ +# Reuse parsed model states + +`models::prepare` parsed `model-states.json` to select blocks, then +`StateModels::load` reopened and parsed the same document for binding and baking. +`StateModels::from_facts` now borrows the first parsed map. The public `load` +entry point still reads, parses and validates its own document. Both paths retain +the `fs::read` + `serde_json::from_slice` strategy merged in PR #205. + +The shared map uses `BTreeMap`, preserving the original catalog loader's JSON +validation, including rejection of top-level `null`. The old selection map was +`serde_json::Map`, also backed by a BTreeMap with the project's current features. +Catalog binding, model selection and baking are unchanged. Preparation no longer +holds a second complete JSON tree while constructing the catalog; no persistent +cache or extra clones were added. + +## Measurement + +The committed `model_states_bench` example runs main's two-parse sequence after PR #205 +(first a serde JSON map, then `StateModels::load`) and the new one-parse sequence +(first a BTreeMap, then `StateModels::from_facts`). Both select blocks from the +same generated document with slice parsing and call the actual catalog binding/baking code. Timing +includes file reads, parsing, filtering, binding, baking and result destruction. +Fixture generation and equality checks run outside the timed region. + +Prepared Minecraft resources were unavailable locally, so this is a synthetic +2,836,696-byte document containing 843 block schemas and 53,952 states. Schemas +combine integer and named properties. Blockstate resources use weighted and +conditional multipart choices with rotations and UV locking, sharing one model +with a baked face. Its absent texture uses the normal missing-sprite fallback. +Both paths read identical files with a warm OS cache. The workload does not +represent the full diversity of production model and texture assets. + +On AMD Ryzen 5 5600X, Linux 7.2.8-zen1-2-zen x86_64, rustc 1.99.0 +(b940084d7 2026-09-28), Cargo `fast` profile, serial execution: + +| Path | Median (15 samples) | +| --- | ---: | +| Before: parse twice, with #205 slice readers | 96.080 ms | +| After: reuse first parse, with #205 slice readers | 73.585 ms | + +**1.306x speedup; 23.41% less elapsed time** for this loading segment after PR #205. Each path +has two warmups, sample order alternates, and inputs/results use `black_box`. +This excludes gallery placements, GPU work and overall application startup. + +These measurements supersede the original unbuffered-reader timings +(2732.004 ms → 1386.060 ms, 1.971x) after rebasing onto main at +`e96e1571`. The reviewer measured approximately 1.05x with real prepared resources; +the generated fixture's balance of parsing and binding differs from production. +The change still removes one complete document read, parse and JSON tree. + +Equality validation compares every state's selected variants and baked geometry +at three positions, plus sprite layers and opacity/translucency flags. The +focused test also checks matching schema/registry errors, malformed/missing +source files, rejection of `null`, and successful shared-facts loading after the +source file has been deleted. + +## Reproduce + +```sh +export CARGO_TARGET_DIR=/home/bob/Documents/horizon/target +export CARGO_INCREMENTAL=0 +cargo run -p horizon-client --profile fast --example model_states_bench -- 15 +cargo test -p horizon-client --profile fast --example model_states_bench +cargo clippy -p horizon-client --all-targets --profile fast -- -D warnings +cargo fmt --all -- --check +``` + +The target directory can be changed for another machine. The example creates and +removes its fixtures in the system temporary directory. diff --git a/crates/horizon-client/examples/model_states_bench.rs b/crates/horizon-client/examples/model_states_bench.rs new file mode 100644 index 000000000..577ff649e --- /dev/null +++ b/crates/horizon-client/examples/model_states_bench.rs @@ -0,0 +1,291 @@ +//! Compare the old two-parse loading path with catalog construction from shared facts. +//! Run: cargo run -p horizon-client --profile fast --example model_states_bench -- 15 +use horizon_client::{Result, models::StateModels, sprites::Sprites}; +use horizon_core::position::BlockPos; +use horizon_world::{ + DATA_VERSION, + chunk::BlockState, + nbt::Tag, + registry::{BlockRegistry, BlockStateId}, +}; +use serde_json::{Value, json}; +use std::{collections::BTreeMap, fs, hint::black_box, path::PathBuf, time::Instant}; + +struct Fixture { + root: PathBuf, + registry: BlockRegistry, + bytes: usize, + blocks: usize, +} +impl Fixture { + fn new(target_bytes: usize) -> Result { + let root = + std::env::temp_dir().join(format!("horizon-model-states-{}", std::process::id())); + fs::create_dir_all(root.join("assets/minecraft/blockstates"))?; + fs::create_dir_all(root.join("assets/minecraft/models/block"))?; + let mut possible = Vec::new(); + for age in 0..8 { + for facing in ["north", "south", "east", "west"] { + for waterlogged in ["false", "true"] { + possible.push( + json!({"age":age.to_string(), "facing":facing, "waterlogged":waterlogged}), + ); + } + } + } + let fact = json!({"schema":{ + "age":{"integer":[0,7]}, + "facing":{"named":["north","south","east","west"]}, + "waterlogged":{"named":["false","true"]} + },"states":possible}); + let blocks = (target_bytes / (serde_json::to_vec(&fact)?.len() + 26)).max(1); + let mut facts = BTreeMap::new(); + let mut states = Vec::new(); + let mut defaults = BTreeMap::new(); + for i in 0..blocks { + let block = format!("fixture_{i:04}"); + let name = format!("minecraft:{block}"); + defaults.insert(name.as_str().into(), Tag::Int(states.len() as i32)); + for properties in &possible { + let state = BlockState { + name: name.clone(), + properties: serde_json::from_value(properties.clone())?, + }; + states.push(state.to_nbt()); + } + facts.insert(name, fact.clone()); + fs::write( + root.join(format!("assets/minecraft/blockstates/{block}.json")), + r#"{"multipart":[{"apply":[{"model":"minecraft:block/fixture","weight":2},{"model":"minecraft:block/fixture","y":90,"weight":1}]},{"when":{"waterlogged":"true"},"apply":{"model":"minecraft:block/fixture","y":180,"uvlock":true}}]}"#, + )?; + } + fs::write( + root.join("assets/minecraft/models/block/fixture.json"), + r##"{"textures":{"all":"minecraft:block/fixture"},"elements":[{"from":[0,0,0],"to":[16,16,16],"faces":{"north":{"texture":"#all","cullface":"north"}}}]}"##, + )?; + let document = serde_json::to_vec(&facts)?; + let bytes = document.len(); + fs::write(root.join("model-states.json"), document)?; + let registry = BlockRegistry::from_nbt(&Tag::compound([ + ("DataVersion", Tag::Int(DATA_VERSION)), + ("states", Tag::List(states)), + ("defaults", Tag::Compound(defaults)), + ]))?; + Ok(Self { + root, + registry, + bytes, + blocks, + }) + } + fn facts(&self) -> Result> { + Ok(serde_json::from_slice(&fs::read( + self.root.join("model-states.json"), + )?)?) + } + fn block_names<'a>(&self, names: impl Iterator) -> Vec<&'a str> { + names + .filter(|name| self.registry.default_state(name).is_some()) + .filter_map(|name| name.strip_prefix("minecraft:")) + .collect() + } + fn load(&self, reuse: bool) -> Result<(StateModels, Sprites)> { + // The first parse and block filtering match models::prepare in both paths. + let mut sprites = Sprites::default(); + let catalog = if reuse { + let facts = self.facts()?; + let blocks = self.block_names(facts.keys()); + StateModels::from_facts(&self.root, &self.registry, &blocks, &mut sprites, &facts)? + } else { + let facts: serde_json::Map = + serde_json::from_slice(&fs::read(self.root.join("model-states.json"))?)?; + let blocks = self.block_names(facts.keys()); + StateModels::load(&self.root, &self.registry, &blocks, &mut sprites)? + }; + Ok((catalog, sprites)) + } + fn verify(&self) -> Result<()> { + let (before, before_sprites) = self.load(false)?; + let (after, after_sprites) = self.load(true)?; + assert_eq!(before_sprites.layers, after_sprites.layers); + assert_eq!(before_sprites.opaque, after_sprites.opaque); + assert_eq!(before_sprites.translucent, after_sprites.translucent); + for id in 0..self.registry.len() { + for position in [ + BlockPos::new(0, 0, 0), + BlockPos::new(12, -4, 7), + BlockPos::new(42, 9, -19), + ] { + let a = before.collect(BlockStateId(id as u32), position)?; + let b = after.collect(BlockStateId(id as u32), position)?; + assert_eq!(a.len(), b.len()); + for ((av, am), (bv, bm)) in a.into_iter().zip(b) { + assert_eq!(av, bv); + assert_eq!(am.ambient_occlusion, bm.ambient_occlusion); + assert_eq!(am.cube, bm.cube); + assert_eq!(am.faces.len(), bm.faces.len()); + for (af, bf) in am.faces.iter().zip(&bm.faces) { + assert_eq!(af.quad, bf.quad); + assert_eq!( + (af.layer, af.opaque, af.translucent), + (bf.layer, bf.opaque, bf.translucent) + ); + } + } + } + } + Ok(()) + } +} +impl Drop for Fixture { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.root); + } +} +fn median(values: &mut [f64]) -> f64 { + values.sort_by(f64::total_cmp); + values[values.len() / 2] +} +fn main() -> Result<()> { + let repetitions: usize = std::env::args() + .nth(1) + .map(|s| s.parse()) + .transpose()? + .unwrap_or(15); + if repetitions == 0 { + return Err("repetitions must be positive".into()); + } + let fixture = Fixture::new(2_840_000)?; + fixture.verify()?; + for _ in 0..2 { + for reuse in [false, true] { + drop(black_box(fixture.load(reuse)?)); + } + } + let mut before = Vec::new(); + let mut after = Vec::new(); + for iteration in 0..repetitions { + // Alternate order to limit cache/order bias. Both paths use slice parsing. + for reuse in if iteration % 2 == 0 { + [false, true] + } else { + [true, false] + } { + let started = Instant::now(); + drop(black_box(fixture.load(black_box(reuse))?)); + let ms = started.elapsed().as_secs_f64() * 1000.0; + if reuse { + after.push(ms); + } else { + before.push(ms); + } + } + } + let before = median(&mut before); + let after = median(&mut after); + println!( + "fixture: {} bytes, {} blocks, {} states; equality: all states at 3 positions", + fixture.bytes, + fixture.blocks, + fixture.registry.len() + ); + println!( + "2 warmups/path, {repetitions} samples/path; median before {before:.3} ms, after {after:.3} ms; {:.3}x speedup ({:.2}% less time)", + before / after, + (1.0 - after / before) * 100.0 + ); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn shared_facts_match_load_and_preserve_errors() -> Result<()> { + let fixture = Fixture::new(1)?; + fixture.verify()?; + let mut facts = fixture.facts()?; + let blocks = ["fixture_0000"]; + let load_error = |facts: &BTreeMap| -> Result { + fs::write( + fixture.root.join("model-states.json"), + serde_json::to_vec(facts)?, + )?; + let a = StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + ) + .err() + .ok_or("expected load error")? + .to_string(); + let b = StateModels::from_facts( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + facts, + ) + .err() + .ok_or("expected shared facts error")? + .to_string(); + assert_eq!(a, b); + Ok(a) + }; + let good = facts.clone(); + facts.clear(); + assert_eq!(load_error(&facts)?, "missing block model state schema"); + facts = good.clone(); + facts.get_mut("minecraft:fixture_0000").unwrap()["schema"] = Value::Null; + assert_eq!(load_error(&facts)?, "invalid model schema"); + facts = good.clone(); + facts.get_mut("minecraft:fixture_0000").unwrap()["states"] + .as_array_mut() + .unwrap() + .reverse(); + assert_eq!( + load_error(&facts)?, + "model state definitions disagree with the imported block registry" + ); + fs::remove_file(fixture.root.join("model-states.json"))?; + // A parsed document remains usable without reopening its source file. + StateModels::from_facts( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + &good, + )?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + fs::write(fixture.root.join("model-states.json"), b"null")?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + fs::write(fixture.root.join("model-states.json"), b"{")?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + Ok(()) + } +} diff --git a/crates/horizon-client/src/models.rs b/crates/horizon-client/src/models.rs index b593c1f66..7d1419087 100644 --- a/crates/horizon-client/src/models.rs +++ b/crates/horizon-client/src/models.rs @@ -55,14 +55,14 @@ pub fn prepare( registry: &BlockRegistry, sprites: &mut Sprites, ) -> Result { - let facts: serde_json::Map = + let facts: std::collections::BTreeMap = serde_json::from_slice(&std::fs::read(root.join("model-states.json"))?)?; let blocks: Vec<&str> = facts .keys() .filter(|name| registry.default_state(name).is_some()) .filter_map(|name| name.strip_prefix("minecraft:")) .collect(); - let catalog = StateModels::load(root, registry, &blocks, sprites)?; + let catalog = StateModels::from_facts(root, registry, &blocks, sprites, &facts)?; let mut placements = Vec::new(); let mut states = Vec::new(); for (index, (name, properties)) in GALLERY.iter().enumerate() { diff --git a/crates/horizon-client/src/models/catalog.rs b/crates/horizon-client/src/models/catalog.rs index d39d19a49..53a035b4d 100644 --- a/crates/horizon-client/src/models/catalog.rs +++ b/crates/horizon-client/src/models/catalog.rs @@ -57,6 +57,16 @@ impl StateModels { ) -> Result { let facts: BTreeMap = serde_json::from_slice(&fs::read(root.join("model-states.json"))?)?; + Self::from_facts(root, registry, blocks, sprites, &facts) + } + /// Bind and bake models using an already parsed model-state document. + pub fn from_facts( + root: &Path, + registry: &BlockRegistry, + blocks: &[&str], + sprites: &mut Sprites, + facts: &BTreeMap, + ) -> Result { let mut choices = Vec::new(); let mut states = BTreeMap::new(); let mut variants = BTreeSet::new();