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.5 KB
Raw Blame
// Cinematic rendering defaults shared by every 3D viewer on the platform.
//
// Extracted from the pattern proven in /irl (src/irl.js) and the avatar
// result viewers (TalkScene, src/voice/talk-scene.js): ACES filmic tone
// mapping, correct sRGB output color space, image-based lighting from a
// real HDRI (falling back to a procedural room environment when the
// network asset hasn't loaded yet or a surface opts out for size), and a
// ground contact shadow that catches without requiring a visible floor.
//
// Any surface constructing its own WebGLRenderer should call
// `applyCinematicDefaults(renderer)` right after construction and
// `loadEnvironment(renderer, scene, preset)` once the scene exists, instead
// of re-deriving these values per file.

import {
	ACESFilmicToneMapping,
	SRGBColorSpace,
	VSMShadowMap,
	PMREMGenerator,
	Box3,
	PlaneGeometry,
	ShadowMaterial,
	Mesh,
} from 'three';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';

/** Curated HDRI set, served from our own static assets (CC0, Poly Haven origin). */
export const HDRI_PRESETS = {
	studio: '/hdri/studio.hdr',
	outdoor: '/hdri/outdoor.hdr',
	sunset: '/hdri/sunset.hdr',
};

/**
 * The same three environments at 512x256, about 360 KB each instead of 1.4 MB.
 *
 * The full-size files are the largest asset any 3D page downloads: on a Pixel 5
 * over slow 4G, `/hdri/outdoor.hdr` was 1,435 KB of `/play`'s 5,470 KB, which is
 * seven seconds of radio time before the world is lit. The map is PMREM-
 * prefiltered into irradiance before it lights anything, so almost all of that
 * resolution is discarded on the way in; what has to survive the downscale is
 * the light's ENERGY, and it does, to within 0.4% of the original's mean
 * radiance (see scripts/build-hdri-mobile.mjs, which regenerates and verifies
 * these). What is genuinely lost is the peak of the sun disc, so the sharpest
 * mirror highlight on a metal is softer here. That is the right thing to trade
 * on a phone and the wrong thing to trade on a desktop, which is why this is a
 * tier choice rather than a replacement.
 */
export const HDRI_PRESETS_MOBILE = {
	studio: '/hdri/studio-mobile.hdr',
	outdoor: '/hdri/outdoor-mobile.hdr',
	sunset: '/hdri/sunset-mobile.hdr',
};

/** Render quality tiers a viewer can request. 'mobile' matches the low-end /club profile. */
export const QUALITY_TIERS = {
	high: { pixelRatioCap: 2, shadows: true, hdri: true },
	// `hdriMobile` picks the 512x256 copy. 'medium' is where a real mid-tier
	// phone lands (coarse pointer, 4 GB of RAM is not "low"), and it was pulling
	// the full 1.4 MB file; only the weakest tier opted out, and opting out
	// entirely is a worse answer than a smaller map.
	medium: { pixelRatioCap: 1.5, shadows: true, hdri: true, hdriMobile: true },
	mobile: { pixelRatioCap: 1, shadows: false, hdri: false },
};

/**
 * Pick a quality tier from real capability signals, matching src/club-perf.js.
 * @param {object} [env]
 * @returns {'high'|'medium'|'mobile'}
 */
export function detectQualityTier(env = {}) {
	const nav = env.navigator ?? (typeof navigator !== 'undefined' ? navigator : {});
	const win = env.window ?? (typeof window !== 'undefined' ? window : {});
	const ua = String(nav.userAgent || '');
	const isMobile = /(iPhone|iPad|Android|Mobi)/i.test(ua);
	const lowMem = (nav.deviceMemory ?? 8) < 4;
	const lowCores = (nav.hardwareConcurrency ?? 8) < 4;
	const coarse = !!(win.matchMedia && win.matchMedia('(any-pointer: coarse)').matches);
	if (env.gl && isSoftwareRenderer(env.gl)) return 'mobile';
	if (isMobile && (lowMem || lowCores)) return 'mobile';
	if (coarse || lowMem || lowCores) return 'medium';
	return 'high';
}

/**
 * True when WebGL is being rasterised on the CPU (SwiftShader, llvmpipe,
 * Mesa software paths): shadows and normal maps cost seconds a frame there,
 * so such a session gets the lightest tier whatever the host's specs say.
 * @param {WebGLRenderingContext|WebGL2RenderingContext} gl
 */
export function isSoftwareRenderer(gl) {
	try {
		const dbg = gl.getExtension('WEBGL_debug_renderer_info');
		const name = String(dbg ? gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER));
		return /SwiftShader|llvmpipe|softpipe|Software|Microsoft Basic Render/i.test(name);
	} catch {
		return false;
	}
}

/**
 * Apply ACES tone mapping + correct color management + soft shadow type to
 * a renderer. Call once, right after construction.
 * @param {import('three').WebGLRenderer} renderer
 * @param {object} [opts]
 * @param {number} [opts.exposure] - toneMappingExposure, default 1.15 (matches /irl)
 * @param {'high'|'medium'|'mobile'} [opts.tier]
 */
