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
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.
- 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.
- Di salinan tes, buka File > Experience Settings dan masuk ke Security.
- 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
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.
| Tipe | Bisa disimpan? | Catatan |
|---|---|---|
| Number, string, boolean, buffer | Ya | String harus UTF-8 yang valid. Jangan simpan inf atau nan. |
| Table | Ya | Kalau 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, Color3 | Tidak | Penyimpanannya 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 | Fungsinya | Pakai 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
nilmembatalkan 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.
- Di Explorer, arahkan kursor ke ServerScriptService, klik + dan sisipkan ModuleScript. Ganti namanya jadi
PlayerDatadan ganti isinya dengan kode di bawah. - ModuleScript hanya berjalan saat ada script yang me-require-nya. Sisipkan Script di ServerScriptService bernama
Maindengan baris ini:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Script server lain me-require-nya dengan cara yang sama. - Edit
DEFAULTSdan tipeDatasesuai game kamu, dengan setiap field tetap berupa number, string, boolean atau table.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- 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
| Kapan | Kenapa |
|---|---|
| Setiap 180 detik selama pemain ada di server | Membatasi 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:
| Panggilan | Fungsinya |
|---|---|
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.Loaded | Berjalan 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.
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.
- 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) - Tekan Play. Jendela Output (di menu Window, atau di tab Script) menampilkan namamu dan 100 (pada jalan pertama), tanpa peringatan
Could not load. - Tekan Stop. Mengakhiri tes menutup server, dan module menyimpanmu sebelum server tutup.
- 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.
- 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. - 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 terjadi | Akibatnya | Pencegahan |
|---|---|---|
| Load gagal dan script tetap menyimpan | Nilai default menimpa progres asli: data terhapus total | Jangan pernah simpan pemain yang load-nya gagal |
Hanya menyimpan di PlayerRemoving | Crash atau server mati melewatkan penyimpanan | Autosave, plus BindToClose yang menunggu penyimpanannya |
Tanpa pcall atau tanpa retry | Satu request gagal menghentikan script atau membuang penyimpanan | pcall dengan beberapa retry berjarak |
| Menyimpan setiap ada perubahan | Request mengantre; saat antrean berisi 30, request baru dibuang | Simpan data di memori dan simpan secara berkala |
| Menyimpan sesuatu yang tidak bisa ditampung data store | Penyimpanannya error, atau value-nya kembali sebagai nil | Simpan number, string, boolean dan table berisi itu |
| Mengubah bentuk data tanpa migrasi | Save lama dimuat ke field yang salah | Versi skema dan langkah migrasi |
| Dua script menyimpan key yang sama | Setiap penyimpanan menimpa field milik yang lain | Satu module memiliki key itu |
| Dua server memegang pemain yang sama | Server dengan data lebih lama menyimpan terakhir dan menimpa progres yang lebih baru | Session 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.
| Opsi | Apa itu | Yang perlu diketahui |
|---|---|---|
| Module di panduan ini | Loading, cache, retry, autosave, penyimpanan saat shutdown dan versi skema, tanpa locking | Cukup pendek untuk dibaca seluruhnya dan diubah |
| Contoh player data and purchasing milik Roblox | Kode referensi dari Roblox dengan session locking, retry yang diproses berurutan per key, dan penanganan receipt pembelian | Roblox bilang kode ini belum terbukti dalam jangka panjang di game populer dan tidak boleh dipakai apa adanya tanpa pengetesan yang ekstensif |
| ProfileStore | Module komunitas gratis dan open source, penerus ProfileService, dibangun di sekitar session locking dan autosave | Bukan 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.
| Jenis request | Data store standar | Ordered data store |
|---|---|---|
Baca: GetAsync, pembacaan di UpdateAsync | 60 + 40 × pemain | 60 + 40 × pemain |
Tulis: SetAsync, IncrementAsync, penulisan di UpdateAsync | 60 + 40 × pemain | 30 + 5 × pemain |
Daftar: ListKeysAsync, atau GetSortedAsync untuk ordered store | 5 + 2 × pemain | 5 + 2 × pemain |
Hapus: RemoveAsync | 60 + 40 × pemain | 30 + 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 | Nilai |
|---|---|
| Nama data store, nama key, scope | Masing-masing 50 karakter |
| Value yang disimpan di satu key | 4,194,304 karakter, diukur sebagai JSON |
| Pembacaan dari satu key, di semua server | 25 MB per menit |
| Penulisan ke satu key, di semua server | 4 MB per menit, setiap request dibulatkan ke atas ke KB berikutnya |
| Request yang menunggu | 30 per antrean; lebih dari itu, request gagal dengan error 301 sampai 306 |
| Penyimpanan untuk seluruh game | 500 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.
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.
- 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
- Roblox Creator Docs: Data stores (dalam bahasa Inggris). akses Studio, GetAsync, SetAsync, UpdateAsync, set vs update
- Roblox Creator Docs: Best practices for data stores (dalam bahasa Inggris). satu key per pemain, buffer di memori, retry dengan backoff, module pihak ketiga
- Roblox Creator Docs: Data store error codes and limits (dalam bahasa Inggris). kode error, batas request server dan game, batas ukuran, throughput dan penyimpanan
- Roblox Creator Docs: Versioning, listing and caching (dalam bahasa Inggris). versi per jam, snapshot, cache 4 detik, yang bisa disimpan
- Roblox Creator Docs: Implement player data and purchasing systems (dalam bahasa Inggris). contoh referensi, session locking, load yang gagal, autosave 180 detik
- Roblox Creator Docs: Data Stores Manager (dalam bahasa Inggris). melihat key, mengembalikan versi, menghapus data
- Roblox Engine API: DataModel:BindToClose (dalam bahasa Inggris). jendela shutdown 30 detik
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.