Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

4.5 KB
Raw Blame

@three-ws/glb-diff

Structural diff for glTF/GLB. Tells you what actually changed between two 3D models: geometry, materials, textures, skeletons, and animations, with git-style rename and move detection.

A binary diff of two GLB files tells you the bytes differ, which you already knew. This tells you the thing you need to know before you ship: whether a consumer of that model is about to break.

Install

npm install @three-ws/glb-diff

Library

import { readFile } from 'node:fs/promises';
import { diffModels, formatText } from '@three-ws/glb-diff';

const before = await readFile('avatar.v1.glb');
const after = await readFile('avatar.v2.glb');

const changes = await diffModels(before, after, { nameA: 'v1', nameB: 'v2' });
console.log(formatText(changes));

if (changes.severity === 'breaking') process.exit(1);

Isomorphic: it takes bytes, so the same call works in Node, in a worker, in a serverless handler, or in a browser.

CLI

glb-diff before.glb after.glb
glb-diff before.glb https://example.com/after.glb --markdown
glb-diff base.glb candidate.glb --fail-on major
Option Meaning
--json The full change set as JSON
--markdown A Markdown report, sized for a pull-request comment
--fail-on <level> Exit 1 once severity reaches this level
--verbose Include unchanged totals in the table

Exit codes are the contract a CI job depends on, so they are deliberate:

Code Meaning
0 The diff ran and stayed below --fail-on
1 The diff ran and the severity reached --fail-on
2 The tool could not run: bad arguments, unreadable input, unparseable model

A tool that returns 1 for both "your model regressed" and "I could not open the file" is useless in a pipeline, which is why 2 exists.

Severity

Every change set carries one severity, the worst of everything it found:

Level Meaning
none The two models are structurally identical.
cosmetic Only metadata changed. Nothing a renderer or a clip can observe.
minor Appearance changed. The model still loads, animates, and keeps its shape.
major Geometry or hierarchy changed. Anything positioned against this model should be re-checked.
breaking Something a consumer references by name is gone. Clips, attachments, or materials bound to it will fail.

That ladder is what makes --fail-on useful. A texture swap should not fail a build; a deleted bone that every animation clip targets should.

API

Export What it does
diffModels(bytesA, bytesB, opts?) Bytes in, change set out. The one call most callers need.
describeModel(bytes) / describeDocument(doc) The structural description a diff is computed from.
diffDescriptions(a, b) Diff two descriptions you already have, skipping the parse.
formatText(changes) / formatMarkdown(changes) Render a change set for a terminal or a PR comment.
readDocument(bytes) / isGLB(bytes) Parse helpers over @gltf-transform/core.
SEVERITIES, SEVERITY_MEANING, atLeast(), maxSeverity(), severityRank() The severity ladder as data.
matchEntries(), jaccard(), ratio() The similarity matcher behind rename and move detection.

DESCRIPTION_VERSION and CHANGESET_VERSION are exported so a cache or a stored report can tell whether it was produced by a compatible version.

Mesh fields

A mesh diff's changes array can report these fields on top of the combined geometry hash, each independent of the others so an edit can be checked against exactly the kind of change it is not supposed to make:

Field What moved
topology Vertex positions (POSITION) or the index buffer. Connectivity changed.
uv TEXCOORD_0/TEXCOORD_1. The mesh's shape is identical; its texture mapping is not.
skinWeights JOINTS_0/WEIGHTS_0. The per-vertex skin binding changed, independent of the skeleton itself.

api/_lib/preserve-contract.js builds on exactly these fields, plus the skins and animations sections, to let an edit operation declare which of topology/UVs/skeleton/skin/clips it keeps and verify that promise against the real diff instead of trusting its own say-so.

Related

  • @three-ws/render: rasterize a GLB to PNG with no GPU, for a visual check alongside the structural one.
  • STRUCTURE.md: where every three.ws surface lives.

License

Apache-2.0