test(entity_model): compare per-vertex normals with vanilla

The entity model parity harness now draws each posed model on both sides
under LivingEntityRenderer's root transform (body yaw, scale(-1, -1, 1),
the renderer's own scale) and compares every vertex's normal as the
signed bytes written to the vertex buffer: vanilla's ModelPart.render /
Cube.compile / PoseStack.Pose.transformNormal into a capturing
VertexConsumer, packed with BufferBuilder's own normalIntValue, against
Horizon's mobs::render::draw RGBA8_SNORM normals. A part-scale override
covers negative and non-uniform part scales (trusted sign flips and
untrusted 1/scale normalisation). A one-step difference is accepted only
where vanilla's float sits at a truncation step; a posed position
checksum per drawn part is compared too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-14 17:15:45 +02:00
parent 45663c9e39
commit 3f61995c8b
3 changed files with 308 additions and 9 deletions
@@ -1,14 +1,17 @@
//! Replays the render states of the vanilla entity-animation oracle through
//! Horizon's `mobs::anim::setup` and writes every part's pose.
//! Horizon's `mobs::anim::setup` and writes every part's pose, then draws the
//! posed model with `mobs::render::draw` under the case's living-entity root
//! transform and writes each drawn part's packed vertex normals.
//!
//! cargo run --profile fast -p horizon-client --example entity_anim_fixture -- \
//! RESOURCES VANILLA.jsonl OUT.jsonl
use horizon_client::mesher::Vertex;
use horizon_client::mobs::{
Mob, MobData, MobTypes, Part, Species, allay,
anim::{self, Poses, State},
aquatic, body_anim as b_anim, equine, guardian,
keyframes::AnimationState,
shulker, sniffer, species, tame,
render, shulker, sniffer, species, tame,
};
use horizon_core::geometry::Vec3;
use serde_json::{Value, json};
@@ -44,6 +47,61 @@ fn walk(part: &Part, path: &str, poses: &Poses, out: &mut BTreeMap<String, Value
}
}
/// Splits the vertices `render::draw` emitted for `part` into its drawn parts,
/// following draw's walk: a hidden or zero-scaled part ends its branch, a
/// skip-draw part keeps its children. Per part: n = packed normal bytes per
/// vertex, p = sum of x + 2y + 3z over the positions.
fn drawn(
part: &Part,
path: &str,
poses: &Poses,
vertices: &[Vertex],
cursor: &mut usize,
out: &mut BTreeMap<String, Value>,
) {
let p = poses.pose(part);
if poses.is_hidden(part) || p[6] == 0.0 && p[7] == 0.0 && p[8] == 0.0 {
return;
}
let count = if poses.skips(part) {
0
} else {
part.polygons.len() * 4
};
if count > 0 {
let own = &vertices[*cursor..*cursor + count];
let normals: Vec<i8> = own.iter().flat_map(|v| v.normal[..3].to_vec()).collect();
let sum: f64 = own
.iter()
.map(|v| f64::from(v.pos[0]) + 2.0 * f64::from(v.pos[1]) + 3.0 * f64::from(v.pos[2]))
.sum();
out.insert(path.to_owned(), json!({"n": normals, "p": sum}));
}
*cursor += count;
for c in &part.children {
let child = if path.is_empty() {
c.name.clone()
} else {
format!("{path}/{}", c.name)
};
drawn(c, &child, poses, vertices, cursor, out);
}
}
/// LivingEntityRenderer's root transform without the entity's position:
/// rotate 180 - yaw about Y, scale(-1, -1, 1), the renderer's own scale, then
/// translate(0, -1.501, 0) (as `render::base_transform`).
fn root_transform(case: &Value) -> glam::Mat4 {
let yaw = case["@rootYaw"].as_f64().unwrap_or(0.0) as f32;
let scale = case["@rootScale"].as_array().map_or(glam::Vec3::ONE, |s| {
glam::Vec3::from_array(std::array::from_fn(|i| s[i].as_f64().unwrap_or(1.0) as f32))
});
glam::Mat4::from_rotation_y((180.0 - yaw).to_radians())
* glam::Mat4::from_scale(glam::Vec3::new(-1.0, -1.0, 1.0))
* glam::Mat4::from_scale(scale)
* glam::Mat4::from_translation(glam::Vec3::new(0.0, -1.501, 0.0))
}
/// The entity-side values behind the render-state fields the case sets, for
/// the species whose Horizon animation reads them from the `Mob`.
fn entity_state(mob: &mut Mob, species: Species, case: &Value) {
@@ -518,9 +576,34 @@ fn main() -> horizon_client::Result<()> {
}
_ => anim::setup(&mob, s, p, &animations),
}
// The harness's part-scale override, set after setupAnim as the oracle does.
if let Some(scale) = case["@partScale"].as_array() {
let pose = poses.get(scale[0].as_str().unwrap_or_default());
for i in 0..3 {
pose[6 + i] = scale[1 + i].as_f64().unwrap_or(1.0) as f32;
}
}
let mut parts = BTreeMap::new();
walk(&model, "", &poses, &mut parts);
out.push_str(&format!("{}\n", json!({"parts": parts})));
let mut emitted = Vec::new();
render::draw(
&model,
root_transform(case),
&poses,
[0.0, 0.0, 1.0, 1.0],
0xFFFF_FFFF,
240 | 240 << 8,
0,
&mut emitted,
);
let mut vertices = BTreeMap::new();
let mut cursor = 0;
drawn(&model, "", &poses, &emitted, &mut cursor, &mut vertices);
assert_eq!(cursor, emitted.len(), "{layer}: draw's walk changed");
out.push_str(&format!(
"{}\n",
json!({"parts": parts, "vertices": vertices})
));
}
fs::write(&args[2], out)?;
Ok(())
@@ -7,6 +7,10 @@ import java.lang.reflect.Modifier;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import com.mojang.blaze3d.vertex.BufferBuilder;
import com.mojang.blaze3d.vertex.PoseStack;
import com.mojang.blaze3d.vertex.VertexConsumer;
import com.mojang.math.Axis;
import net.minecraft.SharedConstants;
import net.minecraft.client.model.EntityModel;
import net.minecraft.client.model.geom.LayerDefinitions;
@@ -21,7 +25,16 @@ import net.minecraft.server.Bootstrap;
* fields, runs the real setupAnim and writes every part's pose.
*
* Input lines: "layer-key ModelClass|case-json" where case-json is an object of state field
* name to value. Output lines: {layer, case, parts:{path:[x,y,z,xRot,yRot,zRot,xScale,yScale,zScale,visible]}}.
* name to value. Output lines: {layer, case, parts:{path:[x,y,z,xRot,yRot,zRot,xScale,yScale,zScale,visible]},
* vertices:{path:{n, f, p, d}}}.
*
* `vertices` renders the posed model the way ModelPart.render does (translateAndRotate on a
* PoseStack, then Cube.compile: PoseStack.Pose.transformNormal once per polygon and
* VertexConsumer.addVertex/setNormal per vertex) under LivingEntityRenderer's root transform:
* rotateDegrees(YP, 180 - "@rootYaw"), scale(-1, -1, 1), scale("@rootScale"),
* translate(0, -1.501, 0). Per drawn part: n = each vertex's normal as the signed bytes
* BufferBuilder.setNormal writes (its own normalIntValue), f = each polygon's float normal before
* packing, p = sum of x + 2y + 3z over the posed positions, d = all its vertices are one point.
*/
public final class VanillaEntityAnimOracle {
private static Field cubes;
@@ -63,6 +76,82 @@ public final class VanillaEntityAnimOracle {
private static final List<String> CLASS_NAMES = new ArrayList<>();
private static Method normalIntValue;
/** Records what Cube.compile hands its VertexConsumer: each vertex's position and normal. */
private static final class Capture implements VertexConsumer {
final List<float[]> vertices = new ArrayList<>();
private float[] current;
@Override
public VertexConsumer addVertex(float x, float y, float z) {
current = new float[] {x, y, z, Float.NaN, Float.NaN, Float.NaN};
vertices.add(current);
return this;
}
@Override
public VertexConsumer setNormal(float x, float y, float z) {
current[3] = x;
current[4] = y;
current[5] = z;
return this;
}
@Override public VertexConsumer setColor(int r, int g, int b, int a) { return this; }
@Override public VertexConsumer setColor(int color) { return this; }
@Override public VertexConsumer setUv(float u, float v) { return this; }
@Override public VertexConsumer setUv1(int u, int v) { return this; }
@Override public VertexConsumer setUv2(int u, int v) { return this; }
@Override public VertexConsumer setUv3(float u, float v) { return this; }
@Override public VertexConsumer setLineWidth(float width) { return this; }
JsonObject json() throws Exception {
var packed = new JsonArray();
var floats = new JsonArray();
double sum = 0;
boolean degenerate = true;
float[] first = vertices.get(0);
for (int i = 0; i < vertices.size(); i++) {
float[] v = vertices.get(i), corner = vertices.get(i - i % 4);
for (int c = 3; c < 6; c++) packed.add((byte) normalIntValue.invoke(null, v[c]));
if (i % 4 == 0) {
for (int c = 3; c < 6; c++) floats.add(Float.isFinite(v[c]) ? v[c] : 0.0F);
} else if (!Arrays.equals(v, 3, 6, corner, 3, 6)) {
throw new IllegalStateException("normal changes inside a polygon");
}
sum += v[0] + 2.0 * v[1] + 3.0 * v[2];
degenerate &= v[0] == first[0] && v[1] == first[1] && v[2] == first[2];
}
var o = new JsonObject();
o.add("n", packed);
o.add("f", floats);
o.addProperty("p", sum);
o.addProperty("d", degenerate);
return o;
}
}
/** ModelPart.render, keeping each part's vertices apart under its path. */
@SuppressWarnings("unchecked")
private static void render(String path, ModelPart part, PoseStack poseStack, JsonObject out) throws Exception {
if (!part.visible) return;
var cubeList = (List<ModelPart.Cube>) cubes.get(part);
var kids = (Map<String, ModelPart>) children.get(part);
if (cubeList.isEmpty() && kids.isEmpty()) return;
poseStack.pushPose();
part.translateAndRotate(poseStack);
if (!part.skipDraw) {
var capture = new Capture();
for (ModelPart.Cube cube : cubeList)
cube.compile(poseStack.last(), capture, 0xF000F0, net.minecraft.client.renderer.texture.OverlayTexture.NO_OVERLAY, -1);
if (!capture.vertices.isEmpty()) out.add(path, capture.json());
}
for (var entry : kids.entrySet())
render(path.isEmpty() ? entry.getKey() : path + "/" + entry.getKey(), entry.getValue(), poseStack, out);
poseStack.popPose();
}
private static Class<?> raw(java.lang.reflect.Type t, Map<java.lang.reflect.TypeVariable<?>, java.lang.reflect.Type> env) {
if (t instanceof Class<?> c) return c;
if (t instanceof java.lang.reflect.ParameterizedType p) return raw(p.getRawType(), env);
@@ -160,6 +249,8 @@ public final class VanillaEntityAnimOracle {
cubes.setAccessible(true);
children = ModelPart.class.getDeclaredField("children");
children.setAccessible(true);
normalIntValue = BufferBuilder.class.getDeclaredMethod("normalIntValue", float.class);
normalIntValue.setAccessible(true);
try (var zip = new java.util.zip.ZipFile(args[2])) {
zip.stream().map(e -> e.getName()).filter(n -> n.startsWith("net/minecraft/client/model/") && n.endsWith(".class"))
.forEach(n -> CLASS_NAMES.add(n.substring(0, n.length() - 6).replace('/', '.')));
@@ -189,14 +280,36 @@ public final class VanillaEntityAnimOracle {
var type = stateClass(cls);
var state = (EntityRenderState) type.getDeclaredConstructor().newInstance();
state.getClass();
for (var entry : kase.entrySet()) set(state, entry.getKey(), entry.getValue());
for (var entry : kase.entrySet())
if (!entry.getKey().startsWith("@")) set(state, entry.getKey(), entry.getValue());
hooks(state, kase);
if (state instanceof net.minecraft.client.renderer.entity.state.ArmedEntityRenderState armed && armed.swingAnimation > 0)
armed.currentSwing = new net.minecraft.world.entity.LivingEntity.SwingDescription(net.minecraft.world.InteractionHand.MAIN_HAND, net.minecraft.world.item.component.SwingAnimation.DEFAULT, 6);
model.setupAnim(state);
if (kase.has("@partScale")) {
var override = kase.getAsJsonArray("@partScale");
var part = baked.createPartLookup().apply(override.get(0).getAsString());
if (part == null) throw new IllegalArgumentException("no part " + override.get(0));
part.xScale = override.get(1).getAsFloat();
part.yScale = override.get(2).getAsFloat();
part.zScale = override.get(3).getAsFloat();
}
var parts = new JsonObject();
dump("", baked, parts);
result.add("parts", parts);
// LivingEntityRenderer.render/setupRotations, without the entity's position.
var poseStack = new PoseStack();
float yaw = kase.has("@rootYaw") ? kase.get("@rootYaw").getAsFloat() : 0.0F;
poseStack.rotateDegrees(Axis.YP, 180.0F - yaw);
poseStack.scale(-1.0F, -1.0F, 1.0F);
if (kase.has("@rootScale")) {
var scale = kase.getAsJsonArray("@rootScale");
poseStack.scale(scale.get(0).getAsFloat(), scale.get(1).getAsFloat(), scale.get(2).getAsFloat());
}
poseStack.translate(0.0F, -1.501F, 0.0F);
var vertices = new JsonObject();
render("", baked, poseStack, vertices);
result.add("vertices", vertices);
} catch (Throwable error) {
var cause = error.getCause() != null ? error.getCause() : error;
result.addProperty("error", cause.toString());
+107 -4
View File
@@ -8,7 +8,18 @@ state fields), runs the real `setupAnim` and writes every part's pose.
`mobs::anim::setup` and the loaded model tree; the two must agree on every part
pose and on the baked polygon count and vertex sums.
Both sides then draw the posed model under LivingEntityRenderer's root transform
(vanilla: ModelPart.render's PoseStack walk and Cube.compile into a capturing
VertexConsumer; Horizon: `mobs::render::draw`) and compare every vertex's normal
as the signed bytes each puts in its vertex buffer: vanilla's BufferBuilder.setNormal
truncates clamp(c) * 127 toward zero (normalIntValue) for the entity format's byte
normal, Horizon packs its RGBA8_SNORM `Vertex.normal` the same way. A one-step
difference is accepted only where vanilla's float lies within --normal-edge of a
truncation step (float rounding); any other difference fails. A checksum of each
drawn part's posed positions is compared too.
test_entity_model_parity.py [--filter SUBSTRING] [--detail LAYER] [--tolerance EPS]
[--normal-edge EPS] [--position-tolerance EPS]
"""
import argparse
import json
@@ -101,7 +112,34 @@ def layers(models):
return chosen
def cases(layer):
# The renderer's root transform for the normal comparison (keys starting with
# '@' are not render-state fields): LivingEntityRenderer's body yaw, and the
# renderer's own scale (uniform like an age scale, or non-uniform like
# CreeperRenderer's swell, which makes PoseStack.Pose's normals untrusted).
ROOT_YAWS = [0.0, 37.5, -112.25, 90.0, 180.0, 213.7, -45.0]
ROOT_SCALES = [[1.0, 1.0, 1.0], [1.0, 1.0, 1.0], [0.5, 0.5, 0.5], [1.18, 0.92, 1.18], [1.0, 1.0, 1.0]]
# No vanilla setupAnim scales a part negatively, so '@partScale' sets one part's scale after
# setupAnim on both sides: PoseStack.Pose.scale flips the normal matrix's signs when |x|=|y|=|z|
# (trusted), and scales it by 1/x, 1/y, 1/z and normalises otherwise.
PART_SCALES = [[-1.0, -1.0, -1.0], [-1.0, 1.0, 1.0], [1.0, -1.0, 1.0], [-0.75, 1.25, 1.0], [0.6, 0.6, 0.6]]
def scaled_part(model):
"""A part with cubes, preferably with children, whose name is unique in the tree (Horizon's
poses are keyed by name)."""
names, found = {}, []
def walk(name, node, depth):
names[name] = names.get(name, 0) + 1
if depth and node.get('polygons'):
found.append((not node.get('children'), depth, name))
for key, child in sorted(node.get('children', {}).items()):
walk(key, child, depth + 1)
walk('root', model, 0)
found = [f for f in found if names[f[2]] == 1]
return min(found)[2] if found else None
def cases(layer, model=None):
rng = random.Random(0x414e494d + sum(map(ord, layer)))
baby = '_baby#' in layer
base_cases = [
@@ -117,14 +155,19 @@ def cases(layer):
rng.uniform(-50, 50), rng.uniform(-70, 70),
rng.choice([0.0, rng.uniform(0.01, 0.99)])))
cases_out = []
for pos, speed, age, y, x, attack in base_cases:
for index, (pos, speed, age, y, x, attack) in enumerate(base_cases):
cases_out.append({'walkAnimationPos': pos, 'walkAnimationSpeed': speed, 'ageInTicks': age,
'yRot': y, 'xRot': x, 'swingAnimation': attack, 'isBaby': baby, 'ageScale': 0.5 if baby else 1.0,
'entityId': 7, 'yHeadRot': y, 'yBodyRot': 0.0})
'entityId': 7, 'yHeadRot': y, 'yBodyRot': 0.0,
'@rootYaw': ROOT_YAWS[index % len(ROOT_YAWS)], '@rootScale': ROOT_SCALES[index % len(ROOT_SCALES)]})
name = layer.split(':')[1].split('#')[0].removesuffix('_baby')
cases_out = [{**c, **DEFAULTS.get(name, {})} for c in cases_out]
yield from cases_out
yield from species_cases(layer, cases_out)
part = model and scaled_part(model)
if part:
for index, scale in enumerate(PART_SCALES):
yield {**cases_out[2 + index % 2], '@partScale': [part, *scale]}
T, F = True, False
@@ -233,11 +276,65 @@ def species_cases(layer, base_cases):
yield {**base_cases[index], **extra}
def compare_vertices(v, r, args, stats):
"""The posed model's per-vertex normals, as the signed bytes both clients put in the vertex
buffer (BufferBuilder.setNormal's normalIntValue; Horizon's RGBA8_SNORM `Vertex.normal`), and
a checksum of each drawn part's posed positions."""
bad = []
vanilla, rust = v.get('vertices', {}), r.get('vertices', {})
for path, ve in vanilla.items():
ru = rust.get(path)
if ru is None:
# Horizon does not draw a part scaled to zero: vanilla's vertices all collapse there.
if ve['d']:
stats['degenerate'] += len(ve['n']) // 3
else:
bad.append((path, 'drawn by vanilla, not by Horizon'))
continue
if len(ve['n']) != len(ru['n']):
bad.append((path, f'{len(ve["n"]) // 3} vertices != {len(ru["n"]) // 3}'))
continue
stats['parts'] += 1
first = None
for i in range(0, len(ve['n']), 3):
stats['vertices'] += 1
exact = True
for c in range(3):
a, b = ve['n'][i + c], ru['n'][i + c]
f = ve['f'][i // 12 * 3 + c]
if a == b:
continue
exact = False
stats['max_bytes'] = max(stats['max_bytes'], abs(a - b))
# A one-byte step where vanilla's float sits within float rounding of a
# truncation step (normalIntValue truncates c * 127 toward zero).
edge = abs(f * 127.0 - round(f * 127.0)) <= args.normal_edge and abs(a - b) == 1
if edge:
stats['edge'] += 1
elif first is None:
first = (path, f'vertex {i // 3} normal {ve["n"][i:i + 3]} != {ru["n"][i:i + 3]}'
f' (vanilla float {ve["f"][i // 12 * 3:i // 12 * 3 + 3]})')
stats['exact'] += exact
if first:
bad.append(first)
count = len(ve['n']) // 3
if abs(ve['p'] - ru['p']) > args.position_tolerance * count * (1.0 + abs(ve['p']) / max(count, 1)):
bad.append((path, f'posed position sum {ve["p"]!r} != {ru["p"]!r}'))
for path in rust:
if path not in vanilla:
bad.append((path, 'drawn by Horizon, not by vanilla'))
return bad
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--filter', default='')
parser.add_argument('--detail', default='')
parser.add_argument('--tolerance', type=float, default=5e-7)
parser.add_argument('--normal-edge', type=float, default=1e-4,
help='accept a one-byte normal step when vanilla\'s float * 127 is this close to an integer')
parser.add_argument('--position-tolerance', type=float, default=1e-5,
help='per-vertex tolerance of the posed position checksums, in blocks')
args = parser.parse_args()
lock, jars, _ = base.verify_artifacts()
libraries = baking.client_libraries()
@@ -249,7 +346,7 @@ def main():
if Path(__file__).with_suffix('.cases.json').exists() else {}
lines = []
for layer, cls in sorted(chosen.items()):
for case in cases(layer):
for case in cases(layer, models[layer]):
lines.append(f'{layer} {cls}|{json.dumps(case)}')
for case in extra_cases.get(layer.split(':')[1].split('#')[0], []):
lines.append(f'{layer} {cls}|{json.dumps(case)}')
@@ -271,6 +368,7 @@ def main():
rust = [json.loads(l) for l in (build / 'rust.jsonl').read_text().splitlines()]
assert len(vanilla) == len(rust), (len(vanilla), len(rust))
errors, skipped, mismatched, checked = {}, set(), {}, 0
stats = dict.fromkeys(['parts', 'vertices', 'exact', 'edge', 'degenerate', 'max_bytes'], 0)
for v, r in zip(vanilla, rust):
layer = v['layer']
if 'error' in v:
@@ -297,9 +395,14 @@ def main():
for path in r['parts']:
if path not in v['parts']:
bad.append((path, 'extra in Horizon'))
bad += compare_vertices(v, r, args, stats)
if bad:
mismatched.setdefault(layer, []).append((v['case'], bad))
print(f'{checked} cases compared over {len(chosen) - len(skipped) - len(errors)} layers')
print(f'normals: {stats["vertices"]} vertices in {stats["parts"]} drawn parts, {stats["exact"]} with identical '
f'packed bytes, {stats["edge"]} components one step apart at a truncation edge, max byte difference '
f'{stats["max_bytes"]} (max normal error {stats["max_bytes"] / 127:.5f}); '
f'{stats["degenerate"]} collapsed vertices of zero-scaled parts left out')
if errors:
print('oracle errors:'); [print(' ', k, v) for k, v in sorted(errors.items())]
if skipped: