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
// Cosmetic visual layer — turns a cosmetic's `visual` spec (sent in the server
// catalogue) into renderable Three.js objects layered over an avatar rig. This
// is the ONLY thing a cosmetic does: it changes how an avatar looks. Nothing
// here reads or writes any gameplay value.
//
// Three visual primitives, any of which a cosmetic may combine:
// tint — recolour the avatar's body materials (a dye). Blends toward the tint
// while keeping some original lightness, so shading/detail survive.
// prop — a GLB worn on the head (hats) or face (glasses), auto-fitted and
// anchored to the head bone so one asset sits right on any model.
// aura — a glowing, slowly-spinning ring at the avatar's feet.
//
// applyCosmetic() returns a handle: tick(dt) animates the aura, dispose() fully
// removes the layer and restores the original material colours. The rig owner
// re-applies after every avatar (re)load, since loading clears the rig.
import {
Group, Mesh, MeshBasicMaterial, RingGeometry, Box3, Vector3, Color,
AdditiveBlending, DoubleSide,
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { getMeshoptDecoder } from '../viewer/internal.js';
import { dracoLoader } from './avatar-rig.js';
import { log } from '../shared/log.js';
// Share the Draco-enabled decoder module + cache with the avatar loader so prop
// GLBs (which may be Draco-compressed) decode without a second decoder instance.
const _loader = new GLTFLoader();
_loader.setDRACOLoader(dracoLoader);
// three.ws GLBs may carry EXT_meshopt_compression — decoder required before load
const _meshoptReady = getMeshoptDecoder().then((d) => _loader.setMeshoptDecoder(d));
// Cache each prop's loaded scene once; every wearer gets a deep clone so they
// never share (and mutate) one another's meshes.
const _propCache = new Map(); // url -> Promise<Object3D|null>
function loadProp(url) {
if (!_propCache.has(url)) {
_propCache.set(url, _meshoptReady.then(() => _loader.loadAsync(url))
.then((g) => g.scene)
.catch((err) => { log.warn('[cosmetics] prop load failed:', url, err?.message); return null; }));
}
return _propCache.get(url);
}
// Recolour every body material as a *dye*: blend each material's colour most of
// the way toward the tint while keeping a fraction of the original, so the
// model's light/dark shading and detail survive instead of going flat (a hard
// `color.set(hex)` washes untextured meshes into a single block). Dedupes by
// material (a model often shares one across meshes) and remembers each original
// so dispose() restores it exactly.
const TINT_STRENGTH = 0.72; // how far toward the dye; the rest preserves detail
function applyTint(rig, hex) {
const tint = new Color(hex);
const restore = new Map(); // material -> original hex
rig.traverse((n) => {
if (!n.isMesh) return;
const mats = Array.isArray(n.material) ? n.material : [n.material];
for (const m of mats) {
if (!m || !m.color || restore.has(m)) continue;
restore.set(m, m.color.getHex());
m.color.lerp(tint, TINT_STRENGTH);
}
});
return () => { for (const [m, orig] of restore) m.color?.setHex(orig); };
}
// Find the rig's head bone so a worn prop can ride the actual skull through the
// idle/walk animation instead of floating at a fixed height. Prefers a real Bone
// named like a head joint (Mixamo `mixamorigHead`, VRM `Head`/`J_Bip_C_Head`,
// or plain `head`), skipping the `HeadTop_End`/`*_end` leaf joints. Returns null
// for rigs without a recognisable head (the fallback capsule, abstract avatars),
// where the prop falls back to a height-anchored position.
function findHeadBone(rig) {
let bone = null;
rig.traverse((o) => {
if (bone || !o.isBone) return;
const n = (o.name || '').toLowerCase();
if (n.includes('head') && !n.includes('end') && !n.includes('top')) bone = o;
});
return bone;
}
// A worn prop (hat / glasses / earrings). The GLB is auto-fitted to a head-ish
// width so one asset fits models of any height, anchored to the head bone when
// present (so it tracks head movement) and to a height fraction otherwise.
// `anchor` is 'head' (hats rest on the crown), 'face' (glasses sit at eye level),
// or 'ear' (earrings hang at cheek/ear level, slightly below the head bone).
const PROP_TARGET_WIDTH_M = 0.34; // ~ a human head's width
function mountProp(rig, height, url, anchor) {
const holder = new Group();
rig.add(holder);
const face = anchor === 'face';
const ear = anchor === 'ear';
const headBone = findHeadBone(rig);
// Per-anchor vertical + forward offsets from the head bone origin.
// ear: slightly below the head-bone centre where the ear canal sits.
// face: slight up + forward nudge to position on the eye line.
// head: higher up so hats sit on the crown, not inside the skull.
const upOffset = ear ? -0.03 * height : (face ? 0.02 : 0.05) * height;
const fwdOffset = face ? 0.05 : 0;
const fallbackY = height * (ear ? 0.78 : (face ? 0.82 : 0.86));
const tmp = new Vector3();
let model = null;
let cancelled = false;
const place = () => {
if (!model) return;
if (headBone) {
// Bone world position → rig-local (holder is a child of rig at unit scale),
// so the prop glues to the head every frame, riding the animation.
headBone.getWorldPosition(tmp);
rig.worldToLocal(tmp);
holder.position.set(tmp.x, tmp.y + upOffset, tmp.z + fwdOffset);
} else {
holder.position.set(0, fallbackY, fwdOffset);
}
};
loadProp(url).then((scene) => {
if (cancelled || !scene) return;
model = scene.clone(true);
model.traverse((n) => { if (n.isMesh) { n.castShadow = true; n.receiveShadow = false; } });
// Fit width to the target, then anchor the prop's reference point at the
// holder origin. Hats rest on their base (floor at y=0); glasses and
// earrings centre on the Y axis so their pivot is the midpoint of the mesh.
const box = new Box3().setFromObject(model);
const size = box.getSize(new Vector3());
const span = Math.max(size.x, size.z) || 1;
model.scale.setScalar(PROP_TARGET_WIDTH_M / span);
const fitted = new Box3().setFromObject(model);
const c = fitted.getCenter(new Vector3());
model.position.x -= c.x;
model.position.z -= c.z;
model.position.y -= (face || ear) ? c.y : fitted.min.y;
holder.add(model);
place();
});
return {
// Re-glue to the head each frame (cheap: one world-matrix read). No-op until
// the GLB has loaded, or static when the rig has no head bone.
tick: () => { if (headBone) place(); },
// Dispose = detach the holder only. The clone shares the cached source's
// geometry + materials (Object3D.clone(true) copies them by reference), so
// those GPU resources live once in _propCache and are reused by every wearer —
// disposing them here would corrupt the cache and other players' props. The
// cache holds one parsed scene per prop URL (a handful total), so it's bounded,
// not a leak; the clone's wrapper objects are freed for GC when the holder goes.
dispose: () => { cancelled = true; rig.remove(holder); },
};
}
// A glowing ground aura: a bright inner ring plus a softer outer halo, laid flat
// at the feet, additively blended so it reads as light. tick() spins it and
// gently pulses the halo.
function mountAura(rig, hex) {
const group = new Group();
const mkRing = (inner, outer, opacity) => {
const geo = new RingGeometry(inner, outer, 48);
const mat = new MeshBasicMaterial({
color: hex, transparent: true, opacity,
blending: AdditiveBlending, side: DoubleSide, depthWrite: false,
});
const ring = new Mesh(geo, mat);
ring.rotation.x = -Math.PI / 2;
return ring;
};
const core = mkRing(0.42, 0.58, 0.85);
const halo = mkRing(0.58, 0.92, 0.28);
group.add(halo, core);
group.position.y = 0.03;
rig.add(group);
let t = 0;
return {
tick: (dt) => {
t += dt;
group.rotation.y += dt * 0.6;
halo.material.opacity = 0.20 + 0.12 * (0.5 + 0.5 * Math.sin(t * 2));
},
dispose: () => {
rig.remove(group);
core.geometry.dispose(); core.material.dispose();
halo.geometry.dispose(); halo.material.dispose();
},
};
}
// Apply a cosmetic `visual` spec to a rig at a known head-anchor `height`.
// Returns { tick(dt), dispose() }. Safe to call before the avatar model has
// finished loading — tint simply finds no meshes yet (callers re-apply on load),
// while a prop/aura attach to the rig regardless.
export function applyCosmetic(rig, height, visual) {
if (!visual) return { tick() {}, dispose() {} };
const undo = [];
const tickers = [];
if (visual.tint) undo.push(applyTint(rig, visual.tint));
if (visual.prop) {
const prop = mountProp(rig, height, visual.prop, visual.anchor);
tickers.push(prop.tick); undo.push(prop.dispose);
}
if (visual.aura) {
const aura = mountAura(rig, visual.aura);
tickers.push(aura.tick); undo.push(aura.dispose);
}
return {
tick: (dt) => { for (const t of tickers) t(dt); },
dispose: () => { for (const fn of undo) { try { fn(); } catch {} } },
};
}