虛擬形象編輯服務 | 文件 - Roblox 創作者中心

虛擬形象編輯服務讓您能夠在遊戲中訪問並對用戶的虛擬形象進行更改。虛擬形象編輯服務還可以訪問用戶的物品和市場，以便保存服裝並將虛擬形象物品購買到用戶的帳戶中。

我們建議將虛擬形象編輯服務與遊戲內的虛擬形象編輯器結合使用，以獲得完整的角色自定義體驗。請參見簡單虛擬形象編輯器演示參考地點，以獲得此功能的範例。

要開始使用虛擬形象編輯服務，您必須首先請求訪問用戶的物品。成功授予訪問權限後，您可以執行以下操作：

讀取用戶物品，以獲取用戶擁有的物品列表。
搜索市場，使用各種屬性進行過濾和排序。
裝備虛擬形象物品並保存服裝到用戶的虛擬形象。
提示用戶購買市場物品。

請求訪問

要開始訪問用戶的物品，您需要提示用戶允許通過PromptAllowInventoryReadAccess()進行訪問。您需要在每個會話中執行此請求一次。

使用以下代碼示例啟動訪問提示並監聽用戶的回應：


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- 訪問授予成功！
end

用戶會收到以下提示：

一旦用戶接受該提示，AvatarEditorService便可以開始訪問用戶的物品。

讀取用戶物品

一旦用戶授予訪問權限，您可以使用GetInventory()函數讀取他們的物品，提供一個AvatarAssetTypes的數組進行過濾。此函數返回一個InventoryPages對象，其中包含用戶擁有的物品。

使用以下代碼示例打印用戶物品中的特定配件列表：


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- 訪問授予成功！
  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

搜索市場

AvatarEditorService包括許多函數和事件，讓您可以搜索Roblox目錄。要進行搜索，請提供包含一個或多個以下屬性的CatalogSearchParams對象：

屬性	描述
AssetTypes	一個Enum.AvatarAssetType的數組，例如Enum.AvatarAssetType.BackAccessory。
BundleTypes	一個Enum.BundleType的數組，例如Enum.BundleType.BodyParts。
CategoryFilter	一個Enum.CatalogCategoryFilter，描述各種目錄類別，如「精選」或「社區創作」。默認設置為Enum.CatalogCategoryFilter.None。
MaxPrice	一個描述最大價格的整數進行過濾。
MinPrice	一個描述最小價格的整數進行過濾。默認情況下，MinPrice為0。
SearchKeyword	用於查詢目錄中物品描述的字符串。
SortType	一個Enum.CatalogSortType，描述結果的排序方式。默認設置為Enum.CatalogSortType.Relevance。
IncludeOffSale	A boolean describing whether the results of the search include off sale items. By default this is set to false.
CreatorId	一個整數，用於指定特定創作者。可以使用UserId或GroupId。
CreatorName	一個字符串，用於按特定創作者創建的物品進行搜索。可以使用用戶名或群組名。

以下代碼示例構建了一個CatalogSearchParams對象，針對背部和肩部資產類型，並通過SearchCatalog()調用這個對象：


local AvatarEditorService = game:GetService("AvatarEditorService")

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

local pagesObject =
--此函數返回一個CatalogPages對象，其中包含結果。
AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for _, item in currentPage do
  print(item)
end

保存虛擬形象和服裝

當與遊戲內虛擬形象編輯器一起使用時，AvatarEditorService可以將虛擬形象物品和服裝保存並更新至Roblox平台。用戶在保存虛擬形象或服裝時不會收到他們不擁有的目錄物品。

任何HumanoidDescription都可以使用PromptSaveAvatar()保存到用戶當前虛擬形象中。這可能包括：

使用現有目錄項構建的預定義虛擬形象配置。
用戶通過遊戲內虛擬形象編輯器選擇的任何配置。

由於AvatarEditorService:PromptSaveAvatar()不會等待，因此您可以通過監聽AvatarEditorService.PromptSaveAvatarCompleted事件來獲取結果。

以下代碼將使用PromptSaveAvatar()保存當前的HumanoidDescription，並檢查是否成功觸發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
  -- 虛擬形象保存成功！
end

要將任何HumanoidDescription作為服裝進行保存（而不覆蓋用戶的當前虛擬形象），請使用AvatarEditorService:PromptCreateOutfit()。

一旦被調用，您可以通過監聽AvatarEditorService.PromptCreateOutfitCompleted事件來獲取AvatarEditorService:PromptCreateOutfit()的結果。

以下代碼示例使用AvatarEditorService:PromptCreateOutfit()創建了一個服裝，並監聽成功觸發的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
  -- 服裝保存成功！
end

購買物品

當保存使用目錄物品的虛擬形象或服裝時，用戶不會收到他們不擁有的任何物品。在保存虛擬形象或服裝之前，請檢查用戶是否擁有資產，使用MarketplaceService:PlayerOwnsAsset()，並提供他們購買該物品的選項，使用MarketplaceService:PromptPurchase()。

如果您不希望實現物品購買，您可以允許用戶將未擁有的物品添加到收藏夾中，使用AvatarEditorService:PromptSetFavorite()。

請注意，如果用戶決定在您的遊戲之外購買這些物品，您將無法賺取Robux 佣金。