Tutorial · Player data

Paano mag-save ng player data sa Roblox Studio gamit ang DataStore

Walang naaalala ang Roblox tungkol sa player sa pagitan ng mga session, maliban kung na-save ito ng isang server script. Sa guide na ito, bubuo ka ng PlayerData module na naglo-load, nag-iimbak sa memory at nagse-save ng data ng bawat player gamit ang DataStoreService, at pagkatapos ay tatalakayin ang testing, ang mga limit, at kung paano nawawala ang naka-save na data.

In-update Nobyembre 20, 202620 minutong basaIsinulat ni

Sa madaling salita

Gamitin ang DataStoreService mula sa isang server Script: i-load ang data ng player gamit ang GetAsync pagpasok niya, itago ito sa isang table habang naglalaro siya, at i-save gamit ang UpdateAsync sa timer, pag-alis niya (PlayerRemoving) at kapag nagsa-shut down ang server (game:BindToClose). Balutin ang bawat call sa pcall at ulitin nang ilang beses ang mga pumalya.

  • Para mag-test sa Studio, i-publish ang place at i-on ang File > Experience Settings > Security > Enable Studio Access to API Services sa isang hiwalay na test game: parehong data ang gamit ng Studio at ng mga live server.
  • Kung hindi na-load ang data ng player, huwag na huwag i-save ang player na iyon. Buburahin ng pag-save ng mga default value ang totoong progress niya.
  • Mag-imbak ng isang table kada player sa ilalim ng isang key, halimbawa User_12345, at mag-save sa timer, hindi sa bawat pagbabago.
  • Para sa trading o mga bayad na item, magdagdag ng session locking para hindi ma-save ng dalawang server ang iisang player.
Sa page na ito
  1. Studio access
  2. Paano gumagana ang DataStore
  3. GetAsync at UpdateAsync
  4. 1. PlayerData module
  5. Paano binuo ang module
  6. 2. Paggamit ng data
  7. 3. Babala
  8. 4. Test sa Studio
  9. Bakit nawawala ang data
  10. Session locking
  11. Mga limit
  12. Bersyon at backup
  13. Common errors
  14. With RoCode
  15. Mga madalas itanong
  16. Mga source at dagdag na babasahin

Bago magsimula: i-on ang Studio access sa isang test copy

Hindi maka-access ng data store ang game na tumatakbo sa Studio hangga't hindi mo ito pinapayagan. May patibong ang pahintulot na ito na binabanggit ng Roblox docs: babasahin at susulatan ng Studio ang mismong mga data store ng live game, kaya ang test na nagre-reset ng coins mo sa Studio ay nagre-reset din ng mga ito sa live game, at ang bug sa test code ay puwedeng sumira sa mga key ng totoong player.

  1. Gumawa ng test copy. I-save ang place sa isang file, buksan ang kopya, piliin ang File > Publish to Roblox As at pindutin ang Create new game. Huwag itong idagdag bilang place sa loob ng live game: iisang data store ang gamit ng lahat ng place ng iisang game.
  2. Sa test copy, buksan ang File > Experience Settings at pumunta sa Security.
  3. I-on ang Enable Studio Access to API Services at pindutin ang Save.

Gumagana lang ang mga data store call sa server Script; ang LocalScript na susubok ay makakakuha ng error, kaya hindi kayang sumulat ng mga client sa naka-save na data. Kapag may button na dapat magbago nito, hihilingin ng client sa server gamit ang RemoteEvent, at ang server ang magpapasya (tingnan ang guide sa RemoteEvents, sa English).

Paano iniimbak ng mga data store ang player data

IlustrasyonAng test mula sa hakbang 4 ng guide, pinabilis: Play, sine-save ng Stop ang session sa data store, nilo-load ito ng sumunod na Play, kaya 200 ang ipinapakita ng Output.

Ang data store ay isang may-pangalang koleksyon ng mga key at value sa mga server ng Roblox, na pinaghahatian ng lahat ng server at lahat ng place ng game mo. Ang DataStoreService:GetDataStore("PlayerData") ay nagbabalik ng isang ganoong store.

Ang mga rekomendasyon ng Roblox ay nauuwi sa patakarang isang store para sa player data, isang key kada player, isang table sa bawat key. Buuin ang key mula sa UserId ng player, halimbawa User_12345, at hindi kailanman mula sa pangalan na puwede niyang palitan. Ang pare-parehong pattern na User_{UserId} ay nagpapahintulot din sa awtomatikong right-to-be-forgotten processing ng Roblox na hanapin ang data ng player, kung ise-set up mo ito.

