diff --git a/crates/horizon-assets/src/resolve.rs b/crates/horizon-assets/src/resolve.rs index 6a12744e1..896d679dc 100644 --- a/crates/horizon-assets/src/resolve.rs +++ b/crates/horizon-assets/src/resolve.rs @@ -50,29 +50,47 @@ impl ModelLibrary { /// A library that also knows `builtin/generated`, the parent of every /// flat item model; the native client registers it as a special model. pub fn with_item_generator(mut models: BTreeMap) -> Result { - models.insert( - GENERATED_MODEL.to_owned(), - CuboidModel { - parent: None, - ambient_occlusion: None, - gui_light: Some(GuiLight::Front), - textures: BTreeMap::from([( - "particle".to_owned(), - TextureSlot::Reference("layer0".to_owned()), - )]), - elements: None, - display: None, - }, - ); + models.insert(GENERATED_MODEL.to_owned(), Self::item_generator_model()); Self::new(models) } + /// Register the item built-in while reusing already decoded resources. + pub fn with_shared_item_generator( + mut models: BTreeMap>, + ) -> Result { + models.insert( + GENERATED_MODEL.to_owned(), + Arc::new(Self::item_generator_model()), + ); + Self::from_shared(models) + } + fn item_generator_model() -> CuboidModel { + CuboidModel { + parent: None, + ambient_occlusion: None, + gui_light: Some(GuiLight::Front), + textures: BTreeMap::from([( + "particle".to_owned(), + TextureSlot::Reference("layer0".to_owned()), + )]), + elements: None, + display: None, + } + } pub fn new(models: BTreeMap) -> Result { + Self::from_models( + models + .into_iter() + .map(|(name, model)| (name, Arc::new(model))), + ) + } + /// Build an immutable resolution view without copying model geometry. + pub fn from_shared(models: BTreeMap>) -> Result { + Self::from_models(models) + } + fn from_models(models: impl IntoIterator)>) -> Result { let mut decoded = BTreeMap::new(); for (name, model) in models { - if decoded - .insert(identifier(&name)?, Arc::new(model)) - .is_some() - { + if decoded.insert(identifier(&name)?, model).is_some() { return Err(error("duplicate normalized model identifier")); } } diff --git a/crates/horizon-client/examples/model_library_bench.rs b/crates/horizon-client/examples/model_library_bench.rs new file mode 100644 index 000000000..d3aba51e0 --- /dev/null +++ b/crates/horizon-client/examples/model_library_bench.rs @@ -0,0 +1,129 @@ +//! Full block/assets + item startup. Compile with HORIZON_BENCH_COUNT_ALLOCATIONS=1 +//! for live requested heap bytes; leave it unset for latency measurements. +//! cargo run --profile fast -p horizon-client --example model_library_bench -- ROOT [--parity] +//! Run fresh processes, warm up twice, then compare multiple alternating baseline/candidate runs. +use horizon_client::{assets::Assets, item_render::ItemRenderer}; +use std::{ + alloc::{GlobalAlloc, Layout, System}, + hash::{Hash, Hasher}, + path::Path, + sync::atomic::{AtomicUsize, Ordering::Relaxed}, + time::Instant, +}; + +struct CountingAllocator; +const TRACK: bool = option_env!("HORIZON_BENCH_COUNT_ALLOCATIONS").is_some(); +static LIVE: AtomicUsize = AtomicUsize::new(0); +// The allocator delegates every operation and layout unchanged to System. +unsafe impl GlobalAlloc for CountingAllocator { + unsafe fn alloc(&self, layout: Layout) -> *mut u8 { + let ptr = unsafe { System.alloc(layout) }; + if TRACK && !ptr.is_null() { + LIVE.fetch_add(layout.size(), Relaxed); + } + ptr + } + unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { + let ptr = unsafe { System.alloc_zeroed(layout) }; + if TRACK && !ptr.is_null() { + LIVE.fetch_add(layout.size(), Relaxed); + } + ptr + } + unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { + if TRACK { + LIVE.fetch_sub(layout.size(), Relaxed); + } + unsafe { System.dealloc(ptr, layout) }; + } + unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, size: usize) -> *mut u8 { + let out = unsafe { System.realloc(ptr, layout, size) }; + if TRACK && !out.is_null() { + LIVE.fetch_sub(layout.size(), Relaxed); + LIVE.fetch_add(size, Relaxed); + } + out + } +} +#[global_allocator] +static ALLOCATOR: CountingAllocator = CountingAllocator; + +fn main() -> horizon_client::Result<()> { + let root = std::env::args() + .nth(1) + .ok_or("usage: model_library_bench ROOT [--parity]")?; + let root = Path::new(&root); + let initial = LIVE.load(Relaxed); + let start = Instant::now(); + let assets = Assets::load(root)?; + let block_ms = start.elapsed().as_secs_f64() * 1000.; + let block_retained = LIVE.load(Relaxed) - initial; + let start_items = Instant::now(); + let items = ItemRenderer::load_with_library(root, assets.model_library.clone())?; + let item_ms = start_items.elapsed().as_secs_f64() * 1000.; + let total_ms = start.elapsed().as_secs_f64() * 1000.; + let retained = LIVE.load(Relaxed) - initial; + println!( + "block_ms={block_ms:.3} item_ms={item_ms:.3} total_ms={total_ms:.3} retained_bytes={retained} block_retained_bytes={block_retained}" + ); + if std::env::args().any(|a| a == "--parity") { + let mut hash = std::collections::hash_map::DefaultHasher::new(); + for id in 0..assets.registry.len() { + let id = horizon_world::registry::BlockStateId(id as u32); + for pos in [ + horizon_core::position::BlockPos::new(0, 0, 0), + horizon_core::position::BlockPos::new(-17, 65, 31), + ] { + if let Ok(selected) = assets.model_catalog.collect(id, pos) { + for (variant, model) in selected { + format!("{variant:?}").hash(&mut hash); + model.ambient_occlusion.hash(&mut hash); + for face in &model.faces { + format!("{:?}", face.quad).hash(&mut hash); + face.layer.hash(&mut hash); + face.opaque.hash(&mut hash); + face.translucent.hash(&mut hash); + } + } + } + } + } + let mut names = Vec::new(); + for ns in std::fs::read_dir(root.join("assets"))? { + let ns = ns?; + let base = ns.path().join("models"); + let mut stack = vec![base.clone()]; + while let Some(dir) = stack.pop() { + let Ok(entries) = std::fs::read_dir(dir) else { + continue; + }; + for entry in entries { + let path = entry?.path(); + if path.is_dir() { + stack.push(path); + } else if path.extension().is_some_and(|e| e == "json") { + names.push(format!( + "{}:{}", + ns.file_name().to_string_lossy(), + path.strip_prefix(&base)? + .with_extension("") + .to_string_lossy() + .replace('\\', "/") + )); + } + } + } + } + names.sort(); + for name in &names { + format!("{:?}", items.bake(name)).hash(&mut hash); + } + println!( + "parity_models={} fingerprint={:016x}", + names.len(), + hash.finish() + ); + } + std::hint::black_box((&assets, &items)); + Ok(()) +} diff --git a/crates/horizon-client/src/assets.rs b/crates/horizon-client/src/assets.rs index df52de1ad..351d57d45 100644 --- a/crates/horizon-client/src/assets.rs +++ b/crates/horizon-client/src/assets.rs @@ -59,6 +59,8 @@ pub struct Assets { pub pixels: Vec, pub texture_layers: u32, pub model_catalog: crate::models::StateModels, + /// Shared parsed resources; item-only validation errors surface at item preparation. + pub model_library: std::result::Result, String>, pub model_placements: Vec<(horizon_core::position::BlockPos, BlockStateId)>, pub model_gallery: Vec, pub animations: Vec, @@ -219,7 +221,9 @@ impl Assets { for name in MATERIALS { sprites.insert(root, &format!("minecraft:block/{name}"))?; } - let models = crate::models::prepare(root, registry, &mut sprites)?; + let parsed = crate::model_library::ParsedModels::load(root); + let models = crate::models::prepare_with_models(root, registry, &mut sprites, &parsed)?; + let model_library = parsed.into_item_library(); // Fluids are drawn by the fluid renderer, not block models; breaking // progress uses the destroy-stage overlays. for name in [ @@ -244,6 +248,7 @@ impl Assets { texture_layers: u32::try_from(sprites.layers.len())?, pixels: sprites.pixels, model_catalog: models.catalog, + model_library, model_placements: models.placements, model_gallery: models.states, animations: sprites.animations, diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index f87d974e0..1324efa1e 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -9143,6 +9143,12 @@ pub fn run() -> Result<()> { let animate = horizon_client::animate_tick::AnimateTables::load(&root, registry_owner.registry, &biomes)?; let fog = horizon_client::fog::FogRenderer::load(&root, &biomes); + let item_renderer = Arc::new( + horizon_client::item_render::ItemRenderer::load_with_library( + &root, + assets.model_library.clone(), + )?, + ); let mut resources = Resources { stations, assets, @@ -9154,7 +9160,7 @@ pub fn run() -> Result<()> { environment, atlas, panorama, - item_renderer: Arc::new(horizon_client::item_render::ItemRenderer::load(&root)?), + item_renderer, layer_names, providers: Providers::load(&root), block_entity_render: horizon_client::block_entity_render::BlockEntityRenderer::load( diff --git a/crates/horizon-client/src/game/packs.rs b/crates/horizon-client/src/game/packs.rs index 0d3f8a74a..27e91200f 100644 --- a/crates/horizon-client/src/game/packs.rs +++ b/crates/horizon-client/src/game/packs.rs @@ -115,7 +115,10 @@ impl Game<'_> { let panorama = horizon_client::gfx::panorama::Faces::load(root); atlas.font.uniform = self.settings.force_unicode; atlas.font.japanese = self.settings.japanese_glyphs; - let item_renderer = horizon_client::item_render::ItemRenderer::load(root)?; + let item_renderer = horizon_client::item_render::ItemRenderer::load_with_library( + root, + assets.model_library.clone(), + )?; let visibility = horizon_client::models::load_visibility(root, assets.registry)?; let tables = std::sync::Arc::new(horizon_client::mesher::MeshTables::new( &assets, diff --git a/crates/horizon-client/src/item_render.rs b/crates/horizon-client/src/item_render.rs index 66246e4a9..45531bedd 100644 --- a/crates/horizon-client/src/item_render.rs +++ b/crates/horizon-client/src/item_render.rs @@ -22,7 +22,7 @@ use horizon_assets::{ ClientItem, Components, Context, DisplayContext, FoilType, ItemEnv, ItemModels, LayerContent, LevelState, OwnerState, SpecialModel, StackView, }, - model::{CuboidModel, Direction}, + model::Direction, palette::PalettedPermutations, resolve::{MISSING_MODEL, ModelLibrary}, }; @@ -370,7 +370,7 @@ impl FileSprites { /// The baked item models and everything resolution needs. pub struct ItemRenderer { pub models: ItemModels, - library: ModelLibrary, + library: Arc, sprites: FileSprites, baked: Mutex>>, extents: Mutex>>>, @@ -382,37 +382,6 @@ pub struct ItemRenderer { item_ids: HashMap, } -/// Every `models/**.json` of a namespace directory, by identifier. -fn load_models(root: &Path) -> BTreeMap { - let mut out = BTreeMap::new(); - let Ok(namespaces) = fs::read_dir(root.join("assets")) else { - return out; - }; - for ns in namespaces.flatten() { - let namespace = ns.file_name().to_string_lossy().into_owned(); - let base = ns.path().join("models"); - let mut stack = vec![base.clone()]; - while let Some(dir) = stack.pop() { - let Ok(entries) = fs::read_dir(&dir) else { - continue; - }; - for e in entries.flatten() { - let path = e.path(); - if path.is_dir() { - stack.push(path); - } else if path.extension().is_some_and(|x| x == "json") - && let Ok(rel) = path.strip_prefix(&base) - && let Ok(text) = fs::read_to_string(&path) - && let Ok(model) = CuboidModel::from_json(&text) - { - let rel = rel.with_extension("").to_string_lossy().replace('\\', "/"); - out.insert(format!("{namespace}:{rel}"), model); - } - } - } - } - out -} /// Every `items/*.json` client item definition, by identifier. fn load_definitions(root: &Path) -> BTreeMap { let mut out = BTreeMap::new(); @@ -445,14 +414,24 @@ impl ItemRenderer { /// Load item definitions, item prototypes (`items.json`), every model, /// the special renderers' entity models and the grass colormap. pub fn load(root: &Path) -> crate::Result { + Self::load_with_library( + root, + crate::model_library::ParsedModels::load(root).into_item_library(), + ) + } + /// Reuse the immutable models prepared with the block resources at `root`. + /// Defer item-only validation failures until after item definitions are loaded. + pub fn load_with_library( + root: &Path, + library: std::result::Result, String>, + ) -> crate::Result { let prototypes: BTreeMap = serde_json::from_slice(&fs::read(root.join("items.json"))?)?; let models = ItemModels { definitions: load_definitions(root), prototypes, }; - let library = ModelLibrary::with_item_generator(load_models(root)) - .map_err(|e| format!("item models: {e:?}"))?; + let library = library?; let permutations = PalettedPermutations::from_atlas( &fs::read_to_string(root.join("assets/minecraft/atlases/items.json")) .unwrap_or_default(), diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index 07ba1af2a..47a0d169d 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -93,6 +93,7 @@ pub mod mesher; pub mod minimap; pub mod mipmap; pub mod mobs; +mod model_library; pub mod models; pub mod motion; pub mod mouse; diff --git a/crates/horizon-client/src/model_library.rs b/crates/horizon-client/src/model_library.rs new file mode 100644 index 000000000..7f7852ad0 --- /dev/null +++ b/crates/horizon-client/src/model_library.rs @@ -0,0 +1,200 @@ +//! Parsed resource models for one startup or resource-pack reload. +use crate::Result; +use horizon_assets::{model::CuboidModel, resolve::ModelLibrary}; +use std::{collections::BTreeMap, fs, path::Path, sync::Arc}; + +#[derive(Default)] +pub(crate) struct ParsedModels { + models: BTreeMap>, +} +impl ParsedModels { + /// Every `models/**.json` of a namespace directory, by identifier. + pub(crate) fn load(root: &Path) -> Self { + let mut out = BTreeMap::new(); + let Ok(namespaces) = fs::read_dir(root.join("assets")) else { + return Self { models: out }; + }; + for ns in namespaces.flatten() { + let namespace = ns.file_name().to_string_lossy().into_owned(); + let base = ns.path().join("models"); + let mut stack = vec![base.clone()]; + while let Some(dir) = stack.pop() { + let Ok(entries) = fs::read_dir(&dir) else { + continue; + }; + for e in entries.flatten() { + let path = e.path(); + if path.is_dir() { + stack.push(path); + } else if path.extension().is_some_and(|x| x == "json") + && let Ok(rel) = path.strip_prefix(&base) + && let Ok(text) = fs::read_to_string(&path) + && let Ok(model) = CuboidModel::from_json(&text) + { + let rel = rel.with_extension("").to_string_lossy().replace('\\', "/"); + out.insert(format!("{namespace}:{rel}"), Arc::new(model)); + } + } + } + } + Self { models: out } + } + + /// Blocks require every referenced resource, including parents. Items instead + /// skip broken resources and use the resolver's missing-model fallback. + pub(crate) fn block_library( + &self, + root: &Path, + mut pending: Vec, + ) -> Result { + let mut models = BTreeMap::new(); + while let Some(name) = pending.pop() { + if models.contains_key(&name) { + continue; + } + let model = match self.models.get(&name) { + Some(model) => Arc::clone(model), + None => { + let (namespace, path) = + name.split_once(':').ok_or("invalid model identifier")?; + let text = fs::read_to_string( + root.join(format!("assets/{namespace}/models/{path}.json")), + )?; + Arc::new(CuboidModel::from_json(&text)?) + } + }; + if let Some(parent) = &model.parent { + pending.push(parent.clone()); + } + models.insert(name, model); + } + Ok(ModelLibrary::from_shared(models)?) + } + pub(crate) fn into_item_library(self) -> std::result::Result, String> { + ModelLibrary::with_shared_item_generator(self.models) + .map(Arc::new) + .map_err(|e| format!("item models: {e:?}")) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use horizon_assets::resolve::{GENERATED_MODEL, MISSING_MODEL}; + + struct Fixture(std::path::PathBuf); + impl Fixture { + fn write(&self, name: &str, json: &str) { + let (namespace, path) = name.split_once(':').unwrap(); + let path = self + .0 + .join(format!("assets/{namespace}/models/{path}.json")); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, json).unwrap(); + } + } + impl Drop for Fixture { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.0); + } + } + + #[test] + fn shared_views_preserve_resolution_errors_builtins_and_reload() -> Result<()> { + let fixture = Fixture( + std::env::temp_dir().join(format!("horizon-shared-models-{}", std::process::id())), + ); + fixture.write("horizon:parent", r##"{"textures":{"side":"#all","all":"block/stone"},"elements":[{"from":[0,0,0],"to":[16,8,16],"faces":{"up":{"texture":"#side"}}}]}"##); + fixture.write("horizon:nested/child", r#"{"parent":"horizon:parent","textures":{"all":"block/glass"},"display":{"gui":{"rotation":[30,45,0]}}}"#); + fixture.write("horizon:broken", "{"); + fixture.write("horizon:dangling", r#"{"parent":"horizon:absent"}"#); + fixture.write("horizon:a", r#"{"parent":"horizon:b"}"#); + fixture.write("horizon:b", r#"{"parent":"horizon:a"}"#); + fixture.write( + GENERATED_MODEL, + r#"{"elements":[{"from":[0,0,0],"to":[1,1,1],"faces":{"up":{"texture":"particle"}}}],"gui_light":"side"}"#, + ); + fixture.write(MISSING_MODEL, r#"{"elements":[]}"#); + let parsed = ParsedModels::load(&fixture.0); + let direct = ParsedModels::default(); + let names = vec![ + "horizon:nested/child".into(), + GENERATED_MODEL.into(), + MISSING_MODEL.into(), + "horizon:a".into(), + ]; + let old = direct.block_library(&fixture.0, names.clone())?; + let shared = parsed.block_library(&fixture.0, names)?; + for name in ["horizon:nested/child", GENERATED_MODEL, MISSING_MODEL] { + assert_eq!( + format!("{:?}", old.resolve(name)?), + format!("{:?}", shared.resolve(name)?) + ); + } + assert!(shared.resolve("horizon:a").is_err()); + for name in ["horizon:broken", "horizon:absent", "horizon:dangling"] { + let load = |models: &ParsedModels| { + models + .block_library(&fixture.0, vec![name.into()]) + .err() + .unwrap() + .to_string() + }; + assert_eq!(load(&direct), load(&parsed)); + } + let items = parsed.into_item_library()?; + let block = shared.resolve("horizon:nested/child")?; + let item = items.resolve("horizon:nested/child")?; + assert!(std::ptr::eq( + block.elements().as_ptr(), + item.elements().as_ptr() + )); + assert_eq!( + item.material("side")?.unwrap().sprite, + "minecraft:block/glass" + ); + assert_eq!(shared.resolve(GENERATED_MODEL)?.elements().len(), 1); + assert!(items.resolve(GENERATED_MODEL)?.elements().is_empty()); + assert!(items.resolve(GENERATED_MODEL)?.uses_item_generator()); + for name in [ + "horizon:broken", + "horizon:absent", + "horizon:dangling", + MISSING_MODEL, + ] { + assert_eq!(items.resolve(name)?.elements().len(), 1); + } + assert!(items.resolve("horizon:a").is_err()); + fixture.write("horizon:parent", r#"{"elements":[]}"#); + let reloaded = ParsedModels::load(&fixture.0).into_item_library()?; + assert!( + reloaded + .resolve("horizon:nested/child")? + .elements() + .is_empty() + ); + assert_eq!(items.resolve("horizon:nested/child")?.elements().len(), 1); + // An unrelated bad item identifier must not make block preparation fail + // (which would trigger resource-pack rollback at a different stage). + fixture.write("horizon:INVALID", "{}"); + let parsed = ParsedModels::load(&fixture.0); + assert!( + parsed + .block_library(&fixture.0, vec!["horizon:nested/child".into()]) + .is_ok() + ); + let library = parsed.into_item_library(); + assert!(library.is_err()); + fs::write(fixture.0.join("items.json"), "{")?; + let load = || { + crate::item_render::ItemRenderer::load_with_library(&fixture.0, library.clone()) + .err() + .unwrap() + .to_string() + }; + assert!(!load().starts_with("item models:")); + fs::write(fixture.0.join("items.json"), "{}")?; + assert!(load().starts_with("item models:")); + Ok(()) + } +} diff --git a/crates/horizon-client/src/models.rs b/crates/horizon-client/src/models.rs index b593c1f66..9ded08041 100644 --- a/crates/horizon-client/src/models.rs +++ b/crates/horizon-client/src/models.rs @@ -54,6 +54,19 @@ pub fn prepare( root: &Path, registry: &BlockRegistry, sprites: &mut Sprites, +) -> Result { + prepare_with_models( + root, + registry, + sprites, + &crate::model_library::ParsedModels::default(), + ) +} +pub(crate) fn prepare_with_models( + root: &Path, + registry: &BlockRegistry, + sprites: &mut Sprites, + models: &crate::model_library::ParsedModels, ) -> Result { let facts: serde_json::Map = serde_json::from_slice(&std::fs::read(root.join("model-states.json"))?)?; @@ -62,7 +75,7 @@ pub fn prepare( .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::load_with_models(root, registry, &blocks, sprites, models)?; 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..b3e0defe1 100644 --- a/crates/horizon-client/src/models/catalog.rs +++ b/crates/horizon-client/src/models/catalog.rs @@ -9,8 +9,6 @@ use horizon_assets::{ bind::{Properties, PropertySchema, PropertyValues, SelectedModels}, choice::CompiledChoices, }, - model::CuboidModel, - resolve::ModelLibrary, }; use horizon_core::{ position::BlockPos, @@ -54,6 +52,21 @@ impl StateModels { registry: &BlockRegistry, blocks: &[&str], sprites: &mut Sprites, + ) -> Result { + Self::load_with_models( + root, + registry, + blocks, + sprites, + &crate::model_library::ParsedModels::default(), + ) + } + pub(crate) fn load_with_models( + root: &Path, + registry: &BlockRegistry, + blocks: &[&str], + sprites: &mut Sprites, + models: &crate::model_library::ParsedModels, ) -> Result { let facts: BTreeMap = serde_json::from_slice(&fs::read(root.join("model-states.json"))?)?; @@ -156,22 +169,10 @@ impl StateModels { } choices.push(CompiledChoices::new(&definition)?); } - let mut models = BTreeMap::new(); - let mut pending: Vec<_> = variants.iter().map(|(name, _, _)| name.clone()).collect(); - while let Some(name) = pending.pop() { - if models.contains_key(&name) { - continue; - } - let (namespace, path) = name.split_once(':').ok_or("invalid model identifier")?; - let text = - fs::read_to_string(root.join(format!("assets/{namespace}/models/{path}.json")))?; - let model = CuboidModel::from_json(&text)?; - if let Some(parent) = &model.parent { - pending.push(parent.clone()); - } - models.insert(name, model); - } - let library = ModelLibrary::new(models)?; + let library = models.block_library( + root, + variants.iter().map(|(name, _, _)| name.clone()).collect(), + )?; let mut baked = BTreeMap::new(); for (name, turns, lock) in variants { let model = library.resolve(&name)?; diff --git a/docs/shared-model-library-benchmark.md b/docs/shared-model-library-benchmark.md new file mode 100644 index 000000000..1479fd417 --- /dev/null +++ b/docs/shared-model-library-benchmark.md @@ -0,0 +1,81 @@ +# Shared model library benchmark + +`model_library_bench` measures `Assets::load` followed by item preparation using +that asset snapshot. It includes filesystem traversal, JSON decoding, blockstate +binding, block model resolution/baking, sprite preparation, item definitions, +entity parts and item registry setup. Timing stops before the optional parity +probe. The Python driver's `wait4` resource accounting reports process peak RSS +on Linux. For latency runs, allocation tracking is compiled out. For separate +retained-memory runs, compile with `HORIZON_BENCH_COUNT_ALLOCATIONS=1`; the counting +system allocator reports live requested bytes after both loads. A zero +`retained_bytes` with tracking disabled is not a heap measurement. + +Use real prepared resources; no game files belong in Git. Build the baseline +at `89b58991bbc02eb79b6965fc4ca56357fe2297d9` with the benchmark example copied in +and `ItemRenderer::load(root)` in its item stage. Save that binary, then build +this branch with `ItemRenderer::load_with_library(root, assets.model_library.clone())`. +Both builds use `cargo build --locked --profile fast -p horizon-client --example +model_library_bench` with `HORIZON_BENCH_COUNT_ALLOCATIONS` unset (`opt-level=3`, LTO disabled, 16 codegen units). Set +`CARGO_BUILD_JOBS=2`. On the optimization machine, hold +`/tmp/horizon-optimizations-20261015-heavy.lock` for each entire build or paired +measurement session. Reuse a shared Cargo target only under that lock. + +```sh +flock /tmp/horizon-optimizations-20261015-heavy.lock \ + python3 tools/model_library_bench.py BASELINE_BINARY CANDIDATE_BINARY RESOURCE_ROOT +BASELINE_BINARY RESOURCE_ROOT --parity +CANDIDATE_BINARY RESOURCE_ROOT --parity +``` + +Run the parity probes under the same lock. The driver runs two warmups for each +binary, followed by ten samples per binary in alternating order. Every sample +uses a fresh process, including setup and allocation costs. Filesystem caches +are warm; these measurements do not represent cold disk, GPU initialization or +entire time to title. The library is built during asset preparation, so compare +the combined time rather than either stage alone. Block-only callers of +`Assets::load` now prepare and retain item models too; standalone +`ItemRenderer::load` remains available for callers without an asset snapshot. + +The optional parity probe hashes every bound registry state's selected variants +and baked block faces at two fixed positions, then every resource model's baked +item geometry, lighting, transforms and particle material. It complements the +synthetic test for malformed/missing parents, cycles, child overrides, built-in +models, shared geometry and reload isolation. It is a baseline comparison, not +a replacement for vanilla differential harnesses. + +## Results + +Prepared 26.3 resources contain 4,192 model JSON files. Both binaries use the +optimized `fast` profile and the same resource root on this Linux machine +(12 logical CPUs, 31 GiB RAM; rustc 1.99.0, b940084d7). Tracking is compiled out +for these ten samples. + +| Median | Baseline | Shared | +| --- | ---: | ---: | +| Assets (ms) | 450.1310 | 477.4105 | +| Items (ms) | 83.1180 | 36.2980 | +| Combined (ms) | 532.6055 | 514.1075 | +| Peak RSS (KiB) | 275440.0000 | 277018.0000 | + +Combined startup preparation improves by 18.4980 ms (3.47%). The +candidate is faster in all ten pairs. Stage medians do not necessarily add to +the median combined time. Peak RSS increases by 1578 KiB (0.57%). + +Combined sample times in milliseconds, in paired order: + +```text +baseline: 531.090, 528.995, 523.807, 534.564, 538.876, 529.148, 531.804, 533.407, 541.323, 539.934 +candidate: 514.767, 513.659, 514.896, 506.912, 516.291, 514.556, 510.443, 513.191, 510.017, 519.038 +``` + +Separate builds with allocation counting enabled report the same retained +requested heap in every sample: 129,921,272 versus 129,921,320 bytes (+48 bytes) +after both loaders. After assets alone, the values are +115,873,670 versus 122,249,411 bytes (+6.08 MiB). The shared models +are prepared earlier, so block-only asset consumers pay this retained-memory +and loading-time cost even when no item renderer follows. + +The baseline and current candidate resource probes both produce +`86a447cfd3f535c2` over all 4,192 item models and the block selections/faces at +two fixed positions. The focused test additionally preserves item-only error +timing, so invalid item identifiers do not change resource-pack rollback. diff --git a/tools/model_library_bench.py b/tools/model_library_bench.py new file mode 100644 index 000000000..1ea2ce8e7 --- /dev/null +++ b/tools/model_library_bench.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""Compare saved model_library_bench baseline/candidate binaries on prepared resources. + +Build both with the same profile, then run under the shared heavy-work lock: + python3 tools/model_library_bench.py BASELINE CANDIDATE RESOURCE_ROOT +Fresh processes include all asset/item setup. Two warmups per binary precede +10 alternating samples. Page caches are warm; this does not simulate cold disk. +""" +import argparse +import json +import os +from pathlib import Path +import re +import statistics +import subprocess +import tempfile + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("baseline", type=Path) + parser.add_argument("candidate", type=Path) + parser.add_argument("resources", type=Path) + args = parser.parse_args() + binaries = {name: str(getattr(args, name).resolve()) for name in ("baseline", "candidate")} + samples = {name: [] for name in binaries} + for iteration in range(12): + order = list(binaries) if iteration % 2 == 0 else list(reversed(binaries)) + for label in order: + with tempfile.TemporaryFile(mode="w+t") as output: + command = [binaries[label], str(args.resources)] + with subprocess.Popen(command, stdout=output, stderr=subprocess.STDOUT) as process: + _, status, usage = os.wait4(process.pid, 0) + process.returncode = os.waitstatus_to_exitcode(status) + output.seek(0) + text = output.read() + if process.returncode: + raise subprocess.CalledProcessError(process.returncode, command, text) + row = {key: float(value) for key, value in re.findall(r"(\w+)=([0-9.]+)", text)} + row["peak_rss_kib"] = usage.ru_maxrss + print(json.dumps({"iteration": iteration, "label": label, **row}), flush=True) + if iteration >= 2: + samples[label].append(row) + for label, rows in samples.items(): + print(label, json.dumps({key: { + "median": statistics.median(row[key] for row in rows), + "samples": [row[key] for row in rows], + } for key in rows[0]}), flush=True) + + +if __name__ == "__main__": + main()