Skip to content

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.

14.4 KB
Raw Blame
<!doctype html>
<html lang="en">
	<head>
		<script>/* three.ws theme boot — no-flash; runtime in /theme-switcher.js */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
		<meta charset="utf-8" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<title data-i18n="docs_walk_embed_sdk.meta_title">JavaScript SDK — Walk docs — three.ws</title>
		<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
		<meta name="description" content="The walk-embed-sdk.js host API. Mount a floating avatar with one script tag and control it at runtime through window.ThreeWalkAvatar: setAvatar, setEnv, setPosition, setSize, on/off events, and track."  data-i18n-attr="content:docs_walk_embed_sdk.meta_description"/>
		<meta name="theme-color" content="#0a0a0a" />
		<link rel="canonical" href="https://three.ws/docs/walk/embed-sdk" />
		<link rel="shortcut icon" href="/favicon.ico" />
		<link rel="stylesheet" href="/fonts/fonts.css" />
		<link rel="stylesheet" href="/style.css" />
		<link rel="stylesheet" href="/footer.css" />
		<link rel="stylesheet" href="/nav.css" />
		<link rel="stylesheet" href="/docs/walk/docs.css" />
	</head>
	<body>
		<a class="wd-skip" href="#wd-main" data-i18n="docs_walk_embed_sdk.skip_to_content">Skip to content</a>
		<header><div id="nav-container"></div></header>
		<script src="/nav.js"></script>

		<div class="wd-shell">
			<button class="wd-side-toggle" type="button" aria-expanded="false" aria-controls="wd-side" data-i18n-html="docs_walk_embed_sdk.documentation_menu">
				<span>Documentation menu</span><span aria-hidden="true">☰</span>
			</button>
			<aside class="wd-side" id="wd-side" aria-label="Walk documentation">
				<h2 data-i18n="docs_walk_embed_sdk.walk_docs">Walk docs</h2>
				<nav aria-label="Walk documentation pages">
					<a href="/docs/walk" data-i18n="docs_walk_embed_sdk.overview">Overview</a>
					<a href="/docs/walk/getting-started" data-i18n="docs_walk_embed_sdk.getting_started">Getting started</a>
				</nav>
				<h2 data-i18n="docs_walk_embed_sdk.use_it">Use it</h2>
				<nav aria-label="Using Walk">
					<a href="/docs/walk/walk-page" data-i18n="docs_walk_embed_sdk.the_walk_page">The walk page</a>
					<a href="/docs/walk/companion-mode" data-i18n="docs_walk_embed_sdk.companion_mode">Companion mode</a>
					<a href="/docs/walk/chrome-extension" data-i18n="docs_walk_embed_sdk.chrome_extension">Chrome extension</a>
				</nav>
				<h2 data-i18n="docs_walk_embed_sdk.build_with_it">Build with it</h2>
				<nav aria-label="Building with Walk">
					<a href="/docs/walk/embed-iframe" data-i18n="docs_walk_embed_sdk.iframe_embed">Iframe embed</a>
					<a href="/docs/walk/embed-sdk" aria-current="page" data-i18n="docs_walk_embed_sdk.javascript_sdk">JavaScript SDK</a>
					<a href="/docs/walk/postmessage-events" data-i18n="docs_walk_embed_sdk.postmessage_events">postMessage events</a>
					<a href="/docs/walk/analytics" data-i18n="docs_walk_embed_sdk.analytics">Analytics</a>
				</nav>
				<h2 data-i18n="docs_walk_embed_sdk.reference">Reference</h2>
				<nav aria-label="Reference"><a href="/docs/walk/changelog" data-i18n="docs_walk_embed_sdk.changelog">Changelog</a></nav>
			</aside>

			<main class="wd-main" id="wd-main">
				<p class="wd-crumbs" data-i18n-html="docs_walk_embed_sdk.docs_walk_javascript_sdk"><a href="/docs">Docs</a> / <a href="/docs/walk">Walk</a> / JavaScript SDK</p>
				<h1 data-i18n="docs_walk_embed_sdk.javascript_sdk_2">JavaScript SDK</h1>
				<p class="wd-lede" data-i18n-html="docs_walk_embed_sdk.is_a_standalone_zero_dependency_script_it">
					<code>walk-embed-sdk.js</code> is a standalone, zero-dependency script. It reads
					<code>data-*</code> attributes off its own tag, injects a fixed-position
					transparent iframe, and exposes <code>window.ThreeWalkAvatar</code> for runtime
					control — plus it re-emits the iframe's <code>postMessage</code> events as
					document-level <code>CustomEvent</code>s so you never touch <code>postMessage</code>
					directly.
				</p>

				<h2 data-i18n="docs_walk_embed_sdk.install">Install</h2>
				<p data-i18n-html="docs_walk_embed_sdk.one_tag_it_auto_mounts_on_dom">One tag. It auto-mounts on DOM ready unless you set <code>data-auto="false"</code>.</p>
				<div class="wd-code" data-lang="html" data-label="HTML">
					<pre><code>&lt;script src="https://three.ws/walk-embed-sdk.js"
        data-avatar="YOUR-AVATAR-UUID"
        data-position="bottom-right"
        data-width="220"
        data-height="320"
        data-env="studio"&gt;&lt;/script&gt;</code></pre>
				</div>

				<h2 data-i18n="docs_walk_embed_sdk.script_attributes">Script attributes</h2>
				<div class="wd-table-wrap">
					<table class="wd-table">
						<thead><tr><th data-i18n="docs_walk_embed_sdk.attribute">Attribute</th><th data-i18n="docs_walk_embed_sdk.values">Values</th><th data-i18n="docs_walk_embed_sdk.default">Default</th><th data-i18n="docs_walk_embed_sdk.description">Description</th></tr></thead>
						<tbody>
							<tr><td><code>data-avatar</code></td><td data-i18n="docs_walk_embed_sdk.avatar_uuid_glb_url">avatar UUID / GLB URL</td><td class="wd-default" data-i18n="docs_walk_embed_sdk.default_avatar">default avatar</td><td data-i18n="docs_walk_embed_sdk.the_model_to_render">The model to render.</td></tr>
							<tr><td><code>data-position</code></td><td><code>bottom-right</code> · <code>bottom-left</code> · <code>top-right</code> · <code>top-left</code></td><td class="wd-default"><code>bottom-right</code></td><td data-i18n="docs_walk_embed_sdk.corner_to_anchor_the_floating_avatar">Corner to anchor the floating avatar.</td></tr>
							<tr><td><code>data-width</code> / <code>data-height</code></td><td data-i18n="docs_walk_embed_sdk.pixels">pixels</td><td class="wd-default"><code>220</code> / <code>320</code></td><td data-i18n="docs_walk_embed_sdk.iframe_size">Iframe size.</td></tr>
							<tr><td><code>data-controls</code></td><td><code>none</code> · <code>joystick</code> · <code>keyboard</code></td><td class="wd-default"><code>none</code></td><td data-i18n-html="docs_walk_embed_sdk.input_method_with_clicks_pass_through_to">Input method. With <code>none</code>, clicks pass through to your page.</td></tr>
							<tr><td><code>data-env</code></td><td data-i18n="docs_walk_embed_sdk.environment_id">environment id</td><td class="wd-default"><code>studio</code></td><td data-i18n="docs_walk_embed_sdk.scene_preset">Scene preset.</td></tr>
							<tr><td><code>data-autoplay</code></td><td><code>true</code> / <code>false</code></td><td class="wd-default"><code>true</code></td><td data-i18n="docs_walk_embed_sdk.auto_walk_so_the_avatar_is_never">Auto-walk so the avatar is never static.</td></tr>
							<tr><td><code>data-ground</code></td><td><code>true</code> / <code>false</code></td><td class="wd-default"><code>false</code></td><td data-i18n="docs_walk_embed_sdk.show_the_ground_disc_off_by_default">Show the ground disc. Off by default for floating corner embeds.</td></tr>
							<tr><td><code>data-orbit</code></td><td><code>true</code> / <code>false</code></td><td class="wd-default"><code>false</code></td><td data-i18n="docs_walk_embed_sdk.allow_drag_to_orbit_off_by_default">Allow drag-to-orbit. Off by default for corner embeds.</td></tr>
							<tr><td><code>data-bg</code></td><td data-i18n-html="docs_walk_embed_sdk.hex"><code>transparent</code> / hex</td><td class="wd-default"><code>transparent</code></td><td data-i18n="docs_walk_embed_sdk.background_fill">Background fill.</td></tr>
							<tr><td><code>data-z-index</code></td><td data-i18n="docs_walk_embed_sdk.integer">integer</td><td class="wd-default"><code>2147483640</code></td><td data-i18n="docs_walk_embed_sdk.stacking_order_of_the_floating_container">Stacking order of the floating container.</td></tr>
							<tr><td><code>data-auto</code></td><td><code>true</code> / <code>false</code></td><td class="wd-default"><code>true</code></td><td data-i18n-html="docs_walk_embed_sdk.auto_mount_on_dom_ready_set_to">Auto-mount on DOM ready. Set <code>false</code> to mount manually.</td></tr>
						</tbody>
					</table>
				</div>

				<h2 data-i18n-html="docs_walk_embed_sdk.the_api">The <code>window.ThreeWalkAvatar</code> API</h2>
				<p data-i18n="docs_walk_embed_sdk.the_sdk_exposes_this_object_once_it">The SDK exposes this object once it loads. Every method below is real and shipped.</p>
				<div class="wd-table-wrap">
					<table class="wd-table">
						<thead><tr><th data-i18n="docs_walk_embed_sdk.method">Method</th><th data-i18n="docs_walk_embed_sdk.description_2">Description</th></tr></thead>
						<tbody>
							<tr><td><code>mount(target?)</code></td><td data-i18n-html="docs_walk_embed_sdk.mount_the_floating_iframe_idempotent_may_be">Mount the floating iframe. Idempotent. <code>target</code> may be an element or selector; defaults to <code>&lt;body&gt;</code>. Returns the container element.</td></tr>
							<tr><td><code>unmount()</code></td><td data-i18n="docs_walk_embed_sdk.remove_the_iframe_and_detach_listeners">Remove the iframe and detach listeners.</td></tr>
							<tr><td><code>setAvatar(id)</code></td><td data-i18n="docs_walk_embed_sdk.swap_the_avatar_live_uuid_or_glb">Swap the avatar live (UUID or GLB URL).</td></tr>
							<tr><td><code>setEnv(env)</code></td><td data-i18n="docs_walk_embed_sdk.change_the_environment_preset">Change the environment preset.</td></tr>
							<tr><td><code>setMotion(motion)</code></td><td data-i18n-html="docs_walk_embed_sdk.set_motion_or">Set motion: <code>'idle'</code>, <code>'walk'</code>, or <code>'run'</code>.</td></tr>
							<tr><td><code>setPosition(pos)</code></td><td data-i18n-html="docs_walk_embed_sdk.re_anchor_to_a_corner_etc">Re-anchor to a corner (<code>bottom-right</code> etc.).</td></tr>
							<tr><td><code>setSize(w, h)</code></td><td data-i18n="docs_walk_embed_sdk.resize_the_floating_container_in_pixels">Resize the floating container in pixels.</td></tr>
							<tr><td><code>resetPose()</code></td><td data-i18n="docs_walk_embed_sdk.recenter_the_avatar_and_reset_its_facing">Recenter the avatar and reset its facing.</td></tr>
							<tr><td><code>on(name, cb)</code></td><td data-i18n="docs_walk_embed_sdk.subscribe_to_an_event_see_below">Subscribe to an event (see below).</td></tr>
							<tr><td><code>off(name, cb)</code></td><td data-i18n="docs_walk_embed_sdk.remove_a_previously_registered_listener">Remove a previously registered listener.</td></tr>
							<tr><td><code>getOptions()</code></td><td data-i18n="docs_walk_embed_sdk.return_a_read_only_snapshot_of_the">Return a read-only snapshot of the current options.</td></tr>
						</tbody>
					</table>
				</div>

				<h2 data-i18n="docs_walk_embed_sdk.events">Events</h2>
				<p data-i18n-html="docs_walk_embed_sdk.the_sdk_forwards_the_iframe_s_events">
					The SDK forwards the iframe's <code>postMessage</code> events two ways: as
					document-level <code>CustomEvent</code>s and through <code>on()/off()</code>.
					The forwarded names are <code>walk:ready</code>, <code>walk:position</code>,
					<code>walk:error</code>, and <code>walk:avatarChanged</code>.
				</p>
				<div class="wd-code" data-lang="js" data-label="JavaScript">
					<pre><code>// Either listen on the document…
