Character QML Type

What the running activity wants the hands to be doing, "" when none does.

The same kind of layer as gaitHandPose and it sits beside it: a Fighting character's hands are fists and a Using character's are loose, whatever handPose says. Before it existed nothing on the Fighting path could close a hand, so a punch was thrown with the fingers open and the whole cycle read as clawing rather than boxing.

See also handPose, gaitHandPose, and ActionCycleAnim::handPose.

How hard at it a Using or Fighting character is, 0..1.

Speed and amplitude, never a different pose: a harder fight is a faster one with a tighter guard, and harder work is a bigger stroke.

See also activity and workHeight.

The move being played, or the one whose last frame is being held; "" when nothing is.

Current activity state. Use Character.Activity enum: Idle, Walking, Running, Using, Fighting.

Arm/sleeve color.

Depth of the arms.

Total arm length.

How much the forearm tapers.

Upper arm proportion of total arm.

Width of the arms.

Whether the character blinks on its own. On by default.

Off at Detail.Minimal regardless, where there is no eye left to shut. Two characters sharing a blinkSeed blink in step, which is the one thing a crowd must not do.

See also blinkSeed and Head::blink.

The lower trunk. Pitching it bends the body at the hip; the chest, the arms and the head come with it.

How far the belly swells past the plain trunk taper. 1 leaves it alone, 1.3 is a gut, below 1 tucks it in.

Mostly depth and rather less width, because that is how a belly reads: it grows forward. The bottom of the belly stays at waistWidth by torsoDepth however far it bulges, so the swell hangs off the ribs rather than off the pelvis. ParametricCharacter drives it from mass.

Colour of the lower trunk. Follows torsoColor until set.

The belly's share of torsoHeight, 0..1. The rest is the chest, and the waist joint sits between them.

The trunk is two boxes on a joint rather than one box, which is what lets a back round and a chest swell. 0.45 puts the joint where a waist is; at that value, and with bellyBulge, chestSwell and waistPinch left alone, the pair traces exactly the tapered box the torso used to be.

See also belly, chest, and Gait::spineCurve.

Which repeatable blink-and-glance rhythm this character gets.

Everything in the idle face is deterministic for a given seed, so two runs of a sandbox render identically and two characters standing next to each other do not. Give each of a crowd its own.

How far the body has travelled forward over its own feet, in the character's own units.

The companion of gaitLift on the other axis, and written by the same animators: a step, a jump or a stagger moves the whole figure - feet included - relative to the character's position, and comes back to zero by the end of the move. Carrying the character itself across the floor is the caller's business; nothing here ever writes position.

See also gaitLift and moveSet.

The upper trunk, on the waist joint. Pitching it against the belly is what rounds a back or lifts a chest - a curve rather than a tilt.

Colour of the upper trunk. Follows torsoColor until set.

How much deeper the chest is than the plain trunk taper. 1 leaves it alone.

Depth only: the chest's width is shoulderWidth and stays it. ParametricCharacter drives it from muscle.

How pointed the chin is (0-1).

Current movement speed based on activity.

How much character to draw. Auto by default.

Auto has to measure the character against something, and a character does not know what it is being looked at through - so with no view it stays Low. That is deliberately the same as the old behaviour, so the default costs an existing scene nothing until it opts in by handing over a view.

See also view, detailThreshold, minimalThreshold, and effectiveDetail.

How tall the character has to be on screen, in pixels, before Auto gives it fingers.

The default of 240 is measured rather than picked: an extended index finger stops being readable at all somewhere around a 90 px figure and is comfortable by about 120, so the switch sits well clear of the point where the fingers it buys would be invisible anyway.

There is a hysteresis band below it - a character drifting across the line would otherwise grow and shed ten boxes a hand every few frames.

Whether the hands have fingers right now.

The answer, not the question - detail is the question. Under Auto this flips on its own.

See also DetailedHand and detail.

Which Detail level is actually being drawn - never Auto.

The face the character is wearing between lines: "happy", "sad", "angry", "disgust", "surprised" or "" for neutral.

Unlike speechEmotion this one persists - it is what the face returns to when a spoken line with its own emotion has finished.

Eye color.

Eye size multiplier.

Current facial expression activity.

Foot/shoe color.

Depth of the feet.

