Merge pull request #204 from rdbtCVS/perf/entity-model-document-20261014

perf(client): share parsed entity models across startup batches
This commit is contained in:
Ludovic Marie
2026-10-15 06:58:11 +02:00
committed by GitHub
9 changed files with 476 additions and 20 deletions
@@ -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.
@@ -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)}))
@@ -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
}
+15 -3
View File
@@ -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::*;
@@ -27,8 +27,11 @@ pub(super) struct ArmorStandAssets {
pub equipment: HashMap<String, HashMap<String, (String, Option<u32>)>>,
}
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"] {
+5 -8
View File
@@ -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::<serde_json::Value>(&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);
}
@@ -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<String, Part> {
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::<Value>(&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<String, Part> {
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
})
);
}
+2 -4
View File
@@ -191,7 +191,7 @@ pub(super) struct CartModels {
pub models: HashMap<CartKind, Part>,
}
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 }
}
+25 -3
View File
@@ -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<Self> {
Ok(Self(serde_json::from_slice(&fs::read(
root.join("entity-models.json"),
)?)?))
}
pub fn model(&self, key: &str) -> Option<Part> {
self.0.get(key).map(|m| Part::parse("root", m))
}
pub fn keys(&self) -> impl Iterator<Item = &str> {
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<Part> {
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(