Dịch vụ Chỉnh sửa Avata | Tài liệu - Trung Tâm Nhà Sáng Tạo Roblox

Dịch vụ Chỉnh sửa Avata cho phép bạn truy cập và thực hiện thay đổi với avatar của người dùng trong một trò chơi. Dịch vụ Chỉnh sửa Avata cũng có thể truy cập vào kho hàng của người dùng và Thị trường để lưu trang phục và mua các vật phẩm avatar cho tài khoản của người dùng.

Chúng tôi khuyên bạn nên triển khai Dịch vụ Chỉnh sửa Avata với một trình chỉnh sửa avatar trong trò chơi để có trải nghiệm tùy chỉnh nhân vật hoàn chỉnh. Xem ví dụ về tính năng này trong Demo Chỉnh sửa Avatar Đơn giản.

Để bắt đầu sử dụng Dịch vụ Chỉnh sửa Avata, trước tiên bạn phải yêu cầu truy cập vào kho hàng của người dùng. Sau khi truy cập được cấp quyền thành công, bạn có thể thực hiện các hành động sau:

Đọc kho hàng của người dùng để lấy danh sách các vật phẩm mà người dùng sở hữu.
Tìm kiếm trên Thị trường, sử dụng nhiều thuộc tính để lọc và sắp xếp.
Equip các vật phẩm avatar và lưu trang phục cho avatar của người dùng.
Yêu cầu người dùng mua một vật phẩm trong Thị trường.

Yêu cầu truy cập

Để bắt đầu truy cập vào kho hàng của người dùng, bạn cần yêu cầu người dùng cho phép truy cập thông qua PromptAllowInventoryReadAccess(). Bạn cần thực hiện yêu cầu này một lần cho mỗi phiên.

Sử dụng mẫu mã sau để khởi tạo yêu cầu truy cập và lắng nghe phản hồi của người dùng:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Truy cập được cấp quyền!
end

Người dùng sẽ nhận được thông báo sau:

Khi người dùng chấp nhận thông báo, AvatarEditorService có thể bắt đầu truy cập vào kho hàng của người dùng.

Đọc kho hàng của người dùng

Sau khi người dùng cấp quyền, bạn có thể đọc kho hàng của họ với hàm GetInventory(), cung cấp một mảng AvatarAssetTypes để lọc theo. Hàm này trả về một đối tượng InventoryPages chứa các vật phẩm mà người dùng sở hữu.

Sử dụng mẫu mã sau để in danh sách các phụ kiện cụ thể trong kho hàng của người dùng:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Truy cập được cấp quyền!
  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

Tìm kiếm trên Thị trường

AvatarEditorService bao gồm các hàm và sự kiện cho phép bạn tìm kiếm trong catalog của Roblox. Để tìm kiếm, cung cấp truy vấn của bạn với đối tượng CatalogSearchParams bao gồm một hoặc nhiều thuộc tính sau:

Thuộc tính	Mô tả
AssetTypes	Một mảng Enum.AvatarAssetType như Enum.AvatarAssetType.BackAccessory.
BundleTypes	Một mảng Enum.BundleType như Enum.BundleType.BodyParts.
CategoryFilter	Một Enum.CatalogCategoryFilter mô tả các loại danh mục trong catalog như "Nổi bật" hoặc "Sáng tạo của cộng đồng". Mặc định điều này được đặt thành Enum.CatalogCategoryFilter.None
MaxPrice	Một số nguyên mô tả giá tối đa để lọc.
MinPrice	Một số nguyên mô tả giá tối thiểu để lọc. Mặc định, MinPrice là 0.
SearchKeyword	Một chuỗi để truy vấn các mô tả vật phẩm trong catalog.
SortType	Một Enum.CatalogSortType mô tả cách mà các kết quả được sắp xếp. Mặc định điều này được đặt thành Enum.CatalogSortType.Relevance.
IncludeOffSale	Một boolean mô tả liệu các kết quả của tìm kiếm có bao gồm các vật phẩm không bán hay không. Mặc định điều này được đặt thành false.
CreatorId	Một số nguyên để chỉ định một người sáng tạo nhất định. Bạn có thể sử dụng UserId hoặc GroupId.
CreatorName	Một chuỗi được sử dụng để tìm kiếm theo các vật phẩm được tạo bởi một người sáng tạo nhất định. Bạn có thể sử dụng tên người dùng hoặc tên nhóm.

