AVEVA™ XR Studio

Avatar

Save PDF

Avatar

Save PDF

Last UpdatedFeb 19, 2025
10 minute read

Avatar is a complex node that defines an avatar, or the representation of a human character. The user or a script can move an avatar.

The avatar can be set as owner of objects, such as camera and torchlight, so that the avatar can directly handle navigation and torchlight use.
Every avatar has a complete set of attributes that enables definitions for animations, speeds, walking paths, and many other attributes.

Platform support

This node is fully supported on XR-Windows platform.

It is partially supported on XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-P WASM platforms.

XR-WIN	XR-P-WIN	XR-P-IOS	XR-P-AND	XR-P-WASM
Full support	Partial support	Partial support	Partial support	Partial support

Customizing Avatars

Work modes

An avatar has these work modes.

Work mode	Description
avatar	The avatar is driven by the user and has a camera is connected to it.
robot	Robot mode is the standard mode for NPC players. Use the robotControl parameter to assign a path to the avatar.
ghost	Ghost mode is the mode used for remotely controlled avatars in multi-playing.
controller	When set to controller mode, the avatar movements are controlled by an external node such as the AvatarControllerViewer.

Camera modes

When avatar is in avatar mode, there can be three camera modes.

Camera mode	Description
fps	First person view. The camera is centered in the eyes of the avatar.
behind	Behind third person view. The camera is right behind the shoulder of the avatar.
over	Fly mode view. The camera is free to go away from the avatar and navigate the scene freely. There are no collisions in over fly mode.

Robot mode

When in robot mode, you can assign a movement path to the avatar. This is often used to drive NCPS.

The syntax used by the robotControl parameter is a sequence of commands.

Command	Description	Examples
WALK	Enables the avatar to walk to an XZ coordinate position (WALK X Z) or close to an item at a specified distance and with a specific item relative angle (WALKitemName distance angle).	WALK 20 10 WALK V56300 0.8 #rad(45)#
RUN	Enables the avatar to walk to an XZ coordinate position (RUN X Z) or close to an item at specified distance and with a specific item relative angle (RUN itemName distance angle).	RUN 20 10 RUN V56300 0.8 #rad(45)#
CROUCHWALK	Enables the avatar to walk to an XZ coordinate position (CROUCHWALK X Z) or close to an item at specified distance and with a specific item relative angle (CROUCHWALK itemName distance angle).	CROUCHWALK 20 10 CROUCHWALK V56300 0.8 #rad(45)#
WAIT	Keeps the avatar still for the specified time in seconds.	WAIT 2
CROUCH	Keeps the avatar still and crouched for the specified time in seconds.	CROUCH 2
ANIM	Plays custom animation with syntax [duration] [anim name] [speed] [loop].	For example, ANIM 15 wave 1 true plays in loop for 15 seconds anim_wave at the speed of 1.
LOOP	Repeats the previous steps in a cycle.	LOOP

Code example

This is a code example combining the commands.

robotControl="WALK -24 8 WALK -24 4 WALK -27 3 LOOP"

Controller mode

Enables an external controller node such as the AvatarViewerController to drive avatar movements.

The avatar must be configured as follows:

Avatar.mode must be set to controller.
Avatar.controllerNode must be set to the name of the AvatarControllerViewer node.

When controlled by an external controller, the avatar position and orientation shows actual camera position.

Code example

This is a code example for the Avatar node.

<Avatar name="av0"

camera="cam"

mesh="omino00,omino00testa,omino00casco,omino00occhiali,omino00eyer,omino00eyel"

anim="omino00_anim,omino00testa_anim,omino00casco_anim,omino00occhiali_anim,omino00eyer_anim,omino00eyel_anim"

animations="Aspetta,Cammina,Run,CamminaCr,CamminaCr"

meshYaw="-1.5707"

position="-26.17672 4 8.985465"

orientation="0 0"

walkSpeed="2.50"

slideSpeed="2.50"

runSpeed="5"

crouchSpeed="1.25"

yawSpeed="2"

pitchSpeed="2"

physicsCmesh="CMESH"

torchlight="SpotTorch"

Position

The Avatar node must be inside a context node, such as Context or Global.

Avatar fields

These are the fields for avatar node. Only the node-specific fields are indicated, not fields obtained by inheritance.

Field inheritance: NodeBase > Avatar

