Introduction

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

1. On login, the viewer needs to told what body parts and clothing it is wearing.
2. The viewer then creates the appearance textures from this data (bakes them).
3. The viewer uploads the baked textures to the simulator via the UploadBakedTexture HTTP capability.
4. The simulator temporarily stores this asset data.
5. The simulator sends asset UUIDs to other viewers in the region.
6. If the viewer does not already have the baked texture asset, it requests it from the simulator via the GetTexture HTTP capability.
7. Other avatars appear with those baked textures.

As you can imagine there are many points at which this process can go wrong. 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.

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 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.

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.

If this works then you will need to update your configuration system.