Height of the feet.

Width of the feet.

How this character walks and runs, by preset and by factor.

A neutral Gait - the default - changes nothing. Replace it to ask for something:

Character { gait: Gait { preset: "heavy"; bounce: 0.02 } }

It composes with what the build and the mood say rather than overriding them; see gaitFactors.

The build as the gait model reads it: an object with maturity, femininity, mass and muscle in 0..1, or null. A ParametricCharacter binds its sliders here.

The composed, clamped factor vector the cycles are walking with.

The thing to assert on: it says what the character was asked to do, where a joint angle mid-swing says only where the leg happens to be. Keys are the thirteen factors of Gait.

Whether the body's build shapes the gait. On by default.

A ParametricCharacter walks by its sliders: a child's quick high steps, an elderly shuffle, a heavy rock, a feminine sway. All subtle, zero at every default, and switched off here for a character whose walk should ignore its body.

Whether the mood shapes the gait. On by default.

The same channel the face uses: a spoken line's emotion while it is spoken, emotion otherwise. A sad character slows and slumps, a happy one springs, an angry one leans in with the elbows bent - the walking counterpart of speechBodyLanguage.

Whether the eyes move inside the head. On by default.

Off pins them dead centre, which is how every character looked before this existed.

See also lookAt, thinking, and GazeAnim.

What the hands are doing: "point", "present", "thumbsUp", "talk", or "" for nothing.

Set the moment a gesture is asked for, while the arm is still on its way there - which is what makes it the thing to assert on. Reading joint angles instead, before gestureSettled, reports the pose the character has just left.

Stretches the rhythm of gesticulate(). 1 is as authored, above 1 is a slower speaker.

Which arm is doing it: "left", "right", or "" while released or while talking, which is two-handed.

How long a gesture takes to arrive at, and to leave.

True once the pose has arrived - the cue to start talking about the thing that was pointed at.

Colour of the gloves and their cuffs.

Whether the hands are gloved - their own colour, and a cuff at each wrist.

A cartoon convention, and a legibility one: a hand the colour of the arm it is on has to be found before it can be read. See Arm::gloved.

See also gloveColor and handScale.

Hair color.

Hair volume multiplier.

Hand color.

Depth of the hands.

Height of the hands.

What the hands do when no gesture is claiming them: "relax", "open", "point", "thumbsUp" or "fist".

Read at both levels of detail. Fingers fold for it when there are fingers; the plain box reshapes itself to the same pose's outline when there are not.

The wrist's resting roll in degrees, signed per side by whoever applies it: 90 turns the palms in to face the body.

