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
import {
forwardRef,
useCallback,
useEffect,
useImperativeHandle,
useMemo,
useRef,
} from 'react';
const DEFAULT_BASE_URL = 'https://three.ws';
/** Coerce a width/height prop (number → px, string passed through). */
function toCssSize(value) {
if (value == null) return undefined;
return typeof value === 'number' ? `${value}px` : value;
}
/**
* Build the embed player URL from props using URL + searchParams (never string
* concat). Maps 1:1 to the params accepted by https://three.ws/walk-embed.
*/
function buildEmbedSrc({
baseUrl,
agentId,
avatarId,
controls,
background,
environment,
autoplay,
ground,
orbit,
}) {
const url = new URL('/walk-embed', baseUrl);
const p = url.searchParams;
// avatarId overrides the agent's default avatar; otherwise the agent id is the avatar.
const avatar = avatarId || agentId;
if (avatar) p.set('avatar', avatar);
if (controls) p.set('controls', controls);
if (background) p.set('bg', background);
if (environment) p.set('env', environment);
if (autoplay) p.set('autoplay', 'true');
// Player defaults ground/orbit to ON; only emit the param to turn them off.
if (ground === false) p.set('ground', 'false');
if (orbit === false) p.set('orbit', 'false');
return url.toString();
}
/**
* <Agent3D> embeds a three.ws walking 3D AI agent via a sandboxed iframe.
*
* The 3D runtime (Three.js / WebGL) lives inside three.ws; this component is a
* thin, dependency-free wrapper around the embed player and its postMessage
* protocol. Also exported as <WalkEmbed>.
*/
const Agent3D = forwardRef(function Agent3D(
{
agentId,
avatarId,
controls = 'joystick',
background,
environment,
autoplay,
ground,
orbit,
speed,
width = '100%',
height = '600px',
baseUrl = DEFAULT_BASE_URL,
onLoad,
onError,
className,
style,
title = 'three.ws 3D agent',
...rest
},
ref,
) {
const iframeRef = useRef(null);
const src = useMemo(
() =>
buildEmbedSrc({
baseUrl,
agentId,
avatarId,
controls,
background,
environment,
autoplay,
ground,
orbit,
}),
[baseUrl, agentId, avatarId, controls, background, environment, autoplay, ground, orbit],
);
// The only origin we trust for inbound messages, derived from the embed URL.
const targetOrigin = useMemo(() => new URL(src).origin, [src]);
const post = useCallback(
(msg) => {
iframeRef.current?.contentWindow?.postMessage(msg, targetOrigin);
},
[targetOrigin],
);
// Imperative handle: drive the live embed from the host app.
useImperativeHandle(
ref,
() => ({
sendMessage: (msg) => post(msg),
setAvatar: (id) => post({ type: 'walk:setAvatar', id }),
setMotion: (motion) => post({ type: 'walk:setMotion', motion }),
setEnvironment: (env) => post({ type: 'walk:setEnv', env }),
setSpeed: (value) => post({ type: 'walk:config', speed: value }),
narrate: (text) => post({ type: 'walk:narrate', text }),
resetPose: () => post({ type: 'walk:resetPose' }),
get iframe() {
return iframeRef.current;
},
}),
[post],
);
// Latest-callback refs so the message listener never goes stale and we don't
// re-bind it on every render.
const onLoadRef = useRef(onLoad);
const onErrorRef = useRef(onError);
onLoadRef.current = onLoad;
onErrorRef.current = onError;
useEffect(() => {
function handleMessage(event) {
// Strictly reject any origin that isn't the embed origin (XSS guard), and
// ignore messages that didn't come from our own iframe.
if (event.origin !== targetOrigin) return;
if (iframeRef.current && event.source !== iframeRef.current.contentWindow) return;
const data = event.data;
if (!data || typeof data !== 'object') return;
if (data.type === 'walk:ready') {
if (typeof speed === 'number') post({ type: 'walk:config', speed });
onLoadRef.current?.();
} else if (data.type === 'walk:error') {
onErrorRef.current?.(new Error(data.error || 'three.ws embed failed to load'));
}
}
window.addEventListener('message', handleMessage);
return () => window.removeEventListener('message', handleMessage);
}, [targetOrigin, speed, post]);
const wrapperStyle = {
position: 'relative',
width: toCssSize(width),
height: toCssSize(height),
...style,
};
return (
<div className={className} style={wrapperStyle} {...rest}>
<iframe
ref={iframeRef}
src={src}
title={title}
allow="xr-spatial-tracking; microphone; camera; autoplay"
loading="lazy"
style={{
display: 'block',
width: '100%',
height: '100%',
border: 0,
}}
/>
</div>
);
});
export { Agent3D };