Penyimpanan data

DataStoreService memungkinkan Anda menyimpan data yang perlu bertahan antara sesi, seperti item dalam inventaris pemain atau poin keterampilan. Penyimpanan data konsisten per game, sehingga tempat mana pun dalam game dapat mengakses dan mengubah data yang sama, termasuk tempat di server yang berbeda.

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

Untuk melihat dan memantau semua penyimpanan data dalam sebuah game melalui Hub Kreator, gunakan Pengelola Penyimpanan Data.

Untuk data sementara yang perlu Anda perbarui atau akses secara sering, gunakan memory stores.

Aktifkan akses Studio

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

Untuk mengaktifkan akses Studio di game yang dipublikasikan:

1. Buka jendela File ⟩ Pengaturan Pengalaman di Studio.
2. Navigasikan ke Keamanan.
3. Aktifkan toggle Aktifkan Akses Studio ke Layanan API.
4. Klik Simpan.

Akses penyimpanan data

Untuk mengakses penyimpanan data di dalam sebuah game:

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

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Buat data

Penyimpanan data pada dasarnya adalah kamus, mirip dengan tabel Luau. Sebuah kunci unik mengindeks setiap nilai dalam penyimpanan data, seperti Player.UserId unik pengguna atau string bernama untuk promosi game.

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

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

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

Perbarui data

Untuk mengubah nilai yang disimpan dalam penyimpanan data, panggil UpdateAsync() dengan nama kunci entri dan fungsi callback yang mendefinisikan bagaimana Anda ingin memperbarui entri tersebut. Callback ini mengambil nilai saat ini dan mengembalikan nilai baru berdasarkan logika yang Anda definisikan. Jika callback 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("Nama Huruf Besar:", updatedName)
end

Set vs update

Gunakan set untuk dengan cepat memperbarui kunci tertentu. Fungsi SetAsync():

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

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

• Membaca nilai kunci saat ini dari server yang terakhir memperbarui sebelum melakukan perubahan
• Lebih lambat karena membaca sebelum menulis
• Dihitung terhadap batas baca dan tulis

Baca data

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

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

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

Increment data

Untuk menambah integer dalam penyimpanan data, panggil IncrementAsync() dengan nama kunci entri dan angka untuk seberapa banyak mengubah nilai. IncrementAsync() adalah fungsi kenyamanan yang memungkinkan Anda menghindari memanggil UpdateAsync() dan secara manual menambah integer.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

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

Hapus 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 baca-saja default, seperti waktu pembaruan terbaru dan waktu pembuatan. Setiap objek memiliki metadata yang didefinisikan layanan.
• Didefinisikan pengguna: Metadata kustom untuk penandaan dan kategorisasi. Didefinisikan menggunakan objek DataStoreSetOptions dan fungsi SetMetadata().

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

• SetAsync() menerima argumen ketiga dan keempat opsional:

  • Sebuah tabel dari UserIds. Ini dapat membantu dengan pelacakan dan penghapusan hak cipta konten dan properti intelektual.

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

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

• GetAsync(), IncrementAsync(), dan RemoveAsync() mengembalikan nilai kedua dalam objek DataStoreKeyInfo. Nilai kedua ini berisi properti yang didefinisikan layanan dan fungsi untuk mengambil metadata yang didefinisikan 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, diformat sebagai jumlah milidetik sejak epoch.
  • Properti UpdatedTime mengambil waktu terakhir kunci diperbarui, diformat sebagai jumlah milidetik sejak epoch.

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

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

  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 batas metadata.

Penyimpanan data terurut

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Penyimpanan data terurut mendukung fungsi dasar yang sama seperti penyimpanan data default, ditambah fungsi unik GetSortedAsync(). Ini mengambil beberapa kunci terurut berdasarkan urutan pengurutan tertentu, ukuran halaman, dan nilai minimum/maksimum.

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Mengisi penyimpanan data terurut
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

-- Mengurutkan data dalam urutan menurun ke dalam 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()
		-- Iterasi melalui semua pasangan kunci-nilai di halaman
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Memeriksa apakah halaman terakhir telah dicapai
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Maju ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end

Baca beberapa entri

Untuk membaca beberapa entri penyimpanan data terurut dalam satu permintaan, panggil BatchGetAsync() dengan array kunci. Ini adalah rekan batch untuk membaca entri satu per satu dengan GetAsync().

BatchGetAsync() mengembalikan kamus yang memetakan setiap kunci yang diminta ke tabel dengan bidang value. Kunci yang tidak ada dihilangkan dari kamus, jadi pastikan bahwa kunci ada sebelum membaca nilainya.

Setiap kunci yang Anda minta dihitung sebagai satu permintaan baca, jadi satu panggilan untuk N kunci dihitung sebagai N permintaan terhadap batas baca penyimpanan data terurut.

Contoh berikut membaca tiga skor pemain dalam satu permintaan, kemudian melakukan loop melalui kunci dan mengeluarkan setiap skor yang ada.

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " tidak memiliki entri yang disimpan")
		end
	end
end