Introduction

Avatar appearance is a particularly complex issue in current OpenSimulator since it involves a complex interaction between a user's viewer (where the texture is actually created) and the simulator (which needs to send appearance information to the viewer, receive the baked textures and distribute those to other viewers). Moreover, the exact steps of this interaction vary depending on whether the user is freshly logging in or region crossing/teleporting to another region on the same or a different simulator.

This document currently describes only the classic viewer-side texture baking. Server-side baking would do most if not all of these steps (especially the baking itself) in OpenSimulator instead. However, this is not yet implemented by OpenSimulator.

Steps

Establishing avatar appearance on login

Making an avatar appearance available in a simulator on login currently involves a large number of steps.

1. On login, the viewer asks the simulator what body parts and clothing it is wearing (AgentWearablesRequest UDP packet)
2. The simulator replies (AgentWearablesUpdate UDP packet).
3. The viewer confirms some appearance information to the server (AgentSetAppearance UDP packets). This includes visual parameters (nose length, etc.).
4. The viewer asks the simulator if its appearance is already cached (AgentCachedTexture UDP packet).
5. The simulator currently always responds that no data is cached (AgentCachedTextureResponse UDP packet).
6. The viewer sends further appearance information the server detailing the baked texture UUIDs it is about to upload (AgentSetAppearance UDP packets).
7. The viewer creates the appearance textures from the wearables (bakes them).
8. The viewer uploads these new baked textures to the simulator via the UploadBakedTexture HTTP capability.
9. The simulator stores this asset data in the simulator cache but does not send it to the asset service.
10. The simulator tells other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures uploaded for that avatar (AvatarAppearance UDP packets).
11. These other viewers then request the baked textures for these UUIDs.
12. When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.

As you can imagine there are many points at which this process can go wrong on, in the simulator, the sending viewer, the receiving viewer and at the network in between. If it does go wrong, you will often end up with a gas cloud instead of an avatar. The text below lists the various ways in which avatar appearance can go wrong, diagnosis commands and some suggestions for trying to fix the situation.

NOTE: The PersistBakeTextures flag in the Appearance section of the ini file allows you to persist baked textures among simulators and over login sessions. On establishment of a scene presence (through login or teleport) the simulator checks the asset service for copies of the baked textures and sends that information to the viewer. On login, this means that textures are not rebaked. While this behavior can lead to a large number of baked textures in the asset service, the only time textures will be re-baked is when 1) the user explicit requests it, 2) the set of wearables changes, or 3) the connection to the asset service is broken. There are some timing issues that come into play as well, though these will simply trigger an unnecessary rebake.

Establishing avatar appearance on teleport/region cross to another region on the same simulator

In this case, the baked textures are already in the simulator's asset cache. Hence, the steps are

1. The simulator tells both the uploading viewer and the other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures it already has for that avatar.
2. These other viewers then request the baked textures for these UUIDs if they don't already have them cached.
3. When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.

Establishing avatar appearance on region cross to another region on a different simulator

Todo: Need to fill out this section. This should be the same as for teleport, but in current git master (as of 2012-02-21) there may be an issue where the avatar does not send AgentSetAppearance on entering the new region, which means that the rebake request is never triggered.

Establishing avatar appearance on teleport to another region on a different simulator

1. On completing the teleport, the viewer sends an visual parameters and the UUIDs of the baked textures it previously uploaded to the server (via the AgentSetAppearance UDP packet).
2. Because these textures are not in the asset service (see earlier), OpenSimulator sends a rebake request for each texture (RebakeAvatarTextures UDP packet).
3. The simulator tells other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures uploaded for that avatar (AvatarAppearance UDP packets).
4. These other viewers then request the baked textures for these UUIDs.
5. When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.

Useful commands

These commands are in OpenSimulator 0.7.4 and later and some will be in 0.7.3.1 and 0.7.3.

appearance show

Usage

appearance show [<first-name> <last-name>]

e.g.

appearance show Lord Lucan

This will show the asset UUID for each baked texture uploaded by the viewer for that user. For instance, a properly baked user may have something like

(test one)# appearance show Lord Lucan
For Lord Lucan in test one
Bake Type  UUID
Head       fd783d4a-b1d2-4bdc-89c7-88578b429ccc (uploaded)
UpperBody  d147b1f5-b99d-49d4-8492-6cd4c7da905e (uploaded)
LowerBody  e8aae819-e04b-4894-983a-15bd2d354b71 (uploaded)
Eyes       ae8fe60d-9d20-440d-989a-869d2ee1ed3d (uploaded)
Skirt      not set
Hair       4e354649-f880-4204-987a-8d744f531469 (uploaded)
Lord Lucan baked appearance texture is OK

The textures may be listed as (not found) if they have been uploaded by the viewer but can't be found in the asset cache. Or they may be listed as (not set) if the viewer has never uploaded this data.

If no name is given then summary data for all users is displayed.

appearance send

Usage

appearance send [<first-name> <last-name>]

e.g.

appearance send Lord Lucan

Send appearance baked texture IDs to other avatars in the scene. In theory, this should trigger other avatars to request those textures if they need them. This will have no effect if the original viewer never uploaded the texture IDs in the first place (i.e. if avatars are appearing as clouds). If avatars are grey instead, then this command may help. There is also a ResendAppearanceUpdates config which can periodically resend this data. We will discuss this later on.

If no name is given then all avatars resend their appearance texture UUIDs to all other avatars.

appearance rebake