Ano ang puwedeng i-save sa data store
TypeNase-save?Mga tala
Numbers, strings, booleans, buffersOoDapat valid na UTF-8 ang mga string. Huwag mag-imbak ng inf o nan.
TablesOoKung nase-save din ang lahat ng nasa loob. Ang table na ang mga numeric key ay hindi nagsisimula sa 1 (kaya 0 ang haba nito) ay bumabalik na string na ang mga key na iyon.
Instance, Vector3, CFrame, Color3HindiNag-e-error ang pag-save o nil ang naisusulat. I-save ang pangalan ng item, o ang posisyon bilang tatlong numero.

Bawat request ay isang web call na puwedeng pumalya, tumatagal, at gumagastos ng budget kada minuto. Kaya ang maaasahang save system ay nagbabasa ng data nang isang beses pagpasok ng player, itinatago ito sa server table habang naglalaro siya, at paminsan-minsan ay isinusulat ito pabalik.

GetAsync, SetAsync o UpdateAsync: alin ang gagamitin

Mga pangunahing method ng data store
MethodAno ang ginagawaPara saan
GetAsync(key)Binabasa ang value. Naka-cache ang resulta sa server na ito nang 4 na segundo.Pag-load ng player data
SetAsync(key, value)Pinapatungan ang value nang hindi ito binabasa. Isang write.Bagong key, o value na hindi nakadepende sa luma
UpdateAsync(key, callback)Binabasa ang pinakabagong value, ipinapasa ito sa function mo, at isinusulat ang ibinalik nito. Isang read at isang write.Pag-save ng player data at kahit anong key na puwedeng sulatan ng ilang server
IncrementAsync(key, delta)Nagdadagdag ng integer sa naka-save na integer.Mga counter
RemoveAsync(key)Binubura ang key at ibinabalik ang lumang value. Puwede pa ring i-list at basahin ang mga dating bersyon.Pagbura ng player data

Bulag na nagsusulat ang SetAsync: kung halos sabay na nag-save ng iisang key ang dalawang server, ang huling write ang mananalo, ano man ang laman nito. Binabasa muna ng UpdateAsync ang kasalukuyang value, at kung may ibang server na sumulat sa pagitan, pinapatakbo ulit ng Roblox ang function mo gamit ang bagong value. Inirerekomenda ito ng Roblox tuwing nakadepende ang write sa kasalukuyang value o puwedeng sulatan ng ilang server ang key, at iyon mismo ang player data. May tatlong patakaran ang function:

  • Hindi ito dapat mag-yield: walang task.wait() at walang ibang data store call sa loob.
  • Puwede itong tumakbo nang higit sa isang beses, kaya dapat kalkulahin lang nito ang bagong value at hindi kailanman magbigay ng item o mag-fire ng event.
  • Kinakansela ng pagbabalik ng nil ang write. Ginagamit ito ng module para hindi mapatungan ang data na na-save ng mas bagong bersyon ng game.

Hakbang 1: gawin ang PlayerData module

Ang ModuleScript na ito lang ang code na nakikipag-usap sa data store. Nilo-load nito ang data ng player pagpasok, itinatago sa memory, sine-save kada 180 segundo, pag-alis at kapag nagsa-shut down ang server, at tumatangging i-save ang mga player na hindi na-load ang data.

  1. Sa Explorer, i-hover ang ServerScriptService, pindutin ang + at mag-insert ng ModuleScript. I-rename ito sa PlayerData at palitan ang laman nito ng code sa ibaba.
  2. Tumatakbo lang ang ModuleScript kapag ni-require ito ng isang script. Mag-insert sa ServerScriptService ng Script na pinangalanang Main na may ganitong linya: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Ganito rin ito nire-require ng ibang server script.
  3. Baguhin ang DEFAULTS at ang type na Data para sa game mo, at panatilihing number, string, boolean o table ang bawat field.
Ang Explorer pagkatapos ng hakbang 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript sa ServerScriptService na pinangalanang PlayerData
-- PlayerData: nilo-load ang data ng player pagpasok, itinatago ito sa memory
-- at sine-save sa timer, pag-alis at kapag nagsa-shut down ang server.
-- Binabasa at binabago ito ng ibang server script gamit ang 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 -- itaas kapag nagbago ang hugis ng data, at magdagdag ng hakbang sa migrate()
local AUTOSAVE_SECONDS = 180
-- Sa Studio, sumusuko agad ang pumalyang call, kaya mabilis ang test na walang access sa store
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- dumodoble pagkatapos ng bawat palya: 1, 2, 4

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

