From 9dbd93192f55dbbaa6878a1968ccc4c9072b8d8e Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Tue, 6 Oct 2026 20:10:30 +0200 Subject: [PATCH] Decode pinned cuboid models and verify native client semantics --- Cargo.lock | 7 + Cargo.toml | 2 +- .../scoped-parity.json | 37 ++ crates/horizon-assets/Cargo.toml | 10 + .../examples/cuboid_model_fixture.rs | 84 ++++ crates/horizon-assets/src/json.rs | 151 +++++++ crates/horizon-assets/src/lib.rs | 7 + crates/horizon-assets/src/model.rs | 394 ++++++++++++++++++ docs/native-client.md | 19 + docs/rust-parity.md | 4 + .../parity/VanillaCuboidModelOracle.java | 96 +++++ tools/test_cuboid_model_parity.py | 160 +++++++ 12 files changed, 970 insertions(+), 1 deletion(-) create mode 100644 benchmarks/rust-cuboid-model-decoding-2026-10-06/scoped-parity.json create mode 100644 crates/horizon-assets/Cargo.toml create mode 100644 crates/horizon-assets/examples/cuboid_model_fixture.rs create mode 100644 crates/horizon-assets/src/json.rs create mode 100644 crates/horizon-assets/src/lib.rs create mode 100644 crates/horizon-assets/src/model.rs create mode 100644 mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java create mode 100644 tools/test_cuboid_model_parity.py diff --git a/Cargo.lock b/Cargo.lock index 4bccbdd69..d9b9907be 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -574,6 +574,13 @@ version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284" +[[package]] +name = "horizon-assets" +version = "0.1.0" +dependencies = [ + "serde_json", +] + [[package]] name = "horizon-client" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index eceb96075..70cf54aba 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client"] +members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets"] resolver = "2" [workspace.package] diff --git a/benchmarks/rust-cuboid-model-decoding-2026-10-06/scoped-parity.json b/benchmarks/rust-cuboid-model-decoding-2026-10-06/scoped-parity.json new file mode 100644 index 000000000..c7d9db116 --- /dev/null +++ b/benchmarks/rust-cuboid-model-decoding-2026-10-06/scoped-parity.json @@ -0,0 +1,37 @@ +{ + "schema": 1, + "minecraft": "26.3", + "manifest_sha1": "4fe1aa1ef8da1cb95c5bad1fb98890ca56dd8ca3", + "platform": "Linux-7.0.0-31-generic-x86_64-with-glibc2.43", + "java": "openjdk 25.0.4.1 2026-08-18", + "rustc": "rustc 1.99.0 (b940084d7 2026-09-28)", + "resource_models": 2883, + "synthetic_models": 2337, + "rejected_models": 1034, + "sources_sha256": { + "mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java": "f6618f16614a47eb62b1cab40ebd514f075aa8590466a884f7e24e9f1844b065", + "tools/test_cuboid_model_parity.py": "3b7c018570b0f609aae43cef60ff3139c543d5d629be804a5aa257e3ab2dd67c", + "tools/lab.py": "d00bf107fa01b6c579734a082c3ca4ade3018f0d6851d46844acf17574f66e64", + "tools/test_rust_parity.py": "29d3db08005873528894b45ca10dcd6278753650473b3eb574e53e06ede40ec6", + "Cargo.toml": "3f93319c1eb70dbd7ba25cd74ef343fbf35c52c7c4752f955605c58699cbff9d", + "Cargo.lock": "7b4ab0ffa35af7ea8b6e38525f18ff6c3e94768198915f5ffe560d84263423f8", + "crates/horizon-assets/Cargo.toml": "fadb78cf819e026500606c45d27138ed67fcbbc967ae8cee6c1e7c82c9046b36", + "crates/horizon-assets/examples/cuboid_model_fixture.rs": "03e44a7040326660b9681e17a78de86d6f5ff295f1cbef69b6fcb64ab4282e8b", + "crates/horizon-assets/src/json.rs": "e7b89bf4852f561a0e5bf1a984857c61e755961dfd86fcc326b6d55558615f39", + "crates/horizon-assets/src/lib.rs": "3dbc77b4438dbc1d77e6fb9c61fccbc29fd14ac90a54d35c1518385765cbe13e", + "crates/horizon-assets/src/model.rs": "57ddb3d65e88e7a8aa22c62bc298a2dae7f4e994326a873a31f06c0f36ed051b" + }, + "fixtures_sha256": { + ".local/rust-cuboid-model-parity/inputs.jsonl": "9c1822180e1d6869e65eea81a38cbcf3786b9286d4c839e31ba686501694d171" + }, + "rust_output_sha256": "80c4b305084658ab968ed466fb1609bfa78d60738d09790c6243b4de27dfb8fc", + "references": [ + { + "side": "client", + "jar_sha256": "4508d006323f24fa02876310c192d739af56516eb259000ac50f0909a68c9a2d", + "output_sha256": "80c4b305084658ab968ed466fb1609bfa78d60738d09790c6243b4de27dfb8fc", + "matched_output_lines": 5220 + } + ], + "scope": "Actual pinned CuboidModel.fromStream parser compared over every bundled block model and synthetic JSON/numeric/syntax cases. Decoded geometry, texture materials/references, nullable children, inheritance markers, face quadrants, light emission and display transforms; floats compare by IEEE-754 bits. Rejections normalize exception text. This client-only API is absent from the server. Does not yet validate parent resolution, rotation matrices, quad baking, blockstate dispatch, rendered pixels or gameplay." +} diff --git a/crates/horizon-assets/Cargo.toml b/crates/horizon-assets/Cargo.toml new file mode 100644 index 000000000..c0e9f214d --- /dev/null +++ b/crates/horizon-assets/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "horizon-assets" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version.workspace = true +description = "Horizon version-specific model and resource decoding" + +[dependencies] +serde_json = { version = "1.0.151", features = ["raw_value"] } diff --git a/crates/horizon-assets/examples/cuboid_model_fixture.rs b/crates/horizon-assets/examples/cuboid_model_fixture.rs new file mode 100644 index 000000000..1d81cb218 --- /dev/null +++ b/crates/horizon-assets/examples/cuboid_model_fixture.rs @@ -0,0 +1,84 @@ +use horizon_assets::model::*; +use serde_json::{Value, json}; +use std::{ + collections::BTreeMap, + fs::File, + io::{BufRead, BufReader, BufWriter, Write}, +}; + +fn bits(values: [f32; N]) -> Vec { + values.map(f32::to_bits).to_vec() +} +fn transform(value: &DisplayTransform) -> Value { + match value { + DisplayTransform::Inherit => json!("inherit"), + DisplayTransform::Explicit(None) => Value::Null, + DisplayTransform::Explicit(Some(v)) => { + json!({"rotation":bits(v.rotation),"translation":bits(v.translation),"scale":bits(v.scale)}) + } + } +} +fn rotation(value: &ElementRotation) -> Value { + let angles = match value.value { + RotationValue::SingleAxis { axis, angle } => { + json!({"axis": match axis { Axis::X => "x", Axis::Y => "y", Axis::Z => "z" }, "angle":angle.to_bits()}) + } + RotationValue::EulerXyz(v) => json!(bits(v)), + }; + json!({"origin":bits(value.origin),"value":angles,"rescale":value.rescale}) +} +fn face(v: &Face) -> Value { + json!({"cull":v.cull.map(Direction::name),"tint":v.tint_index,"texture":v.texture,"rotation":v.rotation,"uv":v.uv.map(bits)}) +} +fn element(v: &Element) -> Value { + let faces: BTreeMap<_, _> = v + .faces + .iter() + .map(|(k, v)| (k.name(), v.as_ref().map(face))) + .collect(); + json!({"from":bits(v.from),"to":bits(v.to),"faces":faces,"rotation":v.rotation.as_ref().map(rotation),"shade":v.shade_direction_override.map(Direction::name),"light":v.light_emission}) +} +fn model(v: &CuboidModel) -> Value { + let textures: BTreeMap<_, _> = v + .textures + .iter() + .map(|(key, value)| { + ( + key, + match value { + TextureSlot::Reference(r) => json!({"reference":r}), + TextureSlot::Material(m) => { + json!({"sprite":m.sprite,"translucent":m.force_translucent}) + } + }, + ) + }) + .collect(); + let elements = v.elements.as_ref().map(|values| { + values + .iter() + .map(|v| v.as_ref().map(element)) + .collect::>() + }); + let display = v.display.as_ref().map(|v| { + DISPLAY_CONTEXTS + .into_iter() + .zip(v.contexts.iter().map(transform)) + .collect::>() + }); + json!({"parent":v.parent,"ao":v.ambient_occlusion,"gui":v.gui_light.map(|v| match v { GuiLight::Front => "front", GuiLight::Side => "side" }),"textures":textures,"elements":elements,"display":display}) +} +fn main() -> Result<(), Box> { + let args: Vec<_> = std::env::args().collect(); + let input = BufReader::new(File::open(&args[1])?); + let mut output = BufWriter::new(File::create(&args[2])?); + for line in input.lines() { + let row: Vec = serde_json::from_str(&line?)?; + let result = match CuboidModel::from_json(&row[1]) { + Ok(value) => json!({"name":row[0],"model":model(&value)}), + Err(_) => json!({"name":row[0],"error":true}), + }; + writeln!(output, "{result}")?; + } + Ok(()) +} diff --git a/crates/horizon-assets/src/json.rs b/crates/horizon-assets/src/json.rs new file mode 100644 index 000000000..4f6ed2594 --- /dev/null +++ b/crates/horizon-assets/src/json.rs @@ -0,0 +1,151 @@ +use serde_json::value::RawValue; +use std::{collections::BTreeMap, fmt}; + +#[derive(Debug)] +pub struct DecodeError(pub(crate) String); + +impl fmt::Display for DecodeError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} +impl std::error::Error for DecodeError {} +impl From for DecodeError { + fn from(value: serde_json::Error) -> Self { + Self(value.to_string()) + } +} +pub(crate) type Result = std::result::Result; +pub(crate) type Object<'a> = BTreeMap; +pub(crate) fn error(message: &str) -> DecodeError { + DecodeError(message.to_owned()) +} +/// The native reader recognizes numeric tokens only while they fit its 1024 +/// character lookahead buffer. This applies even in fields the model ignores. +pub(crate) fn validate_number_tokens(raw: &RawValue) -> Result<()> { + let mut quoted = false; + let mut escaped = false; + let mut length = 0; + for byte in raw.get().bytes() { + if quoted { + if escaped { + escaped = false; + } else if byte == b'\\' { + escaped = true; + } else if byte == b'"' { + quoted = false; + } + } else if byte == b'"' { + quoted = true; + length = 0; + } else if byte.is_ascii_digit() || b"-.eE+".contains(&byte) { + length += 1; + if length >= 1024 { + return Err(error("numeric token exceeds native reader buffer")); + } + } else { + length = 0; + } + } + Ok(()) +} +pub(crate) fn object(raw: &RawValue) -> Result> { + if !raw.get().starts_with('{') { + return Err(error("expected object")); + } + Ok(serde_json::from_str(raw.get())?) +} +pub(crate) fn array(raw: &RawValue) -> Result> { + Ok(serde_json::from_str(raw.get())?) +} +pub(crate) fn required<'a>(object: &Object<'a>, key: &str) -> Result<&'a RawValue> { + object + .get(key) + .copied() + .ok_or_else(|| error(&format!("missing {key}"))) +} +pub(crate) fn string(raw: &RawValue) -> Result { + Ok(serde_json::from_str(raw.get())?) +} +/// Gson's string helper accepts any primitive and preserves a number's spelling. +pub(crate) fn primitive_string(raw: &RawValue) -> Result { + match raw.get().as_bytes().first() { + Some(b'"') => string(raw), + Some(b't' | b'f' | b'-' | b'0'..=b'9') => Ok(raw.get().to_owned()), + _ => Err(error("expected primitive")), + } +} +pub(crate) fn boolean(raw: &RawValue) -> Result { + Ok(primitive_string(raw)?.eq_ignore_ascii_case("true")) +} +fn number(raw: &RawValue) -> Result<&str> { + match raw.get().as_bytes().first() { + Some(b'-' | b'0'..=b'9') => Ok(raw.get()), + _ => Err(error("expected number")), + } +} +pub(crate) fn float(raw: &RawValue) -> Result { + number(raw)?.parse().map_err(|_| error("invalid float")) +} +/// Gson LazilyParsedNumber.intValue truncates decimals then keeps the low 32 bits. +/// Work on decimal digits, avoiding f64 rounding and saturating Rust casts. +pub(crate) fn integer(raw: &RawValue) -> Result { + let raw = number(raw)?; + if raw.len() > 10_000 { + return Err(error("number string too long")); + } + let negative = raw.starts_with('-'); + let raw = raw.strip_prefix('-').unwrap_or(raw); + let (mantissa, exponent) = raw.split_once(['e', 'E']).unwrap_or((raw, "0")); + let exponent: i32 = exponent.parse().map_err(|_| error("invalid exponent"))?; + let fractional = mantissa.split_once('.').map_or(0, |(_, f)| f.len()); + let scale = + i64::try_from(fractional).map_err(|_| error("number too long"))? - i64::from(exponent); + if scale.abs() >= 10_000 { + return Err(error("unsupported decimal scale")); + } + let digits = mantissa.bytes().filter(|c| *c != b'.'); + let count = mantissa.len() - usize::from(mantissa.contains('.')); + let take = (count as i64 - scale.max(0)).max(0) as usize; + let mut value = 0u32; + for digit in digits.take(take) { + value = value.wrapping_mul(10).wrapping_add(u32::from(digit - b'0')); + } + if scale < 0 { + // 10^32 and larger are divisible by 2^32. + value = if scale <= -32 { + 0 + } else { + value.wrapping_mul(10u32.wrapping_pow((-scale) as u32)) + }; + } + Ok(if negative { + value.wrapping_neg() + } else { + value + } as i32) +} +pub(crate) fn vector(raw: &RawValue) -> Result<[f32; N]> { + let values = array(raw)?; + if values.len() != N { + return Err(error("wrong vector length")); + } + let mut result = [0.0; N]; + for (target, value) in result.iter_mut().zip(values) { + *target = float(value)?; + } + Ok(result) +} +pub(crate) fn identifier(name: &str) -> Result { + let (namespace, path) = name.split_once(':').unwrap_or(("minecraft", name)); + let namespace = if namespace.is_empty() { + "minecraft" + } else { + namespace + }; + let valid = |c: u8| c.is_ascii_lowercase() || c.is_ascii_digit() || b"_.-".contains(&c); + if !namespace.bytes().all(valid) || !path.bytes().all(|c| valid(c) || c == b'/') { + return Err(error("invalid resource identifier")); + } + Ok(format!("{namespace}:{path}")) +} diff --git a/crates/horizon-assets/src/lib.rs b/crates/horizon-assets/src/lib.rs new file mode 100644 index 000000000..2fa5fb89c --- /dev/null +++ b/crates/horizon-assets/src/lib.rs @@ -0,0 +1,7 @@ +//! Resource decoding for the pinned Java Edition client. +#![forbid(unsafe_code)] + +mod json; +pub mod model; + +pub use json::DecodeError; diff --git a/crates/horizon-assets/src/model.rs b/crates/horizon-assets/src/model.rs new file mode 100644 index 000000000..2e55f9a0f --- /dev/null +++ b/crates/horizon-assets/src/model.rs @@ -0,0 +1,394 @@ +//! The 26.3 cuboid model format, before parent resolution and quad baking. +//! +//! Absent geometry differs from an explicit empty element list. Explicit null +//! elements, faces and display transforms are retained as the native decoder +//! does; render preparation must diagnose these before baking. +use crate::json::*; +use serde_json::value::RawValue; +use std::collections::BTreeMap; + +#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub enum Direction { + Down, + Up, + North, + South, + West, + East, +} +impl Direction { + pub const ALL: [Self; 6] = [ + Self::Down, + Self::Up, + Self::North, + Self::South, + Self::West, + Self::East, + ]; + pub fn name(self) -> &'static str { + match self { + Self::Down => "down", + Self::Up => "up", + Self::North => "north", + Self::South => "south", + Self::West => "west", + Self::East => "east", + } + } + pub fn by_name(name: &str) -> Option { + Self::ALL + .into_iter() + .find(|direction| direction.name() == name) + } +} +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum GuiLight { + Front, + Side, +} +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Material { + pub sprite: String, + pub force_translucent: bool, +} +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum TextureSlot { + Reference(String), + Material(Material), +} +#[derive(Clone, Debug, PartialEq)] +pub struct CuboidModel { + pub parent: Option, + pub ambient_occlusion: Option, + pub gui_light: Option, + pub textures: BTreeMap, + pub elements: Option>>, + pub display: Option, +} +#[derive(Clone, Debug, PartialEq)] +pub struct Element { + pub from: [f32; 3], + pub to: [f32; 3], + pub faces: BTreeMap>, + pub rotation: Option, + pub shade_direction_override: Option, + pub light_emission: u8, +} +#[derive(Clone, Debug, PartialEq)] +pub struct Face { + pub cull: Option, + pub tint_index: i32, + pub texture: String, + pub uv: Option<[f32; 4]>, + /// Normalized counterclockwise quadrants, in the range 0..4. + pub rotation: u8, +} +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Axis { + X, + Y, + Z, +} +#[derive(Clone, Debug, PartialEq)] +pub enum RotationValue { + SingleAxis { axis: Axis, angle: f32 }, + EulerXyz([f32; 3]), +} +#[derive(Clone, Debug, PartialEq)] +pub struct ElementRotation { + /// Block units, converted from model coordinates during decoding. + pub origin: [f32; 3], + pub value: RotationValue, + pub rescale: bool, +} +#[derive(Clone, Debug, PartialEq)] +pub struct ItemTransform { + pub rotation: [f32; 3], + pub translation: [f32; 3], + pub scale: [f32; 3], +} +/// Missing transforms inherit later. Explicit identity and null values do not. +#[derive(Clone, Debug, PartialEq)] +pub enum DisplayTransform { + Inherit, + Explicit(Option), +} +pub const DISPLAY_CONTEXTS: [&str; 9] = [ + "thirdperson_lefthand", + "thirdperson_righthand", + "firstperson_lefthand", + "firstperson_righthand", + "head", + "gui", + "ground", + "fixed", + "on_shelf", +]; +#[derive(Clone, Debug, PartialEq)] +pub struct ItemTransforms { + pub contexts: [DisplayTransform; 9], +} + +impl CuboidModel { + /// Decode strict JSON, preserving the native parser's primitive coercions, + /// optional inheritance fields, nullable children and f32 conversion. + /// Like the native stream entry point, this reads one value and leaves + /// trailing input unread. The pinned native entry point uses strict JSON. + pub fn from_json(json: &str) -> Result { + let raw = serde_json::Deserializer::from_str(json.strip_prefix('\u{feff}').unwrap_or(json)) + .into_iter::<&RawValue>() + .next() + .ok_or_else(|| error("empty model input"))??; + validate_number_tokens(raw)?; + Self::decode(raw) + } + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let parent = obj + .get("parent") + .map(|r| primitive_string(r)) + .transpose()? + .unwrap_or_default(); + let parent = if parent.is_empty() { + None + } else { + Some(identifier(&parent)?) + }; + let ambient_occlusion = obj + .get("ambientocclusion") + .map(|r| boolean(r)) + .transpose()?; + let gui_light = obj + .get("gui_light") + .map(|raw| match primitive_string(raw)?.as_str() { + "front" => Ok(GuiLight::Front), + "side" => Ok(GuiLight::Side), + _ => Err(error("invalid gui light")), + }) + .transpose()?; + let mut textures = BTreeMap::new(); + if let Some(raw) = obj.get("textures") { + for (key, raw) in object(raw)? { + textures.insert(key, texture(raw)?); + } + } + let elements = obj + .get("elements") + .map(|raw| { + array(raw)? + .into_iter() + .map(|raw| nullable(raw, Element::decode)) + .collect::>>() + }) + .transpose()?; + let display = obj + .get("display") + .map(|r| ItemTransforms::decode(r)) + .transpose()?; + Ok(Self { + parent, + ambient_occlusion, + gui_light, + textures, + elements, + display, + }) + } +} +fn nullable(raw: &RawValue, decode: impl FnOnce(&RawValue) -> Result) -> Result> { + if raw.get() == "null" { + Ok(None) + } else { + decode(raw).map(Some) + } +} +fn texture(raw: &RawValue) -> Result { + if raw.get().starts_with('"') { + let name = string(raw)?; + if name.is_empty() { + return Err(error("empty texture slot value")); + } + if let Some(target) = name.strip_prefix('#') { + return Ok(TextureSlot::Reference(target.to_owned())); + } + return Ok(TextureSlot::Material(Material { + sprite: identifier(&name)?, + force_translucent: false, + })); + } + let obj = object(raw)?; + let sprite = identifier(&string(required(&obj, "sprite")?)?)?; + let force_translucent = match obj.get("force_translucent") { + None => false, + Some(raw) if raw.get() == "null" => false, + Some(raw) if raw.get() == "true" => true, + Some(raw) if raw.get() == "false" => false, + Some(_) => return Err(error("invalid material boolean")), + }; + Ok(TextureSlot::Material(Material { + sprite, + force_translucent, + })) +} +impl Element { + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let from = vector(required(&obj, "from")?)?; + let to = vector(required(&obj, "to")?)?; + if from.iter().chain(&to).any(|v| !(-16.0..=32.0).contains(v)) { + return Err(error("element outside model bounds")); + } + let rotation = obj + .get("rotation") + .map(|r| ElementRotation::decode(r)) + .transpose()?; + let mut faces = BTreeMap::new(); + for (name, raw) in object(required(&obj, "faces")?)? { + let direction = + Direction::by_name(&name).ok_or_else(|| error("invalid face direction"))?; + faces.insert(direction, nullable(raw, Face::decode)?); + } + if faces.is_empty() { + return Err(error("element requires a face")); + } + let shade_direction_override = obj + .get("shade_direction_override") + .map(|raw| { + Direction::by_name(&primitive_string(raw)?) + .ok_or_else(|| error("invalid shade direction")) + }) + .transpose()?; + let light_emission = obj + .get("light_emission") + .map(|r| integer(r)) + .transpose()? + .unwrap_or(0); + if !(0..=15).contains(&light_emission) { + return Err(error("invalid light emission")); + } + Ok(Self { + from, + to, + faces, + rotation, + shade_direction_override, + light_emission: light_emission as u8, + }) + } +} +impl Face { + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let cull = obj + .get("cullface") + .map(|r| primitive_string(r)) + .transpose()? + .and_then(|s| Direction::by_name(&s)); + let texture = primitive_string(required(&obj, "texture")?)?; + let tint_index = obj + .get("tintindex") + .map(|r| integer(r)) + .transpose()? + .unwrap_or(-1); + let rotation = obj + .get("rotation") + .map(|r| integer(r)) + .transpose()? + .unwrap_or(0) + .rem_euclid(360); + if rotation % 90 != 0 { + return Err(error("face rotation must be a multiple of 90")); + } + let uv = obj.get("uv").map(|r| vector(r)).transpose()?; + Ok(Self { + cull, + tint_index, + texture, + uv, + rotation: (rotation / 90) as u8, + }) + } +} +impl ElementRotation { + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let origin = vector::<3>(required(&obj, "origin")?)?.map(|v| v * 0.0625); + let value = if obj.contains_key("axis") || obj.contains_key("angle") { + let axis = match primitive_string(required(&obj, "axis")?)? + .to_lowercase() + .as_str() + { + "x" => Axis::X, + "y" => Axis::Y, + "z" => Axis::Z, + _ => return Err(error("invalid rotation axis")), + }; + RotationValue::SingleAxis { + axis, + angle: float(required(&obj, "angle")?)?, + } + } else if ["x", "y", "z"].iter().any(|key| obj.contains_key(*key)) { + let mut angles = [0.0; 3]; + for (angle, key) in angles.iter_mut().zip(["x", "y", "z"]) { + *angle = obj.get(key).map(|r| float(r)).transpose()?.unwrap_or(0.0); + } + RotationValue::EulerXyz(angles) + } else { + return Err(error("missing rotation value")); + }; + let rescale = obj + .get("rescale") + .map(|r| boolean(r)) + .transpose()? + .unwrap_or(false); + Ok(Self { + origin, + value, + rescale, + }) + } +} +impl ItemTransform { + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let rotation = obj + .get("rotation") + .map(|r| vector(r)) + .transpose()? + .unwrap_or([0.0; 3]); + let translation = obj + .get("translation") + .map(|r| vector(r)) + .transpose()? + .unwrap_or([0.0; 3]) + .map(|v| (v * 0.0625).clamp(-5.0, 5.0)); + let scale = obj + .get("scale") + .map(|r| vector(r)) + .transpose()? + .unwrap_or([1.0; 3]) + .map(|v| v.clamp(-4.0, 4.0)); + Ok(Self { + rotation, + translation, + scale, + }) + } +} +impl ItemTransforms { + fn decode(raw: &RawValue) -> Result { + let obj = object(raw)?; + let mut contexts = std::array::from_fn(|_| DisplayTransform::Inherit); + for (transform, key) in contexts.iter_mut().zip(DISPLAY_CONTEXTS) { + if let Some(raw) = obj.get(key) { + *transform = DisplayTransform::Explicit(nullable(raw, ItemTransform::decode)?); + } + } + for (left, right) in [(0, 1), (2, 3)] { + if contexts[left] == DisplayTransform::Inherit { + contexts[left] = contexts[right].clone(); + } + } + Ok(Self { contexts }) + } +} diff --git a/docs/native-client.md b/docs/native-client.md index e33c222e2..6a4fcaad3 100644 --- a/docs/native-client.md +++ b/docs/native-client.md @@ -53,6 +53,25 @@ physical key positions; typing the character W can report physical Escape. ## Validation +The separate `horizon-assets` crate decodes the pinned 26.3 cuboid model format. +Its native comparison covers all **2,883 block-model JSON files** in the client +JAR plus **2,337 synthetic cases**: element bounds, optional geometry, nullable +children, face UVs and quarter turns, single-axis/Euler rotations, texture +references and translucency materials, light emission, display transforms and +inheritance markers. Floating-point fields compare by their exact bits. The +comparison also covers primitive coercion, integer truncation/wraparound and +selected strict-reader numeric/syntax limits. + +```sh +python3 tools/test_cuboid_model_parity.py +``` + +The [archived decoder result](../benchmarks/rust-cuboid-model-decoding-2026-10-06/scoped-parity.json) +records source, fixture and reference hashes. The oracle uses actual client +classes; those rendering APIs are absent from the server. This decoder is not +yet connected to the development renderer. Parent resolution, rotation matrices, +quad baking, blockstate selection and rendered appearance need their own checks. + ```sh cargo +stable test -p horizon-client cargo +stable clippy --workspace --all-targets -- -D warnings diff --git a/docs/rust-parity.md b/docs/rust-parity.md index 67f32ac3d..3e40ec2e0 100644 --- a/docs/rust-parity.md +++ b/docs/rust-parity.md @@ -13,6 +13,10 @@ families now have native differential coverage. Full simulation callbacks, complete chunk generation, entity behavior, networking, rendering and playable integration remain unfinished. The linked subsystem documents and hashed reports record the exact tested scope and remaining gaps. +The `horizon-assets` crate now decodes pinned cuboid models, with all 2,883 bundled +block-model JSON files and 2,337 synthetic cases compared against the actual +client parser. [Decoder scope and validation](native-client.md#validation) +are separate from the unfinished model-resolution and rendering integration. The playable Java performance packs remain available during development. ## Completion criteria and playable builds diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java new file mode 100644 index 000000000..134851504 --- /dev/null +++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java @@ -0,0 +1,96 @@ +package dev.horizonlab.parity; + +import com.google.gson.*; +import java.io.*; +import java.nio.file.*; +import java.util.*; +import net.minecraft.client.resources.model.cuboid.*; +import net.minecraft.client.resources.model.sprite.TextureSlots; +import net.minecraft.world.item.ItemDisplayContext; +import org.joml.Vector3fc; + +/** Original adapter around the pinned client parser. No model assets are embedded. */ +public final class VanillaCuboidModelOracle { + private static final Gson JSON = new GsonBuilder().serializeNulls().create(); + private static long bits(float value) { return Integer.toUnsignedLong(Float.floatToIntBits(value)); } + private static Object vector(Vector3fc value) { return new long[]{bits(value.x()), bits(value.y()), bits(value.z())}; } + private static String direction(net.minecraft.core.Direction value) { return value == null ? null : value.getName(); } + private static Map map(Object... values) { + var result = new TreeMap(); + for (int i=0;i map("axis", single.axis().getName(), "angle", bits(single.angle())); + case CuboidRotation.EulerXYZRotation euler -> new long[]{bits(euler.x()), bits(euler.y()), bits(euler.z())}; + default -> throw new AssertionError("Unexpected parsed rotation " + value.value().getClass()); + }; + return map("origin", vector(value.origin()), "value", angles, "rescale", value.rescale()); + } + private static Object face(CuboidFace value) { + if (value == null) return null; + var uv = value.uvs(); + return map("cull", direction(value.cullForDirection()), "tint", value.tintIndex(), "texture", value.texture(), + "rotation", value.rotation().ordinal(), "uv", uv == null ? null : new long[]{bits(uv.minU()), bits(uv.minV()), bits(uv.maxU()), bits(uv.maxV())}); + } + private static Object element(CuboidModelElement value) { + if (value == null) return null; + var faces = new TreeMap(); + value.faces().forEach((key, f) -> faces.put(key.getName(), face(f))); + return map("from", vector(value.from()), "to", vector(value.to()), "faces", faces, + "rotation", rotation(value.rotation()), "shade", direction(value.shadeDirectionOverride()), "light", value.lightEmission()); + } + private static Object model(CuboidModel value) throws Exception { + if (value == null) return null; + var textures = new TreeMap(); + // Slot implementation records are package-private; inspect only their public accessors. + for (var entry : value.textureSlots().values().entrySet()) { + Object slot = entry.getValue(); + var cls = slot.getClass(); + if (cls.getSimpleName().equals("Reference")) { + var target = cls.getDeclaredMethod("target"); target.setAccessible(true); + textures.put(entry.getKey(), map("reference", target.invoke(slot))); + } else { + var method = cls.getDeclaredMethod("material"); method.setAccessible(true); + var material = (net.minecraft.client.resources.model.sprite.Material)method.invoke(slot); + textures.put(entry.getKey(), map("sprite", material.sprite().toString(), "translucent", material.forceTranslucent())); + } + } + List elements = null; + if (value.geometry() != null) { + elements = new ArrayList<>(); + for (var element : ((UnbakedCuboidGeometry)value.geometry()).elements()) elements.add(element(element)); + } + Object display = null; + if (value.transforms() != null) { + var transforms = new TreeMap(); + for (var context : ItemDisplayContext.values()) { + if (context != ItemDisplayContext.NONE) transforms.put(context.getSerializedName(), transform(value.transforms().getTransform(context))); + } + display = transforms; + } + return map("parent", value.parent() == null ? null : value.parent().toString(), "ao", value.ambientOcclusion(), + "gui", value.guiLight() == null ? null : value.guiLight().name().toLowerCase(Locale.ROOT), "textures", textures, "elements", elements, "display", display); + } + public static void main(String[] args) throws Exception { + net.minecraft.SharedConstants.tryDetectVersion(); + try (var input=Files.newBufferedReader(Path.of(args[0])); var output=Files.newBufferedWriter(Path.of(args[1]))) { + for (String line; (line=input.readLine())!=null;) { + var row=JsonParser.parseString(line).getAsJsonArray(); + CuboidModel decoded; + try { decoded=CuboidModel.fromStream(new StringReader(row.get(1).getAsString())); } + catch (RuntimeException failure) { + output.write(JSON.toJson(map("name", row.get(0).getAsString(), "error", true))); output.newLine(); continue; + } + output.write(JSON.toJson(map("name", row.get(0).getAsString(), "model", model(decoded)))); output.newLine(); + } + } + } +} diff --git a/tools/test_cuboid_model_parity.py b/tools/test_cuboid_model_parity.py new file mode 100644 index 000000000..bc0b3da57 --- /dev/null +++ b/tools/test_cuboid_model_parity.py @@ -0,0 +1,160 @@ +#!/usr/bin/env python3 +"""Compare cuboid decoding with the actual pinned client parser (client-only API).""" +import argparse +import copy +import json +import os +from pathlib import Path +import platform +import random +import subprocess +import zipfile + +try: + from . import lab, test_rust_parity as base +except ImportError: + import lab, test_rust_parity as base + + +def corpus(): + element = {'from': [0, 0, 0], 'to': [16, 16, 16], 'faces': {'north': {'texture': '#all'}}} + values = [None, False, True, 0, 1, -1, 15, 16, 90, 90.9, -90, 360, 450, 1e30, + '', 'true', 'TRUE', 'false', 'north', 'NORTH', 'x', '#all', [], {}, [0, 0, 0]] + for raw in ['null', '{}', '[]', 'false', '0', '"model"', '{"elements":[]}', + '{"elements":[null]}', '{"elements":null}', '{"parent":"","textures":{}}', + '{} trailing', '{} {}', '\ufeff{}', '', ' ', '{"unknown":NaN}', + '{"unknown":Infinity}', '{"unknown":01}', '{"unknown":true,}', '{/*comment*/}', + '{"unknown":"unescaped\nnewline"}', '{unquoted:0}']: + yield raw + for field in ['parent', 'ambientocclusion', 'gui_light', 'textures', 'display', 'elements']: + for value in values: + yield json.dumps({field: value}) + for name in ['block/cube_all', ':block/cube_all', 'horizon:test', ':', 'minecraft:', + 'a:b:c', 'Minecraft:cube', 'a:b c', '../cube', 'é', 'a:/', 'a:.']: + yield json.dumps({'parent': name}) + yield json.dumps({'textures': {'all': name}}) + for value in values + ['#', '##all', 'block/stone', ':block/stone', + {'sprite': 'block/glass'}, {'sprite': ''}, {'sprite': None}]: + yield json.dumps({'textures': {'all': value}}) + for value in values: + yield json.dumps({'textures': {'all': {'sprite': 'block/glass', 'force_translucent': value}}}) + for field in ['from', 'to', 'rotation', 'faces', 'shade_direction_override', 'light_emission', 'shade']: + for value in values: + modified = copy.deepcopy(element); modified[field] = value + yield json.dumps({'elements': [modified]}) + for field in ['cullface', 'texture', 'tintindex', 'uv', 'rotation']: + for value in values: + modified = copy.deepcopy(element); modified['faces']['north'][field] = value + yield json.dumps({'elements': [modified]}) + for direction in ['down', 'up', 'north', 'south', 'west', 'east', 'NORTH', 'north ', '']: + for value in [None, {'texture': '#all'}, {}]: + modified = copy.deepcopy(element); modified['faces'] = {direction: value} + yield json.dumps({'elements': [modified]}) + for rotation in [{'origin': [8, 8, 8]}, {'origin': [8, 8, 8], 'x': 30}, + {'origin': [8, 8, 8], 'y': 20, 'z': 10}, + {'origin': [-32, 0, 64], 'axis': 'X', 'angle': 63, 'x': None}, + {'origin': [0, 0, 0], 'angle': 45, 'x': 0}, + {'origin': [0, 0, 0], 'axis': 'y', 'x': 0}]: + modified = copy.deepcopy(element); modified['rotation'] = rotation + yield json.dumps({'elements': [modified]}) + for key in ['origin', 'axis', 'angle', 'rescale', 'x', 'y', 'z']: + for value in values: + rotation = {'origin': [8, 8, 8], 'axis': 'y', 'angle': 22.5} if key in ['axis', 'angle'] else {'origin': [8, 8, 8], 'x': 45} + rotation[key] = value + modified = copy.deepcopy(element); modified['rotation'] = rotation + yield json.dumps({'elements': [modified]}) + for context in ['thirdperson_lefthand', 'thirdperson_righthand', 'firstperson_lefthand', + 'firstperson_righthand', 'head', 'gui', 'ground', 'fixed', 'on_shelf', 'unknown']: + for value in values + [{'rotation': [1, 2, 3], 'translation': [-81, -0.0, 81], 'scale': [-5, 0, 5]}]: + yield json.dumps({'display': {context: value}}) + for left in ['thirdperson_lefthand', 'firstperson_lefthand']: + right = left.replace('lefthand', 'righthand') + for value in [None, {}, {'scale': [1, 2, 3]}]: + yield json.dumps({'display': {left: value, right: {'rotation': [1, 2, 3]}}}) + yield json.dumps({'display': {right: {'rotation': [1, 2, 3]}}}) + # Raw tokens retain decimal spelling, integer wraparound and direct f32 rounding. + numbers = ['-0.0', '1e02', '90.999', '-90.999', '4294967296', '4294967297', + '9223372036854775809', '-9223372036854775809', '1e100', '1e-100', + '1e2147483647', '1e2147483648', '1e-2147483648', + '1.00000005960464477539062500000001', '1e-46', '-1e-46', '3.5e38', + '1e9999', '1e10000', '1e-9999', '1e-10000', '1.0e10000', '1.0e10001', + '1' * 1023, '1' * 1024, '1' * 10000, '1' * 10001] + for number in numbers: + for field in ['tintindex', 'rotation', 'texture']: + yield '{"elements":[{"from":[0,0,0],"to":[16,16,16],"faces":{"up":{"texture":"#all","' + field + '":' + number + '}}}]}' + yield '{"display":{"gui":{"rotation":[' + number + ',0,0],"translation":[' + number + ',0,0],"scale":[' + number + ',0,0]}}}' + rng = random.Random(0x4355424f4944) + for _ in range(1200): + modified = copy.deepcopy(element) + modified['from'] = [rng.uniform(-17, 33) for _ in range(3)] + modified['to'] = [rng.uniform(-17, 33) for _ in range(3)] + modified['rotation'] = {'origin': [rng.uniform(-100, 100) for _ in range(3)], 'rescale': rng.choice([False, True])} + if rng.randrange(2): + modified['rotation'].update(axis=rng.choice(['x', 'y', 'z']), angle=rng.uniform(-720, 720)) + else: + modified['rotation'].update(zip(['x', 'y', 'z'], [rng.uniform(-720, 720) for _ in range(3)])) + modified['faces'] = {rng.choice(['down', 'up', 'north', 'south', 'west', 'east']): { + 'texture': '#all', 'rotation': 90 * rng.randrange(-12, 13), 'tintindex': rng.randrange(-4, 5), + 'uv': [rng.uniform(-32, 32) for _ in range(4)]}} + modified['light_emission'] = rng.randrange(16) + yield json.dumps({'elements': [modified]}) + + +def canonicalize(path): + rows = [json.loads(line) for line in path.read_text().splitlines()] + path.write_text(''.join(json.dumps(row, sort_keys=True, separators=(',', ':')) + '\n' for row in rows)) + return sum('error' in row for row in rows) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--prepare', action='store_true') + args = parser.parse_args() + if args.prepare: + lab.prepare() + lock, jars, libraries = base.verify_artifacts() + build = lab.LOCAL / 'rust-cuboid-model-parity'; build.mkdir(parents=True, exist_ok=True) + report_path = build / 'report.json'; report_path.unlink(missing_ok=True) + oracle = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity/VanillaCuboidModelOracle.java' + crate = lab.ROOT / 'crates/horizon-assets' + sources = [oracle, Path(__file__), lab.ROOT / 'tools/lab.py', lab.ROOT / 'tools/test_rust_parity.py', + lab.ROOT / 'Cargo.toml', lab.ROOT / 'Cargo.lock', crate / 'Cargo.toml', + *sorted(crate.rglob('*.rs'))] + tested_sources = base.source_hashes(sources) + with zipfile.ZipFile(jars['client']) as archive: + names = sorted(name for name in archive.namelist() if name.startswith('assets/minecraft/models/block/') and name.endswith('.json')) + rows = [(name, archive.read(name).decode()) for name in names] + synthetic = list(corpus()) + rows += [(f'synthetic/{index}', raw) for index, raw in enumerate(synthetic)] + inputs = build / 'inputs.jsonl' + inputs.write_text(''.join(json.dumps(row) + '\n' for row in rows)) + fixtures = base.source_hashes([inputs]) + classes = build / 'classes'; classes.mkdir(exist_ok=True) + def run(command, name): + with (build / (name + '.log')).open('w') as log: + subprocess.run(list(map(str, command)), cwd=lab.ROOT, check=True, timeout=3600, stdout=log, stderr=subprocess.STDOUT) + dependencies = os.pathsep.join(map(str, [jars['client'], *libraries])) + run(['javac', '--release', lock['minecraft']['java_major'], '-proc:none', '-cp', dependencies, '-d', classes, oracle], 'compile-java') + run(['cargo', 'build', '--locked', '-p', 'horizon-assets', '--example', 'cuboid_model_fixture'], 'compile-rust') + metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--locked', '--no-deps', '--format-version', '1'], cwd=lab.ROOT)) + binary = Path(metadata['target_directory']) / 'debug/examples' / ('cuboid_model_fixture.exe' if os.name == 'nt' else 'cuboid_model_fixture') + run([binary, inputs, build / 'rust.jsonl'], 'rust') + run(['java', '-Xmx512M', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.VanillaCuboidModelOracle', inputs, build / 'client.jsonl'], 'client') + rejected = canonicalize(build / 'client.jsonl'); canonicalize(build / 'rust.jsonl') + matched = base.compare(build / 'client.jsonl', build / 'rust.jsonl') + base.ensure_sources_unchanged(sources, tested_sources); base.ensure_sources_unchanged([inputs], fixtures) + report = {'schema': 1, 'minecraft': lock['minecraft']['version'], 'manifest_sha1': lock['minecraft']['manifest_sha1'], + 'platform': platform.platform(), 'java': subprocess.check_output(['java', '--version'], text=True).splitlines()[0], + 'rustc': subprocess.check_output(['rustc', '--version'], text=True).strip(), + 'resource_models': len(names), 'synthetic_models': len(synthetic), 'rejected_models': rejected, + 'sources_sha256': tested_sources, 'fixtures_sha256': fixtures, + 'rust_output_sha256': lab.digest(build / 'rust.jsonl', 'sha256'), + 'references': [{'side': 'client', 'jar_sha256': lab.digest(jars['client'], 'sha256'), + 'output_sha256': lab.digest(build / 'client.jsonl', 'sha256'), 'matched_output_lines': matched}], + 'scope': 'Actual pinned CuboidModel.fromStream parser compared over every bundled block model and synthetic JSON/numeric/syntax cases. Decoded geometry, texture materials/references, nullable children, inheritance markers, face quadrants, light emission and display transforms; floats compare by IEEE-754 bits. Rejections normalize exception text. This client-only API is absent from the server. Does not yet validate parent resolution, rotation matrices, quad baking, blockstate dispatch, rendered pixels or gameplay.'} + lab.write_json(report_path, report) + print(f'Client cuboid decoding: {matched:,} models match ({rejected:,} rejected); {report_path}', flush=True) + + +if __name__ == '__main__': + main()