Konfigurasi pengalaman

Konfigurasi pengalaman memungkinkan Anda memperbarui nilai dalam permainan secara real-time tanpa memulai ulang server:

• Menghidupkan dan mematikan fitur, seperti mengaktifkan atau menonaktifkan dungeon onboarding baru.
• Menyesuaikan nilai dalam permainan seperti kesehatan bos, perolehan pengalaman, atau harga item.
• Meluncurkan konten terjadwal, seperti acara Halloween yang dimulai pada tengah malam.
• Memberikan nilai yang berbeda kepada pemain yang berbeda, seperti memberikan pemain baru armor tambahan.

Konfigurasi berbentuk kunci dan nilai. Alih-alih menggunakan konstanta yang dikodekan secara keras dalam kode Anda, Anda dapat menggunakan kunci untuk mendapatkan nilai (string, angka, boolean, atau objek JSON) dan kemudian memperbarui nilai tersebut kapan pun Anda mau tanpa menerbitkan versi baru dari pengalaman Anda. Perubahan kode yang diperlukan sangat minimal:

local ConfigService = game:GetService("ConfigService")
local configSnapshot = ConfigService:GetConfigAsync()
local myValue = configSnapshot:GetValue("my_key_name")

Anda dapat memiliki hingga 1.000 konfigurasi aktif pada waktu tertentu dan mengelolanya di Creator Hub atau di Roblox Studio.

Buat dan edit konfigurasi

1. Di halaman Creator Hub Konfigurasi untuk pengalaman Anda, klik Buat konfigurasi.

2. Tentukan kunci, tipe, nilai, dan opsional, deskripsi untuk membantu Anda atau tim Anda nanti mengidentifikasi tujuan konfigurasi. Tipe yang didukung adalah string, angka, boolean, dan objek JSON. Klik Berikutnya.

3. (Opsional) Tambahkan kondisi dan nilai penargetan. Kondisi memungkinkan Anda menerapkan nilai konfigurasi kepada pengguna yang cocok (atau tidak cocok) dengan kriteria tertentu, seperti pengguna yang belum pernah memainkan permainan Anda atau yang berbicara bahasa Portugis. Untuk mempelajari lebih lanjut, lihat Target konfigurasi untuk pemain tertentu.

4. Salin potongan kode yang dihasilkan ke dalam skrip server di pengalaman Anda, kemungkinan di ServerScriptService. Untuk konfigurasi "global" yang tidak berbeda berdasarkan pemain, kodenya mungkin terlihat seperti ini:

   local ConfigService = game:GetService("ConfigService")
   
   local configSnapshot = ConfigService:GetConfigAsync()
   local MY_KEY = "my_key" -- opsional, simpan kunci konfigurasi sebagai konstanta
   local myValue = configSnapshot:GetValue(MY_KEY)

   Untuk konfigurasi bersyarat dan eksperimen, kodenya sedikit berbeda:

   local ConfigService = game:GetService("ConfigService")
   local Players = game:GetService("Players")
   local MY_KEY = "my_key" -- opsional, simpan kunci konfigurasi sebagai konstanta
   
   local function onPlayerAdded(player)
       local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
       local myValue = playerConfigSnapshot:GetValue(MY_KEY)
   end
   
   Players.PlayerAdded:Connect(onPlayerAdded)

5. Gunakan nilai seperti Anda menggunakan variabel lainnya. Konfigurasi tidak melakukan apa-apa kecuali Anda menggunakannya dalam kode Anda.

Untuk informasi lebih lanjut tentang bekerja dengan konfigurasi dalam skrip Anda, lihat Tambahkan konfigurasi ke kode Anda.

Mengedit konfigurasi tidak berbeda dari membuatnya. Klik tombol Edit dan perbarui nilai dan deskripsi sesuai keinginan.

Batasan

Nilai konfigurasi memiliki batasan berikut berdasarkan tipe.

