Decode pinned cuboid models and verify native client semantics

This commit is contained in:
Ludovic Marie
2026-10-06 20:10:30 +02:00
parent 18d0c44e8d
commit 9dbd93192f
12 changed files with 970 additions and 1 deletions
Generated
+7
View File
@@ -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"
+1 -1
View File
@@ -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]
@@ -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."
}
+10
View File
@@ -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"] }
@@ -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<const N: usize>(values: [f32; N]) -> Vec<u32> {
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::<Vec<_>>()
});
let display = v.display.as_ref().map(|v| {
DISPLAY_CONTEXTS
.into_iter()
.zip(v.contexts.iter().map(transform))
.collect::<BTreeMap<_, _>>()
});
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<dyn std::error::Error>> {
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<String> = 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(())
}
+151
View File
@@ -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<serde_json::Error> for DecodeError {
fn from(value: serde_json::Error) -> Self {
Self(value.to_string())
}
}
pub(crate) type Result<T> = std::result::Result<T, DecodeError>;
pub(crate) type Object<'a> = BTreeMap<String, &'a RawValue>;
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<Object<'_>> {
if !raw.get().starts_with('{') {
return Err(error("expected object"));
}
Ok(serde_json::from_str(raw.get())?)
}
pub(crate) fn array(raw: &RawValue) -> Result<Vec<&RawValue>> {
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<String> {
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<String> {
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<bool> {
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<f32> {
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<i32> {
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<const N: usize>(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<String> {
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}"))
}
+7
View File
@@ -0,0 +1,7 @@
//! Resource decoding for the pinned Java Edition client.
#![forbid(unsafe_code)]
mod json;
pub mod model;
pub use json::DecodeError;
+394
View File
@@ -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> {
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<String>,
pub ambient_occlusion: Option<bool>,
pub gui_light: Option<GuiLight>,
pub textures: BTreeMap<String, TextureSlot>,
pub elements: Option<Vec<Option<Element>>>,
pub display: Option<ItemTransforms>,
}
#[derive(Clone, Debug, PartialEq)]
pub struct Element {
pub from: [f32; 3],
pub to: [f32; 3],
pub faces: BTreeMap<Direction, Option<Face>>,
pub rotation: Option<ElementRotation>,
pub shade_direction_override: Option<Direction>,
pub light_emission: u8,
}
#[derive(Clone, Debug, PartialEq)]
pub struct Face {
pub cull: Option<Direction>,
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<ItemTransform>),
}
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<Self> {
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<Self> {
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::<Result<Vec<_>>>()
})
.transpose()?;
let display = obj
.get("display")
.map(|r| ItemTransforms::decode(r))
.transpose()?;
Ok(Self {
parent,
ambient_occlusion,
gui_light,
textures,
elements,
display,
})
}
}
fn nullable<T>(raw: &RawValue, decode: impl FnOnce(&RawValue) -> Result<T>) -> Result<Option<T>> {
if raw.get() == "null" {
Ok(None)
} else {
decode(raw).map(Some)
}
}
fn texture(raw: &RawValue) -> Result<TextureSlot> {
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<Self> {
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<Self> {
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<Self> {
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<Self> {
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<Self> {
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 })
}
}
+19
View File
@@ -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
+4
View File
@@ -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
@@ -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<String, Object> map(Object... values) {
var result = new TreeMap<String, Object>();
for (int i=0;i<values.length;i+=2) result.put((String)values[i], values[i+1]);
return result;
}
private static Object transform(ItemTransform value) {
if (value == ItemTransform.NO_TRANSFORM) return "inherit";
if (value == null) return null;
return map("rotation", vector(value.rotation()), "translation", vector(value.translation()), "scale", vector(value.scale()));
}
private static Object rotation(CuboidRotation value) {
if (value == null) return null;
Object angles = switch (value.value()) {
case CuboidRotation.SingleAxisRotation single -> 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<String, Object>();
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<String, Object>();
// 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<Object> 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<String, Object>();
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();
}
}
}
}
+160
View File
@@ -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()