Iframe embed
/walk-embed is a chrome-less, transparent page that renders one
avatar. It ships frame-ancestors *, so you can drop it into an
<iframe> on any origin and configure everything through URL
query parameters.
The minimal embed
<iframe
src="https://three.ws/walk-embed?env=studio&autoplay=true&ground=false"
width="240" height="340"
style="border:0;background:transparent"
allow="accelerometer; gyroscope; xr-spatial-tracking"
title="three.ws walking avatar"></iframe>Live preview of the embed above?env=studio&autoplay=true&ground=false
For a floating corner avatar that mounts itself and gives you a runtime API, use the one-tag JavaScript SDK instead — it wraps this same iframe.
Query parameters
| Parameter | Values | Default | Description |
|---|---|---|---|
avatar | GLB / VRM URL, or avatar UUID | default avatar | The model to render. UUIDs are resolved through the avatar registry; URLs load directly. |
controls | joystick · keyboard · none | joystick | Input method. joystick shows an on-screen stick, keyboard enables WASD/arrows, none disables input. |
env | studio · void · beach · sunset · night · grid | studio | Scene preset — sets background, fog, ground, and lighting. |
autoplay | true / 1 | off | Start the avatar walking a slow circle so the embed is never static. |
ground | false to hide | shown | The ground disc. Set false to float the avatar on the host background with only a soft shadow. |
orbit | false to disable | enabled | Drag-to-orbit the camera. Disable for non-interactive, autoplay-only embeds. |
bg | transparent or a hex colour | transparent | Background fill. A hex value (e.g. %23101820) overrides the environment preset's clear colour. |
targetOrigin | an origin | * | Restrict outbound postMessage events to a single origin. |
allowOrigins | comma-separated origins | allow any | Allow-list of origins permitted to send inbound commands. |
In a URL,
# in a hex colour must be encoded as %23 — e.g. ?bg=%23101820.
Common recipes
Floating, non-interactive avatar (no ground, no orbit)
/walk-embed?autoplay=true&ground=false&orbit=false&controls=noneInteractive avatar with a joystick on a beach
/walk-embed?env=beach&controls=joystickYour own avatar with a solid backdrop
/walk-embed?avatar=YOUR-AVATAR-UUID&bg=%230b0f1a&ground=falseDriving it live
Once mounted you can change the avatar, environment, motion, and speech at runtime by posting messages to the iframe. The full message protocol — including the events the iframe emits back to you — is documented in postMessage events.
const frame = document.querySelector('iframe');
// swap the avatar
frame.contentWindow.postMessage({ type: 'walk:setAvatar', id: 'NEW-UUID' }, '*');
// change the world
frame.contentWindow.postMessage({ type: 'walk:setEnv', env: 'night' }, '*');
// say something
frame.contentWindow.postMessage({ type: 'walk:narrate', text: 'Hello!' }, '*');