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
/**
* Talk-mode emote controller.
*
* Wraps the existing AnimationManager (src/animation-manager.js) with:
* - manifest fetch from /animations/manifest.json
* - curated subset selection for the talk overlay's emote bar
* - lazy clip load on first play (fast first paint, no eager 30-clip fetch)
*
* AnimationManager already handles model attachment, track filtering by bone
* names (so unmatched-rig clips no-op cleanly), crossfade, and one-shot vs
* looped playback. This is just the glue and the UI-facing curation.
*
* The bone-name filter is what makes this safe across rig conventions: the
* retargeted clips were authored against the Avaturn skeleton, but the
* filter drops tracks for any joint not present on the loaded avatar, so
* applying a "dance" clip to a robot or stylized mesh either animates the
* matching bones or no-ops — never throws.
*/
import { AnimationManager } from '../animation-manager.js';
import { log } from '../shared/log.js';
// Curated set shown on the talk overlay's emote bar. Keep it short — too
// many buttons creates choice paralysis during a live conversation.
// Each entry's `name` must match a `name` in /animations/manifest.json.
export const TALK_EMOTE_BAR = [
{ name: 'idle', label: 'Idle', icon: '🧍', loop: true },
{ name: 'wave', label: 'Wave', icon: '👋', loop: false },
{ name: 'celebrate', label: 'Celebrate', icon: '🎉', loop: false },
{ name: 'dance', label: 'Dance', icon: '💃', loop: true },
{ name: 'reaction', label: 'React', icon: '😲', loop: false },
{ name: 'pray', label: 'Pray', icon: '🙏', loop: false },
];
export class TalkEmotes {
constructor() {
this._manager = new AnimationManager();
this._defs = [];
this._defsByName = new Map();
this._loaded = new Set();
this._loading = new Map(); // name → in-flight promise
this._manifestPromise = null;
}
/** Attach to the live model. Call after TalkScene loads its GLB. */
attach(model) {
this._manager.attach(model);
}
detach() {
this._manager.detach();
}
/**
* Re-measure the rig after a skeleton-space proportion edit (Avatar Studio's
* Proportions sliders) so root motion is rescaled to the new hip height and
* the avatar doesn't foot-slide. Call with the rig at rest.
* @returns {boolean}
*/
remeasureRig() {
return this._manager.remeasureRigProportions();
}
/** Tick the underlying AnimationMixer. Hook into the scene's RAF loop. */
update(dt) {
this._manager.mixer?.update(dt);
}
/**
* Stop every running clip so the mixer stops writing to the bones.
*
* Pausing is not enough: a paused action keeps re-applying its last evaluated
* pose on each tick, which would overwrite a caller that deliberately posed the
* rig (see src/glb-bind-pose.js, used to export a neutral GLB).
*/
stopAll() {
this._manager.stopAll();
}
/**
* Load the manifest. Idempotent — subsequent calls return the cached promise.
* Returns true once defs are populated, false on failure (e.g. 404).
*
* Not declared `async` so the cached promise identity is preserved across
* callers (an outer `async` wrapper would re-wrap on every invocation).
*/
loadManifest() {
if (this._manifestPromise) return this._manifestPromise;
// Only a SUCCESSFUL load is memoized. Caching the failure too meant one
// dropped request disabled every clip for the rest of the session and no
// retry could ever reach the network again, so the caller's "try again"
// was a button that could not work. Clearing the memo on failure keeps
// concurrent callers sharing the in-flight request while still letting
// the next attempt re-fetch.
this._manifestPromise = (async () => {
try {
const r = await fetch('/animations/manifest.json');
if (!r.ok) return false;
const list = await r.json();
if (!Array.isArray(list)) return false;
this._defs = list;
this._defsByName = new Map(list.map((d) => [d.name, d]));
this._manager.setAnimationDefs(list);
return true;
} catch (err) {
log.warn('[talk-emotes] manifest fetch failed:', err?.message);
return false;
}
})().then(
(ok) => {
if (!ok) this._manifestPromise = null;
return ok;
},
(err) => {
this._manifestPromise = null;
throw err;
},
);
return this._manifestPromise;
}
/** Available emote def list — full manifest, post-load. */
getAllDefs() {
return this._defs;
}
/**
* Return only the curated bar entries whose clip exists in the manifest.
* If the manifest hasn't loaded yet, returns []. The talk overlay should
* re-render after loadManifest() resolves.
*/
getBarDefs() {
if (!this._defs.length) return [];
return TALK_EMOTE_BAR.filter((entry) => this._defsByName.has(entry.name));
}
/**
* Play an emote by name. Lazy-loads the clip on first play; subsequent
* plays are immediate. The clip's loop flag is fixed at load time from
* the manifest entry.
*
* Returns false if the emote isn't in the manifest, true on play start.
*/
async play(name) {
const def = this._defsByName.get(name);
if (!def) {
log.warn(`[talk-emotes] unknown emote: ${name}`);
return false;
}
// Lazy-load with deduplication: parallel calls for the same name share
// one in-flight fetch.
if (!this._loaded.has(name)) {
let inflight = this._loading.get(name);
if (!inflight) {
inflight = this._manager
.loadAnimation(name, def.url, { loop: def.loop !== false })
.then(() => this._loaded.add(name))
.finally(() => this._loading.delete(name));
this._loading.set(name, inflight);
}
try {
await inflight;
} catch (err) {
log.warn(`[talk-emotes] load failed for "${name}":`, err?.message);
return false;
}
}
// Cross-fade if something else is already playing, otherwise just play.
if (this._manager.currentName && this._manager.currentName !== name) {
await this._manager.crossfadeTo(name, 0.25);
} else {
await this._manager.play(name);
}
return true;
}
/**
* Play a one-shot emote once, then settle back into a looping clip (idle by
* default) with a crossfade. For manifest entries whose `loop` is false
* (wave, celebrate, flex, …) this avoids freezing the avatar on the final
* frame. Lazily loads both the one-shot and the settle clip via the manager.
*
* @param {string} name
* @param {{ settleTo?: string, fade?: number }} [opts]
* @returns {Promise<boolean>} false if the emote isn't in the manifest.
*/
async playOnce(name, { settleTo = 'idle', fade = 0.25 } = {}) {
const def = this._defsByName.get(name);
if (!def) {
log.warn(`[talk-emotes] unknown emote: ${name}`);
return false;
}
await this._manager.playOnce(name, { settleTo, fade });
return true;
}
get currentEmote() {
return this._manager.currentName;
}
}