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

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