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
// Live 3D avatar for the /play boot loader.
//
// The boot loader (#kx-loading) covers the gap while the main scene bundle and
// avatar assets download. Instead of a bare spinner, we spin up a tiny WebGL
// canvas inside the loader card and render the real default avatar — loaded,
// posed into idle, and slowly turning under a soft key light — so the very
// first thing a player sees is a character, not a wait.
//
// Self-contained on purpose: this evaluates as soon as its module + Three.js
// chunk arrive (overlapping the main bundle's download), so the avatar is on
// screen as early as possible. It shares Three.js and the avatar-rig manifest
// with the scene, so the second GLB fetch is served from the browser cache.
//
// Hand-off: coincommunities.js awaits `window.__ccBootAvatar.ready` before it
// fades the loader out, then calls `dispose()`. `ready` ALWAYS resolves (even on
// WebGL/asset failure) so a missing avatar can never wedge the loader open.
import {
Scene, PerspectiveCamera, WebGLRenderer, Box3, Vector3,
HemisphereLight, DirectionalLight, AmbientLight,
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { AnimationManager } from '../animation-manager.js';
import { installVrmPlugin, prepareVrmModel } from './vrm-loader.js';
import {
AVATAR_DEFAULT, loadManifest, getLocomotionDefs, CLIP_IDLE,
resolveAvatarUrl, dracoLoader, meshoptReady,
} from './avatar-rig.js'; // also registers the real VRM plugin (side effect)
import { getRequestedAvatar } from './play-handoff.js';
import { log } from '../shared/log.js';
import { applyCinematicDefaults, loadEnvironment } from '../shared/cinematic-render.js';
const REDUCED_MOTION = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
const TURN_SPEED = 0.5; // radians/sec — a slow, premium turntable
function boot() {
const canvas = document.getElementById('kx-boot-avatar');
if (!canvas) return { ready: Promise.resolve(), dispose() {} };
let renderer, scene, camera, anim, model, raf = 0, last = 0, yaw = -0.35, alive = true;
let resolveReady;
const ready = new Promise((res) => { resolveReady = res; });
const done = () => { resolveReady?.(); resolveReady = null; };
try {
renderer = new WebGLRenderer({ canvas, alpha: true, antialias: true });
// Cinematic defaults (ACES tone mapping, sRGB output). This view is on
// screen for well under 6s (the loader's own safety net), so the
// environment uses the procedural fallback (no HDRI network fetch) to
// never compete with the real scene bundle's download.
applyCinematicDefaults(renderer, { exposure: 1.1, tier: 'medium' });
sizeToBox();
scene = new Scene();
loadEnvironment(renderer, scene, null);
scene.add(new HemisphereLight(0xffffff, 0x202028, 1.1));
const key = new DirectionalLight(0xffffff, 1.9);
key.position.set(1.4, 2.6, 2.2);
const rim = new DirectionalLight(0xbcd2ff, 0.7);
rim.position.set(-1.8, 1.4, -2.0);
scene.add(key, rim, new AmbientLight(0xffffff, 0.4));
camera = new PerspectiveCamera(28, 1, 0.05, 100);
} catch (err) {
// No WebGL — reveal the static fallback mark and let the loader proceed.
log.warn('[boot-avatar] WebGL unavailable:', err?.message);
canvas.parentElement?.classList.add('kx-boot-noavatar');
done();
return { ready, dispose() {} };
}
window.addEventListener('resize', sizeToBox, { passive: true });
// Preview the avatar this session should show — an `?avatar=` deep link (an
// agent's GLB via a "See in 3D" link) if present, otherwise the one the player
// chose (persisted in cc-avatar by the lobby / a create→play handoff) — not a
// generic default, so the first character they see while the scene loads is the
// right one. DRACO and meshopt are both wired in because most avatar GLBs are
// compressed (the default avatar uses EXT_meshopt_compression). Falls back to
// the default on any resolve/load failure so a broken pick never wedges the loader.
const loader = new GLTFLoader();
loader.setDRACOLoader(dracoLoader);
installVrmPlugin(loader);
meshoptReady
.then((decoder) => { if (decoder) loader.setMeshoptDecoder(decoder); })
.then(() => resolveAvatarUrl(getRequestedAvatar()))
.then((chosen) => loader.loadAsync(chosen).catch(() => loader.loadAsync(AVATAR_DEFAULT)))
.then(async (gltf) => {
if (!alive) return;
prepareVrmModel(gltf);
model = gltf.scene;
model.traverse((n) => { if (n.isMesh) { n.frustumCulled = false; n.castShadow = false; } });
scene.add(model);
// Feet on the ground, centred, framed from the chest up with a slight 3/4
// turn — a portrait, not a full body lost in the small frame.
const box = new Box3().setFromObject(model);
const size = new Vector3(); box.getSize(size);
const center = new Vector3(); box.getCenter(center);
model.position.x -= center.x;
model.position.z -= center.z;
model.position.y -= box.min.y;
const h = Math.max(0.4, size.y);
const target = new Vector3(0, h * 0.82, 0);
const frameH = h * 0.6;
const fov = (camera.fov * Math.PI) / 180;
const dist = (frameH / 2) / Math.tan(fov / 2) * 1.1;
camera.position.set(0, target.y, dist);
camera.lookAt(target);
// Settle into idle so it reads as a standing character, not a T-pose.
try {
await loadManifest();
const idle = getLocomotionDefs().find((d) => d.name === CLIP_IDLE);
if (idle && alive) {
anim = new AnimationManager();
anim.attach(model);
anim.setAnimationDefs([idle]);
await anim.loadAll();
await anim.crossfadeTo(CLIP_IDLE, 0);
}
} catch { /* render the bind pose */ }
if (!alive) return;
canvas.parentElement?.classList.add('kx-boot-ready');
last = performance.now();
loop(last, target);
done();
}).catch((err) => {
// Designed path, logged as telemetry rather than a warning: the loader is
// released on the line below and the card styles itself for the no-avatar
// case, so a blocked or missing GLB costs a decoration, never the boot. It
// is also the normal outcome behind an ad blocker or a venue filter.
log.info('[boot-avatar] avatar load failed:', err?.message);
canvas.parentElement?.classList.add('kx-boot-noavatar');
done();
});
// Safety net: never hold the loader more than 6s waiting on the avatar.
setTimeout(done, 6000);
function loop(now, target) {
if (!alive) return;
raf = requestAnimationFrame((t) => loop(t, target));
const dt = Math.min(0.05, (now - last) / 1000);
last = now;
if (!REDUCED_MOTION && model) {
yaw += TURN_SPEED * dt;
model.rotation.y = Math.sin(yaw) * 0.5 - 0.1; // gentle ease back and forth
}
anim?.update(dt);
renderer.render(scene, camera);
}
function sizeToBox() {
const r = canvas.getBoundingClientRect();
const w = Math.max(1, r.width || canvas.clientWidth || 220);
const h = Math.max(1, r.height || canvas.clientHeight || 280);
renderer.setSize(w, h, false);
if (camera) { camera.aspect = w / h; camera.updateProjectionMatrix(); }
}
function dispose() {
alive = false;
cancelAnimationFrame(raf);
window.removeEventListener('resize', sizeToBox);
try {
anim?.dispose?.();
model?.traverse((n) => {
if (!n.isMesh) return;
n.geometry?.dispose?.();
const mats = Array.isArray(n.material) ? n.material : [n.material];
for (const m of mats) {
if (!m) continue;
for (const k in m) { const v = m[k]; if (v && v.isTexture) v.dispose(); }
m.dispose?.();
}
});
renderer.dispose();
} catch { /* best-effort teardown */ }
}
return { ready, dispose };
}
window.__ccBootAvatar = boot();