Tutorial · Data pemain

Cara menyimpan data pemain di Roblox Studio dengan DataStore

Roblox tidak menyimpan apa pun tentang pemain di antara sesi kecuali script server yang menyimpannya. Panduan ini membuat module PlayerData yang memuat, menyimpan di memori dan menyimpan data setiap pemain dengan DataStoreService, lalu membahas pengetesan, batas-batasnya dan bagaimana data tersimpan bisa hilang.

Diperbarui 12 November 202616 menit bacaDitulis oleh

Singkatnya

Pakai DataStoreService dari Script server: muat data setiap pemain dengan GetAsync saat mereka masuk, simpan di sebuah table selama mereka bermain, dan simpan dengan UpdateAsync secara berkala, saat mereka keluar (PlayerRemoving) dan saat server dimatikan (game:BindToClose). Bungkus setiap panggilan dengan pcall dan ulangi beberapa kali kalau gagal.

  • Untuk mengetes di Studio, publikasikan place-nya dan nyalakan File > Experience Settings > Security > Enable Studio Access to API Services, di game tes terpisah: Studio memakai data yang sama dengan server live.
  • Kalau data seorang pemain gagal dimuat, jangan pernah simpan pemain itu. Menyimpan nilai default akan menimpa progres aslinya.
  • Simpan satu table per pemain di satu key seperti User_12345, secara berkala, bukan setiap kali ada perubahan.
  • Untuk trading atau item berbayar, tambahkan session locking supaya dua server tidak bisa sama-sama menyimpan pemain yang sama.
Di halaman ini
  1. Nyalakan akses Studio
  2. Cara kerja data store
  3. GetAsync vs UpdateAsync
  4. 1. Module PlayerData
  5. Cara kerja module
  6. 2. Pakai datanya
  7. 3. Peringatkan pemain
  8. 4. Tes di Studio
  9. Kenapa data hilang
  10. Session locking
  11. Batas
  12. Versi dan backup
  13. Error umum
  14. Dengan RoCode
  15. Pertanyaan umum
  16. Sumber dan bacaan lanjutan

Sebelum mulai: nyalakan akses Studio di salinan tes

Game yang berjalan di Studio tidak bisa mengakses data store sampai kamu mengizinkannya. Mengizinkannya punya konsekuensi yang disebut dokumentasi Roblox: Studio lalu membaca dan menulis data store yang sama dengan game live, jadi tes yang me-reset coin kamu di Studio juga me-reset-nya di game live, dan bug di kode tes bisa merusak key pemain sungguhan.

  1. Buat salinan tes. Simpan place kamu ke sebuah file, buka salinannya, pilih File > Publish to Roblox As dan klik Create new game. Jangan tambahkan sebagai place di dalam game live kamu: setiap place dalam satu game memakai data store yang sama.
  2. Di salinan tes, buka File > Experience Settings dan masuk ke Security.
  3. Nyalakan Enable Studio Access to API Services dan klik Save.

Panggilan data store hanya bekerja di Script server; LocalScript yang mencobanya mendapat error, jadi client tidak bisa menulis data tersimpan. Saat sebuah tombol perlu mengubahnya, client meminta ke server dengan RemoteEvent dan server yang memutuskan (lihat panduan RemoteEvents, dalam bahasa Inggris).

Cara data store menyimpan data pemain

IlustrasiTes Langkah 4 dari panduan ini, dipercepat: Play, Stop menyimpan sesi ke data store, dan Play lagi memuatnya, jadi Output menampilkan 200.

Data store adalah kumpulan key dan value bernama di server Roblox, dipakai bersama oleh setiap server dan setiap place di game kamu. DataStoreService:GetDataStore("PlayerData") mengembalikan satu data store.

Best practice Roblox intinya satu data store untuk data pemain, satu key per pemain, satu table di setiap key. Buat key dari UserId pemain, seperti User_12345, jangan pernah dari namanya, yang bisa diganti. Pola tetap User_{UserId} juga membuat proses otomatis right-to-be-forgotten milik Roblox bisa menemukan data pemain kalau kamu menyiapkannya.

Yang bisa disimpan data store
TipeBisa disimpan?Catatan
Number, string, boolean, bufferYaString harus UTF-8 yang valid. Jangan simpan inf atau nan.
TableYaKalau semua isinya juga bisa disimpan. Table yang key angkanya tidak mulai dari 1 (jadi panjangnya 0) kembali dengan key itu sebagai string.
Instance, Vector3, CFrame, Color3TidakPenyimpanannya error atau menyimpan nil. Simpan nama item, atau posisi sebagai tiga angka.