Terbitkan konfigurasi

Setelah Anda membuat konfigurasi, itu berpindah ke status staged sehingga Anda dapat mengujinya sebelum tersedia untuk umum. Perubahan yang ditandai tersedia untuk Anda dan tim Anda dalam sesi bermain Studio, tidak untuk pemain dalam pengalaman langsung. Halaman Konfigurasi di Creator Hub menunjukkan semua perubahan aktif dan yang ditandai.

1. Setelah Anda menguji perubahan yang ditandai, klik Terbitkan sekarang untuk menerbitkan kepada semua pemain hampir secara instan (sekitar antara 15 detik dan 1 menit). Anda juga dapat memilih Terbitkan selama 15 menit jika Anda lebih suka periode peluncuran yang lebih lama dan bertahap. Dalam beberapa kasus, klien mungkin memerlukan beberapa menit untuk mencerminkan perubahan setelah diterbitkan.
2. (Disarankan) Tambahkan pesan penerbitan deskriptif yang menunjukkan apa yang Anda perbarui. Pesan ini muncul di halaman Riwayat dan dapat membantu Anda dan tim Anda nanti mengidentifikasi tujuan perubahan.

Target konfigurasi untuk pemain tertentu

Secara default, sebuah konfigurasi memberikan nilai yang sama kepada semua orang. Konfigurasi bersyarat memungkinkan Anda memberikan nilai yang berbeda kepada pemain yang berbeda berdasarkan atribut pemain (negara, masa kerja, bahasa, status pembayar, dll.).

Konfigurasi bersyarat memiliki tiga bagian yang menentukan nilai apa yang diterima pemain:

• Aturan bersyarat mendefinisikan siapa yang cocok. Setiap aturan adalah ekspresi logis, seperti "pembayar aktif dalam 30 hari pertama mereka," yang mengevaluasi atribut pemain.
• Urutan aturan mendefinisikan bagaimana memilih ketika seorang pemain cocok dengan lebih dari satu aturan. Roblox mengevaluasi aturan dari atas ke bawah dan menerapkan cabang yang pertama cocok. Aturan diurutkan secara global, terlepas dari urutan di mana Anda menambahkan nilai bersyarat ke kunci individu.
• Nilai bersyarat mendefinisikan apa yang diterima pemain yang cocok. Untuk setiap kondisi, Anda melampirkan nilai. Jika seorang pemain cocok dengan aturan dalam kondisi tersebut, mereka menerima nilai yang terkait; jika tidak, mereka menerima nilai default dari konfigurasi.

Atribut yang didukung

Konfigurasi bersyarat mendukung atribut berikut. Atribut ini memiliki definisi yang sama dengan filter dan pemecahan yang setara di dasbor analitik.

Buat nilai bersyarat

Anda menambahkan kondisi saat Anda membuat atau mengedit konfigurasi. Pada langkah Tambahkan penargetan, tambahkan kondisi:

1. Pilih kondisi yang ada atau klik Buat yang baru.
2. Tambahkan satu atau lebih aturan.
3. Atur nilai yang diterima pemain yang cocok.

Sebagai contoh, untuk memberikan pengalaman yang lebih sulit kepada pembayar aktif teratas yang mulai bermain dalam 30 hari terakhir, Anda mungkin meningkatkan nilai dynamicBossHealth mereka.

Akses nilai yang ditargetkan dalam kode

Untuk mengambil nilai yang ditargetkan, gunakan ConfigService:GetConfigForPlayerAsync(), yang mengevaluasi aturan dan urutan untuk pemain individu. ConfigService:GetConfigAsync() tidak menerapkan penargetan karena tidak spesifik untuk satu pemain. Untuk informasi lebih lanjut, lihat Tambahkan konfigurasi ke kode Anda.

Praktik terbaik dan batasan