document.addEventListener('walk:ready', (e) =&gt; {
  console.log('avatar loaded', e.detail);
});

// …or through the API.
ThreeWalkAvatar.on('walk:position', ({ x, z, motion }) =&gt; {
  console.log(`at ${x.toFixed(2)}, ${z.toFixed(2)} — ${motion}`);
});</code></pre>
				</div>

				<h2 data-i18n="docs_walk_embed_sdk.runtime_control_example">Runtime control example</h2>
				<div class="wd-code" data-lang="js" data-label="JavaScript">
					<pre><code>const api = window.ThreeWalkAvatar;

api.setPosition('top-right');
api.setSize(180, 260);
api.setEnv('night');
api.setAvatar('NEW-AVATAR-UUID');
api.setMotion('run');</code></pre>
				</div>

				<h2 data-i18n="docs_walk_embed_sdk.conversion_tracking">Conversion tracking</h2>
				<p data-i18n-html="docs_walk_embed_sdk.on_the_dedicated_walk_page_and_any">
					On the dedicated <a href="/walk">walk page</a> (and any surface that boots the
					full walk runtime), <code>window.ThreeWalkAvatar.track(name, opts?)</code> records
					a creator-defined conversion event against the current avatar. It posts
					immediately and powers the funnel in the
					<a href="/docs/walk/analytics">analytics dashboard</a>.
				</p>
				<div class="wd-code" data-lang="js" data-label="JavaScript">
					<pre><code>// name is capped at 64 chars; value is an optional number.