-- Ang panimula ng isang bagong-bagong player
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- false kung pumalya ang pag-load: hindi dapat palitan ng default data ang totoong progress
}

-- Tinatawag sa loob ng bawat pcall sa ibaba, kaya ang place na hindi pa naka-publish
-- (walang access sa store) ay naglo-load pa rin ng mga player na may default data
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- mga save na tumatakbo pa, ayon sa key
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Nagpa-fire kasama ang player kapag handa na ang data niya. Kunin ang table gamit ang PlayerData.Get(player):
-- ang table na ipinadala sa BindableEvent ay dumarating bilang kopya, at walang mababago ang pag-edit dito.
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) -- bagong kopya, para hindi kailanman maghati ang mga player sa iisang Inventory table
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Inaangkop ang naka-save na data sa kasalukuyang schema. Nagbabalik ng nil kung hindi ito ligtas gamitin.
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 -- na-save ng mas bagong bersyon ng game: huwag i-load o patungan dito
	end

	-- Isang hakbang kada pagbabago ng schema, mula luma papunta sa bago
	if version < 2 then
		-- Halimbawa: sa version 1, Gold ang pangalan ng currency. Kopyahin lang ito kung walang Coins,
		-- para mapanatili ang value ng lumang data na may Coins na pero walang SchemaVersion.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Idagdag ang mga field na lumabas pagkatapos ng huling save ng player, at palitan ang mga value na mali ang type
	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

-- Pinapatakbo ang store call sa pcall. Kapag pumalya, naghihintay at sumusubok ulit, dinodoble ang
-- paghihintay bawat beses at nagdadagdag ng kaunting random para hindi sabay-sabay mag-retry ang mga server.
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 -- kinakansela ng pagbabalik ng nil ang write
			end
			-- Isinusulat ang buong kasalukuyang table na may tatak na UserId ng player
			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()
		-- Nagsisimula sa random na sandali ng interval, para hindi sabay-sabay mag-save ang mga server
		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

	-- Kung kaaalis lang ng player sa server na ito at bumalik, hintayin munang matapos ang huling save
	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 -- umalis habang naglo-load: walang nagbago, walang ise-save
	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) -- puwede itong basahin ng GUI para balaan ang player
	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 -- pinapahinto ang autosave loop, at walang ginagawa ang pangalawang call
	save(session)
end

-- Ang live na data table ng player, o nil hangga't hindi pa ito na-load. Baguhin lang ito mula sa mga server script.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- True kapag na-load ang data ng player at ise-save ito. I-check bago ang kahit anong benta.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Nagse-save ngayon, nang hindi hinihintay ang timer, para sa mahahalagang sandali gaya ng pagbili.
-- Nagyi-yield at nagbabalik ng true kapag natuloy ang save.
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) -- mga player na pumasok bago unang ma-require ang module na ito
end