Usage

appearance rebake <first-name> <last-name>

e.g.

appearance rebake Lord Lucan

Now, this sounds like it should be an enormously useful command. Unfortunately, it will only have any effect if the viewer has already successfully uploaded some baked texture data, even if that turned out to be corrupt. The viewer will very probably ignore any requests to rebake textures if it has not managed to perform an initial successful bake.

j2k decode

Usage

j2k decode <id>

e.g.

j2k decode ae8fe60d-9d20-440d-989a-869d2ee1ed3d

Attempt a JPEG2000 decode of the given asset. All baked textures are JPEG2000 files, so this can be useful to assess whether a given upload is corrupt or not. If the decode succeeds then it will tell you how many the number of layers and components in the JPEG2000 texture.

dump asset

Usage

dump asset <id>

e.g.

dump asset ae8fe60d-9d20-440d-989a-869d2ee1ed3d

Dumps an asset to a file with the same name as the ID given. Can be useful for taking a closer look at textures in an external program (e.g. jiv on Linux) if they have been apparently successfully uploaded.

Problems and resolutions

General

• In all these situations, one can force the client to attempt a rebake using the ctrl+alt+r key combination. This is always worth trying.
• Remember, it's possible that the viewer has successfully baked but for some reason the upload of the textures to the simulator has failed, or the simulator has failed to redistribute them to other viewers. In this case, a viewer rebake may work.
• Another general tip is to try clearing the viewer cache and logging back in.
• One should also try a different viewer, either an old viewer such as Imprudence or a newer viewer such as Kokua or Firestorm. Different viewers may have different ways of baking textures or may have issues with bugs.
• If possible, one should also try a different simulator. Even if simulators are running exactly the same version of OpenSimulator, they can be running on a different software stack (e.g. Mono rather than Windows .NET) or different hardware. There may be differences in behaviour that stem from this.
• Try a quiet region. Regions with a lot of avatars and objects may be dealing with a lot of traffic that may cause appearance issues. To test this, you could go to a quieter region or ideally even a local installation of OpenSimulator.
• If you use the same name in the same viewer for multiple different grids, try using a different installation of the viewer instead. On some viewers, it may be possible to get confused between different inventories on different grids where the avatar has the same name. This is especially true in the case of viewers which were not explicitly written to access different grids (though historically the Linden viewer seems to have been okay in this respect).

This is probably only a small selection of issues. Please add more as you encounter them if you know of workarounds or fixes.

Cloudy avatars

The avatar does not have sufficient clothing or body-parts to bake textures

There is a minimum set of body parts and clothing a viewer requires to bake an appearance texture. There are the shape, hair, skin and eyes body parts, and the shirt and trousers clothing. Without these, the viewer will never attempt to bake a texture.

Solution

Make sure your avatar has this minimum set of body parts and clothing.

One of the assets for a bodypart/clothing is corrupt or missing

Sometimes the necessary data to perform the bake may be corrupt or missing.

Solution

Try switching to a different set of clothing and body parts (e.g. using the "replace outfit" option), or create the minimum set from scratch and see if wearing these helps.

The required clothing or bodypart inventory has not downloaded

Sometimes the required clothing or bodypart items for your appearance may not have downloaded, especially on a busy sim where you have a very large inventory and a viewer that aggressively requests inventory data.

Solutions

• Try a quieter region. As above, these have less traffic that may crowd out your appearance information (this is a diagnostic test rather than a long term solution).
• You may also want to try a viewer which is less aggressive about downloading all inventory information on login.
• Try turning off or on HTTP inventory if your viewer supports this option. Newer viewers (version 2, 3 and associated third party viewers) download inventory information using HTTP inventory capabilities rather than via UDP. In principle, this should result in a much better experience since large inventories do not crowd out other UDP messages (avatar movement, object updates, etc.). However, it may be worth changing this setting to see if it helps.

The viewer graphics code is failing to successfully bake textures

We've seen some graphics drivers fail to successfully bake textures. Sometimes this depends on where the baking is done (e.g. if the viewer is on a second screen).

Solution

Update your graphics drivers. Attempt a bake with a simple set of body parts/clothing and on your main screen.

An external OpenSimulator configuration system is not fully creating the necessary bodypart/clothing entries

This can be a problem with older configuration systems which are not viewer 2 aware, where it was enough to create inventory and avatar entries but item links in the "Current Outfit" folder are necessary. One would only expect to see this with initial avatar setup.

Solution

Try an avatar created using the "create user" ROBUST or simulator console command (if running in standalone mode). On OpenSimulator 0.7.4 this will by default create the minimum clothing and inventory links to display an avatar. On OpenSimulator 0.7.3.1 you will need to set CreateDefaultAvatarEntries = true in the [UserAccountService] section of Robust.ini or Robust.HG.ini (it is still set true by default on standalone).

Grey avatars

Sometimes avatars may appear grey rather than cloudy.

The message containing appearance information has been lost

For some reason, the packet containing appearance information is sometimes ignored by the viewer. The "appearance send" command above may help diagnose this.

Solution

Try setting ResendAppearanceUpdates = true setting in the [Appearance] section of OpenSim.ini. This will resend appearance data every 60 seconds. This will probably not help if avatars are clouds, since this usually signals a failure to upload the data in the first place.

In OpenSimulator 0.7.4 this setting is not on by default (it is not present in OpenSimulator 0.7.3.1 and before). In OpenSimulator 0.7.5 it will be on by default.