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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title data-i18n="demos_avatar_sdk.meta_title">@three-ws/avatar SDK · three.ws lab</title>
<meta name="robots" content="noindex" />
<link rel="stylesheet" href="/style.css" />
<link rel="stylesheet" href="/nav.css" />
<style>
:root { color-scheme: dark; }
body { background: #060606; color: #eee; font: 15px/1.5 -apple-system, system-ui, sans-serif; margin: 0; }
.stage { max-width: 1000px; margin: 0 auto; padding: 48px 24px 80px; }
.crumb a { color: #8a8d98; text-decoration: none; }
.crumb a:hover { color: #3dc1ff; }
h1 { font-size: 28px; font-weight: 600; letter-spacing: -0.015em; margin: 14px 0 8px; }
.sub { color: #8a8d98; max-width: 64ch; margin: 0 0 30px; }
pre {
background: #080808; border: 1px solid #202020; border-radius: 9px;
padding: 14px 16px; font-family: ui-monospace, monospace; font-size: 12.5px;
color: #3dc1ff; overflow-x: auto;
}
.card {
background: #101010; border: 1.5px solid #202020; border-radius: 14px;
padding: 22px; margin: 16px 0;
}
.viewer-host {
min-height: 460px;
background: #0b0b0b; border-radius: 10px; overflow: hidden;
margin-top: 14px;
}
.viewer-host agent-3d { width: 100%; height: 460px; display: block; }
button {
background: #3dc1ff; color: #0a0a0a; border: 0; border-radius: 9px;
padding: 10px 14px; font-weight: 600; cursor: pointer; font: inherit;
}
.log {
margin-top: 14px;
background: #080808; border: 1px solid #202020; border-radius: 9px;
padding: 12px; font-family: ui-monospace, monospace; font-size: 12px;
color: #8a8d98; max-height: 200px; overflow: auto; white-space: pre-wrap;
}
.log .ok { color: #3dc1ff; }
.log .err { color: #ff6b6b; }
.log .info { color: #66d9ef; }
</style>
</head>
<body>
<header><div id="nav-container"></div></header>
<main class="stage">
<p class="crumb" data-i18n-html="demos_avatar_sdk.lab"><a href="/demos">← lab</a></p>
<h1 data-i18n="demos_avatar_sdk.three_ws_avatar_sdk">@three-ws/avatar SDK</h1>
<p class="sub" data-i18n-html="demos_avatar_sdk.the_npm_sdk_bundle_loaded_from_what">
The npm SDK bundle loaded from <code>/avatar-sdk/dist/index.mjs</code>
(what consumers would get from <code>npm install @three-ws/avatar</code>
once it's published). On mount it registers <code><agent-3d></code>
as a custom element. The Creator section opens the iframe modal that
resolves with a GLB Blob — the same flow third-party sites would use.
</p>
<section class="card">
<h2 style="margin-top:0;font-size:18px" data-i18n="demos_avatar_sdk.1_drop_in_web_component">1. Drop-in web component</h2>
<pre><script type="module" src="/avatar-sdk/dist/index.mjs"></script>
<agent-3d src="/avatars/default.glb"></agent-3d></pre>
<div class="viewer-host" id="sdk-viewer-host">
<!-- the agent-3d element is injected after the SDK loads -->
</div>
<div class="log" id="component-log">waiting for SDK to register the custom element…</div>
</section>
<section class="card">
<h2 style="margin-top:0;font-size:18px" data-i18n="demos_avatar_sdk.2_hand_off_by_avatar_id">2. Hand off by avatar ID</h2>
<pre><script type="module" src="/avatar-sdk/dist/index.mjs"></script>
<agent-3d avatar-id="AVATAR_UUID"></agent-3d></pre>
<p class="sub" style="margin:10px 0 0" data-i18n-html="demos_avatar_sdk.the_sdk_resolves_against_on_the_same">
The SDK resolves <code>avatar-id</code> against
<code>GET /api/avatars/:id</code> on the same origin the SDK was
loaded from (override with <code>api-base="https://other.host"</code>).
This is the durable handoff the
<a href="/demos/gallery-picker.html" style="color:#3dc1ff">gallery picker</a>
emits, and it keeps working even if the underlying GLB URL changes.
</p>
<div class="viewer-host" id="byid-viewer-host"></div>
<div class="log" id="byid-log">picking a real public avatar from /api/avatars/public…</div>
</section>
<section class="card">
<h2 style="margin-top:0;font-size:18px" data-i18n="demos_avatar_sdk.3_programmatic_creator">3. Programmatic Creator</h2>
<pre>import { AvatarCreator } from '/avatar-sdk/src/creator.js';
const creator = new AvatarCreator({
onExport: (glbBlob) => { /* save it */ },
});
creator.open();</pre>
<button id="open-creator-btn" data-i18n="demos_avatar_sdk.open_three_ws_avatar_creator">Open three.ws Avatar Creator</button>
<div class="log" id="creator-log">click to open the modal.</div>
</section>
</main>
<script src="/nav.js" defer></script>
<!-- Load the prebuilt SDK bundle -->
<script type="module" src="/avatar-sdk/dist/index.mjs"></script>
<script type="module">
const $ = (id) => document.getElementById(id);
const componentLog = $('component-log');
const byIdLog = $('byid-log');
const creatorLog = $('creator-log');
const stamp = () => new Date().toTimeString().slice(0, 8);
const line = (el, msg, cls = '') => {
el.innerHTML += `\n<span class="${cls}">[${stamp()}] ${msg}</span>`;
};
// Wait until the custom element registers (the SDK self-registers on load).
const start = performance.now();
const check = () => {
if (customElements.get('agent-3d')) {
const el = document.createElement('agent-3d');
el.setAttribute('src', '/avatars/default.glb');
$('sdk-viewer-host').appendChild(el);
line(componentLog, `✓ <agent-3d> registered in ${Math.round(performance.now() - start)} ms`, 'ok');
line(componentLog, '✓ mounted with src=/avatars/default.glb', 'ok');
mountByIdDemo();
} else if (performance.now() - start < 8000) {
setTimeout(check, 100);
} else {
line(componentLog, '✗ SDK bundle did not register <agent-3d> within 8s — check /avatar-sdk/dist/index.mjs', 'err');
}
};
check();
// Section 2 — resolve a real public avatar by ID and mount it.
async function mountByIdDemo() {
try {
const res = await fetch('/api/avatars/public?limit=1');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
const avatar = data?.avatars?.[0];
if (!avatar?.id) {
line(byIdLog, '✗ /api/avatars/public returned no avatars', 'err');
return;
}
line(byIdLog, `→ resolving avatar-id=${avatar.id}`, 'info');
const el = document.createElement('agent-3d');
el.setAttribute('avatar-id', avatar.id);
$('byid-viewer-host').appendChild(el);
line(byIdLog, `✓ <agent-3d avatar-id="${avatar.id}"> mounted (${avatar.name || 'unnamed'})`, 'ok');
} catch (err) {
line(byIdLog, '✗ avatar-id demo failed: ' + err.message, 'err');
}
}
// Programmatic Creator demo. Imports from the SDK source so we don't
// rebuild the whole bundle every time creator.js changes.
$('open-creator-btn').addEventListener('click', async () => {
try {
const mod = await import('/avatar-sdk/src/creator.js');
line(creatorLog, 'opening three.ws Avatar Creator iframe modal…', 'info');
const creator = new mod.AvatarCreator({
// Same-origin so dev (codespace) and production (three.ws)
// both load the local build instead of the hard-coded
// three.ws default. The index file is named explicitly:
// the bare /avatar-studio path serves the native sculpting
// page, which does not speak the export protocol.
studioUrl: new URL('/avatar-studio/index.html', location.origin).toString(),
onExport: (glbBlob) => {
line(creatorLog, `✓ export received (${glbBlob.size} bytes)`, 'ok');
},
onClose: () => {
line(creatorLog, 'modal closed without export', 'info');
},
});
await creator.open();
} catch (err) {
line(creatorLog, 'creator failed: ' + err.message, 'err');
}
});
</script>
<script src="/brand.js" defer></script>
<div id="footer-container"></div>
<script src="/footer.js"></script>
<!-- Runtime i18n: detects locale, swaps annotated copy, mounts <lang-switcher>. -->
<script type="module" src="/i18n.js"></script>
</body>
</html>