Setiap request adalah panggilan web yang bisa gagal, butuh waktu dan dihitung terhadap jatah per menit. Jadi sistem save yang andal membaca sekali saat pemain masuk, menyimpan datanya di table server selama mereka bermain, dan menuliskannya kembali sesekali.

GetAsync, SetAsync atau UpdateAsync: mana yang dipakai

Method utama data store
MethodFungsinyaPakai untuk
GetAsync(key)Membaca value-nya. Hasilnya di-cache di server itu selama 4 detik.Memuat data pemain
SetAsync(key, value)Menimpa value tanpa membacanya. Satu penulisan.Key baru, atau value yang tidak bergantung pada value lama
UpdateAsync(key, callback)Membaca value terbaru, memberikannya ke callback kamu dan menulis apa yang dikembalikan. Satu pembacaan dan satu penulisan.Menyimpan data pemain, dan key apa pun yang bisa ditulis lebih dari satu server
IncrementAsync(key, delta)Menambahkan bilangan bulat ke bilangan bulat yang tersimpan.Penghitung
RemoveAsync(key)Menghapus key dan mengembalikan value lamanya. Versi sebelumnya masih bisa didaftar dan dibaca.Menghapus data pemain

SetAsync menulis secara buta: kalau dua server menyimpan key yang sama di saat yang hampir bersamaan, penulisan yang belakangan menang, apa pun isinya. UpdateAsync membaca value saat ini lebih dulu, dan kalau server lain menulis di antaranya, Roblox menjalankan callback kamu lagi dengan value baru. Roblox menyarankannya setiap kali penulisan bergantung pada value saat ini atau beberapa server bisa menulis key itu, dan itulah gambaran data pemain. Callback-nya punya tiga aturan:

  • Tidak boleh yield: tidak ada task.wait() dan tidak ada panggilan data store lain di dalamnya.
  • Bisa berjalan lebih dari sekali, jadi hanya boleh menghitung value baru, jangan pernah memberi item atau menjalankan event.
  • Mengembalikan nil membatalkan penulisan. Module memakai ini untuk menghindari menimpa data yang disimpan versi game yang lebih baru.

Langkah 1: Buat module PlayerData

ModuleScript ini adalah satu-satunya kode yang berbicara dengan data store. Module memuat data setiap pemain saat mereka masuk, menyimpannya di memori, menyimpannya setiap 180 detik, saat mereka keluar dan saat server dimatikan, dan menolak menyimpan siapa pun yang datanya gagal dimuat.

  1. Di Explorer, arahkan kursor ke ServerScriptService, klik + dan sisipkan ModuleScript. Ganti namanya jadi PlayerData dan ganti isinya dengan kode di bawah.
  2. ModuleScript hanya berjalan saat ada script yang me-require-nya. Sisipkan Script di ServerScriptService bernama Main dengan baris ini: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Script server lain me-require-nya dengan cara yang sama.
  3. Edit DEFAULTS dan tipe Data sesuai game kamu, dengan setiap field tetap berupa number, string, boolean atau table.
Explorer setelah Langkah 1 sampai 3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript di ServerScriptService bernama PlayerData
-- PlayerData: memuat data setiap pemain saat mereka masuk, menyimpannya di memori,
-- dan menyimpannya secara berkala, saat mereka keluar dan saat server dimatikan.
-- Script server lain memakai PlayerData.Get(player) untuk membaca dan mengubahnya.

local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")

local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- naikkan ini saat bentuk datanya berubah, dan tambahkan satu langkah ke migrate()
local AUTOSAVE_SECONDS = 180
-- Di Studio panggilan yang gagal langsung menyerah, jadi tes tanpa akses data store cepat
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- berlipat dua setelah setiap kegagalan: 1, 2, 4

export type Data = {
	SchemaVersion: number,
	Coins: number,
	Level: number,
	Inventory: { string },
}

-- Modal awal pemain yang benar-benar baru
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- false kalau load gagal: data default tidak boleh menggantikan progres asli
}

-- Dipanggil di dalam setiap pcall di bawah, jadi place yang belum dipublikasikan
-- (tanpa akses data store) tetap memuat pemain dengan data default
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- penyimpanan yang masih berjalan, per key
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Berjalan dengan pemainnya begitu datanya siap. Panggil PlayerData.Get(player) untuk table-nya:
-- table yang dikirim lewat BindableEvent sampai sebagai salinan, jadi mengubahnya tidak mengubah apa-apa.
PlayerData.Loaded = loadedEvent.Event

local function deepCopy(value: any): any
	if type(value) ~= "table" then
		return value
	end
	local copy = {}
	for key, item in value do
		copy[key] = deepCopy(item)
	end
	return copy