• Setiap nilai bersyarat harus cocok dengan tipe data (boolean, string, angka, atau JSON) dari nilai default konfigurasi.
• Anda dapat memiliki hingga 100 kondisi per permainan.
• Setiap kunci konfigurasi mendukung hingga 20 kondisi.
• Verifikasi urutan aturan sebelum Anda menerbitkan. Karena aturan diurutkan secara global, pastikan bahwa urutan evaluasi Anda diprioritaskan dengan benar. Untuk meninjau urutan, klik tab Kondisi.

Buat dan edit konfigurasi di Studio

Jika Anda mau, Anda dapat membuat, mengedit, menandai, dan menerbitkan konfigurasi di Roblox Studio. Klik File > Buka Konfigurasi untuk membuka widget. Antarmuka Studio sangat nyaman untuk menandai dan menguji nilai baru.

Terbitkan konfigurasi ke pengalaman lain

Di Studio, Anda dapat menerbitkan konfigurasi Anda ke pengalaman lain, yang sepenuhnya menimpa konfigurasi untuk pengalaman tersebut. Ini bisa sangat berguna untuk menyinkronkan konfigurasi dari pengalaman penandaan atau pengembangan ke pengalaman langsung.

1. Di Roblox Studio, pergi ke menu atas dan pilih File > Buka Konfigurasi.

2. Di tab Diterbitkan dari widget Konfigurasi, klik ikon ⋮ dan pilih Terbitkan Sebagai.

   

3. Di dialog yang muncul, temukan dan pilih pengalaman target dari daftar grup di mana Anda memiliki izin edit.

   

Lihat riwayat dan pulihkan konfigurasi

Di halaman Konfigurasi, klik Riwayat untuk melihat pembaruan sebelumnya. Setiap pembaruan memiliki waktu dan tanggal perubahan, siapa yang melakukan perubahan, dan pesan penerbitan.

• Perluas setiap baris untuk melihat kunci, nilai sebelum perubahan, dan nilai setelahnya.
• Gunakan kotak Cari Kunci untuk mencari kunci—bukan deskripsi atau nilai, hanya kunci.

Halaman Riwayat juga memungkinkan Anda memulihkan konfigurasi ke keadaan sebelumnya:

1. Klik Pulihkan di samping perubahan untuk menandai nilai "sebelum". Perhatikan bahwa memulihkan konfigurasi akan membuang perubahan yang ditandai yang ada.
2. Kembali ke halaman Konfigurasi dan terbitkan konfigurasi.

Tambahkan konfigurasi ke kode Anda

Kelas utama untuk bekerja dengan konfigurasi adalah ConfigService, yang mengambil kunci dan nilai terbaru untuk pengalaman Anda. ConfigService hanya tersedia untuk skrip server. Mencoba memanggil metodenya dari skrip klien akan menghasilkan kesalahan.

Langkah pertama untuk bekerja dengan konfigurasi adalah mengambil ConfigSnapshot, nilai terbaru untuk semua konfigurasi pada titik waktu saat ini. Ada dua metode untuk mendapatkan snapshot:

• ConfigService:GetConfigAsync() adalah untuk konfigurasi global yang ingin Anda terapkan ke semua pemain dalam pengalaman:

  local ConfigService = game:GetService("ConfigService")
  local configSnapshot = ConfigService:GetConfigAsync()
  local bossHealth = configSnapshot:GetValue("bossHealth")

• ConfigService:GetConfigForPlayerAsync() mengambil konfigurasi spesifik pemain sehingga pemain yang berbeda dapat mendapatkan nilai yang berbeda. Gunakan untuk konfigurasi bersyarat dan eksperimen.

  local ConfigService = game:GetService("ConfigService")
  local Players = game:GetService("Players")
  
  local function onPlayerAdded(player)
      local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
      local bossHealth = playerConfigSnapshot:GetValue("bossHealth")
  end
  
  Players.PlayerAdded:Connect(onPlayerAdded)

Dalam kedua kasus, jika kunci tidak ada, ConfigSnapshot:GetValue() mengembalikan nil.

