Konfigurasi pengalaman

Konfigurasi pengalaman memungkinkan Anda memperbarui nilai dalam permainan secara real-time tanpa harus me-restart server:

• Menghidupkan dan mematikan fitur, seperti mengaktifkan atau menonaktifkan dungeon onboarding baru.
• Menyesuaikan nilai dalam permainan seperti kesehatan bos, perolehan pengalaman, atau harga barang.
• Meluncurkan konten berbatas waktu, seperti acara Halloween yang dimulai pada tengah malam.

Konfigurasi berbentuk kunci dan nilai. Daripada menggunakan konstanta yang 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.

Membuat dan mengedit konfigurasi

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

2. Tentukan kunci, jenis, nilai, dan jika ingin, deskripsi untuk membantu Anda atau tim Anda mengidentifikasi tujuan konfigurasi tersebut di kemudian hari. Jenis yang didukung adalah string, angka, boolean, dan objek JSON.

3. Salin potongan kode yang dihasilkan ke dalam skrip server di pengalaman Anda, kemungkinan besar di ServerScriptService. Kode tersebut harus 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)

4. Gunakan nilai tersebut seperti Anda menggunakan variabel lainnya. Konfigurasi tidak ada gunanya 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 serta deskripsinya sesuai keinginan.

Batasan

Nilai konfigurasi memiliki batasan berikut berdasarkan jenisnya.

Menerbitkan konfigurasi

Setelah Anda membuat konfigurasi, ia berpindah ke status staged agar Anda dapat mengujinya sebelum tersedia untuk publik. Perubahan yang dalam status staged tersedia untuk Anda dan tim Anda di sesi permainan Studio, tetapi tidak untuk pemain dalam pengalaman yang aktif. Halaman Konfigurasi di Creator Hub menunjukkan semua perubahan aktif dan staged.

1. Setelah Anda menguji perubahan yang staged, klik Publikasikan sekarang untuk menerbitkan kepada semua pemain dalam waktu lima menit. Anda juga bisa memilih Publikasikan selama 15 menit jika Anda lebih suka periode peluncuran yang lebih panjang.
2. (Disarankan) Tambahkan pesan publikasi deskriptif yang menunjukkan apa yang Anda perbarui. Pesan ini muncul di halaman Sejarah dan dapat membantu Anda serta tim Anda di kemudian hari untuk mengidentifikasi tujuan dari perubahan tersebut.

Membuat dan mengedit konfigurasi di Studio

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

Menerbitkan konfigurasi ke pengalaman lain

Hanya di Studio, Anda dapat menerbitkan konfigurasi Anda ke pengalaman lain, yang sepenuhnya akan menimpa konfigurasi untuk pengalaman tersebut. Ini bisa sangat berguna untuk menyinkronkan konfigurasi dari pengalaman staging atau pengembangan ke pengalaman langsung. Arahkan ke tab Dipublikasikan di widget Studio dan klik Publish As di menu ⋮.

Melihat sejarah dan mengembalikan konfigurasi

Di halaman Konfigurasi, klik Sejarah untuk melihat pembaruan masa lalu. Setiap pembaruan mencakup waktu dan tanggal perubahan, siapa yang melakukan perubahan, dan pesan publikasi.

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

Halaman Sejarah juga memungkinkan Anda mengembalikan konfigurasi ke keadaan sebelumnya:

1. Klik Pulihkan di samping perubahan untuk staging nilai "sebelum". Perhatikan bahwa mengembalikan konfigurasi akan mengabaikan perubahan staged yang ada.
2. Kembali ke halaman Konfigurasi dan publikasikan 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 untuk memanggil metodenya dari skrip klien akan menghasilkan kesalahan.

Langkah pertama untuk bekerja dengan konfigurasi adalah mengambil ConfigSnapshot, yang merupakan 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 di pengalaman:

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

• ConfigService:GetConfigForPlayerAsync() adalah untuk eksperimen. Ini mengambil konfigurasi spesifik pemain sehingga pemain yang berbeda dapat mendapatkan nilai yang berbeda.

  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() akan mengembalikan nil.

Penyegaran snapshot

ConfigSnapshots menunjukkan titik waktu, status konfigurasi ketika Anda meminta snapshot. Untuk menghindari gangguan gameplay, pembaruan pada sebuah konfigurasi tidak secara otomatis mengalir ke snapshot. Dalam permainan tembak-menembak yang 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 secara otomatis memperbarui:

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

Setelah Anda menyegarkan sebuah 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 saat konfigurasi gagal dimuat dan belum pernah dimuat sebelumnya, ConfigService:GetConfigAsync() akan melempar sebuah kesalahan.

Jika ConfigService kehilangan koneksi ke server Roblox setelah sebelumnya dimuat, ConfigService:GetConfigAsync() akan 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 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 menyambung kembali, atau solusi lain.

Menguji konfigurasi

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

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

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

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

Perubahan pengujian berlaku untuk periode server saat ini dan tidak mengalir ke server lain. Di Studio, perubahan ini berlaku untuk sesi permainan saat ini dan tidak mempengaruhi server langsung. Anda dapat secara manual menghapus perubahan pengujian dengan ConfigService:ClearTestingValue().