export function applyCinematicDefaults(renderer, opts = {}) {
	const tier = QUALITY_TIERS[opts.tier] ? opts.tier : 'high';
	const budget = QUALITY_TIERS[tier];
	renderer.outputColorSpace = SRGBColorSpace;
	renderer.toneMapping = ACESFilmicToneMapping;
	renderer.toneMappingExposure = opts.exposure ?? 1.15;
	renderer.setPixelRatio(Math.min(typeof window !== 'undefined' ? window.devicePixelRatio : 1, budget.pixelRatioCap));
	if (budget.shadows) {
		renderer.shadowMap.enabled = true;
		renderer.shadowMap.type = VSMShadowMap;
	} else {
		renderer.shadowMap.enabled = false;
	}
	return budget;
}

const _envCache = new Map();

/**
 * Load a curated HDRI as the scene's IBL environment, PMREM-prefiltered.
 *
 * The procedural RoomEnvironment is installed FIRST, synchronously, every time.
 * It is convolved from a handful of emissive boxes and costs a millisecond, so
 * it lights the scene on its very first frame. The HDRI then replaces it when it
 * arrives. This ordering matters because the curated HDRIs are 1-2 MB files: a
 * scene that waited for one rendered its metals and roughness response unlit for
 * as long as that download took (measured at ~8s into a cold /play boot), then
 * popped to full lighting all at once. Now the pop is a refinement of an already
 * correct image rather than the moment the world becomes lit.
 *
 * The room environment is also the permanent answer when `preset` is null (the
 * 'mobile'/'low' tier opts out of HDRIs entirely) or when the fetch fails.
 * @param {import('three').WebGLRenderer} renderer
 * @param {import('three').Scene} scene
 * @param {'studio'|'outdoor'|'sunset'|null} preset
 * @param {object} [opts]
 * @param {'high'|'medium'|'mobile'} [opts.tier] - which copy of the HDRI to
 *   fetch. Defaults to the same capability probe applyCinematicDefaults uses, so
 *   a caller that never passed a tier still stops sending a phone 1.4 MB.
 */
export async function loadEnvironment(renderer, scene, preset = 'studio', opts = {}) {
	const tier = QUALITY_TIERS[opts.tier] ? opts.tier : detectQualityTier();
	const sources = QUALITY_TIERS[tier].hdriMobile ? HDRI_PRESETS_MOBILE : HDRI_PRESETS;
	const pmrem = new PMREMGenerator(renderer);
	pmrem.compileEquirectangularShader();
	const roomTarget = pmrem.fromScene(new RoomEnvironment(), 0.04);
	scene.environment = roomTarget.texture;
	scene.environmentIntensity ??= 1;
	if (!preset || !sources[preset]) {
		// PMREMGenerator holds its own materials and LOD planes; the render target
		// it just handed back stays valid after the generator is disposed, so this
		// frees the scratch without touching the environment map itself.
		pmrem.dispose();
		return scene.environment;
	}
	try {
		// Keyed by URL, not by preset name: the same preset resolves to a different
		// file per tier, and caching by name alone would hand a page that switched
		// tiers the wrong resolution back.
		const url = sources[preset];
		let hdrTexture = _envCache.get(url);
		if (!hdrTexture) {
			// HDRLoader is the same decoder RGBELoader wraps; RGBELoader is a
			// deprecated alias since three r180 and logs a warning on every use.
			const { HDRLoader } = await import('three/addons/loaders/HDRLoader.js');
			hdrTexture = await new HDRLoader().loadAsync(url);
			_envCache.set(url, hdrTexture);
		}
		const envTarget = pmrem.fromEquirectangular(hdrTexture);
		// Another loadEnvironment call (a coin switch rebuilding the world, a stage
		// swapping presets) may have re-pointed the environment while this HDRI was
		// in flight. Losing that race means our map is stale: free it rather than
		// stamp it over the newer one.
		if (scene.environment === roomTarget.texture) scene.environment = envTarget.texture;
		else envTarget.dispose();
		roomTarget.dispose();
		return scene.environment;
	} catch {
		// Fetch or decode failed. The room environment installed above stands, so
		// the scene is still lit; there is nothing to recover.
		return scene.environment;
	} finally {
		pmrem.dispose();
	}
}

/**
 * A ShadowMaterial plane that renders invisible except where a shadow
 * falls on it, giving a soft ground-contact shadow without a visible
 * floor. Sized/positioned from the target object's bounding box, so it
 * works for any model scale. Call again after the model changes size.
 * @param {import('three').Scene} scene
 * @param {import('three').Object3D} target
 * @param {import('three').Mesh} [existing] - reuse a prior catcher plane
 * @param {number} [opacity]
 */
export function updateGroundContactShadow(scene, target, existing, opacity = 0.35) {
	const b = new Box3().setFromObject(target);
	if (!Number.isFinite(b.min.y)) return existing ?? null;
	const footprint = Math.max(b.max.x - b.min.x, b.max.z - b.min.z, 1);
	const size = footprint * 6;
	let plane = existing;
	if (!plane) {
		plane = new Mesh(new PlaneGeometry(1, 1), new ShadowMaterial({ opacity }));
		plane.rotation.x = -Math.PI / 2;
		plane.receiveShadow = true;
		scene.add(plane);
	}
	plane.scale.set(size, size, 1);
	plane.position.set((b.min.x + b.max.x) / 2, b.min.y, (b.min.z + b.max.z) / 2);
	return plane;
}