Ringkasnya
Gunakan DataStoreService daripada Script pelayan: muatkan data pemain dengan GetAsync apabila dia masuk, simpan dalam jadual semasa dia bermain, dan simpan dengan UpdateAsync mengikut pemasa, semasa keluar (PlayerRemoving) dan semasa pelayan ditutup (game:BindToClose). Balut setiap panggilan dalam pcall dan ulang yang gagal beberapa kali.
- Untuk menguji dalam Studio, terbitkan place dan hidupkan File > Experience Settings > Security > Enable Studio Access to API Services dalam game ujian berasingan: Studio menggunakan data yang sama seperti pelayan live.
- Jika data pemain gagal dimuatkan, jangan sekali-kali simpan pemain itu. Menyimpan nilai lalai akan menimpa kemajuan sebenarnya.
- Simpan satu jadual bagi setiap pemain di bawah satu kunci, contohnya
User_12345, dan simpan mengikut pemasa, bukan pada setiap perubahan. - Untuk dagangan item atau item berbayar, tambah session locking supaya dua pelayan tidak boleh menyimpan pemain yang sama.
Di halaman ini
Sebelum bermula: hidupkan akses Studio dalam salinan ujian
Game yang dijalankan dalam Studio tidak boleh mengakses data store sehingga anda membenarkannya. Kebenaran ini ada perangkap yang diberi amaran oleh dokumentasi Roblox: Studio kemudian membaca dan menulis data store yang sama seperti game live, jadi ujian yang mengosongkan syiling anda dalam Studio turut mengosongkannya dalam game live, dan kesilapan dalam kod ujian boleh merosakkan kunci pemain sebenar.
- Buat salinan ujian. Simpan place ke fail, buka salinannya, pilih File > Publish to Roblox As dan klik Create new game. Jangan tambahnya sebagai place di dalam game live: semua place dalam satu game berkongsi data store yang sama.
- Dalam salinan ujian, buka File > Experience Settings dan pergi ke Security.
- Hidupkan Enable Studio Access to API Services dan klik Save.
Panggilan data store hanya berfungsi dalam Script pelayan; LocalScript yang mencubanya mendapat ralat, jadi client tidak boleh menulis data yang disimpan. Apabila butang perlu mengubahnya, client meminta pelayan melalui RemoteEvent, dan pelayan yang memutuskan (lihat panduan RemoteEvents).
Cara data store menyimpan data pemain
Data store ialah set kunci dan nilai bernama pada pelayan Roblox, dikongsi oleh semua pelayan dan semua place dalam game anda. DataStoreService:GetDataStore("PlayerData") memulangkan satu store sebegini.
Cadangan Roblox boleh diringkaskan kepada peraturan satu store untuk data pemain, satu kunci bagi setiap pemain, satu jadual dalam setiap kunci. Bina kunci daripada UserId pemain, contohnya User_12345, dan jangan sekali-kali daripada nama yang boleh ditukarnya. Corak tetap User_{UserId} juga membolehkan pemprosesan automatik Roblox untuk hak untuk dilupakan mencari data pemain, jika anda menyediakannya.
| Jenis | Boleh disimpan? | Nota |
|---|---|---|
| Nombor, string, boolean, buffer | Ya | String mesti UTF-8 yang sah. Jangan simpan inf atau nan. |
| Jadual | Ya | Jika semua di dalamnya juga boleh disimpan. Jadual yang kunci berangkanya tidak bermula dari 1 (jadi panjangnya 0) dikembalikan dengan kunci itu sebagai string. |
Instance, Vector3, CFrame, Color3 | Tidak | Simpanan memberi ralat atau menulis nil. Simpan nama item, atau kedudukan sebagai tiga nombor. |
Setiap permintaan ialah panggilan web yang boleh gagal, mengambil masa dan menggunakan bajet per minit. Sebab itu sistem simpanan yang boleh dipercayai membaca data sekali semasa pemain masuk, menyimpannya dalam jadual pelayan semasa dia bermain, dan menulisnya semula dari semasa ke semasa.
GetAsync, SetAsync atau UpdateAsync: yang mana satu
| Kaedah | Apa yang dibuat | Untuk apa |
|---|---|---|
GetAsync(key) | Membaca nilai. Hasilnya di-cache pada pelayan ini selama 4 saat. | Memuatkan data pemain |
SetAsync(key, value) | Menimpa nilai tanpa membacanya. Satu tulisan. | Kunci baharu atau nilai yang tidak bergantung pada nilai lama |
UpdateAsync(key, callback) | Membaca nilai terkini, menghantarnya kepada fungsi anda dan menulis apa yang dipulangkannya. Satu bacaan dan satu tulisan. | Menyimpan data pemain dan mana-mana kunci yang boleh ditulis oleh beberapa pelayan |
IncrementAsync(key, delta) | Menambah integer kepada integer yang disimpan. | Pembilang |
RemoveAsync(key) | Memadam kunci dan memulangkan nilai lama. Versi terdahulu masih boleh disenaraikan dan dibaca. | Memadam data pemain |
SetAsync menulis secara buta: jika dua pelayan menyimpan kunci yang sama hampir serentak, tulisan terakhir menang, apa pun isinya. UpdateAsync membaca nilai semasa dahulu, dan jika pelayan lain menulis di antaranya, Roblox menjalankan fungsi anda semula dengan nilai baharu. Roblox menasihatkannya setiap kali tulisan bergantung pada nilai semasa atau kunci boleh ditulis oleh beberapa pelayan, dan itulah data pemain. Fungsi itu ada tiga peraturan:
- Ia tidak boleh yield: tiada
task.wait()atau panggilan store lain di dalamnya. - Ia mungkin berjalan lebih daripada sekali, jadi ia hanya patut mengira nilai baharu dan tidak sekali-kali memberi item atau mencetuskan event.
- Memulangkan
nilmembatalkan tulisan. Modul menggunakan ini supaya tidak menimpa data yang disimpan oleh versi game yang lebih baharu.
Langkah 1: cipta modul PlayerData
ModuleScript ini satu-satunya kod yang berkomunikasi dengan data store. Ia memuatkan data pemain semasa masuk, menyimpannya dalam memori, menyimpan setiap 180 saat, semasa keluar dan semasa pelayan ditutup, dan enggan menyimpan pemain yang datanya gagal dimuatkan.
- Dalam Explorer, halakan tetikus pada ServerScriptService, klik + dan masukkan ModuleScript. Namakan semula kepada
PlayerDatadan gantikan kandungannya dengan kod di bawah. - ModuleScript hanya berjalan apabila ada skrip yang memuatkannya (require). Masukkan Script bernama
Mainke dalam ServerScriptService dengan baris ini:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Skrip pelayan lain memuatkannya dengan cara yang sama. - Ubah
DEFAULTSdan jenisDatamengikut game anda, dengan setiap medan kekal sebagai nombor, string, boolean atau jadual.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: memuatkan data pemain semasa masuk, menyimpannya dalam memori
-- dan menyimpannya mengikut pemasa, semasa keluar dan semasa pelayan ditutup.
-- Skrip pelayan lain membaca dan mengubahnya melalui PlayerData.Get(player).
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- naikkan apabila bentuk data berubah, dan tambah langkah dalam migrate()
local AUTOSAVE_SECONDS = 180
-- Dalam Studio panggilan yang gagal terus berputus asa, jadi ujian tanpa akses store berjalan pantas
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- digandakan selepas setiap kegagalan: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- Apa yang dimiliki oleh pemain yang benar-benar baharu pada permulaan
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false jika pemuatan gagal: data lalai tidak boleh menggantikan kemajuan sebenar
}
-- Dipanggil di dalam setiap pcall di bawah, jadi place yang belum diterbitkan
-- (tanpa akses store) tetap memuatkan pemain dengan data lalai
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- simpanan yang masih berjalan, mengikut kunci
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Berlaku dengan pemain apabila datanya sedia. Ambil jadual melalui PlayerData.Get(player):
-- jadual yang dihantar melalui BindableEvent tiba sebagai salinan, dan 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 baharu, supaya pemain tidak pernah berkongsi satu jadual Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Menukar data yang disimpan kepada skema semasa. Memulangkan nil jika ia tidak selamat digunakan.
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 baharu: jangan muatkan atau timpa di sini
end
-- Satu langkah bagi setiap perubahan skema, dari lama ke baharu
if version < 2 then
-- Contoh: dalam versi 1 mata wang dipanggil Gold. Salin hanya jika Coins tiada,
-- supaya data lama yang sudah ada Coins tetapi tiada SchemaVersion mengekalkan nilainya.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Tambah medan yang muncul selepas simpanan terakhir pemain, dan gantikan nilai berjenis salah
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 store dalam pcall. Jika gagal, ia menunggu dan cuba lagi, setiap kali menggandakan
-- penantian dan menambah sedikit rawak, supaya pelayan tidak semua mencuba serentak.
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 -- memulangkan nil membatalkan tulisan
end
-- Tulis seluruh jadual semasa, ditanda 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()
-- Mula pada saat rawak dalam selang, supaya pelayan tidak semua menyimpan serentak
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
-- Jika pemain baru keluar dari pelayan ini dan kembali, biarkan simpanan terakhir selesai dahulu
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 semasa memuatkan: tiada yang berubah, tiada apa untuk 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 boleh membaca ini dan memberi amaran kepada 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 gelung autosave, dan panggilan kedua tidak berbuat apa-apa
save(session)
end
-- Jadual data live pemain, atau nil sehingga ia dimuatkan. Ubahnya hanya daripada skrip pelayan.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True apabila data pemain telah dimuatkan dan akan disimpan. Semak sebelum sebarang jualan.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Menyimpan sekarang, tanpa menunggu pemasa, untuk saat penting seperti pembelian.
-- Melakukan yield dan memulangkan true apabila simpanan berjaya.
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 modul ini dimuatkan kali pertama
end
game:BindToClose(function()
-- Pelayan memberi fungsi ini 30 saat, jadi kita simpan semua orang serentak
for player in sessions do
task.spawn(endSession, player)
end
-- Kemudian tunggu semua simpanan yang masih berjalan, termasuk yang dimulakan dalam PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Selepas game dilancarkan, jangan ubah STORE_NAME dan corak kunci User_. Mengubah salah satunya akan mengarahkan modul ke kunci kosong, dan setiap pemain akan bermula semula daripada nilai lalai.
Cara modul melindungi data
Nilai lalai dan versi skema
Pemain baharu mendapat salinan baharu DEFAULTS. Ia mesti salinan: jika semua pemain berkongsi satu jadual Inventory, item yang ditambah kepada seorang akan muncul pada semua orang.
Setiap jadual yang disimpan membawa SchemaVersion. Menambah medan tidak memerlukan versi baharu, kerana migrate mengisi medan yang hilang daripada nilai lalai. Menamakan semula atau menyusun semula memerlukannya: naikkan SCHEMA_VERSION dan tambah langkah, seperti contoh yang menamakan semula Gold kepada Coins (dalam game baharu, padamkannya dan mulakan dengan 1). Data dengan versi lebih tinggi daripada pelayan datang daripada keluaran lebih baharu yang masih dilancarkan, jadi pelayan lama tidak menyentuhnya.
Pemuatan yang gagal tidak pernah disimpan
Peraturan ini melindungi daripada pemadaman penuh. Jika semua cubaan memuatkan gagal, pemain bermain dengan data lalai, tetapi canSave ialah false, jadi nilai itu tidak pernah menimpa kemajuan sebenarnya. Modul juga menetapkan atribut DataLoaded kepada false, dan langkah 3 menggunakannya untuk memberitahu pemain. Contoh rujukan Roblox mengendalikan pemuatan gagal dengan cara yang sama dan mencadangkannya sebagai ganti kick; jika anda lebih suka kick, panggil player:Kick() dengan mesej di tempat modul mencetak amaran.
Cubaan semula dengan jeda yang bertambah
withRetries membalut setiap panggilan dalam pcall. Selepas kegagalan ia menunggu 1, kemudian 2, kemudian 4 saat, setiap kali ditambah secara rawak sehingga separuh masa itu, dan berhenti selepas empat cubaan (dalam Studio selepas satu, supaya place tanpa akses store bermula serta-merta). Unsur rawak menjarakkan cubaan semula banyak pelayan selepas gangguan, dan had itu mengekalkan penantian dalam lingkungan kira-kira 10 saat, dalam 30 saat yang diberi kepada pelayan untuk ditutup. Oleh kerana setiap simpanan menulis seluruh jadual live melalui UpdateAsync, cubaan semula yang selesai lewat tidak boleh mengembalikan data lama.
Bila modul menyimpan
| Bila | Kenapa |
|---|---|
| Setiap 180 saat semasa pemain berada di pelayan | Mengehadkan kerugian jika ranap. Simpanan pertama jatuh pada saat rawak dalam selang, supaya pelayan tidak semua menyimpan serentak. Contoh rujukan Roblox juga menggunakan 180 saat. |
Apabila pemain keluar (PlayerRemoving) | Simpanan akhir biasa. Sesi dibuang dahulu, jadi autosave berhenti. |
Apabila pelayan ditutup (game:BindToClose) | Semua yang masih di pelayan disimpan serentak, dan fungsi menunggu setiap simpanan yang sedang berjalan. Roblox memberinya 30 saat. |
Atas permintaan, melalui PlayerData.SaveNow(player) | Selepas sesuatu yang tidak boleh hilang, contohnya pembelian. |
Jika pemain masuk semula ke pelayan yang sama semasa simpanan akhirnya masih berjalan, pemuatan baharu menunggu simpanan itu selesai, jadi ia tidak boleh membaca nilai lama.
Langkah 2: baca dan ubah data daripada skrip lain
Semua skrip pelayan yang memuatkan modul bekerja dengan jadual yang sama:
| Panggilan | Apa yang dibuat |
|---|---|
PlayerData.Get(player) | Jadual data live pemain, atau nil sehingga ia dimuatkan. Ubah medan secara terus, contohnya data.Coins += 10, dan simpanan seterusnya akan mengambilnya. |
PlayerData.Loaded | Berlaku dengan pemain apabila datanya sedia, termasuk selepas pemuatan gagal. Ia hanya menghantar pemain, kerana jadual yang dihantar melalui BindableEvent tiba sebagai salinan. |
PlayerData.CanSave(player) | false jika pemuatan gagal. Semak sebelum sebarang jualan: pembelian yang tidak boleh disimpan akan hilang apabila pemain keluar. |
PlayerData.SaveNow(player) | Menyimpan serta-merta dan memulangkan true jika berjaya. Melakukan yield. |
Modul ialah satu-satunya tempat data yang disimpan berada, dan leaderstats hanya paparan: binanya seperti dalam panduan leaderboard, isikannya daripada PlayerData.Get(player) dalam pengendali Loaded, dan kemas kini kedua-duanya apabila nilai berubah. Jangan sekali-kali membaca nilai yang disimpan semula daripada leaderstats, dan jangan sekali-kali biarkan skrip kedua menyimpan kunci yang sama.
Skrip yang memuatkan modul selepas pemain masuk terlepas Loaded untuk mereka. Sambungkan pengendali, kemudian gelungkan juga Players:GetPlayers() dan kendalikan semua yang PlayerData.Get(player)nya sudah memulangkan jadual.
Menggantikan skrip simpanan lama, contohnya daripada panduan leaderboard? Nilainya kekal dalam store dan kuncinya sendiri, jadi modul ini akan memulakan semua orang daripada nilai lalai. Sebelum pelancaran, sama ada arahkan STORE_NAME dan awalan User_ kepada yang lama (migrate menganggap data tanpa SchemaVersion sebagai versi 1 dan mengisi medan yang hilang), atau pindahkan nilai lama, kemudian padam skrip lama.
Client tidak pernah mengubah data ini secara terus. Butang kedai mencetuskan RemoteEvent; pelayan menyemak CanSave, membandingkan harga dengan Coins pemain, mengubah jadual dan memanggil SaveNow. Panduan GUI kedai membina pembelian sebegini di pihak pelayan.
Contoh siap untuk menambah medan ada dalam panduan simulator klik: ia menambah PowerLevel dan Rebirths ke DEFAULTS dan jenis Data, kemudian mengubahnya dalam jadual yang dipulangkan oleh PlayerData.Get. migrate memberi medan baharu kepada pemain dengan simpanan lama.
Langkah 3: beritahu pemain bahawa datanya gagal dimuatkan
Pemain yang datanya gagal dimuatkan perlu tahu bahawa sesi ini tidak akan disimpan, supaya dia masuk semula dan bukan bermain sia-sia. LocalScript ini memerhati atribut DataLoaded dan menunjukkan sepanduk apabila ia bernilai 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
-- Pelayan menetapkan DataLoaded sekali, selepas cubaan memuatkan data pemain ini
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Langkah 4: uji simpanan dalam Studio
Lakukan ini dalam salinan ujian dengan akses Studio dihidupkan.
- Beri diri anda sesuatu untuk disimpan. Di bawah baris require dalam
Main, tambah: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. Tetingkap Output (dalam menu Window atau pada tab Script) menunjukkan nama anda dan 100 (pada larian pertama), tanpa amaran
Could not load. - Tekan Stop. Menamatkan ujian menutup pelayan, dan modul menyimpan anda sebelum ditutup.
- Tekan Play sekali lagi. Output sepatutnya menunjukkan 200, 100 lebih daripada kali lepas. Jika ia menunjukkan nombor yang sama lagi, simpanan gagal: baca amaran di atasnya.
- Uji laluan ralat. Matikan akses Studio dan tekan Play. Selepas beberapa saat cubaan semula, Output menunjukkan
Could not load User_...dan 100, dan sepanduk daripada langkah 3 muncul. Hentikan ujian, hidupkan akses semula dan tekan Play: Output menunjukkan 300, 200 yang disimpan ditambah 100, kerana sesi yang gagal tidak pernah menimpa data anda. - Padam baris ujian daripada
Main.
Kenapa data pemain hilang
Berikut cara biasa sistem simpanan kehilangan kemajuan. Modul menutup empat baris pertama dan baris tentang skema dalam kod; yang lain bergantung pada apa dan bagaimana anda menyimpan, dan baris terakhir memerlukan session locking.
| Apa yang berlaku | Hasil | Cara mencegah |
|---|---|---|
| Pemuatan gagal, tetapi skrip tetap menyimpan | Nilai lalai menimpa kemajuan sebenar: pemadaman penuh | Jangan sekali-kali simpan pemain yang pemuatannya gagal |
Menyimpan hanya dalam PlayerRemoving | Pelayan ranap atau ditutup melangkau simpanan | Autosave ditambah BindToClose yang menunggu simpanannya |
Tiada pcall atau tiada cubaan semula | Satu permintaan gagal menghentikan skrip atau menghilangkan simpanan | pcall dengan beberapa cubaan semula yang dijarakkan |
| Menyimpan pada setiap perubahan | Permintaan beratur; apabila ada 30 dalam baris gilir, yang baharu dibuang | Simpan data dalam memori dan simpan mengikut pemasa |
| Menyimpan sesuatu yang store tidak boleh simpan | Simpanan memberi ralat, atau nilai kembali sebagai nil | Simpan nombor, string, boolean dan jadual daripadanya |
| Mengubah bentuk data tanpa migrasi | Simpanan lama dimuatkan ke medan yang salah | Versi skema dan langkah migrasi |
| Dua skrip menyimpan kunci yang sama | Setiap simpanan menimpa medan yang lain | Satu modul memiliki kunci |
| Dua pelayan memegang pemain yang sama | Pelayan dengan data lama menyimpan terakhir dan menimpa kemajuan baharu | Session locking |
Session locking, "lock lost" dan ProfileStore
Pemain bersambung ke satu pelayan pada satu masa, tetapi simpanan akhir pelayan lama mungkin masih berjalan apabila dia masuk ke pelayan baharu: cubaan semula yang perlahan, teleport atau masuk semula dengan pantas. Jika pelayan baharu memuatkan data dahulu, ia akan mendapat data lama, dan pelayan yang menyimpan terakhir akan menang. Dokumentasi Roblox mencatatkan bahawa dalam game dengan dagangan, jurang ini punca biasa duplikasi item.
Session locking menutup jurang ini. Apabila pelayan memuatkan kunci pemain, dalam panggilan UpdateAsync yang sama ia menulis ID lock-nya ke dalam metadata kunci. Mana-mana pelayan lain yang menjumpai lock yang belum tamat tempoh, yang bukan dipasang olehnya, tidak akan memuatkan atau menyimpan kunci itu. Pemiliknya memperbaharui lock pada setiap autosave dan melepaskannya dalam simpanan akhir; jika ia berhenti memperbaharuinya, lock tamat tempoh, dan pelayan lain boleh mengambilnya.
Apa maksud "lock lost"
Dalam sistem dengan session locking, pelayan kehilangan lock apabila kunci pemain kini dimiliki oleh pelayan lain, kerana lock tamat tempoh atau diambil alih. Salinannya mungkin lapuk, jadi ia perlu berhenti menyimpan pemain itu; tindak balas biasa: kick dia dengan mesej supaya dia bersambung semula. Jika anda melihat "lock lost" sebagai pemain, itu mesej sistem simpanan game itu sendiri, dan hanya pembangunnya boleh menerangkannya.
Adakah anda memerlukannya?
Modul dalam panduan ini tidak mengunci sesi. Tanpa lock, kes paling teruk yang sebenar ialah: dalam perlumbaan yang jarang berlaku, pemain kehilangan apa yang diperolehnya pada pelayan lama selepas simpanan terakhirnya yang berjaya. Tambah lock apabila duplikasi atau kehilangan merugikan pemain sesuatu yang sebenar: dagangan, developer products, item jarang atau teleport yang kerap.
| Pilihan | Apa itu | Apa yang perlu diketahui |
|---|---|---|
| Modul dalam panduan ini | Pemuatan, cache dalam memori, cubaan semula, autosave, simpanan semasa ditutup dan versi skema, tanpa lock | Cukup pendek untuk dibaca sepenuhnya dan diubah |
| Contoh Roblox untuk data pemain dan pembelian | Kod rujukan daripada Roblox dengan session locking, cubaan semula mengikut urutan bagi setiap kunci dan pengendalian resit pembelian | Roblox mengatakan ia belum teruji dalam game popular dan tidak patut digunakan sebagaimana adanya tanpa ujian yang meluas |
| ProfileStore | Modul komuniti percuma bersumber terbuka, pengganti ProfileService, dibina di sekitar session locking dan autosave | Bukan daripada Roblox. Memindahkan game sedia ada kepadanya memerlukan migrasi data yang sudah disimpan |
Untuk mana-mana modul pihak ketiga, Roblox menasihatkan anda menyemak siapa pemiliknya, sama ada ia diselenggara, dan bagaimana anda akan mencapai data anda tanpanya. Dokumentasi yang sama menyebut DataStore2 sebagai pustaka lapuk yang tidak patut digunakan oleh game baharu.
Had data store
Ini had daripada dokumentasi Roblox pada 30 September 2026. Roblox menyemaknya semula, jadi semak halaman kod ralat dan had (dalam bahasa Inggeris) sebelum bergantung pada nombor yang tepat.
| Jenis permintaan | Store biasa | Store tersusun |
|---|---|---|
Baca: GetAsync, bacaan dalam UpdateAsync | 60 + 40 × pemain | 60 + 40 × pemain |
Tulis: SetAsync, IncrementAsync, tulisan dalam UpdateAsync | 60 + 40 × pemain | 30 + 5 × pemain |
Senarai: ListKeysAsync, atau GetSortedAsync untuk store tersusun | 5 + 2 × pemain | 5 + 2 × pemain |
Padam: RemoveAsync | 60 + 40 × pemain | 30 + 5 × pemain |
Dengan 20 pemain, pelayan boleh membuat 860 tulisan biasa seminit; autosave modul ini menggunakan kira-kira 7 daripadanya, ditambah satu bagi setiap pemain yang keluar. Yang menghabiskan bajet ialah menyimpan pada setiap syiling yang dikutip. Bajet kedua berlaku untuk seluruh game dan dikongsi dengan Open Cloud: 300 bacaan seminit ditambah 40 bagi setiap pemain dalam talian, dan 300 tulisan ditambah 20 bagi setiap pemain.
| Had | Nilai |
|---|---|
| Nama store, nama kunci, scope | 50 aksara setiap satu |
| Nilai dalam satu kunci | 4,194,304 aksara dalam bentuk JSON |
| Bacaan satu kunci daripada semua pelayan | 25 MB seminit |
| Tulisan ke satu kunci daripada semua pelayan | 4 MB seminit, setiap permintaan dibundarkan ke atas kepada KB seterusnya |
| Permintaan menunggu | 30 bagi setiap baris gilir; selebihnya gagal dengan ralat 301-306 |
| Storan untuk seluruh game | 500 MB ditambah 1 MB bagi setiap pengguna sepanjang masa |
Ukur saiz data pemain dengan #HttpService:JSONEncode(data), dan lihat baki bajet pelayan live dengan DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Panggilan GetAsync yang dijawab oleh cache 4 saat tidak dikira. Mod Run dalam Studio ada had sendiri, mungkin lebih rendah, jadi untuk menguji had permintaan Roblox menasihatkan Team Create.
Versi dan sandaran
Data store biasa menyimpan sejarah untuk anda. Tulisan pertama ke kunci dalam setiap jam UTC disimpan sebagai versi, dan tulisan seterusnya dalam jam itu saling menimpa. Versi lama tamat tempoh 30 hari selepas ia digantikan oleh tulisan yang lebih baharu; yang terkini tidak pernah tamat tempoh. Store tersusun tidak menyimpan versi.
Untuk mengembalikan seorang pemain, buka Data Stores Manager (Creations, game anda, Configure > Data Stores Manager), pilih kuncinya, pilih versi lebih awal dan klik Revert; ini memerlukan kebenaran Edit. Lakukan semasa pemain tidak dalam talian, jika tidak pelayan dengan sesinya akan menyimpan salinannya di atas pemulihan itu. Daripada skrip pelayan, ListVersionsAsync dan GetVersionAsync mencari dan membaca versi lama, yang kemudian anda tulis semula sebagai nilai semasa.
Sebelum menerbitkan kemas kini yang mengubah cara data disimpan, Roblox menasihatkan mengambil snapshot melalui Open Cloud Snapshot Data Stores API (satu sehari bagi setiap game). Tanpanya, simpanan yang salah pada 3:30 UTC akan menimpa semua yang ditulis ke kunci itu sejak 3:00, kerana ia jatuh dalam versi jam yang sama.
Ralat biasa dan cara membaikinya
Ralat data store muncul dalam tetingkap Output Studio, dan modul mencetak amaran dengan teks ralat Roblox pada setiap cubaan yang gagal. Panduan ralat skrip menerangkan cara membaca Output secara umum.
StudioAccessToApisNotAllowed (ralat 403)
"Can't write to DataStore from Studio because API access is not enabled." Terbitkan place, kemudian hidupkan Enable Studio Access to API Services dalam File > Experience Settings > Security, dalam salinan ujian.
DataStore request was added to queue
Pelayan menghantar permintaan lebih pantas daripada yang dibenarkan oleh bajet, atau menulis satu kunci terlalu kerap, biasanya kerana menyimpan pada setiap perubahan atau dalam gelung. Apabila ada 30 permintaan dalam baris gilir, yang baharu gagal dengan ralat 301-306. Simpan data dalam memori dan simpan mengikut pemasa.
CantStoreValue (ralat 104), atau medan kembali sebagai nil
Jadual mengandungi sesuatu yang store tidak boleh simpan, contohnya Instance, Vector3 atau Color3. Simpan nama, ID atau nombor ringkas sebagai ganti, dan bina semula objek semasa memuatkan.
ValueTooLarge (ralat 105)
Satu kunci menyimpan lebih daripada 4,194,304 aksara JSON. Ukur dengan #HttpService:JSONEncode(data), buang apa yang boleh dibina semula, atau bahagikan data kepada beberapa kunci tetap.
Tiada ralat, tetapi data tidak disimpan
Cari amaran modul Could not load: selepas pemuatan gagal ia sengaja enggan menyimpan. Jika tidak, nilai itu kemungkinan besar diubah dalam LocalScript, yang tidak pernah sampai ke pelayan, atau skrip lain menyimpan kunci yang sama.
Data diset semula setiap kali masuk semula
Kunci berubah antara sesi (dibina daripada player.Name, atau anda mengubah STORE_NAME), pemuatan gagal dan anda melihat nilai lalai, atau tiada siapa memuatkan modul, jadi ia tidak berjalan langsung. Semak Output dan pastikan Main memuatkan PlayerData.
Bina ini dengan RoCode
Jika anda tidak mahu membina ini secara manual, RoCode boleh melakukannya terus dalam place yang anda buka. Ia ejen AI bebas, bukan daripada Roblox, yang berfungsi melalui plugin untuk Roblox Studio: ia menulis Luau yang menggunakan DataStoreService seperti mana-mana skrip, dan mencipta skrip dalam Explorer anda. Ia sendiri tidak pernah mengakses data store anda, tetapi dengan plugin 3.9 atau lebih baharu ia boleh menekan Play untuk playtest pendek, di mana skrip anda berjalan seperti dalam mana-mana ujian.
Tambah simpanan pada game saya: simpan Coins, Level dan Inventory dalam modul PlayerData dengan autosave dan simpanan semasa pelayan ditutup, dan tunjukkan Coins dalam leaderstats yang sudah saya ada.
- Boleh mencari leaderstats dan kod DataStore sedia ada dengan Search Scripts dan Read Script, untuk mengembangkan apa yang anda ada dan bukan menambah skrip simpanan kedua. Dalam place yang besar, sebut nama skrip atau folder dalam mesej.
- Mencipta ModuleScript dan Script yang memuatkannya dengan Create Script, atau mengubah yang sedia ada dengan Edit Script
- Menjalankan Check Script untuk setiap skrip yang ditulis: semakan kompilasi di dalam Studio dengan senarai amaran pendek, bukan semakan jenis dan bukan larian ujian
- Menghantar perubahan dalam kumpulan, dan setiap kumpulan ialah titik undo dalam Studio
Anda tetap perlu menghidupkan Studio Access to API Services dalam salinan ujian sendiri: RoCode tidak boleh mengubah tetapan ini. Dengan plugin 3.9 atau lebih baharu, playtest pendeknya membaca ralat, dan dengan plugin 3.9.11 atau lebih baharu ia boleh mengawal watak ujian untuk menyemak bahawa game berfungsi, tetapi ia hanya menyemak apa yang ia sendiri putuskan untuk disemak, jadi main sendiri dan pastikan Coins, Level dan Inventory disimpan dan dimuatkan. Jika simpanan gagal dalam ujian anda, Check Output boleh membaca baris Server daripada playtest yang anda jalankan. Simpanan biasanya ditambah apabila kitaran utama game sudah berfungsi; membuat game Roblox dengan AI satu sistem pada satu masa menunjukkan urutan ini. Cara RoCode bersambung dengan Studio.
Soalan lazim
Bagaimana menghidupkan DataStore dalam Roblox Studio?
Terbitkan place, buka File > Experience Settings > Security, hidupkan Enable Studio Access to API Services dan klik Save. Lakukan dalam game ujian berasingan, kerana Studio kemudian menggunakan data store yang sama seperti pelayan live game itu.
Adakah Roblox menyimpan data pemain secara automatik?
Tidak. Tiada apa-apa tentang pemain disimpan selepas sesi melainkan skrip pelayan menyimpannya melalui DataStoreService, termasuk leaderstats.
Yang mana patut dipilih: ProfileStore atau DataStoreService secara terus?
ProfileStore juga dibina di atas data store, jadi persoalannya ialah sama ada anda mahu session locking ditulis dan diselenggara untuk anda. Untuk dagangan, item berbayar atau teleport yang kerap, lock berbaloi, daripada pustaka atau contoh rujukan Roblox. Untuk game yang lebih kecil, modul seperti ini lebih mudah dibaca dan diubah.
Bagaimana set semula atau padam data pemain?
Dalam Data Stores Manager, cari kunci dan pilih Mark for Deletion, yang boleh dibatalkan dalam tempoh menunggu, atau panggil RemoveAsync untuk kunci itu daripada skrip pelayan. Lakukan semasa pemain tidak dalam talian, jika tidak simpanan seterusnya daripada pelayannya akan menulis data semula. Dalam salinan ujian, menukar STORE_NAME memulakan semua orang dari kosong; jangan sekali-kali lakukannya dalam game live.
Sumber dan bacaan lanjut
- Roblox Creator Docs: Data stores (dalam bahasa Inggeris). akses Studio, GetAsync, SetAsync, UpdateAsync, set dan update
- Roblox Creator Docs: Best practices for data stores (dalam bahasa Inggeris). satu kunci bagi setiap pemain, data dalam memori, cubaan semula dengan jeda bertambah, modul pihak ketiga
- Roblox Creator Docs: Data store error codes and limits (dalam bahasa Inggeris). kod ralat, had permintaan pelayan dan game, had saiz, daya pemprosesan dan storan
- Roblox Creator Docs: Versioning, listing and caching (dalam bahasa Inggeris). versi setiap jam, snapshot, cache 4 saat, apa yang boleh disimpan
- Roblox Creator Docs: Implement player data and purchasing systems (dalam bahasa Inggeris). contoh rujukan, session locking, pemuatan gagal, autosave setiap 180 saat
- Roblox Creator Docs: Data Stores Manager (dalam bahasa Inggeris). melihat kunci, mengembalikan versi, memadam data
- Roblox Engine API: DataModel:BindToClose (dalam bahasa Inggeris). 30 saat untuk ditutup
Cara kod disemak: setiap skrip di halaman ini lulus semakan jenis Luau yang ketat dengan definisi API Roblox (luau-lsp, 20 November 2026). Semakan jenis mengesan kesilapan nama API dan jenis yang salah, tetapi bukan kesilapan logik permainan, jadi uji semuanya dalam Studio sebelum anda menerbitkannya.