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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
/**
* Avatar material realism, proven in the real viewer at real breakpoints.
*
* Loads an avatar GLB in the actual /avatar-embed page, waits for the model,
* and screenshots it at 320, 768 and 1440 px wide. That page is the shipped
* surface every embedded three.ws avatar renders through, and it is the one
* that runs src/viewer.js's Viewer. /viewer is a different page entirely: it
* hands the model to `<model-viewer>`, which brings its own three.js and never
* calls the realism pass, and it rejects any ?src= that is not an absolute
* https URL, so pointing this script there measured nothing at all.
*
* Alongside each shot it reports
* what `src/shared/avatar-material-realism.js` actually did to the loaded
* scene: how many skin / eye / hair / teeth materials it upgraded, and the
* physical values that landed on each class. A screenshot alone cannot tell
* you whether the pass ran; the readback can.
*
* The readback rides three.js's own devtools hook (the same technique
* scripts/irl-realism-check.mjs uses): every Scene constructor dispatches an
* `observe` event on a global `__THREE_DEVTOOLS__` when one exists, so
* installing an EventTarget there before any page script runs hands us the live
* scene graph without a single source change.
*
* Usage:
* npm run dev
* node scripts/avatar-realism-shots.mjs
* node scripts/avatar-realism-shots.mjs --src=/avatars/selfie-girl.glb
* node scripts/avatar-realism-shots.mjs --base=http://localhost:3000 --out=docs/assets/avatar-realism
* node scripts/avatar-realism-shots.mjs --bg=light # light backdrop
* node scripts/avatar-realism-shots.mjs --src=/avatars/realistic-halfbody.glb --name=avatar-realism-halfbody
*
* Exits nonzero when no skin or eye material was upgraded: that means the pass
* did not reach the model, which is exactly the regression worth failing on.
*/
import { chromium } from 'playwright';
import { mkdir, writeFile } from 'node:fs/promises';
import path from 'node:path';
const args = Object.fromEntries(
process.argv
.slice(2)
.filter((a) => a.startsWith('--'))
.map((a) => {
const [k, ...rest] = a.replace(/^--/, '').split('=');
return [k, rest.length ? rest.join('=') : 'true'];
}),
);
const BASE = args.base || 'http://localhost:3000';
const SRC = args.src || '/avatars/realistic-male.glb';
// /avatar-embed understands three backdrops and nothing else: dark, light, and
// transparent. Transparent is its default and screenshots as pure black, which
// hides the rim light, so the shots are taken on the dark backdrop.
const BG = args.bg || 'dark';
// File-name stem, so a second subject can be captured into the same folder
// without overwriting the first one's shots.
const NAME = args.name || 'avatar-realism';
const OUT_DIR = path.resolve(args.out || 'docs/assets/avatar-realism');
// SwiftShader has to rasterize a skinned avatar under IBL; a cold first paint
// on the 1440px viewport is the slow case.
const LOAD_TIMEOUT = Number(args.timeout || 240_000);
// Vite's HMR client cannot open its websocket through a Codespaces port
// forward, so every dev-server page logs the same three lines regardless of what
// the page itself does. Recording them as page errors buries the ones that
// matter, so they are dropped here and the count of dropped lines is kept.
const DEV_SERVER_NOISE = [
/\[vite\] failed to connect to websocket/i,
/WebSocket connection to '.*' failed/i,
/WebSocket closed without opened/i,
];
function isDevServerNoise(text) {
return DEV_SERVER_NOISE.some((re) => re.test(text));
}
const BREAKPOINTS = [
{ label: '320', width: 320, height: 640 },
{ label: '768', width: 768, height: 1024 },
{ label: '1440', width: 1440, height: 900 },
];
// Installed before any page script: three.js dispatches `observe` on this for
// every Scene and WebGLRenderer it constructs.
const DEVTOOLS_HOOK = `
window.__THREE_DEVTOOLS__ = new EventTarget();
window.__qb04_scenes = [];
window.__THREE_DEVTOOLS__.addEventListener('observe', (event) => {
const obj = event.detail;
if (obj && obj.isScene) window.__qb04_scenes.push(obj);
});
`;
// Installed alongside the hook so it exists before any page script: walks every
// observed scene and reports the physical values the realism pass leaves behind,
// per class. It lives on `window` rather than being passed as a string because
// Playwright treats a string argument that PARSES as an arrow function as the
// function itself, so `waitForFunction('() => ...')` resolves on the first poll
// with the function object as its truthy result and never waits for anything.
// A named page function sidesteps that entirely.
const READBACK_HOOK = `
window.__qb04_readback = () => {
const SKIN = /(^|[_\\s-])(skin|body|face|head|torso|arm|leg|hand|feet|foot)(?=[_\\s-]|$)/i;
const WOLF = /wolf3d_(skin|body|head)/i;
const EYE = /(^|[_\\s-])(eye|cornea|iris|sclera)(left|right)?(?=[_\\s-]|$)/i;
const HAIR = /(^|[_\\s-])(hair|eyebrow|eyelash|beard|fur)(left|right|back|front)?(?=[_\\s-]|$)/i;
const TEETH = /(^|[_\\s-])(teeth|tongue|mouth)(?=[_\\s-]|$)/i;
const out = { meshes: 0, classes: {} };
for (const scene of window.__qb04_scenes || []) {
scene.traverse((node) => {
if (!node.isMesh || !node.material) return;
const n = (node.name || '') + ' ' + (node.material.name || '');
let cls = null;
if (WOLF.test(n) || SKIN.test(n)) cls = 'skin';
else if (EYE.test(n)) cls = 'eye';
else if (HAIR.test(n)) cls = 'hair';
else if (TEETH.test(n)) cls = 'teeth';
if (!cls) return;
out.meshes++;
const mats = Array.isArray(node.material) ? node.material : [node.material];
for (const m of mats) {
if (!m || !('roughness' in m)) continue;
(out.classes[cls] = out.classes[cls] || []).push({
mesh: node.name,
physical: !!m.isMeshPhysicalMaterial,
roughness: Number(m.roughness?.toFixed?.(3) ?? m.roughness),
metalness: m.metalness,
sheen: m.sheen ?? null,
clearcoat: m.clearcoat ?? null,
ior: m.ior ?? null,
specularIntensity: m.specularIntensity ?? null,
doubleSided: m.side === 2,
alphaTest: m.alphaTest ?? null,
});
}
});
}
return out;
};
`;
async function main() {
await mkdir(OUT_DIR, { recursive: true });
const browser = await chromium.launch({
args: ['--use-gl=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'],
});
const report = { src: SRC, base: BASE, capturedAt: new Date().toISOString(), shots: [] };
let sawUpgrade = false;
for (const bp of BREAKPOINTS) {
const page = await browser.newPage({ viewport: { width: bp.width, height: bp.height }, deviceScaleFactor: 1 });
await page.addInitScript(DEVTOOLS_HOOK);
await page.addInitScript(READBACK_HOOK);
const consoleErrors = [];
let suppressedNoise = 0;
const record = (text) => {
if (isDevServerNoise(text)) suppressedNoise++;
else consoleErrors.push(text);
};
page.on('console', (msg) => {
if (msg.type() === 'error') record(msg.text());
});
page.on('pageerror', (err) => record(String(err?.message || err)));
// hide-chrome drops the name plate and the animation picker, so the frame
// is the avatar and nothing else.
const url = `${BASE}/avatar-embed?model=${encodeURIComponent(SRC)}&hide-chrome=1&bg=${encodeURIComponent(BG)}`;
await page.goto(url, { waitUntil: 'load', timeout: LOAD_TIMEOUT });
// The realism pass runs inside setContent(), right after the GLB loads, so
// poll the scene graph rather than guessing at a fixed delay. Poll for a
// CLASSIFIED mesh, not merely any mesh: the viewer builds its shadow
// catcher and a stack of post-processing fullscreen quads before the GLB
// is fetched, so "some mesh exists" is true within a frame of page load
// and reading back there reports an empty avatar every time.
await page
.waitForFunction(() => (window.__qb04_readback?.()?.meshes || 0) > 0, null, { timeout: LOAD_TIMEOUT })
.catch(() => {});
const readback = await page.evaluate(() => window.__qb04_readback());
if ((readback.classes.skin?.length || 0) + (readback.classes.eye?.length || 0) > 0) sawUpgrade = true;
const file = path.join(OUT_DIR, `${NAME}-${bp.label}.png`);
await page.screenshot({ path: file });
report.shots.push({
breakpoint: bp.label,
viewport: `${bp.width}x${bp.height}`,
file: path.relative(process.cwd(), file),
readback,
consoleErrors,
suppressedDevServerNoise: suppressedNoise,
});
console.log(
`✓ ${String(bp.label).padEnd(5)} ${readback.meshes} classified mesh(es); ` +
Object.entries(readback.classes)
.map(([k, v]) => `${k}=${v.length}`)
.join(' ') +
(consoleErrors.length ? ` [${consoleErrors.length} console error(s)]` : ''),
);
await page.close();
}
await browser.close();
const jsonFile = path.join(OUT_DIR, `${NAME}-readback.json`);
await writeFile(jsonFile, `${JSON.stringify(report, null, '\t')}\n`);
console.log(`\nReadback → ${path.relative(process.cwd(), jsonFile)}`);
if (!sawUpgrade) {
console.error('No skin or eye material was upgraded: the realism pass did not reach this model.');
process.exit(1);
}
}
main().catch((err) => {
console.error('[avatar-realism-shots] fatal:', err);
process.exit(1);
});