diff --git a/benchmarks/entity-model-document-2026-10-14/README.md b/benchmarks/entity-model-document-2026-10-14/README.md new file mode 100644 index 000000000..eeb8f6673 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/README.md @@ -0,0 +1,78 @@ +# Entity model document loading + +The three startup batches (boats/chest boats, minecarts, armor stands/player armor) +now share one parsed document. For this fixture, that replaces 43 full document +reads/parses (boat discovery plus 42 selected layers) with one. Selected models +still produce independent `Part` trees; the document is dropped after the batches +are built. Other entity loaders retain their existing behavior. + +## Reproduce + +From the repository root: + +```sh +python3 benchmarks/entity-model-document-2026-10-14/generate_fixture.py /tmp/horizon-entity-model-document-fixture.json +ENTITY_MODEL_BENCH_DOCUMENT=/tmp/horizon-entity-model-document-fixture.json \ + CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo test -p horizon-client --profile fast --bin horizon-client \ + entity_model_document_benchmark -- --ignored --nocapture +``` + +`CARGO_TARGET_DIR` is optional and can be changed for another machine. Supply a +prepared `entity-models.json` through `ENTITY_MODEL_BENCH_DOCUMENT` to benchmark +that document instead; the harness copies only that file to a temporary root. +`ENTITY_MODEL_BENCH_REPETITIONS` controls repetitions (default 15). + +The opt-in Rust test calls the actual three optimized production loaders and +compares every selected part name, pose, polygon normal/vertex and child against +the previous algorithm using the compatible per-model `load_model` API. Timings +include reading, parsing, constructing, normalizing into a common result map, and +dropping the result. Each variant gets three warmups and 15 measured calls, with +order alternating. `black_box` consumes inputs/results. No other builds or +optimization benchmarks ran during the measured calls. + +## Input and limitations + +Prepared resources were unavailable in the repository and local Horizon asset +directories. This is a **synthetic** 2,473,695-byte document with 458 model layers, +each containing 12 posed parts with six exported quads and normals. It selects 22 +boat/chest-boat layers, six minecart layers and 14 armor/player layers (42 total). +One wood name is synthetic (`test_wood`); boat discovery accepts arbitrary wood +names. The extra layers model the cost of parsing a full production-size document +for each selected model. + +File data is warm in the OS page cache. Equipment files are absent, so equipment +texture loading is excluded. This measures the entity-model batch only and does +not establish overall startup, frame time or FPS improvement. Shapes/layer counts +in real prepared documents can produce different absolute timings. + +Machine: AMD Ryzen 5 5600X (6 cores / 12 threads), Linux x86_64, +Rust 1.99.0 (b940084d7, LLVM 23.1.1), Cargo `fast` profile (opt-level 3, +16 codegen units, no LTO). Baseline algorithm corresponds to main +`73a019967e9665c6b96332988c13cb66679d8477`. + +## Results + +| Variant | Median batch time | Full document reads/parses | +| --- | ---: | ---: | +| Previous per-model algorithm | 1,434.974 ms | 43 | +| Shared document | 33.420 ms | 1 | + +The measured batch is **42.94× faster** on this synthetic input. All 15 samples +for both variants, warmup count, document size and selected model count are in +[`results.json`](results.json). + +## Validation + +```sh +cargo fmt --all -- --check +CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo test -p horizon-client --profile fast --bin horizon-client \ + entity_model_loading_tests -- --nocapture +CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo clippy -p horizon-client --profile fast --lib --bin horizon-client --tests -- -D warnings +``` + +The regular tests cover full/sparse documents, unrelated layers, a missing file, +invalid JSON, non-object JSON, missing model keys, independent model trees, and +equipment loading when the document is unavailable. diff --git a/benchmarks/entity-model-document-2026-10-14/generate_fixture.py b/benchmarks/entity-model-document-2026-10-14/generate_fixture.py new file mode 100644 index 000000000..624a7abe1 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/generate_fixture.py @@ -0,0 +1,31 @@ +"""Generate a production-size synthetic document; no prepared assets required.""" +import json +import pathlib +import sys + +woods = "oak spruce birch jungle acacia dark_oak mangrove cherry bamboo pale_oak test_wood".split() +carts = "minecart chest_minecart hopper_minecart furnace_minecart tnt_minecart command_block_minecart".split() +keys = [f"minecraft:{prefix}/{wood}#main" for prefix in ("boat", "chest_boat") for wood in woods] +keys += [f"minecraft:{cart}#main" for cart in carts] +keys += [f"minecraft:{model}#{slot}" for model in ("player", "armor_stand", "armor_stand_small") + for slot in ("helmet", "chestplate", "leggings", "boots")] +keys += [f"minecraft:{model}#main" for model in ("armor_stand", "armor_stand_small")] + +face = [[0, 0, 0, 0, 0], [16, 0, 0, 1, 0], [16, 16, 0, 1, 1], [0, 16, 0, 0, 1]] +part = {"pose": [1, 2, 3, 0.25, -0.5, 0.75, 1, 1, 1], "polygons": [face] * 6, + "normals": [[0, 0, 1]] * 6} +model = {"pose": [0, 0, 0, 0, 0, 0, 1, 1, 1], + "children": {f"part_{i}": part for i in range(12)}} +encoded = json.dumps(model, separators=(",", ":")) +entries = [json.dumps(key) + ":" + encoded for key in keys] +size = 2 + sum(map(len, entries)) + len(entries) - 1 +index = 0 +while size < 2_470_000: + entry = json.dumps(f"minecraft:fixture_{index}#main") + ":" + encoded + entries.append(entry) + size += 1 + len(entry) + index += 1 +output = pathlib.Path(sys.argv[1]) +output.write_text("{" + ",".join(entries) + "}") +print(json.dumps({"path": str(output), "bytes": output.stat().st_size, + "layers": len(entries), "selected_layers": len(keys)})) diff --git a/benchmarks/entity-model-document-2026-10-14/results.json b/benchmarks/entity-model-document-2026-10-14/results.json new file mode 100644 index 000000000..1ef0c6576 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/results.json @@ -0,0 +1,43 @@ +{ + "baseline_median_ms": 1434.973835, + "baseline_ms": [ + 1400.008286, + 1406.761694, + 1408.9131360000001, + 1418.6680549999999, + 1419.149658, + 1427.082872, + 1433.088092, + 1434.973835, + 1449.7688150000001, + 1452.143883, + 1453.987998, + 1455.518231, + 1457.0334540000001, + 1458.588552, + 1485.34133 + ], + "document_bytes": 2473695, + "optimized_median_ms": 33.419768000000005, + "optimized_ms": [ + 32.64795, + 32.812732, + 33.054488, + 33.056914, + 33.102999000000004, + 33.23532, + 33.28287, + 33.419768000000005, + 33.610569, + 33.874749, + 33.915657, + 33.93877, + 34.009893999999996, + 34.550526, + 36.096408000000004 + ], + "repetitions": 15, + "selected_models": 42, + "speedup": 42.937875421516985, + "warmup_pairs": 3 +} diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 242b221a8..61563b3c6 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -9323,6 +9323,15 @@ pub fn run() -> Result<()> { player_arm: horizon_client::mobs::load_model(&root, "minecraft:player#main") .and_then(|m| m.children.into_iter().find(|c| c.name == "right_arm")), }; + // These batches share the exported document instead of reparsing it per layer. + let (armor_stand_assets, boat_models, cart_models) = { + let document = horizon_client::mobs::EntityModelDocument::load(&root).ok(); + ( + armor_stands::ArmorStandAssets::load(&root, document.as_ref()), + boats::BoatModels::load(document.as_ref()), + minecarts::CartModels::load(document.as_ref()), + ) + }; let inventory = vec![None; 36]; let now = Instant::now(); let game_root = options.resources.clone(); @@ -9494,9 +9503,9 @@ pub fn run() -> Result<()> { glow_map_frame_model: frames::bake_frame(&root, "glow_item_frame_map"), armor_stands: Vec::new(), others: Vec::new(), - armor_stand_assets: armor_stands::ArmorStandAssets::load(&root), + armor_stand_assets, boats: Vec::new(), - boat_models: boats::BoatModels::load(&root), + boat_models, crystal_model: horizon_client::mobs::load_model(&root, "minecraft:end_crystal#main"), carts: Vec::new(), jukebox_sounds: HashMap::new(), @@ -9515,7 +9524,7 @@ pub fn run() -> Result<()> { .join("assets/skins"), ), skin_slots: Vec::new(), - cart_models: minecarts::CartModels::load(&root), + cart_models, riding: None, ender_items: vec![None; 27], ender_open: None, @@ -9682,6 +9691,9 @@ mod runtime_reset_tests { } } +#[cfg(test)] +mod entity_model_loading_tests; + #[cfg(test)] mod tests { use super::*; diff --git a/crates/horizon-client/src/game/armor_stands.rs b/crates/horizon-client/src/game/armor_stands.rs index dfc6adfd8..94e9422ed 100644 --- a/crates/horizon-client/src/game/armor_stands.rs +++ b/crates/horizon-client/src/game/armor_stands.rs @@ -27,8 +27,11 @@ pub(super) struct ArmorStandAssets { pub equipment: HashMap)>>, } impl ArmorStandAssets { - pub fn load(root: &std::path::Path) -> Self { - let load = |key: &str| horizon_client::mobs::load_model(root, key); + pub fn load( + root: &std::path::Path, + document: Option<&horizon_client::mobs::EntityModelDocument>, + ) -> Self { + let load = |key: &str| document.and_then(|document| document.model(key)); let mut layers = HashMap::new(); let mut player = HashMap::new(); for slot in ["helmet", "chestplate", "leggings", "boots"] { diff --git a/crates/horizon-client/src/game/boats.rs b/crates/horizon-client/src/game/boats.rs index b31127e1e..5f2897c67 100644 --- a/crates/horizon-client/src/game/boats.rs +++ b/crates/horizon-client/src/game/boats.rs @@ -151,25 +151,22 @@ impl BoatModels { self.models.contains_key(wood) } } - pub fn load(root: &std::path::Path) -> Self { + pub fn load(document: Option<&horizon_client::mobs::EntityModelDocument>) -> Self { let mut models = HashMap::new(); let mut chest_models = HashMap::new(); - if let Ok(bytes) = std::fs::read(root.join("entity-models.json")) - && let Ok(serde_json::Value::Object(all)) = - serde_json::from_slice::(&bytes) - { - for key in all.keys() { + if let Some(document) = document { + for key in document.keys() { if let Some(wood) = key .strip_prefix("minecraft:boat/") .and_then(|k| k.strip_suffix("#main")) - && let Some(part) = horizon_client::mobs::load_model(root, key) + && let Some(part) = document.model(key) { models.insert(wood.to_owned(), part); } if let Some(wood) = key .strip_prefix("minecraft:chest_boat/") .and_then(|k| k.strip_suffix("#main")) - && let Some(part) = horizon_client::mobs::load_model(root, key) + && let Some(part) = document.model(key) { chest_models.insert(wood.to_owned(), part); } diff --git a/crates/horizon-client/src/game/entity_model_loading_tests.rs b/crates/horizon-client/src/game/entity_model_loading_tests.rs new file mode 100644 index 000000000..61ed81491 --- /dev/null +++ b/crates/horizon-client/src/game/entity_model_loading_tests.rs @@ -0,0 +1,272 @@ +//! Model-batch equivalence tests and an opt-in benchmark of the actual loaders. +use super::{armor_stands::ArmorStandAssets, boats::BoatModels, minecarts::CartModels}; +use horizon_client::mobs::{EntityModelDocument, Part, load_model}; +use serde_json::{Value, json}; +use std::{collections::BTreeMap, fs, hint::black_box, path::Path, time::Instant}; + +const WOODS: [&str; 11] = [ + "oak", + "spruce", + "birch", + "jungle", + "acacia", + "dark_oak", + "mangrove", + "cherry", + "bamboo", + "pale_oak", + "test_wood", +]; +const CARTS: [&str; 6] = [ + "minecart", + "chest_minecart", + "hopper_minecart", + "furnace_minecart", + "tnt_minecart", + "command_block_minecart", +]; + +fn fixture() -> Value { + let mut all = serde_json::Map::new(); + let part = json!({ + "pose": [1,2,3,0.25,-0.5,0.75,1,2,0.5], + "polygons": [[[0,0,0,0,0],[1,0,0,1,0],[1,1,0,1,1],[0,1,0,0,1]]], + "normals": [[0,0,1]], + "children": {"root": {"children": {"bone": {"pose": [4,5,6]}}}, "other": {}} + }); + for wood in WOODS { + for prefix in ["boat", "chest_boat"] { + all.insert(format!("minecraft:{prefix}/{wood}#main"), part.clone()); + } + } + for cart in CARTS { + all.insert(format!("minecraft:{cart}#main"), part.clone()); + } + for model in ["player", "armor_stand", "armor_stand_small"] { + for layer in ["helmet", "chestplate", "leggings", "boots"] { + all.insert(format!("minecraft:{model}#{layer}"), part.clone()); + } + } + for model in ["armor_stand", "armor_stand_small"] { + all.insert(format!("minecraft:{model}#main"), part.clone()); + } + // Discovery must exclude other models and non-main boat layers. + all.insert("minecraft:boat/oak#water_patch".into(), part.clone()); + all.insert("minecraft:unrelated#main".into(), part); + Value::Object(all) +} + +struct FixtureRoot(std::path::PathBuf); +impl FixtureRoot { + fn new() -> Self { + static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + let next = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + let root = std::env::temp_dir().join(format!( + "horizon-entity-models-{}-{next}", + std::process::id() + )); + fs::create_dir(&root).unwrap(); + Self(root) + } +} +impl Drop for FixtureRoot { + fn drop(&mut self) { + fs::remove_dir_all(&self.0).unwrap(); + } +} + +// Preserve the previous production algorithm: one discovery parse, then a full +// file read/parse through load_model for each of the 42 selected layers. +fn baseline(root: &Path) -> BTreeMap { + let mut models = BTreeMap::new(); + if let Ok(bytes) = fs::read(root.join("entity-models.json")) + && let Ok(Value::Object(all)) = serde_json::from_slice::(&bytes) + { + for key in all.keys() { + for (prefix, label) in [ + ("minecraft:boat/", "boat"), + ("minecraft:chest_boat/", "chest_boat"), + ] { + if let Some(wood) = key + .strip_prefix(prefix) + .and_then(|k| k.strip_suffix("#main")) + && let Some(part) = load_model(root, key) + { + models.insert(format!("{label}/{wood}"), part); + } + } + } + } + for cart in CARTS { + if let Some(part) = load_model(root, &format!("minecraft:{cart}#main")) { + models.insert(format!("cart/{cart}"), part); + } + } + for slot in ["helmet", "chestplate", "leggings", "boots"] { + for model in ["player", "armor_stand", "armor_stand_small"] { + if let Some(part) = load_model(root, &format!("minecraft:{model}#{slot}")) { + models.insert(format!("{model}/{slot}"), part); + } + } + } + // The fixture contains only entity-models.json; armor equipment is absent. + let _ = fs::read_dir(root.join("assets/minecraft/equipment")); + for model in ["armor_stand", "armor_stand_small"] { + if let Some(part) = load_model(root, &format!("minecraft:{model}#main")) { + models.insert(format!("{model}/main"), part); + } + } + models +} + +fn optimized(root: &Path) -> BTreeMap { + let document = EntityModelDocument::load(root).ok(); + let boats = BoatModels::load(document.as_ref()); + let carts = CartModels::load(document.as_ref()); + let armor = ArmorStandAssets::load(root, document.as_ref()); + let mut models = BTreeMap::new(); + for (label, group) in [("boat", boats.models), ("chest_boat", boats.chest_models)] { + for (wood, part) in group { + models.insert(format!("{label}/{wood}"), part); + } + } + for (kind, part) in carts.models { + models.insert( + format!("cart/{}", kind.id().trim_start_matches("minecraft:")), + part, + ); + } + for ((slot, small), part) in armor.layers { + let model = if small { + "armor_stand_small" + } else { + "armor_stand" + }; + models.insert(format!("{model}/{slot}"), part); + } + for (slot, part) in armor.player { + models.insert(format!("player/{slot}"), part); + } + for (model, part) in [ + ("armor_stand", armor.main), + ("armor_stand_small", armor.small), + ] { + if let Some(part) = part { + models.insert(format!("{model}/main"), part); + } + } + models +} + +fn assert_equivalent(root: &Path) { + // Debug includes every part name, pose, polygon normal/vertex and child. + assert_eq!( + format!("{:?}", baseline(root)), + format!("{:?}", optimized(root)) + ); +} + +#[test] +fn entity_model_batches_preserve_parts_missing_layers_and_load_failures() { + let root = FixtureRoot::new(); + assert_equivalent(&root.0); // missing file + let file = root.0.join("entity-models.json"); + for bytes in [b"{".as_slice(), b"null", b"[]", b"{}"] { + fs::write(&file, bytes).unwrap(); + assert_equivalent(&root.0); + } + let mut all = fixture(); + fs::write(&file, serde_json::to_vec(&all).unwrap()).unwrap(); + assert_equivalent(&root.0); + assert_eq!(optimized(&root.0).len(), 42); + all.as_object_mut() + .unwrap() + .remove("minecraft:armor_stand_small#main"); + all.as_object_mut() + .unwrap() + .remove("minecraft:boat/oak#main"); + fs::write(&file, serde_json::to_vec(&all).unwrap()).unwrap(); + assert_equivalent(&root.0); + assert_eq!(optimized(&root.0).len(), 40); + let document = EntityModelDocument::load(&root.0).unwrap(); + let mut first = document.model("minecraft:armor_stand#main").unwrap(); + first.children.clear(); + assert!( + !document + .model("minecraft:armor_stand#main") + .unwrap() + .children + .is_empty() + ); +} + +#[test] +fn armor_equipment_loads_without_an_entity_model_document() { + let root = FixtureRoot::new(); + let equipment = root.0.join("assets/minecraft/equipment"); + fs::create_dir_all(&equipment).unwrap(); + fs::write( + equipment.join("leather.json"), + serde_json::to_vec(&json!({"layers": {"humanoid": [{ + "texture": "minecraft:leather", "dyeable": {"color_when_undyed": 0x123456} + }]}})) + .unwrap(), + ) + .unwrap(); + fs::write(equipment.join("invalid.json"), b"{").unwrap(); + let assets = ArmorStandAssets::load(&root.0, None); + assert!(assets.main.is_none()); + assert!(assets.layers.is_empty()); + assert_eq!( + assets.equipment["minecraft:leather"]["humanoid"], + ("entity/equipment/humanoid/leather".into(), Some(0x123456)) + ); + assert!(!assets.equipment.contains_key("minecraft:invalid")); +} + +#[test] +#[ignore = "opt-in benchmark; requires ENTITY_MODEL_BENCH_DOCUMENT"] +fn entity_model_document_benchmark() { + let input = std::env::var("ENTITY_MODEL_BENCH_DOCUMENT").unwrap(); + let root = FixtureRoot::new(); + let bytes = fs::read(&input).unwrap(); + fs::write(root.0.join("entity-models.json"), &bytes).unwrap(); + assert_equivalent(&root.0); + let model_count = optimized(&root.0).len(); + let repetitions: usize = std::env::var("ENTITY_MODEL_BENCH_REPETITIONS") + .unwrap_or_else(|_| "15".into()) + .parse() + .unwrap(); + assert!(repetitions > 0); + for _ in 0..3 { + black_box(baseline(black_box(&root.0))); + black_box(optimized(black_box(&root.0))); + } + let mut before = Vec::new(); + let mut after = Vec::new(); + for i in 0..repetitions { + for optimized_first in [i % 2 == 0, i % 2 != 0] { + let started = Instant::now(); + if optimized_first { + black_box(optimized(black_box(&root.0))); + after.push(started.elapsed().as_secs_f64() * 1000.0); + } else { + black_box(baseline(black_box(&root.0))); + before.push(started.elapsed().as_secs_f64() * 1000.0); + } + } + } + before.sort_by(f64::total_cmp); + after.sort_by(f64::total_cmp); + let old = before[repetitions / 2]; + let new = after[repetitions / 2]; + println!( + "{}", + json!({ + "document_bytes": bytes.len(), "selected_models": model_count, + "warmup_pairs": 3, "repetitions": repetitions, + "baseline_ms": before, "optimized_ms": after, + "baseline_median_ms": old, "optimized_median_ms": new, "speedup": old / new + }) + ); +} diff --git a/crates/horizon-client/src/game/minecarts.rs b/crates/horizon-client/src/game/minecarts.rs index b81d09325..47b1ab053 100644 --- a/crates/horizon-client/src/game/minecarts.rs +++ b/crates/horizon-client/src/game/minecarts.rs @@ -191,7 +191,7 @@ pub(super) struct CartModels { pub models: HashMap, } impl CartModels { - pub fn load(root: &std::path::Path) -> Self { + pub fn load(document: Option<&horizon_client::mobs::EntityModelDocument>) -> Self { let kinds = [ CartKind::Rideable, CartKind::Chest, @@ -202,9 +202,7 @@ impl CartModels { ]; let models = kinds .into_iter() - .filter_map(|k| { - horizon_client::mobs::load_model(root, &format!("{}#main", k.id())).map(|m| (k, m)) - }) + .filter_map(|k| document?.model(&format!("{}#main", k.id())).map(|m| (k, m))) .collect(); Self { models } } diff --git a/crates/horizon-client/src/mobs.rs b/crates/horizon-client/src/mobs.rs index b2b63626e..1c1ac82a8 100644 --- a/crates/horizon-client/src/mobs.rs +++ b/crates/horizon-client/src/mobs.rs @@ -1767,11 +1767,33 @@ pub fn render( ) { render::render_single(mob, alpha, camera, uv, light, out); } +/// A parsed `entity-models.json` document, shared while loading model batches. +/// Each lookup still constructs an independent part tree for the caller. +pub struct EntityModelDocument(Value); + +impl EntityModelDocument { + pub fn load(root: &Path) -> crate::Result { + Ok(Self(serde_json::from_slice(&fs::read( + root.join("entity-models.json"), + )?)?)) + } + + pub fn model(&self, key: &str) -> Option { + self.0.get(key).map(|m| Part::parse("root", m)) + } + + pub fn keys(&self) -> impl Iterator { + self.0 + .as_object() + .into_iter() + .flat_map(|all| all.keys().map(String::as_str)) + } +} + /// Load one baked model layer from `entity-models.json` (e.g. `minecraft:chest#main`). +/// Batch loaders should share an `EntityModelDocument` instead. pub fn load_model(root: &Path, key: &str) -> Option { - let models: Value = - serde_json::from_slice(&fs::read(root.join("entity-models.json")).ok()?).ok()?; - models.get(key).map(|m| Part::parse("root", m)) + EntityModelDocument::load(root).ok()?.model(key) } /// ModelPart.render: translate, rotate ZYX, scale, then children. pub fn render_model(