Tutorial · Spelerdata

Spelerdata opslaan in Roblox Studio met DataStore

Roblox onthoudt niets over een speler tussen sessies als een serverscript het niet heeft opgeslagen. In deze handleiding bouw je een PlayerData-module die de data van elke speler laadt, in het geheugen houdt en opslaat via DataStoreService, en daarna bekijk je het testen, de limieten en hoe opgeslagen data verloren gaat.

Bijgewerkt 20 november 202619 min lezenAuteur:

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
  1. Studio-toegang
  2. Hoe DataStore werkt
  3. GetAsync en UpdateAsync
  4. 1. PlayerData-module
  5. Hoe de module werkt
  6. 2. Werken met de data
  7. 3. Waarschuwing
  8. 4. Testen in Studio
  9. Waarom data verloren gaan
  10. Session locking
  11. Limieten
  12. Versies en back-ups
  13. Common errors
  14. With RoCode
  15. Veelgestelde vragen
  16. Bronnen en verder lezen

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.

  1. 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.
  2. Open in de testkopie File > Experience Settings en ga naar Security.
  3. 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

IllustratieDe test uit stap 4 van deze handleiding, versneld: Play, Stop slaat de sessie op in de data store, opnieuw Play laadt hem, dus Output toont 200.

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.

Wat je in een data store kunt opslaan
TypeWordt opgeslagen?Opmerkingen
Getallen, strings, booleans, buffersJaStrings moeten geldige UTF-8 zijn. Sla geen inf of nan op.
TabellenJaAls 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, Color3NeeOpslaan 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

De belangrijkste methoden van een data store
MethodeWat hij doetWaarvoor
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.
  • nil teruggeven 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.

  1. Beweeg in de Explorer je muis over ServerScriptService, klik op + en voeg een ModuleScript in. Hernoem het naar PlayerData en vervang de inhoud door de code hieronder.
  2. Een ModuleScript draait alleen als een ander script het laadt met require. Voeg in ServerScriptService een Script in met de naam Main en deze regel: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Andere serverscripts laden het op dezelfde manier.
  3. Pas DEFAULTS en het type Data aan voor je game, en houd elk veld een getal, string, boolean of tabel.
Explorer na stap 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript in ServerScriptService met de naam PlayerData
-- 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

WanneerWaarom
Elke 180 seconden, zolang de speler op de server isBeperkt 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:

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

LocalScript in StarterPlayerScripts met de naam 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

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

  1. Geef jezelf iets om op te slaan. Voeg onder de require-regel in Main toe: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. 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.
  3. Klik op Stop. Het einde van de test sluit de server, en de module slaat je op voordat hij sluit.
  4. 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.
  5. 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.
  6. 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 gebeurtGevolgHoe je het voorkomt
Het laden mislukt en het script slaat toch opStandaardwaarden overschrijven de echte voortgang: volledig gewistSla nooit een speler op van wie het laden mislukt is
Alleen opslaan in PlayerRemovingEen crash of afsluiting van de server slaat de opslag overAutosave plus BindToClose die op zijn opslagen wacht
Geen pcall of geen retryEén mislukt verzoek stopt het script of verliest een opslagpcall met een paar retries, gespreid in de tijd
Opslaan bij elke wijzigingVerzoeken komen in een wachtrij; bij 30 in de wachtrij worden nieuwe weggegooidData in het geheugen houden en met een timer opslaan
Iets opslaan wat de data store niet kan bewarenOpslaan geeft een fout, of de waarde komt terug als nilGetallen, strings, booleans en tabellen daarvan opslaan
De vorm van de data veranderen zonder migratieOude opslagen laden in de verkeerde veldenEen schemaversie en een migratiestap
Twee scripts slaan dezelfde sleutel opElke opslag overschrijft de velden van de andereEén module is eigenaar van de sleutel
Twee servers houden dezelfde speler vastDe server met oude data slaat als laatste op en overschrijft nieuwe voortgangSession 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.

OptieWat het isGoed om te weten
De module uit deze handleidingLaden, cache in het geheugen, retries, autosave, opslaan bij afsluiten en schemaversies, zonder lockingKort genoeg om helemaal te lezen en aan te passen
Het Roblox-voorbeeld voor spelerdata en aankopenReferentiecode van Roblox met session locking, retries op volgorde per sleutel en afhandeling van aankoopbewijzenRoblox zegt dat het niet beproefd is in een populaire game en niet zonder uitgebreid testen ongewijzigd gebruikt moet worden
ProfileStoreEen gratis opensource-module van de community, opvolger van ProfileService, gebouwd rond session locking en autosaveNiet 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.

Standaard verzoeklimieten per server, per minuut
Type verzoekGewone data storesOrdered data stores
Lezen: GetAsync, lezen in UpdateAsync60 + 40 × spelers60 + 40 × spelers
Schrijven: SetAsync, IncrementAsync, schrijven in UpdateAsync60 + 40 × spelers30 + 5 × spelers
Lijst: ListKeysAsync of GetSortedAsync voor ordered data stores5 + 2 × spelers5 + 2 × spelers
Verwijderen: RemoveAsync60 + 40 × spelers30 + 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.

Limieten voor grootte en doorvoer
LimietWaarde
Naam van de data store, naam van de sleutel, scopeElk 50 tekens
Waarde in één sleutel4.194.304 tekens als JSON
Eén sleutel lezen vanaf alle servers25 MB per minuut
Naar één sleutel schrijven vanaf alle servers4 MB per minuut, elk verzoek wordt naar boven afgerond op de volgende KB
Wachtende verzoeken30 per wachtrij; daarboven mislukken verzoeken met fouten 301-306
Opslag voor de hele game500 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.

Jij typt

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.

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

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.

Probeer RoCode in je eigen game.

Elke dag gratis credits, geen creditcard nodig. Installeer de plugin, beschrijf een functie en kijk wat er in Studio verschijnt.