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.

7.6 KB
Raw Blame

three.ws

@three-ws/agent-ui

Drop a 3D avatar onto a transparent overlay and let it react to your DOM — clicks, inputs, and navigation.

npm downloads license node

Install · Quick start · Imperative API · Declarative · Options · three.ws


@three-ws/agent-ui packages the avatar-overlay runtime from the three.ws demos into a small Three.js SDK. The avatar lives on a transparent, fullscreen canvas above your DOM and is anchored to real elements: it can stand on a card, fall onto a heading, walk over to focus an input, cover its eyes when you type a password, or run off-screen before a navigation. One createAgentUI() call gets you a handle with imperative methods; one agent.scan() call wires up declarative data-agent-* attributes with no per-element JS.

Install

npm install @three-ws/agent-ui three

three (>=0.150.0) is a peer dependency so your bundler de-dupes it. The package ships source ESM (@three-ws/agent-ui) plus a prebuilt bundle subpath (@three-ws/agent-ui/bundle).

Quick start

<canvas></canvas>
<div id="hero">three.ws</div>

<script type="module">
  import { createAgentUI } from '@three-ws/agent-ui';

  const agent = await createAgentUI({
    avatar: '/avatars/cz.glb',
    clipsBase: '/animations/clips/',
    clips: ['idle', 'walk', 'falling'],
  });

  const hero = document.getElementById('hero');
  agent.fallOnto(hero, {
    onLand: () => {
      agent.fx.dust(hero);
      agent.fx.impactPulse(hero);
    },
  });

  agent.scan(); // wires any data-agent-action attributes in the page
</script>

createAgentUI(options) resolves once the GLB and clip JSONs load and the avatar is in scene. The resolved handle exposes the Three.js objects (renderer, scene, camera, canvas, avatar), animation control, movement/posing behaviors, FX helpers, and lifecycle (whenReady, destroy).

Imperative API

// Animation — clips are loaded from `clipsBase`
agent.play('idle', { loop: true });
agent.play('covereyes', { loop: false, hold: true });
agent.clip('walk');        // → clip duration in seconds (0 if not loaded)
agent.currentClip;         // → name of the clip currently playing

// Movement & posing
agent.standOn(formCard, { anchor: 'top-center' }); // park without traversal
agent.walkTo(emailInput);                          // walk-cycle over to an element
agent.fallOnto(heading, { duration: 1.4 });        // drop in from above
agent.runOff('right');                             // walk off-screen
agent.interceptNavigation(homeLink, { direction: 'right', delay: 1100 });
agent.lookAt(450);   // turn yaw toward a screen-X (pixels)
agent.faceFront();

// FX
const stopShadow = agent.fx.proximityShadow(heading); // returns a disposer
agent.fx.dust(buttonEl);
agent.fx.impactPulse(buttonEl);

// Utilities
agent.worldOfElement(el, { anchor: 'center' }); // DOM rect → world-space target
const pick = agent.pickFrom(['nod', 'shrug', 'wave']); // non-repeating picker
agent.whenReady((a) => { /* runs now or on ready */ });
agent.destroy(); // cancels RAF, unlocks root motion, tears down the renderer

Anchors accepted by standOn / walkTo / worldOfElement: top-left, top-right, top-center (default), center, bottom-center, left-of, right-of.

The same behavior functions are exported standalone for advanced compositions: createRenderer, loadAvatar, createAnimator, lockRootMotion, worldOfElement, moveTo, lookAtScreenX, faceFront, walkTo, standOn, fallOnto, runOff, interceptNavigation, createRandomPicker, caretScreenX, startCaretTracking, dust, impactPulse, proximityShadow, scan.

Declarative attributes

Mark up the page, call agent.scan() once. It returns a cleanup function that removes every listener it added.

<div class="card" data-agent-action="stand-on"></div>

<input data-agent-action="track-typing" />
<input data-agent-action="privacy-mode" type="password" />

<a href="/" data-agent-action="navigate-on-click" data-agent-direction="right">Home</a>
<button data-agent-action="react-on-click" data-agent-clip="celebrate">Subscribe</button>
data-agent-action Behavior
stand-on Park the avatar above this element on ready.
track-typing On focus, walk to the input, play lookdown, then follow the caret with yaw.
privacy-mode On focus, walk to the input, play covereyes once and hold; play idle on blur.
navigate-on-click Intercept the click, run off-screen, then follow href.
react-on-click Play data-agent-clip once on click.

Optional modifiers: data-agent-direction (left/right), data-agent-clip, data-agent-anchor, data-agent-delay (ms), data-agent-loop (true/false), data-agent-hold (true/false).

Options

createAgentUI({
  avatar: '/avatars/cz.glb',        // GLB URL (you host it)
  clipsBase: '/animations/clips/',  // base path for clip JSONs
  clips: ['idle', 'walk', 'lookdown', 'covereyes', 'falling', 'celebrate'],
  subclips: {
    // Trim a long Mixamo clip down to just the settle frames
    covereyes: { start: 0, end: 48, fps: 30 },
  },
  container: undefined, // defaults to document.body
  canvas: undefined,    // explicit canvas; otherwise one is created
  pixelsPerUnit: 120,
  zIndex: 999,
  parallax: true,
  crossfade: 0.3,
  lights: true,
});

Notes

  • Assets are yours. The SDK does not bundle the avatar GLB or animation JSONs — point it at whatever you host. Every URL is configurable; the three.ws CDN paths are only the defaults.
  • Three.js is a peer dep so your bundler de-dupes it. Works with Three r150+.
  • No animation-library dependency. All tweens use built-in requestAnimationFrame easings.
  • Root motion is locked automatically so walk-cycle hip translation doesn't drift the avatar off-screen.

Requirements

  • Node >=18.
  • Peer dependency: three >=0.150.0.
  • A GLB avatar and clip JSONs you host (no bundled assets).

Related packages

Links


Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub