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, jadi tempat mana pun di dalam permainan dapat mengakses dan mengubah data yang sama, termasuk tempat di server yang berbeda.

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

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

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

Aktifkan akses Studio

Secara default, game yang diuji di Studio tidak dapat mengakses penyimpanan data, jadi Anda harus terlebih dahulu mengaktifkannya. Mengakses penyimpanan data di Studio dapat berbahaya untuk game yang sedang berjalan karena Studio mengakses penyimpanan data yang sama seperti aplikasi klien. Untuk menghindari penulisan ulang data produksi, jangan aktifkan pengaturan ini untuk game yang sedang berjalan. Sebaliknya, aktifkan untuk versi pengujian terpisah dari game.

Untuk mengaktifkan akses Studio dalam sebuah game yang dipublikasikan:

1. Buka jendela File ⟩ Pengaturan Pengalaman di Studio.
2. Navigasi 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 membuatnya saat Anda menyimpan data permainan untuk pertama kalinya.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Buat data

Penyimpanan data pada dasarnya adalah sebuah kamus, mirip dengan tabel Luau. Sebuah kunci yang unik mengindeks setiap nilai dalam penyimpanan data, seperti Player.UserId yang unik dari pengguna atau string bernama untuk promo 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 di dalam penyimpanan data, panggil UpdateAsync() dengan nama kunci entri dan sebuah 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 menetapkan 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 memperbaruinya sebelum membuat perubahan
• Lebih lambat karena membaca sebelum menulis
• Dihitung terhadap batas baca dan tulis

Baca data

Untuk membaca nilai dari 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

Inkrement data

Untuk menambah sebuah integer dalam penyimpanan data, panggil IncrementAsync() dengan nama kunci entri dan sebuah angka untuk seberapa banyak mengubah nilai tersebut. IncrementAsync() adalah sebuah fungsi kenyamanan yang memungkinkan Anda menghindari memanggil UpdateAsync() dan secara manual menambahkan 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 sebuah entri dan mengembalikan nilai yang terkait dengan kunci tersebut, 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

Terdapat dua jenis metadata yang terkait dengan kunci:

• Ditentukan oleh layanan: Metadata baca-saja default, seperti waktu pembaruan terbaru dan waktu pembuatan. Setiap objek memiliki metadata yang ditentukan oleh layanan.
• Ditentukan oleh pengguna: Metadata kustom untuk penandaan dan pengkategorian. Ditentukan menggunakan objek DataStoreSetOptions dan fungsi SetMetadata().

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

• SetAsync() menerima argumen ketiga dan keempat yang bersifat opsional:

  • Sebuah tabel dari UserIds. Ini dapat membantu dengan pelacakan dan penghapusan hak cipta konten serta 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 sifat yang ditentukan oleh layanan dan fungsi untuk mengambil metadata yang ditentukan oleh pengguna.

  • Fungsi GetUserIds() mengambil tabel dari UserIds yang Anda masukkan ke dalam SetAsync().
  • Fungsi GetMetadata() mengambil metadata yang ditentukan oleh pengguna yang Anda masukkan ke dalam SetAsync() melalui SetMetadata().
  • Properti Version mengambil versi dari kunci tersebut.
  • 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 keadaan kunci saat ini. Ini mengembalikan nilai yang dimodifikasi, kunci yang terkait dengan UserIds, dan metadata dari kunci tersebut.

  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 berurutan

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() daripada GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

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

Contoh berikut mengurutkan data karakter menjadi halaman dengan tiga entri, masing-masing dalam urutan menurun, kemudian melakukan perulangan melalui halaman dan mengeluarkan nama serta umur setiap karakter.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

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