Penyimpanan data

The DataStoreService memungkinkan Anda menyimpan data yang perlu bertahan di antara sesi, seperti item di inventaris pemain atau poin keterampilan.Penyimpanan data konsisten per pengalaman, jadi setiap tempat di pengalaman dapat mengakses dan mengubah data yang sama, termasuk tempat di server yang berbeda.

Jika Anda ingin menambahkan kontrol izin granular ke penyimpanan data dan mengaksesnya di luar server Studio atau Roblox, Anda dapat menggunakan Membuka API Cloud untuk penyimpanan data.

Untuk melihat dan memantau semua penyimpanan data dalam pengalaman melalui Pusat Kreator, gunakan Manajer Penyimpanan Data.

Untuk data sementara yang perlu Anda perbarui atau akses sering, gunakan toko memori.

Aktifkan akses Studio

Secara default, pengalaman yang diuji di Studio tidak dapat mengakses penyimpanan data, jadi Anda harus mengaktifkannya terlebih dahulu.Mengakses penyimpanan data di Studio bisa berbahaya untuk pengalaman langsung karena Studio mengakses penyimpanan data yang sama dengan aplikasi klien.Untuk menghindari menghapus data produksi, jangan aktifkan pengaturan ini untuk pengalaman langsung.Sebagai gantinya, aktifkan untuk versi uji coba terpisah dari pengalaman.

Untuk mengaktifkan akses Studio di pengalaman dipublikasikan:

1. Buka Pengaturan Permainan.
2. Navigasikan ke Keamanan .
3. Aktifkan tombol Aktifkan Akses Studio ke Layanan API .
4. Klik Simpan .

Toko data akses

Untuk mengakses penyimpanan data di dalam pengalaman:

1. Tambahkan DataStoreService ke sisi server Script.
2. Gunakan fungsi GetDataStore() dan spesifikasikan nama penyimpanan data yang ingin Anda gunakan.Jika penyimpanan data tidak ada, Studio membuat satu saat Anda menyimpan data pengalaman Anda untuk pertama kalinya.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Buat data

Penyimpanan data pada dasarnya adalah kamus, mirip dengan tabel Luau.Indeks kunci unik setiap nilai di tokodata, seperti kunci unik pengguna atau string berlabel untuk promo pengalaman.

Untuk membuat entri baru, panggil SetAsync() dengan nama kunci dan nilai.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, errorMessage = pcall(function()
	experienceStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

Mengupdate data

Untuk mengubah nilai tersimpan di tokodata, panggil UpdateAsync() dengan nama kunci entri dan fungsi panggil balik yang mendefinisikan cara Anda ingin memperbarui entri.Panggilan balasan ini mengambil nilai saat ini dan men返ikan nilai baru berdasarkan logika yang Anda definisikan.Jika panggil balasan mengembalikan nil , operasi penulisan dibatalkan dan nilai tidak diperbarui.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

Tetapkan vs update

Gunakan set untuk segera memperbarui unittertentu. Fungsi SetAsync():

• Dapat menyebabkan ketidakkonsistenan data jika dua server mencoba mengatur kunci yang sama pada saat yang sama
• Hanya dihitung melawan batas penulisan

Gunakan pembaruan untuk menangani upaya multi-server. Fungsi UpdateAsync():

• Membaca nilai kunci saat ini dari server yang terakhir diperbarui sebelum membuat perubahan
• Lebih lambat karena membaca sebelum menulis
• Menghitung melawan batas baca dan tulis

Membaca data

Untuk membaca nilai entri penyimpanan data, panggil GetAsync() dengan nama kunci entri.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, currentExperience = pcall(function()
	return experienceStore:GetAsync("User_1234")
end)
if success then
	print(currentExperience)
end

Data peningkatan

Untuk meningkatkan bilangan bulat di tokodata, panggil IncrementAsync() dengan nama kunci entri dan nomor untuk berapa banyak mengubah nilai. IncrementAsync() adalah fungsi kenyamanan yang memungkinkan Anda menghindari memanggil UpdateAsync() dan secara manual meningkatkan bilangan bulat.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newExperience)
end

Menghapus data

Untuk menghapus entri dan mengembalikan nilai yang terkait dengan kunci, panggil RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

metadata

Ada dua jenis metadata yang terkait dengan kunci:

• Didefinisikan layanan : Metadata bacaan default, seperti waktu pembaruan terbaru dan waktu penciptaan. Setiap objek memiliki metadata yang didefinisikan layanan.
• Definisi pengguna : Metadata khusus untuk penandaan dan kategorisasi. Ditentukan menggunakan objek DataStoreSetOptions dan fungsi SetMetadata().

Untuk mengelola metadata, perluas SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), dan RemoveAsync() fungsi.

• SetAsync() menerima argumen ketiga dan keempat opsional:

  • Meja dari UserIds . Ini dapat membantu dengan hak cipta konten dan pelacakan dan penghapusan kekayaan intelektual.

  • Sebuah objek DataStoreSetOptions , di mana Anda dapat mendefinisikan metadata khusus menggunakan fungsi SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["ExperienceElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync() , IncrementAsync() , dan RemoveAsync() kembalikan nilai kedua di objek DataStoreKeyInfo.Nilai kedua ini berisi kedua properti dan fungsi yang didefinisikan oleh layanan untuk mengambil metadata yang didefinisikan oleh pengguna.

  • Fungsi GetUserIds() mengambil tabel dari UserIds yang Anda berikan ke SetAsync() .
  • Fungsi GetMetadata() mengambil metadata yang didefinisikan pengguna yang Anda berikan ke SetAsync() melalui SetMetadata() .
  • Properti Version mengambil versi kunci.
  • Properti CreatedTime mengambil waktu kunci dibuat, dibentuk sebagai jumlah milidetik sejak zaman.
  • Properti UpdatedTime mengambil waktu terakhir kunci diperbarui, dibentuk sebagai jumlah milidetik sejak zaman.

  local DataStoreService = game:GetService("DataStoreService")
  
  local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
  
  local success, currentExperience, keyInfo = pcall(function()
      return experienceStore:GetAsync("User_1234")
  end)
  if success then
      print(currentExperience)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• Fungsi panggil balasan dari UpdateAsync() mengambil parameter tambahan di objek DataStoreKeyInfo yang menggambarkan status kunci saat ini.Ini mengembalikan nilai yang dimodifikasi, kunci yang terkait dengan UserIds , dan metadata unit.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

Untuk batasan saat mendefinisikan metadata, lihat batasan metadata ..

Toko data diurutkan

Secara default, penyimpanan data tidak mengurutkan kontennya.Jika Anda perlu mendapatkan data dengan cara yang teratur, seperti dalam statistik papan peringkat permanen, hubungi GetOrderedDataStore() alih-alih GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Toko data yang diurutkan mendukung fungsi dasar yang sama dengan toko data default, ditambah fungsi unik GetSortedAsync() .Ini memulihkan beberapa kunci disortir berdasarkan perintah penyortiran khusus, ukuran halaman, dan nilai minimum/maksimum.

Contoh berikut mengurutkan data karakter ke halaman dengan tiga entri, masing-masing dalam urutan menurun, kemudian melingkar melalui halaman dan menampilkan nama dan usia setiap karakter.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Mengisi toko data yang diperintahkan
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- Urutkan data dengan urutan menurun ke halaman tiga entri masing-masing
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Mendapatkan halaman saat ini (pertama)
		local entries = pages:GetCurrentPage()
		-- Mengulang melalui semua pasangan kunci-nilai di halaman
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Memeriksa apakah halaman terakhir telah tercapai
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Kemajuan ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end