Tutorial · Data pemain

Cara simpan data pemain dalam Roblox Studio dengan DataStore

Roblox tidak mengingati apa-apa tentang pemain antara sesi melainkan skrip pelayan menyimpannya. Dalam panduan ini anda akan membina modul PlayerData yang memuatkan, menyimpan dalam memori dan menyimpan data setiap pemain melalui DataStoreService, kemudian memahami cara menguji, hadnya dan bagaimana data yang disimpan boleh hilang.

Dikemas kini 20 November 202616 minit bacaanDitulis oleh

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
  1. Akses Studio
  2. Cara DataStore berfungsi
  3. GetAsync dan UpdateAsync
  4. 1. Modul PlayerData
  5. Cara modul berfungsi
  6. 2. Menggunakan data
  7. 3. Amaran
  8. 4. Ujian dalam Studio
  9. Kenapa data hilang
  10. Session locking
  11. Had
  12. Versi dan sandaran
  13. Common errors
  14. With RoCode
  15. Soalan lazim
  16. Sumber dan bacaan lanjut

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.

  1. 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.
  2. Dalam salinan ujian, buka File > Experience Settings dan pergi ke Security.
  3. 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

IlustrasiUjian daripada langkah 4 panduan ini dalam versi dipercepatkan: Play, Stop menyimpan sesi ke dalam data store, Play semula memuatkannya, jadi Output menunjukkan 200.

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.

Apa yang boleh disimpan dalam data store
JenisBoleh disimpan?Nota
Nombor, string, boolean, bufferYaString mesti UTF-8 yang sah. Jangan simpan inf atau nan.
JadualYaJika 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, Color3TidakSimpanan 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 utama data store
KaedahApa yang dibuatUntuk 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 nil membatalkan 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.

  1. Dalam Explorer, halakan tetikus pada ServerScriptService, klik + dan masukkan ModuleScript. Namakan semula kepada PlayerData dan gantikan kandungannya dengan kod di bawah.
  2. ModuleScript hanya berjalan apabila ada skrip yang memuatkannya (require). Masukkan Script bernama Main ke dalam ServerScriptService dengan baris ini: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Skrip pelayan lain memuatkannya dengan cara yang sama.
  3. Ubah DEFAULTS dan jenis Data mengikut game anda, dengan setiap medan kekal sebagai nombor, string, boolean atau jadual.
Explorer selepas langkah 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript dalam ServerScriptService bernama PlayerData
-- 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

BilaKenapa
Setiap 180 saat semasa pemain berada di pelayanMengehadkan 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:

PanggilanApa 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.LoadedBerlaku 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.

LocalScript dalam 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

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

  1. 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)
  2. Tekan Play. Tetingkap Output (dalam menu Window atau pada tab Script) menunjukkan nama anda dan 100 (pada larian pertama), tanpa amaran Could not load.
  3. Tekan Stop. Menamatkan ujian menutup pelayan, dan modul menyimpan anda sebelum ditutup.
  4. 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.
  5. 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.
  6. 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 berlakuHasilCara mencegah
Pemuatan gagal, tetapi skrip tetap menyimpanNilai lalai menimpa kemajuan sebenar: pemadaman penuhJangan sekali-kali simpan pemain yang pemuatannya gagal
Menyimpan hanya dalam PlayerRemovingPelayan ranap atau ditutup melangkau simpananAutosave ditambah BindToClose yang menunggu simpanannya
Tiada pcall atau tiada cubaan semulaSatu permintaan gagal menghentikan skrip atau menghilangkan simpananpcall dengan beberapa cubaan semula yang dijarakkan
Menyimpan pada setiap perubahanPermintaan beratur; apabila ada 30 dalam baris gilir, yang baharu dibuangSimpan data dalam memori dan simpan mengikut pemasa
Menyimpan sesuatu yang store tidak boleh simpanSimpanan memberi ralat, atau nilai kembali sebagai nilSimpan nombor, string, boolean dan jadual daripadanya
Mengubah bentuk data tanpa migrasiSimpanan lama dimuatkan ke medan yang salahVersi skema dan langkah migrasi
Dua skrip menyimpan kunci yang samaSetiap simpanan menimpa medan yang lainSatu modul memiliki kunci
Dua pelayan memegang pemain yang samaPelayan dengan data lama menyimpan terakhir dan menimpa kemajuan baharuSession 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.

PilihanApa ituApa yang perlu diketahui
Modul dalam panduan iniPemuatan, cache dalam memori, cubaan semula, autosave, simpanan semasa ditutup dan versi skema, tanpa lockCukup pendek untuk dibaca sepenuhnya dan diubah
Contoh Roblox untuk data pemain dan pembelianKod rujukan daripada Roblox dengan session locking, cubaan semula mengikut urutan bagi setiap kunci dan pengendalian resit pembelianRoblox mengatakan ia belum teruji dalam game popular dan tidak patut digunakan sebagaimana adanya tanpa ujian yang meluas
ProfileStoreModul komuniti percuma bersumber terbuka, pengganti ProfileService, dibina di sekitar session locking dan autosaveBukan 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.

Had permintaan lalai bagi setiap pelayan, per minit
Jenis permintaanStore biasaStore tersusun
Baca: GetAsync, bacaan dalam UpdateAsync60 + 40 × pemain60 + 40 × pemain
Tulis: SetAsync, IncrementAsync, tulisan dalam UpdateAsync60 + 40 × pemain30 + 5 × pemain
Senarai: ListKeysAsync, atau GetSortedAsync untuk store tersusun5 + 2 × pemain5 + 2 × pemain
Padam: RemoveAsync60 + 40 × pemain30 + 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 saiz dan daya pemprosesan
HadNilai
Nama store, nama kunci, scope50 aksara setiap satu
Nilai dalam satu kunci4,194,304 aksara dalam bentuk JSON
Bacaan satu kunci daripada semua pelayan25 MB seminit
Tulisan ke satu kunci daripada semua pelayan4 MB seminit, setiap permintaan dibundarkan ke atas kepada KB seterusnya
Permintaan menunggu30 bagi setiap baris gilir; selebihnya gagal dengan ralat 301-306
Storan untuk seluruh game500 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.

Anda tulis

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.

RoCode buat
  • 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

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.

Cuba RoCode dalam permainan anda.

Kredit percuma setiap hari, tanpa kad. Pasang plugin, terangkan ciri yang anda mahu dan semak hasilnya dalam Studio.