Avatar Editor Service

The Avatar Editor Service lets you access and make changes to a user's avatar within an experience. The Avatar Editor Service can also access a user's inventory and the Avatar Catalog to save outfits and purchase avatar items to the user's account.

We recommend implementing the Avatar Editor Service with an in-game avatar editor for a complete character customization experience. See the Simple Avatar Editor Demo reference place for an example of this feature.

To begin using the Avatar Editor Service, you must first request access to the user's inventory. After access is successfully granted, you can perform the following actions:

Requesting Access

To begin accessing a user's inventory, you need to prompt the user to allow access through AvatarEditorService:PromptAllowInventoryReadAccess(). You need to perform this request once per session.

Use the following code sample to initiate the access prompt and listen for the user response:


1local AvatarEditorService = game:GetService("AvatarEditorService")
2
3AvatarEditorService:PromptAllowInventoryReadAccess()
4
5local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()
6
7if result == Enum.AvatarPromptResult.Success then
8-- Access granted!
9end
10

The user receives the following prompt:

Once the user accepts the prompt, the AvatarEditorService can begin accessing the user's inventory.

Reading User Inventory

Once access is granted by the user, you can read their inventory with the AvatarEditorService:GetInventory() function, supplying an array of AvatarAssetTypes to filter by. This function returns an InventoryPages object containing the user owned items.

Use the following code sample to print a list of specific accessories in a user's inventory:


1local AvatarEditorService = game:GetService("AvatarEditorService")
2
3AvatarEditorService:PromptAllowInventoryReadAccess()
4
5local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()
6
7if result == Enum.AvatarPromptResult.Success then
8-- Access granted!
9local assetTypes = {
10Enum.AvatarAssetType.BackAccessory,
11Enum.AvatarAssetType.ShoulderAccessory,
12Enum.AvatarAssetType.WaistAccessory
13}
14local pagesObject = AvatarEditorService:GetInventory(assetTypes)
15local currentPage = pagesObject:GetCurrentPage()
16for i = 1, #currentPage do
17local item = currentPage[i]
18print(item)
19end
20end
21

Searching Avatar Catalog

AvatarEditorService includes functions and events which let you search the Roblox catalog. To search, supply your query with a CatalogSearchParams object that includes one or more of the following properties:

Property Description
AssetTypes An array of AvatarAssetType such as Enum.AvatarAssetType.BackAccessory.
BundleTypes An array of BundleType such as Enum.BundleType.BodyParts.
CategoryFilter A CatalogCategoryFilter which describes the various catalog categories like "Featured" or "Community Creations". By default this is set to CatalogCategoryFilter.None
MaxPrice An integer describing the maximum price to filter.
MinPrice An integer describing the minimum price to filter. By default, MinPrice is 0.
SearchKeyword A string used to match item descriptions in the catalog.
SortType A CatalogSortType that describes how the results are ordered. By default this is set to CatalogSortType.Relevance.

The following code sample constructs a CatalogSearchParams object for Back and Shoulder asset types and pass that through a AvatarEditorService:SearchCatalog() call:


1local AvatarEditorService = game:GetService("AvatarEditorService")
2
3local catalogSearchParams = CatalogSearchParams.new()
4local assetTypes = {
5Enum.AvatarAssetType.BackAccessory,
6Enum.AvatarAssetType.ShoulderAccessory
7}
8catalogSearchParams.AssetTypes = assetTypes
9
10local pagesObject =
11--This function returns a CatalogPages object containing the results.
12AvatarEditorService:SearchCatalog(catalogSearchParams)
13local currentPage = pagesObject:GetCurrentPage()
14for i = 1, #currentPage do
15local item = currentPage[i]
16print(item)
17end
18

Saving Avatars and Outfits

When used alongside an in-game avatar editor, AvatarEditorService can save and update avatar items and outfits to the Roblox platform. Users don't receive catalog items they don't own when saving an avatar or outfit.

Any HumanoidDescription can be saved to the user's current avatar with AvatarEditorService:PromptSaveAvatar(). This may include:

  • Pre-defined avatar configurations that you’ve built using existing catalog items.
  • Any configuration that the user has chosen through an in-game avatar editor.

Since AvatarEditorService:PromptSaveAvatar() does not yield, you can get the result by listening to the AvatarEditorService.PromptSaveAvatarCompleted event.

The following code will save a current HumanoidDescription using AvatarEditorService:PromptSaveAvatar() and checks for a successful AvatarEditorService.PromptSaveAvatarCompleted event:


1local AvatarEditorService = game:GetService("AvatarEditorService")
2local Players = game:GetService("Players")
3
4local player = Players.LocalPlayer
5local character = player.Character
6if not character or not character.Parent then
7character = player.CharacterAdded:Wait()
8end
9local humanoid = character:WaitForChild("Humanoid")
10
11local currentDescription = humanoid:GetAppliedDescription()
12AvatarEditorService:PromptSaveAvatar(currentDescription, humanoid.RigType)
13
14local result = AvatarEditorService.PromptSaveAvatarCompleted:Wait()
15if result == Enum.AvatarPromptResult.Success then
16-- Avatar saved!
17end
18

To save any HumanoidDescription as an outfit (without overwriting the user's current avatar), use AvatarEditorService:PromptCreateOutfit().

Once called, you can get the result of AvatarEditorService:PromptCreateOutfit() by listening to the AvatarEditorService.PromptCreateOutfitCompleted event.

The following code sample creates an outfit with AvatarEditorService:PromptCreateOutfit() and listens for a successful AvatarEditorService.PromptCreateOutfitCompleted event:


1local AvatarEditorService = game:GetService("AvatarEditorService")
2local Players = game:GetService("Players")
3
4local player = Players.LocalPlayer
5local character = player.Character
6if not character or not character.Parent then
7character = player.CharacterAdded:Wait()
8end
9local humanoid = character:WaitForChild("Humanoid")
10
11local currentDescription = humanoid:GetAppliedDescription()
12AvatarEditorService:PromptCreateOutfit(currentDescription, humanoid.RigType)
13
14local result = AvatarEditorService.PromptCreateOutfitCompleted:Wait()
15if result == Enum.AvatarPromptResult.Success then
16-- Outfit saved!
17end
18

Purchasing Items

When saving either an avatar or an outfit that uses catalog items, the user doesn't receive any items that they do not own. Before saving an avatar or outfit, check if the user owns the asset with MarketplaceService:PlayerOwnsAsset() and provide them with an option to purchase the item with MarketplaceService:PromptPurchase().

If you don't wish to implement item purchases, you can instead allow users to favorite non-owned items with AvatarEditorService:PromptSetFavorite().