化身編輯器服務

化身編輯器服務讓您可以在體驗中訪問並更改用戶的化身。化身編輯器服務還可以訪問用戶的庫存和市場，以保存服裝並將化身物品購買到用戶的帳戶。

我們建議在遊戲中實現化身編輯器服務，以提供完整的角色自訂體驗。請參見簡單化身編輯器演示的參考範例，以獲取此功能的範例。

要開始使用化身編輯器服務，您必須首先請求訪問用戶的庫存。在成功授予訪問權限後，您可以執行以下操作：

讀取用戶的庫存，以獲取用戶擁有的物品清單。
搜索市場，使用各種屬性進行篩選和排序。
裝備化身物品並保存服裝到用戶的化身。
提示用戶購買市場物品。

請求訪問

要開始訪問用戶的庫存，您需要通過 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	一個布爾值，描述搜索結果是否包含下架物品。默認設置為 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 平台。用戶在保存化身或服裝時不會獲得其未擁有的目錄物品。

您可以使用 PromptSaveAvatar() 將任何 HumanoidDescription 保存到用戶的當前化身中。這可能包括：

您根據現有目錄物品構建的預定義化身配置。
用戶通過遊戲內化身編輯器選擇的任何配置。

由於 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 佣金。

請求訪問

讀取用戶庫存

搜索市場

保存化身和服裝

購買物品

此頁面