虚拟形象编辑器服务 | 文档 - Roblox 创作者中心

虚拟形象编辑服务让您可以在体验中访问并对用户的虚拟形象进行更改。虚拟形象编辑服务还可以访问用户的库存和Marketplace以保存装扮并向用户的帐户购买虚拟形象物品。

我们建议使用游戏中的虚拟形象编辑器服务来实现完整的角色定制体验。请参阅“简易虚拟形象编辑器示例”，了解此精选能的示例。

要使用虚拟形象编辑器服务，您必须首先请求存取用户的道具。经成功授权后，您可以执行以下操作：

读取用户的物品栏以获得用户的物品列表。
搜索市场，使用各种属性过滤和排序。
装备虚拟形象物品并保存装扮到用户的虚拟形象。
提示用户购买一个市场物品。

请求访问

要开始访问用户的道具，您需要提示用户允许访问通过 PromptAllowInventoryReadAccess() . 您需要执行此请求一会话 per session.

使用以下代码示例来启动访问提示并听取用户的回应：


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 对象，其中包含一个或多个以下属性：

属性	描述
资产类型	Enums.AvatarAssetType 类型的阵列，例如枚数.AvatarAssetType.BackAccessory。
束类型	一个类似 Enum.BundleType 的阵列，例如枚列.束体.
类别过滤器	一个 Enum.CatalogCategoryFilter 描述各种类目，例如“Enum.CatalogCategoryFilter.None”或“社区创作”。默认情况下，这是设置为 0>枚列表目录Filter.None0>
最高价格	一个描述最大价格的整数。
最低价格	描述过滤器最低价格的整数。默认情况下，MinPrice 为 0 。
搜索关键字	用于查询目录中的物品描述。
排序类型	描述结果如何排序的 Enum.CatalogSortType 。默认情况下，这是设置为 Enum.CatalogSortType.Relevance 。
包括在销售中	一个描述搜索结果是否包含销售额外物品的否定。默认值为 false。
创建者Id	用于指定给定创建创作者的整数。您可以使用 either a UserId 或 a GroupId。
创建者名称	用于搜索由指定创建者创建的物品。您可以使用用户名或群组名。

下面的代码示例为 CatalogSearchParams 对象，用于返回和肩部资产类型，并通过 2> Class.AvatarEditorService:SearchCatalog()|SearchCatalog()2> 调用传递：


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 事件来获得结果。

以下代码将使用 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: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 佣金。