Fields	Type	Use	Default value	Description
analyze	sbool	Optional	false	When set to true, the avatar analyzes the area (zoom feature).
anim	sstring	Mandatory		Comma-separated names of the animation scene objects that are related to the avatar. There is usually one anim for each avatar mesh.
animSpeed	sfloat	Optional	1	Increases or decreases the animation speed while avatar moves to sync animation with speed.
bodyRay	sfloat	Optional	0.5	Avatar cylinder collision ray. If an object is nearer than this value, the avatar can no longer move in that direction. This distance should be close to arm length.
behindPosition	svec3	Optional	0 0 0	Position when in behind mode. Read-only value for avatar in avatar mode.
behindOrientation	svec2	Optional	0 0	Orientation when in behind mode.Read-only value for avatar in avatar mode.
behindFov	sfloat	Optional	8	Defines the FOV of the camera owned by the avatar while moving around in behind mode. Works only when avatar is in avatar mode.
behindDistance	sfloat	Optional	4	Sets camera distance from avatar mesh in behind mode, in meters.
behindHeight	sfloat	Optional	0.3	Sets camera supplementary height, referred to the avatar mesh in behind mode.
camera	sstring	Optional		Reference name of the camera node to be associated and used by the avatar.
cameraMode	senum	Optional	fps	When the avatar is in avatar mode, there are three camera modes that can be applied to the camera: fps: First person view. The camera is centered in the eyes of the avatar. behind: Behind third person view. The camera is right behind the shoulder of the avatar. over: Fly mode view. The camera is free to go away from the avatar and navigate in free mode the scene. No collisions in over fly mode.
canClimb	sbool	Read only		When the avatar is over a climb-able area, the canClimb parameter changes to true.
climb	sfloat	Optional		Enables an avatar to climb up and down. 1 to move up, 0 to stay still -1 to move down.
climbSpeed	sfloat	Optional	0.5	Defines the speed of the avatar while climbing. The speed is expressed in mt/sec. Works only when avatar is in avatar mode.
crouch	sbool	Optional	false	When set to true, the avatar walks crouched.
crouchSpeed	sfloat	Optional	2.5	Defines the speed, in mt/sec, of the avatar while walking crouched. Works only when avatar is in avatar mode.
crouchFov	sfloat	Optional	75	Defines the FOV of the camera owned by the avatar while walking crouched. Works only when avatar is in avatar mode.
crouchHeight	sfloat	Optional	1	Defines the eye-to-feet distance of the camera owned by the avatar while walking crouched, in meters. Works only when avatar is in avatar mode. This field is ignored if the field useHeadsetHeight is true and the deployment target is an Oculus device.
crouchFov	sfloat	Optional	75	Defines the FOV of the camera owned by the avatar while analyzing. Works only when avatar is in avatar mode.
currentAnim	sstring	Mandatory		Comma-separated list of the AnimationGeometry objects that map the animations supported by the avatar, such as Wait, Walk, Run, Crouch, Crouchwalk. The order is important.
customAnim	sstring	Optional		Sets an animation to play from the DSTRING in the corresponding Human node Animations field. This couples a unique name (the one to be used here) to an included BonesHierarchyAnimation name.
customAnimLoop	sbool	Optional	false	When set to true, the customAnim animation plays in a loop.
customAnimSpeed	sfloat	Optional	1	Specifies the speed multiplier of customAnim animation playback.
customAnimStart	sevent	Optional		Triggers the starting of the playback of the customAnim animation.
customAnimStop	sevent	Optional		Stops the playback of the customAnim animation.
eyePosition	svec3	Optional		Avatar eye position. This is a read-only value for avatar in avatar mode.
flyX	sfloat	Optional		Use this to pilot camera in over mode forward and backward on the x avatar axis. 1 to move ahead, 0 to stay still -1 to move back.
flyY	sfloat	Optional		Use this to pilot camera in over mode up and down on the y avatar axis. 1 to move up, 0 to stay still -1 to move down.
flyZ	sfloat	Optional		Use this to pilot camera in over mode left and right on the Z avatar axis. 1 to move left, 0 to stay still -1 to move right.
flySpeed	sfloat	Optional	5	Defines the speed, in mt/sec, of camera in over fly mode.
mesh	sstring	Mandatory		Comma-separated names of the mesh scene objects that are part of the avatar. Usually, there are different meshes for character, body, and suits.
meshYaw	sfloat	Optional	0	Angle, in radiants, used to rotate all the meshes of the avatar in case they have wrong planar axis.
mode	senum	Optional	Avatar	An avatar can be set in different modes. This value impacts all the other available options, which are dependent on mode. avatar: The avatar is driven by the user and there is a camera is connected to it robot: The usual mode for non-playing characters (NPC) . Using the robotControl parameter, you can assign a path to the avatar ghost: This is the mode used for remotely moved avatars in multi-playing. controller: When set to controller mode, the avatar movements are controlled by an external node.
overPosition	svec3	Optional	0 0 0	Position when over. Read-only value for avatar in avatar mode.
overOrientation	svec2	Optional	0 0	Orientation when over. Read-only value for avatar in avatar mode.
overFov	sfloat	Optional	85	Defines the FOV of the camera owned by the avatar while flying in over camera mode. Works only when avatar is in avatar mode.
overHeight	sfloat	Optional	10	Defines height offset that is given to the avatar camera when switching to over mode. The initial over camera height is position + avatar height + over height offset.
overPhysics	sbool	Optional	false	When set to true, the avatar collides in over mode according to what was set for overRay parameter.
overRay	sfloat	Optional	5	Avatar cylinder collision ray used in over mode. If an object is closer than this value, the avatar can no longer move in that direction. Works only when overPhysics is set to true.
overStartOrientation	svec2	Optional	0 -1.58	The initial over mode orientation.
overToItem	sstring	Optional		If the item node exists, it moves the avatar until it stands over the selected item. Also supports avatar values.
overToItemDistance		Optional	0.2	Distance from the item center when moving by overToItem parameter.
orientation	svec2	Optional		Orientation position. This is a read-only value for avatar in avatar mode.
position	svec3	Optional		Avatar position. This is a read-only value for avatar in avatar mode.
pickingStrategyNode	sstring	Optional		Avatar collides with objects with respect to the rules set in the PickingStrategy node. Note: When name is unspecified, avatar collides with cmeshes.
pitch	sfloat	Optional		Enables avatar to rotate camera up and down. Positive values force up rotation, negative down rotation. Works only when avatar is in avatar mode.
pitchSpeed	sfloat	Optional	2	Defines the pitch rotation speed of the avatar, in radiants.
physicsActive	sbool	Optional	true	Enables and disables check for ground through collision and eventual gravity acceleration.
robotControl	sstring	Optional		Defines a sequence of actions to be taken by the robot mode avatar.
run	sbool	Optional	false	When set to true, the avatar runs instead of walking.
runFov	sfloat	Optional	100	Defines the FOV of the camera owned by the avatar while running. Works only when avatar is in avatar mode.
runHeight	sfloat	Optional	1.6	Defines the eye-to-feet distance, in meters, of the camera owned by the avatar while running. Works only when avatar is in avatar mode. This field is ignored if the field useHeadsetHeight is true and the deployment target is an Oculus device.
runSpeed	sfloat	Optional	5	Defines the speed of the avatar while running. The speed is expressed in mt/sec. Works only when avatar is in avatar mode.
setFromCamera	sstring	Optional		Use at runtime to set avatar position and orientation taking these values from a camera. The value must match a camera node name. It is used in over mode.
slide	sfloat	Optional		Enables avatar to slide left and right. 1 to slide left 0 stay still -1 to slide right. Works only when avatar is in avatar mode.
slideSpeed	sfloat	Optional	2.5	Defines the speed of the avatar while sliding left and right. The speed is expressed in mt/sec. Works only when avatar is in avatar mode.
torchLight	sstring	Optional		Reference name of the logical torchlight object to be associated and used by the avatar. See Torchlight node.
useHeadHeight	sbool	Optional	true	Applies to Oculus target only, when enabled the camera height in the virtual environment is controlled by the Oculus device tracking and will match the actual device height from the phisical floor. When this flag is enabled, and the deployment target is an Oculus device, the fields walkHeight, runHeight and crouchHeight are ignored in the positioning of the camera
walk	sfloat	Optional		Enables avatar to move forward and backward. 1 to move ahead, 0 to stay still -1 to move back. Works only when avatar is in avatar mode.
walkSpeed	sfloat	Optional	2.5	Defines the speed of the avatar while walking (not running, not crouched). The speed is expressed in mt/sec. Works only when avatar is in avatar mode.
walkFov	sfloat	Optional	85	Defines the Field of View (FOV) of the camera owned by the avatar while walking (not running, not crouched). Works only when avatar is in avatar mode.
walkHeight	sfloat	Optional	1.8	Defines the eye-to-feet distance of the camera owned by the avatar while walking (not running, not crouched) in meters. Works only when avatar is in avatar mode. This field is ignored if the field useHeadsetHeight is true and the deployment target is an Oculus device.
walkToPosition	svec3	Optional	0 0 0	When value changes, the avatar starts walking toward the specified position until it reaches it. No check on Y component of the position is made to determine if the avatar reached the position.
walkToPositionIsRunning	sbool	Read Only	false	Automatically set to true when the avatar is walking toward the specified position in walkToPosition field.
walkToItem	sstring	Optional		When an Item node name is specified, the position of that item is copied into the walkToPosition field causing the avatar to move toward the specified object until reached.
yaw	sfloat	Optional		Enables avatar to rotate on the plane CW or CCW. Positive values force CW rotation, negative CCW. Works only when avatar is in avatar mode.
yawSpeed	sfloat	Optional	2	Defines the yaw rotation speed, in radiants, of the avatar.

AVEVA™ XR Studio

Avatar

Table of Contents

Avatar

Platform support

Customizing Avatars

Work modes

Camera modes

Robot mode

Code example

Controller mode

Code example

Position

Avatar fields

In This Topic

Related Links