Avatar Description File Parameters

From RexWiki

Avatar description .xml file parameters

• The realXtend avatar's animations and other properties (like the appearance controls seen in Avatar Generator) are defined in an .xml file named after the avatar mesh, for example Jack.xml for the Jack avatar
• This file is also placed into media\models\avatar directory within the realXtend viewer installation.
• The definition file isn't strictly necessary; if it doesn't exist or doesn't have any animations defined, the default animations from app_settings\ogre_avatar_animations.xml will be used.
• For a minimal example of an avatar .xml file, see Mushroom_bone.xml in media\models\avatar. This defines the run, walk & crouchwalk animations to refer to an animation named Walk (the only one that exists for the Mushroom avatar)

Animation definitions

Animation definitions are identified by the xml tag "animation". The parameters are the following:

• name
  • Identifies the animation definition. Otherwise not used internally, but "WALK" has special meaning: in Avatar Generator one can choose different walk animations (the alternate walk animations should have Walk prefix in the name)
• uuid
  • SL UUID of the animation, for the basic animations like walk, hover, and the pre-existing SL gestures. These are sent from the world server and we need these to know what animation it is! Copy this value from the defaults; do not modify it.
• ogrename
  • What actual animation defined in the avatar's .skeleton file should the animation definition map to
• looped
  • Whether the animation should loop, true or false
• speedfactor
  • Adjusts animation speed. It's a multiplier, 1.0 is the original animation speed, and 2.0 would be twice as fast.
• usevelocity
  • Tells to adjust the animation speed based on avatar's movement velocity, true or false. Typically set true for walk/run animations, and false for others.
• fadein
  • Animation blend-in time in seconds, when starting the animation
• fadeout
  • Animation blend-out time in seconds, when stopping the animation

Note that when you change the .xml description file, you need to re-select the mesh in Avatar Generator (thus resetting the avatar) and re-export to Avatar Storage to see the changes.

Custom animations

Completely custom animations, referred to by their "ogrename" only and not by any pre-existing UUID, can also be used for gestures and server script triggered animations. Because they are referred to by name, they don't necessarily need an animation definition at all.

However, if adjusting fadein/fadeout or other parameters for them is desired, an animation definition should exist for them too. In this case, they should have a non-empty "fake" UUID defined for them, so that the animation definition as a whole is valid. This "fake" UUID does not need to be properly formatted, only to exist and be non-empty.

Morph modifiers

Morph modifiers tell what vertex morphing parameters exist for the current avatar mesh and to what degree they are applied. Normally, morph modifiers don't need to be defined in the avatar description xml file, but rather the Avatar Generator finds out them automatically when choosing the mesh. They can however be seen in the per-account exported avatar xml file (gets stored into the Avatar Storage, as well as stored locally in the realXtend viewer per-account settings directory)

Morph modifiers are identified by the xml tag "morph_modifier". The parameters are the following:

• name
  • Identifies the morph modifier. Normally this is the name of the morph target, with "Morph_" stripped away from the beginning, the same way as RexMeshTool displays it.
• internal_name
  • The full name of the morph target.
• influence
  • How much of the morph is blended in, between 0.0 and 1.0.

Skeletal modifiers

Skeletar modifiers can translate, rotate and scale the bones of the avatar. Normally these are generated using the Advanced controls of the Avatar Generator, but can also be pre-defined, like the posture controls for Jack and Kate. They work by having a start and end position defined for each of translation, rotation, and scaling, and then the "position" of the skeletal modifier can be modified between 0.0 (fully at start) and 1.0 (fully at end), like for morphs.

Skeletal modifiers are identified by the xml tag "dynamic_animation". The parameters and subelements are the following:

• name
  • Identifies the skeletal modifier.
• base_animations
  • This subelement needs to exist, however it can be empty, and is normally not needed.
• bones
  • Inside this the actual bones of the skeletal modifier will be listed, as individual "bone" elements.

The parameters and subelements of the "bone" element are following:

• name
  • Which bone will be affected
• translation
  • How the bone will translate. Contains "start" and "end" 3-dimensional vector positions. Set start and end both to 0 0 0 to not translate. Optionally, a "mode" parameter can be either "absolute" or "relative", meaning whether the positions are absolute or offsets to the bone's original position. Absolute mode is default.