window.ThreeWalkAvatar.track('subscribe', { value: 9 });</code></pre>
				</div>
				<div class="wd-note">
					<span class="wd-icon" aria-hidden="true">✱</span>
					<span data-i18n-html="docs_walk_embed_sdk.is_provided_by_the_full_walk_runtime"><code>track()</code> is provided by the full walk runtime. The lightweight floating-corner SDK focuses on mount and control; for conversion analytics, fire events from a page running the walk runtime.</span>
				</div>

				<h2 data-i18n="docs_walk_embed_sdk.manual_mounting">Manual mounting</h2>
				<div class="wd-code" data-lang="html" data-label="HTML">
					<pre><code>&lt;script src="https://three.ws/walk-embed-sdk.js"
        data-auto="false"&gt;&lt;/script&gt;
&lt;script&gt;
  // mount into a specific container when you're ready
  ThreeWalkAvatar.mount('#avatar-slot');
&lt;/script&gt;</code></pre>
				</div>

				<div class="wd-pagefoot">
					<a class="wd-edit" href="https://github.com/nirholas/three.ws/edit/main/public/docs/walk/embed-sdk.html" rel="noopener" data-i18n-html="docs_walk_embed_sdk.edit_this_page_on_github"><span aria-hidden="true">✎</span> Edit this page on GitHub</a>
					<div class="wd-nextprev">
						<a href="/docs/walk/embed-iframe" data-i18n-html="docs_walk_embed_sdk.previous_iframe_embed"><span>Previous</span>← Iframe embed</a>
						<a href="/docs/walk/postmessage-events" data-i18n-html="docs_walk_embed_sdk.nextpostmessage_events"><span>Next</span>postMessage events →</a>
					</div>
				</div>
			</main>
		</div>

		<div id="footer-container"></div>
		<script src="/footer.js"></script>
		<script src="/brand.js" defer></script>
		<script type="module" src="/docs/walk/docs.js"></script>
		<!-- Runtime i18n: detects locale, swaps annotated copy, mounts <lang-switcher>. -->
	<script type="module" src="/i18n.js"></script>
</body>
</html>