Servizio Editor Avatar | Documentazione

Il Servizio Editor Avatar ti permette di accedere e apportare modifiche all'avatar di un utente all'interno di un gioco. Il Servizio Editor Avatar può anche accedere all'inventario di un utente e al Marketplace per salvare gli outfit e acquistare articoli per avatar sul conto dell'utente.

Ti consigliamo di implementare il Servizio Editor Avatar con un editor avatar nel gioco per un'esperienza di personalizzazione del personaggio completa. Vedi il riferimento Demo Semplice Editor Avatar per un esempio di questa funzionalità.

Per iniziare a utilizzare il Servizio Editor Avatar, devi prima richiedere accesso all'inventario dell'utente. Dopo che l'accesso è stato concesso con successo, puoi eseguire le seguenti azioni:

Leggere l'inventario dell'utente per ottenere un elenco di articoli posseduti dall'utente.
Cercare nel Marketplace, utilizzando una varietà di proprietà per filtrare e ordinare.
Equipaggiare articoli per avatar e salvare outfit per l'avatar dell'utente.
Chiedere all'utente di acquistare un articolo del Marketplace.

Richiedere accesso

Per iniziare ad accedere all'inventario di un utente, devi invitare l'utente a consentire l'accesso tramite PromptAllowInventoryReadAccess(). Devi eseguire questa richiesta una sola volta per sessione.

Usa il seguente campione di codice per iniziare il prompt d'accesso e ascoltare la risposta dell'utente:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Accesso concesso!
end

L'utente riceve il seguente prompt:

Una volta che l'utente accetta il prompt, AvatarEditorService può iniziare ad accedere all'inventario dell'utente.

Leggere l'inventario dell'utente

Una volta che l'accesso è stato concesso dall'utente, puoi leggere il suo inventario con la funzione GetInventory(), fornendo un array di AvatarAssetTypes da utilizzare come filtro. Questa funzione restituisce un oggetto InventoryPages contenente gli articoli posseduti dall'utente.

Usa il seguente campione di codice per stampare un elenco di accessori specifici nell'inventario di un utente:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Accesso concesso!
  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

Cercare nel Marketplace

AvatarEditorService include funzioni ed eventi che ti consentono di cercare nel catalogo di Roblox. Per cercare, fornire la tua query con un oggetto CatalogSearchParams che include una o più delle seguenti proprietà:

Proprietà	Descrizione
AssetTypes	Un array di Enum.AvatarAssetType, come Enum.AvatarAssetType.BackAccessory.
BundleTypes	Un array di Enum.BundleType, come Enum.BundleType.BodyParts.
CategoryFilter	Un Enum.CatalogCategoryFilter che descrive le varie categorie di catalogo come "In Evidenza" o "Creazioni della Community". Di default, questo è impostato su Enum.CatalogCategoryFilter.None
MaxPrice	Un intero che descrive il prezzo massimo per filtrare.
MinPrice	Un intero che descrive il prezzo minimo per filtrare. Di default, MinPrice è 0.
SearchKeyword	Una stringa da utilizzare nella ricerca contro le descrizioni degli articoli nel catalogo.
SortType	Un Enum.CatalogSortType che descrive come vengono ordinati i risultati. Di default, questo è impostato su Enum.CatalogSortType.Relevance.
IncludeOffSale	Un booleano che descrive se i risultati della ricerca includono articoli non in vendita. Di default, questo è impostato su false.
CreatorId	Un intero per specificare un creatore specifico. Puoi utilizzare sia un UserId che un GroupId.
CreatorName	Una stringa utilizzata per cercare articoli creati da un dato creatore. Puoi usare sia un Nome Utente che un Nome Gruppo.

Il seguente campione di codice costruisce un oggetto CatalogSearchParams per i tipi di asset Back e Shoulder, e lo passa attraverso una chiamata a SearchCatalog():


local AvatarEditorService = game:GetService("AvatarEditorService")

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

local pagesObject =
--Quest funzione restituisce un oggetto CatalogPages contenente i risultati.
AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for _, item in currentPage do
  print(item)
end

Salvare avatar e outfit

Quando utilizzato insieme a un editor avatar nel gioco, AvatarEditorService può salvare e aggiornare articoli per avatar e outfit sulla piattaforma Roblox. Gli utenti non ricevono articoli del catalogo che non possiedono quando salvano un avatar o un outfit.

Qualsiasi HumanoidDescription può essere salvato sull'avatar attuale dell'utente con PromptSaveAvatar(). Questo può includere:

Configurazioni di avatar predefinite che hai costruito utilizzando articoli del catalogo esistenti.
Qualsiasi configurazione che l'utente ha scelto attraverso un editor avatar nel gioco.

Poiché AvatarEditorService:PromptSaveAvatar() non restituisce un valore, puoi ottenere il risultato ascoltando l'evento AvatarEditorService.PromptSaveAvatarCompleted.

Il seguente codice salverà una HumanoidDescription corrente utilizzando PromptSaveAvatar() e controlla se è stato registrato un evento AvatarEditorService.PromptSaveAvatarCompleted di successo:


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 salvato!
end

Per salvare qualsiasi HumanoidDescription come outfit (senza sovrascrivere l'avatar corrente dell'utente), usa AvatarEditorService:PromptCreateOutfit().

Una volta chiamato, puoi ottenere il risultato di AvatarEditorService:PromptCreateOutfit() ascoltando l'evento AvatarEditorService.PromptCreateOutfitCompleted.

Il seguente campione di codice crea un outfit con AvatarEditorService:PromptCreateOutfit() e ascolta un evento AvatarEditorService.PromptCreateOutfitCompleted di successo:


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
  -- Outfit salvato!
end

Acquistare articoli

Quando si salvano un avatar o un outfit che utilizza articoli del catalogo, l'utente non riceve articoli che non possiede. Prima di salvare un avatar o un outfit, controlla se l'utente possiede l'asset con MarketplaceService:PlayerOwnsAsset() e offrigli la possibilità di acquistare l'articolo con MarketplaceService:PromptPurchase().

Se non desideri implementare acquisti di articoli, puoi invece consentire agli utenti di aggiungere ai preferiti gli articoli non posseduti con AvatarEditorService:PromptSetFavorite().

Tieni presente che non puoi guadagnare Robux commissioni se l'utente decide di acquistare tali articoli al di fuori del tuo gioco.