end

local function defaultData(): Data
	local data = deepCopy(DEFAULTS) -- salinan baru, jadi pemain tidak pernah berbagi satu table Inventory
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Membawa data tersimpan ke skema saat ini. Mengembalikan nil kalau tidak bisa dipakai dengan aman.
local function migrate(saved: any): Data?
	if type(saved) ~= "table" then
		return nil
	end
	local version = tonumber(saved.SchemaVersion) or 1
	if version > SCHEMA_VERSION then
		return nil -- disimpan oleh versi game yang lebih baru: jangan pernah dimuat atau ditimpa di sini
	end

	-- Satu langkah per perubahan skema, dari yang paling lama
	if version < 2 then
		-- Contoh: versi 1 menyebut mata uangnya Gold. Hanya salin kalau Coins tidak ada,
		-- jadi data lama yang sudah punya Coins tapi tanpa SchemaVersion tetap mempertahankan nilainya.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Tambahkan field yang dibuat sejak pemain ini terakhir menyimpan, dan ganti value yang salah tipe
	for field, default in DEFAULTS do
		if type(saved[field]) ~= type(default) then
			saved[field] = deepCopy(default)
		end
	end
	saved.SchemaVersion = SCHEMA_VERSION
	return saved
end

-- Menjalankan panggilan data store di dalam pcall. Kalau gagal, menunggu lalu mencoba lagi, menggandakan
-- waktu tunggu setiap kali dan menambah sedikit keacakan supaya server tidak mengulang bersamaan.
local function withRetries(label: string, call: () -> any): (boolean, any)
	for attempt = 1, MAX_ATTEMPTS do
		local ok, result = pcall(call)
		if ok then
			return true, result
		end
		warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
		if attempt < MAX_ATTEMPTS then
			local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
			task.wait(waitTime + math.random() * waitTime / 2)
		end
	end
	return false, nil
end

local function save(session: Session): boolean
	if not session.canSave then
		return false
	end
	local key = session.key
	pendingSaves[key] = (pendingSaves[key] or 0) + 1

	local newerSchema = false
	local ok = withRetries(`Save {key}`, function()
		return store():UpdateAsync(key, function(current: any)
			if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
				newerSchema = true
				return nil -- mengembalikan nil membatalkan penulisan
			end
			-- Tulis seluruh table saat ini, ditandai dengan UserId pemain
			return session.data, { session.userId }
		end)
	end)

	local left = (pendingSaves[key] or 1) - 1
	if left > 0 then
		pendingSaves[key] = left
	else
		pendingSaves[key] = nil
	end
	if newerSchema then
		session.canSave = false
		warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
	end
	return ok and not newerSchema
end

local function startAutosave(player: Player, session: Session)
	task.spawn(function()
		-- Mulai di titik acak dalam interval supaya server tidak menyimpan bersamaan
		task.wait(math.random() * AUTOSAVE_SECONDS)
		while sessions[player] == session do
			save(session)
			task.wait(AUTOSAVE_SECONDS)
		end
	end)
end

local function load(player: Player)
	local key = "User_" .. player.UserId

	-- Kalau pemain ini baru keluar dari server ini lalu kembali, biarkan penyimpanan terakhir selesai dulu
	while pendingSaves[key] do
		task.wait()
	end

	local ok, saved = withRetries(`Load {key}`, function()
		return store():GetAsync(key)
	end)
	if player.Parent ~= Players then
		return -- keluar saat loading: tidak ada yang berubah, jadi tidak ada yang perlu disimpan
	end

	local data: Data? = nil
	if ok then
		data = if saved == nil then defaultData() else migrate(saved)
	end

	local session: Session = {
		key = key,
		userId = player.UserId,
		data = data or defaultData(),
		canSave = data ~= nil,
	}
	if not session.canSave then
		warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
	end

	sessions[player] = session
	player:SetAttribute("DataLoaded", session.canSave) -- GUI bisa membaca ini dan memperingatkan pemain
	startAutosave(player, session)
	loadedEvent:Fire(player)
end

local function endSession(player: Player)
	local session = sessions[player]
	if not session then
		return
	end
	sessions[player] = nil -- menghentikan loop autosave dan membuat panggilan kedua tidak berbuat apa-apa
	save(session)
end

