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.

On this page

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>
No build step. The SDK is plain browser JS with zero dependencies. It works from a <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.

waiting for walk:ready…

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.

EventDirPayloadFires 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.

CommandDirPayloadSDK 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:

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

Tip: if you embed user-generated avatar ids, still pass them through 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>
  );
}