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
/**
* Body Studio — controller (P3)
* =============================
* The avatar surface of Agent Studio: choose the 3D body, customize its outfit,
* and shape how it moves. Every change drives the live stage avatar instantly
* (via the shared store + <agent-presence>) and persists the real record.
*
* • Body — the bound avatar (thumbnail + name), swap via the shared avatar
* picker (writes agent.avatar_id), deep-customize in the avatar
* editor, or spin up a new one. The default avatar is a real,
* always-present starter — an agent is never bodiless.
* • Movement — the full retargetable clip library (animation-presets.curate):
* click any clip to play it live on the stage, and pin a looping
* idle as the agent's resting pose (meta.studio.body.idleClip),
* which <agent-presence> honors everywhere on the platform.
*
* Mount: import { mountBodyStudio } from './body/body-studio.js';
* mountBodyStudio(container, { studio });
*/
import { apiFetch } from '../../api.js';
import { createAvatarPicker } from '../../avatar-picker.js';
import { curate } from '../../animation-presets.js';
const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) =>
({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]));
const DEFAULT_AVATAR = { id: null, name: 'Default starter', url: '/avatars/default.glb', thumbnailUrl: null };
export function mountBodyStudio(container, { studio }) {
if (container.dataset.bodyMounted) return;
container.dataset.bodyMounted = '1';
container.querySelector('.studio-empty')?.remove();
return new BodyStudio(container, studio);
}
class BodyStudio {
constructor(el, studio) {
this.el = el;
this.studio = studio;
this.state = {
loading: true,
error: null,
avatar: null, // resolved { id, name, url, thumbnailUrl }
clips: null, // { featured, groups } from curate()
openCat: null,
playing: null, // clip name currently previewing
};
this._picker = null;
this._render();
this._load();
}
_q(sel) { return this.el.querySelector(sel); }
get _idleClip() {
return this.studio.agent?.meta?.studio?.body?.idleClip || 'idle';
}
// The live stage avatar lives in the shell's stage; drive it directly for
// instant, real preview (the same element every other surface renders).
get _stage() {
return document.querySelector('.studio-stage agent-presence') || document.querySelector('agent-presence');
}
// ── Data ────────────────────────────────────────────────────────────────
async _load() {
this.state.loading = true;
this._renderBody();
try {
const [avatar, clips] = await Promise.all([this._resolveAvatar(), this._loadClips()]);
this.state.avatar = avatar;
this.state.clips = clips;
this.state.error = null;
} catch (err) {
this.state.error = err?.message || 'Could not load the body studio.';
} finally {
this.state.loading = false;
this._renderBody();
}
}
async _resolveAvatar() {
const id = this.studio.agent?.avatarId || null;
if (!id) return { ...DEFAULT_AVATAR };
try {
const res = await apiFetch(`/api/avatars/${id}`, { allowAnonymous: true });
if (!res.ok) return { ...DEFAULT_AVATAR, id, name: 'Your avatar' };
const { avatar } = await res.json();
return {
id,
name: avatar?.name || 'Your avatar',
url: avatar?.url || avatar?.model_url || avatar?.base_model_url || null,
thumbnailUrl: avatar?.thumbnail_url || null,
};
} catch {
return { ...DEFAULT_AVATAR, id, name: 'Your avatar' };
}
}
async _loadClips() {
const res = await fetch('/animations/manifest.json');
if (!res.ok) throw new Error('Could not load the animation library.');
const manifest = await res.json();
const defs = Array.isArray(manifest) ? manifest : manifest.clips || manifest.animations || [];
return curate(defs);
}
// ── Shell ─────────────────────────────────────────────────────────────────
_render() {
this.el.innerHTML = `<div class="bdy" data-root></div>`;
// Keep the resting-pose pin in sync if another surface edits the body bag.
this._unsub = this.studio.subscribe(() => {
if (!this.state.loading && this.state.clips) this._syncIdleMarks();
});
}
_renderBody() {
const host = this._q('[data-root]');
if (this.state.loading) { host.innerHTML = this._skeleton(); return; }
if (this.state.error) { host.innerHTML = this._errorState(this.state.error); this._bindError(); return; }
host.innerHTML = `${this._bodySection()}${this._movementSection()}`;
this._bind();
this._syncIdleMarks();
}
_skeleton() {
return `
<div class="bdy-skel">
<div class="bdy-skel-card"></div>
<div class="bdy-skel-row"></div>
<div class="bdy-skel-grid">${'<div class="bdy-skel-chip"></div>'.repeat(8)}</div>
</div>`;
}
_errorState(msg) {
return `
<div class="bdy-empty">
<div class="bdy-empty-glyph" aria-hidden="true">⚠</div>
<h3>Couldn’t load the body studio</h3>
<p>${esc(msg)}</p>
<button class="studio-btn studio-btn-ghost" data-action="retry">Try again</button>
</div>`;
}
// ── Body (avatar) ──────────────────────────────────────────────────────────
_bodySection() {
const a = this.state.avatar || DEFAULT_AVATAR;
const thumb = a.thumbnailUrl
? `<img src="${esc(a.thumbnailUrl)}" alt="" loading="lazy" />`
: `<div class="bdy-avatar-fallback" aria-hidden="true">◓</div>`;
const isDefault = !a.id;
return `
<section class="bdy-section" aria-labelledby="bdy-body-h">
<div class="bdy-section-head">
<h3 id="bdy-body-h">Body</h3>
<p>The 3D avatar your agent wears everywhere — chat, world, profile, and feed.</p>
</div>
<div class="bdy-avatar-card">
<div class="bdy-avatar-thumb">${thumb}</div>
<div class="bdy-avatar-meta">
<span class="bdy-avatar-name">${esc(a.name)}</span>
<span class="bdy-avatar-sub">${isDefault ? 'Default starter — swap it for your own anytime.' : 'Live on the stage →'}</span>
<div class="bdy-avatar-actions">
<button class="studio-btn studio-btn-primary studio-action" data-action="change">Change avatar</button>
<a class="studio-btn studio-btn-ghost studio-action" data-action="customize"
href="${isDefault ? '/create' : `/avatars/${encodeURIComponent(a.id)}/edit`}">
${isDefault ? 'Create your own ↗' : 'Customize outfit ↗'}
</a>
</div>
</div>
</div>
</section>`;
}
// ── Movement (animations) ───────────────────────────────────────────────────
_movementSection() {
const { featured, groups } = this.state.clips;
return `
<section class="bdy-section" aria-labelledby="bdy-move-h">
<div class="bdy-section-head">
<h3 id="bdy-move-h">Movement</h3>
<p>Click any move to preview it live. Pin a looping idle as the resting pose your agent holds everywhere.</p>
</div>
<div class="bdy-resting" aria-live="polite">
<span class="bdy-resting-label">Resting pose</span>
<span class="bdy-resting-val" data-resting>${esc(this._restingLabel())}</span>
</div>
<div class="bdy-featured">
${featured.map((c) => this._chip(c, true)).join('')}
</div>
<div class="bdy-cats">
${groups.map((g) => this._catBlock(g)).join('')}
</div>
</section>`;
}
_restingLabel() {
const idle = this._idleClip;
const all = [...(this.state.clips?.featured || []), ...(this.state.clips?.groups || []).flatMap((g) => g.items)];
return all.find((c) => c.name === idle)?.label || idle;
}
_catBlock(g) {
const open = this.state.openCat === g.key;
return `
<details class="bdy-cat" ${open ? 'open' : ''} data-cat="${esc(g.key)}">
<summary class="bdy-cat-summary">
<span>${g.icon} ${esc(g.label)}</span>
<span class="bdy-cat-count">${g.items.length}</span>
</summary>
<div class="bdy-grid">${g.items.map((c) => this._chip(c, false)).join('')}</div>
</details>`;
}
_chip(c, featured) {
const loop = c.loop !== false;
const canPin = loop; // only loops make sense as a held resting pose
return `
<div class="bdy-chip ${featured ? 'bdy-chip--featured' : ''}" data-clip="${esc(c.name)}" data-loop="${loop}">
<button class="bdy-chip-play" data-action="play" data-clip="${esc(c.name)}" data-loop="${loop}"
title="Preview ${esc(c.label || c.name)}">
<span class="bdy-chip-icon" aria-hidden="true">${c.icon || '▶'}</span>
<span class="bdy-chip-label">${esc(c.label || c.name)}</span>
</button>
${canPin ? `<button class="bdy-chip-pin" data-action="pin" data-clip="${esc(c.name)}"
title="Set as resting pose" aria-label="Set ${esc(c.label || c.name)} as resting pose">☆</button>` : ''}
</div>`;
}
// ── Bind ────────────────────────────────────────────────────────────────────
_bindError() {
this._q('[data-action="retry"]')?.addEventListener('click', () => this._load());
}
_bind() {
this.el.addEventListener('click', (e) => {
const btn = e.target.closest('[data-action]');
if (!btn) return;
const action = btn.dataset.action;
if (action === 'change') return this._openPicker();
if (action === 'play') return this._preview(btn.dataset.clip, btn.dataset.loop === 'true');
if (action === 'pin') return this._pinResting(btn.dataset.clip);
// 'customize' is a real <a> — let it navigate.
});
// Track which category the user expands so a re-render keeps it open.
this.el.querySelectorAll('.bdy-cat').forEach((d) =>
d.addEventListener('toggle', () => { if (d.open) this.state.openCat = d.dataset.cat; }));
}
_openPicker() {
if (!this._picker) {
this._picker = createAvatarPicker({
onSelect: ({ id }) => this._setAvatar(id),
});
}
this._picker.open(this.studio.agent?.avatarId || null);
}
async _setAvatar(avatarId) {
// null = the default starter. patch() drives the live stage immediately
// (presence reloads on avatarId change) and debounce-PUTs avatar_id.
this.studio.patch({ avatarId: avatarId || null });
this.studio.emit('body:change', { avatarId: avatarId || null });
this.state.avatar = await this._resolveAvatar();
this._renderBody();
}
_preview(name, loop) {
if (!name) return;
this.state.playing = name;
this._stage?.playClip?.(name, { loop });
this.studio.emit('body:preview', { clip: name, loop });
// Flash the active chip so the click registers even on a clip-less rig.
this.el.querySelectorAll('.bdy-chip').forEach((c) =>
c.classList.toggle('bdy-chip--playing', c.dataset.clip === name));
clearTimeout(this._playFlash);
this._playFlash = setTimeout(() => {
this.el.querySelectorAll('.bdy-chip--playing').forEach((c) => c.classList.remove('bdy-chip--playing'));
}, loop ? 1200 : 2200);
}
_pinResting(name) {
if (!name) return;
this.studio.patch({ meta: { studio: { body: { idleClip: name } } } });
this.studio.emit('body:change', { idleClip: name });
this._preview(name, true); // show the new resting pose immediately
const restingEl = this._q('[data-resting]');
if (restingEl) restingEl.textContent = this._restingLabel();
this._syncIdleMarks();
}
// Reflect the pinned resting pose on the matching chip (filled star + ring).
_syncIdleMarks() {
const idle = this._idleClip;
this.el.querySelectorAll('.bdy-chip').forEach((chip) => {
const on = chip.dataset.clip === idle;
chip.classList.toggle('bdy-chip--resting', on);
const pin = chip.querySelector('.bdy-chip-pin');
if (pin) {
pin.textContent = on ? '★' : '☆';
pin.classList.toggle('on', on);
pin.title = on ? 'Current resting pose' : 'Set as resting pose';
}
});
const restingEl = this._q('[data-resting]');
if (restingEl) restingEl.textContent = this._restingLabel();
}
destroy() {
this._unsub?.();
clearTimeout(this._playFlash);
}
}