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
// Docs World scene: the documentation rendered as a place.
//
// Fourteen nav sections (from /docs/nav.json, the same manifest the classic
// docs sidebar renders) become fourteen glowing pavilions on a ring around a
// central plaza. Each pavilion carries a portal disc in its section colour and
// a floating label. Walking up to one (or tapping it) opens that section's
// page list; picking a page opens the in-world reader (reader.js) over the
// live markdown at /docs/<slug>.md.
//
// Everything here is deliberately cheap: emissive materials instead of
// per-pavilion lights, canvas-texture sprites for text, one hemisphere + one
// directional light, and a vertex-coloured dome for the sky. The whole scene
// draws in well under a millisecond on integrated GPUs so phones keep 60fps.
import {
AdditiveBlending,
BackSide,
BufferAttribute,
BufferGeometry,
CanvasTexture,
CircleGeometry,
Color,
CylinderGeometry,
DirectionalLight,
Fog,
Group,
HemisphereLight,
Mesh,
MeshBasicMaterial,
MeshStandardMaterial,
PerspectiveCamera,
Points,
PointsMaterial,
RingGeometry,
Scene,
SphereGeometry,
Sprite,
SpriteMaterial,
SRGBColorSpace,
TorusGeometry,
} from 'three';
import { createRenderer } from '../webgl-support.js';
// Matches the classic docs theme (--docs-bg / --docs-accent) so switching
// surfaces reads as one product.
const BG = 0x09090f;
const ACCENT = 0x8b5cf6;
export const WORLD_RADIUS = 38; // player walk bound
export const RING_RADIUS = 24; // pavilion ring
export const PAVILION_TRIGGER = 4.2; // proximity that arms "enter section"
// Stable per-section colour: golden-angle hue walk from the docs purple, so
// any number of sections stays evenly distributed and recognisable.
export function sectionColor(i) {
const c = new Color();
c.setHSL(((262 + i * 137.5) % 360) / 360, 0.62, 0.62);
return c;
}
function makeLabelTexture(title, sub, colorHex) {
const dpr = Math.min(2, globalThis.devicePixelRatio || 1);
const w = 512 * dpr;
const h = 160 * dpr;
const canvas = document.createElement('canvas');
canvas.width = w;
canvas.height = h;
const ctx = canvas.getContext('2d');
ctx.scale(dpr, dpr);
const rw = 512;
const rh = 160;
ctx.fillStyle = 'rgba(12, 12, 22, 0.82)';
ctx.strokeStyle = colorHex;
ctx.lineWidth = 2.5;
ctx.beginPath();
// Safari < 16 has no ctx.roundRect; trace the same shape by hand.
if (typeof ctx.roundRect === 'function') {
ctx.roundRect(6, 6, rw - 12, rh - 12, 22);
} else {
const x = 6, y = 6, w2 = rw - 12, h2 = rh - 12, r = 22;
ctx.moveTo(x + r, y);
ctx.arcTo(x + w2, y, x + w2, y + h2, r);
ctx.arcTo(x + w2, y + h2, x, y + h2, r);
ctx.arcTo(x, y + h2, x, y, r);
ctx.arcTo(x, y, x + w2, y, r);
ctx.closePath();
}
ctx.fill();
ctx.globalAlpha = 0.85;
ctx.stroke();
ctx.globalAlpha = 1;
ctx.textAlign = 'center';
ctx.fillStyle = '#f4f1ff';
ctx.font = '600 44px Inter, system-ui, sans-serif';
ctx.fillText(title, rw / 2, sub ? 74 : 92, rw - 60);
if (sub) {
ctx.fillStyle = 'rgba(228, 223, 255, 0.66)';
ctx.font = '400 28px Inter, system-ui, sans-serif';
ctx.fillText(sub, rw / 2, 118, rw - 80);
}
const tex = new CanvasTexture(canvas);
tex.colorSpace = SRGBColorSpace;
tex.anisotropy = 4;
return tex;
}
// Base footprint of the central welcome sign, in world units, before resize()
// fits it to the viewport's horizontal field of view.
// Pavilion sign height. The portal ring crowns at 3.425 (y 1.9 + radius 1.45 +
// tube 0.075) and the label sprite is 2 units tall, so anything below 4.43 is
// overlapped by the ring.
const LABEL_Y = 4.75;
const BEACON_LABEL_SCALE = 0.8;
const BEACON_LABEL_W = 6.4 * BEACON_LABEL_SCALE;
const BEACON_LABEL_H = 2 * BEACON_LABEL_SCALE;
export function makeLabelSprite(title, sub, colorHex, scale = 1) {
const material = new SpriteMaterial({
map: makeLabelTexture(title, sub, colorHex),
transparent: true,
depthWrite: false,
});
const sprite = new Sprite(material);
sprite.scale.set(6.4 * scale, 2 * scale, 1);
return sprite;
}
function makeGroundTexture(sectionCount) {
const size = 1024;
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
const ctx = canvas.getContext('2d');
const c = size / 2;
const base = ctx.createRadialGradient(c, c, 0, c, c, c);
base.addColorStop(0, '#12121f');
base.addColorStop(0.45, '#0d0d17');
base.addColorStop(1, '#09090f');
ctx.fillStyle = base;
ctx.fillRect(0, 0, size, size);
// Spokes from the plaza out to each pavilion, plus plaza + ring roads.
ctx.strokeStyle = 'rgba(139, 92, 246, 0.16)';
ctx.lineWidth = 10;
const ringPx = (RING_RADIUS / WORLD_RADIUS) * c * 0.96;
for (let i = 0; i < sectionCount; i++) {
const a = (i / sectionCount) * Math.PI * 2;
ctx.beginPath();
ctx.moveTo(c + Math.cos(a) * c * 0.1, c + Math.sin(a) * c * 0.1);
ctx.lineTo(c + Math.cos(a) * ringPx, c + Math.sin(a) * ringPx);
ctx.stroke();
}
ctx.lineWidth = 6;
ctx.strokeStyle = 'rgba(139, 92, 246, 0.2)';
ctx.beginPath();
ctx.arc(c, c, c * 0.1, 0, Math.PI * 2);
ctx.stroke();
ctx.strokeStyle = 'rgba(139, 92, 246, 0.1)';
ctx.beginPath();
ctx.arc(c, c, ringPx, 0, Math.PI * 2);
ctx.stroke();
const tex = new CanvasTexture(canvas);
tex.colorSpace = SRGBColorSpace;
tex.anisotropy = 4;
return tex;
}
export function makeSkyDome() {
// Vertex-coloured dome: near-black zenith into a purple horizon glow.
const geo = new SphereGeometry(220, 24, 12);
const pos = geo.attributes.position;
const colors = new Float32Array(pos.count * 3);
const top = new Color(0x08070f);
const horizon = new Color(0x191330);
const tmp = new Color();
for (let i = 0; i < pos.count; i++) {
const y = pos.getY(i) / 220; // -1..1
const t = Math.max(0, Math.min(1, (y + 0.15) / 0.7));
tmp.copy(horizon).lerp(top, t);
colors[i * 3] = tmp.r;
colors[i * 3 + 1] = tmp.g;
colors[i * 3 + 2] = tmp.b;
}
geo.setAttribute('color', new BufferAttribute(colors, 3));
return new Mesh(
geo,
new MeshBasicMaterial({ vertexColors: true, side: BackSide, fog: false, depthWrite: false }),
);
}
export function makeStars(count = 420) {
const positions = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
// Random point on an upper-hemisphere shell so stars never sit below the
// horizon glow.
const r = 150 + Math.random() * 50;
const theta = Math.random() * Math.PI * 2;
const phi = Math.acos(0.12 + Math.random() * 0.85);
positions[i * 3] = r * Math.sin(phi) * Math.cos(theta);
positions[i * 3 + 1] = r * Math.cos(phi);
positions[i * 3 + 2] = r * Math.sin(phi) * Math.sin(theta);
}
const geo = new BufferGeometry();
geo.setAttribute('position', new BufferAttribute(positions, 3));
const mat = new PointsMaterial({
color: 0xbdb0ff,
size: 0.9,
sizeAttenuation: true,
transparent: true,
opacity: 0.75,
fog: false,
depthWrite: false,
});
return new Points(geo, mat);
}
/**
* Build one pavilion: platform, portal ring + shimmer disc, floating label.
* Returns the group plus the parts the frame loop animates.
*/
function buildPavilion(section, index, count) {
const angle = (index / count) * Math.PI * 2;
const color = sectionColor(index);
const hex = '#' + color.getHexString();
const group = new Group();
group.position.set(Math.cos(angle) * RING_RADIUS, 0, Math.sin(angle) * RING_RADIUS);
// Face the plaza so portals read from spawn.
group.rotation.y = -angle - Math.PI / 2;
const platform = new Mesh(
new CylinderGeometry(2.6, 2.9, 0.28, 28),
new MeshStandardMaterial({
color: 0x14141f,
roughness: 0.85,
metalness: 0.15,
emissive: color,
emissiveIntensity: 0.05,
}),
);
platform.position.y = 0.14;
group.add(platform);
const rim = new Mesh(
new TorusGeometry(2.75, 0.05, 10, 48),
new MeshBasicMaterial({ color, transparent: true, opacity: 0.7 }),
);
rim.rotation.x = Math.PI / 2;
rim.position.y = 0.29;
group.add(rim);
const portal = new Mesh(
new TorusGeometry(1.45, 0.075, 12, 48),
new MeshStandardMaterial({
color: 0x11101c,
roughness: 0.4,
metalness: 0.5,
emissive: color,
emissiveIntensity: 1.1,
}),
);
portal.position.y = 1.9;
group.add(portal);
const shimmer = new Mesh(
new CircleGeometry(1.36, 40),
new MeshBasicMaterial({
color,
transparent: true,
opacity: 0.16,
blending: AdditiveBlending,
depthWrite: false,
}),
);
shimmer.position.y = 1.9;
group.add(shimmer);
const pageCount = section.links.filter((l) => l.path).length;
const label = makeLabelSprite(
section.title,
pageCount === 1 ? '1 page' : pageCount + ' pages',
hex,
);
// Clear of the portal ring's crown (1.9 + 1.45 + 0.075) plus the sprite's own
// half-height: at 3.6 the ring cut straight across the "N pages" line from
// every angle, because sprite and torus share the pavilion's axis and so sit
// at the same depth. Height is the only separation that holds as the camera
// orbits.
label.position.y = LABEL_Y;
group.add(label);
return { group, portal, shimmer, label, angle, color, hex, section, index };
}
/**
* Build the whole scene.
*
* @param {HTMLCanvasElement} canvas
* @param {Array<{title:string, links:Array}>} sections nav.json sections
* @param {{ reducedMotion?: boolean }} [opts]
*/
export function createDocsWorld(canvas, sections, { reducedMotion = false } = {}) {
const renderer = createRenderer(
{ canvas, antialias: true, powerPreference: 'high-performance' },
{ fallback: canvas.parentElement },
);
renderer.setPixelRatio(Math.min(2, globalThis.devicePixelRatio || 1));
const scene = new Scene();
scene.background = new Color(BG);
scene.fog = new Fog(BG, 46, 150);
const camera = new PerspectiveCamera(58, 1, 0.1, 400);
camera.position.set(0, 3, 9);
scene.add(new HemisphereLight(0x8578c8, 0x0a0a14, 1.05));
const sun = new DirectionalLight(0xcabfff, 1.35);
sun.position.set(14, 26, 10);
scene.add(sun);
scene.add(makeSkyDome());
const stars = makeStars();
scene.add(stars);
const ground = new Mesh(
new CircleGeometry(WORLD_RADIUS + 4, 72),
new MeshStandardMaterial({
map: makeGroundTexture(sections.length),
roughness: 0.94,
metalness: 0.05,
}),
);
ground.rotation.x = -Math.PI / 2;
scene.add(ground);
const boundary = new Mesh(
new RingGeometry(WORLD_RADIUS + 1.2, WORLD_RADIUS + 1.5, 96),
new MeshBasicMaterial({ color: ACCENT, transparent: true, opacity: 0.28 }),
);
boundary.rotation.x = -Math.PI / 2;
boundary.position.y = 0.02;
scene.add(boundary);
// Central beacon: a slim monolith marking spawn, labelled with the surface
// name so a shared screenshot explains itself.
const beacon = new Group();
// Height stops below the sign that hangs on it (bottom edge y 1.6). At 3.4 the
// post ran the full height of the sign and, sharing its axis, split the title
// down the middle from every camera angle: the first thing a visitor saw read
// "three.ws ocs World". Shortening the post moves nothing else; the sign keeps
// the screen position tuned below.
const pillar = new Mesh(
new CylinderGeometry(0.16, 0.28, 1.5, 10),
new MeshStandardMaterial({
color: 0x191828,
roughness: 0.35,
metalness: 0.6,
emissive: ACCENT,
emissiveIntensity: 0.7,
}),
);
pillar.position.y = 0.75;
beacon.add(pillar);
const beaconLabel = makeLabelSprite(
'three.ws Docs World',
'walk to a pavilion to read',
'#8b5cf6',
BEACON_LABEL_SCALE,
);
// Height is set against the spawn camera, not against the ring labels' own y.
// The sign sits ~5m from the lens while the pavilions are 24m out, so its
// screen position is dominated by proximity: clearing the ring labels in
// world space (y 5.4) threw it off the top of the frame entirely. Just above
// the pillar's 3.4m crown keeps it legible on spawn and low enough to read
// against the empty plaza rather than across the pavilion label band.
//
// Below the pillar's crown rather than above it: the spawn camera pitches
// down about 24 degrees, which collapses everything at plaza height onto the
// same screen band as the 24m ring labels no matter how the sign is nudged
// around that height. Hanging it on the post instead drops it clear onto the
// dark plaza floor, and reads as a signpost rather than a floating card.
beaconLabel.position.y = 2.4;
beacon.add(beaconLabel);
scene.add(beacon);
const pavilions = sections.map((s, i) => {
const p = buildPavilion(s, i, sections.length);
scene.add(p.group);
return p;
});
function resize() {
const w = canvas.clientWidth || canvas.parentElement?.clientWidth || innerWidth;
const h = canvas.clientHeight || canvas.parentElement?.clientHeight || innerHeight;
renderer.setSize(w, h, false);
camera.aspect = w / h;
camera.updateProjectionMatrix();
// The beacon sign is sized in WORLD units, but how much screen it covers
// depends on the horizontal field of view, which shrinks with the aspect
// ratio. On a portrait phone that made the welcome sign span nearly the full
// width and stack over the ring labels behind it at spawn, before the
// distance fade in tick() has anything to fade. Scaling it with aspect keeps
// the sign the same relative size on every device; desktop (aspect >= 1.6) is
// unchanged, and the floor stops it shrinking into illegibility.
const fit = Math.min(1, Math.max(0.52, camera.aspect / 1.6));
beaconLabel.scale.set(BEACON_LABEL_W * fit, BEACON_LABEL_H * fit, 1);
}
resize();
let t = 0;
function tick(dt) {
// The beacon is a welcome sign, not a permanent overlay: once the visitor
// walks out toward the ring it would sit on top of the pavilion labels
// behind it, so fade it with distance. Deliberately ahead of the
// reduced-motion guard below, since this is a response to the visitor's
// own movement (not ambient decoration) and skipping it would strand the
// sign at full opacity exactly for the people least able to look past it.
const camDist = Math.hypot(camera.position.x, camera.position.z);
beaconLabel.material.opacity = Math.max(0, Math.min(1, (16 - camDist) / 8));
beaconLabel.visible = beaconLabel.material.opacity > 0.01;
if (reducedMotion) return;
t += dt;
for (const p of pavilions) {
p.shimmer.rotation.z += dt * 0.35;
p.label.position.y = LABEL_Y + Math.sin(t * 0.9 + p.index) * 0.07;
p.portal.material.emissiveIntensity = 1.1 + Math.sin(t * 1.6 + p.index * 2) * 0.25;
}
stars.rotation.y += dt * 0.004;
}
return { renderer, scene, camera, pavilions, resize, tick };
}