game:BindToClose(function()
	-- 30 segundo ang ibinibigay ng server sa mga function na ito, kaya sabay-sabay nating sine-save ang lahat
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Saka hinihintay ang lahat ng save na tumatakbo pa, pati ang mga sinimulan sa PlayerRemoving
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

Kapag live na ang game, huwag baguhin ang STORE_NAME at ang key pattern na User_. Kapag binago ang alinman, ituturo ang module sa mga bakanteng key, at magsisimula ulit ang bawat player sa mga default value.

Paano iniingatan ng module ang data

Mga default value at schema version

Nakakakuha ang bagong player ng bagong kopya ng DEFAULTS. Dapat talagang kopya ito: kung iisang Inventory table ang pinaghahatian ng lahat ng player, lalabas sa lahat ang item na idinagdag sa isa.

Bawat naka-save na table ay may dalang SchemaVersion. Hindi kailangan ng bagong version kapag nagdagdag ng field, dahil pinupunan ng migrate ang mga kulang na field mula sa mga default. Kailangan ito kapag nag-rename o nag-ayos ulit: itaas ang SCHEMA_VERSION at magdagdag ng hakbang, gaya ng halimbawang nagre-rename ng Gold sa Coins (sa bagong game, burahin ito at magsimula sa 1). Ang data na may version na mas mataas kaysa sa server ay galing sa mas bagong release na inilalabas pa, kaya hindi ito ginagalaw ng mga lumang server.

Hindi kailanman sine-save ang pumalyang load

Pinoprotektahan ng patakarang ito laban sa tuluyang pagbura. Kung pumalya ang lahat ng pagsubok na mag-load, naglalaro ang player sa default data, pero false ang canSave, kaya hindi kailanman papatungan ng mga value na ito ang totoong progress niya. Ginagawa ring false ng module ang attribute na DataLoaded, at ginagamit ito ng hakbang 3 para sabihan ang player. Ganito rin hinahawakan ng reference example ng Roblox ang mga pumalyang load at iminumungkahi ito sa halip na mag-kick; kung mas gusto mong mag-kick, tawagin ang player:Kick() na may message sa lugar kung saan nagwa-warn ang module.

Mga retry na humahaba ang pagitan

Binabalot ng withRetries ang bawat call sa pcall. Pagkatapos ng palya, naghihintay ito ng 1, tapos 2, tapos 4 na segundo, bawat beses dagdag ang random na hanggang kalahati ng oras na iyon, at humihinto pagkatapos ng apat na pagsubok (sa Studio, pagkatapos ng isa, para agad tumakbo ang place na walang access sa store). Ikinakalat ng random ang mga retry ng maraming server pagkatapos ng outage, at pinapanatili ng limit ang paghihintay sa mga 10 segundo, pasok sa 30 segundong ibinibigay sa server para mag-shut down. Dahil isinusulat ng bawat save ang buong live table gamit ang UpdateAsync, hindi maibabalik ng late na retry ang lumang data.

Kailan nagse-save ang module

KailanBakit
Kada 180 segundo habang nasa server ang playerNililimitahan ang mawawala kapag nag-crash. Nasa random na sandali ng interval ang unang save, para hindi sabay-sabay mag-save ang mga server. 180 segundo rin ang gamit ng reference example ng Roblox.
Kapag umalis ang player (PlayerRemoving)Ang normal na huling save. Binubura muna ang session, kaya humihinto ang autosave.
Kapag nagsa-shut down ang server (game:BindToClose)Sabay-sabay na sine-save ang lahat ng nasa server pa, at hinihintay ng function ang bawat tumatakbong save. 30 segundo ang ibinibigay dito ng Roblox.
Kapag hiniling, gamit ang PlayerData.SaveNow(player)Pagkatapos ng isang bagay na hindi dapat mawala, gaya ng pagbili.

Kung pumasok ulit ang player sa parehong server habang tumatakbo pa ang huling save niya, hinihintay ng bagong load na matapos ang save na iyon, kaya hindi nito mababasa ang lumang value.

Hakbang 2: basahin at baguhin ang data mula sa ibang script

Lahat ng server script na nagre-require ng module ay gumagamit ng iisang mga table:

CallAno ang ginagawa
PlayerData.Get(player)Ang live na data table ng player, o nil hangga't hindi pa ito na-load. Direktang baguhin ang mga field, halimbawa data.Coins += 10, at isasama ito ng susunod na save.
PlayerData.LoadedNagpa-fire kasama ang player kapag handa na ang data niya, pati pagkatapos ng pumalyang load. Player lang ang ipinapasa, dahil ang table na ipinadala sa BindableEvent ay dumarating bilang kopya.
PlayerData.CanSave(player)false kung pumalya ang load. I-check bago ang kahit anong benta: mawawala ang pagbiling hindi ma-save kapag umalis ang player.
PlayerData.SaveNow(player)Nagse-save agad at nagbabalik ng true kung natuloy. Nagyi-yield.

Ang module lang ang lugar kung saan nakatira ang naka-save na data, at display lang ang leaderstats: buuin ito gaya sa guide sa leaderboard, punan ito mula sa PlayerData.Get(player) sa Loaded handler, at i-update ang dalawa kapag nagbago ang value. Huwag kailanman basahin pabalik ang naka-save na value mula sa leaderstats, at huwag kailanman hayaang mag-save ang pangalawang script ng parehong key.

Ang script na nag-require ng module pagkatapos pumasok ng mga player ay hindi makakatanggap ng Loaded para sa kanila. Ikonekta ang handler, tapos mag-loop pa sa Players:GetPlayers() at asikasuhin ang lahat ng may table na mula sa PlayerData.Get(player).

Papalitan mo ba ang lumang save script, halimbawa mula sa guide sa leaderboard? Nananatili ang mga value nito sa sarili nitong store at key, kaya sisimulan ng module na ito ang lahat sa mga default value. Bago mag-launch, ituro ang STORE_NAME at ang prefix na User_ sa mga luma (itinuturing ng migrate na version 1 ang data na walang SchemaVersion at pinupunan ang mga kulang na field), o ilipat ang mga lumang value, saka burahin ang lumang script.

Hindi kailanman direktang binabago ng mga client ang data na ito. Nagpa-fire ng RemoteEvent ang button ng shop; chine-check ng server ang CanSave, ikinukumpara ang presyo sa Coins ng player, binabago ang table at tinatawag ang SaveNow. Binubuo ng guide sa shop GUI ang ganitong pagbili sa server side.

May tapos na halimbawa ng pagdagdag ng mga field sa guide sa clicker simulator: idinadagdag nito ang PowerLevel at Rebirths sa DEFAULTS at sa type na Data, saka binabago ang mga ito sa table na ibinabalik ng PlayerData.Get. Ibinibigay ng migrate ang mga bagong field sa mga player na may lumang save.

Hakbang 3: sabihan ang player na hindi na-load ang data niya

Dapat malaman ng player na hindi na-load ang data na hindi mase-save ang session na ito, para mag-rejoin siya sa halip na maglaro nang walang saysay. Binabantayan ng LocalScript na ito ang attribute na DataLoaded at nagpapakita ng banner kapag false ito.

LocalScript sa StarterPlayerScripts na pinangalanang 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

-- Isang beses sine-set ng server ang DataLoaded, pagkatapos subukang i-load ang data ng player na ito
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Hakbang 4: i-test ang pag-save sa Studio

Gawin ito sa test copy na naka-on ang Studio access.

  1. Bigyan ang sarili mo ng mase-save. Sa ilalim ng require line sa Main, idagdag: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Pindutin ang Play. Ipapakita ng Output window (sa Window menu o sa Script tab) ang pangalan mo at 100 (sa unang run), nang walang warning na Could not load.
  3. Pindutin ang Stop. Isinasara ng pagtatapos ng test ang server, at sine-save ka ng module bago ito magsara.
  4. Pindutin ulit ang Play. Dapat 200 ang ipakita ng Output, 100 na higit sa nakaraan. Kung parehong numero ulit ang ipinapakita, hindi natuloy ang save: basahin ang mga warning sa itaas nito.
  5. I-test ang landas ng palya. I-off ang Studio access at pindutin ang Play. Pagkatapos ng ilang segundo ng retry, ipapakita ng Output ang Could not load User_... at 100, at lalabas ang banner mula sa hakbang 3. Ihinto ang test, i-on ulit ang access at pindutin ang Play: 300 ang ipapakita ng Output, ang naka-save mong 200 dagdag ang 100, dahil hindi kailanman pinatungan ng pumalyang session ang data mo.
  6. Burahin ang test line mula sa Main.

Bakit nawawala ang player data

Ito ang mga karaniwang paraan kung paano nawawalan ng progress ang isang save system. Sinasara ng module sa code ang unang apat na row at ang row tungkol sa schema; ang iba ay depende sa kung ano at paano ka nag-iimbak, at kailangan ng session locking para sa huli.

Ano ang nangyayariResultaPaano iiwasan
Pumalya ang load, pero nagse-save pa rin ang scriptBinubura ng mga default value ang totoong progress: tuluyang pagburaHuwag kailanman i-save ang player na pumalya ang load
Nagse-save lang sa PlayerRemovingNalalaktawan ang save kapag nag-crash o nag-shut down ang serverAutosave dagdag ang BindToClose na naghihintay sa mga save nito
Walang pcall o walang retryIsang pumalyang request ang nagpapahinto sa script o nagpapawala ng savepcall na may ilang retry na magkakalayo ang oras
Nagse-save sa bawat pagbabagoPumipila ang mga request; kapag 30 na ang nasa pila, itinatapon ang mga bagoItago ang data sa memory at mag-save sa timer
Nagse-save ng hindi kayang iimbak ng storeNag-e-error ang save, o bumabalik na nil ang valueMag-save ng numbers, strings, booleans at mga table ng mga ito
Binago ang hugis ng data nang walang migrationNapupunta sa maling field ang mga lumang saveSchema version at migration step
Dalawang script ang nagse-save ng iisang keyBinubura ng bawat save ang mga field ng isaIsang module ang may-ari ng key
Dalawang server ang may hawak sa iisang playerAng server na may lumang data ang huling nagse-save at binubura ang bagong progressSession locking

Session locking, "lock lost" at ProfileStore

Nakakonekta ang player sa isang server lang sa isang pagkakataon, pero puwedeng tumatakbo pa ang huling save ng lumang server kapag pumasok siya sa bago: mabagal na retry, teleport o mabilis na rejoin. Kung unang mag-load ang bagong server, lumang data ang mapupunta rito, at mananalo ang server na huling magse-save. Binabanggit ng Roblox docs na sa mga game na may trading, karaniwang sanhi ng item duplication ang puwang na ito.

Sinasara ng session locking ang puwang na ito. Kapag nilo-load ng server ang key ng player, sa parehong UpdateAsync call ay isinusulat nito ang lock ID nito sa metadata ng key. Hindi maglo-load o magse-save ng key na iyon ang kahit anong ibang server na makakita ng hindi pa expired na lock na hindi nito inilagay. Nire-refresh ng may-ari ang lock sa bawat autosave at inaalis ito sa huling save; kung huminto ito sa pag-refresh, mag-e-expire ang lock at puwede itong kunin ng ibang server.

Ano ang ibig sabihin ng "lock lost"

Sa system na may session locking, nawalan ng lock ang server kapag ibang server na ang may-ari ng key ng player, dahil nag-expire ang lock o naagaw ito. Puwedeng luma na ang kopya nito, kaya dapat itong huminto sa pag-save ng player na iyon; ang karaniwang tugon: i-kick siya na may message para mag-reconnect. Kung nakita mo ang "lock lost" bilang player, message iyon ng sariling save system ng game na iyon, at ang mga developer lang nito ang makakapagpaliwanag.

Kailangan mo ba ito?

Walang session locking ang module sa guide na ito. Kung walang lock, ito ang totoong pinakamasamang kaso: sa bihirang race, nawawala sa player ang nakuha niya sa lumang server pagkatapos ng huling matagumpay na save nito. Magdagdag ng locking kapag may totoong kapalit sa mga player ang duplication o pagkawala: trading, developer products, bihirang item o madalas na teleport.

OpsyonAno itoDapat malaman
Ang module sa guide na itoLoad, cache sa memory, retry, autosave, save sa shutdown at schema version, walang lockingSapat na maikli para basahin nang buo at baguhin
Halimbawa ng Roblox para sa player data at pagbiliReference code mula sa Roblox na may session locking, mga retry nang sunod-sunod kada key, at paghawak ng purchase receiptSabi ng Roblox, hindi pa ito nasubok sa isang sikat na game at hindi dapat gamitin nang ganoon lang nang walang malawakang testing
ProfileStoreLibreng open source na community module, kahalili ng ProfileService, na binuo sa paligid ng session locking at autosaveHindi galing sa Roblox. Kailangan ng migration ng naka-save nang data para ilipat dito ang kasalukuyang game

Para sa kahit anong third-party module, pinapayo ng Roblox na suriin kung sino ang may-ari nito, kung mina-maintain ito, at kung paano mo maaabot ang data mo nang wala ito. Tinatawag ng parehong docs ang DataStore2 na lumang library na hindi na dapat gamitin ng mga bagong game.

Mga limit ng data store

Ito ang mga limit mula sa Roblox docs noong 30 Setyembre 2026. Nirerebisa ito ng Roblox, kaya tingnan ang page ng error codes at limits (sa English) bago umasa sa eksaktong numero.

Default na request limit para sa bawat server, kada minuto
Uri ng requestStandard data storeOrdered data store
Read: GetAsync, read sa UpdateAsync60 + 40 × players60 + 40 × players
Write: SetAsync, IncrementAsync, write sa UpdateAsync60 + 40 × players30 + 5 × players
List: ListKeysAsync o GetSortedAsync para sa ordered data store5 + 2 × players5 + 2 × players
Remove: RemoveAsync60 + 40 × players30 + 5 × players

Sa 20 player, kayang gumawa ang server ng 860 standard write kada minuto; gumagastos ang autosave ng module na ito ng mga 7 sa mga iyon, dagdag ang isa sa bawat player na umalis. Ang nauubos ng budget ay ang pag-save sa bawat napulot na coin. May pangalawang budget para sa buong game na kahati ang Open Cloud: 300 read kada minuto dagdag ang 40 sa bawat online na player, at 300 write dagdag ang 20 kada player.

Mga limit ng laki at throughput
LimitValue
Pangalan ng store, pangalan ng key, scopeTig-50 character
Value sa iisang key4,194,304 character bilang JSON
Pagbasa ng iisang key mula sa lahat ng server25 MB kada minuto
Pagsulat sa iisang key mula sa lahat ng server4 MB kada minuto, ang bawat request ay ira-round up sa susunod na KB
Mga naghihintay na request30 kada pila; lampas doon, pumapalya ang mga request na may error 301-306
Storage para sa buong game500 MB dagdag ang 1 MB sa bawat user sa buong panahon

Sukatin ang laki ng player data gamit ang #HttpService:JSONEncode(data), at tingnan ang natitirang budget ng live server gamit ang DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Hindi binibilang ang mga GetAsync call na sinagot ng 4-segundong cache. May sariling limit ang Run mode sa Studio, na puwedeng mas mababa, kaya para i-test ang request limits ay pinapayo ng Roblox ang Team Create.

Mga bersyon at backup

Ang standard data store ay nag-iimbak ng history para sa iyo. Ang unang write sa isang key sa bawat oras ng UTC ay sine-save bilang bersyon, at pinapatungan ng mga sumunod na write sa oras na iyon ang isa't isa. Nag-e-expire ang lumang bersyon 30 araw matapos itong palitan ng mas bagong write; hindi kailanman nag-e-expire ang pinakahuli. Walang bersyon ang mga ordered data store.

Para i-rollback ang isang player, buksan ang Data Stores Manager (Creations, ang game mo, Configure > Data Stores Manager), piliin ang key niya, pumili ng mas naunang bersyon at pindutin ang Revert; kailangan dito ng Edit permission. Gawin ito habang offline ang player, kung hindi ay ise-save ng server na may session niya ang kopya nito sa ibabaw ng rollback. Mula sa server script, hinahanap at binabasa ng ListVersionsAsync at GetVersionAsync ang lumang bersyon, na isusulat mo pabalik bilang kasalukuyang value.

Bago mag-publish ng update na nagbabago sa paraan ng pag-save ng data, pinapayo ng Roblox na kumuha ng snapshot gamit ang Open Cloud Snapshot Data Stores API (isa kada araw kada game). Kung wala ito, buburahin ng maling save sa 3:30 UTC ang lahat ng naisulat sa key na iyon mula 3:00, dahil napupunta ito sa parehong bersyon ng oras na iyon.

Mga karaniwang error at solusyon

Lumalabas ang mga error ng data store sa Output window ng Studio, at nagpi-print ang module ng warning na may error text ng Roblox sa bawat pumalyang pagsubok. Ipinapaliwanag ng guide sa mga error ng script kung paano basahin ang Output sa pangkalahatan.

StudioAccessToApisNotAllowed (error 403)

"Can't write to DataStore from Studio because API access is not enabled." I-publish ang place, saka i-on ang Enable Studio Access to API Services sa File > Experience Settings > Security, sa test copy.

DataStore request was added to queue

Mas mabilis magpadala ng request ang server kaysa sa pinapayagan ng budget, o masyadong madalas nitong sinusulatan ang iisang key, kadalasan dahil nagse-save sa bawat pagbabago o sa loop. Kapag 30 na ang request sa pila, pumapalya ang mga bago na may error 301-306. Itago ang data sa memory at mag-save sa timer.

CantStoreValue (error 104), o bumabalik na nil ang field

May laman ang table na hindi kayang i-save ng store, gaya ng Instance, Vector3 o Color3. I-save na lang ang pangalan, ID o simpleng numero, at buuin ulit ang object pag-load.

ValueTooLarge (error 105)

Higit sa 4,194,304 character ng JSON ang laman ng isang key. Sukatin gamit ang #HttpService:JSONEncode(data), tanggalin ang kayang buuin ulit, o hatiin ang data sa ilang permanenteng key.

Walang error, pero hindi nase-save ang data

Hanapin ang warning ng module na Could not load: pagkatapos ng pumalyang load, sinasadya nitong tumangging mag-save. Kung hindi, malamang binago ang value sa LocalScript, na hindi kailanman nakakarating sa server, o may ibang script na nagse-save ng parehong key.

Nare-reset ang data sa bawat rejoin

Nagbabago ang key sa pagitan ng mga session (binuo mula sa player.Name, o binago mo ang STORE_NAME), pumapalya ang load at mga default value ang nakikita mo, o walang nagre-require ng module kaya hindi ito tumatakbo. Tingnan ang Output at siguraduhing nire-require ng Main ang PlayerData.

Buuin ito gamit ang RoCode

Kung ayaw mong buuin ito nang mano-mano, kaya itong gawin ng RoCode mismo sa place na bukas mo. Isa itong independent na AI agent, hindi galing sa Roblox, na gumagana sa pamamagitan ng plugin para sa Roblox Studio: sumusulat ito ng Luau na gumagamit ng DataStoreService gaya ng kahit anong script, at gumagawa ng mga script sa Explorer mo. Hindi nito kailanman mismong ina-access ang mga data store mo, pero sa plugin 3.9 o mas bago, kaya nitong pindutin ang Play para sa maikling playtest, kung saan tumatakbo ang mga script mo gaya ng sa kahit anong test.

Ang tina-type mo

Magdagdag ng saving sa game ko: i-store ang Coins, Level at Inventory sa isang PlayerData module na may autosave at save kapag nagsa-shut down ang server, at ipakita ang Coins sa leaderstats na meron na ako.

Ang ginagawa ng RoCode
  • Puwedeng hanapin ang kasalukuyang leaderstats at DataStore code gamit ang Search Scripts at Read Script, para palawakin ang meron ka sa halip na magdagdag ng pangalawang save script. Sa malaking place, banggitin ang script o folder sa message.
  • Gumagawa ng ModuleScript at ng Script na nagre-require nito gamit ang Create Script, o binabago ang mga dati na gamit ang Edit Script
  • Pinapatakbo ang Check Script sa bawat script na isinulat nito: compile check sa loob ng Studio na may maikling listahan ng warning, hindi type check at hindi test run
  • Ipinapadala ang mga pagbabago nang batch-batch, at bawat batch ay isang undo point sa Studio

Ikaw pa rin ang kailangang mag-on ng Studio Access to API Services sa test copy: hindi kayang baguhin ng RoCode ang setting na iyon. Sa plugin 3.9 o mas bago, binabasa ng maikling playtest nito ang mga error, at sa plugin 3.9.11 o mas bago, kaya nitong kontrolin ang isang test character para suriin na gumagana ang game, pero ang pinili lang nitong suriin ang sinusuri nito, kaya maglaro ka mismo at siguraduhing nase-save at naglo-load ang Coins, Level at Inventory. Kung hindi natuloy ang save sa test mo, kayang basahin ng Check Output ang mga Server line mula sa playtest na pinatakbo mo. Karaniwang idinadagdag ang saving kapag gumagana na ang pangunahing game loop; ipinapakita ng paggawa ng Roblox game gamit ang AI, isang system sa isang pagkakataon ang ayos na ito. Paano kumokonekta ang RoCode sa Studio.

Mga madalas itanong

Paano i-enable ang DataStore sa Roblox Studio?

I-publish ang place, buksan ang File > Experience Settings > Security, i-on ang Enable Studio Access to API Services at pindutin ang Save. Gawin ito sa hiwalay na test game, dahil gagamitin ng Studio ang parehong data store ng mga live server ng game na iyon.

Awtomatiko bang sine-save ng Roblox ang player data?

Hindi. Walang nase-save tungkol sa player pagkatapos ng session maliban kung i-save ito ng server script gamit ang DataStoreService, at kasama rito ang leaderstats.

Alin ang pipiliin: ProfileStore o direktang DataStoreService?

Nakabatay rin sa mga data store ang ProfileStore, kaya ang tanong ay kung gusto mong may ibang sumulat at mag-maintain ng session locking para sa iyo. Para sa trading, mga bayad na item o madalas na teleport, sulit ang locking, mula man sa library o sa reference example ng Roblox. Para sa mas maliit na game, mas madaling basahin at baguhin ang module na tulad nito.

Paano i-reset o burahin ang player data?

Sa Data Stores Manager, hanapin ang key at piliin ang Mark for Deletion, na puwedeng i-undo sa loob ng waiting period, o tawagin ang RemoveAsync para sa key mula sa server script. Gawin ito habang offline ang player, kung hindi ay isusulat ulit ng susunod na save ng server niya ang data. Sa test copy, nagsisimula ulit ang lahat sa zero kapag pinalitan ang STORE_NAME; huwag kailanman gawin ito sa live game.

Mga source at dagdag na babasahin

Paano sinuri ang code: bawat script sa page na ito ay dumaan sa strict Luau type check gamit ang mga definition ng Roblox API (luau-lsp, Nobyembre 20, 2026). Nahuhuli ng type check ang maling pangalan ng API at maling type, pero hindi ang mga mali sa game logic, kaya i-test muna ang lahat sa Studio bago mag-publish.

Subukan ang RoCode sa sarili mong game.

Libreng credits araw-araw, walang card. I-install ang plugin, ilarawan ang feature, at tingnan kung ano ang lumabas sa Studio.