头像编辑器服务 | 文档 - 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	一个布尔值，描述搜索结果是否包括下架物品。默认情况下，这个值设置为 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 事件来获取结果。

以下代码将保存当前的 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.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() 来收藏未拥有的物品。

请注意，如果用户选择在您的游戏之外购买这些物品，您将无法获得佣金。