Layanan Editor Avatar | Dokumentasi

Layanan Editor Avatar memungkinkan Anda mengakses dan membuat perubahan pada avatar pengguna dalam pengalaman. Layanan Editor Avatar juga dapat mengakses inventaris pengguna dan Pasar untuk menyimpan pakaian dan membeli item avatar ke akun pengguna.

Kami merekomendasikan menggunakan Editor Avatar untuk mendapatkan pengalaman pengeditan avatar yang lengkap. Lihat Tempat Pengalaman Editor Avatar dalam Game untuk contoh fitur ini.

Untuk mulai menggunakan Avatar Editor Service, Anda harus pertama permintaan akses ke inventaris pengguna. Setelah akses diberikan dengan sukses, Anda dapat melakukan tindakan berikut:

Baca inventaris pengguna untuk mendapatkan daftar item yang dimiliki pengguna.
Mencari Pasar Luar Angkasa , menggunakan berbagai variabel untuk menyaring dan mengurutkan.
Gunakan item avatar dan simpan pakaian ke avatar pengguna.
Minta pengguna untuk membeli item Marketplace.

Minta Akses

Untuk mulai mengakses inventaris pengguna, Anda perlu meminta pengguna untuk mengizinkan akses melalui PromptAllowInventoryReadAccess() . Anda perlu melakukan permintaan ini sekali per sesi.

Gunakan contoh kode berikut untuk memulai prompt akses dan mendengarkan respons pengguna:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Akses diberikan!
end

Pengguna menerima prompt berikut:

Setelah pengguna menerima prompt, AvatarEditorService dapat memulai mengakses inventaris pengguna.

Membaca Inventaris Pengguna

Setelah akses diberikan oleh pengguna, Anda dapat membaca inventaris mereka dengan fungsi GetInventory(), menyediakan berbagai AvatarAssetTypes untuk disaring. Fungsi ini mengembalikan objek InventoryPages yang berisi item yang dimiliki pengguna.

Gunakan contoh kode berikut untuk mencetak daftar aksesori spesifik di inventaris pengguna:


local AvatarEditorService = game:GetService("AvatarEditorService")

AvatarEditorService:PromptAllowInventoryReadAccess()

local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()

if result == Enum.AvatarPromptResult.Success then
  -- Akses diberikan!
  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

Mencari Pasar

AvatarEditorService termasuk fungsi dan acara yang memungkinkan Anda mencari katalog Roblox. Untuk mencari, berikan pencarian Anda dengan objek CatalogSearchParams yang mencakup salah satu atau lebih dari propperti berikut:

Properti	Deskripsi
Jenis Aset	Sebuah matriksi dari Enum.AvatarAssetType seperti Menu.AvatarAssetType.BackAccessory.
Jenis Paket	Sebuah matriksi dari Enum.BundleType seperti Enum.BundleType.BodyParts.
KategoriFilter	A Enum.CatalogCategoryFilter yang menggambarkan berbagai kategori katalog seperti "Featured" atau "Kreasi Komunitas". Secara default ini diatur menjadi Enum.CatalogCategoryFilter.None
Harga Maksimum	Sebuah angka menggambarkan harga maksimum untuk filter.
Harga Minimum	Sebuah angka yang menggambarkan harga minimum untuk filter. Secara default, MinPrice adalah 0 .
Kata Pencarian	String untuk menanyakan deskripsi item di katalog.
Jenis Sort	A Enum.CatalogSortType yang menggambarkan cara hasil dibaca. Secara default ini diatur menjadi Enum.CatalogSortType.Relevance .
Masukkan OffSale	Boolean yang menggambarkan apakah hasil pencarian termasuk item jual off. Secara default ini diatur ke false.
PenciptaId	Sebuah angka untuk menentukan kreatoryang diberikan. Anda dapat menggunakan UserId atau GroupId.
Nama Pencipta	Sebuah string yang digunakan untuk mencari item yang dibuat oleh kreatortertentu. Anda dapat menggunakan nama pengguna atau nama kelompok.

Kode contoh berikut membangun objek CatalogSearchParams untuk Back dan Shoulder jenis aset, dan menyampaikan melalui panggilan 1> Class.AvatarEditorService:SearchCatalog()|SearchCatalog()1> :


local AvatarEditorService = game:GetService("AvatarEditorService")

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

local pagesObject =
--Fungsi ini mengembalikan objek KatalogPagas yang berisi hasil.
AvatarEditorService:SearchCatalog(catalogSearchParams)
local currentPage = pagesObject:GetCurrentPage()
for _, item in currentPage do
  print(item)
end

Menyimpan Avatar dan Pakaian

Ketika digunakan bersama dengan editor avatar dalam game, AvatarEditorService dapat menyimpan dan menyetujui item avatar dan pakaian ke platform Roblox. Pengguna tidak menerima item katalog yang tidak mereka miliki saat menyimpan avatar atau pakaian.

Apa pun HumanoidDescription dapat disimpan ke avatar pengguna dengan PromptSaveAvatar() . Ini mungkin termasuk:

Konfigurasi avatar prasejah yang telah Anda buat menggunakan item katalog yang sudah ada.
Setiap konfigurasi yang dipilih oleh pengguna melalui editor avatar dalam game.

Karena AvatarEditorService:PromptSaveAvatar() tidak menghasilkan, Anda dapat mendapatkan hasil dengan mendengarkan acara AvatarEditorService.PromptSaveAvatarCompleted .

Kode berikut akan menyimpan HumanoidDescription saat ini menggunakan PromptSaveAvatar() dan memeriksa untuk acara AvatarEditorService.PromptSaveAvatarCompleted yang berhasil:


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 disimpan!
end

Untuk menyimpan setiap HumanoidDescription sebagai pakaian (tanpa menulis ulang avatar pengguna), gunakan AvatarEditorService:PromptCreateOutfit() .

Setelah dipanggil, Anda dapat mengambil hasil dari AvatarEditorService:PromptCreateOutfit() dengan mendengarkan acara AvatarEditorService.PromptCreateOutfitCompleted.

Berikut contoh kode menciptakan pakaian dengan AvatarEditorService:PromptCreateOutfit() dan mendengarkan untuk acara AvatarEditorService.PromptCreateOutfitCompleted yang sukses:


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
  -- Pakaian disimpan!
end

Membeli Barang

Ketika menyimpan avatar atau pakaian yang menggunakan item katalog, pengguna tidak menerima item apa pun yang tidak mereka miliki. Sebelum menyimpan avatar atau pakaian, periksa apakah pengguna memiliki aset dengan MarketplaceService:PlayerOwnsAsset() dan berikan mereka pilihan untuk membeli item dengan Class.MarketplaceService:PromptPurchase()

Jika Anda tidak ingin mengaktifkan pembelian item, Anda dapat mengizinkan pengguna untuk menyukai item non-owned dengan AvatarEditorService:PromptSetFavorite() .

Pastikan bahwa Anda tidak bisa mendapatkan Robux komisi jika pengguna memutuskan untuk membeli barang-barang tersebut di luar pengalaman Anda.