头像编辑服务

头像编辑服务让您在体验中访问并更改用户的头像。头像编辑服务还可以访问用户的库存和市场，以保存服装和购买头像物品到用户的账户。

我们推荐在游戏中实施头像编辑服务，以实现完整的角色自定义体验。请查看简单头像编辑演示参考地点作为此功能的示例。

要开始使用头像编辑服务，您必须首先请求访问用户的库存。在成功授予访问权限后，您可以执行以下操作：

读取用户的库存，以获取用户拥有的物品列表。
搜索市场，使用各种属性进行筛选和排序。
装备头像物品并保存服装到用户的头像。
提示用户购买市场物品。

请求访问

要开始访问用户的库存，您需要提示用户通过 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	一个整数，用于指定给定创建者。您可以使用用户 ID 或组 ID。
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 佣金。

请求访问

读取用户库存

搜索市场

保存头像和服装

购买物品

在此页面