Revision as of 13:17, 18 September 2012

Note: This document is a work-in-progress

Introduction

By default, when a new avatar is created in OpenSimulator they are clothed with a default clothing set consisting of hair, shape, eyes, skin, pants and shirt (this is also known as the "Ruth" avatar).

By making various ROBUST service calls and uploading the appropriate assets, one can also set clothing on an avatar without manually doing this through a viewer. It is also possible to achieve the same end through other means, such as direct database updates. However, this document will concentrate on the ROBUST service call approach. Using ROBUST service calls does not require the caller to have an extremely detailed knowledge of the OpenSimulator data structure, though a very large amount of knowledge about OpenSimulator in general is still required. The ROBUST service call approach is also less vulnerable to change as OpenSimulator evolves. One disadvantage is that it requires the appropriate ROBUST service instances to be running whereas direct database updates could be made when OpenSimulator is completely inactive.

This technique also currently applies only to the grid architecture of OpenSimulator, since the standalone mode cannot currently expose the necessary external service interfaces. In theory, there is some undocumented code in the RemoteAdmin facility that can be used to setup differently clothed avatars in standalone mode but the extent to which this is operational is not currently known.

Also, please note that this technique needs the user to be offline throughout. If the user is online then they can make updates to their clothing which conflict with updates made through the ROBUST service calls.

Steps

For now, we are going to assume

1. That we are clothing a new avatar, not changing the clothing of one that already exists.
2. The necessary assets are not yet in OpenSimulator's asset service.

Step 1: Upload the assets

Each clothing item needs an associated asset for its appearance and other parameters (e.g. length in the case of hair). As assets are immutable, they will be reused for every user (if a user were to change their hair length then a new asset just for them would be created). However, we are assuming that the original assets aren't yet in the asset service so we will need to upload them.

One way to do this is to directly POST the assets to the asset service, as described at AssetService#POST:.2Fassets. There are a number of ways to get the raw asset data (the part that actual describes the hair, pants, etc.) itself. One is to dump assets using the "dump asset" region console command. Another is to extract them from OpenSim Region Archives (OARs) or OpenSim Inventory Archives (IARs).

You will also need the textures referenced by the bodyparts/clothing. You can see these by directly reading the asset data files. Or alternatively you could upload everything saved from an OAR or IAR.

Step 2: Create the user

This can be done by any number of means, including via a manual "create user" command on the ROBUST service interface or via the ROBUST calls detailed in UserManipulation. You may want to set

[UserAccountService]
CreateDefaultAvatarEntries = false 

in Robust.ini if you don't want a new avatar to have the "Ruth" clothing. However, there is no harm if the avatar has these entries as well.

Step 3: Create the inventory items

For each user and each asset you will need to create an inventory item (e.g. an eyes inventory item for the eyes asset). You can do this by fetching the BodyParts (asset type 13) and Clothing Type (asset type 6) folders using the GETFOLDERFORTYPE operation in InventoryService and then uploading each item's metadata using the ADDITEM operation in InventoryService.

Each item will need the appropriate asset type (Clothing 6, BodyPart 16), the appropriate inventory type (InventoryType 18) and an extra Flags entry to signal the WearableType (Shape = 0, Skin = 1, Hair = 2, Eyes = 3, Shirt = 4, Pants = 5).

For instance, here is the POST requested use to create an eyes item using the asset we uploaded earlier.

AssetID=4bb6fa4d-1cd2-498a-a84c-95c1a0e74000&AssetType=13&Name=eyesAsset+2&Owner=efc1b932-20e3-4298-8824-0f891fe3dc59&ID=99999999-9999-9999-9999-999999999000&InvType=18&CreatorId=efc1b932-20e3-4298-8824-0f891fe3dc59&CreatorData=&Description=&BasePermissions=581639&CurrentPermissions=581632&NextPermissions=581639&EveryOnePermissions=0&GroupID=00000000-0000-0000-0000-000000000000&GroupOwned=False&GroupPermissions=0&SalePrice=0&SaleType=0&Flags=3&CreationDate=1348002962&Folder=40506578-704d-49bb-adbc-98b2c4719fb2&METHOD=ADDITEM

Step 4: Create inventory item links in the avatar's "Current Outfit" system folder

In version 1 viewers, we would want to set the worn clothing by changing the relevant entries in the Avatar service.

However, this technique will not work on LL viewer 2 and later where worn clothing is controlled by inventory links in the "Current Outfit" system folder. In fact, such viewers will override any existing settings in the Avatar service where they conflict with worn clothing inventory links.

Therefore, we will use the inventory link approach here. However, a full implementation would probably also set the matching Avatar service entries in order to cater for earlier viewers. This is TODO.

Step 4.1: Get the "Current Outfit" system folder

We can do this using InventoryService#GETFOLDERFORTYPE with the parameters

PRINCIPAL=efc1b932-20e3-4298-8824-0f891fe3dc59&TYPE=46&METHOD=GETFOLDERFORTYPE

where 46 is the current folder type.

Step 4.2: Delete existing item links as appropriate

Before we add our links, we want to remove any existing clothing links which would conflict with our links. We would fetch the items in the current outfit folder using InventoryService#GETFOLDERCONTENT and then delete them with InventoryService#DELETEITEMS

Step 4.3: Create inventory links

Inventory links are no different from ordinary inventory items except that

1. They have an asset type of 24 (link).
2. The asset IDs reference the item UUID that the link is pointing to rather than a normal asset.

Therefore, we can add them with ordinary InventoryService#ADDINVENTORYITEM calls such as

AssetID=99999999-9999-9999-9999-999999999000&AssetType=24&Name=eyesLink+2&Owner=efc1b932-20e3-4298-8824-0f891fe3dc59&ID=7851D28E-C980-001A-93CD-4F4C840F658C&InvType=18&CreatorId=efc1b932-20e3-4298-8824-0f891fe3dc59&CreatorData=&Description=&BasePermissions=581639&CurrentPermissions=581632&NextPermissions=581639&EveryOnePermissions=0&GroupID=00000000-0000-0000-0000-000000000000&GroupOwned=False&GroupPermissions=0&SalePrice=0&SaleType=0&Flags=0&CreationDate=1348000896&Folder=2893a6b8-dd5e-a040-855d-100896462e0c&METHOD=ADDITEM

For Folder this uses the ID retrieve in step 4.1.

Once you have done this for the 6 minimal appearance items (eyes, shape, skin, hair, pants, shirt), on login the avatar should be wearing the given clothing.