Where a hand sits when nothing is posing it - standing as much as walking, because a palm facing backwards off a hanging arm is a mannequin either way. The same quarter turn about the same axis (the hand's own Y, which is the forearm) that GestureAnim's thumbs-up uses. A gait scales it through the handRoll factor; a gesture, a use or a fight owns the wrist outright while it runs.

How much bigger the hands are drawn than the proportion tables give. 1 leaves them alone.

Pairs with gloves: the two together are how a cartoon makes a gesture readable across a room. Big enough to see, light enough to find. detail accounts for it - bigger hands mean the fingers are worth drawing from further away.

Width of the hands.

Reference to the head for animation.

Total head height (upper + lower).

Where the head node sits, in the character's own coordinates - the origin of the anchors published by Head.

Reference to the hip.

Hip/pants color.

Depth of the hip section.

Height of the hip section.

Width of the hips.

Duration of the idle animation cycle in milliseconds.

Reference to the left arm for animation.

Reference to the left leg for animation.

Where the left shoulder joint sits, in the character's own coordinates.

Leg/pants color.

Depth of the legs.

Total leg length.

How much the lower leg tapers.

Upper leg proportion of total leg.

Width of the legs.

Whether this character is attending to someone.

Says a target is set and the behaviour is live - NOT that the other one is currently making a sound. A listener between two sentences is still listening.

Who this character is listening to, or null.

While it is set the eyes hold that character's face, break away every few seconds because a continuous stare is not attention, and mark the ends of its phrases. It takes over the look target for as long as it is set - lookAt() and this are the same channel, and this is the one holding it.

The other half of a conversation. Everything else here describes a character while it speaks; without this the one who is not speaking does nothing at all, which is what makes two characters talking read as two monologues in turn.

See also ListenAnim, lookAt, and GazeAnim.

Depth of the lower head/jaw.

Height of the lower head/jaw.

Width of the lower head/jaw.

How small the character has to get, in pixels of figure height, before Auto takes its face away.

Measured the same way as detailThreshold, by looking: at an 83 px figure the eyes are clearly there and a character without them reads as faceless rather than as distant; at 56 px it is marginal; by 26 px the two are the same picture. 60 is the honest cut.

Worth thirteen draw calls a character - a face is two thirds of a head.

Mouth size multiplier.

What the running move wants the hands to be doing, "" when no move is running. Folded into actionHandPose.

True while the loaded set owns the joints - playing, or sitting on the last frame of a move that holds.

True while a move is actually animating - false while a knockdown lies on the floor, which moveHolding is for.

The loadable move set on this character, "" for none.

Either the name of a set that ships with the plugin - see shippedMoveSets, currently "martial arts" - or the URL of a MoveSet QML file of your own. Setting it loads the set and drops whatever was loaded before; setting it to "" unloads.

Loading does not itself move the character. Play something with playMove():

Character {
    id: fighter
    moveSet: "martial arts"
    Component.onCompleted: fighter.playMove("stance")
}

A set only runs while activity is Idle, exactly as a gesture does: playMove() puts the activity back to Idle rather than quietly doing nothing, and starting any other activity drops the move.

See also playMove(), moves, MoveSet, and MartialArts.

What the loaded set calls itself, "" when none is loaded.

What the loaded set offers: a list of {name, label, group, loop, holds}, empty when no set is loaded.

Enough for a UI to build a row of buttons without knowing what the set is about.

Character identifier name.

Height of the neck section.

Nose size multiplier.

Reference to the right arm for animation.

Reference to the right leg for animation.

Where the right shoulder joint sits, in the character's own coordinates (origin between the feet, +Z is the way the character faces).

Published so gesture and aiming code can start from the joint that does the work instead of re-summing the body hierarchy - and so it keeps pointing at a shoulder when the torso's proportions change.

How rounded every box in the character is, 0 for the hard-edged original and about 0.3 for something nearly spherical.

A chamfer on every edge and corner of every part. It is what separates a character built out of bricks from one built out of pebbles, and the reason the cartoon tradition it comes from is full of round shapes: roundness reads as soft, friendly and alive, where a right angle reads as built.

It costs draw calls: none. A box goes from 12 triangles to 44 and stays one draw call, and a character's cost was measured at 17.8 microseconds per draw call and next to nothing per vertex - so this is close to free and having more characters is not. See the crowd scene of the character lab, labs/kits/character/CrowdField.qml.

See also Box3D::bevel.

Running speed derived from animation geometry.

Whether a raised pointing arm is forced to bend at the elbow.

On by default, and a policy rather than a tuning value: a straight arm raised forward reads as a fascist salute, which no character should be able to strike by accident while pointing at something high. The forearm does the reaching instead and the aim is unaffected. Turn it off for a character whose job is exactly that shape - a salute, a hand-raise, a throw.

The sets that ship with the plugin, as a map of name to the URL moveSet resolves it to.

Width at the shoulders.

Skin color for head, hands, and feet.

True while the character is speaking (text or audio), including between the segments of annotated text.

The character's speech engine for advanced configuration (volume, rate, pitch) and signals (started/finished).

How closely a recorded line is analysed for lip-sync.

Speech.Envelope reads loudness only - the shape of the mouth is a guess. Speech.Spectral (the default) reads formant bands, so an open vowel opens further than a closed one, a front vowel spreads and a back vowel rounds.

Not a performance dial: the analysis is a few hundred thousand flops for a whole line, once, before playback starts. What it costs is time-to-first-sound and the samples held while it runs, which is why a barked NPC line and a lecture can want different answers.

Whatever is asked for, the mouth still moves: an unreadable recording falls back on its own. Speech::effectiveAccuracy says what the last line actually got.

See also Speech.

Whether emotional speech may use body language gestures.

When true and the character is otherwise idle, saying something with an emotion plays a matching gesture loop (slumped sway when sad, bouncy arms when happy, agitated pumping when angry). The gestures never override other activities - a walking or fighting character keeps its body animation and only face and voice carry the emotion.

The emotion of the current speech ("happy", "sad", "angry", "disgust", "surprised", or empty for neutral).

Whether the character is working something out.

While true the eyes leave whatever they were looking at and settle off-axis, which is what a person does while recalling something rather than reading it off the listener's face. Releasing it brings them back.

It is the most legible "thinking" signal a face has, and on a boxy one it is the only one - there is no brow furrow to read at ninety pixels. Set it around the gap between being asked and answering.

See also gazeBehaviour and lookAt.

The trunk as a whole - the frame belly and chest hang in. It draws nothing; turning it turns the whole upper body, which is what sway and rock do.

Torso/shirt color - both segments unless one is given its own.

Depth of the torso.

Height of the torso.

Depth of the upper head.

Height of the upper head.

Width of the upper head.

The View3D this character is being seen in.

Only Detail.Auto needs it, and only to ask how many pixels tall the character currently is. Set the same way Label3D takes one.

How far in the waist joint is drawn, as a fraction of the width the taper would have there. 0 (the default) is no pinch.

The one shape a single tapered box could not make: narrow in the middle and wider at both ends.

Width at the waist - where the trunk meets the hip.

Walking speed derived from animation geometry.

Where the work is while activity is Using: 0 a table at the waist, 0.5 a counter at the chest, 1 a shelf at head height.

Moves the whole posture, not only the hands: over a table the back rounds and the head is down at the work, at a counter the forearms angle up, and at a shelf the back arches and the head comes up - reaching high is not something anyone does bent over.

See also activity and actionIntensity.

Emitted when a one-shot move of the loaded set reaches its end.

The joint angles the action cycle ("use" or "fight") holds at phase t, 0..1, with nothing running.

Pure, and the same answer the running cycle gives at that moment - ActionCycleAnim plays this very function. Returns {rightArm, leftArm, rightLeg, leftLeg, hip, torso, belly, chest, head, hand} in the joints' own conventions, with the wrist roll as a fraction of a quarter turn. The gesture sheet is drawn from it.

See also applyActionPose() and gaitPoseAt().

The derived numbers the action cycle ("use" or "fight") is replayed from at this character's actionIntensity and workHeight - its cycleMs among them.

See also actionPoseAt() and ActionCycleAnim::table.

Freezes the joints at phase t of the action cycle.

For looking, not for playing, exactly as applyGaitPose() is: it only makes sense while activity is Idle and no gesture holds the joints, since a running cycle would animate over it within a frame. A row of characters frozen at successive phases is the action on one sheet; see the gesture sheet of the character lab, labs/kits/character/GestureSheet.qml.

The hands are NOT written here - they are handPose's, and a sheet sets that itself.

Freezes the joints at phase t of the base cycle.

For looking, not for playing: it writes the pose of gaitPoseAt() straight onto the joints, which only makes sense while activity is Idle and no gesture holds them - a running cycle would animate over it within a frame. A row of characters frozen at successive phases is a walk cycle on one sheet, the way animators check one; see the gait sheet of the character lab, labs/kits/character/GaitSheet.qml.

Freezes the joints at phase t of move.

For looking, not for playing, exactly as applyActionPose() is: a row of characters frozen at successive phases is the move on one sheet.

The joint angles this character's gait has at phase t of the base cycle ("walk" or "run"), 0..1, with nothing running.

Pure: the same answer as the running cycle would give at that moment, computed from gaitFactors. Returns {rightLeg, leftLeg, rightArm, leftArm, hip, torso, belly, chest, head, lift} in the joints' own conventions, lift in leg heights. The cycle sheet is drawn from it.

The derived numbers the base cycle ("walk" or "run") is replayed from at this character's gaitFactors - its cycleMs among them.

The gait counterpart of actionTable(): what gaitPoseAt() poses from, handed out so a lab can quote a cycle's length without an animation running.

See also gaitPoseAt() and actionTable().

Talks with the hands: a loose two-handed gesticulation that runs until stopGesture().

The other half of pointing. A finger held on a thing for the length of a paragraph turns the character into a signpost; the point has said "this one" within a second or two, and everything after that is explanation, which people deliver facing whoever they are explaining it to. It replaces any point or thumbs-up - one layer owns these joints - and it never stops by itself.

Ignored unless activity is Character.Activity.Idle.

Aims the head - and only the head - at a position in the scene.

Outranks whatever the running gesture wanted to do with the head, so a character can point at one thing and address someone else. Pass null to hand the head back.

Ignored unless activity is Character.Activity.Idle.

The joint angles move of the loaded set holds at phase t, 0..1, with nothing running. Null when there is no such move.

Pure, and the same answer the running move gives at that moment - the set plays this very function.

See also applyMovePose() and actionPoseAt().

Nods, without losing what the head was looking at.

Rides on Head::offsetEuler, so it composes with the aim a body animation or a lookAt() is holding rather than replacing it.

degrees defaults to 7 - a backchannel nod, not a bow - and times to 1.

See also Head::nod and listeningTo.

Plays move of the loaded set. Returns false, and does nothing, when no set is loaded or the set has no such move.

A move owns the whole body, so this drops any held gesture and puts activity back to Idle first - a call that quietly did nothing while a walk was running is one nobody can tell from a broken move.

Points at a position in the scene and holds it.

which picks the arm: "auto" (the default - whichever side the target is on), "left" or "right". The body turns most of the way toward the target, leaving the last few degrees to head and shoulder, and the head looks at it unless lookAt() says otherwise.

The pose is solved once, against the frame the character stands in when it is asked for. Move the character afterwards and the arm is aimed at where the target used to be relative to it - point again.

Ignored unless activity is Character.Activity.Idle.

Offers an open hand toward a position in the scene and holds it - the presenter's "here we have".

Palm up, hand at chest height, elbow bent: the gesture for a GROUP or an AREA - several parts, a whole circuit - where a finger at the centroid would point at nothing in particular. which picks the arm exactly as in pointAt(); the body turns toward the target by the same rule and the head looks at it.

The hand is never raised toward the target - only turned toward it - so the silhouette stays folded whatever the target's height. Something far above or below the hand is what pointAt() is for.

Ignored unless activity is Character.Activity.Idle.

Makes the character say something with lip-synced mouth movement.

Pass either plain text (spoken via text-to-speech when available, otherwise the mouth animates silently) or a path/URL to a wav/mp3 file which is played back while the mouth follows the audio.

For a recording, the optional transcript is what it was recorded saying. With speechAccuracy at Speech.Aligned the mouth then takes its shapes from that script and only its timing from the audio, which is the only way a /m/ closes reliably - a bilabial is voiced, so every acoustic measurement of one says "loud", not "shut".

The optional emotion ("happy", "sad", "angry", "disgust" or "surprised") colors the conversation: facial expression, voice pitch/rate (for TTS) and - if the character is idle and speechBodyLanguage is enabled - matching body language. Everything is restored when the speech finishes.

Text may switch the emotion mid-speech with inline annotations:

npc.say("*angry* Get off my ground! *happy* Just kidding, come in.")

Recognized annotations are *happy*, *sad*, *angry*, *disgust*, *surprised* and *neutral* (plus the aliases *joy*, *anger*, *sadness*, *disgusted*, *surprise*, *shocked* and *calm*); each one applies from where it appears. The emotion argument sets the tone before the first annotation. Unknown annotations are left in the text untouched.

Puts a lasting expression on the face: "happy", "sad", "angry", "disgust", "surprised", or "neutral"/"" for none.

Aliases: "joy", "sadness", "anger", "disgusted", "surprise", "shocked", "calm". A name that is none of these is neutral.

Persists until it is changed, which is what separates it from the emotion of one spoken line: say() colors the face for the length of that line and then restores whatever was set here.

See also emotion and Head::Activity.

Eases every held joint back to the resting pose.

The graceful counterpart to a gesture starting. A head aimed by lookAt() is released with it.

Stops the running move and lets go of the joints, which the idle pose then takes back to standing.

Interrupts the current speech output.

Gives a thumbs up with which hand ("right" by default).

Ignored unless activity is Character.Activity.Idle.

Turns the whole body on the spot to face a position in the scene, the short way round.

Changes the orientation the character rests in, so it outlives the next stopGesture(). Nothing moves if the target is where the character already stands.

Ignored unless activity is Character.Activity.Idle - a walking character is steered by its controller instead.