articles/roblox avatars|Avatars are a big part of players expressing themselves on Roblox. Using AvatarEditorService along with an in-game avatar editor, you can let players customize their character and take it everywhere they go.
We’ll be rolling this functionality out slowly to ensure the best experience for everyone. Fill out
this form if you’re interested in using it for your game for now!
Reading Player Inventory
AvatarEditorService has various functions and events for working with items already in a player’s inventory.
Allowing Access
To begin using inventory-related methods, you’ll need to prompt the player to allow access via AvatarEditorService/PromptAllowInventoryReadAccess|PromptAllowInventoryReadAccess().
local AvatarEditorService = game:GetService("AvatarEditorService")
AvatarEditorService:PromptAllowInventoryReadAccess()
The player’s response can then be tracked by waiting for the AvatarEditorService/PromptAllowInventoryReadAccessCompleted|PromptAllowInventoryReadAccessCompleted event:
local AvatarEditorService = game:GetService("AvatarEditorService")
AvatarEditorService:PromptAllowInventoryReadAccess()
local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()
if result == Enum.AvatarPromptResult.Success then
-- Access granted!
end
Currently, inventory access must be requested once per session, but in the future this permission may be saved per game.
Getting Inventory
Once access is granted by the player, you can read their inventory with the AvatarEditorService/GetInventory|GetInventory() function, supplying an array of enum/AvatarAssetType|AvatarAssetTypes to gather. This function returns an InventoryPages object containing the player’s owned items.
local AvatarEditorService = game:GetService("AvatarEditorService")
AvatarEditorService:PromptAllowInventoryReadAccess()
local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()
if result == Enum.AvatarPromptResult.Success then
-- Access granted!
local assetTypes = {
Enum.AvatarAssetType.BackAccessory,
Enum.AvatarAssetType.ShoulderAccessory,
Enum.AvatarAssetType.WaistAccessory
}
local pagesObject = AvatarEditorService:GetInventory(assetTypes)
local currentPage = pagesObject:GetCurrentPage()
for i = 1, #currentPage do
local item = currentPage[i]
print(item)
end
end
Searching the Catalog
AvatarEditorService includes functions and events which let you search the Roblox catalog. To begin, construct a datatype/CatalogSearchParams object and supply the desired properties:
local AvatarEditorService = game:GetService("AvatarEditorService")
local catalogSearchParams = CatalogSearchParams.new()
local assetTypes = {
Enum.AvatarAssetType.BackAccessory,
Enum.AvatarAssetType.ShoulderAccessory
}
catalogSearchParams.AssetTypes = assetTypes
| Property |
Type |
Default |
| AssetTypes |
array of Enum/AvatarAssetType |
|
| BundleTypes |
array of Enum/BundleType |
|
| CategoryFilter |
Enum/CatalogCategoryFilter |
Enum.CatalogCategoryFilter.None |
| MaxPrice |
integer |
|
| MinPrice |
integer |
0 |
| SearchKeyword |
string |
|
| SortType |
Enum/CatalogSortType |
Enum.CatalogSortType.Relevance |
With a valid datatype/CatalogSearchParams, call AvatarEditorService/SearchCatalog|SearchCatalog(). This function returns a CatalogPages object containing the results.
local AvatarEditorService = game:GetService("AvatarEditorService")
local catalogSearchParams = CatalogSearchParams.new()
local assetTypes = {
Enum.AvatarAssetType.BackAccessory,
Enum.AvatarAssetType.ShoulderAccessory
}
catalogSearchParams.AssetTypes = assetTypes
local pagesObject = AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for i = 1, #currentPage do
local item = currentPage[i]
print(item)
end
Saving Avatars and Outfits
When used alongside an in-game avatar editor, AvatarEditorService is ideal for saving avatars/outfits to the Roblox platform.
Saving as Avatar
Any HumanoidDescription can be saved to the player’s current avatar with AvatarEditorService/PromptSaveAvatar|PromptSaveAvatar(). This may include:
- Pre-defined avatar configurations that you’ve built using existing catalog items.
- Any configuration that the player has chosen through an in-game avatar editor.
local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character
if not character or not character.Parent then
character = player.CharacterAdded:Wait()
end
local humanoid = character:WaitForChild("Humanoid")
local currentDescription = humanoid:GetAppliedDescription()
AvatarEditorService:PromptSaveAvatar(currentDescription, humanoid.RigType)
AvatarEditorService/PromptSaveAvatar|PromptSaveAvatar() does not yield and you can get the result by listening to the AvatarEditorService/PromptSaveAvatarCompleted|PromptSaveAvatarCompleted event:
local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character
if not character or not character.Parent then
character = player.CharacterAdded:Wait()
end
local humanoid = character:WaitForChild("Humanoid")
local currentDescription = humanoid:GetAppliedDescription()
AvatarEditorService:PromptSaveAvatar(currentDescription, humanoid.RigType)
local result = AvatarEditorService.PromptSaveAvatarCompleted:Wait()
if result == Enum.AvatarPromptResult.Success then
-- Avatar saved!
end
Saving as Outfit
To save any HumanoidDescription as an outfit (without overwriting the player’s current avatar), use AvatarEditorService/PromptCreateOutfit|PromptCreateOutfit().
local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character
if not character or not character.Parent then
character = player.CharacterAdded:Wait()
end
local humanoid = character:WaitForChild("Humanoid")
local currentDescription = humanoid:GetAppliedDescription()
AvatarEditorService:PromptCreateOutfit(currentDescription, humanoid.RigType)
Once called, you can get the result of AvatarEditorService/PromptCreateOutfit|PromptCreateOutfit() by listening to the AvatarEditorService/PromptCreateOutfitCompleted|PromptCreateOutfitCompleted event:
local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character
if not character or not character.Parent then
character = player.CharacterAdded:Wait()
end
local humanoid = character:WaitForChild("Humanoid")
local currentDescription = humanoid:GetAppliedDescription()
AvatarEditorService:PromptCreateOutfit(currentDescription, humanoid.RigType)
local result = AvatarEditorService.PromptCreateOutfitCompleted:Wait()
if result == Enum.AvatarPromptResult.Success then
-- Outfit saved!
end
Handling Item Purchases
When saving either an avatar or an outfit that uses catalog items, the player will not receive any items that they do not own. Thus, before calling either AvatarEditorService/PromptSaveAvatar|PromptSaveAvatar() or AvatarEditorService/PromptCreateOutfit|PromptCreateOutfit(), the recommended workflow is:
- Determine if the player does not own any items they’re trying to save via
MarketplaceService/PlayerOwnsAsset|MarketplaceService:PlayerOwnsAsset().
- For non-owned items, give the player an option to purchase them using
MarketplaceService/PromptPurchase|MarketplaceService:PromptPurchase().
If you don't wish to implement item purchases, you can instead allow players to "favorite" non-owned items with AvatarEditorService/PromptSetFavorite|PromptSetFavorite(). However, you will not earn any Robux if the player decides to purchase those items outside of your game.
