Walk Embed API
The walking-avatar embed is programmable. Drop the
/walk-embed iframe on any page and drive it with a typed,
bi-directional postMessage contract — or skip the wire format entirely
and use the ThreeWalkAvatar SDK. This page is the full reference: every
event, the security model, a live playground, and copy-paste examples.
Quick start
Render the iframe, then wrap it with the SDK to get a clean, promise-free command and event API:
<iframe id="avatar" src="https://three.ws/walk-embed?env=studio"
style="width:320px;height:400px;border:0"></iframe>
<script src="https://three.ws/walk-embed-sdk.js"></script>
<script>
const a = ThreeWalkAvatar.embed('#avatar');
a.on('ready', ({ avatarId, env }) => console.log('ready', avatarId, env));
a.on('position', ({ x, z, heading }) => console.log(x, z, heading));
a.goto(2, -1);
a.gesture('wave');
a.say('Hello from your site.');
</script>
<script> tag, a bundler, or an ESM
import of the URL.
Live playground
A real /walk-embed iframe, driven through the SDK. Send commands and
watch the event log update in real time — outbound events in green, the commands you
send in blue, errors in red.
Outbound events (iframe → host)
The embed emits these as you drive it and as the avatar lives its life. Subscribe with
avatar.on(name, cb); the callback receives the message object.
| Event | Dir | Payload | Fires when |
|---|---|---|---|
walk:ready |
OUT | { avatarId, env } |
Avatar + animation clips finished loading. Re-sent in reply to walk:ping. |
walk:position |
OUT | { x, z, heading } |
The avatar moves. Throttled to ≤ 10 Hz; heading is the facing yaw in radians. |
walk:gesture |
OUT | { gesture } |
A gesture starts playing (echoes both one-shots and locomotion changes). |
walk:speak |
OUT | { text, durationMs } |
The avatar starts speaking. durationMs is how long the bubble stays up. |
walk:env |
OUT | { env } |
The environment changes. |
walk:avatarChanged |
OUT | { avatarId } |
A live avatar swap finished loading. |
walk:error |
OUT | { code, message } |
A command was rejected or a load failed. Never carries internal state. |
Inbound commands (host → iframe)
Send these to drive the avatar. With the SDK, each maps to a method; over raw
postMessage, send the typed envelope (see
Envelope). Every command is validated and clamped inside the
iframe before it touches the avatar.
| Command | Dir | Payload | SDK method |
|---|---|---|---|
walk:goto |
IN | { x, z } |
a.goto(x, z) — walks to the point then stops (clamped to the ground disc). |
walk:gesture |
IN | { gesture } |
a.gesture(name) |
walk:say |
IN | { text, voice?, durationMs? } |
a.say(text, voice, durationMs) |
walk:env |
IN | { env } |
a.setEnv(env) |
walk:avatar |
IN | { avatarId } |
a.setAvatar(id) — accepts an avatar id, a site path, or a GLB URL. |
walk:config |
IN | { speed?, bg?, controls? } |
a.config({ … }) |
walk:move |
IN | { x, y, run? } |
a.move(x, y, run) — held analog drive (−1…1 per axis). |
walk:reset |
IN | {} |
a.reset() — recenter and stop all motion. |
walk:ping |
IN | {} |
a.ping() — re-request walk:ready (the SDK fires this for you on attach). |
Vocabulary
The accepted values for the enumerated payload fields:
- Gestures:
idle,walk,run,wave,jump.waveandjumpare one-shots that settle back to idle; the rest control locomotion. - Environments:
studio,void,beach,sunset,night,grid. - Controls (
config.controls):joystick,keyboard,none. - Speed (
config.speed): a walk-speed multiplier, clamped to0.3…3. - Background (
config.bg):transparent, a hex color, or anrgb()/rgba()string. - World bounds:
gototargets are clamped to a radius of ~11.5 m (the ground disc).
Feature-detect at runtime via ThreeWalkAvatar.protocol (the SDK) or
window.WALK_EMBED_PROTOCOL (inside the embed window).
Envelope
Every message — both directions — is a plain object with a channel guard and version,
so it can never be confused with another library's postMessage traffic:
{
channel: 'three-walk', // namespace guard — ignore anything else
v: 1, // protocol version
type: 'walk:position', // event or command name
id?: '<correlation id>', // echoed back on the result/error event
...payload // type-specific fields
}
If you talk to the iframe directly (no SDK), post the envelope to
iframe.contentWindow and read events off window:
const frame = document.getElementById('avatar');
// command
frame.contentWindow.postMessage(
{ channel: 'three-walk', v: 1, type: 'walk:goto', x: 2, z: -1 },
'https://three.ws'
);
// events
window.addEventListener('message', (e) => {
if (e.source !== frame.contentWindow) return; // source check = auth
if (!e.data || e.data.channel !== 'three-walk') return;
if (e.data.type === 'walk:position') console.log(e.data.x, e.data.z);
});
Security
- Source is the real authentication. The iframe only accepts commands whose source window is its own parent; the SDK only accepts events whose source is the iframe it wraps. Spoofed origins can't inject either way.
-
Origin allow-listing is opt-in. The embed ships
frame-ancestors *so it drops onto any site, so inbound is allow-any by default. Pin it with?allowOrigins=https://your.site(and?targetOrigin=to pin where events are posted) when you know the exact host. -
Nothing internal leaks. Outbound messages carry only the fields
in the tables above — never session tokens, avatar source URLs, or scene state.
A live avatar swap reports the public
avatarIdyou gave it, not the resolved CDN URL. -
Everything inbound is validated. Numbers are clamped, strings
are length-bounded, enums are checked, and
config.bgis restricted to safe color forms. A bad command yields awalk:error, never a throw.
a.setAvatar() — the iframe resolves and loads them on the same origin so
third-party hosts never need CORS exceptions.
Examples
The same integration in three flavours. All three use the dependency-free SDK.
import { useEffect, useRef, useState } from 'react';
export function WalkAvatar({ avatarId, env = 'studio' }) {
const frameRef = useRef(null);
const [pos, setPos] = useState(null);
useEffect(() => {
// Load the SDK once.
const SRC = 'https://three.ws/walk-embed-sdk.js';
function attach() {
const a = window.ThreeWalkAvatar.embed(frameRef.current);
a.on('ready', () => a.gesture('wave'));
a.on('position', setPos);
frameRef.current._ctl = a;
}
if (window.ThreeWalkAvatar) attach();
else {
const s = document.createElement('script');
s.src = SRC; s.onload = attach; document.head.appendChild(s);
}
return () => frameRef.current?._ctl?.destroy();
}, []);
return (
<div>
<iframe
ref={frameRef}
src={`https://three.ws/walk-embed?env=${env}${avatarId ? `&avatar=${avatarId}` : ''}`}
style={{ width: 320, height: 400, border: 0 }}
title="three.ws walking avatar"
/>
{pos && <p>x {pos.x.toFixed(2)} · z {pos.z.toFixed(2)}</p>}
</div>
);
}
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
const frame = ref(null);
const pos = ref(null);
let ctl = null;
function attach() {
ctl = window.ThreeWalkAvatar.embed(frame.value);
ctl.on('ready', () => ctl.setEnv('beach'));
ctl.on('position', (p) => (pos.value = p));
}
onMounted(() => {
if (window.ThreeWalkAvatar) return attach();
const s = document.createElement('script');
s.src = 'https://three.ws/walk-embed-sdk.js';
s.onload = attach;
document.head.appendChild(s);
});
onBeforeUnmount(() => ctl?.destroy());
</script>
<template>
<iframe
ref="frame"
src="https://three.ws/walk-embed?env=studio"
style="width:320px;height:400px;border:0"
title="three.ws walking avatar"
/>
<p v-if="pos">x {{ pos.x.toFixed(2) }} · z {{ pos.z.toFixed(2) }}</p>
</template>
<iframe id="avatar" src="https://three.ws/walk-embed?env=studio"
style="width:320px;height:400px;border:0"></iframe>
<script src="https://three.ws/walk-embed-sdk.js"></script>
<script>
const a = ThreeWalkAvatar.embed('#avatar');
a.on('ready', ({ avatarId, env }) => {
console.log('ready:', avatarId, env);
a.say('Welcome.', null, 4000);
});
a.on('position', ({ x, z, heading }) => {
// throttled to 10 Hz
});
a.on('error', ({ code, message }) => console.warn(code, message));
// Drive it.
document.querySelector('#go').addEventListener('click', () => {
a.goto(3, -2);
a.gesture('wave');
a.config({ speed: 1.5 });
});
</script>