虛擬人偶編輯服務

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

虛擬人偶編輯服務讓您可以在體驗中存取和對使用者的虛擬人偶進行更改。虛擬人偶編輯器服務也可以存取使用者的庫存和市場來保存服裝並購買用戶的虛擬人偶物品到用戶的帳帳號。

我們建議使用遊戲內的虛擬人偶編輯器來實現完整的角色自訂體驗，以啟用 Avatar 編輯服務。查看 簡易虛擬人偶編輯器示範地點 以獲得此功能的範例。

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

請求存使用權 通行權 存取

若要開始存取使用者的道具欄，您需要提示使用者通過 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 對象來搜尋您的查詢：

屬性說明
資產類型一個枚列 Enum.AvatarAssetType 例如 Enum.AvatarAssetType.BackAccessory。
包裝類型一個枚列 Enum.BundleType 如 Enum.BundleType.BodyParts。
類別過濾器一個 Enum.CatalogCategoryFilter 描述各種目錄類別，例如「精選」或「社群創作」。默認值為 Enum.CatalogCategoryFilter.None
最高價格一個整數描述要過篩選器的最高價格。
最低價格一個整數描述要過篩選器的最低價格。默認情況下，MinPrice是0。
搜尋關鍵字一個字串，用於查詢目錄中的項目說明。
排序類型一個描述結果如何排序的 Enum.CatalogSortType 。默認值為 Enum.CatalogSortType.Relevance 。
包含關閉銷售一個描述搜索結果是否包含特價物品的 boolean 值。默認值為 false。
創作者ID指定給定創作者的整數。您可以使用使用者ID或群組ID。
創作者名稱用於搜索由給定創作者創建的項目的字串。您可以使用使用者名稱或群組名稱。

下列代碼示例構建了一個 CatalogSearchParams 對象 для 返回 和 肩部 資產類型，並通過一個 SearchCatalog() 呼叫傳送：

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 _, item in currentPage do

  print(item)

end

儲存虛擬人偶和服裝

當與遊戲內的虛擬人偶編輯器一起使用時，AvatarEditorService 可儲存並更新虛擬人偶物品和服裝到 Roblox 平台。使用者在儲存虛擬人偶或服裝時，不會收到未擁有的目錄項目。

任何 HumanoidDescription 都可以儲存到使用者的現有虛擬人偶中，使用 PromptSaveAvatar() 。這可能包括：

  • 使用現有目錄項目建造的預先定義的虛擬人偶配置。
  • 使用遊戲內的虛擬人偶編輯器選擇的任何配置。

因為 AvatarEditorService:PromptSaveAvatar() 不會產生，所以您可以通過聆聽 AvatarEditorService.PromptSaveAvatarCompleted 事件來獲得結果。

下列代碼將使用 HumanoidDescription 儲存當前 PromptSaveAvatar() 並檢查是否成功 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: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() ，並提供他們購買物品的選擇 MarketplaceService:PromptPurchase() 。

如果你不想實現物品購買，你可以允許用戶使用 AvatarEditorService:PromptSetFavorite() 來收藏未擁有的物品。