• rotation
  • How the bone will rotate. Contains "start" and "end" euler angles. Set start and end both to 0 0 0 to not rotate. Optionally, a "mode" parameter can be either "absolute", "relative", or "cumulative". Absolute mode sets absolute orientation, relative rotates relative to original orientation. Cumulative mode can be used when several different skeletal modifiers affect the same bone: it will "continue" from the previous rotation.
• scale
  • How the bone will scale. Contains "start" and "end" 3-dimensional vector scaling values. Set start and end both to 1 1 1 to not scale.

Skeletal modifiers' position is specified with another xml element, with the tag "dynamic_animation_parameter". The parameters are following:

• name
  • Which skeletal modifier is referenced
• position
  • Position between 0.0 and 1.0

Master modifiers

These can control both morph and skeletal modifiers, and show up on the Avater Generator's Appearance panel, grouped into categories.

Master modifiers are identified by the xml tag "master_modifier". The parameters and subelements are following:

• name
  • Identifies the master modifier. This is also the name to display on the UI
• category
  • Into which appearance panel category will this modifier go to. Categories can be freely defined, for example Jack has Body & Posture categories.
• position
  • Initial position, between 0.0 and 1.0
• target_modifier
  • Subelement that identifies the modifier that will be driven by this control

"target_modifier" parameters and subelements are following:

• type
  • Either morph (for morphs) or dynamic_animation (for skeletal modifiers)
• name
  • Identifies the morph or skeletal modifier to be affected.
• mode
  • How the resulting modifier position will be calculated. This is important if several master modifiers affect the same modifier. Can be "cumulative" or "average".
• position_mapping
  • Optional subelements that define the interpolation graph and mapping of master modifier positions to modifier positions. For example, the modifier's position can be made to go in reverse (from 1 to 0) as the master modifier goes from 0 to 1, if so desired. Identity mapping from 0 to 1 is default if these are missing or incomplete. Each position_mapping element has "master" and "target" parameters that define the mapping points.

Properties

In addition to the elements above, the avatar description can contain properties, which are key-value pairs. Various extended features are controlled through them.

A property element is identified by the xml tag "property". The parameters are the following:

• name
  • Name of the property
• value
  • This is just a string value: actual meaning depends on the feature using the property.

Base mesh

The property "basemesh" identifies a mesh name, whose attachments will be used for the avatar in the Avatar Generator, in addition to its own attachments. For example, if a customized Jack.mesh is stored with another name, then it is useful to be still able to select the attachments used with Jack.mesh, and this is achieved by setting "basemesh" to value "Jack.mesh"

Avatar ground offset automatic setting

This function will try to ensure avatar's proper position in relation to the ground even when the avatar's bones are scaled (height setting), and requires three properties. "rootbone" to define the avatar skeleton's hierarchy root, "basebone" to select the bone which should be adjusted to align with the ground, and "baseoffset", which is a 3-dimensional vector offset to further finetune the offset.

Turning animation system

This is a client-side animation extension for realXtend avatars, which make possible for them to execute turning animations when turning around their vertical axis. It is independent of the animation definitions; the animations are only specified by name. However, if definitions exist for those animations, then parameters like fade-in and fade-out can be adjusted.

The properties used by this system are the following:

• turnaniminterval
  • Integration interval for turn animation decision, default 0.1 seconds
• turnanimthreshold
  • Minimum turn angle (in degrees) during integration interval required to trigger turn animation at minimum weight
• turnanimthresholdmax
  • Turn angle (in degrees) during integration interval that will give maximum weight to turn animation
• turnanimweightmin
  • Turn animation minimum height
• turnanimweightmax
  • Turn animation maximum weight, should not be over 1.0
• turnanimretrigger
  • Replay turn animation again and again when doing a continuous turn (boolean value), default false
• turnaniml
  • Animation name for turning left
• turnanimr
  • Animation name for turning right

Parametrized head turning system

By default, realXtend avatars use the hardcoded Bip01_Head, Bip01_Spine2 and Bip01_Spine1 bones for turning the avatar's body towards the view direction. However, these bones and their rotation axes can also be chosen at will.

The properties used by this system are the following:

• headbone
  • Bone in avatar skeleton to use for head turning
• neckbone
  • Bone in ogre skeleton to use for neck turning along with the head
• torsobone
  • Bone in avatar skeleton to use for torso turning along with the head
• headboneaxis
  • Adjustment for head bone rotation axis (3 euler degree values), optional
• neckboneaxis
  • Adjustment for neck bone rotation axis (3 euler degree values), optional
• torsoboneaxis
  • Adjustment for torso bone rotation axis (3 euler degree values), optional