JavaScript library (ara3d)

The ara3d package generates realistic, rigged and animated characters inside your own web app or game, as three.js objects. Characters are built on the visitor's device, in a background worker, so the page keeps running. The character data loads from a free CDN.

npm install ara3d three
import * as THREE from 'three';
import { createCharacter } from 'ara3d';

const hero = await createCharacter('The Soldier', { animations: ['walk', 'run', 'idle'] });
scene.add(hero.scene);

const mixer = new THREE.AnimationMixer(hero.scene);
mixer.clipAction(hero.clip('walk')).play();
// In your render loop: mixer.update(delta);

Try it first in the playground: pick a character, props and an expression, and copy the code it writes.

It's written in TypeScript and ships its types, so editors autocomplete every option. It needs three.js 0.160 or newer, a modern browser, and a bundler (Vite, webpack, Next.js and so on) or an import map. No extra bundler setup is needed: the worker is built in.

Choosing a character

createCharacter(input, options) takes:

Unknown fields and out-of-range values are rejected with a message that says what's wrong.

Options

Option Meaning
animations Clip IDs or categories, such as ['walk', 'run'] or ['locomotion', 'shooter']; 'all' (the default, 216 clips) or 'none'. ANIMATIONS lists them
detail 'low' (about 5–10k triangles), 'medium' (about 30–40k) or 'high' (about 100–120k)
rootMotion Walks, runs and strafes move the character forward instead of playing in place
weapon 'rifle', 'pistol', 'sword', 'knife' or 'grenade', held in the hand
carry Something to carry, such as 'backpack', 'briefcase' or 'phone'
vehicle A vehicle fitted to the rider, such as 'motorcycle' or 'horse'; it comes back in props
colors New colours for parts of the character, such as { outfit: '#1d2a44', carry: '#8a1c1c' }; see Colours
onProgress (label, fraction) => {}, for a loading bar
assetsUrl Where the character data is served from; see Hosting the data

Presets come with their own props: The Female Executive carries a handbag and The Professional Hitman a pistol. Pass 'none' to take one away, such as carry: 'none'.

Choose only the clips you need. A character with every clip is about 28 MB and takes several seconds to build; with three clips it's about 7 MB and takes 1–3 seconds.

What you get back

Property Meaning
scene The character: a three.js Group to add to your scene
animations The clips, for THREE.AnimationMixer
clip(id) The clip for an ID, such as hero.clip('walk')
props Props exported beside the character, such as a vehicle: { name, scene, animations }. They share the character's origin, so add them at the same position and play the matching clip on both
params The character's full settings. Save them to rebuild the same character later
colors The current colour of each part you can recolour, such as { top: '#5b6b3a', bottom: '#5b6b3a' }
height Standing height in metres
glb The character as a GLB file, for downloading or uploading
dispose() Frees the GPU memory when you remove the character

createCharacterGLB(input, options) returns only the GLB bytes and doesn't need three.js. Use it to save characters, send them to a server, or load them in another engine.

Colours

The colors option recolours fabric and props:

const exec = await createCharacter('The Female Executive', {
  colors: { outfit: '#1d2a44', shoes: '#111111', carry: '#8a1c1c' },
});
Part What it colours
outfit A suit, gown or other outfit made of one fabric. On a few older whole-body outfits it's multiplied over the fabric, so it can darken them but not lighten them
top, jacket, bottom Separate pieces, such as a shirt worn under a suit, or a T-shirt and jeans
shoes Heels, sneakers, oxfords, loafers and slides
carry The bag or other carried item
vehicle The vehicle's paint (or a horse's coat)

Which parts a character has depends on what it wears: hero.colors lists them with their current colours, which makes it easy to build colour pickers. Parts the character doesn't have are skipped, so the same colors work across a crowd. On patterned fabric, such as camouflage, the colour replaces the pattern's main colour. For a second colour or a different pattern, set garmentStyles in the character's settings (see the character schema). Weapons keep their own colours.

Chaining animations

playSequence() plays clips one after another, blending each into the next, and starts again after the last:

const hero = await createCharacter('The Priest', { animations: ['walk', 'wave', 'cheer'] });
const mixer = new THREE.AnimationMixer(hero.scene);
const sequence = hero.playSequence(mixer, 'walk 3s, wave, cheer x2');
// In your render loop: mixer.update(delta);

Faces

Every character carries face shapes, so it can change expression, blink and talk.

hero.setExpression('happy');         // or 0.5 for a hint of a smile: hero.setExpression('happy', 0.5)
hero.setMouth('viseme_aa');          // a mouth shape for lip-sync; hero.setMouth(null) closes it
hero.setFace({ browInnerUp: 0.6 });  // any face shape by name

// In your render loop, after mixer.update(delta):
hero.update(delta);                  // runs natural blinking; hero.blinking = false turns it off

Lists

PRESET_NAMES, ANIMATIONS (each clip's id, name, group, category and whether it loops) and PROPS (weapons, carried, vehicles) are available straight away, without loading any data. Use them to build pickers.

Hosting the data

By default the character data (about 50 MB, loaded only as needed and cached by the browser) comes from jsDelivr, a free public CDN, through the ara3d-data npm package. DEFAULT_ASSETS_URL shows the exact address, which is pinned to the data version this release expects.

To serve it yourself, for example for an offline app or a strict network:

npm install ara3d-data
cp -r node_modules/ara3d-data/assets public/ara3d-assets
await createCharacter('The Soldier', { assetsUrl: '/ara3d-assets/' });

Crowds, rigs and other animations

Good to know

For maintainers

The library lives beside the CLI in packages/cli/ (src/index.ts, with the worker in src/library/) and shares the generator code with the website. npx vite build --config packages/cli/vite.lib.config.ts builds dist/index.js, and npm run test:library checks it in headless Chrome, with photos in out/library/. The developers page (developers/index.html, src/developers/) runs the library from source for its playground; after npm run build, npm run test:developers checks it on desktop and phone, with photos in out/developers/. npm run release-cli builds both packages. When public/assets changes, raise the version in packages/data/package.json; --publish then publishes ara3d-data before ara3d.