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.
@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