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
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.
- 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.
- Sa test copy, buksan ang File > Experience Settings at pumunta sa Security.
- 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
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.
| Type | Nase-save? | Mga tala |
|---|---|---|
| Numbers, strings, booleans, buffers | Oo | Dapat valid na UTF-8 ang mga string. Huwag mag-imbak ng inf o nan. |
| Tables | Oo | Kung 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, Color3 | Hindi | Nag-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
| Method | Ano ang ginagawa | Para 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
nilang 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.
- Sa Explorer, i-hover ang ServerScriptService, pindutin ang + at mag-insert ng ModuleScript. I-rename ito sa
PlayerDataat palitan ang laman nito ng code sa ibaba. - Tumatakbo lang ang ModuleScript kapag ni-require ito ng isang script. Mag-insert sa ServerScriptService ng Script na pinangalanang
Mainna may ganitong linya:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Ganito rin ito nire-require ng ibang server script. - Baguhin ang
DEFAULTSat ang type naDatapara sa game mo, at panatilihing number, string, boolean o table ang bawat field.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- 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
| Kailan | Bakit |
|---|---|
| Kada 180 segundo habang nasa server ang player | Nililimitahan 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:
| Call | Ano 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.Loaded | Nagpa-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.
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.
- 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) - 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. - Pindutin ang Stop. Isinasara ng pagtatapos ng test ang server, at sine-save ka ng module bago ito magsara.
- 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.
- 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. - 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 nangyayari | Resulta | Paano iiwasan |
|---|---|---|
| Pumalya ang load, pero nagse-save pa rin ang script | Binubura ng mga default value ang totoong progress: tuluyang pagbura | Huwag kailanman i-save ang player na pumalya ang load |
Nagse-save lang sa PlayerRemoving | Nalalaktawan ang save kapag nag-crash o nag-shut down ang server | Autosave dagdag ang BindToClose na naghihintay sa mga save nito |
Walang pcall o walang retry | Isang pumalyang request ang nagpapahinto sa script o nagpapawala ng save | pcall na may ilang retry na magkakalayo ang oras |
| Nagse-save sa bawat pagbabago | Pumipila ang mga request; kapag 30 na ang nasa pila, itinatapon ang mga bago | Itago ang data sa memory at mag-save sa timer |
| Nagse-save ng hindi kayang iimbak ng store | Nag-e-error ang save, o bumabalik na nil ang value | Mag-save ng numbers, strings, booleans at mga table ng mga ito |
| Binago ang hugis ng data nang walang migration | Napupunta sa maling field ang mga lumang save | Schema version at migration step |
| Dalawang script ang nagse-save ng iisang key | Binubura ng bawat save ang mga field ng isa | Isang module ang may-ari ng key |
| Dalawang server ang may hawak sa iisang player | Ang server na may lumang data ang huling nagse-save at binubura ang bagong progress | Session 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.
| Opsyon | Ano ito | Dapat malaman |
|---|---|---|
| Ang module sa guide na ito | Load, cache sa memory, retry, autosave, save sa shutdown at schema version, walang locking | Sapat na maikli para basahin nang buo at baguhin |
| Halimbawa ng Roblox para sa player data at pagbili | Reference code mula sa Roblox na may session locking, mga retry nang sunod-sunod kada key, at paghawak ng purchase receipt | Sabi ng Roblox, hindi pa ito nasubok sa isang sikat na game at hindi dapat gamitin nang ganoon lang nang walang malawakang testing |
| ProfileStore | Libreng open source na community module, kahalili ng ProfileService, na binuo sa paligid ng session locking at autosave | Hindi 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.
| Uri ng request | Standard data store | Ordered data store |
|---|---|---|
Read: GetAsync, read sa UpdateAsync | 60 + 40 × players | 60 + 40 × players |
Write: SetAsync, IncrementAsync, write sa UpdateAsync | 60 + 40 × players | 30 + 5 × players |
List: ListKeysAsync o GetSortedAsync para sa ordered data store | 5 + 2 × players | 5 + 2 × players |
Remove: RemoveAsync | 60 + 40 × players | 30 + 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.
| Limit | Value |
|---|---|
| Pangalan ng store, pangalan ng key, scope | Tig-50 character |
| Value sa iisang key | 4,194,304 character bilang JSON |
| Pagbasa ng iisang key mula sa lahat ng server | 25 MB kada minuto |
| Pagsulat sa iisang key mula sa lahat ng server | 4 MB kada minuto, ang bawat request ay ira-round up sa susunod na KB |
| Mga naghihintay na request | 30 kada pila; lampas doon, pumapalya ang mga request na may error 301-306 |
| Storage para sa buong game | 500 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.
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.
- 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
- Roblox Creator Docs: Data stores (sa English). Studio access, GetAsync, SetAsync, UpdateAsync, set at update
- Roblox Creator Docs: Best practices for data stores (sa English). isang key kada player, data sa memory, mga retry na humahaba ang pagitan, third-party module
- Roblox Creator Docs: Data store error codes and limits (sa English). error codes, request limit ng server at ng game, limit ng laki, throughput at storage
- Roblox Creator Docs: Versioning, listing and caching (sa English). mga bersyon kada oras, snapshot, 4-segundong cache, ano ang puwedeng i-save
- Roblox Creator Docs: Implement player data and purchasing systems (sa English). reference example, session locking, pumalyang load, autosave kada 180 segundo
- Roblox Creator Docs: Data Stores Manager (sa English). pagtingin sa mga key, rollback ng bersyon, pagbura ng data
- Roblox Engine API: DataModel:BindToClose (sa English). 30 segundo para mag-shut down
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.