Autocomplete

Konfigurasi terintegrasi ke dalam autocomplete Editor Skrip. Ketika Anda memanggil ConfigSnapshot:GetValue(), editor menyarankan nama kunci konfigurasi Anda dan menampilkan tipe setiap konfigurasi saat Anda mengarahkan mouse ke nama variabel.

Jika skrip Anda menggunakan mode --!strict, linter dapat mengambil dan memverifikasi tipe untuk Anda.

Autocomplete juga berfungsi dengan konfigurasi yang menggunakan tipe JSON bersarang yang kompleks.

Segarkan snapshot

ConfigSnapshots mewakili titik waktu, keadaan konfigurasi saat Anda meminta snapshot. Untuk menghindari mengganggu gameplay, pembaruan pada konfigurasi tidak secara otomatis menyebar ke snapshot. Dalam permainan tembak-menembak kompetitif, misalnya, Anda mungkin hanya ingin nilai konfigurasi baru antara ronde sehingga atribut senjata tidak berfluktuasi di tengah pertandingan.

Untuk mendapatkan nilai terbaru secara manual, gunakan metode ConfigSnapshot:Refresh(). Opsional, sambungkan fungsi ke acara ConfigSnapshot.UpdateAvailable untuk menyegarkan secara otomatis:

configSnapshot.UpdateAvailable:Connect(function()
    configSnapshot:Refresh()
end)

Setelah Anda menyegarkan snapshot, Anda dapat menggunakan ConfigSnapshot:GetValueChangedSignal() untuk mendengarkan perubahan pada kunci tertentu sehingga Anda dapat memperbarui kode pengalaman Anda:

configSnapshot:GetValueChangedSignal("bossHealth"):Connect(function(newHealthValue)
    spawnNewBoss(newHealthValue)
end)

Penanganan kesalahan

Dalam kasus yang jarang terjadi ketika konfigurasi gagal dimuat dan belum pernah dimuat sebelumnya, ConfigService:GetConfigAsync() melempar kesalahan.

Jika ConfigService kehilangan koneksi ke server Roblox setelah sebelumnya dimuat, ConfigService:GetConfigAsync() mengembalikan snapshot dengan nilai terbaru yang tersedia. Snapshot ini mencoba untuk menyambung kembali dan memicu acara UpdateAvailable ketika mereka berhasil memuat pembaruan baru.

Bagaimana Anda menangani situasi yang tidak biasa ini terserah Anda. Anda dapat membungkus panggilan dalam pcall() dan memiliki nilai cadangan dalam kode Anda, menunjukkan kesalahan kepada pemain dan menunggu snapshot untuk menyambung kembali, atau solusi lainnya.

Uji konfigurasi

ConfigService memiliki metode bawaan untuk menguji perubahan konfigurasi secara sementara baik di Studio maupun di server langsung tanpa mempengaruhi seluruh pengalaman.

Untuk mengatur nilai uji lokal, panggil ConfigService:SetTestingValue() dari skrip server atau melalui Konsol Pengembang. Perubahan pada nilai uji memicu pembaruan konfigurasi bersama dengan sinyal ConfigSnapshot.UpdateAvailable. Sama seperti pembaruan produksi, Anda harus menyegarkan snapshot yang ada untuk mendapatkan nilai uji:

local ConfigService = game:GetService("ConfigService")
ConfigService:SetTestingValue("bossHealth", 200)

local configSnapshot = ConfigService:GetConfigAsync()
local bossHealth = configSnapshot:GetValue("bossHealth") -- Sekarang 200!

Perubahan uji berlaku untuk masa hidup server saat ini dan tidak menyebar ke server lain. Di Studio, mereka berlaku untuk sesi bermain saat ini dan tidak mempengaruhi server langsung. Anda dapat secara manual menghapus perubahan uji dengan ConfigService:ClearTestingValue().