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:
- A preset name:
'The Soldier'.PRESET_NAMESlists all 32. - A share link from the builder: design a character visually at ara3dgen.com/app, choose Share, copy the link and pass it in:
await createCharacter('https://ara3dgen.com/app/#c=eJyr...'); - A random character:
{ random: 42 }. The same seed always gives the same person, so a crowd of{ random: 1 }to{ random: 50 }looks the same on every visit. - An
ara-characterobject: a preset plus changes, the same format as the CLI's character files and the builder's LLM Assist:await createCharacter({ preset: 'The Bride', params: { name: 'Ada', ageYears: 30 } }); - Character settings: the
params.jsonfrom any export, or your own values. See the character schema for every field and what it means.
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);
- A clip that loops (walk, idle, run) plays one cycle unless you give it a length, such as
walk 3s. - A one-off move (wave, jump, cheer) plays once, or as many times as you ask, such as
cheer x2. - Steps can also be an array:
['walk', { clip: 'wave', times: 2 }, { clip: 'idle', seconds: 4 }]. - Options:
{ fade: 0.5 }sets the blend in seconds (default 0.35), and{ repeat: false }stops on the last clip. - Every clip in the sequence must be in the
animationsyou built the character with.sequence.stop()ends the sequence and hands the mixer back to you.
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
- Expressions:
EXPRESSIONSlists them: neutral, happy, laughing, angry, sad, crying, surprised, afraid and determined. A character starts with the expression in its settings. - Lip-sync:
MOUTH_SHAPESare the 14 Oculus viseme names (viseme_aa,viseme_PPand so on) that lip-sync tools output. Feed each viseme your tool reports tosetMouth(). While a mouth shape shows, it moves the jaw and the expression's smile or frown eases off, so talking and expressions combine without over-stretching the mouth. - Face shapes:
FACE_SHAPESlists every shape, with ARKit-style names (eyeBlinkLeft,jawOpen,mouthSmileand so on), so face-capture data can drive them directly. - A few clips animate the face themselves, such as talk and laugh. While one plays, three.js's mixer sets those shapes each frame; blinking still runs on top.
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
- Crowds: build a few characters, then clone them instead of rebuilding. Clones share the geometry and textures, so they cost little memory:
Mix in random characters (import { clone } from 'three/examples/jsm/utils/SkeletonUtils.js'; const walker = clone(hero.scene); scene.add(walker); new THREE.AnimationMixer(walker).clipAction(hero.clip('walk')).play();{ random: n }) for variety, and usedetail: 'low'with only the clips the crowd needs. - T-pose: characters are rigged in a natural A-pose. Pass
{ preset: 'The Soldier', params: { restPose: 'T' } }for a T-pose, which Unity Humanoid and many retargeting tools expect. - Smaller rigs:
params: { rig: 'game_lite' }gives a 25-bone skeleton without fingers, for distant characters. See Rigging for every option. - Mixamo and other animations: the default game rig uses Mixamo's bone names (
Hips,Spine,LeftArmand so on). Mixamo files prefix their bones withmixamorig:, so rename their tracks to match, for exampletrack.name = track.name.replace('mixamorig:', ''). Clips made for a T-pose skeleton work best on a character built withrestPose: 'T'. If limbs still twist, the skeletons' bone orientations differ; retarget with a tool such as three'sSkeletonUtils.retargetClip.
Good to know
- Responsiveness: building runs in a worker, but loading the finished model into three.js happens on the page and takes a moment for large characters. Build during a loading screen, or keep
animationssmall. - Pages opened as files: browsers block the worker on a page opened straight from disk (
file://), so serve it, even locally (npx serve). - Content-Security-Policy: the worker runs from a
blob:address. Sites with a strict policy needworker-src blob:. - Several characters: the data loads once and is shared, so later characters build faster.
- Licence: the library is MIT. Characters are built from CC0 MakeHuman data, with animations from the CMU Graphics Lab Motion Capture Database, so you can use them in commercial projects.
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.