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.

9.0 KB
Raw Blame
#!/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);
});