-- Table data live milik pemain, atau nil sampai selesai dimuat. Ubah hanya dari script server.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- True kalau data pemain berhasil dimuat dan akan disimpan. Cek ini sebelum menjual apa pun.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Menyimpan sekarang alih-alih menunggu timer, untuk momen penting seperti pembelian.
-- Yield, dan mengembalikan true setelah penyimpanannya berhasil.
function PlayerData.SaveNow(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and save(session)
end

Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
	task.spawn(load, player) -- pemain yang masuk sebelum module ini pertama kali di-require
end

game:BindToClose(function()
	-- Server memberi function ini 30 detik, jadi simpan semua orang pada saat yang sama
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Lalu tunggu setiap penyimpanan yang masih berjalan, termasuk yang dimulai PlayerRemoving
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

Setelah game live, jangan ubah STORE_NAME dan pola key User_. Mengubah salah satunya mengarahkan module ke key kosong, dan setiap pemain mulai lagi dari nilai default.

Cara module menjaga data tetap aman

Nilai default dan versi skema

Pemain baru mendapat salinan baru dari DEFAULTS. Harus salinan: kalau setiap pemain berbagi satu table Inventory, item yang ditambahkan untuk satu pemain akan muncul untuk semua.

Setiap table tersimpan membawa SchemaVersion. Menambah field tidak perlu mengubah versi, karena migrate mengisi field yang hilang dari nilai default. Mengganti nama atau mengubah struktur perlu: naikkan SCHEMA_VERSION dan tambahkan satu langkah, seperti contoh yang mengganti nama Gold menjadi Coins (di game baru, hapus contoh itu dan mulai dari 1). Data dengan versi lebih tinggi dari versi server berasal dari rilis lebih baru yang masih bergulir, jadi server yang lebih lama membiarkannya.

Load yang gagal tidak pernah disimpan

Aturan ini mencegah data terhapus total. Kalau setiap percobaan load gagal, pemain bermain dengan data default, tapi canSave bernilai false, jadi nilai default itu tidak pernah menimpa progres aslinya. Module juga mengatur attribute DataLoaded ke false, yang dipakai Langkah 3 untuk memberi tahu pemain. Contoh referensi Roblox menangani load yang gagal dengan cara yang sama dan menyarankannya dibanding meng-kick; kalau kamu lebih suka meng-kick, panggil player:Kick() dengan pesan di tempat module memberi peringatan.

Retry dengan backoff

withRetries membungkus setiap panggilan dengan pcall. Setelah gagal, ia menunggu 1, lalu 2, lalu 4 detik, masing-masing ditambah acak sampai setengahnya lagi, dan berhenti setelah empat percobaan (satu di Studio, jadi place tanpa akses data store langsung mulai). Keacakan itu menyebar retry dari banyak server setelah gangguan, dan batasnya menjaga waktu tunggu sekitar 10 detik, di dalam 30 detik yang didapat server untuk dimatikan. Karena setiap penyimpanan menulis seluruh table live lewat UpdateAsync, retry yang selesai terlambat tidak bisa mengembalikan data lama.

Kapan module menyimpan

KapanKenapa
Setiap 180 detik selama pemain ada di serverMembatasi kerugian kalau server crash. Penyimpanan pertama terjadi di titik acak dalam interval supaya server tidak menyimpan bersamaan. Contoh referensi Roblox juga memakai 180 detik.
Saat pemain keluar (PlayerRemoving)Penyimpanan terakhir yang normal. Sesinya dihapus lebih dulu, jadi autosave berhenti.
Saat server dimatikan (game:BindToClose)Semua orang yang masih di server disimpan sekaligus, dan function menunggu setiap penyimpanan yang sedang berjalan. Roblox memberinya 30 detik.
Sesuai kebutuhan, dengan PlayerData.SaveNow(player)Setelah sesuatu yang tidak boleh hilang, seperti pembelian.

Kalau pemain masuk lagi ke server yang sama selagi penyimpanan terakhirnya masih berjalan, load baru menunggu penyimpanan itu selesai, jadi tidak bisa membaca value yang lebih lama.

Langkah 2: Baca dan ubah data dari script lain

Setiap script server yang me-require module ini memakai table yang sama:

PanggilanFungsinya
PlayerData.Get(player)Table data live milik pemain, atau nil sampai selesai dimuat. Ubah field-nya langsung, seperti data.Coins += 10, dan penyimpanan berikutnya ikut membawanya.
PlayerData.LoadedBerjalan dengan pemainnya begitu datanya siap, termasuk setelah load yang gagal. Event ini hanya memberikan pemainnya, karena table yang dikirim lewat BindableEvent sampai sebagai salinan.
PlayerData.CanSave(player)false kalau load gagal. Cek ini sebelum menjual apa pun: pembelian yang tidak bisa disimpan hilang saat pemain keluar.
PlayerData.SaveNow(player)Langsung menyimpan dan mengembalikan true kalau berhasil. Panggilan ini yield.

Module adalah satu-satunya tempat data tersimpan berada, dan leaderstats hanya tampilan: buat seperti di panduan leaderboard, isi dari PlayerData.Get(player) di handler Loaded, dan perbarui keduanya saat sebuah value berubah. Jangan pernah membaca value tersimpan kembali dari leaderstats, dan jangan pernah biarkan script kedua menyimpan key yang sama.

Script yang me-require module setelah pemain masuk akan melewatkan Loaded untuk mereka. Sambungkan handler-nya, lalu juga loop lewat Players:GetPlayers() dan tangani siapa pun yang PlayerData.Get(player)-nya sudah mengembalikan table.

Mengganti script save yang lebih lama, seperti yang ada di panduan leaderboard? Value-nya tetap berada di data store dan key miliknya sendiri, jadi module ini memulai semua orang dari nilai default. Sebelum rilis, arahkan STORE_NAME dan prefix User_ ke yang lama (migrate menganggap data tanpa SchemaVersion sebagai versi 1 dan mengisi field yang hilang), atau salin value lamanya, lalu hapus script lama itu.

Client tidak pernah mengubah data ini secara langsung. Tombol shop menjalankan RemoteEvent; server mengecek CanSave, membandingkan harga dengan Coins milik pemain, mengubah table dan memanggil SaveNow. Panduan GUI shop membuat alur pembelian di sisi server itu.

Untuk contoh lengkap menambah field, panduan clicker simulator menambahkan PowerLevel dan Rebirths ke DEFAULTS dan tipe Data, lalu mengubahnya di table yang dikembalikan PlayerData.Get. migrate memberi pemain dengan save lama field-field baru itu.

Langkah 3: Beri tahu pemain saat datanya gagal dimuat

Pemain yang datanya gagal dimuat perlu tahu bahwa sesi ini tidak akan disimpan, supaya mereka bisa masuk lagi alih-alih bermain sia-sia. LocalScript ini memantau attribute DataLoaded dan menampilkan banner saat nilainya false.

LocalScript di StarterPlayerScripts bernama DataWarning
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local shown = false

local function showWarning()
	if shown or player:GetAttribute("DataLoaded") ~= false then
		return
	end
	shown = true

	local gui = Instance.new("ScreenGui")
	gui.Name = "DataWarning"
	gui.ResetOnSpawn = false

	local label = Instance.new("TextLabel")
	label.AnchorPoint = Vector2.new(0.5, 0)
	label.Position = UDim2.new(0.5, 0, 0, 12)
	label.Size = UDim2.new(0.8, 0, 0, 48)
	label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
	label.TextColor3 = Color3.new(1, 1, 1)
	label.TextScaled = true
	label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
	label.Parent = gui

	gui.Parent = player:WaitForChild("PlayerGui")
end

-- Server mengatur DataLoaded sekali, setelah mencoba memuat data pemain ini
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Langkah 4: Tes penyimpanan di Studio

Lakukan ini di salinan tes, dengan akses Studio menyala.

  1. Beri dirimu sesuatu untuk disimpan. Di bawah baris require di Main, tambahkan: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Tekan Play. Jendela Output (di menu Window, atau di tab Script) menampilkan namamu dan 100 (pada jalan pertama), tanpa peringatan Could not load.
  3. Tekan Stop. Mengakhiri tes menutup server, dan module menyimpanmu sebelum server tutup.
  4. Tekan Play lagi. Output seharusnya menampilkan 200, 100 lebih banyak dari sebelumnya. Kalau menampilkan angka yang sama lagi, penyimpanannya tidak berhasil: baca peringatan di atasnya.
  5. Tes jalur kegagalannya. Matikan akses Studio dan tekan Play. Setelah beberapa detik retry, Output menampilkan Could not load User_... dan 100, dan banner dari Langkah 3 muncul. Stop, nyalakan lagi aksesnya dan Play: Output menampilkan 300, yaitu 200 yang tersimpan plus 100, karena sesi yang gagal tidak pernah menimpa datamu.
  6. Hapus baris tes dari Main.

Kenapa data pemain bisa hilang

Ini cara-cara umum sistem save kehilangan progres. Module menangani empat baris pertama dan baris skema di dalam kode; sisanya bergantung pada apa yang kamu simpan dan cara kamu memakainya, dan yang terakhir butuh session locking.

Yang terjadiAkibatnyaPencegahan
Load gagal dan script tetap menyimpanNilai default menimpa progres asli: data terhapus totalJangan pernah simpan pemain yang load-nya gagal
Hanya menyimpan di PlayerRemovingCrash atau server mati melewatkan penyimpananAutosave, plus BindToClose yang menunggu penyimpanannya
Tanpa pcall atau tanpa retrySatu request gagal menghentikan script atau membuang penyimpananpcall dengan beberapa retry berjarak
Menyimpan setiap ada perubahanRequest mengantre; saat antrean berisi 30, request baru dibuangSimpan data di memori dan simpan secara berkala
Menyimpan sesuatu yang tidak bisa ditampung data storePenyimpanannya error, atau value-nya kembali sebagai nilSimpan number, string, boolean dan table berisi itu
Mengubah bentuk data tanpa migrasiSave lama dimuat ke field yang salahVersi skema dan langkah migrasi
Dua script menyimpan key yang samaSetiap penyimpanan menimpa field milik yang lainSatu module memiliki key itu
Dua server memegang pemain yang samaServer dengan data lebih lama menyimpan terakhir dan menimpa progres yang lebih baruSession locking

Session locking, "lock lost" dan ProfileStore

Seorang pemain terhubung ke satu server pada satu waktu, tapi penyimpanan terakhir server lama masih bisa berjalan saat mereka masuk ke server baru: retry yang lambat, teleport atau rejoin cepat. Kalau server baru memuat lebih dulu, ia memegang data yang lebih lama, dan server mana pun yang menyimpan terakhir yang menang. Dokumentasi Roblox mencatat bahwa di game dengan trading, celah ini adalah sumber umum duplikasi item.

Session locking menutup celah itu. Saat sebuah server memuat key pemain, server itu menulis lock ID miliknya ke metadata key di panggilan UpdateAsync yang sama. Server lain yang menemukan lock belum kedaluwarsa yang bukan miliknya tidak akan memuat atau menyimpan key itu. Pemiliknya memperbarui lock di setiap autosave dan menghapusnya di penyimpanan terakhir; kalau berhenti memperbarui, lock-nya kedaluwarsa dan server lain boleh mengambilnya.

Arti "lock lost"

Di sistem session locking, sebuah server kehilangan lock saat server lain sekarang memiliki key pemain itu, karena lock-nya kedaluwarsa atau diambil alih. Salinannya mungkin sudah usang, jadi server itu harus berhenti menyimpan pemain tersebut; respons yang umum adalah meng-kick mereka dengan pesan supaya mereka tersambung ulang. Kalau kamu melihat "lock lost" sebagai pemain, pesan itu datang dari sistem save milik game itu sendiri, dan hanya developernya yang bisa menjelaskannya.

Apakah kamu membutuhkannya?

Module di panduan ini tidak mengunci sesi. Tanpa locking, kasus terburuk yang realistis adalah pemain kehilangan apa yang didapatnya di server lama sejak penyimpanan terakhir yang berhasil, dalam balapan yang jarang terjadi. Tambahkan locking saat duplikasi atau kehilangan akan merugikan pemain secara nyata: trading, developer product, item langka atau teleport yang sering.

OpsiApa ituYang perlu diketahui
Module di panduan iniLoading, cache, retry, autosave, penyimpanan saat shutdown dan versi skema, tanpa lockingCukup pendek untuk dibaca seluruhnya dan diubah
Contoh player data and purchasing milik RobloxKode referensi dari Roblox dengan session locking, retry yang diproses berurutan per key, dan penanganan receipt pembelianRoblox bilang kode ini belum terbukti dalam jangka panjang di game populer dan tidak boleh dipakai apa adanya tanpa pengetesan yang ekstensif
ProfileStoreModule komunitas gratis dan open source, penerus ProfileService, dibangun di sekitar session locking dan autosaveBukan buatan Roblox. Memindahkan game yang sudah ada ke sana berarti memigrasikan data yang sudah kamu simpan

Untuk module pihak ketiga apa pun, Roblox menyarankan mengecek siapa pemiliknya, apakah masih dirawat dan bagaimana kamu akan mengakses datamu tanpanya. Dokumentasi yang sama menyebut DataStore2 sebagai library lama yang sebaiknya tidak dipakai game baru.

Batas data store

Ini batas-batas di dokumentasi Roblox per 30 September 2026. Roblox merevisinya, jadi cek halaman error codes and limits (dalam bahasa Inggris) sebelum mendesain berdasarkan angka yang pasti.

Batas request default untuk setiap server, per menit
Jenis requestData store standarOrdered data store
Baca: GetAsync, pembacaan di UpdateAsync60 + 40 × pemain60 + 40 × pemain
Tulis: SetAsync, IncrementAsync, penulisan di UpdateAsync60 + 40 × pemain30 + 5 × pemain
Daftar: ListKeysAsync, atau GetSortedAsync untuk ordered store5 + 2 × pemain5 + 2 × pemain
Hapus: RemoveAsync60 + 40 × pemain30 + 5 × pemain

Dengan 20 pemain, sebuah server boleh melakukan 860 penulisan standar per menit; autosave module ini memakai sekitar 7, plus satu per pemain yang keluar. Menyimpan setiap kali coin diambil itulah yang menghabiskan jatah. Jatah kedua mencakup seluruh game dan dipakai bersama Open Cloud: 300 pembacaan per menit plus 40 per pemain online, dan 300 penulisan plus 20 per pemain.

Batas ukuran dan throughput
BatasNilai
Nama data store, nama key, scopeMasing-masing 50 karakter
Value yang disimpan di satu key4,194,304 karakter, diukur sebagai JSON
Pembacaan dari satu key, di semua server25 MB per menit
Penulisan ke satu key, di semua server4 MB per menit, setiap request dibulatkan ke atas ke KB berikutnya
Request yang menunggu30 per antrean; lebih dari itu, request gagal dengan error 301 sampai 306
Penyimpanan untuk seluruh game500 MB plus 1 MB per pengguna sepanjang masa

Ukur data pemain dengan #HttpService:JSONEncode(data), dan lihat sisa jatah server live dengan DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Panggilan GetAsync yang dijawab dari cache 4 detik tidak dihitung. Mode Run di Studio punya batasnya sendiri, yang mungkin lebih rendah, jadi Roblox menyarankan Team Create untuk mengetes batas request.

Versi dan backup

Data store standar menyimpan riwayat untukmu. Penulisan pertama ke sebuah key di setiap jam UTC disimpan sebagai versi, dan penulisan berikutnya di jam itu saling menimpa. Versi lama kedaluwarsa 30 hari setelah penulisan yang lebih baru menggantikannya; versi terbaru tidak pernah kedaluwarsa. Ordered data store tidak menyimpan versi.

Untuk mengembalikan data satu pemain, buka Data Stores Manager (Creations, game kamu, Configure > Data Stores Manager), pilih key-nya, pilih versi sebelumnya dan klik Revert, yang butuh izin Edit. Lakukan selagi pemain offline, kalau tidak server yang memegang sesinya akan menyimpan salinannya di atas hasil revert. Dari script server, ListVersionsAsync dan GetVersionAsync menemukan dan membaca versi lama, yang lalu kamu tulis kembali sebagai value saat ini.

Sebelum mempublikasikan update yang mengubah cara data disimpan, Roblox menyarankan snapshot dengan Open Cloud Snapshot Data Stores API (satu per hari per game). Tanpa snapshot, penyimpanan bermasalah pada pukul 3:30 UTC menimpa semua yang ditulis ke key itu sejak 3:00, karena masih berada di versi per jam yang sama.

Error umum dan cara memperbaikinya

Error data store muncul di jendela Output Studio, dan module mencetak peringatan berisi teks error Roblox untuk setiap percobaan yang gagal. Panduan error script menjelaskan cara membaca Output secara umum.

StudioAccessToApisNotAllowed (error 403)

"Can't write to DataStore from Studio because API access is not enabled." Publikasikan place-nya, lalu nyalakan Enable Studio Access to API Services di File > Experience Settings > Security, di salinan tes.

DataStore request was added to queue

Server mengirim request lebih cepat dari jatahnya, atau terlalu sering menulis key yang sama, biasanya karena menyimpan setiap ada perubahan atau di dalam loop. Saat antrean berisi 30, request baru gagal dengan error 301 sampai 306. Simpan data di memori dan simpan secara berkala.

CantStoreValue (error 104), atau sebuah field kembali sebagai nil

Table-nya berisi sesuatu yang tidak bisa disimpan data store, seperti Instance, Vector3 atau Color3. Simpan nama, ID atau angka biasa sebagai gantinya dan bangun ulang objeknya saat load.

ValueTooLarge (error 105)

Satu key berisi lebih dari 4,194,304 karakter JSON. Ukur dengan #HttpService:JSONEncode(data), buang apa yang bisa dibangun ulang, atau pecah datanya ke beberapa key tetap.

Tidak ada error, tapi datanya tidak tersimpan

Cari peringatan Could not load dari module: setelah load gagal, module menolak menyimpan, memang begitu desainnya. Kalau tidak, value-nya mungkin diubah di LocalScript, yang tidak pernah sampai ke server, atau ada script lain yang menyimpan key yang sama.

Data reset setiap kali aku masuk lagi

Key-nya berubah di antara sesi (dibuat dari player.Name, atau STORE_NAME diedit), load-nya gagal dan kamu melihat nilai default, atau tidak ada yang me-require module sehingga tidak pernah berjalan. Cek Output dan pastikan Main me-require PlayerData.

Buat dengan RoCode

Kalau kamu tidak mau menyambungkan ini secara manual, RoCode bisa membuatnya di dalam place yang sedang kamu buka. RoCode adalah agen AI independen, bukan buatan Roblox, yang bekerja lewat plugin Roblox Studio: ia menulis Luau yang memakai DataStoreService seperti script lain dan membuat script di Explorer kamu. RoCode tidak pernah memanggil data store kamu sendiri, tapi dengan plugin 3.9 atau lebih baru ia bisa menekan Play untuk playtest singkat, tempat script kamu berjalan seperti di tes mana pun.

Kamu ketik

Tambahkan penyimpanan ke game-ku: simpan Coins, Level dan Inventory di module PlayerData dengan autosave dan penyimpanan saat shutdown, dan tampilkan Coins di leaderstats yang sudah aku punya.

RoCode mengerjakan
  • Bisa mencari leaderstats dan kode DataStore yang sudah ada dengan Search Scripts dan Read Script, supaya bisa memperluas yang kamu punya alih-alih menambah script save kedua. Di place yang besar, sebutkan nama script atau folder-nya di pesanmu.
  • Membuat ModuleScript dan Script yang me-require-nya dengan Create Script, atau mengubah yang sudah ada dengan Edit Script
  • Menjalankan Check Script pada setiap script yang ditulisnya: cek compile di dalam Studio dengan daftar peringatan singkat, bukan cek tipe atau test run
  • Mengirim perubahannya per batch, dan setiap batch adalah titik undo di Studio

Kamu tetap menyalakan Studio Access to API Services di salinan tes sendiri: RoCode tidak bisa mengubah pengaturan itu. Dengan plugin 3.9 atau lebih baru playtest singkatnya membaca error, dan dengan plugin 3.9.11 atau lebih baru ia bisa mengendalikan karakter tes untuk mengecek game-nya berjalan, tapi ia hanya mengecek yang dipilihnya untuk dites, jadi mainkan sendiri untuk mengecek bahwa Coins, Level dan Inventory tersimpan dan termuat. Kalau penyimpanan gagal di tes kamu, Check Output bisa membaca baris Server dari playtest yang kamu jalankan. Penyimpanan biasanya datang setelah core loop berjalan; membuat game Roblox dengan AI satu sistem per langkah menjelaskan urutan itu. Cara RoCode tersambung ke Studio.

Pertanyaan umum

Bagaimana cara mengaktifkan DataStore di Roblox Studio?

Publikasikan place-nya, buka File > Experience Settings > Security, nyalakan Enable Studio Access to API Services dan klik Save. Lakukan di game tes terpisah, karena Studio lalu memakai data store yang sama dengan server live game itu.

Apakah Roblox menyimpan data pemain secara otomatis?

Tidak. Tidak ada apa pun tentang pemain yang bertahan melewati sesi kecuali script server menyimpannya dengan DataStoreService, termasuk leaderstats.

Sebaiknya aku pakai ProfileStore atau DataStoreService langsung?

ProfileStore juga dibangun di atas data store, jadi pertanyaannya adalah apakah kamu mau session locking yang sudah ditulis dan dirawat untukmu. Untuk trading, item berbayar atau teleport yang sering, locking layak dipakai, dari library atau contoh referensi Roblox. Untuk game yang lebih kecil, module seperti ini lebih mudah dibaca dan diubah.

Bagaimana cara me-reset atau menghapus data pemain?

Di Data Stores Manager, cari key-nya dan pilih Mark for Deletion, yang bisa kamu batalkan selama masa cooldown, atau panggil RemoveAsync pada key itu dari script server. Lakukan selagi pemain offline, kalau tidak penyimpanan berikutnya dari server mereka menulis datanya kembali. Di salinan tes, mengubah STORE_NAME membuat semua orang mulai dari awal; jangan pernah lakukan itu di game live.

Sumber dan bacaan lanjutan

Cara kode ini dicek: setiap skrip di halaman ini lolos pemeriksa tipe strict Luau dengan definisi API Roblox (luau-lsp, 12 November 2026). Pemeriksaan tipe menangkap nama API yang salah ketik dan tipe yang keliru, bukan logika game, jadi uji dulu di Studio sebelum dipublikasikan.

Coba RoCode di game kamu sendiri.

Kredit gratis setiap hari, tanpa kartu. Pasang plugin-nya, jelaskan fiturnya, lalu cek hasilnya di Studio.