CAV
Custom Avatars (or CAV) are customizable avatars, using sliders and options to create a completely unique avatar. They were added in version 4.2.
Principle
The Custom Avatar system is designed to give individual users the ability to create a distinct, modifiable, universal, and easily portable avatar than can be used in multiple worlds. Unlike other methods of providing avatars, the CAvatar system does not create geometry for users to download. Instead, it is a collection of numbers and settings that is used to generate the avatar on the client side.
The system uses one or more base models, which are then deformed (making them fatter, more muscular, etc) to produce the final geometry. The textures are created through layering and blending effects and are then applied to the finished model.
File Formats
To use custom avatars, you must have at least one avatar type. An avatar type is a model which begins with a single base model. Male and female would be different types. Likewise, if you created something very different from a base human (like a robot or a lizard) it would also be another type of avatar. Each type requires three types of assets: Templates, Models, and Textures.
Geometry Formats
Each avatar type begins with a base model. (These are currently created in DirectX ASCII format.) These base models are downloaded by the browser before any individual avatars are constructed. In-house, Activeworlds Inc. uses Blender to create these models.
Texture Formats
A number of base textures are required to generate the final model, including textures for skin, hair, and clothing. Because these textures must be layered together to build a final texture, PNG file format is used, which supports transparency.
Configurations and Template Definitions
Templates are the files which define what parts each avatar type uses, how they go together, what textures are used, and what deformation sliders will be available to the user. Templates are XML files.
CAV Structure
Overview
Activeworlds Custom Avatars (CAV's) is a system to allow world and universe owners to provide customizable clothing and body defenition options to their users, inside of any Activeworlds powered environment.
CAV's are constructed from an arbitrary number of parts, as defined by the world/universe administrator. Individual parts can be selected by the user, and further customized with textures (image maps) and/or colorizing, also defined by the administrator. These parts are combined to form an "avatar", the virtual character "worn" by the user, and representing him/her in the world.
The CAV system can be divided logically into two areas: Content, and the CAVtemplates.xml file.
CAV content includes all of the mesh data files (body parts), textures maps (coloring and some clothing), and animation sequences (avatar movements) used in the CAV system. The CAVtemplate file defines how all of these data are combined to form an avatar, and in which ways it can be modified by the end user.
Content
CAV content is stored on web accessible file paths similar to an Activeworlds world object paths. These locations must contain three folders with the following names and function:
avatars - This folder contains all of the mesh data for the body parts defined in the template file. (DirectX binary or ASCII 3D file format)
seqs - This folder contains all of the avatar animation sequenses defined in the template file. (Activeworlds .seq files)
textures - This folder contains all of the image maps referenced by the mesh models and manipulated by the template file. (jpg, png, bmp, and other image formats)
CAVtemplates.xml
The CAVtemplates.xml file is a text editable configuration file for the CAV system. This file defines which avatar parts and texture layers are availible to the CAV builder system, as well as all of the avatar catagories and options that the user can see. This file also defines which animations are associated with each avatar.
The CAVtemplates.xml file must be compressed in the .zip format and placed in the avatars folder on the chosen CAV object path
Details of the CAVtemplate file are covered in another section.
Setup
CAV's can be defined at both the universe and world level. Universal CAV's can be worn in every world that a user visits, as long as that world is set to allow Universal CAV's. World level CAV's are defined seperately for each world in the universe and are unique to each world in the universe.
When a universe CAV is defined in the current universe, the "Custom Avatar" option will appear in the Avatar menu in the browser menu bar. If a World CAV is defined for the current world, then the "Custom World Avatar" option also apears in the same menu. Both options will be availible if Both the universe and the current world have CAV's enabled.
Universe CAVs
Universe CAV's are automatically available to Citizen level users if a properly configured CAVtemplate.xml file exists in the avatars folder of the Universe Object Path. This path, along with other CAV options are defined in the Universe Attributes menu found under Options>Universe>Options in the browser menu bar.
CAV related items in the Universe Attributes menu: Allow tourist CAV - Enabling this option allows Tourist level users to wear Custom Avatars. Allow bots CAV - Enabling this option allows bots (programs that log into the browser) to be physically represented by a users current CAV.
Under the Object Path subheading:
Uni avatar OP - This field contains the URL of the location which contains the "avatars" content folder. This may be the same location as the "Texture and seq OP". Texture and seq OP - This field contains the URL of the location which contains both the "textures" and "seqs" CAV content folders. This may be the same location as the "Uni Avatar OP". Object Refresh - Defines how long in seconds after which the browser client (end user) will be forced to redownload, or refresh its content. This should generally be set to the default maximum of 10080, unless a special need demands otherwise. Object Password - This field must contain the password used by the compressed (zip) mesh files in the avatars folder, if any is used. Mesh data files need not be password protected.
World CAVs
World CAVs must be enabled in individual worlds via the "World Features" menu found under Options>World>Features in the browser's menu bar, using the following options under the "Custom World Avatar" submenu:
World CAV Citizen - Enables Citizen level users to wear the World CAV's of the current world.
World CAV Tourists - Enables Tourist level users to wear the World CAV's of the current world.
World CAV Bots - Enables Bot users to wear the World CAV's of the current world.
Other options include:
Uni CAV Citizen - Enables Citizen level users to wear a Universe CAV in the current world.
Uni CAV Tourist - Enables Tourist level users to wear a Universe CAV in the current world.
Uni CAV Bots - Enables Bot users to wear a Universe CAV in the current world.
CAV Object Path - This field contains the URL of the location where the current world's CAV content folders are stored. Unlike the universe object path's, all of the folders must be stored in the same location.
CAV Object Password and CAV Object refresh are the same as the Universe equivilents.
The CAV Builder
Once the CAVtemplate file is defined and all of the CAV content exists in the correct locations, the CAV itself can be built by the user useing the browser's CAV window. This can be accessed by clicking the T-shirt icon on the browser toolbar or by pressing "Alt-F6"
This calls the Custom Avatar build screen for the world or universe, depending on which the user is currently wearing. The following hierarchial catagories exist, with selectable entries according to the definitions in the CAVtemplate.xml file:
Avatar Catagories
Type - This is the broadest catagory of avatar, and is intented to be used for Avatars with wildy different structure that generally will not share any body parts. For example; Human, Robot, Alien, Animal, and Dragon, would all be of a different "Type". The "Type" catagory is defined in the CAVtemplates.xml as "Race"
Gender - This is the a sub-catagory of "Type", and would normally contain male and female versions of this type of avatar.
The "Gender" catagory is also defined in the CAVtemplates.xml as "Gender"
Avatar Options - This is a sub-catagory of Gender and can be used to create unique or distinct option sets for each Type>Gender avatar. There may be only one option set with all avatar option availible, or ths catagory could be devided into distinct sets. For example, the avatar Human>Male could have an avatar option set such as "Business" or "Casual" or "Medieval" or "Sci-fi" to create distinct styles sets. Any avatar option that uses the same basic model, but requres a unique option set belongs in this catagory.
The "Avatar Options" catagory is defined in the CAVtemplates.xml as "Avatar"
Template defined Options
The following option sub-catagories are all based on definitions within the CAVtemplates.xml file:
Base Colors - This sub-catagory shows color and opacity selectors from all non-selectable texture layers defined in the CAVtemplates.xml. Shape and Accossories - This sub-catagory shows all geometry (mesh) catagories and parts as defined in the CAVtemplates.xml file. Style and Color - This sub-catagory contains all selectable texture layers along with associated color and opacity slider, as defined in the CAVtemplates.xml file.
Other Options
This CAV builder contains options to Load and Save custom avatar settings as well as to randomly select colors and modifier settings. These options exist in the browser regardless of the contents of the CAVtemplates.xml file.
CAVtemplate file Structure
Header
The template file always begins with a header defining the version number of the CAVtemplates configuration file.
Example:
<?xml version="1.0"?> <!-- CAVtemplate version# - keep this around --> <CAVtemplate version="1">
NOTE - Any line which begins with "<!" is a comment header and does not affect the function of the CAV system, but is used to help navigate the file in an XML veiwer.
Hierarchy
The CAVtemplates.xml file defines individual avatar option sets within the following hierarchial structure:
Race»Gender»Avatar
Avatar must be defined inside of a Gender which must be defined inside of a Race. Individual avatar definisions, including all its parts, textures and sequences are always defined at the "Avatar" level. The higher levels are simply used to provide structure to the CAV Builder window in the browser.
Example:
<!-- Comment heading telling me that human avatars go here--> <race name="Human"> <gender name="Female"> <avatar name="none"> **AVATAR DEFINITIONS GO HERE** </avatar> </gender>
<gender name="Male"> <avatar name="none"> **AVATAR DEFINITIONS GO HERE** </avatar> </gender> </race>
Notice that a </> type definition must occur at the end of each catagory type, so <gender> is ended by </gender> and so forth. All avatars must be inside of a gender, and all genders must be inside of a race.
The template file finishes with the followind footer:
<!-- End of all cav templates in the list --> </CAVtemplate>
Again, the comment is for reference only.
3.1 Avatar Definitions
Each avatar has three basic definitions which control how it may be built:
Geometry - Avatar "parts". These are the 3D models that the avatar is constructed out of. Texture Layers - The "paint" that define the look of the avatar pieces. Soime of these can be selected and some are forced (e.g. the skin tone) Sequences -
Definitions need not be defined in this order. For example, sequences may be defined before textures or any other order.
Geometry
Avatars can be constructed out of an arbitrary number of parts, as defined with the <bodypart> template entry. The user will be presented with a list of selectable geometries (parts) for each catagory that is defined. Only one geometry can be selected for each catagory, so if two parts are intended to be worn at the same time, then the parts need to be defined in two seperate catagories. Geometry is defined with the definition.
bodypart definition:
The <bodypart> definition creates a new geometry category, with a list of selectable geometries that the user can choose from. Individual geometries are defined with <geometry>, inside the curent <bodypart> definition.
Options:
name="MenuNameHere" - The name option defines the name of the current bodypart list as it will apear to the user in the CAV builder window in the browser. This should be a descriptive name so that the user understands what part is being modified, such as "Upperbody", "Torso", or "Legs". Thi swill vary depending on how the avatar parts are constructed.
force="yes/no" - Must be "yes" or "no". If yes, then this geometry part MUST be worn by the CAV. If this is "no" then this part may remain unselected. This option is ideal for making sure that critical body parts are selected, for instance; If the user's head was not forced to be selected, that person could build a headless avatar. If a bodypart is forced, then the first part in the list will be the default.
Geometry definition:
The <geometry> definition references individual parts that a user is allowed to select from in the current bodypart list.
Options:
name="PartNameHere" - The name option defines the name of the part as it will apear to the user in the dropdown list for the current part type. This should generally be a descriptive name like "Red Baseball Cap" so that the user knows what he is selecting.
file="FileName.x" - The file option defines the actual filename of the bodypart that is used by the current geometry definition. The CAV builder currently must use Directx .x files, in binary or ASCII format.
Example:
<bodypart name="Head" force="yes"> <geometry name="Head1" file="part_head1.x"/> <geometry name="Head2" file="part_head2.x"/> </bodypart>
<bodypart name="Body" force="yes"> <geometry name="Body1" file="part_body1.x"/> <geometry name="Body2" file="part_body2.x"/> </bodypart>
<bodypart name="Hat" force="no"> <geometry name="Hat1" file="part_Hat1.x"/> <geometry name="Hat2" file="part_Hat2.x"/> </bodypart>
Notice that the head and body are forced, but the hat is not. This CAV can be built with no hat, but not without a head. Since head and body are forced catagories, head1 and body1 will be worn by default, since the user cannot deselect these parts.
Texture Layers
By default all geometry will use the texture(s) that are called in the file itself, just as any other object in the Activeworlds environment. Thus it is possible to have no texture definitions in the template file at all. However, in order to add layers to a texture, or to modify its color or opacity, then a texture definition must be added to the template file eith the definition.
Texturelayer definition:
The <texturelayer> definition will add a new modifyable texture stack to the CAV. This stack will replace an existing texture that is already called by a geometry file with the results of the current stack. The stack behaves differently depending on the options applied to the <texturelayer> definition. Individual layers in the stack are defined with the <texture> definition.
<texturelayer> options:
name="LayerName" - tex="ReplaceString" - The tex option defines the name of the geometry texture to be replaced by the currrent stack. This will replace any texture that contains the enclosed character string anywhere in the filename. Therefore a bodypart that calls the texture myfacefile.jpg will be replaced by the results of a stack which defines tex as either "my", "face", or "myfacefile".
Be aware that the results of the current stack will replace every file which conatains the defined string, therefore care must be taken to be specific enough to cover all of the texures that are intended to be replaced and no others.
sel="yes/no" - The sel option defines wether the current stack is selectable by the user or not, and must be either "yes" or "no". The sel option also drastically changes the behavior of the stack based on wether "yes" or "no" is defined. "Yes" is the default and if sel is not defined then the layer is assumed to be selectable.
If "no" is defined, then the current stack will be compiled into one resulting image which will replace the image defined by the "tex" option. All of the color modifier options defined in a non-selectable texture stack are presented to the user in the "Base Color" sub-heading of the CAV builder window. This option is ideal to define a base textures that can be "stacked upon" by other texture layers. For example a base skin texture for the body can be defined which allows colorization and modification and which will allow a later selectable stack to apply clothing layers on top of it.
If "yes" is defined, then the current stack behaves as a list of texture layers from which a user may choose one to be applied on top of a previously defined non-selectable layer. Only one texture in a selectable stack may be selected at a time, so textures that should exist together should be in seperate selectable texture stacks. For instance, on a normal avatar, there should be a seperate selectable stack for "Pants", "Shirts", etc, so that each can be applied to the base layer in turn.
stack="number" - The stack option defines in which order each stack is applied in and is only used by selectable stacks where sel="yes". This must be a number value and be applied in sequencial order in the template file.
<texture> definition:
The <texture> definition adds a new modifyable texture layer to the current stack, and is defined from within the current <texlayer>.
<texture> options:
file="ImageFilename.png" - The file option defines the file name of the image used in this texture.
name="LayerName" - The name option defines the name that is seen by the user in the CAV builder window for this texture.
opt="ColorOption" - The opt option defines what colorization and modification options are availible to the user for the current texture. This is not a required option and may be left out. The following options are availible:
"skin_color" - Skin_color is a special color option that forces the user to select a color from a predetermined color palette, as defined by an image file located in the browser client folder Default>Textures this file must be called skinmap.bmp. It must be in the .bmp format. This color picker is presented to the user near the top of the CAV bulder window.
"color" - This option allows the user to select a color with an RGB color picker that is presented to the user under the current texturelayer dropdown menu in the CAV builder window.
"alpha_color" - This option is the same as "color", but also allows the user to set the alpha, or transparency of the current texture with a slider, shown next to the color picker box.
In all cases the selected color option is multiplied by the current texture. Therefore, greyscale textures work best with a color options, as textures which already have colors in them tend to result in unexpected colors.
Texure layer example:
<texlayer tex="face" sel="no"> <texture file="face_greyscale.png" opt="skin_color"/> <texture file="face_lips.png" name="Lips" opt="alpha_color"/> <texture file="avf_face_iris.png" name="EyeColor" opt="color"/> <texture file="avf_face_eyeliner.png" name="Eyeliner" opt="alpha_color"/> </texlayer>
<texlayer tex="body" sel="no"> <texture file="body_greeyscale.png" opt="skin_color"/> <texture file="body_highlight.png"/> <texture file="body_nails.png" name="Fingernails" opt="color"/> </texlayer>
<texlayer name="Pants" tex="body" stack="1"> <texture name="Jeans" file="body_jeans.png"/> <texture name="Shorts" file="body_shorts.png" opt="color"/> </texlayer>
<texlayer name="Shirt layer 1" tex="body" stack="2"> <texture name="Blouse" file="shirt_blouse.png" opt="alpha_color"/> <texture name="Sweater" file="shirt_sweater.png"/> <texture name="TankTop" file="shirt_tank.png" opt="alpha_color"/> </texlayer>
<texlayer name="Shirt layer 2" tex="body" stack="3"> <texture name="Blouse" file="shirt_blouse.png" opt="alpha_color"/> <texture name="Sweater" file="shirt_sweater.png"/> <texture name="TankTop" file="shirt_tank.png" opt="alpha_color"/> </texlayer>
Notice that the first two stacks are non-selectable, since sel is set to "no". These layers will be combined together to form one base texture which can be built upon. The second two stacks are selectable, since they do not have the sel="no" option defined ("yes" is default). The "pants" and "shirts" are in seperate layer stacks so they can both be worn together. Only one from each list may be applied. Also, notice that the same files are called in both Shirt layers, so that they can be layered over each other.
Sequences
Avatar animation sequences are define under the <seqs> section of the template file with the following sub-headings: There are two types of animation sequences or "gestuires"; implicit and explicit, as well as a section of options. Each sunheading must be written in brackets.
[implicit] - Implicit animations are invoked when the user performs certain actions, or certain conditions are present. Implicit animations are defined as follows:
ImplicitAnimation=animation_filename
The following implicit animations exist:
walk - Invoked when the user walks run - Invoked when the user runs wait - Invoked when the user stops moving endwait - Invoked at the end of the wait animation swim - Invoked when the user moves in water float - Invoked when the user is motionless in water fly - Invoked when the user moves in the air hover - Invoked when the user is motionless in the air jump - Invoked when the user presses the jump key fall - Invoked when the user falls idle - Invoked when the user does not press a key for an extended time
[explicit] - Explicit gestures are invoked by the user, and are selected from the "Gestures" toolbar in the browser. Explicit gestures are defined as follows:
gesture1=DisplayName, FileName, where the number after "gesture" is sequencially incremented for each new gesture. DisplayName is the name the user want the gesture to apear as in the gestures toolbar, and FileName is the name of the animation file in the designated Seqs content folder.
A special gesture definition can be used to gather the gestures into groups, as follows:
gesture1=group, GroupName, where GroupName is the name the user wants this group to be seen as in the gestures toolbar. All numbered gestures after a group is defined are included in that group, until a new group is defined.
[options] The following optiones are defined as follows:
option=number, where number is either 1 (on) or 0 (off)
autowalk - Allows the avatar walk sequence to be sped up or slowed down automatically with the speed of the avatar autolook - Turns the avatar's head and upper body to turn when the users camera turns, simulating the avatar "looking around"
Animation definition example:
<seqs> [options] autowalk=1 autolook=1
[implicit] walk=explain run=run_filename wait=explain endwait=explain swim=swim_filename float=float_filename fly=fly_filename hover=hover_filename jump=jump_filename fall=fall_filename idle=idle_filename
[explicit] gesture1=group,Emotions gesture2=Cry,cry_animation gesture3=Happy,happy_animation gesture4=group,Dances gesture5=ChickenDance,chkdance_animation gesture6=Salsa,salsa_animation </seqs>
Setting up CAVs through the SDK
(Please complete this - meant to be an example or conceptional example)
Read the xml content from an .awcav preset; something like:
file_read (filename, &data &len);
Create the compressed data buffer and set the max len Compressed data must be always shorter in size, so len is long enough
zip_buf = new UCHAR[len]; zip_len = len;
Compress the data
aw_zip (zip_buf, &zip_len, data, len);
Set all attributes necessary
aw_int_set (AW_CAV_CITIZEN, citizen); aw_int_set (AW_CAV_SESSION, session); aw_data_set (AW_CAV_DEFINITION, (const char*)zip_buf, zip_len);
In case it is a universe CAV, the bot must be uni-admin to change other's uni-CAVs but always can change his own universe-CAV, using:
aw_cav_change ();
In case it is a world CAV, the bot must be CT to change other's world-CAVs but always can change his own world-CAV, using:
aw_world_cav_change ();
Once the preset is uploaded, set the avatar to CUSTOM_AVATAR (type = 65534) or to CUSTOM_WORLD_AVATAR (type = 65533) using either:
aw_state_change () for your own avatar
or
aw_avatar_set (session) for other's avatars.
To request a CAV definition from the universe, use:
aw_cav_request (citizen, session);
To request a CAV defintion from the world, use:
aw_world_cav_request (citizen, session);
Uni-Callbacks:
AW_CALLBACK_CAV
AW_CALLBACK_CAV_RESULT
World-Callbacks: AW_CALLBACK_WORLD_CAV_RESULT, AW_CALLBACK_WORLD_CAV,
Uni-Events: AW_EVENT_CAV_DEFINITION_CHANGE,
World-Events: AW_EVENT_WORLD_CAV_DEFINITION_CHANGE,