In het kort
Gebruik DataStoreService vanuit een server-Script: laad de data van een speler met GetAsync als hij binnenkomt, houd ze in een tabel zolang hij speelt, en sla ze op met UpdateAsync op een timer, bij vertrek (PlayerRemoving) en bij het afsluiten van de server (game:BindToClose). Zet elke aanroep in een pcall en probeer mislukte aanroepen een paar keer opnieuw.
- Om in Studio te testen publiceer je de place en zet je File > Experience Settings > Security > Enable Studio Access to API Services aan in een aparte testgame: Studio gebruikt dezelfde data als de live servers.
- Als de data van een speler niet geladen zijn, sla die speler dan nooit op. Standaardwaarden opslaan overschrijft zijn echte voortgang.
- Bewaar één tabel per speler onder één sleutel, bijvoorbeeld
User_12345, en sla op met een timer, niet bij elke wijziging. - Voor ruilen of betaalde items voeg je session locking toe, zodat twee servers niet dezelfde speler kunnen opslaan.
Op deze pagina
Voordat je begint: zet Studio-toegang aan in een testkopie
Een game die in Studio draait, kan geen data stores gebruiken tot je dat toestaat. Die toestemming heeft een addertje waar de Roblox-documentatie voor waarschuwt: Studio leest en schrijft dan dezelfde data stores als de live game, dus een test die je munten in Studio op nul zet, zet ze ook in de live game op nul, en een fout in testcode kan de sleutels van echte spelers beschadigen.
- Maak een testkopie. Sla de place op als bestand, open de kopie, kies File > Publish to Roblox As en klik op Create new game. Voeg hem niet toe als place binnen je live game: alle places van één game delen dezelfde data stores.
- Open in de testkopie File > Experience Settings en ga naar Security.
- Zet Enable Studio Access to API Services aan en klik op Save.
Data store-aanroepen werken alleen in server-Scripts; een LocalScript dat het probeert, krijgt een fout, dus clients kunnen geen opgeslagen data schrijven. Als een knop ze moet wijzigen, vraagt de client het aan de server via een RemoteEvent, en de server beslist (zie de handleiding over RemoteEvents, in het Engels).
Hoe data stores spelerdata bewaren
Een data store is een benoemde verzameling sleutels en waarden op de servers van Roblox, gedeeld door alle servers en alle places van je game. DataStoreService:GetDataStore("PlayerData") geeft één zo'n data store terug.
De aanbevelingen van Roblox komen neer op de regel één data store voor spelerdata, één sleutel per speler, één tabel in elke sleutel. Bouw de sleutel op uit de UserId van de speler, bijvoorbeeld User_12345, en nooit uit een naam die hij kan veranderen. Het vaste patroon User_{UserId} laat ook de automatische afhandeling van Roblox voor het recht op vergetelheid de data van een speler vinden, als je die instelt.
| Type | Wordt opgeslagen? | Opmerkingen |
|---|---|---|
| Getallen, strings, booleans, buffers | Ja | Strings moeten geldige UTF-8 zijn. Sla geen inf of nan op. |
| Tabellen | Ja | Als alles erin ook opgeslagen kan worden. Een tabel waarvan de numerieke sleutels niet bij 1 beginnen (zodat de lengte 0 is), komt terug met die sleutels als strings. |
Instance, Vector3, CFrame, Color3 | Nee | Opslaan geeft een fout of schrijft nil. Sla de naam van het item op, of de positie als drie getallen. |
Elk verzoek is een webaanroep die kan mislukken, tijd kost en een budget per minuut verbruikt. Daarom lezen betrouwbare opslagsystemen de data één keer als de speler binnenkomt, houden ze in een servertabel zolang hij speelt, en schrijven ze af en toe terug.
GetAsync, SetAsync of UpdateAsync: wat kies je
| Methode | Wat hij doet | Waarvoor |
|---|---|---|
GetAsync(key) | Leest een waarde. Het resultaat wordt 4 seconden op deze server gecachet. | Spelerdata laden |
SetAsync(key, value) | Overschrijft een waarde zonder hem te lezen. Eén schrijfactie. | Een nieuwe sleutel, of een waarde die niet van de oude afhangt |
UpdateAsync(key, callback) | Leest de laatste waarde, geeft die aan je functie en schrijft wat die teruggeeft. Eén leesactie en één schrijfactie. | Spelerdata opslaan, en elke sleutel waar meerdere servers naar kunnen schrijven |
IncrementAsync(key, delta) | Telt een geheel getal op bij een opgeslagen geheel getal. | Tellers |
RemoveAsync(key) | Verwijdert een sleutel en geeft de oude waarde terug. Eerdere versies kun je nog steeds opsommen en lezen. | Spelerdata verwijderen |
SetAsync schrijft blind: als twee servers bijna tegelijk dezelfde sleutel opslaan, wint de laatste schrijfactie, wat er ook in staat. UpdateAsync leest eerst de huidige waarde, en als een andere server er tussendoor naar schrijft, voert Roblox je functie opnieuw uit met de nieuwe waarde. Roblox raadt het aan wanneer een schrijfactie van de huidige waarde afhangt of meerdere servers de sleutel kunnen schrijven, en dat is precies het geval bij spelerdata. De functie heeft drie regels:
- Hij mag niet yielden: geen
task.wait()en geen andere data store-aanroepen erin. - Hij kan meer dan één keer draaien, dus hij moet alleen de nieuwe waarde berekenen en nooit items uitdelen of events afvuren.
nilteruggeven annuleert de schrijfactie. De module gebruikt dat om geen data te overschrijven die door een nieuwere versie van de game zijn opgeslagen.
Stap 1: maak de PlayerData-module
Dit ModuleScript is de enige code die met de data store praat. Het laadt de data van een speler als hij binnenkomt, houdt ze in het geheugen, slaat ze elke 180 seconden op, bij vertrek en bij het afsluiten van de server, en weigert spelers op te slaan van wie de data niet geladen zijn.
- Beweeg in de Explorer je muis over ServerScriptService, klik op + en voeg een ModuleScript in. Hernoem het naar
PlayerDataen vervang de inhoud door de code hieronder. - Een ModuleScript draait alleen als een ander script het laadt met require. Voeg in ServerScriptService een Script in met de naam
Mainen deze regel:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Andere serverscripts laden het op dezelfde manier. - Pas
DEFAULTSen het typeDataaan voor je game, en houd elk veld een getal, string, boolean of tabel.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: laadt de data van een speler als hij binnenkomt, houdt ze in het geheugen
-- en slaat ze op met een timer, bij vertrek en bij het afsluiten van de server.
-- Andere serverscripts lezen en wijzigen ze via 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 -- verhoog dit als de vorm van de data verandert, en voeg een stap toe in migrate()
local AUTOSAVE_SECONDS = 180
-- In Studio geeft een mislukte aanroep meteen op, zodat een test zonder data store-toegang snel gaat
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- verdubbelt na elke mislukking: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- Waarmee een gloednieuwe speler begint
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false als het laden mislukt is: standaardwaarden mogen de echte voortgang niet vervangen
}
-- Wordt binnen elke pcall hieronder aangeroepen, zodat een nog niet gepubliceerde place
-- (zonder data store-toegang) spelers toch met standaardwaarden laadt
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- opslagen die nog lopen, per sleutel
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Vuurt met de speler zodra zijn data klaar zijn. Haal de tabel op met PlayerData.Get(player):
-- een tabel die via een BindableEvent wordt verstuurd, komt als kopie aan, en die wijzigen verandert niets.
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) -- een verse kopie, zodat spelers nooit één Inventory-tabel delen
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Brengt opgeslagen data naar het huidige schema. Geeft nil terug als ze niet veilig te gebruiken zijn.
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 -- opgeslagen door een nieuwere versie van de game: hier niet laden en niet overschrijven
end
-- Eén stap per schemawijziging, van oud naar nieuw
if version < 2 then
-- Voorbeeld: in versie 1 heette de valuta Gold. Kopieer die alleen als Coins ontbreekt,
-- zodat oude data die al Coins hebben maar geen SchemaVersion, hun waarde houden.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Voeg velden toe die na de laatste opslag van de speler zijn bijgekomen, en vervang waarden van het verkeerde 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
-- Voert een data store-aanroep uit in een pcall. Bij een mislukking wacht hij en probeert opnieuw, elke keer met
-- dubbel zo lang wachten plus wat willekeur, zodat servers niet allemaal tegelijk opnieuw proberen.
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 -- nil teruggeven annuleert de schrijfactie
end
-- Schrijf de hele huidige tabel, gemarkeerd met de UserId van de speler
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()
-- Begin op een willekeurig moment in het interval, zodat servers niet allemaal tegelijk opslaan
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
-- Als de speler net deze server verliet en terugkwam, laat dan eerst de laatste opslag klaar zijn
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 -- vertrokken tijdens het laden: er is niets veranderd, niets om op te slaan
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) -- een GUI kan dit lezen en de speler waarschuwen
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 -- stopt de autosave-lus, en een tweede aanroep doet niets
save(session)
end
-- De live datatabel van de speler, of nil zolang die niet geladen is. Wijzig hem alleen vanuit serverscripts.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True als de data van de speler geladen zijn en opgeslagen zullen worden. Controleer dit voor elke verkoop.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Slaat nu op zonder op de timer te wachten, voor belangrijke momenten zoals een aankoop.
-- Yieldt en geeft true terug als de opslag gelukt is.
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) -- spelers die binnenkwamen voordat deze module voor het eerst geladen werd
end
game:BindToClose(function()
-- De server geeft deze functies 30 seconden, dus we slaan iedereen tegelijk op
for player in sessions do
task.spawn(endSession, player)
end
-- Wacht daarna op alle opslagen die nog lopen, ook die in PlayerRemoving gestart zijn
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Verander STORE_NAME en het sleutelpatroon User_ niet meer zodra je game uit is. Als je een van beide verandert, kijkt de module naar lege sleutels en begint elke speler opnieuw met de standaardwaarden.
Hoe de module je data beschermt
Standaardwaarden en schemaversie
Een nieuwe speler krijgt een verse kopie van DEFAULTS. Het moet echt een kopie zijn: als alle spelers één Inventory-tabel deelden, zou een item dat bij één speler wordt toegevoegd, bij iedereen verschijnen.
Elke opgeslagen tabel draagt een SchemaVersion. Een veld toevoegen vraagt geen nieuwe versie, omdat migrate ontbrekende velden aanvult uit de standaardwaarden. Hernoemen of herstructureren wel: verhoog SCHEMA_VERSION en voeg een stap toe, zoals in het voorbeeld dat Gold hernoemt naar Coins (in een nieuwe game haal je dat weg en begin je bij 1). Data met een hogere versie dan die van de server komen van een nieuwere release die nog wordt uitgerold, dus oudere servers laten ze met rust.
Een mislukte lading wordt nooit opgeslagen
Deze regel beschermt tegen volledig wissen. Als alle laadpogingen mislukken, speelt de speler met standaardwaarden, maar is canSave false, dus die waarden overschrijven nooit zijn echte voortgang. De module zet ook het attribuut DataLoaded op false, en stap 3 gebruikt dat om de speler te waarschuwen. Het referentievoorbeeld van Roblox gaat op dezelfde manier met mislukte ladingen om en stelt dit voor in plaats van een kick; als je liever kickt, roep je player:Kick() met een bericht aan op de plek waar de module de waarschuwing geeft.
Retries met oplopende pauze
withRetries zet elke aanroep in een pcall. Na een mislukking wacht hij 1, dan 2, dan 4 seconden, elke keer plus willekeurig tot de helft van die tijd, en stopt hij na vier pogingen (in Studio na één, zodat een place zonder toegang tot de data store meteen start). De willekeur spreidt de retries van veel servers na een storing, en de limiet houdt het wachten binnen ongeveer 10 seconden, binnen de 30 seconden die een server krijgt om af te sluiten. Omdat elke opslag de hele live tabel via UpdateAsync schrijft, kan een retry die te laat klaar is geen oude data terugzetten.
Wanneer de module opslaat
| Wanneer | Waarom |
|---|---|
| Elke 180 seconden, zolang de speler op de server is | Beperkt het verlies bij een crash. De eerste opslag valt op een willekeurig moment in het interval, zodat servers niet allemaal tegelijk opslaan. Het referentievoorbeeld van Roblox gebruikt ook 180 seconden. |
Als de speler vertrekt (PlayerRemoving) | De gewone laatste opslag. De sessie wordt eerst verwijderd, dus de autosave stopt. |
Als de server afsluit (game:BindToClose) | Iedereen die nog op de server is, wordt tegelijk opgeslagen, en de functie wacht op elke opslag die nog loopt. Roblox geeft haar 30 seconden. |
Op verzoek, met PlayerData.SaveNow(player) | Na iets wat niet verloren mag gaan, bijvoorbeeld een aankoop. |
Als een speler opnieuw op dezelfde server komt terwijl zijn laatste opslag nog loopt, wacht de nieuwe lading tot die opslag klaar is, dus kan hij geen oude waarde lezen.
Stap 2: lees en wijzig de data vanuit andere scripts
Alle serverscripts die de module laden, werken met dezelfde tabellen:
| Aanroep | Wat hij doet |
|---|---|
PlayerData.Get(player) | De live datatabel van de speler, of nil zolang die niet geladen is. Wijzig velden direct, bijvoorbeeld data.Coins += 10, en de volgende opslag neemt het mee. |
PlayerData.Loaded | Vuurt met de speler zodra zijn data klaar zijn, ook na een mislukte lading. Geeft alleen de speler door, omdat een tabel die via een BindableEvent wordt verstuurd, als kopie aankomt. |
PlayerData.CanSave(player) | false als het laden mislukt is. Controleer dit voor elke verkoop: een aankoop die niet opgeslagen kan worden, verdwijnt als de speler vertrekt. |
PlayerData.SaveNow(player) | Slaat meteen op en geeft true terug als het gelukt is. Yieldt. |
De module is de enige plek waar de opgeslagen data leven, en leaderstats is alleen weergave: bouw die zoals in de handleiding over het leaderboard, vul hem vanuit PlayerData.Get(player) in de Loaded-handler en werk beide bij als een waarde verandert. Lees opgeslagen waarden nooit terug uit leaderstats en laat nooit een tweede script dezelfde sleutel opslaan.
Een script dat de module laadt nadat spelers al binnen zijn, mist voor hen Loaded. Koppel de handler, loop daarna ook door Players:GetPlayers() en verwerk iedereen voor wie PlayerData.Get(player) al een tabel teruggeeft.
Vervang je een oud opslagscript, bijvoorbeeld dat uit de handleiding over het leaderboard? De waarden daarvan blijven in zijn eigen data store en sleutel, dus deze module begint iedereen met de standaardwaarden. Richt vóór de lancering STORE_NAME en het voorvoegsel User_ op de oude (migrate behandelt data zonder SchemaVersion als versie 1 en vult ontbrekende velden aan), of zet de oude waarden over en verwijder daarna het oude script.
Clients wijzigen deze data nooit direct. Een winkelknop vuurt een RemoteEvent af; de server controleert CanSave, vergelijkt de prijs met de Coins van de speler, wijzigt de tabel en roept SaveNow aan. De handleiding over een winkel-GUI bouwt zo'n aankoop aan de serverkant.
Een kant-en-klaar voorbeeld van velden toevoegen staat in de handleiding over een clicker-simulator: die voegt PowerLevel en Rebirths toe aan DEFAULTS en het type Data, en wijzigt ze daarna in de tabel die PlayerData.Get teruggeeft. migrate geeft de nieuwe velden aan spelers met oude opslagen.
Stap 3: laat de speler weten dat zijn data niet geladen zijn
Een speler van wie de data niet geladen zijn, moet weten dat deze sessie niet wordt opgeslagen, zodat hij opnieuw kan joinen in plaats van voor niets te spelen. Dit LocalScript let op het attribuut DataLoaded en toont een banner als het false is.
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
-- De server zet DataLoaded één keer, na de poging om de data van deze speler te laden
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Stap 4: test het opslaan in Studio
Doe dit in de testkopie met Studio-toegang aan.
- Geef jezelf iets om op te slaan. Voeg onder de require-regel in
Maintoe:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Klik op Play. Het Output-venster (in het menu Window of op het tabblad Script) toont je naam en 100 (bij de eerste keer), zonder de waarschuwing
Could not load. - Klik op Stop. Het einde van de test sluit de server, en de module slaat je op voordat hij sluit.
- Klik opnieuw op Play. Output moet 200 tonen, 100 meer dan de vorige keer. Toont hij weer hetzelfde getal, dan is het opslaan mislukt: lees de waarschuwingen erboven.
- Test het foutpad. Zet Studio-toegang uit en klik op Play. Na een paar seconden retries toont Output
Could not load User_...en 100, en verschijnt de banner uit stap 3. Stop de test, zet de toegang weer aan en klik op Play: Output toont 300, je opgeslagen 200 plus 100, omdat de mislukte sessie je data nooit heeft overschreven. - Haal de testregel weg uit
Main.
Waarom spelerdata verloren gaan
Dit zijn de gebruikelijke manieren waarop een opslagsysteem voortgang kwijtraakt. De module dekt in code de eerste vier rijen en de rij over het schema af; de rest hangt af van wat je opslaat en hoe, en voor de laatste is session locking nodig.
| Wat er gebeurt | Gevolg | Hoe je het voorkomt |
|---|---|---|
| Het laden mislukt en het script slaat toch op | Standaardwaarden overschrijven de echte voortgang: volledig gewist | Sla nooit een speler op van wie het laden mislukt is |
Alleen opslaan in PlayerRemoving | Een crash of afsluiting van de server slaat de opslag over | Autosave plus BindToClose die op zijn opslagen wacht |
Geen pcall of geen retry | Eén mislukt verzoek stopt het script of verliest een opslag | pcall met een paar retries, gespreid in de tijd |
| Opslaan bij elke wijziging | Verzoeken komen in een wachtrij; bij 30 in de wachtrij worden nieuwe weggegooid | Data in het geheugen houden en met een timer opslaan |
| Iets opslaan wat de data store niet kan bewaren | Opslaan geeft een fout, of de waarde komt terug als nil | Getallen, strings, booleans en tabellen daarvan opslaan |
| De vorm van de data veranderen zonder migratie | Oude opslagen laden in de verkeerde velden | Een schemaversie en een migratiestap |
| Twee scripts slaan dezelfde sleutel op | Elke opslag overschrijft de velden van de andere | Eén module is eigenaar van de sleutel |
| Twee servers houden dezelfde speler vast | De server met oude data slaat als laatste op en overschrijft nieuwe voortgang | Session locking |
Session locking, "lock lost" en ProfileStore
Een speler is met één server tegelijk verbonden, maar de laatste opslag van de oude server kan nog lopen als hij op een nieuwe binnenkomt: een trage retry, een teleport of snel opnieuw joinen. Als de nieuwe server de data eerst laadt, heeft hij oude data, en wint de server die als laatste opslaat. De Roblox-documentatie merkt op dat dit gat in games met ruilen een veelvoorkomende oorzaak is van gedupliceerde items.
Session locking dicht dit gat. Als een server de sleutel van een speler laadt, schrijft hij in dezelfde UpdateAsync-aanroep zijn lock-ID in de metadata van de sleutel. Elke andere server die een niet-verlopen lock vindt die hij niet zelf heeft gezet, laadt en bewaart deze sleutel niet. De eigenaar vernieuwt de lock bij elke autosave en geeft hem vrij bij de laatste opslag; als hij hem niet meer vernieuwt, verloopt de lock en kan een andere server hem overnemen.
Wat "lock lost" betekent
In een systeem met session locking heeft een server de lock verloren als een andere server nu eigenaar is van de sleutel van de speler, omdat de lock verlopen is of overgenomen werd. Zijn kopie kan verouderd zijn, dus hij moet stoppen met het opslaan van die speler; de gebruikelijke reactie is hem kicken met een bericht dat hij opnieuw moet verbinden. Zie je "lock lost" als speler, dan is dat een bericht van het eigen opslagsysteem van die game, en alleen de makers ervan kunnen het uitleggen.
Heb je het nodig?
De module uit deze handleiding gebruikt geen session locking. Zonder lock is het echte slechtste geval: in een zeldzame race verliest een speler wat hij op de oude server verdiende na de laatste geslaagde opslag daar. Voeg locking toe als duplicatie of verlies spelers iets echts kost: ruilen, developer products, zeldzame items of veel teleports.
| Optie | Wat het is | Goed om te weten |
|---|---|---|
| De module uit deze handleiding | Laden, cache in het geheugen, retries, autosave, opslaan bij afsluiten en schemaversies, zonder locking | Kort genoeg om helemaal te lezen en aan te passen |
| Het Roblox-voorbeeld voor spelerdata en aankopen | Referentiecode van Roblox met session locking, retries op volgorde per sleutel en afhandeling van aankoopbewijzen | Roblox zegt dat het niet beproefd is in een populaire game en niet zonder uitgebreid testen ongewijzigd gebruikt moet worden |
| ProfileStore | Een gratis opensource-module van de community, opvolger van ProfileService, gebouwd rond session locking en autosave | Niet van Roblox. Een bestaande game erop overzetten vraagt een migratie van de al opgeslagen data |
Voor elke module van derden raadt Roblox aan te controleren wie de eigenaar is, of hij onderhouden wordt en hoe je zonder hem bij je data komt. Dezelfde documentatie noemt DataStore2 een verouderde bibliotheek die nieuwe games beter niet gebruiken.
Limieten van data stores
Dit zijn de limieten uit de Roblox-documentatie per 30 september 2026. Roblox herziet ze, dus controleer de pagina met foutcodes en limieten (in het Engels) voordat je op een exact getal rekent.
| Type verzoek | Gewone data stores | Ordered data stores |
|---|---|---|
Lezen: GetAsync, lezen in UpdateAsync | 60 + 40 × spelers | 60 + 40 × spelers |
Schrijven: SetAsync, IncrementAsync, schrijven in UpdateAsync | 60 + 40 × spelers | 30 + 5 × spelers |
Lijst: ListKeysAsync of GetSortedAsync voor ordered data stores | 5 + 2 × spelers | 5 + 2 × spelers |
Verwijderen: RemoveAsync | 60 + 40 × spelers | 30 + 5 × spelers |
Bij 20 spelers kan een server 860 gewone schrijfacties per minuut doen; de autosave van deze module gebruikt er ongeveer 7 van, plus één voor elke speler die vertrekt. Opslaan bij elke opgepakte munt maakt het budget op. Een tweede budget geldt voor de hele game en wordt gedeeld met Open Cloud: 300 leesacties per minuut plus 40 per online speler, en 300 schrijfacties plus 20 per speler.
| Limiet | Waarde |
|---|---|
| Naam van de data store, naam van de sleutel, scope | Elk 50 tekens |
| Waarde in één sleutel | 4.194.304 tekens als JSON |
| Eén sleutel lezen vanaf alle servers | 25 MB per minuut |
| Naar één sleutel schrijven vanaf alle servers | 4 MB per minuut, elk verzoek wordt naar boven afgerond op de volgende KB |
| Wachtende verzoeken | 30 per wachtrij; daarboven mislukken verzoeken met fouten 301-306 |
| Opslag voor de hele game | 500 MB plus 1 MB voor elke gebruiker ooit |
Meet de grootte van de spelerdata met #HttpService:JSONEncode(data), en bekijk het resterende budget van een live server met DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). GetAsync-aanroepen die door de cache van 4 seconden beantwoord zijn, tellen niet mee. De Run-modus in Studio heeft eigen, mogelijk lagere limieten, dus voor het testen van verzoeklimieten raadt Roblox Team Create aan.
Versies en back-ups
Gewone data stores bewaren de geschiedenis voor je. De eerste schrijfactie naar een sleutel in elk uur UTC wordt bewaard als versie, en latere schrijfacties in dat uur overschrijven elkaar. Een oude versie verloopt 30 dagen nadat een nieuwere schrijfactie hem verving; de laatste verloopt nooit. Ordered data stores bewaren geen versies.
Om één speler terug te zetten open je de Data Stores Manager (Creations, je game, Configure > Data Stores Manager), kies je zijn sleutel, kies je een eerdere versie en klik je op Revert; daarvoor heb je het recht Edit nodig. Doe dit terwijl de speler offline is, anders slaat de server met zijn sessie zijn kopie op over het terugzetten heen. Vanuit een serverscript vinden en lezen ListVersionsAsync en GetVersionAsync een oude versie, die je daarna terugschrijft als huidige waarde.
Voordat je een update publiceert die verandert hoe data worden opgeslagen, raadt Roblox aan een snapshot te maken met de Open Cloud Snapshot Data Stores API (één per dag per game). Zonder snapshot overschrijft een foute opslag om 3:30 UTC alles wat sinds 3:00 naar die sleutel geschreven is, omdat die in dezelfde uurversie terechtkomt.
Veelvoorkomende fouten en oplossingen
Data store-fouten verschijnen in het Output-venster van Studio, en de module geeft bij elke mislukte poging een waarschuwing met de fouttekst van Roblox. De handleiding over scriptfouten legt uit hoe je Output überhaupt leest.
StudioAccessToApisNotAllowed (fout 403)
"Can't write to DataStore from Studio because API access is not enabled." Publiceer de place en zet daarna Enable Studio Access to API Services aan in File > Experience Settings > Security, in een testkopie.
DataStore request was added to queue
De server stuurt verzoeken sneller dan het budget toestaat, of schrijft te vaak naar één sleutel, meestal door opslaan bij elke wijziging of in een lus. Als er 30 verzoeken in de wachtrij staan, mislukken nieuwe met fouten 301-306. Houd de data in het geheugen en sla op met een timer.
CantStoreValue (fout 104), of een veld komt terug als nil
De tabel bevat iets wat een data store niet kan opslaan, zoals een Instance, Vector3 of Color3. Sla in plaats daarvan een naam, ID of gewone getallen op en bouw het object weer op bij het laden.
ValueTooLarge (fout 105)
Eén sleutel bevat meer dan 4.194.304 tekens JSON. Meet het met #HttpService:JSONEncode(data), haal weg wat je opnieuw kunt opbouwen, of verdeel de data over meerdere vaste sleutels.
Geen fouten, maar de data worden niet opgeslagen
Zoek de waarschuwing Could not load van de module: na een mislukte lading weigert hij met opzet op te slaan. Anders is de waarde waarschijnlijk in een LocalScript gewijzigd, wat de server nooit bereikt, of slaat een ander script dezelfde sleutel op.
De data worden bij elke nieuwe join gereset
De sleutel verandert tussen sessies (opgebouwd uit player.Name, of je hebt STORE_NAME veranderd), het laden mislukt en je ziet de standaardwaarden, of niemand laadt de module met require, zodat hij helemaal niet draait. Controleer Output en of Main PlayerData laadt.
Bouw dit met RoCode
Als je dit niet met de hand wilt bouwen, kan RoCode het direct in de place doen die je open hebt. Het is een onafhankelijke AI-agent, niet van Roblox, die werkt via een plugin voor Roblox Studio: hij schrijft Luau dat DataStoreService gebruikt zoals elk script, en maakt de scripts in je Explorer. Zelf benadert hij je data stores nooit, maar met plugin 3.9 of nieuwer kan hij op Play drukken voor een korte playtest, waarin je scripts draaien zoals in elke test.
Voeg opslaan toe aan mijn game: bewaar Coins, Level en Inventory in een PlayerData-module met autosave en opslaan bij het afsluiten van de server, en toon Coins in de leaderstats die ik al heb.
- Kan met Search Scripts en Read Script zoeken naar bestaande leaderstats en DataStore-code, zodat hij uitbreidt wat je hebt in plaats van een tweede opslagscript toe te voegen. Noem in een grote place het script of de map in je bericht.
- Maakt het ModuleScript en het Script dat het laadt met Create Script, of wijzigt bestaande met Edit Script
- Draait Check Script voor elk script dat hij schrijft: een compileercontrole in Studio met een korte lijst waarschuwingen, geen typecontrole en geen testrun
- Stuurt wijzigingen in batches, en elke batch is een ongedaan-maakpunt (undo) in Studio
Studio Access to API Services in de testkopie aanzetten moet je nog steeds zelf doen: RoCode kan die instelling niet wijzigen. Met plugin 3.9 of nieuwer leest zijn korte playtest de fouten, en met plugin 3.9.11 of nieuwer kan hij een testpersonage besturen om te controleren of de game werkt, maar hij controleert alleen wat hij zelf besloot te controleren, dus speel zelf en zorg dat Coins, Level en Inventory opgeslagen en geladen worden. Als het opslaan in jouw test mislukte, kan Check Output de Server-regels lezen van de playtest die jij draaide. Opslaan voeg je meestal toe als de kern van de gameloop al werkt; een Roblox-game maken met AI, één systeem tegelijk laat die volgorde zien. Hoe RoCode met Studio verbindt.
Veelgestelde vragen
Hoe zet je DataStore aan in Roblox Studio?
Publiceer de place, open File > Experience Settings > Security, zet Enable Studio Access to API Services aan en klik op Save. Doe dit in een aparte testgame, omdat Studio dan dezelfde data stores gebruikt als de live servers van die game.
Slaat Roblox spelerdata automatisch op?
Nee. Niets over een speler blijft na de sessie bewaard als een serverscript het niet opslaat via DataStoreService, ook leaderstats niet.
Wat kies je: ProfileStore of DataStoreService direct?
ProfileStore is ook gebouwd op data stores, dus de vraag is of je wilt dat session locking voor je geschreven en onderhouden wordt. Voor ruilen, betaalde items of veel teleports is locking het waard, uit een bibliotheek of uit het referentievoorbeeld van Roblox. Voor een kleinere game is een module als deze makkelijker te lezen en aan te passen.
Hoe reset of verwijder je de data van een speler?
Zoek in de Data Stores Manager de sleutel en kies Mark for Deletion, wat je tijdens de wachtperiode ongedaan kunt maken, of roep RemoveAsync aan voor de sleutel vanuit een serverscript. Doe dit terwijl de speler offline is, anders schrijft de volgende opslag van zijn server de data terug. In een testkopie laat het wijzigen van STORE_NAME iedereen opnieuw beginnen; doe dit nooit in een live game.
Bronnen en verder lezen
- Roblox Creator Docs: Data stores (in het Engels). Studio-toegang, GetAsync, SetAsync, UpdateAsync, set en update
- Roblox Creator Docs: Best practices for data stores (in het Engels). één sleutel per speler, data in het geheugen, retries met oplopende pauze, modules van derden
- Roblox Creator Docs: Data store error codes and limits (in het Engels). foutcodes, verzoeklimieten per server en per game, limieten voor grootte, doorvoer en opslag
- Roblox Creator Docs: Versioning, listing and caching (in het Engels). versies per uur, snapshots, cache van 4 seconden, wat je kunt opslaan
- Roblox Creator Docs: Implement player data and purchasing systems (in het Engels). referentievoorbeeld, session locking, mislukte ladingen, autosave elke 180 seconden
- Roblox Creator Docs: Data Stores Manager (in het Engels). sleutels bekijken, versies terugzetten, data verwijderen
- Roblox Engine API: DataModel:BindToClose (in het Engels). 30 seconden om af te sluiten
Hoe de code is gecontroleerd: elk script op deze pagina doorloopt een strikte Luau-typecontrole met de Roblox API-definities (luau-lsp, 20 november 2026). De typecontrole vangt fouten in API-namen en verkeerde types op, maar geen fouten in de gamelogica, dus test alles in Studio voordat je publiceert.