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

虛擬人偶編輯服務讓您可以在體驗中存取並作出對用戶的虛擬人偶進行變更。虛擬人偶編輯服務也可以存取用戶的道具欄和市場以儲存服裝並將虛擬人偶道具購買給用戶的帳帳號。

我們推薦實現 Avatar Editor 服務，以內建的虛擬人偶編輯器為一個完整的角色自訂體驗。請參閱簡易虛擬人偶編輯器示範，以取得此功能的範例。

要開始使用虛擬人偶編輯服務，您必須先要求存取用戶的道具欄。在獲得存取權限後，您可以執行以下操作：

閱取使用者的道具欄清單，以取得使用者擁有的道具清單。
搜尋市場，使用各種屬性來過濾和排序。
裝備虛擬人偶道具並儲存服裝到虛擬人偶的衣櫃。
提示用戶購買市場物道具。

請求存取

要開始存取使用者的道具欄，您必須要求使用者允許存取通過 PromptAllowInventoryReadAccess() 。您必須要每作業執行此請求一次。

使用以下代碼示例來啟動存取提示，並且聆聽使用者的回應：


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- 存取授權！
end

使用者收到以下提示：

一旦使用者接受提示，AvatarEditorService 可以開始存取使用者的道具欄。

閱取使用者的道具欄

一旦由用戶授權存取，您可以使用 GetInventory() 函數，閱取用戶的道具欄，並提供一個範圍為 AvatarAssetTypes 的 InventoryPages 對象。此函數返回一個 1>Class.InventoryPages1> 對象，包含用戶擁

使用以下代碼示例列印用戶的道具欄中的特定配件清單：


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 對象，其中包含以下一個或多個屬性：

屬性	說明
資產類型	枚勢兒童遊戲資源的陣列，例如枚勢兒童遊戲資源.BackAccessory。
束組類型	枚數集合體形式如恩惠集合體形式。
類別過濾器	一個 Enum.CatalogCategoryFilter 描述各種目錄類別，例如「Enum.CatalogCategoryFilter.None」或「社群創作」。預設值為 1>Entity.CatalogCategoryFilter.None1>
最高價格	一個描述價格最大值的整數。
最低價格	一個描述最低價格以過篩選器的整數。預設值為 0。
搜尋關鍵字	一個用於查詢目錄中物品描述的字串。
排序類型	一個 Enum.CatalogSortType 說明結果如何排序。預設為 Enum.CatalogSortType.Relevance。
包括關閉銷售	描述搜尋結果是否包含非賣品項目。預設值為 false。
創作者ID	一個整數來指定指定的創作者。您可以使用僅有的創作者ID 或GroupID。
創作者名稱	一個用於搜索指定創作者創作的項目的字串。您可以使用僅一個用戶名或團體名。

下列代碼示例建立了一個 CatalogSearchParams 對象，為返回和肩膀資產類型，並通過 1> Class.AvatarEditorService:SearchCatalog()|SearchCatalog()1> 呼叫傳輸：


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 事件來取得結果。

下列代碼會使用 HumanoidDescription 以及檢查成功 PromptSaveAvatar() 事件：


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:PromptCreateOutfit() 事件的結果來取得 AvatarEditorService.PromptCreateOutfitCompleted 的結果。

下列代碼示例創建了一個 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() 。

如果您不想要實現物品購買，您可以代為允許用戶以 AvatarEditorService:PromptSetFavorite() 的方式喜歡非擁有物品。

注意，您不能在用戶決定購買這些物品外的情況下賺取 Robux 費用。