Serviço de Edição de Avatar

O Serviço de Edição de Avatar permite que você acesse e faça alterações no avatar de um usuário dentro de um jogo. O Serviço de Edição de Avatar também pode acessar o inventário de um usuário e o Marketplace para salvar roupas e comprar itens para o avatar na conta do usuário.

Recomendamos implementar o Serviço de Edição de Avatar com um editor de avatar in-game para uma experiência de personalização de personagem completa. Veja o lugar de referência Demo Simples de Editor de Avatar para um exemplo dessa funcionalidade.

Para começar a usar o Serviço de Edição de Avatar, você deve primeiro solicitar acesso ao inventário do usuário. Após o acesso ser concedido com sucesso, você pode realizar as seguintes ações:

• Ler o inventário do usuário para obter uma lista de itens pertencentes ao usuário.
• Pesquisar no Marketplace, usando uma variedade de propriedades para filtrar e classificar.
• Equipar itens de avatar e salvar roupas para o avatar do usuário.
• Solicitar que o usuário compre um item do Marketplace.

Solicitar acesso

Para começar a acessar o inventário de um usuário, você precisa solicitar ao usuário que permita o acesso através de PromptAllowInventoryReadAccess(). Você deve fazer essa solicitação uma vez por sessão.

Use o seguinte exemplo de código para iniciar o prompt de acesso e escutar a resposta do usuário:

local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Acesso concedido!
end

O usuário recebe o seguinte prompt:

Uma vez que o usuário aceita o prompt, o AvatarEditorService pode começar a acessar o inventário do usuário.

Ler inventário do usuário

Uma vez que o acesso é concedido pelo usuário, você pode ler o inventário deles com a função GetInventory(), fornecendo um array de AvatarAssetTypes para filtrar. Esta função retorna um objeto InventoryPages contendo os itens pertencentes ao usuário.

Use o seguinte exemplo de código para imprimir uma lista de acessórios específicos no inventário de um usuário:

local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Acesso concedido!
  local assetTypes = {
    Enum.AvatarAssetType.BackAccessory,
    Enum.AvatarAssetType.ShoulderAccessory,
    Enum.AvatarAssetType.WaistAccessory
  }
  local pagesObject = AvatarEditorService:GetInventory(assetTypes)
  local currentPage = pagesObject:GetCurrentPage()
  for _, item in currentPage do
    print(item)
  end
end

Pesquisar no Marketplace

O AvatarEditorService inclui funções e eventos que permitem pesquisar no catálogo do Roblox. Para pesquisar, forneça sua consulta com um objeto CatalogSearchParams que inclui uma ou mais das seguintes propriedades:

O seguinte exemplo de código constrói um objeto CatalogSearchParams para tipos de ativos Costas e Ombro, e o passa através de uma chamada SearchCatalog():

local AvatarEditorService = game:GetService("AvatarEditorService")

local catalogSearchParams = CatalogSearchParams.new()
local assetTypes = {
  Enum.AvatarAssetType.BackAccessory,
  Enum.AvatarAssetType.ShoulderAccessory
}
catalogSearchParams.AssetTypes = assetTypes

local pagesObject =
--Esta função retorna um objeto CatalogPages contendo os resultados.
AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for _, item in currentPage do
  print(item)
end

Salvar avatares e roupas

Quando usado em conjunto com um editor de avatar in-game, o AvatarEditorService pode salvar e atualizar itens de avatar e roupas na plataforma Roblox. Os usuários não recebem itens do catálogo que não possuem ao salvar um avatar ou roupa.

Qualquer HumanoidDescription pode ser salva no avatar atual do usuário com PromptSaveAvatar(). Isso pode incluir:

• Configurações de avatar predefinidas que você criou usando itens do catálogo existentes.
• Qualquer configuração que o usuário escolheu através de um editor de avatar in-game.

Como AvatarEditorService:PromptSaveAvatar() não gera yield, você pode obter o resultado escutando o evento AvatarEditorService.PromptSaveAvatarCompleted.

O seguinte código salvará uma HumanoidDescription atual usando PromptSaveAvatar() e verificará um evento bem-sucedido de AvatarEditorService.PromptSaveAvatarCompleted:

local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
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 salvo!
end

Para salvar qualquer HumanoidDescription como uma roupa (sem sobrescrever o avatar atual do usuário), use AvatarEditorService:PromptCreateOutfit().

Uma vez chamado, você pode obter o resultado de AvatarEditorService:PromptCreateOutfit() escutando o evento AvatarEditorService.PromptCreateOutfitCompleted.

O seguinte exemplo de código cria uma roupa com AvatarEditorService:PromptCreateOutfit() e escuta por um evento bem-sucedido de AvatarEditorService.PromptCreateOutfitCompleted:

local AvatarEditorService = game:GetService("AvatarEditorService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
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
  -- Roupa salva!
end

Comprar itens

Ao salvar um avatar ou uma roupa que usa itens do catálogo, o usuário não recebe nenhum item que não possua. Antes de salvar um avatar ou roupa, verifique se o usuário possui o ativo com MarketplaceService:PlayerOwnsAsset() e forneça a ele uma opção para comprar o item com MarketplaceService:PromptPurchase().

Se você não desejar implementar compras de itens, pode permitir que os usuários marquem itens não possuídos como favoritos com AvatarEditorService:PromptSetFavorite().