Mẫu mã sau tạo một đối tượng CatalogSearchParams cho các loại tài sản Back và Shoulder, và truyền thông qua một cuộc gọi SearchCatalog():


local AvatarEditorService = game:GetService("AvatarEditorService")

local catalogSearchParams = CatalogSearchParams.new()
local assetTypes = {
  Enum.AvatarAssetType.BackAccessory,
  Enum.AvatarAssetType.ShoulderAccessory
}
catalogSearchParams.AssetTypes = assetTypes

local pagesObject =
--Hàm này trả về một đối tượng CatalogPages chứa các kết quả.
AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for _, item in currentPage do
  print(item)
end

Lưu avatar và trang phục

Khi dùng cùng với trình chỉnh sửa avatar trong trò chơi, AvatarEditorService có thể lưu và cập nhật các vật phẩm avatar và trang phục lên nền tảng Roblox. Người dùng sẽ không nhận được các vật phẩm catalog họ không sở hữu khi lưu một avatar hoặc trang phục.

Bất kỳ HumanoidDescription nào có thể được lưu vào avatar hiện tại của người dùng với PromptSaveAvatar(). Điều này có thể bao gồm:

Các cấu hình avatar đã được định nghĩa trước mà bạn đã tạo bằng cách sử dụng các vật phẩm trong catalog hiện có.
Bất kỳ cấu hình nào mà người dùng đã chọn qua trình chỉnh sửa avatar trong trò chơi.

Bởi vì AvatarEditorService:PromptSaveAvatar() không chờ, bạn có thể nhận kết quả bằng cách lắng nghe sự kiện AvatarEditorService.PromptSaveAvatarCompleted.

Mẫu mã sau sẽ lưu một HumanoidDescription hiện tại bằng cách sử dụng PromptSaveAvatar() và kiểm tra sự kiện AvatarEditorService.PromptSaveAvatarCompleted thành công:


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
  -- Avatar đã được lưu!
end

Để lưu bất kỳ HumanoidDescription nào như một trang phục (mà không ghi đè avatar hiện tại của người dùng), hãy sử dụng AvatarEditorService:PromptCreateOutfit().

Khi được gọi, bạn có thể nhận kết quả của AvatarEditorService:PromptCreateOutfit() bằng cách lắng nghe sự kiện AvatarEditorService.PromptCreateOutfitCompleted.

Mẫu mã sau tạo một trang phục với AvatarEditorService:PromptCreateOutfit() và lắng nghe sự kiện AvatarEditorService.PromptCreateOutfitCompleted thành công:


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
  -- Trang phục đã được lưu!
end

Mua vật phẩm

Khi lưu một avatar hoặc trang phục sử dụng các vật phẩm trong catalog, người dùng sẽ không nhận được bất kỳ vật phẩm nào mà họ không sở hữu. Trước khi lưu một avatar hoặc trang phục, hãy kiểm tra xem người dùng sở hữu tài sản hay không bằng cách sử dụng MarketplaceService:PlayerOwnsAsset() và cung cấp cho họ tùy chọn mua vật phẩm bằng MarketplaceService:PromptPurchase().

Nếu bạn không muốn triển khai việc mua vật phẩm, bạn có thể cho phép người dùng đánh dấu các vật phẩm không sở hữu bằng AvatarEditorService:PromptSetFavorite().

Hãy lưu ý rằng bạn không thể kiếm được Robux hoa hồng nếu người dùng quyết định mua những vật phẩm đó ngoài trò chơi của bạn.