Add a 3D character to a three.js scene
Add a Convai character to an existing 3D web scene with the framework-free Convai Embody API and update it from your own render loop.
Add a Convai character to a three.js scene you already render, without React. Use this page when your app owns the renderer, scene, and camera. At the end, the character stands in your scene and speaks with lip sync, driven from your render loop.
Prerequisites
A three.js app with a renderer, a scene with lights, a camera, and a render loop.
Node.js 18 or later and a bundler.
A Convai API key or auth token, and a character ID. The character's avatar needs a published web body, or a default body must apply to it.
Install the packages
The root entry point of @convai/embody imports neither React nor @react-three/fiber, so this path needs only the two required peer dependencies.
npm install @convai/embody @convai/web-sdk threeCreate the character
createCharacter resolves the character's body, loads it, opens the Convai Web SDK connection, and returns a handle. Add the handle's root to your scene and give it your camera so the character's gaze can track it.
import * as THREE from 'three'
import { createCharacter } from '@convai/embody'
export async function addCharacter(
scene: THREE.Scene,
camera: THREE.Camera,
renderer: THREE.WebGLRenderer,
token: string,
) {
const character = await createCharacter({ token, characterId: 'YOUR_CHARACTER_ID' })
scene.add(character.root)
character.camera = camera
const clock = new THREE.Clock()
renderer.setAnimationLoop(() => {
character.update(clock.getDelta())
renderer.render(scene, camera)
})
return character
}update advances the animation, lip sync, gaze, breathing, and blinking by the elapsed seconds. Call it once per frame, before rendering.
If the character has Long-Term Memory turned on, the connection also needs an end-user id so the character can tell your users apart: createCharacter({ token, characterId, session: { endUserId: user.id } }). Without it, connecting fails with "Missing end_user_id".
Light the character
The character takes whatever lights your scene has. For a portrait that reads like the studio films, createPortraitRig returns the rig ConvaiCharacter uses in its own canvas (a key 45° to the left of the camera with soft shadows, a cool fill, a warm rim, a faint sky), and placePortraitRig turns it to follow the camera each frame. PORTRAIT_TONE is the matching tone mapping.
Skip this if your scene is already lit the way you want it; the character's skin, hair, eyes and teeth are shaded to take any lighting.
Send a message to the character
character.client is the Convai Web SDK ConvaiClient that Convai Embody opened. Use it for the conversation. It is null only when the character was created with connect: false.
Release the character
Call dispose when the character leaves the page. It releases the model, its materials and textures, and the animation mixer, and closes the connection Convai Embody opened.
A client you passed in through the client option is left connected. Your app owns its lifetime.
Verify the character
Run the app and send a message.
If createCharacter rejects, read the error message. The troubleshooting section of the React guide covers the same errors, because both paths share one loader.
Next steps
createCharacter referenceHow Convai Embody worksLast updated
Was this helpful?