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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Type definitions for @three-ws/walk
import type { Object3D } from 'three';
export declare const VERSION: string;
/** How a roster avatar is animated. */
export type WalkRig = 'embedded' | 'shared';
/** Logical animation states the controller understands. */
export type WalkState = 'idle' | 'walk' | 'run' | 'jump';
/** On-command performances the controller can play (when the rig has the clip). */
export type WalkEmote = 'dance' | 'punch' | 'backflip' | 'wave' | (string & {});
/** Mapping of logical states to clip names (shared rig) or candidate name lists (embedded rig). */
export interface WalkClipMap {
idle?: string | string[];
walk?: string | string[];
run?: string | string[];
wave?: string | string[];
jump?: string | string[];
}
/** A single avatar in the roster. */
export interface WalkAvatar {
id: string;
name: string;
emoji?: string;
blurb?: string;
category: string;
/** GLB path resolved against `assetBase`; null for API-served avatars. */
asset: string | null;
source: 'static' | 'api';
rig: WalkRig;
clips?: WalkClipMap;
/** Shared-rig emote overrides: emote name to manifest clip name. */
emotes?: Record<string, string>;
thumb?: string;
accent?: string;
tags?: string[];
}
export declare const WALK_AVATARS: WalkAvatar[];
export declare const DEFAULT_AVATAR_ID: string;
export declare const DEFAULT_SHARED_CLIPS: Record<string, string>;
export declare const DEFAULT_EMOTES: Record<string, string>;
/** Resolve an emote map against the clips that exist, dropping unsupported emotes. */
export declare function resolveEmotes(
availableClipNames: Iterable<string>,
emotes?: Record<string, string>,
): Record<string, string>;
export declare function getAvatar(id: string): WalkAvatar | null;
export declare function defaultAvatar(): WalkAvatar;
export declare function listCategories(): string[];
export declare function makeApiAvatarEntry(
id: string,
opts?: { name?: string; accent?: string },
): WalkAvatar;
export declare function resolveAvatarUrl(
entry: WalkAvatar,
opts?: { assetBase?: string; apiBase?: string },
): string | null;
/** Options accepted by `createWalkCompanion`. */
export interface WalkCompanionOptions {
/** Roster shown in the picker and resolvable by id. Defaults to WALK_AVATARS. */
avatars?: WalkAvatar[];
/** Avatar to load when none is chosen/stored. Defaults to 'robot'. */
defaultAvatarId?: string;
/** Base prepended to static GLB paths (e.g. a CDN origin). */
assetBase?: string;
/** Base prepended to the `/api/avatars/<id>/glb` proxy. */
apiBase?: string;
/** URL of the shared animation manifest. Defaults to '/animations/manifest.json'. */
manifestUrl?: string;
/** Route prefixes where the companion never mounts. */
excludedRoutes?: string[];
/** Show the avatar picker button. Defaults to true. */
enablePicker?: boolean;
/** Companion's chest/neck/head follow the visitor's cursor. Defaults to true. */
lookAt?: boolean;
/** Override the page-context greeting; return null to fall back to the default. */
greeting?: (path: string) => string | null;
/** Optional "make your own" link shown in the picker footer. */
docsUrl?: string;
/** Storage key prefix. Defaults to 'walk'. */
storagePrefix?: string;
}
/** The controller returned by `createWalkCompanion`. */
export interface WalkCompanionControl {
readonly instance: unknown;
/** The resolved options this control was built with (storage keys included). */
readonly config: WalkConfig;
isEnabled(): boolean;
enable(): void;
disable(): void;
toggle(): void;
/** Persist and (if mounted) hot-swap the live avatar. */
setAvatar(idOrEntry: string | WalkAvatar): void;
openPicker(): void;
/** Run the app-style auto-mount + deep-link logic (reads ?walk= and saved state). */
bootstrap(): void;
}
export declare function createWalkCompanion(opts?: WalkCompanionOptions): WalkCompanionControl;
/** A controller exposing setState/playWave/emotes for a loaded avatar. */
export interface WalkController {
setState(state: WalkState): void;
playWave(): void;
/** Emote names this rig can actually perform; render only these as buttons. */
emotes(): WalkEmote[];
/** Play an emote once, then settle back to the base state. False = unsupported. */
playEmote(name: WalkEmote): boolean;
/** Scale playback rate (1 = authored cadence) so walk cycles match travel speed. */
setSpeed(scale: number): void;
update(dt: number): void;
dispose(): void;
}
export declare function loadWalkAvatar(
entry: WalkAvatar,
opts?: {
assetBase?: string;
apiBase?: string;
manifestUrl?: string;
fallbackEntry?: WalkAvatar | null;
waveMs?: number;
},
): Promise<{ model: Object3D; controller: WalkController; gltf: unknown; entry: WalkAvatar }>;
export type PlaygroundMode = 'stroll' | 'platformer';
export declare function launchPlayground(opts?: {
avatarId?: string | null;
startScreen?: { x: number; y: number } | null;
dropIn?: boolean;
mode?: PlaygroundMode;
config?: unknown;
/** Checkpoint quest: elements the visitor must reach, in order. Works in both movement modes. */
checkpoints?: Array<{ el: Element }>;
/** Called when the active checkpoint is reached; call resume() to unfreeze and advance. */
onReach?: (index: number, resume: () => void) => void;
onComplete?: () => void;
/** Start the quest at this checkpoint index (used to carry progress across a mode switch). */
startCheckpoint?: number;
}): unknown;
export declare function exitPlayground(): void;
export declare function switchPlaygroundMode(forceMode?: PlaygroundMode | null): unknown;
export declare function getPlaygroundMode(): PlaygroundMode;
export declare function shouldDropIn(config?: unknown): boolean;
export declare function consumeDropIn(config?: unknown): boolean;
export declare function playgroundState(): Record<string, unknown> | null;
/** Avatar picker popover. */
export interface AvatarPicker {
el: HTMLElement;
show(): void;
close(): void;
toggle(): void;
isOpen(): boolean;
setCurrent(id: string): void;
destroy(): void;
}
export declare function createAvatarPicker(opts: {
avatars: WalkAvatar[];
currentId?: string | null;
onSelect: (entry: WalkAvatar) => void;
anchor?: { right: number; bottom: number };
assetBase?: string;
docsUrl?: string;
}): AvatarPicker;
export interface WalkConfig {
avatars: WalkAvatar[];
defaultAvatarId: string;
assetBase: string;
apiBase: string;
manifestUrl: string;
excludedRoutes: string[];
enablePicker: boolean;
lookAt: boolean;
greeting: ((path: string) => string | null) | null;
docsUrl: string | null;
keys: Record<string, string>;
}
export declare function resolveConfig(opts?: WalkCompanionOptions): WalkConfig;
export declare function resolveAvatarEntry(id: string | null, config: WalkConfig): WalkAvatar;
export declare const DEFAULT_EXCLUDED_PREFIXES: string[];