Avatar Animation Commands

Beta: Avatar animation commands are still a work in progress. Supported animation names, behavior, and avatar compatibility may change while this feature is being refined.

To configure a 3D avatar first, see Create a 3D avatar.

Querlo Chat supports animation requests for both 3D avatar types:

• Avaturn avatars
• ReadyPlayerMe avatars

The same command format works for both. The client sends the request to whichever 3D avatar is currently active in the chat.

Studio Usage

In Querlo Studio, use a command node of type clientEvent and pass this JSON object:

{
  "name": "Q-AVATAR-ANIM",
  "params": {
    "name": "happy",
    "duration": 1200,
    "intensity": 1
  }
}

The params object is the animation request.

Animation Request Fields

{
  "name": "happy",
  "duration": 1200,
  "intensity": 1,
  "repeat": 1,
  "fade": 0.18
}

• name: Required. Animation name to play.
• duration: Optional. Duration in milliseconds. Default is 900.
• intensity: Optional. Movement/expression strength. Default is 1. Values are clamped from 0 to 2.
• repeat: Optional. Used mainly by clip-based or looping animations.
• fade: Optional. Fade time for real embedded GLTF animation clips. Default is 0.18.

Common Animation Names

These work as high-level animation requests:

happy
laugh
surprised
confused
thinking
skeptical
smile
blink
nod
shakeHead
jump
wave
dance
lookLeft
lookRight
idleShift
agree
disagree

Eye Animations

Eye animations are merged automatically. For example, requesting eyeLookUpLeft makes both eyes look up.

eyeLookUpLeft
eyeLookUpRight
eyesLookUp
eyeLookDownLeft
eyeLookDownRight
eyesLookDown
eyeLookLeft
eyeLookRight
eyeBlinkLeft
eyeBlinkRight
eyesClosed
eyeSquintLeft
eyeSquintRight
eyeWideLeft
eyeWideRight

Avaturn Blendshape Animations

Avaturn currently exposes these supported facial blendshape requests:

mouthSmile
mouthSmileLeft
mouthSmileRight
mouthUpperUpLeft
mouthUpperUpRight
noseSneerLeft
noseSneerRight
browDownLeft
browDownRight
browInnerUp
browOuterUpLeft
browOuterUpRight
cheekSquintLeft
cheekSquintRight

If the Avaturn file contains an embedded GLTF clip, it can also be requested by name. The current known clip is:

avaturn_animation

Examples

Happy expression:

{
  "name": "Q-AVATAR-ANIM",
  "params": {
    "name": "happy"
  }
}

Thinking expression:

{
  "name": "Q-AVATAR-ANIM",
  "params": {
    "name": "thinking",
    "duration": 1600,
    "intensity": 0.8
  }
}

Make both eyes look up:

{
  "name": "Q-AVATAR-ANIM",
  "params": {
    "name": "eyeLookUpLeft",
    "duration": 800
  }
}

Play Avaturn embedded animation:

{
  "name": "Q-AVATAR-ANIM",
  "params": {
    "name": "avaturn_animation",
    "duration": 2000
  }
}

Notes

• The chat must be using a 3D avatar for the command to have a visible effect.
• Animation requests are queued by the chat message queue, so multiple Q-AVATAR-ANIM client events play one after another.
• If no matching animation, blendshape, or morph target exists, the client logs an unsupported animation warning.
• Advanced full-body animations such as real dances require compatible animation clips in the avatar file or external animation assets.