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.
glTF Validation
three.ws integrates the official Khronos glTF-Validator (compiled to WebAssembly) to check every GLB or glTF 2.0 file against the specification before it is presented or registered. Validation runs automatically after a model loads, and its result drives both the UI and the agent's emotional response.
What validation checks
The validator measures conformance against the glTF 2.0 specification and reports four severity levels:
| Severity | Code | Meaning |
|---|---|---|
| Error | 0 | Spec violation. Fix before publishing — some renderers will refuse to load the file. |
| Warning | 1 | Non-conformant but likely to load. Behavior in different renderers may differ. |
| Info | 2 | Informational only. No action needed. |
| Hint | 3 | Best-practice suggestion. Not a problem, but worth addressing. |
A model passes validation when numErrors === 0. Warnings, hints, and infos are allowed for a pass verdict.
Reading a validation report
Every validation produces a structured report. Here is what each field means.
Summary counts
{
"issues": {
"numErrors": 1,
"numWarnings": 2,
"numHints": 5,
"numInfos": 1,
"maxSeverity": 0
}
}
maxSeverity is the code of the most severe non-empty bucket (0 = errors present, 1 = warnings only, 2 = infos, 3 = hints only, -1 = completely clean).
Individual messages
Each message in issues.messages has three fields:
code— machine-readable issue identifier (e.g.ACCESSOR_NON_UNIT)message— human-readable descriptionpointer— JSON Pointer to the offending node (e.g./meshes/0/primitives/0)
When many instances of the same error appear on the same node (for example hundreds of ACCESSOR_NON_UNIT entries on one mesh), the viewer aggregates them into a single [AGGREGATED] entry so the report stays readable.
Model info
Alongside the issue list, the validator also extracts metadata from the asset:
- glTF version and generator (e.g.
"Blender 4.1") - Draw call count, vertex count, triangle count
- Animation, material, and texture counts
- Extensions used
asset.extrasfields:title,author,license,source
This information appears in the Model Info overlay and is used by the present-model agent skill.
Common errors and how to fix them
| Code | What it means | Fix |
|---|---|---|
ACCESSOR_NON_UNIT |
Normal or tangent vectors are not unit-length | Re-export with Normalize Normals checked in your exporter |
ACCESSOR_INDEX_TRIANGLE_DEGENERATE |
Triangle has zero area | Remove degenerate faces in your 3D editor before exporting |
ACCESSOR_ANIMATION_INPUT_NON_INCREASING |
Animation keyframe times are not monotonically increasing | Re-bake animations; check for duplicate or reversed keyframes |
MESH_PRIMITIVE_TANGENT_SPACE_INVALID |
Tangent vectors are malformed | Regenerate normals and tangents in Blender (Object Data → Geometry Data → Clear Custom Split Normals Data, then re-export) |
BUFFER_VIEW_TOO_SHORT |
The binary chunk is truncated or corrupt | Re-export the file from scratch |
TEXTURE_INVALID_IMAGE |
An embedded texture cannot be decoded | Re-export with valid PNG or JPG textures; avoid WebP if broad viewer support matters |
UNUSED_OBJECT |
The file contains materials, textures, or animations that nothing references | Remove unused data-blocks before exporting |
Common warnings
NODE_SKINNED_MESH_NON_ROOT— a skinned mesh is not a direct child of the scene root. Most renderers handle this, but moving the root armature to scene level is safer.MESH_PRIMITIVE_JOINTS_WEIGHTS_MISMATCH— the number of joint indices does not match the number of weight values. Re-export the skinned mesh after verifying vertex group assignments.
Running validation
In the viewer
Validation runs automatically after every model load. The result appears in the validator toggle bar at the bottom of the screen:
N errors.— errors found; click to expand the full reportN warnings.— warnings onlyN hints.— hints onlyN notes.: infos onlyModel details— clean; no issues
Clicking the bar opens the full ValidatorReport panel, which shows the model metadata, a summary banner, and per-severity tables of messages.
On the /validation page
/validation runs both checks in the browser with no upload and no account. Three tabs share one input:
| Tab | What it shows |
|---|---|
| Validate | The Khronos report: summary banner, model metadata, and per-severity message tables. |
| Inspect | A glTF-Transform pass the spec check does not cover: file and texture weight, triangle and draw-call counts, extensions used, and ranked optimization suggestions. |
| Records | On-chain attestations for an agent, and the form that submits a new one. |
Load a model three ways: drop a .glb/.gltf on the drop zone, click it to open the file picker (it is in the tab order, so this works from the keyboard), or paste a URL and press Fetch. The sample chips load Khronos reference models from jsDelivr. Both checks run in parallel on the same bytes, so opening Inspect after a run needs no second load. Every state has a designed result: an unreadable file, a fetch the host refuses (CORS is the usual cause), or a validator crash each render a failure card naming the cause, what to try next, and a Try again button that reruns the same input. Nothing leaves the browser on either lane.
Each report offers Download JSON. Sign & pin on-chain hands the in-memory report straight to the Records submit flow with its keccak256 hash precomputed, skipping the download-and-re-upload round trip.
The tab is reflected in the URL hash (#validate, #inspect, #records), and the Records tab reads ?agent= and ?chain= from the query string, so a specific agent's records are linkable.
Via the agent
Ask the agent in natural language:
"Validate this model."
"Are there any issues with this GLB?"
"Does this file have errors?"
The agent runs the validate-model skill, reads the current validation state, and responds conversationally — explaining any major errors and their likely causes.
The agent's emotional state also reflects the result:
- Clean model (0 errors) →
celebrationemotion (slight smile, head nod) - Errors found →
concern+empathyemotions
Programmatically
The Validator class is used internally by the viewer. It accepts a file URL and a Three.js asset map for multi-file glTF scenes:
import { Validator } from './src/validator.js';
const validator = new Validator(containerElement);
await validator.validate(rootFileURL, rootPath, assetMap, loaderResponse);
const { issues, errors, warnings, hints, infos, info } = validator.report;
console.log(issues.numErrors); // 0 = clean
errors, warnings, hints, and infos are pre-filtered arrays of messages, with repeated high-volume errors already aggregated.
Model stats overlay
Separate from validation, the Model Info overlay (rendered via createModelInfo) displays live geometry stats computed from the loaded Three.js scene:
| Stat | Source |
|---|---|
| Meshes | Count of Mesh, Points, and Line nodes |
| Vertices | geometry.attributes.position.count per mesh |
| Triangles | Index count ÷ 3 (or position count ÷ 3 for unindexed geometry) |
| Materials | Unique material UUIDs across all meshes |
| Textures | Unique texture UUIDs found on all materials |
| Animations | Animation clip count passed from the loader |
Feature chips — Skinned, Morph, Animated, plus material type names — appear below the stats.
On-chain validation attestation
Validation results can be attested on-chain through two complementary mechanisms.
ValidationRegistry (ERC-8004)
For registered agents, a validation record can be written to the ValidationRegistry smart contract. The registry is currently deployed on the testnets only (e.g. Base Sepolia, chain ID 84532); mainnet deployment is pending, so use a testnet chain ID.
The registry is request/response based: the agent's owner (or an approved operator) opens a request naming a validator, and only that validator may answer it. recordValidation() drives both legs from the connected wallet, so that wallet has to own the agent (or be its operator):
import { recordValidation, hashReport, reportPassed } from './src/erc8004/validation-recorder.js';
// Determine pass/fail
const passed = reportPassed(validationReport); // true if numErrors === 0
// Optionally pin the full report to IPFS first
const { txHash, requestTxHash, requestHash, proofHash, proofURI } = await recordValidation({
agentId: 42,
report: validationReport,
signer: connectedWallet, // the agent's owner, or an approved operator
chainId: 84532, // Base Sepolia (ValidationRegistry is testnet-only for now)
apiToken: IPFS_API_TOKEN, // for pinning
pin: true,
});
requestTxHash is null when a request for this report already existed and only the verdict had to be sent.
The hash stored on-chain is keccak256(JSON.stringify(report)). Anyone can recompute it:
- Re-run the validator on the same GLB file.
hashReport(report)produces the same hash if the input is identical.- Query
ValidationRegistry.getValidationStatus(requestHash)(orgetAgentValidations(agentId)for every request id on the agent) and compare itsresponseHash.src/erc8004/validation-recorder.jswraps this asgetLatestValidation({ agentId, runner, chainId }).
The registry has no on-chain validator allow-list: any address the owner requests can answer. Which verdicts three.ws presents as "Validated" is off-chain policy, maintained in public/.well-known/validators.json. See specs/VALIDATORS.md for how to be recognized, and docs/erc8004/validation-attestation.md for the platform's own automatic attestation flow.
The minimum check suite for a pass verdict includes:
glb-schema— file parses as valid GLB with all required chunksgltf-validator— Khronos validator reports zero errorsmanifest-integrity— the agent card'smodel.sha256matches the actual bytescard-schema— the card validates against the three.ws Card v1 spec
ValidationRegistry (Solana)
Solana agents (Metaplex Core assets) get the same on-chain validation guarantee
without a deployed registry contract. On Solana, attestations are first-class
SPL Memo transactions indexed into the solana_attestations table — that
index is the registry. A glTF/schema validation is a threews.validation.v1
memo with subkind: "glb-schema", signed by the platform validator and carrying
the same proof fields as the EVM record.
The platform validator signs and records automatically when an agent is
registered (/api/agents/solana-register-confirm), and on demand:
// POST /api/agents/solana-validate (owner-authenticated)
// body: { asset_pubkey, network: "mainnet"|"devnet", glb_url? }
// glb_url defaults to the agent's avatar GLB.
const res = await fetch('/api/agents/solana-validate', {
method: 'POST',
headers: { 'content-type': 'application/json' },
credentials: 'include',
body: JSON.stringify({ asset_pubkey, network: 'mainnet' }),
}).then((r) => r.json());
// → { passed, signature, proof_hash, proof_uri, model_sha256, validator, explorer }
The on-chain memo payload:
{
"v": 1,
"kind": "threews.validation.v1",
"subkind": "glb-schema",
"agent": "<asset pubkey>",
"ts": 1781483899,
"passed": true,
"proof_hash": "<sha256 of the canonical report JSON>",
"proof_uri": "<URL to the full pinned report>",
"model_sha256": "<sha256 of the GLB bytes>",
"source": "threews.model-check"
}
The proof hash is sha256(JSON.stringify(report)) (Solana convention; the EVM
side uses keccak256). Anyone can recompute it: re-run the validator on the same
GLB, JSON.stringify the report, sha256 it, and compare against proof_hash in
the memo. Read the latest and history:
GET /api/agents/solana-validation?asset=<pubkey>&network=mainnet
→ { latest, history[], count, last_indexed_at }
The validation status also rides on the agent card
(/api/agents/solana-card, validation block) and renders as a model
verified / model failed badge on the agent passport. Schema:
/.well-known/agent-attestation-schemas. Recording is gated to
the platform validator key (ATTEST_AGENT_SECRET_KEY); re-attesting an identical
report is idempotent (returns the existing signature, no duplicate tx).
Signed attestation (off-chain)
For lighter-weight use cases, src/attestations/gltf.js provides a wallet-signed JSON attestation that does not require a blockchain transaction:
import { createGlTFAttestation, verifyGlTFAttestation } from './src/attestations/gltf.js';
// Create
const attestation = await createGlTFAttestation({
glbBlob, // raw GLB as a Blob
validatorReport, // gltf-validator result
signer, // ethers Signer
agentId: '42',
});
// Verify (no wallet required)
const { valid, issuer, reasons } = await verifyGlTFAttestation({
attestation,
glbBlob,
trustedIssuers: ['0xabc...'], // optional allowlist
});
The signing message binds together the agent ID, a SHA-256 hash of the GLB bytes, and a hash of the validator summary { errors, warnings, severityMax }. Tampering with any of these breaks signature recovery. Store the attestation JSON alongside the GLB (for example as attestations/gltf-validator.json) and reference it from the agent manifest's attestations array.
Checking past records
import { getLatestValidation } from './src/erc8004/validation-recorder.js';
import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const record = await getLatestValidation({
agentId: 42,
runner: provider,
chainId: 84532, // ValidationRegistry is testnet-only for now
kind: 'glb-schema',
});
console.log(record.passed); // boolean
console.log(record.proofHash); // 0x-prefixed keccak256
console.log(record.proofURI); // ipfs://... link to the full report
The ValidationDashboard UI (src/validation-ui.js) wraps these calls with a drag-and-drop file picker for submitting new records.
Best practices for clean GLBs
Following these guidelines before exporting will avoid the most common validation errors:
Geometry
- Apply all modifiers before exporting (Blender: enable Apply Modifiers in the glTF exporter).
- Delete loose vertices and zero-area faces.
- Avoid non-manifold geometry if the model will be used for physics or fabrication.
Normals and tangents
- Enable Normals in the Blender glTF exporter.
- If you see
ACCESSOR_NON_UNITorMESH_PRIMITIVE_TANGENT_SPACE_INVALID, clear custom split normals data and re-export.
Textures
- Use PNG for maps that need transparency (albedo with alpha).
- Use JPEG for fully opaque maps (roughness, metallic, AO) to save space.
- For GPU-compressed textures, use KTX2 (exported via Blender's KHR_texture_basisu extension).
- Avoid embedding textures larger than 4096×4096; prefer 2048×2048 for real-time use.
Animations
- Name every clip descriptively —
"idle","wave","run"— because theplay_clipagent tool finds clips by name. - Keep keyframe times strictly ascending; duplicate or reversed timestamps cause
ACCESSOR_ANIMATION_INPUT_NON_INCREASING.
Housekeeping
- Remove unused materials, textures, and shape keys before the final export. These inflate file size and produce
UNUSED_OBJECTwarnings. - Use Draco mesh compression for geometry-heavy models (reduces GLB size 5–10× with negligible visual loss).
Cross-viewer testing Check your file in at least two other viewers before registering it:
- model-viewer.dev — good baseline for web use
- Babylon.js sandbox — strict PBR interpretation
- three.ws itself — run validation and read the report
Validation UI components
Four components render validation state in the browser:
| Component | File | Purpose |
|---|---|---|
ValidatorToggle |
src/components/validator-toggle.jsx |
Compact status bar; shows issue counts and severity class. Clicking opens the full report. |
ValidatorReport |
src/components/validator-report.jsx |
Full report panel: model metadata, summary banner, per-severity message tables, and a JSON download link. |
ValidatorTable |
src/components/validator-table.jsx |
Tabular view of messages for one severity level (Code / Message / Pointer columns). |
InspectReport |
src/components/inspect-report.jsx |
Performance panel for the /validation Inspect tab: stat cards, optimization suggestions, extension and texture tables. |
The toggle's CSS class reflects the highest severity: level-0 (errors), level-1 (warnings), level-2 (infos), level-3 (hints), or no class (clean). Style these classes to match your embedding context.
Related
- ERC-8004 identity: the registry contracts validation records attach to
- Reputation: the human-feedback counterpart to validation
- 3D asset pipeline: formats, optimization, and export guidance
- Provenance: signed content credentials for generated models